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