diff options
| author | Yuriy Andamasov <yuriy@vyos.io> | 2026-05-10 17:19:31 +0300 |
|---|---|---|
| committer | Yuriy Andamasov <yuriy@vyos.io> | 2026-05-10 17:19:31 +0300 |
| commit | 3fd1787d50dda76619647dd95ea6e1d421204734 (patch) | |
| tree | 3e4f5341e2b4c5618ba1fa6b52a5cda63c4c1c29 /docs/configuration/service | |
| parent | d7e63e1923814a791dadf93453e8c090d26ca896 (diff) | |
| download | vyos-documentation-3fd1787d50dda76619647dd95ea6e1d421204734.tar.gz vyos-documentation-3fd1787d50dda76619647dd95ea6e1d421204734.zip | |
chore: remove RST swap mechanism, archive rst-*.rst under docs/_rst_legacy/
The swap mechanism (RST-as-fallback for migrated MD pages) is dormant —
docs/_rst_overrides.txt has been empty since the MyST flip trio
(#1899/#1900/#1901) landed in May 2026. The mechanism's surface area
(scripts/swap_sources.py, its 245-line test, RTD pre/post hooks,
Makefile glue, conf.py dynamic loader) is dead weight, and the
rst-*.rst shadows scattered across the source tree cause Context7's
parser to misclassify the project as RST.
Changes:
- Move 253 rst-*.rst shadow files into docs/_rst_legacy/ preserving
subdirectory structure. They remain in the repo for reference; Sphinx
excludes the folder via exclude_patterns; Context7 excludes it via
excludeFolders.
- Strip swap_sources.py invocation from docs/Makefile (swap/restore
targets, : swap deps, trap chains).
- Strip jobs: pre_build/post_build block from .readthedocs.yml.
- Strip rst-*.rst exclude entry and the _md_exclude.txt loader from
docs/conf.py; replace with a single _rst_legacy exclude.
- Delete scripts/swap_sources.py, tests/test_swap_sources.py,
docs/_rst_overrides.txt.
- Update context7.json: add docs/_rst_legacy to excludeFolders;
fix stale "Branch current tracks…" rule to "Branch rolling tracks…"
(default branch was renamed 2026-05-10).
- Update AGENTS.md: drop the "RST override mechanism" section and the
test-runner snippet for the deleted test; describe _rst_legacy as
archive only.
Verified: sphinx-build -b html with --keep-going produces identical
warning set (68 unique), identical sitemap entry count (257), identical
llms.txt entry count (22), zero rst-* URLs in any artifact.
🤖 Generated by [robots](https://vyos.io)
Diffstat (limited to 'docs/configuration/service')
23 files changed, 0 insertions, 6077 deletions
diff --git a/docs/configuration/service/rst-broadcast-relay.rst b/docs/configuration/service/rst-broadcast-relay.rst deleted file mode 100644 index f64bb208..00000000 --- a/docs/configuration/service/rst-broadcast-relay.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. _udp_broadcast_relay: - -################### -UDP Broadcast Relay -################### - -Certain vendors use broadcasts to identify their equipment within one ethernet -segment. Unfortunately if you split your network with multiple VLANs you loose -the ability of identifying your equipment. - -This is where "UDP broadcast relay" comes into play! It will forward received -broadcasts to other configured networks. - -Every UDP port which will be forward requires one unique ID. Currently we -support 99 IDs! - -Configuration -------------- - -.. cfgcmd:: set service broadcast-relay id <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. - -.. code-block:: none - - set service broadcast-relay id 1 description 'SONOS' - set service broadcast-relay id 1 interface 'eth3' - set service broadcast-relay id 1 interface 'eth4' - set service broadcast-relay id 1 interface 'eth5' - set service broadcast-relay id 1 port '1900' diff --git a/docs/configuration/service/rst-config-sync.rst b/docs/configuration/service/rst-config-sync.rst deleted file mode 100644 index a8984a0d..00000000 --- a/docs/configuration/service/rst-config-sync.rst +++ /dev/null @@ -1,160 +0,0 @@ -.. _config-sync: - -########### -Config Sync -########### - -Configuration synchronization (config sync) is a feature of VyOS that -permits synchronization of the configuration of one VyOS router to -another in a network. - -The main benefit to configuration synchronization is that it eliminates having -to manually replicate configuration changes made on the primary router to the -secondary (replica) router. - -The writing of the configuration to the secondary router is performed through -the VyOS HTTP API. The user can specify which portion(s) of the configuration will -be synchronized and the mode to use - whether to replace or add. - -To prevent issues with divergent configurations between the pair of routers, -synchronization is strictly unidirectional from primary to replica. Both -routers should be online and run the same version of VyOS. - -Configuration -------------- - -.. cfgcmd:: set service config-sync secondary - <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. - -.. code-block:: 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:** - - .. list-table:: - :widths: 30 70 - :header-rows: 0 - - * - ``commands`` (optional) - - Show output as a list of configuration commands instead of raw diff. - * - ``running|candidate|saved`` (optional, mutually exclusive) - - Select which configuration to compare: - ``running`` (current active configuration, default), - ``candidate`` (uncommitted changes), or - ``saved`` (last saved configuration). Only one of these may be - specified at a time; if omitted, ``running`` is used. - - **Examples:** - - .. code-block:: none - - # compare full running configuration with a secondary node - show configuration secondary sync - - # compare only interface configuration - show configuration secondary sync running interfaces dummy - - # compare candidate configuration and display as a list of commands - show configuration secondary sync commands candidate - -Without a built-in cross-node diff, operators may unintentionally push -changes that conflict with the remote configuration (e.g., mismatched -interfaces, firewall policies, or protocol settings). - -Example -------- -* Synchronize the time-zone and OSPF configuration from Router A to Router B -* The address of Router B is 10.0.20.112 and the port used is 8443 - -Configure the HTTP API service on Router B - -.. code-block:: none - - set service https listen-address '10.0.20.112' - set service https port '8443' - set service https api keys id KID key 'foo' - set service https api rest - -Configure the config-sync service on Router A - -.. code-block:: none - - set service config-sync mode 'load' - set service config-sync secondary address '10.0.20.112' - set service config-sync secondary port '8443' - set service config-sync secondary key 'foo' - set service config-sync section protocols 'ospf' - set service config-sync section system 'time-zone' - -Make config-sync relevant changes to Router A's configuration - -.. code-block:: none - - vyos@vyos-A# set system time-zone 'America/Los_Angeles' - vyos@vyos-A# commit - INFO:vyos_config_sync:Config synchronization: Mode=load, - Secondary=10.0.20.112 - vyos@vyos-A# save - - vyos@vyos-A# set protocols ospf area 0 network '10.0.48.0/30' - vyos@vyos-A# commit - INFO:vyos_config_sync:Config synchronization: Mode=load, - Secondary=10.0.20.112 - yos@vyos-A# save - -Verify configuration changes have been replicated to Router B - -.. code-block:: none - - vyos@vyos-B:~$ show configuration commands | match time-zone - set system time-zone 'America/Los_Angeles' - - vyos@vyos-B:~$ show configuration commands | match ospf - set protocols ospf area 0 network '10.0.48.0/30' - -Known issues ------------- -Configuration resynchronization. With the current implementation of `service -config-sync`, the secondary node must be online. diff --git a/docs/configuration/service/rst-conntrack-sync.rst b/docs/configuration/service/rst-conntrack-sync.rst deleted file mode 100644 index 2527407e..00000000 --- a/docs/configuration/service/rst-conntrack-sync.rst +++ /dev/null @@ -1,302 +0,0 @@ -.. _conntrack-sync: - -############## -Conntrack Sync -############## - -One of the important features built on top of the Netfilter framework is -connection tracking. Connection tracking allows the kernel to keep track of all -logical network connections or sessions, and thereby relate all of the packets -which may make up that connection. NAT relies on this information to translate -all related packets in the same way, and iptables can use this information to -act as a stateful firewall. - -The connection state however is completely independent of any upper-level -state, such as TCP's or SCTP's state. Part of the reason for this is that when -merely forwarding packets, i.e. no local delivery, the TCP engine may not -necessarily be invoked at all. Even connectionless-mode transmissions such as -UDP, IPsec (AH/ESP), GRE and other tunneling protocols have, at least, a pseudo -connection state. The heuristic for such protocols is often based upon a preset -timeout value for inactivity, after whose expiration a Netfilter connection is -dropped. - -Each Netfilter connection is uniquely identified by a (layer-3 protocol, source -address, destination address, layer-4 protocol, layer-4 key) tuple. The layer-4 -key depends on the transport protocol; for TCP/UDP it is the port numbers, for -tunnels it can be their tunnel ID, but otherwise is just zero, as if it were -not part of the tuple. To be able to inspect the TCP port in all cases, packets -will be mandatorily defragmented. - -It is possible to use either Multicast or Unicast to sync conntrack traffic. -Most examples below show Multicast, but unicast can be specified by using the -"peer" keywork after the specified interface, as in the following example: - -:cfgcmd:`set service conntrack-sync interface eth0 peer 192.168.0.250` - -************* -Configuration -************* - -.. cfgcmd:: set service conntrack-sync accept-protocol - - Accept only certain protocols: You may want to replicate the state of flows - depending on their layer 4 protocol. - - Protocols are: tcp, sctp, dccp, udp, icmp and ipv6-icmp. - -.. cfgcmd:: set service conntrack-sync event-listen-queue-size <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. - -.. stop_vyoslinter - -.. 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 - -.. start_vyoslinter - -.. 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.* - :scale: 60 % - :alt: Conntrack Sync Example - -Now configure conntrack-sync service on ``router1`` **and** ``router2`` - -.. code-block:: none - - set high-availability vrrp group internal virtual-address ... etc ... - set high-availability vrrp sync-group syncgrp member 'internal' - set service conntrack-sync accept-protocol 'tcp' - set service conntrack-sync accept-protocol 'udp' - set service conntrack-sync accept-protocol 'icmp' - set service conntrack-sync failover-mechanism vrrp sync-group 'syncgrp' - set service conntrack-sync interface 'eth0' - set service conntrack-sync mcast-group '225.0.0.50' - -On the active router, you should have information in the internal-cache of -conntrack-sync. The same current active connections number should be shown in -the external-cache of the standby router - -On active router run: - -.. code-block:: none - - $ show conntrack-sync statistics - - Main Table Statistics: - - cache internal: - current active connections: 10 - connections created: 8517 failed: 0 - connections updated: 127 failed: 0 - connections destroyed: 8507 failed: 0 - - cache external: - current active connections: 0 - connections created: 0 failed: 0 - connections updated: 0 failed: 0 - connections destroyed: 0 failed: 0 - - traffic processed: - 0 Bytes 0 Pckts - - multicast traffic (active device=eth0): - 868780 Bytes sent 224136 Bytes recv - 20595 Pckts sent 14034 Pckts recv - 0 Error send 0 Error recv - - message tracking: - 0 Malformed msgs 0 Lost msgs - -On standby router run: - -.. code-block:: none - - - $ show conntrack-sync statistics - - Main Table Statistics: - - cache internal: - current active connections: 0 - connections created: 0 failed: 0 - connections updated: 0 failed: 0 - connections destroyed: 0 failed: 0 - - cache external: - current active connections: 10 - connections created: 888 failed: 0 - connections updated: 134 failed: 0 - connections destroyed: 878 failed: 0 - - traffic processed: - 0 Bytes 0 Pckts - - multicast traffic (active device=eth0): - 234184 Bytes sent 907504 Bytes recv - 14663 Pckts sent 21495 Pckts recv - 0 Error send 0 Error recv - - message tracking: - 0 Malformed msgs 0 Lost msgs - diff --git a/docs/configuration/service/rst-console-server.rst b/docs/configuration/service/rst-console-server.rst deleted file mode 100644 index c9ea7f77..00000000 --- a/docs/configuration/service/rst-console-server.rst +++ /dev/null @@ -1,120 +0,0 @@ -.. _console_server: - -############## -Console Server -############## - -Starting of with VyOS 1.3 (equuleus) we added support for running VyOS as an -Out-of-Band Management device which provides remote access by means of SSH to -directly attached serial interfaces. - -Serial interfaces can be any interface which is directly connected to the CPU -or chipset (mostly known as a ttyS interface in Linux) or any other USB to -serial converter (Prolific PL2303 or FTDI FT232/FT4232 based chips). - -If you happened to use a Cisco NM-16A - Sixteen Port Async Network Module or -NM-32A - Thirty-two Port Async Network Module - this is your VyOS replacement. - -For USB port information please refor to: :ref:`hardware_usb`. - -Configuration -============= - -Between computers, the most common configuration used was "8N1": eight bit -characters, with one start bit, one stop bit, and no parity bit. Thus 10 Baud -times are used to send a single character, and so dividing the signalling -bit-rate by ten results in the overall transmission speed in characters per -second. This is also the default setting if none of those options are defined. - -.. cfgcmd:: set service console-server device <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/rst-dhcp-relay.rst b/docs/configuration/service/rst-dhcp-relay.rst deleted file mode 100644 index 6a1b02f2..00000000 --- a/docs/configuration/service/rst-dhcp-relay.rst +++ /dev/null @@ -1,205 +0,0 @@ -.. _dhcp-relay: - -########## -DHCP Relay -########## - -If you want your router to forward DHCP requests to an external DHCP server -you can configure the system to act as a DHCP relay agent. The DHCP relay -agent works with IPv4 and IPv6 addresses. - -All interfaces used for the DHCP relay must be configured. This includes the -uplink to the DHCP server. - -********** -IPv4 relay -********** - -Configuration -============= - -.. cfgcmd:: set service dhcp-relay interface <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.* - :scale: 80 % - :alt: DHCP relay example - - DHCP relay example - -The generated configuration will look like: - -.. code-block:: none - - show service dhcp-relay - listen-interface eth1 - upstream-interface eth2 - server 10.0.1.4 - relay-options { - relay-agents-packets discard - } - -Also, for backwards compatibility this configuration, which uses generic -interface definition, is still valid: - -.. code-block:: none - - show service dhcp-relay - interface eth1 - interface eth2 - server 10.0.1.4 - relay-options { - relay-agents-packets discard - } - -Operation -========= - -.. opcmd:: restart dhcp relay-agent - - Restart DHCP relay service - -********** -IPv6 relay -********** - -.. _dhcp-relay:ipv6_configuration: - -Configuration -============= - -.. cfgcmd:: set service dhcpv6-relay listen-interface <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.* - :scale: 80 % - :alt: DHCPv6 relay example - - DHCPv6 relay example - -The generated configuration will look like: - -.. code-block:: none - - commit - show service dhcpv6-relay - listen-interface eth1 { - } - upstream-interface eth2 { - address 2001:db8::4 - } - -.. _dhcp-relay:ipv6_op_cmd: - -Operation -========= - -.. opcmd:: restart dhcpv6 relay-agent - - Restart DHCPv6 relay agent immediately. diff --git a/docs/configuration/service/rst-dhcp-server.rst b/docs/configuration/service/rst-dhcp-server.rst deleted file mode 100644 index 09f40b37..00000000 --- a/docs/configuration/service/rst-dhcp-server.rst +++ /dev/null @@ -1,1087 +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`` - -.. code-block:: 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. - -.. code-block:: 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: - -.. code-block:: 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: - -.. code-block:: 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: - -.. code-block:: 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: - -.. code-block:: 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: - -.. code-block:: 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`` - -.. code-block:: 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: - -.. code-block:: 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. - -.. code-block:: 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. - -.. code-block:: 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** - -.. code-block:: 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** - -.. code-block:: 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: - -.. code-block:: 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: - -.. code-block:: 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): - -.. code-block:: 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. - -.. code-block:: 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``. - -.. code-block:: 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 - -.. code-block:: 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: - -.. code-block:: 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. - -.. code-block:: 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: - -.. stop_vyoslinter (00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff false positive) - -.. code-block:: 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 - } - } - -.. start_vyoslinter - -.. _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: - -.. code-block:: 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) diff --git a/docs/configuration/service/rst-dns.rst b/docs/configuration/service/rst-dns.rst deleted file mode 100644 index 365e7885..00000000 --- a/docs/configuration/service/rst-dns.rst +++ /dev/null @@ -1,511 +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. - -.. code-block:: 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 - -.. code-block:: 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: - -.. code-block:: 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: - -.. code-block:: 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: -^^^^^^^^^^^^^^^^^^ - -.. code-block:: 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/rst-eventhandler.rst b/docs/configuration/service/rst-eventhandler.rst deleted file mode 100644 index 9f4ebb04..00000000 --- a/docs/configuration/service/rst-eventhandler.rst +++ /dev/null @@ -1,159 +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`_ - - `2. Add regex to the script`_ - - `3. Add a full path to the script`_ - - `4. 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 -=========================================== - -.. stop_vyoslinter - - .. cfgcmd:: set service event-handler event <event-handler name> filter pattern <regex> - -.. start_vyoslinter - - 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 -================================ - -.. stop_vyoslinter - - .. cfgcmd:: set service event-handler event <event-handler name> script path <path to script> - -.. start_vyoslinter - - This is a mandatory command. Sets the full path to the script. - The script file must be executable. - - - -4. Add optional parameters -========================== - -.. stop_vyoslinter - - .. cfgcmd:: set service event-handler event <event-handler name> filter syslog-identifier <syslogid name> - -.. start_vyoslinter - - This is an optional command. Filters log messages by syslog-identifier. - -.. stop_vyoslinter - - .. cfgcmd:: set service event-handler event <event-handler name> script environment <env name> value <env value> - -.. start_vyoslinter - - 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. - -.. stop_vyoslinter - - .. cfgcmd:: set service event-handler event <event-handler name> script arguments <arguments> - -.. start_vyoslinter - - 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. - -.. stop_vyoslinter - - .. code-block:: 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 - - .. code-block:: 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) - -.. start_vyoslinter diff --git a/docs/configuration/service/rst-https.rst b/docs/configuration/service/rst-https.rst deleted file mode 100644 index e72e8e8b..00000000 --- a/docs/configuration/service/rst-https.rst +++ /dev/null @@ -1,124 +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. - -.. code-block:: 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/rst-index.rst b/docs/configuration/service/rst-index.rst deleted file mode 100644 index fb6f8413..00000000 --- a/docs/configuration/service/rst-index.rst +++ /dev/null @@ -1,31 +0,0 @@ -####### -Service -####### - - -.. toctree:: - :maxdepth: 1 - :includehidden: - - 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/rst-ipoe-server.rst b/docs/configuration/service/rst-ipoe-server.rst deleted file mode 100644 index 5d7acd5a..00000000 --- a/docs/configuration/service/rst-ipoe-server.rst +++ /dev/null @@ -1,450 +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. - -.. code-block:: 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. - -.. code-block:: 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. - -.. code-block:: 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: - -.. code-block:: 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. - -.. code-block:: 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. - -.. code-block:: 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 - -.. code-block:: 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 -************** - -.. code-block:: 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>] - -.. include:: /_include/common-references.txt -.. _dictionary: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.rfc6911 -.. _`ACCEL-PPP attribute`: https://github.com/accel-ppp/accel-ppp/blob/master/accel-pppd/radius/dict/dictionary.accel diff --git a/docs/configuration/service/rst-lldp.rst b/docs/configuration/service/rst-lldp.rst deleted file mode 100644 index 8aee6183..00000000 --- a/docs/configuration/service/rst-lldp.rst +++ /dev/null @@ -1,148 +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. diff --git a/docs/configuration/service/rst-mdns.rst b/docs/configuration/service/rst-mdns.rst deleted file mode 100644 index 8a26722e..00000000 --- a/docs/configuration/service/rst-mdns.rst +++ /dev/null @@ -1,124 +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. - -.. code-block:: 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: - -.. code-block:: 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: - -.. code-block:: 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: - -.. code-block:: none - - set service mdns repeater browse-domain 'openthread.thread.home.arpa' - -.. _`Multicast DNS`: https://en.wikipedia.org/wiki/Multicast_DNS - -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. diff --git a/docs/configuration/service/rst-monitoring.rst b/docs/configuration/service/rst-monitoring.rst deleted file mode 100644 index 8faf0eb8..00000000 --- a/docs/configuration/service/rst-monitoring.rst +++ /dev/null @@ -1,289 +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: - -.. code-block:: none - - set service monitoring telegraf prometheus-client - -.. code-block:: 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: - -.. code-block:: 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: - -.. code-block:: 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. - -.. _azure-data-explorer: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/azure_data_explorer -.. _prometheus-client: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/prometheus_client -.. _influxdb: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/influxdb_v2 -.. _splunk: https://www.splunk.com/en_us/blog/it/splunk-metrics-via-telegraf.html -.. _loki: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/loki - - -********** -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: - -.. code-block:: 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: - -.. code-block:: 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 - -.. _node_exporter: https://github.com/prometheus/node_exporter -.. _frr_exporter: https://github.com/tynany/frr_exporter -.. _blackbox_exporter: https://github.com/prometheus/blackbox_exporter diff --git a/docs/configuration/service/rst-ntp.rst b/docs/configuration/service/rst-ntp.rst deleted file mode 100644 index f4ccb4b1..00000000 --- a/docs/configuration/service/rst-ntp.rst +++ /dev/null @@ -1,197 +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 - -.. _draft-ntp-interleaved-modes: https://datatracker.ietf.org/doc/draft-ietf-ntp-interleaved-modes/07/ - -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. - diff --git a/docs/configuration/service/rst-pppoe-server.rst b/docs/configuration/service/rst-pppoe-server.rst deleted file mode 100644 index f763536a..00000000 --- a/docs/configuration/service/rst-pppoe-server.rst +++ /dev/null @@ -1,685 +0,0 @@ -:lastproofread: 2022-09-17 - -.. _pppoe-server: - -############ -PPPoE Server -############ - -VyOS utilizes `accel-ppp`_ 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 -************************ - -.. code-block:: 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. - -.. code-block:: 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: - -.. code-block:: 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. - -.. code-block:: 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>`. - - -.. code-block:: 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``. - -.. code-block:: 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. - -.. code-block:: 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. - -.. code-block:: 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. - - -.. code-block:: 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. - -.. code-block:: 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. - -.. code-block:: 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. - -.. code-block:: 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 - -.. include:: /_include/common-references.txt -.. _dictionary: https://github.com/accel-ppp/accel-ppp/blob/master/ - accel-pppd/radius/dict/dictionary.rfc6911 -.. _`ACCEL-PPP attribute`: https://github.com/accel-ppp/accel-ppp/ - blob/master/accel-pppd/radius/dict/dictionary.accel diff --git a/docs/configuration/service/rst-router-advert.rst b/docs/configuration/service/rst-router-advert.rst deleted file mode 100644 index 80f5ae30..00000000 --- a/docs/configuration/service/rst-router-advert.rst +++ /dev/null @@ -1,130 +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> ... - -.. stop_vyoslinter - -.. 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" - -.. start_vyoslinter - - -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. - -.. stop_vyoslinter - -.. 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)" - -.. start_vyoslinter - -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`` - -.. stop_vyoslinter - -.. csv-table:: - :header: "VyOS Field", "Description" - :widths: 10,30 - - "valid-lifetime","Time in seconds that the prefix will remain valid (default: 65528 seconds)" - -.. start_vyoslinter - -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`` - -.. code-block:: 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/rst-salt-minion.rst b/docs/configuration/service/rst-salt-minion.rst deleted file mode 100644 index 8638246b..00000000 --- a/docs/configuration/service/rst-salt-minion.rst +++ /dev/null @@ -1,53 +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/
\ No newline at end of file diff --git a/docs/configuration/service/rst-snmp.rst b/docs/configuration/service/rst-snmp.rst deleted file mode 100644 index 6dc13240..00000000 --- a/docs/configuration/service/rst-snmp.rst +++ /dev/null @@ -1,276 +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.* - :scale: 20 % - :alt: Principle of SNMP Communication - - 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 -^^^^^^^ - -.. code-block:: 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 - -.. code-block:: 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: - -.. code-block:: 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 - -.. code-block:: 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. - - -.. code-block:: none - - set service snmp script-extensions extension-name my-extension script your_script.sh - commit - -.. stop_vyoslinter - -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. - -.. start_vyoslinter - -.. code-block:: 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. - -.. stop_vyoslinter - -Create a file named ``VyOS-1.3.6.1.4.1.44641.ConfigMgmt-Commands`` using the -following content: - - -.. code-block:: 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 - -.. start_vyoslinter diff --git a/docs/configuration/service/rst-ssh.rst b/docs/configuration/service/rst-ssh.rst deleted file mode 100644 index 11f58201..00000000 --- a/docs/configuration/service/rst-ssh.rst +++ /dev/null @@ -1,334 +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" - - 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. diff --git a/docs/configuration/service/rst-suricata.rst b/docs/configuration/service/rst-suricata.rst deleted file mode 100644 index b72bc52a..00000000 --- a/docs/configuration/service/rst-suricata.rst +++ /dev/null @@ -1,101 +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: - -.. code-block:: 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. - - - -
\ No newline at end of file diff --git a/docs/configuration/service/rst-tftp-server.rst b/docs/configuration/service/rst-tftp-server.rst deleted file mode 100644 index 84acf3d4..00000000 --- a/docs/configuration/service/rst-tftp-server.rst +++ /dev/null @@ -1,80 +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> - -.. stop_vyoslinter - -Additional option to run TFTP server in the :abbr:`VRF (Virtual Routing and Forwarding)` context - -.. start_vyoslinter - -.. 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: - -.. code-block:: none - - vyos@vyos# show service - tftp-server { - directory /config/tftpboot - listen-address 2001:db8::1 - listen-address 192.0.2.1 - } - -Verification ------------- - -Client: - -.. code-block:: none - - vyos@RTR2:~$ tftp -p -l /config/config.boot -r backup 192.0.2.1 - backup1 100% |******************************| 723 0:00:00 ETA - -Server: - -.. code-block:: 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/rst-webproxy.rst b/docs/configuration/service/rst-webproxy.rst deleted file mode 100644 index a6c5ff0a..00000000 --- a/docs/configuration/service/rst-webproxy.rst +++ /dev/null @@ -1,445 +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 - - :code:`set service webproxy url-filtering squidguard auto-update - update-hour 23` - -* To configure blocking add the following to the configuration - - :code:`set service webproxy url-filtering squidguard block-category ads` - - :code:`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: - - :code:`set service webproxy whitelist destination-address 198.51.100.33` - - :code:`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: - - :code:`set service webproxy whitelist source-address 192.168.1.2` - - :code:`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 -******** - -.. code-block:: 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/ |