diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/configuration/service/conntrack-sync.rst | 3 | ||||
| -rw-r--r-- | docs/configuration/service/console-server.rst | 3 | ||||
| -rw-r--r-- | docs/configuration/service/dhcp-server.rst | 116 | ||||
| -rw-r--r-- | docs/configuration/service/dhcpv6-relay.rst | 2 | ||||
| -rw-r--r-- | docs/configuration/service/dhcpv6-server.rst | 2 | ||||
| -rw-r--r-- | docs/configuration/service/dns.rst | 73 | ||||
| -rw-r--r-- | docs/configuration/service/https.rst | 33 | ||||
| -rw-r--r-- | docs/configuration/service/index.rst | 2 | ||||
| -rw-r--r-- | docs/configuration/service/ipoe-server.rst | 8 | ||||
| -rw-r--r-- | docs/configuration/service/lldp.rst | 3 | ||||
| -rw-r--r-- | docs/configuration/service/pppoe-server.rst | 34 | ||||
| -rw-r--r-- | docs/configuration/service/router-advert.rst | 14 | ||||
| -rw-r--r-- | docs/configuration/service/snmp.rst | 7 | ||||
| -rw-r--r-- | docs/configuration/service/ssh.rst | 22 | ||||
| -rw-r--r-- | docs/configuration/service/webproxy.rst | 10 |
15 files changed, 212 insertions, 120 deletions
diff --git a/docs/configuration/service/conntrack-sync.rst b/docs/configuration/service/conntrack-sync.rst index 55cd088e..3c9f08e4 100644 --- a/docs/configuration/service/conntrack-sync.rst +++ b/docs/configuration/service/conntrack-sync.rst @@ -119,7 +119,8 @@ Now configure conntrack-sync service on ``router1`` **and** ``router2`` set service conntrack-sync mcast-group '225.0.0.50' set service conntrack-sync sync-queue-size '8' -If you are using VRRP, you need to define a VRRP sync-group, and use ``vrrp sync-group`` instead of ``cluster group``. +If you are using VRRP, you need to define a VRRP sync-group, and use +``vrrp sync-group`` instead of ``cluster group``. .. code-block:: none diff --git a/docs/configuration/service/console-server.rst b/docs/configuration/service/console-server.rst index cf222544..a509723e 100644 --- a/docs/configuration/service/console-server.rst +++ b/docs/configuration/service/console-server.rst @@ -44,7 +44,8 @@ second. This is also the default setting if none of those options are defined. Configure either one or two stop bits. This defaults to one stop bits if left unconfigured. -.. cfgcmd:: set service console-server <device> speed [ 300 | 1200 | 2400 | 4800 | 9600 | 19200 | 38400 | 57600 | 115200 ] +.. cfgcmd:: set service console-server <device> speed + [ 300 | 1200 | 2400 | 4800 | 9600 | 19200 | 38400 | 57600 | 115200 ] .. note:: USB to serial converters will handle most of their work in software so you should be carefull with the selected baudrate as some times they diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst index 6cb0bc83..3946256e 100644 --- a/docs/configuration/service/dhcp-server.rst +++ b/docs/configuration/service/dhcp-server.rst @@ -30,49 +30,57 @@ Configuration 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 <subnet> default-router <address> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + default-router <address> This is a configuration parameter for the `<subnet>`, saying that as part of the response, tell the client that the default gateway can be reached at `<address>`. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> dns-server <address> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + dns-server <address> This is a configuration parameter for the subnet, saying that as part of the response, tell the client that the DNS server can be found at `<address>`. Multiple DNS servers can be defined. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> lease <time> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + lease <time> Assign the IP address to this machine for `<time>` seconds. The default value is 86400 seconds which corresponds to one day. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> range <n> start <address> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + range <n> start <address> Create DHCP address range with a range id of `<n>`. DHCP leases are taken from this pool. The pool starts at address `<address>`. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> range <n> stop <address> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + range <n> stop <address> Create DHCP address range with a range id of `<n>`. DHCP leases are taken from this pool. The pool stops with address `<address>`. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> exclude <address> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + exclude <address> Always exclude this address from any defined range. This address will never be assigned by the DHCP server. This option can be specified multiple times. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> domain-name <domain-name> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + domain-name <domain-name> The domain-name parameter should be the domain name that will be appended to the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP Option 015). -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> domain-search <domain-name> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> + domain-search <domain-name> 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 @@ -84,21 +92,26 @@ Failover VyOS provides support for DHCP failover. DHCP failover must be configured explicitly by the following statements. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> failover local-address <address> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet + <subnet> failover local-address <address> Local IP `<address>` used when communicating to the failover peer. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> failover peer-address <address> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet + <subnet> failover peer-address <address> - Remote peer IP `<address>` of the second DHCP server in this failover cluster. + Remote peer IP `<address>` of the second DHCP server in this failover + cluster. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> failover name <name> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet + <subnet> failover name <name> A generic `<name>` referencing this sync service. .. note:: `<name>` must be identical on both sides! -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> failover status <primary | secondary> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet + <subnet> failover status <primary | secondary> The primary and secondary statements determines whether the server is primary or secondary. @@ -109,11 +122,11 @@ explicitly by the following statements. .. hint:: The dialogue between failover partners is neither encrypted nor authenticated. Since most DHCP servers exist within an organisation's own - secure Intranet, this would be an unnecessary overhead. However, if you have - DHCP failover peers whose communications traverse insecure networks, then we - recommend that you consider the use of VPN tunneling between them to ensure - that the failover partnership is immune to disruption (accidental or - otherwise) via third parties. + secure Intranet, this would be an unnecessary overhead. However, if you + have DHCP failover peers whose communications traverse insecure networks, + then we recommend that you consider the use of VPN tunneling between them + to ensure that the failover partnership is immune to disruption + (accidental or otherwise) via third parties. Static mappings --------------- @@ -122,12 +135,14 @@ 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 the subnet definition but can be outside of the range statement. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> static-mapping <description> mac-address <address> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet + <subnet> static-mapping <description> mac-address <address> Create a new DHCP static mapping named `<description>` which is valid for the host identified by its MAC `<address>`. -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> static-mapping <description> ip-address <address> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet + <subnet> static-mapping <description> ip-address <address> Static DHCP IP address assign to host identified by `<description>`. IP address must be inside the `<subnet>` which is defined but can be outside @@ -137,7 +152,8 @@ inside the subnet definition but can be outside of the range statement. This is useful, for example, in combination with hostfile update. - .. hint:: This is the equivalent of the host block in dhcpd.conf of isc-dhcpd. + .. hint:: This is the equivalent of the host block in dhcpd.conf of + isc-dhcpd. Options ======= @@ -155,12 +171,14 @@ Options * - client-prefix-length - 1 - subnet-mask - - Specifies the clients subnet mask as per RFC 950. If unset, subnet declaration is used. + - 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) + - Offset of the client's subnet in seconds from Coordinated + Universal Time (UTC) - N * - default-router - 3 @@ -390,8 +408,8 @@ Operation Mode 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 + 192.0.2.104 00:53:01: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 00:53:01: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``. @@ -425,36 +443,43 @@ Configuration Clients receiving advertise messages from multiple servers choose the server with the highest preference value. The range for this value is ``0...255``. -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> lease-time {default | maximum | minimum} +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> lease-time {default | maximum | minimum} The default lease time for DHCPv6 leases is 24 hours. This can be changed by supplying a ``default-time``, ``maximum-time`` and ``minimum-time``. All values need to be supplied in seconds. -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> nis-domain <domain-name> +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> nis-domain <domain-name> A :abbr:`NIS (Network Information Service)` domain can be set to be used for DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> nisplus-domain <domain-name> +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> nisplus-domain <domain-name> The procedure to specify a :abbr:`NIS+ (Network Information Service Plus)` domain is similar to the NIS domain one: -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> nis-server <address> +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> nis-server <address> Specify a NIS server address for DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> nisplus-server <address> +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> nisplus-server <address> Specify a NIS+ server address for DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> sip-server <address | fqdn> +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> sip-server <address | fqdn> Specify a :abbr:`SIP (Session Initiation Protocol)` server by IPv6 address of Fully Qualified Domain Name for all DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> sntp-server-address <address> +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> sntp-server-address <address> A SNTP server address can be specified for DHCPv6 clients. @@ -465,12 +490,14 @@ To hand out individual prefixes to your clients the following configuration is used: -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> prefix-delegation start <address> prefix-length <length> +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> prefix-delegation start <address> prefix-length <length> Hand out prefixes of size `<length>` to clients in subnet `<prefix>` when they request for prefix delegation. -.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> prefix-delegation start <address> stop <address> +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet + <prefix> prefix-delegation start <address> stop <address> Delegate prefixes from the range indicated by the start and stop qualifier. @@ -533,6 +560,8 @@ be created. The following example explains the process. The configuration will look as follows: +.. stop_vyoslinter (00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff false positive) + .. code-block:: none show service dhcp-server shared-network-name NET1 @@ -551,6 +580,8 @@ The configuration will look as follows: } } +.. start_vyoslinter + Operation Mode ============== @@ -636,13 +667,14 @@ Options DHCP packet size surpasses this value it will be forwarded without appending relay agent information. Range 64...1400, default 576. -.. cfgcmd:: set service dhcp-relay relay-options relay-agents-packet <append | discard | forward | replace> +.. cfgcmd:: set service dhcp-relay relay-options relay-agents-packet + <append | discard | forward | replace> Four policies for reforwarding DHCP packets exist: * **append:** The relay agent is allowed to append its own relay information - to a received DHCP packet, disregarding relay information already present in - the packet. + to a received DHCP packet, disregarding relay information already present + in the packet. * **discard:** Received packets which already contain relay information will be discarded. @@ -658,7 +690,8 @@ 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. +* 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 % @@ -697,10 +730,11 @@ Configuration Multiple interfaces may be specified. -.. cfgcmd:: set service dhcpv6-relay upstream-interface <interface> address <server> +.. cfgcmd:: set service dhcpv6-relay upstream-interface <interface> + address <server> - Specifies an upstream network `<interface>` from which replies from `<server>` - and other relay agents will be accepted. + Specifies an upstream network `<interface>` from which replies from + `<server>` and other relay agents will be accepted. Options ------- diff --git a/docs/configuration/service/dhcpv6-relay.rst b/docs/configuration/service/dhcpv6-relay.rst deleted file mode 100644 index 2d105fdf..00000000 --- a/docs/configuration/service/dhcpv6-relay.rst +++ /dev/null @@ -1,2 +0,0 @@ -dhcpv6-relay -############
\ No newline at end of file diff --git a/docs/configuration/service/dhcpv6-server.rst b/docs/configuration/service/dhcpv6-server.rst deleted file mode 100644 index 64e523a0..00000000 --- a/docs/configuration/service/dhcpv6-server.rst +++ /dev/null @@ -1,2 +0,0 @@ -dhcpv6-server -#############
\ No newline at end of file diff --git a/docs/configuration/service/dns.rst b/docs/configuration/service/dns.rst index f332c55c..204b6466 100644 --- a/docs/configuration/service/dns.rst +++ b/docs/configuration/service/dns.rst @@ -11,8 +11,8 @@ 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. -The 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 +The 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. @@ -28,9 +28,10 @@ avoid to be tracked by the provider of your upstream DNS server. .. cfgcmd:: set service dns forwarding domain <domain-name> server <address> - Forward received queries for a particular domain (specified via `domain-name`) - to a given name-server. Multiple nameservers can be specified. You can use - this feature for a DNS split-horizon configuration. + Forward received queries for a particular domain + (specified via `domain-name`) to a given name-server. Multiple nameservers + can be specified. You can use this feature for a DNS split-horizon + configuration. .. note:: This also works for reverse-lookup zones (``18.172.in-addr.arpa``). @@ -41,7 +42,8 @@ avoid to be tracked by the provider of your upstream DNS server. 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. -.. cfgcmd:: set service dns forwarding dnssec <off | process-no-validate | process | log-fail | validate> +.. cfgcmd:: set service dns forwarding dnssec + <off | process-no-validate | process | log-fail | validate> 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 @@ -103,23 +105,25 @@ avoid to be tracked by the provider of your upstream DNS server. .. cfgcmd:: set service dns forwarding listen-address - The local IPv4 or IPv6 addresses to bind the DNS forwarder to. The forwarder will listen on this address for - incoming connections. + The local IPv4 or IPv6 addresses to bind the DNS forwarder to. The forwarder + will listen on this address for incoming connections. Example ======= -A VyOS router with two interfaces - eth0 (WAN) and eth1 (LAN) - is required to implement a split-horizon DNS configuration for example.com. +A VyOS router with two interfaces - eth0 (WAN) and eth1 (LAN) - is required to +implement a split-horizon DNS configuration for example.com. In this scenario: -* All DNS requests for example.com must be forwarded to a DNS server at 192.0.2.254 - and 2001:db8:cafe::1 -* All other DNS requests will be forwarded to a different set of DNS servers at 192.0.2.1, - 192.0.2.2, 2001:db8::1:ffff and 2001:db8::2:ffff -* The VyOS DNS forwarder will only listen for requests on the eth1 (LAN) interface addresses - 192.168.1.254 - for IPv4 and 2001:db8::ffff for IPv6 -* The VyOS DNS forwarder will only accept lookup requests from the LAN subnets - 192.168.1.0/24 and 2001:db8::/64 +* All DNS requests for example.com must be forwarded to a DNS server + at 192.0.2.254 and 2001:db8:cafe::1 +* All other DNS requests will be forwarded to a different set of DNS servers at + 192.0.2.1, 192.0.2.2, 2001:db8::1:ffff and 2001:db8::2:ffff +* The VyOS DNS forwarder will only listen for requests on the eth1 (LAN) + interface addresses - 192.168.1.254 for IPv4 and 2001:db8::ffff for IPv6 +* The VyOS DNS forwarder will only accept lookup requests from the + LAN subnets - 192.168.1.0/24 and 2001:db8::/64 .. code-block:: none @@ -139,12 +143,13 @@ Operation .. opcmd:: reset dns forwarding <all | domain> - Resets the local DNS forwarding cache database. You can reset the cache for all - entries or only for entries to a specific domain. + Resets the 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 - Restarts the DNS recursor process. This also invalidates the local DNS forwarding cache. + Restarts the DNS recursor process. This also invalidates the local DNS + forwarding cache. .. _dynamic-dns: @@ -175,26 +180,31 @@ Configuration address assigned to `<interface>` on the service you configured under `<service-name>`. -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> key <keyfile> +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> + key <keyfile> File identified by `<keyfile>` containing the secret RNDC key shared with remote DNS server. -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> server <server> +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> + server <server> Configure the DNS `<server>` IP/FQDN used when updating this dynamic assignment. -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> zone <zone> +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> + zone <zone> Configure DNS `<zone>` to be updated. -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> record <record> +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> + record <record> Configure DNS `<record>` which should be updated. This can be set multiple times. -.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> ttl <ttl> +.. cfgcmd:: set service dns dynamic interface <interface> rfc2136 <service-name> + ttl <ttl> Configure optional TTL value on the given resource record. This defualts to 600 seconds. @@ -248,30 +258,35 @@ VyOS is also able to use any service relying on protocols supported by ddclient. To use such a service, one must define a login, password, one or multiple hostnames, protocol and server. -.. cfgcmd:: set service dns dynamic interface <interface> service <service> host-name <hostname> +.. cfgcmd:: set service dns dynamic interface <interface> service <service> + host-name <hostname> Setup the dynamic DNS hostname `<hostname>` associated with the DynDNS provider identified by `<service>` when the IP address on interface `<interface>` changes. -.. cfgcmd:: set service dns dynamic interface <interface> service <service> login <username> +.. cfgcmd:: set service dns dynamic interface <interface> service <service> + login <username> Configure `<username>` used when authenticating the update request for DynDNS service identified by `<service>`. For Namecheap, set the <domain> you wish to update. -.. cfgcmd:: set service dns dynamic interface <interface> service <service> password <password> +.. cfgcmd:: set service dns dynamic interface <interface> service <service> + password <password> Configure `<password>` used when authenticating the update request for DynDNS service identified by `<service>`. -.. cfgcmd:: set service dns dynamic interface <interface> service <service> protocol <protocol> +.. cfgcmd:: set service dns dynamic interface <interface> service <service> + protocol <protocol> 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> +.. cfgcmd:: set service dns dynamic interface <interface> service <service> + server <server> When a ``custom`` DynDNS provider is used the `<server>` where update requests are being sent to must be specified. diff --git a/docs/configuration/service/https.rst b/docs/configuration/service/https.rst index 49f2dbd9..b9c691da 100644 --- a/docs/configuration/service/https.rst +++ b/docs/configuration/service/https.rst @@ -39,23 +39,34 @@ leave appropriate defaults in the nginx directive. Multiple instances of Configuration mode requests --------------------------- -In our example, we are creating a dummy interface and assigning an address to it: +In our example, we are creating a dummy interface and assigning an address to +it: .. code-block:: none curl -k -X POST -F data='{"op": "set", "path": ["interfaces", "dummy", "dum1", "address"], "value": "203.0.113.76/32"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/configure -The ``/configure`` endpoint takes a request serialized in JSON. The only HTTP method it uses is POST. Request data is passed in the ``data=`` field and the API key is passed in the ``key=`` field. Key identifiers from the config are purely informational and the application doesn't need to know them, they only appear in the server logs to avoid exposing keys in log files, you only need the key itself. +The ``/configure`` endpoint takes a request serialized in JSON. The only HTTP +method it uses is POST. Request data is passed in the ``data=`` field and the +API key is passed in the ``key=`` field. Key identifiers from the config are +purely informational and the application doesn't need to know them, they only +appear in the server logs to avoid exposing keys in log files, you only need +the key itself. -Since internally there is no distinction between a path and a value, you can omit the value field and include the value in the path like it's done in the shell commands: +Since internally there is no distinction between a path and a value, you can +omit the value field and include the value in the path like it's done in the +shell commands: .. code-block:: none curl -k -X POST -F data='{"op": "set", "path": ["interfaces", "dummy", "dum10", "address", "203.0.113.99/32"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/configure -Separate value field make the semantics more clear though, and also makes it easier to create a command template once and update it with different values as needed. +Separate value field make the semantics more clear though, and also makes it +easier to create a command template once and update it with different values +as needed. -You can pass the ``set``, ``delete`` or ``comment`` command to it. The API will push the command to the session and commit. +You can pass the ``set``, ``delete`` or ``comment`` command to it. +The API will push the command to the session and commit. To retrieve a value: @@ -91,9 +102,11 @@ Passing an empty path will return the full config: Configuration management requests --------------------------------- -When saving or loading a configuration, the endpoint is ``/config-file`` and you can pass the ``save`` or ``load`` command. +When saving or loading a configuration, the endpoint is ``/config-file`` and +you can pass the ``save`` or ``load`` command. -If you don't specify the file when saving, it saves to ``/config/config.boot``. Here's an example: +If you don't specify the file when saving, it saves to ``/config/config.boot``. +Here's an example: .. code-block:: none @@ -102,7 +115,8 @@ If you don't specify the file when saving, it saves to ``/config/config.boot``. Image management requests ------------------------- -One may ``add`` or ``delete`` a system image using the endpoint ``/image``. Here are the respective examples: +One may ``add`` or ``delete`` a system image using the endpoint ``/image``. +Here are the respective examples: ``add`` from ``url``. Here we use the URL of the latest rolling release: @@ -116,7 +130,8 @@ One may ``add`` or ``delete`` a system image using the endpoint ``/image``. Here # curl -k -X POST -F data='{"op": "delete", "name": "1.3-rolling-202006070117"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/image -To list the available system images by name, one may use the operational mode request ``show`` discussed in the next section; in this setting it would be: +To list the available system images by name, one may use the operational mode +request ``show`` discussed in the next section; in this setting it would be: .. code-block:: none diff --git a/docs/configuration/service/index.rst b/docs/configuration/service/index.rst index 0ef2bbd3..e73f6dc2 100644 --- a/docs/configuration/service/index.rst +++ b/docs/configuration/service/index.rst @@ -12,8 +12,6 @@ Service console-server dhcp-relay dhcp-server - dhcpv6-relay - dhcpv6-server dns https ipoe-server diff --git a/docs/configuration/service/ipoe-server.rst b/docs/configuration/service/ipoe-server.rst index 3f794af8..7858ff19 100644 --- a/docs/configuration/service/ipoe-server.rst +++ b/docs/configuration/service/ipoe-server.rst @@ -41,8 +41,8 @@ the configuration. set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 set service ipoe-server authentication mode 'local' - set service ipoe-server dns-server server-1 '8.8.8.8' - set service ipoe-server dns-server server-2 '8.8.4.4' + set service ipoe-server dns-server server-1 '10.10.1.1' + set service ipoe-server dns-server server-2 '10.10.1.2' set service ipoe-server interface eth2 client-subnet '192.168.0.0/24' @@ -134,8 +134,8 @@ The rate-limit is set in kbit/sec. set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 rate-limit download '500' set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 rate-limit upload '500' set service ipoe-server authentication mode 'local' - set service ipoe-server dns-server server-1 '8.8.8.8' - set service ipoe-server dns-server server-2 '8.8.4.4' + set service ipoe-server dns-server server-1 '10.10.1.1' + set service ipoe-server dns-server server-2 '10.10.1.2' set service ipoe-server interface eth2 client-subnet '192.168.0.0/24' .. code-block:: none diff --git a/docs/configuration/service/lldp.rst b/docs/configuration/service/lldp.rst index 4b1743e6..aa357211 100644 --- a/docs/configuration/service/lldp.rst +++ b/docs/configuration/service/lldp.rst @@ -12,7 +12,8 @@ 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 -:abbr:`CDP (Cisco Discovery Protocol)`, :abbr:`FDP (Foundry Discovery Protocol)`, +:abbr:`CDP (Cisco Discovery Protocol)`, +:abbr:`FDP (Foundry Discovery Protocol)`, :abbr:`NDP (Nortel Discovery Protocol)` and :abbr:`LLTD (Link Layer Topology Discovery)`. diff --git a/docs/configuration/service/pppoe-server.rst b/docs/configuration/service/pppoe-server.rst index 224ff0d8..8d895f9d 100644 --- a/docs/configuration/service/pppoe-server.rst +++ b/docs/configuration/service/pppoe-server.rst @@ -29,7 +29,8 @@ First steps Use this command to define whether your PPPoE clients will locally authenticate in your VyOS system or in RADIUS server. -.. cfgcmd:: set service pppoe-server authentication local-users username <name> password <password> +.. cfgcmd:: set service pppoe-server authentication local-users username + <name> password <password> Use this command to configure the username and the password of a locally configured user. @@ -103,7 +104,8 @@ used, multiple subnets can be setup which are used sequentially. To use a radius server, you need to switch to authentication mode RADIUS and then configure it. -.. cfgcmd:: set service pppoe-server authentication radius server <address> key <secret> +.. cfgcmd:: set service pppoe-server authentication radius server <address> + key <secret> Use this command to configure the IP address and the shared secret key of your RADIUS server. You can have multiple RADIUS servers @@ -123,7 +125,8 @@ Framed-IP-Address. **RADIUS sessions management DM/CoA** -.. cfgcmd:: set service pppoe-server authentication radius dynamic-author <key | port | server> +.. cfgcmd:: set service pppoe-server authentication radius dynamic-author + <key | port | server> Use this command to configure Dynamic Authorization Extensions to RADIUS so that you can remotely disconnect sessions and change some @@ -141,7 +144,8 @@ username test .. code-block:: none - root@radius-server:~# echo "User-Name=test" | radclient -x 10.1.1.2:3799 disconnect secret123 + root@radius-server:~# echo "User-Name=test" | radclient -x 10.1.1.2:3799 + disconnect secret123 You can also use another attributes for identify client for disconnect, like Framed-IP-Address, Acct-Session-Id, etc. Result commands appears in @@ -155,7 +159,8 @@ Example for changing rate-limit via RADIUS CoA. .. code-block:: none - echo "User-Name=test,Filter-Id=5000/4000" | radclient 10.1.1.2:3799 coa secret123 + echo "User-Name=test,Filter-Id=5000/4000" | radclient 10.1.1.2:3799 coa + secret123 Filter-Id=5000/4000 (means 5000Kbit down-stream rate and 4000Kbit up-stream rate) If attribute Filter-Id redefined, replace it in RADIUS @@ -164,7 +169,8 @@ CoA request. Automatic VLAN Creation ----------------------- -.. cfgcmd:: set service pppoe-server interface <interface> <vlan-id | vlan range> <text> +.. cfgcmd:: set service pppoe-server interface <interface> + <vlan-id | vlan range> <text> VLAN's can be created by accel-ppp on the fly via the use of a Kernel module named `vlan_mon`, which is monitoring incoming vlans and @@ -193,7 +199,8 @@ attributes. For Local Users ^^^^^^^^^^^^^^^ -.. cfgcmd:: set service pppoe-server authentication local-users username <name> rate-limit <download | upload> +.. cfgcmd:: set service pppoe-server authentication local-users username <name> + rate-limit <download | upload> Use this command to configure a data-rate limit to PPPOoE clients for traffic download or upload. The rate-limit is set in kbit/sec. @@ -248,7 +255,8 @@ Load Balancing -------------- -.. cfgcmd:: set service pppoe-server pado-delay <number-of-ms> sessions <number-of-sessions> +.. cfgcmd:: set service pppoe-server pado-delay <number-of-ms> + sessions <number-of-sessions> Use this command to enable the delay of PADO (PPPoE Active Discovery Offer) packets, which can be used as a session balancing mechanism @@ -273,7 +281,8 @@ IPv6 IPv6 client's prefix assignment ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. cfgcmd:: set service pppoe-server client-ipv6-pool prefix <address> mask <number-of-bits> +.. cfgcmd:: set service pppoe-server client-ipv6-pool prefix <address> + mask <number-of-bits> Use this comand to set the IPv6 address pool from which a PPPoE client will get an IPv6 prefix of your defined length (mask) to @@ -284,7 +293,8 @@ IPv6 client's prefix assignment IPv6 Prefix Delegation ^^^^^^^^^^^^^^^^^^^^^^ -.. cfgcmd:: set service pppoe-server client-ipv6-pool delegate <address> delegation-prefix <number-of-bits> +.. cfgcmd:: set service pppoe-server client-ipv6-pool delegate <address> + delegation-prefix <number-of-bits> Use this command to configure DHCPv6 Prefix Delegation (RFC3633). You will have to set your IPv6 pool and the length of the delegation @@ -378,8 +388,8 @@ The example below covers a dual-stack configuration via pppoe-server. set service pppoe-server client-ip-pool stop '192.168.0.10' set service pppoe-server client-ipv6-pool delegate '2001:db8:8003::/48' delegation-prefix '56' set service pppoe-server client-ipv6-pool prefix '2001:db8:8002::/48' mask '64' - set service pppoe-server name-server '8.8.8.8' - set service pppoe-server name-server '2001:4860:4860::8888' + set service pppoe-server name-server '10.1.1.1' + set service pppoe-server name-server '2001:db8:4860::8888' set service pppoe-server interface 'eth2' set service pppoe-server gateway-address '10.100.100.1' diff --git a/docs/configuration/service/router-advert.rst b/docs/configuration/service/router-advert.rst index bc92f315..36fa600d 100644 --- a/docs/configuration/service/router-advert.rst +++ b/docs/configuration/service/router-advert.rst @@ -29,6 +29,8 @@ Enabling Advertisments .. cfgcmd:: set service router-advert interface <interface> .... +.. stop_vyoslinter + .. csv-table:: :header: "Field", "VyOS Option", "Description" :widths: 10, 10, 20 @@ -45,11 +47,16 @@ Enabling Advertisments "DNSSL", "dnssl", "DNS search list to advertise" "Name Server", "name-server", "Advertise DNS server per https://tools.ietf.org/html/rfc6106" +.. start_vyoslinter + + Advertising a Prefix '''''''''''''''''''' .. cfgcmd:: set service router-advert interface <interface> prefix 2001:DB8::/32 +.. stop_vyoslinter + .. csv-table:: :header: "VyOS Field", "Description" :widths: 10,30 @@ -59,6 +66,7 @@ Advertising a Prefix "preferred-lifetime","Time in seconds that the prefix will remain preferred (default 4 hours)" "valid-lifetime","Time in seconds that the prefix will remain valid (default: 30 days)" +.. start_vyoslinter Disabling Advertisements ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -78,10 +86,10 @@ Example Configuration interval { max 600 } - name-server 2001:4860:4860::8888 - name-server 2001:4860:4860::8844 + name-server 2001:db8::1 + name-server 2001:db8::2 other-config-flag - prefix 2001:DB8:beef:2::/64 { + prefix 2001:db8:beef:2::/64 { valid-lifetime 2592000 } reachable-time 0 diff --git a/docs/configuration/service/snmp.rst b/docs/configuration/service/snmp.rst index 3f445ea8..e962c1c5 100644 --- a/docs/configuration/service/snmp.rst +++ b/docs/configuration/service/snmp.rst @@ -223,10 +223,13 @@ Once the script is uploaded, it needs to be configured via the command below. set service snmp script-extensions extension-name my-extension script your_script.sh commit +.. stop_vyoslinter The OID ``.1.3.6.1.4.1.8072.1.3.2.3.1.1.4.116.101.115.116``, once called, will contain the output of the extension. +.. start_vyoslinter + .. code-block:: none root@vyos:/home/vyos# snmpwalk -v2c -c public 127.0.0.1 nsExtendOutput1 @@ -241,9 +244,12 @@ SolarWinds If you happen to use SolarWinds Orion as NMS you can also use the Device Templates Management. A template for VyOS can be easily imported. +.. stop_vyoslinter + Create a file named ``VyOS-1.3.6.1.4.1.44641.ConfigMgmt-Commands`` using the following content: + .. code-block:: none <Configuration-Management Device="VyOS" SystemOID="1.3.6.1.4.1.44641"> @@ -264,3 +270,4 @@ following content: .. _SNMPv2: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2 .. _SNMPv3: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_3 +.. start_vyoslinter
\ No newline at end of file diff --git a/docs/configuration/service/ssh.rst b/docs/configuration/service/ssh.rst index 0153d918..f7541a70 100644 --- a/docs/configuration/service/ssh.rst +++ b/docs/configuration/service/ssh.rst @@ -47,12 +47,12 @@ Configuration .. 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. + 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`` + ``aes256-cbc``, ``aes128-ctr``, ``aes192-ctr``, ``aes256-ctr``, + ``arcfour128``, ``arcfour256``, ``arcfour``, ``blowfish-cbc``, ``cast128-cbc`` .. cfgcmd:: set service ssh disable-password-authentication @@ -72,11 +72,12 @@ Configuration 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`` + ``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> @@ -95,7 +96,8 @@ Configuration 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``, + ``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``. diff --git a/docs/configuration/service/webproxy.rst b/docs/configuration/service/webproxy.rst index 654e73f2..e65c672c 100644 --- a/docs/configuration/service/webproxy.rst +++ b/docs/configuration/service/webproxy.rst @@ -68,7 +68,8 @@ first. Otherwise you will not be able to commit the config changes. * To auto update the blacklist files - :code:`set service webproxy url-filtering squidguard auto-update update-hour 23` + :code:`set service webproxy url-filtering squidguard auto-update + update-hour 23` * To configure blocking add the following to the configuration @@ -108,9 +109,12 @@ Directory as authentication backend. Queries are done via LDAP. * ``base-dn`` set the base directory for the search * ``bind-dn`` and ``password``: set the user, which is used for the ldap search -* ``filter-expression``: set the exact filter which a authorized user match in a ldap-search. In this example every User is able to authorized. +* ``filter-expression``: set the exact filter which a authorized user match in + a ldap-search. In this example every User is able to authorized. -You can find more about the ldap authentication `here <http://www.squid-cache.org/Versions/v3/3.2/manuals/basic_ldap_auth.html>`_ +You can find more about the ldap authentication +`here +<http://www.squid-cache.org/Versions/v3/3.2/manuals/basic_ldap_auth.html>`_ Adjusting cache size ^^^^^^^^^^^^^^^^^^^^ |