diff --git a/doc/source/_extra/.htaccess b/doc/source/_extra/.htaccess index 97056cd8e77d..62904edd2a24 100644 --- a/doc/source/_extra/.htaccess +++ b/doc/source/_extra/.htaccess @@ -86,3 +86,4 @@ redirectmatch 301 ^/nova/([^/]+)/admin/port_with_resource_request.html$ /nova/$1 redirectmatch 301 ^/nova/([^/]+)/admin/manage-users.html$ /nova/$1/admin/architecture.html redirectmatch 301 ^/nova/([^/]+)/admin/mitigation-for-Intel-MDS-security-flaws.html /nova/$1/admin/cpu-models.html redirectmatch 301 ^/nova/([^/]+)/contributor/api-2.html$ /nova/$1/contributor/api.html +redirectmatch 301 ^/nova/([^/]+)/admin/security-groups.html /nova/$1/user/security-groups.html diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 79c6e9a21c67..b4252f852695 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -160,7 +160,6 @@ log management and live migration of instances. metadata-service unified-limits networking - security-groups security vendordata notifications diff --git a/doc/source/admin/security-groups.rst b/doc/source/admin/security-groups.rst deleted file mode 100644 index 4419111fe757..000000000000 --- a/doc/source/admin/security-groups.rst +++ /dev/null @@ -1,237 +0,0 @@ -======================= -Manage project security -======================= - -Security groups are sets of IP filter rules that are applied to all project -instances, which define networking access to the instance. Group rules are -project specific; project members can edit the default rules for their group -and add new rule sets. - -All projects have a ``default`` security group which is applied to any instance -that has no other defined security group. Unless you change the default, this -security group denies all incoming traffic and allows only outgoing traffic to -your instance. - -Security groups (and their quota) are managed by :neutron-doc:`Neutron, the -networking service `. - -Working with security groups -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -From the command-line you can get a list of security groups for the project, -using the :command:`openstack` commands. - -List and view current security groups -------------------------------------- - -#. Ensure your system variables are set for the user and project for which you - are checking security group rules. For example: - - .. code-block:: console - - export OS_USERNAME=demo00 - export OS_TENANT_NAME=tenant01 - -#. Output security groups, as follows: - - .. code-block:: console - - $ openstack security group list - +--------------------------------------+---------+-------------+ - | Id | Name | Description | - +--------------------------------------+---------+-------------+ - | 73580272-d8fa-4927-bd55-c85e43bc4877 | default | default | - | 6777138a-deb7-4f10-8236-6400e7aff5b0 | open | all ports | - +--------------------------------------+---------+-------------+ - -#. View the details of a group, as follows: - - .. code-block:: console - - $ openstack security group rule list GROUPNAME - - For example: - - .. code-block:: console - - $ openstack security group rule list open - +--------------------------------------+-------------+-----------+-----------------+-----------------------+ - | ID | IP Protocol | IP Range | Port Range | Remote Security Group | - +--------------------------------------+-------------+-----------+-----------------+-----------------------+ - | 353d0611-3f67-4848-8222-a92adbdb5d3a | udp | 0.0.0.0/0 | 1:65535 | None | - | 63536865-e5b6-4df1-bac5-ca6d97d8f54d | tcp | 0.0.0.0/0 | 1:65535 | None | - +--------------------------------------+-------------+-----------+-----------------+-----------------------+ - - These rules are allow type rules as the default is deny. The first column is - the IP protocol (one of ICMP, TCP, or UDP). The second and third columns - specify the affected port range. The third column specifies the IP range in - CIDR format. This example shows the full port range for all protocols - allowed from all IPs. - -Create a security group ------------------------ - -When adding a new security group, you should pick a descriptive but brief name. -This name shows up in brief descriptions of the instances that use it where the -longer description field often does not. For example, seeing that an instance -is using security group "http" is much easier to understand than "bobs\_group" -or "secgrp1". - -#. Ensure your system variables are set for the user and project for which you - are creating security group rules. - -#. Add the new security group, as follows: - - .. code-block:: console - - $ openstack security group create GroupName --description Description - - For example: - - .. code-block:: console - - $ openstack security group create global_http --description "Allows Web traffic anywhere on the Internet." - +-----------------+--------------------------------------------------------------------------------------------------------------------------+ - | Field | Value | - +-----------------+--------------------------------------------------------------------------------------------------------------------------+ - | created_at | 2016-11-03T13:50:53Z | - | description | Allows Web traffic anywhere on the Internet. | - | headers | | - | id | c0b92b20-4575-432a-b4a9-eaf2ad53f696 | - | name | global_http | - | project_id | 5669caad86a04256994cdf755df4d3c1 | - | project_id | 5669caad86a04256994cdf755df4d3c1 | - | revision_number | 1 | - | rules | created_at='2016-11-03T13:50:53Z', direction='egress', ethertype='IPv4', id='4d8cec94-e0ee-4c20-9f56-8fb67c21e4df', | - | | project_id='5669caad86a04256994cdf755df4d3c1', revision_number='1', updated_at='2016-11-03T13:50:53Z' | - | | created_at='2016-11-03T13:50:53Z', direction='egress', ethertype='IPv6', id='31be2ad1-be14-4aef-9492-ecebede2cf12', | - | | project_id='5669caad86a04256994cdf755df4d3c1', revision_number='1', updated_at='2016-11-03T13:50:53Z' | - | updated_at | 2016-11-03T13:50:53Z | - +-----------------+--------------------------------------------------------------------------------------------------------------------------+ - -#. Add a new group rule, as follows: - - .. code-block:: console - - $ openstack security group rule create SEC_GROUP_NAME \ - --protocol PROTOCOL --dst-port FROM_PORT:TO_PORT --remote-ip CIDR - - The arguments are positional, and the ``from-port`` and ``to-port`` - arguments specify the local port range connections are allowed to access, - not the source and destination ports of the connection. For example: - - .. code-block:: console - - $ openstack security group rule create global_http \ - --protocol tcp --dst-port 80:80 --remote-ip 0.0.0.0/0 - +-------------------+--------------------------------------+ - | Field | Value | - +-------------------+--------------------------------------+ - | created_at | 2016-11-06T14:02:00Z | - | description | | - | direction | ingress | - | ethertype | IPv4 | - | headers | | - | id | 2ba06233-d5c8-43eb-93a9-8eaa94bc9eb5 | - | port_range_max | 80 | - | port_range_min | 80 | - | project_id | 5669caad86a04256994cdf755df4d3c1 | - | project_id | 5669caad86a04256994cdf755df4d3c1 | - | protocol | tcp | - | remote_group_id | None | - | remote_ip_prefix | 0.0.0.0/0 | - | revision_number | 1 | - | security_group_id | c0b92b20-4575-432a-b4a9-eaf2ad53f696 | - | updated_at | 2016-11-06T14:02:00Z | - +-------------------+--------------------------------------+ - - You can create complex rule sets by creating additional rules. For example, - if you want to pass both HTTP and HTTPS traffic, run: - - .. code-block:: console - - $ openstack security group rule create global_http \ - --protocol tcp --dst-port 443:443 --remote-ip 0.0.0.0/0 - +-------------------+--------------------------------------+ - | Field | Value | - +-------------------+--------------------------------------+ - | created_at | 2016-11-06T14:09:20Z | - | description | | - | direction | ingress | - | ethertype | IPv4 | - | headers | | - | id | 821c3ef6-9b21-426b-be5b-c8a94c2a839c | - | port_range_max | 443 | - | port_range_min | 443 | - | project_id | 5669caad86a04256994cdf755df4d3c1 | - | project_id | 5669caad86a04256994cdf755df4d3c1 | - | protocol | tcp | - | remote_group_id | None | - | remote_ip_prefix | 0.0.0.0/0 | - | revision_number | 1 | - | security_group_id | c0b92b20-4575-432a-b4a9-eaf2ad53f696 | - | updated_at | 2016-11-06T14:09:20Z | - +-------------------+--------------------------------------+ - - Despite only outputting the newly added rule, this operation is additive - (both rules are created and enforced). - -#. View all rules for the new security group, as follows: - - .. code-block:: console - - $ openstack security group rule list global_http - +--------------------------------------+-------------+-----------+-----------------+-----------------------+ - | ID | IP Protocol | IP Range | Port Range | Remote Security Group | - +--------------------------------------+-------------+-----------+-----------------+-----------------------+ - | 353d0611-3f67-4848-8222-a92adbdb5d3a | tcp | 0.0.0.0/0 | 80:80 | None | - | 63536865-e5b6-4df1-bac5-ca6d97d8f54d | tcp | 0.0.0.0/0 | 443:443 | None | - +--------------------------------------+-------------+-----------+-----------------+-----------------------+ - -Delete a security group ------------------------ - -#. Ensure your system variables are set for the user and project for which you - are deleting a security group. - -#. Delete the new security group, as follows: - - .. code-block:: console - - $ openstack security group delete GROUPNAME - - For example: - - .. code-block:: console - - $ openstack security group delete global_http - -Create security group rules for a cluster of instances ------------------------------------------------------- - -Source Groups are a special, dynamic way of defining the CIDR of allowed -sources. The user specifies a Source Group (Security Group name), and all the -user's other Instances using the specified Source Group are selected -dynamically. This alleviates the need for individual rules to allow each new -member of the cluster. - -#. Make sure to set the system variables for the user and project for which you - are creating a security group rule. - -#. Add a source group, as follows: - - .. code-block:: console - - $ openstack security group rule create secGroupName \ - --remote-group source-group --protocol ip-protocol \ - --dst-port from-port:to-port - - For example: - - .. code-block:: console - - $ openstack security group rule create cluster \ - --remote-group global_http --protocol tcp --dst-port 22:22 - - The ``cluster`` rule allows SSH access from any other instance that uses the - ``global_http`` group. diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index 104da8f070a3..e90e7d155185 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -18,6 +18,7 @@ End user guide :maxdepth: 1 availability-zones + security-groups launch-instances server-groups metadata diff --git a/doc/source/user/security-groups.rst b/doc/source/user/security-groups.rst new file mode 100644 index 000000000000..0f48055fc311 --- /dev/null +++ b/doc/source/user/security-groups.rst @@ -0,0 +1,340 @@ +=============== +Security Groups +=============== + +Security groups are sets of IP filter rules that are applied to all project +servers, which define networking access to the instance. Group rules are +project specific; project members can edit the default rules for their group +and add new rule sets. + +All projects have a ``default`` security group which is applied to any port +that has no other defined security group. Unless you change the default, this +security group denies all incoming traffic and allows only outgoing traffic to +your instance. + +It's important to note early on that security groups and their quota are +resources of :neutron-doc:`the networking service, Neutron +`. The are modelled as an +attribute of ports rather than servers. With this said, Nova provides utility +APIs that allow users to add and remove security groups from all ports attached +to a server. In addition, it is possible to specify security groups to +configure for newly created ports when creating a new server, and to retrieve +the combined set of security groups for all ports attached to a server. + +.. note:: + + Nova previously provided its own security group APIs. These were proxy APIs + for Neutron APIs and have been deprecated since microversion 2.36. + + +Usage +----- + +Security group-related operations can be broken down into three categories: +operations on security groups and security group rules themselves, operations +on ports, and operations on servers. + +.. rubric:: Security group and security group rule operations + +By default, security groups can be created by any project member. For example: + +.. code-block:: console + + $ openstack security group create --description ... + +.. tip:: + + When adding a new security group, you should pick a descriptive but brief + name. This name shows up in brief descriptions of the servers that use it + where the longer description field often does not. For example, seeing that + an server is using security group ``http`` is much easier to understand + than ``bobs_group`` or ``secgrp1``. + +Security groups are really only containers for rules. Security group rules +define the actual IP filter rules that will be applied. Security groups deny +everything by default, so rules indicated what is allowed. A security group +rule has a couple of attribute: an IP protocol (one of ICMP, TCP, or UDP), a +destination port or port range, and a remote IP range (in CIDR format). You +create security group rules by specifying these attributes and the security +group to which the rules should be added. For example: + +.. code-block:: console + + $ openstack security group rule create \ + --protocol --dst-port \ + --remote-ip \ + + +.. important:: + + The ```` argument takes the form of ``port`` or + ``from-port:to-port``. This specifies the range of local ports that + connections are allowed to access, **not** the source and destination ports + of the connection. + +Alternatively, rather than specifying a remote IP range, we can specify a +remote security group. A remote group will allow requests with the specified +protocol(s) and port(s) from any server with said port. If you create a +security group rule with remote group ``foo`` and apply the security group to +server ``bar``, ``bar`` will be able to receive matching traffic from any other +server with security group ``foo``. Security group rules with remote security +groups are created in much the same way as security group rules with remote +IPs. For example: + +.. code-block:: console + + $ openstack security group rule create \ + --protocol --dst-port \ + --remote-group \ + + +Once created, both security groups and security group rules can be listed. For +example: + +.. code-block:: console + + $ openstack security group list + $ openstack security group rule list + +Likewise, you can inspect an individual security group or security group rule. +For example: + +.. code-block:: console + + $ openstack security group show + $ openstack security group rule show + +Finally, you can delete security groups. This will delete both the security +group and associated security group rules. For example: + +.. code-block:: console + + $ openstack security group delete + +Alternatively, you can delete individual rules from an existing group. For +example: + +.. code-block:: console + + $ openstack security group rule show + +.. rubric:: Port operations + +Security groups are an attribute of ports. By default, Neutron will assign the +``default`` security group to all newly created ports. It is possible to +disable this behavior. For example: + +.. code-block:: console + + $ openstack port create --no-security-group ... + +It is possible to specify different security groups when creating a new port. +For example: + +.. code-block:: console + + $ openstack port create --security-group ... + +.. note:: + + If you specify a security group when creating the port, the ``default`` + security group **will not** be added to the port. If you wish to add the + ``default`` security group, you will need to specify this also. + +Additional security groups can also be added or removed from existing ports. +For example: + +.. code-block:: console + + $ openstack port set --security-group ... + $ openstack port unset --security-group ... + +It is also possible to remove all security groups from a port. For example: + +.. code-block:: console + + $ openstack port set --no-security-group + +.. rubric:: Server operations + +It is possible to manipulate and configure security groups on an server-wide +basis. When you create a new server, networks can be either automatically +allocated (a feature known as ":neutron-doc:`Get me a network +`") or manually configured. In both cases, +attaching a network to server results in the creation of a port. It is possible +to specify one or more security groups to assign to these ports. For example: + +.. code-block:: console + + $ openstack server create --security-group ... + +.. note:: + + These security groups will only apply to automatically created ports. They + will not apply to any pre-created ports attached to the server at boot. + +Once a server has been created, it is possible to add or remove a security +group from all ports attached to the server. For example: + +.. code-block:: console + + $ openstack server add security group + $ openstack server remove security group + +It is also possible to view the security groups associated with a server. For +example: + +.. code-block:: console + + $ openstack server show -f value -c security_groups + +.. important:: + + As security groups are an attribute of ports rather than servers, this + value is the combined set of security groups assigned to all ports. + Different ports may have different sets of security groups. You can inspect + the port with ``openstack port show`` to see the exact security groups + assigned to an individual port. + + +Example +------- + +Let's look through a worked example of creating security groups for a +deployment of 3 web server hosts and 2 database hosts. First, we'll configure +the security group that will allow HTTP traffic to the web server hosts. + +.. code-block:: console + + $ openstack security group create \ + --description "Allows Web traffic anywhere on the Internet." \ + web + +-----------------+--------------------------------------------------------------------------------------------------------------------------+ + | Field | Value | + +-----------------+--------------------------------------------------------------------------------------------------------------------------+ + | created_at | 2016-11-03T13:50:53Z | + | description | Allows Web traffic anywhere on the Internet. | + | headers | | + | id | c0b92b20-4575-432a-b4a9-eaf2ad53f696 | + | name | web | + | project_id | 5669caad86a04256994cdf755df4d3c1 | + | project_id | 5669caad86a04256994cdf755df4d3c1 | + | revision_number | 1 | + | rules | created_at='2016-11-03T13:50:53Z', direction='egress', ethertype='IPv4', id='4d8cec94-e0ee-4c20-9f56-8fb67c21e4df', | + | | project_id='5669caad86a04256994cdf755df4d3c1', revision_number='1', updated_at='2016-11-03T13:50:53Z' | + | | created_at='2016-11-03T13:50:53Z', direction='egress', ethertype='IPv6', id='31be2ad1-be14-4aef-9492-ecebede2cf12', | + | | project_id='5669caad86a04256994cdf755df4d3c1', revision_number='1', updated_at='2016-11-03T13:50:53Z' | + | updated_at | 2016-11-03T13:50:53Z | + +-----------------+--------------------------------------------------------------------------------------------------------------------------+ + +Once created, we can add a new group rule to allow ingress HTTP traffic on port +80: + +.. code-block:: console + + $ openstack security group rule create \ + --protocol tcp --dst-port 80:80 --remote-ip 0.0.0.0/0 \ + web + +-------------------+--------------------------------------+ + | Field | Value | + +-------------------+--------------------------------------+ + | created_at | 2016-11-06T14:02:00Z | + | description | | + | direction | ingress | + | ethertype | IPv4 | + | headers | | + | id | 2ba06233-d5c8-43eb-93a9-8eaa94bc9eb5 | + | port_range_max | 80 | + | port_range_min | 80 | + | project_id | 5669caad86a04256994cdf755df4d3c1 | + | project_id | 5669caad86a04256994cdf755df4d3c1 | + | protocol | tcp | + | remote_group_id | None | + | remote_ip_prefix | 0.0.0.0/0 | + | revision_number | 1 | + | security_group_id | c0b92b20-4575-432a-b4a9-eaf2ad53f696 | + | updated_at | 2016-11-06T14:02:00Z | + +-------------------+--------------------------------------+ + +You can create complex rule sets by creating additional rules. In this instance +we want to pass both HTTP and HTTPS traffic so we'll add an additional rule: + +.. code-block:: console + + $ openstack security group rule create \ + --protocol tcp --dst-port 443:443 --remote-ip 0.0.0.0/0 \ + web + +-------------------+--------------------------------------+ + | Field | Value | + +-------------------+--------------------------------------+ + | created_at | 2016-11-06T14:09:20Z | + | description | | + | direction | ingress | + | ethertype | IPv4 | + | headers | | + | id | 821c3ef6-9b21-426b-be5b-c8a94c2a839c | + | port_range_max | 443 | + | port_range_min | 443 | + | project_id | 5669caad86a04256994cdf755df4d3c1 | + | project_id | 5669caad86a04256994cdf755df4d3c1 | + | protocol | tcp | + | remote_group_id | None | + | remote_ip_prefix | 0.0.0.0/0 | + | revision_number | 1 | + | security_group_id | c0b92b20-4575-432a-b4a9-eaf2ad53f696 | + | updated_at | 2016-11-06T14:09:20Z | + +-------------------+--------------------------------------+ + +.. note:: + + Despite only outputting the newly added rule, this operation is additive + (both rules are created and enforced). + +That's one security group wrapped up. Next, the database hosts. These are +running MySQL and we would like to both restrict traffic to the relevant port +(``3306`` in this case) **and** to restrict ingress traffic to requests from +the web server hosts. While we could specify a CIDR for the IP addresses of the +web servers, a preferred solution is to configure a source group. This will +allow us to dynamically add and remove web server hosts with the ``web`` +security group applied without needing to modify the security group for the +database hosts. Let's create the security group and the necessary rule: + +.. code-block:: console + + $ openstack security group create database + $ openstack security group rule create \ + --protocol tcp --dst-port 3306 --remote-group web \ + database + +The ``database`` rule will now allows access to MySQL's default port from any +server that uses the ``web`` group. + +Now that we've created the security group and rules, let's list them to verify +everything: + +.. code-block:: console + + $ openstack security group list + +--------------------------------------+----------+-------------+ + | Id | Name | Description | + +--------------------------------------+----------+-------------+ + | 73580272-d8fa-4927-bd55-c85e43bc4877 | default | default | + | c0b92b20-4575-432a-b4a9-eaf2ad53f696 | web | web server | + | 40e1e336-e207-494f-a3ec-a3c222336b22 | database | database | + +--------------------------------------+----------+-------------+ + +We can also inspect the rules for the security group. Let's look at the ``web`` +security group: + +.. code-block:: console + + $ openstack security group rule list web + +--------------------------------------+-------------+-----------+-----------------+-----------------------+ + | ID | IP Protocol | IP Range | Port Range | Remote Security Group | + +--------------------------------------+-------------+-----------+-----------------+-----------------------+ + | 2ba06233-d5c8-43eb-93a9-8eaa94bc9eb5 | tcp | 0.0.0.0/0 | 80:80 | None | + | 821c3ef6-9b21-426b-be5b-c8a94c2a839c | tcp | 0.0.0.0/0 | 443:443 | None | + +--------------------------------------+-------------+-----------+-----------------+-----------------------+ + +Assuming everything looks correct, you can now use these security groups when +creating your new servers. diff --git a/doc/test/redirect-tests.txt b/doc/test/redirect-tests.txt index 2142ffbe94de..6c28e790422b 100644 --- a/doc/test/redirect-tests.txt +++ b/doc/test/redirect-tests.txt @@ -87,3 +87,4 @@ /nova/latest/admin/manage-users.html 301 /nova/latest/admin/architecture.html /nova/latest/admin/mitigation-for-Intel-MDS-security-flaws.html 301 /nova/latest/admin/cpu-models.html /nova/latest/contributor/api-2.html 301 /nova/latest/contributor/api.html +/nova/latest/admin/security-groups.html 301 /nova/latest/user/security-groups.html