diff options
Diffstat (limited to 'docs/services')
| -rw-r--r-- | docs/services/conntrack.rst | 178 | ||||
| -rw-r--r-- | docs/services/dhcp-relay.rst | 165 | ||||
| -rw-r--r-- | docs/services/dhcp.rst | 138 | ||||
| -rw-r--r-- | docs/services/dhcpv6.rst | 305 | ||||
| -rw-r--r-- | docs/services/dns-forwarding.rst | 72 | ||||
| -rw-r--r-- | docs/services/dynamic-dns.rst | 152 | ||||
| -rw-r--r-- | docs/services/index.rst | 27 | ||||
| -rw-r--r-- | docs/services/ipoe-server.rst | 129 | ||||
| -rw-r--r-- | docs/services/lldp.rst | 97 | ||||
| -rw-r--r-- | docs/services/mdns-repeater.rst | 30 | ||||
| -rw-r--r-- | docs/services/pppoe-server.rst | 217 | ||||
| -rw-r--r-- | docs/services/references.rst | 15 | ||||
| -rw-r--r-- | docs/services/snmp.rst | 245 | ||||
| -rw-r--r-- | docs/services/ssh.rst | 150 | ||||
| -rw-r--r-- | docs/services/tftp.rst | 42 | ||||
| -rw-r--r-- | docs/services/udp-broadcast-relay.rst | 53 | ||||
| -rw-r--r-- | docs/services/webproxy.rst | 152 |
17 files changed, 0 insertions, 2167 deletions
diff --git a/docs/services/conntrack.rst b/docs/services/conntrack.rst deleted file mode 100644 index 28f16d54..00000000 --- a/docs/services/conntrack.rst +++ /dev/null @@ -1,178 +0,0 @@ -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. - -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> - - # Queue size for syncing conntrack entries (in MB) - set service conntrack-sync sync-queue-size <size> - -Example -^^^^^^^ -The next exemple 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' # Or VRRP - set service conntrack-sync interface 'eth0' - set service conntrack-sync mcast-group '225.0.0.50' - set service conntrack-sync sync-queue-size '8' - -On the active router, you should have informations 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: - - - $ 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/dhcp-relay.rst b/docs/services/dhcp-relay.rst deleted file mode 100644 index 0b838442..00000000 --- a/docs/services/dhcp-relay.rst +++ /dev/null @@ -1,165 +0,0 @@ - - -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. See -https://wiki.vyos.net/wiki/Network_address_setup. - -DHCP relay example -^^^^^^^^^^^^^^^^^^ - -.. figure:: /_static/images/service_dhcp-relay01.png - :scale: 80 % - :alt: DHCP relay example - - DHCP relay example - -In this example the interfaces used for the DHCP relay are eth1 and eth2. The -router receives DHCP client requests on eth1 and relays them through eth2 to -the DHCP server at 10.0.1.4. - -Configuration -^^^^^^^^^^^^^ - -Enable DHCP relay for eth1 and eth2: - -.. code-block:: none - - set service dhcp-relay interface eth1 - set service dhcp-relay interface eth2 - -Set the IP address of the DHCP server: - -.. code-block:: none - - set service dhcp-relay server 10.0.1.4 - -The router should discard DHCP packages already containing relay agent -information to ensure that only requests from DHCP clients are forwarded: - -.. code-block:: none - - set service dhcp-relay relay-options relay-agents-packets discard - -Commit the changes and show the results: - -.. code-block:: none - - commit - show service dhcp-relay - interface eth1 - interface eth2 - server 10.0.1.4 - relay-options { - relay-agents-packets discard - } - -The DHCP relay agent can be restarted with: - -.. code-block:: none - - restart dhcp relay-agent - -DHCPv6 relay example -^^^^^^^^^^^^^^^^^^^^ - -.. figure:: /_static/images/service_dhcpv6-relay01.png - :scale: 80 % - :alt: DHCPv6 relay example - - DHCPv6 relay example - -In this example DHCPv6 requests are received by the router on eth1 -(`listening interface`) and forwarded through eth2 (`upstream interface`) to -the external DHCPv6 server at 2001:db8:100::4. - -Configuration -************* - -Set eth1 to be the listening interface for the DHCPv6 relay: - -.. code-block:: none - - set service dhcpv6-relay listen-interface eth1 - -Set eth2 to be the upstream interface and specify the IPv6 address of -the DHCPv6 server: - -.. code-block:: none - - set service dhcpv6-relay upstream-interface eth2 address 2001:db8:100::4 - -Commit the changes and show results: - -.. code-block:: none - - commit - show service dhcpv6-relay - listen-interface eth1 { - } - upstream-interface eth2 { - address 2001:db8:100::4 - } - -Show the current status of the DHCPv6 relay agent: - -.. code-block:: none - - show dhcpv6 relay-agent status - -The DHCPv6 relay agent can be restarted with: - -.. code-block:: none - - restart dhcpv6 relay-agent - -Additional parameters -^^^^^^^^^^^^^^^^^^^^^ - -DHCP relay agent options -************************ - -Set the maximum hop count before packets are discarded. Range 0...255, -default 10. - -* :code:`set service dhcp-relay relay-options hop-count 'count'` - -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. - -* :code:`set service dhcp-relay relay-options max-size 'size'` - -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. - -* :code:`set service dhcp-relay relay-options relay-agents-packet 'policy'` - -DHCPv6 relay agent options -************************** - -Set maximum hop count before packets are discarded. Default: 10. - -* :code:`set service dhcpv6-relay max-hop-count 'count'` - -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. - -* :code:`set service dhcpv6-relay use-interface-id-option` diff --git a/docs/services/dhcp.rst b/docs/services/dhcp.rst deleted file mode 100644 index f11d9a7e..00000000 --- a/docs/services/dhcp.rst +++ /dev/null @@ -1,138 +0,0 @@ - -DHCP Server ------------ - -Multiple DHCP Servers can be run from a single machine. Each DHCP service is -identified by a `shared-network-name`. - -DHCP Server Example -^^^^^^^^^^^^^^^^^^^ - -In this example, we are offering address space in the 172.16.17.0/24 network, -which is on eth1, and pppoe0 is our connection to the internet. We are using -the network name `dhcpexample`. - -Prerequisites -^^^^^^^^^^^^^ - -Configuring the PPPoE interface is assumed to be done already, and appears -on `pppoe0` - -Interface Configuration -^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - set interface ethernet eth1 address 172.16.17.1/24 - -Multiple ranges can be defined and can contain holes. - -.. code-block:: none - - set service dhcp-server shared-network-name dhcpexample authoritative - set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 default-router 172.16.17.1 - set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 dns-server 172.16.17.1 - set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 lease 86400 - set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 range 0 start 172.16.17.100 - set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 range 0 stop 172.16.17.199 - - -Explanation -^^^^^^^^^^^ - -* :code:`set service dhcp-server shared-network-name dhcpexample 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. - -* :code:`set service dhcp-server shared-network-name dhcpexample subnet - 172.16.17.0/24 default-router 172.16.17.1` - - This is a configuration parameter for the subnet, saying that as part of the - response, tell the client that I am the default router for this network - -* :code:`set service dhcp-server shared-network-name dhcpexample subnet - 172.16.17.0/24 dns-server 172.16.17.1` - - This is a configuration parameter for the subnet, saying that as part of the - response, tell the client that I am the DNS server for this network. If you - do not want to run a DNS server, you could also provide one of the public - DNS servers, such as google's. You can add multiple entries by repeating the - line. - -* :code:`set service dhcp-server shared-network-name dhcpexample subnet - 172.16.17.0/24 lease 86400` - - Assign the IP address to this machine for 24 hours. It is unlikely you'd need - to shorten this period, unless you are running a network with lots of devices - appearing and disappearing. - - -* :code:`set service dhcp-server shared-network-name dhcpexample subnet - 172.16.17.0/24 range 0 start 172.16.17.100` - - Make a range of addresses available for clients starting from .100 [...] - -* :code:`set service dhcp-server shared-network-name dhcpexample subnet - 172.16.17.0/24 range 0 stop 172.16.17.199` - - [...] and ending at .199 - - -Failover -^^^^^^^^ - -VyOS provides support for DHCP failover: - -.. code-block:: none - - set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover local-address '192.168.0.1' - set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover name 'foo' - set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover peer-address '192.168.0.2' - -.. note:: `name` must be identical on both sides! - -The primary and secondary statements determines whether the server is -primary or secondary - -.. code-block:: none - - set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover status 'primary' - -or - -.. code-block:: none - - set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover status '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. - -Static mappings MAC/IP -^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 static-mapping static-mapping-01 ip-address 172.16.17.10 - set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 static-mapping static-mapping-01 mac-address ff:ff:ff:ff:ff:ff - -DHCP server options -^^^^^^^^^^^^^^^^^^^^^^^^^ - -default-router (DHCP option 003) - :code:`set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 default-router <ROUTER-IP>` - -dns-server (DHCP option 006) - :code:`set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 dns-server <DNS-SERVER-IP>` - -domain-name Client domain name (DHCP option 015) - :code:`set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 domain-name "<DOMAIN-NAME>"` - -domain-search (DHCP option 119) - This option can be given multiple times if you need multiple search domains - :code:`set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 domain-search "<DOMAIN_NAME_1>"` - :code:`set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 domain-search "<DOMAIN_NAME_2>"` - diff --git a/docs/services/dhcpv6.rst b/docs/services/dhcpv6.rst deleted file mode 100644 index db566d5f..00000000 --- a/docs/services/dhcpv6.rst +++ /dev/null @@ -1,305 +0,0 @@ - -DHCPv6 server -------------- - -VyOS provides DHCPv6 server functionality which is described in this section. -In order to use the DHCPv6 server it has to be enabled first: - -.. code-block:: none - - set service dhcpv6-server - -To restart the DHCPv6 server (operational mode): - -.. code-block:: none - - restart dhcpv6 server - -To show the current status of the DHCPv6 server use: - -.. code-block:: none - - show dhcpv6 server status - -Show statuses of all assigned leases: - -.. code-block:: none - - show dhcpv6 server leases - -DHCPv6 server options -^^^^^^^^^^^^^^^^^^^^^ - -DHCPv6 server 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`. Set -a preference value for the DHCPv6 server: - -.. code-block:: none - - set service dhcpv6-server preference <preference value> - -Delete a preference: - -.. code-block:: none - - set service dhcpv6-server preference - -Show current preference: - -.. code-block:: none - - show service dhcpv6-server preference - -Specify address lease time -************************** - -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 in -seconds): - -.. code-block:: none - - set service dhcpv6-server shared-network-name <name> subnet <ipv6net> lease-time {default <default-time> | maximum <maximum-time> | minimum <minimum-time>} - -Reset the custom lease times: - -.. code-block:: none - - delete service dhcpv6-server shared-network-name <name> subnet <ipv6net> lease-time {default | maximum | minimum} - -Show the current configuration: - -.. code-block:: none - - show service dhcpv6-server shared-network-name <name> subnet <ipv6net> lease-time {default | maximum | minimum} - -Specify NIS domain -****************** - -A Network Information (NIS) domain can be set to be used for DHCPv6 clients: - -.. code-block:: none - - set service dhcpv6-server shared-network-name <name> subnet <ipv6net> nis-domain <nis-domain-name> - -To Delete the NIS domain: - -.. code-block:: none - - delete service dhcpv6-server shared-network-name <name> subnet <ipv6net> nis-domain <nis-domain-name> - -Show a configured NIS domain: - -.. code-block:: none - - show service dhcpv6-server shared-network-name <name> subnet <ipv6net> nis-domain <nis-domain-name> - -Specify NIS+ domain -******************* - -The procedure to specify a Network Information Service Plus (NIS+) domain is -similar to the NIS domain one: - -.. code-block:: none - - set service dhcpv6-server shared-network-name <name> subnet <ipv6net> nisplus-domain <nisplus-domain-name> - -To Delete the NIS+ domain: - -.. code-block:: none - - delete service dhcpv6-server shared-network-name <name> subnet <ipv6net> nisplus-domain <nisplus-domain-name> - -Show a configured NIS domain: - - # show service dhcpv6-server shared-network-name <name> subnet <ipv6net> nisplus-domain <nisplus-domain-name> - -Specify NIS server address -************************** - -To specify a NIS server address for DHCPv6 clients: - -.. code-block:: none - - set service dhcpv6-server shared-network-name <name> subnet <ipv6net> nis-server <IPv6 address> - -Delete a specified NIS server address: - -.. code-block:: none - - delete service dhcpv6-server shared-network-name <name> subnet <ipv6net> nis-server <IPv6 address> - -Show specified NIS server addresses: - -.. code-block:: none - - show service dhcpv6-server shared-network-name <name> subnet <ipv6net> nis-server - -Specify NIS+ server address -*************************** - -To specify a NIS+ server address for DHCPv6 clients: - -.. code-block:: none - - set service dhcpv6-server shared-network-name <name> subnet <ipv6net> nisplus-server <IPv6 address> - -Delete a specified NIS+ server address: - -.. code-block:: none - - delete service dhcpv6-server shared-network-name <name> subnet <ipv6net> nisplus-server <IPv6 address> - -Show specified NIS+ server addresses: - -.. code-block:: none - - show service dhcpv6-server shared-network-name <name> subnet <ipv6net> nisplus-server - -Specify a SIP server address for DHCPv6 clients -*********************************************** - -By IPv6 address -############### - - -A Session Initiation Protocol (SIP) server address can be specified -for DHCPv6 clients: - -.. code-block:: none - - set service dhcpv6-server shared-network-name <name> subnet <ipv6net> sip-server-address <IPv6 address> - -Delete a specified SIP server address: - -.. code-block:: none - - delete service dhcpv6-server shared-network-name <name> subnet <ipv6net> sip-server-address <IPv6 address> - -Show specified SIP server addresses: - -.. code-block:: none - - show service dhcpv6-server shared-network-name <name> subnet <ipv6net> sip-server-address - -By FQDN -####### - -A name for SIP server can be specified: - -.. code-block:: none - - set service dhcpv6-server shared-network-name <name> subnet <ipv6net> sip-server-name <sip-server-name> - -Delete a specified SIP server name: - -.. code-block:: none - - delete service dhcpv6-server shared-network-name <name> subnet <ipv6net> sip-server-name <sip-server-name> - -Show specified SIP server names: - -.. code-block:: none - - show service dhcpv6-server shared-network-name <name> subnet <ipv6net> sip-server-name - -Simple Network Time Protocol (SNTP) server address for DHCPv6 clients -********************************************************************* - -A SNTP server address can be specified for DHCPv6 clients: - -.. code-block:: none - - set service dhcpv6-server shared-network-name <name> subnet <ipv6net> sntp-server-address <IPv6 address> - -Delete a specified SNTP server address: - -.. code-block:: none - - delete service dhcpv6-server shared-network-name <name> subnet <ipv6net> sntp-server-address <IPv6 address> - -Show specified SNTP server addresses: - -.. code-block:: none - - show service dhcpv6-server shared-network-name <name> subnet <ipv6net> sntp-server-address - -DHCPv6 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 1: DHCPv6 address pool -****************************** - -A shared network named `NET1` serves subnet `2001:db8:100::/64` which is -connected to `eth1`, a DNS server at `2001:db8:111::111` is used for name -services. The range of the address pool shall be `::100` through `::199`. The -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:100::/64 address-range start 2001:db8:100::100 stop 2001:db8:100::199 - set service dhcpv6-server shared-network-name NET1 subnet 2001:db8:100::/64 name-server 2001:db8:111::111 - -Commit the changes and show the configuration: - -.. code-block:: none - - commit - show service dhcpv6-server - shared-network-name NET1 { - subnet 2001:db8:100::/64 { - address-range { - start 2001:db8:100::100 { - stop 2001:db8:100::199 - } - } - name-server 2001:db8:111::111 - } - } - -Static mappings -^^^^^^^^^^^^^^^ - -In order to map specific IPv6 addresses to specific hosts static mappings can -be created. The following example explains the process. - -Example 1: Static IPv6 MAC-based mapping -**************************************** - -IPv6 address `2001:db8:100::101` shall be statically mapped to a device with -MAC address `00:15:c5:b7:5e:23`, this host-specific mapping shall be named -`client1`. - -.. note:: The MAC address identifier is defined by the last 4 byte of the - MAC address. - -.. code-block:: none - - set service dhcpv6-server shared-network-name NET1 subnet 2001:db8:100::/64 static-mapping client1 ipv6-address 2001:db8:100::101 - set service dhcpv6-server shared-network-name NET1 subnet 2001:db8:100::/64 static-mapping client1 identifier c5b75e23 - -Commit the changes and show the configuration: - -.. code-block:: none - - show service dhcp-server shared-network-name NET1 - shared-network-name NET1 { - subnet 2001:db8:100::/64 { - name-server 2001:db8:111::111 - address-range { - start 2001:db8:100::100 { - stop 2001:db8:100::199 { - } - } - static-mapping client1 { - ipv6-address 2001:db8:100::101 - identifier c5b75e23 - } - } - } diff --git a/docs/services/dns-forwarding.rst b/docs/services/dns-forwarding.rst deleted file mode 100644 index 84e4fc93..00000000 --- a/docs/services/dns-forwarding.rst +++ /dev/null @@ -1,72 +0,0 @@ -DNS Forwarding --------------- - -Use DNS forwarding if you want your router to function as a DNS server for the -local network. There are several options, the easiest being 'forward all -traffic to the system DNS server(s)' (defined with set system name-server): - -.. code-block:: none - - set service dns forwarding system - -Manually setting DNS servers for forwarding: - -.. code-block:: none - - set service dns forwarding name-server 8.8.8.8 - set service dns forwarding name-server 8.8.4.4 - -Manually setting DNS servers with IPv6 connectivity: - -.. code-block:: none - - set service dns forwarding name-server 2001:4860:4860::8888 - set service dns forwarding name-server 2001:4860:4860::8844 - -Setting a forwarding DNS server for a specific domain: - -.. code-block:: none - - set service dns forwarding domain example.com server 192.0.2.1 - -Set which networks or clients are allowed to query the DNS Server. Allow from all: - -.. code-block:: none - - set service dns forwarding allow-from 0.0.0.0/0 - -Example 1 -^^^^^^^^^ - -Router with two interfaces eth0 (WAN link) and eth1 (LAN). Split DNS for example.com. - -* DNS request for a local domain (example.com) get forwarded to 192.0.2.1 -* Other DNS requests are forwarded to Google's DNS servers. -* The IP address for the LAN interface is 192.168.0.1. - -.. code-block:: none - - set service dns forwarding domain example.com server 192.0.2.1 - set service dns forwarding name-server 8.8.8.8 - set service dns forwarding name-server 8.8.4.4 - set service dns forwarding listen-address 192.168.0.1 - set service dns forwarding allow-from 0.0.0.0/0 - -Example 2 -^^^^^^^^^ - -Same as example 1 but with additional IPv6 addresses for Google's public DNS -servers. - -The IP addresses for the LAN interface are 192.168.0.1 and 2001:db8::1 - -.. code-block:: none - - set service dns forwarding domain example.com server 192.0.2.1 - set service dns forwarding name-server 8.8.8.8 - set service dns forwarding name-server 8.8.4.4 - set service dns forwarding name-server 2001:4860:4860::8888 - set service dns forwarding name-server 2001:4860:4860::8844 - set service dns forwarding listen-address 2001:db8::1 - set service dns forwarding listen-address 192.168.0.1 - set service dns forwarding allow-from 0.0.0.0/0 diff --git a/docs/services/dynamic-dns.rst b/docs/services/dynamic-dns.rst deleted file mode 100644 index 6a3c6e28..00000000 --- a/docs/services/dynamic-dns.rst +++ /dev/null @@ -1,152 +0,0 @@ -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 exact purpose. - -ddclient_ uses two methods to update a DNS record. The first one will send -updates directly to the DNS daemon, in compliance with RFC2136_. 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. - -VyOS CLI and RFC2136 -^^^^^^^^^^^^^^^^^^^^ - -First, create an RFC2136_ config node : - -.. code-block:: none - - edit service dns dynamic interface eth0 rfc2136 <confignodename> - -Present your RNDC key to ddclient : - -.. code-block:: none - - set key /config/dyndns/mydnsserver.rndc.key - -Set the DNS server IP/FQDN : - -.. code-block:: none - - set server dns.mydomain.com - -Set the NS zone to be updated : - -.. code-block:: none - - set zone mydomain.com - -Set the records to be updated : - -.. code-block:: none - - set record dyn - set record dyn2 - -You can optionally set a TTL (note : default value is 600 seconds) : - -.. code-block:: none - - set ttl 600 - -This will generate the following ddclient config blocks: - -.. code-block:: none - - server=dns.mydomain.com - protocol=nsupdate - password=/config/dyndns/mydnsserver.rndc.key - ttl=600 - zone=mydomain.com - dyn - server=dns.mydomain.com - protocol=nsupdate - password=/config/dyndns/mydnsserver.rndc.key - ttl=600 - zone=mydomain.com - dyn2 - -You can also keep a different dns zone updated. Just create a new config node: - -.. code-block:: none - - edit service dns dynamic interface eth0 rfc2136 <confignode2> - -VyOS CLI and HTTP dynamic DNS services -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -VyOS is also able to use any service relying on protocols supported -by ddclient. - -To use such a service, you must define a login, a password, one or multiple -hostnames, a protocol and a server. - -.. code-block:: none - - edit service dns dynamic interface eth0 service HeNet - set login my-login # set password my-password - set host-name my-tunnel-id - set protocol dyndns2 - set server ipv4.tunnelbroker.net - -VyOS is also shipped with a list of known services. You don't need to set the -protocol and server value as VyOS has defaults provided for those. These are -the services VyOS knows about: - -* afraid -* changeip -* dnspark -* dslreports -* dyndns -* easydns -* namecheap -* noip -* zoneedit - -To use DynDNS for example: - -.. code-block:: none - - edit service dns dynamic interface eth0 service dyndns - set login my-login - set password my-password - set host-name my-dyndns-hostname - -It's possible to use multiple services : - -.. code-block:: none - - edit service dns dynamic interface eth0 service dyndns - set login my-login - set password my-password - set host-name my-dyndns-hostname - edit service dns dynamic interface eth0 service HeNet - set login my-login - set password my-password - set host-name my-tunnel-id - set protocol dyndns2 - set server ipv4.tunnelbroker.net - -ddclient 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 these two options: - -.. code-block:: none - - set service dns dynamic interface eth0 use-web url - set service dns dynamic interface eth0 use-web skip - -ddclient_ will load the webpage at `[url]` and will try to extract an IP -address for the response. ddclient_ will skip any address located before the -string set in `[skip]`. - - -.. include:: references.rst diff --git a/docs/services/index.rst b/docs/services/index.rst deleted file mode 100644 index dbfcfce2..00000000 --- a/docs/services/index.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. _services: - -.. include:: references.rst - -Services -======== - -This chapter describes the available system/network services provided by VyOS. - -.. toctree:: - :maxdepth: 1 - - conntrack - dhcp - dhcpv6 - dhcp-relay - dns-forwarding - dynamic-dns - lldp - mdns-repeater - ipoe-server - pppoe-server - udp-broadcast-relay - snmp - ssh - tftp - webproxy diff --git a/docs/services/ipoe-server.rst b/docs/services/ipoe-server.rst deleted file mode 100644 index eed4cced..00000000 --- a/docs/services/ipoe-server.rst +++ /dev/null @@ -1,129 +0,0 @@ -IPoE server ------------- - -VyOS utilizes `accel-ppp`_ to provide IPoE server functionality. It can be -used with local authentication (mac-address) 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 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 cpe 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 - - - - -.. _`accel-ppp`: https://accel-ppp.org/ diff --git a/docs/services/lldp.rst b/docs/services/lldp.rst deleted file mode 100644 index dccd68fa..00000000 --- a/docs/services/lldp.rst +++ /dev/null @@ -1,97 +0,0 @@ -LLDP ----- - -The Link Layer Discovery Protocol (LLDP) 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.[1] 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 -`Cisco Discovery Protocol`_, `Foundry Discovery Protocol`_, -Nortel Discovery Protocol and Link Layer Topology Discovery. - -Information gathered -^^^^^^^^^^^^^^^^^^^^ - -Information gathered with LLDP is stored in the device as a management -information database (MIB_) and can be queried with the Simple Network -Management Protocol (SNMP_) 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 -^^^^^^^^^^^^^ - -* Enable service with: - - :code:`set service lldp` - -Options -******* - -* Configure a Define management-address: - - :code:`set service lldp management-address <x.x.x.x>` - -* Define listening interfaces - - :code:`set service lldp interface <all|interface name>` - -* LLDPd also implements an SNMP subagent. To Enable SNMP queries of the LLDP - database: - - :code:`set service lldp snmp enable` - -* Enable optional/other protocols - - :code:`set service lldp legacy-protocols cdp` - - Supported legacy protocols: - - * ``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 - - -Display neighbors -^^^^^^^^^^^^^^^^^ - -* Display with: - -``show lldp neighbors`` - -Exemple: - -.. 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 - --------- ----- ----- --- -------- ------- - swA309 eth0 LLDP ? Cisco IOS Software, GigE0/33 - - -* Options: - - * ``detail`` - Show lldp neighbors detail - * ``interface`` - Show LLDP for specified interface - -Troubleshooting -^^^^^^^^^^^^^^^ - -Use operational command ``show log lldp`` to display logs. - -.. include:: references.rst diff --git a/docs/services/mdns-repeater.rst b/docs/services/mdns-repeater.rst deleted file mode 100644 index 22e824ba..00000000 --- a/docs/services/mdns-repeater.rst +++ /dev/null @@ -1,30 +0,0 @@ -mDNS Repeater -------------- - -Starting with VyOS 1.2 a `Multicast DNS`_ (mDNS) repeater functionality is -provided. - -Multicast DNS uses the 224.0.0.51 address, which is "administratively scoped" -and does not leave the subnet. It re-broadcast mDNS packets from one interface -to other interfaces. This enables support for e.g. Apple Airplay devices across -multiple VLANs. - -To enable mDNS repeater you need to configure at least two interfaces. To re- -broadcast all mDNS packets from `eth0` to `eth1` and vice versa run: - -.. code-block:: none - - set service mdns repeater interface eth0 - set service mdns repeater interface eth1 - -mDNS repeater can be temporarily disabled without deleting the service using - -.. code-block:: none - - set service mdns repeater disable - -.. 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! - - -.. _`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 8e37a068..00000000 --- a/docs/services/pppoe-server.rst +++ /dev/null @@ -1,217 +0,0 @@ -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 -^^^^^^^^^^^^^ - -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 dns-servers server-1 '10.100.100.1' - set service pppoe-server dns-servers server-2 '10.100.200.1' - set service pppoe-server interface 'eth1' - set service pppoe-server local-ip '10.1.1.2' - - -Connections can be locally checked via the command - -.. 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 | 08:00:27:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B | 76 B - - -Client IP 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** - -.. 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** - -.. 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 -of course need to specify an IP for the server. You can have multiple RADIUS -server 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 secret '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** - -For remotely disconnect sessions and change some authentication parameters you can configure dae-server - -.. code-block:: none - - set service pppoe-server authentication radius-settings dae-server ip-address '10.1.1.2' - set service pppoe-server authentication radius-settings dae-server port '3799' - set service pppoe-server authentication radius-settings dae-server secret 'secret123' - -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 -======================= - -VLAN's can be created by accel-ppp on the fly if via the use of the kernel module 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. - -.. 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 - - -The pppoe-server will now create these VLANs if required and once the user session has been cancelled, and the VLAN is not necessary anymore, it will remove it again. - - - -Bandwidth Shaping -^^^^^^^^^^^^^^^^^ - -Bandwidth rate limits can be set for local users or RADIUS based attributes. - -Bandwidth Shaping for local users -================================= - -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 dns-servers server-1 '10.100.100.1' - set service pppoe-server dns-servers server-2 '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 | 08:00:27:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B | 76 B - - -RADIUS based shaper setup -========================= - -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. - -.. code-block:: none - - set service pppoe-server authentication radius-settings rate-limit enable - -Other attributes can be used, but they have to be in one of the dictionaries in /usr/share/accel-ppp/radius. - - - -Practical Configuration Examples -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Dual-stack provisioning with IPv6 PD via pppoe -============================================== - -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-prefix '2001:db8:8003::1/48,56' - set service pppoe-server client-ipv6-pool prefix '2001:db8:8002::1/48,64' - set service pppoe-server dns-servers server-1 '8.8.8.8' - set service pppoe-server dnsv6-servers server-1 '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 | 08:00:27:12:42:eb | | active | 00:00:49 | 875 B | 2.1 KiB - -.. _`accel-ppp`: https://accel-ppp.org/ diff --git a/docs/services/references.rst b/docs/services/references.rst deleted file mode 100644 index bee936d7..00000000 --- a/docs/services/references.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _`Cisco Discovery Protocol`: https://en.wikipedia.org/wiki/Cisco_Discovery_Protocol -.. _ddclient: http://github.com/ddclient/ddclient -.. _`Foundry Discovery Protocol`: https://en.wikipedia.org/wiki/Foundry_Discovery_Protocol -.. _MIB: https://en.wikipedia.org/wiki/Management_information_base -.. _RFC2136: https://www.ietf.org/rfc/rfc2136.txt -.. _SNMP: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol -.. _SNMPv2: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2 -.. _SNMPv3: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_3 -.. _SSH: https://en.wikipedia.org/wiki/Secure_Shell -.. _Squid3: http://www.squid-cache.org/ -.. _Squidguard: http://www.squidguard.org/ -.. _TFTP: https://en.wikipedia.org/wiki/Trivial_File_Transfer_Protocol -.. _`arbitrary extension commands`: http://net-snmp.sourceforge.net/docs/man/snmpd.conf.html#lbAZ -.. _`accel-ppp`: https://accel-ppp.org/ -.. _`Secure Socket Tunneling Protocol`: https://en.wikipedia.org/wiki/Secure_Socket_Tunneling_Protocol diff --git a/docs/services/snmp.rst b/docs/services/snmp.rst deleted file mode 100644 index 6418a516..00000000 --- a/docs/services/snmp.rst +++ /dev/null @@ -1,245 +0,0 @@ -SNMP ----- - -Simple Network Management Protocol (SNMP_) 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 -******* - -.. code-block:: none - - set service snmp v3 engineid '0x0aa0d6c6f450' - set service snmp v3 group defaultgroup mode 'ro' - set service snmp v3 group defaultgroup seclevel 'priv' - set service snmp v3 group defaultgroup view 'defaultview' - set service snmp v3 view defaultview oid '1' - - set service snmp v3 user testUser1 auth plaintext-key testUserKey1 - set service snmp v3 user testUser1 auth type 'md5' - set service snmp v3 user testUser1 engineid '0x0aa0d6c6f450' - set service snmp v3 user testUser1 group 'defaultgroup' - set service snmp v3 user testUser1 mode 'ro' - set service snmp v3 user testUser1 privacy type aes - set service snmp v3 user testUser1 privacy plaintext-key testUserKey1 - -After commit the resulting configuration will look like: - -.. note:: SNMPv3 keys won't we stored in plaintext. On ``commit`` the keys - will be encrypted and the encrypted key is based on the engineid! - -.. code-block:: none - - vyos@vyos# show service snmp - v3 { - engineid 0x0aa0d6c6f450 - group defaultgroup { - mode ro - seclevel priv - view defaultview - } - user testUser1 { - auth { - encrypted-key 0x3b68d4162c2c817b8e9dfb6f08583e5d - type md5 - } - engineid 0x0aa0d6c6f450 - group defaultgroup - mode ro - privacy { - encrypted-key 0x3b68d4162c2c817b8e9dfb6f08583e5d - type aes - } - } - view defaultview { - oid 1 { - } - } - } - -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 extension -commands``_. 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> - -.. include:: references.rst diff --git a/docs/services/ssh.rst b/docs/services/ssh.rst deleted file mode 100644 index 3af71899..00000000 --- a/docs/services/ssh.rst +++ /dev/null @@ -1,150 +0,0 @@ -SSH ---- - -Secure Shell (SSH_) is a cryptographic network protocol for operating network -services securely over an unsecured network.[1] 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 -^^^^^^^^^^^^^ - -Enabling SSH only requires you to add ``service ssh port NN``, where 'NN' is -the port you want SSH to listen on. By default, SSH runs on port 22. - -.. code-block:: none - - set service ssh port 22 - -Options -******* - -* Listening address - Specify the IPv4/IPv6 listening address for connection - requests. Multiple ``listen-address`` nodes can be defined. - - :code:`set service ssh listen-address <address>` - -* Allow ``root`` login, this can be set to allow ``root`` logins on SSH - connections, however it is not advisable to use this setting as this bears - serious security risks. The default system user possesses all required - privileges. - - :code:`set service ssh allow-root` - -* Allowed ciphers - A number of allowed ciphers can be specified, use multiple - occurrences to allow multiple ciphers. - - :code:`set service ssh ciphers <cipher>` - - Available ciphers: - - * `3des-cbc` - * `aes128-cbc` - * `aes192-cbc` - * `aes256-cbc` - * `aes128-ctr` - * `aes192-ctr` - * `aes256-ctr` - * `arcfour128` - * `arcfour256` - * `arcfour` - * `blowfish-cbc` - * `cast128-cbc` - -* Disable password authentication - If SSH key authentication is set up, - password-based user authentication can be disabled. This hardens security! - - :code:`set service ssh disable-password-authentication` - -* Disable host validation - Disable the host validation through reverse DNS - lookups. - - :code:`set service ssh disable-host-validation` - -* MAC algorithms - Specifies the available MAC (message authentication code) - algorithms. The MAC algorithm is used in protocol version 2 for data - integrity protection. Multiple algorithms can be entered. - - :code:`set service ssh macs <macs>` - - 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` - - -Key Authentication -################## - -It is highly recommended to use SSH Key authentication. By default there is -only one user (``vyos``), and you can assign any number of keys to that user. -You can generate a ssh key with the ``ssh-keygen`` command on your local -machine, which will (by default) save it as ``~/.ssh/id_rsa.pub`` which is in -three parts: - - ``ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAA...VByBD5lKwEWB username@host.example.com`` - -Only the type (``ssh-rsa``) and the key (``AAAB3N...``) are used. Note that -the key will usually be several hundred characters long, and you will need to -copy and paste it. Some terminal emulators may accidentally split this over -several lines. Be attentive when you paste it that it only pastes as a single -line. The third part is simply an identifier, and is for your own reference. - - -**Assign SSH Key to user** - -Under the user (in this example, ``vyos``), add the public key and the type. -The `identifier` is simply a string that is relevant to you. - -.. code-block:: none - - set system login user vyos authentication public-keys 'identifier' key "AAAAB3Nz...." - set system login user vyos authentication public-keys 'identifier' type ssh-rsa" - -You can assign multiple keys to the same user by changing the identifier. In -the following example, both Unicron and xrobau will be able to SSH into VyOS -as the ``vyos`` user using their own keys. - -.. code-block:: none - - set system login user vyos authentication public-keys 'Unicron' key "AAAAB3Nz...." - set system login user vyos authentication public-keys 'Unicron' type ssh-rsa - set system login user vyos authentication public-keys 'xrobau' key "AAAAQ39x...." - set system login user vyos authentication public-keys 'xrobau' type ssh-rsa - - - diff --git a/docs/services/tftp.rst b/docs/services/tftp.rst deleted file mode 100644 index 9ce46b02..00000000 --- a/docs/services/tftp.rst +++ /dev/null @@ -1,42 +0,0 @@ -TFTP ----- - -Trivial File Transfer Protocol (TFTP_) 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. - -Example -^^^^^^^ - -.. code-block:: none - - # If you want to enable uploads, else TFTP server will act as read-only (optional) - set service tftp-server allow-upload - - # Directory for TFTP server content - set service tftp-server directory '/config/tftpboot' - - # On which addresses we want to listen for incoming TFTP connections? (mandatory) - set service tftp-server listen-address '2001:db8:ffee::1' - set service tftp-server listen-address '10.10.1.1' - -.. note:: 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. - -.. note:: Configuring a listen-address is essential for the service to work. - -The resulting configuration will look like: - -.. code-block:: none - - vyos@vyos# show service - tftp-server { - allow-upload - directory /config/tftpboot - listen-address 2001:db8:ffee::1 - listen-address 10.10.1.1 - } - diff --git a/docs/services/udp-broadcast-relay.rst b/docs/services/udp-broadcast-relay.rst deleted file mode 100644 index 40f738e6..00000000 --- a/docs/services/udp-broadcast-relay.rst +++ /dev/null @@ -1,53 +0,0 @@ -UDP broadcast relay -------------------- - -Certain vendors use broadcasts to identify their equipemnt within one ethernet -segment. Unfortunately if you split your network with multiple VLANs you loose -the ability of identifying your equiment. - -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! - -Example #1: 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' - -Example #2: To Forward all broadcasts packets received on `UDP port 6969` on -`eth3` or `eth4` to the other interface in this configuration. - -.. code-block:: none - - set service broadcast-relay id 2 description 'SONOS MGMT' - set service broadcast-relay id 2 interface 'eth3' - set service broadcast-relay id 2 interface 'eth4' - set service broadcast-relay id 2 port '6969' - -Disable Instance(s) -^^^^^^^^^^^^^^^^^^^ - -Each broadcast relay instance can be individually disabled without deleting the -configured node by using the following command: - -.. code-block:: none - - set service broadcast-relay id <n> disable - -In addition you can also disable the whole service without removing the -configuration by: - -.. code-block:: none - - set service broadcast-relay disable - -.. note:: You can run the UDP broadcast relay service on multiple routers - connected to a subnet. There is **NO** UDP broadcast relay packet storm! diff --git a/docs/services/webproxy.rst b/docs/services/webproxy.rst deleted file mode 100644 index 61546cda..00000000 --- a/docs/services/webproxy.rst +++ /dev/null @@ -1,152 +0,0 @@ -Webproxy --------- - -The proxy service in VyOS is based on Squid3 and some related modules. - -Squid is a caching and forwarding HTTP web proxy. It has a wide variety of -uses, including speeding up a web server by caching repeated requests, -caching web, DNS and other computer network lookups for a group of people -sharing network resources, and aiding security by filtering traffic. Although -primarily used for HTTP and FTP, Squid includes limited support for several -other protocols including Internet Gopher, SSL,[6] TLS and HTTPS. Squid does -not support the SOCKS protocol. - -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 wan't 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 wan't 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.) - -.. include:: references.rst |