diff options
| author | Daniel Thorpe <1077065+dantho281@users.noreply.github.com> | 2021-02-11 02:25:57 +0000 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-02-11 02:25:57 +0000 |
| commit | e88fba68357181bd54fcc7489cbba08780cee6cd (patch) | |
| tree | b67e88b1208fa835edf0420a42dd2b624ec2105b /docs/configuration/service | |
| parent | dab473bfd04ab2930c043b853ba9995d1ff335e6 (diff) | |
| parent | f33b0c78b07c80998d2c0e64d6a20bcb109f6db5 (diff) | |
| download | vyos-documentation-e88fba68357181bd54fcc7489cbba08780cee6cd.tar.gz vyos-documentation-e88fba68357181bd54fcc7489cbba08780cee6cd.zip | |
Merge pull request #1 from vyos/master
Update fork
Diffstat (limited to 'docs/configuration/service')
19 files changed, 3445 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..3c9f08e4 --- /dev/null +++ b/docs/configuration/service/conntrack-sync.rst @@ -0,0 +1,201 @@ +.. 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..a509723e --- /dev/null +++ b/docs/configuration/service/console-server.rst @@ -0,0 +1,108 @@ +.. _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..5355a0fd --- /dev/null +++ b/docs/configuration/service/dhcp-relay.rst @@ -0,0 +1,159 @@ +.. _dhcp-relay: + +########## +DHCP Relay +########## + +If you want your router to forward DHCP requests to an external DHCP server +you can configure the system to act as a DHCP relay agent. The DHCP relay +agent works with IPv4 and IPv6 addresses. + +All interfaces used for the DHCP relay must be configured. + +********** +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/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst new file mode 100644 index 00000000..28dddb2f --- /dev/null +++ b/docs/configuration/service/dhcp-server.rst @@ -0,0 +1,621 @@ +.. _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 00:53:01: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 00:53:01: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: + +.. stop_vyoslinter (00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff false positive) + +.. 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 + } + } + } + +.. start_vyoslinter + +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) diff --git a/docs/configuration/service/dns.rst b/docs/configuration/service/dns.rst new file mode 100644 index 00000000..0a65161b --- /dev/null +++ b/docs/configuration/service/dns.rst @@ -0,0 +1,328 @@ +.. _dns-forwarding: + +############## +DNS Forwarding +############## + +Configuration +============= + +VyOS provides DNS infrastructure for small networks. It is designed to be +lightweight and have a small footprint, suitable for resource constrained +routers and firewalls. For this we utilize PowerDNS recursor. + +The VyOS DNS forwarder does not require an upstream DNS server. It can serve as +a full recursive DNS server - but it can also forward queries to configurable +upstream DNS servers. By not configuring any upstream DNS servers you also +avoid being tracked by the provider of your upstream DNS server. + +.. cfgcmd:: set service dns forwarding system + + Forward incoming DNS queries to the DNS servers configured under the ``system + name-server`` nodes. + +.. cfgcmd:: set service dns forwarding 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 nameserver. Multiple nameservers + can be specified. You can use this feature for a DNS split-horizon + configuration. + + .. note:: This also works for reverse-lookup zones (``18.172.in-addr.arpa``). + +.. cfgcmd:: set service dns forwarding allow-from <network> + + Given the fact that open DNS recursors could be used on DDoS amplification + attacks, you must configure the networks which are allowed to use this + recursor. A network of ``0.0.0.0/0`` or ``::/0`` would allow all IPv4 and + IPv6 networks to query this server. This is generally a bad idea. + +.. cfgcmd:: set service dns forwarding dnssec + <off | process-no-validate | process | log-fail | validate> + + The PowerDNS recursor has 5 different levels of DNSSEC processing, which can + be set with the dnssec setting. In order from least to most processing, these + are: + + * **off** In this mode, no DNSSEC processing takes place. The recursor will + not set the DNSSEC OK (DO) bit in the outgoing queries and will ignore the + DO and AD bits in queries. + + * **process-no-validate** In this mode the recursor acts as a "security + aware, non-validating" nameserver, meaning it will set the DO-bit on + outgoing queries and will provide DNSSEC related RRsets (NSEC, RRSIG) to + clients that ask for them (by means of a DO-bit in the query), except for + zones provided through the auth-zones setting. It will not do any + validation in this mode, not even when requested by the client. + + * **process** When dnssec is set to process the behavior is similar to + process-no-validate. However, the recursor will try to validate the data + if at least one of the DO or AD bits is set in the query; in that case, + it will set the AD-bit in the response when the data is validated + successfully, or send SERVFAIL when the validation comes up bogus. + + * **log-fail** In this mode, the recursor will attempt to validate all data + it retrieves from authoritative servers, regardless of the client's DNSSEC + desires, and will log the validation result. This mode can be used to + determine the extra load and amount of possibly bogus answers before + turning on full-blown validation. Responses to client queries are the same + as with process. + + * **validate** The highest mode of DNSSEC processing. In this mode, all + queries will be validated and will be answered with a SERVFAIL in case of + bogus data, regardless of the client's request. + + .. note:: The popular Unix/Linux ``dig`` tool sets the AD-bit in the query. + This might lead to unexpected query results when testing. Set ``+noad`` + on the ``dig`` command line when this is the case. + + .. note:: The ``CD``-bit is honored correctly for process and validate. For + log-fail, failures will be logged too. + +.. cfgcmd:: set service dns forwarding ignore-hosts-file + + Do not use the local ``/etc/hosts`` file in name resolution. VyOS DHCP + server will use this file to add resolvers to assigned addresses. + +.. cfgcmd:: set service dns forwarding 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 defaults 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 + services 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..b9c691da --- /dev/null +++ b/docs/configuration/service/https.rst @@ -0,0 +1,181 @@ +.. _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..fb194239 --- /dev/null +++ b/docs/configuration/service/index.rst @@ -0,0 +1,25 @@ +####### +Service +####### + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + broadcast-relay + conntrack-sync + console-server + dhcp-relay + dhcp-server + dns + https + ipoe-server + lldp + mdns + pppoe-server + router-advert + 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..7858ff19 --- /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 '10.10.1.1' + set service ipoe-server dns-server server-2 '10.10.1.2' + 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 '10.10.1.1' + set service ipoe-server dns-server server-2 '10.10.1.2' + 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..aa357211 --- /dev/null +++ b/docs/configuration/service/lldp.rst @@ -0,0 +1,142 @@ +.. _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.disable b/docs/configuration/service/pppoe-advert.disable new file mode 100644 index 00000000..bbb82202 --- /dev/null +++ b/docs/configuration/service/pppoe-advert.disable @@ -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..8d895f9d --- /dev/null +++ b/docs/configuration/service/pppoe-server.rst @@ -0,0 +1,407 @@ +.. _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 '10.1.1.1' + set service pppoe-server name-server '2001:db8:4860::8888' + set service pppoe-server interface 'eth2' + set service pppoe-server gateway-address '10.100.100.1' + +The client, once successfully authenticated, will receive an IPv4 and an +IPv6 /64 address to terminate the pppoe endpoint on the client side and +a /56 subnet for the clients internal use. + +.. code-block:: none + + vyos@pppoe-server:~$ sh pppoe-server sessions + ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes + --------+----------+-------------+--------------------------+---------------------+-------------------+------------+--------+----------+----------+---------- + ppp0 | test | 192.168.0.1 | 2001:db8:8002:0:200::/64 | 2001:db8:8003::1/56 | 00:53:00:12:42:eb | | active | 00:00:49 | 875 B | 2.1 KiB + +.. include:: /_include/common-references.txt diff --git a/docs/configuration/service/router-advert.rst b/docs/configuration/service/router-advert.rst new file mode 100644 index 00000000..36fa600d --- /dev/null +++ b/docs/configuration/service/router-advert.rst @@ -0,0 +1,97 @@ +.. _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> .... + +.. stop_vyoslinter + +.. csv-table:: + :header: "Field", "VyOS Option", "Description" + :widths: 10, 10, 20 + + "Cur Hop Limit", "hop-limit", "Hop count field of the outgoing RA packets" + """Managed address configuration"" flag", "managed-flag", "Tell hosts to use the administered stateful protocol (i.e. DHCP) for autoconfiguration" + """Other configuration"" flag", "other-config-flag", "Tell hosts to use the administered (stateful) protocol (i.e. DHCP) for autoconfiguration of other (non-address) information" + "MTU","link-mtu","Link MTU value placed in RAs, 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" + +.. start_vyoslinter + + +Advertising a Prefix +'''''''''''''''''''' + +.. cfgcmd:: set service router-advert interface <interface> prefix 2001:DB8::/32 + +.. stop_vyoslinter + +.. 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)" + +.. start_vyoslinter + +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:db8::1 + name-server 2001:db8::2 + 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.disable b/docs/configuration/service/salt-minion.disable new file mode 100644 index 00000000..63df57a4 --- /dev/null +++ b/docs/configuration/service/salt-minion.disable @@ -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..e962c1c5 --- /dev/null +++ b/docs/configuration/service/snmp.rst @@ -0,0 +1,273 @@ +.. _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 + +.. stop_vyoslinter + +The OID ``.1.3.6.1.4.1.8072.1.3.2.3.1.1.4.116.101.115.116``, once called, will +contain the output of the extension. + +.. start_vyoslinter + +.. code-block:: none + + root@vyos:/home/vyos# snmpwalk -v2c -c public 127.0.0.1 nsExtendOutput1 + NET-SNMP-EXTEND-MIB::nsExtendOutput1Line."my-extension" = STRING: hello + NET-SNMP-EXTEND-MIB::nsExtendOutputFull."my-extension" = STRING: hello + NET-SNMP-EXTEND-MIB::nsExtendOutNumLines."my-extension" = INTEGER: 1 + NET-SNMP-EXTEND-MIB::nsExtendResult."my-extension" = INTEGER: 0 + +SolarWinds +========== + +If you happen to use SolarWinds Orion as NMS you can also use the Device +Templates Management. A template for VyOS can be easily imported. + +.. stop_vyoslinter + +Create a file named ``VyOS-1.3.6.1.4.1.44641.ConfigMgmt-Commands`` using the +following content: + + +.. code-block:: none + + <Configuration-Management Device="VyOS" SystemOID="1.3.6.1.4.1.44641"> + <Commands> + <Command Name="Reset" Value="set terminal width 0${CRLF}set terminal length 0"/> + <Command Name="Reboot" Value="reboot${CRLF}Yes"/> + <Command Name="EnterConfigMode" Value="configure"/> + <Command Name="ExitConfigMode" Value="commit${CRLF}exit"/> + <Command Name="DownloadConfig" Value="show configuration commands"/> + <Command Name="SaveConfig" Value="commit${CRLF}save"/> + <Command Name="Version" Value="show version"/> + <Command Name="MenuBased" Value="False"/> + <Command Name="VirtualPrompt" Value=":~"/> + </Commands> + </Configuration-Management> + +.. _MIB: https://en.wikipedia.org/wiki/Management_information_base +.. _SNMPv2: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2 +.. _SNMPv3: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_3 + +.. start_vyoslinter
\ No newline at end of file diff --git a/docs/configuration/service/ssh.rst b/docs/configuration/service/ssh.rst new file mode 100644 index 00000000..94249766 --- /dev/null +++ b/docs/configuration/service/ssh.rst @@ -0,0 +1,157 @@ +.. _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. + +Operation +========= + +.. opcmd:: restart ssh + + Restart the SSH daemon process, the current session is not affected, only the + background daemon is restarted. + +.. opcmd:: generate ssh server-key + + Re-generated the public/private keyportion which SSH uses to secure + connections. + + .. note:: Already learned known_hosts files of clients need an update as the + public key will change. + +.. opcmd:: generate ssh client-key /path/to/private_key + + Re-generated a known pub/private keyfile which can e.g. used to connect to + other services (RPKI cache). + + Example: + + .. code-block:: none + + vyos@vyos:~$ generate ssh client-key /config/auth/id_rsa_rpki + Generating public/private rsa key pair. + Your identification has been saved in /config/auth/id_rsa_rpki. + Your public key has been saved in /config/auth/id_rsa_rpki.pub. + The key fingerprint is: + SHA256:XGv2PpdOzVCzpmEzJZga8hTRq7B/ZYL3fXaioLFLS5Q cpo@LR1.wue3 + The key's randomart image is: + +---[RSA 2048]----+ + | oo | + | ..o | + | . o.o.. o.| + | o+ooo o.o| + | Eo* =.o | + | o = +.o*+ | + | = o *.o.o| + | o * +.o+.+| + | =.. o=.oo| + +----[SHA256]-----+ + + Two new files ``/config/auth/id_rsa_rpki`` and ``/config/auth/id_rsa_rpki.pub`` + will be created. 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..e8f6423e --- /dev/null +++ b/docs/configuration/service/webproxy.rst @@ -0,0 +1,434 @@ +.. _webproxy: + +######## +Webproxy +######## + +The proxy service in VyOS is based on Squid_ and some related modules. + +Squid_ is a caching and forwarding HTTP web proxy. It has a wide variety of +uses, including speeding up a web server by caching repeated requests, caching +web, DNS and other computer network lookups for a group of people sharing +network resources, and aiding security by filtering traffic. Although primarily +used for HTTP and FTP, Squid includes limited support for several other +protocols including Internet Gopher, SSL,[6] TLS and HTTPS. Squid does not +support the SOCKS protocol. + +URL Filtering is provided by SquidGuard_. + +************* +Configuration +************* + +.. cfgcmd:: set service webproxy append-domain <domain> + + Use this command to specify a domain name to be appended to domain-names + within URLs that do not include a dot ``.`` the domain is appended. + + Example: to be appended is set to ``vyos.net`` and the URL received is + ``www/foo.html``, the system will use the generated, final URL of + ``www.vyos.net/foo.html``. + + .. code-block:: none + + set service webproxy append-domain vyos.net + +.. cfgcmd:: set service webproxy cache-size <size> + + The size of the on-disk Proxy cache is user configurable. The Proxies default + cache-size is configured to 100 MB. + + Unit of this command is MB. + + .. code-block:: none + + set service webproxy cache-size 1024 + +.. cfgcmd:: set service webproxy default-port <port> + + Specify the port used on which the proxy service is listening for requests. + This port is the default port used for the specified listen-address. + + Default port is 3128. + + .. code-block:: none + + set service webproxy default-port 8080 + +.. cfgcmd:: set service webproxy domain-block <domain> + + Used to block specific domains by the Proxy. Specifying "vyos.net" will block + all access to vyos.net, and specifying ".xxx" will block all access to URLs + having an URL ending on .xxx. + + .. code-block:: none + + set service webproxy domain-block vyos.net + +.. cfgcmd:: set service webproxy domain-noncache <domain> + + Allow access to sites in a domain without retrieving them from the Proxy + cache. Specifying "vyos.net" will allow access to vyos.net but the pages + accessed will not be cached. It useful for working around problems with + "If-Modified-Since" checking at certain sites. + + .. code-block:: none + + set service webproxy domain-noncache vyos.net + +.. cfgcmd:: set service webproxy listen-address <address> + + Specifies proxy service listening address. The listen address is the IP + address on which the web proxy service listens for client requests. + + For security, the listen address should only be used on internal/trusted + networks! + + .. code-block:: none + + set service webproxy listen-address 192.0.2.1 + +.. cfgcmd:: set service webproxy listen-address <address> disable-transparent + + Disables web proxy transparent mode at a listening address. + + In transparent proxy mode, all traffic arriving on port 80 and destined for + the Internet is automatically forwarded through the proxy. This allows + immediate proxy forwarding without configuring client browsers. + + Non-transparent proxying requires that the client browsers be configured with + the proxy settings before requests are redirected. The advantage of this is + that the client web browser can detect that a proxy is in use and can behave + accordingly. In addition, web-transmitted malware can sometimes be blocked by + a non-transparent web proxy, since they are not aware of the proxy settings. + + .. code-block:: none + + set service webproxy listen-address 192.0.2.1 disable-transparent + +.. cfgcmd:: set service webproxy listen-address <address> port <port> + + Sets the listening port for a listening address. This overrides the default + port of 3128 on the specific listen address. + + .. code-block:: none + + set service webproxy listen-address 192.0.2.1 port 8080 + + +.. cfgcmd:: set service webproxy reply-block-mime <mime> + + Used to block a specific mime-type. + + .. code-block:: none + + # block all PDFs + set service webproxy reply-block-mime application/pdf + + +.. cfgcmd:: set service webproxy reply-body-max-size <size> + + Specifies the maximum size of a reply body in KB, used to limit the reply + size. + + All reply sizes are accepted by default. + + .. code-block:: none + + set service webproxy reply-body-max-size 2048 + +Authentication +============== + +The embedded Squid proxy can use LDAP to authenticate users against a company +wide directory. The following configuration is an example of how to use Active +Directory as authentication backend. Queries are done via LDAP. + +.. cfgcmd:: set service webproxy authentication children <number> + + Maximum number of authenticator processes to spawn. If you start too few + Squid will have to wait for them to process a backlog of credential + verifications, slowing it down. When password verifications are done via a + (slow) network you are likely to need lots of authenticator processes. + + This defaults to 5. + + .. code-block:: none + + set service webproxy authentication children 10 + +.. cfgcmd:: set service webproxy authentication credentials-ttl <time> + + Specifies how long squid assumes an externally validated username:password + pair is valid for - in other words how often the helper program is called for + that user. Set this low to force revalidation with short lived passwords. + + Time is in minutes and defaults to 60. + + .. code-block:: none + + set service webproxy authentication credentials-ttl 120 + + +.. cfgcmd:: set service webproxy authentication method <ldap> + + Proxy authentication method, currently only LDAP is supported. + + .. code-block:: none + + set service webproxy authentication method ldap + +.. cfgcmd:: set service webproxy authentication realm + + Specifies the protection scope (aka realm name) which is to be reported to + the client for the authentication scheme. It is commonly part of the text + the user will see when prompted for their username and password. + + .. code-block:: none + + set service webproxy authentication realm "VyOS proxy auth" + +LDAP +---- + +.. cfgcmd:: set service webproxy authentication ldap base-dn <base-dn> + + Specifies the base DN under which the users are located. + + .. code-block:: none + + set service webproxy authentication ldap base-dn DC=vyos,DC=net + + +.. cfgcmd:: set service webproxy authentication ldap bind-dn <bind-dn> + + The DN and password to bind as while performing searches. + + .. code-block:: none + + set service webproxy authentication ldap bind-dn CN=proxyuser,CN=Users,DC=vyos,DC=net + +.. cfgcmd:: set service webproxy authentication ldap filter-expression <expr> + + LDAP search filter to locate the user DN. Required if the users are in a + hierarchy below the base DN, or if the login name is not what builds the user + specific part of the users DN. + + The search filter can contain up to 15 occurrences of %s which will be + replaced by the username, as in "uid=%s" for :rfc:`2037` directories. For a + detailed description of LDAP search filter syntax see :rfc:`2254`. + + .. code-block:: none + + set service webproxy authentication ldap filter-expression (cn=%s) + +.. cfgcmd:: set service webproxy authentication ldap password <password> + + The DN and password to bind as while performing searches. As the password + needs to be printed in plain text in your Squid configuration it is strongly + recommended to use a account with minimal associated privileges. This to limit + the damage in case someone could get hold of a copy of your Squid + configuration file. + + .. code-block:: none + + set service webproxy authentication ldap password vyos + +.. cfgcmd:: set service webproxy authentication ldap persistent-connection + + Use a persistent LDAP connection. Normally the LDAP connection is only open + while validating a username to preserve resources at the LDAP server. This + option causes the LDAP connection to be kept open, allowing it to be reused + for further user validations. + + Recommended for larger installations. + + .. code-block:: none + + set service webproxy authentication ldap persistent-connection + +.. cfgcmd:: set service webproxy authentication ldap port <port> + + Specify an alternate TCP port where the ldap server is listening if other than + the default LDAP port 389. + + .. code-block:: none + + set service webproxy authentication ldap port 389 + +.. cfgcmd:: set service webproxy authentication ldap server <server> + + Specify the LDAP server to connect to. + + .. code-block:: none + + set service webproxy authentication ldap server ldap.vyos.net + + +.. cfgcmd:: set service webproxy authentication ldap use-ssl + + Use TLS encryption. + + .. code-block:: none + + set service webproxy authentication ldap use-ssl + + +.. cfgcmd:: set service webproxy authentication ldap username-attribute <attr> + + Specifies the name of the DN attribute that contains the username/login. + Combined with the base DN to construct the users DN when no search filter is + specified (`filter-expression`). + + Defaults to 'uid' + + .. note:: This can only be done if all your users are located directly under + the same position in the LDAP tree and the login name is used for naming + each user object. If your LDAP tree does not match these criterias or if you + want to filter who are valid users then you need to use a search filter to + search for your users DN (`filter-expression`). + + .. code-block:: none + + set service webproxy authentication ldap username-attribute uid + +.. cfgcmd:: set service webproxy authentication ldap version <2 | 3> + + LDAP protocol version. Defaults to 3 if not specified. + + .. code-block:: none + + set service webproxy authentication ldap version 2 + +URL filtering +============= + +.. include:: /_include/need_improvement.txt + + +.. cfgcmd:: set service webproxy url-filtering disable + + Disables web filtering without discarding configuration. + + .. code-block:: none + + set service webproxy url-filtering disable + +********* +Operation +********* + +.. include:: /_include/need_improvement.txt + +Filtering +========= + +Update +------ + +If you want to use existing blacklists you have to create/download a database +first. Otherwise you will not be able to commit the config changes. + + +.. opcmd:: update webproxy blacklists + + Download/Update complete blacklist + + .. code-block:: none + + vyos@vyos:~$ update webproxy blacklists + Warning: No url-filtering blacklist installed + Would you like to download a default blacklist? [confirm][y] + Connecting to ftp.univ-tlse1.fr (193.49.48.249:21) + blacklists.gz 100% |*************************************************************************************************************| 17.0M 0:00:00 ETA + Uncompressing blacklist... + Checking permissions... + Skip link for [ads] -> [publicite] + Building DB for [adult/domains] - 2467177 entries + Building DB for [adult/urls] - 67798 entries + Skip link for [aggressive] -> [agressif] + Building DB for [agressif/domains] - 348 entries + Building DB for [agressif/urls] - 36 entries + Building DB for [arjel/domains] - 69 entries + ... + + Building DB for [webmail/domains] - 374 entries + Building DB for [webmail/urls] - 9 entries + + The webproxy daemon must be restarted + Would you like to restart it now? [confirm][y] + + [ ok ] Restarting squid (via systemctl): squid.service. + vyos@vyos:~$ + +.. opcmd:: update webproxy blacklists category <category> + + Download/Update partial blacklist. + + Use tab completion to get a list of categories. + +* To auto update the blacklist files + + :code:`set service webproxy url-filtering squidguard auto-update + update-hour 23` + +* To configure blocking add the following to the configuration + + :code:`set service webproxy url-filtering squidguard block-category ads` + + :code:`set service webproxy url-filtering squidguard block-category malware` + +Bypassing the webproxy +---------------------- + +.. include:: /_include/need_improvement.txt + +Some services don't work correctly when being handled via a web proxy. +So sometimes it is useful to bypass a transparent proxy: + +* To bypass the proxy for every request that is directed to a specific + destination: + + :code:`set service webproxy whitelist destination-address 198.51.100.33` + + :code:`set service webproxy whitelist destination-address 192.0.2.0/24` + + +* To bypass the proxy for every request that is coming from a specific source: + + :code:`set service webproxy whitelist source-address 192.168.1.2` + + :code:`set service webproxy whitelist source-address 192.168.2.0/24` + + (This can be useful when a called service has many and/or often changing + destination addresses - e.g. Netflix.) + +******** +Examples +******** + +.. code-block:: none + + vyos@vyos# show service webproxy + authentication { + children 5 + credentials-ttl 60 + ldap { + base-dn DC=example,DC=local + bind-dn CN=proxyuser,CN=Users,DC=example,DC=local + filter-expression (cn=%s) + password Qwert1234 + server ldap.example.local + username-attribute cn + } + method ldap + realm "VyOS Webproxy" + } + cache-size 100 + default-port 3128 + listen-address 192.168.188.103 { + disable-transparent + } + +.. _Squid: http://www.squid-cache.org/ +.. _SquidGuard: http://www.squidguard.org/ |