diff options
| author | rebortg <github@ghlr.de> | 2020-11-30 20:53:36 +0100 |
|---|---|---|
| committer | rebortg <github@ghlr.de> | 2020-11-30 20:53:36 +0100 |
| commit | 8943fc9f877cbee3301a8261ddd27b4b1f15f174 (patch) | |
| tree | bb09c5f41a7683dc361517c2bde346eea36cda24 /docs/services | |
| parent | e33e1268f944be445b5a771df0e97e913487512f (diff) | |
| download | vyos-documentation-8943fc9f877cbee3301a8261ddd27b4b1f15f174.tar.gz vyos-documentation-8943fc9f877cbee3301a8261ddd27b4b1f15f174.zip | |
arrange services and protocols
Diffstat (limited to 'docs/services')
| -rw-r--r-- | docs/services/conntrack.rst | 200 | ||||
| -rw-r--r-- | docs/services/console-server.rst | 107 | ||||
| -rw-r--r-- | docs/services/dhcp.rst | 776 | ||||
| -rw-r--r-- | docs/services/dns-forwarding.rst | 147 | ||||
| -rw-r--r-- | docs/services/dynamic-dns.rst | 164 | ||||
| -rw-r--r-- | docs/services/index.rst | 26 | ||||
| -rw-r--r-- | docs/services/ipoe-server.rst | 149 | ||||
| -rw-r--r-- | docs/services/lldp.rst | 141 | ||||
| -rw-r--r-- | docs/services/mdns-repeater.rst | 44 | ||||
| -rw-r--r-- | docs/services/pppoe-server.rst | 397 | ||||
| -rw-r--r-- | docs/services/router-advert.rst | 89 | ||||
| -rw-r--r-- | docs/services/snmp.rst | 266 | ||||
| -rw-r--r-- | docs/services/ssh.rst | 106 | ||||
| -rw-r--r-- | docs/services/tftp.rst | 54 | ||||
| -rw-r--r-- | docs/services/udp-broadcast-relay.rst | 61 | ||||
| -rw-r--r-- | docs/services/webproxy.rst | 153 |
16 files changed, 0 insertions, 2880 deletions
diff --git a/docs/services/conntrack.rst b/docs/services/conntrack.rst deleted file mode 100644 index 55cd088e..00000000 --- a/docs/services/conntrack.rst +++ /dev/null @@ -1,200 +0,0 @@ -.. 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/services/console-server.rst b/docs/services/console-server.rst deleted file mode 100644 index cf222544..00000000 --- a/docs/services/console-server.rst +++ /dev/null @@ -1,107 +0,0 @@ -.. _console_server: - -############## -Console Server -############## - -Starting of with VyOS 1.3 (equuleus) we added support for running VyOS as an -Out-of-Band Management device which provides remote access by means of SSH to -directly attached serial interfaces. - -Serial interfaces can be any interface which is directly connected to the CPU -or chipset (mostly known as a ttyS interface in Linux) or any other USB to -serial converter (Prolific PL2303 or FTDI FT232/FT4232 based chips). - -If you happened to use a Cisco NM-16A - Sixteen Port Async Network Module or -NM-32A - Thirty-two Port Async Network Module - this is your VyOS replacement. - -For USB port information please refor to: :ref:`hardware_usb`. - -Configuration -============= - -Between computers, the most common configuration used was "8N1": eight bit -characters, with one start bit, one stop bit, and no parity bit. Thus 10 Baud -times are used to send a single character, and so dividing the signalling -bit-rate by ten results in the overall transmission speed in characters per -second. This is also the default setting if none of those options are defined. - -.. cfgcmd:: set service console-server <device> 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/services/dhcp.rst b/docs/services/dhcp.rst deleted file mode 100644 index 56316793..00000000 --- a/docs/services/dhcp.rst +++ /dev/null @@ -1,776 +0,0 @@ -.. _dhcp: - -############# -DHCP / DHCPv6 -############# - -VyOS uses ISC DHCPd for both IPv4 and IPv6 address assignment. - -.. _dhcp-server: - -DHCP 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 -^^^^^^^ - -Quick-Start -""""""""""" - -* We are offering address space in the `192.0.2.0/24` network. -* We are using the network name `mypool`. - -.. code-block:: none - - set service dhcp-server shared-network-name mypool authoritative - set service dhcp-server shared-network-name mypool subnet 192.0.2.0/24 default-router 192.0.2.1 - set service dhcp-server shared-network-name mypool subnet 192.0.2.0/24 dns-server 192.0.2.1 - set service dhcp-server shared-network-name mypool subnet 192.0.2.0/24 lease 86400 - set service dhcp-server shared-network-name mypool subnet 192.0.2.0/24 range 0 start 192.0.2.100 - set service dhcp-server shared-network-name mypool subnet 192.0.2.0/24 range 0 stop 192.0.2.199 - -The generated config will look like: - -.. code-block:: none - - vyos@vyos# show service dhcp-server shared-network-name mypool - authoritative - subnet 192.0.2.0/24 { - default-router 192.0.2.1 - dns-server 192.0.2.1 - lease 86400 - range 0 { - start 192.0.2.100 - stop 192.0.2.199 - } - } - - -Failover -"""""""" - -* 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` - -**Primary** - -.. 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 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' - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 start '192.168.189.10' - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 stop '192.168.189.250' - -**Secondary** - -.. 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 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' - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 start '192.168.189.10' - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 stop '192.168.189.250' - - -Raw Parameters -"""""""""""""" - -* Override static-mapping's dns-server with a custom one that will be sent only - to this host. -* An option that takes a quoted string is set by replacing all quote characters - with the string ``"`` inside the static-mapping-parameters value. - The resulting line in dhcpd.conf will be - ``option pxelinux.configfile "pxelinux.cfg/01-00-15-17-44-2d-aa";``. - - -.. code-block:: none - - set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option domain-name-servers 192.0.2.11, 192.0.2.12;" - set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option pxelinux.configfile "pxelinux.cfg/01-00-15-17-44-2d-aa";" - - - -Operation Mode --------------- - -.. opcmd:: restart dhcp server - - Restart the DHCP server - -.. opcmd:: show dhcp server statistics - - Show the DHCP server statistics: - -.. code-block:: none - - vyos@vyos:~$ show dhcp server statistics - Pool Size Leases Available Usage - ----------- ------ -------- ----------- ------- - dhcpexample 99 2 97 2% - -.. opcmd:: show dhcp server statistics pool <pool> - - Show the DHCP server statistics for the specified pool. - -.. opcmd:: show dhcp server leases - - Show statuses of all active leases: - -.. code-block:: none - - vyos@vyos:~$ show dhcp server leases - IP address Hardware address State Lease start Lease expiration Remaining Pool Hostname - -------------- ------------------ ------- ------------------- ------------------- ---------- ----------- --------- - 192.0.2.104 aa:bb:cc:dd:ee:ff active 2019/12/05 14:24:23 2019/12/06 02:24:23 6:05:35 dhcpexample test1 - 192.0.2.115 ab:ac:ad:ae:af:bf active 2019/12/05 18:02:37 2019/12/06 06:02:37 9:43:49 dhcpexample test2 - -.. hint:: Static mappings aren't shown. To show all states, use - ``show dhcp server leases state all``. - -.. opcmd:: show dhcp server leases pool <pool> - - Show only leases in the specified pool. - -.. opcmd:: show dhcp server leases sort <key> - - Sort the output by the specified key. Possible keys: ip, hardware_address, - state, start, end, remaining, pool, hostname (default = ip) - -.. opcmd:: show dhcp server leases state <state> - - Show only leases with the specified state. Possible states: all, active, - free, expired, released, abandoned, reset, backup (default = active) - -DHCPv6 Server -============= - -VyOS also provides DHCPv6 server functionality which is described in this -section. - -Configuration Options ---------------------- - -.. cfgcmd:: set service dhcpv6-server preference <preference value> - - Clients receiving advertise messages from multiple servers choose the server - with the highest preference value. The range for this value is ``0...255``. - -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> lease-time {default | maximum | minimum} - - The default lease time for DHCPv6 leases is 24 hours. This can be changed by - supplying a ``default-time``, ``maximum-time`` and ``minimum-time``. All - values need to be supplied in seconds. - -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> nis-domain <domain-name> - - A :abbr:`NIS (Network Information Service)` domain can be set to be used for - DHCPv6 clients. - -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> nisplus-domain <domain-name> - - The procedure to specify a :abbr:`NIS+ (Network Information Service Plus)` - domain is similar to the NIS domain one: - -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> nis-server <address> - - Specify a NIS server address for DHCPv6 clients. - -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> nisplus-server <address> - - Specify a NIS+ server address for DHCPv6 clients. - -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> sip-server <address | fqdn> - - Specify a :abbr:`SIP (Session Initiation Protocol)` server by IPv6 - address of Fully Qualified Domain Name for all DHCPv6 clients. - -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> sntp-server-address <address> - - A SNTP server address can be specified for DHCPv6 clients. - -Prefix Delegation -^^^^^^^^^^^^^^^^^ - -To hand out individual prefixes to your clients the following configuration is -used: - - -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> prefix-delegation start <address> prefix-length <length> - - Hand out prefixes of size `<length>` to clients in subnet `<prefix>` when - they request for prefix delegation. - -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> prefix-delegation start <address> stop <address> - - Delegate prefixes from the range indicated by the start and stop qualifier. - -Address pools -------------- - -DHCPv6 address pools must be configured for the system to act as a DHCPv6 -server. The following example describes a common scenario. - -**Example:** - -* A shared network named ``NET1`` serves subnet ``2001:db8::/64`` -* It is connected to ``eth1`` -* DNS server is located at ``2001:db8::ffff`` -* Address pool shall be ``2001:db8::100`` through ``2001:db8::199``. -* Lease time will be left at the default value which is 24 hours - -.. code-block:: none - - set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 address-range start 2001:db8::100 stop 2001:db8::199 - set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 name-server 2001:db8::ffff - -The configuration will look as follows: - -.. code-block:: none - - show service dhcpv6-server - shared-network-name NET1 { - subnet 2001:db8::/64 { - address-range { - start 2001:db8::100 { - stop 2001:db8::199 - } - } - name-server 2001:db8::ffff - } - } - -Static mappings -^^^^^^^^^^^^^^^ - -In order to map specific IPv6 addresses to specific hosts static mappings can -be created. The following example explains the process. - -**Example:** - -* IPv6 address ``2001:db8::101`` shall be statically mapped -* Host specific mapping shall be named ``client1`` - -.. hint:: The identifier is the device's DUID: colon-separated hex list (as - used by isc-dhcp option dhcpv6.client-id). If the device already has a - dynamic lease from the DHCPv6 server, its DUID can be found with ``show - service dhcpv6 server leases``. The DUID begins at the 5th octet (after the - 4th colon) of IAID_DUID. - -.. code-block:: none - - set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 ipv6-address 2001:db8::101 - set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 identifier 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff - -The configuration will look as follows: - -.. code-block:: none - - show service dhcp-server shared-network-name NET1 - shared-network-name NET1 { - subnet 2001:db8::/64 { - name-server 2001:db8:111::111 - address-range { - start 2001:db8::100 { - stop 2001:db8::199 { - } - } - static-mapping client1 { - ipv6-address 2001:db8::101 - identifier 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff - } - } - } - -Operation Mode --------------- - -.. opcmd:: restart dhcpv6 server - - To restart the DHCPv6 server - -.. opcmd:: show dhcpv6 server status - - To show the current status of the DHCPv6 server. - -.. opcmd:: show dhcpv6 server leases - - Show statuses of all assigned leases: - -.. code-block:: none - - vyos@vyos:~$ show dhcpv6 server leases - IPv6 address State Last communication Lease expiration Remaining Type Pool IAID_DUID - ------------- ------- -------------------- ------------------- ----------- ------------- ----- -------------------------------------------- - 2001:db8::101 active 2019/12/05 19:40:10 2019/12/06 07:40:10 11:45:21 non-temporary NET1 98:76:54:32:00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff - 2001:db8::102 active 2019/12/05 14:01:23 2019/12/06 02:01:23 6:06:34 non-temporary NET1 87:65:43:21:00:01:00:01:11:22:33:44:fa:fb:fc:fd:fe:ff - -.. hint:: Static mappings aren't shown. To show all states, use ``show dhcp - server leases state all``. - -.. opcmd:: show dhcpv6 server leases pool <pool> - - Show only leases in the specified pool. - -.. opcmd:: show dhcpv6 server leases sort <key> - - Sort the output by the specified key. Possible keys: expires, iaid_duid, ip, - last_comm, pool, remaining, state, type (default = ip) - -.. opcmd:: show dhcpv6 server leases state <state> - - Show only leases with the specified state. Possible states: abandoned, - active, all, backup, expired, free, released, reset (default = active) - -DHCP Relay -========== - -If you want your router to forward DHCP requests to an external DHCP server -you can configure the system to act as a DHCP relay agent. The DHCP relay -agent works with IPv4 and IPv6 addresses. - -All interfaces used for the DHCP relay must be configured. - -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. - -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 - } - -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. - -Operation ---------- - -.. opcmd:: restart dhcp relay-agent - - Restart DHCP relay service - -DHCPv6 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. - -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 - } - -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. - -Operation ---------- - -.. opcmd:: show dhcpv6 relay-agent status - - Show the current status of the DHCPv6 relay agent: - -.. opcmd:: restart dhcpv6 relay-agent - - Restart DHCPv6 relay agent immediately. diff --git a/docs/services/dns-forwarding.rst b/docs/services/dns-forwarding.rst deleted file mode 100644 index 5c154fdf..00000000 --- a/docs/services/dns-forwarding.rst +++ /dev/null @@ -1,147 +0,0 @@ -.. _dns-forwarding: - -############## -DNS Forwarding -############## - -Configuration -============= - -VyOS provides DNS infrastructure for small networks. It is designed to be -lightweight and have a small footprint, suitable for resource constrained -routers and firewalls, for this we utilize PowerDNS recursor. - -The VyOS DNS forwarder does not require an upstream DNS server. It can serve as a -full recursive DNS server - but it can also forward queries to configurable -upstream DNS servers. By not configuring any upstream DNS servers you also -avoid to be tracked by the provider of your upstream DNS server. - -.. cfgcmd:: set service dns forwarding system - - Forward incoming DNS queries to the DNS servers configured under the ``system - name-server`` nodes. - -.. cfgcmd:: set service dns forwarding name-server <address> - - Send all DNS queries to the IPv4/IPv6 DNS server specified under `<address>`. - You can configure multiple nameservers here. - -.. cfgcmd:: set service dns forwarding domain <domain-name> server <address> - - Forward received queries for a particular domain (specified via `domain-name`) - to a given name-server. Multiple nameservers can be specified. You can use - this feature for a DNS split-horizon configuration. - - .. note:: This also works for reverse-lookup zones (``18.172.in-addr.arpa``). - -.. cfgcmd:: set service dns forwarding allow-from <network> - - Given the fact that open DNS recursors could be used on DDOS amplification - attacts, you must configure the networks which are allowed to use this - recursor. A network of ``0.0.0.0/0`` or ``::/0`` would allow all IPv4 and - IPv6 networks to query this server. This is on general a bad idea. - -.. cfgcmd:: set service dns forwarding dnssec <off | process-no-validate | process | log-fail | validate> - - The PowerDNS Recursor has 5 different levels of DNSSEC processing, which can - be set with the dnssec setting. In order from least to most processing, these - are: - - * **off** In this mode, no DNSSEC processing takes place. The recursor will - not set the DNSSEC OK (DO) bit in the outgoing queries and will ignore the - DO and AD bits in queries. - - * **process-no-validate** In this mode the Recursor acts as a "security - aware, non-validating" nameserver, meaning it will set the DO-bit on - outgoing queries and will provide DNSSEC related RRsets (NSEC, RRSIG) to - clients that ask for them (by means of a DO-bit in the query), except for - zones provided through the auth-zones setting. It will not do any - validation in this mode, not even when requested by the client. - - * **process** When dnssec is set to process the behaviour is similar to - process-no-validate. However, the recursor will try to validate the data - if at least one of the DO or AD bits is set in the query; in that case, - it will set the AD-bit in the response when the data is validated - successfully, or send SERVFAIL when the validation comes up bogus. - - * **log-fail** In this mode, the recursor will attempt to validate all data - it retrieves from authoritative servers, regardless of the client's DNSSEC - desires, and will log the validation result. This mode can be used to - determine the extra load and amount of possibly bogus answers before - turning on full-blown validation. Responses to client queries are the same - as with process. - - * **validate** The highest mode of DNSSEC processing. In this mode, all - queries will be validated and will be answered with a SERVFAIL in case of - bogus data, regardless of the client's request. - - .. note:: The famous UNIX/Linux ``dig`` tool sets the AD-bit in the query. - This might lead to unexpected query results when testing. Set ``+noad`` - on the ``dig`` commandline when this is the case. - - .. note:: The ``CD``-bit is honored correctly for process and validate. For - log-fail, failures will be logged too. - -.. cfgcmd:: set service dns forwarding ignore-hosts-file - - Do not use local ``/etc/hosts`` file in name resolution. VyOS DHCP server - will use this file to add resolvers to assigned addresses. - -.. cfgcmd:: set service dns forwarding max-cache-entries - - Maximum number of DNS cache entries. 1 million per CPU core will generally - suffice for most installations. - -.. cfgcmd:: set service dns forwarding negative-ttl - - A query for which there is authoritatively no answer is cached to quickly - deny a record's existence later on, without putting a heavy load on the - remote server. In practice, caches can become saturated with hundreds of - thousands of hosts which are tried only once. This setting, which defaults - to 3600 seconds, puts a maximum on the amount of time negative entries are - cached. - -.. cfgcmd:: set service dns forwarding listen-address - - The local IPv4 or IPv6 addresses to bind the DNS forwarder to. The forwarder will listen on this address for - incoming connections. - -Example -======= - -A VyOS router with two interfaces - eth0 (WAN) and eth1 (LAN) - is required to implement a split-horizon DNS configuration for example.com. - -In this scenario: - -* All DNS requests for example.com must be forwarded to a DNS server at 192.0.2.254 - and 2001:db8:cafe::1 -* All other DNS requests will be forwarded to a different set of DNS servers at 192.0.2.1, - 192.0.2.2, 2001:db8::1:ffff and 2001:db8::2:ffff -* The VyOS DNS forwarder will only listen for requests on the eth1 (LAN) interface addresses - 192.168.1.254 - for IPv4 and 2001:db8::ffff for IPv6 -* The VyOS DNS forwarder will only accept lookup requests from the LAN subnets - 192.168.1.0/24 and 2001:db8::/64 - -.. code-block:: none - - set service dns forwarding domain example.com server 192.0.2.254 - set service dns forwarding domain example.com server 2001:db8:cafe::1 - set service dns forwarding name-server 192.0.2.1 - set service dns forwarding name-server 192.0.2.2 - set service dns forwarding name-server 2001:db8::1:ffff - set service dns forwarding name-server 2001:db8::2:ffff - set service dns forwarding listen-address 192.168.1.254 - set service dns forwarding listen-address 2001:db8::ffff - set service dns forwarding allow-from 192.168.1.0/24 - set service dns forwarding allow-from 2001:db8::/64 - -Operation -========= - -.. opcmd:: reset dns forwarding <all | domain> - - Resets the local DNS forwarding cache database. You can reset the cache for all - entries or only for entries to a specific domain. - -.. opcmd:: restart dns forwarding - - Restarts the DNS recursor process. This also invalidates the local DNS forwarding cache. diff --git a/docs/services/dynamic-dns.rst b/docs/services/dynamic-dns.rst deleted file mode 100644 index 3d802d29..00000000 --- a/docs/services/dynamic-dns.rst +++ /dev/null @@ -1,164 +0,0 @@ -.. _dynamic-dns: - -########### -Dynamic DNS -########### - -VyOS is able to update a remote DNS record when an interface gets a new IP -address. In order to do so, VyOS includes ddclient_, a Perl script written for -this only one purpose. - -ddclient_ uses two methods to update a DNS record. The first one will send -updates directly to the DNS daemon, in compliance with :rfc:`2136`. The second -one involves a third party service, like DynDNS.com or any other similar -website. This method uses HTTP requests to transmit the new IP address. You -can configure both in VyOS. - -Configuration -============= - -:rfc:`2136` Based ------------------ - -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> - - Create new :rfc:`2136` DNS update configuration which will update the IP - address assigned to `<interface>` on the service you configured under - `<service-name>`. - -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> key <keyfile> - - File identified by `<keyfile>` containing the secret RNDC key shared with - remote DNS server. - -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> server <server> - - Configure the DNS `<server>` IP/FQDN used when updating this dynamic - assignment. - -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> zone <zone> - - Configure DNS `<zone>` to be updated. - -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> record <record> - - Configure DNS `<record>` which should be updated. This can be set multiple - times. - -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> ttl <ttl> - - Configure optional TTL value on the given resource record. This defualts to - 600 seconds. - -Example -^^^^^^^ - -* Register DNS record ``example.vyos.io`` on DNS server ``ns1.vyos.io`` -* Use auth key file at ``/config/auth/my.key`` -* Set TTL to 300 seconds - -.. code-block:: none - - vyos@vyos# show service dns dynamic - interface eth0.7 { - rfc2136 VyOS-DNS { - key /config/auth/my.key - record example.vyos.io - server ns1.vyos.io - ttl 300 - zone vyos.io - } - } - -This will render the following ddclient_ configuration entry: - -.. code-block:: none - - # - # ddclient configuration for interface "eth0.7": - # - use=if, if=eth0.7 - - # RFC2136 dynamic DNS configuration for example.vyos.io.vyos.io - server=ns1.vyos.io - protocol=nsupdate - password=/config/auth/my.key - ttl=300 - zone=vyos.io - example.vyos.io - -.. note:: You can also keep different DNS zone updated. Just create a new - config node: ``set service dns dynamic interface <interface> rfc2136 - <other-service-name>`` - -HTTP based services -------------------- - -VyOS is also able to use any service relying on protocols supported by ddclient. - -To use such a service, one must define a login, password, one or multiple -hostnames, protocol and server. - -.. cfgcmd:: set service dns dynamic interface <interface> service <service> host-name <hostname> - - Setup the dynamic DNS hostname `<hostname>` associated with the DynDNS - provider identified by `<service>` when the IP address on interface - `<interface>` changes. - -.. cfgcmd:: set service dns dynamic interface <interface> service <service> login <username> - - Configure `<username>` used when authenticating the update request for - DynDNS service identified by `<service>`. - For Namecheap, set the <domain> you wish to update. - -.. cfgcmd:: set service dns dynamic interface <interface> service <service> password <password> - - Configure `<password>` used when authenticating the update request for - DynDNS service identified by `<service>`. - -.. cfgcmd:: set service dns dynamic interface <interface> service <service> protocol <protocol> - - When a ``custom`` DynDNS provider is used the protocol used for communicating - to the provider must be specified under `<protocol>`. See the embedded - completion helper for available protocols. - -.. cfgcmd:: set service dns dynamic interface <interface> service <service> server <server> - - When a ``custom`` DynDNS provider is used the `<server>` where update - requests are being sent to must be specified. - -Example: -^^^^^^^^ - -Use DynDNS as your preferred provider: - -.. code-block:: none - - set service dns dynamic interface eth0 service dyndns - set service dns dynamic interface eth0 service dyndns login my-login - set service dns dynamic interface eth0 service dyndns password my-password - set service dns dynamic interface eth0 service dyndns host-name my-dyndns-hostname - -.. note:: Multiple services can be used per interface. Just specify as many - serives per interface as you like! - -Running Behind NAT ------------------- - -By default, ddclient_ will update a dynamic dns record using the IP address -directly attached to the interface. If your VyOS instance is behind NAT, your -record will be updated to point to your internal IP. - -ddclient_ has another way to determine the WAN IP address. This is controlled -by: - -.. cfgcmd:: set service dns dynamic interface <interface> use-web url <url> - - Use configured `<url>` to determine your IP address. ddclient_ will load - `<url>` and tries to extract your IP address from the response. - -.. cfgcmd:: set service dns dynamic interface <interface> use-web skip <pattern> - - ddclient_ will skip any address located before the string set in `<pattern>`. - -.. _ddclient: https://github.com/ddclient/ddclient diff --git a/docs/services/index.rst b/docs/services/index.rst deleted file mode 100644 index 76520b52..00000000 --- a/docs/services/index.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. _services: - -######## -Services -######## - -This chapter describes the available system/network services provided by VyOS. - -.. toctree:: - :maxdepth: 1 - - conntrack - console-server - dhcp - dns-forwarding - dynamic-dns - lldp - mdns-repeater - ipoe-server - pppoe-server - udp-broadcast-relay - router-advert - snmp - ssh - tftp - webproxy diff --git a/docs/services/ipoe-server.rst b/docs/services/ipoe-server.rst deleted file mode 100644 index 279f0c6d..00000000 --- a/docs/services/ipoe-server.rst +++ /dev/null @@ -1,149 +0,0 @@ -.. include:: /_include/need_improvement.txt - -.. _ipoe_server: - -########### -IPoE Server -########### - -VyOS utilizes `accel-ppp`_ to provide :abbr:`IPoE (Internet Protocol over -Ethernet)` server functionality. It can be used with local authentication -(mac-address) or a connected RADIUS server. - -IPoE is a method of delivering an IP payload over an Ethernet-based access -network or an access network using bridged Ethernet over Asynchronous Transfer -Mode (ATM) without using PPPoE. It directly encapsulates the IP datagrams in -Ethernet frames, using the standard :rfc:`894` encapsulation. - -The use of IPoE addresses the disadvantage that PPP is unsuited for multicast -delivery to multiple users. Typically, IPoE uses Dynamic Host Configuration -Protocol and Extensible Authentication Protocol to provide the same -functionality as PPPoE, but in a less robust manner. - -.. note:: Please be aware, due to an upstream bug, config changes/commits - will restart the ppp daemon and will reset existing IPoE sessions, - in order to become effective. - -Configuration -============= - -IPoE can be configure on different interfaces, it will depend on each specific -situation which interface will provide IPoE to clients. The clients mac address -and the incoming interface is being used as control parameter, to authenticate -a client. - -The example configuration below will assign an IP to the client on the incoming -interface eth2 with the client mac address 08:00:27:2f:d8:06. Other DHCP -discovery requests will be ignored, unless the client mac has been enabled in -the configuration. - -.. code-block:: none - - set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 - set service ipoe-server authentication mode 'local' - set service ipoe-server dns-server server-1 '8.8.8.8' - set service ipoe-server dns-server server-2 '8.8.4.4' - set service ipoe-server interface eth2 client-subnet '192.168.0.0/24' - - -The first address of the parameter ``client-subnet``, will be used as the -default gateway. Connected sessions can be checked via the ``show ipoe-server -sessions`` command. - -.. code-block:: none - - vyos@vyos:~$ show ipoe-server sessions - - ifname | called-sid | calling-sid | ip | ip6 | ip6-dp | rate-limit | state | uptime | sid - -------+------------+-------------------+-------------+-----+--------+------------+--------+----------+------------------ - ipoe0 | eth2 | 08:00:27:2f:d8:06 | 192.168.0.2 | | | | active | 00:45:05 | dccc870fd3134612 - - -IPv6 SLAAC and IA-PD --------------------- - -To configure IPv6 assignments for clients, two options need to be configured. -A global prefix which is terminated on the clients cpe and a delegated prefix, -the client can use for devices routed via the clients cpe. - -IPv6 DNS addresses are optional. - -.. code-block:: none - - set service ipoe-server authentication interface eth3 mac-address 08:00:27:2F:D8:06 - set service ipoe-server authentication mode 'local' - set service ipoe-server client-ipv6-pool delegate-prefix '2001:db8:1::/48,56' - set service ipoe-server client-ipv6-pool prefix '2001:db8::/48,64' - set service ipoe-server dnsv6-server server-1 '2001:db8::' - set service ipoe-server dnsv6-server server-2 '2001:db8:aaa::' - set service ipoe-server dnsv6-server server-3 '2001:db8:bbb::' - set service ipoe-server interface eth3 client-subnet '192.168.1.0/24' - -.. code-block:: none - - vyos@ipoe-server# run sh ipoe-server sessions - ifname | called-sid | calling-sid | ip | ip6 | ip6-dp | rate-limit | state | uptime | sid - -------+------------+-------------------+-------------+---------------------------------+-----------------+------------+--------+----------+------------------ - ipoe0 | eth3 | 08:00:27:2f:d8:06 | 192.168.1.2 | 2001:db8::a00:27ff:fe2f:d806/64 | 2001:db8:1::/56 | | active | 01:02:59 | 4626faf71b12cc25 - - -The clients :abbr:`CPE (Customer Premises Equipment)` can now communicate via -IPv4 or IPv6. All devices behind ``2001:db8::a00:27ff:fe2f:d806/64`` can use -addresses from ``2001:db8:1::/56`` and can globally communicate without the -need of any NAT rules. - -Automatic VLAN creation ------------------------ - -To create VLANs per user during runtime, the following settings are required on -a per interface basis. VLAN ID and VLAN range can be present in the -configuration at the same time. - -.. code-block:: none - - set service ipoe-server interface eth2 network vlan - set service ipoe-server interface eth2 vlan-id 100 - set service ipoe-server interface eth2 vlan-id 200 - set service ipoe-server interface eth2 vlan-range 1000-2000 - set service ipoe-server interface eth2 vlan-range 2500-2700 - -RADIUS Setup ------------- - -To use a RADIUS server for authentication and bandwidth-shaping, the following -example configuration can be used. - -.. code-block:: none - - set service ipoe-server authentication mode 'radius' - set service ipoe-server authentication radius-server 10.100.100.1 secret 'password' - -Bandwidth Shaping -================= - -Bandwidth rate limits can be set for local users within the configuration or -via RADIUS based attributes. - -Bandwidth Shaping for local users ---------------------------------- - -The rate-limit is set in kbit/sec. - -.. code-block:: none - - set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 rate-limit download '500' - set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 rate-limit upload '500' - set service ipoe-server authentication mode 'local' - set service ipoe-server dns-server server-1 '8.8.8.8' - set service ipoe-server dns-server server-2 '8.8.4.4' - set service ipoe-server interface eth2 client-subnet '192.168.0.0/24' - -.. code-block:: none - - vyos@vyos# run show ipoe-server sessions - - ifname | called-sid | calling-sid | ip | ip6 | ip6-dp | rate-limit | state | uptime | sid - -------+------------+-------------------+-------------+-----+--------+------------+--------+----------+------------------ - ipoe0 | eth2 | 08:00:27:2f:d8:06 | 192.168.0.2 | | | 500/500 | active | 00:00:05 | dccc870fd31349fb - -.. include:: /common-references.rst diff --git a/docs/services/lldp.rst b/docs/services/lldp.rst deleted file mode 100644 index 4b1743e6..00000000 --- a/docs/services/lldp.rst +++ /dev/null @@ -1,141 +0,0 @@ -.. _lldp: - -#### -LLDP -#### - -:abbr:`LLDP (Link Layer Discovery Protocol)` is a vendor-neutral link layer -protocol in the Internet Protocol Suite used by network devices for advertising -their identity, capabilities, and neighbors on an IEEE 802 local area network, -principally wired Ethernet. The protocol is formally referred to by the IEEE -as Station and Media Access Control Connectivity Discovery specified in IEEE -802.1AB and IEEE 802.3-2012 section 6 clause 79. - -LLDP performs functions similar to several proprietary protocols, such as -:abbr:`CDP (Cisco Discovery Protocol)`, :abbr:`FDP (Foundry Discovery Protocol)`, -:abbr:`NDP (Nortel Discovery Protocol)` and :abbr:`LLTD (Link Layer Topology -Discovery)`. - -Information gathered with LLDP is stored in the device as a :abbr:`MIB -(Management Information Database)` and can be queried with :abbr:`SNMP (Simple -Network Management Protocol)` as specified in :rfc:`2922`. The topology of an -LLDP-enabled network can be discovered by crawling the hosts and querying this -database. Information that may be retrieved include: - -* System Name and Description -* Port name and description -* VLAN name -* IP management address -* System capabilities (switching, routing, etc.) -* MAC/PHY information -* MDI power -* Link aggregation - -Configuration -============= - -.. cfgcmd:: set service lldp - - Enable LLDP service - -.. cfgcmd:: set service lldp management-address <address> - - Define IPv4/IPv6 management address transmitted via LLDP. Multiple addresses - can be defined. Only addresses connected to the system will be transmitted. - -.. cfgcmd:: set service lldp interface <interface> - - Enable transmission of LLDP information on given `<interface>`. You can also - say ``all`` here so LLDP is turned on on every interface. - -.. cfgcmd:: set service lldp interface <interface> 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/services/mdns-repeater.rst b/docs/services/mdns-repeater.rst deleted file mode 100644 index 9d6a292a..00000000 --- a/docs/services/mdns-repeater.rst +++ /dev/null @@ -1,44 +0,0 @@ -mDNS Repeater -------------- - -Starting with VyOS 1.2 a :abbr:`mDNS (Multicast DNS)` repeater functionality is -provided. Additional information can be obtained from -https://en.wikipedia.org/wiki/Multicast_DNS. - -Multicast DNS uses the 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/services/pppoe-server.rst b/docs/services/pppoe-server.rst deleted file mode 100644 index 4deb6c7e..00000000 --- a/docs/services/pppoe-server.rst +++ /dev/null @@ -1,397 +0,0 @@ -.. _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 local-ip <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 local-ip -'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 local-ip '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 local-ip '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 local-ip '10.1.1.2' - set service pppoe-server name-server '10.100.100.1' - set service pppoe-server name-server '10.100.200.1' - - - -Dual-Stack IPv4/IPv6 provisioning with Prefix Delegation --------------------------------------------------------- - -The example below covers a dual-stack configuration via pppoe-server. - -.. code-block:: none - - set service pppoe-server authentication local-users username test password 'test' - set service pppoe-server authentication mode 'local' - set service pppoe-server client-ip-pool start '192.168.0.1' - set service pppoe-server client-ip-pool stop '192.168.0.10' - set service pppoe-server client-ipv6-pool delegate '2001:db8:8003::/48' delegation-prefix '56' - set service pppoe-server client-ipv6-pool prefix '2001:db8:8002::/48' mask '64' - set service pppoe-server name-server '8.8.8.8' - set service pppoe-server name-server '2001:4860:4860::8888' - set service pppoe-server interface 'eth2' - set service pppoe-server local-ip '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:: /common-references.rst diff --git a/docs/services/router-advert.rst b/docs/services/router-advert.rst deleted file mode 100644 index bc92f315..00000000 --- a/docs/services/router-advert.rst +++ /dev/null @@ -1,89 +0,0 @@ -.. _router-advert: - -##################### -Router Advertisements -##################### - -:abbr:`RAs (Router advertisements)` are described in :rfc:`4861#section-4.6.2`. -They are part of what is known as :abbr:`SLAAC (Stateless Address -Autoconfiguration)`. - - -Supported interface types: - - * bonding - * bridge - * ethernet - * l2tpv3 - * openvpn - * pseudo-ethernet - * tunnel - * vxlan - * wireguard - * wireless - * wirelessmodem - - -Enabling Advertisments -~~~~~~~~~~~~~~~~~~~~~~~ - -.. cfgcmd:: set service router-advert interface <interface> .... - -.. csv-table:: - :header: "Field", "VyOS Option", "Description" - :widths: 10, 10, 20 - - "Cur Hop Limit", "hop-limit", "Hop count field of the outgoing RA packets" - """Managed address configuration"" flag", "managed-flag", "Tell hosts to use the administered stateful protocol (i.e. DHCP) for autoconfiguration" - """Other configuration"" flag", "other-config-flag", "Tell hosts to use the administered (stateful) protocol (i.e. DHCP) for autoconfiguration of other (non-address) information" - "MTU","link-mtu","Link MTU value placed in RAs, exluded in RAs if unset" - "Router Lifetime","default-lifetime","Lifetime associated with the default router in units of seconds" - "Reachable Time","reachable-time","Time, in milliseconds, that a node assumes a neighbor is reachable after having received a reachability confirmation" - "Retransmit Timer","retrans-timer","Time in milliseconds between retransmitted Neighbor Solicitation messages" - "Default Router Preference","default-preference","Preference associated with the default router" - "Interval", "interval", "Min and max intervals between unsolicited multicast RAs" - "DNSSL", "dnssl", "DNS search list to advertise" - "Name Server", "name-server", "Advertise DNS server per https://tools.ietf.org/html/rfc6106" - -Advertising a Prefix -'''''''''''''''''''' - -.. cfgcmd:: set service router-advert interface <interface> prefix 2001:DB8::/32 - -.. csv-table:: - :header: "VyOS Field", "Description" - :widths: 10,30 - - "no-autonomous-flag","Prefix can not be used for stateless address auto-configuration" - "no-on-link-flag","Prefix can not be used for on-link determination" - "preferred-lifetime","Time in seconds that the prefix will remain preferred (default 4 hours)" - "valid-lifetime","Time in seconds that the prefix will remain valid (default: 30 days)" - - -Disabling Advertisements -~~~~~~~~~~~~~~~~~~~~~~~~ - -To disable advertisements without deleting the configuration: - -.. cfgcmd:: set service router-advert interface <interface> no-send-advert - -Example Configuration -~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: none - - interface eth0.2 { - default-preference high - hop-limit 64 - interval { - max 600 - } - name-server 2001:4860:4860::8888 - name-server 2001:4860:4860::8844 - other-config-flag - prefix 2001:DB8:beef:2::/64 { - valid-lifetime 2592000 - } - reachable-time 0 - retrans-timer 0 - } diff --git a/docs/services/snmp.rst b/docs/services/snmp.rst deleted file mode 100644 index 3f445ea8..00000000 --- a/docs/services/snmp.rst +++ /dev/null @@ -1,266 +0,0 @@ -.. _snmp: - -#### -SNMP -#### - -:abbr:`SNMP (Simple Network Management Protocol)` is an Internet Standard -protocol for collecting and organizing information about managed devices on -IP networks and for modifying that information to change device behavior. -Devices that typically support SNMP include cable modems, routers, switches, -servers, workstations, printers, and more. - -SNMP is widely used in network management for network monitoring. SNMP exposes -management data in the form of variables on the managed systems organized in -a management information base (MIB_) which describe the system status and -configuration. These variables can then be remotely queried (and, in some -circumstances, manipulated) by managing applications. - -Three significant versions of SNMP have been developed and deployed. SNMPv1 is -the original version of the protocol. More recent versions, SNMPv2c and SNMPv3, -feature improvements in performance, flexibility and security. - -SNMP is a component of the Internet Protocol Suite as defined by the Internet -Engineering Task Force (IETF). It consists of a set of standards for network -management, including an application layer protocol, a database schema, and a -set of data objects. - -Overview and basic concepts -=========================== - -In typical uses of SNMP, one or more administrative computers called managers -have the task of monitoring or managing a group of hosts or devices on a -computer network. Each managed system executes a software component called an -agent which reports information via SNMP to the manager. - -An SNMP-managed network consists of three key components: - -* Managed devices -* Agent - software which runs on managed devices -* Network management station (NMS) - software which runs on the manager - -A managed device is a network node that implements an SNMP interface that -allows unidirectional (read-only) or bidirectional (read and write) access to -node-specific information. Managed devices exchange node-specific information -with the NMSs. Sometimes called network elements, the managed devices can be -any type of device, including, but not limited to, routers, access servers, -switches, cable modems, bridges, hubs, IP telephones, IP video cameras, -computer hosts, and printers. - -An agent is a network-management software module that resides on a managed -device. An agent has local knowledge of management information and translates -that information to or from an SNMP-specific form. - -A network management station executes applications that monitor and control -managed devices. NMSs provide the bulk of the processing and memory resources -required for network management. One or more NMSs may exist on any managed -network. - -.. figure:: /_static/images/service_snmp_communication_principles_diagram.png - :scale: 20 % - :alt: Principle of SNMP Communication - - Image thankfully borrowed from - https://en.wikipedia.org/wiki/File:SNMP_communication_principles_diagram.PNG - which is under the GNU Free Documentation License - -.. note:: VyOS SNMP supports both IPv4 and IPv6. - -SNMP Protocol Versions -====================== - -VyOS itself supports SNMPv2_ (version 2) and SNMPv3_ (version 3) where the -later is recommended because of improved security (optional authentication and -encryption). - -SNMPv2 ------- - -SNMPv2 is the original and most commonly used version. For authorizing clients, -SNMP uses the concept of communities. Communities may have authorization set -to read only (this is most common) or to read and write (this option is not -actively used in VyOS). - -SNMP can work synchronously or asynchronously. In synchronous communication, -the monitoring system queries the router periodically. In asynchronous, the -router sends notification to the "trap" (the monitoring host). - -SNMPv2 does not support any authentication mechanisms, other than client source -address, so you should specify addresses of clients allowed to monitor the -router. Note that SNMPv2 also supports no encryption and always sends data in -plain text. - -Example -^^^^^^^ - -.. code-block:: none - - # Define a community - set service snmp community routers authorization ro - - # Allow monitoring access from the entire network - set service snmp community routers network 192.0.2.0/24 - set service snmp community routers network 2001::db8:ffff:eeee::/64 - - # Allow monitoring access from specific addresses - set service snmp community routers client 203.0.113.10 - set service snmp community routers client 203.0.113.20 - - # Define optional router information - set service snmp location "UK, London" - set service snmp contact "admin@example.com" - - # Trap target if you want asynchronous communication - set service snmp trap-target 203.0.113.10 - - # Listen only on specific IP addresses (port defaults to 161) - set service snmp listen-address 172.16.254.36 port 161 - set service snmp listen-address 2001:db8::f00::1 - - -SNMPv3 ------- - -SNMPv3 (version 3 of the SNMP protocol) introduced a whole slew of new security -related features that have been missing from the previous versions. Security -was one of the biggest weakness of SNMP until v3. Authentication in SNMP -Versions 1 and 2 amounts to nothing more than a password (community string) -sent in clear text between a manager and agent. Each SNMPv3 message contains -security parameters which are encoded as an octet string. The meaning of these -security parameters depends on the security model being used. - -The securityapproach in v3 targets: - -* Confidentiality – Encryption of packets to prevent snooping by an - unauthorized source. - -* Integrity – Message integrity to ensure that a packet has not been tampered - while in transit including an optional packet replay protection mechanism. - -* Authentication – to verify that the message is from a valid source. - -Example -^^^^^^^ - -* Let SNMP daemon listen only on IP address 192.0.2.1 -* Configure new SNMP user named "vyos" with password "vyos12345678" -* New user will use SHA/AES for authentication and privacy - -.. code-block:: none - - set service snmp listen-address 192.0.2.1 - set service snmp location 'VyOS Datacenter' - set service snmp v3 engineid '000000000000000000000002' - set service snmp v3 group default mode 'ro' - set service snmp v3 group default view 'default' - set service snmp v3 user vyos auth plaintext-password 'vyos12345678' - set service snmp v3 user vyos auth type 'sha' - set service snmp v3 user vyos group 'default' - set service snmp v3 user vyos privacy plaintext-password 'vyos12345678' - set service snmp v3 user vyos privacy type 'aes' - set service snmp v3 view default oid 1 - -After commit the plaintext passwords will be hashed and stored in your -configuration. The resulting LCI config will look like: - -.. code-block:: none - - vyos@vyos# show service snmp - listen-address 172.18.254.201 { - } - location "Wuerzburg, Dr.-Georg-Fuchs-Str. 8" - v3 { - engineid 000000000000000000000002 - group default { - mode ro - view default - } - user vyos { - auth { - encrypted-password 4e52fe55fd011c9c51ae2c65f4b78ca93dcafdfe - type sha - } - group default - privacy { - encrypted-password 4e52fe55fd011c9c51ae2c65f4b78ca93dcafdfe - type aes - } - } - view default { - oid 1 { - } - } - } - -You can test the SNMPv3 functionality from any linux based system, just run the -following command: ``snmpwalk -v 3 -u vyos -a SHA -A vyos12345678 -x AES --X vyos12345678 -l authPriv 192.0.2.1 .1`` - -VyOS MIBs -========= - -All SNMP MIBs are located in each image of VyOS here: ``/usr/share/snmp/mibs/`` - -you are be able to download the files with the a activate ssh service like this - -.. code-block:: none - - scp -r vyos@your_router:/usr/share/snmp/mibs /your_folder/mibs - -SNMP Extensions -=============== - -To extend SNMP agent functionality, custom scripts can be executed every time -the agent is being called. This can be achieved by using -``arbitrary extensioncommands``. The first step is to create a functional -script of course, then upload it to your VyOS instance via the command -``scp your_script.sh vyos@your_router:/config/user-data``. -Once the script is uploaded, it needs to be configured via the command below. - - -.. code-block:: none - - set service snmp script-extensions extension-name my-extension script your_script.sh - commit - - -The OID ``.1.3.6.1.4.1.8072.1.3.2.3.1.1.4.116.101.115.116``, once called, will -contain the output of the extension. - -.. code-block:: none - - root@vyos:/home/vyos# snmpwalk -v2c -c public 127.0.0.1 nsExtendOutput1 - NET-SNMP-EXTEND-MIB::nsExtendOutput1Line."my-extension" = STRING: hello - NET-SNMP-EXTEND-MIB::nsExtendOutputFull."my-extension" = STRING: hello - NET-SNMP-EXTEND-MIB::nsExtendOutNumLines."my-extension" = INTEGER: 1 - NET-SNMP-EXTEND-MIB::nsExtendResult."my-extension" = INTEGER: 0 - -SolarWinds -========== - -If you happen to use SolarWinds Orion as NMS you can also use the Device -Templates Management. A template for VyOS can be easily imported. - -Create a file named ``VyOS-1.3.6.1.4.1.44641.ConfigMgmt-Commands`` using the -following content: - -.. code-block:: none - - <Configuration-Management Device="VyOS" SystemOID="1.3.6.1.4.1.44641"> - <Commands> - <Command Name="Reset" Value="set terminal width 0${CRLF}set terminal length 0"/> - <Command Name="Reboot" Value="reboot${CRLF}Yes"/> - <Command Name="EnterConfigMode" Value="configure"/> - <Command Name="ExitConfigMode" Value="commit${CRLF}exit"/> - <Command Name="DownloadConfig" Value="show configuration commands"/> - <Command Name="SaveConfig" Value="commit${CRLF}save"/> - <Command Name="Version" Value="show version"/> - <Command Name="MenuBased" Value="False"/> - <Command Name="VirtualPrompt" Value=":~"/> - </Commands> - </Configuration-Management> - -.. _MIB: https://en.wikipedia.org/wiki/Management_information_base -.. _SNMPv2: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2 -.. _SNMPv3: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_3 - diff --git a/docs/services/ssh.rst b/docs/services/ssh.rst deleted file mode 100644 index 6da8560f..00000000 --- a/docs/services/ssh.rst +++ /dev/null @@ -1,106 +0,0 @@ -.. _ssh: - -### -SSH -### - -:abbr:`SSH (Secure Shell)` is a cryptographic network protocol for operating -network services securely over an unsecured network. The standard TCP port for -SSH is 22. The best known example application is for remote login to computer -systems by users. - -SSH provides a secure channel over an unsecured network in a client-server -architecture, connecting an SSH client application with an SSH server. Common -applications include remote command-line login and remote command execution, -but any network service can be secured with SSH. The protocol specification -distinguishes between two major versions, referred to as SSH-1 and SSH-2. - -The most visible application of the protocol is for access to shell accounts -on Unix-like operating systems, but it sees some limited use on Windows as -well. In 2015, Microsoft announced that they would include native support for -SSH in a future release. - -SSH was designed as a replacement for Telnet and for unsecured remote shell -protocols such as the Berkeley rlogin, rsh, and rexec protocols. -Those protocols send information, notably passwords, in plaintext, -rendering them susceptible to interception and disclosure using packet -analysis. The encryption used by SSH is intended to provide confidentiality -and integrity of data over an unsecured network, such as the Internet. - -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. You can -choose from the following 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. 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`` - -.. note:: VyOS 1.1 supported login as user ``root``. This has been removed due - to tighter security in VyOS 1.2. - -.. 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. -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. - -.. seealso:: SSH :ref:`ssh_key_based_authentication` diff --git a/docs/services/tftp.rst b/docs/services/tftp.rst deleted file mode 100644 index 276ce5fb..00000000 --- a/docs/services/tftp.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. _tftp-server: - -########### -TFTP Server -########### - -:abbr:`TFTP (Trivial File Transfer Protocol)` is a simple, lockstep file -transfer protocol which allows a client to get a file from or put a file onto -a remote host. One of its primary uses is in the early stages of nodes booting -from a local area network. TFTP has been used for this application because it -is very simple to implement. - -Configuration -============= - -.. cfgcmd:: set service tftp-server directory <directory> - -Enable TFTP service by specifying the `<directory>` which will be used to serve -files. - -.. hint:: Choose your ``directory`` location carefully or you will loose the - content on image upgrades. Any directory under ``/config`` is save at this - will be migrated. - -.. cfgcmd:: set service tftp-server listen-address <address> - -Configure the IPv4 or IPv6 listen address of the TFTP server. Multiple IPv4 and -IPv6 addresses can be given. There will be one TFTP server instances listening -on each IP address. - -.. 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/services/udp-broadcast-relay.rst b/docs/services/udp-broadcast-relay.rst deleted file mode 100644 index df48bfd6..00000000 --- a/docs/services/udp-broadcast-relay.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. _udp_broadcast_relay: - -################### -UDP Broadcast Relay -################### - -Certain vendors use broadcasts to identify their equipment within one ethernet -segment. Unfortunately if you split your network with multiple VLANs you loose -the ability of identifying your equipment. - -This is where "UDP broadcast relay" comes into play! It will forward received -broadcasts to other configured networks. - -Every UDP port which will be forward requires one unique ID. Currently we -support 99 IDs! - -Configuration -------------- - -.. cfgcmd:: set service broadcast-relay id <n> description <description> - - A description can be added for each and every unique relay ID. This is - useful to distinguish between multiple different ports/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/services/webproxy.rst b/docs/services/webproxy.rst deleted file mode 100644 index 654e73f2..00000000 --- a/docs/services/webproxy.rst +++ /dev/null @@ -1,153 +0,0 @@ -Webproxy --------- - -The proxy service in VyOS is based on Squid3 and some related modules. - -Squid3_ is a caching and forwarding HTTP web proxy. It has a wide variety of -uses, including speeding up a web server by caching repeated requests, -caching web, DNS and other computer network lookups for a group of people -sharing network resources, and aiding security by filtering traffic. Although -primarily used for HTTP and FTP, Squid includes limited support for several -other protocols including Internet Gopher, SSL,[6] TLS and HTTPS. Squid does -not support the SOCKS protocol. - -All examples here assumes that your inside ip address is ``192.168.0.1``. -Replace with your own where applicable. - -URL Filtering is provided by Squidguard_. - -Configuration -^^^^^^^^^^^^^^ - -.. code-block:: none - - # Enable proxy service - set service webproxy listen-address 192.168.0.1 - - # By default it will listen to port 3128. If you want something else you have to define that. - set service webproxy listen-address 192.168.0.1 port 2050 - - # By default the transparent proxy on that interface is enabled. To disable that you simply - set service webproxy listen-address 192.168.0.1 disable-transparent - - # Block specific urls - set service webproxy url-filtering squidguard local-block myspace.com - - # If you want to you can log these blocks - set service webproxy url-filtering squidguard log local-block - - -Options -******* - -Filtering by category -^^^^^^^^^^^^^^^^^^^^^ - -If you want to use existing blacklists you have to create/download a database -first. Otherwise you will not be able to commit the config changes. - -.. code-block:: none - - vyos@vyos# commit - [ service webproxy ] - Warning: no blacklists installed - Unknown block-category [ads] for policy [default] - - [[service webproxy]] failed - Commit failed - -* Download/Update complete blacklist - - :code:`update webproxy blacklists` - -* Download/Update partial blacklist - - :code:`update webproxy blacklists category ads` - - Use tab completion to get a list of categories. - -* To auto update the blacklist files - - :code:`set service webproxy url-filtering squidguard auto-update update-hour 23` - -* To configure blocking add the following to the configuration - - :code:`set service webproxy url-filtering squidguard block-category ads` - - :code:`set service webproxy url-filtering squidguard block-category malware` - -Authentication -^^^^^^^^^^^^^^ - -The embedded Squid proxy can use LDAP to authenticate users against a company -wide directory. The following configuration is an example of how to use Active -Directory as authentication backend. Queries are done via LDAP. - -.. code-block:: none - - vyos@vyos# show service webproxy - authentication { - children 5 - credentials-ttl 60 - ldap { - base-dn DC=example,DC=local - bind-dn CN=proxyuser,CN=Users,DC=example,DC=local - filter-expression (cn=%s) - password Qwert1234 - server ldap.example.local - username-attribute cn - } - method ldap - realm "VyOS Webproxy" - } - cache-size 100 - default-port 3128 - listen-address 192.168.188.103 { - disable-transparent - } - -* ``base-dn`` set the base directory for the search -* ``bind-dn`` and ``password``: set the user, which is used for the ldap search -* ``filter-expression``: set the exact filter which a authorized user match in a ldap-search. In this example every User is able to authorized. - -You can find more about the ldap authentication `here <http://www.squid-cache.org/Versions/v3/3.2/manuals/basic_ldap_auth.html>`_ - -Adjusting cache size -^^^^^^^^^^^^^^^^^^^^ - -The size of the proxy cache can be adjusted by the user. - -.. code-block:: none - - set service webproxy cache-size - Possible completions: - <0-4294967295> - Disk cache size in MB (default 100) - 0 Disable disk caching - 100 - -Bypassing the webproxy -^^^^^^^^^^^^^^^^^^^^^^ - -Some services don't work correctly when being handled via a web proxy. -So sometimes it is useful to bypass a transparent proxy: - -* To bypass the proxy for every request that is directed to a specific - destination: - - :code:`set service webproxy whitelist destination-address 198.51.100.33` - - :code:`set service webproxy whitelist destination-address 192.0.2.0/24` - - -* To bypass the proxy for every request that is coming from a specific source: - - :code:`set service webproxy whitelist source-address 192.168.1.2` - - :code:`set service webproxy whitelist source-address 192.168.2.0/24` - - (This can be useful when a called service has many and/or often changing - destination addresses - e.g. Netflix.) - -.. _Squid3: http://www.squid-cache.org/ -.. _Squidguard: http://www.squidguard.org/ |