diff options
Diffstat (limited to 'docs/configuration/service')
21 files changed, 3034 insertions, 0 deletions
diff --git a/docs/configuration/service/broadcast-relay.rst b/docs/configuration/service/broadcast-relay.rst new file mode 100644 index 00000000..df48bfd6 --- /dev/null +++ b/docs/configuration/service/broadcast-relay.rst @@ -0,0 +1,61 @@ +.. _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/appliactions. + +.. 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> port <port> + + The UDP port number used by your apllication. 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/conntrack-sync.rst b/docs/configuration/service/conntrack-sync.rst new file mode 100644 index 00000000..55cd088e --- /dev/null +++ b/docs/configuration/service/conntrack-sync.rst @@ -0,0 +1,200 @@ +.. include:: /_include/need_improvement.txt + +Conntrack +--------- + +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 specificed interface, as in the following example: + +set service conntrack-sync interface eth0 peer 192.168.0.250 + +Configuration +^^^^^^^^^^^^^ + +.. code-block:: none + + # Protocols only for which local conntrack entries will be synced (tcp, udp, icmp, sctp) + set service conntrack-sync accept-protocol + + # Queue size for listening to local conntrack events (in MB) + set service conntrack-sync event-listen-queue-size <int> + + # Protocol for which expect entries need to be synchronized. (all, ftp, h323, nfs, sip, sqlnet) + set service conntrack-sync expect-sync + + # Failover mechanism to use for conntrack-sync [REQUIRED] + set service conntrack-sync failover-mechanism + + set service conntrack-sync cluster group <string> + set service conntrack-sync vrrp sync-group <1-255> + + # IP addresses for which local conntrack entries will not be synced + set service conntrack-sync ignore-address ipv4 <x.x.x.x> + + # Interface to use for syncing conntrack entries [REQUIRED] + set service conntrack-sync interface <ifname> + + # Multicast group to use for syncing conntrack entries + set service conntrack-sync mcast-group <x.x.x.x> + + # Peer to send Unicast UDP conntrack sync entires to, if not using Multicast above + set service conntrack-sync interface <ifname> peer <remote IP of peer> + + # Queue size for syncing conntrack entries (in MB) + set service conntrack-sync sync-queue-size <size> + +Example +^^^^^^^ +The next example is a simple configuration of conntrack-sync. + + +.. figure:: /_static/images/service_conntrack_sync-schema.png + :scale: 60 % + :alt: Conntrack Sync Example + + Conntrack Sync Example + +First of all, make sure conntrack is enabled by running + +.. code-block:: none + + show conntrack table ipv4 + +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. + +.. code-block:: none + + set firewall state-policy established action accept + +You now should have a conntrack table + +.. code-block:: none + + $ 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 + +Now configure conntrack-sync service on ``router1`` **and** ``router2`` + +.. code-block:: none + + set service conntrack-sync accept-protocol 'tcp,udp,icmp' + set service conntrack-sync event-listen-queue-size '8' + set service conntrack-sync failover-mechanism cluster group 'GROUP' + set service conntrack-sync interface 'eth0' + set service conntrack-sync mcast-group '225.0.0.50' + set service conntrack-sync sync-queue-size '8' + +If you are using VRRP, you need to define a VRRP sync-group, and use ``vrrp sync-group`` instead of ``cluster group``. + +.. code-block:: none + + set high-availablilty vrrp group internal virtual-address ... etc ... + set high-availability vrrp sync-group syncgrp member 'internal' + set service conntrack-sync failover-mechanism vrrp sync-group 'syncgrp' + + +On the active router, you should have information in the internal-cache of +conntrack-sync. The same current active connections number should be shown in +the external-cache of the standby router + +On active router run: + +.. code-block:: none + + $ show conntrack-sync statistics + + Main Table Statistics: + + cache internal: + current active connections: 10 + connections created: 8517 failed: 0 + connections updated: 127 failed: 0 + connections destroyed: 8507 failed: 0 + + cache external: + current active connections: 0 + connections created: 0 failed: 0 + connections updated: 0 failed: 0 + connections destroyed: 0 failed: 0 + + traffic processed: + 0 Bytes 0 Pckts + + multicast traffic (active device=eth0): + 868780 Bytes sent 224136 Bytes recv + 20595 Pckts sent 14034 Pckts recv + 0 Error send 0 Error recv + + message tracking: + 0 Malformed msgs 0 Lost msgs + + + +On standby router run: + + +.. code-block:: none + + + $ show conntrack-sync statistics + + Main Table Statistics: + + cache internal: + current active connections: 0 + connections created: 0 failed: 0 + connections updated: 0 failed: 0 + connections destroyed: 0 failed: 0 + + cache external: + current active connections: 10 + connections created: 888 failed: 0 + connections updated: 134 failed: 0 + connections destroyed: 878 failed: 0 + + traffic processed: + 0 Bytes 0 Pckts + + multicast traffic (active device=eth0): + 234184 Bytes sent 907504 Bytes recv + 14663 Pckts sent 21495 Pckts recv + 0 Error send 0 Error recv + + message tracking: + 0 Malformed msgs 0 Lost msgs + diff --git a/docs/configuration/service/console-server.rst b/docs/configuration/service/console-server.rst new file mode 100644 index 00000000..cf222544 --- /dev/null +++ b/docs/configuration/service/console-server.rst @@ -0,0 +1,107 @@ +.. _console_server: + +############## +Console Server +############## + +Starting of with VyOS 1.3 (equuleus) we added support for running VyOS as an +Out-of-Band Management device which provides remote access by means of SSH to +directly attached serial interfaces. + +Serial interfaces can be any interface which is directly connected to the CPU +or chipset (mostly known as a ttyS interface in Linux) or any other USB to +serial converter (Prolific PL2303 or FTDI FT232/FT4232 based chips). + +If you happened to use a Cisco NM-16A - Sixteen Port Async Network Module or +NM-32A - Thirty-two Port Async Network Module - this is your VyOS replacement. + +For USB port information please refor to: :ref:`hardware_usb`. + +Configuration +============= + +Between computers, the most common configuration used was "8N1": eight bit +characters, with one start bit, one stop bit, and no parity bit. Thus 10 Baud +times are used to send a single character, and so dividing the signalling +bit-rate by ten results in the overall transmission speed in characters per +second. This is also the default setting if none of those options are defined. + +.. cfgcmd:: set service console-server <device> data-bits [7 | 8] + + Configure either seven or eight data bits. This defaults to eight data + bits if left unconfigured. + +.. cfgcmd:: set service console-server <device> description <string> + + A user friendly description identifying the connected peripheral. + +.. cfgcmd:: set service console-server <device> parity [even | odd | none] + + Set the parity option for the console. If unset this will default to none. + +.. cfgcmd:: set service console-server <device> stop-bits [1 | 2] + + Configure either one or two stop bits. This defaults to one stop bits if + left unconfigured. + +.. cfgcmd:: set service console-server <device> speed [ 300 | 1200 | 2400 | 4800 | 9600 | 19200 | 38400 | 57600 | 115200 ] + + .. note:: USB to serial converters will handle most of their work in software + so you should be carefull with the selected baudrate as some times they + can't cope with the expected speed. + +Remote Access +------------- + +Each individual configured console-server device can be directly exposed to +the outside world. A user can directly connect via SSH to the configured +port. + +.. cfgcmd:: set service console-server <device> ssh port <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-server <device> + + Locally connect to serial port identified by `<device>`. + + .. code-block:: none + + vyos@vyos-r1:~$ connect console-server 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 .`` diff --git a/docs/configuration/service/dhcp-relay.rst b/docs/configuration/service/dhcp-relay.rst new file mode 100644 index 00000000..445519b3 --- /dev/null +++ b/docs/configuration/service/dhcp-relay.rst @@ -0,0 +1,2 @@ +dhcp-relay +##########
\ No newline at end of file diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst new file mode 100644 index 00000000..6cb0bc83 --- /dev/null +++ b/docs/configuration/service/dhcp-server.rst @@ -0,0 +1,747 @@ +.. _dhcp: + +.. _dhcp-server: + +########### +DHCP Server +########### + +VyOS uses ISC 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 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> 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> dns-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> 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> 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). + +Failover +-------- + +VyOS provides support for DHCP failover. DHCP failover must be configured +explicitly by the following statements. + +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> failover local-address <address> + + Local IP `<address>` used when communicating to the failover peer. + +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> failover peer-address <address> + + Remote peer IP `<address>` of the second DHCP server in this failover cluster. + +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> failover name <name> + + A generic `<name>` referencing this sync service. + + .. note:: `<name>` must be identical on both sides! + +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> failover 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 failover 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 failover peers whose communications traverse insecure networks, then we + recommend that you consider the use of VPN tunneling between them to ensure + that the failover 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 <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> 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. + +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 + * - dns-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 + * - 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. + +Raw Parameters +============== + +Raw parameters can be passed to shared-network-name, subnet and static-mapping: + +.. code-block:: none + + set service dhcp-server shared-network-name <name> shared-network-parameters + <text> Additional shared-network parameters for DHCP server. + set service dhcp-server shared-network-name <name> subnet <subnet> subnet-parameters + <text> Additional subnet parameters for DHCP server. + set service dhcp-server shared-network-name <name> subnet <subnet> static-mapping <description> static-mapping-parameters + <text> Additional static-mapping parameters for DHCP server. + Will be placed inside the "host" block of the mapping. + +These parameters are passed as-is to isc-dhcp's dhcpd.conf under the +configuration node they are defined in. They are not validated so an error in +the raw parameters won't be caught by vyos's scripts and will cause dhcpd to +fail to start. Always verify that the parameters are correct before committing +the configuration. Refer to isc-dhcp's dhcpd.conf manual for more information: +https://kb.isc.org/docs/isc-dhcp-44-manual-pages-dhcpdconf + +Quotes can be used inside parameter values by replacing all quote characters +with the string ``"``. They will be replaced with literal quote characters +when generating dhcpd.conf. + +Example +======= + +Please see the :ref:`dhcp-dns-quick-start` configuration. + +Failover +-------- + +Configuration of a DHCP failover pair + +* Setup DHCP failover for network 192.0.2.0/24 +* Default gateway and DNS server is at `192.0.2.254` +* The primary DHCP server uses address `192.168.189.252` +* The secondary DHCP server 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 default-router '192.0.2.254' + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 dns-server '192.0.2.254' + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 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' + + +**Primary** + +.. code-block:: none + + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover local-address '192.168.189.252' + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover name 'NET-VYOS' + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover peer-address '192.168.189.253' + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover status 'primary' + +**Secondary** + +.. code-block:: none + + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover local-address '192.168.189.253' + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover name 'NET-VYOS' + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover peer-address '192.168.189.252' + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover status 'primary' + + +Raw Parameters +-------------- + +* Override static-mapping's dns-server with a custom one that will be sent only + to this host. +* An option that takes a quoted string is set by replacing all quote characters + with the string ``"`` inside the static-mapping-parameters value. + The resulting line in dhcpd.conf will be + ``option pxelinux.configfile "pxelinux.cfg/01-00-15-17-44-2d-aa";``. + + +.. code-block:: none + + set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option domain-name-servers 192.0.2.11, 192.0.2.12;" + set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option pxelinux.configfile "pxelinux.cfg/01-00-15-17-44-2d-aa";" + + +Operation Mode +============== + +.. 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 Hardware address State Lease start Lease expiration Remaining Pool Hostname + -------------- ------------------ ------- ------------------- ------------------- ---------- ----------- --------- + 192.0.2.104 aa:bb:cc:dd:ee:ff active 2019/12/05 14:24:23 2019/12/06 02:24:23 6:05:35 dhcpexample test1 + 192.0.2.115 ab:ac:ad:ae:af:bf active 2019/12/05 18:02:37 2019/12/06 06:02:37 9:43:49 dhcpexample test2 + +.. hint:: Static mappings aren't shown. To show all states, use + ``show dhcp server leases state all``. + +.. opcmd:: show dhcp server leases pool <pool> + + Show only leases in the specified pool. + +.. 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. + +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 <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> 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> 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> nis-server <address> + + Specify a NIS server address for DHCPv6 clients. + +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> nisplus-server <address> + + Specify a NIS+ server address for DHCPv6 clients. + +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> 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> 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 start <address> prefix-length <length> + + Hand out prefixes of size `<length>` to clients in subnet `<prefix>` when + they request for prefix delegation. + +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> prefix-delegation start <address> stop <address> + + Delegate prefixes from the range indicated by the start and stop qualifier. + +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 'NET1' subnet 2001:db8::/64 address-range start 2001:db8::100 stop 2001:db8::199 + set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 name-server 2001:db8::ffff + +The configuration will look as follows: + +.. code-block:: none + + show service dhcpv6-server + shared-network-name NET1 { + subnet 2001:db8::/64 { + address-range { + start 2001:db8::100 { + stop 2001:db8::199 + } + } + name-server 2001:db8::ffff + } + } + +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 +* 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 identifier 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff + +The configuration will look as follows: + +.. code-block:: none + + show service dhcp-server shared-network-name NET1 + shared-network-name NET1 { + subnet 2001:db8::/64 { + name-server 2001:db8:111::111 + address-range { + start 2001:db8::100 { + stop 2001:db8::199 { + } + } + static-mapping client1 { + ipv6-address 2001:db8::101 + identifier 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff + } + } + } + +Operation Mode +============== + +.. opcmd:: restart dhcpv6 server + + To restart the DHCPv6 server + +.. opcmd:: show dhcpv6 server status + + To show the current status of the DHCPv6 server. + +.. opcmd:: show dhcpv6 server leases + + Show statuses of all assigned leases: + +.. code-block:: none + + vyos@vyos:~$ show dhcpv6 server leases + IPv6 address State Last communication Lease expiration Remaining Type Pool IAID_DUID + ------------- ------- -------------------- ------------------- ----------- ------------- ----- -------------------------------------------- + 2001:db8::101 active 2019/12/05 19:40:10 2019/12/06 07:40:10 11:45:21 non-temporary 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 non-temporary NET1 87:65:43:21:00:01:00:01:11:22:33:44:fa:fb:fc:fd:fe: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) + +########## +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. + +********** +IPv4 relay +********** + +Configuration +============= + +.. cfgcmd:: set service dhcp-relay interface <interface> + + Enable the DHCP relay service on the given interface. + +.. 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. + +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-packet <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. +* Router receives DHCP client requests on ``eth1`` and relays them to the server at 10.0.1.4. + +.. figure:: /_static/images/service_dhcp-relay01.png + :scale: 80 % + :alt: DHCP relay example + + DHCP relay example + +The generated configuration will look like: + +.. code-block:: none + + show service dhcp-relay + interface eth1 + server 10.0.1.4 + relay-options { + relay-agents-packets discard + } + +Operation +========= + +.. opcmd:: restart dhcp relay-agent + + Restart DHCP relay service + +********** +IPv6 relay +********** + +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. + +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. + +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.png + :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 + } + +Operation +========= + +.. opcmd:: restart dhcpv6 relay-agent + + Restart DHCPv6 relay agent immediately. diff --git a/docs/configuration/service/dhcpv6-relay.rst b/docs/configuration/service/dhcpv6-relay.rst new file mode 100644 index 00000000..2d105fdf --- /dev/null +++ b/docs/configuration/service/dhcpv6-relay.rst @@ -0,0 +1,2 @@ +dhcpv6-relay +############
\ No newline at end of file diff --git a/docs/configuration/service/dhcpv6-server.rst b/docs/configuration/service/dhcpv6-server.rst new file mode 100644 index 00000000..64e523a0 --- /dev/null +++ b/docs/configuration/service/dhcpv6-server.rst @@ -0,0 +1,2 @@ +dhcpv6-server +#############
\ No newline at end of file diff --git a/docs/configuration/service/dns.rst b/docs/configuration/service/dns.rst new file mode 100644 index 00000000..f332c55c --- /dev/null +++ b/docs/configuration/service/dns.rst @@ -0,0 +1,313 @@ +.. _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 to be 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 name-server <address> + + Send all DNS queries to the IPv4/IPv6 DNS server specified under `<address>`. + You can configure multiple nameservers here. + +.. cfgcmd:: set service dns forwarding domain <domain-name> server <address> + + Forward received queries for a particular domain (specified via `domain-name`) + to a given name-server. 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 allow-from <network> + + Given the fact that open DNS recursors could be used on DDOS amplification + attacts, 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 on general 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 behaviour 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 famous 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`` commandline 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 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 max-cache-entries + + Maximum number of DNS cache entries. 1 million per CPU core will generally + suffice for most installations. + +.. cfgcmd:: set service dns forwarding negative-ttl + + 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 listen-address + + The local IPv4 or IPv6 addresses to bind the DNS forwarder to. The forwarder will listen on this address for + incoming connections. + +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 + +.. code-block:: none + + set service dns forwarding domain example.com server 192.0.2.254 + set service dns forwarding domain example.com 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 2001:db8::1:ffff + set service dns forwarding name-server 2001:db8::2:ffff + 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 + +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 similar +website. This method uses HTTP requests to transmit the new IP address. You +can configure both in VyOS. + +Configuration +============= + +:rfc:`2136` Based +----------------- + +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> + + Create new :rfc:`2136` 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 interface <interface> rfc2136 <service-name> key <keyfile> + + File identified by `<keyfile>` containing the secret RNDC key shared with + remote DNS server. + +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> server <server> + + Configure the DNS `<server>` IP/FQDN used when updating this dynamic + assignment. + +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> zone <zone> + + Configure DNS `<zone>` to be updated. + +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> record <record> + + Configure DNS `<record>` which should be updated. This can be set multiple + times. + +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> ttl <ttl> + + Configure optional TTL value on the given resource record. This defualts to + 600 seconds. + +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 + + vyos@vyos# show service dns dynamic + interface eth0.7 { + rfc2136 VyOS-DNS { + key /config/auth/my.key + record example.vyos.io + 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.7": + # + use=if, if=eth0.7 + + # RFC2136 dynamic DNS configuration for example.vyos.io.vyos.io + server=ns1.vyos.io + protocol=nsupdate + password=/config/auth/my.key + ttl=300 + zone=vyos.io + 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 interface <interface> service <service> host-name <hostname> + + Setup the dynamic DNS hostname `<hostname>` associated with the DynDNS + provider identified by `<service>` when the IP address on interface + `<interface>` changes. + +.. cfgcmd:: set service dns dynamic interface <interface> service <service> login <username> + + Configure `<username>` used when authenticating the update request for + DynDNS service identified by `<service>`. + For Namecheap, set the <domain> you wish to update. + +.. cfgcmd:: set service dns dynamic interface <interface> service <service> password <password> + + Configure `<password>` used when authenticating the update request for + DynDNS service identified by `<service>`. + +.. cfgcmd:: set service dns dynamic interface <interface> service <service> 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 for available protocols. + +.. cfgcmd:: set service dns dynamic interface <interface> service <service> server <server> + + When a ``custom`` DynDNS provider is used the `<server>` where update + requests are being sent to must be specified. + +Example: +^^^^^^^^ + +Use DynDNS as your preferred provider: + +.. code-block:: none + + set service dns dynamic interface eth0 service dyndns + set service dns dynamic interface eth0 service dyndns login my-login + set service dns dynamic interface eth0 service dyndns password my-password + set service dns dynamic interface eth0 service dyndns host-name my-dyndns-hostname + +.. note:: Multiple services can be used per interface. Just specify as many + serives per interface as you like! + +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 interface <interface> use-web url <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 interface <interface> use-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/https.rst b/docs/configuration/service/https.rst new file mode 100644 index 00000000..49f2dbd9 --- /dev/null +++ b/docs/configuration/service/https.rst @@ -0,0 +1,166 @@ +.. _http-api: + +######## +HTTP-API +######## + +Enabling HTTP-API +----------------- + +VyOS HTTP API can be enabled through the ``set service https api`` command. + +.. code-block:: none + + set service https api debug + set service https api keys id MY-HTTP-API-ID key MY-HTTP-API-PLAINTEXT-KEY + +The local API process listens on localhost:8080, and nginx exposes it on all +virtual servers, by default. For the purpose of illustration below, we will +assume nginx is running at https://192.168.122.127. + +One can limit proxying to specific listen addresses/ports/server-names by +defining a ``service https virtual-host <id>``, and setting ``service https +api-restrict virtual-host <id>``. + +.. code-block:: none + + set service https virtual-host example listen-address 192.168.122.127 + set service https virtual-host example listen-port 44302 + set service https virtual-host example server-name example.net + + set service https api-restrict virtual-host example + +In this example, nginx will proxy only those requests to +192.168.122.127:44302 or example.net:44302 (assuming the DNS record is +viable). Omitting any of listen-address, listen-port, or server-name, will +leave appropriate defaults in the nginx directive. Multiple instances of +``service https api-restrict virtual-host`` may be set. + +Configuration mode requests +--------------------------- + +In our example, we are creating a dummy interface and assigning an address to it: + +.. code-block:: none + + curl -k -X POST -F data='{"op": "set", "path": ["interfaces", "dummy", "dum1", "address"], "value": "203.0.113.76/32"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/configure + +The ``/configure`` endpoint takes a request serialized in JSON. The only HTTP method it uses is POST. Request data is passed in the ``data=`` field and the API key is passed in the ``key=`` field. Key identifiers from the config are purely informational and the application doesn't need to know them, they only appear in the server logs to avoid exposing keys in log files, you only need the key itself. + +Since internally there is no distinction between a path and a value, you can omit the value field and include the value in the path like it's done in the shell commands: + +.. code-block:: none + + curl -k -X POST -F data='{"op": "set", "path": ["interfaces", "dummy", "dum10", "address", "203.0.113.99/32"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/configure + +Separate value field make the semantics more clear though, and also makes it easier to create a command template once and update it with different values as needed. + +You can pass the ``set``, ``delete`` or ``comment`` command to it. The API will push the command to the session and commit. + +To retrieve a value: + +.. code-block:: none + + curl -k -X POST -F data='{"op": "returnValue", "path": ["interfaces", "dummy", "dum1", "address"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve + +Use ``returnValues`` for multi-valued nodes. + + +Show config +""""""""""" + +To retrieve the full config under a path: + +.. code-block:: none + + # curl -k -X POST -F data='{"op": "showConfig", "path": ["interfaces", "dummy"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve + +It will return: + +.. code-block:: none + + {"success": true, "data": {"dummy": {"dum1": {"address": "203.0.113.76/32"}}}, "error": null} + +Passing an empty path will return the full config: + +.. code-block:: none + + # curl -k -X POST -F data='{"op": "showConfig", "path": []}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve + + +Configuration management requests +--------------------------------- + +When saving or loading a configuration, the endpoint is ``/config-file`` and you can pass the ``save`` or ``load`` command. + +If you don't specify the file when saving, it saves to ``/config/config.boot``. Here's an example: + +.. code-block:: none + + # curl -k -X POST -F key=MY-HTTP-API-PLAINTEXT-KEY -Fdata='{"op": "save", "file": "/config/config.boot"}' https://192.168.122.127/config-file + +Image management requests +------------------------- + +One may ``add`` or ``delete`` a system image using the endpoint ``/image``. Here are the respective examples: + +``add`` from ``url``. Here we use the URL of the latest rolling release: + +.. code-block:: none + + # curl -k -X POST -F data='{"op": "add", "url": "https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/image + +``delete`` by image ``name``. For example: + +.. code-block:: none + + # curl -k -X POST -F data='{"op": "delete", "name": "1.3-rolling-202006070117"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/image + +To list the available system images by name, one may use the operational mode request ``show`` discussed in the next section; in this setting it would be: + +.. code-block:: none + + # curl -k -X POST -F data='{"op": "show", "path": ["system", "image"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show + +Operational mode requests +------------------------- + +It is possible to run ``show`` and ``generate`` commands: + + +Request: + +.. code-block:: none + + curl -k -X POST -F data='{"op": "generate", "path": ["wireguard", "default-keypair"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/generate + +Response: + +.. code-block:: none + + {"success": true, "data": "", "error": null} + +Request: + +.. code-block:: none + + curl -k -X POST -F data='{"op": "show", "path": ["wireguard", "keypairs", "pubkey", "default"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show + +Response: + +.. code-block:: none + + {"success": true, "data": "<some pubkey>=\n", "error": null} + +Request: + +.. code-block:: none + + curl -k -X POST -F data='{"op": "show", "path": ["ip", "route"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show + +Response: + +.. code-block:: none + + {"success": true, "data": "Codes: K - kernel route, C - connected, S - static, R - RIP,\n O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP,\n T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP,\n F - PBR, f - OpenFabric,\n > - selected route, * - FIB route, q - queued route, r - rejected route\n\nS>* 0.0.0.0/0 [210/0] via 192.168.100.1, eth0, 01:41:05\nC>* 192.168.0.0/24 is directly connected, eth1, 01:41:09\nC>* 192.168.100.0/24 is directly connected, eth0, 01:41:05\nC>* 203.0.113.76/32 is directly connected, dum1, 01:38:40\n", "error": null} + diff --git a/docs/configuration/service/index.rst b/docs/configuration/service/index.rst new file mode 100644 index 00000000..0ef2bbd3 --- /dev/null +++ b/docs/configuration/service/index.rst @@ -0,0 +1,29 @@ +####### +Service +####### + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + broadcast-relay + conntrack-sync + console-server + dhcp-relay + dhcp-server + dhcpv6-relay + dhcpv6-server + dns + https + ipoe-server + lldp + mdns + pppoe-advert + pppoe-server + router-advert + salt-minion + snmp + ssh + tftp-server + webproxy diff --git a/docs/configuration/service/ipoe-server.rst b/docs/configuration/service/ipoe-server.rst new file mode 100644 index 00000000..3f794af8 --- /dev/null +++ b/docs/configuration/service/ipoe-server.rst @@ -0,0 +1,149 @@ +.. include:: /_include/need_improvement.txt + +.. _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. + +Configuration +============= + +IPoE can be configure on different interfaces, it will depend on each specific +situation which interface will provide IPoE to clients. The clients 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 eth2 with the client mac address 08:00:27:2f:d8:06. Other DHCP +discovery requests will be ignored, unless the client mac has been enabled in +the configuration. + +.. code-block:: none + + set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 + set service ipoe-server authentication mode 'local' + set service ipoe-server dns-server server-1 '8.8.8.8' + set service ipoe-server dns-server server-2 '8.8.4.4' + set service ipoe-server interface eth2 client-subnet '192.168.0.0/24' + + +The first address of the parameter ``client-subnet``, will be used as the +default gateway. Connected sessions can be checked via the ``show ipoe-server +sessions`` command. + +.. code-block:: none + + vyos@vyos:~$ show ipoe-server sessions + + ifname | called-sid | calling-sid | ip | ip6 | ip6-dp | rate-limit | state | uptime | sid + -------+------------+-------------------+-------------+-----+--------+------------+--------+----------+------------------ + ipoe0 | eth2 | 08:00:27:2f:d8:06 | 192.168.0.2 | | | | active | 00:45:05 | dccc870fd3134612 + + +IPv6 SLAAC and IA-PD +-------------------- + +To configure IPv6 assignments for clients, two options need to be configured. +A global prefix which is terminated on the clients cpe and a delegated prefix, +the client can use for devices routed via the clients cpe. + +IPv6 DNS addresses are optional. + +.. code-block:: none + + set service ipoe-server authentication interface eth3 mac-address 08:00:27:2F:D8:06 + set service ipoe-server authentication mode 'local' + set service ipoe-server client-ipv6-pool delegate-prefix '2001:db8:1::/48,56' + set service ipoe-server client-ipv6-pool prefix '2001:db8::/48,64' + set service ipoe-server dnsv6-server server-1 '2001:db8::' + set service ipoe-server dnsv6-server server-2 '2001:db8:aaa::' + set service ipoe-server dnsv6-server server-3 '2001:db8:bbb::' + set service ipoe-server interface eth3 client-subnet '192.168.1.0/24' + +.. code-block:: none + + vyos@ipoe-server# run sh ipoe-server sessions + ifname | called-sid | calling-sid | ip | ip6 | ip6-dp | rate-limit | state | uptime | sid + -------+------------+-------------------+-------------+---------------------------------+-----------------+------------+--------+----------+------------------ + ipoe0 | eth3 | 08:00:27:2f:d8:06 | 192.168.1.2 | 2001:db8::a00:27ff:fe2f:d806/64 | 2001:db8:1::/56 | | active | 01:02:59 | 4626faf71b12cc25 + + +The clients :abbr:`CPE (Customer Premises Equipment)` can now communicate via +IPv4 or IPv6. All devices behind ``2001:db8::a00:27ff:fe2f:d806/64`` can use +addresses from ``2001:db8:1::/56`` and can globally communicate without the +need of any NAT rules. + +Automatic VLAN creation +----------------------- + +To create VLANs per user during runtime, the following settings are required on +a per interface basis. VLAN ID and VLAN range can be present in the +configuration at the same time. + +.. code-block:: none + + set service ipoe-server interface eth2 network vlan + set service ipoe-server interface eth2 vlan-id 100 + set service ipoe-server interface eth2 vlan-id 200 + set service ipoe-server interface eth2 vlan-range 1000-2000 + set service ipoe-server interface eth2 vlan-range 2500-2700 + +RADIUS Setup +------------ + +To use a RADIUS server for authentication and bandwidth-shaping, the following +example configuration can be used. + +.. code-block:: none + + set service ipoe-server authentication mode 'radius' + set service ipoe-server authentication radius-server 10.100.100.1 secret 'password' + +Bandwidth Shaping +================= + +Bandwidth rate limits can be set for local users within the configuration or +via RADIUS based attributes. + +Bandwidth Shaping for local users +--------------------------------- + +The rate-limit is set in kbit/sec. + +.. code-block:: none + + set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 rate-limit download '500' + set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 rate-limit upload '500' + set service ipoe-server authentication mode 'local' + set service ipoe-server dns-server server-1 '8.8.8.8' + set service ipoe-server dns-server server-2 '8.8.4.4' + set service ipoe-server interface eth2 client-subnet '192.168.0.0/24' + +.. code-block:: none + + vyos@vyos# run show ipoe-server sessions + + ifname | called-sid | calling-sid | ip | ip6 | ip6-dp | rate-limit | state | uptime | sid + -------+------------+-------------------+-------------+-----+--------+------------+--------+----------+------------------ + ipoe0 | eth2 | 08:00:27:2f:d8:06 | 192.168.0.2 | | | 500/500 | active | 00:00:05 | dccc870fd31349fb + +.. include:: /_include/common-references.txt diff --git a/docs/configuration/service/lldp.rst b/docs/configuration/service/lldp.rst new file mode 100644 index 00000000..4b1743e6 --- /dev/null +++ b/docs/configuration/service/lldp.rst @@ -0,0 +1,141 @@ +.. _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> disable + + Disable transmit of LLDP frames on given `<interface>`. Useful to exclude + certain interfaces from LLDP when ``all`` have been enabled. + +.. cfgcmd:: set service lldp snmp enable + + 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/mdns.rst b/docs/configuration/service/mdns.rst new file mode 100644 index 00000000..9d6a292a --- /dev/null +++ b/docs/configuration/service/mdns.rst @@ -0,0 +1,44 @@ +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 224.0.0.251 address, which is "administratively scoped" +and does not leave the subnet. It retransmits mDNS packets from one interface +to other interfaces. This enables support for e.g. Apple Airplay devices across +multiple VLANs. + +Since the mDNS protocol sends the AA 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. + +Configuration +============= + +.. cfgcmd:: set service mdns repeater interface <interface> + + To enable mDNS repeater you need to configure at least two interfaces. To + re-broadcast all incoming mDNS packets from any interface configured here to + any other interface configured under this section. + +.. cfgcmd:: set service mdns repeater disable + + mDNS repeater can be temporarily disabled without deleting the service using + +.. 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! + +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' + +.. _`Multicast DNS`: https://en.wikipedia.org/wiki/Multicast_DNS diff --git a/docs/configuration/service/pppoe-advert.rst b/docs/configuration/service/pppoe-advert.rst new file mode 100644 index 00000000..bbb82202 --- /dev/null +++ b/docs/configuration/service/pppoe-advert.rst @@ -0,0 +1,2 @@ +pppoe-advert +############
\ No newline at end of file diff --git a/docs/configuration/service/pppoe-server.rst b/docs/configuration/service/pppoe-server.rst new file mode 100644 index 00000000..224ff0d8 --- /dev/null +++ b/docs/configuration/service/pppoe-server.rst @@ -0,0 +1,397 @@ +.. _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. + +Configuration +============= + + +First steps +----------- + + +.. 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> + + Use this command to define whether your PPPoE clients will locally + authenticate in your VyOS system or in RADIUS server. + +.. cfgcmd:: set service pppoe-server authentication local-users username <name> password <password> + + Use this command to configure the username and the password of a + locally configured user. + +.. 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> + + Use this command to configure the local gateway IP address. + +.. cfgcmd:: set service pppoe-server name-server <address> + + Use this command to set the IPv4 or IPv6 address of every Doman Name + Server you want to configure. They will be propagated to PPPoE + clients. + + +Client Address Pools +-------------------- + +To automatically assign the client an IP address as tunnel endpoint, a +client IP pool is needed. The source can be either RADIUS or a local +subnet or IP range definition. + +Once the local tunnel endpoint ``set service pppoe-server gateway-address +'10.1.1.2'`` has been defined, the client IP pool can be either defined +as a range or as subnet using CIDR notation. If the CIDR notation is +used, multiple subnets can be setup which are used sequentially. + + +**Client IP address via IP range definition** + +.. cfgcmd:: set service pppoe-server client-ip-pool start <address> + + Use this command to define the first IP address of a pool of + addresses to be given to PPPoE clients. It must be within a /24 + subnet. + +.. cfgcmd:: set service pppoe-server client-ip-pool stop <address> + + Use this command to define the last IP address of a pool of + addresses to be given to PPPoE clients. It must be within a /24 + subnet. + +.. code-block:: none + + set service pppoe-server client-ip-pool start '10.1.1.100' + set service pppoe-server client-ip-pool stop '10.1.1.111' + + +**Client IP subnets via CIDR notation** + +.. cfgcmd:: set service pppoe-server client-ip-pool subnet <address> + + Use this command for every pool of client IP addresses you want to + define. The addresses of this pool will be given to PPPoE clients. + You must use CIDR notation and it must be within a /24 subnet. + +.. code-block:: none + + set service pppoe-server client-ip-pool subnet '10.1.1.0/24' + set service pppoe-server client-ip-pool subnet '10.1.2.0/24' + set service pppoe-server client-ip-pool subnet '10.1.3.0/24' + + +**RADIUS based IP pools (Framed-IP-Address)** + +To use a radius server, you need to switch to authentication mode RADIUS +and then configure it. + +.. cfgcmd:: set service pppoe-server authentication radius server <address> key <secret> + + Use this command to configure the IP address and the shared secret + key of your RADIUS server. You can have multiple RADIUS servers + configured if you wish to achieve redundancy. + + +.. code-block:: none + + set service pppoe-server access-concentrator 'ACN' + set service pppoe-server authentication mode 'radius' + set service pppoe-server authentication radius server 10.1.100.1 key 'secret' + set service pppoe-server interface 'eth1' + set service pppoe-server gateway-address '10.1.1.2' + +RADIUS provides the IP addresses in the example above via +Framed-IP-Address. + +**RADIUS sessions management DM/CoA** + +.. cfgcmd:: set service pppoe-server authentication radius dynamic-author <key | port | server> + + Use this command to configure Dynamic Authorization Extensions to + RADIUS so that you can remotely disconnect sessions and change some + authentication parameters. + +.. code-block:: none + + set service pppoe-server authentication radius dynamic-author key 'secret123' + set service pppoe-server authentication radius dynamic-author port '3799' + set service pppoe-server authentication radius dynamic-author server '10.1.1.2' + + +Example, from radius-server send command for disconnect client with +username test + +.. code-block:: none + + root@radius-server:~# echo "User-Name=test" | radclient -x 10.1.1.2:3799 disconnect secret123 + +You can also use another attributes for identify client for disconnect, +like Framed-IP-Address, Acct-Session-Id, etc. Result commands appears in +log. + +.. code-block:: none + + show log | match Disconnect* + +Example for changing rate-limit via RADIUS CoA. + +.. code-block:: none + + echo "User-Name=test,Filter-Id=5000/4000" | radclient 10.1.1.2:3799 coa secret123 + +Filter-Id=5000/4000 (means 5000Kbit down-stream rate and 4000Kbit +up-stream rate) If attribute Filter-Id redefined, replace it in RADIUS +CoA request. + +Automatic VLAN Creation +----------------------- + +.. cfgcmd:: set service pppoe-server interface <interface> <vlan-id | vlan range> <text> + + 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, the 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-id 100 + set service pppoe-server interface eth3 vlan-id 200 + set service pppoe-server interface eth3 vlan-range 500-1000 + set service pppoe-server interface eth3 vlan-range 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 <name> rate-limit <download | upload> + + Use this command to configure a data-rate limit to PPPOoE clients for + traffic download or upload. The rate-limit is set in kbit/sec. + +.. 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 start '10.1.1.100' + set service pppoe-server client-ip-pool stop '10.1.1.111' + 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 +---- + +IPv6 client's prefix assignment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set service pppoe-server client-ipv6-pool prefix <address> mask <number-of-bits> + + Use this comand to set the IPv6 address pool from which a 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. + + +IPv6 Prefix Delegation +^^^^^^^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set service pppoe-server client-ipv6-pool delegate <address> delegation-prefix <number-of-bits> + + Use this command to configure DHCPv6 Prefix Delegation (RFC3633). 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. + + +Maintenance mode +================ + +.. opcmd:: set pppoe-server maintenance-mode <enable | disable> + + For network maintenance, it's a good idea to direct users to a backup + server so that the primary server can be safely taken out of service. + It's possible to switch your PPPoE server to maintenance mode where + it maintains already established connections, but refuses new + connection attempts. + + +Checking connections +==================== + +.. 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 + + +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. + +.. code-block:: none + + vyos@# set service pppoe-server session-control + Possible completions: + disable Disables session control + deny Deny second session authorization + + + + + + +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 start '10.1.1.100' + set service pppoe-server client-ip-pool stop '10.1.1.111' + 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 via pppoe-server. + +.. 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 start '192.168.0.1' + set service pppoe-server client-ip-pool stop '192.168.0.10' + set service pppoe-server client-ipv6-pool delegate '2001:db8:8003::/48' delegation-prefix '56' + set service pppoe-server client-ipv6-pool prefix '2001:db8:8002::/48' mask '64' + set service pppoe-server name-server '8.8.8.8' + set service pppoe-server name-server '2001:4860: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 diff --git a/docs/configuration/service/router-advert.rst b/docs/configuration/service/router-advert.rst new file mode 100644 index 00000000..bc92f315 --- /dev/null +++ b/docs/configuration/service/router-advert.rst @@ -0,0 +1,89 @@ +.. _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 + * l2tpv3 + * openvpn + * pseudo-ethernet + * tunnel + * vxlan + * wireguard + * wireless + * wirelessmodem + + +Enabling Advertisments +~~~~~~~~~~~~~~~~~~~~~~~ + +.. cfgcmd:: set service router-advert interface <interface> .... + +.. 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, exluded 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" + +Advertising a Prefix +'''''''''''''''''''' + +.. cfgcmd:: set service router-advert interface <interface> prefix 2001:DB8::/32 + +.. csv-table:: + :header: "VyOS Field", "Description" + :widths: 10,30 + + "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)" + + +Disabling Advertisements +~~~~~~~~~~~~~~~~~~~~~~~~ + +To disable advertisements without deleting the configuration: + +.. cfgcmd:: set service router-advert interface <interface> no-send-advert + +Example Configuration +~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: none + + interface eth0.2 { + default-preference high + hop-limit 64 + interval { + max 600 + } + name-server 2001:4860:4860::8888 + name-server 2001:4860:4860::8844 + other-config-flag + prefix 2001:DB8:beef:2::/64 { + valid-lifetime 2592000 + } + reachable-time 0 + retrans-timer 0 + } diff --git a/docs/configuration/service/salt-minion.rst b/docs/configuration/service/salt-minion.rst new file mode 100644 index 00000000..63df57a4 --- /dev/null +++ b/docs/configuration/service/salt-minion.rst @@ -0,0 +1,2 @@ +salt-minion +###########
\ No newline at end of file diff --git a/docs/configuration/service/snmp.rst b/docs/configuration/service/snmp.rst new file mode 100644 index 00000000..3f445ea8 --- /dev/null +++ b/docs/configuration/service/snmp.rst @@ -0,0 +1,266 @@ +.. _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.png + :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 securityapproach in v3 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. + +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 LCI config will look like: + +.. code-block:: none + + vyos@vyos# show service snmp + listen-address 172.18.254.201 { + } + location "Wuerzburg, Dr.-Georg-Fuchs-Str. 8" + 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 with the a activate ssh service like this + +.. 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 + + +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. + +.. 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. + +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 + diff --git a/docs/configuration/service/ssh.rst b/docs/configuration/service/ssh.rst new file mode 100644 index 00000000..0153d918 --- /dev/null +++ b/docs/configuration/service/ssh.rst @@ -0,0 +1,108 @@ +.. _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 ciphers <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``, ``arcfour128``, + ``arcfour256``, ``arcfour``, ``blowfish-cbc``, ``cast128-cbc`` + +.. cfgcmd:: set service ssh disable-password-authentication + + Disable password based authentication. Login via SSH keys only. This hardens + security! + +.. 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 macs <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. + + 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. diff --git a/docs/configuration/service/tftp-server.rst b/docs/configuration/service/tftp-server.rst new file mode 100644 index 00000000..276ce5fb --- /dev/null +++ b/docs/configuration/service/tftp-server.rst @@ -0,0 +1,54 @@ +.. _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. + +.. 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 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 not allowed! + +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 + } diff --git a/docs/configuration/service/webproxy.rst b/docs/configuration/service/webproxy.rst new file mode 100644 index 00000000..654e73f2 --- /dev/null +++ b/docs/configuration/service/webproxy.rst @@ -0,0 +1,153 @@ +Webproxy +-------- + +The proxy service in VyOS is based on Squid3 and some related modules. + +Squid3_ 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. + +All examples here assumes that your inside ip address is ``192.168.0.1``. +Replace with your own where applicable. + +URL Filtering is provided by Squidguard_. + +Configuration +^^^^^^^^^^^^^^ + +.. code-block:: none + + # Enable proxy service + set service webproxy listen-address 192.168.0.1 + + # By default it will listen to port 3128. If you want something else you have to define that. + set service webproxy listen-address 192.168.0.1 port 2050 + + # By default the transparent proxy on that interface is enabled. To disable that you simply + set service webproxy listen-address 192.168.0.1 disable-transparent + + # Block specific urls + set service webproxy url-filtering squidguard local-block myspace.com + + # If you want to you can log these blocks + set service webproxy url-filtering squidguard log local-block + + +Options +******* + +Filtering by category +^^^^^^^^^^^^^^^^^^^^^ + +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. + +.. code-block:: none + + vyos@vyos# commit + [ service webproxy ] + Warning: no blacklists installed + Unknown block-category [ads] for policy [default] + + [[service webproxy]] failed + Commit failed + +* Download/Update complete blacklist + + :code:`update webproxy blacklists` + +* Download/Update partial blacklist + + :code:`update webproxy blacklists category ads` + + 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` + +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. + +.. 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 + } + +* ``base-dn`` set the base directory for the search +* ``bind-dn`` and ``password``: set the user, which is used for the ldap search +* ``filter-expression``: set the exact filter which a authorized user match in a ldap-search. In this example every User is able to authorized. + +You can find more about the ldap authentication `here <http://www.squid-cache.org/Versions/v3/3.2/manuals/basic_ldap_auth.html>`_ + +Adjusting cache size +^^^^^^^^^^^^^^^^^^^^ + +The size of the proxy cache can be adjusted by the user. + +.. code-block:: none + + set service webproxy cache-size + Possible completions: + <0-4294967295> + Disk cache size in MB (default 100) + 0 Disable disk caching + 100 + +Bypassing the webproxy +^^^^^^^^^^^^^^^^^^^^^^ + +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.) + +.. _Squid3: http://www.squid-cache.org/ +.. _Squidguard: http://www.squidguard.org/ |