diff options
Diffstat (limited to 'docs/services')
| -rw-r--r-- | docs/services/dhcp.rst | 304 | ||||
| -rw-r--r-- | docs/services/dns-forwarding.rst | 163 | ||||
| -rw-r--r-- | docs/services/dynamic-dns.rst | 196 | ||||
| -rw-r--r-- | docs/services/lldp.rst | 139 | ||||
| -rw-r--r-- | docs/services/references.rst | 3 | ||||
| -rw-r--r-- | docs/services/ssh.rst | 185 | ||||
| -rw-r--r-- | docs/services/tftp.rst | 58 |
7 files changed, 703 insertions, 345 deletions
diff --git a/docs/services/dhcp.rst b/docs/services/dhcp.rst index f74195d8..1303395a 100644 --- a/docs/services/dhcp.rst +++ b/docs/services/dhcp.rst @@ -9,39 +9,33 @@ VyOS uses ISC DHCPd for both IPv4 and IPv6 address assignment. DHCP Server =========== -Multiple DHCP Servers can be run from a single machine. Each DHCP service is -identified by a ``shared-network-name``. +The network topology is declared by shared-network-name and the subnet declarations. +The DHCP service can serve multiple shared networks, with each shared network having 1 or more subnets. +Each subnet must be present on an interface. +A range can be declared inside a subnet to define a pool of dynamic addresses. +Multiple ranges can be defined and can contain holes. +Static mappings can be set to assign "static" addresses to clients based on their MAC address. Basic Example ------------- -We are offering address space in the 192.0.2.0/24 network, which is -physically connected on eth1, and pppoe0 is our connection to the internet. -We are using the network name ``<name>``. - -Prerequisites: - -* Configuring PPPoE interface is assumed to be done already, and appears - on `pppoe0` -* Interface ``eth1`` is configured to be connected to our DHCP subnet - 192.0.2.0/24 by assigning e.g. address 192.0.2.1/24. - -Multiple DHCP ranges can be defined and may contain holes. +In this example, we are offering address space in the 192.0.2.0/24 network. +We are using the network name `dhcpexample`. .. code-block:: none - set service dhcp-server shared-network-name '<name>' authoritative - set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 default-router 192.0.2.1 - set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 dns-server 192.0.2.1 - set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 lease 86400 - set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 range 0 start 192.0.2.100 - set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 range 0 stop 192.0.2.199 + set service dhcp-server shared-network-name dhcpexample authoritative + set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 default-router 192.0.2.1 + set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 dns-server 192.0.2.1 + set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 lease 86400 + set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 range 0 start 192.0.2.100 + set service dhcp-server shared-network-name dhcpexample 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 '<name>' + vyos@vyos# show service dhcp-server shared-network-name dhcpexample authoritative subnet 192.0.2.0/24 { default-router 192.0.2.1 @@ -53,23 +47,22 @@ The generated config will look like: } } - Explanation ^^^^^^^^^^^ -.. cfgcmd:: set service dhcp-server shared-network-name '<name>' authoritative +.. cfgcmd:: 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. -.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 default-router 192.0.2.1 +.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 default-router 192.0.2.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 -.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 dns-server 192.0.2.1 +.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 dns-server 192.0.2.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 @@ -77,20 +70,20 @@ 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. -.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 lease 86400 +.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.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. -.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 range 0 start 192.0.2.100 -Make a range of addresses available for clients starting from .100 [...] +.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 range 0 start 192.0.2.100 -.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 range 0 stop 192.0.2.199 +Make a range of addresses available for clients starting from .100 [...] -[...] and ending at .199 +.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 range 0 stop 192.0.2.199 +[...] and ending at .199. Failover -------- @@ -115,7 +108,7 @@ A generic name referencing this sync service. .. cfgcmd:: set service dhcp-server shared-network-name 'LAN' subnet '192.0.2.0/24' failover status '{primary|secondary}' The primary and secondary statements determines whether the server is primary -r secondary. +or secondary. .. note:: In order for the primary and the secondary DHCP server to keep their lease tables in sync, they must be able to reach each other on TCP @@ -134,16 +127,18 @@ Static mappings You can specify a static DHCP assignment on a per host basis. You will need the MAC address of the station and your desired IP address. The address must be -inside your subnet definition but can be outside of your range sttement. +inside the subnet definition but can be outside of the range statement. + +.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping static-mapping-01 mac-address ff:ff:ff:ff:ff:ff -.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 static-mapping <host> ip-address 192.0.2.10 +Each host is uniquely identified by its MAC address. -Configure desired IPv4 address for your host referenced to as `host`. +.. cfgcmd:: set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping static-mapping-01 ip-address 192.0.2.10 -.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 static-mapping <hodt> mac-address ff:ff:ff:ff:ff:ff +IP address to assign to this host. It must be inside the subnet in which it is defined but can be outside the dynamic range. +If ip-address is not specified, an IP from the dynamic pool (as specified by ``range``) is used. This is useful, for example, in combination with hostfile update. -Configure MAC address for your host referenced by as `host` used in this static -assignment. +.. hint:: This is the equivalent of the host block in dhcpd.conf of isc-dhcpd. DHCP Options ------------ @@ -170,6 +165,209 @@ The domain-name parameter should be the domain name used when completing DNS request where no full FQDN is passed. This option can be given multiple times if you need multiple search domains (DHCP Option 119). +.. list-table:: + :header-rows: 1 + :stub-columns: 0 + :widths: 12 7 23 40 20 + + * - Setting name + - Option number + - ISC-DHCP Option name + - Option description + - Multi + * - client-prefix-length + - 1 + - subnet-mask + - Specifies the clients subnet mask as per RFC 950. If unset, subnet declaration is used. + - N + * - time-offset + - 2 + - time-offset + - Offset of the client's subnet in seconds from Coordinated Universal Time (UTC) + - N + * - default-router + - 3 + - routers + - IPv4 address of router on the client's subnet + - N + * - time-server + - 4 + - time-servers + - RFC 868 time server IPv4 address + - Y + * - dns-server + - 6 + - domain-name-servers + - DNS server IPv4 address + - Y + * - domain-name + - 15 + - domain-name + - Client domain name + - Y + * - ip-forwarding + - 19 + - ip-forwarding + - Enable IP forwarding on client + - N + * - ntp-server + - 42 + - ntp-servers + - IP address of NTP server + - Y + * - wins-server + - 44 + - netbios-name-servers + - NetBIOS over TCP/IP name server + - Y + * - server-identifier + - 54 + - dhcp-server-identifier + - IP address for DHCP server identifier + - N + * - bootfile-server + - siaddr + - next-server + - IPv4 address of next bootstrap server + - N + * - tftp-server-name + - 66 + - tftp-server-name + - Name or IPv4 address of TFTP server + - N + * - bootfile-name + - 67 + - bootfile-name, filename + - Bootstrap file name + - N + * - smtp-server + - 69 + - smtp-server + - IP address of SMTP server + - Y + * - pop-server + - 70 + - pop-server + - IP address of POP3 server + - Y + * - domain-search + - 119 + - domain-search + - Client domain search + - Y + * - static-route + - 121, 249 + - rfc3442-static-route, windows-static-route + - Classless static route + - N + * - wpad-url + - 252 + - wpad-url, wpad-url code 252 = text + - Web Proxy Autodiscovery (WPAD) URL + - N + * - lease + - + - default-lease-time, max-lease-time + - Lease timeout in seconds (default: 86400) + - N + * - range + - + - range + - DHCP lease range + - Y + * - exclude + - + - + - IP address to exclude from DHCP lease range + - Y + * - failover + - + - + - DHCP failover parameters + - + * - static-mapping + - + - + - Name of static mapping + - Y + +Multi: can be specified multiple times. + +Raw parameters +-------------- + +Raw parameters can be passed to shared-network-name, subnet and static-mapping: + +.. code-block:: none + + set service dhcp-server shared-network-name dhcpexample shared-network-parameters + <text> Additional shared-network parameters for DHCP server. + set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 subnet-parameters + <text> Additional subnet parameters for DHCP server. + set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters + <text> Additional static-mapping parameters for DHCP server. + Will be placed inside the "host" block of the mapping. + +These parameters are passed as-is to isc-dhcp's dhcpd.conf under the configuration node they are defined in. +They are not validated so an error in the raw parameters won't be caught by vyos's scripts and will cause dhcpd to fail to start. +Always verify that the parameters are correct before commiting the configuration. +Refer to isc-dhcp's dhcpd.conf manual for more information: +https://kb.isc.org/docs/isc-dhcp-44-manual-pages-dhcpdconf + +Example +^^^^^^^ + +.. opcmd:: set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option domain-name-servers 192.0.2.11, 192.0.2.12;" + +Override the static-mapping's dns-server with a custom one that will be sent only to this host. + +Operation Mode +-------------- + +.. opcmd:: restart dhcp server + +Restart the DHCP server + +.. opcmd:: show dhcp server statistics + +Show the DHCP server statistics: + +.. code-block:: none + + vyos@vyos:~$ show dhcp server statistics + Pool Size Leases Available Usage + ----------- ------ -------- ----------- ------- + dhcpexample 99 2 97 2% + +.. opcmd:: show dhcp server statistics pool <pool> + +Show the DHCP server statistics for the specified pool. + +.. opcmd:: show dhcp server leases + +Show statuses of all active leases: + +.. code-block:: none + + vyos@vyos:~$ show dhcp server leases + IP address Hardware address State Lease start Lease expiration Remaining Pool Hostname + -------------- ------------------ ------- ------------------- ------------------- ---------- ----------- --------- + 192.0.2.104 aa:bb:cc:dd:ee:ff active 2019/12/05 14:24:23 2019/12/06 02:24:23 6:05:35 dhcpexample test1 + 192.0.2.115 ab:ac:ad:ae:af:bf active 2019/12/05 18:02:37 2019/12/06 06:02:37 9:43:49 dhcpexample test2 + +.. hint:: Static mappings aren't shown. To show all states, use ``show dhcp server leases state all``. + +.. opcmd:: show dhcp server leases pool <pool> + +Show only leases in the specified pool. + +.. opcmd:: show dhcp server leases sort <key> + +Sort the output by the specified key. Possible keys: ip, hardware_address, state, start, end, remaining, pool, hostname (default = ip) + +.. opcmd:: show dhcp server leases state <state> + +Show only leases with the specified state. Possible states: all, active, free, expired, released, abandoned, reset, backup (default = active) DHCPv6 Server ============= @@ -268,16 +466,16 @@ be created. The following example explains the process. **Example:** * IPv6 address ``2001:db8::101`` shall be statically mapped -* Device MAC address will be ``00:53:c5:b7:5e:23`` * Host specific mapping shall be named ``client1`` -.. hint:: The MAC address identifier is defined by the last 4 byte of the - MAC address. +.. hint:: The identifier is the device's DUID: colon-separated hex list (as used by isc-dhcp option dhcpv6.client-id). + If the device already has a dynamic lease from the DHCPv6 server, its DUID can be found with ``show service dhcpv6 server leases``. + The DUID begins at the 5th octet (after the 4th colon) of IAID_DUID. .. code-block:: none set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 ipv6-address 2001:db8::101 - set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 identifier c5b75e23 + set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 identifier 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff The configuration will look as follows: @@ -294,12 +492,11 @@ The configuration will look as follows: } static-mapping client1 { ipv6-address 2001:db8::101 - identifier c5b75e23 + identifier 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff } } } - Operation Mode -------------- @@ -315,6 +512,27 @@ To show the current status of the DHCPv6 server. Show statuses of all assigned leases: +.. code-block:: none + + vyos@vyos:~$ show dhcpv6 server leases + IPv6 address State Last communication Lease expiration Remaining Type Pool IAID_DUID + ------------- ------- -------------------- ------------------- ----------- ------------- ----- -------------------------------------------- + 2001:db8::101 active 2019/12/05 19:40:10 2019/12/06 07:40:10 11:45:21 non-temporary NET1 98:76:54:32:00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff + 2001:db8::102 active 2019/12/05 14:01:23 2019/12/06 02:01:23 6:06:34 non-temporary NET1 87:65:43:21:00:01:00:01:11:22:33:44:fa:fb:fc:fd:fe:ff + +.. hint:: Static mappings aren't shown. To show all states, use ``show dhcp server leases state all``. + +.. opcmd:: show dhcpv6 server leases pool <pool> + +Show only leases in the specified pool. + +.. opcmd:: show dhcpv6 server leases sort <key> + +Sort the output by the specified key. Possible keys: expires, iaid_duid, ip, last_comm, pool, remaining, state, type (default = ip) + +.. opcmd:: show dhcpv6 server leases state <state> + +Show only leases with the specified state. Possible states: abandoned, active, all, backup, expired, free, released, reset (default = active) DHCP Relay ========== diff --git a/docs/services/dns-forwarding.rst b/docs/services/dns-forwarding.rst index fbfac6c9..a4fbdd9f 100644 --- a/docs/services/dns-forwarding.rst +++ b/docs/services/dns-forwarding.rst @@ -1,72 +1,145 @@ +.. _dns-forwarding: + +############## 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): +Configuration +============= -.. code-block:: none +VyOS provides DNS infrastructure for small networks. It is designed to be +lightweight and have a small footprint, suitable for resource constrained +routers and firewalls, for this we utilize PowerDNS recursor. - set service dns forwarding system +VyOS DNS forwarder does not require an upstream DNS server. It can serve as a +full recursive DNS server - but it can also forward queries to configurable +upstream DNS servers. By not configuring any upstream DNS servers you also +avoid to be tracked by the provider of your upstream DNS server. -Manually setting DNS servers for forwarding: +.. cfgcmd:: set service dns forwarding system -.. code-block:: none +Forward incoming DNS queries to the DNS servers configured under the ``system +name-server`` nodes. - set service dns forwarding name-server 8.8.8.8 - set service dns forwarding name-server 8.8.4.4 +.. cfgcmd:: set service dns forwarding name-server <address> -Manually setting DNS servers with IPv6 connectivity: +Send all DNS queries to the IPv4/IPv6 DNS server specified under `<address>`. +You can configure multiple nameservers here. -.. code-block:: none +.. cfgcmd:: set service dns forwarding domain <domain-name> server <address> - set service dns forwarding name-server 2001:4860:4860::8888 - set service dns forwarding name-server 2001:4860:4860::8844 +Forward received queries for a particular domain (specified via `domain-name`) +to a given name-server. Multiple nameservers can be specified. -Setting a forwarding DNS server for a specific domain: +.. note:: This also works for reverse-lookup zones e.g. ``18.172.in-addr.arpa``. -.. code-block:: none +.. cfgcmd:: set service dns forwarding allow-from <network> - set service dns forwarding domain example.com server 192.0.2.1 +Given the fact that open DNS recursors could be used on DDOS amplification +attacts, you must configure the networks which are allowed to use this recursor. +A network of ``0.0.0.0/0`` or ``::/0`` would allow all IPv4 and IPv6 networks +to query this server. This is on general a bad idea. -Set which networks or clients are allowed to query the DNS Server. Allow from all: +.. cfgcmd:: set service dns forwarding dnssec <off | process-no-validate | process | log-fail | validate> -.. code-block:: none +The PowerDNS Recursor has 5 different levels of DNSSEC processing, which can +be set with the dnssec setting. In order from least to most processing, these +are: - set service dns forwarding allow-from 0.0.0.0/0 +* **off** In this mode, no DNSSEC processing takes place. The recursor will not + set the DNSSEC OK (DO) bit in the outgoing queries and will ignore the DO and + AD bits in queries. -Example 1 -^^^^^^^^^ +* **process-no-validate** In this mode the Recursor acts as a "security aware, + non-validating" nameserver, meaning it will set the DO-bit on outgoing queries + and will provide DNSSEC related RRsets (NSEC, RRSIG) to clients that ask for + them (by means of a DO-bit in the query), except for zones provided through + the auth-zones setting. It will not do any validation in this mode, not even + when requested by the client. -Router with two interfaces eth0 (WAN link) and eth1 (LAN). Split DNS for example.com. +* **process** When dnssec is set to process the behaviour is similar to + process-no-validate. However, the recursor will try to validate the data if + at least one of the DO or AD bits is set in the query; in that case, it will + set the AD-bit in the response when the data is validated successfully, or + send SERVFAIL when the validation comes up bogus. -* 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. +* **log-fail** In this mode, the recursor will attempt to validate all data it + retrieves from authoritative servers, regardless of the client's DNSSEC + desires, and will log the validation result. This mode can be used to + determine the extra load and amount of possibly bogus answers before turning + on full-blown validation. Responses to client queries are the same as with + process. -.. code-block:: none +* **validate** The highest mode of DNSSEC processing. In this mode, all queries + will be be validated and will be answered with a SERVFAIL in case of bogus + data, regardless of the client's request. + +.. note:: The famous UNIX/Linux ``dig`` tool sets the AD-bit in the query. This + might lead to unexpected query results when testing. Set ``+noad`` on the + ``dig`` commandline when this is the case. + +.. note:: The ``CD``-bit is honored correctly for process and validate. For + log-fail, failures will be logged too. + +.. cfgcmd:: set service dns forwarding ignore-hosts-file + +Do not use local ``/etc/hosts`` file in name resolution. VyOS DHCP server will +use this file to add resolvers to assigned addresses. - 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 +.. cfgcmd:: set service dns forwarding max-cache-entries -Example 2 -^^^^^^^^^ +Maximum number of DNS cache entries. 1 million per CPU core will generally +suffice for most installations. -Same as example 1 but with additional IPv6 addresses for Google's public DNS -servers. +.. cfgcmd:: set service dns forwarding negative-ttl -The IP addresses for the LAN interface are 192.168.0.1 and 2001:db8::1 +A query for which there is authoritatively no answer is cached to quickly deny +a record's existence later on, without putting a heavy load on the remote +server. In practice, caches can become saturated with hundreds of thousands of +hosts which are tried only once. This setting, which defaults to 3600 seconds, +puts a maximum on the amount of time negative entries are cached. + +.. cfgcmd:: set service dns forwarding listen-address + +Local IPv4 or IPv6 addresses to bind to - waiting on this address for incoming +connections. + +Example +======= + +Router with two interfaces eth0 (WAN link) and eth1 (LAN) does want to make +use of DNS split-horizon for example.com. + +* DNS request for example.com need to get forwarded to IPv4 address 192.0.2.254 + and IPv6 address 2001:db8:cafe::1 +* All other DNS requests are forwarded to DNS server listening on 192.0.2.1, + 192.0.2.2, 2001:db8::1:ffff and 2001:db8::2:ffff +* DNS server is listening on the LAN interface addresses only, 192.168.1.254 + for IPv4 and 2001:db8::ffff for IPv6 +* Only clients from the LAN segment (192.168.1.0/24) are allowed to use this + server .. 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 + set service dns forwarding domain example.com server 192.0.2.254 + set service dns forwarding domain example.com server 2001:db8:cafe::1 + set service dns forwarding name-server 192.0.2.1 + set service dns forwarding name-server 192.0.2.2 + set service dns forwarding name-server 2001:db8::1:ffff + set service dns forwarding name-server 2001:db8::2:ffff + set service dns forwarding listen-address 192.168.1.254 + set service dns forwarding listen-address 2001:db8::ffff + set service dns forwarding allow-from 192.168.1.0/24 + set service dns forwarding allow-from 2001:db8::/64 + +Operation +========= + +.. opcmd:: reset dns forwarding <all | domain> + +Reset local DNS forwarding cache database. You can reset the cache for all +entries or only for entries to a specific domain. + +.. opcmd:: restart dns forwarding + +Restart DNS recursor process which also invalidates the cache. diff --git a/docs/services/dynamic-dns.rst b/docs/services/dynamic-dns.rst index f4968295..154f9023 100644 --- a/docs/services/dynamic-dns.rst +++ b/docs/services/dynamic-dns.rst @@ -1,9 +1,12 @@ +.. _dynamic-dns: + +########### Dynamic DNS ------------ +########### VyOS is able to update a remote DNS record when an interface gets a new IP -address. In order to do so, VyOS includes ddclient_, a perl script written for -this exact purpose. +address. In order to do so, VyOS includes ddclient_, a Perl script written for +this only one purpose. ddclient_ uses two methods to update a DNS record. The first one will send updates directly to the DNS daemon, in compliance with :rfc:`2136`. The second @@ -11,141 +14,148 @@ 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 -^^^^^^^^^^^^^^^^^^^^ +Configuration +============= -First, create an :rfc:`2136` config node : +:rfc:`2136` Based +----------------- -.. code-block:: none +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> - edit service dns dynamic interface eth0 rfc2136 <confignodename> +Create new :rfc:`2136` DNS update configuration which will update the IP address +assigned to `<interface>` on the service you configured under `<service-name>`. -Present your RNDC key to ddclient : +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> key <keyfile> -.. code-block:: none +File identified by `<keyfile>` containing the secret RNDC key shared with +remote DNS server. - set key /config/dyndns/mydnsserver.rndc.key +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> server <server> -Set the DNS server IP/FQDN : - -.. code-block:: none +Configure the DNS `<server>` IP/FQDN used when updating this dynamic assignemnt. - set server dns.mydomain.com +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> zone <zone> -Set the NS zone to be updated : +Configure DNS `<zone>` to be updated. -.. code-block:: none +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> record <record> - set zone mydomain.com +Configure DNS `<record>` which should be updated. This can be set multiple +times. -Set the records to be updated : +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> ttl <ttl> -.. code-block:: none +Configure optional TTL value on the given resource record. This defualts to 600 +seconds. - set record dyn - set record dyn2 +Example +^^^^^^^ -You can optionally set a TTL (note : default value is 600 seconds) : +* Register DNS record ``example.vyos.io`` on DNS server ``ns1.vyos.io`` +* Use auth key file at ``/config/auth/my.key`` +* Set TTL to 300 seconds .. code-block:: none - set ttl 600 + vyos@vyos# show service dns dynamic + interface eth0.7 { + rfc2136 VyOS-DNS { + key /config/auth/my.key + record example.vyos.io + server ns1.vyos.io + ttl 300 + zone vyos.io + } + } -This will generate the following ddclient config blocks: +This will render the following ddclient_ configuration entry: .. 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 + # + # ddclient configuration for interface "eth0.7": + # + use=if, if=eth0.7 + + # RFC2136 dynamic DNS configuration for example.vyos.io.vyos.io + server=ns1.vyos.io protocol=nsupdate - password=/config/dyndns/mydnsserver.rndc.key - ttl=600 - zone=mydomain.com - dyn2 + password=/config/auth/my.key + ttl=300 + zone=vyos.io + example.vyos.io -You can also keep a different dns zone updated. Just create a new config node: +.. note:: You can also keep different DNS zone updated. Just create a new + config node: ``set service dns dynamic interface <interface> rfc2136 + <other-service-name>`` -.. code-block:: none +HTTP based services +------------------- - edit service dns dynamic interface eth0 rfc2136 <confignode2> +VyOS is also able to use any service relying on protocols supported by ddclient. -VyOS CLI and HTTP dynamic DNS services -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +To use such a service, one must define a login, password, one or multiple +hostnames, protocol and server. -VyOS is also able to use any service relying on protocols supported -by ddclient. +.. cfgcmd:: set service dns dynamic interface <interface> service <service> host-name <hostname> -To use such a service, you must define a login, a password, one or multiple -hostnames, a protocol and a server. +Setup the dynamic DNS hostname `<hostname>` associated with the DynDNS provider +identified by `<service>` when the IP address on interface `<interface>` +changes. -.. code-block:: none +.. cfgcmd:: set service dns dynamic interface <interface> service <service> login <username> - 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 +Configure `<username>` used when authenticating the update request for DynDNS +service identified by `<service>`. -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: +.. cfgcmd:: set service dns dynamic interface <interface> service <service> password <password> -* afraid -* changeip -* dnspark -* dslreports -* dyndns -* easydns -* namecheap -* noip -* zoneedit +Configure `<password>` used when authenticating the update request for DynDNS +service identified by `<service>`. -To use DynDNS for example: +.. cfgcmd:: set service dns dynamic interface <interface> service <service> protocol <protocol> -.. code-block:: none +When a ``custom`` DynDNS provider is used the protocol used for communicating to +the provider must be specified under `<protocol>`. See the embedded completion +helper for available protocols. + +.. cfgcmd:: set service dns dynamic interface <interface> service <service> server <server> - edit service dns dynamic interface eth0 service dyndns - set login my-login - set password my-password - set host-name my-dyndns-hostname +When a ``custom`` DynDNS provider is used the `<server>` where update requests +are beeing sent to must be specified. -It's possible to use multiple services : +Example: +^^^^^^^^ + +Use DynDNS as your preferred provider: .. 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 + set service dns dynamic interface eth0 service dyndns + set service dns dynamic interface eth0 service dyndns login my-login + set service dns dynamic interface eth0 service dyndns password my-password + set service dns dynamic interface eth0 service dyndns host-name my-dyndns-hostname + +.. note:: Multiple services can be used per interface. Just specify as many + serives per interface as you like! + +Running Behind NAT +------------------ + +By default, ddclient_ will update a dynamic dns record using the IP address directly attached to the interface. If your VyOS instance is behind NAT, your record will be updated to point to your internal IP. ddclient_ has another way to determine the WAN IP address. This is controlled -by these two options: +by: -.. code-block:: none +.. cfgcmd:: set service dns dynamic interface <interface> use-web url <url> + +Use configured `<url>` to determine your IP address. ddclient_ will load `<url>` +and tries to extract your IP address from the response. - set service dns dynamic interface eth0 use-web url - set service dns dynamic interface eth0 use-web skip +.. cfgcmd:: set service dns dynamic interface <interface> use-web skip <pattern> -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]`. +ddclient_ will skip any address located before the string set in `<pattern>`. -.. include:: references.rst +.. _ddclient: https://github.com/ddclient/ddclient diff --git a/docs/services/lldp.rst b/docs/services/lldp.rst index 3149e4ca..05c187b0 100644 --- a/docs/services/lldp.rst +++ b/docs/services/lldp.rst @@ -1,27 +1,28 @@ +.. _lldp: + +#### LLDP ----- +#### :abbr:`LLDP (Link Layer Discovery Protocol)` is a vendor-neutral link layer protocol in the Internet Protocol Suite used by network devices for advertising their identity, capabilities, and neighbors on an IEEE 802 local area network, -principally wired Ethernet.[1] The protocol is formally referred to by the IEEE +principally wired Ethernet. The protocol is formally referred to by the IEEE as Station and Media Access Control Connectivity Discovery specified in IEEE 802.1AB and IEEE 802.3-2012 section 6 clause 79. LLDP performs functions similar to several proprietary protocols, such as -`Cisco Discovery Protocol`_, `Foundry Discovery Protocol`_, -Nortel Discovery Protocol and Link Layer Topology Discovery. - -Information gathered -^^^^^^^^^^^^^^^^^^^^ +:abbr:`CDP (Cisco Discovery Protocol)`, :abbr:`FDP (Foundry Discovery Protocol)`, +:abbr:`NDP (Nortel Discovery Protocol)` and :abbr:`LLTD (Link Layer Topology +Discovery)`. -Information gathered with LLDP is stored in the device as a management -information database (MIB_) and can be queried with the Simple Network -Management Protocol (SNMP_) as specified in :rfc:`2922`. The topology of an +Information gathered with LLDP is stored in the device as a :abbr:`MIB +(Management Information Database)` and can be queried with :abbr:`SNMP (Simple +Network Management Protocol)` as specified in :rfc:`2922`. The topology of an LLDP-enabled network can be discovered by crawling the hosts and querying this database. Information that may be retrieved include: -* System name and description +* System Name and Description * Port name and description * VLAN name * IP management address @@ -31,67 +32,111 @@ database. Information that may be retrieved include: * Link aggregation Configuration -^^^^^^^^^^^^^ +============= -* Enable service with: +.. cfgcmd:: set service lldp - :code:`set service lldp` +Enable LLDP service -Options -******* +.. cfgcmd:: set service lldp management-address <address> -* Configure a Define management-address: +Define IPv4 management address transmitted via LLDP. - :code:`set service lldp management-address <x.x.x.x>` +.. cfgcmd:: set service lldp interface <interface> -* Define listening interfaces +Enable transmission of LLDP information on given `<interface>`. You can also +say ``all`` here so LLDP is turned on on every interface. - :code:`set service lldp interface <all|interface name>` +.. cfgcmd:: set service lldp interface <interface> disable -* LLDPd also implements an SNMP subagent. To Enable SNMP queries of the LLDP - database: +Disable transmit of LLDP frames on given `<interface>`. Useful to exclude +certain interfaces from LLDP when ``all`` have been enabled. - :code:`set service lldp snmp enable` +.. cfgcmd:: set service lldp snmp enable -* Enable optional/other protocols +Enable SNMP queries of the LLDP database - :code:`set service lldp legacy-protocols cdp` - Supported legacy protocols: +.. cfgcmd:: set service lldp legacy-protocols <cdp|edp|fdp|sonmp> - * ``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 +Enable given legacy protocol on this LLDP instance. Legacy protocols include: +* ``cdp`` - Listen for CDP for Cisco routers/switches +* ``edp`` - Listen for EDP for Extreme routers/switches +* ``fdp`` - Listen for FDP for Foundry routers/switches +* ``sonmp`` - Listen for SONMP for Nortel routers/switches -Display neighbors -^^^^^^^^^^^^^^^^^ +Operation +========= -* Display with: +.. opcmd:: show lldp neighbors -``show lldp neighbors`` - -Exemple: +Displays information about all neighbors discovered via LLDP. .. code-block:: none vyos@vyos:~# show lldp neighbors Capability Codes: R - Router, B - Bridge, W - Wlan r - Repeater, S - Station - D - Docsis, T - Telephone, O - Other + D - Docsis, T - Telephone, O - Other + Device ID Local Proto Cap Platform Port ID --------- ----- ----- --- -------- ------- - swA309 eth0 LLDP ? Cisco IOS Software, GigE0/33 + Switch0815 eth0 LLDP B Cisco IOS Software, Gi0/4 +.. opcmd:: show lldp neighbors detail -* Options: +Get detailed information about LLDP neighbors. - * ``detail`` - Show lldp neighbors detail - * ``interface`` - Show LLDP for specified interface - -Troubleshooting -^^^^^^^^^^^^^^^ - -Use operational command ``show log lldp`` to display logs. +.. code-block:: none -.. include:: references.rst + vyos@vyos:~# show lldp neighbors detail + ------------------------------------------------------------------------------- + LLDP neighbors: + ------------------------------------------------------------------------------- + Interface: eth0, via: LLDP, RID: 1, Time: 12 days, xxxx:xxxx:40 + Chassis: + ChassisID: mac 00:50:40:20:03:00 + SysName: Switch0815 + SysDescr: Cisco IOS Software, C2960 Software (C2960-LANBASEK9-M), Version 15.0(2)SE11, RELEASE SOFTWARE (fc3) + Technical Support: http://www.cisco.com/techsupport + Copyright (c) 1986-2017 by Cisco Systems, Inc. + Compiled Sat 19-Aug-17 09:34 by prod_rel_team + MgmtIP: 192.0.2.201 + Capability: Bridge, on + Port: + PortID: ifname Gi0/4 + PortDescr: GigabitEthernet0/4 + TTL: 120 + PMD autoneg: supported: yes, enabled: yes + Adv: 10Base-T, HD: yes, FD: yes + Adv: 100Base-TX, HD: yes, FD: yes + Adv: 1000Base-T, HD: no, FD: yes + MAU oper type: 1000BaseTFD - Four-pair Category 5 UTP, full duplex mode + VLAN: 1, pvid: yes + LLDP-MED: + Device Type: Network Connectivity Device + Capability: Capabilities, yes + Capability: Policy, yes + Capability: Location, yes + Capability: Inventory, yes + LLDP-MED Network Policy for: Voice, Defined: no + Priority: Best effort + PCP: 0 + DSCP Value: 0 + LLDP-MED Network Policy for: Voice Signaling, Defined: no + Priority: Best effort + PCP: 0 + DSCP Value: 0 + Inventory: + Hardware Revision: WS-C2960G-8TC-L (PowerPC405):C0 + Software Revision: 15.0(2)SE11 + Manufacturer: Cisco Systems, Inc. + Model: WS-C2960G-8TC-L + +.. opcmd:: show lldp neighbors interface <interface> + +Show LLDP neighbors connected via interface `<interface>`. + +.. opcmd:: show log lldp + +Used for troubleshooting. diff --git a/docs/services/references.rst b/docs/services/references.rst index 7d9ae82c..704f33f7 100644 --- a/docs/services/references.rst +++ b/docs/services/references.rst @@ -1,6 +1,3 @@ -.. _`Cisco Discovery Protocol`: https://en.wikipedia.org/wiki/Cisco_Discovery_Protocol -.. _ddclient: https://sourceforge.net/p/ddclient/wiki/Home/ -.. _`Foundry Discovery Protocol`: https://en.wikipedia.org/wiki/Foundry_Discovery_Protocol .. _MIB: https://en.wikipedia.org/wiki/Management_information_base .. _SNMP: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol .. _SNMPv2: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2 diff --git a/docs/services/ssh.rst b/docs/services/ssh.rst index 3af71899..9a1418d3 100644 --- a/docs/services/ssh.rst +++ b/docs/services/ssh.rst @@ -1,9 +1,12 @@ +.. _ssh: + +### 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 +:abbr:`SSH (Secure Shell)` is a cryptographic network protocol for operating +network services securely over an unsecured network. The standard TCP port for +SSH is 22. The best known example application is for remote login to computer systems by users. SSH provides a secure channel over an unsecured network in a client-server @@ -25,126 +28,126 @@ 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 -******* +.. cfgcmd:: set service ssh port '<number>' -* Listening address - Specify the IPv4/IPv6 listening address for connection - requests. Multiple ``listen-address`` nodes can be defined. +Enabling SSH only requires you to specify the port ``<number>`` you want SSH to +listen on. By default, SSH runs on port 22. - :code:`set service ssh listen-address <address>` +.. cfgcmd:: 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. +Specify IPv4/IPv6 listen address of SSH server. Multiple addresses can be +defined. - :code:`set service ssh allow-root` +.. cfgcmd:: set service ssh ciphers '<cipher>' -* Allowed ciphers - A number of allowed ciphers can be specified, use multiple - occurrences to allow multiple ciphers. +Define allowed ciphers used for the SSH connection. A number of allowed ciphers +can be specified, use multiple occurrences to allow multiple ciphers. - :code:`set service ssh ciphers <cipher>` +* ``3des-cbc`` +* ``aes128-cbc`` +* ``aes192-cbc`` +* ``aes256-cbc`` +* ``aes128-ctr`` +* ``aes192-ctr`` +* ``aes256-ctr`` +* ``arcfour128`` +* ``arcfour256`` +* ``arcfour`` +* ``blowfish-cbc`` +* ``cast128-cbc`` - Available ciphers: +This could be used to harden security. - * `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 authentication - If SSH key authentication is set up, - password-based user authentication can be disabled. This hardens security! +Disable password based authentication. Login via SSH keys only. This hardens +security! - :code:`set service ssh disable-password-authentication` -* Disable host validation - Disable the host validation through reverse DNS - lookups. +.. cfgcmd: set service ssh disable-host-validation - :code:`set service ssh disable-host-validation` +Disable the host validation through reverse DNS lookups - can speedup login +time when reverse lookup is not possible. -* 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. +.. cfgcmd:: set service ssh macs '<mac>' - :code:`set service ssh macs <macs>` +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: - 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`` - * `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` +This could be used to harden security. +.. note:: VyOS 1.1 supported login as user ``root``. This has been removed due + to tighter security in VyOS 1.2. -Key Authentication -################## +Key Based 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: +machine, which will (by default) save it as ``~/.ssh/id_rsa.pub``. - ``ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAA...VByBD5lKwEWB username@host.example.com`` +Every SSH key comes in three parts: -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. +``ssh-rsa AAAAB3NzaC1yc2EAAAABAA...VBD5lKwEWB 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** +.. cfgcmd:: set system login user '<username>' authentication public-keys '<identifier>' key '<key>' -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. +Assign the SSH public key portion `<key>` identified by per-key `<identifier>` +to the local user `<username>`. -.. code-block:: none +.. cfgcmd:: set system login user '<username>' authentication public-keys '<identifier>' type '<type>' - set system login user vyos authentication public-keys 'identifier' key "AAAAB3Nz...." - set system login user vyos authentication public-keys 'identifier' type ssh-rsa" +Every SSH public key portion referenced by `<identifier>` requires the +configuration of the `<type>` of public-key used. This type can be any of: -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. +* ``ecdsa-sha2-nistp256`` +* ``ecdsa-sha2-nistp384`` +* ``ecdsa-sha2-nistp521`` +* ``ssh-dss`` +* ``ssh-ed25519`` +* ``ssh-rsa`` -.. code-block:: none +.. note:: You can assign multiple keys to the same user by using a unique + identifier per SSH key. - 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 +Example +------- +In the following example, both User1 and User2 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 'User1' key "AAAAB3Nz...KwEW" + set system login user vyos authentication public-keys 'User1' type ssh-rsa + set system login user vyos authentication public-keys 'User2' key "AAAAQ39x...fbV3" + set system login user vyos authentication public-keys 'User2' type ssh-rsa diff --git a/docs/services/tftp.rst b/docs/services/tftp.rst index 9ce46b02..c33d6c7c 100644 --- a/docs/services/tftp.rst +++ b/docs/services/tftp.rst @@ -1,42 +1,54 @@ -TFTP ----- +.. _tftp-server: -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. +#### +TFTP +#### -Example -^^^^^^^ +:abbr:`TFTP (Trivial File Transfer Protocol)` is a simple, lockstep file +transfer protocol which allows a client to get a file from or put a file onto +a remote host. One of its primary uses is in the early stages of nodes booting +from a local area network. TFTP has been used for this application because it +is very simple to implement. -.. code-block:: none +Configuration +============= - # If you want to enable uploads, else TFTP server will act as read-only (optional) - set service tftp-server allow-upload +.. cfgcmd:: set service tftp-server directory '/config/tftpboot' - # Directory for TFTP server content - set service tftp-server directory '/config/tftpboot' +Enable TFTP service by specifying the directory which will be used to serve +files. - # 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 +.. hint:: Choose your ``directory`` location carefully or you will loose the content on image upgrades. Any directory under ``/config`` is save at this will be migrated. +.. cfgcmd:: set service tftp-server listen-address '<address>' + +Configure the IPv4 or IPv6 listen address of the TFTP server. Multiple IPv4 and +IPv6 addresses can be given. There will be one TFTP server instances listening +on each IP address. + .. note:: Configuring a listen-address is essential for the service to work. +.. cfgcmd:: set service tftp-server allow-upload + +Optional, if you want to enable uploads, else TFTP server will act as read-only +server. + +Example +------- + +Provide TFTP server listening on both IPv4 and IPv6 addresses ``192.0.2.1`` and +``2001:db8::1`` serving the content from ``/config/tftpboot``. Uploading via +TFTP to this server is not allowed! + The resulting configuration will look like: .. code-block:: none vyos@vyos# show service tftp-server { - allow-upload directory /config/tftpboot - listen-address 2001:db8:ffee::1 - listen-address 10.10.1.1 + listen-address 2001:db8::1 + listen-address 192.0.2.1 } - |