diff options
Diffstat (limited to 'docs/configuration')
| -rw-r--r-- | docs/configuration/firewall/bridge.rst | 219 | ||||
| -rw-r--r-- | docs/configuration/firewall/global-options.rst | 5 | ||||
| -rw-r--r-- | docs/configuration/firewall/index.rst | 30 |
3 files changed, 177 insertions, 77 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 diff --git a/docs/configuration/firewall/global-options.rst b/docs/configuration/firewall/global-options.rst index 87fb755d..60addbe9 100644 --- a/docs/configuration/firewall/global-options.rst +++ b/docs/configuration/firewall/global-options.rst @@ -53,6 +53,11 @@ Configuration addressed to itself at all, no matter where it comes from or whether more specific rules are being applied to accept them. +.. cfgcmd:: set firewall global-options apply-to-bridged-traffic [ipv4 | ipv6] + + Use these commands to also use IPv4, or IPv6 firewall rules for bridged + traffic + .. cfgcmd:: set firewall global-options broadcast-ping [enable | disable] This setting enables or disables the response to icmp broadcast diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst index 58e3463b..3d1d1c08 100644 --- a/docs/configuration/firewall/index.rst +++ b/docs/configuration/firewall/index.rst @@ -92,14 +92,32 @@ packet is processed at the **IP Layer**: destination...``. If the interface where the packet was received is part of a bridge, then -the packet is processed at the **Bridge Layer**, which contains a basic setup for -bridge filtering: +the packet is processed at the **Bridge Layer**: + + * **Prerouting (Bridge)**: all packets that are received by the bridge are + processed in this stage, regardless of the destination of the packet. + First filters can be applied here, and/or also configure rules for + ignoring connection tracking system, and also apply policy routing using + ``set`` option while defining the rule. The relevant configuration that + acts in: + + * ``set firewall bridge prerouting filter ...``. * **Forward (Bridge)**: stage where traffic that is trespassing through the bridge is filtered and controlled: * ``set firewall bridge forward filter ...``. + * **Input (Bridge)**: stage where traffic destined for the bridge itself can + be filtered and controlled: + + * ``set firewall bridge input filter ...``. + + * **Output (Bridge)**: stage where traffic that originates from the bridge + itself can be filtered and controlled: + + * ``set firewall bridge output filter ...``. + The main structure of the VyOS firewall CLI is shown next: .. code-block:: none @@ -108,6 +126,14 @@ The main structure of the VyOS firewall CLI is shown next: * bridge - forward + filter + - input + + filter + - output + + filter + - prerouting + + filter + - name + + custom_name * flowtable - custom_flow_table + ... |