From 371bf8185f3cd0628969a8603aa92503b2fc3853 Mon Sep 17 00:00:00 2001 From: rebortg Date: Sun, 29 Nov 2020 19:08:35 +0100 Subject: rearange changelog, cli, contributing --- docs/automation/index.rst | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 docs/automation/index.rst (limited to 'docs/automation') diff --git a/docs/automation/index.rst b/docs/automation/index.rst new file mode 100644 index 00000000..a3df9bc0 --- /dev/null +++ b/docs/automation/index.rst @@ -0,0 +1,9 @@ +############### +VyOS Automation +############### + + + * Ansible + * Saltstack + * HTTP-API + * startup scripts \ No newline at end of file -- cgit v1.2.3 From a3f7e4ae450248bb5b28474d908e51e6560cb68d Mon Sep 17 00:00:00 2001 From: rebortg Date: Sun, 29 Nov 2020 19:36:16 +0100 Subject: arange http-api and command-scripting --- docs/appendix/command-scripting.rst | 127 -------------- docs/appendix/http-api.rst | 166 ------------------ docs/appendix/release-notes.rst | 305 ---------------------------------- docs/automation/command-scripting.rst | 127 ++++++++++++++ docs/automation/http-api.rst | 166 ++++++++++++++++++ docs/automation/index.rst | 9 +- 6 files changed, 301 insertions(+), 599 deletions(-) delete mode 100644 docs/appendix/command-scripting.rst delete mode 100644 docs/appendix/http-api.rst delete mode 100644 docs/appendix/release-notes.rst create mode 100644 docs/automation/command-scripting.rst create mode 100644 docs/automation/http-api.rst (limited to 'docs/automation') diff --git a/docs/appendix/command-scripting.rst b/docs/appendix/command-scripting.rst deleted file mode 100644 index 7d0ab6c5..00000000 --- a/docs/appendix/command-scripting.rst +++ /dev/null @@ -1,127 +0,0 @@ -.. _command-scripting: - -Command Scripting -================= - -VyOS supports executing configuration and operational commands non-interactively -from shell scripts. - -To include VyOS specific functions and aliases you need to ``source -/opt/vyatta/etc/functions/script-template`` files at the top of your script. - -.. code-block:: none - - #!/bin/vbash - source /opt/vyatta/etc/functions/script-template - exit - -Run configuration commands --------------------------- - -Configuration commands are executed just like from a normal config session. For -example, if you want to disable a BGP peer on VRRP transition to backup: - -.. code-block:: none - - #!/bin/vbash - source /opt/vyatta/etc/functions/script-template - configure - set protocols bgp 65536 neighbor 192.168.2.1 shutdown - commit - exit - -Run operational commands ------------------------- - -Unlike a normal configuration sessions, all operational commands must be -prepended with ``run``, even if you haven't created a session with configure. - -.. code-block:: none - - #!/bin/vbash - source /opt/vyatta/etc/functions/script-template - run show interfaces - exit - -Other script language ---------------------- - -If you want to script the configs in a language other than bash you can have -your script output commands and then source them in a bash script. - -Here is a simple example: - -.. code-block:: python - - #!/usr/bin/env python - print "delete firewall group address-group somehosts" - print "set firewall group address-group somehosts address '192.0.2.3'" - print "set firewall group address-group somehosts address '203.0.113.55'" - - -.. code-block:: none - - #!/bin/vbash - source /opt/vyatta/etc/functions/script-template - configure - source < /config/scripts/setfirewallgroup.py - commit - - -Executing Configuration Scripts -------------------------------- - -There is a pitfall when working with configuration scripts. It is tempting to -call configuration scripts with "sudo" (i.e., temporary root permissions), -because that's the common way on most Linux platforms to call system commands. - -On VyOS this will cause the following problem: After modifying the configuration -via script like this once, it is not possible to manually modify the config -anymore: - -.. code-block:: none - - sudo ./myscript.sh # Modifies config - configure - set ... # Any configuration parameter - -This will result in the following error message: ``Set failed`` If this happens, -a reboot is required to be able to edit the config manually again. - -To avoid these problems, the proper way is to call a script with the -``vyattacfg`` group, e.g., by using the ``sg`` (switch group) command: - -.. code-block:: none - - sg vyattacfg -c ./myscript.sh - -To make sure that a script is not accidentally called without the ``vyattacfg`` -group, the script can be safeguarded like this: - -.. code-block:: none - - if [ "$(id -g -n)" != 'vyattacfg' ] ; then - exec sg vyattacfg -c "/bin/vbash $(readlink -f $0) $@" - fi - -Postconfig on boot ------------------- - -The ``/config/scripts/vyos-postconfig-bootup.script`` script is called on boot -after the VyOS configuration is fully applied. - -Any modifications done to work around unfixed bugs and implement enhancements -which are not complete in the VyOS system can be placed here. - -The default file looks like this: - -.. code-block:: none - - #!/bin/sh - # This script is executed at boot time after VyOS configuration is fully - # applied. Any modifications required to work around unfixed bugs or use - # services not available through the VyOS CLI system can be placed here. - -.. hint:: For configuration/upgrade management issues, modification of this - script should be the last option. Always try to find solutions based on CLI - commands first. diff --git a/docs/appendix/http-api.rst b/docs/appendix/http-api.rst deleted file mode 100644 index 49f2dbd9..00000000 --- a/docs/appendix/http-api.rst +++ /dev/null @@ -1,166 +0,0 @@ -.. _http-api: - -######## -HTTP-API -######## - -Enabling HTTP-API ------------------ - -VyOS HTTP API can be enabled through the ``set service https api`` command. - -.. code-block:: none - - set service https api debug - set service https api keys id MY-HTTP-API-ID key MY-HTTP-API-PLAINTEXT-KEY - -The local API process listens on localhost:8080, and nginx exposes it on all -virtual servers, by default. For the purpose of illustration below, we will -assume nginx is running at https://192.168.122.127. - -One can limit proxying to specific listen addresses/ports/server-names by -defining a ``service https virtual-host ``, and setting ``service https -api-restrict virtual-host ``. - -.. code-block:: none - - set service https virtual-host example listen-address 192.168.122.127 - set service https virtual-host example listen-port 44302 - set service https virtual-host example server-name example.net - - set service https api-restrict virtual-host example - -In this example, nginx will proxy only those requests to -192.168.122.127:44302 or example.net:44302 (assuming the DNS record is -viable). Omitting any of listen-address, listen-port, or server-name, will -leave appropriate defaults in the nginx directive. Multiple instances of -``service https api-restrict virtual-host`` may be set. - -Configuration mode requests ---------------------------- - -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. - -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. - -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: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "returnValue", "path": ["interfaces", "dummy", "dum1", "address"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve - -Use ``returnValues`` for multi-valued nodes. - - -Show config -""""""""""" - -To retrieve the full config under a path: - -.. code-block:: none - - # curl -k -X POST -F data='{"op": "showConfig", "path": ["interfaces", "dummy"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve - -It will return: - -.. code-block:: none - - {"success": true, "data": {"dummy": {"dum1": {"address": "203.0.113.76/32"}}}, "error": null} - -Passing an empty path will return the full config: - -.. code-block:: none - - # curl -k -X POST -F data='{"op": "showConfig", "path": []}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve - - -Configuration management requests ---------------------------------- - -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: - -.. code-block:: none - - # curl -k -X POST -F key=MY-HTTP-API-PLAINTEXT-KEY -Fdata='{"op": "save", "file": "/config/config.boot"}' https://192.168.122.127/config-file - -Image management requests -------------------------- - -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: - -.. code-block:: none - - # curl -k -X POST -F data='{"op": "add", "url": "https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/image - -``delete`` by image ``name``. For example: - -.. code-block:: none - - # 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: - -.. code-block:: none - - # curl -k -X POST -F data='{"op": "show", "path": ["system", "image"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show - -Operational mode requests -------------------------- - -It is possible to run ``show`` and ``generate`` commands: - - -Request: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "generate", "path": ["wireguard", "default-keypair"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/generate - -Response: - -.. code-block:: none - - {"success": true, "data": "", "error": null} - -Request: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "show", "path": ["wireguard", "keypairs", "pubkey", "default"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show - -Response: - -.. code-block:: none - - {"success": true, "data": "=\n", "error": null} - -Request: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "show", "path": ["ip", "route"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show - -Response: - -.. code-block:: none - - {"success": true, "data": "Codes: K - kernel route, C - connected, S - static, R - RIP,\n O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP,\n T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP,\n F - PBR, f - OpenFabric,\n > - selected route, * - FIB route, q - queued route, r - rejected route\n\nS>* 0.0.0.0/0 [210/0] via 192.168.100.1, eth0, 01:41:05\nC>* 192.168.0.0/24 is directly connected, eth1, 01:41:09\nC>* 192.168.100.0/24 is directly connected, eth0, 01:41:05\nC>* 203.0.113.76/32 is directly connected, dum1, 01:38:40\n", "error": null} - diff --git a/docs/appendix/release-notes.rst b/docs/appendix/release-notes.rst deleted file mode 100644 index 89454fa0..00000000 --- a/docs/appendix/release-notes.rst +++ /dev/null @@ -1,305 +0,0 @@ -.. _release-notes: - -############# -Release Notes -############# - -1.2 (Crux) -========== - -1.2.5 ------ - -1.2.5 is a maintenance release made in April 2020. - -Resolved issues -^^^^^^^^^^^^^^^ - -* :vytask:`1020` OSPF Stops distributing default route after a while -* :vytask:`1228` pppoe default-route force option not working (Rel 1.2.0-rc11) -* :vytask:`1301` bgp peer-groups don't work when "no-ipv4-unicast" is enabled. -* :vytask:`1341` Adding rate-limiter for pppoe server users -* :vytask:`1376` Incorrect DHCP lease counting -* :vytask:`1392` Large firewall rulesets cause the system to lose configuration and crash at startup -* :vytask:`1416` 2 dhcp server run in failover mode can't sync hostname with each other -* :vytask:`1452` accel-pppoe - add vendor option to shaper -* :vytask:`1490` BGP configuration (is lost|not applied) when updating 1.1.8 -> 1.2.1 -* :vytask:`1780` Adding ipsec ike closeaction -* :vytask:`1803` Unbind NTP while it's not requested... -* :vytask:`1821` "authentication mode radius" has no effect for PPPoE server -* :vytask:`1827` Increase default gc_thresh -* :vytask:`1828` Missing completion helper for "set system syslog host 192.0.2.1 facility all protocol" -* :vytask:`1832` radvd adding feature DNSSL branch.example.com example.com to existing package -* :vytask:`1837` PPPoE unrecognized option 'replacedefaultroute' -* :vytask:`1851` wireguard - changing the pubkey on an existing peer seems to destroy the running config. -* :vytask:`1858` l2tp: Delete depricated outside-nexthop and add gateway-address -* :vytask:`1864` Lower IPSec DPD timeout lower limit from 10s -> 2s -* :vytask:`1879` Extend Dynamic DNS XML definition value help strings and validators -* :vytask:`1881` Execute permissions are removed from custom SNMP scripts at commit time -* :vytask:`1884` Keeping VRRP transition-script native behaviour and adding stop-script -* :vytask:`1891` Router announcements broken on boot -* :vytask:`1900` Enable SNMP for VRRP. -* :vytask:`1902` Add redistribute non main table in bgp -* :vytask:`1909` Incorrect behaviour of static routes with overlapping networks -* :vytask:`1913` "system ipv6 blacklist" command has no effect -* :vytask:`1914` IPv6 multipath hash policy does not apply -* :vytask:`1917` Update WireGuard to Debian release 0.0.20191219-1 -* :vytask:`1934` Change default hostname when deploy from OVA without params. -* :vytask:`1935` NIC identification and usage problem in Hyper-V environments -* :vytask:`1936` pppoe-server CLI control features -* :vytask:`1964` SNMP Script-extensions allows names with spaces, but commit fails -* :vytask:`1967` BGP parameter "enforce-first-as" does not work anymore -* :vytask:`1970` Correct adding interfaces on boot -* :vytask:`1971` Missing modules in initrd.img for PXE boot -* :vytask:`1998` Update FRR to 7.3 -* :vytask:`2001` Error when router reboot -* :vytask:`2032` Monitor bandwidth bits -* :vytask:`2059` Set source-validation on bond vif don't work -* :vytask:`2066` PPPoE interface can be created multiple times - last wins -* :vytask:`2069` PPPoE-client does not works with service-name option -* :vytask:`2077` ISO build from crux branch is failing -* :vytask:`2079` Update Linux Kernel to v4.19.106 -* :vytask:`2087` Add maxfail 0 option to pppoe configuration. -* :vytask:`2100` BGP route adverisement wih checks rib -* :vytask:`2120` "reset vpn ipsec-peer" doesn't work with named peers -* :vytask:`2197` Cant add vif-s interface into a bridge -* :vytask:`2228` WireGuard does not allow ports < 1024 to be used -* :vytask:`2252` HTTP API add system image can return '504 Gateway Time-out' -* :vytask:`2272` Set system flow-accounting disable-imt has syntax error -* :vytask:`2276` PPPoE server vulnerability - - -1.2.4 ------ - -1.2.4 is a maintenance release made in December 2019. - -Resolved issues -^^^^^^^^^^^^^^^ - -* :vytask:`T258` Can not configure wan load-balancing on vyos-1.2 -* :vytask:`T818` SNMP v3 - remove required engineid from user node -* :vytask:`T1030` Upgrade ddclient from 3.8.2 to 3.9.0 (support Cloudflare API v4) -* :vytask:`T1183` BFD Support via FRR -* :vytask:`T1299` Allow SNMPd to be extended with custom scripts -* :vytask:`T1351` accel-pppoe adding CIDR based IP pool option -* :vytask:`T1391` In route-map set community additive -* :vytask:`T1394` syslog systemd and host_name.py race condition -* :vytask:`T1401` Copying files with the FTP protocol fails if the password contains special characters -* :vytask:`T1421` OpenVPN client push-route stopped working, needs added quotes to fix -* :vytask:`T1430` Add options for custom DHCP client-id and hostname -* :vytask:`T1447` Python subprocess called without import in host_name.py -* :vytask:`T1470` improve output of "show dhcpv6 server leases" -* :vytask:`T1485` Enable 'AdvIntervalOpt' option in for radvd.conf -* :vytask:`T1496` Separate rolling release and LTS kernel builds -* :vytask:`T1560` "set load-balancing wan rule 0" causes segfault and prevents load balancing from starting -* :vytask:`T1568` strip-private command improvement for additional masking of IPv6 and MAC address -* :vytask:`T1578` completion offers "show table", but show table does not exist -* :vytask:`T1593` Support ip6gre -* :vytask:`T1597` /usr/sbin/rsyslogd after deleting "system syslog" -* :vytask:`T1638` vyos-hostsd not setting system domain name -* :vytask:`T1678` hostfile-update missing line feed -* :vytask:`T1694` NTPd: Do not listen on all interfaces by default -* :vytask:`T1701` Delete domain-name and domain-search won't work -* :vytask:`T1705` High CPU usage by bgpd when snmp is active -* :vytask:`T1707` DHCP static mapping and exclude address not working -* :vytask:`T1708` Update Rolling Release Kernel to 4.19.76 -* :vytask:`T1709` Update WireGuard to 0.0.20190913 -* :vytask:`T1716` Update Intel NIC drivers to recent versions -* :vytask:`T1726` Update Linux Firmware binaries to a more recent version 2019-03-14 -> 2019-10-07 -* :vytask:`T1728` Update Linux Kernel to 4.19.79 -* :vytask:`T1737` SNMP tab completion missing -* :vytask:`T1738` Copy SNMP configuration from node to node raises exception -* :vytask:`T1740` Broken OSPFv2 virtual-link authentication -* :vytask:`T1742` NHRP unable to commit. -* :vytask:`T1745` dhcp-server commit fails with "DHCP range stop address x must be greater or equal to the range start address y!" when static mapping has same IP as range stop -* :vytask:`T1749` numeric validator doesn't support multiple ranges -* :vytask:`T1769` Remove complex SNMPv3 Transport Security Model (TSM) -* :vytask:`T1772` constraints in XML are partially broken -* :vytask:`T1778` Kilobits/Megabits difference in configuration Vyos/FRR -* :vytask:`T1780` Adding ipsec ike closeaction -* :vytask:`T1786` disable-dhcp-nameservers is missed in current host_name.py implementation -* :vytask:`T1788` Intel QAT (QuickAssist Technology ) implementation -* :vytask:`T1792` Update WireGuard to Debian release 0.0.20191012-1 -* :vytask:`T1800` Update Linux Kernel to v4.19.84 -* :vytask:`T1809` Wireless: SSID scan does not work in AP mode -* :vytask:`T1811` Upgrade from 1.1.8: Config file migration failed: module=l2tp -* :vytask:`T1812` DHCP: hostnames of clients not resolving after update v1.2.3 -> 1.2-rolling -* :vytask:`T1819` Reboot kills SNMPv3 configuration -* :vytask:`T1822` Priority inversion wireless interface dhcpv6 -* :vytask:`T1825` Improve DHCP configuration error message -* :vytask:`T1836` import-conf-mode-commands in vyos-1x/scripts fails to create an xml -* :vytask:`T1839` LLDP shows "VyOS unknown" instead of "VyOS" -* :vytask:`T1841` PPP ipv6-up.d direcotry missing -* :vytask:`T1893` igmp-proxy: Do not allow adding unknown interface -* :vytask:`T1903` Implementation udev predefined interface naming -* :vytask:`T1904` update eth1 and eth2 link files for the vep4600 - - -1.2.3 ------ - -1.2.3 is a maintenance and feature backport release made in September 2019. - -New features -^^^^^^^^^^^^ - -* HTTP API -* :vytask:`T1524` "set service dns forwarding allow-from " - option for limiting queries to specific client networks -* :vytask:`T1503` Functions for checking if a commit is in progress -* :vytask:`T1543` "set system contig-mangement commit-archive source-address" - option -* :vytask:`T1554` Intel NIC drivers now support receive side scaling and - multiqueue - -Resolved issues -^^^^^^^^^^^^^^^ - -* :vytask:`T1209` OSPF max-metric values over 100 no longer causes commit - errors -* :vytask:`T1333` Fixes issue with DNS forwarding not performing recursive - lookups on domain specific forwarders -* :vytask:`T1362` Special characters in VRRP passwords are handled correctly -* :vytask:`T1377` BGP weight is applied properly -* :vytask:`T1420` Fixed permission for log files -* :vytask:`T1425` Wireguard interfaces now support /31 addresses -* :vytask:`T1428` Wireguard correctly handles firewall marks -* :vytask:`T1439` DHCPv6 static mappings now work correctly -* :vytask:`T1450` Flood ping commands now works correctly -* :vytask:`T1460` Op mode "show firewall" commands now support counters longer - than 8 digits (T1460) -* :vytask:`T1465` Fixed priority inversion in VTI commands -* :vytask:`T1468` Fixed remote-as check in the BGP route-reflector-client option -* :vytask:`T1472` It's now possible to re-create VRRP groups with RFC - compatibility mode enabled -* :vytask:`T1527` Fixed a typo in DHCPv6 server help strings -* :vytask:`T1529` Unnumbered BGP peers now support VLAN interfaces -* :vytask:`T1530` Fixed "set system syslog global archive file" command -* :vytask:`T1531` Multiple fixes in cluster configuration scripts -* :vytask:`T1537` Fixed missing help text for "service dns" -* :vytask:`T1541` Fixed input validation in DHCPv6 relay options -* :vytask:`T1551` It's now possible to create a QinQ interface and a firewall - assigned to it in one commit -* :vytask:`T1559` URL filtering now uses correct rule database path and works - again -* :vytask:`T1579` "show log vpn ipsec" command works again -* :vytask:`T1576` "show arp interface " command works again -* :vytask:`T1605` Fixed regression in L2TP/IPsec server -* :vytask:`T1613` Netflow/sFlow captures IPv6 traffic correctly -* :vytask:`T1616` "renew dhcpv6" command now works from op mode -* :vytask:`T1642` BGP remove-private-as option iBGP vs eBGP check works - correctly now -* :vytask:`T1540`, :vytask:`T1360`, :vytask:`T1264`, :vytask:`T1623` Multiple - improvements in name servers and hosts configuration handling - -Internals -^^^^^^^^^ - -``/etc/resolv.conf`` and ``/etc/hosts`` files are now managed by the -*vyos-hostsd* service that listens on a ZMQ socket for update messages. - -1.2.2 ------ - -1.2.2 is a maintenance release made in July 2019. - -New features -^^^^^^^^^^^^ - -* Options for per-interface MSS clamping. -* BGP extended next-hop capability -* Relaxed BGP multipath option -* Internal and external options for "remote-as" (accept any AS as long as it's - the same to this router or different, respectively) -* "Unnumbered" (interface-based) BGP peers -* BGP no-prepend option -* Additive BGP community option -* OSPFv3 network type option -* Custom arguments for VRRP scripts -* A script for querying values from config files - -Resolved issues -^^^^^^^^^^^^^^^ - -* Linux kernel 4.19.54, including a fix for the TCP SACK vulnerability -* :vytask:`T1371` VRRP health-check scripts now can use arguments -* :vytask:`T1497` DNS server addresses coming from a DHCP server are now - correctly propagated to resolv.conf -* :vytask:`T1469` Domain-specific name servers in DNS forwarding are now used - for recursive queries -* :vytask:`T1433` ``run show dhcpv6 server leases`` now display leases correctly -* :vytask:`T1461` Deleting ``firewall options`` node no longer causes errors -* :vytask:`T1458` Correct hostname is sent to remote syslog again -* :vytask:`T1438` Board serial number from DMI is correctly displayed in - ``show version`` -* :vytask:`T1358`, :vytask:`T1355`, :vytask:`T1294` Multiple corrections in - remote syslog config -* :vytask:`T1255` Fixed missing newline in ``/etc/hosts`` -* :vytask:`T1174` ``system domain-name`` is correctly included in - ``/etc/resolv.conf`` -* :vytask:`T1465` Fixed priority inversion in ``interfaces vti vtiX ip`` - settings -* :vytask:`T1446` Fixed errors when installing with RAID1 on UEFI machines -* :vytask:`T1387` Fixed an error on disabling an interfaces that has no address -* :vytask:`T1367` Fixed deleting VLAN interface with non-default MTU -* :vytask:`T1505` vyos.config ``return_effective_values()`` function now - correctly returns a list rather than a string - -1.2.1 ------ - -VyOS 1.2.1 is a maintenance release made in April 2019. - -Resolved issues -^^^^^^^^^^^^^^^ - -* Package updates: kernel 4.19.32, open-vm-tools 10.3, latest Intel NIC drivers -* :vytask:`T1326` The kernel now includes drivers for various USB serial - adapters, which allows people to add a serial console to a machine without - onboard RS232, or connect to something else from the router -* The collection of network card firmware is now much more extensive -* :vytask:`T1271` VRRP now correctly uses a virtual rather than physical MAC - addresses in the RFC-compliant mode -* :vytask:`T1330` DHCP WPAD URL option works correctly again -* :vytask:`T1312` Many to many NAT rules now can use source/destination and - translation networks of non-matching size. If 1:1 network bits translation is - desired, it's now users responsibility to check if prefix length matches. -* :vytask:`T1290` IPv6 network prefix translation is fixed -* :vytask:`T1308` Non-alphanumeric characters such as ``>`` can now be safely - used in PPPoE passwords -* :vytask:`T1305` ``show | commands`` no longer fails when a config section ends - with a leaf node such as ``timezone`` in ``show system | commands`` -* :vytask:`T1235` ``show | commands`` correctly works in config mode now -* :vytask:`T1298` VTI is now compatible with the DHCP-interface IPsec option -* :vytask:`T1277` ``show dhcp server statistics`` command was broken in latest - Crux -* :vytask:`T1261` An issue with TFTP server refusing to listen on addresses - other than loopback was fixed -* :vytask:`T1224` Template issue that might cause UDP broadcast relay fail to - start is fixed -* :vytask:`T1067` VXLAN value validation is improved -* :vytask:`T1211` Blank hostnames in DHCP updates no longer can crash DNS - forwarding -* :vytask:`T1322` Correct configuration is now generated for DHCPv6 relays with - more than one upstream interface -* :vytask:`T1234` ``relay-agents-packets`` option works correctly now -* :vytask:`T1231` Dynamic DNS data is now cleaned on configuration change -* :vytask:`T1282` Remote Syslog can now use a fully qualified domain name -* :vytask:`T1279` ACPI power off works again -* :vytask:`T1247` Negation in WAN load balancing rules works again -* :vytask:`T1218` FRR staticd now starts on boot correctly -* :vytask:`T1296` The installer now correctly detects SD card devices -* :vytask:`T1225` Wireguard peers can be disabled now -* :vytask:`T1217` The issue with Wireguard interfaces impossible to delete - is fixed -* :vytask:`T1160` Unintended IPv6 access is fixed in SNMP configuration -* :vytask:`T1060` It's now possible to exclude hosts from the transparent - web proxy -* :vytask:`T484` An issue with rules impossible to delete from the zone-based - firewall is fixed - -Earlier releases -================ - -Release notes for legacy versions (1.1.x, 1.0.x) can be found in the `archived wiki `_. diff --git a/docs/automation/command-scripting.rst b/docs/automation/command-scripting.rst new file mode 100644 index 00000000..7d0ab6c5 --- /dev/null +++ b/docs/automation/command-scripting.rst @@ -0,0 +1,127 @@ +.. _command-scripting: + +Command Scripting +================= + +VyOS supports executing configuration and operational commands non-interactively +from shell scripts. + +To include VyOS specific functions and aliases you need to ``source +/opt/vyatta/etc/functions/script-template`` files at the top of your script. + +.. code-block:: none + + #!/bin/vbash + source /opt/vyatta/etc/functions/script-template + exit + +Run configuration commands +-------------------------- + +Configuration commands are executed just like from a normal config session. For +example, if you want to disable a BGP peer on VRRP transition to backup: + +.. code-block:: none + + #!/bin/vbash + source /opt/vyatta/etc/functions/script-template + configure + set protocols bgp 65536 neighbor 192.168.2.1 shutdown + commit + exit + +Run operational commands +------------------------ + +Unlike a normal configuration sessions, all operational commands must be +prepended with ``run``, even if you haven't created a session with configure. + +.. code-block:: none + + #!/bin/vbash + source /opt/vyatta/etc/functions/script-template + run show interfaces + exit + +Other script language +--------------------- + +If you want to script the configs in a language other than bash you can have +your script output commands and then source them in a bash script. + +Here is a simple example: + +.. code-block:: python + + #!/usr/bin/env python + print "delete firewall group address-group somehosts" + print "set firewall group address-group somehosts address '192.0.2.3'" + print "set firewall group address-group somehosts address '203.0.113.55'" + + +.. code-block:: none + + #!/bin/vbash + source /opt/vyatta/etc/functions/script-template + configure + source < /config/scripts/setfirewallgroup.py + commit + + +Executing Configuration Scripts +------------------------------- + +There is a pitfall when working with configuration scripts. It is tempting to +call configuration scripts with "sudo" (i.e., temporary root permissions), +because that's the common way on most Linux platforms to call system commands. + +On VyOS this will cause the following problem: After modifying the configuration +via script like this once, it is not possible to manually modify the config +anymore: + +.. code-block:: none + + sudo ./myscript.sh # Modifies config + configure + set ... # Any configuration parameter + +This will result in the following error message: ``Set failed`` If this happens, +a reboot is required to be able to edit the config manually again. + +To avoid these problems, the proper way is to call a script with the +``vyattacfg`` group, e.g., by using the ``sg`` (switch group) command: + +.. code-block:: none + + sg vyattacfg -c ./myscript.sh + +To make sure that a script is not accidentally called without the ``vyattacfg`` +group, the script can be safeguarded like this: + +.. code-block:: none + + if [ "$(id -g -n)" != 'vyattacfg' ] ; then + exec sg vyattacfg -c "/bin/vbash $(readlink -f $0) $@" + fi + +Postconfig on boot +------------------ + +The ``/config/scripts/vyos-postconfig-bootup.script`` script is called on boot +after the VyOS configuration is fully applied. + +Any modifications done to work around unfixed bugs and implement enhancements +which are not complete in the VyOS system can be placed here. + +The default file looks like this: + +.. code-block:: none + + #!/bin/sh + # This script is executed at boot time after VyOS configuration is fully + # applied. Any modifications required to work around unfixed bugs or use + # services not available through the VyOS CLI system can be placed here. + +.. hint:: For configuration/upgrade management issues, modification of this + script should be the last option. Always try to find solutions based on CLI + commands first. diff --git a/docs/automation/http-api.rst b/docs/automation/http-api.rst new file mode 100644 index 00000000..49f2dbd9 --- /dev/null +++ b/docs/automation/http-api.rst @@ -0,0 +1,166 @@ +.. _http-api: + +######## +HTTP-API +######## + +Enabling HTTP-API +----------------- + +VyOS HTTP API can be enabled through the ``set service https api`` command. + +.. code-block:: none + + set service https api debug + set service https api keys id MY-HTTP-API-ID key MY-HTTP-API-PLAINTEXT-KEY + +The local API process listens on localhost:8080, and nginx exposes it on all +virtual servers, by default. For the purpose of illustration below, we will +assume nginx is running at https://192.168.122.127. + +One can limit proxying to specific listen addresses/ports/server-names by +defining a ``service https virtual-host ``, and setting ``service https +api-restrict virtual-host ``. + +.. code-block:: none + + set service https virtual-host example listen-address 192.168.122.127 + set service https virtual-host example listen-port 44302 + set service https virtual-host example server-name example.net + + set service https api-restrict virtual-host example + +In this example, nginx will proxy only those requests to +192.168.122.127:44302 or example.net:44302 (assuming the DNS record is +viable). Omitting any of listen-address, listen-port, or server-name, will +leave appropriate defaults in the nginx directive. Multiple instances of +``service https api-restrict virtual-host`` may be set. + +Configuration mode requests +--------------------------- + +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. + +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. + +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: + +.. code-block:: none + + curl -k -X POST -F data='{"op": "returnValue", "path": ["interfaces", "dummy", "dum1", "address"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve + +Use ``returnValues`` for multi-valued nodes. + + +Show config +""""""""""" + +To retrieve the full config under a path: + +.. code-block:: none + + # curl -k -X POST -F data='{"op": "showConfig", "path": ["interfaces", "dummy"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve + +It will return: + +.. code-block:: none + + {"success": true, "data": {"dummy": {"dum1": {"address": "203.0.113.76/32"}}}, "error": null} + +Passing an empty path will return the full config: + +.. code-block:: none + + # curl -k -X POST -F data='{"op": "showConfig", "path": []}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve + + +Configuration management requests +--------------------------------- + +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: + +.. code-block:: none + + # curl -k -X POST -F key=MY-HTTP-API-PLAINTEXT-KEY -Fdata='{"op": "save", "file": "/config/config.boot"}' https://192.168.122.127/config-file + +Image management requests +------------------------- + +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: + +.. code-block:: none + + # curl -k -X POST -F data='{"op": "add", "url": "https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/image + +``delete`` by image ``name``. For example: + +.. code-block:: none + + # 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: + +.. code-block:: none + + # curl -k -X POST -F data='{"op": "show", "path": ["system", "image"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show + +Operational mode requests +------------------------- + +It is possible to run ``show`` and ``generate`` commands: + + +Request: + +.. code-block:: none + + curl -k -X POST -F data='{"op": "generate", "path": ["wireguard", "default-keypair"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/generate + +Response: + +.. code-block:: none + + {"success": true, "data": "", "error": null} + +Request: + +.. code-block:: none + + curl -k -X POST -F data='{"op": "show", "path": ["wireguard", "keypairs", "pubkey", "default"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show + +Response: + +.. code-block:: none + + {"success": true, "data": "=\n", "error": null} + +Request: + +.. code-block:: none + + curl -k -X POST -F data='{"op": "show", "path": ["ip", "route"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show + +Response: + +.. code-block:: none + + {"success": true, "data": "Codes: K - kernel route, C - connected, S - static, R - RIP,\n O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP,\n T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP,\n F - PBR, f - OpenFabric,\n > - selected route, * - FIB route, q - queued route, r - rejected route\n\nS>* 0.0.0.0/0 [210/0] via 192.168.100.1, eth0, 01:41:05\nC>* 192.168.0.0/24 is directly connected, eth1, 01:41:09\nC>* 192.168.100.0/24 is directly connected, eth0, 01:41:05\nC>* 203.0.113.76/32 is directly connected, dum1, 01:38:40\n", "error": null} + diff --git a/docs/automation/index.rst b/docs/automation/index.rst index a3df9bc0..1f2b40b1 100644 --- a/docs/automation/index.rst +++ b/docs/automation/index.rst @@ -6,4 +6,11 @@ VyOS Automation * Ansible * Saltstack * HTTP-API - * startup scripts \ No newline at end of file + * startup scripts + + +.. toctree:: + :maxdepth: 1 + + command-scripting + http-api \ No newline at end of file -- cgit v1.2.3 From 8943fc9f877cbee3301a8261ddd27b4b1f15f174 Mon Sep 17 00:00:00 2001 From: rebortg Date: Mon, 30 Nov 2020 20:53:36 +0100 Subject: arrange services and protocols --- docs/automation/http-api.rst | 166 ------ docs/configuration/firewall/index.rst | 65 +++ docs/configuration/protocols/bfd.rst | 117 ++++ docs/configuration/protocols/bgp.rst | 335 +++++++++++ docs/configuration/protocols/igmp-proxy.rst | 2 + docs/configuration/protocols/igmp.rst | 244 ++++++++ docs/configuration/protocols/index.rst | 22 + docs/configuration/protocols/mpls.rst | 157 +++++ docs/configuration/protocols/ospf.rst | 70 +++ docs/configuration/protocols/ospfv3.rst | 71 +++ docs/configuration/protocols/pim.rst | 2 + docs/configuration/protocols/rip.rst | 37 ++ docs/configuration/protocols/ripng.rst | 3 + docs/configuration/protocols/rpki.rst | 113 ++++ docs/configuration/protocols/static.rst | 195 +++++++ docs/configuration/protocols/vrf.rst | 3 + docs/configuration/service/broadcast-relay.rst | 61 ++ docs/configuration/service/conntrack-sync.rst | 200 +++++++ docs/configuration/service/console-server.rst | 107 ++++ docs/configuration/service/dhcp-relay.rst | 2 + docs/configuration/service/dhcp-server.rst | 776 +++++++++++++++++++++++++ docs/configuration/service/dhcpv6-relay.rst | 2 + docs/configuration/service/dhcpv6-server.rst | 2 + docs/configuration/service/dns.rst | 313 ++++++++++ docs/configuration/service/https.rst | 166 ++++++ docs/configuration/service/index.rst | 29 + docs/configuration/service/ipoe-server.rst | 149 +++++ docs/configuration/service/lldp.rst | 141 +++++ docs/configuration/service/mdns.rst | 44 ++ docs/configuration/service/pppoe-advert.rst | 2 + docs/configuration/service/pppoe-server.rst | 397 +++++++++++++ docs/configuration/service/router-advert.rst | 89 +++ docs/configuration/service/salt-minion.rst | 2 + docs/configuration/service/snmp.rst | 266 +++++++++ docs/configuration/service/ssh.rst | 106 ++++ docs/configuration/service/tftp-server.rst | 54 ++ docs/configuration/service/webproxy.rst | 153 +++++ docs/operation/index.rst | 10 + docs/operation/ip-commands.rst | 258 ++++++++ docs/routing/arp.rst | 59 -- docs/routing/bfd.rst | 117 ---- docs/routing/bgp.rst | 335 ----------- docs/routing/index.rst | 22 - docs/routing/ip-commands.rst | 258 -------- docs/routing/mpls.rst | 157 ----- docs/routing/mss-clamp.rst | 63 -- docs/routing/multicast.rst | 244 -------- docs/routing/ospf.rst | 141 ----- docs/routing/rip.rst | 37 -- docs/routing/rpki.rst | 113 ---- docs/routing/static.rst | 134 ----- docs/services/conntrack.rst | 200 ------- docs/services/console-server.rst | 107 ---- docs/services/dhcp.rst | 776 ------------------------- docs/services/dns-forwarding.rst | 147 ----- docs/services/dynamic-dns.rst | 164 ------ docs/services/index.rst | 26 - docs/services/ipoe-server.rst | 149 ----- docs/services/lldp.rst | 141 ----- docs/services/mdns-repeater.rst | 44 -- docs/services/pppoe-server.rst | 397 ------------- docs/services/router-advert.rst | 89 --- docs/services/snmp.rst | 266 --------- docs/services/ssh.rst | 106 ---- docs/services/tftp.rst | 54 -- docs/services/udp-broadcast-relay.rst | 61 -- docs/services/webproxy.rst | 153 ----- 67 files changed, 4765 insertions(+), 4726 deletions(-) delete mode 100644 docs/automation/http-api.rst create mode 100644 docs/configuration/protocols/bfd.rst create mode 100644 docs/configuration/protocols/bgp.rst create mode 100644 docs/configuration/protocols/igmp-proxy.rst create mode 100644 docs/configuration/protocols/igmp.rst create mode 100644 docs/configuration/protocols/index.rst create mode 100644 docs/configuration/protocols/mpls.rst create mode 100644 docs/configuration/protocols/ospf.rst create mode 100644 docs/configuration/protocols/ospfv3.rst create mode 100644 docs/configuration/protocols/pim.rst create mode 100644 docs/configuration/protocols/rip.rst create mode 100644 docs/configuration/protocols/ripng.rst create mode 100644 docs/configuration/protocols/rpki.rst create mode 100644 docs/configuration/protocols/static.rst create mode 100644 docs/configuration/protocols/vrf.rst create mode 100644 docs/configuration/service/broadcast-relay.rst create mode 100644 docs/configuration/service/conntrack-sync.rst create mode 100644 docs/configuration/service/console-server.rst create mode 100644 docs/configuration/service/dhcp-relay.rst create mode 100644 docs/configuration/service/dhcp-server.rst create mode 100644 docs/configuration/service/dhcpv6-relay.rst create mode 100644 docs/configuration/service/dhcpv6-server.rst create mode 100644 docs/configuration/service/dns.rst create mode 100644 docs/configuration/service/https.rst create mode 100644 docs/configuration/service/index.rst create mode 100644 docs/configuration/service/ipoe-server.rst create mode 100644 docs/configuration/service/lldp.rst create mode 100644 docs/configuration/service/mdns.rst create mode 100644 docs/configuration/service/pppoe-advert.rst create mode 100644 docs/configuration/service/pppoe-server.rst create mode 100644 docs/configuration/service/router-advert.rst create mode 100644 docs/configuration/service/salt-minion.rst create mode 100644 docs/configuration/service/snmp.rst create mode 100644 docs/configuration/service/ssh.rst create mode 100644 docs/configuration/service/tftp-server.rst create mode 100644 docs/configuration/service/webproxy.rst create mode 100644 docs/operation/index.rst create mode 100644 docs/operation/ip-commands.rst delete mode 100644 docs/routing/arp.rst delete mode 100644 docs/routing/bfd.rst delete mode 100644 docs/routing/bgp.rst delete mode 100644 docs/routing/index.rst delete mode 100644 docs/routing/ip-commands.rst delete mode 100644 docs/routing/mpls.rst delete mode 100644 docs/routing/mss-clamp.rst delete mode 100644 docs/routing/multicast.rst delete mode 100644 docs/routing/ospf.rst delete mode 100644 docs/routing/rip.rst delete mode 100644 docs/routing/rpki.rst delete mode 100644 docs/routing/static.rst delete mode 100644 docs/services/conntrack.rst delete mode 100644 docs/services/console-server.rst delete mode 100644 docs/services/dhcp.rst delete mode 100644 docs/services/dns-forwarding.rst delete mode 100644 docs/services/dynamic-dns.rst delete mode 100644 docs/services/index.rst delete mode 100644 docs/services/ipoe-server.rst delete mode 100644 docs/services/lldp.rst delete mode 100644 docs/services/mdns-repeater.rst delete mode 100644 docs/services/pppoe-server.rst delete mode 100644 docs/services/router-advert.rst delete mode 100644 docs/services/snmp.rst delete mode 100644 docs/services/ssh.rst delete mode 100644 docs/services/tftp.rst delete mode 100644 docs/services/udp-broadcast-relay.rst delete mode 100644 docs/services/webproxy.rst (limited to 'docs/automation') diff --git a/docs/automation/http-api.rst b/docs/automation/http-api.rst deleted file mode 100644 index 49f2dbd9..00000000 --- a/docs/automation/http-api.rst +++ /dev/null @@ -1,166 +0,0 @@ -.. _http-api: - -######## -HTTP-API -######## - -Enabling HTTP-API ------------------ - -VyOS HTTP API can be enabled through the ``set service https api`` command. - -.. code-block:: none - - set service https api debug - set service https api keys id MY-HTTP-API-ID key MY-HTTP-API-PLAINTEXT-KEY - -The local API process listens on localhost:8080, and nginx exposes it on all -virtual servers, by default. For the purpose of illustration below, we will -assume nginx is running at https://192.168.122.127. - -One can limit proxying to specific listen addresses/ports/server-names by -defining a ``service https virtual-host ``, and setting ``service https -api-restrict virtual-host ``. - -.. code-block:: none - - set service https virtual-host example listen-address 192.168.122.127 - set service https virtual-host example listen-port 44302 - set service https virtual-host example server-name example.net - - set service https api-restrict virtual-host example - -In this example, nginx will proxy only those requests to -192.168.122.127:44302 or example.net:44302 (assuming the DNS record is -viable). Omitting any of listen-address, listen-port, or server-name, will -leave appropriate defaults in the nginx directive. Multiple instances of -``service https api-restrict virtual-host`` may be set. - -Configuration mode requests ---------------------------- - -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. - -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. - -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: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "returnValue", "path": ["interfaces", "dummy", "dum1", "address"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve - -Use ``returnValues`` for multi-valued nodes. - - -Show config -""""""""""" - -To retrieve the full config under a path: - -.. code-block:: none - - # curl -k -X POST -F data='{"op": "showConfig", "path": ["interfaces", "dummy"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve - -It will return: - -.. code-block:: none - - {"success": true, "data": {"dummy": {"dum1": {"address": "203.0.113.76/32"}}}, "error": null} - -Passing an empty path will return the full config: - -.. code-block:: none - - # curl -k -X POST -F data='{"op": "showConfig", "path": []}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve - - -Configuration management requests ---------------------------------- - -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: - -.. code-block:: none - - # curl -k -X POST -F key=MY-HTTP-API-PLAINTEXT-KEY -Fdata='{"op": "save", "file": "/config/config.boot"}' https://192.168.122.127/config-file - -Image management requests -------------------------- - -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: - -.. code-block:: none - - # curl -k -X POST -F data='{"op": "add", "url": "https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/image - -``delete`` by image ``name``. For example: - -.. code-block:: none - - # 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: - -.. code-block:: none - - # curl -k -X POST -F data='{"op": "show", "path": ["system", "image"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show - -Operational mode requests -------------------------- - -It is possible to run ``show`` and ``generate`` commands: - - -Request: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "generate", "path": ["wireguard", "default-keypair"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/generate - -Response: - -.. code-block:: none - - {"success": true, "data": "", "error": null} - -Request: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "show", "path": ["wireguard", "keypairs", "pubkey", "default"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show - -Response: - -.. code-block:: none - - {"success": true, "data": "=\n", "error": null} - -Request: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "show", "path": ["ip", "route"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show - -Response: - -.. code-block:: none - - {"success": true, "data": "Codes: K - kernel route, C - connected, S - static, R - RIP,\n O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP,\n T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP,\n F - PBR, f - OpenFabric,\n > - selected route, * - FIB route, q - queued route, r - rejected route\n\nS>* 0.0.0.0/0 [210/0] via 192.168.100.1, eth0, 01:41:05\nC>* 192.168.0.0/24 is directly connected, eth1, 01:41:09\nC>* 192.168.100.0/24 is directly connected, eth0, 01:41:05\nC>* 203.0.113.76/32 is directly connected, dum1, 01:38:40\n", "error": null} - diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst index d9a3ebe3..2615774f 100644 --- a/docs/configuration/firewall/index.rst +++ b/docs/configuration/firewall/index.rst @@ -766,3 +766,68 @@ Example Partial Config } } } + + +.. _routing-mss-clamp: + +################ +TCP-MSS Clamping +################ + +As Internet wide PMTU discovery rarely works, we sometimes need to clamp +our TCP MSS value to a specific value. This is a field in the TCP +Options part of a SYN packet. By setting the MSS value, you are telling +the remote side unequivocally 'do not try to send me packets bigger than +this value'. + +Starting with VyOS 1.2 there is a firewall option to clamp your TCP MSS +value for IPv4 and IPv6. + + +.. note:: MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting + in 1452 bytes on a 1492 byte MTU. + + +IPv4 +==== + +.. cfgcmd:: set firewall options interface adjust-mss + + Use this command to set the maximum segment size for IPv4 transit + packets on a specific interface (500-1460 bytes). + +Example +------- + +Clamp outgoing MSS value in a TCP SYN packet to `1452` for `pppoe0` and +`1372` +for your WireGuard `wg02` tunnel. + +.. code-block:: none + + set firewall options interface pppoe0 adjust-mss '1452' + set firewall options interface wg02 adjust-mss '1372' + +IPv6 +==== + +.. cfgcmd:: set firewall options interface adjust-mss6 + + Use this command to set the maximum segment size for IPv6 transit + packets on a specific interface (1280-1492 bytes). + +Example +------- + +Clamp outgoing MSS value in a TCP SYN packet to `1280` for both `pppoe0` and +`wg02` interface. + +.. code-block:: none + + set firewall options interface pppoe0 adjust-mss6 '1280' + set firewall options interface wg02 adjust-mss6 '1280' + + + +.. hint:: When doing your byte calculations, you might find useful this + `Visual packet size calculator `_. diff --git a/docs/configuration/protocols/bfd.rst b/docs/configuration/protocols/bfd.rst new file mode 100644 index 00000000..b8fdf489 --- /dev/null +++ b/docs/configuration/protocols/bfd.rst @@ -0,0 +1,117 @@ +.. include:: /_include/need_improvement.txt + +.. _routing-bfd: + +### +BFD +### + +:abbr:`BFD (Bidirectional Forwarding Detection)` is described and extended by +the following RFCs: :rfc:`5880`, :rfc:`5881` and :rfc:`5883`. + + +Configure BFD +============= + +.. cfgcmd:: set protocols bfd peer
+ + Set BFD peer IPv4 address or IPv6 address + +.. cfgcmd:: set protocols bfd peer
echo-mode + + Enables the echo transmission mode + +.. cfgcmd:: set protocols bfd peer
multihop + + Allow this BFD peer to not be directly connected + +.. cfgcmd:: set protocols bfd peer
source [address
| interface ] + + Bind listener to specifid interface/address, mandatory for IPv6 + +.. cfgcmd:: set protocols bfd peer
interval echo-interval <10-60000> + + The minimal echo receive transmission interval that this system is capable of handling + +.. cfgcmd:: set protocols bfd peer
interval multiplier <2-255> + + Remote transmission interval will be multiplied by this value + +.. cfgcmd:: set protocols bfd peer
interval [receive | transmit] <10-60000> + + Interval in milliseconds + +.. cfgcmd:: set protocols bfd peer
shutdown + + Disable a BFD peer + + +Enable BFD in BGP +----------------- + +.. cfgcmd:: set protocols bgp neighbor
bfd + + Enable BFD on a single BGP neighbor + +.. cfgcmd:: set protocols bgp peer-group bfd + + Enable BFD on a BGP peer group + + + +Enable BFD in OSPF +------------------ + +.. cfgcmd:: set interfaces ethernet ip ospf bfd + + Enable BFD for ospf on a interface + +.. cfgcmd:: set interfaces ethernet ipv6 ospfv3 bfd + + Enable BFD for ospfv3 on a interface + + + +Operational Commands +==================== + +.. opcmd:: show protocols bfd peer + + Show all BFD peers + + .. code-block:: none + + BFD Peers: + peer 198.51.100.33 vrf default interface eth4.100 + ID: 4182341893 + Remote ID: 12678929647 + Status: up + Uptime: 1 month(s), 16 hour(s), 29 minute(s), 38 second(s) + Diagnostics: ok + Remote diagnostics: ok + Local timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 50ms + Remote timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 0ms + + peer 198.51.100.55 vrf default interface eth4.101 + ID: 4618932327 + Remote ID: 3312345688 + Status: up + Uptime: 20 hour(s), 16 minute(s), 19 second(s) + Diagnostics: ok + Remote diagnostics: ok + Local timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 50ms + Remote timers: + Receive interval: 300ms + Transmission interval: 300ms + Echo transmission interval: 0ms + + diff --git a/docs/configuration/protocols/bgp.rst b/docs/configuration/protocols/bgp.rst new file mode 100644 index 00000000..c576d836 --- /dev/null +++ b/docs/configuration/protocols/bgp.rst @@ -0,0 +1,335 @@ +.. _bgp: + +### +BGP +### + +:abbr:`BGP (Border Gateway Protocol)` is one of the Exterior Gateway Protocols +and the de facto standard interdomain routing protocol. The latest BGP version +is 4. BGP-4 is described in :rfc:`1771` and updated by :rfc:`4271`. :rfc:`2858` +adds multiprotocol support to BGP. + +VyOS makes use of :abbr:`FRR (Free Range Routing)` and we would like to thank +them for their effort! + +Basic Concepts +============== + +.. _bgp-autonomous-systems: + +Autonomous Systems +------------------ + +From :rfc:`1930`: + + An AS is a connected group of one or more IP prefixes run by one or more + network operators which has a SINGLE and CLEARLY DEFINED routing policy. + +Each AS has an identifying number associated with it called an :abbr:`ASN +(Autonomous System Number)`. This is a two octet value ranging in value from 1 +to 65535. The AS numbers 64512 through 65535 are defined as private AS numbers. +Private AS numbers must not be advertised on the global Internet. + +The :abbr:`ASN (Autonomous System Number)` is one of the essential elements of +BGP. BGP is a distance vector routing protocol, and the AS-Path framework +provides distance vector metric and loop detection to BGP. + +.. _bgp-address-families: + +Address Families +---------------- + +Multiprotocol extensions enable BGP to carry routing information for multiple +network layer protocols. BGP supports an Address Family Identifier (AFI) for +IPv4 and IPv6. + +.. _bgp-route-selection: + +Route Selection +--------------- + +The route selection process used by FRR's BGP implementation uses the following +decision criterion, starting at the top of the list and going towards the +bottom until one of the factors can be used. + +1. **Weight check** + + Prefer higher local weight routes to lower routes. + +2. **Local preference check** + + Prefer higher local preference routes to lower. + +3. **Local route check** + + Prefer local routes (statics, aggregates, redistributed) to received routes. + +4. **AS path length check** + + Prefer shortest hop-count AS_PATHs. + +5. **Origin check** + + Prefer the lowest origin type route. That is, prefer IGP origin routes to + EGP, to Incomplete routes. + +6. **MED check** + + Where routes with a MED were received from the same AS, prefer the route + with the lowest MED. + +7. **External check** + + Prefer the route received from an external, eBGP peer over routes received + from other types of peers. + +8. **IGP cost check** + + Prefer the route with the lower IGP cost. + +9. **Multi-path check** + + If multi-pathing is enabled, then check whether the routes not yet + distinguished in preference may be considered equal. If + :cfgcmd:`bgp bestpath as-path multipath-relax` is set, all such routes are + considered equal, otherwise routes received via iBGP with identical AS_PATHs + or routes received from eBGP neighbours in the same AS are considered equal. + +10. **Already-selected external check** + + Where both routes were received from eBGP peers, then prefer the route + which is already selected. Note that this check is not applied if + :cfgcmd:`bgp bestpath compare-routerid` is configured. This check can + prevent some cases of oscillation. + +11. **Router-ID check** + + Prefer the route with the lowest `router-ID`. If the route has an + `ORIGINATOR_ID` attribute, through iBGP reflection, then that router ID is + used, otherwise the `router-ID` of the peer the route was received from is + used. + +12. **Cluster-List length check** + + The route with the shortest cluster-list length is used. The cluster-list + reflects the iBGP reflection path the route has taken. + +13. **Peer address** + + Prefer the route received from the peer with the higher transport layer + address, as a last-resort tie-breaker. + +.. _bgp-capability-negotiation: + +Capability Negotiation +---------------------- + +When adding IPv6 routing information exchange feature to BGP. There were some +proposals. :abbr:`IETF (Internet Engineering Task Force)` +:abbr:`IDR (Inter Domain Routing)` adopted a proposal called Multiprotocol +Extension for BGP. The specification is described in :rfc:`2283`. The protocol +does not define new protocols. It defines new attributes to existing BGP. When +it is used exchanging IPv6 routing information it is called BGP-4+. When it is +used for exchanging multicast routing information it is called MBGP. + +*bgpd* supports Multiprotocol Extension for BGP. So if a remote peer supports +the protocol, *bgpd* can exchange IPv6 and/or multicast routing information. + +Traditional BGP did not have the feature to detect a remote peer's +capabilities, e.g. whether it can handle prefix types other than IPv4 unicast +routes. This was a big problem using Multiprotocol Extension for BGP in an +operational network. :rfc:`2842` adopted a feature called Capability +Negotiation. *bgpd* use this Capability Negotiation to detect the remote peer's +capabilities. If a peer is only configured as an IPv4 unicast neighbor, *bgpd* +does not send these Capability Negotiation packets (at least not unless other +optional BGP features require capability negotiation). + +By default, FRR will bring up peering with minimal common capability for the +both sides. For example, if the local router has unicast and multicast +capabilities and the remote router only has unicast capability the local router +will establish the connection with unicast only capability. When there are no +common capabilities, FRR sends Unsupported Capability error and then resets the +connection. + +.. _bgp-router-configuration: + +BGP Router Configuration +======================== + +ASN and Router ID +----------------- + +.. cfgcmd:: set protocols bgp + + First of all you must configure BGP router with the :abbr:`ASN (Autonomous + System Number)`. The AS number is an identifier for the autonomous system. + The BGP protocol uses the AS number for detecting whether the BGP connection + is internal or external. + +.. cfgcmd:: set protocols bgp parameters router-id + + This command specifies the router-ID. If router ID is not specified it will + use the highest interface IP address. + +Route Selection +--------------- + +.. cfgcmd:: set protocols bgp parameters bestpath as-path confed + + This command specifies that the length of confederation path sets and + sequences should be taken into account during the BGP best path + decision process. + +.. cfgcmd:: set protocols bgp parameters bestpath as-path multipath-relax + + This command specifies that BGP decision process should consider paths + of equal AS_PATH length candidates for multipath computation. Without + the knob, the entire AS_PATH must match for multipath computation. + +.. cfgcmd:: set protocols bgp parameters bestpath as-path ignore + + Ignore AS_PATH length when selecting a route + +IPv4 +^^^^ + +A simple eBGP configuration: + +**Node 1:** + +.. code-block:: none + + set protocols bgp 65534 neighbor 192.168.0.2 ebgp-multihop '2' + set protocols bgp 65534 neighbor 192.168.0.2 remote-as '65535' + set protocols bgp 65534 neighbor 192.168.0.2 update-source '192.168.0.1' + set protocols bgp 65534 address-family ipv4-unicast network '172.16.0.0/16' + set protocols bgp 65534 parameters router-id '192.168.0.1' + +**Node 2:** + +.. code-block:: none + + set protocols bgp 65535 neighbor 192.168.0.1 ebgp-multihop '2' + set protocols bgp 65535 neighbor 192.168.0.1 remote-as '65534' + set protocols bgp 65535 neighbor 192.168.0.1 update-source '192.168.0.2' + set protocols bgp 65535 address-family ipv4-unicast network '172.17.0.0/16' + set protocols bgp 65535 parameters router-id '192.168.0.2' + + +Don't forget, the CIDR declared in the network statement MUST **exist in your +routing table (dynamic or static), the best way to make sure that is true is +creating a static route:** + +**Node 1:** + +.. code-block:: none + + set protocols static route 172.16.0.0/16 blackhole distance '254' + +**Node 2:** + +.. code-block:: none + + set protocols static route 172.17.0.0/16 blackhole distance '254' + + +IPv6 +^^^^ + +A simple BGP configuration via IPv6. + +**Node 1:** + +.. code-block:: none + + set protocols bgp 65534 neighbor 2001:db8::2 ebgp-multihop '2' + set protocols bgp 65534 neighbor 2001:db8::2 remote-as '65535' + set protocols bgp 65534 neighbor 2001:db8::2 update-source '2001:db8::1' + set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv6-unicast + set protocols bgp 65534 address-family ipv6-unicast network '2001:db8:1::/48' + set protocols bgp 65534 parameters router-id '10.1.1.1' + +**Node 2:** + +.. code-block:: none + + set protocols bgp 65535 neighbor 2001:db8::1 ebgp-multihop '2' + set protocols bgp 65535 neighbor 2001:db8::1 remote-as '65534' + set protocols bgp 65535 neighbor 2001:db8::1 update-source '2001:db8::2' + set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv6-unicast + set protocols bgp 65535 address-family ipv6-unicast network '2001:db8:2::/48' + set protocols bgp 65535 parameters router-id '10.1.1.2' + +Don't forget, the CIDR declared in the network statement **MUST exist in your +routing table (dynamic or static), the best way to make sure that is true is +creating a static route:** + +**Node 1:** + +.. code-block:: none + + set protocols static route6 2001:db8:1::/48 blackhole distance '254' + +**Node 2:** + +.. code-block:: none + + set protocols static route6 2001:db8:2::/48 blackhole distance '254' + +Route Filter +^^^^^^^^^^^^ + +Route filter can be applied using a route-map: + +**Node1:** + +.. code-block:: none + + set policy prefix-list AS65535-IN rule 10 action 'permit' + set policy prefix-list AS65535-IN rule 10 prefix '172.16.0.0/16' + set policy prefix-list AS65535-OUT rule 10 action 'deny' + set policy prefix-list AS65535-OUT rule 10 prefix '172.16.0.0/16' + set policy prefix-list6 AS65535-IN rule 10 action 'permit' + set policy prefix-list6 AS65535-IN rule 10 prefix '2001:db8:2::/48' + set policy prefix-list6 AS65535-OUT rule 10 action 'deny' + set policy prefix-list6 AS65535-OUT rule 10 prefix '2001:db8:2::/48' + set policy route-map AS65535-IN rule 10 action 'permit' + set policy route-map AS65535-IN rule 10 match ip address prefix-list 'AS65535-IN' + set policy route-map AS65535-IN rule 10 match ipv6 address prefix-list 'AS65535-IN' + set policy route-map AS65535-IN rule 20 action 'deny' + set policy route-map AS65535-OUT rule 10 action 'deny' + set policy route-map AS65535-OUT rule 10 match ip address prefix-list 'AS65535-OUT' + set policy route-map AS65535-OUT rule 10 match ipv6 address prefix-list 'AS65535-OUT' + set policy route-map AS65535-OUT rule 20 action 'permit' + set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv4-unicast route-map export 'AS65535-OUT' + set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv4-unicast route-map import 'AS65535-IN' + set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv6-unicast route-map export 'AS65535-OUT' + set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv6-unicast route-map import 'AS65535-IN' + +**Node2:** + +.. code-block:: none + + set policy prefix-list AS65534-IN rule 10 action 'permit' + set policy prefix-list AS65534-IN rule 10 prefix '172.17.0.0/16' + set policy prefix-list AS65534-OUT rule 10 action 'deny' + set policy prefix-list AS65534-OUT rule 10 prefix '172.17.0.0/16' + set policy prefix-list6 AS65534-IN rule 10 action 'permit' + set policy prefix-list6 AS65534-IN rule 10 prefix '2001:db8:1::/48' + set policy prefix-list6 AS65534-OUT rule 10 action 'deny' + set policy prefix-list6 AS65534-OUT rule 10 prefix '2001:db8:1::/48' + set policy route-map AS65534-IN rule 10 action 'permit' + set policy route-map AS65534-IN rule 10 match ip address prefix-list 'AS65534-IN' + set policy route-map AS65534-IN rule 10 match ipv6 address prefix-list 'AS65534-IN' + set policy route-map AS65534-IN rule 20 action 'deny' + set policy route-map AS65534-OUT rule 10 action 'deny' + set policy route-map AS65534-OUT rule 10 match ip address prefix-list 'AS65534-OUT' + set policy route-map AS65534-OUT rule 10 match ipv6 address prefix-list 'AS65534-OUT' + set policy route-map AS65534-OUT rule 20 action 'permit' + set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv4-unicast route-map export 'AS65534-OUT' + set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv4-unicast route-map import 'AS65534-IN' + set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv6-unicast route-map export 'AS65534-OUT' + set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv6-unicast route-map import 'AS65534-IN' + +We could expand on this and also deny link local and multicast in the rule 20 +action deny. diff --git a/docs/configuration/protocols/igmp-proxy.rst b/docs/configuration/protocols/igmp-proxy.rst new file mode 100644 index 00000000..cce5f948 --- /dev/null +++ b/docs/configuration/protocols/igmp-proxy.rst @@ -0,0 +1,2 @@ +igmp-proxy +########## \ No newline at end of file diff --git a/docs/configuration/protocols/igmp.rst b/docs/configuration/protocols/igmp.rst new file mode 100644 index 00000000..9104b0c9 --- /dev/null +++ b/docs/configuration/protocols/igmp.rst @@ -0,0 +1,244 @@ +.. _multicast: + +######### +Multicast +######### + +VyOS facilitates IP Multicast by supporting **PIM Sparse Mode**, +**IGMP** and **IGMP-Proxy**. + +************ +PIM and IGMP +************ + +PIM (Protocol Independent Multicast) must be configured in every +interface of every participating router. Every router must also have the +location of the Rendevouz Point manually configured. Then, +unidirectional shared trees rooted at the Rendevouz Point will +automatically be built for multicast distribution. + +Traffic from multicast sources will go to the Rendezvous Point, and +receivers will pull it from a shared tree using IGMP (Internet Group +Management Protocol). + +Multicast receivers will talk IGMP to their local router, so, besides +having PIM configured in every router, IGMP must also be configured in +any router where there could be a multicast receiver locally connected. + +VyOS supports both IGMP version 2 and version 3 (which allows +source-specific multicast). + + +Example +======= + +In the following example we can see a basic multicast setup: + +.. image:: /_static/images/multicast-basic.png + :width: 90% + :align: center + :alt: Network Topology Diagram + + + +**Router 1** + +.. code-block:: none + + set interfaces ethernet eth2 address '172.16.0.2/24' + set interfaces ethernet eth1 address '100.64.0.1/24' + set protocols ospf area 0 network '172.16.0.0/24' + set protocols ospf area 0 network '100.64.0.0/24' + set protocols igmp interface eth1 + set protocols pim interface eth1 + set protocols pim interface eth2 + set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' + +**Router 3** + +.. code-block:: none + + set interfaces dummy dum0 address '172.16.255.1/24' + set interfaces ethernet eth0 address '172.16.0.1/24' + set interfaces ethernet eth1 address '172.16.1.1/24' + set protocols ospf area 0 network '172.16.0.0/24' + set protocols ospf area 0 network '172.16.255.0/24' + set protocols ospf area 0 network '172.16.1.0/24' + set protocols pim interface dum0 + set protocols pim interface eth0 + set protocols pim interface eth1 + set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' + +**Router 2** + +.. code-block:: none + + set interfaces ethernet eth1 address '10.0.0.1/24' + set interfaces ethernet eth2 address '172.16.1.2/24' + set protocols ospf area 0 network '10.0.0.0/24' + set protocols ospf area 0 network '172.16.1.0/24' + set protocols pim interface eth1 + set protocols pim interface eth2 + set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' + + + + + +Basic commands +============== + +These are the commands for a basic setup. + +.. cfgcmd:: set protocols pim interface + + Use this command to enable PIM in the selected interface so that it + can communicate with PIM neighbors. + + +.. cfgcmd:: set protocols pim rp address
group + + Use this comand to manually configure a Rendevouz Point for PIM so + that join messages can be sent there. Set the Rendevouz Point address + and the matching prefix of group ranges covered. These values must + be shared with every router participating in the PIM network. + + +.. cfgcmd:: set protocols igmp interface eth1 + + Use this command to configure an interface with IGMP so that PIM can + receive IGMP reports and query on the selected interface. By defaul + IGMP version 3 will be used. + + + +Tuning commands +=============== + +You can also tune multicast with the following commands. + +.. cfgcmd:: set protocols pim interface dr-priority + + Use this PIM command in the selected interface to set the priority + (1-4294967295) you want to influence in the election of a node to + become the Designated Router for a LAN segment. The default priority + is 1, set a higher value to give the router more preference in the + DR election process. + + +.. cfgcmd:: set protocols pim int hello + + Use this command to configure the PIM hello interval in seconds + (1-180) for the selected interface. + + +.. cfgcmd:: set protocols pim rp keep-alive-timer + + Use this PIM command to modify the the time out value (31-60000 + seconds) for an `(S,G) `_ + flow. 31 seconds is chosen for a lower bound as some hardware + platforms cannot see data flowing in better than 30 second chunks. + + +.. cfgcmd:: set protocols igmp interface join source + + Use this command to allow the selected interface join a multicast + group defining the multicast address you want to join and the source + IP address too. + + +.. cfgcmd:: set protocols igmp interface + + Use this command to configure in the selected interface the IGMP + host query interval (1-1800) in seconds that PIM will use. + + +.. cfgcmd:: set protocols igmp interface + + Use this command to configure in the selected interface the IGMP + query response timeout value (10-250) in deciseconds. If a report is + not returned in the specified time, it will be asumed the `(S,G) or + (*,G) state `_ has + timed out. + + +.. cfgcmd:: set protocols igmp interface version + + Use this command to define in the selected interface whether you + choose IGMP version 2 or 3. The default value is 3. + + + +********** +IGMP Proxy +********** + +:abbr:`IGMP (Internet Group Management Protocol)` proxy sends IGMP host messages +on behalf of a connected client. The configuration must define one, and only one +upstream interface, and one or more downstream interfaces. + +Configuration +============= + +.. cfgcmd:: set protocols igmp-proxy interface role + + * **upstream:** The upstream network interface is the outgoing interface + which is responsible for communicating to available multicast data sources. + There can only be one upstream interface. + + * **downstream:** Downstream network interfaces are the distribution + interfaces to the destination networks, where multicast clients can join + groups and receive multicast data. One or more downstream interfaces must + be configured. + +.. cfgcmd:: set protocols igmp-proxy interface alt-subnet + + Defines alternate sources for multicasting and IGMP data. The network address + must be on the following format 'a.b.c.d/n'. By default the router will + accept data from sources on the same network as configured on an interface. + If the multicast source lies on a remote network, one must define from where + traffic should be accepted. + + This is especially useful for the upstream interface, since the source for + multicast traffic is often from a remote location. + + This option can be supplied multiple times. + +.. cfgcmd:: set protocols igmp-proxy disable-quickleave + + Disables quickleave mode. In this mode the daemon will not send a Leave IGMP + message upstream as soon as it receives a Leave message for any downstream + interface. The daemon will not ask for Membership reports on the downstream + interfaces, and if a report is received the group is not joined again + upstream. + + If it's vital that the daemon should act exactly as a real multicast client + on the upstream interface, this function should be enabled. + + Enabling this function increases the risk of bandwidth saturation. + +.. cfgcmd:: set protocols igmp-proxy disable + + Disable this service. + +Example +------- + +Interface `eth1` LAN is behind NAT. In order to subscribe `10.0.0.0/23` subnet +multicast which is in `eth0` WAN we need to configure igmp-proxy. + +.. code-block:: none + + set protocols igmp-proxy interface eth0 role upstream + set protocols igmp-proxy interface eth0 alt-subnet 10.0.0.0/23 + set protocols igmp-proxy interface eth1 role downstream + +Operation +========= + +.. opcmd:: restart igmp-proxy + + Restart the IGMP proxy process. + + + diff --git a/docs/configuration/protocols/index.rst b/docs/configuration/protocols/index.rst new file mode 100644 index 00000000..271b6056 --- /dev/null +++ b/docs/configuration/protocols/index.rst @@ -0,0 +1,22 @@ +######### +Protocols +######### + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + bfd + bgp + igmp + igmp-proxy + mpls + ospf + ospfv3 + pim + rip + ripng + rpki + static + vrf diff --git a/docs/configuration/protocols/mpls.rst b/docs/configuration/protocols/mpls.rst new file mode 100644 index 00000000..82e99a17 --- /dev/null +++ b/docs/configuration/protocols/mpls.rst @@ -0,0 +1,157 @@ +.. _mpls: + +#################################### +MPLS (Multiprotocol Label Switching) +#################################### + +:abbr:`MPLS (Multi-Protocol Label Switching)` is a packet forwarding paradigm +which differs from regular IP forwarding. Instead of IP addresses being used to +make the decision on finding the exit interface, a router will instead use an +exact match on a 32 bit/4 byte header called the MPLS label. This label is +inserted between the ethernet (layer 2) header and the IP (layer 3) header. +One can statically or dynamically assign label allocations, but we will focus +on dynamic allocation of labels using some sort of label distribution protocol +(such as the aptly named Label Distribution Protocol / LDP, Resource Reservation +Protocol / RSVP, or Segment Routing through OSPF/ISIS). These protocols allow +for the creation of a unidirectional/unicast path called a labeled switched +path (initialized as LSP) throughout the network that operates very much like +a tunnel through the network. An easy way of thinking about how an MPLS LSP +actually forwards traffic throughout a network is to think of a GRE tunnel. +They are not the same in how they operate, but they are the same in how they +handle the tunneled packet. It would be good to think of MPLS as a tunneling +technology that can be used to transport many different types of packets, to +aid in traffic engineering by allowing one to specify paths throughout the +network (using RSVP or SR), and to generally allow for easier intra/inter +network transport of data packets. + +For more information on how MPLS label switching works, please go visit +`Wikipedia (MPLS)`_. + +.. note:: MPLS support in VyOS is not finished yet, and therefore its + functionality is limited. Currently there is no support for MPLS enabled VPN + services such as L3VPNs, L2VPNs, and mVPNs. RSVP support is also not present + as the underlying routing stack (FRR) does not implement it. Currently VyOS + can be configured as a label switched router (MPLS P router), in both + penultimate and ultimate hop popping operations. + +Label Distribution Protocol +=========================== + +The :abbr:`MPLS (Multi-Protocol Label Switching)` architecture does not assume +a single protocol to create MPLS paths. VyOS supports the Label Distribution +Protocol (LDP) as implemented by FRR, based on :rfc:`5036`. + +:abbr:`LDP (Label Distribution Protocol)` is a TCP based MPLS signaling protocol +that distributes labels creating MPLS label switched paths in a dynamic manner. +LDP is not a routing protocol, as it relies on other routing protocols for +forwarding decisions. LDP cannot bootstrap itself, and therefore relies on said +routing protocols for communication with other routers that use LDP. + +In order to allow for LDP on the local router to exchange label advertisements +with other routers, a TCP session will be established between automatically +discovered and statically assigned routers. LDP will try to establish a TCP +session to the **transport address** of other routers. Therefore for LDP to +function properly please make sure the transport address is shown in the +routing table and reachable to traffic at all times. + +It is highly recommended to use the same address for both the LDP router-id and +the discovery transport address, but for VyOS MPLS LDP to work both parameters +must be explicitly set in the configuration. + +Configuration Options +===================== + +.. cfgcmd:: set protocols mpls ldp interface + + Use this command to enable LDP, and enable MPLS processing on the interface you + define. + +.. cfgcmd:: set protocols mpls ldp router-id
+ + Use this command to configure the IP address used as the LDP router-id of the + local device. + +.. cfgcmd:: set protocols mpls ldp discovery transport-ipv4-address +.. cfgcmd:: set protocols mpls ldp discovery transport-ipv6-address + + Use this command to set the IPv4 or IPv6 transport-address used by LDP. + +.. cfgcmd:: set protocols mpls ldp neighbor password + + Use this command to configure authentication for LDP peers. Set the + IP address of the LDP peer and a password that should be shared in + order to become neighbors. + +.. cfgcmd:: set protocols mpls ldp discovery hello-interval +.. cfgcmd:: set protocols mpls ldp discovery hello-holdtime + + Use this command if you would like to set the discovery hello and hold time + parameters. + +.. cfgcmd:: set protocols mpls ldp discovery session-ipv4-holdtime +.. cfgcmd:: set protocols mpls ldp discovery session-ipv6-holdtime + + Use this command if you would like to set the TCP session hold time intervals. + +.. cfgcmd:: set protocols mpls ldp export ipv4 explicit-null +.. cfgcmd:: set protocols mpls ldp export ipv6 explicit-null + + Use this command if you would like for the router to advertise FECs with a label + of 0 for explicit null operations. + + +Sample configuration to setup LDP on VyOS +----------------------------------------- + +.. code-block:: none + + set protocols ospf area 0 network '192.168.255.252/32' <--- Routing for loopback + set protocols ospf area 0 network '192.168.0.5/32' <--- Routing for an interface connecting to the network + set protocols ospf parameters router-id '192.168.255.252' <--- Router ID setting for OSPF + set protocols mpls ldp discovery transport-ipv4-address '192.168.255.252' <--- Transport address for LDP for TCP sessions to connect to + set protocols mpls ldp interface 'eth1' <--- Enable MPLS and LDP for an interface connecting to network + set protocols mpls ldp interface 'lo' <--- Enable MPLS and LDP on loopback for future services connectivity + set protocols mpls ldp router-id '192.168.255.252' <--- Router ID setting for LDP + set interfaces ethernet eth1 address '192.168.0.5/31' <--- Interface IP for connecting to network + set interfaces loopback lo address '192.168.255.252/32' <--- Interface loopback IP for router ID and other uses + + +Operational Mode Commands +========================= + +When LDP is working, you will be able to see label information in the outcome +of ``show ip route``. Besides that information, there are also specific *show* +commands for LDP: + +Show +---- + +.. opcmd:: show mpls ldp binding + + Use this command to see the Label Information Base. + +.. opcmd:: show mpls ldp discovery + + Use this command to see discovery hello information + +.. opcmd:: show mpls ldp interface + + Use this command to see LDP interface information + +.. opcmd:: show mpls ldp neighbor + + Use this command to see LDP neighbor information + +.. opcmd:: show mpls ldp neighbor detail + + Use this command to see detailed LDP neighbor information + +Reset +----- + +.. opcmd:: reset mpls ldp neighbor + + Use this command to reset an LDP neighbor/TCP session that is established + + +.. _`Wikipedia (MPLS)`: https://en.wikipedia.org/wiki/Multiprotocol_Label_Switching diff --git a/docs/configuration/protocols/ospf.rst b/docs/configuration/protocols/ospf.rst new file mode 100644 index 00000000..ff7c5e64 --- /dev/null +++ b/docs/configuration/protocols/ospf.rst @@ -0,0 +1,70 @@ +.. include:: /_include/need_improvement.txt + +.. _routing-ospf: + +#### +OSPF +#### + +:abbr:`OSPF (Open Shortest Path First)` is a routing protocol for Internet +Protocol (IP) networks. It uses a link state routing (LSR) algorithm and falls +into the group of interior gateway protocols (IGPs), operating within a single +autonomous system (AS). It is defined as OSPF Version 2 in :rfc:`2328` (1998) +for IPv4. Updates for IPv6 are specified as OSPF Version 3 in :rfc:`5340` +(2008). OSPF supports the :abbr:`CIDR (Classless Inter-Domain Routing)` +addressing model. + +OSPF is a widely used IGP in large enterprise networks. + +OSPFv2 (IPv4) +############# + +In order to have a VyOS system exchanging routes with OSPF neighbors, you will +at least need to configure an OSPF area and some network. + +.. code-block:: none + + set protocols ospf area 0 network 192.168.0.0/24 + +That is the minimum configuration you will need. +It is a good practice to define the router ID too. + +.. code-block:: none + + set protocols ospf parameters router-id 10.1.1.1 + + +Below you can see a typical configuration using 2 nodes, redistribute loopback +address and the node 1 sending the default route: + +**Node 1** + +.. code-block:: none + + set interfaces loopback lo address 10.1.1.1/32 + set protocols ospf area 0 network 192.168.0.0/24 + set protocols ospf default-information originate always + set protocols ospf default-information originate metric 10 + set protocols ospf default-information originate metric-type 2 + set protocols ospf log-adjacency-changes + set protocols ospf parameters router-id 10.1.1.1 + set protocols ospf redistribute connected metric-type 2 + set protocols ospf redistribute connected route-map CONNECT + + set policy route-map CONNECT rule 10 action permit + set policy route-map CONNECT rule 10 match interface lo + +**Node 2** + +.. code-block:: none + + set interfaces loopback lo address 10.2.2.2/32 + set protocols ospf area 0 network 192.168.0.0/24 + set protocols ospf log-adjacency-changes + set protocols ospf parameters router-id 10.2.2.2 + set protocols ospf redistribute connected metric-type 2 + set protocols ospf redistribute connected route-map CONNECT + + set policy route-map CONNECT rule 10 action permit + set policy route-map CONNECT rule 10 match interface lo + diff --git a/docs/configuration/protocols/ospfv3.rst b/docs/configuration/protocols/ospfv3.rst new file mode 100644 index 00000000..f0e28983 --- /dev/null +++ b/docs/configuration/protocols/ospfv3.rst @@ -0,0 +1,71 @@ +OSPFv3 (IPv6) +############# + +A typical configuration using 2 nodes. + +**Node 1:** + +.. code-block:: none + + set protocols ospfv3 area 0.0.0.0 interface eth1 + set protocols ospfv3 area 0.0.0.0 range 2001:db8:1::/64 + set protocols ospfv3 parameters router-id 192.168.1.1 + set protocols ospfv3 redistribute connected + +**Node 2:** + +.. code-block:: none + + set protocols ospfv3 area 0.0.0.0 interface eth1 + set protocols ospfv3 area 0.0.0.0 range 2001:db8:2::/64 + set protocols ospfv3 parameters router-id 192.168.2.1 + set protocols ospfv3 redistribute connected + +.. note:: You can not easily redistribute IPv6 routes via OSPFv3 on a WireGuard + interface link. This requires you to configure link-local addresses manually + on the WireGuard interfaces, see :vytask:`T1483`. + +Example configuration for WireGuard interfaces: + +**Node 1** + +.. code-block:: none + + set interfaces wireguard wg01 address 'fe80::216:3eff:fe51:fd8c/64' + set interfaces wireguard wg01 address '192.168.0.1/24' + set interfaces wireguard wg01 peer ospf02 allowed-ips '::/0' + set interfaces wireguard wg01 peer ospf02 allowed-ips '0.0.0.0/0' + set interfaces wireguard wg01 peer ospf02 endpoint '10.1.1.101:12345' + set interfaces wireguard wg01 peer ospf02 pubkey 'ie3...=' + set interfaces wireguard wg01 port '12345' + set protocols ospfv3 parameters router-id 192.168.1.1 + set protocols ospfv3 area 0.0.0.0 interface 'wg01' + set protocols ospfv3 area 0.0.0.0 interface 'lo' + +**Node 2** + +.. code-block:: none + + set interfaces wireguard wg01 address 'fe80::216:3eff:fe0a:7ada/64' + set interfaces wireguard wg01 address '192.168.0.2/24' + set interfaces wireguard wg01 peer ospf01 allowed-ips '::/0' + set interfaces wireguard wg01 peer ospf01 allowed-ips '0.0.0.0/0' + set interfaces wireguard wg01 peer ospf01 endpoint '10.1.1.100:12345' + set interfaces wireguard wg01 peer ospf01 pubkey 'NHI...=' + set interfaces wireguard wg01 port '12345' + set protocols ospfv3 parameters router-id 192.168.1.2 + set protocols ospfv3 area 0.0.0.0 interface 'wg01' + set protocols ospfv3 area 0.0.0.0 interface 'lo' + +**Status** + +.. code-block:: none + + vyos@ospf01:~$ sh ipv6 ospfv3 neighbor + Neighbor ID Pri DeadTime State/IfState Duration I/F[State] + 192.168.0.2 1 00:00:37 Full/PointToPoint 00:18:03 wg01[PointToPoint] + + vyos@ospf02# run sh ipv6 ospfv3 neighbor + Neighbor ID Pri DeadTime State/IfState Duration I/F[State] + 192.168.0.1 1 00:00:39 Full/PointToPoint 00:19:44 wg01[PointToPoint] + diff --git a/docs/configuration/protocols/pim.rst b/docs/configuration/protocols/pim.rst new file mode 100644 index 00000000..1dd373d8 --- /dev/null +++ b/docs/configuration/protocols/pim.rst @@ -0,0 +1,2 @@ +PIM +### \ No newline at end of file diff --git a/docs/configuration/protocols/rip.rst b/docs/configuration/protocols/rip.rst new file mode 100644 index 00000000..0d73ad34 --- /dev/null +++ b/docs/configuration/protocols/rip.rst @@ -0,0 +1,37 @@ +.. include:: /_include/need_improvement.txt + +.. _rip: + +### +RIP +### + +:abbr:`RIP (Routing Information Protocol)` is a widely deployed interior gateway +protocol. RIP was developed in the 1970s at Xerox Labs as part of the XNS +routing protocol. RIP is a distance-vector protocol and is based on the +Bellman-Ford algorithms. As a distance-vector protocol, RIP router send updates +to its neighbors periodically, thus allowing the convergence to a known +topology. In each update, the distance to any given network will be broadcast +to its neighboring router. + +Supported versions of RIP are: +* RIPv1 as described in :rfc:`1058` +* RIPv2 as described in :rfc:`2453` + +Simple RIP configuration using 2 nodes and redistributing connected interfaces. + +**Node 1:** + +.. code-block:: none + + set interfaces loopback address 10.1.1.1/32 + set protocols rip network 192.168.0.0/24 + set protocols rip redistribute connected + +**Node 2:** + +.. code-block:: none + + set interfaces loopback address 10.2.2.2/32 + set protocols rip network 192.168.0.0/24 + set protocols rip redistribute connected diff --git a/docs/configuration/protocols/ripng.rst b/docs/configuration/protocols/ripng.rst new file mode 100644 index 00000000..dec6bddf --- /dev/null +++ b/docs/configuration/protocols/ripng.rst @@ -0,0 +1,3 @@ +##### +RIPng +##### \ No newline at end of file diff --git a/docs/configuration/protocols/rpki.rst b/docs/configuration/protocols/rpki.rst new file mode 100644 index 00000000..9813b1b6 --- /dev/null +++ b/docs/configuration/protocols/rpki.rst @@ -0,0 +1,113 @@ +.. _rpki: + +#### +RPKI +#### + +.. pull-quote:: + + There are two types of Network Admins who deal with BGP, those who have + created an international incident and/or outage, and those who are lying + + -- `tweet by EvilMog`_, 2020-02-21 + +:abbr:`RPKI (Resource Public Key Infrastructure)` is a framework :abbr:`PKI +(Public Key Infrastructure)` designed to secure the Internet routing +infrastructure. It associates BGP route announcements with the correct +originating :abbr:`ASN (Autonomus System Number)` which BGP routers can then +use to check each route against the corresponding :abbr:`ROA (Route Origin +Authorisation)` for validity. RPKI is described in :rfc:`6480`. + +A BGP-speaking router like VyOS can retrieve ROA information from RPKI +"Relying Party software" (often just called an "RPKI server" or "RPKI +validator") by using :abbr:`RTR (RPKI to Router)` protocol. There are several +open source implementations to choose from, such as NLNetLabs' Routinator_ +(written in Rust), Cloudflare's GoRTR_ and OctoRPKI_ (written in Go), and +RIPE NCC's RPKI Validator_ (written in Java). The RTR protocol is described +in :rfc:`8210`. + +.. tip:: + If you are new to these routing security technologies then there is an + `excellent guide to RPKI`_ by NLnet Labs which will get you up to speed + very quickly. Their documentation explains everything from what RPKI is to + deploying it in production (albeit with a focus on using NLnet Labs' + tools). It also has some `help and operational guidance`_ including + "What can I do about my route having an Invalid state?" + +First you will need to deploy an RPKI validator for your routers to use. The +RIPE NCC helpfully provide `some instructions`_ to get you started with +several different options. Once your server is running you can start +validating announcements. + +Imported prefixes during the validation may have values: + + valid + The prefix and ASN that originated it match a signed ROA. These are + probably trustworthy route announcements. + + invalid + The prefix or prefix length and ASN that originated it doesn't + match any existing ROA. This could be the result of a prefix hijack, or + merely a misconfiguration, but should probably be treated as + untrustworthy route announcements. + + notfound + No ROA exists which covers that prefix. Unfortunately this is the case + for about 80% of the IPv4 prefixes which were announced to the :abbr:`DFZ + (default-free zone)` at the start of 2020 (see more detail in + NLnet Labs' `RPKI analytics`_). + +.. note:: + If you are responsible for the global addresses assigned to your + network, please make sure that your prefixes have ROAs associated with them + to avoid being `notfound` by RPKI. For most ASNs this will involve + publishing ROAs via your :abbr:`RIR (Regional Internet Registry)` (RIPE + NCC, APNIC, ARIN, LACNIC or AFRINIC), and is something you are encouraged + to do whenever you plan to announce addresses into the DFZ. + + Particularly large networks may wish to run their own RPKI certificate + authority and publication server instead of publishing ROAs via their RIR. + This is a subject far beyond the scope of VyOS' documentation. Consider + reading about Krill_ if this is a rabbit hole you need or especially want + to dive down. + +We can build route-maps for import based on these states. Here is a simple +RPKI configuration, where `routinator` is the RPKI-validating "cache" +server with ip `192.0.2.1`: + +.. code-block:: none + + set protocols rpki cache routinator address '192.0.2.1' + set protocols rpki cache routinator port '3323' + +Here is an example route-map to apply to routes learned at import. In this +filter we reject prefixes with the state `invalid`, and set a higher +`local-preference` if the prefix is RPKI `valid` rather than merely +`notfound`. + +.. code-block:: none + + set policy route-map ROUTES-IN rule 10 action 'permit' + set policy route-map ROUTES-IN rule 10 match rpki 'valid' + set policy route-map ROUTES-IN rule 10 set local-preference '300' + set policy route-map ROUTES-IN rule 20 action 'permit' + set policy route-map ROUTES-IN rule 20 match rpki 'notfound' + set policy route-map ROUTES-IN rule 20 set local-preference '125' + set policy route-map ROUTES-IN rule 30 action 'deny' + set policy route-map ROUTES-IN rule 30 match rpki 'invalid' + +Once your routers are configured to reject RPKI-invalid prefixes, you can +test whether the configuration is working correctly using the `RIPE Labs RPKI +Test`_ experimental tool. + +.. _tweet by EvilMog: https://twitter.com/Evil_Mog/status/1230924170508169216 +.. _Routinator: https://www.nlnetlabs.nl/projects/rpki/routinator/ +.. _GoRTR: https://github.com/cloudflare/gortr +.. _OctoRPKI: https://github.com/cloudflare/cfrpki#octorpki +.. _Validator: https://www.ripe.net/manage-ips-and-asns/resource-management/certification/tools-and-resources +.. _some instructions: https://labs.ripe.net/Members/tashi_phuntsho_3/how-to-install-an-rpki-validator +.. _Krill: https://www.nlnetlabs.nl/projects/rpki/krill/ +.. _RPKI analytics: https://www.nlnetlabs.nl/projects/rpki/rpki-analytics/ +.. _RIPE Labs RPKI Test: https://sg-pub.ripe.net/jasper/rpki-web-test/ +.. _excellent guide to RPKI: https://rpki.readthedocs.io/ +.. _help and operational guidance: https://rpki.readthedocs.io/en/latest/about/help.html diff --git a/docs/configuration/protocols/static.rst b/docs/configuration/protocols/static.rst new file mode 100644 index 00000000..fbde8228 --- /dev/null +++ b/docs/configuration/protocols/static.rst @@ -0,0 +1,195 @@ +.. _static-routing: + +###### +Static +###### + +Static routes are manually configured routes, which, in general, cannot be +updated dynamically from information VyOS learns about the network topology from +other routing protocols. However, if a link fails, the router will remove +routes, including static routes, from the :abbr:`RIPB (Routing Information +Base)` that used this interface to reach the next hop. In general, static +routes should only be used for very simple network topologies, or to override +the behavior of a dynamic routing protocol for a small number of routes. The +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 +############# + +.. cfgcmd:: set protocols static route next-hop
+ + Configure next-hop `
` for an IPv4 static route. Multiple static + routes can be created. + +.. cfgcmd:: set protocols static route next-hop
disable + + Disable this IPv4 static route entry. + +.. cfgcmd:: set protocols static route next-hop
distance + + Defines next-hop distance for this route, routes with smaller administrative + distance are elected prior those with a higher distance. + + Range is 1 to 255, default is 1. + + .. note:: Routes with a distance of 255 are effectively disabled and not + installed into the kernel. + +.. cfgcmd:: set protocols static route6 next-hop
+ + Configure next-hop `
` for an IPv6 static route. Multiple static + routes can be created. + +.. cfgcmd:: set protocols static route6 next-hop
disable + + Disable this IPv6 static route entry. + +.. cfgcmd:: set protocols static route6 next-hop
distance + + Defines next-hop distance for this route, routes with smaller administrative + distance are elected prior those with a higher distance. + + Range is 1 to 255, default is 1. + + .. note:: Routes with a distance of 255 are effectively disabled and not + installed into the kernel. + + +Interface Routes +================ + +.. cfgcmd:: set protocols static interface-route next-hop-interface + + Allows you to configure the next-hop interface for an interface-based IPv4 + static route. `` will be the next-hop interface where trafic is + routed for the given ``. + +.. cfgcmd:: set protocols static interface-route next-hop-interface disable + + Disables interface-based IPv4 static route. + +.. cfgcmd:: set protocols static interface-route next-hop-interface distance + + Defines next-hop distance for this route, routes with smaller administrative + distance are elected prior those with a higher distance. + + Range is 1 to 255, default is 1. + +.. cfgcmd:: set protocols static interface-route6 next-hop-interface + + Allows you to configure the next-hop interface for an interface-based IPv6 + static route. `` will be the next-hop interface where trafic is + routed for the given ``. + +.. cfgcmd:: set protocols static interface-route6 next-hop-interface disable + + Disables interface-based IPv6 static route. + +.. cfgcmd:: set protocols static interface-route6 next-hop-interface distance + + Defines next-hop distance for this route, routes with smaller administrative + distance are elected prior those with a higher distance. + + Range is 1 to 255, default is 1. + + +Blackhole +========= + +.. cfgcmd:: set protocols static route 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 blackhole distance + + Defines blackhole distance for this route, routes with smaller administrative + distance are elected prior those with a higher distance. + +.. cfgcmd:: set protocols static route6 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 route6 blackhole distance + + Defines blackhole distance for this route, routes with smaller administrative + distance are elected prior those with a higher distance. + + +Alternate Routing Tables +======================== + +TBD + +Alternate routing tables are used with policy based routing of 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
hwaddr + + This will configure a static ARP entry always resolving `
` to + ``. + + Example: + + .. code-block:: none + + set protocols static arp 192.0.2.100 hwaddr 00:53:27:de:23:aa + +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/vrf.rst b/docs/configuration/protocols/vrf.rst new file mode 100644 index 00000000..e7609a77 --- /dev/null +++ b/docs/configuration/protocols/vrf.rst @@ -0,0 +1,3 @@ +############# +Protocols VRF +############# diff --git a/docs/configuration/service/broadcast-relay.rst b/docs/configuration/service/broadcast-relay.rst new file mode 100644 index 00000000..df48bfd6 --- /dev/null +++ b/docs/configuration/service/broadcast-relay.rst @@ -0,0 +1,61 @@ +.. _udp_broadcast_relay: + +################### +UDP Broadcast Relay +################### + +Certain vendors use broadcasts to identify their equipment within one ethernet +segment. Unfortunately if you split your network with multiple VLANs you loose +the ability of identifying your equipment. + +This is where "UDP broadcast relay" comes into play! It will forward received +broadcasts to other configured networks. + +Every UDP port which will be forward requires one unique ID. Currently we +support 99 IDs! + +Configuration +------------- + +.. cfgcmd:: set service broadcast-relay id description + + A description can be added for each and every unique relay ID. This is + useful to distinguish between multiple different ports/appliactions. + +.. cfgcmd:: set service broadcast-relay id interface + + The interface used to receive and relay individual broadcast packets. If you + want to receive/relay packets on both `eth1` and `eth2` both interfaces need + to be added. + +.. cfgcmd:: set service broadcast-relay id port + + The UDP port number used by your apllication. It is mandatory for this kind + of operation. + +.. cfgcmd:: set service broadcast-relay id disable + + Each broadcast relay instance can be individually disabled without deleting + the configured node by using the following command: + +.. cfgcmd:: set service broadcast-relay disable + + In addition you can also disable the whole service without the need to remove + it from the current configuration. + +.. note:: You can run the UDP broadcast relay service on multiple routers + connected to a subnet. There is **NO** UDP broadcast relay packet storm! + +Example +------- + +To forward all broadcast packets received on `UDP port 1900` on `eth3`, `eth4` +or `eth5` to all other interfaces in this configuration. + +.. code-block:: none + + set service broadcast-relay id 1 description 'SONOS' + set service broadcast-relay id 1 interface 'eth3' + set service broadcast-relay id 1 interface 'eth4' + set service broadcast-relay id 1 interface 'eth5' + set service broadcast-relay id 1 port '1900' diff --git a/docs/configuration/service/conntrack-sync.rst b/docs/configuration/service/conntrack-sync.rst new file mode 100644 index 00000000..55cd088e --- /dev/null +++ b/docs/configuration/service/conntrack-sync.rst @@ -0,0 +1,200 @@ +.. include:: /_include/need_improvement.txt + +Conntrack +--------- + +One of the important features built on top of the Netfilter framework is +connection tracking. Connection tracking allows the kernel to keep track of all +logical network connections or sessions, and thereby relate all of the packets +which may make up that connection. NAT relies on this information to translate +all related packets in the same way, and iptables can use this information to +act as a stateful firewall. + +The connection state however is completely independent of any upper-level +state, such as TCP's or SCTP's state. Part of the reason for this is that when +merely forwarding packets, i.e. no local delivery, the TCP engine may not +necessarily be invoked at all. Even connectionless-mode transmissions such as +UDP, IPsec (AH/ESP), GRE and other tunneling protocols have, at least, a pseudo +connection state. The heuristic for such protocols is often based upon a preset +timeout value for inactivity, after whose expiration a Netfilter connection is +dropped. + +Each Netfilter connection is uniquely identified by a (layer-3 protocol, source +address, destination address, layer-4 protocol, layer-4 key) tuple. The layer-4 +key depends on the transport protocol; for TCP/UDP it is the port numbers, for +tunnels it can be their tunnel ID, but otherwise is just zero, as if it were +not part of the tuple. To be able to inspect the TCP port in all cases, packets +will be mandatorily defragmented. + +It is possible to use either Multicast or Unicast to sync conntrack traffic. +Most examples below show Multicast, but unicast can be specified by using the +"peer" keywork after the specificed interface, as in the following example: + +set service conntrack-sync interface eth0 peer 192.168.0.250 + +Configuration +^^^^^^^^^^^^^ + +.. code-block:: none + + # Protocols only for which local conntrack entries will be synced (tcp, udp, icmp, sctp) + set service conntrack-sync accept-protocol + + # Queue size for listening to local conntrack events (in MB) + set service conntrack-sync event-listen-queue-size + + # Protocol for which expect entries need to be synchronized. (all, ftp, h323, nfs, sip, sqlnet) + set service conntrack-sync expect-sync + + # Failover mechanism to use for conntrack-sync [REQUIRED] + set service conntrack-sync failover-mechanism + + set service conntrack-sync cluster group + set service conntrack-sync vrrp sync-group <1-255> + + # IP addresses for which local conntrack entries will not be synced + set service conntrack-sync ignore-address ipv4 + + # Interface to use for syncing conntrack entries [REQUIRED] + set service conntrack-sync interface + + # Multicast group to use for syncing conntrack entries + set service conntrack-sync mcast-group + + # Peer to send Unicast UDP conntrack sync entires to, if not using Multicast above + set service conntrack-sync interface peer + + # Queue size for syncing conntrack entries (in MB) + set service conntrack-sync sync-queue-size + +Example +^^^^^^^ +The next example is a simple configuration of conntrack-sync. + + +.. figure:: /_static/images/service_conntrack_sync-schema.png + :scale: 60 % + :alt: Conntrack Sync Example + + Conntrack Sync Example + +First of all, make sure conntrack is enabled by running + +.. code-block:: none + + show conntrack table ipv4 + +If the table is empty and you have a warning message, it means conntrack is not +enabled. To enable conntrack, just create a NAT or a firewall rule. + +.. code-block:: none + + set firewall state-policy established action accept + +You now should have a conntrack table + +.. code-block:: none + + $ show conntrack table ipv4 + TCP state codes: SS - SYN SENT, SR - SYN RECEIVED, ES - ESTABLISHED, + FW - FIN WAIT, CW - CLOSE WAIT, LA - LAST ACK, + TW - TIME WAIT, CL - CLOSE, LI - LISTEN + + CONN ID Source Destination Protocol TIMEOUT + 1015736576 10.35.100.87:58172 172.31.20.12:22 tcp [6] ES 430279 + 1006235648 10.35.101.221:57483 172.31.120.21:22 tcp [6] ES 413310 + 1006237088 10.100.68.100 172.31.120.21 icmp [1] 29 + 1015734848 10.35.100.87:56282 172.31.20.12:22 tcp [6] ES 300 + 1015734272 172.31.20.12:60286 239.10.10.14:694 udp [17] 29 + 1006239392 10.35.101.221 172.31.120.21 icmp [1] 29 + +Now configure conntrack-sync service on ``router1`` **and** ``router2`` + +.. code-block:: none + + set service conntrack-sync accept-protocol 'tcp,udp,icmp' + set service conntrack-sync event-listen-queue-size '8' + set service conntrack-sync failover-mechanism cluster group 'GROUP' + set service conntrack-sync interface 'eth0' + 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``. + +.. code-block:: none + + set high-availablilty vrrp group internal virtual-address ... etc ... + set high-availability vrrp sync-group syncgrp member 'internal' + set service conntrack-sync failover-mechanism vrrp sync-group 'syncgrp' + + +On the active router, you should have information in the internal-cache of +conntrack-sync. The same current active connections number should be shown in +the external-cache of the standby router + +On active router run: + +.. code-block:: none + + $ show conntrack-sync statistics + + Main Table Statistics: + + cache internal: + current active connections: 10 + connections created: 8517 failed: 0 + connections updated: 127 failed: 0 + connections destroyed: 8507 failed: 0 + + cache external: + current active connections: 0 + connections created: 0 failed: 0 + connections updated: 0 failed: 0 + connections destroyed: 0 failed: 0 + + traffic processed: + 0 Bytes 0 Pckts + + multicast traffic (active device=eth0): + 868780 Bytes sent 224136 Bytes recv + 20595 Pckts sent 14034 Pckts recv + 0 Error send 0 Error recv + + message tracking: + 0 Malformed msgs 0 Lost msgs + + + +On standby router run: + + +.. code-block:: none + + + $ show conntrack-sync statistics + + Main Table Statistics: + + cache internal: + current active connections: 0 + connections created: 0 failed: 0 + connections updated: 0 failed: 0 + connections destroyed: 0 failed: 0 + + cache external: + current active connections: 10 + connections created: 888 failed: 0 + connections updated: 134 failed: 0 + connections destroyed: 878 failed: 0 + + traffic processed: + 0 Bytes 0 Pckts + + multicast traffic (active device=eth0): + 234184 Bytes sent 907504 Bytes recv + 14663 Pckts sent 21495 Pckts recv + 0 Error send 0 Error recv + + message tracking: + 0 Malformed msgs 0 Lost msgs + diff --git a/docs/configuration/service/console-server.rst b/docs/configuration/service/console-server.rst new file mode 100644 index 00000000..cf222544 --- /dev/null +++ b/docs/configuration/service/console-server.rst @@ -0,0 +1,107 @@ +.. _console_server: + +############## +Console Server +############## + +Starting of with VyOS 1.3 (equuleus) we added support for running VyOS as an +Out-of-Band Management device which provides remote access by means of SSH to +directly attached serial interfaces. + +Serial interfaces can be any interface which is directly connected to the CPU +or chipset (mostly known as a ttyS interface in Linux) or any other USB to +serial converter (Prolific PL2303 or FTDI FT232/FT4232 based chips). + +If you happened to use a Cisco NM-16A - Sixteen Port Async Network Module or +NM-32A - Thirty-two Port Async Network Module - this is your VyOS replacement. + +For USB port information please refor to: :ref:`hardware_usb`. + +Configuration +============= + +Between computers, the most common configuration used was "8N1": eight bit +characters, with one start bit, one stop bit, and no parity bit. Thus 10 Baud +times are used to send a single character, and so dividing the signalling +bit-rate by ten results in the overall transmission speed in characters per +second. This is also the default setting if none of those options are defined. + +.. cfgcmd:: set service console-server data-bits [7 | 8] + + Configure either seven or eight data bits. This defaults to eight data + bits if left unconfigured. + +.. cfgcmd:: set service console-server description + + A user friendly description identifying the connected peripheral. + +.. cfgcmd:: set service console-server parity [even | odd | none] + + Set the parity option for the console. If unset this will default to none. + +.. cfgcmd:: set service console-server stop-bits [1 | 2] + + Configure either one or two stop bits. This defaults to one stop bits if + left unconfigured. + +.. cfgcmd:: set service console-server 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 + can't cope with the expected speed. + +Remote Access +------------- + +Each individual configured console-server device can be directly exposed to +the outside world. A user can directly connect via SSH to the configured +port. + +.. cfgcmd:: set service console-server ssh port + + Accept SSH connections for the given `` on TCP port ``. + After successfull authentication the user will be directly dropped to + the connected serial device. + + .. hint:: Multiple users can connect to the same serial device but only + one is allowed to write to the console port. + +Operation +========= + +.. opcmd:: show console-server ports + + Show configured serial ports and their respective interface configuration. + + .. code-block:: none + + vyos@vyos:~$ show console-server ports + usb0b2.4p1.0 on /dev/serial/by-bus/usb0b2.4p1.0@ at 9600n + +.. opcmd:: show console-server user + + Show currently connected users. + + .. code-block:: none + + vyos@vyos:~$ show console-server user + usb0b2.4p1.0 up vyos@localhost + + +.. opcmd:: connect console-server + + Locally connect to serial port identified by ``. + + .. code-block:: none + + vyos@vyos-r1:~$ connect console-server usb0b2.4p1.0 + [Enter `^Ec?' for help] + [-- MOTD -- VyOS Console Server] + + vyos-r2 login: + + .. hint:: Multiple users can connect to the same serial device but only + one is allowed to write to the console port. + + .. hint:: The sequence ``^Ec?`` translates to: ``Ctrl+E c ?``. To quit + the session use: ``Ctrl+E c .`` diff --git a/docs/configuration/service/dhcp-relay.rst b/docs/configuration/service/dhcp-relay.rst new file mode 100644 index 00000000..445519b3 --- /dev/null +++ b/docs/configuration/service/dhcp-relay.rst @@ -0,0 +1,2 @@ +dhcp-relay +########## \ No newline at end of file diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst new file mode 100644 index 00000000..56316793 --- /dev/null +++ b/docs/configuration/service/dhcp-server.rst @@ -0,0 +1,776 @@ +.. _dhcp: + +############# +DHCP / DHCPv6 +############# + +VyOS uses ISC DHCPd for both IPv4 and IPv6 address assignment. + +.. _dhcp-server: + +DHCP Server +=========== + +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. + +Configuration +------------- + +.. cfgcmd:: set service dhcp-server shared-network-name 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 subnet default-router
+ + This is a configuration parameter for the ``, saying that as part of + the response, tell the client that the default gateway can be reached at + `
`. + +.. cfgcmd:: set service dhcp-server shared-network-name subnet dns-server
+ + 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 `
`. + + Multiple DNS servers can be defined. + +.. cfgcmd:: set service dhcp-server shared-network-name subnet lease