From 22e34ce5aee24d2fd11f8205522ab7ecdb3c4c5e Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 14:41:08 +0300 Subject: Add incremental RST-to-MyST swap mechanism (sagitta) (#1868) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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> --- docs/configuration/system/md-acceleration.md | 168 +++++++ docs/configuration/system/md-conntrack.md | 473 ++++++++++++++++++ docs/configuration/system/md-console.md | 59 +++ docs/configuration/system/md-default-route.md | 48 ++ docs/configuration/system/md-flow-accounting.md | 312 ++++++++++++ docs/configuration/system/md-frr.md | 50 ++ docs/configuration/system/md-host-name.md | 86 ++++ docs/configuration/system/md-index.md | 31 ++ docs/configuration/system/md-ip.md | 132 ++++++ docs/configuration/system/md-ipv6.md | 278 +++++++++++ docs/configuration/system/md-lcd.md | 52 ++ docs/configuration/system/md-login.md | 549 +++++++++++++++++++++ docs/configuration/system/md-name-server.md | 81 ++++ docs/configuration/system/md-option.md | 262 ++++++++++ docs/configuration/system/md-proxy.md | 40 ++ docs/configuration/system/md-sflow.md | 81 ++++ docs/configuration/system/md-sysctl.md | 12 + docs/configuration/system/md-syslog.md | 606 ++++++++++++++++++++++++ docs/configuration/system/md-task-scheduler.md | 70 +++ docs/configuration/system/md-time-zone.md | 18 + docs/configuration/system/md-updates.md | 39 ++ 21 files changed, 3447 insertions(+) create mode 100644 docs/configuration/system/md-acceleration.md create mode 100644 docs/configuration/system/md-conntrack.md create mode 100644 docs/configuration/system/md-console.md create mode 100644 docs/configuration/system/md-default-route.md create mode 100644 docs/configuration/system/md-flow-accounting.md create mode 100644 docs/configuration/system/md-frr.md create mode 100644 docs/configuration/system/md-host-name.md create mode 100644 docs/configuration/system/md-index.md create mode 100644 docs/configuration/system/md-ip.md create mode 100644 docs/configuration/system/md-ipv6.md create mode 100644 docs/configuration/system/md-lcd.md create mode 100644 docs/configuration/system/md-login.md create mode 100644 docs/configuration/system/md-name-server.md create mode 100644 docs/configuration/system/md-option.md create mode 100644 docs/configuration/system/md-proxy.md create mode 100644 docs/configuration/system/md-sflow.md create mode 100644 docs/configuration/system/md-sysctl.md create mode 100644 docs/configuration/system/md-syslog.md create mode 100644 docs/configuration/system/md-task-scheduler.md create mode 100644 docs/configuration/system/md-time-zone.md create mode 100644 docs/configuration/system/md-updates.md (limited to 'docs/configuration/system') 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 + +
+ +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 ``\` + +
+ +
+ +set system acceleration qat + +if there is a supported device, enable Intel® QAT + +
+ +
+ +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 +``` + +
+ +### Operation Mode + +
+ +show system acceleration qat device \ config + +Show the full config uploaded to the QAT device. + +
+ +
+ +show system acceleration qat device \ flows + +Get an overview over the encryption counters. + +
+ +
+ +show system acceleration qat interrupts + +Show binded qat device interrupts to certain core. + +
+ +### Example + +Let's build a simple VPN between 2 Intel® QAT ready devices. + +Side A: + +``` +set interfaces vti vti1 address '192.168.1.2/24' +set vpn ipsec authentication psk right id '10.10.10.2' +set vpn ipsec authentication psk right id '10.10.10.1' +set vpn ipsec authentication psk right secret 'Qwerty123' +set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes256' +set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha256' +set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '14' +set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes256' +set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha256' +set vpn ipsec interface 'eth0' +set vpn ipsec site-to-site peer right authentication local-id '10.10.10.2' +set vpn ipsec site-to-site peer right authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer right authentication remote-id '10.10.10.1' +set vpn ipsec site-to-site peer right connection-type 'initiate' +set vpn ipsec site-to-site peer right default-esp-group 'MyESPGroup' +set vpn ipsec site-to-site peer right ike-group 'MyIKEGroup' +set vpn ipsec site-to-site peer right local-address '10.10.10.2' +set vpn ipsec site-to-site peer right remote-address '10.10.10.1' +set vpn ipsec site-to-site peer right vti bind 'vti1' +``` + +Side B: + +``` +set interfaces vti vti1 address '192.168.1.1/24' +set vpn ipsec authentication psk left id '10.10.10.2' +set vpn ipsec authentication psk left id '10.10.10.1' +set vpn ipsec authentication psk left secret 'Qwerty123' +set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes256' +set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha256' +set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '14' +set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes256' +set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha256' +set vpn ipsec interface 'eth0' +set vpn ipsec site-to-site peer left authentication local-id '10.10.10.1' +set vpn ipsec site-to-site peer left authentication mode 'pre-shared-secret' +set vpn ipsec site-to-site peer left authentication remote-id '10.10.10.2' +set vpn ipsec site-to-site peer left connection-type 'initiate' +set vpn ipsec site-to-site peer left default-esp-group 'MyESPGroup' +set vpn ipsec site-to-site peer left ike-group 'MyIKEGroup' +set vpn ipsec site-to-site peer left local-address '10.10.10.1' +set vpn ipsec site-to-site peer left remote-address '10.10.10.2' +set vpn ipsec site-to-site peer left vti bind 'vti1' +``` + +a bandwidth test over the VPN got these results: + +``` +Connecting to host 192.168.1.2, port 5201 +[ 9] local 192.168.1.1 port 51344 connected to 192.168.1.2 port 5201 +[ ID] Interval Transfer Bitrate Retr Cwnd +[ 9] 0.00-1.01 sec 32.3 MBytes 268 Mbits/sec 0 196 KBytes +[ 9] 1.01-2.03 sec 32.5 MBytes 268 Mbits/sec 0 208 KBytes +[ 9] 2.03-3.03 sec 32.5 MBytes 271 Mbits/sec 0 208 KBytes +[ 9] 3.03-4.04 sec 32.5 MBytes 272 Mbits/sec 0 208 KBytes +[ 9] 4.04-5.00 sec 31.2 MBytes 272 Mbits/sec 0 208 KBytes +[ 9] 5.00-6.01 sec 32.5 MBytes 272 Mbits/sec 0 234 KBytes +[ 9] 6.01-7.04 sec 32.5 MBytes 265 Mbits/sec 0 234 KBytes +[ 9] 7.04-8.04 sec 32.5 MBytes 272 Mbits/sec 0 234 KBytes +[ 9] 8.04-9.04 sec 32.5 MBytes 273 Mbits/sec 0 336 KBytes +[ 9] 9.04-10.00 sec 31.2 MBytes 272 Mbits/sec 0 336 KBytes +- - - - - - - - - - - - - - - - - - - - - - - - - +[ ID] Interval Transfer Bitrate Retr +[ 9] 0.00-10.00 sec 322 MBytes 270 Mbits/sec 0 sender +[ 9] 0.00-10.00 sec 322 MBytes 270 Mbits/sec receiver +``` + +with `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 + +
+ +set system conntrack table-size \<1-50000000\> + +The connection tracking table contains one entry for each connection being +tracked by the system. + +
+ +
+ +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. + +
+ +
+ +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. + +
+ +
+ +set system conntrack modules ftp + +
+ +
+ +set system conntrack modules h323 + +
+ +
+ +set system conntrack modules nfs + +
+ +
+ +set system conntrack modules pptp + +
+ +
+ +set system conntrack modules sip + +
+ +
+ +set system conntrack modules sqlnet + +
+ +
+ +set system conntrack modules tftp + +Configure the connection tracking protocol helper modules. +All modules are enable by default. + +Use delete system conntrack modules to deactive all modules.\ +Or, for example ftp, delete system conntrack modules ftp. + +
+ +### Define Conection Timeouts + +VyOS supports setting timeouts for connections according to the +connection type. You can set timeout values for generic connections, for ICMP +connections, UDP connections, or for TCP connections in a number of different +states. + +
+ +set system conntrack timeout icmp \<1-21474836\> + +
+ +
+ +set system conntrack timeout other \<1-21474836\> + +
+ +
+ +set system conntrack timeout tcp close \<1-21474836\> + +
+ +
+ +set system conntrack timeout tcp close-wait \<1-21474836\> + +
+ +
+ +set system conntrack timeout tcp established \<1-21474836\> + +
+ +
+ +set system conntrack timeout tcp fin-wait \<1-21474836\> + +
+ +
+ +set system conntrack timeout tcp last-ack \<1-21474836\> + +
+ +
+ +set system conntrack timeout tcp syn-recv \<1-21474836\> + +
+ +
+ +set system conntrack timeout tcp syn-sent \<1-21474836\> + +
+ +
+ +set system conntrack timeout tcp time-wait \<1-21474836\> + +
+ +
+ +set system conntrack timeout udp other \<1-21474836\> + +
+ +
+ +set system conntrack timeout udp stream \<1-21474836\> + +Set the timeout in secounds for a protocol or state. + +
+ +You can also define custom timeout values to apply to a specific subset of +connections, based on a packet and flow selector. To do this, you need to +create a rule defining the packet and flow selector. + +
+ +set system conntrack timeout custom rule \<1-9999\> description \ + +Set a rule description. + +
+ +
+ +set system conntrack timeout custom rule \<1-9999\> destination address \ + +
+ +
+ +set system conntrack timeout custom rule \<1-9999\> source address \ + +set a destination and/or source address. Accepted input: + +``` none + IP address to match + Subnet to match +- + IP range to match +! Match everything except the specified address +! Match everything except the specified subnet +!- + Match everything except the specified range +``` + +
+ +
+ +set system conntrack timeout custom rule \<1-9999\> destination port \ + +
+ +
+ +set system conntrack timeout custom rule \<1-9999\> source port \ + +Set a destination and/or source port. Accepted input: + +``` none + Named port (any name in /etc/services, e.g., http) +<1-65535> Numbered port +- Numbered port range (e.g., 1001-1005) +``` + +Multiple destination ports can be specified as a comma-separated list. +The whole list can also be "negated" using '!'. For example: +!22,telnet,http,123,1001-1005\` + +
+ +
+ +set system conntrack timeout custom rule \<1-9999\> protocol icmp \<1-21474836\> + +
+ +
+ +set system conntrack timeout custom rule \<1-9999\> protocol other \<1-21474836\> + +
+ +
+ +set system conntrack timeout custom rule \<1-9999\> protocol tcp close \<1-21474836\> + +
+ +
+ +set system conntrack timeout custom rule \<1-9999\> protocol tcp close-wait \<1-21474836\> + +
+ +
+ +set system conntrack timeout custom rule \<1-9999\> protocol tcp established \<1-21474836\> + +
+ +
+ +set system conntrack timeout custom rule \<1-9999\> protocol tcp fin-wait \<1-21474836\> + +
+ +
+ +set system conntrack timeout custom rule \<1-9999\> protocol tcp last-ack \<1-21474836\> + +
+ +
+ +set system conntrack timeout custom rule \<1-9999\> protocol tcp syn-recv \<1-21474836\> + +
+ +
+ +set system conntrack timeout custom rule \<1-9999\> protocol tcp syn-sent \<1-21474836\> + +
+ +
+ +set system conntrack timeout custom rule \<1-9999\> protocol tcp time-wait \<1-21474836\> + +
+ +
+ +set system conntrack timeout custom rule \<1-9999\> protocol udp other \<1-21474836\> + +
+ +
+ +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. + +
+ +
+ +set system conntrack tcp half-open-connections \<1-21474836\> + +Set the maximum number of TCP half-open connections. + +
+ +
+ +set system conntrack tcp loose \ + +Policy to track previously established connections. + +
+ +
+ +set system conntrack tcp max-retrans \<1-2147483647\> + +Set the number of TCP maximum retransmit attempts. + +
+ +
+ +set system conntrack ignore rule \<1-9999\> description \ + +
+ +
+ +set system conntrack ignore rule \<1-9999\> destination address \ + +
+ +
+ +set system conntrack ignore rule \<1-9999\> destination port \ + +
+ +
+ +set system conntrack ignore rule \<1-9999\> inbound-interface \ + +
+ +
+ +set system conntrack ignore rule \<1-9999\> protocol \ + +
+ +
+ +set system conntrack ignore rule \<1-9999\> source address \ + +
+ +
+ +set system conntrack ignore rule \<1-9999\> source port \ + +Customized ignore rules, based on a packet and flow selector. + +
+ +
+ +set system conntrack log icmp destroy + +
+ +
+ +set system conntrack log icmp new + +
+ +
+ +set system conntrack log icmp update + +
+ +
+ +set system conntrack log other destroy + +
+ +
+ +set system conntrack log other new + +
+ +
+ +set system conntrack log other update + +
+ +
+ +set system conntrack log tcp destroy + +
+ +
+ +set system conntrack log tcp new + +
+ +
+ +set system conntrack log tcp update close-wait + +
+ +
+ +set system conntrack log tcp update established + +
+ +
+ +set system conntrack log tcp update fin-wait + +
+ +
+ +set system conntrack log tcp update last-ack + +
+ +
+ +set system conntrack log tcp update syn-received + +
+ +
+ +set system conntrack log tcp update time-wait + +
+ +
+ +set system conntrack log udp destroy + +
+ +
+ +set system conntrack log udp new + +
+ +
+ +set system conntrack log udp update + +Log the connection tracking events per protocol. + +
diff --git a/docs/configuration/system/md-console.md b/docs/configuration/system/md-console.md 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. + +
+ +set system console device \ + +Defines the specified device as a system console. Available console devices +can be (see completion helper): + +- `ttySN` - Serial device name +- `ttyUSBX` - USB Serial device name +- `hvc0` - Xen console + +
+ +
+ +set system console device \ speed \ + +The speed (baudrate) of the console device. Supported values are: + +- `1200` - 1200 bps +- `2400` - 2400 bps +- `4800` - 4800 bps +- `9600` - 9600 bps +- `19200` - 19,200 bps +- `38400` - 38,400 bps (default for Xen console) +- `57600` - 57,600 bps +- `115200` - 115,200 bps (default for serial console) + +
+ +
+ +Note + +
+ +If you use USB to serial converters for connecting to your VyOS +appliance please note that most of them use software emulation without flow +control. This means you should start with a common baud rate (most likely +9600 baud) as otherwise you probably can not connect to the device using +high speed baud rates as your serial converter simply can not process this +data rate. + +
+ +
diff --git a/docs/configuration/system/md-default-route.md b/docs/configuration/system/md-default-route.md 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
`), this is no longer supported +and existing configurations are migrated to the new CLI command. + +## Configuration + +
+ +set protocols static route 0.0.0.0/0 next-hop \ + +Specify static route into the routing table sending all non local traffic +to the nexthop address \. + +
+ +
+ +delete protocols static route 0.0.0.0/0 + +Delete default route from the system. + +
+ +## Operation + +
+ +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 +``` + +
+ +
+ +Configuration of `routing-static` + +
diff --git a/docs/configuration/system/md-flow-accounting.md b/docs/configuration/system/md-flow-accounting.md new file mode 100644 index 00000000..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. + +
+ +
+ +Warning + +
+ +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. + +
+ +## NetFlow / IPFIX + +NetFlow is a feature that was introduced on Cisco routers around 1996 that +provides the ability to collect IP network traffic as it enters or exits an +interface. By analyzing the data provided by NetFlow, a network administrator +can determine things such as the source and destination of traffic, class of +service, and the causes of congestion. A typical flow monitoring setup (using +NetFlow) consists of three main components: + +- **exporter**: aggregates packets into flows and exports flow records towards + one or more flow collectors +- **collector**: responsible for reception, storage and pre-processing of flow + data received from a flow exporter +- **application**: analyzes received flow data in the context of intrusion + detection or traffic profiling, for example + +For connectionless protocols as like ICMP and UDP, a flow is considered +complete once no more packets for this flow appear after configurable timeout. + +NetFlow is usually enabled on a per-interface basis to limit load on the router +components involved in NetFlow, or to limit the amount of NetFlow records +exported. + +## Configuration + +
+ +
+ +Warning + +
+ +Using NetFlow on routers with high traffic levels may lead to +high CPU usage and may affect the router's performance. In such cases, +consider using sFlow instead. + +
+ +In order for flow accounting information to be collected and displayed for an +interface, the interface must be configured for flow accounting. + +
+ +set system flow-accounting interface \ + +Configure and enable collection of flow information for the interface +identified by \. + +You can configure multiple interfaces which whould participate in flow +accounting. + +
+ +
+ +
+ +Note + +
+ +Will be recorded only packets/flows on **incoming** direction in +configured interfaces by default. + +
+ +By default, recorded flows will be saved internally and can be listed with the +CLI command. You may disable using the local in-memory table with the command: + +
+ +set system flow-accounting disable-imt + +If you need to sample also egress traffic, you may want to +configure egress flow-accounting: + +
+ +
+ +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: + +
+ +
+ +set system flow-accounting buffer-size \ + +In case, if you need to catch some logs from flow-accounting daemon, you may +configure logging facility: + +
+ +
+ +set system flow-accounting syslog-facility \ + +TBD + +
+ +### Flow Export + +In addition to displaying flow accounting information locally, one can also +exported them to a collection server. + +#### NetFlow + +
+ +set system flow-accounting netflow version \ + +There are multiple versions available for the NetFlow data. The \ +used in the exported flow data can be configured here. The following +versions are supported: + +- **5** - Most common version, but restricted to IPv4 flows only +- **9** - NetFlow version 9 (default) +- **10** - `IPFIX (IP Flow Information Export)` as per `3917` + +
+ +
+ +set system flow-accounting netflow server \ + +Configure address of NetFlow collector. NetFlow server at \ can +be both listening on an IPv4 or IPv6 address. + +
+ +
+ +set system flow-accounting netflow source-ip \ + +IPv4 or IPv6 source address of NetFlow packets + +
+ +
+ +set system flow-accounting netflow engine-id \ + +NetFlow engine-id which will appear in NetFlow data. The range is 0 to 255. + +
+ +
+ +set system flow-accounting netflow sampling-rate \ + +Use this command to configure the sampling rate for flow accounting. The +system samples one in every \ packets, where \ is the value +configured for the sampling-rate option. The advantage of sampling every n +packets, where n \> 1, allows you to decrease the amount of processing +resources required for flow accounting. The disadvantage of not sampling +every packet is that the statistics produced are estimates of actual data +flows. + +Per default every packet is sampled (that is, the sampling rate is 1). + +
+ +
+ +set system flow-accounting netflow timeout expiry-interval +\ + +Specifies the interval at which Netflow data will be sent to a collector. As +per default, Netflow data will be sent every 60 seconds. + +You may also additionally configure timeouts for different types of +connections. + +
+ +
+ +set system flow-accounting netflow max-flows \ + +If you want to change the maximum number of flows, which are tracking +simultaneously, you may do this with this command (default 8192). + +
+ +#### sFlow + +
+ +
+ +Note + +
+ +Using system sflow is recommended in favor of +system flow-accounting. See [sflow](sflow.html) + +
+ +
+ +set system flow-accounting sflow server \ + +Configure address of sFlow collector. sFlow server at \ can +be an IPv4 or IPv6 address. But you cannot export to both IPv4 and +IPv6 collectors at the same time! + +
+ +
+ +set system flow-accounting sflow sampling-rate \ + +Enable sampling of packets, which will be transmitted to sFlow collectors. + +
+ +
+ +set system flow-accounting sflow agent-address \ + +Configure a sFlow agent address. It can be IPv4 or IPv6 address, but you +must set the same protocol, which is used for sFlow collector addresses. By +default, using router-id from BGP or OSPF protocol, or the primary IP +address from the first interface. + +
+ +### Example: + +NetFlow v5 example: + +``` none +set system flow-accounting netflow engine-id 100 +set system flow-accounting netflow version 5 +set system flow-accounting netflow server 192.168.2.10 port 2055 +``` + +## Operation + +Once flow accounting is configured on an interfaces it provides the ability to +display captured network traffic information for all configured interfaces. + +
+ +show flow-accounting interface \ + +Show flow accounting information for given \. + +``` 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 +``` + +
+ +
+ +show flow-accounting interface \ host \ + +Show flow accounting information for given \ 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 +``` + +
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\]() 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. + +
+ +set system frr bmp + +Enable `BMP (BGP Monitoring Protocol)` support + +
+ +
+ +set system frr descriptors \ + +This allows the operator to control the number of open file descriptors +each daemon is allowed to start with. If the operator plans to run bgp with +several thousands of peers then this is where we would modify FRR to allow +this to happen. + +
+ +
+ +set system frr irdp + +Enable ICMP Router Discovery Protocol support + +
+ +
+ +set system frr snmp \ + +Enable SNMP support for an individual routing daemon. + +Supported daemons: + +- bgpd +- isisd +- ldpd +- ospf6d +- ospfd +- ripd +- zebra + +
diff --git a/docs/configuration/system/md-host-name.md b/docs/configuration/system/md-host-name.md 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. + +
+ +set system host-name \ + +The hostname can be up to 63 characters. A hostname +must start and end with a letter or digit, and have as interior characters +only letters, digits, or a hyphen. + +The default hostname used is vyos. + +
+ +## Domain Name + +A domain name is the label (name) assigned to a computer network and is thus +unique. VyOS appends the domain name as a suffix to any unqualified name. For +example, if you set the domain name example.com, and you would ping the +unqualified name of crux, then VyOS qualifies the name to crux.example.com. + +
+ +set system domain-name \ + +Configure system domain name. A domain name must start and end with a letter +or digit, and have as interior characters only letters, digits, or a hyphen. + +
+ +## Static Hostname Mapping + +How an IP address is assigned to an interface in `ethernet-interface`. +This section shows how to statically map an IP address to a hostname for local +(meaning on this VyOS instance) name resolution. This is the VyOS equivalent to +/etc/hosts file entries. + +
+ +
+ +Note + +
+ +Do *not* manually edit /etc/hosts. This file will automatically be +regenerated on boot based on the settings in this section, which means you'll +lose all your manual edits. Instead, configure static host mappings as follows. + +
+ +
+ +set system static-host-mapping host-name \ inet \ + +Create a static hostname mapping which will always resolve the name +\ to IP address \. + +
+ +
+ +set system static-host-mapping host-name \ alias \ + +Create named \ for the configured static mapping for \. +Thus the address configured as `set system static-host-mapping +host-name inet
` can be reached via multiple names. + +Multiple aliases can be specified per host-name. + +
diff --git a/docs/configuration/system/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 + +
+ +acceleration +conntrack +console +flow-accounting +frr +host-name +ip +ipv6 +lcd +login +name-server +option +proxy +sflow +syslog +sysctl +task-scheduler +time-zone +updates + +
+ +
+ +default-route + +
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 + +
+ +set system ip disable-forwarding + +Use this command to disable IPv4 forwarding on all interfaces. + +
+ +
+ +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. + +
+ +
+ +set system ip arp table-size \ + +Use this command to define the maximum number of entries to keep in +the ARP cache (1024, 2048, 4096, 8192, 16384, 32768). + +
+ +
+ +set system ip multipath layer4-hashing + +Use this command to use Layer 4 information for IPv4 ECMP hashing. + +
+ +### Zebra/Kernel route filtering + +Zebra supports prefix-lists and Route Mapss to match routes received from +other FRR components. The permit/deny facilities provided by these commands +can be used to filter which routes zebra will install in the kernel. + +
+ +set system ip protocol \ route-map \ + +Apply a route-map filter to routes for the specified protocol. The following +protocols can be used: any, babel, bgp, connected, eigrp, isis, kernel, +ospf, rip, static, table + +
+ +
+ +Note + +
+ +If you choose any as the option that will cause all protocols that +are sending routes to zebra. + +
+ +
+ +### Nexthop Tracking + +Nexthop tracking resolve nexthops via the default route by default. This is enabled +by default for a traditional profile of FRR which we use. It and can be disabled if +you do not wan't to e.g. allow BGP to peer across the default route. + +
+ +set system ip nht no-resolve-via-default + +Do not allow IPv4 nexthop tracking to resolve via the default route. This +parameter is configured per-VRF, so the command is also available in the VRF +subnode. + +
+ +## Operational commands + +### show commands + +See below the different parameters available for the IPv4 **show** command: + +``` none +vyos@vyos:~$ show ip +Possible completions: + access-list Show all IP access-lists + as-path-access-list + Show all as-path-access-lists + bgp Show Border Gateway Protocol (BGP) information + community-list + Show IP community-lists + extcommunity-list + Show extended IP community-lists + forwarding Show IP forwarding status + groups Show IP multicast group membership + igmp Show IGMP (Internet Group Management Protocol) information + large-community-list + Show IP large-community-lists + multicast Show IP multicast + ospf Show IPv4 Open Shortest Path First (OSPF) routing information + pim Show PIM (Protocol Independent Multicast) information + ports Show IP ports in use by various system services + prefix-list Show all IP prefix-lists + protocol Show IP route-maps per protocol + rip Show Routing Information Protocol (RIP) information + route Show IP routes +``` + +### reset commands + +And the different IPv4 **reset** commands available: + +``` none +vyos@vyos:~$ reset ip +Possible completions: + arp Reset Address Resolution Protocol (ARP) cache + bgp Clear Border Gateway Protocol (BGP) statistics or status + igmp IGMP clear commands + multicast IP multicast routing table + route Reset IP route +``` diff --git a/docs/configuration/system/md-ipv6.md b/docs/configuration/system/md-ipv6.md new file mode 100644 index 00000000..47b775e6 --- /dev/null +++ b/docs/configuration/system/md-ipv6.md @@ -0,0 +1,278 @@ +# IPv6 + +## System configuration commands + +
+ +set system ipv6 disable-forwarding + +Use this command to disable IPv6 forwarding on all interfaces. + +
+ +
+ +set system ipv6 neighbor table-size \ + +Use this command to define the maximum number of entries to keep in +the Neighbor cache (1024, 2048, 4096, 8192, 16384, 32768). + +
+ +
+ +set system ipv6 strict-dad + +Use this command to disable IPv6 operation on interface when +Duplicate Address Detection fails on Link-Local address. + +
+ +
+ +set system ipv6 multipath layer4-hashing + +Use this command to user Layer 4 information for ECMP hashing. + +
+ +### Zebra/Kernel route filtering + +Zebra supports prefix-lists and Route Mapss to match routes received from +other FRR components. The permit/deny facilities provided by these commands +can be used to filter which routes zebra will install in the kernel. + +
+ +set system ipv6 protocol \ route-map \ + +Apply a route-map filter to routes for the specified protocol. The following +protocols can be used: any, babel, bgp, connected, isis, kernel, ospfv3, +ripng, static, table + +
+ +
+ +Note + +
+ +If you choose any as the option that will cause all protocols that +are sending routes to zebra. + +
+ +
+ +### Nexthop Tracking + +Nexthop tracking resolve nexthops via the default route by default. This is enabled +by default for a traditional profile of FRR which we use. It and can be disabled if +you do not wan't to e.g. allow BGP to peer across the default route. + +
+ +set system ipv6 nht no-resolve-via-default + +Do not allow IPv6 nexthop tracking to resolve via the default route. This +parameter is configured per-VRF, so the command is also available in the VRF +subnode. + +
+ +## Operational commands + +### Show commands + +
+ +show ipv6 neighbors + +Use this command to show IPv6 Neighbor Discovery Protocol information. + +
+ +
+ +show ipv6 groups + +Use this command to show IPv6 multicast group membership. + +
+ +
+ +show ipv6 forwarding + +Use this command to show IPv6 forwarding status. + +
+ +
+ +show ipv6 route + +Use this command to show IPv6 routes. + +Check the many parameters available for the show ipv6 route command: + +``` none +vyos@vyos:~$ show ipv6 route +Possible completions: + Execute the current command + Show IPv6 routes of given address or prefix + + bgp Show IPv6 BGP routes + cache Show kernel IPv6 route cache + connected Show IPv6 connected routes + forward Show kernel IPv6 route table + isis Show IPv6 ISIS routes + kernel Show IPv6 kernel routes + ospfv3 Show IPv6 OSPF6 routes + ripng Show IPv6 RIPNG routes + static Show IPv6 static routes + summary Show IPv6 routes summary + table Show IP routes in policy table + vrf Show IPv6 routes in VRF +``` + +
+ +
+ +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: + Execute the current command + Show specified IPv6 prefix-list + detail Show detail of IPv6 prefix-lists + summary Show summary of IPv6 prefix-lists +``` + +
+ +
+ +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: + Execute the current command + Show specified IPv6 access-list +``` + +
+ +
+ +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: + Execute the current command + Show BGP information for given address or prefix + + community Show routes matching the communities + community-list + Show routes matching the community-list + filter-list Show routes conforming to the filter-list + large-community + Show routes matching the large-community-list + large-community-list + neighbors Show detailed information on TCP and BGP neighbor connections + prefix-list Show routes matching the prefix-list + regexp Show routes matching the AS path regular expression + route-map Show BGP routes matching the specified route map + summary Show summary of BGP neighbor status +``` + +
+ +
+ +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: + 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 +``` + +
+ +
+ +show ipv6 ripng + +Use this command to get information about the RIPNG protocol + +
+ +
+ +show ipv6 ripng status + +Use this command to show the status of the RIPNG protocol + +
+ +### Reset commands + +
+ +reset bgp ipv6 \ + +Use this command to clear Border Gateway Protocol statistics or +status. + +
+ +
+ +reset ipv6 neighbors \
+ +Use this command to reset IPv6 Neighbor Discovery Protocol cache for +an address or interface. + +
+ +
+ +reset ipv6 route cache + +Use this command to flush the kernel IPv6 route cache. +An address can be added to flush it only for that route. + +
diff --git a/docs/configuration/system/md-lcd.md b/docs/configuration/system/md-lcd.md 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 +(ttySxx) or serial via USB or even old parallel port interfaces. + +## Configuration + +
+ +set system lcd device \ + +This is the name of the physical interface used to connect to your LCD +display. Tab completion is supported and it will list you all available +serial interface. + +For serial via USB port information please refor to: `hardware_usb`. + +
+ +
+ +set system lcd model \ + +This is the LCD model used in your system. + +At the time of this writing the following displays are supported: + +- Crystalfontz CFA-533 +- Crystalfontz CFA-631 +- Crystalfontz CFA-633 +- Crystalfontz CFA-635 + +
+ +
+ +Note + +
+ +We can't support all displays from the beginning. If your display +type is missing, please create a feature request via [Phabricator](). + +
+ +
diff --git a/docs/configuration/system/md-login.md b/docs/configuration/system/md-login.md new file mode 100644 index 00000000..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 (vyos), as well as newly created user accounts, +have all capabilities to configure the system. All accounts have sudo +capabilities and therefore can operate as root on the system. + +Both local administered and remote administered `RADIUS (Remote +Authentication Dial-In User Service)` accounts are supported. + +## Local + +
+ +set system login user \ full-name "\" + +Create new system user with username \ and real-name specified by +\. + +
+ +
+ +set system login user \ authentication plaintext-password +\ + +Specify the plaintext password user by user \ on this system. The +plaintext password will be automatically transferred into a secure hashed +password and not saved anywhere in plaintext. + +
+ +
+ +set system login user \ authentication encrypted-password +\ + +Setup encrypted password for given username. This is useful for +transferring a hashed password from system to system. + +
+ +
+ +set system login user \ disable + +Disable (lock) account. User will not be able to log in. + +
+ +### 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. + +
+ +SSH `ssh_operation` + +
+ +
+ +set system login user \ authentication public-keys +\ key \ + +Assign the SSH public key portion \ identified by per-key +\ to the local user \. + +
+ +
+ +set system login user \ authentication public-keys +\ type \ + +Every SSH public key portion referenced by \ requires the +configuration of the \ of public-key used. This type can be any of: + +- `ecdsa-sha2-nistp256` +- `ecdsa-sha2-nistp384` +- `ecdsa-sha2-nistp521` +- `ssh-dss` +- `ssh-ed25519` +- `ssh-rsa` + +
+ +
+ +Note + +
+ +You can assign multiple keys to the same user by using a unique +identifier per SSH key. + +
+ +
+ +
+ +set system login user \ authentication public-keys +\ options \ + +Set the options for this public key. See the ssh `authorized_keys` man +page for details of what you can specify here. To place a `"` +character in the options field, use `"`, for example +`from="10.0.0.0/24"` to restrict where the user +may connect from when using this key. + +
+ +### MFA/2FA authentication using OTP (one time passwords) + +It is possible to enhance authentication security by using the `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. + +
+ +set system login user \ authentication otp key \ + +Enable OTP 2FA for user username with default settings, using the BASE32 +encoded 2FA/MFA key specified by \. + +
+ +#### Optional/default settings + +
+ +set system login user \ authentication otp rate-limit \ + +Limit logins to \ per every `rate-time` seconds. Rate limit +must be between 1 and 10 attempts. + +
+ +
+ +set system login user \ authentication otp rate-time \ + +Limit logins to `rate-limit` attemps per every \. Rate time must +be between 15 and 600 seconds. + +
+ +
+ +set system login user \ authentication otp window-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. + +
+ +#### OTP-key generation + +The following command can be used to generate the OTP key as well +as the CLI commands to configure them: + +
+ +generate system login username \ otp-key hotp-time +rate-limit \<1-10\> rate-time \<15-600\> window-size \<1-21\> + +
+ +An example of key generation: + +``` none +vyos@vyos:~$ generate system login username otptester otp-key hotp-time rate-limit 2 rate-time 20 window-size 5 +# You can share it with the user, he just needs to scan the QR in his OTP app +# username: otptester +# OTP KEY: J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY +# OTP URL: otpauth://totp/otptester@vyos?secret=J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY&digits=6&period=30 +█████████████████████████████████████████████ +█████████████████████████████████████████████ +████ ▄▄▄▄▄ █▀█ █▄ ▀▄▀▄█▀▄ ▀█▀ █ ▄▄▄▄▄ ████ +████ █ █ █▀▀▀█ ▄▀ █▄▀ ▀▄ ▄ ▀ ▄█ █ █ ████ +████ █▄▄▄█ █▀ █▀▀██▄▄ █ █ ██ ▀▄▀ █ █▄▄▄█ ████ +████▄▄▄▄▄▄▄█▄▀ ▀▄█ █ ▀ █ █ █ █▄█▄█▄▄▄▄▄▄▄████ +████ ▄ █▄ ▄ ▀▄▀▀▀▀▄▀▄▀▄▄▄▀▀▄▄▄ █ █▄█ █████ +████▄▄ ██▀▄▄▄▀▀█▀ ▄ ▄▄▄ ▄▀ ▀ █ ▄ ▄ ██▄█ ████ +█████▄ ██▄▄▀█▄█▄█▄ ▀█▄▀▄ ▀█▀▄ █▄▄▄ ▄ ▄████ +████▀▀▄ ▄█▀▄▀ ▄█▀█▀▄▄▄▀█▄ ██▄▄▄ ▀█ █ ████ +████ ▄▀▄█▀▄▄█▀▀▄▀▀▀▀█ ▄▀▄▀ ▄█ ▀▄ ▄ ▄▀ █▄████ +████▄ ██ ▀▄▀▀ ▄█▀ ▄ ██ ▀█▄█ ▄█ ▄ ▀▄ ▄▄ ████ +████▄█▀▀▄ ▄▄ █▄█▄█▄ █▄▄▀▄▄▀▀▄▄██▀ ▄▀▄▄ ▀▄████ +████▀▄▀ ▄ ▄▀█ ▄ ▄█▀ █ ▀▄▄ ▄█▀ ▄▄ ▀▄▄ ████ +████ ▀███▄ █▄█▄▀▀▀▀▄ ▄█▄▄▀ ▀███ ▄▄█▄▄ ▄████ +████ ███▀ ▄▄▀▀██▀ ▄▀▄█▄▄▄ ██▄▄▀▄▀ ███▄ ▄████ +████▄████▄▄▄▀▄ █▄█▄▀▄▄▄▄██▀ ▄▀ ▄ ▄▄▄ █▄▄█████ +████ ▄▄▄▄▄ █▄▄▄ ▄█▀█▀▀▀▀█▀█▀ █▄█ █▄█ ▄█ ████ +████ █ █ █ ██▄▀▀▀▀▄▄▄▀ ▄▄▄ ▀ ▄ ▄ ▄▄████ +████ █▄▄▄█ █ ▀▀█▀ ▄▄█ █▄▄██▀▀█▀ █▄▀▄██▄█ ████ +████▄▄▄▄▄▄▄█▄█▄█▄█▄▄▄▄▄█▄▄▄█▄██████▄██▄▄▄████ +█████████████████████████████████████████████ +█████████████████████████████████████████████ +# To add this OTP key to configuration, run the following commands: +set system login user otptester authentication otp key 'J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY' +set system login user otptester authentication otp rate-limit '2' +set system login user otptester authentication otp rate-time '20' +set system login user otptester authentication otp window-size '5' +``` + +#### Display OTP key for user + +To display the configured OTP user key, use the command: + +
+ +sh system login authentication user \ otp +\ + +
+ +An example: + +``` none +vyos@vyos:~$ sh system login authentication user otptester otp full +# You can share it with the user, he just needs to scan the QR in his OTP app +# username: otptester +# OTP KEY: J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY +# OTP URL: otpauth://totp/otptester@vyos?secret=J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY&digits=6&period=30 +█████████████████████████████████████████████ +█████████████████████████████████████████████ +████ ▄▄▄▄▄ █▀█ █▄ ▀▄▀▄█▀▄ ▀█▀ █ ▄▄▄▄▄ ████ +████ █ █ █▀▀▀█ ▄▀ █▄▀ ▀▄ ▄ ▀ ▄█ █ █ ████ +████ █▄▄▄█ █▀ █▀▀██▄▄ █ █ ██ ▀▄▀ █ █▄▄▄█ ████ +████▄▄▄▄▄▄▄█▄▀ ▀▄█ █ ▀ █ █ █ █▄█▄█▄▄▄▄▄▄▄████ +████ ▄ █▄ ▄ ▀▄▀▀▀▀▄▀▄▀▄▄▄▀▀▄▄▄ █ █▄█ █████ +████▄▄ ██▀▄▄▄▀▀█▀ ▄ ▄▄▄ ▄▀ ▀ █ ▄ ▄ ██▄█ ████ +█████▄ ██▄▄▀█▄█▄█▄ ▀█▄▀▄ ▀█▀▄ █▄▄▄ ▄ ▄████ +████▀▀▄ ▄█▀▄▀ ▄█▀█▀▄▄▄▀█▄ ██▄▄▄ ▀█ █ ████ +████ ▄▀▄█▀▄▄█▀▀▄▀▀▀▀█ ▄▀▄▀ ▄█ ▀▄ ▄ ▄▀ █▄████ +████▄ ██ ▀▄▀▀ ▄█▀ ▄ ██ ▀█▄█ ▄█ ▄ ▀▄ ▄▄ ████ +████▄█▀▀▄ ▄▄ █▄█▄█▄ █▄▄▀▄▄▀▀▄▄██▀ ▄▀▄▄ ▀▄████ +████▀▄▀ ▄ ▄▀█ ▄ ▄█▀ █ ▀▄▄ ▄█▀ ▄▄ ▀▄▄ ████ +████ ▀███▄ █▄█▄▀▀▀▀▄ ▄█▄▄▀ ▀███ ▄▄█▄▄ ▄████ +████ ███▀ ▄▄▀▀██▀ ▄▀▄█▄▄▄ ██▄▄▀▄▀ ███▄ ▄████ +████▄████▄▄▄▀▄ █▄█▄▀▄▄▄▄██▀ ▄▀ ▄ ▄▄▄ █▄▄█████ +████ ▄▄▄▄▄ █▄▄▄ ▄█▀█▀▀▀▀█▀█▀ █▄█ █▄█ ▄█ ████ +████ █ █ █ ██▄▀▀▀▀▄▄▄▀ ▄▄▄ ▀ ▄ ▄ ▄▄████ +████ █▄▄▄█ █ ▀▀█▀ ▄▄█ █▄▄██▀▀█▀ █▄▀▄██▄█ ████ +████▄▄▄▄▄▄▄█▄█▄█▄█▄▄▄▄▄█▄▄▄█▄██████▄██▄▄▄████ +█████████████████████████████████████████████ +█████████████████████████████████████████████ +# To add this OTP key to configuration, run the following commands: +set system login user otptester authentication otp key 'J5A64ERPMGJOZXY6FMHHLKXKANNI6TCY' +set system login user otptester authentication otp rate-limit '2' +set system login user otptester authentication otp rate-time '20' +set system login user otptester authentication otp window-size '5' +``` + +Once a user has 2FA/OTP configured against their account, they must login +using their password with the OTP code appended to it. +For example: If the users password is vyosrocks and the OTP code is 817454 +then they would enter their password as vyosrocks817454 + +## RADIUS + +In large deployments it is not reasonable to configure each user individually +on every system. VyOS supports using `RADIUS (Remote Authentication +Dial-In User Service)` servers as backend for user authentication. + +### Configuration + +
+ +set system login radius server \ key \ + +Specify the IP \ of the RADIUS server user with the pre-shared-secret +given in \. + +Multiple servers can be specified. + +
+ +
+ +set system login radius server \ port \ + +Configure the discrete port under which the RADIUS server can be reached. + +This defaults to 1812. + +
+ +
+ +set system login radius server \ disable + +Temporary disable this RADIUS server. It won't be queried. + +
+ +
+ +set system login radius server \ timeout \ + +Setup the \ in seconds when querying the RADIUS server. + +
+ +
+ +set system login radius source-address \ + +RADIUS servers could be hardened by only allowing certain IP addresses to +connect. As of this the source address of each RADIUS query can be +configured. + +If unset, incoming connections to the RADIUS server will use the nearest +interface address pointing towards the server - making it error prone on +e.g. OSPF networks when a link fails and a backup route is taken. + +
+ +
+ +set system login radius vrf \ + +Source all connections to the RADIUS servers from given VRF \. + +
+ +
+ +
+ +Hint + +
+ +If you want to have admin users to authenticate via RADIUS it is +essential to sent the `Cisco-AV-Pair shell:priv-lvl=15` attribute. Without +the attribute you will only get regular, non privilegued, system users. + +
+ +## TACACS+ + +In addition to `RADIUS (Remote Authentication Dial-In User Service)`, +`TACACS (Terminal Access Controller Access Control System)` can also be +found in large deployments. +VyOS only supports Authentication via TACACS+ servers but does not support Authorization or Accounting yet + +TACACS is defined in `8907`. + +### Configuration + +
+ +set system login tacas server \ key \ + +Specify the IP \ of the TACACS server user with the pre-shared-secret +given in \. + +Multiple servers can be specified. + +
+ +
+ +set system login tacas server \ port \ + +Configure the discrete port under which the TACACS server can be reached. + +This defaults to 49. + +
+ +
+ +set system login tacas server \ disable + +Temporary disable this TACACS server. It won't be queried. + +
+ +
+ +set system login tacas server \ timeout \ + +Setup the \ in seconds when querying the TACACS server. + +
+ +
+ +set system login tacas source-address \ + +TACACS servers could be hardened by only allowing certain IP addresses to +connect. As of this the source address of each TACACS query can be +configured. + +If unset, incoming connections to the TACACS server will use the nearest +interface address pointing towards the server - making it error prone on +e.g. OSPF networks when a link fails and a backup route is taken. + +
+ +
+ +set system login tacas vrf \ + +Source all connections to the TACACS servers from given VRF \. + +
+ +## Login Banner + +You are able to set post-login or pre-login banner messages to display certain +information for this system. + +
+ +set system login banner pre-login \ + +Configure \ which is shown during SSH connect and before a user is +logged in. + +
+ +
+ +set system login banner post-login \ + +Configure \ which is shown after user has logged in to the system. + +
+ +
+ +
+ +Note + +
+ +To create a new line in your login message you need to escape the new +line character by using `\\n`. + +
+ +## Limits + +Login limits + +
+ +set system login max-login-session \ + +Set a limit on the maximum number of concurrent logged-in users on +the system. + +This option must be used with `timeout` option. + +
+ +
+ +set system login timeout \ + +Configure session timeout after which the user will be logged out. + +
+ +## Example + +In the following example, both User1 and User2 will be able to SSH into +VyOS as user `vyos` using their very own keys. User1 is restricted to only +be able to connect from a single IP address. In addition if password base login +is wanted for the `vyos` user a 2FA/MFA keycode is required in addition to +the password. + +``` none +set system login user vyos authentication public-keys 'User1' key "AAAAB3Nz...KwEW" +set system login user vyos authentication public-keys 'User1' type ssh-rsa +set system login user vyos authentication public-keys 'User1' options "from="192.168.0.100"" + +set system login user vyos authentication public-keys 'User2' key "AAAAQ39x...fbV3" +set system login user vyos authentication public-keys 'User2' type ssh-rsa + +set system login user vyos authentication otp key OHZ3OJ7U2N25BK4G7SOFFJTZDTCFUUE2 +set system login user vyos authentication plaintext-password vyos +``` + +### TACACS Example + +We use a vontainer providing the TACACS serve rin this example. + +Load the container image in op-mode. + +``` none +add container image lfkeitel/tacacs_plus:latest +``` + +``` none +set container network tac-test prefix '100.64.0.0/24' + +set container name tacacs1 image 'lfkeitel/tacacs_plus:latest' +set container name tacacs1 network tac-test address '100.64.0.11' + +set container name tacacs2 image 'lfkeitel/tacacs_plus:latest' +set container name tacacs2 network tac-test address '100.64.0.12' + +set system login tacacs server 100.64.0.11 key 'tac_plus_key' +set system login tacacs server 100.64.0.12 key 'tac_plus_key' + +commit +``` + +You can now SSH into your system using admin/admin as a default user supplied +from the `lfkeitel/tacacs_plus:latest` container. diff --git a/docs/configuration/system/md-name-server.md b/docs/configuration/system/md-name-server.md new file mode 100644 index 00000000..ea544b16 --- /dev/null +++ b/docs/configuration/system/md-name-server.md @@ -0,0 +1,81 @@ +# System DNS + +
+ +
+ +Warning + +
+ +If you are configuring a VRF for management purposes, there is +currently no way to force system DNS traffic via a specific VRF. + +
+ +This section describes configuring DNS on the system, namely: + +> - DNS name servers +> - Domain search order + +## DNS name servers + +
+ +set system name-server \ + +Use this command to specify a DNS server for the system to be used +for DNS lookups. More than one DNS server can be added, configuring +one at a time. Both IPv4 and IPv6 addresses are supported. + +
+ +### Example + +In this example, some *OpenNIC* servers are used, two IPv4 addresses +and two IPv6 addresses: + +``` none +set system name-server 176.9.37.132 +set system name-server 195.10.195.195 +set system name-server 2a01:4f8:161:3441::1 +set system name-server 2a00:f826:8:2::195 +``` + +## Domain search order + +In order for the system to use and complete unqualified host names, a +list can be defined which will be used for domain searches. + +
+ +set system domain-search \ + +Use this command to define domains, one at a time, so that the system +uses them to complete unqualified host names. Maximum: 6 entries. + +
+ +
+ +
+ +Note + +
+ +Domain names can include letters, numbers, hyphens and periods +with a maximum length of 253 characters. + +
+ +### 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 + +
+ +set system option ctrl-alt-delete \ + +Action which will be run once the ctrl-alt-del keystroke is received. + +
+ +
+ +set system option reboot-on-panic + +Automatically reboot system on kernel panic after 60 seconds. + +
+ +
+ +set system option startup-beep + +Play an audible beep to the system speaker when system is ready. + +
+ +
+ +set system option root-partition-auto-resize + +Enables the root partition auto-extension and resizes to the maximum +available space on system boot. + +
+ +### Kernel + +
+ +set system option kernel disable-mitigations + +Disable all optional CPU mitigations. This improves system performance, +but it may also expose users to several CPU vulnerabilities. + +This will add the following option to the Kernel commandline: + +- `mitigations=off` + +
+ +
+ +Note + +
+ +Setting will only become active with the next reboot! + +
+ +
+ +
+ +set system option kernel disable-power-saving + +This will add the following two options to the Kernel commandline: + +- `intel_idle.max_cstate=0` Disable intel_idle and fall back on acpi_idle +- `processor.max_cstate=1` Limit processor to maximum C-state 1 + +
+ +
+ +Note + +
+ +Setting will only become active with the next reboot! + +
+ +
+ +
+ +set system option kernel amd-pstate-driver \ + +Enables and configures p-state driver for modern AMD Ryzen and Epyc CPUs. + +The available modes are: + +- `active` This is the low-level firmware control mode based on the profile + set and the system governor has no effect. +- `passive` The driver allows the system governor to manage CPU frequency + while providing available performance states. +- `guided` The driver allows to set desired performance levels and the firmware + selects a performance level in this range and fitting to the current workload. + +This will add the following two options to the Kernel commandline: + +- `initcall_blacklist=acpi_cpufreq_init` Disable default ACPI CPU frequency scale +- `amd_pstate={mode}` Sets the p-state mode + +
+ +
+ +Note + +
+ +Setting will only become active with the next reboot! + +
+ +
+ + + +
+ +
+ +
+ +set system option kernel quiet + +Suppress most kernel messages during boot. This is useful for systems with +embedded serial console interfaces to speed up the boot process. + +
+ +## HTTP client + +
+ +set system option http-client source-address \ + +Several commands utilize cURL to initiate transfers. Configure the local +source IPv4/IPv6 address used for all cURL operations. + +
+ +
+ +set system option http-client source-interface \ + +Several commands utilize curl to initiate transfers. Configure the local +source interface used for all CURL operations. + +
+ +
+ +
+ +Note + +
+ +source-address and source-interface can not be used at the same +time. + +
+ +## SSH client + +
+ +set system option ssh-client source-address \ + +Use the specified address on the local machine as the source address of the +connection. Only useful on systems with more than one address. + +
+ +
+ +set system option ssh-client source-interface \ + +Use the address of the specified interface on the local machine as the +source address of the connection. + +
+ +## Keyboard Layout + +When starting a VyOS live system (the installation CD) the configured keyboard +layout defaults to US. As this might not suite everyones use case you can adjust +the used keyboard layout on the system console. + +
+ +set system option keyboard-layout \ + +Change system keyboard layout to given language. + +Defaults to `us`. + +
+ +
+ +Note + +
+ +Changing the keymap only has an effect on the system console, using +SSH or Serial remote access to the device is not affected as the keyboard +layout here corresponds to your access system. + +
+ +
+ +## 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 tuned for dynamic resource balancing based on profiles. + +
+ + + +
+ +
+ +set system option performance \< throughput | latency \> + +Configure one of the predefined system performance profiles. + +- `throughput`: A server profile focused on improving network throughput. + This profile favors performance over power savings by setting + `intel_pstate` and `max_perf_pct=100` and increasing kernel network + buffer sizes. + + It enables transparent huge pages, and uses cpupower to set the performance + cpufreq governor. It also sets `kernel.sched_min_granularity_ns` to 10 us, + `kernel.sched_wakeup_granularity_ns` to 15 uss, and `vm.dirty_ratio` to + 40%. + +- `latency`: A server profile focused on lowering network latency. + This profile favors performance over power savings by setting + `intel_pstate` and `min_perf_pct=100`. + + It disables transparent huge pages, and automatic NUMA balancing. It also + uses cpupower to set the performance cpufreq governor, and requests a + cpu_dma_latency value of 1. It also sets busy_read and busy_poll times to + 50 us, and tcp_fastopen to 3. + +
diff --git a/docs/configuration/system/md-proxy.md b/docs/configuration/system/md-proxy.md 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`). + +
+ +set system proxy url \ + +Set proxy for all connections initiated by VyOS, including HTTP, HTTPS, and +FTP (anonymous ftp). + +
+ +
+ +set system proxy port \ + +Configure proxy port if it does not listen to the default port 80. + +
+ +
+ +set system proxy username \ + +Some proxys require/support the "basic" HTTP authentication scheme as per +`7617`, thus a username can be configured. + +
+ +
+ +set system proxy password \ + +Some proxys require/support the "basic" HTTP authentication scheme as per +`7617`, thus a password can be configured. + +
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 + +## Configuration + +
+ +set system sflow agent-address \ + +Configure sFlow agent IPv4 or IPv6 address + +
+ +
+ +set system sflow agent-interface \ + +Configure agent IP address associated with this interface. + +
+ +
+ +set system sflow drop-monitor-limit \ + +Dropped packets reported on DROPMON Netlink channel by Linux kernel are exported via the standard sFlow v5 extension for reporting dropped packets + +
+ +
+ +set system sflow interface \ + +Configure and enable collection of flow information for the interface identified by \. + +You can configure multiple interfaces which whould participate in sflow accounting. + +
+ +
+ +set system sflow polling \ + +Configure schedule counter-polling in seconds (default: 30) + +
+ +
+ +set system sflow sampling-rate \ + +Use this command to configure the sampling rate for sFlow accounting (default: 1000) + +
+ +
+ +set system sflow server \ port \ + +Configure address of sFlow collector. sFlow server at \ can be both listening on an IPv4 or IPv6 address. + +
+ +## Example + +``` none +set system sflow agent-address '192.0.2.14' +set system sflow agent-interface 'eth0' +set system sflow drop-monitor-limit '50' +set system sflow interface 'eth0' +set system sflow interface 'eth1' +set system sflow polling '30' +set system sflow sampling-rate '1000' +set system sflow server 192.0.2.1 port '6343' +set system sflow server 203.0.113.23 port '6343' +``` diff --git a/docs/configuration/system/md-sysctl.md b/docs/configuration/system/md-sysctl.md 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/. + +
+ +set system sysctl parameter \ value \ + +
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 +local7 error messages, emergency messages will be sent to the console, too. + +To configure syslog, you need to switch into configuration mode. + +## Logging + +Syslog supports logging to multiple targets, those targets could be a plain +file on your VyOS installation itself, a serial console or a remote syslog +server which is reached via `IP (Internet Protocol)` UDP/TCP. + +### Console + +
+ +set system syslog console facility \ level \ + +Log syslog messages to `/dev/console`, for an explanation on +`syslog_facilities` keywords and `syslog_severity_level` keywords +see tables below. + +
+ +### Custom File + +
+ +set system syslog file \ facility \ level \ + +Log syslog messages to file specified via \, for an explanation on +`syslog_facilities` keywords and `syslog_severity_level` keywords +see tables below. + +
+ +
+ +set system syslog file \ archive size \ + +Syslog will write \ kilobytes into the file specified by \. +After this limit has been reached, the custom file is "rotated" by logrotate +and a new custom file is created. + +
+ +
+ +set system syslog file \ archive file \ + +Syslog uses logrotate to rotate logiles after a number of gives bytes. +We keep as many as \ rotated file before they are deleted on the +system. + +
+ +### Remote Host + +Logging to a remote host leaves the local logging configuration intact, it +can be configured in parallel to a custom file or console logging. You can log +to multiple hosts at the same time, using either TCP or UDP. The default is +sending the messages via port 514/UDP. + +
+ +set system syslog host \ facility \ level \ + +Log syslog messages to remote host specified by \. The address +can be specified by either FQDN or IP address. For an explanation on +`syslog_facilities` keywords and `syslog_severity_level` +keywords see tables below. + +
+ +
+ +set system syslog host \ facility \ protocol +\ + +Configure protocol used for communication to remote syslog host. This can be +either UDP or TCP. + +
+ +
+ +set system syslog vrf \ + +Specify name of the `VRF (Virtual Routing and Forwarding)` instance. + +
+ +#### `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
protocol tcp + ``` + +
+ +
+ +Note + +
+ +`TLS (Transport Layer Security)`-encrypted remote logging is +**not supported** over **UDP**. + +
+ +
+ +set system syslog remote \ tls + +Enable TLS-encrypted remote logging. + +
+ +
+ +set system syslog remote \ tls ca-certificate \ + +**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`. + +
+ +
+ +set system syslog remote \ tls certificate \ + +**Configure the client certificate.** + +The remote syslog server uses the client certificate to verify the identity +of the syslog client. + +The client certificate is required if the remote syslog server enforces +client certificate verification. + +
+ +
+ +set system syslog remote \ tls auth-mode \ + +**Configure the authentication mode.** + +The authentication mode defines how the syslog client verifies the syslog +server's identity. + +The following authentication modes are available: + +- `anon` **(default)**: Allows encrypted connections without verifying the syslog + server's identity. This mode is **not recommended**, as it is vulnerable to + `MITM (Man-in-the-Middle)` attacks. + +- `fingerprint`: Verifies the server’s certificate fingerprint against the + value preconfigured with: + + ``` none + set system syslog remote
tls permitted-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
tls permitted-peer + ``` + + This is a **recommended** secure mode for production environments. + +
+ +
+ +set system syslog remote \ tls permitted-peer \ + +**Configure the peer certificate identifiers.** + +The certificate identifier format depends on the authentication mode: + +- `fingerprint`: Enter the expected certificate fingerprints (SHA-1 or + SHA-256). +- `name`: Enter the expected certificate `CNs (Common Names)`. + +For `anon` and `certvalid` authentication modes, certificate identifiers +are not required. + +
+ +#### Examples: + +``` none +# Example of 'anon' authentication mode +set system syslog host 10.10.2.3 facility all level debug +set system syslog host 10.10.2.3 port 6514 +set system syslog host 10.10.2.3 protocol tcp +set system syslog host 10.10.2.3 tls auth-mode anon +# or just use 'set system syslog host 10.10.2.3 tls' + +# Example of 'certvalid' authentication mode +set system syslog host elk.example.com facility all level debug +set system syslog host elk.example.com port 6514 +set system syslog host elk.example.com protocol tcp +set system syslog host elk.example.com tls ca-certificate my-ca +set system syslog host elk.example.com tls auth-mode certvalid + +# Example of 'fingerprint' authentication mode +set system syslog host syslog.example.com facility all level debug +set system syslog host syslog.example.com port 6514 +set system syslog host syslog.example.com protocol tcp +set system syslog host syslog.example.com tls ca-certificate my-ca +set system syslog host syslog.example.com tls auth-mode fingerprint +set system syslog host syslog.example.com tls permitted-peer 'SHA1:10:C4:26:...' + +# Example of 'name' authentication mode +set system syslog host graylog.example.com facility all level debug +set system syslog host graylog.example.com port 6514 +set system syslog host graylog.example.com protocol tcp +set system syslog host graylog.example.com tls ca-certificate my-ca +set system syslog host graylog.example.com tls certificate syslog-client +set system syslog host graylog.example.com tls auth-mode name +set system syslog host graylog.example.com tls permitted-peer 'graylog.example.com' +``` + +#### Security Notes + +- Always prefer `auth-mode name` for secure deployments, as it ensures + both CA trust and server hostname validation. +- `anon` mode should only be used for testing, because it does not + authenticate the server. +- Ensure private keys are stored and managed exclusively in the + `PKI system `. + +### Local User Account + +
+ +set system syslog user \ facility \ level \ + +If logging to a local user account is configured, all defined log messages +are display on the console if the local user is logged in, if the user is not +logged in, no messages are being displayed. For an explanation on +`syslog_facilities` keywords and `syslog_severity_level` keywords +see tables below. + +
+ +## Facilities + +List of facilities used by syslog. Most facilities names are self explanatory. +Facilities local0 - local7 common usage is f.e. as network logs facilities for +nodes and network equipment. Generally it depends on the situation how to +classify logs and put them to facilities. See facilities more as a tool rather +than a directive to follow. + +Facilities can be adjusted to meet the needs of the user: + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Facility +CodeKeywordDescription
allAll facilities
0kernKernel messages
1userUser-level messages
2mailMail system
3daemonSystem daemons
4authSecurity/authentication messages
5syslogMessages generated internally by syslogd
6lprLine printer subsystem
7newsNetwork news subsystem
8uucpUUCP subsystem
9cronClock daemon
10securitySecurity/authentication messages
11ftpFTP daemon
12ntpNTP subsystem
13logauditLog audit
14logalertLog alert
15clockclock daemon (note 2)
16local0local use 0 (local0)
17local1local use 1 (local1)
18local2local use 2 (local2)
19local3local use 3 (local3)
20local4local use 4 (local4)
21local5local use 5 (local5)
22local6
+

use 6 (local6)

+
23local7local use 7 (local7)
+ +## Severity Level + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueSeverityKeywordDescription
allLog everything
0EmergencyemergSystem is unusable - a panic condition
1AlertalertAction must be taken immediately - A +condition that should be corrected +immediately, such as a corrupted system +database.
2CriticalcritCritical conditions - e.g. hard drive +errors.
3ErrorerrError conditions
4WarningwarningWarning conditions
5NoticenoticeNormal but significant conditions - +conditions that are not error conditions, +but that may require special handling.
6InformationalinfoInformational messages
7DebugdebugDebug-level messages - Messages that +contain information normally of use only +when debugging a program.
+ +## Display Logs + +
+ +show log \[all | authorization | cluster | conntrack-sync | ...\] + +Display log files of given category on the console. Use tab completion to get +a list of available categories. Thos categories could be: all, authorization, +cluster, conntrack-sync, dhcp, directory, dns, file, firewall, https, image +lldp, nat, openvpn, snmp, tail, vpn, vrrp + +
+ +If no option is specified, this defaults to all. + +
+ +show log image \ +\[all | authorization | directory | file \ | tail \\] + +Log messages from a specified image can be displayed on the console. Details +of allowed parameters: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + +
allDisplay contents of all master log files of the specified image
authorizationDisplay all authorization attempts of the specified image
directoryDisplay list of all user-defined log files of the specified image
file <file name>Display contents of a specified user-defined log file of the specified +image
tailDisplay last lines of the system log of the specified image
<lines>Number of lines to be displayed, default 10
+ +
+ +When no options/parameters are used, the contents of the main syslog file are +displayed. + +
+ +
+ +Hint + +
+ +Use `show log | strip-private` if you want to hide private data +when sharing your logs. + +
+ +## Delete Logs + +
+ +delete log file \ + +
+ +Deletes the specified user-defined file \ in the /var/log/user directory + +Note that deleting the log file does not stop the system from logging events. +If you use this command while the system is logging events, old log events +will be deleted, but events after the delete operation will be recorded in +the new file. To delete the file altogether, first delete logging to the +file using system syslog `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). + +
+ +
+ +Note + +
+ +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. + +
+ +
+ +set system task-scheduler task \ interval \ + +Specify the time interval when \ should be executed. The interval +is specified as number with one of the following suffixes: + +- `none` - Execution interval in minutes +- `m` - Execution interval in minutes +- `h` - Execution interval in hours +- `d` - Execution interval in days + +
+ +
+ +Note + +
+ +If suffix is omitted, minutes are implied. + +
+ +
+ +
+ +set system task-scheduler task \ crontab-spec \ + +Set execution time in common [cron](https://en.wikipedia.org/wiki/Cron) time format. A cron \ of +`30 */6 * * *` would execute the \ at minute 30 past every 6th hour. + +
+ +
+ +set system task-scheduler task \ executable path \ + +Specify absolute \ to script which will be run when \ is +executed. + +
+ +
+ +set system task-scheduler task \ executable arguments \ + +Arguments which will be passed to the executable. + +
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. + +
+ +set system time-zone \ + +Specify the systems \ as the Region/Location that best defines +your location. For example, specifying US/Pacific sets the time zone to US +Pacific time. + +Command completion can be used to list available time zones. The adjustment +for daylight time will take place automatically based on the time of year. + +
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 + +
+ +set system update-check auto-check + +Configure auto-checking for new images + +
+ +
+ +set system update-check url \ + +Configure a URL that contains information about images. + +
+ +## Example + +``` none +set system update-check auto-check +set system update-check url 'https://raw.githubusercontent.com/vyos/vyos-rolling-nightly-builds/main/version.json' +``` + +Check: + +``` none +vyos@r4:~$ show system updates +Current version: 1.5-rolling-202312220023 + +Update available: 1.5-rolling-202312250024 +Update URL: https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.5-rolling-202312250024/1.5-rolling-202312250024-amd64.iso +vyos@r4:~$ +``` -- cgit v1.2.3