diff options
Diffstat (limited to 'docs/configuration/service')
| -rw-r--r-- | docs/configuration/service/dhcp-server.rst | 203 | ||||
| -rw-r--r-- | docs/configuration/service/pppoe-server.rst | 12 | ||||
| -rw-r--r-- | docs/configuration/service/ssh.rst | 84 |
3 files changed, 136 insertions, 163 deletions
diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst index 56316793..6cb0bc83 100644 --- a/docs/configuration/service/dhcp-server.rst +++ b/docs/configuration/service/dhcp-server.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.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. @@ -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 diff --git a/docs/configuration/service/pppoe-server.rst b/docs/configuration/service/pppoe-server.rst index 28d1f097..224ff0d8 100644 --- a/docs/configuration/service/pppoe-server.rst +++ b/docs/configuration/service/pppoe-server.rst @@ -39,7 +39,7 @@ First steps 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> +.. cfgcmd:: set service pppoe-server gateway-address <address> Use this command to configure the local gateway IP address. @@ -57,7 +57,7 @@ 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 +Once the local tunnel endpoint ``set service pppoe-server gateway-address '10.1.1.2'`` has been defined, the client IP pool can be either defined as a range or as subnet using CIDR notation. If the CIDR notation is used, multiple subnets can be setup which are used sequentially. @@ -116,7 +116,7 @@ and then configure it. 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' + set service pppoe-server gateway-address '10.1.1.2' RADIUS provides the IP addresses in the example above via Framed-IP-Address. @@ -210,7 +210,7 @@ For Local Users 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' + set service pppoe-server gateway-address '10.1.1.2' Once the user is connected, the user session is using the set limits and @@ -359,7 +359,7 @@ address from the pool 10.1.1.100-111, terminates at the local endpoint 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 gateway-address '10.1.1.2' set service pppoe-server name-server '10.100.100.1' set service pppoe-server name-server '10.100.200.1' @@ -381,7 +381,7 @@ The example below covers a dual-stack configuration via pppoe-server. 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' + set service pppoe-server gateway-address '10.100.100.1' The client, once successfully authenticated, will receive an IPv4 and an IPv6 /64 address to terminate the pppoe endpoint on the client side and diff --git a/docs/configuration/service/ssh.rst b/docs/configuration/service/ssh.rst index 6da8560f..0153d918 100644 --- a/docs/configuration/service/ssh.rst +++ b/docs/configuration/service/ssh.rst @@ -27,80 +27,82 @@ rendering them susceptible to interception and disclosure using packet analysis. The encryption used by SSH is intended to provide confidentiality and integrity of data over an unsecured network, such as the Internet. +.. note:: VyOS 1.1 supported login as user ``root``. This has been removed due + to tighter security in VyOS 1.2. + +.. seealso:: SSH :ref:`ssh_key_based_authentication` + Configuration ============= .. cfgcmd:: set service ssh port <port> -Enabling SSH only requires you to specify the port ``<port>`` you want SSH to -listen on. By default, SSH runs on port 22. + 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. + 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`` + Define allowed ciphers used for the SSH connection. A number of allowed ciphers + can be specified, use multiple occurrences to allow multiple ciphers. + + List of supported ciphers: ``3des-cbc``, ``aes128-cbc``, ``aes192-cbc``, + ``aes256-cbc``, ``aes128-ctr``, ``aes192-ctr``, ``aes256-ctr``, ``arcfour128``, + ``arcfour256``, ``arcfour``, ``blowfish-cbc``, ``cast128-cbc`` .. cfgcmd:: set service ssh disable-password-authentication -Disable password based authentication. Login via SSH keys only. This hardens -security! + 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. + 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`` + 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. -.. note:: VyOS 1.1 supported login as user ``root``. This has been removed due - to tighter security in VyOS 1.2. + List of supported MACs: ``hmac-md5``, ``hmac-md5-96``, ``hmac-ripemd160``, + ``hmac-sha1``, ``hmac-sha1-96``, ``hmac-sha2-256``, ``hmac-sha2-512``, + ``umac-64@openssh.com``, ``umac-128@openssh.com``, ``hmac-md5-etm@openssh.com``, + ``hmac-md5-96-etm@openssh.com``, ``hmac-ripemd160-etm@openssh.com``, + ``hmac-sha1-etm@openssh.com``, ``hmac-sha1-96-etm@openssh.com``, + ``hmac-sha2-256-etm@openssh.com``, ``hmac-sha2-512-etm@openssh.com``, + ``umac-64-etm@openssh.com``, ``umac-128-etm@openssh.com`` .. cfgcmd:: set service ssh access-control <allow | deny> <group | user> <name> -Add access-control directive to allow or deny users and groups. Directives are -processed in the following order of precedence: ``deny-users``, ``allow-users``, -``deny-groups`` and ``allow-groups``. + 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. + 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``. + Specify allowed :abbr:`KEX (Key Exchange)` algorithms. + + List of supported algorithms: ``diffie-hellman-group1-sha1``, + ``diffie-hellman-group14-sha1``, ``diffie-hellman-group14-sha256``, + ``diffie-hellman-group16-sha512``, ``diffie-hellman-group18-sha512``, + ``diffie-hellman-group-exchange-sha1``, ``diffie-hellman-group-exchange-sha256``, + ``ecdh-sha2-nistp256``, ``ecdh-sha2-nistp384``, ``ecdh-sha2-nistp521``, + ``curve25519-sha256`` and ``curve25519-sha256@libssh.org``. .. cfgcmd:: set service ssh loglevel <quiet | fatal | error | info | verbose> -Set the ``sshd`` log level. The default is ``info``. + 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` + Specify name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance. |