diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/configuration/container/index.rst | 6 | ||||
| -rw-r--r-- | docs/configuration/protocols/arp.rst | 63 | ||||
| -rw-r--r-- | docs/configuration/protocols/index.rst | 2 | ||||
| -rw-r--r-- | docs/configuration/protocols/multicast.rst | 34 | ||||
| -rw-r--r-- | docs/configuration/protocols/static.rst | 248 | ||||
| -rw-r--r-- | docs/configuration/service/monitoring.rst | 112 | ||||
| -rw-r--r-- | docs/configuration/service/ssh.rst | 6 | ||||
| -rw-r--r-- | docs/contributing/debugging.rst | 51 | ||||
| -rw-r--r-- | docs/contributing/development.rst | 21 |
9 files changed, 373 insertions, 170 deletions
diff --git a/docs/configuration/container/index.rst b/docs/configuration/container/index.rst index 3e9f6341..979996b0 100644 --- a/docs/configuration/container/index.rst +++ b/docs/configuration/container/index.rst @@ -74,6 +74,12 @@ Configuration .. note:: The first IP in the container network is reserved by the engine and cannot be used +.. cfgcmd:: set container name <name> name-server <address> + + Optionally set a custom name server. + If a container network is used with DNS enabled, + this setting will not have any effect. + .. cfgcmd:: set container name <name> description <text> Set a container description diff --git a/docs/configuration/protocols/arp.rst b/docs/configuration/protocols/arp.rst new file mode 100644 index 00000000..3d39a816 --- /dev/null +++ b/docs/configuration/protocols/arp.rst @@ -0,0 +1,63 @@ +.. _routing-static-arp: + +### +ARP +### + +:abbr:`ARP (Address Resolution Protocol)` is a communication protocol used for +discovering the link layer address, such as a MAC address, associated with a +given internet layer address, typically an IPv4 address. This mapping is a +critical function in the Internet protocol suite. ARP was defined in 1982 by +:rfc:`826` which is Internet Standard STD 37. + +In Internet Protocol Version 6 (IPv6) networks, the functionality of ARP is +provided by the Neighbor Discovery Protocol (NDP). + +To manipulate or display ARP_ table entries, the following commands are +implemented. + +********* +Configure +********* + +.. cfgcmd:: set protocols static arp interface <interface> address <host> + mac <mac> + + This will configure a static ARP entry always resolving `<address>` to + `<mac>` for interface `<interface>`. + + Example: + + .. code-block:: none + + set protocols static arp interface eth0 address 192.0.2.1 mac 01:23:45:67:89:01 + + +********* +Operation +********* + +.. opcmd:: show protocols static arp + + Display all known ARP table entries spanning across all interfaces + +.. code-block:: none + + vyos@vyos:~$ show protocols static arp + Address HWtype HWaddress Flags Mask Iface + 10.1.1.1 ether 00:53:00:de:23:2e C eth1 + 10.1.1.100 ether 00:53:00:de:23:aa CM eth1 + + +.. opcmd:: show protocols static arp interface eth1 + + Display all known ARP table entries on a given interface only (`eth1`): + +.. code-block:: none + + vyos@vyos:~$ show protocols static arp interface eth1 + Address HWtype HWaddress Flags Mask Iface + 10.1.1.1 ether 00:53:00:de:23:2e C eth1 + 10.1.1.100 ether 00:53:00:de:23:aa CM eth1 + +.. _ARP: https://en.wikipedia.org/wiki/Address_Resolution_Protocol diff --git a/docs/configuration/protocols/index.rst b/docs/configuration/protocols/index.rst index e7b1b27f..f95c1cf6 100644 --- a/docs/configuration/protocols/index.rst +++ b/docs/configuration/protocols/index.rst @@ -6,6 +6,7 @@ Protocols :maxdepth: 1 :includehidden: + arp babel bfd bgp @@ -13,6 +14,7 @@ Protocols igmp-proxy isis mpls + multicast segment-routing openfabric ospf diff --git a/docs/configuration/protocols/multicast.rst b/docs/configuration/protocols/multicast.rst new file mode 100644 index 00000000..61a04e5e --- /dev/null +++ b/docs/configuration/protocols/multicast.rst @@ -0,0 +1,34 @@ +.. _routing-static: + +######### +Multicast +######### + +In order to influence Multicast :abbr:`RPF (Reverse Path Forwarding)` lookup, +it is possible to insert into zebra routes for the Multicast +:abbr:`RIB (Routing Information Base)`. These routes are only used for RPF +lookup and will not be used by ZEBRA for insertion into the kernel or for +normal RIB processing. As such it is possible to create weird states with +these commands. + +Use with caution. Most of the time this will not be necessary. + +.. cfgcmd:: set protocols static mroute <subnet> next-hop <address> + [distance <distance>] + + Insert into the Multicast RIB Route `<subnet>` with specified next-hop. + The distance can be specified as well if desired. + +.. cfgcmd:: set protocols static mroute <subnet> next-hop <address> disable + + Do not install route for `<subnet>` into the Multicast RIB. + +.. cfgcmd:: set protocols static mroute <subnet> interface <interface> + [distance <distance>] + + Insert into the Multicast RIB Route `<subnet>` with specified `<interface>`. + The distance can be specified as well if desired. + +.. cfgcmd:: set protocols static mroute <subnet> interface <interface> disable + + Do not install route for `<subnet>` into the Multicast RIB. diff --git a/docs/configuration/protocols/static.rst b/docs/configuration/protocols/static.rst index 02c9e91b..3e3eb47b 100644 --- a/docs/configuration/protocols/static.rst +++ b/docs/configuration/protocols/static.rst @@ -15,9 +15,9 @@ collection of all routes the router has learned from its configuration or from its dynamic routing protocols is stored in the RIB. Unicast routes are directly used to determine the forwarding table used for unicast packet forwarding. -************* -Static Routes -************* +******************* +IPv4 Unicast Routes +******************* .. cfgcmd:: set protocols static route <subnet> next-hop <address> @@ -39,6 +39,100 @@ Static Routes .. note:: Routes with a distance of 255 are effectively disabled and not installed into the kernel. +IPv4 Interface Routes +===================== + +.. cfgcmd:: set protocols static route <subnet> interface + <interface> + + Allows you to configure the next-hop interface for an interface-based IPv4 + static route. `<interface>` will be the next-hop interface where traffic is + routed for the given `<subnet>`. + +.. cfgcmd:: set protocols static route <subnet> interface + <interface> disable + + Disables interface-based IPv4 static route. + +.. cfgcmd:: set protocols static route <subnet> interface + <interface> distance <distance> + + Defines next-hop distance for this route, routes with smaller administrative + distance are elected prior to those with a higher distance. + + Range is 1 to 255, default is 1. + +IPv4 BFD +======== + +.. cfgcmd:: set protocols static route <subnet> next-hop <address> bfd + + Configure a static route for `<subnet>` using gateway `<address>` and use the + gateway address as BFD peer destination address. + +.. cfgcmd:: set protocols static route <subnet> next-hop <address> bfd profile <profile> + + Configure a static route for `<subnet>` using gateway `<address>` and use the + gateway address as BFD peer destination address with BFD profile `<profile>`. + +.. cfgcmd:: set protocols static route <subnet> next-hop <address> bfd multi-hop + source-address <source-address> + + Configure a static route for `<subnet>` using gateway `<address>` and use the + gateway address as BFD peer destination address with source address + `<source>` but initiate a multi-hop session. + +DHCP Interface Routes +===================== + +.. cfgcmd:: set protocols static route <subnet> dhcp-interface <interface> + + Defines route with DHCP interface supplying next-hop IP address. + +IPv4 Reject Routes +================== + +.. cfgcmd:: set protocol static route <subnet> reject + + Defines route which emits an ICMP unreachable when matched. + +.. cfgcmd:: set protocols static route <subnet> reject distance <distance> + + Defines distance for this route, routes with smaller administrative + distance are elected prior to those with a higher distance. + +.. cfgcmd:: set protocols static route <subnet> reject tag <tag> + + Sets a tag for this route. + +.. cfgcmd:: set protocol static route6 <subnet> reject + + Defines route which emits an ICMP unreachable when matched. + +IPv4 Blackhole Routes +===================== + +.. cfgcmd:: set protocols static route <subnet> blackhole + + Use this command to configure a "black-hole" route on the router. A + black-hole route is a route for which the system silently discard packets + that are matched. This prevents networks leaking out public interfaces, but + it does not prevent them from being used as a more specific route inside your + network. + +.. cfgcmd:: set protocols static route <subnet> blackhole distance <distance> + + Defines blackhole distance for this route, routes with smaller administrative + distance are elected prior to those with a higher distance. + +.. cfgcmd:: set protocols static route <subnet> blackhole tag <tag> + + Sets a tag for this route. + +******************* +IPv6 Unicast Routes +******************* + .. cfgcmd:: set protocols static route6 <subnet> next-hop <address> Configure next-hop `<address>` for an IPv6 static route. Multiple static @@ -82,29 +176,8 @@ Static Routes C>* 2001:db8:201::/64 is directly connected, eth0.201, 00:00:46 S>* 2001:db8:1000::/36 [1/0] via 2001:db8:201::ffff, eth0.201, seg6 2001:db8:aaaa::7,2002::4,2002::3,2002::2, weight 1, 00:00:08 - -Interface Routes -================ - -.. cfgcmd:: set protocols static route <subnet> interface - <interface> - - Allows you to configure the next-hop interface for an interface-based IPv4 - static route. `<interface>` will be the next-hop interface where traffic is - routed for the given `<subnet>`. - -.. cfgcmd:: set protocols static route <subnet> interface - <interface> disable - - Disables interface-based IPv4 static route. - -.. cfgcmd:: set protocols static route <subnet> interface - <interface> distance <distance> - - Defines next-hop distance for this route, routes with smaller administrative - distance are elected prior to those with a higher distance. - - Range is 1 to 255, default is 1. +IPv6 Interface Routes +===================== .. cfgcmd:: set protocols static route6 <subnet> interface <interface> @@ -138,30 +211,28 @@ Interface Routes set protocols static route6 2001:db8:1000::/36 interface eth0 segments '2001:db8:aaaa::7/2002::4/2002::3/2002::2' +IPv6 BFD +======== -DHCP Interface Routes -===================== +.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> bfd -.. cfgcmd:: set protocols static route <subnet> dhcp-interface <interface> + Configure a static route for `<subnet>` using gateway `<address>` and use the + gateway address as BFD peer destination address. - Defines route with DHCP interface supplying next-hop IP address. - - -Reject Routes -============= - -.. cfgcmd:: set protocol static route <subnet> reject +.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> bfd profile <profile> - Defines route which emits an ICMP unreachable when matched. + Configure a static route for `<subnet>` using gateway `<address>` and use the + gateway address as BFD peer destination address with BFD profile `<profile>`. -.. cfgcmd:: set protocols static route <subnet> reject distance <distance> +.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> bfd multi-hop + source-address <source> - Defines distance for this route, routes with smaller administrative - distance are elected prior to those with a higher distance. + Configure a static route for `<subnet>` using gateway `<address>` and use the + gateway address as BFD peer destination address with source address + `<source>` but initiate a multi-hop session. -.. cfgcmd:: set protocols static route <subnet> reject tag <tag> - - Sets a tag for this route. +IPv6 Reject Routes +================== .. cfgcmd:: set protocol static route6 <subnet> reject @@ -176,26 +247,8 @@ Reject Routes Sets a tag for this route. - -Blackhole Routes -================ - -.. cfgcmd:: set protocols static route <subnet> blackhole - - Use this command to configure a "black-hole" route on the router. A - black-hole route is a route for which the system silently discard packets - that are matched. This prevents networks leaking out public interfaces, but - it does not prevent them from being used as a more specific route inside your - network. - -.. cfgcmd:: set protocols static route <subnet> blackhole distance <distance> - - Defines blackhole distance for this route, routes with smaller administrative - distance are elected prior to those with a higher distance. - -.. cfgcmd:: set protocols static route <subnet> blackhole tag <tag> - - Sets a tag for this route. +IPv6 Blackhole Routes +===================== .. cfgcmd:: set protocols static route6 <subnet> blackhole @@ -214,76 +267,11 @@ Blackhole Routes Sets a tag for this route. +************************ Alternate Routing Tables -======================== +************************ TBD Alternate routing tables are used with policy based routing by utilizing :ref:`vrf`. - - -.. _routing-arp: - -### -ARP -### - -:abbr:`ARP (Address Resolution Protocol)` is a communication protocol used for -discovering the link layer address, such as a MAC address, associated with a -given internet layer address, typically an IPv4 address. This mapping is a -critical function in the Internet protocol suite. ARP was defined in 1982 by -:rfc:`826` which is Internet Standard STD 37. - -In Internet Protocol Version 6 (IPv6) networks, the functionality of ARP is -provided by the Neighbor Discovery Protocol (NDP). - -To manipulate or display ARP_ table entries, the following commands are -implemented. - -********* -Configure -********* - -.. cfgcmd:: set protocols static arp interface <interface> address <host> - mac <mac> - - This will configure a static ARP entry always resolving `<address>` to - `<mac>` for interface `<interface>`. - - Example: - - .. code-block:: none - - set protocols static arp interface eth0 address 192.0.2.1 mac 01:23:45:67:89:01 - - -********* -Operation -********* - - -.. opcmd:: show protocols static arp - - Display all known ARP table entries spanning across all interfaces - -.. code-block:: none - - vyos@vyos:~$ show protocols static arp - Address HWtype HWaddress Flags Mask Iface - 10.1.1.1 ether 00:53:00:de:23:2e C eth1 - 10.1.1.100 ether 00:53:00:de:23:aa CM eth1 - - -.. opcmd:: show protocols static arp interface eth1 - - Display all known ARP table entries on a given interface only (`eth1`): - -.. code-block:: none - - vyos@vyos:~$ show protocols static arp interface eth1 - Address HWtype HWaddress Flags Mask Iface - 10.1.1.1 ether 00:53:00:de:23:2e C eth1 - 10.1.1.100 ether 00:53:00:de:23:aa CM eth1 - -.. _ARP: https://en.wikipedia.org/wiki/Address_Resolution_Protocol diff --git a/docs/configuration/service/monitoring.rst b/docs/configuration/service/monitoring.rst index 10b4dee2..37dc6b43 100644 --- a/docs/configuration/service/monitoring.rst +++ b/docs/configuration/service/monitoring.rst @@ -1,9 +1,27 @@ +########## Monitoring ----------- +########## -Azure-data-explorer +VyOS supports monitoring through Telegraf as well as through Prometheus exporters. + +******** +Telegraf +******** + +Telegraf is the open source server agent to help you collect metrics, events +and logs from your routers. + +The following Telegraf plugins are configurable to export metrics and logs: + * Azure Data Explorer + * Prometheus Client + * Splunk + * InfluxDB + * Loki + + +Azure data explorer =================== -Telegraf output plugin azure-data-explorer_ +Telegraf output plugin azure-data-explorer_. .. cfgcmd:: set service monitoring telegraf azure-data-explorer authentication client-id <client-id> @@ -34,9 +52,12 @@ Telegraf output plugin azure-data-explorer_ Remote URL. -Prometheus-client + +Prometheus client ================= Telegraf output plugin prometheus-client_ +This plugin allows export of Telegraf metrics to Prometheus, +for Prometheus native metrics through exporters see section below. .. cfgcmd:: set service monitoring telegraf prometheus-client @@ -79,9 +100,10 @@ Example: cpu_usage_system{cpu="cpu0",host="r14"} 0.17182130584191915 cpu_usage_system{cpu="cpu1",host="r14"} 0.22896393817971655 + Splunk ====== -Telegraf output plugin splunk_. HTTP Event Collector. +Telegraf output plugin splunk_ HTTP Event Collector. .. cfgcmd:: set service monitoring telegraf splunk authentication insecure @@ -103,11 +125,10 @@ Example: set service monitoring telegraf splunk authentication token 'xxxxf5b8-xxxx-452a-xxxx-43828911xxxx' set service monitoring telegraf splunk url 'https://192.0.2.10:8088/services/collector' -Telegraf + +InfluxDB ======== -Monitoring functionality with ``telegraf`` and ``InfluxDB 2`` is provided. -Telegraf is the open source server agent to help you collect metrics, events -and logs from your routers. +Telegraf output plugin influxdb_ to write metrics to ``InfluxDB`` via HTTP. .. cfgcmd:: set service monitoring telegraf influxdb authentication organization <organization> @@ -130,10 +151,21 @@ and logs from your routers. Remote URL +Example: + +.. code-block:: none + + set service monitoring telegraf influxdb authentication organization 'vyos' + set service monitoring telegraf influxdb authentication token 'ZAml9Uy5wrhA...==' + set service monitoring telegraf influxdb bucket 'bucket_vyos' + set service monitoring telegraf influxdb port '8086' + set service monitoring telegraf influxdb url 'http://r1.influxdb2.local' + + Loki ==== -Telegraf can be used to send logs to Loki using tags as labels. +Telegraf can be used to send logs to loki_ using tags as labels. .. cfgcmd:: set service monitoring telegraf loki port <port> @@ -160,20 +192,54 @@ Telegraf can be used to send logs to Loki using tags as labels. This is NOT recommended, as it makes it impossible to differentiate between multiple metrics. -Example -======= +.. _azure-data-explorer: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/azure_data_explorer +.. _prometheus-client: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/prometheus_client +.. _influxdb: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/influxdb_v2 +.. _splunk: https://www.splunk.com/en_us/blog/it/splunk-metrics-via-telegraf.html +.. _loki: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/loki -An example of a configuration that sends ``telegraf`` metrics to remote -``InfluxDB 2`` -.. code-block:: none +********** +Prometheus +********** - set service monitoring telegraf influxdb authentication organization 'vyos' - set service monitoring telegraf influxdb authentication token 'ZAml9Uy5wrhA...==' - set service monitoring telegraf influxdb bucket 'bucket_vyos' - set service monitoring telegraf influxdb port '8086' - set service monitoring telegraf influxdb url 'http://r1.influxdb2.local' +The following Prometheus exporters are configurable to export metrics: + * Node Exporter + * FRR Exporter -.. _azure-data-explorer: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/azure_data_explorer -.. _prometheus-client: https://github.com/influxdata/telegraf/tree/master/plugins/outputs/prometheus_client -.. _splunk: https://www.splunk.com/en_us/blog/it/splunk-metrics-via-telegraf.html + +Node Exporter +============= +Prometheus node_exporter_ which provides a wide range of hardware and OS metrics. + +.. cfgcmd:: set service monitoring prometheus node-exporter listen-address <address> + + Configure the address node_exporter is listening on. + +.. cfgcmd:: set service monitoring prometheus node-exporter port <port> + + Configure the port number node_exporter is listening on. + +.. cfgcmd:: set service monitoring prometheus node-exporter vrf <name> + + Configure name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance. + + +FRR Exporter +============ +Prometheus frr_exporter_ which provides free range routing metrics. + +.. cfgcmd:: set service monitoring prometheus frr-exporter listen-address <address> + + Configure the address frr_exporter is listening on. + +.. cfgcmd:: set service monitoring prometheus frr-exporter port <port> + + Configure the port number frr_exporter is listening on. + +.. cfgcmd:: set service monitoring prometheus frr-exporter vrf <name> + + Configure name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance. + +.. _node_exporter: https://github.com/prometheus/node_exporter +.. _frr_exporter: https://github.com/tynany/frr_exporter
\ No newline at end of file diff --git a/docs/configuration/service/ssh.rst b/docs/configuration/service/ssh.rst index e7642433..17e6c6df 100644 --- a/docs/configuration/service/ssh.rst +++ b/docs/configuration/service/ssh.rst @@ -129,6 +129,12 @@ Configuration ``rsa-sha2-256-cert-v01@openssh.com``, ``rsa-sha2-512``, ``rsa-sha2-512-cert-v01@openssh.com`` +.. cfgcmd::set service ssh trusted-user-ca-key ca-certificate <ca_cert_name> + + Specify the name of the CA certificate that will be used to verify the user + certificates. + You can use it by adding the CA certificate with the PKI command. + Dynamic-protection ================== Protects host from brute-force attacks against diff --git a/docs/contributing/debugging.rst b/docs/contributing/debugging.rst index e03f3f81..e443feee 100644 --- a/docs/contributing/debugging.rst +++ b/docs/contributing/debugging.rst @@ -131,28 +131,49 @@ Useful commands are: Config Migration Scripts ------------------------ -When writing a new configuration migrator it may happen that you see an error -when you try to invoke it manually on a development system. This error will -look like: +Starting with VyOS 1.5 a new mechanism is used for config migration whichwill improve +migration performance. New migrators only exist in the new format with a migration() +function. + +.. code-block:: python + + from vyos.configtree import ConfigTree + base = ['vpn', 'ipsec'] + def migrate(config: ConfigTree) -> None: + if not config.exists(base): + # Nothing to do + return + # do your stuff here + +New style migrations scripts can no longer be executed on their own. The new +handler of the entire migration subsystem on the other hand comes with a handy +test kit: .. code-block:: none - vyos@vyos:~$ /opt/vyatta/etc/config-migrate/migrate/ssh/0-to-1 /tmp/config.boot - Traceback (most recent call last): - File "/opt/vyatta/etc/config-migrate/migrate/ssh/0-to-1", line 31, in <module> - config = ConfigTree(config_file) - File "/usr/lib/python3/dist-packages/vyos/configtree.py", line 134, in __init__ - raise ValueError("Failed to parse config: {0}".format(msg)) - ValueError: Failed to parse config: Syntax error on line 240, character 1: Invalid syntax. + vyos@vyos:~$ /usr/libexec/vyos/run-config-migration.py --help + usage: run-config-migration.py [-h] [--test-script TEST_SCRIPT] [--output-file OUTPUT_FILE] [--force] config_file + + positional arguments: + config_file configuration file to migrate -The reason is that the configuration migration backend is rewritten and uses -a new form of "magic string" which is applied on demand when real config -migration is run on boot. When running individual migrators for testing, -you need to convert the "magic string" on your own by: + options: + -h, --help show this help message and exit + --test-script TEST_SCRIPT + test named script + --output-file OUTPUT_FILE + write to named output file instead of config file + --force force run of all migration scripts + + +So in order to test your migrator you can run this as simple as: .. code-block:: none - vyos@vyos:~$ /usr/libexec/vyos/run-config-migration.py --virtual --set-vintage vyos /tmp/config.boot + vyos@vyos:~$ /usr/libexec/vyos/run-config-migration.py --test-script /opt/vyatta/etc/config-migrate/migrate/quagga/11-to-12 --output-file /tmp/foo /tmp/static-route-basic + vyos@vyos:~$ cat /tmp/foo + +Where `/tmp/foo` will contain the migrated configuration. Configuration Error on System Boot ---------------------------------- diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst index e39af3a5..c5df8b12 100644 --- a/docs/contributing/development.rst +++ b/docs/contributing/development.rst @@ -290,7 +290,7 @@ device if you happen to be a crazy scientist. from vyos.config import Config from vyos import ConfigError - def get_config(): + def get_config(config=None): if config: conf = config else: @@ -306,7 +306,6 @@ device if you happen to be a crazy scientist. # Verify that configuration is valid if invalid: raise ConfigError("Descriptive message") - return True def generate(config): # Generate daemon configs @@ -385,6 +384,24 @@ For easy orientation we suggest you take a look on the ``ntp.py`` or ``interfaces-bonding.py`` (for tag nodes) implementation. Both files can be found in the vyos-1x_ repository. +Other considerations: vyos-configd +---------------------------------- + +All scripts now run under the config daemon and must conform to the +following: + +1. The signature and initial four lines of ``get_config(...)`` `must` be as + above. + +2. Each of ``get_config``, ``verify``, ``apply``, ``generate`` `must` + appear, with signatures as above, even if they are a no-op. + +3. Instantiations of ``Config`` other than that in ``get_config`` `must not` + appear. + +4. The legacy function ``my_set`` `must not` appear: modifications of the + active config `should not` appear in new code (if absolutely necessary, + alternative mechanisms may be used). XML (used for CLI definitions) ============================== |