diff options
Diffstat (limited to 'docs/configuration')
37 files changed, 550 insertions, 311 deletions
diff --git a/docs/configuration/container/index.rst b/docs/configuration/container/index.rst new file mode 100644 index 00000000..c23a6184 --- /dev/null +++ b/docs/configuration/container/index.rst @@ -0,0 +1,223 @@ +:lastproofread: 2022-06-10 + +######### +Container +######### + +The VyOS container implementation is based on `Podman<https://podman.io/>` as +a deamonless container engine. + +************* +Configuration +************* + +.. cfgcmd:: set container name <name> image + + Sets the image name in the hub registry + + .. code-block:: none + + set container name mysql-server image mysql:8.0 + + If a registry is not specified, Docker.io will be used as the container + registry unless an alternative registry is specified using + **set container registry <name>** or the registry is included in the image name + + .. code-block:: none + + set container name mysql-server image quay.io/mysql:8.0 + +.. cfgcmd:: set container name <name> allow-host-networks + + Allow host networking in a container. The network stack of the container is + not isolated from the host and will use the host IP. + + The following commands translate to "--net host" when the container + is created + + .. note:: **allow-host-networks** cannot be used with **network** + +.. cfgcmd:: set container name <name> network <networkname> + + Attaches user-defined network to a container. + Only one network must be specified and must already exist. + +.. cfgcmd:: set container name <name> network <networkname> address <address> + + Optionally set a specific static IPv4 or IPv6 address for the container. + This address must be within the named network prefix. + + .. note:: The first IP in the container network is reserved by the engine and cannot be used + +.. cfgcmd:: set container name <name> description <text> + + Set a container description + +.. cfgcmd:: set container name <name> environment <key> value <value> + + Add custom environment variables. + Multiple environment variables are allowed. + The following commands translate to "-e key=value" when the container + is created. + + .. code-block:: none + + set container name mysql-server environment MYSQL_DATABASE value 'zabbix' + set container name mysql-server environment MYSQL_USER value 'zabbix' + set container name mysql-server environment MYSQL_PASSWORD value 'zabbix_pwd' + set container name mysql-server environment MYSQL_ROOT_PASSWORD value 'root_pwd' + +.. cfgcmd:: set container name <name> port <portname> source <portnumber> +.. cfgcmd:: set container name <name> port <portname> destination <portnumber> +.. cfgcmd:: set container name <name> port <portname> protocol <tcp | udp> + + Publish a port for the container. + + .. code-block:: none + + set container name zabbix-web-nginx-mysql port http source 80 + set container name zabbix-web-nginx-mysql port http destination 8080 + set container name zabbix-web-nginx-mysql port http protocol tcp + +.. cfgcmd:: set container name <name> volume <volumename> source <path> +.. cfgcmd:: set container name <name> volume <volumename> destination <path> + + Mount a volume into the container + + .. code-block:: none + + set container name coredns volume 'corefile' source /config/coredns/Corefile + set container name coredns volume 'corefile' destination /etc/Corefile + +.. cfgcmd:: set container name <name> volume <volumename> mode <ro | rw> + + Volume is either mounted as rw (read-write - default) or ro (read-only) + +.. cfgcmd:: set container name <name> restart [no | on-failure | always] + + Set the restart behavior of the container. + + - **no**: Do not restart containers on exit + - **on-failure**: Restart containers when they exit with a non-zero exit code, retrying indefinitely (default) + - **always**: Restart containers when they exit, regardless of status, retrying indefinitely + +.. cfgcmd:: set container name <name> memory <MB> + + Constrain the memory available to the container. + + Default is 512 MB. Use 0 MB for unlimited memory. + +.. cfgcmd:: set container name <name> device <devicename> source <path> +.. cfgcmd:: set container name <name> device <devicename> destination <path> + + Add a host device to the container. + +.. cfgcmd:: container name <name> cap-add <text> + + Set container capabilities or permissions. + + - **net-admin**: Network operations (interface, firewall, routing tables) + - **net-bind-service**: Bind a socket to privileged ports (port numbers less than 1024) + - **net-raw**: Permission to create raw network sockets + - **setpcap**: Capability sets (from bounded or inherited set) + - **sys-admin**: Administation operations (quotactl, mount, sethostname, setdomainame) + - **sys-time**: Permission to set system clock + +.. cfgcmd:: set container name <name> disable + + Disable a container. + +.. cfgcmd:: set container network <networkname> + + Creates a named container network + +.. cfgcmd:: set container registry <name> + + Adds registry to list of unqualified-search-registries. By default, for any + image that does not include the registry in the image name, Vyos will use + docker.io as the container registry. + + +****************** +Operation Commands +****************** + +.. opcmd:: add container image <containername> + + Pull a new image for container + +.. opcmd:: show container + + Show the list of all active containers. + +.. opcmd:: show container image + + Show the local container images. + +.. opcmd:: show container log <containername> + + Show logs from a given container + +.. opcmd:: show container network + + Show a list available container networks + +.. opcmd:: restart container <containername> + + Restart a given container + +.. opcmd:: update container image <containername> + + Update container image + + + +********************* +Example Configuration +********************* + + For the sake of demonstration, `example #1 in the official documentation + <https://www.zabbix.com/documentation/current/manual/installation/containers>`_ + to the declarative VyOS CLI syntax. + + .. code-block:: none + + set container network zabbix-net prefix 172.20.0.0/16 + set container network zabbix-net description 'Network for Zabbix component containers' + + set container name mysql-server image mysql:8.0 + set container name mysql-server network zabbix-net + + set container name mysql-server environment 'MYSQL_DATABASE' value 'zabbix' + set container name mysql-server environment 'MYSQL_USER' value 'zabbix' + set container name mysql-server environment 'MYSQL_PASSWORD' value 'zabbix_pwd' + set container name mysql-server environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' + + set container name zabbix-java-gateway image zabbix/zabbix-java-gateway:alpine-5.2-latest + set container name zabbix-java-gateway network zabbix-net + + set container name zabbix-server-mysql image zabbix/zabbix-server-mysql:alpine-5.2-latest + set container name zabbix-server-mysql network zabbix-net + + set container name zabbix-server-mysql environment 'DB_SERVER_HOST' value 'mysql-server' + set container name zabbix-server-mysql environment 'MYSQL_DATABASE' value 'zabbix' + set container name zabbix-server-mysql environment 'MYSQL_USER' value 'zabbix' + set container name zabbix-server-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd' + set container name zabbix-server-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' + set container name zabbix-server-mysql environment 'ZBX_JAVAGATEWAY' value 'zabbix-java-gateway' + + set container name zabbix-server-mysql port zabbix source 10051 + set container name zabbix-server-mysql port zabbix destination 10051 + + set container name zabbix-web-nginx-mysql image zabbix/zabbix-web-nginx-mysql:alpine-5.2-latest + set container name zabbix-web-nginx-mysql network zabbix-net + + set container name zabbix-web-nginx-mysql environment 'MYSQL_DATABASE' value 'zabbix' + set container name zabbix-web-nginx-mysql environment 'ZBX_SERVER_HOST' value 'zabbix-server-mysql' + set container name zabbix-web-nginx-mysql environment 'DB_SERVER_HOST' value 'mysql-server' + set container name zabbix-web-nginx-mysql environment 'MYSQL_USER' value 'zabbix' + set container name zabbix-web-nginx-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd' + set container name zabbix-web-nginx-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd' + + set container name zabbix-web-nginx-mysql port http source 80 + set container name zabbix-web-nginx-mysql port http destination 8080 diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst index 8a90e7fa..c2e584a3 100644 --- a/docs/configuration/firewall/index.rst +++ b/docs/configuration/firewall/index.rst @@ -812,10 +812,13 @@ IPv4 .. cfgcmd:: set firewall options interface <interface> adjust-mss - <number-of-bytes> + <mss | clamp-mss-to-pmtu> Use this command to set the maximum segment size for IPv4 transit - packets on a specific interface (500-1460 bytes). + packets on a specific interface (536-65535 bytes). + + Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to + automatically set the proper value. Example ------- @@ -835,10 +838,13 @@ IPv6 ==== .. cfgcmd:: set firewall options interface <interface> adjust-mss6 - <number-of-bytes> + <mss | clamp-mss-to-pmtu> Use this command to set the maximum segment size for IPv6 transit - packets on a specific interface (1280-1492 bytes). + packets on a specific interface (1220-65535 bytes). + + Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to + automatically set the proper value. .. _firewall:ipv6_example: diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst index bce013cb..0fe481da 100644 --- a/docs/configuration/index.rst +++ b/docs/configuration/index.rst @@ -8,6 +8,7 @@ The following structure respresent the cli structure. :maxdepth: 1 :includehidden: + container/index firewall/index highavailability/index interfaces/index @@ -20,4 +21,4 @@ The following structure respresent the cli structure. trafficpolicy/index vpn/index vrf/index - zonepolicy/index
\ No newline at end of file + zonepolicy/index diff --git a/docs/configuration/interfaces/bonding.rst b/docs/configuration/interfaces/bonding.rst index 1e89e5f0..6db8e53b 100644 --- a/docs/configuration/interfaces/bonding.rst +++ b/docs/configuration/interfaces/bonding.rst @@ -271,13 +271,6 @@ Bond options The maximum number of targets that can be specified is 16. The default value is no IP address. -Offloading ----------- - -.. cmdinclude:: /_include/interface-xdp.txt - :var0: bonding - :var1: bond0 - VLAN ==== diff --git a/docs/configuration/interfaces/dummy.rst b/docs/configuration/interfaces/dummy.rst index e521f40d..945361c2 100644 --- a/docs/configuration/interfaces/dummy.rst +++ b/docs/configuration/interfaces/dummy.rst @@ -1,4 +1,4 @@ -:lastproofread: 2022-08-26 +:lastproofread: 2023-01-20 .. _dummy-interface: @@ -68,7 +68,7 @@ Operation .. code-block:: none - vyos@vyos:~$ show interfaces ethernet eth0 + vyos@vyos:~$ show interfaces dummy dum0 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 diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst index 6ed59bc0..071044f5 100644 --- a/docs/configuration/interfaces/ethernet.rst +++ b/docs/configuration/interfaces/ethernet.rst @@ -1,4 +1,4 @@ -:lastproofread: 2022-08-26 +:lastproofread: 2023-01-20 .. _ethernet-interface: @@ -107,11 +107,6 @@ Offloading - 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) ---------------------- @@ -288,29 +283,3 @@ Operation 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 index f81c6ba6..bf8b0920 100644 --- a/docs/configuration/interfaces/geneve.rst +++ b/docs/configuration/interfaces/geneve.rst @@ -1,4 +1,4 @@ -:lastproofread: 2022-08-26 +:lastproofread: 2023-01-20 .. _geneve-interface: diff --git a/docs/configuration/interfaces/l2tpv3.rst b/docs/configuration/interfaces/l2tpv3.rst index b40d7027..b8959816 100644 --- a/docs/configuration/interfaces/l2tpv3.rst +++ b/docs/configuration/interfaces/l2tpv3.rst @@ -1,4 +1,4 @@ -:lastproofread: 2022-08-26 +:lastproofread: 2023-01-30 .. include:: /_include/need_improvement.txt diff --git a/docs/configuration/interfaces/loopback.rst b/docs/configuration/interfaces/loopback.rst index 92edeb56..08be0c8a 100644 --- a/docs/configuration/interfaces/loopback.rst +++ b/docs/configuration/interfaces/loopback.rst @@ -1,4 +1,4 @@ -:lastproofread: 2022-08-26 +:lastproofread: 2023-01-20 .. _loopback-interface: @@ -59,7 +59,7 @@ Operation .. code-block:: none - vyos@vyos:~$ show interfaces ethernet eth0 + vyos@vyos:~$ show interfaces loopback lo 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 diff --git a/docs/configuration/interfaces/macsec.rst b/docs/configuration/interfaces/macsec.rst index 6ee8f1fe..c56241c6 100644 --- a/docs/configuration/interfaces/macsec.rst +++ b/docs/configuration/interfaces/macsec.rst @@ -1,4 +1,4 @@ -:lastproofread: 2022-08-26 +:lastproofread: 2023-01-30 .. _macsec-interface: @@ -29,14 +29,11 @@ Common interface configuration MACsec options ============== -.. cfgcmd:: set interfaces macsec <interface> security cipher [gcm-aes-128] +.. cfgcmd:: set interfaces macsec <interface> security cipher <gcm-aes-128|gcm-aes-256> 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 @@ -56,11 +53,12 @@ individual peers. .. cfgcmd:: set interfaces macsec <interface> security mka cak <key> IEEE 802.1X/MACsec pre-shared key mode. This allows configuring MACsec with - a pre-shared key using a (CAK,CKN) pair. + a pre-shared key using a :abbr:`CAK (MACsec connectivity association key)` and + :abbr:`CKN (MACsec connectivity association name)` pair. .. cfgcmd:: set interfaces macsec <interface> security mka ckn <key> - CAK Name + :abbr:`CKN (MACsec connectivity association name)` key .. cfgcmd:: set interfaces macsec <interface> security mka priority <priority> @@ -104,7 +102,7 @@ Operation .. opcmd:: show interfaces macsec - List all MACsec interfaces + List all MACsec interfaces. .. code-block:: none diff --git a/docs/configuration/interfaces/pseudo-ethernet.rst b/docs/configuration/interfaces/pseudo-ethernet.rst index 2a67c297..59b3581c 100644 --- a/docs/configuration/interfaces/pseudo-ethernet.rst +++ b/docs/configuration/interfaces/pseudo-ethernet.rst @@ -1,4 +1,4 @@ -:lastproofread: 2022-08-26 +:lastproofread: 2023-01-26 .. _pseudo-ethernet-interface: diff --git a/docs/configuration/interfaces/tunnel.rst b/docs/configuration/interfaces/tunnel.rst index 9ea825ac..bd7a8460 100644 --- a/docs/configuration/interfaces/tunnel.rst +++ b/docs/configuration/interfaces/tunnel.rst @@ -1,4 +1,4 @@ -:lastproofread: 2022-08-26 +:lastproofread: 2023-01-26 .. _tunnel-interface: @@ -18,7 +18,7 @@ a closer look at the protocols and options currently supported by VyOS. Common interface configuration ------------------------------ -.. cmdinclude:: /_include/interface-common-without-dhcp.txt +.. cmdinclude:: /_include/interface-common-without-dhcp1.txt :var0: tunnel :var1: tun0 @@ -114,12 +114,12 @@ over either IPv4 (gre) or IPv6 (ip6gre). Configuration ^^^^^^^^^^^^^ -A basic configuration requires a tunnel source (source-address), a tunnel destination -(remote), 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. +A basic configuration requires a tunnel source (source-address), a tunnel +destination (remote), 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:** @@ -203,22 +203,21 @@ An example: set interfaces tunnel tun0 address 172.16.17.18/24 set interfaces tunnel tun0 parameters ip key 20 -GRE-Bridge -^^^^^^^^^^ +GRETAP +^^^^^^^ -While normal GRE is for layer 3, GRE-Bridge is for layer 2. GRE-Bridge can -encapsulate Ethernet frames, thus it can be bridged with other interfaces to -create datalink layer segments that span multiple remote sites. - -Layer 2 GRE example: +While normal GRE is for layer 3, GRETAP is for layer 2. GRETAP can encapsulate +Ethernet frames, thus it can be bridged with other interfaces to create +datalink layer segments that span multiple remote sites. .. code-block:: none set interfaces bridge br0 member interface eth0 set interfaces bridge br0 member interface tun0 set interfaces tunnel tun0 encapsulation gretap - set interfaces tunnel tun0 source-address 192.0.2.100 - set interfaces tunnel tun0 remote 192.0.2.1 + set interfaces tunnel tun0 source-address 198.51.100.2 + set interfaces tunnel tun0 remote 203.0.113.10 + Troubleshooting ^^^^^^^^^^^^^^^ diff --git a/docs/configuration/interfaces/vxlan.rst b/docs/configuration/interfaces/vxlan.rst index 08916309..cb638736 100644 --- a/docs/configuration/interfaces/vxlan.rst +++ b/docs/configuration/interfaces/vxlan.rst @@ -1,4 +1,4 @@ -:lastproofread: 2022-08-26 +:lastproofread: 2023-01-26 .. _vxlan-interface: diff --git a/docs/configuration/interfaces/wireguard.rst b/docs/configuration/interfaces/wireguard.rst index bd7b4899..036a9063 100644 --- a/docs/configuration/interfaces/wireguard.rst +++ b/docs/configuration/interfaces/wireguard.rst @@ -1,3 +1,5 @@ +:lastproofread: 2023-01-26 + .. _wireguard: ######### @@ -16,19 +18,12 @@ This diagram corresponds with the example site to site configuration below. .. figure:: /_static/images/wireguard_site2site_diagram.jpg -************* -Configuration -************* - - - ******** Keypairs ******** -WireGuard requires the generation of a keypair, which includes a private -key to decrypt incoming traffic, and a public key for peer(s) to encrypt -traffic. +WireGuard requires the generation of a keypair, which includes a private key to +decrypt incoming traffic, and a public key for peer(s) to encrypt traffic. Generate Keypair ================ @@ -71,52 +66,48 @@ own keypairs. 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; however, if you act as a -server and endpoints initiate the connections to your system, you need to -define a port your clients can connect to, otherwise the port is randomly -chosen and may make connection difficult with firewall rules, since the port -may be different each time the system is rebooted. +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; however, if you act like a server and +endpoints initiate the connections to your system, you need to define a port +your clients can connect to, otherwise the port is randomly chosen and may +make connection difficult with firewall rules, since the port may be different +each time the system is rebooted. -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. +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 - commands** +- WireGuard interface itself uses address 10.1.0.1/30 +- We only allow the 192.168.2.0/24 subnet to travel over the tunnel +- Our remote end of the tunnel for peer `to-wg02` is reachable at 192.0.2.1 + port 51820 +- The remote peer `to-wg02` uses XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI= + as its public key portion +- We listen on port 51820 +- We route all traffic for the 192.168.2.0/24 network to interface `wg01` + .. code-block:: none set interfaces wireguard wg01 address '10.1.0.1/30' set interfaces wireguard wg01 description 'VPN-to-wg02' set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.2.0/24' - set interfaces wireguard wg01 peer to-wg02 address '<Site1 Pub IP>' + set interfaces wireguard wg01 peer to-wg02 address '192.0.2.1' set interfaces wireguard wg01 peer to-wg02 port '51820' set interfaces wireguard wg01 peer to-wg02 pubkey 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=' set interfaces wireguard wg01 port '51820' - set protocols static interface-route 192.168.2.0/24 next-hop-interface wg01 -**local side - annotated commands** + set protocols static interface-route 192.168.2.0/24 next-hop-interface wg01 -.. code-block:: none +The last step is to define an interface route for 192.168.2.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. - set interfaces wireguard wg01 address '10.1.0.1/30' # Address of the wg01 tunnel interface. - set interfaces wireguard wg01 description 'VPN-to-wg02' - set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.2.0/24' # Subnets that are allowed to travel over the tunnel - set interfaces wireguard wg01 peer to-wg02 address '<Site2 Pub IP>' # Public IP of the peer - set interfaces wireguard wg01 peer to-wg02 port '58120' # Port of the Peer - set interfaces wireguard wg01 peer to-wg02 pubkey '<pubkey>' # Public Key of the Peer - set interfaces wireguard wg01 port '51820' # Port of own server - set protocols static interface-route 192.168.2.0/24 next-hop-interface wg01 # Static route to remote subnet - -The last step is to define an interface route for 192.168.2.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 decision. For more information please +.. warning:: You can not assign the same allowed-ips statement to multiple + WireGuard peers. This a design decision. For more information please check the `WireGuard mailing list`_. .. cfgcmd:: set interfaces wireguard <interface> private-key <name> @@ -131,38 +122,26 @@ or allows the traffic. The command :opcmd:`show wireguard keypairs pubkey KP01` will then show the public key, which needs to be shared with the peer. - **remote side - commands** .. code-block:: none set interfaces wireguard wg01 address '10.1.0.2/30' set interfaces wireguard wg01 description 'VPN-to-wg01' - set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.1.0/24' - set interfaces wireguard wg01 peer to-wg02 address '<Site1 Pub IP>' - set interfaces wireguard wg01 peer to-wg02 port '51820' - set interfaces wireguard wg01 peer to-wg02 pubkey 'u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk=' + set interfaces wireguard wg01 peer to-wg01 allowed-ips '192.168.1.0/24' + set interfaces wireguard wg01 peer to-wg01 address '192.0.2.2' + set interfaces wireguard wg01 peer to-wg01 port '51820' + set interfaces wireguard wg01 peer to-wg01 public-key 'EKY0dxRrSD98QHjfHOK13mZ5PJ7hnddRZt5woB3szyw=' set interfaces wireguard wg01 port '51820' - set protocols static route 192.168.1.0/24 interface wg01 - -**remote side - annotated commands** -.. code-block:: none - - set interfaces wireguard wg01 address '10.1.0.2/30' # Address of the wg01 tunnel interface. - set interfaces wireguard wg01 description 'VPN-to-wg01' - set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.1.0/24' # Subnets that are allowed to travel over the tunnel - set interfaces wireguard wg01 peer to-wg02 address 'Site1 Pub IP' # Public IP address of the Peer - set interfaces wireguard wg01 peer to-wg02 port '51820' # Port of the Peer - set interfaces wireguard wg01 peer to-wg02 pubkey '<pubkey>' # Public key of the Peer - set interfaces wireguard wg01 port '51820' # Port of own server - set protocols static route 192.168.1.0/24 interface wg01 # Static route to remote subnet + set protocols static route 192.168.1.0/24 interface wg01 ******************* Firewall Exceptions ******************* -For the WireGuard traffic to pass through the WAN interface, you must create a firewall exception. +For the WireGuard traffic to pass through the WAN interface, you must create a +firewall exception. .. code-block:: none @@ -177,13 +156,15 @@ For the WireGuard traffic to pass through the WAN interface, you must create a f set firewall name OUTSIDE_LOCAL rule 20 protocol udp set firewall name OUTSIDE_LOCAL rule 20 source -You should also ensure that the OUTISDE_LOCAL firewall group is applied to the WAN interface and a direction (local). +You should also ensure that the OUTISDE_LOCAL firewall group is applied to the +WAN interface and a direction (local). .. code-block:: none set interfaces ethernet eth0 firewall local name 'OUTSIDE-LOCAL' -Assure that your firewall rules allow the traffic, in which case you have a working VPN using WireGuard. +Assure that your firewall rules allow the traffic, in which case you have a +working VPN using WireGuard. .. code-block:: none @@ -223,23 +204,28 @@ 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 allows the peers to interact with one another. +the peers. This allows the peers to interact with one another. In +comparison to the site-to-site example the ``persistent-keepalive`` +flag is set to 15 seconds to assure the connection is kept alive. +This is mainly relevant if one of the peers is behind NAT and can't +be connected to if the connection is lost. To be effective this +value needs to be lower than the UDP timeout. .. code-block:: none - wireguard wg0 { + wireguard wg01 { address 10.172.24.1/24 - address 2001:DB8:470:22::1/64 + 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 + 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::20/128 + allowed-ips 2001:db8:470:22::20/128 persistent-keepalive 15 pubkey BknHcLFo8nOo8Dwq2CjaC/TedchKQ0ebxC7GYn7Al00= } @@ -254,7 +240,7 @@ through the connection. [Interface] PrivateKey = ARAKLSDJsadlkfjasdfiowqeruriowqeuasdf= - Address = 10.172.24.20/24, 2001:DB8:470:22::20/64 + Address = 10.172.24.20/24, 2001:db8:470:22::20/64 DNS = 10.0.0.53, 10.0.0.54 [Peer] @@ -263,19 +249,19 @@ through the connection. Endpoint = 192.0.2.1:2224 PersistentKeepalive = 25 -However, split-tunneling can be achieved by specifing the remote subnets. -This ensures that only traffic destined for the remote site is sent over the tunnel. -All other traffic is unaffected. +However, split-tunneling can be achieved by specifying the remote subnets. +This ensures that only traffic destined for the remote site is sent over the +tunnel. All other traffic is unaffected. .. code-block:: none [Interface] PrivateKey = 8Iasdfweirousd1EVGUk5XsT+wYFZ9mhPnQhmjzaJE6Go= - Address = 10.172.24.30/24, 2001:DB8:470:22::30/64 + 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 + AllowedIPs = 10.172.24.30/24, 2001:db8:470:22::/64 Endpoint = 192.0.2.1:2224 PersistentKeepalive = 25 @@ -296,7 +282,7 @@ Status Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down Interface IP Address S/L Description --------- ---------- --- ----------- - wg0 10.0.0.1/24 u/u + wg01 10.0.0.1/24 u/u .. opcmd:: show interfaces wireguard <interface> @@ -306,7 +292,7 @@ Status .. code-block:: none vyos@vyos:~$ show interfaces wireguard wg01 - interface: wg0 + interface: wg01 address: 10.0.0.1/24 public key: h1HkYlSuHdJN6Qv4Hz4bBzjGg5WUty+U1L7DJsZy1iE= private key: (hidden) @@ -358,14 +344,15 @@ Some users tend to connect their mobile devices using WireGuard to their VyOS router. To ease deployment one can generate a "per mobile" configuration from the VyOS CLI. -.. warning:: From a security perspective it is not recommended to let a third - party create and share the private key for a secured connection. You should create the - private portion on your own and only hand out the public key. Please keep this - in mind when using this convenience feature. +.. warning:: From a security perspective, it is not recommended to let a third + party create and share the private key for a secured connection. + You should create the private portion on your own and only hand out the + public key. Please keep this in mind when using this convenience feature. -.. opcmd:: generate wireguard client-config <name> interface <interface> server <ip|fqdn> address <client-ip> +.. opcmd:: generate wireguard client-config <name> interface <interface> server + <ip|fqdn> address <client-ip> - Using this command you will create a new client configuration which can + Using this command, you will create a new client configuration which can connect to ``interface`` on this router. The public key from the specified interface is automatically extracted and embedded into the configuration. @@ -375,7 +362,7 @@ the VyOS CLI. In addition you will specifiy the IP address or FQDN for the client where it will connect to. The address parameter can be used up to two times and is used - to assign the client its specific IPv4 (/32) or IPv6 (/128) address. + to assign the clients specific IPv4 (/32) or IPv6 (/128) address. .. figure:: /_static/images/wireguard_qrcode.jpg :alt: WireGuard Client QR code diff --git a/docs/configuration/interfaces/wireless.rst b/docs/configuration/interfaces/wireless.rst index eeb54401..f45101b5 100644 --- a/docs/configuration/interfaces/wireless.rst +++ b/docs/configuration/interfaces/wireless.rst @@ -1,4 +1,4 @@ -:lastproofread: 2022-08-26 +:lastproofread: 2023-01-26 .. _wireless-interface: @@ -305,7 +305,7 @@ default physical device (``phy0``) is used. set interfaces wireless wlan0 type station set interfaces wireless wlan0 address dhcp set interfaces wireless wlan0 ssid Test - set interfaces wireless wlan0 security wpa + set interfaces wireless wlan0 security wpa passphrase '12345678' Resulting in diff --git a/docs/configuration/interfaces/wwan.rst b/docs/configuration/interfaces/wwan.rst index 457445e3..45b18387 100644 --- a/docs/configuration/interfaces/wwan.rst +++ b/docs/configuration/interfaces/wwan.rst @@ -1,4 +1,4 @@ -:lastproofread: 2022-08-26 +:lastproofread: 2023-01-27 .. _wwan-interface: diff --git a/docs/configuration/loadbalancing/index.rst b/docs/configuration/loadbalancing/index.rst index 838d0044..18f01347 100644 --- a/docs/configuration/loadbalancing/index.rst +++ b/docs/configuration/loadbalancing/index.rst @@ -1,4 +1,4 @@ -:lastproofread: 2022-08-26 +:lastproofread: 2023-01-27 .. _load-balancing: @@ -13,7 +13,7 @@ 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: +In a minimal configuration, the following must be provided: * an interface with a nexthop * one rule with a LAN (inbound-interface) and the WAN (interface). diff --git a/docs/configuration/nat/nptv6.rst b/docs/configuration/nat/nptv6.rst index c09c8336..cffb2a14 100644 --- a/docs/configuration/nat/nptv6.rst +++ b/docs/configuration/nat/nptv6.rst @@ -44,12 +44,12 @@ NPTv6 support has been added in VyOS 1.2 (Crux) and is available through .. code-block:: none - set rule 10 source prefix 'fc00:dead:beef::/48' - set rule 10 outbound-interface 'eth1' - set rule 10 translation prefix '2001:db8:e1::/48' - set rule 20 source prefix 'fc00:dead:beef::/48' - set rule 20 outbound-interface 'eth2' - set rule 20 translation prefix '2001:db8:e2::/48' + set nat nptv6 rule 10 source prefix 'fc00:dead:beef::/48' + set nat nptv6 rule 10 outbound-interface 'eth1' + set nat nptv6 rule 10 translation prefix '2001:db8:e1::/48' + set nat nptv6 rule 20 source prefix 'fc00:dead:beef::/48' + set nat nptv6 rule 20 outbound-interface 'eth2' + set nat nptv6 rule 20 translation prefix '2001:db8:e2::/48' Resulting in the following ip6tables rules: diff --git a/docs/configuration/protocols/bfd.rst b/docs/configuration/protocols/bfd.rst index eb8088fd..9df2bd40 100644 --- a/docs/configuration/protocols/bfd.rst +++ b/docs/configuration/protocols/bfd.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-09-28 +:lastproofread: 2023-01-27 .. include:: /_include/need_improvement.txt diff --git a/docs/configuration/protocols/bgp.rst b/docs/configuration/protocols/bgp.rst index 8481f0e2..5b9cb762 100644 --- a/docs/configuration/protocols/bgp.rst +++ b/docs/configuration/protocols/bgp.rst @@ -538,7 +538,8 @@ Common parametrs 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> +.. cfgcmd:: set protocols bgp <asn> address-family <ipv4-unicast|ipv6-unicast> + 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 diff --git a/docs/configuration/protocols/igmp.rst b/docs/configuration/protocols/igmp.rst index 7f14b262..56703d1f 100644 --- a/docs/configuration/protocols/igmp.rst +++ b/docs/configuration/protocols/igmp.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-09-30 +:lastproofread: 2023-01-27 .. _multicast: @@ -151,13 +151,13 @@ You can also tune multicast with the following commands. IP address too. -.. cfgcmd:: set protocols igmp interface <interface query-interval <seconds> +.. 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 +.. cfgcmd:: set protocols igmp interface <interface> query-max-response-time <deciseconds> Use this command to configure in the selected interface the IGMP diff --git a/docs/configuration/protocols/rpki.rst b/docs/configuration/protocols/rpki.rst index cae66044..294a91f8 100644 --- a/docs/configuration/protocols/rpki.rst +++ b/docs/configuration/protocols/rpki.rst @@ -58,8 +58,7 @@ Imported prefixes during the validation may have values: 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`_). + (default-free zone)` at the start of 2020 .. note:: If you are responsible for the global addresses assigned to your @@ -104,20 +103,20 @@ In a nutshell, the current implementation provides the following features: Configuration ************* -.. cfgcmd:: protocols rpki polling-period <1-86400> +.. cfgcmd:: set 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> +.. cfgcmd:: set 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> +.. cfgcmd:: set 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. @@ -133,19 +132,19 @@ 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> +.. cfgcmd:: set 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> +.. cfgcmd:: set 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> +.. cfgcmd:: set 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 +.. cfgcmd:: set protocols rpki cache <address> ssh public-key-file <filepath> Local path that includes the public key file of the router. @@ -191,10 +190,9 @@ Test`_ experimental tool. .. _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 +.. _Validator: https://www.ripe.net/manage-ips-and-asns/resource-management/rpki/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.html diff --git a/docs/configuration/protocols/static.rst b/docs/configuration/protocols/static.rst index 42c0c4b7..78db63dc 100644 --- a/docs/configuration/protocols/static.rst +++ b/docs/configuration/protocols/static.rst @@ -32,7 +32,7 @@ Static Routes distance <distance> Defines next-hop distance for this route, routes with smaller administrative - distance are elected prior those with a higher distance. + distance are elected prior to those with a higher distance. Range is 1 to 255, default is 1. @@ -52,7 +52,7 @@ Static Routes distance <distance> Defines next-hop distance for this route, routes with smaller administrative - distance are elected prior those with a higher distance. + distance are elected prior to those with a higher distance. Range is 1 to 255, default is 1. @@ -67,7 +67,7 @@ Interface Routes <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 + static route. `<interface>` will be the next-hop interface where traffic is routed for the given `<subnet>`. .. cfgcmd:: set protocols static interface-route <subnet> next-hop-interface @@ -79,7 +79,7 @@ Interface Routes <interface> distance <distance> Defines next-hop distance for this route, routes with smaller administrative - distance are elected prior those with a higher distance. + distance are elected prior to those with a higher distance. Range is 1 to 255, default is 1. @@ -87,7 +87,7 @@ Interface Routes <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 + static route. `<interface>` will be the next-hop interface where traffic is routed for the given `<subnet>`. .. cfgcmd:: set protocols static interface-route6 <subnet> next-hop-interface @@ -99,7 +99,7 @@ Interface Routes <interface> distance <distance> Defines next-hop distance for this route, routes with smaller administrative - distance are elected prior those with a higher distance. + distance are elected prior to those with a higher distance. Range is 1 to 255, default is 1. @@ -118,7 +118,7 @@ Blackhole .. 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. + distance are elected prior to those with a higher distance. .. cfgcmd:: set protocols static route6 <subnet> blackhole @@ -131,7 +131,7 @@ Blackhole .. 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. + distance are elected prior to those with a higher distance. Alternate Routing Tables @@ -139,7 +139,7 @@ Alternate Routing Tables TBD -Alternate routing tables are used with policy based routing of by utilizing +Alternate routing tables are used with policy based routing by utilizing :ref:`vrf`. diff --git a/docs/configuration/service/broadcast-relay.rst b/docs/configuration/service/broadcast-relay.rst index 0b0e1054..b6e2bed7 100644 --- a/docs/configuration/service/broadcast-relay.rst +++ b/docs/configuration/service/broadcast-relay.rst @@ -28,10 +28,10 @@ Configuration want to receive/relay packets on both `eth1` and `eth2` both interfaces need to be added. -.. cfgcmd:: set service broadcast-relay id <n> address <address> +.. cfgcmd:: set service broadcast-relay id <n> address <ipv4-address> - Set a optional source IP of the forwarded packets, - otherwise the original sender address is used. + Set the source IP of forwarded packets, otherwise original senders address + is used. .. cfgcmd:: set service broadcast-relay id <n> port <port> diff --git a/docs/configuration/service/dhcp-relay.rst b/docs/configuration/service/dhcp-relay.rst index b9aefbfb..b489b600 100644 --- a/docs/configuration/service/dhcp-relay.rst +++ b/docs/configuration/service/dhcp-relay.rst @@ -8,7 +8,8 @@ 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. +All interfaces used for the DHCP relay must be configured. This includes the +uplink to the DHCP server. ********** IPv4 relay @@ -19,7 +20,8 @@ Configuration .. cfgcmd:: set service dhcp-relay interface <interface> - Enable the DHCP relay service on the given interface. + Interfaces that participate in the DHCP relay process, including the uplink + to the DHCP server. .. cfgcmd:: set service dhcp-relay server <server> @@ -62,9 +64,9 @@ Example ======= * Listen for DHCP requests on interface ``eth1``. -* DHCP server is located at IPv4 address 10.0.1.4. +* DHCP server is located at IPv4 address 10.0.1.4 on ``eth2``. * Router receives DHCP client requests on ``eth1`` and relays them to the server - at 10.0.1.4. + at 10.0.1.4 on ``eth2``. .. figure:: /_static/images/service_dhcp-relay01.png :scale: 80 % diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst index f55c7a45..4ddb6d69 100644 --- a/docs/configuration/service/dhcp-server.rst +++ b/docs/configuration/service/dhcp-server.rst @@ -21,6 +21,16 @@ address. Configuration ============= +.. cfgcmd:: set service dhcp-server hostfile-update + + Create DNS record per client lease, by adding clients to /etc/hosts file. + Entry will have format: `<shared-network-name>_<hostname>.<domain-name>` + +.. cfgcmd:: set service dhcp-server host-decl-name + + Will drop `<shared-network-name>_` from client DNS record, using only the + host declaration name and domain: `<hostname>.<domain-name>` + .. cfgcmd:: set service dhcp-server shared-network-name <name> domain-name <domain-name> The domain-name parameter should be the domain name that will be appended to @@ -447,7 +457,8 @@ Raw Parameters Option 43 for UniFI ------------------- -* These parameters need to be part of the DHCP global options. They stay unchanged. +* These parameters need to be part of the DHCP global options. + They stay unchanged. .. code-block:: none diff --git a/docs/configuration/service/dns.rst b/docs/configuration/service/dns.rst index 23634824..ce26b856 100644 --- a/docs/configuration/service/dns.rst +++ b/docs/configuration/service/dns.rst @@ -204,6 +204,8 @@ 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>`. diff --git a/docs/configuration/service/https.rst b/docs/configuration/service/https.rst index de5e759a..a1ca6490 100644 --- a/docs/configuration/service/https.rst +++ b/docs/configuration/service/https.rst @@ -4,7 +4,7 @@ HTTP-API ######## -VyOS provides an HTTP API. You can use it to execute op-mode commands, +VyOS provide an HTTP API. You can use it to execute op-mode commands, update VyOS, set or delete config. Please take a look at the :ref:`vyosapi` page for an detailed how-to. @@ -15,7 +15,7 @@ Configuration .. cfgcmd:: set service https api keys id <name> key <apikey> - Set a named api key, every key has the same, full permissions + Set a named api key. Every key has the same, full permissions on the system. .. cfgcmd:: set service https api debug @@ -37,6 +37,7 @@ Configuration Enforce strict path checking .. cfgcmd:: set service https virtual-host <vhost> listen-address + <ipv4 or ipv6 address> Address to listen for HTTPS requests @@ -46,11 +47,11 @@ Configuration .. cfgcmd:: set service https virtual-host <vhost> server-name <text> - Server names for virtual hosts it ca be exact, wildcard or regex. + Server names for virtual hosts it can be exact, wildcard or regex. .. cfgcmd:: set service https api-restrict virtual-host <vhost> - Nginx exposes the local API on all virtual servers, by default. + By default, nginx exposes the local API on all virtual servers. Use this to restrict nginx to one or more virtual hosts. .. cfgcmd:: set service https certificates certbot domain-name <text> @@ -75,15 +76,14 @@ Configuration Example Configuration ********************* -Setting an API-KEY is the minimal configuration needed to get a working API -Endpoint. +Set an API-KEY is the minimal configuration to get a working API Endpoint. .. code-block:: none set service https api keys id MY-HTTPS-API-ID key MY-HTTPS-API-PLAINTEXT-KEY -To use this full configuration we asume a globally resolvable hostname. +To use this full configuration we asume a public accessible hostname. .. code-block:: none diff --git a/docs/configuration/service/pppoe-server.rst b/docs/configuration/service/pppoe-server.rst index ad99cec0..066ecc73 100644 --- a/docs/configuration/service/pppoe-server.rst +++ b/docs/configuration/service/pppoe-server.rst @@ -172,14 +172,15 @@ 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. + 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, 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 diff --git a/docs/configuration/service/router-advert.rst b/docs/configuration/service/router-advert.rst index 36fa600d..9aaacec2 100644 --- a/docs/configuration/service/router-advert.rst +++ b/docs/configuration/service/router-advert.rst @@ -8,7 +8,6 @@ Router Advertisements They are part of what is known as :abbr:`SLAAC (Stateless Address Autoconfiguration)`. - Supported interface types: * bonding @@ -21,7 +20,7 @@ Supported interface types: * vxlan * wireguard * wireless - * wirelessmodem + * wwan Enabling Advertisments diff --git a/docs/configuration/service/snmp.rst b/docs/configuration/service/snmp.rst index 1977bf7f..7f50a6a0 100644 --- a/docs/configuration/service/snmp.rst +++ b/docs/configuration/service/snmp.rst @@ -131,7 +131,7 @@ 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 security approach in v3 targets: +The security approach in SNMPv3 targets: * Confidentiality – Encryption of packets to prevent snooping by an unauthorized source. @@ -203,7 +203,8 @@ VyOS MIBs All SNMP MIBs are located in each image of VyOS here: ``/usr/share/snmp/mibs/`` -You can download the file to your local host with an active ssh service like this +You are be able to download the files using SCP, once the SSH service +has been activated like so .. code-block:: none diff --git a/docs/configuration/service/ssh.rst b/docs/configuration/service/ssh.rst index e03d1e70..b4018c52 100644 --- a/docs/configuration/service/ssh.rst +++ b/docs/configuration/service/ssh.rst @@ -157,7 +157,7 @@ Operation ``/config/auth/id_rsa_rpki.pub`` will be created. -.. opcmd:: generate public-key-command name <username> path <location> +.. opcmd:: generate public-key-command user <username> path <location> Generate the configuration mode commands to add a public key for :ref:`ssh_key_based_authentication`. @@ -169,7 +169,7 @@ Operation .. code-block:: none - alyssa@vyos:~$ generate public-key-command name alyssa path sftp://example.net/home/alyssa/.ssh/id_rsa.pub + alyssa@vyos:~$ generate public-key-command user alyssa path sftp://example.net/home/alyssa/.ssh/id_rsa.pub # To add this key as an embedded key, run the following commands: configure set system login user alyssa authentication public-keys alyssa@example.net key AAA... diff --git a/docs/configuration/service/tftp-server.rst b/docs/configuration/service/tftp-server.rst index 268db872..1f4bb380 100644 --- a/docs/configuration/service/tftp-server.rst +++ b/docs/configuration/service/tftp-server.rst @@ -15,18 +15,18 @@ Configuration .. cfgcmd:: set service tftp-server directory <directory> -Enable TFTP service by specifying the `<directory>` which will be used to serve -files. + 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. +.. hint:: Choose your ``directory`` location carefully or you will lose the + content on image upgrades. We preserve the contents of ``/config``, so we + recommend using a directory there, for example ``/config/tftpboot``. .. 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. + 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. .. cfgcmd:: set service tftp-server listen-address <address> vrf <name> @@ -40,15 +40,15 @@ Additional option to run TFTP server in the :abbr:`VRF (Virtual Routing and Forw .. cfgcmd:: set service tftp-server allow-upload -Optional, if you want to enable uploads, else TFTP server will act as read-only -server. + Optional, if you want to enable uploads, else TFTP server will act as a + 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! +TFTP to this server is disabled. The resulting configuration will look like: diff --git a/docs/configuration/system/conntrack.rst b/docs/configuration/system/conntrack.rst index 6329fcf2..68a4f2b8 100644 --- a/docs/configuration/system/conntrack.rst +++ b/docs/configuration/system/conntrack.rst @@ -29,16 +29,16 @@ Configure :defaultvalue: Set the size of the hash table. The connection tracking hash table makes - searching the connection tracking table faster. The hash table uses “buckets” to - record entries in the connection tracking table. + searching the connection tracking table faster. The hash table uses + “buckets” to record entries in the connection tracking table. -.. cfgcmd:: system conntrack modules ftp -.. cfgcmd:: system conntrack modules h323 -.. cfgcmd:: system conntrack modules nfs -.. cfgcmd:: system conntrack modules pptp -.. cfgcmd:: system conntrack modules sip -.. cfgcmd:: system conntrack modules sqlnet -.. cfgcmd:: system conntrack modules tftp +.. cfgcmd:: set system conntrack modules ftp +.. cfgcmd:: set system conntrack modules h323 +.. cfgcmd:: set system conntrack modules nfs +.. cfgcmd:: set system conntrack modules pptp +.. cfgcmd:: set system conntrack modules sip +.. cfgcmd:: set system conntrack modules sqlnet +.. cfgcmd:: set system conntrack modules tftp Configure the connection tracking protocol helper modules. All modules are enable by default. @@ -52,47 +52,48 @@ Define Conection Timeouts VyOS supports setting timeouts for connections according to the connection type. You can set timeout values for generic connections, for ICMP -connections, UDP connections, or for TCP connections in a number of different states. +connections, UDP connections, or for TCP connections in a number of different +states. -.. cfgcmd:: system conntrack timeout icmp <1-21474836> +.. cfgcmd:: set system conntrack timeout icmp <1-21474836> :defaultvalue: -.. cfgcmd:: system conntrack timeout other <1-21474836> +.. cfgcmd:: set system conntrack timeout other <1-21474836> :defaultvalue: -.. cfgcmd:: system conntrack timeout tcp close <1-21474836> +.. cfgcmd:: set system conntrack timeout tcp close <1-21474836> :defaultvalue: -.. cfgcmd:: system conntrack timeout tcp close-wait <1-21474836> +.. cfgcmd:: set system conntrack timeout tcp close-wait <1-21474836> :defaultvalue: -.. cfgcmd:: system conntrack timeout tcp established <1-21474836> +.. cfgcmd:: set system conntrack timeout tcp established <1-21474836> :defaultvalue: -.. cfgcmd:: system conntrack timeout tcp fin-wait <1-21474836> +.. cfgcmd:: set system conntrack timeout tcp fin-wait <1-21474836> :defaultvalue: -.. cfgcmd:: system conntrack timeout tcp last-ack <1-21474836> +.. cfgcmd:: set system conntrack timeout tcp last-ack <1-21474836> :defaultvalue: -.. cfgcmd:: system conntrack timeout tcp syn-recv <1-21474836> +.. cfgcmd:: set system conntrack timeout tcp syn-recv <1-21474836> :defaultvalue: -.. cfgcmd:: system conntrack timeout tcp syn-sent <1-21474836> +.. cfgcmd:: set system conntrack timeout tcp syn-sent <1-21474836> :defaultvalue: -.. cfgcmd:: system conntrack timeout tcp time-wait <1-21474836> +.. cfgcmd:: set system conntrack timeout tcp time-wait <1-21474836> :defaultvalue: -.. cfgcmd:: system conntrack timeout udp other <1-21474836> +.. cfgcmd:: set system conntrack timeout udp other <1-21474836> :defaultvalue: -.. cfgcmd:: system conntrack timeout udp stream <1-21474836> +.. cfgcmd:: set system conntrack timeout udp stream <1-21474836> :defaultvalue: Set the timeout in secounds for a protocol or state. You can also define custom timeout values to apply to a specific subset of -connections, based on a packet and flow selector. To do this, you create a rule -defining the packet and flow selector. +connections, based on a packet and flow selector. To do this, you need to +create a rule defining the packet and flow selector. -.. cfgcmd:: system conntrack timeout custom rule <1-9999> description <test> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> description <test> Set a rule description. -.. cfgcmd:: system conntrack timeout custom rule <1-9999> destination address <ip-address> -.. cfgcmd:: system conntrack timeout custom rule <1-9999> source address <ip-address> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> destination address <ip-address> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> source address <ip-address> set a destination and/or source address. Accepted input: @@ -107,8 +108,8 @@ defining the packet and flow selector. !<x.x.x.x>-<x.x.x.x> Match everything except the specified range -.. cfgcmd:: system conntrack timeout custom rule <1-9999> destination port <value> -.. cfgcmd:: system conntrack timeout custom rule <1-9999> source port <value> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> destination port <value> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> source port <value> Set a destination and/or source port. Accepted input: @@ -124,63 +125,63 @@ defining the packet and flow selector. -.. cfgcmd:: system conntrack timeout custom rule <1-9999> protocol icmp <1-21474836> -.. cfgcmd:: system conntrack timeout custom rule <1-9999> protocol other <1-21474836> -.. cfgcmd:: system conntrack timeout custom rule <1-9999> protocol tcp close <1-21474836> -.. cfgcmd:: system conntrack timeout custom rule <1-9999> protocol tcp close-wait <1-21474836> -.. cfgcmd:: system conntrack timeout custom rule <1-9999> protocol tcp established <1-21474836> -.. cfgcmd:: system conntrack timeout custom rule <1-9999> protocol tcp fin-wait <1-21474836> -.. cfgcmd:: system conntrack timeout custom rule <1-9999> protocol tcp last-ack <1-21474836> -.. cfgcmd:: system conntrack timeout custom rule <1-9999> protocol tcp syn-recv <1-21474836> -.. cfgcmd:: system conntrack timeout custom rule <1-9999> protocol tcp syn-sent <1-21474836> -.. cfgcmd:: system conntrack timeout custom rule <1-9999> protocol tcp time-wait <1-21474836> -.. cfgcmd:: system conntrack timeout custom rule <1-9999> protocol udp other <1-21474836> -.. cfgcmd:: system conntrack timeout custom rule <1-9999> protocol udp stream <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol icmp <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol other <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp close <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp close-wait <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp established <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp fin-wait <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp last-ack <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp syn-recv <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp syn-sent <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp time-wait <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol udp other <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol udp stream <1-21474836> Set the timeout in secounds for a protocol or state in a custom rule. -.. cfgcmd:: system conntrack tcp half-open-connections <1-21474836> +.. cfgcmd:: set system conntrack tcp half-open-connections <1-21474836> :defaultvalue: Set the maximum number of TCP half-open connections. -.. cfgcmd:: system conntrack tcp loose <enable | disable> +.. cfgcmd:: set system conntrack tcp loose <enable | disable> :defaultvalue: Policy to track previously established connections. -.. cfgcmd:: system conntrack tcp max-retrans <1-2147483647> +.. cfgcmd:: set system conntrack tcp max-retrans <1-2147483647> :defaultvalue: Set the number of TCP maximum retransmit attempts. -.. cfgcmd:: system conntrack ignore rule <1-9999> description <text> -.. cfgcmd:: system conntrack ignore rule <1-9999> destination address <ip-address> -.. cfgcmd:: system conntrack ignore rule <1-9999> destination port <port> -.. cfgcmd:: system conntrack ignore rule <1-9999> inbound-interface <interface> -.. cfgcmd:: system conntrack ignore rule <1-9999> protocol <protocol> -.. cfgcmd:: system conntrack ignore rule <1-9999> source address <ip-address> -.. cfgcmd:: system conntrack ignore rule <1-9999> source port <port> - - Configure customized ignore rules for selective connection tracking - -.. cfgcmd:: system conntrack log icmp destroy -.. cfgcmd:: system conntrack log icmp new -.. cfgcmd:: system conntrack log icmp update -.. cfgcmd:: system conntrack log other destroy -.. cfgcmd:: system conntrack log other new -.. cfgcmd:: system conntrack log other update -.. cfgcmd:: system conntrack log tcp destroy -.. cfgcmd:: system conntrack log tcp new -.. cfgcmd:: system conntrack log tcp update close-wait -.. cfgcmd:: system conntrack log tcp update established -.. cfgcmd:: system conntrack log tcp update fin-wait -.. cfgcmd:: system conntrack log tcp update last-ack -.. cfgcmd:: system conntrack log tcp update syn-received -.. cfgcmd:: system conntrack log tcp update time-wait -.. cfgcmd:: system conntrack log udp destroy -.. cfgcmd:: system conntrack log udp new -.. cfgcmd:: system conntrack log udp update +.. cfgcmd:: set system conntrack ignore rule <1-9999> description <text> +.. cfgcmd:: set system conntrack ignore rule <1-9999> destination address <ip-address> +.. cfgcmd:: set system conntrack ignore rule <1-9999> destination port <port> +.. cfgcmd:: set system conntrack ignore rule <1-9999> inbound-interface <interface> +.. cfgcmd:: set system conntrack ignore rule <1-9999> protocol <protocol> +.. cfgcmd:: set system conntrack ignore rule <1-9999> source address <ip-address> +.. cfgcmd:: set system conntrack ignore rule <1-9999> source port <port> + + Customized ignore rules, based on a packet and flow selector. + +.. cfgcmd:: set system conntrack log icmp destroy +.. cfgcmd:: set system conntrack log icmp new +.. cfgcmd:: set system conntrack log icmp update +.. cfgcmd:: set system conntrack log other destroy +.. cfgcmd:: set system conntrack log other new +.. cfgcmd:: set system conntrack log other update +.. cfgcmd:: set system conntrack log tcp destroy +.. cfgcmd:: set system conntrack log tcp new +.. cfgcmd:: set system conntrack log tcp update close-wait +.. cfgcmd:: set system conntrack log tcp update established +.. cfgcmd:: set system conntrack log tcp update fin-wait +.. cfgcmd:: set system conntrack log tcp update last-ack +.. cfgcmd:: set system conntrack log tcp update syn-received +.. cfgcmd:: set system conntrack log tcp update time-wait +.. cfgcmd:: set system conntrack log udp destroy +.. cfgcmd:: set system conntrack log udp new +.. cfgcmd:: set system conntrack log udp update Log the connection tracking events per protocol.
\ No newline at end of file diff --git a/docs/configuration/system/syslog.rst b/docs/configuration/system/syslog.rst index 9ba9d415..ab427d99 100644 --- a/docs/configuration/system/syslog.rst +++ b/docs/configuration/system/syslog.rst @@ -33,7 +33,7 @@ Custom File .. cfgcmd:: set system syslog file <filename> facility <keyword> level <keyword> - Log syslog messages to file specified via `<filename>`, for en explanation on + Log syslog messages to file specified via `<filename>`, for an explanation on :ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords see tables below. @@ -62,7 +62,7 @@ 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 + can be specified by either FQDN or IP address. For an explanation on :ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords see tables below. @@ -81,7 +81,7 @@ Local User Account 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 + logged in, no messages are being displayed. For an explanation on :ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords see tables below. diff --git a/docs/configuration/vpn/l2tp.rst b/docs/configuration/vpn/l2tp.rst index 0df5080c..3418b66c 100644 --- a/docs/configuration/vpn/l2tp.rst +++ b/docs/configuration/vpn/l2tp.rst @@ -26,7 +26,7 @@ with native Windows and Mac VPN clients): 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. +In the above example, 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: @@ -162,7 +162,7 @@ servers can be setup and will be used subsequentially. RADIUS source address ^^^^^^^^^^^^^^^^^^^^^ -If you are using OSPF as IGP always the closets interface connected to the +If you are using OSPF as IGP, always the closest 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. @@ -174,7 +174,7 @@ 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. + Best practice would be a loopback or dummy interface. RADIUS bandwidth shaping attribute ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/configuration/vpn/site2site_ipsec.rst b/docs/configuration/vpn/site2site_ipsec.rst index e81c5c3b..879f8dfa 100644 --- a/docs/configuration/vpn/site2site_ipsec.rst +++ b/docs/configuration/vpn/site2site_ipsec.rst @@ -344,3 +344,50 @@ Imagine the following topology 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' + +Key Parameters: + +* ``authentication local-id/remote-id`` - IKE identification is used for + validation of VPN peer devices during IKE negotiation. If you do not configure + local/remote-identity, the device uses the IPv4 or IPv6 address that + corresponds to the local/remote peer by default. + In certain network setups (like ipsec interface with dynamic address, or + behind the NAT ), the IKE ID received from the peer does not match the IKE + gateway configured on the device. This can lead to a Phase 1 validation + failure. + So, make sure to configure the local/remote id explicitly and ensure that the + IKE ID is the same as the remote-identity configured on the peer device. + +* ``disable-route-autoinstall`` - This option when configured disables the + routes installed in the default table 220 for site-to-site ipsec. + It is mostly used with VTI configuration. + +* ``dead-peer-detection action = clear | hold | restart`` - R_U_THERE + notification messages(IKEv1) or empty INFORMATIONAL messages (IKEv2) + are periodically sent in order to check the liveliness of the IPsec peer. The + values clear, hold, and restart all activate DPD and determine the action to + perform on a timeout. + With ``clear`` the connection is closed with no further actions taken. + ``hold`` installs a trap policy, which will catch matching traffic and tries + to re-negotiate the connection on demand. + ``restart`` will immediately trigger an attempt to re-negotiate the + connection. + +* ``close-action = none | clear | hold | restart`` - defines the action to take + if the remote peer unexpectedly closes a CHILD_SA (see above for meaning of + values). A closeaction should not be used if the peer uses reauthentication or + uniqueids. + + When the close-action option is set on the peers, the connection-type + of each peer has to considered carefully. For example, if the option is set + on both peers, then both would attempt to initiate and hold open multiple + copies of each child SA. This might lead to instability of the device or + cpu/memory utilization. + + Below flow-chart could be a quick reference for the close-action + combination depending on how the peer is configured. + +.. figure:: /_static/images/IPSec_close_action_settings.jpg + + Similar combinations are applicable for the dead-peer-detection. + |