diff options
Diffstat (limited to 'docs/configuration')
97 files changed, 18921 insertions, 0 deletions
diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst new file mode 100644 index 00000000..04800b91 --- /dev/null +++ b/docs/configuration/firewall/index.rst @@ -0,0 +1,847 @@ +.. _firewall: + +######## +Firewall +######## + +******** +Overview +******** + +VyOS makes use of Linux `netfilter <https://netfilter.org/>`_ for packet +filtering. + +The firewall supports the creation of groups for ports, addresses, and +networks (implemented using netfilter ipset) and the option of interface +or zone based firewall policy. + +.. note:: **Important note on usage of terms:** + The firewall makes use of the terms `in`, `out`, and `local` + for firewall policy. Users experienced with netfilter often confuse + `in` to be a reference to the `INPUT` chain, and `out` the `OUTPUT` + chain from netfilter. This is not the case. These instead indicate + the use of the `FORWARD` chain and either the input or output + interface. The `INPUT` chain, which is used for local traffic to the + OS, is a reference to as `local` with respect to its input interface. + + +*************** +Global settings +*************** + +Some firewall settings are global and have a affect on the whole system. + +.. cfgcmd:: set firewall all-ping [enable | disable] + + By default, when VyOS receives an ICMP echo request packet destined for + itself, it will answer with an ICMP echo reply, unless you avoid it + through its firewall. + + With the firewall you can set rules to accept, drop or reject ICMP in, + out or local traffic. You can also use the general **firewall all-ping** + command. This command affects only to LOCAL (packets destined for your + VyOS system), not to IN or OUT traffic. + + .. note:: **firewall all-ping** affects only to LOCAL and it always + behaves in the most restrictive way + + .. code-block:: none + + set firewall all-ping enable + + When the command above is set, VyOS will answer every ICMP echo request + addressed to itself, but that will only happen if no other rule is + applied dropping or rejecting local echo requests. In case of conflict, + VyOS will not answer ICMP echo requests. + + .. code-block:: none + + set firewall all-ping disable + + When the command above is set, VyOS will answer no ICMP echo request + addressed to itself at all, no matter where it comes from or whether + more specific rules are being applied to accept them. + +.. cfgcmd:: set firewall broadcast-ping [enable | disable] + + This setting enable or disable the response of icmp broadcast + messages. The following system parameter will be altered: + + * ``net.ipv4.icmp_echo_ignore_broadcasts`` + +.. cfgcmd:: set firewall ip-src-route [enable | disable] +.. cfgcmd:: set firewall ipv6-src-route [enable | disable] + + This setting handle if VyOS accept packets with a source route + option. The following system parameter will be altered: + + * ``net.ipv4.conf.all.accept_source_route`` + * ``net.ipv6.conf.all.accept_source_route`` + +.. cfgcmd:: set firewall receive-redirects [enable | disable] +.. cfgcmd:: set firewall ipv6-receive-redirects [enable | disable] + + enable or disable of ICMPv4 or ICMPv6 redirect messages accepted + by VyOS. The following system parameter will be altered: + + * ``net.ipv4.conf.all.accept_redirects`` + * ``net.ipv6.conf.all.accept_redirects`` + +.. cfgcmd:: set firewall send-redirects [enable | disable] + + enable or disable of ICMPv4 redirect messages send by VyOS + The following system parameter will be altered: + + * ``net.ipv4.conf.all.send_redirects`` + +.. cfgcmd:: set firewall log-martians [enable | disable] + + enable or disable the logging of martian IPv4 packets. + The following system parameter will be altered: + + * ``net.ipv4.conf.all.log_martians`` + +.. cfgcmd:: set firewall source-validation [strict | loose | disable] + + Set the IPv4 source validation mode. + The following system parameter will be altered: + + * ``net.ipv4.conf.all.rp_filter`` + +.. cfgcmd:: set firewall syn-cookies [enable | disable] + + Enable or Disable if VyOS use IPv4 TCP SYN Cookies. + The following system parameter will be altered: + + * ``net.ipv4.tcp_syncookies`` + +.. cfgcmd:: set firewall twa-hazards-protection [enable | disable] + + Enable or Disable VyOS to be :rfc:`1337` conform. + The following system parameter will be altered: + + * ``net.ipv4.tcp_rfc1337`` + +.. cfgcmd:: set firewall state-policy established action [accept | drop | + reject] + +.. cfgcmd:: set firewall state-policy established log enable + + Set the global setting for a astablished connections. + +.. cfgcmd:: set firewall state-policy invalid action [accept | drop | reject] + +.. cfgcmd:: set firewall state-policy invalid log enable + + Set the global setting for invalid packets. + +.. cfgcmd:: set firewall state-policy related action [accept | drop | reject] + +.. cfgcmd:: set firewall state-policy related log enable + + Set the global setting for related connections. + + +****** +Groups +****** + +Firewall groups represent collections of IP addresses, networks, or +ports. Once created, a group can be referenced by firewall rules as +either a source or destination. Members can be added or removed from a +group without changes to, or the need to reload, individual firewall +rules. + +.. note:: Groups can also be referenced by NAT configuration. + +Groups need to have unique names. Even though some contain IPv4 +addresses and others contain IPv6 addresses, they still need to have +unique names, so you may want to append "-v4" or "-v6" to your group +names. + + +Address Groups +============== + +In a **address group** a single IP adresses or IP address ranges are +definded. + +.. cfgcmd:: set firewall group address-group <name> address [address | + address range] +.. cfgcmd:: set firewall group ipv6-address-group <name> address <address> + + Define a IPv4 or a IPv6 address group + + .. code-block:: none + + set firewall group address-group ADR-INSIDE-v4 address 192.168.0.1 + set firewall group address-group ADR-INSIDE-v4 address 10.0.0.1-10.0.0.8 + set firewall group ipv6-address-group ADR-INSIDE-v6 address 2001:db8::1 + +.. cfgcmd:: set firewall group address-group <name> description <text> +.. cfgcmd:: set firewall group ipv6-address-group <name> description <text> + + Provide a IPv4 or IPv6 address group description + + +Network Groups +============== + +While **network groups** accept IP networks in CIDR notation, specific +IP addresses can be added as a 32-bit prefix. If you foresee the need +to add a mix of addresses and networks, the network group is +recommended. + +.. cfgcmd:: set firewall group network-group <name> network <CIDR> +.. cfgcmd:: set firewall group ipv6-network-group <name> network <CIDR> + + Define a IPv4 or IPv6 Network group. + + .. code-block:: none + + set firewall group network-group NET-INSIDE-v4 network 192.168.0.0/24 + set firewall group network-group NET-INSIDE-v4 network 192.168.1.0/24 + set firewall group ipv6-network-group NET-INSIDE-v6 network 2001:db8::/64 + +.. cfgcmd:: set firewall group network-group <name> description <text> +.. cfgcmd:: set firewall group ipv6-network-group <name> description <text> + + Provide a IPv4 or IPv6 network group description. + + +Port Groups +=========== + +A **port group** represents only port numbers, not the protocol. Port +groups can be referenced for either TCP or UDP. It is recommended that +TCP and UDP groups are created separately to avoid accidentally +filtering unnecessary ports. Ranges of ports can be specified by using +`-`. + +.. cfgcmd:: set firewall group port-group <name> port + [portname | portnumber | startport-endport] + + Define a port group. A port name are any name defined in + /etc/services. e.g.: http + + .. code-block:: none + + set firewall group port-group PORT-TCP-SERVER1 port http + set firewall group port-group PORT-TCP-SERVER1 port 443 + set firewall group port-group PORT-TCP-SERVER1 port 5000-5010 + +.. cfgcmd:: set firewall group port-group <name> description <text> + + Provide a port group description. + + +********* +Rule-Sets +********* + +A rule-set is a named collection of firewall rules that can be applied +to an interface or zone. Each rule is numbered, has an action to apply +if the rule is matched, and the ability to specify the criteria to +match. Data packets go through the rules from 1 - 9999, at the first match +the action of the rule will executed. + +.. cfgcmd:: set firewall name <name> description <text> +.. cfgcmd:: set firewall ipv6-name <name> description <text> + + Provide a rule-set description. + +.. cfgcmd:: set firewall name <name> default-action [drop | reject | accept] +.. cfgcmd:: set firewall ipv6-name <name> default-action [drop | reject | + accept] + + This set the default action of the rule-set if no rule matched a paket + criteria. + +.. cfgcmd:: set firewall name <name> enable-default-log +.. cfgcmd:: set firewall ipv6-name <name> enable-default-log + + Use this command to enable the logging of the default action. + +.. cfgcmd:: set firewall name <name> rule <1-9999> action [drop | reject | + accept] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> action [drop | reject | + accept] + + This required setting define the action of the current rule. + +.. cfgcmd:: set firewall name <name> rule <1-9999> description <text> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> description <text> + + Provide a description for each rule. + +.. cfgcmd:: set firewall name <name> rule <1-9999> log [disable | enable] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> log [disable | enable] + + Enable or disable logging for the matched packet. + +.. cfgcmd:: set firewall name <name> rule <1-9999> disable +.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> disable + + If you want to disable a rule but let it in the configuration. + +Matching criteria +================= + +There are a lot of matching criteria gainst which the package can be tested. + + +.. cfgcmd:: set firewall name <name> rule <1-9999> source address + [address | addressrange | CIDR] +.. cfgcmd:: set firewall name <name> rule <1-9999> destination address + [address | addressrange | CIDR] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> source address + [address | addressrange | CIDR] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> destination address + [address | addressrange | CIDR] + + This is similiar to the network groups part, but here you are able to negate + the matching addresses. + + .. code-block:: none + + set firewall name WAN-IN-v4 rule 100 source address 192.0.2.10-192.0.2.11 + # with a '!' the rule match everything except the specified subnet + set fitewall name WAN-IN-v4 rule 101 source address !203.0.113.0/24 + set firewall ipv6-name WAN-IN-v6 rule 100 source address 2001:db8::202 + + +.. cfgcmd:: set firewall name <name> rule <1-9999> source mac-address + <mac-address> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> source mac-address + <mac-address> + + Only in the source criteria you can specify a mac-address + + .. code-block:: none + + set firewall name LAN-IN-v4 rule 100 source mac-address 00:53:00:11:22:33 + set firewall name LAN-IN-v4 rule 101 source mac-address !00:53:00:aa:12:34 + +.. cfgcmd:: set firewall name <name> rule <1-9999> source port + [1-65535 | portname | start-end] +.. cfgcmd:: set firewall name <name> rule <1-9999> destination port + [1-65535 | portname | start-end] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> source port + [1-65535 | portname | start-end] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> destination port + [1-65535 | portname | start-end] + + A port can be set with a portnumber or a name which is here + defined: ``/etc/services``. + + .. code-block:: none + + set firewall name WAN-IN-v4 rule 10 source port '22' + set firewall name WAN-IN-v4 rule 11 source port '!http' + set firewall name WAN-IN-v4 rule 12 source port 'https' + + Multiple source ports can be specified as a comma-separated list. + The whole list can also be "negated" using '!'. For example: + + .. code-block:: none + + set firewall ipv6-name WAN-IN-v6 rule 10 source port '!22,https,3333-3338' + +.. cfgcmd:: set firewall name <name> rule <1-9999> source group + address-group <name> +.. cfgcmd:: set firewall name <name> rule <1-9999> destination group + address-group <name> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> source group + address-group <name> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> destination group + address-group <name> + + Use a specific address-group + +.. cfgcmd:: set firewall name <name> rule <1-9999> source group + network-group <name> +.. cfgcmd:: set firewall name <name> rule <1-9999> destination group + network-group <name> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> source group + network-group <name> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> destination group + network-group <name> + + Use a specific network-group + +.. cfgcmd:: set firewall name <name> rule <1-9999> source group + port-group <name> +.. cfgcmd:: set firewall name <name> rule <1-9999> destination group + port-group <name> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> source group + port-group <name> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> destination group + port-group <name> + + Use a specific port-group + +.. cfgcmd:: set firewall name <name> rule <1-9999> protocol [<text> | + <0-255> | all | tcp_udp] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> protocol [<text> | + <0-255> | all | tcp_udp] + + Match a protocol criteria. A protocol number or a name which is here + defined: ``/etc/protocols``. + Special names are ``all`` for all protocols and ``tcp_udp`` for tcp and upd + based pakets. The ``!`` negate the selected protocol. + + .. code-block:: none + + set firewall name WAN-IN-v4 rule 10 protocol tcp_udp + set firewall name WAN-IN-v4 rule 11 protocol !tcp_udp + set firewall ipv6-name WAN-IN-v6 rule 10 protocol tcp + +.. cfgcmd:: set firewall name <name> rule <1-9999> tcp flags <text> +.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> tcp flags <text> + + Allowed values fpr TCP flags: ``SYN``, ``ACK``, ``FIN``, ``RST``, ``URG``, + ``PSH``, ``ALL`` When specifying more than one flag, flags should be comma + separated. The ``!`` negate the selected protocol. + + .. code-block:: none + + set firewall name WAN-IN-v4 rule 10 tcp flags 'ACK' + set firewall name WAN-IN-v4 rule 12 tcp flags 'SYN' + set firewall name WAN-IN-v4 rule 13 tcp flags 'SYN,!ACK,!FIN,!RST' + +.. cfgcmd:: set firewall name <name> rule <1-9999> state [established | + invalid | new | related] [enable | disable ] +.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> state [established | + invalid | new | related] [enable | disable ] + + Match against the state of a packet. + + +*********************************** +Applying a Rule-Set to an Interface +*********************************** + +A Rule-Set can be appliend to every inteface: + +* ``in``: Ruleset for forwarded packets on inbound interface +* ``out``: Ruleset for forwarded packets on outbound interface +* ``local``: Ruleset for packets destined for this router + +.. cfgcmd:: set interface ethernet <ethN> firewall [in | out | local] + [name | ipv6-name] <rule-set> + + Here are some examples for applying a rule-set to an interface + + .. code-block:: none + + set interface ethernet eth1 vif 100 firewall in name LANv4-IN + set interface ethernet eth1 vif 100 firewall out name LANv4-OUT + set interface bonding bond0 firewall in name LANv4-IN + set interfaces openvpn vtun1 firewall in name Lanv4-IN + + .. note:: + As you can see in the example here, you can assign the same rule-set to + several interfaces. An interface can only have one rule-set per chain. + + +************************** +Zone-based Firewall Policy +************************** + +As an alternative to applying policy to an interface directly, a +zone-based firewall can be created to simplify configuration when +multiple interfaces belong to the same security zone. Instead of +applying rulesets to interfaces, they are applied to source +zone-destination zone pairs. + +An basic introduction to zone-based firewalls can be found `here +<https://support.vyos.io/en/kb/articles/a-primer-to-zone-based-firewall>`_, +and an example at :ref:`examples-zone-policy`. + +Define a Zone +============= + +To define a zone setup either one with interfaces or a local zone. + +.. cfgcmd:: set zone-policy zone <name> interface <interfacenames> + + Set a interfaces to a zone. A zone can have multiple interfaces. + But a interface can only be member in one zone. + +.. cfgcmd:: set zone-policy zone <name> local-zone + + Define the Zone as a local zone. A local zone have no interfaces and + will be applied to the router itself. + +.. cfgcmd:: set zone-policy zone <name> default-action [drop | reject] + + Change the default-action with this setting. + +.. cfgcmd:: set zone-policy zone <name> description + + Set a meaningful description. + + +Applying a Rule-Set to a Zone +============================= + +Before you are able to apply a rule-set to a zone you have to create the zones +first. + +.. cfgcmd:: set zone-policy zone <name> from <name> firewall name + <rule-set> +.. cfgcmd:: set zone-policy zone <name> from <name> firewall ipv6-name + <rule-set> + + You apply a rule-set always to a zone from a other zone, it is recommended + to create one rule-set for each zone pair. + + .. code-block:: none + + set zone-policy zone DMZ from LAN firewall name LANv4-to-DMZv4 + set zone-policy zone LAN from DMZ firewall name DMZv4-to-LANv4 + + +*********************** +Operation-mode Firewall +*********************** + +Rule-set overview +================= + +.. opcmd:: show firewall + + This will show you a basic firewall overview + + .. code-block:: none + + vyos@vyos:~$ show firewall + + ------------------------ + Firewall Global Settings + ------------------------ + + Firewall state-policy for all IPv4 and Ipv6 traffic + + state action log + ----- ------ --- + invalid accept disabled + established accept disabled + related accept disabled + + ----------------------------- + Rulesets Information + ----------------------------- + -------------------------------------------------------------------------- + IPv4 Firewall "DMZv4-1-IN": + + Active on (eth0,IN) + + rule action proto packets bytes + ---- ------ ----- ------- ----- + 10 accept icmp 0 0 + condition - saddr 10.1.0.0/24 daddr 0.0.0.0/0 LOG enabled + + 10000 drop all 0 0 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 LOG enabled + + -------------------------------------------------------------------------- + IPv4 Firewall "DMZv4-1-OUT": + + Active on (eth0,OUT) + + rule action proto packets bytes + ---- ------ ----- ------- ----- + 10 accept tcp_udp 1 60 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 match-DST-PORT-GROUP DMZ-Ports /* + DMZv4-1-OUT-10 */LOG enabled + + 11 accept icmp 1 84 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 /* DMZv4-1-OUT-11 */LOG enabled + + 10000 drop all 6 360 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 LOG enabled + + -------------------------------------------------------------------------- + IPv4 Firewall "LANv4-IN": + + Inactive - Not applied to any interfaces or zones. + + rule action proto packets bytes + ---- ------ ----- ------- ----- + 10 accept all 0 0 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 /* LANv4-IN-10 */ + + 10000 drop all 0 0 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 + +.. opcmd:: show firewall summary + + This will show you a summary about rule-sets and groups + + .. code-block:: none + + vyos@vyos:~$ show firewall summary + + ------------------------ + Firewall Global Settings + ------------------------ + + Firewall state-policy for all IPv4 and Ipv6 traffic + + state action log + ----- ------ --- + invalid accept disabled + related accept disabled + established accept disabled + + ------------------------ + Firewall Rulesets + ------------------------ + + IPv4 name: + + Rule-set name Description References + ------------- ----------- ---------- + DMZv4-1-OUT (eth0,OUT) + DMZv4-1-IN (eth0,IN) + + ------------------------ + Firewall Groups + ------------------------ + + Port Groups: + + Group name Description References + ---------- ----------- ---------- + DMZ-Ports DMZv4-1-OUT-10-destination + + Network Groups: + + Group name Description References + ---------- ----------- ---------- + LANv4 LANv4-IN-10-source, + DMZv4-1-OUT-10-source, + DMZv4-1-OUT-11-source + +.. opcmd:: show firewall statistics + + This will show you a statistic of all rule-sets since the last boot. + +.. opcmd:: show firewall [name | ipv6name] <name> rule <1-9999> + + This command will give an overview about a rule in a single rule-set + +.. opcmd:: show firewall group <name> + + Overview of defined groups. You see the type, the members, and where the + group is used. + + .. code-block:: none + + vyos@vyos:~$ show firewall group DMZ-Ports + Name : DMZ-Ports + Type : port + References : none + Members : + 80 + 443 + 8080 + 8443 + + vyos@vyos:~$ show firewall group LANv4 + Name : LANv4 + Type : network + References : LANv4-IN-10-source + Members : + 10.10.0.0/16 + +.. opcmd:: show firewall [name | ipv6name] <name> + + This command will give an overview about a single rule-set + +.. opcmd:: show firewall [name | ipv6name] <name> statistics + + This will show you a rule-set statistic since the last boot. + +.. opcmd:: show firewall [name | ipv6name] <name> rule <1-9999> + + This command will give an overview about a rule in a single rule-set + + +Zone-Policy Overview +==================== + +.. opcmd:: show zone-policy zone <name> + + Use this command to get an overview about a zone + + .. code-block:: none + + vyos@vyos:~$ show zone-policy zone DMZ + ------------------- + Name: DMZ + + Interfaces: eth0 eth1 + + From Zone: + name firewall + ---- -------- + LAN DMZv4-1-OUT + + +Show Firewall log +================= + +.. opcmd:: show log firewall [name | ipv6name] <name> + + Show the logs of a specific Rule-Set + +.. note:: + At the moment it not possible to look at the whole firewall log with VyOS + operational commands. All logs will save to ``/var/logs/messages``. + For example: ``grep '10.10.0.10' /var/log/messages`` + + + +Example Partial Config +====================== + +.. code-block:: none + + firewall { + all-ping enable + broadcast-ping disable + config-trap disable + 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 + } + } + name FROM-INTERNET { + default-action accept + description "From the Internet" + rule 10 { + action accept + description "Authorized Networks" + protocol all + source { + group { + network-group GOOD-NETWORKS + } + } + } + rule 11 { + action drop + description "Bad Networks" + protocol all + source { + group { + network-group BAD-NETWORKS + } + } + } + rule 30 { + action drop + description "BAD PORTS" + destination { + group { + port-group BAD-PORTS + } + } + log enable + protocol all + } + } + } + interfaces { + ethernet eth1 { + address dhcp + description OUTSIDE + duplex auto + firewall { + in { + name FROM-INTERNET + } + } + } + } + + +.. _routing-mss-clamp: + + +**************** +TCP-MSS Clamping +**************** + +As Internet wide PMTU discovery rarely works, we sometimes need to clamp +our TCP MSS value to a specific value. This is a field in the TCP +Options part of a SYN packet. By setting the MSS value, you are telling +the remote side unequivocally 'do not try to send me packets bigger than +this value'. + +Starting with VyOS 1.2 there is a firewall option to clamp your TCP MSS +value for IPv4 and IPv6. + + +.. note:: MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting + in 1452 bytes on a 1492 byte MTU. + + + +IPv4 +==== + + +.. cfgcmd:: set firewall options interface <interface> adjust-mss + <number-of-bytes> + + Use this command to set the maximum segment size for IPv4 transit + packets on a specific interface (500-1460 bytes). + +Example +------- + +Clamp outgoing MSS value in a TCP SYN packet to `1452` for `pppoe0` and +`1372` +for your WireGuard `wg02` tunnel. + +.. code-block:: none + + set firewall options interface pppoe0 adjust-mss '1452' + set firewall options interface wg02 adjust-mss '1372' + + + +IPv6 +==== + +.. cfgcmd:: set firewall options interface <interface> adjust-mss6 + <number-of-bytes> + + Use this command to set the maximum segment size for IPv6 transit + packets on a specific interface (1280-1492 bytes). + +Example +------- + +Clamp outgoing MSS value in a TCP SYN packet to `1280` for both `pppoe0` and +`wg02` interface. + +.. code-block:: none + + set firewall options interface pppoe0 adjust-mss6 '1280' + set firewall options interface wg02 adjust-mss6 '1280' + + + +.. hint:: When doing your byte calculations, you might find useful this + `Visual packet size calculator <https://baturin.org/tools/encapcalc/>`_. diff --git a/docs/configuration/highavailability/index.rst b/docs/configuration/highavailability/index.rst new file mode 100644 index 00000000..a223c283 --- /dev/null +++ b/docs/configuration/highavailability/index.rst @@ -0,0 +1,191 @@ +.. _high-availability: + +High availability +================= + +VRRP (Virtual Router Redundancy Protocol) provides active/backup redundancy for +routers. Every VRRP router has a physical IP/IPv6 address, and a virtual +address. On startup, routers elect the master, and the router with the highest +priority becomes the master and assigns the virtual address to its interface. +All routers with lower priorities become backup routers. The master then starts +sending keepalive packets to notify other routers that it's available. If the +master fails and stops sending keepalive packets, the router with the next +highest priority becomes the new master and takes over the virtual address. + +VRRP keepalive packets use multicast, and VRRP setups are limited to a single +datalink layer segment. You can setup multiple VRRP groups +(also called virtual routers). Virtual routers are identified by a +VRID (Virtual Router IDentifier). If you setup multiple groups on the same +interface, their VRIDs must be unique, but it's possible (even if not +recommended for readability reasons) to use duplicate VRIDs on different +interfaces. + +Basic setup +----------- + +VRRP groups are created with the +``set high-availability vrrp group $GROUP_NAME`` commands. The required +parameters are interface, vrid, and virtual-address. + +minimal config + +.. code-block:: none + + set high-availability vrrp group Foo vrid 10 + set high-availability vrrp group Foo interface eth0 + set high-availability vrrp group Foo virtual-address 192.0.2.1/24 + +You can verify your VRRP group status with the operational mode +``run show vrrp`` command: + +.. code-block:: none + + vyos@vyos# run show vrrp + Name Interface VRID State Last Transition + ---------- ----------- ------ ------- ----------------- + Foo eth1 10 MASTER 2s + +IPv6 support +------------ + +The ``virtual-address`` parameter can be either an IPv4 or IPv6 address, but you +cannot mix IPv4 and IPv6 in the same group, and will need to create groups with +different VRIDs specially for IPv4 and IPv6. + +Disabling a VRRP group +---------------------- + +You can disable a VRRP group with ``disable`` option: + +.. code-block:: none + + set high-availability vrrp group Foo disable + +A disabled group will be removed from the VRRP process and your router will not +participate in VRRP for that VRID. It will disappear from operational mode +commands output, rather than enter the backup state. + +Setting VRRP group priority +--------------------------- + +VRRP priority can be set with ``priority`` option: + +.. code-block:: none + + set high-availability vrrp group Foo priority 200 + +The priority must be an integer number from 1 to 255. Higher priority value +increases router's precedence in the master elections. + +Sync groups +----------- + +A sync group allows VRRP groups to transition together. + +.. code-block:: none + + edit high-availability vrrp + set sync-group MAIN member VLAN9 + set sync-group MAIN member VLAN20 + +In the following example, when VLAN9 transitions, VLAN20 will also transition: + +.. code-block:: none + + vrrp { + group VLAN9 { + interface eth0.9 + virtual-address 10.9.1.1/24 + priority 200 + vrid 9 + } + group VLAN20 { + interface eth0.20 + priority 200 + virtual-address 10.20.20.1/24 + vrid 20 + } + sync-group MAIN { + member VLAN20 + member VLAN9 + } + } + + +.. warning:: All items in a sync group should be similarly configured. + If one VRRP group is set to a different premption delay or priority, + it would result in an endless transition loop. + + +Preemption +---------- + +VRRP can use two modes: preemptive and non-preemptive. In the preemptive mode, +if a router with a higher priority fails and then comes back, routers with lower +priority will give up their master status. In non-preemptive mode, the newly +elected master will keep the master status and the virtual address indefinitely. + +By default VRRP uses preemption. You can disable it with the "no-preempt" +option: + +.. code-block:: none + + set high-availability vrrp group Foo no-preempt + +You can also configure the time interval for preemption with the "preempt-delay" +option. For example, to set the higher priority router to take over in 180 +seconds, use: + +.. code-block:: none + + set high-availability vrrp group Foo preempt-delay 180 + +Unicast VRRP +------------ + +By default VRRP uses multicast packets. If your network does not support +multicast for whatever reason, you can make VRRP use unicast communication +instead. + +.. code-block:: none + + set high-availability vrrp group Foo peer-address 192.0.2.10 + set high-availability vrrp group Foo hello-source-address 192.0.2.15 + +Scripting +--------- + +VRRP functionality can be extended with scripts. VyOS supports two kinds of +scripts: health check scripts and transition scripts. Health check scripts +execute custom checks in addition to the master router reachability. Transition +scripts are executed when VRRP state changes from master to backup or fault and +vice versa and can be used to enable or disable certain services, for example. + +Health check scripts +^^^^^^^^^^^^^^^^^^^^ + +This setup will make the VRRP process execute the +``/config/scripts/vrrp-check.sh script`` every 60 seconds, and transition the +group to the fault state if it fails (i.e. exits with non-zero status) three +times: + +.. code-block:: none + + set high-availability vrrp group Foo health-check script /config/scripts/vrrp-check.sh + set high-availability vrrp group Foo health-check interval 60 + set high-availability vrrp group Foo health-check failure-count 3 + +Transition scripts +^^^^^^^^^^^^^^^^^^ + +Transition scripts can help you implement various fixups, such as starting and +stopping services, or even modifying the VyOS config on VRRP transition. +This setup will make the VRRP process execute the +``/config/scripts/vrrp-fail.sh`` with argument ``Foo`` when VRRP fails, +and the ``/config/scripts/vrrp-master.sh`` when the router becomes the master: + +.. code-block:: none + + set high-availability vrrp group Foo transition-script backup "/config/scripts/vrrp-fail.sh Foo" + set high-availability vrrp group Foo transition-script fault "/config/scripts/vrrp-fail.sh Foo" + set high-availability vrrp group Foo transition-script master "/config/scripts/vrrp-master.sh Foo" diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst new file mode 100644 index 00000000..bce013cb --- /dev/null +++ b/docs/configuration/index.rst @@ -0,0 +1,23 @@ +################### +Configuration Guide +################### + +The following structure respresent the cli structure. + +.. toctree:: + :maxdepth: 1 + :includehidden: + + firewall/index + highavailability/index + interfaces/index + loadbalancing/index + nat/index + policy/index + protocols/index + service/index + system/index + trafficpolicy/index + vpn/index + vrf/index + zonepolicy/index
\ No newline at end of file diff --git a/docs/configuration/interfaces/bonding.rst b/docs/configuration/interfaces/bonding.rst new file mode 100644 index 00000000..bf7cfc2c --- /dev/null +++ b/docs/configuration/interfaces/bonding.rst @@ -0,0 +1,575 @@ +.. _bond-interface: + +####################### +Bond / Link Aggregation +####################### + +The bonding interface provides a method for aggregating multiple network +interfaces into a single logical "bonded" interface, or LAG, or ether-channel, +or port-channel. The behavior of the bonded interfaces depends upon the mode; +generally speaking, modes provide either hot standby or load balancing services. +Additionally, link integrity monitoring may be performed. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: bond + :var1: bond0 + +Member Interfaces +================= + +.. cfgcmd:: set interfaces bonding <interface> member interface <member> + + Enslave `<member>` interface to bond `<interface>`. + +Bond options +============ + +.. cfgcmd:: set interfaces bonding <interface> mode <802.3ad | active-backup | + broadcast | round-robin | transmit-load-balance | adaptive-load-balance | + xor-hash> + + Specifies one of the bonding policies. The default is 802.3ad. Possible + values are: + + * ``802.3ad`` - IEEE 802.3ad Dynamic link aggregation. Creates aggregation + groups that share the same speed and duplex settings. Utilizes all slaves + in the active aggregator according to the 802.3ad specification. + + Slave selection for outgoing traffic is done according to the transmit + hash policy, which may be changed from the default simple XOR policy via + the :cfgcmd:`hash-policy` option, documented below. + + .. note:: Not all transmit policies may be 802.3ad compliant, particularly + in regards to the packet mis-ordering requirements of section 43.2.4 + of the 802.3ad standard. + + * ``active-backup`` - Active-backup policy: Only one slave in the bond is + active. A different slave becomes active if, and only if, the active slave + fails. The bond's MAC address is externally visible on only one port + (network adapter) to avoid confusing the switch. + + When a failover occurs in active-backup mode, bonding will issue one or + more gratuitous ARPs on the newly active slave. One gratuitous ARP is + issued for the bonding master interface and each VLAN interfaces + configured above it, provided that the interface has at least one IP + address configured. Gratuitous ARPs issued for VLAN interfaces are tagged + with the appropriate VLAN id. + + This mode provides fault tolerance. The :cfgcmd:`primary` option, + documented below, affects the behavior of this mode. + + * ``broadcast`` - Broadcast policy: transmits everything on all slave + interfaces. + + This mode provides fault tolerance. + + * ``round-robin`` - Round-robin policy: Transmit packets in sequential + order from the first available slave through the last. + + This mode provides load balancing and fault tolerance. + + * ``transmit-load-balance`` - Adaptive transmit load balancing: channel + bonding that does not require any special switch support. + + Incoming traffic is received by the current slave. If the receiving slave + fails, another slave takes over the MAC address of the failed receiving + slave. + + * ``adaptive-load-balance`` - Adaptive load balancing: includes + transmit-load-balance plus receive load balancing for IPV4 traffic, and + does not require any special switch support. The receive load balancing + is achieved by ARP negotiation. The bonding driver intercepts the ARP + Replies sent by the local system on their way out and overwrites the + source hardware address with the unique hardware address of one of the + slaves in the bond such that different peers use different hardware + addresses for the server. + + Receive traffic from connections created by the server is also balanced. + When the local system sends an ARP Request the bonding driver copies and + saves the peer's IP information from the ARP packet. When the ARP Reply + arrives from the peer, its hardware address is retrieved and the bonding + driver initiates an ARP reply to this peer assigning it to one of the + slaves in the bond. A problematic outcome of using ARP negotiation for + balancing is that each time that an ARP request is broadcast it uses the + hardware address of the bond. Hence, peers learn the hardware address + of the bond and the balancing of receive traffic collapses to the current + slave. This is handled by sending updates (ARP Replies) to all the peers + with their individually assigned hardware address such that the traffic + is redistributed. Receive traffic is also redistributed when a new slave + is added to the bond and when an inactive slave is re-activated. The + receive load is distributed sequentially (round robin) among the group + of highest speed slaves in the bond. + + When a link is reconnected or a new slave joins the bond the receive + traffic is redistributed among all active slaves in the bond by initiating + ARP Replies with the selected MAC address to each of the clients. The + updelay parameter (detailed below) must be set to a value equal or greater + than the switch's forwarding delay so that the ARP Replies sent to the + peers will not be blocked by the switch. + + * ``xor-hash`` - XOR policy: Transmit based on the selected transmit + hash policy. The default policy is a simple [(source MAC address XOR'd + with destination MAC address XOR packet type ID) modulo slave count]. + Alternate transmit policies may be selected via the :cfgcmd:`hash-policy` + option, described below. + + This mode provides load balancing and fault tolerance. + +.. cfgcmd:: set interfaces bonding <interface> min-links <0-16> + + Specifies the minimum number of links that must be active before asserting + carrier. It is similar to the Cisco EtherChannel min-links feature. This + allows setting the minimum number of member ports that must be up (link-up + state) before marking the bond device as up (carrier on). This is useful for + situations where higher level services such as clustering want to ensure a + minimum number of low bandwidth links are active before switchover. + + This option only affects 802.3ad mode. + + The default value is 0. This will cause carrier to be asserted (for 802.3ad + mode) whenever there is an active aggregator, regardless of the number of + available links in that aggregator. + + .. note:: Because an aggregator cannot be active without at least one + available link, setting this option to 0 or to 1 has the exact same + effect. + +.. cfgcmd:: set interfaces bonding <interface> hash-policy <policy> + + * **layer2** - Uses XOR of hardware MAC addresses and packet type ID field + to generate the hash. The formula is + + .. code-block:: none + + hash = source MAC XOR destination MAC XOR packet type ID + slave number = hash modulo slave count + + This algorithm will place all traffic to a particular network peer on + the same slave. + + This algorithm is 802.3ad compliant. + + * **layer2+3** - This policy uses a combination of layer2 and layer3 + protocol information to generate the hash. Uses XOR of hardware MAC + addresses and IP addresses to generate the hash. The formula is: + + .. code-block:: none + + hash = source MAC XOR destination MAC XOR packet type ID + hash = hash XOR source IP XOR destination IP + hash = hash XOR (hash RSHIFT 16) + hash = hash XOR (hash RSHIFT 8) + + And then hash is reduced modulo slave count. + + If the protocol is IPv6 then the source and destination addresses are + first hashed using ipv6_addr_hash. + + This algorithm will place all traffic to a particular network peer on the + same slave. For non-IP traffic, the formula is the same as for the layer2 + transmit hash policy. + + This policy is intended to provide a more balanced distribution of traffic + than layer2 alone, especially in environments where a layer3 gateway + device is required to reach most destinations. + + This algorithm is 802.3ad compliant. + + * **layer3+4** - This policy uses upper layer protocol information, when + available, to generate the hash. This allows for traffic to a particular + network peer to span multiple slaves, although a single connection will + not span multiple slaves. + + The formula for unfragmented TCP and UDP packets is + + .. code-block:: none + + hash = source port, destination port (as in the header) + hash = hash XOR source IP XOR destination IP + hash = hash XOR (hash RSHIFT 16) + hash = hash XOR (hash RSHIFT 8) + + And then hash is reduced modulo slave count. + + If the protocol is IPv6 then the source and destination addresses are + first hashed using ipv6_addr_hash. + + For fragmented TCP or UDP packets and all other IPv4 and IPv6 protocol + traffic, the source and destination port information is omitted. For + non-IP traffic, the formula is the same as for the layer2 transmit hash + policy. + + This algorithm is not fully 802.3ad compliant. A single TCP or UDP + conversation containing both fragmented and unfragmented packets will see + packets striped across two interfaces. This may result in out of order + delivery. Most traffic types will not meet this criteria, as TCP rarely + fragments traffic, and most UDP traffic is not involved in extended + conversations. Other implementations of 802.3ad may or may not tolerate + this noncompliance. + +.. cfgcmd:: set interfaces bonding <interface> primary <interface> + + An `<interface>` specifying which slave is the primary device. The specified + device will always be the active slave while it is available. Only when the + primary is off-line will alternate devices be used. This is useful when one + slave is preferred over another, e.g., when one slave has higher throughput + than another. + + The primary option is only valid for active-backup, transmit-load-balance, + and adaptive-load-balance mode. + +.. cfgcmd:: set interfaces bonding <interface> arp-monitor interval <time> + + Specifies the ARP link monitoring `<time>` in seconds. + + The ARP monitor works by periodically checking the slave devices to determine + whether they have sent or received traffic recently (the precise criteria + depends upon the bonding mode, and the state of the slave). Regular traffic + is generated via ARP probes issued for the addresses specified by the + :cfgcmd:`arp-monitor target` option. + + If ARP monitoring is used in an etherchannel compatible mode (modes + round-robin and xor-hash), the switch should be configured in a mode that + evenly distributes packets across all links. If the switch is configured to + distribute the packets in an XOR fashion, all replies from the ARP targets + will be received on the same link which could cause the other team members + to fail. + + A value of 0 disables ARP monitoring. The default value is 0. + +.. cfgcmd:: set interfaces bonding <interface> arp-monitor target <address> + + Specifies the IP addresses to use as ARP monitoring peers when + :cfgcmd:`arp-monitor interval` option is > 0. These are the targets of the + ARP request sent to determine the health of the link to the targets. + + Multiple target IP addresses can be specified. At least one IP address must + be given for ARP monitoring to function. + + The maximum number of targets that can be specified is 16. The default value + is no IP addresses. + +Offloading +---------- + +.. cmdinclude:: /_include/interface-xdp.txt + :var0: bonding + :var1: bond0 + +VLAN +==== + +.. cmdinclude:: /_include/interface-vlan-8021q.txt + :var0: bond + :var1: bond0 + +Port Mirror (SPAN) +================== + +.. cmdinclude:: ../../_include/interface-mirror.txt + :var0: bonding + :var1: bond1 + :var2: eth3 + +******* +Example +******* + +The following configuration on VyOS applies to all following 3rd party vendors. +It creates a bond with two links and VLAN 10, 100 on the bonded interfaces with +a per VIF IPv4 address. + +.. code-block:: none + + # Create bonding interface bond0 with 802.3ad LACP + set interfaces bonding bond0 hash-policy 'layer2' + set interfaces bonding bond0 mode '802.3ad' + + # Add the required vlans and IPv4 addresses on them + set interfaces bonding bond0 vif 10 address 192.168.0.1/24 + set interfaces bonding bond0 vif 100 address 10.10.10.1/24 + + # Add the member interfaces to the bonding interface + set interfaces bonding bond0 member interface eth1 + set interfaces bonding bond0 member interface eth2 + +Cisco Catalyst +============== + +Assign member interfaces to PortChannel + +.. code-block:: none + + interface GigabitEthernet1/0/23 + description VyOS eth1 + channel-group 1 mode active + ! + interface GigabitEthernet1/0/24 + description VyOS eth2 + channel-group 1 mode active + ! + +A new interface becomes present ``Port-channel1``, all configuration like +allowed VLAN interfaces, STP will happen here. + +.. code-block:: none + + interface Port-channel1 + description LACP Channel for VyOS + switchport trunk encapsulation dot1q + switchport trunk allowed vlan 10,100 + switchport mode trunk + spanning-tree portfast trunk + ! + + +Juniper EX Switch +================= + +For a headstart you can use the below example on how to build a bond with two +interfaces from VyOS to a Juniper EX Switch system. + +.. code-block:: none + + # Create aggregated ethernet device with 802.3ad LACP and port speeds of 10gbit/s + set interfaces ae0 aggregated-ether-options link-speed 10g + set interfaces ae0 aggregated-ether-options lacp active + + # Create layer 2 on the aggregated ethernet device with trunking for our vlans + set interfaces ae0 unit 0 family ethernet-switching port-mode trunk + + # Add the required vlans to the device + set interfaces ae0 unit 0 family ethernet-switching vlan members 10 + set interfaces ae0 unit 0 family ethernet-switching vlan members 100 + + # Add the two interfaces to the aggregated ethernet device, in this setup both + # ports are on the same switch (switch 0, module 1, port 0 and 1) + set interfaces xe-0/1/0 ether-options 802.3ad ae0 + set interfaces xe-0/1/1 ether-options 802.3ad ae0 + + # But this can also be done with multiple switches in a stack, a virtual + # chassis on Juniper (switch 0 and switch 1, module 1, port 0 on both switches) + set interfaces xe-0/1/0 ether-options 802.3ad ae0 + set interfaces xe-1/1/0 ether-options 802.3ad ae0 + +Aruba/HP +======== + +For a headstart you can use the below example on how to build a +bond,port-channel with two interfaces from VyOS to a Aruba/HP 2510G switch. + +.. code-block:: none + + # Create trunk with 2 member interfaces (interface 1 and 2) and LACP + trunk 1-2 Trk1 LACP + + # Add the required vlans to the trunk + vlan 10 tagged Trk1 + vlan 100 tagged Trk1 + +Arista EOS +========== + +When utilizing VyOS in an environment with Arista gear you can use this blue +print as an initial setup to get an LACP bond / port-channel operational between +those two devices. + +Lets assume the following topology: + +.. figure:: /_static/images/vyos_arista_bond_lacp.png + :alt: VyOS Arista EOS setup + +**R1** + + .. code-block:: none + + interfaces { + bonding bond10 { + hash-policy layer3+4 + member { + interface eth1 + interface eth2 + } + mode 802.3ad + vif 100 { + address 192.0.2.1/30 + address 2001:db8::1/64 + } + } + +**R2** + + .. code-block:: none + + interfaces { + bonding bond10 { + hash-policy layer3+4 + member { + interface eth1 + interface eth2 + } + mode 802.3ad + vif 100 { + address 192.0.2.2/30 + address 2001:db8::2/64 + } + } + +**SW1** + + .. code-block:: none + + ! + vlan 100 + name FOO + ! + interface Port-Channel10 + switchport trunk allowed vlan 100 + switchport mode trunk + spanning-tree portfast + ! + interface Port-Channel20 + switchport mode trunk + no spanning-tree portfast auto + spanning-tree portfast network + ! + interface Ethernet1 + channel-group 10 mode active + ! + interface Ethernet2 + channel-group 10 mode active + ! + interface Ethernet3 + channel-group 20 mode active + ! + interface Ethernet4 + channel-group 20 mode active + ! + +**SW2** + + .. code-block:: none + + ! + vlan 100 + name FOO + ! + interface Port-Channel10 + switchport trunk allowed vlan 100 + switchport mode trunk + spanning-tree portfast + ! + interface Port-Channel20 + switchport mode trunk + no spanning-tree portfast auto + spanning-tree portfast network + ! + interface Ethernet1 + channel-group 10 mode active + ! + interface Ethernet2 + channel-group 10 mode active + ! + interface Ethernet3 + channel-group 20 mode active + ! + interface Ethernet4 + channel-group 20 mode active + ! + +.. note:: When using EVE-NG to lab this environment ensure you are using e1000 + as the desired driver for your VyOS network interfaces. When using the regular + virtio network driver no LACP PDUs will be sent by VyOS thus the port-channel + will never become active! + +********* +Operation +********* + +.. opcmd:: show interfaces bonding + + Show brief interface information. + + .. code-block:: none + + vyos@vyos:~$ show interfaces bonding + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + bond0 - u/u my-sw1 int 23 and 24 + bond0.10 192.168.0.1/24 u/u office-net + bond0.100 10.10.10.1/24 u/u management-net + + +.. opcmd:: show interfaces bonding <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces bonding bond5 + bond5: <NO-CARRIER,BROADCAST,MULTICAST,MASTER,UP> mtu 1500 qdisc noqueue state DOWN group default qlen 1000 + link/ether 00:50:56:bf:ef:aa brd ff:ff:ff:ff:ff:ff + inet6 fe80::e862:26ff:fe72:2dac/64 scope link tentative + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 0 0 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 0 0 0 0 0 0 + +.. opcmd:: show interfaces bonding <interface> detail + + Show detailed information about the underlaying physical links on given + bond `<interface>`. + + .. code-block:: none + + vyos@vyos:~$ show interfaces bonding bond5 detail + Ethernet Channel Bonding Driver: v3.7.1 (April 27, 2011) + + Bonding Mode: IEEE 802.3ad Dynamic link aggregation + Transmit Hash Policy: layer2 (0) + MII Status: down + MII Polling Interval (ms): 100 + Up Delay (ms): 0 + Down Delay (ms): 0 + + 802.3ad info + LACP rate: slow + Min links: 0 + Aggregator selection policy (ad_select): stable + + Slave Interface: eth1 + MII Status: down + Speed: Unknown + Duplex: Unknown + Link Failure Count: 0 + Permanent HW addr: 00:50:56:bf:ef:aa + Slave queue ID: 0 + Aggregator ID: 1 + Actor Churn State: churned + Partner Churn State: churned + Actor Churned Count: 1 + Partner Churned Count: 1 + + Slave Interface: eth2 + MII Status: down + Speed: Unknown + Duplex: Unknown + Link Failure Count: 0 + Permanent HW addr: 00:50:56:bf:19:26 + Slave queue ID: 0 + Aggregator ID: 2 + Actor Churn State: churned + Partner Churn State: churned + Actor Churned Count: 1 + Partner Churned Count: 1 + diff --git a/docs/configuration/interfaces/bridge.rst b/docs/configuration/interfaces/bridge.rst new file mode 100644 index 00000000..7f49f9a8 --- /dev/null +++ b/docs/configuration/interfaces/bridge.rst @@ -0,0 +1,316 @@ +.. _bridge-interface: + +###### +Bridge +###### + +A Bridge is a way to connect two Ethernet segments together in a +protocol independent way. Packets are forwarded based on Ethernet +address, rather than IP address (like a router). Since forwarding is +done at Layer 2, all protocols can go transparently through a bridge. +The Linux bridge code implements a subset of the ANSI/IEEE 802.1d +standard. + +.. note:: Spanning Tree Protocol is not enabled by default in VyOS. + :ref:`stp` can be easily enabled if needed. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: bridge + :var1: br0 + +Member Interfaces +================= + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + + Assign `<member>` interface to bridge `<interface>`. A completion + helper will help you with all allowed interfaces which can be + bridged. This includes :ref:`ethernet-interface`, + :ref:`bond-interface`, :ref:`l2tpv3-interface`, :ref:`openvpn`, + :ref:`vxlan-interface`, :ref:`wireless-interface`, + :ref:`tunnel-interface` and :ref:`geneve-interface`. + + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + priority <priority> + + Configure individual bridge port `<priority>`. + + Each bridge has a relative priority and cost. Each interface is + associated with a port (number) in the STP code. Each has a priority + and a cost, that is used to decide which is the shortest path to + forward a packet. The lowest cost path is always used unless the + other path is down. If you have multiple bridges and interfaces then + you may need to adjust the priorities to achieve optimium + performance. + + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + cost <cost> + + Path `<cost>` value for Spanning Tree Protocol. Each interface in a + bridge could have a different speed and this value is used when + deciding which link to use. Faster interfaces should have lower + costs. + +Bridge Options +============== + +.. cfgcmd:: set interfaces bridge <interface> aging <time> + + MAC address aging `<time`> in seconds (default: 300). + +.. cfgcmd:: set interfaces bridge <interface> max-age <time> + + Bridge maximum aging `<time>` in seconds (default: 20). + + If a another bridge in the spanning tree does not send out a hello + packet for a long period of time, it is assumed to be dead. + +.. cfgcmd:: set interfaces bridge <interface> igmp querier + + Enable IGMP querier + +.. _stp: + +STP Parameter +------------- + +:abbr:`STP (Spanning Tree Protocol)` is a network protocol that builds a +loop-free logical topology for Ethernet networks. The basic function of +STP is to prevent bridge loops and the broadcast radiation that results +from them. Spanning tree also allows a network design to include backup +links providing fault tolerance if an active link fails. + +.. cfgcmd:: set interfaces bridge <interface> stp + + Enable spanning tree protocol. STP is disabled by default. + + +.. cfgcmd:: set interfaces bridge <interface> forwarding-delay <delay> + + Spanning Tree Protocol forwarding `<delay>` in seconds (default: 15). + + Forwarding delay time is the time spent in each of the Listening and + Learning states before the Forwarding state is entered. This delay is + so that when a new bridge comes onto a busy network it looks at some + traffic before participating. + + +.. cfgcmd:: set interfaces bridge <interface> hello-time <interval> + + Spanning Tree Protocol hello advertisement `<interval>` in seconds + (default: 2). + + Periodically, a hello packet is sent out by the Root Bridge and the + Designated Bridges. Hello packets are used to communicate information + about the topology throughout the entire Bridged Local Area Network. + +VLAN +==== + +Enable VLAN-Aware Bridge +------------------------ + +.. cfgcmd:: set interfaces bridge <interface> enable-vlan + + To activate the VLAN aware bridge, you must activate this setting to use VLAN + settings for the bridge + +VLAN Options +------------ + +.. note:: It is not valid to use the `vif 1` option for VLAN aware bridges + because VLAN aware bridges assume that all unlabeled packets belong to + the default VLAN 1 member and that the VLAN ID of the bridge's parent + interface is always 1 + +.. cmdinclude:: /_include/interface-vlan-8021q.txt + :var0: bridge + :var1: br0 + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + native-vlan <vlan-id> + + Set the native VLAN ID flag of the interface. When a data packet without a + VLAN tag enters the port, the data packet will be forced to add a tag of a + specific vlan id. When the vlan id flag flows out, the tag of the vlan id + will be stripped + + Example: Set `eth0` member port to be native VLAN 2 + + .. code-block:: none + + set interfaces bridge br1 member interface eth0 native-vlan 2 + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + allowed-vlan <vlan-id> + + Allows specific VLAN IDs to pass through the bridge member interface. This + can either be an individual VLAN id or a range of VLAN ids delimited by a + hyphen. + + Example: Set `eth0` member port to be allowed VLAN 4 + + .. code-block:: none + + set interfaces bridge br1 member interface eth0 allowed-vlan 4 + + Example: Set `eth0` member port to be allowed VLAN 6-8 + + .. code-block:: none + + set interfaces bridge br1 member interface eth0 allowed-vlan 6-8 + +Port Mirror (SPAN) +================== +.. cmdinclude:: ../../_include/interface-mirror.txt + :var0: bridge + :var1: br1 + :var2: eth3 + +******** +Examples +******** + +Create a basic bridge +===================== + +Creating a bridge interface is very simple. In this example we will +have: + +* A bridge named `br100` +* Member interfaces `eth1` and VLAN 10 on interface `eth2` +* Enable STP +* Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64 + +.. code-block:: none + + set interfaces bridge br100 address 192.0.2.1/24 + set interfaces bridge br100 address 2001:db8::ffff/64 + set interfaces bridge br100 member interface eth1 + set interfaces bridge br100 member interface eth2.10 + set interfaces bridge br100 stp + +This results in the active configuration: + +.. code-block:: none + + vyos@vyos# show interfaces bridge br100 + address 192.0.2.1/24 + address 2001:db8::ffff/64 + member { + interface eth1 { + } + interface eth2.10 { + } + } + stp + + +Using VLAN aware Bridge +======================= + +An example of creating a VLAN-aware bridge is as follows: + +* A bridge named `br100` +* The member interface `eth1` is a trunk that allows VLAN 10 to pass +* VLAN 10 on member interface `eth2` (ACCESS mode) +* Enable STP +* Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64 + +.. code-block:: none + + set interfaces bridge br100 enable-vlan + set interfaces bridge br100 member interface eth1 allowed-vlan 10 + set interfaces bridge br100 member interface eth2 native-vlan 10 + set interfaces bridge br100 vif 10 address 192.0.2.1/24 + set interfaces bridge br100 vif 10 address 2001:db8::ffff/64 + set interfaces bridge br100 stp + +This results in the active configuration: + +.. code-block:: none + + vyos@vyos# show interfaces bridge br100 + enable-vlan + member { + interface eth1 { + allowed-vlan 10 + } + interface eth2 { + native-vlan 10 + } + } + stp + vif 10 { + address 192.0.2.1/24 + address 2001:db8::ffff/64 + } + + +Using the operation mode command to view Bridge Information +=========================================================== + +.. opcmd:: show bridge + + The `show bridge` operational command can be used to display + configured bridges: + + .. code-block:: none + + vyos@vyos:~$ show bridge + bridge name bridge id STP enabled interfaces + br100 8000.0050569d11df yes eth1 + eth2.10 + +.. opcmd:: show bridge <name> spanning-tree + + Show bridge `<name>` STP configuration. + + .. code-block:: none + + vyos@vyos:~$ show bridge br100 spanning-tree + br100 + bridge id 8000.0050569d11df + designated root 8000.0050569d11df + root port 0 path cost 0 + max age 20.00 bridge max age 20.00 + hello time 2.00 bridge hello time 2.00 + forward delay 14.00 bridge forward delay 14.00 + ageing time 300.00 + hello timer 0.06 tcn timer 0.00 + topology change timer 0.00 gc timer 242.02 + flags + + eth1 (1) + port id 8001 state disabled + designated root 8000.0050569d11df path cost 100 + designated bridge 8000.0050569d11df message age timer 0.00 + designated port 8001 forward delay timer 0.00 + designated cost 0 hold timer 0.00 + flags + + eth2.10 (2) + port id 8002 state disabled + designated root 8000.0050569d11df path cost 100 + designated bridge 8000.0050569d11df message age timer 0.00 + designated port 8002 forward delay timer 0.00 + designated cost 0 hold timer 0.00 + +.. opcmd: show bridge <name> macs + + Show bridge Media Access Control (MAC) address table + + .. code-block:: none + + vyos@vyos:~$ show bridge br100 macs + port no mac addr is local? ageing timer + 1 00:53:29:44:3b:19 yes 0.00 diff --git a/docs/configuration/interfaces/dummy.rst b/docs/configuration/interfaces/dummy.rst new file mode 100644 index 00000000..c9845230 --- /dev/null +++ b/docs/configuration/interfaces/dummy.rst @@ -0,0 +1,79 @@ +.. _dummy-interface: + +##### +Dummy +##### + +The dummy interface is really a little exotic, but rather useful nevertheless. +Dummy interfaces are much like the :ref:`loopback-interface` interface, except +you can have as many as you want. + +.. note:: Dummy interfaces can be used as interfaces that always stay up (in + the same fashion to loopbacks in Cisco IOS), or for testing purposes. + +.. hint:: A Dummy interface is always up, thus it could be used for + management traffic or as source/destination for and :abbr:`IGP (Interior + Gateway Protocol)` like :ref:`bgp` so your internal BGP link is not dependent + on physical link states and multiple routes can be chosen to the + destination. A :ref:`dummy-interface` Interface should always be preferred + over a :ref:`loopback-interface` interface. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-address.txt + :var0: dummy + :var1: dum0 + +.. cmdinclude:: /_include/interface-description.txt + :var0: dummy + :var1: dum0 + +.. cmdinclude:: /_include/interface-disable.txt + :var0: dummy + :var1: dum0 + +.. cmdinclude:: /_include/interface-vrf.txt + :var0: dummy + :var1: dum0 + +********* +Operation +********* + +.. opcmd:: show interfaces dummy + + Show brief interface information.information + + .. code-block:: none + + vyos@vyos:~$ show interfaces dummy + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + dum0 172.18.254.201/32 u/u + +.. opcmd:: show interfaces dummy <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 + dum0: <BROADCAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN group default qlen 1000 + link/ether 26:7c:8e:bc:fc:f5 brd ff:ff:ff:ff:ff:ff + inet 172.18.254.201/32 scope global dum0 + valid_lft forever preferred_lft forever + inet6 fe80::247c:8eff:febc:fcf5/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 0 0 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 1369707 4267 0 0 0 0 + + diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst new file mode 100644 index 00000000..1d99019c --- /dev/null +++ b/docs/configuration/interfaces/ethernet.rst @@ -0,0 +1,315 @@ +.. _ethernet-interface: + +######## +Ethernet +######## + +This will be the most widely used interface on a router carrying traffic to the +real world. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: ethernet + :var1: eth0 + +Ethernet options +================ + +.. cfgcmd:: set interfaces ethernet <interface> duplex <auto | full | half> + + Configure physical interface duplex setting. + + * auto - interface duplex setting is auto-negotiated + * full - always use full-duplex + * half - always use half-duplex + + VyOS default will be `auto`. + +.. cfgcmd:: set interfaces ethernet <interface> speed <auto | 10 | 100 | 1000 | + 2500 | 5000 | 10000 | 25000 | 40000 | 50000 | 100000> + + Configure physical interface speed setting. + + * auto - interface speed is auto-negotiated + * 10 - 10 MBit/s + * 100 - 100 MBit/s + * 1000 - 1 GBit/s + * 2500 - 2.5 GBit/s + * 5000 - 5 GBit/s + * 10000 - 10 GBit/s + * 25000 - 25 GBit/s + * 40000 - 40 GBit/s + * 50000 - 50 GBit/s + * 100000 - 100 GBit/s + + VyOS default will be `auto`. + + +.. cfgcmd:: set interfaces ethernet <interface> mirror <interface> + + Use this command to mirror the inbound traffic from one Ethernet interface to + another interface. This feature is typically used to provide a copy of traffic + inbound on one interface to a system running a monitoring or IPS application + on another interface. The benefit of mirroring the traffic is that the + application is isolated from the source traffic and so application processing + does not affect the traffic or the system performance. + + Example: + + .. code-block:: none + + set interfaces ethernet eth0 mirror eth1 + +Offloading +---------- + +.. cfgcmd:: set interfaces ethernet <interface> offload <gro | gso | sg | tso | + ufo | rps> + + Enable different types of hardware offloading on the given NIC. + + :abbr:`GSO (Generic Segmentation Offload)` is a pure software offload that is + meant to deal with cases where device drivers cannot perform the offloads + described above. What occurs in GSO is that a given skbuff will have its data + broken out over multiple skbuffs that have been resized to match the MSS + provided via skb_shinfo()->gso_size. + + Before enabling any hardware segmentation offload a corresponding software + offload is required in GSO. Otherwise it becomes possible for a frame to be + re-routed between devices and end up being unable to be transmitted. + + :abbr:`GRO (Generic receive offload)` is the complement to GSO. Ideally any + frame assembled by GRO should be segmented to create an identical sequence of + frames using GSO, and any sequence of frames segmented by GSO should be able + to be reassembled back to the original by GRO. The only exception to this is + IPv4 ID in the case that the DF bit is set for a given IP header. If the + value of the IPv4 ID is not sequentially incrementing it will be altered so + that it is when a frame assembled via GRO is segmented via GSO. + + :abbr:`RPS (Receive Packet Steering)` is logically a software implementation + of :abbr:`RSS (Receive Side Scaling)`. Being in software, it is necessarily + called later in the datapath. Whereas RSS selects the queue and hence CPU that + will run the hardware interrupt handler, RPS selects the CPU to perform + protocol processing above the interrupt handler. This is accomplished by + placing the packet on the desired CPU's backlog queue and waking up the CPU + for processing. RPS has some advantages over RSS: + + - it can be used with any NIC, + - software filters can easily be added to hash over new protocols, + - it does not increase hardware device interrupt rate (although it does + introduce inter-processor interrupts (IPIs)). + + +.. cmdinclude:: /_include/interface-xdp.txt + :var0: ethernet + :var1: eth0 + +Authentication (EAPoL) +---------------------- + +.. cmdinclude:: /_include/interface-eapol.txt + :var0: ethernet + :var1: eth0 + + +VLAN +==== + +Regular VLANs (802.1q) +---------------------- + +.. cmdinclude:: /_include/interface-vlan-8021q.txt + :var0: ethernet + :var1: eth0 + +QinQ (802.1ad) +-------------- + +.. cmdinclude:: /_include/interface-vlan-8021ad.txt + :var0: ethernet + :var1: eth0 + +Port Mirror (SPAN) +================== +.. cmdinclude:: ../../_include/interface-mirror.txt + :var0: ethernet + :var1: eth1 + :var2: eth3 + +********* +Operation +********* + +.. opcmd:: show interfaces ethernet + + Show brief interface information. + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 172.18.201.10/24 u/u LAN + eth1 172.18.202.11/24 u/u WAN + eth2 - u/D + +.. opcmd:: show interfaces ethernet <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 + eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 + link/ether 00:50:44:00:f5:c9 brd ff:ff:ff:ff:ff:ff + inet6 fe80::250:44ff:fe00:f5c9/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 56735451 179841 0 0 0 142380 + TX: bytes packets errors dropped carrier collisions + 5601460 62595 0 0 0 0 + +.. stop_vyoslinter + +.. opcmd:: show interfaces ethernet <interface> physical + + Show information about physical `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 physical + Settings for eth0: + Supported ports: [ TP ] + Supported link modes: 1000baseT/Full + 10000baseT/Full + Supported pause frame use: No + Supports auto-negotiation: No + Supported FEC modes: Not reported + Advertised link modes: Not reported + Advertised pause frame use: No + Advertised auto-negotiation: No + Advertised FEC modes: Not reported + Speed: 10000Mb/s + Duplex: Full + Port: Twisted Pair + PHYAD: 0 + Transceiver: internal + Auto-negotiation: off + MDI-X: Unknown + Supports Wake-on: uag + Wake-on: d + Link detected: yes + driver: vmxnet3 + version: 1.4.16.0-k-NAPI + firmware-version: + expansion-rom-version: + bus-info: 0000:0b:00.0 + supports-statistics: yes + supports-test: no + supports-eeprom-access: no + supports-register-dump: yes + supports-priv-flags: no + +.. start_vyoslinter + +.. opcmd:: show interfaces ethernet <interface> physical offload + + Show available offloading functions on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 physical offload + rx-checksumming on + tx-checksumming on + tx-checksum-ip-generic on + scatter-gather off + tx-scatter-gather off + tcp-segmentation-offload off + tx-tcp-segmentation off + tx-tcp-mangleid-segmentation off + tx-tcp6-segmentation off + udp-fragmentation-offload off + generic-segmentation-offload off + generic-receive-offload off + large-receive-offload off + rx-vlan-offload on + tx-vlan-offload on + ntuple-filters off + receive-hashing on + tx-gre-segmentation on + tx-gre-csum-segmentation on + tx-udp_tnl-segmentation on + tx-udp_tnl-csum-segmentation on + tx-gso-partial on + tx-nocache-copy off + rx-all off + +.. opcmd:: show interfaces ethernet <interface> transceiver + + Show transceiver information from plugin modules, e.g SFP+, QSFP + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth5 transceiver + Identifier : 0x03 (SFP) + Extended identifier : 0x04 (GBIC/SFP defined by 2-wire interface ID) + Connector : 0x07 (LC) + Transceiver codes : 0x00 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00 + Transceiver type : Ethernet: 1000BASE-SX + Encoding : 0x01 (8B/10B) + BR, Nominal : 1300MBd + Rate identifier : 0x00 (unspecified) + Length (SMF,km) : 0km + Length (SMF) : 0m + Length (50um) : 550m + Length (62.5um) : 270m + Length (Copper) : 0m + Length (OM3) : 0m + Laser wavelength : 850nm + Vendor name : CISCO-FINISAR + Vendor OUI : 00:90:65 + Vendor PN : FTRJ-8519-7D-CS4 + Vendor rev : A + Option values : 0x00 0x1a + Option : RX_LOS implemented + Option : TX_FAULT implemented + Option : TX_DISABLE implemented + BR margin, max : 0% + BR margin, min : 0% + Vendor SN : FNS092xxxxx + Date code : 0506xx + +.. stop_vyoslinter + +.. opcmd:: show interfaces ethernet <interface> xdp + + Display XDP forwarding statistics + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth1 xdp + + Collecting stats from BPF map + - BPF map (bpf_map_type:6) id:176 name:xdp_stats_map key_size:4 value_size:16 max_entries:5 + XDP-action + XDP_ABORTED 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250340 + XDP_DROP 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250317 + XDP_PASS 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250314 + XDP_TX 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250313 + XDP_REDIRECT 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250313 + + XDP-action + XDP_ABORTED 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000410 + XDP_DROP 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000414 + XDP_PASS 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000414 + XDP_TX 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000414 + XDP_REDIRECT 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000414 + diff --git a/docs/configuration/interfaces/geneve.rst b/docs/configuration/interfaces/geneve.rst new file mode 100644 index 00000000..9e00d621 --- /dev/null +++ b/docs/configuration/interfaces/geneve.rst @@ -0,0 +1,61 @@ +.. _geneve-interface: + +###### +GENEVE +###### + +:abbr:`GENEVE (Generic Network Virtualization Encapsulation)` supports all of +the capabilities of :abbr:`VXLAN (Virtual Extensible LAN)`, :abbr:`NVGRE +(Network Virtualization using Generic Routing Encapsulation)`, and :abbr:`STT +(Stateless Transport Tunneling)` and was designed to overcome their perceived +limitations. Many believe GENEVE could eventually replace these earlier formats +entirely. + +GENEVE is designed to support network virtualization use cases, where tunnels +are typically established to act as a backplane between the virtual switches +residing in hypervisors, physical switches, or middleboxes or other appliances. +An arbitrary IP network can be used as an underlay although Clos networks - A +technique for composing network fabrics larger than a single switch while +maintaining non-blocking bandwidth across connection points. ECMP is used to +divide traffic across the multiple links and switches that constitute the +fabric. Sometimes termed "leaf and spine" or "fat tree" topologies. + +Geneve Header: + +.. code-block:: none + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + |Ver| Opt Len |O|C| Rsvd. | Protocol Type | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Virtual Network Identifier (VNI) | Reserved | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Variable Length Options | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-without-dhcp.txt + :var0: geneve + :var1: gnv0 + +GENEVE options +============== + +.. cfgcmd:: set interfaces geneve gnv0 remote <address> + + Configure GENEVE tunnel far end/remote tunnel endpoint. + +.. cfgcmd:: set interfaces geneve gnv0 vni <vni> + + :abbr:`VNI (Virtual Network Identifier)` is an identifier for a unique + element of a virtual network. In many situations this may represent an L2 + segment, however, the control plane defines the forwarding semantics of + decapsulated packets. The VNI MAY be used as part of ECMP forwarding + decisions or MAY be used as a mechanism to distinguish between overlapping + address spaces contained in the encapsulated packet when load balancing + across CPUs. diff --git a/docs/configuration/interfaces/index.rst b/docs/configuration/interfaces/index.rst new file mode 100644 index 00000000..85d2c177 --- /dev/null +++ b/docs/configuration/interfaces/index.rst @@ -0,0 +1,28 @@ +########## +Interfaces +########## + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + bonding + bridge + dummy + ethernet + geneve + l2tpv3 + loopback + macsec + openvpn + pppoe + pseudo-ethernet + tunnel + vti + vxlan + wireguard + wireless + wirelessmodem + + diff --git a/docs/configuration/interfaces/l2tpv3.rst b/docs/configuration/interfaces/l2tpv3.rst new file mode 100644 index 00000000..a4b7be36 --- /dev/null +++ b/docs/configuration/interfaces/l2tpv3.rst @@ -0,0 +1,192 @@ +.. include:: /_include/need_improvement.txt + +.. _l2tpv3-interface: + +###### +L2TPv3 +###### + +Layer 2 Tunnelling Protocol Version 3 is an IETF standard related to L2TP that +can be used as an alternative protocol to :ref:`mpls` for encapsulation of +multiprotocol Layer 2 communications traffic over IP networks. Like L2TP, +L2TPv3 provides a pseudo-wire service, but scaled to fit carrier requirements. + +L2TPv3 can be regarded as being to MPLS what IP is to ATM: a simplified version +of the same concept, with much of the same benefit achieved at a fraction of the +effort, at the cost of losing some technical features considered less important +in the market. + +In the case of L2TPv3, the features lost are teletraffic engineering features +considered important in MPLS. However, there is no reason these features could +not be re-engineered in or on top of L2TPv3 in later products. + +The protocol overhead of L2TPv3 is also significantly bigger than MPLS. + +L2TPv3 is described in :rfc:`3921`. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-without-dhcp.txt + :var0: l2tpv3 + :var1: l2tpeth0 + +L2TPv3 options +============== + +.. cfgcmd:: set interfaces l2tpv3 <interface> encapsulation <udp | ip> + + Set the encapsulation type of the tunnel. Valid values for encapsulation are: + udp, ip. + + This defaults to UDP + +.. cfgcmd:: set interfaces l2tpv3 <interface> local-ip <address> + + set the IP address of the local interface to be used for the tunnel. + + This address must be the address of a local interface. May be specified as an + IPv4 address or an IPv6 address. + +.. cfgcmd:: set interfaces l2tpv3 <interface> remote-ip <address> + + Set the IP address of the remote peer. May be specified as an IPv4 address or + an IPv6 address. + +.. cfgcmd:: set interfaces l2tpv3 <interface> session-id <id> + + Set the session id, which is a 32-bit integer value. Uniquely identifies the + session being created. The value used must match the peer_session_id value + being used at the peer. + +.. cfgcmd:: set interfaces l2tpv3 <interface> peer-session-id <id> + + Set the peer session id, which is a 32-bit integer value assigned to the + session by the peer. The value used must match the session_id value being + used at the peer. + +.. cfgcmd:: set interfaces l2tpv3 <interface> tunnel-id <id> + + Set the tunnel id, which is a 32-bit integer value. Uniquely identifies the + tunnel into which the session will be created. + +.. cfgcmd:: set interfaces l2tpv3 <interface> peer-tunnel-id <id> + + Set the tunnel id, which is a 32-bit integer value. Uniquely identifies the + tunnel into which the session will be created. + +******* +Example +******* + +Over IP +======= + +.. code-block:: none + + # show interfaces l2tpv3 + l2tpv3 l2tpeth10 { + address 192.168.37.1/27 + encapsulation ip + local-ip 192.0.2.1 + peer-session-id 100 + peer-tunnel-id 200 + remote-ip 203.0.113.24 + session-id 100 + tunnel-id 200 + } + +Inverse configuration has to be applied to the remote side. + +Over UDP +======== + +UDP mode works better with NAT: + +* Set local-ip to your local IP (LAN). +* Add a forwarding rule matching UDP port on your internet router. + +.. code-block:: none + + # show interfaces l2tpv3 + l2tpv3 l2tpeth10 { + address 192.168.37.1/27 + destination-port 9001 + encapsulation udp + local-ip 192.0.2.1 + peer-session-id 100 + peer-tunnel-id 200 + remote-ip 203.0.113.24 + session-id 100 + source-port 9000 + tunnel-id 200 + } + +To create more than one tunnel, use distinct UDP ports. + + +Over IPSec, L2 VPN (bridge) +=========================== + +This is the LAN extension use case. The eth0 port of the distant VPN peers +will be directly connected like if there was a switch between them. + +IPSec: + +.. code-block:: none + + set vpn ipsec ipsec-interfaces <VPN-interface> + set vpn ipsec esp-group test-ESP-1 compression 'disable' + set vpn ipsec esp-group test-ESP-1 lifetime '3600' + set vpn ipsec esp-group test-ESP-1 mode 'transport' + set vpn ipsec esp-group test-ESP-1 pfs 'enable' + set vpn ipsec esp-group test-ESP-1 proposal 1 encryption 'aes128' + set vpn ipsec esp-group test-ESP-1 proposal 1 hash 'sha1' + set vpn ipsec ike-group test-IKE-1 ikev2-reauth 'no' + set vpn ipsec ike-group test-IKE-1 key-exchange 'ikev1' + set vpn ipsec ike-group test-IKE-1 lifetime '3600' + set vpn ipsec ike-group test-IKE-1 proposal 1 dh-group '5' + set vpn ipsec ike-group test-IKE-1 proposal 1 encryption 'aes128' + set vpn ipsec ike-group test-IKE-1 proposal 1 hash 'sha1' + set vpn ipsec site-to-site peer <peer-ip> authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer <peer-ip> authentication pre-shared-secret <pre-shared-key> + set vpn ipsec site-to-site peer <peer-ip> connection-type 'initiate' + set vpn ipsec site-to-site peer <peer-ip> ike-group 'test-IKE-1' + set vpn ipsec site-to-site peer <peer-ip> ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer <peer-ip> local-address <local-ip> + set vpn ipsec site-to-site peer <peer-ip> tunnel 1 allow-nat-networks 'disable' + set vpn ipsec site-to-site peer <peer-ip> tunnel 1 allow-public-networks 'disable' + set vpn ipsec site-to-site peer <peer-ip> tunnel 1 esp-group 'test-ESP-1' + set vpn ipsec site-to-site peer <peer-ip> tunnel 1 protocol 'l2tp' + +Bridge: + +.. code-block:: none + + set interfaces bridge br0 description 'L2 VPN Bridge' + # remote side in this example: + # set interfaces bridge br0 address '172.16.30.18/30' + set interfaces bridge br0 address '172.16.30.17/30' + set interfaces bridge br0 member interface eth0 + set interfaces ethernet eth0 description 'L2 VPN Physical port' + +L2TPv3: + +.. code-block:: none + + set interfaces bridge br0 member interface 'l2tpeth0' + set interfaces l2tpv3 l2tpeth0 description 'L2 VPN Tunnel' + set interfaces l2tpv3 l2tpeth0 destination-port '5000' + set interfaces l2tpv3 l2tpeth0 encapsulation 'ip' + set interfaces l2tpv3 l2tpeth0 local-ip <local-ip> + set interfaces l2tpv3 l2tpeth0 mtu '1500' + set interfaces l2tpv3 l2tpeth0 peer-session-id '110' + set interfaces l2tpv3 l2tpeth0 peer-tunnel-id '10' + set interfaces l2tpv3 l2tpeth0 remote-ip <peer-ip> + set interfaces l2tpv3 l2tpeth0 session-id '110' + set interfaces l2tpv3 l2tpeth0 source-port '5000' + set interfaces l2tpv3 l2tpeth0 tunnel-id '10' diff --git a/docs/configuration/interfaces/loopback.rst b/docs/configuration/interfaces/loopback.rst new file mode 100644 index 00000000..f7386c62 --- /dev/null +++ b/docs/configuration/interfaces/loopback.rst @@ -0,0 +1,71 @@ +.. _loopback-interface: + +######## +Loopback +######## + +The loopback networking interface is a virtual network device implemented +entirely in software. All traffic sent to it "loops back" and just targets +services on your local machine. + +.. note:: There can only be one loopback ``lo`` interface on the system. If + you need multiple interfaces, please use the :ref:`dummy-interface` + interface type. + +.. hint:: A lookback interface is always up, thus it could be used for + management traffic or as source/destination for and :abbr:`IGP (Interior + Gateway Protocol)` like :ref:`bgp` so your internal BGP link is not dependent + on physical link states and multiple routes can be chosen to the + destination. A :ref:`dummy-interface` Interface should always be preferred + over a :ref:`loopback-interface` interface. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-address.txt + :var0: loopback + :var1: lo + +.. cmdinclude:: /_include/interface-description.txt + :var0: loopback + :var1: lo + +********* +Operation +********* + +.. opcmd:: show interfaces loopback + + Show brief interface information. + + .. code-block:: none + + vyos@vyos:~$ show interfaces loopback + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + lo 127.0.0.1/8 u/u + ::1/128 + +.. opcmd:: show interfaces loopback lo + + Show detailed information on given loopback interface `lo`. + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 + lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 + inet 127.0.0.1/8 scope host lo + valid_lft forever preferred_lft forever + inet6 ::1/128 scope host + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 300 6 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 300 6 0 0 0 0 diff --git a/docs/configuration/interfaces/macsec.rst b/docs/configuration/interfaces/macsec.rst new file mode 100644 index 00000000..2bf643aa --- /dev/null +++ b/docs/configuration/interfaces/macsec.rst @@ -0,0 +1,191 @@ +.. _macsec-interface: + +###### +MACsec +###### + +MACsec is an IEEE standard (IEEE 802.1AE) for MAC security, introduced in 2006. +It defines a way to establish a protocol independent connection between two +hosts with data confidentiality, authenticity and/or integrity, using +GCM-AES-128. MACsec operates on the Ethernet layer and as such is a layer 2 +protocol, which means it's designed to secure traffic within a layer 2 network, +including DHCP or ARP requests. It does not compete with other security +solutions such as IPsec (layer 3) or TLS (layer 4), as all those solutions are +used for their own specific use cases. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: macsec + :var1: macsec0 + +MACsec options +============== + +.. cfgcmd:: set interfaces macsec <interface> security cipher [gcm-aes-128] + + Select cipher suite used for cryptographic operations. This setting is + mandatory. + + .. note:: gcm-aes-256 support planned once iproute2 package is updated to + version >=5.2. + +.. cfgcmd:: set interfaces macsec <interface> security encrypt + + MACsec only provides authentication by default, encryption is optional. This + command will enable encryption for all outgoing packets. + +.. cfgcmd:: set interfaces macsec <interface> source-interface <physical-source> + + A physical interface is required to connect this MACsec instance to. Traffic + leaving this interfac will now be authenticated/encrypted. + +Key Management +-------------- + +:abbr:`MKA (MACsec Key Agreement protocol)` is used to synchronize keys between +individual peers. + +.. cfgcmd:: set interfaces macsec <interface> security mka cak <key> + + IEEE 802.1X/MACsec pre-shared key mode. This allows to configure MACsec with + a pre-shared key using a (CAK,CKN) pair. + +.. cfgcmd:: set interfaces macsec <interface> security mka ckn <key> + + CAK Name + +.. cfgcmd:: set interfaces macsec <interface> security mka priority <priority> + + The peer with lower priority will become the key server and start + distributing SAKs. + +Replay protection +----------------- + +.. cfgcmd:: set interfaces macsec <interface> security replay-window <window> + + IEEE 802.1X/MACsec replay protection window. This determines a window in which + replay is tolerated, to allow receipt of frames that have been misordered by + the network. + + - ``0``: No replay window, strict check + - ``1-4294967295``: Number of packets that could be misordered + +********* +Operation +********* + +.. opcmd:: run generate macsec mka-cak + + Generate :abbr:`MKA (MACsec Key Agreement protocol)` CAK key + + .. code-block:: none + + vyos@vyos:~$ generate macsec mka-cak + 20693b6e08bfa482703a563898c9e3ad + + +.. opcmd:: run generate macsec mka-ckn + + Generate :abbr:`MKA (MACsec Key Agreement protocol)` CAK key + + .. code-block:: none + + vyos@vyos:~$ generate macsec mka-ckn + 88737efef314ee319b2cbf30210a5f164957d884672c143aefdc0f5f6bc49eb2 + +.. opcmd:: show interfaces macsec + + List all MACsec interfaces + + .. code-block:: none + + vyos@vyos:~$ show interfaces macsec + 17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off + cipher suite: GCM-AES-128, using ICV length 16 + TXSC: 005056bfefaa0001 on SA 0 + 20: macsec0: protect on validate strict sc off sa off encrypt off send_sci on end_station off scb off replay off + cipher suite: GCM-AES-128, using ICV length 16 + TXSC: 005056bfefaa0001 on SA 0 + +.. opcmd:: show interfaces macsec <interface> + + Show specific MACsec interface information + + .. code-block:: none + + vyos@vyos:~$ show interfaces macsec macsec1 + 17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off + cipher suite: GCM-AES-128, using ICV length 16 + TXSC: 005056bfefaa0001 on SA 0 + +******** +Examples +******** + +* Two routers connected both via eth1 through an untrusted switch +* R1 has 192.0.2.1/24 & 2001:db8::1/64 +* R2 has 192.0.2.2/24 & 2001:db8::2/64 + +**R1** + +.. code-block:: none + + set interfaces macsec macsec1 address '192.0.2.1/24' + set interfaces macsec macsec1 address '2001:db8::1/64' + set interfaces macsec macsec1 security cipher 'gcm-aes-128' + set interfaces macsec macsec1 security encrypt + set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' + set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' + set interfaces macsec macsec1 source-interface 'eth1' + +**R2** + +.. code-block:: none + + set interfaces macsec macsec1 address '192.0.2.2/24' + set interfaces macsec macsec1 address '2001:db8::2/64' + set interfaces macsec macsec1 security cipher 'gcm-aes-128' + set interfaces macsec macsec1 security encrypt + set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' + set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' + set interfaces macsec macsec1 source-interface 'eth1' + +Pinging (IPv6) the other host and intercepting the traffic in ``eth1`` will +show you the content is encrypted. + +.. code-block:: none + + 17:35:44.586668 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: + 0x0000: 2c00 0000 000a 0050 56bf efaa 0001 d9fb ,......PV....... + 0x0010: 920a 8b8d 68ed 9609 29dd e767 25a4 4466 ....h...)..g%.Df + 0x0020: 5293 487b 9990 8517 3b15 22c7 ea5c ac83 R.H{....;."..\.. + 0x0030: 4c6e 13cf 0743 f917 2c4e 694e 87d1 0f09 Ln...C..,NiN.... + 0x0040: 0f77 5d53 ed75 cfe1 54df 0e5a c766 93cb .w]S.u..T..Z.f.. + 0x0050: c4f2 6e23 f200 6dfe 3216 c858 dcaa a73b ..n#..m.2..X...; + 0x0060: 4dd1 9358 d9e4 ed0e 072f 1acc 31c4 f669 M..X...../..1..i + 0x0070: e93a 9f38 8a62 17c6 2857 6ac5 ec11 8b0e .:.8.b..(Wj..... + 0x0080: 6b30 92a5 7ccc 720b k0..|.r. + +Disabling the encryption on the link by removing ``security encrypt`` will show +the unencrypted but authenticated content. + +.. code-block:: none + + 17:37:00.746155 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: + 0x0000: 2000 0000 0009 0050 56bf efaa 0001 86dd .......PV....... + 0x0010: 6009 86f3 0040 3a40 2001 0db8 0000 0000 `....@:@........ + 0x0020: 0000 0000 0000 0001 2001 0db8 0000 0000 ................ + 0x0030: 0000 0000 0000 0002 8100 d977 0f30 0003 ...........w.0.. + 0x0040: 1ca0 c65e 0000 0000 8d93 0b00 0000 0000 ...^............ + 0x0050: 1011 1213 1415 1617 1819 1a1b 1c1d 1e1f ................ + 0x0060: 2021 2223 2425 2627 2829 2a2b 2c2d 2e2f .!"#$%&'()*+,-./ + 0x0070: 3031 3233 3435 3637 87d5 eed3 3a39 d52b 01234567....:9.+ + 0x0080: a282 c842 5254 ef28 ...BRT.( + diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/openvpn.rst new file mode 100644 index 00000000..8b32743f --- /dev/null +++ b/docs/configuration/interfaces/openvpn.rst @@ -0,0 +1,590 @@ +.. _openvpn: + +####### +OpenVPN +####### + +Traditionally hardware routers implement IPsec exclusively due to relative +ease of implementing it in hardware and insufficient CPU power for doing +encryption in software. Since VyOS is a software router, this is less of a +concern. OpenVPN has been widely used on UNIX platform for a long time and is +a popular option for remote access VPN, though it's also capable of +site-to-site connections. + +Advantages of OpenVPN are: + +* It uses a single TCP or UDP connection and does not rely on packet source + addresses, so it will work even through a double NAT: perfect for public + hotspots and such + +* It's easy to setup and offers very flexible split tunneling + +* There's a variety of client GUI frontends for any platform + +Disadvantages are: + +* It's slower than IPsec due to higher protocol overhead and the fact it runs + in user mode while IPsec, on Linux, is in kernel mode + +* None of the operating systems have client software installed by default + +In the VyOS CLI, a key point often overlooked is that rather than being +configured using the `set vpn` stanza, OpenVPN is configured as a network +interface using `set interfaces openvpn`. + +Site-To-Site +============ + +While many are aware of OpenVPN as a Client VPN solution, it is often +overlooked as a site-to-site VPN solution due to lack of support for this mode +in many router platforms. + +Site-to-site mode supports x.509 but doesn't require it and can also work with +static keys, which is simpler in many cases. In this example, we'll configure +a simple site-to-site OpenVPN tunnel using a 2048-bit pre-shared key. + +First, one of the systems generate the key using the operational command +``generate openvpn key <filename>``. This will generate a key with the name +provided in the ``/config/auth/`` directory. Once generated, you will need to +copy this key to the remote router. + +In our example, we used the filename ``openvpn-1.key`` which we will reference +in our configuration. + +* The public IP address of the local side of the VPN will be 198.51.100.10 +* The remote will be 203.0.113.11 +* The tunnel will use 10.255.1.1 for the local IP and 10.255.1.2 for the remote. +* OpenVPN allows for either TCP or UDP. UDP will provide the lowest latency, + while TCP will work better for lossy connections; generally UDP is preferred + when possible. +* The official port for OpenVPN is 1194, which we reserve for client VPN; we + will use 1195 for site-to-site VPN. +* The ``persistent-tunnel`` directive will allow us to configure tunnel-related + attributes, such as firewall policy as we would on any normal network + interface. +* If known, the IP of the remote router can be configured using the + ``remote-host`` directive; if unknown, it can be omitted. We will assume a + dynamic IP for our remote router. + +Local Configuration: + +.. code-block:: none + + set interfaces openvpn vtun1 mode site-to-site + set interfaces openvpn vtun1 protocol udp + set interfaces openvpn vtun1 persistent-tunnel + set interfaces openvpn vtun1 local-host '198.51.100.10' + set interfaces openvpn vtun1 local-port '1195' + set interfaces openvpn vtun1 remote-port '1195' + set interfaces openvpn vtun1 shared-secret-key-file '/config/auth/openvpn-1.key' + set interfaces openvpn vtun1 local-address '10.255.1.1' + set interfaces openvpn vtun1 remote-address '10.255.1.2' + +Remote Configuration: + +.. code-block:: none + + set interfaces openvpn vtun1 mode site-to-site + set interfaces openvpn vtun1 protocol udp + set interfaces openvpn vtun1 persistent-tunnel + set interfaces openvpn vtun1 remote-host '198.51.100.10' + set interfaces openvpn vtun1 local-port '1195' + set interfaces openvpn vtun1 remote-port '1195' + set interfaces openvpn vtun1 shared-secret-key-file '/config/auth/openvpn-1.key' + set interfaces openvpn vtun1 local-address '10.255.1.2' + set interfaces openvpn vtun1 remote-address '10.255.1.1' + +The configurations above will default to using 256-bit AES in GCM mode +for encryption (if both sides supports NCP) and SHA-1 for HMAC authentication. +SHA-1 is considered weak, but other hashing algorithms are available, as are +encryption algorithms: + +For Encryption: + +This sets the cipher when NCP (Negotiable Crypto Parameters) is disabled or +OpenVPN version < 2.4.0. + +.. code-block:: none + + vyos@vyos# set interfaces openvpn vtun1 encryption cipher + Possible completions: + des DES algorithm + 3des DES algorithm with triple encryption + bf128 Blowfish algorithm with 128-bit key + bf256 Blowfish algorithm with 256-bit key + aes128 AES algorithm with 128-bit key CBC + aes128gcm AES algorithm with 128-bit key GCM + aes192 AES algorithm with 192-bit key CBC + aes192gcm AES algorithm with 192-bit key GCM + aes256 AES algorithm with 256-bit key CBC + aes256gcm AES algorithm with 256-bit key GCM + +This sets the accepted ciphers to use when version => 2.4.0 and NCP is +enabled (which is default). Default NCP cipher for versions >= 2.4.0 is +aes256gcm. The first cipher in this list is what server pushes to clients. + +.. code-block:: none + + vyos@vyos# set int open vtun0 encryption ncp-ciphers + Possible completions: + des DES algorithm + 3des DES algorithm with triple encryption + aes128 AES algorithm with 128-bit key CBC + aes128gcm AES algorithm with 128-bit key GCM + aes192 AES algorithm with 192-bit key CBC + aes192gcm AES algorithm with 192-bit key GCM + aes256 AES algorithm with 256-bit key CBC + aes256gcm AES algorithm with 256-bit key GCM + +For Hashing: + +.. code-block:: none + + vyos@vyos# set interfaces openvpn vtun1 hash + Possible completions: + md5 MD5 algorithm + sha1 SHA-1 algorithm + sha256 SHA-256 algorithm + sha512 SHA-512 algorithm + +If you change the default encryption and hashing algorithms, be sure that the +local and remote ends have matching configurations, otherwise the tunnel will +not come up. + +Static routes can be configured referencing the tunnel interface; for example, +the local router will use a network of 10.0.0.0/16, while the remote has a +network of 10.1.0.0/16: + +Local Configuration: + +.. code-block:: none + + set protocols static route 10.1.0.0/16 interface vtun1 + +Remote Configuration: + +.. code-block:: none + + set protocols static route 10.0.0.0/16 interface vtun1 + +Firewall policy can also be applied to the tunnel interface for `local`, `in`, +and `out` directions and function identically to ethernet interfaces. + +If making use of multiple tunnels, OpenVPN must have a way to distinguish +between different tunnels aside from the pre-shared-key. This is either by +referencing IP address or port number. One option is to dedicate a public IP +to each tunnel. Another option is to dedicate a port number to each tunnel +(e.g. 1195,1196,1197...). + +OpenVPN status can be verified using the `show openvpn` operational commands. +See the built-in help for a complete list of options. + +Server +====== + +Multi-client server is the most popular OpenVPN mode on routers. It always uses +x.509 authentication and therefore requires a PKI setup. Refer this section +**Generate X.509 Certificate and Keys** to generate a CA certificate, +a server certificate and key, a certificate revocation list, a Diffie-Hellman +key exchange parameters file. You do not need client certificates and keys for +the server setup. + +In this example we will use the most complicated case: a setup where each +client is a router that has its own subnet (think HQ and branch offices), since +simpler setups are subsets of it. + +Suppose you want to use 10.23.1.0/24 network for client tunnel endpoints and +all client subnets belong to 10.23.0.0/20. All clients need access to the +192.168.0.0/16 network. + +First we need to specify the basic settings. 1194/UDP is the default. The +``persistent-tunnel`` option is recommended, it prevents the TUN/TAP device from +closing on connection resets or daemon reloads. + +.. note:: Using **openvpn-option -reneg-sec** can be tricky. This option is + used to renegotiate data channel after n seconds. When used at both server + and client, the lower value will trigger the renegotiation. If you set it to + 0 on one side of the connection (to disable it), the chosen value on the + other side will determine when the renegotiation will occur. + +.. code-block:: none + + set interfaces openvpn vtun10 mode server + set interfaces openvpn vtun10 local-port 1194 + set interfaces openvpn vtun10 persistent-tunnel + set interfaces openvpn vtun10 protocol udp + +Then we need to specify the location of the cryptographic materials. Suppose +you keep the files in `/config/auth/openvpn` + +.. code-block:: none + + set interfaces openvpn vtun10 tls ca-cert-file /config/auth/openvpn/ca.crt + set interfaces openvpn vtun10 tls cert-file /config/auth/openvpn/server.crt + set interfaces openvpn vtun10 tls key-file /config/auth/openvpn/server.key + set interfaces openvpn vtun10 tls crl-file /config/auth/openvpn/crl.pem + set interfaces openvpn vtun10 tls dh-file /config/auth/openvpn/dh2048.pem + +Now we need to specify the server network settings. In all cases we need to +specify the subnet for client tunnel endpoints. Since we want clients to access +a specific network behind out router, we will use a push-route option for +installing that route on clients. + +.. code-block:: none + + set interfaces openvpn vtun10 server push-route 192.168.0.0/16 + set interfaces openvpn vtun10 server subnet 10.23.1.0/24 + +Since it's a HQ and branch offices setup, we will want all clients to have +fixed addresses and we will route traffic to specific subnets through them. We +need configuration for each client to achieve this. + +.. note:: Clients are identified by the CN field of their x.509 certificates, + in this example the CN is ``client0``: + +.. code-block:: none + + set interfaces openvpn vtun10 server client client0 ip 10.23.1.10 + set interfaces openvpn vtun10 server client client0 subnet 10.23.2.0/25 + +OpenVPN **will not** automatically create routes in the kernel for client +subnets when they connect and will only use client-subnet association +internally, so we need to create a route to the 10.23.0.0/20 network ourselves: + +.. code-block:: none + + set protocols static route 10.23.0.0/20 interface vtun10 + +Generate X.509 Certificate and Keys +----------------------------------- + +OpenVPN ships with a set of scripts called Easy-RSA that can generate the +appropriate files needed for an OpenVPN setup using X.509 certificates. +Easy-RSA comes installed by default on VyOS routers. + +Copy the Easy-RSA scripts to a new directory to modify the values. + +.. code-block:: none + + cp -r /usr/share/easy-rsa/ /config/my-easy-rsa-config + cd /config/my-easy-rsa-config + +To ensure the consistent use of values when generating the PKI, set default +values to be used by the PKI generating scripts. Rename the vars.example +filename to vars + +.. code-block:: none + + mv vars.example vars + +Following is the instance of the file after editing. You may also change other +values in the file at your discretion/need, though for most cases the defaults +should be just fine. (do not leave any of these parameters blank) + +.. code-block:: none + + set_var EASYRSA_DN "org" + set_var EASYRSA_REQ_COUNTRY "US" + set_var EASYRSA_REQ_PROVINCE "California" + set_var EASYRSA_REQ_CITY "San Francisco" + set_var EASYRSA_REQ_ORG "Copyleft Certificate Co" + set_var EASYRSA_REQ_EMAIL "me@example.net" + set_var EASYRSA_REQ_OU "My Organizational Unit" + set_var EASYRSA_KEY_SIZE 2048 + + +init-pki option will create a new pki directory or will delete any previously +generated certificates stored in that folder. The term 'central' is used to +refer server and 'branch' for client + +.. note:: Remember the “CA Key Passphrase” prompted in build-ca command, + as it will be asked in signing the server/client certificate. + +.. code-block:: none + + vyos@vyos:/config/my-easy-rsa-config$./easyrsa init-pki + vyos@vyos:/config/my-easy-rsa-config$./easyrsa build-ca + vyos@vyos:/config/my-easy-rsa-config$./easyrsa gen-req central nopass + vyos@vyos:/config/my-easy-rsa-config$./easyrsa sign-req server central + vyos@vyos:/config/my-easy-rsa-config$./easyrsa gen-dh + vyos@vyos:/config/my-easy-rsa-config$./easyrsa build-client-full branch1 nopass + +To generate a certificate revocation list for any client, execute these +commands: + +.. code-block:: none + + vyos@vyos:/config/my-easy-rsa-config$./easyrsa revoke client1 + vyos@vyos:/config/my-easy-rsa-config$ ./easyrsa gen-crl + +Copy the files to /config/auth/openvpn/ to use in OpenVPN tunnel creation + +.. code-block:: none + + vyos@vyos:/config/my-easy-rsa-config$ sudo mkdir /config/auth/openvpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/ca.crt /config/auth/openvpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/dh.pem /config/auth/openvpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/private/central.key /config/auth/openvpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/issued/central.crt /config/auth/openvpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/crl.pem /config/auth/openvpn + +Additionally, each client needs a copy of ca.crt and its own client key and +cert files. The files are plaintext so they may be copied either manually, +or through a remote file transfer tool like scp. Whichever method you use, +the files need to end up in the proper location on each router. +For example, Branch 1's router might have the following files: + +.. code-block:: none + + vyos@branch1-rtr:$ ls /config/auth/openvpn + ca.crt branch1.crt branch1.key + +Client Authentication +===================== + +LDAP +---- + +Enterprise installations usually ship a kind of directory service which is used +to have a single password store for all employees. VyOS and OpenVPN support +using LDAP/AD as single user backend. + +Authentication is done by using the ``openvpn-auth-ldap.so`` plugin which is +shipped with every VyOS installation. A dedicated configuration file is +required. It is best practise to store it in ``/config`` to survive image +updates + +.. code-block:: none + + set interfaces openvpn vtun0 openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" + +The required config file may look like: + +.. code-block:: none + + <LDAP> + # LDAP server URL + URL ldap://ldap.example.com + # Bind DN (If your LDAP server doesn't support anonymous binds) + BindDN cn=LDAPUser,dc=example,dc=com + # Bind Password password + Password S3cr3t + # Network timeout (in seconds) + Timeout 15 + </LDAP> + + <Authorization> + # Base DN + BaseDN "ou=people,dc=example,dc=com" + # User Search Filter + SearchFilter "(&(uid=%u)(objectClass=shadowAccount))" + # Require Group Membership - allow all users + RequireGroup false + </Authorization> + +Active Directory +^^^^^^^^^^^^^^^^ + +Despite the fact that AD is a superset of LDAP + +.. code-block:: none + + <LDAP> + # LDAP server URL + URL ldap://dc01.example.com + # Bind DN (If your LDAP server doesn’t support anonymous binds) + BindDN CN=LDAPUser,DC=example,DC=com + # Bind Password + Password mysecretpassword + # Network timeout (in seconds) + Timeout 15 + # Enable Start TLS + TLSEnable no + # Follow LDAP Referrals (anonymously) + FollowReferrals no + </LDAP> + + <Authorization> + # Base DN + BaseDN "DC=example,DC=com" + # User Search Filter, user must be a member of the VPN AD group + SearchFilter "(&(sAMAccountName=%u)(memberOf=CN=VPN,OU=Groups,DC=example,DC=com))" + # Require Group Membership + RequireGroup false # already handled by SearchFilter + <Group> + BaseDN "OU=Groups,DC=example,DC=com" + SearchFilter "(|(cn=VPN))" + MemberAttribute memberOf + </Group> + </Authorization> + +If you only want to check if the user account is enabled and can authenticate +(against the primary group) the following snipped is sufficient: + +.. code-block:: none + + <LDAP> + URL ldap://dc01.example.com + BindDN CN=SA_OPENVPN,OU=ServiceAccounts,DC=example,DC=com + Password ThisIsTopSecret + Timeout 15 + TLSEnable no + FollowReferrals no + </LDAP> + + <Authorization> + BaseDN "DC=example,DC=com" + SearchFilter "sAMAccountName=%u" + RequireGroup false + </Authorization> + +A complete LDAP auth OpenVPN configuration could look like the following +example: + +.. code-block:: none + + vyos@vyos# show interfaces openvpn + openvpn vtun0 { + mode server + openvpn-option "--tun-mtu 1500 --fragment 1300 --mssfix" + openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" + openvpn-option "--push redirect-gateway" + openvpn-option --duplicate-cn + openvpn-option --client-cert-not-required + openvpn-option --comp-lzo + openvpn-option --persist-key + openvpn-option --persist-tun + server { + domain-name example.com + max-connections 5 + name-server 203.0.113.0.10 + name-server 198.51.100.3 + subnet 172.18.100.128/29 + } + tls { + ca-cert-file /config/auth/ca.crt + cert-file /config/auth/server.crt + dh-file /config/auth/dh1024.pem + key-file /config/auth/server.key + } + } + +Client +====== + +VyOS can not only act as an OpenVPN site-to-site or Server for multiple clients. +You can indeed also configure any VyOS OpenVPN interface as an OpenVPN client +connecting to a VyOS OpenVPN server or any other OpenVPN server. + +Given the following example we have one VyOS router acting as OpenVPN server +and another VyOS router acting as OpenVPN client. The Server also pushes a +static client IP address to the OpenVPN client. Remember, clients are identified +using their CN attribute in the SSL certificate. + +Server +------ + +.. code-block:: none + + set interfaces openvpn vtun10 encryption cipher 'aes256' + set interfaces openvpn vtun10 hash 'sha512' + set interfaces openvpn vtun10 local-host '172.18.201.10' + set interfaces openvpn vtun10 local-port '1194' + set interfaces openvpn vtun10 mode 'server' + set interfaces openvpn vtun10 persistent-tunnel + set interfaces openvpn vtun10 protocol 'udp' + set interfaces openvpn vtun10 server client client1 ip '10.10.0.10' + set interfaces openvpn vtun10 server domain-name 'vyos.net' + set interfaces openvpn vtun10 server max-connections '250' + set interfaces openvpn vtun10 server name-server '172.16.254.30' + set interfaces openvpn vtun10 server subnet '10.10.0.0/24' + set interfaces openvpn vtun10 server topology 'subnet' + set interfaces openvpn vtun10 tls ca-cert-file '/config/auth/ca.crt' + set interfaces openvpn vtun10 tls cert-file '/config/auth/server.crt' + set interfaces openvpn vtun10 tls dh-file '/config/auth/dh.pem' + set interfaces openvpn vtun10 tls key-file '/config/auth/server.key' + set interfaces openvpn vtun10 use-lzo-compression + +Client +------ + +.. code-block:: none + + set interfaces openvpn vtun10 encryption cipher 'aes256' + set interfaces openvpn vtun10 hash 'sha512' + set interfaces openvpn vtun10 mode 'client' + set interfaces openvpn vtun10 persistent-tunnel + set interfaces openvpn vtun10 protocol 'udp' + set interfaces openvpn vtun10 remote-host '172.18.201.10' + set interfaces openvpn vtun10 remote-port '1194' + set interfaces openvpn vtun10 tls ca-cert-file '/config/auth/ca.crt' + set interfaces openvpn vtun10 tls cert-file '/config/auth/client1.crt' + set interfaces openvpn vtun10 tls key-file '/config/auth/client1.key' + set interfaces openvpn vtun10 use-lzo-compression + +Options +======= + +We do not have CLI nodes for every single OpenVPN options. If an option is +missing, a feature request should be opened at Phabricator_ so all users can +benefit from it (see :ref:`issues_features`). + +If you are a hacker or want to try on your own we support passing raw OpenVPN +options to OpenVPN. + +.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option 'persistent-key' + +Will add ``persistent-key`` at the end of the generated OpenVPN configuration. +Please use this only as last resort - things might break and OpenVPN won't start +if you pass invalid options/syntax. + +.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option + 'push "keepalive 1 10"' + +Will add ``push "keepalive 1 10"`` to the generated OpenVPN config file. + +.. note:: Sometimes option lines in the generated OpenVPN configurarion require + quotes. This is done through a hack on our config generator. You can pass + quotes using the ``"`` statement. + + +Troubleshooting +=============== + +VyOS provides some operational commands on OpenVPN. + +Check status +------------ + +The following commands let you check tunnel status. + +.. opcmd:: show openvpn client + + Use this command to check the tunnel status for OpenVPN client interfaces. + +.. opcmd:: show openvpn server + + Use this command to check the tunnel status for OpenVPN server interfaces. + +.. opcmd:: show openvpn site-to-site + + Use this command to check the tunnel status for OpenVPN site-to-site + interfaces. + + +Reset OpenVPN +------------- + +The following commands let you reset OpenVPN. + +.. opcmd:: reset openvpn client <text> + + Use this command to reset specified OpenVPN client. + +.. opcmd:: reset openvpn interface <interface> + + Uset this command to reset the OpenVPN process on a specific interface. + + + +.. include:: /_include/common-references.txt diff --git a/docs/configuration/interfaces/pppoe.rst b/docs/configuration/interfaces/pppoe.rst new file mode 100644 index 00000000..1bbccc0c --- /dev/null +++ b/docs/configuration/interfaces/pppoe.rst @@ -0,0 +1,317 @@ +.. _pppoe-interface: + +##### +PPPoE +##### + +:abbr:`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol +for encapsulating PPP frames inside Ethernet frames. It appeared in 1999, +in the context of the boom of DSL as the solution for tunneling packets +over the DSL connection to the :abbr:`ISPs (Internet Service Providers)` +IP network, and from there to the rest of the Internet. A 2005 networking +book noted that "Most DSL providers use PPPoE, which provides authentication, +encryption, and compression." Typical use of PPPoE involves leveraging the +PPP facilities for authenticating the user with a username and password, +predominately via the PAP protocol and less often via CHAP. + +*************** +Operating Modes +*************** + +VyOS supports setting up PPPoE in two different ways to a PPPoE internet +connection. This is due to most ISPs provide a modem that is also a wireless +router. + +Home Users +========== + +In this method, the DSL Modem/Router connects to the ISP for you with your +credentials preprogrammed into the device. This gives you an :rfc:`1918` +address, such as ``192.168.1.0/24`` by default. + +For a simple home network using just the ISP's equipment, this is usually +desirable. But if you want to run VyOS as your firewall and router, this +will result in having a double NAT and firewall setup. This results in a +few extra layers of complexity, particularly if you use some NAT or +tunnel features. + +Business Users +============== + +In order to have full control and make use of multiple static public IP +addresses, your VyOS will have to initiate the PPPoE connection and control +it. In order for this method to work, you will have to figure out how to make +your DSL Modem/Router switch into a Bridged Mode so it only acts as a DSL +Transceiver device to connect between the Ethernet link of your VyOS and the +phone cable. Once your DSL Transceiver is in Bridge Mode, you should get no +IP address from it. Please make sure you connect to the Ethernet Port 1 if +your DSL Transeiver has a switch, as some of them only work this way. + +Once you have an Ethernet device connected, i.e. `eth0`, then you can +configure it to open the PPPoE session for you and your DSL Transceiver +(Modem/Router) just acts to translate your messages in a way that +vDSL/aDSL understands. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-description.txt + :var0: pppoe + :var1: pppoe0 + +.. cmdinclude:: /_include/interface-disable.txt + :var0: pppoe + :var1: pppoe0 + +.. cmdinclude:: /_include/interface-vrf.txt + :var0: pppoe + :var1: pppoe0 + +PPPoE options +============= + +.. cfgcmd:: set interfaces pppoe <interface> access-concentrator <name> + + Use this command to restrict the PPPoE session on a given access + concentrator. Normally, a host sends a PPPoE initiation packet to start the + PPPoE discovery process, a number of access concentrators respond with offer + packets and the host selects one of the responding access concentrators to + serve this session. + + This command allows you to select a specific access concentrator when you + know the access concentrators `<name>`. + +.. cfgcmd:: set interfaces pppoe <interface> authentication user <username> + + Use this command to set the username for authenticating with a remote PPPoE + endpoint. Authentication is optional from the system's point of view but + most service providers require it. + +.. cfgcmd:: set interfaces pppoe <interface> authentication password <password> + + Use this command to set the password for authenticating with a remote PPPoE + endpoint. Authentication is optional from the system's point of view but + most service providers require it. + +.. cfgcmd:: set interfaces pppoe <interface> connect-on-demand + + When set the interface is enabled for "dial-on-demand". + + Use this command to instruct the system to establish a PPPoE connections + automatically once traffic passes through the interface. A disabled on-demand + connection is established at boot time and remains up. If the link fails for + any reason, the link is brought back up immediately. + + Enabled on-demand PPPoE connections bring up the link only when traffic needs + to pass this link. If the link fails for any reason, the link is brought + back up automatically once traffic passes the interface again. If you + configure an on-demand PPPoE connection, you must also configure the idle + timeout period, after which an idle PPPoE link will be disconnected. A + non-zero idle timeout will never disconnect the link after it first came up. + +.. cfgcmd:: set interfaces pppoe <interface> default-route [auto | force | none] + + Use this command to specify whether to automatically add a default route + pointing to the endpoint of the PPPoE when the link comes up. The default + route is only added if no other default route already exists in the system. + + **default:** A default route to the remote endpoint is automatically added + when the link comes up (i.e. auto). + + * auto: A default route is added if no other default route (From any + source) already exists. + * force: A default route is added after removing *all* existing default + routes. + * none: No default route is installed. + +.. note:: In all modes except 'none', all default routes using this interface + will be removed when the interface is torn down - even manually installed + static routes. + +.. cfgcmd:: set interfaces pppoe <interface> idle-timeout <time> + + Use this command to set the idle timeout interval to be used with on-demand + PPPoE sessions. When an on-demand connection is established, the link is + brought up only when traffic is sent and is disabled when the link is idle + for the interval specified. + + If this parameter is not set or 0, an on-demand link will not be taken down + when it is idle and after the initial establishment of the connection. It + will stay up forever. + +.. cfgcmd:: set interfaces pppoe <interface> local-address <address> + + Use this command to set the IP address of the local endpoint of a PPPoE + session. If it is not set it will be negotiated. + +.. cfgcmd:: set interfaces pppoe <interface> mtu <mtu> + + Configure :abbr:`MTU (Maximum Transmission Unit)` on given `<interface>`. It + is the size (in bytes) of the largest ethernet frame sent on this link. + +.. cfgcmd:: set interfaces pppoe <interface> no-peer-dns + + Use this command to not install advertised DNS nameservers into the local + system. + +.. cfgcmd:: set interfaces pppoe <interface> remote-address <address> + + Use this command to set the IP address of the remote endpoint of a PPPoE + session. If it is not set it will be negotiated. + +.. cfgcmd:: set interfaces pppoe <interface> service-name <name> + + Use this command to specify a service name by which the local PPPoE interface + can select access concentrators to connect with. It will connect to any + access concentrator if not set. + +.. cfgcmd:: set interfaces pppoe <interface> source-interface <source-interface> + + Use this command to link the PPPoE connection to a physical interface. Each + PPPoE connection must be established over a physical interface. Interfaces + can be regular Ethernet interfaces, VIFs or bonding interfaces/VIFs. + +IPv6 +---- + +.. cfgcmd:: set interfaces pppoe <interface> ipv6 address autoconf + + Use this command to enable acquisition of IPv6 address using stateless + autoconfig (SLAAC). + +.. cmdinclude:: /_include/interface-dhcpv6-prefix-delegation.txt + :var0: pppoe + :var1: pppoe0 + +********* +Operation +********* + +.. opcmd:: show interfaces pppoe <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces pppoe pppoe0 + pppoe0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1492 qdisc pfifo_fast state UNKNOWN group default qlen 3 + link/ppp + inet 192.0.2.1 peer 192.0.2.255/32 scope global pppoe0 + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 7002658233 5064967 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 533822843 1620173 0 0 0 0 + +.. opcmd:: show interfaces pppoe <interface> queue + + Displays queue information for a PPPoE interface. + + .. code-block:: none + + vyos@vyos:~$ show interfaces pppoe pppoe0 queue + qdisc pfifo_fast 0: root refcnt 2 bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 + Sent 534625359 bytes 1626761 pkt (dropped 62, overlimits 0 requeues 0) + backlog 0b 0p requeues 0 + +Connect/Disconnect +================== + +.. opcmd:: disconnect interface <interface> + + Test disconnecting given connection-oriented interface. `<interface>` can be + ``pppoe0`` as example. + +.. opcmd:: connect interface <interface> + + Test connecting given connection-oriented interface. `<interface>` can be + ``pppoe0`` as example. + +******* +Example +******* + +Requirements: + +* Your ISPs modem is connected to port ``eth0`` of your VyOS box. +* No VLAN tagging required by your ISP. +* You need your PPPoE credentials from your DSL ISP in order to configure + this. The usual username is in the form of name@host.net but may vary + depending on ISP. +* The largest MTU size you can use with DSL is 1492 due to PPPoE overhead. + If you are switching from a DHCP based ISP like cable then be aware that + things like VPN links may need to have their MTU sizes adjusted to work + within this limit. +* With the ``default-route`` option set to ``auto``, VyOS will only add the + default gateway you receive from your DSL ISP to the routing table if you + have no other WAN connections. If you wish to use a dual WAN connection, + change the ``default-route`` option to ``force``. You could also install + a static route and set the ``default-route`` option to ``none``. +* With the ``name-server`` option set to ``none``, VyOS will ignore the + nameservers your ISP sens you and thus you can fully rely on the ones you + have configured statically. + +.. note:: Syntax has changed from VyOS 1.2 (crux) and it will be automatically + migrated during an upgrade. + +.. code-block:: none + + set interfaces pppoe pppoe0 default-route 'auto' + set interfaces pppoe pppoe0 mtu 1492 + set interfaces pppoe pppoe0 authentication user 'userid' + set interfaces pppoe pppoe0 authentication password 'secret' + set interfaces pppoe pppoe0 source-interface 'eth0' + + +You should add a firewall to your configuration above as well by +assigning it to the pppoe0 itself as shown here: + +.. code-block:: none + + set interfaces pppoe pppoe0 firewall in name NET-IN + set interfaces pppoe pppoe0 firewall local name NET-LOCAL + set interfaces pppoe pppoe0 firewall out name NET-OUT + +VLAN Example +============ + +Some recent ISPs require you to build the PPPoE connection through a VLAN +interface. One of those ISPs is e.g. Deutsche Telekom in Germany. VyOS +can easily create a PPPoE session through an encapsulated VLAN interface. +The following configuration will run your PPPoE connection through VLAN7 +which is the default VLAN for Deutsche Telekom: + +.. code-block:: none + + set interfaces pppoe pppoe0 default-route 'auto' + set interfaces pppoe pppoe0 mtu 1492 + set interfaces pppoe pppoe0 authentication user 'userid' + set interfaces pppoe pppoe0 authentication password 'secret' + set interfaces pppoe pppoe0 source-interface 'eth0.7' + + +IPv6 DHCPv6-PD Example +---------------------- + +.. stop_vyoslinter + +The following configuration will assign a /64 prefix out of a /56 delegation +to eth0. The IPv6 address assigned to eth0 will be <prefix>::ffff/64. +If you do not know the prefix size delegated to you, start with sla-len 0. + +.. start_vyoslinter + +.. code-block:: none + + set interfaces pppoe pppoe0 authentication user vyos + set interfaces pppoe pppoe0 authentication password vyos + set interfaces pppoe pppoe0 dhcpv6-options prefix-delegation interface eth0 address 65535 + set interfaces pppoe pppoe0 dhcpv6-options prefix-delegation interface eth0 sla-id 0 + set interfaces pppoe pppoe0 dhcpv6-options prefix-delegation interface eth0 sla-len 8 + set interfaces pppoe pppoe0 ipv6 address autoconf + set interfaces pppoe pppoe0 source-interface eth1 diff --git a/docs/configuration/interfaces/pseudo-ethernet.rst b/docs/configuration/interfaces/pseudo-ethernet.rst new file mode 100644 index 00000000..0471d2e1 --- /dev/null +++ b/docs/configuration/interfaces/pseudo-ethernet.rst @@ -0,0 +1,65 @@ +.. _pseudo-ethernet-interface: + +####################### +Pseudo Ethernet/MACVLAN +####################### + +Pseudo-Ethernet or MACVLAN interfaces can be seen as subinterfaces to regular +ethernet interfaces. Each and every subinterface is created a different media +access control (MAC) address, for a single physical Ethernet port. Pseudo- +Ethernet interfaces have most of their application in virtualized environments, + +By using Pseudo-Ethernet interfaces there will be less system overhead compared +to running a traditional bridging approach. Pseudo-Ethernet interfaces can also +be used to workaround the general limit of 4096 virtual LANs (VLANs) per +physical Ethernet port, since that limit is with respect to a single MAC +address. + +Every Virtual Ethernet interfaces behaves like a real Ethernet interface. They +can have IPv4/IPv6 addresses configured, or can request addresses by DHCP/ +DHCPv6 and are associated/mapped with a real ethernet port. This also makes +Pseudo-Ethernet interfaces interesting for testing purposes. A Pseudo-Ethernet +device will inherit characteristics (speed, duplex, ...) from its physical +parent (the so called link) interface. + +Once created in the system, Pseudo-Ethernet interfaces can be referenced in +the exact same way as other Ethernet interfaces. Notes about using Pseudo- +Ethernet interfaces: + +* Pseudo-Ethernet interfaces can not be reached from your internal host. This + means that you can not try to ping a Pseudo-Ethernet interface from the host + system on which it is defined. The ping will be lost. +* Loopbacks occurs at the IP level the same way as for other interfaces, + ethernet frames are not forwarded between Pseudo-Ethernet interfaces. +* Pseudo-Ethernet interfaces may not work in environments which expect a + :abbr:`NIC (Network Interface Card)` to only have a single address. This + applies to: + - VMware machines using default settings + - Network switches with security settings allowing only a single MAC address + - xDSL modems that try to lear the MAC address of the NIC + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: pseudo-ethernet + :var1: peth0 + +Pseudo Ethernet/MACVLAN options +=============================== + +.. cfgcmd:: set interfaces pseudo-ethernet <interface> source-interface <ethX> + + Specifies the physical `<ethX>` Ethernet interface associated with a Pseudo + Ethernet `<interface>`. + +VLAN +==== + +.. cmdinclude:: /_include/interface-vlan-8021q.txt + :var0: pseudo-ethernet + :var1: peth0 diff --git a/docs/configuration/interfaces/tunnel.rst b/docs/configuration/interfaces/tunnel.rst new file mode 100644 index 00000000..d2d63ce2 --- /dev/null +++ b/docs/configuration/interfaces/tunnel.rst @@ -0,0 +1,265 @@ +.. _tunnel-interface: + +Tunnel +====== + +This article touches on 'classic' IP tunneling protocols. + +GRE is often seen as a one size fits all solution when it comes to classic IP +tunneling protocols, and for a good reason. However, there are more specialized +options, and many of them are supported by VyOS. There are also rather obscure +GRE options that can be useful. + +All those protocols are grouped under ``interfaces tunnel`` in VyOS. Let's take +a closer look at the protocols and options currently supported by VyOS. + +Common interface configuration +------------------------------ + +.. cmdinclude:: /_include/interface-common-without-dhcp.txt + :var0: tunnel + :var1: tun0 + +IPIP +---- + +This is one of the simplest types of tunnels, as defined by :rfc:`2003`. +It takes an IPv4 packet and sends it as a payload of another IPv4 packet. For +this reason, there are no other configuration options for this kind of tunnel. + +An example: + +.. code-block:: none + + set interfaces tunnel tun0 encapsulation ipip + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 203.0.113.20 + set interfaces tunnel tun0 address 192.168.100.200/24 + +IP6IP6 +------ + +This is the IPv6 counterpart of IPIP. I'm not aware of an RFC that defines this +encapsulation specifically, but it's a natural specific case of IPv6 +encapsulation mechanisms described in :rfc:2473`. + +It's not likely that anyone will need it any time soon, but it does exist. + +An example: + +.. code-block:: none + + set interfaces tunnel tun0 encapsulation ip6ip6 + set interfaces tunnel tun0 local-ip 2001:db8:aa::1 + set interfaces tunnel tun0 remote-ip 2001:db8:aa::2 + set interfaces tunnel tun0 address 2001:db8:bb::1/64 + +IPIP6 +----- + +In the future this is expected to be a very useful protocol (though there are +`other proposals`_). + +As the name implies, it's IPv4 encapsulated in IPv6, as simple as that. + +An example: + +.. code-block:: none + + set interfaces tunnel tun0 encapsulation ipip6 + set interfaces tunnel tun0 local-ip 2001:db8:aa::1 + set interfaces tunnel tun0 remote-ip 2001:db8:aa::2 + set interfaces tunnel tun0 address 192.168.70.80/24 + +6in4 (SIT) +---------- + +6in4 uses tunneling to encapsulate IPv6 traffic over IPv4 links as defined in +:rfc:`4213`. The 6in4 traffic is sent over IPv4 inside IPv4 packets whose IP +headers have the IP protocol number set to 41. This protocol number is +specifically designated for IPv6 encapsulation, the IPv4 packet header is +immediately followed by the IPv6 packet being carried. The encapsulation +overhead is the size of the IPv4 header of 20 bytes, therefore with an MTU of +1500 bytes, IPv6 packets of 1480 bytes can be sent without fragmentation. This +tunneling technique is frequently used by IPv6 tunnel brokers like `Hurricane +Electric`_. + +An example: + +.. code-block:: none + + set interfaces tunnel tun0 encapsulation sit + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 192.0.2.20 + set interfaces tunnel tun0 address 2001:db8:bb::1/64 + +A full example of a Tunnelbroker.net config can be found at +:ref:`here <examples-tunnelbroker-ipv6>`. + +Generic Routing Encapsulation (GRE) +----------------------------------- + +A GRE tunnel operates at layer 3 of the OSI model and is repsented by IP +protocol 47.The main benefit of a GRE tunnel is that you are able to carry +multiple protocols inside the same tunnel. GRE also supports multicast traffic +and supports routing protocols that leverage multicast to form neighbor +adjacencies. + +A VyOS GRE tunnel can carry both IPv4 and IPv6 traffic and can also be created +over either IPv4 (gre) or IPv6 (ip6gre). + + +Configuration +^^^^^^^^^^^^^ + +A basic configuration requires a tunnel source (local-ip), a tunnel destination +(remote-ip), an encapsulation type (gre), and an address (ipv4/ipv6).Below is a +basic IPv4 only configuration example taken from a VyOS router and a Cisco IOS +router. The main difference between these two configurations is that VyOS +requires you explicitly configure the encapsulation type. The Cisco router +defaults to gre ip otherwise it would have to be configured as well. + +**VyOS Router:** + +.. code-block:: none + + set interfaces tunnel tun100 address '10.0.0.1/30' + set interfaces tunnel tun100 encapsulation 'gre' + set interfaces tunnel tun100 local-ip '198.51.100.2' + set interfaces tunnel tun100 remote-ip '203.0.113.10' + +**Cisco IOS Router:** + +.. code-block:: none + + interface Tunnel100 + ip address 10.0.0.2 255.255.255.252 + tunnel source 203.0.113.10 + tunnel destination 198.51.100.2 + +Here is a second example of a dual-stack tunnel over IPv6 between a VyOS router +and a Linux host using systemd-networkd. + +**VyOS Router:** + +.. code-block:: none + + set interfaces tunnel tun101 address '2001:db8:feed:beef::1/126' + set interfaces tunnel tun101 address '192.168.5.1/30' + set interfaces tunnel tun101 encapsulation 'ip6gre' + set interfaces tunnel tun101 local-ip '2001:db8:babe:face::3afe:3' + set interfaces tunnel tun101 remote-ip '2001:db8:9bb:3ce::5' + +**Linux systemd-networkd:** + +This requires two files, one to create the device (XXX.netdev) and one +to configure the network on the device (XXX.network) + +.. code-block:: none + + # cat /etc/systemd/network/gre-example.netdev + [NetDev] + Name=gre-example + Kind=ip6gre + MTUBytes=14180 + + [Tunnel] + Remote=2001:db8:babe:face::3afe:3 + + + # cat /etc/systemd/network/gre-example.network + [Match] + Name=gre-example + + [Network] + Address=2001:db8:feed:beef::2/126 + + [Address] + Address=192.168.5.2/30 + +Tunnel keys +^^^^^^^^^^^ + +GRE is also the only classic protocol that allows creating multiple tunnels +with the same source and destination due to its support for tunnel keys. +Despite its name, this feature has nothing to do with security: it's simply +an identifier that allows routers to tell one tunnel from another. + +An example: + +.. code-block:: none + + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 192.0.2.20 + set interfaces tunnel tun0 address 10.40.50.60/24 + set interfaces tunnel tun0 parameters ip key 10 + +.. code-block:: none + + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 192.0.2.20 + set interfaces tunnel tun0 address 172.16.17.18/24 + set interfaces tunnel tun0 parameters ip key 20 + + +Troubleshooting +^^^^^^^^^^^^^^^ + +GRE is a well defined standard that is common in most networks. While not +inherently difficult to configure there are a couple of things to keep in mind +to make sure the configuration performs as expected. A common cause for GRE +tunnels to fail to come up correctly include ACL or Firewall configurations +that are discarding IP protocol 47 or blocking your source/desintation traffic. + +**1. Confirm IP connectivity between tunnel local-ip and remote-ip:** + +.. code-block:: none + + vyos@vyos:~$ ping 203.0.113.10 interface 198.51.100.2 count 4 + PING 203.0.113.10 (203.0.113.10) from 198.51.100.2 : 56(84) bytes of data. + 64 bytes from 203.0.113.10: icmp_seq=1 ttl=254 time=0.807 ms + 64 bytes from 203.0.113.10: icmp_seq=2 ttl=254 time=1.50 ms + 64 bytes from 203.0.113.10: icmp_seq=3 ttl=254 time=0.624 ms + 64 bytes from 203.0.113.10: icmp_seq=4 ttl=254 time=1.41 ms + + --- 203.0.113.10 ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3007ms + rtt min/avg/max/mdev = 0.624/1.087/1.509/0.381 ms + +**2. Confirm the link type has been set to GRE:** + +.. code-block:: none + + vyos@vyos:~$ show interfaces tunnel tun100 + tun100@NONE: <POINTOPOINT,NOARP,UP,LOWER_UP> mtu 1476 qdisc noqueue state UNKNOWN group default qlen 1000 + link/gre 198.51.100.2 peer 203.0.113.10 + inet 10.0.0.1/30 brd 10.0.0.3 scope global tun100 + valid_lft forever preferred_lft forever + inet6 fe80::5efe:c612:2/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 2183 27 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 836 9 0 0 0 0 + +**3. Confirm IP connectivity across the tunnel:** + +.. code-block:: none + + vyos@vyos:~$ ping 10.0.0.2 interface 10.0.0.1 count 4 + PING 10.0.0.2 (10.0.0.2) from 10.0.0.1 : 56(84) bytes of data. + 64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=1.05 ms + 64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=1.88 ms + 64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=1.98 ms + 64 bytes from 10.0.0.2: icmp_seq=4 ttl=255 time=1.98 ms + + --- 10.0.0.2 ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3008ms + rtt min/avg/max/mdev = 1.055/1.729/1.989/0.395 ms + +.. note:: There is also a GRE over IPv6 encapsulation available, it is + called: ``ip6gre``. + +.. _`other proposals`: https://www.isc.org/othersoftware/ +.. _`Hurricane Electric`: https://tunnelbroker.net/ diff --git a/docs/configuration/interfaces/vti.rst b/docs/configuration/interfaces/vti.rst new file mode 100644 index 00000000..62cd13f3 --- /dev/null +++ b/docs/configuration/interfaces/vti.rst @@ -0,0 +1,22 @@ +############################## +Virtual Tunnel Interface (VTI) +############################## + + +Set Virtual Tunnel Interface + +.. code-block:: none + + set interfaces vti vti0 address 192.168.2.249/30 + set interfaces vti vti0 address 2001:db8:2::249/64 + +Results in: + +.. code-block:: none + + vyos@vyos# show interfaces vti + vti vti0 { + address 192.168.2.249/30 + address 2001:db8:2::249/64 + description "Description" + }
\ No newline at end of file diff --git a/docs/configuration/interfaces/vxlan.rst b/docs/configuration/interfaces/vxlan.rst new file mode 100644 index 00000000..ca25d21e --- /dev/null +++ b/docs/configuration/interfaces/vxlan.rst @@ -0,0 +1,295 @@ +.. _vxlan-interface: + +##### +VXLAN +##### + +:abbr:`VXLAN (Virtual Extensible LAN)` is a network virtualization technology +that attempts to address the scalability problems associated with large cloud +computing deployments. It uses a VLAN-like encapsulation technique to +encapsulate OSI layer 2 Ethernet frames within layer 4 UDP datagrams, using +4789 as the default IANA-assigned destination UDP port number. VXLAN +endpoints, which terminate VXLAN tunnels and may be either virtual or physical +switch ports, are known as :abbr:`VTEPs (VXLAN tunnel endpoints)`. + +VXLAN is an evolution of efforts to standardize on an overlay encapsulation +protocol. It increases scalability up to 16 million logical networks and +allows for layer 2 adjacency across IP networks. Multicast or unicast with +head-end replication (HER) is used to flood broadcast, unknown unicast, +and multicast (BUM) traffic. + +The VXLAN specification was originally created by VMware, Arista Networks +and Cisco. Other backers of the VXLAN technology include Huawei, Broadcom, +Citrix, Pica8, Big Switch Networks, Cumulus Networks, Dell EMC, Ericsson, +Mellanox, FreeBSD, OpenBSD, Red Hat, Joyent, and Juniper Networks. + +VXLAN was officially documented by the IETF in :rfc:`7348`. + +If configuring VXLAN in a VyOS virtual machine, ensure that MAC spoofing +(Hyper-V) or Forged Transmits (ESX) are permitted, otherwise forwarded frames +may be blocked by the hypervisor. + +.. note:: As VyOS is based on Linux and there was no official IANA port assigned + for VXLAN, VyOS uses a default port of 8472. You can change the port on a + per VXLAN interface basis to get it working across multiple vendors. + +Configuration +============= + +Common interface configuration +------------------------------ + +.. cmdinclude:: /_include/interface-common-without-dhcp.txt + :var0: vxlan + :var1: vxlan0 + +VXLAN specific options +----------------------- + +.. cfgcmd:: set interfaces vxlan <interface> vni <number> + + Each VXLAN segment is identified through a 24-bit segment ID, termed the + :abbr:`VNI (VXLAN Network Identifier (or VXLAN Segment ID))`, This allows + up to 16M VXLAN segments to coexist within the same administrative domain. + +.. cfgcmd:: set interfaces vxlan <interface> port <port> + + Configure port number of remote VXLAN endpoint. + + .. note:: As VyOS is Linux based the default port used is not using 4789 + as the default IANA-assigned destination UDP port number. Instead VyOS + uses the Linux default port of 8472. + +.. cfgcmd:: set interfaces vxlan <interface> source-address <interface> + + Source IP address used for VXLAN underlay. This is mandatory when using VXLAN + via L2VPN/EVPN. + +Unicast +^^^^^^^ + +.. cfgcmd:: set interfaces vxlan <interface> remote <address> + + IPv4/IPv6 remote address of the VXLAN tunnel. Alternative to multicast, the + remote IPv4/IPv6 address can set directly. + +Multicast +^^^^^^^^^ + +.. cfgcmd:: set interfaces vxlan <interface> source-interface <interface> + + Interface used for VXLAN underlay. This is mandatory when using VXLAN via + a multicast network. VXLAN traffic will always enter and exit this interface. + + +.. cfgcmd:: set interfaces vxlan <interface> group <address> + + Multicast group address for VXLAN interface. VXLAN tunnels can be built + either via Multicast or via Unicast. + + Both IPv4 and IPv6 multicast is possible. + +Multicast VXLAN +=============== + +Topology: PC4 - Leaf2 - Spine1 - Leaf3 - PC5 + +PC4 has IP 10.0.0.4/24 and PC5 has IP 10.0.0.5/24, so they believe they are in +the same broadcast domain. + +Let's assume PC4 on Leaf2 wants to ping PC5 on Leaf3. Instead of setting Leaf3 +as our remote end manually, Leaf2 encapsulates the packet into a UDP-packet and +sends it to its designated multicast-address via Spine1. When Spine1 receives +this packet it forwards it to all other Leafs who has joined the same +multicast-group, in this case Leaf3. When Leaf3 receives the packet it forwards +it, while at the same time learning that PC4 is reachable behind Leaf2, because +the encapsulated packet had Leaf2's IP-address set as source IP. + +PC5 receives the ping echo, responds with an echo reply that Leaf3 receives and +this time forwards to Leaf2's unicast address directly because it learned the +location of PC4 above. When Leaf2 receives the echo reply from PC5 it sees that +it came from Leaf3 and so remembers that PC5 is reachable via Leaf3. + +Thanks to this discovery, any subsequent traffic between PC4 and PC5 will not +be using the multicast-address between the Leafs as they both know behind which +Leaf the PCs are connected. This saves traffic as less multicast packets sent +reduces the load on the network, which improves scalability when more Leafs are +added. + +For optimal scalability Multicast shouldn't be used at all, but instead use BGP +to signal all connected devices between leafs. Unfortunately, VyOS does not yet +support this. + +Example +------- + +The setup is this: Leaf2 - Spine1 - Leaf3 + +Spine1 is a Cisco IOS router running version 15.4, Leaf2 and Leaf3 is each a +VyOS router running 1.2. + +This topology was built using GNS3. + +Topology: + +.. code-block:: none + + Spine1: + fa0/2 towards Leaf2, IP-address: 10.1.2.1/24 + fa0/3 towards Leaf3, IP-address: 10.1.3.1/24 + + Leaf2: + Eth0 towards Spine1, IP-address: 10.1.2.2/24 + Eth1 towards a vlan-aware switch + + Leaf3: + Eth0 towards Spine1, IP-address 10.1.3.3/24 + Eth1 towards a vlan-aware switch + +**Spine1 Configuration:** + +.. code-block:: none + + conf t + ip multicast-routing + ! + interface fastethernet0/2 + ip address 10.1.2.1 255.255.255.0 + ip pim sparse-dense-mode + ! + interface fastethernet0/3 + ip address 10.1.3.1 255.255.255.0 + ip pim sparse-dense-mode + ! + router ospf 1 + network 10.0.0.0 0.255.255.255 area 0 + +Multicast-routing is required for the leafs to forward traffic between each +other in a more scalable way. This also requires PIM to be enabled towards the +Leafs so that the Spine can learn what multicast groups each Leaf expect +traffic from. + +**Leaf2 configuration:** + +.. code-block:: none + + set interfaces ethernet eth0 address '10.1.2.2/24' + set protocols ospf area 0 network '10.0.0.0/8' + + ! Our first vxlan interface + set interfaces bridge br241 address '172.16.241.1/24' + set interfaces bridge br241 member interface 'eth1.241' + set interfaces bridge br241 member interface 'vxlan241' + + set interfaces vxlan vxlan241 group '239.0.0.241' + set interfaces vxlan vxlan241 source-interface 'eth0' + set interfaces vxlan vxlan241 vni '241' + + ! Our seconds vxlan interface + set interfaces bridge br242 address '172.16.242.1/24' + set interfaces bridge br242 member interface 'eth1.242' + set interfaces bridge br242 member interface 'vxlan242' + + set interfaces vxlan vxlan242 group '239.0.0.242' + set interfaces vxlan vxlan242 source-interface 'eth0' + set interfaces vxlan vxlan242 vni '242' + +**Leaf3 configuration:** + +.. code-block:: none + + set interfaces ethernet eth0 address '10.1.3.3/24' + set protocols ospf area 0 network '10.0.0.0/8' + + ! Our first vxlan interface + set interfaces bridge br241 address '172.16.241.1/24' + set interfaces bridge br241 member interface 'eth1.241' + set interfaces bridge br241 member interface 'vxlan241' + + set interfaces vxlan vxlan241 group '239.0.0.241' + set interfaces vxlan vxlan241 source-interface 'eth0' + set interfaces vxlan vxlan241 vni '241' + + ! Our seconds vxlan interface + set interfaces bridge br242 address '172.16.242.1/24' + set interfaces bridge br242 member interface 'eth1.242' + set interfaces bridge br242 member interface 'vxlan242' + + set interfaces vxlan vxlan242 group '239.0.0.242' + set interfaces vxlan vxlan242 source-interface 'eth0' + set interfaces vxlan vxlan242 vni '242' + +As you can see, Leaf2 and Leaf3 configuration is almost identical. There are +lots of commands above, I'll try to into more detail below, command +descriptions are placed under the command boxes: + +.. code-block:: none + + set interfaces bridge br241 address '172.16.241.1/24' + +This commands creates a bridge that is used to bind traffic on eth1 vlan 241 +with the vxlan241-interface. The IP-address is not required. It may however be +used as a default gateway for each Leaf which allows devices on the vlan to +reach other subnets. This requires that the subnets are redistributed by OSPF +so that the Spine will learn how to reach it. To do this you need to change the +OSPF network from '10.0.0.0/8' to '0.0.0.0/0' to allow 172.16/12-networks to be +advertised. + +.. code-block:: none + + set interfaces bridge br241 member interface 'eth1.241' + set interfaces bridge br241 member interface 'vxlan241' + +Binds eth1.241 and vxlan241 to each other by making them both member +interfaces of the same bridge. + +.. code-block:: none + + set interfaces vxlan vxlan241 group '239.0.0.241' + +The multicast-group used by all Leafs for this vlan extension. Has to be the +same on all Leafs that has this interface. + +.. code-block:: none + + set interfaces vxlan vxlan241 source-interface 'eth0' + +Sets the interface to listen for multicast packets on. Could be a loopback, not +yet tested. + +.. code-block:: none + + set interfaces vxlan vxlan241 vni '241' + +Sets the unique id for this vxlan-interface. Not sure how it correlates with +multicast-address. + +.. code-block:: none + + set interfaces vxlan vxlan241 port 12345 + +The destination port used for creating a VXLAN interface in Linux defaults to +its pre-standard value of 8472 to preserve backwards compatibility. A +configuration directive to support a user-specified destination port to override +that behavior is available using the above command. + +Unicast VXLAN +============= + +Alternative to multicast, the remote IPv4 address of the VXLAN tunnel can be +set directly. Let's change the Multicast example from above: + +.. code-block:: none + + # leaf2 and leaf3 + delete interfaces vxlan vxlan241 group '239.0.0.241' + delete interfaces vxlan vxlan241 source-interface 'eth0' + + # leaf2 + set interface vxlan vxlan241 remote 10.1.3.3 + + # leaf3 + set interface vxlan vxlan241 remote 10.1.2.2 + +The default port udp is set to 8472. +It can be changed with ``set interface vxlan <vxlanN> port <port>`` diff --git a/docs/configuration/interfaces/wireguard.rst b/docs/configuration/interfaces/wireguard.rst new file mode 100644 index 00000000..852ff520 --- /dev/null +++ b/docs/configuration/interfaces/wireguard.rst @@ -0,0 +1,269 @@ +.. _wireguard: + +######### +WireGuard +######### + +WireGuard is an extremely simple yet fast and modern VPN that utilizes +state-of-the-art cryptography. See https://www.wireguard.com for more +information. + +Configuration +============= + +WireGuard requires the generation of a keypair, a private key which will +decrypt incoming traffic and a public key, which the peer(s) will use to +encrypt traffic. + +Generate keypair +---------------- + +.. opcmd:: generate wireguard default-keypair + + It generates the keypair, that is its public and private part and stores + it within VyOS. It will be used per default on any configured WireGuard + interface, even if multiple interfaces are being configured. + +.. opcmd:: show wireguard keypairs pubkey default + + It shows the public key which needs to be shared with your peer(s). Your + peer will encrypt all traffic to your system using this public key. + + .. code-block:: none + + vyos@vyos:~$ show wireguard keypairs pubkey default + hW17UxY7zeydJNPIyo3UtGnBHkzTK/NeBOrDSIU9Tx0= + + +Generate named keypair +---------------------- + +Named keypairs can be used on a interface basis, if configured. If +multiple WireGuard interfaces are being configured, each can have their +own keypairs. + +The commands below will generate 2 keypairs, which are not related to +each other. + +.. code-block:: none + + vyos@vyos:~$ generate wireguard named-keypairs KP01 + vyos@vyos:~$ generate wireguard named-keypairs KP02 + + +Interface configuration +----------------------- + +The next step is to configure your local side as well as the policy +based trusted destination addresses. If you only initiate a connection, +the listen port and address/port is optional, if you however act as a server +and endpoints initiate the connections to your system, you need to +define a port your clients can connect to, otherwise it's randomly +chosen and may make it difficult with firewall rules, since the port may +be a different one when you reboot your system. + +You will also need the public key of your peer as well as the network(s) +you want to tunnel (allowed-ips) to configure a WireGuard tunnel. The +public key below is always the public key from your peer, not your local +one. + +**local side** + +.. code-block:: none + + set interfaces wireguard wg01 address '10.1.0.1/24' + set interfaces wireguard wg01 description 'VPN-to-wg02' + set interfaces wireguard wg01 peer to-wg02 allowed-ips '10.2.0.0/24' + set interfaces wireguard wg01 peer to-wg02 address '192.168.0.142' + set interfaces wireguard wg01 peer to-wg02 port '12345' + set interfaces wireguard wg01 peer to-wg02 pubkey 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=' + set interfaces wireguard wg01 port '12345' + set protocols static route 10.2.0.0/24 interface wg01 + +The last step is to define an interface route for 10.2.0.0/24 to get +through the WireGuard interface `wg01`. Multiple IPs or networks can be +defined and routed, the last check is allowed-ips which either prevents +or allows the traffic. + +.. note:: You can not assign the same allowed-ips statement to multiple + WireGuard peers. This a a design decission. For more information please + check the `WireGuard mailing list`_. + + +To use a named key on an interface, the option private-key needs to be +set. + +.. code-block:: none + + set interfaces wireguard wg01 private-key KP01 + set interfaces wireguard wg02 private-key KP02 + +The command ``run show wireguard keypairs pubkey KP01`` will then show +the public key, which needs to be shared with the peer. + + +**remote side** + +.. code-block:: none + + set interfaces wireguard wg01 address '10.2.0.1/24' + set interfaces wireguard wg01 description 'VPN-to-wg01' + set interfaces wireguard wg01 peer to-wg02 allowed-ips '10.1.0.0/24' + set interfaces wireguard wg01 peer to-wg02 address '192.168.0.124' + set interfaces wireguard wg01 peer to-wg02 port '12345' + set interfaces wireguard wg01 peer to-wg02 pubkey 'u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk=' + set interfaces wireguard wg01 port '12345' + set protocols static route 10.1.0.0/24 interface wg01 + +Assure that your firewall rules allow the traffic, in which case you +have a working VPN using WireGuard + +.. code-block:: none + + wg01# ping 10.2.0.1 + PING 10.2.0.1 (10.2.0.1) 56(84) bytes of data. + 64 bytes from 10.2.0.1: icmp_seq=1 ttl=64 time=1.16 ms + 64 bytes from 10.2.0.1: icmp_seq=2 ttl=64 time=1.77 ms + + wg02# ping 10.1.0.1 + PING 10.1.0.1 (10.1.0.1) 56(84) bytes of data. + 64 bytes from 10.1.0.1: icmp_seq=1 ttl=64 time=4.40 ms + 64 bytes from 10.1.0.1: icmp_seq=2 ttl=64 time=1.02 ms + +An additional layer of symmetric-key crypto can be used on top of the +asymmetric crypto, which is optional. + +.. code-block:: none + + wg01# run generate wireguard preshared-key + rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc= + +Copy the key, as it is not stored on the local file system. Make sure +you distribute that key in a safe manner, it's a symmetric key, so only +you and your peer should have knowledge of its content. + +.. code-block:: none + + wg01# set interfaces wireguard wg01 peer to-wg02 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' + wg02# set interfaces wireguard wg01 peer to-wg01 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' + +Road Warrior Example +-------------------- + +With WireGuard, a Road Warrior VPN config is similar to a site-to-site +VPN. It just lacks the ``address`` and ``port`` statements. + +In the following example, the IPs for the remote clients are defined in +the peers. This would allow the peers to interact with one another. + +.. code-block:: none + + wireguard wg0 { + address 10.172.24.1/24 + address 2001:DB8:470:22::1/64 + description RoadWarrior + peer MacBook { + allowed-ips 10.172.24.30/32 + allowed-ips 2001:DB8:470:22::30/128 + persistent-keepalive 15 + pubkey F5MbW7ye7DsoxdOaixjdrudshjjxN5UdNV+pGFHqehc= + } + peer iPhone { + allowed-ips 10.172.24.20/32 + allowed-ips 2001:DB8:470:22::30/128 + persistent-keepalive 15 + pubkey BknHcLFo8nOo8Dwq2CjaC/TedchKQ0ebxC7GYn7Al00= + } + port 2224 + } + +The following is the config for the iPhone peer above. It's important to +note that the ``AllowedIPs`` setting directs all IPv4 and IPv6 traffic +through the connection. + +.. code-block:: none + + [Interface] + PrivateKey = ARAKLSDJsadlkfjasdfiowqeruriowqeuasdf= + Address = 10.172.24.20/24, 2001:DB8:470:22::20/64 + DNS = 10.0.0.53, 10.0.0.54 + + [Peer] + PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= + AllowedIPs = 0.0.0.0/0, ::/0 + Endpoint = 192.0.2.1:2224 + PersistentKeepalive = 25 + + +This MacBook peer is doing split-tunneling, where only the subnets local +to the server go over the connection. + +.. code-block:: none + + [Interface] + PrivateKey = 8Iasdfweirousd1EVGUk5XsT+wYFZ9mhPnQhmjzaJE6Go= + Address = 10.172.24.30/24, 2001:DB8:470:22::30/64 + + [Peer] + PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= + AllowedIPs = 10.172.24.30/24, 2001:DB8:470:22::/64 + Endpoint = 192.0.2.1:2224 + PersistentKeepalive = 25 + + +Operational commands +==================== + +**Show interface status** + +.. code-block:: none + + vyos@wg01# run show interfaces wireguard wg01 + interface: wg1 + description: VPN-to-wg01 + address: 10.2.0.1/24 + public key: RIbtUTCfgzNjnLNPQ/asldkfjhaERDFl2H/xUfbyjc= + private key: (hidden) + listening port: 53665 + peer: to-wg02 + public key: u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk= + latest handshake: 0:01:20 + status: active + endpoint: 192.168.0.124:12345 + allowed ips: 10.2.0.0/24 + transfer: 42 GB received, 487 MB sent + persistent keepalive: every 15 seconds + RX: + bytes packets errors dropped overrun mcast + 45252407916 31192260 0 244493 0 0 + TX: + bytes packets errors dropped carrier collisions + 511649780 5129601 24465 0 0 0 + +**Show public key of the default key** + +.. code-block:: none + + vyos@wg01# run show wireguard keypair pubkey default + FAXCPb6EbTlSH5200J5zTopt9AYXneBthAySPBLbZwM= + +**Show public key of a named key** + +.. code-block:: none + + vyos@wg01# run show wireguard keypair pubkey KP01 + HUtsu198toEnm1poGoRTyqkUKfKUdyh54f45dtcahDM= + + +**Delete wireguard keypairs** + +.. code-block:: none + + vyos@wg01# wireguard keypair default + + +.. stop_vyoslinter + +.. _`WireGuard mailing list`: https://lists.zx2c4.com/pipermail/wireguard/2018-December/003704.html + +.. start_vyoslinter
\ No newline at end of file diff --git a/docs/configuration/interfaces/wireless.rst b/docs/configuration/interfaces/wireless.rst new file mode 100644 index 00000000..097d7c49 --- /dev/null +++ b/docs/configuration/interfaces/wireless.rst @@ -0,0 +1,590 @@ +.. _wireless-interface: + +################### +Wireless LAN (WiFi) +################### + +:abbr:`WLAN (Wireless LAN)` interface provide 802.11 (a/b/g/n/ac) wireless +support (commonly referred to as Wi-Fi) by means of compatible hardware. If your +hardware supports it, VyOS supports multiple logical wireless interfaces per +physical device. + +There are three modes of operation for a wireless interface: + +* :abbr:`WAP (Wireless Access-Point)` provides network access to connecting + stations if the physical hardware supports acting as a WAP + +* A station acts as a Wi-Fi client accessing the network through an available + WAP + +* Monitor, the system passively monitors any kind of wireless traffic + +If the system detects an unconfigured wireless device, it will be automatically +added the configuration tree, specifying any detected settings (for example, +its MAC address) and configured to run in monitor mode. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: wireless + :var1: wlan0 + +Wireless options +================ + +.. cfgcmd:: set interfaces wireless <interface> channel <number> + + Channel number (IEEE 802.11), for 2.4Ghz (802.11 b/g/n) channels range from + 1-14. On 5Ghz (802.11 a/h/j/n/ac) channels available are 0, 34 to 173 + +.. cfgcmd:: set interfaces wireless <interface> country-code <cc> + + Country code (ISO/IEC 3166-1). Used to set regulatory domain. Set as needed + to indicate country in which device is operating. This can limit available + channels and transmit power. + + .. note:: This option is mandatory in Access-Point mode. + +.. cfgcmd:: set interfaces wireless <interface> disable-broadcast-ssid + + Send empty SSID in beacons and ignore probe request frames that do not specify + full SSID, i.e., require stations to know SSID. + +.. cfgcmd:: set interfaces wireless <interface> expunge-failing-stations + + Disassociate stations based on excessive transmission failures or other + indications of connection loss. + + This depends on the driver capabilities and may not be available with all + drivers. + +.. cfgcmd:: set interfaces wireless <interface> isolate-stations + + Client isolation can be used to prevent low-level bridging of frames between + associated stations in the BSS. + + By default, this bridging is allowed. + +.. cfgcmd:: set interfaces wireless <interface> max-stations + + Maximum number of stations allowed in station table. New stations will be + rejected after the station table is full. IEEE 802.11 has a limit of 2007 + different association IDs, so this number should not be larger than that. + + This defaults to 2007. + +.. cfgcmd:: set interfaces wireless <interface> mgmt-frame-protection + + Management Frame Protection (MFP) according to IEEE 802.11w + +.. cfgcmd:: set interfaces wireless <interface> mode <a | b | g | n | ac> + + Operation mode of wireless radio. + + * ``a`` - 802.11a - 54 Mbits/sec + * ``b`` - 802.11b - 11 Mbits/sec + * ``g`` - 802.11g - 54 Mbits/sec (default) + * ``n`` - 802.11n - 600 Mbits/sec + * ``ac`` - 802.11ac - 1300 Mbits/sec + +.. cfgcmd:: set interfaces wireless <interface> physical-device <device> + + Wireless hardware device used as underlay radio. + + This defaults to phy0. + +.. cfgcmd:: set interfaces wireless <interface> reduce-transmit-power <number> + + Add Power Constraint element to Beacon and Probe Response frames. + + This option adds Power Constraint element when applicable and Country element + is added. Power Constraint element is required by Transmit Power Control. + + Valid values are 0..255. + +.. cfgcmd:: set interfaces wireless <interface> ssid <ssid> + + SSID to be used in IEEE 802.11 management frames + +.. cfgcmd:: set interfaces wireless <interface> type + <access-point | station | monitor> + + Wireless device type for this interface + + * ``access-point`` - Access-point forwards packets between other nodes + * ``station`` - Connects to another access point + * ``monitor`` - Passively monitor all packets on the frequency/channel + +PPDU +---- + +.. cfgcmd:: set interfaces wireless <interface> capabilities require-ht + +.. cfgcmd:: set interfaces wireless <interface> capabilities require-hvt + +HT (High Throughput) capabilities (802.11n) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht 40mhz-incapable + + Device is incapable of 40 MHz, do not advertise. This sets ``[40-INTOLERANT]`` + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht auto-powersave + + WMM-PS Unscheduled Automatic Power Save Delivery [U-APSD] + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht + channel-set-width <ht20 | ht40+ | ht40-> + + Supported channel width set. + + * ``ht40-`` - Both 20 MHz and 40 MHz with secondary channel below the primary + channel + * ``ht40+`` - Both 20 MHz and 40 MHz with secondary channel above the primary + channel + + .. note:: There are limits on which channels can be used with HT40- and HT40+. + Following table shows the channels that may be available for HT40- and HT40+ + use per IEEE 802.11n Annex J: + + Depending on the location, not all of these channels may be available for + use! + + .. code-block:: none + + freq HT40- HT40+ + 2.4 GHz 5-13 1-7 (1-9 in Europe/Japan) + 5 GHz 40,48,56,64 36,44,52,60 + + .. note:: 40 MHz channels may switch their primary and secondary channels if + needed or creation of 40 MHz channel maybe rejected based on overlapping + BSSes. These changes are done automatically when hostapd is setting up the + 40 MHz channel. + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht + delayed-block-ack + + Enable HT-delayed Block Ack ``[DELAYED-BA]`` + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht dsss-cck-40 + + DSSS/CCK Mode in 40 MHz, this sets ``[DSSS_CCK-40]`` + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht greenfield + + This enables the greenfield option which sets the ``[GF]`` option + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht ldpc + + Enable LDPC coding capability + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht lsig-protection + + Enable L-SIG TXOP protection capability + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht max-amsdu + <3839 | 7935> + + Maximum A-MSDU length 3839 (default) or 7935 octets + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht + short-gi <20 | 40> + + Short GI capabilities for 20 and 40 MHz + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht + smps <static | dynamic> + + Spatial Multiplexing Power Save (SMPS) settings + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc rx <num> + + Enable receiving PPDU using STBC (Space Time Block Coding) + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc tx + + Enable sending PPDU using STBC (Space Time Block Coding) + +VHT (Very High Throughput) capabilities (802.11ac) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht antenna-count + + Number of antennas on this card + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + antenna-pattern-fixed + + Set if antenna pattern does not change during the lifetime of an association + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht beamform + <single-user-beamformer | single-user-beamformee | multi-user-beamformer | + multi-user-beamformee> + + Beamforming capabilities: + + * ``single-user-beamformer`` - Support for operation as single user beamformer + * ``single-user-beamformee`` - Support for operation as single user beamformee + * ``multi-user-beamformer`` - Support for operation as single user beamformer + * ``multi-user-beamformee`` - Support for operation as single user beamformer + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + center-channel-freq <freq-1 | freq-2> <number> + + VHT operating channel center frequency - center freq 1 + (for use with 80, 80+80 and 160 modes) + + VHT operating channel center frequency - center freq 2 + (for use with the 80+80 mode) + + <number> must be from 34 - 173. For 80 MHz channels it should be channel + 6. + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + channel-set-width <0 | 1 | 2 | 3> + + * ``0`` - 20 or 40 MHz channel width (default) + * ``1`` - 80 MHz channel width + * ``2`` - 160 MHz channel width + * ``3`` - 80+80 MHz channel width + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht ldpc + + Enable LDPC (Low Density Parity Check) coding capability + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht link-adaptation + + VHT link adaptation capabilities + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + max-mpdu <value> + + Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets) + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + max-mpdu-exp <value> + + Set the maximum length of A-MPDU pre-EOF padding that the station can receive + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + short-gi <80 | 160> + + Short GI capabilities + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc rx <num> + + Enable receiving PPDU using STBC (Space Time Block Coding) + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc tx + + Enable sending PPDU using STBC (Space Time Block Coding) + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht tx-powersave + + Enable VHT TXOP Power Save Mode + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht vht-cf + + Station supports receiving VHT variant HT Control field + +Wireless options (Station/Client) +================================= + +The example creates a wireless station (commonly referred to as Wi-Fi client) +that accesses the network through the WAP defined in the above example. The +default physical device (``phy0``) is used. + +.. code-block:: none + + set interfaces wireless wlan0 type station + set interfaces wireless wlan0 address dhcp + set interfaces wireless wlan0 ssid Test + set interfaces wireless wlan0 security wpa + +Resulting in + +.. code-block:: none + + interfaces { + [...] + wireless wlan0 { + address dhcp + security { + wpa { + passphrase "12345678" + } + } + ssid TEST + type station + } + +Security +======== + +:abbr:`WPA (Wi-Fi Protected Access)` and WPA2 Enterprise in combination with +802.1x based authentication can be used to authenticate users or computers +in a domain. + +The wireless client (supplicant) authenticates against the RADIUS server +(authentication server) using an :abbr:`EAP (Extensible Authentication +Protocol)` method configured on the RADIUS server. The WAP (also referred +to as authenticator) role is to send all authentication messages between the +supplicant and the configured authentication server, thus the RADIUS server +is responsible for authenticating the users. + +The WAP in this example has the following characteristics: + +* IP address ``192.168.2.1/24`` +* Network ID (SSID) ``Enterprise-TEST`` +* WPA passphrase ``12345678`` +* Use 802.11n protocol +* Wireless channel ``1`` +* RADIUS server at ``192.168.3.10`` with shared-secret ``VyOSPassword`` + +.. code-block:: none + + set interfaces wireless wlan0 address '192.168.2.1/24' + set interfaces wireless wlan0 type access-point + set interfaces wireless wlan0 channel 1 + set interfaces wireless wlan0 mode n + set interfaces wireless wlan0 ssid 'TEST' + set interfaces wireless wlan0 security wpa mode wpa2 + set interfaces wireless wlan0 security wpa cipher CCMP + set interfaces wireless wlan0 security wpa radius server 192.168.3.10 key 'VyOSPassword' + set interfaces wireless wlan0 security wpa radius server 192.168.3.10 port 1812 + +Resulting in + +.. code-block:: none + + interfaces { + [...] + wireless wlan0 { + address 192.168.2.1/24 + channel 1 + mode n + security { + wpa { + cipher CCMP + mode wpa2 + radius { + server 192.168.3.10 { + key 'VyOSPassword' + port 1812 + } + } + } + } + ssid "Enterprise-TEST" + type access-point + } + } + system { + [...] + wifi-regulatory-domain DE + } + + +VLAN +==== + +Regular VLANs (802.1q) +---------------------- + +.. cmdinclude:: /_include/interface-vlan-8021q.txt + :var0: wireless + :var1: wlan0 + +QinQ (802.1ad) +-------------- + +.. cmdinclude:: /_include/interface-vlan-8021ad.txt + :var0: wireless + :var1: wlan0 + +********* +Operation +********* + +.. opcmd:: show interfaces wireless info + +Use this command to view operational status and wireless-specific information +about all wireless interfaces. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless info + Interface Type SSID Channel + wlan0 access-point VyOS-TEST-0 1 + +.. opcmd:: show interfaces wireless detail + +Use this command to view operational status and detailes wireless-specific +information about all wireless interfaces. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless detail + wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.99.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 66072 282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 83413 430 0 0 0 0 + + wlan1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.100.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:ffff:2ed3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 166072 5282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 183413 5430 0 0 0 0 + +.. opcmd:: show interfaces wireless <wlanX> + +This command shows both status and statistics on the specified wireless +interface. The wireless interface identifier can range from wlan0 to wlan999. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless wlan0 + wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.99.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 66072 282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 83413 430 0 0 0 0 + + +.. opcmd:: show interfaces wireless <wlanX> brief + +This command gives a brief status overview of a specified wireless interface. +The wireless interface identifier can range from wlan0 to wlan999. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless wlan0 brief + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + wlan0 192.168.2.254/24 u/u + + +.. opcmd:: show interfaces wireless <wlanX> queue + +Use this command to view wireless interface queue information. +The wireless interface identifier can range from wlan0 to wlan999. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless wlan0 queue + qdisc pfifo_fast 0: root bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 + Sent 810323 bytes 6016 pkt (dropped 0, overlimits 0 requeues 0) + rate 0bit 0pps backlog 0b 0p requeues 0 + + +.. opcmd:: show interfaces wireless <wlanX> scan + +This command is used to retrieve information about WAP within the range of your +wireless interface. This command is useful on wireless interfaces configured +in station mode. + +.. note:: Scanning is not supported on all wireless drivers and wireless + hardware. Refer to your driver and wireless hardware documentation for + further details. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless wlan0 scan + Address SSID Channel Signal (dbm) + 00:53:3b:88:6e:d8 WLAN-576405 1 -64.00 + 00:53:3b:88:6e:da Telekom_FON 1 -64.00 + 00:53:00:f2:c2:a4 BabyView_F2C2A4 6 -60.00 + 00:53:3b:88:6e:d6 Telekom_FON 100 -72.00 + 00:53:3b:88:6e:d4 WLAN-576405 100 -71.00 + 00:53:44:a4:96:ec KabelBox-4DC8 56 -81.00 + 00:53:d9:7a:67:c2 WLAN-741980 1 -75.00 + 00:53:7c:99:ce:76 Vodafone Homespot 1 -86.00 + 00:53:44:a4:97:21 KabelBox-4DC8 1 -78.00 + 00:53:44:a4:97:21 Vodafone Hotspot 1 -79.00 + 00:53:44:a4:97:21 Vodafone Homespot 1 -79.00 + 00:53:86:40:30:da Telekom_FON 1 -86.00 + 00:53:7c:99:ce:76 Vodafone Hotspot 1 -86.00 + 00:53:44:46:d2:0b Vodafone Hotspot 1 -87.00 + + +******** +Examples +******** + +The following example creates a WAP. When configuring multiple WAP interfaces, +you must specify unique IP addresses, channels, Network IDs commonly referred +to as :abbr:`SSID (Service Set Identifier)`, and MAC addresses. + +The WAP in this example has the following characteristics: + +* IP address ``192.168.2.1/24`` +* Network ID (SSID) ``TEST`` +* WPA passphrase ``12345678`` +* Use 802.11n protocol +* Wireless channel ``1`` + +.. code-block:: none + + set interfaces wireless wlan0 address '192.168.2.1/24' + set interfaces wireless wlan0 type access-point + set interfaces wireless wlan0 channel 1 + set interfaces wireless wlan0 mode n + set interfaces wireless wlan0 ssid 'TEST' + set interfaces wireless wlan0 security wpa mode wpa2 + set interfaces wireless wlan0 security wpa cipher CCMP + set interfaces wireless wlan0 security wpa passphrase '12345678' + +Resulting in + +.. code-block:: none + + interfaces { + [...] + wireless wlan0 { + address 192.168.2.1/24 + channel 1 + mode n + security { + wpa { + cipher CCMP + mode wpa2 + passphrase "12345678" + } + } + ssid "TEST" + type access-point + } + } + system { + [...] + wifi-regulatory-domain DE + } + +To get it to work as a access point with this configuration you will need +to set up a DHCP server to work with that network. You can - of course - also +bridge the Wireless interface with any configured bridge +(:ref:`bridge-interface`) on the system. diff --git a/docs/configuration/interfaces/wirelessmodem.rst b/docs/configuration/interfaces/wirelessmodem.rst new file mode 100644 index 00000000..a65a47f4 --- /dev/null +++ b/docs/configuration/interfaces/wirelessmodem.rst @@ -0,0 +1,128 @@ +.. _wwan-interface: + +#################### +WirelessModem (WWAN) +#################### + +The wirelessmodem interface provides access (through a wireless modem/wwan) +to wireless networks provided by various cellular providers. VyOS uses the +interfaces wirelessmodem subsystem for configuration. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-description.txt + :var0: wirelessmodem + :var1: wlm0 + +.. cmdinclude:: /_include/interface-disable.txt + :var0: wirelessmodem + :var1: wlm0 + +.. cmdinclude:: /_include/interface-vrf.txt + :var0: wirelessmodem + :var1: wlm0 + +WirelessModem (WWAN) options +============================ + +.. cfgcmd:: set interfaces wirelessmodem <interface> apn <apn> + + Every WWAN connection requires an :abbr:`APN (Access Point Name)` which is + used by the client to dial into the ISPs network. This is a mandatory + parameter. Contact your Service Provider for correct APN. + +.. cfgcmd:: set interfaces wirelessmodem <interface> backup distance <metric> + + Configure metric of the default route added via the Wireless Modem interface. + The default metric if not specified is 10. + +.. cfgcmd:: set interfaces wirelessmodem <interface> device <tty> + + Device identifier of the underlaying physical interface. This is usually a + ttyUSB device, if not configured this defaults to ttyUSB2. + +.. cfgcmd:: set interfaces wirelessmodem <interface> no-peer-dns + + Do not install DNS nameservers received from ISP into system wide nameserver + list. + +.. cfgcmd:: set interfaces wirelessmodem <interface> connect-on-demand + + When set the interface is enabled for "dial-on-demand". + + Use this command to instruct the system to establish a PPP connection + automatically once traffic passes through the interface. A disabled on-demand + connection is established at boot time and remains up. If the link fails for + any reason, the link is brought back up immediately. + +********* +Operation +********* + +.. opcmd:: show interfaces wirelessmodem <interface> + + Retrive interface information from given WWAN interface. + + .. code-block:: none + + vyos@vyos:~$ show interfaces wirelessmodem wlm0 + wlm0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master black state UNKNOWN group default qlen 3 + link/ppp + inet 10.26.238.93 peer 10.64.64.64/32 scope global wlm0 + valid_lft forever preferred_lft forever + Description: baaar + + RX: bytes packets errors dropped overrun mcast + 38 5 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 217 8 0 0 0 0 + +.. opcmd:: show interfaces wirelessmodem <interface> statistics + + Retrive interface statistics from given WWAN interface. + + .. code-block:: none + + vyos@vyos:~$ show interfaces wirelessmodem wlm0 statistics + IN PACK VJCOMP VJUNC VJERR | OUT PACK VJCOMP VJUNC NON-VJ + 38 5 0 0 0 | 217 8 0 0 8 + +.. opcmd:: show interfaces wirelessmodem <interface> log + + Displays log information for a WWAN interface. + + +******* +Example +******* + +The following example is based on a Sierra Wireless MC7710 miniPCIe card (only +the form factor in reality it runs UBS) and Deutsche Telekom as ISP. The card +is assembled into a :ref:`pc-engines-apu4`. + +.. code-block:: none + + set interfaces wirelessmodem wlm0 apn 'internet.telekom' + set interfaces wirelessmodem wlm0 backup distance '100' + set interfaces wirelessmodem wlm0 device 'ttyUSB2' + set interfaces wirelessmodem wlm0 disable + set interfaces wirelessmodem wlm0 no-peer-dns + +***************** +Supported Modules +***************** + +The following hardware modules have been tested successfully in an +:ref:`pc-engines-apu4` board: + +* Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) +* Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) +* Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) +* Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) +* Huawei ME909u-521 miniPCIe card (LTE) +* Huawei ME909s-120 miniPCIe card (LTE) diff --git a/docs/configuration/loadbalancing/index.rst b/docs/configuration/loadbalancing/index.rst new file mode 100644 index 00000000..7d675c1b --- /dev/null +++ b/docs/configuration/loadbalancing/index.rst @@ -0,0 +1,307 @@ +.. _load-balancing: + +WAN load balancing +================== + +Outbound traffic can be balanced between two or more outbound interfaces. +If a path fails, traffic is balanced across the remaining healthy paths, +a recovered path is automatically added back to the routing table and used by +the load balancer. The load balancer automatically adds routes for each path to +the routing table and balances traffic across the configured interfaces, +determined by interface health and weight. + + +In a minimal, configuration the following must be provided: + + * a interface with a nexthop + * one rule with a LAN (inbound-interface) and the WAN (interface). + +Let's assume we have two DHCP WAN interfaces and one LAN (eth2): + +.. code-block:: none + + set load-balancing wan interface-health eth0 nexthop 'dhcp' + set load-balancing wan interface-health eth1 nexthop 'dhcp' + set load-balancing wan rule 1 inbound-interface 'eth2' + set load-balancing wan rule 1 interface eth0 + set load-balancing wan rule 1 interface eth1 + +Balancing Rules +--------------- + +Interfaces, their weight and the type of traffic to be balanced are defined in +numbered balancing rule sets. The rule sets are executed in numerical order +against outgoing packets. In case of a match the packet is sent through an +interface specified in the matching rule. If a packet doesn't match any rule +it is sent by using the system routing table. Rule numbers can't be changed. + +Create a load balancing rule, rule can be a number between 1 and 9999: + +.. code-block:: none + + vyos@vyos# set load-balancing wan rule 1 + Possible completions: + description Description for this rule + > destination Destination + exclude Exclude packets matching this rule from wan load balance + failover Enable failover for packets matching this rule from wan load balance + inbound-interface Inbound interface name (e.g., "eth0") [REQUIRED] + +> interface Interface name [REQUIRED] + > limit Enable packet limit for this rule + per-packet-balancing Option to match traffic per-packet instead of the default, per-flow + protocol Protocol to match + > source Source information + +Interface weight +**************** + +Let's expand the example from above and add a weight to the interfaces. +The bandwidth from eth0 is larger than eth1. Per default outbound traffic is +distributed randomly across available interfaces. Weights can be assigned to +interfaces to influence the balancing. + +.. code-block:: none + + set load-balancing wan rule 1 interface eth0 weight 2 + set load-balancing wan rule 1 interface eth1 weight 1 + +66% traffic is routed to eth0 and eth1 get 33% of traffic. + +Rate limit +********** + +A packet rate limit can be set for a rule to apply the rule to traffic above or +below a specified threshold. To configure the rate limiting use: + +.. code-block:: none + + set load-balancing wan rule <rule> limit <parameter> + +* ``burst``: Number of packets allowed to overshoot the limit within ``period``. + Default 5. +* ``period``: Time window for rate calculation. Possible values: + ``second`` (one second), ``minute`` (one minute), ``hour`` (one hour). + Default is ``second``. +* ``rate``: Number of packets. Default 5. +* ``threshold``: ``below`` or ``above`` the specified rate limit. + +Flow and packet-based balancing +******************************* + +Outgoing traffic is balanced in a flow-based manner. +A connection tracking table is used to track flows by their source address, +destination address and port. Each flow is assigned to an interface according +to the defined balancing rules and subsequent packets are sent through the +same interface. This has the advantage that packets always arrive in order if +links with different speeds are in use. + +Packet-based balancing can lead to a better balance across interfaces when out +of order packets are no issue. Per-packet-based balancing can be set for a +balancing rule with: + +.. code-block:: none + + set load-balancing wan rule <rule> per-packet-balancing + +Exclude traffic +*************** + +To exclude traffic from load balancing, traffic matching an exclude rule is not +balanced but routed through the system routing table instead: + +.. code-block:: none + + set load-balancing wan rule <rule> exclude + + +Health checks +------------- + +The health of interfaces and paths assigned to the load balancer is +periodically checked by sending ICMP packets (ping) to remote destinations, +a TTL test or the execution of a user defined script. If an interface fails the +health check it is removed from the load balancer's pool of interfaces. +To enable health checking for an interface: + +.. code-block:: none + + vyos@vyos# set load-balancing wan interface-health <interface> + Possible completions: + failure-count Failure count + nexthop Outbound interface nexthop address. Can be 'dhcp or ip address' [REQUIRED] + success-count Success count + +> test Rule number + +Specify nexthop on the path to destination, ``ipv4-address`` can be set to +``dhcp`` + +.. code-block:: none + + set load-balancing wan interface-health <interface> nexthop <ipv4-address> + +Set the number of health check failures before an interface is marked as +unavailable, range for number is 1 to 10, default 1. Or set the number of +successful health checks before an interface is added back to the interface +pool, range for number is 1 to 10, default 1. + +.. code-block:: none + + set load-balancing wan interface-health <interface> failure-count <number> + set load-balancing wan interface-health <interface> success-count <number> + +Each health check is configured in its own test, tests are numbered and +processed in numeric order. For multi target health checking multiple tests +can be defined: + +.. code-block:: none + + vyos@vyos# set load-balancing wan interface-health eth1 test 0 + Possible completions: + resp-time Ping response time (seconds) + target Health target address + test-script Path to user defined script + ttl-limit Ttl limit (hop count) + type WLB test type + +* ``resp-time``: the maximum response time for ping in seconds. + Range 1...30, default 5 +* ``target``: the target to be sent ICMP packets to, address can be an IPv4 + address or hostname +* ``test-script``: A user defined script must return 0 to be considered + successful and non-zero to fail. Scripts are located in /config/scripts, + for different locations the full path needs to be provided +* ``ttl-limit``: For the UDP TTL limit test the hop count limit must be + specified. The limit must be shorter than the path length, an ICMP time + expired message is needed to be returned for a successful test. default 1 +* ``type``: Specify the type of test. type can be ping, ttl or a user defined + script + +Source NAT rules +---------------- + +Per default, interfaces used in a load balancing pool replace the source IP +of each outgoing packet with its own address to ensure that replies arrive on +the same interface. This works through automatically generated source NAT (SNAT) +rules, these rules are only applied to balanced traffic. In cases where this +behaviour is not desired, the automatic generation of SNAT rules can be +disabled: + +.. code-block:: none + + set load-balancing wan disable-source-nat + +Sticky Connections +------------------ +Inbound connections to a WAN interface can be improperly handled when the reply +is sent back to the client. + +.. image:: /_static/images/sticky-connections.jpg + :width: 80% + :align: center + + +Upon reception of an incoming packet, when a response is sent, it might be +desired to ensure that it leaves from the same interface as the inbound one. +This can be achieved by enabling sticky connections in the load balancing: + +.. code-block:: none + + set load-balancing wan sticky-connections inbound + +Failover +-------- + +In failover mode, one interface is set to be the primary interface and other +interfaces are secondary or spare. Instead of balancing traffic across all +healthy interfaces, only the primary interface is used and in case of failure, +a secondary interface selected from the pool of available interfaces takes over. +The primary interface is selected based on its weight and health, others become +secondary interfaces. Secondary interfaces to take over a failed primary +interface are chosen from the load balancer's interface pool, depending +on their weight and health. Interface roles can also be selected based on rule +order by including interfaces in balancing rules and ordering those rules +accordingly. To put the load balancer in failover mode, create a failover rule: + +.. code-block:: none + + set load-balancing wan rule <number> failover + +Because existing sessions do not automatically fail over to a new path, +the session table can be flushed on each connection state change: + +.. code-block:: none + + set load-balancing wan flush-connections + +.. warning:: + + Flushing the session table will cause other connections to fall back from + flow-based to packet-based balancing until each flow is reestablished. + +Script execution +---------------- + +A script can be run when an interface state change occurs. Scripts are run +from /config/scripts, for a different location specify the full path: + +.. code-block:: none + + set load-balancing wan hook script-name + +Two environment variables are available: + +* ``WLB_INTERFACE_NAME=[interfacename]``: Interface to be monitored +* ``WLB_INTERFACE_STATE=[ACTIVE|FAILED]``: Interface state + +.. warning:: + + Blocking call with no timeout. System will become unresponsive if script + does not return! + +Handling and monitoring +----------------------- + + +Show WAN load balancer information including test types and targets. +A character at the start of each line depicts the state of the test + +* ``+`` successful +* ``-`` failed +* a blank indicates that no test has been carried out + +.. code-block:: none + + vyos@vyos:~$ show wan-load-balance + Interface: eth0 + Status: failed + Last Status Change: Tue Jun 11 20:12:19 2019 + -Test: ping Target: + Last Interface Success: 55s + Last Interface Failure: 0s + # Interface Failure(s): 5 + + Interface: eth1 + Status: active + Last Status Change: Tue Jun 11 20:06:42 2019 + +Test: ping Target: + Last Interface Success: 0s + Last Interface Failure: 6m26s + # Interface Failure(s): 0 + +Show connection data of load balanced traffic: + +.. code-block:: none + + vyos@vyos:~$ show wan-load-balance connection + conntrack v1.4.2 (conntrack-tools): 3 flow entries have been shown. + Type State Src Dst Packets Bytes + tcp TIME_WAIT 10.1.1.13:38040 203.0.113.2:80 203.0.113.2 192.168.188.71 + udp 10.1.1.13:41891 198.51.100.3:53 198.51.100.3 192.168.188.71 + udp 10.1.1.13:55437 198.51.100.3:53 198.51.100.3 192.168.188.71 + +Restart +******* + +.. code-block:: none + + restart wan-load-balance diff --git a/docs/configuration/nat/index.rst b/docs/configuration/nat/index.rst new file mode 100644 index 00000000..90275226 --- /dev/null +++ b/docs/configuration/nat/index.rst @@ -0,0 +1,12 @@ +.. _nat: + +### +NAT +### + +.. toctree:: + :maxdepth: 1 + :includehidden: + + nat44 + nat66 diff --git a/docs/configuration/nat/nat44.rst b/docs/configuration/nat/nat44.rst new file mode 100644 index 00000000..59cee741 --- /dev/null +++ b/docs/configuration/nat/nat44.rst @@ -0,0 +1,733 @@ +.. _nat44: + +##### +NAT44 +##### + +:abbr:`NAT (Network Address Translation)` is a common method of +remapping one IP address space into another by modifying network address +information in the IP header of packets while they are in transit across +a traffic routing device. The technique was originally used as a +shortcut to avoid the need to readdress every host when a network was +moved. It has become a popular and essential tool in conserving global +address space in the face of IPv4 address exhaustion. One +Internet-routable IP address of a NAT gateway can be used for an entire +private network. + +IP masquerading is a technique that hides an entire IP address space, +usually consisting of private IP addresses, behind a single IP address +in another, usually public address space. The hidden addresses are +changed into a single (public) IP address as the source address of the +outgoing IP packets so they appear as originating not from the hidden +host but from the routing device itself. Because of the popularity of +this technique to conserve IPv4 address space, the term NAT has become +virtually synonymous with IP masquerading. + +As network address translation modifies the IP address information in +packets, NAT implementations may vary in their specific behavior in +various addressing cases and their effect on network traffic. The +specifics of NAT behavior are not commonly documented by vendors of +equipment containing NAT implementations. + +The computers on an internal network can use any of the addresses set +aside by the :abbr:`IANA (Internet Assigned Numbers Authority)` for +private addressing (see :rfc:`1918`). These reserved IP addresses are +not in use on the Internet, so an external machine will not directly +route to them. The following addresses are reserved for private use: + +* 10.0.0.0 to 10.255.255.255 (CIDR: 10.0.0.0/8) +* 172.16.0.0 to 172.31.255.255 (CIDR: 172.16.0.0/12) +* 192.168.0.0 to 192.168.255.255 (CIDR: 192.168.0.0/16) + + +If an ISP deploys a :abbr:`CGN (Carrier-grade NAT)`, and uses +:rfc:`1918` address space to number customer gateways, the risk of +address collision, and therefore routing failures, arises when the +customer network already uses an :rfc:`1918` address space. + +This prompted some ISPs to develop a policy within the :abbr:`ARIN +(American Registry for Internet Numbers)` to allocate new private +address space for CGNs, but ARIN deferred to the IETF before +implementing the policy indicating that the matter was not a typical +allocation issue but a reservation of addresses for technical purposes +(per :rfc:`2860`). + +IETF published :rfc:`6598`, detailing a shared address space for use in +ISP CGN deployments that can handle the same network prefixes occurring +both on inbound and outbound interfaces. ARIN returned address space to +the :abbr:`IANA (Internet Assigned Numbers Authority)` for this +allocation. + +The allocated address block is 100.64.0.0/10. + +Devices evaluating whether an IPv4 address is public must be updated to +recognize the new address space. Allocating more private IPv4 address +space for NAT devices might prolong the transition to IPv6. + +Overview +======== + +Different NAT Types +------------------- + +.. _source-nat: + +SNAT +^^^^ + +:abbr:`SNAT (Source Network Address Translation)` is the most common +form of :abbr:`NAT (Network Address Translation)` and is typically +referred to simply as NAT. To be more correct, what most people refer +to as :abbr:`NAT (Network Address Translation)` is actually the process +of :abbr:`PAT (Port Address Translation)`, or NAT overload. SNAT is +typically used by internal users/private hosts to access the Internet +- the source address is translated and thus kept private. + +.. _destination-nat: + +DNAT +^^^^ + +:abbr:`DNAT (Destination Network Address Translation)` changes the +destination address of packets passing through the router, while +:ref:`source-nat` changes the source address of packets. DNAT is +typically used when an external (public) host needs to initiate a +session with an internal (private) host. A customer needs to access a +private service behind the routers public IP. A connection is +established with the routers public IP address on a well known port and +thus all traffic for this port is rewritten to address the internal +(private) host. + +.. _bidirectional-nat: + +Bidirectional NAT +^^^^^^^^^^^^^^^^^ + +This is a common scenario where both :ref:`source-nat` and +:ref:`destination-nat` are configured at the same time. It's commonly +used then internal (private) hosts need to establish a connection with +external resources and external systems need to access internal +(private) resources. + +NAT, Routing, Firewall Interaction +---------------------------------- + +There is a very nice picture/explanation in the Vyatta documentation +which should be rewritten here. + +NAT Ruleset +----------- + +:abbr:`NAT (Network Address Translation)` is configured entirely on a +series of so called `rules`. Rules are numbered and evaluated by the +underlying OS in numerical order! The rule numbers can be changes by +utilizing the :cfgcmd:`rename` and :cfgcmd:`copy` commands. + +.. note:: Changes to the NAT system only affect newly established + connections. Already established connections are not affected. + +.. hint:: When designing your NAT ruleset leave some space between + consecutive rules for later extension. Your ruleset could start with + numbers 10, 20, 30. You thus can later extend the ruleset and place + new rules between existing ones. + +Rules will be created for both :ref:`source-nat` and +:ref:`destination-nat`. + +For :ref:`bidirectional-nat` a rule for both :ref:`source-nat` and +:ref:`destination-nat` needs to be created. + +.. _traffic-filters: + +Traffic Filters +--------------- + +Traffic Filters are used to control which packets will have the defined +NAT rules applied. Five different filters can be applied within a NAT +rule. + +* **outbound-interface** - applicable only to :ref:`source-nat`. It + configures the interface which is used for the outside traffic that + this translation rule applies to. + + Example: + + .. code-block:: none + + set nat source rule 20 outbound-interface eth0 + +* **inbound-interface** - applicable only to :ref:`destination-nat`. It + configures the interface which is used for the inside traffic the + translation rule applies to. + + Example: + + .. code-block:: none + + set nat destination rule 20 inbound-interface eth1 + +* **protocol** - specify which types of protocols this translation rule + applies to. Only packets matching the specified protocol are NATed. + By default this applies to `all` protocols. + + Example: + + * Set SNAT rule 20 to only NAT TCP and UDP packets + * Set DNAT rule 20 to only NAT UDP packets + + .. code-block:: none + + set nat source rule 20 protocol tcp_udp + set nat destination rule 20 protocol udp + +* **source** - specifies which packets the NAT translation rule applies + to based on the packets source IP address and/or source port. Only + matching packets are considered for NAT. + + Example: + + * Set SNAT rule 20 to only NAT packets arriving from the 192.0.2.0/24 + network + * Set SNAT rule 30 to only NAT packets arriving from the 203.0.113.0/24 + network with a source port of 80 and 443 + + .. code-block:: none + + set nat source rule 20 source address 192.0.2.0/24 + set nat source rule 30 source address 203.0.113.0/24 + set nat source rule 30 source port 80,443 + + +* **destination** - specify which packets the translation will be + applied to, only based on the destination address and/or port number + configured. + + .. note:: If no destination is specified the rule will match on any + destination address and port. + + Example: + + * Configure SNAT rule (40) to only NAT packets with a destination + address of 192.0.2.1. + + .. code-block:: none + + set nat source rule 40 destination address 192.0.2.1 + + +Address Conversion +------------------ + +Every NAT rule has a translation command defined. The address defined +for the translation is the address used when the address information in +a packet is replaced. + +Source Address +^^^^^^^^^^^^^^ + +For :ref:`source-nat` rules the packets source address will be replaced +with the address specified in the translation command. A port +translation can also be specified and is part of the translation +address. + +.. note:: The translation address must be set to one of the available + addresses on the configured `outbound-interface` or it must be set to + `masquerade` which will use the primary IP address of the + `outbound-interface` as its translation address. + +.. note:: When using NAT for a large number of host systems it + recommended that a minimum of 1 IP address is used to NAT every 256 + private host systems. This is due to the limit of 65,000 port numbers + available for unique translations and a reserving an average of + 200-300 sessions per host system. + +Example: + +* Define a discrete source IP address of 100.64.0.1 for SNAT rule 20 +* Use address `masquerade` (the interfaces primary address) on rule 30 +* For a large amount of private machines behind the NAT your address + pool might to be bigger. Use any address in the range 100.64.0.10 - + 100.64.0.20 on SNAT rule 40 when doing the translation + + +.. code-block:: none + + set nat source rule 20 translation address 100.64.0.1 + set nat source rule 30 translation address 'masquerade' + set nat source rule 40 translation address 100.64.0.10-100.64.0.20 + + +Destination Address +^^^^^^^^^^^^^^^^^^^ + +For :ref:`destination-nat` rules the packets destination address will be +replaced by the specified address in the `translation address` command. + +Example: + +* DNAT rule 10 replaces the destination address of an inbound packet + with 192.0.2.10 + +.. code-block:: none + + set nat destination rule 10 translation address 192.0.2.10 + + +Configuration Examples +====================== + +To setup SNAT, we need to know: + +* The internal IP addresses we want to translate +* The outgoing interface to perform the translation on +* The external IP address to translate to + +In the example used for the Quick Start configuration above, we +demonstrate the following configuration: + +.. code-block:: none + + set nat source rule 100 outbound-interface 'eth0' + set nat source rule 100 source address '192.168.0.0/24' + set nat source rule 100 translation address 'masquerade' + +Which generates the following configuration: + +.. code-block:: none + + rule 100 { + outbound-interface eth0 + source { + address 192.168.0.0/24 + } + translation { + address masquerade + } + } + +In this example, we use **masquerade** as the translation address +instead of an IP address. The **masquerade** target is effectively an +alias to say "use whatever IP address is on the outgoing interface", +rather than a statically configured IP address. This is useful if you +use DHCP for your outgoing interface and do not know what the external +address will be. + +When using NAT for a large number of host systems it recommended that a +minimum of 1 IP address is used to NAT every 256 host systems. This is +due to the limit of 65,000 port numbers available for unique +translations and a reserving an average of 200-300 sessions per host +system. + +Example: For an ~8,000 host network a source NAT pool of 32 IP addresses +is recommended. + +A pool of addresses can be defined by using a hyphen between two IP +addresses: + +.. code-block:: none + + set nat source rule 100 translation address '203.0.113.32-203.0.113.63' + +.. _avoidng_leaky_nat: + +Avoiding "leaky" NAT +-------------------- + +Linux netfilter will not NAT traffic marked as INVALID. This often +confuses people into thinking that Linux (or specifically VyOS) has a +broken NAT implementation because non-NATed traffic is seen leaving an +external interface. This is actually working as intended, and a packet +capture of the "leaky" traffic should reveal that the traffic is either +an additional TCP "RST", "FIN,ACK", or "RST,ACK" sent by client systems +after Linux netfilter considers the connection closed. The most common +is the additional TCP RST some host implementations send after +terminating a connection (which is implementation-specific). + +In other words, connection tracking has already observed the connection +be closed and has transition the flow to INVALID to prevent attacks from +attempting to reuse the connection. + +You can avoid the "leaky" behavior by using a firewall policy that drops +"invalid" state packets. + +Having control over the matching of INVALID state traffic, e.g. the +ability to selectively log, is an important troubleshooting tool for +observing broken protocol behavior. For this reason, VyOS does not +globally drop invalid state traffic, instead allowing the operator to +make the determination on how the traffic is handled. + +.. _hairpin_nat_reflection: + +Hairpin NAT/NAT Reflection +-------------------------- + +A typical problem with using NAT and hosting public servers is the +ability for internal systems to reach an internal server using it's +external IP address. The solution to this is usually the use of +split-DNS to correctly point host systems to the internal address when +requests are made internally. Because many smaller networks lack DNS +infrastructure, a work-around is commonly deployed to facilitate the +traffic by NATing the request from internal hosts to the source address +of the internal interface on the firewall. + +This technique is commonly referred to as NAT Reflection or Hairpin NAT. + +Example: + +* Redirect Microsoft RDP traffic from the outside (WAN, external) world + via :ref:`destination-nat` in rule 100 to the internal, private host + 192.0.2.40. + +* Redirect Microsoft RDP traffic from the internal (LAN, private) + network via :ref:`destination-nat` in rule 110 to the internal, + private host 192.0.2.40. We also need a :ref:`source-nat` rule 110 for + the reverse path of the traffic. The internal network 192.0.2.0/24 is + reachable via interface `eth0.10`. + +.. code-block:: none + + set nat destination rule 100 description 'Regular destination NAT from external' + set nat destination rule 100 destination port '3389' + set nat destination rule 100 inbound-interface 'pppoe0' + set nat destination rule 100 protocol 'tcp' + set nat destination rule 100 translation address '192.0.2.40' + + set nat destination rule 110 description 'NAT Reflection: INSIDE' + set nat destination rule 110 destination port '3389' + set nat destination rule 110 inbound-interface 'eth0.10' + set nat destination rule 110 protocol 'tcp' + set nat destination rule 110 translation address '192.0.2.40' + + set nat source rule 110 description 'NAT Reflection: INSIDE' + set nat source rule 110 destination address '192.0.2.0/24' + set nat source rule 110 outbound-interface 'eth0.10' + set nat source rule 110 protocol 'tcp' + set nat source rule 110 source address '192.0.2.0/24' + set nat source rule 110 translation address 'masquerade' + +Which results in a configuration of: + +.. code-block:: none + + vyos@vyos# show nat + destination { + rule 100 { + description "Regular destination NAT from external" + destination { + port 3389 + } + inbound-interface pppoe0 + protocol tcp + translation { + address 192.0.2.40 + } + } + rule 110 { + description "NAT Reflection: INSIDE" + destination { + port 3389 + } + inbound-interface eth0.10 + protocol tcp + translation { + address 192.0.2.40 + } + } + } + source { + rule 110 { + description "NAT Reflection: INSIDE" + destination { + address 192.0.2.0/24 + } + outbound-interface eth0.10 + protocol tcp + source { + address 192.0.2.0/24 + } + translation { + address masquerade + } + } + } + + +Destination NAT +--------------- + +DNAT is typically referred to as a **Port Forward**. When using VyOS as +a NAT router and firewall, a common configuration task is to redirect +incoming traffic to a system behind the firewall. + +In this example, we will be using the example Quick Start configuration +above as a starting point. + +To setup a destination NAT rule we need to gather: + +* The interface traffic will be coming in on; +* The protocol and port we wish to forward; +* The IP address of the internal system we wish to forward traffic to. + +In our example, we will be forwarding web server traffic to an internal +web server on 192.168.0.100. HTTP traffic makes use of the TCP protocol +on port 80. For other common port numbers, see: +https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers + +Our configuration commands would be: + +.. code-block:: none + + set nat destination rule 10 description 'Port Forward: HTTP to 192.168.0.100' + set nat destination rule 10 destination port '80' + set nat destination rule 10 inbound-interface 'eth0' + set nat destination rule 10 protocol 'tcp' + set nat destination rule 10 translation address '192.168.0.100' + +Which would generate the following NAT destination configuration: + +.. code-block:: none + + nat { + destination { + rule 10 { + description "Port Forward: HTTP to 192.168.0.100" + destination { + port 80 + } + inbound-interface eth0 + protocol tcp + translation { + address 192.168.0.100 + } + } + } + } + +.. note:: If forwarding traffic to a different port than it is arriving + on, you may also configure the translation port using + `set nat destination rule [n] translation port`. + +This establishes our Port Forward rule, but if we created a firewall +policy it will likely block the traffic. + +It is important to note that when creating firewall rules that the DNAT +translation occurs **before** traffic traverses the firewall. In other +words, the destination address has already been translated to +192.168.0.100. + +So in our firewall policy, we want to allow traffic coming in on the +outside interface, destined for TCP port 80 and the IP address of +192.168.0.100. + +.. code-block:: none + + set firewall name OUTSIDE-IN rule 20 action 'accept' + set firewall name OUTSIDE-IN rule 20 destination address '192.168.0.100' + set firewall name OUTSIDE-IN rule 20 destination port '80' + set firewall name OUTSIDE-IN rule 20 protocol 'tcp' + set firewall name OUTSIDE-IN rule 20 state new 'enable' + +This would generate the following configuration: + +.. code-block:: none + + rule 20 { + action accept + destination { + address 192.168.0.100 + port 80 + } + protocol tcp + state { + new enable + } + } + +.. note:: + + If you have configured the `INSIDE-OUT` policy, you will need to add + additional rules to permit inbound NAT traffic. + +1-to-1 NAT +---------- + +Another term often used for DNAT is **1-to-1 NAT**. For a 1-to-1 NAT +configuration, both DNAT and SNAT are used to NAT all traffic from an +external IP address to an internal IP address and vice-versa. + +Typically, a 1-to-1 NAT rule omits the destination port (all ports) and +replaces the protocol with either **all** or **ip**. + +Then a corresponding SNAT rule is created to NAT outgoing traffic for +the internal IP to a reserved external IP. This dedicates an external IP +address to an internal IP address and is useful for protocols which +don't have the notion of ports, such as GRE. + +Here's an extract of a simple 1-to-1 NAT configuration with one internal +and one external interface: + +.. code-block:: none + + set interfaces ethernet eth0 address '192.168.1.1/24' + set interfaces ethernet eth0 description 'Inside interface' + set interfaces ethernet eth1 address '192.0.2.30/24' + set interfaces ethernet eth1 description 'Outside interface' + set nat destination rule 2000 description '1-to-1 NAT example' + set nat destination rule 2000 destination address '192.0.2.30' + set nat destination rule 2000 inbound-interface 'eth1' + set nat destination rule 2000 translation address '192.168.1.10' + set nat source rule 2000 description '1-to-1 NAT example' + set nat source rule 2000 outbound-interface 'eth1' + set nat source rule 2000 source address '192.168.1.10' + set nat source rule 2000 translation address '192.0.2.30' + +Firewall rules are written as normal, using the internal IP address as +the source of outbound rules and the destination of inbound rules. + +NAT before VPN +-------------- + +Some application service providers (ASPs) operate a VPN gateway to +provide access to their internal resources, and require that a +connecting organisation translate all traffic to the service provider +network to a source address provided by the ASP. + +Example Network +^^^^^^^^^^^^^^^ + +Here's one example of a network environment for an ASP. +The ASP requests that all connections from this company should come from +172.29.41.89 - an address that is assigned by the ASP and not in use at +the customer site. + +.. figure:: /_static/images/nat_before_vpn_topology.png + :scale: 100 % + :alt: NAT before VPN Topology + + NAT before VPN Topology + + +Configuration +^^^^^^^^^^^^^ + +The required configuration can be broken down into 4 major pieces: + +* A dummy interface for the provider-assigned IP; +* NAT (specifically, Source NAT); +* IPSec IKE and ESP Groups; +* IPSec VPN tunnels. + + +Dummy interface +""""""""""""""" + +The dummy interface allows us to have an equivalent of the Cisco IOS +Loopback interface - a router-internal interface we can use for IP +addresses the router must know about, but which are not actually +assigned to a real network. + +We only need a single step for this interface: + +.. code-block:: none + + set interfaces dummy dum0 address '172.29.41.89/32' + +NAT Configuration +""""""""""""""""" + +.. code-block:: none + + set nat source rule 110 description 'Internal to ASP' + set nat source rule 110 destination address '172.27.1.0/24' + set nat source rule 110 outbound-interface 'any' + set nat source rule 110 source address '192.168.43.0/24' + set nat source rule 110 translation address '172.29.41.89' + set nat source rule 120 description 'Internal to ASP' + set nat source rule 120 destination address '10.125.0.0/16' + set nat source rule 120 outbound-interface 'any' + set nat source rule 120 source address '192.168.43.0/24' + set nat source rule 120 translation address '172.29.41.89' + +IPSec IKE and ESP +""""""""""""""""" + +The ASP has documented their IPSec requirements: + +* IKE Phase: + + * aes256 Encryption + * sha256 Hashes + +* ESP Phase: + + * aes256 Encryption + * sha256 Hashes + * DH Group 14 + + +Additionally, we want to use VPNs only on our eth1 interface (the +external interface in the image above) + +.. code-block:: none + + set vpn ipsec ike-group my-ike ikev2-reauth 'no' + set vpn ipsec ike-group my-ike key-exchange 'ikev1' + set vpn ipsec ike-group my-ike lifetime '7800' + set vpn ipsec ike-group my-ike proposal 1 dh-group '14' + set vpn ipsec ike-group my-ike proposal 1 encryption 'aes256' + set vpn ipsec ike-group my-ike proposal 1 hash 'sha256' + + set vpn ipsec esp-group my-esp compression 'disable' + set vpn ipsec esp-group my-esp lifetime '3600' + set vpn ipsec esp-group my-esp mode 'tunnel' + set vpn ipsec esp-group my-esp pfs 'disable' + set vpn ipsec esp-group my-esp proposal 1 encryption 'aes256' + set vpn ipsec esp-group my-esp proposal 1 hash 'sha256' + + set vpn ipsec ipsec-interfaces interface 'eth1' + +IPSec VPN Tunnels +""""""""""""""""" + +We'll use the IKE and ESP groups created above for this VPN. Because we +need access to 2 different subnets on the far side, we will need two +different tunnels. If you changed the names of the ESP group and IKE +group in the previous step, make sure you use the correct names here +too. + +.. code-block:: none + + set vpn ipsec site-to-site peer 198.51.100.243 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 198.51.100.243 authentication pre-shared-secret 'PASSWORD IS HERE' + set vpn ipsec site-to-site peer 198.51.100.243 connection-type 'initiate' + set vpn ipsec site-to-site peer 198.51.100.243 default-esp-group 'my-esp' + set vpn ipsec site-to-site peer 198.51.100.243 ike-group 'my-ike' + set vpn ipsec site-to-site peer 198.51.100.243 ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer 198.51.100.243 local-address '203.0.113.46' + set vpn ipsec site-to-site peer 198.51.100.243 tunnel 0 local prefix '172.29.41.89/32' + set vpn ipsec site-to-site peer 198.51.100.243 tunnel 0 remote prefix '172.27.1.0/24' + set vpn ipsec site-to-site peer 198.51.100.243 tunnel 1 local prefix '172.29.41.89/32' + set vpn ipsec site-to-site peer 198.51.100.243 tunnel 1 remote prefix '10.125.0.0/16' + +Testing and Validation +"""""""""""""""""""""" + +If you've completed all the above steps you no doubt want to see if it's +all working. + +Start by checking for IPSec SAs (Security Associations) with: + +.. code-block:: none + + $ show vpn ipsec sa + + Peer ID / IP Local ID / IP + ------------ ------------- + 198.51.100.243 203.0.113.46 + + Tunnel State Bytes Out/In Encrypt Hash NAT-T A-Time L-Time Proto + ------ ----- ------------- ------- ---- ----- ------ ------ ----- + 0 up 0.0/0.0 aes256 sha256 no 1647 3600 all + 1 up 0.0/0.0 aes256 sha256 no 865 3600 all + +That looks good - we defined 2 tunnels and they're both up and running. diff --git a/docs/configuration/nat/nat66.rst b/docs/configuration/nat/nat66.rst new file mode 100644 index 00000000..bcf5570f --- /dev/null +++ b/docs/configuration/nat/nat66.rst @@ -0,0 +1,127 @@ +.. _nat66: + +############ +NAT66(NPTv6) +############ + +:abbr:`NPTv6 (IPv6-to-IPv6 Network Prefix Translation)` is an address translation technology based +on IPv6 networks, used to convert an IPv6 address prefix in an IPv6 message into another IPv6 +address prefix. We call this address translation method NAT66. Devices that support the NAT66 +function are called NAT66 devices, which can provide NAT66 source and destination address +translation functions. + +Overview +======== + +Different NAT Types +------------------- + +.. _source-nat66: + +SNAT66 +^^^^^^ + +:abbr:`SNPTv6 (Source IPv6-to-IPv6 Network Prefix Translation)` The conversion function is mainly used in +the following scenarios: + +* A single internal network and external network. Use the NAT66 device to connect a single internal + network and public network, and the hosts in the internal network use IPv6 address prefixes that + only support routing within the local range. When a host in the internal network accesses the + external network, the source IPv6 address prefix in the message will be converted into a + global unicast IPv6 address prefix by the NAT66 device. +* Redundancy and load sharing. There are multiple NAT66 devices at the edge of an IPv6 network + to another IPv6 network. The path through the NAT66 device to another IPv6 network forms an + equivalent route, and traffic can be load-shared on these NAT66 devices. In this case, you + can configure the same source address translation rules on these NAT66 devices, so that any + NAT66 device can handle IPv6 traffic between different sites. +* Multi-homed. In a multi-homed network environment, the NAT66 device connects to an + internal network and simultaneously connects to different external networks. Address + translation can be configured on each external network side interface of the NAT66 + device to convert the same internal network address into different external network + addresses, and realize the mapping of the same internal address to multiple external addresses. + +.. _destination-nat66: + +DNAT66 +^^^^^^ + +The :abbr:`DNPTv6 (Destination IPv6-to-IPv6 Network Prefix Translation)` destination address translation +function is used in scenarios where the server in the internal network provides services to the external +network, such as providing Web services or FTP services to the external network. By configuring the mapping +relationship between the internal server address and the external network address on the external network +side interface of the NAT66 device, external network users can access the internal network server through +the designated external network address. + +Prefix Conversion +------------------ + +Source Prefix +^^^^^^^^^^^^^ + +Every SNAT66 rule has a translation command defined. The prefix defined +for the translation is the prefix used when the address information in +a packet is replaced.、 + +The :ref:`source-nat66` rule replaces the source address of the packet and calculates the +converted address using the prefix specified in the rule. + +Example: + +* Convert the address prefix of a single `fc01::/64` network to `fc00::/64` +* Output from `eth0` network interface + +.. code-block:: none + + set nat66 source rule 1 outbound-interface 'eth0' + set nat66 source rule 1 source prefix 'fc01::/64' + set nat66 source rule 1 translation prefix 'fc00::/64' + +Destination Prefix +^^^^^^^^^^^^^^^^^^ + +For the :ref:`destination-nat66` rule, the destination address of the packet is +replaced by the address calculated from the specified address or prefix in the +`translation address` command + +Example: + +* Convert the address prefix of a single `fc00::/64` network to `fc01::/64` +* Input from `eth0` network interface + +.. code-block:: none + + set nat66 destination rule 1 inbound-interface 'eth0' + set nat66 destination rule 1 destination address 'fc00::/64' + set nat66 destination rule 1 translation address 'fc01::/64' + +Configuration Examples +====================== + +Use the following topology to build a nat66 based isolated network between internal +and external networks (dynamic prefix is not supported): + +.. figure:: /_static/images/vyos_1_4_nat66_simple.png + :alt: VyOS NAT66 Simple Configure + +R1: + +.. code-block:: none + + set interfaces ethernet eth0 ipv6 address autoconf + set interfaces ethernet eth1 address 'fc01::1/64' + set nat66 destination rule 1 destination address 'fc00:470:f1cd:101::/64' + set nat66 destination rule 1 inbound-interface 'eth0' + set nat66 destination rule 1 translation address 'fc01::/64' + set nat66 source rule 1 outbound-interface 'eth0' + set nat66 source rule 1 source prefix 'fc01::/64' + set nat66 source rule 1 translation prefix 'fc00:470:f1cd:101::/64' + +R2: + +.. code-block:: none + + set interfaces bridge br1 address 'fc01::2/64' + set interfaces bridge br1 member interface eth0 + set interfaces bridge br1 member interface eth1 + set protocols static route6 ::/0 next-hop fc01::1 + set service router-advert interface br1 prefix ::/0 diff --git a/docs/configuration/policy/index.rst b/docs/configuration/policy/index.rst new file mode 100644 index 00000000..c772306f --- /dev/null +++ b/docs/configuration/policy/index.rst @@ -0,0 +1,207 @@ +.. include:: /_include/need_improvement.txt + +###### +Policy +###### + +Routing Policies could be used to tell the router (self or neighbors) what +routes and their attributes needs to be put into the routing table. + +There could be a wide range of routing policies. Some examples are below: + +* Set some metric to routes learned from a particular neighbor +* Set some attributes (like AS PATH or Community value) to advertised routes + to neighbors +* Prefer a specific routing protocol routes over another routing protocol + running on the same router + +Example +======= + +**Policy definition:** + +.. code-block:: none + + # Create policy + set policy route-map setmet rule 2 action 'permit' + set policy route-map setmet rule 2 set as-path-prepend '2 2 2' + + # Apply policy to BGP + set protocols bgp 1 neighbor 203.0.113.2 address-family ipv4-unicast route-map import 'setmet' + set protocols bgp 1 neighbor 203.0.113.2 address-family ipv4-unicast soft-reconfiguration 'inbound' + +Using 'soft-reconfiguration' we get the policy update without bouncing the +neighbor. + +**Routes learned before routing policy applied:** + +.. code-block:: none + + vyos@vos1:~$ show ip bgp + BGP table version is 0, local router ID is 192.168.56.101 + Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, + r RIB-failure, S Stale, R Removed + Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path + *> 198.51.100.3/32 203.0.113.2 1 0 2 i < Path + + Total number of prefixes 1 + +**Routes learned after routing policy applied:** + +.. code-block:: none + + vyos@vos1:~$ sho ip b + BGP table version is 0, local router ID is 192.168.56.101 + Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, + r RIB-failure, S Stale, R Removed + Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path + *> 198.51.100.3/32 203.0.113.2 1 0 2 2 2 2 i + + Total number of prefixes 1 + vyos@vos1:~$ + +You now see the longer AS path. + + +.. _routing-pbr: + +### +PBR +### + +:abbr:`PBR (Policy-Based Routing)` allowing traffic to be assigned to +different routing tables. Traffic can be matched using standard 5-tuple +matching (source address, destination address, protocol, source port, +destination port). + +Transparent Proxy +================= + +The following example will show how VyOS can be used to redirect web +traffic to an external transparent proxy: + +.. code-block:: none + + set policy route FILTER-WEB rule 1000 destination port 80 + set policy route FILTER-WEB rule 1000 protocol tcp + set policy route FILTER-WEB rule 1000 set table 100 + +This creates a route policy called FILTER-WEB with one rule to set the +routing table for matching traffic (TCP port 80) to table ID 100 +instead of the default routing table. + +To create routing table 100 and add a new default gateway to be used by +traffic matching our route policy: + +.. code-block:: none + + set protocols static table 100 route 0.0.0.0/0 next-hop 10.255.0.2 + +This can be confirmed using the ``show ip route table 100`` operational +command. + +Finally, to apply the policy route to ingress traffic on our LAN +interface, we use: + +.. code-block:: none + + set interfaces ethernet eth1 policy route FILTER-WEB + + +Multiple Uplinks +================ + +VyOS Policy-Based Routing (PBR) works by matching source IP address +ranges and forwarding the traffic using different routing tables. + +Routing tables that will be used in this example are: + +* ``table 10`` Routing table used for VLAN 10 (192.168.188.0/24) +* ``table 11`` Routing table used for VLAN 11 (192.168.189.0/24) +* ``main`` Routing table used by VyOS and other interfaces not + participating in PBR + +.. figure:: /_static/images/pbr_example_1.png + :scale: 80 % + :alt: PBR multiple uplinks + + Policy-Based Routing with multiple ISP uplinks + (source ./draw.io/pbr_example_1.drawio) + +Add default routes for routing ``table 10`` and ``table 11`` + +.. code-block:: none + + set protocols static table 10 route 0.0.0.0/0 next-hop 192.0.2.1 + set protocols static table 11 route 0.0.0.0/0 next-hop 192.0.2.2 + +Add policy route matching VLAN source addresses + +.. code-block:: none + + set policy route PBR rule 20 set table '10' + set policy route PBR rule 20 description 'Route VLAN10 traffic to table 10' + set policy route PBR rule 20 source address '192.168.188.0/24' + + set policy route PBR rule 30 set table '11' + set policy route PBR rule 30 description 'Route VLAN11 traffic to table 11' + set policy route PBR rule 30 source address '192.168.189.0/24' + +Apply routing policy to **inbound** direction of out VLAN interfaces + +.. code-block:: none + + set interfaces ethernet eth0 vif 10 policy route 'PBR' + set interfaces ethernet eth0 vif 11 policy route 'PBR' + + +**OPTIONAL:** Exclude Inter-VLAN traffic (between VLAN10 and VLAN11) +from PBR + +.. code-block:: none + + set policy route PBR rule 10 description 'VLAN10 <-> VLAN11 shortcut' + set policy route PBR rule 10 destination address '192.168.188.0/24' + set policy route PBR rule 10 destination address '192.168.189.0/24' + set policy route PBR rule 10 set table 'main' + +These commands allow the VLAN10 and VLAN20 hosts to communicate with +each other using the main routing table. + +Local route +=========== + +The following example allows VyOS to use :abbr:`PBR (Policy-Based Routing)` +for traffic, which originated from the router itself. That solution for multiple +ISP's and VyOS router will respond from the same interface that the packet was +received. Also, it used, if we want that one VPN tunnel to be through one +provider, and the second through another. + +* ``203.0.113.0.254`` IP addreess on VyOS eth1 from ISP1 +* ``192.168.2.254`` IP addreess on VyOS eth2 from ISP2 +* ``table 10`` Routing table used for ISP1 +* ``table 11`` Routing table used for ISP2 + + +.. code-block:: none + + set policy local-route rule 101 set table '10' + set policy local-route rule 101 source '203.0.113.0.254' + set policy local-route rule 102 set table '11' + set policy local-route rule 102 source '192.0.2.254' + set protocols static table 10 route '0.0.0.0/0' next-hop '203.0.113.0.1' + set protocols static table 11 route '0.0.0.0/0' next-hop '192.0.2.2' + +Add multiple source IP in one rule with same priority + +.. code-block:: none + + set policy local-route rule 101 set table '10' + set policy local-route rule 101 source '203.0.113.0.254' + set policy local-route rule 101 source '203.0.113.0.253' + set policy local-route rule 101 source '198.51.100.0/24' + diff --git a/docs/configuration/protocols/bfd.rst b/docs/configuration/protocols/bfd.rst new file mode 100644 index 00000000..8d19334c --- /dev/null +++ b/docs/configuration/protocols/bfd.rst @@ -0,0 +1,133 @@ +.. include:: /_include/need_improvement.txt + +.. _routing-bfd: + +### +BFD +### + +:abbr:`BFD (Bidirectional Forwarding Detection)` is described and extended by +the following RFCs: :rfc:`5880`, :rfc:`5881` and :rfc:`5883`. + +In the age of very fast networks, a second of unreachability may equal millions of lost packets. +The idea behind BFD is to detect very quickly when a peer is down and take action extremely fast. + +BFD sends lots of small UDP packets very quickly to ensures that the peer is still alive. + +This allows avoiding the timers defined in BGP and OSPF protocol to expires. + +Configure BFD +============= + +.. cfgcmd:: set protocols bfd peer <address> + + Set BFD peer IPv4 address or IPv6 address + +.. cfgcmd:: set protocols bfd peer <address> echo-mode + + Enables the echo transmission mode + +.. cfgcmd:: set protocols bfd peer <address> multihop + + Allow this BFD peer to not be directly connected + +.. cfgcmd:: set protocols bfd peer <address> source + [address <address> | interface <interface>] + + Bind listener to specifid interface/address, mandatory for IPv6 + +.. cfgcmd:: set protocols bfd peer <address> interval echo-interval <10-60000> + + The minimal echo receive transmission interval that this system is + capable of handling + +.. cfgcmd:: set protocols bfd peer <address> interval multiplier <2-255> + + Remote transmission interval will be multiplied by this value + +.. cfgcmd:: set protocols bfd peer <address> interval + [receive | transmit] <10-60000> + + Interval in milliseconds + +.. cfgcmd:: set protocols bfd peer <address> shutdown + + Disable a BFD peer + + +Enable BFD in BGP +----------------- + +.. cfgcmd:: set protocols bgp <asn> neighbor <address> bfd + + Enable BFD on a single BGP neighbor + +.. cfgcmd:: set protocols bgp <asn> peer-group <group> bfd + + Enable BFD on a BGP peer group + + +Enable BFD in OSPF +------------------ + +.. cfgcmd:: set interfaces ethernet <interface> ip ospf bfd + + Enable BFD for OSPF on a interface + +.. cfgcmd:: set interfaces ethernet <interface> ipv6 ospfv3 bfd + + Enable BFD for OSPFv3 on a interface + + +Enable BFD in ISIS +------------------ + +.. cfgcmd:: set protocols isis <name> interface <interface> bfd + + Enable BFD for ISIS on a interface + + + +Operational Commands +==================== + +.. opcmd:: show protocols bfd peer + + Show all BFD peers + + .. code-block:: none + + BFD Peers: + peer 198.51.100.33 vrf default interface eth4.100 + ID: 4182341893 + Remote ID: 12678929647 + Status: up + Uptime: 1 month(s), 16 hour(s), 29 minute(s), 38 second(s) + Diagnostics: ok + Remote diagnostics: ok + Local timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 50ms + Remote timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 0ms + + peer 198.51.100.55 vrf default interface eth4.101 + ID: 4618932327 + Remote ID: 3312345688 + Status: up + Uptime: 20 hour(s), 16 minute(s), 19 second(s) + Diagnostics: ok + Remote diagnostics: ok + Local timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 50ms + Remote timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 0ms + + diff --git a/docs/configuration/protocols/bgp.rst b/docs/configuration/protocols/bgp.rst new file mode 100644 index 00000000..6b6605a6 --- /dev/null +++ b/docs/configuration/protocols/bgp.rst @@ -0,0 +1,1179 @@ +.. _bgp: + +### +BGP +### + +:abbr:`BGP (Border Gateway Protocol)` is one of the Exterior Gateway Protocols +and the de facto standard interdomain routing protocol. The latest BGP version +is 4. BGP-4 is described in :rfc:`1771` and updated by :rfc:`4271`. :rfc:`2858` +adds multiprotocol support to BGP. + +VyOS makes use of :abbr:`FRR (Free Range Routing)` and we would like to thank +them for their effort! + +Basic Concepts +============== + +.. _bgp-autonomous-systems: + +Autonomous Systems +------------------ + +From :rfc:`1930`: + + An AS is a connected group of one or more IP prefixes run by one or more + network operators which has a SINGLE and CLEARLY DEFINED routing policy. + +Each AS has an identifying number associated with it called an :abbr:`ASN +(Autonomous System Number)`. This is a two octet value ranging in value from 1 +to 65535. The AS numbers 64512 through 65535 are defined as private AS numbers. +Private AS numbers must not be advertised on the global Internet. The 2-byte AS +number range has been exhausted. 4-byte AS numbers are specified in +:rfc:`6793`, and provide a pool of 4294967296 AS numbers. + +The :abbr:`ASN (Autonomous System Number)` is one of the essential elements of +BGP. BGP is a distance vector routing protocol, and the AS-Path framework +provides distance vector metric and loop detection to BGP. + +.. _bgp-address-families: + +Address Families +---------------- + +Multiprotocol extensions enable BGP to carry routing information for multiple +network layer protocols. BGP supports an Address Family Identifier (AFI) for +IPv4 and IPv6. + +.. _bgp-route-selection: + +Route Selection +--------------- + +The route selection process used by FRR's BGP implementation uses the following +decision criterion, starting at the top of the list and going towards the +bottom until one of the factors can be used. + +1. **Weight check** + + Prefer higher local weight routes to lower routes. + +2. **Local preference check** + + Prefer higher local preference routes to lower. + +3. **Local route check** + + Prefer local routes (statics, aggregates, redistributed) to received routes. + +4. **AS path length check** + + Prefer shortest hop-count AS_PATHs. + +5. **Origin check** + + Prefer the lowest origin type route. That is, prefer IGP origin routes to + EGP, to Incomplete routes. + +6. **MED check** + + Where routes with a MED were received from the same AS, prefer the route + with the lowest MED. + +7. **External check** + + Prefer the route received from an external, eBGP peer over routes received + from other types of peers. + +8. **IGP cost check** + + Prefer the route with the lower IGP cost. + +9. **Multi-path check** + + If multi-pathing is enabled, then check whether the routes not yet + distinguished in preference may be considered equal. If + :cfgcmd:`bgp bestpath as-path multipath-relax` is set, all such routes are + considered equal, otherwise routes received via iBGP with identical AS_PATHs + or routes received from eBGP neighbours in the same AS are considered equal. + +10. **Already-selected external check** + + Where both routes were received from eBGP peers, then prefer the route + which is already selected. Note that this check is not applied if + :cfgcmd:`bgp bestpath compare-routerid` is configured. This check can + prevent some cases of oscillation. + +11. **Router-ID check** + + Prefer the route with the lowest `router-ID`. If the route has an + `ORIGINATOR_ID` attribute, through iBGP reflection, then that router ID is + used, otherwise the `router-ID` of the peer the route was received from is + used. + +12. **Cluster-List length check** + + The route with the shortest cluster-list length is used. The cluster-list + reflects the iBGP reflection path the route has taken. + +13. **Peer address** + + Prefer the route received from the peer with the higher transport layer + address, as a last-resort tie-breaker. + +.. _bgp-capability-negotiation: + +Capability Negotiation +---------------------- + +When adding IPv6 routing information exchange feature to BGP. There were some +proposals. :abbr:`IETF (Internet Engineering Task Force)` +:abbr:`IDR (Inter Domain Routing)` adopted a proposal called Multiprotocol +Extension for BGP. The specification is described in :rfc:`2283`. The protocol +does not define new protocols. It defines new attributes to existing BGP. When +it is used exchanging IPv6 routing information it is called BGP-4+. When it is +used for exchanging multicast routing information it is called MBGP. + +*bgpd* supports Multiprotocol Extension for BGP. So if a remote peer supports +the protocol, *bgpd* can exchange IPv6 and/or multicast routing information. + +Traditional BGP did not have the feature to detect a remote peer's +capabilities, e.g. whether it can handle prefix types other than IPv4 unicast +routes. This was a big problem using Multiprotocol Extension for BGP in an +operational network. :rfc:`2842` adopted a feature called Capability +Negotiation. *bgpd* use this Capability Negotiation to detect the remote peer's +capabilities. If a peer is only configured as an IPv4 unicast neighbor, *bgpd* +does not send these Capability Negotiation packets (at least not unless other +optional BGP features require capability negotiation). + +By default, FRR will bring up peering with minimal common capability for the +both sides. For example, if the local router has unicast and multicast +capabilities and the remote router only has unicast capability the local router +will establish the connection with unicast only capability. When there are no +common capabilities, FRR sends Unsupported Capability error and then resets the +connection. + +.. _bgp-router-configuration: + +BGP Router Configuration +======================== + +First of all you must configure BGP router with the :abbr:`ASN (Autonomous +System Number)`. The AS number is an identifier for the autonomous system. +The BGP protocol uses the AS number for detecting whether the BGP connection +is internal or external. VyOS does not have a special command to start the BGP +process. The BGP process starts when the first neighbor is configured. + +Peers Configuration +------------------- + +Defining Peers +^^^^^^^^^^^^^^ + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> remote-as + <nasn> + + This command creates a new neighbor whose remote-as is <nasn>. The neighbor + address can be an IPv4 address or an IPv6 address or an interface to use + for the connection. The command it applicable for peer and peer group. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> remote-as + internal + + Create a peer as you would when you specify an ASN, except that if the + peers ASN is different than mine as specified under the :cfgcmd:`protocols + bgp <asn>` command the connection will be denied. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> remote-as + external + + Create a peer as you would when you specify an ASN, except that if the + peers ASN is the same as mine as specified under the :cfgcmd:`protocols + bgp <asn>` command the connection will be denied. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> shutdown + + This command disable the peer or peer group. To reenable the peer use + the delete form of this command. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> description + <text> + + Set description of the peer or peer group. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> update-source + <address|interface> + + Specify the IPv4 source address to use for the BGP session to this neighbor, + may be specified as either an IPv4 address directly or as an interface name. + + +Capability Negotiation +^^^^^^^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> capability + dynamic + + This command would allow the dynamic update of capabilities over an + established BGP session. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> capability + extended-nexthop + + Allow bgp to negotiate the extended-nexthop capability with it’s peer. + If you are peering over a IPv6 Link-Local address then this capability + is turned on automatically. If you are peering over a IPv6 Global Address + then turning on this command will allow BGP to install IPv4 routes with + IPv6 nexthops if you do not have IPv4 configured on interfaces. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> + disable-capability-negotiation + + Suppress sending Capability Negotiation as OPEN message optional + parameter to the peer. This command only affects the peer is + configured other than IPv4 unicast configuration. + + When remote peer does not have capability negotiation feature, + remote peer will not send any capabilities at all. In that case, + bgp configures the peer with configured capabilities. + + You may prefer locally configured capabilities more than the negotiated + capabilities even though remote peer sends capabilities. If the peer is + configured by :cfgcmd:`override-capability`, VyOS ignores received + capabilities then override negotiated capabilities with configured values. + + Additionally you should keep in mind that this feature fundamentally + disables the ability to use widely deployed BGP features. BGP unnumbered, + hostname support, AS4, Addpath, Route Refresh, ORF, Dynamic Capabilities, + and graceful restart. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> + override-capability + + This command allow override the result of Capability Negotiation with + local configuration. Ignore remote peer’s capability value. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> + strict-capability-match + + This command forces strictly compare remote capabilities and local + capabilities. If capabilities are different, send Unsupported Capability + error then reset connection. + + You may want to disable sending Capability Negotiation OPEN message + optional parameter to the peer when remote peer does not implement + Capability Negotiation. Please use :cfgcmd:`disable-capability-negotiation` + command to disable the feature. + + +Peer Parameters +^^^^^^^^^^^^^^^ + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> allowas-in number <number> + + This command accept incoming routes with AS path containing AS + number with the same value as the current system AS. This is + used when you want to use the same AS number in your sites, + but you can’t connect them directly. + + The number parameter (1-10) configures the amount of accepted + occurences of the system AS number in AS path. + + This command is only allowed for eBGP peers. It is not applicable + for peer groups. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> as-override + + This command override AS number of the originating router with + the local AS number. + + Usually this configuration is used in PEs (Provider Edge) to + replace the incoming customer AS number so the connected CE ( + Customer Edge) can use the same AS number as the other customer + sites. This allows customers of the provider network to use the + same AS number across their sites. + + This command is only allowed for eBGP peers. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> attribute-unchanged <as-path|med|next-hop> + + This command specifies attributes to be left unchanged for + advertisements sent to a peer or peer group. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> maximum-prefix <number> + + This command specifies a maximum number of prefixes we can receive + from a given peer. If this number is exceeded, the BGP session + will be destroyed. The number range is 1 to 4294967295. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> nexthop-self + + This command forces the BGP speaker to report itself as the + next hop for an advertised route it advertised to a neighbor. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> remove-private-as + + This command removes the private ASN of routes that are advertised + to the configured peer. It removes only private ASNs on routes + advertised to EBGP peers. + + If the AS-Path for the route has only private ASNs, the private + ASNs are removed. + + If the AS-Path for the route has a private ASN between public + ASNs, it is assumed that this is a design choice, and the + private ASN is not removed. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> soft-reconfiguration inbound + + Changes in BGP policies require the BGP session to be cleared. Clearing has a + large negative impact on network operations. Soft reconfiguration enables you + to generate inbound updates from a neighbor, change and activate BGP policies + without clearing the BGP session. + + This command specifies that route updates received from this neighbor will be + stored unmodified, regardless of the inbound policy. When inbound soft + reconfiguration is enabled, the stored updates are processed by the new + policy configuration to create new inbound updates. + + .. note:: Storage of route updates uses memory. If you enable soft + reconfiguration inbound for multiple neighbors, the amount of memory used + can become significant. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> weight <number> + + This command specifies a default weight value for the neighbor’s + routes. The number range is 1 to 65535. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> + advertisement-interval <seconds> + + This command specifies the minimum route advertisement interval for + the peer. The interval value is 0 to 600 seconds, with the default + advertisement interval being 0. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> + disable-connected-check + + This command allows peerings between directly connected eBGP peers + using loopback addresses without adjusting the default TTL of 1. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> + disable-send-community <extended|standard> + + This command specifies that the community attribute should not be sent + in route updates to a peer. By default community attribute is sent. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> ebgp-multihop + <number> + + This command allows sessions to be established with eBGP neighbors + when they are multiple hops away. When the neighbor is not directly + connected and this knob is not enabled, the session will not establish. + The number of hops range is 1 to 255. This command is mutually + exclusive with :cfgcmd:`ttl-security hops`. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> local-as <asn> + [no-prepend] [replace-as] + + Specify an alternate AS for this BGP process when interacting with + the specified peer or peer group. With no modifiers, the specified + local-as is prepended to the received AS_PATH when receiving routing + updates from the peer, and prepended to the outgoing AS_PATH (after + the process local AS) when transmitting local routes to the peer. + + If the :cfgcmd:`no-prepend` attribute is specified, then the supplied + local-as is not prepended to the received AS_PATH. + + If the :cfgcmd:`replace-as` attribute is specified, then only the supplied + local-as is prepended to the AS_PATH when transmitting local-route + updates to this peer. + + .. note:: This command is only allowed for eBGP peers. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> passive + + Configures the BGP speaker so that it only accepts inbound connections + from, but does not initiate outbound connections to the peer or peer group. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> password + <text> + + This command specifies a MD5 password to be used with the tcp socket that + is being used to connect to the remote peer. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> ttl-security + hops <number> + + This command enforces Generalized TTL Security Mechanism (GTSM), + as specified in :rfc:`5082`. With this command, only neighbors + that are the specified number of hops away will be allowed to + become neighbors. The number of hops range is 1 to 254. This + command is mutually exclusive with :cfgcmd:`ebgp-multihop`. + + +Peer Groups +^^^^^^^^^^^ + +Peer groups are used to help improve scaling by generating the same update +information to all members of a peer group. Note that this means that the +routes generated by a member of a peer group will be sent back to that +originating peer with the originator identifier attribute set to indicated +the originating peer. All peers not associated with a specific peer group +are treated as belonging to a default peer group, and will share updates. + +.. cfgcmd:: set protocols bgp <asn> peer-group <name> + + This command defines a new peer group. You can specify to the group the same + parameters that you can specify for specific neighbors. + + .. note:: If you apply a parameter to an individual neighbor IP address, you + override the action defined for a peer group that includes that IP + address. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> peer-group + <name> + + This command bind specific peer to peer group with a given name. + + +Network Advertisement Configuration +----------------------------------- + +.. cfgcmd:: set protocols bgp <asn> address-family <ipv4-unicast|ipv6-unicast> + network <prefix> + + This command is used for advertising IPv4 or IPv6 networks. + + .. note:: By default, the BGP prefix is advertised even if it's not present + in the routing table. This behaviour differs from the implementation of + some vendors. + +.. cfgcmd:: set protocols bgp <asn> parameters network-import-check + + This configuration modifies the behavior of the network statement. If you + have this configured the underlying network must exist in the routing table. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> default-originate [route-map <name>] + + By default, VyOS does not advertise a default route (0.0.0.0/0) even if it is + in routing table. When you want to announce default routes to the peer, use + this command. Using optional argument :cfgcmd:`route-map` you can inject the + default route to given neighbor only if the conditions in the route map are + met. + + +Route Aggregation Configuration +------------------------------- + +.. cfgcmd:: set protocols bgp <asn> address-family <ipv4-unicast|ipv6-unicast> + aggregate-address <prefix> + + This command specifies an aggregate address. The router will also + announce longer-prefixes inside of the aggregate address. + +.. cfgcmd:: set protocols bgp <asn> address-family <ipv4-unicast|ipv6-unicast> + aggregate-address <prefix> as-set + + This command specifies an aggregate address with a mathematical set of + autonomous systems. This command summarizes the AS_PATH attributes of + all the individual routes. + +.. cfgcmd:: set protocols bgp <asn> address-family <ipv4-unicast|ipv6-unicast> + aggregate-address <prefix> summary-only + + This command specifies an aggregate address and provides that + longer-prefixes inside of the aggregate address are suppressed + before sending BGP updates out to peers. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> unsuppress-map <name> + + This command applies route-map to selectively unsuppress prefixes + suppressed by summarisation. + + +Redistribution Configuration +---------------------------- + +.. cfgcmd:: set protocols bgp <asn> address-family <ipv4-unicast|ipv6-unicast> + redistribute <route source> + + This command redistributes routing information from the given route source + to the BGP process. There are six modes available for route source: + connected, kernel, ospf, rip, static, table. + +.. cfgcmd:: set protocols bgp <asn> address-family <ipv4-unicast|ipv6-unicast> + redistribute <route source> metric <number> + + This command specifies metric (MED) for redistributed routes. The + metric range is 0 to 4294967295. There are six modes available for + route source: connected, kernel, ospf, rip, static, table. + +.. cfgcmd:: set protocols bgp <asn> address-family <ipv4-unicast|ipv6-unicast> + redistribute <route source> route-map <name> + + This command allows to use route map to filter redistributed routes. + There are six modes available for route source: connected, kernel, + ospf, rip, static, table. + + +General Configuration +--------------------- + +Common parametrs +^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set protocols bgp <asn> parameters router-id <id> + + This command specifies the router-ID. If router ID is not specified it will + use the highest interface IP address. + +.. cfgcmd:: set protocols bgp <asn> maximum-paths <ebgp|ibgp> <number> + + This command defines the maximum number of parallel routes that + the BGP can support. In order for BGP to use the second path, the + following attributes have to match: Weight, Local Preference, AS + Path (both AS number and AS path length), Origin code, MED, IGP + metric. Also, the next hop address for each path must be different. + +.. cfgcmd:: set protocols bgp <asn> parameters default no-ipv4-unicast + + This command allows the user to specify that IPv4 peering is turned off by + default. + +.. cfgcmd:: set protocols bgp <asn> parameters log-neighbor-changes + + This command enable logging neighbor up/down changes and reset reason. + +.. cfgcmd:: set protocols bgp <asn> parameters no-client-to-client-reflection + + This command disables route reflection between route reflector clients. + By default, the clients of a route reflector are not required to be + fully meshed and the routes from a client are reflected to other clients. + However, if the clients are fully meshed, route reflection is not required. + In this case, use the :cfgcmd:`no-client-to-client-reflection` command + to disable client-to-client reflection. + +.. cfgcmd:: set protocols bgp <asn> parameters no-fast-external-failover + + Disable immediate session reset if peer's connected link goes down. + +.. cfgcmd:: set protocols bgp <asn> listen range <prefix> peer-group <name> + + This command is useful if one desires to loosen the requirement for BGP + to have strictly defined neighbors. Specifically what is allowed is for + the local router to listen to a range of IPv4 or IPv6 addresses defined + by a prefix and to accept BGP open messages. When a TCP connection + (and subsequently a BGP open message) from within this range tries to + connect the local router then the local router will respond and connect + with the parameters that are defined within the peer group. One must define + a peer-group for each range that is listed. If no peer-group is defined + then an error will keep you from committing the configuration. + +.. cfgcmd:: set protocols bgp <asn> listen limit <number> + + This command goes hand in hand with the listen range command to limit the + amount of BGP neighbors that are allowed to connect to the local router. + The limit range is 1 to 5000. + +Administrative Distance +^^^^^^^^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set protocols bgp <asn> parameters distance global + <external|internal|local> <distance> + + This command change distance value of BGP. The arguments are the distance + values for external routes, internal routes and local routes respectively. + The distance range is 1 to 255. + +.. cfgcmd:: set protocols bgp <asn> parameters distance prefix <subnet> + distance <distance> + + This command sets the administrative distance for a particular route. The + distance range is 1 to 255. + + .. note:: Routes with a distance of 255 are effectively disabled and not + installed into the kernel. + + +Timers +^^^^^^ + +.. cfgcmd:: set protocols bgp <asn> timers holdtime <seconds> + + This command specifies hold-time in seconds. The timer range is + 4 to 65535. The default value is 180 second. If you set value to 0 + VyOS will not hold routes. + +.. cfgcmd:: set protocols bgp <asn> timers keepalive <seconds> + + This command specifies keep-alive time in seconds. The timer + can range from 4 to 65535. The default value is 60 second. + + +Route Dampening +^^^^^^^^^^^^^^^ + +When a route fails, a routing update is sent to withdraw the route from the +network's routing tables. When the route is re-enabled, the change in +availability is also advertised. A route that continually fails and returns +requires a great deal of network traffic to update the network about the +route's status. + +Route dampening wich described in :rfc:`2439` enables you to identify routes +that repeatedly fail and return. If route dampening is enabled, an unstable +route accumulates penalties each time the route fails and returns. If the +accumulated penalties exceed a threshold, the route is no longer advertised. +This is route suppression. Routes that have been suppressed are re-entered +into the routing table only when the amount of their penalty falls below a +threshold. + +A penalty of 1000 is assessed each time the route fails. When the penalties +reach a predefined threshold (suppress-value), the router stops advertising +the route. + +Once a route is assessed a penalty, the penalty is decreased by half each time +a predefined amount of time elapses (half-life-time). When the accumulated +penalties fall below a predefined threshold (reuse-value), the route is +unsuppressed and added back into the BGP routing table. + +No route is suppressed indefinitely. Maximum-suppress-time defines the maximum +time a route can be suppressed before it is re-advertised. + +.. cfgcmd:: set protocols bgp <asn> parameters dampening + half-life <minutes> + + This command defines the amount of time in minutes after + which a penalty is reduced by half. The timer range is + 10 to 45 minutes. + +.. cfgcmd:: set protocols bgp <asn> parameters dampening + re-use <seconds> + + This command defines the accumulated penalty amount at which the + route is re-advertised. The penalty range is 1 to 20000. + +.. cfgcmd:: set protocols bgp <asn> parameters dampening + start-suppress-time <seconds> + + This command defines the accumulated penalty amount at which the + route is suppressed. The penalty range is 1 to 20000. + +.. cfgcmd:: set protocols bgp <asn> parameters dampening + max-suppress-time <seconds> + + This command defines the maximum time in minutes that a route is + suppressed. The timer range is 1 to 255 minutes. + + +Route Selection Configuration +----------------------------- + +.. cfgcmd:: set protocols bgp <asn> parameters always-compare-med + + This command provides to compare the MED on routes, even when they were + received from different neighbouring ASes. Setting this option makes the + order of preference of routes more defined, and should eliminate MED + induced oscillations. + +.. cfgcmd:: set protocols bgp <asn> parameters bestpath as-path confed + + This command specifies that the length of confederation path sets and + sequences should be taken into account during the BGP best path + decision process. + +.. cfgcmd:: set protocols bgp <asn> parameters bestpath as-path multipath-relax + + This command specifies that BGP decision process should consider paths + of equal AS_PATH length candidates for multipath computation. Without + the knob, the entire AS_PATH must match for multipath computation. + +.. cfgcmd:: set protocols bgp <asn> parameters bestpath as-path ignore + + Ignore AS_PATH length when selecting a route + +.. cfgcmd:: set protocols bgp <asn> parameters bestpath compare-routerid + + Ensure that when comparing routes where both are equal on most metrics, + including local-pref, AS_PATH length, IGP cost, MED, that the tie is + broken based on router-ID. + + If this option is enabled, then the already-selected check, where + already selected eBGP routes are preferred, is skipped. + + If a route has an ORIGINATOR_ID attribute because it has been reflected, + that ORIGINATOR_ID will be used. Otherwise, the router-ID of the peer + the route was received from will be used. + + The advantage of this is that the route-selection (at this point) will + be more deterministic. The disadvantage is that a few or even one lowest-ID + router may attract all traffic to otherwise-equal paths because of this + check. It may increase the possibility of MED or IGP oscillation, unless + other measures were taken to avoid these. The exact behaviour will be + sensitive to the iBGP and reflection topology. + +.. cfgcmd:: set protocols bgp <asn> parameters bestpath med confed + + This command specifies that BGP considers the MED when comparing routes + originated from different sub-ASs within the confederation to which this + BGP speaker belongs. The default state, where the MED attribute is not + considered. + +.. cfgcmd:: set protocols bgp <asn> parameters bestpath med missing-as-worst + + This command specifies that a route with a MED is always considered to be + better than a route without a MED by causing the missing MED attribute to + have a value of infinity. The default state, where the missing MED + attribute is considered to have a value of zero. + +.. cfgcmd:: set protocols bgp <asn> parameters default local-pref + <local-pref value> + + This command specifies the default local preference value. The local + preference range is 0 to 4294967295. + +.. cfgcmd:: set protocols bgp <asn> parameters deterministic-med + + This command provides to compare different MED values that advertised by + neighbours in the same AS for routes selection. When this command is + enabled, routes from the same autonomous system are grouped together, and + the best entries of each group are compared. + +.. cfgcmd:: set protocols bgp <asn> address-family ipv4-unicast network + <prefix> backdoor + + This command allows the router to prefer route to specified prefix learned + via IGP through backdoor link instead of a route to the same prefix learned + via EBGP. + + +Route Filtering Configuration +----------------------------- + +In order to control and modify routing information that is exchanged between +peers you can use route-map, filter-list, prefix-list, distribute-list. + +For inbound updates the order of preference is: + + - route-map + - filter-list + - prefix-list, distribute-list + +For outbound updates the order of preference is: + + - prefix-list, distribute-list + - filter-list + - route-map + + .. note:: The attributes :cfgcmd:`prefix-list` and :cfgcmd:`distribute-list` + are mutually exclusive, and only one command (distribute-list or + prefix-list) can be applied to each inbound or outbound direction for a + particular neighbor. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> distribute-list <export|import> <number> + + This command applys the access list filters named in <number> to the + specified BGP neighbor to restrict the routing information that BGP learns + and/or advertises. The arguments :cfgcmd:`export` and :cfgcmd:`import` + specify the direction in which the access list are applied. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> prefix-list <export|import> <name> + + This command applys the prfefix list filters named in <name> to the + specified BGP neighbor to restrict the routing information that BGP learns + and/or advertises. The arguments :cfgcmd:`export` and :cfgcmd:`import` + specify the direction in which the prefix list are applied. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> route-map <export|import> <name> + + This command applys the route map named in <name> to the specified BGP + neighbor to control and modify routing information that is exchanged + between peers. The arguments :cfgcmd:`export` and :cfgcmd:`import` + specify the direction in which the route map are applied. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> filter-list <export|import> <name> + + This command applys the AS path access list filters named in <name> to the + specified BGP neighbor to restrict the routing information that BGP learns + and/or advertises. The arguments :cfgcmd:`export` and :cfgcmd:`import` + specify the direction in which the AS path access list are applied. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address|interface> address-family + <ipv4-unicast|ipv6-unicast> capability orf <receive|send> + + This command enables the ORF capability (described in :rfc:`5291`) on the + local router, and enables ORF capability advertisement to the specified BGP + peer. The :cfgcmd:`receive` keyword configures a router to advertise ORF + receive capabilities. The :cfgcmd:`send` keyword configures a router to + advertise ORF send capabilities. To advertise a filter from a sender, you + must create an IP prefix list for the specified BGP peer applied in inbound + derection. + + +BGP Scaling Configuration +------------------------- + +BGP routers connected inside the same AS through BGP belong to an internal BGP +session, or IBGP. In order to prevent routing table loops, IBGP speaker does +not advertise IBGP-learned routes to other IBGP speaker (Split Horizon +mechanism). As such, IBGP requires a full mesh of all peers. For large +networks, this quickly becomes unscalable. + +There are two ways that help us to mitigate the BGPs full-mesh requirement in +a network: + + - Using BGP route-reflectors + - Using BGP confederation + + +Route Reflector Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Introducing route reflectors removes the need for the full-mesh. When you +configure a route reflector you have to tell the router whether the other IBGP +router is a client or non-client. A client is an IBGP router that the route +reflector will “reflect” routes to, the non-client is just a regular IBGP +neighbor. Route reflectors mechanism is described in :rfc:`4456` and updated +by :rfc:`7606`. + +.. cfgcmd:: set protocols bgp <asn> neighbor <address> address-family + <ipv4-unicast|ipv6-unicast> route-reflector-client + + This command specifies the given neighbor as route reflector client. + +.. cfgcmd:: set protocols bgp <asn> parameters cluster-id <id> + + This command specifies cluster ID which identifies a collection of route + reflectors and their clients, and is used by route reflectors to avoid + looping. By default cluster ID is set to the BGP router id value, but can be + set to an arbitrary 32-bit value. + + +Confederation Configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A BGP confederation divides our AS into sub-ASes to reduce the number of +required IBGP peerings. Within a sub-AS we still require full-mesh IBGP but +between these sub-ASes we use something that looks like EBGP but behaves like +IBGP (called confederation BGP). Confederation mechanism is described in +:rfc:`5065` + +.. cfgcmd:: set protocols bgp <subasn> parameters confederation identifier + <asn> + + This command specifies a BGP confederation identifier. <asn> is the number + of the autonomous system that internally includes multiple sub-autonomous + systems (a confederation). <subasn> is the number sub-autonomous system + inside <asn>. + +.. cfgcmd:: set protocols bgp <subasn> parameters confederation confederation + peers <nsubasn> + + This command sets other confederations <nsubasn> as members of autonomous + system specified by :cfgcmd:`confederation identifier <asn>`. + + +Operational Mode Commands +========================= + +Show +---- + +.. opcmd:: show <ip|ipv6> bgp + + This command displays all entries in BGP routing table. + +.. code-block:: none + + BGP table version is 10, local router ID is 10.0.35.3, vrf id 0 + Default local pref 100, local AS 65000 + Status codes: s suppressed, d damped, h history, * valid, > best, = multipath, + 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 + + Network Next Hop Metric LocPrf Weight Path + *> 198.51.100.0/24 10.0.34.4 0 0 65004 i + *> 203.0.113.0/24 10.0.35.5 0 0 65005 i + + Displayed 2 routes and 2 total paths + +.. opcmd:: show <ip|ipv6> bgp <address|prefix> + + This command displays information about the particular entry in the BGP + routing table. + +.. code-block:: none + + BGP routing table entry for 198.51.100.0/24 + Paths: (1 available, best #1, table default) + Advertised to non peer-group peers: + 10.0.13.1 10.0.23.2 10.0.34.4 10.0.35.5 + 65004 + 10.0.34.4 from 10.0.34.4 (10.0.34.4) + Origin IGP, metric 0, valid, external, best (First path received) + Last update: Wed Jan 6 12:18:53 2021 + +.. opcmd:: show ip bgp cidr-only + + This command displays routes with classless interdomain routing (CIDR). + +.. opcmd:: show <ip|ipv6> bgp 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> + + This command displays routes that are permitted by the BGP + community list. + +.. opcmd:: show ip bgp dampened-paths + + This command displays BGP dampened routes. + +.. opcmd:: show ip bgp flap-statistics + + This command displays information about flapping BGP routes. + +.. opcmd:: show ip bgp filter-list <name> + + This command displays BGP routes allowed by by the specified AS Path + access list. + +.. opcmd:: show <ip|ipv6> bgp neighbors <address> advertised-routes + + This command displays BGP routes advertised to a neighbor. + +.. opcmd:: show <ip|ipv6> bgp 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 + + This command displays BGP received-routes that are accepted after filtering. + +.. opcmd:: show <ip|ipv6> bgp neighbors <address> dampened-routes + + This command displays dampened routes received from BGP neighbor. + +.. opcmd:: show <ip|ipv6> bgp regexp <text> + + This command displays information about BGP routes whose AS path + matches the specified regular expression. + +.. opcmd:: show <ip|ipv6> bgp summary + + This command displays the status of all BGP connections. + +.. code-block:: none + + IPv4 Unicast Summary: + BGP router identifier 10.0.35.3, local AS number 65000 vrf-id 0 + BGP table version 11 + RIB entries 5, using 920 bytes of memory + Peers 4, using 82 KiB of memory + + Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd + 10.0.13.1 4 65000 148 159 0 0 0 02:16:01 0 + 10.0.23.2 4 65000 136 143 0 0 0 02:13:21 0 + 10.0.34.4 4 65004 161 163 0 0 0 02:16:01 1 + 10.0.35.5 4 65005 162 166 0 0 0 02:16:01 1 + + Total number of neighbors 4 + +Reset +----- + +.. opcmd:: reset <ip|ipv6> bgp <address> [soft [in|out]] + + This command resets BGP connections to the specified neighbor IP address. + With argument :cfgcmd:`soft` this command initiates a soft reset. If + you do not specify the :cfgcmd:`in` or :cfgcmd:`out` options, both + inbound and outbound soft reconfiguration are triggered. + +.. opcmd:: reset ip bgp all + + This command resets all BGP connections of given router. + +.. opcmd:: reset ip bgp dampening + + This command uses to clear BGP route dampening information and to + unsuppress suppressed routes. + +.. opcmd:: reset ip bgp external + + This command resets all external BGP peers of given router. + +.. opcmd:: reset ip bgp peer-group <name> [soft [in|out]] + + This command resets BGP connections to the specified peer group. + With argument :cfgcmd:`soft` this command initiates a soft reset. If + you do not specify the :cfgcmd:`in` or :cfgcmd:`out` options, both + inbound and outbound soft reconfiguration are triggered. + + +Configuration Examples +---------------------- + +IPv4 +^^^^ + +A simple eBGP configuration: + +**Node 1:** + +.. code-block:: none + + set protocols bgp 65534 neighbor 192.168.0.2 ebgp-multihop '2' + set protocols bgp 65534 neighbor 192.168.0.2 remote-as '65535' + set protocols bgp 65534 neighbor 192.168.0.2 update-source '192.168.0.1' + set protocols bgp 65534 address-family ipv4-unicast network '172.16.0.0/16' + set protocols bgp 65534 parameters router-id '192.168.0.1' + +**Node 2:** + +.. code-block:: none + + set protocols bgp 65535 neighbor 192.168.0.1 ebgp-multihop '2' + set protocols bgp 65535 neighbor 192.168.0.1 remote-as '65534' + set protocols bgp 65535 neighbor 192.168.0.1 update-source '192.168.0.2' + set protocols bgp 65535 address-family ipv4-unicast network '172.17.0.0/16' + set protocols bgp 65535 parameters router-id '192.168.0.2' + + +Don't forget, the CIDR declared in the network statement MUST **exist in your +routing table (dynamic or static), the best way to make sure that is true is +creating a static route:** + +**Node 1:** + +.. code-block:: none + + set protocols static route 172.16.0.0/16 blackhole distance '254' + +**Node 2:** + +.. code-block:: none + + set protocols static route 172.17.0.0/16 blackhole distance '254' + + +IPv6 +^^^^ + +A simple BGP configuration via IPv6. + +**Node 1:** + +.. code-block:: none + + set protocols bgp 65534 neighbor 2001:db8::2 ebgp-multihop '2' + set protocols bgp 65534 neighbor 2001:db8::2 remote-as '65535' + set protocols bgp 65534 neighbor 2001:db8::2 update-source '2001:db8::1' + set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv6-unicast + set protocols bgp 65534 address-family ipv6-unicast network '2001:db8:1::/48' + set protocols bgp 65534 parameters router-id '10.1.1.1' + +**Node 2:** + +.. code-block:: none + + set protocols bgp 65535 neighbor 2001:db8::1 ebgp-multihop '2' + set protocols bgp 65535 neighbor 2001:db8::1 remote-as '65534' + set protocols bgp 65535 neighbor 2001:db8::1 update-source '2001:db8::2' + set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv6-unicast + set protocols bgp 65535 address-family ipv6-unicast network '2001:db8:2::/48' + set protocols bgp 65535 parameters router-id '10.1.1.2' + +Don't forget, the CIDR declared in the network statement **MUST exist in your +routing table (dynamic or static), the best way to make sure that is true is +creating a static route:** + +**Node 1:** + +.. code-block:: none + + set protocols static route6 2001:db8:1::/48 blackhole distance '254' + +**Node 2:** + +.. code-block:: none + + set protocols static route6 2001:db8:2::/48 blackhole distance '254' + +Route Filter +^^^^^^^^^^^^ + +Route filter can be applied using a route-map: + +**Node1:** + +.. code-block:: none + + set policy prefix-list AS65535-IN rule 10 action 'permit' + set policy prefix-list AS65535-IN rule 10 prefix '172.16.0.0/16' + set policy prefix-list AS65535-OUT rule 10 action 'deny' + set policy prefix-list AS65535-OUT rule 10 prefix '172.16.0.0/16' + set policy prefix-list6 AS65535-IN rule 10 action 'permit' + set policy prefix-list6 AS65535-IN rule 10 prefix '2001:db8:2::/48' + set policy prefix-list6 AS65535-OUT rule 10 action 'deny' + set policy prefix-list6 AS65535-OUT rule 10 prefix '2001:db8:2::/48' + set policy route-map AS65535-IN rule 10 action 'permit' + set policy route-map AS65535-IN rule 10 match ip address prefix-list 'AS65535-IN' + set policy route-map AS65535-IN rule 10 match ipv6 address prefix-list 'AS65535-IN' + set policy route-map AS65535-IN rule 20 action 'deny' + set policy route-map AS65535-OUT rule 10 action 'deny' + set policy route-map AS65535-OUT rule 10 match ip address prefix-list 'AS65535-OUT' + set policy route-map AS65535-OUT rule 10 match ipv6 address prefix-list 'AS65535-OUT' + set policy route-map AS65535-OUT rule 20 action 'permit' + set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv4-unicast route-map export 'AS65535-OUT' + set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv4-unicast route-map import 'AS65535-IN' + set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv6-unicast route-map export 'AS65535-OUT' + set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv6-unicast route-map import 'AS65535-IN' + +**Node2:** + +.. code-block:: none + + set policy prefix-list AS65534-IN rule 10 action 'permit' + set policy prefix-list AS65534-IN rule 10 prefix '172.17.0.0/16' + set policy prefix-list AS65534-OUT rule 10 action 'deny' + set policy prefix-list AS65534-OUT rule 10 prefix '172.17.0.0/16' + set policy prefix-list6 AS65534-IN rule 10 action 'permit' + set policy prefix-list6 AS65534-IN rule 10 prefix '2001:db8:1::/48' + set policy prefix-list6 AS65534-OUT rule 10 action 'deny' + set policy prefix-list6 AS65534-OUT rule 10 prefix '2001:db8:1::/48' + set policy route-map AS65534-IN rule 10 action 'permit' + set policy route-map AS65534-IN rule 10 match ip address prefix-list 'AS65534-IN' + set policy route-map AS65534-IN rule 10 match ipv6 address prefix-list 'AS65534-IN' + set policy route-map AS65534-IN rule 20 action 'deny' + set policy route-map AS65534-OUT rule 10 action 'deny' + set policy route-map AS65534-OUT rule 10 match ip address prefix-list 'AS65534-OUT' + set policy route-map AS65534-OUT rule 10 match ipv6 address prefix-list 'AS65534-OUT' + set policy route-map AS65534-OUT rule 20 action 'permit' + set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv4-unicast route-map export 'AS65534-OUT' + set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv4-unicast route-map import 'AS65534-IN' + set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv6-unicast route-map export 'AS65534-OUT' + set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv6-unicast route-map import 'AS65534-IN' + +We could expand on this and also deny link local and multicast in the rule 20 +action deny. diff --git a/docs/configuration/protocols/igmp-proxy.disable b/docs/configuration/protocols/igmp-proxy.disable new file mode 100644 index 00000000..cce5f948 --- /dev/null +++ b/docs/configuration/protocols/igmp-proxy.disable @@ -0,0 +1,2 @@ +igmp-proxy +##########
\ No newline at end of file diff --git a/docs/configuration/protocols/igmp.rst b/docs/configuration/protocols/igmp.rst new file mode 100644 index 00000000..7109deb6 --- /dev/null +++ b/docs/configuration/protocols/igmp.rst @@ -0,0 +1,248 @@ +.. _multicast: + +######### +Multicast +######### + +VyOS facilitates IP Multicast by supporting **PIM Sparse Mode**, +**IGMP** and **IGMP-Proxy**. + +************ +PIM and IGMP +************ + +PIM (Protocol Independent Multicast) must be configured in every +interface of every participating router. Every router must also have the +location of the Rendevouz Point manually configured. Then, +unidirectional shared trees rooted at the Rendevouz Point will +automatically be built for multicast distribution. + +Traffic from multicast sources will go to the Rendezvous Point, and +receivers will pull it from a shared tree using IGMP (Internet Group +Management Protocol). + +Multicast receivers will talk IGMP to their local router, so, besides +having PIM configured in every router, IGMP must also be configured in +any router where there could be a multicast receiver locally connected. + +VyOS supports both IGMP version 2 and version 3 (which allows +source-specific multicast). + + +Example +======= + +In the following example we can see a basic multicast setup: + +.. image:: /_static/images/multicast-basic.png + :width: 90% + :align: center + :alt: Network Topology Diagram + + + +**Router 1** + +.. code-block:: none + + set interfaces ethernet eth2 address '172.16.0.2/24' + set interfaces ethernet eth1 address '100.64.0.1/24' + set protocols ospf area 0 network '172.16.0.0/24' + set protocols ospf area 0 network '100.64.0.0/24' + set protocols igmp interface eth1 + set protocols pim interface eth1 + set protocols pim interface eth2 + set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' + +**Router 3** + +.. code-block:: none + + set interfaces dummy dum0 address '172.16.255.1/24' + set interfaces ethernet eth0 address '172.16.0.1/24' + set interfaces ethernet eth1 address '172.16.1.1/24' + set protocols ospf area 0 network '172.16.0.0/24' + set protocols ospf area 0 network '172.16.255.0/24' + set protocols ospf area 0 network '172.16.1.0/24' + set protocols pim interface dum0 + set protocols pim interface eth0 + set protocols pim interface eth1 + set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' + +**Router 2** + +.. code-block:: none + + set interfaces ethernet eth1 address '10.0.0.1/24' + set interfaces ethernet eth2 address '172.16.1.2/24' + set protocols ospf area 0 network '10.0.0.0/24' + set protocols ospf area 0 network '172.16.1.0/24' + set protocols pim interface eth1 + set protocols pim interface eth2 + set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' + + + + + +Basic commands +============== + +These are the commands for a basic setup. + +.. cfgcmd:: set protocols pim interface <interface-name> + + Use this command to enable PIM in the selected interface so that it + can communicate with PIM neighbors. + + +.. cfgcmd:: set protocols pim rp address <address> group + <multicast-address/mask-bits> + + Use this comand to manually configure a Rendevouz Point for PIM so + that join messages can be sent there. Set the Rendevouz Point address + and the matching prefix of group ranges covered. These values must + be shared with every router participating in the PIM network. + + +.. cfgcmd:: set protocols igmp interface eth1 + + Use this command to configure an interface with IGMP so that PIM can + receive IGMP reports and query on the selected interface. By defaul + IGMP version 3 will be used. + + + +Tuning commands +=============== + +You can also tune multicast with the following commands. + +.. cfgcmd:: set protocols pim interface <interface> dr-priority <value> + + Use this PIM command in the selected interface to set the priority + (1-4294967295) you want to influence in the election of a node to + become the Designated Router for a LAN segment. The default priority + is 1, set a higher value to give the router more preference in the + DR election process. + + +.. cfgcmd:: set protocols pim int <interface> hello <seconds> + + Use this command to configure the PIM hello interval in seconds + (1-180) for the selected interface. + + +.. cfgcmd:: set protocols pim rp keep-alive-timer <seconds> + + Use this PIM command to modify the the time out value (31-60000 + seconds) for an `(S,G) <https://tools.ietf.org/html/rfc7761#section-4.1>`_ + flow. 31 seconds is chosen for a lower bound as some hardware + platforms cannot see data flowing in better than 30 second chunks. + + +.. cfgcmd:: set protocols igmp interface <interface> join <multicast-address> + source <IP-address> + + Use this command to allow the selected interface join a multicast + group defining the multicast address you want to join and the source + IP address too. + + +.. cfgcmd:: set protocols igmp interface <interface query-interval <seconds> + + Use this command to configure in the selected interface the IGMP + host query interval (1-1800) in seconds that PIM will use. + + +.. cfgcmd:: set protocols igmp interface <interface query-max-response-time + <deciseconds> + + Use this command to configure in the selected interface the IGMP + query response timeout value (10-250) in deciseconds. If a report is + not returned in the specified time, it will be asumed the `(S,G) or + (*,G) state <https://tools.ietf.org/html/rfc7761#section-4.1>`_ has + timed out. + + +.. cfgcmd:: set protocols igmp interface <interface> version <version-number> + + Use this command to define in the selected interface whether you + choose IGMP version 2 or 3. The default value is 3. + + + +********** +IGMP Proxy +********** + +:abbr:`IGMP (Internet Group Management Protocol)` proxy sends IGMP host messages +on behalf of a connected client. The configuration must define one, and only one +upstream interface, and one or more downstream interfaces. + +Configuration +============= + +.. cfgcmd:: set protocols igmp-proxy interface <interface> role + <upstream | downstream> + + * **upstream:** The upstream network interface is the outgoing interface + which is responsible for communicating to available multicast data sources. + There can only be one upstream interface. + + * **downstream:** Downstream network interfaces are the distribution + interfaces to the destination networks, where multicast clients can join + groups and receive multicast data. One or more downstream interfaces must + be configured. + +.. cfgcmd:: set protocols igmp-proxy interface <interface> alt-subnet <network> + + Defines alternate sources for multicasting and IGMP data. The network address + must be on the following format 'a.b.c.d/n'. By default the router will + accept data from sources on the same network as configured on an interface. + If the multicast source lies on a remote network, one must define from where + traffic should be accepted. + + This is especially useful for the upstream interface, since the source for + multicast traffic is often from a remote location. + + This option can be supplied multiple times. + +.. cfgcmd:: set protocols igmp-proxy disable-quickleave + + Disables quickleave mode. In this mode the daemon will not send a Leave IGMP + message upstream as soon as it receives a Leave message for any downstream + interface. The daemon will not ask for Membership reports on the downstream + interfaces, and if a report is received the group is not joined again + upstream. + + If it's vital that the daemon should act exactly as a real multicast client + on the upstream interface, this function should be enabled. + + Enabling this function increases the risk of bandwidth saturation. + +.. cfgcmd:: set protocols igmp-proxy disable + + Disable this service. + +Example +------- + +Interface `eth1` LAN is behind NAT. In order to subscribe `10.0.0.0/23` subnet +multicast which is in `eth0` WAN we need to configure igmp-proxy. + +.. code-block:: none + + set protocols igmp-proxy interface eth0 role upstream + set protocols igmp-proxy interface eth0 alt-subnet 10.0.0.0/23 + set protocols igmp-proxy interface eth1 role downstream + +Operation +========= + +.. opcmd:: restart igmp-proxy + + Restart the IGMP proxy process. + + + diff --git a/docs/configuration/protocols/index.rst b/docs/configuration/protocols/index.rst new file mode 100644 index 00000000..c302d6a9 --- /dev/null +++ b/docs/configuration/protocols/index.rst @@ -0,0 +1,18 @@ +######### +Protocols +######### + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + bfd + bgp + igmp + isis + mpls + ospf + rip + rpki + static diff --git a/docs/configuration/protocols/isis.rst b/docs/configuration/protocols/isis.rst new file mode 100644 index 00000000..05a851f1 --- /dev/null +++ b/docs/configuration/protocols/isis.rst @@ -0,0 +1,305 @@ +.. include:: /_include/need_improvement.txt + +.. _isis: + +##### +IS-IS +##### + +:abbr:`IS-IS (Intermediate System to Intermediate System)` is a link-state +interior gateway routing protocol which is described in ISO10589, +:rfc:`1195`, :rfc:`5308`. Like OSPF, IS-IS runs the Dijkstra shortest-path +first (SPF) algorithm to create a database of the network’s topology and, +from that database, to determine the best (that is, shortest) path to a +destination. The routers exchange topology information with their nearest +neighbors. IS-IS runs directly on the data link layer (Layer 2). IS-IS +addresses are called :abbr:`NETs (Network Entity Titles)` and can be +8 to 20 bytes long, but are generally 10 bytes long. + +For example :abbr:`NET (Network Entity Title)` + +.. code-block:: none + + 49.0001.1921.6800.1002.00 + +The IS-IS address consists of three parts: + + :abbr:`AFI (Address family authority identifier)` + ``49`` The AFI value 49 is what IS-IS uses for private addressing. + + Area identifier: + ``0001`` IS-IS area number (Area1) + + System identifier: + ``1921.6800.1002`` For system idetifier we recommend to use IP address or + MAC address of the router. + + NET selector: + ``00`` Must always be 00, to indicate "this system". + + +General Configuration +--------------------- + +.. cfgcmd:: set protocols isis <name> net <network-entity-title> + + This command enables the ISIS process by specifying the ISIS domain with + ‘name’. ISIS implementation does not yet support multiple ISIS processes + but you must specify the name of ISIS process. This commad also sets + network entity title (NET) provided in ISO format. + +.. cfgcmd:: set protocols isis <name> interface <interface> + + This command activates ISIS adjacency on this interface. Note that the name + of ISIS instance must be the same as the one used to configure the ISIS + process. + +.. cfgcmd:: set protocols isis <name> dynamic-hostname + + This command enables support for dynamic hostname. Dynamic hostname mapping + determined as described in :rfc:`2763`, Dynamic Hostname Exchange Mechanism + for IS-IS. + +.. cfgcmd:: set protocols isis <name> level <level-1|level-1-2|level-2> + + This command defines the ISIS router behavior: + + **level-1** Act as a station router only. + **level-1-2** Act as both a station router and an area router. + **level-2-only** Act as an area router only. + +.. cfgcmd:: set protocols isis <name> lsp-mtu <size> + + This command configures the maximum size of generated LSPs, in bytes. The + size range is 128 to 4352. + +.. cfgcmd:: set protocols isis <name> metric-style <narrow|transition|wide> + + This command sets old-style (ISO 10589) or new-style packet formats: + + **narrow** Use old style of TLVs with narrow metric. + **transition** Send and accept both styles of TLVs during transition. + **wide** Use new style of TLVs to carry wider metric. + +.. cfgcmd:: set protocols isis <name> purge-originator + + This command enables :rfc:`6232` purge originator identification. Enable + purge originator identification (POI) by adding the type, length and value + (TLV) with the Intermediate System (IS) identification to the LSPs that do + not contain POI information. If an IS generates a purge, VyOS adds this TLV + with the system ID of the IS to the purge. + +.. cfgcmd:: set protocols isis <name> set-attached-bit + + This command sets ATT bit to 1 in Level1 LSPs. It is described in :rfc:`3787`. + +.. cfgcmd:: set protocols isis <name> set-overload-bit + + This command sets overload bit to avoid any transit traffic through this + router. It is described in :rfc:`3787`. + +.. cfgcmd:: set protocols isis name default-information originate <ipv4|ipv6> + level-1 + + This command will generate a default-route in L1 database. + +.. cfgcmd:: set protocols isis name default-information originate <ipv4|ipv6> + level-2 + + This command will generate a default-route in L2 database. + + +Interfaces Configuration +------------------------ + +.. cfgcmd:: set protocols isis <name> interface <interface> circuit-type + <level-1|level-1-2|level-2-only> + + This command specifies circuit type for interface: + + **level-1** Level-1 only adjacencies are formed. + **level-1-2** Level-1-2 adjacencies are formed + **level-2-only** Level-2 only adjacencies are formed + +.. cfgcmd:: set protocols isis <name> interface <interface> hello-interval + <seconds> + + This command sets hello interval in seconds on a given interface. + The range is 1 to 600. + +.. cfgcmd:: set protocols isis <name> interface <interface> hello-multiplier + <seconds> + + This command sets multiplier for hello holding time on a given + interface. The range is 2 to 100. + +.. cfgcmd:: set protocols isis <name> interface <interface> hello-padding + + This command configures padding on hello packets to accommodate asymmetrical + maximum transfer units (MTUs) from different hosts as described in + :rfc:`3719`. This helps to prevent a premature adjacency Up state when one + routing device’s MTU does not meet the requirements to establish the + adjacency. + +.. cfgcmd:: set protocols isis <name> interface <interface> metric <metric> + + This command set default metric for circuit. The metric range is 1 to + 16777215 (Max value depend if metric support narrow or wide value). + +.. cfgcmd:: set protocols isis <name> interface <interface> network + point-to-point + + This command specifies network type to ‘Point-to-Point’. The default network + type is broadcast. + +.. cfgcmd:: set protocols isis <name> interface <interface> passive + + This command configures the passive mode for this interface. + +.. cfgcmd:: set protocols isis <name> interface <interface> password + plaintext-password <text> + + This command configures the authentication password for the interface. + +.. cfgcmd:: set protocols isis <name> interface <interface> priority <number> + + This command sets priority for the interface for + :abbr:`DIS (Designated Intermediate System)` election. The priority + range is 0 to 127. + +.. cfgcmd:: set protocols isis <name> interface <interface> psnp-interval + <number> + + This command sets PSNP interval in seconds. The interval range is 0 + to 127. + +.. cfgcmd:: set protocols isis <name> interface <interface> + no-three-way-handshake + + This command disables Three-Way Handshake for P2P adjacencies which + described in :rfc:`5303`. Three-Way Handshake is enabled by default. + + +Redistribution Configuration +---------------------------- + +.. cfgcmd:: set protocols isis <name> redistribute ipv4 <route source> level-1 + + This command redistributes routing information from the given route source + into the ISIS database as Level-1. There are six modes available for route + source: bgp, connected, kernel, ospf, rip, static. + +.. cfgcmd:: set protocols isis <name> redistribute ipv4 <route source> level-2 + + This command redistributes routing information from the given route source + into the ISIS database as Level-2. There are six modes available for route + source: bgp, connected, kernel, ospf, rip, static. + +.. cfgcmd:: set protocols isis <name> redistribute ipv4 <route source> + <level-1|level-2> metric <number> + + This command specifies metric for redistributed routes from the given route + source. There are six modes available for route source: bgp, connected, + kernel, ospf, rip, static. The metric range is 1 to 16777215. + +.. cfgcmd:: set protocols isis <name> redistribute ipv4 <route source> + <level-1|level-2> route-map <name> + + This command allows to use route map to filter redistributed routes from + the given route source. There are six modes available for route source: + bgp, connected, kernel, ospf, rip, static. + + +Timers Configuration +-------------------- + +.. cfgcmd:: set protocols isis <name> lsp-gen-interval <seconds> + + This command sets minimum interval in seconds between regenerating same + LSP. The interval range is 1 to 120. + +.. cfgcmd:: set protocols isis <name> lsp-refresh-interval <seconds> + + This command sets LSP refresh interval in seconds. IS-IS generates LSPs + when the state of a link changes. However, to ensure that routing + databases on all routers remain converged, LSPs in stable networks are + generated on a regular basis even though there has been no change to + the state of the links. The interval range is 1 to 65235. The default + value is 900 seconds. + +.. cfgcmd:: set protocols isis <name> max-lsp-lifetime <seconds> + + This command sets LSP maximum LSP lifetime in seconds. The interval range + is 350 to 65535. LSPs remain in a database for 1200 seconds by default. + If they are not refreshed by that time, they are deleted. You can change + the LSP refresh interval or the LSP lifetime. The LSP refresh interval + should be less than the LSP lifetime or else LSPs will time out before + they are refreshed. + +.. cfgcmd:: set protocols isis <name> spf-interval <seconds> + + This command sets minimum interval between consecutive SPF calculations in + seconds.The interval range is 1 to 120. + +.. cfgcmd:: set protocols isis <name> spf-delay-ietf holddown <milliseconds> + +.. cfgcmd:: set protocols isis <name> spf-delay-ietf init-delay + <milliseconds> + +.. cfgcmd:: set protocols isis <name> spf-delay-ietf long-delay + <milliseconds> + +.. cfgcmd:: set protocols isis <name> spf-delay-ietf short-delay + <milliseconds> + +.. cfgcmd:: set protocols isis <name> spf-delay-ietf time-to-learn + <milliseconds> + + This commands specifies the Finite State Machine (FSM) intended to + control the timing of the execution of SPF calculations in response + to IGP events. The process described in :rfc:`8405`. + + +Configuration Example +--------------------- + +Simple IS-IS configuration using 2 nodes and redistributing connected +interfaces. + +**Node 1:** + +.. code-block:: none + + set interfaces dummy dum0 address '203.0.113.1/24' + set interfaces ethernet eth1 address '192.0.2.1/24' + + set policy prefix-list EXPORT-ISIS rule 10 action 'permit' + set policy prefix-list EXPORT-ISIS rule 10 prefix '203.0.113.0/24' + set policy route-map EXPORT-ISIS rule 10 action 'permit' + set policy route-map EXPORT-ISIS rule 10 match ip address prefix-list 'EXPORT-ISIS' + + set protocols isis FOO interface eth1 + set protocols isis FOO net '49.0001.1921.6800.1002.00' + set protocols isis FOO redistribute ipv4 connected level-2 route-map 'EXPORT-ISIS' + +**Node 2:** + +.. code-block:: none + + set interfaces ethernet eth1 address '192.0.2.2/24' + + set protocols isis FOO interface eth1 + set protocols isis FOO net '49.0001.1921.6800.2002.00' + +Show ip routes on Node2: + +.. code-block:: none + + vyos@r2:~$ show ip route isis + Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued route, r - rejected route + + I 203.0.113.0/24 [115/10] via 192.0.2.1, eth1, 00:03:42 diff --git a/docs/configuration/protocols/mpls.rst b/docs/configuration/protocols/mpls.rst new file mode 100644 index 00000000..312a0df2 --- /dev/null +++ b/docs/configuration/protocols/mpls.rst @@ -0,0 +1,253 @@ +.. _mpls: + +#### +MPLS +#### + +:abbr:`MPLS (Multi-Protocol Label Switching)` is a packet forwarding paradigm +which differs from regular IP forwarding. Instead of IP addresses being used to +make the decision on finding the exit interface, a router will instead use an +exact match on a 32 bit/4 byte header called the MPLS label. This label is +inserted between the ethernet (layer 2) header and the IP (layer 3) header. +One can statically or dynamically assign label allocations, but we will focus +on dynamic allocation of labels using some sort of label distribution protocol +(such as the aptly named Label Distribution Protocol / LDP, Resource Reservation +Protocol / RSVP, or Segment Routing through OSPF/ISIS). These protocols allow +for the creation of a unidirectional/unicast path called a labeled switched +path (initialized as LSP) throughout the network that operates very much like +a tunnel through the network. An easy way of thinking about how an MPLS LSP +actually forwards traffic throughout a network is to think of a GRE tunnel. +They are not the same in how they operate, but they are the same in how they +handle the tunneled packet. It would be good to think of MPLS as a tunneling +technology that can be used to transport many different types of packets, to +aid in traffic engineering by allowing one to specify paths throughout the +network (using RSVP or SR), and to generally allow for easier intra/inter +network transport of data packets. + +For more information on how MPLS label switching works, please go visit +`Wikipedia (MPLS)`_. + +.. note:: MPLS support in VyOS is not finished yet, and therefore its + functionality is limited. Currently there is no support for MPLS enabled VPN + services such as L3VPNs, L2VPNs, and mVPNs. RSVP support is also not present + as the underlying routing stack (FRR) does not implement it. Currently VyOS + can be configured as a label switched router (MPLS P router), in both + penultimate and ultimate hop popping operations. + +Label Distribution Protocol +=========================== + +The :abbr:`MPLS (Multi-Protocol Label Switching)` architecture does not assume +a single protocol to create MPLS paths. VyOS supports the Label Distribution +Protocol (LDP) as implemented by FRR, based on :rfc:`5036`. + +:abbr:`LDP (Label Distribution Protocol)` is a TCP based MPLS signaling protocol +that distributes labels creating MPLS label switched paths in a dynamic manner. +LDP is not a routing protocol, as it relies on other routing protocols for +forwarding decisions. LDP cannot bootstrap itself, and therefore relies on said +routing protocols for communication with other routers that use LDP. + +In order to allow for LDP on the local router to exchange label advertisements +with other routers, a TCP session will be established between automatically +discovered and statically assigned routers. LDP will try to establish a TCP +session to the **transport address** of other routers. Therefore for LDP to +function properly please make sure the transport address is shown in the +routing table and reachable to traffic at all times. + +It is highly recommended to use the same address for both the LDP router-id and +the discovery transport address, but for VyOS MPLS LDP to work both parameters +must be explicitly set in the configuration. + +Another thing to keep in mind with LDP is that much like BGP, it is a protocol +that runs on top of TCP. It however does not have an ability to do something +like a refresh capability like BGPs route refresh capability. Therefore one +might have to reset the neighbor for a capability change or a configuration +change to work. + +Configuration Options +===================== + +.. cfgcmd:: set protocols mpls ldp interface <interface> + + Use this command to enable LDP, and enable MPLS processing on the interface + you define. + +.. cfgcmd:: set protocols mpls ldp router-id <address> + + Use this command to configure the IP address used as the LDP router-id of the + local device. + +.. cfgcmd:: set protocols mpls ldp discovery transport-ipv4-address <address> +.. cfgcmd:: set protocols mpls ldp discovery transport-ipv6-address <address> + + Use this command to set the IPv4 or IPv6 transport-address used by LDP. + +.. cfgcmd:: set protocols mpls ldp neighbor <address> password <password> + + Use this command to configure authentication for LDP peers. Set the + IP address of the LDP peer and a password that should be shared in + order to become neighbors. + +.. cfgcmd:: set protocols mpls ldp neighbor <address> session-holdtime <seconds> + + Use this command to configure a specific session hold time for LDP peers. + Set the IP address of the LDP peer and a session hold time that should be + configured for it. You may have to reset the neighbor for this to work. + +.. cfgcmd:: set protocols mpls ldp neighbor <address> ttl-security + <disable | hop count> + + Use this command to enable, disable, or specify hop count for TTL security + for LDP peers. By default the value is set to 255 (or max TTL). + +.. cfgcmd:: set protocols mpls ldp discovery hello-ipv4-interval <seconds> +.. cfgcmd:: set protocols mpls ldp discovery hello-ipv4-holdtime <seconds> +.. cfgcmd:: set protocols mpls ldp discovery hello-ipv6-interval <seconds> +.. cfgcmd:: set protocols mpls ldp discovery hello-ipv6-holdtime <seconds> + + Use these commands if you would like to set the discovery hello and hold time + parameters. + +.. cfgcmd:: set protocols mpls ldp discovery session-ipv4-holdtime <seconds> +.. cfgcmd:: set protocols mpls ldp discovery session-ipv6-holdtime <seconds> + + Use this command if you would like to set the TCP session hold time intervals. + +.. cfgcmd:: set protocols mpls ldp import ipv4 import-filter filter-access-list + <access list number> +.. cfgcmd:: set protocols mpls ldp import ipv6 import-filter filter-access-list6 + <access list number> + + Use these commands to control the importing of forwarding equivalence classes + (FECs) for LDP from neighbors. This would be useful for example on only + accepting the labeled routes that are needed and not ones that are not + needed, such as accepting loopback interfaces and rejecting all others. + +.. cfgcmd:: set protocols mpls ldp export ipv4 export-filter filter-access-list + <access list number> +.. cfgcmd:: set protocols mpls ldp export ipv6 export-filter filter-access-list6 + <access list number> + + Use these commands to control the exporting of forwarding equivalence classes + (FECs) for LDP to neighbors. This would be useful for example on only + announcing the labeled routes that are needed and not ones that are not + needed, such as announcing loopback interfaces and no others. + +.. cfgcmd:: set protocols mpls ldp export ipv4 explicit-null +.. cfgcmd:: set protocols mpls ldp export ipv6 explicit-null + + Use this command if you would like for the router to advertise FECs with a + label of 0 for explicit null operations. + +.. cfgcmd:: set protocols mpls ldp allocation ipv4 access-list + <access list number> +.. cfgcmd:: set protocols mpls ldp allocation ipv6 access-list6 + <access list number> + + Use this command if you would like to control the local FEC allocations for + LDP. A good example would be for your local router to not allocate a label for + everything. Just a label for what it's useful. A good example would be just a + loopback label. + +.. cfgcmd:: set protocols mpls ldp parameters cisco-interop-tlv + + Use this command to use a Cisco non-compliant format to send and interpret + the Dual-Stack capability TLV for IPv6 LDP communications. This is related to + :rfc:`7552`. + +.. cfgcmd:: set protocols mpls ldp parameters ordered-control + + Use this command to use ordered label distribution control mode. FRR + by default uses independent label distribution control mode for label + distribution. This is related to :rfc:`5036`. + +.. cfgcmd:: set protocols mpls ldp parameters transport-prefer-ipv4 + + Use this command to prefer IPv4 for TCP peer transport connection for LDP + when both an IPv4 and IPv6 LDP address are configured on the same interface. + +.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv4 enable +.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv6 enable + + Use this command to enable targeted LDP sessions to the local router. The + router will then respond to any sessions that are trying to connect to it that + are not a link local type of TCP connection. + +.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv4 address <address> +.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv6 address <address> + + Use this command to enable the local router to try and connect with a targeted + LDP session to another router. + +.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv4 hello-holdtime + <seconds> +.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv4 hello-interval + <seconds> +.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv6 hello-holdtime + <seconds> +.. cfgcmd:: set protocols mpls ldp targeted-neighbor ipv6 hello-interval + <seconds> + + Use these commands if you would like to set the discovery hello and hold time + parameters for the targeted LDP neighbors. + + +Sample configuration to setup LDP on VyOS +----------------------------------------- + +.. code-block:: none + + set protocols ospf area 0 network '192.168.255.252/32' <--- Routing for loopback + set protocols ospf area 0 network '192.168.0.5/32' <--- Routing for an interface connecting to the network + set protocols ospf parameters router-id '192.168.255.252' <--- Router ID setting for OSPF + set protocols mpls ldp discovery transport-ipv4-address '192.168.255.252' <--- Transport address for LDP for TCP sessions to connect to + set protocols mpls ldp interface 'eth1' <--- Enable MPLS and LDP for an interface connecting to network + set protocols mpls ldp interface 'lo' <--- Enable MPLS and LDP on loopback for future services connectivity + set protocols mpls ldp router-id '192.168.255.252' <--- Router ID setting for LDP + set interfaces ethernet eth1 address '192.168.0.5/31' <--- Interface IP for connecting to network + set interfaces loopback lo address '192.168.255.252/32' <--- Interface loopback IP for router ID and other uses + + +Operational Mode Commands +========================= + +When LDP is working, you will be able to see label information in the outcome +of ``show ip route``. Besides that information, there are also specific *show* +commands for LDP: + +Show +---- + +.. opcmd:: show mpls ldp binding + + Use this command to see the Label Information Base. + +.. opcmd:: show mpls ldp discovery + + Use this command to see discovery hello information + +.. opcmd:: show mpls ldp interface + + Use this command to see LDP interface information + +.. opcmd:: show mpls ldp neighbor + + Use this command to see LDP neighbor information + +.. opcmd:: show mpls ldp neighbor detail + + Use this command to see detailed LDP neighbor information + +Reset +----- + +.. opcmd:: reset mpls ldp neighbor <IPv4 or IPv6 address> + + Use this command to reset an LDP neighbor/TCP session that is established + + +.. stop_vyoslinter + +.. _`Wikipedia (MPLS)`: https://en.wikipedia.org/wiki/Multiprotocol_Label_Switching + +.. start_vyoslinter
\ No newline at end of file diff --git a/docs/configuration/protocols/ospf.rst b/docs/configuration/protocols/ospf.rst new file mode 100644 index 00000000..e1957cec --- /dev/null +++ b/docs/configuration/protocols/ospf.rst @@ -0,0 +1,1019 @@ +.. _routing-ospf: + +#### +OSPF +#### + +:abbr:`OSPF (Open Shortest Path First)` is a routing protocol for Internet +Protocol (IP) networks. It uses a link state routing (LSR) algorithm and falls +into the group of interior gateway protocols (IGPs), operating within a single +autonomous system (AS). It is defined as OSPF Version 2 in :rfc:`2328` (1998) +for IPv4. Updates for IPv6 are specified as OSPF Version 3 in :rfc:`5340` +(2008). OSPF supports the :abbr:`CIDR (Classless Inter-Domain Routing)` +addressing model. + +OSPF is a widely used IGP in large enterprise networks. + +************* +OSPFv2 (IPv4) +************* + +Configuration +============= + +General +------- + +VyOS does not have a special command to start the OSPF process. The OSPF process +starts when the first ospf enabled interface is configured. + +.. cfgcmd:: set protocols ospf area <number> network <A.B.C.D/M> + + This command specifies the OSPF enabled interface(s). If the interface has + an address from defined range then the command enables OSPF on this + interface so router can provide network information to the other ospf + routers via this interface. + + This command is also used to enable the OSPF process. The area number can be + specified in decimal notation in the range from 0 to 4294967295. Or it + can be specified in dotted decimal notation similar to ip address. + +.. cfgcmd:: set protocols ospf auto-cost reference-bandwidth <number> + + This command sets the reference bandwidth for cost calculations, where + bandwidth can be in range from 1 to 4294967, specified in Mbits/s. The + default is 100Mbit/s (i.e. a link of bandwidth 100Mbit/s or higher will + have a cost of 1. Cost of lower bandwidth links will be scaled with + reference to this cost). + +.. cfgcmd:: set protocols ospf parameters router-id <rid> + + This command sets the router-ID of the OSPF process. The router-ID may be an + IP address of the router, but need not be – it can be any arbitrary 32bit + number. However it MUST be unique within the entire OSPF domain to the OSPF + speaker – bad things will happen if multiple OSPF speakers are configured + with the same router-ID! + + +Optional +-------- + +.. cfgcmd:: set protocols ospf default-information originate [always] + [metric <number>] [metric-type <1|2>] [route-map <name>] + + Originate an AS-External (type-5) LSA describing a default route into all + external-routing capable areas, of the specified metric and metric type. + If the :cfgcmd:`always` keyword is given then the default is always + advertised, even when there is no default present in the routing table. + The argument :cfgcmd:`route-map` specifies to advertise the default route + if the route map is satisfied. + +.. cfgcmd:: set protocols ospf distance global <distance> + + This command change distance value of OSPF globally. + The distance range is 1 to 255. + +.. cfgcmd:: set protocols ospf distance ospf <external|inter-area|intra-area> + <distance> + + This command change distance value of OSPF. The arguments are the distance + values for external routes, inter-area routes and intra-area routes + respectively. The distance range is 1 to 255. + + .. note:: Routes with a distance of 255 are effectively disabled and not + installed into the kernel. + +.. cfgcmd:: set protocols ospf log-adjacency-changes [detail] + + This command allows to log changes in adjacency. With the optional + :cfgcmd:`detail` argument, all changes in adjacency status are shown. + Without :cfgcmd:`detail`, only changes to full or regressions are shown. + +.. cfgcmd:: set protocols ospf max-metric router-lsa + <administrative|on-shutdown <seconds>|on-startup <seconds>> + + This enables :rfc:`3137` support, where the OSPF process describes its + transit links in its router-LSA as having infinite distance so that other + routers will avoid calculating transit paths through the router while + still being able to reach networks through the router. + + This support may be enabled administratively (and indefinitely) with the + :cfgcmd:`administrative` command. It may also be enabled conditionally. + Conditional enabling of max-metric router-lsas can be for a period of + seconds after startup with the :cfgcmd:`on-startup <seconds>` command + and/or for a period of seconds prior to shutdown with the + :cfgcmd:`on-shutdown <seconds>` command. The time range is 5 to 86400. + +.. cfgcmd:: set protocols ospf parameters abr-type + <cisco|ibm|shortcut|standard> + + This command selects ABR model. OSPF router supports four ABR models: + + **cisco** – a router will be considered as ABR if it has several configured + links to the networks in different areas one of which is a backbone area. + Moreover, the link to the backbone area should be active (working). + **ibm** – identical to "cisco" model but in this case a backbone area link + may not be active. + **standard** – router has several active links to different areas. + **shortcut** – identical to "standard" but in this model a router is + allowed to use a connected areas topology without involving a backbone + area for inter-area connections. + + Detailed information about "cisco" and "ibm" models differences can be + found in :rfc:`3509`. A "shortcut" model allows ABR to create routes + between areas based on the topology of the areas connected to this router + but not using a backbone area in case if non-backbone route will be + cheaper. For more information about "shortcut" model, + see :t:`ospf-shortcut-abr-02.txt` + +.. cfgcmd:: set protocols ospf parameters rfc1583-compatibility + + :rfc:`2328`, the successor to :rfc:`1583`, suggests according to section + G.2 (changes) in section 16.4.1 a change to the path preference algorithm + that prevents possible routing loops that were possible in the old version + of OSPFv2. More specifically it demands that inter-area paths and + intra-area backbone path are now of equal preference but still both + preferred to external paths. + + This command should NOT be set normally. + +.. cfgcmd:: set protocols ospf passive-interface <interface> + + This command specifies interface as passive. Passive interface advertises + its address, but does not run the OSPF protocol (adjacencies are not formed + and hello packets are not generated). + +.. cfgcmd:: set protocols ospf passive-interface default + + This command specifies all interfaces as passive by default. Because this + command changes the configuration logic to a default passive; therefore, + interfaces where router adjacencies are expected need to be configured + with the :cfgcmd:`passive-interface-exclude` command. + +.. cfgcmd:: set protocols ospf passive-interface-exclude <interface> + + This command allows exclude interface from passive state. This command is + used if the command :cfgcmd:`passive-interface default` was configured. + +.. cfgcmd:: set protocols ospf refresh timers <seconds> + + The router automatically updates link-state information with its neighbors. + Only an obsolete information is updated which age has exceeded a specific + threshold. This parameter changes a threshold value, which by default is + 1800 seconds (half an hour). The value is applied to the whole OSPF router. + The timer range is 10 to 1800. + +.. cfgcmd:: set protocols ospf timers throttle spf + <delay|initial-holdtime|max-holdtime> <seconds> + + This command sets the initial delay, the initial-holdtime and the + maximum-holdtime between when SPF is calculated and the event which + triggered the calculation. The times are specified in milliseconds and must + be in the range of 0 to 600000 milliseconds. :cfgcmd:`delay` sets the + initial SPF schedule delay in milliseconds. The default value is 200 ms. + :cfgcmd:`initial-holdtime` sets the minimum hold time between two + consecutive SPF calculations. The default value is 1000 ms. + :cfgcmd:`max-holdtime` sets the maximum wait time between two + consecutive SPF calculations. The default value is 10000 ms. + + +Area Configuration +------------------ + +.. cfgcmd:: set protocols ospf area <number> area-type stub + + This command specifies the area to be a Stub Area. That is, an area where + no router originates routes external to OSPF and hence an area where all + external routes are via the ABR(s). Hence, ABRs for such an area do not + need to pass AS-External LSAs (type-5) or ASBR-Summary LSAs (type-4) into + the area. They need only pass Network-Summary (type-3) LSAs into such an + area, along with a default-route summary. + +.. cfgcmd:: set protocols ospf area <number> area-type stub no-summary + + This command specifies the area to be a Totally Stub Area. In addition to + stub area limitations this area type prevents an ABR from injecting + Network-Summary (type-3) LSAs into the specified stub area. Only default + summary route is allowed. + +.. cfgcmd:: set protocols ospf area <number> area-type stub default-cost + <number> + + This command sets the cost of default-summary LSAs announced to stubby + areas. The cost range is 0 to 16777215. + +.. cfgcmd:: set protocols ospf area <number> area-type nssa + + This command specifies the area to be a Not So Stubby Area. External + routing information is imported into an NSSA in Type-7 LSAs. Type-7 LSAs + are similar to Type-5 AS-external LSAs, except that they can only be + flooded into the NSSA. In order to further propagate the NSSA external + information, the Type-7 LSA must be translated to a Type-5 AS-external-LSA + by the NSSA ABR. + +.. cfgcmd:: set protocols ospf area <number> area-type nssa no-summary + + This command specifies the area to be a NSSA Totally Stub Area. ABRs for + such an area do not need to pass Network-Summary (type-3) LSAs (except the + default summary route), ASBR-Summary LSAs (type-4) and AS-External LSAs + (type-5) into the area. But Type-7 LSAs that convert to Type-5 at the NSSA + ABR are allowed. + +.. cfgcmd:: set protocols ospf area <number> area-type nssa default-cost + <number> + + This command sets the default cost of LSAs announced to NSSA areas. + The cost range is 0 to 16777215. + +.. cfgcmd:: set protocols ospf area <number> area-type nssa translate + <always|candidate|never> + + Specifies whether this NSSA border router will unconditionally translate + Type-7 LSAs into Type-5 LSAs. When role is Always, Type-7 LSAs are + translated into Type-5 LSAs regardless of the translator state of other + NSSA border routers. When role is Candidate, this router participates in + the translator election to determine if it will perform the translations + duties. When role is Never, this router will never translate Type-7 LSAs + into Type-5 LSAs. + +.. cfgcmd:: set protocols ospf area <number> authentication plaintext-password + + This command specifies that simple password authentication should be used + for the given area. The password must also be configured on a per-interface + basis. + +.. cfgcmd:: set protocols ospf area <number> authentication md5 + + This command specify that OSPF packets must be authenticated with MD5 HMACs + within the given area. Keying material must also be configured on a + per-interface basis. + +.. cfgcmd:: set protocols ospf area <number> range <A.B.C.D/M> [cost <number>] + + This command summarizes intra area paths from specified area into one + summary-LSA (Type-3) announced to other areas. This command can be used + only in ABR and ONLY router-LSAs (Type-1) and network-LSAs (Type-2) + (i.e. LSAs with scope area) can be summarized. AS-external-LSAs (Type-5) + can’t be summarized - their scope is AS. The optional argument + :cfgcmd:`cost` specifies the aggregated link metric. The metric range is 0 + to 16777215. + +.. cfgcmd:: set protocols ospf area <number> range <A.B.C.D/M> not-advertise + + This command instead of summarizing intra area paths filter them - i.e. + intra area paths from this range are not advertised into other areas. + This command makes sense in ABR only. + +.. cfgcmd:: set protocols ospf area <number> range <A.B.C.D/M> substitute + <E.F.G.H/M> + + One Type-3 summary-LSA with routing info <E.F.G.H/M> is announced into + backbone area if defined area contains at least one intra-area network + (i.e. described with router-LSA or network-LSA) from range <A.B.C.D/M>. + This command makes sense in ABR only. + +.. cfgcmd:: set protocols ospf area <number> shortcut <default|disable|enable> + + This parameter allows to "shortcut" routes (non-backbone) for inter-area + routes. There are three modes available for routes shortcutting: + + **default** – this area will be used for shortcutting only if ABR does not + have a link to the backbone area or this link was lost. + **enable** – the area will be used for shortcutting every time the route + that goes through it is cheaper. + **disable** – this area is never used by ABR for routes shortcutting. + +.. cfgcmd:: set protocols ospf area <number> virtual-link <A.B.C.D> + + Provides a backbone area coherence by virtual link establishment. + + In general, OSPF protocol requires a backbone area (area 0) to be coherent + and fully connected. I.e. any backbone area router must have a route to any + other backbone area router. Moreover, every ABR must have a link to + backbone area. However, it is not always possible to have a physical link + to a backbone area. In this case between two ABR (one of them has a link to + the backbone area) in the area (not stub area) a virtual link is organized. + + <number> – area identifier through which a virtual link goes. + <A.B.C.D> – ABR router-id with which a virtual link is established. Virtual + link must be configured on both routers. + + Formally, a virtual link looks like a point-to-point network connecting two + ABR from one area one of which physically connected to a backbone area. + This pseudo-network is considered to belong to a backbone area. + + +Interface Configuration +----------------------- + +.. cfgcmd:: set protocols ospf interface <interface> authentication + plaintext-password <text> + + This command sets OSPF authentication key to a simple password. After + setting, all OSPF packets are authenticated. Key has length up to 8 chars. + + Simple text password authentication is insecure and deprecated in favour of + MD5 HMAC authentication. + +.. cfgcmd:: set protocols ospf interface <interface> authentication md5 + key-id <id> md5-key <text> + + This command specifys that MD5 HMAC authentication must be used on this + interface. It sets OSPF authentication key to a cryptographic password. + Key-id identifies secret key used to create the message digest. This ID + is part of the protocol and must be consistent across routers on a link. + The key can be long up to 16 chars (larger strings will be truncated), + and is associated with the given key-id. + +.. cfgcmd:: set protocols ospf interface <interface> bandwidth <number> + + This command sets the interface bandwidth for cost calculations, where + bandwidth can be in range from 1 to 100000, specified in Mbits/s. + +.. cfgcmd:: set protocols ospf interface <interface> cost <number> + + This command sets link cost for the specified interface. The cost value is + set to router-LSA’s metric field and used for SPF calculation. The cost + range is 1 to 65535. + +.. cfgcmd:: set protocols ospf interface <interface> dead-interval <number> + + Set number of seconds for router Dead Interval timer value used for Wait + Timer and Inactivity Timer. This value must be the same for all routers + attached to a common network. The default value is 40 seconds. The + interval range is 1 to 65535. + +.. cfgcmd:: set protocols ospf interface <interface> hello-multiplier <number> + + The hello-multiplier specifies how many Hellos to send per second, from 1 + (every second) to 10 (every 100ms). Thus one can have 1s convergence time + for OSPF. If this form is specified, then the hello-interval advertised in + Hello packets is set to 0 and the hello-interval on received Hello packets + is not checked, thus the hello-multiplier need NOT be the same across + multiple routers on a common link. + +.. cfgcmd:: set protocols ospf interface <interface> hello-interval <number> + + Set number of seconds for Hello Interval timer value. Setting this value, + Hello packet will be sent every timer value seconds on the specified + interface. This value must be the same for all routers attached to a + common network. The default value is 10 seconds. The interval range is 1 + to 65535. + +.. cfgcmd:: set protocols ospf interface <interface> bfd + + This command enables :abbr:`BFD (Bidirectional Forwarding Detection)` on + this OSPF link interface. + +.. cfgcmd:: set protocols ospf interface <interface> mtu-ignore + + This command disables check of the MTU value in the OSPF DBD packets. Thus, + use of this command allows the OSPF adjacency to reach the FULL state even + though there is an interface MTU mismatch between two OSPF routers. + +.. cfgcmd:: set protocols ospf interface <interface> network <type> + + This command allows to specify the distribution type for the network + connected to this interface: + + **broadcast** – broadcast IP addresses distribution. + **non-broadcast** – address distribution in NBMA networks topology. + **point-to-multipoint** – address distribution in point-to-multipoint + networks. + **point-to-point** – address distribution in point-to-point networks. + +.. cfgcmd:: set protocols ospf interface <interface> priority <number> + + This command sets Router Priority integer value. The router with the + highest priority will be more eligible to become Designated Router. + Setting the value to 0, makes the router ineligible to become + Designated Router. The default value is 1. The interval range is 0 to 255. + +.. cfgcmd:: set protocols ospf interface <interface> retransmit-interval + <number> + + This command sets number of seconds for RxmtInterval timer value. This + value is used when retransmitting Database Description and Link State + Request packets if acknowledge was not received. The default value is 5 + seconds. The interval range is 3 to 65535. + +.. cfgcmd:: set protocols ospf interface <interface> transmit-delay <number> + + This command sets number of seconds for InfTransDelay value. It allows to + set and adjust for each interface the delay interval before starting the + synchronizing process of the router's database with all neighbors. The + default value is 1 seconds. The interval range is 3 to 65535. + + +Manual Neighbor Configuration +----------------------------- + +OSPF routing devices normally discover their neighbors dynamically by +listening to the broadcast or multicast hello packets on the network. +Because an NBMA network does not support broadcast (or multicast), the +device cannot discover its neighbors dynamically, so you must configure all +the neighbors statically. + +.. cfgcmd:: set protocols ospf neighbor <A.B.C.D> + + This command specifies the IP address of the neighboring device. + +.. cfgcmd:: set protocols ospf neighbor <A.B.C.D> poll-interval <seconds> + + This command specifies the length of time, in seconds, before the routing + device sends hello packets out of the interface before it establishes + adjacency with a neighbor. The range is 1 to 65535 seconds. The default + value is 60 seconds. + +.. cfgcmd:: set protocols ospf neighbor <A.B.C.D> priority <number> + + This command specifies the router priority value of the nonbroadcast + neighbor associated with the IP address specified. The default is 0. + This keyword does not apply to point-to-multipoint interfaces. + + +Redistribution Configuration +---------------------------- + +.. cfgcmd:: set protocols ospf redistribute <route source> + + This command redistributes routing information from the given route source + to the OSPF process. There are five modes available for route source: bgp, + connected, kernel, rip, static. + +.. cfgcmd:: set protocols ospf default-metric <number> + + This command specifies the default metric value of redistributed routes. + The metric range is 0 to 16777214. + +.. cfgcmd:: set protocols ospf redistribute <route source> metric <number> + + This command specifies metric for redistributed routes from the given + route source. There are five modes available for route source: bgp, + connected, kernel, rip, static. The metric range is 1 to 16777214. + +.. cfgcmd:: set protocols ospf redistribute <route source> metric-type <1|2> + + This command specifies metric type for redistributed routes. Difference + between two metric types that metric type 1 is a metric which is + "commensurable" with inner OSPF links. When calculating a metric to the + external destination, the full path metric is calculated as a metric sum + path of a router which had advertised this link plus the link metric. + Thus, a route with the least summary metric will be selected. If external + link is advertised with metric type 2 the path is selected which lies + through the router which advertised this link with the least metric + despite of the fact that internal path to this router is longer (with more + cost). However, if two routers advertised an external link and with metric + type 2 the preference is given to the path which lies through the router + with a shorter internal path. If two different routers advertised two + links to the same external destimation but with different metric type, + metric type 1 is preferred. If type of a metric left undefined the router + will consider these external links to have a default metric type 2. + +.. cfgcmd:: set protocols ospf redistribute <route source> route-map <name> + + This command allows to use route map to filter redistributed routes from + the given route source. There are five modes available for route source: + bgp, connected, kernel, rip, static. + + +Operational Mode Commands +------------------------- + +.. opcmd:: show ip ospf neighbor + + This command displays the neighbors status. + +.. code-block:: none + + Neighbor ID Pri State Dead Time Address Interface RXmtL RqstL DBsmL + 10.0.13.1 1 Full/DR 38.365s 10.0.13.1 eth0:10.0.13.3 0 0 0 + 10.0.23.2 1 Full/Backup 39.175s 10.0.23.2 eth1:10.0.23.3 0 0 0 + +.. opcmd:: show ip ospf neighbor detail + + This command displays the neighbors information in a detailed form, not + just a summary table. + +.. code-block:: none + + Neighbor 10.0.13.1, interface address 10.0.13.1 + In the area 0.0.0.0 via interface eth0 + Neighbor priority is 1, State is Full, 5 state changes + Most recent state change statistics: + Progressive change 11m55s ago + DR is 10.0.13.1, BDR is 10.0.13.3 + Options 2 *|-|-|-|-|-|E|- + Dead timer due in 34.854s + Database Summary List 0 + Link State Request List 0 + Link State Retransmission List 0 + Thread Inactivity Timer on + Thread Database Description Retransmision off + Thread Link State Request Retransmission on + Thread Link State Update Retransmission on + + Neighbor 10.0.23.2, interface address 10.0.23.2 + In the area 0.0.0.1 via interface eth1 + Neighbor priority is 1, State is Full, 4 state changes + Most recent state change statistics: + Progressive change 41.193s ago + DR is 10.0.23.3, BDR is 10.0.23.2 + Options 2 *|-|-|-|-|-|E|- + Dead timer due in 35.661s + Database Summary List 0 + Link State Request List 0 + Link State Retransmission List 0 + Thread Inactivity Timer on + Thread Database Description Retransmision off + Thread Link State Request Retransmission on + Thread Link State Update Retransmission on + +.. opcmd:: show ip ospf neighbor <A.B.C.D> + + This command displays the neighbors information in a detailed form for a + neighbor whose IP address is specified. + +.. opcmd:: show ip ospf neighbor <intname> + + This command displays the neighbors status for a neighbor on the specified + interface. + +.. opcmd:: show ip ospf interface [<intname>] + + This command displays state and configuration of OSPF the specified + interface, or all interfaces if no interface is given. + +.. code-block:: none + + eth0 is up + ifindex 2, MTU 1500 bytes, BW 4294967295 Mbit <UP,BROADCAST,RUNNING,MULTICAST> + Internet Address 10.0.13.3/24, Broadcast 10.0.13.255, Area 0.0.0.0 + MTU mismatch detection: enabled + Router ID 10.0.23.3, Network Type BROADCAST, Cost: 1 + Transmit Delay is 1 sec, State Backup, Priority 1 + Backup Designated Router (ID) 10.0.23.3, Interface Address 10.0.13.3 + Multicast group memberships: OSPFAllRouters OSPFDesignatedRouters + Timer intervals configured, Hello 10s, Dead 40s, Wait 40s, Retransmit 5 + Hello due in 4.470s + Neighbor Count is 1, Adjacent neighbor count is 1 + eth1 is up + ifindex 3, MTU 1500 bytes, BW 4294967295 Mbit <UP,BROADCAST,RUNNING,MULTICAST> + Internet Address 10.0.23.3/24, Broadcast 10.0.23.255, Area 0.0.0.1 + MTU mismatch detection: enabled + Router ID 10.0.23.3, Network Type BROADCAST, Cost: 1 + Transmit Delay is 1 sec, State DR, Priority 1 + Backup Designated Router (ID) 10.0.23.2, Interface Address 10.0.23.2 + Saved Network-LSA sequence number 0x80000002 + Multicast group memberships: OSPFAllRouters OSPFDesignatedRouters + Timer intervals configured, Hello 10s, Dead 40s, Wait 40s, Retransmit 5 + Hello due in 4.563s + Neighbor Count is 1, Adjacent neighbor count is 1 + +.. opcmd:: show ip ospf route + + This command displays the OSPF routing table, as determined by the most + recent SPF calculation. + +.. code-block:: none + + ============ OSPF network routing table ============ + N IA 10.0.12.0/24 [3] area: 0.0.0.0 + via 10.0.13.3, eth0 + N 10.0.13.0/24 [1] area: 0.0.0.0 + directly attached to eth0 + N IA 10.0.23.0/24 [2] area: 0.0.0.0 + via 10.0.13.3, eth0 + N 10.0.34.0/24 [2] area: 0.0.0.0 + via 10.0.13.3, eth0 + + ============ OSPF router routing table ============= + R 10.0.23.3 [1] area: 0.0.0.0, ABR + via 10.0.13.3, eth0 + R 10.0.34.4 [2] area: 0.0.0.0, ASBR + via 10.0.13.3, eth0 + + ============ OSPF external routing table =========== + N E2 172.16.0.0/24 [2/20] tag: 0 + via 10.0.13.3, eth0 + +The table consists of following data: + +**OSPF network routing table** – includes a list of acquired routes for all +accessible networks (or aggregated area ranges) of OSPF system. "IA" flag +means that route destination is in the area to which the router is not +connected, i.e. it’s an inter-area path. In square brackets a summary metric +for all links through which a path lies to this network is specified. "via" +prefix defines a router-gateway, i.e. the first router on the way to the +destination (next hop). +**OSPF router routing table** – includes a list of acquired routes to all +accessible ABRs and ASBRs. +**OSPF external routing table** – includes a list of acquired routes that are +external to the OSPF process. "E" flag points to the external link metric type +(E1 – metric type 1, E2 – metric type 2). External link metric is printed in +the "<metric of the router which advertised the link>/<link metric>" format. + +.. opcmd:: show ip ospf border-routers + + This command displays a table of paths to area boundary and autonomous + system boundary routers. + +.. opcmd:: show ip ospf database + + This command displays a summary table with a database contents (LSA). + +.. code-block:: none + + OSPF Router with ID (10.0.13.1) + + Router Link States (Area 0.0.0.0) + + Link ID ADV Router Age Seq# CkSum Link count + 10.0.13.1 10.0.13.1 984 0x80000005 0xd915 1 + 10.0.23.3 10.0.23.3 1186 0x80000008 0xfe62 2 + 10.0.34.4 10.0.34.4 1063 0x80000004 0x4e3f 1 + + Net Link States (Area 0.0.0.0) + + Link ID ADV Router Age Seq# CkSum + 10.0.13.1 10.0.13.1 994 0x80000003 0x30bb + 10.0.34.4 10.0.34.4 1188 0x80000001 0x9411 + + Summary Link States (Area 0.0.0.0) + + Link ID ADV Router Age Seq# CkSum Route + 10.0.12.0 10.0.23.3 1608 0x80000001 0x6ab6 10.0.12.0/24 + 10.0.23.0 10.0.23.3 981 0x80000003 0xe232 10.0.23.0/24 + + AS External Link States + + Link ID ADV Router Age Seq# CkSum Route + 172.16.0.0 10.0.34.4 1063 0x80000001 0xc40d E2 172.16.0.0/24 [0x0] + +.. opcmd:: show ip ospf database <type> [A.B.C.D] + [adv-router <A.B.C.D>|self-originate] + + This command displays a database contents for a specific link advertisement + type. + + The type can be the following: + asbr-summary, external, network, nssa-external, opaque-area, opaque-as, + opaque-link, router, summary. + + [A.B.C.D] – link-state-id. With this specified the command displays portion + of the network environment that is being described by the advertisement. + The value entered depends on the advertisement’s LS type. It must be + entered in the form of an IP address. + + :cfgcmd:`adv-router <A.B.C.D>` – router id, which link advertisements need + to be reviewed. + + :cfgcmd:`self-originate` displays only self-originated LSAs from the local + router. + +.. code-block:: none + + OSPF Router with ID (10.0.13.1) + + Router Link States (Area 0.0.0.0) + + LS age: 1213 + Options: 0x2 : *|-|-|-|-|-|E|- + LS Flags: 0x3 + Flags: 0x0 + LS Type: router-LSA + Link State ID: 10.0.13.1 + Advertising Router: 10.0.13.1 + LS Seq Number: 80000009 + Checksum: 0xd119 + Length: 36 + + Number of Links: 1 + + Link connected to: a Transit Network + (Link ID) Designated Router address: 10.0.13.1 + (Link Data) Router Interface address: 10.0.13.1 + Number of TOS metrics: 0 + TOS 0 Metric: 1 + +.. opcmd:: show ip ospf database max-age + + This command displays LSAs in MaxAge list. + + +Configuration Example +--------------------- + +Below you can see a typical configuration using 2 nodes, redistribute loopback +address and the node 1 sending the default route: + +**Node 1** + +.. code-block:: none + + set interfaces loopback lo address 10.1.1.1/32 + set protocols ospf area 0 network 192.168.0.0/24 + set protocols ospf default-information originate always + set protocols ospf default-information originate metric 10 + set protocols ospf default-information originate metric-type 2 + set protocols ospf log-adjacency-changes + set protocols ospf parameters router-id 10.1.1.1 + set protocols ospf redistribute connected metric-type 2 + set protocols ospf redistribute connected route-map CONNECT + + set policy route-map CONNECT rule 10 action permit + set policy route-map CONNECT rule 10 match interface lo + +**Node 2** + +.. code-block:: none + + set interfaces loopback lo address 10.2.2.2/32 + set protocols ospf area 0 network 192.168.0.0/24 + set protocols ospf log-adjacency-changes + set protocols ospf parameters router-id 10.2.2.2 + set protocols ospf redistribute connected metric-type 2 + set protocols ospf redistribute connected route-map CONNECT + + set policy route-map CONNECT rule 10 action permit + set policy route-map CONNECT rule 10 match interface lo + + +************* +OSPFv3 (IPv6) +************* + +Configuration +============= + +General +------- + +VyOS does not have a special command to start the OSPFv3 process. The OSPFv3 +process starts when the first ospf enabled interface is configured. + +.. cfgcmd:: set protocols ospfv3 area <number> interface <interface> + + This command specifies the OSPFv3 enabled interface. This command is also + used to enable the OSPF process. The area number can be specified in + decimal notation in the range from 0 to 4294967295. Or it can be specified + in dotted decimal notation similar to ip address. + +.. cfgcmd:: set protocols ospfv3 parameters router-id <rid> + + This command sets the router-ID of the OSPFv3 process. The router-ID may be + an IP address of the router, but need not be – it can be any arbitrary + 32bit number. However it MUST be unique within the entire OSPFv3 domain to + the OSPFv3 speaker – bad things will happen if multiple OSPFv3 speakers are + configured with the same router-ID! + + +Optional +-------- + +.. cfgcmd:: set protocols ospfv3 distance global <distance> + + This command change distance value of OSPFv3 globally. + The distance range is 1 to 255. + +.. cfgcmd:: set protocols ospfv3 distance ospfv3 + <external|inter-area|intra-area> <distance> + + This command change distance value of OSPFv3. The arguments are the + distance values for external routes, inter-area routes and intra-area + routes respectively. The distance range is 1 to 255. + + +Area Configuration +------------------ + +.. cfgcmd:: set protocols ospfv3 area <number> range <prefix> + + This command summarizes intra area paths from specified area into one + Type-3 Inter-Area Prefix LSA announced to other areas. This command can be + used only in ABR. + +.. cfgcmd:: set protocols ospfv3 area <number> range <prefix> not-advertise + + This command instead of summarizing intra area paths filter them - i.e. + intra area paths from this range are not advertised into other areas. This + command makes sense in ABR only. + + +Interface Configuration +----------------------- + +.. cfgcmd:: set interfaces <inttype> <intname> ipv6 ospfv3 cost <number> + + This command sets link cost for the specified interface. The cost value is + set to router-LSA’s metric field and used for SPF calculation. The cost + range is 1 to 65535. + +.. cfgcmd:: set interfaces <inttype> <intname> ipv6 ospfv3 dead-interval + <number> + + Set number of seconds for router Dead Interval timer value used for Wait + Timer and Inactivity Timer. This value must be the same for all routers + attached to a common network. The default value is 40 seconds. The + interval range is 1 to 65535. + +.. cfgcmd:: set interfaces <inttype> <intname> ipv6 ospfv3 hello-interval + <number> + + Set number of seconds for Hello Interval timer value. Setting this value, + Hello packet will be sent every timer value seconds on the specified + interface. This value must be the same for all routers attached to a + common network. The default value is 10 seconds. The interval range is 1 + to 65535. + +.. cfgcmd:: set interfaces <inttype> <intname> ipv6 ospfv3 mtu-ignore + + This command disables check of the MTU value in the OSPF DBD packets. + Thus, use of this command allows the OSPF adjacency to reach the FULL + state even though there is an interface MTU mismatch between two OSPF + routers. + +.. cfgcmd:: set interfaces <inttype> <intname> ipv6 ospfv3 network <type> + + This command allows to specify the distribution type for the network + connected to this interface: + + **broadcast** – broadcast IP addresses distribution. + **point-to-point** – address distribution in point-to-point networks. + +.. cfgcmd:: set interfaces <inttype> <intname> ipv6 ospfv3 priority <number> + + This command sets Router Priority integer value. The router with the + highest priority will be more eligible to become Designated Router. + Setting the value to 0, makes the router ineligible to become Designated + Router. The default value is 1. The interval range is 0 to 255. + +.. cfgcmd:: set interfaces <inttype> <intname> ipv6 ospfv3 passive + + This command specifies interface as passive. Passive interface advertises + its address, but does not run the OSPF protocol (adjacencies are not formed + and hello packets are not generated). + +.. cfgcmd:: set interfaces <inttype> <intname> ipv6 ospfv3 retransmit-interval + <number> + + This command sets number of seconds for RxmtInterval timer value. This + value is used when retransmitting Database Description and Link State + Request packets if acknowledge was not received. The default value is 5 + seconds. The interval range is 3 to 65535. + +.. cfgcmd:: set interfaces <inttype> <intname> ipv6 ospfv3 transmit-delay + <number> + + This command sets number of seconds for InfTransDelay value. It allows to + set and adjust for each interface the delay interval before starting the + synchronizing process of the router's database with all neighbors. The + default value is 1 seconds. The interval range is 3 to 65535. + + +Redistribution Configuration +---------------------------- + +.. cfgcmd:: set protocols ospfv3 redistribute <route source> + + This command redistributes routing information from the given route source + to the OSPFv3 process. There are five modes available for route source: + bgp, connected, kernel, ripng, static. + +.. cfgcmd:: set protocols ospf redistribute <route source> route-map <name> + + This command allows to use route map to filter redistributed routes from + given route source. There are five modes available for route source: bgp, + connected, kernel, ripng, static. + + +Operational Mode Commands +------------------------- + +.. opcmd:: show ipv6 ospfv3 neighbor + + This command displays the neighbors status. + +.. opcmd:: show ipv6 ospfv3 neighbor detail + + This command displays the neighbors information in a detailed form, not + just a summary table. + +.. opcmd:: show ipv6 ospfv3 neighbor <A.B.C.D> + + This command displays the neighbors information in a detailed form for + a neighbor whose IP address is specified. + +.. opcmd:: show ipv6 ospfv3 neighbor <intname> + + This command displays the neighbors status for a neighbor on the specified + interface. + +.. opcmd:: show ipv6 ospfv3 interface [prefix]|[<intname> [prefix]] + + This command displays state and configuration of OSPF the specified + interface, or all interfaces if no interface is given. Whith the argument + :cfgcmd:`prefix` this command shows connected prefixes to advertise. + +.. opcmd:: show ipv6 ospfv3 route + + This command displays the OSPF routing table, as determined by the most + recent SPF calculation. + +.. opcmd:: show ipv6 ospfv3 border-routers + + This command displays a table of paths to area boundary and autonomous + system boundary routers. + +.. opcmd:: show ipv6 ospfv3 database + + This command displays a summary table with a database contents (LSA). + +.. opcmd:: show ipv6 ospfv3 database <type> [A.B.C.D] + [adv-router <A.B.C.D>|self-originate] + + This command displays a database contents for a specific link + advertisement type. + +.. opcmd:: show ipv6 ospfv3 redistribute + + This command displays external information redistributed into OSPFv3 + + +Configuration Example +--------------------- + +A typical configuration using 2 nodes. + +**Node 1:** + +.. code-block:: none + + set protocols ospfv3 area 0.0.0.0 interface eth1 + set protocols ospfv3 area 0.0.0.0 range 2001:db8:1::/64 + set protocols ospfv3 parameters router-id 192.168.1.1 + set protocols ospfv3 redistribute connected + +**Node 2:** + +.. code-block:: none + + set protocols ospfv3 area 0.0.0.0 interface eth1 + set protocols ospfv3 area 0.0.0.0 range 2001:db8:2::/64 + set protocols ospfv3 parameters router-id 192.168.2.1 + set protocols ospfv3 redistribute connected + +**To see the redistributed routes:** + +.. code-block:: none + + show ipv6 ospfv3 redistribute + +.. note:: You cannot easily redistribute IPv6 routes via OSPFv3 on a + WireGuard interface link. This requires you to configure link-local + addresses manually on the WireGuard interfaces, see :vytask:`T1483`. + +Example configuration for WireGuard interfaces: + +**Node 1** + +.. code-block:: none + + set interfaces wireguard wg01 address 'fe80::216:3eff:fe51:fd8c/64' + set interfaces wireguard wg01 address '192.168.0.1/24' + set interfaces wireguard wg01 peer ospf02 allowed-ips '::/0' + set interfaces wireguard wg01 peer ospf02 allowed-ips '0.0.0.0/0' + set interfaces wireguard wg01 peer ospf02 endpoint '10.1.1.101:12345' + set interfaces wireguard wg01 peer ospf02 pubkey 'ie3...=' + set interfaces wireguard wg01 port '12345' + set protocols ospfv3 parameters router-id 192.168.1.1 + set protocols ospfv3 area 0.0.0.0 interface 'wg01' + set protocols ospfv3 area 0.0.0.0 interface 'lo' + +**Node 2** + +.. code-block:: none + + set interfaces wireguard wg01 address 'fe80::216:3eff:fe0a:7ada/64' + set interfaces wireguard wg01 address '192.168.0.2/24' + set interfaces wireguard wg01 peer ospf01 allowed-ips '::/0' + set interfaces wireguard wg01 peer ospf01 allowed-ips '0.0.0.0/0' + set interfaces wireguard wg01 peer ospf01 endpoint '10.1.1.100:12345' + set interfaces wireguard wg01 peer ospf01 pubkey 'NHI...=' + set interfaces wireguard wg01 port '12345' + set protocols ospfv3 parameters router-id 192.168.1.2 + set protocols ospfv3 area 0.0.0.0 interface 'wg01' + set protocols ospfv3 area 0.0.0.0 interface 'lo' + +**Status** + +.. code-block:: none + + vyos@ospf01:~$ sh ipv6 ospfv3 neighbor + Neighbor ID Pri DeadTime State/IfState Duration I/F[State] + 192.168.0.2 1 00:00:37 Full/PointToPoint 00:18:03 wg01[PointToPoint] + + vyos@ospf02# run sh ipv6 ospfv3 neighbor + Neighbor ID Pri DeadTime State/IfState Duration I/F[State] + 192.168.0.1 1 00:00:39 Full/PointToPoint 00:19:44 wg01[PointToPoint] + diff --git a/docs/configuration/protocols/pim.disable b/docs/configuration/protocols/pim.disable new file mode 100644 index 00000000..1dd373d8 --- /dev/null +++ b/docs/configuration/protocols/pim.disable @@ -0,0 +1,2 @@ +PIM +###
\ No newline at end of file diff --git a/docs/configuration/protocols/rip.rst b/docs/configuration/protocols/rip.rst new file mode 100644 index 00000000..4d46e2f0 --- /dev/null +++ b/docs/configuration/protocols/rip.rst @@ -0,0 +1,255 @@ +.. _rip: + +### +RIP +### + +:abbr:`RIP (Routing Information Protocol)` is a widely deployed interior gateway +protocol. RIP was developed in the 1970s at Xerox Labs as part of the XNS +routing protocol. RIP is a distance-vector protocol and is based on the +Bellman-Ford algorithms. As a distance-vector protocol, RIP router send updates +to its neighbors periodically, thus allowing the convergence to a known +topology. In each update, the distance to any given network will be broadcast +to its neighboring router. + +Supported versions of RIP are: + + - RIPv1 as described in :rfc:`1058` + - RIPv2 as described in :rfc:`2453` + +General Configuration +--------------------- + +.. cfgcmd:: set protocols rip network <A.B.C.D/M> + + This command enables RIP and sets the RIP enable interface by NETWORK. + The interfaces which have addresses matching with NETWORK are enabled. + +.. cfgcmd:: set protocols rip interface <interface> + + This command specifies a RIP enabled interface by interface name. Both + the sending and receiving of RIP packets will be enabled on the port + specified in this command. + +.. cfgcmd:: set protocols rip neighbor <A.B.C.D> + + This command specifies a RIP neighbor. When a neighbor doesn’t understand + multicast, this command is used to specify neighbors. In some cases, not + all routers will be able to understand multicasting, where packets are + sent to a network or a group of addresses. In a situation where a neighbor + cannot process multicast packets, it is necessary to establish a direct + link between routers. + +.. cfgcmd:: set protocols rip passive-interface interface <interface> + + This command sets the specified interface to passive mode. On passive mode + interface, all receiving packets are processed as normal and VyOS does not + send either multicast or unicast RIP packets except to RIP neighbors + specified with neighbor command. + +.. cfgcmd:: set protocols rip passive-interface interface default + + This command specifies all interfaces to passive mode. + + +Optional Configuration +---------------------- + +.. cfgcmd:: set protocols rip default-distance <distance> + + This command change distance value of RIP. The distance range is 1 to 255. + + .. note:: Routes with a distance of 255 are effectively disabled and not + installed into the kernel. + +.. cfgcmd:: set protocols rip network-distance <A.B.C.D/M> distance <distance> + + This command sets default RIP distance to specified value when the route’s + source IP address matches the specified prefix. + +.. cfgcmd:: set protocols rip network-distance <A.B.C.D/M> access-list <name> + + This command can be used with previous command to sets default RIP distance + to specified value when the route’s source IP address matches the specified + prefix and the specified access-list. + +.. cfgcmd:: set protocols rip default-information originate + + This command generate a default route into the RIP. + +.. cfgcmd:: set protocols rip distribute-list access-list <in|out> <number> + + This command can be used to filter the RIP path using access lists. + :cfgcmd:`in` and :cfgcmd:`out` this is the direction in which the access + lists are applied. + +.. cfgcmd:: set protocols rip distribute-list interface <interface> access-list <in|out> <number> + + This command allows you apply access lists to a chosen interface to + filter the RIP path. + +.. cfgcmd:: set protocols rip distribute-list prefix-list <in|out> <name> + + This command can be used to filter the RIP path using prefix lists. + :cfgcmd:`in` and :cfgcmd:`out` this is the direction in which the prefix + lists are applied. + +.. cfgcmd:: set protocols rip distribute-list interface <interface> prefix-list <in|out> <name> + + This command allows you apply prefix lists to a chosen interface to + filter the RIP path. + +.. cfgcmd:: set protocols rip route <A.B.C.D/M> + + This command is specific to FRR and VyOS. The route command makes a static + route only inside RIP. This command should be used only by advanced users + who are particularly knowledgeable about the RIP protocol. In most cases, + we recommend creating a static route in VyOS and redistributing it in RIP + using :cfgcmd:`redistribute static`. + +.. cfgcmd:: set protocols rip timers update <seconds> + + This command specifies the update timer. Every update timer seconds, the + RIP process is awakened to send an unsolicited response message containing + the complete routing table to all neighboring RIP routers. The time range + is 5 to 2147483647. The default value is 30 seconds. + +.. cfgcmd:: set protocols rip timers timeout <seconds> + + This command specifies the timeout timer. Upon expiration of the timeout, + the route is no longer valid; however, it is retained in the routing table + for a short time so that neighbors can be notified that the route has been + dropped. The time range is 5 to 2147483647. The default value is 180 + seconds. + +.. cfgcmd:: set protocols rip timers garbage-collection <seconds> + + This command specifies the garbage-collection timer. Upon expiration of + the garbage-collection timer, the route is finally removed from the + routing table. The time range is 5 to 2147483647. The default value is 120 + seconds. + + +Redistribution Configuration +---------------------------- + +.. cfgcmd:: set protocols rip redistribute <route source> + + This command redistributes routing information from the given route source + into the RIP tables. There are five modes available for route source: bgp, + connected, kernel, ospf, static. + +.. cfgcmd:: set protocols rip redistribute <route source> metric <metric> + + This command specifies metric for redistributed routes from the given route + source. There are five modes available for route source: bgp, connected, + kernel, ospf, static. The metric range is 1 to 16. + +.. cfgcmd:: set protocols rip redistribute <route source> route-map <name> + + This command allows to use route map to filter redistributed routes from + the given route source. There are five modes available for route source: + bgp, connected, kernel, ospf, static. + +.. cfgcmd:: set protocols rip default-metric <metric> + + This command modifies the default metric (hop count) value for redistributed + routes. The metric range is 1 to 16. The default value is 1. This command + does not affect connected route even if it is redistributed by + :cfgcmd:`redistribute connected`. To modify connected route’s metric + value, please use :cfgcmd:`redistribute connected metric`. + + +Interfaces Configuration +------------------------ + +.. cfgcmd:: set interfaces <inttype> <intname> ip rip authentication plaintext-password <text> + + This command sets the interface with RIP simple password authentication. + This command also sets authentication string. The string must be shorter + than 16 characters. + +.. cfgcmd:: set interfaces <inttype> <intname> ip rip authentication md5 <id> password <text> + + This command sets the interface with RIP MD5 authentication. This command + also sets MD5 Key. The key must be shorter than 16 characters. + +.. cfgcmd:: set interfaces <inttype> <intname> ip rip split-horizon disable + + This command disables split-horizon on the interface. By default, VyOS does + not advertise RIP routes out the interface over which they were learned + (split horizon). + +.. cfgcmd:: set interfaces <inttype> <intname> ip rip split-horizon poison-reverse + + This command enables poison-reverse on the interface. If both poison reverse + and split horizon are enabled, then VyOS advertises the learned routes + as unreachable over the interface on which the route was learned. + + +Operational Mode Commands +------------------------- + +.. opcmd:: show ip rip + + This command displays RIP routes. + +.. code-block:: none + + Codes: R - RIP, C - connected, S - Static, O - OSPF, B - BGP + Sub-codes: + (n) - normal, (s) - static, (d) - default, (r) - redistribute, + (i) - interface + + Network Next Hop Metric From Tag Time + C(i) 10.0.12.0/24 0.0.0.0 1 self 0 + C(i) 10.0.13.0/24 0.0.0.0 1 self 0 + R(n) 10.0.23.0/24 10.0.12.2 2 10.0.12.2 0 02:53 + +.. opcmd:: show ip rip status + + The command displays current RIP status. It includes RIP timer, filtering, + version, RIP enabled interface and RIP peer information. + +.. code-block:: none + + Routing Protocol is "rip" + Sending updates every 30 seconds with +/-50%, next due in 11 seconds + Timeout after 180 seconds, garbage collect after 120 seconds + Outgoing update filter list for all interface is not set + Incoming update filter list for all interface is not set + Default redistribution metric is 1 + Redistributing: + Default version control: send version 2, receive any version + Interface Send Recv Key-chain + eth0 2 1 2 + eth2 2 1 2 + Routing for Networks: + 10.0.12.0/24 + eth0 + Routing Information Sources: + Gateway BadPackets BadRoutes Distance Last Update + 10.0.12.2 0 0 120 00:00:11 + Distance: (default is 120) + + +Configuration Example +--------------------- + +Simple RIP configuration using 2 nodes and redistributing connected interfaces. + +**Node 1:** + +.. code-block:: none + + set interfaces loopback address 10.1.1.1/32 + set protocols rip network 192.168.0.0/24 + set protocols rip redistribute connected + +**Node 2:** + +.. code-block:: none + + set interfaces loopback address 10.2.2.2/32 + set protocols rip network 192.168.0.0/24 + set protocols rip redistribute connected diff --git a/docs/configuration/protocols/ripng.disable b/docs/configuration/protocols/ripng.disable new file mode 100644 index 00000000..dec6bddf --- /dev/null +++ b/docs/configuration/protocols/ripng.disable @@ -0,0 +1,3 @@ +##### +RIPng +#####
\ No newline at end of file diff --git a/docs/configuration/protocols/rpki.rst b/docs/configuration/protocols/rpki.rst new file mode 100644 index 00000000..d9884296 --- /dev/null +++ b/docs/configuration/protocols/rpki.rst @@ -0,0 +1,202 @@ +.. _rpki: + +#### +RPKI +#### + +.. pull-quote:: + + There are two types of Network Admins who deal with BGP, those who have + created an international incident and/or outage, and those who are lying + + -- `tweet by EvilMog`_, 2020-02-21 + +:abbr:`RPKI (Resource Public Key Infrastructure)` is a framework :abbr:`PKI +(Public Key Infrastructure)` designed to secure the Internet routing +infrastructure. It associates BGP route announcements with the correct +originating :abbr:`ASN (Autonomus System Number)` which BGP routers can then +use to check each route against the corresponding :abbr:`ROA (Route Origin +Authorisation)` for validity. RPKI is described in :rfc:`6480`. + +A BGP-speaking router like VyOS can retrieve ROA information from RPKI +"Relying Party software" (often just called an "RPKI server" or "RPKI +validator") by using :abbr:`RTR (RPKI to Router)` protocol. There are several +open source implementations to choose from, such as NLNetLabs' Routinator_ +(written in Rust), Cloudflare's GoRTR_ and OctoRPKI_ (written in Go), and +RIPE NCC's RPKI Validator_ (written in Java). The RTR protocol is described +in :rfc:`8210`. + +.. tip:: + If you are new to these routing security technologies then there is an + `excellent guide to RPKI`_ by NLnet Labs which will get you up to speed + very quickly. Their documentation explains everything from what RPKI is to + deploying it in production (albeit with a focus on using NLnet Labs' + tools). It also has some `help and operational guidance`_ including + "What can I do about my route having an Invalid state?" + +*************** +Getting started +*************** + +First you will need to deploy an RPKI validator for your routers to use. The +RIPE NCC helpfully provide `some instructions`_ to get you started with +several different options. Once your server is running you can start +validating announcements. + +Imported prefixes during the validation may have values: + + valid + The prefix and ASN that originated it match a signed ROA. These are + probably trustworthy route announcements. + + invalid + The prefix or prefix length and ASN that originated it doesn't + match any existing ROA. This could be the result of a prefix hijack, or + merely a misconfiguration, but should probably be treated as + untrustworthy route announcements. + + notfound + No ROA exists which covers that prefix. Unfortunately this is the case + for about 80% of the IPv4 prefixes which were announced to the :abbr:`DFZ + (default-free zone)` at the start of 2020 (see more detail in + NLnet Labs' `RPKI analytics`_). + +.. note:: + If you are responsible for the global addresses assigned to your + network, please make sure that your prefixes have ROAs associated with them + to avoid being `notfound` by RPKI. For most ASNs this will involve + publishing ROAs via your :abbr:`RIR (Regional Internet Registry)` (RIPE + NCC, APNIC, ARIN, LACNIC or AFRINIC), and is something you are encouraged + to do whenever you plan to announce addresses into the DFZ. + + Particularly large networks may wish to run their own RPKI certificate + authority and publication server instead of publishing ROAs via their RIR. + This is a subject far beyond the scope of VyOS' documentation. Consider + reading about Krill_ if this is a rabbit hole you need or especially want + to dive down. + +Features of the Current Implementation +====================================== + +In a nutshell, the current implementation provides the following features: + +* The BGP router can connect to one or more RPKI cache servers to receive + validated prefix to origin AS mappings. Advanced failover can be implemented + by server sockets with different preference values. + +* If no connection to an RPKI cache server can be established after a + pre-defined timeout, the router will process routes without prefix origin + validation. It still will try to establish a connection to an RPKI cache + server in the background. + +* By default, enabling RPKI does not change best path selection. In particular, + invalid prefixes will still be considered during best path selection. However, + the router can be configured to ignore all invalid prefixes. + +* Route maps can be configured to match a specific RPKI validation state. This + allows the creation of local policies, which handle BGP routes based on the + outcome of the Prefix Origin Validation. + +* Updates from the RPKI cache servers are directly applied and path selection is + updated accordingly. (Soft reconfiguration must be enabled for this to work). + +************* +Configuration +************* + +.. cfgcmd:: protocols rpki polling-period <1-86400> + + Define the time interval to update the local cache + + The default value is 300 seconds. + +.. cfgcmd:: protocols rpki cache <address> port <port> + + Defined the IPv4, IPv6 or FQDN and port number of the caching RPKI caching + instance which is used. + + This is a mandatory setting. + +.. cfgcmd:: protocols rpki cache <address> preference <preference> + + Multiple RPKI caching instances can be supplied and they need a preference in + which their result sets are used. + + This is a mandatory setting. + +SSH +=== + +Connections to the RPKI caching server can not only be established by HTTP/TLS +but you can also rely on a secure SSH session to the server. To enable SSH you +first need to create yoursels an SSH client keypair using ``generate ssh +client-key /config/auth/id_rsa_rpki``. Once your key is created you can setup +the connection. + +.. cfgcmd:: protocols rpki cache <address> ssh username <user> + + SSH username to establish an SSH connection to the cache server. + +.. cfgcmd:: protocols rpki cache <address> ssh known-hosts-file <filepath> + + Local path that includes the known hosts file. + +.. cfgcmd:: protocols rpki cache <address> ssh private-key-file <filepath> + + Local path that includes the private key file of the router. + +.. cfgcmd:: protocols rpki cache <address> ssh public-key-file <filepath + + Local path that includes the public key file of the router. + +.. note:: When using SSH, known-hosts-file, private-key-file and public-key-file + are mandatory options. + +******* +Example +******* + +We can build route-maps for import based on these states. Here is a simple +RPKI configuration, where `routinator` is the RPKI-validating "cache" +server with ip `192.0.2.1`: + +.. code-block:: none + + set protocols rpki cache 192.0.2.1 port '3323' + set protocols rpki cache 192.0.2.1 preference '1' + +Here is an example route-map to apply to routes learned at import. In this +filter we reject prefixes with the state `invalid`, and set a higher +`local-preference` if the prefix is RPKI `valid` rather than merely +`notfound`. + +.. code-block:: none + + set policy route-map ROUTES-IN rule 10 action 'permit' + set policy route-map ROUTES-IN rule 10 match rpki 'valid' + set policy route-map ROUTES-IN rule 10 set local-preference '300' + set policy route-map ROUTES-IN rule 20 action 'permit' + set policy route-map ROUTES-IN rule 20 match rpki 'notfound' + set policy route-map ROUTES-IN rule 20 set local-preference '125' + set policy route-map ROUTES-IN rule 30 action 'deny' + set policy route-map ROUTES-IN rule 30 match rpki 'invalid' + +Once your routers are configured to reject RPKI-invalid prefixes, you can +test whether the configuration is working correctly using the `RIPE Labs RPKI +Test`_ experimental tool. + +.. stop_vyoslinter + +.. _tweet by EvilMog: https://twitter.com/Evil_Mog/status/1230924170508169216 +.. _Routinator: https://www.nlnetlabs.nl/projects/rpki/routinator/ +.. _GoRTR: https://github.com/cloudflare/gortr +.. _OctoRPKI: https://github.com/cloudflare/cfrpki#octorpki +.. _Validator: https://www.ripe.net/manage-ips-and-asns/resource-management/certification/tools-and-resources +.. _some instructions: https://labs.ripe.net/Members/tashi_phuntsho_3/how-to-install-an-rpki-validator +.. _Krill: https://www.nlnetlabs.nl/projects/rpki/krill/ +.. _RPKI analytics: https://www.nlnetlabs.nl/projects/rpki/rpki-analytics/ +.. _RIPE Labs RPKI Test: https://sg-pub.ripe.net/jasper/rpki-web-test/ +.. _excellent guide to RPKI: https://rpki.readthedocs.io/ +.. _help and operational guidance: https://rpki.readthedocs.io/en/latest/about/help.htm + +.. start_vyoslinter diff --git a/docs/configuration/protocols/static.rst b/docs/configuration/protocols/static.rst new file mode 100644 index 00000000..723db727 --- /dev/null +++ b/docs/configuration/protocols/static.rst @@ -0,0 +1,208 @@ +.. _static-routing: + +###### +Static +###### + +Static routes are manually configured routes, which, in general, cannot be +updated dynamically from information VyOS learns about the network topology from +other routing protocols. However, if a link fails, the router will remove +routes, including static routes, from the :abbr:`RIPB (Routing Information +Base)` that used this interface to reach the next hop. In general, static +routes should only be used for very simple network topologies, or to override +the behavior of a dynamic routing protocol for a small number of routes. The +collection of all routes the router has learned from its configuration or from +its dynamic routing protocols is stored in the RIB. Unicast routes are directly +used to determine the forwarding table used for unicast packet forwarding. + +************* +Static Routes +************* + +.. cfgcmd:: set protocols static route <subnet> next-hop <address> + + Configure next-hop `<address>` for an IPv4 static route. Multiple static + routes can be created. + +.. cfgcmd:: set protocols static route <subnet> next-hop <address> disable + + Disable this IPv4 static route entry. + +.. cfgcmd:: set protocols static route <subnet> next-hop <address> + distance <distance> + + Defines next-hop distance for this route, routes with smaller administrative + distance are elected prior those with a higher distance. + + Range is 1 to 255, default is 1. + + .. note:: Routes with a distance of 255 are effectively disabled and not + installed into the kernel. + +.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> + + Configure next-hop `<address>` for an IPv6 static route. Multiple static + routes can be created. + +.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> disable + + Disable this IPv6 static route entry. + +.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> + distance <distance> + + Defines next-hop distance for this route, routes with smaller administrative + distance are elected prior those with a higher distance. + + Range is 1 to 255, default is 1. + + .. note:: Routes with a distance of 255 are effectively disabled and not + installed into the kernel. + + +Interface Routes +================ + +.. cfgcmd:: set protocols static route <subnet> interface + <interface> + + Allows you to configure the next-hop interface for an interface-based IPv4 + static route. `<interface>` will be the next-hop interface where trafic is + routed for the given `<subnet>`. + +.. cfgcmd:: set protocols static route <subnet> interface + <interface> disable + + Disables interface-based IPv4 static route. + +.. cfgcmd:: set protocols static route <subnet> interface + <interface> distance <distance> + + Defines next-hop distance for this route, routes with smaller administrative + distance are elected prior those with a higher distance. + + Range is 1 to 255, default is 1. + +.. cfgcmd:: set protocols static route6 <subnet> interface + <interface> + + Allows you to configure the next-hop interface for an interface-based IPv6 + static route. `<interface>` will be the next-hop interface where trafic is + routed for the given `<subnet>`. + +.. cfgcmd:: set protocols static route6 <subnet> interface + <interface> disable + + Disables interface-based IPv6 static route. + +.. cfgcmd:: set protocols static route6 <subnet> interface + <interface> distance <distance> + + Defines next-hop distance for this route, routes with smaller administrative + distance are elected prior those with a higher distance. + + Range is 1 to 255, default is 1. + + +Blackhole +========= + +.. cfgcmd:: set protocols static route <subnet> blackhole + + Use this command to configure a "black-hole" route on the router. A + black-hole route is a route for which the system silently discard packets + that are matched. This prevents networks leaking out public interfaces, but + it does not prevent them from being used as a more specific route inside your + network. + +.. cfgcmd:: set protocols static route <subnet> blackhole distance <distance> + + Defines blackhole distance for this route, routes with smaller administrative + distance are elected prior those with a higher distance. + +.. cfgcmd:: set protocols static route6 <subnet> blackhole + + Use this command to configure a "black-hole" route on the router. A + black-hole route is a route for which the system silently discard packets + that are matched. This prevents networks leaking out public interfaces, but + it does not prevent them from being used as a more specific route inside your + network. + +.. cfgcmd:: set protocols static route6 <subnet> blackhole distance <distance> + + Defines blackhole distance for this route, routes with smaller administrative + distance are elected prior those with a higher distance. + + +Alternate Routing Tables +======================== + +TBD + +Alternate routing tables are used with policy based routing of by utilizing +:ref:`vrf`. + + +.. _routing-arp: + +### +ARP +### + +:abbr:`ARP (Address Resolution Protocol)` is a communication protocol used for +discovering the link layer address, such as a MAC address, associated with a +given internet layer address, typically an IPv4 address. This mapping is a +critical function in the Internet protocol suite. ARP was defined in 1982 by +:rfc:`826` which is Internet Standard STD 37. + +In Internet Protocol Version 6 (IPv6) networks, the functionality of ARP is +provided by the Neighbor Discovery Protocol (NDP). + +To manipulate or display ARP_ table entries, the following commands are +implemented. + +********* +Configure +********* + +.. cfgcmd:: set protocols static arp <address> hwaddr <mac> + + This will configure a static ARP entry always resolving `<address>` to + `<mac>`. + + Example: + + .. code-block:: none + + set protocols static arp 192.0.2.100 hwaddr 00:53:27:de:23:aa + + +********* +Operation +********* + + +.. opcmd:: show protocols static arp + + Display all known ARP table entries spanning across all interfaces + +.. code-block:: none + + vyos@vyos:~$ show protocols static arp + Address HWtype HWaddress Flags Mask Iface + 10.1.1.1 ether 00:53:00:de:23:2e C eth1 + 10.1.1.100 ether 00:53:00:de:23:aa CM eth1 + + +.. opcmd:: show protocols static arp interface eth1 + + Display all known ARP table entries on a given interface only (`eth1`): + +.. code-block:: none + + vyos@vyos:~$ show protocols static arp interface eth1 + Address HWtype HWaddress Flags Mask Iface + 10.1.1.1 ether 00:53:00:de:23:2e C eth1 + 10.1.1.100 ether 00:53:00:de:23:aa CM eth1 + +.. _ARP: https://en.wikipedia.org/wiki/Address_Resolution_Protocol diff --git a/docs/configuration/protocols/vrf.disable b/docs/configuration/protocols/vrf.disable new file mode 100644 index 00000000..e7609a77 --- /dev/null +++ b/docs/configuration/protocols/vrf.disable @@ -0,0 +1,3 @@ +############# +Protocols VRF +############# diff --git a/docs/configuration/service/broadcast-relay.rst b/docs/configuration/service/broadcast-relay.rst new file mode 100644 index 00000000..df48bfd6 --- /dev/null +++ b/docs/configuration/service/broadcast-relay.rst @@ -0,0 +1,61 @@ +.. _udp_broadcast_relay: + +################### +UDP Broadcast Relay +################### + +Certain vendors use broadcasts to identify their equipment within one ethernet +segment. Unfortunately if you split your network with multiple VLANs you loose +the ability of identifying your equipment. + +This is where "UDP broadcast relay" comes into play! It will forward received +broadcasts to other configured networks. + +Every UDP port which will be forward requires one unique ID. Currently we +support 99 IDs! + +Configuration +------------- + +.. cfgcmd:: set service broadcast-relay id <n> description <description> + + A description can be added for each and every unique relay ID. This is + useful to distinguish between multiple different ports/appliactions. + +.. cfgcmd:: set service broadcast-relay id <n> interface <interface> + + The interface used to receive and relay individual broadcast packets. If you + want to receive/relay packets on both `eth1` and `eth2` both interfaces need + to be added. + +.. cfgcmd:: set service broadcast-relay id <n> port <port> + + The UDP port number used by your apllication. It is mandatory for this kind + of operation. + +.. cfgcmd:: set service broadcast-relay id <n> disable + + Each broadcast relay instance can be individually disabled without deleting + the configured node by using the following command: + +.. cfgcmd:: set service broadcast-relay disable + + In addition you can also disable the whole service without the need to remove + it from the current configuration. + +.. note:: You can run the UDP broadcast relay service on multiple routers + connected to a subnet. There is **NO** UDP broadcast relay packet storm! + +Example +------- + +To forward all broadcast packets received on `UDP port 1900` on `eth3`, `eth4` +or `eth5` to all other interfaces in this configuration. + +.. code-block:: none + + set service broadcast-relay id 1 description 'SONOS' + set service broadcast-relay id 1 interface 'eth3' + set service broadcast-relay id 1 interface 'eth4' + set service broadcast-relay id 1 interface 'eth5' + set service broadcast-relay id 1 port '1900' diff --git a/docs/configuration/service/conntrack-sync.rst b/docs/configuration/service/conntrack-sync.rst new file mode 100644 index 00000000..3c9f08e4 --- /dev/null +++ b/docs/configuration/service/conntrack-sync.rst @@ -0,0 +1,201 @@ +.. include:: /_include/need_improvement.txt + +Conntrack +--------- + +One of the important features built on top of the Netfilter framework is +connection tracking. Connection tracking allows the kernel to keep track of all +logical network connections or sessions, and thereby relate all of the packets +which may make up that connection. NAT relies on this information to translate +all related packets in the same way, and iptables can use this information to +act as a stateful firewall. + +The connection state however is completely independent of any upper-level +state, such as TCP's or SCTP's state. Part of the reason for this is that when +merely forwarding packets, i.e. no local delivery, the TCP engine may not +necessarily be invoked at all. Even connectionless-mode transmissions such as +UDP, IPsec (AH/ESP), GRE and other tunneling protocols have, at least, a pseudo +connection state. The heuristic for such protocols is often based upon a preset +timeout value for inactivity, after whose expiration a Netfilter connection is +dropped. + +Each Netfilter connection is uniquely identified by a (layer-3 protocol, source +address, destination address, layer-4 protocol, layer-4 key) tuple. The layer-4 +key depends on the transport protocol; for TCP/UDP it is the port numbers, for +tunnels it can be their tunnel ID, but otherwise is just zero, as if it were +not part of the tuple. To be able to inspect the TCP port in all cases, packets +will be mandatorily defragmented. + +It is possible to use either Multicast or Unicast to sync conntrack traffic. +Most examples below show Multicast, but unicast can be specified by using the +"peer" keywork after the specificed interface, as in the following example: + +set service conntrack-sync interface eth0 peer 192.168.0.250 + +Configuration +^^^^^^^^^^^^^ + +.. code-block:: none + + # Protocols only for which local conntrack entries will be synced (tcp, udp, icmp, sctp) + set service conntrack-sync accept-protocol + + # Queue size for listening to local conntrack events (in MB) + set service conntrack-sync event-listen-queue-size <int> + + # Protocol for which expect entries need to be synchronized. (all, ftp, h323, nfs, sip, sqlnet) + set service conntrack-sync expect-sync + + # Failover mechanism to use for conntrack-sync [REQUIRED] + set service conntrack-sync failover-mechanism + + set service conntrack-sync cluster group <string> + set service conntrack-sync vrrp sync-group <1-255> + + # IP addresses for which local conntrack entries will not be synced + set service conntrack-sync ignore-address ipv4 <x.x.x.x> + + # Interface to use for syncing conntrack entries [REQUIRED] + set service conntrack-sync interface <ifname> + + # Multicast group to use for syncing conntrack entries + set service conntrack-sync mcast-group <x.x.x.x> + + # Peer to send Unicast UDP conntrack sync entires to, if not using Multicast above + set service conntrack-sync interface <ifname> peer <remote IP of peer> + + # Queue size for syncing conntrack entries (in MB) + set service conntrack-sync sync-queue-size <size> + +Example +^^^^^^^ +The next example is a simple configuration of conntrack-sync. + + +.. figure:: /_static/images/service_conntrack_sync-schema.png + :scale: 60 % + :alt: Conntrack Sync Example + + Conntrack Sync Example + +First of all, make sure conntrack is enabled by running + +.. code-block:: none + + show conntrack table ipv4 + +If the table is empty and you have a warning message, it means conntrack is not +enabled. To enable conntrack, just create a NAT or a firewall rule. + +.. code-block:: none + + set firewall state-policy established action accept + +You now should have a conntrack table + +.. code-block:: none + + $ show conntrack table ipv4 + TCP state codes: SS - SYN SENT, SR - SYN RECEIVED, ES - ESTABLISHED, + FW - FIN WAIT, CW - CLOSE WAIT, LA - LAST ACK, + TW - TIME WAIT, CL - CLOSE, LI - LISTEN + + CONN ID Source Destination Protocol TIMEOUT + 1015736576 10.35.100.87:58172 172.31.20.12:22 tcp [6] ES 430279 + 1006235648 10.35.101.221:57483 172.31.120.21:22 tcp [6] ES 413310 + 1006237088 10.100.68.100 172.31.120.21 icmp [1] 29 + 1015734848 10.35.100.87:56282 172.31.20.12:22 tcp [6] ES 300 + 1015734272 172.31.20.12:60286 239.10.10.14:694 udp [17] 29 + 1006239392 10.35.101.221 172.31.120.21 icmp [1] 29 + +Now configure conntrack-sync service on ``router1`` **and** ``router2`` + +.. code-block:: none + + set service conntrack-sync accept-protocol 'tcp,udp,icmp' + set service conntrack-sync event-listen-queue-size '8' + set service conntrack-sync failover-mechanism cluster group 'GROUP' + set service conntrack-sync interface 'eth0' + set service conntrack-sync mcast-group '225.0.0.50' + set service conntrack-sync sync-queue-size '8' + +If you are using VRRP, you need to define a VRRP sync-group, and use +``vrrp sync-group`` instead of ``cluster group``. + +.. code-block:: none + + set high-availablilty vrrp group internal virtual-address ... etc ... + set high-availability vrrp sync-group syncgrp member 'internal' + set service conntrack-sync failover-mechanism vrrp sync-group 'syncgrp' + + +On the active router, you should have information in the internal-cache of +conntrack-sync. The same current active connections number should be shown in +the external-cache of the standby router + +On active router run: + +.. code-block:: none + + $ show conntrack-sync statistics + + Main Table Statistics: + + cache internal: + current active connections: 10 + connections created: 8517 failed: 0 + connections updated: 127 failed: 0 + connections destroyed: 8507 failed: 0 + + cache external: + current active connections: 0 + connections created: 0 failed: 0 + connections updated: 0 failed: 0 + connections destroyed: 0 failed: 0 + + traffic processed: + 0 Bytes 0 Pckts + + multicast traffic (active device=eth0): + 868780 Bytes sent 224136 Bytes recv + 20595 Pckts sent 14034 Pckts recv + 0 Error send 0 Error recv + + message tracking: + 0 Malformed msgs 0 Lost msgs + + + +On standby router run: + + +.. code-block:: none + + + $ show conntrack-sync statistics + + Main Table Statistics: + + cache internal: + current active connections: 0 + connections created: 0 failed: 0 + connections updated: 0 failed: 0 + connections destroyed: 0 failed: 0 + + cache external: + current active connections: 10 + connections created: 888 failed: 0 + connections updated: 134 failed: 0 + connections destroyed: 878 failed: 0 + + traffic processed: + 0 Bytes 0 Pckts + + multicast traffic (active device=eth0): + 234184 Bytes sent 907504 Bytes recv + 14663 Pckts sent 21495 Pckts recv + 0 Error send 0 Error recv + + message tracking: + 0 Malformed msgs 0 Lost msgs + diff --git a/docs/configuration/service/console-server.rst b/docs/configuration/service/console-server.rst new file mode 100644 index 00000000..a509723e --- /dev/null +++ b/docs/configuration/service/console-server.rst @@ -0,0 +1,108 @@ +.. _console_server: + +############## +Console Server +############## + +Starting of with VyOS 1.3 (equuleus) we added support for running VyOS as an +Out-of-Band Management device which provides remote access by means of SSH to +directly attached serial interfaces. + +Serial interfaces can be any interface which is directly connected to the CPU +or chipset (mostly known as a ttyS interface in Linux) or any other USB to +serial converter (Prolific PL2303 or FTDI FT232/FT4232 based chips). + +If you happened to use a Cisco NM-16A - Sixteen Port Async Network Module or +NM-32A - Thirty-two Port Async Network Module - this is your VyOS replacement. + +For USB port information please refor to: :ref:`hardware_usb`. + +Configuration +============= + +Between computers, the most common configuration used was "8N1": eight bit +characters, with one start bit, one stop bit, and no parity bit. Thus 10 Baud +times are used to send a single character, and so dividing the signalling +bit-rate by ten results in the overall transmission speed in characters per +second. This is also the default setting if none of those options are defined. + +.. cfgcmd:: set service console-server <device> data-bits [7 | 8] + + Configure either seven or eight data bits. This defaults to eight data + bits if left unconfigured. + +.. cfgcmd:: set service console-server <device> description <string> + + A user friendly description identifying the connected peripheral. + +.. cfgcmd:: set service console-server <device> parity [even | odd | none] + + Set the parity option for the console. If unset this will default to none. + +.. cfgcmd:: set service console-server <device> stop-bits [1 | 2] + + Configure either one or two stop bits. This defaults to one stop bits if + left unconfigured. + +.. cfgcmd:: set service console-server <device> speed + [ 300 | 1200 | 2400 | 4800 | 9600 | 19200 | 38400 | 57600 | 115200 ] + + .. note:: USB to serial converters will handle most of their work in software + so you should be carefull with the selected baudrate as some times they + can't cope with the expected speed. + +Remote Access +------------- + +Each individual configured console-server device can be directly exposed to +the outside world. A user can directly connect via SSH to the configured +port. + +.. cfgcmd:: set service console-server <device> ssh port <port> + + Accept SSH connections for the given `<device>` on TCP port `<port>`. + After successfull authentication the user will be directly dropped to + the connected serial device. + + .. hint:: Multiple users can connect to the same serial device but only + one is allowed to write to the console port. + +Operation +========= + +.. opcmd:: show console-server ports + + Show configured serial ports and their respective interface configuration. + + .. code-block:: none + + vyos@vyos:~$ show console-server ports + usb0b2.4p1.0 on /dev/serial/by-bus/usb0b2.4p1.0@ at 9600n + +.. opcmd:: show console-server user + + Show currently connected users. + + .. code-block:: none + + vyos@vyos:~$ show console-server user + usb0b2.4p1.0 up vyos@localhost + + +.. opcmd:: connect console-server <device> + + Locally connect to serial port identified by `<device>`. + + .. code-block:: none + + vyos@vyos-r1:~$ connect console-server usb0b2.4p1.0 + [Enter `^Ec?' for help] + [-- MOTD -- VyOS Console Server] + + vyos-r2 login: + + .. hint:: Multiple users can connect to the same serial device but only + one is allowed to write to the console port. + + .. hint:: The sequence ``^Ec?`` translates to: ``Ctrl+E c ?``. To quit + the session use: ``Ctrl+E c .`` diff --git a/docs/configuration/service/dhcp-relay.rst b/docs/configuration/service/dhcp-relay.rst new file mode 100644 index 00000000..5355a0fd --- /dev/null +++ b/docs/configuration/service/dhcp-relay.rst @@ -0,0 +1,159 @@ +.. _dhcp-relay: + +########## +DHCP Relay +########## + +If you want your router to forward DHCP requests to an external DHCP server +you can configure the system to act as a DHCP relay agent. The DHCP relay +agent works with IPv4 and IPv6 addresses. + +All interfaces used for the DHCP relay must be configured. + +********** +IPv4 relay +********** + +Configuration +============= + +.. cfgcmd:: set service dhcp-relay interface <interface> + + Enable the DHCP relay service on the given interface. + +.. cfgcmd:: set service dhcp-relay server <server> + + Configure IP address of the DHCP `<server>` which will handle the relayed + packets. + +.. cfgcmd:: set service dhcp-relay relay-options relay-agents-packets discard + + The router should discard DHCP packages already containing relay agent + information to ensure that only requests from DHCP clients are forwarded. + +Options +------- + +.. cfgcmd:: set service dhcp-relay relay-options hop-count <count> + + Set the maximum hop `<count>` before packets are discarded. Range 0...255, + default 10. + +.. cfgcmd:: set service dhcp-relay relay-options max-size <size> + + Set maximum `<size>` of DHCP packets including relay agent information. If a + DHCP packet size surpasses this value it will be forwarded without appending + relay agent information. Range 64...1400, default 576. + +.. cfgcmd:: set service dhcp-relay relay-options relay-agents-packet + <append | discard | forward | replace> + + Four policies for reforwarding DHCP packets exist: + + * **append:** The relay agent is allowed to append its own relay information + to a received DHCP packet, disregarding relay information already present + in the packet. + + * **discard:** Received packets which already contain relay information will + be discarded. + + * **forward:** All packets are forwarded, relay information already present + will be ignored. + + * **replace:** Relay information already present in a packet is stripped and + replaced with the router's own relay information set. + +Example +======= + +* Listen for DHCP requests on interface ``eth1``. +* DHCP server is located at IPv4 address 10.0.1.4. +* Router receives DHCP client requests on ``eth1`` and relays them to the server + at 10.0.1.4. + +.. figure:: /_static/images/service_dhcp-relay01.png + :scale: 80 % + :alt: DHCP relay example + + DHCP relay example + +The generated configuration will look like: + +.. code-block:: none + + show service dhcp-relay + interface eth1 + server 10.0.1.4 + relay-options { + relay-agents-packets discard + } + +Operation +========= + +.. opcmd:: restart dhcp relay-agent + + Restart DHCP relay service + +********** +IPv6 relay +********** + +Configuration +============= + +.. cfgcmd:: set service dhcpv6-relay listen-interface <interface> + + Set eth1 to be the listening interface for the DHCPv6 relay. + + Multiple interfaces may be specified. + +.. cfgcmd:: set service dhcpv6-relay upstream-interface <interface> + address <server> + + Specifies an upstream network `<interface>` from which replies from + `<server>` and other relay agents will be accepted. + +Options +------- + +.. cfgcmd:: set service dhcpv6-relay max-hop-count 'count' + + Set maximum hop count before packets are discarded, default: 10 + +.. cfgcmd:: set service dhcpv6-relay use-interface-id-option + + If this is set the relay agent will insert the interface ID. This option is + set automatically if more than one listening interfaces are in use. + +Example +======= + +* DHCPv6 requests are received by the router on `listening interface` ``eth1`` +* Requests are forwarded through ``eth2`` as the `upstream interface` +* External DHCPv6 server is at 2001:db8::4 + +.. figure:: /_static/images/service_dhcpv6-relay01.png + :scale: 80 % + :alt: DHCPv6 relay example + + DHCPv6 relay example + +The generated configuration will look like: + +.. code-block:: none + + commit + show service dhcpv6-relay + listen-interface eth1 { + } + upstream-interface eth2 { + address 2001:db8::4 + } + +Operation +========= + +.. opcmd:: restart dhcpv6 relay-agent + + Restart DHCPv6 relay agent immediately. diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst new file mode 100644 index 00000000..28dddb2f --- /dev/null +++ b/docs/configuration/service/dhcp-server.rst @@ -0,0 +1,621 @@ +.. _dhcp-server: + +########### +DHCP Server +########### + +VyOS uses ISC DHCP server for both IPv4 and IPv6 address assignment. + +*********** +IPv4 server +*********** + +The network topology is declared by shared-network-name and the subnet +declarations. The DHCP service can serve multiple shared networks, with each +shared network having 1 or more subnets. Each subnet must be present on an +interface. A range can be declared inside a subnet to define a pool of dynamic +addresses. Multiple ranges can be defined and can contain holes. Static +mappings can be set to assign "static" addresses to clients based on their MAC +address. + +Configuration +============= + +.. cfgcmd:: set service dhcp-server shared-network-name <name> authoritative + + This says that this device is the only DHCP server for this network. If other + devices are trying to offer DHCP leases, this machine will send 'DHCPNAK' to + any device trying to request an IP address that is not valid for this + network. + +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + 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> + dns-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>`. + + Multiple DNS servers can be defined. + +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + lease <time> + + Assign the IP address to this machine for `<time>` seconds. + + The default value is 86400 seconds which corresponds to one day. + +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + range <n> start <address> + + Create DHCP address range with a range id of `<n>`. DHCP leases are taken + from this pool. The pool starts at address `<address>`. + +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + range <n> stop <address> + + Create DHCP address range with a range id of `<n>`. DHCP leases are taken + from this pool. The pool stops with address `<address>`. + +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + exclude <address> + + Always exclude this address from any defined range. This address will never + be assigned by the DHCP server. + + This option can be specified multiple times. + +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + 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> + + 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). + +Failover +-------- + +VyOS provides support for DHCP failover. DHCP failover must be configured +explicitly by the following statements. + +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet + <subnet> failover local-address <address> + + Local IP `<address>` used when communicating to the failover peer. + +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet + <subnet> failover peer-address <address> + + Remote peer IP `<address>` of the second DHCP server in this failover + cluster. + +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet + <subnet> failover name <name> + + A generic `<name>` referencing this sync service. + + .. note:: `<name>` must be identical on both sides! + +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet + <subnet> failover status <primary | secondary> + + The primary and secondary statements determines whether the server is primary + or secondary. + + .. note:: In order for the primary and the secondary DHCP server to keep + their lease tables in sync, they must be able to reach each other on TCP + port 647. If you have firewall rules in effect, adjust them accordingly. + + .. hint:: The dialogue between failover partners is neither encrypted nor + authenticated. Since most DHCP servers exist within an organisation's own + secure Intranet, this would be an unnecessary overhead. However, if you + have DHCP failover peers whose communications traverse insecure networks, + then we recommend that you consider the use of VPN tunneling between them + to ensure that the failover partnership is immune to disruption + (accidental or otherwise) via third parties. + +Static mappings +--------------- + +You can specify a static DHCP assignment on a per host basis. You will need the +MAC address of the station and your desired IP address. The address must be +inside the subnet definition but can be outside of the range statement. + +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet + <subnet> static-mapping <description> mac-address <address> + + Create a new DHCP static mapping named `<description>` which is valid for + the host identified by its MAC `<address>`. + +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet + <subnet> static-mapping <description> ip-address <address> + + Static DHCP IP address assign to host identified by `<description>`. IP + address must be inside the `<subnet>` which is defined but can be outside + the dynamic range created with :cfgcmd:`set service dhcp-server + shared-network-name <name> subnet <subnet> range <n>`. If no ip-address is + specified, an IP from the dynamic pool is used. + + This is useful, for example, in combination with hostfile update. + + .. hint:: This is the equivalent of the host block in dhcpd.conf of + isc-dhcpd. + +Options +======= + +.. list-table:: + :header-rows: 1 + :stub-columns: 0 + :widths: 12 7 23 40 20 + + * - Setting name + - Option number + - ISC-DHCP Option name + - Option description + - Multi + * - client-prefix-length + - 1 + - subnet-mask + - Specifies the clients subnet mask as per RFC 950. If unset, + subnet declaration is used. + - N + * - time-offset + - 2 + - time-offset + - Offset of the client's subnet in seconds from Coordinated + Universal Time (UTC) + - N + * - default-router + - 3 + - routers + - IPv4 address of router on the client's subnet + - N + * - time-server + - 4 + - time-servers + - RFC 868 time server IPv4 address + - Y + * - dns-server + - 6 + - domain-name-servers + - DNS server IPv4 address + - Y + * - domain-name + - 15 + - domain-name + - Client domain name + - Y + * - ip-forwarding + - 19 + - ip-forwarding + - Enable IP forwarding on client + - N + * - ntp-server + - 42 + - ntp-servers + - IP address of NTP server + - Y + * - wins-server + - 44 + - netbios-name-servers + - NetBIOS over TCP/IP name server + - Y + * - server-identifier + - 54 + - dhcp-server-identifier + - IP address for DHCP server identifier + - N + * - bootfile-server + - siaddr + - next-server + - IPv4 address of next bootstrap server + - N + * - tftp-server-name + - 66 + - tftp-server-name + - Name or IPv4 address of TFTP server + - N + * - bootfile-name + - 67 + - bootfile-name, filename + - Bootstrap file name + - N + * - smtp-server + - 69 + - smtp-server + - IP address of SMTP server + - Y + * - pop-server + - 70 + - pop-server + - IP address of POP3 server + - Y + * - domain-search + - 119 + - domain-search + - Client domain search + - Y + * - static-route + - 121, 249 + - rfc3442-static-route, windows-static-route + - Classless static route + - N + * - wpad-url + - 252 + - wpad-url, wpad-url code 252 = text + - Web Proxy Autodiscovery (WPAD) URL + - N + * - lease + - + - default-lease-time, max-lease-time + - Lease timeout in seconds (default: 86400) + - N + * - range + - + - range + - DHCP lease range + - Y + * - exclude + - + - + - IP address to exclude from DHCP lease range + - Y + * - failover + - + - + - DHCP failover parameters + - + * - static-mapping + - + - + - Name of static mapping + - Y + +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 +======= + +Please see the :ref:`dhcp-dns-quick-start` configuration. + +Failover +-------- + +Configuration of a DHCP failover pair + +* Setup DHCP failover for network 192.0.2.0/24 +* Default gateway and DNS server is at `192.0.2.254` +* The primary DHCP server uses address `192.168.189.252` +* The secondary DHCP server uses address `192.168.189.253` +* DHCP range spans from `192.168.189.10` - `192.168.189.250` + +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 dns-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 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' + + +**Primary** + +.. code-block:: none + + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover local-address '192.168.189.252' + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover name 'NET-VYOS' + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover peer-address '192.168.189.253' + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover status 'primary' + +**Secondary** + +.. code-block:: none + + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover local-address '192.168.189.253' + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover name 'NET-VYOS' + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover peer-address '192.168.189.252' + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover status 'primary' + + +Raw Parameters +-------------- + +* Override static-mapping's dns-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";" + + +Operation Mode +============== + +.. opcmd:: restart dhcp server + + Restart the DHCP server + +.. opcmd:: show dhcp server statistics + + Show the DHCP server statistics: + +.. code-block:: none + + vyos@vyos:~$ show dhcp server statistics + Pool Size Leases Available Usage + ----------- ------ -------- ----------- ------- + dhcpexample 99 2 97 2% + +.. opcmd:: show dhcp server statistics pool <pool> + + Show the DHCP server statistics for the specified pool. + +.. opcmd:: show dhcp server leases + + Show statuses of all active leases: + +.. 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 + +.. hint:: Static mappings aren't shown. To show all states, use + ``show dhcp server leases state all``. + +.. opcmd:: show dhcp server leases pool <pool> + + Show only leases in the specified pool. + +.. opcmd:: show dhcp server leases sort <key> + + Sort the output by the specified key. Possible keys: ip, hardware_address, + state, start, end, remaining, pool, hostname (default = ip) + +.. opcmd:: show dhcp server leases state <state> + + Show only leases with the specified state. Possible states: all, active, + free, expired, released, abandoned, reset, backup (default = active) + +*********** +IPv6 server +*********** + +VyOS also provides DHCPv6 server functionality which is described in this +section. + +Configuration +============= + +.. cfgcmd:: set service dhcpv6-server preference <preference value> + + 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 + <prefix> lease-time {default | maximum | minimum} + + The default lease time for DHCPv6 leases is 24 hours. This can be changed by + supplying a ``default-time``, ``maximum-time`` and ``minimum-time``. All + values need to be supplied in seconds. + +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> nis-domain <domain-name> + + A :abbr:`NIS (Network Information Service)` domain can be set to be used for + DHCPv6 clients. + +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> nisplus-domain <domain-name> + + The procedure to specify a :abbr:`NIS+ (Network Information Service Plus)` + domain is similar to the NIS domain one: + +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> nis-server <address> + + Specify a NIS server address for DHCPv6 clients. + +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> nisplus-server <address> + + Specify a NIS+ server address for DHCPv6 clients. + +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> sip-server <address | fqdn> + + Specify a :abbr:`SIP (Session Initiation Protocol)` server by IPv6 + address of Fully Qualified Domain Name for all DHCPv6 clients. + +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> sntp-server-address <address> + + A SNTP server address can be specified for DHCPv6 clients. + +Prefix Delegation +----------------- + +To hand out individual prefixes to your clients the following configuration is +used: + + +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> prefix-delegation start <address> prefix-length <length> + + Hand out prefixes of size `<length>` to clients in subnet `<prefix>` when + they request for prefix delegation. + +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> prefix-delegation start <address> stop <address> + + Delegate prefixes from the range indicated by the start and stop qualifier. + +Address pools +------------- + +DHCPv6 address pools must be configured for the system to act as a DHCPv6 +server. The following example describes a common scenario. + +**Example:** + +* A shared network named ``NET1`` serves subnet ``2001:db8::/64`` +* It is connected to ``eth1`` +* DNS server is located at ``2001:db8::ffff`` +* Address pool shall be ``2001:db8::100`` through ``2001:db8::199``. +* Lease time will be left at the default value which is 24 hours + +.. code-block:: none + + 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 + +The configuration will look as follows: + +.. code-block:: none + + show service dhcpv6-server + shared-network-name NET1 { + subnet 2001:db8::/64 { + address-range { + start 2001:db8::100 { + stop 2001:db8::199 + } + } + name-server 2001:db8::ffff + } + } + +Static mappings +--------------- + +In order to map specific IPv6 addresses to specific hosts static mappings can +be created. The following example explains the process. + +**Example:** + +* IPv6 address ``2001:db8::101`` shall be statically mapped +* Host specific mapping shall be named ``client1`` + +.. hint:: The identifier is the device's DUID: colon-separated hex list (as + used by isc-dhcp option dhcpv6.client-id). If the device already has a + dynamic lease from the DHCPv6 server, its DUID can be found with ``show + service dhcpv6 server leases``. The DUID begins at the 5th octet (after the + 4th colon) of IAID_DUID. + +.. code-block:: none + + set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 ipv6-address 2001:db8::101 + set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 identifier 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff + +The configuration will look as follows: + +.. stop_vyoslinter (00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff false positive) + +.. code-block:: none + + show service dhcp-server shared-network-name NET1 + shared-network-name NET1 { + subnet 2001:db8::/64 { + name-server 2001:db8:111::111 + address-range { + start 2001:db8::100 { + stop 2001:db8::199 { + } + } + static-mapping client1 { + ipv6-address 2001:db8::101 + identifier 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff + } + } + } + +.. start_vyoslinter + +Operation Mode +============== + +.. opcmd:: restart dhcpv6 server + + To restart the DHCPv6 server + +.. opcmd:: show dhcpv6 server status + + To show the current status of the DHCPv6 server. + +.. opcmd:: show dhcpv6 server leases + + Show statuses of all assigned leases: + +.. code-block:: none + + vyos@vyos:~$ show dhcpv6 server leases + IPv6 address State Last communication Lease expiration Remaining Type Pool IAID_DUID + ------------- ------- -------------------- ------------------- ----------- ------------- ----- -------------------------------------------- + 2001:db8::101 active 2019/12/05 19:40:10 2019/12/06 07:40:10 11:45:21 non-temporary NET1 98:76:54:32:00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff + 2001:db8::102 active 2019/12/05 14:01:23 2019/12/06 02:01:23 6:06:34 non-temporary NET1 87:65:43:21:00:01:00:01:11:22:33:44:fa:fb:fc:fd:fe:ff + +.. hint:: Static mappings aren't shown. To show all states, use ``show dhcp + server leases state all``. + +.. opcmd:: show dhcpv6 server leases pool <pool> + + Show only leases in the specified pool. + +.. opcmd:: show dhcpv6 server leases sort <key> + + Sort the output by the specified key. Possible keys: expires, iaid_duid, ip, + last_comm, pool, remaining, state, type (default = ip) + +.. opcmd:: show dhcpv6 server leases state <state> + + Show only leases with the specified state. Possible states: abandoned, + active, all, backup, expired, free, released, reset (default = active) diff --git a/docs/configuration/service/dns.rst b/docs/configuration/service/dns.rst new file mode 100644 index 00000000..0a65161b --- /dev/null +++ b/docs/configuration/service/dns.rst @@ -0,0 +1,328 @@ +.. _dns-forwarding: + +############## +DNS Forwarding +############## + +Configuration +============= + +VyOS provides DNS infrastructure for small networks. It is designed to be +lightweight and have a small footprint, suitable for resource constrained +routers and firewalls. For this we utilize PowerDNS recursor. + +The VyOS DNS forwarder does not require an upstream DNS server. It can serve as +a full recursive DNS server - but it can also forward queries to configurable +upstream DNS servers. By not configuring any upstream DNS servers you also +avoid being tracked by the provider of your upstream DNS server. + +.. cfgcmd:: set service dns forwarding system + + Forward incoming DNS queries to the DNS servers configured under the ``system + name-server`` nodes. + +.. cfgcmd:: set service dns forwarding name-server <address> + + Send all DNS queries to the IPv4/IPv6 DNS server specified under `<address>`. + You can configure multiple nameservers here. + +.. cfgcmd:: set service dns forwarding domain <domain-name> server <address> + + Forward received queries for a particular domain + (specified via `domain-name`) to a given nameserver. Multiple nameservers + can be specified. You can use this feature for a DNS split-horizon + configuration. + + .. note:: This also works for reverse-lookup zones (``18.172.in-addr.arpa``). + +.. cfgcmd:: set service dns forwarding allow-from <network> + + Given the fact that open DNS recursors could be used on DDoS amplification + attacks, you must configure the networks which are allowed to use this + recursor. A network of ``0.0.0.0/0`` or ``::/0`` would allow all IPv4 and + IPv6 networks to query this server. This is generally a bad idea. + +.. cfgcmd:: set service dns forwarding dnssec + <off | process-no-validate | process | log-fail | validate> + + The PowerDNS recursor has 5 different levels of DNSSEC processing, which can + be set with the dnssec setting. In order from least to most processing, these + are: + + * **off** In this mode, no DNSSEC processing takes place. The recursor will + not set the DNSSEC OK (DO) bit in the outgoing queries and will ignore the + DO and AD bits in queries. + + * **process-no-validate** In this mode the recursor acts as a "security + aware, non-validating" nameserver, meaning it will set the DO-bit on + outgoing queries and will provide DNSSEC related RRsets (NSEC, RRSIG) to + clients that ask for them (by means of a DO-bit in the query), except for + zones provided through the auth-zones setting. It will not do any + validation in this mode, not even when requested by the client. + + * **process** When dnssec is set to process the behavior is similar to + process-no-validate. However, the recursor will try to validate the data + if at least one of the DO or AD bits is set in the query; in that case, + it will set the AD-bit in the response when the data is validated + successfully, or send SERVFAIL when the validation comes up bogus. + + * **log-fail** In this mode, the recursor will attempt to validate all data + it retrieves from authoritative servers, regardless of the client's DNSSEC + desires, and will log the validation result. This mode can be used to + determine the extra load and amount of possibly bogus answers before + turning on full-blown validation. Responses to client queries are the same + as with process. + + * **validate** The highest mode of DNSSEC processing. In this mode, all + queries will be validated and will be answered with a SERVFAIL in case of + bogus data, regardless of the client's request. + + .. note:: The popular Unix/Linux ``dig`` tool sets the AD-bit in the query. + This might lead to unexpected query results when testing. Set ``+noad`` + on the ``dig`` command line when this is the case. + + .. note:: The ``CD``-bit is honored correctly for process and validate. For + log-fail, failures will be logged too. + +.. cfgcmd:: set service dns forwarding ignore-hosts-file + + Do not use the local ``/etc/hosts`` file in name resolution. VyOS DHCP + server will use this file to add resolvers to assigned addresses. + +.. cfgcmd:: set service dns forwarding max-cache-entries + + Maximum number of DNS cache entries. 1 million per CPU core will generally + suffice for most installations. + +.. cfgcmd:: set service dns forwarding negative-ttl + + A query for which there is authoritatively no answer is cached to quickly + deny a record's existence later on, without putting a heavy load on the + remote server. In practice, caches can become saturated with hundreds of + thousands of hosts which are tried only once. This setting, which defaults + to 3600 seconds, puts a maximum on the amount of time negative entries are + cached. + +.. cfgcmd:: set service dns forwarding listen-address + + The local IPv4 or IPv6 addresses to bind the DNS forwarder to. The forwarder + will listen on this address for incoming connections. + +Example +======= + +A VyOS router with two interfaces - eth0 (WAN) and eth1 (LAN) - is required to +implement a split-horizon DNS configuration for example.com. + +In this scenario: + +* All DNS requests for example.com must be forwarded to a DNS server + at 192.0.2.254 and 2001:db8:cafe::1 +* All other DNS requests will be forwarded to a different set of DNS servers at + 192.0.2.1, 192.0.2.2, 2001:db8::1:ffff and 2001:db8::2:ffff +* The VyOS DNS forwarder will only listen for requests on the eth1 (LAN) + interface addresses - 192.168.1.254 for IPv4 and 2001:db8::ffff for IPv6 +* The VyOS DNS forwarder will only accept lookup requests from the + LAN subnets - 192.168.1.0/24 and 2001:db8::/64 + +.. code-block:: none + + set service dns forwarding domain example.com server 192.0.2.254 + set service dns forwarding domain example.com server 2001:db8:cafe::1 + set service dns forwarding name-server 192.0.2.1 + set service dns forwarding name-server 192.0.2.2 + set service dns forwarding name-server 2001:db8::1:ffff + set service dns forwarding name-server 2001:db8::2:ffff + set service dns forwarding listen-address 192.168.1.254 + set service dns forwarding listen-address 2001:db8::ffff + set service dns forwarding allow-from 192.168.1.0/24 + set service dns forwarding allow-from 2001:db8::/64 + +Operation +========= + +.. opcmd:: reset dns forwarding <all | domain> + + Resets the local DNS forwarding cache database. You can reset the cache + for all entries or only for entries to a specific domain. + +.. opcmd:: restart dns forwarding + + Restarts the DNS recursor process. This also invalidates the local DNS + forwarding cache. + + +.. _dynamic-dns: + +########### +Dynamic DNS +########### + +VyOS is able to update a remote DNS record when an interface gets a new IP +address. In order to do so, VyOS includes ddclient_, a Perl script written for +this only one purpose. + +ddclient_ uses two methods to update a DNS record. The first one will send +updates directly to the DNS daemon, in compliance with :rfc:`2136`. The second +one involves a third party service, like DynDNS.com or any other similar +website. This method uses HTTP requests to transmit the new IP address. You +can configure both in VyOS. + +Configuration +============= + +:rfc:`2136` Based +----------------- + +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> + + Create new :rfc:`2136` DNS update configuration which will update the IP + address assigned to `<interface>` on the service you configured under + `<service-name>`. + +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> + key <keyfile> + + File identified by `<keyfile>` containing the secret RNDC key shared with + remote DNS server. + +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> + server <server> + + Configure the DNS `<server>` IP/FQDN used when updating this dynamic + assignment. + +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> + zone <zone> + + Configure DNS `<zone>` to be updated. + +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> + record <record> + + Configure DNS `<record>` which should be updated. This can be set multiple + times. + +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> + ttl <ttl> + + Configure optional TTL value on the given resource record. This defaults to + 600 seconds. + +Example +^^^^^^^ + +* Register DNS record ``example.vyos.io`` on DNS server ``ns1.vyos.io`` +* Use auth key file at ``/config/auth/my.key`` +* Set TTL to 300 seconds + +.. code-block:: none + + vyos@vyos# show service dns dynamic + interface eth0.7 { + rfc2136 VyOS-DNS { + key /config/auth/my.key + record example.vyos.io + server ns1.vyos.io + ttl 300 + zone vyos.io + } + } + +This will render the following ddclient_ configuration entry: + +.. code-block:: none + + # + # ddclient configuration for interface "eth0.7": + # + use=if, if=eth0.7 + + # RFC2136 dynamic DNS configuration for example.vyos.io.vyos.io + server=ns1.vyos.io + protocol=nsupdate + password=/config/auth/my.key + ttl=300 + zone=vyos.io + example.vyos.io + +.. note:: You can also keep different DNS zone updated. Just create a new + config node: ``set service dns dynamic interface <interface> rfc2136 + <other-service-name>`` + +HTTP based services +------------------- + +VyOS is also able to use any service relying on protocols supported by ddclient. + +To use such a service, one must define a login, password, one or multiple +hostnames, protocol and server. + +.. cfgcmd:: set service dns dynamic interface <interface> service <service> + host-name <hostname> + + Setup the dynamic DNS hostname `<hostname>` associated with the DynDNS + provider identified by `<service>` when the IP address on interface + `<interface>` changes. + +.. cfgcmd:: set service dns dynamic interface <interface> service <service> + login <username> + + Configure `<username>` used when authenticating the update request for + DynDNS service identified by `<service>`. + For Namecheap, set the <domain> you wish to update. + +.. cfgcmd:: set service dns dynamic interface <interface> service <service> + password <password> + + Configure `<password>` used when authenticating the update request for + DynDNS service identified by `<service>`. + +.. cfgcmd:: set service dns dynamic interface <interface> service <service> + protocol <protocol> + + When a ``custom`` DynDNS provider is used the protocol used for communicating + to the provider must be specified under `<protocol>`. See the embedded + completion helper for available protocols. + +.. cfgcmd:: set service dns dynamic interface <interface> service <service> + server <server> + + When a ``custom`` DynDNS provider is used the `<server>` where update + requests are being sent to must be specified. + +Example: +^^^^^^^^ + +Use DynDNS as your preferred provider: + +.. code-block:: none + + set service dns dynamic interface eth0 service dyndns + set service dns dynamic interface eth0 service dyndns login my-login + set service dns dynamic interface eth0 service dyndns password my-password + set service dns dynamic interface eth0 service dyndns host-name my-dyndns-hostname + +.. note:: Multiple services can be used per interface. Just specify as many + services per interface as you like! + +Running Behind NAT +------------------ + +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. + +ddclient_ has another way to determine the WAN IP address. This is controlled +by: + +.. cfgcmd:: set service dns dynamic interface <interface> use-web url <url> + + Use configured `<url>` to determine your IP address. ddclient_ will load + `<url>` and tries to extract your IP address from the response. + +.. cfgcmd:: set service dns dynamic interface <interface> use-web skip <pattern> + + ddclient_ will skip any address located before the string set in `<pattern>`. + +.. _ddclient: https://github.com/ddclient/ddclient diff --git a/docs/configuration/service/https.rst b/docs/configuration/service/https.rst new file mode 100644 index 00000000..b9c691da --- /dev/null +++ b/docs/configuration/service/https.rst @@ -0,0 +1,181 @@ +.. _http-api: + +######## +HTTP-API +######## + +Enabling HTTP-API +----------------- + +VyOS HTTP API can be enabled through the ``set service https api`` command. + +.. code-block:: none + + set service https api debug + set service https api keys id MY-HTTP-API-ID key MY-HTTP-API-PLAINTEXT-KEY + +The local API process listens on localhost:8080, and nginx exposes it on all +virtual servers, by default. For the purpose of illustration below, we will +assume nginx is running at https://192.168.122.127. + +One can limit proxying to specific listen addresses/ports/server-names by +defining a ``service https virtual-host <id>``, and setting ``service https +api-restrict virtual-host <id>``. + +.. code-block:: none + + set service https virtual-host example listen-address 192.168.122.127 + set service https virtual-host example listen-port 44302 + set service https virtual-host example server-name example.net + + set service https api-restrict virtual-host example + +In this example, nginx will proxy only those requests to +192.168.122.127:44302 or example.net:44302 (assuming the DNS record is +viable). Omitting any of listen-address, listen-port, or server-name, will +leave appropriate defaults in the nginx directive. Multiple instances of +``service https api-restrict virtual-host`` may be set. + +Configuration mode requests +--------------------------- + +In our example, we are creating a dummy interface and assigning an address to +it: + +.. code-block:: none + + curl -k -X POST -F data='{"op": "set", "path": ["interfaces", "dummy", "dum1", "address"], "value": "203.0.113.76/32"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/configure + +The ``/configure`` endpoint takes a request serialized in JSON. The only HTTP +method it uses is POST. Request data is passed in the ``data=`` field and the +API key is passed in the ``key=`` field. Key identifiers from the config are +purely informational and the application doesn't need to know them, they only +appear in the server logs to avoid exposing keys in log files, you only need +the key itself. + +Since internally there is no distinction between a path and a value, you can +omit the value field and include the value in the path like it's done in the +shell commands: + +.. code-block:: none + + curl -k -X POST -F data='{"op": "set", "path": ["interfaces", "dummy", "dum10", "address", "203.0.113.99/32"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/configure + +Separate value field make the semantics more clear though, and also makes it +easier to create a command template once and update it with different values +as needed. + +You can pass the ``set``, ``delete`` or ``comment`` command to it. +The API will push the command to the session and commit. + +To retrieve a value: + +.. code-block:: none + + curl -k -X POST -F data='{"op": "returnValue", "path": ["interfaces", "dummy", "dum1", "address"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve + +Use ``returnValues`` for multi-valued nodes. + + +Show config +""""""""""" + +To retrieve the full config under a path: + +.. code-block:: none + + # curl -k -X POST -F data='{"op": "showConfig", "path": ["interfaces", "dummy"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve + +It will return: + +.. code-block:: none + + {"success": true, "data": {"dummy": {"dum1": {"address": "203.0.113.76/32"}}}, "error": null} + +Passing an empty path will return the full config: + +.. code-block:: none + + # curl -k -X POST -F data='{"op": "showConfig", "path": []}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve + + +Configuration management requests +--------------------------------- + +When saving or loading a configuration, the endpoint is ``/config-file`` and +you can pass the ``save`` or ``load`` command. + +If you don't specify the file when saving, it saves to ``/config/config.boot``. +Here's an example: + +.. code-block:: none + + # curl -k -X POST -F key=MY-HTTP-API-PLAINTEXT-KEY -Fdata='{"op": "save", "file": "/config/config.boot"}' https://192.168.122.127/config-file + +Image management requests +------------------------- + +One may ``add`` or ``delete`` a system image using the endpoint ``/image``. +Here are the respective examples: + +``add`` from ``url``. Here we use the URL of the latest rolling release: + +.. code-block:: none + + # curl -k -X POST -F data='{"op": "add", "url": "https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/image + +``delete`` by image ``name``. For example: + +.. code-block:: none + + # curl -k -X POST -F data='{"op": "delete", "name": "1.3-rolling-202006070117"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/image + +To list the available system images by name, one may use the operational mode +request ``show`` discussed in the next section; in this setting it would be: + +.. code-block:: none + + # curl -k -X POST -F data='{"op": "show", "path": ["system", "image"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show + +Operational mode requests +------------------------- + +It is possible to run ``show`` and ``generate`` commands: + + +Request: + +.. code-block:: none + + curl -k -X POST -F data='{"op": "generate", "path": ["wireguard", "default-keypair"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/generate + +Response: + +.. code-block:: none + + {"success": true, "data": "", "error": null} + +Request: + +.. code-block:: none + + curl -k -X POST -F data='{"op": "show", "path": ["wireguard", "keypairs", "pubkey", "default"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show + +Response: + +.. code-block:: none + + {"success": true, "data": "<some pubkey>=\n", "error": null} + +Request: + +.. code-block:: none + + curl -k -X POST -F data='{"op": "show", "path": ["ip", "route"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show + +Response: + +.. code-block:: none + + {"success": true, "data": "Codes: K - kernel route, C - connected, S - static, R - RIP,\n O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP,\n T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP,\n F - PBR, f - OpenFabric,\n > - selected route, * - FIB route, q - queued route, r - rejected route\n\nS>* 0.0.0.0/0 [210/0] via 192.168.100.1, eth0, 01:41:05\nC>* 192.168.0.0/24 is directly connected, eth1, 01:41:09\nC>* 192.168.100.0/24 is directly connected, eth0, 01:41:05\nC>* 203.0.113.76/32 is directly connected, dum1, 01:38:40\n", "error": null} + diff --git a/docs/configuration/service/index.rst b/docs/configuration/service/index.rst new file mode 100644 index 00000000..fb194239 --- /dev/null +++ b/docs/configuration/service/index.rst @@ -0,0 +1,25 @@ +####### +Service +####### + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + broadcast-relay + conntrack-sync + console-server + dhcp-relay + dhcp-server + dns + https + ipoe-server + lldp + mdns + pppoe-server + router-advert + snmp + ssh + tftp-server + webproxy diff --git a/docs/configuration/service/ipoe-server.rst b/docs/configuration/service/ipoe-server.rst new file mode 100644 index 00000000..7858ff19 --- /dev/null +++ b/docs/configuration/service/ipoe-server.rst @@ -0,0 +1,149 @@ +.. include:: /_include/need_improvement.txt + +.. _ipoe_server: + +########### +IPoE Server +########### + +VyOS utilizes `accel-ppp`_ to provide :abbr:`IPoE (Internet Protocol over +Ethernet)` server functionality. It can be used with local authentication +(mac-address) or a connected RADIUS server. + +IPoE is a method of delivering an IP payload over an Ethernet-based access +network or an access network using bridged Ethernet over Asynchronous Transfer +Mode (ATM) without using PPPoE. It directly encapsulates the IP datagrams in +Ethernet frames, using the standard :rfc:`894` encapsulation. + +The use of IPoE addresses the disadvantage that PPP is unsuited for multicast +delivery to multiple users. Typically, IPoE uses Dynamic Host Configuration +Protocol and Extensible Authentication Protocol to provide the same +functionality as PPPoE, but in a less robust manner. + +.. note:: Please be aware, due to an upstream bug, config changes/commits + will restart the ppp daemon and will reset existing IPoE sessions, + in order to become effective. + +Configuration +============= + +IPoE can be configure on different interfaces, it will depend on each specific +situation which interface will provide IPoE to clients. The clients mac address +and the incoming interface is being used as control parameter, to authenticate +a client. + +The example configuration below will assign an IP to the client on the incoming +interface eth2 with the client mac address 08:00:27:2f:d8:06. Other DHCP +discovery requests will be ignored, unless the client mac has been enabled in +the configuration. + +.. code-block:: none + + set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 + set service ipoe-server authentication mode 'local' + set service ipoe-server dns-server server-1 '10.10.1.1' + set service ipoe-server dns-server server-2 '10.10.1.2' + set service ipoe-server interface eth2 client-subnet '192.168.0.0/24' + + +The first address of the parameter ``client-subnet``, will be used as the +default gateway. Connected sessions can be checked via the ``show ipoe-server +sessions`` command. + +.. code-block:: none + + vyos@vyos:~$ show ipoe-server sessions + + ifname | called-sid | calling-sid | ip | ip6 | ip6-dp | rate-limit | state | uptime | sid + -------+------------+-------------------+-------------+-----+--------+------------+--------+----------+------------------ + ipoe0 | eth2 | 08:00:27:2f:d8:06 | 192.168.0.2 | | | | active | 00:45:05 | dccc870fd3134612 + + +IPv6 SLAAC and IA-PD +-------------------- + +To configure IPv6 assignments for clients, two options need to be configured. +A global prefix which is terminated on the clients cpe and a delegated prefix, +the client can use for devices routed via the clients cpe. + +IPv6 DNS addresses are optional. + +.. code-block:: none + + set service ipoe-server authentication interface eth3 mac-address 08:00:27:2F:D8:06 + set service ipoe-server authentication mode 'local' + set service ipoe-server client-ipv6-pool delegate-prefix '2001:db8:1::/48,56' + set service ipoe-server client-ipv6-pool prefix '2001:db8::/48,64' + set service ipoe-server dnsv6-server server-1 '2001:db8::' + set service ipoe-server dnsv6-server server-2 '2001:db8:aaa::' + set service ipoe-server dnsv6-server server-3 '2001:db8:bbb::' + set service ipoe-server interface eth3 client-subnet '192.168.1.0/24' + +.. code-block:: none + + vyos@ipoe-server# run sh ipoe-server sessions + ifname | called-sid | calling-sid | ip | ip6 | ip6-dp | rate-limit | state | uptime | sid + -------+------------+-------------------+-------------+---------------------------------+-----------------+------------+--------+----------+------------------ + ipoe0 | eth3 | 08:00:27:2f:d8:06 | 192.168.1.2 | 2001:db8::a00:27ff:fe2f:d806/64 | 2001:db8:1::/56 | | active | 01:02:59 | 4626faf71b12cc25 + + +The clients :abbr:`CPE (Customer Premises Equipment)` can now communicate via +IPv4 or IPv6. All devices behind ``2001:db8::a00:27ff:fe2f:d806/64`` can use +addresses from ``2001:db8:1::/56`` and can globally communicate without the +need of any NAT rules. + +Automatic VLAN creation +----------------------- + +To create VLANs per user during runtime, the following settings are required on +a per interface basis. VLAN ID and VLAN range can be present in the +configuration at the same time. + +.. code-block:: none + + set service ipoe-server interface eth2 network vlan + set service ipoe-server interface eth2 vlan-id 100 + set service ipoe-server interface eth2 vlan-id 200 + set service ipoe-server interface eth2 vlan-range 1000-2000 + set service ipoe-server interface eth2 vlan-range 2500-2700 + +RADIUS Setup +------------ + +To use a RADIUS server for authentication and bandwidth-shaping, the following +example configuration can be used. + +.. code-block:: none + + set service ipoe-server authentication mode 'radius' + set service ipoe-server authentication radius-server 10.100.100.1 secret 'password' + +Bandwidth Shaping +================= + +Bandwidth rate limits can be set for local users within the configuration or +via RADIUS based attributes. + +Bandwidth Shaping for local users +--------------------------------- + +The rate-limit is set in kbit/sec. + +.. code-block:: none + + set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 rate-limit download '500' + set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 rate-limit upload '500' + set service ipoe-server authentication mode 'local' + set service ipoe-server dns-server server-1 '10.10.1.1' + set service ipoe-server dns-server server-2 '10.10.1.2' + set service ipoe-server interface eth2 client-subnet '192.168.0.0/24' + +.. code-block:: none + + vyos@vyos# run show ipoe-server sessions + + ifname | called-sid | calling-sid | ip | ip6 | ip6-dp | rate-limit | state | uptime | sid + -------+------------+-------------------+-------------+-----+--------+------------+--------+----------+------------------ + ipoe0 | eth2 | 08:00:27:2f:d8:06 | 192.168.0.2 | | | 500/500 | active | 00:00:05 | dccc870fd31349fb + +.. include:: /_include/common-references.txt diff --git a/docs/configuration/service/lldp.rst b/docs/configuration/service/lldp.rst new file mode 100644 index 00000000..aa357211 --- /dev/null +++ b/docs/configuration/service/lldp.rst @@ -0,0 +1,142 @@ +.. _lldp: + +#### +LLDP +#### + +:abbr:`LLDP (Link Layer Discovery Protocol)` is a vendor-neutral link layer +protocol in the Internet Protocol Suite used by network devices for advertising +their identity, capabilities, and neighbors on an IEEE 802 local area network, +principally wired Ethernet. The protocol is formally referred to by the IEEE +as Station and Media Access Control Connectivity Discovery specified in IEEE +802.1AB and IEEE 802.3-2012 section 6 clause 79. + +LLDP performs functions similar to several proprietary protocols, such as +:abbr:`CDP (Cisco Discovery Protocol)`, +:abbr:`FDP (Foundry Discovery Protocol)`, +:abbr:`NDP (Nortel Discovery Protocol)` and :abbr:`LLTD (Link Layer Topology +Discovery)`. + +Information gathered with LLDP is stored in the device as a :abbr:`MIB +(Management Information Database)` and can be queried with :abbr:`SNMP (Simple +Network Management Protocol)` as specified in :rfc:`2922`. The topology of an +LLDP-enabled network can be discovered by crawling the hosts and querying this +database. Information that may be retrieved include: + +* System Name and Description +* Port name and description +* VLAN name +* IP management address +* System capabilities (switching, routing, etc.) +* MAC/PHY information +* MDI power +* Link aggregation + +Configuration +============= + +.. cfgcmd:: set service lldp + + Enable LLDP service + +.. cfgcmd:: set service lldp management-address <address> + + Define IPv4/IPv6 management address transmitted via LLDP. Multiple addresses + can be defined. Only addresses connected to the system will be transmitted. + +.. cfgcmd:: set service lldp interface <interface> + + Enable transmission of LLDP information on given `<interface>`. You can also + say ``all`` here so LLDP is turned on on every interface. + +.. cfgcmd:: set service lldp interface <interface> disable + + 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 + + Enable SNMP queries of the LLDP database + +.. cfgcmd:: set service lldp legacy-protocols <cdp|edp|fdp|sonmp> + + Enable given legacy protocol on this LLDP instance. Legacy protocols include: + + * ``cdp`` - Listen for CDP for Cisco routers/switches + * ``edp`` - Listen for EDP for Extreme routers/switches + * ``fdp`` - Listen for FDP for Foundry routers/switches + * ``sonmp`` - Listen for SONMP for Nortel routers/switches + +Operation +========= + +.. opcmd:: show lldp neighbors + + Displays information about all neighbors discovered via LLDP. + + .. code-block:: none + + vyos@vyos:~$ show lldp neighbors + Capability Codes: R - Router, B - Bridge, W - Wlan r - Repeater, S - Station + D - Docsis, T - Telephone, O - Other + + Device ID Local Proto Cap Platform Port ID + --------- ----- ----- --- -------- ------- + BR2.vyos.net eth0 LLDP R VyOS 1.2.4 eth1 + BR3.vyos.net eth0 LLDP RB VyOS 1.2.4 eth2 + SW1.vyos.net eth0 LLDP B Cisco IOS Software GigabitEthernet0/6 + +.. opcmd:: show lldp neighbors detail + + Get detailed information about LLDP neighbors. + + .. code-block:: none + + vyos@vyos:~$ show lldp neighbors detail + ------------------------------------------------------------------------------- + LLDP neighbors: + ------------------------------------------------------------------------------- + Interface: eth0, via: LLDP, RID: 28, Time: 0 day, 00:24:33 + Chassis: + ChassisID: mac 00:53:00:01:02:c9 + SysName: BR2.vyos.net + SysDescr: VyOS 1.3-rolling-201912230217 + MgmtIP: 192.0.2.1 + MgmtIP: 2001:db8::ffff + Capability: Bridge, on + Capability: Router, on + Capability: Wlan, off + Capability: Station, off + Port: + PortID: mac 00:53:00:01:02:c9 + PortDescr: eth0 + TTL: 120 + PMD autoneg: supported: no, enabled: no + MAU oper type: 10GigBaseCX4 - X copper over 8 pair 100-Ohm balanced cable + VLAN: 201 eth0.201 + VLAN: 205 eth0.205 + LLDP-MED: + Device Type: Network Connectivity Device + Capability: Capabilities, yes + Capability: Policy, yes + Capability: Location, yes + Capability: MDI/PSE, yes + Capability: MDI/PD, yes + Capability: Inventory, yes + Inventory: + Hardware Revision: None + Software Revision: 4.19.89-amd64-vyos + Firmware Revision: 6.00 + Serial Number: VMware-42 1d 83 b9 fe c1 bd b2-7 + Manufacturer: VMware, Inc. + Model: VMware Virtual Platform + Asset ID: No Asset Tag + ------------------------------------------------------------------------------- + +.. opcmd:: show lldp neighbors interface <interface> + + Show LLDP neighbors connected via interface `<interface>`. + +.. opcmd:: show log lldp + + Used for troubleshooting. diff --git a/docs/configuration/service/mdns.rst b/docs/configuration/service/mdns.rst new file mode 100644 index 00000000..9d6a292a --- /dev/null +++ b/docs/configuration/service/mdns.rst @@ -0,0 +1,44 @@ +mDNS Repeater +------------- + +Starting with VyOS 1.2 a :abbr:`mDNS (Multicast DNS)` repeater functionality is +provided. Additional information can be obtained from +https://en.wikipedia.org/wiki/Multicast_DNS. + +Multicast DNS uses the 224.0.0.251 address, which is "administratively scoped" +and does not leave the subnet. It retransmits mDNS packets from one interface +to other interfaces. This enables support for e.g. Apple Airplay devices across +multiple VLANs. + +Since the mDNS protocol sends the AA records in the packet itself, the repeater +does not need to forge the source address. Instead, the source address is of +the interface that repeats the packet. + +Configuration +============= + +.. cfgcmd:: set service mdns repeater interface <interface> + + To enable mDNS repeater you need to configure at least two interfaces. To + re-broadcast all incoming mDNS packets from any interface configured here to + any other interface configured under this section. + +.. cfgcmd:: set service mdns repeater disable + + mDNS repeater can be temporarily disabled without deleting the service using + +.. note:: You can not run this in a VRRP setup, if multiple mDNS repeaters + are launched in a subnet you will experience the mDNS packet storm death! + +Example +======= + +To listen on both `eth0` and `eth1` mDNS packets and also repeat packets +received on `eth0` to `eth1` (and vice-versa) use the following commands: + +.. code-block:: none + + set service mdns repeater interface 'eth0' + set service mdns repeater interface 'eth1' + +.. _`Multicast DNS`: https://en.wikipedia.org/wiki/Multicast_DNS diff --git a/docs/configuration/service/pppoe-advert.disable b/docs/configuration/service/pppoe-advert.disable new file mode 100644 index 00000000..bbb82202 --- /dev/null +++ b/docs/configuration/service/pppoe-advert.disable @@ -0,0 +1,2 @@ +pppoe-advert +############
\ No newline at end of file diff --git a/docs/configuration/service/pppoe-server.rst b/docs/configuration/service/pppoe-server.rst new file mode 100644 index 00000000..8d895f9d --- /dev/null +++ b/docs/configuration/service/pppoe-server.rst @@ -0,0 +1,407 @@ +.. _pppoe-server: + +############ +PPPoE Server +############ + +VyOS utilizes `accel-ppp`_ to provide PPPoE server functionality. It can +be used with local authentication or a connected RADIUS server. + +.. note:: Please be aware, due to an upstream bug, config + changes/commits will restart the ppp daemon and will reset existing + PPPoE connections from connected users, in order to become effective. + +Configuration +============= + + +First steps +----------- + + +.. cfgcmd:: set service pppoe-server access-concentrator <name> + + Use this command to set a name for this PPPoE-server access + concentrator. + +.. cfgcmd:: set service pppoe-server authentication mode <local | radius> + + Use this command to define whether your PPPoE clients will locally + authenticate in your VyOS system or in RADIUS server. + +.. cfgcmd:: set service pppoe-server authentication local-users username + <name> password <password> + + Use this command to configure the username and the password of a + locally configured user. + +.. cfgcmd:: set service pppoe-server interface <interface> + + Use this command to define the interface the PPPoE server will use to + listen for PPPoE clients. + +.. cfgcmd:: set service pppoe-server gateway-address <address> + + Use this command to configure the local gateway IP address. + +.. cfgcmd:: set service pppoe-server name-server <address> + + Use this command to set the IPv4 or IPv6 address of every Doman Name + Server you want to configure. They will be propagated to PPPoE + clients. + + +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 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 + + set service pppoe-server client-ip-pool start '10.1.1.100' + set service pppoe-server client-ip-pool stop '10.1.1.111' + + +**Client IP subnets via CIDR notation** + +.. cfgcmd:: set service pppoe-server client-ip-pool subnet <address> + + 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 and it must be within a /24 subnet. + +.. 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/24' + set service pppoe-server client-ip-pool subnet '10.1.3.0/24' + + +**RADIUS based IP pools (Framed-IP-Address)** + +To use a radius server, you need to switch to authentication mode RADIUS +and then configure it. + +.. cfgcmd:: set service pppoe-server authentication radius server <address> + key <secret> + + Use this command to configure the IP address and the shared secret + key of your RADIUS server. You can have multiple RADIUS servers + configured if you wish to achieve redundancy. + + +.. code-block:: none + + set service pppoe-server access-concentrator 'ACN' + set service pppoe-server authentication mode 'radius' + set service pppoe-server authentication radius server 10.1.100.1 key 'secret' + set service pppoe-server interface 'eth1' + set service pppoe-server gateway-address '10.1.1.2' + +RADIUS provides the IP addresses in the example above via +Framed-IP-Address. + +**RADIUS sessions management DM/CoA** + +.. cfgcmd:: set service pppoe-server authentication radius dynamic-author + <key | port | server> + + Use this command to configure Dynamic Authorization Extensions to + RADIUS so that you can remotely disconnect sessions and change some + authentication parameters. + +.. code-block:: none + + set service pppoe-server authentication radius dynamic-author key 'secret123' + set service pppoe-server authentication radius dynamic-author port '3799' + set service pppoe-server authentication radius dynamic-author server '10.1.1.2' + + +Example, from radius-server send command for disconnect client with +username test + +.. code-block:: none + + root@radius-server:~# echo "User-Name=test" | radclient -x 10.1.1.2:3799 + disconnect secret123 + +You can also use another attributes for identify client for disconnect, +like Framed-IP-Address, Acct-Session-Id, etc. Result commands appears in +log. + +.. code-block:: none + + show log | match Disconnect* + +Example for changing rate-limit via RADIUS CoA. + +.. code-block:: none + + echo "User-Name=test,Filter-Id=5000/4000" | radclient 10.1.1.2:3799 coa + secret123 + +Filter-Id=5000/4000 (means 5000Kbit down-stream rate and 4000Kbit +up-stream rate) If attribute Filter-Id redefined, replace it in RADIUS +CoA request. + +Automatic VLAN Creation +----------------------- + +.. cfgcmd:: set service pppoe-server interface <interface> + <vlan-id | vlan range> <text> + + VLAN's can be created by accel-ppp on the fly via the use of a Kernel + module named `vlan_mon`, which is monitoring incoming vlans and + creates the necessary VLAN if required and allowed. VyOS supports the + use of either VLAN ID's or entire ranges, both values can be defined + at the same time for an interface. When configured, the PPPoE will + create the necessary VLANs when required. Once the user session has + been cancelled and the VLAN is not needed anymore, VyOS will remove + it again. + +.. code-block:: none + + set service pppoe-server interface eth3 vlan-id 100 + set service pppoe-server interface eth3 vlan-id 200 + set service pppoe-server interface eth3 vlan-range 500-1000 + set service pppoe-server interface eth3 vlan-range 2000-3000 + + + +Bandwidth Shaping +----------------- + +Bandwidth rate limits can be set for local users or RADIUS based +attributes. + +For Local Users +^^^^^^^^^^^^^^^ + +.. cfgcmd:: set service pppoe-server authentication local-users username <name> + rate-limit <download | upload> + + Use this command to configure a data-rate limit to PPPOoE clients for + traffic download or upload. The rate-limit is set in kbit/sec. + +.. code-block:: none + + set service pppoe-server access-concentrator 'ACN' + set service pppoe-server authentication local-users username foo password 'bar' + 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 name-server '10.100.100.1' + set service pppoe-server name-server '10.100.200.1' + set service pppoe-server interface 'eth1' + set service pppoe-server gateway-address '10.1.1.2' + + +Once the user is connected, the user session is using the set limits and +can be displayed via 'show pppoe-server sessions'. + +.. code-block:: none + + show pppoe-server sessions + ifname | username | ip | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes + -------+----------+------------+-------------------+-------------+--------+----------+----------+---------- + ppp0 | foo | 10.1.1.100 | 00:53:00:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B | 76 B + + +For RADIUS users +^^^^^^^^^^^^^^^^ + +The current attribute 'Filter-Id' is being used as default and can be +setup within RADIUS: + +Filter-Id=2000/3000 (means 2000Kbit down-stream rate and 3000Kbit +up-stream rate) + +The command below enables it, assuming the RADIUS connection has been +setup and is working. + +.. cfgcmd:: set service pppoe-server authentication radius rate-limit enable + + Use this command to enable bandwidth shaping via RADIUS. + +Other attributes can be used, but they have to be in one of the +dictionaries in */usr/share/accel-ppp/radius*. + + +Load Balancing +-------------- + + +.. cfgcmd:: set service pppoe-server pado-delay <number-of-ms> + sessions <number-of-sessions> + + Use this command to enable the delay of PADO (PPPoE Active Discovery + Offer) packets, which can be used as a session balancing mechanism + with other PPPoE servers. + +.. code-block:: none + + set service pppoe-server pado-delay 50 sessions '500' + set service pppoe-server pado-delay 100 sessions '1000' + set service pppoe-server pado-delay 300 sessions '3000' + +In the example above, the first 499 sessions connect without delay. PADO +packets will be delayed 50 ms for connection from 500 to 999, this trick +allows other PPPoE servers send PADO faster and clients will connect to +other servers. Last command says that this PPPoE server can serve only +3000 clients. + + +IPv6 +---- + +IPv6 client's prefix assignment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set service pppoe-server client-ipv6-pool prefix <address> + mask <number-of-bits> + + Use this comand to set the IPv6 address pool from which a PPPoE + client will get an IPv6 prefix of your defined length (mask) to + terminate the PPPoE endpoint at their side. The mask length can be + set from 48 to 128 bit long, the default value is 64. + + +IPv6 Prefix Delegation +^^^^^^^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set service pppoe-server client-ipv6-pool delegate <address> + delegation-prefix <number-of-bits> + + Use this command to configure DHCPv6 Prefix Delegation (RFC3633). You + will have to set your IPv6 pool and the length of the delegation + prefix. From the defined IPv6 pool you will be handing out networks + of the defined length (delegation-prefix). The length of the + delegation prefix can be set from 32 to 64 bit long. + + +Maintenance mode +================ + +.. opcmd:: set pppoe-server maintenance-mode <enable | disable> + + For network maintenance, it's a good idea to direct users to a backup + server so that the primary server can be safely taken out of service. + It's possible to switch your PPPoE server to maintenance mode where + it maintains already established connections, but refuses new + connection attempts. + + +Checking connections +==================== + +.. opcmd:: show pppoe-server sessions + + Use this command to locally check the active sessions in the PPPoE + server. + + +.. code-block:: none + + show pppoe-server sessions + ifname | username | ip | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes + -------+----------+------------+-------------------+-------------+--------+----------+----------+---------- + ppp0 | foo | 10.1.1.100 | 00:53:00:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B | 76 B + + +Per default the user session is being replaced if a second +authentication request succeeds. Such session requests can be either +denied or allowed entirely, which would allow multiple sessions for a +user in the latter case. If it is denied, the second session is being +rejected even if the authentication succeeds, the user has to terminate +its first session and can then authentication again. + +.. code-block:: none + + vyos@# set service pppoe-server session-control + Possible completions: + disable Disables session control + deny Deny second session authorization + + + + + + +Examples +======== + +IPv4 +---- + +The example below uses ACN as access-concentrator name, assigns an +address from the pool 10.1.1.100-111, terminates at the local endpoint +10.1.1.1 and serves requests only on eth1. + +.. code-block:: none + + 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 interface eth1 + set service pppoe-server gateway-address '10.1.1.2' + set service pppoe-server name-server '10.100.100.1' + set service pppoe-server name-server '10.100.200.1' + + + +Dual-Stack IPv4/IPv6 provisioning with Prefix Delegation +-------------------------------------------------------- + +The example below covers a dual-stack configuration via pppoe-server. + +.. code-block:: none + + 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-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 name-server '10.1.1.1' + set service pppoe-server name-server '2001:db8:4860::8888' + set service pppoe-server interface 'eth2' + set service pppoe-server gateway-address '10.100.100.1' + +The client, once successfully authenticated, will receive an IPv4 and an +IPv6 /64 address to terminate the pppoe endpoint on the client side and +a /56 subnet for the clients internal use. + +.. code-block:: none + + vyos@pppoe-server:~$ sh pppoe-server sessions + ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes + --------+----------+-------------+--------------------------+---------------------+-------------------+------------+--------+----------+----------+---------- + ppp0 | test | 192.168.0.1 | 2001:db8:8002:0:200::/64 | 2001:db8:8003::1/56 | 00:53:00:12:42:eb | | active | 00:00:49 | 875 B | 2.1 KiB + +.. include:: /_include/common-references.txt diff --git a/docs/configuration/service/router-advert.rst b/docs/configuration/service/router-advert.rst new file mode 100644 index 00000000..36fa600d --- /dev/null +++ b/docs/configuration/service/router-advert.rst @@ -0,0 +1,97 @@ +.. _router-advert: + +##################### +Router Advertisements +##################### + +:abbr:`RAs (Router advertisements)` are described in :rfc:`4861#section-4.6.2`. +They are part of what is known as :abbr:`SLAAC (Stateless Address +Autoconfiguration)`. + + +Supported interface types: + + * bonding + * bridge + * ethernet + * l2tpv3 + * openvpn + * pseudo-ethernet + * tunnel + * vxlan + * wireguard + * wireless + * wirelessmodem + + +Enabling Advertisments +~~~~~~~~~~~~~~~~~~~~~~~ + +.. cfgcmd:: set service router-advert interface <interface> .... + +.. stop_vyoslinter + +.. csv-table:: + :header: "Field", "VyOS Option", "Description" + :widths: 10, 10, 20 + + "Cur Hop Limit", "hop-limit", "Hop count field of the outgoing RA packets" + """Managed address configuration"" flag", "managed-flag", "Tell hosts to use the administered stateful protocol (i.e. DHCP) for autoconfiguration" + """Other configuration"" flag", "other-config-flag", "Tell hosts to use the administered (stateful) protocol (i.e. DHCP) for autoconfiguration of other (non-address) information" + "MTU","link-mtu","Link MTU value placed in RAs, exluded in RAs if unset" + "Router Lifetime","default-lifetime","Lifetime associated with the default router in units of seconds" + "Reachable Time","reachable-time","Time, in milliseconds, that a node assumes a neighbor is reachable after having received a reachability confirmation" + "Retransmit Timer","retrans-timer","Time in milliseconds between retransmitted Neighbor Solicitation messages" + "Default Router Preference","default-preference","Preference associated with the default router" + "Interval", "interval", "Min and max intervals between unsolicited multicast RAs" + "DNSSL", "dnssl", "DNS search list to advertise" + "Name Server", "name-server", "Advertise DNS server per https://tools.ietf.org/html/rfc6106" + +.. start_vyoslinter + + +Advertising a Prefix +'''''''''''''''''''' + +.. cfgcmd:: set service router-advert interface <interface> prefix 2001:DB8::/32 + +.. stop_vyoslinter + +.. csv-table:: + :header: "VyOS Field", "Description" + :widths: 10,30 + + "no-autonomous-flag","Prefix can not be used for stateless address auto-configuration" + "no-on-link-flag","Prefix can not be used for on-link determination" + "preferred-lifetime","Time in seconds that the prefix will remain preferred (default 4 hours)" + "valid-lifetime","Time in seconds that the prefix will remain valid (default: 30 days)" + +.. start_vyoslinter + +Disabling Advertisements +~~~~~~~~~~~~~~~~~~~~~~~~ + +To disable advertisements without deleting the configuration: + +.. cfgcmd:: set service router-advert interface <interface> no-send-advert + +Example Configuration +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: none + + interface eth0.2 { + default-preference high + hop-limit 64 + interval { + max 600 + } + name-server 2001:db8::1 + name-server 2001:db8::2 + other-config-flag + prefix 2001:db8:beef:2::/64 { + valid-lifetime 2592000 + } + reachable-time 0 + retrans-timer 0 + } diff --git a/docs/configuration/service/salt-minion.disable b/docs/configuration/service/salt-minion.disable new file mode 100644 index 00000000..63df57a4 --- /dev/null +++ b/docs/configuration/service/salt-minion.disable @@ -0,0 +1,2 @@ +salt-minion +###########
\ No newline at end of file diff --git a/docs/configuration/service/snmp.rst b/docs/configuration/service/snmp.rst new file mode 100644 index 00000000..e962c1c5 --- /dev/null +++ b/docs/configuration/service/snmp.rst @@ -0,0 +1,273 @@ +.. _snmp: + +#### +SNMP +#### + +:abbr:`SNMP (Simple Network Management Protocol)` is an Internet Standard +protocol for collecting and organizing information about managed devices on +IP networks and for modifying that information to change device behavior. +Devices that typically support SNMP include cable modems, routers, switches, +servers, workstations, printers, and more. + +SNMP is widely used in network management for network monitoring. SNMP exposes +management data in the form of variables on the managed systems organized in +a management information base (MIB_) which describe the system status and +configuration. These variables can then be remotely queried (and, in some +circumstances, manipulated) by managing applications. + +Three significant versions of SNMP have been developed and deployed. SNMPv1 is +the original version of the protocol. More recent versions, SNMPv2c and SNMPv3, +feature improvements in performance, flexibility and security. + +SNMP is a component of the Internet Protocol Suite as defined by the Internet +Engineering Task Force (IETF). It consists of a set of standards for network +management, including an application layer protocol, a database schema, and a +set of data objects. + +Overview and basic concepts +=========================== + +In typical uses of SNMP, one or more administrative computers called managers +have the task of monitoring or managing a group of hosts or devices on a +computer network. Each managed system executes a software component called an +agent which reports information via SNMP to the manager. + +An SNMP-managed network consists of three key components: + +* Managed devices +* Agent - software which runs on managed devices +* Network management station (NMS) - software which runs on the manager + +A managed device is a network node that implements an SNMP interface that +allows unidirectional (read-only) or bidirectional (read and write) access to +node-specific information. Managed devices exchange node-specific information +with the NMSs. Sometimes called network elements, the managed devices can be +any type of device, including, but not limited to, routers, access servers, +switches, cable modems, bridges, hubs, IP telephones, IP video cameras, +computer hosts, and printers. + +An agent is a network-management software module that resides on a managed +device. An agent has local knowledge of management information and translates +that information to or from an SNMP-specific form. + +A network management station executes applications that monitor and control +managed devices. NMSs provide the bulk of the processing and memory resources +required for network management. One or more NMSs may exist on any managed +network. + +.. figure:: /_static/images/service_snmp_communication_principles_diagram.png + :scale: 20 % + :alt: Principle of SNMP Communication + + Image thankfully borrowed from + https://en.wikipedia.org/wiki/File:SNMP_communication_principles_diagram.PNG + which is under the GNU Free Documentation License + +.. note:: VyOS SNMP supports both IPv4 and IPv6. + +SNMP Protocol Versions +====================== + +VyOS itself supports SNMPv2_ (version 2) and SNMPv3_ (version 3) where the +later is recommended because of improved security (optional authentication and +encryption). + +SNMPv2 +------ + +SNMPv2 is the original and most commonly used version. For authorizing clients, +SNMP uses the concept of communities. Communities may have authorization set +to read only (this is most common) or to read and write (this option is not +actively used in VyOS). + +SNMP can work synchronously or asynchronously. In synchronous communication, +the monitoring system queries the router periodically. In asynchronous, the +router sends notification to the "trap" (the monitoring host). + +SNMPv2 does not support any authentication mechanisms, other than client source +address, so you should specify addresses of clients allowed to monitor the +router. Note that SNMPv2 also supports no encryption and always sends data in +plain text. + +Example +^^^^^^^ + +.. code-block:: none + + # Define a community + set service snmp community routers authorization ro + + # Allow monitoring access from the entire network + set service snmp community routers network 192.0.2.0/24 + set service snmp community routers network 2001::db8:ffff:eeee::/64 + + # Allow monitoring access from specific addresses + set service snmp community routers client 203.0.113.10 + set service snmp community routers client 203.0.113.20 + + # Define optional router information + set service snmp location "UK, London" + set service snmp contact "admin@example.com" + + # Trap target if you want asynchronous communication + set service snmp trap-target 203.0.113.10 + + # Listen only on specific IP addresses (port defaults to 161) + set service snmp listen-address 172.16.254.36 port 161 + set service snmp listen-address 2001:db8::f00::1 + + +SNMPv3 +------ + +SNMPv3 (version 3 of the SNMP protocol) introduced a whole slew of new security +related features that have been missing from the previous versions. Security +was one of the biggest weakness of SNMP until v3. Authentication in SNMP +Versions 1 and 2 amounts to nothing more than a password (community string) +sent in clear text between a manager and agent. Each SNMPv3 message contains +security parameters which are encoded as an octet string. The meaning of these +security parameters depends on the security model being used. + +The securityapproach in v3 targets: + +* Confidentiality – Encryption of packets to prevent snooping by an + unauthorized source. + +* Integrity – Message integrity to ensure that a packet has not been tampered + while in transit including an optional packet replay protection mechanism. + +* Authentication – to verify that the message is from a valid source. + +Example +^^^^^^^ + +* Let SNMP daemon listen only on IP address 192.0.2.1 +* Configure new SNMP user named "vyos" with password "vyos12345678" +* New user will use SHA/AES for authentication and privacy + +.. code-block:: none + + set service snmp listen-address 192.0.2.1 + set service snmp location 'VyOS Datacenter' + set service snmp v3 engineid '000000000000000000000002' + set service snmp v3 group default mode 'ro' + set service snmp v3 group default view 'default' + set service snmp v3 user vyos auth plaintext-password 'vyos12345678' + set service snmp v3 user vyos auth type 'sha' + set service snmp v3 user vyos group 'default' + set service snmp v3 user vyos privacy plaintext-password 'vyos12345678' + set service snmp v3 user vyos privacy type 'aes' + set service snmp v3 view default oid 1 + +After commit the plaintext passwords will be hashed and stored in your +configuration. The resulting LCI config will look like: + +.. code-block:: none + + vyos@vyos# show service snmp + listen-address 172.18.254.201 { + } + location "Wuerzburg, Dr.-Georg-Fuchs-Str. 8" + v3 { + engineid 000000000000000000000002 + group default { + mode ro + view default + } + user vyos { + auth { + encrypted-password 4e52fe55fd011c9c51ae2c65f4b78ca93dcafdfe + type sha + } + group default + privacy { + encrypted-password 4e52fe55fd011c9c51ae2c65f4b78ca93dcafdfe + type aes + } + } + view default { + oid 1 { + } + } + } + +You can test the SNMPv3 functionality from any linux based system, just run the +following command: ``snmpwalk -v 3 -u vyos -a SHA -A vyos12345678 -x AES +-X vyos12345678 -l authPriv 192.0.2.1 .1`` + +VyOS MIBs +========= + +All SNMP MIBs are located in each image of VyOS here: ``/usr/share/snmp/mibs/`` + +you are be able to download the files with the a activate ssh service like this + +.. code-block:: none + + scp -r vyos@your_router:/usr/share/snmp/mibs /your_folder/mibs + +SNMP Extensions +=============== + +To extend SNMP agent functionality, custom scripts can be executed every time +the agent is being called. This can be achieved by using +``arbitrary extensioncommands``. The first step is to create a functional +script of course, then upload it to your VyOS instance via the command +``scp your_script.sh vyos@your_router:/config/user-data``. +Once the script is uploaded, it needs to be configured via the command below. + + +.. code-block:: none + + set service snmp script-extensions extension-name my-extension script your_script.sh + commit + +.. stop_vyoslinter + +The OID ``.1.3.6.1.4.1.8072.1.3.2.3.1.1.4.116.101.115.116``, once called, will +contain the output of the extension. + +.. start_vyoslinter + +.. code-block:: none + + root@vyos:/home/vyos# snmpwalk -v2c -c public 127.0.0.1 nsExtendOutput1 + NET-SNMP-EXTEND-MIB::nsExtendOutput1Line."my-extension" = STRING: hello + NET-SNMP-EXTEND-MIB::nsExtendOutputFull."my-extension" = STRING: hello + NET-SNMP-EXTEND-MIB::nsExtendOutNumLines."my-extension" = INTEGER: 1 + NET-SNMP-EXTEND-MIB::nsExtendResult."my-extension" = INTEGER: 0 + +SolarWinds +========== + +If you happen to use SolarWinds Orion as NMS you can also use the Device +Templates Management. A template for VyOS can be easily imported. + +.. stop_vyoslinter + +Create a file named ``VyOS-1.3.6.1.4.1.44641.ConfigMgmt-Commands`` using the +following content: + + +.. code-block:: none + + <Configuration-Management Device="VyOS" SystemOID="1.3.6.1.4.1.44641"> + <Commands> + <Command Name="Reset" Value="set terminal width 0${CRLF}set terminal length 0"/> + <Command Name="Reboot" Value="reboot${CRLF}Yes"/> + <Command Name="EnterConfigMode" Value="configure"/> + <Command Name="ExitConfigMode" Value="commit${CRLF}exit"/> + <Command Name="DownloadConfig" Value="show configuration commands"/> + <Command Name="SaveConfig" Value="commit${CRLF}save"/> + <Command Name="Version" Value="show version"/> + <Command Name="MenuBased" Value="False"/> + <Command Name="VirtualPrompt" Value=":~"/> + </Commands> + </Configuration-Management> + +.. _MIB: https://en.wikipedia.org/wiki/Management_information_base +.. _SNMPv2: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2 +.. _SNMPv3: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_3 + +.. start_vyoslinter
\ No newline at end of file diff --git a/docs/configuration/service/ssh.rst b/docs/configuration/service/ssh.rst new file mode 100644 index 00000000..94249766 --- /dev/null +++ b/docs/configuration/service/ssh.rst @@ -0,0 +1,157 @@ +.. _ssh: + +### +SSH +### + +:abbr:`SSH (Secure Shell)` is a cryptographic network protocol for operating +network services securely over an unsecured network. The standard TCP port for +SSH is 22. The best known example application is for remote login to computer +systems by users. + +SSH provides a secure channel over an unsecured network in a client-server +architecture, connecting an SSH client application with an SSH server. Common +applications include remote command-line login and remote command execution, +but any network service can be secured with SSH. The protocol specification +distinguishes between two major versions, referred to as SSH-1 and SSH-2. + +The most visible application of the protocol is for access to shell accounts +on Unix-like operating systems, but it sees some limited use on Windows as +well. In 2015, Microsoft announced that they would include native support for +SSH in a future release. + +SSH was designed as a replacement for Telnet and for unsecured remote shell +protocols such as the Berkeley rlogin, rsh, and rexec protocols. +Those protocols send information, notably passwords, in plaintext, +rendering them susceptible to interception and disclosure using packet +analysis. The encryption used by SSH is intended to provide confidentiality +and integrity of data over an unsecured network, such as the Internet. + +.. note:: VyOS 1.1 supported login as user ``root``. This has been removed due + to tighter security in VyOS 1.2. + +.. seealso:: SSH :ref:`ssh_key_based_authentication` + +Configuration +============= + +.. cfgcmd:: set service ssh port <port> + + Enabling SSH only requires you to specify the port ``<port>`` you want SSH to + listen on. By default, SSH runs on port 22. + +.. cfgcmd:: set service ssh listen-address <address> + + Specify IPv4/IPv6 listen address of SSH server. Multiple addresses can be + defined. + +.. cfgcmd:: set service ssh ciphers <cipher> + + Define allowed ciphers used for the SSH connection. A number of allowed + ciphers can be specified, use multiple occurrences to allow multiple ciphers. + + List of supported ciphers: ``3des-cbc``, ``aes128-cbc``, ``aes192-cbc``, + ``aes256-cbc``, ``aes128-ctr``, ``aes192-ctr``, ``aes256-ctr``, + ``arcfour128``, ``arcfour256``, ``arcfour``, ``blowfish-cbc``, ``cast128-cbc`` + +.. cfgcmd:: set service ssh disable-password-authentication + + Disable password based authentication. Login via SSH keys only. This hardens + security! + +.. cfgcmd:: set service ssh disable-host-validation + + Disable the host validation through reverse DNS lookups - can speedup login + time when reverse lookup is not possible. + +.. cfgcmd:: set service ssh macs <mac> + + Specifies the available :abbr:`MAC (Message Authentication Code)` algorithms. + The MAC algorithm is used in protocol version 2 for data integrity protection. + Multiple algorithms can be provided. + + List of supported MACs: ``hmac-md5``, ``hmac-md5-96``, ``hmac-ripemd160``, + ``hmac-sha1``, ``hmac-sha1-96``, ``hmac-sha2-256``, ``hmac-sha2-512``, + ``umac-64@openssh.com``, ``umac-128@openssh.com``, + ``hmac-md5-etm@openssh.com``, ``hmac-md5-96-etm@openssh.com``, + ``hmac-ripemd160-etm@openssh.com``, ``hmac-sha1-etm@openssh.com``, + ``hmac-sha1-96-etm@openssh.com``, ``hmac-sha2-256-etm@openssh.com``, + ``hmac-sha2-512-etm@openssh.com``, ``umac-64-etm@openssh.com``, + ``umac-128-etm@openssh.com`` + +.. cfgcmd:: set service ssh access-control <allow | deny> <group | user> <name> + + Add access-control directive to allow or deny users and groups. Directives + are processed in the following order of precedence: ``deny-users``, + ``allow-users``, ``deny-groups`` and ``allow-groups``. + +.. cfgcmd:: set service ssh client-keepalive-interval <interval> + + Specify timeout interval for keepalive message in seconds. + +.. cfgcmd:: set service ssh key-exchange <kex> + + Specify allowed :abbr:`KEX (Key Exchange)` algorithms. + + List of supported algorithms: ``diffie-hellman-group1-sha1``, + ``diffie-hellman-group14-sha1``, ``diffie-hellman-group14-sha256``, + ``diffie-hellman-group16-sha512``, ``diffie-hellman-group18-sha512``, + ``diffie-hellman-group-exchange-sha1``, + ``diffie-hellman-group-exchange-sha256``, + ``ecdh-sha2-nistp256``, ``ecdh-sha2-nistp384``, ``ecdh-sha2-nistp521``, + ``curve25519-sha256`` and ``curve25519-sha256@libssh.org``. + +.. cfgcmd:: set service ssh loglevel <quiet | fatal | error | info | verbose> + + Set the ``sshd`` log level. The default is ``info``. + +.. cfgcmd:: set service ssh vrf <name> + + Specify name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance. + +Operation +========= + +.. opcmd:: restart ssh + + Restart the SSH daemon process, the current session is not affected, only the + background daemon is restarted. + +.. opcmd:: generate ssh server-key + + Re-generated the public/private keyportion which SSH uses to secure + connections. + + .. note:: Already learned known_hosts files of clients need an update as the + public key will change. + +.. opcmd:: generate ssh client-key /path/to/private_key + + Re-generated a known pub/private keyfile which can e.g. used to connect to + other services (RPKI cache). + + Example: + + .. code-block:: none + + vyos@vyos:~$ generate ssh client-key /config/auth/id_rsa_rpki + Generating public/private rsa key pair. + Your identification has been saved in /config/auth/id_rsa_rpki. + Your public key has been saved in /config/auth/id_rsa_rpki.pub. + The key fingerprint is: + SHA256:XGv2PpdOzVCzpmEzJZga8hTRq7B/ZYL3fXaioLFLS5Q cpo@LR1.wue3 + The key's randomart image is: + +---[RSA 2048]----+ + | oo | + | ..o | + | . o.o.. o.| + | o+ooo o.o| + | Eo* =.o | + | o = +.o*+ | + | = o *.o.o| + | o * +.o+.+| + | =.. o=.oo| + +----[SHA256]-----+ + + Two new files ``/config/auth/id_rsa_rpki`` and ``/config/auth/id_rsa_rpki.pub`` + will be created. diff --git a/docs/configuration/service/tftp-server.rst b/docs/configuration/service/tftp-server.rst new file mode 100644 index 00000000..276ce5fb --- /dev/null +++ b/docs/configuration/service/tftp-server.rst @@ -0,0 +1,54 @@ +.. _tftp-server: + +########### +TFTP Server +########### + +:abbr:`TFTP (Trivial File Transfer Protocol)` is a simple, lockstep file +transfer protocol which allows a client to get a file from or put a file onto +a remote host. One of its primary uses is in the early stages of nodes booting +from a local area network. TFTP has been used for this application because it +is very simple to implement. + +Configuration +============= + +.. cfgcmd:: set service tftp-server directory <directory> + +Enable TFTP service by specifying the `<directory>` which will be used to serve +files. + +.. hint:: Choose your ``directory`` location carefully or you will loose the + content on image upgrades. Any directory under ``/config`` is save at this + will be migrated. + +.. cfgcmd:: set service tftp-server listen-address <address> + +Configure the IPv4 or IPv6 listen address of the TFTP server. Multiple IPv4 and +IPv6 addresses can be given. There will be one TFTP server instances listening +on each IP address. + +.. note:: Configuring a listen-address is essential for the service to work. + +.. cfgcmd:: set service tftp-server allow-upload + +Optional, if you want to enable uploads, else TFTP server will act as read-only +server. + +Example +------- + +Provide TFTP server listening on both IPv4 and IPv6 addresses ``192.0.2.1`` and +``2001:db8::1`` serving the content from ``/config/tftpboot``. Uploading via +TFTP to this server is not allowed! + +The resulting configuration will look like: + +.. code-block:: none + + vyos@vyos# show service + tftp-server { + directory /config/tftpboot + listen-address 2001:db8::1 + listen-address 192.0.2.1 + } diff --git a/docs/configuration/service/webproxy.rst b/docs/configuration/service/webproxy.rst new file mode 100644 index 00000000..e8f6423e --- /dev/null +++ b/docs/configuration/service/webproxy.rst @@ -0,0 +1,434 @@ +.. _webproxy: + +######## +Webproxy +######## + +The proxy service in VyOS is based on Squid_ and some related modules. + +Squid_ is a caching and forwarding HTTP web proxy. It has a wide variety of +uses, including speeding up a web server by caching repeated requests, caching +web, DNS and other computer network lookups for a group of people sharing +network resources, and aiding security by filtering traffic. Although primarily +used for HTTP and FTP, Squid includes limited support for several other +protocols including Internet Gopher, SSL,[6] TLS and HTTPS. Squid does not +support the SOCKS protocol. + +URL Filtering is provided by SquidGuard_. + +************* +Configuration +************* + +.. cfgcmd:: set service webproxy append-domain <domain> + + Use this command to specify a domain name to be appended to domain-names + within URLs that do not include a dot ``.`` the domain is appended. + + Example: to be appended is set to ``vyos.net`` and the URL received is + ``www/foo.html``, the system will use the generated, final URL of + ``www.vyos.net/foo.html``. + + .. code-block:: none + + set service webproxy append-domain vyos.net + +.. cfgcmd:: set service webproxy cache-size <size> + + The size of the on-disk Proxy cache is user configurable. The Proxies default + cache-size is configured to 100 MB. + + Unit of this command is MB. + + .. code-block:: none + + set service webproxy cache-size 1024 + +.. cfgcmd:: set service webproxy default-port <port> + + Specify the port used on which the proxy service is listening for requests. + This port is the default port used for the specified listen-address. + + Default port is 3128. + + .. code-block:: none + + set service webproxy default-port 8080 + +.. cfgcmd:: set service webproxy domain-block <domain> + + Used to block specific domains by the Proxy. Specifying "vyos.net" will block + all access to vyos.net, and specifying ".xxx" will block all access to URLs + having an URL ending on .xxx. + + .. code-block:: none + + set service webproxy domain-block vyos.net + +.. cfgcmd:: set service webproxy domain-noncache <domain> + + Allow access to sites in a domain without retrieving them from the Proxy + cache. Specifying "vyos.net" will allow access to vyos.net but the pages + accessed will not be cached. It useful for working around problems with + "If-Modified-Since" checking at certain sites. + + .. code-block:: none + + set service webproxy domain-noncache vyos.net + +.. cfgcmd:: set service webproxy listen-address <address> + + Specifies proxy service listening address. The listen address is the IP + address on which the web proxy service listens for client requests. + + For security, the listen address should only be used on internal/trusted + networks! + + .. code-block:: none + + set service webproxy listen-address 192.0.2.1 + +.. cfgcmd:: set service webproxy listen-address <address> disable-transparent + + Disables web proxy transparent mode at a listening address. + + In transparent proxy mode, all traffic arriving on port 80 and destined for + the Internet is automatically forwarded through the proxy. This allows + immediate proxy forwarding without configuring client browsers. + + Non-transparent proxying requires that the client browsers be configured with + the proxy settings before requests are redirected. The advantage of this is + that the client web browser can detect that a proxy is in use and can behave + accordingly. In addition, web-transmitted malware can sometimes be blocked by + a non-transparent web proxy, since they are not aware of the proxy settings. + + .. code-block:: none + + set service webproxy listen-address 192.0.2.1 disable-transparent + +.. cfgcmd:: set service webproxy listen-address <address> port <port> + + Sets the listening port for a listening address. This overrides the default + port of 3128 on the specific listen address. + + .. code-block:: none + + set service webproxy listen-address 192.0.2.1 port 8080 + + +.. cfgcmd:: set service webproxy reply-block-mime <mime> + + Used to block a specific mime-type. + + .. code-block:: none + + # block all PDFs + set service webproxy reply-block-mime application/pdf + + +.. cfgcmd:: set service webproxy reply-body-max-size <size> + + Specifies the maximum size of a reply body in KB, used to limit the reply + size. + + All reply sizes are accepted by default. + + .. code-block:: none + + set service webproxy reply-body-max-size 2048 + +Authentication +============== + +The embedded Squid proxy can use LDAP to authenticate users against a company +wide directory. The following configuration is an example of how to use Active +Directory as authentication backend. Queries are done via LDAP. + +.. cfgcmd:: set service webproxy authentication children <number> + + Maximum number of authenticator processes to spawn. If you start too few + Squid will have to wait for them to process a backlog of credential + verifications, slowing it down. When password verifications are done via a + (slow) network you are likely to need lots of authenticator processes. + + This defaults to 5. + + .. code-block:: none + + set service webproxy authentication children 10 + +.. cfgcmd:: set service webproxy authentication credentials-ttl <time> + + Specifies how long squid assumes an externally validated username:password + pair is valid for - in other words how often the helper program is called for + that user. Set this low to force revalidation with short lived passwords. + + Time is in minutes and defaults to 60. + + .. code-block:: none + + set service webproxy authentication credentials-ttl 120 + + +.. cfgcmd:: set service webproxy authentication method <ldap> + + Proxy authentication method, currently only LDAP is supported. + + .. code-block:: none + + set service webproxy authentication method ldap + +.. cfgcmd:: set service webproxy authentication realm + + Specifies the protection scope (aka realm name) which is to be reported to + the client for the authentication scheme. It is commonly part of the text + the user will see when prompted for their username and password. + + .. code-block:: none + + set service webproxy authentication realm "VyOS proxy auth" + +LDAP +---- + +.. cfgcmd:: set service webproxy authentication ldap base-dn <base-dn> + + Specifies the base DN under which the users are located. + + .. code-block:: none + + set service webproxy authentication ldap base-dn DC=vyos,DC=net + + +.. cfgcmd:: set service webproxy authentication ldap bind-dn <bind-dn> + + The DN and password to bind as while performing searches. + + .. code-block:: none + + set service webproxy authentication ldap bind-dn CN=proxyuser,CN=Users,DC=vyos,DC=net + +.. cfgcmd:: set service webproxy authentication ldap filter-expression <expr> + + LDAP search filter to locate the user DN. Required if the users are in a + hierarchy below the base DN, or if the login name is not what builds the user + specific part of the users DN. + + The search filter can contain up to 15 occurrences of %s which will be + replaced by the username, as in "uid=%s" for :rfc:`2037` directories. For a + detailed description of LDAP search filter syntax see :rfc:`2254`. + + .. code-block:: none + + set service webproxy authentication ldap filter-expression (cn=%s) + +.. cfgcmd:: set service webproxy authentication ldap password <password> + + The DN and password to bind as while performing searches. As the password + needs to be printed in plain text in your Squid configuration it is strongly + recommended to use a account with minimal associated privileges. This to limit + the damage in case someone could get hold of a copy of your Squid + configuration file. + + .. code-block:: none + + set service webproxy authentication ldap password vyos + +.. cfgcmd:: set service webproxy authentication ldap persistent-connection + + Use a persistent LDAP connection. Normally the LDAP connection is only open + while validating a username to preserve resources at the LDAP server. This + option causes the LDAP connection to be kept open, allowing it to be reused + for further user validations. + + Recommended for larger installations. + + .. code-block:: none + + set service webproxy authentication ldap persistent-connection + +.. cfgcmd:: set service webproxy authentication ldap port <port> + + Specify an alternate TCP port where the ldap server is listening if other than + the default LDAP port 389. + + .. code-block:: none + + set service webproxy authentication ldap port 389 + +.. cfgcmd:: set service webproxy authentication ldap server <server> + + Specify the LDAP server to connect to. + + .. code-block:: none + + set service webproxy authentication ldap server ldap.vyos.net + + +.. cfgcmd:: set service webproxy authentication ldap use-ssl + + Use TLS encryption. + + .. code-block:: none + + set service webproxy authentication ldap use-ssl + + +.. cfgcmd:: set service webproxy authentication ldap username-attribute <attr> + + Specifies the name of the DN attribute that contains the username/login. + Combined with the base DN to construct the users DN when no search filter is + specified (`filter-expression`). + + Defaults to 'uid' + + .. note:: This can only be done if all your users are located directly under + the same position in the LDAP tree and the login name is used for naming + each user object. If your LDAP tree does not match these criterias or if you + want to filter who are valid users then you need to use a search filter to + search for your users DN (`filter-expression`). + + .. code-block:: none + + set service webproxy authentication ldap username-attribute uid + +.. cfgcmd:: set service webproxy authentication ldap version <2 | 3> + + LDAP protocol version. Defaults to 3 if not specified. + + .. code-block:: none + + set service webproxy authentication ldap version 2 + +URL filtering +============= + +.. include:: /_include/need_improvement.txt + + +.. cfgcmd:: set service webproxy url-filtering disable + + Disables web filtering without discarding configuration. + + .. code-block:: none + + set service webproxy url-filtering disable + +********* +Operation +********* + +.. include:: /_include/need_improvement.txt + +Filtering +========= + +Update +------ + +If you want to use existing blacklists you have to create/download a database +first. Otherwise you will not be able to commit the config changes. + + +.. opcmd:: update webproxy blacklists + + Download/Update complete blacklist + + .. code-block:: none + + vyos@vyos:~$ update webproxy blacklists + Warning: No url-filtering blacklist installed + Would you like to download a default blacklist? [confirm][y] + Connecting to ftp.univ-tlse1.fr (193.49.48.249:21) + blacklists.gz 100% |*************************************************************************************************************| 17.0M 0:00:00 ETA + Uncompressing blacklist... + Checking permissions... + Skip link for [ads] -> [publicite] + Building DB for [adult/domains] - 2467177 entries + Building DB for [adult/urls] - 67798 entries + Skip link for [aggressive] -> [agressif] + Building DB for [agressif/domains] - 348 entries + Building DB for [agressif/urls] - 36 entries + Building DB for [arjel/domains] - 69 entries + ... + + Building DB for [webmail/domains] - 374 entries + Building DB for [webmail/urls] - 9 entries + + The webproxy daemon must be restarted + Would you like to restart it now? [confirm][y] + + [ ok ] Restarting squid (via systemctl): squid.service. + vyos@vyos:~$ + +.. opcmd:: update webproxy blacklists category <category> + + Download/Update partial blacklist. + + Use tab completion to get a list of categories. + +* To auto update the blacklist files + + :code:`set service webproxy url-filtering squidguard auto-update + update-hour 23` + +* To configure blocking add the following to the configuration + + :code:`set service webproxy url-filtering squidguard block-category ads` + + :code:`set service webproxy url-filtering squidguard block-category malware` + +Bypassing the webproxy +---------------------- + +.. include:: /_include/need_improvement.txt + +Some services don't work correctly when being handled via a web proxy. +So sometimes it is useful to bypass a transparent proxy: + +* To bypass the proxy for every request that is directed to a specific + destination: + + :code:`set service webproxy whitelist destination-address 198.51.100.33` + + :code:`set service webproxy whitelist destination-address 192.0.2.0/24` + + +* To bypass the proxy for every request that is coming from a specific source: + + :code:`set service webproxy whitelist source-address 192.168.1.2` + + :code:`set service webproxy whitelist source-address 192.168.2.0/24` + + (This can be useful when a called service has many and/or often changing + destination addresses - e.g. Netflix.) + +******** +Examples +******** + +.. code-block:: none + + vyos@vyos# show service webproxy + authentication { + children 5 + credentials-ttl 60 + ldap { + base-dn DC=example,DC=local + bind-dn CN=proxyuser,CN=Users,DC=example,DC=local + filter-expression (cn=%s) + password Qwert1234 + server ldap.example.local + username-attribute cn + } + method ldap + realm "VyOS Webproxy" + } + cache-size 100 + default-port 3128 + listen-address 192.168.188.103 { + disable-transparent + } + +.. _Squid: http://www.squid-cache.org/ +.. _SquidGuard: http://www.squidguard.org/ diff --git a/docs/configuration/system/acceleration.disable b/docs/configuration/system/acceleration.disable new file mode 100644 index 00000000..b09da38b --- /dev/null +++ b/docs/configuration/system/acceleration.disable @@ -0,0 +1,7 @@ +.. _acceleration: + +############ +Acceleration +############ + + diff --git a/docs/configuration/system/config-management.disable b/docs/configuration/system/config-management.disable new file mode 100644 index 00000000..40973713 --- /dev/null +++ b/docs/configuration/system/config-management.disable @@ -0,0 +1,2 @@ +config-management +#################
\ No newline at end of file diff --git a/docs/configuration/system/conntrack.disable b/docs/configuration/system/conntrack.disable new file mode 100644 index 00000000..7d5d4308 --- /dev/null +++ b/docs/configuration/system/conntrack.disable @@ -0,0 +1,2 @@ +conntrack +#########
\ No newline at end of file diff --git a/docs/configuration/system/console.rst b/docs/configuration/system/console.rst new file mode 100644 index 00000000..4890da92 --- /dev/null +++ b/docs/configuration/system/console.rst @@ -0,0 +1,46 @@ +.. _serial-console: + +############## +Serial Console +############## + +For the average user a serial console has no advantage over a console offered +by a directly attached keyboard and screen. Serial consoles are much slower, +taking up to a second to fill a 80 column by 24 line screen. Serial consoles +generally only support non-proportional ASCII text, with limited support for +languages other than English. + +There are some scenarios where serial consoles are useful. System administration +of remote computers is usually done using :ref:`ssh`, but there are times when +access to the console is the only way to diagnose and correct software failures. +Major upgrades to the installed distribution may also require console access. + + +.. cfgcmd:: set system console device <device> + + Defines the specified device as a system console. Available console devices + can be (see completion helper): + + * ``ttySN`` - Serial device name + * ``ttyUSBX`` - USB Serial device name + * ``hvc0`` - Xen console + +.. cfgcmd:: set system console device <device> speed <speed> + + The speed (baudrate) of the console device. Supported values are: + + * ``1200`` - 1200 bps + * ``2400`` - 2400 bps + * ``4800`` - 4800 bps + * ``9600`` - 9600 bps + * ``19200`` - 19,200 bps + * ``38400`` - 38,400 bps (default for Xen console) + * ``57600`` - 57,600 bps + * ``115200`` - 115,200 bps (default for serial console) + + .. note:: If you use USB to serial converters for connecting to your VyOS + appliance please note that most of them use software emulation without flow + control. This means you should start with a common baud rate (most likely + 9600 baud) as otherwise you probably can not connect to the device using + high speed baud rates as your serial converter simply can not process this + datarate. diff --git a/docs/configuration/system/default-route.rst b/docs/configuration/system/default-route.rst new file mode 100644 index 00000000..27c74188 --- /dev/null +++ b/docs/configuration/system/default-route.rst @@ -0,0 +1,40 @@ +.. _default_gateway: + +##################### +Default Gateway/Route +##################### + +In the past (VyOS 1.1) used a gateway-address configured under the system tree +(:cfgcmd:`set system gateway-address <address>`), this is no longer supported +and existing configurations are migrated to the new CLI command. + +Configuration +============= + +.. cfgcmd:: set protocols static route 0.0.0.0/0 next-hop <address> + + Specify static route into the routing table sending all non local traffic + to the nexthop address `<address>`. + + +.. cfgcmd:: delete protocols static route 0.0.0.0/0 + + Delete default route from the system. + +Operation +========= + +.. opcmd:: show ip route 0.0.0.0 + + Show routing table entry for the default route. + + .. code-block:: none + + vyos@vyos:~$ show ip route 0.0.0.0 + Routing entry for 0.0.0.0/0 + Known via "static", distance 10, metric 0, best + Last update 09:46:30 ago + * 172.18.201.254, via eth0.201 + +.. seealso:: Configuration of :ref:`static-routing` + diff --git a/docs/configuration/system/domain-name.disable b/docs/configuration/system/domain-name.disable new file mode 100644 index 00000000..9028b65b --- /dev/null +++ b/docs/configuration/system/domain-name.disable @@ -0,0 +1,2 @@ +domain-name +###########
\ No newline at end of file diff --git a/docs/configuration/system/domain-search.disable b/docs/configuration/system/domain-search.disable new file mode 100644 index 00000000..f4aef62e --- /dev/null +++ b/docs/configuration/system/domain-search.disable @@ -0,0 +1,2 @@ +domain-search +#############
\ No newline at end of file diff --git a/docs/configuration/system/eventhandler.rst b/docs/configuration/system/eventhandler.rst new file mode 100644 index 00000000..3eab4e2c --- /dev/null +++ b/docs/configuration/system/eventhandler.rst @@ -0,0 +1,51 @@ +.. _event-handler: + +Event Handler +------------- + +Event handler allows you to execute scripts when a string that matches a regex +appears in a text stream (e.g. log file). + +It uses "feeds" (output of commands, or a named pipes) and "policies" that +define what to execute if a regex is matched. + +.. code-block:: none + + system + event-handler + feed <name> + description <feed description> + policy <policy name> + source + preset + syslog # Use the syslog logs for feed + custom + command <command to execute> # E.g. "tail -f /var/log/somelogfile" + named-pipe <path to a names pipe> + policy <policy name> + description <policy description> + event <event name> + description <event description> + pattern <regex> + run <command to run> + +In this small example a script runs every time a login failed and an interface +goes down + +.. code-block:: none + + vyos@vyos# show system event-handler + feed Syslog { + policy MyPolicy + source { + preset syslog + } + } + policy MyPolicy { + description "Test policy" + event BadThingsHappened { + pattern "authentication failure" + pattern "interface \.* index \d+ .* DOWN.*" + run /config/scripts/email-to-admin + } + }
\ No newline at end of file diff --git a/docs/configuration/system/flow-accounting.rst b/docs/configuration/system/flow-accounting.rst new file mode 100644 index 00000000..8d46b178 --- /dev/null +++ b/docs/configuration/system/flow-accounting.rst @@ -0,0 +1,209 @@ +.. _flow-accounting: + +############### +Flow Accounting +############### + +VyOS supports flow-accounting for both IPv4 and IPv6 traffic. The system acts +as a flow exporter, and you are free to use it with any compatible collector. + +Flows can be exported via two different protocols: NetFlow (versions 5, 9 and +10/IPFIX) and sFlow. Additionally, you may save flows to an in-memory table +internally in a router. + +.. warning:: You need to disable the in-memory table in production environments! + Using :abbr:`IMT (In-Memory Table)` may lead to heavy CPU overloading and + unstable flow-accounting behavior. + + +NetFlow / IPFIX +=============== +NetFlow is a feature that was introduced on Cisco routers around 1996 that +provides the ability to collect IP network traffic as it enters or exits an +interface. By analyzing the data provided by NetFlow, a network administrator +can determine things such as the source and destination of traffic, class of +service, and the causes of congestion. A typical flow monitoring setup (using +NetFlow) consists of three main components: + +* **exporter**: aggregates packets into flows and exports flow records towards + one or more flow collectors +* **collector**: responsible for reception, storage and pre-processing of flow + data received from a flow exporter +* **application**: analyzes received flow data in the context of intrusion + detection or traffic profiling, for example + +For connectionless protocols as like ICMP and UDP, a flow is considered +complete once no more packets for this flow appear after configurable timeout. + +NetFlow is usually enabled on a per-interface basis to limit load on the router +components involved in NetFlow, or to limit the amount of NetFlow records +exported. + +Configuration +============= + +In order for flow accounting information to be collected and displayed for an +interface, the interface must be configured for flow accounting. + +.. cfgcmd:: set system flow-accounting interface <interface> + + Configure and enable collection of flow information for the interface + identified by `<interface>`. + + You can configure multiple interfaces which whould participate in flow + accounting. + +.. note:: Will be recorded only packets/flows on **incoming** direction in + configured interfaces by default. + + +By default, recorded flows will be saved internally and can be listed with the +CLI command. You may disable using the local in-memory table with the command: + +.. cfgcmd:: set system flow-accounting disable-imt + + If you need to sample also egress traffic, you may want to + configure egress flow-accounting: + +.. cfgcmd:: set system flow-accounting enable-egress + + Internally, in flow-accounting processes exist a buffer for data exchanging + between core process and plugins (each export target is a separated plugin). + If you have high traffic levels or noted some problems with missed records + or stopping exporting, you may try to increase a default buffer size (10 + MiB) with the next command: + +.. cfgcmd:: set system flow-accounting buffer-size <buffer size> + + In case, if you need to catch some logs from flow-accounting daemon, you may + configure logging facility: + +.. cfgcmd:: set system flow-accounting syslog-facility <facility> + + TBD + +Flow Export +----------- + +In addition to displaying flow accounting information locally, one can also +exported them to a collection server. + +NetFlow +^^^^^^^ + +.. cfgcmd:: set system flow-accounting netflow version <version> + + There are multiple versions available for the NetFlow data. The `<version>` + used in the exported flow data can be configured here. The following + versions are supported: + + * **5** - Most common version, but restricted to IPv4 flows only + * **9** - NetFlow version 9 (default) + * **10** - :abbr:`IPFIX (IP Flow Information Export)` as per :rfc:`3917` + +.. cfgcmd:: set system flow-accounting netflow server <address> + + Configure address of NetFlow collector. NetFlow server at `<address>` can + be both listening on an IPv4 or IPv6 address. + +.. cfgcmd:: set system flow-accounting netflow source-ip <address> + + IPv4 or IPv6 source address of NetFlow packets + +.. cfgcmd:: set system flow-accounting netflow engine-id <id> + + NetFlow engine-id which will appear in NetFlow data. The range is 0 to 255. + +.. cfgcmd:: set system flow-accounting netflow sampling-rate <rate> + + Use this command to configure the sampling rate for flow accounting. The + system samples one in every `<rate>` packets, where `<rate>` is the value + configured for the sampling-rate option. The advantage of sampling every n + packets, where n > 1, allows you to decrease the amount of processing + resources required for flow accounting. The disadvantage of not sampling + every packet is that the statistics produced are estimates of actual data + flows. + + Per default every packet is sampled (that is, the sampling rate is 1). + +.. cfgcmd:: set system flow-accounting netflow timeout expiry-interval + <interval> + + Specifies the interval at which Netflow data will be sent to a collector. As + per default, Netflow data will be sent every 60 seconds. + + You may also additionally configure timeouts for different types of + connections. + +.. cfgcmd:: set system flow-accounting netflow max-flows <n> + + If you want to change the maximum number of flows, which are tracking + simultaneously, you may do this with this command (default 8192). + +sFlow +^^^^^ + +.. cfgcmd:: set system flow-accounting sflow server <address> + + Configure address of sFlow collector. sFlow server at `<address>` can + be an IPv4 or IPv6 address. But you cannot export to both IPv4 and + IPv6 collectors at the same time! + +.. cfgcmd:: set system flow-accounting sflow sampling-rate <rate> + + Enable sampling of packets, which will be transmitted to sFlow collectors. + +.. cfgcmd:: set system flow-accounting sflow agent-address <address> + + Configure a sFlow agent address. It can be IPv4 or IPv6 address, but you + must set the same protocol, which is used for sFlow collector addresses. By + default, using router-id from BGP or OSPF protocol, or the primary IP + address from the first interface. + +Example: +-------- + +NetFlow v5 example: + +.. code-block:: none + + set system flow-accounting netflow engine-id 100 + set system flow-accounting netflow version 5 + set system flow-accounting netflow server 192.168.2.10 port 2055 + +Operation +========= + +Once flow accounting is configured on an interfaces it provides the ability to +display captured network traffic information for all configured interfaces. + +.. opcmd:: show flow-accounting interface <interface> + + Show flow accounting information for given `<interface>`. + + .. code-block:: none + + vyos@vyos:~$ show flow-accounting interface eth0 + IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES + ---------- ----------------- ----------------- ------------------------ --------------- ---------- ---------- ---------- ----- --------- ------- ------- + eth0 00:53:01:a8:28:ac ff:ff:ff:ff:ff:ff 192.0.2.2 255.255.255.255 5678 5678 udp 0 1 1 178 + eth0 00:53:01:b2:2f:34 33:33:ff:00:00:00 fe80::253:01ff:feb2:2f34 ff02::1:ff00:0 0 0 ipv6-icmp 0 2 1 144 + eth0 00:53:01:1a:b4:53 33:33:ff:00:00:00 fe80::253:01ff:fe1a:b453 ff02::1:ff00:0 0 0 ipv6-icmp 0 1 1 72 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 39 1 2064 + eth0 00:53:01:c8:33:af ff:ff:ff:ff:ff:ff 192.0.2.3 255.255.255.255 5678 5678 udp 0 1 1 154 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 146 1 9444 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 27 1 4455 + +.. opcmd:: show flow-accounting interface <interface> host <address> + + Show flow accounting information for given `<interface>` for a specific host + only. + + .. code-block:: none + + vyos@vyos:~$ show flow-accounting interface eth0 host 192.0.2.14 + IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES + ---------- ----------------- ----------------- ----------- ---------- ---------- ---------- ---------- ----- --------- ------- ------- + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 197 2 12940 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 94 1 4924 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 36 1 5877 diff --git a/docs/configuration/system/host-name.rst b/docs/configuration/system/host-name.rst new file mode 100644 index 00000000..30efe01e --- /dev/null +++ b/docs/configuration/system/host-name.rst @@ -0,0 +1,63 @@ +.. _host-information: + +################ +Host Information +################ + +This section describes the system's host information and how to configure them, +it covers the following topics: + +* Host name +* Domain +* IP address +* Aliases + +Hostname +======== + +A hostname is the label (name) assigned to a network device (a host) on a +network and is used to distinguish one device from another on specific networks +or over the internet. On the other hand this will be the name which appears on +the command line prompt. + +.. cfgcmd:: set system host-name <hostname> + + Set system hostname. The hostname can be up to 63 characters. A hostname + must start and end with a letter or digit, and have as interior characters + only letters, digits, or a hyphen. + + The default hostname used is `vyos`. + +Domain Name +=========== + +A domain name is the label (name) assigned to a computer network and is thus +unique. VyOS appends the domain name as a suffix to any unqualified name. For +example, if you set the domain name `example.com`, and you would ping the +unqualified name of `crux`, then VyOS qualifies the name to `crux.example.com`. + +.. cfgcmd:: set system domain-name <domain> + + Configure system domain name. A domain name must start and end with a letter + or digit, and have as interior characters only letters, digits, or a hyphen. + +Static Hostname Mapping +======================= + +How an IP address is assigned to an interface in :ref:`ethernet-interface`. +This section shows how to statically map an IP address to a hostname for local +(meaning on this VyOS instance) name resolution. + +.. cfgcmd:: set system static-host-mapping host-name <hostname> inet <address> + + Create a static hostname mapping which will always resolve the name + `<hostname>` to IP address `<address>`. + + +.. cfgcmd:: set system static-host-mapping host-name <hostname> alias <alias> + + Create named `<alias>` for the configured static mapping for `<hostname>`. + Thus the address configured as :cfgcmd:`set system static-host-mapping + host-name <hostname> inet <address>` can be reached via multiple names. + + Multiple aliases can pe specified per host-name. diff --git a/docs/configuration/system/index.rst b/docs/configuration/system/index.rst new file mode 100644 index 00000000..2e428333 --- /dev/null +++ b/docs/configuration/system/index.rst @@ -0,0 +1,31 @@ +###### +System +###### + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + console + flow-accounting + host-name + ip + ipv6 + lcd + login + name-server + ntp + option + proxy + syslog + task-scheduler + time-zone + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + default-route + eventhandler diff --git a/docs/configuration/system/ip.rst b/docs/configuration/system/ip.rst new file mode 100644 index 00000000..78aeef4e --- /dev/null +++ b/docs/configuration/system/ip.rst @@ -0,0 +1,70 @@ +## +IP +## + +System configuration commands +----------------------------- + +.. cfgcmd:: set system ip disable-forwarding + + Use this command to disable IPv4 forwarding on all interfaces. + +.. cfgcmd:: set system ip arp table-size <number> + + Use this command to define the maximum number of entries to keep in + the ARP cache (1024, 2048, 4096, 8192, 16384, 32768). + +.. cfgcmd:: set system ip multipath layer4-hashing + + Use this command to use Layer 4 information for IPv4 ECMP hashing. + + +Operational commands +-------------------- + +show commands +^^^^^^^^^^^^^ + +See below the different parameters available for the IPv4 **show** command: + +.. code-block:: none + + vyos@vyos:~$ show ip + Possible completions: + access-list Show all IP access-lists + as-path-access-list + Show all as-path-access-lists + bgp Show Border Gateway Protocol (BGP) information + community-list + Show IP community-lists + extcommunity-list + Show extended IP community-lists + forwarding Show IP forwarding status + groups Show IP multicast group membership + igmp Show IGMP (Internet Group Management Protocol) information + large-community-list + Show IP large-community-lists + multicast Show IP multicast + ospf Show IPv4 Open Shortest Path First (OSPF) routing information + pim Show PIM (Protocol Independent Multicast) information + ports Show IP ports in use by various system services + prefix-list Show all IP prefix-lists + protocol Show IP route-maps per protocol + rip Show Routing Information Protocol (RIP) information + route Show IP routes + + +reset commands +^^^^^^^^^^^^^^ + +And the different IPv4 **reset** commands available: + +.. code-block:: none + + vyos@vyos:~$ reset ip + Possible completions: + arp Reset Address Resolution Protocol (ARP) cache + bgp Clear Border Gateway Protocol (BGP) statistics or status + igmp IGMP clear commands + multicast IP multicast routing table + route Reset IP route
\ No newline at end of file diff --git a/docs/configuration/system/ipv6.rst b/docs/configuration/system/ipv6.rst new file mode 100644 index 00000000..cba5c0e0 --- /dev/null +++ b/docs/configuration/system/ipv6.rst @@ -0,0 +1,182 @@ +#### +IPv6 +#### + +System configuration commands +----------------------------- + +.. cfgcmd:: set system ipv6 disable + + Use this command to disable assignment of IPv6 addresses on all + interfaces. + +.. cfgcmd:: set system ipv6 disable-forwarding + + Use this command to disable IPv6 forwarding on all interfaces. + +.. cfgcmd:: set system ipv6 neighbor table-size <number> + + Use this command to define the maximum number of entries to keep in + the Neighbor cache (1024, 2048, 4096, 8192, 16384, 32768). + +.. cfgcmd:: set system ipv6 strict-dad + + Use this command to disable IPv6 operation on interface when + Duplicate Address Detection fails on Link-Local address. + +.. cfgcmd:: set system ipv6 multipath layer4-hashing + + Use this command to user Layer 4 information for ECMP hashing. + + +Operational commands +-------------------- + +Show commands +^^^^^^^^^^^^^ + +.. opcmd:: show ipv6 neighbors + + Use this command to show IPv6 Neighbor Discovery Protocol information. + +.. opcmd:: show ipv6 groups + + Use this command to show IPv6 multicast group membership. + +.. opcmd:: show ipv6 forwarding + + Use this command to show IPv6 forwarding status. + +.. opcmd:: show ipv6 route + + Use this command to show IPv6 routes. + + Check the many parameters available for the `show ipv6 route` command: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 route + Possible completions: + <Enter> Execute the current command + <X:X::X:X> Show IPv6 routes of given address or prefix + <X:X::X:X/M> + bgp Show IPv6 BGP routes + cache Show kernel IPv6 route cache + connected Show IPv6 connected routes + forward Show kernel IPv6 route table + isis Show IPv6 ISIS routes + kernel Show IPv6 kernel routes + ospfv3 Show IPv6 OSPF6 routes + ripng Show IPv6 RIPNG routes + static Show IPv6 static routes + summary Show IPv6 routes summary + table Show IP routes in policy table + vrf Show IPv6 routes in VRF + + +.. opcmd:: show ipv6 prefix-list + + Use this command to show all IPv6 prefix lists + + There are different parameters for getting prefix-list information: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 prefix-list + Possible completions: + <Enter> Execute the current command + <WORD> Show specified IPv6 prefix-list + detail Show detail of IPv6 prefix-lists + summary Show summary of IPv6 prefix-lists + +.. opcmd:: show ipv6 access-list + + Use this command to show all IPv6 access lists + + You can also specify which IPv6 access-list should be shown: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 access-list + Possible completions: + <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 + + Use this command to get information about OSPFv3. + + You can get more specific OSPFv3 information by using the parameters + shown below: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 ospfv3 + Possible completions: + <Enter> Execute the current command + area Show OSPFv3 spf-tree information + border-routers + Show OSPFv3 border-router (ABR and ASBR) information + database Show OSPFv3 Link state database information + interface Show OSPFv3 interface information + linkstate Show OSPFv3 linkstate routing information + neighbor Show OSPFv3 neighbor information + redistribute Show OSPFv3 redistribute External information + route Show OSPFv3 routing table information + +.. opcmd:: show ipv6 ripng + + Use this command to get information about the RIPNG protocol + +.. opcmd:: show ipv6 ripng status + + Use this command to show the status of the RIPNG protocol + + +Reset commands +^^^^^^^^^^^^^^ + +.. opcmd:: reset ipv6 bgp <address> + + Use this command to clear Border Gateway Protocol statistics or + status. + + +.. opcmd:: reset ipv6 neighbors <address | interface> + + Use this command to reset IPv6 Neighbor Discovery Protocol cache for + an address or interface. + +.. opcmd:: reset ipv6 route cache + + Use this command to flush the kernel IPv6 route cache. + An address can be added to flush it only for that route.
\ No newline at end of file diff --git a/docs/configuration/system/lcd.rst b/docs/configuration/system/lcd.rst new file mode 100644 index 00000000..808d45a2 --- /dev/null +++ b/docs/configuration/system/lcd.rst @@ -0,0 +1,45 @@ +.. _system-display: + +******************** +System Display (LCD) +******************** + +The system LCD :abbr:`LCD (Liquid-crystal display)` option is for users running +VyOS on hardware that features an LCD display. This is typically a small display +built in an 19 inch rack-mountable appliance. Those displays are used to show +runtime data. + +To configure your LCD display you must first identify the used hardware, and +connectivity of the display to your system. This can be any serial port +(`ttySxx`) or serial via USB or even old parallel port interfaces. + +Configuration +============= + +.. cfgcmd:: set system lcd device <device> + + This is the name of the physical interface used to connect to your LCD + display. Tab completion is supported and it will list you all available + serial interface. + + For serial via USB port information please refor to: :ref:`hardware_usb`. + +.. cfgcmd:: set system lcd model <model> + + This is the LCD model used in your system. + + At the time of this writing the following displays are supported: + + * Crystalfontz CFA-533 + + * Crystalfontz CFA-631 + + * Crystalfontz CFA-633 + + * Crystalfontz CFA-635 + + .. note:: We can't support all displays from the beginning. If your display + type is missing, please create a feature request via Phabricator_. + +.. include:: /_include/common-references.txt + diff --git a/docs/configuration/system/login.rst b/docs/configuration/system/login.rst new file mode 100644 index 00000000..0492f4d1 --- /dev/null +++ b/docs/configuration/system/login.rst @@ -0,0 +1,164 @@ +.. _user_management: + +############### +User Management +############### + +The default VyOS user account (`vyos`), as well as newly created user accounts, +have all capabilities to configure the system. All accounts have sudo +capabilities and therefore can operate as root on the system. + +Both local administered and remote administered :abbr:`RADIUS (Remote +Authentication Dial-In User Service)` accounts are supported. + +Local +===== + +.. cfgcmd:: set system login user <name> full-name "<string>" + + Create new system user with username `<name>` and real-name specified by + `<string>`. + +.. cfgcmd:: set system login user <name> authentication plaintext-password + <password> + + Specify the plaintext password user by user `<name>` on this system. The + plaintext password will be automatically transferred into a secure hashed + password and not saved anywhere in plaintext. + +.. cfgcmd:: set system login user <name> authentication encrypted-password + <password> + + Setup encrypted password for given username. This is useful for + transferring a hashed password from system to system. + +.. _ssh_key_based_authentication: + +Key Based Authentication +------------------------ + +It is highly recommended to use SSH key authentication. By default there is +only one user (``vyos``), and you can assign any number of keys to that user. +You can generate a ssh key with the ``ssh-keygen`` command on your local +machine, which will (by default) save it as ``~/.ssh/id_rsa.pub``. + +Every SSH key comes in three parts: + +``ssh-rsa AAAAB3NzaC1yc2EAAAABAA...VBD5lKwEWB username@host.example.com`` + +Only the type (``ssh-rsa``) and the key (``AAAB3N...``) are used. Note that the +key will usually be several hundred characters long, and you will need to copy +and paste it. Some terminal emulators may accidentally split this over several +lines. Be attentive when you paste it that it only pastes as a single line. +The third part is simply an identifier, and is for your own reference. + +.. cfgcmd:: set system login user <username> authentication public-keys + <identifier> key <key> + + Assign the SSH public key portion `<key>` identified by per-key + `<identifier>` to the local user `<username>`. + +.. cfgcmd:: set system login user <username> authentication public-keys + <identifier> type <type> + + Every SSH public key portion referenced by `<identifier>` requires the + configuration of the `<type>` of public-key used. This type can be any of: + + * ``ecdsa-sha2-nistp256`` + * ``ecdsa-sha2-nistp384`` + * ``ecdsa-sha2-nistp521`` + * ``ssh-dss`` + * ``ssh-ed25519`` + * ``ssh-rsa`` + + .. note:: You can assign multiple keys to the same user by using a unique + identifier per SSH key. + +.. cfgcmd:: loadkey <username> <location> + + SSH keys can not only be specified on the command-line but also loaded for + a given user with `<username>` from a file pointed to by `<location>.` Keys + can be either loaded from local filesystem or any given remote location + using one of the following :abbr:`URIs (Uniform Resource Identifier)`: + + * ``<file>`` - Load from file on local filesystem path + * ``scp://<user>@<host>:/<file>`` - Load via SCP from remote machine + * ``sftp://<user>@<host>/<file>`` - Load via SFTP from remote machine + * ``ftp://<user>@<host>/<file>`` - Load via FTP from remote machine + * ``http://<host>/<file>`` - Load via HTTP from remote machine + * ``tftp://<host>/<file>`` - Load via TFTP from remote machine + +Example +------- + +In the following example, both `User1` and `User2` will be able to SSH into +VyOS as user ``vyos`` using their very own keys. + +.. code-block:: none + + set system login user vyos authentication public-keys 'User1' key "AAAAB3Nz...KwEW" + set system login user vyos authentication public-keys 'User1' type ssh-rsa + set system login user vyos authentication public-keys 'User2' key "AAAAQ39x...fbV3" + set system login user vyos authentication public-keys 'User2' type ssh-rsa + + +RADIUS +====== + +In large deployments it is not reasonable to configure each user individually +on every system. VyOS supports using :abbr:`RADIUS (Remote Authentication +Dial-In User Service)` servers as backend for user authentication. + +Configuration +------------- + +.. cfgcmd:: set system login radius server <address> secret <secret> + + Specify the `<address>` of the RADIUS server user with the pre-shared-secret + given in `<secret>`. Multiple servers can be specified. + +.. cfgcmd:: set system login radius server <address> port <port> + + Configure the discrete port under which the RADIUS server can be reached. + This defaults to 1812. + +.. cfgcmd:: set system login radius server <address> timeout <timeout> + + Setup the `<timeout>` in seconds when querying the RADIUS server. + +.. cfgcmd:: set system login radius server <address> disable + + Temporary disable this RADIUS server. It won't be queried. + +.. cfgcmd:: set system login radius source-address <address> + + RADIUS servers could be hardened by only allowing certain IP addresses to + connect. As of this the source address of each RADIUS query can be + configured. If this is not set, incoming connections to the RADIUS server + will use the nearest interface address pointing towards the server - making + it error prone on e.g. OSPF networks when a link fails and a backup route is + taken. + +.. hint:: If you want to have admin users to authenticate via RADIUS it is + essential to sent the ``Cisco-AV-Pair shell:priv-lvl=15`` attribute. Without + the attribute you will only get regular, non privilegued, system users. + + + +Login Banner +============ + +You are able to set post-login or pre-login banner messages to display certain +information for this system. + +.. cfgcmd:: set system login banner pre-login <message> + + Configure `<message>` which is shown during SSH connect and before a user is + logged in. + +.. cfgcmd:: set system login banner post-login <message> + + Configure `<message>` which is shown after user has logged in to the system. + +.. note:: To create a new line in your login message you need to escape the new + line character by using ``\\n``. diff --git a/docs/configuration/system/name-server.rst b/docs/configuration/system/name-server.rst new file mode 100644 index 00000000..1896eeda --- /dev/null +++ b/docs/configuration/system/name-server.rst @@ -0,0 +1,71 @@ +.. _system-dns: + +########## +System DNS +########## + + +This section describes configuring DNS on the system, namely: + + * DNS name servers + * Domain search order + + +DNS name servers +================ + +.. cfgcmd:: set system name-server <address> + + Use this command to specify a DNS server for the system to be used + for DNS lookups. More than one DNS server can be added, configuring + one at a time. Both IPv4 and IPv6 addresses are supported. + + + +Example +------- + +In this example, some *OpenNIC* servers are used, two IPv4 addresses +and two IPv6 addresses: + +.. stop_vyoslinter + +.. code-block:: none + + set system name-server 176.9.37.132 + set system name-server 195.10.195.195 + set system name-server 2a01:4f8:161:3441::1 + set system name-server 2a00:f826:8:2::195 + +.. start_vyoslinter + +Domain search order +=================== + +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> + + Use this command to define domains, one at a time, so that the system + uses them to complete unqualified host names. Maximum: 6 entries. + + +.. note:: Domain names can include letters, numbers, hyphens and periods + with a maximum length of 253 characters. + + +Example +------- + +The system is configured to attempt domain completion in the following +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 + diff --git a/docs/configuration/system/name-servers-dhcp.disable b/docs/configuration/system/name-servers-dhcp.disable new file mode 100644 index 00000000..6719fef9 --- /dev/null +++ b/docs/configuration/system/name-servers-dhcp.disable @@ -0,0 +1,2 @@ +name-servers-dhcp +#################
\ No newline at end of file diff --git a/docs/configuration/system/ntp.rst b/docs/configuration/system/ntp.rst new file mode 100644 index 00000000..223447f5 --- /dev/null +++ b/docs/configuration/system/ntp.rst @@ -0,0 +1,77 @@ +.. _ntp: + +### +NTP +### + +:abbr:`NTP (Network Time Protocol`) is a networking protocol for clock +synchronization between computer systems over packet-switched, variable-latency +data networks. In operation since before 1985, NTP is one of the oldest Internet +protocols in current use. + +NTP is intended to synchronize all participating computers to within a few +milliseconds of :abbr:`UTC (Coordinated Universal Time)`. It uses the +intersection algorithm, a modified version of Marzullo's algorithm, to select +accurate time servers and is designed to mitigate the effects of variable +network latency. NTP can usually maintain time to within tens of milliseconds +over the public Internet, and can achieve better than one millisecond accuracy +in local area networks under ideal conditions. Asymmetric routes and network +congestion can cause errors of 100 ms or more. + +The protocol is usually described in terms of a client-server model, but can as +easily be used in peer-to-peer relationships where both peers consider the other +to be a potential time source. Implementations send and receive timestamps using +:abbr:`UDP (User Datagram Protocol)` on port number 123. + +NTP supplies a warning of any impending leap second adjustment, but no +information about local time zones or daylight saving time is transmitted. + +The current protocol is version 4 (NTPv4), which is a proposed standard as +documented in :rfc:`5905`. It is backward compatible with version 3, specified +in :rfc:`1305`. + +Configuration +============= + +.. cfgcmd:: set system ntp server <address> + + Configure one or more servers for synchronisation. Server name can be either + an IP address or :abbr:`FQDN (Fully Qualified Domain Name)`. + + There are 3 default NTP server set. You are able to change them. + + * ``0.pool.ntp.org`` + * ``1.pool.ntp.org`` + * ``2.pool.ntp.org`` + +.. cfgcmd:: set system ntp server <address> <noselect | pool | preempt | prefer> + + Configure one or more attributes to the given NTP server. + + * ``noselect`` marks the server as unused, except for display purposes. The + server is discarded by the selection algorithm. + + * ``pool`` mobilizes persistent client mode association with a number of + remote servers. + + * ``preempt`` a preemptable association is expendable. + + * ``prefer`` marks the server as preferred. All other things being equal, + this host will be chosen for synchronization among a set of correctly + operating hosts. + +.. cfgcmd:: set system ntp listen-address <address> + + NTP process will only listen on the specified IP address. You must specify + the `<address>` and optionally the permitted clients. Multiple listen + addresses can be configured. + +.. cfgcmd:: set system ntp allow-clients address <address> + + List of networks or client addresses permitted to contact this NTP server. + + Multiple networks can be configured. + +.. cfgcmd:: set system ntp vrf <name> + + Specify name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance. diff --git a/docs/configuration/system/option.rst b/docs/configuration/system/option.rst new file mode 100644 index 00000000..e029ec96 --- /dev/null +++ b/docs/configuration/system/option.rst @@ -0,0 +1,100 @@ +.. _system_option: + +###### +Option +###### + +This chapter describe the possibilities of advanced system behavior. + +******* +General +******* + +.. cfgcmd:: set system option ctrl-alt-delete <ignore | reboot | poweroff> + + Action which will be run once the ctrl-alt-del keystroke is received. + +.. cfgcmd:: set system option reboot-on-panic + + Automatically reboot system on kernel panic after 60 seconds. + +.. cfgcmd:: set system option startup-beep + + Play an audible beep to the system speaker when system is ready. + +*********** +HTTP client +*********** + +.. cfgcmd:: set system option http-client source-address <address> + + Several commands utilize curl to initiate transfers. Configure the local + source IPv4/IPv6 address used for all CURL operations. + +.. cfgcmd:: set system option http-client source-interface <interface> + + Several commands utilize curl to initiate transfers. Configure the local + source interface used for all CURL operations. + +.. note:: `source-address` and `source-interface` can not be used at the same + time. + +*************** +Keyboard Layout +*************** + +When starting a VyOS live system (the installation CD) the configured keyboard +layout defaults to US. As this might not suite everyones use case you can adjust +the used keyboard layout on the system console. + +.. cfgcmd:: set system option keyboard-layout <us | fr | de | fi | no | dk> + + Change system keyboard layout to given language. + + Defaults to ``us``. + + .. note:: Changing the keymap only has an effect on the system console, using + SSH oder Serial remote access to the device is not affected as the keyboard + layout here corresponds to your access system. + +.. _system_options_performance: + +*********** +Performance +*********** + +As more and more routers run on Hypervisors, expecially with a :abbr:`NOS +(Network Operating System)` as VyOS, it makes fewer and fewer sense to use +static resource bindings like ``smp-affinity`` as present in VyOS 1.2 and +earlier to pin certain interrupt handlers to specific CPUs. + +We now utilize `tuned` for dynamic resource balancing based on profiles. + +.. stop_vyoslinter + +.. seealso:: https://access.redhat.com/sites/default/files/attachments/201501-perf-brief-low-latency-tuning-rhel7-v2.1.pdf + +.. start_vyoslinter + +.. cfgcmd:: set system option performance < throughput | latency > + + Configure one of the predefined system performance profiles. + + * ``throughput``: A server profile focused on improving network throughput. + This profile favors performance over power savings by setting + ``intel_pstate`` and ``max_perf_pct=100`` and increasing kernel network + buffer sizes. + + It enables transparent huge pages, and uses cpupower to set the performance + cpufreq governor. It also sets ``kernel.sched_min_granularity_ns`` to 10 us, + ``kernel.sched_wakeup_granularity_ns`` to 15 uss, and ``vm.dirty_ratio`` to + 40%. + + * ``latency``: A server profile focused on lowering network latency. + This profile favors performance over power savings by setting + ``intel_pstate`` and ``min_perf_pct=100``. + + It disables transparent huge pages, and automatic NUMA balancing. It also + uses cpupower to set the performance cpufreq governor, and requests a + cpu_dma_latency value of 1. It also sets busy_read and busy_poll times to + 50 us, and tcp_fastopen to 3. diff --git a/docs/configuration/system/proxy.rst b/docs/configuration/system/proxy.rst new file mode 100644 index 00000000..8e0339a7 --- /dev/null +++ b/docs/configuration/system/proxy.rst @@ -0,0 +1,28 @@ +.. _system_proxy: + +############ +System Proxy +############ + +Some IT environments require the use of a proxy to connect to the Internet. +Without this configuration VyOS updates could not be installed directly by +using the :opcmd:`add system image` command (:ref:`update_vyos`). + +.. cfgcmd:: set system proxy url <url> + + Set proxy for all connections initiated by VyOS, including HTTP, HTTPS, and + FTP (anonymous ftp). + +.. cfgcmd:: set system proxy port <port> + + Configure proxy port if it does not listen to the default port 80. + +.. cfgcmd:: set system proxy username <username> + + Some proxys require/support the "basic" HTTP authentication scheme as per + :rfc:`7617`, thus a username can be configured. + +.. cfgcmd:: set system proxy password <password> + + Some proxys require/support the "basic" HTTP authentication scheme as per + :rfc:`7617`, thus a password can be configured. diff --git a/docs/configuration/system/static-host-mapping.disable b/docs/configuration/system/static-host-mapping.disable new file mode 100644 index 00000000..97d9a443 --- /dev/null +++ b/docs/configuration/system/static-host-mapping.disable @@ -0,0 +1,2 @@ +static-host-mapping +###################
\ No newline at end of file diff --git a/docs/configuration/system/sysctl.disable b/docs/configuration/system/sysctl.disable new file mode 100644 index 00000000..82ffd159 --- /dev/null +++ b/docs/configuration/system/sysctl.disable @@ -0,0 +1,2 @@ +sysctl +######
\ No newline at end of file diff --git a/docs/configuration/system/syslog.rst b/docs/configuration/system/syslog.rst new file mode 100644 index 00000000..a4d641b5 --- /dev/null +++ b/docs/configuration/system/syslog.rst @@ -0,0 +1,231 @@ +.. _syslog: + +###### +Syslog +###### + +Per default VyOSs has minimal syslog logging enabled which is stored and +rotated locally. Errors will be always logged to a local file, which includes +`local7` error messages, emergency messages will be sent to the console, too. + +To configure syslog, you need to switch into configuration mode. + +Logging +======= + +Syslog supports logging to multiple targets, those targets could be a plain +file on your VyOS installation itself, a serial console or a remote syslog +server which is reached via :abbr:`IP (Internet Protocol)` UDP/TCP. + +Console +------- + +.. cfgcmd:: set system syslog console facility <keyword> level <keyword> + + Log syslog messages to ``/dev/console``, for an explanation on + :ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords + see tables below. + + +Custom File +----------- + +.. cfgcmd:: set system syslog file <filename> facility <keyword> level <keyword> + + Log syslog messages to file specified via `<filename>`, for en explanation on + :ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords + see tables below. + +.. cfgcmd:: set system syslog file <filename> archive size <size> + + Syslog will write `<size>` kilobytes into the file specified by `<filename>`. + After this limit has been reached, the custom file is "rotated" by logrotate + and a new custom file is created. + +.. cfgcmd:: set system syslog file <filename> archive file <number> + + Syslog uses logrotate to rotate logiles after a number of gives bytes. + We keep as many as `<number>` rotated file before they are deleted on the + system. + + +Remote Host +----------- + +Logging to a remote host leaves the local logging configuration intact, it +can be configured in parallel to a custom file or console logging. You can log +to multiple hosts at the same time, using either TCP or UDP. The default is +sending the messages via port 514/UDP. + + +.. cfgcmd:: set system syslog host <address> facility <keyword> level <keyword> + + Log syslog messages to remote host specified by `<address>`. The address + can be specified by either FQDN or IP address. For en explanation on + :ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` + keywords see tables below. + + +.. cfgcmd:: set system syslog host <address> facility <keyword> protocol + <udp|tcp> + + Configure protocol used for communication to remote syslog host. This can be + either UDP or TCP. + + +Local User Account +------------------ + +.. cfgcmd:: set system syslog user <username> facility <keyword> level <keyword> + + If logging to a local user account is configured, all defined log messages + are display on the console if the local user is logged in, if the user is not + logged in, no messages are being displayed. For en explanation on + :ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords + see tables below. + +.. _syslog_facilities: + +Facilities +========== + +List of facilities used by syslog. Most facilities names are self explanatory. +Facilities local0 - local7 common usage is f.e. as network logs facilities for +nodes and network equipment. Generally it depends on the situation how to +classify logs and put them to facilities. See facilities more as a tool rather +than a directive to follow. + +Facilities can be adjusted to meet the needs of the user: + ++----------+----------+----------------------------------------------------+ +| Facility | Keyword | Description | +| Code | | | ++==========+==========+====================================================+ +| | all | All facilities | ++----------+----------+----------------------------------------------------+ +| 0 | kern | Kernel messages | ++----------+----------+----------------------------------------------------+ +| 1 | user | User-level messages | ++----------+----------+----------------------------------------------------+ +| 2 | mail | Mail system | ++----------+----------+----------------------------------------------------+ +| 3 | daemon | System daemons | ++----------+----------+----------------------------------------------------+ +| 4 | auth | Security/authentication messages | ++----------+----------+----------------------------------------------------+ +| 5 | syslog | Messages generated internally by syslogd | ++----------+----------+----------------------------------------------------+ +| 6 | lpr | Line printer subsystem | ++----------+----------+----------------------------------------------------+ +| 7 | news | Network news subsystem | ++----------+----------+----------------------------------------------------+ +| 8 | uucp | UUCP subsystem | ++----------+----------+----------------------------------------------------+ +| 9 | cron | Clock daemon | ++----------+----------+----------------------------------------------------+ +| 10 | security | Security/authentication messages | ++----------+----------+----------------------------------------------------+ +| 11 | ftp | FTP daemon | ++----------+----------+----------------------------------------------------+ +| 12 | ntp | NTP subsystem | ++----------+----------+----------------------------------------------------+ +| 13 | logaudit | Log audit | ++----------+----------+----------------------------------------------------+ +| 14 | logalert | Log alert | ++----------+----------+----------------------------------------------------+ +| 15 | clock | clock daemon (note 2) | ++----------+----------+----------------------------------------------------+ +| 16 | local0 | local use 0 (local0) | ++----------+----------+----------------------------------------------------+ +| 17 | local1 | local use 1 (local1) | ++----------+----------+----------------------------------------------------+ +| 18 | local2 | local use 2 (local2) | ++----------+----------+----------------------------------------------------+ +| 19 | local3 | local use 3 (local3) | ++----------+----------+----------------------------------------------------+ +| 20 | local4 | local use 4 (local4) | ++----------+----------+----------------------------------------------------+ +| 21 | local5 | local use 5 (local5) | ++----------+----------+----------------------------------------------------+ +| 22 | local6 | use 6 (local6) | ++----------+----------+----------------------------------------------------+ +| 23 | local7 | local use 7 (local7) | ++----------+----------+----------------------------------------------------+ + +.. _syslog_severity_level: + +Severity Level +============== + ++-------+---------------+---------+-------------------------------------------+ +| Value | Severity | Keyword | Description | ++=======+===============+=========+===========================================+ +| | | all | Log everything | ++-------+---------------+---------+-------------------------------------------+ +| 0 | Emergency | emerg | System is unusable - a panic condition | ++-------+---------------+---------+-------------------------------------------+ +| 1 | Alert | alert | Action must be taken immediately - A | +| | | | condition that should be corrected | +| | | | immediately, such as a corrupted system | +| | | | database. | ++-------+---------------+---------+-------------------------------------------+ +| 2 | Critical | crit | Critical conditions - e.g. hard drive | +| | | | errors. | ++-------+---------------+---------+-------------------------------------------+ +| 3 | Error | err | Error conditions | ++-------+---------------+---------+-------------------------------------------+ +| 4 | Warning | warning | Warning conditions | ++-------+---------------+---------+-------------------------------------------+ +| 5 | Notice | notice | Normal but significant conditions - | +| | | | conditions that are not error conditions, | +| | | | but that may require special handling. | ++-------+---------------+---------+-------------------------------------------+ +| 6 | Informational | info | Informational messages | ++-------+---------------+---------+-------------------------------------------+ +| 7 | Debug | debug | Debug-level messages - Messages that | +| | | | contain information normally of use only | +| | | | when debugging a program. | ++-------+---------------+---------+-------------------------------------------+ + + +Display Logs +============ + +.. opcmd:: show log [all | authorization | cluster | conntrack-sync | ...] + + Display log files of given category on the console. Use tab completion to get + a list of available categories. Thos categories could be: all, authorization, + cluster, conntrack-sync, dhcp, directory, dns, file, firewall, https, image + lldp, nat, openvpn, snmp, tail, vpn, vrrp + +If no option is specified, this defaults to `all`. + +.. opcmd:: show log image <name> + [all | authorization | directory | file <file name> | tail <lines>] + + Log messages from a specified image can be displayed on the console. Details + of allowed parameters: + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - all + - Display contents of all master log files of the specified image + * - authorization + - Display all authorization attempts of the specified image + * - directory + - Display list of all user-defined log files of the specified image + * - file <file name> + - Display contents of a specified user-defined log file of the specified + image + * - tail + - Display last lines of the system log of the specified image + * - <lines> + - Number of lines to be displayed, default 10 + +When no options/parameters are used, the contents of the main syslog file are +displayed. + +.. hint:: Use ``show log | strip-private`` if you want to hide private data + when sharing your logs. diff --git a/docs/configuration/system/task-scheduler.rst b/docs/configuration/system/task-scheduler.rst new file mode 100644 index 00000000..382da39f --- /dev/null +++ b/docs/configuration/system/task-scheduler.rst @@ -0,0 +1,40 @@ +.. _task-scheduler: + +############## +Task Scheduler +############## + +The task scheduler allows you to execute tasks on a given schedule. It makes +use of UNIX cron_. + +.. note:: All scripts excecuted this way are executed as root user - this may + be dangerous. Together with :ref:`command-scripting` this can be used for + automating (re-)configuration. + +.. cfgcmd:: set system task-scheduler task <task> interval <interval> + + Specify the time interval when `<task>` should be executed. The interval + is specified as number with one of the following suffixes: + + * ``none`` - Execution interval in minutes + * ``m`` - Execution interval in minutes + * ``h`` - Execution interval in hours + * ``d`` - Execution interval in days + + .. note:: If suffix is omitted, minutes are implied. + +.. cfgcmd:: set system task-scheduler task <task> crontab-spec <spec> + + Set execution time in common cron_ time format. A cron `<spec>` of + ``30 */6 * * *`` would execute the `<task>` at minute 30 past every 6th hour. + +.. cfgcmd:: set system task-scheduler task <task> executable path <path> + + Specify absolute `<path>` to script which will be run when `<task>` is + executed. + +.. cfgcmd:: set system task-scheduler task <task> executable arguments <args> + + Arguments which will be passed to the executable. + +.. _cron: https://en.wikipedia.org/wiki/Cron diff --git a/docs/configuration/system/time-zone.rst b/docs/configuration/system/time-zone.rst new file mode 100644 index 00000000..025c4376 --- /dev/null +++ b/docs/configuration/system/time-zone.rst @@ -0,0 +1,18 @@ +.. _timezone: + +######### +Time Zone +######### + +Time Zone setting is very important as e.g all your logfile entries will be +based on the configured zone. Without proper time zone configuration it will +be very difficult to compare logfiles from different systems. + +.. cfgcmd:: set system time-zone <timezone> + + Specify the systems `<timezone>` as the Region/Location that best defines + your location. For example, specifying US/Pacific sets the time zone to US + Pacific time. + + Command completion can be used to list available time zones. The adjustment + for daylight time will take place automatically based on the time of year.
\ No newline at end of file diff --git a/docs/configuration/system/wifi-requlatory-domain.disable b/docs/configuration/system/wifi-requlatory-domain.disable new file mode 100644 index 00000000..2b6ce7d4 --- /dev/null +++ b/docs/configuration/system/wifi-requlatory-domain.disable @@ -0,0 +1,2 @@ +wifi-requlatory-domain +######################
\ No newline at end of file diff --git a/docs/configuration/trafficpolicy/index.rst b/docs/configuration/trafficpolicy/index.rst new file mode 100644 index 00000000..f3e498d4 --- /dev/null +++ b/docs/configuration/trafficpolicy/index.rst @@ -0,0 +1,1228 @@ +.. _qos: + +############## +Traffic Policy +############## + + +*** +QoS +*** + +The generic name of Quality of Service or Traffic Control involves +things like shaping traffic, scheduling or dropping packets, which +are the kind of things you may want to play with when you have, for +instance, a bandwidth bottleneck in a link and you want to somehow +prioritize some type of traffic over another. + +tc_ is a powerful tool for Traffic Control found at the Linux kernel. +However, its configuration is often considered a cumbersome task. +Fortunately, VyOS eases the job through its CLI, while using ``tc`` as +backend. + + +How to make it work +=================== + +In order to have VyOS Traffic Control working you need to follow 2 +steps: + + 1. **Create a traffic policy**. + + 2. **Apply the traffic policy to an interface ingress or egress**. + + +But before learning to configure your policy, we will warn you +about the different units you can use and also show you what *classes* +are and how they work, as some policies may require you to configure +them. + + +Units +===== + +When configuring your traffic policy, you will have to set data rate +values, watch out the units you are managing, it is easy to get confused +with the different prefixes and suffixes you can use. VyOS will always +show you the different units you can use. + +Prefixes +-------- + +They can be **decimal** prefixes. + + .. code-block:: none + + kbit (10^3) kilobit per second + mbit (10^6) megabit per second + gbit (10^9) gigabit per second + tbit (10^12) terabit per second + + kbps (8*10^3) kilobyte per second + mbps (8*10^6) megabyte per second + gbps (8*10^9) gigabyte per second + tbps (8*10^12) terabyte per second + +Or **binary** prefixes. + + .. code-block:: none + + kibit (2^10 = 1024) kibibit per second + mibit (2^20 = 1024^2) mebibit per second + gibit (2^30 = 1024^3) gibibit per second + tbit (2^40 = 1024^4) tebibit per second + + kibps (1024*8) kibibyte (KiB) per second + mibps (1024^2*8) mebibyte (MiB) per second + gibps (1024^3*8) gibibyte (GiB) per second + tibps (1024^4*8) tebibyte (TiB) per second + + +Suffixes +-------- + +A *bit* is written as **bit**, + + .. code-block:: none + + kbit (kilobits per second) + mbit (megabits per second) + gbit (gigabits per second) + tbit (terabits per second) + +while a *byte* is written as a single **b**. + + .. code-block:: none + + kbps (kilobytes per second) + mbps (megabytes per second) + gbps (gigabytes per second) + + + + +.. _classes: + +Classes +======= + +In the :ref:`creating_a_traffic_policy` section you will see that +some of the policies use *classes*. Those policies let you distribute +traffic into different classes according to different parameters you can +choose. So, a class is just a specific type of traffic you select. + +The ultimate goal of classifying traffic is to give each class a +different treatment. + + +Matching traffic +---------------- + +In order to define which traffic goes into which class, you define +filters (that is, the matching criteria). Packets go through these matching +rules (as in the rules of a firewall) and, if a packet matches the filter, it +is assigned to that class. + +In VyOS, a class is identified by a number you can choose when +configuring it. + + +.. note:: The meaning of the Class ID is not the same for every type of + policy. Normally policies just need a meaningless number to identify + a class (Class ID), but that does not apply to every policy. + The the number of a class in a Priority Queue it does not only + identify it, it also defines its priority. + + +.. code-block:: none + + set traffic-policy <policy> <policy-name> class <class-ID> match <class-matching-rule-name> + + +In the command above, we set the type of policy we are going to +work with and the name we choose for it; a class (so that we can +differentiate some traffic) and an identifiable number for that class; +then we configure a matching rule (or filter) and a name for it. + +A class can have multiple match filters: + +.. code-block:: none + + set traffic-policy shaper MY-SHAPER class 30 match HTTP + set traffic-policy shaper MY-SHAPER class 30 match HTTPs + +A match filter can contain multiple criteria and will match traffic if +all those criteria are true. + +For example: + +.. code-block:: none + + set traffic-policy shaper MY-SHAPER class 30 match HTTP ip protocol tcp + set traffic-policy shaper MY-SHAPER class 30 match HTTP ip source port 80 + +This will match TCP traffic with source port 80. + +There are many parameters you will be able to use in order to match the +traffic you want for a class: + + - **Ethernet (protocol, destination address or source address)** + - **Interface name** + - **IPv4 (DSCP value, maximum packet length, protocol, source address,** + **destination address, source port, destination port or TCP flags)** + - **IPv6 (DSCP value, maximum payload length, protocol, source address,** + **destination address, source port, destination port or TCP flags)** + - **Firewall mark** + - **VLAN ID** + +When configuring your filter, you can use the ``Tab`` key to see the many +different parameters you can configure. + + +.. code-block:: none + + vyos@vyos# set traffic-policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER + Possible completions: + description Description for this match + > ether Ethernet header match + interface Interface name for this match + > ip Match IP protocol header + > ipv6 Match IPV6 header + mark Match on mark applied by firewall + vif Virtual Local Area Network (VLAN) ID for this match + + + +As shown in the example above, one of the possibilities to match packets +is based on marks done by the firewall, +`that can give you a great deal of flexibility`_. + +You can also write a description for a filter: + +.. code-block:: none + + set traffic-policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER description "My filter description" + + + +.. note:: An IPv4 TCP filter will only match packets with an IPv4 header + length of 20 bytes (which is the majority of IPv4 packets anyway). + + +.. note:: IPv6 TCP filters will only match IPv6 packets with no header + extension, see https://en.wikipedia.org/wiki/IPv6_packet#Extension_headers + + +Default +------- + +Often you will also have to configure your *default* traffic in the same +way you do with a class. *Default* can be considered a class as it +behaves like that. It contains any traffic that did not match any +of the defined classes, so it is like an open class, a class without +matching filters. + + +Class treatment +--------------- + +Once a class has a filter configured, you will also have to define what +you want to do with the traffic of that class, what specific +Traffic-Control treatment you want to give it. You will have different +possibilities depending on the Traffic Policy you are configuring. + +.. code-block:: none + + vyos@vyos# set traffic-policy shaper MY-SHAPER class 30 + Possible completions: + bandwidth Bandwidth used for this class + burst Burst size for this class (default: 15kb) + ceiling Bandwidth limit for this class + codel-quantum + fq-codel - Number of bytes used as 'deficit' (default 1514) + description Description for this traffic class + flows fq-codel - Number of flows (default 1024) + interval fq-codel - Interval (milliseconds) used to measure the delay (default 100) + +> match Class matching rule name + priority Priority for usage of excess bandwidth + queue-limit Maximum queue size (packets) + queue-type Queue type for this class + set-dscp Change the Differentiated Services (DiffServ) field in the IP header + target fq-codel - Acceptable minimum queue delay (milliseconds) + + +For instance, with :code:`set traffic-policy shaper MY-SHAPER +class 30 set-dscp EF` you would be modifying the DSCP field value of packets in +that class to Expedite Forwarding. + + + DSCP values as per :rfc:`2474` and :rfc:`4595`: + + +---------+------------+--------+------------------------------+ + | Binary | Configured | Drop | Description | + | value | value | rate | | + +=========+============+========+==============================+ + | 101110 | 46 | - | Expedited forwarding (EF) | + +---------+------------+--------+------------------------------+ + | 000000 | 0 | - | Best effort traffic, default | + +---------+------------+--------+------------------------------+ + | 001010 | 10 | Low | Assured Forwarding(AF) 11 | + +---------+------------+--------+------------------------------+ + | 001100 | 12 | Medium | Assured Forwarding(AF) 12 | + +---------+------------+--------+------------------------------+ + | 001110 | 14 | High | Assured Forwarding(AF) 13 | + +---------+------------+--------+------------------------------+ + | 010010 | 18 | Low | Assured Forwarding(AF) 21 | + +---------+------------+--------+------------------------------+ + | 010100 | 20 | Medium | Assured Forwarding(AF) 22 | + +---------+------------+--------+------------------------------+ + | 010110 | 22 | High | Assured Forwarding(AF) 23 | + +---------+------------+--------+------------------------------+ + | 011010 | 26 | Low | Assured Forwarding(AF) 31 | + +---------+------------+--------+------------------------------+ + | 011100 | 28 | Medium | Assured Forwarding(AF) 32 | + +---------+------------+--------+------------------------------+ + | 011110 | 30 | High | Assured Forwarding(AF) 33 | + +---------+------------+--------+------------------------------+ + | 100010 | 34 | Low | Assured Forwarding(AF) 41 | + +---------+------------+--------+------------------------------+ + | 100100 | 36 | Medium | Assured Forwarding(AF) 42 | + +---------+------------+--------+------------------------------+ + | 100110 | 38 | High | Assured Forwarding(AF) 43 | + +---------+------------+--------+------------------------------+ + + + + +.. _embed: + +Embedding one policy into another one +------------------------------------- + +Often we need to embed one policy into another one. It is possible to do +so on classful policies, by attaching a new policy into a class. For +instance, you might want to apply different policies to the different +classes of a Round-Robin policy you have configured. + +A common example is the case of some policies which, in order to be +effective, they need to be applied to an interface that is directly +connected where the bottleneck is. If your router is not +directly connected to the bottleneck, but some hop before it, you can +emulate the bottleneck by embedding your non-shaping policy into a +classful shaping one so that it takes effect. + +You can configure a policy into a class through the ``queue-type`` +setting. + +.. code-block:: none + + set traffic-policy shaper FQ-SHAPER bandwidth 4gbit + set traffic-policy shaper FQ-SHAPER default bandwidth 100% + set traffic-policy shaper FQ-SHAPER default queue-type fq-codel + +As shown in the last command of the example above, the `queue-type` +setting allows these combinations. You will be able to use it +in many policies. + +.. note:: Some policies already include other embedded policies inside. + That is the case of Shaper_: each of its classes use fair-queue + unless you change it. + +.. _creating_a_traffic_policy: + + +Creating a traffic policy +========================= + +VyOS lets you control traffic in many different ways, here we will cover +every possibility. You can configure as many policies as you want, but +you will only be able to apply one policy per interface and direction +(inbound or outbound). + +Some policies can be combined, you will be able to embed_ a different +policy that will be applied to a class of the main policy. + +.. hint:: **If you are looking for a policy for your outbound traffic** + but you don't know which one you need and you don't want to go + through every possible policy shown here, **our bet is that highly + likely you are looking for a** Shaper_ **policy and you want to** + :ref:`set its queues <embed>` **as FQ-CoDel**. + +Drop Tail +--------- + +| **Queueing discipline:** PFIFO (Packet First In First Out). +| **Applies to:** Outbound traffic. + +This the simplest queue possible you can apply to your traffic. Traffic +must go through a finite queue before it is actually sent. You must +define how many packets that queue can contain. + +When a packet is to be sent, it will have to go through that queue, so +the packet will be placed at the tail of it. When the packet completely +goes through it, it will be dequeued emptying its place in the queue and +being eventually handed to the NIC to be actually sent out. + +Despite the Drop-Tail policy does not slow down packets, if many packets +are to be sent, they could get dropped when trying to get enqueued at +the tail. This can happen if the queue has still not been able to +release enough packets from its head. + +This is the policy that requieres the lowest resources for the same +amount of traffic. But **very likely you do not need it as you cannot +get much from it. Sometimes it is used just to enable logging.** + +.. cfgcmd:: set traffic-policy drop-tail <policy-name> queue-limit + <number-of-packets> + + Use this command to configure a drop-tail policy (PFIFO). Choose a + unique name for this policy and the size of the queue by setting the + number of packets it can contain (maximum 4294967295). + + +Fair Queue +---------- + +| **Queueing discipline:** SFQ (Stochastic Fairness Queuing). +| **Applies to:** Outbound traffic. + +Fair Queue is a work-conserving scheduler which schedules the +transmission of packets based on flows, that is, it balances traffic +distributing it through different sub-queues in order to ensure +fairness so that each flow is able to send data in turn, preventing any +single one from drowning out the rest. + + +.. cfgcmd:: set traffic-policy fair-queue <policy-name> + + Use this command to create a Fair-Queue policy and give it a name. + It is based on the Stochastic Fairness Queueing and can be applied to + outbound traffic. + +In order to separate traffic, Fair Queue uses a classifier based on +source address, destination address and source port. The algorithm +enqueues packets to hash buckets based on those tree parameters. +Each of these buckets should represent a unique flow. Because multiple +flows may get hashed to the same bucket, the hashing algorithm is +perturbed at configurable intervals so that the unfairness lasts only +for a short while. Perturbation may however cause some inadvertent +packet reordering to occur. An advisable value could be 10 seconds. + +One of the uses of Fair Queue might be the mitigation of Denial of +Service attacks. + +.. cfgcmd:: set traffic-policy fair-queue <policy-name> hash-interval <seconds>` + + Use this command to define a Fair-Queue policy, based on the + Stochastic Fairness Queueing, and set the number of seconds at which + a new queue algorithm perturbation will occur (maximum 4294967295). + +When dequeuing, each hash-bucket with data is queried in a round robin +fashion. You can configure the length of the queue. + +.. cfgcmd:: set traffic-policy fair-queue <policy-name> queue-limit <limit> + + Use this command to define a Fair-Queue policy, based on the + Stochastic Fairness Queueing, and set the number of maximum packets + allowed to wait in the queue. Any other packet will be dropped. + +.. note:: Fair Queue is a non-shaping (work-conserving) policy, so it + will only be useful if your outgoing interface is really full. If it + is not, VyOS will not own the queue and Fair Queue will have no + effect. If there is bandwidth available on the physical link, you can + embed_ Fair-Queue into a classful shaping policy to make sure it owns + the queue. + + + +.. _FQ-CoDel: + +FQ-CoDel +-------- + +| **Queueing discipline** Fair/Flow Queue CoDel. +| **Applies to:** Outbound Traffic. + +The FQ-CoDel policy distributes the traffic into 1024 FIFO queues and +tries to provide good service between all of them. It also tries to keep +the length of all the queues short. + +FQ-CoDel fights bufferbloat and reduces latency without the need of +complex configurations. It has become the new default Queueing +Discipline for the interfaces of some GNU/Linux distributions. + +It uses a stochastic model to classify incoming packets into +different flows and is used to provide a fair share of the bandwidth to +all the flows using the queue. Each flow is managed by the CoDel +queuing discipline. Reordering within a flow is avoided since Codel +internally uses a FIFO queue. + +FQ-CoDel is based on a modified Deficit Round Robin (DRR_) queue +scheduler with the CoDel Active Queue Management (AQM) algorithm +operating on each queue. + + +.. note:: FQ-Codel is a non-shaping (work-conserving) policy, so it + will only be useful if your outgoing interface is really full. If it + is not, VyOS will not own the queue and FQ-Codel will have no + effect. If there is bandwidth available on the physical link, you can + embed_ FQ-Codel into a classful shaping policy to make sure it owns + the queue. If you are not sure if you need to embed your FQ-CoDel + policy into a Shaper, do it. + + +FQ-CoDel is tuned to run ok with its default parameters at 10Gbit +speeds. It might work ok too at other speeds without configuring +anything, but here we will explain some cases when you might want to +tune its parameters. + +When running it at 1Gbit and lower, you may want to reduce the +`queue-limit` to 1000 packets or less. In rates like 10Mbit, you may +want to set it to 600 packets. + +If you are using FQ-CoDel embedded into Shaper_ and you have large rates +(100Mbit and above), you may consider increasing `quantum` to 8000 or +higher so that the scheduler saves CPU. + +On low rates (below 40Mbit) you may want to tune `quantum` down to +something like 300 bytes. + +At very low rates (below 3Mbit), besides tuning `quantum` (300 keeps +being ok) you may also want to increase `target` to something like 15ms +and increase `interval` to something around 150 ms. + + +.. cfgcmd:: set traffic-policy fq-codel <policy name> codel-quantum <bytes> + + Use this command to configure an fq-codel policy, set its name and + the maximum number of bytes (default: 1514) to be dequeued from a + queue at once. + +.. cfgcmd:: set traffic-policy fq-codel <policy name> flows <number-of-flows> + + Use this command to configure an fq-codel policy, set its name and + the number of sub-queues (default: 1024) into which packets are + classified. + +.. cfgcmd:: set traffic-policy fq-codel <policy name> interval <miliseconds> + + Use this command to configure an fq-codel policy, set its name and + the time period used by the control loop of CoDel to detect when a + persistent queue is developing, ensuring that the measured minimum + delay does not become too stale (default: 100ms). + +.. cfgcmd:: set traffic-policy fq-codel <policy-name> queue-limit + <number-of-packets>` + + Use this command to configure an fq-codel policy, set its name, and + define a hard limit on the real queue size. When this limit is + reached, new packets are dropped (default: 10240 packets). + +.. cfgcmd:: set traffic-policy fq-codel <policy-name> target <miliseconds>` + + Use this command to configure an fq-codel policy, set its name, and + define the acceptable minimum standing/persistent queue delay. This + minimum delay is identified by tracking the local minimum queue delay + that packets experience (default: 5ms). + + +Example +^^^^^^^ + +A simple example of an FQ-CoDel policy working inside a Shaper one. + + +.. code-block:: none + + set traffic-policy shaper FQ-CODEL-SHAPER bandwidth 2gbit + set traffic-policy shaper FQ-CODEL-SHAPER default bandwidth 100% + set traffic-policy shaper FQ-CODEL-SHAPER default queue-type fq-codel + + + +Limiter +------- + +| **Queueing discipline:** Ingress policer. +| **Applies to:** Inbound traffic. + +Limiter is one of those policies that uses classes_ (Ingress qdisc is +actually a classless policy but filters do work in it). + +The limiter performs basic ingress policing of traffic flows. Multiple +classes of traffic can be defined and traffic limits can be applied to +each class. Although the policer uses a token bucket mechanism +internally, it does not have the capability to delay a packet as a +shaping mechanism does. Traffic exceeding the defined bandwidth limits +is directly dropped. A maximum allowed burst can be configured too. + +You can configure classes (up to 4090) with different settings and a +default policy which will be applied to any traffic not matching any of +the configured classes. + + +.. note:: In the case you want to apply some kind of **shaping** to your + **inbound** traffic, check the ingress-shaping_ section. + + +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class ID> match + <match-name> description <description> + + Use this command to configure an Ingress Policer, defining its name, + a class identifier (1-4090), a class matching rule name and its + description. + + +Once the matching rules are set for a class, you can start configuring +how you want matching traffic to behave. + + +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class-ID> bandwidth + <rate> + + Use this command to configure an Ingress Policer, defining its name, + a class identifier (1-4090) and the maximum allowed bandwidth for + this class. + + +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class-ID> burst + <burst-size> + + Use this command to configure an Ingress Policer, defining its name, + a class identifier (1-4090) and the burst size in bytes for this + class (default: 15). + + +.. cfgcmd:: set traffic-policy limiter <policy-name> default bandwidth <rate> + + Use this command to configure an Ingress Policer, defining its name + and the maximum allowed bandwidth for its default policy. + + +.. cfgcmd:: set traffic-policy limiter <policy-name> default burst <burst-size> + + Use this command to configure an Ingress Policer, defining its name + and the burst size in bytes (default: 15) for its default policy. + + +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class ID> priority + <value> + + Use this command to configure an Ingress Policer, defining its name, + a class identifier (1-4090), and the priority (0-20, default 20) in + which the rule is evaluated (the lower the number, the higher the + priority). + + + +Network Emulator +---------------- + +| **Queueing discipline:** netem (Network Emulator) + TBF (Token Bucket Filter). +| **Applies to:** Outbound traffic. + +VyOS Network Emulator policy emulates the conditions you can suffer in a +real network. You will be able to configure things like rate, burst, +delay, packet loss, packet corruption or packet reordering. + +This could be helpful if you want to test how an application behaves +under certain network conditions. + + +.. cfgcmd:: set traffic-policy network-emulator <policy-name> bandwidth <rate> + + Use this command to configure the maximum rate at which traffic will + be shaped in a Network Emulator policy. Define the name of the policy + and the rate. + +.. cfgcmd:: set traffic-policy network-emulator <policy-name> burst <burst-size> + + Use this command to configure the burst size of the traffic in a + Network Emulator policy. Define the name of the Network Emulator + policy and its traffic burst size (it will be configured through the + Token Bucket Filter qdisc). Default:15kb. It will only take effect if + you have configured its bandwidth too. + +.. cfgcmd:: set traffic-policy network-emulator <policy-name> network-delay + <delay> + + Use this command to configure a Network Emulator policy defining its + name and the fixed amount of time you want to add to all packet going + out of the interface. The latency will be added through the + Token Bucket Filter qdisc. It will only take effect if you have + configured its bandwidth too. You can use secs, ms and us. Default: + 50ms. + +.. cfgcmd:: set traffic-policy network-emulator <policy-name> packet-corruption + <percent> + + Use this command to emulate noise in a Network Emulator policy. Set + the policy name and the percentage of corrupted packets you want. A + random error will be introduced in a random position for the chosen + percent of packets. + +.. cfgcmd:: set traffic-policy network-emulator <policy-name> packet-loss + <percent> + + Use this command to emulate packet-loss conditions in a Network + Emulator policy. Set the policy name and the percentage of loss + packets your traffic will suffer. + +.. cfgcmd:: set traffic-policy network-emulator <policy-name> packet-reordering + <percent> + + Use this command to emulate packet-reordering conditions in a Network + Emulator policy. Set the policy name and the percentage of reordered + packets your traffic will suffer. + +.. cfgcmd:: set traffic-policy network-emulator <policy-name> queue-limit + <limit> + + Use this command to define the length of the queue of your Network + Emulator policy. Set the policy name and the maximum number of + packets (1-4294967295) the queue may hold queued at a time. + + + +Priority Queue +-------------- + +| **Queueing discipline:** PRIO. +| **Applies to:** Outbound traffic. + + +The Priority Queue is a classful scheduling policy. It does not delay +packets (Priority Queue is not a shaping policy), it simply dequeues +packets according to their priority. + +.. note:: Priority Queue, as other non-shaping policies, is only useful + if your outgoing interface is really full. If it is not, VyOS will + not own the queue and Priority Queue will have no effect. If there is + bandwidth available on the physical link, you can embed_ Priority + Queue into a classful shaping policy to make sure it owns the queue. + In that case packets can be prioritized based on DSCP. + +Up to seven queues -defined as classes_ with different priorities- can +be configured. Packets are placed into queues based on associated match +criteria. Packets are transmitted from the queues in priority order. If +classes with a higher priority are being filled with packets +continuously, packets from lower priority classes will only be +transmitted after traffic volume from higher priority classes decreases. + + +.. note:: In Priority Queue we do not define clases with a meaningless + class ID number but with a class priority number (1-7). The lower the + number, the higher the priority. + + +As with other policies, you can define different type of matching rules +for your classes: + +.. code-block:: none + + vyos@vyos# set traffic-policy priority-queue MY-PRIO class 3 match MY-MATCH-RULE + Possible completions: + description Description for this match + > ether Ethernet header match + interface Interface name for this match + > ip Match IP protocol header + > ipv6 Match IPV6 header + mark Match on mark applied by firewall + vif Virtual Local Area Network (VLAN) ID for this match + + +As with other policies, you can embed_ other policies into the classes +(and default) of your Priority Queue policy through the ``queue-type`` +setting: + +.. code-block:: none + + vyos@vyos# set traffic-policy priority-queue MY-PRIO class 3 queue-type + Possible completions: + fq-codel Fair Queue Codel + fair-queue Stochastic Fair Queue (SFQ) + drop-tail First-In-First-Out (FIFO) + priority Priority queueing based on DSCP + random-detect + Random Early Detection (RED) + + +.. cfgcmd:: set traffic-policy priority-queue <policy-name> class <class-ID> + queue-limit <limit>` + + Use this command to configure a Priority Queue policy, set its name, + set a class with a priority from 1 to 7 and define a hard limit on + the real queue size. When this limit is reached, new packets are + dropped. + + + +.. _Random-Detect: + +Random-Detect +------------- + + +| **Queueing discipline:** Generalized Random Early Drop. +| **Applies to:** Outbound traffic. + +A simple Random Early Detection (RED) policy would start randomly +dropping packets from a queue before it reaches its queue limit thus +avoiding congestion. That is good for TCP connections as the gradual +dropping of packets acts as a signal for the sender to decrease its +transmission rate. + +In contrast to simple RED, VyOS' Random-Detect uses a Generalized Random +Early Detect policy that provides different virtual queues based on the +IP Precedence value so that some virtual queues can drop more packets +than others. + +This is achieved by using the first three bits of the ToS (Type of +Service) field to categorize data streams and, in accordance with the +defined precedence parameters, a decision is made. + +IP precedence as defined in :rfc:`791`: + + +------------+----------------------+ + | Precedence | Priority | + +============+======================+ + | 7 | Network Control | + +------------+----------------------+ + | 6 | Internetwork Control | + +------------+----------------------+ + | 5 | CRITIC/ECP | + +------------+----------------------+ + | 4 | Flash Override | + +------------+----------------------+ + | 3 | Flash | + +------------+----------------------+ + | 2 | Immediate | + +------------+----------------------+ + | 1 | Priority | + +------------+----------------------+ + | 0 | Routine | + +------------+----------------------+ + + +Random-Detect could be useful for heavy traffic. One use of this +algorithm might be to prevent a backbone overload. But only for TCP +(because dropped packets could be retransmitted), not for UDP. + + +.. cfgcmd:: set traffic-policy random-detect <policy-name> bandwidth <bandwidth> + + Use this command to configure a Random-Detect policy, set its name + and set the available bandwidth for this policy. It is used for + calculating the average queue size after some idle time. It should be + set to the bandwidth of your interface. Random Detect is not a + shaping policy, this command will not shape. + +.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence + <IP-precedence-value> average-packet <bytes> + + Use this command to configure a Random-Detect policy and set its + name, then state the IP Precedence for the virtual queue you are + configuring and what the size of its average-packet should be + (in bytes, default: 1024). + +.. note:: When configuring a Random-Detect policy: **the higher the + precedence number, the higher the priority**. + +.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence + <IP-precedence-value> mark-probability <value> + + Use this command to configure a Random-Detect policy and set its + name, then state the IP Precedence for the virtual queue you are + configuring and what its mark (drop) probability will be. Set the + probability by giving the N value of the fraction 1/N (default: 10). + + +.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence + <IP-precedence-value> maximum-threshold <packets> + + Use this command to configure a Random-Detect policy and set its + name, then state the IP Precedence for the virtual queue you are + configuring and what its maximum threshold for random detection will + be (from 0 to 4096 packets, default: 18). At this size, the marking + (drop) probability is maximal. + +.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence + <IP-precedence-value> minimum-threshold <packets> + + Use this command to configure a Random-Detect policy and set its + name, then state the IP Precedence for the virtual queue you are + configuring and what its minimum threshold for random detection will + be (from 0 to 4096 packets). If this value is exceeded, packets + start being eligible for being dropped. + + +The default values for the minimum-threshold depend on IP precedence: + + +------------+-----------------------+ + | Precedence | default min-threshold | + +============+=======================+ + | 7 | 16 | + +------------+-----------------------+ + | 6 | 15 | + +------------+-----------------------+ + | 5 | 14 | + +------------+-----------------------+ + | 4 | 13 | + +------------+-----------------------+ + | 3 | 12 | + +------------+-----------------------+ + | 2 | 11 | + +------------+-----------------------+ + | 1 | 10 | + +------------+-----------------------+ + | 0 | 9 | + +------------+-----------------------+ + + +.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence + <IP-precedence-value> queue-limit <packets> + + Use this command to configure a Random-Detect policy and set its + name, then name the IP Precedence for the virtual queue you are + configuring and what the maximum size of its queue will be (from 1 to + 1-4294967295 packets). Packets are dropped when the current queue + length reaches this value. + + +If the average queue size is lower than the **min-threshold**, an +arriving packet will be placed in the queue. + +In the case the average queue size is between **min-threshold** and +**max-threshold**, then an arriving packet would be either dropped or +placed in the queue, it will depend on the defined **mark-probability**. + +If the current queue size is larger than **queue-limit**, +then packets will be dropped. The average queue size depends on its +former average size and its current one. + +If **max-threshold** is set but **min-threshold is not, then +**min-threshold** is scaled to 50% of **max-threshold**. + +In principle, values must be +:code:`min-threshold` < :code:`max-threshold` < :code:`queue-limit`. + + + + +Rate Control +------------ + +| **Queueing discipline:** Tocken Bucket Filter. +| **Applies to:** Outbound traffic. + +Rate-Control is a classless policy that limits the packet flow to a set +rate. It is a pure shaper, it does not schedule traffic. Traffic is +filtered based on the expenditure of tokens. Tokens roughly correspond +to bytes. + +Short bursts can be allowed to exceed the limit. On creation, the +Rate-Control traffic is stocked with tokens which correspond to the +amount of traffic that can be burst in one go. Tokens arrive at a steady +rate, until the bucket is full. + +.. cfgcmd:: set traffic-policy rate-control <policy-name> bandwidth <rate> + + Use this command to configure a Rate-Control policy, set its name + and the rate limit you want to have. + +.. cfgcmd:: set traffic-policy rate-control <policy-name> burst <burst-size> + + Use this command to configure a Rate-Control policy, set its name + and the size of the bucket in bytes which will be available for + burst. + + +As a reference: for 10mbit/s on Intel, you might need at least 10kbyte +buffer if you want to reach your configured rate. + +A very small buffer will soon start dropping packets. + +.. cfgcmd:: set traffic-policy rate-control <policy-name> latency + + Use this command to configure a Rate-Control policy, set its name + and the maximum amount of time a packet can be queued (default: 50 + ms). + + +Rate-Control is a CPU-friendly policy. You might consider using it when +you just simply want to slow traffic down. + +.. _DRR: + +Round Robin +----------- + +| **Queueing discipline:** Deficit Round Robin. +| **Applies to:** Outbound traffic. + +The round-robin policy is a classful scheduler that divides traffic in +different classes_ you can configure (up to 4096). You can embed_ a +new policy into each of those classes (default included). + +Each class is assigned a deficit counter (the number of bytes that a +flow is allowed to transmit when it is its turn) initialized to quantum. +Quantum is a parameter you configure which acts like a credit of fix +bytes the counter receives on each round. Then the Round-Robin policy +starts moving its Round Robin pointer through the queues. If the deficit +counter is greater than the packet's size at the head of the queue, this +packet will be sent and the value of the counter will be decremented by +the packet size. Then, the size of the next packet will be compared to +the counter value again, repeating the process. Once the queue is empty +or the value of the counter is insufficient, the Round-Robin pointer +will move to the next queue. If the queue is empty, the value of the +deficit counter is reset to 0. + +At every round, the deficit counter adds the quantum so that even large +packets will have their opportunity to be dequeued. + + +.. cfgcmd:: set traffic-policy round-robin <policy name> class + <class-ID> quantum <packets> + + Use this command to configure a Round-Robin policy, set its name, set + a class ID, and the quantum for that class. The deficit counter will + add that value each round. + +.. cfgcmd:: set traffic-policy round-robin <policy name> class + <class ID> queue-limit <packets> + + Use this command to configure a Round-Robin policy, set its name, set + a class ID, and the queue size in packets. + +As with other policies, Round-Robin can embed_ another policy into a +class through the ``queue-type`` setting. + +.. code-block:: none + + vyos@vyos# set traffic-policy round-robin DRR class 10 queue-type + Possible completions: + fq-codel Fair Queue Codel + fair-queue Stochastic Fair Queue (SFQ) + drop-tail First-In-First-Out (FIFO) + priority Priority queueing based on DSCP + + + + +.. _Shaper: + +Shaper +------ + +| **Queueing discipline:** Hierarchical Token Bucket. +| **Applies to:** Outbound traffic. + + +The Shaper policy does not guarantee a low delay, but it does guarantee +bandwidth to different traffic classes and also lets you decide how to +allocate more traffic once the guarantees are met. + +Each class can have a guaranteed part of the total bandwidth defined for +the whole policy, so all those shares together should not be higher +than the policy's whole bandwidth. + +If guaranteed traffic for a class is met and there is room for more +traffic, the ceiling parameter can be used to set how much more +bandwidth could be used. If guaranteed traffic is met and there are +several classes willing to use their ceilings, the priority parameter +will establish the order in which that additional traffic will be +allocated. Priority can be any number from 0 to 7. The lower the number, +the higher the priority. + + +.. cfgcmd:: set traffic-policy shaper <policy-name> bandwidth <rate> + + Use this command to configure a Shaper policy, set its name + and the maximum bandwidth for all combined traffic. + + +.. cfgcmd:: set traffic-policy shaper <policy-name> class <class-ID> bandwidth + <rate> + + Use this command to configure a Shaper policy, set its name, define + a class and set the guaranteed traffic you want to allocate to that + class. + +.. cfgcmd:: set traffic-policy shaper <policy-name> class <class-ID> burst + <bytes> + + Use this command to configure a Shaper policy, set its name, define + a class and set the size of the `tocken bucket`_ in bytes, which will + be available to be sent at ceiling speed (default: 15Kb). + +.. cfgcmd:: set traffic-policy shaper <policy-name> class <class-ID> ceiling + <bandwidth> + + Use this command to configure a Shaper policy, set its name, define + a class and set the maximum speed possible for this class. The + default ceiling value is the bandwidth value. + +.. cfgcmd:: set traffic-policy shaper <policy-name> class <class-ID> priority + <0-7> + + Use this command to configure a Shaper policy, set its name, define + a class and set the priority for usage of available bandwidth once + guarantees have been met. The lower the priority number, the higher + the priority. The default priority value is 0, the highest priority. + + +As with other policies, Shaper can embed_ other policies into its +classes through the ``queue-type`` setting and then configure their +parameters. + + +.. code-block:: none + + vyos@vyos# set traffic-policy shaper HTB class 10 queue-type + Possible completions: + fq-codel Fair Queue Codel + fair-queue Stochastic Fair Queue (SFQ) + drop-tail First-In-First-Out (FIFO) + priority Priority queueing based on DSCP + random-detect + Random Early Detection (RED) + + +.. code-block:: none + + vyos@vyos# set traffic-policy shaper HTB class 10 + Possible completions: + bandwidth Bandwidth used for this class + burst Burst size for this class (default: 15kb) + ceiling Bandwidth limit for this class + codel-quantum + fq-codel - Number of bytes used as 'deficit' (default 1514) + description Description for this traffic class + flows fq-codel - Number of flows (default 1024) + interval fq-codel - Interval (milliseconds) used to measure the delay (default 100) + +> match Class matching rule name + priority Priority for usage of excess bandwidth + queue-limit Maximum queue size (packets) + queue-type Queue type for this class + set-dscp Change the Differentiated Services (DiffServ) field in the IP header + target fq-codel - Acceptable minimum queue delay (milliseconds) + + + +.. note:: If you configure a class for **VoIP traffic**, don't give it any + *ceiling*, otherwise new VoIP calls could start when the link is + available and get suddenly dropped when other classes start using + their assigned *bandwidth* share. + + +Example +^^^^^^^ + +A simple example of Shaper using priorities. + + +.. code-block:: none + + set traffic-policy shaper MY-HTB bandwidth '50mbit' + set traffic-policy shaper MY-HTB class 10 bandwidth '20%' + set traffic-policy shaper MY-HTB class 10 match DSCP ip dscp 'EF' + set traffic-policy shaper MY-HTB class 10 queue-type 'fq-codel' + set traffic-policy shaper MY-HTB class 20 bandwidth '10%' + set traffic-policy shaper MY-HTB class 20 ceiling '50%' + set traffic-policy shaper MY-HTB class 20 match PORT666 ip destination port '666' + set traffic-policy shaper MY-HTB class 20 priority '3' + set traffic-policy shaper MY-HTB class 20 queue-type 'fair-queue' + set traffic-policy shaper MY-HTB class 30 bandwidth '10%' + set traffic-policy shaper MY-HTB class 30 ceiling '50%' + set traffic-policy shaper MY-HTB class 30 match ADDRESS30 ip source address '192.168.30.0/24' + set traffic-policy shaper MY-HTB class 30 priority '5' + set traffic-policy shaper MY-HTB class 30 queue-type 'fair-queue' + set traffic-policy shaper MY-HTB default bandwidth '10%' + set traffic-policy shaper MY-HTB default ceiling '100%' + set traffic-policy shaper MY-HTB default priority '7' + set traffic-policy shaper MY-HTB default queue-type 'fair-queue' + + +Applying a traffic policy +========================= + +Once a traffic-policy is created, you can apply it to an interface: + +.. code-block:: none + + set interfaces etherhet eth0 traffic-policy out WAN-OUT + +You can only apply one policy per interface and direction, but you could +reuse a policy on different interfaces and directions: + +.. code-block:: none + + set interfaces ethernet eth0 traffic-policy in WAN-IN + set interfaces etherhet eth0 traffic-policy out WAN-OUT + set interfaces etherhet eth1 traffic-policy in LAN-IN + set interfaces etherhet eth1 traffic-policy out LAN-OUT + set interfaces ethernet eth2 traffic-policy in LAN-IN + set interfaces ethernet eth2 traffic-policy out LAN-OUT + set interfaces etherhet eth3 traffic-policy in TWO-WAY-POLICY + set interfaces etherhet eth3 traffic-policy out TWO-WAY-POLICY + set interfaces etherhet eth4 traffic-policy in TWO-WAY-POLICY + set interfaces etherhet eth4 traffic-policy out TWO-WAY-POLICY + +Getting queueing information +---------------------------- + +.. opcmd:: show queueing <interface-type> <interface-name> + + Use this command to see the queueing information for an interface. + You will be able to see a packet counter (Sent, Dropped, Overlimit + and Backlog) per policy and class configured. + + + +.. _ingress-shaping: + +The case of ingress shaping +=========================== + +| **Applies to:** Inbound traffic. + +For the ingress traffic of an interface, there is only one policy you +can directly apply, a **Limiter** policy. You cannot apply a shaping +policy directly to the ingress traffic of any interface because shaping +only works for outbound traffic. + +This workaround lets you apply a shaping policy to the ingress traffic +by first redirecting it to an in-between virtual interface +(`Intermediate Functional Block`_). There, in that virtual interface, +you will be able to apply any of the policies that work for outbound +traffic, for instance, a shaping one. + +That is how it is possible to do the so-called "ingress shaping". + + +.. code-block:: none + + set traffic-policy shaper MY-INGRESS-SHAPING bandwidth 1000kbit + set traffic-policy shaper MY-INGRESS-SHAPING default bandwidth 1000kbit + set traffic-policy shaper MY-INGRESS-SHAPING default queue-type fair-queue + + set interfaces input ifb0 traffic-policy out MY-INGRESS-SHAPING + set interfaces ethernet eth0 redirect ifb0 + +.. warning:: + + Do not configure IFB as the first step. First create everything else + of your traffic-policy, and then you can configure IFB. + Otherwise you might get the ``RTNETLINK answer: File exists`` error, + which can be solved with ``sudo ip link delete ifb0``. + + +.. stop_vyoslinter + +.. _that can give you a great deal of flexibility: https://blog.vyos.io/using-the-policy-route-and-packet-marking-for-custom-qos-matches +.. _tc: https://en.wikipedia.org/wiki/Tc_(Linux) +.. _tocken bucket: https://en.wikipedia.org/wiki/Token_bucket +.. _HFSC: https://en.wikipedia.org/wiki/Hierarchical_fair-service_curve +.. _Intermediate Functional Block: https://www.linuxfoundation.org/collaborate/workgroups/networking/ifb + +.. start_vyoslinter
\ No newline at end of file diff --git a/docs/configuration/vpn/dmvpn.rst b/docs/configuration/vpn/dmvpn.rst new file mode 100644 index 00000000..f902c388 --- /dev/null +++ b/docs/configuration/vpn/dmvpn.rst @@ -0,0 +1,336 @@ +.. _vpn-dmvpn: + +##### +DMVPN +##### + +:abbr:`DMVPN (Dynamic Multipoint Virtual Private Network)` is a dynamic +:abbr:`VPN (Virtual Private Network)` technology originally developed by Cisco. +While their implementation was somewhat proprietary, the underlying +technologies are actually standards based. The three technologies are: + +* :abbr:`NHRP (Next Hop Resolution Protocol)` :rfc:`2332` +* :abbr:`mGRE (Multipoint Generic Routing Encapsulation)` :rfc:`1702` +* :abbr:`IPSec (IP Security)` - too many RFCs to list, but start with + :rfc:`4301` + +NHRP provides the dynamic tunnel endpoint discovery mechanism (endpoint +registration, and endpoint discovery/lookup), mGRE provides the tunnel +encapsulation itself, and the IPSec protocols handle the key exchange, and +crypto mechanism. + +In short, DMVPN provides the capability for creating a dynamic-mesh VPN +network without having to pre-configure (static) all possible tunnel end-point +peers. + +.. note:: DMVPN only automates the tunnel endpoint discovery and setup. A + complete solution also incorporates the use of a routing protocol. BGP is + particularly well suited for use with DMVPN. + +.. figure:: /_static/images/vpn_dmvpn_topology01.png + :scale: 40 % + :alt: Baseline DMVPN topology + + Baseline DMVPN topology + +************* +Configuration +************* + +* Please refer to the :ref:`tunnel-interface` documentation for the individual + tunnel related options. + +* Please refer to the :ref:`ipsec` documentation for the individual IPSec + related options. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> cisco-authentication <secret> + + Enables Cisco style authentication on NHRP packets. This embeds the secret + plaintext password to the outgoing NHRP packets. Incoming NHRP packets on + this interface are discarded unless the secret password is present. Maximum + length of the secret is 8 characters. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> dynamic-map <address> + nbma-domain-name <fqdn> + + Specifies that the :abbr:`NBMA (Non-broadcast multiple-access network)` + addresses of the next hop servers are defined in the domain name + nbma-domain-name. For each A record opennhrp creates a dynamic NHS entry. + + Each dynamic NHS will get a peer entry with the configured network address + and the discovered NBMA address. + + The first registration request is sent to the protocol broadcast address, and + the server's real protocol address is dynamically detected from the first + registration reply. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> holding-time <timeout> + + Specifies the holding time for NHRP Registration Requests and Resolution + Replies sent from this interface or shortcut-target. The holdtime is specified + in seconds and defaults to two hours. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> map cisco + + If the statically mapped peer is running Cisco IOS, specify the cisco keyword. + It is used to fix statically the Registration Request ID so that a matching + Purge Request can be sent if NBMA address has changed. This is to work around + broken IOS which requires Purge Request ID to match the original Registration + Request ID. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> map nbma-address <address> + + Creates static peer mapping of protocol-address to :abbr:`NBMA (Non-broadcast + multiple-access network)` address. + + If the IP prefix mask is present, it directs opennhrp to use this peer as a + next hop server when sending Resolution Requests matching this subnet. + + This is also known as the HUBs IP address or FQDN. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> map register + + The optional parameter register specifies that Registration Request should be + sent to this peer on startup. + + This option is required when running a DMVPN spoke. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> multicast <dynamic | nhs> + + Determines how opennhrp daemon should soft switch the multicast traffic. + Currently, multicast traffic is captured by opennhrp daemon using a packet + socket, and resent back to proper destinations. This means that multicast + packet sending is CPU intensive. + + Specfying nhs makes all multicast packets to be repeated to each statically + configured next hop. + + Synamic instructs to forward to all peers which we have a direct connection + with. Alternatively, you can specify the directive multiple times for each + protocol-address the multicast traffic should be sent to. + + .. warning:: It is very easy to misconfigure multicast repeating if you have + multiple NHSes. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> non-caching + + Disables caching of peer information from forwarded NHRP Resolution Reply + packets. This can be used to reduce memory consumption on big NBMA subnets. + + .. note:: Currently does not do much as caching is not implemented. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> redirect + + Enable sending of Cisco style NHRP Traffic Indication packets. If this is + enabled and opennhrp detects a forwarded packet, it will send a message to + the original sender of the packet instructing it to create a direct connection + with the destination. This is basically a protocol independent equivalent of + ICMP redirect. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> shortcut + + Enable creation of shortcut routes. + + A received NHRP Traffic Indication will trigger the resolution and + establishment of a shortcut route. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> shortcut-destination + + This instructs opennhrp to reply with authorative answers on NHRP Resolution + Requests destinied to addresses in this interface (instead of forwarding the + packets). This effectively allows the creation of shortcut routes to subnets + located on the interface. + + When specified, this should be the only keyword for the interface. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> shortcut-target <address> + + Defines an off-NBMA network prefix for which the GRE interface will act as a + gateway. This an alternative to defining local interfaces with + shortcut-destination flag. + +.. cfgcmd:: set protocols nhrp tunnel <tunnel> shortcut-target <address> + holding-time <timeout> + + Specifies the holding time for NHRP Registration Requests and Resolution + Replies sent from this interface or shortcut-target. The holdtime is specified + in seconds and defaults to two hours. + +******* +Example +******* + + +This blueprint uses VyOS as the DMVPN Hub and Cisco (7206VXR) and VyOS as +multiple spoke sites. The lab was build using :abbr:`EVE-NG (Emulated Virtual +Environment NG)`. + +.. figure:: /_static/images/blueprint-dmvpn.png + :alt: DMVPN network + + DMVPN example network + +Each node (Hub and Spoke) uses an IP address from the network 172.16.253.128/29. + +The below referenced IP address `192.0.2.1` is used as example address +representing a global unicast address under which the HUB can be contacted by +each and every individual spoke. + +Configuration +============= + +Hub +--- + +.. code-block:: none + + set interfaces ethernet eth0 address 192.0.2.1/24 + + set interfaces tunnel tun100 address '172.16.253.134/29' + set interfaces tunnel tun100 encapsulation 'gre' + set interfaces tunnel tun100 local-ip '192.0.2.1' + set interfaces tunnel tun100 multicast 'enable' + set interfaces tunnel tun100 parameters ip key '1' + + set protocols nhrp tunnel tun100 cisco-authentication 'secret' + set protocols nhrp tunnel tun100 holding-time '300' + set protocols nhrp tunnel tun100 multicast 'dynamic' + set protocols nhrp tunnel tun100 redirect + set protocols nhrp tunnel tun100 shortcut + + set vpn ipsec esp-group ESP-HUB compression 'disable' + set vpn ipsec esp-group ESP-HUB lifetime '1800' + set vpn ipsec esp-group ESP-HUB mode 'transport' + set vpn ipsec esp-group ESP-HUB pfs 'dh-group2' + set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' + set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' + set vpn ipsec esp-group ESP-HUB proposal 2 encryption '3des' + set vpn ipsec esp-group ESP-HUB proposal 2 hash 'md5' + set vpn ipsec ike-group IKE-HUB ikev2-reauth 'no' + set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' + set vpn ipsec ike-group IKE-HUB lifetime '3600' + set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' + set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' + set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' + set vpn ipsec ike-group IKE-HUB proposal 2 dh-group '2' + set vpn ipsec ike-group IKE-HUB proposal 2 encryption 'aes128' + set vpn ipsec ike-group IKE-HUB proposal 2 hash 'sha1' + + set vpn ipsec ipsec-interfaces interface 'eth0' + + set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' + set vpn ipsec profile NHRPVPN authentication pre-shared-secret 'secret' + set vpn ipsec profile NHRPVPN bind tunnel 'tun100' + set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' + set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' + +.. note:: Setting this up on AWS will require a "Custom Protocol Rule" for + protocol number "47" (GRE) Allow Rule in TWO places. Firstly on the VPC + Network ACL, and secondly on the security group network ACL attached to the + EC2 instance. This has been tested as working for the official AMI image on + the AWS Marketplace. (Locate the correct VPC and security group by navigating + through the details pane below your EC2 instance in the AWS console). + +Spoke +----- + +The individual spoke configurations only differ in the local IP address on the +``tun10`` interface. See the above diagram for the individual IP addresses. + +spoke01-spoke04 +^^^^^^^^^^^^^^^ + +.. code-block:: none + + crypto keyring DMVPN + pre-shared-key address 192.0.2.1 key secret + ! + crypto isakmp policy 10 + encr aes 256 + authentication pre-share + group 2 + crypto isakmp invalid-spi-recovery + crypto isakmp keepalive 30 30 periodic + crypto isakmp profile DMVPN + keyring DMVPN + match identity address 192.0.2.1 255.255.255.255 + ! + crypto ipsec transform-set DMVPN-AES256 esp-aes 256 esp-sha-hmac + mode transport + ! + crypto ipsec profile DMVPN + set security-association idle-time 720 + set transform-set DMVPN-AES256 + set isakmp-profile DMVPN + ! + interface Tunnel10 + ! individual spoke tunnel IP must change + ip address 172.16.253.129 255.255.255.248 + no ip redirects + ip nhrp authentication secret + ip nhrp map 172.16.253.134 192.0.2.1 + ip nhrp map multicast 192.0.2.1 + ip nhrp network-id 1 + ip nhrp holdtime 600 + ip nhrp nhs 172.16.253.134 + ip nhrp registration timeout 75 + tunnel source FastEthernet0/0 + tunnel mode gre multipoint + tunnel key 1 + ! + interface FastEthernet0/0 + ip address dhcp + duplex half + + +spoke05 +^^^^^^^ + +VyOS can also run in DMVPN spoke mode. + +.. code-block:: none + + set interfaces ethernet eth0 address 'dhcp' + + set interfaces tunnel tun100 address '172.16.253.133/29' + set interfaces tunnel tun100 local-ip 0.0.0.0 + set interfaces tunnel tun100 encapsulation 'gre' + set interfaces tunnel tun100 multicast 'enable' + set interfaces tunnel tun100 parameters ip key '1' + + set protocols nhrp tunnel tun100 cisco-authentication 'secret' + set protocols nhrp tunnel tun100 holding-time '300' + set protocols nhrp tunnel tun100 map 172.16.253.134/29 nbma-address '192.0.2.1' + set protocols nhrp tunnel tun100 map 172.16.253.134/29 register + set protocols nhrp tunnel tun100 multicast 'nhs' + set protocols nhrp tunnel tun100 redirect + set protocols nhrp tunnel tun100 shortcut + + set vpn ipsec esp-group ESP-HUB compression 'disable' + set vpn ipsec esp-group ESP-HUB lifetime '1800' + set vpn ipsec esp-group ESP-HUB mode 'transport' + set vpn ipsec esp-group ESP-HUB pfs 'dh-group2' + set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' + set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' + set vpn ipsec esp-group ESP-HUB proposal 2 encryption '3des' + set vpn ipsec esp-group ESP-HUB proposal 2 hash 'md5' + set vpn ipsec ike-group IKE-HUB close-action 'none' + set vpn ipsec ike-group IKE-HUB ikev2-reauth 'no' + set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' + set vpn ipsec ike-group IKE-HUB lifetime '3600' + set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' + set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' + set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' + set vpn ipsec ike-group IKE-HUB proposal 2 dh-group '2' + set vpn ipsec ike-group IKE-HUB proposal 2 encryption 'aes128' + set vpn ipsec ike-group IKE-HUB proposal 2 hash 'sha1' + + set vpn ipsec ipsec-interfaces interface 'eth0' + + set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' + set vpn ipsec profile NHRPVPN authentication pre-shared-secret 'secret' + set vpn ipsec profile NHRPVPN bind tunnel 'tun100' + set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' + set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' + + diff --git a/docs/configuration/vpn/index.rst b/docs/configuration/vpn/index.rst new file mode 100644 index 00000000..abaca198 --- /dev/null +++ b/docs/configuration/vpn/index.rst @@ -0,0 +1,26 @@ +### +VPN +### + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + ipsec + l2tp + openconnect + pptp + rsa-keys + sstp + + + +pages to sort + +.. toctree:: + :maxdepth: 1 + :includehidden: + + dmvpn + site2site_ipsec
\ No newline at end of file diff --git a/docs/configuration/vpn/ipsec.rst b/docs/configuration/vpn/ipsec.rst new file mode 100644 index 00000000..2888336c --- /dev/null +++ b/docs/configuration/vpn/ipsec.rst @@ -0,0 +1,192 @@ +.. _ipsec: + +##### +IPsec +##### + +:abbr:`GRE (Generic Routing Encapsulation)`, GRE/IPsec (or IPIP/IPsec, +SIT/IPsec, or any other stateless tunnel protocol over IPsec) is the usual way +to protect the traffic inside a tunnel. + +An advantage of this scheme is that you get a real interface with its own +address, which makes it easier to setup static routes or use dynamic routing +protocols without having to modify IPsec policies. The other advantage is that +it greatly simplifies router to router communication, which can be tricky with +plain IPsec because the external outgoing address of the router usually doesn't +match the IPsec policy of typical site-to-site setup and you need to add special +configuration for it, or adjust the source address for outgoing traffic of your +applications. GRE/IPsec has no such problem and is completely transparent for +the applications. + +GRE/IPIP/SIT and IPsec are widely accepted standards, which make this scheme +easy to implement between VyOS and virtually any other router. + +For simplicity we'll assume that the protocol is GRE, it's not hard to guess +what needs to be changed to make it work with a different protocol. We assume +that IPsec will use pre-shared secret authentication and will use AES128/SHA1 +for the cipher and hash. Adjust this as necessary. + +.. NOTE:: VMware users should ensure that a VMXNET3 adapter is used. E1000 + adapters have known issues with GRE processing. + +************************* +IPsec policy matching GRE +************************* + +The first and arguably cleaner option is to make your IPsec policy match GRE +packets between external addresses of your routers. This is the best option if +both routers have static external addresses. + +Suppose the LEFT router has external address 192.0.2.10 on its eth0 interface, +and the RIGHT router is 203.0.113.45 + +On the LEFT: + +.. code-block:: none + + # GRE tunnel + set interfaces tunnel tun0 encapsulation gre + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 203.0.113.45 + set interfaces tunnel tun0 address 10.10.10.1/30 + + ## IPsec + set vpn ipsec ipsec-interfaces interface eth0 + + # IKE group + set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '2' + set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes128' + set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha1' + + # ESP group + set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes128' + set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha1' + + # IPsec tunnel + set vpn ipsec site-to-site peer 203.0.113.45 authentication mode pre-shared-secret + set vpn ipsec site-to-site peer 203.0.113.45 authentication pre-shared-secret MYSECRETKEY + + set vpn ipsec site-to-site peer 203.0.113.45 ike-group MyIKEGroup + set vpn ipsec site-to-site peer 203.0.113.45 default-esp-group MyESPGroup + + set vpn ipsec site-to-site peer 203.0.113.45 local-address 192.0.2.10 + + # This will match all GRE traffic to the peer + set vpn ipsec site-to-site peer 203.0.113.45 tunnel 1 protocol gre + +On the RIGHT, setup by analogy and swap local and remote addresses. + + +Source tunnel from loopbacks +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The scheme above doesn't work when one of the routers has a dynamic external +address though. The classic workaround for this is to setup an address on a +loopback interface and use it as a source address for the GRE tunnel, then setup +an IPsec policy to match those loopback addresses. + +We assume that the LEFT router has static 192.0.2.10 address on eth0, and the +RIGHT router has a dynamic address on eth0. + +**Setting up the GRE tunnel** + +On the LEFT: + +.. code-block:: none + + set interfaces loopback lo address 192.168.99.1/32 + + set interfaces tunnel tun0 encapsulation gre + set interfaces tunnel tun0 address 10.10.10.1/30 + set interfaces tunnel tun0 local-ip 192.168.99.1 + set interfaces tunnel tun0 remote-ip 192.168.99.2 + +On the RIGHT: + +.. code-block:: none + + set interfaces loopback lo address 192.168.99.2/32 + + set interfaces tunnel tun0 encapsulation gre + set interfaces tunnel tun0 address 10.10.10.2/30 + set interfaces tunnel tun0 local-ip 192.168.99.2 + set interfaces tunnel tun0 remote-ip 192.168.99.1 + +**Setting up IPSec** + +However, now you need to make IPsec work with dynamic address on one side. The +tricky part is that pre-shared secret authentication doesn't work with dynamic +address, so we'll have to use RSA keys. + +First, on both routers run the operational command "generate vpn rsa-key bits +2048". You may choose different length than 2048 of course. + +.. code-block:: none + + vyos@left# run generate vpn rsa-key bits 2048 + Generating rsa-key to /config/ipsec.d/rsa-keys/localhost.key + + Your new local RSA key has been generated + The public portion of the key is: + + 0sAQO2335[long string here] + +Then on the opposite router, add the RSA key to your config. + +.. code-block:: none + + set vpn rsa-keys rsa-key-name LEFT rsa-key KEYGOESHERE + +Now you are ready to setup IPsec. You'll need to use an ID instead of address +for the peer on the dynamic side. + +On the LEFT (static address): + +.. code-block:: none + + set vpn rsa-keys rsa-key-name RIGHT rsa-key <PUBLIC KEY FROM THE RIGHT> + + set vpn ipsec ipsec-interfaces interface eth0 + + set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128 + set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1 + + set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2 + set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128 + set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1 + + set vpn ipsec site-to-site peer @RIGHT authentication mode rsa + set vpn ipsec site-to-site peer @RIGHT authentication rsa-key-name RIGHT + set vpn ipsec site-to-site peer @RIGHT default-esp-group MyESPGroup + set vpn ipsec site-to-site peer @RIGHT ike-group MyIKEGroup + set vpn ipsec site-to-site peer @RIGHT local-address 192.0.2.10 + set vpn ipsec site-to-site peer @RIGHT connection-type respond + set vpn ipsec site-to-site peer @RIGHT tunnel 1 local prefix 192.168.99.1/32 # Additional loopback address on the local + set vpn ipsec site-to-site peer @RIGHT tunnel 1 remote prefix 192.168.99.2/32 # Additional loopback address on the remote + + +On the RIGHT (dynamic address): + +.. code-block:: none + + set vpn rsa-keys rsa-key-name LEFT rsa-key <PUBLIC KEY FROM THE LEFT> + + set vpn ipsec ipsec-interfaces interface eth0 + + set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128 + set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1 + + set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2 + set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128 + set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1 + + set vpn ipsec site-to-site peer 192.0.2.10 authentication id @RIGHT + set vpn ipsec site-to-site peer 192.0.2.10 authentication mode rsa + set vpn ipsec site-to-site peer 192.0.2.10 authentication rsa-key-name LEFT + set vpn ipsec site-to-site peer 192.0.2.10 authentication remote-id LEFT + set vpn ipsec site-to-site peer 192.0.2.10 connection-type initiate + set vpn ipsec site-to-site peer 192.0.2.10 default-esp-group MyESPGroup + set vpn ipsec site-to-site peer 192.0.2.10 ike-group MyIKEGroup + set vpn ipsec site-to-site peer 192.0.2.10 local-address any + set vpn ipsec site-to-site peer 192.0.2.10 tunnel 1 local prefix 192.168.99.2/32 # Additional loopback address on the local + set vpn ipsec site-to-site peer 192.0.2.10 tunnel 1 remote prefix 192.168.99.1/32 # Additional loopback address on the remote diff --git a/docs/configuration/vpn/l2tp.rst b/docs/configuration/vpn/l2tp.rst new file mode 100644 index 00000000..0df5080c --- /dev/null +++ b/docs/configuration/vpn/l2tp.rst @@ -0,0 +1,232 @@ +.. _l2tp: + +L2TP +---- + +VyOS utilizes accel-ppp_ to provide L2TP server functionality. It can be used +with local authentication or a connected RADIUS server. + +L2TP over IPsec +=============== + +Example for configuring a simple L2TP over IPsec VPN for remote access (works +with native Windows and Mac VPN clients): + +.. code-block:: none + + set vpn ipsec ipsec-interfaces interface eth0 + set vpn ipsec nat-traversal enable + set vpn ipsec nat-networks allowed-network 0.0.0.0/0 + + 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 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 + set vpn l2tp remote-access authentication local-users username test password 'test' + +In the example above an external IP of 192.0.2.2 is assumed. + +If a local firewall policy is in place on your external interface you will need +to allow the ports below: + +* UDP port 500 (IKE) +* IP protocol number 50 (ESP) +* UDP port 1701 for IPsec + +As well as the below to allow NAT-traversal (when NAT is detected by the +VPN client, ESP is encapsulated in UDP for NAT-traversal): + +* UDP port 4500 (NAT-T) + +Example: + +.. code-block:: none + + set firewall name OUTSIDE-LOCAL rule 40 action 'accept' + set firewall name OUTSIDE-LOCAL rule 40 protocol 'esp' + set firewall name OUTSIDE-LOCAL rule 41 action 'accept' + set firewall name OUTSIDE-LOCAL rule 41 destination port '500' + set firewall name OUTSIDE-LOCAL rule 41 protocol 'udp' + set firewall name OUTSIDE-LOCAL rule 42 action 'accept' + set firewall name OUTSIDE-LOCAL rule 42 destination port '4500' + set firewall name OUTSIDE-LOCAL rule 42 protocol 'udp' + set firewall name OUTSIDE-LOCAL rule 43 action 'accept' + set firewall name OUTSIDE-LOCAL rule 43 destination port '1701' + set firewall name OUTSIDE-LOCAL rule 43 ipsec 'match-ipsec' + set firewall name OUTSIDE-LOCAL rule 43 protocol 'udp' + +To allow VPN-clients access via your external address, a NAT rule is required: + + +.. code-block:: none + + set nat source rule 110 outbound-interface 'eth0' + set nat source rule 110 source address '192.168.255.0/24' + set nat source rule 110 translation address masquerade + + +VPN-clients will request configuration parameters, optionally you can DNS +parameter to the client. + +.. code-block:: none + + set vpn l2tp remote-access name-server '198.51.100.8' + set vpn l2tp remote-access name-server '198.51.100.4' + +Established sessions can be viewed using the **show vpn remote-access** +operational command, or **show l2tp-server sessions** + +.. code-block:: none + + vyos@vyos:~$ show vpn remote-access + ifname | username | calling-sid | ip | rate-limit | type | comp | state | uptime + --------+----------+--------------+---------------+------------+------+------+--------+---------- + ppp0 | vyos | 192.168.0.36 | 192.168.255.1 | | l2tp | | active | 00:06:13 + + +LNS (L2TP Network Server) +========================= + +LNS are often used to connect to a LAC (L2TP Access Concentrator). + +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 lns shared-secret 'secret' + set vpn l2tp remote-access ccp-disable + set vpn l2tp remote-access authentication mode local + set vpn l2tp remote-access authentication local-users username test password 'test' + +The example above uses 192.0.2.2 as external IP address. A LAC normally requires +an authentication password, which is set in the example configuration to +``lns shared-secret 'secret'``. This setup requires the Compression Control +Protocol (CCP) being disabled, the command ``set vpn l2tp remote-access +ccp-disable`` accomplishes that. + + +Bandwidth Shaping +================= + +Bandwidth rate limits can be set for local users or via RADIUS based attributes. + +Bandwidth Shaping for local users +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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 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 + set vpn l2tp remote-access authentication local-users username test rate-limit upload 10240 + + vyos@vyos:~$ show vpn remote-access + ifname | username | calling-sid | ip | rate-limit | type | comp | state | uptime + -------+----------+--------------+---------------+-------------+------+------+--------+----------- + ppp0 | test | 192.168.0.36 | 192.168.255.2 | 20480/10240 | l2tp | | active | 00:06:30 + +RADIUS authentication +====================== + +To enable RADIUS based authentication, the authentication mode needs to be +changed within the configuration. Previous settings like the local users, still +exists within the configuration, however they are not used if the mode has been +changed from local to radius. Once changed back to local, it will use all local +accounts again. + +.. code-block:: none + + set vpn l2tp remote-access authentication mode <local|radius> + +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. + +.. code-block:: none + + set vpn l2tp remote-access authentication radius server 10.0.0.1 key 'foo' + set vpn l2tp remote-access authentication radius server 10.0.0.2 key 'foo' + +.. note:: Some RADIUS_ severs use an access control list which allows or denies + queries, make sure to add your VyOS router to the allowed client list. + +RADIUS source address +^^^^^^^^^^^^^^^^^^^^^ + +If you are using OSPF as IGP always the closets interface connected to the +RADIUS server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests +to a single source IP e.g. the loopback interface. + +.. code-block:: none + + set vpn l2tp remote-access authentication radius source-address 10.0.0.3 + +Above command will use `10.0.0.3` as source IPv4 address for all RADIUS queries +on this NAS. + +.. note:: The ``source-address`` must be configured on one of VyOS interface. + Best proctice would be a loopback or dummy interface. + +RADIUS bandwidth shaping attribute +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To enable bandwidth shaping via RADIUS, the option rate-limit needs to be +enabled. + +.. code-block:: none + + set vpn l2tp remote-access authentication radius rate-limit enable + +The default RADIUS attribute for rate limiting is ``Filter-Id``, but you may +also redefine it. + +.. code-block:: none + + set vpn l2tp remote-access authentication radius rate-limit attribute Download-Speed + +.. note:: If you set a custom RADIUS attribute you must define it on both + dictionaries at RADIUS server and client, which is the vyos router in our + example. + +The RADIUS dictionaries in VyOS are located at ``/usr/share/accel-ppp/radius/`` + +RADIUS advanced features +^^^^^^^^^^^^^^^^^^^^^^^^ + +Received RADIUS attributes have a higher priority than parameters defined within +the CLI configuration, refer to the explanation below. + +Allocation clients ip addresses by RADIUS +***************************************** + +If the RADIUS server sends the attribute ``Framed-IP-Address`` then this IP +address will be allocated to the client and the option ip-pool within the CLI +config is being ignored. + +Renaming clients interfaces by RADIUS +************************************* + +If the RADIUS server uses the attribute ``NAS-Port-Id``, ppp tunnels will be +renamed. + +.. note:: The value of the attribute ``NAS-Port-Id`` must be less than 16 + characters, otherwise the interface won't be renamed. + + +.. _`Google Public DNS`: https://developers.google.com/speed/public-dns +.. _Quad9: https://quad9.net +.. _CloudFlare: https://blog.cloudflare.com/announcing-1111 +.. _OpenNIC: https://www.opennic.org/ +.. _RADIUS: https://en.wikipedia.org/wiki/RADIUS +.. _FreeRADIUS: https://freeradius.org +.. _`Network Policy Server`: https://en.wikipedia.org/wiki/Network_Policy_Server +.. _accel-ppp: https://accel-ppp.org/ diff --git a/docs/configuration/vpn/openconnect.rst b/docs/configuration/vpn/openconnect.rst new file mode 100644 index 00000000..feb0bab1 --- /dev/null +++ b/docs/configuration/vpn/openconnect.rst @@ -0,0 +1,95 @@ +.. _vpn-openconnect: + +########### +OpenConnect +########### + +OpenConnect-compatible server feature is available from this release. +Openconnect VPN supports SSL connection and offers full network access. SSL VPN +network extension connects the end-user system to the corporate network with +access controls based only on network layer information, such as destination IP +address and port number. So, it provides safe communication for all types of +device traffic across public networks and private networks, also encrypts the +traffic with SSL protocol. + +The remote user will use the openconnect client to connect to the router and +will receive an IP address from a VPN pool, allowing full access to the network. + +.. note:: All certificates should be stored on VyOS under /config/auth. If + certificates are not stored in the /config directory they will not be + migrated during a software update. + +************* +Configuration +************* + +SSL Certificates +================ + +We need to generate the certificate which authenticates users who attempt to +access the network resource through the SSL VPN tunnels. The following command +will create a self signed certificates and will be stored in the file path +`/config/auth`. + +.. code-block:: none + + openssl req -newkey rsa:4096 -new -nodes -x509 -days 3650 -keyout /config/auth/server.key -out /config/auth/server.crt + openssl req -new -x509 -key /config/auth/server.key -out /config/auth/ca.crt + +We can also create the certificates using Cerbort which is an easy-to-use client +that fetches a certificate from Let's Encrypt an open certificate authority +launched by the EFF, Mozilla, and others and deploys it to a web server. + +.. code-block:: none + + sudo certbot certonly --standalone --preferred-challenges http -d <domain name> + +Server Configuration +==================== + +.. code-block:: none + + set vpn openconnect authentication local-users username <user> password <pass> + set vpn openconnect authentication mode <local|radius> + set vpn opneconnect network-settings client-ip-settings subnet <subnet> + set vpn openconnect network-settings name-server <address> + set vpn openconnect network-settings name-server <address> + set vpn openconnect ssl ca-cert-file <file> + set vpn openconnect ssl cert-file <file> + set vpn openconnect ssl key-file <file> + + +******* +Example +******* + +Use local user name "user4" with password "SecretPassword" +Client IP addresses will be provided from pool 100.64.0.0/24 +The Gateway IP Address must be in one of the router´s interfaces. + +.. code-block:: none + + set vpn openconnect authentication local-users username user4 password 'SecretPassword' + set vpn openconnect authentication mode 'local' + set vpn openconnect network-settings client-ip-settings subnet '100.64.0.0/24' + set vpn openconnect network-settings name-server '10.1.1.1' + set vpn openconnect network-settings name-server '10.1.1.2' + set vpn openconnect ssl ca-cert-file '/config/auth/fullchain.pem' + set vpn openconnect ssl cert-file '/config/auth/cert.pem' + set vpn openconnect ssl key-file '/config/auth/privkey.pem' + + +************ +Verification +************ + +.. code-block:: none + + + vyos@RTR1:~$ show openconnect-server sessions + + interface username ip remote IP RX TX state uptime + ----------- ---------- ------------ ------------- -------- -------- --------- -------- + sslvpn0 user4 100.64.0.105 xx.xxx.49.253 127.3 KB 160.0 KB connected 12m:28s + +.. note:: It is compatible with Cisco (R) AnyConnect (R) clients. diff --git a/docs/configuration/vpn/pptp.rst b/docs/configuration/vpn/pptp.rst new file mode 100644 index 00000000..12364acb --- /dev/null +++ b/docs/configuration/vpn/pptp.rst @@ -0,0 +1,52 @@ +.. _pptp: + +PPTP-Server +----------- + +The Point-to-Point Tunneling Protocol (PPTP_) has been implemented in VyOS only +for backwards compatibility. PPTP has many well known security issues and you +should use one of the many other new VPN implementations. + +As per default and if not otherwise defined, mschap-v2 is being used for +authentication and mppe 128-bit (stateless) for encryption. If no +gateway-address is set within the configuration, the lowest IP out of the /24 +client-ip-pool is being used. For instance, in the example below it would be +192.168.0.1. + +server example +^^^^^^^^^^^^^^ + +.. code-block:: none + + 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 gateway-address '10.100.100.1' + set vpn pptp remote-access outside-address '10.1.1.120' + + +client example (debian 9) +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Install the client software via apt and execute pptpsetup to generate the +configuration. + + +.. code-block:: none + + apt-get install pptp-linux + pptpsetup --create TESTTUNNEL --server 10.1.1.120 --username test --password test --encrypt + pon TESTTUNNEL + +The command pon TESTUNNEL establishes the PPTP tunnel to the remote system. + + +All tunnel sessions can be checked via: + +.. code-block:: none + + run sh pptp-server sessions + ifname | username | calling-sid | ip | type | comp | state | uptime + --------+----------+-------------+--------------+------+------+--------+---------- + ppp0 | test | 10.1.1.99 | 192.168.0.10 | pptp | mppe | active | 00:00:58 diff --git a/docs/configuration/vpn/rsa-keys.rst b/docs/configuration/vpn/rsa-keys.rst new file mode 100644 index 00000000..7912cffe --- /dev/null +++ b/docs/configuration/vpn/rsa-keys.rst @@ -0,0 +1,88 @@ + +######## +RSA-Keys +######## +RSA can be used for services such as key exchanges and for encryption purposes. +To make IPSec work with dynamic address on one/both sides, we will have to use +RSA keys for authentication. They are very fast and easy to setup. + +First, on both routers run the operational command “generate vpn rsa-key +bits 2048”. You may choose different length than 2048 of course. + +.. code-block:: none + + vyos@left# run generate vpn rsa-key bits 2048 + Generating rsa-key to /config/ipsec.d/rsa-keys/localhost.key + + Your new local RSA key has been generated + The public portion of the key is: + + 0sAQO2335[long string here] + +Please note down this public key, as you have to add this RSA key in the opposite router. + +.. code-block:: none + + set vpn rsa-keys rsa-key-name LEFT rsa-key KEYGOESHERE + +Now you are ready to setup IPsec. The key points: + +1. Since both routers do not know their effective public addresses, we set the local-address of the peer to "any". +2. On the initiator, we set the peer address to its public address, but on the responder we only set the id. +3. On the initiator, we need to set the remote-id option so that it can identify IKE traffic from the responder correctly. +4. On the responder, we need to set the local id so that initiator can know who's talking to it for the point #3 to work. +5. Don't forget to enable NAT traversal on both sides, "set vpn ipsec nat-traversal enable". + +LEFT SIDE: + +.. code-block:: none + + set vpn rsa-keys rsa-key-name RIGHT rsa-key <PUBLIC KEY FROM THE RIGHT> + + set vpn ipsec ipsec-interfaces interface eth0 + set vpn ipsec nat-traversal 'enable' + + set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128 + set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1 + + set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2 + set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128 + set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1 + + set vpn ipsec site-to-site peer 192.0.2.60 authentication mode rsa + set vpn ipsec site-to-site peer 192.0.2.60 authentication id @LEFT + set vpn ipsec site-to-site peer 192.0.2.60 authentication rsa-key-name RIGHT + set vpn ipsec site-to-site peer 192.0.2.60 authentication remote-id RIGHT + set vpn ipsec site-to-site peer 192.0.2.60 default-esp-group MyESPGroup + set vpn ipsec site-to-site peer 192.0.2.60 ike-group MyIKEGroup + set vpn ipsec site-to-site peer 192.0.2.60 local-address any + set vpn ipsec site-to-site peer 192.0.2.60 connection-type initiate + set vpn ipsec site-to-site peer 192.0.2.60 tunnel 1 local prefix 192.168.99.1/32 + set vpn ipsec site-to-site peer 192.0.2.60 tunnel 1 remote prefix 192.168.99.2/32 + +RIGHT SIDE: + +.. code-block:: none + + set vpn rsa-keys rsa-key-name LEFT rsa-key <PUBLIC KEY FROM THE LEFT> + + set vpn ipsec ipsec-interfaces interface eth0 + set vpn ipsec nat-traversal 'enable' + + set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128 + set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1 + + set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2 + set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128 + set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1 + + set vpn ipsec site-to-site peer @LEFT authentication id @RIGHT + set vpn ipsec site-to-site peer @LEFT authentication mode rsa + set vpn ipsec site-to-site peer @LEFT authentication rsa-key-name LEFT + set vpn ipsec site-to-site peer @LEFT connection-type respond + set vpn ipsec site-to-site peer @LEFT default-esp-group MyESPGroup + set vpn ipsec site-to-site peer @LEFT ike-group MyIKEGroup + set vpn ipsec site-to-site peer @LEFT local-address any + set vpn ipsec site-to-site peer @LEFT tunnel 1 local prefix 192.168.99.2/32 + set vpn ipsec site-to-site peer @LEFT tunnel 1 remote prefix 192.168.99.1/32 + diff --git a/docs/configuration/vpn/site2site_ipsec.rst b/docs/configuration/vpn/site2site_ipsec.rst new file mode 100644 index 00000000..e81c5c3b --- /dev/null +++ b/docs/configuration/vpn/site2site_ipsec.rst @@ -0,0 +1,346 @@ +.. _size2site_ipsec: + +Site-to-Site +============ + +Site-to-site mode provides a way to add remote peers, which could be configured +to exchange encrypted information between them and VyOS itself or +connected/routed networks. + +To configure site-to-site connection you need to add peers with the +``set vpn ipsec site-to-site`` command. + +You can identify a remote peer with: + +* IPv4 or IPv6 address. This mode is easiest for configuration and mostly used + when a peer has a public static IP address; +* Hostname. This mode is similar to IP address, only you define DNS name instead + of an IP. 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; +* Remote ID of the peer. In this mode, there is no predefined remote address + nor DNS name of the peer. This mode is useful when a peer doesn't have a + publicly available IP address (NAT between it and VyOS), or IP address could + be changed. + +Each site-to-site peer has the next options: + +* ``authentication`` - configure authentication between VyOS and a remote peer. + Suboptions: + + * ``id`` - ID for the local VyOS router. If defined, during the authentication + it will be send to remote peer; + + * ``mode`` - mode for authentication between VyOS and remote peer: + + * ``pre-shared-secret`` - use predefined shared secret phrase, must be the + same for local and remote side; + + * ``rsa`` - use simple shared RSA key. The key must be defined in the + ``set vpn rsa-keys`` section; + + * ``x509`` - use certificates infrastructure for authentication. + + * ``pre-shared-secret`` - predefined shared secret. Used if configured + ``mode pre-shared-secret``; + + * ``remote-id`` - define an ID for remote peer, instead of using peer name or + address. Useful in case if the remote peer is behind NAT or if ``mode x509`` + is used; + + * ``rsa-key-name`` - shared RSA key for authentication. The key must be defined + in the ``set vpn rsa-keys`` section; + + * ``use-x509-id`` - use local ID from x509 certificate. Cannot be used when + ``id`` is defined; + + * ``x509`` - options for x509 authentication mode: + + * ``ca-cert-file`` - CA certificate file. Using for authenticating + remote peer; + + * ``cert-file`` - certificate file, which will be used for authenticating + local router on remote peer; + + * ``crl-file`` - file with the Certificate Revocation List. Using to check if + a certificate for the remote peer is valid or revoked; + + * ``key`` - a private key, which will be used for authenticating local router + on remote peer: + + * ``file`` - path to the key file; + + * ``password`` - passphrase private key, if needed. + +* ``connection-type`` - how to handle this connection process. Possible + variants: + + * ``initiate`` - do initial connection to remote peer immediately after + configuring and after boot. In this mode the connection will not be restarted + in case of disconnection, therefore should be used only together with DPD or + another session tracking methods; + + * ``respond`` - do not try to initiate a connection to a remote peer. In this + mode, the IPSec session will be established only after initiation from a + remote peer. Could be useful when there is no direct connectivity to the + peer due to firewall or NAT in the middle of the local and remote side. + +* ``default-esp-group`` - ESP group to use by default for traffic encryption. + Might be overwritten by individual settings for tunnel or VTI interface + binding; + +* ``description`` - description for this peer; + +* ``dhcp-interface`` - use an IP address, received from DHCP for IPSec + connection with this peer, instead of ``local-address``; + +* ``force-encapsulation`` - force encapsulation of ESP into UDP datagrams. + Useful in case if between local and remote side is firewall or NAT, which not + allows passing plain ESP packets between them; + +* ``ike-group`` - IKE group to use for key exchanges; + +* ``ikev2-reauth`` - reauthenticate remote peer during the rekeying process. + Can be used only with IKEv2: + + * ``yes`` - create a new IKE_SA from the scratch and try to recreate all + IPsec SAs; + + * ``no`` - rekey without uninstalling the IPsec SAs; + + * ``inherit`` - use default behavior for the used IKE group. + +* ``local-address`` - local IP address for IPSec connection with this peer. + If defined ``any``, then an IP address which configured on interface with + default route will be used; + +* ``tunnel`` - define criteria for traffic to be matched for encrypting and send + it to a peer: + + * ``disable`` - disable this tunnel; + + * ``esp-group`` - define ESP group for encrypt traffic, defined by this tunnel; + + * ``local`` - define a local source for match traffic, which should be + encrypted and send to this peer: + + * ``port`` - define port. Have effect only when used together with ``prefix``; + + * ``prefix`` - IP network at local side. + + * ``protocol`` - define the protocol for match traffic, which should be + encrypted and send to this peer; + + * ``remote`` - define the remote destination for match traffic, which should be + encrypted and send to this peer: + + * ``port`` - define port. Have effect only when used together with ``prefix``; + + * ``prefix`` - IP network at remote side. + +* ``vti`` - use a VTI interface for traffic encryption. Any traffic, which will + be send to VTI interface will be encrypted and send to this peer. Using VTI + makes IPSec configuration much flexible and easier in complex situation, and + allows to dynamically add/delete remote networks, reachable via a peer, as in + this mode router don't need to create additional SA/policy for each remote + network: + + * ``bind`` - select a VTI interface to bind to this peer; + + * ``esp-group`` - define ESP group for encrypt traffic, passed this VTI + interface. + +Examples: +------------------ + +IKEv1 +^^^^^ + +Example: + +* WAN interface on `eth1` +* left subnet: `192.168.0.0/24` site1, server side (i.e. locality, actually + there is no client or server roles) +* left local_ip: `198.51.100.3` # server side WAN IP +* right subnet: `10.0.0.0/24` site2,remote office side +* right local_ip: `203.0.113.2` # remote office side WAN IP + +.. code-block:: none + + # server config + set vpn ipsec esp-group office-srv-esp compression 'disable' + set vpn ipsec esp-group office-srv-esp lifetime '1800' + set vpn ipsec esp-group office-srv-esp mode 'tunnel' + set vpn ipsec esp-group office-srv-esp pfs 'enable' + set vpn ipsec esp-group office-srv-esp proposal 1 encryption 'aes256' + set vpn ipsec esp-group office-srv-esp proposal 1 hash 'sha1' + set vpn ipsec ike-group office-srv-ike ikev2-reauth 'no' + set vpn ipsec ike-group office-srv-ike key-exchange 'ikev1' + set vpn ipsec ike-group office-srv-ike lifetime '3600' + set vpn ipsec ike-group office-srv-ike proposal 1 encryption 'aes256' + set vpn ipsec ike-group office-srv-ike proposal 1 hash 'sha1' + set vpn ipsec ipsec-interfaces interface 'eth1' + set vpn ipsec site-to-site peer 203.0.113.2 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 203.0.113.2 authentication pre-shared-secret 'SomePreSharedKey' + set vpn ipsec site-to-site peer 203.0.113.2 ike-group 'office-srv-ike' + set vpn ipsec site-to-site peer 203.0.113.2 local-address '198.51.100.3' + set vpn ipsec site-to-site peer 203.0.113.2 tunnel 0 allow-nat-networks 'disable' + set vpn ipsec site-to-site peer 203.0.113.2 tunnel 0 allow-public-networks 'disable' + set vpn ipsec site-to-site peer 203.0.113.2 tunnel 0 esp-group 'office-srv-esp' + set vpn ipsec site-to-site peer 203.0.113.2 tunnel 0 local prefix '192.168.0.0/24' + set vpn ipsec site-to-site peer 203.0.113.2 tunnel 0 remote prefix '10.0.0.0/21' + + # remote office config + set vpn ipsec esp-group office-srv-esp compression 'disable' + set vpn ipsec esp-group office-srv-esp lifetime '1800' + set vpn ipsec esp-group office-srv-esp mode 'tunnel' + set vpn ipsec esp-group office-srv-esp pfs 'enable' + set vpn ipsec esp-group office-srv-esp proposal 1 encryption 'aes256' + set vpn ipsec esp-group office-srv-esp proposal 1 hash 'sha1' + set vpn ipsec ike-group office-srv-ike ikev2-reauth 'no' + set vpn ipsec ike-group office-srv-ike key-exchange 'ikev1' + set vpn ipsec ike-group office-srv-ike lifetime '3600' + set vpn ipsec ike-group office-srv-ike proposal 1 encryption 'aes256' + set vpn ipsec ike-group office-srv-ike proposal 1 hash 'sha1' + set vpn ipsec ipsec-interfaces interface 'eth1' + set vpn ipsec site-to-site peer 198.51.100.3 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 198.51.100.3 authentication pre-shared-secret 'SomePreSharedKey' + set vpn ipsec site-to-site peer 198.51.100.3 ike-group 'office-srv-ike' + set vpn ipsec site-to-site peer 198.51.100.3 local-address '203.0.113.2' + set vpn ipsec site-to-site peer 198.51.100.3 tunnel 0 allow-nat-networks 'disable' + set vpn ipsec site-to-site peer 198.51.100.3 tunnel 0 allow-public-networks 'disable' + set vpn ipsec site-to-site peer 198.51.100.3 tunnel 0 esp-group 'office-srv-esp' + set vpn ipsec site-to-site peer 198.51.100.3 tunnel 0 local prefix '10.0.0.0/21' + set vpn ipsec site-to-site peer 198.51.100.3 tunnel 0 remote prefix '192.168.0.0/24' + +Show status of new setup: + +.. code-block:: none + + vyos@srv-gw0:~$ show vpn ike sa + Peer ID / IP Local ID / IP + ------------ ------------- + 203.0.113.2 198.51.100.3 + State Encrypt Hash D-H Grp NAT-T A-Time L-Time + ----- ------- ---- ------- ----- ------ ------ + up aes256 sha1 5 no 734 3600 + + vyos@srv-gw0:~$ show vpn ipsec sa + Peer ID / IP Local ID / IP + ------------ ------------- + 203.0.113.2 198.51.100.3 + Tunnel State Bytes Out/In Encrypt Hash NAT-T A-Time L-Time Proto + ------ ----- ------------- ------- ---- ----- ------ ------ ----- + 0 up 7.5M/230.6K aes256 sha1 no 567 1800 all + +If there is SNAT rules on eth1, need to add exclude rule + +.. code-block:: none + + # server side + set nat source rule 10 destination address '10.0.0.0/24' + set nat source rule 10 'exclude' + set nat source rule 10 outbound-interface 'eth1' + set nat source rule 10 source address '192.168.0.0/24' + + # remote office side + set nat source rule 10 destination address '192.168.0.0/24' + set nat source rule 10 'exclude' + set nat source rule 10 outbound-interface 'eth1' + set nat source rule 10 source address '10.0.0.0/24' + +To allow traffic to pass through to clients, you need to add the following +rules. (if you used the default configuration at the top of this page) + +.. code-block:: none + + # server side + set firewall name OUTSIDE-LOCAL rule 32 action 'accept' + set firewall name OUTSIDE-LOCAL rule 32 source address '10.0.0.0/24' + + # remote office side + set firewall name OUTSIDE-LOCAL rule 32 action 'accept' + set firewall name OUTSIDE-LOCAL rule 32 source address '192.168.0.0/24' + +IKEv2 +^^^^^ + +Imagine the following topology + +.. figure:: /_static/images/vpn_s2s_ikev2.png + :scale: 50 % + :alt: IPSec IKEv2 site2site VPN + + IPSec IKEv2 site2site VPN (source ./draw.io/vpn_s2s_ikev2.drawio) + + +.. note:: Don't get confused about the used /31 tunnel subnet. :rfc:`3021` + gives you additional information for using /31 subnets on point-to-point + links. + +**left** + +.. code-block:: none + + set interfaces vti vti10 address '10.0.0.2/31' + + set vpn ipsec esp-group ESP_DEFAULT compression 'disable' + 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 '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 ikev2-reauth 'no' + 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 mobike 'disable' + 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 ipsec-interfaces interface 'eth0.201' + set vpn ipsec site-to-site peer 172.18.202.10 authentication id '172.18.201.10' + set vpn ipsec site-to-site peer 172.18.202.10 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 172.18.202.10 authentication pre-shared-secret 'secretkey' + set vpn ipsec site-to-site peer 172.18.202.10 authentication remote-id '172.18.202.10' + set vpn ipsec site-to-site peer 172.18.202.10 connection-type 'initiate' + set vpn ipsec site-to-site peer 172.18.202.10 ike-group 'IKEv2_DEFAULT' + set vpn ipsec site-to-site peer 172.18.202.10 ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer 172.18.202.10 local-address '172.18.201.10' + set vpn ipsec site-to-site peer 172.18.202.10 vti bind 'vti10' + set vpn ipsec site-to-site peer 172.18.202.10 vti esp-group 'ESP_DEFAULT' + +**right** + +.. code-block:: none + + set interfaces vti vti10 address '10.0.0.3/31' + + set vpn ipsec esp-group ESP_DEFAULT compression 'disable' + 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 '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 ikev2-reauth 'no' + 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 mobike 'disable' + 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 ipsec-interfaces interface 'eth0.202' + set vpn ipsec site-to-site peer 172.18.201.10 authentication id '172.18.202.10' + set vpn ipsec site-to-site peer 172.18.201.10 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 172.18.201.10 authentication pre-shared-secret 'secretkey' + set vpn ipsec site-to-site peer 172.18.201.10 authentication remote-id '172.18.201.10' + set vpn ipsec site-to-site peer 172.18.201.10 connection-type 'initiate' + set vpn ipsec site-to-site peer 172.18.201.10 ike-group 'IKEv2_DEFAULT' + set vpn ipsec site-to-site peer 172.18.201.10 ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer 172.18.201.10 local-address '172.18.202.10' + set vpn ipsec site-to-site peer 172.18.201.10 vti bind 'vti10' + set vpn ipsec site-to-site peer 172.18.201.10 vti esp-group 'ESP_DEFAULT' diff --git a/docs/configuration/vpn/sstp.rst b/docs/configuration/vpn/sstp.rst new file mode 100644 index 00000000..3600681f --- /dev/null +++ b/docs/configuration/vpn/sstp.rst @@ -0,0 +1,353 @@ +.. _sstp: + +#### +SSTP +#### + +:abbr:`SSTP (Secure Socket Tunneling Protocol)` is a form of :abbr:`VPN +(Virtual Private Network)` tunnel that provides a mechanism to transport PPP +traffic through an SSL/TLS channel. SSL/TLS provides transport-level security +with key negotiation, encryption and traffic integrity checking. The use of +SSL/TLS over TCP port 443 allows SSTP to pass through virtually all firewalls +and proxy servers except for authenticated web proxies. + +SSTP is available for Linux, BSD, and Windows. + +VyOS utilizes accel-ppp_ to provide SSTP server functionality. We support both +local and RADIUS authentication. + +As SSTP provides PPP via a SSL/TLS channel the use of either publically signed +certificates as well as a private PKI is required. + +.. note:: All certificates should be stored on VyOS under ``/config/auth``. If + certificates are not stored in the ``/config`` directory they will not be + migrated during a software update. + +Certificates +============ + +Self Signed CA +-------------- + +To generate the CA, the server private key and certificates the following +commands can be used. + +.. code-block:: none + + vyos@vyos:~$ mkdir -p /config/user-data/sstp + vyos@vyos:~$ openssl req -newkey rsa:4096 -new -nodes -x509 -days 3650 -keyout /config/user-data/sstp/server.key -out /config/user-data/sstp/server.crt + + Generating a 4096 bit RSA private key + .........................++ + ...............................................................++ + writing new private key to 'server.key' + [...] + Country Name (2 letter code) [AU]: + State or Province Name (full name) [Some-State]: + Locality Name (eg, city) []: + Organization Name (eg, company) [Internet Widgits Pty Ltd]: + Organizational Unit Name (eg, section) []: + Common Name (e.g. server FQDN or YOUR name) []: + Email Address []: + + vyos@vyos:~$ openssl req -new -x509 -key /config/user-data/sstp/server.key -out /config/user-data/sstp/ca.crt + [...] + Country Name (2 letter code) [AU]: + State or Province Name (full name) [Some-State]: + Locality Name (eg, city) []: + Organization Name (eg, company) [Internet Widgits Pty Ltd]: + Organizational Unit Name (eg, section) []: + Common Name (e.g. server FQDN or YOUR name) []: + Email Address []: + + +Configuration +============= + +.. cfgcmd:: set vpn sstp authentication local-users username <user> password + <pass> + + Create `<user>` for local authentication on this system. The users password + will be set to `<pass>`. + +.. cfgcmd:: set vpn sstp authentication local-users username <user> disable + + Disable `<user>` account. + +.. cfgcmd:: set vpn sstp authentication local-users username <user> static-ip + <address> + + Assign static IP address to `<user>` account. + +.. cfgcmd:: set vpn sstp authentication local-users username <user> rate-limit + download <bandwidth> + + Download bandwidth limit in kbit/s for `<user>`. + +.. cfgcmd:: set vpn sstp authentication local-users username <user> rate-limit + upload <bandwidth> + + Upload bandwidth limit in kbit/s for `<user>`. + +.. cfgcmd:: set vpn sstp authentication protocols + <pap | chap | mschap | mschap-v2> + + Require the peer to authenticate itself using one of the following protocols: + pap, chap, mschap, mschap-v2. + +.. cfgcmd:: set vpn sstp authentication mode <local | radius> + + Set authentication backend. The configured authentication backend is used + for all queries. + + * **radius**: All authentication queries are handled by a configured RADIUS + server. + * **local**: All authentication queries are handled locally. + + +.. cfgcmd:: set vpn sstp gateway-address <gateway> + + Specifies single `<gateway>` IP address to be used as local address of PPP + interfaces. + + +.. cfgcmd:: set vpn sstp client-ip-pool subnet <subnet> + + Use `<subnet>` as the IP pool for all connecting clients. + + +.. cfgcmd:: set vpn sstp client-ipv6-pool prefix <address> mask <number-of-bits> + + Use this comand to set the IPv6 address pool from which an SSTP client + will get an IPv6 prefix of your defined length (mask) to terminate the + SSTP endpoint at their side. The mask length can be set from 48 to 128 + bit long, the default value is 64. + + +.. cfgcmd:: set vpn sstp client-ipv6-pool delegate <address> delegation-prefix + <number-of-bits> + + Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on + SSTP. You will have to set your IPv6 pool and the length of the + delegation prefix. From the defined IPv6 pool you will be handing out + networks of the defined length (delegation-prefix). The length of the + delegation prefix can be set from 32 to 64 bit long. + + +.. cfgcmd:: set vpn sstp name-server <address> + + Connected client should use `<address>` as their DNS server. This + command accepts both IPv4 and IPv6 addresses. Up to two nameservers + can be configured for IPv4, up to three for IPv6. + +Maximum number of IPv4 nameservers + +SSL Certificates +---------------- + +.. cfgcmd:: set vpn sstp ssl ca-cert-file <file> + + Path to `<file>` pointing to the certificate authority certificate. + +.. cfgcmd:: set vpn sstp ssl cert-file <file> + + Path to `<file>` pointing to the servers certificate (public portion). + +.. cfgcmd:: set vpn sstp ssl key-file <file> + + Path to `<file>` pointing to the servers certificate (private portion). + +PPP Settings +------------ + +.. cfgcmd:: set vpn sstp ppp-options lcp-echo-failure <number> + + Defines the maximum `<number>` of unanswered echo requests. Upon reaching the + value `<number>`, the session will be reset. + +.. cfgcmd:: set vpn sstp ppp-options lcp-echo-interval <interval> + + If this option is specified and is greater than 0, then the PPP module will + send LCP pings of the echo request every `<interval>` seconds. + +.. cfgcmd:: set vpn sstp ppp-options lcp-echo-timeout + + Specifies timeout in seconds to wait for any peer activity. If this option + specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" + is not used. + +.. cfgcmd:: set vpn sstp ppp-options mppe <require | prefer | deny> + + Specifies :abbr:`MPPE (Microsoft Point-to-Point Encryption)` negotioation + preference. + + * **require** - ask client for mppe, if it rejects drop connection + * **prefer** - ask client for mppe, if it rejects don't fail + * **deny** - deny mppe + + Default behavior - don't ask client for mppe, but allow it if client wants. + Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy + attribute. + + +RADIUS +------ + +Server +^^^^^^ + +.. cfgcmd:: set vpn sstp authentication radius server <server> port <port> + + Configure RADIUS `<server>` and its required port for authentication requests. + +.. cfgcmd:: set vpn sstp authentication radius server <server> key <secret> + + Configure RADIUS `<server>` and its required shared `<secret>` for + communicating with the RADIUS server. + +.. cfgcmd:: set vpn sstp authentication radius server <server> fail-time <time> + + Mark RADIUS server as offline for this given `<time>` in seconds. + +.. cfgcmd:: set vpn sstp authentication radius server <server> disable + + Temporary disable this RADIUS server. + +Options +^^^^^^^ + +.. cfgcmd:: set vpn sstp authentication radius acct-timeout <timeout> + + Timeout to wait reply for Interim-Update packets. (default 3 seconds) + +.. cfgcmd:: set vpn sstp authentication radius dynamic-author server <address> + + Specifies IP address for Dynamic Authorization Extension server (DM/CoA) + +.. cfgcmd:: set vpn sstp authentication radius dynamic-author port <port> + + Port for Dynamic Authorization Extension server (DM/CoA) + +.. cfgcmd:: set vpn sstp authentication radius dynamic-author key <secret> + + Secret for Dynamic Authorization Extension server (DM/CoA) + +.. cfgcmd:: set vpn sstp authentication radius max-try <number> + + Maximum number of tries to send Access-Request/Accounting-Request queries + +.. cfgcmd:: set vpn sstp authentication radius timeout <timeout> + + Timeout to wait response from server (seconds) + +.. cfgcmd:: set vpn sstp authentication radius nas-identifier <identifier> + + Value to send to RADIUS server in NAS-Identifier attribute and to be matched + in DM/CoA requests. + +.. cfgcmd:: set vpn sstp authentication radius nas-ip-address <address> + + Value to send to RADIUS server in NAS-IP-Address attribute and to be matched + in DM/CoA requests. Also DM/CoA server will bind to that address. + +.. cfgcmd:: set vpn sstp authentication radius source-address <address> + + Source IPv4 address used in all RADIUS server queires. + +.. cfgcmd:: set vpn sstp authentication radius rate-limit attribute <attribute> + + Specifies which RADIUS server attribute contains the rate limit information. + The default attribute is `Filter-Id`. + +.. cfgcmd:: set vpn sstp authentication radius rate-limit enable + + Enables bandwidth shaping via RADIUS. + +.. cfgcmd:: set vpn sstp authentication radius rate-limit vendor + + Specifies the vendor dictionary, dictionary needs to be in + /usr/share/accel-ppp/radius. + + +Example +======= + +* Use local user `foo` with password `bar` +* Client IP addresses will be provided from pool `192.0.2.0/25` + +.. code-block:: none + + 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 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 + set vpn sstp ssl cert-file /config/auth/server.crt + set vpn sstp ssl key-file /config/auth/server.key + +Testing SSTP +============ + +Once you have setup your SSTP server there comes the time to do some basic +testing. The Linux client used for testing is called sstpc_. sstpc_ requires a +PPP configuration/peer file. + +The following PPP configuration tests MSCHAP-v2: + +.. code-block:: none + + $ cat /etc/ppp/peers/vyos + usepeerdns + #require-mppe + #require-pap + require-mschap-v2 + noauth + lock + refuse-pap + refuse-eap + refuse-chap + refuse-mschap + #refuse-mschap-v2 + nobsdcomp + nodeflate + debug + + +You can now "dial" the peer with the follwoing command: ``sstpc --log-level 4 +--log-stderr --user vyos --password vyos vpn.example.com -- call vyos``. + +A connection attempt will be shown as: + +.. code-block:: none + + $ sstpc --log-level 4 --log-stderr --user vyos --password vyos vpn.example.com -- call vyos + + Mar 22 13:29:12 sstpc[12344]: Resolved vpn.example.com to 192.0.2.1 + Mar 22 13:29:12 sstpc[12344]: Connected to vpn.example.com + Mar 22 13:29:12 sstpc[12344]: Sending Connect-Request Message + Mar 22 13:29:12 sstpc[12344]: SEND SSTP CRTL PKT(14) + Mar 22 13:29:12 sstpc[12344]: TYPE(1): CONNECT REQUEST, ATTR(1): + Mar 22 13:29:12 sstpc[12344]: ENCAP PROTO(1): 6 + Mar 22 13:29:12 sstpc[12344]: RECV SSTP CRTL PKT(48) + Mar 22 13:29:12 sstpc[12344]: TYPE(2): CONNECT ACK, ATTR(1): + Mar 22 13:29:12 sstpc[12344]: CRYPTO BIND REQ(4): 40 + Mar 22 13:29:12 sstpc[12344]: Started PPP Link Negotiation + Mar 22 13:29:15 sstpc[12344]: Sending Connected Message + Mar 22 13:29:15 sstpc[12344]: SEND SSTP CRTL PKT(112) + Mar 22 13:29:15 sstpc[12344]: TYPE(4): CONNECTED, ATTR(1): + Mar 22 13:29:15 sstpc[12344]: CRYPTO BIND(3): 104 + Mar 22 13:29:15 sstpc[12344]: Connection Established + + $ ip addr show ppp0 + 164: ppp0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1452 qdisc fq_codel state UNKNOWN group default qlen 3 + link/ppp promiscuity 0 + inet 100.64.2.2 peer 100.64.1.1/32 scope global ppp0 + valid_lft forever preferred_lft forever + + + +.. _sstpc: https://github.com/reliablehosting/sstp-client + +.. include:: /_include/common-references.txt diff --git a/docs/configuration/vrf/index.rst b/docs/configuration/vrf/index.rst new file mode 100644 index 00000000..244784de --- /dev/null +++ b/docs/configuration/vrf/index.rst @@ -0,0 +1,322 @@ +.. _vrf: + +### +VRF +### + +:abbr:`VRF (Virtual Routing and Forwarding)` devices combined with ip rules +provides the ability to create virtual routing and forwarding domains (aka +VRFs, VRF-lite to be specific) in the Linux network stack. One use case is the +multi-tenancy problem where each tenant has their own unique routing tables and +in the very least need different default gateways. + +.. warning:: VRFs are an "needs testing" feature. If you think things should be + different then they are implemented and handled right now - please feedback + via a task created in Phabricator_. + + +Configuration +============= + +A VRF device is created with an associated route table. Network interfaces are +then enslaved to a VRF device. + +.. cfgcmd:: set vrf name <name> + + Create new VRF instance with `<name>`. The name is used when placing + individual interfaces into the VRF. + +.. cfgcmd:: set vrf name <name> table <id> + + Configure use routing table `<id>` used by VRF `<name>`. + + .. note:: A routing table ID can not be modified once it is assigned. It can + only be changed by deleting and re-adding the VRF instance. + + +.. cfgcmd:: set vrf bind-to-all + + By default the scope of the port bindings for unbound sockets is limited to + the default VRF. That is, it will not be matched by packets arriving on + interfaces enslaved to a VRF and processes may bind to the same port if + they bind to a VRF. + + TCP & UDP services running in the default VRF context (ie., not bound to any + VRF device) can work across all VRF domains by enabling this option. + +Interfaces +---------- + +When VRFs are used it is not only mandatory to create a VRF but also the VRF +itself needs to be assigned to an interface. + +.. cfgcmd:: set interfaces <dummy | ethernet | bonding | bridge | pppoe> + <interface> vrf <name> + + Assign interface identified by `<interface>` to VRF named `<name>`. + +Routing +------- + +Static +^^^^^^ + +Static routes are manually configured routes, which, in general, cannot be +updated dynamically from information VyOS learns about the network topology from +other routing protocols. However, if a link fails, the router will remove +routes, including static routes, from the :abbr:`RIPB (Routing Information +Base)` that used this interface to reach the next hop. In general, static +routes should only be used for very simple network topologies, or to override +the behavior of a dynamic routing protocol for a small number of routes. The +collection of all routes the router has learned from its configuration or from +its dynamic routing protocols is stored in the RIB. Unicast routes are directly +used to determine the forwarding table used for unicast packet forwarding. + +Static Routes +""""""""""""" + +.. cfgcmd:: set protocols vrf <name> static route <subnet> next-hop <address> + + Configure next-hop `<address>` for an IPv4 static route in the VRF identified + by `<name>`. Multiple static routes can be created. + +.. cfgcmd:: set protocols vrf <name> static route <subnet> next-hop <address> + disable + + Disable IPv4 static route entry in the VRF identified by `<name>` + +.. cfgcmd:: set protocols vrf <name> static route <subnet> next-hop <address> + distance <distance> + + Defines next-hop distance for this route, routes with smaller administrative + distance are elected prior those with a higher distance. + + Range is 1 to 255, default is 1. + +.. cfgcmd:: set protocols vrf <name> static route6 <subnet> next-hop <address> + + Configure next-hop `<address>` for an IPv6 static route in the VRF identified + by `<name>`. Multiple IPv6 static routes can be created. + +.. cfgcmd:: set protocols vrf <name> static route6 <subnet> next-hop <address> + disable + + Disable IPv6 static route entry in the VRF identified by `<name>`. + +.. cfgcmd:: set protocols vrf <name> static route6 <subnet> next-hop <address> + distance <distance> + + Defines next-hop distance for this route, routes with smaller administrative + distance are elected prior those with a higher distance. + + Range is 1 to 255, default is 1. + + .. note:: Routes with a distance of 255 are effectively disabled and not + installed into the kernel. + + +Leaking +""""""" + +.. cfgcmd:: set protocols vrf <name> static route <subnet> next-hop <address> + vrf <default | vrf-name> + + Use this command if you have shared services or routes that should be shared + between multiple VRF instances. This will add an IPv4 route to VRF `<name>` + routing table to reach a `<subnet>` via a next-hop gatewys `<address>` in + a different VRF or leak it into the default VRF. + +.. cfgcmd:: set protocols vrf <name> static route6 <subnet> next-hop <address> + vrf <default | vrf-name> + + Use this command if you have shared services or routes that should be shared + between multiple VRF instances. This will add an IPv6 route to VRF `<name>` + routing table to reach a `<subnet>` via a next-hop gatewys `<address>` in + a different VRF or leak it into the default VRF. + + +Interface Routes +"""""""""""""""" + +.. cfgcmd:: set protocols vrf <name> static route <subnet> + interface <interface> + + Allows you to configure the next-hop interface for an interface-based IPv4 + static route. `<interface>` will be the next-hop interface where trafic is + routed for the given `<subnet>`. + +.. cfgcmd:: set protocols vrf <name> static route <subnet> + interface <interface> disable + + Disables interface-based IPv4 static route. + +.. cfgcmd:: set protocols vrf <name> static route <subnet> + interface <interface> distance <distance> + + Defines next-hop distance for this route, routes with smaller administrative + distance are elected prior those with a higher distance. + + Range is 1 to 255, default is 1. + +.. cfgcmd:: set protocols vrf <name> static route6 <subnet> + interface <interface> + + Allows you to configure the next-hop interface for an interface-based IPv6 + static route. `<interface>` will be the next-hop interface where trafic is + routed for the given `<subnet>`. + +.. cfgcmd:: set protocols vrf <name> static route6 <subnet> + interface <interface> disable + + Disables interface-based IPv6 static route. + +.. cfgcmd:: set protocols vrf <name> static route6 <subnet> + interface <interface> distance <distance> + + Defines next-hop distance for this route, routes with smaller administrative + distance are elected prior those with a higher distance. + + Range is 1 to 255, default is 1. + +Blackhole +""""""""" + +.. cfgcmd:: set protocols vrf <name> static route <subnet> blackhole + + Use this command to configure a "black-hole" route on the router. A + black-hole route is a route for which the system silently discard packets + that are matched. This prevents networks leaking out public interfaces, but + it does not prevent them from being used as a more specific route inside your + network. + +.. cfgcmd:: set protocols vrf <name> static route <subnet> blackhole distance + <distance> + + Defines blackhole distance for this route, routes with smaller administrative + distance are elected prior those with a higher distance. + +.. cfgcmd:: set protocols vrf <name> static route6 <subnet> blackhole + + Use this command to configure a "black-hole" route on the router. A + black-hole route is a route for which the system silently discard packets + that are matched. This prevents networks leaking out public interfaces, but + it does not prevent them from being used as a more specific route inside your + network. + +.. cfgcmd:: set protocols vrf <name> static route6 <subnet> blackhole distance + <distance> + + Defines blackhole distance for this route, routes with smaller administrative + distance are elected prior those with a higher distance. + + +Operation +========= + +It is not sufficient to only configure a VRF but VRFs must be maintained, too. +For VR Fmaintenance the followin operational commands are in place. + +.. opcmd:: show vrf + + List VRFs that have been created + + .. code-block:: none + + vyos@vyos:~$ show vrf + VRF name state mac address flags interfaces + -------- ----- ----------- ----- ---------- + blue up 00:53:12:d8:74:24 noarp,master,up,lower_up dum200,eth0.302 + red up 00:53:de:02:df:aa noarp,master,up,lower_up dum100,eth0.300,bond0.100,peth0 + + .. note:: Command should probably be extended to list also the real + interfaces assigned to this one VRF to get a better overview. + +.. opcmd:: show vrf <name> + + .. code-block:: none + + vyos@vyos:~$ show vrf name blue + VRF name state mac address flags interfaces + -------- ----- ----------- ----- ---------- + blue up 00:53:12:d8:74:24 noarp,master,up,lower_up dum200,eth0.302 + +.. opcmd:: show ip route vrf <name> + + Display IPv4 routing table for VRF identified by `<name>`. + + .. code-block:: none + + vyos@vyos:~$ show ip route vrf blue + Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued route, r - rejected route + + VRF blue: + K 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 00:00:50 + S>* 172.16.0.0/16 [1/0] via 192.0.2.1, dum1, 00:00:02 + C>* 192.0.2.0/24 is directly connected, dum1, 00:00:06 + + +.. opcmd:: show ipv6 route vrf <name> + + Display IPv6 routing table for VRF identified by `<name>`. + + .. code-block:: none + + vyos@vyos:~$ show ipv6 route vrf red + Codes: K - kernel route, C - connected, S - static, R - RIPng, + O - OSPFv3, I - IS-IS, B - BGP, N - NHRP, T - Table, + v - VNC, V - VNC-Direct, A - Babel, D - SHARP, F - PBR, + f - OpenFabric, + > - selected route, * - FIB route, q - queued route, r - rejected route + + VRF red: + K ::/0 [255/8192] unreachable (ICMP unreachable), 00:43:20 + C>* 2001:db8::/64 is directly connected, dum1, 00:02:19 + C>* fe80::/64 is directly connected, dum1, 00:43:19 + K>* ff00::/8 [0/256] is directly connected, dum1, 00:43:19 + + +.. opcmd:: ping <host> vrf <name> + + The ping command is used to test whether a network host is reachable or not. + + Ping uses ICMP protocol's mandatory ECHO_REQUEST datagram to elicit an + ICMP ECHO_RESPONSE from a host or gateway. ECHO_REQUEST datagrams (pings) + will have an IP and ICMP header, followed by "struct timeval" and an + arbitrary number of pad bytes used to fill out the packet. + + When doing fault isolation with ping, your should first run it on the local + host, to verify that the local network interface is up and running. Then, + continue with hosts and gateways further down the road towards your + destination. Round-trip times and packet loss statistics are computed. + + Duplicate packets are not included in the packet loss calculation, although + the round-trip time of these packets is used in calculating the minimum/ + average/maximum round-trip time numbers. + + Ping command can be interrupted at any given time using `<Ctrl>+c`- A brief + statistic is shown afterwards. + + .. code-block:: none + + vyos@vyos:~$ ping 192.0.2.1 vrf red + PING 192.0.2.1 (192.0.2.1) 56(84) bytes of data. + 64 bytes from 192.0.2.1: icmp_seq=1 ttl=64 time=0.070 ms + 64 bytes from 192.0.2.1: icmp_seq=2 ttl=64 time=0.078 ms + ^C + --- 192.0.2.1 ping statistics --- + 2 packets transmitted, 2 received, 0% packet loss, time 4ms + rtt min/avg/max/mdev = 0.070/0.074/0.078/0.004 ms + +.. opcmd:: traceroute vrf <name> [ipv4 | ipv6] <host> + + Displays the route packets take to a network host utilizing VRF instance + identified by `<name>`. When using the IPv4 or IPv6 option, display the route + packets take to the for the given hosts IP address family. This option is + useful when the host specified is a hostname rather than an IP address. + + +.. include:: /_include/common-references.txt diff --git a/docs/configuration/zonepolicy/index.rst b/docs/configuration/zonepolicy/index.rst new file mode 100644 index 00000000..8fe18778 --- /dev/null +++ b/docs/configuration/zonepolicy/index.rst @@ -0,0 +1,71 @@ + +########### +Zone Policy +########### + + +.. toctree:: + :maxdepth: 1 + :includehidden: + +In zone-based policy, interfaces are assigned to zones, and inspection policy is applied to traffic moving between the zones and acted on according to firewall rules. +A Zone is a group of interfaces that have similar functions or features. It establishes the security borders of a network. +A zone defines a boundary where traffic is subjected to policy restrictions as it crosses to another region of a network. + +Key Points: + +* A zone must be configured before an interface is assigned to it and an interface can be assigned to only a single zone. +* All traffic to and from an interface within a zone is permitted. +* All traffic between zones is affected by existing policies +* Traffic cannot flow between zone member interface and any interface that is not a zone member. +* You need 2 separate firewalls to define traffic: one for each direction. + +Example: LAN Network is given SSH access to VyOS box. + +Firewall rules: + +.. code-block:: none + + set firewall name lan-local default-action 'drop' + set firewall name lan-local rule 1 action 'accept' + set firewall name lan-local rule 1 state established 'enable' + set firewall name lan-local rule 1 state related 'enable' + set firewall name lan-local rule 2 action 'drop' + set firewall name lan-local rule 2 state invalid 'enable' + set firewall name lan-local rule 2 log enable + set firewall name lan-local rule 100 action 'accept' + set firewall name lan-local rule 100 destination port '22' + set firewall name lan-local rule 100 log 'enable' + set firewall name lan-local rule 100 protocol 'tcp' + set firewall name local-lan default-action 'drop' + set firewall name local-lan rule 1 action 'accept' + set firewall name local-lan rule 1 state established 'enable' + set firewall name local-lan rule 1 state related 'enable' + set firewall name local-lan rule 2 action 'drop' + set firewall name local-lan rule 2 state invalid 'enable' + set firewall name local-lan rule 2 log enable + set firewall name local-lan rule 100 action 'accept' + set firewall name local-lan rule 100 destination address '192.168.0.0/24' + set firewall name local-lan rule 100 log 'enable' + set firewall name local-lan rule 100 protocol 'tcp' + +Zone-policy Config: + +.. code-block:: none + + set zone-policy zone lan default-action 'drop' + set zone-policy zone lan description 'Local Area Network' + set zone-policy zone lan interface 'eth2' + set zone-policy zone lan from local firewall name 'lan-local' + set zone-policy zone local default-action 'drop' + set zone-policy zone local description 'system-defined zone' + set zone-policy zone local from lan firewall name 'local-lan' + set zone-policy zone local local-zone + +A detailed zone-based policy example is written in the Configuration-Blueprints_ section. + +.. stop_vyoslinter + +.. _Configuration-Blueprints: https://docs.vyos.io/en/latest/configexamples/zone-policy.html + +.. start_vyoslinter |