neutron-fwaas — Summary

Reverse-specification of neutron-fwaas — branch stable/2026.2

• Repository: https://opendev.org/openstack/neutron-fwaas (local clone neutron-fwaas/) — specified branch: stable/2026.2 @ 5303a4deed1e — analysed on: 2026-10-28
• Other repositories cited: neutron-lib: = neutron-lib stable/2026.2 @ 1ee72052251a (API definitions, exceptions); neutron: = neutron stable/2026.2 @ eef1a0f7ee36 (API controller, error translation, OVN helpers); clients in 07.
• Scope: the whole project. API (FWaaS v2), service plugin, both service drivers (OVN, the OpenKeel priority, and agent/RPC), the L3 and L2 agent extensions, the OVN DB sync plugin, FWaaS logging, errors, interactions, scenarios, plus the rewrite pack (step 8). No change history (step 7), as agreed.

Overview

neutron-fwaas adds Firewall-as-a-Service v2 to Neutron: firewall rules (protocol, addresses, ports, allow/deny/reject), ordered into policies, applied through firewall groups to router interface ports (L3) or VM ports (L2).

It has no process of its own. Its components are:

• a Neutron service plugin firewall_v2 (neutron_fwaas/services/firewall/fwaas_plugin_v2.py:42), which serves the API through Neutron's extension framework under /v2.0/fwaas/;
• a pluggable service driver, chosen by [service_providers]:
  • the OVN driver (neutron_fwaas/services/firewall/service_drivers/ovn/firewall_l3_driver.py:31) maps each group to an OVN Northbound Port_Group holding the router interfaces, and each rule to a stateless ACL. It works synchronously in the API request, without agents, and supports router ports only;
  • the agent driver (neutron_fwaas/services/firewall/service_drivers/agents/agents.py:162) casts the groups over RabbitMQ to extensions of the L3 agent (iptables + conntrack in router namespaces) and of the OVS agent (OpenFlow tables 64–69 for VM ports), which report the status back;
• a sync plugin for neutron-ovn-db-sync-util.

All state lives in six tables of the Neutron database. A per-project default firewall group is created lazily, including on GET list calls.

Architecture

flowchart LR
  client[Client / OSC / SDK / Skyline] -->|HTTPS REST /v2.0/fwaas| api[neutron-server<br/>FirewallPluginV2]
  api -->|SQL| db[(MariaDB<br/>firewall_*_v2)]
  api -->|"OVN driver: OVSDB txn<br/>Port_Group + ACL"| nb[(OVN NB DB)]
  api -->|"agent driver: AMQP cast fanout<br/>topic firewall_agent"| mq{{RabbitMQ}}
  mq --> l3[neutron-l3-agent<br/>fwaas_v2 ext: iptables]
  mq --> l2[neutron-openvswitch-agent<br/>fwaas_v2 ext: OVS flows]
  l3 -->|"AMQP call q-firewall-plugin<br/>set_firewall_group_status"| api
  l2 -->|AMQP call| api
  sync[neutron-ovn-db-sync-util<br/>neutron_fwaas_nb_sync] -->|SQL read| db
  sync -->|OVSDB repair| nb
  api -->|notifications firewall_*.create.end| mq

Processes

External dependencies

Key figures

• REST: 17 operations on 3 resources (15 CRUD + 2 member actions), 26 policy rules, 3 quotas.
• Non-HTTP triggers: 5 RPC endpoints on the server, 3 fanout cast handlers on each agent extension (L3 and L2), 2 L3 router hooks, 2 L2 port hooks, 3 callback subscriptions, 1 sync plugin. 0 periodic tasks, 0 OVSDB event handlers.
• Exceptions: 24 FWaaS exceptions from neutron-lib (22 raised) and 13 defined in the repository.
• Tables: 6, plus the Neutron standardattributes, tags and ports they reference.
• Conformance data: 943 vectors replayed against the original (67 + 868 OVN ACL, 8 iptables), all passing; 691 HTTP exchanges from 135 passing API tests.

Points of attention

1. OVN allow rules are stateless (allow-stateless, neutron_fwaas/services/firewall/service_drivers/ovn/constants.py:22): return traffic needs explicit rules in the other direction, unlike the iptables driver, which accepts RELATED/ESTABLISHED.
2. Protocols without an OVN mapping match everything: gre, ah, esp, vrrp… are accepted by the API, but the OVN driver writes no protocol clause (neutron_fwaas/services/firewall/service_drivers/ovn/acl.py:82). A "deny gre" rule drops all IP traffic of that version at its priority.
3. **OVN ignores admin_state_up** and supports router ports only: VM ports are refused with 409, and the automatic attachment of new VM ports to the default group never runs on OVN.
4. GET list calls write: they create the project's default group, policies and rules if missing (neutron_fwaas/db/firewall/v2/firewall_db_v2.py:643). So does the agent RPC get_firewall_groups_for_project.
5. OVN writes are not transactional with the DB: they happen inside the request (pre/post-commit hooks within the plugin transaction). An OVSDB failure rolls the DB back, but not the OVSDB transactions already committed. The only repair is the manual neutron-ovn-db-sync-util --sync_mode repair, which does not remove stale ACLs or ports, and deletes the default group's Port_Group.
6. **Agent driver can stay PENDING_* forever** if no agent answers: services_sync_needed is set but process_services_sync is never called. Every update then returns 409 FirewallGroupInPendingState.
7. Misleading statuses: FirewallPolicyConflict, FirewallRuleSharingConflict and MechanismDriverNotFound are 404s, and the "default policy" update error says "Firewall Group".
8. **standard-attr-fwaas-v2 is not advertised** (extension class name mismatch, seen at run time), although the standard attributes are returned.
9. Priority overflow above 999 rules per policy (2000 - position reaches the default drops at 1001); bounded in practice by the rule quota (100).
10. Concurrency: the policy rule list and the default group's ports are read-modify-write without locks, so concurrent insert_rule calls, or concurrent VM bindings (agent driver), can lose an update [inferred].
11. **FirewallRuleConflict reveals another project's id** in its message.

Blind spots / [inferred]

• No live system: OVN behaviour is derived from the code, the OVN driver unit tests (mocked NB IDL) and replayed vectors. The OVSDB transaction sequence and the real ovsdbapp pg_acl_add row contents were not observed against an NB DB. Points marked [inferred] in 01–05 (transaction joining, rollback effects, concurrent losses) were reasoned from the code.
• Agent path: the OVS L2 driver (1022 lines of OpenFlow programming, neutron_fwaas/services/firewall/service_drivers/agents/drivers/linux/l2/openvswitch_firewall/firewall.py:216) and the NFLOG logging driver are summarised, not specified flow by flow. Both are irrelevant for an OVN/Kube-OVN target.
• Neutron generic behaviour (pagination, sorting, field projection, filter handling, quota engine, notifications) is cited, not re-specified; see reverse-spec-neutron/.
• Clients: neutron-fwaas-dashboard is not cloned in the workspace and was not read. Heat's firewall resources target FWaaS v1.
• Dynamic validation (capturing real NB transactions and RPC frames) was not done; it needs a running environment.

Source: reverse-spec-neutron-fwaas/00-summary_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.