diff options
Diffstat (limited to 'docs')
57 files changed, 2620 insertions, 1426 deletions
diff --git a/docs/appendix/examples/dmvpn.rst b/docs/appendix/examples/dmvpn.rst index cbb9f300..49b1fcaa 100644 --- a/docs/appendix/examples/dmvpn.rst +++ b/docs/appendix/examples/dmvpn.rst @@ -17,7 +17,7 @@ Configuration set interfaces tunnel tun100 multicast 'enable' set interfaces tunnel tun100 parameters ip key '1' - set protocols nhrp tunnel tun100 cisco-authentication '<nhrp secret key>' + set protocols nhrp tunnel tun100 cisco-authentication <secret> set protocols nhrp tunnel tun100 holding-time '300' set protocols nhrp tunnel tun100 multicast 'dynamic' set protocols nhrp tunnel tun100 redirect @@ -43,7 +43,7 @@ Configuration set vpn ipsec ipsec-interfaces interface 'eth0' set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' - set vpn ipsec profile NHRPVPN authentication pre-shared-secret '<secretkey>' + set vpn ipsec profile NHRPVPN authentication pre-shared-secret <secret> set vpn ipsec profile NHRPVPN bind tunnel 'tun100' set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' diff --git a/docs/appendix/release-notes.rst b/docs/appendix/release-notes.rst new file mode 100644 index 00000000..b9c5ccbe --- /dev/null +++ b/docs/appendix/release-notes.rst @@ -0,0 +1,243 @@ +.. _release-notes: + +############# +Release Notes +############# + +1.2 (Crux) +========== + +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` <regex> 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 <IPv4 net|IPv6 net>" + 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 <intf>" 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 +================ + +See `the wiki <https://wiki.vyos.net/wiki/1.2.0/release_notes>`_. diff --git a/docs/appendix/releasenotes.rst b/docs/appendix/releasenotes.rst deleted file mode 100644 index 13e8fa1c..00000000 --- a/docs/appendix/releasenotes.rst +++ /dev/null @@ -1,140 +0,0 @@ -.. _releasenotes: - -Release notes -############# - -1.2 (Crux) -========== - -1.2.3 ------ - -1.2.3 is a maintenance and feature backport release made in September 2019. - -New features -^^^^^^^^^^^^ - -* HTTP API -* "set service dns forwarding allow-from <IPv4 net|IPv6 net>" option for limiting queries to specific client networks (T1524) -* Functions for checking if a commit is in progress (T1503) -* "set system contig-mangement commit-archive source-address" option (T1543) -* Intel NIC drivers now support receive side scaling and multiqueue (T1554) - -Resolved issues -^^^^^^^^^^^^^^^ - -* OSPF max-metric values over 100 no longer causes commit errors (T1209) -* Fixes issue with DNS forwarding not performing recursive lookups on domain specific forwarders (T1333) -* Special characters in VRRP passwords are handled correctly (T1362) -* BGP weight is applied properly (T1377) -* Fixed permission for log files (T1420) -* Wireguard interfaces now support /31 addresses (T1425) -* Wireguard correctly handles firewall marks (T1428) -* DHCPv6 static mappings now work correctly (T1439) -* Flood ping commands now works correctly (T1450) -* Op mode "show firewall" commands now support counters longer than 8 digits (T1460) -* Fixed priority inversion in VTI commands (T1465) -* Fixed remote-as check in the BGP route-reflector-client option (T1468) -* It's now possible to re-create VRRP groups with RFC compatibility mode enabled (T1472) -* Fixed a typo in DHCPv6 server help strings (T1527) -* Unnumbered BGP peers now support VLAN interfaces (T1529) -* Fixed "set system syslog global archive file" command (T1530) -* Multiple fixes in cluster configuration scripts (T1531) -* Fixed missing help text for "service dns" (T1537) -* Fixed input validation in DHCPv6 relay options (T1541) -* It's now possible to create a QinQ interface and a firewall assigned to it in one commit (T1551) -* URL filtering now uses correct rule database path and works again (T1559) -* "show log vpn ipsec" command works again (T1579) -* "show arp interface <intf>" command works again (T1576) -* Fixed regression in L2TP/IPsec server (T1605) -* Netflow/sFlow captures IPv6 traffic correctly (T1613) -* "renew dhcpv6" command now works from op mode (T1616) -* BGP remove-private-as option iBGP vs eBGP check works correctly now (T1642) -* Multiple improvements in name servers and hosts configuration handling (T1540, T1360, T1264, T1623) - -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 -* VRRP health-check scripts now can use arguments (T1371) -* DNS server addresses coming from a DHCP server are now correctly propagated to resolv.conf (T1497) -* Domain-specific name servers in DNS forwarding are now used for recursive queries (T1469) -* “run show dhcpv6 server leases” now display leases correctly (T1433) -* Deleting “firewall options” node no longer causes errors (T1461) -* Correct hostname is sent to remote syslog again (T1458) -* Board serial number from DMI is correctly displayed in “show version” (T1438) -* Multiple corrections in remote syslog config (T1358, T1355, T1294) -* Fixed missing newline in /etc/hosts (T1255) -* “system domain-name” is correctly included in /etc/resolv.conf (T1174) -* Fixed priority inversion in “interfaces vti vtiX ip” settings (T1465) -* Fixed errors when installing with RAID1 on UEFI machines (T1446) -* Fixed an error on disabling an interfaces that has no address (T1387) -* Fixed deleting VLAN interface with non-default MTU (T1367) -* vyos.config return_effective_values() function now correctly returns a list rather than a string (T1505) - -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. -* 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 (`T1326 <https://phabricator.vyos.net/T1326>`_). -* The collection of network card firmware is now much more extensive. -* VRRP now correctly uses a virtual rather than physical MAC addresses in the RFC-compliant mode (`T1271 <https://phabricator.vyos.net/T1271>`_). -* DHCP WPAD URL option works correctly again (`T1330 <https://phabricator.vyos.net/T1330>`_) -* Many to many NAT rules now can use source/destination and translation networks of non-matching size (`T1312 <https://phabricator.vyos.net/T1312>`_). If 1:1 network bits translation is desired, it’s now user’s responsibility to check if prefix length matches. -* IPv6 network prefix translation is fixed (`T1290 <https://phabricator.vyos.net/T1290>`_). -* Non-alphanumeric characters such as “>” can now be safely used in PPPoE passwords (`T1308 <https://phabricator.vyos.net/T1308>`_). -* “show | commands” no longer fails when a config section ends with a leaf node such as “timezone” in “show system | commands” (`T1305 <https://phabricator.vyos.net/T1305>`_). -* “show | commands” correctly works in config mode now (`T1235 <https://phabricator.vyos.net/T1235>`_). -* VTI is now compatible with the DHCP-interface IPsec option (`T1298 <https://phabricator.vyos.net/T1298>`_). -* “show dhcp server statistics” command was broken in latest Crux (`T1277 <https://phabricator.vyos.net/T1277>`_). -* An issue with TFTP server refusing to listen on addresses other than loopback was fixed (`T1261 <https://phabricator.vyos.net/T1261>`_). -* Template issue that might cause UDP broadcast relay fail to start is fixed (`T1224 <https://phabricator.vyos.net/T1224>`_). -* VXLAN value validation is improved (`T1067 <https://phabricator.vyos.net/T1067>`_). -* Blank hostnames in DHCP updates no longer can crash DNS forwarding (`T1211 <https://phabricator.vyos.net/T1211>`_). -* Correct configuration is now generated for DHCPv6 relays with more than one upstream interface (`T1322 <https://phabricator.vyos.net/T1322>`_). -* “relay-agents-packets” option works correctly now (`T1234 <https://phabricator.vyos.net/T1234>`_). -* Dynamic DNS data is now cleaned on configuration change (`T1231 <https://phabricator.vyos.net/T1231>`_). -* Remote Syslog can now use a fully qualified domain name (`T1282 <https://phabricator.vyos.net/T1282>`_). -* ACPI power off works again (`T1279 <https://phabricator.vyos.net/T1279>`_). -* Negation in WAN load balancing rules works again (`T1247 <https://phabricator.vyos.net/T1247>`_). -* FRR’s staticd now starts on boot correctly (`T1218 <https://phabricator.vyos.net/T1218>`_). -* The installer now correctly detects SD card devices (`T1296 <https://phabricator.vyos.net/T1296>`_). -* Wireguard peers can be disabled now (`T1225 <https://phabricator.vyos.net/T1225>`_). -* The issue with wireguard interfaces impossible to delete is fixed (`T1217 <https://phabricator.vyos.net/T1217>`_). -* Unintended IPv6 access is fixed in SNMP configuration (`T1160 <https://phabricator.vyos.net/T1160>`_). -* It’s now possible to exclude hosts from the transparent web proxy (`T1060 <https://phabricator.vyos.net/T1060>`_). -* An issue with rules impossible to delete from the zone-based firewall is fixed (`T484 <https://phabricator.vyos.net/T484>`_). - -Earlier releases -================ - -See `the wiki <https://wiki.vyos.net/wiki/1.2.0/release_notes>`_. diff --git a/docs/appendix/vyos-on-baremetal.rst b/docs/appendix/vyos-on-baremetal.rst index 76b5e210..5f20a03f 100644 --- a/docs/appendix/vyos-on-baremetal.rst +++ b/docs/appendix/vyos-on-baremetal.rst @@ -107,7 +107,7 @@ VyOS 1.2 (crux) --------------- Depending on the VyOS versions you intend to install there is a difference in -the serial port settings (T1327_). +the serial port settings (:vytask:`T1327`). Create a bootable USB pendrive using e.g. Rufus_ on a Windows machine. @@ -190,7 +190,7 @@ VyOS 1.2 (rolling) ------------------ Installing the rolling release on an APU2 board does not require any change -on the serial console from your host side as T1327_ was successfully +on the serial console from your host side as :vytask:`T1327` was successfully implemented. Simply proceed with a regular image installation as described in @@ -246,8 +246,6 @@ Desktop :alt: APU4C4 desktop back .. _Rufus: https://rufus.ie/ -.. _T1327: https://phabricator.vyos.net/T1327 - Qotom Q355G4 ************ diff --git a/docs/common-references.rst b/docs/common-references.rst new file mode 100644 index 00000000..d7e376eb --- /dev/null +++ b/docs/common-references.rst @@ -0,0 +1,3 @@ +.. _`accel-ppp`: https://accel-ppp.org/ +.. _`Secure Socket Tunneling Protocol`: https://en.wikipedia.org/wiki/Secure_Socket_Tunneling_Protocol +.. _Phabricator: https://phabricator.vyos.net/ diff --git a/docs/conf.py b/docs/conf.py index b5e67368..4c8989ef 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,6 +16,8 @@ import os import sys sys.path.append(os.path.abspath("./_ext")) +from docutils import nodes, utils +from docutils.parsers.rst.roles import set_classes # -- Project information ----------------------------------------------------- @@ -174,6 +176,17 @@ texinfo_documents = [ 'Miscellaneous'), ] + +def vytask_role(name, rawtext, text, lineno, inliner, options={}, content=[]): + app = inliner.document.settings.env.app + base = app.config.vyos_phabricator_url + ref = base + str(text) + set_classes(options) + node = nodes.reference( + rawtext, utils.unescape(str(text)), refuri=ref, **options) + return [node], [] + + def setup(app): pass #app.add_object_type('opcmd', 'opcmd') diff --git a/docs/configuration-overview.rst b/docs/configuration-overview.rst index 352f219c..0ee4e0f5 100644 --- a/docs/configuration-overview.rst +++ b/docs/configuration-overview.rst @@ -4,131 +4,129 @@ Configuration Overview ###################### -VyOS makes use of a unified configuration file for all system configuration: -`config.boot`. This allows for easy template creation, backup, and replication -of system configuration. - -The current active configuration -aka running configuration- can be viewed -using the show configuration command. - -.. code-block:: none - - vyos@vyos:~$ show configuration - interfaces { - ethernet eth0 { - address dhcp - hw-id 00:53:dd:44:3b:0f - } - loopback lo { - } - } - service { - ssh { - port 22 - } - } - system { - config-management { - commit-revisions 20 - } - console { - device ttyS0 { - speed 9600 - } - } - login { - user vyos { - authentication { - encrypted-password **************** - } - level admin - } - } - ntp { - server 0.pool.ntp.org { - } - server 1.pool.ntp.org { - } - server 2.pool.ntp.org { - } - } - syslog { - global { - facility all { - level notice - } - facility protocols { - level debug - } - } - } - } - -By default the configuration is displayed in a hierarchy like the example above, -this is only one of the possible ways to display the configuration. When the -configuration is generated and the device is configured, changes are added -through a collection of ``set`` and ``delete`` commands. - -.. opcmd:: show configuration commands - -Get a collection of all the set commands required which led to this -running configuration. - -.. code-block:: none - - vyos@vyos:~$ show configuration commands - set interfaces ethernet eth0 address 'dhcp' - set interfaces ethernet eth0 hw-id '00:53:dd:44:3b:0f' - set interfaces loopback 'lo' - set service ssh port '22' - set system config-management commit-revisions '20' - set system console device ttyS0 speed '9600' - set system login user vyos authentication encrypted-password '<removed>' - set system login user vyos level 'admin' - set system ntp server '0.pool.ntp.org' - set system ntp server '1.pool.ntp.org' - set system ntp server '2.pool.ntp.org' - set system syslog global facility all level 'notice' - set system syslog global facility protocols level 'debug' - -Both these commands should be executed when in operational mode, they do not -work in configuration mode. +VyOS makes use of a unified configuration file for the entire systems +configuration: ``/config/config.boot``. This allows easy template creation, +backup, and replication of system configuration. A sytem can thus also be +easily cloned by simply copying the required configuration files. Terminology =========== A VyOS system has three major types of configurations: -Active/Running --------------- +* **Active/Running** configuration is the system configuration that is loaded + and currently active (used by VyOS). Any change in the configuration will + have to be committed to belong to the active/running configuration. + +* **Working** - is the configuration which is currently being modified in + configuration mode. Changes made to the working configuration do not go into + effect until the changes are committed with the :cfgcmd:`commit` command. At + which time the working configuration will become the active or running + configuration. + +* **Saved** - is a configuration saved to a file using the :cfgcmd:`save` + command. It allows you to keep safe a configuration for future uses. There + can be multiple configuration files. The default or "boot" configuration is + saved and loaded from the file ``/config/config.boot``. -The active or running configuration is the system configuration that is loaded -and currently being used by VyOS. Any change in the configuration will have to -be committed to belong to the active/running configuration. +Work the Config +=============== -Working -------- +.. opcmd:: show configuration + + View the current active configuration, also known as the running + configuration. + + .. code-block:: none + + vyos@vyos:~$ show configuration + interfaces { + ethernet eth0 { + address dhcp + hw-id 00:53:00:00:aa:01 + } + loopback lo { + } + } + service { + ssh { + port 22 + } + } + system { + config-management { + commit-revisions 20 + } + console { + device ttyS0 { + speed 9600 + } + } + login { + user vyos { + authentication { + encrypted-password **************** + } + level admin + } + } + ntp { + server 0.pool.ntp.org { + } + server 1.pool.ntp.org { + } + server 2.pool.ntp.org { + } + } + syslog { + global { + facility all { + level notice + } + facility protocols { + level debug + } + } + } + } + +By default, the configuration is displayed in a hierarchy like the above +example, this is only one of the possible ways to display the configuration. +When the configuration is generated and the device is configured, changes are +added through a collection of :cfgcmd:`set` and :cfgcmd:`delete` commands. -The working configuration is the configuration which is currently being -modified in configuration mode. Changes made to the working configuration do -not go into effect until the changes are committed with the `commit` command. -At which time the working configuration will become the active or running -configuration. +.. opcmd:: show configuration commands -Saved ------ + Get a collection of all the set commands required which led to this + running configuration. + + .. code-block:: none + + vyos@vyos:~$ show configuration commands + set interfaces ethernet eth0 address 'dhcp' + set interfaces ethernet eth0 hw-id '00:53:dd:44:3b:0f' + set interfaces loopback 'lo' + set service ssh port '22' + set system config-management commit-revisions '20' + set system console device ttyS0 speed '9600' + set system login user vyos authentication encrypted-password '$6$Vt68...QzF0' + set system login user vyos level 'admin' + set system ntp server '0.pool.ntp.org' + set system ntp server '1.pool.ntp.org' + set system ntp server '2.pool.ntp.org' + set system syslog global facility all level 'notice' + set system syslog global facility protocols level 'debug' -A saved configuration is a configuration saved to a file using the ``save`` -command. It allows you to keep safe a configuration for future uses. There can -be multiple configuration files. The default or "boot" configuration is saved -and loaded from the file config.boot. +Both these commands should be executed when in operational mode, they do not +work directly in configuration mode. The is a special way on how to +:ref:`run_opmode_from_config_mode`. Navigating ========== When entering the configuration mode you are navigating inside the tree structure exported in the overview above, to enter configuration mode enter -the command ``configure`` when in operational mode. +the command :opcmd:`configure` when in operational mode. .. code-block:: none @@ -136,14 +134,11 @@ the command ``configure`` when in operational mode. [edit] vyos@vyos# -.. note:: When going into configuration mode, prompt changes from *$* to *#*. - To exit configuration mode, type `exit`. - All commands executed here are relative to the configuration level you have entered. You can do everything from the top level, but commands will be quite lengthy when manually typing them. -To change the current hierarchy level use the command: ``edit`` +The current hierarchy level can be changed by the :cfgcmd:`edit` command. .. code-block:: none @@ -155,13 +150,19 @@ To change the current hierarchy level use the command: ``edit`` You are now in a sublevel relative to ``interfaces ethernet eth0``, all commands executed from this point on are relative to this sublevel. Use either -the ``top`` or ``exit`` command to go back to the top of the hierarchy. You can -also use the ``up`` command to move only one level up at a time. +the :cfgcmd:`top` or :cfgcmd:`exit` command to go back to the top of the +hierarchy. You can also use the :cfgcmd:`up` command to move only one level up +at a time. -The ``show`` command within configuration mode will show the working +The :cfgcmd:`show` command within configuration mode will show the working configuration indicating line changes with ``+`` for additions, ``>`` for replacements and ``-`` for deletions. +.. note:: When going into configuration mode, prompt changes from + ``$`` to ``#``. + +**Example:** + .. code-block:: none vyos@vyos:~$ configure @@ -192,7 +193,7 @@ replacements and ``-`` for deletions. } It is also possible to display all `set` commands within configuration mode -using ``show | commands`` +using :cfgcmd:`show | commands` .. code-block:: none @@ -210,9 +211,9 @@ configuration blocks will be displayed when entering a sub-level. address dhcp hw-id 00:53:ad:44:3b:03 -Exiting from the configuration mode is done via the ``exit`` command from the -top level, executing `exit` from within a sub-level takes you back to the top -level. +Exiting from the configuration mode is done via the :cfgcmd:`exit` command from +the top level, executing :cfgcmd:`exit` from within a sub-level takes you back +to the top level. .. code-block:: none @@ -225,14 +226,13 @@ level. Managing ======== -The configuration is managed by the use of ``set`` and ``delete`` commands from -within configuration mode. Configuration commands are flattened from the tree -into 'one-liner' commands shown in ``show configuration commands`` from -operation mode. +The configuration is managed by the use of :cfgcmd:`set` and :cfgcmd:`delete` +commands from within configuration mode. Configuration commands are flattened +from the tree into 'one-liner' commands shown in :opcmd:`show configuration +commands` from operation mode. -These commands are also relative to the level where they are executed and all -redundant information from the current level is removed from the command -entered. +Commands are relative to the level where they are executed and all redundant +information from the current level is removed from the command entered. .. code-block:: none @@ -245,197 +245,214 @@ entered. These two commands above are essentially the same, just executed from different levels in the hierarchy. -To delete a configuration entry use the ``delete`` command, this also deletes -all sub-levels under the current level you've specified in the ``delete`` -command. Deleting an entry will also result in the element reverting back to -its default value if one exists. +.. cfgcmd:: delete -.. code-block:: none + To delete a configuration entry use the :cfgcmd:`delete` command, this also + deletes all sub-levels under the current level you've specified in the + :cfgcmd:`delete` command. Deleting an entry will also result in the element + reverting back to its default value if one exists. - [edit interfaces ethernet eth0] - vyos@vyos# delete address 192.0.2.100/24 + .. code-block:: none -Any change you do on the configuration, will not take effect until committed -using the ``commit`` command in configuration mode. + [edit interfaces ethernet eth0] + vyos@vyos# delete address 192.0.2.100/24 -.. code-block:: none +.. cfgcmd:: commit - vyos@vyos# commit - [edit] - vyos@vyos# exit - Warning: configuration changes have not been saved. - vyos@vyos:~$ + Any change you do on the configuration, will not take effect until committed + using the :cfgcmd:`commit` command in configuration mode. -In order to preserve configuration changes upon reboot, the configuration must -also be saved once applied. This is done using the ``save`` command in -configuration mode. + .. code-block:: none -.. code-block:: none + vyos@vyos# commit + [edit] + vyos@vyos# exit + Warning: configuration changes have not been saved. + vyos@vyos:~$ - vyos@vyos# save - Saving configuration to '/config/config.boot'... - Done +.. cfgcmd:: save -Configuration mode can not be exited while uncommitted changes exist. To exit -configuration mode without applying changes, the exit discard command can be -used. + In order to preserve configuration changes upon reboot, the configuration + must also be saved once applied. This is done using the :cfgcmd:`save` + command in configuration mode. -.. code-block:: none + .. code-block:: none - vyos@vyos# exit - Cannot exit: configuration modified. - Use 'exit discard' to discard the changes and exit. - [edit] - vyos@vyos# exit discard + vyos@vyos# save + Saving configuration to '/config/config.boot'... + Done -.. code-block:: none + .. code-block:: none - vyos@vyos# save [tab] - Possible completions: - <Enter> Save to system config file - <file> Save to file on local machine - scp://<user>:<passwd>@<host>/<file> Save to file on remote machine - ftp://<user>:<passwd>@<host>/<file> Save to file on remote machine - tftp://<host>/<file> Save to file on remote machine - vyos@vyos# save tftp://192.168.0.100/vyos-test.config.boot - Saving configuration to 'tftp://192.168.0.100/vyos-test.config.boot'... - ######################################################################## 100.0% - Done - -Access from config mode -======================= + vyos@vyos# save [tab] + Possible completions: + <Enter> Save to system config file + <file> Save to file on local machine + scp://<user>:<passwd>@<host>/<file> Save to file on remote machine + ftp://<user>:<passwd>@<host>/<file> Save to file on remote machine + tftp://<host>/<file> Save to file on remote machine + vyos@vyos# save tftp://192.168.0.100/vyos-test.config.boot + Saving configuration to 'tftp://192.168.0.100/vyos-test.config.boot'... + ######################################################################## 100.0% + Done -When inside configuration mode you are not directly able to execute operational -commands. +.. cfgcmd:: exit [discard] -Access to these commands are possible through the use of the ``run [command]`` -command. From this command you will have access to everything accessible from -operational mode. + Configuration mode can not be exited while uncommitted changes exist. To + exit configuration mode without applying changes, the :cfgcmd:`exit discard` + command must be used. -Command completion and syntax help with ``?`` and ``[tab]`` will also work. + All changes in the working config will thus be lost. -.. code-block:: none - - [edit] - vyos@vyos# run show interfaces - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - eth0 0.0.0.0/0 u/u - -Archive -======= + .. code-block:: none -VyOS automatically maintains backups of previous configurations. + vyos@vyos# exit + Cannot exit: configuration modified. + Use 'exit discard' to discard the changes and exit. + [edit] + vyos@vyos# exit discard -Local archive and revisions ---------------------------- +.. _run_opmode_from_config_mode: -Revisions are stored on disk. You can view them, compare them, and rollback to -previous revisions if anything goes wrong. - -To view existing revisions, use ``show system commit`` operational mode command. - -.. code-block:: none +Access opmode from config mode +============================== - vyos@vyos-test-2# run show system commit - 0 2015-03-30 08:53:03 by vyos via cli - 1 2015-03-30 08:52:20 by vyos via cli - 2 2015-03-26 21:26:01 by root via boot-config-loader - 3 2015-03-26 20:43:18 by root via boot-config-loader - 4 2015-03-25 11:06:14 by root via boot-config-loader - 5 2015-03-25 01:04:28 by root via boot-config-loader - 6 2015-03-25 00:16:47 by vyos via cli - 7 2015-03-24 23:43:45 by root via boot-config-loader - -To compare configuration revisions in configuration mode, use the compare -command: - -.. code-block:: none - - vyos@vyos# compare [tab] - Possible completions: - <Enter> Compare working & active configurations - saved Compare working & saved configurations - <N> Compare working with revision N - <N> <M> Compare revision N with M - Revisions: - 0 2013-12-17 20:01:37 root by boot-config-loader - 1 2013-12-13 15:59:31 root by boot-config-loader - 2 2013-12-12 21:56:22 vyos by cli - 3 2013-12-12 21:55:11 vyos by cli - 4 2013-12-12 21:27:54 vyos by cli - 5 2013-12-12 21:23:29 vyos by cli - 6 2013-12-12 21:13:59 root by boot-config-loader - 7 2013-12-12 16:25:19 vyos by cli - 8 2013-12-12 15:44:36 vyos by cli - 9 2013-12-12 15:42:07 root by boot-config-loader - 10 2013-12-12 15:42:06 root by init - -Comparing Revisions -^^^^^^^^^^^^^^^^^^^ - -You can compare revisions with ``compare X Y`` command, where X and Y are -revision numbers. The output will describe how the configuration X is when -compared to Y, indicating with a plus sign (``+``) the additional parts X has -when compared to y, and indicating with a minus sign (``-``) the lacking parts -x misses when compared to y. - -.. code-block:: none - - vyos@vyos-test-2# compare 0 6 - [edit interfaces] - +dummy dum1 { - + address 10.189.0.1/31 - +} - [edit interfaces ethernet eth0] - +vif 99 { - + address 10.199.0.1/31 - +} - -vif 900 { - - address 192.0.2.4/24 - -} - -Rolling Back Changes -^^^^^^^^^^^^^^^^^^^^ +When inside configuration mode you are not directly able to execute operational +commands. -You can rollback configuration using the rollback command. This command will +.. cfgcmd:: run + + Access to these commands are possible through the use of the ``run [command]`` + command. From this command you will have access to everything accessible from + operational mode. + + Command completion and syntax help with ``?`` and ``[tab]`` will also work. + + .. code-block:: none + + [edit] + vyos@vyos# run show interfaces + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 0.0.0.0/0 u/u + +Config Archive +============== + +VyOS automatically maintains backups of every previous configurations which +has been comitted to the system. + +Local Archive +------------- + +Revisions are stored on disk. You can view, compare and rollback them to any +previous revisions if something goes wrong. + +.. opcmd:: show system commit + + View all existing revisions on the local system. + + .. code-block:: none + + vyos@vyos:~$ show system commit + 0 2015-03-30 08:53:03 by vyos via cli + 1 2015-03-30 08:52:20 by vyos via cli + 2 2015-03-26 21:26:01 by root via boot-config-loader + 3 2015-03-26 20:43:18 by root via boot-config-loader + 4 2015-03-25 11:06:14 by root via boot-config-loader + 5 2015-03-25 01:04:28 by root via boot-config-loader + 6 2015-03-25 00:16:47 by vyos via cli + 7 2015-03-24 23:43:45 by root via boot-config-loader + +.. cfgcmd:: compare <saved | N> <M> + + Compare difference in configuration revisions. + + .. code-block:: none + + vyos@vyos# compare [tab] + Possible completions: + <Enter> Compare working & active configurations + saved Compare working & saved configurations + <N> Compare working with revision N + <N> <M> Compare revision N with M + Revisions: + 0 2013-12-17 20:01:37 root by boot-config-loader + 1 2013-12-13 15:59:31 root by boot-config-loader + 2 2013-12-12 21:56:22 vyos by cli + 3 2013-12-12 21:55:11 vyos by cli + 4 2013-12-12 21:27:54 vyos by cli + 5 2013-12-12 21:23:29 vyos by cli + 6 2013-12-12 21:13:59 root by boot-config-loader + 7 2013-12-12 16:25:19 vyos by cli + 8 2013-12-12 15:44:36 vyos by cli + 9 2013-12-12 15:42:07 root by boot-config-loader + 10 2013-12-12 15:42:06 root by init + + Revisions can be compared with :cfgcmd:`compare N M` command, where N and M + are revision numbers. The output will describe how the configuration N is + when compared to YM indicating with a plus sign (``+``) the additional parts + N has when compared to M, and indicating with a minus sign (``-``) the + lacking parts N misses when compared to Y. + + .. code-block:: none + + vyos@vyos# compare 0 6 + [edit interfaces] + +dummy dum1 { + + address 10.189.0.1/31 + +} + [edit interfaces ethernet eth0] + +vif 99 { + + address 10.199.0.1/31 + +} + -vif 900 { + - address 192.0.2.4/24 + -} + +.. cfgcmd:: set system config-management commit-revisions <N> + + You can specify the number of revisions stored on disk. N can be in the + range of 0 - 65535. When the number of revisions exceeds the configured + value, the oldest revision is removed. + +Rollback Changes +---------------- + +You can rollback configuration changes using the rollback command. This will apply the selected revision and trigger a system reboot. -.. code-block:: none +.. cfgcmd:: rollback <N> - vyos@vyos# compare 1 - [edit system] - >host-name vyos-1 - [edit] - vyos@vyos# rollback 1 - Proceed with reboot? [confirm][y] - Broadcast message from root@vyos-1 (pts/0) (Tue Dec 17 21:07:45 2013): - The system is going down for reboot NOW! + Rollback to revision N (currently requires reboot) -Configuring the archive size -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. code-block:: none -You can specify the number of revisions stored on disk with ``set system -config-management commit-revisions X``, where X is a number between 0 and 65535. -When the number of revisions exceeds that number, the oldest revision is -removed. + vyos@vyos# compare 1 + [edit system] + >host-name vyos-1 + [edit] -Remote archive -^^^^^^^^^^^^^^ + vyos@vyos# rollback 1 + Proceed with reboot? [confirm][y] + Broadcast message from root@vyos-1 (pts/0) (Tue Dec 17 21:07:45 2013): + The system is going down for reboot NOW! -VyOS can copy the config to a remote location after each commit. TFTP, FTP, -and SFTP servers are supported. +Remote Archive +-------------- -You can specify the location with: +VyOS can upload the configuration to a remote location after each call to +:cfgcmd:`commit`. TFTP, FTP, and SFTP servers are supported. -* ``set system config-management commit-archive location URL`` +.. cfgcmd set system config-management commit-archive location <URI> -For example, ``set system config-management commit-archive location tftp://10.0.0.1/vyos``. + Specify remote location of commit archive. -You can specify the location with ``set system config-management commit-archive -location URL`` command, e.g. ``set system config-management commit-archive -location tftp://10.0.0.1/vyos``. + * scp://<user>:<passwd>@<host>/<dir> + * sftp://<user>:<passwd>@<host>/<dir> + * ftp://<user>:<passwd>@<host>/<dir> + * tftp://<host>/<dir> Restore Default =============== @@ -447,10 +464,11 @@ default one, you can enter the following command in configuration mode: load /opt/vyatta/etc/config.boot.default -You will be asked if you want to continue. If you accept, -you will have to use `commit` if you want to make the changes active. +You will be asked if you want to continue. If you accept, you will have to use + :cfgcmd:`commit` if you want to make the changes active. -Then you may want to ``save`` in order to delete the saved configuration too. +Then you may want to :cfgcmd:`save` in order to delete the saved configuration +too. .. note:: If you are remotely connected, you will lose your connection. You may want to copy first the config, edit it to ensure connectivity, and load the diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst index bc113750..d158594e 100644 --- a/docs/contributing/build-vyos.rst +++ b/docs/contributing/build-vyos.rst @@ -121,6 +121,108 @@ Good luck! or ``rolling`` image. Make sure to choose the matching container for the version of VyOS that is being built. +.. _build_packages: + +Build packages +-------------- + +VyOS requires a bunch of packages which are VyOS specific and thus can not be +found in any Debian Upstream mirrror. Those packages can be found at the VyOS +GitHub project (https://github.com/vyos) and there is a nice helper script +available to build and list those individual packages. + +`scripts/build-packages` provides an easy interface to automate the process +of building all VyOS related packages that are not part of the upstream Debian +version. Execute it in the root of the `vyos-build` directory to start +compilation. + +.. code-block:: none + + $ scripts/build-packages -h + usage: build-packages [-h] [-c | -k | -f] [-v] [-l] [-b BUILD [BUILD ...]] + [-p] [--blacklist BLACKLIST [BLACKLIST ...]] + + optional arguments: + -h, --help show this help message and exit + -c, --clean Re-clone required Git repositories + -k, --keep Keep modified Git repositories + -f, --fetch Fetch sources only, no build + -v, --verbose Increase logging verbosity for each occurance + -l, --list-packages List all packages to build + -b BUILD [BUILD ...], --build BUILD [BUILD ...] + Whitespace separated list of packages to build + -p, --parallel Build on all CPUs + --blacklist BLACKLIST [BLACKLIST ...] + Do not build/report packages when calling --list + +Git repositoriers are automatically fetched and build on demand. If you want to +work offline you can fetch all source code first with the `-f` option. + +The easiest way to compile is with the above mentioned Docker +container, it includes all dependencies for compiling supported packages. + +.. code-block:: none + + $ docker run --rm -it -v $(pwd):/vyos -w /vyos \ + --sysctl net.ipv6.conf.lo.disable_ipv6=0 \ + vyos-builder scripts/build-packages + +.. note:: `--sysctl net.ipv6.conf.lo.disable_ipv6=0` is required to build the + `vyos-strongswan` package + +.. note:: Prior to executing this script you need to create or build the Docker + container and checkout all packages you want to compile. + +Building single package(s) +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To build a single package use the same script as above but specify packages with +`-b`: + +Executed from the root of `vyos-build` + +.. code-block:: none + + $ docker run --rm -it -v $(pwd):/vyos -w /vyos/packages/PACKAGENAME \ + --sysctl net.ipv6.conf.lo.disable_ipv6=0 \ + vyos-builder scripts/build-packages -b <package> + +.. note:: `--sysctl net.ipv6.conf.lo.disable_ipv6=0` is only needed when + building `vyos-strongswan` and can be ignored on other packages. + +.. note:: `vyos-strongswan` will only compile on a Linux system, running on + macOS or Windows might result in a unittest deadlock (it never exits). + +Building single packages from your own repositories +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can also build packages that are not from the default git repositories, +for example from your own forks of the official vyos repositories. + +First create a directory "packages" at the top level of the vyos-build +repository and clone your package into it (creating a subdirectory with the +package contents). Then checkout the correct branch or commit you want to build +before building the package. + +Example using `git@github.com:myname/vyos-1x.git` repository to build vyos-1x: + +.. code-block:: none + + $ mkdir packages + $ cd packages + $ git clone git@github.com:myname/vyos-1x.git + $ cd .. + $ docker run --rm -it -v $(pwd):/vyos -w /vyos/packages/PACKAGENAME \ + --sysctl net.ipv6.conf.lo.disable_ipv6=0 \ + vyos-builder scripts/build-packages -b vyos-1x + +.. note:: You need to git pull manually after you commit to the remote and + before rebuilding, the local repository won't be updated automatically. + +.. warning:: Any packages in the packages directory will be added to the iso + during build, replacing the upstream ones. Make sure you delete them (both + the source directories and built deb packages) if you want to build an iso + from purely upstream packages. .. _upstream_packages: diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst index 1c257772..fed06e6f 100644 --- a/docs/contributing/development.rst +++ b/docs/contributing/development.rst @@ -486,7 +486,7 @@ GNU Preprocessor ---------------- XML interface definition files use the `xml.in` file extension which was -implemented in T1843_. XML interface definitions tend to have a lot of +implemented in :vytask:`T1843`. XML interface definitions tend to have a lot of duplicated code in areas such as: * VIF (incl. VIF-S/VIF-C) @@ -695,11 +695,11 @@ http://dev.packages.vyos.net/repositories/. .. _VyConf: https://github.com/vyos/vyconf/tree/master/data/schemata .. _vyos-1x: https://github.com/vyos/vyos-1x/tree/current/schema .. _Jinja2: https://jinja.palletsprojects.com/ -.. _Phabricator: https://phabricator.vyos.net/ .. _Jenkins: https://jenkins.io/ .. _Dockerhub: https://hub.docker.com/u/vyos/ -.. _T1843: https://phabricator.vyos.net/T1843 .. _`IPv4, IPv6 and DHCP(v6)`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/address-ipv4-ipv6-dhcp.xml.i .. _`IPv4, IPv6`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/address-ipv4-ipv6.xml.i .. _`VLAN (VIF)`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/vif.xml.i .. _`MAC address`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/interface-mac.xml.i + +.. include:: ../common-references.rst diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst index 48cc063b..2d9f14d1 100644 --- a/docs/contributing/documentation.rst +++ b/docs/contributing/documentation.rst @@ -5,12 +5,12 @@ Documentation As most software projects we also have a lack in documentation. We encourage every VyOS user to help us improve our documentation. This will not only be -benefical four you (when reading something up) but also for the whole world. +beneficial for you (when reading something up) but also for the whole world. -If you are willing to contribute to our documentation this is the definate -guid how to do so. +If you are willing to contribute to our documentation this is the definite +guide how to do so. -.. note:: In contrast to submitting code patches there is no requirement that +.. note:: In contrast to submitting code patches, there is no requirement that you open up a Phabricator_ task prior to submitting a Pull-Request to the documentation. @@ -147,29 +147,60 @@ system numbers for the documentation: Please don't use other public address space. - Custom Sphinx-doc Markup ^^^^^^^^^^^^^^^^^^^^^^^^ -When documenting CLI commands use the ``.. cfgcmd::`` directive for all -configuration mode commands. When documenting operational level command use -the ``.. opcmd::`` directive. An explanation of the described command should -be added below this statement. +When writing the documentation custom commands have been developed. Please +make yourself comfortable with those commands as this eases the way we +render the documentation. -**Example** +cfgcmd +"""""" -.. code-block:: none +When documenting CLI commands use the ``.. cfgcmd::`` directive for all +configuration mode commands. An explanation of the described command should be +added below this statement. - .. opcmd:: show protocols static arp +With those custom commands it will be possible to render them in a more +descriptive way in the resulting HTML/PDF manual. - Display all known ARP table entries spanning accross all interfaces +.. code-block:: none .. cfgcmd:: set protocols static arp 192.0.2.100 hwaddr 00:53:27:de:23:aa This will configure a static ARP entry always resolving `192.0.2.100` to `00:53:27:de:23:aa`. +opcmd +""""" + +When documenting operational level command use the ``.. opcmd::`` directive. +An explanation of the described command should be added below this statement. + +With those custom commands it will be possible to render them in a more +descriptive way in the resulting HTML/PDF manual. + +.. code-block:: none + + .. opcmd:: show protocols static arp + + Display all known ARP table entries spanning across all interfaces + +vytask +"""""" + +When referencing to VyOS Phabricator Tasks, there is a custom Spinx Markup +command called ``vytask`` which automatically renders to a proper Phabricator +URL. This is heavily used in the :ref:`release-notes` section. + +.. code-block:: none + + * :vytask:`T1605` Fixed regression in L2TP/IPsec server + * :vytask:`T1613` Netflow/sFlow captures IPv6 traffic correctly + + .. _Sphinx-doc: https://www.sphinx-doc.org .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html -.. _Phabricator: https://phabricator.vyos.net .. _README.md: https://github.com/vyos/vyos-documentation/blob/master/README.md + +.. include:: ../common-references.rst diff --git a/docs/contributing/issues-features.rst b/docs/contributing/issues-features.rst index 3a1738d7..1c6563b9 100644 --- a/docs/contributing/issues-features.rst +++ b/docs/contributing/issues-features.rst @@ -1,10 +1,14 @@ .. _issues_features: +####################### Issues/Feature requests -======================= +####################### + +.. _bug_report: Bug Report/Issue ----------------- +================ + Issues or bugs are found in any software project. VyOS is not an exception. All issues should be reported to the developers. This lets the developers know @@ -12,7 +16,7 @@ what is not working properly. Without this sort of feedback every developer will believe that everything is working correctly. I have found a bug, what should I do? -************************************* +------------------------------------- When you believe you have found a bug, it is always a good idea to verify the issue prior to opening a bug request. @@ -22,7 +26,7 @@ issue prior to opening a bug request. * Get community support via Slack_ or our Forum_ Ensure the problem is reproducible -********************************** +---------------------------------- When you are able to verify that it is actually a bug, spend some time to document how to reproduce the issue. This documentation can be invaluable. @@ -38,7 +42,7 @@ information can be very useful. * What commands did you use? Use e.g. ``run show configuration commands`` Include output -************** +-------------- The output you get when you find a bug can provide lots of information. If you get an error message on the screen, copy it exactly. Having the exact message @@ -47,18 +51,21 @@ messages that also are from the time of the issue, include those. They may also contain information that is helpful for the development team. Report a Bug -************ +------------ -Create an account on VyOS Phabricator_. Phabricator_ is located at -https://phabricator.vyos.net. To create a bug-report use the quick link in the -left side under the specific project. +In order to open up a bug-report/feature request you need to create yourself +an account on VyOS Phabricator_. On the left side of the specific project (VyOS +1.2 or VyOS 1.3) you will find quick-links for opening a bug-report/feature +request. * Provide as much information as you can * Which version of VyOS are you using? ``run show version`` * How can we reproduce this Bug? +.. _feature_request: + Feature Request ---------------- +=============== You have an idea of how to make VyOS better or you are in need of a specific feature which all users of VyOS would benefit from? To send a feature request @@ -69,4 +76,5 @@ the left side under the specific project. .. _documentation: https://docs.vyos.io .. _Slack: https://slack.vyos.io .. _Forum: https://forum.vyos.io -.. _Phabricator: https://phabricator.vyos.net
\ No newline at end of file + +.. include:: ../common-references.rst
\ No newline at end of file diff --git a/docs/image-mgmt.rst b/docs/image-mgmt.rst index 245a31b7..3b8f04c3 100644 --- a/docs/image-mgmt.rst +++ b/docs/image-mgmt.rst @@ -48,9 +48,11 @@ configured to be the default (:opcmd:`set system image default-boot`). system image` -.. opcmd:: delete system image +.. opcmd:: delete system image [image-name] - Delete no longer needed images from the system. + Delete no longer needed images from the system. You can specify an optional + image name to delete, the image name can be retrived via a list of available + images can be shown using the :opcmd:`show system image`. .. code-block:: none diff --git a/docs/index.rst b/docs/index.rst index 94b0189a..f6b3d595 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -23,7 +23,7 @@ VyOS User Guide :maxdepth: 2 configuration-overview - interfaces/index + interfaces/basic-index system/basic-index image-mgmt @@ -33,6 +33,7 @@ VyOS User Guide :name: advanced :maxdepth: 2 + interfaces/advanced-index services/index system/index firewall @@ -51,7 +52,7 @@ VyOS User Guide :name: appendix :maxdepth: 2 - appendix/releasenotes + appendix/release-notes appendix/examples/index appendix/cmd-index appendix/commandtree/index diff --git a/docs/install.rst b/docs/install.rst index 0a36e831..0f6f0f23 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -7,14 +7,14 @@ Installation Requirements ============ -The recommended system requirements are 512 MiB RAM and 2 GiB storage. Depending -on your use you might need additional RAM and CPU resources e.g. when having -multiple BGP full tables in your system. +The recommended system requirements are 512 MiB RAM and 2 GiB storage. +Depending on your use you might need additional RAM and CPU resources e.g. +when having multiple BGP full tables in your system. -Getting the software -==================== +Download +======== -Registered subscribers +Registered Subscribers ---------------------- Registered subscribers can log into https://support.vyos.io/ to have access to @@ -28,23 +28,29 @@ ISOs. Building from source ---------------------- -Non-subscribers can get the LTS release by building it from source. Instruction -can be found here: :ref:`build` and the source repository is available -for everyone at https://github.com/vyos/vyos-build. +Non-subscribers can always get the LTS release by building it from source. +Instruction can be found in the :ref:`build` section of this manual. VyOS +source code repository is available for everyone at +https://github.com/vyos/vyos-build. Rolling Release --------------- -Non-subscribers and subscribers can download bleeding-edge VyOS rolling images -from: https://downloads.vyos.io/ +Everyone can download bleeding-edge VyOS rolling images from: +https://downloads.vyos.io/ -The following link will always fetch the most updated AMD64 image of the -current branch: +.. note:: Rolling releases contain all the latest enhancements and fixes. This + means that there will be new bugs of course. If you think you hit a bug + please follow the guide at :ref:`bug_report`. To improve VyOS we depend on + your feedback! + +The following link will always fetch the most recent VyOS build for AMD64 +systems from the current branch: https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso -Software verification -===================== +Download Verification +--------------------- This subsection and the following one applies to downloaded LTS images, for other versions please jump to :ref:`Install`. @@ -164,12 +170,12 @@ Finally, verify the authencity of the downloaded image: .. _Install: -Install -======= +Installation +============ -VyOS ISO is a Live CD and will boot to a functional VyOS image. +VyOS ISO is a live CD and will boot into a full functional VyOS system. -To login to the system, use the default username and password will be: ``vyos`` +.. hint:: The default username and password for the live system is ``vyos``. .. code-block:: none @@ -251,34 +257,34 @@ the provided default credentials. Setting up grub: OK Done! -After the installation is complete, remove the Live CD and reboot the system: +After the installation is complete, remove the live CD and reboot the system: .. code-block:: none vyos@vyos:~$ reboot Proceed with reboot? (Yes/No) [No] Yes -.. _PXE Install: - -PXE Install ------------ +PXE Boot +-------- VyOS can also be installed through PXE. This is a more complex installation method which allows deploying VyOS through the network. -Requirements -^^^^^^^^^^^^ +**Requirements** + +* :ref:`dhcp-server` +* :ref:`tftp-server` +* Webserver (HTTP) - optional, but we will use it to speed up intallation +* VyOS ISO image to be installed (do not use images prior to VyOS 1.2.3) +* ``pxelinux.0``, ``ldlinux.c32`` from SYSLINUX_ + (https://mirrors.edge.kernel.org/pub/linux/utils/boot/syslinux/) -* **Clients** (where VyOS is to be installed) **with a PXE-enabled NIC** -* A **DHCP server** -* A **TFTP server** -* A **HTTP server** (optional, but we will use it to speed up intallation) -* The **VyOS ISO** image to be installed (do not use images prior to VyOS 1.2.3) -* The ``pxelinux.0`` and ``ldlinux.c32`` files from the Syslinux distribution - https://mirrors.edge.kernel.org/pub/linux/utils/boot/syslinux/ -Step 1: DHCP -^^^^^^^^^^^^ +Configuration +^^^^^^^^^^^^^ + +DHCP +"""" Configure DHCP server to provide the client with: @@ -305,8 +311,8 @@ In this example we configured an existent VyOS as the DHCP server: .. _install_from_tftp: -Step 2: TFTP -^^^^^^^^^^^^ +TFTP +"""" Configure a TFTP server so that it serves the following: @@ -365,8 +371,8 @@ Example of simple (no menu) configuration file: APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence \ noautologin nonetworking fetch=http://address:8000/filesystem.squashfs -Step 3: HTTP -^^^^^^^^^^^^ +HTTP +"""" As you read in the configuration file, we are sending ``filesystem.squashfs`` through HTTP. As that is a heavy file, we choose HTTP to speed up the transfer @@ -375,8 +381,8 @@ over TFTP. Run a web server - you can use a simple one like file. The file can be found inside the ``/live`` directory of the extracted contents of the ISO file. -Edit the configuration file at the :ref:`install_from_tftp` so that it shows the -correct URL at ``fetch=http://address/filesystem.squashfs``. Then restart +Edit the configuration file at the :ref:`install_from_tftp` so that it shows +the correct URL at ``fetch=http://address/filesystem.squashfs``. Then restart the TFTP service. If you are using VyOS as your TFTP Server, you can restart the service with ``sudo service tftpd-hpa restart``. @@ -385,8 +391,8 @@ the service with ``sudo service tftpd-hpa restart``. .. _`Python's SimpleHTTPServer`: https://docs.python.org/2/library/simplehttpserver.html -Step 4: Boot the clients -^^^^^^^^^^^^^^^^^^^^^^^^ +Client Boot +""""""""""" Turn on your PXE-enabled client or clients. They will automatically get an IP address from the DHCP server and start booting into VyOS live from the files @@ -394,3 +400,5 @@ automatically taken from the TFTP and HTTP servers. Once finished you will be able to proceed with the ``install image`` command as in a regular VyOS installation. + +.. _SYSLINUX: http://www.syslinux.org/ diff --git a/docs/interfaces/addresses.rst b/docs/interfaces/addresses.rst deleted file mode 100644 index 709490c8..00000000 --- a/docs/interfaces/addresses.rst +++ /dev/null @@ -1,175 +0,0 @@ -.. _interfaces-addresses: - -Addresses ---------- - -Each interface can be configured with a description and address. Interface -addresses might be: - -* Static IPv4 ``address 172.16.51.129/24`` -* Static IPv6 ``address 2001:db8:1::ffff/64`` -* DHCP IPv4 ``address dhcp`` -* DHCP IPv6 ``address dhcpv6`` - -.. cfgcmd:: set interfaces ethernet eth0 description 'OUTSIDE' - - An interface description is assigned using the following command: - -IPv4 -^^^^ - -Static Address -************** - -This method is supported on all interfaces, apart from OpenVPN that uses -different syntax and wireless modems that are always autoconfigured through -PPP. - -The command is ``set interfaces $type $name address $address``. Examples: - -.. code-block:: none - - set interfaces ethernet eth0 address 192.0.2.1/24 - set interfaces tunnel tun0 address 10.0.0.1/30 - set interfaces bridge br0 address 203.0.113.45/26 - set interfaces ethernet eth0 vif 30 address 198.51.100.254/24 - -DHCP -**** - -This method is supported on all physical interfaces, and those that are -directly connected to a physical interface (Ethernet, VLAN, Bridge, Bond, -Pseudo-ethernet, Wireless). - -The command is ``set interfaces $type $name address dhcp``. Examples: - -.. code-block:: none - - set interfaces ethernet eth0 vif 90 address dhcp - set interfaces bridge br0 address dhcp - -IPv6 -^^^^ - -Static Address -************** - -This method is supported on all interfaces, apart from OpenVPN that uses -different syntax and wireless modems that are always autoconfigured through -PPP. Static IPv6 addresses are supported on all interfaces -except :ref:`tunnel-interface`. - -The command is ``set interfaces $type $name address $address``. Examples: - -.. code-block:: none - - set interfaces ethernet eth0 address 2001:db8:100::ffff/64 - set interfaces tunnel tun0 address 2001:db8::1/64 - set interfaces bridge br0 address 2001:db8:200::1/64 - set interfaces ethernet eth0 vif 30 address 2001:db8:3::ffff/64 - -DHCP -**** - -This method is supported on all physical interfaces, and those that are -directly connected to a physical interface (Ethernet, VLAN, Bridge, Bond, -Pseudo-ethernet, Wireless). - -The command is `set interfaces $type $name address dhcpv6`. Examples: - -.. code-block:: none - - set interfaces bonding bond1 address dhcpv6 - set interfaces bridge br0 vif 56 address dhcpv6 - -Autoconfiguration (SLAAC) -************************* - -SLAAC is specified in :rfc:`4862`. This method is supported on all physical -interfaces, and those that are directly connected to a physical interface -(Ethernet, VLAN, Bridge, Bond, Pseudo-ethernet, Wireless). - -The command is ``set interfaces $type $name ipv6 address autoconf``. Examples: - -.. code-block:: none - - set interfaces ethernet eth0 vif 90 ipv6 address autoconf - set interfaces bridge br0 ipv6 address autoconf - -.. note:: This method automatically disables IPv6 traffic forwarding on the - interface in question. - -EUI-64 -****** - -EUI-64 (64-Bit Extended Unique Identifier) as specified in :rfc:`4291`. IPv6 -addresses in /64 networks can be automatically generated from the prefix and -MAC address, if you specify the prefix. - -The command is `set interfaces $type $name ipv6 address eui64 $prefix`. -Examples: - -.. code-block:: none - - set interfaces bridge br0 ipv6 address eui64 2001:db8:beef::/64 - set interfaces pseudo-ethernet peth0 ipv6 address eui64 2001:db8:aa::/64 - - -Router Advertisements -********************* - -Router advertisements are described in :rfc:`4861#section-4.6.2`. They are part -of what is known as SLAAC (Stateless Address Autoconfiguration). - -To enable or disable, use: - -.. code-block:: none - - set interfaces <interface> ipv6 router-advert send-advert <true|false> - - -To set the options described in "Router Advertisement Message Format": - -.. code-block:: none - - vyos@vyos# set interfaces <interface> ipv6 router-advert - Possible completions: - cur-hop-limit Value to be placed in the "Current Hop Limit" field in RAs - default-lifetime Value to be placed in "Router Lifetime" field in RAs - default-preference Default router preference - link-mtu Value of link MTU to place in RAs - managed-flag Value for "managed address configuration" flag in RAs - max-interval Maximum interval between unsolicited multicast RAs - min-interval Minimum interval between unsolicited multicast RAs - + name-server IPv6 address of a Recursive DNS Server - other-config-flag Value to be placed in the "other configuration" flag in RAs - +> prefix IPv6 prefix to be advertised in Router Advertisements (RAs) - reachable-time Value to be placed in "Reachable Time" field in RAs - retrans-timer Value to place in "Retrans Timer" field in RAs. - send-advert Enable/disable sending RAs - - -Prefix Information -~~~~~~~~~~~~~~~~~~ - -Prefix information is described in :rfc:`4861#section-4.6.2`. - -.. code-block:: none - - vyos@vyos# set interfaces <interface> ipv6 router-advert prefix <h:h:h:h:h:h:h:h/x> - Possible completions: - autonomous-flag Whether prefix can be used for address auto-configuration - on-link-flag Flag that prefix can be used for on-link determination - preferred-lifetime Time in seconds that the prefix will remain preferred - valid-lifetime Time in seconds that the prefix will remain valid - -Receiving Router Advertisements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To receive and accept RAs on an interface, you need to enable it with the -following configuration command - -.. code-block:: none - - vyos@vyos# set system sysctl custom net.ipv6.conf.<interface>.accept_ra value 2 - diff --git a/docs/interfaces/advanced-index.rst b/docs/interfaces/advanced-index.rst new file mode 100644 index 00000000..00c1c73e --- /dev/null +++ b/docs/interfaces/advanced-index.rst @@ -0,0 +1,19 @@ +.. _network-interfaces: + +################## +Network Interfaces +################## + +.. toctree:: + :maxdepth: 1 + + dummy + bridge + bond + l2tpv3 + wireless + tunnel + vlan + qinq + vxlan + geneve diff --git a/docs/interfaces/basic-index.rst b/docs/interfaces/basic-index.rst new file mode 100644 index 00000000..c652c7bb --- /dev/null +++ b/docs/interfaces/basic-index.rst @@ -0,0 +1,12 @@ +.. _basic_network-interfaces: + +################ +Basic Interfaces +################ + +.. toctree:: + :maxdepth: 1 + + ethernet + loopback + pppoe diff --git a/docs/interfaces/bond.rst b/docs/interfaces/bond.rst index 880c7580..c0fc0ca6 100644 --- a/docs/interfaces/bond.rst +++ b/docs/interfaces/bond.rst @@ -1,72 +1,362 @@ .. _bond-interface: +#### Bond ----- +#### -You can combine (aggregate) 2 or more physical interfaces into a single -logical one. It's called bonding, or LAG, or ether-channel, or port-channel. +The bonding interface provides a method for aggregating multiple network +interfaces into a single logical "bonded" interface, or LAG, or ether-channel, +or port-channel. The behavior of the bonded interfaces depends upon the mode; +generally speaking, modes provide either hot standby or load balancing services. +Additionally, link integrity monitoring may be performed. -Create interface bondX, where X is just a number: +Configuration +############# -.. code-block:: none +Address +------- - set interfaces bonding bond0 description 'my-sw1 int 23 and 24' +.. cfgcmd:: set interfaces bonding <interface> address <address | dhcp | dhcpv6> -You are able to choose a hash policy: + Configure interface `<interface>` with one or more interface addresses. -.. code-block:: none + * **address** can be specified multiple times as IPv4 and/or IPv6 address, + e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + * **dhcp** interface address is received by DHCP from a DHCP server on this + segment. + * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 server on + this segment. + + Example: + + .. code-block:: none + + set interfaces bonding bond0 address 192.0.2.1/24 + set interfaces bonding bond0 address 192.0.2.2/24 + set interfaces bonding bond0 address 2001:db8::ffff/64 + set interfaces bonding bond0 address 2001:db8:100::ffff/64 + + +.. cfgcmd:: set interfaces bonding <interface> ipv6 address autoconf + + .. include:: common-ipv6-addr-autoconf.txt + +.. cfgcmd:: set interfaces bonding <interface> ipv6 address eui64 <prefix> + + :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in + :rfc:`4291` allows a host to assign iteslf a unique 64-Bit IPv6 address. + + .. code-block:: none + + set interfaces bonding bond0 ipv6 address eui64 2001:db8:beef::/64 + + +Link Administration +------------------- + +.. cfgcmd:: set interfaces bonding <interface> description <description> + + Assign given `<description>` to interface. Description will also be passed + to SNMP monitoring systems. + + +.. cfgcmd:: set interfaces bonding <interface> disable + + Disable given `<interface>`. It will be placed in administratively down + (``A/D``) state. + +.. cfgcmd:: set interfaces bonding <interface> mac <mac-address> + + Configure user defined :abbr:`MAC (Media Access Control)` address on given + `<interface>`. + +.. cfgcmd:: set interfaces bonding <interface> mode <mode> + + Specifies one of the bonding policies. The default is 802.3ad. Possible + values are: + + * **802.3ad** - IEEE 802.3ad Dynamic link aggregation. Creates aggregation + groups that share the same speed and duplex settings. Utilizes all slaves + in the active aggregator according to the 802.3ad specification. + + Slave selection for outgoing traffic is done according to the transmit + hash policy, which may be changed from the default simple XOR policy via + the :cfgcmd:`hash-policy` option, documented below. + + .. note:: Not all transmit policies may be 802.3ad compliant, particularly + in regards to the packet mis-ordering requirements of section 43.2.4 + of the 802.3ad standard. + + * **active-backup** - Active-backup policy: Only one slave in the bond is + active. A different slave becomes active if, and only if, the active slave + fails. The bond's MAC address is externally visible on only one port + (network adapter) to avoid confusing the switch. + + When a failover occurs in active-backup mode, bonding will issue one or + more gratuitous ARPs on the newly active slave. One gratuitous ARP is + issued for the bonding master interface and each VLAN interfaces + configured above it, provided that the interface has at least one IP + address configured. Gratuitous ARPs issued for VLAN interfaces are tagged + with the appropriate VLAN id. + + This mode provides fault tolerance. The :cfgcmd:`primary` option, + documented below, affects the behavior of this mode. + + * **broadcast** - Broadcast policy: transmits everything on all slave + interfaces. + + This mode provides fault tolerance. + + * **round-robin** - Round-robin policy: Transmit packets in sequential + order from the first available slave through the last. + + This mode provides load balancing and fault tolerance. + + * **transmit-load-balance** - Adaptive transmit load balancing: channel + bonding that does not require any special switch support. + + Incoming traffic is received by the current slave. If the receiving slave + fails, another slave takes over the MAC address of the failed receiving + slave. + + * **adaptive-load-balance** - Adaptive load balancing: includes + transmit-load-balance plus receive load balancing for IPV4 traffic, and + does not require any special switch support. The receive load balancing + is achieved by ARP negotiation. The bonding driver intercepts the ARP + Replies sent by the local system on their way out and overwrites the + source hardware address with the unique hardware address of one of the + slaves in the bond such that different peers use different hardware + addresses for the server. + + Receive traffic from connections created by the server is also balanced. + When the local system sends an ARP Request the bonding driver copies and + saves the peer's IP information from the ARP packet. When the ARP Reply + arrives from the peer, its hardware address is retrieved and the bonding + driver initiates an ARP reply to this peer assigning it to one of the + slaves in the bond. A problematic outcome of using ARP negotiation for + balancing is that each time that an ARP request is broadcast it uses the + hardware address of the bond. Hence, peers learn the hardware address + of the bond and the balancing of receive traffic collapses to the current + slave. This is handled by sending updates (ARP Replies) to all the peers + with their individually assigned hardware address such that the traffic + is redistributed. Receive traffic is also redistributed when a new slave + is added to the bond and when an inactive slave is re-activated. The + receive load is distributed sequentially (round robin) among the group + of highest speed slaves in the bond. + + When a link is reconnected or a new slave joins the bond the receive + traffic is redistributed among all active slaves in the bond by initiating + ARP Replies with the selected MAC address to each of the clients. The + updelay parameter (detailed below) must be set to a value equal or greater + than the switch's forwarding delay so that the ARP Replies sent to the + peers will not be blocked by the switch. + + * **xor-hash** - XOR policy: Transmit based on the selected transmit + hash policy. The default policy is a simple [(source MAC address XOR'd + with destination MAC address XOR packet type ID) modulo slave count]. + Alternate transmit policies may be selected via the :cfgcmd:`hash-policy` + option, described below. + + This mode provides load balancing and fault tolerance. + +.. cfgcmd:: set interfaces bonding <interface> hash-policy <policy> + + * **layer2** - Uses XOR of hardware MAC addresses and packet type ID field + to generate the hash. The formula is + + .. code-block:: none + + hash = source MAC XOR destination MAC XOR packet type ID + slave number = hash modulo slave count - vyos@vyos# set interfaces bonding bond0 hash-policy - Possible completions: - layer2 use MAC addresses to generate the hash (802.3ad) - layer2+3 combine MAC address and IP address to make hash - layer3+4 combine IP address and port to make hash + This algorithm will place all traffic to a particular network peer on + the same slave. -For example: + This algorithm is 802.3ad compliant. + + * **layer2+3** - This policy uses a combination of layer2 and layer3 + protocol information to generate the hash. Uses XOR of hardware MAC + addresses and IP addresses to generate the hash. The formula is: + + .. code-block:: none + + hash = source MAC XOR destination MAC XOR packet type ID + hash = hash XOR source IP XOR destination IP + hash = hash XOR (hash RSHIFT 16) + hash = hash XOR (hash RSHIFT 8) + + And then hash is reduced modulo slave count. + + If the protocol is IPv6 then the source and destination addresses are + first hashed using ipv6_addr_hash. + + This algorithm will place all traffic to a particular network peer on the + same slave. For non-IP traffic, the formula is the same as for the layer2 + transmit hash policy. + + This policy is intended to provide a more balanced distribution of traffic + than layer2 alone, especially in environments where a layer3 gateway + device is required to reach most destinations. + + This algorithm is 802.3ad compliant. + + * **layer3+4** - This policy uses upper layer protocol information, when + available, to generate the hash. This allows for traffic to a particular + network peer to span multiple slaves, although a single connection will + not span multiple slaves. + + The formula for unfragmented TCP and UDP packets is + + .. code-block:: none + + hash = source port, destination port (as in the header) + hash = hash XOR source IP XOR destination IP + hash = hash XOR (hash RSHIFT 16) + hash = hash XOR (hash RSHIFT 8) + + And then hash is reduced modulo slave count. + + If the protocol is IPv6 then the source and destination addresses are + first hashed using ipv6_addr_hash. + + For fragmented TCP or UDP packets and all other IPv4 and IPv6 protocol + traffic, the source and destination port information is omitted. For + non-IP traffic, the formula is the same as for the layer2 transmit hash + policy. + + This algorithm is not fully 802.3ad compliant. A single TCP or UDP + conversation containing both fragmented and unfragmented packets will see + packets striped across two interfaces. This may result in out of order + delivery. Most traffic types will not meet this criteria, as TCP rarely + fragments traffic, and most UDP traffic is not involved in extended + conversations. Other implementations of 802.3ad may or may not tolerate + this noncompliance. + +.. cfgcmd:: set interfaces bonding <interface> primary <interface> + + An `<interface>` specifying which slave is the primary device. The specified + device will always be the active slave while it is available. Only when the + primary is off-line will alternate devices be used. This is useful when one + slave is preferred over another, e.g., when one slave has higher throughput + than another. + + The primary option is only valid for active-backup, transmit-load-balance, + and adaptive-load-balance mode. + +.. cfgcmd:: set interfaces bonding <interface> arp-monitor interval <time> + + Specifies the ARP link monitoring `<time>` in seconds. + + The ARP monitor works by periodically checking the slave devices to determine + whether they have sent or received traffic recently (the precise criteria + depends upon the bonding mode, and the state of the slave). Regular traffic + is generated via ARP probes issued for the addresses specified by the + :cfgcmd:`arp-monitor target` option. + + If ARP monitoring is used in an etherchannel compatible mode (modes + round-robin and xor-hash), the switch should be configured in a mode that + evenly distributes packets across all links. If the switch is configured to + distribute the packets in an XOR fashion, all replies from the ARP targets + will be received on the same link which could cause the other team members + to fail. + + A value of 0 disables ARP monitoring. The default value is 0. + +.. cfgcmd:: set interfaces bonding <interface> arp-monitor target <address> + + Specifies the IP addresses to use as ARP monitoring peers when + :cfgcmd:`arp-monitor interval` option is > 0. These are the targets of the + ARP request sent to determine the health of the link to the targets. + + Multiple target IP addresses can be specified. At least one IP address must + be given for ARP monitoring to function. + + The maximum number of targets that can be specified is 16. The default value + is no IP addresses. + +Member Interfaces +----------------- + +.. cfgcmd:: set interfaces bonding <interface> member interface <member> + + Enslave `<member>` interface to bond `<interface>`. + +Example +------- + +The following configuration on VyOS applies to all following 3rd party vendors. +It creates a bond with two links and VLAN 10, 100 on the bonded interfaces with +a per VIF IPv4 address. .. code-block:: none + # Create bonding interface bond0 with 802.3ad LACP set interfaces bonding bond0 hash-policy 'layer2' + set interfaces bonding bond0 mode '802.3ad' -You may want to set IEEE 802.3ad Dynamic link aggregation (802.3ad) AKA LACP -(don't forget to setup it on the other end of these links): + # Add the required vlans and IPv4 addresses on them + set interfaces bonding bond0 vif 10 address 192.168.0.1/24 + set interfaces bonding bond0 vif 100 address 10.10.10.1/24 -.. code-block:: none + # Add the member interfaces to the bonding interface + set interfaces bonding bond0 member interface eth1 + set interfaces bonding bond0 member interface eth2 + +Cisco +^^^^^ - set interfaces bonding bond0 mode '802.3ad' +An example configuration for a Cisco PortChannel to VyOS would be nice -or some other modes: +Juniper EX Switch +^^^^^^^^^^^^^^^^^ + +For a headstart you can use the below example on how to build a bond with two +interfaces from VyOS to a Juniper EX Switch system. .. code-block:: none - vyos@vyos# set interfaces bonding bond0 mode - Possible completions: - 802.3ad IEEE 802.3ad Dynamic link aggregation (Default) - active-backup - Fault tolerant: only one slave in the bond is active - broadcast Fault tolerant: transmits everything on all slave interfaces - round-robin Load balance: transmit packets in sequential order - transmit-load-balance - Load balance: adapts based on transmit load and speed - adaptive-load-balance - Load balance: adapts based on transmit and receive plus ARP - xor-hash Load balance: distribute based on MAC address - -Now bond some physical interfaces into bond0: + # Create aggregated ethernet device with 802.3ad LACP and port speeds of 10gbit/s + set interfaces ae0 aggregated-ether-options link-speed 10g + set interfaces ae0 aggregated-ether-options lacp active + + # Create layer 2 on the aggregated ethernet device with trunking for our vlans + set interfaces ae0 unit 0 family ethernet-switching port-mode trunk + + # Add the required vlans to the device + set interfaces ae0 unit 0 family ethernet-switching vlan members 10 + set interfaces ae0 unit 0 family ethernet-switching vlan members 100 + + # Add the two interfaces to the aggregated ethernet device, in this setup both + # ports are on the same switch (switch 0, module 1, port 0 and 1) + set interfaces xe-0/1/0 ether-options 802.3ad ae0 + set interfaces xe-0/1/1 ether-options 802.3ad ae0 + + # But this can also be done with multiple switches in a stack, a virtual + # chassis on Juniper (switch 0 and switch 1, module 1, port 0 on both switches) + set interfaces xe-0/1/0 ether-options 802.3ad ae0 + set interfaces xe-1/1/0 ether-options 802.3ad ae0 + +Aruba/HP +^^^^^^^^ + +For a headstart you can use the below example on how to build a bond,port-channel +with two interfaces from VyOS to a Aruba/HP 2510G switch. .. code-block:: none - set interfaces bonding bond0 member interface eth0 - set interfaces bonding bond0 member interface eth1 + # Create trunk with 2 member interfaces (interface 1 and 2) and LACP + trunk 1-2 Trk1 LACP -After a commit you may treat bond0 as almost a physical interface (you can't -change its` duplex, for example) and assign IPs or VIFs on it. + # Add the required vlans to the trunk + vlan 10 tagged Trk1 + vlan 100 tagged Trk1 -You may check the result: +Operation +######### .. code-block:: none - vyos@vyos# run sh interfaces bonding + vyos@vyos:~$ show interfaces bonding Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down Interface IP Address S/L Description --------- ---------- --- ----------- diff --git a/docs/interfaces/bridge.rst b/docs/interfaces/bridge.rst index a7bbbca6..d51f4ec2 100644 --- a/docs/interfaces/bridge.rst +++ b/docs/interfaces/bridge.rst @@ -1,112 +1,254 @@ .. _bridge-interface: +###### Bridge ------- +###### -Interfaces in VyOS can be bridged together to provide software switching of -Layer-2 traffic. +A Bridge is a way to connect two Ethernet segments together in a protocol +independent way. Packets are forwarded based on Ethernet address, rather than +IP address (like a router). Since forwarding is done at Layer 2, all protocols +can go transparently through a bridge. The Linux bridge code implements a +subset of the ANSI/IEEE 802.1d standard. -A bridge is created when a bridge interface is defined. In the example below -we create a bridge named br100 with eth1 and eth2 as the bridge member ports. +Configuration +############# -.. code-block:: none +Address +------- - set interfaces bridge 'br100' - set interfaces bridge br100 member interface eth1 - set interfaces bridge br100 member interface eth2 +.. cfgcmd:: set interfaces bridge <interface> address <address | dhcp | dhcpv6> -Each bridge member can be assiged a port cost and priority using the following -commands: + Configure interface `<interface>` with one or more interface addresses. -.. code-block:: none + * **address** can be specified multiple times as IPv4 and/or IPv6 address, + e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + * **dhcp** interface address is received by DHCP from a DHCP server on this + segment. + * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 server on + this segment. - set interfaces bridge br100 member interface eth1 cost 10 - set interfaces bridge br100 member interface eth1 priority 1024 + Example: -Interfaces assigned to a bridge do not have address configuration. An IP -address can be assigned to the bridge interface itself, however, like any -normal interface. + .. code-block:: none -.. code-block:: none + set interfaces bridge br0 address 192.0.2.1/24 + set interfaces bridge br0 address 192.0.2.2/24 + set interfaces bridge br0 address 2001:db8::ffff/64 + set interfaces bridge br0 address 2001:db8:100::ffff/64 - set interfaces bridge br100 address '192.168.100.1/24' - set interfaces bridge br100 address '2001:db8:100::1/64' -Example Result: +.. cfgcmd:: set interfaces bridge <interface> ipv6 address autoconf -.. code-block:: none + .. include:: common-ipv6-addr-autoconf.txt - bridge br100 { - address 192.168.100.1/24 - address 2001:db8:100::1/64 - member { - interface eth1 { - cost 10 - priority 1024 - } - interface eth2 { - } - } +.. cfgcmd:: set interfaces bridge <interface> ipv6 address eui64 <prefix> - } - [...] + :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in + :rfc:`4291` allows a host to assign iteslf a unique 64-Bit IPv6 address. -In addition to normal IP interface configuration, bridge interfaces support -Spanning-Tree Protocol. STP is disabled by default. + .. code-block:: none -.. note:: Please use caution when introducing spanning-tree protocol on a - network as it may result in topology changes. + set interfaces bridge br0 ipv6 address eui64 2001:db8:beef::/64 -To enable spanning-tree use the `set interfaces bridge <name> stp` command: -.. code-block:: none +.. cfgcmd:: set interfaces bridge <interface> aging <time> - set interfaces bridge br100 stp + MAC address aging `<time`> in seconds (default: 300). -STP `priority`, `forwarding-delay`, `hello-time`, and `max-age` can be -configured for the bridge. The MAC aging time can also be configured -using the `aging` directive. -The `show bridge` operational command can be used to display configured -bridges: +.. cfgcmd:: set interfaces bridge <interface> max-age <time> -.. code-block:: none + Bridge maximum aging `<time>` in seconds (default: 20). + + If a another bridge in the spanning tree does not send out a hello packet + for a long period of time, it is assumed to be dead. + + +Link Administration +------------------- + +.. cfgcmd:: set interfaces bridge <interface> description <description> + + Assign given `<description>` to interface. Description will also be passed + to SNMP monitoring systems. + + +.. cfgcmd:: set interfaces bridge <interface> disable + + Disable given `<interface>`. It will be placed in administratively down + (``A/D``) state. + + +.. cfgcmd:: set interfaces bridge <interface> disable-flow-control + + Disable Ethernet flow control (pause frames). + + +.. cfgcmd:: set interfaces bridge <interface> mac <mac-address> + + Configure user defined :abbr:`MAC (Media Access Control)` address on given + `<interface>`. + + +.. cfgcmd:: set interfaces bridge <interface> igmp querier + + Enable IGMP querier + + +Member Interfaces +----------------- + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + + Assign `<member>` interface to bridge `<interface>`. A completion helper + will help you with all allowed interfaces which can be bridged. This includes + :ref:`ethernet-interface`, :ref:`bond-interface`, :ref:`l2tpv3-interface`, + :ref:`openvpn`, :ref:`vxlan-interface`, :ref:`wireless-interface`, + :ref:`tunnel-interface` and :ref:`geneve-interface`. + + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> priority <priority> + + Configure individual bridge port `<priority>`. + + Each bridge has a relative priority and cost. Each interface is associated + with a port (number) in the STP code. Each has a priority and a cost, that + is used to decide which is the shortest path to forward a packet. The lowest + cost path is always used unless the other path is down. If you have multiple + bridges and interfaces then you may need to adjust the priorities to achieve + optimium performance. + + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> cost <cost> - vyos@vyos:~$ show bridge - bridge name bridge id STP enabled interfaces - br100 0000.000c29443b19 yes eth1.100 + Path `<cost>` value for Spanning Tree Protocol. Each interface in a bridge + could have a different speed and this value is used when deciding which + link to use. Faster interfaces should have lower costs. -If spanning-tree is enabled, the `show bridge <name> spanning-tree` command -can be used to show STP configuration: + +STP Parameter +------------- + +:abbr:`STP (Spanning Tree Protocol)` is a network protocol that builds a +loop-free logical topology for Ethernet networks. The basic function of STP is +to prevent bridge loops and the broadcast radiation that results from them. +Spanning tree also allows a network design to include backup links providing +fault tolerance if an active link fails. + +.. cfgcmd:: set interfaces bridge <interface> stp + + Enable spanning tree protocol. STP is disabled by default. + + +.. cfgcmd:: set interfaces bridge <interface> forwarding-delay <delay> + + Spanning Tree Protocol forwarding `<delay>` in seconds (default: 15). + + Forwarding delay time is the time spent in each of the Listening and + Learning states before the Forwarding state is entered. This delay is so + that when a new bridge comes onto a busy network it looks at some traffic + before participating. + + +.. cfgcmd:: set interfaces bridge <interface> hello-time <interval> + + Spanning Tree Protocol hello advertisement `<interval>` in seconds + (default: 2). + + Periodically, a hello packet is sent out by the Root Bridge and the + Designated Bridges. Hello packets are used to communicate information about + the topology throughout the entire Bridged Local Area Network. + + +Exammple +-------- + +Creating a bridge interface is very simple. In this example we will have: + +* A bridge named `br100` +* Member interfaces `eth1` and VLAN 10 on interface `eth2` +* Enable STP +* Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64 .. code-block:: none - vyos@vyos:~$ show bridge br100 spanning-tree - br100 - bridge id 0000.000c29443b19 - designated root 0000.000c29443b19 - root port 0 path cost 0 - max age 20.00 bridge max age 20.00 - hello time 2.00 bridge hello time 2.00 - forward delay 15.00 bridge forward delay 15.00 - ageing time 300.00 - hello timer 0.47 tcn timer 0.00 - topology change timer 0.00 gc timer 64.63 - flags - - eth1.100 (1) - port id 8001 state forwarding - designated root 0000.000c29443b19 path cost 4 - designated bridge 0000.000c29443b19 message age timer 0.00 - designated port 8001 forward delay timer 0.00 - designated cost 0 hold timer 0.00 - flags - -The MAC address-table for a bridge can be displayed using the -`show bridge <name> macs` command: + set interfaces bridge br100 address 192.0.2.1/24 + set interfaces bridge br100 address 2001:db8::ffff/64 + set interfaces bridge br100 member interface eth1 + set interfaces bridge br100 member interface eth2.10 + set interfaces bridge br100 stp + +This results in the active configuration: .. code-block:: none - vyos@vyos:~$ show bridge br100 macs - port no mac addr is local? ageing timer - 1 00:53:29:44:3b:19 yes 0.00 + vyos@vyos# show interfaces bridge br100 + address 192.0.2.1/24 + address 2001:db8::ffff/64 + member { + interface eth1 { + } + interface eth2.10 { + } + } + stp + + +Operation +========= + +.. opcmd:: show bridge + + The `show bridge` operational command can be used to display configured + bridges: + + .. code-block:: none + + vyos@vyos:~$ show bridge + bridge name bridge id STP enabled interfaces + br100 8000.0050569d11df yes eth1 + eth2.10 + +.. opcmd:: show bridge <name> spanning-tree + + Show bridge `<name>` STP configuration. + + .. code-block:: none + + vyos@vyos:~$ show bridge br100 spanning-tree + br100 + bridge id 8000.0050569d11df + designated root 8000.0050569d11df + root port 0 path cost 0 + max age 20.00 bridge max age 20.00 + hello time 2.00 bridge hello time 2.00 + forward delay 14.00 bridge forward delay 14.00 + ageing time 300.00 + hello timer 0.06 tcn timer 0.00 + topology change timer 0.00 gc timer 242.02 + flags + + eth1 (1) + port id 8001 state disabled + designated root 8000.0050569d11df path cost 100 + designated bridge 8000.0050569d11df message age timer 0.00 + designated port 8001 forward delay timer 0.00 + designated cost 0 hold timer 0.00 + flags + + eth2.10 (2) + port id 8002 state disabled + designated root 8000.0050569d11df path cost 100 + designated bridge 8000.0050569d11df message age timer 0.00 + designated port 8002 forward delay timer 0.00 + designated cost 0 hold timer 0.00 + +.. opcmd: show bridge <name> macs + + Show bridge Media Access Control (MAC) address table + + .. code-block:: none + + vyos@vyos:~$ show bridge br100 macs + port no mac addr is local? ageing timer + 1 00:53:29:44:3b:19 yes 0.00 diff --git a/docs/interfaces/common-ipv6-addr-autoconf.txt b/docs/interfaces/common-ipv6-addr-autoconf.txt new file mode 100644 index 00000000..838b299f --- /dev/null +++ b/docs/interfaces/common-ipv6-addr-autoconf.txt @@ -0,0 +1,12 @@ +:abbr:`SLAAC (Stateless Address Autoconfiguration)`
+:rfc:`4862`. IPv6 hosts can configure themselves automatically when connected
+to an IPv6 network using the Neighbor Discovery Protocol via :abbr:`ICMPv6
+(Internet Control Message Protocol version 6)` router discovery messages.
+When first connected to a network, a host sends a link-local router
+solicitation multicast request for its configuration parameters; routers
+respond to such a request with a router advertisement packet that contains
+Internet Layer configuration parameters.
+
+.. note:: This method automatically disables IPv6 traffic forwarding on the
+ interface in question.
+
diff --git a/docs/interfaces/dummy.rst b/docs/interfaces/dummy.rst index 9dbb9668..4627d1dc 100644 --- a/docs/interfaces/dummy.rst +++ b/docs/interfaces/dummy.rst @@ -1,25 +1,90 @@ .. _dummy-interface: +##### Dummy ------ - -Dummy interfaces are much like the loopback interface, except you can have -as many as you want. Dummy interfaces can be used as interfaces that always -stay up (in the same fashion to loopbacks in Cisco IOS), or for testing -purposes. - -Configuration commands: - -.. code-block:: none - - vyos@vyos# set interfaces dummy dum0 - Possible completions: - + address IP address - description Interface description - disable Disable interface - > ip IPv4 routing parameters - > ipv6 IPv6 routing parameters - redirect Incoming packet redirection destination - > traffic-policy - Traffic-policy for interface +##### + +The dummy interface is really a little exotic, but rather useful nevertheless. +Dummy interfaces are much like the :ref:`loopback-interface` interface, except +you can have as many as you want. + +.. note:: Dummy interfaces can be used as interfaces that always stay up (in + the same fashion to loopbacks in Cisco IOS), or for testing purposes. + +.. hint:: A Dummy interface is always up, thus it could be used for + management traffic or as source/destination for and :abbr:`IGP (Interior + Gateway Protocol)` like :ref:`bgp` so your internal BGP link is not dependant + on physical link states and multiple routes can be choosen to the + destination. A :ref:`dummy-interface` Interface should always be preferred + over a :ref:`loopback-interface` interface. + + +Configuration +############# + +Address +------- + +.. cfgcmd:: set interfaces dummy <interface> address <address | dhcp | dhcpv6> + + Configure dummy interface `<interface>` with one or more interface + addresses. Address can be specified multiple times as IPv4 and/or IPv6 + address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + + Example: + + .. code-block:: none + + set interfaces dummy dum10 address 192.0.2.1/24 + set interfaces dummy dum10 address 192.0.2.2/24 + set interfaces dummy dum10 address 2001:db8::ffff/64 + set interfaces dummy dum10 address 2001:db8:100::ffff/64 + +Link Administration +------------------- + +.. cfgcmd:: set interfaces dummy <interface> description <description> + + Assign given `<description>` to interface. Description will also be passed + to SNMP monitoring systems. + +.. cfgcmd:: set interfaces dummy <interface> disable + + Disable given `<interface>`. It will be placed in administratively down + state. + +Operation +========= + +.. opcmd:: show interfaces dummy + + Show brief interface information.information + + .. code-block:: none + + vyos@vyos:~$ show interfaces dummy + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + dum0 172.18.254.201/32 u/u + +.. opcmd:: show interfaces dummy <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 + dum0: <BROADCAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN group default qlen 1000 + link/ether 26:7c:8e:bc:fc:f5 brd ff:ff:ff:ff:ff:ff + inet 172.18.254.201/32 scope global dum0 + valid_lft forever preferred_lft forever + inet6 fe80::247c:8eff:febc:fcf5/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 0 0 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 1369707 4267 0 0 0 0 + diff --git a/docs/interfaces/ethernet.rst b/docs/interfaces/ethernet.rst index a8cee8c2..1f691269 100644 --- a/docs/interfaces/ethernet.rst +++ b/docs/interfaces/ethernet.rst @@ -1,72 +1,226 @@ .. _ethernet-interface: +######## Ethernet --------- - -Ethernet interfaces allow for the configuration of speed, duplex, and hw-id -(MAC address). Below is an example configuration: - -.. code-block:: none - - set interfaces ethernet eth1 address '192.168.0.1/24' - set interfaces ethernet eth1 address '2001:db8:1::ffff/64' - set interfaces ethernet eth1 description 'INSIDE' - set interfaces ethernet eth1 duplex 'auto' - set interfaces ethernet eth1 speed 'auto' - -Resulting in: - -.. code-block:: none - - ethernet eth1 { - address 192.168.0.1/24 - address 2001:db8:1::ffff/64 - description INSIDE - duplex auto - hw-id 00:53:29:44:3b:19 - smp_affinity auto - speed auto - } - -In addition, Ethernet interfaces provide the extended operational commands: - -* ``show interfaces ethernet <name> physical`` -* ``show interfaces ethernet <name> statistics`` - -Statistics available are driver dependent. - -.. code-block:: none - - vyos@vyos:~$ show interfaces ethernet eth0 physical - Settings for eth0: - Supported ports: [ TP ] - Supported link modes: 10baseT/Half 10baseT/Full - 100baseT/Half 100baseT/Full - 1000baseT/Full - Supports auto-negotiation: Yes - Advertised link modes: 10baseT/Half 10baseT/Full - 100baseT/Half 100baseT/Full - 1000baseT/Full - Advertised pause frame use: No - Advertised auto-negotiation: Yes - Speed: 1000Mb/s - Duplex: Full - Port: Twisted Pair - PHYAD: 0 - Transceiver: internal - Auto-negotiation: on - MDI-X: Unknown - Supports Wake-on: d - Wake-on: d - Current message level: 0x00000007 (7) - Link detected: yes - driver: e1000 - version: 7.3.21-k8-NAPI - firmware-version: - bus-info: 0000:02:01.0 - - vyos@vyos:~$ show interfaces ethernet eth0 statistics - NIC statistics: - rx_packets: 3530 - tx_packets: 2179 - [...] +######## + +Configuration +############# + +Address +------- + +.. cfgcmd:: set interfaces ethernet <interface> address <address | dhcp | dhcpv6> + + Configure interface `<interface>` with one or more interface addresses. + + * **address** can be specified multiple times as IPv4 and/or IPv6 address, + e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + * **dhcp** interface address is received by DHCP from a DHCP server on this + segment. + * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 server on + this segment. + + Example: + + .. code-block:: none + + set interfaces ethernet eth0 address 192.0.2.1/24 + set interfaces ethernet eth0 address 192.0.2.2/24 + set interfaces ethernet eth0 address 2001:db8::ffff/64 + set interfaces ethernet eth0 address 2001:db8:100::ffff/64 + +.. cfgcmd:: set interfaces ethernet <interface> ipv6 address autoconf + + .. include:: common-ipv6-addr-autoconf.txt + +.. cfgcmd:: set interfaces ethernet <interface> ipv6 address eui64 <prefix> + + :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in + :rfc:`4291` allows a host to assign iteslf a unique 64-Bit IPv6 address. + + .. code-block:: none + + set interfaces ethernet eth0 ipv6 address eui64 2001:db8:beef::/64 + +Speed/Duplex +------------ + +.. cfgcmd:: set interfaces ethernet <interface> duplex <auto | full | half> + + Configure physical interface duplex setting. + + * auto - interface duplex setting is auto-negotiated + * full - always use full-duplex + * half - always use half-duplex + + VyOS default will be `auto`. + +.. cfgcmd:: set interfaces ethernet <interface> speed <auto | 10 | 100 | 1000 | 2500 | 5000 | 10000 | 25000 | 40000 | 50000 | 100000> + + Configure physical interface speed setting. + + * auto - interface speed is auto-negotiated + * 10 - 10 MBit/s + * 100 - 100 MBit/s + * 1000 - 1 GBit/s + * 2500 - 2.5 GBit/s + * 5000 - 5 GBit/s + * 10000 - 10 GBit/s + * 25000 - 25 GBit/s + * 40000 - 40 GBit/s + * 50000 - 50 GBit/s + * 100000 - 100 GBit/s + + VyOS default will be `auto`. + +Link Administration +------------------- + +.. cfgcmd:: set interfaces ethernet <interface> description <description> + + Assign given `<description>` to interface. Description will also be passed + to SNMP monitoring systems. + +.. cfgcmd:: set interfaces ethernet <interface> disable + + Disable given `<interface>`. It will be placed in administratively down + (``A/D``) state. + +.. cfgcmd:: set interfaces ethernet <interface> disable-flow-control + + Disable Ethernet flow control (pause frames). + + +.. cfgcmd:: set interfaces ethernet <interface> mac <mac-address> + + Configure user defined :abbr:`MAC (Media Access Control)` address on given + `<interface>`. + +.. cfgcmd:: set interfaces ethernet <interface> mtu <mtu> + + Configure :abbr:`MTU (Maximum Transmission Unit)` on given `<interface>`. It + is the size (in bytes) of the largest ethernet frame sent on this link. + +Router Advertisements +--------------------- + +Router advertisements are described in :rfc:`4861#section-4.6.2`. They are part +of what is known as :abbr:`SLAAC (Stateless Address Autoconfiguration)`. + +.. cfgcmd:: set interfaces ethernet <interface> ipv6 router-advert send-advert <true | false> + + Enable or disable router advertisements in this `<interface>`. + +.. cfgcmd:: set interfaces ethernet <interface> ipv6 router-advert prefix <prefix> + + Prefix information is described in :rfc:`4861#section-4.6.2`. + +Operation +========= + +.. opcmd:: show interfaces ethernet + + Show brief interface information. + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 172.18.201.10/24 u/u LAN + eth1 172.18.202.11/24 u/u WAN + eth2 - u/D + +.. opcmd:: show interfaces ethernet <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 + eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 + link/ether 00:50:44:00:f5:c9 brd ff:ff:ff:ff:ff:ff + inet6 fe80::250:44ff:fe00:f5c9/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 56735451 179841 0 0 0 142380 + TX: bytes packets errors dropped carrier collisions + 5601460 62595 0 0 0 0 + +.. opcmd:: show interfaces ethernet <interface> physical + + Show information about physical `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 physical + Settings for eth0: + Supported ports: [ TP ] + Supported link modes: 1000baseT/Full + 10000baseT/Full + Supported pause frame use: No + Supports auto-negotiation: No + Supported FEC modes: Not reported + Advertised link modes: Not reported + Advertised pause frame use: No + Advertised auto-negotiation: No + Advertised FEC modes: Not reported + Speed: 10000Mb/s + Duplex: Full + Port: Twisted Pair + PHYAD: 0 + Transceiver: internal + Auto-negotiation: off + MDI-X: Unknown + Supports Wake-on: uag + Wake-on: d + Link detected: yes + driver: vmxnet3 + version: 1.4.16.0-k-NAPI + firmware-version: + expansion-rom-version: + bus-info: 0000:0b:00.0 + supports-statistics: yes + supports-test: no + supports-eeprom-access: no + supports-register-dump: yes + supports-priv-flags: no + +.. opcmd:: show interfaces ethernet <interface> transceiver + + Show transceiver information from plugin modules, e.g SFP+, QSFP + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth5 transceiver + Identifier : 0x03 (SFP) + Extended identifier : 0x04 (GBIC/SFP defined by 2-wire interface ID) + Connector : 0x07 (LC) + Transceiver codes : 0x00 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00 + Transceiver type : Ethernet: 1000BASE-SX + Encoding : 0x01 (8B/10B) + BR, Nominal : 1300MBd + Rate identifier : 0x00 (unspecified) + Length (SMF,km) : 0km + Length (SMF) : 0m + Length (50um) : 550m + Length (62.5um) : 270m + Length (Copper) : 0m + Length (OM3) : 0m + Laser wavelength : 850nm + Vendor name : CISCO-FINISAR + Vendor OUI : 00:90:65 + Vendor PN : FTRJ-8519-7D-CS4 + Vendor rev : A + Option values : 0x00 0x1a + Option : RX_LOS implemented + Option : TX_FAULT implemented + Option : TX_DISABLE implemented + BR margin, max : 0% + BR margin, min : 0% + Vendor SN : FNS092xxxxx + Date code : 0506xx + diff --git a/docs/interfaces/geneve.rst b/docs/interfaces/geneve.rst index dc762738..b0bfde06 100644 --- a/docs/interfaces/geneve.rst +++ b/docs/interfaces/geneve.rst @@ -32,6 +32,9 @@ Geneve Header: | Variable Length Options | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +Configuration +============= + .. cfgcmd:: set interfaces geneve gnv0 address '192.0.2.2/24' Create GENEVE tunnel listening on local address `192.0.2.2/24`. diff --git a/docs/interfaces/index.rst b/docs/interfaces/index.rst deleted file mode 100644 index 0513adf1..00000000 --- a/docs/interfaces/index.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. _network-interfaces: - -################## -Network Interfaces -################## - -Configured interfaces on a VyOS system can be displayed using the -``show interfaces`` command. - -.. code-block:: none - - vyos@vyos:~$ show interfaces - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - eth0 172.16.51.129/24 u/u OUTSIDE - eth1 192.168.0.1/24 u/u INSIDE - lo 127.0.0.1/8 u/u - ::1/128 - -A specific interface can be shown using the ``show interfaces <type> <name>`` -command. - -.. code-block:: none - - vyos@vyos:~$ show interfaces ethernet eth0 - eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP qlen 1000 - link/ether 00:53:29:44:3b:0f brd ff:ff:ff:ff:ff:ff - inet 172.16.51.129/24 brd 172.16.51.255 scope global eth0 - inet6 fe80::20c:29ff:fe44:3b0f/64 scope link - valid_lft forever preferred_lft forever - Description: OUTSIDE - - RX: bytes packets errors dropped overrun mcast - 274397 3064 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 257276 1890 0 0 0 0 - -Different network interfaces provide type-specific configuration. Ethernet -interfaces, for example, allow the configuration of speed and duplex. - -Many services, such as network routing, firewall, and traffic policy also -maintain interface-specific configuration. These will be covered in their -respective sections. - - -.. toctree:: - :maxdepth: 2 - - addresses - dummy - ethernet - l2tpv3 - pppoe - wireless - bridge - bond - tunnel - vlan - qinq - vxlan - geneve diff --git a/docs/interfaces/loopback.rst b/docs/interfaces/loopback.rst new file mode 100644 index 00000000..f7519631 --- /dev/null +++ b/docs/interfaces/loopback.rst @@ -0,0 +1,75 @@ +.. _loopback-interface: + +######## +Loopback +######## + +The loopback networking interface is a virtual network device implemented +entirely in software. All traffic sent to it "loops back" and just targets +services on your local machine. + +.. note:: There can only be one loopback ``lo`` interface on the system. If + you need multiple interfaces, please use the :ref:`dummy-interface` + interface type. + +.. hint:: A lookback interface is always up, thus it could be used for + management traffic or as source/destination for and :abbr:`IGP (Interior + Gateway Protocol)` like :ref:`bgp` so your internal BGP link is not dependant + on physical link states and multiple routes can be choosen to the + destination. A :ref:`dummy-interface` Interface should always be preferred + over a :ref:`loopback-interface` interface. + +Configuration +============= + +Address +------- + +.. cfgcmd:: set interfaces loopback lo address <address> + + Configure Loopback interface `lo` with one or more interface addresses. + Address can be specified multiple times as IPv4 and/or IPv6 address, e.g. + 192.0.2.1/24 and/or 2001:db8::1/64. + +Link Administration +------------------- + +.. cfgcmd:: set interfaces loopback lo description <description> + + Assign given `<description>` to interface `lo`. Description will also be + passed to SNMP monitoring systems. + +Operation +========= + +.. opcmd:: show interfaces loopback + + Show brief interface information. + + .. code-block:: none + + vyos@vyos:~$ show interfaces loopback + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + lo 127.0.0.1/8 u/u + ::1/128 + +.. opcmd:: show interfaces loopback lo + + Show detailed information on given loopback interface `lo`. + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 + lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 + inet 127.0.0.1/8 scope host lo + valid_lft forever preferred_lft forever + inet6 ::1/128 scope host + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 300 6 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 300 6 0 0 0 0 diff --git a/docs/interfaces/pppoe.rst b/docs/interfaces/pppoe.rst index ef595b97..9888d682 100644 --- a/docs/interfaces/pppoe.rst +++ b/docs/interfaces/pppoe.rst @@ -1,7 +1,8 @@ .. _pppoe-interface: +##### PPPoE -===== +##### :abbr:`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol for encapsulating PPP frames inside Ethernet frames. It appeared in 1999, @@ -14,14 +15,14 @@ PPP facilities for authenticating the user with a username and password, predominately via the PAP protocol and less often via CHAP. Operating Modes ---------------- +=============== VyOS supports setting up PPPoE in two different ways to a PPPoE internet connection. This is due to most ISPs provide a modem that is also a wireless router. Home Users -********** +---------- In this method, the DSL Modem/Router connects to the ISP for you with your credentials preprogrammed into the device. This gives you an :rfc:`1918` @@ -34,7 +35,7 @@ few extra layers of complexity, particularly if you use some NAT or tunnel features. Business Users -************** +-------------- In order to have full control and make use of multiple static public IP addresses, your VyOS will have to initiate the PPPoE connection and control @@ -50,8 +51,8 @@ configure it to open the PPPoE session for you and your DSL Transceiver (Modem/Router) just acts to translate your messages in a way that vDSL/aDSL understands. -Configuration Example -~~~~~~~~~~~~~~~~~~~~~ +Example +======= Requirements: @@ -95,7 +96,7 @@ assigning it to the pppoe0 itself as shown here: set interfaces ethernet eth0 pppoe 0 firewall out name NET-OUT VLAN Example -++++++++++++ +------------ Some recent ISPs require you to build the PPPoE connection through a VLAN interface. One of those ISPs is e.g. Deutsche Telekom in Germany. VyOS @@ -116,30 +117,31 @@ which is the default VLAN for Deutsche Telekom: set interfaces ethernet eth0 vif 7 pppoe 0 password 'secret' Troubleshooting ---------------- +=============== .. opcmd:: disconnect interface <interface> -Test disconnecting given connection-oriented interface. `<interface>` can be -``pppoe0`` as example. + Test disconnecting given connection-oriented interface. `<interface>` can be + ``pppoe0`` as example. .. opcmd:: connect interface <interface> -Test connecting given connection-oriented interface. `<interface>` can be -``pppoe0`` as example. + Test connecting given connection-oriented interface. `<interface>` can be + ``pppoe0`` as example. .. opcmd:: show interfaces pppoe <interface> -Check PPPoE connection logs with the following command which shows the current -statistics, status and some of the settings (i.e. MTU) for the current -connection on <interface> (e.g. ``pppoe0``) + Check PPPoE connection logs with the following command which shows the + current statistics, status and some of the settings (i.e. MTU) for the + current connection on <interface> (e.g. ``pppoe0``) .. opcmd:: show interfaces pppoe <interface> log -Show entire log for the PPPoE connection starting with the oldest data. Scroll -down with the <space> key to reach the end where the current data is. + Show entire log for the PPPoE connection starting with the oldest data. + Scroll down with the <space> key to reach the end where the current data is. .. opcmd:: show interfaces pppoe <interface> log tail -Shows the same log as without the 'tail' option but start with the last few -lines and continues to show added lines until you exit with ``Ctrl + x`` + Shows the same log as without the 'tail' option but start with the last few + lines and continues to show added lines until you exit with ``Ctrl + x`` + diff --git a/docs/interfaces/vxlan.rst b/docs/interfaces/vxlan.rst index e597e167..67dab820 100644 --- a/docs/interfaces/vxlan.rst +++ b/docs/interfaces/vxlan.rst @@ -1,7 +1,8 @@ .. _vxlan-interface: +##### VXLAN ------ +##### :abbr:`VXLAN (Virtual Extensible LAN)` is a network virtualization technology that attempts to address the scalability problems associated with large cloud @@ -32,12 +33,102 @@ may be blocked by the hypervisor. for VXLAN, VyOS uses a default port of 8472. You can change the port on a per VXLAN interface basis to get it working accross multiple vendors. -Multicast VXLAN -^^^^^^^^^^^^^^^^ +Configuration +============= + +Address +------- + +.. cfgcmd:: set interfaces vxlan <interface> address <address> + + Configure VXLAN interface `<interface>` with one or more interface + addresses. Address can be specified multiple times as IPv4 and/or IPv6 + address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + + Example: + + .. code-block:: none + + set interfaces vxlan vxlan0 address 192.0.2.1/24 + set interfaces vxlan vxlan0 address 192.0.2.2/24 + set interfaces vxlan vxlan0 address 2001:db8::ffff/64 + set interfaces vxlan vxlan0 address 2001:db8:100::ffff/64 + + +.. cfgcmd:: set interfaces vxlan <interface> ipv6 address autoconf + + .. include:: common-ipv6-addr-autoconf.txt + +.. cfgcmd:: set interfaces vxlan <interface> ipv6 address eui64 <prefix> + + :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in + :rfc:`4291` allows a host to assign iteslf a unique 64-Bit IPv6 address. + + .. code-block:: none + + set interfaces vxlan vxlan0 ipv6 address eui64 2001:db8:beef::/64 + + +.. cfgcmd:: set interfaces vxlan <interface> link <interface> + + Interface used for VXLAN underlay. This is mandatory when using VXLAN via + a multicast network. VXLAN traffic will always enter and exit this interface. + + +.. cfgcmd:: set interfaces vxlan <interface> group <address> + + Multicast group address for VXLAN interface. VXLAN tunnels can be built + either via Multicast or via Unicast. + + Both IPv4 and IPv6 multicast is possible. + + +.. cfgcmd:: set interfaces vxlan <interface> remote <address> + + IPv4/IPv6 remote address of the VXLAN tunnel. Alternative to multicast, the + remote IPv4/IPv6 address can set directly. + + +.. cfgcmd:: set interfaces vxlan <interface> port <port> + + Configure port number of remote VXLAN endpoint. -Example Topology: + .. note:: As VyOS is Linux based the default port used is not using 4789 + as the default IANA-assigned destination UDP port number. Instead VyOS + uses the Linux default port of 8472. -PC4 - Leaf2 - Spine1 - Leaf3 - PC5 + +.. cfgcmd:: set interfaces vxlan <interface> vni <number> + + Each VXLAN segment is identified through a 24-bit segment ID, termed the + :abbr:`VNI (VXLAN Network Identifier (or VXLAN Segment ID))`, This allows + up to 16M VXLAN segments to coexist within the same administrative domain. + + +Link Administration +------------------- + +.. cfgcmd:: set interfaces vxlan <interface> description <description> + + Assign given `<description>` to interface. Description will also be passed + to SNMP monitoring systems. + +.. cfgcmd:: set interfaces vxlan <interface> disable + + Disable given `<interface>`. It will be placed in administratively down + (``A/D``) state. + +.. cfgcmd:: set interfaces vxlan <interface> mtu <mtu> + + Configure :abbr:`MTU (Maximum Transmission Unit)` on given `<interface>`. It + is the size (in bytes) of the largest ethernet frame sent on this link. + MTU ranges from 1450 to 9000 bytes. For best performance you should have + a MTU > 1550 bytes on your underlay. + +Multicast VXLAN +=============== + +Topology: PC4 - Leaf2 - Spine1 - Leaf3 - PC5 PC4 has IP 10.0.0.4/24 and PC5 has IP 10.0.0.5/24, so they believe they are in the same broadcast domain. @@ -65,30 +156,10 @@ For optimal scalability Multicast shouldn't be used at all, but instead use BGP to signal all connected devices between leafs. Unfortunately, VyOS does not yet support this. -Configuration commands -^^^^^^^^^^^^^^^^^^^^^^ +Example +------- -.. code-block:: none - - interfaces - vxlan <vxlan[0-16777215]> - address # IP address of the VXLAN interface - description # Description - group <ipv4> # IPv4 Multicast group address (required) - ip # IPv4 routing options - ipv6 # IPv6 routing options - link <dev> # IP interface for underlay of this vxlan overlay (optional) - mtu # MTU - policy # Policy routing options - remote # Remote address of the VXLAN tunnel, used for PTP instead of multicast - vni <1-16777215> # Virtual Network Identifier (required) - -Configuration Example -^^^^^^^^^^^^^^^^^^^^^ - -The setup is this: - -Leaf2 - Spine1 - Leaf3 +The setup is this: Leaf2 - Spine1 - Leaf3 Spine1 is a Cisco IOS router running version 15.4, Leaf2 and Leaf3 is each a VyOS router running 1.2. @@ -111,7 +182,7 @@ Topology: Eth0 towards Spine1, IP-address 10.1.3.3/24 Eth1 towards a vlan-aware switch -Spine1 Configuration: +**Spine1 Configuration:** .. code-block:: none @@ -131,10 +202,10 @@ Spine1 Configuration: Multicast-routing is required for the leafs to forward traffic between each other in a more scalable way. This also requires PIM to be enabled towards the -Leafs so that the Spine can learn what multicast groups each Leaf expect traffic -from. +Leafs so that the Spine can learn what multicast groups each Leaf expect +traffic from. -Leaf2 configuration: +**Leaf2 configuration:** .. code-block:: none @@ -159,7 +230,7 @@ Leaf2 configuration: set interfaces vxlan vxlan242 link 'eth0' set interfaces vxlan vxlan242 vni '242' -Leaf3 configuration: +**Leaf3 configuration:** .. code-block:: none @@ -238,77 +309,11 @@ its pre-standard value of 8472 to preserve backwards compatibility. A configuration directive to support a user-specified destination port to override that behavior is available using the above command. -Older Examples -^^^^^^^^^^^^^^ - -Example for bridging normal L2 segment and vxlan overlay network, and using a -vxlan interface as routing interface. - -.. code-block:: none - - interfaces { - bridge br0 { - member { - interface vxlan0 { - } - } - } - ethernet eth0 { - address dhcp - } - loopback lo { - } - vxlan vxlan0 { - group 239.0.0.1 - vni 0 - } - vxlan vxlan1 { - address 192.168.0.1/24 - link eth0 - group 239.0.0.1 - vni 1 - } - } - -Here is a working configuration that creates a VXLAN between two routers. Each -router has a VLAN interface (26) facing the client devices and a VLAN interface -(30) that connects it to the other routers. With this configuration, traffic -can flow between both routers' VLAN 26, but can't escape since there is no L3 -gateway. You can add an IP to a bridge to create a gateway. - -.. code-block:: none - - interfaces { - bridge br0 { - member { - interface eth0.26 { - } - interface vxlan0 { - } - } - } - ethernet eth0 { - duplex auto - smp-affinity auto - speed auto - vif 30 { - address 10.7.50.6/24 - } - } - loopback lo { - } - vxlan vxlan0 { - group 239.0.0.241 - vni 241 - } - } - Unicast VXLAN -^^^^^^^^^^^^^ - -Alternative to multicast, the remote IPv4 address of the VXLAN tunnel can set directly. -Let's change the Multicast example from above: +============= +Alternative to multicast, the remote IPv4 address of the VXLAN tunnel can be +set directly. Let's change the Multicast example from above: .. code-block:: none diff --git a/docs/nat.rst b/docs/nat.rst index 714697d3..9607be3d 100644 --- a/docs/nat.rst +++ b/docs/nat.rst @@ -1,22 +1,270 @@ .. _nat: +### NAT -=== +### + +:abbr:`NAT (Network Address Translation)` is a common method of remapping one +IP address space into another by modifying network address information in the +IP header of packets while they are in transit across a traffic routing device. +The technique was originally used as a shortcut to avoid the need to readdress +every host when a network was moved. It has become a popular and essential tool +in conserving global address space in the face of IPv4 address exhaustion. One +Internet-routable IP address of a NAT gateway can be used for an entire private +network. + +IP masquerading is a technique that hides an entire IP address space, usually +consisting of private IP addresses, behind a single IP address in another, +usually public address space. The hidden addresses are changed into a single +(public) IP address as the source address of the outgoing IP packets so they +appear as originating not from the hidden host but from the routing device +itself. Because of the popularity of this technique to conserve IPv4 address +space, the term NAT has become virtually synonymous with IP masquerading. + +As network address translation modifies the IP address information in packets, +NAT implementations may vary in their specific behavior in various addressing +cases and their effect on network traffic. The specifics of NAT behavior are +not commonly documented by vendors of equipment containing NAT implementations. + +The computers on an internal network can use any of the addresses set aside by +the :abbr:`IANA (Internet Assigned Numbers Authority)` for private addressing +(see :rfc:`1918`). These reserved IP addresses are not in use on the Internet, +so an external machine will not directly route to them. The following addresses +are reserved for private use: + +* 10.0.0.0 to 10.255.255.255 (CIDR: 10.0.0.0/8) +* 172.16.0.0 to 172.31.255.255 (CIDR: 172.16.0.0/12) +* 192.168.0.0 to 192.168.255.255 (CIDR: 192.268.0.0/16) + + +If an ISP deploys a :abbr:`CGN (Carrier-grade NAT)`, and uses :rfc:`1918` +address space to number customer gateways, the risk of address collision, and +therefore routing failures, arises when the customer network already uses an +:rfc:`1918` address space. + +This prompted some ISPs to develop a policy within the :abbr:`ARIN (American +Registry for Internet Numbers)` to allocate new private address space for CGNs, +but ARIN deferred to the IETF before implementing the policy indicating that +the matter was not a typical allocation issue but a reservation of addresses +for technical purposes (per :rfc:`2860`). + +IETF published :rfc:`6598`, detailing a shared address space for use in ISP +CGN deployments that can handle the same network prefixes occurring both on +inbound and outbound interfaces. ARIN returned address space to the :abbr:`IANA +(Internet Assigned Numbers Authority)` for this allocation. + +The allocated address block is 100.64.0.0/10. + +Devices evaluating whether an IPv4 address is public must be updated to +recognize the new address space. Allocating more private IPv4 address space for +NAT devices might prolong the transition to IPv6. + +Overview +======== + +Different NAT Types +------------------- + +.. _source-nat: + +Source NAT (SNAT) +^^^^^^^^^^^^^^^^^ + +Source NAT is the most common form of NAT and is typically referred to simply +as NAT. To be more correct, what most people refer to as NAT is actually the +process of :abbr:`PAT (Port Address Translation)`, or NAT Overload. SNAT is +typically used by internal users/private hosts to access the Internet - the +source address is translated and thus kept private. + +.. _destination-nat: + +Destination NAT (DNAT) +^^^^^^^^^^^^^^^^^^^^^^ + +While :ref:`source-nat` changes the source address of packets, DNAT changes +the destination address of packets passing through the router. DNAT is +typically used when an external (public) host needs to initiate a session with +an internal (private) host. A customer needs to access a private service +behind the routers public IP. A connection is established with the routers +public IP address on a well known port and thus all traffic for this port is +rewritten to address the internal (private) host. + +.. _bidirectional-nat: + +Bidirectional NAT +^^^^^^^^^^^^^^^^^ + +This is a common szenario where both :ref:`source-nat` and +:ref:`destination-nat` are configured at the same time. It's commonly used then +internal (private) hosts need to establish a connection with external resources +and external systems need to acces sinternal (private) resources. + +NAT, Routing, Firewall Interaction +---------------------------------- + +There is a very nice picture/explanation in the Vyatta documentation which +should be rewritten here. + +NAT Ruleset +----------- + +:abbr:`NAT (Network Address Translation)` is configured entirely on a series +of so called `rules`. Rules are numbered and evaluated by the underlaying OS +in numerical order! The rule numbers can be changes by utilizing the +:cfgcmd:`rename` and :cfgcmd:`copy` commands. + +.. note:: Changes to the NAT system only affect newly established connections. + Already establiushed ocnnections are not affected. + +.. hint:: When designing your NAT ruleset leave some space between consecutive + rules for later extension. Your ruleset could start with numbers 10, 20, 30. + You thus can later extend the ruleset and place new rules between existing + ones. + +Rules will be created for both :ref:`source-nat` and :ref:`destination-nat`. + +For :ref:`bidirectional-nat` a rule for both :ref:`source-nat` and +:ref:`destination-nat` needs to be created. + +.. _traffic-filters: + +Traffic Filters +--------------- + +Traffic Filters are used to control which packets will have the defined NAT +rules applied. Five different filters can be applied within a NAT rule + +* **outbound-interface** - applicable only to :ref:`source-nat`. It configures + the interface which is used for the outside traffic that this translation rule + applies to. + + Example: + + .. code-block:: none + + set nat source rule 20 outbound-interface eth0 + +* **inbound-interface** - applicable only to :ref:`destination-nat`. It + configures the interface which is used for the inside traffic the the + translation rule applies to. + + Example: + + .. code-block:: none + + set nat destination rule 20 inbound-interface eth1 + +* **protocol** - specify which types of protocols this translation rule applies + to. Only packets matching the specified protocol are NATed. By default this + applies to `all` protocols. + + Example: + + * Set SNAT rule 20 to only NAT TCP and UDP packets + * Set DNAT rule 20 to only NAT UDP packets + + .. code-block:: none + + set nat source rule 20 protocol tcp_udp + set nat destination rule 20 protocol udp + +* **source** - specifies which packets the NAT translation rule applies to + based on the packets source IP address and/or source port. Only matching + packets are considered for NAT. + + Example: + + * Set SNAT rule 20 to only NAT packets arriving from the 192.0.2.0/24 network + * Set SNAT rule 30 to only NAT packets arriving from the 192.0.3.0/24 network + with a source port of 80 and 443 + + .. code-block:: none + + set nat source rule 20 source address 192.0.2.0/24 + set nat source rule 30 source address 192.0.3.0/24 + set nat source rule 30 source port 80,443 + + +* **destination** - specify which packets the translation will be applied to, + only based on the destination address and/or port number configured. + + .. note:: If no destination is specified the rule will match on any + destination address and port. + + Example: + + * Configure SNAT rule (40) to only NAT packets with a destination address of + 192.0.2.1. + + .. code-block:: none + + set nat source rule 40 destination address 192.0.2.1 -Source NAT ----------- -Source NAT is typically referred to simply as NAT. To be more correct, what -most people refer to as NAT is actually the process of **Port Address -Translation (PAT)**, or **NAT Overload**. The process of having many internal -host systems communicate to the Internet using a single or subset of IP -addresses. +Address Conversion +------------------ + +Every NAT rule has a translation command defined. The address defined for the +translation is the addrass used when the address information in a packet is +replaced. + +Source Address +^^^^^^^^^^^^^^ + +For :ref:`source-nat` rules the packets source address will be replaced with +the address specified in the translation command. A port translation can also +be specified and is part of the translation address. + +.. note:: The translation address must be set to one of the available addresses + on the configured `outbound-interface` or it must be set to `masquerade` + which will use the primary IP address of the `outbound-interface` as its + translation address. + +.. note:: When using NAT for a large number of host systems it recommended that + a minimum of 1 IP address is used to NAT every 256 private host systems. + This is due to the limit of 65,000 port numbers available for unique + translations and a reserving an average of 200-300 sessions per host system. + +Example: + +* Define a discrete source IP address of 100.64.0.1 for SNAT rule 20 +* Use address `masquerade` (the interfaces primary address) on rule 30 +* For a large amount of private machines behind the NAT your address pool might + to be bigger. Use any address in the range 100.64.0.10 - 100.64.0.20 on SNAT + rule 40 when doing the translation + + +.. code-block:: none + + set nat source rule 20 translation address 100.64.0.1 + set nat source rule 30 translation address 'masquerade' + set nat source rule 40 translation address 100.64.0.10-100.64.0.20 + + +Destination Address +^^^^^^^^^^^^^^^^^^^ + +For :ref:`destination-nat` rules the packets destination address will be +replaced by the specified address in the `translation address` command. + +Example: + +* DNAT rule 10 replaces the destination address of an inbound packet with + 192.0.2.10 + +.. code-block:: none + + set nat destination rule 10 translation address 192.0.2.10 + + +Configuration Examples +====================== To setup SNAT, we need to know: -* The internal IP addresses we want to translate; -* The outgoing interface to perform the translation on; -* The external IP address to translate to. +* The internal IP addresses we want to translate +* The outgoing interface to perform the translation on +* The external IP address to translate to In the example used for the Quick Start configuration above, we demonstrate the following configuration: @@ -87,10 +335,10 @@ protocol behavior. For this reason, VyOS does not globally drop invalid state traffic, instead allowing the operator to make the determination on how the traffic is handled. -NAT Reflection/Hairpin NAT -^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _hairpin_nat_reflection: -.. note:: Avoiding NAT breakage in the absence of split-DNS +Hairpin NAT/NAT Reflection +-------------------------- A typical problem with using NAT and hosting public servers is the ability for internal systems to reach an internal server using it's external IP address. @@ -98,41 +346,87 @@ The solution to this is usually the use of split-DNS to correctly point host systems to the internal address when requests are made internally. Because many smaller networks lack DNS infrastructure, a work-around is commonly deployed to facilitate the traffic by NATing the request from internal hosts -to the source address of the internal interface on the firewall. This technique -is commonly referred to as **NAT Reflection**, or **Hairpin NAT**. +to the source address of the internal interface on the firewall. -In this example, we will be using the example Quick Start configuration above -as a starting point. +This technique is commonly referred to as NAT Reflection or Hairpin NAT. + +Example: -To setup a NAT reflection rule, we need to create a rule to NAT connections -from the internal network to the same internal network to use the source -address of the internal interface. +* Redirect Microsoft RDP traffic from the outside (WAN, external) world via + :ref:`destination-nat` in rule 100 to the internal, private host 192.0.2.40. + +* Redirect Microsoft RDP traffic from the internal (LAN, private) network via + :ref:`destination-nat` in rule 110 to the internal, private host 192.0.2.40. + We also need a :ref:`source-nat` rule 110 for the reverse path of the traffic. + The internal network 192.0.2.0/24 is reachable via interfache `eth0.10`. .. code-block:: none + set nat destination rule 100 description 'Regular destination NAT from external' + set nat destination rule 100 destination port '3389' + set nat destination rule 100 inbound-interface 'pppoe0' + set nat destination rule 100 protocol 'tcp' + set nat destination rule 100 translation address '192.0.2.40' + + set nat destination rule 110 description 'NAT Reflection: INSIDE' + set nat destination rule 110 destination port '3389' + set nat destination rule 110 inbound-interface 'eth0.10' + set nat destination rule 110 protocol 'tcp' + set nat destination rule 110 translation address '192.0.2.40' + set nat source rule 110 description 'NAT Reflection: INSIDE' - set nat source rule 110 destination address '192.168.0.0/24' - set nat source rule 110 outbound-interface 'eth1' - set nat source rule 110 source address '192.168.0.0/24' + set nat source rule 110 destination address '192.0.2.0/24' + set nat source rule 110 outbound-interface 'eth0.10' + set nat source rule 110 protocol 'tcp' + set nat source rule 110 source address '192.0.2.0/24' set nat source rule 110 translation address 'masquerade' Which results in a configuration of: .. code-block:: none - rule 110 { - description "NAT Reflection: INSIDE" - destination { - address 192.168.0.0/24 - } - outbound-interface eth1 - source { - address 192.168.0.0/24 - } - translation { - address masquerade - } - } + vyos@vyos# show nat + destination { + rule 100 { + description "Regular destination NAT from external" + destination { + port 3389 + } + inbound-interface pppoe0 + protocol tcp + translation { + address 192.0.2.40 + } + } + rule 110 { + description "NAT Reflection: INSIDE" + destination { + port 3389 + } + inbound-interface eth0.10 + protocol tcp + translation { + address 192.0.2.40 + } + } + } + source { + rule 110 { + description "NAT Reflection: INSIDE" + destination { + address 192.0.2.0/24 + } + outbound-interface eth0.10 + protocol tcp + source { + address 192.0.2.0/24 + } + translation { + address masquerade + } + } + } + Destination NAT --------------- @@ -242,9 +536,6 @@ internal IP to a reserved external IP. This dedicates an external IP address to an internal IP address and is useful for protocols which don't have the notion of ports, such as GRE. -1-to-1 NAT example ------------------- - Here's an extract of a simple 1-to-1 NAT configuration with one internal and one external interface: @@ -272,11 +563,11 @@ NPTv6 NPTv6 stands for Network Prefix Translation. It's a form of NAT for IPv6. It's described in :rfc:`6296`. NPTv6 is supported in linux kernel since version 3.13. -Usage -^^^^^ +**Usage** -NPTv6 is very useful for IPv6 multihoming. It is also commonly used when the external IPv6 prefix is dynamic, -as it prevents the need for renumbering of internal hosts when the extern prefix changes. +NPTv6 is very useful for IPv6 multihoming. It is also commonly used when the +external IPv6 prefix is dynamic, as it prevents the need for renumbering of +internal hosts when the extern prefix changes. Let's assume the following network configuration: @@ -333,14 +624,18 @@ Resulting in the following ip6tables rules: NAT before VPN -------------- -Some application service providers (ASPs) operate a VPN gateway to provide access to their internal resources, -and require that a connecting organisation translate all traffic to the service provider network to a source address provided by the ASP. +Some application service providers (ASPs) operate a VPN gateway to provide +access to their internal resources, and require that a connecting organisation +translate all traffic to the service provider network to a source address +provided by the ASP. Example Network ^^^^^^^^^^^^^^^ Here's one example of a network environment for an ASP. -The ASP requests that all connections from this company should come from 172.29.41.89 - an address that is assigned by the ASP and not in use at the customer site. +The ASP requests that all connections from this company should come from +172.29.41.89 - an address that is assigned by the ASP and not in use at the +customer site. .. figure:: _static/images/nat_before_vpn_topology.png :scale: 100 % @@ -361,10 +656,11 @@ The required configuration can be broken down into 4 major pieces: Dummy interface -*************** +""""""""""""""" -The dummy interface allows us to have an equivalent of the Cisco IOS Loopback interface - a router-internal interface we can use for IP addresses the router must know about, -but which are not actually assigned to a real network. +The dummy interface allows us to have an equivalent of the Cisco IOS Loopback +interface - a router-internal interface we can use for IP addresses the router +must know about, but which are not actually assigned to a real network. We only need a single step for this interface: @@ -373,7 +669,7 @@ We only need a single step for this interface: set interfaces dummy dum0 address '172.29.41.89/32' NAT Configuration -***************** +""""""""""""""""" .. code-block:: none @@ -389,8 +685,7 @@ NAT Configuration set nat source rule 120 translation address '172.29.41.89' IPSec IKE and ESP -***************** - +""""""""""""""""" The ASP has documented their IPSec requirements: @@ -406,7 +701,8 @@ The ASP has documented their IPSec requirements: * DH Group 14 -Additionally, we want to use VPNs only on our eth1 interface (the external interface in the image above) +Additionally, we want to use VPNs only on our eth1 interface (the external +interface in the image above) .. code-block:: none @@ -427,11 +723,12 @@ Additionally, we want to use VPNs only on our eth1 interface (the external inter set vpn ipsec ipsec-interfaces interface 'eth1' IPSec VPN Tunnels -***************** +""""""""""""""""" -We'll use the IKE and ESP groups created above for this VPN. -Because we need access to 2 different subnets on the far side, we will need two different tunnels. -If you changed the names of the ESP group and IKE group in the previous step, make sure you use the correct names here too. +We'll use the IKE and ESP groups created above for this VPN. Because we need +access to 2 different subnets on the far side, we will need two different +tunnels. If you changed the names of the ESP group and IKE group in the previous +step, make sure you use the correct names here too. .. code-block:: none @@ -448,9 +745,10 @@ If you changed the names of the ESP group and IKE group in the previous step, ma set vpn ipsec site-to-site peer 198.51.100.243 tunnel 1 remote prefix '10.125.0.0/16' Testing and Validation -^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""" -If you've completed all the above steps you no doubt want to see if it's all working. +If you've completed all the above steps you no doubt want to see if it's all +working. Start by checking for IPSec SAs (Security Associations) with: diff --git a/docs/quick-start.rst b/docs/quick-start.rst index ad0d896f..253f093e 100644 --- a/docs/quick-start.rst +++ b/docs/quick-start.rst @@ -4,17 +4,46 @@ Quick Start ########### -Below is a very basic configuration example that will provide a NAT gateway -for a device with two interfaces. +This chapter will guide you on how to get up to speed using your new VyOS +system. It will show you a very basic configuration example that will provide +a :ref:`nat` gateway for a device with two network interfaces (`eth0` and +`eth1`). -Enter configuration mode: +.. _quick-start-configuration-mode: + +Configuration Mode +################## .. code-block:: none vyos@vyos$ configure vyos@vyos# -Configure network interfaces: +Commit and Save +################ + +After every configuration change you need to apply the changes by using the + +.. code-block:: none + + commit + +Once your configuration works as expected you can save it permanently. + +.. code-block:: none + + save + +Interface Configuration +####################### + +* Your outside/WAN interface will be `eth0`, it receives it's interface address + be means of DHCP. +* Your internal/LAN interface is `eth1`. It uses a fixed IP address of + `192.168.0.1/24`. + +After switching to :ref:`quick-start-configuration-mode` issue the following +commands: .. code-block:: none @@ -23,14 +52,31 @@ Configure network interfaces: set interfaces ethernet eth1 address '192.168.0.1/24' set interfaces ethernet eth1 description 'INSIDE' -Enable SSH for remote management: + +Enable SSH Management SSH +######################### + +After switching to :ref:`quick-start-configuration-mode` issue the following +commands, and your system will listen on every interface for incoming SSH +connections. You might want to check the :ref:`ssh` chapter on how to listen +on specific addresses only. .. code-block:: none set service ssh port '22' -Configure DHCP Server and DNS -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Configure DHCP/DNS Servers +########################## + +* Provide DHCP service on your internal/LAN network where VyOS will act + as the default gateway and DNS server. +* Client IP addresses are assigned from the range ``192.168.0.9 - + 192.168.0.254`` +* DHCP leases will hold for one day (86400 seconds) +* VyOS will server as full DNS recursor - no need to bother the Google or + Cloudflare DNS servers (good for privacy) +* Only clients from your internal/LAN network can use the DNS resolver .. code-block:: none @@ -41,19 +87,15 @@ Configure DHCP Server and DNS set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 range 0 start 192.168.0.9 set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 range 0 stop '192.168.0.254' -And a DNS forwarder: - -.. code-block:: none - set service dns forwarding cache-size '0' set service dns forwarding listen-address '192.168.0.1' - set service dns forwarding name-server '203.0.113.1' - set service dns forwarding name-server '203.0.113.2' + set service dns forwarding allow-from '192.168.0.0/24' -NAT and Firewall -^^^^^^^^^^^^^^^^ -Configure Source NAT for our "Inside" network. +NAT +### + +* Configure :ref:`source-nat` for our internal/LAN network .. code-block:: none @@ -61,9 +103,14 @@ Configure Source NAT for our "Inside" network. set nat source rule 100 source address '192.168.0.0/24' set nat source rule 100 translation address masquerade -Add a set of firewall policies for our "Outside" interface. -This configuration creates a proper stateful firewall that blocks all traffic: +Firewall +######## + +Add a set of firewall policies for our outside/WAN interface. + +This configuration creates a proper stateful firewall that blocks all traffic +which was not initiated from the internal/LAN side first. .. code-block:: none @@ -71,6 +118,7 @@ This configuration creates a proper stateful firewall that blocks all traffic: set firewall name OUTSIDE-IN rule 10 action 'accept' set firewall name OUTSIDE-IN rule 10 state established 'enable' set firewall name OUTSIDE-IN rule 10 state related 'enable' + set firewall name OUTSIDE-LOCAL default-action 'drop' set firewall name OUTSIDE-LOCAL rule 10 action 'accept' set firewall name OUTSIDE-LOCAL rule 10 state established 'enable' @@ -80,8 +128,8 @@ This configuration creates a proper stateful firewall that blocks all traffic: set firewall name OUTSIDE-LOCAL rule 20 protocol 'icmp' set firewall name OUTSIDE-LOCAL rule 20 state new 'enable' -If you wanted to enable SSH access to your firewall from the Internet, you -could create some additional rules to allow the traffic. +If you wanted to enable SSH access to your firewall from the outside/WAN +interface, you could create some additional rules to allow that kind of traffic. These rules allow SSH traffic and rate limit it to 4 requests per minute. This blocks brute-forcing attempts: @@ -94,6 +142,7 @@ blocks brute-forcing attempts: set firewall name OUTSIDE-LOCAL rule 30 recent count '4' set firewall name OUTSIDE-LOCAL rule 30 recent time '60' set firewall name OUTSIDE-LOCAL rule 30 state new 'enable' + set firewall name OUTSIDE-LOCAL rule 31 action 'accept' set firewall name OUTSIDE-LOCAL rule 31 destination port '22' set firewall name OUTSIDE-LOCAL rule 31 protocol 'tcp' @@ -117,15 +166,13 @@ Commit changes, save the configuration, and exit configuration mode: vyos@vyos# exit vyos@vyos$ -Basic QoS -^^^^^^^^^ -The traffic policy subsystem provides an interface to Linux traffic control -(tc_). +QoS +### -One common use of traffic policy is to limit bandwidth for an interface. In -the example below we limit bandwidth for our LAN connection to 200 Mbit -download and out WAN connection to 50 Mbit upload: +One common use of :ref:`qos` is to limit bandwidth for an interface. In +the example below we limit bandwidth for our internal/LAN connection to 200 +Mbit/s download and our outside/WAN connection to 50 Mbit/s upload: .. code-block:: none @@ -133,35 +180,13 @@ download and out WAN connection to 50 Mbit upload: set traffic-policy shaper WAN-OUT default bandwidth '50%' set traffic-policy shaper WAN-OUT default ceiling '100%' set traffic-policy shaper WAN-OUT default queue-type 'fair-queue' + set traffic-policy shaper LAN-OUT bandwidth '200Mbit' set traffic-policy shaper LAN-OUT default bandwidth '50%' set traffic-policy shaper LAN-OUT default ceiling '100%' set traffic-policy shaper LAN-OUT default queue-type 'fair-queue' -Resulting in the following configuration: - -.. code-block:: none - - traffic-policy { - shaper WAN-OUT { - bandwidth 50Mbit - default { - bandwidth 50% - ceiling 100% - queue-type fair-queue - } - } - shaper LAN-OUT { - bandwidth 200Mbit - default { - bandwidth 50% - ceiling 100% - queue-type fair-queue - } - } - } - -Once defined, a traffic policy can be applied to each interface using the +Once defined, a traffic policy needs to be applied to each interface using the interface-level traffic-policy directive: .. code-block:: none @@ -169,46 +194,34 @@ interface-level traffic-policy directive: set interfaces ethernet eth0 traffic-policy out 'WAN-OUT' set interfaces ethernet eth1 traffic-policy out 'LAN-OUT' -.. note:: A traffic policy can also be defined to match specific traffic - flows using class statements. - -VyOS 1.2 (Crux) also supports HFSC (:code:`set traffic-policy shaper-hfsc`) - -See further information in the :ref:`qos` chapter. Security Hardening -^^^^^^^^^^^^^^^^^^ +################## -Especially if you are allowing SSH access from the Internet, there are a few -additional configuration steps that should be taken. +Especially if you are allowing SSH remote access from the outside/WAN interface, +there are a few additional configuration steps that should be taken. -Create a user to replace the default `vyos` user: +Replace the default `vyos` system user: .. code-block:: none set system login user myvyosuser level admin set system login user myvyosuser authentication plaintext-password mysecurepassword -Set up SSH key based authentication. For example, on Linux you'd want to run -``ssh-keygen -t rsa``. Then the contents of ``id_rsa.pub`` would be used below: +Set up :ref:`ssh_key_based_authentication`: .. code-block:: none set system login user myvyosuser authentication public-keys myusername@mydesktop type ssh-rsa set system login user myvyosuser authentication public-keys myusername@mydesktop key contents_of_id_rsa.pub -Or you can use the ``loadkey`` command. Commit and save. - Finally, try and SSH into the VyOS install as your new user. Once you have -confirmed that your new user can access your server, without a password, delete +confirmed that your new user can access your router without a password, delete the original ``vyos`` user and probably disable password authentication for -SSH: +:ref:`ssh` at all: .. code-block:: none delete system login user vyos set service ssh disable-password-authentication -Commit and save. - -.. _tc: https://en.wikipedia.org/wiki/Tc_(Linux) diff --git a/docs/routing/bgp.rst b/docs/routing/bgp.rst index d8860e15..14ea1238 100644 --- a/docs/routing/bgp.rst +++ b/docs/routing/bgp.rst @@ -159,14 +159,14 @@ BGP Router Configuration ASN and Router ID ----------------- -.. cfgcmd:: set protocols bgp '<ASN>' +.. cfgcmd:: set protocols bgp <asn> 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 '<ASN>' parameters router-id +.. cfgcmd:: set protocols bgp <asn> parameters router-id This command specifies the router-ID. If router ID is not specified it will use the highest interface IP address. @@ -174,19 +174,19 @@ ASN and Router ID Route Selection --------------- -.. cfgcmd:: set protocols bgp '<ASN>' parameters bestpath as-path confed +.. cfgcmd:: set protocols bgp <asn> parameters bestpath as-path confed This command specifies that the length of confederation path sets and sequences should should be taken into account during the BGP best path decision process. -.. cfgcmd:: set protocols bgp '<ASN>' parameters bestpath as-path multipath-relax +.. cfgcmd:: set protocols bgp <asn> 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 '<ASN>' parameters bestpath as-path ignore +.. cfgcmd:: set protocols bgp <asn> parameters bestpath as-path ignore Ignore AS_PATH length when selecting a route diff --git a/docs/routing/ospf.rst b/docs/routing/ospf.rst index bee70895..acffb7b3 100644 --- a/docs/routing/ospf.rst +++ b/docs/routing/ospf.rst @@ -90,7 +90,7 @@ A typical configuration using 2 nodes. .. 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 Phabricator task T1483_. + on the WireGuard interfaces, see :vytask:`T1483`. Example configuration for WireGuard interfaces: @@ -136,5 +136,3 @@ Example configuration for WireGuard interfaces: 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] -.. _T1483: https://phabricator.vyos.net/T1483 - diff --git a/docs/routing/static.rst b/docs/routing/static.rst index cebe42fa..52a73354 100644 --- a/docs/routing/static.rst +++ b/docs/routing/static.rst @@ -18,32 +18,32 @@ used to determine the forwarding table used for unicast packet forwarding. Static Routes ############# -.. cfgcmd:: set protocols static route '<subnet>' next-hop '<address>' +.. cfgcmd:: set protocols static route <subnet> next-hop <address> Configure next-hop `<address>` for an IPv4 static route. Multiple static routes can be created. -.. cfgcmd:: set protocols static route '<subnet>' next-hop '<address>' disable +.. cfgcmd:: set protocols static route <subnet> next-hop <address> disable Disable this IPv4 static route entry. -.. cfgcmd:: set protocols static route '<subnet>' next-hop '<address>' distance '<distance>' +.. cfgcmd:: set protocols static route <subnet> next-hop <address> distance <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 route6 '<subnet>' next-hop '<address>' +.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> Configure next-hop `<address>` for an IPv6 static route. Multiple static routes can be created. -.. cfgcmd:: set protocols static route6 '<subnet>' next-hop '<address>' disable +.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> disable Disable this IPv6 static route entry. -.. cfgcmd:: set protocols static route6 '<subnet>' next-hop '<address>' distance '<distance>' +.. cfgcmd:: set protocols static route6 <subnet> next-hop <address> distance <distance> Defines next-hop distance for this route, routes with smaller administrative distance are elected prior those with a higher distance. @@ -57,34 +57,34 @@ Static Routes Interface Routes ================ -.. cfgcmd:: set protocols static interface-route '<subnet>' next-hop-interface '<interface>' +.. cfgcmd:: set protocols static interface-route <subnet> next-hop-interface <interface> Allows you to configure the next-hop interface for an interface-based IPv4 static route. `<interface>` will be the next-hop interface where trafic is routed for the given `<subnet>`. -.. cfgcmd:: set protocols static interface-route '<subnet>' next-hop-interface '<interface>' disable +.. cfgcmd:: set protocols static interface-route <subnet> next-hop-interface <interface> disable Disables interface-based IPv4 static route. -.. cfgcmd:: set protocols static interface-route '<subnet>' next-hop-interface '<interface>' distance '<distance>' +.. cfgcmd:: set protocols static interface-route <subnet> next-hop-interface <interface> distance <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 '<subnet>' next-hop-interface '<interface>' +.. cfgcmd:: set protocols static interface-route6 <subnet> next-hop-interface <interface> Allows you to configure the next-hop interface for an interface-based IPv6 static route. `<interface>` will be the next-hop interface where trafic is routed for the given `<subnet>`. -.. cfgcmd:: set protocols static interface-route6 '<subnet>' next-hop-interface '<interface>' disable +.. cfgcmd:: set protocols static interface-route6 <subnet> next-hop-interface <interface> disable Disables interface-based IPv6 static route. -.. cfgcmd:: set protocols static interface-route6 '<subnet>' next-hop-interface '<interface>' distance '<distance>' +.. cfgcmd:: set protocols static interface-route6 <subnet> next-hop-interface <interface> distance <distance> Defines next-hop distance for this route, routes with smaller administrative distance are elected prior those with a higher distance. @@ -95,7 +95,7 @@ Interface Routes Blackhole ========= -.. cfgcmd:: set protocols static route '<subnet>' blackhole +.. cfgcmd:: set protocols static route <subnet> blackhole Use this command to configure a "black-hole" route on the router. A black-hole route is a route for which the system silently discard packets @@ -103,12 +103,12 @@ Blackhole it does not prevent them from being used as a more specific route inside your network. -.. cfgcmd:: set protocols static route '<subnet>' blackhole distance '<distance>' +.. cfgcmd:: set protocols static route <subnet> blackhole distance <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 '<subnet>' blackhole +.. cfgcmd:: set protocols static route6 <subnet> blackhole Use this command to configure a "black-hole" route on the router. A black-hole route is a route for which the system silently discard packets @@ -116,7 +116,7 @@ Blackhole it does not prevent them from being used as a more specific route inside your network. -.. cfgcmd:: set protocols static route6 '<subnet>' blackhole distance '<distance>' +.. cfgcmd:: set protocols static route6 <subnet> blackhole distance <distance> Defines blackhole distance for this route, routes with smaller administrative distance are elected prior those with a higher distance. diff --git a/docs/services/dhcp.rst b/docs/services/dhcp.rst index 19c92aac..bcadb673 100644 --- a/docs/services/dhcp.rst +++ b/docs/services/dhcp.rst @@ -6,6 +6,8 @@ DHCP / DHCPv6 VyOS uses ISC DHCPd for both IPv4 and IPv6 address assignment. +.. _dhcp-server: + DHCP Server =========== @@ -144,23 +146,23 @@ inside the subnet definition but can be outside of the range statement. DHCP Options ------------ -.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 default-router '<address>' +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet 192.0.2.0/24 default-router <address> Specify the default routers IPv4 address which should be used in this subnet. This can - of course - be a VRRP address (DHCP option 003). -.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 dns-server '<address>' +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet 192.0.2.0/24 dns-server <address> Specify the DNS nameservers used (Option 006). This option may be used mulltiple times to specify additional DNS nameservers. -.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 domain-name '<domain-name>' +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet 192.0.2.0/24 domain-name <domain-name> The domain-name parameter should be the domain name that will be appended to the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP Option 015). -.. cfgcmd:: set service dhcp-server shared-network-name '<name>' subnet 192.0.2.0/24 domain-search '<domain-name>' +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet 192.0.2.0/24 domain-search <domain-name> The domain-name parameter should be the domain name used when completing DNS request where no full FQDN is passed. This option can be given multiple times @@ -315,12 +317,24 @@ Always verify that the parameters are correct before commiting the configuration Refer to isc-dhcp's dhcpd.conf manual for more information: https://kb.isc.org/docs/isc-dhcp-44-manual-pages-dhcpdconf +Quotes can be used inside parameter values by replacing all quote characters +with the string ``"``. They will be replaced with literal quote characters +when generating dhcpd.conf. + Example ^^^^^^^ .. opcmd:: set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option domain-name-servers 192.0.2.11, 192.0.2.12;" - Override the static-mapping's dns-server with a custom one that will be sent only to this host. + Override the static-mapping's dns-server with a custom one that will be sent + only to this host. + +.. opcmd:: set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option pxelinux.configfile "pxelinux.cfg/01-00-15-17-44-2d-aa";" + + An option that takes a quoted string is set by replacing all quote characters + with the string ``"`` inside the static-mapping-parameters value. + The resulting line in dhcpd.conf will be + ``option pxelinux.configfile "pxelinux.cfg/01-00-15-17-44-2d-aa";``. Operation Mode -------------- @@ -387,41 +401,41 @@ Configuration Options Clients receiving advertise messages from multiple servers choose the server with the highest preference value. The range for this value is ``0...255``. -.. cfgcmd:: set service dhcpv6-server shared-network-name '<name>' subnet '<v6net>' lease-time {default | maximum | minimum} +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> lease-time {default | maximum | minimum} The default lease time for DHCPv6 leases is 24 hours. This can be changed by supplying a ``default-time``, ``maximum-time`` and ``minimum-time``. All values need to be supplied in seconds. -.. cfgcmd:: set service dhcpv6-server shared-network-name '<name>' subnet '<v6net>' nis-domain '<domain-name>' +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> nis-domain <domain-name> A :abbr:`NIS (Network Information Service)` domain can be set to be used for DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name '<name>' subnet '<v6net>' nisplus-domain '<domain-name>' +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> nisplus-domain <domain-name> The procedure to specify a :abbr:`NIS+ (Network Information Service Plus)` domain is similar to the NIS domain one: -.. cfgcmd:: set service dhcpv6-server shared-network-name '<name>' subnet '<v6net>' nis-server '<address>' +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> nis-server <address> Specify a NIS server address for DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name '<name>' subnet '<v6net>' nisplus-server '<address>' +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> nisplus-server <address> Specify a NIS+ server address for DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name '<name>' subnet '<v6net>' sip-server-address '<address>' +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> sip-server-address <address> Specify a :abbr:`SIP (Session Initiation Protocol)` server by IPv6 address for all DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name '<name>' subnet '<v6net>' sip-server-name '<fqdn>' +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> sip-server-name <fqdn> Specify a :abbr:`SIP (Session Initiation Protocol)` server by FQDN for all DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name '<name>' subnet '<v6net>' sntp-server-address '<address>' +.. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet <prefix> sntp-server-address <address> A SNTP server address can be specified for DHCPv6 clients. @@ -556,7 +570,7 @@ https://wiki.vyos.net/wiki/Network_address_setup. Configuration ------------- -.. cfgcmd:: set service dhcp-relay interface '<interface>' +.. cfgcmd:: set service dhcp-relay interface <interface> Enable the DHCP relay service on the given interface. diff --git a/docs/services/dns-forwarding.rst b/docs/services/dns-forwarding.rst index fb996709..a529f6a7 100644 --- a/docs/services/dns-forwarding.rst +++ b/docs/services/dns-forwarding.rst @@ -29,9 +29,10 @@ avoid to be tracked by the provider of your upstream DNS server. .. cfgcmd:: set service dns forwarding domain <domain-name> server <address> Forward received queries for a particular domain (specified via `domain-name`) - to a given name-server. Multiple nameservers can be specified. + to a given name-server. Multiple nameservers can be specified. You can use + this feature for a DNS split-horizon configuration. -.. note:: This also works for reverse-lookup zones e.g. ``18.172.in-addr.arpa``. + .. note:: This also works for reverse-lookup zones (``18.172.in-addr.arpa``). .. cfgcmd:: set service dns forwarding allow-from <network> @@ -71,8 +72,8 @@ avoid to be tracked by the provider of your upstream DNS server. as with process. * **validate** The highest mode of DNSSEC processing. In this mode, all - queries will be be validated and will be answered with a SERVFAIL in case - of bogus data, regardless of the client's request. + queries will be validated and will be answered with a SERVFAIL in case of + bogus data, regardless of the client's request. .. note:: The famous UNIX/Linux ``dig`` tool sets the AD-bit in the query. This might lead to unexpected query results when testing. Set ``+noad`` diff --git a/docs/services/index.rst b/docs/services/index.rst index af3e6cb1..e0773090 100644 --- a/docs/services/index.rst +++ b/docs/services/index.rst @@ -1,7 +1,5 @@ .. _services: -.. include:: references.rst - ######## Services ######## diff --git a/docs/services/ipoe-server.rst b/docs/services/ipoe-server.rst index 8e3a88eb..a1144301 100644 --- a/docs/services/ipoe-server.rst +++ b/docs/services/ipoe-server.rst @@ -4,9 +4,9 @@ IPoE server VyOS utilizes `accel-ppp`_ to provide IPoE server functionality. It can be used with local authentication (mac-address) or a connected RADIUS server. -.. note:: **Please be aware, due to an upstream bug, config changes/commits +.. note:: Please be aware, due to an upstream bug, config changes/commits will restart the ppp daemon and will reset existing IPoE sessions, - in order to become effective.** + in order to become effective. Configuration ^^^^^^^^^^^^^ @@ -123,7 +123,4 @@ The rate-limit is set in kbit/sec. -------+------------+-------------------+-------------+-----+--------+------------+--------+----------+------------------ ipoe0 | eth2 | 08:00:27:2f:d8:06 | 192.168.0.2 | | | 500/500 | active | 00:00:05 | dccc870fd31349fb - - - -.. _`accel-ppp`: https://accel-ppp.org/ +.. include:: ../common-references.rst diff --git a/docs/services/lldp.rst b/docs/services/lldp.rst index c1f39fba..4b1743e6 100644 --- a/docs/services/lldp.rst +++ b/docs/services/lldp.rst @@ -40,7 +40,8 @@ Configuration .. cfgcmd:: set service lldp management-address <address> - Define IPv4 management address transmitted via LLDP. + Define IPv4/IPv6 management address transmitted via LLDP. Multiple addresses + can be defined. Only addresses connected to the system will be transmitted. .. cfgcmd:: set service lldp interface <interface> @@ -72,65 +73,64 @@ Operation Displays information about all neighbors discovered via LLDP. -.. code-block:: none + .. code-block:: none - vyos@vyos:~# show lldp neighbors - Capability Codes: R - Router, B - Bridge, W - Wlan r - Repeater, S - Station - D - Docsis, T - Telephone, O - Other + vyos@vyos:~$ show lldp neighbors + Capability Codes: R - Router, B - Bridge, W - Wlan r - Repeater, S - Station + D - Docsis, T - Telephone, O - Other - Device ID Local Proto Cap Platform Port ID - --------- ----- ----- --- -------- ------- - Switch0815 eth0 LLDP B Cisco IOS Software, Gi0/4 + Device ID Local Proto Cap Platform Port ID + --------- ----- ----- --- -------- ------- + BR2.vyos.net eth0 LLDP R VyOS 1.2.4 eth1 + BR3.vyos.net eth0 LLDP RB VyOS 1.2.4 eth2 + SW1.vyos.net eth0 LLDP B Cisco IOS Software GigabitEthernet0/6 .. opcmd:: show lldp neighbors detail Get detailed information about LLDP neighbors. -.. code-block:: none - - vyos@vyos:~# show lldp neighbors detail - ------------------------------------------------------------------------------- - LLDP neighbors: - ------------------------------------------------------------------------------- - Interface: eth0, via: LLDP, RID: 1, Time: 12 days, xxxx:xxxx:40 - Chassis: - ChassisID: mac 00:50:40:20:03:00 - SysName: Switch0815 - SysDescr: Cisco IOS Software, C2960 Software (C2960-LANBASEK9-M), Version 15.0(2)SE11, RELEASE SOFTWARE (fc3) - Technical Support: http://www.cisco.com/techsupport - Copyright (c) 1986-2017 by Cisco Systems, Inc. - Compiled Sat 19-Aug-17 09:34 by prod_rel_team - MgmtIP: 192.0.2.201 - Capability: Bridge, on - Port: - PortID: ifname Gi0/4 - PortDescr: GigabitEthernet0/4 - TTL: 120 - PMD autoneg: supported: yes, enabled: yes - Adv: 10Base-T, HD: yes, FD: yes - Adv: 100Base-TX, HD: yes, FD: yes - Adv: 1000Base-T, HD: no, FD: yes - MAU oper type: 1000BaseTFD - Four-pair Category 5 UTP, full duplex mode - VLAN: 1, pvid: yes - LLDP-MED: - Device Type: Network Connectivity Device - Capability: Capabilities, yes - Capability: Policy, yes - Capability: Location, yes - Capability: Inventory, yes - LLDP-MED Network Policy for: Voice, Defined: no - Priority: Best effort - PCP: 0 - DSCP Value: 0 - LLDP-MED Network Policy for: Voice Signaling, Defined: no - Priority: Best effort - PCP: 0 - DSCP Value: 0 - Inventory: - Hardware Revision: WS-C2960G-8TC-L (PowerPC405):C0 - Software Revision: 15.0(2)SE11 - Manufacturer: Cisco Systems, Inc. - Model: WS-C2960G-8TC-L + .. code-block:: none + + vyos@vyos:~$ show lldp neighbors detail + ------------------------------------------------------------------------------- + LLDP neighbors: + ------------------------------------------------------------------------------- + Interface: eth0, via: LLDP, RID: 28, Time: 0 day, 00:24:33 + Chassis: + ChassisID: mac 00:53:00:01:02:c9 + SysName: BR2.vyos.net + SysDescr: VyOS 1.3-rolling-201912230217 + MgmtIP: 192.0.2.1 + MgmtIP: 2001:db8::ffff + Capability: Bridge, on + Capability: Router, on + Capability: Wlan, off + Capability: Station, off + Port: + PortID: mac 00:53:00:01:02:c9 + PortDescr: eth0 + TTL: 120 + PMD autoneg: supported: no, enabled: no + MAU oper type: 10GigBaseCX4 - X copper over 8 pair 100-Ohm balanced cable + VLAN: 201 eth0.201 + VLAN: 205 eth0.205 + LLDP-MED: + Device Type: Network Connectivity Device + Capability: Capabilities, yes + Capability: Policy, yes + Capability: Location, yes + Capability: MDI/PSE, yes + Capability: MDI/PD, yes + Capability: Inventory, yes + Inventory: + Hardware Revision: None + Software Revision: 4.19.89-amd64-vyos + Firmware Revision: 6.00 + Serial Number: VMware-42 1d 83 b9 fe c1 bd b2-7 + Manufacturer: VMware, Inc. + Model: VMware Virtual Platform + Asset ID: No Asset Tag + ------------------------------------------------------------------------------- .. opcmd:: show lldp neighbors interface <interface> diff --git a/docs/services/pppoe-server.rst b/docs/services/pppoe-server.rst index 481831ba..a229d3f9 100644 --- a/docs/services/pppoe-server.rst +++ b/docs/services/pppoe-server.rst @@ -7,9 +7,9 @@ PPPoE Server VyOS utilizes `accel-ppp`_ to provide PPPoE server functionality. It can be used with local authentication or a connected RADIUS server. -.. note:: **Please be aware, due to an upstream bug, config changes/commits +.. note:: Please be aware, due to an upstream bug, config changes/commits will restart the ppp daemon and will reset existing PPPoE connections from - connected users, in order to become effective.** + connected users, in order to become effective. Configuration ============= @@ -241,4 +241,4 @@ subnet for the clients internal use. --------+----------+-------------+--------------------------+---------------------+-------------------+------------+--------+----------+----------+---------- ppp0 | test | 192.168.0.1 | 2001:db8:8002:0:200::/64 | 2001:db8:8003::1/56 | 00:53:00:12:42:eb | | active | 00:00:49 | 875 B | 2.1 KiB -.. _`accel-ppp`: https://accel-ppp.org/ +.. include:: ../common-references.rst diff --git a/docs/services/references.rst b/docs/services/references.rst deleted file mode 100644 index 704f33f7..00000000 --- a/docs/services/references.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _MIB: https://en.wikipedia.org/wiki/Management_information_base -.. _SNMP: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol -.. _SNMPv2: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2 -.. _SNMPv3: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_3 -.. _SSH: https://en.wikipedia.org/wiki/Secure_Shell -.. _Squid3: http://www.squid-cache.org/ -.. _Squidguard: http://www.squidguard.org/ -.. _TFTP: https://en.wikipedia.org/wiki/Trivial_File_Transfer_Protocol -.. _`arbitrary extension commands`: http://net-snmp.sourceforge.net/docs/man/snmpd.conf.html#lbAZ -.. _`accel-ppp`: https://accel-ppp.org/ -.. _`Secure Socket Tunneling Protocol`: https://en.wikipedia.org/wiki/Secure_Socket_Tunneling_Protocol diff --git a/docs/services/snmp.rst b/docs/services/snmp.rst index c4b8fa32..c27cf02a 100644 --- a/docs/services/snmp.rst +++ b/docs/services/snmp.rst @@ -254,4 +254,8 @@ following content: </Commands> </Configuration-Management> -.. include:: references.rst +.. _MIB: https://en.wikipedia.org/wiki/Management_information_base +.. _SNMP: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol +.. _SNMPv2: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2 +.. _SNMPv3: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_3 + diff --git a/docs/services/ssh.rst b/docs/services/ssh.rst index fde575ea..1dd996d4 100644 --- a/docs/services/ssh.rst +++ b/docs/services/ssh.rst @@ -30,17 +30,17 @@ and integrity of data over an unsecured network, such as the Internet. Configuration ============= -.. cfgcmd:: set service ssh port '<number>' +.. cfgcmd:: set service ssh port <port> -Enabling SSH only requires you to specify the port ``<number>`` you want SSH to +Enabling SSH only requires you to specify the port ``<port>`` you want SSH to listen on. By default, SSH runs on port 22. -.. cfgcmd:: set service ssh listen-address '<address>' +.. cfgcmd:: set service ssh listen-address <address> Specify IPv4/IPv6 listen address of SSH server. Multiple addresses can be defined. -.. cfgcmd:: set service ssh ciphers '<cipher>' +.. cfgcmd:: set service ssh ciphers <cipher> Define allowed ciphers used for the SSH connection. A number of allowed ciphers can be specified, use multiple occurrences to allow multiple ciphers. @@ -71,7 +71,7 @@ security! Disable the host validation through reverse DNS lookups - can speedup login time when reverse lookup is not possible. -.. cfgcmd:: set service ssh macs '<mac>' +.. cfgcmd:: set service ssh macs <mac> Specifies the available :abbr:`MAC (Message Authentication Code)` algorithms. The MAC algorithm is used in protocol version 2 for data integrity protection. diff --git a/docs/services/sstp-server.rst b/docs/services/sstp-server.rst index 64a5206b..8e67b95c 100644 --- a/docs/services/sstp-server.rst +++ b/docs/services/sstp-server.rst @@ -6,9 +6,9 @@ SSTP server VyOS utilizes accel-ppp_ to provide SSTP server functionality. It can be used with local authentication or a connected RADIUS server. -.. note:: **Please be aware, due to an upstream bug, config changes/commits +.. note:: Please be aware, due to an upstream bug, config changes/commits will restart the ppp daemon and will reset existing PPPoE connections from - connected users, in order to become effective.** + connected users, in order to become effective. Configuration ^^^^^^^^^^^^^ @@ -73,4 +73,4 @@ looks for all files and directories in ``/config/user-data/sstp``. set sstp-settings ssl-certs server-cert 'server.crt' set sstp-settings ssl-certs server-key 'server.key' -.. include:: references.rst +.. include:: ../common-references.rst diff --git a/docs/services/tftp.rst b/docs/services/tftp.rst index c33d6c7c..ce87011c 100644 --- a/docs/services/tftp.rst +++ b/docs/services/tftp.rst @@ -1,8 +1,8 @@ .. _tftp-server: -#### -TFTP -#### +########### +TFTP Server +########### :abbr:`TFTP (Trivial File Transfer Protocol)` is a simple, lockstep file transfer protocol which allows a client to get a file from or put a file onto @@ -22,7 +22,7 @@ files. content on image upgrades. Any directory under ``/config`` is save at this will be migrated. -.. cfgcmd:: set service tftp-server listen-address '<address>' +.. cfgcmd:: set service tftp-server listen-address <address> Configure the IPv4 or IPv6 listen address of the TFTP server. Multiple IPv4 and IPv6 addresses can be given. There will be one TFTP server instances listening diff --git a/docs/services/udp-broadcast-relay.rst b/docs/services/udp-broadcast-relay.rst index 10939c9d..f9e1b03e 100644 --- a/docs/services/udp-broadcast-relay.rst +++ b/docs/services/udp-broadcast-relay.rst @@ -17,23 +17,23 @@ support 99 IDs! Configuration ------------- -.. cfgcmd:: set service broadcast-relay id '<n>' description '<description>' +.. cfgcmd:: set service broadcast-relay id <n> description <description> A description can be added for each and every unique relay ID. This is usefull to distinguish between multiple different ports/appliactions. -.. cfgcmd:: set service broadcast-relay id '<n>' interface '<interface>' +.. cfgcmd:: set service broadcast-relay id <n> interface <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 '<n>' port '<port>' +.. cfgcmd:: set service broadcast-relay id <n> port <port> The UDP port number used by your apllication. It is mandatory for this kind of operation. -.. cfgcmd:: set service broadcast-relay id '<n>' disable +.. cfgcmd:: set service broadcast-relay id <n> disable Each broadcast relay instance can be individually disabled without deleting the configured node by using the following command: diff --git a/docs/services/webproxy.rst b/docs/services/webproxy.rst index b4b20ef5..20e1eb73 100644 --- a/docs/services/webproxy.rst +++ b/docs/services/webproxy.rst @@ -3,7 +3,7 @@ Webproxy The proxy service in VyOS is based on Squid3 and some related modules. -Squid is a caching and forwarding HTTP web proxy. It has a wide variety of +Squid3_ is a caching and forwarding HTTP web proxy. It has a wide variety of uses, including speeding up a web server by caching repeated requests, caching web, DNS and other computer network lookups for a group of people sharing network resources, and aiding security by filtering traffic. Although @@ -149,4 +149,5 @@ So sometimes it is useful to bypass a transparent proxy: (This can be useful when a called service has many and/or often changing destination addresses - e.g. Netflix.) -.. include:: references.rst +.. _Squid3: http://www.squid-cache.org/ +.. _Squidguard: http://www.squidguard.org/ diff --git a/docs/system/config-management.rst b/docs/system/config-management.rst index df2a80aa..9d65adb3 100644 --- a/docs/system/config-management.rst +++ b/docs/system/config-management.rst @@ -13,7 +13,7 @@ stored on a remote host for archiving/backup reasons. Change the number of commit revisions to `<number>`, the default setting for this value is to store 20 revisions locally. -.. cfgcmd:: set system config-management commit-archive location '<url>' +.. cfgcmd:: set system config-management commit-archive location <url> If you want to save all config changes to a remote destination. Set the commit-archive location. Every time a commit is successfully the diff --git a/docs/system/default-route.rst b/docs/system/default-route.rst index a46790e4..27c74188 100644 --- a/docs/system/default-route.rst +++ b/docs/system/default-route.rst @@ -5,13 +5,13 @@ Default Gateway/Route ##################### In the past (VyOS 1.1) used a gateway-address configured under the system tree -(:cfgcmd:`set system gateway-address '<address>'`), this is no longer supported +(:cfgcmd:`set system gateway-address <address>`), this is no longer supported and existing configurations are migrated to the new CLI command. Configuration ============= -.. cfgcmd:: set protocols static route 0.0.0.0/0 next-hop '<address>' +.. cfgcmd:: set protocols static route 0.0.0.0/0 next-hop <address> Specify static route into the routing table sending all non local traffic to the nexthop address `<address>`. diff --git a/docs/system/flow-accounting.rst b/docs/system/flow-accounting.rst index 4f566490..df58e1f3 100644 --- a/docs/system/flow-accounting.rst +++ b/docs/system/flow-accounting.rst @@ -4,6 +4,20 @@ Flow Accounting ############### +VyOS supports flow-accounting for both IPv4 and IPv6 traffic. The system acts +as a flow exporter, and you are free to use it with any compatible collector. + +Flows can be exported via two different protocols: NetFlow (versions 5, 9 and +10/IPFIX) and sFlow. Additionally, you may save flows to an in-memory table +internally in a router. + +.. warning:: You need to disable the in-memory table in production environments! + Using :abbr:`IMT (In-Memory Table)` may lead to heavy CPU overloading and + unstable flow-accounting behavior. + + +NetFlow / IPFIX +=============== NetFlow is a feature that was introduced on Cisco routers around 1996 that provides the ability to collect IP network traffic as it enters or exits an interface. By analyzing the data provided by NetFlow, a network administrator @@ -18,8 +32,8 @@ NetFlow) consists of three main components: * **application**: analyzes received flow data in the context of intrusion detection or traffic profiling, for example -For connectionless protocols as like ICMP and UDP, a flow is considered complete -once no more packets for this flow appear after configurable timeout. +For connectionless protocols as like ICMP and UDP, a flow is considered +complete once no more packets for this flow appear after configurable timeout. NetFlow is usually enabled on a per-interface basis to limit load on the router components involved in NetFlow, or to limit the amount of NetFlow records @@ -31,7 +45,7 @@ Configururation In order for flow accounting information to be collected and displayed for an interface, the interface must be configured for flow accounting. -.. cfgcmd:: set system flow-accounting interface '<interface>' +.. cfgcmd:: set system flow-accounting interface <interface> Configure and enable collection of flow information for the interface identified by `<interface>`. @@ -39,15 +53,41 @@ interface, the interface must be configured for flow accounting. You can configure multiple interfaces which whould participate in flow accounting. +.. note:: Will be recorded only packets/flows on **incoming** direction in + configured interfaces. + + +By default, recorded flows will be saved internally and can be listed with the +CLI command. You may disable using the local in-memory table with the command: + +.. cfgcmd:: set system flow-accounting disable-imt + +Internally, in flow-accounting processes exist a buffer for data exchanging +between core process and plugins (each export target is a separated plugin). If +you have high traffic levels or noted some problems with missed records or +stopping exporting, you may try to increase a default buffer size (10 MiB) with +the next command: + +.. cfgcmd:: set system flow-accounting buffer-size <buffer size> + +In case, if you need to catch some logs from flow-accounting daemon, you may +configure logging facility: + +.. cfgcmd:: set system flow-accounting syslog-facility <facility> + + Flow Export ----------- In addition to displaying flow accounting information locally, one can also exported them to a collection server. -.. cfgcmd:: set system flow-accounting netflow version '<version>' +NetFlow +^^^^^^^ + +.. cfgcmd:: set system flow-accounting netflow version <version> - There are multiple versions available for the NetFlo data. The `<version>` + There are multiple versions available for the NetFlow data. The `<version>` used in the exported flow data can be configured here. The following versions are supported: @@ -55,20 +95,20 @@ exported them to a collection server. * **9** - NetFlow version 9 (default) * **10** - :abbr:`IPFIX (IP Flow Information Export)` as per :rfc:`3917` -.. cfgcmd:: set system flow-accounting netflow server '<address>' +.. cfgcmd:: set system flow-accounting netflow server <address> Configure address of NetFlow collector. NetFlow server at `<address>` can be both listening on an IPv4 or IPv6 address. -.. cfgcmd:: set system flow-accounting netflow source-ip '<address>' +.. cfgcmd:: set system flow-accounting netflow source-ip <address> IPv4 or IPv6 source address of NetFlow packets -.. cfgcmd:: set system flow-accounting netflow engine-id '<id>' +.. cfgcmd:: set system flow-accounting netflow engine-id <id> NetFlow engine-id which will appear in NetFlow data. The range is 0 to 255. -.. cfgcmd:: set system flow-accounting netflow sampling-rate '<rate>' +.. cfgcmd:: set system flow-accounting netflow sampling-rate <rate> Use this command to configure the sampling rate for flow accounting. The system samples one in every `<rate>` packets, where `<rate>` is the value @@ -80,11 +120,37 @@ exported them to a collection server. Per default every packet is sampled (that is, the sampling rate is 1). -.. cfgcmd:: set system flow-accounting netflow timeout expiry interval '<interval>' +.. cfgcmd:: set system flow-accounting netflow timeout expiry interval <interval> Specifies the interval at which Netflow data will be sent to a collector. As per default, Netflow data will be sent every 60 seconds. + You may also additionally configure timeouts for different types of + connections. + +.. cfgcmd:: set system flow-accounting netflow max-flows <n> + + If you want to change the maximum number of flows, which are tracking + simultaneously, you may do this with this command (default 8192). + +sFlow +^^^^^ +.. cfgcmd:: set system flow-accounting sflow server <address> + + Configure address of sFlow collector. sFlow server at `<address>` can + be an IPv4 or IPv6 address. But you cannot export to both IPv4 and + IPv6 collectors at the same time! + +.. cfgcmd:: set system flow-accounting sflow sampling-rate <rate> + + Enable sampling of packets, which will be transmitted to sFlow collectors. + +.. cfgcmd:: set system flow-accounting sflow agent-address <address> + + Configure a sFlow agent address. It can be IPv4 or IPv6 address, but you + must set the same protocol, which is used for sFlow collector addresses. By + default, using router-id from BGP or OSPF protocol, or the primary IP + address from the first interface. Example: -------- @@ -103,44 +169,33 @@ Operation Once flow accounting is configured on an interfaces it provides the ability to display captured network traffic information for all configured interfaces. -.. opcmd:: show flow-accounting interface '<interface>' +.. opcmd:: show flow-accounting interface <interface> Show flow accounting information for given `<interface>`. .. code-block:: none vyos@vyos:~$ show flow-accounting interface eth0 - flow-accounting for [eth0] - Src Addr Dst Addr Sport Dport Proto Packets Bytes Flows - 0.0.0.0 192.0.2.50 811 811 udp 7733 591576 0 - 0.0.0.0 192.0.2.50 811 811 udp 7669 586558 1 - 192.0.2.200 192.0.2.51 56188 22 tcp 586 36504 1 - 192.0.2.99 192.0.2.51 61636 161 udp 46 6313 4 - 192.0.2.99 192.0.2.51 61638 161 udp 42 5364 9 - 192.0.2.99 192.0.2.51 61640 161 udp 42 5111 3 - 192.0.2.200 192.0.2.51 54702 22 tcp 86 4432 1 - 192.0.2.99 192.0.2.51 62509 161 udp 24 3540 1 - 192.0.2.99 192.0.2.51 0 0 icmp 49 2989 8 - 192.0.2.99 192.0.2.51 54667 161 udp 18 2658 1 - 192.0.2.99 192.0.2.51 54996 161 udp 18 2622 1 - 192.0.2.99 192.0.2.51 63708 161 udp 18 2622 1 - 192.0.2.99 192.0.2.51 62111 161 udp 18 2622 1 - 192.0.2.99 192.0.2.51 61646 161 udp 16 1977 4 - 192.0.2.99 192.0.2.51 56038 161 udp 10 1256 1 - 192.0.2.99 192.0.2.51 55570 161 udp 6 1146 1 - 192.0.2.99 192.0.2.51 54599 161 udp 6 1134 1 - 192.0.2.99 192.0.2.51 56304 161 udp 8 1029 1 - - -.. opcmd:: show flow-accounting interface '<interface>' host '<address>' + IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES + ---------- ----------------- ----------------- ------------------------ --------------- ---------- ---------- ---------- ----- --------- ------- ------- + eth0 00:53:01:a8:28:ac ff:ff:ff:ff:ff:ff 192.0.2.2 255.255.255.255 5678 5678 udp 0 1 1 178 + eth0 00:53:01:b2:2f:34 33:33:ff:00:00:00 fe80::253:01ff:feb2:2f34 ff02::1:ff00:0 0 0 ipv6-icmp 0 2 1 144 + eth0 00:53:01:1a:b4:53 33:33:ff:00:00:00 fe80::253:01ff:fe1a:b453 ff02::1:ff00:0 0 0 ipv6-icmp 0 1 1 72 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 39 1 2064 + eth0 00:53:01:c8:33:af ff:ff:ff:ff:ff:ff 192.0.2.3 255.255.255.255 5678 5678 udp 0 1 1 154 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 146 1 9444 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 27 1 4455 + +.. opcmd:: show flow-accounting interface <interface> host <address> Show flow accounting information for given `<interface>` for a specific host only. .. code-block:: none - vyos@vyos:~$ show flow-accounting interface eth0 host 192.0.2.200 - flow-accounting for [eth0] - Src Addr Dst Addr Sport Dport Proto Packets Bytes Flows - 192.0.2.200 192.0.2.51 56188 22 tcp 586 36504 1 - 192.0.2.200 192.0.2.51 54702 22 tcp 86 4432 1 + vyos@vyos:~$ show flow-accounting interface eth0 host 192.0.2.14 + IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES + ---------- ----------------- ----------------- ----------- ---------- ---------- ---------- ---------- ----- --------- ------- ------- + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 197 2 12940 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 94 1 4924 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 36 1 5877 diff --git a/docs/system/host-information.rst b/docs/system/host-information.rst index 89f1c6ad..30efe01e 100644 --- a/docs/system/host-information.rst +++ b/docs/system/host-information.rst @@ -20,7 +20,7 @@ network and is used to distinguish one device from another on specific networks or over the internet. On the other hand this will be the name which appears on the command line prompt. -.. cfgcmd:: set system host-name '<hostname>' +.. cfgcmd:: set system host-name <hostname> Set system hostname. The hostname can be up to 63 characters. A hostname must start and end with a letter or digit, and have as interior characters @@ -36,7 +36,7 @@ unique. VyOS appends the domain name as a suffix to any unqualified name. For example, if you set the domain name `example.com`, and you would ping the unqualified name of `crux`, then VyOS qualifies the name to `crux.example.com`. -.. cfgcmd:: set system domain-name '<domain>' +.. cfgcmd:: set system domain-name <domain> Configure system domain name. A domain name must start and end with a letter or digit, and have as interior characters only letters, digits, or a hyphen. @@ -44,20 +44,20 @@ unqualified name of `crux`, then VyOS qualifies the name to `crux.example.com`. Static Hostname Mapping ======================= -How an IP address is assigned to an interface in :ref:`interfaces-addresses`. +How an IP address is assigned to an interface in :ref:`ethernet-interface`. This section shows how to statically map an IP address to a hostname for local (meaning on this VyOS instance) name resolution. -.. cfgcmd:: set system static-host-mapping host-name '<hostname>' inet '<address>' +.. cfgcmd:: set system static-host-mapping host-name <hostname> inet <address> Create a static hostname mapping which will always resolve the name `<hostname>` to IP address `<address>`. -.. cfgcmd:: set system static-host-mapping host-name '<hostname>' alias '<alias>' +.. cfgcmd:: set system static-host-mapping host-name <hostname> alias <alias> Create named `<alias>` for the configured static mapping for `<hostname>`. Thus the address configured as :cfgcmd:`set system static-host-mapping - host-name '<hostname>' inet '<address>'` can be reached via multiple names. + host-name <hostname> inet <address>` can be reached via multiple names. Multiple aliases can pe specified per host-name. diff --git a/docs/system/ntp.rst b/docs/system/ntp.rst index 0836f2fa..5fd1837f 100644 --- a/docs/system/ntp.rst +++ b/docs/system/ntp.rst @@ -33,9 +33,9 @@ in :rfc:`1305`. Configuration ============= -.. cfgcmd:: set system ntp server '<address | fqdn>' +.. cfgcmd:: set system ntp server <address> - Configure one or more servers for synchronisation. Server name cen be either + Configure one or more servers for synchronisation. Server name can be either an IP address or :abbr:`FQDN (Fully Qualified Domain Name)`. There are 3 default NTP server set. You are able to change them. @@ -44,13 +44,13 @@ Configuration * 1.pool.ntp.org * 2.pool.ntp.org -.. cfgcmd:: set system ntp listen-address '<address>' +.. cfgcmd:: set system ntp listen-address <address> Setup VyOS as an NTP responder, you must specify the `<address>` and optionally the permitted clients. Multiple listen addresses can be configured. -.. cfgcmd:: set system ntp allow-clients address '<address>' +.. cfgcmd:: set system ntp allow-clients address <address> List of networks or client addresses permitted to contact this NTP server. Multiple networks can be configured. diff --git a/docs/system/proxy.rst b/docs/system/proxy.rst index 40bdf998..8e0339a7 100644 --- a/docs/system/proxy.rst +++ b/docs/system/proxy.rst @@ -8,21 +8,21 @@ Some IT environments require the use of a proxy to connect to the Internet. Without this configuration VyOS updates could not be installed directly by using the :opcmd:`add system image` command (:ref:`update_vyos`). -.. cfgcmd:: set system proxy url '<url>' +.. cfgcmd:: set system proxy url <url> Set proxy for all connections initiated by VyOS, including HTTP, HTTPS, and FTP (anonymous ftp). -.. cfgcmd:: set system proxy port '<port>' +.. cfgcmd:: set system proxy port <port> Configure proxy port if it does not listen to the default port 80. -.. cfgcmd:: set system proxy username '<username>' +.. cfgcmd:: set system proxy username <username> Some proxys require/support the "basic" HTTP authentication scheme as per :rfc:`7617`, thus a username can be configured. -.. cfgcmd:: set system proxy password '<password>' +.. cfgcmd:: set system proxy password <password> Some proxys require/support the "basic" HTTP authentication scheme as per :rfc:`7617`, thus a password can be configured. diff --git a/docs/system/serial-console.rst b/docs/system/serial-console.rst index cd27fa21..309c6ad2 100644 --- a/docs/system/serial-console.rst +++ b/docs/system/serial-console.rst @@ -16,7 +16,7 @@ access to the console is the only way to diagnose and correct software failures. Major upgrades to the installed distribution may also require console access. -.. cfgcmd:: set system console device '<device>' +.. cfgcmd:: set system console device <device> Defines the specified device as a system console. Available console devices can be (see completion helper): @@ -25,7 +25,7 @@ Major upgrades to the installed distribution may also require console access. * ``ttyUSBX`` - USB Serial device name * ``hvc0`` - Xen console -.. cfgcmd:: set system console device '<device>' speed '<speed>' +.. cfgcmd:: set system console device <device> speed <speed> The speed (baudrate) of the console device. Supported values are: @@ -44,6 +44,6 @@ Network Console TBD. -.. cfgcmd:: set system console network '<netconXX>' +.. cfgcmd:: set system console network <netconXX> ... and many more commands ...
\ No newline at end of file diff --git a/docs/system/task-scheduler.rst b/docs/system/task-scheduler.rst index 869a0600..382da39f 100644 --- a/docs/system/task-scheduler.rst +++ b/docs/system/task-scheduler.rst @@ -11,7 +11,7 @@ use of UNIX cron_. be dangerous. Together with :ref:`command-scripting` this can be used for automating (re-)configuration. -.. cfgcmd:: set system task-scheduler task '<task>' interval '<interval>' +.. cfgcmd:: set system task-scheduler task <task> interval <interval> Specify the time interval when `<task>` should be executed. The interval is specified as number with one of the following suffixes: @@ -23,17 +23,17 @@ use of UNIX cron_. .. note:: If suffix is omitted, minutes are implied. -.. cfgcmd:: set system task-scheduler task '<task>' crontab-spec '<spec>' +.. cfgcmd:: set system task-scheduler task <task> crontab-spec <spec> Set execution time in common cron_ time format. A cron `<spec>` of ``30 */6 * * *`` would execute the `<task>` at minute 30 past every 6th hour. -.. cfgcmd:: set system task-scheduler task '<task>' executable path '<path>' +.. cfgcmd:: set system task-scheduler task <task> executable path <path> Specify absolute `<path>` to script which will be run when `<task>` is executed. -.. cfgcmd:: set system task-scheduler task '<task>' executable arguments '<args>' +.. cfgcmd:: set system task-scheduler task <task> executable arguments <args> Arguments which will be passed to the executable. diff --git a/docs/system/time-zone.rst b/docs/system/time-zone.rst index d65e1d78..025c4376 100644 --- a/docs/system/time-zone.rst +++ b/docs/system/time-zone.rst @@ -8,7 +8,7 @@ Time Zone setting is very important as e.g all your logfile entries will be based on the configured zone. Without proper time zone configuration it will be very difficult to compare logfiles from different systems. -.. cfgcmd:: set system time-zone '<timezone>' +.. cfgcmd:: set system time-zone <timezone> Specify the systems `<timezone>` as the Region/Location that best defines your location. For example, specifying US/Pacific sets the time zone to US diff --git a/docs/system/user-management.rst b/docs/system/user-management.rst index b2dd3d08..bb9a6e90 100644 --- a/docs/system/user-management.rst +++ b/docs/system/user-management.rst @@ -15,23 +15,23 @@ Authentication Dial-In User Service)` accounts are supported. Local ===== -.. cfgcmd:: set system login user '<name>' full-name "<string>" +.. cfgcmd:: set system login user <name> full-name "<string>" Create new system user with username `<name>` and real-name specified by `<string>`. -.. cfgcmd:: set system login user '<name>' authentication plaintext-password '<password>' +.. cfgcmd:: set system login user <name> authentication plaintext-password <password> Specify the plaintext password user by user `<name>` on this system. The plaintext password will be automatically transferred into a secure hashed password and not saved anywhere in plaintext. -.. cfgcmd:: set system login user '<name>' authentication encrypted-password '<password>' +.. cfgcmd:: set system login user <name> authentication encrypted-password <password> Setup encrypted password for given username. This is usefull for transferring a hashed password from system to system. -.. cfgcmd:: set system login user '<name>' group '<group>' +.. cfgcmd:: set system login user <name> group <group> Specify additional group membership for given username `<name>`. @@ -55,12 +55,12 @@ and paste it. Some terminal emulators may accidentally split this over several lines. Be attentive when you paste it that it only pastes as a single line. The third part is simply an identifier, and is for your own reference. -.. cfgcmd:: set system login user '<username>' authentication public-keys '<identifier>' key '<key>' +.. cfgcmd:: set system login user <username> authentication public-keys <identifier> key <key> Assign the SSH public key portion `<key>` identified by per-key `<identifier>` to the local user `<username>`. -.. cfgcmd:: set system login user '<username>' authentication public-keys '<identifier>' type '<type>' +.. cfgcmd:: set system login user <username> authentication public-keys <identifier> type <type> Every SSH public key portion referenced by `<identifier>` requires the configuration of the `<type>` of public-key used. This type can be any of: @@ -75,7 +75,7 @@ The third part is simply an identifier, and is for your own reference. .. note:: You can assign multiple keys to the same user by using a unique identifier per SSH key. -.. cfgcmd:: loadkey '<username>' '<location>' +.. cfgcmd:: loadkey <username> <location> SSH keys can not only be specified on the command-line but also loaded for a given user with `<username>` from a file pointed to by `<location>.` Keys @@ -113,17 +113,17 @@ Dial-In User Service)` servers as backend for user authentication. Configuration ------------- -.. cfgcmd:: set system login radius server '<address>' secret '<secret>' +.. cfgcmd:: set system login radius server <address> secret <secret> Specify the `<address>` of the RADIUS server user with the pre-shared-secret given in `<secret>`. Multiple servers can be specified. -.. cfgcmd:: set system login radius server '<address>' port '<port>' +.. cfgcmd:: set system login radius server <address> port <port> Configure the discrete port under which the RADIUS server can be reached. This defaults to 1812. -.. cfgcmd:: set system login radius server '<address>' timeout '<timeout>' +.. cfgcmd:: set system login radius server <address> timeout <timeout> Setup the `<timeout>` in seconds when querying the RADIUS server. @@ -132,7 +132,7 @@ Configuration the attribute you will only get regular, non privilegued, system users. -.. cfgcmd:: set system login radius source-address '<address>' +.. cfgcmd:: set system login radius source-address <address> RADIUS servers could be hardened by only allowing certain IP addresses to connect. As of this the source address of each RADIUS query can be @@ -148,12 +148,12 @@ Login Banner You are able to set post-login or pre-login banner messages to display certain information for this system. -.. cfgcmd:: set system login banner pre-login '<message>' +.. cfgcmd:: set system login banner pre-login <message> Configure `<message>` which is shown during SSH connect and before a user is logged in. -.. cfgcmd:: set system login banner post-login '<message>' +.. cfgcmd:: set system login banner post-login <message> Configure `<message>` which is shown after user has logged in to the system. diff --git a/docs/vpn/l2tp.rst b/docs/vpn/l2tp.rst index 107a42d3..768e5acd 100644 --- a/docs/vpn/l2tp.rst +++ b/docs/vpn/l2tp.rst @@ -19,7 +19,6 @@ with native Windows and Mac VPN clients): set vpn ipsec nat-networks allowed-network 0.0.0.0/0 set vpn l2tp remote-access outside-address 192.0.2.2 - set vpn l2tp remote-access outside-nexthop 192.168.255.1 set vpn l2tp remote-access client-ip-pool start 192.168.255.2 set vpn l2tp remote-access client-ip-pool stop 192.168.255.254 set vpn l2tp remote-access ipsec-settings authentication mode pre-shared-secret @@ -27,8 +26,7 @@ with native Windows and Mac VPN clients): set vpn l2tp remote-access authentication mode local set vpn l2tp remote-access authentication local-users username test password 'test' -In the example above an external IP of 192.0.2.2 is assumed. Nexthop IP address -192.168.255.1 uses as client tunnel termination point. +In the example above an external IP of 192.0.2.2 is assumed. If a local firewall policy is in place on your external interface you will need to allow the ports below: @@ -100,7 +98,6 @@ Below is an example to configure a LNS: .. code-block:: none set vpn l2tp remote-access outside-address 192.0.2.2 - set vpn l2tp remote-access outside-nexthop 192.168.255.1 set vpn l2tp remote-access client-ip-pool start 192.168.255.2 set vpn l2tp remote-access client-ip-pool stop 192.168.255.254 set vpn l2tp remote-access lns shared-secret 'secret' @@ -108,8 +105,7 @@ Below is an example to configure a LNS: set vpn l2tp remote-access authentication mode local set vpn l2tp remote-access authentication local-users username test password 'test' -The example above uses 192.0.2.2 as external IP address, the nexthop is supposed -to be 192.168.255.1 and is used as client termination point. A LAC normally +The example above uses 192.0.2.2 as external IP address. A LAC normally requires an authentication password, which is set in the example configuration to ``lns shared-secret 'secret'``. This setup requires the Compression Control Protocol (CCP) being disabled, the command ``set vpn l2tp remote-access ccp-disable`` @@ -129,7 +125,6 @@ The rate-limit is set in kbit/sec. .. code-block:: none set vpn l2tp remote-access outside-address 192.0.2.2 - set vpn l2tp remote-access outside-nexthop 192.168.255.1 set vpn l2tp remote-access client-ip-pool start 192.168.255.2 set vpn l2tp remote-access client-ip-pool stop 192.168.255.254 set vpn l2tp remote-access authentication mode local diff --git a/docs/vpn/openvpn.rst b/docs/vpn/openvpn.rst index 69961f0c..cbb89fbe 100644 --- a/docs/vpn/openvpn.rst +++ b/docs/vpn/openvpn.rst @@ -441,8 +441,8 @@ Options ======= We do not have CLI nodes for every single OpenVPN options. If an option is -missing, a feature request should be opened at https://phabricator.vyos.net so -all users can benefit from it. +missing, a feature request should be opened at Phabricator_ so all users can +benefit from it (see :ref:`issues_features`). If you are a hacker or want to try on your own we support passing raw OpenVPN options to OpenVPN. @@ -460,3 +460,5 @@ Will add ``push "keepalive 1 10"`` to the generated OpenVPN config file. .. note:: Sometimes option lines in the generated OpenVPN configurarion require quotes. This is done through a hack on our config generator. You can pass quotes using the ``"`` statement. + +.. include:: ../common-references.rst |