Merge "[networking] Migrate FWaaS docs from admin to networking guide"

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
+For information on Firewall-as-a-Service (FWaaS), please consult the `Networking Guide <http://docs.openstack.org/mitaka/networking-guide/fwaas.html>`__.
-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
-   <http://docs.openstack.org/cli-reference/neutron.html>`_
-   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.
 
 Allowed-address-pairs
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 ``Allowed-address-pairs`` enables you to specify
 mac_address and ip_address(cidr) pairs that pass through a port regardless

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
+   <http://docs.openstack.org/cli-reference/neutron.html>`_
+   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.

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
+   <http://docs.openstack.org/cli-reference/neutron.html>`_
+   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.

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  |
+

doc/networking-guide/source/intro.rst

@@ -45,3 +45,4 @@ components:
    intro-network-namespaces
    intro-nat
    intro-os-networking
+   fwaas

doc/networking-guide/source/misc.rst

@@ -7,4 +7,6 @@ Miscellaneous
 .. toctree::
    :maxdepth: 2
 
+   fwaas-v2-scenario
+   fwaas-v1-scenario
    misc-libvirt