diff options
Diffstat (limited to 'docs/configuration/service')
| -rw-r--r-- | docs/configuration/service/dhcp-server.rst | 209 | ||||
| -rw-r--r-- | docs/configuration/service/ipoe-server.rst | 5 | ||||
| -rw-r--r-- | docs/configuration/service/pppoe-server.rst | 7 | ||||
| -rw-r--r-- | docs/configuration/service/router-advert.rst | 5 | ||||
| -rw-r--r-- | docs/configuration/service/ssh.rst | 31 |
5 files changed, 232 insertions, 25 deletions
diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst index 00f0b21c..502d1e1b 100644 --- a/docs/configuration/service/dhcp-server.rst +++ b/docs/configuration/service/dhcp-server.rst @@ -49,15 +49,15 @@ Configuration Inform client that the DNS server can be found at `<address>`. This is the configuration parameter for the entire shared network definition. - All subnets will inherit this configuration item if not specified locally. + All subnets will inherit this configuration item if not specified locally. Multiple DNS servers can be defined. -.. cfgcmd:: set service dhcp-server shared-network-name <name> option +.. cfgcmd:: set service dhcp-server shared-network-name <name> option vendor-option <option-name> - This configuration parameter lets you specify a vendor-option for the - entire shared network definition. All subnets will inherit this - configuration item if not specified locally. An example for Ubiquiti is + This configuration parameter lets you specify a vendor-option for the + entire shared network definition. All subnets will inherit this + configuration item if not specified locally. An example for Ubiquiti is shown below: **Example:** @@ -66,14 +66,14 @@ Pass address of Unifi controller at ``172.16.100.1`` to all clients of ``NET1`` .. code-block:: none - set service dhcp-server shared-network-name 'NET1' option vendor-option + set service dhcp-server shared-network-name 'NET1' option vendor-option ubiquiti '172.16.100.1' .. cfgcmd:: set service dhcp-server listen-address <address> - This configuration parameter lets the DHCP server to listen for DHCP - requests sent to the specified address, it is only realistically useful for - a server whose only clients are reached via unicasts, such as via DHCP relay + This configuration parameter lets the DHCP server to listen for DHCP + requests sent to the specified address, it is only realistically useful for + a server whose only clients are reached via unicasts, such as via DHCP relay agents. Individual Client Subnet @@ -148,24 +148,205 @@ Individual Client Subnet request where no full FQDN is passed. This option can be given multiple times if you need multiple search domains (DHCP Option 119). -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> option vendor-option <option-name> This configuration parameter lets you specify a vendor-option for the - subnet specified within the shared network definition. An example for + subnet specified within the shared network definition. An example for Ubiquiti is shown below: **Example:** -Create ``172.18.201.0/24`` as a subnet within ``NET1`` and pass address of +Create ``172.18.201.0/24`` as a subnet within ``NET1`` and pass address of Unifi controller at ``172.16.100.1`` to clients of that subnet. .. code-block:: none - set service dhcp-server shared-network-name 'NET1' subnet + set service dhcp-server shared-network-name 'NET1' subnet '172.18.201.0/24' option vendor-option ubiquiti '172.16.100.1' +Dynamic DNS Update (RFC 2136) +----------------------------- + +VyOS DHCP service supports RFC-2136 DDNS protocol. Based on DHCP lease change +events, DHCP server generates DDNS update requests (defines as NameChangeRequests +or NCRs) and posts them to a compliant DNS server, that will update its name +database accordingly. + +VyOS built-in DNS Forwarder does not support DDNS, you will need an external DNS +server with RFC-2136 DDNS support. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update + + Enables DDNS globally. + +**Behavioral settings** + +These settings can be configured on the global level and overridden on the scope +level, i.e. for individual shared networks or subnets. See examples below. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update send-updates [ enable + | disable ] + + If set to ``enable`` on global level, updates for all scopes will be enabled, + except if explicitly set to ``disable`` on the scope level. If set to ``disable``, + updates will only be sent for scopes, where ``send-updates`` is explicity + set to ``enable``. + + This model is followed for a few behavioral settings below: if the option is + not set, the setting is inherited from the parent scope. You can override the + parent scope setting by setting the option explicitly. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update override-no-update [ enable + | disable ] + + VyOS will ignore client request not to update DNS records and send DDNS + update requests regardless. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update override-client-update [ enable + | disable ] + + VyOS will override client DDNS request settings and always update both + forward and reverse DNS records. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update update-on-renew [ enable + | disable ] + + Issue DDNS update requests on DHCP lease renew. In busy networks this may + generate a lot of traffic. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update conflict-resolution [ enable + | disable ] + + Use RFC-4703 conflict resolution. This algorithm helps in situation when + multiple clients reserve same IP addresses or advertise identical hostnames. + Should be used in most situations. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update replace-client-name [ never + | always | when-present | when-not-present ] + + * **never**: use the name sent by the client. If the client didn't provide any, + do not generate one. This is the default behavior + + * **always**: always generate a name for the client + + * **when-present**: replace the name the client sent with a generated one, if + the client didn't send any, do not generate one + + * **when-not-present**: use the name sent by the client. If the client didn't + send any, generate one for the client + + The names are generated using ``generated-prefix``, ``qualifying-suffix`` and the + client's IP address string. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update generated-prefix <prefix> + + Prefix used in client name generation. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update qualifying-suffix <suffix> + + DNS suffix used in client name generation. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update ttl-percent <0-100> + + TTL of the DNS record as a percentage of the DHCP lease time. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update hostname-char-set + <character string> + + Characters, that are considered invalid in the client name. They will be replaced + with ``hostname-char-replacement`` string. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update hostname-char-replacement + <character string> + + Replacement string for the invalid characters defined by ``hostname-char-set``. + +**TSIG keys definition** + +This is the global list of TSIG keys for DDNS updates. They need to be specified by +the name in the DNS domain definitions. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update tsig-key <key-name> + algorithm <algorithm> + + Sets the algorithm for the TSIG key. Supported algorithms are ``hmac-md5``, + ``hmac-sha1``, ``hmac-sha224``, ``hmac-sha256``, ``hmac-sha384``, ``hmac-sha512`` + +.. cfgcmd:: set service dhcp-server dynamic-dns-update tsig-key <key-name> + secret <key-secret> + + base64-encoded TSIG key secret value + +**DNS domains definition** + +This is global configuration of DNS servers for the updatable forward and reverse +DNS domains. For every domain multiple DNS servers can be specified. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-domain + <domain-name> key-name <tsig-key-name> + + TSIG key used for the domain. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-domain + <domain-name> dns-server <number> address <ip-address> + + IP address of the DNS server. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-domain + <domain-name> dns-server <number> port <port> + + UDP port of the DNS server. ``53`` is the default. + +**Example:** + +Global configuration you will most likely want: + +.. code-block:: none + + set service dhcp-server dynamic-dns-update send-updates enable + set service dhcp-server dynamic-dns-update conflict-resolution enable + +Override the above configuration for a shared network NET1: + +.. code-block:: none + + set service dhcp-server shared-network-name 'NET1' dynamic-dns-update replace-client-name when-not-present + set service dhcp-server shared-network-name 'NET1' dynamic-dns-update generated-prefix ip + set service dhcp-server shared-network-name 'NET1' dynamic-dns-update qualifying-suffix mybigdomain.net + +And in a subnet within the same shared network: + +.. code-block:: none + + set service dhcp-server shared-network-name 'NET1' subnet '172.18.201.0/24' dynamic-dns-update qualifying-suffix mydomain.net + +Configure TSIG keys: + +.. code-block:: none + + set service dhcp-server dynamic-dns-update tsig-key mydomain-net algorithm hmac-sha256 + set service dhcp-server dynamic-dns-update tsig-key mydomain-net secret eWF5YW15bGl0dGxla2V5IQ== + set service dhcp-server dynamic-dns-update tsig-key reverse-172-18-201 algorithm hmac-sha256 + set service dhcp-server dynamic-dns-update tsig-key reverse-172-18-201 secret eWF5YW15YW5vdGhlcmxpdHRsZWtleSE= + +Configure DDNS domains: + +.. code-block:: none + + set service dhcp-server dynamic-dns-update forward-domain mydomain.net key-name mydomain-net + set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 1 address '172.18.0.254' + set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 1 port 1053 + set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 2 address '192.168.124.254' + set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 2 port 53 + set service dhcp-server dynamic-dns-update forward-domain 201.18.172.in-addr.arpa key-name reverse-172-18-201 + set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 1 address '172.18.0.254' + set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 1 port 1053 + set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 2 address '192.168.124.254' + set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 2 port 53 + + High Availability ----------------- @@ -645,7 +826,7 @@ used: .. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet - <prefix> prefix-delegation prefix <pd-prefix> excluded-prefix-length <length> + <prefix> prefix-delegation prefix <pd-prefix> excluded-prefix-length <length> Define lenght of exclude prefix in `<pd-prefix>`. diff --git a/docs/configuration/service/ipoe-server.rst b/docs/configuration/service/ipoe-server.rst index ef06bcd5..5d7acd5a 100644 --- a/docs/configuration/service/ipoe-server.rst +++ b/docs/configuration/service/ipoe-server.rst @@ -174,11 +174,12 @@ RADIUS advanced options .. cfgcmd:: set service ipoe-server authentication radius dynamic-author server <address> - Specifies IP address for Dynamic Authorization Extension server (DM/CoA) + Specifies IP address for Dynamic Authorization Extension server (DM/CoA). + This IP must exist on any VyOS interface or it can be ``0.0.0.0``. .. cfgcmd:: set service ipoe-server authentication radius dynamic-author port <port> - Port for Dynamic Authorization Extension server (DM/CoA) + UDP port for Dynamic Authorization Extension server (DM/CoA) .. cfgcmd:: set service ipoe-server authentication radius dynamic-author key <secret> diff --git a/docs/configuration/service/pppoe-server.rst b/docs/configuration/service/pppoe-server.rst index 6d818c70..f763536a 100644 --- a/docs/configuration/service/pppoe-server.rst +++ b/docs/configuration/service/pppoe-server.rst @@ -144,12 +144,13 @@ RADIUS advanced options .. cfgcmd:: set service pppoe-server authentication radius dynamic-author server <address> - Specifies IP address for Dynamic Authorization Extension server (DM/CoA) + Specifies IP address for Dynamic Authorization Extension server (DM/CoA). + This IP must exist on any VyOS interface or it can be ``0.0.0.0``. .. cfgcmd:: set service pppoe-server authentication radius dynamic-author port <port> - Port for Dynamic Authorization Extension server (DM/CoA) + UDP port for Dynamic Authorization Extension server (DM/CoA) .. cfgcmd:: set service pppoe-server authentication radius dynamic-author key <secret> @@ -681,4 +682,4 @@ a /56 subnet for the clients internal use. .. _dictionary: https://github.com/accel-ppp/accel-ppp/blob/master/ accel-pppd/radius/dict/dictionary.rfc6911 .. _`ACCEL-PPP attribute`: https://github.com/accel-ppp/accel-ppp/ - blob/master/accel-pppd/radius/dict/dictionary.accel
\ No newline at end of file + blob/master/accel-pppd/radius/dict/dictionary.accel diff --git a/docs/configuration/service/router-advert.rst b/docs/configuration/service/router-advert.rst index 365017dd..cb9a6037 100644 --- a/docs/configuration/service/router-advert.rst +++ b/docs/configuration/service/router-advert.rst @@ -46,6 +46,7 @@ Configuration "Interval", "interval", "Min and max intervals between unsolicited multicast RAs" "DNSSL", "dnssl", "DNS search list to advertise" "Name Server", "name-server", "Advertise DNS server per https://tools.ietf.org/html/rfc6106" + "Auto Ignore Prefix", "auto-ignore", "Exclude a prefix from being advertised when the wildcard ::/64 prefix is used" .. start_vyoslinter @@ -56,8 +57,8 @@ Advertising a Prefix .. cfgcmd:: set service router-advert interface <interface> prefix <prefix/mask> .. note:: You can also opt for using `::/64` as prefix for your :abbr:`RAs (Router - Advertisements)`. This will take the IPv6 GUA prefix assigned to the interface, - which comes in handy when using DHCPv6-PD. + Advertisements)`. This is a special wildcard prefix that will emit :abbr:`RAs (Router Advertisements)` for every prefix assigned to the interface. + This comes in handy when using dynamically obtained prefixes from DHCPv6-PD. .. stop_vyoslinter diff --git a/docs/configuration/service/ssh.rst b/docs/configuration/service/ssh.rst index 4fa44d3e..c9969aa6 100644 --- a/docs/configuration/service/ssh.rst +++ b/docs/configuration/service/ssh.rst @@ -129,11 +129,34 @@ Configuration ``rsa-sha2-256-cert-v01@openssh.com``, ``rsa-sha2-512``, ``rsa-sha2-512-cert-v01@openssh.com`` -.. cfgcmd:: set service ssh trusted-user-ca-key ca-certificate <ca_cert_name> +.. cfgcmd:: set service ssh trusted-user-ca <name> + + Specify the name of the OpenSSH key-pair that acts as certificate authority + and will be used to verify user certificates. + + You can use it by adding the OpenSSH key-pair under the PKI subsystem. + + Example: + + .. code-block:: none + + # Generate key-pair acting as CA + $ ssh-keygen -f vyos-ssh-ca.key + + # Generate key for user: vyos_testca + $ ssh-keygen -f vyos_testca -C "vyos_tesca@vyos.net" + + # Sign public key from user vyos_testca and insert principal names: vyos, vyos_testca + # with a key lifetime of two weeks - after which the key is unusable + $ ssh-keygen -s vyos-ssh-ca.key -I vyos_testca@vyos.net -n vyos,vyos_testca -V +2w vyos_testca.pub + + $ set system login user vyos_testca + $ set pki openssh test_ca public key AAAAB3N..... + $ set pki openssh test_ca public type ssh-rsa + $ set service ssh trusted-user-ca test_ca + + You can now log into the system using: ``ssh -i vyos_testca vyos_testca@vyos.test.com`` - Specify the name of the CA certificate that will be used to verify the user - certificates. - You can use it by adding the CA certificate with the PKI command. Dynamic-protection ================== |