openstack/neutron
Code Issues Proposed changes

[doc] Follow-up logging service for firewall_group

Browse Source 
This patch updates the networking guide to include 'firewall_group'
as a new resource-type in 'Neutron Packet Logging Framework'

Change-Id: I94d779fcabc64417d4d561c659270501c0651a66
Co-Authored-By: Nguyen Phuong An <AnNP@vn.fujitsu.com>
Partial-Bug: #1720727
This commit is contained in:
Kim Bao Long 2018-07-13 17:23:21 +07:00
parent 8f27c2a165
commit e82a17527d
2 changed files with 323 additions and 244 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

567
doc/source/admin/config-logging.rst
View File

@ -1,244 +1,323 @@
.. _config-logging: .. _config-logging:
=========================== ================================
Logging for security groups Neutron Packet Logging Framework
=========================== ================================
Logging is designed as a service plug-in that captures events for Packet logging service is designed as a Neutron plug-in that captures network
relevant resources (for example, security groups or firewalls) when they occur. packets for relevant resources (e.g. security group or firewall group) when the
registered events occur.
Supported logging resource types .. image:: figures/logging-framework.png
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :width: 100%
:alt: Packet Logging Framework
As of the Queens release, the ``security_group`` resource type is supported.
Supported loggable resource types
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Configuration
~~~~~~~~~~~~~ From Rocky release, both of ``security_group`` and ``firewall_group`` are
supported as resource types in Neutron packet logging framework.
To enable the service, follow the steps below.
#. On Neutron server node: Service Configuration
~~~~~~~~~~~~~~~~~~~~~
#. Add the Logging service to the ``service_plugins`` setting in
``/etc/neutron/neutron.conf``. For example: To enable the logging service, follow the below steps.
.. code-block:: none #. On Neutron controller node, add ``log`` to ``service_plugins`` setting in
``/etc/neutron/neutron.conf`` file. For example:
service_plugins = router,metering,log
.. code-block:: none
#. Add the Logging extension to the ``extensions`` setting in
``/etc/neutron/plugins/ml2/ml2_conf.ini``. For example: service_plugins = router,metering,log
.. code-block:: ini #. To enable logging service for ``security_group`` in Layer 2, add ``log`` to
option ``extensions`` in section ``[agent]`` in ``/etc/neutron/plugins/ml2/ml2_conf.ini``
[agent] for controller node and in ``/etc/neutron/plugins/ml2/openvswitch_agent.ini``
extensions = log for compute/network nodes. For example:
#. On compute/network nodes: .. code-block:: ini
#. In ``/etc/neutron/plugins/ml2/openvswitch_agent.ini``, add ``log`` [agent]
to the ``extensions`` setting in the ``[agent]`` section. For example: extensions = log
.. code-block:: ini #. To enable logging service for ``firewall_group`` in Layer 3, add
``fwaas_v2_log`` to option ``extensions`` in section ``[AGENT]`` in
[agent] ``/etc/neutron/l3_agent.ini`` for network nodes. For example:
extensions = log
.. code-block:: ini
#. In ``/etc/neutron/plugins/ml2/openvswitch_agent.ini``, add configuration
options for logging feature in the ``[network_log]`` section. For example: [AGENT]
extensions = fwaas_v2,fwaas_v2_log
.. code-block:: ini
#. On compute/network nodes, add configuration for logging service to
[network_log] ``[network_log]`` in ``/etc/neutron/plugins/ml2/openvswitch_agent.ini`` as
rate_limit = 100 shown bellow:
burst_limit = 25
#local_output_log_base = <None> .. code-block:: ini
In which, ``rate_limit`` is used to configure the maximum number of packets [network_log]
to be logged per second (packets per second). When a high rate triggers rate_limit = 100
``rate_limit``, logging queues packets to be logged. ``burst_limit`` is used burst_limit = 25
to configure the maximum of queued packets. And logged data can be stored #local_output_log_base = <None>
anywhere by using ``local_output_log_base``.
In which, ``rate_limit`` is used to configure the maximum number of packets
.. note:: to be logged per second (packets per second). When a high rate triggers
``rate_limit``, logging queues packets to be logged. ``burst_limit`` is
- Logging currently works with ``openvswitch`` firewall driver only. used to configure the maximum of queued packets. And logged packets can be
- It requires at least 100 for ``rate_limit`` and at least 25 for ``burst_limit``. stored anywhere by using ``local_output_log_base``.
- If ``rate_limit`` is unset, logging will log unlimited.
- If we don't specify ``local_output_log_base``, logged data will be stored .. note::
in system journal like ``/var/log/syslog``.
- It requires at least ``100`` for ``rate_limit`` and at least ``25``
Trusted projects policy.json configuration for ``burst_limit``.
------------------------------------------ - If ``rate_limit`` is unset, logging will log unlimited.
- If we don't specify ``local_output_log_base``, logged packets will be
With the default ``/etc/neutron/policy.json``, administrators must stored in system journal like ``/var/log/syslog`` by default.
set up resource logging on behalf of the cloud projects.
Trusted projects policy.json configuration
If projects are trusted to administer their own resource logging in your cloud, ----------------------------------------------
neutron's file ``policy.json`` can be modified to allow this.
With the default ``/etc/neutron/policy.json``, administrators must set up
Modify ``/etc/neutron/policy.json`` policy entries as follows: resource logging on behalf of the cloud projects.
.. code-block:: none If projects are trusted to administer their own loggable resources in their
cloud, neutron's policy file ``policy.json`` can be modified to allow this.
"get_loggable_resources": "rule:regular_user",
"create_log": "rule:regular_user", Modify ``/etc/neutron/policy.json`` entries as follows:
"update_log": "rule:regular_user",
"delete_log": "rule:regular_user", .. code-block:: none
"get_logs": "rule:regular_user",
"get_log": "rule:regular_user", "get_loggable_resources": "rule:regular_user",
"create_log": "rule:regular_user",
Operator workflow "get_log": "rule:regular_user",
~~~~~~~~~~~~~~~~~ "get_logs": "rule:regular_user",
"update_log": "rule:regular_user",
#. Confirm logging resources are supported: "delete_log": "rule:regular_user",
.. code-block:: console Service workflow for Operator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$ openstack network loggable resources list
+-----------------+ #. To check the loggable resources that are supported by framework:
| Supported types |
+-----------------+ .. code-block:: console
| security_group |
+-----------------+ $ openstack network loggable resources list
+-----------------+
#. Create a logging resource with an appropriate resource type: | Supported types |
+-----------------+
.. code-block:: console | security_group |
| firewall_group |
$ openstack network log create --resource-type security_group \ +-----------------+
--description "Collecting all security events in project demo" \
--enable --event ALL Log_Created .. note::
+-----------------+------------------------------------------------+
| Field | Value | - In VM ports, logging for ``security_group`` in currently works with
+-----------------+------------------------------------------------+ ``openvswitch`` firewall driver only. ``linuxbridge`` is under
| Description | Collecting all security events in project demo | development.
| Enabled | True | - Logging for ``firewall_group`` works on internal router ports only. VM
| Event | ALL | ports would be supported in the future.
| ID | 8085c3e6-0fa2-4954-b5ce-ff6207931b6d |
| Name | Log_Created | #. Log creation:
| Project | 02568bd62b414221956f15dbe9527d16 |
| Resource | None | * Create a logging resource with an appropriate resource type
| Target | None |
| Type | security_group | .. code-block:: console
| created_at | 2017-07-05T02:56:43Z |
| revision_number | 0 | $ openstack network log create --resource-type security_group \
| tenant_id | 02568bd62b414221956f15dbe9527d16 | --description "Collecting all security events" \
| updated_at | 2017-07-05T02:56:43Z | --event ALL Log_Created
+-----------------+------------------------------------------------+ +-----------------+------------------------------------------------+
| Field | Value |
.. note:: +-----------------+------------------------------------------------+
| Description | Collecting all security events |
The ``Enabled`` field is set to ``True`` by default. If enabled, | Enabled | True |
log information is written to the destination if configured in | Event | ALL |
``local_output_log_base`` or system journal like ``/var/log/syslog``. | ID | 8085c3e6-0fa2-4954-b5ce-ff6207931b6d |
| Name | Log_Created |
| Project | 02568bd62b414221956f15dbe9527d16 |
Enable/Disable log | Resource | None |
------------------ | Target | None |
| Type | security_group |
We can enable or disable logging objects at runtime. It means that it will | created_at | 2017-07-05T02:56:43Z |
apply to all attached ports with the logging object immediately. | revision_number | 0 |
| tenant_id | 02568bd62b414221956f15dbe9527d16 |
For example: | updated_at | 2017-07-05T02:56:43Z |
+-----------------+------------------------------------------------+
.. code-block:: console
.. warning::
$ openstack network log set --disable Log_Created
$ openstack network log show Log_Created In the case of ``--resource`` and ``--target`` are not specified from the
+-----------------+------------------------------------------------+ request, these arguments will be assigned to ``ALL`` by default. Hence,
| Field | Value | there is an enormous range of log events will be created.
+-----------------+------------------------------------------------+
| Description | Collecting all security events in project demo | * Create logging resource with a given resource (sg1 or fwg1)
| Enabled | False |
| Event | ALL | .. code-block:: console
| ID | 8085c3e6-0fa2-4954-b5ce-ff6207931b6d |
| Name | Log_Created | $ openstack network log create my-log --resource-type security_group --resource sg1
| Project | 02568bd62b414221956f15dbe9527d16 | $ openstack network log create my-log --resource-type firewall_group --resource fwg1
| Resource | None |
| Target | None | * Create logging resource with a given target (portA)
| Type | security_group |
| created_at | 2017-07-05T02:56:43Z | .. code-block:: console
| revision_number | 1 |
| tenant_id | 02568bd62b414221956f15dbe9527d16 | $ openstack network log create my-log --resource-type security_group --target portA
| updated_at | 2017-07-05T03:12:01Z |
+-----------------+------------------------------------------------+ * Create logging resource for only the given target (portB) and the given
resource (sg1 or fwg1)
Events collected description .. code-block:: console
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
$ openstack network log create my-log --resource-type security_group --target portB --resource sg1
Logging will collect ``ACCEPT`` or ``DROP`` or both events related to security group, $ openstack network log create my-log --resource-type firewall_group --target portB --resource fwg1
with the following general characteristics:
.. note::
* Log every ``DROP`` event: Every ``DROP`` security event will be generated when
an incoming or outgoing session is dropped, that is the new session is not - The ``Enabled`` field is set to ``True`` by default. If enabled, logged
allowed for the security group and because of that blocked. events are written to the destination if ``local_output_log_base`` is
configured or ``/var/log/syslog`` in default.
* Log an ``ACCEPT`` event: An ``ACCEPT`` security event will be generated for each - The ``Event`` field will be set to ``ALL`` if ``--event`` is not specified
**NEW** incoming or outgoing session that is allowed by the ports security group. from log creation request.
More details for the events follow below:
#. Enable/Disable log
* North/South ``ACCEPT``: For a North/South session there would be a single ``ACCEPT``
event irrespective of direction. We can ``enable`` or ``disable`` logging objects at runtime. It means that
it will apply to all registered ports with the logging object immediately.
* East/West ``ACCEPT``/``ACCEPT``: In an intra-project East/West session where the For example:
security group on the originating port allows the session and the security
group on the destination port allows the session, i.e. the traffic is allowed, .. code-block:: console
there would be two ``ACCEPT`` security events generated, one from the perspective
of the originating port and one from the perspective of the destination port. $ openstack network log set --disable Log_Created
$ openstack network log show Log_Created
* East/West ``ACCEPT``/``DROP``: In an intra-project East/West session initiation +-----------------+------------------------------------------------+
where the security group on the originating port allows the session and the | Field | Value |
security group on the destination port does not allow the session there would +-----------------+------------------------------------------------+
be ``ACCEPT`` security events generated from the perspective of the originating | Description | Collecting all security events |
port and ``DROP`` security events generated from the perspective of the | Enabled | False |
destination port. | Event | ALL |
| ID | 8085c3e6-0fa2-4954-b5ce-ff6207931b6d |
General data requirements: The security event should include: | Name | Log_Created |
| Project | 02568bd62b414221956f15dbe9527d16 |
* A status of the flow ``ACCEPT``/``DROP``. | Resource | None |
* An indication of the originator of the flow, e.g which project or log resource | Target | None |
generated the event. | Type | security_group |
* A timestamp of the flow. | created_at | 2017-07-05T02:56:43Z |
* An identifier of the associated instance interface (neutron port id). | revision_number | 1 |
* An identifier of the matching security group rule. | tenant_id | 02568bd62b414221956f15dbe9527d16 |
* A layer 3 and 4 information (address, port, protocol, etc). | updated_at | 2017-07-05T03:12:01Z |
+-----------------+------------------------------------------------+
.. note::
Logged events description
No other extraneous events are generated within the security event logs, ~~~~~~~~~~~~~~~~~~~~~~~~~
e.g. no debugging data, etc.
Currently, packet logging framework supports to collect ``ACCEPT`` or ``DROP``
* Security event record format: or both events related to registered resources. As mentioned above, Neutron
packet logging framework offers two loggable resources through the ``log``
* Logged data of an ``ACCEPT`` event would look like: service plug-in: ``security_group`` and ``firewall_group``.
.. code-block:: console The general characteristics of each event will be shown as the following:
May 5 09:05:07 action=ACCEPT project_id=736672c700cd43e1bd321aeaf940365c * Log every ``DROP`` event: Every ``DROP`` security events will be generated
log_resource_ids=['4522efdf-8d44-4e19-b237-64cafc49469b', '42332d89-df42-4588-a2bb-3ce50829ac51'] when an incoming or outgoing session is blocked by the security groups or
vm_port=e0259ade-86de-482e-a717-f58258f7173f firewall groups
ethernet(dst='fa:16:3e:ec:36:32',ethertype=2048,src='fa:16:3e:50:aa:b5'),
ipv4(csum=62071,dst='10.0.0.4',flags=2,header_length=5,identification=36638,offset=0, * Log an ``ACCEPT`` event: The ``ACCEPT`` security event will be generated only
option=None,proto=6,src='172.24.4.10',tos=0,total_length=60,ttl=63,version=4), for each ``NEW`` incoming or outgoing session that is allowed by security
tcp(ack=0,bits=2,csum=15097,dst_port=80,offset=10,option=[TCPOptionMaximumSegmentSize(kind=2,length=4,max_seg_size=1460), groups or firewall groups. More details for the ``ACCEPT`` events are shown
TCPOptionSACKPermitted(kind=4,length=2), TCPOptionTimestamps(kind=8,length=10,ts_ecr=0,ts_val=196418896), as bellow:
TCPOptionNoOperation(kind=1,length=1), TCPOptionWindowScale(kind=3,length=3,shift_cnt=3)],
seq=3284890090,src_port=47825,urgent=0,window_size=14600) * North/South ``ACCEPT``: For a North/South session there would be a single
``ACCEPT`` event irrespective of direction.
* Logged data of a ``DROP`` event:
* East/West ``ACCEPT``/``ACCEPT``: In an intra-project East/West session
.. code-block:: console where the originating port allows the session and the destination port
allows the session, i.e. the traffic is allowed, there would be two
May 5 09:05:07 action=DROP project_id=736672c700cd43e1bd321aeaf940365c ``ACCEPT`` security events generated, one from the perspective of the
log_resource_ids=['4522efdf-8d44-4e19-b237-64cafc49469b'] vm_port=e0259ade-86de-482e-a717-f58258f7173f originating port and one from the perspective of the destination port.
ethernet(dst='fa:16:3e:ec:36:32',ethertype=2048,src='fa:16:3e:50:aa:b5'),
ipv4(csum=62071,dst='10.0.0.4',flags=2,header_length=5,identification=36638,offset=0, * East/West ``ACCEPT``/``DROP``: In an intra-project East/West session
option=None,proto=6,src='172.24.4.10',tos=0,total_length=60,ttl=63,version=4), initiation where the originating port allows the session and the
tcp(ack=0,bits=2,csum=15097,dst_port=80,offset=10,option=[TCPOptionMaximumSegmentSize(kind=2,length=4,max_seg_size=1460), destination port does not allow the session there would be ``ACCEPT``
TCPOptionSACKPermitted(kind=4,length=2), TCPOptionTimestamps(kind=8,length=10,ts_ecr=0,ts_val=196418896), security events generated from the perspective of the originating port and
TCPOptionNoOperation(kind=1,length=1), TCPOptionWindowScale(kind=3,length=3,shift_cnt=3)], ``DROP`` security events generated from the perspective of the destination
seq=3284890090,src_port=47825,urgent=0,window_size=14600) port.
#. The security events that are collected by security group should include:
* A timestamp of the flow.
* A status of the flow ``ACCEPT``/``DROP``.
* An indication of the originator of the flow, e.g which project or log resource
generated the events.
* An identifier of the associated instance interface (neutron port id).
* A layer 2, 3 and 4 information (mac, address, port, protocol, etc).
* Security event record format:
* Logged data of an ``ACCEPT`` event would look like:
.. code-block:: console
May 5 09:05:07 action=ACCEPT project_id=736672c700cd43e1bd321aeaf940365c
log_resource_ids=['4522efdf-8d44-4e19-b237-64cafc49469b', '42332d89-df42-4588-a2bb-3ce50829ac51']
vm_port=e0259ade-86de-482e-a717-f58258f7173f
ethernet(dst='fa:16:3e:ec:36:32',ethertype=2048,src='fa:16:3e:50:aa:b5'),
ipv4(csum=62071,dst='10.0.0.4',flags=2,header_length=5,identification=36638,offset=0,
option=None,proto=6,src='172.24.4.10',tos=0,total_length=60,ttl=63,version=4),
tcp(ack=0,bits=2,csum=15097,dst_port=80,offset=10,option=[TCPOptionMaximumSegmentSize(kind=2,length=4,max_seg_size=1460),
TCPOptionSACKPermitted(kind=4,length=2), TCPOptionTimestamps(kind=8,length=10,ts_ecr=0,ts_val=196418896),
TCPOptionNoOperation(kind=1,length=1), TCPOptionWindowScale(kind=3,length=3,shift_cnt=3)],
seq=3284890090,src_port=47825,urgent=0,window_size=14600)
* Logged data of a ``DROP`` event:
.. code-block:: console
May 5 09:05:07 action=DROP project_id=736672c700cd43e1bd321aeaf940365c
log_resource_ids=['4522efdf-8d44-4e19-b237-64cafc49469b'] vm_port=e0259ade-86de-482e-a717-f58258f7173f
ethernet(dst='fa:16:3e:ec:36:32',ethertype=2048,src='fa:16:3e:50:aa:b5'),
ipv4(csum=62071,dst='10.0.0.4',flags=2,header_length=5,identification=36638,offset=0,
option=None,proto=6,src='172.24.4.10',tos=0,total_length=60,ttl=63,version=4),
tcp(ack=0,bits=2,csum=15097,dst_port=80,offset=10,option=[TCPOptionMaximumSegmentSize(kind=2,length=4,max_seg_size=1460),
TCPOptionSACKPermitted(kind=4,length=2), TCPOptionTimestamps(kind=8,length=10,ts_ecr=0,ts_val=196418896),
TCPOptionNoOperation(kind=1,length=1), TCPOptionWindowScale(kind=3,length=3,shift_cnt=3)],
seq=3284890090,src_port=47825,urgent=0,window_size=14600)
#. The events that are collected by firewall group should include:
* A timestamp of the flow.
* A status of the flow ``ACCEPT``/``DROP``.
* The identifier of log objects that are collecting this event
* An identifier of the associated instance interface (neutron port id).
* A layer 2, 3 and 4 information (mac, address, port, protocol, etc).
* Security event record format:
* Logged data of an ``ACCEPT`` event would look like:
.. code-block:: console
Jul 26 14:46:20:
action=ACCEPT, log_resource_ids=[u'2e030f3a-e93d-4a76-bc60-1d11c0f6561b'], port=9882c485-b808-4a34-a3fb-b537642c66b2
pkt=ethernet(dst='fa:16:3e:8f:47:c5',ethertype=2048,src='fa:16:3e:1b:3e:67')
ipv4(csum=47423,dst='10.10.1.16',flags=2,header_length=5,identification=27969,offset=0,option=None,proto=1,src='10.10.0.5',tos=0,total_length=84,ttl=63,version=4)
icmp(code=0,csum=41376,data=echo(data='\xe5\xf2\xfej\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
\x00\x00\x00\x00\x00\x00\x00',id=29185,seq=0),type=8)
* Logged data of a ``DROP`` event:
.. code-block:: console
Jul 26 14:51:20:
action=DROP, log_resource_ids=[u'2e030f3a-e93d-4a76-bc60-1d11c0f6561b'], port=9882c485-b808-4a34-a3fb-b537642c66b2
pkt=ethernet(dst='fa:16:3e:32:7d:ff',ethertype=2048,src='fa:16:3e:28:83:51')
ipv4(csum=17518,dst='10.10.0.5',flags=2,header_length=5,identification=57874,offset=0,option=None,proto=1,src='10.10.1.16',tos=0,total_length=84,ttl=63,version=4)
icmp(code=0,csum=23772,data=echo(data='\x8a\xa0\xac|\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
\x00\x00\x00\x00\x00\x00\x00',id=25601,seq=5),type=8)
.. note::
No other extraneous events are generated within the security event logs,
e.g. no debugging data, etc.

BIN
doc/source/admin/figures/logging-framework.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 68 KiB