diff options
| author | Yuriy Andamasov <yuriy@vyos.io> | 2026-05-06 14:41:08 +0300 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2026-05-06 12:41:08 +0100 |
| commit | 22e34ce5aee24d2fd11f8205522ab7ecdb3c4c5e (patch) | |
| tree | 8d97f7766d9bbd2d0e3a55e5643a60b387308675 /docs/configuration/system | |
| parent | c21b38dbe24088eaca73dbc8030cfebc898d2186 (diff) | |
| download | vyos-documentation-22e34ce5aee24d2fd11f8205522ab7ecdb3c4c5e.tar.gz vyos-documentation-22e34ce5aee24d2fd11f8205522ab7ecdb3c4c5e.zip | |
Add incremental RST-to-MyST swap mechanism (sagitta) (#1868)
* feat(swap-sagitta): add incremental RST-to-MyST swap mechanism
Backport of the swap mechanism from feat/incremental-myst-swap onto
the sagitta release branch. Built directly on top of origin/sagitta,
so the underlying RST tree is sagitta's (not current's).
Mechanism:
- scripts/import_myst.py — import md from myst/* with md- prefix
- scripts/swap_sources.py — rename md-{name}.md → {name}.md before
Sphinx builds, restore after; writes _build/_swap_state.json and
_build/_swap_exclude.txt
- docs/Makefile — html/dirhtml/pdf/livehtml all run swap → build →
trap restore; explicit `swap` and `restore` targets too
- docs/conf.py — MyST extensions enabled; swap exclude_patterns
loader; _prefer_webp builder hook so html prefers webp over png
Content:
- 202 md-prefixed pages from origin/myst/sagitta (md-{name}.md
alongside each {name}.rst counterpart)
- 1 plain MyST-only page from myst/sagitta where no .rst exists
(already at canonical name on sagitta: docs/copyright.md)
- 240 .webp images from myst/sagitta (added alongside the existing
PNG/JPG so RST builds keep their assets)
- docs/_swap.txt populated with all 202 stems → MyST is served by
default, revert a page by removing its stem from _swap.txt
🤖 Generated by [robots](https://vyos.io)
* feat(conf): copy .md sources into HTML output for plain-text serving
Adds a build-finished hook that mirrors every .md file from the Sphinx
source tree into the HTML output directory verbatim, making unrendered
MyST sources accessible alongside HTML renders at the same URL path.
🤖 Generated by [robots](https://vyos.io)
* docs: address review feedback (backport from PR #1857)
Fix conversion artifacts, typos, and technical inaccuracies applicable
to the sagitta branch: curly quotes, typos (deamonless, cammans,
amdifferent, trough), incorrect firewall command paths, missing closing
brace in zone-policy, peer name inconsistencies, hardcoded passwords
replaced with vault references, and md-*.md exclusion in conf.py.
🤖 Generated by [robots](https://vyos.io)
* docs: port .readthedocs.yml jobs, _ext/vyos.py fallback and swap-script tests from PR #1857
Parity backport from PR #1857 (current) — three pieces were missing on
sagitta.
- .readthedocs.yml: add build.jobs.pre_build / post_build hooks that run
scripts/swap_sources.py --swap before the Sphinx build and --restore
after. Without this, the swap mechanism ships but never runs on RTD
builds for this branch — the swap is a silent no-op.
- docs/_ext/vyos.py: CmdInclude.run() now falls back to nested_parse()
when self.state._renderer is not present. Required for cfgcmd /
opcmd / cmdincludemd directives to render correctly when included
from MyST pages (the swap mechanism's whole point). Sagitta-only
delta on _ext/vyos.py (the path = str(path) line on 224) is
intentionally untouched.
- tests/test_import_myst.py, tests/test_swap_sources.py: tests for the
swap scripts. The scripts on this branch are byte-identical to
current's, so the same tests apply. Travels with the branch so CI
catches per-branch regressions if the scripts ever drift.
🤖 Generated by [robots](https://vyos.io)
* fix(conf): skip md-*.md staging files in _copy_md_sources
Agent-Logs-Url: https://github.com/vyos/vyos-documentation/sessions/919695a7-688d-41b9-89f0-540684625dbc
Co-authored-by: andamasov <12631358+andamasov@users.noreply.github.com>
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: andamasov <12631358+andamasov@users.noreply.github.com>
Diffstat (limited to 'docs/configuration/system')
21 files changed, 3447 insertions, 0 deletions
diff --git a/docs/configuration/system/md-acceleration.md b/docs/configuration/system/md-acceleration.md new file mode 100644 index 00000000..21096988 --- /dev/null +++ b/docs/configuration/system/md-acceleration.md @@ -0,0 +1,168 @@ +# Acceleration + +In this command tree, all hardware acceleration options will be handled. +At the moment only [Intel® QAT](https://www.intel.com/content/www/us/en/architecture-and-technology/intel-quick-assist-technology-overview.html) is supported + +## Intel® QAT + +<div class="opcmd"> + +show system acceleration qat + +use this command to check if there is an Intel® QAT supported Processor in +your system. + +``` +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 ``\` + +</div> + +<div class="cfgcmd"> + +set system acceleration qat + +if there is a supported device, enable Intel® QAT + +</div> + +<div class="opcmd"> + +show system acceleration qat status + +Check if the Intel® QAT device is up and ready to do the job. + +``` +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 +``` + +</div> + +### Operation Mode + +<div class="opcmd"> + +show system acceleration qat device \<device\> config + +Show the full config uploaded to the QAT device. + +</div> + +<div class="opcmd"> + +show system acceleration qat device \<device\> flows + +Get an overview over the encryption counters. + +</div> + +<div class="opcmd"> + +show system acceleration qat interrupts + +Show binded qat device interrupts to certain core. + +</div> + +### 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 `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 +``` diff --git a/docs/configuration/system/md-conntrack.md b/docs/configuration/system/md-conntrack.md new file mode 100644 index 00000000..2d5afdfd --- /dev/null +++ b/docs/configuration/system/md-conntrack.md @@ -0,0 +1,473 @@ +# 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 + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack table-size \<1-50000000\> + +The connection tracking table contains one entry for each connection being +tracked by the system. + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack expect-table-size \<1-50000000\> + +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. + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack hash-size \<1-50000000\> + +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. + +</div> + +<div class="cfgcmd"> + +set system conntrack modules ftp + +</div> + +<div class="cfgcmd"> + +set system conntrack modules h323 + +</div> + +<div class="cfgcmd"> + +set system conntrack modules nfs + +</div> + +<div class="cfgcmd"> + +set system conntrack modules pptp + +</div> + +<div class="cfgcmd"> + +set system conntrack modules sip + +</div> + +<div class="cfgcmd"> + +set system conntrack modules sqlnet + +</div> + +<div class="cfgcmd"> + +set system conntrack modules tftp + +Configure the connection tracking protocol helper modules. +All modules are enable by default. + +Use <span class="title-ref">delete system conntrack modules</span> to deactive all modules.\ +Or, for example ftp, <span class="title-ref">delete system conntrack modules ftp</span>. + +</div> + +### 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. + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout icmp \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout other \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp close \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp close-wait \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp established \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp fin-wait \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp last-ack \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp syn-recv \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp syn-sent \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout tcp time-wait \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout udp other \<1-21474836\> + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack timeout udp stream \<1-21474836\> + +Set the timeout in secounds for a protocol or state. + +</div> + +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. + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> description \<test\> + +Set a rule description. + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> destination address \<ip-address\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> source address \<ip-address\> + +set a destination and/or source address. Accepted input: + +``` none +<x.x.x.x> IP address to match +<x.x.x.x/x> Subnet to match +<x.x.x.x>-<x.x.x.x> + IP range to match +!<x.x.x.x> Match everything except the specified address +!<x.x.x.x/x> Match everything except the specified subnet +!<x.x.x.x>-<x.x.x.x> + Match everything except the specified range +``` + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> destination port \<value\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> source port \<value\> + +Set a destination and/or source port. Accepted input: + +``` none +<port name> Named port (any name in /etc/services, e.g., http) +<1-65535> Numbered port +<start>-<end> Numbered port range (e.g., 1001-1005) +``` + +Multiple destination ports can be specified as a comma-separated list. +The whole list can also be "negated" using '!'. For example: +<span class="title-ref">!22,telnet,http,123,1001-1005</span>\` + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol icmp \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol other \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp close \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp close-wait \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp established \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp fin-wait \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp last-ack \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp syn-recv \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp syn-sent \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol tcp time-wait \<1-21474836\> + +</div> + +<div class="cfgcmd"> + +set system conntrack timeout custom rule \<1-9999\> protocol udp other \<1-21474836\> + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack tcp half-open-connections \<1-21474836\> + +Set the maximum number of TCP half-open connections. + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack tcp loose \<enable | disable\> + +Policy to track previously established connections. + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system conntrack tcp max-retrans \<1-2147483647\> + +Set the number of TCP maximum retransmit attempts. + +</div> + +<div class="cfgcmd"> + +set system conntrack ignore rule \<1-9999\> description \<text\> + +</div> + +<div class="cfgcmd"> + +set system conntrack ignore rule \<1-9999\> destination address \<ip-address\> + +</div> + +<div class="cfgcmd"> + +set system conntrack ignore rule \<1-9999\> destination port \<port\> + +</div> + +<div class="cfgcmd"> + +set system conntrack ignore rule \<1-9999\> inbound-interface \<interface\> + +</div> + +<div class="cfgcmd"> + +set system conntrack ignore rule \<1-9999\> protocol \<protocol\> + +</div> + +<div class="cfgcmd"> + +set system conntrack ignore rule \<1-9999\> source address \<ip-address\> + +</div> + +<div class="cfgcmd"> + +set system conntrack ignore rule \<1-9999\> source port \<port\> + +Customized ignore rules, based on a packet and flow selector. + +</div> + +<div class="cfgcmd"> + +set system conntrack log icmp destroy + +</div> + +<div class="cfgcmd"> + +set system conntrack log icmp new + +</div> + +<div class="cfgcmd"> + +set system conntrack log icmp update + +</div> + +<div class="cfgcmd"> + +set system conntrack log other destroy + +</div> + +<div class="cfgcmd"> + +set system conntrack log other new + +</div> + +<div class="cfgcmd"> + +set system conntrack log other update + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp destroy + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp new + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp update close-wait + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp update established + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp update fin-wait + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp update last-ack + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp update syn-received + +</div> + +<div class="cfgcmd"> + +set system conntrack log tcp update time-wait + +</div> + +<div class="cfgcmd"> + +set system conntrack log udp destroy + +</div> + +<div class="cfgcmd"> + +set system conntrack log udp new + +</div> + +<div class="cfgcmd"> + +set system conntrack log udp update + +Log the connection tracking events per protocol. + +</div> diff --git a/docs/configuration/system/md-console.md b/docs/configuration/system/md-console.md new file mode 100644 index 00000000..3a58301d --- /dev/null +++ b/docs/configuration/system/md-console.md @@ -0,0 +1,59 @@ +# 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 `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. + +<div class="cfgcmd"> + +set system console device \<device\> + +Defines the specified device as a system console. Available console devices +can be (see completion helper): + +- `ttySN` - Serial device name +- `ttyUSBX` - USB Serial device name +- `hvc0` - Xen console + +</div> + +<div class="cfgcmd"> + +set system console device \<device\> speed \<speed\> + +The speed (baudrate) of the console device. Supported values are: + +- `1200` - 1200 bps +- `2400` - 2400 bps +- `4800` - 4800 bps +- `9600` - 9600 bps +- `19200` - 19,200 bps +- `38400` - 38,400 bps (default for Xen console) +- `57600` - 57,600 bps +- `115200` - 115,200 bps (default for serial console) + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +</div> diff --git a/docs/configuration/system/md-default-route.md b/docs/configuration/system/md-default-route.md new file mode 100644 index 00000000..c973dc09 --- /dev/null +++ b/docs/configuration/system/md-default-route.md @@ -0,0 +1,48 @@ +# Default Gateway/Route + +In the past (VyOS 1.1) used a gateway-address configured under the system tree +(`set system gateway-address <address>`), this is no longer supported +and existing configurations are migrated to the new CLI command. + +## Configuration + +<div class="cfgcmd"> + +set protocols static route 0.0.0.0/0 next-hop \<address\> + +Specify static route into the routing table sending all non local traffic +to the nexthop address <span class="title-ref">\<address\></span>. + +</div> + +<div class="cfgcmd"> + +delete protocols static route 0.0.0.0/0 + +Delete default route from the system. + +</div> + +## Operation + +<div class="opcmd"> + +show ip route 0.0.0.0 + +Show routing table entry for the default route. + +``` 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 +``` + +</div> + +<div class="seealso"> + +Configuration of `routing-static` + +</div> diff --git a/docs/configuration/system/md-flow-accounting.md b/docs/configuration/system/md-flow-accounting.md new file mode 100644 index 00000000..3a66fce5 --- /dev/null +++ b/docs/configuration/system/md-flow-accounting.md @@ -0,0 +1,312 @@ +# 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. + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +You need to disable the in-memory table in production environments! +Using `IMT (In-Memory Table)` may lead to heavy CPU overloading and +unstable flow-accounting behavior. + +</div> + +## 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 + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +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. + +</div> + +In order for flow accounting information to be collected and displayed for an +interface, the interface must be configured for flow accounting. + +<div class="cfgcmd"> + +set system flow-accounting interface \<interface\> + +Configure and enable collection of flow information for the interface +identified by <span class="title-ref">\<interface\></span>. + +You can configure multiple interfaces which whould participate in flow +accounting. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Will be recorded only packets/flows on **incoming** direction in +configured interfaces by default. + +</div> + +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: + +<div class="cfgcmd"> + +set system flow-accounting disable-imt + +If you need to sample also egress traffic, you may want to +configure egress flow-accounting: + +</div> + +<div class="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: + +</div> + +<div class="cfgcmd"> + +set system flow-accounting buffer-size \<buffer size\> + +In case, if you need to catch some logs from flow-accounting daemon, you may +configure logging facility: + +</div> + +<div class="cfgcmd"> + +set system flow-accounting syslog-facility \<facility\> + +TBD + +</div> + +### Flow Export + +In addition to displaying flow accounting information locally, one can also +exported them to a collection server. + +#### NetFlow + +<div class="cfgcmd"> + +set system flow-accounting netflow version \<version\> + +There are multiple versions available for the NetFlow data. The <span class="title-ref">\<version\></span> +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** - `IPFIX (IP Flow Information Export)` as per `3917` + +</div> + +<div class="cfgcmd"> + +set system flow-accounting netflow server \<address\> + +Configure address of NetFlow collector. NetFlow server at <span class="title-ref">\<address\></span> can +be both listening on an IPv4 or IPv6 address. + +</div> + +<div class="cfgcmd"> + +set system flow-accounting netflow source-ip \<address\> + +IPv4 or IPv6 source address of NetFlow packets + +</div> + +<div class="cfgcmd"> + +set system flow-accounting netflow engine-id \<id\> + +NetFlow engine-id which will appear in NetFlow data. The range is 0 to 255. + +</div> + +<div class="cfgcmd"> + +set system flow-accounting netflow sampling-rate \<rate\> + +Use this command to configure the sampling rate for flow accounting. The +system samples one in every <span class="title-ref">\<rate\></span> packets, where <span class="title-ref">\<rate\></span> 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). + +</div> + +<div class="cfgcmd"> + +set system flow-accounting netflow timeout expiry-interval +\<interval\> + +Specifies the interval at which Netflow data will be sent to a collector. As +per default, Netflow data will be sent every 60 seconds. + +You may also additionally configure timeouts for different types of +connections. + +</div> + +<div class="cfgcmd"> + +set system flow-accounting netflow max-flows \<n\> + +If you want to change the maximum number of flows, which are tracking +simultaneously, you may do this with this command (default 8192). + +</div> + +#### sFlow + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Using <span class="title-ref">system sflow</span> is recommended in favor of +<span class="title-ref">system flow-accounting</span>. See [sflow](sflow.html) + +</div> + +<div class="cfgcmd"> + +set system flow-accounting sflow server \<address\> + +Configure address of sFlow collector. sFlow server at <span class="title-ref">\<address\></span> can +be an IPv4 or IPv6 address. But you cannot export to both IPv4 and +IPv6 collectors at the same time! + +</div> + +<div class="cfgcmd"> + +set system flow-accounting sflow sampling-rate \<rate\> + +Enable sampling of packets, which will be transmitted to sFlow collectors. + +</div> + +<div class="cfgcmd"> + +set system flow-accounting sflow agent-address \<address\> + +Configure a sFlow agent address. It can be IPv4 or IPv6 address, but you +must set the same protocol, which is used for sFlow collector addresses. By +default, using router-id from BGP or OSPF protocol, or the primary IP +address from the first interface. + +</div> + +### 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. + +<div class="opcmd"> + +show flow-accounting interface \<interface\> + +Show flow accounting information for given <span class="title-ref">\<interface\></span>. + +``` 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 +``` + +</div> + +<div class="opcmd"> + +show flow-accounting interface \<interface\> host \<address\> + +Show flow accounting information for given <span class="title-ref">\<interface\></span> for a specific host +only. + +``` 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 +``` + +</div> diff --git a/docs/configuration/system/md-frr.md b/docs/configuration/system/md-frr.md new file mode 100644 index 00000000..7116d1de --- /dev/null +++ b/docs/configuration/system/md-frr.md @@ -0,0 +1,50 @@ +# 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. + +<div class="cfgcmd"> + +set system frr bmp + +Enable `BMP (BGP Monitoring Protocol)` support + +</div> + +<div class="cfgcmd"> + +set system frr descriptors \<numer\> + +This allows the operator to control the number of open file descriptors +each daemon is allowed to start with. If the operator plans to run bgp with +several thousands of peers then this is where we would modify FRR to allow +this to happen. + +</div> + +<div class="cfgcmd"> + +set system frr irdp + +Enable ICMP Router Discovery Protocol support + +</div> + +<div class="cfgcmd"> + +set system frr snmp \<daemon\> + +Enable SNMP support for an individual routing daemon. + +Supported daemons: + +- bgpd +- isisd +- ldpd +- ospf6d +- ospfd +- ripd +- zebra + +</div> diff --git a/docs/configuration/system/md-host-name.md b/docs/configuration/system/md-host-name.md new file mode 100644 index 00000000..ebb83a5f --- /dev/null +++ b/docs/configuration/system/md-host-name.md @@ -0,0 +1,86 @@ +# 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. + +<div class="cfgcmd"> + +set system host-name \<hostname\> + +The hostname can be up to 63 characters. A hostname +must start and end with a letter or digit, and have as interior characters +only letters, digits, or a hyphen. + +The default hostname used is <span class="title-ref">vyos</span>. + +</div> + +## 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 <span class="title-ref">example.com</span>, and you would ping the +unqualified name of <span class="title-ref">crux</span>, then VyOS qualifies the name to <span class="title-ref">crux.example.com</span>. + +<div class="cfgcmd"> + +set system domain-name \<domain\> + +Configure system domain name. A domain name must start and end with a letter +or digit, and have as interior characters only letters, digits, or a hyphen. + +</div> + +## Static Hostname Mapping + +How an IP address is assigned to an interface in `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 +<span class="title-ref">/etc/hosts</span> file entries. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Do *not* manually edit <span class="title-ref">/etc/hosts</span>. 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. + +</div> + +<div class="cfgcmd"> + +set system static-host-mapping host-name \<hostname\> inet \<address\> + +Create a static hostname mapping which will always resolve the name +<span class="title-ref">\<hostname\></span> to IP address <span class="title-ref">\<address\></span>. + +</div> + +<div class="cfgcmd"> + +set system static-host-mapping host-name \<hostname\> alias \<alias\> + +Create named <span class="title-ref">\<alias\></span> for the configured static mapping for <span class="title-ref">\<hostname\></span>. +Thus the address configured as `set system static-host-mapping +host-name <hostname> inet <address>` can be reached via multiple names. + +Multiple aliases can be specified per host-name. + +</div> diff --git a/docs/configuration/system/md-index.md b/docs/configuration/system/md-index.md new file mode 100644 index 00000000..ea77a2c6 --- /dev/null +++ b/docs/configuration/system/md-index.md @@ -0,0 +1,31 @@ +# System + +<div class="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 + +</div> + +<div class="toctree" maxdepth="1" includehidden=""> + +default-route + +</div> diff --git a/docs/configuration/system/md-ip.md b/docs/configuration/system/md-ip.md new file mode 100644 index 00000000..cbdc53c4 --- /dev/null +++ b/docs/configuration/system/md-ip.md @@ -0,0 +1,132 @@ +# IP + +## System configuration commands + +<div class="cfgcmd"> + +set system ip disable-forwarding + +Use this command to disable IPv4 forwarding on all interfaces. + +</div> + +<div class="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. + +</div> + +<div class="cfgcmd"> + +set system ip arp table-size \<number\> + +Use this command to define the maximum number of entries to keep in +the ARP cache (1024, 2048, 4096, 8192, 16384, 32768). + +</div> + +<div class="cfgcmd"> + +set system ip multipath layer4-hashing + +Use this command to use Layer 4 information for IPv4 ECMP hashing. + +</div> + +### 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. + +<div class="cfgcmd"> + +set system ip protocol \<protocol\> route-map \<route-map\> + +Apply a route-map filter to routes for the specified protocol. The following +protocols can be used: any, babel, bgp, connected, eigrp, isis, kernel, +ospf, rip, static, table + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you choose any as the option that will cause all protocols that +are sending routes to zebra. + +</div> + +</div> + +### 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. + +<div class="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. + +</div> + +## Operational commands + +### show commands + +See below the different parameters available for the IPv4 **show** command: + +``` none +vyos@vyos:~$ show ip +Possible completions: + access-list Show all IP access-lists + as-path-access-list + Show all as-path-access-lists + bgp Show Border Gateway Protocol (BGP) information + community-list + Show IP community-lists + extcommunity-list + Show extended IP community-lists + forwarding Show IP forwarding status + groups Show IP multicast group membership + igmp Show IGMP (Internet Group Management Protocol) information + large-community-list + Show IP large-community-lists + multicast Show IP multicast + ospf Show IPv4 Open Shortest Path First (OSPF) routing information + pim Show PIM (Protocol Independent Multicast) information + ports Show IP ports in use by various system services + prefix-list Show all IP prefix-lists + protocol Show IP route-maps per protocol + rip Show Routing Information Protocol (RIP) information + route Show IP routes +``` + +### reset commands + +And the different IPv4 **reset** commands available: + +``` none +vyos@vyos:~$ reset ip +Possible completions: + arp Reset Address Resolution Protocol (ARP) cache + bgp Clear Border Gateway Protocol (BGP) statistics or status + igmp IGMP clear commands + multicast IP multicast routing table + route Reset IP route +``` diff --git a/docs/configuration/system/md-ipv6.md b/docs/configuration/system/md-ipv6.md new file mode 100644 index 00000000..47b775e6 --- /dev/null +++ b/docs/configuration/system/md-ipv6.md @@ -0,0 +1,278 @@ +# IPv6 + +## System configuration commands + +<div class="cfgcmd"> + +set system ipv6 disable-forwarding + +Use this command to disable IPv6 forwarding on all interfaces. + +</div> + +<div class="cfgcmd"> + +set system ipv6 neighbor table-size \<number\> + +Use this command to define the maximum number of entries to keep in +the Neighbor cache (1024, 2048, 4096, 8192, 16384, 32768). + +</div> + +<div class="cfgcmd"> + +set system ipv6 strict-dad + +Use this command to disable IPv6 operation on interface when +Duplicate Address Detection fails on Link-Local address. + +</div> + +<div class="cfgcmd"> + +set system ipv6 multipath layer4-hashing + +Use this command to user Layer 4 information for ECMP hashing. + +</div> + +### 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. + +<div class="cfgcmd"> + +set system ipv6 protocol \<protocol\> route-map \<route-map\> + +Apply a route-map filter to routes for the specified protocol. The following +protocols can be used: any, babel, bgp, connected, isis, kernel, ospfv3, +ripng, static, table + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If you choose any as the option that will cause all protocols that +are sending routes to zebra. + +</div> + +</div> + +### 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. + +<div class="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. + +</div> + +## Operational commands + +### Show commands + +<div class="opcmd"> + +show ipv6 neighbors + +Use this command to show IPv6 Neighbor Discovery Protocol information. + +</div> + +<div class="opcmd"> + +show ipv6 groups + +Use this command to show IPv6 multicast group membership. + +</div> + +<div class="opcmd"> + +show ipv6 forwarding + +Use this command to show IPv6 forwarding status. + +</div> + +<div class="opcmd"> + +show ipv6 route + +Use this command to show IPv6 routes. + +Check the many parameters available for the <span class="title-ref">show ipv6 route</span> command: + +``` none +vyos@vyos:~$ show ipv6 route +Possible completions: + <Enter> Execute the current command + <X:X::X:X> Show IPv6 routes of given address or prefix + <X:X::X:X/M> + bgp Show IPv6 BGP routes + cache Show kernel IPv6 route cache + connected Show IPv6 connected routes + forward Show kernel IPv6 route table + isis Show IPv6 ISIS routes + kernel Show IPv6 kernel routes + ospfv3 Show IPv6 OSPF6 routes + ripng Show IPv6 RIPNG routes + static Show IPv6 static routes + summary Show IPv6 routes summary + table Show IP routes in policy table + vrf Show IPv6 routes in VRF +``` + +</div> + +<div class="opcmd"> + +show ipv6 prefix-list + +Use this command to show all IPv6 prefix lists + +There are different parameters for getting prefix-list information: + +``` none +vyos@vyos:~$ show ipv6 prefix-list +Possible completions: + <Enter> Execute the current command + <WORD> Show specified IPv6 prefix-list + detail Show detail of IPv6 prefix-lists + summary Show summary of IPv6 prefix-lists +``` + +</div> + +<div class="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: + +``` none +vyos@vyos:~$ show ipv6 access-list +Possible completions: + <Enter> Execute the current command + <text> Show specified IPv6 access-list +``` + +</div> + +<div class="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: + +``` none +vyos@vyos:~$ show ipv6 bgp +Possible completions: + <Enter> Execute the current command + <X:X::X:X> Show BGP information for given address or prefix + <X:X::X:X/M> + community Show routes matching the communities + community-list + Show routes matching the community-list + filter-list Show routes conforming to the filter-list + large-community + Show routes matching the large-community-list + large-community-list + neighbors Show detailed information on TCP and BGP neighbor connections + prefix-list Show routes matching the prefix-list + regexp Show routes matching the AS path regular expression + route-map Show BGP routes matching the specified route map + summary Show summary of BGP neighbor status +``` + +</div> + +<div class="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: + +``` none +vyos@vyos:~$ show ipv6 ospfv3 +Possible completions: + <Enter> Execute the current command + area Show OSPFv3 spf-tree information + border-routers + Show OSPFv3 border-router (ABR and ASBR) information + database Show OSPFv3 Link state database information + interface Show OSPFv3 interface information + linkstate Show OSPFv3 linkstate routing information + neighbor Show OSPFv3 neighbor information + redistribute Show OSPFv3 redistribute External information + route Show OSPFv3 routing table information +``` + +</div> + +<div class="opcmd"> + +show ipv6 ripng + +Use this command to get information about the RIPNG protocol + +</div> + +<div class="opcmd"> + +show ipv6 ripng status + +Use this command to show the status of the RIPNG protocol + +</div> + +### Reset commands + +<div class="opcmd"> + +reset bgp ipv6 \<address\> + +Use this command to clear Border Gateway Protocol statistics or +status. + +</div> + +<div class="opcmd"> + +reset ipv6 neighbors \<address | interface\> + +Use this command to reset IPv6 Neighbor Discovery Protocol cache for +an address or interface. + +</div> + +<div class="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. + +</div> diff --git a/docs/configuration/system/md-lcd.md b/docs/configuration/system/md-lcd.md new file mode 100644 index 00000000..b5a50b3c --- /dev/null +++ b/docs/configuration/system/md-lcd.md @@ -0,0 +1,52 @@ +# System Display (LCD) + +The system LCD `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 +(<span class="title-ref">ttySxx</span>) or serial via USB or even old parallel port interfaces. + +## Configuration + +<div class="cfgcmd"> + +set system lcd device \<device\> + +This is the name of the physical interface used to connect to your LCD +display. Tab completion is supported and it will list you all available +serial interface. + +For serial via USB port information please refor to: `hardware_usb`. + +</div> + +<div class="cfgcmd"> + +set system lcd model \<model\> + +This is the LCD model used in your system. + +At the time of this writing the following displays are supported: + +- Crystalfontz CFA-533 +- Crystalfontz CFA-631 +- Crystalfontz CFA-633 +- Crystalfontz CFA-635 + +<div class="note"> + +<div class="title"> + +Note + +</div> + +We can't support all displays from the beginning. If your display +type is missing, please create a feature request via [Phabricator](). + +</div> + +</div> diff --git a/docs/configuration/system/md-login.md b/docs/configuration/system/md-login.md new file mode 100644 index 00000000..253e3673 --- /dev/null +++ b/docs/configuration/system/md-login.md @@ -0,0 +1,549 @@ +lastproofread +2022-10-15 + +# Login/User Management + +The default VyOS user account (<span class="title-ref">vyos</span>), 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 `RADIUS (Remote +Authentication Dial-In User Service)` accounts are supported. + +## Local + +<div class="cfgcmd"> + +set system login user \<name\> full-name "\<string\>" + +Create new system user with username <span class="title-ref">\<name\></span> and real-name specified by +<span class="title-ref">\<string\></span>. + +</div> + +<div class="cfgcmd"> + +set system login user \<name\> authentication plaintext-password +\<password\> + +Specify the plaintext password user by user <span class="title-ref">\<name\></span> on this system. The +plaintext password will be automatically transferred into a secure hashed +password and not saved anywhere in plaintext. + +</div> + +<div class="cfgcmd"> + +set system login user \<name\> authentication encrypted-password +\<password\> + +Setup encrypted password for given username. This is useful for +transferring a hashed password from system to system. + +</div> + +<div class="cfgcmd"> + +set system login user \<name\> disable + +Disable (lock) account. User will not be able to log in. + +</div> + +### 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. + +<div class="seealso"> + +SSH `ssh_operation` + +</div> + +<div class="cfgcmd"> + +set system login user \<username\> authentication public-keys +\<identifier\> key \<key\> + +Assign the SSH public key portion <span class="title-ref">\<key\></span> identified by per-key +<span class="title-ref">\<identifier\></span> to the local user <span class="title-ref">\<username\></span>. + +</div> + +<div class="cfgcmd"> + +set system login user \<username\> authentication public-keys +\<identifier\> type \<type\> + +Every SSH public key portion referenced by <span class="title-ref">\<identifier\></span> requires the +configuration of the <span class="title-ref">\<type\></span> 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` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +You can assign multiple keys to the same user by using a unique +identifier per SSH key. + +</div> + +</div> + +<div class="cfgcmd"> + +set system login user \<username\> authentication public-keys +\<identifier\> options \<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. + +</div> + +### MFA/2FA authentication using OTP (one time passwords) + +It is possible to enhance authentication security by using the `2FA +(Two-factor authentication)`/`MFA (Multi-factor authentication)` feature +together with `OTP (One-Time-Pad)` on VyOS. `2FA (Two-factor +authentication)`/`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. + +<div class="cfgcmd"> + +set system login user \<username\> authentication otp key \<key\> + +Enable OTP 2FA for user <span class="title-ref">username</span> with default settings, using the BASE32 +encoded 2FA/MFA key specified by <span class="title-ref">\<key\></span>. + +</div> + +#### Optional/default settings + +<div class="cfgcmd" defaultvalue=""> + +set system login user \<username\> authentication otp rate-limit \<limit\> + +Limit logins to <span class="title-ref">\<limit\></span> per every `rate-time` seconds. Rate limit +must be between 1 and 10 attempts. + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system login user \<username\> authentication otp rate-time \<seconds\> + +Limit logins to `rate-limit` attemps per every <span class="title-ref">\<seconds\></span>. Rate time must +be between 15 and 600 seconds. + +</div> + +<div class="cfgcmd" defaultvalue=""> + +set system login user \<username\> authentication otp window-size \<size\> + +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. + +</div> + +#### OTP-key generation + +The following command can be used to generate the OTP key as well +as the CLI commands to configure them: + +<div class="cfgcmd"> + +generate system login username \<username\> otp-key hotp-time +rate-limit \<1-10\> rate-time \<15-600\> window-size \<1-21\> + +</div> + +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: + +<div class="cfgcmd"> + +sh system login authentication user \<username\> otp +\<full[|key-b32|](##SUBST##|key-b32|)qrcode|uri\> + +</div> + +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 `RADIUS (Remote Authentication +Dial-In User Service)` servers as backend for user authentication. + +### Configuration + +<div class="cfgcmd"> + +set system login radius server \<address\> key \<secret\> + +Specify the IP <span class="title-ref">\<address\></span> of the RADIUS server user with the pre-shared-secret +given in <span class="title-ref">\<secret\></span>. + +Multiple servers can be specified. + +</div> + +<div class="cfgcmd"> + +set system login radius server \<address\> port \<port\> + +Configure the discrete port under which the RADIUS server can be reached. + +This defaults to 1812. + +</div> + +<div class="cfgcmd"> + +set system login radius server \<address\> disable + +Temporary disable this RADIUS server. It won't be queried. + +</div> + +<div class="cfgcmd"> + +set system login radius server \<address\> timeout \<timeout\> + +Setup the <span class="title-ref">\<timeout\></span> in seconds when querying the RADIUS server. + +</div> + +<div class="cfgcmd"> + +set system login radius source-address \<address\> + +RADIUS servers could be hardened by only allowing certain IP addresses to +connect. As of this the source address of each RADIUS query can be +configured. + +If 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. + +</div> + +<div class="cfgcmd"> + +set system login radius vrf \<name\> + +Source all connections to the RADIUS servers from given VRF <span class="title-ref">\<name\></span>. + +</div> + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +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. + +</div> + +## TACACS+ + +In addition to `RADIUS (Remote Authentication Dial-In User Service)`, +`TACACS (Terminal Access Controller Access Control System)` can also be +found in large deployments. +VyOS only supports <span class="title-ref">Authentication</span> via <span class="title-ref">TACACS+</span> servers but does not support <span class="title-ref">Authorization</span> or <span class="title-ref">Accounting</span> yet + +TACACS is defined in `8907`. + +### Configuration + +<div class="cfgcmd"> + +set system login tacas server \<address\> key \<secret\> + +Specify the IP <span class="title-ref">\<address\></span> of the TACACS server user with the pre-shared-secret +given in <span class="title-ref">\<secret\></span>. + +Multiple servers can be specified. + +</div> + +<div class="cfgcmd"> + +set system login tacas server \<address\> port \<port\> + +Configure the discrete port under which the TACACS server can be reached. + +This defaults to 49. + +</div> + +<div class="cfgcmd"> + +set system login tacas server \<address\> disable + +Temporary disable this TACACS server. It won't be queried. + +</div> + +<div class="cfgcmd"> + +set system login tacas server \<address\> timeout \<timeout\> + +Setup the <span class="title-ref">\<timeout\></span> in seconds when querying the TACACS server. + +</div> + +<div class="cfgcmd"> + +set system login tacas source-address \<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. + +</div> + +<div class="cfgcmd"> + +set system login tacas vrf \<name\> + +Source all connections to the TACACS servers from given VRF <span class="title-ref">\<name\></span>. + +</div> + +## Login Banner + +You are able to set post-login or pre-login banner messages to display certain +information for this system. + +<div class="cfgcmd"> + +set system login banner pre-login \<message\> + +Configure <span class="title-ref">\<message\></span> which is shown during SSH connect and before a user is +logged in. + +</div> + +<div class="cfgcmd"> + +set system login banner post-login \<message\> + +Configure <span class="title-ref">\<message\></span> which is shown after user has logged in to the system. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +To create a new line in your login message you need to escape the new +line character by using `\\n`. + +</div> + +## Limits + +Login limits + +<div class="cfgcmd"> + +set system login max-login-session \<number\> + +Set a limit on the maximum number of concurrent logged-in users on +the system. + +This option must be used with `timeout` option. + +</div> + +<div class="cfgcmd"> + +set system login timeout \<timeout\> + +Configure session timeout after which the user will be logged out. + +</div> + +## Example + +In the following example, both <span class="title-ref">User1</span> and <span class="title-ref">User2</span> will be able to SSH into +VyOS as user `vyos` using their very own keys. <span class="title-ref">User1</span> 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 new file mode 100644 index 00000000..ea544b16 --- /dev/null +++ b/docs/configuration/system/md-name-server.md @@ -0,0 +1,81 @@ +# System DNS + +<div class="warning"> + +<div class="title"> + +Warning + +</div> + +If you are configuring a VRF for management purposes, there is +currently no way to force system DNS traffic via a specific VRF. + +</div> + +This section describes configuring DNS on the system, namely: + +> - DNS name servers +> - Domain search order + +## DNS name servers + +<div class="cfgcmd"> + +set system name-server \<address\> + +Use this command to specify a DNS server for the system to be used +for DNS lookups. More than one DNS server can be added, configuring +one at a time. Both IPv4 and IPv6 addresses are supported. + +</div> + +### 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. + +<div class="cfgcmd"> + +set system domain-search \<domain\> + +Use this command to define domains, one at a time, so that the system +uses them to complete unqualified host names. Maximum: 6 entries. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Domain names can include letters, numbers, hyphens and periods +with a maximum length of 253 characters. + +</div> + +### Example + +The system is configured to attempt domain completion in the following +order: vyos.io (first), vyos.net (second) and vyos.network (last): + +``` none +set system domain-search vyos.io +set system domain-search vyos.net +set system domain-search vyos.network +``` diff --git a/docs/configuration/system/md-option.md b/docs/configuration/system/md-option.md new file mode 100644 index 00000000..8ad69d76 --- /dev/null +++ b/docs/configuration/system/md-option.md @@ -0,0 +1,262 @@ +# Option + +This chapter describe the possibilities of advanced system behavior. + +## General + +<div class="cfgcmd"> + +set system option ctrl-alt-delete \<ignore | reboot | poweroff\> + +Action which will be run once the ctrl-alt-del keystroke is received. + +</div> + +<div class="cfgcmd"> + +set system option reboot-on-panic + +Automatically reboot system on kernel panic after 60 seconds. + +</div> + +<div class="cfgcmd"> + +set system option startup-beep + +Play an audible beep to the system speaker when system is ready. + +</div> + +<div class="cfgcmd"> + +set system option root-partition-auto-resize + +Enables the root partition auto-extension and resizes to the maximum +available space on system boot. + +</div> + +### Kernel + +<div class="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` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Setting will only become active with the next reboot! + +</div> + +</div> + +<div class="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 + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Setting will only become active with the next reboot! + +</div> + +</div> + +<div class="cfgcmd"> + +set system option kernel amd-pstate-driver \<mode\> + +Enables and configures p-state driver for modern AMD Ryzen and Epyc CPUs. + +The available modes are: + +- `active` This is the low-level firmware control mode based on the profile + set and the system governor has no effect. +- `passive` The driver allows the system governor to manage CPU frequency + while providing available performance states. +- `guided` The driver allows to set desired performance levels and the firmware + selects a performance level in this range and fitting to the current workload. + +This will add the following two options to the Kernel commandline: + +- `initcall_blacklist=acpi_cpufreq_init` Disable default ACPI CPU frequency scale +- `amd_pstate={mode}` Sets the p-state mode + +<div class="note"> + +<div class="title"> + +Note + +</div> + +Setting will only become active with the next reboot! + +</div> + +<div class="seealso"> + +<https://docs.kernel.org/admin-guide/pm/amd-pstate.html> + +</div> + +</div> + +<div class="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. + +</div> + +## HTTP client + +<div class="cfgcmd"> + +set system option http-client source-address \<address\> + +Several commands utilize cURL to initiate transfers. Configure the local +source IPv4/IPv6 address used for all cURL operations. + +</div> + +<div class="cfgcmd"> + +set system option http-client source-interface \<interface\> + +Several commands utilize curl to initiate transfers. Configure the local +source interface used for all CURL operations. + +</div> + +<div class="note"> + +<div class="title"> + +Note + +</div> + +<span class="title-ref">source-address</span> and <span class="title-ref">source-interface</span> can not be used at the same +time. + +</div> + +## SSH client + +<div class="cfgcmd"> + +set system option ssh-client source-address \<address\> + +Use the specified address on the local machine as the source address of the +connection. Only useful on systems with more than one address. + +</div> + +<div class="cfgcmd"> + +set system option ssh-client source-interface \<interface\> + +Use the address of the specified interface on the local machine as the +source address of the connection. + +</div> + +## 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. + +<div class="cfgcmd"> + +set system option keyboard-layout \<us | fr | de | fi | no | dk\> + +Change system keyboard layout to given language. + +Defaults to `us`. + +<div class="note"> + +<div class="title"> + +Note + +</div> + +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. + +</div> + +</div> + +## Performance + +As more and more routers run on Hypervisors, expecially with a `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 <span class="title-ref">tuned</span> for dynamic resource balancing based on profiles. + +<div class="seealso"> + +<https://access.redhat.com/sites/default/files/attachments/201501-perf-brief-low-latency-tuning-rhel7-v2.1.pdf> + +</div> + +<div class="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. + +</div> diff --git a/docs/configuration/system/md-proxy.md b/docs/configuration/system/md-proxy.md new file mode 100644 index 00000000..911392ad --- /dev/null +++ b/docs/configuration/system/md-proxy.md @@ -0,0 +1,40 @@ +# 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 `add system image` command (`update_vyos`). + +<div class="cfgcmd"> + +set system proxy url \<url\> + +Set proxy for all connections initiated by VyOS, including HTTP, HTTPS, and +FTP (anonymous ftp). + +</div> + +<div class="cfgcmd"> + +set system proxy port \<port\> + +Configure proxy port if it does not listen to the default port 80. + +</div> + +<div class="cfgcmd"> + +set system proxy username \<username\> + +Some proxys require/support the "basic" HTTP authentication scheme as per +`7617`, thus a username can be configured. + +</div> + +<div class="cfgcmd"> + +set system proxy password \<password\> + +Some proxys require/support the "basic" HTTP authentication scheme as per +`7617`, thus a password can be configured. + +</div> diff --git a/docs/configuration/system/md-sflow.md b/docs/configuration/system/md-sflow.md new file mode 100644 index 00000000..b64de63f --- /dev/null +++ b/docs/configuration/system/md-sflow.md @@ -0,0 +1,81 @@ +# 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 + +<div class="cfgcmd"> + +set system sflow agent-address \<address\> + +Configure sFlow agent IPv4 or IPv6 address + +</div> + +<div class="cfgcmd"> + +set system sflow agent-interface \<interface\> + +Configure agent IP address associated with this interface. + +</div> + +<div class="cfgcmd"> + +set system sflow drop-monitor-limit \<limit\> + +Dropped packets reported on DROPMON Netlink channel by Linux kernel are exported via the standard sFlow v5 extension for reporting dropped packets + +</div> + +<div class="cfgcmd"> + +set system sflow interface \<interface\> + +Configure and enable collection of flow information for the interface identified by \<interface\>. + +You can configure multiple interfaces which whould participate in sflow accounting. + +</div> + +<div class="cfgcmd"> + +set system sflow polling \<sec\> + +Configure schedule counter-polling in seconds (default: 30) + +</div> + +<div class="cfgcmd"> + +set system sflow sampling-rate \<rate\> + +Use this command to configure the sampling rate for sFlow accounting (default: 1000) + +</div> + +<div class="cfgcmd"> + +set system sflow server \<address\> port \<port\> + +Configure address of sFlow collector. sFlow server at \<address\> can be both listening on an IPv4 or IPv6 address. + +</div> + +## Example + +``` none +set system sflow agent-address '192.0.2.14' +set system sflow agent-interface 'eth0' +set system sflow drop-monitor-limit '50' +set system sflow interface 'eth0' +set system sflow interface 'eth1' +set system sflow polling '30' +set system sflow sampling-rate '1000' +set system sflow server 192.0.2.1 port '6343' +set system sflow server 203.0.113.23 port '6343' +``` diff --git a/docs/configuration/system/md-sysctl.md b/docs/configuration/system/md-sysctl.md new file mode 100644 index 00000000..2786ceea --- /dev/null +++ b/docs/configuration/system/md-sysctl.md @@ -0,0 +1,12 @@ +# 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/. + +<div class="cfgcmd"> + +set system sysctl parameter \<parameter\> value \<value\> + +</div> diff --git a/docs/configuration/system/md-syslog.md b/docs/configuration/system/md-syslog.md new file mode 100644 index 00000000..fc4d5eef --- /dev/null +++ b/docs/configuration/system/md-syslog.md @@ -0,0 +1,606 @@ +# 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 +<span class="title-ref">local7</span> 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 `IP (Internet Protocol)` UDP/TCP. + +### Console + +<div class="cfgcmd"> + +set system syslog console facility \<keyword\> level \<keyword\> + +Log syslog messages to `/dev/console`, for an explanation on +`syslog_facilities` keywords and `syslog_severity_level` keywords +see tables below. + +</div> + +### Custom File + +<div class="cfgcmd"> + +set system syslog file \<filename\> facility \<keyword\> level \<keyword\> + +Log syslog messages to file specified via <span class="title-ref">\<filename\></span>, for an explanation on +`syslog_facilities` keywords and `syslog_severity_level` keywords +see tables below. + +</div> + +<div class="cfgcmd"> + +set system syslog file \<filename\> archive size \<size\> + +Syslog will write <span class="title-ref">\<size\></span> kilobytes into the file specified by <span class="title-ref">\<filename\></span>. +After this limit has been reached, the custom file is "rotated" by logrotate +and a new custom file is created. + +</div> + +<div class="cfgcmd"> + +set system syslog file \<filename\> archive file \<number\> + +Syslog uses logrotate to rotate logiles after a number of gives bytes. +We keep as many as <span class="title-ref">\<number\></span> rotated file before they are deleted on the +system. + +</div> + +### 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. + +<div class="cfgcmd"> + +set system syslog host \<address\> facility \<keyword\> level \<keyword\> + +Log syslog messages to remote host specified by <span class="title-ref">\<address\></span>. The address +can be specified by either FQDN or IP address. For an explanation on +`syslog_facilities` keywords and `syslog_severity_level` +keywords see tables below. + +</div> + +<div class="cfgcmd"> + +set system syslog host \<address\> facility \<keyword\> protocol +\<udp|tcp\> + +Configure protocol used for communication to remote syslog host. This can be +either UDP or TCP. + +</div> + +<div class="cfgcmd"> + +set system syslog vrf \<name\> + +Specify name of the `VRF (Virtual Routing and Forwarding)` instance. + +</div> + +#### `TLS (Transport Layer Security)`-encrypted remote logging + +VyOS supports `TLS (Transport Layer Security)`-encrypted remote logging +over TCP to ensure secure transmission of syslog data to remote syslog servers. + +**Prerequisites**: Before configuring `TLS (Transport Layer +Security)`-encrypted remote logging, ensure you have: + +- A valid remote syslog server address. + +- Valid `CA (Certificate Authority)` and client certificates uploaded + to the local `PKI (Public Key Infrastructure)` storage. + +- The **remote syslog transport protocol** is set to **TCP**: + + ``` none + set system syslog remote <address> protocol tcp + ``` + +<div class="note"> + +<div class="title"> + +Note + +</div> + +`TLS (Transport Layer Security)`-encrypted remote logging is +**not supported** over **UDP**. + +</div> + +<div class="cfgcmd"> + +set system syslog remote \<address\> tls + +Enable TLS-encrypted remote logging. + +</div> + +<div class="cfgcmd"> + +set system syslog remote \<address\> tls ca-certificate \<ca_name\> + +**Configure the** `CA (Certificate Authority)` **certificate.** + +The syslog client uses the `CA (Certificate Authority)` certificate to +verify the identity of the remote syslog server. + +The `CA (Certificate Authority)` certificate is required for **all** +authentication modes except `anon`. + +</div> + +<div class="cfgcmd"> + +set system syslog remote \<address\> tls certificate \<cert_name\> + +**Configure the client certificate.** + +The remote syslog server uses the client certificate to verify the identity +of the syslog client. + +The client certificate is required if the remote syslog server enforces +client certificate verification. + +</div> + +<div class="cfgcmd"> + +set system syslog remote \<address\> tls auth-mode \<anon | fingerprint +| certvalid | name\> + +**Configure the authentication mode.** + +The authentication mode defines how the syslog client verifies the syslog +server's identity. + +The following authentication modes are available: + +- `anon` **(default)**: Allows encrypted connections without verifying the syslog + server's identity. This mode is **not recommended**, as it is vulnerable to + `MITM (Man-in-the-Middle)` attacks. + +- `fingerprint`: Verifies the server’s certificate fingerprint against the + value preconfigured with: + + ``` none + set system syslog remote <address> tls permitted-peer <peer> + ``` + +- `certvalid`: Verifies the server certificate is signed by a trusted + `CA (Certificate Authority)`, skipping `CN (Common Name)` check. + +- `name`: Verifies that: + + - The server’s certificate is signed by a trusted `CA (Certificate + Authority)`. + - The `CN (Common Name)` in the certificate matches the value + preconfigured with: + + ``` none + set system syslog remote <address> tls permitted-peer <peer> + ``` + + This is a **recommended** secure mode for production environments. + +</div> + +<div class="cfgcmd"> + +set system syslog remote \<address\> tls permitted-peer \<peer\> + +**Configure the peer certificate identifiers.** + +The certificate identifier format depends on the authentication mode: + +- `fingerprint`: Enter the expected certificate fingerprints (SHA-1 or + SHA-256). +- `name`: Enter the expected certificate `CNs (Common Names)`. + +For `anon` and `certvalid` authentication modes, certificate identifiers +are not required. + +</div> + +#### 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 + `PKI system </configuration/pki/index>`. + +### Local User Account + +<div class="cfgcmd"> + +set system syslog user \<username\> facility \<keyword\> level \<keyword\> + +If logging to a local user account is configured, all defined log messages +are display on the console if the local user is logged in, if the user is not +logged in, no messages are being displayed. For an explanation on +`syslog_facilities` keywords and `syslog_severity_level` keywords +see tables below. + +</div> + +## 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: + +<table style="width:99%;"> +<colgroup> +<col style="width: 14%" /> +<col style="width: 14%" /> +<col style="width: 69%" /> +</colgroup> +<thead> +<tr> +<th>Facility +Code</th> +<th>Keyword</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td></td> +<td>all</td> +<td>All facilities</td> +</tr> +<tr> +<td>0</td> +<td>kern</td> +<td>Kernel messages</td> +</tr> +<tr> +<td>1</td> +<td>user</td> +<td>User-level messages</td> +</tr> +<tr> +<td>2</td> +<td>mail</td> +<td>Mail system</td> +</tr> +<tr> +<td>3</td> +<td>daemon</td> +<td>System daemons</td> +</tr> +<tr> +<td>4</td> +<td>auth</td> +<td>Security/authentication messages</td> +</tr> +<tr> +<td>5</td> +<td>syslog</td> +<td>Messages generated internally by syslogd</td> +</tr> +<tr> +<td>6</td> +<td>lpr</td> +<td>Line printer subsystem</td> +</tr> +<tr> +<td>7</td> +<td>news</td> +<td>Network news subsystem</td> +</tr> +<tr> +<td>8</td> +<td>uucp</td> +<td>UUCP subsystem</td> +</tr> +<tr> +<td>9</td> +<td>cron</td> +<td>Clock daemon</td> +</tr> +<tr> +<td>10</td> +<td>security</td> +<td>Security/authentication messages</td> +</tr> +<tr> +<td>11</td> +<td>ftp</td> +<td>FTP daemon</td> +</tr> +<tr> +<td>12</td> +<td>ntp</td> +<td>NTP subsystem</td> +</tr> +<tr> +<td>13</td> +<td>logaudit</td> +<td>Log audit</td> +</tr> +<tr> +<td>14</td> +<td>logalert</td> +<td>Log alert</td> +</tr> +<tr> +<td>15</td> +<td>clock</td> +<td>clock daemon (note 2)</td> +</tr> +<tr> +<td>16</td> +<td>local0</td> +<td>local use 0 (local0)</td> +</tr> +<tr> +<td>17</td> +<td>local1</td> +<td>local use 1 (local1)</td> +</tr> +<tr> +<td>18</td> +<td>local2</td> +<td>local use 2 (local2)</td> +</tr> +<tr> +<td>19</td> +<td>local3</td> +<td>local use 3 (local3)</td> +</tr> +<tr> +<td>20</td> +<td>local4</td> +<td>local use 4 (local4)</td> +</tr> +<tr> +<td>21</td> +<td>local5</td> +<td>local use 5 (local5)</td> +</tr> +<tr> +<td>22</td> +<td>local6</td> +<td><blockquote> +<p>use 6 (local6)</p> +</blockquote></td> +</tr> +<tr> +<td>23</td> +<td>local7</td> +<td>local use 7 (local7)</td> +</tr> +</tbody> +</table> + +## Severity Level + +<table style="width:98%;"> +<colgroup> +<col style="width: 10%" /> +<col style="width: 20%" /> +<col style="width: 12%" /> +<col style="width: 55%" /> +</colgroup> +<thead> +<tr> +<th>Value</th> +<th>Severity</th> +<th>Keyword</th> +<th>Description</th> +</tr> +</thead> +<tbody> +<tr> +<td></td> +<td></td> +<td>all</td> +<td>Log everything</td> +</tr> +<tr> +<td>0</td> +<td>Emergency</td> +<td>emerg</td> +<td>System is unusable - a panic condition</td> +</tr> +<tr> +<td>1</td> +<td>Alert</td> +<td>alert</td> +<td>Action must be taken immediately - A +condition that should be corrected +immediately, such as a corrupted system +database.</td> +</tr> +<tr> +<td>2</td> +<td>Critical</td> +<td>crit</td> +<td>Critical conditions - e.g. hard drive +errors.</td> +</tr> +<tr> +<td>3</td> +<td>Error</td> +<td>err</td> +<td>Error conditions</td> +</tr> +<tr> +<td>4</td> +<td>Warning</td> +<td>warning</td> +<td>Warning conditions</td> +</tr> +<tr> +<td>5</td> +<td>Notice</td> +<td>notice</td> +<td>Normal but significant conditions - +conditions that are not error conditions, +but that may require special handling.</td> +</tr> +<tr> +<td>6</td> +<td>Informational</td> +<td>info</td> +<td>Informational messages</td> +</tr> +<tr> +<td>7</td> +<td>Debug</td> +<td>debug</td> +<td>Debug-level messages - Messages that +contain information normally of use only +when debugging a program.</td> +</tr> +</tbody> +</table> + +## Display Logs + +<div class="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 + +</div> + +If no option is specified, this defaults to <span class="title-ref">all</span>. + +<div class="opcmd"> + +show log image \<name\> +\[all | authorization | directory | file \<file name\> | tail \<lines\>\] + +Log messages from a specified image can be displayed on the console. Details +of allowed parameters: + +<table> +<colgroup> +<col style="width: 25%" /> +<col style="width: 75%" /> +</colgroup> +<tbody> +<tr> +<td>all</td> +<td>Display contents of all master log files of the specified image</td> +</tr> +<tr> +<td>authorization</td> +<td>Display all authorization attempts of the specified image</td> +</tr> +<tr> +<td>directory</td> +<td>Display list of all user-defined log files of the specified image</td> +</tr> +<tr> +<td>file <file name></td> +<td>Display contents of a specified user-defined log file of the specified +image</td> +</tr> +<tr> +<td>tail</td> +<td>Display last lines of the system log of the specified image</td> +</tr> +<tr> +<td><lines></td> +<td>Number of lines to be displayed, default 10</td> +</tr> +</tbody> +</table> + +</div> + +When no options/parameters are used, the contents of the main syslog file are +displayed. + +<div class="hint"> + +<div class="title"> + +Hint + +</div> + +Use `show log | strip-private` if you want to hide private data +when sharing your logs. + +</div> + +## Delete Logs + +<div class="opcmd"> + +delete log file \<text\> + +</div> + +Deletes the specified user-defined file \<text\> 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 `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 new file mode 100644 index 00000000..9a43b430 --- /dev/null +++ b/docs/configuration/system/md-task-scheduler.md @@ -0,0 +1,70 @@ +# Task Scheduler + +The task scheduler allows you to execute tasks on a given schedule. It makes +use of UNIX [cron](https://en.wikipedia.org/wiki/Cron). + +<div class="note"> + +<div class="title"> + +Note + +</div> + +All scripts excecuted this way are executed as root user - this may +be dangerous. Together with `command-scripting` this can be used for +automating (re-)configuration. + +</div> + +<div class="cfgcmd"> + +set system task-scheduler task \<task\> interval \<interval\> + +Specify the time interval when <span class="title-ref">\<task\></span> 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 + +<div class="note"> + +<div class="title"> + +Note + +</div> + +If suffix is omitted, minutes are implied. + +</div> + +</div> + +<div class="cfgcmd"> + +set system task-scheduler task \<task\> crontab-spec \<spec\> + +Set execution time in common [cron](https://en.wikipedia.org/wiki/Cron) time format. A cron <span class="title-ref">\<spec\></span> of +`30 */6 * * *` would execute the <span class="title-ref">\<task\></span> at minute 30 past every 6th hour. + +</div> + +<div class="cfgcmd"> + +set system task-scheduler task \<task\> executable path \<path\> + +Specify absolute <span class="title-ref">\<path\></span> to script which will be run when <span class="title-ref">\<task\></span> is +executed. + +</div> + +<div class="cfgcmd"> + +set system task-scheduler task \<task\> executable arguments \<args\> + +Arguments which will be passed to the executable. + +</div> diff --git a/docs/configuration/system/md-time-zone.md b/docs/configuration/system/md-time-zone.md new file mode 100644 index 00000000..20f24b41 --- /dev/null +++ b/docs/configuration/system/md-time-zone.md @@ -0,0 +1,18 @@ +# 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. + +<div class="cfgcmd"> + +set system time-zone \<timezone\> + +Specify the systems <span class="title-ref">\<timezone\></span> 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. + +</div> diff --git a/docs/configuration/system/md-updates.md b/docs/configuration/system/md-updates.md new file mode 100644 index 00000000..4e0460ac --- /dev/null +++ b/docs/configuration/system/md-updates.md @@ -0,0 +1,39 @@ +# Updates + +VyOS supports online checking for updates + +## Configuration + +<div class="cfgcmd"> + +set system update-check auto-check + +Configure auto-checking for new images + +</div> + +<div class="cfgcmd"> + +set system update-check url \<url\> + +Configure a URL that contains information about images. + +</div> + +## 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:~$ +``` |