From b8b3044d3c3515d91de0f44785bfd965174867df Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 21:50:08 +0300 Subject: feat: flip swap mechanism on sagitta — MD as primary, RST as override MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mirror of #1899 (current) and #1900 (circinus) for sagitta. Same logic, same scripts, per-branch file set. Changes: - Rename docs/**/md-.md to docs/**/.md (drop md- prefix) for all 210 stems previously listed in docs/_swap.txt - Rename docs/**/.rst to docs/**/rst-.rst (add rst- prefix) for the same 210 stems - Repurpose docs/_swap.txt as docs/_rst_overrides.txt; initially empty - conf.py exclude_patterns flipped: rst-*.rst excluded by default - conf.py runtime-artifact references updated to _rst_override_state.json and _md_exclude.txt - scripts/swap_sources.py imported from current (post-#1899 rewrite, with inverted rename direction) - scripts/import_myst.py and tests/test_import_myst.py deleted (obsolete) - tests/test_swap_sources.py imported from current (post-#1899 rewrite) Side-effect: fixes the same 404 on /en/1.4/ View page source links that #1899 fixed for /en/rolling/ and #1900 fixed for /en/1.5/. Per-branch differences vs #1899: - sagitta has 210 stems vs current's 254 (sagitta has no vpp pages and fewer current-only features; cli + installation/cloud/aws are still RST-only on sagitta pending the title-level fix follow-up) - otherwise the script/conf.py/test changes are byte-identical with current Generated by robots https://vyos.io --- docs/configuration/system/acceleration.md | 158 ++++++++ docs/configuration/system/acceleration.rst | 157 ------- docs/configuration/system/conntrack.md | 365 +++++++++++++++++ docs/configuration/system/conntrack.rst | 187 --------- docs/configuration/system/console.md | 47 +++ docs/configuration/system/console.rst | 46 --- docs/configuration/system/default-route.md | 40 ++ docs/configuration/system/default-route.rst | 40 -- docs/configuration/system/flow-accounting.md | 248 +++++++++++ docs/configuration/system/flow-accounting.rst | 216 ---------- docs/configuration/system/frr.md | 44 ++ docs/configuration/system/frr.rst | 38 -- docs/configuration/system/host-name.md | 70 ++++ docs/configuration/system/host-name.rst | 68 ---- docs/configuration/system/index.md | 36 ++ docs/configuration/system/index.rst | 35 -- docs/configuration/system/ip.md | 110 +++++ docs/configuration/system/ip.rst | 107 ----- docs/configuration/system/ipv6.md | 235 +++++++++++ docs/configuration/system/ipv6.rst | 205 ---------- docs/configuration/system/lcd.md | 46 +++ docs/configuration/system/lcd.rst | 45 -- docs/configuration/system/login.md | 474 ++++++++++++++++++++++ docs/configuration/system/login.rst | 425 ------------------- docs/configuration/system/md-acceleration.md | 158 -------- docs/configuration/system/md-conntrack.md | 365 ----------------- docs/configuration/system/md-console.md | 47 --- docs/configuration/system/md-default-route.md | 40 -- docs/configuration/system/md-flow-accounting.md | 248 ----------- docs/configuration/system/md-frr.md | 44 -- docs/configuration/system/md-host-name.md | 70 ---- docs/configuration/system/md-index.md | 36 -- docs/configuration/system/md-ip.md | 110 ----- docs/configuration/system/md-ipv6.md | 235 ----------- docs/configuration/system/md-lcd.md | 46 --- docs/configuration/system/md-login.md | 474 ---------------------- docs/configuration/system/md-name-server.md | 65 --- docs/configuration/system/md-option.md | 186 --------- docs/configuration/system/md-proxy.md | 27 -- docs/configuration/system/md-sflow.md | 71 ---- docs/configuration/system/md-sysctl.md | 12 - docs/configuration/system/md-syslog.md | 365 ----------------- docs/configuration/system/md-task-scheduler.md | 48 --- docs/configuration/system/md-time-zone.md | 17 - docs/configuration/system/md-updates.md | 37 -- docs/configuration/system/name-server.md | 65 +++ docs/configuration/system/name-server.rst | 74 ---- docs/configuration/system/option.md | 186 +++++++++ docs/configuration/system/option.rst | 169 -------- docs/configuration/system/proxy.md | 27 ++ docs/configuration/system/proxy.rst | 28 -- docs/configuration/system/rst-acceleration.rst | 157 +++++++ docs/configuration/system/rst-conntrack.rst | 187 +++++++++ docs/configuration/system/rst-console.rst | 46 +++ docs/configuration/system/rst-default-route.rst | 40 ++ docs/configuration/system/rst-flow-accounting.rst | 216 ++++++++++ docs/configuration/system/rst-frr.rst | 38 ++ docs/configuration/system/rst-host-name.rst | 68 ++++ docs/configuration/system/rst-index.rst | 35 ++ docs/configuration/system/rst-ip.rst | 107 +++++ docs/configuration/system/rst-ipv6.rst | 205 ++++++++++ docs/configuration/system/rst-lcd.rst | 45 ++ docs/configuration/system/rst-login.rst | 425 +++++++++++++++++++ docs/configuration/system/rst-name-server.rst | 74 ++++ docs/configuration/system/rst-option.rst | 169 ++++++++ docs/configuration/system/rst-proxy.rst | 28 ++ docs/configuration/system/rst-sflow.rst | 61 +++ docs/configuration/system/rst-sysctl.rst | 12 + docs/configuration/system/rst-syslog.rst | 389 ++++++++++++++++++ docs/configuration/system/rst-task-scheduler.rst | 40 ++ docs/configuration/system/rst-time-zone.rst | 18 + docs/configuration/system/rst-updates.rst | 37 ++ docs/configuration/system/sflow.md | 71 ++++ docs/configuration/system/sflow.rst | 61 --- docs/configuration/system/sysctl.md | 12 + docs/configuration/system/sysctl.rst | 12 - docs/configuration/system/syslog.md | 365 +++++++++++++++++ docs/configuration/system/syslog.rst | 389 ------------------ docs/configuration/system/task-scheduler.md | 48 +++ docs/configuration/system/task-scheduler.rst | 40 -- docs/configuration/system/time-zone.md | 17 + docs/configuration/system/time-zone.rst | 18 - docs/configuration/system/updates.md | 37 ++ docs/configuration/system/updates.rst | 37 -- 84 files changed, 5098 insertions(+), 5098 deletions(-) create mode 100644 docs/configuration/system/acceleration.md delete mode 100644 docs/configuration/system/acceleration.rst create mode 100644 docs/configuration/system/conntrack.md delete mode 100644 docs/configuration/system/conntrack.rst create mode 100644 docs/configuration/system/console.md delete mode 100644 docs/configuration/system/console.rst create mode 100644 docs/configuration/system/default-route.md delete mode 100644 docs/configuration/system/default-route.rst create mode 100644 docs/configuration/system/flow-accounting.md delete mode 100644 docs/configuration/system/flow-accounting.rst create mode 100644 docs/configuration/system/frr.md delete mode 100644 docs/configuration/system/frr.rst create mode 100644 docs/configuration/system/host-name.md delete mode 100644 docs/configuration/system/host-name.rst create mode 100644 docs/configuration/system/index.md delete mode 100644 docs/configuration/system/index.rst create mode 100644 docs/configuration/system/ip.md delete mode 100644 docs/configuration/system/ip.rst create mode 100644 docs/configuration/system/ipv6.md delete mode 100644 docs/configuration/system/ipv6.rst create mode 100644 docs/configuration/system/lcd.md delete mode 100644 docs/configuration/system/lcd.rst create mode 100644 docs/configuration/system/login.md delete mode 100644 docs/configuration/system/login.rst delete mode 100644 docs/configuration/system/md-acceleration.md delete mode 100644 docs/configuration/system/md-conntrack.md delete mode 100644 docs/configuration/system/md-console.md delete mode 100644 docs/configuration/system/md-default-route.md delete mode 100644 docs/configuration/system/md-flow-accounting.md delete mode 100644 docs/configuration/system/md-frr.md delete mode 100644 docs/configuration/system/md-host-name.md delete mode 100644 docs/configuration/system/md-index.md delete mode 100644 docs/configuration/system/md-ip.md delete mode 100644 docs/configuration/system/md-ipv6.md delete mode 100644 docs/configuration/system/md-lcd.md delete mode 100644 docs/configuration/system/md-login.md delete mode 100644 docs/configuration/system/md-name-server.md delete mode 100644 docs/configuration/system/md-option.md delete mode 100644 docs/configuration/system/md-proxy.md delete mode 100644 docs/configuration/system/md-sflow.md delete mode 100644 docs/configuration/system/md-sysctl.md delete mode 100644 docs/configuration/system/md-syslog.md delete mode 100644 docs/configuration/system/md-task-scheduler.md delete mode 100644 docs/configuration/system/md-time-zone.md delete mode 100644 docs/configuration/system/md-updates.md create mode 100644 docs/configuration/system/name-server.md delete mode 100644 docs/configuration/system/name-server.rst create mode 100644 docs/configuration/system/option.md delete mode 100644 docs/configuration/system/option.rst create mode 100644 docs/configuration/system/proxy.md delete mode 100644 docs/configuration/system/proxy.rst create mode 100644 docs/configuration/system/rst-acceleration.rst create mode 100644 docs/configuration/system/rst-conntrack.rst create mode 100644 docs/configuration/system/rst-console.rst create mode 100644 docs/configuration/system/rst-default-route.rst create mode 100644 docs/configuration/system/rst-flow-accounting.rst create mode 100644 docs/configuration/system/rst-frr.rst create mode 100644 docs/configuration/system/rst-host-name.rst create mode 100644 docs/configuration/system/rst-index.rst create mode 100644 docs/configuration/system/rst-ip.rst create mode 100644 docs/configuration/system/rst-ipv6.rst create mode 100644 docs/configuration/system/rst-lcd.rst create mode 100644 docs/configuration/system/rst-login.rst create mode 100644 docs/configuration/system/rst-name-server.rst create mode 100644 docs/configuration/system/rst-option.rst create mode 100644 docs/configuration/system/rst-proxy.rst create mode 100644 docs/configuration/system/rst-sflow.rst create mode 100644 docs/configuration/system/rst-sysctl.rst create mode 100644 docs/configuration/system/rst-syslog.rst create mode 100644 docs/configuration/system/rst-task-scheduler.rst create mode 100644 docs/configuration/system/rst-time-zone.rst create mode 100644 docs/configuration/system/rst-updates.rst create mode 100644 docs/configuration/system/sflow.md delete mode 100644 docs/configuration/system/sflow.rst create mode 100644 docs/configuration/system/sysctl.md delete mode 100644 docs/configuration/system/sysctl.rst create mode 100644 docs/configuration/system/syslog.md delete mode 100644 docs/configuration/system/syslog.rst create mode 100644 docs/configuration/system/task-scheduler.md delete mode 100644 docs/configuration/system/task-scheduler.rst create mode 100644 docs/configuration/system/time-zone.md delete mode 100644 docs/configuration/system/time-zone.rst create mode 100644 docs/configuration/system/updates.md delete mode 100644 docs/configuration/system/updates.rst (limited to 'docs/configuration/system') diff --git a/docs/configuration/system/acceleration.md b/docs/configuration/system/acceleration.md new file mode 100644 index 00000000..871129e6 --- /dev/null +++ b/docs/configuration/system/acceleration.md @@ -0,0 +1,158 @@ +(acceleration)= + +# Acceleration + +In this command tree, all hardware acceleration options will be handled. +At the moment only [Intel® QAT] is supported + +## Intel® QAT + +```{opcmd} show system acceleration qat + +use this command to check if there is an Intel® QAT supported Processor in your system. + +:::{code-block} none +vyos@vyos:~$ show system acceleration qat +01:00.0 Co-processor [0b40]: Intel Corporation Atom Processor C3000 Series QuickAssist Technology [8086:19e2] (rev 11) +::: + +if there is non device the command will show `` `No QAT device found` `` +``` + +```{cfgcmd} set system acceleration qat + +if there is a supported device, enable Intel® QAT +``` + + +```{opcmd} show system acceleration qat status + +Check if the Intel® QAT device is up and ready to do the job. + +:::{code-block} none +vyos@vyos:~$ show system acceleration qat status +Checking status of all devices. +There is 1 QAT acceleration device(s) in the system: +qat_dev0 - type: c3xxx, inst_id: 0, node_id: 0, bsf: 0000:01:00.0, #accel: 3 #engines: 6 state: up +::: +``` + + +### Operation Mode + +```{opcmd} show system acceleration qat device \ config + +Show the full config uploaded to the QAT device. +``` + + +```{opcmd} show system acceleration qat device \ flows + +Get an overview over the encryption counters. +``` + + +```{opcmd} show system acceleration qat interrupts + +Show binded qat device interrupts to certain core. +``` + + +### Example + +Let's build a simple VPN between 2 Intel® QAT ready devices. + +Side A: + +``` +set interfaces vti vti1 address '192.168.1.2/24' +set vpn ipsec authentication psk right id '10.10.10.2' +set vpn ipsec authentication psk right id '10.10.10.1' +set vpn ipsec authentication psk right secret 'Qwerty123' +set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes256' +set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha256' +set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '14' +set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes256' +set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha256' +set vpn ipsec interface 'eth0' +set vpn ipsec site-to-site peer right authentication local-id '10.10.10.2' +set vpn ipsec site-to-site peer right authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer right authentication remote-id '10.10.10.1' +set vpn ipsec site-to-site peer right connection-type 'initiate' +set vpn ipsec site-to-site peer right default-esp-group 'MyESPGroup' +set vpn ipsec site-to-site peer right ike-group 'MyIKEGroup' +set vpn ipsec site-to-site peer right local-address '10.10.10.2' +set vpn ipsec site-to-site peer right remote-address '10.10.10.1' +set vpn ipsec site-to-site peer right vti bind 'vti1' +``` + +Side B: + +``` +set interfaces vti vti1 address '192.168.1.1/24' +set vpn ipsec authentication psk left id '10.10.10.2' +set vpn ipsec authentication psk left id '10.10.10.1' +set vpn ipsec authentication psk left secret 'Qwerty123' +set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes256' +set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha256' +set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '14' +set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes256' +set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha256' +set vpn ipsec interface 'eth0' +set vpn ipsec site-to-site peer left authentication local-id '10.10.10.1' +set vpn ipsec site-to-site peer left authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer left authentication remote-id '10.10.10.2' +set vpn ipsec site-to-site peer left connection-type 'initiate' +set vpn ipsec site-to-site peer left default-esp-group 'MyESPGroup' +set vpn ipsec site-to-site peer left ike-group 'MyIKEGroup' +set vpn ipsec site-to-site peer left local-address '10.10.10.1' +set vpn ipsec site-to-site peer left remote-address '10.10.10.2' +set vpn ipsec site-to-site peer left vti bind 'vti1' +``` + +a bandwidth test over the VPN got these results: + +``` +Connecting to host 192.168.1.2, port 5201 +[ 9] local 192.168.1.1 port 51344 connected to 192.168.1.2 port 5201 +[ ID] Interval Transfer Bitrate Retr Cwnd +[ 9] 0.00-1.01 sec 32.3 MBytes 268 Mbits/sec 0 196 KBytes +[ 9] 1.01-2.03 sec 32.5 MBytes 268 Mbits/sec 0 208 KBytes +[ 9] 2.03-3.03 sec 32.5 MBytes 271 Mbits/sec 0 208 KBytes +[ 9] 3.03-4.04 sec 32.5 MBytes 272 Mbits/sec 0 208 KBytes +[ 9] 4.04-5.00 sec 31.2 MBytes 272 Mbits/sec 0 208 KBytes +[ 9] 5.00-6.01 sec 32.5 MBytes 272 Mbits/sec 0 234 KBytes +[ 9] 6.01-7.04 sec 32.5 MBytes 265 Mbits/sec 0 234 KBytes +[ 9] 7.04-8.04 sec 32.5 MBytes 272 Mbits/sec 0 234 KBytes +[ 9] 8.04-9.04 sec 32.5 MBytes 273 Mbits/sec 0 336 KBytes +[ 9] 9.04-10.00 sec 31.2 MBytes 272 Mbits/sec 0 336 KBytes +- - - - - - - - - - - - - - - - - - - - - - - - - +[ ID] Interval Transfer Bitrate Retr +[ 9] 0.00-10.00 sec 322 MBytes 270 Mbits/sec 0 sender +[ 9] 0.00-10.00 sec 322 MBytes 270 Mbits/sec receiver +``` + +with {cfgcmd}`set system acceleration qat` on both systems the bandwidth +increases. + +``` +Connecting to host 192.168.1.2, port 5201 +[ 9] local 192.168.1.1 port 51340 connected to 192.168.1.2 port 5201 +[ ID] Interval Transfer Bitrate Retr Cwnd +[ 9] 0.00-1.00 sec 97.3 MBytes 817 Mbits/sec 0 1000 KBytes +[ 9] 1.00-2.00 sec 92.5 MBytes 776 Mbits/sec 0 1.07 MBytes +[ 9] 2.00-3.00 sec 92.5 MBytes 776 Mbits/sec 0 820 KBytes +[ 9] 3.00-4.00 sec 92.5 MBytes 776 Mbits/sec 0 899 KBytes +[ 9] 4.00-5.00 sec 91.2 MBytes 765 Mbits/sec 0 972 KBytes +[ 9] 5.00-6.00 sec 92.5 MBytes 776 Mbits/sec 0 1.02 MBytes +[ 9] 6.00-7.00 sec 92.5 MBytes 776 Mbits/sec 0 1.08 MBytes +[ 9] 7.00-8.00 sec 92.5 MBytes 776 Mbits/sec 0 1.14 MBytes +[ 9] 8.00-9.00 sec 91.2 MBytes 765 Mbits/sec 0 915 KBytes +[ 9] 9.00-10.00 sec 92.5 MBytes 776 Mbits/sec 0 1000 KBytes +- - - - - - - - - - - - - - - - - - - - - - - - - +[ ID] Interval Transfer Bitrate Retr +[ 9] 0.00-10.00 sec 927 MBytes 778 Mbits/sec 0 sender +[ 9] 0.00-10.01 sec 925 MBytes 775 Mbits/sec receiver +``` + +[intel® qat]: https://www.intel.com/content/www/us/en/architecture-and-technology/intel-quick-assist-technology-overview.html diff --git a/docs/configuration/system/acceleration.rst b/docs/configuration/system/acceleration.rst deleted file mode 100644 index 63506d6d..00000000 --- a/docs/configuration/system/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 config - - Show the full config uploaded to the QAT device. - -.. opcmd:: show system acceleration qat device flows - - Get an overview over the encryption counters. - -.. opcmd:: show system acceleration qat interrupts - - Show binded qat device interrupts to certain core. - - -Example -======= - -Let's build a simple VPN between 2 Intel® QAT ready devices. - -Side A: - -.. 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/conntrack.md b/docs/configuration/system/conntrack.md new file mode 100644 index 00000000..b5f926b7 --- /dev/null +++ b/docs/configuration/system/conntrack.md @@ -0,0 +1,365 @@ +# 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 + +```{eval-rst} +.. cfgcmd:: set system conntrack table-size <1-50000000> + :defaultvalue: + + The connection tracking table contains one entry for each connection being + tracked by the system. +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack hash-size <1-50000000> + :defaultvalue: + + Set the size of the hash table. The connection tracking hash table makes + searching the connection tracking table faster. The hash table uses + “buckets” to record entries in the connection tracking table. +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack modules ftp +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack modules h323 +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack modules nfs +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack modules pptp +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack modules sip +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack modules sqlnet +``` + +```{eval-rst} +.. 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`. + +``` + +### Define Conection Timeouts + +VyOS supports setting timeouts for connections according to the +connection type. You can set timeout values for generic connections, for ICMP +connections, UDP connections, or for TCP connections in a number of different +states. + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout icmp <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout other <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout tcp close <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout tcp close-wait <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout tcp established <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout tcp fin-wait <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout tcp last-ack <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout tcp syn-recv <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout tcp syn-sent <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout tcp time-wait <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout udp other <1-21474836> + :defaultvalue: +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout udp stream <1-21474836> + :defaultvalue: + + Set the timeout in secounds for a protocol or state. + +``` + +You can also define custom timeout values to apply to a specific subset of +connections, based on a packet and flow selector. To do this, you need to +create a rule defining the packet and flow selector. + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> description + + Set a rule description. + +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> destination address +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> source address + + set a destination and/or source address. Accepted input: + + .. code-block:: none + + IP address to match + Subnet to match + - + IP range to match + ! Match everything except the specified address + ! Match everything except the specified subnet + !- + Match everything except the specified range +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> destination port +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> source port + + Set a destination and/or source port. Accepted input: + + .. code-block:: none + + Named port (any name in /etc/services, e.g., http) + <1-65535> Numbered port + - Numbered port range (e.g., 1001-1005) + + Multiple destination ports can be specified as a comma-separated list. + The whole list can also be "negated" using '!'. For example: + `!22,telnet,http,123,1001-1005`` + + +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol icmp <1-21474836> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol other <1-21474836> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp close <1-21474836> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp close-wait <1-21474836> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp established <1-21474836> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp fin-wait <1-21474836> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp last-ack <1-21474836> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp syn-recv <1-21474836> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp syn-sent <1-21474836> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp time-wait <1-21474836> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol udp other <1-21474836> +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol udp stream <1-21474836> + + Set the timeout in secounds for a protocol or state in a custom rule. + +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack tcp half-open-connections <1-21474836> + :defaultvalue: + + Set the maximum number of TCP half-open connections. +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack tcp loose + :defaultvalue: + + Policy to track previously established connections. +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack tcp max-retrans <1-2147483647> + :defaultvalue: + + Set the number of TCP maximum retransmit attempts. +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack ignore rule <1-9999> description +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack ignore rule <1-9999> destination address +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack ignore rule <1-9999> destination port +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack ignore rule <1-9999> inbound-interface +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack ignore rule <1-9999> protocol +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack ignore rule <1-9999> source address +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack ignore rule <1-9999> source port + + Customized ignore rules, based on a packet and flow selector. +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log icmp destroy +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log icmp new +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log icmp update +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log other destroy +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log other new +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log other update +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log tcp destroy +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log tcp new +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log tcp update close-wait +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log tcp update established +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log tcp update fin-wait +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log tcp update last-ack +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log tcp update syn-received +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log tcp update time-wait +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log udp destroy +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log udp new +``` + +```{eval-rst} +.. cfgcmd:: set system conntrack log udp update + + Log the connection tracking events per protocol. +``` diff --git a/docs/configuration/system/conntrack.rst b/docs/configuration/system/conntrack.rst deleted file mode 100644 index 68a4f2b8..00000000 --- a/docs/configuration/system/conntrack.rst +++ /dev/null @@ -1,187 +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`. - - -Define Conection Timeouts -========================= - -VyOS supports setting timeouts for connections according to the -connection type. You can set timeout values for generic connections, for ICMP -connections, UDP connections, or for TCP connections in a number of different -states. - -.. cfgcmd:: set system conntrack timeout icmp <1-21474836> - :defaultvalue: -.. cfgcmd:: set system conntrack timeout other <1-21474836> - :defaultvalue: -.. cfgcmd:: set system conntrack timeout tcp close <1-21474836> - :defaultvalue: -.. cfgcmd:: set system conntrack timeout tcp close-wait <1-21474836> - :defaultvalue: -.. cfgcmd:: set system conntrack timeout tcp established <1-21474836> - :defaultvalue: -.. cfgcmd:: set system conntrack timeout tcp fin-wait <1-21474836> - :defaultvalue: -.. cfgcmd:: set system conntrack timeout tcp last-ack <1-21474836> - :defaultvalue: -.. cfgcmd:: set system conntrack timeout tcp syn-recv <1-21474836> - :defaultvalue: -.. cfgcmd:: set system conntrack timeout tcp syn-sent <1-21474836> - :defaultvalue: -.. cfgcmd:: set system conntrack timeout tcp time-wait <1-21474836> - :defaultvalue: -.. cfgcmd:: set system conntrack timeout udp other <1-21474836> - :defaultvalue: -.. cfgcmd:: set system conntrack timeout udp stream <1-21474836> - :defaultvalue: - - Set the timeout in secounds for a protocol or state. - - -You can also define custom timeout values to apply to a specific subset of -connections, based on a packet and flow selector. To do this, you need to -create a rule defining the packet and flow selector. - -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> description - - Set a rule description. - - -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> destination address -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> source address - - set a destination and/or source address. Accepted input: - - .. code-block:: none - - IP address to match - Subnet to match - - - IP range to match - ! Match everything except the specified address - ! Match everything except the specified subnet - !- - Match everything except the specified range - -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> destination port -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> source port - - Set a destination and/or source port. Accepted input: - - .. code-block:: none - - Named port (any name in /etc/services, e.g., http) - <1-65535> Numbered port - - Numbered port range (e.g., 1001-1005) - - Multiple destination ports can be specified as a comma-separated list. - The whole list can also be "negated" using '!'. For example: - `!22,telnet,http,123,1001-1005`` - - - -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol icmp <1-21474836> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol other <1-21474836> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp close <1-21474836> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp close-wait <1-21474836> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp established <1-21474836> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp fin-wait <1-21474836> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp last-ack <1-21474836> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp syn-recv <1-21474836> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp syn-sent <1-21474836> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp time-wait <1-21474836> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol udp other <1-21474836> -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol udp stream <1-21474836> - - Set the timeout in secounds for a protocol or state in a custom rule. - - -.. cfgcmd:: set system conntrack tcp half-open-connections <1-21474836> - :defaultvalue: - - Set the maximum number of TCP half-open connections. - -.. cfgcmd:: set system conntrack tcp loose - :defaultvalue: - - Policy to track previously established connections. - -.. cfgcmd:: set system conntrack tcp max-retrans <1-2147483647> - :defaultvalue: - - Set the number of TCP maximum retransmit attempts. - -.. cfgcmd:: set system conntrack ignore rule <1-9999> description -.. cfgcmd:: set system conntrack ignore rule <1-9999> destination address -.. cfgcmd:: set system conntrack ignore rule <1-9999> destination port -.. cfgcmd:: set system conntrack ignore rule <1-9999> inbound-interface -.. cfgcmd:: set system conntrack ignore rule <1-9999> protocol -.. cfgcmd:: set system conntrack ignore rule <1-9999> source address -.. cfgcmd:: set system conntrack ignore rule <1-9999> source port - - Customized ignore rules, based on a packet and flow selector. - -.. cfgcmd:: set system conntrack log icmp destroy -.. cfgcmd:: set system conntrack log icmp new -.. cfgcmd:: set system conntrack log icmp update -.. cfgcmd:: set system conntrack log other destroy -.. cfgcmd:: set system conntrack log other new -.. cfgcmd:: set system conntrack log other update -.. cfgcmd:: set system conntrack log tcp destroy -.. cfgcmd:: set system conntrack log tcp new -.. cfgcmd:: set system conntrack log tcp update close-wait -.. cfgcmd:: set system conntrack log tcp update established -.. cfgcmd:: set system conntrack log tcp update fin-wait -.. cfgcmd:: set system conntrack log tcp update last-ack -.. cfgcmd:: set system conntrack log tcp update syn-received -.. cfgcmd:: set system conntrack log tcp update time-wait -.. cfgcmd:: set system conntrack log udp destroy -.. cfgcmd:: set system conntrack log udp new -.. cfgcmd:: set system conntrack log udp update - - Log the connection tracking events per protocol. \ No newline at end of file diff --git a/docs/configuration/system/console.md b/docs/configuration/system/console.md new file mode 100644 index 00000000..adcaef8c --- /dev/null +++ b/docs/configuration/system/console.md @@ -0,0 +1,47 @@ +(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. + +```{eval-rst} +.. cfgcmd:: set system console device + + Defines the specified device as a system console. Available console devices + can be (see completion helper): + + * ``ttySN`` - Serial device name + * ``ttyUSBX`` - USB Serial device name + * ``hvc0`` - Xen console +``` + +```{eval-rst} +.. cfgcmd:: set system console device speed + + The speed (baudrate) of the console device. Supported values are: + + * ``1200`` - 1200 bps + * ``2400`` - 2400 bps + * ``4800`` - 4800 bps + * ``9600`` - 9600 bps + * ``19200`` - 19,200 bps + * ``38400`` - 38,400 bps (default for Xen console) + * ``57600`` - 57,600 bps + * ``115200`` - 115,200 bps (default for serial console) + + .. note:: If you use USB to serial converters for connecting to your VyOS + appliance please note that most of them use software emulation without flow + control. This means you should start with a common baud rate (most likely + 9600 baud) as otherwise you probably can not connect to the device using + high speed baud rates as your serial converter simply can not process this + data rate. +``` diff --git a/docs/configuration/system/console.rst b/docs/configuration/system/console.rst deleted file mode 100644 index 1f917e54..00000000 --- a/docs/configuration/system/console.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. _serial-console: - -############## -Serial Console -############## - -For the average user a serial console has no advantage over a console offered -by a directly attached keyboard and screen. Serial consoles are much slower, -taking up to a second to fill a 80 column by 24 line screen. Serial consoles -generally only support non-proportional ASCII text, with limited support for -languages other than English. - -There are some scenarios where serial consoles are useful. System administration -of remote computers is usually done using :ref:`ssh`, but there are times when -access to the console is the only way to diagnose and correct software failures. -Major upgrades to the installed distribution may also require console access. - - -.. cfgcmd:: set system console device - - Defines the specified device as a system console. Available console devices - can be (see completion helper): - - * ``ttySN`` - Serial device name - * ``ttyUSBX`` - USB Serial device name - * ``hvc0`` - Xen console - -.. cfgcmd:: set system console device speed - - The speed (baudrate) of the console device. Supported values are: - - * ``1200`` - 1200 bps - * ``2400`` - 2400 bps - * ``4800`` - 4800 bps - * ``9600`` - 9600 bps - * ``19200`` - 19,200 bps - * ``38400`` - 38,400 bps (default for Xen console) - * ``57600`` - 57,600 bps - * ``115200`` - 115,200 bps (default for serial console) - - .. note:: If you use USB to serial converters for connecting to your VyOS - appliance please note that most of them use software emulation without flow - control. This means you should start with a common baud rate (most likely - 9600 baud) as otherwise you probably can not connect to the device using - high speed baud rates as your serial converter simply can not process this - data rate. diff --git a/docs/configuration/system/default-route.md b/docs/configuration/system/default-route.md new file mode 100644 index 00000000..9f2793d1 --- /dev/null +++ b/docs/configuration/system/default-route.md @@ -0,0 +1,40 @@ +(default-gateway)= + +# Default Gateway/Route + +In the past (VyOS 1.1) used a gateway-address configured under the system tree +({cfgcmd}`set system gateway-address
`), this is no longer supported +and existing configurations are migrated to the new CLI command. + +## Configuration + +```{cfgcmd} set protocols static route 0.0.0.0/0 next-hop \ + +Specify static route into the routing table sending all non local traffic +to the nexthop address \. +``` + +```{cfgcmd} delete protocols static route 0.0.0.0/0 + +Delete default route from the system. +``` + + +## Operation + +```{opcmd} show ip route 0.0.0.0 + +Show routing table entry for the default route. + +:::{code-block} none +vyos@vyos:~$ show ip route 0.0.0.0 +Routing entry for 0.0.0.0/0 +Known via "static", distance 10, metric 0, best +Last update 09:46:30 ago +* 172.18.201.254, via eth0.201 +::: +``` + +:::{seealso} +Configuration of {ref}`routing-static` +::: diff --git a/docs/configuration/system/default-route.rst b/docs/configuration/system/default-route.rst deleted file mode 100644 index e102eb9c..00000000 --- a/docs/configuration/system/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
`), this is no longer supported -and existing configurations are migrated to the new CLI command. - -Configuration -============= - -.. cfgcmd:: set protocols static route 0.0.0.0/0 next-hop
- - Specify static route into the routing table sending all non local traffic - to the nexthop address `
`. - - -.. cfgcmd:: delete protocols static route 0.0.0.0/0 - - Delete default route from the system. - -Operation -========= - -.. opcmd:: show ip route 0.0.0.0 - - Show routing table entry for the default route. - - .. code-block:: none - - vyos@vyos:~$ show ip route 0.0.0.0 - Routing entry for 0.0.0.0/0 - Known via "static", distance 10, metric 0, best - Last update 09:46:30 ago - * 172.18.201.254, via eth0.201 - -.. seealso:: Configuration of :ref:`routing-static` - diff --git a/docs/configuration/system/flow-accounting.md b/docs/configuration/system/flow-accounting.md new file mode 100644 index 00000000..9b328fff --- /dev/null +++ b/docs/configuration/system/flow-accounting.md @@ -0,0 +1,248 @@ +(flow-accounting)= + +# Flow Accounting + +VyOS supports flow-accounting for both IPv4 and IPv6 traffic. The system acts +as a flow exporter, and you are free to use it with any compatible collector. + +Flows can be exported via two different protocols: NetFlow (versions 5, 9 and +10/IPFIX) and sFlow. Additionally, you may save flows to an in-memory table +internally in a router. + +:::{warning} +You need to disable the in-memory table in production environments! +Using {abbr}`IMT (In-Memory Table)` may lead to heavy CPU overloading and +unstable flow-accounting behavior. +::: + +## NetFlow / IPFIX + +NetFlow is a feature that was introduced on Cisco routers around 1996 that +provides the ability to collect IP network traffic as it enters or exits an +interface. By analyzing the data provided by NetFlow, a network administrator +can determine things such as the source and destination of traffic, class of +service, and the causes of congestion. A typical flow monitoring setup (using +NetFlow) consists of three main components: + +- **exporter**: aggregates packets into flows and exports flow records towards + one or more flow collectors +- **collector**: responsible for reception, storage and pre-processing of flow + data received from a flow exporter +- **application**: analyzes received flow data in the context of intrusion + detection or traffic profiling, for example + +For connectionless protocols as like ICMP and UDP, a flow is considered +complete once no more packets for this flow appear after configurable timeout. + +NetFlow is usually enabled on a per-interface basis to limit load on the router +components involved in NetFlow, or to limit the amount of NetFlow records +exported. + +## Configuration + +:::{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. + +```{eval-rst} +.. cfgcmd:: set system flow-accounting interface + + Configure and enable collection of flow information for the interface + identified by ``. + + You can configure multiple interfaces which whould participate in flow + accounting. +``` + +:::{note} +Will be recorded only packets/flows on **incoming** direction in +configured interfaces by default. +::: + +By default, recorded flows will be saved internally and can be listed with the +CLI command. You may disable using the local in-memory table with the command: + +```{eval-rst} +.. cfgcmd:: set system flow-accounting disable-imt + + If you need to sample also egress traffic, you may want to + configure egress flow-accounting: +``` + +```{eval-rst} +.. 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: +``` + +```{eval-rst} +.. cfgcmd:: set system flow-accounting buffer-size + + In case, if you need to catch some logs from flow-accounting daemon, you may + configure logging facility: +``` + +```{eval-rst} +.. cfgcmd:: set system flow-accounting syslog-facility + + TBD +``` + +### Flow Export + +In addition to displaying flow accounting information locally, one can also +exported them to a collection server. + +#### NetFlow + +```{eval-rst} +.. cfgcmd:: set system flow-accounting netflow version + + There are multiple versions available for the NetFlow data. The `` + used in the exported flow data can be configured here. The following + versions are supported: + + * **5** - Most common version, but restricted to IPv4 flows only + * **9** - NetFlow version 9 (default) + * **10** - {abbr}`IPFIX (IP Flow Information Export)` as per {rfc}`3917` +``` + +```{eval-rst} +.. cfgcmd:: set system flow-accounting netflow server
+ + Configure address of NetFlow collector. NetFlow server at `
` can + be both listening on an IPv4 or IPv6 address. +``` + +```{eval-rst} +.. cfgcmd:: set system flow-accounting netflow source-ip
+ + IPv4 or IPv6 source address of NetFlow packets +``` + +```{eval-rst} +.. cfgcmd:: set system flow-accounting netflow engine-id + + NetFlow engine-id which will appear in NetFlow data. The range is 0 to 255. +``` + +```{eval-rst} +.. cfgcmd:: set system flow-accounting netflow sampling-rate + + Use this command to configure the sampling rate for flow accounting. The + system samples one in every `` packets, where `` is the value + configured for the sampling-rate option. The advantage of sampling every n + packets, where n > 1, allows you to decrease the amount of processing + resources required for flow accounting. The disadvantage of not sampling + every packet is that the statistics produced are estimates of actual data + flows. + + Per default every packet is sampled (that is, the sampling rate is 1). +``` + +```{eval-rst} +.. cfgcmd:: set system flow-accounting netflow timeout expiry-interval + + + Specifies the interval at which Netflow data will be sent to a collector. As + per default, Netflow data will be sent every 60 seconds. + + You may also additionally configure timeouts for different types of + connections. +``` + +```{eval-rst} +.. cfgcmd:: set system flow-accounting netflow max-flows + + If you want to change the maximum number of flows, which are tracking + simultaneously, you may do this with this command (default 8192). +``` + +#### sFlow + +:::{note} +Using `system sflow` is recommended in favor of +`system flow-accounting`. See [sflow](sflow.html) +::: + +```{eval-rst} +.. cfgcmd:: set system flow-accounting sflow server
+ + Configure address of sFlow collector. sFlow server at `
` can + be an IPv4 or IPv6 address. But you cannot export to both IPv4 and + IPv6 collectors at the same time! +``` + +```{eval-rst} +.. cfgcmd:: set system flow-accounting sflow sampling-rate + + Enable sampling of packets, which will be transmitted to sFlow collectors. +``` + +```{eval-rst} +.. cfgcmd:: set system flow-accounting sflow agent-address
+ + Configure a sFlow agent address. It can be IPv4 or IPv6 address, but you + must set the same protocol, which is used for sFlow collector addresses. By + default, using router-id from BGP or OSPF protocol, or the primary IP + address from the first interface. +``` + +### Example: + +NetFlow v5 example: + +```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. + +```{eval-rst} +.. opcmd:: show flow-accounting interface + + Show flow accounting information for given ``. + + .. code-block:: none + + vyos@vyos:~$ show flow-accounting interface eth0 + IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES + ---------- ----------------- ----------------- ------------------------ --------------- ---------- ---------- ---------- ----- --------- ------- ------- + eth0 00:53:01:a8:28:ac ff:ff:ff:ff:ff:ff 192.0.2.2 255.255.255.255 5678 5678 udp 0 1 1 178 + eth0 00:53:01:b2:2f:34 33:33:ff:00:00:00 fe80::253:01ff:feb2:2f34 ff02::1:ff00:0 0 0 ipv6-icmp 0 2 1 144 + eth0 00:53:01:1a:b4:53 33:33:ff:00:00:00 fe80::253:01ff:fe1a:b453 ff02::1:ff00:0 0 0 ipv6-icmp 0 1 1 72 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 39 1 2064 + eth0 00:53:01:c8:33:af ff:ff:ff:ff:ff:ff 192.0.2.3 255.255.255.255 5678 5678 udp 0 1 1 154 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 146 1 9444 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 27 1 4455 +``` + +```{eval-rst} +.. opcmd:: show flow-accounting interface host
+ + Show flow accounting information for given `` for a specific host + only. + + .. code-block:: none + + vyos@vyos:~$ show flow-accounting interface eth0 host 192.0.2.14 + IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES + ---------- ----------------- ----------------- ----------- ---------- ---------- ---------- ---------- ----- --------- ------- ------- + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 197 2 12940 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 94 1 4924 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 36 1 5877 +``` diff --git a/docs/configuration/system/flow-accounting.rst b/docs/configuration/system/flow-accounting.rst deleted file mode 100644 index 7ed2d88c..00000000 --- a/docs/configuration/system/flow-accounting.rst +++ /dev/null @@ -1,216 +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 two different protocols: NetFlow (versions 5, 9 and -10/IPFIX) and sFlow. Additionally, you may save flows to an in-memory table -internally in a router. - -.. warning:: You need to disable the in-memory table in production environments! - Using :abbr:`IMT (In-Memory Table)` may lead to heavy CPU overloading and - unstable flow-accounting behavior. - - -NetFlow / IPFIX -=============== -NetFlow is a feature that was introduced on Cisco routers around 1996 that -provides the ability to collect IP network traffic as it enters or exits an -interface. By analyzing the data provided by NetFlow, a network administrator -can determine things such as the source and destination of traffic, class of -service, and the causes of congestion. A typical flow monitoring setup (using -NetFlow) consists of three main components: - -* **exporter**: aggregates packets into flows and exports flow records towards - one or more flow collectors -* **collector**: responsible for reception, storage and pre-processing of flow - data received from a flow exporter -* **application**: analyzes received flow data in the context of intrusion - detection or traffic profiling, for example - -For connectionless protocols as like ICMP and UDP, a flow is considered -complete once no more packets for this flow appear after configurable timeout. - -NetFlow is usually enabled on a per-interface basis to limit load on the router -components involved in NetFlow, or to limit the amount of NetFlow records -exported. - -Configuration -============= - -.. warning:: Using NetFlow on routers with high traffic levels may lead to - high CPU usage and may affect the router's performance. In such cases, - consider using sFlow instead. - -In order for flow accounting information to be collected and displayed for an -interface, the interface must be configured for flow accounting. - -.. cfgcmd:: set system flow-accounting interface - - Configure and enable collection of flow information for the interface - identified by ``. - - You can configure multiple interfaces which whould participate in flow - accounting. - -.. note:: Will be recorded only packets/flows on **incoming** direction in - configured interfaces by default. - - -By default, recorded flows will be saved internally and can be listed with the -CLI command. You may disable using the local in-memory table with the command: - -.. cfgcmd:: set system flow-accounting disable-imt - - If you need to sample also egress traffic, you may want to - configure egress flow-accounting: - -.. cfgcmd:: set system flow-accounting enable-egress - - Internally, in flow-accounting processes exist a buffer for data exchanging - between core process and plugins (each export target is a separated plugin). - If you have high traffic levels or noted some problems with missed records - or stopping exporting, you may try to increase a default buffer size (10 - MiB) with the next command: - -.. cfgcmd:: set system flow-accounting buffer-size - - 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 - - TBD - -Flow Export ------------ - -In addition to displaying flow accounting information locally, one can also -exported them to a collection server. - -NetFlow -^^^^^^^ - -.. cfgcmd:: set system flow-accounting netflow version - - There are multiple versions available for the NetFlow data. The `` - used in the exported flow data can be configured here. The following - versions are supported: - - * **5** - Most common version, but restricted to IPv4 flows only - * **9** - NetFlow version 9 (default) - * **10** - :abbr:`IPFIX (IP Flow Information Export)` as per :rfc:`3917` - -.. cfgcmd:: set system flow-accounting netflow server
- - Configure address of NetFlow collector. NetFlow server at `
` can - be both listening on an IPv4 or IPv6 address. - -.. cfgcmd:: set system flow-accounting netflow source-ip
- - IPv4 or IPv6 source address of NetFlow packets - -.. cfgcmd:: set system flow-accounting netflow engine-id - - NetFlow engine-id which will appear in NetFlow data. The range is 0 to 255. - -.. cfgcmd:: set system flow-accounting netflow sampling-rate - - Use this command to configure the sampling rate for flow accounting. The - system samples one in every `` packets, where `` is the value - configured for the sampling-rate option. The advantage of sampling every n - packets, where n > 1, allows you to decrease the amount of processing - resources required for flow accounting. The disadvantage of not sampling - every packet is that the statistics produced are estimates of actual data - flows. - - Per default every packet is sampled (that is, the sampling rate is 1). - -.. cfgcmd:: set system flow-accounting netflow timeout expiry-interval - - - Specifies the interval at which Netflow data will be sent to a collector. As - per default, Netflow data will be sent every 60 seconds. - - You may also additionally configure timeouts for different types of - connections. - -.. cfgcmd:: set system flow-accounting netflow max-flows - - If you want to change the maximum number of flows, which are tracking - simultaneously, you may do this with this command (default 8192). - -sFlow -^^^^^ - -.. note:: Using `system sflow` is recommended in favor of - `system flow-accounting`. See `sflow `_ - -.. cfgcmd:: set system flow-accounting sflow server
- - Configure address of sFlow collector. sFlow server at `
` can - be an IPv4 or IPv6 address. But you cannot export to both IPv4 and - IPv6 collectors at the same time! - -.. cfgcmd:: set system flow-accounting sflow sampling-rate - - Enable sampling of packets, which will be transmitted to sFlow collectors. - -.. cfgcmd:: set system flow-accounting sflow agent-address
- - Configure a sFlow agent address. It can be IPv4 or IPv6 address, but you - must set the same protocol, which is used for sFlow collector addresses. By - default, using router-id from BGP or OSPF protocol, or the primary IP - address from the first interface. - -Example: --------- - -NetFlow v5 example: - -.. code-block:: none - - set system flow-accounting netflow engine-id 100 - set system flow-accounting netflow version 5 - set system flow-accounting netflow server 192.168.2.10 port 2055 - -Operation -========= - -Once flow accounting is configured on an interfaces it provides the ability to -display captured network traffic information for all configured interfaces. - -.. opcmd:: show flow-accounting interface - - Show flow accounting information for given ``. - - .. code-block:: none - - vyos@vyos:~$ show flow-accounting interface eth0 - IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES - ---------- ----------------- ----------------- ------------------------ --------------- ---------- ---------- ---------- ----- --------- ------- ------- - eth0 00:53:01:a8:28:ac ff:ff:ff:ff:ff:ff 192.0.2.2 255.255.255.255 5678 5678 udp 0 1 1 178 - eth0 00:53:01:b2:2f:34 33:33:ff:00:00:00 fe80::253:01ff:feb2:2f34 ff02::1:ff00:0 0 0 ipv6-icmp 0 2 1 144 - eth0 00:53:01:1a:b4:53 33:33:ff:00:00:00 fe80::253:01ff:fe1a:b453 ff02::1:ff00:0 0 0 ipv6-icmp 0 1 1 72 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 39 1 2064 - eth0 00:53:01:c8:33:af ff:ff:ff:ff:ff:ff 192.0.2.3 255.255.255.255 5678 5678 udp 0 1 1 154 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 146 1 9444 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 27 1 4455 - -.. opcmd:: show flow-accounting interface host
- - Show flow accounting information for given `` for a specific host - only. - - .. code-block:: none - - vyos@vyos:~$ show flow-accounting interface eth0 host 192.0.2.14 - IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES - ---------- ----------------- ----------------- ----------- ---------- ---------- ---------- ---------- ----- --------- ------- ------- - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 197 2 12940 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 94 1 4924 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 36 1 5877 diff --git a/docs/configuration/system/frr.md b/docs/configuration/system/frr.md new file mode 100644 index 00000000..37e6e502 --- /dev/null +++ b/docs/configuration/system/frr.md @@ -0,0 +1,44 @@ +(system-frr)= + +# FRR + +VyOS uses \[FRRouting\]() as the control plane for dynamic +and static routing. The routing daemon behavior can be adjusted during runtime, +but require either a restart of the routing daemon, or a reboot of the system. + +```{eval-rst} +.. cfgcmd:: set system frr bmp + + Enable {abbr}`BMP (BGP Monitoring Protocol)` support +``` + +```{eval-rst} +.. cfgcmd:: set system frr descriptors + + This allows the operator to control the number of open file descriptors + each daemon is allowed to start with. If the operator plans to run bgp with + several thousands of peers then this is where we would modify FRR to allow + this to happen. +``` + +```{eval-rst} +.. cfgcmd:: set system frr irdp + + Enable ICMP Router Discovery Protocol support +``` + +```{eval-rst} +.. cfgcmd:: set system frr snmp + + Enable SNMP support for an individual routing daemon. + + Supported daemons: + + - bgpd + - isisd + - ldpd + - ospf6d + - ospfd + - ripd + - zebra +``` diff --git a/docs/configuration/system/frr.rst b/docs/configuration/system/frr.rst deleted file mode 100644 index a7f7ff93..00000000 --- a/docs/configuration/system/frr.rst +++ /dev/null @@ -1,38 +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 require either a restart of the routing daemon, or a reboot of the system. - -.. cfgcmd:: set system frr bmp - - Enable :abbr:`BMP (BGP Monitoring Protocol)` support - -.. cfgcmd:: set system frr descriptors - - This allows the operator to control the number of open file descriptors - each daemon is allowed to start with. If the operator plans to run bgp with - several thousands of peers then this is where we would modify FRR to allow - this to happen. - -.. cfgcmd:: set system frr irdp - - Enable ICMP Router Discovery Protocol support - -.. cfgcmd:: set system frr snmp - - Enable SNMP support for an individual routing daemon. - - Supported daemons: - - - bgpd - - isisd - - ldpd - - ospf6d - - ospfd - - ripd - - zebra diff --git a/docs/configuration/system/host-name.md b/docs/configuration/system/host-name.md new file mode 100644 index 00000000..81840d1f --- /dev/null +++ b/docs/configuration/system/host-name.md @@ -0,0 +1,70 @@ +(host-information)= + +# Host Information + +This section describes the system's host information and how to configure them, +it covers the following topics: + +- Host name +- Domain +- IP address +- Aliases + +## Hostname + +A hostname is the label (name) assigned to a network device (a host) on a +network and is used to distinguish one device from another on specific networks +or over the internet. On the other hand this will be the name which appears on +the command line prompt. + +```{cfgcmd} set system host-name \ + + The hostname can be up to 63 characters. A hostname + must start and end with a letter or digit, and have as interior characters + only letters, digits, or a hyphen. + + The default hostname used is `vyos`. +``` + +## Domain Name + + +A domain name is the label (name) assigned to a computer network and is thus +unique. VyOS appends the domain name as a suffix to any unqualified name. For +example, if you set the domain name `example.com`, and you would ping the +unqualified name of `crux`, then VyOS qualifies the name to `crux.example.com`. + +```{cfgcmd} set system domain-name \ + +Configure system domain name. A domain name must start and end with a letter +or digit, and have as interior characters only letters, digits, or a hyphen. +``` + +## Static Hostname Mapping + + +How an IP address is assigned to an interface in {ref}`ethernet-interface`. +This section shows how to statically map an IP address to a hostname for local +(meaning on this VyOS instance) name resolution. This is the VyOS equivalent to +`/etc/hosts` file entries. + + +:::{note} +Do *not* manually edit `/etc/hosts`. This file will automatically be +regenerated on boot based on the settings in this section, which means you'll +lose all your manual edits. Instead, configure static host mappings as follows. +::: + +```{cfgcmd} set system static-host-mapping host-name \ inet \ + +Create a static hostname mapping which will always resolve the name +`` to IP address `
`. +``` +```{cfgcmd} set system static-host-mapping host-name \ alias \ + +Create named `` for the configured static mapping for ``. +Thus the address configured as {cfgcmd}`set system static-host-mapping +host-name inet
` can be reached via multiple names. + +Multiple aliases can be specified per host-name. +``` \ No newline at end of file diff --git a/docs/configuration/system/host-name.rst b/docs/configuration/system/host-name.rst deleted file mode 100644 index 4d1567bf..00000000 --- a/docs/configuration/system/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 - - The hostname can be up to 63 characters. A hostname - must start and end with a letter or digit, and have as interior characters - only letters, digits, or a hyphen. - - The default hostname used is `vyos`. - -Domain Name -=========== - -A domain name is the label (name) assigned to a computer network and is thus -unique. VyOS appends the domain name as a suffix to any unqualified name. For -example, if you set the domain name `example.com`, and you would ping the -unqualified name of `crux`, then VyOS qualifies the name to `crux.example.com`. - -.. cfgcmd:: set system domain-name - - Configure system domain name. A domain name must start and end with a letter - or digit, and have as interior characters only letters, digits, or a hyphen. - -Static Hostname Mapping -======================= - -How an IP address is assigned to an interface in :ref:`ethernet-interface`. -This section shows how to statically map an IP address to a hostname for local -(meaning on this VyOS instance) name resolution. This is the VyOS equivalent to -`/etc/hosts` file entries. - -.. note:: Do *not* manually edit `/etc/hosts`. This file will automatically be - regenerated on boot based on the settings in this section, which means you'll - lose all your manual edits. Instead, configure static host mappings as follows. - -.. cfgcmd:: set system static-host-mapping host-name inet
- - Create a static hostname mapping which will always resolve the name - `` to IP address `
`. - - -.. cfgcmd:: set system static-host-mapping host-name alias - - Create named `` for the configured static mapping for ``. - Thus the address configured as :cfgcmd:`set system static-host-mapping - host-name inet
` can be reached via multiple names. - - Multiple aliases can be specified per host-name. diff --git a/docs/configuration/system/index.md b/docs/configuration/system/index.md new file mode 100644 index 00000000..624a8434 --- /dev/null +++ b/docs/configuration/system/index.md @@ -0,0 +1,36 @@ +# System + +```{eval-rst} +.. 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 + +``` + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :includehidden: + + default-route +``` diff --git a/docs/configuration/system/index.rst b/docs/configuration/system/index.rst deleted file mode 100644 index dbb63d09..00000000 --- a/docs/configuration/system/index.rst +++ /dev/null @@ -1,35 +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 - - -.. toctree:: - :maxdepth: 1 - :includehidden: - - default-route diff --git a/docs/configuration/system/ip.md b/docs/configuration/system/ip.md new file mode 100644 index 00000000..2445509d --- /dev/null +++ b/docs/configuration/system/ip.md @@ -0,0 +1,110 @@ +# IP + +## System configuration commands + +```{eval-rst} +.. cfgcmd:: set system ip disable-forwarding + + Use this command to disable IPv4 forwarding on all interfaces. +``` + +```{eval-rst} +.. 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. +``` + +```{eval-rst} +.. cfgcmd:: set system ip arp table-size + + Use this command to define the maximum number of entries to keep in + the ARP cache (1024, 2048, 4096, 8192, 16384, 32768). +``` + +```{eval-rst} +.. cfgcmd:: set system ip multipath layer4-hashing + + Use this command to use Layer 4 information for IPv4 ECMP hashing. +``` + +### Zebra/Kernel route filtering + +Zebra supports prefix-lists and Route Mapss 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. + +```{eval-rst} +.. cfgcmd:: set system ip protocol route-map + + Apply a route-map filter to routes for the specified protocol. The following + protocols can be used: any, babel, bgp, connected, eigrp, isis, kernel, + ospf, rip, static, table + + .. 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 wan't to e.g. allow BGP to peer across the default route. + +```{eval-rst} +.. cfgcmd:: set system ip nht no-resolve-via-default + + Do not allow IPv4 nexthop tracking to resolve via the default route. This + parameter is configured per-VRF, so the command is also available in the VRF + subnode. +``` + +## Operational commands + +### show commands + +See below the different parameters available for the IPv4 **show** command: + +```none +vyos@vyos:~$ show ip +Possible completions: + access-list Show all IP access-lists + as-path-access-list + Show all as-path-access-lists + bgp Show Border Gateway Protocol (BGP) information + community-list + Show IP community-lists + extcommunity-list + Show extended IP community-lists + forwarding Show IP forwarding status + groups Show IP multicast group membership + igmp Show IGMP (Internet Group Management Protocol) information + large-community-list + Show IP large-community-lists + multicast Show IP multicast + ospf Show IPv4 Open Shortest Path First (OSPF) routing information + pim Show PIM (Protocol Independent Multicast) information + ports Show IP ports in use by various system services + prefix-list Show all IP prefix-lists + protocol Show IP route-maps per protocol + rip Show Routing Information Protocol (RIP) information + route Show IP routes +``` + +### reset commands + +And the different IPv4 **reset** commands available: + +```none +vyos@vyos:~$ reset ip +Possible completions: + arp Reset Address Resolution Protocol (ARP) cache + bgp Clear Border Gateway Protocol (BGP) statistics or status + igmp IGMP clear commands + multicast IP multicast routing table + route Reset IP route +``` diff --git a/docs/configuration/system/ip.rst b/docs/configuration/system/ip.rst deleted file mode 100644 index 279630e2..00000000 --- a/docs/configuration/system/ip.rst +++ /dev/null @@ -1,107 +0,0 @@ -## -IP -## - -System configuration commands ------------------------------ - -.. cfgcmd:: set system ip disable-forwarding - - Use this command to disable IPv4 forwarding on all interfaces. - -.. cfgcmd:: set system ip disable-directed-broadcast - - Use this command to disable IPv4 directed broadcast forwarding on all - interfaces. - - If set, IPv4 directed broadcast forwarding will be completely disabled - regardless of whether per-interface directed broadcast forwarding is - enabled or not. - -.. cfgcmd:: set system ip arp table-size - - Use this command to define the maximum number of entries to keep in - the ARP cache (1024, 2048, 4096, 8192, 16384, 32768). - -.. cfgcmd:: set system ip multipath layer4-hashing - - Use this command to use Layer 4 information for IPv4 ECMP hashing. - -Zebra/Kernel route filtering -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Zebra supports prefix-lists and Route Mapss to match routes received from -other FRR components. The permit/deny facilities provided by these commands -can be used to filter which routes zebra will install in the kernel. - -.. cfgcmd:: set system ip protocol route-map - - Apply a route-map filter to routes for the specified protocol. The following - protocols can be used: any, babel, bgp, connected, eigrp, isis, kernel, - ospf, rip, static, table - - .. 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 wan't 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/ipv6.md b/docs/configuration/system/ipv6.md new file mode 100644 index 00000000..80f0e33a --- /dev/null +++ b/docs/configuration/system/ipv6.md @@ -0,0 +1,235 @@ +# IPv6 + +## System configuration commands + +```{eval-rst} +.. cfgcmd:: set system ipv6 disable-forwarding + + Use this command to disable IPv6 forwarding on all interfaces. +``` + +```{eval-rst} +.. cfgcmd:: set system ipv6 neighbor table-size + + Use this command to define the maximum number of entries to keep in + the Neighbor cache (1024, 2048, 4096, 8192, 16384, 32768). +``` + +```{eval-rst} +.. cfgcmd:: set system ipv6 strict-dad + + Use this command to disable IPv6 operation on interface when + Duplicate Address Detection fails on Link-Local address. +``` + +```{eval-rst} +.. 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 Mapss 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. + +```{eval-rst} +.. cfgcmd:: set system ipv6 protocol route-map + + Apply a route-map filter to routes for the specified protocol. The following + protocols can be used: any, babel, bgp, connected, isis, kernel, ospfv3, + ripng, static, table + + .. 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 wan't to e.g. allow BGP to peer across the default route. + +```{eval-rst} +.. 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 + +```{eval-rst} +.. opcmd:: show ipv6 neighbors + + Use this command to show IPv6 Neighbor Discovery Protocol information. +``` + +```{eval-rst} +.. opcmd:: show ipv6 groups + + Use this command to show IPv6 multicast group membership. +``` + +```{eval-rst} +.. opcmd:: show ipv6 forwarding + + Use this command to show IPv6 forwarding status. +``` + +```{eval-rst} +.. opcmd:: show ipv6 route + + Use this command to show IPv6 routes. + + Check the many parameters available for the `show ipv6 route` command: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 route + Possible completions: + Execute the current command + Show IPv6 routes of given address or prefix + + bgp Show IPv6 BGP routes + cache Show kernel IPv6 route cache + connected Show IPv6 connected routes + forward Show kernel IPv6 route table + isis Show IPv6 ISIS routes + kernel Show IPv6 kernel routes + ospfv3 Show IPv6 OSPF6 routes + ripng Show IPv6 RIPNG routes + static Show IPv6 static routes + summary Show IPv6 routes summary + table Show IP routes in policy table + vrf Show IPv6 routes in VRF + +``` + +```{eval-rst} +.. opcmd:: show ipv6 prefix-list + + Use this command to show all IPv6 prefix lists + + There are different parameters for getting prefix-list information: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 prefix-list + Possible completions: + Execute the current command + Show specified IPv6 prefix-list + detail Show detail of IPv6 prefix-lists + summary Show summary of IPv6 prefix-lists +``` + +```{eval-rst} +.. opcmd:: show ipv6 access-list + + Use this command to show all IPv6 access lists + + You can also specify which IPv6 access-list should be shown: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 access-list + Possible completions: + Execute the current command + Show specified IPv6 access-list +``` + +```{eval-rst} +.. opcmd:: show ipv6 bgp + + Use this command to show IPv6 Border Gateway Protocol information. + + + In addition, you can specify many other parameters to get BGP + information: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 bgp + Possible completions: + Execute the current command + Show BGP information for given address or prefix + + community Show routes matching the communities + community-list + Show routes matching the community-list + filter-list Show routes conforming to the filter-list + large-community + Show routes matching the large-community-list + large-community-list + neighbors Show detailed information on TCP and BGP neighbor connections + prefix-list Show routes matching the prefix-list + regexp Show routes matching the AS path regular expression + route-map Show BGP routes matching the specified route map + summary Show summary of BGP neighbor status + +``` + +```{eval-rst} +.. opcmd:: show ipv6 ospfv3 + + Use this command to get information about OSPFv3. + + You can get more specific OSPFv3 information by using the parameters + shown below: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 ospfv3 + Possible completions: + Execute the current command + area Show OSPFv3 spf-tree information + border-routers + Show OSPFv3 border-router (ABR and ASBR) information + database Show OSPFv3 Link state database information + interface Show OSPFv3 interface information + linkstate Show OSPFv3 linkstate routing information + neighbor Show OSPFv3 neighbor information + redistribute Show OSPFv3 redistribute External information + route Show OSPFv3 routing table information +``` + +```{eval-rst} +.. opcmd:: show ipv6 ripng + + Use this command to get information about the RIPNG protocol +``` + +```{eval-rst} +.. opcmd:: show ipv6 ripng status + + Use this command to show the status of the RIPNG protocol + +``` + +### Reset commands + +```{eval-rst} +.. opcmd:: reset bgp ipv6
+ + Use this command to clear Border Gateway Protocol statistics or + status. + +``` + +```{eval-rst} +.. opcmd:: reset ipv6 neighbors
+ + Use this command to reset IPv6 Neighbor Discovery Protocol cache for + an address or interface. +``` + +```{eval-rst} +.. 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/ipv6.rst b/docs/configuration/system/ipv6.rst deleted file mode 100644 index ee0fa341..00000000 --- a/docs/configuration/system/ipv6.rst +++ /dev/null @@ -1,205 +0,0 @@ -#### -IPv6 -#### - -System configuration commands ------------------------------ - -.. cfgcmd:: set system ipv6 disable-forwarding - - Use this command to disable IPv6 forwarding on all interfaces. - -.. cfgcmd:: set system ipv6 neighbor table-size - - Use this command to define the maximum number of entries to keep in - the Neighbor cache (1024, 2048, 4096, 8192, 16384, 32768). - -.. cfgcmd:: set system ipv6 strict-dad - - Use this command to disable IPv6 operation on interface when - Duplicate Address Detection fails on Link-Local address. - -.. cfgcmd:: set system ipv6 multipath layer4-hashing - - Use this command to user Layer 4 information for ECMP hashing. - -Zebra/Kernel route filtering -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Zebra supports prefix-lists and Route Mapss to match routes received from -other FRR components. The permit/deny facilities provided by these commands -can be used to filter which routes zebra will install in the kernel. - -.. cfgcmd:: set system ipv6 protocol route-map - - Apply a route-map filter to routes for the specified protocol. The following - protocols can be used: any, babel, bgp, connected, isis, kernel, ospfv3, - ripng, static, table - - .. 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 wan't to e.g. allow BGP to peer across the default route. - -.. cfgcmd:: set system ipv6 nht no-resolve-via-default - - Do not allow IPv6 nexthop tracking to resolve via the default route. This - parameter is configured per-VRF, so the command is also available in the VRF - subnode. - -Operational commands --------------------- - -Show commands -^^^^^^^^^^^^^ - -.. opcmd:: show ipv6 neighbors - - Use this command to show IPv6 Neighbor Discovery Protocol information. - -.. opcmd:: show ipv6 groups - - Use this command to show IPv6 multicast group membership. - -.. opcmd:: show ipv6 forwarding - - Use this command to show IPv6 forwarding status. - -.. opcmd:: show ipv6 route - - Use this command to show IPv6 routes. - - Check the many parameters available for the `show ipv6 route` command: - - .. code-block:: none - - vyos@vyos:~$ show ipv6 route - Possible completions: - Execute the current command - Show IPv6 routes of given address or prefix - - bgp Show IPv6 BGP routes - cache Show kernel IPv6 route cache - connected Show IPv6 connected routes - forward Show kernel IPv6 route table - isis Show IPv6 ISIS routes - kernel Show IPv6 kernel routes - ospfv3 Show IPv6 OSPF6 routes - ripng Show IPv6 RIPNG routes - static Show IPv6 static routes - summary Show IPv6 routes summary - table Show IP routes in policy table - vrf Show IPv6 routes in VRF - - -.. opcmd:: show ipv6 prefix-list - - Use this command to show all IPv6 prefix lists - - There are different parameters for getting prefix-list information: - - .. code-block:: none - - vyos@vyos:~$ show ipv6 prefix-list - Possible completions: - Execute the current command - Show specified IPv6 prefix-list - detail Show detail of IPv6 prefix-lists - summary Show summary of IPv6 prefix-lists - -.. opcmd:: show ipv6 access-list - - Use this command to show all IPv6 access lists - - You can also specify which IPv6 access-list should be shown: - - .. code-block:: none - - vyos@vyos:~$ show ipv6 access-list - Possible completions: - Execute the current command - Show specified IPv6 access-list - -.. opcmd:: show ipv6 bgp - - Use this command to show IPv6 Border Gateway Protocol information. - - - In addition, you can specify many other parameters to get BGP - information: - - .. code-block:: none - - vyos@vyos:~$ show ipv6 bgp - Possible completions: - Execute the current command - Show BGP information for given address or prefix - - community Show routes matching the communities - community-list - Show routes matching the community-list - filter-list Show routes conforming to the filter-list - large-community - Show routes matching the large-community-list - large-community-list - neighbors Show detailed information on TCP and BGP neighbor connections - prefix-list Show routes matching the prefix-list - regexp Show routes matching the AS path regular expression - route-map Show BGP routes matching the specified route map - summary Show summary of BGP neighbor status - - -.. opcmd:: show ipv6 ospfv3 - - Use this command to get information about OSPFv3. - - You can get more specific OSPFv3 information by using the parameters - shown below: - - .. code-block:: none - - vyos@vyos:~$ show ipv6 ospfv3 - Possible completions: - Execute the current command - area Show OSPFv3 spf-tree information - border-routers - Show OSPFv3 border-router (ABR and ASBR) information - database Show OSPFv3 Link state database information - interface Show OSPFv3 interface information - linkstate Show OSPFv3 linkstate routing information - neighbor Show OSPFv3 neighbor information - redistribute Show OSPFv3 redistribute External information - route Show OSPFv3 routing table information - -.. opcmd:: show ipv6 ripng - - Use this command to get information about the RIPNG protocol - -.. opcmd:: show ipv6 ripng status - - Use this command to show the status of the RIPNG protocol - - -Reset commands -^^^^^^^^^^^^^^ - -.. opcmd:: reset bgp ipv6
- - Use this command to clear Border Gateway Protocol statistics or - status. - - -.. opcmd:: reset ipv6 neighbors
- - Use this command to reset IPv6 Neighbor Discovery Protocol cache for - an address or interface. - -.. opcmd:: reset ipv6 route cache - - Use this command to flush the kernel IPv6 route cache. - An address can be added to flush it only for that route. diff --git a/docs/configuration/system/lcd.md b/docs/configuration/system/lcd.md new file mode 100644 index 00000000..c857ae34 --- /dev/null +++ b/docs/configuration/system/lcd.md @@ -0,0 +1,46 @@ +(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 + +```{eval-rst} +.. cfgcmd:: set system lcd device + + This is the name of the physical interface used to connect to your LCD + display. Tab completion is supported and it will list you all available + serial interface. + + For serial via USB port information please refor to: {ref}`hardware_usb`. +``` + +```{eval-rst} +.. cfgcmd:: set system lcd model + + This is the LCD model used in your system. + + At the time of this writing the following displays are supported: + + * Crystalfontz CFA-533 + + * Crystalfontz CFA-631 + + * Crystalfontz CFA-633 + + * Crystalfontz CFA-635 + + .. note:: We can't support all displays from the beginning. If your display + type is missing, please create a feature request via Phabricator_. +``` + +```{include} /_include/common-references.txt +``` diff --git a/docs/configuration/system/lcd.rst b/docs/configuration/system/lcd.rst deleted file mode 100644 index 808d45a2..00000000 --- a/docs/configuration/system/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 - - 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 - - This is the LCD model used in your system. - - At the time of this writing the following displays are supported: - - * Crystalfontz CFA-533 - - * Crystalfontz CFA-631 - - * Crystalfontz CFA-633 - - * Crystalfontz CFA-635 - - .. note:: We can't support all displays from the beginning. If your display - type is missing, please create a feature request via Phabricator_. - -.. include:: /_include/common-references.txt - diff --git a/docs/configuration/system/login.md b/docs/configuration/system/login.md new file mode 100644 index 00000000..562ed419 --- /dev/null +++ b/docs/configuration/system/login.md @@ -0,0 +1,474 @@ +--- +lastproofread: '2022-10-15' +--- + +(user-management)= + +# Login/User Management + +The default VyOS user account (`vyos`), as well as newly created user accounts, +have all capabilities to configure the system. All accounts have sudo +capabilities and therefore can operate as root on the system. + +Both local administered and remote administered {abbr}`RADIUS (Remote +Authentication Dial-In User Service)` accounts are supported. + +## Local + +```{eval-rst} +.. cfgcmd:: set system login user full-name "" + + Create new system user with username `` and real-name specified by + ``. +``` + +```{eval-rst} +.. cfgcmd:: set system login user authentication plaintext-password + + + Specify the plaintext password user by user `` on this system. The + plaintext password will be automatically transferred into a secure hashed + password and not saved anywhere in plaintext. +``` + +```{eval-rst} +.. cfgcmd:: set system login user authentication encrypted-password + + + Setup encrypted password for given username. This is useful for + transferring a hashed password from system to system. +``` + +```{eval-rst} +.. cfgcmd:: set system login user disable + + Disable (lock) account. User will not be able to log in. +``` + +(ssh_key_based_authentication)= + +### Key Based Authentication + +It is highly recommended to use SSH key authentication. By default there is +only one user (`vyos`), and you can assign any number of keys to that user. +You can generate a ssh key with the `ssh-keygen` command on your local +machine, which will (by default) save it as `~/.ssh/id_rsa.pub`. + +Every SSH key comes in three parts: + +`ssh-rsa AAAAB3NzaC1yc2EAAAABAA...VBD5lKwEWB username@host.example.com` + +Only the type (`ssh-rsa`) and the key (`AAAB3N...`) are used. Note that the +key will usually be several hundred characters long, and you will need to copy +and paste it. Some terminal emulators may accidentally split this over several +lines. Be attentive when you paste it that it only pastes as a single line. +The third part is simply an identifier, and is for your own reference. + +```{eval-rst} +.. seealso:: SSH {ref}`ssh_operation` +``` + +```{eval-rst} +.. cfgcmd:: set system login user authentication public-keys + key + + Assign the SSH public key portion `` identified by per-key + `` to the local user ``. +``` + +```{eval-rst} +.. cfgcmd:: set system login user authentication public-keys + type + + Every SSH public key portion referenced by `` requires the + configuration of the `` of public-key used. This type can be any of: + + * ``ecdsa-sha2-nistp256`` + * ``ecdsa-sha2-nistp384`` + * ``ecdsa-sha2-nistp521`` + * ``ssh-dss`` + * ``ssh-ed25519`` + * ``ssh-rsa`` + + .. note:: You can assign multiple keys to the same user by using a unique + identifier per SSH key. +``` + +```{eval-rst} +.. cfgcmd:: set system login user authentication public-keys + options + + Set the options for this public key. See the ssh ``authorized_keys`` man + page for details of what you can specify here. To place a ``"`` + character in the options field, use ``"``, for example + ``from="10.0.0.0/24"`` to restrict where the user + may connect from when using this key. +``` + +### MFA/2FA authentication using OTP (one time passwords) + +It is possible to enhance authentication security by using the {abbr}`2FA +(Two-factor authentication)`/{abbr}`MFA (Multi-factor authentication)` feature +together with {abbr}`OTP (One-Time-Pad)` on VyOS. {abbr}`2FA (Two-factor +authentication)`/{abbr}`MFA (Multi-factor authentication)` is configured +independently per each user. If an OTP key is configured for a user, 2FA/MFA +is automatically enabled for that particular user. If a user does not have an +OTP key configured, there is no 2FA/MFA check for that user. + +```{eval-rst} +.. cfgcmd:: set system login user authentication otp key + + Enable OTP 2FA for user `username` with default settings, using the BASE32 + encoded 2FA/MFA key specified by ``. +``` + +#### Optional/default settings + +```{eval-rst} +.. cfgcmd:: set system login user authentication otp rate-limit + :defaultvalue: + + Limit logins to `` per every ``rate-time`` seconds. Rate limit + must be between 1 and 10 attempts. +``` + +```{eval-rst} +.. cfgcmd:: set system login user authentication otp rate-time + :defaultvalue: + + Limit logins to ``rate-limit`` attemps per every ``. Rate time must + be between 15 and 600 seconds. +``` + +```{eval-rst} +.. cfgcmd:: set system login user authentication otp window-size + :defaultvalue: + + Set window of concurrently valid codes. + + By default, a new token is generated every 30 seconds by the mobile + application. In order to compensate for possible time-skew between + the client and the server, an extra token before and after the current + time is allowed. This allows for a time skew of up to 30 seconds + between authentication server and client. + + For example, if problems with poor time synchronization are experienced, + the window can be increased from its default size of 3 permitted codes + (one previous code, the current code, the next code) to 17 permitted codes + (the 8 previous codes, the current code, and the 8 next codes). This will + permit for a time skew of up to 4 minutes between client and server. + + The window size must be between 1 and 21. +``` + +#### OTP-key generation + +The following command can be used to generate the OTP key as well +as the CLI commands to configure them: + +```{eval-rst} +.. cfgcmd:: generate system login username otp-key hotp-time + rate-limit <1-10> rate-time <15-600> window-size <1-21> +``` + +An example of key generation: + +```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 OTP key for user + +To display the configured OTP user key, use the command: + +```{eval-rst} +.. cfgcmd:: sh system login authentication user otp + +``` + +An example: + +```none +vyos@vyos:~$ sh system login authentication user otptester otp full +# 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' +``` + +Once a user has 2FA/OTP configured against their account, they must login +using their password with the OTP code appended to it. +For example: If the users password is vyosrocks and the OTP code is 817454 +then they would enter their password as vyosrocks817454 + +## RADIUS + +In large deployments it is not reasonable to configure each user individually +on every system. VyOS supports using {abbr}`RADIUS (Remote Authentication +Dial-In User Service)` servers as backend for user authentication. + +### Configuration + +```{eval-rst} +.. cfgcmd:: set system login radius server
key + + Specify the IP `
` of the RADIUS server user with the pre-shared-secret + given in ``. + + Multiple servers can be specified. +``` + +```{eval-rst} +.. cfgcmd:: set system login radius server
port + + Configure the discrete port under which the RADIUS server can be reached. + + This defaults to 1812. +``` + +```{eval-rst} +.. cfgcmd:: set system login radius server
disable + + Temporary disable this RADIUS server. It won't be queried. +``` + +```{eval-rst} +.. cfgcmd:: set system login radius server
timeout + + Setup the `` in seconds when querying the RADIUS server. +``` + +```{eval-rst} +.. cfgcmd:: set system login radius source-address
+ + RADIUS servers could be hardened by only allowing certain IP addresses to + connect. As of this the source address of each RADIUS query can be + configured. + + If unset, incoming connections to the RADIUS server will use the nearest + interface address pointing towards the server - making it error prone on + e.g. OSPF networks when a link fails and a backup route is taken. +``` + +```{eval-rst} +.. cfgcmd:: set system login radius vrf + + Source all connections to the RADIUS servers from given VRF ``. +``` + +:::{hint} +If you want to have admin users to authenticate via RADIUS it is +essential to sent the `Cisco-AV-Pair shell:priv-lvl=15` attribute. Without +the attribute you will only get regular, non privilegued, system users. +::: + +## TACACS+ + +In addition to {abbr}`RADIUS (Remote Authentication Dial-In User Service)`, +{abbr}`TACACS (Terminal Access Controller Access Control System)` can also be +found in large deployments. +VyOS only supports `Authentication` via `TACACS+` servers but does not support `Authorization` or `Accounting` yet + +TACACS is defined in {rfc}`8907`. + +(tacacs-configuration)= + +### Configuration + +```{eval-rst} +.. cfgcmd:: set system login tacas server
key + + Specify the IP `
` of the TACACS server user with the pre-shared-secret + given in ``. + + Multiple servers can be specified. +``` + +```{eval-rst} +.. cfgcmd:: set system login tacas server
port + + Configure the discrete port under which the TACACS server can be reached. + + This defaults to 49. +``` + +```{eval-rst} +.. cfgcmd:: set system login tacas server
disable + + Temporary disable this TACACS server. It won't be queried. +``` + +```{eval-rst} +.. cfgcmd:: set system login tacas server
timeout + + Setup the `` in seconds when querying the TACACS server. +``` + +```{eval-rst} +.. cfgcmd:: set system login tacas source-address
+ + TACACS servers could be hardened by only allowing certain IP addresses to + connect. As of this the source address of each TACACS query can be + configured. + + If unset, incoming connections to the TACACS server will use the nearest + interface address pointing towards the server - making it error prone on + e.g. OSPF networks when a link fails and a backup route is taken. +``` + +```{eval-rst} +.. cfgcmd:: set system login tacas vrf + + Source all connections to the TACACS servers from given VRF ``. + +``` + +## Login Banner + +You are able to set post-login or pre-login banner messages to display certain +information for this system. + +```{eval-rst} +.. cfgcmd:: set system login banner pre-login + + Configure `` which is shown during SSH connect and before a user is + logged in. +``` + +```{eval-rst} +.. cfgcmd:: set system login banner post-login + + Configure `` which is shown after user has logged in to the system. +``` + +:::{note} +To create a new line in your login message you need to escape the new +line character by using `\\n`. +::: + +## Limits + +Login limits + +```{eval-rst} +.. cfgcmd:: set system login max-login-session + + Set a limit on the maximum number of concurrent logged-in users on + the system. + + This option must be used with ``timeout`` option. +``` + +```{eval-rst} +.. cfgcmd:: set system login timeout + + Configure session timeout after which the user will be logged out. +``` + +## Example + +In the following example, both `User1` and `User2` will be able to SSH into +VyOS as user `vyos` using their very own keys. `User1` is restricted to only +be able to connect from a single IP address. In addition if password base login +is wanted for the `vyos` user a 2FA/MFA keycode is required in addition to +the password. + +```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 +``` + +### TACACS Example + +We use a vontainer providing the TACACS serve rin this example. + +Load the container image in op-mode. + +```none +add container image lfkeitel/tacacs_plus:latest +``` + +```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 SSH into your system using admin/admin as a default user supplied +from the `lfkeitel/tacacs_plus:latest` container. diff --git a/docs/configuration/system/login.rst b/docs/configuration/system/login.rst deleted file mode 100644 index 6009a39b..00000000 --- a/docs/configuration/system/login.rst +++ /dev/null @@ -1,425 +0,0 @@ -:lastproofread: 2022-10-15 - -.. _user_management: - -##################### -Login/User Management -##################### - -The default VyOS user account (`vyos`), as well as newly created user accounts, -have all capabilities to configure the system. All accounts have sudo -capabilities and therefore can operate as root on the system. - -Both local administered and remote administered :abbr:`RADIUS (Remote -Authentication Dial-In User Service)` accounts are supported. - -Local -===== - -.. cfgcmd:: set system login user full-name "" - - Create new system user with username `` and real-name specified by - ``. - -.. cfgcmd:: set system login user authentication plaintext-password - - - Specify the plaintext password user by user `` on this system. The - plaintext password will be automatically transferred into a secure hashed - password and not saved anywhere in plaintext. - -.. cfgcmd:: set system login user authentication encrypted-password - - - Setup encrypted password for given username. This is useful for - transferring a hashed password from system to system. - -.. cfgcmd:: set system login user disable - - Disable (lock) account. User will not be able to log in. - -.. _ssh_key_based_authentication: - -Key Based Authentication ------------------------- - -It is highly recommended to use SSH key authentication. By default there is -only one user (``vyos``), and you can assign any number of keys to that user. -You can generate a ssh key with the ``ssh-keygen`` command on your local -machine, which will (by default) save it as ``~/.ssh/id_rsa.pub``. - -Every SSH key comes in three parts: - -``ssh-rsa AAAAB3NzaC1yc2EAAAABAA...VBD5lKwEWB username@host.example.com`` - -Only the type (``ssh-rsa``) and the key (``AAAB3N...``) are used. Note that the -key will usually be several hundred characters long, and you will need to copy -and paste it. Some terminal emulators may accidentally split this over several -lines. Be attentive when you paste it that it only pastes as a single line. -The third part is simply an identifier, and is for your own reference. - -.. seealso:: SSH :ref:`ssh_operation` - -.. cfgcmd:: set system login user authentication public-keys - key - - Assign the SSH public key portion `` identified by per-key - `` to the local user ``. - -.. cfgcmd:: set system login user authentication public-keys - type - - Every SSH public key portion referenced by `` requires the - configuration of the `` of public-key used. This type can be any of: - - * ``ecdsa-sha2-nistp256`` - * ``ecdsa-sha2-nistp384`` - * ``ecdsa-sha2-nistp521`` - * ``ssh-dss`` - * ``ssh-ed25519`` - * ``ssh-rsa`` - - .. note:: You can assign multiple keys to the same user by using a unique - identifier per SSH key. - -.. cfgcmd:: set system login user authentication public-keys - options - - Set the options for this public key. See the ssh ``authorized_keys`` man - page for details of what you can specify here. To place a ``"`` - character in the options field, use ``"``, for example - ``from="10.0.0.0/24"`` to restrict where the user - may connect from when using this key. - -MFA/2FA authentication using OTP (one time passwords) ------------------------------------------------------ - -It is possible to enhance authentication security by using the :abbr:`2FA -(Two-factor authentication)`/:abbr:`MFA (Multi-factor authentication)` feature -together with :abbr:`OTP (One-Time-Pad)` on VyOS. :abbr:`2FA (Two-factor -authentication)`/:abbr:`MFA (Multi-factor authentication)` is configured -independently per each user. If an OTP key is configured for a user, 2FA/MFA -is automatically enabled for that particular user. If a user does not have an -OTP key configured, there is no 2FA/MFA check for that user. - -.. cfgcmd:: set system login user authentication otp key - - Enable OTP 2FA for user `username` with default settings, using the BASE32 - encoded 2FA/MFA key specified by ``. - -Optional/default settings -^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. cfgcmd:: set system login user authentication otp rate-limit - :defaultvalue: - - Limit logins to `` per every ``rate-time`` seconds. Rate limit - must be between 1 and 10 attempts. - -.. cfgcmd:: set system login user authentication otp rate-time - :defaultvalue: - - Limit logins to ``rate-limit`` attemps per every ``. Rate time must - be between 15 and 600 seconds. - -.. cfgcmd:: set system login user authentication otp window-size - :defaultvalue: - - Set window of concurrently valid codes. - - By default, a new token is generated every 30 seconds by the mobile - application. In order to compensate for possible time-skew between - the client and the server, an extra token before and after the current - time is allowed. This allows for a time skew of up to 30 seconds - between authentication server and client. - - For example, if problems with poor time synchronization are experienced, - the window can be increased from its default size of 3 permitted codes - (one previous code, the current code, the next code) to 17 permitted codes - (the 8 previous codes, the current code, and the 8 next codes). This will - permit for a time skew of up to 4 minutes between client and server. - - The window size must be between 1 and 21. - -OTP-key generation -^^^^^^^^^^^^^^^^^^ - -The following command can be used to generate the OTP key as well -as the CLI commands to configure them: - -.. cfgcmd:: generate system login username otp-key hotp-time - rate-limit <1-10> rate-time <15-600> window-size <1-21> - -An example of key generation: - -.. 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 OTP key for user -^^^^^^^^^^^^^^^^^^^^^^^^ - -To display the configured OTP user key, use the command: - -.. cfgcmd:: sh system login authentication user otp - - -An example: - -.. code-block:: none - - vyos@vyos:~$ sh system login authentication user otptester otp full - # 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' - -Once a user has 2FA/OTP configured against their account, they must login -using their password with the OTP code appended to it. -For example: If the users password is vyosrocks and the OTP code is 817454 -then they would enter their password as vyosrocks817454 - - -RADIUS -====== - -In large deployments it is not reasonable to configure each user individually -on every system. VyOS supports using :abbr:`RADIUS (Remote Authentication -Dial-In User Service)` servers as backend for user authentication. - -Configuration -------------- - -.. cfgcmd:: set system login radius server
key - - Specify the IP `
` of the RADIUS server user with the pre-shared-secret - given in ``. - - Multiple servers can be specified. - -.. cfgcmd:: set system login radius server
port - - Configure the discrete port under which the RADIUS server can be reached. - - This defaults to 1812. - -.. cfgcmd:: set system login radius server
disable - - Temporary disable this RADIUS server. It won't be queried. - -.. cfgcmd:: set system login radius server
timeout - - Setup the `` in seconds when querying the RADIUS server. - -.. cfgcmd:: set system login radius source-address
- - RADIUS servers could be hardened by only allowing certain IP addresses to - connect. As of this the source address of each RADIUS query can be - configured. - - If unset, incoming connections to the RADIUS server will use the nearest - interface address pointing towards the server - making it error prone on - e.g. OSPF networks when a link fails and a backup route is taken. - -.. cfgcmd:: set system login radius vrf - - Source all connections to the RADIUS servers from given VRF ``. - -.. hint:: If you want to have admin users to authenticate via RADIUS it is - essential to sent the ``Cisco-AV-Pair shell:priv-lvl=15`` attribute. Without - the attribute you will only get regular, non privilegued, system users. - -TACACS+ -======= - -In addition to :abbr:`RADIUS (Remote Authentication Dial-In User Service)`, -:abbr:`TACACS (Terminal Access Controller Access Control System)` can also be -found in large deployments. -VyOS only supports `Authentication` via `TACACS+` servers but does not support `Authorization` or `Accounting` yet - -TACACS is defined in :rfc:`8907`. - -.. _TACACS Configuration: - -Configuration -------------- - -.. cfgcmd:: set system login tacas server
key - - Specify the IP `
` of the TACACS server user with the pre-shared-secret - given in ``. - - Multiple servers can be specified. - -.. cfgcmd:: set system login tacas server
port - - Configure the discrete port under which the TACACS server can be reached. - - This defaults to 49. - -.. cfgcmd:: set system login tacas server
disable - - Temporary disable this TACACS server. It won't be queried. - -.. cfgcmd:: set system login tacas server
timeout - - Setup the `` in seconds when querying the TACACS server. - -.. cfgcmd:: set system login tacas source-address
- - TACACS servers could be hardened by only allowing certain IP addresses to - connect. As of this the source address of each TACACS query can be - configured. - - If unset, incoming connections to the TACACS server will use the nearest - interface address pointing towards the server - making it error prone on - e.g. OSPF networks when a link fails and a backup route is taken. - -.. cfgcmd:: set system login tacas vrf - - Source all connections to the TACACS servers from given VRF ``. - - -Login Banner -============ - -You are able to set post-login or pre-login banner messages to display certain -information for this system. - -.. cfgcmd:: set system login banner pre-login - - Configure `` which is shown during SSH connect and before a user is - logged in. - -.. cfgcmd:: set system login banner post-login - - Configure `` which is shown after user has logged in to the system. - -.. note:: To create a new line in your login message you need to escape the new - line character by using ``\\n``. - -Limits -====== - -Login limits - -.. cfgcmd:: set system login max-login-session - - Set a limit on the maximum number of concurrent logged-in users on - the system. - - This option must be used with ``timeout`` option. - -.. cfgcmd:: set system login timeout - - Configure session timeout after which the user will be logged out. - -Example -======= - -In the following example, both `User1` and `User2` will be able to SSH into -VyOS as user ``vyos`` using their very own keys. `User1` is restricted to only -be able to connect from a single IP address. In addition if password base login -is wanted for the ``vyos`` user a 2FA/MFA keycode is required in addition to -the password. - -.. 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 - -TACACS Example --------------- - -We use a vontainer providing the TACACS serve rin this example. - -Load the container image in op-mode. - -.. code-block:: none - - add container image lfkeitel/tacacs_plus:latest - -.. 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 SSH into your system using admin/admin as a default user supplied -from the ``lfkeitel/tacacs_plus:latest`` container. diff --git a/docs/configuration/system/md-acceleration.md b/docs/configuration/system/md-acceleration.md deleted file mode 100644 index 871129e6..00000000 --- a/docs/configuration/system/md-acceleration.md +++ /dev/null @@ -1,158 +0,0 @@ -(acceleration)= - -# Acceleration - -In this command tree, all hardware acceleration options will be handled. -At the moment only [Intel® QAT] is supported - -## Intel® QAT - -```{opcmd} show system acceleration qat - -use this command to check if there is an Intel® QAT supported Processor in your system. - -:::{code-block} none -vyos@vyos:~$ show system acceleration qat -01:00.0 Co-processor [0b40]: Intel Corporation Atom Processor C3000 Series QuickAssist Technology [8086:19e2] (rev 11) -::: - -if there is non device the command will show `` `No QAT device found` `` -``` - -```{cfgcmd} set system acceleration qat - -if there is a supported device, enable Intel® QAT -``` - - -```{opcmd} show system acceleration qat status - -Check if the Intel® QAT device is up and ready to do the job. - -:::{code-block} none -vyos@vyos:~$ show system acceleration qat status -Checking status of all devices. -There is 1 QAT acceleration device(s) in the system: -qat_dev0 - type: c3xxx, inst_id: 0, node_id: 0, bsf: 0000:01:00.0, #accel: 3 #engines: 6 state: up -::: -``` - - -### Operation Mode - -```{opcmd} show system acceleration qat device \ config - -Show the full config uploaded to the QAT device. -``` - - -```{opcmd} show system acceleration qat device \ flows - -Get an overview over the encryption counters. -``` - - -```{opcmd} show system acceleration qat interrupts - -Show binded qat device interrupts to certain core. -``` - - -### Example - -Let's build a simple VPN between 2 Intel® QAT ready devices. - -Side A: - -``` -set interfaces vti vti1 address '192.168.1.2/24' -set vpn ipsec authentication psk right id '10.10.10.2' -set vpn ipsec authentication psk right id '10.10.10.1' -set vpn ipsec authentication psk right secret 'Qwerty123' -set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes256' -set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha256' -set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '14' -set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes256' -set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha256' -set vpn ipsec interface 'eth0' -set vpn ipsec site-to-site peer right authentication local-id '10.10.10.2' -set vpn ipsec site-to-site peer right authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer right authentication remote-id '10.10.10.1' -set vpn ipsec site-to-site peer right connection-type 'initiate' -set vpn ipsec site-to-site peer right default-esp-group 'MyESPGroup' -set vpn ipsec site-to-site peer right ike-group 'MyIKEGroup' -set vpn ipsec site-to-site peer right local-address '10.10.10.2' -set vpn ipsec site-to-site peer right remote-address '10.10.10.1' -set vpn ipsec site-to-site peer right vti bind 'vti1' -``` - -Side B: - -``` -set interfaces vti vti1 address '192.168.1.1/24' -set vpn ipsec authentication psk left id '10.10.10.2' -set vpn ipsec authentication psk left id '10.10.10.1' -set vpn ipsec authentication psk left secret 'Qwerty123' -set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes256' -set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha256' -set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '14' -set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes256' -set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha256' -set vpn ipsec interface 'eth0' -set vpn ipsec site-to-site peer left authentication local-id '10.10.10.1' -set vpn ipsec site-to-site peer left authentication mode 'pre-shared-secret' -set vpn ipsec site-to-site peer left authentication remote-id '10.10.10.2' -set vpn ipsec site-to-site peer left connection-type 'initiate' -set vpn ipsec site-to-site peer left default-esp-group 'MyESPGroup' -set vpn ipsec site-to-site peer left ike-group 'MyIKEGroup' -set vpn ipsec site-to-site peer left local-address '10.10.10.1' -set vpn ipsec site-to-site peer left remote-address '10.10.10.2' -set vpn ipsec site-to-site peer left vti bind 'vti1' -``` - -a bandwidth test over the VPN got these results: - -``` -Connecting to host 192.168.1.2, port 5201 -[ 9] local 192.168.1.1 port 51344 connected to 192.168.1.2 port 5201 -[ ID] Interval Transfer Bitrate Retr Cwnd -[ 9] 0.00-1.01 sec 32.3 MBytes 268 Mbits/sec 0 196 KBytes -[ 9] 1.01-2.03 sec 32.5 MBytes 268 Mbits/sec 0 208 KBytes -[ 9] 2.03-3.03 sec 32.5 MBytes 271 Mbits/sec 0 208 KBytes -[ 9] 3.03-4.04 sec 32.5 MBytes 272 Mbits/sec 0 208 KBytes -[ 9] 4.04-5.00 sec 31.2 MBytes 272 Mbits/sec 0 208 KBytes -[ 9] 5.00-6.01 sec 32.5 MBytes 272 Mbits/sec 0 234 KBytes -[ 9] 6.01-7.04 sec 32.5 MBytes 265 Mbits/sec 0 234 KBytes -[ 9] 7.04-8.04 sec 32.5 MBytes 272 Mbits/sec 0 234 KBytes -[ 9] 8.04-9.04 sec 32.5 MBytes 273 Mbits/sec 0 336 KBytes -[ 9] 9.04-10.00 sec 31.2 MBytes 272 Mbits/sec 0 336 KBytes -- - - - - - - - - - - - - - - - - - - - - - - - - -[ ID] Interval Transfer Bitrate Retr -[ 9] 0.00-10.00 sec 322 MBytes 270 Mbits/sec 0 sender -[ 9] 0.00-10.00 sec 322 MBytes 270 Mbits/sec receiver -``` - -with {cfgcmd}`set system acceleration qat` on both systems the bandwidth -increases. - -``` -Connecting to host 192.168.1.2, port 5201 -[ 9] local 192.168.1.1 port 51340 connected to 192.168.1.2 port 5201 -[ ID] Interval Transfer Bitrate Retr Cwnd -[ 9] 0.00-1.00 sec 97.3 MBytes 817 Mbits/sec 0 1000 KBytes -[ 9] 1.00-2.00 sec 92.5 MBytes 776 Mbits/sec 0 1.07 MBytes -[ 9] 2.00-3.00 sec 92.5 MBytes 776 Mbits/sec 0 820 KBytes -[ 9] 3.00-4.00 sec 92.5 MBytes 776 Mbits/sec 0 899 KBytes -[ 9] 4.00-5.00 sec 91.2 MBytes 765 Mbits/sec 0 972 KBytes -[ 9] 5.00-6.00 sec 92.5 MBytes 776 Mbits/sec 0 1.02 MBytes -[ 9] 6.00-7.00 sec 92.5 MBytes 776 Mbits/sec 0 1.08 MBytes -[ 9] 7.00-8.00 sec 92.5 MBytes 776 Mbits/sec 0 1.14 MBytes -[ 9] 8.00-9.00 sec 91.2 MBytes 765 Mbits/sec 0 915 KBytes -[ 9] 9.00-10.00 sec 92.5 MBytes 776 Mbits/sec 0 1000 KBytes -- - - - - - - - - - - - - - - - - - - - - - - - - -[ ID] Interval Transfer Bitrate Retr -[ 9] 0.00-10.00 sec 927 MBytes 778 Mbits/sec 0 sender -[ 9] 0.00-10.01 sec 925 MBytes 775 Mbits/sec receiver -``` - -[intel® qat]: https://www.intel.com/content/www/us/en/architecture-and-technology/intel-quick-assist-technology-overview.html diff --git a/docs/configuration/system/md-conntrack.md b/docs/configuration/system/md-conntrack.md deleted file mode 100644 index b5f926b7..00000000 --- a/docs/configuration/system/md-conntrack.md +++ /dev/null @@ -1,365 +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 - -```{eval-rst} -.. cfgcmd:: set system conntrack table-size <1-50000000> - :defaultvalue: - - The connection tracking table contains one entry for each connection being - tracked by the system. -``` - -```{eval-rst} -.. 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. -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack hash-size <1-50000000> - :defaultvalue: - - Set the size of the hash table. The connection tracking hash table makes - searching the connection tracking table faster. The hash table uses - “buckets” to record entries in the connection tracking table. -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack modules ftp -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack modules h323 -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack modules nfs -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack modules pptp -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack modules sip -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack modules sqlnet -``` - -```{eval-rst} -.. 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`. - -``` - -### Define Conection Timeouts - -VyOS supports setting timeouts for connections according to the -connection type. You can set timeout values for generic connections, for ICMP -connections, UDP connections, or for TCP connections in a number of different -states. - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout icmp <1-21474836> - :defaultvalue: -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout other <1-21474836> - :defaultvalue: -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout tcp close <1-21474836> - :defaultvalue: -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout tcp close-wait <1-21474836> - :defaultvalue: -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout tcp established <1-21474836> - :defaultvalue: -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout tcp fin-wait <1-21474836> - :defaultvalue: -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout tcp last-ack <1-21474836> - :defaultvalue: -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout tcp syn-recv <1-21474836> - :defaultvalue: -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout tcp syn-sent <1-21474836> - :defaultvalue: -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout tcp time-wait <1-21474836> - :defaultvalue: -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout udp other <1-21474836> - :defaultvalue: -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout udp stream <1-21474836> - :defaultvalue: - - Set the timeout in secounds for a protocol or state. - -``` - -You can also define custom timeout values to apply to a specific subset of -connections, based on a packet and flow selector. To do this, you need to -create a rule defining the packet and flow selector. - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> description - - Set a rule description. - -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> destination address -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> source address - - set a destination and/or source address. Accepted input: - - .. code-block:: none - - IP address to match - Subnet to match - - - IP range to match - ! Match everything except the specified address - ! Match everything except the specified subnet - !- - Match everything except the specified range -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> destination port -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> source port - - Set a destination and/or source port. Accepted input: - - .. code-block:: none - - Named port (any name in /etc/services, e.g., http) - <1-65535> Numbered port - - Numbered port range (e.g., 1001-1005) - - Multiple destination ports can be specified as a comma-separated list. - The whole list can also be "negated" using '!'. For example: - `!22,telnet,http,123,1001-1005`` - - -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol icmp <1-21474836> -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol other <1-21474836> -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp close <1-21474836> -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp close-wait <1-21474836> -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp established <1-21474836> -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp fin-wait <1-21474836> -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp last-ack <1-21474836> -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp syn-recv <1-21474836> -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp syn-sent <1-21474836> -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp time-wait <1-21474836> -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol udp other <1-21474836> -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol udp stream <1-21474836> - - Set the timeout in secounds for a protocol or state in a custom rule. - -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack tcp half-open-connections <1-21474836> - :defaultvalue: - - Set the maximum number of TCP half-open connections. -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack tcp loose - :defaultvalue: - - Policy to track previously established connections. -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack tcp max-retrans <1-2147483647> - :defaultvalue: - - Set the number of TCP maximum retransmit attempts. -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack ignore rule <1-9999> description -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack ignore rule <1-9999> destination address -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack ignore rule <1-9999> destination port -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack ignore rule <1-9999> inbound-interface -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack ignore rule <1-9999> protocol -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack ignore rule <1-9999> source address -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack ignore rule <1-9999> source port - - Customized ignore rules, based on a packet and flow selector. -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack log icmp destroy -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack log icmp new -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack log icmp update -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack log other destroy -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack log other new -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack log other update -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack log tcp destroy -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack log tcp new -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack log tcp update close-wait -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack log tcp update established -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack log tcp update fin-wait -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack log tcp update last-ack -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack log tcp update syn-received -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack log tcp update time-wait -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack log udp destroy -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack log udp new -``` - -```{eval-rst} -.. cfgcmd:: set system conntrack log udp update - - Log the connection tracking events per protocol. -``` diff --git a/docs/configuration/system/md-console.md b/docs/configuration/system/md-console.md deleted file mode 100644 index adcaef8c..00000000 --- a/docs/configuration/system/md-console.md +++ /dev/null @@ -1,47 +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. - -```{eval-rst} -.. cfgcmd:: set system console device - - Defines the specified device as a system console. Available console devices - can be (see completion helper): - - * ``ttySN`` - Serial device name - * ``ttyUSBX`` - USB Serial device name - * ``hvc0`` - Xen console -``` - -```{eval-rst} -.. cfgcmd:: set system console device speed - - The speed (baudrate) of the console device. Supported values are: - - * ``1200`` - 1200 bps - * ``2400`` - 2400 bps - * ``4800`` - 4800 bps - * ``9600`` - 9600 bps - * ``19200`` - 19,200 bps - * ``38400`` - 38,400 bps (default for Xen console) - * ``57600`` - 57,600 bps - * ``115200`` - 115,200 bps (default for serial console) - - .. note:: If you use USB to serial converters for connecting to your VyOS - appliance please note that most of them use software emulation without flow - control. This means you should start with a common baud rate (most likely - 9600 baud) as otherwise you probably can not connect to the device using - high speed baud rates as your serial converter simply can not process this - data rate. -``` diff --git a/docs/configuration/system/md-default-route.md b/docs/configuration/system/md-default-route.md deleted file mode 100644 index 9f2793d1..00000000 --- a/docs/configuration/system/md-default-route.md +++ /dev/null @@ -1,40 +0,0 @@ -(default-gateway)= - -# Default Gateway/Route - -In the past (VyOS 1.1) used a gateway-address configured under the system tree -({cfgcmd}`set system gateway-address
`), this is no longer supported -and existing configurations are migrated to the new CLI command. - -## Configuration - -```{cfgcmd} set protocols static route 0.0.0.0/0 next-hop \ - -Specify static route into the routing table sending all non local traffic -to the nexthop address \. -``` - -```{cfgcmd} delete protocols static route 0.0.0.0/0 - -Delete default route from the system. -``` - - -## Operation - -```{opcmd} show ip route 0.0.0.0 - -Show routing table entry for the default route. - -:::{code-block} none -vyos@vyos:~$ show ip route 0.0.0.0 -Routing entry for 0.0.0.0/0 -Known via "static", distance 10, metric 0, best -Last update 09:46:30 ago -* 172.18.201.254, via eth0.201 -::: -``` - -:::{seealso} -Configuration of {ref}`routing-static` -::: diff --git a/docs/configuration/system/md-flow-accounting.md b/docs/configuration/system/md-flow-accounting.md deleted file mode 100644 index 9b328fff..00000000 --- a/docs/configuration/system/md-flow-accounting.md +++ /dev/null @@ -1,248 +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 two different protocols: NetFlow (versions 5, 9 and -10/IPFIX) and sFlow. Additionally, you may save flows to an in-memory table -internally in a router. - -:::{warning} -You need to disable the in-memory table in production environments! -Using {abbr}`IMT (In-Memory Table)` may lead to heavy CPU overloading and -unstable flow-accounting behavior. -::: - -## NetFlow / IPFIX - -NetFlow is a feature that was introduced on Cisco routers around 1996 that -provides the ability to collect IP network traffic as it enters or exits an -interface. By analyzing the data provided by NetFlow, a network administrator -can determine things such as the source and destination of traffic, class of -service, and the causes of congestion. A typical flow monitoring setup (using -NetFlow) consists of three main components: - -- **exporter**: aggregates packets into flows and exports flow records towards - one or more flow collectors -- **collector**: responsible for reception, storage and pre-processing of flow - data received from a flow exporter -- **application**: analyzes received flow data in the context of intrusion - detection or traffic profiling, for example - -For connectionless protocols as like ICMP and UDP, a flow is considered -complete once no more packets for this flow appear after configurable timeout. - -NetFlow is usually enabled on a per-interface basis to limit load on the router -components involved in NetFlow, or to limit the amount of NetFlow records -exported. - -## Configuration - -:::{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. - -```{eval-rst} -.. cfgcmd:: set system flow-accounting interface - - Configure and enable collection of flow information for the interface - identified by ``. - - You can configure multiple interfaces which whould participate in flow - accounting. -``` - -:::{note} -Will be recorded only packets/flows on **incoming** direction in -configured interfaces by default. -::: - -By default, recorded flows will be saved internally and can be listed with the -CLI command. You may disable using the local in-memory table with the command: - -```{eval-rst} -.. cfgcmd:: set system flow-accounting disable-imt - - If you need to sample also egress traffic, you may want to - configure egress flow-accounting: -``` - -```{eval-rst} -.. 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: -``` - -```{eval-rst} -.. cfgcmd:: set system flow-accounting buffer-size - - In case, if you need to catch some logs from flow-accounting daemon, you may - configure logging facility: -``` - -```{eval-rst} -.. cfgcmd:: set system flow-accounting syslog-facility - - TBD -``` - -### Flow Export - -In addition to displaying flow accounting information locally, one can also -exported them to a collection server. - -#### NetFlow - -```{eval-rst} -.. cfgcmd:: set system flow-accounting netflow version - - There are multiple versions available for the NetFlow data. The `` - used in the exported flow data can be configured here. The following - versions are supported: - - * **5** - Most common version, but restricted to IPv4 flows only - * **9** - NetFlow version 9 (default) - * **10** - {abbr}`IPFIX (IP Flow Information Export)` as per {rfc}`3917` -``` - -```{eval-rst} -.. cfgcmd:: set system flow-accounting netflow server
- - Configure address of NetFlow collector. NetFlow server at `
` can - be both listening on an IPv4 or IPv6 address. -``` - -```{eval-rst} -.. cfgcmd:: set system flow-accounting netflow source-ip
- - IPv4 or IPv6 source address of NetFlow packets -``` - -```{eval-rst} -.. cfgcmd:: set system flow-accounting netflow engine-id - - NetFlow engine-id which will appear in NetFlow data. The range is 0 to 255. -``` - -```{eval-rst} -.. cfgcmd:: set system flow-accounting netflow sampling-rate - - Use this command to configure the sampling rate for flow accounting. The - system samples one in every `` packets, where `` is the value - configured for the sampling-rate option. The advantage of sampling every n - packets, where n > 1, allows you to decrease the amount of processing - resources required for flow accounting. The disadvantage of not sampling - every packet is that the statistics produced are estimates of actual data - flows. - - Per default every packet is sampled (that is, the sampling rate is 1). -``` - -```{eval-rst} -.. cfgcmd:: set system flow-accounting netflow timeout expiry-interval - - - Specifies the interval at which Netflow data will be sent to a collector. As - per default, Netflow data will be sent every 60 seconds. - - You may also additionally configure timeouts for different types of - connections. -``` - -```{eval-rst} -.. cfgcmd:: set system flow-accounting netflow max-flows - - If you want to change the maximum number of flows, which are tracking - simultaneously, you may do this with this command (default 8192). -``` - -#### sFlow - -:::{note} -Using `system sflow` is recommended in favor of -`system flow-accounting`. See [sflow](sflow.html) -::: - -```{eval-rst} -.. cfgcmd:: set system flow-accounting sflow server
- - Configure address of sFlow collector. sFlow server at `
` can - be an IPv4 or IPv6 address. But you cannot export to both IPv4 and - IPv6 collectors at the same time! -``` - -```{eval-rst} -.. cfgcmd:: set system flow-accounting sflow sampling-rate - - Enable sampling of packets, which will be transmitted to sFlow collectors. -``` - -```{eval-rst} -.. cfgcmd:: set system flow-accounting sflow agent-address
- - Configure a sFlow agent address. It can be IPv4 or IPv6 address, but you - must set the same protocol, which is used for sFlow collector addresses. By - default, using router-id from BGP or OSPF protocol, or the primary IP - address from the first interface. -``` - -### Example: - -NetFlow v5 example: - -```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. - -```{eval-rst} -.. opcmd:: show flow-accounting interface - - Show flow accounting information for given ``. - - .. code-block:: none - - vyos@vyos:~$ show flow-accounting interface eth0 - IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES - ---------- ----------------- ----------------- ------------------------ --------------- ---------- ---------- ---------- ----- --------- ------- ------- - eth0 00:53:01:a8:28:ac ff:ff:ff:ff:ff:ff 192.0.2.2 255.255.255.255 5678 5678 udp 0 1 1 178 - eth0 00:53:01:b2:2f:34 33:33:ff:00:00:00 fe80::253:01ff:feb2:2f34 ff02::1:ff00:0 0 0 ipv6-icmp 0 2 1 144 - eth0 00:53:01:1a:b4:53 33:33:ff:00:00:00 fe80::253:01ff:fe1a:b453 ff02::1:ff00:0 0 0 ipv6-icmp 0 1 1 72 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 39 1 2064 - eth0 00:53:01:c8:33:af ff:ff:ff:ff:ff:ff 192.0.2.3 255.255.255.255 5678 5678 udp 0 1 1 154 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 146 1 9444 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 27 1 4455 -``` - -```{eval-rst} -.. opcmd:: show flow-accounting interface host
- - Show flow accounting information for given `` for a specific host - only. - - .. code-block:: none - - vyos@vyos:~$ show flow-accounting interface eth0 host 192.0.2.14 - IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES - ---------- ----------------- ----------------- ----------- ---------- ---------- ---------- ---------- ----- --------- ------- ------- - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 197 2 12940 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 94 1 4924 - eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 36 1 5877 -``` diff --git a/docs/configuration/system/md-frr.md b/docs/configuration/system/md-frr.md deleted file mode 100644 index 37e6e502..00000000 --- a/docs/configuration/system/md-frr.md +++ /dev/null @@ -1,44 +0,0 @@ -(system-frr)= - -# FRR - -VyOS uses \[FRRouting\]() as the control plane for dynamic -and static routing. The routing daemon behavior can be adjusted during runtime, -but require either a restart of the routing daemon, or a reboot of the system. - -```{eval-rst} -.. cfgcmd:: set system frr bmp - - Enable {abbr}`BMP (BGP Monitoring Protocol)` support -``` - -```{eval-rst} -.. cfgcmd:: set system frr descriptors - - This allows the operator to control the number of open file descriptors - each daemon is allowed to start with. If the operator plans to run bgp with - several thousands of peers then this is where we would modify FRR to allow - this to happen. -``` - -```{eval-rst} -.. cfgcmd:: set system frr irdp - - Enable ICMP Router Discovery Protocol support -``` - -```{eval-rst} -.. cfgcmd:: set system frr snmp - - Enable SNMP support for an individual routing daemon. - - Supported daemons: - - - bgpd - - isisd - - ldpd - - ospf6d - - ospfd - - ripd - - zebra -``` diff --git a/docs/configuration/system/md-host-name.md b/docs/configuration/system/md-host-name.md deleted file mode 100644 index 81840d1f..00000000 --- a/docs/configuration/system/md-host-name.md +++ /dev/null @@ -1,70 +0,0 @@ -(host-information)= - -# Host Information - -This section describes the system's host information and how to configure them, -it covers the following topics: - -- Host name -- Domain -- IP address -- Aliases - -## Hostname - -A hostname is the label (name) assigned to a network device (a host) on a -network and is used to distinguish one device from another on specific networks -or over the internet. On the other hand this will be the name which appears on -the command line prompt. - -```{cfgcmd} set system host-name \ - - The hostname can be up to 63 characters. A hostname - must start and end with a letter or digit, and have as interior characters - only letters, digits, or a hyphen. - - The default hostname used is `vyos`. -``` - -## Domain Name - - -A domain name is the label (name) assigned to a computer network and is thus -unique. VyOS appends the domain name as a suffix to any unqualified name. For -example, if you set the domain name `example.com`, and you would ping the -unqualified name of `crux`, then VyOS qualifies the name to `crux.example.com`. - -```{cfgcmd} set system domain-name \ - -Configure system domain name. A domain name must start and end with a letter -or digit, and have as interior characters only letters, digits, or a hyphen. -``` - -## Static Hostname Mapping - - -How an IP address is assigned to an interface in {ref}`ethernet-interface`. -This section shows how to statically map an IP address to a hostname for local -(meaning on this VyOS instance) name resolution. This is the VyOS equivalent to -`/etc/hosts` file entries. - - -:::{note} -Do *not* manually edit `/etc/hosts`. This file will automatically be -regenerated on boot based on the settings in this section, which means you'll -lose all your manual edits. Instead, configure static host mappings as follows. -::: - -```{cfgcmd} set system static-host-mapping host-name \ inet \ - -Create a static hostname mapping which will always resolve the name -`` to IP address `
`. -``` -```{cfgcmd} set system static-host-mapping host-name \ alias \ - -Create named `` for the configured static mapping for ``. -Thus the address configured as {cfgcmd}`set system static-host-mapping -host-name inet
` can be reached via multiple names. - -Multiple aliases can be specified per host-name. -``` \ No newline at end of file diff --git a/docs/configuration/system/md-index.md b/docs/configuration/system/md-index.md deleted file mode 100644 index 624a8434..00000000 --- a/docs/configuration/system/md-index.md +++ /dev/null @@ -1,36 +0,0 @@ -# System - -```{eval-rst} -.. 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 - -``` - -```{eval-rst} -.. toctree:: - :maxdepth: 1 - :includehidden: - - default-route -``` diff --git a/docs/configuration/system/md-ip.md b/docs/configuration/system/md-ip.md deleted file mode 100644 index 2445509d..00000000 --- a/docs/configuration/system/md-ip.md +++ /dev/null @@ -1,110 +0,0 @@ -# IP - -## System configuration commands - -```{eval-rst} -.. cfgcmd:: set system ip disable-forwarding - - Use this command to disable IPv4 forwarding on all interfaces. -``` - -```{eval-rst} -.. 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. -``` - -```{eval-rst} -.. cfgcmd:: set system ip arp table-size - - Use this command to define the maximum number of entries to keep in - the ARP cache (1024, 2048, 4096, 8192, 16384, 32768). -``` - -```{eval-rst} -.. cfgcmd:: set system ip multipath layer4-hashing - - Use this command to use Layer 4 information for IPv4 ECMP hashing. -``` - -### Zebra/Kernel route filtering - -Zebra supports prefix-lists and Route Mapss 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. - -```{eval-rst} -.. cfgcmd:: set system ip protocol route-map - - Apply a route-map filter to routes for the specified protocol. The following - protocols can be used: any, babel, bgp, connected, eigrp, isis, kernel, - ospf, rip, static, table - - .. 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 wan't to e.g. allow BGP to peer across the default route. - -```{eval-rst} -.. cfgcmd:: set system ip nht no-resolve-via-default - - Do not allow IPv4 nexthop tracking to resolve via the default route. This - parameter is configured per-VRF, so the command is also available in the VRF - subnode. -``` - -## Operational commands - -### show commands - -See below the different parameters available for the IPv4 **show** command: - -```none -vyos@vyos:~$ show ip -Possible completions: - access-list Show all IP access-lists - as-path-access-list - Show all as-path-access-lists - bgp Show Border Gateway Protocol (BGP) information - community-list - Show IP community-lists - extcommunity-list - Show extended IP community-lists - forwarding Show IP forwarding status - groups Show IP multicast group membership - igmp Show IGMP (Internet Group Management Protocol) information - large-community-list - Show IP large-community-lists - multicast Show IP multicast - ospf Show IPv4 Open Shortest Path First (OSPF) routing information - pim Show PIM (Protocol Independent Multicast) information - ports Show IP ports in use by various system services - prefix-list Show all IP prefix-lists - protocol Show IP route-maps per protocol - rip Show Routing Information Protocol (RIP) information - route Show IP routes -``` - -### reset commands - -And the different IPv4 **reset** commands available: - -```none -vyos@vyos:~$ reset ip -Possible completions: - arp Reset Address Resolution Protocol (ARP) cache - bgp Clear Border Gateway Protocol (BGP) statistics or status - igmp IGMP clear commands - multicast IP multicast routing table - route Reset IP route -``` diff --git a/docs/configuration/system/md-ipv6.md b/docs/configuration/system/md-ipv6.md deleted file mode 100644 index 80f0e33a..00000000 --- a/docs/configuration/system/md-ipv6.md +++ /dev/null @@ -1,235 +0,0 @@ -# IPv6 - -## System configuration commands - -```{eval-rst} -.. cfgcmd:: set system ipv6 disable-forwarding - - Use this command to disable IPv6 forwarding on all interfaces. -``` - -```{eval-rst} -.. cfgcmd:: set system ipv6 neighbor table-size - - Use this command to define the maximum number of entries to keep in - the Neighbor cache (1024, 2048, 4096, 8192, 16384, 32768). -``` - -```{eval-rst} -.. cfgcmd:: set system ipv6 strict-dad - - Use this command to disable IPv6 operation on interface when - Duplicate Address Detection fails on Link-Local address. -``` - -```{eval-rst} -.. 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 Mapss 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. - -```{eval-rst} -.. cfgcmd:: set system ipv6 protocol route-map - - Apply a route-map filter to routes for the specified protocol. The following - protocols can be used: any, babel, bgp, connected, isis, kernel, ospfv3, - ripng, static, table - - .. 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 wan't to e.g. allow BGP to peer across the default route. - -```{eval-rst} -.. 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 - -```{eval-rst} -.. opcmd:: show ipv6 neighbors - - Use this command to show IPv6 Neighbor Discovery Protocol information. -``` - -```{eval-rst} -.. opcmd:: show ipv6 groups - - Use this command to show IPv6 multicast group membership. -``` - -```{eval-rst} -.. opcmd:: show ipv6 forwarding - - Use this command to show IPv6 forwarding status. -``` - -```{eval-rst} -.. opcmd:: show ipv6 route - - Use this command to show IPv6 routes. - - Check the many parameters available for the `show ipv6 route` command: - - .. code-block:: none - - vyos@vyos:~$ show ipv6 route - Possible completions: - Execute the current command - Show IPv6 routes of given address or prefix - - bgp Show IPv6 BGP routes - cache Show kernel IPv6 route cache - connected Show IPv6 connected routes - forward Show kernel IPv6 route table - isis Show IPv6 ISIS routes - kernel Show IPv6 kernel routes - ospfv3 Show IPv6 OSPF6 routes - ripng Show IPv6 RIPNG routes - static Show IPv6 static routes - summary Show IPv6 routes summary - table Show IP routes in policy table - vrf Show IPv6 routes in VRF - -``` - -```{eval-rst} -.. opcmd:: show ipv6 prefix-list - - Use this command to show all IPv6 prefix lists - - There are different parameters for getting prefix-list information: - - .. code-block:: none - - vyos@vyos:~$ show ipv6 prefix-list - Possible completions: - Execute the current command - Show specified IPv6 prefix-list - detail Show detail of IPv6 prefix-lists - summary Show summary of IPv6 prefix-lists -``` - -```{eval-rst} -.. opcmd:: show ipv6 access-list - - Use this command to show all IPv6 access lists - - You can also specify which IPv6 access-list should be shown: - - .. code-block:: none - - vyos@vyos:~$ show ipv6 access-list - Possible completions: - Execute the current command - Show specified IPv6 access-list -``` - -```{eval-rst} -.. opcmd:: show ipv6 bgp - - Use this command to show IPv6 Border Gateway Protocol information. - - - In addition, you can specify many other parameters to get BGP - information: - - .. code-block:: none - - vyos@vyos:~$ show ipv6 bgp - Possible completions: - Execute the current command - Show BGP information for given address or prefix - - community Show routes matching the communities - community-list - Show routes matching the community-list - filter-list Show routes conforming to the filter-list - large-community - Show routes matching the large-community-list - large-community-list - neighbors Show detailed information on TCP and BGP neighbor connections - prefix-list Show routes matching the prefix-list - regexp Show routes matching the AS path regular expression - route-map Show BGP routes matching the specified route map - summary Show summary of BGP neighbor status - -``` - -```{eval-rst} -.. opcmd:: show ipv6 ospfv3 - - Use this command to get information about OSPFv3. - - You can get more specific OSPFv3 information by using the parameters - shown below: - - .. code-block:: none - - vyos@vyos:~$ show ipv6 ospfv3 - Possible completions: - Execute the current command - area Show OSPFv3 spf-tree information - border-routers - Show OSPFv3 border-router (ABR and ASBR) information - database Show OSPFv3 Link state database information - interface Show OSPFv3 interface information - linkstate Show OSPFv3 linkstate routing information - neighbor Show OSPFv3 neighbor information - redistribute Show OSPFv3 redistribute External information - route Show OSPFv3 routing table information -``` - -```{eval-rst} -.. opcmd:: show ipv6 ripng - - Use this command to get information about the RIPNG protocol -``` - -```{eval-rst} -.. opcmd:: show ipv6 ripng status - - Use this command to show the status of the RIPNG protocol - -``` - -### Reset commands - -```{eval-rst} -.. opcmd:: reset bgp ipv6
- - Use this command to clear Border Gateway Protocol statistics or - status. - -``` - -```{eval-rst} -.. opcmd:: reset ipv6 neighbors
- - Use this command to reset IPv6 Neighbor Discovery Protocol cache for - an address or interface. -``` - -```{eval-rst} -.. 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/md-lcd.md b/docs/configuration/system/md-lcd.md deleted file mode 100644 index c857ae34..00000000 --- a/docs/configuration/system/md-lcd.md +++ /dev/null @@ -1,46 +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 - -```{eval-rst} -.. cfgcmd:: set system lcd device - - This is the name of the physical interface used to connect to your LCD - display. Tab completion is supported and it will list you all available - serial interface. - - For serial via USB port information please refor to: {ref}`hardware_usb`. -``` - -```{eval-rst} -.. cfgcmd:: set system lcd model - - This is the LCD model used in your system. - - At the time of this writing the following displays are supported: - - * Crystalfontz CFA-533 - - * Crystalfontz CFA-631 - - * Crystalfontz CFA-633 - - * Crystalfontz CFA-635 - - .. note:: We can't support all displays from the beginning. If your display - type is missing, please create a feature request via Phabricator_. -``` - -```{include} /_include/common-references.txt -``` diff --git a/docs/configuration/system/md-login.md b/docs/configuration/system/md-login.md deleted file mode 100644 index 562ed419..00000000 --- a/docs/configuration/system/md-login.md +++ /dev/null @@ -1,474 +0,0 @@ ---- -lastproofread: '2022-10-15' ---- - -(user-management)= - -# Login/User Management - -The default VyOS user account (`vyos`), as well as newly created user accounts, -have all capabilities to configure the system. All accounts have sudo -capabilities and therefore can operate as root on the system. - -Both local administered and remote administered {abbr}`RADIUS (Remote -Authentication Dial-In User Service)` accounts are supported. - -## Local - -```{eval-rst} -.. cfgcmd:: set system login user full-name "" - - Create new system user with username `` and real-name specified by - ``. -``` - -```{eval-rst} -.. cfgcmd:: set system login user authentication plaintext-password - - - Specify the plaintext password user by user `` on this system. The - plaintext password will be automatically transferred into a secure hashed - password and not saved anywhere in plaintext. -``` - -```{eval-rst} -.. cfgcmd:: set system login user authentication encrypted-password - - - Setup encrypted password for given username. This is useful for - transferring a hashed password from system to system. -``` - -```{eval-rst} -.. cfgcmd:: set system login user disable - - Disable (lock) account. User will not be able to log in. -``` - -(ssh_key_based_authentication)= - -### Key Based Authentication - -It is highly recommended to use SSH key authentication. By default there is -only one user (`vyos`), and you can assign any number of keys to that user. -You can generate a ssh key with the `ssh-keygen` command on your local -machine, which will (by default) save it as `~/.ssh/id_rsa.pub`. - -Every SSH key comes in three parts: - -`ssh-rsa AAAAB3NzaC1yc2EAAAABAA...VBD5lKwEWB username@host.example.com` - -Only the type (`ssh-rsa`) and the key (`AAAB3N...`) are used. Note that the -key will usually be several hundred characters long, and you will need to copy -and paste it. Some terminal emulators may accidentally split this over several -lines. Be attentive when you paste it that it only pastes as a single line. -The third part is simply an identifier, and is for your own reference. - -```{eval-rst} -.. seealso:: SSH {ref}`ssh_operation` -``` - -```{eval-rst} -.. cfgcmd:: set system login user authentication public-keys - key - - Assign the SSH public key portion `` identified by per-key - `` to the local user ``. -``` - -```{eval-rst} -.. cfgcmd:: set system login user authentication public-keys - type - - Every SSH public key portion referenced by `` requires the - configuration of the `` of public-key used. This type can be any of: - - * ``ecdsa-sha2-nistp256`` - * ``ecdsa-sha2-nistp384`` - * ``ecdsa-sha2-nistp521`` - * ``ssh-dss`` - * ``ssh-ed25519`` - * ``ssh-rsa`` - - .. note:: You can assign multiple keys to the same user by using a unique - identifier per SSH key. -``` - -```{eval-rst} -.. cfgcmd:: set system login user authentication public-keys - options - - Set the options for this public key. See the ssh ``authorized_keys`` man - page for details of what you can specify here. To place a ``"`` - character in the options field, use ``"``, for example - ``from="10.0.0.0/24"`` to restrict where the user - may connect from when using this key. -``` - -### MFA/2FA authentication using OTP (one time passwords) - -It is possible to enhance authentication security by using the {abbr}`2FA -(Two-factor authentication)`/{abbr}`MFA (Multi-factor authentication)` feature -together with {abbr}`OTP (One-Time-Pad)` on VyOS. {abbr}`2FA (Two-factor -authentication)`/{abbr}`MFA (Multi-factor authentication)` is configured -independently per each user. If an OTP key is configured for a user, 2FA/MFA -is automatically enabled for that particular user. If a user does not have an -OTP key configured, there is no 2FA/MFA check for that user. - -```{eval-rst} -.. cfgcmd:: set system login user authentication otp key - - Enable OTP 2FA for user `username` with default settings, using the BASE32 - encoded 2FA/MFA key specified by ``. -``` - -#### Optional/default settings - -```{eval-rst} -.. cfgcmd:: set system login user authentication otp rate-limit - :defaultvalue: - - Limit logins to `` per every ``rate-time`` seconds. Rate limit - must be between 1 and 10 attempts. -``` - -```{eval-rst} -.. cfgcmd:: set system login user authentication otp rate-time - :defaultvalue: - - Limit logins to ``rate-limit`` attemps per every ``. Rate time must - be between 15 and 600 seconds. -``` - -```{eval-rst} -.. cfgcmd:: set system login user authentication otp window-size - :defaultvalue: - - Set window of concurrently valid codes. - - By default, a new token is generated every 30 seconds by the mobile - application. In order to compensate for possible time-skew between - the client and the server, an extra token before and after the current - time is allowed. This allows for a time skew of up to 30 seconds - between authentication server and client. - - For example, if problems with poor time synchronization are experienced, - the window can be increased from its default size of 3 permitted codes - (one previous code, the current code, the next code) to 17 permitted codes - (the 8 previous codes, the current code, and the 8 next codes). This will - permit for a time skew of up to 4 minutes between client and server. - - The window size must be between 1 and 21. -``` - -#### OTP-key generation - -The following command can be used to generate the OTP key as well -as the CLI commands to configure them: - -```{eval-rst} -.. cfgcmd:: generate system login username otp-key hotp-time - rate-limit <1-10> rate-time <15-600> window-size <1-21> -``` - -An example of key generation: - -```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 OTP key for user - -To display the configured OTP user key, use the command: - -```{eval-rst} -.. cfgcmd:: sh system login authentication user otp - -``` - -An example: - -```none -vyos@vyos:~$ sh system login authentication user otptester otp full -# 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' -``` - -Once a user has 2FA/OTP configured against their account, they must login -using their password with the OTP code appended to it. -For example: If the users password is vyosrocks and the OTP code is 817454 -then they would enter their password as vyosrocks817454 - -## RADIUS - -In large deployments it is not reasonable to configure each user individually -on every system. VyOS supports using {abbr}`RADIUS (Remote Authentication -Dial-In User Service)` servers as backend for user authentication. - -### Configuration - -```{eval-rst} -.. cfgcmd:: set system login radius server
key - - Specify the IP `
` of the RADIUS server user with the pre-shared-secret - given in ``. - - Multiple servers can be specified. -``` - -```{eval-rst} -.. cfgcmd:: set system login radius server
port - - Configure the discrete port under which the RADIUS server can be reached. - - This defaults to 1812. -``` - -```{eval-rst} -.. cfgcmd:: set system login radius server
disable - - Temporary disable this RADIUS server. It won't be queried. -``` - -```{eval-rst} -.. cfgcmd:: set system login radius server
timeout - - Setup the `` in seconds when querying the RADIUS server. -``` - -```{eval-rst} -.. cfgcmd:: set system login radius source-address
- - RADIUS servers could be hardened by only allowing certain IP addresses to - connect. As of this the source address of each RADIUS query can be - configured. - - If unset, incoming connections to the RADIUS server will use the nearest - interface address pointing towards the server - making it error prone on - e.g. OSPF networks when a link fails and a backup route is taken. -``` - -```{eval-rst} -.. cfgcmd:: set system login radius vrf - - Source all connections to the RADIUS servers from given VRF ``. -``` - -:::{hint} -If you want to have admin users to authenticate via RADIUS it is -essential to sent the `Cisco-AV-Pair shell:priv-lvl=15` attribute. Without -the attribute you will only get regular, non privilegued, system users. -::: - -## TACACS+ - -In addition to {abbr}`RADIUS (Remote Authentication Dial-In User Service)`, -{abbr}`TACACS (Terminal Access Controller Access Control System)` can also be -found in large deployments. -VyOS only supports `Authentication` via `TACACS+` servers but does not support `Authorization` or `Accounting` yet - -TACACS is defined in {rfc}`8907`. - -(tacacs-configuration)= - -### Configuration - -```{eval-rst} -.. cfgcmd:: set system login tacas server
key - - Specify the IP `
` of the TACACS server user with the pre-shared-secret - given in ``. - - Multiple servers can be specified. -``` - -```{eval-rst} -.. cfgcmd:: set system login tacas server
port - - Configure the discrete port under which the TACACS server can be reached. - - This defaults to 49. -``` - -```{eval-rst} -.. cfgcmd:: set system login tacas server
disable - - Temporary disable this TACACS server. It won't be queried. -``` - -```{eval-rst} -.. cfgcmd:: set system login tacas server
timeout - - Setup the `` in seconds when querying the TACACS server. -``` - -```{eval-rst} -.. cfgcmd:: set system login tacas source-address
- - TACACS servers could be hardened by only allowing certain IP addresses to - connect. As of this the source address of each TACACS query can be - configured. - - If unset, incoming connections to the TACACS server will use the nearest - interface address pointing towards the server - making it error prone on - e.g. OSPF networks when a link fails and a backup route is taken. -``` - -```{eval-rst} -.. cfgcmd:: set system login tacas vrf - - Source all connections to the TACACS servers from given VRF ``. - -``` - -## Login Banner - -You are able to set post-login or pre-login banner messages to display certain -information for this system. - -```{eval-rst} -.. cfgcmd:: set system login banner pre-login - - Configure `` which is shown during SSH connect and before a user is - logged in. -``` - -```{eval-rst} -.. cfgcmd:: set system login banner post-login - - Configure `` which is shown after user has logged in to the system. -``` - -:::{note} -To create a new line in your login message you need to escape the new -line character by using `\\n`. -::: - -## Limits - -Login limits - -```{eval-rst} -.. cfgcmd:: set system login max-login-session - - Set a limit on the maximum number of concurrent logged-in users on - the system. - - This option must be used with ``timeout`` option. -``` - -```{eval-rst} -.. cfgcmd:: set system login timeout - - Configure session timeout after which the user will be logged out. -``` - -## Example - -In the following example, both `User1` and `User2` will be able to SSH into -VyOS as user `vyos` using their very own keys. `User1` is restricted to only -be able to connect from a single IP address. In addition if password base login -is wanted for the `vyos` user a 2FA/MFA keycode is required in addition to -the password. - -```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 -``` - -### TACACS Example - -We use a vontainer providing the TACACS serve rin this example. - -Load the container image in op-mode. - -```none -add container image lfkeitel/tacacs_plus:latest -``` - -```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 SSH into your system using admin/admin as a default user supplied -from the `lfkeitel/tacacs_plus:latest` container. diff --git a/docs/configuration/system/md-name-server.md b/docs/configuration/system/md-name-server.md deleted file mode 100644 index 9090ba5f..00000000 --- a/docs/configuration/system/md-name-server.md +++ /dev/null @@ -1,65 +0,0 @@ -(system-dns)= - -# System DNS - -:::{warning} -If you are configuring a VRF for management purposes, there is -currently no way to force system DNS traffic via a specific VRF. -::: - -This section describes configuring DNS on the system, namely: - -> - DNS name servers -> - Domain search order - -## DNS name servers - -```{cfgcmd} set system name-server \ - -Use this command to specify a DNS server for the system to be used -for DNS lookups. More than one DNS server can be added, configuring -one at a time. Both IPv4 and IPv6 addresses are supported. -``` - - -### Example - -In this example, some *OpenNIC* servers are used, two IPv4 addresses -and two IPv6 addresses: - -```none -set system name-server 176.9.37.132 -set system name-server 195.10.195.195 -set system name-server 2a01:4f8:161:3441::1 -set system name-server 2a00:f826:8:2::195 -``` - - -## Domain search order - -In order for the system to use and complete unqualified host names, a -list can be defined which will be used for domain searches. - -```{cfgcmd} set system domain-search \ - -Use this command to define domains, one at a time, so that the system -uses them to complete unqualified host names. Maximum: 6 entries. -``` - -:::{note} -Domain names can include letters, numbers, hyphens and periods -with a maximum length of 253 characters. -::: - -(name-server-domain-search-order-example)= - -### Example - -The system is configured to attempt domain completion in the following -order: vyos.io (first), vyos.net (second) and vyos.network (last): - -```none -set system domain-search vyos.io -set system domain-search vyos.net -set system domain-search vyos.network -``` diff --git a/docs/configuration/system/md-option.md b/docs/configuration/system/md-option.md deleted file mode 100644 index 7fbf5d23..00000000 --- a/docs/configuration/system/md-option.md +++ /dev/null @@ -1,186 +0,0 @@ -(system-option)= - -# Option - -This chapter describe the possibilities of advanced system behavior. - -## General - -```{eval-rst} -.. cfgcmd:: set system option ctrl-alt-delete - - Action which will be run once the ctrl-alt-del keystroke is received. -``` - -```{eval-rst} -.. cfgcmd:: set system option reboot-on-panic - - Automatically reboot system on kernel panic after 60 seconds. -``` - -```{eval-rst} -.. cfgcmd:: set system option startup-beep - - Play an audible beep to the system speaker when system is ready. -``` - -```{eval-rst} -.. 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 - -```{eval-rst} -.. 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! -``` - -```{eval-rst} -.. 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! -``` - -```{eval-rst} -.. cfgcmd:: set system option kernel amd-pstate-driver - - Enables and configures p-state driver for modern AMD Ryzen and Epyc CPUs. - - The available modes are: - - * ``active`` This is the low-level firmware control mode based on the profile - set and the system governor has no effect. - * ``passive`` The driver allows the system governor to manage CPU frequency - while providing available performance states. - * ``guided`` The driver allows to set desired performance levels and the firmware - selects a performance level in this range and fitting to the current workload. - - This will add the following two options to the Kernel commandline: - - * ``initcall_blacklist=acpi_cpufreq_init`` Disable default ACPI CPU frequency scale - * ``amd_pstate={mode}`` Sets the p-state mode - - .. note:: Setting will only become active with the next reboot! - - .. seealso:: https://docs.kernel.org/admin-guide/pm/amd-pstate.html -``` - -```{eval-rst} -.. 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 - -```{eval-rst} -.. cfgcmd:: set system option http-client source-address
- - Several commands utilize cURL to initiate transfers. Configure the local - source IPv4/IPv6 address used for all cURL operations. -``` - -```{eval-rst} -.. cfgcmd:: set system option http-client source-interface - - Several commands utilize curl to initiate transfers. Configure the local - source interface used for all CURL operations. -``` - -:::{note} -`source-address` and `source-interface` can not be used at the same -time. -::: - -## SSH client - -```{eval-rst} -.. cfgcmd:: set system option ssh-client source-address
- - Use the specified address on the local machine as the source address of the - connection. Only useful on systems with more than one address. -``` - -```{eval-rst} -.. cfgcmd:: set system option ssh-client source-interface - - Use the address of the specified interface on the local machine as the - source address of the connection. -``` - -## Keyboard Layout - -When starting a VyOS live system (the installation CD) the configured keyboard -layout defaults to US. As this might not suite everyones use case you can adjust -the used keyboard layout on the system console. - -```{eval-rst} -.. cfgcmd:: set system option keyboard-layout - - Change system keyboard layout to given language. - - Defaults to ``us``. - - .. note:: Changing the keymap only has an effect on the system console, using - SSH or Serial remote access to the device is not affected as the keyboard - layout here corresponds to your access system. -``` - -(system-options-performance)= - -## Performance - -As more and more routers run on Hypervisors, expecially with a {abbr}`NOS -(Network Operating System)` as VyOS, it makes fewer and fewer sense to use -static resource bindings like `smp-affinity` as present in VyOS 1.2 and -earlier to pin certain interrupt handlers to specific CPUs. - -We now utilize `tuned` for dynamic resource balancing based on profiles. - - -```{eval-rst} -.. seealso:: https://access.redhat.com/sites/default/files/attachments/201501-perf-brief-low-latency-tuning-rhel7-v2.1.pdf -``` - - -```{eval-rst} -.. 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/md-proxy.md b/docs/configuration/system/md-proxy.md deleted file mode 100644 index 3b12634b..00000000 --- a/docs/configuration/system/md-proxy.md +++ /dev/null @@ -1,27 +0,0 @@ -(system-proxy)= - -# System Proxy - -Some IT environments require the use of a proxy to connect to the Internet. -Without this configuration VyOS updates could not be installed directly by -using the {opcmd}`add system image` command ({ref}`update_vyos`). - -```{cfgcmd} set system proxy url \ - -Set proxy for all connections initiated by VyOS, including HTTP, HTTPS, and -FTP (anonymous ftp). -``` -```{cfgcmd} set system proxy port \ - -Configure proxy port if it does not listen to the default port 80. -``` -```{cfgcmd} set system proxy username \ - -Some proxies require/support the "basic" HTTP authentication scheme as per -{rfc}`7617`, thus a username can be configured. -``` -```{cfgcmd} set system proxy password \ - -Some proxies require/support the "basic" HTTP authentication scheme as per -{rfc}`7617`, thus a password can be configured. -``` \ No newline at end of file diff --git a/docs/configuration/system/md-sflow.md b/docs/configuration/system/md-sflow.md deleted file mode 100644 index c63699db..00000000 --- a/docs/configuration/system/md-sflow.md +++ /dev/null @@ -1,71 +0,0 @@ -# sFlow - -VyOS supports sFlow accounting for both IPv4 and IPv6 traffic. The system acts as a flow exporter, and you are free to use it with any compatible collector. - -sFlow is a technology that enables monitoring of network traffic by sending sampled packets to a collector device. - -The sFlow accounting based on hsflowd - -## Configuration - -```{eval-rst} -.. cfgcmd:: set system sflow agent-address
- - Configure sFlow agent IPv4 or IPv6 address - -``` - -```{eval-rst} -.. cfgcmd:: set system sflow agent-interface - - Configure agent IP address associated with this interface. - -``` - -```{eval-rst} -.. cfgcmd:: set system sflow drop-monitor-limit - - Dropped packets reported on DROPMON Netlink channel by Linux kernel are exported via the standard sFlow v5 extension for reporting dropped packets -``` - -```{eval-rst} -.. cfgcmd:: set system sflow interface - - Configure and enable collection of flow information for the interface identified by . - - You can configure multiple interfaces which whould participate in sflow accounting. - -``` - -```{eval-rst} -.. cfgcmd:: set system sflow polling - - Configure schedule counter-polling in seconds (default: 30) -``` - -```{eval-rst} -.. cfgcmd:: set system sflow sampling-rate - - Use this command to configure the sampling rate for sFlow accounting (default: 1000) -``` - -```{eval-rst} -.. cfgcmd:: set system sflow server
port - - Configure address of sFlow collector. sFlow server at
can be both listening on an IPv4 or IPv6 address. - -``` - -## Example - -```none -set system sflow agent-address '192.0.2.14' -set system sflow agent-interface 'eth0' -set system sflow drop-monitor-limit '50' -set system sflow interface 'eth0' -set system sflow interface 'eth1' -set system sflow polling '30' -set system sflow sampling-rate '1000' -set system sflow server 192.0.2.1 port '6343' -set system sflow server 203.0.113.23 port '6343' -``` diff --git a/docs/configuration/system/md-sysctl.md b/docs/configuration/system/md-sysctl.md deleted file mode 100644 index b815861b..00000000 --- a/docs/configuration/system/md-sysctl.md +++ /dev/null @@ -1,12 +0,0 @@ -(sysctl)= - -# Sysctl - -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/. - -```{eval-rst} -.. cfgcmd:: set system sysctl parameter value -``` diff --git a/docs/configuration/system/md-syslog.md b/docs/configuration/system/md-syslog.md deleted file mode 100644 index b4335c22..00000000 --- a/docs/configuration/system/md-syslog.md +++ /dev/null @@ -1,365 +0,0 @@ -(syslog)= - -# Syslog - -Per default VyOSs has minimal syslog logging enabled which is stored and -rotated locally. Errors will be always logged to a local file, which includes -`local7` error messages, emergency messages will be sent to the console, too. - -To configure syslog, you need to switch into configuration mode. - -## Logging - -Syslog supports logging to multiple targets, those targets could be a plain -file on your VyOS installation itself, a serial console or a remote syslog -server which is reached via {abbr}`IP (Internet Protocol)` UDP/TCP. - -### Console - -```{eval-rst} -.. cfgcmd:: set system syslog console facility level - - Log syslog messages to ``/dev/console``, for an explanation on - {ref}`syslog_facilities` keywords and {ref}`syslog_severity_level` keywords - see tables below. -``` - -(custom-file)= - -### Custom File - -```{eval-rst} -.. cfgcmd:: set system syslog file facility level - - Log syslog messages to file specified via ``, for an explanation on - {ref}`syslog_facilities` keywords and {ref}`syslog_severity_level` keywords - see tables below. -``` - -```{eval-rst} -.. cfgcmd:: set system syslog file archive size - - Syslog will write `` kilobytes into the file specified by ``. - After this limit has been reached, the custom file is "rotated" by logrotate - and a new custom file is created. -``` - -```{eval-rst} -.. cfgcmd:: set system syslog file archive file - - Syslog uses logrotate to rotate logiles after a number of gives bytes. - We keep as many as `` rotated file before they are deleted on the - system. - -``` - -### Remote Host - -Logging to a remote host leaves the local logging configuration intact, it -can be configured in parallel to a custom file or console logging. You can log -to multiple hosts at the same time, using either TCP or UDP. The default is -sending the messages via port 514/UDP. - -```{eval-rst} -.. cfgcmd:: set system syslog host
facility level - - Log syslog messages to remote host specified by `
`. The address - can be specified by either FQDN or IP address. For an explanation on - {ref}`syslog_facilities` keywords and {ref}`syslog_severity_level` - keywords see tables below. - -``` - -```{eval-rst} -.. cfgcmd:: set system syslog host
facility protocol - - - Configure protocol used for communication to remote syslog host. This can be - either UDP or TCP. - -``` - -```{eval-rst} -.. cfgcmd:: set system syslog vrf - - Specify name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance. -``` - -#### {abbr}`TLS (Transport Layer Security)`-encrypted remote logging - -VyOS supports {abbr}`TLS (Transport Layer Security)`-encrypted remote logging -over TCP to ensure secure transmission of syslog data to remote syslog servers. - -**Prerequisites**: Before configuring {abbr}`TLS (Transport Layer -Security)`-encrypted remote logging, ensure you have: - -- A valid remote syslog server address. - -- Valid {abbr}`CA (Certificate Authority)` and client certificates uploaded - to the local {abbr}`PKI (Public Key Infrastructure)` storage. - -- The **remote syslog transport protocol** is set to **TCP**: - - ```none - set system syslog remote
protocol tcp - ``` - -:::{note} -{abbr}`TLS (Transport Layer Security)`-encrypted remote logging is -**not supported** over **UDP**. -::: - -```{eval-rst} -.. cfgcmd:: set system syslog remote
tls - - Enable TLS-encrypted remote logging. -``` - -```{eval-rst} -.. cfgcmd:: set system syslog remote
tls ca-certificate - - **Configure the** {abbr}`CA (Certificate Authority)` **certificate.** - - The syslog client uses the {abbr}`CA (Certificate Authority)` certificate to - verify the identity of the remote syslog server. - - The {abbr}`CA (Certificate Authority)` certificate is required for **all** - authentication modes except ``anon``. -``` - -```{eval-rst} -.. cfgcmd:: set system syslog remote
tls certificate - - **Configure the client certificate.** - - The remote syslog server uses the client certificate to verify the identity - of the syslog client. - - The client certificate is required if the remote syslog server enforces - client certificate verification. -``` - -```{eval-rst} -.. cfgcmd:: set system syslog remote
tls auth-mode - - **Configure the authentication mode.** - - The authentication mode defines how the syslog client verifies the syslog - server's identity. - - The following authentication modes are available: - - * ``anon`` **(default)**: Allows encrypted connections without verifying the syslog - server's identity. This mode is **not recommended**, as it is vulnerable to - {abbr}`MITM (Man-in-the-Middle)` attacks. - * ``fingerprint``: Verifies the server’s certificate fingerprint against the - value preconfigured with: - - .. code-block:: none - - set system syslog remote
tls permitted-peer - - * ``certvalid``: Verifies the server certificate is signed by a trusted - {abbr}`CA (Certificate Authority)`, skipping {abbr}`CN (Common Name)` check. - * ``name``: Verifies that: - - * The server’s certificate is signed by a trusted {abbr}`CA (Certificate - Authority)`. - * The {abbr}`CN (Common Name)` in the certificate matches the value - preconfigured with: - - .. code-block:: none - - set system syslog remote
tls permitted-peer - - This is a **recommended** secure mode for production environments. -``` - -```{eval-rst} -.. cfgcmd:: set system syslog remote
tls permitted-peer - - **Configure the peer certificate identifiers.** - - The certificate identifier format depends on the authentication mode: - - * ``fingerprint``: Enter the expected certificate fingerprints (SHA-1 or - SHA-256). - * ``name``: Enter the expected certificate {abbr}`CNs (Common Names)`. - - For ``anon`` and ``certvalid`` authentication modes, certificate identifiers - are not required. -``` - -#### Examples: - -```none -# Example of 'anon' authentication mode -set system syslog host 10.10.2.3 facility all level debug -set system syslog host 10.10.2.3 port 6514 -set system syslog host 10.10.2.3 protocol tcp -set system syslog host 10.10.2.3 tls auth-mode anon -# or just use 'set system syslog host 10.10.2.3 tls' - -# Example of 'certvalid' authentication mode -set system syslog host elk.example.com facility all level debug -set system syslog host elk.example.com port 6514 -set system syslog host elk.example.com protocol tcp -set system syslog host elk.example.com tls ca-certificate my-ca -set system syslog host elk.example.com tls auth-mode certvalid - -# Example of 'fingerprint' authentication mode -set system syslog host syslog.example.com facility all level debug -set system syslog host syslog.example.com port 6514 -set system syslog host syslog.example.com protocol tcp -set system syslog host syslog.example.com tls ca-certificate my-ca -set system syslog host syslog.example.com tls auth-mode fingerprint -set system syslog host syslog.example.com tls permitted-peer 'SHA1:10:C4:26:...' - -# Example of 'name' authentication mode -set system syslog host graylog.example.com facility all level debug -set system syslog host graylog.example.com port 6514 -set system syslog host graylog.example.com protocol tcp -set system syslog host graylog.example.com tls ca-certificate my-ca -set system syslog host graylog.example.com tls certificate syslog-client -set system syslog host graylog.example.com tls auth-mode name -set system syslog host graylog.example.com tls permitted-peer 'graylog.example.com' -``` - -#### Security Notes - -- Always prefer `auth-mode name` for secure deployments, as it ensures - both CA trust and server hostname validation. -- `anon` mode should only be used for testing, because it does not - authenticate the server. -- Ensure private keys are stored and managed exclusively in the - {doc}`PKI system `. - -### Local User Account - -```{eval-rst} -.. cfgcmd:: set system syslog user facility level - - If logging to a local user account is configured, all defined log messages - are display on the console if the local user is logged in, if the user is not - logged in, no messages are being displayed. For an explanation on - {ref}`syslog_facilities` keywords and {ref}`syslog_severity_level` keywords - see tables below. -``` - -(syslog_facilities)= - -## Facilities - -List of facilities used by syslog. Most facilities names are self explanatory. -Facilities local0 - local7 common usage is f.e. as network logs facilities for -nodes and network equipment. Generally it depends on the situation how to -classify logs and put them to facilities. See facilities more as a tool rather -than a directive to follow. - -Facilities can be adjusted to meet the needs of the user: - -| Facility Code | Keyword | Description | -| ------------- | -------- | ---------------------------------------- | -| | all | All facilities | -| 0 | kern | Kernel messages | -| 1 | user | User-level messages | -| 2 | mail | Mail system | -| 3 | daemon | System daemons | -| 4 | auth | Security/authentication messages | -| 5 | syslog | Messages generated internally by syslogd | -| 6 | lpr | Line printer subsystem | -| 7 | news | Network news subsystem | -| 8 | uucp | UUCP subsystem | -| 9 | cron | Clock daemon | -| 10 | security | Security/authentication messages | -| 11 | ftp | FTP daemon | -| 12 | ntp | NTP subsystem | -| 13 | logaudit | Log audit | -| 14 | logalert | Log alert | -| 15 | clock | clock daemon (note 2) | -| 16 | local0 | local use 0 (local0) | -| 17 | local1 | local use 1 (local1) | -| 18 | local2 | local use 2 (local2) | -| 19 | local3 | local use 3 (local3) | -| 20 | local4 | local use 4 (local4) | -| 21 | local5 | local use 5 (local5) | -| 22 | local6 | use 6 (local6) | -| 23 | local7 | local use 7 (local7) | - -(syslog_severity_level)= - -## Severity Level - -| Value | Severity | Keyword | Description | -| ----- | ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- | -| | | all | Log everything | -| 0 | Emergency | emerg | System is unusable - a panic condition | -| 1 | Alert | alert | Action must be taken immediately - A condition that should be corrected immediately, such as a corrupted system database. | -| 2 | Critical | crit | Critical conditions - e.g. hard drive errors. | -| 3 | Error | err | Error conditions | -| 4 | Warning | warning | Warning conditions | -| 5 | Notice | notice | Normal but significant conditions - conditions that are not error conditions, but that may require special handling. | -| 6 | Informational | info | Informational messages | -| 7 | Debug | debug | Debug-level messages - Messages that contain information normally of use only when debugging a program. | - -## Display Logs - -```{eval-rst} -.. opcmd:: show log [all | authorization | cluster | conntrack-sync | ...] - - Display log files of given category on the console. Use tab completion to get - a list of available categories. Thos categories could be: all, authorization, - cluster, conntrack-sync, dhcp, directory, dns, file, firewall, https, image - lldp, nat, openvpn, snmp, tail, vpn, vrrp -``` - -If no option is specified, this defaults to `all`. - -```{eval-rst} -.. opcmd:: show log image - [all | authorization | directory | file | tail ] - - Log messages from a specified image can be displayed on the console. Details - of allowed parameters: - - .. list-table:: - :widths: 25 75 - :header-rows: 0 - - * - all - - Display contents of all master log files of the specified image - * - authorization - - Display all authorization attempts of the specified image - * - directory - - Display list of all user-defined log files of the specified image - * - file - - Display contents of a specified user-defined log file of the specified - image - * - tail - - Display last lines of the system log of the specified image - * - - - Number of lines to be displayed, default 10 -``` - -When no options/parameters are used, the contents of the main syslog file are -displayed. - -:::{hint} -Use `show log | strip-private` if you want to hide private data -when sharing your logs. -::: - -## Delete Logs - -```{eval-rst} -.. opcmd:: delete log file -``` - -Deletes the specified user-defined file \ in the /var/log/user directory - -Note that deleting the log file does not stop the system from logging events. -If you use this command while the system is logging events, old log events -will be deleted, but events after the delete operation will be recorded in -the new file. To delete the file altogether, first delete logging to the -file using system syslog {ref}`custom-file` command, and then delete the file. diff --git a/docs/configuration/system/md-task-scheduler.md b/docs/configuration/system/md-task-scheduler.md deleted file mode 100644 index 378a648d..00000000 --- a/docs/configuration/system/md-task-scheduler.md +++ /dev/null @@ -1,48 +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 excecuted this way are executed as root user - this may -be dangerous. Together with {ref}`command-scripting` this can be used for -automating (re-)configuration. -::: - -```{eval-rst} -.. cfgcmd:: set system task-scheduler task interval - - Specify the time interval when `` should be executed. The interval - is specified as number with one of the following suffixes: - - * ``none`` - Execution interval in minutes - * ``m`` - Execution interval in minutes - * ``h`` - Execution interval in hours - * ``d`` - Execution interval in days - - .. note:: If suffix is omitted, minutes are implied. -``` - -```{eval-rst} -.. cfgcmd:: set system task-scheduler task crontab-spec - - Set execution time in common cron_ time format. A cron `` of - ``30 */6 * * *`` would execute the `` at minute 30 past every 6th hour. -``` - -```{eval-rst} -.. cfgcmd:: set system task-scheduler task executable path - - Specify absolute `` to script which will be run when `` is - executed. -``` - -```{eval-rst} -.. cfgcmd:: set system task-scheduler task executable arguments - - Arguments which will be passed to the executable. -``` - -[cron]: https://en.wikipedia.org/wiki/Cron diff --git a/docs/configuration/system/md-time-zone.md b/docs/configuration/system/md-time-zone.md deleted file mode 100644 index 2279a773..00000000 --- a/docs/configuration/system/md-time-zone.md +++ /dev/null @@ -1,17 +0,0 @@ -(timezone)= - -# Time Zone - -Time Zone setting is very important as e.g all your logfile entries will be -based on the configured zone. Without proper time zone configuration it will -be very difficult to compare logfiles from different systems. - -```{cfgcmd} set system time-zone \ - -Specify the systems \ as the Region/Location that best defines -your location. For example, specifying US/Pacific sets the time zone to US -Pacific time. - -Command completion can be used to list available time zones. The adjustment -for daylight time will take place automatically based on the time of year. -``` \ No newline at end of file diff --git a/docs/configuration/system/md-updates.md b/docs/configuration/system/md-updates.md deleted file mode 100644 index 05a9d189..00000000 --- a/docs/configuration/system/md-updates.md +++ /dev/null @@ -1,37 +0,0 @@ -# Updates - -VyOS supports online checking for updates - -## Configuration - -```{eval-rst} -.. cfgcmd:: set system update-check auto-check - - Configure auto-checking for new images - -``` - -```{eval-rst} -.. cfgcmd:: set system update-check url - - Configure a URL that contains information about images. - -``` - -## Example - -```none -set system update-check auto-check -set system update-check url 'https://raw.githubusercontent.com/vyos/vyos-rolling-nightly-builds/main/version.json' -``` - -Check: - -```none -vyos@r4:~$ show system updates -Current version: 1.5-rolling-202312220023 - -Update available: 1.5-rolling-202312250024 -Update URL: https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.5-rolling-202312250024/1.5-rolling-202312250024-amd64.iso -vyos@r4:~$ -``` diff --git a/docs/configuration/system/name-server.md b/docs/configuration/system/name-server.md new file mode 100644 index 00000000..9090ba5f --- /dev/null +++ b/docs/configuration/system/name-server.md @@ -0,0 +1,65 @@ +(system-dns)= + +# System DNS + +:::{warning} +If you are configuring a VRF for management purposes, there is +currently no way to force system DNS traffic via a specific VRF. +::: + +This section describes configuring DNS on the system, namely: + +> - DNS name servers +> - Domain search order + +## DNS name servers + +```{cfgcmd} set system name-server \ + +Use this command to specify a DNS server for the system to be used +for DNS lookups. More than one DNS server can be added, configuring +one at a time. Both IPv4 and IPv6 addresses are supported. +``` + + +### Example + +In this example, some *OpenNIC* servers are used, two IPv4 addresses +and two IPv6 addresses: + +```none +set system name-server 176.9.37.132 +set system name-server 195.10.195.195 +set system name-server 2a01:4f8:161:3441::1 +set system name-server 2a00:f826:8:2::195 +``` + + +## Domain search order + +In order for the system to use and complete unqualified host names, a +list can be defined which will be used for domain searches. + +```{cfgcmd} set system domain-search \ + +Use this command to define domains, one at a time, so that the system +uses them to complete unqualified host names. Maximum: 6 entries. +``` + +:::{note} +Domain names can include letters, numbers, hyphens and periods +with a maximum length of 253 characters. +::: + +(name-server-domain-search-order-example)= + +### Example + +The system is configured to attempt domain completion in the following +order: vyos.io (first), vyos.net (second) and vyos.network (last): + +```none +set system domain-search vyos.io +set system domain-search vyos.net +set system domain-search vyos.network +``` diff --git a/docs/configuration/system/name-server.rst b/docs/configuration/system/name-server.rst deleted file mode 100644 index 5d08dbc5..00000000 --- a/docs/configuration/system/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
- - 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 - - 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/option.md b/docs/configuration/system/option.md new file mode 100644 index 00000000..7fbf5d23 --- /dev/null +++ b/docs/configuration/system/option.md @@ -0,0 +1,186 @@ +(system-option)= + +# Option + +This chapter describe the possibilities of advanced system behavior. + +## General + +```{eval-rst} +.. cfgcmd:: set system option ctrl-alt-delete + + Action which will be run once the ctrl-alt-del keystroke is received. +``` + +```{eval-rst} +.. cfgcmd:: set system option reboot-on-panic + + Automatically reboot system on kernel panic after 60 seconds. +``` + +```{eval-rst} +.. cfgcmd:: set system option startup-beep + + Play an audible beep to the system speaker when system is ready. +``` + +```{eval-rst} +.. 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 + +```{eval-rst} +.. 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! +``` + +```{eval-rst} +.. 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! +``` + +```{eval-rst} +.. cfgcmd:: set system option kernel amd-pstate-driver + + Enables and configures p-state driver for modern AMD Ryzen and Epyc CPUs. + + The available modes are: + + * ``active`` This is the low-level firmware control mode based on the profile + set and the system governor has no effect. + * ``passive`` The driver allows the system governor to manage CPU frequency + while providing available performance states. + * ``guided`` The driver allows to set desired performance levels and the firmware + selects a performance level in this range and fitting to the current workload. + + This will add the following two options to the Kernel commandline: + + * ``initcall_blacklist=acpi_cpufreq_init`` Disable default ACPI CPU frequency scale + * ``amd_pstate={mode}`` Sets the p-state mode + + .. note:: Setting will only become active with the next reboot! + + .. seealso:: https://docs.kernel.org/admin-guide/pm/amd-pstate.html +``` + +```{eval-rst} +.. 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 + +```{eval-rst} +.. cfgcmd:: set system option http-client source-address
+ + Several commands utilize cURL to initiate transfers. Configure the local + source IPv4/IPv6 address used for all cURL operations. +``` + +```{eval-rst} +.. cfgcmd:: set system option http-client source-interface + + Several commands utilize curl to initiate transfers. Configure the local + source interface used for all CURL operations. +``` + +:::{note} +`source-address` and `source-interface` can not be used at the same +time. +::: + +## SSH client + +```{eval-rst} +.. cfgcmd:: set system option ssh-client source-address
+ + Use the specified address on the local machine as the source address of the + connection. Only useful on systems with more than one address. +``` + +```{eval-rst} +.. cfgcmd:: set system option ssh-client source-interface + + Use the address of the specified interface on the local machine as the + source address of the connection. +``` + +## Keyboard Layout + +When starting a VyOS live system (the installation CD) the configured keyboard +layout defaults to US. As this might not suite everyones use case you can adjust +the used keyboard layout on the system console. + +```{eval-rst} +.. cfgcmd:: set system option keyboard-layout + + Change system keyboard layout to given language. + + Defaults to ``us``. + + .. note:: Changing the keymap only has an effect on the system console, using + SSH or Serial remote access to the device is not affected as the keyboard + layout here corresponds to your access system. +``` + +(system-options-performance)= + +## Performance + +As more and more routers run on Hypervisors, expecially with a {abbr}`NOS +(Network Operating System)` as VyOS, it makes fewer and fewer sense to use +static resource bindings like `smp-affinity` as present in VyOS 1.2 and +earlier to pin certain interrupt handlers to specific CPUs. + +We now utilize `tuned` for dynamic resource balancing based on profiles. + + +```{eval-rst} +.. seealso:: https://access.redhat.com/sites/default/files/attachments/201501-perf-brief-low-latency-tuning-rhel7-v2.1.pdf +``` + + +```{eval-rst} +.. 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/option.rst b/docs/configuration/system/option.rst deleted file mode 100644 index d039315c..00000000 --- a/docs/configuration/system/option.rst +++ /dev/null @@ -1,169 +0,0 @@ -.. _system_option: - -###### -Option -###### - -This chapter describe the possibilities of advanced system behavior. - -******* -General -******* - -.. cfgcmd:: set system option ctrl-alt-delete - - Action which will be run once the ctrl-alt-del keystroke is received. - -.. cfgcmd:: set system option reboot-on-panic - - Automatically reboot system on kernel panic after 60 seconds. - -.. cfgcmd:: set system option startup-beep - - Play an audible beep to the system speaker when system is ready. - -.. cfgcmd:: set system option root-partition-auto-resize - - Enables the root partition auto-extension and resizes to the maximum - available space on system boot. - -Kernel -====== - -.. cfgcmd:: set system option kernel disable-mitigations - - Disable all optional CPU mitigations. This improves system performance, - but it may also expose users to several CPU vulnerabilities. - - This will add the following option to the Kernel commandline: - - * ``mitigations=off`` - - .. note:: Setting will only become active with the next reboot! - -.. cfgcmd:: set system option kernel disable-power-saving - - This will add the following two options to the Kernel commandline: - - * ``intel_idle.max_cstate=0`` Disable intel_idle and fall back on acpi_idle - * ``processor.max_cstate=1`` Limit processor to maximum C-state 1 - - .. note:: Setting will only become active with the next reboot! - -.. cfgcmd:: set system option kernel amd-pstate-driver - - Enables and configures p-state driver for modern AMD Ryzen and Epyc CPUs. - - The available modes are: - - * ``active`` This is the low-level firmware control mode based on the profile - set and the system governor has no effect. - * ``passive`` The driver allows the system governor to manage CPU frequency - while providing available performance states. - * ``guided`` The driver allows to set desired performance levels and the firmware - selects a performance level in this range and fitting to the current workload. - - This will add the following two options to the Kernel commandline: - - * ``initcall_blacklist=acpi_cpufreq_init`` Disable default ACPI CPU frequency scale - * ``amd_pstate={mode}`` Sets the p-state mode - - .. note:: Setting will only become active with the next reboot! - - .. seealso:: 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
- - Several commands utilize cURL to initiate transfers. Configure the local - source IPv4/IPv6 address used for all cURL operations. - -.. cfgcmd:: set system option http-client source-interface - - Several commands utilize curl to initiate transfers. Configure the local - source interface used for all CURL operations. - -.. note:: `source-address` and `source-interface` can not be used at the same - time. - -********** -SSH client -********** - -.. cfgcmd:: set system option ssh-client source-address
- - Use the specified address on the local machine as the source address of the - connection. Only useful on systems with more than one address. - -.. cfgcmd:: set system option ssh-client source-interface - - Use the address of the specified interface on the local machine as the - source address of the connection. - -*************** -Keyboard Layout -*************** - -When starting a VyOS live system (the installation CD) the configured keyboard -layout defaults to US. As this might not suite everyones use case you can adjust -the used keyboard layout on the system console. - -.. cfgcmd:: set system option keyboard-layout - - Change system keyboard layout to given language. - - Defaults to ``us``. - - .. note:: Changing the keymap only has an effect on the system console, using - SSH or Serial remote access to the device is not affected as the keyboard - layout here corresponds to your access system. - -.. _system_options_performance: - -*********** -Performance -*********** - -As more and more routers run on Hypervisors, expecially with a :abbr:`NOS -(Network Operating System)` as VyOS, it makes fewer and fewer sense to use -static resource bindings like ``smp-affinity`` as present in VyOS 1.2 and -earlier to pin certain interrupt handlers to specific CPUs. - -We now utilize `tuned` for dynamic resource balancing based on profiles. - -.. stop_vyoslinter - -.. seealso:: https://access.redhat.com/sites/default/files/attachments/201501-perf-brief-low-latency-tuning-rhel7-v2.1.pdf - -.. start_vyoslinter - -.. cfgcmd:: set system option performance < throughput | latency > - - Configure one of the predefined system performance profiles. - - * ``throughput``: A server profile focused on improving network throughput. - This profile favors performance over power savings by setting - ``intel_pstate`` and ``max_perf_pct=100`` and increasing kernel network - buffer sizes. - - It enables transparent huge pages, and uses cpupower to set the performance - cpufreq governor. It also sets ``kernel.sched_min_granularity_ns`` to 10 us, - ``kernel.sched_wakeup_granularity_ns`` to 15 uss, and ``vm.dirty_ratio`` to - 40%. - - * ``latency``: A server profile focused on lowering network latency. - This profile favors performance over power savings by setting - ``intel_pstate`` and ``min_perf_pct=100``. - - It disables transparent huge pages, and automatic NUMA balancing. It also - uses cpupower to set the performance cpufreq governor, and requests a - cpu_dma_latency value of 1. It also sets busy_read and busy_poll times to - 50 us, and tcp_fastopen to 3. diff --git a/docs/configuration/system/proxy.md b/docs/configuration/system/proxy.md new file mode 100644 index 00000000..3b12634b --- /dev/null +++ b/docs/configuration/system/proxy.md @@ -0,0 +1,27 @@ +(system-proxy)= + +# System Proxy + +Some IT environments require the use of a proxy to connect to the Internet. +Without this configuration VyOS updates could not be installed directly by +using the {opcmd}`add system image` command ({ref}`update_vyos`). + +```{cfgcmd} set system proxy url \ + +Set proxy for all connections initiated by VyOS, including HTTP, HTTPS, and +FTP (anonymous ftp). +``` +```{cfgcmd} set system proxy port \ + +Configure proxy port if it does not listen to the default port 80. +``` +```{cfgcmd} set system proxy username \ + +Some proxies require/support the "basic" HTTP authentication scheme as per +{rfc}`7617`, thus a username can be configured. +``` +```{cfgcmd} set system proxy password \ + +Some proxies require/support the "basic" HTTP authentication scheme as per +{rfc}`7617`, thus a password can be configured. +``` \ No newline at end of file diff --git a/docs/configuration/system/proxy.rst b/docs/configuration/system/proxy.rst deleted file mode 100644 index 8e0339a7..00000000 --- a/docs/configuration/system/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 - - Set proxy for all connections initiated by VyOS, including HTTP, HTTPS, and - FTP (anonymous ftp). - -.. cfgcmd:: set system proxy port - - Configure proxy port if it does not listen to the default port 80. - -.. cfgcmd:: set system proxy username - - Some proxys require/support the "basic" HTTP authentication scheme as per - :rfc:`7617`, thus a username can be configured. - -.. cfgcmd:: set system proxy password - - Some proxys require/support the "basic" HTTP authentication scheme as per - :rfc:`7617`, thus a password can be configured. diff --git a/docs/configuration/system/rst-acceleration.rst b/docs/configuration/system/rst-acceleration.rst new file mode 100644 index 00000000..63506d6d --- /dev/null +++ b/docs/configuration/system/rst-acceleration.rst @@ -0,0 +1,157 @@ +.. _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 config + + Show the full config uploaded to the QAT device. + +.. opcmd:: show system acceleration qat device flows + + Get an overview over the encryption counters. + +.. opcmd:: show system acceleration qat interrupts + + Show binded qat device interrupts to certain core. + + +Example +======= + +Let's build a simple VPN between 2 Intel® QAT ready devices. + +Side A: + +.. 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 new file mode 100644 index 00000000..68a4f2b8 --- /dev/null +++ b/docs/configuration/system/rst-conntrack.rst @@ -0,0 +1,187 @@ + +######### +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`. + + +Define Conection Timeouts +========================= + +VyOS supports setting timeouts for connections according to the +connection type. You can set timeout values for generic connections, for ICMP +connections, UDP connections, or for TCP connections in a number of different +states. + +.. cfgcmd:: set system conntrack timeout icmp <1-21474836> + :defaultvalue: +.. cfgcmd:: set system conntrack timeout other <1-21474836> + :defaultvalue: +.. cfgcmd:: set system conntrack timeout tcp close <1-21474836> + :defaultvalue: +.. cfgcmd:: set system conntrack timeout tcp close-wait <1-21474836> + :defaultvalue: +.. cfgcmd:: set system conntrack timeout tcp established <1-21474836> + :defaultvalue: +.. cfgcmd:: set system conntrack timeout tcp fin-wait <1-21474836> + :defaultvalue: +.. cfgcmd:: set system conntrack timeout tcp last-ack <1-21474836> + :defaultvalue: +.. cfgcmd:: set system conntrack timeout tcp syn-recv <1-21474836> + :defaultvalue: +.. cfgcmd:: set system conntrack timeout tcp syn-sent <1-21474836> + :defaultvalue: +.. cfgcmd:: set system conntrack timeout tcp time-wait <1-21474836> + :defaultvalue: +.. cfgcmd:: set system conntrack timeout udp other <1-21474836> + :defaultvalue: +.. cfgcmd:: set system conntrack timeout udp stream <1-21474836> + :defaultvalue: + + Set the timeout in secounds for a protocol or state. + + +You can also define custom timeout values to apply to a specific subset of +connections, based on a packet and flow selector. To do this, you need to +create a rule defining the packet and flow selector. + +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> description + + Set a rule description. + + +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> destination address +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> source address + + set a destination and/or source address. Accepted input: + + .. code-block:: none + + IP address to match + Subnet to match + - + IP range to match + ! Match everything except the specified address + ! Match everything except the specified subnet + !- + Match everything except the specified range + +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> destination port +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> source port + + Set a destination and/or source port. Accepted input: + + .. code-block:: none + + Named port (any name in /etc/services, e.g., http) + <1-65535> Numbered port + - Numbered port range (e.g., 1001-1005) + + Multiple destination ports can be specified as a comma-separated list. + The whole list can also be "negated" using '!'. For example: + `!22,telnet,http,123,1001-1005`` + + + +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol icmp <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol other <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp close <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp close-wait <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp established <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp fin-wait <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp last-ack <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp syn-recv <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp syn-sent <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol tcp time-wait <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol udp other <1-21474836> +.. cfgcmd:: set system conntrack timeout custom rule <1-9999> protocol udp stream <1-21474836> + + Set the timeout in secounds for a protocol or state in a custom rule. + + +.. cfgcmd:: set system conntrack tcp half-open-connections <1-21474836> + :defaultvalue: + + Set the maximum number of TCP half-open connections. + +.. cfgcmd:: set system conntrack tcp loose + :defaultvalue: + + Policy to track previously established connections. + +.. cfgcmd:: set system conntrack tcp max-retrans <1-2147483647> + :defaultvalue: + + Set the number of TCP maximum retransmit attempts. + +.. cfgcmd:: set system conntrack ignore rule <1-9999> description +.. cfgcmd:: set system conntrack ignore rule <1-9999> destination address +.. cfgcmd:: set system conntrack ignore rule <1-9999> destination port +.. cfgcmd:: set system conntrack ignore rule <1-9999> inbound-interface +.. cfgcmd:: set system conntrack ignore rule <1-9999> protocol +.. cfgcmd:: set system conntrack ignore rule <1-9999> source address +.. cfgcmd:: set system conntrack ignore rule <1-9999> source port + + Customized ignore rules, based on a packet and flow selector. + +.. cfgcmd:: set system conntrack log icmp destroy +.. cfgcmd:: set system conntrack log icmp new +.. cfgcmd:: set system conntrack log icmp update +.. cfgcmd:: set system conntrack log other destroy +.. cfgcmd:: set system conntrack log other new +.. cfgcmd:: set system conntrack log other update +.. cfgcmd:: set system conntrack log tcp destroy +.. cfgcmd:: set system conntrack log tcp new +.. cfgcmd:: set system conntrack log tcp update close-wait +.. cfgcmd:: set system conntrack log tcp update established +.. cfgcmd:: set system conntrack log tcp update fin-wait +.. cfgcmd:: set system conntrack log tcp update last-ack +.. cfgcmd:: set system conntrack log tcp update syn-received +.. cfgcmd:: set system conntrack log tcp update time-wait +.. cfgcmd:: set system conntrack log udp destroy +.. cfgcmd:: set system conntrack log udp new +.. cfgcmd:: set system conntrack log udp update + + Log the connection tracking events per protocol. \ No newline at end of file diff --git a/docs/configuration/system/rst-console.rst b/docs/configuration/system/rst-console.rst new file mode 100644 index 00000000..1f917e54 --- /dev/null +++ b/docs/configuration/system/rst-console.rst @@ -0,0 +1,46 @@ +.. _serial-console: + +############## +Serial Console +############## + +For the average user a serial console has no advantage over a console offered +by a directly attached keyboard and screen. Serial consoles are much slower, +taking up to a second to fill a 80 column by 24 line screen. Serial consoles +generally only support non-proportional ASCII text, with limited support for +languages other than English. + +There are some scenarios where serial consoles are useful. System administration +of remote computers is usually done using :ref:`ssh`, but there are times when +access to the console is the only way to diagnose and correct software failures. +Major upgrades to the installed distribution may also require console access. + + +.. cfgcmd:: set system console device + + Defines the specified device as a system console. Available console devices + can be (see completion helper): + + * ``ttySN`` - Serial device name + * ``ttyUSBX`` - USB Serial device name + * ``hvc0`` - Xen console + +.. cfgcmd:: set system console device 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 new file mode 100644 index 00000000..e102eb9c --- /dev/null +++ b/docs/configuration/system/rst-default-route.rst @@ -0,0 +1,40 @@ +.. _default_gateway: + +##################### +Default Gateway/Route +##################### + +In the past (VyOS 1.1) used a gateway-address configured under the system tree +(:cfgcmd:`set system gateway-address
`), this is no longer supported +and existing configurations are migrated to the new CLI command. + +Configuration +============= + +.. cfgcmd:: set protocols static route 0.0.0.0/0 next-hop
+ + Specify static route into the routing table sending all non local traffic + to the nexthop address `
`. + + +.. cfgcmd:: delete protocols static route 0.0.0.0/0 + + Delete default route from the system. + +Operation +========= + +.. opcmd:: show ip route 0.0.0.0 + + Show routing table entry for the default route. + + .. code-block:: none + + vyos@vyos:~$ show ip route 0.0.0.0 + Routing entry for 0.0.0.0/0 + Known via "static", distance 10, metric 0, best + Last update 09:46:30 ago + * 172.18.201.254, via eth0.201 + +.. seealso:: Configuration of :ref:`routing-static` + diff --git a/docs/configuration/system/rst-flow-accounting.rst b/docs/configuration/system/rst-flow-accounting.rst new file mode 100644 index 00000000..7ed2d88c --- /dev/null +++ b/docs/configuration/system/rst-flow-accounting.rst @@ -0,0 +1,216 @@ +.. _flow-accounting: + +############### +Flow Accounting +############### + +VyOS supports flow-accounting for both IPv4 and IPv6 traffic. The system acts +as a flow exporter, and you are free to use it with any compatible collector. + +Flows can be exported via two different protocols: NetFlow (versions 5, 9 and +10/IPFIX) and sFlow. Additionally, you may save flows to an in-memory table +internally in a router. + +.. warning:: You need to disable the in-memory table in production environments! + Using :abbr:`IMT (In-Memory Table)` may lead to heavy CPU overloading and + unstable flow-accounting behavior. + + +NetFlow / IPFIX +=============== +NetFlow is a feature that was introduced on Cisco routers around 1996 that +provides the ability to collect IP network traffic as it enters or exits an +interface. By analyzing the data provided by NetFlow, a network administrator +can determine things such as the source and destination of traffic, class of +service, and the causes of congestion. A typical flow monitoring setup (using +NetFlow) consists of three main components: + +* **exporter**: aggregates packets into flows and exports flow records towards + one or more flow collectors +* **collector**: responsible for reception, storage and pre-processing of flow + data received from a flow exporter +* **application**: analyzes received flow data in the context of intrusion + detection or traffic profiling, for example + +For connectionless protocols as like ICMP and UDP, a flow is considered +complete once no more packets for this flow appear after configurable timeout. + +NetFlow is usually enabled on a per-interface basis to limit load on the router +components involved in NetFlow, or to limit the amount of NetFlow records +exported. + +Configuration +============= + +.. warning:: Using NetFlow on routers with high traffic levels may lead to + high CPU usage and may affect the router's performance. In such cases, + consider using sFlow instead. + +In order for flow accounting information to be collected and displayed for an +interface, the interface must be configured for flow accounting. + +.. cfgcmd:: set system flow-accounting interface + + Configure and enable collection of flow information for the interface + identified by ``. + + You can configure multiple interfaces which whould participate in flow + accounting. + +.. note:: Will be recorded only packets/flows on **incoming** direction in + configured interfaces by default. + + +By default, recorded flows will be saved internally and can be listed with the +CLI command. You may disable using the local in-memory table with the command: + +.. cfgcmd:: set system flow-accounting disable-imt + + If you need to sample also egress traffic, you may want to + configure egress flow-accounting: + +.. cfgcmd:: set system flow-accounting enable-egress + + Internally, in flow-accounting processes exist a buffer for data exchanging + between core process and plugins (each export target is a separated plugin). + If you have high traffic levels or noted some problems with missed records + or stopping exporting, you may try to increase a default buffer size (10 + MiB) with the next command: + +.. cfgcmd:: set system flow-accounting buffer-size + + 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 + + TBD + +Flow Export +----------- + +In addition to displaying flow accounting information locally, one can also +exported them to a collection server. + +NetFlow +^^^^^^^ + +.. cfgcmd:: set system flow-accounting netflow version + + There are multiple versions available for the NetFlow data. The `` + used in the exported flow data can be configured here. The following + versions are supported: + + * **5** - Most common version, but restricted to IPv4 flows only + * **9** - NetFlow version 9 (default) + * **10** - :abbr:`IPFIX (IP Flow Information Export)` as per :rfc:`3917` + +.. cfgcmd:: set system flow-accounting netflow server
+ + Configure address of NetFlow collector. NetFlow server at `
` can + be both listening on an IPv4 or IPv6 address. + +.. cfgcmd:: set system flow-accounting netflow source-ip
+ + IPv4 or IPv6 source address of NetFlow packets + +.. cfgcmd:: set system flow-accounting netflow engine-id + + NetFlow engine-id which will appear in NetFlow data. The range is 0 to 255. + +.. cfgcmd:: set system flow-accounting netflow sampling-rate + + Use this command to configure the sampling rate for flow accounting. The + system samples one in every `` packets, where `` is the value + configured for the sampling-rate option. The advantage of sampling every n + packets, where n > 1, allows you to decrease the amount of processing + resources required for flow accounting. The disadvantage of not sampling + every packet is that the statistics produced are estimates of actual data + flows. + + Per default every packet is sampled (that is, the sampling rate is 1). + +.. cfgcmd:: set system flow-accounting netflow timeout expiry-interval + + + Specifies the interval at which Netflow data will be sent to a collector. As + per default, Netflow data will be sent every 60 seconds. + + You may also additionally configure timeouts for different types of + connections. + +.. cfgcmd:: set system flow-accounting netflow max-flows + + If you want to change the maximum number of flows, which are tracking + simultaneously, you may do this with this command (default 8192). + +sFlow +^^^^^ + +.. note:: Using `system sflow` is recommended in favor of + `system flow-accounting`. See `sflow `_ + +.. cfgcmd:: set system flow-accounting sflow server
+ + Configure address of sFlow collector. sFlow server at `
` can + be an IPv4 or IPv6 address. But you cannot export to both IPv4 and + IPv6 collectors at the same time! + +.. cfgcmd:: set system flow-accounting sflow sampling-rate + + Enable sampling of packets, which will be transmitted to sFlow collectors. + +.. cfgcmd:: set system flow-accounting sflow agent-address
+ + Configure a sFlow agent address. It can be IPv4 or IPv6 address, but you + must set the same protocol, which is used for sFlow collector addresses. By + default, using router-id from BGP or OSPF protocol, or the primary IP + address from the first interface. + +Example: +-------- + +NetFlow v5 example: + +.. code-block:: none + + set system flow-accounting netflow engine-id 100 + set system flow-accounting netflow version 5 + set system flow-accounting netflow server 192.168.2.10 port 2055 + +Operation +========= + +Once flow accounting is configured on an interfaces it provides the ability to +display captured network traffic information for all configured interfaces. + +.. opcmd:: show flow-accounting interface + + Show flow accounting information for given ``. + + .. code-block:: none + + vyos@vyos:~$ show flow-accounting interface eth0 + IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES + ---------- ----------------- ----------------- ------------------------ --------------- ---------- ---------- ---------- ----- --------- ------- ------- + eth0 00:53:01:a8:28:ac ff:ff:ff:ff:ff:ff 192.0.2.2 255.255.255.255 5678 5678 udp 0 1 1 178 + eth0 00:53:01:b2:2f:34 33:33:ff:00:00:00 fe80::253:01ff:feb2:2f34 ff02::1:ff00:0 0 0 ipv6-icmp 0 2 1 144 + eth0 00:53:01:1a:b4:53 33:33:ff:00:00:00 fe80::253:01ff:fe1a:b453 ff02::1:ff00:0 0 0 ipv6-icmp 0 1 1 72 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 39 1 2064 + eth0 00:53:01:c8:33:af ff:ff:ff:ff:ff:ff 192.0.2.3 255.255.255.255 5678 5678 udp 0 1 1 154 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 146 1 9444 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 27 1 4455 + +.. opcmd:: show flow-accounting interface host
+ + Show flow accounting information for given `` for a specific host + only. + + .. code-block:: none + + vyos@vyos:~$ show flow-accounting interface eth0 host 192.0.2.14 + IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES + ---------- ----------------- ----------------- ----------- ---------- ---------- ---------- ---------- ----- --------- ------- ------- + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 197 2 12940 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 94 1 4924 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 36 1 5877 diff --git a/docs/configuration/system/rst-frr.rst b/docs/configuration/system/rst-frr.rst new file mode 100644 index 00000000..a7f7ff93 --- /dev/null +++ b/docs/configuration/system/rst-frr.rst @@ -0,0 +1,38 @@ +.. _system_frr: + +### +FRR +### + +VyOS uses [FRRouting](https://frrouting.org/) as the control plane for dynamic +and static routing. The routing daemon behavior can be adjusted during runtime, +but require either a restart of the routing daemon, or a reboot of the system. + +.. cfgcmd:: set system frr bmp + + Enable :abbr:`BMP (BGP Monitoring Protocol)` support + +.. cfgcmd:: set system frr descriptors + + This allows the operator to control the number of open file descriptors + each daemon is allowed to start with. If the operator plans to run bgp with + several thousands of peers then this is where we would modify FRR to allow + this to happen. + +.. cfgcmd:: set system frr irdp + + Enable ICMP Router Discovery Protocol support + +.. cfgcmd:: set system frr snmp + + 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 new file mode 100644 index 00000000..4d1567bf --- /dev/null +++ b/docs/configuration/system/rst-host-name.rst @@ -0,0 +1,68 @@ +.. _host-information: + +################ +Host Information +################ + +This section describes the system's host information and how to configure them, +it covers the following topics: + +* Host name +* Domain +* IP address +* Aliases + +Hostname +======== + +A hostname is the label (name) assigned to a network device (a host) on a +network and is used to distinguish one device from another on specific networks +or over the internet. On the other hand this will be the name which appears on +the command line prompt. + +.. cfgcmd:: set system host-name + + The hostname can be up to 63 characters. A hostname + must start and end with a letter or digit, and have as interior characters + only letters, digits, or a hyphen. + + The default hostname used is `vyos`. + +Domain Name +=========== + +A domain name is the label (name) assigned to a computer network and is thus +unique. VyOS appends the domain name as a suffix to any unqualified name. For +example, if you set the domain name `example.com`, and you would ping the +unqualified name of `crux`, then VyOS qualifies the name to `crux.example.com`. + +.. cfgcmd:: set system domain-name + + Configure system domain name. A domain name must start and end with a letter + or digit, and have as interior characters only letters, digits, or a hyphen. + +Static Hostname Mapping +======================= + +How an IP address is assigned to an interface in :ref:`ethernet-interface`. +This section shows how to statically map an IP address to a hostname for local +(meaning on this VyOS instance) name resolution. This is the VyOS equivalent to +`/etc/hosts` file entries. + +.. note:: Do *not* manually edit `/etc/hosts`. This file will automatically be + regenerated on boot based on the settings in this section, which means you'll + lose all your manual edits. Instead, configure static host mappings as follows. + +.. cfgcmd:: set system static-host-mapping host-name inet
+ + Create a static hostname mapping which will always resolve the name + `` to IP address `
`. + + +.. cfgcmd:: set system static-host-mapping host-name alias + + Create named `` for the configured static mapping for ``. + Thus the address configured as :cfgcmd:`set system static-host-mapping + host-name inet
` can be reached via multiple names. + + Multiple aliases can be specified per host-name. diff --git a/docs/configuration/system/rst-index.rst b/docs/configuration/system/rst-index.rst new file mode 100644 index 00000000..dbb63d09 --- /dev/null +++ b/docs/configuration/system/rst-index.rst @@ -0,0 +1,35 @@ +###### +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 + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + default-route diff --git a/docs/configuration/system/rst-ip.rst b/docs/configuration/system/rst-ip.rst new file mode 100644 index 00000000..279630e2 --- /dev/null +++ b/docs/configuration/system/rst-ip.rst @@ -0,0 +1,107 @@ +## +IP +## + +System configuration commands +----------------------------- + +.. cfgcmd:: set system ip disable-forwarding + + Use this command to disable IPv4 forwarding on all interfaces. + +.. cfgcmd:: set system ip disable-directed-broadcast + + Use this command to disable IPv4 directed broadcast forwarding on all + interfaces. + + If set, IPv4 directed broadcast forwarding will be completely disabled + regardless of whether per-interface directed broadcast forwarding is + enabled or not. + +.. cfgcmd:: set system ip arp table-size + + Use this command to define the maximum number of entries to keep in + the ARP cache (1024, 2048, 4096, 8192, 16384, 32768). + +.. cfgcmd:: set system ip multipath layer4-hashing + + Use this command to use Layer 4 information for IPv4 ECMP hashing. + +Zebra/Kernel route filtering +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Zebra supports prefix-lists and Route Mapss to match routes received from +other FRR components. The permit/deny facilities provided by these commands +can be used to filter which routes zebra will install in the kernel. + +.. cfgcmd:: set system ip protocol route-map + + Apply a route-map filter to routes for the specified protocol. The following + protocols can be used: any, babel, bgp, connected, eigrp, isis, kernel, + ospf, rip, static, table + + .. 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 wan't 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 new file mode 100644 index 00000000..ee0fa341 --- /dev/null +++ b/docs/configuration/system/rst-ipv6.rst @@ -0,0 +1,205 @@ +#### +IPv6 +#### + +System configuration commands +----------------------------- + +.. cfgcmd:: set system ipv6 disable-forwarding + + Use this command to disable IPv6 forwarding on all interfaces. + +.. cfgcmd:: set system ipv6 neighbor table-size + + Use this command to define the maximum number of entries to keep in + the Neighbor cache (1024, 2048, 4096, 8192, 16384, 32768). + +.. cfgcmd:: set system ipv6 strict-dad + + Use this command to disable IPv6 operation on interface when + Duplicate Address Detection fails on Link-Local address. + +.. cfgcmd:: set system ipv6 multipath layer4-hashing + + Use this command to user Layer 4 information for ECMP hashing. + +Zebra/Kernel route filtering +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Zebra supports prefix-lists and Route Mapss to match routes received from +other FRR components. The permit/deny facilities provided by these commands +can be used to filter which routes zebra will install in the kernel. + +.. cfgcmd:: set system ipv6 protocol route-map + + Apply a route-map filter to routes for the specified protocol. The following + protocols can be used: any, babel, bgp, connected, isis, kernel, ospfv3, + ripng, static, table + + .. 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 wan't to e.g. allow BGP to peer across the default route. + +.. cfgcmd:: set system ipv6 nht no-resolve-via-default + + Do not allow IPv6 nexthop tracking to resolve via the default route. This + parameter is configured per-VRF, so the command is also available in the VRF + subnode. + +Operational commands +-------------------- + +Show commands +^^^^^^^^^^^^^ + +.. opcmd:: show ipv6 neighbors + + Use this command to show IPv6 Neighbor Discovery Protocol information. + +.. opcmd:: show ipv6 groups + + Use this command to show IPv6 multicast group membership. + +.. opcmd:: show ipv6 forwarding + + Use this command to show IPv6 forwarding status. + +.. opcmd:: show ipv6 route + + Use this command to show IPv6 routes. + + Check the many parameters available for the `show ipv6 route` command: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 route + Possible completions: + Execute the current command + Show IPv6 routes of given address or prefix + + bgp Show IPv6 BGP routes + cache Show kernel IPv6 route cache + connected Show IPv6 connected routes + forward Show kernel IPv6 route table + isis Show IPv6 ISIS routes + kernel Show IPv6 kernel routes + ospfv3 Show IPv6 OSPF6 routes + ripng Show IPv6 RIPNG routes + static Show IPv6 static routes + summary Show IPv6 routes summary + table Show IP routes in policy table + vrf Show IPv6 routes in VRF + + +.. opcmd:: show ipv6 prefix-list + + Use this command to show all IPv6 prefix lists + + There are different parameters for getting prefix-list information: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 prefix-list + Possible completions: + Execute the current command + Show specified IPv6 prefix-list + detail Show detail of IPv6 prefix-lists + summary Show summary of IPv6 prefix-lists + +.. opcmd:: show ipv6 access-list + + Use this command to show all IPv6 access lists + + You can also specify which IPv6 access-list should be shown: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 access-list + Possible completions: + Execute the current command + Show specified IPv6 access-list + +.. opcmd:: show ipv6 bgp + + Use this command to show IPv6 Border Gateway Protocol information. + + + In addition, you can specify many other parameters to get BGP + information: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 bgp + Possible completions: + Execute the current command + Show BGP information for given address or prefix + + community Show routes matching the communities + community-list + Show routes matching the community-list + filter-list Show routes conforming to the filter-list + large-community + Show routes matching the large-community-list + large-community-list + neighbors Show detailed information on TCP and BGP neighbor connections + prefix-list Show routes matching the prefix-list + regexp Show routes matching the AS path regular expression + route-map Show BGP routes matching the specified route map + summary Show summary of BGP neighbor status + + +.. opcmd:: show ipv6 ospfv3 + + Use this command to get information about OSPFv3. + + You can get more specific OSPFv3 information by using the parameters + shown below: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 ospfv3 + Possible completions: + Execute the current command + area Show OSPFv3 spf-tree information + border-routers + Show OSPFv3 border-router (ABR and ASBR) information + database Show OSPFv3 Link state database information + interface Show OSPFv3 interface information + linkstate Show OSPFv3 linkstate routing information + neighbor Show OSPFv3 neighbor information + redistribute Show OSPFv3 redistribute External information + route Show OSPFv3 routing table information + +.. opcmd:: show ipv6 ripng + + Use this command to get information about the RIPNG protocol + +.. opcmd:: show ipv6 ripng status + + Use this command to show the status of the RIPNG protocol + + +Reset commands +^^^^^^^^^^^^^^ + +.. opcmd:: reset bgp ipv6
+ + Use this command to clear Border Gateway Protocol statistics or + status. + + +.. opcmd:: reset ipv6 neighbors
+ + Use this command to reset IPv6 Neighbor Discovery Protocol cache for + an address or interface. + +.. opcmd:: reset ipv6 route cache + + Use this command to flush the kernel IPv6 route cache. + An address can be added to flush it only for that route. diff --git a/docs/configuration/system/rst-lcd.rst b/docs/configuration/system/rst-lcd.rst new file mode 100644 index 00000000..808d45a2 --- /dev/null +++ b/docs/configuration/system/rst-lcd.rst @@ -0,0 +1,45 @@ +.. _system-display: + +******************** +System Display (LCD) +******************** + +The system LCD :abbr:`LCD (Liquid-crystal display)` option is for users running +VyOS on hardware that features an LCD display. This is typically a small display +built in an 19 inch rack-mountable appliance. Those displays are used to show +runtime data. + +To configure your LCD display you must first identify the used hardware, and +connectivity of the display to your system. This can be any serial port +(`ttySxx`) or serial via USB or even old parallel port interfaces. + +Configuration +============= + +.. cfgcmd:: set system lcd device + + 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 + + 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 new file mode 100644 index 00000000..6009a39b --- /dev/null +++ b/docs/configuration/system/rst-login.rst @@ -0,0 +1,425 @@ +:lastproofread: 2022-10-15 + +.. _user_management: + +##################### +Login/User Management +##################### + +The default VyOS user account (`vyos`), as well as newly created user accounts, +have all capabilities to configure the system. All accounts have sudo +capabilities and therefore can operate as root on the system. + +Both local administered and remote administered :abbr:`RADIUS (Remote +Authentication Dial-In User Service)` accounts are supported. + +Local +===== + +.. cfgcmd:: set system login user full-name "" + + Create new system user with username `` and real-name specified by + ``. + +.. cfgcmd:: set system login user authentication plaintext-password + + + Specify the plaintext password user by user `` on this system. The + plaintext password will be automatically transferred into a secure hashed + password and not saved anywhere in plaintext. + +.. cfgcmd:: set system login user authentication encrypted-password + + + Setup encrypted password for given username. This is useful for + transferring a hashed password from system to system. + +.. cfgcmd:: set system login user disable + + Disable (lock) account. User will not be able to log in. + +.. _ssh_key_based_authentication: + +Key Based Authentication +------------------------ + +It is highly recommended to use SSH key authentication. By default there is +only one user (``vyos``), and you can assign any number of keys to that user. +You can generate a ssh key with the ``ssh-keygen`` command on your local +machine, which will (by default) save it as ``~/.ssh/id_rsa.pub``. + +Every SSH key comes in three parts: + +``ssh-rsa AAAAB3NzaC1yc2EAAAABAA...VBD5lKwEWB username@host.example.com`` + +Only the type (``ssh-rsa``) and the key (``AAAB3N...``) are used. Note that the +key will usually be several hundred characters long, and you will need to copy +and paste it. Some terminal emulators may accidentally split this over several +lines. Be attentive when you paste it that it only pastes as a single line. +The third part is simply an identifier, and is for your own reference. + +.. seealso:: SSH :ref:`ssh_operation` + +.. cfgcmd:: set system login user authentication public-keys + key + + Assign the SSH public key portion `` identified by per-key + `` to the local user ``. + +.. cfgcmd:: set system login user authentication public-keys + type + + Every SSH public key portion referenced by `` requires the + configuration of the `` of public-key used. This type can be any of: + + * ``ecdsa-sha2-nistp256`` + * ``ecdsa-sha2-nistp384`` + * ``ecdsa-sha2-nistp521`` + * ``ssh-dss`` + * ``ssh-ed25519`` + * ``ssh-rsa`` + + .. note:: You can assign multiple keys to the same user by using a unique + identifier per SSH key. + +.. cfgcmd:: set system login user authentication public-keys + options + + Set the options for this public key. See the ssh ``authorized_keys`` man + page for details of what you can specify here. To place a ``"`` + character in the options field, use ``"``, for example + ``from="10.0.0.0/24"`` to restrict where the user + may connect from when using this key. + +MFA/2FA authentication using OTP (one time passwords) +----------------------------------------------------- + +It is possible to enhance authentication security by using the :abbr:`2FA +(Two-factor authentication)`/:abbr:`MFA (Multi-factor authentication)` feature +together with :abbr:`OTP (One-Time-Pad)` on VyOS. :abbr:`2FA (Two-factor +authentication)`/:abbr:`MFA (Multi-factor authentication)` is configured +independently per each user. If an OTP key is configured for a user, 2FA/MFA +is automatically enabled for that particular user. If a user does not have an +OTP key configured, there is no 2FA/MFA check for that user. + +.. cfgcmd:: set system login user authentication otp key + + Enable OTP 2FA for user `username` with default settings, using the BASE32 + encoded 2FA/MFA key specified by ``. + +Optional/default settings +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set system login user authentication otp rate-limit + :defaultvalue: + + Limit logins to `` per every ``rate-time`` seconds. Rate limit + must be between 1 and 10 attempts. + +.. cfgcmd:: set system login user authentication otp rate-time + :defaultvalue: + + Limit logins to ``rate-limit`` attemps per every ``. Rate time must + be between 15 and 600 seconds. + +.. cfgcmd:: set system login user authentication otp window-size + :defaultvalue: + + Set window of concurrently valid codes. + + By default, a new token is generated every 30 seconds by the mobile + application. In order to compensate for possible time-skew between + the client and the server, an extra token before and after the current + time is allowed. This allows for a time skew of up to 30 seconds + between authentication server and client. + + For example, if problems with poor time synchronization are experienced, + the window can be increased from its default size of 3 permitted codes + (one previous code, the current code, the next code) to 17 permitted codes + (the 8 previous codes, the current code, and the 8 next codes). This will + permit for a time skew of up to 4 minutes between client and server. + + The window size must be between 1 and 21. + +OTP-key generation +^^^^^^^^^^^^^^^^^^ + +The following command can be used to generate the OTP key as well +as the CLI commands to configure them: + +.. cfgcmd:: generate system login username otp-key hotp-time + rate-limit <1-10> rate-time <15-600> window-size <1-21> + +An example of key generation: + +.. 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 OTP key for user +^^^^^^^^^^^^^^^^^^^^^^^^ + +To display the configured OTP user key, use the command: + +.. cfgcmd:: sh system login authentication user otp + + +An example: + +.. code-block:: none + + vyos@vyos:~$ sh system login authentication user otptester otp full + # 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' + +Once a user has 2FA/OTP configured against their account, they must login +using their password with the OTP code appended to it. +For example: If the users password is vyosrocks and the OTP code is 817454 +then they would enter their password as vyosrocks817454 + + +RADIUS +====== + +In large deployments it is not reasonable to configure each user individually +on every system. VyOS supports using :abbr:`RADIUS (Remote Authentication +Dial-In User Service)` servers as backend for user authentication. + +Configuration +------------- + +.. cfgcmd:: set system login radius server
key + + Specify the IP `
` of the RADIUS server user with the pre-shared-secret + given in ``. + + Multiple servers can be specified. + +.. cfgcmd:: set system login radius server
port + + Configure the discrete port under which the RADIUS server can be reached. + + This defaults to 1812. + +.. cfgcmd:: set system login radius server
disable + + Temporary disable this RADIUS server. It won't be queried. + +.. cfgcmd:: set system login radius server
timeout + + Setup the `` in seconds when querying the RADIUS server. + +.. cfgcmd:: set system login radius source-address
+ + RADIUS servers could be hardened by only allowing certain IP addresses to + connect. As of this the source address of each RADIUS query can be + configured. + + If unset, incoming connections to the RADIUS server will use the nearest + interface address pointing towards the server - making it error prone on + e.g. OSPF networks when a link fails and a backup route is taken. + +.. cfgcmd:: set system login radius vrf + + Source all connections to the RADIUS servers from given VRF ``. + +.. hint:: If you want to have admin users to authenticate via RADIUS it is + essential to sent the ``Cisco-AV-Pair shell:priv-lvl=15`` attribute. Without + the attribute you will only get regular, non privilegued, system users. + +TACACS+ +======= + +In addition to :abbr:`RADIUS (Remote Authentication Dial-In User Service)`, +:abbr:`TACACS (Terminal Access Controller Access Control System)` can also be +found in large deployments. +VyOS only supports `Authentication` via `TACACS+` servers but does not support `Authorization` or `Accounting` yet + +TACACS is defined in :rfc:`8907`. + +.. _TACACS Configuration: + +Configuration +------------- + +.. cfgcmd:: set system login tacas server
key + + Specify the IP `
` of the TACACS server user with the pre-shared-secret + given in ``. + + Multiple servers can be specified. + +.. cfgcmd:: set system login tacas server
port + + Configure the discrete port under which the TACACS server can be reached. + + This defaults to 49. + +.. cfgcmd:: set system login tacas server
disable + + Temporary disable this TACACS server. It won't be queried. + +.. cfgcmd:: set system login tacas server
timeout + + Setup the `` in seconds when querying the TACACS server. + +.. cfgcmd:: set system login tacas source-address
+ + TACACS servers could be hardened by only allowing certain IP addresses to + connect. As of this the source address of each TACACS query can be + configured. + + If unset, incoming connections to the TACACS server will use the nearest + interface address pointing towards the server - making it error prone on + e.g. OSPF networks when a link fails and a backup route is taken. + +.. cfgcmd:: set system login tacas vrf + + Source all connections to the TACACS servers from given VRF ``. + + +Login Banner +============ + +You are able to set post-login or pre-login banner messages to display certain +information for this system. + +.. cfgcmd:: set system login banner pre-login + + Configure `` which is shown during SSH connect and before a user is + logged in. + +.. cfgcmd:: set system login banner post-login + + Configure `` which is shown after user has logged in to the system. + +.. note:: To create a new line in your login message you need to escape the new + line character by using ``\\n``. + +Limits +====== + +Login limits + +.. cfgcmd:: set system login max-login-session + + Set a limit on the maximum number of concurrent logged-in users on + the system. + + This option must be used with ``timeout`` option. + +.. cfgcmd:: set system login timeout + + Configure session timeout after which the user will be logged out. + +Example +======= + +In the following example, both `User1` and `User2` will be able to SSH into +VyOS as user ``vyos`` using their very own keys. `User1` is restricted to only +be able to connect from a single IP address. In addition if password base login +is wanted for the ``vyos`` user a 2FA/MFA keycode is required in addition to +the password. + +.. 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 + +TACACS Example +-------------- + +We use a vontainer providing the TACACS serve rin this example. + +Load the container image in op-mode. + +.. code-block:: none + + add container image lfkeitel/tacacs_plus:latest + +.. 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 SSH into your system using admin/admin as a default user supplied +from the ``lfkeitel/tacacs_plus:latest`` container. diff --git a/docs/configuration/system/rst-name-server.rst b/docs/configuration/system/rst-name-server.rst new file mode 100644 index 00000000..5d08dbc5 --- /dev/null +++ b/docs/configuration/system/rst-name-server.rst @@ -0,0 +1,74 @@ +.. _system-dns: + +########## +System DNS +########## + +.. warning:: If you are configuring a VRF for management purposes, there is + currently no way to force system DNS traffic via a specific VRF. + +This section describes configuring DNS on the system, namely: + + * DNS name servers + * Domain search order + + +DNS name servers +================ + +.. cfgcmd:: set system name-server
+ + Use this command to specify a DNS server for the system to be used + for DNS lookups. More than one DNS server can be added, configuring + one at a time. Both IPv4 and IPv6 addresses are supported. + + + +Example +------- + +In this example, some *OpenNIC* servers are used, two IPv4 addresses +and two IPv6 addresses: + +.. 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 + + 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 new file mode 100644 index 00000000..d039315c --- /dev/null +++ b/docs/configuration/system/rst-option.rst @@ -0,0 +1,169 @@ +.. _system_option: + +###### +Option +###### + +This chapter describe the possibilities of advanced system behavior. + +******* +General +******* + +.. cfgcmd:: set system option ctrl-alt-delete + + Action which will be run once the ctrl-alt-del keystroke is received. + +.. cfgcmd:: set system option reboot-on-panic + + Automatically reboot system on kernel panic after 60 seconds. + +.. cfgcmd:: set system option startup-beep + + Play an audible beep to the system speaker when system is ready. + +.. cfgcmd:: set system option root-partition-auto-resize + + Enables the root partition auto-extension and resizes to the maximum + available space on system boot. + +Kernel +====== + +.. cfgcmd:: set system option kernel disable-mitigations + + Disable all optional CPU mitigations. This improves system performance, + but it may also expose users to several CPU vulnerabilities. + + This will add the following option to the Kernel commandline: + + * ``mitigations=off`` + + .. note:: Setting will only become active with the next reboot! + +.. cfgcmd:: set system option kernel disable-power-saving + + This will add the following two options to the Kernel commandline: + + * ``intel_idle.max_cstate=0`` Disable intel_idle and fall back on acpi_idle + * ``processor.max_cstate=1`` Limit processor to maximum C-state 1 + + .. note:: Setting will only become active with the next reboot! + +.. cfgcmd:: set system option kernel amd-pstate-driver + + Enables and configures p-state driver for modern AMD Ryzen and Epyc CPUs. + + The available modes are: + + * ``active`` This is the low-level firmware control mode based on the profile + set and the system governor has no effect. + * ``passive`` The driver allows the system governor to manage CPU frequency + while providing available performance states. + * ``guided`` The driver allows to set desired performance levels and the firmware + selects a performance level in this range and fitting to the current workload. + + This will add the following two options to the Kernel commandline: + + * ``initcall_blacklist=acpi_cpufreq_init`` Disable default ACPI CPU frequency scale + * ``amd_pstate={mode}`` Sets the p-state mode + + .. note:: Setting will only become active with the next reboot! + + .. seealso:: 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
+ + Several commands utilize cURL to initiate transfers. Configure the local + source IPv4/IPv6 address used for all cURL operations. + +.. cfgcmd:: set system option http-client source-interface + + Several commands utilize curl to initiate transfers. Configure the local + source interface used for all CURL operations. + +.. note:: `source-address` and `source-interface` can not be used at the same + time. + +********** +SSH client +********** + +.. cfgcmd:: set system option ssh-client source-address
+ + Use the specified address on the local machine as the source address of the + connection. Only useful on systems with more than one address. + +.. cfgcmd:: set system option ssh-client source-interface + + Use the address of the specified interface on the local machine as the + source address of the connection. + +*************** +Keyboard Layout +*************** + +When starting a VyOS live system (the installation CD) the configured keyboard +layout defaults to US. As this might not suite everyones use case you can adjust +the used keyboard layout on the system console. + +.. cfgcmd:: set system option keyboard-layout + + Change system keyboard layout to given language. + + Defaults to ``us``. + + .. note:: Changing the keymap only has an effect on the system console, using + SSH or Serial remote access to the device is not affected as the keyboard + layout here corresponds to your access system. + +.. _system_options_performance: + +*********** +Performance +*********** + +As more and more routers run on Hypervisors, expecially with a :abbr:`NOS +(Network Operating System)` as VyOS, it makes fewer and fewer sense to use +static resource bindings like ``smp-affinity`` as present in VyOS 1.2 and +earlier to pin certain interrupt handlers to specific CPUs. + +We now utilize `tuned` for dynamic resource balancing based on profiles. + +.. 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 new file mode 100644 index 00000000..8e0339a7 --- /dev/null +++ b/docs/configuration/system/rst-proxy.rst @@ -0,0 +1,28 @@ +.. _system_proxy: + +############ +System Proxy +############ + +Some IT environments require the use of a proxy to connect to the Internet. +Without this configuration VyOS updates could not be installed directly by +using the :opcmd:`add system image` command (:ref:`update_vyos`). + +.. cfgcmd:: set system proxy url + + Set proxy for all connections initiated by VyOS, including HTTP, HTTPS, and + FTP (anonymous ftp). + +.. cfgcmd:: set system proxy port + + Configure proxy port if it does not listen to the default port 80. + +.. cfgcmd:: set system proxy username + + Some proxys require/support the "basic" HTTP authentication scheme as per + :rfc:`7617`, thus a username can be configured. + +.. cfgcmd:: set system proxy password + + Some proxys require/support the "basic" HTTP authentication scheme as per + :rfc:`7617`, thus a password can be configured. diff --git a/docs/configuration/system/rst-sflow.rst b/docs/configuration/system/rst-sflow.rst new file mode 100644 index 00000000..c2cf5a80 --- /dev/null +++ b/docs/configuration/system/rst-sflow.rst @@ -0,0 +1,61 @@ +##### +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
+ + Configure sFlow agent IPv4 or IPv6 address + + +.. cfgcmd:: set system sflow agent-interface + + Configure agent IP address associated with this interface. + + +.. cfgcmd:: set system sflow drop-monitor-limit + + Dropped packets reported on DROPMON Netlink channel by Linux kernel are exported via the standard sFlow v5 extension for reporting dropped packets + +.. cfgcmd:: set system sflow interface + + Configure and enable collection of flow information for the interface identified by . + + You can configure multiple interfaces which whould participate in sflow accounting. + + +.. cfgcmd:: set system sflow polling + + Configure schedule counter-polling in seconds (default: 30) + +.. cfgcmd:: set system sflow sampling-rate + + Use this command to configure the sampling rate for sFlow accounting (default: 1000) + +.. cfgcmd:: set system sflow server
port + + Configure address of sFlow collector. sFlow server at
can be both listening on an IPv4 or IPv6 address. + + +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 new file mode 100644 index 00000000..06e15031 --- /dev/null +++ b/docs/configuration/system/rst-sysctl.rst @@ -0,0 +1,12 @@ +.. _sysctl: + +###### +Sysctl +###### + +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 value diff --git a/docs/configuration/system/rst-syslog.rst b/docs/configuration/system/rst-syslog.rst new file mode 100644 index 00000000..95c3bc87 --- /dev/null +++ b/docs/configuration/system/rst-syslog.rst @@ -0,0 +1,389 @@ +.. _syslog: + +###### +Syslog +###### + +Per default VyOSs has minimal syslog logging enabled which is stored and +rotated locally. Errors will be always logged to a local file, which includes +`local7` error messages, emergency messages will be sent to the console, too. + +To configure syslog, you need to switch into configuration mode. + +Logging +======= + +Syslog supports logging to multiple targets, those targets could be a plain +file on your VyOS installation itself, a serial console or a remote syslog +server which is reached via :abbr:`IP (Internet Protocol)` UDP/TCP. + +Console +------- + +.. cfgcmd:: set system syslog console facility level + + Log syslog messages to ``/dev/console``, for an explanation on + :ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords + see tables below. + +.. _custom-file: + +Custom File +----------- + +.. cfgcmd:: set system syslog file facility level + + Log syslog messages to file specified via ``, for an explanation on + :ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords + see tables below. + +.. cfgcmd:: set system syslog file archive size + + Syslog will write `` kilobytes into the file specified by ``. + After this limit has been reached, the custom file is "rotated" by logrotate + and a new custom file is created. + +.. cfgcmd:: set system syslog file archive file + + Syslog uses logrotate to rotate logiles after a number of gives bytes. + We keep as many as `` rotated file before they are deleted on the + system. + + +Remote Host +----------- + +Logging to a remote host leaves the local logging configuration intact, it +can be configured in parallel to a custom file or console logging. You can log +to multiple hosts at the same time, using either TCP or UDP. The default is +sending the messages via port 514/UDP. + + +.. cfgcmd:: set system syslog host
facility level + + Log syslog messages to remote host specified by `
`. The address + can be specified by either FQDN or IP address. For an explanation on + :ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` + keywords see tables below. + + +.. cfgcmd:: set system syslog host
facility protocol + + + Configure protocol used for communication to remote syslog host. This can be + either UDP or TCP. + + +.. cfgcmd:: set system syslog vrf + + Specify name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance. + +: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
protocol tcp + + +.. note:: :abbr:`TLS (Transport Layer Security)`-encrypted remote logging is + **not supported** over **UDP**. + +.. cfgcmd:: set system syslog remote
tls + + Enable TLS-encrypted remote logging. + +.. cfgcmd:: set system syslog remote
tls ca-certificate + + **Configure the** :abbr:`CA (Certificate Authority)` **certificate.** + + The syslog client uses the :abbr:`CA (Certificate Authority)` certificate to + verify the identity of the remote syslog server. + + The :abbr:`CA (Certificate Authority)` certificate is required for **all** + authentication modes except ``anon``. + +.. cfgcmd:: set system syslog remote
tls certificate + + **Configure the client certificate.** + + The remote syslog server uses the client certificate to verify the identity + of the syslog client. + + The client certificate is required if the remote syslog server enforces + client certificate verification. + +.. cfgcmd:: set system syslog remote
tls auth-mode + + **Configure the authentication mode.** + + The authentication mode defines how the syslog client verifies the syslog + server's identity. + + The following authentication modes are available: + + * ``anon`` **(default)**: Allows encrypted connections without verifying the syslog + server's identity. This mode is **not recommended**, as it is vulnerable to + :abbr:`MITM (Man-in-the-Middle)` attacks. + * ``fingerprint``: Verifies the server’s certificate fingerprint against the + value preconfigured with: + + .. code-block:: none + + set system syslog remote
tls permitted-peer + + * ``certvalid``: Verifies the server certificate is signed by a trusted + :abbr:`CA (Certificate Authority)`, skipping :abbr:`CN (Common Name)` check. + * ``name``: Verifies that: + + * The server’s certificate is signed by a trusted :abbr:`CA (Certificate + Authority)`. + * The :abbr:`CN (Common Name)` in the certificate matches the value + preconfigured with: + + .. code-block:: none + + set system syslog remote
tls permitted-peer + + This is a **recommended** secure mode for production environments. + +.. cfgcmd:: set system syslog remote
tls permitted-peer + + **Configure the peer certificate identifiers.** + + The certificate identifier format depends on the authentication mode: + + * ``fingerprint``: Enter the expected certificate fingerprints (SHA-1 or + SHA-256). + * ``name``: Enter the expected certificate :abbr:`CNs (Common Names)`. + + For ``anon`` and ``certvalid`` authentication modes, certificate identifiers + are not required. + +Examples: +^^^^^^^^^ + +.. code-block:: none + + # Example of 'anon' authentication mode + set system syslog host 10.10.2.3 facility all level debug + set system syslog host 10.10.2.3 port 6514 + set system syslog host 10.10.2.3 protocol tcp + set system syslog host 10.10.2.3 tls auth-mode anon + # or just use 'set system syslog host 10.10.2.3 tls' + + # Example of 'certvalid' authentication mode + set system syslog host elk.example.com facility all level debug + set system syslog host elk.example.com port 6514 + set system syslog host elk.example.com protocol tcp + set system syslog host elk.example.com tls ca-certificate my-ca + set system syslog host elk.example.com tls auth-mode certvalid + + # Example of 'fingerprint' authentication mode + set system syslog host syslog.example.com facility all level debug + set system syslog host syslog.example.com port 6514 + set system syslog host syslog.example.com protocol tcp + set system syslog host syslog.example.com tls ca-certificate my-ca + set system syslog host syslog.example.com tls auth-mode fingerprint + set system syslog host syslog.example.com tls permitted-peer 'SHA1:10:C4:26:...' + + # Example of 'name' authentication mode + set system syslog host graylog.example.com facility all level debug + set system syslog host graylog.example.com port 6514 + set system syslog host graylog.example.com protocol tcp + set system syslog host graylog.example.com tls ca-certificate my-ca + set system syslog host graylog.example.com tls certificate syslog-client + set system syslog host graylog.example.com tls auth-mode name + set system syslog host graylog.example.com tls permitted-peer 'graylog.example.com' + +Security Notes +^^^^^^^^^^^^^^ + +* Always prefer ``auth-mode name`` for secure deployments, as it ensures + both CA trust and server hostname validation. +* ``anon`` mode should only be used for testing, because it does not + authenticate the server. +* Ensure private keys are stored and managed exclusively in the + :doc:`PKI system `. + +Local User Account +------------------ + +.. cfgcmd:: set system syslog user facility level + + If logging to a local user account is configured, all defined log messages + are display on the console if the local user is logged in, if the user is not + logged in, no messages are being displayed. For an explanation on + :ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords + see tables below. + +.. _syslog_facilities: + +Facilities +========== + +List of facilities used by syslog. Most facilities names are self explanatory. +Facilities local0 - local7 common usage is f.e. as network logs facilities for +nodes and network equipment. Generally it depends on the situation how to +classify logs and put them to facilities. See facilities more as a tool rather +than a directive to follow. + +Facilities can be adjusted to meet the needs of the user: + ++----------+----------+----------------------------------------------------+ +| Facility | Keyword | Description | +| Code | | | ++==========+==========+====================================================+ +| | all | All facilities | ++----------+----------+----------------------------------------------------+ +| 0 | kern | Kernel messages | ++----------+----------+----------------------------------------------------+ +| 1 | user | User-level messages | ++----------+----------+----------------------------------------------------+ +| 2 | mail | Mail system | ++----------+----------+----------------------------------------------------+ +| 3 | daemon | System daemons | ++----------+----------+----------------------------------------------------+ +| 4 | auth | Security/authentication messages | ++----------+----------+----------------------------------------------------+ +| 5 | syslog | Messages generated internally by syslogd | ++----------+----------+----------------------------------------------------+ +| 6 | lpr | Line printer subsystem | ++----------+----------+----------------------------------------------------+ +| 7 | news | Network news subsystem | ++----------+----------+----------------------------------------------------+ +| 8 | uucp | UUCP subsystem | ++----------+----------+----------------------------------------------------+ +| 9 | cron | Clock daemon | ++----------+----------+----------------------------------------------------+ +| 10 | security | Security/authentication messages | ++----------+----------+----------------------------------------------------+ +| 11 | ftp | FTP daemon | ++----------+----------+----------------------------------------------------+ +| 12 | ntp | NTP subsystem | ++----------+----------+----------------------------------------------------+ +| 13 | logaudit | Log audit | ++----------+----------+----------------------------------------------------+ +| 14 | logalert | Log alert | ++----------+----------+----------------------------------------------------+ +| 15 | clock | clock daemon (note 2) | ++----------+----------+----------------------------------------------------+ +| 16 | local0 | local use 0 (local0) | ++----------+----------+----------------------------------------------------+ +| 17 | local1 | local use 1 (local1) | ++----------+----------+----------------------------------------------------+ +| 18 | local2 | local use 2 (local2) | ++----------+----------+----------------------------------------------------+ +| 19 | local3 | local use 3 (local3) | ++----------+----------+----------------------------------------------------+ +| 20 | local4 | local use 4 (local4) | ++----------+----------+----------------------------------------------------+ +| 21 | local5 | local use 5 (local5) | ++----------+----------+----------------------------------------------------+ +| 22 | local6 | use 6 (local6) | ++----------+----------+----------------------------------------------------+ +| 23 | local7 | local use 7 (local7) | ++----------+----------+----------------------------------------------------+ + +.. _syslog_severity_level: + +Severity Level +============== + ++-------+---------------+---------+-------------------------------------------+ +| Value | Severity | Keyword | Description | ++=======+===============+=========+===========================================+ +| | | all | Log everything | ++-------+---------------+---------+-------------------------------------------+ +| 0 | Emergency | emerg | System is unusable - a panic condition | ++-------+---------------+---------+-------------------------------------------+ +| 1 | Alert | alert | Action must be taken immediately - A | +| | | | condition that should be corrected | +| | | | immediately, such as a corrupted system | +| | | | database. | ++-------+---------------+---------+-------------------------------------------+ +| 2 | Critical | crit | Critical conditions - e.g. hard drive | +| | | | errors. | ++-------+---------------+---------+-------------------------------------------+ +| 3 | Error | err | Error conditions | ++-------+---------------+---------+-------------------------------------------+ +| 4 | Warning | warning | Warning conditions | ++-------+---------------+---------+-------------------------------------------+ +| 5 | Notice | notice | Normal but significant conditions - | +| | | | conditions that are not error conditions, | +| | | | but that may require special handling. | ++-------+---------------+---------+-------------------------------------------+ +| 6 | Informational | info | Informational messages | ++-------+---------------+---------+-------------------------------------------+ +| 7 | Debug | debug | Debug-level messages - Messages that | +| | | | contain information normally of use only | +| | | | when debugging a program. | ++-------+---------------+---------+-------------------------------------------+ + + +Display Logs +============ + +.. opcmd:: show log [all | authorization | cluster | conntrack-sync | ...] + + Display log files of given category on the console. Use tab completion to get + a list of available categories. Thos categories could be: all, authorization, + cluster, conntrack-sync, dhcp, directory, dns, file, firewall, https, image + lldp, nat, openvpn, snmp, tail, vpn, vrrp + +If no option is specified, this defaults to `all`. + +.. opcmd:: show log image + [all | authorization | directory | file | tail ] + + Log messages from a specified image can be displayed on the console. Details + of allowed parameters: + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - all + - Display contents of all master log files of the specified image + * - authorization + - Display all authorization attempts of the specified image + * - directory + - Display list of all user-defined log files of the specified image + * - file + - Display contents of a specified user-defined log file of the specified + image + * - tail + - Display last lines of the system log of the specified image + * - + - Number of lines to be displayed, default 10 + +When no options/parameters are used, the contents of the main syslog file are +displayed. + +.. hint:: Use ``show log | strip-private`` if you want to hide private data + when sharing your logs. + +Delete Logs +=========== + +.. opcmd:: delete log file + +Deletes the specified user-defined file in the /var/log/user directory + +Note that deleting the log file does not stop the system from logging events. +If you use this command while the system is logging events, old log events +will be deleted, but events after the delete operation will be recorded in +the new file. To delete the file altogether, first delete logging to the +file using system syslog :ref:`custom-file` command, and then delete the file. diff --git a/docs/configuration/system/rst-task-scheduler.rst b/docs/configuration/system/rst-task-scheduler.rst new file mode 100644 index 00000000..382da39f --- /dev/null +++ b/docs/configuration/system/rst-task-scheduler.rst @@ -0,0 +1,40 @@ +.. _task-scheduler: + +############## +Task Scheduler +############## + +The task scheduler allows you to execute tasks on a given schedule. It makes +use of UNIX cron_. + +.. note:: All scripts excecuted this way are executed as root user - this may + be dangerous. Together with :ref:`command-scripting` this can be used for + automating (re-)configuration. + +.. cfgcmd:: set system task-scheduler task interval + + Specify the time interval when `` should be executed. The interval + is specified as number with one of the following suffixes: + + * ``none`` - Execution interval in minutes + * ``m`` - Execution interval in minutes + * ``h`` - Execution interval in hours + * ``d`` - Execution interval in days + + .. note:: If suffix is omitted, minutes are implied. + +.. cfgcmd:: set system task-scheduler task crontab-spec + + Set execution time in common cron_ time format. A cron `` of + ``30 */6 * * *`` would execute the `` at minute 30 past every 6th hour. + +.. cfgcmd:: set system task-scheduler task executable path + + Specify absolute `` to script which will be run when `` is + executed. + +.. cfgcmd:: set system task-scheduler task executable arguments + + Arguments which will be passed to the executable. + +.. _cron: https://en.wikipedia.org/wiki/Cron diff --git a/docs/configuration/system/rst-time-zone.rst b/docs/configuration/system/rst-time-zone.rst new file mode 100644 index 00000000..025c4376 --- /dev/null +++ b/docs/configuration/system/rst-time-zone.rst @@ -0,0 +1,18 @@ +.. _timezone: + +######### +Time Zone +######### + +Time Zone setting is very important as e.g all your logfile entries will be +based on the configured zone. Without proper time zone configuration it will +be very difficult to compare logfiles from different systems. + +.. cfgcmd:: set system time-zone + + Specify the systems `` as the Region/Location that best defines + your location. For example, specifying US/Pacific sets the time zone to US + Pacific time. + + Command completion can be used to list available time zones. The adjustment + for daylight time will take place automatically based on the time of year. \ No newline at end of file diff --git a/docs/configuration/system/rst-updates.rst b/docs/configuration/system/rst-updates.rst new file mode 100644 index 00000000..a55bfa9a --- /dev/null +++ b/docs/configuration/system/rst-updates.rst @@ -0,0 +1,37 @@ +####### +Updates +####### + +VyOS supports online checking for updates + +Configuration +============= + +.. cfgcmd:: set system update-check auto-check + + Configure auto-checking for new images + + +.. cfgcmd:: set system update-check url + + Configure a URL that contains information about images. + + +Example +======= + +.. 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:~$ diff --git a/docs/configuration/system/sflow.md b/docs/configuration/system/sflow.md new file mode 100644 index 00000000..c63699db --- /dev/null +++ b/docs/configuration/system/sflow.md @@ -0,0 +1,71 @@ +# sFlow + +VyOS supports sFlow accounting for both IPv4 and IPv6 traffic. The system acts as a flow exporter, and you are free to use it with any compatible collector. + +sFlow is a technology that enables monitoring of network traffic by sending sampled packets to a collector device. + +The sFlow accounting based on hsflowd + +## Configuration + +```{eval-rst} +.. cfgcmd:: set system sflow agent-address
+ + Configure sFlow agent IPv4 or IPv6 address + +``` + +```{eval-rst} +.. cfgcmd:: set system sflow agent-interface + + Configure agent IP address associated with this interface. + +``` + +```{eval-rst} +.. cfgcmd:: set system sflow drop-monitor-limit + + Dropped packets reported on DROPMON Netlink channel by Linux kernel are exported via the standard sFlow v5 extension for reporting dropped packets +``` + +```{eval-rst} +.. cfgcmd:: set system sflow interface + + Configure and enable collection of flow information for the interface identified by . + + You can configure multiple interfaces which whould participate in sflow accounting. + +``` + +```{eval-rst} +.. cfgcmd:: set system sflow polling + + Configure schedule counter-polling in seconds (default: 30) +``` + +```{eval-rst} +.. cfgcmd:: set system sflow sampling-rate + + Use this command to configure the sampling rate for sFlow accounting (default: 1000) +``` + +```{eval-rst} +.. cfgcmd:: set system sflow server
port + + Configure address of sFlow collector. sFlow server at
can be both listening on an IPv4 or IPv6 address. + +``` + +## Example + +```none +set system sflow agent-address '192.0.2.14' +set system sflow agent-interface 'eth0' +set system sflow drop-monitor-limit '50' +set system sflow interface 'eth0' +set system sflow interface 'eth1' +set system sflow polling '30' +set system sflow sampling-rate '1000' +set system sflow server 192.0.2.1 port '6343' +set system sflow server 203.0.113.23 port '6343' +``` diff --git a/docs/configuration/system/sflow.rst b/docs/configuration/system/sflow.rst deleted file mode 100644 index c2cf5a80..00000000 --- a/docs/configuration/system/sflow.rst +++ /dev/null @@ -1,61 +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
- - Configure sFlow agent IPv4 or IPv6 address - - -.. cfgcmd:: set system sflow agent-interface - - Configure agent IP address associated with this interface. - - -.. cfgcmd:: set system sflow drop-monitor-limit - - Dropped packets reported on DROPMON Netlink channel by Linux kernel are exported via the standard sFlow v5 extension for reporting dropped packets - -.. cfgcmd:: set system sflow interface - - Configure and enable collection of flow information for the interface identified by . - - You can configure multiple interfaces which whould participate in sflow accounting. - - -.. cfgcmd:: set system sflow polling - - Configure schedule counter-polling in seconds (default: 30) - -.. cfgcmd:: set system sflow sampling-rate - - Use this command to configure the sampling rate for sFlow accounting (default: 1000) - -.. cfgcmd:: set system sflow server
port - - Configure address of sFlow collector. sFlow server at
can be both listening on an IPv4 or IPv6 address. - - -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/sysctl.md b/docs/configuration/system/sysctl.md new file mode 100644 index 00000000..b815861b --- /dev/null +++ b/docs/configuration/system/sysctl.md @@ -0,0 +1,12 @@ +(sysctl)= + +# Sysctl + +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/. + +```{eval-rst} +.. cfgcmd:: set system sysctl parameter value +``` diff --git a/docs/configuration/system/sysctl.rst b/docs/configuration/system/sysctl.rst deleted file mode 100644 index 06e15031..00000000 --- a/docs/configuration/system/sysctl.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _sysctl: - -###### -Sysctl -###### - -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 value diff --git a/docs/configuration/system/syslog.md b/docs/configuration/system/syslog.md new file mode 100644 index 00000000..b4335c22 --- /dev/null +++ b/docs/configuration/system/syslog.md @@ -0,0 +1,365 @@ +(syslog)= + +# Syslog + +Per default VyOSs has minimal syslog logging enabled which is stored and +rotated locally. Errors will be always logged to a local file, which includes +`local7` error messages, emergency messages will be sent to the console, too. + +To configure syslog, you need to switch into configuration mode. + +## Logging + +Syslog supports logging to multiple targets, those targets could be a plain +file on your VyOS installation itself, a serial console or a remote syslog +server which is reached via {abbr}`IP (Internet Protocol)` UDP/TCP. + +### Console + +```{eval-rst} +.. cfgcmd:: set system syslog console facility level + + Log syslog messages to ``/dev/console``, for an explanation on + {ref}`syslog_facilities` keywords and {ref}`syslog_severity_level` keywords + see tables below. +``` + +(custom-file)= + +### Custom File + +```{eval-rst} +.. cfgcmd:: set system syslog file facility level + + Log syslog messages to file specified via ``, for an explanation on + {ref}`syslog_facilities` keywords and {ref}`syslog_severity_level` keywords + see tables below. +``` + +```{eval-rst} +.. cfgcmd:: set system syslog file archive size + + Syslog will write `` kilobytes into the file specified by ``. + After this limit has been reached, the custom file is "rotated" by logrotate + and a new custom file is created. +``` + +```{eval-rst} +.. cfgcmd:: set system syslog file archive file + + Syslog uses logrotate to rotate logiles after a number of gives bytes. + We keep as many as `` rotated file before they are deleted on the + system. + +``` + +### Remote Host + +Logging to a remote host leaves the local logging configuration intact, it +can be configured in parallel to a custom file or console logging. You can log +to multiple hosts at the same time, using either TCP or UDP. The default is +sending the messages via port 514/UDP. + +```{eval-rst} +.. cfgcmd:: set system syslog host
facility level + + Log syslog messages to remote host specified by `
`. The address + can be specified by either FQDN or IP address. For an explanation on + {ref}`syslog_facilities` keywords and {ref}`syslog_severity_level` + keywords see tables below. + +``` + +```{eval-rst} +.. cfgcmd:: set system syslog host
facility protocol + + + Configure protocol used for communication to remote syslog host. This can be + either UDP or TCP. + +``` + +```{eval-rst} +.. cfgcmd:: set system syslog vrf + + Specify name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance. +``` + +#### {abbr}`TLS (Transport Layer Security)`-encrypted remote logging + +VyOS supports {abbr}`TLS (Transport Layer Security)`-encrypted remote logging +over TCP to ensure secure transmission of syslog data to remote syslog servers. + +**Prerequisites**: Before configuring {abbr}`TLS (Transport Layer +Security)`-encrypted remote logging, ensure you have: + +- A valid remote syslog server address. + +- Valid {abbr}`CA (Certificate Authority)` and client certificates uploaded + to the local {abbr}`PKI (Public Key Infrastructure)` storage. + +- The **remote syslog transport protocol** is set to **TCP**: + + ```none + set system syslog remote
protocol tcp + ``` + +:::{note} +{abbr}`TLS (Transport Layer Security)`-encrypted remote logging is +**not supported** over **UDP**. +::: + +```{eval-rst} +.. cfgcmd:: set system syslog remote
tls + + Enable TLS-encrypted remote logging. +``` + +```{eval-rst} +.. cfgcmd:: set system syslog remote
tls ca-certificate + + **Configure the** {abbr}`CA (Certificate Authority)` **certificate.** + + The syslog client uses the {abbr}`CA (Certificate Authority)` certificate to + verify the identity of the remote syslog server. + + The {abbr}`CA (Certificate Authority)` certificate is required for **all** + authentication modes except ``anon``. +``` + +```{eval-rst} +.. cfgcmd:: set system syslog remote
tls certificate + + **Configure the client certificate.** + + The remote syslog server uses the client certificate to verify the identity + of the syslog client. + + The client certificate is required if the remote syslog server enforces + client certificate verification. +``` + +```{eval-rst} +.. cfgcmd:: set system syslog remote
tls auth-mode + + **Configure the authentication mode.** + + The authentication mode defines how the syslog client verifies the syslog + server's identity. + + The following authentication modes are available: + + * ``anon`` **(default)**: Allows encrypted connections without verifying the syslog + server's identity. This mode is **not recommended**, as it is vulnerable to + {abbr}`MITM (Man-in-the-Middle)` attacks. + * ``fingerprint``: Verifies the server’s certificate fingerprint against the + value preconfigured with: + + .. code-block:: none + + set system syslog remote
tls permitted-peer + + * ``certvalid``: Verifies the server certificate is signed by a trusted + {abbr}`CA (Certificate Authority)`, skipping {abbr}`CN (Common Name)` check. + * ``name``: Verifies that: + + * The server’s certificate is signed by a trusted {abbr}`CA (Certificate + Authority)`. + * The {abbr}`CN (Common Name)` in the certificate matches the value + preconfigured with: + + .. code-block:: none + + set system syslog remote
tls permitted-peer + + This is a **recommended** secure mode for production environments. +``` + +```{eval-rst} +.. cfgcmd:: set system syslog remote
tls permitted-peer + + **Configure the peer certificate identifiers.** + + The certificate identifier format depends on the authentication mode: + + * ``fingerprint``: Enter the expected certificate fingerprints (SHA-1 or + SHA-256). + * ``name``: Enter the expected certificate {abbr}`CNs (Common Names)`. + + For ``anon`` and ``certvalid`` authentication modes, certificate identifiers + are not required. +``` + +#### Examples: + +```none +# Example of 'anon' authentication mode +set system syslog host 10.10.2.3 facility all level debug +set system syslog host 10.10.2.3 port 6514 +set system syslog host 10.10.2.3 protocol tcp +set system syslog host 10.10.2.3 tls auth-mode anon +# or just use 'set system syslog host 10.10.2.3 tls' + +# Example of 'certvalid' authentication mode +set system syslog host elk.example.com facility all level debug +set system syslog host elk.example.com port 6514 +set system syslog host elk.example.com protocol tcp +set system syslog host elk.example.com tls ca-certificate my-ca +set system syslog host elk.example.com tls auth-mode certvalid + +# Example of 'fingerprint' authentication mode +set system syslog host syslog.example.com facility all level debug +set system syslog host syslog.example.com port 6514 +set system syslog host syslog.example.com protocol tcp +set system syslog host syslog.example.com tls ca-certificate my-ca +set system syslog host syslog.example.com tls auth-mode fingerprint +set system syslog host syslog.example.com tls permitted-peer 'SHA1:10:C4:26:...' + +# Example of 'name' authentication mode +set system syslog host graylog.example.com facility all level debug +set system syslog host graylog.example.com port 6514 +set system syslog host graylog.example.com protocol tcp +set system syslog host graylog.example.com tls ca-certificate my-ca +set system syslog host graylog.example.com tls certificate syslog-client +set system syslog host graylog.example.com tls auth-mode name +set system syslog host graylog.example.com tls permitted-peer 'graylog.example.com' +``` + +#### Security Notes + +- Always prefer `auth-mode name` for secure deployments, as it ensures + both CA trust and server hostname validation. +- `anon` mode should only be used for testing, because it does not + authenticate the server. +- Ensure private keys are stored and managed exclusively in the + {doc}`PKI system `. + +### Local User Account + +```{eval-rst} +.. cfgcmd:: set system syslog user facility level + + If logging to a local user account is configured, all defined log messages + are display on the console if the local user is logged in, if the user is not + logged in, no messages are being displayed. For an explanation on + {ref}`syslog_facilities` keywords and {ref}`syslog_severity_level` keywords + see tables below. +``` + +(syslog_facilities)= + +## Facilities + +List of facilities used by syslog. Most facilities names are self explanatory. +Facilities local0 - local7 common usage is f.e. as network logs facilities for +nodes and network equipment. Generally it depends on the situation how to +classify logs and put them to facilities. See facilities more as a tool rather +than a directive to follow. + +Facilities can be adjusted to meet the needs of the user: + +| Facility Code | Keyword | Description | +| ------------- | -------- | ---------------------------------------- | +| | all | All facilities | +| 0 | kern | Kernel messages | +| 1 | user | User-level messages | +| 2 | mail | Mail system | +| 3 | daemon | System daemons | +| 4 | auth | Security/authentication messages | +| 5 | syslog | Messages generated internally by syslogd | +| 6 | lpr | Line printer subsystem | +| 7 | news | Network news subsystem | +| 8 | uucp | UUCP subsystem | +| 9 | cron | Clock daemon | +| 10 | security | Security/authentication messages | +| 11 | ftp | FTP daemon | +| 12 | ntp | NTP subsystem | +| 13 | logaudit | Log audit | +| 14 | logalert | Log alert | +| 15 | clock | clock daemon (note 2) | +| 16 | local0 | local use 0 (local0) | +| 17 | local1 | local use 1 (local1) | +| 18 | local2 | local use 2 (local2) | +| 19 | local3 | local use 3 (local3) | +| 20 | local4 | local use 4 (local4) | +| 21 | local5 | local use 5 (local5) | +| 22 | local6 | use 6 (local6) | +| 23 | local7 | local use 7 (local7) | + +(syslog_severity_level)= + +## Severity Level + +| Value | Severity | Keyword | Description | +| ----- | ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- | +| | | all | Log everything | +| 0 | Emergency | emerg | System is unusable - a panic condition | +| 1 | Alert | alert | Action must be taken immediately - A condition that should be corrected immediately, such as a corrupted system database. | +| 2 | Critical | crit | Critical conditions - e.g. hard drive errors. | +| 3 | Error | err | Error conditions | +| 4 | Warning | warning | Warning conditions | +| 5 | Notice | notice | Normal but significant conditions - conditions that are not error conditions, but that may require special handling. | +| 6 | Informational | info | Informational messages | +| 7 | Debug | debug | Debug-level messages - Messages that contain information normally of use only when debugging a program. | + +## Display Logs + +```{eval-rst} +.. opcmd:: show log [all | authorization | cluster | conntrack-sync | ...] + + Display log files of given category on the console. Use tab completion to get + a list of available categories. Thos categories could be: all, authorization, + cluster, conntrack-sync, dhcp, directory, dns, file, firewall, https, image + lldp, nat, openvpn, snmp, tail, vpn, vrrp +``` + +If no option is specified, this defaults to `all`. + +```{eval-rst} +.. opcmd:: show log image + [all | authorization | directory | file | tail ] + + Log messages from a specified image can be displayed on the console. Details + of allowed parameters: + + .. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - all + - Display contents of all master log files of the specified image + * - authorization + - Display all authorization attempts of the specified image + * - directory + - Display list of all user-defined log files of the specified image + * - file + - Display contents of a specified user-defined log file of the specified + image + * - tail + - Display last lines of the system log of the specified image + * - + - Number of lines to be displayed, default 10 +``` + +When no options/parameters are used, the contents of the main syslog file are +displayed. + +:::{hint} +Use `show log | strip-private` if you want to hide private data +when sharing your logs. +::: + +## Delete Logs + +```{eval-rst} +.. opcmd:: delete log file +``` + +Deletes the specified user-defined file \ in the /var/log/user directory + +Note that deleting the log file does not stop the system from logging events. +If you use this command while the system is logging events, old log events +will be deleted, but events after the delete operation will be recorded in +the new file. To delete the file altogether, first delete logging to the +file using system syslog {ref}`custom-file` command, and then delete the file. diff --git a/docs/configuration/system/syslog.rst b/docs/configuration/system/syslog.rst deleted file mode 100644 index 95c3bc87..00000000 --- a/docs/configuration/system/syslog.rst +++ /dev/null @@ -1,389 +0,0 @@ -.. _syslog: - -###### -Syslog -###### - -Per default VyOSs has minimal syslog logging enabled which is stored and -rotated locally. Errors will be always logged to a local file, which includes -`local7` error messages, emergency messages will be sent to the console, too. - -To configure syslog, you need to switch into configuration mode. - -Logging -======= - -Syslog supports logging to multiple targets, those targets could be a plain -file on your VyOS installation itself, a serial console or a remote syslog -server which is reached via :abbr:`IP (Internet Protocol)` UDP/TCP. - -Console -------- - -.. cfgcmd:: set system syslog console facility level - - Log syslog messages to ``/dev/console``, for an explanation on - :ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords - see tables below. - -.. _custom-file: - -Custom File ------------ - -.. cfgcmd:: set system syslog file facility level - - Log syslog messages to file specified via ``, for an explanation on - :ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords - see tables below. - -.. cfgcmd:: set system syslog file archive size - - Syslog will write `` kilobytes into the file specified by ``. - After this limit has been reached, the custom file is "rotated" by logrotate - and a new custom file is created. - -.. cfgcmd:: set system syslog file archive file - - Syslog uses logrotate to rotate logiles after a number of gives bytes. - We keep as many as `` rotated file before they are deleted on the - system. - - -Remote Host ------------ - -Logging to a remote host leaves the local logging configuration intact, it -can be configured in parallel to a custom file or console logging. You can log -to multiple hosts at the same time, using either TCP or UDP. The default is -sending the messages via port 514/UDP. - - -.. cfgcmd:: set system syslog host
facility level - - Log syslog messages to remote host specified by `
`. The address - can be specified by either FQDN or IP address. For an explanation on - :ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` - keywords see tables below. - - -.. cfgcmd:: set system syslog host
facility protocol - - - Configure protocol used for communication to remote syslog host. This can be - either UDP or TCP. - - -.. cfgcmd:: set system syslog vrf - - Specify name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance. - -: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
protocol tcp - - -.. note:: :abbr:`TLS (Transport Layer Security)`-encrypted remote logging is - **not supported** over **UDP**. - -.. cfgcmd:: set system syslog remote
tls - - Enable TLS-encrypted remote logging. - -.. cfgcmd:: set system syslog remote
tls ca-certificate - - **Configure the** :abbr:`CA (Certificate Authority)` **certificate.** - - The syslog client uses the :abbr:`CA (Certificate Authority)` certificate to - verify the identity of the remote syslog server. - - The :abbr:`CA (Certificate Authority)` certificate is required for **all** - authentication modes except ``anon``. - -.. cfgcmd:: set system syslog remote
tls certificate - - **Configure the client certificate.** - - The remote syslog server uses the client certificate to verify the identity - of the syslog client. - - The client certificate is required if the remote syslog server enforces - client certificate verification. - -.. cfgcmd:: set system syslog remote
tls auth-mode - - **Configure the authentication mode.** - - The authentication mode defines how the syslog client verifies the syslog - server's identity. - - The following authentication modes are available: - - * ``anon`` **(default)**: Allows encrypted connections without verifying the syslog - server's identity. This mode is **not recommended**, as it is vulnerable to - :abbr:`MITM (Man-in-the-Middle)` attacks. - * ``fingerprint``: Verifies the server’s certificate fingerprint against the - value preconfigured with: - - .. code-block:: none - - set system syslog remote
tls permitted-peer - - * ``certvalid``: Verifies the server certificate is signed by a trusted - :abbr:`CA (Certificate Authority)`, skipping :abbr:`CN (Common Name)` check. - * ``name``: Verifies that: - - * The server’s certificate is signed by a trusted :abbr:`CA (Certificate - Authority)`. - * The :abbr:`CN (Common Name)` in the certificate matches the value - preconfigured with: - - .. code-block:: none - - set system syslog remote
tls permitted-peer - - This is a **recommended** secure mode for production environments. - -.. cfgcmd:: set system syslog remote
tls permitted-peer - - **Configure the peer certificate identifiers.** - - The certificate identifier format depends on the authentication mode: - - * ``fingerprint``: Enter the expected certificate fingerprints (SHA-1 or - SHA-256). - * ``name``: Enter the expected certificate :abbr:`CNs (Common Names)`. - - For ``anon`` and ``certvalid`` authentication modes, certificate identifiers - are not required. - -Examples: -^^^^^^^^^ - -.. code-block:: none - - # Example of 'anon' authentication mode - set system syslog host 10.10.2.3 facility all level debug - set system syslog host 10.10.2.3 port 6514 - set system syslog host 10.10.2.3 protocol tcp - set system syslog host 10.10.2.3 tls auth-mode anon - # or just use 'set system syslog host 10.10.2.3 tls' - - # Example of 'certvalid' authentication mode - set system syslog host elk.example.com facility all level debug - set system syslog host elk.example.com port 6514 - set system syslog host elk.example.com protocol tcp - set system syslog host elk.example.com tls ca-certificate my-ca - set system syslog host elk.example.com tls auth-mode certvalid - - # Example of 'fingerprint' authentication mode - set system syslog host syslog.example.com facility all level debug - set system syslog host syslog.example.com port 6514 - set system syslog host syslog.example.com protocol tcp - set system syslog host syslog.example.com tls ca-certificate my-ca - set system syslog host syslog.example.com tls auth-mode fingerprint - set system syslog host syslog.example.com tls permitted-peer 'SHA1:10:C4:26:...' - - # Example of 'name' authentication mode - set system syslog host graylog.example.com facility all level debug - set system syslog host graylog.example.com port 6514 - set system syslog host graylog.example.com protocol tcp - set system syslog host graylog.example.com tls ca-certificate my-ca - set system syslog host graylog.example.com tls certificate syslog-client - set system syslog host graylog.example.com tls auth-mode name - set system syslog host graylog.example.com tls permitted-peer 'graylog.example.com' - -Security Notes -^^^^^^^^^^^^^^ - -* Always prefer ``auth-mode name`` for secure deployments, as it ensures - both CA trust and server hostname validation. -* ``anon`` mode should only be used for testing, because it does not - authenticate the server. -* Ensure private keys are stored and managed exclusively in the - :doc:`PKI system `. - -Local User Account ------------------- - -.. cfgcmd:: set system syslog user facility level - - If logging to a local user account is configured, all defined log messages - are display on the console if the local user is logged in, if the user is not - logged in, no messages are being displayed. For an explanation on - :ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords - see tables below. - -.. _syslog_facilities: - -Facilities -========== - -List of facilities used by syslog. Most facilities names are self explanatory. -Facilities local0 - local7 common usage is f.e. as network logs facilities for -nodes and network equipment. Generally it depends on the situation how to -classify logs and put them to facilities. See facilities more as a tool rather -than a directive to follow. - -Facilities can be adjusted to meet the needs of the user: - -+----------+----------+----------------------------------------------------+ -| Facility | Keyword | Description | -| Code | | | -+==========+==========+====================================================+ -| | all | All facilities | -+----------+----------+----------------------------------------------------+ -| 0 | kern | Kernel messages | -+----------+----------+----------------------------------------------------+ -| 1 | user | User-level messages | -+----------+----------+----------------------------------------------------+ -| 2 | mail | Mail system | -+----------+----------+----------------------------------------------------+ -| 3 | daemon | System daemons | -+----------+----------+----------------------------------------------------+ -| 4 | auth | Security/authentication messages | -+----------+----------+----------------------------------------------------+ -| 5 | syslog | Messages generated internally by syslogd | -+----------+----------+----------------------------------------------------+ -| 6 | lpr | Line printer subsystem | -+----------+----------+----------------------------------------------------+ -| 7 | news | Network news subsystem | -+----------+----------+----------------------------------------------------+ -| 8 | uucp | UUCP subsystem | -+----------+----------+----------------------------------------------------+ -| 9 | cron | Clock daemon | -+----------+----------+----------------------------------------------------+ -| 10 | security | Security/authentication messages | -+----------+----------+----------------------------------------------------+ -| 11 | ftp | FTP daemon | -+----------+----------+----------------------------------------------------+ -| 12 | ntp | NTP subsystem | -+----------+----------+----------------------------------------------------+ -| 13 | logaudit | Log audit | -+----------+----------+----------------------------------------------------+ -| 14 | logalert | Log alert | -+----------+----------+----------------------------------------------------+ -| 15 | clock | clock daemon (note 2) | -+----------+----------+----------------------------------------------------+ -| 16 | local0 | local use 0 (local0) | -+----------+----------+----------------------------------------------------+ -| 17 | local1 | local use 1 (local1) | -+----------+----------+----------------------------------------------------+ -| 18 | local2 | local use 2 (local2) | -+----------+----------+----------------------------------------------------+ -| 19 | local3 | local use 3 (local3) | -+----------+----------+----------------------------------------------------+ -| 20 | local4 | local use 4 (local4) | -+----------+----------+----------------------------------------------------+ -| 21 | local5 | local use 5 (local5) | -+----------+----------+----------------------------------------------------+ -| 22 | local6 | use 6 (local6) | -+----------+----------+----------------------------------------------------+ -| 23 | local7 | local use 7 (local7) | -+----------+----------+----------------------------------------------------+ - -.. _syslog_severity_level: - -Severity Level -============== - -+-------+---------------+---------+-------------------------------------------+ -| Value | Severity | Keyword | Description | -+=======+===============+=========+===========================================+ -| | | all | Log everything | -+-------+---------------+---------+-------------------------------------------+ -| 0 | Emergency | emerg | System is unusable - a panic condition | -+-------+---------------+---------+-------------------------------------------+ -| 1 | Alert | alert | Action must be taken immediately - A | -| | | | condition that should be corrected | -| | | | immediately, such as a corrupted system | -| | | | database. | -+-------+---------------+---------+-------------------------------------------+ -| 2 | Critical | crit | Critical conditions - e.g. hard drive | -| | | | errors. | -+-------+---------------+---------+-------------------------------------------+ -| 3 | Error | err | Error conditions | -+-------+---------------+---------+-------------------------------------------+ -| 4 | Warning | warning | Warning conditions | -+-------+---------------+---------+-------------------------------------------+ -| 5 | Notice | notice | Normal but significant conditions - | -| | | | conditions that are not error conditions, | -| | | | but that may require special handling. | -+-------+---------------+---------+-------------------------------------------+ -| 6 | Informational | info | Informational messages | -+-------+---------------+---------+-------------------------------------------+ -| 7 | Debug | debug | Debug-level messages - Messages that | -| | | | contain information normally of use only | -| | | | when debugging a program. | -+-------+---------------+---------+-------------------------------------------+ - - -Display Logs -============ - -.. opcmd:: show log [all | authorization | cluster | conntrack-sync | ...] - - Display log files of given category on the console. Use tab completion to get - a list of available categories. Thos categories could be: all, authorization, - cluster, conntrack-sync, dhcp, directory, dns, file, firewall, https, image - lldp, nat, openvpn, snmp, tail, vpn, vrrp - -If no option is specified, this defaults to `all`. - -.. opcmd:: show log image - [all | authorization | directory | file | tail ] - - Log messages from a specified image can be displayed on the console. Details - of allowed parameters: - - .. list-table:: - :widths: 25 75 - :header-rows: 0 - - * - all - - Display contents of all master log files of the specified image - * - authorization - - Display all authorization attempts of the specified image - * - directory - - Display list of all user-defined log files of the specified image - * - file - - Display contents of a specified user-defined log file of the specified - image - * - tail - - Display last lines of the system log of the specified image - * - - - Number of lines to be displayed, default 10 - -When no options/parameters are used, the contents of the main syslog file are -displayed. - -.. hint:: Use ``show log | strip-private`` if you want to hide private data - when sharing your logs. - -Delete Logs -=========== - -.. opcmd:: delete log file - -Deletes the specified user-defined file in the /var/log/user directory - -Note that deleting the log file does not stop the system from logging events. -If you use this command while the system is logging events, old log events -will be deleted, but events after the delete operation will be recorded in -the new file. To delete the file altogether, first delete logging to the -file using system syslog :ref:`custom-file` command, and then delete the file. diff --git a/docs/configuration/system/task-scheduler.md b/docs/configuration/system/task-scheduler.md new file mode 100644 index 00000000..378a648d --- /dev/null +++ b/docs/configuration/system/task-scheduler.md @@ -0,0 +1,48 @@ +(task-scheduler)= + +# Task Scheduler + +The task scheduler allows you to execute tasks on a given schedule. It makes +use of UNIX [cron]. + +:::{note} +All scripts excecuted this way are executed as root user - this may +be dangerous. Together with {ref}`command-scripting` this can be used for +automating (re-)configuration. +::: + +```{eval-rst} +.. cfgcmd:: set system task-scheduler task interval + + Specify the time interval when `` should be executed. The interval + is specified as number with one of the following suffixes: + + * ``none`` - Execution interval in minutes + * ``m`` - Execution interval in minutes + * ``h`` - Execution interval in hours + * ``d`` - Execution interval in days + + .. note:: If suffix is omitted, minutes are implied. +``` + +```{eval-rst} +.. cfgcmd:: set system task-scheduler task crontab-spec + + Set execution time in common cron_ time format. A cron `` of + ``30 */6 * * *`` would execute the `` at minute 30 past every 6th hour. +``` + +```{eval-rst} +.. cfgcmd:: set system task-scheduler task executable path + + Specify absolute `` to script which will be run when `` is + executed. +``` + +```{eval-rst} +.. cfgcmd:: set system task-scheduler task executable arguments + + Arguments which will be passed to the executable. +``` + +[cron]: https://en.wikipedia.org/wiki/Cron diff --git a/docs/configuration/system/task-scheduler.rst b/docs/configuration/system/task-scheduler.rst deleted file mode 100644 index 382da39f..00000000 --- a/docs/configuration/system/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 excecuted this way are executed as root user - this may - be dangerous. Together with :ref:`command-scripting` this can be used for - automating (re-)configuration. - -.. cfgcmd:: set system task-scheduler task interval - - Specify the time interval when `` should be executed. The interval - is specified as number with one of the following suffixes: - - * ``none`` - Execution interval in minutes - * ``m`` - Execution interval in minutes - * ``h`` - Execution interval in hours - * ``d`` - Execution interval in days - - .. note:: If suffix is omitted, minutes are implied. - -.. cfgcmd:: set system task-scheduler task crontab-spec - - Set execution time in common cron_ time format. A cron `` of - ``30 */6 * * *`` would execute the `` at minute 30 past every 6th hour. - -.. cfgcmd:: set system task-scheduler task executable path - - Specify absolute `` to script which will be run when `` is - executed. - -.. cfgcmd:: set system task-scheduler task executable arguments - - Arguments which will be passed to the executable. - -.. _cron: https://en.wikipedia.org/wiki/Cron diff --git a/docs/configuration/system/time-zone.md b/docs/configuration/system/time-zone.md new file mode 100644 index 00000000..2279a773 --- /dev/null +++ b/docs/configuration/system/time-zone.md @@ -0,0 +1,17 @@ +(timezone)= + +# Time Zone + +Time Zone setting is very important as e.g all your logfile entries will be +based on the configured zone. Without proper time zone configuration it will +be very difficult to compare logfiles from different systems. + +```{cfgcmd} set system time-zone \ + +Specify the systems \ as the Region/Location that best defines +your location. For example, specifying US/Pacific sets the time zone to US +Pacific time. + +Command completion can be used to list available time zones. The adjustment +for daylight time will take place automatically based on the time of year. +``` \ No newline at end of file diff --git a/docs/configuration/system/time-zone.rst b/docs/configuration/system/time-zone.rst deleted file mode 100644 index 025c4376..00000000 --- a/docs/configuration/system/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 - - Specify the systems `` as the Region/Location that best defines - your location. For example, specifying US/Pacific sets the time zone to US - Pacific time. - - Command completion can be used to list available time zones. The adjustment - for daylight time will take place automatically based on the time of year. \ No newline at end of file diff --git a/docs/configuration/system/updates.md b/docs/configuration/system/updates.md new file mode 100644 index 00000000..05a9d189 --- /dev/null +++ b/docs/configuration/system/updates.md @@ -0,0 +1,37 @@ +# Updates + +VyOS supports online checking for updates + +## Configuration + +```{eval-rst} +.. cfgcmd:: set system update-check auto-check + + Configure auto-checking for new images + +``` + +```{eval-rst} +.. cfgcmd:: set system update-check url + + Configure a URL that contains information about images. + +``` + +## Example + +```none +set system update-check auto-check +set system update-check url 'https://raw.githubusercontent.com/vyos/vyos-rolling-nightly-builds/main/version.json' +``` + +Check: + +```none +vyos@r4:~$ show system updates +Current version: 1.5-rolling-202312220023 + +Update available: 1.5-rolling-202312250024 +Update URL: https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.5-rolling-202312250024/1.5-rolling-202312250024-amd64.iso +vyos@r4:~$ +``` diff --git a/docs/configuration/system/updates.rst b/docs/configuration/system/updates.rst deleted file mode 100644 index a55bfa9a..00000000 --- a/docs/configuration/system/updates.rst +++ /dev/null @@ -1,37 +0,0 @@ -####### -Updates -####### - -VyOS supports online checking for updates - -Configuration -============= - -.. cfgcmd:: set system update-check auto-check - - Configure auto-checking for new images - - -.. cfgcmd:: set system update-check url - - Configure a URL that contains information about images. - - -Example -======= - -.. 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:~$ -- cgit v1.2.3