diff options
| author | Yuriy Andamasov <yuriy@vyos.io> | 2026-05-06 14:40:28 +0300 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2026-05-06 12:40:28 +0100 |
| commit | 4b36114e053ee11d0cb264a1e4cfe4692d78f194 (patch) | |
| tree | be4ecc665eb3f1d556a37e768eed14989fec57b6 /docs/configuration/service | |
| parent | 21a554bd4f9156e41f1c73ba6b7223bb63b3a4ef (diff) | |
| download | vyos-documentation-4b36114e053ee11d0cb264a1e4cfe4692d78f194.tar.gz vyos-documentation-4b36114e053ee11d0cb264a1e4cfe4692d78f194.zip | |
Add incremental RST-to-MyST swap mechanism (#1857)
* feat: add swap_sources.py for incremental RST-to-MyST migration
Pre-build swap/restore script that renames md-{name}.md → {name}.md
before Sphinx builds and restores after. Includes state tracking,
exclude file generation, collision detection, and partial-failure
rollback. 10 tests cover all specified behaviors plus rollback path.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat: add import_myst.py for importing MyST files from myst/* branches
Adds scripts/import_myst.py with import_page, git_show, list_myst_files,
list_rst_files, and do_import. Imported files are written as md-{name}.md
alongside existing RST files; importing is decoupled from swap activation.
Adds tests/test_import_myst.py covering single-page write, identical-skip,
warn-on-different-without-force, force-overwrite, and nested-path creation.
All 5 tests pass on Python 3.9.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat: add MyST swap exclude patterns and directive config to conf.py
🤖 Generated by [robots](https://vyos.io)
* feat: add swap-wrapped rendering targets to Makefile
🤖 Generated by [robots](https://vyos.io)
* feat: add swap pre/post build hooks for ReadTheDocs
🤖 Generated by [robots](https://vyos.io)
* feat: add empty _swap.txt, remove atexit from swap script
The atexit handler in --swap mode caused immediate restore on process
exit, breaking standalone usage. Makefile trap and RTD post_build
handle restore reliably.
🤖 Generated by [robots](https://vyos.io)
* feat: activate quick-start as MyST canary via swap mechanism
Imports docs/md-quick-start.md from origin/myst/current and adds
quick-start to docs/_swap.txt. Validates the swap pipeline end-to-end
on one page: import_myst pulls the MD via git show, swap_sources
renames md-quick-start.md to quick-start.md, sphinx-build renders
quick-start.html with zero MD-specific warnings, and restore reverses
the rename cleanly.
🤖 Generated by [robots](https://vyos.io)
* feat: activate 106 visual-validated canaries via swap
Imports 105 MD files (plus quick-start already present) from
origin/myst/current and adds them to docs/_swap.txt. The selection
is the BackstopJS visual-passers cohort: pages with <5% rendered
diff vs the live RST docs at docs.vyos.io/en/latest/, filtered to
those with an RST counterpart on current and no cmdincludemd usage
(template-format reconciliation pending).
Local sphinx-build with all 106 swapped: succeeded with 100
warnings (vs 95 baseline). The 5 new warnings are all undefined
cross-reference labels, not build failures:
- contributing/development.md (missing 'coding-guidelines')
- operation/upgrade-recovery.md (3 missing 'how_it_works' /
'cancelling_recovery')
- vpp/configuration/dataplane/{buffers,memory,unix}.md (missing
'vpp_config_dataplane_*' labels)
Source list: ~/.claude/projects/-Users-vybot-GitHub-vyos-documentation/docs/2026-04-29-myst-conversion-audit/visual-passers-under-5pct.txt
BackstopJS report: claude/gifted-hertz-74b9f9 worktree
(visual-compare/), 2026-04-23 vs vyos--1838.org.readthedocs.build.
🤖 Generated by [robots](https://vyos.io)
* fix: re-import 4 canary md-*.md files with xref label fixes
Re-imports the dash-form-corrected versions of:
- contributing/md-development.md (added (coding-guidelines)= anchor)
- operation/md-upgrade-recovery.md (3 ref renames: how_it_works /
cancelling_recovery -> dash form)
- vpp/configuration/dataplane/md-buffers.md (vpp_config_dataplane_physmem
-> vpp-config-dataplane-physmem)
- vpp/configuration/dataplane/md-unix.md
(vpp_config_dataplane_interface_rx_mode
-> vpp-config-dataplane-interface-rx-mode)
Source: origin/myst/current commit 59fbe3ea. Verified locally: clean
swap-build no longer reports any of the 5 target labels (1 of 6 —
vpp-config-hugepages — remains because system.md isn't in the canary
swap list; that anchor lives there).
🤖 Generated by [robots](https://vyos.io)
* fix: re-add 4 canary md-*.md files deleted by 242b334a
Commit 242b334a accidentally staged deletions instead of modifications
because the working tree had unprefixed *.md files left over from an
incomplete swap-restore cycle. Re-imports the same 4 files from
origin/myst/current with the xref label fixes applied:
- contributing/md-development.md — (coding-guidelines)= anchor
- operation/md-upgrade-recovery.md — how_it_works → how-it-works,
cancelling_recovery → cancelling-recovery
- vpp/configuration/dataplane/md-buffers.md — vpp_config_dataplane_physmem
→ vpp-config-dataplane-physmem
- vpp/configuration/dataplane/md-unix.md — vpp_config_dataplane_interface_rx_mode
→ vpp-config-dataplane-interface-rx-mode
Source: origin/myst/current commit 59fbe3ea.
🤖 Generated by [robots](https://vyos.io)
* fix: resolve remaining xref label gaps in swap-active build
Three small additions clear the cross-reference warnings tied to
underscore-vs-dash label form mismatches and the vpp-config-hugepages
reference that previously needed system.md in the canary set.
- system.rst: add .. _vpp-config-hugepages: alongside the existing
underscore label so memory.md references resolve regardless of
whether system.md is swap-active.
- md-lcp.md: add (vpp_config_dataplane_lcp_ignore-kernel-routes)=
alongside dash form (carries upstream from myst/current 079fa786).
- md-memory.md: add (vpp_config_dataplane_memory)= alongside dash
form (also from myst/current 079fa786).
Local clean swap-build with 106 canaries:
before: 305 warnings, 8 undefined-label entries in our scope
after: 300 warnings, 0 undefined-label entries in our scope
Remaining undefined-label warnings (release-notes, prepare_commit)
are in documentation.rst and unrelated to the canary swap mechanism.
🤖 Generated by [robots](https://vyos.io)
* fix: re-add md-lcp.md and md-memory.md (deleted by 870c9e7e)
Same disaster pattern as 242b334a: a swap-restore cycle left
unprefixed *.md files in the working tree, and the subsequent
git add staged deletions instead of modifications. Restoring the
two affected md-*.md files from origin/myst/current 079fa786
(which has the dual underscore+dash anchors needed for the
swap-active build).
🤖 Generated by [robots](https://vyos.io)
* feat: expand canaries to 114; refresh 3 with cfgcmd body fix
Adds 8 new visual-validated canaries from the post-cfgcmd-fix
BackstopJS run (2026-04-29):
- configuration/policy/as-path-list
- configuration/policy/community-list
- configuration/policy/extcommunity-list
- configuration/policy/large-community-list
- configuration/policy/local-route
- configuration/policy/prefix-list
- configuration/service/salt-minion
- configuration/system/updates
Refreshes 3 existing canaries whose MD content changed via the
cfgcmd/opcmd single-line body fix on myst/current fc19ab5c:
- configuration/firewall/global-options
- configuration/firewall/groups
- configuration/policy/route
All 11 sourced from origin/myst/current. Net: 106 -> 114 canaries.
🤖 Generated by [robots](https://vyos.io)
* fix: re-import md-cloud-init.md (block 3 fix from myst/current)
🤖 Generated by [robots](https://vyos.io)
* feat(swap): import .md files and webp transition from myst/current
Selective import from origin/myst/current (cf9c9b34):
- Add/update 255 .md files (full MyST conversion plus webp ref updates)
- Delete 175 PNG/JPG from docs/_static/images (webp twins already present)
- Delete 5 autotest topology.png (webp twins already present)
Preserved on swap (untouched):
- All .rst files (incremental swap pattern)
- conf.py, _ext/, _include/*.txt, .gitignore
- 115 canary md-*.md files
- 7 superpowers/specs/*.md design docs
- Logos vyos-logo.png / vyos-logo-icon.png (referenced by conf.py)
🤖 Generated by [robots](https://vyos.io)
* chore(swap): remove canary md-*.md files and docs/superpowers
- Remove 115 canary md-*.md files (incremental swap helpers no longer needed)
- Remove 8 files under docs/superpowers (project planning/design docs that
shouldn't ship in the documentation tree)
🤖 Generated by [robots](https://vyos.io)
* docs: address Copilot review feedback on imported MyST pages
Fix issues flagged by Copilot review on PR #1857 (the same content lives
in myst/current as the canonical source):
Real bugs:
- site-2-site-cisco.md: replace curly quote (U+2019) with ASCII apostrophe
- rsa-keys.md: fix typo "key-pair nam>>" → "key-pair name>"
- vmware.md: lowercase admonition directive (:::{NOTE} → :::{note})
- vpp/configuration/nat/index.md: remove blank line inside {include} fence
Grammar:
- vpp/configuration/interfaces/loopback.md: "bounded" → "bound"
- vpp/configuration/sflow.md: "VyOS support" → "VyOS supports"
- vpp/requirements.md: "bypass" → "bypasses"
- vpp/configuration/dataplane/interface.md: "configures" → "configure"
CI linter (IP addresses):
- nmp.md: wrap 8.8.8.8 example with stop/start_vyoslinter
- lac-lns.md: wrap LNS config block (contains 8.8.8.8)
- wan-load-balancing.md: wrap whole file (illustrative non-RFC IPs)
- policy/examples.md: replace 192.0.1.1 with RFC 5737 192.0.2.1
🤖 Generated by [robots](https://vyos.io)
* fix(swap): address Copilot review feedback on swap infrastructure
Category D — drop obsolete canary mechanism settings:
- conf.py: remove '**/md-*.md' from exclude_patterns (no canaries left)
- Makefile: replace malformed '*/_build/*' with '$(BUILDDIR)/**' and drop
the '*/md-*' ignore (canary files no longer exist)
Category C — script robustness:
- import_myst.py:
* list_myst_files() now raises SystemExit on git ls-tree failure instead
of silently returning [] (would have masked typo'd --source refs)
* list_rst_files() skips _build/ when scanning for .rst stems
* import_page() rejects stems containing '..' or absolute paths and
re-checks that the resolved destination stays under docs_dir
* --dry-run uses a separate "would_import" counter; summary line now
distinguishes dry-run from actual imports
- swap_sources.py:
* parse_swap_list() reads with explicit encoding='utf-8'
* do_restore() validates state file version + entry shape before
renaming files; raises with actionable message on corruption
* State file reads/writes use explicit encoding='utf-8' throughout
_swap.txt:
- Wrap long comment line to satisfy 80-character doc-linter limit
🤖 Generated by [robots](https://vyos.io)
* refactor(swap): rename imported .md files to md- prefix for swap mechanism
Restore the canary file naming convention that swap_sources.py expects:
the imported MyST pages now live as docs/<dir>/md-<name>.md alongside
the existing docs/<dir>/<name>.rst, so swap_sources.py --swap can rename
them into place at build time.
- 254 .md files renamed (every page with a matching .rst counterpart)
- 2 MyST-only pages left at their final names (no .rst exists, no swap
needed): docs/copyright.md, docs/automation/terraform/terraformvyos.md
All 114 stems listed in docs/_swap.txt now have a corresponding
md-<name>.md source file ready to swap in.
🤖 Generated by [robots](https://vyos.io)
* docs: address CodeRabbit review feedback on imported MyST pages
Fix issues flagged by CodeRabbit on PR #1857. All issues are pre-existing
in the upstream RST docs and inherited by the MyST conversion.
Real bugs:
- inter-vrf-routing-vrf-lite.md: invalid IPv6 next-hop "2001:db8::*" →
"2001:db8::1"
- ipsec-pa-route-based.md: vendor mislabel "Cisco" → "Palo Alto"
(header on line 39 and "Monitoring on Cisco side" section heading)
- bgp-ipv6-unnumbered.md: AS number mismatch between configuration and
verification output for both routers (Router A: 65020 → 64496;
Router B: 65021 → 64499)
- qos.md: class 30 used "match ADDRESS20" instead of ADDRESS30 — broke
the documented pattern (classes 10/20/30 → ADDRESS10/20/30)
Security:
- OpenVPN_with_LDAP.md: redact full PEM private key material from the
three "set pki ... private key '...'" lines and from the embedded
OpenVPN client <key> block; replace with <REDACTED> / ...REDACTED...
placeholders. Public certificates retained.
🤖 Generated by [robots](https://vyos.io)
* feat(swap): default to serving MyST for all swapped pages
Replace the previously-curated 114-stem _swap.txt with the full set of
254 imported md-prefixed pages, so MD is served by default at build
time. To revert any specific page back to RST, remove its stem from
_swap.txt (or comment it out).
🤖 Generated by [robots](https://vyos.io)
* fix(ext): handle RST fallback in CmdInclude when _renderer absent
`cmdincludemd` is in `myst_fence_as_directive`, so MyST routes
fence blocks through `render_fence → render_restructuredtext →
MockRSTParser`. In that path `self.state` is a plain docutils Body
with no `_renderer`, crashing the build.
Fall back to `nested_parse` when `_renderer` is unavailable so the
directive works in both MyST and RST/MockRSTParser contexts.
🤖 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 from PR #1857
Fix conversion artifacts, typos, grammar errors, and technical
inaccuracies flagged by automated code review (Copilot + CodeRabbit).
Infrastructure: add root-level md-*.md exclusion to conf.py,
fix sphinx-autobuild ignore globs in Makefile.
Content: fix curly quotes, invalid Go panic() calls, shell quoting
in cURL examples, incorrect firewall command paths, typos across
22 documentation files, remove duplicate sections.
🤖 Generated by [robots](https://vyos.io)
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Diffstat (limited to 'docs/configuration/service')
23 files changed, 6468 insertions, 0 deletions
diff --git a/docs/configuration/service/md-broadcast-relay.md b/docs/configuration/service/md-broadcast-relay.md new file mode 100644 index 00000000..4202ad6b --- /dev/null +++ b/docs/configuration/service/md-broadcast-relay.md @@ -0,0 +1,70 @@ +(udp-broadcast-relay)= + +# UDP Broadcast Relay + +Certain vendors use broadcasts to identify their equipment within one ethernet +segment. Unfortunately if you split your network with multiple VLANs you loose +the ability of identifying your equipment. + +This is where "UDP broadcast relay" comes into play! It will forward received +broadcasts to other configured networks. + +Every UDP port which will be forward requires one unique ID. Currently we +support 99 IDs! + +## Configuration + +```{cfgcmd} set service broadcast-relay id \<n\> description \<description\> + +A description can be added for each and every unique relay ID. This is +useful to distinguish between multiple different ports/applications. +``` + +```{cfgcmd} set service broadcast-relay id \<n\> interface \<interface\> + +The interface used to receive and relay individual broadcast packets. If you +want to receive/relay packets on both `eth1` and `eth2` both interfaces need +to be added. +``` + +```{cfgcmd} set service broadcast-relay id \<n\> address \<ipv4-address\> + +Set the source IP of forwarded packets, otherwise original senders address +is used. +``` + +```{cfgcmd} set service broadcast-relay id \<n\> port \<port\> + +The UDP port number used by your application. It is mandatory for this kind +of operation. +``` + +```{cfgcmd} set service broadcast-relay id \<n\> disable + +Each broadcast relay instance can be individually disabled without deleting +the configured node by using the following command: +``` + +```{cfgcmd} set service broadcast-relay disable + +In addition you can also disable the whole service without the need to remove +it from the current configuration. +``` + +:::{note} +You can run the UDP broadcast relay service on multiple routers +connected to a subnet. There is **NO** UDP broadcast relay packet storm! +::: + +## Example + +To forward all broadcast packets received on `UDP port 1900` on `eth3`, `eth4` +or `eth5` to all other interfaces in this configuration. + +```none +set service broadcast-relay id 1 description 'SONOS' +set service broadcast-relay id 1 interface 'eth3' +set service broadcast-relay id 1 interface 'eth4' +set service broadcast-relay id 1 interface 'eth5' +set service broadcast-relay id 1 port '1900' +``` diff --git a/docs/configuration/service/md-config-sync.md b/docs/configuration/service/md-config-sync.md new file mode 100644 index 00000000..a575f947 --- /dev/null +++ b/docs/configuration/service/md-config-sync.md @@ -0,0 +1,164 @@ +(config-sync)= + +# Config Sync + +Configuration synchronization (config sync) is a feature of VyOS that +permits synchronization of the configuration of one VyOS router to +another in a network. + +The main benefit to configuration synchronization is that it eliminates having +to manually replicate configuration changes made on the primary router to the +secondary (replica) router. + +The writing of the configuration to the secondary router is performed through +the VyOS HTTP API. The user can specify which portion(s) of the configuration will +be synchronized and the mode to use - whether to replace or add. + +To prevent issues with divergent configurations between the pair of routers, +synchronization is strictly unidirectional from primary to replica. Both +routers should be online and run the same version of VyOS. + +## Configuration + +```{cfgcmd} set service config-sync secondary \<address|key|timeout|port\> + +Specify the address, API key, timeout and port of the secondary router. +You need to enable and configure the HTTP API service on the secondary +router for config sync to operate. +``` + +```{cfgcmd} set service config-sync section \<section\> + +Specify the section of the configuration to synchronize. If more than one +section is to be synchronized, repeat the command to add additional +sections as required. +``` + +```{cfgcmd} set service config-sync mode \<load|set\> + +Two options are available for *mode*: either *load* and replace or *set* +the configuration section. +``` + +```none +Supported options for <section> include: + firewall + interfaces <interface> + nat + nat66 + pki + policy + protocols <protocol> + qos <interface|policy> + service <service> + system <conntrack| + flow-accounting|option|sflow|static-host-mapping|sysctl|time-zone> + vpn + vrf +``` + + +## Operational Commands + +````{opcmd} show configuration secondary sync [commands] [running | candidate | saved] [\<config-node-path\>] + +Display configuration differences between the local node and +a config-sync secondary node. + +This command allows operators to compare configurations across nodes +participating in configuration synchronization (e.g., primary and +secondary routers). It helps detect configuration drift and validate +intended changes before synchronization. + +**Parameters:** + +```{eval-rst} +.. list-table:: + :widths: 30 70 + :header-rows: 0 + + * - ``commands`` (optional) + - Show output as a list of configuration commands instead of raw diff. + * - ``running|candidate|saved`` (optional, mutually exclusive) + - Select which configuration to compare: + ``running`` (current active configuration, default), + ``candidate`` (uncommitted changes), or + ``saved`` (last saved configuration). Only one of these may be + specified at a time; if omitted, ``running`` is used. +``` + +**Examples:** + +:::{code-block} none +# compare full running configuration with a secondary node +show configuration secondary sync + +# compare only interface configuration +show configuration secondary sync running interfaces dummy + +# compare candidate configuration and display as a list of commands +show configuration secondary sync commands candidate +::: +```` + +Without a built-in cross-node diff, operators may unintentionally push +changes that conflict with the remote configuration (e.g., mismatched +interfaces, firewall policies, or protocol settings). + + +## Example + +- Synchronize the time-zone and OSPF configuration from Router A to Router B +- The address of Router B is 10.0.20.112 and the port used is 8443 + +Configure the HTTP API service on Router B + +```none +set service https listen-address '10.0.20.112' +set service https port '8443' +set service https api keys id KID key 'foo' +set service https api rest +``` + +Configure the config-sync service on Router A + +```none +set service config-sync mode 'load' +set service config-sync secondary address '10.0.20.112' +set service config-sync secondary port '8443' +set service config-sync secondary key 'foo' +set service config-sync section protocols 'ospf' +set service config-sync section system 'time-zone' +``` + +Make config-sync relevant changes to Router A's configuration + +```none +vyos@vyos-A# set system time-zone 'America/Los_Angeles' +vyos@vyos-A# commit +INFO:vyos_config_sync:Config synchronization: Mode=load, +Secondary=10.0.20.112 +vyos@vyos-A# save + +vyos@vyos-A# set protocols ospf area 0 network '10.0.48.0/30' +vyos@vyos-A# commit +INFO:vyos_config_sync:Config synchronization: Mode=load, +Secondary=10.0.20.112 +yos@vyos-A# save +``` + +Verify configuration changes have been replicated to Router B + +```none +vyos@vyos-B:~$ show configuration commands | match time-zone +set system time-zone 'America/Los_Angeles' + +vyos@vyos-B:~$ show configuration commands | match ospf +set protocols ospf area 0 network '10.0.48.0/30' +``` + + +## Known issues + +Configuration resynchronization. With the current implementation of *service +config-sync*, the secondary node must be online. diff --git a/docs/configuration/service/md-conntrack-sync.md b/docs/configuration/service/md-conntrack-sync.md new file mode 100644 index 00000000..47a0ae2f --- /dev/null +++ b/docs/configuration/service/md-conntrack-sync.md @@ -0,0 +1,321 @@ +(conntrack-sync)= + +# Conntrack Sync + +One of the important features built on top of the Netfilter framework is +connection tracking. Connection tracking allows the kernel to keep track of all +logical network connections or sessions, and thereby relate all of the packets +which may make up that connection. NAT relies on this information to translate +all related packets in the same way, and iptables can use this information to +act as a stateful firewall. + +The connection state however is completely independent of any upper-level +state, such as TCP's or SCTP's state. Part of the reason for this is that when +merely forwarding packets, i.e. no local delivery, the TCP engine may not +necessarily be invoked at all. Even connectionless-mode transmissions such as +UDP, IPsec (AH/ESP), GRE and other tunneling protocols have, at least, a pseudo +connection state. The heuristic for such protocols is often based upon a preset +timeout value for inactivity, after whose expiration a Netfilter connection is +dropped. + +Each Netfilter connection is uniquely identified by a (layer-3 protocol, source +address, destination address, layer-4 protocol, layer-4 key) tuple. The layer-4 +key depends on the transport protocol; for TCP/UDP it is the port numbers, for +tunnels it can be their tunnel ID, but otherwise is just zero, as if it were +not part of the tuple. To be able to inspect the TCP port in all cases, packets +will be mandatorily defragmented. + +It is possible to use either Multicast or Unicast to sync conntrack traffic. +Most examples below show Multicast, but unicast can be specified by using the +"peer" keywork after the specified interface, as in the following example: + +{cfgcmd}`set service conntrack-sync interface eth0 peer 192.168.0.250` + +## Configuration + +```{cfgcmd} set service conntrack-sync accept-protocol + +Accept only certain protocols: You may want to replicate the state of flows +depending on their layer 4 protocol. + +Protocols are: tcp, sctp, dccp, udp, icmp and ipv6-icmp. +``` + + +```{cfgcmd} set service conntrack-sync event-listen-queue-size \<size\> + +The daemon doubles the size of the netlink event socket buffer size if it +detects netlink event message dropping. This clause sets the maximum buffer +size growth that can be reached. + +Queue size for listening to local conntrack events in MB. +``` + + +```{cfgcmd} set service conntrack-sync expect-sync \<all|ftp|h323|nfs|sip|sqlnet\> + +Protocol for which expect entries need to be synchronized. +``` + + +```{cfgcmd} set service conntrack-sync failover-mechanism vrrp sync-group \<group\> + +Failover mechanism to use for conntrack-sync. + +Only VRRP is supported. Required option. +``` + + +```{cfgcmd} set service conntrack-sync ignore-address \<x.x.x.x\> + +IP addresses or networks for which local conntrack entries will not be synced +``` + + +```{cfgcmd} set service conntrack-sync interface \<name\> + +Interface to use for syncing conntrack entries. +``` + + +```{cfgcmd} set service conntrack-sync interface \<name\> port \<port\> + +Port number used by connection. +``` + + +```{cfgcmd} set service conntrack-sync listen-address \<ipv4address\> + +Local IPv4 addresses for service to listen on. +``` + + +```{cfgcmd} set service conntrack-sync mcast-group \<x.x.x.x\> + +Multicast group to use for syncing conntrack entries. + +Defaults to 225.0.0.50. +``` + + +```{cfgcmd} set service conntrack-sync interface \<name\> peer \<address\> + +Peer to send unicast UDP conntrack sync entires to, if not using Multicast +configuration from above above. +``` + + +```{cfgcmd} set service conntrack-sync sync-queue-size \<size\> + +Queue size for syncing conntrack entries in MB. +``` + + +```{cfgcmd} set service conntrack-sync disable-external-cache + +This diable the external cache and directly injects the flow-states into the +in-kernel Connection Tracking System of the backup firewall. +``` + + +```{cfgcmd} set service conntrack-sync purge-timeout \<timeout\> + +Timeout (in seconds) for purging synchronized entries on handover events. + +On handover, ``conntrackd -t`` is invoked, which schedules a conntrack table +flush after ``<timeout>`` seconds to purge stale (“zombie”) entries and +reduce clashes when multiple handovers occur in a short period. +The default is 60 seconds. +``` + +:::{note} +In VRRP stateful firewall deployments, align VRRP timing with this +behavior: because synchronized conntrack state is purged after the purge +timeout, set **VRRP preempt-delay** to ≥ **purge-timeout** so mastership +can be restored before conntrack state is purged. +::: + +```{cfgcmd} set service conntrack-sync disable-syslog + +Disable connection logging via Syslog. +``` + + +```{cfgcmd} set service conntrack-sync startup-resync + +Order conntrackd to request a complete conntrack table resync against +the other node at startup. +``` + +## Operation + +```{opcmd} show conntrack table ipv4 + +Make sure conntrack is enabled by running and show connection tracking table. + +:::{code-block} none +vyos@vyos:~$ show conntrack table ipv4 +TCP state codes: SS - SYN SENT, SR - SYN RECEIVED, ES - ESTABLISHED, +FW - FIN WAIT, CW - CLOSE WAIT, LA - LAST ACK, +TW - TIME WAIT, CL - CLOSE, LI - LISTEN + +CONN ID Source Destination Protocol TIMEOUT +1015736576 10.35.100.87:58172 172.31.20.12:22 tcp [6] ES 430279 +1006235648 10.35.101.221:57483 172.31.120.21:22 tcp [6] ES 413310 +1006237088 10.100.68.100 172.31.120.21 icmp [1] 29 +1015734848 10.35.100.87:56282 172.31.20.12:22 tcp [6] ES 300 +1015734272 172.31.20.12:60286 239.10.10.14:694 udp [17] 29 +1006239392 10.35.101.221 172.31.120.21 icmp [1] 29 +::: +:::{note} +If the table is empty and you have a warning message, it means +conntrack is not enabled. To enable conntrack, just create a NAT or a firewall +rule. {cfgcmd}`set firewall state-policy established action accept` +::: +``` + + +```{opcmd} show conntrack-sync cache external + +Show connection syncing external cache entries +``` + + +```{opcmd} show conntrack-sync cache internal + +Show connection syncing internal cache entries +``` + + +```{opcmd} show conntrack-sync statistics + +Retrieve current statistics of connection tracking subsystem. + +:::{code-block} none +vyos@vyos:~$ show conntrack-sync statistics +Main Table Statistics: + +cache internal: +current active connections: 19606 +connections created: 6298470 failed: 0 +connections updated: 3786793 failed: 0 +connections destroyed: 6278864 failed: 0 + +cache external: +current active connections: 15771 +connections created: 1660193 failed: 0 +connections updated: 77204 failed: 0 +connections destroyed: 1644422 failed: 0 + +traffic processed: +0 Bytes 0 Pckts + +multicast traffic (active device=eth0.5): +976826240 Bytes sent 212898000 Bytes recv +8302333 Pckts sent 2009929 Pckts recv +0 Error send 0 Error recv + +message tracking: +0 Malformed msgs 263 Lost msgs +::: +``` +```{opcmd} show conntrack-sync status + +Retrieve current status of connection tracking subsystem. + +:::{code-block} none +vyos@vyos:~$ show conntrack-sync status +sync-interface : eth0.5 +failover-mechanism : vrrp [sync-group GEFOEKOM] +last state transition : no transition yet! +ExpectationSync : disabled +::: +``` + +## Example + +The next example is a simple configuration of conntrack-sync. + +:::{figure} /_static/images/service_conntrack_sync-schema.webp +:alt: Conntrack Sync Example +:scale: 60 % +::: + +Now configure conntrack-sync service on `router1` **and** `router2` + +```none +set high-availability vrrp group internal virtual-address ... etc ... +set high-availability vrrp sync-group syncgrp member 'internal' +set service conntrack-sync accept-protocol 'tcp' +set service conntrack-sync accept-protocol 'udp' +set service conntrack-sync accept-protocol 'icmp' +set service conntrack-sync failover-mechanism vrrp sync-group 'syncgrp' +set service conntrack-sync interface 'eth0' +set service conntrack-sync mcast-group '225.0.0.50' +``` + +On the active router, you should have information in the internal-cache of +conntrack-sync. The same current active connections number should be shown in +the external-cache of the standby router + +On active router run: + +```none +$ show conntrack-sync statistics + +Main Table Statistics: + +cache internal: +current active connections: 10 +connections created: 8517 failed: 0 +connections updated: 127 failed: 0 +connections destroyed: 8507 failed: 0 + +cache external: +current active connections: 0 +connections created: 0 failed: 0 +connections updated: 0 failed: 0 +connections destroyed: 0 failed: 0 + +traffic processed: + 0 Bytes 0 Pckts + +multicast traffic (active device=eth0): + 868780 Bytes sent 224136 Bytes recv + 20595 Pckts sent 14034 Pckts recv + 0 Error send 0 Error recv + +message tracking: + 0 Malformed msgs 0 Lost msgs +``` + +On standby router run: + +```none +$ show conntrack-sync statistics + +Main Table Statistics: + +cache internal: +current active connections: 0 +connections created: 0 failed: 0 +connections updated: 0 failed: 0 +connections destroyed: 0 failed: 0 + +cache external: +current active connections: 10 +connections created: 888 failed: 0 +connections updated: 134 failed: 0 +connections destroyed: 878 failed: 0 + +traffic processed: + 0 Bytes 0 Pckts + +multicast traffic (active device=eth0): + 234184 Bytes sent 907504 Bytes recv + 14663 Pckts sent 21495 Pckts recv + 0 Error send 0 Error recv + +message tracking: + 0 Malformed msgs 0 Lost msgs +``` diff --git a/docs/configuration/service/md-console-server.md b/docs/configuration/service/md-console-server.md new file mode 100644 index 00000000..9402e935 --- /dev/null +++ b/docs/configuration/service/md-console-server.md @@ -0,0 +1,139 @@ +(console-server)= + +# Console Server + +Starting of with VyOS 1.3 (equuleus) we added support for running VyOS as an +Out-of-Band Management device which provides remote access by means of SSH to +directly attached serial interfaces. + +Serial interfaces can be any interface which is directly connected to the CPU +or chipset (mostly known as a ttyS interface in Linux) or any other USB to +serial converter (Prolific PL2303 or FTDI FT232/FT4232 based chips). + +If you happened to use a Cisco NM-16A - Sixteen Port Async Network Module or +NM-32A - Thirty-two Port Async Network Module - this is your VyOS replacement. + +For USB port information please refor to: {ref}`hardware_usb`. + +## Configuration + +Between computers, the most common configuration used was "8N1": eight bit +characters, with one start bit, one stop bit, and no parity bit. Thus 10 Baud +times are used to send a single character, and so dividing the signalling +bit-rate by ten results in the overall transmission speed in characters per +second. This is also the default setting if none of those options are defined. + +```{cfgcmd} set service console-server device \<device\> data-bits [7 | 8] + +Configure either seven or eight data bits. This defaults to eight data +bits if left unconfigured. +``` + + +```{cfgcmd} set service console-server device \<device\> description \<string\> + +A user friendly description identifying the connected peripheral. +``` + + +```{cfgcmd} set service console-server device \<device\> alias \<string\> + +A user friendly alias for this connection. Can be used instead of the +device name when connecting. +``` + + +```{cfgcmd} set service console-server device \<device\> parity [even | odd | none] + +Set the parity option for the console. If unset this will default to none. +``` + + +```{cfgcmd} set service console-server device \<device\> stop-bits [1 | 2] + +Configure either one or two stop bits. This defaults to one stop bits if +left unconfigured. +``` + + +```{cfgcmd} set service console-server device \<device\> speed [ 300 | 1200 | 2400 | 4800 | 9600 | 19200 | 38400 | 57600 | 115200 ] + +:::{note} +USB to serial converters will handle most of their work in software +so you should be carefull with the selected baudrate as some times they +can't cope with the expected speed. +::: +``` + +### Remote Access + + +Each individual configured console-server device can be directly exposed to +the outside world. A user can directly connect via SSH to the configured +port. + +```{cfgcmd} set service console-server device \<device\> ssh port \<port\> + +Accept SSH connections for the given `<device>` on TCP port `<port>`. +After successfull authentication the user will be directly dropped to +the connected serial device. + +:::{hint} +Multiple users can connect to the same serial device but only +one is allowed to write to the console port. +::: +``` + +## Operation + +```{opcmd} show console-server ports + +Show configured serial ports and their respective interface configuration. + +:::{code-block} none +vyos@vyos:~$ show console-server ports +usb0b2.4p1.0 on /dev/serial/by-bus/usb0b2.4p1.0@ at 9600n +::: +``` + + +```{opcmd} show console-server user + +Show currently connected users. + +:::{code-block} none +vyos@vyos:~$ show console-server user +usb0b2.4p1.0 up vyos@localhost +::: +``` +```{opcmd} connect console \<device\> + +Locally connect to serial port identified by `<device>`. + +:::{code-block} none +vyos@vyos-r1:~$ connect console usb0b2.4p1.0 +[Enter `^Ec?' for help] +[-- MOTD -- VyOS Console Server] + +vyos-r2 login: +::: + +:::{hint} +Multiple users can connect to the same serial device but only +one is allowed to write to the console port. +::: + +:::{hint} +The sequence ``^Ec?`` translates to: ``Ctrl+E c ?``. To quit +the session use: ``Ctrl+E c .`` +::: + +:::{hint} +If ``alias`` is set, it can be used instead of the device when +connecting. +::: +``` +```{opcmd} show log console-server + +Show the console server log. +```
\ No newline at end of file diff --git a/docs/configuration/service/md-dhcp-relay.md b/docs/configuration/service/md-dhcp-relay.md new file mode 100644 index 00000000..a4a10109 --- /dev/null +++ b/docs/configuration/service/md-dhcp-relay.md @@ -0,0 +1,205 @@ +(dhcp-relay)= + +# DHCP Relay + +If you want your router to forward DHCP requests to an external DHCP server +you can configure the system to act as a DHCP relay agent. The DHCP relay +agent works with IPv4 and IPv6 addresses. + +All interfaces used for the DHCP relay must be configured. This includes the +uplink to the DHCP server. + +## IPv4 relay + +### Configuration + +```{cfgcmd} set service dhcp-relay interface \<interface\> + +Interfaces that participate in the DHCP relay process. If this command is +used, at least two entries of it are required: one for the interface that +captures the dhcp-requests, and one for the interface to forward such +requests. A warning message will be shown if this command is used, since +new implementations should use ``listen-interface`` and +``upstream-interface``. +``` + +```{cfgcmd} set service dhcp-relay listen-interface \<interface\> + +Interface for DHCP Relay Agent to listen for requests. +``` + +```{cfgcmd} set service dhcp-relay upstream-interface \<interface\> + +Interface for DHCP Relay Agent to forward requests out. +``` + +```{cfgcmd} set service dhcp-relay server \<server\> + +Configure IP address of the DHCP `<server>` which will handle the relayed +packets. +``` + +```{cfgcmd} set service dhcp-relay relay-options relay-agents-packets discard + +The router should discard DHCP packages already containing relay agent +information to ensure that only requests from DHCP clients are forwarded. +``` + +```{cfgcmd} set service dhcp-relay disable + +Disable dhcp-relay service. +``` + + +#### Options + +```{cfgcmd} set service dhcp-relay relay-options hop-count \<count\> + +Set the maximum hop `<count>` before packets are discarded. Range 0...255, +default 10. +``` + +```{cfgcmd} set service dhcp-relay relay-options max-size \<size\> + +Set maximum `<size>` of DHCP packets including relay agent information. If a +DHCP packet size surpasses this value it will be forwarded without appending +relay agent information. Range 64...1400, default 576. +``` + +```{cfgcmd} set service dhcp-relay relay-options relay-agents-packets \<append | discard | forward | replace\> + +Four policies for reforwarding DHCP packets exist: +* **append:** The relay agent is allowed to append its own relay information +to a received DHCP packet, disregarding relay information already present +in the packet. +* **discard:** Received packets which already contain relay information will +be discarded. +* **forward:** All packets are forwarded, relay information already present +will be ignored. +* **replace:** Relay information already present in a packet is stripped and +replaced with the router's own relay information set. +``` + + +### Example + +- Listen for DHCP requests on interface `eth1`. +- DHCP server is located at IPv4 address 10.0.1.4 on `eth2`. +- Router receives DHCP client requests on `eth1` and relays them to the + server at 10.0.1.4 on `eth2`. + +:::{figure} /_static/images/service_dhcp-relay01.webp +:alt: DHCP relay example +:scale: 80 % +DHCP relay example +::: + +The generated configuration will look like: + +```none +show service dhcp-relay + listen-interface eth1 + upstream-interface eth2 + server 10.0.1.4 + relay-options { + relay-agents-packets discard + } +``` + +Also, for backwards compatibility this configuration, which uses generic +interface definition, is still valid: + +```none +show service dhcp-relay + interface eth1 + interface eth2 + server 10.0.1.4 + relay-options { + relay-agents-packets discard + } +``` + + +### Operation + +```{opcmd} restart dhcp relay-agent + +Restart DHCP relay service +``` + + +## IPv6 relay + +(dhcp-relay-ipv6-configuration)= + +### Configuration + +```{cfgcmd} set service dhcpv6-relay listen-interface \<interface\> + +Set eth1 to be the listening interface for the DHCPv6 relay. + +Multiple interfaces may be specified. +``` + +```{cfgcmd} set service dhcpv6-relay upstream-interface \<interface\> address \<server\> + +Specifies an upstream network `<interface>` from which replies from +`<server>` and other relay agents will be accepted. +``` + +(dhcp-relay-ipv6-options)= + +```{cfgcmd} set service dhcpv6-relay disable + +Disable dhcpv6-relay service. +``` + +(dhcp-relay-v6-options)= + +#### Options + +```{cfgcmd} set service dhcpv6-relay max-hop-count \<count\> + +Set maximum hop count before packets are discarded, default: 10 +``` + +```{cfgcmd} set service dhcpv6-relay use-interface-id-option + +If this is set the relay agent will insert the interface ID. This option is +set automatically if more than one listening interfaces are in use. +``` + +(dhcp-relay-ipv6-example)= + +### Example + +- DHCPv6 requests are received by the router on `listening interface` `eth1` +- Requests are forwarded through `eth2` as the `upstream interface` +- External DHCPv6 server is at 2001:db8::4 + +:::{figure} /_static/images/service_dhcpv6-relay01.webp +:alt: DHCPv6 relay example +:scale: 80 % +DHCPv6 relay example +::: + +The generated configuration will look like: + +```none +commit +show service dhcpv6-relay + listen-interface eth1 { + } + upstream-interface eth2 { + address 2001:db8::4 + } +``` + +(dhcp-relay-ipv6-op-cmd)= + +### Operation + +```{opcmd} restart dhcpv6 relay-agent + +Restart DHCPv6 relay agent immediately. +```
\ No newline at end of file diff --git a/docs/configuration/service/md-dhcp-server.md b/docs/configuration/service/md-dhcp-server.md new file mode 100644 index 00000000..96c375da --- /dev/null +++ b/docs/configuration/service/md-dhcp-server.md @@ -0,0 +1,1178 @@ +(dhcp-server)= + +# DHCP Server + +VyOS uses Kea DHCP server for both IPv4 and IPv6 address assignment. + +## IPv4 server + +The network topology is declared by shared-network-name and the subnet +declarations. The DHCP service can serve multiple shared networks, with each +shared network having 1 or more subnets. Each subnet must be present on an +interface. A range can be declared inside a subnet to define a pool of dynamic +addresses. Multiple ranges can be defined and can contain holes. Static +mappings can be set to assign "static" addresses to clients based on their MAC +address. + +### Configuration + +```{cfgcmd} set service dhcp-server hostfile-update + + Create DNS record per client lease, by adding clients to /etc/hosts file. + Entry will have format: `<shared-network-name>_<hostname>.<domain-name>` +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> option domain-name \<domain-name\> + +The domain-name parameter should be the domain name that will be appended to +the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP +Option 015). + +This is the configuration parameter for the entire shared network definition. +All subnets will inherit this configuration item if not specified locally. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> option domain-search \<domain-name\> + +The domain-name parameter should be the domain name used when completing DNS +request where no full FQDN is passed. This option can be given multiple times +if you need multiple search domains (DHCP Option 119). + +This is the configuration parameter for the entire shared network definition. +All subnets will inherit this configuration item if not specified locally. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> option name-server \<address\> + +Inform client that the DNS server can be found at `<address>`. + +This is the configuration parameter for the entire shared network definition. +All subnets will inherit this configuration item if not specified locally. +Multiple DNS servers can be defined. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> option vendor-option \<option-name\> + +This configuration parameter lets you specify a vendor-option for the +entire shared network definition. All subnets will inherit this +configuration item if not specified locally. An example for Ubiquiti is +shown below: +``` + +**Example:** + + +Pass address of Unifi controller at `172.16.100.1` to all clients of `NET1` + +```none +set service dhcp-server shared-network-name 'NET1' option vendor-option +ubiquiti '172.16.100.1' +``` + + +```{cfgcmd} set service dhcp-server listen-address \<address\> + +This configuration parameter lets the DHCP server to listen for DHCP +requests sent to the specified address, it is only realistically useful for +a server whose only clients are reached via unicasts, such as via DHCP relay +agents. +``` + +#### Individual Client Subnet + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> authoritative + +This says that this device is the only DHCP server for this network. If other +devices are trying to offer DHCP leases, this machine will send 'DHCPNAK' to +any device trying to request an IP address that is not valid for this +network. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> subnet-id \<id\> + +This configuration parameter is required and must be unique to each subnet. +It is required to map subnets to lease file entries. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> option default-router \<address\> + +This is a configuration parameter for the `<subnet>`, saying that as part of +the response, tell the client that the default gateway can be reached at +`<address>`. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> option name-server \<address\> + +This is a configuration parameter for the subnet, saying that as part of the +response, tell the client that the DNS server can be found at `<address>`. + +Multiple DNS servers can be defined. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> lease \<time\> + +Assign the IP address to this machine for `<time>` seconds. + +The default value is 86400 seconds which corresponds to one day. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> range \<n\> start \<address\> + +Create DHCP address range with a range id of `<n>`. DHCP leases are taken +from this pool. The pool starts at address `<address>`. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> range \<n\> stop \<address\> + +Create DHCP address range with a range id of `<n>`. DHCP leases are taken +from this pool. The pool stops with address `<address>`. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> exclude \<address\> + +Always exclude this address from any defined range. This address will never +be assigned by the DHCP server. + +This option can be specified multiple times. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> option domain-name \<domain-name\> + +The domain-name parameter should be the domain name that will be appended to +the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP +Option 015). +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> option domain-search \<domain-name\> + +The domain-name parameter should be the domain name used when completing DNS +request where no full FQDN is passed. This option can be given multiple times +if you need multiple search domains (DHCP Option 119). +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> option vendor-option \<option-name\> + +This configuration parameter lets you specify a vendor-option for the +subnet specified within the shared network definition. An example for +Ubiquiti is shown below: +``` + +**Example:** + + +Create `172.18.201.0/24` as a subnet within `NET1` and pass address of +Unifi controller at `172.16.100.1` to clients of that subnet. + +```none +set service dhcp-server shared-network-name 'NET1' subnet +'172.18.201.0/24' option vendor-option ubiquiti '172.16.100.1' +``` + +#### Dynamic DNS Update (RFC 2136) + + +VyOS DHCP service supports RFC-2136 DDNS protocol. Based on DHCP lease change +events, DHCP server generates DDNS update requests (defines as NameChangeRequests +or NCRs) and posts them to a compliant DNS server, that will update its name +database accordingly. + + +VyOS built-in DNS Forwarder does not support DDNS, you will need an external DNS +server with RFC-2136 DDNS support. + +```{cfgcmd} set service dhcp-server dynamic-dns-update + +Enables DDNS globally. +``` + +**Behavioral settings** + + +These settings can be configured on the global level and overridden on the scope +level, i.e. for individual shared networks or subnets. See examples below. + +```{cfgcmd} set service dhcp-server dynamic-dns-update send-updates [ enable | disable ] + +If set to ``enable`` on global level, updates for all scopes will be enabled, +except if explicitly set to ``disable`` on the scope level. If set to ``disable``, +updates will only be sent for scopes, where ``send-updates`` is explicity +set to ``enable``. + +This model is followed for a few behavioral settings below: if the option is +not set, the setting is inherited from the parent scope. You can override the +parent scope setting by setting the option explicitly. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update override-no-update [ enable | disable ] + +VyOS will ignore client request not to update DNS records and send DDNS +update requests regardless. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update override-client-update [ enable | disable ] + +VyOS will override client DDNS request settings and always update both +forward and reverse DNS records. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update update-on-renew [ enable | disable ] + +Issue DDNS update requests on DHCP lease renew. In busy networks this may +generate a lot of traffic. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update conflict-resolution [ enable | disable ] + +Use RFC-4703 conflict resolution. This algorithm helps in situation when +multiple clients reserve same IP addresses or advertise identical hostnames. +Should be used in most situations. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update replace-client-name [ never | always | when-present | when-not-present ] + +* **never**: use the name sent by the client. If the client didn't provide any, +do not generate one. This is the default behavior + +* **always**: always generate a name for the client + +* **when-present**: replace the name the client sent with a generated one, if +the client didn't send any, do not generate one + +* **when-not-present**: use the name sent by the client. If the client didn't +send any, generate one for the client + +The names are generated using ``generated-prefix``, ``qualifying-suffix`` and the +client's IP address string. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update generated-prefix \<prefix\> + +Prefix used in client name generation. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update qualifying-suffix \<suffix\> + +DNS suffix used in client name generation. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update ttl-percent \<0-100\> + +TTL of the DNS record as a percentage of the DHCP lease time. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update hostname-char-set \<character string\> + +Characters, that are considered invalid in the client name. They will be replaced +with ``hostname-char-replacement`` string. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update hostname-char-replacement \<character string\> + +Replacement string for the invalid characters defined by ``hostname-char-set``. +``` + +**TSIG keys definition** + + +This is the global list of TSIG keys for DDNS updates. They need to be specified by +the name in the DNS domain definitions. + +```{cfgcmd} set service dhcp-server dynamic-dns-update tsig-key \<key-name\> algorithm \<algorithm\> + +Sets the algorithm for the TSIG key. Supported algorithms are ``hmac-md5``, +``hmac-sha1``, ``hmac-sha224``, ``hmac-sha256``, ``hmac-sha384``, ``hmac-sha512`` +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update tsig-key \<key-name\> secret \<key-secret\> + +base64-encoded TSIG key secret value +``` + +**DNS domains definition** + + +This is global configuration of DNS servers for the updatable forward and reverse +DNS domains. For every domain multiple DNS servers can be specified. + +```{cfgcmd} set service dhcp-server dynamic-dns-update [forward|reverse]-domain \<domain-name\> key-name \<tsig-key-name\> + +TSIG key used for the domain. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update [forward|reverse]-domain \<domain-name\> dns-server \<number\> address \<ip-address\> + +IP address of the DNS server. +``` + + +```{cfgcmd} set service dhcp-server dynamic-dns-update [forward|reverse]-domain \<domain-name\> dns-server \<number\> port \<port\> + +UDP port of the DNS server. ``53`` is the default. +``` + +**Example:** + + +Global configuration you will most likely want: + +```none +set service dhcp-server dynamic-dns-update send-updates enable +set service dhcp-server dynamic-dns-update conflict-resolution enable +``` + +Override the above configuration for a shared network NET1: + +```none +set service dhcp-server shared-network-name 'NET1' dynamic-dns-update replace-client-name when-not-present +set service dhcp-server shared-network-name 'NET1' dynamic-dns-update generated-prefix ip +set service dhcp-server shared-network-name 'NET1' dynamic-dns-update qualifying-suffix mybigdomain.net +``` + +And in a subnet within the same shared network: + +```none +set service dhcp-server shared-network-name 'NET1' subnet '172.18.201.0/24' dynamic-dns-update qualifying-suffix mydomain.net +``` + +Configure TSIG keys: + +```none +set service dhcp-server dynamic-dns-update tsig-key mydomain-net algorithm hmac-sha256 +set service dhcp-server dynamic-dns-update tsig-key mydomain-net secret eWF5YW15bGl0dGxla2V5IQ== +set service dhcp-server dynamic-dns-update tsig-key reverse-172-18-201 algorithm hmac-sha256 +set service dhcp-server dynamic-dns-update tsig-key reverse-172-18-201 secret eWF5YW15YW5vdGhlcmxpdHRsZWtleSE= +``` + +Configure DDNS domains: + +```none +set service dhcp-server dynamic-dns-update forward-domain mydomain.net key-name mydomain-net +set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 1 address '172.18.0.254' +set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 1 port 1053 +set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 2 address '192.168.124.254' +set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 2 port 53 +set service dhcp-server dynamic-dns-update forward-domain 201.18.172.in-addr.arpa key-name reverse-172-18-201 +set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 1 address '172.18.0.254' +set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 1 port 1053 +set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 2 address '192.168.124.254' +set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 2 port 53 +``` + +#### High Availability + + +VyOS provides High Availability support for DHCP server. DHCP High +Availability can act in two different modes: + + +- **Active-active**: both DHCP servers will respond to DHCP requests. If + `mode` is not defined, this is the default behavior. +- **Active-passive**: only `primary` server will respond to DHCP requests. + If this server goes offline, then `secondary` server will take place. + + +DHCP High Availability must be configured explicitly by the following +statements on both servers: + +```{cfgcmd} set service dhcp-server high-availability mode [active-active | active-passive] + +Define operation mode of High Availability feature. Default value if command +is not specified is `active-active` +``` + + +```{cfgcmd} set service dhcp-server high-availability source-address \<address\> + +Local IP `<address>` used when communicating to the HA peer. +``` + + +```{cfgcmd} set service dhcp-server high-availability remote \<address\> + +Remote peer IP `<address>` of the second DHCP server in this HA +cluster. +``` + + +```{cfgcmd} set service dhcp-server high-availability name \<name\> + +Define the name of the peer server to establish and identify the HA (High Availability) connection. + +:::{note} +Make sure the specified value does not conflict with the system host-name. +::: +``` + + +```{cfgcmd} set service dhcp-server high-availability status \<primary | secondary\> + +The primary and secondary statements determines whether the server is primary +or secondary. + +:::{note} +In order for the primary and the secondary DHCP server to keep +their lease tables in sync, they must be able to reach each other on TCP +port 647. If you have firewall rules in effect, adjust them accordingly. +::: +:::{hint} +The dialogue between HA partners is neither encrypted nor +authenticated. Since most DHCP servers exist within an organisation's own +secure Intranet, this would be an unnecessary overhead. However, if you +have DHCP HA peers whose communications traverse insecure networks, +then we recommend that you consider the use of VPN tunneling between them +to ensure that the HA partnership is immune to disruption +(accidental or otherwise) via third parties. +::: +``` + +#### Static mappings + + +You can specify a static DHCP assignment on a per host basis. You will need the +MAC address of the station and your desired IP address. The address must be +inside the subnet definition but can be outside of the range statement. + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> static-mapping \<description\> mac \<address\> + +Create a new DHCP static mapping named `<description>` which is valid for +the host identified by its MAC `<address>`. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> static-mapping \<description\> duid \<identifier\> + +Create a new DHCP static mapping named `<description>` which is valid for +the host identified by its DHCP unique identifier (DUID) `<identifier>`. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<name\> subnet \<subnet\> static-mapping \<description\> ip-address \<address\> + +Static DHCP IP address assign to host identified by `<description>`. IP +address must be inside the `<subnet>` which is defined but can be outside +the dynamic range created with {cfgcmd}`set service dhcp-server +shared-network-name <name> subnet <subnet> range <n>`. If no ip-address is +specified, an IP from the dynamic pool is used. + +This is useful, for example, in combination with hostfile update. + +:::{hint} +This is the equivalent of the host block in dhcpd.conf of +isc-dhcpd. +::: +``` + +**Example:** + + +- IP address `192.168.1.100` shall be statically mapped to client named `client1` + +```none +set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 subnet-id 1 +set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 static-mapping client1 ip-address 192.168.1.100 +set service dhcp-server shared-network-name 'NET1' subnet 192.168.1.0/24 static-mapping client1 mac aa:bb:11:22:33:00 +``` + +The configuration will look as follows: + +```none +show service dhcp-server shared-network-name NET1 + subnet 192.168.1.0/24 { + static-mapping client1 { + ip-address 192.168.1.100 + mac aa:bb:11:22:33:00 + } + subnet-id 1 + } +``` + +#### Relay agent information (Option 82) + + +Some DHCP relays support the injection of information into a DHCP request, depending on +where the request originated from. This is commonly used to determine the +behaviour of the DHCP server, based on the port/switch combination where the +request was first detected. I.e. the device plugged into a particular port (or +set of ports) always gets the same IP address (or range of IP addresses). This +information is usually included in the request using Option 82, hence this +is what we call this part of the configuration. + + +This behaviour is controlled in two parts. First, "client classes" are defined +which determine which inputs match. Once a positive match has been found the +request is "tagged" with this client class. Second, when the DHCP server +processes the request it checks to see if the configuration has a client class +defined. If it does then that part of the configuration will override the others + + +Client classes can be applied at either the subnet or range level, depending on +how you want the server to behave. + + +**Client Class definition** + +```{cfgcmd} set service dhcp-server client-class \<name\> relay-agent-information circuit-id \<value\> + +Create a new client class (if not already defined) and set it to match on +the "Circuit ID" part of the Option 82 field in the DHCP request. This is +sub option "1" as specified by RFC 3046. The value specified here is either +interpreted as a raw hex value, if it starts with the prefix 0x, or ASCII text +otherwise. e.g. ``e1-5`` and ``0x65312d35`` are the same +``` + + +```{cfgcmd} set service dhcp-server client-class \<name\> relay-agent-information remote-id \<value\> + +Create a new client class (if not already defined) and set it to match on +the "Remote ID" part of the Option 82 field in the DHCP request. This is +sub option "2" as specified by RFC 3046. The value specified here is either +interpreted as a raw hex value, if it starts with the prefix 0x, or ASCII text +otherwise. e.g. ``10.100.0.41`` and ``0x31302e3130302e302e3431`` are the +same +``` + +**Client Class application** + +```{cfgcmd} set service dhcp-server shared-network-name \<subnet-name\> subnet \<CIDR\> client-class \<class-name\> + +Applies the Client Class with the name `<class-name>` to the subnet `<subnet-name>`. +This means that whenever the client class matches a request it is always +routed to this subnet definition first. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \<subnet-name\> subnet \<CIDR\> range \<range-name\> client-class \<class-name\> + +Applies the Client Class with the name `<class-name>` to the range +`<range-name>` which belongs to subnet `<subnet-name>`. This means that whenever the +client class matches a request it is always routed to this range definition +first. +``` + +NB: Kea (the DHCP server used by VyOS) is programmed to offer as many +alternatives as it can to repeated DHCP Discover requests. Some operating +systems (Notably Microsoft Windows) make multiple DHCP Discover requests before +settling on an address. This particularly seems to happen when the DHCP server +isn't set to authorative. This may explain why the address you espect isn't +being chosen. Wireshark is helpful in these situations. + + +**Example:** + + +The following configuration example will classify requests coming in on port +`e1-5` from DHCP Relay `192.0.2.1` and make sure that they are allocated the +address `192.0.2.4`. Any requests which do not match the circuit and remote ID +will, instead, be allocated from the range otherRange in the usual manner. + + +NB: Both the Circuit ID and Remote ID fields are arbitrary free text. *Most* +switches set the Remote ID to the IP address of the management interface but +that should not be relied upon. Check the documentation of your DHCP Relay for +more detail or, as a measure of last resort, inspect the DHCP requests in +Wireshark. + +```none +service { + dhcp-server { + client-class className { + relay-agent-information { + circuit-id e1-5 + remote-id 192.0.2.1 + } + } + shared-network-name test { + subnet 192.0.2.0/24 { + range classNameRange { + client-class className + start 192.0.2.4 + stop 192.0.2.4 + } + range otherRange { + start 192.0.2.5 + stop 192.0.2.100 + } + subnet-id 1 + } + } + } +} +``` + +### Options + + +:::{list-table} +:header-rows: 1 +:stub-columns: 0 +:widths: 12 7 23 40 20 + +* - Setting name + - Option number + - ISC-DHCP Option name + - Option description + - Multi +* - client-prefix-length + - 1 + - subnet-mask + - Specifies the clients subnet mask as per RFC 950. If unset, + subnet declaration is used. + - N +* - time-offset + - 2 + - time-offset + - Offset of the client's subnet in seconds from Coordinated + Universal Time (UTC) + - N +* - default-router + - 3 + - routers + - IPv4 address of router on the client's subnet + - N +* - time-server + - 4 + - time-servers + - RFC 868 time server IPv4 address + - Y +* - name-server + - 6 + - domain-name-servers + - DNS server IPv4 address + - Y +* - domain-name + - 15 + - domain-name + - Client domain name + - Y +* - ip-forwarding + - 19 + - ip-forwarding + - Enable IP forwarding on client + - N +* - ntp-server + - 42 + - ntp-servers + - IP address of NTP server + - Y +* - wins-server + - 44 + - netbios-name-servers + - NetBIOS over TCP/IP name server + - Y +* - server-identifier + - 54 + - dhcp-server-identifier + - IP address for DHCP server identifier + - N +* - bootfile-server + - siaddr + - next-server + - IPv4 address of next bootstrap server + - N +* - tftp-server-name + - 66 + - tftp-server-name + - Name or IPv4 address of TFTP server + - N +* - bootfile-name + - 67 + - bootfile-name, filename + - Bootstrap file name + - N +* - bootfile-size + - 13 + - boot-size + - Boot image length in 512-octet blocks + - N +* - smtp-server + - 69 + - smtp-server + - IP address of SMTP server + - Y +* - pop-server + - 70 + - pop-server + - IP address of POP3 server + - Y +* - domain-search + - 119 + - domain-search + - Client domain search + - Y +* - static-route + - 121, 249 + - rfc3442-static-route, windows-static-route + - Classless static route + - N +* - wpad-url + - 252 + - wpad-url, wpad-url code 252 = text + - Web Proxy Autodiscovery (WPAD) URL + - N +* - lease + - + - default-lease-time, max-lease-time + - Lease timeout in seconds (default: 86400) + - N +* - range + - + - range + - DHCP lease range + - Y +* - exclude + - + - + - IP address to exclude from DHCP lease range + - Y +* - failover + - + - + - DHCP failover parameters + - +* - static-mapping + - + - + - Name of static mapping + - Y +::: + + +Multi: can be specified multiple times. + + +### Example + + +Please see the {ref}`dhcp-dns-quick-start` configuration. + + +(dhcp-server-v4-example-failover)= + + +#### High Availability + + +Configuration of a DHCP HA pair: + + +- Setup DHCP HA for network 192.0.2.0/24 +- Use active-active HA mode. +- Default gateway and DNS server is at `192.0.2.254` +- The primary DHCP server named dhcp-primary uses address `192.168.189.252` +- The secondary DHCP server with named dhcp-secondary uses address `192.168.189.253` +- DHCP range spans from `192.168.189.10` - `192.168.189.250` + + +Common configuration, valid for both primary and secondary node. + +```none +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 option default-router '192.0.2.254' +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 option name-server '192.0.2.254' +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 option domain-name 'vyos.net' +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 start '192.0.2.10' +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 stop '192.0.2.250' +set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 subnet-id '1' +``` + +**Primary** + +```none +set service dhcp-server high-availability mode 'active-active' +set service dhcp-server high-availability source-address '192.168.189.252' +set service dhcp-server high-availability name 'dhcp-secondary' +set service dhcp-server high-availability remote '192.168.189.253' +set service dhcp-server high-availability status 'primary' +``` + +**Secondary** + +```none +set service dhcp-server high-availability mode 'active-active' +set service dhcp-server high-availability source-address '192.168.189.253' +set service dhcp-server high-availability name 'dhcp-primary' +set service dhcp-server high-availability remote '192.168.189.252' +set service dhcp-server high-availability status 'secondary' +``` + +(dhcp-server-v4-example-raw)= + + +### Operation Mode + +```{opcmd} show log dhcp server + +Show DHCP server daemon log file +``` + + +```{opcmd} show log dhcp client + +Show logs from all DHCP client processes. +``` + + +```{opcmd} show log dhcp client interface \<interface\> + +Show logs from specific `interface` DHCP client process. +``` + + +```{opcmd} restart dhcp server + +Restart the DHCP server +``` + + +```{opcmd} show dhcp server statistics + +Show the DHCP server statistics: +``` + + +```none +vyos@vyos:~$ show dhcp server statistics +Pool Size Leases Available Usage +----------- ------ -------- ----------- ------- +dhcpexample 99 2 97 2% +``` + + +```{opcmd} show dhcp server statistics pool \<pool\> + +Show the DHCP server statistics for the specified pool. +``` + + +```{opcmd} show dhcp server leases + +Show statuses of all active leases: +``` + + +```none +vyos@vyos:~$ show dhcp server leases +IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname Origin +-------------- ----------------- ------- ------------------- ------------------- ----------- -------- ---------- -------- +192.168.11.134 00:50:79:66:68:09 active 2023/11/29 09:51:05 2023/11/29 10:21:05 0:24:10 LAN VPCS1 local +192.168.11.133 50:00:00:06:00:00 active 2023/11/29 09:51:38 2023/11/29 10:21:38 0:24:43 LAN VYOS-6 local +10.11.11.108 50:00:00:05:00:00 active 2023/11/29 09:51:43 2023/11/29 10:21:43 0:24:48 VIF-1001 VYOS5 local +192.168.11.135 00:50:79:66:68:07 active 2023/11/29 09:55:16 2023/11/29 09:59:16 0:02:21 remote +vyos@vyos:~$ +``` + +:::{hint} +Static mappings aren't shown. To show all states, use +`show dhcp server leases state all`. +::: + +```{opcmd} show dhcp server leases origin [local | remote] + +Show statuses of all active leases granted by local (this server) or +remote (failover server): +``` + + +```none +vyos@vyos:~$ show dhcp server leases origin remote +IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname Origin +-------------- ----------------- ------- ------------------- ------------------- ----------- -------- ---------- -------- +192.168.11.135 00:50:79:66:68:07 active 2023/11/29 09:55:16 2023/11/29 09:59:16 0:02:21 remote +vyos@vyos:~$ +``` + + +```{opcmd} show dhcp server leases pool \<pool\> + +Show only leases in the specified pool. +``` + + +```none +vyos@vyos:~$ show dhcp server leases pool LAN +IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname Origin +-------------- ----------------- ------- ------------------- ------------------- ----------- ------ ---------- -------- +192.168.11.134 00:50:79:66:68:09 active 2023/11/29 09:51:05 2023/11/29 10:21:05 0:23:55 LAN VPCS1 local +192.168.11.133 50:00:00:06:00:00 active 2023/11/29 09:51:38 2023/11/29 10:21:38 0:24:28 LAN VYOS-6 local +vyos@vyos:~$ +``` + + +```{opcmd} show dhcp server leases sort \<key\> + +Sort the output by the specified key. Possible keys: ip, hardware_address, +state, start, end, remaining, pool, hostname (default = ip) +``` + + +```{opcmd} show dhcp server leases state \<state\> + +Show only leases with the specified state. Possible states: all, active, +free, expired, released, abandoned, reset, backup (default = active) +``` + +## IPv6 server + +VyOS also provides DHCPv6 server functionality which is described in this +section. +(dhcp-server-v6-config)= + +### Configuration + +```{cfgcmd} set service dhcpv6-server preference \<preference value\> + + Clients receiving advertise messages from multiple servers choose the server + with the highest preference value. The range for this value is ``0...255``. +``` + + +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<subnet\> subnet-id \<id\> + +This configuration parameter is required and must be unique to each subnet. +It is required to map subnets to lease file entries. +``` + + +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> lease-time {default | maximum | minimum} + +The default lease time for DHCPv6 leases is 24 hours. This can be changed by +supplying a ``default-time``, ``maximum-time`` and ``minimum-time``. All +values need to be supplied in seconds. +``` + + +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option nis-domain \<domain-name\> + +A {abbr}`NIS (Network Information Service)` domain can be set to be used for +DHCPv6 clients. +``` + + +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option nisplus-domain \<domain-name\> + +The procedure to specify a {abbr}`NIS+ (Network Information Service Plus)` +domain is similar to the NIS domain one: +``` + + +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option nis-server \<address\> + +Specify a NIS server address for DHCPv6 clients. +``` + + +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option nisplus-server \<address\> + +Specify a NIS+ server address for DHCPv6 clients. +``` + + +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option sip-server \<address | fqdn\> + +Specify a {abbr}`SIP (Session Initiation Protocol)` server by IPv6 +address of Fully Qualified Domain Name for all DHCPv6 clients. +``` + + +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> option sntp-server-address \<address\> + +A SNTP server address can be specified for DHCPv6 clients. +``` + +#### Prefix Delegation + + +To hand out individual prefixes to your clients the following configuration is +used: + +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> prefix-delegation prefix \<pd-prefix\> prefix-length \<lenght\> + +Delegate prefixes from `<pd-prefix>` to clients in subnet `<prefix>`. Range +is defined by `<lenght>` in bits, 32 to 64. +``` + + +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> prefix-delegation prefix \<pd-prefix\> delegated-length \<lenght\> + +Hand out prefixes of size `<length>` in bits from `<pd-prefix>` to clients +in subnet `<prefix>` when the request for prefix delegation. +``` + + +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> prefix-delegation prefix \<pd-prefix\> excluded-prefix \<exclude-prefix\> + +Exclude `<exclude-prefix>` from `<pd-prefix>`. +``` +```{cfgcmd} set service dhcpv6-server shared-network-name \<name\> subnet \<prefix\> prefix-delegation prefix \<pd-prefix\> excluded-prefix-length \<length\> + +Define lenght of exclude prefix in `<pd-prefix>`. +``` + +**Example:** +- A shared network named `PD-NET` serves subnet `2001:db8::/64`. +- It is connected to `eth1`. +- Address pool shall be `2001:db8::100` through `2001:db8::199`. +- It hands out prefixes `2001:db8:0:10::/64` through `2001:db8:0:1f::/64`. + +```none +set service dhcpv6-server shared-network-name 'PD-NET' interface 'eth1' +set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 range 1 start 2001:db8::100 +set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 range 1 stop 2001:db8::199 +set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 prefix-delegation prefix 2001:db8:0:10:: delegated-length '64' +set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 prefix-delegation prefix 2001:db8:0:10:: prefix-length '60' +set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 subnet-id 1 +``` + +#### Address pools + +DHCPv6 address pools must be configured for the system to act as a DHCPv6 +server. The following example describes a common scenario. + +**Example:** +- A shared network named `NET1` serves subnet `2001:db8::/64` +- It is connected to `eth1` +- DNS server is located at `2001:db8::ffff` +- Address pool shall be `2001:db8::100` through `2001:db8::199`. +- Lease time will be left at the default value which is 24 hours + +```none +set service dhcpv6-server shared-network-name 'NET' interface 'eth1' +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 range 1 start 2001:db8::100 +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 range 1 stop 2001:db8::199 +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 option name-server 2001:db8::ffff +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 subnet-id 1 +``` + +The configuration will look as follows: + +```none +show service dhcpv6-server + shared-network-name NET1 { + subnet 2001:db8::/64 { + range 1 { + start 2001:db8::100 + stop 2001:db8::199 + } + option { + name-server 2001:db8::ffff + } + subnet-id 1 + } + } +``` + +(dhcp-server-v6-static-mapping)= + +#### Static mappings + +In order to map specific IPv6 addresses to specific hosts static mappings can +be created. The following example explains the process. + +**Example:** +- IPv6 address `2001:db8::101` shall be statically mapped +- IPv6 prefix `2001:db8:0:101::/64` shall be statically mapped +- Host specific mapping shall be named `client1` + +:::{hint} +The identifier is the device's DUID: colon-separated hex list (as +used by isc-dhcp option dhcpv6.client-id). If the device already has a +dynamic lease from the DHCPv6 server, its DUID can be found with `show +service dhcpv6 server leases`. The DUID begins at the 5th octet (after the +4th colon) of IAID_DUID. +::: +```none +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 ipv6-address 2001:db8::101 +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 ipv6-prefix 2001:db8:0:101::/64 +set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 duid 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff +``` + +The configuration will look as follows: + +```none +show service dhcpv6-server shared-network-name NET1 + subnet 2001:db8::/64 { + static-mapping client1 { + duid 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff + ipv6-address 2001:db8::101 + ipv6-prefix 2001:db8:0:101::/64 + } + } +``` + +(dhcp-server-v6-op-cmd)= + +### Operation Mode + +```{opcmd} show log dhcpv6 server + +Show DHCPv6 server daemon log file +``` +```{opcmd} show log dhcpv6 client + +Show logs from all DHCPv6 client processes. +``` +```{opcmd} show log dhcpv6 client interface \<interface\> + +Show logs from specific `interface` DHCPv6 client process. +``` +```{opcmd} restart dhcpv6 server + +To restart the DHCPv6 server +``` +```{opcmd} show dhcpv6 server leases + +Shows status of all assigned leases: +``` +```none +vyos@vyos:~$ show dhcpv6 server leases +IPv6 address State Last communication Lease expiration Remaining Type Pool DUID +---------------- ------- -------------------- ------------------- ----------- ----- -------- -------------------------------------------- +2001:db8::101 active 2019/12/05 19:40:10 2019/12/06 07:40:10 11:45:21 IA_NA NET1 98:76:54:32:00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff +2001:db8::102 active 2019/12/05 14:01:23 2019/12/06 02:01:23 6:06:34 IA_NA NET1 87:65:43:21:00:01:00:01:11:22:33:44:fa:fb:fc:fd:fe:ff +2001:db8:10::/64 active 2019/12/05 23:20:10 2019/12/06 11:40:10 11:45:21 IA_PD PD-NET1 98:76:54:32:00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff +``` + +:::{hint} +Static mappings aren't shown. To show all states, use `show dhcp +server leases state all`. +::: + +```{opcmd} show dhcpv6 server leases pool \<pool\> + +Show only leases in the specified pool. +``` +```{opcmd} show dhcpv6 server leases sort \<key\> + +Sort the output by the specified key. Possible keys: expires, iaid_duid, ip, +last_comm, pool, remaining, state, type (default = ip) +``` +```{opcmd} show dhcpv6 server leases state \<state\> + +Show only leases with the specified state. Possible states: abandoned, +active, all, backup, expired, free, released, reset (default = active) +```
\ No newline at end of file diff --git a/docs/configuration/service/md-dns.md b/docs/configuration/service/md-dns.md new file mode 100644 index 00000000..e7e9b457 --- /dev/null +++ b/docs/configuration/service/md-dns.md @@ -0,0 +1,582 @@ +(dns-forwarding)= + +# DNS Forwarding + +## Configuration + +VyOS provides DNS infrastructure for small networks. It is designed to be +lightweight and have a small footprint, suitable for resource constrained +routers and firewalls. For this we utilize PowerDNS recursor. + +The VyOS DNS forwarder does not require an upstream DNS server. It can serve as +a full recursive DNS server - but it can also forward queries to configurable +upstream DNS servers. By not configuring any upstream DNS servers you also +avoid being tracked by the provider of your upstream DNS server. + +```{cfgcmd} set service dns forwarding system + + Forward incoming DNS queries to the DNS servers configured under the ``system + name-server`` nodes. +``` + + +```{cfgcmd} set service dns forwarding dhcp \<interface\> + +Interfaces whose DHCP client nameservers to forward requests to. +``` + + +```{cfgcmd} set service dns forwarding name-server \<address\> port \<port\> + +Send all DNS queries to the IPv4/IPv6 DNS server specified under `<address>` +on optional port specified under `<port>`. The port defaults to 53. You can +configure multiple nameservers here. +``` + + +```{cfgcmd} set service dns forwarding domain \<domain-name\> name-server \<address\> + +Forward received queries for a particular domain +(specified via `domain-name`) to a given nameserver. Multiple nameservers +can be specified. You can use this feature for a DNS split-horizon +configuration. + +:::{note} +This also works for reverse-lookup zones (``18.172.in-addr.arpa``). +::: +``` + + +```{cfgcmd} set service dns forwarding domain \<domain-name\> addnta + +Add NTA (negative trust anchor) for this domain. This must be set if the +domain does not support DNSSEC. +``` + + +```{cfgcmd} set service dns forwarding domain \<domain-name\> recursion-desired + +Set the "recursion desired" bit in requests to the upstream nameserver. +``` + + +```{cfgcmd} set service dns forwarding allow-from \<network\> + +Given the fact that open DNS recursors could be used on DDoS amplification +attacks, you must configure the networks which are allowed to use this +recursor. A network of ``0.0.0.0/0`` or ``::/0`` would allow all IPv4 and +IPv6 networks to query this server. This is generally a bad idea. +``` + + +```{cfgcmd} set service dns forwarding dnssec \<off | process-no-validate | process | log-fail | validate\> + +The PowerDNS recursor has 5 different levels of DNSSEC processing, which can +be set with the dnssec setting. In order from least to most processing, these +are: + +* **off** In this mode, no DNSSEC processing takes place. The recursor will +not set the DNSSEC OK (DO) bit in the outgoing queries and will ignore the +DO and AD bits in queries. + +* **process-no-validate** In this mode the recursor acts as a "security +aware, non-validating" nameserver, meaning it will set the DO-bit on +outgoing queries and will provide DNSSEC related RRsets (NSEC, RRSIG) to +clients that ask for them (by means of a DO-bit in the query), except for +zones provided through the auth-zones setting. It will not do any +validation in this mode, not even when requested by the client. + +* **process** When dnssec is set to process the behavior is similar to +process-no-validate. However, the recursor will try to validate the data +if at least one of the DO or AD bits is set in the query; in that case, +it will set the AD-bit in the response when the data is validated +successfully, or send SERVFAIL when the validation comes up bogus. + +* **log-fail** In this mode, the recursor will attempt to validate all data +it retrieves from authoritative servers, regardless of the client's DNSSEC +desires, and will log the validation result. This mode can be used to +determine the extra load and amount of possibly bogus answers before +turning on full-blown validation. Responses to client queries are the same +as with process. + +* **validate** The highest mode of DNSSEC processing. In this mode, all +queries will be validated and will be answered with a SERVFAIL in case of +bogus data, regardless of the client's request. + +:::{note} +The popular Unix/Linux ``dig`` tool sets the AD-bit in the query. +This might lead to unexpected query results when testing. Set ``+noad`` +on the ``dig`` command line when this is the case. +::: + +:::{note} +The ``CD``-bit is honored correctly for process and validate. For +log-fail, failures will be logged too. +::: +``` + + +```{cfgcmd} set service dns forwarding ignore-hosts-file + +Do not use the local ``/etc/hosts`` file in name resolution. VyOS DHCP +server will use this file to add resolvers to assigned addresses. +``` + + +```{cfgcmd} set service dns forwarding cache-size \<0-2147483647\> + +Maximum number of DNS cache entries. 1 million per CPU core will generally +suffice for most installations. + +This defaults to 10000. +``` + + +```{cfgcmd} set service dns forwarding negative-ttl \<0-7200\> + +A query for which there is authoritatively no answer is cached to quickly +deny a record's existence later on, without putting a heavy load on the +remote server. In practice, caches can become saturated with hundreds of +thousands of hosts which are tried only once. + +This setting, which defaults to 3600 seconds, puts a maximum on the amount +of time negative entries are cached. +``` + + +```{cfgcmd} set service dns forwarding timeout \<10-60000\> + +The number of milliseconds to wait for a remote authoritative server to +respond before timing out and responding with SERVFAIL. + +This setting defaults to 1500 and is valid between 10 and 60000. +``` + + +```{cfgcmd} set service dns forwarding listen-address \<address\> + +The local IPv4 or IPv6 addresses to bind the DNS forwarder to. The forwarder +will listen on this address for incoming connections. +``` + + +```{cfgcmd} set service dns forwarding source-address \<address\> + +The local IPv4 or IPv6 addresses to use as a source address for sending queries. +The forwarder will send forwarded outbound DNS requests from this address. +``` + + +```{cfgcmd} set service dns forwarding no-serve-rfc1918 + +This makes the server authoritatively not aware of: 10.in-addr.arpa, +168.192.in-addr.arpa, 16-31.172.in-addr.arpa, which enabling upstream +DNS server(s) to be used for reverse lookups of these zones. +``` + +### Authoritative zones + + +The VyOS DNS forwarder can also be configured to host authoritative records for a domain. + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> disable + +Disable hosting authoritative zone for `<domain-name>` without deleting from +configuration. +``` + + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records \<type\> \<name\> disable + +Disable specific record without deleting it from configuration. +``` + + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records \<type\> \<name\> ttl \<seconds\> + +Set the {abbr}`TTL (Time-to-live)` for the record in seconds. Default is 300 seconds. +``` + +#### Record types + + +Below are a list of record types available to be configured within VyOS. Some records +support special `<name>` keywords: + + +- `@` Use @ as record name to set the record for the root domain. +- `any` Use any as record name to configure the record as a wildcard. + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records a \<name\> address \<x.x.x.x\> + +Set an {abbr}`A (Address)` record. Supports ``@`` and ``any`` keywords. +``` + + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records aaaa \<name\> address \<h:h:h:h:h:h:h:h\> + +Set an {abbr}`AAAA (IPv6 Address)` record. Supports ``@`` and ``any`` keywords. +``` + + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records cname \<name\> target \<target-domain-name\> + +Set an {abbr}`CNAME (Canonical name)` record. Supports ``@`` keyword. +``` + + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records naptr \<name\> rule \<rule-number\> \<option\> \<value\> + +Set an {abbr}`NAPTR (Naming authority pointer)` record. Supports ``@`` keyword. +NAPTR records support the following options: + +* **lookup-a** A Flag. + +* **lookup-srv** S flag. + +* **order** Rule order. Requires `<value>`. + +* **preference** Rule preference. Requires `<value>`. Defaults to 0 if not set. + +* **protocol-specific** P flag. + +* **regexp** Regular expression. Requires `<value>`. + +* **replacement** Replacement DNS name. + +* **resolve-uri** U flag. + +* **service** Service type. Requires `<value>`. +``` + + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records ns \<name\> target \<target-name\> + +Set an {abbr}`NS (Nameserver)` record. +``` + + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records ptr \<name\> target \<target-name\> + +Set an {abbr}`PTR (Pointer record)` record. Supports ``@`` keyword. +``` + + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records spf \<name\> value \<value\> + +Set an {abbr}`SPF (Sender policy framework)` record. Supports ``@`` keyword. +``` + + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records srv \<name\> entry \<entry-number\> [hostname | port | priority | weight] \<value\> + +Set an {abbr}`SRV (Service)` record. Supports ``@`` keyword. +``` + + +```{cfgcmd} set service dns forwarding authoritative-domain \<domain-name\> records txt \<name\> value \<value\> + +Set an {abbr}`TXT (Text)` record. Supports ``@`` keyword. +``` + +## Example + + +A VyOS router with two interfaces - eth0 (WAN) and eth1 (LAN) - is required to +implement a split-horizon DNS configuration for example.com. + + +In this scenario: + + +- All DNS requests for example.com must be forwarded to a DNS server + at 192.0.2.254 and 2001:db8:cafe::1 +- All other DNS requests will be forwarded to a different set of DNS servers at + 192.0.2.1, 192.0.2.2, 2001:db8::1:ffff and 2001:db8::2:ffff +- The VyOS DNS forwarder will only listen for requests on the eth1 (LAN) + interface addresses - 192.168.1.254 for IPv4 and 2001:db8::ffff for IPv6 +- The VyOS DNS forwarder will only accept lookup requests from the + LAN subnets - 192.168.1.0/24 and 2001:db8::/64 +- The VyOS DNS forwarder will pass reverse lookups for 10.in-addr.arpa, + 168.192.in-addr.arpa, 16-31.172.in-addr.arpa zones to upstream server. + +```none +set service dns forwarding domain example.com name-server 192.0.2.254 +set service dns forwarding domain example.com name-server 2001:db8:cafe::1 +set service dns forwarding name-server 192.0.2.1 +set service dns forwarding name-server 192.0.2.2 +set service dns forwarding name-server 192.0.2.3 port 853 +set service dns forwarding name-server 2001:db8::1:ffff +set service dns forwarding name-server 2001:db8::2:ffff +set service dns forwarding name-server 2001:db8::3:ffff port 8053 +set service dns forwarding listen-address 192.168.1.254 +set service dns forwarding listen-address 2001:db8::ffff +set service dns forwarding allow-from 192.168.1.0/24 +set service dns forwarding allow-from 2001:db8::/64 +set service dns forwarding no-serve-rfc1918 +``` + +## Operation + +```{opcmd} reset dns forwarding \<all | domain\> + +Resets the local DNS forwarding cache database. You can reset the cache +for all entries or only for entries to a specific domain. +``` + + +```{opcmd} restart dns forwarding + +Restarts the DNS recursor process. This also invalidates the local DNS +forwarding cache. +``` + +(dynamic-dns)= + +# Dynamic DNS + +VyOS is able to update a remote DNS record when an interface gets a new IP +address. In order to do so, VyOS includes [ddclient], a Perl script written for +this only one purpose. + +[ddclient] uses two methods to update a DNS record. The first one will send +updates directly to the DNS daemon, in compliance with {rfc}`2136`. The second +one involves a third party service, like DynDNS.com or any other such +service provider. This method uses HTTP requests to transmit the new IP address. +You can configure both in VyOS. +(dns-dynamic-config)= + +## Configuration +### {rfc}`2136` Based + +```{cfgcmd} set service dns dynamic name \<service-name\> address interface \<interface\> + + Create new dynamic DNS update configuration which will update the IP + address assigned to `<interface>` on the service you configured under + `<service-name>`. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> description \<text\> + +Set description `<text>` for dynamic DNS service being configured. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> key \<filename\> + +File identified by `<filename>` containing the TSIG authentication key for RFC2136 +nsupdate on remote DNS server. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> server \<server\> + +Configure the DNS `<server>` IP/FQDN used when updating this dynamic +assignment. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> zone \<zone\> + +Configure DNS `<zone>` to be updated. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> host-name \<record\> + +Configure DNS `<record>` which should be updated. This can be set multiple times. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> ttl \<ttl\> + +Configure optional TTL value on the given resource record. This defaults to +600 seconds. +``` + + +```{cfgcmd} set service dns dynamic interval \<60-3600\> + +Specify interval in seconds to wait between Dynamic DNS updates. +The default is 300 seconds. +``` + +(dns-dynamic-example)= + + +#### Example + + +- Register DNS record `example.vyos.io` on DNS server `ns1.vyos.io` +- Use auth key file at `/config/auth/my.key` +- Set TTL to 300 seconds + +```none +# Configuration commands entered: +# +set service dns dynamic name 'VyOS-DNS' address interface 'eth0' +set service dns dynamic name 'VyOS-DNS' description 'RFC 2136 dynamic dns service' +set service dns dynamic name 'VyOS-DNS' key '/config/auth/my.key' +set service dns dynamic name 'VyOS-DNS' server 'ns1.vyos.io' +set service dns dynamic name 'VyOS-DNS' zone 'vyos.io' +set service dns dynamic name 'VyOS-DNS' host-name 'example.vyos.io' +set service dns dynamic name 'VyOS-DNS' protocol 'nsupdate' +set service dns dynamic name 'VyOS-DNS' ttl '300' + +# Resulting config: +# +vyos@vyos# show service dns dynamic + name VyOS-DNS { + address { + interface eth0 + } + description "RFC 2136 dynamic dns service" + host-name example.vyos.io + key /config/auth/my.key + protocol nsupdate + server ns1.vyos.io + ttl 300 + zone vyos.io + } +``` + +This will render the following [ddclient] configuration entry: + +```none +# ddclient configuration for interface "eth0": +# + +# Web service dynamic DNS configuration for VyOS-DNS: [nsupdate, example.vyos.io] +use=if, \ +if=eth0, \ +protocol=nsupdate, \ +server=ns1.vyos.io, \ +zone=vyos.io, \ +password='/config/auth/my.key', \ +ttl=300 \ +example.vyos.io +``` + +:::{note} +You can also keep different DNS zone updated. Just create a new +config node: `set service dns dynamic interface <interface> rfc2136 +<other-service-name>` +::: + + +### HTTP based services + + +VyOS is also able to use any service relying on protocols supported by ddclient. + + +To use such a service, one must define a login, password, one or multiple +hostnames, protocol and server. + +```{cfgcmd} set service dns dynamic name \<service-name\> address interface \<interface\> + +Create new dynamic DNS update configuration which will update the IP +address assigned to `<interface>` on the service you configured under +`<service-name>`. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> description \<text\> + +Set description `<text>` for dynamic DNS service being configured. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> host-name \<hostname\> + +Setup the dynamic DNS hostname `<hostname>` associated with the DynDNS +provider identified by `<service-name>`. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> username \<username\> + +Configure `<username>` used when authenticating the update request for +DynDNS service identified by `<service-name>`. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> password \<password\> + +Configure `<password>` used when authenticating the update request for +DynDNS service identified by `<service-name>`. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> protocol \<protocol\> + +When a ``custom`` DynDNS provider is used, the protocol used for communicating +to the provider must be specified under `<protocol>`. See the embedded +completion helper when entering above command for available protocols. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> server \<server\> + +When a ``custom`` DynDNS provider is used the `<server>` where update +requests are being sent to must be specified. +``` + + +```{cfgcmd} set service dns dynamic name \<service-name\> ip-version 'ipv6' + +Allow explicit IPv6 address for the interface. +``` + +#### Example: + +Use deSEC (dedyn.io) as your preferred provider: + +```none +set service dns dynamic name dedyn description 'deSEC dynamic dns service' +set service dns dynamic name dedyn username 'myusername' +set service dns dynamic name dedyn password 'mypassword' +set service dns dynamic name dedyn host-name 'myhostname.dedyn.io' +set service dns dynamic name dedyn protocol 'dyndns2' +set service dns dynamic name dedyn server 'update.dedyn.io' +set service dns dynamic name dedyn address interface 'eth0' +``` + +:::{note} +Multiple services can be used per interface. Just specify as many +services per interface as you like! +::: +#### Example IPv6 only: + +```none +set service dns dynamic name dedyn description 'deSEC ipv6 dynamic dns service' +set service dns dynamic name dedyn username 'myusername' +set service dns dynamic name dedyn password 'mypassword' +set service dns dynamic name dedyn host-name 'myhostname.dedyn.io' +set service dns dynamic name dedyn protocol 'dyndns2' +set service dns dynamic name dedyn ip-version 'ipv6' +set service dns dynamic name dedyn server 'update6.dedyn.io' +set service dns dynamic name dedyn address interface 'eth0' +``` + +### Running Behind NAT + +By default, [ddclient] will update a dynamic dns record using the IP address +directly attached to the interface. If your VyOS instance is behind NAT, your +record will be updated to point to your internal IP. + +[ddclient] has another way to determine the WAN IP address. This is controlled +by: + +```{cfgcmd} set service dns dynamic name \<service-name\> address web \<url\> + +Use configured `<url>` to determine your IP address. [ddclient] will load +`<url>` and tries to extract your IP address from the response. +``` +```{cfgcmd} set service dns dynamic name \<service-name\> address web skip \<pattern\> + +ddclient will skip any address located before the string set in `<pattern>`. +``` + +[ddclient]: https://github.com/ddclient/ddclient diff --git a/docs/configuration/service/md-eventhandler.md b/docs/configuration/service/md-eventhandler.md new file mode 100644 index 00000000..48031909 --- /dev/null +++ b/docs/configuration/service/md-eventhandler.md @@ -0,0 +1,130 @@ +(event-handler)= + +# Event Handler + +## Event Handler Technology Overview + +Event handler allows you to execute scripts when a string that matches +a regex or a regex with a service name appears in journald logs. You +can pass variables, arguments, and a full matching string to the script. + +## How to configure Event Handler + +> [1. Create an event handler](#create-an-event-handler) +> +> [2. Add regex to the script](#add-regex-to-the-script) +> +> [3. Add a full path to the script](#add-a-full-path-to-the-script) +> +> [4. Add optional parameters](#add-optional-parameters) + +## Event Handler Configuration Steps + +### 1. Create an event handler + +```{cfgcmd} set service event-handler event \<event-handler name\> + +This is an optional command because the event handler will be +automatically created after any of the next commands. +``` + + +### 2. Add regex to the script + +```{cfgcmd} set service event-handler event \<event-handler name\> filter pattern \<regex\> + +This is a mandatory command. Sets regular expression to match +against log string message. + +:::{note} +The regular expression matches if and only if the entire +string matches the pattern. +::: +``` + + +### 3. Add a full path to the script + +```{cfgcmd} set service event-handler event \<event-handler name\> script path \<path to script\> + +This is a mandatory command. Sets the full path to the script. +The script file must be executable. +``` + + +### 4. Add optional parameters + +```{cfgcmd} set service event-handler event \<event-handler name\> filter syslog-identifier \<syslogid name\> + +This is an optional command. Filters log messages by +syslog-identifier. +``` + +```{cfgcmd} set service event-handler event \<event-handler name\> script environment \<env name\> value \<env value\> + +This is an optional command. Adds environment and its value to +the script. Use separate commands for each environment. + +One implicit environment exists. + +* ``message``: Full message that has triggered the script. +``` + +```{cfgcmd} set service event-handler event \<event-handler name\> script arguments \<arguments\> + +This is an optional command. Adds arguments to the script. +Arguments must be separated by spaces. + +:::{note} +We don't recommend to use arguments. Using environments +is more preferable. +::: +``` + + +## Example + +Event handler that monitors the state of interface eth0. + +```none +set service event-handler event INTERFACE_STATE_DOWN filter pattern '.*eth0.*,RUNNING,.*->.*' +set service event-handler event INTERFACE_STATE_DOWN filter syslog-identifier 'netplugd' +set service event-handler event INTERFACE_STATE_DOWN script environment interface_action value 'down' +set service event-handler event INTERFACE_STATE_DOWN script environment interface_name value 'eth0' +set service event-handler event INTERFACE_STATE_DOWN script path '/config/scripts/eventhandler.py' +``` + +Event handler script + +```none +#!/usr/bin/env python3 +# +# VyOS event-handler script example +from os import environ +import subprocess +from sys import exit + +# Perform actions according to requirements +def process_event() -> None: + # Get variables + message_text = environ.get('message') + interface_name = environ.get('interface_name') + interface_action = environ.get('interface_action') + # Print the message that triggered this script + print(f'Logged message: {message_text}') + # Prepare a command to run + command = f'sudo ip link set {interface_name} {interface_action}'.split() + # Execute a command + subprocess.run(command) + +if __name__ == '__main__': + try: + # Run script actions and exit + process_event() + exit(0) + except Exception as err: + # Exit properly in case if something in the script goes wrong + print(f'Error running script: {err}') + exit(1) +``` + diff --git a/docs/configuration/service/md-https.md b/docs/configuration/service/md-https.md new file mode 100644 index 00000000..184fd088 --- /dev/null +++ b/docs/configuration/service/md-https.md @@ -0,0 +1,138 @@ +(http-api)= + +# HTTP API + +VyOS provide an HTTP API. You can use it to execute op-mode commands, +update VyOS, set or delete config. + +Please take a look at the {ref}`vyosapi` page for an detailed how-to. + +## Configuration + +```{cfgcmd} set service https allow-client address \<address\> + +Only allow certain IP addresses or prefixes to access the https +webserver. +``` + +```{cfgcmd} set service https certificates ca-certificate \<name\> + +Use CA certificate from PKI subsystem +``` + +```{cfgcmd} set service https certificates certificate \<name\> + +Use certificate from PKI subsystem +``` + +```{cfgcmd} set service https certificates dh-params \<name\> + +Use {abbr}`DH (Diffie–Hellman)` parameters from PKI subsystem. +Must be at least 2048 bits in length. +``` + +```{cfgcmd} set service https listen-address \<address\> + +Webserver should only listen on specified IP address +``` + +```{cfgcmd} set service https port \<number\> + +Webserver should listen on specified port. + +Default: 443 +``` + +```{cfgcmd} set service https enable-http-redirect + +Enable automatic redirect from http to https. +``` + +```{cfgcmd} set service https tls-version \<1.2 | 1.3\> + +Select TLS version used. + +This defaults to both 1.2 and 1.3. +``` + +```{cfgcmd} set service https vrf \<name\> + +Start Webserver in given VRF. +``` + +```{cfgcmd} set service https request-body-size-limit \<size\> + +Set the maximum request body size in megabytes. Default is 1MB. +``` + + +### API + +```{cfgcmd} set service https api keys id \<name\> key \<apikey\> + +Set a named api key. Every key has the same, full permissions +on the system. +``` + + +### REST + +```{cfgcmd} set service https api rest + +Enable REST API +``` + +```{cfgcmd} set service https api rest debug + +To enable debug messages. Available via {opcmd}`show log` or +{opcmd}`monitor log` +``` + +```{cfgcmd} set service https api rest strict + +Enforce strict path checking. +``` + + +### GraphQL + +```{cfgcmd} set service https api graphql introspection + +Enable GraphQL Schema introspection. +``` + +:::{note} +Do not leave introspection enabled in production, it is a security risk. +::: + +```{cfgcmd} set service https api graphql authentication type \<key | token\> + +Set the authentication type for GraphQL, default option is key. Available options are: +* ``key`` use API keys configured in ``service https api keys`` +* ``token`` use JWT tokens. +``` + +```{cfgcmd} set service https api graphql authentication expiration + +Set the lifetime for JWT tokens in seconds. Default is 3600 seconds. +``` + +```{cfgcmd} set service https api graphql authentication secret-length + +Set the byte length of the JWT secret. Default is 32. +``` + +```{cfgcmd} set service https api graphql cors allow-origin \<origin\> + +Allow cross-origin requests from \<origin\>. +``` + + +## Example Configuration + +Setting REST API and an API-KEY is the minimal configuration to get a working API Endpoint. + +```none +set service https api keys id MY-HTTPS-API-ID key MY-HTTPS-API-PLAINTEXT-KEY +set service https api rest +``` diff --git a/docs/configuration/service/md-index.md b/docs/configuration/service/md-index.md new file mode 100644 index 00000000..4018c5be --- /dev/null +++ b/docs/configuration/service/md-index.md @@ -0,0 +1,29 @@ +# Service + +```{toctree} +:includehidden: true +:maxdepth: 1 + +broadcast-relay +config-sync +conntrack-sync +console-server +dhcp-relay +dhcp-server +dns +eventhandler +https +ipoe-server +lldp +mdns +monitoring +ntp +pppoe-server +router-advert +salt-minion +snmp +ssh +tftp-server +webproxy +suricata +``` diff --git a/docs/configuration/service/md-ipoe-server.md b/docs/configuration/service/md-ipoe-server.md new file mode 100644 index 00000000..88ec4f51 --- /dev/null +++ b/docs/configuration/service/md-ipoe-server.md @@ -0,0 +1,512 @@ +(ipoe-server)= + +# IPoE Server + +VyOS utilizes [accel-ppp] to provide {abbr}`IPoE (Internet Protocol over +Ethernet)` server functionality. It can be used with local authentication +(mac-address) or a connected RADIUS server. + +IPoE is a method of delivering an IP payload over an Ethernet-based access +network or an access network using bridged Ethernet over Asynchronous Transfer +Mode (ATM) without using PPPoE. It directly encapsulates the IP datagrams in +Ethernet frames, using the standard {rfc}`894` encapsulation. + +The use of IPoE addresses the disadvantage that PPP is unsuited for multicast +delivery to multiple users. Typically, IPoE uses Dynamic Host Configuration +Protocol and Extensible Authentication Protocol to provide the same +functionality as PPPoE, but in a less robust manner. + +:::{note} +Please be aware, due to an upstream bug, config changes/commits +will restart the ppp daemon and will reset existing IPoE sessions, +in order to become effective. +::: + +## Configuring IPoE Server + +IPoE can be configured on different interfaces, it will depend on each specific +situation which interface will provide IPoE to clients. The client's mac address +and the incoming interface is being used as control parameter, to authenticate +a client. + +The example configuration below will assign an IP to the client on the incoming +interface eth1 with the client mac address 00:50:79:66:68:00. Other DHCP +discovery requests will be ignored, unless the client mac has been enabled in +the configuration. + +```none +set interfaces ethernet eth1 address '192.168.0.1/24' +set service ipoe-server authentication interface eth1.100 mac 00:50:79:66:68:00 +set service ipoe-server authentication interface eth1.101 mac 00:50:79:66:68:01 +set service ipoe-server authentication mode 'local' +set service ipoe-server client-ip-pool IPOE-POOL range '192.168.0.2-192.168.0.254' +set service ipoe-server default-pool 'IPOE-POOL' +set service ipoe-server gateway-address '192.168.0.1/24' +set service ipoe-server interface eth1 mode 'l2' +set service ipoe-server interface eth1 network 'vlan' +set service ipoe-server interface eth1 vlan '100-200' +``` + +```{cfgcmd} set service ipoe-server authentication interface \<interface\> mac \<MAC\> + +Creates local IPoE user with username=\*\*\<interface\>\*\* and +password=\*\*\<MAC\>\*\* (mac-address) +``` + + +```{cfgcmd} set service ipoe-server authentication mode \<local | radius\> + +Set authentication backend. The configured authentication backend is used +for all queries. + +* **radius**: All authentication queries are handled by a configured RADIUS +server. +* **local**: All authentication queries are handled locally. +* **noauth**: Authentication disabled +``` + + +```{cfgcmd} set service ipoe-server client-ip-pool \<POOL-NAME\> range \<x.x.x.x-x.x.x.x | x.x.x.x/x\> + +Use this command to define the first IP address of a pool of +addresses to be given to IPoE clients. If notation ``x.x.x.x-x.x.x.x``, +it must be within a /24 subnet. If notation ``x.x.x.x/x`` is +used there is possibility to set host/netmask. +``` + + +```{cfgcmd} set service ipoe-server default-pool \<POOL-NAME\> + +Use this command to define default address pool name. +``` + + +```{cfgcmd} set service ipoe-server gateway-address \<x.x.x.x/x\> + +Specifies address to be used as server ip address if radius can assign +only client address. In such case if client address is matched network +and mask then specified address and mask will be used. You can specify +multiple such options. +``` + + +```{cfgcmd} set service ipoe-server interface \<interface\> mode \<l2 | l3\> + +> Specifies the client connectivity mode. + +* **l2**: It means that clients are on same network where interface +is.\*\*(default)\*\* +* **l3**: It means that client are behind some router. +``` + + +```{cfgcmd} set service ipoe-server interface \<interface\> network \<shared | vlan\> + +Specify where interface is shared by multiple users or it is vlan-per-user. + +* **shared**: Multiple clients share the same network. **(default)** +* **vlan**: One VLAN per client. +``` + + +```none +vyos@vyos:~$ show ipoe-server sessions + + ifname | username | calling-sid | ip | rate-limit | type | comp | state | uptime +--------+----------+-------------------+-------------+------------+------+------+--------+---------- + ipoe0 | eth1.100 | 00:50:79:66:68:00 | 192.168.0.2 | | ipoe | | active | 00:04:55 + ipoe1 | eth1.101 | 00:50:79:66:68:01 | 192.168.0.3 | | ipoe | | active | 00:04:44 +``` + +## Configuring RADIUS authentication + + +To enable RADIUS based authentication, the authentication mode needs to be +changed within the configuration. Previous settings like the local users, still +exists within the configuration, however they are not used if the mode has been +changed from local to radius. Once changed back to local, it will use all local +accounts again. + +```none +set service ipoe-server authentication mode radius +``` + + +```{cfgcmd} set service ipoe-server authentication radius server \<server\> key \<secret\> + +Configure RADIUS *\<server\>* and its required shared *\<secret\>* for +communicating with the RADIUS server. +``` + +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. +For example: + +```none +set service ipoe-server authentication radius server 10.0.0.1 key 'foo' +set service ipoe-server authentication radius server 10.0.0.2 key 'foo' +``` + +:::{note} +Some RADIUS severs use an access control list which allows or denies +queries, make sure to add your VyOS router to the allowed client list. +::: + + +### RADIUS source address + + +If you are using OSPF as IGP, always the closest interface connected to the +RADIUS server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests +to a single source IP e.g. the loopback interface. + +```{cfgcmd} set service ipoe-server authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. +``` + +:::{note} +The ``source-address`` must be configured on one of VyOS interface. +Best practice would be a loopback or dummy interface. +::: + + +### RADIUS advanced options + +```{cfgcmd} set service ipoe-server authentication radius server \<server\> port \<port\> + +Configure RADIUS *\<server\>* and its required port for authentication requests. +``` + + +```{cfgcmd} set service ipoe-server authentication radius server \<server\> fail-time \<time\> + +Mark RADIUS server as offline for this given *\<time\>* in seconds. +``` + + +```{cfgcmd} set service ipoe-server authentication radius server \<server\> disable + +Temporary disable this RADIUS server. +``` + + +```{cfgcmd} set service ipoe-server authentication radius acct-timeout \<timeout\> + +Timeout to wait reply for Interim-Update packets. (default 3 seconds) +``` + + +```{cfgcmd} set service ipoe-server authentication radius dynamic-author server \<address\> + +Specifies IP address for Dynamic Authorization Extension server (DM/CoA). +This IP must exist on any VyOS interface or it can be ``0.0.0.0``. +``` + + +```{cfgcmd} set service ipoe-server authentication radius dynamic-author port \<port\> + +UDP port for Dynamic Authorization Extension server (DM/CoA) +``` + + +```{cfgcmd} set service ipoe-server authentication radius dynamic-author key \<secret\> + +Secret for Dynamic Authorization Extension server (DM/CoA) +``` + + +```{cfgcmd} set service ipoe-server authentication radius max-try \<number\> + +Maximum number of tries to send Access-Request/Accounting-Request queries +``` + + +```{cfgcmd} set service ipoe-server authentication radius timeout \<timeout\> + +Timeout to wait response from server (seconds) +``` + + +```{cfgcmd} set service ipoe-server authentication radius nas-identifier \<identifier\> + +Value to send to RADIUS server in NAS-Identifier attribute and to be matched +in DM/CoA requests. +``` + + +```{cfgcmd} set service ipoe-server authentication radius nas-ip-address \<address\> + +Value to send to RADIUS server in NAS-IP-Address attribute and to be matched +in DM/CoA requests. Also DM/CoA server will bind to that address. +``` + + +```{cfgcmd} set service ipoe-server authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. +``` + + +```{cfgcmd} set service ipoe-server authentication radius rate-limit attribute \<attribute\> + +Specifies which RADIUS server attribute contains the rate limit information. +The default attribute is *Filter-Id*. +``` + +:::{note} +If you set a custom RADIUS attribute you must define it on both +dictionaries at RADIUS server and client. +::: + +```{cfgcmd} set service ipoe-server authentication radius rate-limit enable + +Enables bandwidth shaping via RADIUS. +``` + + +```{cfgcmd} set service ipoe-server authentication radius rate-limit vendor + +Specifies the vendor dictionary, dictionary needs to be in +/usr/share/accel-ppp/radius. +``` + +Received RADIUS attributes have a higher priority than parameters defined within +the CLI configuration, refer to the explanation below. + + +### Allocation clients ip addresses by RADIUS + + +If the RADIUS server sends the attribute ``Framed-IP-Address`` then this IP +address will be allocated to the client and the option ``default-pool`` within the CLI +config is being ignored. + + +If the RADIUS server sends the attribute ``Framed-Pool``, IP address will be allocated +from a predefined IP pool whose name equals the attribute value. + + +If the RADIUS server sends the attribute ``Stateful-IPv6-Address-Pool``, IPv6 address +will be allocated from a predefined IPv6 pool ``prefix`` whose name equals the attribute value. + + +If the RADIUS server sends the attribute ``Delegated-IPv6-Prefix-Pool``, IPv6 +delegation pefix will be allocated from a predefined IPv6 pool ``delegate`` +whose name equals the attribute value. + + +:::{note} +``Stateful-IPv6-Address-Pool`` and ``Delegated-IPv6-Prefix-Pool`` are defined in +RFC6911. If they are not defined in your RADIUS server, add new [dictionary]. +::: + + +User interface can be put to VRF context via RADIUS Access-Accept packet, or change +it via RADIUS CoA. ``Accel-VRF-Name`` is used from these purposes. It is custom [ACCEL-PPP attribute]. +Define it in your RADIUS server. + + +## IPv6 + +```{cfgcmd} set service ipoe-server client-ipv6-pool \<IPv6-POOL-NAME\> prefix \<address\> mask \<number-of-bits\> + +Use this comand to set the IPv6 address pool from which an IPoE client +will get an IPv6 prefix of your defined length (mask) to terminate the +IPoE endpoint at their side. The mask length can be set from 48 to 128 +bit long, the default value is 64. +``` + + +```{cfgcmd} set service ipoe-server client-ipv6-pool \<IPv6-POOL-NAME\> delegate \<address\> delegation-prefix \<number-of-bits\> + +Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on +IPoE. You will have to set your IPv6 pool and the length of the +delegation prefix. From the defined IPv6 pool you will be handing out +networks of the defined length (delegation-prefix). The length of the +delegation prefix can be set from 32 to 64 bit long. +``` + + +```{cfgcmd} set service ipoe-server default-ipv6-pool \<IPv6-POOL-NAME\> + +Use this command to define default IPv6 address pool name. +``` + + +```none +set service ipoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' +set service ipoe-server client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' +set service ipoe-server default-ipv6-pool IPv6-POOL +``` + +## Scripting + +```{cfgcmd} set service ipoe-server extended-scripts on-change \<path_to_script\> + +Script to run when session interface changed by RADIUS CoA handling +``` + + +```{cfgcmd} set service ipoe-server extended-scripts on-down \<path_to_script\> + +Script to run when session interface going to terminate +``` + + +```{cfgcmd} set service ipoe-server extended-scripts on-pre-up \<path_to_script\> + +Script to run before session interface comes up +``` + + +```{cfgcmd} set service ipoe-server extended-scripts on-up \<path_to_script\> + +Script to run when session interface is completely configured and started +``` + +## Advanced Options + + +### Authentication Advanced Options + +```{cfgcmd} set service ipoe-server authentication interface \<interface\> mac \<MAC\> vlan \<vlan-id\> + +VLAN monitor for automatic creation of VLAN interfaces for specific user on specific \<interface\> +``` + + +```{cfgcmd} set service ipoe-server authentication interface \<interface\> mac \<MAC\> rate-limit download \<bandwidth\> + +Download bandwidth limit in kbit/s for user on interface *\<interface\>*. +``` + + +```{cfgcmd} set service ipoe-server authentication interface \<interface\> mac \<MAC\> rate-limit upload \<bandwidth\> + +Upload bandwidth limit in kbit/s for for user on interface *\<interface\>*. +``` + +### Client IP Pool Advanced Options + +```{cfgcmd} set service ipoe-server client-ip-pool \<POOL-NAME\> next-pool \<NEXT-POOL-NAME\> + +Use this command to define the next address pool name. +``` + +### Advanced Interface Options + +```{cfgcmd} set service ipoe-server interface \<interface\> client-subnet \<x.x.x.x/x\> + +Specify local range of ip address to give to dhcp clients. First IP in range is router IP. +If you need more customization use *client-ip-pool* +``` + + +```{cfgcmd} set service ipoe-server interface \<interface\> external-dhcp dhcp-relay \<x.x.x.x\> + +Specify DHCPv4 relay IP address to pass requests to. If specified giaddr is also needed. +``` + + +```{cfgcmd} set service ipoe-server interface \<interface\> external-dhcp giaddr \<x.x.x.x\> + +Specifies relay agent IP addre +``` + +### Global Advanced options + +```{cfgcmd} set service ipoe-server description \<description\> + +Set description. +``` +```{cfgcmd} set service ipoe-server limits burst \<value\> + +Burst count +``` +```{cfgcmd} set service ipoe-server limits connection-limit \<value\> + +Acceptable rate of connections (e.g. 1/min, 60/sec) +``` +```{cfgcmd} set service ipoe-server limits timeout \<value\> + +Timeout in seconds +``` +```{cfgcmd} set service ipoe-server max-concurrent-sessions + +Maximum number of concurrent session start attempts +``` +```{cfgcmd} set service ipoe-server name-server \<address\> + +Connected client should use *\<address\>* as their DNS server. This +command accepts both IPv4 and IPv6 addresses. Up to two nameservers +can be configured for IPv4, up to three for IPv6. +``` +```{cfgcmd} set service ipoe-server shaper fwmark \<1-2147483647\> + +Match firewall mark value +``` +```{cfgcmd} set service ipoe-server snmp master-agent + +Enable SNMP +``` + +## Monitoring + +```{opcmd} show ipoe-server sessions + +Use this command to locally check the active sessions in the IPoE +server. +``` +```none +vyos@vyos:~$ show ipoe-server sessions +ifname | username | calling-sid | ip | rate-limit | type | comp | state | uptime +----------+----------+-------------------+-------------+------------+------+------+--------+---------- + eth1.100 | eth1.100 | 0c:98:bd:b8:00:01 | 192.168.0.3 | | ipoe | | active | 03:03:58 +``` + +```none +vyos@vyos:~$ show ipoe-server statistics +uptime: 0.03:31:36 +cpu: 0% +mem(rss/virt): 6044/101360 kB +core: + mempool_allocated: 148628 + mempool_available: 144748 + thread_count: 1 + thread_active: 1 + context_count: 10 + context_sleeping: 0 + context_pending: 0 + md_handler_count: 6 + md_handler_pending: 0 + timer_count: 1 + timer_pending: 0 +sessions: + starting: 0 + active: 1 + finishing: 0 +ipoe: + starting: 0 + active: 1 + delayed: 0 +``` + +## Toubleshooting + +```none +vyos@vyos:~$ show log ipoe-server + +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:: recv [DHCPv4 Discover xid=55df9228 chaddr=0c:98:bd:b8:00:01 <Message-Type Discover> <Request-IP 192.168.0.3> <Host-Name vyos> <Request-List Subnet,Broadcast,Router,DNS,Classless-Route,Domain-Name,MTU>] +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: eth1.100: authentication succeeded +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: send [DHCPv4 Offer xid=55df9228 yiaddr=192.168.0.4 chaddr=0c:98:bd:b8:00:01 <Message-Type Offer> <Server-ID 192.168.0.1> <Lease-Time 600> <T1 300> <T2 525> <Router 192.168.0.1> <Subnet 255.255.255.0>] +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: recv [DHCPv4 Request xid=55df9228 chaddr=0c:98:bd:b8:00:01 <Message-Type Request> <Server-ID 192.168.0.1> <Request-IP 192.168.0.4> <Host-Name vyos> <Request-List Subnet,Broadcast,Router,DNS,Classless-Route,Domain-Name,MTU>] +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: activate session +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: no free IPv6 address +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: ipoe: session started +Feb 27 14:29:27 vyos accel-ipoe[2262]: eth1.100:eth1.100: send [DHCPv4 Ack xid=55df9228 yiaddr=192.168.0.4 chaddr=0c:98:bd:b8:00:01 <Message-Type Ack> <Server-ID 192.168.0.1> <Lease-Time 600> <T1 300> <T2 525> <Router 192.168.0.1> <Subnet 255.255.255.0>] +``` + +[accel-ppp]: https://accel-ppp.org/ +[accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel +[dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 diff --git a/docs/configuration/service/md-lldp.md b/docs/configuration/service/md-lldp.md new file mode 100644 index 00000000..7fdba6c8 --- /dev/null +++ b/docs/configuration/service/md-lldp.md @@ -0,0 +1,154 @@ +(lldp)= + +# LLDP + +{abbr}`LLDP (Link Layer Discovery Protocol)` is a vendor-neutral link layer +protocol in the Internet Protocol Suite used by network devices for advertising +their identity, capabilities, and neighbors on an IEEE 802 local area network, +principally wired Ethernet. The protocol is formally referred to by the IEEE +as Station and Media Access Control Connectivity Discovery specified in IEEE +802.1AB and IEEE 802.3-2012 section 6 clause 79. + +LLDP performs functions similar to several proprietary protocols, such as +{abbr}`CDP (Cisco Discovery Protocol)`, +{abbr}`FDP (Foundry Discovery Protocol)`, +{abbr}`NDP (Nortel Discovery Protocol)` and {abbr}`LLTD (Link Layer Topology +Discovery)`. + +Information gathered with LLDP is stored in the device as a {abbr}`MIB +(Management Information Database)` and can be queried with {abbr}`SNMP (Simple +Network Management Protocol)` as specified in {rfc}`2922`. The topology of an +LLDP-enabled network can be discovered by crawling the hosts and querying this +database. Information that may be retrieved include: + +- System Name and Description +- Port name and description +- VLAN name +- IP management address +- System capabilities (switching, routing, etc.) +- MAC/PHY information +- MDI power +- Link aggregation + +## Configuration + +```{cfgcmd} set service lldp + +Enable LLDP service +``` + +```{cfgcmd} set service lldp management-address \<address\> + +Define IPv4/IPv6 management address transmitted via LLDP. Multiple addresses +can be defined. Only addresses connected to the system will be transmitted. +``` + +```{cfgcmd} set service lldp interface \<interface\> + +Enable transmission of LLDP information on given \<interface\>. You can also +say ``all`` here so LLDP is turned on on every interface. +``` + +```{cfgcmd} set service lldp interface \<interface\> mode [disable|rx-tx|rx|tx] + +Configure the administrative status of the given port. + +By default, all ports are configured to be in rx-tx mode. This means they +can receive and transmit LLDP frames. + +In rx mode, they won't emit any frames. In tx mode, they won't receive +any frames. In disabled mode, no frame will be sent and any incoming frame +will be discarded. +``` + +```{cfgcmd} set service lldp snmp + +Enable SNMP queries of the LLDP database +``` + +```{cfgcmd} set service lldp legacy-protocols \<cdp|edp|fdp|sonmp\> + +Enable given legacy protocol on this LLDP instance. Legacy protocols include: +* ``cdp`` - Listen for CDP for Cisco routers/switches +* ``edp`` - Listen for EDP for Extreme routers/switches +* ``fdp`` - Listen for FDP for Foundry routers/switches +* ``sonmp`` - Listen for SONMP for Nortel routers/switches +``` + + +## Operation + +```{opcmd} show lldp neighbors + +Displays information about all neighbors discovered via LLDP. + +:::{code-block} none +vyos@vyos:~$ show lldp neighbors +Capability Codes: R - Router, B - Bridge, W - Wlan r - Repeater, S - Station + D - Docsis, T - Telephone, O - Other + +Device ID Local Proto Cap Platform Port ID +--------- ----- ----- --- -------- ------- +BR2.vyos.net eth0 LLDP R VyOS 1.2.4 eth1 +BR3.vyos.net eth0 LLDP RB VyOS 1.2.4 eth2 +SW1.vyos.net eth0 LLDP B Cisco IOS Software GigabitEthernet0/6 +::: +``` + +```{opcmd} show lldp neighbors detail + +Get detailed information about LLDP neighbors. + +:::{code-block} none +vyos@vyos:~$ show lldp neighbors detail +------------------------------------------------------------------------------- +LLDP neighbors: +------------------------------------------------------------------------------- +Interface: eth0, via: LLDP, RID: 28, Time: 0 day, 00:24:33 +Chassis: + ChassisID: mac 00:53:00:01:02:c9 + SysName: BR2.vyos.net + SysDescr: VyOS 1.3-rolling-201912230217 + MgmtIP: 192.0.2.1 + MgmtIP: 2001:db8::ffff + Capability: Bridge, on + Capability: Router, on + Capability: Wlan, off + Capability: Station, off +Port: + PortID: mac 00:53:00:01:02:c9 + PortDescr: eth0 + TTL: 120 + PMD autoneg: supported: no, enabled: no + MAU oper type: 10GigBaseCX4 - X copper over 8 pair 100-Ohm balanced cable +VLAN: 201 eth0.201 +VLAN: 205 eth0.205 +LLDP-MED: + Device Type: Network Connectivity Device + Capability: Capabilities, yes + Capability: Policy, yes + Capability: Location, yes + Capability: MDI/PSE, yes + Capability: MDI/PD, yes + Capability: Inventory, yes + Inventory: + Hardware Revision: None + Software Revision: 4.19.89-amd64-vyos + Firmware Revision: 6.00 + Serial Number: VMware-42 1d 83 b9 fe c1 bd b2-7 + Manufacturer: VMware, Inc. + Model: VMware Virtual Platform + Asset ID: No Asset Tag +------------------------------------------------------------------------------- +::: +``` + +```{opcmd} show lldp neighbors interface \<interface\> + +Show LLDP neighbors connected via interface \<interface\>. +``` + +```{opcmd} show log lldp + +Used for troubleshooting. +```
\ No newline at end of file diff --git a/docs/configuration/service/md-mdns.md b/docs/configuration/service/md-mdns.md new file mode 100644 index 00000000..088bca3c --- /dev/null +++ b/docs/configuration/service/md-mdns.md @@ -0,0 +1,131 @@ +# mDNS Repeater + +Starting with VyOS 1.2 a {abbr}`mDNS (Multicast DNS)` repeater functionality is +provided. Additional information can be obtained from +<https://en.wikipedia.org/wiki/Multicast_DNS>. + +Multicast DNS uses the reserved address `224.0.0.251`, which is +"administratively scoped" and does not leave the subnet. mDNS repeater +retransmits mDNS packets from one interface to other interfaces. This enables +support for devices using mDNS discovery (like network printers, Apple Airplay, +Chromecast, various IP based home-automation devices etc) across multiple VLANs. + +Since the mDNS protocol sends the {abbr}`AA(Authoritative Answer)` records in +the packet itself, the repeater does not need to forge the source address. +Instead, the source address is of the interface that repeats the packet. + +:::{note} +You can not run this in a VRRP setup, if multiple mDNS repeaters +are launched in a subnet you will experience the mDNS packet storm death! +::: + +## Configuration + +```{cfgcmd} set service mdns repeater interface \<interface\> + +To enable mDNS repeater you need to configure at least two interfaces so that +all incoming mDNS packets from one interface configured here can be +re-broadcasted to any other interface(s) configured under this section. +``` + +```{cfgcmd} set service mdns repeater disable + +mDNS repeater can be temporarily disabled without deleting the service using +``` + +```{cfgcmd} set service mdns repeater ip-version \<ipv4 | ipv6 | both\> + +mDNS repeater can be enabled either on IPv4 socket or on IPv6 socket or both +to re-broadcast. By default, mDNS repeater will listen on both IPv4 and IPv6. +``` + +```{cfgcmd} set service mdns repeater allow-service \<service\> + +mDNS repeater can be configured to re-broadcast only specific services. By +default, all services are re-broadcasted. +``` + +```{cfgcmd} set service mdns repeater browse-domain \<domain\> + +Allow listing additional custom domains to be browsed (in addition to the +default ``local``) so that they can be reflected. +``` + +```{cfgcmd} set service mdns repeater cache-entries \<entries\> + +Specify how many resource records are cached per interface. Bigger values +allow mDNS work correctly in large LANs but also increase memory consumption. + +Defaults to: 4096 +``` + + +## Firewall recommendations + +Unlike typical routed traffic, mDNS packets relayed between interfaces do not +traverse the FORWARD hook chain in the firewall. Instead, they are processed +through the following hooks: +> - **INPUT**: For packets received by the local system +> - **OUTPUT**: For packets sent from the local system + +To control or allow mDNS packet forwarding via the relay, you must define +appropriate rules in the INPUT and OUTPUT directions. Rules in the FORWARD +direction will have no effect on mDNS relay traffic. + +```none +set firewall ipv4 input filter rule 10 action 'accept' +set firewall ipv4 input filter rule 10 destination address '224.0.0.251' +set firewall ipv4 input filter rule 10 destination port '5353' +set firewall ipv4 input filter rule 10 protocol 'udp' +set firewall ipv4 output filter rule 10 action 'accept' +set firewall ipv4 output filter rule 10 destination address '224.0.0.251' +set firewall ipv4 output filter rule 10 destination port '5353' +set firewall ipv4 output filter rule 10 protocol 'udp' +``` + + +## Example + +To listen on both `eth0` and `eth1` mDNS packets and also repeat packets +received on `eth0` to `eth1` (and vice-versa) use the following commands: + +```none +set service mdns repeater interface 'eth0' +set service mdns repeater interface 'eth1' +``` + +To allow only specific services, for example `_airplay._tcp` or `_ipp._tcp`, +(instead of all services) to be re-broadcasted, use the following command: + +```none +set service mdns repeater allow-service '_airplay._tcp' +set service mdns repeater allow-service '_ipp._tcp' +``` + +To allow listing additional custom domain, for example +`openthread.thread.home.arpa`, so that it can reflected in addition to the +default `local`, use the following command: + +```none +set service mdns repeater browse-domain 'openthread.thread.home.arpa' +``` + + +## Operation + +```{opcmd} restart mdns repeater + +Restart mDNS repeater service. +``` + +```{opcmd} show log mdns repeater + +Show logs for mDNS repeater service. +``` + +```{opcmd} monitor log mdns repeater + +Follow the logs for mDNS repeater service. +``` + +[multicast dns]: <https://en.wikipedia.org/wiki/Multicast_DNS> diff --git a/docs/configuration/service/md-monitoring.md b/docs/configuration/service/md-monitoring.md new file mode 100644 index 00000000..a6bf2605 --- /dev/null +++ b/docs/configuration/service/md-monitoring.md @@ -0,0 +1,334 @@ +# Monitoring + +VyOS supports monitoring through Telegraf as well as through Prometheus exporters. + +## Telegraf + +Telegraf is the open source server agent to help you collect metrics, events +and logs from your routers. + +The following Telegraf plugins are configurable to export metrics and logs: +: - Azure Data Explorer + - Prometheus Client + - Splunk + - InfluxDB + - Loki + +### Azure data explorer + +Telegraf output plugin [azure-data-explorer]. + +```{cfgcmd} set service monitoring telegraf azure-data-explorer authentication client-id \<client-id\> + + Authentication application client-id. +``` + + +```{cfgcmd} set service monitoring telegraf azure-data-explorer authentication client-secret \<client-secret\> + +Authentication application client-secret. +``` + + +```{cfgcmd} set service monitoring telegraf azure-data-explorer authentication tenant-id \<tenant-id\> + +Authentication application tenant-id +``` + + +```{cfgcmd} set service monitoring telegraf azure-data-explorer database \<name\> + +Remote database name. +``` + + +```{cfgcmd} set service monitoring telegraf azure-data-explorer group-metrics \<single-table | table-per-metric\> + +Type of metrics grouping when push to Azure Data Explorer. The default is +``table-per-metric``. +``` + + +```{cfgcmd} set service monitoring telegraf azure-data-explorer table \<name\> + +Name of the single table Only if set group-metrics single-table. +``` + + +```{cfgcmd} set service monitoring telegraf azure-data-explorer url \<url\> + +Remote URL. +``` + +### Prometheus client + +Telegraf output plugin [prometheus-client] +This plugin allows export of Telegraf metrics to Prometheus, +for Prometheus native metrics through exporters see section below. + +```{cfgcmd} set service monitoring telegraf prometheus-client + + Output plugin Prometheus client +``` + + +```{cfgcmd} set service monitoring telegraf prometheus-client allow-from \<prefix\> + +Networks allowed to query this server +``` + + +```{cfgcmd} set service monitoring telegraf prometheus-client authentication username \<username\> + +HTTP basic authentication username +``` + + +```{cfgcmd} set service monitoring telegraf prometheus-client authentication password \<password\> + +HTTP basic authentication username +``` + + +```{cfgcmd} set service monitoring telegraf prometheus-client listen-address \<address\> + +Local IP addresses to listen on +``` + + +```{cfgcmd} set service monitoring telegraf prometheus-client metric-version \<1 | 2\> + +Metris version, the default is ``2`` +``` + + +```{cfgcmd} set service monitoring telegraf prometheus-client port \<port\> + +Port number used by connection, default is ``9273`` +``` + +Example: + +```none +set service monitoring telegraf prometheus-client +``` + + +```none +vyos@r14:~$ curl --silent localhost:9273/metrics | egrep -v "#" | grep cpu_usage_system +cpu_usage_system{cpu="cpu-total",host="r14"} 0.20040080160320556 +cpu_usage_system{cpu="cpu0",host="r14"} 0.17182130584191915 +cpu_usage_system{cpu="cpu1",host="r14"} 0.22896393817971655 +``` + +### Splunk + + +Telegraf output plugin [splunk] HTTP Event Collector. + +```{cfgcmd} set service monitoring telegraf splunk authentication insecure + +Use TLS but skip host validation +``` + + +```{cfgcmd} set service monitoring telegraf splunk authentication token \<token\> + +Authorization token +``` + + +```{cfgcmd} set service monitoring telegraf splunk authentication url \<url\> + +Remote URL to Splunk collector +``` + +Example: + +```none +set service monitoring telegraf splunk authentication insecure +set service monitoring telegraf splunk authentication token 'xxxxf5b8-xxxx-452a-xxxx-43828911xxxx' +set service monitoring telegraf splunk url 'https://192.0.2.10:8088/services/collector' +``` + +### InfluxDB + + +Telegraf output plugin [influxdb] to write metrics to `InfluxDB` via HTTP. + +```{cfgcmd} set service monitoring telegraf influxdb authentication organization \<organization\> + +Authentication organization name +``` + + +```{cfgcmd} set service monitoring telegraf influxdb authentication token \<token\> + +Authentication token +``` + + +```{cfgcmd} set service monitoring telegraf bucket \<bucket\> + +Remote ``InfluxDB`` bucket name +``` + + +```{cfgcmd} set service monitoring telegraf influxdb port \<port\> + +Remote port +``` + + +```{cfgcmd} set service monitoring telegraf influxdb url \<url\> + +Remote URL +``` + +Example: + +```none +set service monitoring telegraf influxdb authentication organization 'vyos' +set service monitoring telegraf influxdb authentication token 'ZAml9Uy5wrhA...==' +set service monitoring telegraf influxdb bucket 'bucket_vyos' +set service monitoring telegraf influxdb port '8086' +set service monitoring telegraf influxdb url 'http://r1.influxdb2.local' +``` + +### Loki + +Telegraf can be used to send logs to [loki] using tags as labels. + +```{cfgcmd} set service monitoring telegraf loki port \<port\> + + Remote Loki port + + Default is 3100 +``` + + +```{cfgcmd} set service monitoring telegraf loki url \<url\> + +Remote Loki url +``` + + +```{cfgcmd} set service monitoring telegraf loki authentication username \<username\> +``` + +```{cfgcmd} set service monitoring telegraf loki authentication password \<password\> + +HTTP basic authentication. + +If either is set both must be set. +``` + +```{cfgcmd} set service monitoring telegraf loki metric-name-label \<label\> + +Label to use for the metric name when sending metrics. + +If set to an empty string, the label will not be added. +This is NOT recommended, as it makes it impossible to differentiate +between multiple metrics. +``` + +## Prometheus + + +The following Prometheus exporters are configurable to export metrics: +: - Node Exporter + - FRR Exporter + + +### Node Exporter + + +Prometheus [node_exporter] which provides a wide range of hardware and OS metrics. + +```{cfgcmd} set service monitoring prometheus node-exporter listen-address \<address\> + +Configure the address node_exporter is listening on. +``` + +```{cfgcmd} set service monitoring prometheus node-exporter port \<port\> + +Configure the port number node_exporter is listening on. +``` + +```{cfgcmd} set service monitoring prometheus node-exporter vrf \<name\> + +Configure name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance. +``` + +```{cfgcmd} set service monitoring prometheus node-exporter collectors textfile + +Configure textfile collector to export custom metrics read from +`/run/node_exporter/collector` +``` + +### FRR Exporter + +Prometheus [frr_exporter] which provides free range routing metrics. + +```{cfgcmd} set service monitoring prometheus frr-exporter listen-address \<address\> + +Configure the address frr_exporter is listening on. + +``` + +```{cfgcmd} set service monitoring prometheus frr-exporter port \<port\> + +Configure the port number frr_exporter is listening on. +``` + +```{cfgcmd} set service monitoring prometheus frr-exporter vrf \<name\> + +Configure name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance. +``` + +### Blackbox Exporter + +Prometheus [blackbox_exporter] which allows probing of endpoints over +HTTP, HTTPS, DNS, TCP, ICMP and gRPC . + +```{cfgcmd} set service monitoring prometheus blackbox-exporter listen-address \<address\> + +Configure the address blackbox_exporter is listening on. +``` +```{cfgcmd} set service monitoring prometheus blackbox-exporter port \<port\> + +Configure the port number blackbox_exporter is listening on. +``` +```{cfgcmd} set service monitoring prometheus blackbox-exporter vrf \<name\> + +Configure name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance. +``` + +#### Configuring modules + +Blackbox exporter can be configured with different modules for probing DNS or ICMP. + +DNS module example: + +```none +set service monitoring prometheus blackbox-exporter modules dns name dns4 preferred-ip-protocol ipv4 +set service monitoring prometheus blackbox-exporter modules dns name dns4 query-name vyos.io +set service monitoring prometheus blackbox-exporter modules dns name dns4 query-type A +``` + +ICMP module example: + +```none +set service monitoring prometheus blackbox-exporter modules icmp name ping6 preferred-ip-protocol ipv6 +set service monitoring prometheus blackbox-exporter modules icmp name ping6 ip-protocol-fallback +set service monitoring prometheus blackbox-exporter modules icmp name ping6 timeout 3 +``` + +[azure-data-explorer]: <https://github.com/influxdata/telegraf/tree/master/plugins/outputs/azure_data_explorer> +[blackbox_exporter]: <https://github.com/prometheus/blackbox_exporter> +[frr_exporter]: <https://github.com/tynany/frr_exporter> +[influxdb]: <https://github.com/influxdata/telegraf/tree/master/plugins/outputs/influxdb_v2> +[loki]: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/loki +[node_exporter]: <https://github.com/prometheus/node_exporter> +[prometheus-client]: <https://github.com/influxdata/telegraf/tree/master/plugins/outputs/prometheus_client> +[splunk]: <https://www.splunk.com/en_us/blog/it/splunk-metrics-via-telegraf.html> diff --git a/docs/configuration/service/md-ntp.md b/docs/configuration/service/md-ntp.md new file mode 100644 index 00000000..c8c1dee3 --- /dev/null +++ b/docs/configuration/service/md-ntp.md @@ -0,0 +1,202 @@ +(ntp)= + +# NTP + +{abbr}`NTP (Network Time Protocol`) is a networking protocol for clock +synchronization between computer systems over packet-switched, variable-latency +data networks. In operation since before 1985, NTP is one of the oldest Internet +protocols in current use. + +NTP is intended to synchronize all participating computers to within a few +milliseconds of {abbr}`UTC (Coordinated Universal Time)`. It uses the +intersection algorithm, a modified version of Marzullo's algorithm, to select +accurate time servers and is designed to mitigate the effects of variable +network latency. NTP can usually maintain time to within tens of milliseconds +over the public Internet, and can achieve better than one millisecond accuracy +in local area networks under ideal conditions. Asymmetric routes and network +congestion can cause errors of 100 ms or more. + +The protocol is usually described in terms of a client-server model, but can as +easily be used in peer-to-peer relationships where both peers consider the other +to be a potential time source. Implementations send and receive timestamps using +{abbr}`UDP (User Datagram Protocol)` on port number 123. + +NTP supplies a warning of any impending leap second adjustment, but no +information about local time zones or daylight saving time is transmitted. + +The current protocol is version 4 (NTPv4), which is a proposed standard as +documented in {rfc}`5905`. It is backward compatible with version 3, specified +in {rfc}`1305`. + +:::{note} +VyOS 1.4 uses chrony instead of ntpd (see {vytask}`T3008`) which will +no longer accept anonymous NTP requests as in VyOS 1.3. All configurations +will be migrated to keep the anonymous functionality. For new setups if you +have clients using your VyOS installation as NTP server, you must specify +the `allow-client` directive. +::: + +## Configuration + +```{cfgcmd} set service ntp server \<address\> + + Configure one or more servers for synchronisation. Server name can be either + an IP address or {abbr}`FQDN (Fully Qualified Domain Name)`. + + There are 3 default NTP server set. You are able to change them. + + * ``time1.vyos.net`` + * ``time2.vyos.net`` + * ``time3.vyos.net`` +``` + + +```{cfgcmd} set service ntp server \<address\> \<noselect | nts | pool | prefer | ptp | interleave\> + +Configure one or more attributes to the given NTP server. + +* ``noselect`` marks the server as unused, except for display purposes. The +server is discarded by the selection algorithm. + +* ``nts`` enables Network Time Security (NTS) for the server as specified +in {rfc}`8915` + +* ``pool`` mobilizes persistent client mode association with a number of +remote servers. + +* ``prefer`` marks the server as preferred. All other things being equal, +this host will be chosen for synchronization among a set of correctly +operating hosts. + +* ``ptp`` enables the PTP transport for this server (see {ref}`ptp-transport`). + +* ``interleave`` enables NTP interleaved mode (see [draft-ntp-interleaved-modes]), which can improve +synchronization accuracy and stability when supported by both parties. +``` + + +```{cfgcmd} set service ntp listen-address \<address\> + +NTP process will only listen on the specified IP address. You must specify +the `<address>` and optionally the permitted clients. Multiple listen +addresses for same IP family is no longer supported. Only one IPv4 and one +IPv6 address can be configured, using separate commands for each. +``` + + +```{cfgcmd} set service ntp allow-client address \<address\> + +List of networks or client addresses permitted to contact this NTP server. + +Multiple networks/client IP addresses can be configured. +``` + + +```{cfgcmd} set service ntp vrf \<name\> + +Specify name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance. +``` + + +```{cfgcmd} set service ntp leap-second [ignore|smear|system|timezone] + +Define how to handle leap-seconds. + +* `ignore`: No correction is applied to the clock for the leap second. The +clock will be corrected later in normal operation when new measurements are +made and the estimated offset includes the one second error. + +* `smear`: When smearing a leap second, the leap status is suppressed on the +server and the served time is corrected slowly by slewing instead of +stepping. The clients do not need any special configuration as they do not +know there is any leap second and they follow the server time which +eventually brings them back to UTC. Care must be taken to ensure they use +only NTP servers which smear the leap second in exactly the same way for +synchronisation. + +* `system`: When inserting a leap second, the kernel steps the system clock +backwards by one second when the clock gets to 00:00:00 UTC. When deleting +a leap second, it steps forward by one second when the clock gets to +23:59:59 UTC. + +* `timezone`: This directive specifies a timezone in the system timezone +database which chronyd can use to determine when will the next leap second +occur and what is the current offset between TAI and UTC. It will +periodically check if 23:59:59 and 23:59:60 are valid times in the +timezone. This normally works with the right/UTC timezone which is the +default +``` + +## Hardware Timestamping of NTP Packets + + +The chrony daemon on VyOS can leverage NIC hardware capabilities to record the +exact time packets are received on the interface, as well as when packets were +actually transmitted. This provides improved accuracy and stability when the +system is under load, as queuing and OS context switching can introduce a +variable delay between when the packet is received on the network and when it +is actually processed by the NTP daemon. + + +Hardware timestamping depends on NIC support. Some NICs can be configured to +apply timestamps to any incoming packet, while others only support applying +timestamps to specific protocols (e.g. PTP). + + +When timestamping is enabled on an interface, chrony's default behavior is to +try to configure the interface to only timestamp NTP packets. If this mode is +not supported, chrony will attempt to set it to timestamp all packets. If +neither option is supported (e.g. the NIC can only timestamp received PTP +packets), chrony will leverage timestamping on transmitted packets only, which +still provides some benefit. + +```{cfgcmd} set service ntp timestamp interface \<interface\> + +Configures hardware timestamping on the interface \<interface\>. The special +value `all` can also be specified to enable timestamping on all interfaces +that support it. + +Configure the timestamping behavior with the following option: + +* ``receive-filter [all|ntp|ptp|none]`` selects the receive filter mode, +which controls which inbound packets the NIC applies timestamps to. The +selected mode must be supported by the NIC, or timestamping will be +disabled for the interface. +``` + +The following `receive-filter` modes can be selected: +- *all*: All received packets will be timestamped. +- *ntp*: Only received NTP protocol packets will be timestamped. +- *ptp*: Only received PTP protocol packets will be timestamped. Combined with + the PTP transport for NTP packets, this can be leveraged to take advantage of + hardware timestamping on NICs that only support the ptp filter mode. +- *none*: No received packets will be timestamped. Hardware timestamping of + transmitted packets will still be leveraged, if supported by the NIC. +(ptp-transport)= + +## PTP Transport of NTP Packets + +The Precision Time Protocol (IEEE 1588) is a local network time synchronization +protocol that provides high precision time synchronization by leveraging +hardware clocks in NICs and other network elements. VyOS does not currently +support standards-based PTP, which can be deployed independently of +NTP. + +For networks consisting of VyOS and other Linux systems running relatively +recent versions of the chrony daemon, NTP packets can be "tunneled" over +PTP. NTP over PTP provides the best of both worlds, leveraging hardware support +for timestamping PTP packets while retaining the configuration flexibility and +fault tolerance of NTP. + +```{cfgcmd} set service ntp ptp + +Enables the NTP daemon PTP transport. The NTP daemon will listen on the +configured PTP port. Note that one or more servers must be individually +enabled for PTP before the daemon will synchronize over the transport. +``` +```{cfgcmd} set service ntp ptp port \<port\> + +Configures the PTP port. By default, the standard port 319 is used. +``` + +[draft-ntp-interleaved-modes]: https://datatracker.ietf.org/doc/draft-ietf-ntp-interleaved-modes/07/ diff --git a/docs/configuration/service/md-pppoe-server.md b/docs/configuration/service/md-pppoe-server.md new file mode 100644 index 00000000..32881845 --- /dev/null +++ b/docs/configuration/service/md-pppoe-server.md @@ -0,0 +1,753 @@ +--- +lastproofread: '2022-09-17' +--- + +(pppoe-server)= + +# PPPoE Server + +VyOS utilizes [accel-ppp](https://accel-ppp.org/) to provide PPPoE server functionality. It can +be used with local authentication or a connected RADIUS server. + +:::{note} +Please be aware, due to an upstream bug, config +changes/commits will restart the ppp daemon and will reset existing +PPPoE connections from connected users, in order to become effective. +::: + +## Configuring PPPoE Server + +```none +set service pppoe-server access-concentrator PPPoE-Server +set service pppoe-server authentication mode local +set service pppoe-server authentication local-users username test password 'test' +set service pppoe-server client-ip-pool PPPOE-POOL range 192.168.255.2-192.168.255.254 +set service pppoe-server default-pool 'PPPOE-POOL' +set service pppoe-server gateway-address 192.168.255.1 +set service pppoe-server interface eth0 +``` + +```{cfgcmd} set service pppoe-server access-concentrator \<name\> + + Use this command to set a name for this PPPoE-server access + concentrator. +``` + + +```{cfgcmd} set service pppoe-server authentication mode \<local | radius\> + +Set authentication backend. The configured authentication backend is used +for all queries. + +* **radius**: All authentication queries are handled by a configured RADIUS +server. +* **local**: All authentication queries are handled locally. +* **noauth**: Authentication disabled. +``` + + +```{cfgcmd} set service pppoe-server authentication local-users username \<name\> password \<password\> + +Create `<user>` for local authentication on this system. The users password +will be set to `<pass>`. +``` + + +```{cfgcmd} set service pppoe-server client-ip-pool \<POOL-NAME\> range \<x.x.x.x-x.x.x.x | x.x.x.x/x\> + +Use this command to define the first IP address of a pool of +addresses to be given to pppoe clients. If notation ``x.x.x.x-x.x.x.x``, +it must be within a /24 subnet. If notation ``x.x.x.x/x`` is +used there is possibility to set host/netmask. +``` + + +```{cfgcmd} set service pppoe-server default-pool \<POOL-NAME\> + +Use this command to define default address pool name. +``` + + +```{cfgcmd} set service pppoe-server interface \<interface\> + +Use this command to define the interface the PPPoE server will use to +listen for PPPoE clients. +``` + + +```{cfgcmd} set service pppoe-server gateway-address \<address\> + +Specifies single `<gateway>` IP address to be used as local address of PPP +interfaces. +``` + +## Configuring RADIUS authentication + +To enable RADIUS based authentication, the authentication mode needs to be +changed within the configuration. Previous settings like the local users, still +exists within the configuration, however they are not used if the mode has been +changed from local to radius. Once changed back to local, it will use all local +accounts again. + +```none +set service pppoe-server authentication mode radius +``` + +```{cfgcmd} set service pppoe-server authentication radius server \<server\> key \<secret\> + +Configure RADIUS `<server>` and its required shared `<secret>` for +communicating with the RADIUS server. +``` + +Since the RADIUS server would be a single point of failure, multiple RADIUS +servers can be setup and will be used subsequentially. +For example: + +```none +set service pppoe-server authentication radius server 10.0.0.1 key 'foo' +set service pppoe-server authentication radius server 10.0.0.2 key 'foo' +``` + +:::{note} +Some RADIUS severs use an access control list which allows or denies +queries, make sure to add your VyOS router to the allowed client list. +::: + + +### RADIUS source address + + +If you are using OSPF as IGP, always the closest interface connected to the +RADIUS server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests +to a single source IP e.g. the loopback interface. + +```{cfgcmd} set service pppoe-server authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. +``` + +:::{note} +The `source-address` must be configured on one of VyOS interface. +Best practice would be a loopback or dummy interface. +::: + + +### RADIUS advanced options + +```{cfgcmd} set service pppoe-server authentication radius server \<server\> port \<port\> + +Configure RADIUS `<server>` and its required port for authentication requests. +``` + + +```{cfgcmd} set service pppoe-server authentication radius server \<server\> fail-time \<time\> + +Mark RADIUS server as offline for this given `<time>` in seconds. +``` + + +```{cfgcmd} set service pppoe-server authentication radius server \<server\> disable + +Temporary disable this RADIUS server. +``` + + +```{cfgcmd} set service pppoe-server authentication radius acct-timeout \<timeout\> + +Timeout to wait reply for Interim-Update packets. (default 3 seconds) +``` + + +```{cfgcmd} set service pppoe-server authentication radius dynamic-author server \<address\> + +Specifies IP address for Dynamic Authorization Extension server (DM/CoA). +This IP must exist on any VyOS interface or it can be ``0.0.0.0``. +``` + + +```{cfgcmd} set service pppoe-server authentication radius dynamic-author port \<port\> + +UDP port for Dynamic Authorization Extension server (DM/CoA) +``` + + +```{cfgcmd} set service pppoe-server authentication radius dynamic-author key \<secret\> + +Secret for Dynamic Authorization Extension server (DM/CoA) +``` + + +```{cfgcmd} set service pppoe-server authentication radius max-try \<number\> + +Maximum number of tries to send Access-Request/Accounting-Request queries +``` + + +```{cfgcmd} set service pppoe-server authentication radius timeout \<timeout\> + +Timeout to wait response from server (seconds) +``` + + +```{cfgcmd} set service pppoe-server authentication radius nas-identifier \<identifier\> + +Value to send to RADIUS server in NAS-Identifier attribute and to be matched +in DM/CoA requests. +``` + + +```{cfgcmd} set service pppoe-server authentication radius nas-ip-address \<address\> + +Value to send to RADIUS server in NAS-IP-Address attribute and to be matched +in DM/CoA requests. Also DM/CoA server will bind to that address. +``` + + +```{cfgcmd} set service pppoe-server authentication radius source-address \<address\> + +Source IPv4 address used in all RADIUS server queires. +``` + + +```{cfgcmd} set service pppoe-server authentication radius rate-limit attribute \<attribute\> + +Specifies which RADIUS server attribute contains the rate limit information. +The default attribute is ``Filter-Id``. +``` + +:::{note} +If you set a custom RADIUS attribute you must define it on both +dictionaries at RADIUS server and client. +::: + +```{cfgcmd} set service pppoe-server authentication radius rate-limit enable + +Enables bandwidth shaping via RADIUS. +``` + + +```{cfgcmd} set service pppoe-server authentication radius rate-limit vendor + +Specifies the vendor dictionary, dictionary needs to be in +/usr/share/accel-ppp/radius. +``` + +Received RADIUS attributes have a higher priority than parameters defined within +the CLI configuration, refer to the explanation below. + + +### Allocation clients ip addresses by RADIUS + + +If the RADIUS server sends the attribute `Framed-IP-Address` then this IP +address will be allocated to the client and the option `default-pool` +within the CLI config is being ignored. + + +If the RADIUS server sends the attribute `Framed-Pool`, IP address will +be allocated from a predefined IP pool whose name equals the attribute value. + + +If the RADIUS server sends the attribute `Stateful-IPv6-Address-Pool`, +IPv6 address will be allocated from a predefined IPv6 pool `prefix` +whose name equals the attribute value. + + +If the RADIUS server sends the attribute `Delegated-IPv6-Prefix-Pool`, +IPv6 delegation pefix will be allocated from a predefined IPv6 pool `delegate` +whose name equals the attribute value. + + +:::{note} +`Stateful-IPv6-Address-Pool` and `Delegated-IPv6-Prefix-Pool` +are defined in RFC6911. If they are not defined in your RADIUS server, +add new [dictionary]. +::: + + +User interface can be put to VRF context via RADIUS Access-Accept packet, +or change it via RADIUS CoA. `Accel-VRF-Name` is used from these purposes. +It is custom [ACCEL-PPP attribute]. Define it in your RADIUS server. + + +### Renaming clients interfaces by RADIUS + + +If the RADIUS server uses the attribute `NAS-Port-Id`, ppp tunnels will be +renamed. + + +:::{note} +The value of the attribute `NAS-Port-Id` must be less than 16 +characters, otherwise the interface won't be renamed. +::: + + +## Automatic VLAN Creation + +```{cfgcmd} set service pppoe-server interface \<interface\> vlan \<id | range\> + +VLAN's can be created by Accel-ppp on the fly via the use of a Kernel module +named ``vlan_mon``, which is monitoring incoming vlans and creates the +necessary VLAN if required and allowed. VyOS supports the use of either +VLAN ID's or entire ranges, both values can be defined at the same time for +an interface. + +When configured, PPPoE will create the necessary VLANs when required. Once +the user session has been cancelled and the VLAN is not needed anymore, VyOS +will remove it again. +``` + + +```none +set service pppoe-server interface eth3 vlan 100 +set service pppoe-server interface eth3 vlan 200 +set service pppoe-server interface eth3 vlan 500-1000 +set service pppoe-server interface eth3 vlan 2000-3000 +``` + +## Bandwidth Shaping + + +Bandwidth rate limits can be set for local users or RADIUS based +attributes. + + +### For Local Users + +```{cfgcmd} set service pppoe-server authentication local-users username \<user\> rate-limit download \<bandwidth\> + +Download bandwidth limit in kbit/s for `<user>`. +``` + + +```{cfgcmd} set service pppoe-server authentication local-users username \<user\> rate-limit upload \<bandwidth\> + +Upload bandwidth limit in kbit/s for `<user>`. +``` +```none +set service pppoe-server access-concentrator 'ACN' +set service pppoe-server authentication local-users username foo password 'bar' +set service pppoe-server authentication local-users username foo rate-limit download '20480' +set service pppoe-server authentication local-users username foo rate-limit upload '10240' +set service pppoe-server authentication mode 'local' +set service pppoe-server client-ip-pool IP-POOL range '10.1.1.100/24' +set service pppoe-server default-pool 'IP-POOL' +set service pppoe-server name-server '10.100.100.1' +set service pppoe-server name-server '10.100.200.1' +set service pppoe-server interface 'eth1' +set service pppoe-server gateway-address '10.1.1.2' +``` + +Once the user is connected, the user session is using the set limits and +can be displayed via `show pppoe-server sessions`. + +```none +show pppoe-server sessions +ifname | username | ip | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +-------+----------+------------+-------------------+-------------+--------+----------+----------+---------- +ppp0 | foo | 10.1.1.100 | 00:53:00:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B | 76 B +``` + +### For RADIUS users + +The current attribute `Filter-Id` is being used as default and can be +setup within RADIUS: + +Filter-Id=2000/3000 (means 2000Kbit down-stream rate and 3000Kbit +up-stream rate) + +The command below enables it, assuming the RADIUS connection has been +setup and is working. + +```{cfgcmd} set service pppoe-server authentication radius rate-limit enable + + Use this command to enable bandwidth shaping via RADIUS. +``` + +Other attributes can be used, but they have to be in one of the +dictionaries in */usr/share/accel-ppp/radius*. + + +## Load Balancing + +```{cfgcmd} set service pppoe-server pado-delay \<number-of-ms\> sessions \<number-of-sessions\> + +Use this command to enable the delay of PADO (PPPoE Active Discovery +Offer) packets, which can be used as a session balancing mechanism +with other PPPoE servers. +``` + + +```none +set service pppoe-server pado-delay 50 sessions '500' +set service pppoe-server pado-delay 100 sessions '1000' +set service pppoe-server pado-delay 300 sessions '3000' +``` + +In the example above, the first 499 sessions connect without delay. PADO +packets will be delayed 50 ms for connection from 500 to 999, this trick +allows other PPPoE servers send PADO faster and clients will connect to +other servers. Last command says that this PPPoE server can serve only +3000 clients. + + +## IPv6 + +```{cfgcmd} set service pppoe-server ppp-options ipv6 \<require | prefer | allow | deny\> + +Specifies IPv6 negotiation preference. + +* **require** - Require IPv6 negotiation +* **prefer** - Ask client for IPv6 negotiation, do not fail if it rejects +* **allow** - Negotiate IPv6 only if client requests +* **deny** - Do not negotiate IPv6 (default value) +``` + + +```{cfgcmd} set service pppoe-server client-ipv6-pool \<IPv6-POOL-NAME\> prefix \<address\> mask \<number-of-bits\> + +Use this comand to set the IPv6 address pool from which an PPPoE client +will get an IPv6 prefix of your defined length (mask) to terminate the +PPPoE endpoint at their side. The mask length can be set from 48 to 128 +bit long, the default value is 64. +``` + + +```{cfgcmd} set service pppoe-server client-ipv6-pool \<IPv6-POOL-NAME\> delegate \<address\> delegation-prefix \<number-of-bits\> + +Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on +PPPoE. You will have to set your IPv6 pool and the length of the +delegation prefix. From the defined IPv6 pool you will be handing out +networks of the defined length (delegation-prefix). The length of the +delegation prefix can be set from 32 to 64 bit long. +``` + + +```{cfgcmd} set service pppoe-server default-ipv6-pool \<IPv6-POOL-NAME\> + +Use this command to define default IPv6 address pool name. +``` + + +```none +set service pppoe-server ppp-options ipv6 allow +set service pppoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' +set service pppoe-server client-ipv6-pool IPv6-POOL prefix '2001:db8:8002::/48' mask '64' +set service pppoe-server default-ipv6-pool IPv6-POOL +``` + +### IPv6 Advanced Options + +```{cfgcmd} set service pppoe-server ppp-options ipv6-accept-peer-interface-id + +Accept peer interface identifier. By default is not defined. +``` + + +```{cfgcmd} set service pppoe-server ppp-options ipv6-interface-id \<random | x:x:x:x\> + +Specifies fixed or random interface identifier for IPv6. +By default is fixed. + +* **random** - Random interface identifier for IPv6 +* **x:x:x:x** - Specify interface identifier for IPv6 +``` + + +```{cfgcmd} set service pppoe-server ppp-options ipv6-interface-id \<random | x:x:x:x\> + +Specifies peer interface identifier for IPv6. By default is fixed. + +* **random** - Random interface identifier for IPv6 +* **x:x:x:x** - Specify interface identifier for IPv6 +* **ipv4-addr** - Calculate interface identifier from IPv4 address. +* **calling-sid** - Calculate interface identifier from calling-station-id. +``` + +## Scripting + +```{cfgcmd} set service pppoe-server extended-scripts on-change \<path_to_script\> + +Script to run when session interface changed by RADIUS CoA handling +``` + + +```{cfgcmd} set service pppoe-server extended-scripts on-down \<path_to_script\> + +Script to run when session interface going to terminate +``` + + +```{cfgcmd} set service pppoe-server extended-scripts on-pre-up \<path_to_script\> + +Script to run before session interface comes up +``` + + +```{cfgcmd} set service pppoe-server extended-scripts on-up \<path_to_script\> + +Script to run when session interface is completely configured and started +``` + +## Advanced Options + + +### Authentication Advanced Options + +```{cfgcmd} set service pppoe-server authentication local-users username \<user\> disable + +Disable `<user>` account. +``` + + +```{cfgcmd} set service pppoe-server authentication local-users username \<user\> static-ip \<address\> + +Assign static IP address to `<user>` account. +``` + + +```{cfgcmd} set service pppoe-server authentication protocols \<pap | chap | mschap | mschap-v2\> + +Require the peer to authenticate itself using one of the following protocols: +pap, chap, mschap, mschap-v2. +``` + +### Client IP Pool Advanced Options + +```{cfgcmd} set service pppoe-server client-ip-pool \<POOL-NAME\> next-pool \<NEXT-POOL-NAME\> + +Use this command to define the next address pool name. +``` + +### PPP Advanced Options + +```{cfgcmd} set service pppoe-server ppp-options disable-ccp + +Disable Compression Control Protocol (CCP). +CCP is enabled by default. +``` + + +```{cfgcmd} set service pppoe-server ppp-options interface-cache \<number\> + +Specifies number of interfaces to keep in cache. It means that don’t +destroy interface after corresponding session is destroyed, instead +place it to cache and use it later for new sessions repeatedly. +This should reduce kernel-level interface creation/deletion rate lack. +Default value is **0**. +``` + + +```{cfgcmd} set service pppoe-server ppp-options ipv4 \<require | prefer | allow | deny\> + +Specifies IPv4 negotiation preference. + +* **require** - Require IPv4 negotiation +* **prefer** - Ask client for IPv4 negotiation, do not fail if it rejects +* **allow** - Negotiate IPv4 only if client requests (Default value) +* **deny** - Do not negotiate IPv4 +``` + + +```{cfgcmd} set service pppoe-server ppp-options lcp-echo-failure \<number\> + +Defines the maximum `<number>` of unanswered echo requests. Upon reaching the +value `<number>`, the session will be reset. Default value is **3**. +``` + + +```{cfgcmd} set service pppoe-server ppp-options lcp-echo-interval \<interval\> + +If this option is specified and is greater than 0, then the PPP module will +send LCP pings of the echo request every `<interval>` seconds. +Default value is **30**. +``` + + +```{cfgcmd} set service pppoe-server ppp-options lcp-echo-timeout + +Specifies timeout in seconds to wait for any peer activity. If this option +specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" +is not used. Default value is **0**. +``` + + +```{cfgcmd} set service pppoe-server ppp-options min-mtu \<number\> + +Defines minimum acceptable MTU. If client will try to negotiate less then +specified MTU then it will be NAKed or disconnected if rejects greater MTU. +Default value is **100**. +``` + + +```{cfgcmd} set service pppoe-server ppp-options mppe \<require | prefer | deny\> + +Specifies {abbr}`MPPE (Microsoft Point-to-Point Encryption)` negotiation +preference. + +* **require** - ask client for mppe, if it rejects drop connection +* **prefer** - ask client for mppe, if it rejects don't fail. (Default value) +* **deny** - deny mppe + +Default behavior - don't ask client for mppe, but allow it if client wants. +Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy +attribute. +``` + + +```{cfgcmd} set service pppoe-server ppp-options mru \<number\> + +Defines preferred MRU. By default is not defined. +``` + +### Global Advanced options + +```{cfgcmd} set service pppoe-server description \<description\> + +Set description. +``` + + +```{cfgcmd} set service pppoe-server limits burst \<value\> + +Burst count +``` + + +```{cfgcmd} set service pppoe-server limits connection-limit \<value\> + +Acceptable rate of connections (e.g. 1/min, 60/sec) +``` + + +```{cfgcmd} set service pppoe-server limits timeout \<value\> + +Timeout in seconds +``` + + +```{cfgcmd} set service pppoe-server mtu + +Maximum Transmission Unit (MTU) (default: **1492**) +``` + + +```{cfgcmd} set service pppoe-server max-concurrent-sessions + +Maximum number of concurrent session start attempts +``` + + +```{cfgcmd} set service pppoe-server name-server \<address\> + +Connected client should use `<address>` as their DNS server. This +command accepts both IPv4 and IPv6 addresses. Up to two nameservers +can be configured for IPv4, up to three for IPv6. +``` + + +```{cfgcmd} set service pppoe-server service-name \<names\> + +Specifies Service-Name to respond. If absent any Service-Name is +acceptable and client’s Service-Name will be sent back. Also possible +set multiple service-names: `sn1,sn2,sn3` +``` + +Per default the user session is being replaced if a second +authentication request succeeds. Such session requests can be either +denied or allowed entirely, which would allow multiple sessions for a +user in the latter case. If it is denied, the second session is being +rejected even if the authentication succeeds, the user has to terminate +its first session and can then authentication again. + +```{cfgcmd} set service pppoe-server session-control + +* **disable**: Disables session control. +* **deny**: Deny second session authorization. +* **replace**: Terminate first session when second is authorized **(default)** +``` + + +```{cfgcmd} set service pppoe-server shaper fwmark \<1-2147483647\> + +Match firewall mark value +``` + + +```{cfgcmd} set service pppoe-server snmp master-agent + +Enable SNMP +``` + + +```{cfgcmd} set service pppoe-server wins-server \<address\> + +Windows Internet Name Service (WINS) servers propagated to client +``` + +## Monitoring + +```{opcmd} show pppoe-server sessions + +Use this command to locally check the active sessions in the PPPoE +server. +``` +```none +show pppoe-server sessions +ifname | username | ip | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +-------+----------+------------+-------------------+-------------+--------+----------+----------+---------- +ppp0 | foo | 10.1.1.100 | 00:53:00:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B | 76 B +``` + +## Examples +### IPv4 + +The example below uses ACN as access-concentrator name, assigns an +address from the pool 10.1.1.100-111, terminates at the local endpoint +10.1.1.1 and serves requests only on eth1. + +```none +set service pppoe-server access-concentrator 'ACN' +set service pppoe-server authentication local-users username foo password 'bar' +set service pppoe-server authentication mode 'local' +set service pppoe-server client-ip-pool IP-POOL range '10.1.1.100-10.1.1.111' +set service pppoe-server default-pool 'IP-POOL' +set service pppoe-server interface eth1 +set service pppoe-server gateway-address '10.1.1.2' +set service pppoe-server name-server '10.100.100.1' +set service pppoe-server name-server '10.100.200.1' +``` + +### Dual-Stack IPv4/IPv6 provisioning with Prefix Delegation + +The example below covers a dual-stack configuration. + +```none +set service pppoe-server authentication local-users username test password 'test' +set service pppoe-server authentication mode 'local' +set service pppoe-server client-ip-pool IP-POOL range '192.168.0.1/24' +set service pppoe-server default-pool 'IP-POOL' +set service pppoe-server client-ipv6-pool IPv6-POOL delegate '2001:db8:8003::/48' delegation-prefix '56' +set service pppoe-server client-ipv6-pool IPV6-POOL prefix '2001:db8:8002::/48' mask '64' +set service pppoe-server default-ipv6-pool IPv6-POOL +set service pppoe-server ppp-options ipv6 allow +set service pppoe-server name-server '10.1.1.1' +set service pppoe-server name-server '2001:db8:4860::8888' +set service pppoe-server interface 'eth2' +set service pppoe-server gateway-address '10.100.100.1' +``` + +The client, once successfully authenticated, will receive an IPv4 and an +IPv6 /64 address to terminate the PPPoE endpoint on the client side and +a /56 subnet for the clients internal use. + +```none +vyos@pppoe-server:~$ sh pppoe-server sessions + ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes +--------+----------+-------------+--------------------------+---------------------+-------------------+------------+--------+----------+----------+---------- + ppp0 | test | 192.168.0.1 | 2001:db8:8002:0:200::/64 | 2001:db8:8003::1/56 | 00:53:00:12:42:eb | | active | 00:00:49 | 875 B | 2.1 KiB +``` + +[accel-ppp attribute]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel +[dictionary]: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 diff --git a/docs/configuration/service/md-router-advert.md b/docs/configuration/service/md-router-advert.md new file mode 100644 index 00000000..10753105 --- /dev/null +++ b/docs/configuration/service/md-router-advert.md @@ -0,0 +1,121 @@ +(router-advert)= + +# Router Advertisements + +{abbr}`RAs (Router advertisements)` are described in {rfc}`4861#section-4.6.2`. +They are part of what is known as {abbr}`SLAAC (Stateless Address +Autoconfiguration)`. + +Supported interface types: + +> - bonding +> - bridge +> - ethernet +> - geneve +> - l2tpv3 +> - openvpn +> - pseudo-ethernet +> - tunnel +> - vxlan +> - wireguard +> - wireless +> - wwan + +## Configuration + +```{cfgcmd} set service router-advert interface \<interface\> ... +``` + +```{eval-rst} +.. csv-table:: + :header: "Field", "VyOS Option", "Description" + :widths: 10, 10, 20 + + "Cur Hop Limit", "hop-limit", "Hop count field of the outgoing RA packets" + """Managed address configuration"" flag", "managed-flag", "Tell hosts to use the administered stateful protocol (i.e. DHCP) for autoconfiguration" + """Other configuration"" flag", "other-config-flag", "Tell hosts to use the administered (stateful) protocol (i.e. DHCP) for autoconfiguration of other (non-address) information" + "MTU","link-mtu","Link MTU value placed in RAs, excluded in RAs if unset" + "Router Lifetime","default-lifetime","Lifetime associated with the default router in units of seconds" + "Reachable Time","reachable-time","Time, in milliseconds, that a node assumes a neighbor is reachable after having received a reachability confirmation" + "Retransmit Timer","retrans-timer","Time in milliseconds between retransmitted Neighbor Solicitation messages" + "Default Router Preference","default-preference","Preference associated with the default router" + "Interval", "interval", "Min and max intervals between unsolicited multicast RAs" + "DNSSL", "dnssl", "DNS search list to advertise" + "Name Server", "name-server", "Advertise DNS server per https://tools.ietf.org/html/rfc6106" + "Auto Ignore Prefix", "auto-ignore", "Exclude a prefix from being advertised when the wildcard ::/64 prefix is used" + "Captive Portal", "captive-portal", "Advertise a URL pointing to an RFC 8908-compliant API to tell hosts that they are behind a captive portal" +``` + +### Advertising a Prefix + +```{cfgcmd} set service router-advert interface \<interface\> prefix \<prefix/mask\> + +:::{note} +You can also opt for using ::/64 as prefix for your {abbr}`RAs (Router +Advertisements)`. This is a special wildcard prefix that will emit {abbr}`RAs (Router Advertisements)` for every prefix assigned to the interface. +This comes in handy when using dynamically obtained prefixes from DHCPv6-PD. +::: +``` +```{eval-rst} +.. csv-table:: + :header: "VyOS Field", "Description" + :widths: 10,30 + + "decrement-lifetime", "Lifetime is decremented by the number of seconds since the last RA - use in conjunction with a DHCPv6-PD prefix" + "deprecate-prefix", "Upon shutdown, this option will deprecate the prefix by announcing it in the shutdown RA" + "no-autonomous-flag","Prefix can not be used for stateless address auto-configuration" + "no-on-link-flag","Prefix can not be used for on-link determination" + "preferred-lifetime","Time in seconds that the prefix will remain preferred (default 4 hours)" + "valid-lifetime","Time in seconds that the prefix will remain valid (default: 30 days)" +``` + +### Advertising a NAT64 Prefix + +```{cfgcmd} set service router-advert interface \<interface\> nat64prefix \<prefix/mask\> + +Enable PREF64 option as outlined in {rfc}`8781`. + +NAT64 prefix mask must be one of: /32, /40, /48, /56, /64 or 96. + +:::{note} +The well known NAT64 prefix is ``64:ff9b::/96`` +::: +``` +```{eval-rst} +.. csv-table:: + :header: "VyOS Field", "Description" + :widths: 10,30 + + "valid-lifetime","Time in seconds that the prefix will remain valid (default: 65528 seconds)" +``` + +### Disabling Advertisements + +To disable advertisements without deleting the configuration: + +```{cfgcmd} set service router-advert interface \<interface\> no-send-advert + +If set, the router will no longer send periodic router advertisements and +will not respond to router solicitations. +``` + +```{cfgcmd} set service router-advert interface \<interface\> no-send-interval + +Advertisement Interval Option (specified by Mobile IPv6) is always included in +Router Advertisements unless this option is set. +``` + +## Example + +Your LAN connected on eth0 uses prefix `2001:db8:beef:2::/64` with the router +beeing `2001:db8:beef:2::1` + +```none +set interfaces ethernet eth0 address 2001:db8:beef:2::1/64 + +set service router-advert interface eth0 default-preference 'high' +set service router-advert interface eth0 name-server '2001:db8::1' +set service router-advert interface eth0 name-server '2001:db8::2' +set service router-advert interface eth0 other-config-flag +set service router-advert interface eth0 prefix 2001:db8:beef:2::/64 +``` diff --git a/docs/configuration/service/md-salt-minion.md b/docs/configuration/service/md-salt-minion.md new file mode 100644 index 00000000..e6f99752 --- /dev/null +++ b/docs/configuration/service/md-salt-minion.md @@ -0,0 +1,51 @@ +(saltminion)= + +# Salt-Minion + +[SaltStack] is Python-based, open-source +software for event-driven IT automation, remote task execution, and +configuration management. Supporting the "infrastructure as code" +approach to data center system and network deployment and management, +configuration automation, SecOps orchestration, vulnerability remediation, +and hybrid cloud control. + +## Requirements + +To use the Salt-Minion, a running Salt-Master is required. You can find more +in the [Salt Project Documentation](https://docs.saltproject.io/en/latest/contents.html) + +## Configuration + +```{cfgcmd} set service salt-minion hash \<type\> + + The hash type used when discovering file on master server (default: sha256) +``` + + +```{cfgcmd} set service salt-minion id \<id\> + +Explicitly declare ID for this minion to use (default: hostname) +``` + + +```{cfgcmd} set service salt-minion interval \<1-1440\> + +Interval in minutes between updates (default: 60) +``` + + +```{cfgcmd} set service salt-minion master \<hostname | IP\> + +The hostname or IP address of the master +``` + + +```{cfgcmd} set service salt-minion master-key \<key\> + +URL with signature of master for auth reply verification +``` + +Please take a look in the Automation section to find some usefull +Examples. + +[saltstack]: https://saltproject.io/ diff --git a/docs/configuration/service/md-snmp.md b/docs/configuration/service/md-snmp.md new file mode 100644 index 00000000..ac0429ff --- /dev/null +++ b/docs/configuration/service/md-snmp.md @@ -0,0 +1,258 @@ +(snmp)= + +# SNMP + +{abbr}`SNMP (Simple Network Management Protocol)` is an Internet Standard +protocol for collecting and organizing information about managed devices on +IP networks and for modifying that information to change device behavior. +Devices that typically support SNMP include cable modems, routers, switches, +servers, workstations, printers, and more. + +SNMP is widely used in network management for network monitoring. SNMP exposes +management data in the form of variables on the managed systems organized in +a management information base ([MIB]) which describe the system status and +configuration. These variables can then be remotely queried (and, in some +circumstances, manipulated) by managing applications. + +Three significant versions of SNMP have been developed and deployed. SNMPv1 is +the original version of the protocol. More recent versions, SNMPv2c and SNMPv3, +feature improvements in performance, flexibility and security. + +SNMP is a component of the Internet Protocol Suite as defined by the Internet +Engineering Task Force (IETF). It consists of a set of standards for network +management, including an application layer protocol, a database schema, and a +set of data objects. + +## Overview and basic concepts + +In typical uses of SNMP, one or more administrative computers called managers +have the task of monitoring or managing a group of hosts or devices on a +computer network. Each managed system executes a software component called an +agent which reports information via SNMP to the manager. + +An SNMP-managed network consists of three key components: + +- Managed devices +- Agent - software which runs on managed devices +- Network management station (NMS) - software which runs on the manager + +A managed device is a network node that implements an SNMP interface that +allows unidirectional (read-only) or bidirectional (read and write) access to +node-specific information. Managed devices exchange node-specific information +with the NMSs. Sometimes called network elements, the managed devices can be +any type of device, including, but not limited to, routers, access servers, +switches, cable modems, bridges, hubs, IP telephones, IP video cameras, +computer hosts, and printers. + +An agent is a network-management software module that resides on a managed +device. An agent has local knowledge of management information and translates +that information to or from an SNMP-specific form. + +A network management station executes applications that monitor and control +managed devices. NMSs provide the bulk of the processing and memory resources +required for network management. One or more NMSs may exist on any managed +network. + +:::{figure} /_static/images/service_snmp_communication_principles_diagram.webp +:alt: Principle of SNMP Communication +:scale: 20 % + +Image thankfully borrowed from +<https://en.wikipedia.org/wiki/File:SNMP_communication_principles_diagram.PNG> +which is under the GNU Free Documentation License +::: + +:::{note} +VyOS SNMP supports both IPv4 and IPv6. +::: + +## SNMP Protocol Versions + +VyOS itself supports [SNMPv2] (version 2) and [SNMPv3] (version 3) where the +later is recommended because of improved security (optional authentication and +encryption). + +### SNMPv2 + +SNMPv2 is the original and most commonly used version. For authorizing clients, +SNMP uses the concept of communities. Communities may have authorization set +to read only (this is most common) or to read and write (this option is not +actively used in VyOS). + +SNMP can work synchronously or asynchronously. In synchronous communication, +the monitoring system queries the router periodically. In asynchronous, the +router sends notification to the "trap" (the monitoring host). + +SNMPv2 does not support any authentication mechanisms, other than client source +address, so you should specify addresses of clients allowed to monitor the +router. Note that SNMPv2 also supports no encryption and always sends data in +plain text. + +#### Example + +```none +# Define a community +set service snmp community routers authorization ro + +# Allow monitoring access from the entire network +set service snmp community routers network 192.0.2.0/24 +set service snmp community routers network 2001::db8:ffff:eeee::/64 + +# Allow monitoring access from specific addresses +set service snmp community routers client 203.0.113.10 +set service snmp community routers client 203.0.113.20 + +# Define optional router information +set service snmp location "UK, London" +set service snmp contact "admin@example.com" + +# Trap target if you want asynchronous communication +set service snmp trap-target 203.0.113.10 + +# Listen only on specific IP addresses (port defaults to 161) +set service snmp listen-address 172.16.254.36 port 161 +set service snmp listen-address 2001:db8::f00::1 +``` + + +### SNMPv3 + +SNMPv3 (version 3 of the SNMP protocol) introduced a whole slew of new security +related features that have been missing from the previous versions. Security +was one of the biggest weakness of SNMP until v3. Authentication in SNMP +Versions 1 and 2 amounts to nothing more than a password (community string) +sent in clear text between a manager and agent. Each SNMPv3 message contains +security parameters which are encoded as an octet string. The meaning of these +security parameters depends on the security model being used. + +The security approach in SNMPv3 targets: + +- Confidentiality – Encryption of packets to prevent snooping by an + unauthorized source. +- Integrity – Message integrity to ensure that a packet has not been tampered + while in transit including an optional packet replay protection mechanism. +- Authentication – to verify that the message is from a valid source. + +(snmp-v3-example)= + +#### Example + +- Let SNMP daemon listen only on IP address 192.0.2.1 +- Configure new SNMP user named "vyos" with password "vyos12345678" +- New user will use SHA/AES for authentication and privacy + +```none +set service snmp listen-address 192.0.2.1 +set service snmp location 'VyOS Datacenter' +set service snmp v3 engineid '000000000000000000000002' +set service snmp v3 group default mode 'ro' +set service snmp v3 group default view 'default' +set service snmp v3 user vyos auth plaintext-password 'vyos12345678' +set service snmp v3 user vyos auth type 'sha' +set service snmp v3 user vyos group 'default' +set service snmp v3 user vyos privacy plaintext-password 'vyos12345678' +set service snmp v3 user vyos privacy type 'aes' +set service snmp v3 view default oid 1 +``` + +After commit the plaintext passwords will be hashed and stored in your +configuration. The resulting CLI config will look like: + +```none +vyos@vyos# show service snmp + listen-address 192.0.2.1 { + } + location "VyOS Datacenter" + v3 { + engineid 000000000000000000000002 + group default { + mode ro + view default + } + user vyos { + auth { + encrypted-password 4e52fe55fd011c9c51ae2c65f4b78ca93dcafdfe + type sha + } + group default + privacy { + encrypted-password 4e52fe55fd011c9c51ae2c65f4b78ca93dcafdfe + type aes + } + } + view default { + oid 1 { + } + } + } +``` + +You can test the SNMPv3 functionality from any linux based system, just run the +following command: `snmpwalk -v 3 -u vyos -a SHA -A vyos12345678 -x AES +-X vyos12345678 -l authPriv 192.0.2.1 .1` + +## VyOS MIBs + +All SNMP MIBs are located in each image of VyOS here: `/usr/share/snmp/mibs/` + +You are be able to download the files using SCP, once the SSH service +has been activated like so + +```none +scp -r vyos@your_router:/usr/share/snmp/mibs /your_folder/mibs +``` + + +## SNMP Extensions + +To extend SNMP agent functionality, custom scripts can be executed every time +the agent is being called. This can be achieved by using +`arbitrary extensioncommands`. The first step is to create a functional +script of course, then upload it to your VyOS instance via the command +`scp your_script.sh vyos@your_router:/config/user-data`. +Once the script is uploaded, it needs to be configured via the command below. + +```none +set service snmp script-extensions extension-name my-extension script your_script.sh +commit +``` + +The OID `.1.3.6.1.4.1.8072.1.3.2.3.1.1.4.116.101.115.116`, once called, will +contain the output of the extension. + +```none +root@vyos:/home/vyos# snmpwalk -v2c -c public 127.0.0.1 nsExtendOutput1 +NET-SNMP-EXTEND-MIB::nsExtendOutput1Line."my-extension" = STRING: hello +NET-SNMP-EXTEND-MIB::nsExtendOutputFull."my-extension" = STRING: hello +NET-SNMP-EXTEND-MIB::nsExtendOutNumLines."my-extension" = INTEGER: 1 +NET-SNMP-EXTEND-MIB::nsExtendResult."my-extension" = INTEGER: 0 +``` + + +## SolarWinds + +If you happen to use SolarWinds Orion as NMS you can also use the Device +Templates Management. A template for VyOS can be easily imported. + +Create a file named `VyOS-1.3.6.1.4.1.44641.ConfigMgmt-Commands` using the +following content: + +```none +<Configuration-Management Device="VyOS" SystemOID="1.3.6.1.4.1.44641"> + <Commands> + <Command Name="Reset" Value="set terminal width 0${CRLF}set terminal length 0"/> + <Command Name="Reboot" Value="reboot${CRLF}Yes"/> + <Command Name="EnterConfigMode" Value="configure"/> + <Command Name="ExitConfigMode" Value="commit${CRLF}exit"/> + <Command Name="DownloadConfig" Value="show configuration commands"/> + <Command Name="SaveConfig" Value="commit${CRLF}save"/> + <Command Name="Version" Value="show version"/> + <Command Name="MenuBased" Value="False"/> + <Command Name="VirtualPrompt" Value=":~"/> + </Commands> +</Configuration-Management> +``` + +[mib]: <https://en.wikipedia.org/wiki/Management_information_base> +[snmpv2]: <https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2> +[snmpv3]: <https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_3> diff --git a/docs/configuration/service/md-ssh.md b/docs/configuration/service/md-ssh.md new file mode 100644 index 00000000..d873cbee --- /dev/null +++ b/docs/configuration/service/md-ssh.md @@ -0,0 +1,366 @@ +(ssh)= + +# SSH + +{abbr}`SSH (Secure Shell)` is a cryptographic network protocol for operating +network services securely over an unsecured network. The standard TCP port for +SSH is 22. The best known example application is for remote login to computer +systems by users. + +SSH provides a secure channel over an unsecured network in a client-server +architecture, connecting an SSH client application with an SSH server. Common +applications include remote command-line login and remote command execution, +but any network service can be secured with SSH. The protocol specification +distinguishes between two major versions, referred to as SSH-1 and SSH-2. + +The most visible application of the protocol is for access to shell accounts +on Unix-like operating systems, but it sees some limited use on Windows as +well. In 2015, Microsoft announced that they would include native support for +SSH in a future release. + +SSH was designed as a replacement for Telnet and for unsecured remote shell +protocols such as the Berkeley rlogin, rsh, and rexec protocols. +Those protocols send information, notably passwords, in plaintext, +rendering them susceptible to interception and disclosure using packet +analysis. The encryption used by SSH is intended to provide confidentiality +and integrity of data over an unsecured network, such as the Internet. + +:::{note} +VyOS 1.1 supported login as user `root`. This has been removed due +to tighter security in VyOS 1.2. +::: + +:::{seealso} +SSH {ref}`ssh_key_based_authentication` +::: + +## Configuration + +```{cfgcmd} set service ssh port \<port\> + +Enabling SSH only requires you to specify the port ``<port>`` you want SSH to +listen on. By default, SSH runs on port 22. +``` + + +```{cfgcmd} set service ssh listen-address \<address\> + +Specify IPv4/IPv6 listen address of SSH server. Multiple addresses can be +defined. +``` + + +```{cfgcmd} set service ssh cipher \<cipher\> + +Define allowed ciphers used for the SSH connection. A number of allowed +ciphers can be specified, use multiple occurrences to allow multiple ciphers. + +List of supported ciphers: ``3des-cbc``, ``aes128-cbc``, ``aes192-cbc``, +``aes256-cbc``, ``aes128-ctr``, ``aes192-ctr``, ``aes256-ctr``, +``aes128-gcm@openssh.com``, ``aes256-gcm@openssh.com``, +``chacha20-poly1305@openssh.com`` +``` + + +```{cfgcmd} set service ssh disable-password-authentication + +Disable password based authentication. Login via SSH keys only. This hardens +security! +``` + + +```{cfgcmd} set service ssh fido pin-required + +Require FIDO2 keys to attest that a user has been verified (e.g. via a PIN). +``` + + +````{cfgcmd} set service ssh fido touch-required + +Require FIDO2 keys to attest that a user is physically present. + +VyOS supports SSH authentication using FIDO2-backed keys generated by OpenSSH. +Two FIDO2 key types are supported by OpenSSH: ``ed25519-sk``, ``ecdsa-sk`` + +Generic FIDO2-backed SSH key generation example: + +:::{code-block} none +ssh-keygen -t ecdsa-sk -O verify-required -C "fido2-ssh-key" +::: + +```{eval-rst} +During key generation, OpenSSH will: + * Request user presence (for example, a physical touch or confirmation) + * Optionally request user verification (PIN), if supported by the authenticator + * Create a local key handle file and a corresponding public key (``.pub``) +``` + +The private key material never leaves the authenticator device. + +VyOS configuration example: + +:::{code-block} none +# Generate a FIDO2 SSH key on the client system +# Copy the public key to the VyOS instance +set system login user vyos authentication public-keys fido key '<public-key>' +set system login user vyos authentication public-keys fido type 'sk-ecdsa-sha2-nistp256@openssh.com' +set service ssh fido touch-required +::: + +You can now log into the system using: ``ssh -i ~/.ssh/id_fido_key vyos@192.0.2.1`` +```` + + +```{cfgcmd} set service ssh disable-host-validation + +Disable the host validation through reverse DNS lookups - can speedup login +time when reverse lookup is not possible. +``` + + +```{cfgcmd} set service ssh mac \<mac\> + +Specifies the available {abbr}`MAC (Message Authentication Code)` algorithms. +The MAC algorithm is used in protocol version 2 for data integrity protection. +Multiple algorithms can be provided by using multiple commands, defining +one algorithm per command. + +List of supported MACs: ``hmac-md5``, ``hmac-md5-96``, ``hmac-ripemd160``, +``hmac-sha1``, ``hmac-sha1-96``, ``hmac-sha2-256``, ``hmac-sha2-512``, +``umac-64@openssh.com``, ``umac-128@openssh.com``, +``hmac-md5-etm@openssh.com``, ``hmac-md5-96-etm@openssh.com``, +``hmac-ripemd160-etm@openssh.com``, ``hmac-sha1-etm@openssh.com``, +``hmac-sha1-96-etm@openssh.com``, ``hmac-sha2-256-etm@openssh.com``, +``hmac-sha2-512-etm@openssh.com``, ``umac-64-etm@openssh.com``, +``umac-128-etm@openssh.com`` +``` + + +```{cfgcmd} set service ssh access-control \<allow | deny\> \<group | user\> \<name\> + +Add access-control directive to allow or deny users and groups. Directives +are processed in the following order of precedence: ``deny-users``, +``allow-users``, ``deny-groups`` and ``allow-groups``. +``` + + +```{cfgcmd} set service ssh client-keepalive-interval \<interval\> + +Specify timeout interval for keepalive message in seconds. +``` + + +```{cfgcmd} set service ssh key-exchange \<kex\> + +Specify allowed {abbr}`KEX (Key Exchange)` algorithms. + +List of supported algorithms: ``diffie-hellman-group1-sha1``, +``diffie-hellman-group14-sha1``, ``diffie-hellman-group14-sha256``, +``diffie-hellman-group16-sha512``, ``diffie-hellman-group18-sha512``, +``diffie-hellman-group-exchange-sha1``, +``diffie-hellman-group-exchange-sha256``, +``ecdh-sha2-nistp256``, ``ecdh-sha2-nistp384``, ``ecdh-sha2-nistp521``, +``curve25519-sha256`` and ``curve25519-sha256@libssh.org``. +``` + + +```{cfgcmd} set service ssh loglevel \<quiet | fatal | error | info | verbose\> + +Set the ``sshd`` log level. The default is ``info``. +``` + + +```{cfgcmd} set service ssh vrf \<name\> + +Specify name of the {abbr}`VRF (Virtual Routing and Forwarding)` instance. +``` + + +```{cfgcmd} set service ssh pubkey-accepted-algorithm \<name\> + +Specifies the signature algorithms that will be accepted for public key +authentication + +List of supported algorithms: ``ssh-ed25519``, +``ssh-ed25519-cert-v01@openssh.com``, ``sk-ssh-ed25519@openssh.com``, +``sk-ssh-ed25519-cert-v01@openssh.com``, ``ecdsa-sha2-nistp256``, +``ecdsa-sha2-nistp256-cert-v01@openssh.com``, ``ecdsa-sha2-nistp384``, +``ecdsa-sha2-nistp384-cert-v01@openssh.com``, ``ecdsa-sha2-nistp521``, +``ecdsa-sha2-nistp521-cert-v01@openssh.com``, +``sk-ecdsa-sha2-nistp256@openssh.com``, +``sk-ecdsa-sha2-nistp256-cert-v01@openssh.com``, +``webauthn-sk-ecdsa-sha2-nistp256@openssh.com``, +``ssh-dss``, ``ssh-dss-cert-v01@openssh.com``, ``ssh-rsa``, +``ssh-rsa-cert-v01@openssh.com``, ``rsa-sha2-256``, +``rsa-sha2-256-cert-v01@openssh.com``, ``rsa-sha2-512``, +``rsa-sha2-512-cert-v01@openssh.com`` +``` + + +```{cfgcmd} set service ssh trusted-user-ca \<name\> + +Specify the name of the OpenSSH key-pair that acts as certificate authority +and will be used to verify user certificates. + +You can use it by adding the OpenSSH key-pair under the PKI subsystem. + +Example: + +:::{code-block} none +# Generate key-pair acting as CA +$ ssh-keygen -f vyos-ssh-ca.key + +# Generate key for user: vyos_testca +$ ssh-keygen -f vyos_testca -C "vyos_tesca@vyos.net" + +# Sign public key from user vyos_testca and insert principal names: vyos, vyos_testca +# with a key lifetime of two weeks - after which the key is unusable +$ ssh-keygen -s vyos-ssh-ca.key -I vyos_testca@vyos.net -n vyos,vyos_testca -V +2w vyos_testca.pub + +$ set system login user vyos_testca +$ set pki openssh test_ca public key AAAAB3N..... +$ set pki openssh test_ca public type ssh-rsa +$ set service ssh trusted-user-ca test_ca +::: +You can now log into the system using: ``ssh -i vyos_testca vyos_testca@vyos.test.com`` +``` + +## Dynamic-protection + +Protects host from brute-force attacks against +SSH. Log messages are parsed, line-by-line, for recognized patterns. If an +attack, such as several login failures within a few seconds, is detected, the +offending IP is blocked. Offenders are unblocked after a set interval. + +```{cfgcmd} set service ssh dynamic-protection + +Allow ``ssh`` dynamic-protection. +``` +```{cfgcmd} set service ssh dynamic-protection allow-from \<address | prefix\> + +Whitelist of addresses and networks. Always allow inbound connections from +these systems. +``` +```{cfgcmd} set service ssh dynamic-protection block-time \<sec\> + +Block source IP in seconds. Subsequent blocks increase by a factor of 1.5 +The default is 120. +``` +```{cfgcmd} set service ssh dynamic-protection detect-time \<sec\> + +Remember source IP in seconds before reset their score. The default is 1800. +``` +```{cfgcmd} set service ssh dynamic-protection threshold \<sec\> + +Block source IP when their cumulative attack score exceeds threshold. The +default is 30. +``` + +(ssh-operation)= + +## Operation + +```{opcmd} restart ssh + +Restart the SSH daemon process, the current session is not affected, only the +background daemon is restarted. +``` +```{opcmd} generate ssh server-key + +Re-generated the public/private keyportion which SSH uses to secure +connections. + +:::{note} +Already learned known_hosts files of clients need an update as the +public key will change. +::: +``` +```{opcmd} generate ssh client-key /path/to/private_key + +Re-generated a known pub/private keyfile which can be used to connect to +other services (e.g. RPKI cache). + +Example: + +:::{code-block} none +vyos@vyos:~$ generate ssh client-key /config/auth/id_rsa_rpki +Generating public/private rsa key pair. +Your identification has been saved in /config/auth/id_rsa_rpki. +Your public key has been saved in /config/auth/id_rsa_rpki.pub. +The key fingerprint is: +SHA256:XGv2PpdOzVCzpmEzJZga8hTRq7B/ZYL3fXaioLFLS5Q vyos@vyos +The key's randomart image is: ++---[RSA 2048]----+ +| oo | +| ..o | +| . o.o.. o.| +| o+ooo o.o| +| Eo* =.o | +| o = +.o*+ | +| = o *.o.o| +| o * +.o+.+| +| =.. o=.oo| ++----[SHA256]-----+ +::: +Two new files ``/config/auth/id_rsa_rpki`` and +``/config/auth/id_rsa_rpki.pub`` +will be created. +``` +```{opcmd} generate public-key-command user \<username\> path \<location\> + +> Generate the configuration mode commands to add a public key for +> {ref}`ssh_key_based_authentication`. +> ``<location>`` can be a local path or a URL pointing at a remote file. +> +> Supported remote protocols are FTP, FTPS, HTTP, HTTPS, SCP/SFTP and TFTP. + +Example: + +:::{code-block} none +alyssa@vyos:~$ generate public-key-command user alyssa path sftp://example.net/home/alyssa/.ssh/id_rsa.pub +# To add this key as an embedded key, run the following commands: +configure +set system login user alyssa authentication public-keys alyssa@example.net key AAA... +set system login user alyssa authentication public-keys alyssa@example.net type ssh-rsa +commit +save +exit + +ben@vyos:~$ generate public-key-command user ben path ~/.ssh/id_rsa.pub +# To add this key as an embedded key, run the following commands: +configure +set system login user ben authentication public-keys ben@vyos key AAA... +set system login user ben authentication public-keys ben@vyos type ssh-dss +commit +save +exit +::: +``` +```{opcmd} show log ssh + +Show SSH server log. +``` +```{opcmd} monitor log ssh + +Follow the SSH server log. +``` +```{opcmd} show log ssh dynamic-protection + +Show SSH dynamic-protection log. +``` +```{opcmd} monitor log ssh dynamic-protection + +Follow the SSH dynamic-protection log. +``` +```{opcmd} show ssh dynamic-protection + +Show list of IPs currently blocked by SSH dynamic-protection. +``` +```{opcmd} show ssh fingerprints + +Show SSH server public key fingerprints. +``` +```{opcmd} show ssh fingerprints ascii + +Show SSH server public key fingerprints, including a visual ASCII art representation. +```
\ No newline at end of file diff --git a/docs/configuration/service/md-suricata.md b/docs/configuration/service/md-suricata.md new file mode 100644 index 00000000..ca9ae968 --- /dev/null +++ b/docs/configuration/service/md-suricata.md @@ -0,0 +1,93 @@ +(suricata)= + +# suricata + +Suricata and VyOS are powerful tools for ensuring network security and traffic management. +Suricata is an open-source intrusion detection and prevention system (IDS/IPS) that analyzes network packets in real-time. + +## Suricata Features + +Intrusion Detection (IDS): Analyzes network traffic and detects suspicious activities, attacks, and malicious traffic. +Intrusion Prevention (IPS): Blocks or modifies suspicious traffic in real-time, preventing attacks before they penetrate the network. +Network Security Monitoring (NSM): Collects and analyzes network data to detect anomalies and identify threats. +Multi-Protocol Support: Suricata supports analysis of various network protocols such as HTTP, FTP, SMB, and many others. +In configuration mode, the commands are as follows: + +```none +vyos@vyos# set service suricata +Possible completions: ++> address-group Address group name ++ interface Interface to use + > log Suricata log outputs ++> port-group Port group name +``` + +These commands create a flexible interface for configuring the Suricata service, allowing users to specify addresses, ports, +and logging parameters. + +After completing the service configuration in configuration mode, the main configuration file suricata.yaml is created, +into which all specified parameters are added. Then, to ensure proper operation, the command {opcmd}`update suricata` must be run +from operational mode, waiting for Suricata to update all its rules, which are used for analyzing traffic for threats and attacks. + +## Configuration + +```{cfgcmd} set service suricata address-group \<text\> \<address | group\> + + Address groups are useful when you need to create rules that apply to specific IP addresses. + For example, if you want to create a rule that monitors traffic going to or from a specific IP address, + you can use the group name instead of the actual IP address. This simplifies rule management and makes the + configuration more flexible. + + * ``address`` IP address or subnet. + + * ``group`` Address group. +``` + + +```{cfgcmd} set service suricata port-group \<text\> \<address | group\> + +Port groups are useful when you need to create rules that apply to specific ports. +For example, if you want to create a rule that monitors traffic directed to a specific port or group of ports, +you can use the group name instead of the actual port. This also simplifies rule management and makes +the configuration more flexible. + +* ``port`` Port number. + +* ``group`` Port group. +``` + + +```{cfgcmd} set service suricata interface \<text\> + +The interface that will be monitored by the Suricata service. +``` +```{cfgcmd} set service suricata log eve \<filename | filetype | type\> + + Configuration of the logging file. + + * ``filename`` Log file (default: eve.json). + + * ``filetype`` EVE logging destination (default: regular). + + * ``type`` Log types. +``` + +## Operation Mode + +```{cfgcmd} update suricata + +Checks for the existence of the Suricata configuration file, updates the service, +and then restarts it. If the configuration file is not found, a message indicates that Suricata is not configured. +``` +```{cfgcmd} restart suricata + +Restarts the service. It checks if the Suricata service is active before attempting to restart it. +If it is not active, a message indicates that the service is not configured. This command is used when adding new rules manually. +``` + +## Conclusion + +Using address and port groups allows you to make your Suricata configuration more flexible and manageable. +Instead of specifying IP addresses and ports directly in each rule, you can define them once in the vars section and then +reference them by group names. This is especially useful in large networks and complex configurations where multiple IP addresses +and ports need to be monitored. diff --git a/docs/configuration/service/md-tftp-server.md b/docs/configuration/service/md-tftp-server.md new file mode 100644 index 00000000..f4a6c34c --- /dev/null +++ b/docs/configuration/service/md-tftp-server.md @@ -0,0 +1,78 @@ +(tftp-server)= + +# TFTP Server + +{abbr}`TFTP (Trivial File Transfer Protocol)` is a simple, lockstep file +transfer protocol which allows a client to get a file from or put a file onto +a remote host. One of its primary uses is in the early stages of nodes booting +from a local area network. TFTP has been used for this application because it +is very simple to implement. + +## Configuration + +```{cfgcmd} set service tftp-server directory \<directory\> + +Enable TFTP service by specifying the `<directory>` which will be used to serve +files. +``` + +:::{hint} +Choose your `directory` location carefully or you will loose the +content on image upgrades. Any directory under `/config` is save at this +will be migrated. +::: + +```{cfgcmd} set service tftp-server listen-address \<address\> + +Configure the IPv4 or IPv6 listen address of the TFTP server. Multiple IPv4 and +IPv6 addresses can be given. There will be one TFTP server instances listening +on each IP address. +``` + +```{cfgcmd} set service tftp-server listen-address \<address\> vrf \<name\> +``` + +Additional option to run TFTP server in the {abbr}`VRF (Virtual Routing and Forwarding)` context + +:::{note} +Configuring a listen-address is essential for the service to work. +::: +```{cfgcmd} set service tftp-server allow-upload + +Optional, if you want to enable uploads, else TFTP server will act as a +read-only server. +``` + +### Example + +Provide TFTP server listening on both IPv4 and IPv6 addresses `192.0.2.1` and +`2001:db8::1` serving the content from `/config/tftpboot`. Uploading via +TFTP to this server is disabled. + +The resulting configuration will look like: + +```none +vyos@vyos# show service + tftp-server { + directory /config/tftpboot + listen-address 2001:db8::1 + listen-address 192.0.2.1 + } +``` + +### Verification + +Client: + +```none +vyos@RTR2:~$ tftp -p -l /config/config.boot -r backup 192.0.2.1 +backup1 100% |******************************| 723 0:00:00 ETA +``` + +Server: + +```none +vyos@RTR1# ls -ltr /config/tftpboot/ +total 1 +-rw-rw-rw- 1 tftp tftp 1995 May 19 16:02 backup +``` diff --git a/docs/configuration/service/md-webproxy.md b/docs/configuration/service/md-webproxy.md new file mode 100644 index 00000000..28156b2b --- /dev/null +++ b/docs/configuration/service/md-webproxy.md @@ -0,0 +1,459 @@ +(webproxy)= + +# Webproxy + +The proxy service in VyOS is based on [Squid] and some related modules. + +[Squid] is a caching and forwarding HTTP web proxy. It has a wide variety of +uses, including speeding up a web server by caching repeated requests, caching +web, DNS and other computer network lookups for a group of people sharing +network resources, and aiding security by filtering traffic. Although primarily +used for HTTP and FTP, Squid includes limited support for several other +protocols including Internet Gopher, SSL,[6] TLS and HTTPS. Squid does not +support the SOCKS protocol. + +URL Filtering is provided by [SquidGuard]. + +## Configuration + +```{cfgcmd} set service webproxy append-domain \<domain\> + +Use this command to specify a domain name to be appended to domain-names +within URLs that do not include a dot ``.`` the domain is appended. + +Example: to be appended is set to ``vyos.net`` and the URL received is +``www/foo.html``, the system will use the generated, final URL of +``www.vyos.net/foo.html``. + +:::{code-block} none +set service webproxy append-domain vyos.net +::: +``` + + +```{cfgcmd} set service webproxy cache-size \<size\> + +The size of the on-disk Proxy cache is user configurable. The Proxies default +cache-size is configured to 100 MB. + +Unit of this command is MB. + +:::{code-block} none +set service webproxy cache-size 1024 +::: +``` + + +```{cfgcmd} set service webproxy default-port \<port\> + +Specify the port used on which the proxy service is listening for requests. +This port is the default port used for the specified listen-address. + +Default port is 3128. + +:::{code-block} none +set service webproxy default-port 8080 +::: +``` + + +```{cfgcmd} set service webproxy domain-block \<domain\> + +Used to block specific domains by the Proxy. Specifying "vyos.net" will block +all access to vyos.net, and specifying ".xxx" will block all access to URLs +having an URL ending on .xxx. + +:::{code-block} none +set service webproxy domain-block vyos.net +::: +``` + + +```{cfgcmd} set service webproxy domain-noncache \<domain\> + +Allow access to sites in a domain without retrieving them from the Proxy +cache. Specifying "vyos.net" will allow access to vyos.net but the pages +accessed will not be cached. It useful for working around problems with +"If-Modified-Since" checking at certain sites. + +:::{code-block} none +set service webproxy domain-noncache vyos.net +::: +``` + + +```{cfgcmd} set service webproxy listen-address \<address\> + +Specifies proxy service listening address. The listen address is the IP +address on which the web proxy service listens for client requests. + +For security, the listen address should only be used on internal/trusted +networks! + +:::{code-block} none +set service webproxy listen-address 192.0.2.1 +::: +``` + + +```{cfgcmd} set service webproxy listen-address \<address\> disable-transparent + +Disables web proxy transparent mode at a listening address. + +In transparent proxy mode, all traffic arriving on port 80 and destined for +the Internet is automatically forwarded through the proxy. This allows +immediate proxy forwarding without configuring client browsers. + +Non-transparent proxying requires that the client browsers be configured with +the proxy settings before requests are redirected. The advantage of this is +that the client web browser can detect that a proxy is in use and can behave +accordingly. In addition, web-transmitted malware can sometimes be blocked by +a non-transparent web proxy, since they are not aware of the proxy settings. + +:::{code-block} none +set service webproxy listen-address 192.0.2.1 disable-transparent +::: +``` + + +```{cfgcmd} set service webproxy listen-address \<address\> port \<port\> + +Sets the listening port for a listening address. This overrides the default +port of 3128 on the specific listen address. + +:::{code-block} none +set service webproxy listen-address 192.0.2.1 port 8080 +::: +``` +```{cfgcmd} set service webproxy reply-block-mime \<mime\> + +Used to block a specific mime-type. + +:::{code-block} none +# block all PDFs +set service webproxy reply-block-mime application/pdf +::: +``` +```{cfgcmd} set service webproxy reply-body-max-size \<size\> + +Specifies the maximum size of a reply body in KB, used to limit the reply +size. + +All reply sizes are accepted by default. + +:::{code-block} none +set service webproxy reply-body-max-size 2048 +::: +``` + + +```{cfgcmd} set service webproxy safe-ports \<port\> + +Add new port to Safe-ports acl. Ports included by default in Safe-ports acl: +21, 70, 80, 210, 280, 443, 488, 591, 777, 873, 1025-65535 +``` + + +```{cfgcmd} set service webproxy ssl-safe-ports \<port\> + +Add new port to SSL-ports acl. Ports included by default in SSL-ports acl: +443 +``` + +### Authentication + +The embedded Squid proxy can use LDAP to authenticate users against a company +wide directory. The following configuration is an example of how to use Active +Directory as authentication backend. Queries are done via LDAP. + +```{cfgcmd} set service webproxy authentication children \<number\> + +Maximum number of authenticator processes to spawn. If you start too few +Squid will have to wait for them to process a backlog of credential +verifications, slowing it down. When password verifications are done via a +(slow) network you are likely to need lots of authenticator processes. + +This defaults to 5. + +:::{code-block} none +set service webproxy authentication children 10 +::: +``` + + +```{cfgcmd} set service webproxy authentication credentials-ttl \<time\> + +Specifies how long squid assumes an externally validated username:password +pair is valid for - in other words how often the helper program is called for +that user. Set this low to force revalidation with short lived passwords. + +Time is in minutes and defaults to 60. + +:::{code-block} none +set service webproxy authentication credentials-ttl 120 +::: +``` +```{cfgcmd} set service webproxy authentication method \<ldap\> + +Proxy authentication method, currently only LDAP is supported. + +:::{code-block} none +set service webproxy authentication method ldap +::: +``` + + +```{cfgcmd} set service webproxy authentication realm + +Specifies the protection scope (aka realm name) which is to be reported to +the client for the authentication scheme. It is commonly part of the text +the user will see when prompted for their username and password. + +:::{code-block} none +set service webproxy authentication realm "VyOS proxy auth" +::: +``` + +#### LDAP + +```{cfgcmd} set service webproxy authentication ldap base-dn \<base-dn\> + +Specifies the base DN under which the users are located. + +:::{code-block} none +set service webproxy authentication ldap base-dn DC=vyos,DC=net +::: +``` +```{cfgcmd} set service webproxy authentication ldap bind-dn \<bind-dn\> + +The DN and password to bind as while performing searches. + +:::{code-block} none +set service webproxy authentication ldap bind-dn CN=proxyuser,CN=Users,DC=vyos,DC=net +::: +``` + + +```{cfgcmd} set service webproxy authentication ldap filter-expression \<expr\> + +LDAP search filter to locate the user DN. Required if the users are in a +hierarchy below the base DN, or if the login name is not what builds the user +specific part of the users DN. + +The search filter can contain up to 15 occurrences of %s which will be +replaced by the username, as in "uid=%s" for {rfc}`2037` directories. For a +detailed description of LDAP search filter syntax see {rfc}`2254`. + +:::{code-block} none +set service webproxy authentication ldap filter-expression (cn=%s) +::: +``` + + +```{cfgcmd} set service webproxy authentication ldap password \<password\> + +The DN and password to bind as while performing searches. As the password +needs to be printed in plain text in your Squid configuration it is strongly +recommended to use a account with minimal associated privileges. This to limit +the damage in case someone could get hold of a copy of your Squid +configuration file. + +:::{code-block} none +set service webproxy authentication ldap password vyos +::: +``` + + +```{cfgcmd} set service webproxy authentication ldap persistent-connection + +Use a persistent LDAP connection. Normally the LDAP connection is only open +while validating a username to preserve resources at the LDAP server. This +option causes the LDAP connection to be kept open, allowing it to be reused +for further user validations. + +Recommended for larger installations. + +:::{code-block} none +set service webproxy authentication ldap persistent-connection +::: +``` + + +```{cfgcmd} set service webproxy authentication ldap port \<port\> + +Specify an alternate TCP port where the ldap server is listening if other than +the default LDAP port 389. + +:::{code-block} none +set service webproxy authentication ldap port 389 +::: +``` + + +```{cfgcmd} set service webproxy authentication ldap server \<server\> + +Specify the LDAP server to connect to. + +:::{code-block} none +set service webproxy authentication ldap server ldap.vyos.net +::: +``` +```{cfgcmd} set service webproxy authentication ldap use-ssl + +Use TLS encryption. + +:::{code-block} none +set service webproxy authentication ldap use-ssl +::: +``` +```{cfgcmd} set service webproxy authentication ldap username-attribute \<attr\> + +Specifies the name of the DN attribute that contains the username/login. +Combined with the base DN to construct the users DN when no search filter is +specified (filter-expression). + +Defaults to 'uid' + +:::{note} +This can only be done if all your users are located directly under +the same position in the LDAP tree and the login name is used for naming +each user object. If your LDAP tree does not match these criterias or if you +want to filter who are valid users then you need to use a search filter to +search for your users DN (filter-expression). +::: + +:::{code-block} none +set service webproxy authentication ldap username-attribute uid +::: +``` + + +```{cfgcmd} set service webproxy authentication ldap version \<2 | 3\> + +LDAP protocol version. Defaults to 3 if not specified. + +:::{code-block} none +set service webproxy authentication ldap version 2 +::: +``` + +### URL filtering + +```{include} /_include/need_improvement.txt +``` +```{cfgcmd} set service webproxy url-filtering disable + +Disables web filtering without discarding configuration. + +:::{code-block} none +set service webproxy url-filtering disable +::: +``` + +## Operation + +```{include} /_include/need_improvement.txt +``` + +### Filtering +#### Update + +If you want to use existing blacklists you have to create/download a database +first. Otherwise you will not be able to commit the config changes. + +```{opcmd} update webproxy blacklists + +Download/Update complete blacklist + +:::{code-block} none +vyos@vyos:~$ update webproxy blacklists +Warning: No url-filtering blacklist installed +Would you like to download a default blacklist? [confirm][y] +Connecting to ftp.univ-tlse1.fr (193.49.48.249:21) +blacklists.gz 100% |*************************************************************************************************************| 17.0M 0:00:00 ETA +Uncompressing blacklist... +Checking permissions... +Skip link for [ads] -> [publicite] +Building DB for [adult/domains] - 2467177 entries +Building DB for [adult/urls] - 67798 entries +Skip link for [aggressive] -> [agressif] +Building DB for [agressif/domains] - 348 entries +Building DB for [agressif/urls] - 36 entries +Building DB for [arjel/domains] - 69 entries +... +Building DB for [webmail/domains] - 374 entries +Building DB for [webmail/urls] - 9 entries +The webproxy daemon must be restarted +Would you like to restart it now? [confirm][y] +[ ok ] Restarting squid (via systemctl): squid.service. +vyos@vyos:~$ +::: +``` +```{opcmd} update webproxy blacklists category \<category\> + +Download/Update partial blacklist. + +Use tab completion to get a list of categories. +``` + +- To auto update the blacklist files + + `set service webproxy url-filtering squidguard auto-update update-hour 23` + +- To configure blocking add the following to the configuration + + `set service webproxy url-filtering squidguard block-category ads` + + `set service webproxy url-filtering squidguard block-category malware` + +#### Bypassing the webproxy + +```{include} /_include/need_improvement.txt +``` + +Some services don't work correctly when being handled via a web proxy. +So sometimes it is useful to bypass a transparent proxy: + +- To bypass the proxy for every request that is directed to a specific + destination: + + `set service webproxy whitelist destination-address 198.51.100.33` + + `set service webproxy whitelist destination-address 192.0.2.0/24` + +- To bypass the proxy for every request that is coming from a specific source: + + `set service webproxy whitelist source-address 192.168.1.2` + + `set service webproxy whitelist source-address 192.168.2.0/24` + + (This can be useful when a called service has many and/or often changing + destination addresses - e.g. Netflix.) + +## Examples + +```none +vyos@vyos# show service webproxy + authentication { + children 5 + credentials-ttl 60 + ldap { + base-dn DC=example,DC=local + bind-dn CN=proxyuser,CN=Users,DC=example,DC=local + filter-expression (cn=%s) + password Qwert1234 + server ldap.example.local + username-attribute cn + } + method ldap + realm "VyOS Webproxy" + } + cache-size 100 + default-port 3128 + listen-address 192.168.188.103 { + disable-transparent + } +``` + +[squid]: http://www.squid-cache.org/ +[squidguard]: http://www.squidguard.org/ |