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