vyos/vyos-documentation
1
0
Fork 0
mirror of https://github.com/vyos/vyos-documentation.git synced 2025-10-26 08:41:46 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1144 from nicolas-fort/fwall-nat-update

Browse Source 
Fwall nat update
This commit is contained in:
Robert Göhler 2023-11-12 21:43:16 +01:00 committed by GitHub
commit f59bff9cdd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
15 changed files with 2929 additions and 1597 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/_static/images/firewall-bridge-packet-flow.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

BIN
docs/_static/images/firewall-flowtable-packet-flow.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 47 KiB

BIN
docs/_static/images/firewall-fwd-packet-flow.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 39 KiB

BIN
docs/_static/images/firewall-gral-packet-flow.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 40 KiB

BIN
docs/_static/images/firewall-input-packet-flow.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 55 KiB

42
docs/configuration/firewall/bridge.rst Normal file
View File

@ -0,0 +1,42 @@
:lastproofread: 2023-11-08
.. _firewall-configuration:
#############################
Bridge Firewall Configuration
#############################
.. note:: **Documentation under development**
********
Overview
********
In this section there's useful information of all firewall configuration that
can be done regarding bridge, and appropiate op-mode commands.
Configuration commands covered in this section:
.. cfgcmd:: set firewall bridge ...
From main structure defined in :doc:`Firewall Overview</configuration/firewall/index>`
in this section you can find detailed information only for the next part
of the general structure:
.. code-block:: none
- set firewall
* bridge
- forward
+ 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:
.. figure:: /_static/images/firewall-bridge-packet-flow.png
For traffic that needs to be forwared internally by the bridge, base chain is
is **forward**, and it's base command for filtering is ``set firewall bridge
forward filter ...``

52
docs/configuration/firewall/flowtables.rst Normal file
View File

@ -0,0 +1,52 @@
:lastproofread: 2023-11-08
.. _firewall-flowtables-configuration:
###################ä#############
Flowtables Firewall Configuration
#################################
.. note:: **Documentation under development**
********
Overview
********
In this section there's useful information of all firewall configuration that
can be done regarding flowtables
.. cfgcmd:: set firewall flowtables ...
From main structure defined in :doc:`Firewall Overview</configuration/firewall/index>`
in this section you can find detailed information only for the next part
of the general structure:
.. code-block:: none
- set firewall
* flowtable
- custom_flow_table
+ ...
Flowtables allows you to define a fastpath through the flowtable datapath.
The flowtable supports for the layer 3 IPv4 and IPv6 and the layer 4 TCP
and UDP protocols.
.. figure:: /_static/images/firewall-flowtable-packet-flow.png
Once the first packet of the flow successfully goes through the IP forwarding
path (black circles path), from the second packet on, you might decide to
offload the flow to the flowtable through your ruleset. The flowtable
infrastructure provides a rule action that allows you to specify when to add
a flow to the flowtable (On forward filtering, red circle number 6)
A packet that finds a matching entry in the flowtable (flowtable hit) is
transmitted to the output netdevice, hence, packets bypass the classic IP
forwarding path and uses the **Fast Path** (orange circles path). The visible
effect is that you do not see these packets from any of the Netfilter
hooks coming after ingress. In case that there is no matching entry in the
flowtable (flowtable miss), the packet follows the classic IP forwarding path.
.. note:: **Flowtable Reference:**
https://docs.kernel.org/networking/nf_flowtable.html

1544
docs/configuration/firewall/general.rst
View File

File diff suppressed because it is too large Load Diff

117
docs/configuration/firewall/global-options.rst Normal file
View File

@ -0,0 +1,117 @@
:lastproofread: 2023-11-07
.. _firewall-global-options-configuration:
#####################################
Global Options Firewall Configuration
#####################################
********
Overview
********
Some firewall settings are global and have an affect on the whole system.
In this section there's useful information about these global-options that can
be configured using vyos cli.
Configuration commands covered in this section:
.. cfgcmd:: set firewall global-options ...
*************
Configuration
*************
.. cfgcmd:: set firewall global-options all-ping [enable | disable]
By default, when VyOS receives an ICMP echo request packet destined for
itself, it will answer with an ICMP echo reply, unless you avoid it
through its firewall.
With the firewall you can set rules to accept, drop or reject ICMP in,
out or local traffic. You can also use the general **firewall all-ping**
command. This command affects only to LOCAL (packets destined for your
VyOS system), not to IN or OUT traffic.
.. note:: **firewall global-options all-ping** affects only to LOCAL
and it always behaves in the most restrictive way
.. code-block:: none
set firewall global-options all-ping enable
When the command above is set, VyOS will answer every ICMP echo request
addressed to itself, but that will only happen if no other rule is
applied dropping or rejecting local echo requests. In case of conflict,
VyOS will not answer ICMP echo requests.
.. code-block:: none
set firewall global-options all-ping disable
When the command above is set, VyOS will answer no ICMP echo request
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 broadcast-ping [enable | disable]
This setting enable or disable the response of icmp broadcast
messages. The following system parameter will be altered:
* ``net.ipv4.icmp_echo_ignore_broadcasts``
.. cfgcmd:: set firewall global-options ip-src-route [enable | disable]
.. cfgcmd:: set firewall global-options ipv6-src-route [enable | disable]
This setting handle if VyOS accept packets with a source route
option. The following system parameter will be altered:
* ``net.ipv4.conf.all.accept_source_route``
* ``net.ipv6.conf.all.accept_source_route``
.. cfgcmd:: set firewall global-options receive-redirects [enable | disable]
.. cfgcmd:: set firewall global-options ipv6-receive-redirects
[enable | disable]
enable or disable of ICMPv4 or ICMPv6 redirect messages accepted
by VyOS. The following system parameter will be altered:
* ``net.ipv4.conf.all.accept_redirects``
* ``net.ipv6.conf.all.accept_redirects``
.. cfgcmd:: set firewall global-options send-redirects [enable | disable]
enable or disable ICMPv4 redirect messages send by VyOS
The following system parameter will be altered:
* ``net.ipv4.conf.all.send_redirects``
.. cfgcmd:: set firewall global-options log-martians [enable | disable]
enable or disable the logging of martian IPv4 packets.
The following system parameter will be altered:
* ``net.ipv4.conf.all.log_martians``
.. cfgcmd:: set firewall global-options source-validation
[strict | loose | disable]
Set the IPv4 source validation mode.
The following system parameter will be altered:
* ``net.ipv4.conf.all.rp_filter``
.. cfgcmd:: set firewall global-options syn-cookies [enable | disable]
Enable or Disable if VyOS use IPv4 TCP SYN Cookies.
The following system parameter will be altered:
* ``net.ipv4.tcp_syncookies``
.. cfgcmd:: set firewall global-options twa-hazards-protection
[enable | disable]
Enable or Disable VyOS to be :rfc:`1337` conform.
The following system parameter will be altered:
* ``net.ipv4.tcp_rfc1337``

210
docs/configuration/firewall/groups.rst Normal file
View File

@ -0,0 +1,210 @@
:lastproofread: 2023-11-08
.. _firewall-groups-configuration:
###############
Firewall groups
###############
*************
Configuration
*************
Firewall groups represent collections of IP addresses, networks, ports,
mac addresses, domains or interfaces. Once created, a group can be referenced
by firewall, nat and policy route rules as either a source or destination
matcher, and/or as inbound/outbound in the case of interface group.
Address Groups
==============
In an **address group** a single IP address or IP address ranges are
defined.
.. cfgcmd:: set firewall group address-group <name> address [address |
address range]
.. cfgcmd:: set firewall group ipv6-address-group <name> address <address>
Define a IPv4 or a IPv6 address group
.. code-block:: none
set firewall group address-group ADR-INSIDE-v4 address 192.168.0.1
set firewall group address-group ADR-INSIDE-v4 address 10.0.0.1-10.0.0.8
set firewall group ipv6-address-group ADR-INSIDE-v6 address 2001:db8::1
.. cfgcmd:: set firewall group address-group <name> description <text>
.. cfgcmd:: set firewall group ipv6-address-group <name> description <text>
Provide a IPv4 or IPv6 address group description
Network Groups
==============
While **network groups** accept IP networks in CIDR notation, specific
IP addresses can be added as a 32-bit prefix. If you foresee the need
to add a mix of addresses and networks, the network group is
recommended.
.. cfgcmd:: set firewall group network-group <name> network <CIDR>
.. cfgcmd:: set firewall group ipv6-network-group <name> network <CIDR>
Define a IPv4 or IPv6 Network group.
.. code-block:: none
set firewall group network-group NET-INSIDE-v4 network 192.168.0.0/24
set firewall group network-group NET-INSIDE-v4 network 192.168.1.0/24
set firewall group ipv6-network-group NET-INSIDE-v6 network 2001:db8::/64
.. cfgcmd:: set firewall group network-group <name> description <text>
.. cfgcmd:: set firewall group ipv6-network-group <name> description <text>
Provide an IPv4 or IPv6 network group description.
Interface Groups
================
An **interface group** represents a collection of interfaces.
.. cfgcmd:: set firewall group interface-group <name> interface <text>
Define an interface group. Wildcard are accepted too.
.. code-block:: none
set firewall group interface-group LAN interface bond1001
set firewall group interface-group LAN interface eth3*
.. cfgcmd:: set firewall group interface-group <name> description <text>
Provide an interface group description
Port Groups
===========
A **port group** represents only port numbers, not the protocol. Port
groups can be referenced for either TCP or UDP. It is recommended that
TCP and UDP groups are created separately to avoid accidentally
filtering unnecessary ports. Ranges of ports can be specified by using
`-`.
.. cfgcmd:: set firewall group port-group <name> port
[portname | portnumber | startport-endport]
Define a port group. A port name can be any name defined in
/etc/services. e.g.: http
.. code-block:: none
set firewall group port-group PORT-TCP-SERVER1 port http
set firewall group port-group PORT-TCP-SERVER1 port 443
set firewall group port-group PORT-TCP-SERVER1 port 5000-5010
.. cfgcmd:: set firewall group port-group <name> description <text>
Provide a port group description.
MAC Groups
==========
A **mac group** represents a collection of mac addresses.
.. cfgcmd:: set firewall group mac-group <name> mac-address <mac-address>
Define a mac group.
.. code-block:: none
set firewall group mac-group MAC-G01 mac-address 88:a4:c2:15:b6:4f
set firewall group mac-group MAC-G01 mac-address 4c:d5:77:c0:19:81
.. cfgcmd:: set firewall group mac-group <name> description <text>
Provide a mac group description.
Domain Groups
=============
A **domain group** represents a collection of domains.
.. cfgcmd:: set firewall group domain-group <name> address <domain>
Define a domain group.
.. code-block:: none
set firewall group domain-group DOM address example.com
.. cfgcmd:: set firewall group domain-group <name> description <text>
Provide a domain group description.
********
Examples
********
As said before, once firewall groups are created, they can be referenced
either in firewall, nat, nat66 and/or policy-route rules.
Here is an example were multiple groups are created:
.. code-block:: none
set firewall group address-group SERVERS address 198.51.100.101
set firewall group address-group SERVERS address 198.51.100.102
set firewall group network-group TRUSTEDv4 network 192.0.2.0/30
set firewall group network-group TRUSTEDv4 network 203.0.113.128/25
set firewall group ipv6-network-group TRUSTEDv6 network 2001:db8::/64
set firewall group interface-group LAN interface eth2.2001
set firewall group interface-group LAN interface bon0
set firewall group port-group PORT-SERVERS port http
set firewall group port-group PORT-SERVERS port 443
set firewall group port-group PORT-SERVERS port 5000-5010
And next, some configuration example where groups are used:
.. code-block:: none
set firewall ipv4 input filter rule 10 action accept
set firewall ipv4 input filter rule 10 inbound-interface group !LAN
set firewall ipv4 forward filter rule 20 action accept
set firewall ipv4 forward filter rule 20 source group network-group TRUSTEDv4
set firewall ipv6 input filter rule 10 action accept
set firewall ipv6 input filter rule 10 source-group network-group TRUSTEDv6
set nat destination rule 101 inbound-interface group LAN
set nat destination rule 101 destination group address-group SERVERS
set nat destination rule 101 protocol tcp
set nat destination rule 101 destination group port-group PORT-SERVERS
set nat destination rule 101 translation address 203.0.113.250
set policy route PBR rule 201 destination group port-group PORT-SERVERS
set policy route PBR rule 201 protocol tcp
set policy route PBR rule 201 set table 15
**************
Operation-mode
**************
.. opcmd:: show firewall group <name>
Overview of defined groups. You see the type, the members, and where the
group is used.
.. code-block:: none
vyos@ZBF-15-CLean:~$ show firewall group
Firewall Groups
Name Type References Members
------------ ------------------ ---------------------- ----------------
SERVERS address_group nat-destination-101 198.51.100.101
198.51.100.102
LAN interface_group ipv4-input-filter-10 bon0
nat-destination-101 eth2.2001
TRUSTEDv6 ipv6_network_group ipv6-input-filter-10 2001:db8::/64
TRUSTEDv4 network_group ipv4-forward-filter-20 192.0.2.0/30
203.0.113.128/25
PORT-SERVERS port_group route-PBR-201 443
nat-destination-101 5000-5010
http
vyos@ZBF-15-CLean:~$

196
docs/configuration/firewall/index.rst
View File

@ -1,4 +1,4 @@
:lastproofread: 2023-09-17
:lastproofread: 2023-11-08
########
Firewall
@ -8,43 +8,164 @@ Firewall
Starting from VyOS 1.4-rolling-202308040557, a new firewall structure
can be found on all vyos installations.
.. note::
The legacy and zone-based firewall configuration options is not longer
supported. They are here for reference purposes only.
***************
Netfilter based
^^^^^^^^^^^^^^^
***************
With VyOS being based on top of Linux and its kernel, the Netfilter project
created the iptables and now the successor nftables for the Linux kernel to
work directly on the data flows. This now extends the concept of zone-based
security to allow for manipulating the data at multiple stages once accepted
by the network interface and the driver before being handed off to the
destination (e.g. a web server OR another device).
A simplified traffic flow, based on Netfilter packet flow, is shown next, in
order to have a full view and understanding of how packets are processed, and
what possible paths can take.
.. figure:: /_static/images/firewall-gral-packet-flow.png
Main notes regarding this packet flow and terminology used in VyOS firewall:
* **Bridge Port?**: choose appropiate path based on if interface were the
packet was received is part of a bridge, or not.
If interface were the packet was received isn't part of a bridge, then packet
is processed at the **IP Layer**:
* **Prerouting**: several actions can be done in this stage, and currently
these actions are defined in different parts in vyos configuration. Order
is important, and all these actions are performed before any actions
define under ``firewall`` section. Relevant configuration that acts in
this stage are:
* **Conntrack Ignore**: rules defined under ``set system conntrack ignore
[ipv4 | ipv6] ...``.
* **Policy Route**: rules defined under ``set policy [route | route6]
...``.
* **Destination NAT**: rules defined under ``set [nat | nat66]
destination...``.
* **Destination is the router?**: choose appropiate path based on
destination IP address. Transit forward continunes to **forward**,
while traffic that destination IP address is configured on the router
continues to **input**.
* **Input**: stage where traffic destinated to the router itself can be
filtered and controlled. This is where all rules for securing the router
should take place. This includes ipv4 and ipv6 filtering rules, defined
in:
* ``set firewall ipv4 input filter ...``.
* ``set firewall ipv6 input filter ...``.
* **Forward**: stage where transit traffic can be filtered and controlled.
This includes ipv4 and ipv6 filtering rules, defined in:
* ``set firewall ipv4 forward filter ...``.
* ``set firewall ipv6 forward filter ...``.
* **Output**: stage where traffic that is originated by the router itself
can be filtered and controlled. Bare in mind that this traffic can be a
new connection originted by a internal process running on VyOS router,
such as NTP, or can be a response to traffic received externaly through
**inputt** (for example response to an ssh login attempt to the router).
This includes ipv4 and ipv6 filtering rules, defined in:
* ``set firewall ipv4 input filter ...``.
* ``set firewall ipv6 output filter ...``.
* **Postrouting**: as in **Prerouting**, several actions defined in
different parts of VyOS configuration are performed in this
stage. This includes:
* **Source NAT**: rules defined under ``set [nat | nat66]
destination...``.
If interface were the packet was received is part of a bridge, then packet
is processed at the **Bridge Layer**, which contains a ver basic setup where
for bridge filtering:
* **Forward (Bridge)**: stage where traffic that is trasspasing through the
bridge is filtered and controlled:
* ``set firewall bridge forward filter ...``.
Main structure VyOS firewall cli is shown next:
.. code-block:: none
- set firewall
* bridge
- forward
+ filter
* flowtable
- custom_flow_table
+ ...
* global-options
+ all-ping
+ broadcast-ping
+ ...
* group
- address-group
- ipv6-address-group
- network-group
- ipv6-network-group
- interface-group
- mac-group
- port-group
- domain-group
* ipv4
- forward
+ filter
- input
+ filter
- output
+ filter
- name
+ custom_name
* ipv6
- forward
+ filter
- input
+ filter
- output
+ filter
- ipv6-name
+ custom_name
* zone
- custom_zone_name
+ ...
Please, refer to appropiate section for more information about firewall
configuration:
.. toctree::
:maxdepth: 1
:includehidden:
general
With VyOS being based on top of Linux and its kernel, the Netfilter project created
the iptables and now the successor nftables for the Linux kernel to work directly
on the data flows. This now extends the concept of zone-based security to allow
for manipulating the data at multiple stages once accepted by the network interface
and the driver before being handed off to the destination (e.g. a web server OR
another device).
To configure VyOS with the new :doc:`firewall configuration </configuration/firewall/general>`
The only stages VyOS will process as part of the firewall configuration is the
`forward` (F4 stage), `input` (L4 stage), and `output` (L5 stage). All the other
stages and steps are for reference and cant be manipulated through VyOS.
In this example image, a simplifed traffic flow is shown to help provide context
to the terms of `forward`, `input`, and `output` for the new firewall CLI format.
.. figure:: /_static/images/firewall-netfilter.png
global-options
groups
bridge
ipv4
ipv6
flowtables
zone
.. note:: **For more information**
of Netfilter hooks and Linux networking packet flows can be
found in `Netfilter-Hooks
<https://wiki.nftables.org/wiki-nftables/index.php/Netfilter_hooks>`_
***************
Legacy Firewall
^^^^^^^^^^^^^^^
***************
.. toctree::
:maxdepth: 1
:includehidden:
@ -55,7 +176,8 @@ Traditionally firewalls weere configured with the concept of data going in and
out of an interface. The router just listened to the data flowing through and
responding as required if it was directed at the router itself.
To configure VyOS with the :doc:`legacy firewall configuration </configuration/firewall/general-legacy>`
To configure VyOS with the
:doc:`legacy firewall configuration </configuration/firewall/general-legacy>`
As the example image below shows, the device was configured with rules blocking
inbound or outbound traffic on each interface.
@ -70,16 +192,18 @@ Zone-based firewall
zone
With zone-based firewalls a new concept was implemented, in addtion to the standard
in and out traffic flows, a local flow was added. This local was for traffic
originating and destined to the router itself. Which means additional rules were
required to secure the firewall itself from the network, in addition to the existing
inbound and outbound rules from the traditional concept above.
With zone-based firewalls a new concept was implemented, in addtion to the
standard in and out traffic flows, a local flow was added. This local was for
traffic originating and destined to the router itself. Which means additional
rules were required to secure the firewall itself from the network, in
addition to the existing inbound and outbound rules from the traditional
concept above.
To configure VyOS with the :doc:`zone-based firewall configuration </configuration/firewall/zone>`
To configure VyOS with the
:doc:`zone-based firewall configuration </configuration/firewall/zone>`
As the example image below shows, the device now needs rules to allow/block traffic
to or from the services running on the device that have open connections on that
interface.
As the example image below shows, the device now needs rules to allow/block
traffic to or from the services running on the device that have open
connections on that interface.
.. figure:: /_static/images/firewall-zonebased.png

1145
docs/configuration/firewall/ipv4.rst Normal file
View File

File diff suppressed because it is too large Load Diff

1167
docs/configuration/firewall/ipv6.rst Normal file
View File

File diff suppressed because it is too large Load Diff

45
docs/configuration/firewall/zone.rst
View File

@ -1,25 +1,44 @@
:lastproofread: 2022-09-14
:lastproofread: 2023-11-01
.. _firewall-zone:
################################
Zone Based Firewall (Deprecated)
################################
###################
Zone Based Firewall
###################
********
Overview
********
.. note:: Starting from VyOS 1.4-rolling-202308040557, a new firewall
structure can be found on all vyos instalations, and zone based firewall is
no longer supported. Documentation for most of the new firewall CLI can be
structure can be found on all vyos instalations. Zone based firewall was
removed in that version, but re introduced in VyOS 1.4 and 1.5. All
versions built after 2023-10-22 has this feature.
Documentation for most of the new firewall CLI can be
found in the `firewall
<https://docs.vyos.io/en/latest/configuration/firewall/general.html>`_
chapter. The legacy firewall is still available for versions before
1.4-rolling-202308040557 and can be found in the :ref:`firewall-legacy`
chapter. The examples in this section use the legacy firewall configuration
commands, since this feature has been removed in earlier releases.
1.4-rolling-202308040557 and can be found in the
:doc:`legacy firewall configuration </configuration/firewall/general-legacy>`
chapter.
.. note:: For latest releases, refer the `firewall (interface-groups)
<https://docs.vyos.io/en/latest/configuration/firewall/general.html#interface-groups>`_
main page to configure zone based rules. New syntax was introduced here
:vytask:`T5160`
In this section there's useful information of all firewall configuration that
is needed for zone-based firewall.
Configuration commands covered in this section:
.. cfgcmd:: set firewall zone ...
From main structure defined in
:doc:`Firewall Overview</configuration/firewall/index>`
in this section you can find detailed information only for the next part
of the general structure:
.. code-block:: none
- set firewall
* zone
- custom_zone_name
+ ...
In zone-based policy, interfaces are assigned to zones, and inspection policy
is applied to traffic moving between the zones and acted on according to

8
docs/configuration/nat/nat66.rst
View File

@ -82,7 +82,7 @@ Example:
.. code-block:: none
set nat66 source rule 1 outbound-interface 'eth0'
set nat66 source rule 1 outbound-interface name 'eth0'
set nat66 source rule 1 source prefix 'fc01::/64'
set nat66 source rule 1 translation address 'fc00::/64'
@ -101,7 +101,7 @@ Example:
.. code-block:: none
set nat66 destination rule 1 inbound-interface 'eth0'
set nat66 destination rule 1 inbound-interface name 'eth0'
set nat66 destination rule 1 destination address 'fc00::/64'
set nat66 destination rule 1 translation address 'fc01::/64'
@ -122,9 +122,9 @@ R1:
set interfaces ethernet eth0 ipv6 address autoconf
set interfaces ethernet eth1 address 'fc01::1/64'
set nat66 destination rule 1 destination address 'fc00:470:f1cd:101::/64'
set nat66 destination rule 1 inbound-interface 'eth0'
set nat66 destination rule 1 inbound-interface name 'eth0'
set nat66 destination rule 1 translation address 'fc01::/64'
set nat66 source rule 1 outbound-interface 'eth0'
set nat66 source rule 1 outbound-interface name 'eth0'
set nat66 source rule 1 source prefix 'fc01::/64'
set nat66 source rule 1 translation address 'fc00:470:f1cd:101::/64'