From fa54a080fac977157454beb0853daf0ac0e6af66 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Sat, 2 May 2026 17:25:47 +0300 Subject: feat(swap): import .md files and webp transition from myst/current MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- docs/configuration/service/broadcast-relay.md | 70 ++ docs/configuration/service/config-sync.md | 164 ++++ docs/configuration/service/conntrack-sync.md | 321 +++++++ docs/configuration/service/console-server.md | 139 +++ docs/configuration/service/dhcp-relay.md | 205 +++++ docs/configuration/service/dhcp-server.md | 1178 +++++++++++++++++++++++++ docs/configuration/service/dns.md | 582 ++++++++++++ docs/configuration/service/eventhandler.md | 130 +++ docs/configuration/service/https.md | 138 +++ docs/configuration/service/index.md | 29 + docs/configuration/service/ipoe-server.md | 512 +++++++++++ docs/configuration/service/lldp.md | 154 ++++ docs/configuration/service/mdns.md | 131 +++ docs/configuration/service/monitoring.md | 334 +++++++ docs/configuration/service/ntp.md | 202 +++++ docs/configuration/service/pppoe-server.md | 753 ++++++++++++++++ docs/configuration/service/router-advert.md | 121 +++ docs/configuration/service/salt-minion.md | 51 ++ docs/configuration/service/snmp.md | 258 ++++++ docs/configuration/service/ssh.md | 366 ++++++++ docs/configuration/service/suricata.md | 93 ++ docs/configuration/service/tftp-server.md | 78 ++ docs/configuration/service/webproxy.md | 459 ++++++++++ 23 files changed, 6468 insertions(+) create mode 100644 docs/configuration/service/broadcast-relay.md create mode 100644 docs/configuration/service/config-sync.md create mode 100644 docs/configuration/service/conntrack-sync.md create mode 100644 docs/configuration/service/console-server.md create mode 100644 docs/configuration/service/dhcp-relay.md create mode 100644 docs/configuration/service/dhcp-server.md create mode 100644 docs/configuration/service/dns.md create mode 100644 docs/configuration/service/eventhandler.md create mode 100644 docs/configuration/service/https.md create mode 100644 docs/configuration/service/index.md create mode 100644 docs/configuration/service/ipoe-server.md create mode 100644 docs/configuration/service/lldp.md create mode 100644 docs/configuration/service/mdns.md create mode 100644 docs/configuration/service/monitoring.md create mode 100644 docs/configuration/service/ntp.md create mode 100644 docs/configuration/service/pppoe-server.md create mode 100644 docs/configuration/service/router-advert.md create mode 100644 docs/configuration/service/salt-minion.md create mode 100644 docs/configuration/service/snmp.md create mode 100644 docs/configuration/service/ssh.md create mode 100644 docs/configuration/service/suricata.md create mode 100644 docs/configuration/service/tftp-server.md create mode 100644 docs/configuration/service/webproxy.md (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/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/conntrack-sync.md b/docs/configuration/service/conntrack-sync.md new file mode 100644 index 00000000..47a0ae2f --- /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" 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. +``` + + +```{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 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.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/console-server.md b/docs/configuration/service/console-server.md new file mode 100644 index 00000000..9402e935 --- /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 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-server.md b/docs/configuration/service/dhcp-server.md new file mode 100644 index 00000000..96c375da --- /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 `