diff --git a/doc/source/admin/config-logging.rst b/doc/source/admin/config-logging.rst index 00ccbc3706c..7e5ef297666 100644 --- a/doc/source/admin/config-logging.rst +++ b/doc/source/admin/config-logging.rst @@ -1,244 +1,323 @@ -.. _config-logging: - -=========================== -Logging for security groups -=========================== - -Logging is designed as a service plug-in that captures events for -relevant resources (for example, security groups or firewalls) when they occur. - - -Supported logging resource types -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -As of the Queens release, the ``security_group`` resource type is supported. - - -Configuration -~~~~~~~~~~~~~ - -To enable the service, follow the steps below. - -#. On Neutron server node: - - #. Add the Logging service to the ``service_plugins`` setting in - ``/etc/neutron/neutron.conf``. For example: - - .. code-block:: none - - service_plugins = router,metering,log - - #. Add the Logging extension to the ``extensions`` setting in - ``/etc/neutron/plugins/ml2/ml2_conf.ini``. For example: - - .. code-block:: ini - - [agent] - extensions = log - -#. On compute/network nodes: - - #. In ``/etc/neutron/plugins/ml2/openvswitch_agent.ini``, add ``log`` - to the ``extensions`` setting in the ``[agent]`` section. For example: - - .. code-block:: ini - - [agent] - extensions = log - - #. In ``/etc/neutron/plugins/ml2/openvswitch_agent.ini``, add configuration - options for logging feature in the ``[network_log]`` section. For example: - - .. code-block:: ini - - [network_log] - rate_limit = 100 - burst_limit = 25 - #local_output_log_base = - - 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 ------------------------------------------- - -With the default ``/etc/neutron/policy.json``, administrators must -set up resource logging on behalf of the cloud projects. - -If projects are trusted to administer their own resource logging in your cloud, -neutron's file ``policy.json`` can be modified to allow this. - -Modify ``/etc/neutron/policy.json`` policy entries as follows: - -.. code-block:: none - - "get_loggable_resources": "rule:regular_user", - "create_log": "rule:regular_user", - "update_log": "rule:regular_user", - "delete_log": "rule:regular_user", - "get_logs": "rule:regular_user", - "get_log": "rule:regular_user", - -Operator workflow -~~~~~~~~~~~~~~~~~ - -#. Confirm logging resources are supported: - - .. code-block:: console - - $ openstack network loggable resources list - +-----------------+ - | Supported types | - +-----------------+ - | security_group | - +-----------------+ - -#. 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 in project demo" \ - --enable --event ALL Log_Created - +-----------------+------------------------------------------------+ - | Field | Value | - +-----------------+------------------------------------------------+ - | Description | Collecting all security events in project demo | - | 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 | - +-----------------+------------------------------------------------+ - -.. note:: - - The ``Enabled`` field is set to ``True`` by default. If enabled, - log information is written to the destination if configured in - ``local_output_log_base`` or system journal like ``/var/log/syslog``. - - -Enable/Disable log ------------------- - -We can enable or disable logging objects at runtime. It means that it will -apply to all attached ports with the logging object immediately. - -For example: - -.. code-block:: console - - $ openstack network log set --disable Log_Created - $ openstack network log show Log_Created - +-----------------+------------------------------------------------+ - | Field | Value | - +-----------------+------------------------------------------------+ - | Description | Collecting all security events in project demo | - | 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 | - +-----------------+------------------------------------------------+ - - -Events collected description -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Logging will collect ``ACCEPT`` or ``DROP`` or both events related to security group, -with the following general characteristics: - -* 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 - allowed for the security group and because of that blocked. - -* Log an ``ACCEPT`` event: An ``ACCEPT`` security event will be generated for each - **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`` - event irrespective of direction. - - * East/West ``ACCEPT``/``ACCEPT``: In an intra-project East/West session where the - 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 - 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: - -* A status of the flow ``ACCEPT``/``DROP``. -* An indication of the originator of the flow, e.g which project or log resource - generated the event. -* A timestamp of the flow. -* An identifier of the associated instance interface (neutron port id). -* An identifier of the matching security group rule. -* A layer 3 and 4 information (address, port, protocol, etc). - -.. note:: - - No other extraneous events are generated within the security event logs, - 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) +.. _config-logging: + +================================ +Neutron Packet Logging Framework +================================ + +Packet logging service is designed as a Neutron plug-in that captures network +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. + + +Service Configuration +~~~~~~~~~~~~~~~~~~~~~ + +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: + + .. code-block:: none + + service_plugins = router,metering,log + +#. 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: + + .. code-block:: ini + + [agent] + extensions = 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: + + .. code-block:: ini + + [AGENT] + extensions = fwaas_v2,fwaas_v2_log + +#. On compute/network nodes, add configuration for logging service to + ``[network_log]`` in ``/etc/neutron/plugins/ml2/openvswitch_agent.ini`` as + shown bellow: + + .. code-block:: ini + + [network_log] + rate_limit = 100 + burst_limit = 25 + #local_output_log_base = + + 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``. + + .. note:: + + - 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 packets will be + stored in system journal like ``/var/log/syslog`` by default. + +Trusted projects policy.json configuration +---------------------------------------------- + +With the default ``/etc/neutron/policy.json``, administrators must set up +resource logging on behalf of the cloud projects. + +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. + +Modify ``/etc/neutron/policy.json`` entries as follows: + +.. code-block:: none + + "get_loggable_resources": "rule:regular_user", + "create_log": "rule:regular_user", + "get_log": "rule:regular_user", + "get_logs": "rule:regular_user", + "update_log": "rule:regular_user", + "delete_log": "rule:regular_user", + +Service workflow for Operator +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +#. To check the loggable resources that are supported by framework: + + .. code-block:: console + + $ openstack network loggable resources list + +-----------------+ + | Supported types | + +-----------------+ + | security_group | + | firewall_group | + +-----------------+ + + .. 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 + + $ openstack network log set --disable Log_Created + $ openstack network log show Log_Created + +-----------------+------------------------------------------------+ + | Field | Value | + +-----------------+------------------------------------------------+ + | Description | Collecting all security events | + | 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 | + +-----------------+------------------------------------------------+ + +Logged events description +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Currently, packet logging framework supports to collect ``ACCEPT`` or ``DROP`` +or both events related to registered resources. As mentioned above, Neutron +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: + +* 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 + +* Log an ``ACCEPT`` event: The ``ACCEPT`` security event will be generated only + 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: + + * North/South ``ACCEPT``: For a North/South session there would be a single + ``ACCEPT`` event irrespective of direction. + + * 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. + + * East/West ``ACCEPT``/``DROP``: In an intra-project East/West session + initiation where the originating port allows the session and 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. + +#. 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. diff --git a/doc/source/admin/figures/logging-framework.png b/doc/source/admin/figures/logging-framework.png new file mode 100644 index 00000000000..8e3c2059c93 Binary files /dev/null and b/doc/source/admin/figures/logging-framework.png differ