openstack/nova
Code Issues Proposed changes

docs: Revamp the security groups guide

Browse Source 
I did not have a clear understanding of when a security group would or
would not be applied to a port and reading the documentation did not
help. Massively expand the security groups document, adding a couple of
important notes along the way as well as references to the nova-specific
security group operations. The document is moved from the admin guide to
the user guide (with redirects) since these are not admin-only
operations by default.

Change-Id: I212bc99112aad2f1e3057befca381a26d702be2e
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
This commit is contained in:
Stephen Finucane
2023-12-12 14:27:00 +00:00
parent da1c40dae9
commit cef74cbd10
6 changed files with 343 additions and 238 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
doc/source/_extra/.htaccess
View File

@@ -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/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/([^/]+)/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/([^/]+)/contributor/api-2.html$ /nova/$1/contributor/api.html
redirectmatch 301 ^/nova/([^/]+)/admin/security-groups.html /nova/$1/user/security-groups.html

1
doc/source/admin/index.rst
View File

@@ -160,7 +160,6 @@ log management and live migration of instances.
metadata-service metadata-service
unified-limits unified-limits
networking networking
security-groups
security security
vendordata vendordata
notifications notifications

237
doc/source/admin/security-groups.rst
View File

@@ -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 </admin/archives/adv-features.html#security-groups>`.
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.

1
doc/source/user/index.rst
View File

@@ -18,6 +18,7 @@ End user guide
:maxdepth: 1 :maxdepth: 1
availability-zones availability-zones
security-groups
launch-instances launch-instances
server-groups server-groups
metadata metadata

340
doc/source/user/security-groups.rst Normal file
View File

@@ -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
</admin/intro-os-networking.html#security-groups>`. 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 <description> ... <name>
.. 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 <protocol> --dst-port <port-range> \
--remote-ip <ip-address> \
<group>
.. important::
The ``<port-range>`` 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 <protocol> --dst-port <port-range> \
--remote-group <remote-group> \
<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 <group>
Likewise, you can inspect an individual security group or security group rule.
For example:
.. code-block:: console
$ openstack security group show <group>
$ openstack security group rule show <group> <rule>
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 <group>
Alternatively, you can delete individual rules from an existing group. For
example:
.. code-block:: console
$ openstack security group rule show <group> <rule>
.. 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 ... <name>
It is possible to specify different security groups when creating a new port.
For example:
.. code-block:: console
$ openstack port create --security-group <group> ... <name>
.. 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 <group> ... <port>
$ openstack port unset --security-group <group> ... <port>
It is also possible to remove all security groups from a port. For example:
.. code-block:: console
$ openstack port set --no-security-group <port>
.. 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
</admin/config-auto-allocation.html>`") 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 <group> ... <name>
.. 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 <server> <group>
$ openstack server remove security group <server> <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.

1
doc/test/redirect-tests.txt
View File

@@ -87,3 +87,4 @@
/nova/latest/admin/manage-users.html 301 /nova/latest/admin/architecture.html /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/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/contributor/api-2.html 301 /nova/latest/contributor/api.html
/nova/latest/admin/security-groups.html 301 /nova/latest/user/security-groups.html