summaryrefslogtreecommitdiff
path: root/docs/configuration/firewall/bridge.rst
diff options
context:
space:
mode:
authorNicolas Fort <nicolasfort1988@gmail.com>2024-07-31 09:56:05 -0300
committerNicolas Fort <nicolasfort1988@gmail.com>2024-08-02 08:21:03 -0300
commit014e88d74f21ec2a6e9ec591c94d56d084f0e3ec (patch)
tree9ccff7e425fbc0471db399a90c4a27e681dfd008 /docs/configuration/firewall/bridge.rst
parent6b2069ebb2ebaa97abe86ad22a4fbbddbb36723b (diff)
downloadvyos-documentation-014e88d74f21ec2a6e9ec591c94d56d084f0e3ec.tar.gz
vyos-documentation-014e88d74f21ec2a6e9ec591c94d56d084f0e3ec.zip
Extend firewall bridge documentation
Diffstat (limited to 'docs/configuration/firewall/bridge.rst')
-rw-r--r--docs/configuration/firewall/bridge.rst219
1 files changed, 144 insertions, 75 deletions
diff --git a/docs/configuration/firewall/bridge.rst b/docs/configuration/firewall/bridge.rst
index 2e3d3634..13fd0b42 100644
--- a/docs/configuration/firewall/bridge.rst
+++ b/docs/configuration/firewall/bridge.rst
@@ -6,8 +6,6 @@
Bridge Firewall Configuration
#############################
-.. note:: **Documentation under development**
-
********
Overview
********
@@ -28,29 +26,50 @@ of the general structure:
* bridge
- forward
+ filter
+ - input
+ + filter
+ - output
+ + filter
+ - prerouting
+ + filter
- name
+ custom_name
Traffic which is received by the router on an interface which is member of a
-bridge is processed on the **Bridge Layer**. A simplified packet flow diagram
-for this layer is shown next:
+bridge is processed on the **Bridge Layer**. Before the bridge decision is
+made, all packets are analyzed at **Prerouting**. First filters can be applied
+here, and also rules for ignoring connection tracking system can be configured.
+The relevant configuration that acts in **prerouting** is:
-.. figure:: /_static/images/firewall-bridge-packet-flow.png
+ * ``set firewall bridge prerouting filter ...``.
-For traffic that needs to be forwarded internally by the bridge, base chain is
-is **forward**, and it's base command for filtering is ``set firewall bridge
+For traffic that needs to be switched internally by the bridge, base chain is
+**forward**, and it's base command for filtering is ``set firewall bridge
forward filter ...``, which happens in stage 4, highlighted with red color.
+.. figure:: /_static/images/firewall-bridge-forward.png
+
+For traffic destined to the router itself, or that needs to be routed (assuming
+a layer3 bridge is configured), the base chain is **input**, the base command
+is ``set firewall bridge input filter ...`` and the path is:
+
+.. figure:: /_static/images/firewall-bridge-input.png
+
+If it's not dropped, then the packet is sent to **IP Layer**, and will be
+processed by the **IP Layer** firewall: IPv4 or IPv6 ruleset. Check once again
+the :doc:`general packet flow diagram</configuration/firewall/index>` if
+needed.
+
+And for traffic that originates from the bridge itself, the base chain is
+**output**, base command is ``set firewall bridge output filter ...``, and
+the path is:
+
+.. figure:: /_static/images/firewall-bridge-output.png
+
Custom bridge firewall chains can be created with the command ``set firewall bridge
name <name> ...``. In order to use such custom chain, a rule with action jump,
and the appropriate target should be defined in a base chain.
-.. note:: **Layer 3 bridge**:
- When an IP address is assigned to the bridge interface, and if traffic
- is sent to the router to this IP (for example using such IP as
- default gateway), then rules defined for **bridge firewall** won't
- match, and firewall analysis continues at **IP layer**.
-
************
Bridge Rules
************
@@ -82,8 +101,17 @@ In firewall bridge rules, the action can be:
* ``queue``: Enqueue packet to userspace.
+ * ``notrack``: ignore connection tracking system. This action is only
+ available in prerouting chain.
+
.. cfgcmd:: set firewall bridge forward filter rule <1-999999> action
[accept | continue | drop | jump | queue | return]
+.. cfgcmd:: set firewall bridge input filter rule <1-999999> action
+ [accept | continue | drop | jump | queue | return]
+.. cfgcmd:: set firewall bridge output filter rule <1-999999> action
+ [accept | continue | drop | jump | queue | return]
+.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> action
+ [accept | continue | drop | jump | notrack | queue | return]
.. cfgcmd:: set firewall bridge name <name> rule <1-999999> action
[accept | continue | drop | jump | queue | return]
@@ -92,42 +120,68 @@ In firewall bridge rules, the action can be:
.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
jump-target <text>
+.. cfgcmd:: set firewall bridge input filter rule <1-999999>
+ jump-target <text>
+.. cfgcmd:: set firewall bridge output filter rule <1-999999>
+ jump-target <text>
+.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999>
+ jump-target <text>
.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
jump-target <text>
+ If action is set to ``queue``, use next command to specify the queue
+ target. Range is also supported:
+
.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
queue <0-65535>
+.. cfgcmd:: set firewall bridge input filter rule <1-999999>
+ queue <0-65535>
+.. cfgcmd:: set firewall bridge output filter rule <1-999999>
+ queue <0-65535>
+.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999>
+ queue <0-65535>
.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
queue <0-65535>
- To be used only when action is set to ``queue``. Use this command to specify
- the queue target to use. Queue range is also supported.
+ Also, if action is set to ``queue``, use next command to specify the queue
+ options. Possible options are ``bypass`` and ``fanout``:
.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
queue-options bypass
+.. cfgcmd:: set firewall bridge input filter rule <1-999999>
+ queue-options bypass
+.. cfgcmd:: set firewall bridge output filter rule <1-999999>
+ queue-options bypass
+.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999>
+ queue-options bypass
.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
queue-options bypass
- To be used only when action is set to ``queue``. Use this command to let
- packet go through firewall when no userspace software is connected to the
- queue.
-
.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
queue-options fanout
+.. cfgcmd:: set firewall bridge input filter rule <1-999999>
+ queue-options fanout
+.. cfgcmd:: set firewall bridge output filter rule <1-999999>
+ queue-options fanout
+.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999>
+ queue-options fanout
.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
queue-options fanout
- To be used only when action is set to ``queue``. Use this command to
- distribute packets between several queues.
-
Also, **default-action** is an action that takes place whenever a packet does
not match any rule in its' chain. For base chains, possible options for
**default-action** are **accept** or **drop**.
.. cfgcmd:: set firewall bridge forward filter default-action
[accept | drop]
+.. cfgcmd:: set firewall bridge input filter default-action
+ [accept | drop]
+.. cfgcmd:: set firewall bridge output filter default-action
+ [accept | drop]
+.. cfgcmd:: set firewall bridge prerouting filter default-action
+ [accept | drop]
.. cfgcmd:: set firewall bridge name <name> default-action
- [accept | continue | drop | jump | queue | return]
+ [accept | continue | drop | jump | reject | return]
This sets the default action of the rule-set if a packet does not match
any of the rules in that chain. If default-action is set to ``jump``, then
@@ -152,12 +206,18 @@ Logging can be enable for every single firewall rule. If enabled, other
log options can be defined.
.. cfgcmd:: set firewall bridge forward filter rule <1-999999> log
+.. cfgcmd:: set firewall bridge input filter rule <1-999999> log
+.. cfgcmd:: set firewall bridge output filter rule <1-999999> log
+.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> log
.. cfgcmd:: set firewall bridge name <name> rule <1-999999> log
Enable logging for the matched packet. If this configuration command is not
present, then the log is not enabled.
.. cfgcmd:: set firewall bridge forward filter default-log
+.. cfgcmd:: set firewall bridge input filter default-log
+.. cfgcmd:: set firewall bridge output filter default-log
+.. cfgcmd:: set firewall bridge prerouting filter default-log
.. cfgcmd:: set firewall bridge name <name> default-log
Use this command to enable the logging of the default action on
@@ -166,6 +226,15 @@ log options can be defined.
.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
log-options level [emerg | alert | crit | err | warn | notice
| info | debug]
+.. cfgcmd:: set firewall bridge input filter rule <1-999999>
+ log-options level [emerg | alert | crit | err | warn | notice
+ | info | debug]
+.. cfgcmd:: set firewall bridge output filter rule <1-999999>
+ log-options level [emerg | alert | crit | err | warn | notice
+ | info | debug]
+.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999>
+ log-options level [emerg | alert | crit | err | warn | notice
+ | info | debug]
.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
log-options level [emerg | alert | crit | err | warn | notice
| info | debug]
@@ -174,6 +243,12 @@ log options can be defined.
.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
log-options group <0-65535>
+.. cfgcmd:: set firewall bridge input filter rule <1-999999>
+ log-options group <0-65535>
+.. cfgcmd:: set firewall bridge output filter rule <1-999999>
+ log-options group <0-65535>
+.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999>
+ log-options group <0-65535>
.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
log-options group <0-65535>
@@ -182,6 +257,12 @@ log options can be defined.
.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
log-options snapshot-length <0-9000>
+.. cfgcmd:: set firewall bridge input filter rule <1-999999>
+ log-options snapshot-length <0-9000>
+.. cfgcmd:: set firewall bridge output filter rule <1-999999>
+ log-options snapshot-length <0-9000>
+.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999>
+ log-options snapshot-length <0-9000>
.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
log-options snapshot-length <0-9000>
@@ -190,6 +271,12 @@ log options can be defined.
.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
log-options queue-threshold <0-65535>
+.. cfgcmd:: set firewall bridge input filter rule <1-999999>
+ log-options queue-threshold <0-65535>
+.. cfgcmd:: set firewall bridge output filter rule <1-999999>
+ log-options queue-threshold <0-65535>
+.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999>
+ log-options queue-threshold <0-65535>
.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
log-options queue-threshold <0-65535>
@@ -206,6 +293,19 @@ For reference, a description can be defined for every defined custom chain.
Provide a rule-set description to a custom firewall chain.
+.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
+ description <text>
+.. cfgcmd:: set firewall bridge input filter rule <1-999999>
+ description <text>
+.. cfgcmd:: set firewall bridge output filter rule <1-999999>
+ description <text>
+.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999>
+ description <text>
+.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
+ description <text>
+
+ Provide a description for each rule.
+
Rule Status
===========
@@ -213,6 +313,9 @@ When defining a rule, it is enabled by default. In some cases, it is useful to
just disable the rule, rather than removing it.
.. cfgcmd:: set firewall bridge forward filter rule <1-999999> disable
+.. cfgcmd:: set firewall bridge input filter rule <1-999999> disable
+.. cfgcmd:: set firewall bridge output filter rule <1-999999> disable
+.. cfgcmd:: set firewall bridge prerouting filter rule <1-999999> disable
.. cfgcmd:: set firewall bridge name <name> rule <1-999999> disable
Command for disabling a rule but keep it in the configuration.
@@ -221,65 +324,31 @@ Matching criteria
=================
There are a lot of matching criteria against which the packet can be tested.
+Please refer to :doc:`IPv4</configuration/firewall/ipv4>` and
+:doc:`IPv6</configuration/firewall/ipv6>` matching criteria for more details.
-.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
- destination mac-address <mac-address>
-.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
- destination mac-address <mac-address>
-.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
- source mac-address <mac-address>
-.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
- source mac-address <mac-address>
+Since bridges operates at layer 2, both matchers for IPv4 and IPv6 are
+supported in bridge firewall configuration. Same applies for firewall groups.
- Match criteria based on source and/or destination mac-address.
+Use IP firewall
+===============
-.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
- inbound-interface name <iface>
-.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
- inbound-interface name <iface>
-
- Match based on inbound interface. Wildcard ``*`` can be used.
- For example: ``eth2*``. Prepending character ``!`` for inverted matching
- criteria is also supported. For example ``!eth2``
-
-.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
- inbound-interface group <iface_group>
-.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
- inbound-interface group <iface_group>
-
- Match based on inbound interface group. Prepending character ``!`` for
- inverted matching criteria is also supported. For example ``!IFACE_GROUP``
-
-.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
- outbound-interface name <iface>
-.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
- outbound-interface name <iface>
+By default, for switched traffic, only the rules defined under ``set firewall
+bridge`` are applied. There are two global-options that can be configured in
+order to force deeper analysis of the packet on the IP layer. These options
+are:
- Match based on outbound interface. Wildcard ``*`` can be used.
- For example: ``eth2*``. Prepending character ``!`` for inverted matching
- criteria is also supported. For example ``!eth2``
+.. cfgcmd:: set firewall global-options apply-to-bridged-traffic ipv4
-.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
- outbound-interface group <iface_group>
-.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
- outbound-interface group <iface_group>
-
- Match based on outbound interface group. Prepending character ``!`` for
- inverted matching criteria is also supported. For example ``!IFACE_GROUP``
+ This command enables the IPv4 firewall for bridged traffic. If this
+ options is used, then packet will also be parsed by rules defined in ``set
+ firewall ipv4 ...``
-.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
- vlan id <0-4096>
-.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
- vlan id <0-4096>
-
- Match based on vlan ID. Range is also supported.
-
-.. cfgcmd:: set firewall bridge forward filter rule <1-999999>
- vlan priority <0-7>
-.. cfgcmd:: set firewall bridge name <name> rule <1-999999>
- vlan priority <0-7>
+.. cfgcmd:: set firewall global-options apply-to-bridged-traffic ipv6
- Match based on vlan priority(pcp). Range is also supported.
+ This command enables the IPv6 firewall for bridged traffic. If this
+ options is used, then packet will also be parsed by rules defined in ``set
+ firewall ipv6 ...``
***********************
Operation-mode Firewall