diff options
| author | Yuriy Andamasov <yuriy@vyos.io> | 2026-05-10 17:23:58 +0300 |
|---|---|---|
| committer | Yuriy Andamasov <yuriy@vyos.io> | 2026-05-10 17:23:58 +0300 |
| commit | b6ff49dc4873e370083205d2f12bb2eb3894c7bc (patch) | |
| tree | 70adcc0335887a92ac99f6e20b64bc8192461412 /docs/configuration/system | |
| parent | 1d5a918294f65de399da012ab5f9b6cea224f474 (diff) | |
| download | vyos-documentation-b6ff49dc4873e370083205d2f12bb2eb3894c7bc.tar.gz vyos-documentation-b6ff49dc4873e370083205d2f12bb2eb3894c7bc.zip | |
chore: remove RST swap mechanism, archive rst-*.rst under docs/_rst_legacy/
The swap mechanism (RST-as-fallback for migrated MD pages) is dormant —
docs/_rst_overrides.txt has been empty since the MyST flip trio
(#1899/#1900/#1901) landed. The mechanism's surface area is dead weight
and the rst-*.rst shadows scattered across the source tree cause
Context7's parser to misclassify the project as RST.
Sibling PR on rolling: yuriy/remove-rst-swap-mechanism
Changes:
- Move 253 rst-*.rst shadow files into docs/_rst_legacy/ preserving
subdirectory structure. They remain in the repo for reference; Sphinx
excludes the folder via exclude_patterns.
- Strip swap_sources.py invocation from docs/Makefile.
- Strip jobs: pre_build/post_build block from .readthedocs.yml.
- Strip rst-*.rst exclude entry and the _md_exclude.txt loader from
docs/conf.py; replace with a single _rst_legacy exclude.
- Delete scripts/swap_sources.py, tests/test_swap_sources.py,
docs/_rst_overrides.txt.
- Update AGENTS.md: drop the "RST override mechanism" section and the
test-runner snippet for the deleted test.
Verified: sphinx-build -b html with --keep-going produces identical
warning set (68 unique), identical sitemap entry count (267), identical
llms.txt entry count (22), zero rst-* URLs in any artifact.
🤖 Generated by [robots](https://vyos.io)
Diffstat (limited to 'docs/configuration/system')
22 files changed, 0 insertions, 2847 deletions
diff --git a/docs/configuration/system/rst-acceleration.rst b/docs/configuration/system/rst-acceleration.rst deleted file mode 100644 index 63506d6d..00000000 --- a/docs/configuration/system/rst-acceleration.rst +++ /dev/null @@ -1,157 +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:: - - 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:: - - 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 <device> config - - Show the full config uploaded to the QAT device. - -.. opcmd:: show system acceleration qat device <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: - -.. code-block:: - - - 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: - -.. code-block:: - - 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: - -.. code-block:: - - 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. - -.. code-block:: - - 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/rst-conntrack.rst b/docs/configuration/system/rst-conntrack.rst deleted file mode 100644 index 59209b36..00000000 --- a/docs/configuration/system/rst-conntrack.rst +++ /dev/null @@ -1,210 +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. - -.. 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 <enable | disable> - :defaultvalue: - - Policy to track previously established connections. - -.. cfgcmd:: set system conntrack tcp max-retrans <1-2147483647> - :defaultvalue: - - Set the number of TCP maximum retransmit attempts. - -Contrack Timeouts -================= - -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. - -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - description <test> - - Set a rule description. - -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - destination address <ip-address> -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - source address <ip-address> - - 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: - <x.x.x.x> IPv4 address to match - <x.x.x.x/x> IPv4 prefix to match - <x.x.x.x>-<x.x.x.x> IPv4 address range to match - !<x.x.x.x> Match everything except the specified address - !<x.x.x.x/x> Match everything except the specified prefix - !<x.x.x.x>-<x.x.x.x> Match everything except the specified range - - set system conntrack timeout custom ipv6 rule <1-999999> [source | destination] address - Possible completions: - <h:h:h:h:h:h:h:h> IP address to match - <h:h:h:h:h:h:h:h/x> Subnet to match - <h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h> - IP range to match - !<h:h:h:h:h:h:h:h> Match everything except the specified address - !<h:h:h:h:h:h:h:h/x> Match everything except the specified prefix - !<h:h:h:h:h:h:h:h>-<h:h:h:h:h:h:h:h> - Match everything except the specified range - -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - destination port <value> -.. cfgcmd:: set system conntrack timeout custom [ipv4 | ipv6] rule <1-999999> - source port <value> - - Set a destination and/or source port. Accepted input: - - .. code-block:: none - - <port name> Named port (any name in /etc/services, e.g., http) - <1-65535> Numbered port - <start>-<end> 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. - -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - description <text> -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - destination address <ip-address> -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - destination port <port> -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - inbound-interface <interface> -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - protocol <protocol> -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - source address <ip-address> -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - source port <port> -.. cfgcmd:: set system conntrack ignore [ipv4 | ipv6] rule <1-999999> - tcp flags [not] <text> - - Allowed values fpr TCP flags: ``ack``, ``cwr``, ``ecn``, ``fin``, ``psh``, - ``rst``, ``syn`` and ``urg``. Multiple values are supported, and for - inverted selection use ``not``, as shown in the example. - -Conntrack log -============= - -.. cfgcmd:: set system conntrack log 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 <info | debug> - - Manage log level diff --git a/docs/configuration/system/rst-console.rst b/docs/configuration/system/rst-console.rst deleted file mode 100644 index a0e46afb..00000000 --- a/docs/configuration/system/rst-console.rst +++ /dev/null @@ -1,57 +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 <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 <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 <device> speed <speed> - - The speed (baudrate) of the console device. Supported values are: - - * ``1200`` - 1200 bps - * ``2400`` - 2400 bps - * ``4800`` - 4800 bps - * ``9600`` - 9600 bps - * ``19200`` - 19,200 bps - * ``38400`` - 38,400 bps (default for Xen console) - * ``57600`` - 57,600 bps - * ``115200`` - 115,200 bps (default for serial console) - - .. note:: If you use USB to serial converters for connecting to your VyOS - appliance please note that most of them use software emulation without flow - control. This means you should start with a common baud rate (most likely - 9600 baud) as otherwise you probably can not connect to the device using - high speed baud rates as your serial converter simply can not process this - data rate. diff --git a/docs/configuration/system/rst-default-route.rst b/docs/configuration/system/rst-default-route.rst deleted file mode 100644 index e102eb9c..00000000 --- a/docs/configuration/system/rst-default-route.rst +++ /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 <address>`), this is no longer supported -and existing configurations are migrated to the new CLI command. - -Configuration -============= - -.. cfgcmd:: set protocols static route 0.0.0.0/0 next-hop <address> - - Specify static route into the routing table sending all non local traffic - to the nexthop address `<address>`. - - -.. cfgcmd:: delete protocols static route 0.0.0.0/0 - - Delete default route from the system. - -Operation -========= - -.. opcmd:: show ip route 0.0.0.0 - - Show routing table entry for the default route. - - .. code-block:: none - - vyos@vyos:~$ show ip route 0.0.0.0 - Routing entry for 0.0.0.0/0 - Known via "static", distance 10, metric 0, best - Last update 09:46:30 ago - * 172.18.201.254, via eth0.201 - -.. seealso:: Configuration of :ref:`routing-static` - diff --git a/docs/configuration/system/rst-flow-accounting.rst b/docs/configuration/system/rst-flow-accounting.rst deleted file mode 100644 index cb18839a..00000000 --- a/docs/configuration/system/rst-flow-accounting.rst +++ /dev/null @@ -1,195 +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 <interface> - - Configure and enable collection of flow information for the interface - identified by `<interface>`. - - 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 <buffer size> - - In case, if you need to catch some logs from flow-accounting daemon, you may - configure logging facility: - -.. cfgcmd:: set system flow-accounting syslog-facility <facility> - - Configure the syslog facility used for flow-accounting log messages. - Available facilities follow standard syslog conventions (e.g., - ``daemon``, ``local0`` through ``local7``). - -Flow Export ------------ - -In addition to displaying flow accounting information locally, one can also -exported them to a collection server. - -NetFlow -^^^^^^^ - -.. cfgcmd:: set system flow-accounting netflow version <version> - - There are multiple versions available for the NetFlow data. The `<version>` - used in the exported flow data can be configured here. The following - versions are supported: - - * **5** - Most common version, but restricted to IPv4 flows only - * **9** - NetFlow version 9 (default) - * **10** - :abbr:`IPFIX (IP Flow Information Export)` as per :rfc:`3917` - -.. cfgcmd:: set system flow-accounting netflow server <address> - - Configure address of NetFlow collector. NetFlow server at `<address>` can - be both listening on an IPv4 or IPv6 address. - -.. cfgcmd:: set system flow-accounting netflow source-ip <address> - - IPv4 or IPv6 source address of NetFlow packets - -.. cfgcmd:: set system flow-accounting netflow engine-id <id> - - NetFlow engine-id which will appear in NetFlow data. The range is 0 to 255. - -.. cfgcmd:: set system flow-accounting netflow sampling-rate <rate> - - Use this command to configure the sampling rate for flow accounting. The - system samples one in every `<rate>` packets, where `<rate>` is the value - configured for the sampling-rate option. The advantage of sampling every n - packets, where n > 1, allows you to decrease the amount of processing - resources required for flow accounting. The disadvantage of not sampling - every packet is that the statistics produced are estimates of actual data - flows. - - Per default every packet is sampled (that is, the sampling rate is 1). - -.. cfgcmd:: set system flow-accounting netflow timeout expiry-interval - <interval> - - Specifies the interval at which Netflow data will be sent to a collector. As - per default, Netflow data will be sent every 60 seconds. - - You may also additionally configure timeouts for different types of - connections. - -.. cfgcmd:: set system flow-accounting netflow max-flows <n> - - If you want to change the maximum number of flows, which are tracking - simultaneously, you may do this with this command (default 8192). - -Example: --------- - -NetFlow v5 example: - -.. code-block:: none - - set system flow-accounting netflow engine-id 100 - set system flow-accounting netflow version 5 - set system flow-accounting netflow server 192.168.2.10 port 2055 - -Operation -========= - -Once flow accounting is configured on an interfaces it provides the ability to -display captured network traffic information for all configured interfaces. - -.. opcmd:: show flow-accounting interface <interface> - - Show flow accounting information for given `<interface>`. - - .. code-block:: none - - vyos@vyos:~$ show flow-accounting interface eth0 - IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES - ---------- ----------------- ----------------- ------------------------ --------------- ---------- ---------- ---------- ----- --------- ------- ------- - eth0 00:53:01:a8:28:ac ff:ff:ff:ff:ff:ff 192.0.2.2 255.255.255.255 5678 5678 udp 0 1 1 178 - eth0 00:53:01:b2:2f:34 33:33:ff:00:00:00 fe80::253:01ff:feb2:2f34 ff02::1:ff00:0 0 0 ipv6-icmp 0 2 1 144 - eth0 00:53:01:1a:b4:53 33:33:ff:00:00:00 fe80::253:01ff:fe1a:b453 ff02::1:ff00:0 0 0 ipv6-icmp 0 1 1 72 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 39 1 2064 - eth0 00:53:01:c8:33:af ff:ff:ff:ff:ff:ff 192.0.2.3 255.255.255.255 5678 5678 udp 0 1 1 154 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 146 1 9444 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 27 1 4455 - -.. opcmd:: show flow-accounting interface <interface> host <address> - - Show flow accounting information for given `<interface>` for a specific host - only. - - .. code-block:: none - - vyos@vyos:~$ show flow-accounting interface eth0 host 192.0.2.14 - IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES - ---------- ----------------- ----------------- ----------- ---------- ---------- ---------- ---------- ----- --------- ------- ------- - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 197 2 12940 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 94 1 4924 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 36 1 5877 diff --git a/docs/configuration/system/rst-frr.rst b/docs/configuration/system/rst-frr.rst deleted file mode 100644 index 2fa6e3c3..00000000 --- a/docs/configuration/system/rst-frr.rst +++ /dev/null @@ -1,43 +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 <numer> - - This allows the operator to control the number of open file descriptors - each daemon is allowed to start with. If the operator plans to run bgp with - several thousands of peers then this is where we would modify FRR to allow - this to happen. - -.. cfgcmd:: set system frr irdp - - Enable ICMP Router Discovery Protocol support. - -.. cfgcmd:: set system frr profile <traditional | datacenter> - - Select an FRR profile to adapt its default settings. If unset, the - traditional profile is applied. - -.. cfgcmd:: set system frr snmp <daemon> - - Enable SNMP support for an individual routing daemon. - - Supported daemons: - - - bgpd - - isisd - - ldpd - - ospf6d - - ospfd - - ripd - - zebra diff --git a/docs/configuration/system/rst-host-name.rst b/docs/configuration/system/rst-host-name.rst deleted file mode 100644 index 4d1567bf..00000000 --- a/docs/configuration/system/rst-host-name.rst +++ /dev/null @@ -1,68 +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 <hostname> - - The hostname can be up to 63 characters. A hostname - must start and end with a letter or digit, and have as interior characters - only letters, digits, or a hyphen. - - The default hostname used is `vyos`. - -Domain Name -=========== - -A domain name is the label (name) assigned to a computer network and is thus -unique. VyOS appends the domain name as a suffix to any unqualified name. For -example, if you set the domain name `example.com`, and you would ping the -unqualified name of `crux`, then VyOS qualifies the name to `crux.example.com`. - -.. cfgcmd:: set system domain-name <domain> - - Configure system domain name. A domain name must start and end with a letter - or digit, and have as interior characters only letters, digits, or a hyphen. - -Static Hostname Mapping -======================= - -How an IP address is assigned to an interface in :ref:`ethernet-interface`. -This section shows how to statically map an IP address to a hostname for local -(meaning on this VyOS instance) name resolution. 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 <hostname> inet <address> - - Create a static hostname mapping which will always resolve the name - `<hostname>` to IP address `<address>`. - - -.. cfgcmd:: set system static-host-mapping host-name <hostname> alias <alias> - - Create named `<alias>` for the configured static mapping for `<hostname>`. - Thus the address configured as :cfgcmd:`set system static-host-mapping - host-name <hostname> inet <address>` can be reached via multiple names. - - Multiple aliases can be specified per host-name. diff --git a/docs/configuration/system/rst-index.rst b/docs/configuration/system/rst-index.rst deleted file mode 100644 index c0113cce..00000000 --- a/docs/configuration/system/rst-index.rst +++ /dev/null @@ -1,36 +0,0 @@ -###### -System -###### - - -.. toctree:: - :maxdepth: 1 - :includehidden: - - 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:: - :maxdepth: 1 - :includehidden: - - default-route diff --git a/docs/configuration/system/rst-ip.rst b/docs/configuration/system/rst-ip.rst deleted file mode 100644 index c724faac..00000000 --- a/docs/configuration/system/rst-ip.rst +++ /dev/null @@ -1,120 +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 <number> - - Use this command to define the maximum number of entries to keep in - the ARP cache (1024, 2048, 4096, 8192, 16384, 32768). - -.. cfgcmd:: set system ip multipath layer4-hashing - - Use this command to use Layer 4 information for IPv4 ECMP hashing. - -.. cfgcmd:: set system ip import-table <table-id> - - Use this command to immport the table, by given table id, into the main RIB. - -.. cfgcmd:: set system ip import-table <table-id> distance <distance> - - Use this command to override the default distance when importing routers - from the alternate table. - -.. cfgcmd:: set system ip import-table <table-id> route-map <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 <protocol> route-map <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: - -.. code-block:: none - - vyos@vyos:~$ show ip - Possible completions: - access-list Show all IP access-lists - as-path-access-list - Show all as-path-access-lists - bgp Show Border Gateway Protocol (BGP) information - community-list - Show IP community-lists - extcommunity-list - Show extended IP community-lists - forwarding Show IP forwarding status - groups Show IP multicast group membership - igmp Show IGMP (Internet Group Management Protocol) information - large-community-list - Show IP large-community-lists - multicast Show IP multicast - ospf Show IPv4 Open Shortest Path First (OSPF) routing information - pim Show PIM (Protocol Independent Multicast) information - ports Show IP ports in use by various system services - prefix-list Show all IP prefix-lists - protocol Show IP route-maps per protocol - rip Show Routing Information Protocol (RIP) information - route Show IP routes - - -reset commands -^^^^^^^^^^^^^^ - -And the different IPv4 **reset** commands available: - -.. code-block:: none - - vyos@vyos:~$ reset ip - Possible completions: - arp Reset Address Resolution Protocol (ARP) cache - bgp Clear Border Gateway Protocol (BGP) statistics or status - igmp IGMP clear commands - multicast IP multicast routing table - route Reset IP route diff --git a/docs/configuration/system/rst-ipv6.rst b/docs/configuration/system/rst-ipv6.rst deleted file mode 100644 index eaa1d2b8..00000000 --- a/docs/configuration/system/rst-ipv6.rst +++ /dev/null @@ -1,178 +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 <number> - - Use this command to define the maximum number of entries to keep in - the Neighbor cache (1024, 2048, 4096, 8192, 16384, 32768). - -.. cfgcmd:: set system ipv6 strict-dad - - Use this command to disable IPv6 operation on interface when - Duplicate Address Detection fails on Link-Local address. - -.. cfgcmd:: set system ipv6 multipath layer4-hashing - - Use this command to user Layer 4 information for ECMP hashing. - -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 <protocol> route-map <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: - <Enter> Execute the current command - <X:X::X:X> Show IPv6 routes of given address or prefix - <X:X::X:X/M> - bgp Show IPv6 BGP routes - cache Show kernel IPv6 route cache - connected Show IPv6 connected routes - forward Show kernel IPv6 route table - isis Show IPv6 ISIS routes - kernel Show IPv6 kernel routes - ospfv3 Show IPv6 OSPF6 routes - ripng Show IPv6 RIPNG routes - static Show IPv6 static routes - summary Show IPv6 routes summary - table Show IP routes in policy table - 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: - <Enter> Execute the current command - <WORD> Show specified IPv6 prefix-list - detail Show detail of IPv6 prefix-lists - summary Show summary of IPv6 prefix-lists - -.. opcmd:: show ipv6 access-list - - Use this command to show all IPv6 access lists - - You can also specify which IPv6 access-list should be shown: - - .. code-block:: none - - vyos@vyos:~$ show ipv6 access-list - Possible completions: - <Enter> Execute the current command - <text> Show specified IPv6 access-list - - - -.. opcmd:: show ipv6 ospfv3 - - Use this command to get information about OSPFv3. - - You can get more specific OSPFv3 information by using the parameters - shown below: - - .. code-block:: none - - vyos@vyos:~$ show ipv6 ospfv3 - Possible completions: - <Enter> Execute the current command - area Show OSPFv3 spf-tree information - border-routers - Show OSPFv3 border-router (ABR and ASBR) information - database Show OSPFv3 Link state database information - interface Show OSPFv3 interface information - linkstate Show OSPFv3 linkstate routing information - neighbor Show OSPFv3 neighbor information - redistribute Show OSPFv3 redistribute External information - route Show OSPFv3 routing table information - -.. opcmd:: show ipv6 ripng - - Use this command to get information about the RIPNG protocol - -.. opcmd:: show ipv6 ripng status - - Use this command to show the status of the RIPNG protocol - - -Reset commands -^^^^^^^^^^^^^^ - -.. opcmd:: reset bgp ipv6 <address> - - Use this command to clear Border Gateway Protocol statistics or - status. - - -.. opcmd:: reset ipv6 neighbors <address | interface> - - Use this command to reset IPv6 Neighbor Discovery Protocol cache for - an address or interface. - -.. opcmd:: reset ipv6 route cache - - Use this command to flush the kernel IPv6 route cache. - An address can be added to flush it only for that route. diff --git a/docs/configuration/system/rst-lcd.rst b/docs/configuration/system/rst-lcd.rst deleted file mode 100644 index 808d45a2..00000000 --- a/docs/configuration/system/rst-lcd.rst +++ /dev/null @@ -1,45 +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 <device> - - This is the name of the physical interface used to connect to your LCD - display. Tab completion is supported and it will list you all available - serial interface. - - For serial via USB port information please refor to: :ref:`hardware_usb`. - -.. cfgcmd:: set system lcd model <model> - - This is the LCD model used in your system. - - At the time of this writing the following displays are supported: - - * Crystalfontz CFA-533 - - * Crystalfontz CFA-631 - - * Crystalfontz CFA-633 - - * Crystalfontz CFA-635 - - .. note:: We can't support all displays from the beginning. If your display - type is missing, please create a feature request via Phabricator_. - -.. include:: /_include/common-references.txt - diff --git a/docs/configuration/system/rst-login.rst b/docs/configuration/system/rst-login.rst deleted file mode 100644 index 1a2c2c5a..00000000 --- a/docs/configuration/system/rst-login.rst +++ /dev/null @@ -1,597 +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 <name> full-name "<string>" - - **Configure the real name or description for a system user.** - - If the description includes spaces, enclose ``<string>`` in double quotes. - - If the user ``<name>`` already exists, the command updates the current - description. If not, it creates a new user with the specified description. - -.. cfgcmd:: set system login user <name> authentication plaintext-password - <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 ``<name>`` 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 <name> authentication encrypted-password - <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 ``<name>`` 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 <name> authentication principal <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 ``<name>`` 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 ``<name>``. - -.. cfgcmd:: set system login user <name> 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 <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 ``<identifier>``: - -.. cfgcmd:: set system login user <username> authentication public-keys - <identifier> key <key> - - **Configure the SSH public key for the user account.** - - * ``<identifier>``: A unique label that identifies this specific key entry. - - * ``<key>``: The actual string of characters from your public key. - -.. cfgcmd:: set system login user <username> authentication public-keys - <identifier> type <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 <username> authentication public-keys - <identifier> options <options> - - **Configure specific restrictions or behaviors for an SSH public key.** - - ``<options>``: 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 <username> authentication otp key <key> - - **Configure** :abbr:`OTP (One-time password)`**-based** :abbr:`MFA - (Multi-factor Authentication)` **for a user.** - - ``<key>``: 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 <username> authentication otp rate-limit <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 <username> authentication otp rate-time <seconds> - - **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 <username> authentication otp window-size <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 <username> otp-key hotp-time - rate-limit <1-10> rate-time <15-600> window-size <1-21> - -Key generation example: - -.. code-block:: 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 <username> otp - <full | key-b32 | qrcode | uri> - -Example: - -.. code-block:: 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 <address> key <secret> - - **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 <address> port <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 <address> 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 <address> timeout <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 <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 <name> - - **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 -^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: 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 <address> key <secret> - - **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 <address> port <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 <address> 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 <address> timeout <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 <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 <name> - - 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 -^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: 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 <message> - - Configure a message to be shown to users before the ``username`` and ``password`` - prompts appear. - -.. cfgcmd:: set system login banner post-login <message> - - 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 <number> - - **Configure the maximum number of concurrent login sessions.** - -.. note:: If you limit concurrent login sessions, you must also configure a - session ``<timeout>``. This clears inactive sessions and prevents blocking new - login attempts. - -.. cfgcmd:: set system login timeout <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)`. - -.. code-block:: none - - set system login user vyos authentication public-keys 'User1' key "AAAAB3Nz...KwEW" - set system login user vyos authentication public-keys 'User1' type ssh-rsa - set system login user vyos authentication public-keys '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: - -.. code-block:: none - - add container image lfkeitel/tacacs_plus:latest - -Next, configure the containers in configuration mode: - -.. code-block:: 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/rst-name-server.rst b/docs/configuration/system/rst-name-server.rst deleted file mode 100644 index 5d08dbc5..00000000 --- a/docs/configuration/system/rst-name-server.rst +++ /dev/null @@ -1,74 +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 <address> - - Use this command to specify a DNS server for the system to be used - for DNS lookups. More than one DNS server can be added, configuring - one at a time. Both IPv4 and IPv6 addresses are supported. - - - -Example -------- - -In this example, some *OpenNIC* servers are used, two IPv4 addresses -and two IPv6 addresses: - -.. stop_vyoslinter - -.. code-block:: none - - set system name-server 176.9.37.132 - set system name-server 195.10.195.195 - set system name-server 2a01:4f8:161:3441::1 - set system name-server 2a00:f826:8:2::195 - -.. start_vyoslinter - -Domain search order -=================== - -In order for the system to use and complete unqualified host names, a -list can be defined which will be used for domain searches. - - -.. cfgcmd:: set system domain-search <domain> - - 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): - - -.. code-block:: 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/rst-option.rst b/docs/configuration/system/rst-option.rst deleted file mode 100644 index a13e38a8..00000000 --- a/docs/configuration/system/rst-option.rst +++ /dev/null @@ -1,179 +0,0 @@ -.. _system_option: - -###### -Option -###### - -This chapter describe the possibilities of advanced system behavior. - -******* -General -******* - -.. cfgcmd:: set system option ctrl-alt-delete <ignore | reboot | poweroff> - - Action which will be run once the ctrl-alt-del keystroke is received. - -.. cfgcmd:: set system option reboot-on-panic - - Automatically reboot system on kernel panic after 60 seconds. - -.. cfgcmd:: set system option reboot-on-upgrade-failure <timeout> - - 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 <mode> - - 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:: https://docs.kernel.org/admin-guide/pm/amd-pstate.html - -.. 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 <address> - - Several commands utilize cURL to initiate transfers. Configure the local - source IPv4/IPv6 address used for all cURL operations. - -.. cfgcmd:: set system option http-client source-interface <interface> - - Several commands utilize curl to initiate transfers. Configure the local - source interface used for all CURL operations. - -.. note:: `source-address` and `source-interface` can not be used at the same - time. - -********** -SSH client -********** - -.. cfgcmd:: set system option ssh-client source-address <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 <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 <us | fr | de | fi | no | dk> - - Change system keyboard layout to given language. - - Defaults to ``us``. - - .. note:: Changing the keymap only has an effect on the system console, using - SSH 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. - -.. stop_vyoslinter - -.. seealso:: https://access.redhat.com/sites/default/files/attachments/201501-perf-brief-low-latency-tuning-rhel7-v2.1.pdf - -.. start_vyoslinter - -.. cfgcmd:: set system option performance < throughput | latency > - - Configure one of the predefined system performance profiles. - - * ``throughput``: A server profile focused on improving network throughput. - This profile favors performance over power savings by setting - ``intel_pstate`` and ``max_perf_pct=100`` and increasing kernel network - buffer sizes. - - It enables transparent huge pages, and uses cpupower to set the performance - cpufreq governor. It also sets ``kernel.sched_min_granularity_ns`` to 10 us, - ``kernel.sched_wakeup_granularity_ns`` to 15 uss, and ``vm.dirty_ratio`` to - 40%. - - * ``latency``: A server profile focused on lowering network latency. - This profile favors performance over power savings by setting - ``intel_pstate`` and ``min_perf_pct=100``. - - It disables transparent huge pages, and automatic NUMA balancing. It also - uses cpupower to set the performance cpufreq governor, and requests a - cpu_dma_latency value of 1. It also sets busy_read and busy_poll times to - 50 us, and tcp_fastopen to 3. diff --git a/docs/configuration/system/rst-proxy.rst b/docs/configuration/system/rst-proxy.rst deleted file mode 100644 index 8e0339a7..00000000 --- a/docs/configuration/system/rst-proxy.rst +++ /dev/null @@ -1,28 +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 <url> - - Set proxy for all connections initiated by VyOS, including HTTP, HTTPS, and - FTP (anonymous ftp). - -.. cfgcmd:: set system proxy port <port> - - Configure proxy port if it does not listen to the default port 80. - -.. cfgcmd:: set system proxy username <username> - - Some proxys require/support the "basic" HTTP authentication scheme as per - :rfc:`7617`, thus a username can be configured. - -.. cfgcmd:: set system proxy password <password> - - Some proxys require/support the "basic" HTTP authentication scheme as per - :rfc:`7617`, thus a password can be configured. diff --git a/docs/configuration/system/rst-sflow.rst b/docs/configuration/system/rst-sflow.rst deleted file mode 100644 index 926d667b..00000000 --- a/docs/configuration/system/rst-sflow.rst +++ /dev/null @@ -1,65 +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 https://sflow.net/ - -Configuration -============= - -.. cfgcmd:: set system sflow agent-address <address> - - Configure sFlow agent IPv4 or IPv6 address - - -.. cfgcmd:: set system sflow agent-interface <interface> - - Configure agent IP address associated with this interface. - - -.. cfgcmd:: set system sflow drop-monitor-limit <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 <interface> - - Configure and enable collection of flow information for the interface identified by <interface>. - - You can configure multiple interfaces which would participate in sflow accounting. - - -.. cfgcmd:: set system sflow polling <sec> - - Configure schedule counter-polling in seconds (default: 30) - -.. cfgcmd:: set system sflow sampling-rate <rate> - - Use this command to configure the sampling rate for sFlow accounting (default: 1000) - -.. cfgcmd:: set system sflow server <address> port <port> - - Configure address of sFlow collector. sFlow server at <address> 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 -======= - -.. code-block:: 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/rst-sysctl.rst b/docs/configuration/system/rst-sysctl.rst deleted file mode 100644 index d1398822..00000000 --- a/docs/configuration/system/rst-sysctl.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. _sysctl: - -###### -Sysctl -###### - -.. note:: This page is a stub and needs expansion. - Contributions welcome via the - VyOS `documentation repository`_. - -.. _documentation repository: https://github.com/vyos/vyos-documentation - -This chapeter 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 <parameter> value <value> diff --git a/docs/configuration/system/rst-syslog.rst b/docs/configuration/system/rst-syslog.rst deleted file mode 100644 index c2767c4a..00000000 --- a/docs/configuration/system/rst-syslog.rst +++ /dev/null @@ -1,432 +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 <number> - - **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 <filename> facility <keyword> level <keyword> - - **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 <keyword> level <keyword> - - **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 <address> facility <keyword> level <keyword> - - **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 <address> protocol <udp | tcp> - - **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 <address> port <port> - - **Configure the port for log transmission.** - - By default, the standard port 514 is used. - -.. cfgcmd:: set system syslog remote <address> 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 <address> 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 <address> vrf <name> - - Configure the :abbr:`VRF (Virtual Routing and Forwarding)` instance - for log transmission. - -.. cfgcmd:: set system syslog remote <address> source-address <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**: - - .. code-block:: none - - set system syslog remote <address> protocol tcp - - -.. note:: :abbr:`TLS (Transport Layer Security)`-encrypted remote logging is - **not supported** over **UDP**. - -.. cfgcmd:: set system syslog remote <address> tls - - Enable TLS-encrypted remote logging. - -.. cfgcmd:: set system syslog remote <address> tls ca-certificate <ca_name> - - **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 <address> tls certificate <cert_name> - - **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 <address> tls auth-mode <anon | fingerprint - | certvalid | name> - - **Configure the authentication mode.** - - The authentication mode defines how the syslog client verifies the syslog - server's identity. - - The following authentication modes are available: - - * ``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 <address> tls permitted-peer <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 <address> tls permitted-peer <peer> - - This is a **recommended** secure mode for production environments. - -.. cfgcmd:: set system syslog remote <address> tls permitted-peer <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: -^^^^^^^^^ - -.. code-block:: 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 </configuration/pki/index>`. - -.. _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. - -+----------+----------+----------------------------------------------------+ -| 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 -=============== - -+-------+---------------+---------+-------------------------------------------+ -| 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 <name> - [all | authorization | directory | file <file name> | tail <lines>] - - **Display logs for a specific image on the console.** - - Available log categories: - - .. 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 <file name> - - 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. - * - <lines> - - 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/rst-task-scheduler.rst b/docs/configuration/system/rst-task-scheduler.rst deleted file mode 100644 index 4a754ba3..00000000 --- a/docs/configuration/system/rst-task-scheduler.rst +++ /dev/null @@ -1,40 +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 <task> interval <interval> - - Specify the time interval when `<task>` should be executed. The interval - is specified as number with one of the following suffixes: - - * ``none`` - Execution interval in minutes - * ``m`` - Execution interval in minutes - * ``h`` - Execution interval in hours - * ``d`` - Execution interval in days - - .. note:: If suffix is omitted, minutes are implied. - -.. cfgcmd:: set system task-scheduler task <task> crontab-spec <spec> - - Set execution time in common cron_ time format. A cron `<spec>` of - ``30 */6 * * *`` would execute the `<task>` at minute 30 past every 6th hour. - -.. cfgcmd:: set system task-scheduler task <task> executable path <path> - - Specify absolute `<path>` to script which will be run when `<task>` is - executed. - -.. cfgcmd:: set system task-scheduler task <task> executable arguments <args> - - Arguments which will be passed to the executable. - -.. _cron: https://en.wikipedia.org/wiki/Cron diff --git a/docs/configuration/system/rst-time-zone.rst b/docs/configuration/system/rst-time-zone.rst deleted file mode 100644 index 025c4376..00000000 --- a/docs/configuration/system/rst-time-zone.rst +++ /dev/null @@ -1,18 +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 <timezone> - - Specify the systems `<timezone>` as the Region/Location that best defines - your location. For example, specifying US/Pacific sets the time zone to US - Pacific time. - - Command completion can be used to list available time zones. The adjustment - for daylight time will take place automatically based on the time of year.
\ No newline at end of file diff --git a/docs/configuration/system/rst-updates.rst b/docs/configuration/system/rst-updates.rst deleted file mode 100644 index 505d9318..00000000 --- a/docs/configuration/system/rst-updates.rst +++ /dev/null @@ -1,39 +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 <url> - - Configure a URL that contains information about images. - - -Example -======= - -.. code-block:: none - - set system update-check auto-check - set system update-check url 'https://raw.githubusercontent.com/vyos/vyos-rolling-nightly-builds/main/version.json' - -Check: - -.. code-block:: none - - vyos@r4:~$ show system updates - Current version: 1.5-rolling-202312220023 - - Update available: 1.5-rolling-202312250024 - Update URL: https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.5-rolling-202312250024/1.5-rolling-202312250024-amd64.iso - vyos@r4:~$ - - vyos@r4:~$ add system image latest diff --git a/docs/configuration/system/rst-watchdog.rst b/docs/configuration/system/rst-watchdog.rst deleted file mode 100644 index 9db4a666..00000000 --- a/docs/configuration/system/rst-watchdog.rst +++ /dev/null @@ -1,208 +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 <module-name> - - 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 <seconds> - :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 <seconds> - :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 <seconds> - :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: - -.. code-block:: 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: - -.. code-block:: 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. |