diff options
| -rw-r--r-- | docs/contributing/debugging.rst | 7 | ||||
| -rw-r--r-- | docs/quick-start.rst | 10 | ||||
| -rw-r--r-- | docs/services/dhcp.rst | 203 |
3 files changed, 99 insertions, 121 deletions
diff --git a/docs/contributing/debugging.rst b/docs/contributing/debugging.rst index ac2e0510..40633535 100644 --- a/docs/contributing/debugging.rst +++ b/docs/contributing/debugging.rst @@ -51,7 +51,7 @@ interface debugging. It is also possible to set up the debugging using environment variables. In that case, the name will be (in uppercase) VYOS_FEATURE_DEBUG. -For example running, ``export VYOS_IFCONFIG_DEBUG=""`` on your vash, +For example running, ``export VYOS_IFCONFIG_DEBUG=""`` on your vbash, will have the same effect as ``touch /tmp/vyos.ifconfig.debug``. * ``ifconfig`` - Once set, all commands used, and their responses received @@ -71,6 +71,11 @@ will have the same effect as ``touch /tmp/vyos.ifconfig.debug``. including during boot. This option sends all commands used by VyOS to a file. The default file is ``/tmp/full-log`` but it can be changed. +.. note:: In order to retrieve the debug output on the command-line you need to + disable ``vyos-configd`` in addition. This can be run either one-time by calling + ``sudo systemctl stop vyos-configd`` or make this reboot-safe by calling + ``sudo systemctl disable vyos-configd``. + Config Migration Scripts ------------------------ diff --git a/docs/quick-start.rst b/docs/quick-start.rst index 367bdb4c..c70d4cc5 100644 --- a/docs/quick-start.rst +++ b/docs/quick-start.rst @@ -70,8 +70,10 @@ on specific addresses only. set service ssh port '22' -Configure DHCP/DNS Servers -########################## +.. _dhcp-dns-quick-start: + +DHCP/DNS quick-start +#################### The following settings will configure DHCP and DNS services on your internal/LAN network, where VyOS will act as the default gateway and DNS server. @@ -81,7 +83,7 @@ where VyOS will act as the default gateway and DNS server. * DHCP clients will be assigned IP addresses within the range of `192.168.0.9 - 192.168.0.254` and have a domain name of `internal-network` * DHCP leases will hold for one day (86400 seconds) -* VyOS will serve as a full DNS recursor, replacing the need to utilize Google, +* VyOS will serve as a full DNS recursor, replacing the need to utilize Google, Cloudflare, or other public DNS servers (which is good for privacy) * Only hosts from your internal/LAN network can use the DNS recursor @@ -214,5 +216,5 @@ As above, commit your changes, save the configuration, and exit configuration mo Done vyos@vyos# exit vyos@vyos$ - + You now should have a simple yet secure and functioning router to experiment with further. Enjoy! diff --git a/docs/services/dhcp.rst b/docs/services/dhcp.rst index 39ec3ed3..6cb0bc83 100644 --- a/docs/services/dhcp.rst +++ b/docs/services/dhcp.rst @@ -1,15 +1,16 @@ .. _dhcp: -############# -DHCP / DHCPv6 -############# - -VyOS uses ISC DHCPd for both IPv4 and IPv6 address assignment. - .. _dhcp-server: +########### DHCP Server -=========== +########### + +VyOS uses ISC DHCP server for both IPv4 and IPv6 address assignment. + +*********** +IPv4 server +*********** The network topology is declared by shared-network-name and the subnet declarations. The DHCP service can serve multiple shared networks, with each @@ -20,7 +21,7 @@ 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 @@ -77,9 +78,8 @@ Configuration 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. @@ -115,9 +115,8 @@ explicitly by the following statements. 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 @@ -140,9 +139,8 @@ inside the subnet definition but can be outside of the range statement. .. hint:: This is the equivalent of the host block in dhcpd.conf of isc-dhcpd. - Options -^^^^^^^ +======= .. list-table:: :header-rows: 1 @@ -272,9 +270,8 @@ Options Multi: can be specified multiple times. - Raw Parameters -^^^^^^^^^^^^^^ +============== Raw parameters can be passed to shared-network-name, subnet and static-mapping: @@ -299,44 +296,15 @@ 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 - } - } +======= +Please see the :ref:`dhcp-dns-quick-start` configuration. Failover -"""""""" +-------- + +Configuration of a DHCP failover pair * Setup DHCP failover for network 192.0.2.0/24 * Default gateway and DNS server is at `192.0.2.254` @@ -344,37 +312,38 @@ Failover * The secondary DHCP server uses address `192.168.189.253` * DHCP range spans from `192.168.189.10` - `192.168.189.250` -**Primary** +Common configuration, valid for both primary and secondary node. .. code-block:: none set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 default-router '192.0.2.254' set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 dns-server '192.0.2.254' set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 domain-name 'vyos.net' + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 start '192.0.2.10' + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 stop '192.0.2.250' + + +**Primary** + +.. code-block:: none + set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover local-address '192.168.189.252' set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover name 'NET-VYOS' set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover peer-address '192.168.189.253' set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover status 'primary' - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 start '192.0.2.10' - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 stop '192.0.2.250' **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.0.2.10' - set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 range 0 stop '192.0.2.250' Raw Parameters -"""""""""""""" +-------------- * Override static-mapping's dns-server with a custom one that will be sent only to this host. @@ -390,9 +359,8 @@ Raw Parameters 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 @@ -442,14 +410,15 @@ Operation Mode Show only leases with the specified state. Possible states: all, active, free, expired, released, abandoned, reset, backup (default = active) -DHCPv6 Server -============= +*********** +IPv6 server +*********** VyOS also provides DHCPv6 server functionality which is described in this section. -Configuration Options ---------------------- +Configuration +============= .. cfgcmd:: set service dhcpv6-server preference <preference value> @@ -490,7 +459,7 @@ Configuration Options 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: @@ -541,7 +510,7 @@ The configuration will look as follows: } Static mappings -^^^^^^^^^^^^^^^ +--------------- In order to map specific IPv6 addresses to specific hosts static mappings can be created. The following example explains the process. @@ -583,7 +552,7 @@ The configuration will look as follows: } Operation Mode --------------- +============== .. opcmd:: restart dhcpv6 server @@ -622,8 +591,9 @@ Operation Mode 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 @@ -631,8 +601,12 @@ agent works with IPv4 and IPv6 addresses. All interfaces used for the DHCP relay must be configured. +********** +IPv4 relay +********** + Configuration -------------- +============= .. cfgcmd:: set service dhcp-relay interface <interface> @@ -648,30 +622,6 @@ Configuration 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 ------- @@ -703,18 +653,43 @@ Options * **replace:** Relay information already present in a packet is stripped and replaced with the router's own relay information set. +Example +======= + +* Listen for DHCP requests on interface ``eth1``. +* DHCP server is located at IPv4 address 10.0.1.4. +* Router receives DHCP client requests on ``eth1`` and relays them to the server at 10.0.1.4. + +.. figure:: /_static/images/service_dhcp-relay01.png + :scale: 80 % + :alt: DHCP relay example + + DHCP relay example + +The generated configuration will look like: + +.. code-block:: none + + show service dhcp-relay + interface eth1 + server 10.0.1.4 + relay-options { + relay-agents-packets discard + } + Operation ---------- +========= .. opcmd:: restart dhcp relay-agent Restart DHCP relay service -DHCPv6 relay -============ +********** +IPv6 relay +********** Configuration -------------- +============= .. cfgcmd:: set service dhcpv6-relay listen-interface <interface> @@ -727,8 +702,20 @@ Configuration Specifies an upstream network `<interface>` from which replies from `<server>` and other relay agents will be accepted. +Options +------- + +.. cfgcmd:: set service dhcpv6-relay max-hop-count 'count' + + Set maximum hop count before packets are discarded, default: 10 + +.. cfgcmd:: set service dhcpv6-relay use-interface-id-option + + If this is set the relay agent will insert the interface ID. This option is + set automatically if more than one listening interfaces are in use. + Example -^^^^^^^ +======= * DHCPv6 requests are received by the router on `listening interface` ``eth1`` * Requests are forwarded through ``eth2`` as the `upstream interface` @@ -752,24 +739,8 @@ The generated configuration will look like: 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 |