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