diff options
Diffstat (limited to 'docs/configuration')
33 files changed, 1416 insertions, 497 deletions
diff --git a/docs/configuration/container/index.rst b/docs/configuration/container/index.rst index c23a6184..0487f863 100644 --- a/docs/configuration/container/index.rst +++ b/docs/configuration/container/index.rst @@ -182,11 +182,11 @@ Example Configuration .. code-block:: none - set container network zabbix-net prefix 172.20.0.0/16 - set container network zabbix-net description 'Network for Zabbix component containers' + set container network zabbix prefix 172.20.0.0/16 + set container network zabbix description 'Network for Zabbix component containers' set container name mysql-server image mysql:8.0 - set container name mysql-server network zabbix-net + set container name mysql-server network zabbix set container name mysql-server environment 'MYSQL_DATABASE' value 'zabbix' set container name mysql-server environment 'MYSQL_USER' value 'zabbix' @@ -194,10 +194,10 @@ Example Configuration set container name mysql-server environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' set container name zabbix-java-gateway image zabbix/zabbix-java-gateway:alpine-5.2-latest - set container name zabbix-java-gateway network zabbix-net + set container name zabbix-java-gateway network zabbix set container name zabbix-server-mysql image zabbix/zabbix-server-mysql:alpine-5.2-latest - set container name zabbix-server-mysql network zabbix-net + set container name zabbix-server-mysql network zabbix set container name zabbix-server-mysql environment 'DB_SERVER_HOST' value 'mysql-server' set container name zabbix-server-mysql environment 'MYSQL_DATABASE' value 'zabbix' @@ -210,7 +210,7 @@ Example Configuration set container name zabbix-server-mysql port zabbix destination 10051 set container name zabbix-web-nginx-mysql image zabbix/zabbix-web-nginx-mysql:alpine-5.2-latest - set container name zabbix-web-nginx-mysql network zabbix-net + set container name zabbix-web-nginx-mysql network zabbix set container name zabbix-web-nginx-mysql environment 'MYSQL_DATABASE' value 'zabbix' set container name zabbix-web-nginx-mysql environment 'ZBX_SERVER_HOST' value 'zabbix-server-mysql' diff --git a/docs/configuration/firewall/bridge.rst b/docs/configuration/firewall/bridge.rst index 4a0dc3bb..9fb019c5 100644 --- a/docs/configuration/firewall/bridge.rst +++ b/docs/configuration/firewall/bridge.rst @@ -39,4 +39,363 @@ for this layer is shown next: 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 ...`` +forward filter ...``, which happens in stage 4, highlightened with red color. + +Custom bridge firewall chains can be create with command ``set firewall bridge +name <name> ...``. In order to use such custom chain, a rule with action jump, +and the appropiate 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 +************ + +For firewall filtering, firewall rules needs to be created. Each rule is +numbered, has an action to apply if the rule is matched, and the ability +to specify multiple criteria matchers. Data packets go through the rules +from 1 - 999999, so order is crucial. At the first match the action of the +rule will be executed. + +Actions +======= + +If a rule is defined, then an action must be defined for it. This tells the +firewall what to do if all criteria matchers defined for such rule do match. + +In firewall bridge rules, the action can be: + + * ``accept``: accept the packet. + + * ``continue``: continue parsing next rule. + + * ``drop``: drop the packet. + + * ``jump``: jump to another custom chain. + + * ``return``: Return from the current chain and continue at the next rule + of the last chain. + + * ``queue``: Enqueue packet to userspace. + +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> action + [accept | continue | drop | jump | queue | return] +.. cfgcmd:: set firewall bridge name <name> rule <1-999999> action + [accept | continue | drop | jump | queue | return] + + This required setting defines the action of the current rule. If action is + set to jump, then jump-target is also needed. + +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + jump-target <text> +.. cfgcmd:: set firewall bridge name <name> rule <1-999999> + jump-target <text> + +.. cfgcmd:: set firewall bridge forward 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 + queue target to use. Queue range is also supported. + +.. cfgcmd:: set firewall bridge forward 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 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 it's 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 name <name> default-action + [accept | continue | drop | jump | queue | return] + + This set the default action of the rule-set if no rule matched a packet + criteria. If default-action is set to ``jump``, then + ``default-jump-target`` is also needed. Note that for base chains, default + action can only be set to ``accept`` or ``drop``, while on custom chain, + more actions are available. + +.. cfgcmd:: set firewall bridge name <name> default-jump-target <text> + + To be used only when ``defult-action`` is set to ``jump``. Use this + command to specify jump target for default rule. + +.. note:: **Important note about default-actions:** + If default action for any base chain is not defined, then the default + action is set to **accept** for that chain. For custom chains, if default + action is not defined, then the default-action is set to **drop**. + +Firewall Logs +============= + +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 name <name> rule <1-999999> log + + Enable logging for the matched packet. If this configuration command is not + present, then log is not enabled. + +.. cfgcmd:: set firewall bridge forward filter enable-default-log +.. cfgcmd:: set firewall bridge name <name> enable-default-log + + Use this command to enable the logging of the default action on + the specified chain. + +.. cfgcmd:: set firewall bridge forward 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] + + Define log-level. Only applicable if rule log is enable. + +.. cfgcmd:: set firewall bridge forward filter rule <1-999999> + log-options group <0-65535> +.. cfgcmd:: set firewall bridge name <name> rule <1-999999> + log-options group <0-65535> + + Define log group to send message to. Only applicable if rule log is enable. + +.. cfgcmd:: set firewall bridge forward 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> + + Define length of packet payload to include in netlink message. Only + applicable if rule log is enable and log group is defined. + +.. cfgcmd:: set firewall bridge forward 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> + + Define number of packets to queue inside the kernel before sending them to + userspace. Only applicable if rule log is enable and log group is defined. + +Firewall Description +==================== + +For reference, a description can be defined for every defined custom chain. + +.. cfgcmd:: set firewall bridge name <name> description <text> + + Provide a rule-set description to a custom firewall chain. + +Rule Status +=========== + +When defining a rule, it is enable 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 name <name> rule <1-999999> disable + + Command for disabling a rule but keep it in the configuration. + +Matching criteria +================= + +There are a lot of matching criteria against which the packet can be tested. + +.. 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> + + Match criteria based on source and/or destination mac-address. + +.. 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. Wilcard ``*`` can be used. + For example: ``eth2*``. Prepending character ``!`` for inverted matching + criteria is also supportd. 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 supportd. 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> + + Match based on outbound interface. Wilcard ``*`` can be used. + For example: ``eth2*``. Prepending character ``!`` for inverted matching + criteria is also supportd. For example ``!eth2`` + +.. 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 supportd. For example ``!IFACE_GROUP`` + +.. 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> + + Match based on vlan priority(pcp). Range is also supported. + +*********************** +Operation-mode Firewall +*********************** + +Rule-set overview +================= + +In this section you can find all useful firewall op-mode commands. + +General commands for firewall configuration, counter and statiscits: + +.. opcmd:: show firewall +.. opcmd:: show firewall summary +.. opcmd:: show firewall statistics + +And, to print only bridge firewall information: + +.. opcmd:: show firewall bridge +.. opcmd:: show firewall bridge forward filter +.. opcmd:: show firewall bridge forward filter rule <rule> +.. opcmd:: show firewall bridge name <name> +.. opcmd:: show firewall bridge name <name> rule <rule> + +Show Firewall log +================= + +.. opcmd:: show log firewall +.. opcmd:: show log firewall bridge +.. opcmd:: show log firewall bridge forward +.. opcmd:: show log firewall bridge forward filter +.. opcmd:: show log firewall bridge name <name> +.. opcmd:: show log firewall bridge forward filter rule <rule> +.. opcmd:: show log firewall bridge name <name> rule <rule> + + Show the logs of all firewall; show all bridge firewall logs; show all logs + for forward hook; show all logs for forward hook and priority filter; show + all logs for particular custom chain; show logs for specific Rule-Set. + +Example +======= + +Configuration example: + +.. code-block:: none + + set firewall bridge forward filter default-action 'drop' + set firewall bridge forward filter enable-default-log + set firewall bridge forward filter rule 10 action 'continue' + set firewall bridge forward filter rule 10 inbound-interface name 'eth2' + set firewall bridge forward filter rule 10 vlan id '22' + set firewall bridge forward filter rule 20 action 'drop' + set firewall bridge forward filter rule 20 inbound-interface group 'TRUNK-RIGHT' + set firewall bridge forward filter rule 20 vlan id '60' + set firewall bridge forward filter rule 30 action 'jump' + set firewall bridge forward filter rule 30 jump-target 'TEST' + set firewall bridge forward filter rule 30 outbound-interface name '!eth1' + set firewall bridge forward filter rule 35 action 'accept' + set firewall bridge forward filter rule 35 vlan id '11' + set firewall bridge forward filter rule 40 action 'continue' + set firewall bridge forward filter rule 40 destination mac-address '66:55:44:33:22:11' + set firewall bridge forward filter rule 40 source mac-address '11:22:33:44:55:66' + set firewall bridge name TEST default-action 'accept' + set firewall bridge name TEST enable-default-log + set firewall bridge name TEST rule 10 action 'continue' + set firewall bridge name TEST rule 10 log + set firewall bridge name TEST rule 10 vlan priority '0' + +And op-mode commands: + +.. code-block:: none + + vyos@BRI:~$ show firewall bridge + Rulesets bridge Information + + --------------------------------- + bridge Firewall "forward filter" + + Rule Action Protocol Packets Bytes Conditions + ------- -------- ---------- --------- ------- --------------------------------------------------------------------- + 10 continue all 0 0 iifname "eth2" vlan id 22 continue + 20 drop all 0 0 iifname @I_TRUNK-RIGHT vlan id 60 + 30 jump all 2130 170688 oifname != "eth1" jump NAME_TEST + 35 accept all 2080 168616 vlan id 11 accept + 40 continue all 0 0 ether daddr 66:55:44:33:22:11 ether saddr 11:22:33:44:55:66 continue + default drop all 0 0 + + --------------------------------- + bridge Firewall "name TEST" + + Rule Action Protocol Packets Bytes Conditions + ------- -------- ---------- --------- ------- -------------------------------------------------- + 10 continue all 2130 170688 vlan pcp 0 prefix "[bri-NAM-TEST-10-C]" continue + default accept all 2130 170688 + + vyos@BRI:~$ + vyos@BRI:~$ show firewall bridge name TEST + Ruleset Information + + --------------------------------- + bridge Firewall "name TEST" + + Rule Action Protocol Packets Bytes Conditions + ------- -------- ---------- --------- ------- -------------------------------------------------- + 10 continue all 2130 170688 vlan pcp 0 prefix "[bri-NAM-TEST-10-C]" continue + default accept all 2130 170688 + + vyos@BRI:~$ + +Inspect logs: + +.. code-block:: none + + vyos@BRI:~$ show log firewall bridge + Dec 05 14:37:47 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 + Dec 05 14:37:48 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 + Dec 05 14:37:49 kernel: [bri-NAM-TEST-10-C]IN=eth1 OUT=eth2 ARP HTYPE=1 PTYPE=0x0800 OPCODE=1 MACSRC=50:00:00:04:00:00 IPSRC=10.11.11.101 MACDST=00:00:00:00:00:00 IPDST=10.11.11.102 + ... + vyos@BRI:~$ show log firewall bridge forward filter + Dec 05 14:42:22 kernel: [bri-FWD-filter-default-D]IN=eth2 OUT=eth1 MAC=33:33:00:00:00:16:50:00:00:06:00:00:86:dd SRC=0000:0000:0000:0000:0000:0000:0000:0000 DST=ff02:0000:0000:0000:0000:0000:0000:0016 LEN=96 TC=0 HOPLIMIT=1 FLOWLBL=0 PROTO=ICMPv6 TYPE=143 CODE=0 + Dec 05 14:42:22 kernel: [bri-FWD-filter-default-D]IN=eth2 OUT=eth1 MAC=33:33:00:00:00:16:50:00:00:06:00:00:86:dd SRC=0000:0000:0000:0000:0000:0000:0000:0000 DST=ff02:0000:0000:0000:0000:0000:0000:0016 LEN=96 TC=0 HOPLIMIT=1 FLOWLBL=0 PROTO=ICMPv6 TYPE=143 CODE=0 diff --git a/docs/configuration/firewall/flowtables.rst b/docs/configuration/firewall/flowtables.rst index 8b44a9b9..bc7b9212 100644 --- a/docs/configuration/firewall/flowtables.rst +++ b/docs/configuration/firewall/flowtables.rst @@ -1,4 +1,4 @@ -:lastproofread: 2023-11-08 +:lastproofread: 2023-12-26 .. _firewall-flowtables-configuration: @@ -13,7 +13,7 @@ Overview ******** In this section there's useful information of all firewall configuration that -can be done regarding flowtables +can be done regarding flowtables. .. cfgcmd:: set firewall flowtables ... @@ -50,3 +50,139 @@ flowtable (flowtable miss), the packet follows the classic IP forwarding path. .. note:: **Flowtable Reference:** https://docs.kernel.org/networking/nf_flowtable.html + + +*********************** +Flowtable Configuration +*********************** + +In order to use flowtables, the minimal configuration needed includes: + + * Create flowtable: create flowtable, which includes the interfaces + that are going to be used by the flowtable. + + * Create firewall rule: create a firewall rule, setting action to + ``offload`` and using desired flowtable for ``offload-target``. + +Creating a flow table: + +.. cfgcmd:: set firewall flowtable <flow_table_name> interface <iface> + + Define interfaces to be used in the flowtable. + +.. cfgcmd:: set firewall flowtable <flow_table_name> description <text> + +Provide a description to the flow table. + +.. cfgcmd:: set firewall flowtable <flow_table_name> offload + <hardware | software> + + Define type of offload to be used by the flowtable: ``hardware`` or + ``software``. By default, ``software`` offload is used. + +.. note:: **Hardware offload:** should be supported by the NICs used. + +Creating rules for using flow tables: + +.. cfgcmd:: set firewall [ipv4 | ipv4] forward filter rule <1-999999> + action offload + + Create firewall rule in forward chain, and set action to ``offload``. + +.. cfgcmd:: set firewall [ipv4 | ipv4] forward filter rule <1-999999> + offload-target <flowtable> + + Create firewall rule in forward chain, and define which flowtbale + should be used. Only applicable if action is ``offload``. + +********************* +Configuration Example +********************* + +Things to be considred in this setup: + + * Two interfaces are going to be used in the flowtables: eth0 and eth1 + + * Minumum firewall ruleset is provided, which includes some filtering rules, + and appropiate rules for using flowtable offload capabilities. + +As described, first packet will be evaluated by all the firewall path, so +desired connection should be explicitely accepted. Same thing should be taken +into account for traffic in reverse order. In most cases state policies are +used in order to accept connection in reverse patch. + +We will only accept traffic comming from interface eth0, protocol tcp and +destination port 1122. All other traffic traspassing the router should be +blocked. + +Commands +-------- + +.. code-block:: none + + set firewall flowtable FT01 interface 'eth0' + set firewall flowtable FT01 interface 'eth1' + set firewall ipv4 forward filter default-action 'drop' + set firewall ipv4 forward filter rule 10 action 'offload' + set firewall ipv4 forward filter rule 10 offload-target 'FT01' + set firewall ipv4 forward filter rule 10 state 'established' + set firewall ipv4 forward filter rule 10 state 'related' + set firewall ipv4 forward filter rule 20 action 'accept' + set firewall ipv4 forward filter rule 20 state 'established' + set firewall ipv4 forward filter rule 20 state 'related' + set firewall ipv4 forward filter rule 110 action 'accept' + set firewall ipv4 forward filter rule 110 destination address '192.0.2.100' + set firewall ipv4 forward filter rule 110 destination port '1122' + set firewall ipv4 forward filter rule 110 inbound-interface name 'eth0' + set firewall ipv4 forward filter rule 110 protocol 'tcp' + +Explanation +----------- + +Analysis on what happens for desired connection: + + 1. First packet is received on eht0, with destination address 192.0.2.100, + protocol tcp and destination port 1122. Assume such destination address is + reachable through interface eth1. + + 2. Since this is the first packet, connection status of this connection, + so far is **new**. So neither rule 10 nor 20 are valid. + + 3. Rule 110 is hit, so connection is accepted. + + 4. Once answer from server 192.0.2.100 is seen in opposite direction, + connection state will be triggered to **established**, so this reply is + accepted in rule 10. + + 5. Second packet for this connection is received by the router. Since + connection state is **established**, then rule 10 is hit, and a new entry + in the flowtable FT01 is added for this connection. + + 6. All subsecuent packets will skip traditional path, and will be offloaded + and will use the **Fast Path**. + +Checks +------ + +It's time to check conntrack table, to see if any connection was accepted, +and if was properly offloaded + +.. code-block:: none + + vyos@FlowTables:~$ show firewall ipv4 forward filter + Ruleset Information + + --------------------------------- + ipv4 Firewall "forward filter" + + Rule Action Protocol Packets Bytes Conditions + ------- -------- ---------- --------- ------- ---------------------------------------------------------------- + 10 offload all 8 468 ct state { established, related } flow add @VYOS_FLOWTABLE_FT01 + 20 accept all 8 468 ct state { established, related } accept + 110 accept tcp 2 120 ip daddr 192.0.2.100 tcp dport 1122 iifname "eth0" accept + default drop all 7 420 + + vyos@FlowTables:~$ sudo conntrack -L | grep tcp + conntrack v1.4.6 (conntrack-tools): 5 flow entries have been shown. + tcp 6 src=198.51.100.100 dst=192.0.2.100 sport=41676 dport=1122 src=192.0.2.100 dst=198.51.100.100 sport=1122 dport=41676 [OFFLOAD] mark=0 use=2 + vyos@FlowTables:~$ diff --git a/docs/configuration/firewall/global-options.rst b/docs/configuration/firewall/global-options.rst index 316e0802..b3f311aa 100644 --- a/docs/configuration/firewall/global-options.rst +++ b/docs/configuration/firewall/global-options.rst @@ -1,4 +1,4 @@ -:lastproofread: 2023-11-07 +:lastproofread: 2023-12-26 .. _firewall-global-options-configuration: @@ -114,4 +114,34 @@ Configuration Enable or Disable VyOS to be :rfc:`1337` conform. The following system parameter will be altered: - * ``net.ipv4.tcp_rfc1337``
\ No newline at end of file + * ``net.ipv4.tcp_rfc1337`` + +.. cfgcmd:: set firewall global-options state-policy established action + [accept | drop | reject] + +.. cfgcmd:: set firewall global-options state-policy established log + +.. cfgcmd:: set firewall global-options state-policy established log-level + [emerg | alert | crit | err | warn | notice | info | debug] + + Set the global setting for an established connection. + +.. cfgcmd:: set firewall global-options state-policy invalid action + [accept | drop | reject] + +.. cfgcmd:: set firewall global-options state-policy invalid log + +.. cfgcmd:: set firewall global-options state-policy invalid log-level + [emerg | alert | crit | err | warn | notice | info | debug] + + Set the global setting for invalid packets. + +.. cfgcmd:: set firewall global-options state-policy related action + [accept | drop | reject] + +.. cfgcmd:: set firewall global-options state-policy related log + +.. cfgcmd:: set firewall global-options state-policy related log-level + [emerg | alert | crit | err | warn | notice | info | debug] + + Set the global setting for related connections. diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst index 3887e26a..74d5bc20 100644 --- a/docs/configuration/firewall/index.rst +++ b/docs/configuration/firewall/index.rst @@ -4,31 +4,32 @@ Firewall ######## -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). +As VyOS is based on Linux it leverages its firewall. The Netfilter project +created iptables and its successor nftables for the Linux kernel to +work directly on packet 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. +A simplified traffic flow diagram, 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 traffic can take. .. figure:: /_static/images/firewall-gral-packet-flow.png -Main notes regarding this packet flow and terminology used in VyOS firewall: +The main points regarding this packet flow and terminology used in VyOS +firewall are covered below: - * **Bridge Port?**: choose appropiate path based on if interface were the - packet was received is part of a bridge, or not. + * **Bridge Port?**: choose appropriate path based on whether interface + where 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**: +If the interface where the packet was received isn't part of a bridge, then +packetis 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 + 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 + defined under ``firewall`` section. Relevant configuration that acts in this stage are: * **Conntrack Ignore**: rules defined under ``set system conntrack ignore @@ -40,12 +41,12 @@ is processed at the **IP Layer**: * **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**, + * **Destination is the router?**: choose appropriate path based on + destination IP address. Transit forward continues 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 + * **Input**: stage where traffic destined for 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: @@ -61,10 +62,10 @@ is processed at the **IP Layer**: * ``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 + * **Output**: stage where traffic that originates from the router itself + can be filtered and controlled. Bear in mind that this traffic can be a + new connection originated by a internal process running on VyOS router, + such as NTP, or 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: @@ -79,16 +80,16 @@ is processed at the **IP Layer**: * **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: +If the interface where the packet was received is part of a bridge, then +packetis processed at the **Bridge Layer**, which contains a basic setup for +bridge filtering: - * **Forward (Bridge)**: stage where traffic that is trasspasing through the + * **Forward (Bridge)**: stage where traffic that is trespasing through the bridge is filtered and controlled: * ``set firewall bridge forward filter ...``. -Main structure VyOS firewall cli is shown next: +The main structure VyOS firewall cli is shown next: .. code-block:: none @@ -134,7 +135,7 @@ Main structure VyOS firewall cli is shown next: - custom_zone_name + ... -Please, refer to appropiate section for more information about firewall +Please, refer to appropriate section for more information about firewall configuration: .. toctree:: diff --git a/docs/configuration/firewall/ipv4.rst b/docs/configuration/firewall/ipv4.rst index 3fd365e1..9a683d22 100644 --- a/docs/configuration/firewall/ipv4.rst +++ b/docs/configuration/firewall/ipv4.rst @@ -123,9 +123,46 @@ The action can be : .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> jump-target <text> - To be used only when action is set to jump. Use this command to specify + To be used only when action is set to ``jump``. Use this command to specify jump target. +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + queue <0-65535> +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + queue <0-65535> +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + queue <0-65535> +.. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> + queue <0-65535> + + To be used only when action is set to ``queue``. Use this command to specify + queue target to use. Queue range is also supported. + +.. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> + queue-options bypass +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + queue-options bypass +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + queue-options bypass +.. cfgcmd:: set firewall ipv4 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 ipv4 forward filter rule <1-999999> + queue-options fanout +.. cfgcmd:: set firewall ipv4 input filter rule <1-999999> + queue-options fanout +.. cfgcmd:: set firewall ipv4 output filter rule <1-999999> + queue-options fanout +.. cfgcmd:: set firewall ipv4 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 it's chain. For base chains, possible options for **default-action** are **accept** or **drop**. @@ -140,7 +177,7 @@ not match any rule in it's chain. For base chains, possible options for [accept | drop | jump | queue | reject | return] This set the default action of the rule-set if no rule matched a packet - criteria. If defacult-action is set to ``jump``, then + criteria. If default-action is set to ``jump``, then ``default-jump-target`` is also needed. Note that for base chains, default action can only be set to ``accept`` or ``drop``, while on custom chain, more actions are available. @@ -153,7 +190,7 @@ not match any rule in it's chain. For base chains, possible options for .. note:: **Important note about default-actions:** If default action for any base chain is not defined, then the default action is set to **accept** for that chain. For custom chains, if default - action is not defined, then the default-action is set to **drop** + action is not defined, then the default-action is set to **drop**. Firewall Logs ============= @@ -162,15 +199,12 @@ Logging can be enable for every single firewall rule. If enabled, other log options can be defined. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> log - [disable | enable] .. cfgcmd:: set firewall ipv4 input filter rule <1-999999> log - [disable | enable] .. cfgcmd:: set firewall ipv4 output filter rule <1-999999> log - [disable | enable] .. cfgcmd:: set firewall ipv4 name <name> rule <1-999999> log - [disable | enable] - Enable or disable logging for the matched packet. + Enable logging for the matched packet. If this configuration command is not + present, then log is not enabled. .. cfgcmd:: set firewall ipv4 forward filter enable-default-log .. cfgcmd:: set firewall ipv4 input filter enable-default-log @@ -266,7 +300,7 @@ just disable the rule, rather than removing it. Matching criteria ================= -There are a lot of matching criteria against which the package can be tested. +There are a lot of matching criteria against which the packet can be tested. .. cfgcmd:: set firewall ipv4 forward filter rule <1-999999> connection-status nat [destination | source] diff --git a/docs/configuration/firewall/ipv6.rst b/docs/configuration/firewall/ipv6.rst index 83a5f694..0aa8a137 100644 --- a/docs/configuration/firewall/ipv6.rst +++ b/docs/configuration/firewall/ipv6.rst @@ -123,9 +123,46 @@ The action can be : .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> jump-target <text> - To be used only when action is set to jump. Use this command to specify + To be used only when action is set to ``jump``. Use this command to specify jump target. +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + queue <0-65535> +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + queue <0-65535> +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + queue <0-65535> +.. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> + queue <0-65535> + + To be used only when action is set to ``queue``. Use this command to specify + queue target to use. Queue range is also supported. + +.. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> + queue-options bypass +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + queue-options bypass +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + queue-options bypass +.. cfgcmd:: set firewall ipv6 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 ipv6 forward filter rule <1-999999> + queue-options fanout +.. cfgcmd:: set firewall ipv6 input filter rule <1-999999> + queue-options fanout +.. cfgcmd:: set firewall ipv6 output filter rule <1-999999> + queue-options fanout +.. cfgcmd:: set firewall ipv6 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 it's chain. For base chains, possible options for **default-action** are **accept** or **drop**. @@ -140,7 +177,7 @@ not match any rule in it's chain. For base chains, possible options for [accept | drop | jump | queue | reject | return] This set the default action of the rule-set if no rule matched a packet - criteria. If defacult-action is set to ``jump``, then + criteria. If default-action is set to ``jump``, then ``default-jump-target`` is also needed. Note that for base chains, default action can only be set to ``accept`` or ``drop``, while on custom chain, more actions are available. @@ -153,7 +190,7 @@ not match any rule in it's chain. For base chains, possible options for .. note:: **Important note about default-actions:** If default action for any base chain is not defined, then the default action is set to **accept** for that chain. For custom chains, if default - action is not defined, then the default-action is set to **drop** + action is not defined, then the default-action is set to **drop**. Firewall Logs ============= @@ -162,15 +199,12 @@ Logging can be enable for every single firewall rule. If enabled, other log options can be defined. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> log - [disable | enable] .. cfgcmd:: set firewall ipv6 input filter rule <1-999999> log - [disable | enable] .. cfgcmd:: set firewall ipv6 output filter rule <1-999999> log - [disable | enable] .. cfgcmd:: set firewall ipv6 name <name> rule <1-999999> log - [disable | enable] - Enable or disable logging for the matched packet. + Enable logging for the matched packet. If this configuration command is not + present, then log is not enabled. .. cfgcmd:: set firewall ipv6 forward filter enable-default-log .. cfgcmd:: set firewall ipv6 input filter enable-default-log @@ -266,7 +300,7 @@ just disable the rule, rather than removing it. Matching criteria ================= -There are a lot of matching criteria against which the package can be tested. +There are a lot of matching criteria against which the packet can be tested. .. cfgcmd:: set firewall ipv6 forward filter rule <1-999999> connection-status nat [destination | source] @@ -936,7 +970,7 @@ Rule-set overview .. code-block:: none - vyos@vyos:~$ show firewall + vyos@vyos:~$ show firewall Rulesets Information --------------------------------- @@ -999,7 +1033,7 @@ Rule-set overview .. code-block:: none - vyos@vyos:~$ show firewall summary + vyos@vyos:~$ show firewall summary Ruleset Summary IPv6 Ruleset: @@ -1049,29 +1083,30 @@ Rule-set overview .. opcmd:: show firewall ipv6 [forward | input | output] filter -.. opcmd:: show firewall ipv4 name <name> - .. opcmd:: show firewall ipv6 ipv6-name <name> This command will give an overview of a single rule-set. .. code-block:: none - vyos@vyos:~$ show firewall ipv4 input filter + vyos@vyos:~$ show firewall ipv6 input filter Ruleset Information --------------------------------- - IPv4 Firewall "input filter" + ipv6 Firewall "input filter" Rule Action Protocol Packets Bytes Conditions - ------- -------- ---------- --------- ------- ----------------------------------------- - 5 jump all 0 0 iifname "eth2" jump NAME_VyOS_MANAGEMENT - default accept all + ------- -------- ---------- --------- ------- ------------------------------------------------------------------------------ + 10 jump all 13 1456 iifname "eth1" jump NAME6_INP-ETH1 + 20 accept ipv6-icmp 10 1112 meta l4proto ipv6-icmp iifname "eth0" prefix "[ipv6-INP-filter-20-A]" accept + default accept all 14 1584 + + vyos@vyos:~$ .. opcmd:: show firewall ipv6 [forward | input | output] filter rule <1-999999> -.. opcmd:: show firewall ipv4 name <name> rule <1-999999> +.. opcmd:: show firewall ipv6 name <name> rule <1-999999> .. opcmd:: show firewall ipv6 ipv6-name <name> rule <1-999999> @@ -1084,7 +1119,7 @@ Rule-set overview .. code-block:: none - vyos@vyos:~$ show firewall group LAN + vyos@vyos:~$ show firewall group LAN Firewall Groups Name Type References Members @@ -1119,45 +1154,38 @@ Example Partial Config .. code-block:: none - firewall { - group { - network-group BAD-NETWORKS { - network 198.51.100.0/24 - network 203.0.113.0/24 - } - network-group GOOD-NETWORKS { - network 192.0.2.0/24 - } - port-group BAD-PORTS { - port 65535 - } - } - ipv4 { - forward { - filter { - default-action accept - rule 5 { - action accept - source { - group { - network-group GOOD-NETWORKS + firewall { + ipv6 { + input { + filter { + rule 10 { + action jump + inbound-interface { + name eth1 } + jump-target INP-ETH1 } - } - rule 10 { - action drop - description "Bad Networks" - protocol all - source { - group { - network-group BAD-NETWORKS + rule 20 { + action accept + inbound-interface { + name eth0 } + log + protocol ipv6-icmp } } } + name INP-ETH1 { + default-action drop + enable-default-log + rule 10 { + action accept + protocol tcp_udp + } + } } } - } + Update geoip database ===================== diff --git a/docs/configuration/firewall/zone.rst b/docs/configuration/firewall/zone.rst index 1ab9c630..059b029d 100644 --- a/docs/configuration/firewall/zone.rst +++ b/docs/configuration/firewall/zone.rst @@ -123,3 +123,41 @@ written from the perspective of: *Source Zone*-to->*Destination Zone* set firewall zone DMZ from LAN firewall name LANv4-to-DMZv4 set firewall zone LAN from DMZ firewall name DMZv4-to-LANv4 +************** +Operation-mode +************** + +.. opcmd:: show firewall zone-policy + + This will show you a basic summary of zones configuration. + + .. code-block:: none + + vyos@vyos:~$ show firewall zone-policy + Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 + ------ ------------ ----------- --------------- --------------- + LAN eth1 WAN WAN_to_LAN + eth2 + LOCAL LOCAL LAN LAN_to_LOCAL + WAN WAN_to_LOCAL WAN_to_LOCAL_v6 + WAN eth3 LAN LAN_to_WAN + eth0 LOCAL LOCAL_to_WAN + vyos@vyos:~$ + +.. opcmd:: show firewall zone-policy zone <zone> + + This will show you a basic summary of a particular zone. + + .. code-block:: none + + vyos@vyos:~$ show firewall zone-policy zone WAN + Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 + ------ ------------ ----------- --------------- --------------- + WAN eth3 LAN LAN_to_WAN + eth0 LOCAL LOCAL_to_WAN + vyos@vyos:~$ show firewall zone-policy zone LOCAL + Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 + ------ ------------ ----------- --------------- --------------- + LOCAL LOCAL LAN LAN_to_LOCAL + WAN WAN_to_LOCAL WAN_to_LOCAL_v6 + vyos@vyos:~$ diff --git a/docs/configuration/loadbalancing/reverse-proxy.rst b/docs/configuration/loadbalancing/reverse-proxy.rst index 04b612f5..19ef3773 100644 --- a/docs/configuration/loadbalancing/reverse-proxy.rst +++ b/docs/configuration/loadbalancing/reverse-proxy.rst @@ -105,7 +105,7 @@ Backend of the client * ``round-robin`` Distributes requests in a circular manner, sequentially sending each request to the next server in line - * ``least-connection`` Distributes requests tp tje server wotj the fewest + * ``least-connection`` Distributes requests to the server with the fewest active connections .. cfgcmd:: set load-balancing reverse-proxy backend <name> mode diff --git a/docs/configuration/nat/index.rst b/docs/configuration/nat/index.rst index 90275226..6556b7f9 100644 --- a/docs/configuration/nat/index.rst +++ b/docs/configuration/nat/index.rst @@ -9,4 +9,5 @@ NAT :includehidden: nat44 + nat64 nat66 diff --git a/docs/configuration/nat/nat64.rst b/docs/configuration/nat/nat64.rst new file mode 100644 index 00000000..e8a3a0e6 --- /dev/null +++ b/docs/configuration/nat/nat64.rst @@ -0,0 +1,81 @@ +.. _nat64: + +##### +NAT64 +##### + +:abbr:`NAT64 (IPv6-to-IPv4 Prefix Translation)` is a critical component in +modern networking, facilitating communication between IPv6 and IPv4 networks. +This documentation outlines the setup, configuration, and usage of the NAT64 +feature in your project. Whether you are transitioning to IPv6 or need to +seamlessly connect IPv4 and IPv6 devices. +NAT64 is a stateful translation mechanism that translates IPv6 addresses to +IPv4 addresses and IPv4 addresses to IPv6 addresses. NAT64 is used to enable +IPv6-only clients to contact IPv4 servers using unicast UDP, TCP, or ICMP. + + +Overview +======== + +Different NAT Types +------------------- + +.. _source-nat64: + +SNAT64 +^^^^^^ + +:abbr:`SNAT64 (IPv6-to-IPv4 Source Address Translation)` is a stateful +translation mechanism that translates IPv6 addresses to IPv4 addresses. + +``64:ff9b::/96`` is the well-known prefix for IPv4-embedded IPv6 addresses. +The prefix is used to represent IPv4 addresses in an IPv6 address format. +The IPv4 address is encoded in the low-order 32 bits of the IPv6 address. +The high-order 32 bits are set to the well-known prefix 64:ff9b::/96. + + +Configuration Examples +====================== + +The following examples show how to configure NAT64 on a VyOS router. +The 192.0.2.10 address is used as the IPv4 address for the translation pool. + + +NAT64 server configuration: + +.. code-block:: none + + set interfaces ethernet eth0 address '192.0.2.1/24' + set interfaces ethernet eth0 address '192.0.2.10/24' + set interfaces ethernet eth0 description 'WAN' + set interfaces ethernet eth1 address '2001:db8::1/64' + set interfaces ethernet eth1 description 'LAN' + + set service dns forwarding allow-from '2001:db8::/64' + set service dns forwarding dns64-prefix '64:ff9b::/96' + set service dns forwarding listen-address '2001:db8::1' + + set nat64 source rule 100 source prefix '64:ff9b::/96' + set nat64 source rule 100 translation pool 10 address '192.0.2.10' + set nat64 source rule 100 translation pool 10 port '1-65535' + +NAT64 client configuration: + +.. code-block:: none + + set interfaces ethernet eth1 address '2001:db8::2/64' + set protocols static route6 64:ff9b::/96 next-hop 2001:db8::1 + set system name-server '2001:db8::1' + +Test from the IPv6 only client: + +.. code-block:: none + + vyos@r1:~$ ping 64:ff9b::192.0.2.1 count 2 + PING 64:ff9b::192.0.2.1(64:ff9b::c000:201) 56 data bytes + 64 bytes from 64:ff9b::c000:201: icmp_seq=1 ttl=63 time=0.351 ms + 64 bytes from 64:ff9b::c000:201: icmp_seq=2 ttl=63 time=0.373 ms + + --- 64:ff9b::192.0.2.1 ping statistics --- + 2 packets transmitted, 2 received, 0% packet loss, time 1023ms + rtt min/avg/max/mdev = 0.351/0.362/0.373/0.011 ms diff --git a/docs/configuration/nat/nat66.rst b/docs/configuration/nat/nat66.rst index 66cceb0a..9345e708 100644 --- a/docs/configuration/nat/nat66.rst +++ b/docs/configuration/nat/nat66.rst @@ -137,3 +137,100 @@ R2: set interfaces bridge br1 member interface eth1 set protocols static route6 ::/0 next-hop fc01::1 set service router-advert interface br1 prefix ::/0 + + +Use the following topology to translate internal user local addresses (``fc::/7``) +to DHCPv6-PD provided prefixes from an ISP connected to a VyOS HA pair. + +.. figure:: /_static/images/vyos_1_5_nat66_dhcpv6_wdummy.png + :alt: VyOS NAT66 DHCPv6 using a dummy interface + +Configure both routers (a and b) for DHCPv6-PD via dummy interface: + +.. code-block:: none + + set interfaces dummy dum1 description 'DHCPv6-PD NPT dummy' + set interfaces bonding bond0 vif 20 dhcpv6-options pd 0 interface dum1 address '0' + set interfaces bonding bond0 vif 20 dhcpv6-options pd 1 interface dum1 address '0' + set interfaces bonding bond0 vif 20 dhcpv6-options pd 2 interface dum1 address '0' + set interfaces bonding bond0 vif 20 dhcpv6-options pd 3 interface dum1 address '0' + set interfaces bonding bond0 vif 20 dhcpv6-options rapid-commit + commit + +Get the DHCPv6-PD prefixes from both routers: + +.. code-block:: none + + trae@cr01a-vyos# run show interfaces dummy dum1 br + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + dum1 2001:db8:123:b008::/64 u/u DHCPv6-PD NPT dummy + 2001:db8:123:b00a::/64 + 2001:db8:123:b00b::/64 + 2001:db8:123:b009::/64 + + trae@cr01b-vyos# run show int dummy dum1 brief + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + dum1 2001:db8:123:b00d::/64 u/u DHCPv6-PD NPT dummy + 2001:db8:123:b00c::/64 + 2001:db8:123:b00e::/64 + 2001:db8:123:b00f::/64 + +Configure the A-side router for NPTv6 using the prefixes above: + +.. code-block:: none + + set nat66 source rule 10 description 'NPT to VLAN 10' + set nat66 source rule 10 outbound-interface name 'bond0.20' + set nat66 source rule 10 source prefix 'fd52:d62e:8011:a::/64' + set nat66 source rule 10 translation address '2001:db8:123:b008::/64' + set nat66 source rule 20 description 'NPT to VLAN 70' + set nat66 source rule 20 outbound-interface name 'bond0.20' + set nat66 source rule 20 source prefix 'fd52:d62e:8011:46::/64' + set nat66 source rule 20 translation address '2001:db8:123:b009::/64' + set nat66 source rule 30 description 'NPT to VLAN 200' + set nat66 source rule 30 outbound-interface name 'bond0.20' + set nat66 source rule 30 source prefix 'fd52:d62e:8011:c8::/64' + set nat66 source rule 30 translation address '2001:db8:123:b00a::/64' + set nat66 source rule 40 description 'NPT to VLAN 240' + set nat66 source rule 40 outbound-interface name 'bond0.20' + set nat66 source rule 40 source prefix 'fd52:d62e:8011:f0::/64' + set nat66 source rule 40 translation address '2001:db8:123:b00b::/64' + commit + +Configure the B-side router for NPTv6 using the prefixes above: + +.. code-block:: none + + set nat66 source rule 10 description 'NPT to VLAN 10' + set nat66 source rule 10 outbound-interface name 'bond0.20' + set nat66 source rule 10 source prefix 'fd52:d62e:8011:a::/64' + set nat66 source rule 10 translation address '2001:db8:123:b00c::/64' + set nat66 source rule 20 description 'NPT to VLAN 70' + set nat66 source rule 20 outbound-interface name 'bond0.20' + set nat66 source rule 20 source prefix 'fd52:d62e:8011:46::/64' + set nat66 source rule 20 translation address '2001:db8:123:b00d::/64' + set nat66 source rule 30 description 'NPT to VLAN 200' + set nat66 source rule 30 outbound-interface name 'bond0.20' + set nat66 source rule 30 source prefix 'fd52:d62e:8011:c8::/64' + set nat66 source rule 30 translation address '2001:db8:123:b00e::/64' + set nat66 source rule 40 description 'NPT to VLAN 240' + set nat66 source rule 40 outbound-interface name 'bond0.20' + set nat66 source rule 40 source prefix 'fd52:d62e:8011:f0::/64' + set nat66 source rule 40 translation address '2001:db8:123:b00f::/64' + commit + +Verify that connections are hitting the rule on both sides: + +.. code-block:: none + + trae@cr01a-vyos# run show nat66 source statistics + Rule Packets Bytes Interface + ------ --------- ------- ----------- + 10 1 104 bond0.20 + 20 1 104 bond0.20 + 30 8093 669445 bond0.20 + 40 2446 216912 bond0.20 diff --git a/docs/configuration/pki/index.rst b/docs/configuration/pki/index.rst index 66ad84a3..1fea13ac 100644 --- a/docs/configuration/pki/index.rst +++ b/docs/configuration/pki/index.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-09-01 +:lastproofread: 2024-01-05 .. include:: /_include/need_improvement.txt @@ -248,6 +248,44 @@ certificates used by services on this router. If CA is present, this certificate will be included in generated CRLs +ACME +^^^^ + +The VyOS PKI subsystem can also be used to automatically retrieve Certificates +using the :abbr:`ACME (Automatic Certificate Management Environment)` protocol. + +.. cfgcmd:: set pki certificate <name> acme domain-name <name> + + Domain names to apply, multiple domain-names can be specified. + + This is a mandatory option + +.. cfgcmd:: set pki certificate <name> acme email <address> + + Email used for registration and recovery contact. + + This is a mandatory option + +.. cfgcmd:: set pki certificate <name> acme listen-address <address> + + The address the server listens to during http-01 challenge + +.. cfgcmd:: set pki certificate <name> acme rsa-key-size <2048 | 3072 | 4096> + + Size of the RSA key. + + This options defaults to 2048 + +.. cfgcmd:: set pki certificate <name> acme url <url> + + ACME Directory Resource URI. + + This defaults to https://acme-v02.api.letsencrypt.org/directory + + .. note:: During initial deployment we recommend using the staging API + of LetsEncrypt to prevent and blacklisting of your system. The API + endpoint is https://acme-staging-v02.api.letsencrypt.org/directory + Operation ========= @@ -292,3 +330,7 @@ also to display them. .. opcmd:: show pki crl Show a list of installed :abbr:`CRLs (Certificate Revocation List)`. + +.. opcmd:: renew certbot + + Manually trigger certificate renewal. This will be done twice a day. diff --git a/docs/configuration/policy/route-map.rst b/docs/configuration/policy/route-map.rst index 9fe1eef7..07cfcf02 100644 --- a/docs/configuration/policy/route-map.rst +++ b/docs/configuration/policy/route-map.rst @@ -318,10 +318,12 @@ Route Map Set BGP local preference attribute. .. cfgcmd:: set policy route-map <text> rule <1-65535> set metric - <+/-metric|0-4294967295> + <+/-metric|0-4294967295|rtt|+rtt|-rtt> - Set destination routing protocol metric. Add or subtract metric, or set - metric value. + Set the route metric. When used with BGP, set the BGP attribute MED + to a specific value. Use ``+/-`` to add or subtract the specified value + to/from the existing/MED. Use ``rtt`` to set the MED to the round trip + time or ``+rtt/-rtt`` to add/subtract the round trip time to/from the MED. .. cfgcmd:: set policy route-map <text> rule <1-65535> set metric-type <type-1|type-2> diff --git a/docs/configuration/protocols/bgp.rst b/docs/configuration/protocols/bgp.rst index 737e98fa..8fc69111 100644 --- a/docs/configuration/protocols/bgp.rst +++ b/docs/configuration/protocols/bgp.rst @@ -952,7 +952,7 @@ Operational Mode Commands Show ==== -.. opcmd:: show <ip|ipv6> bgp +.. opcmd:: show bgp <ipv4|ipv6> This command displays all entries in BGP routing table. @@ -964,6 +964,7 @@ Show i internal, r RIB-failure, S Stale, R Removed Nexthop codes: @NNN nexthop's vrf id, < announce-nh-self Origin codes: i - IGP, e - EGP, ? - incomplete + RPKI validation codes: V valid, I invalid, N Not found Network Next Hop Metric LocPrf Weight Path *> 198.51.100.0/24 10.0.34.4 0 0 65004 i @@ -971,7 +972,7 @@ Show Displayed 2 routes and 2 total paths -.. opcmd:: show <ip|ipv6> bgp <address|prefix> +.. opcmd:: show bgp <ipv4|ipv6> <address|prefix> This command displays information about the particular entry in the BGP routing table. @@ -991,55 +992,55 @@ Show This command displays routes with classless interdomain routing (CIDR). -.. opcmd:: show <ip|ipv6> bgp community <value> +.. opcmd:: show bgp <ipv4|ipv6> community <value> This command displays routes that belong to specified BGP communities. Valid value is a community number in the range from 1 to 4294967200, or AA:NN (autonomous system-community number/2-byte number), no-export, local-as, or no-advertise. -.. opcmd:: show <ip|ipv6> bgp community-list <name> +.. opcmd:: show bgp <ipv4|ipv6> community-list <name> This command displays routes that are permitted by the BGP community list. -.. opcmd:: show ip bgp dampened-paths +.. opcmd:: show bgp <ipv4|ipv6> dampening dampened-paths This command displays BGP dampened routes. -.. opcmd:: show ip bgp flap-statistics +.. opcmd:: show bgp <ipv4|ipv6> dampening flap-statistics This command displays information about flapping BGP routes. -.. opcmd:: show ip bgp filter-list <name> +.. opcmd:: show bgp <ipv4|ipv6> filter-list <name> This command displays BGP routes allowed by the specified AS Path access list. -.. opcmd:: show <ip|ipv6> bgp neighbors <address> advertised-routes +.. opcmd:: show bgp <ipv4|ipv6> neighbors <address> advertised-routes This command displays BGP routes advertised to a neighbor. -.. opcmd:: show <ip|ipv6> bgp neighbors <address> received-routes +.. opcmd:: show bgp <ipv4|ipv6> neighbors <address> received-routes This command displays BGP routes originating from the specified BGP neighbor before inbound policy is applied. To use this command inbound soft reconfiguration must be enabled. -.. opcmd:: show <ip|ipv6> bgp neighbors <address> routes +.. opcmd:: show bgp <ipv4|ipv6> neighbors <address> routes This command displays BGP received-routes that are accepted after filtering. -.. opcmd:: show <ip|ipv6> bgp neighbors <address> dampened-routes +.. opcmd:: show bgp <ipv4|ipv6> neighbors <address> dampened-routes This command displays dampened routes received from BGP neighbor. -.. opcmd:: show <ip|ipv6> bgp regexp <text> +.. opcmd:: show bgp <ipv4|ipv6> regexp <text> This command displays information about BGP routes whose AS path matches the specified regular expression. -.. opcmd:: show <ip|ipv6> bgp summary +.. opcmd:: show bgp <ipv4|ipv6> summary This command displays the status of all BGP connections. diff --git a/docs/configuration/protocols/isis.rst b/docs/configuration/protocols/isis.rst index 18a7c166..1f779d0a 100644 --- a/docs/configuration/protocols/isis.rst +++ b/docs/configuration/protocols/isis.rst @@ -302,6 +302,34 @@ Timers control the timing of the execution of SPF calculations in response to IGP events. The process described in :rfc:`8405`. +Loop Free Alternate (LFA) +------------------------- + +.. cfgcmd:: set protocols isis fast-reroute lfa remote prefix-list <name> + <level-1|level-2> + + This command enables IP fast re-routing that is part of :rfc:`5286`. + Specifically this is a prefix list which references a prefix in which + will select eligible PQ nodes for remote LFA backups. + +.. cfgcmd:: set protocols isis fast-reroute lfa local load-sharing disable + <level-1|level-2> + + This command disables the load sharing across multiple LFA backups. + +.. cfgcmd:: set protocols isis fast-reroute lfa local tiebreaker + <downstream|lowest-backup-metric|node-protecting> index <number> + <level-1|level-2> + + This command will configure a tie-breaker for multiple local LFA backups. + The lower index numbers will be processed first. + +.. cfgcmd:: set protocols isis fast-reroute lfa local priority-limit + <medium|high|critical> <level-1|level-2> + + This command will limit LFA backup computation up to the specified + prefix priority. + ******** Examples diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst index b5b12a5b..c51a0aff 100644 --- a/docs/configuration/service/dhcp-server.rst +++ b/docs/configuration/service/dhcp-server.rst @@ -4,7 +4,7 @@ DHCP Server ########### -VyOS uses ISC DHCP server for both IPv4 and IPv6 address assignment. +VyOS uses Kea DHCP server for both IPv4 and IPv6 address assignment. *********** IPv4 server @@ -26,12 +26,7 @@ Configuration Create DNS record per client lease, by adding clients to /etc/hosts file. Entry will have format: `<shared-network-name>_<hostname>.<domain-name>` -.. cfgcmd:: set service dhcp-server host-decl-name - - Will drop `<shared-network-name>_` from client DNS record, using only the - host declaration name and domain: `<hostname>.<domain-name>` - -.. cfgcmd:: set service dhcp-server shared-network-name <name> domain-name <domain-name> +.. cfgcmd:: set service dhcp-server shared-network-name <name> option domain-name <domain-name> The domain-name parameter should be the domain name that will be appended to the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP @@ -40,7 +35,7 @@ Configuration This is the configuration parameter for the entire shared network definition. All subnets will inherit this configuration item if not specified locally. -.. cfgcmd:: set service dhcp-server shared-network-name <name> domain-search <domain-name> +.. cfgcmd:: set service dhcp-server shared-network-name <name> option domain-search <domain-name> The domain-name parameter should be the domain name used when completing DNS request where no full FQDN is passed. This option can be given multiple times @@ -49,7 +44,7 @@ Configuration This is the configuration parameter for the entire shared network definition. All subnets will inherit this configuration item if not specified locally. -.. cfgcmd:: set service dhcp-server shared-network-name <name> name-server <address> +.. cfgcmd:: set service dhcp-server shared-network-name <name> option name-server <address> Inform client that the DNS server can be found at `<address>`. @@ -58,21 +53,6 @@ Configuration Multiple DNS servers can be defined. -.. cfgcmd:: set service dhcp-server shared-network-name <name> ping-check - - When the DHCP server is considering dynamically allocating an IP address to a - client, it first sends an ICMP Echo request (a ping) to the address being - assigned. It waits for a second, and if no ICMP Echo response has been heard, - it assigns the address. - - If a response is heard, the lease is abandoned, and the server does not - respond to the client. The lease will remain abandoned for a minimum of - abandon-lease-time seconds (defaults to 24 hours). - - If there are no free addresses but there are abandoned IP addresses, the - DHCP server will attempt to reclaim an abandoned IP address regardless of the - value of abandon-lease-time. - .. cfgcmd:: set service dhcp-server listen-address <address> This configuration parameter lets the DHCP server to listen for DHCP @@ -91,14 +71,20 @@ Individual Client Subnet network. .. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> - default-router <address> + subnet-id <id> + + This configuration parameter is required and must be unique to each subnet. + It is required to map subnets to lease file entries. + +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + option default-router <address> This is a configuration parameter for the `<subnet>`, saying that as part of the response, tell the client that the default gateway can be reached at `<address>`. .. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> - name-server <address> + option name-server <address> This is a configuration parameter for the subnet, saying that as part of the response, tell the client that the DNS server can be found at `<address>`. @@ -133,40 +119,19 @@ Individual Client Subnet This option can be specified multiple times. .. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> - domain-name <domain-name> + option domain-name <domain-name> The domain-name parameter should be the domain name that will be appended to the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP Option 015). .. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> - domain-search <domain-name> + option domain-search <domain-name> The domain-name parameter should be the domain name used when completing DNS request where no full FQDN is passed. This option can be given multiple times if you need multiple search domains (DHCP Option 119). -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> - ping-check - - When the DHCP server is considering dynamically allocating an IP address to a - client, it first sends an ICMP Echo request (a ping) to the address being - assigned. It waits for a second, and if no ICMP Echo response has been heard, - it assigns the address. - - If a response is heard, the lease is abandoned, and the server does not - respond to the client. The lease will remain abandoned for a minimum of - abandon-lease-time seconds (defaults to 24 hours). - - If a there are no free addresses but there are abandoned IP addresses, the - DHCP server will attempt to reclaim an abandoned IP address regardless of the - value of abandon-lease-time. - -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> - enable-failover - - Enable DHCP failover configuration for this address pool. - Failover -------- @@ -238,6 +203,7 @@ inside the subnet definition but can be outside of the range statement. .. code-block:: none + set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 subnet-id 1 set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 static-mapping client1 ip-address 192.168.1.100 set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 static-mapping client1 mac-address aa:bb:11:22:33:00 @@ -251,6 +217,7 @@ The configuration will look as follows: ip-address 192.168.1.100 mac-address aa:bb:11:22:33:00 } + subnet-id 1 } Options @@ -391,32 +358,6 @@ Options Multi: can be specified multiple times. -Raw Parameters -============== - -Raw parameters can be passed to shared-network-name, subnet and static-mapping: - -.. code-block:: none - - set service dhcp-server shared-network-name <name> shared-network-parameters - <text> Additional shared-network parameters for DHCP server. - set service dhcp-server shared-network-name <name> subnet <subnet> subnet-parameters - <text> Additional subnet parameters for DHCP server. - set service dhcp-server shared-network-name <name> subnet <subnet> static-mapping <description> static-mapping-parameters - <text> Additional static-mapping parameters for DHCP server. - Will be placed inside the "host" block of the mapping. - -These parameters are passed as-is to isc-dhcp's dhcpd.conf under the -configuration node they are defined in. They are not validated so an error in -the raw parameters won't be caught by vyos's scripts and will cause dhcpd to -fail to start. Always verify that the parameters are correct before committing -the configuration. Refer to isc-dhcp's dhcpd.conf manual for more information: -https://kb.isc.org/docs/isc-dhcp-44-manual-pages-dhcpdconf - -Quotes can be used inside parameter values by replacing all quote characters -with the string ``"``. They will be replaced with literal quote characters -when generating dhcpd.conf. - Example ======= @@ -439,12 +380,12 @@ Common configuration, valid for both primary and secondary node. .. code-block:: none - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 default-router '192.0.2.254' - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 name-server '192.0.2.254' - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 domain-name 'vyos.net' + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 option default-router '192.0.2.254' + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 option name-server '192.0.2.254' + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 option domain-name 'vyos.net' set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 start '192.0.2.10' set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 stop '192.0.2.250' - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 enable-failover + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 subnet-id '1' **Primary** @@ -467,47 +408,6 @@ Common configuration, valid for both primary and secondary node. .. _dhcp-server:v4_example_raw: -Raw Parameters --------------- - -* Override static-mapping's name-server with a custom one that will be sent only - to this host. -* An option that takes a quoted string is set by replacing all quote characters - with the string ``"`` inside the static-mapping-parameters value. - The resulting line in dhcpd.conf will be - ``option pxelinux.configfile "pxelinux.cfg/01-00-15-17-44-2d-aa";``. - - -.. code-block:: none - - set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option domain-name-servers 192.0.2.11, 192.0.2.12;" - set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option pxelinux.configfile "pxelinux.cfg/01-00-15-17-44-2d-aa";" - -Option 43 for UniFI -------------------- - -* These parameters need to be part of the DHCP global options. - They stay unchanged. - - -.. code-block:: none - - set service dhcp-server global-parameters 'option space ubnt;' - set service dhcp-server global-parameters 'option ubnt.unifi-address code 1 = ip-address;' - set service dhcp-server global-parameters 'class "ubnt" {' - set service dhcp-server global-parameters 'match if substring (option vendor-class-identifier, 0, 4) = "ubnt";' - set service dhcp-server global-parameters 'option vendor-class-identifier "ubnt";' - set service dhcp-server global-parameters 'vendor-option-space ubnt;' - set service dhcp-server global-parameters '}' - -* Now we add the option to the scope, adapt to your setup - - -.. code-block:: none - - set service dhcp-server shared-network-name example-scope subnet 10.1.1.0/24 subnet-parameters 'option ubnt.unifi-address 172.16.1.10;' - - Operation Mode ============== @@ -549,18 +449,43 @@ Operation Mode .. code-block:: none vyos@vyos:~$ show dhcp server leases - IP address Hardware address State Lease start Lease expiration Remaining Pool Hostname - -------------- ------------------ ------- ------------------- ------------------- ---------- ----------- --------- - 192.0.2.104 00:53:01:dd:ee:ff active 2019/12/05 14:24:23 2019/12/06 02:24:23 6:05:35 dhcpexample test1 - 192.0.2.115 00:53:01:ae:af:bf active 2019/12/05 18:02:37 2019/12/06 06:02:37 9:43:49 dhcpexample test2 + IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname Origin + -------------- ----------------- ------- ------------------- ------------------- ----------- -------- ---------- -------- + 192.168.11.134 00:50:79:66:68:09 active 2023/11/29 09:51:05 2023/11/29 10:21:05 0:24:10 LAN VPCS1 local + 192.168.11.133 50:00:00:06:00:00 active 2023/11/29 09:51:38 2023/11/29 10:21:38 0:24:43 LAN VYOS-6 local + 10.11.11.108 50:00:00:05:00:00 active 2023/11/29 09:51:43 2023/11/29 10:21:43 0:24:48 VIF-1001 VYOS5 local + 192.168.11.135 00:50:79:66:68:07 active 2023/11/29 09:55:16 2023/11/29 09:59:16 0:02:21 remote + vyos@vyos:~$ .. hint:: Static mappings aren't shown. To show all states, use ``show dhcp server leases state all``. +.. opcmd:: show dhcp server leases origin [local | remote] + + Show statuses of all active leases granted by local (this server) or + remote (failover server): + +.. code-block:: none + + vyos@vyos:~$ show dhcp server leases origin remote + IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname Origin + -------------- ----------------- ------- ------------------- ------------------- ----------- -------- ---------- -------- + 192.168.11.135 00:50:79:66:68:07 active 2023/11/29 09:55:16 2023/11/29 09:59:16 0:02:21 remote + vyos@vyos:~$ + .. opcmd:: show dhcp server leases pool <pool> Show only leases in the specified pool. +.. code-block:: none + + vyos@vyos:~$ show dhcp server leases pool LAN + IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname Origin + -------------- ----------------- ------- ------------------- ------------------- ----------- ------ ---------- -------- + 192.168.11.134 00:50:79:66:68:09 active 2023/11/29 09:51:05 2023/11/29 10:21:05 0:23:55 LAN VPCS1 local + 192.168.11.133 50:00:00:06:00:00 active 2023/11/29 09:51:38 2023/11/29 10:21:38 0:24:28 LAN VYOS-6 local + vyos@vyos:~$ + .. opcmd:: show dhcp server leases sort <key> Sort the output by the specified key. Possible keys: ip, hardware_address, @@ -572,7 +497,6 @@ Operation Mode free, expired, released, abandoned, reset, backup (default = active) - *********** IPv6 server *********** @@ -590,6 +514,12 @@ Configuration Clients receiving advertise messages from multiple servers choose the server with the highest preference value. The range for this value is ``0...255``. +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <subnet> + subnet-id <id> + + This configuration parameter is required and must be unique to each subnet. + It is required to map subnets to lease file entries. + .. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> lease-time {default | maximum | minimum} @@ -666,6 +596,7 @@ server. The following example describes a common scenario. set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 address-range start 2001:db8::100 stop 2001:db8::199 set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 name-server 2001:db8::ffff + set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 subnet-id 1 The configuration will look as follows: @@ -680,6 +611,7 @@ The configuration will look as follows: } } name-server 2001:db8::ffff + subnet-id 1 } } diff --git a/docs/configuration/service/dns.rst b/docs/configuration/service/dns.rst index 2caeb22d..7624d309 100644 --- a/docs/configuration/service/dns.rst +++ b/docs/configuration/service/dns.rst @@ -143,6 +143,19 @@ avoid being tracked by the provider of your upstream DNS server. 168.192.in-addr.arpa, 16-31.172.in-addr.arpa, which enabling upstream DNS server(s) to be used for reverse lookups of these zones. +.. cfgcmd:: set service dns forwarding serve-stale-extension <0-65535> + + Maximum number of times an expired record’s TTL is extended by 30s when + serving stale. Extension only occurs if a record cannot be refreshed. A + value of 0 means the Serve Stale mechanism is not used. To allow records + becoming stale to be served for an hour, use a value of 120. + +.. cfgcmd:: set service dns forwarding exclude-throttle-address <ip|prefix> + + When an authoritative server does not answer a query or sends a reply the + recursor does not like, it is throttled. Any servers matching the supplied + netmasks will never be throttled. + Example ======= @@ -381,12 +394,12 @@ By default, ddclient_ will update a dynamic dns record using the IP address directly attached to the interface. If your VyOS instance is behind NAT, your record will be updated to point to your internal IP. -Above, command syntax isn noted to configure dynamic dns on a specific interface. -It is possible to overlook the additional address option, web, when completeing -those commands. ddclient_ has another way to determine the WAN IP address, using -a web-based url to determine the external IP. Each of the commands above will -need to be modified to use 'web' as the 'interface' specified if this functionality -is to be utilized. +Above, command syntax isn noted to configure dynamic dns on a specific interface. +It is possible to overlook the additional address option, web, when completeing +those commands. ddclient_ has another way to determine the WAN IP address, using +a web-based url to determine the external IP. Each of the commands above will +need to be modified to use 'web' as the 'interface' specified if this functionality +is to be utilized. This functionality is controlled by adding the following configuration: diff --git a/docs/configuration/service/https.rst b/docs/configuration/service/https.rst index eb2e30eb..973c5355 100644 --- a/docs/configuration/service/https.rst +++ b/docs/configuration/service/https.rst @@ -1,7 +1,7 @@ .. _http-api: ######## -HTTP-API +HTTP API ######## VyOS provide an HTTP API. You can use it to execute op-mode commands, @@ -13,75 +13,71 @@ Please take a look at the :ref:`vyosapi` page for an detailed how-to. Configuration ************* -.. cfgcmd:: set service https api keys id <name> key <apikey> +.. cfgcmd:: set service https allow-client address <address> - Set a named api key. Every key has the same, full permissions - on the system. + Only allow certain IP addresses or prefixes to access the https + webserver. -.. cfgcmd:: set service https api debug +.. cfgcmd:: set service https certificates ca-certificate <name> - To enable debug messages. Available via :opcmd:`show log` or - :opcmd:`monitor log` + Use CA certificate from PKI subsystem -.. cfgcmd:: set service https api strict +.. cfgcmd:: set service https certificates certificate <name> - Enforce strict path checking + Use certificate from PKI subsystem -.. cfgcmd:: set service https virtual-host <vhost> listen-address - <ipv4 or ipv6 address> +.. cfgcmd:: set service https certificates dh-params <name> - Address to listen for HTTPS requests + Use :abbr:`DH (Diffie–Hellman)` parameters from PKI subsystem. + Must be at least 2048 bits in length. -.. cfgcmd:: set service https virtual-host <vhost> port <1-65535> +.. cfgcmd:: set service https listen-address <address> - Port to listen for HTTPS requests; default 443 + Webserver should only listen on specified IP address -.. cfgcmd:: set service https virtual-host <vhost> server-name <text> +.. cfgcmd:: set service https port <number> - Server names for virtual hosts it can be exact, wildcard or regex. + Webserver should listen on specified port. -.. cfgcmd:: set service https api-restrict virtual-host <vhost> + Default: 443 - By default, nginx exposes the local API on all virtual servers. - Use this to restrict nginx to one or more virtual hosts. +.. cfgcmd:: set service https enable-http-redirect -.. cfgcmd:: set service https certificates certbot domain-name <text> + Enable automatic redirect from http to https. - Domain name(s) for which to obtain certificate +.. cfgcmd:: set service https tls-version <1.2 | 1.3> -.. cfgcmd:: set service https certificates certbot email + Select TLS version used. - Email address to associate with certificate + This defaults to both 1.2 and 1.3. -.. cfgcmd:: set service https certificates system-generated-certificate +.. cfgcmd:: set service https vrf <name> - Use an automatically generated self-signed certificate + Start Webserver in given VRF. -.. cfgcmd:: set service https certificates system-generated-certificate - lifetime <days> +API +=== - Lifetime in days; default is 365 +.. cfgcmd:: set service https api keys id <name> key <apikey> + Set a named api key. Every key has the same, full permissions + on the system. -********************* -Example Configuration -********************* +.. cfgcmd:: set service https api debug -Set an API-KEY is the minimal configuration to get a working API Endpoint. + To enable debug messages. Available via :opcmd:`show log` or + :opcmd:`monitor log` -.. code-block:: none +.. cfgcmd:: set service https api strict - set service https api keys id MY-HTTPS-API-ID key MY-HTTPS-API-PLAINTEXT-KEY + Enforce strict path checking +********************* +Example Configuration +********************* -To use this full configuration we asume a public accessible hostname. +Set an API-KEY is the minimal configuration to get a working API Endpoint. .. code-block:: none set service https api keys id MY-HTTPS-API-ID key MY-HTTPS-API-PLAINTEXT-KEY - set service https certificates certbot domain-name rtr01.example.com - set service https certificates certbot email mail@example.com - set service https virtual-host rtr01 listen-address 198.51.100.2 - set service https virtual-host rtr01 port 11443 - set service https virtual-host rtr01 server-name rtr01.example.com - set service https api-restrict virtual-host rtr01 diff --git a/docs/configuration/service/lldp.rst b/docs/configuration/service/lldp.rst index aa357211..12a9e0b6 100644 --- a/docs/configuration/service/lldp.rst +++ b/docs/configuration/service/lldp.rst @@ -54,7 +54,7 @@ Configuration Disable transmit of LLDP frames on given `<interface>`. Useful to exclude certain interfaces from LLDP when ``all`` have been enabled. -.. cfgcmd:: set service lldp snmp enable +.. cfgcmd:: set service lldp snmp Enable SNMP queries of the LLDP database diff --git a/docs/configuration/service/monitoring.rst b/docs/configuration/service/monitoring.rst index 0aa93e71..245af067 100644 --- a/docs/configuration/service/monitoring.rst +++ b/docs/configuration/service/monitoring.rst @@ -109,11 +109,11 @@ Monitoring functionality with ``telegraf`` and ``InfluxDB 2`` is provided. Telegraf is the open source server agent to help you collect metrics, events and logs from your routers. -.. cfgcmd:: set service monitoring telegraf authentication organization <organization> +.. cfgcmd:: set service monitoring telegraf influxdb authentication organization <organization> Authentication organization name -.. cfgcmd:: set service monitoring telegraf authentication token <token> +.. cfgcmd:: set service monitoring telegraf influxdb authentication token <token> Authentication token @@ -121,11 +121,11 @@ and logs from your routers. Remote ``InfluxDB`` bucket name -.. cfgcmd:: set service monitoring port <port> +.. cfgcmd:: set service monitoring telegraf influxdb port <port> Remote port -.. cfgcmd:: set service monitoring telegraf url <url> +.. cfgcmd:: set service monitoring telegraf influxdb url <url> Remote URL @@ -138,12 +138,11 @@ An example of a configuration that sends ``telegraf`` metrics to remote .. code-block:: none - set service monitoring telegraf authentication organization 'vyos' - set service monitoring telegraf authentication token 'ZAml9Uy5wrhA...==' - set service monitoring telegraf bucket 'bucket_vyos' - set service monitoring telegraf port '8086' - set service monitoring telegraf source 'all' - set service monitoring telegraf url 'http://r1.influxdb2.local' + set service monitoring telegraf influxdb authentication organization 'vyos' + set service monitoring telegraf influxdb authentication token 'ZAml9Uy5wrhA...==' + set service monitoring telegraf influxdb bucket 'bucket_vyos' + set service monitoring telegraf influxdb port '8086' + set service monitoring telegraf influxdb url 'http://r1.influxdb2.local' .. _azure-data-explorer: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/azure_data_explorer .. _prometheus-client: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/prometheus_client diff --git a/docs/configuration/service/pppoe-server.rst b/docs/configuration/service/pppoe-server.rst index 3a0adee7..a230d9fe 100644 --- a/docs/configuration/service/pppoe-server.rst +++ b/docs/configuration/service/pppoe-server.rst @@ -57,48 +57,35 @@ Client Address Pools -------------------- To automatically assign the client an IP address as tunnel endpoint, a -client IP pool is needed. The source can be either RADIUS or a local -subnet or IP range definition. - -Once the local tunnel endpoint ``set service pppoe-server gateway-address -'10.1.1.2'`` has been defined, the client IP pool can be either defined -as a range or as subnet using CIDR notation. If the CIDR notation is -used, multiple subnets can be setup which are used sequentially. +client IP pool is needed. The source can be either RADIUS or a +named pool. There is possibility to create multiple named pools. +Each named pool can include only one address range. To use multiple +address ranges configure ``next-pool`` option. **Client IP address via IP range definition** -.. cfgcmd:: set service pppoe-server client-ip-pool start <address> - - Use this command to define the first IP address of a pool of - addresses to be given to PPPoE clients. It must be within a /24 - subnet. - -.. cfgcmd:: set service pppoe-server client-ip-pool stop <address> - - Use this command to define the last IP address of a pool of - addresses to be given to PPPoE clients. It must be within a /24 - subnet. - -.. code-block:: none +.. cfgcmd:: set service pppoe-server client-ip-pool <POOL-NAME> range <x.x.x.x-x.x.x.x | x.x.x.x/x> - set service pppoe-server client-ip-pool start '10.1.1.100' - set service pppoe-server client-ip-pool stop '10.1.1.111' + Use this command to define the IP address range to be given + to PPPoE clients. If notation ``x.x.x.x-x.x.x.x``, + it must be within a /24 subnet. If notation ``x.x.x.x/x`` is + used there is possibility to set host/netmask. +.. cfgcmd:: set service pppoe-server client-ip-pool <POOL-NAME> next-pool <NEXT-POOL-NAME> -**Client IP subnets via CIDR notation** + Use this command to define the next address pool name. -.. cfgcmd:: set service pppoe-server client-ip-pool subnet <address> +.. cfgcmd:: set service pppoe-server default-pool <POOL-NAME> - Use this command for every pool of client IP addresses you want to - define. The addresses of this pool will be given to PPPoE clients. - You must use CIDR notation. + Use this command to define default address pool name. .. code-block:: none - set service pppoe-server client-ip-pool subnet '10.1.1.0/24' - set service pppoe-server client-ip-pool subnet '10.1.2.0/23' - set service pppoe-server client-ip-pool subnet '10.1.4.0/22' + set service pppoe-server client-ip-pool IP-POOL next-pool 'IP-POOL2' + set service pppoe-server client-ip-pool IP-POOL range '10.0.10.5/24' + set service pppoe-server client-ip-pool IP-POOL2 range '10.0.0.10-10.0.0.12' + set service pppoe-server default-pool 'IP-POOL' **RADIUS based IP pools (Framed-IP-Address)** @@ -213,8 +200,8 @@ For Local Users set service pppoe-server authentication local-users username foo rate-limit download '20480' set service pppoe-server authentication local-users username foo rate-limit upload '10240' set service pppoe-server authentication mode 'local' - set service pppoe-server client-ip-pool start '10.1.1.100' - set service pppoe-server client-ip-pool stop '10.1.1.111' + set service pppoe-server client-ip-pool IP-POOL range '10.1.1.100/24' + set service pppoe-server default-pool 'IP-POOL' set service pppoe-server name-server '10.100.100.1' set service pppoe-server name-server '10.100.200.1' set service pppoe-server interface 'eth1' @@ -367,8 +354,8 @@ address from the pool 10.1.1.100-111, terminates at the local endpoint set service pppoe-server access-concentrator 'ACN' set service pppoe-server authentication local-users username foo password 'bar' set service pppoe-server authentication mode 'local' - set service pppoe-server client-ip-pool start '10.1.1.100' - set service pppoe-server client-ip-pool stop '10.1.1.111' + set service pppoe-server client-ip-pool IP-POOL range '10.1.1.100-10.1.1.111' + set service pppoe-server default-pool 'IP-POOL' set service pppoe-server interface eth1 set service pppoe-server gateway-address '10.1.1.2' set service pppoe-server name-server '10.100.100.1' @@ -385,8 +372,8 @@ The example below covers a dual-stack configuration via pppoe-server. set service pppoe-server authentication local-users username test password 'test' set service pppoe-server authentication mode 'local' - set service pppoe-server client-ip-pool start '192.168.0.1' - set service pppoe-server client-ip-pool stop '192.168.0.10' + set service pppoe-server client-ip-pool IP-POOL range '192.168.0.1/24' + set service pppoe-server default-pool 'IP-POOL' set service pppoe-server client-ipv6-pool delegate '2001:db8:8003::/48' delegation-prefix '56' set service pppoe-server client-ipv6-pool prefix '2001:db8:8002::/48' mask '64' set service pppoe-server ppp-options ipv6 allow diff --git a/docs/configuration/system/conntrack.rst b/docs/configuration/system/conntrack.rst index 68a4f2b8..6ed5fef7 100644 --- a/docs/configuration/system/conntrack.rst +++ b/docs/configuration/system/conntrack.rst @@ -46,9 +46,23 @@ Configure | Use `delete system conntrack modules` to deactive all modules. | Or, for example ftp, `delete system conntrack modules ftp`. +.. cfgcmd:: set system conntrack tcp half-open-connections <1-21474836> + :defaultvalue: -Define Conection Timeouts -========================= + Set the maximum number of TCP half-open connections. + +.. cfgcmd:: set system conntrack tcp loose <enable | disable> + :defaultvalue: + + Policy to track previously established connections. + +.. cfgcmd:: set system conntrack tcp max-retrans <1-2147483647> + :defaultvalue: + + Set the number of TCP maximum retransmit attempts. + +Contrack Timeouts +================= VyOS supports setting timeouts for connections according to the connection type. You can set timeout values for generic connections, for ICMP @@ -82,34 +96,48 @@ states. Set the timeout in secounds for a protocol or state. - You can also define custom timeout values to apply to a specific subset of connections, based on a packet and flow selector. To do this, you need to create a rule defining the packet and flow selector. -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> description <test> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + description <test> Set a rule description. +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + destination address <ip-address> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + source address <ip-address> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> destination address <ip-address> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> source address <ip-address> - - set a destination and/or source address. Accepted input: + Set a destination and/or source address. Accepted input for ipv4: .. code-block:: none - <x.x.x.x> IP address to match - <x.x.x.x/x> Subnet to match - <x.x.x.x>-<x.x.x.x> - IP range to match - !<x.x.x.x> Match everything except the specified address - !<x.x.x.x/x> Match everything except the specified subnet - !<x.x.x.x>-<x.x.x.x> - Match everything except the specified range - -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> destination port <value> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> source port <value> + set system conntrack timeout custom ipv4 rule <1-999999> [source | destination] address + Possible completions: + <x.x.x.x> IPv4 address to match + <x.x.x.x/x> IPv4 prefix to match + <x.x.x.x>-<x.x.x.x> IPv4 address range to match + !<x.x.x.x> Match everything except the specified address + !<x.x.x.x/x> Match everything except the specified prefix + !<x.x.x.x>-<x.x.x.x> Match everything except the specified range + + set system conntrack timeout custom ipv6 rule <1-999999> [source | destination] address + Possible completions: + <h:h:h:h:h:h:h:h> IP address to match + <h:h:h:h:h:h:h:h/x> Subnet to match + <h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h> + IP range to match + !<h:h:h:h:h:h:h:h> Match everything except the specified address + !<h:h:h:h:h:h:h:h/x> Match everything except the specified prefix + !<h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h> + Match everything except the specified range + +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + destination port <value> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + source port <value> Set a destination and/or source port. Accepted input: @@ -123,49 +151,58 @@ create a rule defining the packet and flow selector. The whole list can also be "negated" using '!'. For example: `!22,telnet,http,123,1001-1005`` - - -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol icmp <1-21474836> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol other <1-21474836> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp close <1-21474836> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp close-wait <1-21474836> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp established <1-21474836> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp fin-wait <1-21474836> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp last-ack <1-21474836> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp syn-recv <1-21474836> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp syn-sent <1-21474836> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp time-wait <1-21474836> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol udp other <1-21474836> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol udp stream <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp close <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp close-wait <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp established <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp fin-wait <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp last-ack <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp syn-recv <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp syn-sent <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp time-wait <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol udp replied <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol udp unreplied <1-21474836> Set the timeout in secounds for a protocol or state in a custom rule. - -.. cfgcmd:: set system conntrack tcp half-open-connections <1-21474836> - :defaultvalue: - - Set the maximum number of TCP half-open connections. - -.. cfgcmd:: set system conntrack tcp loose <enable | disable> - :defaultvalue: - - Policy to track previously established connections. - -.. cfgcmd:: set system conntrack tcp max-retrans <1-2147483647> - :defaultvalue: - - Set the number of TCP maximum retransmit attempts. - -.. cfgcmd:: set system conntrack ignore rule <1-9999> description <text> -.. cfgcmd:: set system conntrack ignore rule <1-9999> destination address <ip-address> -.. cfgcmd:: set system conntrack ignore rule <1-9999> destination port <port> -.. cfgcmd:: set system conntrack ignore rule <1-9999> inbound-interface <interface> -.. cfgcmd:: set system conntrack ignore rule <1-9999> protocol <protocol> -.. cfgcmd:: set system conntrack ignore rule <1-9999> source address <ip-address> -.. cfgcmd:: set system conntrack ignore rule <1-9999> source port <port> +Conntrack ignore rules +====================== Customized ignore rules, based on a packet and flow selector. +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + description <text> +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + destination address <ip-address> +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + destination port <port> +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + inbound-interface <interface> +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + protocol <protocol> +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + source address <ip-address> +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + source port <port> +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + tcp flags [not] <text> + + Allowed values fpr TCP flags: ``ack``, ``cwr``, ``ecn``, ``fin``, ``psh``, + ``rst``, ``syn`` and ``urg``. Multiple values are supported, and for + inverted selection use ``not``, as shown in the example. + +Conntrack log +============= + .. cfgcmd:: set system conntrack log icmp destroy .. cfgcmd:: set system conntrack log icmp new .. cfgcmd:: set system conntrack log icmp update diff --git a/docs/configuration/system/frr.rst b/docs/configuration/system/frr.rst new file mode 100644 index 00000000..a7f7ff93 --- /dev/null +++ b/docs/configuration/system/frr.rst @@ -0,0 +1,38 @@ +.. _system_frr: + +### +FRR +### + +VyOS uses [FRRouting](https://frrouting.org/) as the control plane for dynamic +and static routing. The routing daemon behavior can be adjusted during runtime, +but require either a restart of the routing daemon, or a reboot of the system. + +.. cfgcmd:: set system frr bmp + + Enable :abbr:`BMP (BGP Monitoring Protocol)` support + +.. cfgcmd:: set system frr descriptors <numer> + + This allows the operator to control the number of open file descriptors + each daemon is allowed to start with. If the operator plans to run bgp with + several thousands of peers then this is where we would modify FRR to allow + this to happen. + +.. cfgcmd:: set system frr irdp + + Enable ICMP Router Discovery Protocol support + +.. cfgcmd:: set system frr snmp <daemon> + + Enable SNMP support for an individual routing daemon. + + Supported daemons: + + - bgpd + - isisd + - ldpd + - ospf6d + - ospfd + - ripd + - zebra diff --git a/docs/configuration/system/index.rst b/docs/configuration/system/index.rst index 23edaa3f..dbb63d09 100644 --- a/docs/configuration/system/index.rst +++ b/docs/configuration/system/index.rst @@ -11,6 +11,7 @@ System conntrack console flow-accounting + frr host-name ip ipv6 @@ -24,6 +25,7 @@ System sysctl task-scheduler time-zone + updates .. toctree:: diff --git a/docs/configuration/system/ipv6.rst b/docs/configuration/system/ipv6.rst index 076efdae..c7308f9d 100644 --- a/docs/configuration/system/ipv6.rst +++ b/docs/configuration/system/ipv6.rst @@ -81,6 +81,7 @@ Show commands static Show IPv6 static routes summary Show IPv6 routes summary table Show IP routes in policy table + tag Show only routes with tag vrf Show IPv6 routes in VRF @@ -112,33 +113,6 @@ Show commands <Enter> Execute the current command <text> Show specified IPv6 access-list -.. opcmd:: show ipv6 bgp - - Use this command to show IPv6 Border Gateway Protocol information. - - - In addition, you can specify many other parameters to get BGP - information: - - .. code-block:: none - - vyos@vyos:~$ show ipv6 bgp - Possible completions: - <Enter> Execute the current command - <X:X::X:X> Show BGP information for given address or prefix - <X:X::X:X/M> - community Show routes matching the communities - community-list - Show routes matching the community-list - filter-list Show routes conforming to the filter-list - large-community - Show routes matching the large-community-list - large-community-list - neighbors Show detailed information on TCP and BGP neighbor connections - prefix-list Show routes matching the prefix-list - regexp Show routes matching the AS path regular expression - route-map Show BGP routes matching the specified route map - summary Show summary of BGP neighbor status .. opcmd:: show ipv6 ospfv3 diff --git a/docs/configuration/system/name-server.rst b/docs/configuration/system/name-server.rst index f18cb5a3..5d08dbc5 100644 --- a/docs/configuration/system/name-server.rst +++ b/docs/configuration/system/name-server.rst @@ -48,7 +48,7 @@ In order for the system to use and complete unqualified host names, a list can be defined which will be used for domain searches. -.. cfgcmd:: set system domain-search domain <domain> +.. cfgcmd:: set system domain-search <domain> Use this command to define domains, one at a time, so that the system uses them to complete unqualified host names. Maximum: 6 entries. @@ -68,7 +68,7 @@ order: vyos.io (first), vyos.net (second) and vyos.network (last): .. code-block:: none - set system domain-search domain vyos.io - set system domain-search domain vyos.net - set system domain-search domain vyos.network + set system domain-search vyos.io + set system domain-search vyos.net + set system domain-search vyos.network diff --git a/docs/configuration/system/updates.rst b/docs/configuration/system/updates.rst new file mode 100644 index 00000000..505d9318 --- /dev/null +++ b/docs/configuration/system/updates.rst @@ -0,0 +1,39 @@ +####### +Updates +####### + +VyOS supports online checking for updates + +Configuration +============= + +.. cfgcmd:: set system update-check auto-check + + Configure auto-checking for new images + + +.. cfgcmd:: set system update-check url <url> + + Configure a URL that contains information about images. + + +Example +======= + +.. code-block:: none + + set system update-check auto-check + set system update-check url 'https://raw.githubusercontent.com/vyos/vyos-rolling-nightly-builds/main/version.json' + +Check: + +.. code-block:: none + + vyos@r4:~$ show system updates + Current version: 1.5-rolling-202312220023 + + Update available: 1.5-rolling-202312250024 + Update URL: https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.5-rolling-202312250024/1.5-rolling-202312250024-amd64.iso + vyos@r4:~$ + + vyos@r4:~$ add system image latest diff --git a/docs/configuration/vpn/l2tp.rst b/docs/configuration/vpn/l2tp.rst index 26de47b3..4a7657e7 100644 --- a/docs/configuration/vpn/l2tp.rst +++ b/docs/configuration/vpn/l2tp.rst @@ -17,8 +17,8 @@ with native Windows and Mac VPN clients): set vpn ipsec interface eth0 set vpn l2tp remote-access outside-address 192.0.2.2 - set vpn l2tp remote-access client-ip-pool start 192.168.255.2 - set vpn l2tp remote-access client-ip-pool stop 192.168.255.254 + set vpn l2tp remote-access client-ip-pool L2TP-POOL range 192.168.255.2-192.168.255.254 + set vpn l2tp remote-access default-pool 'L2TP-POOL' set vpn l2tp remote-access ipsec-settings authentication mode pre-shared-secret set vpn l2tp remote-access ipsec-settings authentication pre-shared-secret <secret> set vpn l2tp remote-access authentication mode local @@ -95,8 +95,8 @@ Below is an example to configure a LNS: .. code-block:: none set vpn l2tp remote-access outside-address 192.0.2.2 - set vpn l2tp remote-access client-ip-pool start 192.168.255.2 - set vpn l2tp remote-access client-ip-pool stop 192.168.255.254 + set vpn l2tp remote-access client-ip-pool L2TP-POOL range 192.168.255.2-192.168.255.254 + set vpn l2tp remote-access default-pool 'L2TP-POOL' set vpn l2tp remote-access lns shared-secret 'secret' set vpn l2tp remote-access ccp-disable set vpn l2tp remote-access authentication mode local @@ -122,8 +122,8 @@ The rate-limit is set in kbit/sec. .. code-block:: none set vpn l2tp remote-access outside-address 192.0.2.2 - set vpn l2tp remote-access client-ip-pool start 192.168.255.2 - set vpn l2tp remote-access client-ip-pool stop 192.168.255.254 + set vpn l2tp remote-access client-ip-pool L2TP-POOL range 192.168.255.2-192.168.255.254 + set vpn l2tp remote-access default-pool 'L2TP-POOL' set vpn l2tp remote-access authentication mode local set vpn l2tp remote-access authentication local-users username test password test set vpn l2tp remote-access authentication local-users username test rate-limit download 20480 diff --git a/docs/configuration/vpn/openconnect.rst b/docs/configuration/vpn/openconnect.rst index 1cc197e9..845d9196 100644 --- a/docs/configuration/vpn/openconnect.rst +++ b/docs/configuration/vpn/openconnect.rst @@ -165,6 +165,13 @@ Simple setup with one user added and password authentication: set vpn openconnect ssl ca-certificate 'ca-ocserv' set vpn openconnect ssl certificate 'srv-ocserv' +To enable the HTTP security headers in the configuration file, use the command: + +.. code-block:: none + + set vpn openconnect http-security-headers + + Adding a 2FA with an OTP-key ============================ diff --git a/docs/configuration/vpn/pptp.rst b/docs/configuration/vpn/pptp.rst index 12364acb..fe536eec 100644 --- a/docs/configuration/vpn/pptp.rst +++ b/docs/configuration/vpn/pptp.rst @@ -20,8 +20,8 @@ server example set vpn pptp remote-access authentication local-users username test password 'test' set vpn pptp remote-access authentication mode 'local' - set vpn pptp remote-access client-ip-pool start '192.168.0.10' - set vpn pptp remote-access client-ip-pool stop '192.168.0.15' + set vpn pptp remote-access client-ip-pool PPTP-POOL range 192.168.0.10-192.168.0.15 + set vpn pptp remote-access default-pool 'PPTP-POOL' set vpn pptp remote-access gateway-address '10.100.100.1' set vpn pptp remote-access outside-address '10.1.1.120' diff --git a/docs/configuration/vpn/site2site_ipsec.rst b/docs/configuration/vpn/site2site_ipsec.rst index 8c0af774..23df1b76 100644 --- a/docs/configuration/vpn/site2site_ipsec.rst +++ b/docs/configuration/vpn/site2site_ipsec.rst @@ -10,8 +10,8 @@ connected/routed networks. To configure site-to-site connection you need to add peers with the ``set vpn ipsec site-to-site peer <name>`` command. -The peer name must be an alphanumeric and can have hypen or underscore as -special characters. It is purely informational. +The peer name must be an alphanumeric and can have hypen or underscore as +special characters. It is purely informational. Each site-to-site peer has the next options: @@ -20,11 +20,11 @@ Each site-to-site peer has the next options: * ``psk`` - Preshared secret key name: - * ``dhcp-interface`` - ID for authentication generated from DHCP address + * ``dhcp-interface`` - ID for authentication generated from DHCP address dynamically; - * ``id`` - static ID's for authentication. In general local and remote + * ``id`` - static ID's for authentication. In general local and remote address ``<x.x.x.x>``, ``<h:h:h:h:h:h:h:h>`` or ``%any``; - * ``secret`` - predefined shared secret. Used if configured mode + * ``secret`` - predefined shared secret. Used if configured mode ``pre-shared-secret``; @@ -110,7 +110,7 @@ Each site-to-site peer has the next options: * ``remote-address`` - remote IP address or hostname for IPSec connection. IPv4 or IPv6 address is used when a peer has a public static IP address. - Hostname is a DNS name which could be used when a peer has a public IP + Hostname is a DNS name which could be used when a peer has a public IP address and DNS name, but an IP address could be changed from time to time. * ``tunnel`` - define criteria for traffic to be matched for encrypting and send @@ -149,9 +149,9 @@ Each site-to-site peer has the next options: * ``esp-group`` - define ESP group for encrypt traffic, passed this VTI interface. -* ``virtual-address`` - Defines a virtual IP address which is requested by the - initiator and one or several IPv4 and/or IPv6 addresses are assigned from - multiple pools by the responder. +* ``virtual-address`` - Defines a virtual IP address which is requested by the + initiator and one or several IPv4 and/or IPv6 addresses are assigned from + multiple pools by the responder. Examples: ------------------ @@ -308,31 +308,35 @@ Imagine the following topology set interfaces dummy dum0 address '10.0.11.1/24' set interfaces vti vti10 address '10.0.0.2/31' - set vpn ipsec option disable-route-autoinstall - set vpn ipsec authentication psk OFFICE-B id '172.18.201.10' - set vpn ipsec authentication psk OFFICE-B id '172.18.202.10' - set vpn ipsec authentication psk OFFICE-B secret 'secretkey' + set vpn ipsec authentication psk peer_172-18-202-10 id '172.18.201.10' + set vpn ipsec authentication psk peer_172-18-202-10 id '172.18.202.10' + set vpn ipsec authentication psk peer_172-18-202-10 secret 'secretkey' set vpn ipsec esp-group ESP_DEFAULT lifetime '3600' set vpn ipsec esp-group ESP_DEFAULT mode 'tunnel' set vpn ipsec esp-group ESP_DEFAULT pfs 'dh-group19' set vpn ipsec esp-group ESP_DEFAULT proposal 10 encryption 'aes256gcm128' set vpn ipsec esp-group ESP_DEFAULT proposal 10 hash 'sha256' + set vpn ipsec ike-group IKEv2_DEFAULT close-action 'none' + set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection action 'hold' + set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection interval '30' + set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection timeout '120' + set vpn ipsec ike-group IKEv2_DEFAULT disable-mobike set vpn ipsec ike-group IKEv2_DEFAULT key-exchange 'ikev2' set vpn ipsec ike-group IKEv2_DEFAULT lifetime '10800' - set vpn ipsec ike-group IKEv2_DEFAULT disable-mobike set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 dh-group '19' set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 encryption 'aes256gcm128' set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 hash 'sha256' set vpn ipsec interface 'eth0.201' - set vpn ipsec site-to-site peer OFFICE-B authentication local-id '172.18.201.10' - set vpn ipsec site-to-site peer OFFICE-B authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer OFFICE-B authentication remote-id '172.18.202.10' - set vpn ipsec site-to-site peer OFFICE-B connection-type 'respond' - set vpn ipsec site-to-site peer OFFICE-B ike-group 'IKEv2_DEFAULT' - set vpn ipsec site-to-site peer OFFICE-B local-address '172.18.201.10' - set vpn ipsec site-to-site peer OFFICE-B remote-address '172.18.202.10' - set vpn ipsec site-to-site peer OFFICE-B vti bind 'vti10' - set vpn ipsec site-to-site peer OFFICE-B vti esp-group 'ESP_DEFAULT' + set vpn ipsec site-to-site peer peer_172-18-202-10 authentication local-id '172.18.201.10' + set vpn ipsec site-to-site peer peer_172-18-202-10 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer peer_172-18-202-10 authentication remote-id '172.18.202.10' + set vpn ipsec site-to-site peer peer_172-18-202-10 connection-type 'initiate' + set vpn ipsec site-to-site peer peer_172-18-202-10 ike-group 'IKEv2_DEFAULT' + set vpn ipsec site-to-site peer peer_172-18-202-10 ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer peer_172-18-202-10 local-address '172.18.201.10' + set vpn ipsec site-to-site peer peer_172-18-202-10 remote-address '172.18.202.10' + set vpn ipsec site-to-site peer peer_172-18-202-10 vti bind 'vti10' + set vpn ipsec site-to-site peer peer_172-18-202-10 vti esp-group 'ESP_DEFAULT' set protocols static interface-route 10.0.12.0/24 next-hop-interface vti10 @@ -344,34 +348,35 @@ Imagine the following topology set interfaces dummy dum0 address '10.0.12.1/24' set interfaces vti vti10 address '10.0.0.3/31' - set vpn ipsec option disable-route-autoinstall - set vpn ipsec authentication psk OFFICE-A id '172.18.201.10' - set vpn ipsec authentication psk OFFICE-A id '172.18.202.10' - set vpn ipsec authentication psk OFFICE-A secret 'secretkey' + set vpn ipsec authentication psk peer_172-18-201-10 id '172.18.202.10' + set vpn ipsec authentication psk peer_172-18-201-10 id '172.18.201.10' + set vpn ipsec authentication psk peer_172-18-201-10 secret 'secretkey' set vpn ipsec esp-group ESP_DEFAULT lifetime '3600' set vpn ipsec esp-group ESP_DEFAULT mode 'tunnel' set vpn ipsec esp-group ESP_DEFAULT pfs 'dh-group19' set vpn ipsec esp-group ESP_DEFAULT proposal 10 encryption 'aes256gcm128' set vpn ipsec esp-group ESP_DEFAULT proposal 10 hash 'sha256' - set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection action 'restart' + set vpn ipsec ike-group IKEv2_DEFAULT close-action 'none' + set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection action 'hold' set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection interval '30' set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection timeout '120' + set vpn ipsec ike-group IKEv2_DEFAULT disable-mobike set vpn ipsec ike-group IKEv2_DEFAULT key-exchange 'ikev2' set vpn ipsec ike-group IKEv2_DEFAULT lifetime '10800' - set vpn ipsec ike-group IKEv2_DEFAULT disable-mobike set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 dh-group '19' set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 encryption 'aes256gcm128' set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 hash 'sha256' set vpn ipsec interface 'eth0.202' - set vpn ipsec site-to-site peer OFFICE-A authentication local-id '172.18.202.10' - set vpn ipsec site-to-site peer OFFICE-A authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer OFFICE-A authentication remote-id '172.18.201.10' - set vpn ipsec site-to-site peer OFFICE-A connection-type 'initiate' - set vpn ipsec site-to-site peer OFFICE-A ike-group 'IKEv2_DEFAULT' - set vpn ipsec site-to-site peer OFFICE-A local-address '172.18.202.10' - set vpn ipsec site-to-site peer OFFICE-A remote-address '172.18.201.10' - set vpn ipsec site-to-site peer OFFICE-A vti bind 'vti10' - set vpn ipsec site-to-site peer OFFICE-A vti esp-group 'ESP_DEFAULT' + set vpn ipsec site-to-site peer peer_172-18-201-10 authentication local-id '172.18.202.10' + set vpn ipsec site-to-site peer peer_172-18-201-10 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer peer_172-18-201-10 authentication remote-id '172.18.201.10' + set vpn ipsec site-to-site peer peer_172-18-201-10 connection-type 'initiate' + set vpn ipsec site-to-site peer peer_172-18-201-10 ike-group 'IKEv2_DEFAULT' + set vpn ipsec site-to-site peer peer_172-18-201-10 ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer peer_172-18-201-10 local-address '172.18.202.10' + set vpn ipsec site-to-site peer peer_172-18-201-10 remote-address '172.18.201.10' + set vpn ipsec site-to-site peer peer_172-18-201-10 vti bind 'vti10' + set vpn ipsec site-to-site peer peer_172-18-201-10 vti esp-group 'ESP_DEFAULT' set protocols static interface-route 10.0.11.0/24 next-hop-interface vti10 @@ -379,44 +384,44 @@ Key Parameters: * ``authentication local-id/remote-id`` - IKE identification is used for validation of VPN peer devices during IKE negotiation. If you do not configure - local/remote-identity, the device uses the IPv4 or IPv6 address that + local/remote-identity, the device uses the IPv4 or IPv6 address that corresponds to the local/remote peer by default. - In certain network setups (like ipsec interface with dynamic address, or - behind the NAT ), the IKE ID received from the peer does not match the IKE - gateway configured on the device. This can lead to a Phase 1 validation + In certain network setups (like ipsec interface with dynamic address, or + behind the NAT ), the IKE ID received from the peer does not match the IKE + gateway configured on the device. This can lead to a Phase 1 validation failure. - So, make sure to configure the local/remote id explicitly and ensure that the + So, make sure to configure the local/remote id explicitly and ensure that the IKE ID is the same as the remote-identity configured on the peer device. * ``disable-route-autoinstall`` - This option when configured disables the routes installed in the default table 220 for site-to-site ipsec. It is mostly used with VTI configuration. -* ``dead-peer-detection action = clear | hold | restart`` - R_U_THERE - notification messages(IKEv1) or empty INFORMATIONAL messages (IKEv2) - are periodically sent in order to check the liveliness of the IPsec peer. The - values clear, hold, and restart all activate DPD and determine the action to +* ``dead-peer-detection action = clear | hold | restart`` - R_U_THERE + notification messages(IKEv1) or empty INFORMATIONAL messages (IKEv2) + are periodically sent in order to check the liveliness of the IPsec peer. The + values clear, hold, and restart all activate DPD and determine the action to perform on a timeout. - With ``clear`` the connection is closed with no further actions taken. - ``hold`` installs a trap policy, which will catch matching traffic and tries - to re-negotiate the connection on demand. - ``restart`` will immediately trigger an attempt to re-negotiate the + With ``clear`` the connection is closed with no further actions taken. + ``hold`` installs a trap policy, which will catch matching traffic and tries + to re-negotiate the connection on demand. + ``restart`` will immediately trigger an attempt to re-negotiate the connection. -* ``close-action = none | clear | hold | restart`` - defines the action to take - if the remote peer unexpectedly closes a CHILD_SA (see above for meaning of +* ``close-action = none | clear | hold | restart`` - defines the action to take + if the remote peer unexpectedly closes a CHILD_SA (see above for meaning of values). A closeaction should not be used if the peer uses reauthentication or uniqueids. - - When the close-action option is set on the peers, the connection-type + + When the close-action option is set on the peers, the connection-type of each peer has to considered carefully. For example, if the option is set - on both peers, then both would attempt to initiate and hold open multiple - copies of each child SA. This might lead to instability of the device or - cpu/memory utilization. - - Below flow-chart could be a quick reference for the close-action - combination depending on how the peer is configured. + on both peers, then both would attempt to initiate and hold open multiple + copies of each child SA. This might lead to instability of the device or + cpu/memory utilization. + + Below flow-chart could be a quick reference for the close-action + combination depending on how the peer is configured. .. figure:: /_static/images/IPSec_close_action_settings.jpg - + Similar combinations are applicable for the dead-peer-detection. diff --git a/docs/configuration/vpn/sstp.rst b/docs/configuration/vpn/sstp.rst index f3e062fe..d9bb4353 100644 --- a/docs/configuration/vpn/sstp.rst +++ b/docs/configuration/vpn/sstp.rst @@ -116,9 +116,20 @@ Configuration Specifies the port `<port>` that the SSTP port will listen on (default 443). -.. cfgcmd:: set vpn sstp client-ip-pool subnet <subnet> +.. cfgcmd:: set vpn sstp client-ip-pool <POOL-NAME> range <x.x.x.x-x.x.x.x | x.x.x.x/x> - Use `<subnet>` as the IP pool for all connecting clients. + Use this command to define the first IP address of a pool of + addresses to be given to SSTP clients. If notation ``x.x.x.x-x.x.x.x``, + it must be within a /24 subnet. If notation ``x.x.x.x/x`` is + used there is possibility to set host/netmask. + +.. cfgcmd:: set vpn sstp client-ip-pool <POOL-NAME> next-pool <NEXT-POOL-NAME> + + Use this command to define the next address pool name. + +.. cfgcmd:: set vpn sstp default-pool <POOL-NAME> + + Use this command to define default address pool name. .. cfgcmd:: set vpn sstp client-ipv6-pool prefix <address> mask <number-of-bits> @@ -282,7 +293,8 @@ Example set vpn sstp authentication local-users username vyos password vyos set vpn sstp authentication mode local set vpn sstp gateway-address 192.0.2.254 - set vpn sstp client-ip-pool subnet 192.0.2.0/25 + set vpn sstp client-ip-pool SSTP-POOL range 192.0.2.0/25 + set vpn sstp default-pool 'SSTP-POOL' set vpn sstp name-server 10.0.0.1 set vpn sstp name-server 10.0.0.2 set vpn sstp ssl ca-cert-file /config/auth/ca.crt |