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

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

@ -1,99 +1,104 @@
.. _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.
.. image:: figures/logging-framework.png
:width: 100%
:alt: Packet Logging Framework
Supported loggable resource types
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
From Rocky release, both of ``security_group`` and ``firewall_group`` are
supported as resource types in Neutron packet logging framework.
Supported logging resource types Service Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
As of the Queens release, the ``security_group`` resource type is supported. To enable the logging service, follow the below steps.
#. On Neutron controller node, add ``log`` to ``service_plugins`` setting in
``/etc/neutron/neutron.conf`` file. For example:
Configuration .. code-block:: none
~~~~~~~~~~~~~
To enable the service, follow the steps below. service_plugins = router,metering,log
#. On Neutron server node: #. 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``
for controller node and in ``/etc/neutron/plugins/ml2/openvswitch_agent.ini``
for compute/network nodes. For example:
#. Add the Logging service to the ``service_plugins`` setting in .. code-block:: ini
``/etc/neutron/neutron.conf``. For example:
.. code-block:: none [agent]
extensions = log
service_plugins = router,metering,log #. To enable logging service for ``firewall_group`` in Layer 3, add
``fwaas_v2_log`` to option ``extensions`` in section ``[AGENT]`` in
``/etc/neutron/l3_agent.ini`` for network nodes. For example:
#. Add the Logging extension to the ``extensions`` setting in .. code-block:: ini
``/etc/neutron/plugins/ml2/ml2_conf.ini``. For example:
.. code-block:: ini [AGENT]
extensions = fwaas_v2,fwaas_v2_log
[agent] #. On compute/network nodes, add configuration for logging service to
extensions = log ``[network_log]`` in ``/etc/neutron/plugins/ml2/openvswitch_agent.ini`` as
shown bellow:
#. On compute/network nodes: .. code-block:: ini
#. In ``/etc/neutron/plugins/ml2/openvswitch_agent.ini``, add ``log`` [network_log]
to the ``extensions`` setting in the ``[agent]`` section. For example: rate_limit = 100
burst_limit = 25
#local_output_log_base = <None>
.. code-block:: ini In which, ``rate_limit`` is used to configure the maximum number of packets
to be logged per second (packets per second). When a high rate triggers
``rate_limit``, logging queues packets to be logged. ``burst_limit`` is
used to configure the maximum of queued packets. And logged packets can be
stored anywhere by using ``local_output_log_base``.
[agent] .. note::
extensions = log
#. In ``/etc/neutron/plugins/ml2/openvswitch_agent.ini``, add configuration - It requires at least ``100`` for ``rate_limit`` and at least ``25``
options for logging feature in the ``[network_log]`` section. For example: for ``burst_limit``.
- If ``rate_limit`` is unset, logging will log unlimited.
.. code-block:: ini - If we don't specify ``local_output_log_base``, logged packets will be
stored in system journal like ``/var/log/syslog`` by default.
[network_log]
rate_limit = 100
burst_limit = 25
#local_output_log_base = <None>
In which, ``rate_limit`` is used to configure the maximum number of packets
to be logged per second (packets per second). When a high rate triggers
``rate_limit``, logging queues packets to be logged. ``burst_limit`` is used
to configure the maximum of queued packets. And logged data can be stored
anywhere by using ``local_output_log_base``.
.. note::
- Logging currently works with ``openvswitch`` firewall driver only.
- It requires at least 100 for ``rate_limit`` and at least 25 for ``burst_limit``.
- If ``rate_limit`` is unset, logging will log unlimited.
- If we don't specify ``local_output_log_base``, logged data will be stored
in system journal like ``/var/log/syslog``.
Trusted projects policy.json configuration Trusted projects policy.json configuration
------------------------------------------ ----------------------------------------------
With the default ``/etc/neutron/policy.json``, administrators must With the default ``/etc/neutron/policy.json``, administrators must set up
set up resource logging on behalf of the cloud projects. resource logging on behalf of the cloud projects.
If projects are trusted to administer their own resource logging in your cloud, If projects are trusted to administer their own loggable resources in their
neutron's file ``policy.json`` can be modified to allow this. cloud, neutron's policy file ``policy.json`` can be modified to allow this.
Modify ``/etc/neutron/policy.json`` policy entries as follows: Modify ``/etc/neutron/policy.json`` entries as follows:
.. code-block:: none .. code-block:: none
"get_loggable_resources": "rule:regular_user", "get_loggable_resources": "rule:regular_user",
"create_log": "rule:regular_user", "create_log": "rule:regular_user",
"get_log": "rule:regular_user",
"get_logs": "rule:regular_user",
"update_log": "rule:regular_user", "update_log": "rule:regular_user",
"delete_log": "rule:regular_user", "delete_log": "rule:regular_user",
"get_logs": "rule:regular_user",
"get_log": "rule:regular_user",
Operator workflow Service workflow for Operator
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. Confirm logging resources are supported: #. To check the loggable resources that are supported by framework:
.. code-block:: console .. code-block:: console
@ -102,143 +107,217 @@ Operator workflow
| Supported types | | Supported types |
+-----------------+ +-----------------+
| security_group | | security_group |
| firewall_group |
+-----------------+ +-----------------+
#. Create a logging resource with an appropriate resource type: .. note::
- In VM ports, logging for ``security_group`` in currently works with
``openvswitch`` firewall driver only. ``linuxbridge`` is under
development.
- Logging for ``firewall_group`` works on internal router ports only. VM
ports would be supported in the future.
#. Log creation:
* Create a logging resource with an appropriate resource type
.. code-block:: console
$ openstack network log create --resource-type security_group \
--description "Collecting all security events" \
--event ALL Log_Created
+-----------------+------------------------------------------------+
| Field | Value |
+-----------------+------------------------------------------------+
| Description | Collecting all security events |
| Enabled | True |
| Event | ALL |
| ID | 8085c3e6-0fa2-4954-b5ce-ff6207931b6d |
| Name | Log_Created |
| Project | 02568bd62b414221956f15dbe9527d16 |
| Resource | None |
| Target | None |
| Type | security_group |
| created_at | 2017-07-05T02:56:43Z |
| revision_number | 0 |
| tenant_id | 02568bd62b414221956f15dbe9527d16 |
| updated_at | 2017-07-05T02:56:43Z |
+-----------------+------------------------------------------------+
.. warning::
In the case of ``--resource`` and ``--target`` are not specified from the
request, these arguments will be assigned to ``ALL`` by default. Hence,
there is an enormous range of log events will be created.
* Create logging resource with a given resource (sg1 or fwg1)
.. code-block:: console
$ openstack network log create my-log --resource-type security_group --resource sg1
$ openstack network log create my-log --resource-type firewall_group --resource fwg1
* Create logging resource with a given target (portA)
.. code-block:: console
$ openstack network log create my-log --resource-type security_group --target portA
* Create logging resource for only the given target (portB) and the given
resource (sg1 or fwg1)
.. code-block:: console
$ openstack network log create my-log --resource-type security_group --target portB --resource sg1
$ openstack network log create my-log --resource-type firewall_group --target portB --resource fwg1
.. note::
- The ``Enabled`` field is set to ``True`` by default. If enabled, logged
events are written to the destination if ``local_output_log_base`` is
configured or ``/var/log/syslog`` in default.
- The ``Event`` field will be set to ``ALL`` if ``--event`` is not specified
from log creation request.
#. Enable/Disable log
We can ``enable`` or ``disable`` logging objects at runtime. It means that
it will apply to all registered ports with the logging object immediately.
For example:
.. code-block:: console .. code-block:: console
$ openstack network log create --resource-type security_group \ $ openstack network log set --disable Log_Created
--description "Collecting all security events in project demo" \ $ openstack network log show Log_Created
--enable --event ALL Log_Created +-----------------+------------------------------------------------+
+-----------------+------------------------------------------------+ | Field | Value |
| Field | Value | +-----------------+------------------------------------------------+
+-----------------+------------------------------------------------+ | Description | Collecting all security events |
| Description | Collecting all security events in project demo | | Enabled | False |
| Enabled | True | | Event | ALL |
| Event | ALL | | ID | 8085c3e6-0fa2-4954-b5ce-ff6207931b6d |
| ID | 8085c3e6-0fa2-4954-b5ce-ff6207931b6d | | Name | Log_Created |
| Name | Log_Created | | Project | 02568bd62b414221956f15dbe9527d16 |
| Project | 02568bd62b414221956f15dbe9527d16 | | Resource | None |
| Resource | None | | Target | None |
| Target | None | | Type | security_group |
| Type | security_group | | created_at | 2017-07-05T02:56:43Z |
| created_at | 2017-07-05T02:56:43Z | | revision_number | 1 |
| revision_number | 0 | | tenant_id | 02568bd62b414221956f15dbe9527d16 |
| tenant_id | 02568bd62b414221956f15dbe9527d16 | | updated_at | 2017-07-05T03:12:01Z |
| updated_at | 2017-07-05T02:56:43Z | +-----------------+------------------------------------------------+
+-----------------+------------------------------------------------+
.. note:: Logged events description
~~~~~~~~~~~~~~~~~~~~~~~~~
The ``Enabled`` field is set to ``True`` by default. If enabled, Currently, packet logging framework supports to collect ``ACCEPT`` or ``DROP``
log information is written to the destination if configured in or both events related to registered resources. As mentioned above, Neutron
``local_output_log_base`` or system journal like ``/var/log/syslog``. packet logging framework offers two loggable resources through the ``log``
service plug-in: ``security_group`` and ``firewall_group``.
The general characteristics of each event will be shown as the following:
Enable/Disable log * Log every ``DROP`` event: Every ``DROP`` security events will be generated
------------------ when an incoming or outgoing session is blocked by the security groups or
firewall groups
We can enable or disable logging objects at runtime. It means that it will * Log an ``ACCEPT`` event: The ``ACCEPT`` security event will be generated only
apply to all attached ports with the logging object immediately. for each ``NEW`` incoming or outgoing session that is allowed by security
groups or firewall groups. More details for the ``ACCEPT`` events are shown
as bellow:
For example: * North/South ``ACCEPT``: For a North/South session there would be a single
``ACCEPT`` event irrespective of direction.
.. code-block:: console * East/West ``ACCEPT``/``ACCEPT``: In an intra-project East/West session
where the originating port allows the session and the destination port
allows the session, i.e. the traffic is allowed, 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 * East/West ``ACCEPT``/``DROP``: In an intra-project East/West session
$ openstack network log show Log_Created initiation where the originating port allows the session and the
+-----------------+------------------------------------------------+ destination port does not allow the session there would be ``ACCEPT``
| Field | Value | security events generated from the perspective of the originating port and
+-----------------+------------------------------------------------+ ``DROP`` security events generated from the perspective of the destination
| Description | Collecting all security events in project demo | port.
| Enabled | False |
| Event | ALL |
| ID | 8085c3e6-0fa2-4954-b5ce-ff6207931b6d |
| Name | Log_Created |
| Project | 02568bd62b414221956f15dbe9527d16 |
| Resource | None |
| Target | None |
| Type | security_group |
| created_at | 2017-07-05T02:56:43Z |
| revision_number | 1 |
| tenant_id | 02568bd62b414221956f15dbe9527d16 |
| updated_at | 2017-07-05T03:12:01Z |
+-----------------+------------------------------------------------+
#. The security events that are collected by security group should include:
Events collected description * 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).
Logging will collect ``ACCEPT`` or ``DROP`` or both events related to security group, * Security event record format:
with the following general characteristics:
* Log every ``DROP`` event: Every ``DROP`` security event will be generated when * Logged data of an ``ACCEPT`` event would look like:
an incoming or outgoing session is dropped, that is the new session is not
allowed for the security group and because of that blocked.
* Log an ``ACCEPT`` event: An ``ACCEPT`` security event will be generated for each .. code-block:: console
**NEW** incoming or outgoing session that is allowed by the ports security group.
More details for the events follow below:
* North/South ``ACCEPT``: For a North/South session there would be a single ``ACCEPT`` May 5 09:05:07 action=ACCEPT project_id=736672c700cd43e1bd321aeaf940365c
event irrespective of direction. 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)
* East/West ``ACCEPT``/``ACCEPT``: In an intra-project East/West session where the * Logged data of a ``DROP`` event:
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,
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.
* East/West ``ACCEPT``/``DROP``: In an intra-project East/West session initiation .. code-block:: console
where the security group on the originating port allows the session and the
security group on the destination port does not allow the session there would
be ``ACCEPT`` security events generated from the perspective of the originating
port and ``DROP`` security events generated from the perspective of the
destination port.
General data requirements: The security event should include: 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)
* A status of the flow ``ACCEPT``/``DROP``. #. The events that are collected by firewall group should include:
* An indication of the originator of the flow, e.g which project or log resource
generated the event. * A timestamp of the flow.
* A timestamp of the flow. * A status of the flow ``ACCEPT``/``DROP``.
* An identifier of the associated instance interface (neutron port id). * The identifier of log objects that are collecting this event
* An identifier of the matching security group rule. * An identifier of the associated instance interface (neutron port id).
* A layer 3 and 4 information (address, port, protocol, etc). * 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:: .. note::
No other extraneous events are generated within the security event logs, No other extraneous events are generated within the security event logs,
e.g. no debugging data, etc. e.g. no debugging data, 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)

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