From 5a35f4d30e5c16bd85e811176cffa86b721112b7 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Sat, 2 May 2026 18:59:58 +0300 Subject: refactor(swap): rename imported .md files to md- prefix for swap mechanism MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restore the canary file naming convention that swap_sources.py expects: the imported MyST pages now live as docs//md-.md alongside the existing docs//.rst, so swap_sources.py --swap can rename them into place at build time. - 254 .md files renamed (every page with a matching .rst counterpart) - 2 MyST-only pages left at their final names (no .rst exists, no swap needed): docs/copyright.md, docs/automation/terraform/terraformvyos.md All 114 stems listed in docs/_swap.txt now have a corresponding md-.md source file ready to swap in. ๐Ÿค– Generated by [robots](https://vyos.io) --- docs/configuration/system/acceleration.md | 158 ------- docs/configuration/system/conntrack.md | 218 --------- docs/configuration/system/console.md | 59 --- docs/configuration/system/default-route.md | 40 -- docs/configuration/system/flow-accounting.md | 209 -------- docs/configuration/system/frr.md | 45 -- docs/configuration/system/host-name.md | 70 --- docs/configuration/system/index.md | 34 -- docs/configuration/system/ip.md | 126 ----- docs/configuration/system/ipv6.md | 193 -------- docs/configuration/system/lcd.md | 41 -- docs/configuration/system/login.md | 604 ------------------------ docs/configuration/system/md-acceleration.md | 158 +++++++ docs/configuration/system/md-conntrack.md | 218 +++++++++ docs/configuration/system/md-console.md | 59 +++ docs/configuration/system/md-default-route.md | 40 ++ docs/configuration/system/md-flow-accounting.md | 209 ++++++++ docs/configuration/system/md-frr.md | 45 ++ docs/configuration/system/md-host-name.md | 70 +++ docs/configuration/system/md-index.md | 34 ++ docs/configuration/system/md-ip.md | 126 +++++ docs/configuration/system/md-ipv6.md | 193 ++++++++ docs/configuration/system/md-lcd.md | 41 ++ docs/configuration/system/md-login.md | 604 ++++++++++++++++++++++++ docs/configuration/system/md-name-server.md | 65 +++ docs/configuration/system/md-option.md | 190 ++++++++ docs/configuration/system/md-proxy.md | 27 ++ docs/configuration/system/md-sflow.md | 66 +++ docs/configuration/system/md-sysctl.md | 16 + docs/configuration/system/md-syslog.md | 450 ++++++++++++++++++ docs/configuration/system/md-task-scheduler.md | 45 ++ docs/configuration/system/md-time-zone.md | 17 + docs/configuration/system/md-updates.md | 36 ++ docs/configuration/system/md-watchdog.md | 212 +++++++++ docs/configuration/system/name-server.md | 65 --- docs/configuration/system/option.md | 190 -------- docs/configuration/system/proxy.md | 27 -- docs/configuration/system/sflow.md | 66 --- docs/configuration/system/sysctl.md | 16 - docs/configuration/system/syslog.md | 450 ------------------ docs/configuration/system/task-scheduler.md | 45 -- docs/configuration/system/time-zone.md | 17 - docs/configuration/system/updates.md | 36 -- docs/configuration/system/watchdog.md | 212 --------- 44 files changed, 2921 insertions(+), 2921 deletions(-) delete mode 100644 docs/configuration/system/acceleration.md delete mode 100644 docs/configuration/system/conntrack.md delete mode 100644 docs/configuration/system/console.md delete mode 100644 docs/configuration/system/default-route.md delete mode 100644 docs/configuration/system/flow-accounting.md delete mode 100644 docs/configuration/system/frr.md delete mode 100644 docs/configuration/system/host-name.md delete mode 100644 docs/configuration/system/index.md delete mode 100644 docs/configuration/system/ip.md delete mode 100644 docs/configuration/system/ipv6.md delete mode 100644 docs/configuration/system/lcd.md delete mode 100644 docs/configuration/system/login.md create mode 100644 docs/configuration/system/md-acceleration.md create mode 100644 docs/configuration/system/md-conntrack.md create mode 100644 docs/configuration/system/md-console.md create mode 100644 docs/configuration/system/md-default-route.md create mode 100644 docs/configuration/system/md-flow-accounting.md create mode 100644 docs/configuration/system/md-frr.md create mode 100644 docs/configuration/system/md-host-name.md create mode 100644 docs/configuration/system/md-index.md create mode 100644 docs/configuration/system/md-ip.md create mode 100644 docs/configuration/system/md-ipv6.md create mode 100644 docs/configuration/system/md-lcd.md create mode 100644 docs/configuration/system/md-login.md create mode 100644 docs/configuration/system/md-name-server.md create mode 100644 docs/configuration/system/md-option.md create mode 100644 docs/configuration/system/md-proxy.md create mode 100644 docs/configuration/system/md-sflow.md create mode 100644 docs/configuration/system/md-sysctl.md create mode 100644 docs/configuration/system/md-syslog.md create mode 100644 docs/configuration/system/md-task-scheduler.md create mode 100644 docs/configuration/system/md-time-zone.md create mode 100644 docs/configuration/system/md-updates.md create mode 100644 docs/configuration/system/md-watchdog.md delete mode 100644 docs/configuration/system/name-server.md delete mode 100644 docs/configuration/system/option.md delete mode 100644 docs/configuration/system/proxy.md delete mode 100644 docs/configuration/system/sflow.md delete mode 100644 docs/configuration/system/sysctl.md delete mode 100644 docs/configuration/system/syslog.md delete mode 100644 docs/configuration/system/task-scheduler.md delete mode 100644 docs/configuration/system/time-zone.md delete mode 100644 docs/configuration/system/updates.md delete mode 100644 docs/configuration/system/watchdog.md (limited to 'docs/configuration/system') diff --git a/docs/configuration/system/acceleration.md b/docs/configuration/system/acceleration.md deleted file mode 100644 index 871129e6..00000000 --- a/docs/configuration/system/acceleration.md +++ /dev/null @@ -1,158 +0,0 @@ -(acceleration)= - -# Acceleration - -In this command tree, all hardware acceleration options will be handled. -At the moment only [Intelยฎ QAT] is supported - -## Intelยฎ QAT - -```{opcmd} show system acceleration qat - -use this command to check if there is an Intelยฎ QAT supported Processor in your system. - -:::{code-block} none -vyos@vyos:~$ show system acceleration qat -01:00.0 Co-processor [0b40]: Intel Corporation Atom Processor C3000 Series QuickAssist Technology [8086:19e2] (rev 11) -::: - -if there is non device the command will show `` `No QAT device found` `` -``` - -```{cfgcmd} set system acceleration qat - -if there is a supported device, enable Intelยฎ QAT -``` - - -```{opcmd} show system acceleration qat status - -Check if the Intelยฎ QAT device is up and ready to do the job. - -:::{code-block} none -vyos@vyos:~$ show system acceleration qat status -Checking status of all devices. -There is 1 QAT acceleration device(s) in the system: -qat_dev0 - type: c3xxx, inst_id: 0, node_id: 0, bsf: 0000:01:00.0, #accel: 3 #engines: 6 state: up -::: -``` - - -### Operation Mode - -```{opcmd} show system acceleration qat device \ config - -Show the full config uploaded to the QAT device. -``` - - -```{opcmd} show system acceleration qat device \ flows - -Get an overview over the encryption counters. -``` - - -```{opcmd} show system acceleration qat interrupts - -Show binded qat device interrupts to certain core. -``` - - -### Example - -Let's build a simple VPN between 2 Intelยฎ QAT ready devices. - -Side A: - -``` -set interfaces vti vti1 address '192.168.1.2/24' -set vpn ipsec authentication psk right id '10.10.10.2' -set vpn ipsec authentication psk right id '10.10.10.1' -set vpn ipsec authentication psk right secret 'Qwerty123' -set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes256' -set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha256' -set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '14' -set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes256' -set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha256' -set vpn ipsec interface 'eth0' -set vpn ipsec site-to-site peer right authentication local-id '10.10.10.2' -set vpn ipsec site-to-site peer right authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer right authentication remote-id '10.10.10.1' -set vpn ipsec site-to-site peer right connection-type 'initiate' -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 '10.10.10.2' -set vpn ipsec site-to-site peer right remote-address '10.10.10.1' -set vpn ipsec site-to-site peer right vti bind 'vti1' -``` - -Side B: - -``` -set interfaces vti vti1 address '192.168.1.1/24' -set vpn ipsec authentication psk left id '10.10.10.2' -set vpn ipsec authentication psk left id '10.10.10.1' -set vpn ipsec authentication psk left secret 'Qwerty123' -set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes256' -set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha256' -set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '14' -set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes256' -set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha256' -set vpn ipsec interface 'eth0' -set vpn ipsec site-to-site peer left authentication local-id '10.10.10.1' -set vpn ipsec site-to-site peer left authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer left authentication remote-id '10.10.10.2' -set vpn ipsec site-to-site peer left connection-type 'initiate' -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 '10.10.10.1' -set vpn ipsec site-to-site peer left remote-address '10.10.10.2' -set vpn ipsec site-to-site peer left vti bind 'vti1' -``` - -a bandwidth test over the VPN got these results: - -``` -Connecting to host 192.168.1.2, port 5201 -[ 9] local 192.168.1.1 port 51344 connected to 192.168.1.2 port 5201 -[ ID] Interval Transfer Bitrate Retr Cwnd -[ 9] 0.00-1.01 sec 32.3 MBytes 268 Mbits/sec 0 196 KBytes -[ 9] 1.01-2.03 sec 32.5 MBytes 268 Mbits/sec 0 208 KBytes -[ 9] 2.03-3.03 sec 32.5 MBytes 271 Mbits/sec 0 208 KBytes -[ 9] 3.03-4.04 sec 32.5 MBytes 272 Mbits/sec 0 208 KBytes -[ 9] 4.04-5.00 sec 31.2 MBytes 272 Mbits/sec 0 208 KBytes -[ 9] 5.00-6.01 sec 32.5 MBytes 272 Mbits/sec 0 234 KBytes -[ 9] 6.01-7.04 sec 32.5 MBytes 265 Mbits/sec 0 234 KBytes -[ 9] 7.04-8.04 sec 32.5 MBytes 272 Mbits/sec 0 234 KBytes -[ 9] 8.04-9.04 sec 32.5 MBytes 273 Mbits/sec 0 336 KBytes -[ 9] 9.04-10.00 sec 31.2 MBytes 272 Mbits/sec 0 336 KBytes -- - - - - - - - - - - - - - - - - - - - - - - - - -[ ID] Interval Transfer Bitrate Retr -[ 9] 0.00-10.00 sec 322 MBytes 270 Mbits/sec 0 sender -[ 9] 0.00-10.00 sec 322 MBytes 270 Mbits/sec receiver -``` - -with {cfgcmd}`set system acceleration qat` on both systems the bandwidth -increases. - -``` -Connecting to host 192.168.1.2, port 5201 -[ 9] local 192.168.1.1 port 51340 connected to 192.168.1.2 port 5201 -[ ID] Interval Transfer Bitrate Retr Cwnd -[ 9] 0.00-1.00 sec 97.3 MBytes 817 Mbits/sec 0 1000 KBytes -[ 9] 1.00-2.00 sec 92.5 MBytes 776 Mbits/sec 0 1.07 MBytes -[ 9] 2.00-3.00 sec 92.5 MBytes 776 Mbits/sec 0 820 KBytes -[ 9] 3.00-4.00 sec 92.5 MBytes 776 Mbits/sec 0 899 KBytes -[ 9] 4.00-5.00 sec 91.2 MBytes 765 Mbits/sec 0 972 KBytes -[ 9] 5.00-6.00 sec 92.5 MBytes 776 Mbits/sec 0 1.02 MBytes -[ 9] 6.00-7.00 sec 92.5 MBytes 776 Mbits/sec 0 1.08 MBytes -[ 9] 7.00-8.00 sec 92.5 MBytes 776 Mbits/sec 0 1.14 MBytes -[ 9] 8.00-9.00 sec 91.2 MBytes 765 Mbits/sec 0 915 KBytes -[ 9] 9.00-10.00 sec 92.5 MBytes 776 Mbits/sec 0 1000 KBytes -- - - - - - - - - - - - - - - - - - - - - - - - - -[ ID] Interval Transfer Bitrate Retr -[ 9] 0.00-10.00 sec 927 MBytes 778 Mbits/sec 0 sender -[ 9] 0.00-10.01 sec 925 MBytes 775 Mbits/sec receiver -``` - -[intelยฎ qat]: https://www.intel.com/content/www/us/en/architecture-and-technology/intel-quick-assist-technology-overview.html diff --git a/docs/configuration/system/conntrack.md b/docs/configuration/system/conntrack.md deleted file mode 100644 index f83f0684..00000000 --- a/docs/configuration/system/conntrack.md +++ /dev/null @@ -1,218 +0,0 @@ -# Conntrack - -VyOS can be configured to track connections using the connection -tracking subsystem. Connection tracking becomes operational once either -stateful firewall or NAT is configured. - -## Configure - -```{cfgcmd} set system conntrack table-size \<1-50000000\> -:defaultvalue: - -The connection tracking table contains one entry for each connection being -tracked by the system. -``` - -```{cfgcmd} set system conntrack expect-table-size \<1-50000000\> -:defaultvalue: - -The connection tracking expect table contains one entry for each expected -connection related to an existing connection. These are generally used by -โ€œconnection tracking helperโ€ modules such as FTP. -The default size of the expect table is 2048 entries. -``` - -```{cfgcmd} set system conntrack hash-size \<1-50000000\> -: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. -``` - -```{eval-rst} -.. 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. - - | Use `delete system conntrack modules` to deactive all modules. - | Or, for example ftp, `delete system conntrack modules ftp`. -``` - -```{cfgcmd} set system conntrack tcp half-open-connections \<1-21474836\> -:defaultvalue: - -Set the maximum number of TCP half-open connections. -``` - -```{cfgcmd} set system conntrack tcp loose \ -:defaultvalue: - -Policy to track previously established connections. -``` - -```{cfgcmd} set system conntrack tcp max-retrans \<1-2147483647\> -:defaultvalue: - -Set the number of TCP maximum retransmit attempts. -``` - -### Contrack Timeouts - -You can define custom timeout values to apply to a specific subset of -connections, based on a packet and flow selector. To do this, you need to -create a rule defining the packet and flow selector. - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - description - - Set a rule description. - -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - destination address -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - source address - - Set a destination and/or source address. Accepted input for ipv4: - - .. code-block:: none - - set system conntrack timeout custom ipv4 rule <1-999999> [source | destination] address - Possible completions: - IPv4 address to match - IPv4 prefix to match - - IPv4 address range to match - ! Match everything except the specified address - ! Match everything except the specified prefix - !- Match everything except the specified range - - set system conntrack timeout custom ipv6 rule <1-999999> [source | destination] address - Possible completions: - IP address to match - Subnet to match - - - IP range to match - ! Match everything except the specified address - ! Match everything except the specified prefix - !- - Match everything except the specified range - -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - destination port -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - source port - - Set a destination and/or source port. Accepted input: - - .. code-block:: none - - Named port (any name in /etc/services, e.g., http) - <1-65535> Numbered port - - Numbered port range (e.g., 1001-1005) - - Multiple destination ports can be specified as a comma-separated list. - The whole list can also be "negated" using '!'. For example: - `!22,telnet,http,123,1001-1005`` - -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - protocol tcp close <1-21474836> -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - protocol tcp close-wait <1-21474836> -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - protocol tcp established <1-21474836> -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - protocol tcp fin-wait <1-21474836> -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - protocol tcp last-ack <1-21474836> -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - protocol tcp syn-recv <1-21474836> -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - protocol tcp syn-sent <1-21474836> -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - protocol tcp time-wait <1-21474836> -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - protocol udp replied <1-21474836> -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - protocol udp unreplied <1-21474836> - - Set the timeout in seconds for a protocol or state in a custom rule. -``` - -### Conntrack ignore rules - -:::{note} -**Important note about conntrack ignore rules:** -Starting from vyos-1.5-rolling-202406120020, ignore rules can be defined in -``set firewall [ipv4 | ipv6] prerouting raw ...``. It's expected that in -the future the conntrack ignore rules will be removed. - -> Customized ignore rules, based on a packet and flow selector. -::: - -```{eval-rst} -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - description -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - destination address -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - destination port -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - inbound-interface -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - protocol -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - source address -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - source port -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - tcp flags [not] - - Allowed values fpr TCP flags: ``ack``, ``cwr``, ``ecn``, ``fin``, ``psh``, - ``rst``, ``syn`` and ``urg``. Multiple values are supported, and for - inverted selection use ``not``, as shown in the example. -``` - -### Conntrack log - -```{eval-rst} -.. cfgcmd:: set system conntrack log event destroy -.. cfgcmd:: set system conntrack log event new -.. cfgcmd:: set system conntrack log event update - - Log the connection tracking events per type. - -.. cfgcmd:: set system conntrack log event destroy icmp -.. cfgcmd:: set system conntrack log event destroy other -.. cfgcmd:: set system conntrack log event destroy tcp -.. cfgcmd:: set system conntrack log event destroy udp -.. cfgcmd:: set system conntrack log event new icmp -.. cfgcmd:: set system conntrack log event new other -.. cfgcmd:: set system conntrack log event new tcp -.. cfgcmd:: set system conntrack log event new udp -.. cfgcmd:: set system conntrack log event update icmp -.. cfgcmd:: set system conntrack log event update other -.. cfgcmd:: set system conntrack log event update tcp -.. cfgcmd:: set system conntrack log event update udp - - Log the connection tracking events per protocol. - -.. cfgcmd:: set system conntrack log timestamp - - Turn on flow-based timestamp extension. - -.. cfgcmd:: set system conntrack log queue-size <100-999999> - - Manage internal queue size, default size is 4096 events. - -.. cfgcmd:: set system conntrack log log-level - - Manage log level -``` \ No newline at end of file diff --git a/docs/configuration/system/console.md b/docs/configuration/system/console.md deleted file mode 100644 index 9017fa30..00000000 --- a/docs/configuration/system/console.md +++ /dev/null @@ -1,59 +0,0 @@ -(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 \ - -Defines the specified device as a system console. Available console devices -can be (see completion helper): -* ``ttySN`` - Serial device name -* ``ttyAMAN``- Serial device name for some arm64 systems -* ``ttyUSBX`` - USB Serial device name -* ``hvc0`` - Xen console -``` - -```{cfgcmd} set system console device \ kernel - -When set, the selected serial console is used as the kernel boot console. -When removed, the kernel boot console falls back to tty0. - -:::{note} -Only one serial console can carry the ``kernel`` option. -When VyOS is installed via serial console, this option is set automatically -for the serial interface used during installation; usually ``ttyS0`` or -``ttyAMA0``. -::: -``` - -```{cfgcmd} set system console device \ 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 -data rate. -::: -``` \ No newline at end of file diff --git a/docs/configuration/system/default-route.md b/docs/configuration/system/default-route.md deleted file mode 100644 index 9f2793d1..00000000 --- a/docs/configuration/system/default-route.md +++ /dev/null @@ -1,40 +0,0 @@ -(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
`), 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 \ - -Specify static route into the routing table sending all non local traffic -to the nexthop 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}`routing-static` -::: diff --git a/docs/configuration/system/flow-accounting.md b/docs/configuration/system/flow-accounting.md deleted file mode 100644 index c97d5473..00000000 --- a/docs/configuration/system/flow-accounting.md +++ /dev/null @@ -1,209 +0,0 @@ -(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 protocol NetFlow (versions 5, 9 and -10/IPFIX). 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 - -:::{warning} -Using NetFlow on routers with high traffic levels may lead to -high CPU usage and may affect the router's performance. In such cases, -consider using sFlow instead. -::: - -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 \ - -Configure and enable collection of flow information for the interface -identified by \. - -You can configure multiple interfaces which would 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 \ - -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 \ - -Set the syslog facility for flow-accounting log messages. Supported values -include ``daemon``, ``local0`` through ``local7``, and other standard syslog -facilities. -``` - - -### 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 \ - -There are multiple versions available for the NetFlow data. The \ -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 \ - -Configure address of NetFlow collector. NetFlow server at \ can -be both listening on an IPv4 or IPv6 address. -``` - -```{cfgcmd} set system flow-accounting netflow source-ip \ - -IPv4 or IPv6 source address of NetFlow packets -``` - -```{cfgcmd} set system flow-accounting netflow engine-id \ - -NetFlow engine-id which will appear in NetFlow data. The range is 0 to 255. -``` - -```{cfgcmd} set system flow-accounting netflow sampling-rate \ - -Use this command to configure the sampling rate for flow accounting. The -system samples one in every \ packets, where \ 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 \ - -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 \ - -If you want to change the maximum number of flows, which are tracking -simultaneously, you may do this with this command (default 8192). -``` - - -### Example: - -NetFlow v5 example: - -```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 \ - -Show flow accounting information for given \. - - -:::{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 \ host \ - -Show flow accounting information for given \ 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 -::: -``` \ No newline at end of file diff --git a/docs/configuration/system/frr.md b/docs/configuration/system/frr.md deleted file mode 100644 index 1741e286..00000000 --- a/docs/configuration/system/frr.md +++ /dev/null @@ -1,45 +0,0 @@ -(system-frr)= - -# FRR - -VyOS uses [FRRouting](https://frrouting.org/) as the control plane for dynamic -and static routing. The routing daemon behavior can be adjusted during runtime, -but requires either a restart of the routing daemon, or a reboot of the system. - -```{cfgcmd} set system frr bmp - -Enable {abbr}`BMP (BGP Monitoring Protocol)` support. -``` - -```{cfgcmd} set system frr descriptors \ - -This allows the operator to control the number of open file descriptors -each daemon is allowed to start with. If the operator plans to run bgp with -several thousands of peers then this is where we would modify FRR to allow -this to happen. -``` - -```{cfgcmd} set system frr irdp - -Enable ICMP Router Discovery Protocol support. -``` - -```{cfgcmd} set system frr profile \ - -Select an FRR profile to adapt its default settings. If unset, the -traditional profile is applied. -``` - -```{cfgcmd} set system frr snmp \ - -Enable SNMP support for an individual routing daemon. - -Supported daemons: -- bgpd -- isisd -- ldpd -- ospf6d -- ospfd -- ripd -- zebra -``` \ No newline at end of file diff --git a/docs/configuration/system/host-name.md b/docs/configuration/system/host-name.md deleted file mode 100644 index 81840d1f..00000000 --- a/docs/configuration/system/host-name.md +++ /dev/null @@ -1,70 +0,0 @@ -(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 \ - - 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 \ - -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. This is the VyOS equivalent to -`/etc/hosts` file entries. - - -:::{note} -Do *not* manually edit `/etc/hosts`. This file will automatically be -regenerated on boot based on the settings in this section, which means you'll -lose all your manual edits. Instead, configure static host mappings as follows. -::: - -```{cfgcmd} set system static-host-mapping host-name \ inet \ - -Create a static hostname mapping which will always resolve the name -`` to IP address `
`. -``` -```{cfgcmd} set system static-host-mapping host-name \ alias \ - -Create named `` for the configured static mapping for ``. -Thus the address configured as {cfgcmd}`set system static-host-mapping -host-name inet
` can be reached via multiple names. - -Multiple aliases can be specified per host-name. -``` \ No newline at end of file diff --git a/docs/configuration/system/index.md b/docs/configuration/system/index.md deleted file mode 100644 index e0b8a5a1..00000000 --- a/docs/configuration/system/index.md +++ /dev/null @@ -1,34 +0,0 @@ -# System - -```{toctree} -:includehidden: true -:maxdepth: 1 - -acceleration -conntrack -console -flow-accounting -frr -host-name -ip -ipv6 -lcd -login -name-server -option -proxy -sflow -syslog -sysctl -task-scheduler -time-zone -updates -watchdog -``` - -```{toctree} -:includehidden: true -:maxdepth: 1 - -default-route -``` diff --git a/docs/configuration/system/ip.md b/docs/configuration/system/ip.md deleted file mode 100644 index 717ee57d..00000000 --- a/docs/configuration/system/ip.md +++ /dev/null @@ -1,126 +0,0 @@ -# IP - -## System configuration commands - -```{cfgcmd} set system ip disable-forwarding - -Use this command to disable IPv4 forwarding on all interfaces. -``` - -```{cfgcmd} set system ip disable-directed-broadcast - -Use this command to disable IPv4 directed broadcast forwarding on all -interfaces. - -If set, IPv4 directed broadcast forwarding will be completely disabled -regardless of whether per-interface directed broadcast forwarding is -enabled or not. -``` - -```{cfgcmd} set system ip arp table-size \ - -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. -``` - -```{cfgcmd} set system ip import-table \ - -Use this command to immport the table, by given table id, into the main RIB. -``` - -```{cfgcmd} set system ip import-table \ distance \ - -Use this command to override the default distance when importing routers -from the alternate table. -``` - -```{cfgcmd} set system ip import-table \ route-map \ - -Use this command to filter routes that are imported into the main table -from alternate table using route-map. -``` - - -### Zebra/Kernel route filtering - -Zebra supports prefix-lists and Route Maps to match routes received from -other FRR components. The permit/deny facilities provided by these commands -can be used to filter which routes zebra will install in the kernel. - -```{cfgcmd} set system ip protocol \ route-map \ - -Apply a route-map filter to routes for the specified protocol. The following -protocols can be used: any, babel, bgp, eigrp, isis, ospf, rip, static - -:::{note} -If you choose any as the option that will cause all protocols that -are sending routes to zebra. -::: -``` - - -### Nexthop Tracking - -Nexthop tracking resolve nexthops via the default route by default. This is enabled -by default for a traditional profile of FRR which we use. It and can be disabled if -you do not want to e.g. allow BGP to peer across the default route. - -```{cfgcmd} set system ip nht no-resolve-via-default - -Do not allow IPv4 nexthop tracking to resolve via the default route. This -parameter is configured per-VRF, so the command is also available in the VRF -subnode. -``` - - -## Operational commands - -### show commands - -See below the different parameters available for the IPv4 **show** command: - -```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: - -```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 -``` diff --git a/docs/configuration/system/ipv6.md b/docs/configuration/system/ipv6.md deleted file mode 100644 index ee0a6ade..00000000 --- a/docs/configuration/system/ipv6.md +++ /dev/null @@ -1,193 +0,0 @@ -# IPv6 - -## System configuration commands - -```{cfgcmd} set system ipv6 disable-forwarding - - Use this command to disable IPv6 forwarding on all interfaces. -``` - - -```{cfgcmd} set system ipv6 neighbor table-size \ - -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. -``` - -### Zebra/Kernel route filtering - - -Zebra supports prefix-lists and Route Maps to match routes received from -other FRR components. The permit/deny facilities provided by these commands -can be used to filter which routes zebra will install in the kernel. - -```{cfgcmd} set system ipv6 protocol \ route-map \ - -Apply a route-map filter to routes for the specified protocol. The following -protocols can be used: any, babel, bgp, isis, ospfv3, ripng, static - -:::{note} -If you choose any as the option that will cause all protocols that -are sending routes to zebra. -::: -``` - -### Nexthop Tracking - - -Nexthop tracking resolve nexthops via the default route by default. This is enabled -by default for a traditional profile of FRR which we use. It and can be disabled if -you do not want to e.g. allow BGP to peer across the default route. - -```{cfgcmd} set system ipv6 nht no-resolve-via-default - -Do not allow IPv6 nexthop tracking to resolve via the default route. This -parameter is configured per-VRF, so the command is also available in the VRF -subnode. -``` - -## 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: - Execute the current command - Show IPv6 routes of given address or prefix - - 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 - tag Show only routes with tag - 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: - Execute the current command - 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: - Execute the current command - Show specified IPv6 access-list -::: -``` -```{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: - 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 bgp ipv6 \ - -Use this command to clear Border Gateway Protocol statistics or -status. -``` -```{opcmd} reset ipv6 neighbors \
- -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.md b/docs/configuration/system/lcd.md deleted file mode 100644 index ef9031ea..00000000 --- a/docs/configuration/system/lcd.md +++ /dev/null @@ -1,41 +0,0 @@ -(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 \ - -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 refer to the USB hardware section. -``` - -```{cfgcmd} set system lcd 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. -::: -``` - diff --git a/docs/configuration/system/login.md b/docs/configuration/system/login.md deleted file mode 100644 index 288d30a8..00000000 --- a/docs/configuration/system/login.md +++ /dev/null @@ -1,604 +0,0 @@ ---- -lastproofread: '2026-01-12' ---- - -(user-management)= - -# Login/user management - -The default VyOS user account (`vyos`), as well as newly created user accounts, -possess full system configuration privileges. These accounts are granted sudo -privileges, allowing them to execute commands as the root user. - -VyOS supports both local authentication and remote authentication via -{abbr}`RADIUS (Remote Authentication Dial-In User Service)`/ {abbr}`TACACS+ -(Terminal Access Controller Access-Control System)`. - -## Local authentication - -```{cfgcmd} set system login user \ full-name "\" - -**Configure the real name or description for a system user.** - -If the description includes spaces, enclose ```` in double quotes. - -If the user ```` already exists, the command updates the current -description. If not, it creates a new user with the specified description. -``` - -```{cfgcmd} set system login user \ authentication plaintext-password \ - -**Configure a password for a system user.** - -Enter the password in plaintext. Upon ``commit``, VyOS hashes the password for -secure storage and removes the plaintext value. - -If the user ```` already exists, the command updates the current password. -If not, it creates a new user with the specified plaintext password. -``` - -```{cfgcmd} set system login user \ authentication encrypted-password \ - -**Configure a pre-encrypted password for a system user.** - -Enter the password in its hashed format. Upon ``commit``, VyOS stores this value -directly without modification. - -If the user ```` already exists, the command updates the current password. -If not, it creates a new user with the specified pre-encrypted password. -``` - -```{cfgcmd} set system login user \ authentication principal \ - -**Configure an SSH certificate principal for a system user.** - -Enter the principal (a string included in the user's signed SSH certificate). -Upon ``commit``, VyOS stores this mapping, allowing the user to log in if the -certificate they present contains this principal. - -If the user ```` already exists, the command updates the principal. If not, -it creates a new user linked to the specified principal. - -**If not configured**, the principal defaults to ````. -``` - -```{cfgcmd} set system login user \ disable - -**Disable a system user account.** - -VyOS locks the account, preventing the user from logging in. -``` - -(ssh_key_based_authentication)= - -## Key-based authentication - -Key-based authentication is the recommended method for securing SSH access in -VyOS. It uses a **public/private key pair** to verify user identity without -requiring a password. To authorize access, you assign **SSH public keys** to -user accounts on the router, while SSH private keys remain on local devices. -VyOS allows assigning multiple SSH public keys to a single user account, which -is useful for accessing a router from different devices. - -### Generate the key pair - -Generate an SSH key pair on your **local machine** using the `ssh-keygen` -command. This creates two files: -- **Private key** (e.g., `id_rsa`): Remains on your local machine and must - never be shared. -- **Public key** (e.g., `id_rsa.pub`): Is used to configure the VyOS user - account. By default, it is saved to `~/.ssh/id_rsa.pub`. - -Each SSH public key consists of three parts, separated by spaces: -- **Encryption algorithm type:** `ssh-rsa`, `ssh-ed25519`, etc. -- **Key:** The actual data (a long string beginning with `AAAA...`). -- **Comment:** An identifier for your reference (e.g., `user@host`). - -Only the encryption algorithm type and key parts are required to -configure the authorization entry in VyOS. The comment part is optional. - -:::{seealso} -{ref}`SSH operation ` -::: - -:::{warning} -SSH key strings are long. When copying and pasting, ensure your -terminal does not insert line breaks. The key must be entered as a **single -line** to function correctly. -::: - -### Configure the router - -To configure SSH public key authentication for a user account, run the -following two commands using the same ``: - -```{cfgcmd} set system login user \ authentication public-keys \ key \ - -**Configure the SSH public key for the user account.** -* ````: A unique label that identifies this specific key entry. -* ````: The actual string of characters from your public key. -``` - -```{cfgcmd} set system login user \ authentication public-keys \ type \ - -**Configure the SSH key's encryption type.** - -The following encryption algorithm types are available: - -* ``ecdsa-sha2-nistp256`` -* ``ecdsa-sha2-nistp384`` -* ``ecdsa-sha2-nistp521`` -* ``ssh-dss`` -* ``ssh-ed25519`` -* ``ssh-rsa`` - -:::{note} -To assign multiple SSH public keys to a user account, repeat the -commands above with a unique identifier for each key. -::: -``` - -```{cfgcmd} set system login user \ authentication public-keys \ options \ - -**Configure specific restrictions or behaviors for an SSH public key.** - -````: A string of comma-separated values that define permissions -or restrictions for this key. - -The command accepts standard OpenSSH options listed in the router's -``~/.ssh/authorized_keys`` file. - -To include a ``"`` character in the options string, use ``"``. - -For example, to restrict allowed source IP addresses for an SSH public key, -use: ``from="10.0.0.0/24"``. -``` - - -## OTP-based MFA - -VyOS lets you enhance user access security by enabling {abbr}`OTP (One-time -password)`-based {abbr}`MFA (Multi-factor Authentication)` for individual -users. Users with {abbr}`OTP (One-time password)`-based {abbr}`MFA -(Multi-factor Authentication)` must enter a valid {abbr}`OTP (One-time -password)` along with their password at login. Users without {abbr}`OTP -(One-time password)`-based {abbr}`MFA (Multi-factor Authentication)` use -standard authentication. - -```{cfgcmd} set system login user \ authentication otp key \ - -**Configure** {abbr}`OTP (One-time password)`**-based** {abbr}`MFA -(Multi-factor Authentication)` **for a user.** - -````: A Base32-encoded secret key. This key must be added to the user's -authenticator app to generate valid {abbr}`OTPs (One-time passwords)`. - -**When configured**, the user is required to enter their password followed by -a valid OTP for all subsequent logins. -``` - - -### OTP settings - -```{cfgcmd} set system login user \ authentication otp rate-limit \ - -**Configure the number of** {abbr}`OTP (One-time password)` **authentication -attempts allowed within a specified time period.** - -If this limit is exceeded, the user is temporarily blocked. - -The default value is 3 attempts. The valid range is 1 to 10 attempts. -``` - -```{cfgcmd} set system login user \ authentication otp rate-time \ - -**Configure the time period, in seconds, for tracking** {abbr}`OTP (One-time -password)` **authentication attempts.** - -The default value is 30 seconds. The valid range is 1 to 600 seconds. -``` - -```{cfgcmd} set system login user \ authentication otp window-size \ - -**Configure the** {abbr}`OTP (One-time password)` **window size for a user.** - -The {abbr}`OTP (One-time password)` window size defines the number of -concurrently valid {abbr}`OTPs (One-time passwords)` that the authentication -server accepts. This setting assumes a new token is generated every 30 seconds. - -The default value is 3. This permits 3 concurrent codes: the code for the -current 30-second interval, the preceding code, and the following code. This -allows up to 30 seconds of time skew between the authentication server and -client. - -If the window size is increased to 17, the system permits 17 concurrent codes -(the current code, the 8 preceding codes, and the 8 following codes). This -allows for a time skew of up to 4 minutes. - -The valid range is 1 to 21. -``` - - -### Generate an OTP-key - -Use the following command to generate an OTP key: - -```{cfgcmd} generate system login username \ otp-key hotp-time rate-limit \<1-10\> rate-time \<15-600\> window-size \<1-21\> -``` - -Key generation example: - -```none -vyos@vyos:~$ generate system login username otptester otp-key hotp-time rate-limit 2 rate-time 20 window-size 5 -# You can share it with the user, he just needs to scan the QR in his OTP app -# username: otptester -# OTP KEY: J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY -# OTP URL: otpauth://totp/otptester@vyos?secret=J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY&digits=6&period=30 -โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆ โ–„โ–„โ–„โ–„โ–„ โ–ˆโ–€โ–ˆ โ–ˆโ–„ โ–€โ–„โ–€โ–„โ–ˆโ–€โ–„ โ–€โ–ˆโ–€ โ–ˆ โ–„โ–„โ–„โ–„โ–„ โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆ โ–ˆ โ–ˆโ–€โ–€โ–€โ–ˆ โ–„โ–€ โ–ˆโ–„โ–€ โ–€โ–„ โ–„ โ–€ โ–„โ–ˆ โ–ˆ โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–„โ–„โ–„โ–ˆ โ–ˆโ–€ โ–ˆโ–€โ–€โ–ˆโ–ˆโ–„โ–„ โ–ˆ โ–ˆ โ–ˆโ–ˆ โ–€โ–„โ–€ โ–ˆ โ–ˆโ–„โ–„โ–„โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–ˆโ–„โ–€ โ–€โ–„โ–ˆ โ–ˆ โ–€ โ–ˆ โ–ˆ โ–ˆ โ–ˆโ–„โ–ˆโ–„โ–ˆโ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆ โ–„ โ–ˆโ–„ โ–„ โ–€โ–„โ–€โ–€โ–€โ–€โ–„โ–€โ–„โ–€โ–„โ–„โ–„โ–€โ–€โ–„โ–„โ–„ โ–ˆ โ–ˆโ–„โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–„ โ–ˆโ–ˆโ–€โ–„โ–„โ–„โ–€โ–€โ–ˆโ–€ โ–„ โ–„โ–„โ–„ โ–„โ–€ โ–€ โ–ˆ โ–„ โ–„ โ–ˆโ–ˆโ–„โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–„ โ–ˆโ–ˆโ–„โ–„โ–€โ–ˆโ–„โ–ˆโ–„โ–ˆโ–„ โ–€โ–ˆโ–„โ–€โ–„ โ–€โ–ˆโ–€โ–„ โ–ˆโ–„โ–„โ–„ โ–„ โ–„โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–€โ–€โ–„ โ–„โ–ˆโ–€โ–„โ–€ โ–„โ–ˆโ–€โ–ˆโ–€โ–„โ–„โ–„โ–€โ–ˆโ–„ โ–ˆโ–ˆโ–„โ–„โ–„ โ–€โ–ˆ โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆ โ–„โ–€โ–„โ–ˆโ–€โ–„โ–„โ–ˆโ–€โ–€โ–„โ–€โ–€โ–€โ–€โ–ˆ โ–„โ–€โ–„โ–€ โ–„โ–ˆ โ–€โ–„ โ–„ โ–„โ–€ โ–ˆโ–„โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–„ โ–ˆโ–ˆ โ–€โ–„โ–€โ–€ โ–„โ–ˆโ–€ โ–„ โ–ˆโ–ˆ โ–€โ–ˆโ–„โ–ˆ โ–„โ–ˆ โ–„ โ–€โ–„ โ–„โ–„ โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–ˆโ–€โ–€โ–„ โ–„โ–„ โ–ˆโ–„โ–ˆโ–„โ–ˆโ–„ โ–ˆโ–„โ–„โ–€โ–„โ–„โ–€โ–€โ–„โ–„โ–ˆโ–ˆโ–€ โ–„โ–€โ–„โ–„ โ–€โ–„โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–€โ–„โ–€ โ–„ โ–„โ–€โ–ˆ โ–„ โ–„โ–ˆโ–€ โ–ˆ โ–€โ–„โ–„ โ–„โ–ˆโ–€ โ–„โ–„ โ–€โ–„โ–„ โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆ โ–€โ–ˆโ–ˆโ–ˆโ–„ โ–ˆโ–„โ–ˆโ–„โ–€โ–€โ–€โ–€โ–„ โ–„โ–ˆโ–„โ–„โ–€ โ–€โ–ˆโ–ˆโ–ˆ โ–„โ–„โ–ˆโ–„โ–„ โ–„โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–€ โ–„โ–„โ–€โ–€โ–ˆโ–ˆโ–€ โ–„โ–€โ–„โ–ˆโ–„โ–„โ–„ โ–ˆโ–ˆโ–„โ–„โ–€โ–„โ–€ โ–ˆโ–ˆโ–ˆโ–„ โ–„โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–„โ–„โ–€โ–„ โ–ˆโ–„โ–ˆโ–„โ–€โ–„โ–„โ–„โ–„โ–ˆโ–ˆโ–€ โ–„โ–€ โ–„ โ–„โ–„โ–„ โ–ˆโ–„โ–„โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆ โ–„โ–„โ–„โ–„โ–„ โ–ˆโ–„โ–„โ–„ โ–„โ–ˆโ–€โ–ˆโ–€โ–€โ–€โ–€โ–ˆโ–€โ–ˆโ–€ โ–ˆโ–„โ–ˆ โ–ˆโ–„โ–ˆ โ–„โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆ โ–ˆ โ–ˆ โ–ˆโ–ˆโ–„โ–€โ–€โ–€โ–€โ–„โ–„โ–„โ–€ โ–„โ–„โ–„ โ–€ โ–„ โ–„ โ–„โ–„โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–„โ–„โ–„โ–ˆ โ–ˆ โ–€โ–€โ–ˆโ–€ โ–„โ–„โ–ˆ โ–ˆโ–„โ–„โ–ˆโ–ˆโ–€โ–€โ–ˆโ–€ โ–ˆโ–„โ–€โ–„โ–ˆโ–ˆโ–„โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–ˆโ–„โ–ˆโ–„โ–ˆโ–„โ–ˆโ–„โ–„โ–„โ–„โ–„โ–ˆโ–„โ–„โ–„โ–ˆโ–„โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–ˆโ–ˆโ–„โ–„โ–„โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ -# To add this OTP key to configuration, run the following commands: -set system login user otptester authentication otp key 'J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY' -set system login user otptester authentication otp rate-limit '2' -set system login user otptester authentication otp rate-time '20' -set system login user otptester authentication otp window-size '5' -``` - -### Display the OTP key for a user - -Use the following command to display the {abbr}`OTP (One-time password)` -key for a user: - -```{cfgcmd} sh system login authentication user \ otp \ -``` - -Example: - -```none -vyos@vyos:~$ sh system login authentication user otptester otp full -# You can share the OTP key with the user. They just need to scan the QR in their OTP app. -# username: otptester -# OTP KEY: J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY -# OTP URL: otpauth://totp/otptester@vyos?secret=J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY&digits=6&period=30 -โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆ โ–„โ–„โ–„โ–„โ–„ โ–ˆโ–€โ–ˆ โ–ˆโ–„ โ–€โ–„โ–€โ–„โ–ˆโ–€โ–„ โ–€โ–ˆโ–€ โ–ˆ โ–„โ–„โ–„โ–„โ–„ โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆ โ–ˆ โ–ˆโ–€โ–€โ–€โ–ˆ โ–„โ–€ โ–ˆโ–„โ–€ โ–€โ–„ โ–„ โ–€ โ–„โ–ˆ โ–ˆ โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–„โ–„โ–„โ–ˆ โ–ˆโ–€ โ–ˆโ–€โ–€โ–ˆโ–ˆโ–„โ–„ โ–ˆ โ–ˆ โ–ˆโ–ˆ โ–€โ–„โ–€ โ–ˆ โ–ˆโ–„โ–„โ–„โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–ˆโ–„โ–€ โ–€โ–„โ–ˆ โ–ˆ โ–€ โ–ˆ โ–ˆ โ–ˆ โ–ˆโ–„โ–ˆโ–„โ–ˆโ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆ โ–„ โ–ˆโ–„ โ–„ โ–€โ–„โ–€โ–€โ–€โ–€โ–„โ–€โ–„โ–€โ–„โ–„โ–„โ–€โ–€โ–„โ–„โ–„ โ–ˆ โ–ˆโ–„โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–„ โ–ˆโ–ˆโ–€โ–„โ–„โ–„โ–€โ–€โ–ˆโ–€ โ–„ โ–„โ–„โ–„ โ–„โ–€ โ–€ โ–ˆ โ–„ โ–„ โ–ˆโ–ˆโ–„โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–„ โ–ˆโ–ˆโ–„โ–„โ–€โ–ˆโ–„โ–ˆโ–„โ–ˆโ–„ โ–€โ–ˆโ–„โ–€โ–„ โ–€โ–ˆโ–€โ–„ โ–ˆโ–„โ–„โ–„ โ–„ โ–„โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–€โ–€โ–„ โ–„โ–ˆโ–€โ–„โ–€ โ–„โ–ˆโ–€โ–ˆโ–€โ–„โ–„โ–„โ–€โ–ˆโ–„ โ–ˆโ–ˆโ–„โ–„โ–„ โ–€โ–ˆ โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆ โ–„โ–€โ–„โ–ˆโ–€โ–„โ–„โ–ˆโ–€โ–€โ–„โ–€โ–€โ–€โ–€โ–ˆ โ–„โ–€โ–„โ–€ โ–„โ–ˆ โ–€โ–„ โ–„ โ–„โ–€ โ–ˆโ–„โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–„ โ–ˆโ–ˆ โ–€โ–„โ–€โ–€ โ–„โ–ˆโ–€ โ–„ โ–ˆโ–ˆ โ–€โ–ˆโ–„โ–ˆ โ–„โ–ˆ โ–„ โ–€โ–„ โ–„โ–„ โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–ˆโ–€โ–€โ–„ โ–„โ–„ โ–ˆโ–„โ–ˆโ–„โ–ˆโ–„ โ–ˆโ–„โ–„โ–€โ–„โ–„โ–€โ–€โ–„โ–„โ–ˆโ–ˆโ–€ โ–„โ–€โ–„โ–„ โ–€โ–„โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–€โ–„โ–€ โ–„ โ–„โ–€โ–ˆ โ–„ โ–„โ–ˆโ–€ โ–ˆ โ–€โ–„โ–„ โ–„โ–ˆโ–€ โ–„โ–„ โ–€โ–„โ–„ โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆ โ–€โ–ˆโ–ˆโ–ˆโ–„ โ–ˆโ–„โ–ˆโ–„โ–€โ–€โ–€โ–€โ–„ โ–„โ–ˆโ–„โ–„โ–€ โ–€โ–ˆโ–ˆโ–ˆ โ–„โ–„โ–ˆโ–„โ–„ โ–„โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–€ โ–„โ–„โ–€โ–€โ–ˆโ–ˆโ–€ โ–„โ–€โ–„โ–ˆโ–„โ–„โ–„ โ–ˆโ–ˆโ–„โ–„โ–€โ–„โ–€ โ–ˆโ–ˆโ–ˆโ–„ โ–„โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–„โ–„โ–€โ–„ โ–ˆโ–„โ–ˆโ–„โ–€โ–„โ–„โ–„โ–„โ–ˆโ–ˆโ–€ โ–„โ–€ โ–„ โ–„โ–„โ–„ โ–ˆโ–„โ–„โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆ โ–„โ–„โ–„โ–„โ–„ โ–ˆโ–„โ–„โ–„ โ–„โ–ˆโ–€โ–ˆโ–€โ–€โ–€โ–€โ–ˆโ–€โ–ˆโ–€ โ–ˆโ–„โ–ˆ โ–ˆโ–„โ–ˆ โ–„โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆ โ–ˆ โ–ˆ โ–ˆโ–ˆโ–„โ–€โ–€โ–€โ–€โ–„โ–„โ–„โ–€ โ–„โ–„โ–„ โ–€ โ–„ โ–„ โ–„โ–„โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–„โ–„โ–„โ–ˆ โ–ˆ โ–€โ–€โ–ˆโ–€ โ–„โ–„โ–ˆ โ–ˆโ–„โ–„โ–ˆโ–ˆโ–€โ–€โ–ˆโ–€ โ–ˆโ–„โ–€โ–„โ–ˆโ–ˆโ–„โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–ˆโ–„โ–ˆโ–„โ–ˆโ–„โ–ˆโ–„โ–„โ–„โ–„โ–„โ–ˆโ–„โ–„โ–„โ–ˆโ–„โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–ˆโ–ˆโ–„โ–„โ–„โ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ -โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ -# To add this OTP key to configuration, run the following commands: -set system login user otptester authentication otp key 'J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY' -set system login user otptester authentication otp rate-limit '2' -set system login user otptester authentication otp rate-time '20' -set system login user otptester authentication otp window-size '5' -``` - -Once {abbr}`OTP (One-time password)`-based {abbr}`MFA (Multi-factor -Authentication)` is configured for a user account, this user must enter their -standard password followed by the current 6-digit OTP code at login. For -example, if the user's password is `vyosrocks` and the OTP is `817454`, they -should enter `vyosrocks817454`. - -## RADIUS authentication - -For large-scale deployments, managing individual user accounts across multiple -VyOS instances is inefficient. VyOS supports centralized authentication via -{abbr}`RADIUS (Remote Authentication Dial-In User Service)`, consolidating user -account management on a single backend server. - -### Configuration - -```{cfgcmd} set system login radius server \ key \ - -**Configure the** {abbr}`RADIUS (Remote Authentication Dial-In User Service)` -**server's IP address and shared secret.** - -The shared secret is used to verify the router's identity and to encrypt user -passwords during authentication. - -You can configure multiple {abbr}`RADIUS (Remote Authentication Dial-In User -Service)` servers. -``` - -```{cfgcmd} set system login radius server \ port \ - -**Configure the UDP port for communication with the** {abbr}`RADIUS (Remote -Authentication Dial-In User Service)` **server.** - -The default port is 1812. -``` - -```{cfgcmd} set system login radius server \ disable - -**Disable a** {abbr}`RADIUS (Remote Authentication Dial-In User Service)` -**server from the authentication process.** - -Disabling a specific {abbr}`RADIUS (Remote Authentication Dial-In User -Service)` server doesnโ€™t remove its configuration settings (the serverโ€™s IP -address and shared secret). -``` - -```{cfgcmd} set system login radius server \ timeout \ - -Configure the duration, in seconds, that the VyOS router waits for a -response from the {abbr}`RADIUS (Remote Authentication Dial-In User Service)` -server after sending an authentication request. - -If the server does not respond within this timeframe, the VyOS router tries to -connect to another configured server or falls back to local authentication. -``` - -```{cfgcmd} set system login radius source-address \ - -**Configure the source IP address the router uses for** {abbr}`RADIUS (Remote -Authentication Dial-In User Service)` **authentication requests.** - -A consistent source IP address is recommended as RADIUS servers typically -accept requests only from known, trusted IP addresses. - -If not explicitly defined, the router uses the current egress interface -address, which may change (e.g., due to a link outage), causing authentication -failures. -``` - -```{cfgcmd} set system login radius vrf \ - -**Configure the router to send all** {abbr}`RADIUS (Remote Authentication -Dial-In User Service)` **authentication requests via a specific VRF.** - -By default, {abbr}`RADIUS (Remote Authentication Dial-In User Service)` -authentication requests are sent via the global routing table. -``` - -### Configuration example - -```none -set system login radius server 192.168.0.2 key 'test-vyos' -set system login radius server 192.168.0.2 port '1812' -set system login radius server 192.168.0.2 timeout '5' -set system login radius source-address '192.168.0.1' -``` - -If communication with the {abbr}`RADIUS (Remote Authentication Dial-In User -Service)` server fails, the router falls back to local user authentication. -During this process, users may experience a login delay while the system waits -for the {abbr}`RADIUS (Remote Authentication Dial-In User Service)` request to -time out. This delay depends on the configured timeout value. - -:::{hint} -To grant administrative privileges to {abbr}`RADIUS (Remote -Authentication Dial-In User Service)`-authenticated users, the server must -return the Cisco-AV-Pair attribute set to `shell:priv-lvl=15`. Otherwise, users -receive standard privileges and cannot perform configuration tasks. -::: - -## TACACS+ authentication - -In addition to {abbr}`RADIUS (Remote Authentication Dial-In User Service)`, -VyOS supports {abbr}`TACACS+ (Terminal Access Controller Access Control -System)`, which is commonly used in large enterprise environments. - -Unlike {abbr}`RADIUS (Remote Authentication Dial-In User Service)`, -{abbr}`TACACS+ (Terminal Access Controller Access Control System)` separates -Authentication, Authorization, and Accounting (AAA) into independent processes -and encrypts the entire packet body for enhanced security. - -{abbr}`TACACS+ (Terminal Access Controller Access Control System)` is defined -in {rfc}`8907`. -(tacacs-configuration)= - -### Configuration - -```{cfgcmd} set system login tacacs server \ key \ - -**Configure the** {abbr}`TACACS+ (Terminal Access Controller Access Control -System)` **server IP address and shared secret.** - -Unlike {abbr}`RADIUS (Remote Authentication Dial-In User Service)`, which -encrypts only passwords, {abbr}`TACACS+ (Terminal Access Controller Access -Control System)` encrypts the entire packet body for enhanced security. - -You can configure multiple {abbr}`TACACS+ (Terminal Access Controller Access -Control System)` servers. -``` - -```{cfgcmd} set system login tacacs server \ port \ - -**Configure the TCP port for communication with the** {abbr}`TACACS+ (Terminal -Access Controller Access Control System)` **server.** - -The default port is 49. -``` - -```{cfgcmd} set system login tacacs server \ disable - -**Disable a** {abbr}`TACACS+ (Terminal Access Controller Access Control -System)` **server from the authentication process.** - -Disabling a specific {abbr}`TACACS+ (Terminal Access Controller Access Control -System)` server doesnโ€™t remove its configuration settings (the serverโ€™s IP -address and shared secret). -``` - -```{cfgcmd} set system login tacacs server \ timeout \ - -Configure the duration, in seconds, that the VyOS router waits for a -response from the {abbr}`TACACS+ (Terminal Access Controller Access -Control System)` server after sending an authentication request. - -If the server does not respond within this timeframe, the VyOS router tries -to connect to another configured server or falls back to local authentication. -``` - -```{cfgcmd} set system login tacacs source-address \ - -**Configure the source IP address the router uses for** -{abbr}`TACACS+ (Terminal Access Controller Access Control System)` -**authentication requests.** - -A consistent source IP address is recommended as {abbr}`TACACS+ (Terminal -Access Controller Access Control System)` servers typically accept requests -only from known, trusted IP addresses. - -If not explicitly defined, the router uses the current egress interface address, -which may change (e.g., due to a link outage), causing authentication failures. -``` - -```{cfgcmd} set system login tacacs vrf \ - -Configure the router to send all {abbr}`TACACS+ (Terminal Access Controller -Access Control System)` authentication requests via a specific VRF. - -By default, {abbr}`TACACS+ (Terminal Access Controller Access Control System)` -authentication requests are sent via the global routing table. -``` - -(login-tacacs-example)= - -### Configuration example - -```none -set system login tacacs server 192.168.0.2 key 'test-vyos' -set system login tacacs server 192.168.0.2 port '49' -set system login tacacs source-address '192.168.0.1' -``` - -If communication with the {abbr}`TACACS+ (Terminal Access Controller Access -Control System)` server fails, the router falls back to local user -authentication. - -## Login banners - -VyOS allows you to configure **pre-login** and **post-login** banners. -Pre-login banners are typically used for system identification, legal disclaimers, or security warnings -displayed before authentication, while post-login banners provide system -information or operational notices to users after login. - -```{cfgcmd} set system login banner pre-login \ - -Configure a message to be shown to users before the ``username`` and ``password`` -prompts appear. -``` - -```{cfgcmd} set system login banner post-login \ - -Configure a message to be shown to users after successful authentication. -``` -:::{note} -Use `\\n` to insert line breaks in multi-line banner messages. -::: - -## Login session limits - -```{cfgcmd} set system login max-login-session \ - -**Configure the maximum number of concurrent login sessions.** -``` -:::{note} -If you limit concurrent login sessions, you must also configure a -session ``. This clears inactive sessions and prevents blocking new -login attempts. -::: -```{cfgcmd} set system login timeout \ - -**Configure the login session timeout, in seconds.** - -Idle login sessions are terminated after this period. -``` - -## Configuration examples - -Example 1: Multi-key SSH with MFA and source restrictions - -In this configuration, `User1` and `User2` both use the vyos user account, -each with a unique SSH key. `User1` is restricted to authentication from a -single IP address. - -For both users, password-based logins require {abbr}`OTP (One-time password)` --based {abbr}`MFA (Multi-factor Authentication)`. - -```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 'User1' options "from="192.168.0.100"" - -set system login user vyos authentication public-keys 'User2' key "AAAAQ39x...fbV3" -set system login user vyos authentication public-keys 'User2' type ssh-rsa - -set system login user vyos authentication otp key OHZ3OJ7U2N25BK4G7SOFFJTZDTCFUUE2 -set system login user vyos authentication plaintext-password vyos -``` - -Example 2: Containerized {abbr}`TACACS+ (Terminal Access Controller Access Control System)` -deployment with redundancy. - -In this configuration, the VyOS router hosts its own authentication -infrastructure using two containerized {abbr}`TACACS+ (Terminal Access -Controller Access Control System)` servers (`tacacs1` and `tacacs2`) on a -private network for redundancy. - -System logins are authenticated against credentials stored within these internal -containers rather than the router's local user database. - -First, download the image in operational mode: - -```none -add container image lfkeitel/tacacs_plus:latest -``` - -Next, configure the containers in configuration mode: - -```none -set container network tac-test prefix '100.64.0.0/24' - -set container name tacacs1 image 'lfkeitel/tacacs_plus:latest' -set container name tacacs1 network tac-test address '100.64.0.11' - -set container name tacacs2 image 'lfkeitel/tacacs_plus:latest' -set container name tacacs2 network tac-test address '100.64.0.12' - -set system login tacacs server 100.64.0.11 key 'tac_plus_key' -set system login tacacs server 100.64.0.12 key 'tac_plus_key' - -commit -``` - -You can now log in via SSH or console using `admin/admin` credentials supplied -by the container image. diff --git a/docs/configuration/system/md-acceleration.md b/docs/configuration/system/md-acceleration.md new file mode 100644 index 00000000..871129e6 --- /dev/null +++ b/docs/configuration/system/md-acceleration.md @@ -0,0 +1,158 @@ +(acceleration)= + +# Acceleration + +In this command tree, all hardware acceleration options will be handled. +At the moment only [Intelยฎ QAT] is supported + +## Intelยฎ QAT + +```{opcmd} show system acceleration qat + +use this command to check if there is an Intelยฎ QAT supported Processor in your system. + +:::{code-block} none +vyos@vyos:~$ show system acceleration qat +01:00.0 Co-processor [0b40]: Intel Corporation Atom Processor C3000 Series QuickAssist Technology [8086:19e2] (rev 11) +::: + +if there is non device the command will show `` `No QAT device found` `` +``` + +```{cfgcmd} set system acceleration qat + +if there is a supported device, enable Intelยฎ QAT +``` + + +```{opcmd} show system acceleration qat status + +Check if the Intelยฎ QAT device is up and ready to do the job. + +:::{code-block} none +vyos@vyos:~$ show system acceleration qat status +Checking status of all devices. +There is 1 QAT acceleration device(s) in the system: +qat_dev0 - type: c3xxx, inst_id: 0, node_id: 0, bsf: 0000:01:00.0, #accel: 3 #engines: 6 state: up +::: +``` + + +### Operation Mode + +```{opcmd} show system acceleration qat device \ config + +Show the full config uploaded to the QAT device. +``` + + +```{opcmd} show system acceleration qat device \ flows + +Get an overview over the encryption counters. +``` + + +```{opcmd} show system acceleration qat interrupts + +Show binded qat device interrupts to certain core. +``` + + +### Example + +Let's build a simple VPN between 2 Intelยฎ QAT ready devices. + +Side A: + +``` +set interfaces vti vti1 address '192.168.1.2/24' +set vpn ipsec authentication psk right id '10.10.10.2' +set vpn ipsec authentication psk right id '10.10.10.1' +set vpn ipsec authentication psk right secret 'Qwerty123' +set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes256' +set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha256' +set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '14' +set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes256' +set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha256' +set vpn ipsec interface 'eth0' +set vpn ipsec site-to-site peer right authentication local-id '10.10.10.2' +set vpn ipsec site-to-site peer right authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer right authentication remote-id '10.10.10.1' +set vpn ipsec site-to-site peer right connection-type 'initiate' +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 '10.10.10.2' +set vpn ipsec site-to-site peer right remote-address '10.10.10.1' +set vpn ipsec site-to-site peer right vti bind 'vti1' +``` + +Side B: + +``` +set interfaces vti vti1 address '192.168.1.1/24' +set vpn ipsec authentication psk left id '10.10.10.2' +set vpn ipsec authentication psk left id '10.10.10.1' +set vpn ipsec authentication psk left secret 'Qwerty123' +set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes256' +set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha256' +set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '14' +set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes256' +set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha256' +set vpn ipsec interface 'eth0' +set vpn ipsec site-to-site peer left authentication local-id '10.10.10.1' +set vpn ipsec site-to-site peer left authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer left authentication remote-id '10.10.10.2' +set vpn ipsec site-to-site peer left connection-type 'initiate' +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 '10.10.10.1' +set vpn ipsec site-to-site peer left remote-address '10.10.10.2' +set vpn ipsec site-to-site peer left vti bind 'vti1' +``` + +a bandwidth test over the VPN got these results: + +``` +Connecting to host 192.168.1.2, port 5201 +[ 9] local 192.168.1.1 port 51344 connected to 192.168.1.2 port 5201 +[ ID] Interval Transfer Bitrate Retr Cwnd +[ 9] 0.00-1.01 sec 32.3 MBytes 268 Mbits/sec 0 196 KBytes +[ 9] 1.01-2.03 sec 32.5 MBytes 268 Mbits/sec 0 208 KBytes +[ 9] 2.03-3.03 sec 32.5 MBytes 271 Mbits/sec 0 208 KBytes +[ 9] 3.03-4.04 sec 32.5 MBytes 272 Mbits/sec 0 208 KBytes +[ 9] 4.04-5.00 sec 31.2 MBytes 272 Mbits/sec 0 208 KBytes +[ 9] 5.00-6.01 sec 32.5 MBytes 272 Mbits/sec 0 234 KBytes +[ 9] 6.01-7.04 sec 32.5 MBytes 265 Mbits/sec 0 234 KBytes +[ 9] 7.04-8.04 sec 32.5 MBytes 272 Mbits/sec 0 234 KBytes +[ 9] 8.04-9.04 sec 32.5 MBytes 273 Mbits/sec 0 336 KBytes +[ 9] 9.04-10.00 sec 31.2 MBytes 272 Mbits/sec 0 336 KBytes +- - - - - - - - - - - - - - - - - - - - - - - - - +[ ID] Interval Transfer Bitrate Retr +[ 9] 0.00-10.00 sec 322 MBytes 270 Mbits/sec 0 sender +[ 9] 0.00-10.00 sec 322 MBytes 270 Mbits/sec receiver +``` + +with {cfgcmd}`set system acceleration qat` on both systems the bandwidth +increases. + +``` +Connecting to host 192.168.1.2, port 5201 +[ 9] local 192.168.1.1 port 51340 connected to 192.168.1.2 port 5201 +[ ID] Interval Transfer Bitrate Retr Cwnd +[ 9] 0.00-1.00 sec 97.3 MBytes 817 Mbits/sec 0 1000 KBytes +[ 9] 1.00-2.00 sec 92.5 MBytes 776 Mbits/sec 0 1.07 MBytes +[ 9] 2.00-3.00 sec 92.5 MBytes 776 Mbits/sec 0 820 KBytes +[ 9] 3.00-4.00 sec 92.5 MBytes 776 Mbits/sec 0 899 KBytes +[ 9] 4.00-5.00 sec 91.2 MBytes 765 Mbits/sec 0 972 KBytes +[ 9] 5.00-6.00 sec 92.5 MBytes 776 Mbits/sec 0 1.02 MBytes +[ 9] 6.00-7.00 sec 92.5 MBytes 776 Mbits/sec 0 1.08 MBytes +[ 9] 7.00-8.00 sec 92.5 MBytes 776 Mbits/sec 0 1.14 MBytes +[ 9] 8.00-9.00 sec 91.2 MBytes 765 Mbits/sec 0 915 KBytes +[ 9] 9.00-10.00 sec 92.5 MBytes 776 Mbits/sec 0 1000 KBytes +- - - - - - - - - - - - - - - - - - - - - - - - - +[ ID] Interval Transfer Bitrate Retr +[ 9] 0.00-10.00 sec 927 MBytes 778 Mbits/sec 0 sender +[ 9] 0.00-10.01 sec 925 MBytes 775 Mbits/sec receiver +``` + +[intelยฎ qat]: https://www.intel.com/content/www/us/en/architecture-and-technology/intel-quick-assist-technology-overview.html diff --git a/docs/configuration/system/md-conntrack.md b/docs/configuration/system/md-conntrack.md new file mode 100644 index 00000000..f83f0684 --- /dev/null +++ b/docs/configuration/system/md-conntrack.md @@ -0,0 +1,218 @@ +# Conntrack + +VyOS can be configured to track connections using the connection +tracking subsystem. Connection tracking becomes operational once either +stateful firewall or NAT is configured. + +## Configure + +```{cfgcmd} set system conntrack table-size \<1-50000000\> +:defaultvalue: + +The connection tracking table contains one entry for each connection being +tracked by the system. +``` + +```{cfgcmd} set system conntrack expect-table-size \<1-50000000\> +:defaultvalue: + +The connection tracking expect table contains one entry for each expected +connection related to an existing connection. These are generally used by +โ€œconnection tracking helperโ€ modules such as FTP. +The default size of the expect table is 2048 entries. +``` + +```{cfgcmd} set system conntrack hash-size \<1-50000000\> +: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. +``` + +```{eval-rst} +.. 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. + + | Use `delete system conntrack modules` to deactive all modules. + | Or, for example ftp, `delete system conntrack modules ftp`. +``` + +```{cfgcmd} set system conntrack tcp half-open-connections \<1-21474836\> +:defaultvalue: + +Set the maximum number of TCP half-open connections. +``` + +```{cfgcmd} set system conntrack tcp loose \ +:defaultvalue: + +Policy to track previously established connections. +``` + +```{cfgcmd} set system conntrack tcp max-retrans \<1-2147483647\> +:defaultvalue: + +Set the number of TCP maximum retransmit attempts. +``` + +### Contrack Timeouts + +You can define custom timeout values to apply to a specific subset of +connections, based on a packet and flow selector. To do this, you need to +create a rule defining the packet and flow selector. + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + description + + Set a rule description. + +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + destination address +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + source address + + Set a destination and/or source address. Accepted input for ipv4: + + .. code-block:: none + + set system conntrack timeout custom ipv4 rule <1-999999> [source | destination] address + Possible completions: + IPv4 address to match + IPv4 prefix to match + - IPv4 address range to match + ! Match everything except the specified address + ! Match everything except the specified prefix + !- Match everything except the specified range + + set system conntrack timeout custom ipv6 rule <1-999999> [source | destination] address + Possible completions: + IP address to match + Subnet to match + - + IP range to match + ! Match everything except the specified address + ! Match everything except the specified prefix + !- + Match everything except the specified range + +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + destination port +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + source port + + Set a destination and/or source port. Accepted input: + + .. code-block:: none + + Named port (any name in /etc/services, e.g., http) + <1-65535> Numbered port + - Numbered port range (e.g., 1001-1005) + + Multiple destination ports can be specified as a comma-separated list. + The whole list can also be "negated" using '!'. For example: + `!22,telnet,http,123,1001-1005`` + +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp close <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp close-wait <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp established <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp fin-wait <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp last-ack <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp syn-recv <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp syn-sent <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol tcp time-wait <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol udp replied <1-21474836> +.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> + protocol udp unreplied <1-21474836> + + Set the timeout in seconds for a protocol or state in a custom rule. +``` + +### Conntrack ignore rules + +:::{note} +**Important note about conntrack ignore rules:** +Starting from vyos-1.5-rolling-202406120020, ignore rules can be defined in +``set firewall [ipv4 | ipv6] prerouting raw ...``. It's expected that in +the future the conntrack ignore rules will be removed. + +> Customized ignore rules, based on a packet and flow selector. +::: + +```{eval-rst} +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + description +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + destination address +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + destination port +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + inbound-interface +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + protocol +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + source address +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + source port +.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> + tcp flags [not] + + Allowed values fpr TCP flags: ``ack``, ``cwr``, ``ecn``, ``fin``, ``psh``, + ``rst``, ``syn`` and ``urg``. Multiple values are supported, and for + inverted selection use ``not``, as shown in the example. +``` + +### Conntrack log + +```{eval-rst} +.. cfgcmd:: set system conntrack log event destroy +.. cfgcmd:: set system conntrack log event new +.. cfgcmd:: set system conntrack log event update + + Log the connection tracking events per type. + +.. cfgcmd:: set system conntrack log event destroy icmp +.. cfgcmd:: set system conntrack log event destroy other +.. cfgcmd:: set system conntrack log event destroy tcp +.. cfgcmd:: set system conntrack log event destroy udp +.. cfgcmd:: set system conntrack log event new icmp +.. cfgcmd:: set system conntrack log event new other +.. cfgcmd:: set system conntrack log event new tcp +.. cfgcmd:: set system conntrack log event new udp +.. cfgcmd:: set system conntrack log event update icmp +.. cfgcmd:: set system conntrack log event update other +.. cfgcmd:: set system conntrack log event update tcp +.. cfgcmd:: set system conntrack log event update udp + + Log the connection tracking events per protocol. + +.. cfgcmd:: set system conntrack log timestamp + + Turn on flow-based timestamp extension. + +.. cfgcmd:: set system conntrack log queue-size <100-999999> + + Manage internal queue size, default size is 4096 events. + +.. cfgcmd:: set system conntrack log log-level + + Manage log level +``` \ No newline at end of file diff --git a/docs/configuration/system/md-console.md b/docs/configuration/system/md-console.md new file mode 100644 index 00000000..9017fa30 --- /dev/null +++ b/docs/configuration/system/md-console.md @@ -0,0 +1,59 @@ +(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 \ + +Defines the specified device as a system console. Available console devices +can be (see completion helper): +* ``ttySN`` - Serial device name +* ``ttyAMAN``- Serial device name for some arm64 systems +* ``ttyUSBX`` - USB Serial device name +* ``hvc0`` - Xen console +``` + +```{cfgcmd} set system console device \ kernel + +When set, the selected serial console is used as the kernel boot console. +When removed, the kernel boot console falls back to tty0. + +:::{note} +Only one serial console can carry the ``kernel`` option. +When VyOS is installed via serial console, this option is set automatically +for the serial interface used during installation; usually ``ttyS0`` or +``ttyAMA0``. +::: +``` + +```{cfgcmd} set system console device \ 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 +data rate. +::: +``` \ No newline at end of file diff --git a/docs/configuration/system/md-default-route.md b/docs/configuration/system/md-default-route.md new file mode 100644 index 00000000..9f2793d1 --- /dev/null +++ b/docs/configuration/system/md-default-route.md @@ -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
`), 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 \ + +Specify static route into the routing table sending all non local traffic +to the nexthop 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}`routing-static` +::: diff --git a/docs/configuration/system/md-flow-accounting.md b/docs/configuration/system/md-flow-accounting.md new file mode 100644 index 00000000..c97d5473 --- /dev/null +++ b/docs/configuration/system/md-flow-accounting.md @@ -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 protocol NetFlow (versions 5, 9 and +10/IPFIX). 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 + +:::{warning} +Using NetFlow on routers with high traffic levels may lead to +high CPU usage and may affect the router's performance. In such cases, +consider using sFlow instead. +::: + +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 \ + +Configure and enable collection of flow information for the interface +identified by \. + +You can configure multiple interfaces which would 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 \ + +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 \ + +Set the syslog facility for flow-accounting log messages. Supported values +include ``daemon``, ``local0`` through ``local7``, and other standard syslog +facilities. +``` + + +### 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 \ + +There are multiple versions available for the NetFlow data. The \ +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 \ + +Configure address of NetFlow collector. NetFlow server at \ can +be both listening on an IPv4 or IPv6 address. +``` + +```{cfgcmd} set system flow-accounting netflow source-ip \ + +IPv4 or IPv6 source address of NetFlow packets +``` + +```{cfgcmd} set system flow-accounting netflow engine-id \ + +NetFlow engine-id which will appear in NetFlow data. The range is 0 to 255. +``` + +```{cfgcmd} set system flow-accounting netflow sampling-rate \ + +Use this command to configure the sampling rate for flow accounting. The +system samples one in every \ packets, where \ 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 \ + +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 \ + +If you want to change the maximum number of flows, which are tracking +simultaneously, you may do this with this command (default 8192). +``` + + +### Example: + +NetFlow v5 example: + +```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 \ + +Show flow accounting information for given \. + + +:::{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 \ host \ + +Show flow accounting information for given \ 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 +::: +``` \ No newline at end of file diff --git a/docs/configuration/system/md-frr.md b/docs/configuration/system/md-frr.md new file mode 100644 index 00000000..1741e286 --- /dev/null +++ b/docs/configuration/system/md-frr.md @@ -0,0 +1,45 @@ +(system-frr)= + +# FRR + +VyOS uses [FRRouting](https://frrouting.org/) as the control plane for dynamic +and static routing. The routing daemon behavior can be adjusted during runtime, +but requires either a restart of the routing daemon, or a reboot of the system. + +```{cfgcmd} set system frr bmp + +Enable {abbr}`BMP (BGP Monitoring Protocol)` support. +``` + +```{cfgcmd} set system frr descriptors \ + +This allows the operator to control the number of open file descriptors +each daemon is allowed to start with. If the operator plans to run bgp with +several thousands of peers then this is where we would modify FRR to allow +this to happen. +``` + +```{cfgcmd} set system frr irdp + +Enable ICMP Router Discovery Protocol support. +``` + +```{cfgcmd} set system frr profile \ + +Select an FRR profile to adapt its default settings. If unset, the +traditional profile is applied. +``` + +```{cfgcmd} set system frr snmp \ + +Enable SNMP support for an individual routing daemon. + +Supported daemons: +- bgpd +- isisd +- ldpd +- ospf6d +- ospfd +- ripd +- zebra +``` \ No newline at end of file diff --git a/docs/configuration/system/md-host-name.md b/docs/configuration/system/md-host-name.md new file mode 100644 index 00000000..81840d1f --- /dev/null +++ b/docs/configuration/system/md-host-name.md @@ -0,0 +1,70 @@ +(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 \ + + 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 \ + +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. This is the VyOS equivalent to +`/etc/hosts` file entries. + + +:::{note} +Do *not* manually edit `/etc/hosts`. This file will automatically be +regenerated on boot based on the settings in this section, which means you'll +lose all your manual edits. Instead, configure static host mappings as follows. +::: + +```{cfgcmd} set system static-host-mapping host-name \ inet \ + +Create a static hostname mapping which will always resolve the name +`` to IP address `
`. +``` +```{cfgcmd} set system static-host-mapping host-name \ alias \ + +Create named `` for the configured static mapping for ``. +Thus the address configured as {cfgcmd}`set system static-host-mapping +host-name inet
` can be reached via multiple names. + +Multiple aliases can be specified per host-name. +``` \ No newline at end of file diff --git a/docs/configuration/system/md-index.md b/docs/configuration/system/md-index.md new file mode 100644 index 00000000..e0b8a5a1 --- /dev/null +++ b/docs/configuration/system/md-index.md @@ -0,0 +1,34 @@ +# System + +```{toctree} +:includehidden: true +:maxdepth: 1 + +acceleration +conntrack +console +flow-accounting +frr +host-name +ip +ipv6 +lcd +login +name-server +option +proxy +sflow +syslog +sysctl +task-scheduler +time-zone +updates +watchdog +``` + +```{toctree} +:includehidden: true +:maxdepth: 1 + +default-route +``` diff --git a/docs/configuration/system/md-ip.md b/docs/configuration/system/md-ip.md new file mode 100644 index 00000000..717ee57d --- /dev/null +++ b/docs/configuration/system/md-ip.md @@ -0,0 +1,126 @@ +# IP + +## System configuration commands + +```{cfgcmd} set system ip disable-forwarding + +Use this command to disable IPv4 forwarding on all interfaces. +``` + +```{cfgcmd} set system ip disable-directed-broadcast + +Use this command to disable IPv4 directed broadcast forwarding on all +interfaces. + +If set, IPv4 directed broadcast forwarding will be completely disabled +regardless of whether per-interface directed broadcast forwarding is +enabled or not. +``` + +```{cfgcmd} set system ip arp table-size \ + +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. +``` + +```{cfgcmd} set system ip import-table \ + +Use this command to immport the table, by given table id, into the main RIB. +``` + +```{cfgcmd} set system ip import-table \ distance \ + +Use this command to override the default distance when importing routers +from the alternate table. +``` + +```{cfgcmd} set system ip import-table \ route-map \ + +Use this command to filter routes that are imported into the main table +from alternate table using route-map. +``` + + +### Zebra/Kernel route filtering + +Zebra supports prefix-lists and Route Maps to match routes received from +other FRR components. The permit/deny facilities provided by these commands +can be used to filter which routes zebra will install in the kernel. + +```{cfgcmd} set system ip protocol \ route-map \ + +Apply a route-map filter to routes for the specified protocol. The following +protocols can be used: any, babel, bgp, eigrp, isis, ospf, rip, static + +:::{note} +If you choose any as the option that will cause all protocols that +are sending routes to zebra. +::: +``` + + +### Nexthop Tracking + +Nexthop tracking resolve nexthops via the default route by default. This is enabled +by default for a traditional profile of FRR which we use. It and can be disabled if +you do not want to e.g. allow BGP to peer across the default route. + +```{cfgcmd} set system ip nht no-resolve-via-default + +Do not allow IPv4 nexthop tracking to resolve via the default route. This +parameter is configured per-VRF, so the command is also available in the VRF +subnode. +``` + + +## Operational commands + +### show commands + +See below the different parameters available for the IPv4 **show** command: + +```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: + +```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 +``` diff --git a/docs/configuration/system/md-ipv6.md b/docs/configuration/system/md-ipv6.md new file mode 100644 index 00000000..ee0a6ade --- /dev/null +++ b/docs/configuration/system/md-ipv6.md @@ -0,0 +1,193 @@ +# IPv6 + +## System configuration commands + +```{cfgcmd} set system ipv6 disable-forwarding + + Use this command to disable IPv6 forwarding on all interfaces. +``` + + +```{cfgcmd} set system ipv6 neighbor table-size \ + +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. +``` + +### Zebra/Kernel route filtering + + +Zebra supports prefix-lists and Route Maps to match routes received from +other FRR components. The permit/deny facilities provided by these commands +can be used to filter which routes zebra will install in the kernel. + +```{cfgcmd} set system ipv6 protocol \ route-map \ + +Apply a route-map filter to routes for the specified protocol. The following +protocols can be used: any, babel, bgp, isis, ospfv3, ripng, static + +:::{note} +If you choose any as the option that will cause all protocols that +are sending routes to zebra. +::: +``` + +### Nexthop Tracking + + +Nexthop tracking resolve nexthops via the default route by default. This is enabled +by default for a traditional profile of FRR which we use. It and can be disabled if +you do not want to e.g. allow BGP to peer across the default route. + +```{cfgcmd} set system ipv6 nht no-resolve-via-default + +Do not allow IPv6 nexthop tracking to resolve via the default route. This +parameter is configured per-VRF, so the command is also available in the VRF +subnode. +``` + +## 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: + Execute the current command + Show IPv6 routes of given address or prefix + + 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 + tag Show only routes with tag + 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: + Execute the current command + 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: + Execute the current command + Show specified IPv6 access-list +::: +``` +```{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: + 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 bgp ipv6 \ + +Use this command to clear Border Gateway Protocol statistics or +status. +``` +```{opcmd} reset ipv6 neighbors \
+ +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/md-lcd.md b/docs/configuration/system/md-lcd.md new file mode 100644 index 00000000..ef9031ea --- /dev/null +++ b/docs/configuration/system/md-lcd.md @@ -0,0 +1,41 @@ +(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 \ + +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 refer to the USB hardware section. +``` + +```{cfgcmd} set system lcd 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. +::: +``` + diff --git a/docs/configuration/system/md-login.md b/docs/configuration/system/md-login.md new file mode 100644 index 00000000..288d30a8 --- /dev/null +++ b/docs/configuration/system/md-login.md @@ -0,0 +1,604 @@ +--- +lastproofread: '2026-01-12' +--- + +(user-management)= + +# Login/user management + +The default VyOS user account (`vyos`), as well as newly created user accounts, +possess full system configuration privileges. These accounts are granted sudo +privileges, allowing them to execute commands as the root user. + +VyOS supports both local authentication and remote authentication via +{abbr}`RADIUS (Remote Authentication Dial-In User Service)`/ {abbr}`TACACS+ +(Terminal Access Controller Access-Control System)`. + +## Local authentication + +```{cfgcmd} set system login user \ full-name "\" + +**Configure the real name or description for a system user.** + +If the description includes spaces, enclose ```` in double quotes. + +If the user ```` already exists, the command updates the current +description. If not, it creates a new user with the specified description. +``` + +```{cfgcmd} set system login user \ authentication plaintext-password \ + +**Configure a password for a system user.** + +Enter the password in plaintext. Upon ``commit``, VyOS hashes the password for +secure storage and removes the plaintext value. + +If the user ```` already exists, the command updates the current password. +If not, it creates a new user with the specified plaintext password. +``` + +```{cfgcmd} set system login user \ authentication encrypted-password \ + +**Configure a pre-encrypted password for a system user.** + +Enter the password in its hashed format. Upon ``commit``, VyOS stores this value +directly without modification. + +If the user ```` already exists, the command updates the current password. +If not, it creates a new user with the specified pre-encrypted password. +``` + +```{cfgcmd} set system login user \ authentication principal \ + +**Configure an SSH certificate principal for a system user.** + +Enter the principal (a string included in the user's signed SSH certificate). +Upon ``commit``, VyOS stores this mapping, allowing the user to log in if the +certificate they present contains this principal. + +If the user ```` already exists, the command updates the principal. If not, +it creates a new user linked to the specified principal. + +**If not configured**, the principal defaults to ````. +``` + +```{cfgcmd} set system login user \ disable + +**Disable a system user account.** + +VyOS locks the account, preventing the user from logging in. +``` + +(ssh_key_based_authentication)= + +## Key-based authentication + +Key-based authentication is the recommended method for securing SSH access in +VyOS. It uses a **public/private key pair** to verify user identity without +requiring a password. To authorize access, you assign **SSH public keys** to +user accounts on the router, while SSH private keys remain on local devices. +VyOS allows assigning multiple SSH public keys to a single user account, which +is useful for accessing a router from different devices. + +### Generate the key pair + +Generate an SSH key pair on your **local machine** using the `ssh-keygen` +command. This creates two files: +- **Private key** (e.g., `id_rsa`): Remains on your local machine and must + never be shared. +- **Public key** (e.g., `id_rsa.pub`): Is used to configure the VyOS user + account. By default, it is saved to `~/.ssh/id_rsa.pub`. + +Each SSH public key consists of three parts, separated by spaces: +- **Encryption algorithm type:** `ssh-rsa`, `ssh-ed25519`, etc. +- **Key:** The actual data (a long string beginning with `AAAA...`). +- **Comment:** An identifier for your reference (e.g., `user@host`). + +Only the encryption algorithm type and key parts are required to +configure the authorization entry in VyOS. The comment part is optional. + +:::{seealso} +{ref}`SSH operation ` +::: + +:::{warning} +SSH key strings are long. When copying and pasting, ensure your +terminal does not insert line breaks. The key must be entered as a **single +line** to function correctly. +::: + +### Configure the router + +To configure SSH public key authentication for a user account, run the +following two commands using the same ``: + +```{cfgcmd} set system login user \ authentication public-keys \ key \ + +**Configure the SSH public key for the user account.** +* ````: A unique label that identifies this specific key entry. +* ````: The actual string of characters from your public key. +``` + +```{cfgcmd} set system login user \ authentication public-keys \ type \ + +**Configure the SSH key's encryption type.** + +The following encryption algorithm types are available: + +* ``ecdsa-sha2-nistp256`` +* ``ecdsa-sha2-nistp384`` +* ``ecdsa-sha2-nistp521`` +* ``ssh-dss`` +* ``ssh-ed25519`` +* ``ssh-rsa`` + +:::{note} +To assign multiple SSH public keys to a user account, repeat the +commands above with a unique identifier for each key. +::: +``` + +```{cfgcmd} set system login user \ authentication public-keys \ options \ + +**Configure specific restrictions or behaviors for an SSH public key.** + +````: A string of comma-separated values that define permissions +or restrictions for this key. + +The command accepts standard OpenSSH options listed in the router's +``~/.ssh/authorized_keys`` file. + +To include a ``"`` character in the options string, use ``"``. + +For example, to restrict allowed source IP addresses for an SSH public key, +use: ``from="10.0.0.0/24"``. +``` + + +## OTP-based MFA + +VyOS lets you enhance user access security by enabling {abbr}`OTP (One-time +password)`-based {abbr}`MFA (Multi-factor Authentication)` for individual +users. Users with {abbr}`OTP (One-time password)`-based {abbr}`MFA +(Multi-factor Authentication)` must enter a valid {abbr}`OTP (One-time +password)` along with their password at login. Users without {abbr}`OTP +(One-time password)`-based {abbr}`MFA (Multi-factor Authentication)` use +standard authentication. + +```{cfgcmd} set system login user \ authentication otp key \ + +**Configure** {abbr}`OTP (One-time password)`**-based** {abbr}`MFA +(Multi-factor Authentication)` **for a user.** + +````: A Base32-encoded secret key. This key must be added to the user's +authenticator app to generate valid {abbr}`OTPs (One-time passwords)`. + +**When configured**, the user is required to enter their password followed by +a valid OTP for all subsequent logins. +``` + + +### OTP settings + +```{cfgcmd} set system login user \ authentication otp rate-limit \ + +**Configure the number of** {abbr}`OTP (One-time password)` **authentication +attempts allowed within a specified time period.** + +If this limit is exceeded, the user is temporarily blocked. + +The default value is 3 attempts. The valid range is 1 to 10 attempts. +``` + +```{cfgcmd} set system login user \ authentication otp rate-time \ + +**Configure the time period, in seconds, for tracking** {abbr}`OTP (One-time +password)` **authentication attempts.** + +The default value is 30 seconds. The valid range is 1 to 600 seconds. +``` + +```{cfgcmd} set system login user \ authentication otp window-size \ + +**Configure the** {abbr}`OTP (One-time password)` **window size for a user.** + +The {abbr}`OTP (One-time password)` window size defines the number of +concurrently valid {abbr}`OTPs (One-time passwords)` that the authentication +server accepts. This setting assumes a new token is generated every 30 seconds. + +The default value is 3. This permits 3 concurrent codes: the code for the +current 30-second interval, the preceding code, and the following code. This +allows up to 30 seconds of time skew between the authentication server and +client. + +If the window size is increased to 17, the system permits 17 concurrent codes +(the current code, the 8 preceding codes, and the 8 following codes). This +allows for a time skew of up to 4 minutes. + +The valid range is 1 to 21. +``` + + +### Generate an OTP-key + +Use the following command to generate an OTP key: + +```{cfgcmd} generate system login username \ otp-key hotp-time rate-limit \<1-10\> rate-time \<15-600\> window-size \<1-21\> +``` + +Key generation example: + +```none +vyos@vyos:~$ generate system login username otptester otp-key hotp-time rate-limit 2 rate-time 20 window-size 5 +# You can share it with the user, he just needs to scan the QR in his OTP app +# username: otptester +# OTP KEY: J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY +# OTP URL: otpauth://totp/otptester@vyos?secret=J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY&digits=6&period=30 +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆ โ–„โ–„โ–„โ–„โ–„ โ–ˆโ–€โ–ˆ โ–ˆโ–„ โ–€โ–„โ–€โ–„โ–ˆโ–€โ–„ โ–€โ–ˆโ–€ โ–ˆ โ–„โ–„โ–„โ–„โ–„ โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆ โ–ˆ โ–ˆโ–€โ–€โ–€โ–ˆ โ–„โ–€ โ–ˆโ–„โ–€ โ–€โ–„ โ–„ โ–€ โ–„โ–ˆ โ–ˆ โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–„โ–„โ–„โ–ˆ โ–ˆโ–€ โ–ˆโ–€โ–€โ–ˆโ–ˆโ–„โ–„ โ–ˆ โ–ˆ โ–ˆโ–ˆ โ–€โ–„โ–€ โ–ˆ โ–ˆโ–„โ–„โ–„โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–ˆโ–„โ–€ โ–€โ–„โ–ˆ โ–ˆ โ–€ โ–ˆ โ–ˆ โ–ˆ โ–ˆโ–„โ–ˆโ–„โ–ˆโ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆ โ–„ โ–ˆโ–„ โ–„ โ–€โ–„โ–€โ–€โ–€โ–€โ–„โ–€โ–„โ–€โ–„โ–„โ–„โ–€โ–€โ–„โ–„โ–„ โ–ˆ โ–ˆโ–„โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–„ โ–ˆโ–ˆโ–€โ–„โ–„โ–„โ–€โ–€โ–ˆโ–€ โ–„ โ–„โ–„โ–„ โ–„โ–€ โ–€ โ–ˆ โ–„ โ–„ โ–ˆโ–ˆโ–„โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–„ โ–ˆโ–ˆโ–„โ–„โ–€โ–ˆโ–„โ–ˆโ–„โ–ˆโ–„ โ–€โ–ˆโ–„โ–€โ–„ โ–€โ–ˆโ–€โ–„ โ–ˆโ–„โ–„โ–„ โ–„ โ–„โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–€โ–€โ–„ โ–„โ–ˆโ–€โ–„โ–€ โ–„โ–ˆโ–€โ–ˆโ–€โ–„โ–„โ–„โ–€โ–ˆโ–„ โ–ˆโ–ˆโ–„โ–„โ–„ โ–€โ–ˆ โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆ โ–„โ–€โ–„โ–ˆโ–€โ–„โ–„โ–ˆโ–€โ–€โ–„โ–€โ–€โ–€โ–€โ–ˆ โ–„โ–€โ–„โ–€ โ–„โ–ˆ โ–€โ–„ โ–„ โ–„โ–€ โ–ˆโ–„โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–„ โ–ˆโ–ˆ โ–€โ–„โ–€โ–€ โ–„โ–ˆโ–€ โ–„ โ–ˆโ–ˆ โ–€โ–ˆโ–„โ–ˆ โ–„โ–ˆ โ–„ โ–€โ–„ โ–„โ–„ โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–ˆโ–€โ–€โ–„ โ–„โ–„ โ–ˆโ–„โ–ˆโ–„โ–ˆโ–„ โ–ˆโ–„โ–„โ–€โ–„โ–„โ–€โ–€โ–„โ–„โ–ˆโ–ˆโ–€ โ–„โ–€โ–„โ–„ โ–€โ–„โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–€โ–„โ–€ โ–„ โ–„โ–€โ–ˆ โ–„ โ–„โ–ˆโ–€ โ–ˆ โ–€โ–„โ–„ โ–„โ–ˆโ–€ โ–„โ–„ โ–€โ–„โ–„ โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆ โ–€โ–ˆโ–ˆโ–ˆโ–„ โ–ˆโ–„โ–ˆโ–„โ–€โ–€โ–€โ–€โ–„ โ–„โ–ˆโ–„โ–„โ–€ โ–€โ–ˆโ–ˆโ–ˆ โ–„โ–„โ–ˆโ–„โ–„ โ–„โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–€ โ–„โ–„โ–€โ–€โ–ˆโ–ˆโ–€ โ–„โ–€โ–„โ–ˆโ–„โ–„โ–„ โ–ˆโ–ˆโ–„โ–„โ–€โ–„โ–€ โ–ˆโ–ˆโ–ˆโ–„ โ–„โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–„โ–„โ–€โ–„ โ–ˆโ–„โ–ˆโ–„โ–€โ–„โ–„โ–„โ–„โ–ˆโ–ˆโ–€ โ–„โ–€ โ–„ โ–„โ–„โ–„ โ–ˆโ–„โ–„โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆ โ–„โ–„โ–„โ–„โ–„ โ–ˆโ–„โ–„โ–„ โ–„โ–ˆโ–€โ–ˆโ–€โ–€โ–€โ–€โ–ˆโ–€โ–ˆโ–€ โ–ˆโ–„โ–ˆ โ–ˆโ–„โ–ˆ โ–„โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆ โ–ˆ โ–ˆ โ–ˆโ–ˆโ–„โ–€โ–€โ–€โ–€โ–„โ–„โ–„โ–€ โ–„โ–„โ–„ โ–€ โ–„ โ–„ โ–„โ–„โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–„โ–„โ–„โ–ˆ โ–ˆ โ–€โ–€โ–ˆโ–€ โ–„โ–„โ–ˆ โ–ˆโ–„โ–„โ–ˆโ–ˆโ–€โ–€โ–ˆโ–€ โ–ˆโ–„โ–€โ–„โ–ˆโ–ˆโ–„โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–ˆโ–„โ–ˆโ–„โ–ˆโ–„โ–ˆโ–„โ–„โ–„โ–„โ–„โ–ˆโ–„โ–„โ–„โ–ˆโ–„โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–ˆโ–ˆโ–„โ–„โ–„โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ +# To add this OTP key to configuration, run the following commands: +set system login user otptester authentication otp key 'J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY' +set system login user otptester authentication otp rate-limit '2' +set system login user otptester authentication otp rate-time '20' +set system login user otptester authentication otp window-size '5' +``` + +### Display the OTP key for a user + +Use the following command to display the {abbr}`OTP (One-time password)` +key for a user: + +```{cfgcmd} sh system login authentication user \ otp \ +``` + +Example: + +```none +vyos@vyos:~$ sh system login authentication user otptester otp full +# You can share the OTP key with the user. They just need to scan the QR in their OTP app. +# username: otptester +# OTP KEY: J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY +# OTP URL: otpauth://totp/otptester@vyos?secret=J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY&digits=6&period=30 +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆ โ–„โ–„โ–„โ–„โ–„ โ–ˆโ–€โ–ˆ โ–ˆโ–„ โ–€โ–„โ–€โ–„โ–ˆโ–€โ–„ โ–€โ–ˆโ–€ โ–ˆ โ–„โ–„โ–„โ–„โ–„ โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆ โ–ˆ โ–ˆโ–€โ–€โ–€โ–ˆ โ–„โ–€ โ–ˆโ–„โ–€ โ–€โ–„ โ–„ โ–€ โ–„โ–ˆ โ–ˆ โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–„โ–„โ–„โ–ˆ โ–ˆโ–€ โ–ˆโ–€โ–€โ–ˆโ–ˆโ–„โ–„ โ–ˆ โ–ˆ โ–ˆโ–ˆ โ–€โ–„โ–€ โ–ˆ โ–ˆโ–„โ–„โ–„โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–ˆโ–„โ–€ โ–€โ–„โ–ˆ โ–ˆ โ–€ โ–ˆ โ–ˆ โ–ˆ โ–ˆโ–„โ–ˆโ–„โ–ˆโ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆ โ–„ โ–ˆโ–„ โ–„ โ–€โ–„โ–€โ–€โ–€โ–€โ–„โ–€โ–„โ–€โ–„โ–„โ–„โ–€โ–€โ–„โ–„โ–„ โ–ˆ โ–ˆโ–„โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–„ โ–ˆโ–ˆโ–€โ–„โ–„โ–„โ–€โ–€โ–ˆโ–€ โ–„ โ–„โ–„โ–„ โ–„โ–€ โ–€ โ–ˆ โ–„ โ–„ โ–ˆโ–ˆโ–„โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–„ โ–ˆโ–ˆโ–„โ–„โ–€โ–ˆโ–„โ–ˆโ–„โ–ˆโ–„ โ–€โ–ˆโ–„โ–€โ–„ โ–€โ–ˆโ–€โ–„ โ–ˆโ–„โ–„โ–„ โ–„ โ–„โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–€โ–€โ–„ โ–„โ–ˆโ–€โ–„โ–€ โ–„โ–ˆโ–€โ–ˆโ–€โ–„โ–„โ–„โ–€โ–ˆโ–„ โ–ˆโ–ˆโ–„โ–„โ–„ โ–€โ–ˆ โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆ โ–„โ–€โ–„โ–ˆโ–€โ–„โ–„โ–ˆโ–€โ–€โ–„โ–€โ–€โ–€โ–€โ–ˆ โ–„โ–€โ–„โ–€ โ–„โ–ˆ โ–€โ–„ โ–„ โ–„โ–€ โ–ˆโ–„โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–„ โ–ˆโ–ˆ โ–€โ–„โ–€โ–€ โ–„โ–ˆโ–€ โ–„ โ–ˆโ–ˆ โ–€โ–ˆโ–„โ–ˆ โ–„โ–ˆ โ–„ โ–€โ–„ โ–„โ–„ โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–ˆโ–€โ–€โ–„ โ–„โ–„ โ–ˆโ–„โ–ˆโ–„โ–ˆโ–„ โ–ˆโ–„โ–„โ–€โ–„โ–„โ–€โ–€โ–„โ–„โ–ˆโ–ˆโ–€ โ–„โ–€โ–„โ–„ โ–€โ–„โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–€โ–„โ–€ โ–„ โ–„โ–€โ–ˆ โ–„ โ–„โ–ˆโ–€ โ–ˆ โ–€โ–„โ–„ โ–„โ–ˆโ–€ โ–„โ–„ โ–€โ–„โ–„ โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆ โ–€โ–ˆโ–ˆโ–ˆโ–„ โ–ˆโ–„โ–ˆโ–„โ–€โ–€โ–€โ–€โ–„ โ–„โ–ˆโ–„โ–„โ–€ โ–€โ–ˆโ–ˆโ–ˆ โ–„โ–„โ–ˆโ–„โ–„ โ–„โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–ˆโ–ˆโ–€ โ–„โ–„โ–€โ–€โ–ˆโ–ˆโ–€ โ–„โ–€โ–„โ–ˆโ–„โ–„โ–„ โ–ˆโ–ˆโ–„โ–„โ–€โ–„โ–€ โ–ˆโ–ˆโ–ˆโ–„ โ–„โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–„โ–„โ–€โ–„ โ–ˆโ–„โ–ˆโ–„โ–€โ–„โ–„โ–„โ–„โ–ˆโ–ˆโ–€ โ–„โ–€ โ–„ โ–„โ–„โ–„ โ–ˆโ–„โ–„โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆ โ–„โ–„โ–„โ–„โ–„ โ–ˆโ–„โ–„โ–„ โ–„โ–ˆโ–€โ–ˆโ–€โ–€โ–€โ–€โ–ˆโ–€โ–ˆโ–€ โ–ˆโ–„โ–ˆ โ–ˆโ–„โ–ˆ โ–„โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆ โ–ˆ โ–ˆ โ–ˆโ–ˆโ–„โ–€โ–€โ–€โ–€โ–„โ–„โ–„โ–€ โ–„โ–„โ–„ โ–€ โ–„ โ–„ โ–„โ–„โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆ โ–ˆโ–„โ–„โ–„โ–ˆ โ–ˆ โ–€โ–€โ–ˆโ–€ โ–„โ–„โ–ˆ โ–ˆโ–„โ–„โ–ˆโ–ˆโ–€โ–€โ–ˆโ–€ โ–ˆโ–„โ–€โ–„โ–ˆโ–ˆโ–„โ–ˆ โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–„โ–„โ–„โ–„โ–„โ–„โ–ˆโ–„โ–ˆโ–„โ–ˆโ–„โ–ˆโ–„โ–„โ–„โ–„โ–„โ–ˆโ–„โ–„โ–„โ–ˆโ–„โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–„โ–ˆโ–ˆโ–„โ–„โ–„โ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ +โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ +# To add this OTP key to configuration, run the following commands: +set system login user otptester authentication otp key 'J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY' +set system login user otptester authentication otp rate-limit '2' +set system login user otptester authentication otp rate-time '20' +set system login user otptester authentication otp window-size '5' +``` + +Once {abbr}`OTP (One-time password)`-based {abbr}`MFA (Multi-factor +Authentication)` is configured for a user account, this user must enter their +standard password followed by the current 6-digit OTP code at login. For +example, if the user's password is `vyosrocks` and the OTP is `817454`, they +should enter `vyosrocks817454`. + +## RADIUS authentication + +For large-scale deployments, managing individual user accounts across multiple +VyOS instances is inefficient. VyOS supports centralized authentication via +{abbr}`RADIUS (Remote Authentication Dial-In User Service)`, consolidating user +account management on a single backend server. + +### Configuration + +```{cfgcmd} set system login radius server \ key \ + +**Configure the** {abbr}`RADIUS (Remote Authentication Dial-In User Service)` +**server's IP address and shared secret.** + +The shared secret is used to verify the router's identity and to encrypt user +passwords during authentication. + +You can configure multiple {abbr}`RADIUS (Remote Authentication Dial-In User +Service)` servers. +``` + +```{cfgcmd} set system login radius server \ port \ + +**Configure the UDP port for communication with the** {abbr}`RADIUS (Remote +Authentication Dial-In User Service)` **server.** + +The default port is 1812. +``` + +```{cfgcmd} set system login radius server \ disable + +**Disable a** {abbr}`RADIUS (Remote Authentication Dial-In User Service)` +**server from the authentication process.** + +Disabling a specific {abbr}`RADIUS (Remote Authentication Dial-In User +Service)` server doesnโ€™t remove its configuration settings (the serverโ€™s IP +address and shared secret). +``` + +```{cfgcmd} set system login radius server \ timeout \ + +Configure the duration, in seconds, that the VyOS router waits for a +response from the {abbr}`RADIUS (Remote Authentication Dial-In User Service)` +server after sending an authentication request. + +If the server does not respond within this timeframe, the VyOS router tries to +connect to another configured server or falls back to local authentication. +``` + +```{cfgcmd} set system login radius source-address \ + +**Configure the source IP address the router uses for** {abbr}`RADIUS (Remote +Authentication Dial-In User Service)` **authentication requests.** + +A consistent source IP address is recommended as RADIUS servers typically +accept requests only from known, trusted IP addresses. + +If not explicitly defined, the router uses the current egress interface +address, which may change (e.g., due to a link outage), causing authentication +failures. +``` + +```{cfgcmd} set system login radius vrf \ + +**Configure the router to send all** {abbr}`RADIUS (Remote Authentication +Dial-In User Service)` **authentication requests via a specific VRF.** + +By default, {abbr}`RADIUS (Remote Authentication Dial-In User Service)` +authentication requests are sent via the global routing table. +``` + +### Configuration example + +```none +set system login radius server 192.168.0.2 key 'test-vyos' +set system login radius server 192.168.0.2 port '1812' +set system login radius server 192.168.0.2 timeout '5' +set system login radius source-address '192.168.0.1' +``` + +If communication with the {abbr}`RADIUS (Remote Authentication Dial-In User +Service)` server fails, the router falls back to local user authentication. +During this process, users may experience a login delay while the system waits +for the {abbr}`RADIUS (Remote Authentication Dial-In User Service)` request to +time out. This delay depends on the configured timeout value. + +:::{hint} +To grant administrative privileges to {abbr}`RADIUS (Remote +Authentication Dial-In User Service)`-authenticated users, the server must +return the Cisco-AV-Pair attribute set to `shell:priv-lvl=15`. Otherwise, users +receive standard privileges and cannot perform configuration tasks. +::: + +## TACACS+ authentication + +In addition to {abbr}`RADIUS (Remote Authentication Dial-In User Service)`, +VyOS supports {abbr}`TACACS+ (Terminal Access Controller Access Control +System)`, which is commonly used in large enterprise environments. + +Unlike {abbr}`RADIUS (Remote Authentication Dial-In User Service)`, +{abbr}`TACACS+ (Terminal Access Controller Access Control System)` separates +Authentication, Authorization, and Accounting (AAA) into independent processes +and encrypts the entire packet body for enhanced security. + +{abbr}`TACACS+ (Terminal Access Controller Access Control System)` is defined +in {rfc}`8907`. +(tacacs-configuration)= + +### Configuration + +```{cfgcmd} set system login tacacs server \ key \ + +**Configure the** {abbr}`TACACS+ (Terminal Access Controller Access Control +System)` **server IP address and shared secret.** + +Unlike {abbr}`RADIUS (Remote Authentication Dial-In User Service)`, which +encrypts only passwords, {abbr}`TACACS+ (Terminal Access Controller Access +Control System)` encrypts the entire packet body for enhanced security. + +You can configure multiple {abbr}`TACACS+ (Terminal Access Controller Access +Control System)` servers. +``` + +```{cfgcmd} set system login tacacs server \ port \ + +**Configure the TCP port for communication with the** {abbr}`TACACS+ (Terminal +Access Controller Access Control System)` **server.** + +The default port is 49. +``` + +```{cfgcmd} set system login tacacs server \ disable + +**Disable a** {abbr}`TACACS+ (Terminal Access Controller Access Control +System)` **server from the authentication process.** + +Disabling a specific {abbr}`TACACS+ (Terminal Access Controller Access Control +System)` server doesnโ€™t remove its configuration settings (the serverโ€™s IP +address and shared secret). +``` + +```{cfgcmd} set system login tacacs server \ timeout \ + +Configure the duration, in seconds, that the VyOS router waits for a +response from the {abbr}`TACACS+ (Terminal Access Controller Access +Control System)` server after sending an authentication request. + +If the server does not respond within this timeframe, the VyOS router tries +to connect to another configured server or falls back to local authentication. +``` + +```{cfgcmd} set system login tacacs source-address \ + +**Configure the source IP address the router uses for** +{abbr}`TACACS+ (Terminal Access Controller Access Control System)` +**authentication requests.** + +A consistent source IP address is recommended as {abbr}`TACACS+ (Terminal +Access Controller Access Control System)` servers typically accept requests +only from known, trusted IP addresses. + +If not explicitly defined, the router uses the current egress interface address, +which may change (e.g., due to a link outage), causing authentication failures. +``` + +```{cfgcmd} set system login tacacs vrf \ + +Configure the router to send all {abbr}`TACACS+ (Terminal Access Controller +Access Control System)` authentication requests via a specific VRF. + +By default, {abbr}`TACACS+ (Terminal Access Controller Access Control System)` +authentication requests are sent via the global routing table. +``` + +(login-tacacs-example)= + +### Configuration example + +```none +set system login tacacs server 192.168.0.2 key 'test-vyos' +set system login tacacs server 192.168.0.2 port '49' +set system login tacacs source-address '192.168.0.1' +``` + +If communication with the {abbr}`TACACS+ (Terminal Access Controller Access +Control System)` server fails, the router falls back to local user +authentication. + +## Login banners + +VyOS allows you to configure **pre-login** and **post-login** banners. +Pre-login banners are typically used for system identification, legal disclaimers, or security warnings +displayed before authentication, while post-login banners provide system +information or operational notices to users after login. + +```{cfgcmd} set system login banner pre-login \ + +Configure a message to be shown to users before the ``username`` and ``password`` +prompts appear. +``` + +```{cfgcmd} set system login banner post-login \ + +Configure a message to be shown to users after successful authentication. +``` +:::{note} +Use `\\n` to insert line breaks in multi-line banner messages. +::: + +## Login session limits + +```{cfgcmd} set system login max-login-session \ + +**Configure the maximum number of concurrent login sessions.** +``` +:::{note} +If you limit concurrent login sessions, you must also configure a +session ``. This clears inactive sessions and prevents blocking new +login attempts. +::: +```{cfgcmd} set system login timeout \ + +**Configure the login session timeout, in seconds.** + +Idle login sessions are terminated after this period. +``` + +## Configuration examples + +Example 1: Multi-key SSH with MFA and source restrictions + +In this configuration, `User1` and `User2` both use the vyos user account, +each with a unique SSH key. `User1` is restricted to authentication from a +single IP address. + +For both users, password-based logins require {abbr}`OTP (One-time password)` +-based {abbr}`MFA (Multi-factor Authentication)`. + +```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 'User1' options "from="192.168.0.100"" + +set system login user vyos authentication public-keys 'User2' key "AAAAQ39x...fbV3" +set system login user vyos authentication public-keys 'User2' type ssh-rsa + +set system login user vyos authentication otp key OHZ3OJ7U2N25BK4G7SOFFJTZDTCFUUE2 +set system login user vyos authentication plaintext-password vyos +``` + +Example 2: Containerized {abbr}`TACACS+ (Terminal Access Controller Access Control System)` +deployment with redundancy. + +In this configuration, the VyOS router hosts its own authentication +infrastructure using two containerized {abbr}`TACACS+ (Terminal Access +Controller Access Control System)` servers (`tacacs1` and `tacacs2`) on a +private network for redundancy. + +System logins are authenticated against credentials stored within these internal +containers rather than the router's local user database. + +First, download the image in operational mode: + +```none +add container image lfkeitel/tacacs_plus:latest +``` + +Next, configure the containers in configuration mode: + +```none +set container network tac-test prefix '100.64.0.0/24' + +set container name tacacs1 image 'lfkeitel/tacacs_plus:latest' +set container name tacacs1 network tac-test address '100.64.0.11' + +set container name tacacs2 image 'lfkeitel/tacacs_plus:latest' +set container name tacacs2 network tac-test address '100.64.0.12' + +set system login tacacs server 100.64.0.11 key 'tac_plus_key' +set system login tacacs server 100.64.0.12 key 'tac_plus_key' + +commit +``` + +You can now log in via SSH or console using `admin/admin` credentials supplied +by the container image. diff --git a/docs/configuration/system/md-name-server.md b/docs/configuration/system/md-name-server.md new file mode 100644 index 00000000..9090ba5f --- /dev/null +++ b/docs/configuration/system/md-name-server.md @@ -0,0 +1,65 @@ +(system-dns)= + +# System DNS + +:::{warning} +If you are configuring a VRF for management purposes, there is +currently no way to force system DNS traffic via a specific VRF. +::: + +This section describes configuring DNS on the system, namely: + +> - DNS name servers +> - Domain search order + +## DNS name servers + +```{cfgcmd} set system name-server \ + +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: + +```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 +``` + + +## 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 \ + +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. +::: + +(name-server-domain-search-order-example)= + +### Example + +The system is configured to attempt domain completion in the following +order: vyos.io (first), vyos.net (second) and vyos.network (last): + +```none +set system domain-search vyos.io +set system domain-search vyos.net +set system domain-search vyos.network +``` diff --git a/docs/configuration/system/md-option.md b/docs/configuration/system/md-option.md new file mode 100644 index 00000000..c7a6ccf2 --- /dev/null +++ b/docs/configuration/system/md-option.md @@ -0,0 +1,190 @@ +(system-option)= + +# Option + +This chapter describe the possibilities of advanced system behavior. + +## General + +```{cfgcmd} set system option ctrl-alt-delete \ + +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 reboot-on-upgrade-failure \ + +Automatically reboot after `timeout` minutes into the previous running +image, that was used to perform the image upgrade. + +Reboot `timeout` is configurable in minutes. This gives the user the change +to log into the system and perform some analysis before automatic rebooting. + +Automatic reboot can be cancelled after login using: {opcmd}`reboot cancel` +``` + +```{cfgcmd} set system option startup-beep + +Play an audible beep to the system speaker when system is ready. +``` + +```{cfgcmd} set system option root-partition-auto-resize + +Enables the root partition auto-extension and resizes to the maximum +available space on system boot. +``` + + +### Kernel + +```{cfgcmd} set system option kernel disable-mitigations + +Disable all optional CPU mitigations. This improves system performance, +but it may also expose users to several CPU vulnerabilities. + +This will add the following option to the Kernel commandline: +* ``mitigations=off`` + +:::{note} +Setting will only become active with the next reboot! +::: +``` + +```{cfgcmd} set system option kernel disable-power-saving + +This will add the following two options to the Kernel commandline: +* ``intel_idle.max_cstate=0`` Disable intel_idle and fall back on acpi_idle +* ``processor.max_cstate=1`` Limit processor to maximum C-state 1 + +:::{note} +Setting will only become active with the next reboot! +::: +``` + +```{cfgcmd} set system option kernel amd-pstate-driver \ + +Enables and configures p-state driver for modern AMD Ryzen and Epyc CPUs. + +The available modes are: +* ``active`` This is the low-level firmware control mode based on the profile +set and the system governor has no effect. +* ``passive`` The driver allows the system governor to manage CPU frequency +while providing available performance states. +* ``guided`` The driver allows to set desired performance levels and the firmware +selects a performance level in this range and fitting to the current workload. + +This will add the following two options to the Kernel commandline: +* ``initcall_blacklist=acpi_cpufreq_init`` Disable default ACPI CPU frequency scale +* ``amd_pstate={mode}`` Sets the p-state mode + +:::{note} +Setting will only become active with the next reboot! +::: + +:::{seealso} + +::: +``` + +```{cfgcmd} set system option kernel quiet + +Suppress most kernel messages during boot. This is useful for systems with +embedded serial console interfaces to speed up the boot process. +``` + + +## HTTP client + +```{cfgcmd} set system option http-client source-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 \ + +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. +::: + +## SSH client + +```{cfgcmd} set system option ssh-client source-address \ + +Use the specified address on the local machine as the source address of the +connection. Only useful on systems with more than one address. +``` + +```{cfgcmd} set system option ssh-client source-interface \ + +Use the address of the specified interface on the local machine as the +source address of the connection. +``` + + +## Keyboard Layout + +When starting a VyOS live system (the installation CD) the configured keyboard +layout defaults to US. As this might not suite everyone's use case you can adjust +the used keyboard layout on the system console. + +```{cfgcmd} set system option keyboard-layout \ + +Change system keyboard layout to given language. + +Defaults to ``us``. + +:::{note} +Changing the keymap only has an effect on the system console, using +SSH or 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. + +:::{seealso} + +::: + +```{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. +``` \ No newline at end of file diff --git a/docs/configuration/system/md-proxy.md b/docs/configuration/system/md-proxy.md new file mode 100644 index 00000000..286e835f --- /dev/null +++ b/docs/configuration/system/md-proxy.md @@ -0,0 +1,27 @@ +(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 \ + +Set proxy for all connections initiated by VyOS, including HTTP, HTTPS, and +FTP (anonymous ftp). +``` +```{cfgcmd} set system proxy port \ + +Configure proxy port if it does not listen to the default port 80. +``` +```{cfgcmd} set system proxy 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 \ + +Some proxys require/support the "basic" HTTP authentication scheme as per +{rfc}`7617`, thus a password can be configured. +``` \ No newline at end of file diff --git a/docs/configuration/system/md-sflow.md b/docs/configuration/system/md-sflow.md new file mode 100644 index 00000000..350bbdd8 --- /dev/null +++ b/docs/configuration/system/md-sflow.md @@ -0,0 +1,66 @@ +# sFlow + +VyOS supports sFlow 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. + +sFlow is a technology that enables monitoring of network traffic by sending sampled packets to a collector device. + +The sFlow accounting based on hsflowd + +## Configuration + +```{cfgcmd} set system sflow agent-address \ + +Configure sFlow agent IPv4 or IPv6 address +``` +```{cfgcmd} set system sflow agent-interface \ + +Configure agent IP address associated with this interface. +``` +```{cfgcmd} set system sflow drop-monitor-limit \ + + Dropped packets reported on DROPMON Netlink channel by Linux kernel are exported via the standard sFlow v5 extension for reporting dropped packets +``` + + +```{cfgcmd} set system sflow interface \ + +Configure and enable collection of flow information for the interface identified by \. + +You can configure multiple interfaces which would participate in sflow accounting. +``` +```{cfgcmd} set system sflow polling \ + + Configure schedule counter-polling in seconds (default: 30) +``` + + +```{cfgcmd} set system sflow sampling-rate \ + +Use this command to configure the sampling rate for sFlow accounting (default: 1000) +``` + + +```{cfgcmd} set system sflow server \ port \ + +Configure address of sFlow collector. sFlow server at \ can be both listening on an IPv4 or IPv6 address. +``` + + +```{cfgcmd} set system sflow enable-egress + +Use this command to if you need to sample also egress traffic +``` + +## Example + +```none +set system sflow agent-address '192.0.2.14' +set system sflow agent-interface 'eth0' +set system sflow drop-monitor-limit '50' +set system sflow interface 'eth0' +set system sflow interface 'eth1' +set system sflow polling '30' +set system sflow sampling-rate '1000' +set system sflow server 192.0.2.1 port '6343' +set system sflow server 203.0.113.23 port '6343' +``` diff --git a/docs/configuration/system/md-sysctl.md b/docs/configuration/system/md-sysctl.md new file mode 100644 index 00000000..90434fb2 --- /dev/null +++ b/docs/configuration/system/md-sysctl.md @@ -0,0 +1,16 @@ +(sysctl)= + +# Sysctl + +:::{note} +This page is a stub and needs expansion. Contributions +welcome via the [VyOS documentation repository](https://github.com/vyos/vyos-documentation). +::: + +This chapter describes how to configure kernel parameters at runtime. + +`sysctl` is used to modify kernel parameters at runtime. The parameters +available are those listed under /proc/sys/. + +```{cfgcmd} set system sysctl parameter \ value \ +``` \ No newline at end of file diff --git a/docs/configuration/system/md-syslog.md b/docs/configuration/system/md-syslog.md new file mode 100644 index 00000000..ae30d272 --- /dev/null +++ b/docs/configuration/system/md-syslog.md @@ -0,0 +1,450 @@ +(syslog)= + +# Syslog + +## Overview + +By default, VyOS provides a minimal logging configuration with local storage +and log rotation. All errors, including local7 messages, are saved to a local +file. Emergency alerts are sent to the console. + +To change these settings, enter configuration mode. + +## Syslog configuration + +Syslog supports logging to multiple destinations: a local file, a console, or +a remote syslog server over UDP or TCP. + +The syslog configuration is organized into the following categories: + +- Global settings +- Local logging +- Console logging +- Remote logging +- TLS-encrypted remote logging + +### Global settings + +Configure the general behavior of the syslog service. + +```{cfgcmd} set system syslog marker interval \ + +**Configure the interval, in seconds, for sending syslog mark messages.** + +Syslog mark messages confirm the logging service is operational. + +Default: 1200 seconds. +``` + +```{cfgcmd} set system syslog marker disable + +Disable sending syslog mark messages. +``` + +```{cfgcmd} set system syslog preserve-fqdn + +**Configure how the logging device's hostname appears in log messages sent +to a remote syslog server.** + +If configured, the device includes its {abbr}`FQDN (Fully Qualified Domain +Name)` in log messages, even if the syslog server is in the same domain. +``` + + +### Local logging + +Configure which log messages to save to a local log file. + +```{cfgcmd} set system syslog local \ facility \ level \ + +**Configure syslog to save log messages for a specific facility and +severity level to \`\`/var/log/messages\`\`.** + +Refer to the tables below for valid facility and severity options. +``` + +(syslog-console)= + +### Console logging + +Configure which log messages to send to `/dev/console`. + +```{cfgcmd} set system syslog console facility \ level \ + +**Configure syslog to send log messages for a specific facility and severity +level to the device's console.** + +Refer to the tables below for valid facility and severity options. +``` + +(syslog-remote)= + +### Remote logging + +Configure **remote logging** to send log messages to a remote syslog server. + +Remote logging does not affect either **local** or **console logging** and +runs in parallel with them. Remote logging supports sending log messages +to multiple hosts. + +```{cfgcmd} set system syslog remote \ facility \ level \ + +**Configure log transmission to the remote syslog server for a specific +facility and severity level.** + +The serverโ€™s address can be specified using either a {abbr}`FQDN (Fully +Qualified Domain Name)` or an IP address. + +Refer to the tables below for valid facility and severity options. +``` + +```{cfgcmd} set system syslog remote \ protocol \ + +**Configure the protocol for log transmission.** + +The protocol can be either UDP or TCP. By default, log messages are sent +over UDP. +``` + +```{cfgcmd} set system syslog remote \ port \ + +**Configure the port for log transmission.** + +By default, the standard port 514 is used. +``` + +```{cfgcmd} set system syslog remote \ format include-timezone + +**Configure log transmission in the RFC 5424 format.** + +The RFC 5424 format includes the timezone in the timestamp. For example: + +:::{code-block} none +<34>1 2003-10-11T22:14:15.003-07:00 mymachine.example.com su - ID47 - BOMโ€™su rootโ€™ failed for lonvick on /dev/pts/8. +::: + +By default, log messages are sent in the RFC 3164 format. For example: + +:::{code-block} none +<34>Oct 11 22:14:15 mymachine su: โ€˜su rootโ€™ failed for lonvick on /dev/pts/8 +::: +``` + +```{cfgcmd} set system syslog remote \ format octet-counted + +**Enable octet-counted framing for log transmission.** + +When enabled, multi-line log messages are sent without splitting. Ensure +the remote server supports octet-counted framing to avoid parsing errors. + +Octet-counted framing is not available for the UDP protocol. +``` + +```{cfgcmd} set system syslog remote \ vrf \ + +Configure the {abbr}`VRF (Virtual Routing and Forwarding)` instance +for log transmission. +``` + +```{cfgcmd} set system syslog remote \ source-address \ + +Configure the source IP address (IPv4 or IPv6) for log transmission. +``` + + +#### {abbr}`TLS (Transport Layer Security)`-encrypted remote logging + +VyOS supports {abbr}`TLS (Transport Layer Security)`-encrypted remote logging +over TCP to ensure secure transmission of syslog data to remote syslog servers. + +**Prerequisites**: Before configuring {abbr}`TLS (Transport Layer +Security)`-encrypted remote logging, ensure you have: +- A valid remote syslog server address. +- Valid {abbr}`CA (Certificate Authority)` and client certificates uploaded + to the local {abbr}`PKI (Public Key Infrastructure)` storage. +- The **remote syslog transport protocol** is set to **TCP**: + + ```none + set system syslog remote
protocol tcp + ``` + +:::{note} +{abbr}`TLS (Transport Layer Security)`-encrypted remote logging is +**not supported** over **UDP**. +::: +```{cfgcmd} set system syslog remote \ tls + +Enable TLS-encrypted remote logging. + +``` + +```{cfgcmd} set system syslog remote \ tls ca-certificate \ + +**Configure the** {abbr}`CA (Certificate Authority)` **certificate.** + +The syslog client uses the {abbr}`CA (Certificate Authority)` certificate to +verify the identity of the remote syslog server. + +The {abbr}`CA (Certificate Authority)` certificate is required for **all** +authentication modes except ``anon``. + +``` + +```{cfgcmd} set system syslog remote \ tls certificate \ + +**Configure the client certificate.** + +The remote syslog server uses the client certificate to verify the identity +of the syslog client. + +The client certificate is required if the remote syslog server enforces +client certificate verification. + +``` + +````{cfgcmd} set system syslog remote \ tls auth-mode \ + +**Configure the authentication mode.** + +The authentication mode defines how the syslog client verifies the syslog +server's identity. + +The following authentication modes are available: + +```{eval-rst} +* ``anon`` **(default)**: Allows encrypted connections without verifying the syslog + server's identity. This mode is **not recommended**, as it is vulnerable to + :abbr:`MITM (Man-in-the-Middle)` attacks. +* ``fingerprint``: Verifies the serverโ€™s certificate fingerprint against the + value preconfigured with: + + .. code-block:: none + + set system syslog remote
tls permitted-peer + +* ``certvalid``: Verifies the server certificate is signed by a trusted + :abbr:`CA (Certificate Authority)`, skipping :abbr:`CN (Common Name)` check. +* ``name``: Verifies that: + + * The serverโ€™s certificate is signed by a trusted :abbr:`CA (Certificate + Authority)`. + * The :abbr:`CN (Common Name)` in the certificate matches the value + preconfigured with: + + .. code-block:: none + + set system syslog remote
tls permitted-peer + + This is a **recommended** secure mode for production environments. +``` + +```` + +```{cfgcmd} set system syslog remote \ tls permitted-peer \ + +**Configure the peer certificate identifiers.** + +The certificate identifier format depends on the authentication mode: +* ``fingerprint``: Enter the expected certificate fingerprints (SHA-1 or +SHA-256). +* ``name``: Enter the expected certificate {abbr}`CNs (Common Names)`. + +For ``anon`` and ``certvalid`` authentication modes, certificate identifiers +are not required. + +``` + +#### Examples: + +```none +# Example of 'anon' authentication mode +set system syslog remote 10.10.2.3 facility all level debug +set system syslog remote 10.10.2.3 port 6514 +set system syslog remote 10.10.2.3 protocol tcp +set system syslog remote 10.10.2.3 tls auth-mode anon +# or just use 'set system syslog remote 10.10.2.3 tls' + +# Example of 'certvalid' authentication mode +set system syslog remote elk.example.com facility all level debug +set system syslog remote elk.example.com port 6514 +set system syslog remote elk.example.com protocol tcp +set system syslog remote elk.example.com tls ca-certificate my-ca +set system syslog remote elk.example.com tls auth-mode certvalid + +# Example of 'fingerprint' authentication mode +set system syslog remote syslog.example.com facility all level debug +set system syslog remote syslog.example.com port 6514 +set system syslog remote syslog.example.com protocol tcp +set system syslog remote syslog.example.com tls ca-certificate my-ca +set system syslog remote syslog.example.com tls auth-mode fingerprint +set system syslog remote syslog.example.com tls permitted-peers 'SHA1:10:C4:26:...,SHA256:7B:4B:10:...' + +# Example of 'name' authentication mode +set system syslog remote graylog.example.com facility all level debug +set system syslog remote graylog.example.com port 6514 +set system syslog remote graylog.example.com protocol tcp +set system syslog remote graylog.example.com tls ca-certificate my-ca +set system syslog remote graylog.example.com tls certificate syslog-client +set system syslog remote graylog.example.com tls auth-mode name +set system syslog remote graylog.example.com tls permitted-peers 'graylog.example.com' +``` + +#### Security recommendations + +- For secure deployments, always use the `name` authentication mode. It + ensures that the server is validated by a trusted {abbr}`CA (Certificate + Authority)` and that the hostname matches the certificate. +- Use the `anon` authentication mode only in testing environments, as it + doesn't provide server authentication. +- Ensure private keys are generated, stored, and maintained exclusively within + the {doc}`PKI system `. +(syslog_facilities)= + +## Syslog facilities + +This section lists facilities used by syslog. Most facility names are self- +explanatory. The local0โ€“local7 facilities are used for custom purposes, such as +logging from network nodes and equipment. Facility assignment is flexible and +should be tailored to your company's needs. Consider facilities as categorization +tools, rather than strict directives. + +```{eval-rst} ++----------+----------+----------------------------------------------------+ +| 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 syslog | ++----------+----------+----------------------------------------------------+ +| 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 | local use 6 (local6) | ++----------+----------+----------------------------------------------------+ +| 23 | local7 | local use 7 (local7) | ++----------+----------+----------------------------------------------------+ +``` + +(syslog_severity_level)= + +## Severity levels + +```{eval-rst} ++-------+---------------+---------+-------------------------------------------+ +| 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 logs for a specific category on the console.** + +Use tab completion to view a list of available categories. + +If no category is specified, all logs are shown. + +``` + +````{opcmd} show log image \ [all | authorization | directory | file \ | tail \] + +**Display logs for a specific image on the console.** + +Available log categories: + +```{eval-rst} +.. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - all + - Displays the contents of system log files of the specified image. + * - authorization + - Displays authorization attempts of the specified image. + * - directory + - Displays user-defined log files of the specified image. + * - file + - Displays the contents of a specified user-defined log file of the specified + image. + * - tail + - Displays last lines of the system log of the specified image. + * - + - Number of lines to be displayed, default 10. +``` + +```` + +If no category is specified, the contents of the main syslog file are +displayed. + +:::{hint} +Use `show log | strip-private` to hide private data +when displaying your logs. +::: diff --git a/docs/configuration/system/md-task-scheduler.md b/docs/configuration/system/md-task-scheduler.md new file mode 100644 index 00000000..94ca9f4d --- /dev/null +++ b/docs/configuration/system/md-task-scheduler.md @@ -0,0 +1,45 @@ +(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 executed 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 \ interval \ + +Specify the time interval when `` 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 \ crontab-spec \ + +Set execution time in common cron time format. A cron `` of +``30 */6 * * *`` would execute the `` at minute 30 past every 6th hour. +``` + +```{cfgcmd} set system task-scheduler task \ executable path \ + +Specify absolute `` to script which will be run when `` is +executed. +``` + +```{cfgcmd} set system task-scheduler task \ executable arguments \ + +Arguments which will be passed to the executable. +``` + +[cron]: https://en.wikipedia.org/wiki/Cron diff --git a/docs/configuration/system/md-time-zone.md b/docs/configuration/system/md-time-zone.md new file mode 100644 index 00000000..2279a773 --- /dev/null +++ b/docs/configuration/system/md-time-zone.md @@ -0,0 +1,17 @@ +(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 \ + +Specify the systems \ 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/md-updates.md b/docs/configuration/system/md-updates.md new file mode 100644 index 00000000..c82d37be --- /dev/null +++ b/docs/configuration/system/md-updates.md @@ -0,0 +1,36 @@ +# Updates + +VyOS supports online checking for updates + +## Configuration + +```{cfgcmd} set system update-check auto-check + +Configure auto-checking for new images +``` + +```{cfgcmd} set system update-check url \ + +Configure a URL that contains information about images. +``` + + +## Example + +```none +set system update-check auto-check +set system update-check url 'https://raw.githubusercontent.com/vyos/vyos-rolling-nightly-builds/main/version.json' +``` + +Check: + +```none +vyos@r4:~$ show system updates +Current version: 1.5-rolling-202312220023 + +Update available: 1.5-rolling-202312250024 +Update URL: https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.5-rolling-202312250024/1.5-rolling-202312250024-amd64.iso +vyos@r4:~$ + +vyos@r4:~$ add system image latest +``` diff --git a/docs/configuration/system/md-watchdog.md b/docs/configuration/system/md-watchdog.md new file mode 100644 index 00000000..700051a6 --- /dev/null +++ b/docs/configuration/system/md-watchdog.md @@ -0,0 +1,212 @@ +(system-watchdog)= + +# Watchdog + +VyOS supports hardware watchdog timers to automatically reboot the system if +it becomes unresponsive. This is particularly useful for remote or embedded +systems where physical access is limited. + +A watchdog timer is a hardware or software mechanism that automatically resets +the system if the operating system stops responding within a configured timeout +period. The system will periodically notify the watchdog that it is still +running. If the watchdog is not notified within the timeout period, the watchdog +will reset the system. + +## Configuration + +The watchdog feature is configured under the `system watchdog` configuration +tree. The presence of the `system watchdog` node enables the watchdog feature. + +```{cfgcmd} set system watchdog + +Enable watchdog support. + +The watchdog is enabled only when a watchdog device is available as +``/dev/watchdog0``. + +:::{note} +If multiple watchdog devices are present, only the first watchdog +device is supported (VyOS uses ``/dev/watchdog0`` only). +::: +If ``/dev/watchdog0`` does not exist and no module is configured, commit will +fail. If a module is configured but ``/dev/watchdog0`` still cannot be +created, VyOS will emit a warning and will not enable the systemd watchdog. +``` + +```{cfgcmd} set system watchdog module \ + +Specify the kernel watchdog driver module to load for ``/dev/watchdog0``. + +The configured module must be a watchdog driver module, not an arbitrary +kernel module. + +**In most cases, this option is not required** as the kernel will +automatically load the appropriate watchdog driver for your system. Use this +option if the kernel fails to load the required driver, or when you want to +use the software watchdog (``softdog``). + +Common modules include: +* ``softdog`` - Software watchdog timer (available on all systems) +* ``iTCO_wdt`` - Intel TCO watchdog timer +* ``sp5100_tco`` - AMD SP5100 TCO watchdog timer +* ``i6300esb`` - Intel 6300ESB watchdog timer +* ``ipmi_watchdog`` - IPMI watchdog timer + +:::{warning} +``softdog`` is not a hardware watchdog. It is implemented using +kernel timers and therefore depends on the Linux kernel continuing to run. +In some fault conditions (for example, a kernel hang), ``softdog`` may not +be able to trigger a reset. + +Prefer a hardware watchdog driver whenever possible, as hardware watchdogs +can operate independently of the operating system. +::: + +If no module is specified, VyOS will use an existing ``/dev/watchdog0`` +device if available. + +:::{note} +If a module is specified but a different driver is actually bound +to ``watchdog0``, VyOS will emit a warning during commit. +::: +Example: + +:::{code-block} none +set system watchdog module softdog +::: +``` + +```{cfgcmd} set system watchdog timeout \ +:defaultvalue: + +Set the watchdog timeout for normal runtime operation in seconds. + +Valid range: 1-65535 seconds + +:::{note} +Some watchdog drivers expose minimum and maximum supported runtime +timeouts via sysfs. When available, VyOS validates ``timeout`` against +those driver limits during commit. +::: + +This is the interval during which the system must respond to the watchdog. +If the system does not respond within this time, the watchdog will trigger +a reboot. + +Example: + +:::{code-block} none +set system watchdog timeout 30 +::: +``` + +```{cfgcmd} set system watchdog shutdown-timeout \ +:defaultvalue: + +Set the watchdog timeout during system shutdown in seconds. + +Valid range: 60-65535 seconds + +This extended timeout allows the system to complete a graceful shutdown +without triggering the watchdog. + +:::{warning} +Setting this value too low (below 120 seconds) may cause +unclean shutdowns, as the system may not have enough time to properly +stop all services and flush disk buffers. The recommended minimum value +is 120 seconds. +::: +Example: + +:::{code-block} none +set system watchdog shutdown-timeout 180 +::: +``` + +```{cfgcmd} set system watchdog reboot-timeout \ +:defaultvalue: + +Set the watchdog timeout during system reboot in seconds. + +Valid range: 60-65535 seconds + +This extended timeout allows the system to complete the reboot process +without triggering the watchdog during the transition. + +:::{warning} +Setting this value too low (below 120 seconds) may cause +unclean reboots, as the system may not have enough time to properly +stop all services before restarting. The recommended minimum value +is 120 seconds. +::: +Example: + +:::{code-block} none +set system watchdog reboot-timeout 180 +::: +``` + + +## Examples + +### Basic Configuration with Software Watchdog + +This example configures a basic software watchdog with default timeouts: + +```none +set system watchdog module softdog +``` + +This will: +- Enable the watchdog feature +- Load the `softdog` kernel module +- Use a 10-second runtime timeout (default) +- Use 120-second shutdown and reboot timeouts (default) + +### Advanced Configuration + +This example shows a more customized configuration suitable for a production +system: + +```none +set system watchdog module iTCO_wdt +set system watchdog timeout 30 +set system watchdog shutdown-timeout 300 +set system watchdog reboot-timeout 300 +``` + +This configuration: + +- Enables the watchdog feature +- Loads the Intel TCO hardware watchdog module +- Sets a 30-second runtime timeout +- Allows 5 minutes for shutdown and reboot operations + +## Best Practices + +- **Start with conservative timeouts**: Use longer timeouts initially and + reduce them as you gain confidence in system stability. +- **Test before deployment**: Verify the watchdog works as expected in a + non-production environment before deploying to production systems. +- **Choose appropriate modules**: Use hardware watchdog modules (like + `iTCO_wdt`) when available, as they are more reliable than software + watchdogs. +- **Consider shutdown time**: Set `shutdown-timeout` and `reboot-timeout` + values high enough to allow for normal shutdown procedures, especially on + systems with many services or slow storage. +- **Monitor watchdog events**: Check system logs after any unexpected reboots + to determine if the watchdog triggered the reboot. +- **Remote systems**: For systems without physical console access, use + conservative timeout values to avoid false-positive reboots during high + load conditions. + +:::{note} +The watchdog configuration takes effect immediately after commit, +but systemd must be reloaded. This happens automatically during commit. +::: + +:::{warning} +Incorrect watchdog configuration on remote systems can result +in unexpected reboots. Always test watchdog settings in a controlled +environment before deploying to production systems. +::: diff --git a/docs/configuration/system/name-server.md b/docs/configuration/system/name-server.md deleted file mode 100644 index 9090ba5f..00000000 --- a/docs/configuration/system/name-server.md +++ /dev/null @@ -1,65 +0,0 @@ -(system-dns)= - -# System DNS - -:::{warning} -If you are configuring a VRF for management purposes, there is -currently no way to force system DNS traffic via a specific VRF. -::: - -This section describes configuring DNS on the system, namely: - -> - DNS name servers -> - Domain search order - -## DNS name servers - -```{cfgcmd} set system name-server \ - -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: - -```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 -``` - - -## 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 \ - -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. -::: - -(name-server-domain-search-order-example)= - -### Example - -The system is configured to attempt domain completion in the following -order: vyos.io (first), vyos.net (second) and vyos.network (last): - -```none -set system domain-search vyos.io -set system domain-search vyos.net -set system domain-search vyos.network -``` diff --git a/docs/configuration/system/option.md b/docs/configuration/system/option.md deleted file mode 100644 index c7a6ccf2..00000000 --- a/docs/configuration/system/option.md +++ /dev/null @@ -1,190 +0,0 @@ -(system-option)= - -# Option - -This chapter describe the possibilities of advanced system behavior. - -## General - -```{cfgcmd} set system option ctrl-alt-delete \ - -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 reboot-on-upgrade-failure \ - -Automatically reboot after `timeout` minutes into the previous running -image, that was used to perform the image upgrade. - -Reboot `timeout` is configurable in minutes. This gives the user the change -to log into the system and perform some analysis before automatic rebooting. - -Automatic reboot can be cancelled after login using: {opcmd}`reboot cancel` -``` - -```{cfgcmd} set system option startup-beep - -Play an audible beep to the system speaker when system is ready. -``` - -```{cfgcmd} set system option root-partition-auto-resize - -Enables the root partition auto-extension and resizes to the maximum -available space on system boot. -``` - - -### Kernel - -```{cfgcmd} set system option kernel disable-mitigations - -Disable all optional CPU mitigations. This improves system performance, -but it may also expose users to several CPU vulnerabilities. - -This will add the following option to the Kernel commandline: -* ``mitigations=off`` - -:::{note} -Setting will only become active with the next reboot! -::: -``` - -```{cfgcmd} set system option kernel disable-power-saving - -This will add the following two options to the Kernel commandline: -* ``intel_idle.max_cstate=0`` Disable intel_idle and fall back on acpi_idle -* ``processor.max_cstate=1`` Limit processor to maximum C-state 1 - -:::{note} -Setting will only become active with the next reboot! -::: -``` - -```{cfgcmd} set system option kernel amd-pstate-driver \ - -Enables and configures p-state driver for modern AMD Ryzen and Epyc CPUs. - -The available modes are: -* ``active`` This is the low-level firmware control mode based on the profile -set and the system governor has no effect. -* ``passive`` The driver allows the system governor to manage CPU frequency -while providing available performance states. -* ``guided`` The driver allows to set desired performance levels and the firmware -selects a performance level in this range and fitting to the current workload. - -This will add the following two options to the Kernel commandline: -* ``initcall_blacklist=acpi_cpufreq_init`` Disable default ACPI CPU frequency scale -* ``amd_pstate={mode}`` Sets the p-state mode - -:::{note} -Setting will only become active with the next reboot! -::: - -:::{seealso} - -::: -``` - -```{cfgcmd} set system option kernel quiet - -Suppress most kernel messages during boot. This is useful for systems with -embedded serial console interfaces to speed up the boot process. -``` - - -## HTTP client - -```{cfgcmd} set system option http-client source-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 \ - -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. -::: - -## SSH client - -```{cfgcmd} set system option ssh-client source-address \ - -Use the specified address on the local machine as the source address of the -connection. Only useful on systems with more than one address. -``` - -```{cfgcmd} set system option ssh-client source-interface \ - -Use the address of the specified interface on the local machine as the -source address of the connection. -``` - - -## Keyboard Layout - -When starting a VyOS live system (the installation CD) the configured keyboard -layout defaults to US. As this might not suite everyone's use case you can adjust -the used keyboard layout on the system console. - -```{cfgcmd} set system option keyboard-layout \ - -Change system keyboard layout to given language. - -Defaults to ``us``. - -:::{note} -Changing the keymap only has an effect on the system console, using -SSH or 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. - -:::{seealso} - -::: - -```{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. -``` \ No newline at end of file diff --git a/docs/configuration/system/proxy.md b/docs/configuration/system/proxy.md deleted file mode 100644 index 286e835f..00000000 --- a/docs/configuration/system/proxy.md +++ /dev/null @@ -1,27 +0,0 @@ -(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 \ - -Set proxy for all connections initiated by VyOS, including HTTP, HTTPS, and -FTP (anonymous ftp). -``` -```{cfgcmd} set system proxy port \ - -Configure proxy port if it does not listen to the default port 80. -``` -```{cfgcmd} set system proxy 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 \ - -Some proxys require/support the "basic" HTTP authentication scheme as per -{rfc}`7617`, thus a password can be configured. -``` \ No newline at end of file diff --git a/docs/configuration/system/sflow.md b/docs/configuration/system/sflow.md deleted file mode 100644 index 350bbdd8..00000000 --- a/docs/configuration/system/sflow.md +++ /dev/null @@ -1,66 +0,0 @@ -# sFlow - -VyOS supports sFlow 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. - -sFlow is a technology that enables monitoring of network traffic by sending sampled packets to a collector device. - -The sFlow accounting based on hsflowd - -## Configuration - -```{cfgcmd} set system sflow agent-address \ - -Configure sFlow agent IPv4 or IPv6 address -``` -```{cfgcmd} set system sflow agent-interface \ - -Configure agent IP address associated with this interface. -``` -```{cfgcmd} set system sflow drop-monitor-limit \ - - Dropped packets reported on DROPMON Netlink channel by Linux kernel are exported via the standard sFlow v5 extension for reporting dropped packets -``` - - -```{cfgcmd} set system sflow interface \ - -Configure and enable collection of flow information for the interface identified by \. - -You can configure multiple interfaces which would participate in sflow accounting. -``` -```{cfgcmd} set system sflow polling \ - - Configure schedule counter-polling in seconds (default: 30) -``` - - -```{cfgcmd} set system sflow sampling-rate \ - -Use this command to configure the sampling rate for sFlow accounting (default: 1000) -``` - - -```{cfgcmd} set system sflow server \ port \ - -Configure address of sFlow collector. sFlow server at \ can be both listening on an IPv4 or IPv6 address. -``` - - -```{cfgcmd} set system sflow enable-egress - -Use this command to if you need to sample also egress traffic -``` - -## Example - -```none -set system sflow agent-address '192.0.2.14' -set system sflow agent-interface 'eth0' -set system sflow drop-monitor-limit '50' -set system sflow interface 'eth0' -set system sflow interface 'eth1' -set system sflow polling '30' -set system sflow sampling-rate '1000' -set system sflow server 192.0.2.1 port '6343' -set system sflow server 203.0.113.23 port '6343' -``` diff --git a/docs/configuration/system/sysctl.md b/docs/configuration/system/sysctl.md deleted file mode 100644 index 90434fb2..00000000 --- a/docs/configuration/system/sysctl.md +++ /dev/null @@ -1,16 +0,0 @@ -(sysctl)= - -# Sysctl - -:::{note} -This page is a stub and needs expansion. Contributions -welcome via the [VyOS documentation repository](https://github.com/vyos/vyos-documentation). -::: - -This chapter describes how to configure kernel parameters at runtime. - -`sysctl` is used to modify kernel parameters at runtime. The parameters -available are those listed under /proc/sys/. - -```{cfgcmd} set system sysctl parameter \ value \ -``` \ No newline at end of file diff --git a/docs/configuration/system/syslog.md b/docs/configuration/system/syslog.md deleted file mode 100644 index ae30d272..00000000 --- a/docs/configuration/system/syslog.md +++ /dev/null @@ -1,450 +0,0 @@ -(syslog)= - -# Syslog - -## Overview - -By default, VyOS provides a minimal logging configuration with local storage -and log rotation. All errors, including local7 messages, are saved to a local -file. Emergency alerts are sent to the console. - -To change these settings, enter configuration mode. - -## Syslog configuration - -Syslog supports logging to multiple destinations: a local file, a console, or -a remote syslog server over UDP or TCP. - -The syslog configuration is organized into the following categories: - -- Global settings -- Local logging -- Console logging -- Remote logging -- TLS-encrypted remote logging - -### Global settings - -Configure the general behavior of the syslog service. - -```{cfgcmd} set system syslog marker interval \ - -**Configure the interval, in seconds, for sending syslog mark messages.** - -Syslog mark messages confirm the logging service is operational. - -Default: 1200 seconds. -``` - -```{cfgcmd} set system syslog marker disable - -Disable sending syslog mark messages. -``` - -```{cfgcmd} set system syslog preserve-fqdn - -**Configure how the logging device's hostname appears in log messages sent -to a remote syslog server.** - -If configured, the device includes its {abbr}`FQDN (Fully Qualified Domain -Name)` in log messages, even if the syslog server is in the same domain. -``` - - -### Local logging - -Configure which log messages to save to a local log file. - -```{cfgcmd} set system syslog local \ facility \ level \ - -**Configure syslog to save log messages for a specific facility and -severity level to \`\`/var/log/messages\`\`.** - -Refer to the tables below for valid facility and severity options. -``` - -(syslog-console)= - -### Console logging - -Configure which log messages to send to `/dev/console`. - -```{cfgcmd} set system syslog console facility \ level \ - -**Configure syslog to send log messages for a specific facility and severity -level to the device's console.** - -Refer to the tables below for valid facility and severity options. -``` - -(syslog-remote)= - -### Remote logging - -Configure **remote logging** to send log messages to a remote syslog server. - -Remote logging does not affect either **local** or **console logging** and -runs in parallel with them. Remote logging supports sending log messages -to multiple hosts. - -```{cfgcmd} set system syslog remote \ facility \ level \ - -**Configure log transmission to the remote syslog server for a specific -facility and severity level.** - -The serverโ€™s address can be specified using either a {abbr}`FQDN (Fully -Qualified Domain Name)` or an IP address. - -Refer to the tables below for valid facility and severity options. -``` - -```{cfgcmd} set system syslog remote \ protocol \ - -**Configure the protocol for log transmission.** - -The protocol can be either UDP or TCP. By default, log messages are sent -over UDP. -``` - -```{cfgcmd} set system syslog remote \ port \ - -**Configure the port for log transmission.** - -By default, the standard port 514 is used. -``` - -```{cfgcmd} set system syslog remote \ format include-timezone - -**Configure log transmission in the RFC 5424 format.** - -The RFC 5424 format includes the timezone in the timestamp. For example: - -:::{code-block} none -<34>1 2003-10-11T22:14:15.003-07:00 mymachine.example.com su - ID47 - BOMโ€™su rootโ€™ failed for lonvick on /dev/pts/8. -::: - -By default, log messages are sent in the RFC 3164 format. For example: - -:::{code-block} none -<34>Oct 11 22:14:15 mymachine su: โ€˜su rootโ€™ failed for lonvick on /dev/pts/8 -::: -``` - -```{cfgcmd} set system syslog remote \ format octet-counted - -**Enable octet-counted framing for log transmission.** - -When enabled, multi-line log messages are sent without splitting. Ensure -the remote server supports octet-counted framing to avoid parsing errors. - -Octet-counted framing is not available for the UDP protocol. -``` - -```{cfgcmd} set system syslog remote \ vrf \ - -Configure the {abbr}`VRF (Virtual Routing and Forwarding)` instance -for log transmission. -``` - -```{cfgcmd} set system syslog remote \ source-address \ - -Configure the source IP address (IPv4 or IPv6) for log transmission. -``` - - -#### {abbr}`TLS (Transport Layer Security)`-encrypted remote logging - -VyOS supports {abbr}`TLS (Transport Layer Security)`-encrypted remote logging -over TCP to ensure secure transmission of syslog data to remote syslog servers. - -**Prerequisites**: Before configuring {abbr}`TLS (Transport Layer -Security)`-encrypted remote logging, ensure you have: -- A valid remote syslog server address. -- Valid {abbr}`CA (Certificate Authority)` and client certificates uploaded - to the local {abbr}`PKI (Public Key Infrastructure)` storage. -- The **remote syslog transport protocol** is set to **TCP**: - - ```none - set system syslog remote
protocol tcp - ``` - -:::{note} -{abbr}`TLS (Transport Layer Security)`-encrypted remote logging is -**not supported** over **UDP**. -::: -```{cfgcmd} set system syslog remote \ tls - -Enable TLS-encrypted remote logging. - -``` - -```{cfgcmd} set system syslog remote \ tls ca-certificate \ - -**Configure the** {abbr}`CA (Certificate Authority)` **certificate.** - -The syslog client uses the {abbr}`CA (Certificate Authority)` certificate to -verify the identity of the remote syslog server. - -The {abbr}`CA (Certificate Authority)` certificate is required for **all** -authentication modes except ``anon``. - -``` - -```{cfgcmd} set system syslog remote \ tls certificate \ - -**Configure the client certificate.** - -The remote syslog server uses the client certificate to verify the identity -of the syslog client. - -The client certificate is required if the remote syslog server enforces -client certificate verification. - -``` - -````{cfgcmd} set system syslog remote \ tls auth-mode \ - -**Configure the authentication mode.** - -The authentication mode defines how the syslog client verifies the syslog -server's identity. - -The following authentication modes are available: - -```{eval-rst} -* ``anon`` **(default)**: Allows encrypted connections without verifying the syslog - server's identity. This mode is **not recommended**, as it is vulnerable to - :abbr:`MITM (Man-in-the-Middle)` attacks. -* ``fingerprint``: Verifies the serverโ€™s certificate fingerprint against the - value preconfigured with: - - .. code-block:: none - - set system syslog remote
tls permitted-peer - -* ``certvalid``: Verifies the server certificate is signed by a trusted - :abbr:`CA (Certificate Authority)`, skipping :abbr:`CN (Common Name)` check. -* ``name``: Verifies that: - - * The serverโ€™s certificate is signed by a trusted :abbr:`CA (Certificate - Authority)`. - * The :abbr:`CN (Common Name)` in the certificate matches the value - preconfigured with: - - .. code-block:: none - - set system syslog remote
tls permitted-peer - - This is a **recommended** secure mode for production environments. -``` - -```` - -```{cfgcmd} set system syslog remote \ tls permitted-peer \ - -**Configure the peer certificate identifiers.** - -The certificate identifier format depends on the authentication mode: -* ``fingerprint``: Enter the expected certificate fingerprints (SHA-1 or -SHA-256). -* ``name``: Enter the expected certificate {abbr}`CNs (Common Names)`. - -For ``anon`` and ``certvalid`` authentication modes, certificate identifiers -are not required. - -``` - -#### Examples: - -```none -# Example of 'anon' authentication mode -set system syslog remote 10.10.2.3 facility all level debug -set system syslog remote 10.10.2.3 port 6514 -set system syslog remote 10.10.2.3 protocol tcp -set system syslog remote 10.10.2.3 tls auth-mode anon -# or just use 'set system syslog remote 10.10.2.3 tls' - -# Example of 'certvalid' authentication mode -set system syslog remote elk.example.com facility all level debug -set system syslog remote elk.example.com port 6514 -set system syslog remote elk.example.com protocol tcp -set system syslog remote elk.example.com tls ca-certificate my-ca -set system syslog remote elk.example.com tls auth-mode certvalid - -# Example of 'fingerprint' authentication mode -set system syslog remote syslog.example.com facility all level debug -set system syslog remote syslog.example.com port 6514 -set system syslog remote syslog.example.com protocol tcp -set system syslog remote syslog.example.com tls ca-certificate my-ca -set system syslog remote syslog.example.com tls auth-mode fingerprint -set system syslog remote syslog.example.com tls permitted-peers 'SHA1:10:C4:26:...,SHA256:7B:4B:10:...' - -# Example of 'name' authentication mode -set system syslog remote graylog.example.com facility all level debug -set system syslog remote graylog.example.com port 6514 -set system syslog remote graylog.example.com protocol tcp -set system syslog remote graylog.example.com tls ca-certificate my-ca -set system syslog remote graylog.example.com tls certificate syslog-client -set system syslog remote graylog.example.com tls auth-mode name -set system syslog remote graylog.example.com tls permitted-peers 'graylog.example.com' -``` - -#### Security recommendations - -- For secure deployments, always use the `name` authentication mode. It - ensures that the server is validated by a trusted {abbr}`CA (Certificate - Authority)` and that the hostname matches the certificate. -- Use the `anon` authentication mode only in testing environments, as it - doesn't provide server authentication. -- Ensure private keys are generated, stored, and maintained exclusively within - the {doc}`PKI system `. -(syslog_facilities)= - -## Syslog facilities - -This section lists facilities used by syslog. Most facility names are self- -explanatory. The local0โ€“local7 facilities are used for custom purposes, such as -logging from network nodes and equipment. Facility assignment is flexible and -should be tailored to your company's needs. Consider facilities as categorization -tools, rather than strict directives. - -```{eval-rst} -+----------+----------+----------------------------------------------------+ -| 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 syslog | -+----------+----------+----------------------------------------------------+ -| 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 | local use 6 (local6) | -+----------+----------+----------------------------------------------------+ -| 23 | local7 | local use 7 (local7) | -+----------+----------+----------------------------------------------------+ -``` - -(syslog_severity_level)= - -## Severity levels - -```{eval-rst} -+-------+---------------+---------+-------------------------------------------+ -| 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 logs for a specific category on the console.** - -Use tab completion to view a list of available categories. - -If no category is specified, all logs are shown. - -``` - -````{opcmd} show log image \ [all | authorization | directory | file \ | tail \] - -**Display logs for a specific image on the console.** - -Available log categories: - -```{eval-rst} -.. list-table:: - :widths: 25 75 - :header-rows: 0 - - * - all - - Displays the contents of system log files of the specified image. - * - authorization - - Displays authorization attempts of the specified image. - * - directory - - Displays user-defined log files of the specified image. - * - file - - Displays the contents of a specified user-defined log file of the specified - image. - * - tail - - Displays last lines of the system log of the specified image. - * - - - Number of lines to be displayed, default 10. -``` - -```` - -If no category is specified, the contents of the main syslog file are -displayed. - -:::{hint} -Use `show log | strip-private` to hide private data -when displaying your logs. -::: diff --git a/docs/configuration/system/task-scheduler.md b/docs/configuration/system/task-scheduler.md deleted file mode 100644 index 94ca9f4d..00000000 --- a/docs/configuration/system/task-scheduler.md +++ /dev/null @@ -1,45 +0,0 @@ -(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 executed 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 \ interval \ - -Specify the time interval when `` 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 \ crontab-spec \ - -Set execution time in common cron time format. A cron `` of -``30 */6 * * *`` would execute the `` at minute 30 past every 6th hour. -``` - -```{cfgcmd} set system task-scheduler task \ executable path \ - -Specify absolute `` to script which will be run when `` is -executed. -``` - -```{cfgcmd} set system task-scheduler task \ executable arguments \ - -Arguments which will be passed to the executable. -``` - -[cron]: https://en.wikipedia.org/wiki/Cron diff --git a/docs/configuration/system/time-zone.md b/docs/configuration/system/time-zone.md deleted file mode 100644 index 2279a773..00000000 --- a/docs/configuration/system/time-zone.md +++ /dev/null @@ -1,17 +0,0 @@ -(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 \ - -Specify the systems \ 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/updates.md b/docs/configuration/system/updates.md deleted file mode 100644 index c82d37be..00000000 --- a/docs/configuration/system/updates.md +++ /dev/null @@ -1,36 +0,0 @@ -# Updates - -VyOS supports online checking for updates - -## Configuration - -```{cfgcmd} set system update-check auto-check - -Configure auto-checking for new images -``` - -```{cfgcmd} set system update-check url \ - -Configure a URL that contains information about images. -``` - - -## Example - -```none -set system update-check auto-check -set system update-check url 'https://raw.githubusercontent.com/vyos/vyos-rolling-nightly-builds/main/version.json' -``` - -Check: - -```none -vyos@r4:~$ show system updates -Current version: 1.5-rolling-202312220023 - -Update available: 1.5-rolling-202312250024 -Update URL: https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.5-rolling-202312250024/1.5-rolling-202312250024-amd64.iso -vyos@r4:~$ - -vyos@r4:~$ add system image latest -``` diff --git a/docs/configuration/system/watchdog.md b/docs/configuration/system/watchdog.md deleted file mode 100644 index 700051a6..00000000 --- a/docs/configuration/system/watchdog.md +++ /dev/null @@ -1,212 +0,0 @@ -(system-watchdog)= - -# Watchdog - -VyOS supports hardware watchdog timers to automatically reboot the system if -it becomes unresponsive. This is particularly useful for remote or embedded -systems where physical access is limited. - -A watchdog timer is a hardware or software mechanism that automatically resets -the system if the operating system stops responding within a configured timeout -period. The system will periodically notify the watchdog that it is still -running. If the watchdog is not notified within the timeout period, the watchdog -will reset the system. - -## Configuration - -The watchdog feature is configured under the `system watchdog` configuration -tree. The presence of the `system watchdog` node enables the watchdog feature. - -```{cfgcmd} set system watchdog - -Enable watchdog support. - -The watchdog is enabled only when a watchdog device is available as -``/dev/watchdog0``. - -:::{note} -If multiple watchdog devices are present, only the first watchdog -device is supported (VyOS uses ``/dev/watchdog0`` only). -::: -If ``/dev/watchdog0`` does not exist and no module is configured, commit will -fail. If a module is configured but ``/dev/watchdog0`` still cannot be -created, VyOS will emit a warning and will not enable the systemd watchdog. -``` - -```{cfgcmd} set system watchdog module \ - -Specify the kernel watchdog driver module to load for ``/dev/watchdog0``. - -The configured module must be a watchdog driver module, not an arbitrary -kernel module. - -**In most cases, this option is not required** as the kernel will -automatically load the appropriate watchdog driver for your system. Use this -option if the kernel fails to load the required driver, or when you want to -use the software watchdog (``softdog``). - -Common modules include: -* ``softdog`` - Software watchdog timer (available on all systems) -* ``iTCO_wdt`` - Intel TCO watchdog timer -* ``sp5100_tco`` - AMD SP5100 TCO watchdog timer -* ``i6300esb`` - Intel 6300ESB watchdog timer -* ``ipmi_watchdog`` - IPMI watchdog timer - -:::{warning} -``softdog`` is not a hardware watchdog. It is implemented using -kernel timers and therefore depends on the Linux kernel continuing to run. -In some fault conditions (for example, a kernel hang), ``softdog`` may not -be able to trigger a reset. - -Prefer a hardware watchdog driver whenever possible, as hardware watchdogs -can operate independently of the operating system. -::: - -If no module is specified, VyOS will use an existing ``/dev/watchdog0`` -device if available. - -:::{note} -If a module is specified but a different driver is actually bound -to ``watchdog0``, VyOS will emit a warning during commit. -::: -Example: - -:::{code-block} none -set system watchdog module softdog -::: -``` - -```{cfgcmd} set system watchdog timeout \ -:defaultvalue: - -Set the watchdog timeout for normal runtime operation in seconds. - -Valid range: 1-65535 seconds - -:::{note} -Some watchdog drivers expose minimum and maximum supported runtime -timeouts via sysfs. When available, VyOS validates ``timeout`` against -those driver limits during commit. -::: - -This is the interval during which the system must respond to the watchdog. -If the system does not respond within this time, the watchdog will trigger -a reboot. - -Example: - -:::{code-block} none -set system watchdog timeout 30 -::: -``` - -```{cfgcmd} set system watchdog shutdown-timeout \ -:defaultvalue: - -Set the watchdog timeout during system shutdown in seconds. - -Valid range: 60-65535 seconds - -This extended timeout allows the system to complete a graceful shutdown -without triggering the watchdog. - -:::{warning} -Setting this value too low (below 120 seconds) may cause -unclean shutdowns, as the system may not have enough time to properly -stop all services and flush disk buffers. The recommended minimum value -is 120 seconds. -::: -Example: - -:::{code-block} none -set system watchdog shutdown-timeout 180 -::: -``` - -```{cfgcmd} set system watchdog reboot-timeout \ -:defaultvalue: - -Set the watchdog timeout during system reboot in seconds. - -Valid range: 60-65535 seconds - -This extended timeout allows the system to complete the reboot process -without triggering the watchdog during the transition. - -:::{warning} -Setting this value too low (below 120 seconds) may cause -unclean reboots, as the system may not have enough time to properly -stop all services before restarting. The recommended minimum value -is 120 seconds. -::: -Example: - -:::{code-block} none -set system watchdog reboot-timeout 180 -::: -``` - - -## Examples - -### Basic Configuration with Software Watchdog - -This example configures a basic software watchdog with default timeouts: - -```none -set system watchdog module softdog -``` - -This will: -- Enable the watchdog feature -- Load the `softdog` kernel module -- Use a 10-second runtime timeout (default) -- Use 120-second shutdown and reboot timeouts (default) - -### Advanced Configuration - -This example shows a more customized configuration suitable for a production -system: - -```none -set system watchdog module iTCO_wdt -set system watchdog timeout 30 -set system watchdog shutdown-timeout 300 -set system watchdog reboot-timeout 300 -``` - -This configuration: - -- Enables the watchdog feature -- Loads the Intel TCO hardware watchdog module -- Sets a 30-second runtime timeout -- Allows 5 minutes for shutdown and reboot operations - -## Best Practices - -- **Start with conservative timeouts**: Use longer timeouts initially and - reduce them as you gain confidence in system stability. -- **Test before deployment**: Verify the watchdog works as expected in a - non-production environment before deploying to production systems. -- **Choose appropriate modules**: Use hardware watchdog modules (like - `iTCO_wdt`) when available, as they are more reliable than software - watchdogs. -- **Consider shutdown time**: Set `shutdown-timeout` and `reboot-timeout` - values high enough to allow for normal shutdown procedures, especially on - systems with many services or slow storage. -- **Monitor watchdog events**: Check system logs after any unexpected reboots - to determine if the watchdog triggered the reboot. -- **Remote systems**: For systems without physical console access, use - conservative timeout values to avoid false-positive reboots during high - load conditions. - -:::{note} -The watchdog configuration takes effect immediately after commit, -but systemd must be reloaded. This happens automatically during commit. -::: - -:::{warning} -Incorrect watchdog configuration on remote systems can result -in unexpected reboots. Always test watchdog settings in a controlled -environment before deploying to production systems. -::: -- cgit v1.2.3