Revert "doc: Remove fwaas references from docs"

This reverts commit bce27811df.

Reason for revert: neutron-fwaas has maintainers so the documentation should be available.

Due to changes since the original deletion commit the following changes
were added:
* Add note that OVN is not yet supported
* Remove note that Horizon support is not available

Change-Id: I1a739ee045b49e9b44283c28f95b1accc8a1e37f

doc/source/admin/archives/introduction.rst

@@ -104,6 +104,11 @@ Set these options to configure SSL:
 ``backlog = 4096``
     Number of backlog requests with which to configure the socket.
 
+Firewall-as-a-Service (FWaaS) overview
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For information on Firewall-as-a-Service (FWaaS), please consult the :doc:`Networking Guide <../fwaas>`.
+
 Allowed-address-pairs
 ~~~~~~~~~~~~~~~~~~~~~
 

doc/source/admin/config-ipv6.rst

@@ -413,6 +413,11 @@ configuration. Either or both the ``peer_address`` and the
 addressing modes and router modes described above should not impact
 support.
 
+FWaaS
+-----
+
+FWaaS allows creation of IPv6 based rules.
+
 NAT & Floating IPs
 ------------------
 

doc/source/admin/config-logging.rst

@@ -41,6 +41,20 @@ To enable the logging service, follow the below steps.
      [agent]
      extensions = log
 
+   .. note::
+
+       Fwaas v2 log is currently only supported by openvswitch, the firewall
+       logging driver of linuxbridge is not implemented.
+
+#. 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`` and in
    ``/etc/neutron/l3_agent.ini`` as shown bellow:

doc/source/admin/config-ovs-dpdk.rst

@@ -151,7 +151,7 @@ Known limitations
   If huge pages are not present in the guest, the interface will appear but
   will not function.
 * Expect performance degradation of services using tap devices: these devices
-  do not support DPDK. Example services include DVR.
+  do not support DPDK. Example services include DVR and FWaaS.
 * When the ``ovs_use_veth`` option is set to ``True``, any traffic sent
   from a DHCP namespace will have an incorrect TCP checksum.
   This means that if ``enable_isolated_metadata`` is set to ``True`` and

doc/source/admin/config-services-agent.rst

@@ -18,7 +18,7 @@ Among those of special interest are:
    responsible for wiring and securing virtual interfaces (usually both
    compute and network nodes).
 #. Layer3 agent that runs on network node and provides east-west and
-   north-south routing plus some advanced services such as VPNaaS.
+   north-south routing plus some advanced services such as FWaaS or VPNaaS.
 
 Configuration options
 ~~~~~~~~~~~~~~~~~~~~~

doc/source/admin/fwaas-v2-scenario.rst

@@ -0,0 +1,129 @@
+Firewall-as-a-Service (FWaaS) v2 scenario
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+
+   Firewall v2 has no support for OVN currently.
+
+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_V2:fwaas_db:neutron_fwaas.services.firewall.service_drivers.agents.agents.FirewallAgentDriver:default
+
+      [fwaas]
+      agent_version = v2
+      driver = neutron_fwaas.services.firewall.service_drivers.agents.drivers.linux.iptables_fwaas_v2.IptablesFwaasDriver
+      enabled = True
+
+   .. note::
+
+      On Ubuntu and Centos, modify the ``[fwaas]`` section in the
+      ``/etc/neutron/fwaas_driver.ini`` file instead of
+      ``/etc/neutron/neutron.conf``.
+
+#. Configure the FWaaS plugin for the L3 agent.
+
+   In the ``AGENT`` section of ``l3_agent.ini``, make sure the FWaaS v2
+   extension is loaded:
+
+   .. code-block:: ini
+
+      [AGENT]
+      extensions = fwaas_v2
+
+#. Configure the ML2 plugin agent extension.
+
+   Add the following statements to ``ml2_conf.ini``, this file is usually
+   located at ``/etc/neutron/plugins/ml2/ml2_conf.ini``:
+
+   .. code-block:: ini
+
+      [agent]
+      extensions = fwaas_v2
+
+      [fwaas]
+      firewall_l2_driver = noop
+
+#. Create the required tables in the database:
+
+   .. code-block:: console
+
+      # neutron-db-manage --subproject neutron-fwaas upgrade head
+
+#. Restart the ``neutron-l3-agent``, ``neutron-openvswitch-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
+
+      $ openstack firewall group 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
+
+      $ openstack firewall group policy create --firewall-rule \
+        "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
+   <https://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 group:
+
+   .. code-block:: console
+
+      $ openstack firewall group create --ingress-firewall-policy \
+        "FIREWALL_POLICY_IDS_OR_NAMES" --egress-firewall-policy \
+        "FIREWALL_POLICY_IDS_OR_NAMES" --port "PORT_IDS_OR_NAMES"
+
+   Separate firewall policy IDs or names with spaces. The direction in which you
+   specify the policies is important.
+
+   .. note::
+
+      The firewall remains in PENDING\_CREATE state until you create a
+      Networking router and attach an interface to it.

doc/source/admin/fwaas.rst

@@ -0,0 +1,58 @@
+Firewall-as-a-Service (FWaaS)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Firewall-as-a-Service (FWaaS) plug-in applies firewalls to
+OpenStack objects such as projects, routers, and router ports.
+
+The central concepts with OpenStack firewalls are the notions of a firewall
+policy and a firewall rule. A policy is an ordered collection of rules. A rule
+specifies a collection of attributes (such as port ranges, protocol, and IP
+addresses) that constitute match criteria and an action to take (allow or deny)
+on matched traffic. A policy can be made public, so it can be shared across
+projects.
+
+Firewalls are implemented in various ways, depending on the driver used. For
+example, an iptables driver implements firewalls using iptable rules. An
+OpenVSwitch driver implements firewall rules using flow entries in flow tables.
+A Cisco firewall driver manipulates NSX devices.
+
+FWaaS v2
+--------
+
+The newer FWaaS implementation, v2, provides a much more granular service.
+The notion of a firewall has been replaced with firewall group to indicate
+that a firewall consists of two policies: an ingress policy and an egress
+policy. A firewall group is applied not at the router level (all ports on a
+router) but at the port level. Currently, router ports can be specified. For
+Ocata, VM ports can also be specified.
+
+FWaaS v1
+--------
+
+FWaaS v1 was deprecated in the Newton cycle and removed entirely in the Stein
+cycle.
+
+FWaaS Feature Matrix
+---------------------
+
+The following table shows FWaaS v2 features.
+
++------------------------------------------+-----------+
+| Feature                                  | Supported |
++==========================================+===========+
+| Supports L3 firewalling for routers      | NO*       |
++------------------------------------------+-----------+
+| Supports L3 firewalling for router ports | YES       |
++------------------------------------------+-----------+
+| Supports L2 firewalling (VM ports)       | YES       |
++------------------------------------------+-----------+
+| CLI support                              | YES       |
++------------------------------------------+-----------+
+| Horizon support                          | YES       |
++------------------------------------------+-----------+
+
+\* A firewall group can be applied to all ports on a given router in order to
+effect this.
+
+For further information, see the
+`FWaaS v2 configuration guide <./fwaas-v2-scenario.html>`_.

doc/source/admin/intro-os-networking.rst

@@ -372,3 +372,9 @@ The Load-Balancer-as-a-Service (LBaaS) API provisions and configures
 load balancers. The reference implementation is based on the HAProxy
 software load balancer. See the `Octavia project
 <https://docs.openstack.org/octavia/latest/>`_ for more information.
+
+FWaaS
+^^^^^
+
+The Firewall-as-a-Service (FWaaS) API allows to apply firewalls to OpenStack
+objects such as projects, routers, and router ports.

doc/source/admin/intro.rst

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

doc/source/admin/misc.rst

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

doc/source/contributor/internals/policy.rst

@@ -379,14 +379,14 @@ oslo.policy, so we cannot determine which projects are neutron related
 projects, so the second entry point is required.
 
 The recommended entry point name is a repository name: For example,
-'networking-sfc' for SFC:
+'neutron-fwaas' for FWaaS and 'networking-sfc' for SFC:
 
 .. code-block:: none
 
    oslo.policy.policies =
-       neutron-sfc = neutron_sfc.policies:list_rules
+       neutron-fwaas = neutron_fwaas.policies:list_rules
    neutron.policies =
-       neutron-sfc = neutron_sfc.policies:list_rules
+       neutron-fwaas = neutron_fwaas.policies:list_rules
 
 Except registering the ``neutron.policies`` entry point, other steps to be done
 in each neutron related project for policy-in-code support are same for all

doc/source/contributor/internals/service_extensions.rst

@@ -30,10 +30,6 @@ Historically, Neutron supported the following advanced services:
 #. **VPNaaS** (*VPN-as-a-Service*): derives from L3 agent to add
    VPNaaS functionality.
 
-.. note::
-
-   neutron-fwaas is deprecated and no more maintained!
-
 Starting with the Kilo release, these services are split into separate
 repositories, and more extensions are being developed as well. Service
 plugins are a clean way of adding functionality in a cohesive manner

doc/source/contributor/internals/services_and_agents.rst

@@ -37,7 +37,7 @@ services. Among those of special interest:
    responsible for wiring and securing virtual interfaces (usually both Compute
    and Network nodes).
 #. Layer3 agent that runs on Network node and provides East-West and
-   North-South routing plus some advanced services such as VPNaaS.
+   North-South routing plus some advanced services such as FWaaS or VPNaaS.
 
 For the purpose of this document, we call all services, servers and agents that
 run on any node as just "services".

doc/source/contributor/policies/blueprints.rst

@@ -26,7 +26,7 @@ Sub-Projects and Specs
 
 The `neutron-specs <http://opendev.org/openstack/neutron-specs>`_
 repository is only meant for specs from Neutron itself, and the advanced
-services repositories as well. This includes VPNaaS for example. Other
+services repositories as well. This includes FWaaS and VPNaaS. Other
 sub-projects are encouraged to fold their specs into their own devref code
 in their sub-project gerrit repositories. Please see additional comments
 in the Neutron teams :ref:`section <specs-core-reviewer-team>`

doc/source/contributor/policies/bugs.rst

@@ -3,7 +3,7 @@
 Neutron Bugs
 ============
 
-Neutron (client, core, VPNaaS) maintains all of its bugs in the following
+Neutron (client, core, FwaaS, VPNaaS) maintains all of its bugs in the following
 Launchpad projects:
 
 * `Launchpad Neutron <https://bugs.launchpad.net/neutron>`_

doc/source/contributor/testing/template_model_sync_test.rst

@@ -69,6 +69,8 @@ names, which were moved out of Neutron: ::
 
  VPNAAS_TABLES = [...]
 
+ FWAAS_TABLES = [...]
+
  # Arista ML2 driver Models moved to openstack/networking-arista
  REPO_ARISTA_TABLES = [...]
 
@@ -77,7 +79,7 @@ names, which were moved out of Neutron: ::
 
  ...
 
- TABLES = (VPNAAS_TABLES + ...
+ TABLES = (FWAAS_TABLES + VPNAAS_TABLES + ...
            + REPO_ARISTA_TABLES + REPO_CISCO_TABLES)
 
 

doc/source/install/concepts.rst

@@ -49,4 +49,5 @@ Each plug-in that Networking uses has its own concepts. While not vital
 to operating the VNI and OpenStack environment, understanding these
 concepts can help you set up Networking. All Networking installations
 use a core plug-in and a security group plug-in (or just the No-Op
-security group plug-in).
+security group plug-in). Additionally, Firewall-as-a-Service (FWaaS)
+is available.

doc/source/install/overview.rst

@@ -147,8 +147,8 @@ infrastructure.
 .. warning::
 
    This option lacks support for self-service (private) networks, layer-3
-   (routing) services, and advanced services such as LoadBalancer-as-a-Service
-   (Octavia).
+   (routing) services, and advanced services such as FireWall-as-a-Service
+   (FWaaS).
    Consider the self-service networks option below if you desire these features.
 
 .. _figure-network1-services:
@@ -167,7 +167,7 @@ self-service networks using overlay segmentation methods such
 as Virtual Extensible LAN (VXLAN). Essentially, it routes
 virtual networks to physical networks using Network Address
 Translation (NAT). Additionally, this option provides the foundation for
-advanced services such as LoadBalancer-as-a-service.
+advanced services such as FWaaS.
 
 The OpenStack user can create virtual networks without the knowledge
 of underlying infrastructure on the data network. This can also include