From 5d6fa52b8985f8068314aba26878a1d7d5cb84e5 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 20:42:32 +0300 Subject: feat: flip swap mechanism — MD as primary, RST as override (Phase 1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is the first of three phases inverting the per-page swap mechanism so MD becomes the canonical primary and RST becomes the rare override. Phase 1 — file renames + conf.py exclude_patterns flip only: - Rename docs/**/md-.md to docs/**/.md (drop md- prefix) for all 254 stems previously listed in docs/_swap.txt - Rename docs/**/.rst to docs/**/rst-.rst (add rst- prefix) for the same 254 stems - Repurpose docs/_swap.txt as docs/_rst_overrides.txt; initially empty comment-only since no pages need the RST fallback right now - conf.py exclude_patterns flipped: rst-*.rst is now excluded by default instead of md-*.md - conf.py runtime-artifact references updated to _rst_override_state.json and _md_exclude.txt (Phase 2 will rewrite swap_sources.py to produce these names; for now no swap script runs because overrides list is empty) Phase 2 (next commit on this branch) will rewrite scripts/swap_sources.py with inverted rename direction, delete scripts/import_myst.py + tests, and update tests/test_swap_sources.py for the new semantics. Phase 3 will be the cleanup pass and ready-for-review flip. Generated by robots https://vyos.io --- docs/configuration/service/broadcast-relay.md | 70 ++ docs/configuration/service/broadcast-relay.rst | 66 -- docs/configuration/service/config-sync.md | 164 +++ docs/configuration/service/config-sync.rst | 160 --- docs/configuration/service/conntrack-sync.md | 321 ++++++ docs/configuration/service/conntrack-sync.rst | 302 ----- docs/configuration/service/console-server.md | 139 +++ docs/configuration/service/console-server.rst | 120 -- docs/configuration/service/dhcp-relay.md | 205 ++++ docs/configuration/service/dhcp-relay.rst | 205 ---- docs/configuration/service/dhcp-server.md | 1178 ++++++++++++++++++++ docs/configuration/service/dhcp-server.rst | 1087 ------------------ docs/configuration/service/dns.md | 582 ++++++++++ docs/configuration/service/dns.rst | 511 --------- docs/configuration/service/eventhandler.md | 129 +++ docs/configuration/service/eventhandler.rst | 159 --- docs/configuration/service/https.md | 138 +++ docs/configuration/service/https.rst | 124 --- docs/configuration/service/index.md | 29 + docs/configuration/service/index.rst | 31 - docs/configuration/service/ipoe-server.md | 512 +++++++++ docs/configuration/service/ipoe-server.rst | 450 -------- docs/configuration/service/lldp.md | 154 +++ docs/configuration/service/lldp.rst | 148 --- docs/configuration/service/md-broadcast-relay.md | 70 -- docs/configuration/service/md-config-sync.md | 164 --- docs/configuration/service/md-conntrack-sync.md | 321 ------ docs/configuration/service/md-console-server.md | 139 --- docs/configuration/service/md-dhcp-relay.md | 205 ---- docs/configuration/service/md-dhcp-server.md | 1178 -------------------- docs/configuration/service/md-dns.md | 582 ---------- docs/configuration/service/md-eventhandler.md | 129 --- docs/configuration/service/md-https.md | 138 --- docs/configuration/service/md-index.md | 29 - docs/configuration/service/md-ipoe-server.md | 512 --------- docs/configuration/service/md-lldp.md | 154 --- docs/configuration/service/md-mdns.md | 131 --- docs/configuration/service/md-monitoring.md | 334 ------ docs/configuration/service/md-ntp.md | 202 ---- docs/configuration/service/md-pppoe-server.md | 753 ------------- docs/configuration/service/md-router-advert.md | 121 -- docs/configuration/service/md-salt-minion.md | 51 - docs/configuration/service/md-snmp.md | 258 ----- docs/configuration/service/md-ssh.md | 366 ------ docs/configuration/service/md-suricata.md | 93 -- docs/configuration/service/md-tftp-server.md | 78 -- docs/configuration/service/md-webproxy.md | 459 -------- docs/configuration/service/mdns.md | 131 +++ docs/configuration/service/mdns.rst | 124 --- docs/configuration/service/monitoring.md | 334 ++++++ docs/configuration/service/monitoring.rst | 289 ----- docs/configuration/service/ntp.md | 202 ++++ docs/configuration/service/ntp.rst | 197 ---- docs/configuration/service/pppoe-server.md | 753 +++++++++++++ docs/configuration/service/pppoe-server.rst | 685 ------------ docs/configuration/service/router-advert.md | 121 ++ docs/configuration/service/router-advert.rst | 130 --- docs/configuration/service/rst-broadcast-relay.rst | 66 ++ docs/configuration/service/rst-config-sync.rst | 160 +++ docs/configuration/service/rst-conntrack-sync.rst | 302 +++++ docs/configuration/service/rst-console-server.rst | 120 ++ docs/configuration/service/rst-dhcp-relay.rst | 205 ++++ docs/configuration/service/rst-dhcp-server.rst | 1087 ++++++++++++++++++ docs/configuration/service/rst-dns.rst | 511 +++++++++ docs/configuration/service/rst-eventhandler.rst | 159 +++ docs/configuration/service/rst-https.rst | 124 +++ docs/configuration/service/rst-index.rst | 31 + docs/configuration/service/rst-ipoe-server.rst | 450 ++++++++ docs/configuration/service/rst-lldp.rst | 148 +++ docs/configuration/service/rst-mdns.rst | 124 +++ docs/configuration/service/rst-monitoring.rst | 289 +++++ docs/configuration/service/rst-ntp.rst | 197 ++++ docs/configuration/service/rst-pppoe-server.rst | 685 ++++++++++++ docs/configuration/service/rst-router-advert.rst | 130 +++ docs/configuration/service/rst-salt-minion.rst | 53 + docs/configuration/service/rst-snmp.rst | 276 +++++ docs/configuration/service/rst-ssh.rst | 334 ++++++ docs/configuration/service/rst-suricata.rst | 101 ++ docs/configuration/service/rst-tftp-server.rst | 80 ++ docs/configuration/service/rst-webproxy.rst | 445 ++++++++ docs/configuration/service/salt-minion.md | 51 + docs/configuration/service/salt-minion.rst | 53 - docs/configuration/service/snmp.md | 258 +++++ docs/configuration/service/snmp.rst | 276 ----- docs/configuration/service/ssh.md | 366 ++++++ docs/configuration/service/ssh.rst | 334 ------ docs/configuration/service/suricata.md | 93 ++ docs/configuration/service/suricata.rst | 101 -- docs/configuration/service/tftp-server.md | 78 ++ docs/configuration/service/tftp-server.rst | 80 -- docs/configuration/service/webproxy.md | 459 ++++++++ docs/configuration/service/webproxy.rst | 445 -------- 92 files changed, 12544 insertions(+), 12544 deletions(-) create mode 100644 docs/configuration/service/broadcast-relay.md delete mode 100644 docs/configuration/service/broadcast-relay.rst create mode 100644 docs/configuration/service/config-sync.md delete mode 100644 docs/configuration/service/config-sync.rst create mode 100644 docs/configuration/service/conntrack-sync.md delete mode 100644 docs/configuration/service/conntrack-sync.rst create mode 100644 docs/configuration/service/console-server.md delete mode 100644 docs/configuration/service/console-server.rst create mode 100644 docs/configuration/service/dhcp-relay.md delete mode 100644 docs/configuration/service/dhcp-relay.rst create mode 100644 docs/configuration/service/dhcp-server.md delete mode 100644 docs/configuration/service/dhcp-server.rst create mode 100644 docs/configuration/service/dns.md delete mode 100644 docs/configuration/service/dns.rst create mode 100644 docs/configuration/service/eventhandler.md delete mode 100644 docs/configuration/service/eventhandler.rst create mode 100644 docs/configuration/service/https.md delete mode 100644 docs/configuration/service/https.rst create mode 100644 docs/configuration/service/index.md delete mode 100644 docs/configuration/service/index.rst create mode 100644 docs/configuration/service/ipoe-server.md delete mode 100644 docs/configuration/service/ipoe-server.rst create mode 100644 docs/configuration/service/lldp.md delete mode 100644 docs/configuration/service/lldp.rst delete mode 100644 docs/configuration/service/md-broadcast-relay.md delete mode 100644 docs/configuration/service/md-config-sync.md delete mode 100644 docs/configuration/service/md-conntrack-sync.md delete mode 100644 docs/configuration/service/md-console-server.md delete mode 100644 docs/configuration/service/md-dhcp-relay.md delete mode 100644 docs/configuration/service/md-dhcp-server.md delete mode 100644 docs/configuration/service/md-dns.md delete mode 100644 docs/configuration/service/md-eventhandler.md delete mode 100644 docs/configuration/service/md-https.md delete mode 100644 docs/configuration/service/md-index.md delete mode 100644 docs/configuration/service/md-ipoe-server.md delete mode 100644 docs/configuration/service/md-lldp.md delete mode 100644 docs/configuration/service/md-mdns.md delete mode 100644 docs/configuration/service/md-monitoring.md delete mode 100644 docs/configuration/service/md-ntp.md delete mode 100644 docs/configuration/service/md-pppoe-server.md delete mode 100644 docs/configuration/service/md-router-advert.md delete mode 100644 docs/configuration/service/md-salt-minion.md delete mode 100644 docs/configuration/service/md-snmp.md delete mode 100644 docs/configuration/service/md-ssh.md delete mode 100644 docs/configuration/service/md-suricata.md delete mode 100644 docs/configuration/service/md-tftp-server.md delete mode 100644 docs/configuration/service/md-webproxy.md create mode 100644 docs/configuration/service/mdns.md delete mode 100644 docs/configuration/service/mdns.rst create mode 100644 docs/configuration/service/monitoring.md delete mode 100644 docs/configuration/service/monitoring.rst create mode 100644 docs/configuration/service/ntp.md delete mode 100644 docs/configuration/service/ntp.rst create mode 100644 docs/configuration/service/pppoe-server.md delete mode 100644 docs/configuration/service/pppoe-server.rst create mode 100644 docs/configuration/service/router-advert.md delete mode 100644 docs/configuration/service/router-advert.rst create mode 100644 docs/configuration/service/rst-broadcast-relay.rst create mode 100644 docs/configuration/service/rst-config-sync.rst create mode 100644 docs/configuration/service/rst-conntrack-sync.rst create mode 100644 docs/configuration/service/rst-console-server.rst create mode 100644 docs/configuration/service/rst-dhcp-relay.rst create mode 100644 docs/configuration/service/rst-dhcp-server.rst create mode 100644 docs/configuration/service/rst-dns.rst create mode 100644 docs/configuration/service/rst-eventhandler.rst create mode 100644 docs/configuration/service/rst-https.rst create mode 100644 docs/configuration/service/rst-index.rst create mode 100644 docs/configuration/service/rst-ipoe-server.rst create mode 100644 docs/configuration/service/rst-lldp.rst create mode 100644 docs/configuration/service/rst-mdns.rst create mode 100644 docs/configuration/service/rst-monitoring.rst create mode 100644 docs/configuration/service/rst-ntp.rst create mode 100644 docs/configuration/service/rst-pppoe-server.rst create mode 100644 docs/configuration/service/rst-router-advert.rst create mode 100644 docs/configuration/service/rst-salt-minion.rst create mode 100644 docs/configuration/service/rst-snmp.rst create mode 100644 docs/configuration/service/rst-ssh.rst create mode 100644 docs/configuration/service/rst-suricata.rst create mode 100644 docs/configuration/service/rst-tftp-server.rst create mode 100644 docs/configuration/service/rst-webproxy.rst create mode 100644 docs/configuration/service/salt-minion.md delete mode 100644 docs/configuration/service/salt-minion.rst create mode 100644 docs/configuration/service/snmp.md delete mode 100644 docs/configuration/service/snmp.rst create mode 100644 docs/configuration/service/ssh.md delete mode 100644 docs/configuration/service/ssh.rst create mode 100644 docs/configuration/service/suricata.md delete mode 100644 docs/configuration/service/suricata.rst create mode 100644 docs/configuration/service/tftp-server.md delete mode 100644 docs/configuration/service/tftp-server.rst create mode 100644 docs/configuration/service/webproxy.md delete mode 100644 docs/configuration/service/webproxy.rst (limited to 'docs/configuration/service') diff --git a/docs/configuration/service/broadcast-relay.md b/docs/configuration/service/broadcast-relay.md new file mode 100644 index 00000000..4202ad6b --- /dev/null +++ b/docs/configuration/service/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 \ 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 \ 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 \ address \ + +Set the source IP of forwarded packets, otherwise original senders address +is used. +``` + +```{cfgcmd} set service broadcast-relay id \ port \ + +The UDP port number used by your application. It is mandatory for this kind +of operation. +``` + +```{cfgcmd} set service broadcast-relay id \ 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/broadcast-relay.rst b/docs/configuration/service/broadcast-relay.rst deleted file mode 100644 index f64bb208..00000000 --- a/docs/configuration/service/broadcast-relay.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. _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 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 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 address - - Set the source IP of forwarded packets, otherwise original senders address - is used. - -.. cfgcmd:: set service broadcast-relay id port - - The UDP port number used by your application. It is mandatory for this kind - of operation. - -.. cfgcmd:: set service broadcast-relay id 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. - -.. code-block:: 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/config-sync.md b/docs/configuration/service/config-sync.md new file mode 100644 index 00000000..a575f947 --- /dev/null +++ b/docs/configuration/service/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 \ + +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 \ + +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 \ + +Two options are available for *mode*: either *load* and replace or *set* +the configuration section. +``` + +```none +Supported options for
include: + firewall + interfaces + nat + nat66 + pki + policy + protocols + qos + service + system + vpn + vrf +``` + + +## Operational Commands + +````{opcmd} show configuration secondary sync [commands] [running | candidate | saved] [\] + +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/config-sync.rst b/docs/configuration/service/config-sync.rst deleted file mode 100644 index a8984a0d..00000000 --- a/docs/configuration/service/config-sync.rst +++ /dev/null @@ -1,160 +0,0 @@ -.. _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 - - - 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
- - 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 - - Two options are available for `mode`: either `load` and replace or `set` - the configuration section. - -.. code-block:: none - - Supported options for
include: - firewall - interfaces - nat - nat66 - pki - policy - protocols - qos - service - system - vpn - vrf - -Operational Commands --------------------- - -.. opcmd:: show configuration secondary sync [commands] [running | candidate | saved] [] - - 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:** - - .. 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 - -.. code-block:: 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 - -.. code-block:: 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 - -.. code-block:: 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 - -.. code-block:: 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/conntrack-sync.md b/docs/configuration/service/conntrack-sync.md new file mode 100644 index 00000000..4aad6283 --- /dev/null +++ b/docs/configuration/service/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" keyword 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 \ + +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 \ + +Protocol for which expect entries need to be synchronized. +``` + + +```{cfgcmd} set service conntrack-sync failover-mechanism vrrp sync-group \ + +Failover mechanism to use for conntrack-sync. + +Only VRRP is supported. Required option. +``` + + +```{cfgcmd} set service conntrack-sync ignore-address \ + +IP addresses or networks for which local conntrack entries will not be synced +``` + + +```{cfgcmd} set service conntrack-sync interface \ + +Interface to use for syncing conntrack entries. +``` + + +```{cfgcmd} set service conntrack-sync interface \ port \ + +Port number used by connection. +``` + + +```{cfgcmd} set service conntrack-sync listen-address \ + +Local IPv4 addresses for service to listen on. +``` + + +```{cfgcmd} set service conntrack-sync mcast-group \ + +Multicast group to use for syncing conntrack entries. + +Defaults to 225.0.0.50. +``` + + +```{cfgcmd} set service conntrack-sync interface \ peer \ + +Peer to send unicast UDP conntrack sync entries to, if not using Multicast +configuration from above. +``` + + +```{cfgcmd} set service conntrack-sync sync-queue-size \ + +Queue size for syncing conntrack entries in MB. +``` + + +```{cfgcmd} set service conntrack-sync disable-external-cache + +This disables 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 (in seconds) for purging synchronized entries on handover events. + +On handover, ``conntrackd -t`` is invoked, which schedules a conntrack table +flush after ```` 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/conntrack-sync.rst b/docs/configuration/service/conntrack-sync.rst deleted file mode 100644 index 2527407e..00000000 --- a/docs/configuration/service/conntrack-sync.rst +++ /dev/null @@ -1,302 +0,0 @@ -.. _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 - - 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 - - Protocol for which expect entries need to be synchronized. - -.. stop_vyoslinter - -.. cfgcmd:: set service conntrack-sync failover-mechanism vrrp sync-group - - Failover mechanism to use for conntrack-sync. - - Only VRRP is supported. Required option. - -.. cfgcmd:: set service conntrack-sync ignore-address - - IP addresses or networks for which local conntrack entries will not - be synced - -.. start_vyoslinter - -.. cfgcmd:: set service conntrack-sync interface - - Interface to use for syncing conntrack entries. - -.. cfgcmd:: set service conntrack-sync interface port - - Port number used by connection. - -.. cfgcmd:: set service conntrack-sync listen-address - - Local IPv4 addresses for service to listen on. - -.. cfgcmd:: set service conntrack-sync mcast-group - - Multicast group to use for syncing conntrack entries. - - Defaults to 225.0.0.50. - -.. cfgcmd:: set service conntrack-sync interface peer
- - 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 - - 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 (in seconds) for purging synchronized entries on handover events. - - On handover, ``conntrackd -t`` is invoked, which schedules a conntrack table - flush after ```` 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.* - :scale: 60 % - :alt: Conntrack Sync Example - -Now configure conntrack-sync service on ``router1`` **and** ``router2`` - -.. code-block:: 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: - -.. code-block:: 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: - -.. code-block:: 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/console-server.md b/docs/configuration/service/console-server.md new file mode 100644 index 00000000..f0556652 --- /dev/null +++ b/docs/configuration/service/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 \ 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 \ description \ + +A user friendly description identifying the connected peripheral. +``` + + +```{cfgcmd} set service console-server device \ alias \ + +A user friendly alias for this connection. Can be used instead of the +device name when connecting. +``` + + +```{cfgcmd} set service console-server 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 \ 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 \ 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 \ ssh port \ + +Accept SSH connections for the given `` on TCP port ``. +After successful 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 \ + +Locally connect to serial port identified by ``. + +:::{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/console-server.rst b/docs/configuration/service/console-server.rst deleted file mode 100644 index c9ea7f77..00000000 --- a/docs/configuration/service/console-server.rst +++ /dev/null @@ -1,120 +0,0 @@ -.. _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 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 description - - A user friendly description identifying the connected peripheral. - -.. cfgcmd:: set service console-server device alias - - A user friendly alias for this connection. Can be used instead of the - device name when connecting. - -.. cfgcmd:: set service console-server 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 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 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 ssh port - - Accept SSH connections for the given `` on TCP 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 - - Locally connect to serial port identified by ``. - - .. 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/dhcp-relay.md b/docs/configuration/service/dhcp-relay.md new file mode 100644 index 00000000..a4a10109 --- /dev/null +++ b/docs/configuration/service/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 \ + +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 for DHCP Relay Agent to listen for requests. +``` + +```{cfgcmd} set service dhcp-relay upstream-interface \ + +Interface for DHCP Relay Agent to forward requests out. +``` + +```{cfgcmd} set service dhcp-relay server \ + +Configure IP address of the DHCP `` 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 \ + +Set the maximum hop `` before packets are discarded. Range 0...255, +default 10. +``` + +```{cfgcmd} set service dhcp-relay relay-options max-size \ + +Set maximum `` 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 \ + +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 \ + +Set eth1 to be the listening interface for the DHCPv6 relay. + +Multiple interfaces may be specified. +``` + +```{cfgcmd} set service dhcpv6-relay upstream-interface \ address \ + +Specifies an upstream network `` from which replies from +`` 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 \ + +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/dhcp-relay.rst b/docs/configuration/service/dhcp-relay.rst deleted file mode 100644 index 6a1b02f2..00000000 --- a/docs/configuration/service/dhcp-relay.rst +++ /dev/null @@ -1,205 +0,0 @@ -.. _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 - - 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 for DHCP Relay Agent to listen for requests. - -.. cfgcmd:: set service dhcp-relay upstream-interface - - Interface for DHCP Relay Agent to forward requests out. - -.. cfgcmd:: set service dhcp-relay server - - Configure IP address of the DHCP `` 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 - - Set the maximum hop `` before packets are discarded. Range 0...255, - default 10. - -.. cfgcmd:: set service dhcp-relay relay-options max-size - - Set maximum `` 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 - - - 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.* - :scale: 80 % - :alt: DHCP relay example - - DHCP relay example - -The generated configuration will look like: - -.. code-block:: 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: - -.. code-block:: 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 - - Set eth1 to be the listening interface for the DHCPv6 relay. - - Multiple interfaces may be specified. - -.. cfgcmd:: set service dhcpv6-relay upstream-interface - address - - Specifies an upstream network `` from which replies from - `` 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 - - 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.* - :scale: 80 % - :alt: DHCPv6 relay example - - DHCPv6 relay example - -The generated configuration will look like: - -.. code-block:: 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. diff --git a/docs/configuration/service/dhcp-server.md b/docs/configuration/service/dhcp-server.md new file mode 100644 index 00000000..721d6d4a --- /dev/null +++ b/docs/configuration/service/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: `_.` +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \ option 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 \ option domain-search \ + +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 \ option name-server \ + +Inform client that the DNS server can be found at `
`. + +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 \ option vendor-option \ + +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 \ + +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 \ 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 \ subnet \ subnet-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 \ subnet \ option default-router \ + +This is a configuration parameter for the ``, saying that as part of +the response, tell the client that the default gateway can be reached at +`
`. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \ subnet \ option name-server \ + +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 `
`. + +Multiple DNS servers can be defined. +``` + + +```{cfgcmd} set service dhcp-server shared-network-name \ subnet \ lease \ + +Assign the IP address to this machine for `