From ca8fa070685ff7c5a42c45e201a86a9b5d17cc7e Mon Sep 17 00:00:00 2001 From: Nate Johnston Date: Tue, 6 Sep 2016 20:33:44 +0000 Subject: [PATCH] [networking] Migrate FWaaS docs from admin to networking guide With the introduction of FWaaS v2, it is time to revamp the documentation for FireWall as a Service and bring it up to speed with current standards. As part of that, the documentation is being relocated from the Admin Guide to the Networking Guide. The documentation is also being sliced into FWaaS v1 and FWaaS v2 scenarios, so that they can be added in the correct places in the documentation tree. To do in future patch: - The FWaaS v2 scenario needs to be updated to show exactly how FWaaS will be used with API calls. - The 'feature comparison' section needs to be expanded to show all of the points of comparison between v1 and v2. Change-Id: I8a1635743d8df22970405193180916bd438605bb --- .../source/networking-introduction.rst | 130 +----------------- .../source/figures/fwaas.png | Bin .../source/figures/fwaas.svg | 0 .../source/fwaas-v1-scenario.rst | 117 ++++++++++++++++ .../source/fwaas-v2-scenario.rst | 115 ++++++++++++++++ doc/networking-guide/source/fwaas.rst | 28 ++++ doc/networking-guide/source/intro.rst | 1 + doc/networking-guide/source/misc.rst | 2 + 8 files changed, 265 insertions(+), 128 deletions(-) rename doc/{admin-guide => networking-guide}/source/figures/fwaas.png (100%) rename doc/{admin-guide => networking-guide}/source/figures/fwaas.svg (100%) create mode 100644 doc/networking-guide/source/fwaas-v1-scenario.rst create mode 100644 doc/networking-guide/source/fwaas-v2-scenario.rst create mode 100644 doc/networking-guide/source/fwaas.rst diff --git a/doc/admin-guide/source/networking-introduction.rst b/doc/admin-guide/source/networking-introduction.rst index 428d2bf132..473ebc4df6 100644 --- a/doc/admin-guide/source/networking-introduction.rst +++ b/doc/admin-guide/source/networking-introduction.rst @@ -156,136 +156,10 @@ Least connections Firewall-as-a-Service (FWaaS) overview ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The Firewall-as-a-Service (FWaaS) plug-in adds perimeter firewall -management to Networking. FWaaS uses iptables to apply firewall policy -to all Networking routers within a project. FWaaS supports one firewall -policy and logical firewall instance per project. - -Whereas security groups operate at the instance-level, FWaaS operates at -the perimeter to filter traffic at the neutron router. - -The example diagram illustrates the flow of ingress and egress traffic -for the VM2 instance: - -.. figure:: figures/fwaas.png - -Enable FWaaS ------------- - -FWaaS management options are also available in the Dashboard. - -#. Enable the FWaaS plug-in in the ``/etc/neutron/neutron.conf`` file: - - .. code-block:: ini - - service_plugins = firewall - [service_providers] - ... - service_provider = FIREWALL:Iptables:neutron.agent.linux.iptables_ - firewall.OVSHybridIptablesFirewallDriver:default - - [fwaas] - driver = neutron_fwaas.services.firewall.drivers.linux.iptables_ - fwaas.IptablesFwaasDriver - enabled = True - - .. note:: - - On Ubuntu, modify the ``[fwaas]`` section in the - ``/etc/neutron/fwaas_driver.ini`` file instead of - ``/etc/neutron/neutron.conf``. - -#. Create the required tables in the database: - - .. code-block:: console - - # neutron-db-manage --subproject neutron-fwaas upgrade head - -#. Enable the option in the ``local_settings.py`` file, - which is typically located on the controller node: - - .. code-block:: ini - - OPENSTACK_NEUTRON_NETWORK = { - ... - 'enable_firewall' = True, - ... - } - - .. note:: - - By default, ``enable_firewall`` option value is ``True`` in - ``local_settings.py`` file. - - Apply the settings by restarting the web server. - -#. Restart the ``neutron-l3-agent`` and ``neutron-server`` services - to apply the settings. - -Configure Firewall-as-a-Service -------------------------------- - -Create the firewall rules and create a policy that contains them. -Then, create a firewall that applies the policy. - -#. Create a firewall rule: - - .. code-block:: console - - $ neutron firewall-rule-create --protocol {tcp,udp,icmp,any} \ - --source-ip-address SOURCE_IP_ADDRESS \ - --destination-ip-address DESTINATION_IP_ADDRESS \ - --source-port SOURCE_PORT_RANGE --destination-port DEST_PORT_RANGE \ - --action {allow,deny,reject} - - The Networking client requires a protocol value; if the rule is protocol - agnostic, you can use the ``any`` value. - - .. note:: - - When the source or destination IP address are not of the same IP - version (for example, IPv6), the command returns an error. - -#. Create a firewall policy: - - .. code-block:: console - - $ neutron firewall-policy-create --firewall-rules \ - "FIREWALL_RULE_IDS_OR_NAMES" myfirewallpolicy - - Separate firewall rule IDs or names with spaces. The order in which you - specify the rules is important. - - You can create a firewall policy without any rules and add rules later, - as follows: - - * To add multiple rules, use the update operation. - - * To add a single rule, use the insert-rule operation. - - For more details, see `Networking command-line client - `_ - in the OpenStack Command-Line Interface Reference. - - .. note:: - - FWaaS always adds a default ``deny all`` rule at the lowest precedence - of each policy. Consequently, a firewall policy with no rules blocks - all traffic by default. - -#. Create a firewall: - - .. code-block:: console - - $ neutron firewall-create FIREWALL_POLICY_UUID - - .. note:: - - The firewall remains in PENDING\_CREATE state until you create a - Networking router and attach an interface to it. +For information on Firewall-as-a-Service (FWaaS), please consult the `Networking Guide `__. Allowed-address-pairs ---------------------- +~~~~~~~~~~~~~~~~~~~~~ ``Allowed-address-pairs`` enables you to specify mac_address and ip_address(cidr) pairs that pass through a port regardless diff --git a/doc/admin-guide/source/figures/fwaas.png b/doc/networking-guide/source/figures/fwaas.png similarity index 100% rename from doc/admin-guide/source/figures/fwaas.png rename to doc/networking-guide/source/figures/fwaas.png diff --git a/doc/admin-guide/source/figures/fwaas.svg b/doc/networking-guide/source/figures/fwaas.svg similarity index 100% rename from doc/admin-guide/source/figures/fwaas.svg rename to doc/networking-guide/source/figures/fwaas.svg diff --git a/doc/networking-guide/source/fwaas-v1-scenario.rst b/doc/networking-guide/source/fwaas-v1-scenario.rst new file mode 100644 index 0000000000..9bd89398f5 --- /dev/null +++ b/doc/networking-guide/source/fwaas-v1-scenario.rst @@ -0,0 +1,117 @@ +Firewall-as-a-Service (FWaaS) v2 scenario +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enable FWaaS v1 +--------------- + +FWaaS management options are also available in the Dashboard. + +#. Enable the FWaaS plug-in in the ``/etc/neutron/neutron.conf`` file: + + .. code-block:: ini + + service_plugins = firewall + [service_providers] + ... + service_provider = FIREWALL:Iptables:neutron.agent.linux.iptables_ + firewall.OVSHybridIptablesFirewallDriver:default + + [fwaas] + driver = neutron_fwaas.services.firewall.drivers.linux.iptables_ + fwaas.IptablesFwaasDriver + enabled = True + + .. note:: + + On Ubuntu, modify the ``[fwaas]`` section in the + ``/etc/neutron/fwaas_driver.ini`` file instead of + ``/etc/neutron/neutron.conf``. + +#. Create the required tables in the database: + + .. code-block:: console + + # neutron-db-manage --subproject neutron-fwaas upgrade head + +#. Enable the option in the ``local_settings.py`` file, + which is typically located on the controller node: + + .. code-block:: ini + + OPENSTACK_NEUTRON_NETWORK = { + ... + 'enable_firewall' = True, + ... + } + + .. note:: + + By default, ``enable_firewall`` option value is ``True`` in + ``local_settings.py`` file. + + Apply the settings by restarting the web server. + +#. Restart the ``neutron-l3-agent`` and ``neutron-server`` services + to apply the settings. + +Configure Firewall-as-a-Service v1 +---------------------------------- + +Create the firewall rules and create a policy that contains them. +Then, create a firewall that applies the policy. + +#. Create a firewall rule: + + .. code-block:: console + + $ neutron firewall-rule-create --protocol {tcp,udp,icmp,any} \ + --source-ip-address SOURCE_IP_ADDRESS \ + --destination-ip-address DESTINATION_IP_ADDRESS \ + --source-port SOURCE_PORT_RANGE --destination-port DEST_PORT_RANGE \ + --action {allow,deny,reject} + + The Networking client requires a protocol value. If the rule is protocol + agnostic, you can use the ``any`` value. + + .. note:: + + When the source or destination IP address are not of the same IP + version (for example, IPv6), the command returns an error. + +#. Create a firewall policy: + + .. code-block:: console + + $ neutron firewall-policy-create --firewall-rules \ + "FIREWALL_RULE_IDS_OR_NAMES" myfirewallpolicy + + Separate firewall rule IDs or names with spaces. The order in which you + specify the rules is important. + + You can create a firewall policy without any rules and add rules later, + as follows: + + * To add multiple rules, use the update operation. + + * To add a single rule, use the insert-rule operation. + + For more details, see `Networking command-line client + `_ + in the OpenStack Command-Line Interface Reference. + + .. note:: + + FWaaS always adds a default ``deny all`` rule at the lowest precedence + of each policy. Consequently, a firewall policy with no rules blocks + all traffic by default. + +#. Create a firewall: + + .. code-block:: console + + $ neutron firewall-create FIREWALL_POLICY_UUID + + .. note:: + + The firewall remains in PENDING\_CREATE state until you create a + Networking router and attach an interface to it. diff --git a/doc/networking-guide/source/fwaas-v2-scenario.rst b/doc/networking-guide/source/fwaas-v2-scenario.rst new file mode 100644 index 0000000000..be088276cd --- /dev/null +++ b/doc/networking-guide/source/fwaas-v2-scenario.rst @@ -0,0 +1,115 @@ +Firewall-as-a-Service (FWaaS) v2 scenario +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Enable FWaaS v2 +--------------- + +#. Enable the FWaaS plug-in in the ``/etc/neutron/neutron.conf`` file: + + .. code-block:: ini + + service_plugins = firewall_v2 + [service_providers] + ... + service_provider = FIREWALL:Iptables:neutron.agent.linux.iptables_ + firewall.OVSHybridIptablesFirewallDriver:default + + [fwaas] + driver = neutron_fwaas.services.firewall.drivers.linux.iptables_ + fwaas.IptablesFwaasDriver + enabled = True + + .. note:: + + On Ubuntu, modify the ``[fwaas]`` section in the + ``/etc/neutron/fwaas_driver.ini`` file instead of + ``/etc/neutron/neutron.conf``. + +#. Create the required tables in the database: + + .. code-block:: console + + # neutron-db-manage --subproject neutron-fwaas upgrade head + +#. Enable the option in the ``local_settings.py`` file, + which is typically located on the controller node: + + .. code-block:: ini + + OPENSTACK_NEUTRON_NETWORK = { + ... + 'enable_firewall' = True, + ... + } + + .. note:: + + By default, ``enable_firewall`` option value is ``True`` in + ``local_settings.py`` file. + + Apply the settings by restarting the web server. + +#. Restart the ``neutron-l3-agent`` and ``neutron-server`` services + to apply the settings. + +Configure Firewall-as-a-Service v2 +---------------------------------- + +Create the firewall rules and create a policy that contains them. +Then, create a firewall that applies the policy. + +#. Create a firewall rule: + + .. code-block:: console + + $ neutron firewall-rule-create --protocol {tcp,udp,icmp,any} \ + --source-ip-address SOURCE_IP_ADDRESS \ + --destination-ip-address DESTINATION_IP_ADDRESS \ + --source-port SOURCE_PORT_RANGE --destination-port DEST_PORT_RANGE \ + --action {allow,deny,reject} + + The Networking client requires a protocol value. If the rule is protocol + agnostic, you can use the ``any`` value. + + .. note:: + + When the source or destination IP address are not of the same IP + version (for example, IPv6), the command returns an error. + +#. Create a firewall policy: + + .. code-block:: console + + $ neutron firewall-policy-create --firewall-rules \ + "FIREWALL_RULE_IDS_OR_NAMES" myfirewallpolicy + + Separate firewall rule IDs or names with spaces. The order in which you + specify the rules is important. + + You can create a firewall policy without any rules and add rules later, + as follows: + + * To add multiple rules, use the update operation. + + * To add a single rule, use the insert-rule operation. + + For more details, see `Networking command-line client + `_ + in the OpenStack Command-Line Interface Reference. + + .. note:: + + FWaaS always adds a default ``deny all`` rule at the lowest precedence + of each policy. Consequently, a firewall policy with no rules blocks + all traffic by default. + +#. Create a firewall: + + .. code-block:: console + + $ neutron firewall-create FIREWALL_POLICY_UUID + + .. note:: + + The firewall remains in PENDING\_CREATE state until you create a + Networking router and attach an interface to it. diff --git a/doc/networking-guide/source/fwaas.rst b/doc/networking-guide/source/fwaas.rst new file mode 100644 index 0000000000..0e30515cc9 --- /dev/null +++ b/doc/networking-guide/source/fwaas.rst @@ -0,0 +1,28 @@ +Firewall-as-a-Service (FWaaS) overview +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Firewall-as-a-Service (FWaaS) plug-in adds perimeter firewall management to +the OpenStack Networking service. FWaaS uses iptables to apply firewall policy +to all neutron routers within a project. FWaaS supports one firewall policy and +logical firewall instance per project. + +Whereas security groups operate at the instance-level, FWaaS operates at +the perimeter to filter traffic at the neutron router. + +The example diagram illustrates the flow of ingress and egress traffic +for the VM2 instance: + +.. figure:: figures/fwaas.png + +FWaaS version selection +------------------------ + +Consult this feature matrix to compare features for FWaaS v1 and v2. + +| Feature | v1 | v2 | +| ---------------------------------- | --- | --- | +| Supports L3 firewalling (routers) | YES | YES | +| Supports L2 firewalling (VM ports) | NO | NO | +| CLI support | YES | NO | +| Horizon support | YES | NO | + diff --git a/doc/networking-guide/source/intro.rst b/doc/networking-guide/source/intro.rst index 2fec27d3ff..8eb4b6fd8b 100644 --- a/doc/networking-guide/source/intro.rst +++ b/doc/networking-guide/source/intro.rst @@ -45,3 +45,4 @@ components: intro-network-namespaces intro-nat intro-os-networking + fwaas diff --git a/doc/networking-guide/source/misc.rst b/doc/networking-guide/source/misc.rst index 0d027c666b..0dd90b27da 100644 --- a/doc/networking-guide/source/misc.rst +++ b/doc/networking-guide/source/misc.rst @@ -7,4 +7,6 @@ Miscellaneous .. toctree:: :maxdepth: 2 + fwaas-v2-scenario + fwaas-v1-scenario misc-libvirt