vyos/vyos-documentation
1
0
Fork 0
mirror of https://github.com/vyos/vyos-documentation.git synced 2025-10-26 08:41:46 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into newdirectives

Browse Source
This commit is contained in:
Robert Göhler 2020-01-04 14:12:53 +01:00
commit 52595595f7
57 changed files with 2568 additions and 1405 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/appendix/examples/dmvpn.rst
View File

@ -17,7 +17,7 @@ Configuration
set interfaces tunnel tun100 multicast 'enable' set interfaces tunnel tun100 multicast 'enable'
set interfaces tunnel tun100 parameters ip key '1' 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 holding-time '300'
set protocols nhrp tunnel tun100 multicast 'dynamic' set protocols nhrp tunnel tun100 multicast 'dynamic'
set protocols nhrp tunnel tun100 redirect set protocols nhrp tunnel tun100 redirect
@ -43,7 +43,7 @@ Configuration
set vpn ipsec ipsec-interfaces interface 'eth0' set vpn ipsec ipsec-interfaces interface 'eth0'
set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' 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 bind tunnel 'tun100'
set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB'
set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB'

243
docs/appendix/release-notes.rst Normal file
View File

@ -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>`_.

140
docs/appendix/releasenotes.rst
View File

@ -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>`_.

6
docs/appendix/vyos-on-baremetal.rst
View File

@ -107,7 +107,7 @@ VyOS 1.2 (crux)
--------------- ---------------
Depending on the VyOS versions you intend to install there is a difference in 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. 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 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. implemented.
Simply proceed with a regular image installation as described in Simply proceed with a regular image installation as described in
@ -246,8 +246,6 @@ Desktop
:alt: APU4C4 desktop back :alt: APU4C4 desktop back
.. _Rufus: https://rufus.ie/ .. _Rufus: https://rufus.ie/
.. _T1327: https://phabricator.vyos.net/T1327
Qotom Q355G4 Qotom Q355G4
************ ************

3
docs/common-references.rst Normal file
View File

@ -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/

13
docs/conf.py
View File

@ -16,6 +16,8 @@ import os
import sys import sys
sys.path.append(os.path.abspath("./_ext")) sys.path.append(os.path.abspath("./_ext"))
from docutils import nodes, utils
from docutils.parsers.rst.roles import set_classes
# -- Project information ----------------------------------------------------- # -- Project information -----------------------------------------------------
@ -174,5 +176,16 @@ texinfo_documents = [
'Miscellaneous'), '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): def setup(app):
pass pass

562
docs/configuration-overview.rst
View File

@ -4,131 +4,129 @@
Configuration Overview Configuration Overview
###################### ######################
VyOS makes use of a unified configuration file for all system configuration: VyOS makes use of a unified configuration file for the entire systems
`config.boot`. This allows for easy template creation, backup, and replication configuration: ``/config/config.boot``. This allows easy template creation,
of system configuration. backup, and replication of system configuration. A sytem can thus also be
easily cloned by simply copying the required configuration files.
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.
Terminology Terminology
=========== ===========
A VyOS system has three major types of configurations: 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.
The active or running configuration is the system configuration that is loaded * **Working** - is the configuration which is currently being modified in
and currently being used by VyOS. Any change in the configuration will have to configuration mode. Changes made to the working configuration do not go into
be committed to belong to the active/running configuration. effect until the changes are committed with the :cfgcmd:`commit` command. At
which time the working configuration will become the active or running
configuration.
Working * **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 working configuration is the configuration which is currently being Work the Config
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.
Saved .. opcmd:: show configuration
-----
A saved configuration is a configuration saved to a file using the ``save`` View the current active configuration, also known as the running
command. It allows you to keep safe a configuration for future uses. There can configuration.
be multiple configuration files. The default or "boot" configuration is saved
and loaded from the file config.boot. .. 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.
.. 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 '$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'
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 Navigating
========== ==========
When entering the configuration mode you are navigating inside the tree When entering the configuration mode you are navigating inside the tree
structure exported in the overview above, to enter configuration mode enter 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 .. code-block:: none
@ -136,14 +134,11 @@ the command ``configure`` when in operational mode.
[edit] [edit]
vyos@vyos# 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 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 entered. You can do everything from the top level, but commands will be quite
lengthy when manually typing them. 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 .. 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 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 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 the :cfgcmd:`top` or :cfgcmd:`exit` command to go back to the top of the
also use the ``up`` command to move only one level up at a time. 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 configuration indicating line changes with ``+`` for additions, ``>`` for
replacements and ``-`` for deletions. replacements and ``-`` for deletions.
.. note:: When going into configuration mode, prompt changes from
``$`` to ``#``.
**Example:**
.. code-block:: none .. code-block:: none
vyos@vyos:~$ configure vyos@vyos:~$ configure
@ -192,7 +193,7 @@ replacements and ``-`` for deletions.
} }
It is also possible to display all `set` commands within configuration mode It is also possible to display all `set` commands within configuration mode
using ``show | commands`` using :cfgcmd:`show | commands`
.. code-block:: none .. code-block:: none
@ -210,9 +211,9 @@ configuration blocks will be displayed when entering a sub-level.
address dhcp address dhcp
hw-id 00:53:ad:44:3b:03 hw-id 00:53:ad:44:3b:03
Exiting from the configuration mode is done via the ``exit`` command from the Exiting from the configuration mode is done via the :cfgcmd:`exit` command from
top level, executing `exit` from within a sub-level takes you back to the top the top level, executing :cfgcmd:`exit` from within a sub-level takes you back
level. to the top level.
.. code-block:: none .. code-block:: none
@ -225,14 +226,13 @@ level.
Managing Managing
======== ========
The configuration is managed by the use of ``set`` and ``delete`` commands from The configuration is managed by the use of :cfgcmd:`set` and :cfgcmd:`delete`
within configuration mode. Configuration commands are flattened from the tree commands from within configuration mode. Configuration commands are flattened
into 'one-liner' commands shown in ``show configuration commands`` from from the tree into 'one-liner' commands shown in :opcmd:`show configuration
operation mode. commands` from operation mode.
These commands are also relative to the level where they are executed and all Commands are relative to the level where they are executed and all redundant
redundant information from the current level is removed from the command information from the current level is removed from the command entered.
entered.
.. code-block:: none .. code-block:: none
@ -245,197 +245,214 @@ entered.
These two commands above are essentially the same, just executed from different These two commands above are essentially the same, just executed from different
levels in the hierarchy. levels in the hierarchy.
To delete a configuration entry use the ``delete`` command, this also deletes .. cfgcmd:: delete
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.
.. 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] .. code-block:: none
vyos@vyos# delete address 192.0.2.100/24
Any change you do on the configuration, will not take effect until committed [edit interfaces ethernet eth0]
using the ``commit`` command in configuration mode. vyos@vyos# delete address 192.0.2.100/24
.. code-block:: none .. cfgcmd:: commit
vyos@vyos# commit Any change you do on the configuration, will not take effect until committed
[edit] using the :cfgcmd:`commit` command in configuration mode.
vyos@vyos# exit
Warning: configuration changes have not been saved.
vyos@vyos:~$
In order to preserve configuration changes upon reboot, the configuration must .. code-block:: none
also be saved once applied. This is done using the ``save`` command in
configuration mode.
.. code-block:: none vyos@vyos# commit
[edit]
vyos@vyos# exit
Warning: configuration changes have not been saved.
vyos@vyos:~$
vyos@vyos# save .. cfgcmd:: save
Saving configuration to '/config/config.boot'...
Done
Configuration mode can not be exited while uncommitted changes exist. To exit In order to preserve configuration changes upon reboot, the configuration
configuration mode without applying changes, the exit discard command can be must also be saved once applied. This is done using the :cfgcmd:`save`
used. command in configuration mode.
.. code-block:: none .. code-block:: none
vyos@vyos# exit vyos@vyos# save
Cannot exit: configuration modified. Saving configuration to '/config/config.boot'...
Use 'exit discard' to discard the changes and exit. Done
[edit]
vyos@vyos# exit discard
.. code-block:: none .. code-block:: none
vyos@vyos# save [tab] vyos@vyos# save [tab]
Possible completions: Possible completions:
<Enter> Save to system config file <Enter> Save to system config file
<file> Save to file on local machine <file> Save to file on local machine
scp://<user>:<passwd>@<host>/<file> Save to file on remote machine scp://<user>:<passwd>@<host>/<file> Save to file on remote machine
ftp://<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 tftp://<host>/<file> Save to file on remote machine
vyos@vyos# save tftp://192.168.0.100/vyos-test.config.boot vyos@vyos# save tftp://192.168.0.100/vyos-test.config.boot
Saving configuration to 'tftp://192.168.0.100/vyos-test.config.boot'... Saving configuration to 'tftp://192.168.0.100/vyos-test.config.boot'...
######################################################################## 100.0% ######################################################################## 100.0%
Done Done
Access from config mode .. cfgcmd:: exit [discard]
=======================
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.
All changes in the working config will thus be lost.
.. code-block:: none
vyos@vyos# exit
Cannot exit: configuration modified.
Use 'exit discard' to discard the changes and exit.
[edit]
vyos@vyos# exit discard
.. _run_opmode_from_config_mode:
Access opmode from config mode
==============================
When inside configuration mode you are not directly able to execute operational When inside configuration mode you are not directly able to execute operational
commands. commands.
Access to these commands are possible through the use of the ``run [command]`` .. cfgcmd:: run
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. 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.
.. code-block:: none Command completion and syntax help with ``?`` and ``[tab]`` will also work.
[edit] .. code-block:: none
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 [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
VyOS automatically maintains backups of previous configurations. Config Archive
==============
Local archive and revisions VyOS automatically maintains backups of every previous configurations which
--------------------------- has been comitted to the system.
Revisions are stored on disk. You can view them, compare them, and rollback to Local Archive
previous revisions if anything goes wrong. -------------
To view existing revisions, use ``show system commit`` operational mode command. Revisions are stored on disk. You can view, compare and rollback them to any
previous revisions if something goes wrong.
.. code-block:: none .. opcmd:: show system commit
vyos@vyos-test-2# run show system commit View all existing revisions on the local system.
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 .. code-block:: none
command:
.. 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
vyos@vyos# compare [tab] .. cfgcmd:: compare <saved | N> <M>
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 Compare difference in configuration revisions.
^^^^^^^^^^^^^^^^^^^
You can compare revisions with ``compare X Y`` command, where X and Y are .. code-block:: none
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# 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
vyos@vyos-test-2# compare 0 6 Revisions can be compared with :cfgcmd:`compare N M` command, where N and M
[edit interfaces] are revision numbers. The output will describe how the configuration N is
+dummy dum1 { when compared to YM indicating with a plus sign (``+``) the additional parts
+ address 10.189.0.1/31 N has when compared to M, and indicating with a minus sign (``-``) the
+} lacking parts N misses when compared to Y.
[edit interfaces ethernet eth0]
+vif 99 {
+ address 10.199.0.1/31
+}
-vif 900 {
- address 192.0.2.4/24
-}
Rolling Back Changes .. code-block:: none
^^^^^^^^^^^^^^^^^^^^
You can rollback configuration using the rollback command. This command will 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. apply the selected revision and trigger a system reboot.
.. code-block:: none .. cfgcmd:: rollback <N>
vyos@vyos# compare 1 Rollback to revision N (currently requires reboot)
[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!
Configuring the archive size .. code-block:: none
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can specify the number of revisions stored on disk with ``set system vyos@vyos# compare 1
config-management commit-revisions X``, where X is a number between 0 and 65535. [edit system]
When the number of revisions exceeds that number, the oldest revision is >host-name vyos-1
removed. [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, Remote Archive
and SFTP servers are supported. --------------
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 * scp://<user>:<passwd>@<host>/<dir>
location URL`` command, e.g. ``set system config-management commit-archive * sftp://<user>:<passwd>@<host>/<dir>
location tftp://10.0.0.1/vyos``. * ftp://<user>:<passwd>@<host>/<dir>
* tftp://<host>/<dir>
Restore Default Restore Default
=============== ===============
@ -447,10 +464,11 @@ default one, you can enter the following command in configuration mode:
load /opt/vyatta/etc/config.boot.default load /opt/vyatta/etc/config.boot.default
You will be asked if you want to continue. If you accept, You will be asked if you want to continue. If you accept, you will have to use
you will have to use `commit` if you want to make the changes active. :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 .. 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 want to copy first the config, edit it to ensure connectivity, and load the

102
docs/contributing/build-vyos.rst
View File

@ -121,6 +121,108 @@ Good luck!
or ``rolling`` image. Make sure to choose the matching container for the or ``rolling`` image. Make sure to choose the matching container for the
version of VyOS that is being built. 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: .. _upstream_packages:

6
docs/contributing/development.rst
View File

@ -486,7 +486,7 @@ GNU Preprocessor
---------------- ----------------
XML interface definition files use the `xml.in` file extension which was 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: duplicated code in areas such as:
* VIF (incl. VIF-S/VIF-C) * 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 .. _VyConf: https://github.com/vyos/vyconf/tree/master/data/schemata
.. _vyos-1x: https://github.com/vyos/vyos-1x/tree/current/schema .. _vyos-1x: https://github.com/vyos/vyos-1x/tree/current/schema
.. _Jinja2: https://jinja.palletsprojects.com/ .. _Jinja2: https://jinja.palletsprojects.com/
.. _Phabricator: https://phabricator.vyos.net/
.. _Jenkins: https://jenkins.io/ .. _Jenkins: https://jenkins.io/
.. _Dockerhub: https://hub.docker.com/u/vyos/ .. _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 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 .. _`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 .. _`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 .. _`MAC address`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/interface-mac.xml.i
.. include:: ../common-references.rst

2
docs/contributing/documentation.rst
View File

@ -215,4 +215,4 @@ URL. This is heavily used in the :ref:`release-notes` section.
.. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
.. _README.md: https://github.com/vyos/vyos-documentation/blob/master/README.md .. _README.md: https://github.com/vyos/vyos-documentation/blob/master/README.md
.. include:: ../common-references.rst .. include:: ../common-references.rst

30
docs/contributing/issues-features.rst
View File

@ -1,10 +1,14 @@
.. _issues_features: .. _issues_features:
#######################
Issues/Feature requests Issues/Feature requests
======================= #######################
.. _bug_report:
Bug Report/Issue Bug Report/Issue
---------------- ================
Issues or bugs are found in any software project. VyOS is not an exception. 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 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. will believe that everything is working correctly.
I have found a bug, what should I do? 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 When you believe you have found a bug, it is always a good idea to verify the
issue prior to opening a bug request. 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_ * Get community support via Slack_ or our Forum_
Ensure the problem is reproducible Ensure the problem is reproducible
********************************** ----------------------------------
When you are able to verify that it is actually a bug, spend some time to 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. 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`` * What commands did you use? Use e.g. ``run show configuration commands``
Include output Include output
************** --------------
The output you get when you find a bug can provide lots of information. If you 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 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. also contain information that is helpful for the development team.
Report a Bug Report a Bug
************ ------------
Create an account on VyOS Phabricator_. Phabricator_ is located at In order to open up a bug-report/feature request you need to create yourself
https://phabricator.vyos.net. To create a bug-report use the quick link in the an account on VyOS Phabricator_. On the left side of the specific project (VyOS
left side under the specific project. 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 * Provide as much information as you can
* Which version of VyOS are you using? ``run show version`` * Which version of VyOS are you using? ``run show version``
* How can we reproduce this Bug? * How can we reproduce this Bug?
.. _feature_request:
Feature Request Feature Request
--------------- ===============
You have an idea of how to make VyOS better or you are in need of a specific 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 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 .. _documentation: https://docs.vyos.io
.. _Slack: https://slack.vyos.io .. _Slack: https://slack.vyos.io
.. _Forum: https://forum.vyos.io .. _Forum: https://forum.vyos.io
.. _Phabricator: https://phabricator.vyos.net
.. include:: ../common-references.rst

6
docs/image-mgmt.rst
View File

@ -48,9 +48,11 @@ configured to be the default (:opcmd:`set system image default-boot`).
system image` 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 .. code-block:: none

5
docs/index.rst
View File

@ -23,7 +23,7 @@ VyOS User Guide
:maxdepth: 2 :maxdepth: 2
configuration-overview configuration-overview
interfaces/index interfaces/basic-index
system/basic-index system/basic-index
image-mgmt image-mgmt
@ -33,6 +33,7 @@ VyOS User Guide
:name: advanced :name: advanced
:maxdepth: 2 :maxdepth: 2
interfaces/advanced-index
services/index services/index
system/index system/index
firewall firewall
@ -51,7 +52,7 @@ VyOS User Guide
:name: appendix :name: appendix
:maxdepth: 2 :maxdepth: 2
appendix/releasenotes appendix/release-notes
appendix/examples/index appendix/examples/index
appendix/cmd-index appendix/cmd-index
appendix/commandtree/index appendix/commandtree/index

94
docs/install.rst
View File

@ -7,14 +7,14 @@ Installation
Requirements Requirements
============ ============
The recommended system requirements are 512 MiB RAM and 2 GiB storage. Depending The recommended system requirements are 512 MiB RAM and 2 GiB storage.
on your use you might need additional RAM and CPU resources e.g. when having Depending on your use you might need additional RAM and CPU resources e.g.
multiple BGP full tables in your system. 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 Registered subscribers can log into https://support.vyos.io/ to have access to
@ -28,23 +28,29 @@ ISOs.
Building from source Building from source
---------------------- ----------------------
Non-subscribers can get the LTS release by building it from source. Instruction Non-subscribers can always get the LTS release by building it from source.
can be found here: :ref:`build` and the source repository is available Instruction can be found in the :ref:`build` section of this manual. VyOS
for everyone at https://github.com/vyos/vyos-build. source code repository is available for everyone at
https://github.com/vyos/vyos-build.
Rolling Release Rolling Release
--------------- ---------------
Non-subscribers and subscribers can download bleeding-edge VyOS rolling images Everyone can download bleeding-edge VyOS rolling images from:
from: https://downloads.vyos.io/ https://downloads.vyos.io/
The following link will always fetch the most updated AMD64 image of the .. note:: Rolling releases contain all the latest enhancements and fixes. This
current branch: 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 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 This subsection and the following one applies to downloaded LTS images, for
other versions please jump to :ref:`Install`. other versions please jump to :ref:`Install`.
@ -164,12 +170,12 @@ Finally, verify the authencity of the downloaded image:
.. _Install: .. _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 .. code-block:: none
@ -251,34 +257,34 @@ the provided default credentials.
Setting up grub: OK Setting up grub: OK
Done! 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 .. code-block:: none
vyos@vyos:~$ reboot vyos@vyos:~$ reboot
Proceed with reboot? (Yes/No) [No] Yes Proceed with reboot? (Yes/No) [No] Yes
.. _PXE Install: PXE Boot
--------
PXE Install
-----------
VyOS can also be installed through PXE. This is a more complex installation VyOS can also be installed through PXE. This is a more complex installation
method which allows deploying VyOS through the network. method which allows deploying VyOS through the network.
Requirements **Requirements**
^^^^^^^^^^^^
* **Clients** (where VyOS is to be installed) **with a PXE-enabled NIC** * :ref:`dhcp-server`
* A **DHCP server** * :ref:`tftp-server`
* A **TFTP server** * Webserver (HTTP) - optional, but we will use it to speed up intallation
* A **HTTP server** (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)
* The **VyOS ISO** image to be installed (do not use images prior to VyOS 1.2.3) * ``pxelinux.0``, ``ldlinux.c32`` from SYSLINUX_
* The ``pxelinux.0`` and ``ldlinux.c32`` files from the Syslinux distribution (https://mirrors.edge.kernel.org/pub/linux/utils/boot/syslinux/)
https://mirrors.edge.kernel.org/pub/linux/utils/boot/syslinux/
Step 1: DHCP
^^^^^^^^^^^^ Configuration
^^^^^^^^^^^^^
DHCP
""""
Configure DHCP server to provide the client with: 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: .. _install_from_tftp:
Step 2: TFTP TFTP
^^^^^^^^^^^^ """"
Configure a TFTP server so that it serves the following: 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 \ APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence \
noautologin nonetworking fetch=http://address:8000/filesystem.squashfs noautologin nonetworking fetch=http://address:8000/filesystem.squashfs
Step 3: HTTP HTTP
^^^^^^^^^^^^ """"
As you read in the configuration file, we are sending ``filesystem.squashfs`` 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 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 file. The file can be found inside the ``/live`` directory of the extracted
contents of the ISO file. contents of the ISO file.
Edit the configuration file at the :ref:`install_from_tftp` so that it shows the Edit the configuration file at the :ref:`install_from_tftp` so that it shows
correct URL at ``fetch=http://address/filesystem.squashfs``. Then restart 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 TFTP service. If you are using VyOS as your TFTP Server, you can restart
the service with ``sudo service tftpd-hpa 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 .. _`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 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 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 Once finished you will be able to proceed with the ``install image`` command as
in a regular VyOS installation. in a regular VyOS installation.
.. _SYSLINUX: http://www.syslinux.org/

175
docs/interfaces/addresses.rst
View File

@ -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

19
docs/interfaces/advanced-index.rst Normal file
View File

@ -0,0 +1,19 @@
.. _network-interfaces:
##################
Network Interfaces
##################
.. toctree::
:maxdepth: 1
dummy
bridge
bond
l2tpv3
wireless
tunnel
vlan
qinq
vxlan
geneve

12
docs/interfaces/basic-index.rst Normal file
View File

@ -0,0 +1,12 @@
.. _basic_network-interfaces:
################
Basic Interfaces
################
.. toctree::
:maxdepth: 1
ethernet
loopback
pppoe

394
docs/interfaces/bond.rst
View File

@ -1,72 +1,362 @@
.. _bond-interface: .. _bond-interface:
####
Bond Bond
---- ####
You can combine (aggregate) 2 or more physical interfaces into a single The bonding interface provides a method for aggregating multiple network
logical one. It's called bonding, or LAG, or ether-channel, or port-channel. 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' -------
You are able to choose a hash policy: .. cfgcmd:: set interfaces bonding <interface> address <address | dhcp | dhcpv6>
.. code-block:: none Configure interface `<interface>` with one or more interface addresses.
vyos@vyos# set interfaces bonding bond0 hash-policy * **address** can be specified multiple times as IPv4 and/or IPv6 address,
Possible completions: e.g. 192.0.2.1/24 and/or 2001:db8::1/64
layer2 use MAC addresses to generate the hash (802.3ad) * **dhcp** interface address is received by DHCP from a DHCP server on this
layer2+3 combine MAC address and IP address to make hash segment.
layer3+4 combine IP address and port to make hash * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 server on
this segment.
For example:
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
This algorithm will place all traffic to a particular network peer on
the same slave.
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 .. code-block:: none
# Create bonding interface bond0 with 802.3ad LACP
set interfaces bonding bond0 hash-policy 'layer2' 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 # Add the required vlans and IPv4 addresses on them
(don't forget to setup it on the other end of these links): 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 mode '802.3ad'
or some other modes:
.. 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:
.. code-block:: none
set interfaces bonding bond0 member interface eth0
set interfaces bonding bond0 member interface eth1 set interfaces bonding bond0 member interface eth1
set interfaces bonding bond0 member interface eth2
After a commit you may treat bond0 as almost a physical interface (you can't Cisco
change its` duplex, for example) and assign IPs or VIFs on it. ^^^^^
You may check the result: An example configuration for a Cisco PortChannel to VyOS would be nice
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 .. code-block:: none
vyos@vyos# run sh interfaces bonding # 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
# Create trunk with 2 member interfaces (interface 1 and 2) and LACP
trunk 1-2 Trk1 LACP
# Add the required vlans to the trunk
vlan 10 tagged Trk1
vlan 100 tagged Trk1
Operation
#########
.. code-block:: none
vyos@vyos:~$ show interfaces bonding
Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
Interface IP Address S/L Description Interface IP Address S/L Description
--------- ---------- --- ----------- --------- ---------- --- -----------

324
docs/interfaces/bridge.rst
View File

@ -1,112 +1,254 @@
.. _bridge-interface: .. _bridge-interface:
######
Bridge Bridge
------ ######
Interfaces in VyOS can be bridged together to provide software switching of A Bridge is a way to connect two Ethernet segments together in a protocol
Layer-2 traffic. 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 Configuration
we create a bridge named br100 with eth1 and eth2 as the bridge member ports. #############
Address
-------
.. cfgcmd:: set interfaces bridge <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 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
.. cfgcmd:: set interfaces bridge <interface> ipv6 address autoconf
.. include:: common-ipv6-addr-autoconf.txt
.. 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.
.. code-block:: none
set interfaces bridge br0 ipv6 address eui64 2001:db8:beef::/64
.. cfgcmd:: set interfaces bridge <interface> aging <time>
MAC address aging `<time`> in seconds (default: 300).
.. cfgcmd:: set interfaces bridge <interface> max-age <time>
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>
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.
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 .. code-block:: none
set interfaces bridge 'br100' 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 eth1
set interfaces bridge br100 member interface eth2 set interfaces bridge br100 member interface eth2.10
Each bridge member can be assiged a port cost and priority using the following
commands:
.. code-block:: none
set interfaces bridge br100 member interface eth1 cost 10
set interfaces bridge br100 member interface eth1 priority 1024
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
set interfaces bridge br100 address '192.168.100.1/24'
set interfaces bridge br100 address '2001:db8:100::1/64'
Example Result:
.. code-block:: none
bridge br100 {
address 192.168.100.1/24
address 2001:db8:100::1/64
member {
interface eth1 {
cost 10
priority 1024
}
interface eth2 {
}
}
}
[...]
In addition to normal IP interface configuration, bridge interfaces support
Spanning-Tree Protocol. STP is disabled by default.
.. note:: Please use caution when introducing spanning-tree protocol on a
network as it may result in topology changes.
To enable spanning-tree use the `set interfaces bridge <name> stp` command:
.. code-block:: none
set interfaces bridge br100 stp set interfaces bridge br100 stp
STP `priority`, `forwarding-delay`, `hello-time`, and `max-age` can be This results in the active configuration:
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:
.. code-block:: none .. code-block:: none
vyos@vyos:~$ show bridge vyos@vyos# show interfaces bridge br100
bridge name bridge id STP enabled interfaces address 192.0.2.1/24
br100 0000.000c29443b19 yes eth1.100 address 2001:db8::ffff/64
member {
interface eth1 {
}
interface eth2.10 {
}
}
stp
If spanning-tree is enabled, the `show bridge <name> spanning-tree` command
can be used to show STP configuration:
.. code-block:: none Operation
=========
vyos@vyos:~$ show bridge br100 spanning-tree .. opcmd:: show bridge
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) The `show bridge` operational command can be used to display configured
port id 8001 state forwarding bridges:
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 .. code-block:: none
`show bridge <name> macs` command:
.. code-block:: none vyos@vyos:~$ show bridge
bridge name bridge id STP enabled interfaces
br100 8000.0050569d11df yes eth1
eth2.10
vyos@vyos:~$ show bridge br100 macs .. opcmd:: show bridge <name> spanning-tree
port no mac addr is local? ageing timer
1 00:53:29:44:3b:19 yes 0.00 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

12
docs/interfaces/common-ipv6-addr-autoconf.txt Normal file
View File

@ -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.

99
docs/interfaces/dummy.rst
View File

@ -1,25 +1,90 @@
.. _dummy-interface: .. _dummy-interface:
#####
Dummy Dummy
----- #####
Dummy interfaces are much like the loopback interface, except you can have The dummy interface is really a little exotic, but rather useful nevertheless.
as many as you want. Dummy interfaces can be used as interfaces that always Dummy interfaces are much like the :ref:`loopback-interface` interface, except
stay up (in the same fashion to loopbacks in Cisco IOS), or for testing you can have as many as you want.
purposes.
Configuration commands: .. 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.
.. code-block:: none .. 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
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

268
docs/interfaces/ethernet.rst
View File

@ -1,72 +1,226 @@
.. _ethernet-interface: .. _ethernet-interface:
########
Ethernet Ethernet
-------- ########
Ethernet interfaces allow for the configuration of speed, duplex, and hw-id Configuration
(MAC address). Below is an example configuration: #############
.. code-block:: none Address
-------
set interfaces ethernet eth1 address '192.168.0.1/24' .. cfgcmd:: set interfaces ethernet <interface> address <address | dhcp | dhcpv6>
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: 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.
ethernet eth1 { Example:
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: .. code-block:: none
* ``show interfaces ethernet <name> physical`` set interfaces ethernet eth0 address 192.0.2.1/24
* ``show interfaces ethernet <name> statistics`` 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
Statistics available are driver dependent. .. cfgcmd:: set interfaces ethernet <interface> ipv6 address autoconf
.. code-block:: none .. include:: common-ipv6-addr-autoconf.txt
vyos@vyos:~$ show interfaces ethernet eth0 physical .. cfgcmd:: set interfaces ethernet <interface> ipv6 address eui64 <prefix>
Settings for eth0:
Supported ports: [ TP ] :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in
Supported link modes: 10baseT/Half 10baseT/Full :rfc:`4291` allows a host to assign iteslf a unique 64-Bit IPv6 address.
100baseT/Half 100baseT/Full
1000baseT/Full .. code-block:: none
Supports auto-negotiation: Yes
Advertised link modes: 10baseT/Half 10baseT/Full set interfaces ethernet eth0 ipv6 address eui64 2001:db8:beef::/64
100baseT/Half 100baseT/Full
1000baseT/Full Speed/Duplex
Advertised pause frame use: No ------------
Advertised auto-negotiation: Yes
Speed: 1000Mb/s .. cfgcmd:: set interfaces ethernet <interface> duplex <auto | full | half>
Duplex: Full
Port: Twisted Pair Configure physical interface duplex setting.
PHYAD: 0
Transceiver: internal * auto - interface duplex setting is auto-negotiated
Auto-negotiation: on * full - always use full-duplex
MDI-X: Unknown * half - always use half-duplex
Supports Wake-on: d
Wake-on: d VyOS default will be `auto`.
Current message level: 0x00000007 (7)
Link detected: yes .. cfgcmd:: set interfaces ethernet <interface> speed <auto | 10 | 100 | 1000 | 2500 | 5000 | 10000 | 25000 | 40000 | 50000 | 100000>
driver: e1000
version: 7.3.21-k8-NAPI Configure physical interface speed setting.
firmware-version:
bus-info: 0000:02:01.0 * 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
vyos@vyos:~$ show interfaces ethernet eth0 statistics
NIC statistics:
rx_packets: 3530
tx_packets: 2179
[...]

3
docs/interfaces/geneve.rst
View File

@ -32,6 +32,9 @@ Geneve Header:
| Variable Length Options | | Variable Length Options |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Configuration
=============
.. cfgcmd:: set interfaces geneve gnv0 address '192.0.2.2/24' .. cfgcmd:: set interfaces geneve gnv0 address '192.0.2.2/24'
Create GENEVE tunnel listening on local address `192.0.2.2/24`. Create GENEVE tunnel listening on local address `192.0.2.2/24`.

62
docs/interfaces/index.rst
View File

@ -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

75
docs/interfaces/loopback.rst Normal file
View File

@ -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

40
docs/interfaces/pppoe.rst
View File

@ -1,7 +1,8 @@
.. _pppoe-interface: .. _pppoe-interface:
#####
PPPoE PPPoE
===== #####
:abbr:`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol :abbr:`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol
for encapsulating PPP frames inside Ethernet frames. It appeared in 1999, 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. predominately via the PAP protocol and less often via CHAP.
Operating Modes Operating Modes
--------------- ===============
VyOS supports setting up PPPoE in two different ways to a PPPoE internet 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 connection. This is due to most ISPs provide a modem that is also a wireless
router. router.
Home Users Home Users
********** ----------
In this method, the DSL Modem/Router connects to the ISP for you with your 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` 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. tunnel features.
Business Users Business Users
************** --------------
In order to have full control and make use of multiple static public IP 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 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 (Modem/Router) just acts to translate your messages in a way that
vDSL/aDSL understands. vDSL/aDSL understands.
Configuration Example Example
~~~~~~~~~~~~~~~~~~~~~ =======
Requirements: 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 set interfaces ethernet eth0 pppoe 0 firewall out name NET-OUT
VLAN Example VLAN Example
++++++++++++ ------------
Some recent ISPs require you to build the PPPoE connection through a VLAN 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 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' set interfaces ethernet eth0 vif 7 pppoe 0 password 'secret'
Troubleshooting Troubleshooting
--------------- ===============
.. opcmd:: disconnect interface <interface> .. opcmd:: disconnect interface <interface>
Test disconnecting given connection-oriented interface. `<interface>` can be Test disconnecting given connection-oriented interface. `<interface>` can be
``pppoe0`` as example. ``pppoe0`` as example.
.. opcmd:: connect interface <interface> .. opcmd:: connect interface <interface>
Test connecting given connection-oriented interface. `<interface>` can be Test connecting given connection-oriented interface. `<interface>` can be
``pppoe0`` as example. ``pppoe0`` as example.
.. opcmd:: show interfaces pppoe <interface> .. opcmd:: show interfaces pppoe <interface>
Check PPPoE connection logs with the following command which shows the current Check PPPoE connection logs with the following command which shows the
statistics, status and some of the settings (i.e. MTU) for the current current statistics, status and some of the settings (i.e. MTU) for the
connection on <interface> (e.g. ``pppoe0``) current connection on <interface> (e.g. ``pppoe0``)
.. opcmd:: show interfaces pppoe <interface> log .. opcmd:: show interfaces pppoe <interface> log
Show entire log for the PPPoE connection starting with the oldest data. Scroll Show entire log for the PPPoE connection starting with the oldest data.
down with the <space> key to reach the end where the current data is. Scroll down with the <space> key to reach the end where the current data is.
.. opcmd:: show interfaces pppoe <interface> log tail .. opcmd:: show interfaces pppoe <interface> log tail
Shows the same log as without the 'tail' option but start with the last few 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`` lines and continues to show added lines until you exit with ``Ctrl + x``

209
docs/interfaces/vxlan.rst
View File

@ -1,7 +1,8 @@
.. _vxlan-interface: .. _vxlan-interface:
#####
VXLAN VXLAN
----- #####
:abbr:`VXLAN (Virtual Extensible LAN)` is a network virtualization technology :abbr:`VXLAN (Virtual Extensible LAN)` is a network virtualization technology
that attempts to address the scalability problems associated with large cloud 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 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. per VXLAN interface basis to get it working accross multiple vendors.
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.
.. 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.
.. 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 Multicast VXLAN
^^^^^^^^^^^^^^^^ ===============
Example Topology: Topology: PC4 - Leaf2 - Spine1 - Leaf3 - PC5
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 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. 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 to signal all connected devices between leafs. Unfortunately, VyOS does not yet
support this. support this.
Configuration commands Example
^^^^^^^^^^^^^^^^^^^^^^ -------
.. code-block:: none The setup is this: Leaf2 - Spine1 - Leaf3
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
Spine1 is a Cisco IOS router running version 15.4, Leaf2 and Leaf3 is each a Spine1 is a Cisco IOS router running version 15.4, Leaf2 and Leaf3 is each a
VyOS router running 1.2. VyOS router running 1.2.
@ -111,7 +182,7 @@ Topology:
Eth0 towards Spine1, IP-address 10.1.3.3/24 Eth0 towards Spine1, IP-address 10.1.3.3/24
Eth1 towards a vlan-aware switch Eth1 towards a vlan-aware switch
Spine1 Configuration: **Spine1 Configuration:**
.. code-block:: none .. code-block:: none
@ -131,10 +202,10 @@ Spine1 Configuration:
Multicast-routing is required for the leafs to forward traffic between each 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 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 Leafs so that the Spine can learn what multicast groups each Leaf expect
from. traffic from.
Leaf2 configuration: **Leaf2 configuration:**
.. code-block:: none .. code-block:: none
@ -159,7 +230,7 @@ Leaf2 configuration:
set interfaces vxlan vxlan242 link 'eth0' set interfaces vxlan vxlan242 link 'eth0'
set interfaces vxlan vxlan242 vni '242' set interfaces vxlan vxlan242 vni '242'
Leaf3 configuration: **Leaf3 configuration:**
.. code-block:: none .. 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 configuration directive to support a user-specified destination port to override
that behavior is available using the above command. 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 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 .. code-block:: none

418
docs/nat.rst
View File

@ -1,22 +1,270 @@
.. _nat: .. _nat:
###
NAT NAT
=== ###
Source 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.
Source NAT is typically referred to simply as NAT. To be more correct, what IP masquerading is a technique that hides an entire IP address space, usually
most people refer to as NAT is actually the process of **Port Address consisting of private IP addresses, behind a single IP address in another,
Translation (PAT)**, or **NAT Overload**. The process of having many internal usually public address space. The hidden addresses are changed into a single
host systems communicate to the Internet using a single or subset of IP (public) IP address as the source address of the outgoing IP packets so they
addresses. 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
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: To setup SNAT, we need to know:
* The internal IP addresses we want to translate; * The internal IP addresses we want to translate
* The outgoing interface to perform the translation on; * The outgoing interface to perform the translation on
* The external IP address to translate to. * The external IP address to translate to
In the example used for the Quick Start configuration above, we demonstrate In the example used for the Quick Start configuration above, we demonstrate
the following configuration: 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, instead allowing the operator to make the determination on how the
traffic is handled. 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 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. 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 systems to the internal address when requests are made internally. Because
many smaller networks lack DNS infrastructure, a work-around is commonly many smaller networks lack DNS infrastructure, a work-around is commonly
deployed to facilitate the traffic by NATing the request from internal hosts 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 to the source address of the internal interface on the firewall.
is commonly referred to as **NAT Reflection**, or **Hairpin NAT**.
In this example, we will be using the example Quick Start configuration above This technique is commonly referred to as NAT Reflection or Hairpin NAT.
as a starting point.
To setup a NAT reflection rule, we need to create a rule to NAT connections Example:
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 .. 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 description 'NAT Reflection: INSIDE'
set nat source rule 110 destination 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 'eth1' set nat source rule 110 outbound-interface 'eth0.10'
set nat source rule 110 source address '192.168.0.0/24' 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' set nat source rule 110 translation address 'masquerade'
Which results in a configuration of: Which results in a configuration of:
.. code-block:: none .. code-block:: none
rule 110 { vyos@vyos# show nat
description "NAT Reflection: INSIDE" destination {
destination { rule 100 {
address 192.168.0.0/24 description "Regular destination NAT from external"
} destination {
outbound-interface eth1 port 3389
source { }
address 192.168.0.0/24 inbound-interface pppoe0
} protocol tcp
translation { translation {
address masquerade 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 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 to an internal IP address and is useful for protocols which don't have the
notion of ports, such as GRE. 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 Here's an extract of a simple 1-to-1 NAT configuration with one internal and
one external interface: one external interface:
@ -272,11 +563,11 @@ NPTv6
NPTv6 stands for Network Prefix Translation. It's a form of NAT for IPv6. It's 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. 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, NPTv6 is very useful for IPv6 multihoming. It is also commonly used when the
as it prevents the need for renumbering of internal hosts when the extern prefix changes. 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: Let's assume the following network configuration:
@ -333,14 +624,18 @@ Resulting in the following ip6tables rules:
NAT before VPN NAT before VPN
-------------- --------------
Some application service providers (ASPs) operate a VPN gateway to provide access to their internal resources, Some application service providers (ASPs) operate a VPN gateway to provide
and require that a connecting organisation translate all traffic to the service provider network to a source address provided by the ASP. 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 Example Network
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
Here's one example of a network environment for an ASP. 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 .. figure:: _static/images/nat_before_vpn_topology.png
:scale: 100 % :scale: 100 %
@ -361,10 +656,11 @@ The required configuration can be broken down into 4 major pieces:
Dummy interface 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, The dummy interface allows us to have an equivalent of the Cisco IOS Loopback
but which are not actually assigned to a real network. 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: 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' set interfaces dummy dum0 address '172.29.41.89/32'
NAT Configuration NAT Configuration
***************** """""""""""""""""
.. code-block:: none .. code-block:: none
@ -389,8 +685,7 @@ NAT Configuration
set nat source rule 120 translation address '172.29.41.89' set nat source rule 120 translation address '172.29.41.89'
IPSec IKE and ESP IPSec IKE and ESP
***************** """""""""""""""""
The ASP has documented their IPSec requirements: The ASP has documented their IPSec requirements:
@ -406,7 +701,8 @@ The ASP has documented their IPSec requirements:
* DH Group 14 * 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 .. 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' set vpn ipsec ipsec-interfaces interface 'eth1'
IPSec VPN Tunnels IPSec VPN Tunnels
***************** """""""""""""""""
We'll use the IKE and ESP groups created above for this VPN. We'll use the IKE and ESP groups created above for this VPN. Because we need
Because we need access to 2 different subnets on the far side, we will need two different tunnels. access to 2 different subnets on the far side, we will need two different
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. 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 .. 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' set vpn ipsec site-to-site peer 198.51.100.243 tunnel 1 remote prefix '10.125.0.0/16'
Testing and Validation 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: Start by checking for IPSec SAs (Security Associations) with:

153
docs/quick-start.rst
View File

@ -4,17 +4,46 @@
Quick Start Quick Start
########### ###########
Below is a very basic configuration example that will provide a NAT gateway This chapter will guide you on how to get up to speed using your new VyOS
for a device with two interfaces. 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 .. code-block:: none
vyos@vyos$ configure vyos@vyos$ configure
vyos@vyos# 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 .. code-block:: none
@ -23,14 +52,31 @@ Configure network interfaces:
set interfaces ethernet eth1 address '192.168.0.1/24' set interfaces ethernet eth1 address '192.168.0.1/24'
set interfaces ethernet eth1 description 'INSIDE' 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 .. code-block:: none
set service ssh port '22' 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 .. 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 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' 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 cache-size '0'
set service dns forwarding listen-address '192.168.0.1' set service dns forwarding listen-address '192.168.0.1'
set service dns forwarding name-server '203.0.113.1' set service dns forwarding allow-from '192.168.0.0/24'
set service dns forwarding name-server '203.0.113.2'
NAT and Firewall
^^^^^^^^^^^^^^^^
Configure Source NAT for our "Inside" network. NAT
###
* Configure :ref:`source-nat` for our internal/LAN network
.. code-block:: none .. 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 source address '192.168.0.0/24'
set nat source rule 100 translation address masquerade 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 .. 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 action 'accept'
set firewall name OUTSIDE-IN rule 10 state established 'enable' set firewall name OUTSIDE-IN rule 10 state established 'enable'
set firewall name OUTSIDE-IN rule 10 state related 'enable' set firewall name OUTSIDE-IN rule 10 state related 'enable'
set firewall name OUTSIDE-LOCAL default-action 'drop' set firewall name OUTSIDE-LOCAL default-action 'drop'
set firewall name OUTSIDE-LOCAL rule 10 action 'accept' set firewall name OUTSIDE-LOCAL rule 10 action 'accept'
set firewall name OUTSIDE-LOCAL rule 10 state established 'enable' 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 protocol 'icmp'
set firewall name OUTSIDE-LOCAL rule 20 state new 'enable' set firewall name OUTSIDE-LOCAL rule 20 state new 'enable'
If you wanted to enable SSH access to your firewall from the Internet, you If you wanted to enable SSH access to your firewall from the outside/WAN
could create some additional rules to allow the traffic. 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 These rules allow SSH traffic and rate limit it to 4 requests per minute. This
blocks brute-forcing attempts: 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 count '4'
set firewall name OUTSIDE-LOCAL rule 30 recent time '60' 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 30 state new 'enable'
set firewall name OUTSIDE-LOCAL rule 31 action 'accept' 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 destination port '22'
set firewall name OUTSIDE-LOCAL rule 31 protocol 'tcp' 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# exit
vyos@vyos$ vyos@vyos$
Basic QoS
^^^^^^^^^
The traffic policy subsystem provides an interface to Linux traffic control QoS
(tc_). ###
One common use of traffic policy is to limit bandwidth for an interface. In One common use of :ref:`qos` is to limit bandwidth for an interface. In
the example below we limit bandwidth for our LAN connection to 200 Mbit the example below we limit bandwidth for our internal/LAN connection to 200
download and out WAN connection to 50 Mbit upload: Mbit/s download and our outside/WAN connection to 50 Mbit/s upload:
.. code-block:: none .. 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 bandwidth '50%'
set traffic-policy shaper WAN-OUT default ceiling '100%' set traffic-policy shaper WAN-OUT default ceiling '100%'
set traffic-policy shaper WAN-OUT default queue-type 'fair-queue' 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 bandwidth '200Mbit'
set traffic-policy shaper LAN-OUT default bandwidth '50%' 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 ceiling '100%'
set traffic-policy shaper LAN-OUT default queue-type 'fair-queue' set traffic-policy shaper LAN-OUT default queue-type 'fair-queue'
Resulting in the following configuration: Once defined, a traffic policy needs to be applied to each interface using the
.. 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
interface-level traffic-policy directive: interface-level traffic-policy directive:
.. code-block:: none .. code-block:: none
@ -169,46 +194,34 @@ interface-level traffic-policy directive:
set interfaces ethernet eth0 traffic-policy out 'WAN-OUT' set interfaces ethernet eth0 traffic-policy out 'WAN-OUT'
set interfaces ethernet eth1 traffic-policy out 'LAN-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 Security Hardening
^^^^^^^^^^^^^^^^^^ ##################
Especially if you are allowing SSH access from the Internet, there are a few Especially if you are allowing SSH remote access from the outside/WAN interface,
additional configuration steps that should be taken. 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 .. code-block:: none
set system login user myvyosuser level admin set system login user myvyosuser level admin
set system login user myvyosuser authentication plaintext-password mysecurepassword set system login user myvyosuser authentication plaintext-password mysecurepassword
Set up SSH key based authentication. For example, on Linux you'd want to run Set up :ref:`ssh_key_based_authentication`:
``ssh-keygen -t rsa``. Then the contents of ``id_rsa.pub`` would be used below:
.. code-block:: none .. 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 type ssh-rsa
set system login user myvyosuser authentication public-keys myusername@mydesktop key contents_of_id_rsa.pub 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 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 the original ``vyos`` user and probably disable password authentication for
SSH: :ref:`ssh` at all:
.. code-block:: none .. code-block:: none
delete system login user vyos delete system login user vyos
set service ssh disable-password-authentication set service ssh disable-password-authentication
Commit and save.
.. _tc: https://en.wikipedia.org/wiki/Tc_(Linux)

10
docs/routing/bgp.rst
View File

@ -159,14 +159,14 @@ BGP Router Configuration
ASN and Router ID 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 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. 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 The BGP protocol uses the AS number for detecting whether the BGP connection
is internal or external. 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 This command specifies the router-ID. If router ID is not specified it will
use the highest interface IP address. use the highest interface IP address.
@ -174,19 +174,19 @@ ASN and Router ID
Route Selection 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 This command specifies that the length of confederation path sets and
sequences should should be taken into account during the BGP best path sequences should should be taken into account during the BGP best path
decision process. 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 This command specifies that BGP decision process should consider paths
of equal AS_PATH length candidates for multipath computation. Without of equal AS_PATH length candidates for multipath computation. Without
the knob, the entire AS_PATH must match for multipath computation. 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 Ignore AS_PATH length when selecting a route

4
docs/routing/ospf.rst
View File

@ -90,7 +90,7 @@ A typical configuration using 2 nodes.
.. note:: You can not easily redistribute IPv6 routes via OSPFv3 on a WireGuard .. note:: You can not easily redistribute IPv6 routes via OSPFv3 on a WireGuard
interface link. This requires you to configure link-local addresses manually 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: Example configuration for WireGuard interfaces:
@ -136,5 +136,3 @@ Example configuration for WireGuard interfaces:
Neighbor ID Pri DeadTime State/IfState Duration I/F[State] 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] 192.168.0.1 1 00:00:39 Full/PointToPoint 00:19:44 wg01[PointToPoint]
.. _T1483: https://phabricator.vyos.net/T1483

32
docs/routing/static.rst
View File

@ -18,32 +18,32 @@ used to determine the forwarding table used for unicast packet forwarding.
Static Routes 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 Configure next-hop `<address>` for an IPv4 static route. Multiple static
routes can be created. 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. 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 Defines next-hop distance for this route, routes with smaller administrative
distance are elected prior those with a higher distance. distance are elected prior those with a higher distance.
Range is 1 to 255, default is 1. 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 Configure next-hop `<address>` for an IPv6 static route. Multiple static
routes can be created. 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. 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 Defines next-hop distance for this route, routes with smaller administrative
distance are elected prior those with a higher distance. distance are elected prior those with a higher distance.
@ -57,34 +57,34 @@ Static Routes
Interface 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 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 static route. `<interface>` will be the next-hop interface where trafic is
routed for the given `<subnet>`. 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. 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 Defines next-hop distance for this route, routes with smaller administrative
distance are elected prior those with a higher distance. distance are elected prior those with a higher distance.
Range is 1 to 255, default is 1. 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 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 static route. `<interface>` will be the next-hop interface where trafic is
routed for the given `<subnet>`. 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. 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 Defines next-hop distance for this route, routes with smaller administrative
distance are elected prior those with a higher distance. distance are elected prior those with a higher distance.
@ -95,7 +95,7 @@ Interface Routes
Blackhole 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 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 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 it does not prevent them from being used as a more specific route inside your
network. 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 Defines blackhole distance for this route, routes with smaller administrative
distance are elected prior those with a higher distance. 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 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 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 it does not prevent them from being used as a more specific route inside your
network. 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 Defines blackhole distance for this route, routes with smaller administrative
distance are elected prior those with a higher distance. distance are elected prior those with a higher distance.

42
docs/services/dhcp.rst
View File

@ -6,6 +6,8 @@ DHCP / DHCPv6
VyOS uses ISC DHCPd for both IPv4 and IPv6 address assignment. VyOS uses ISC DHCPd for both IPv4 and IPv6 address assignment.
.. _dhcp-server:
DHCP Server DHCP Server
=========== ===========
@ -144,23 +146,23 @@ inside the subnet definition but can be outside of the range statement.
DHCP Options 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. Specify the default routers IPv4 address which should be used in this subnet.
This can - of course - be a VRRP address (DHCP option 003). 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 Specify the DNS nameservers used (Option 006). This option may be used
mulltiple times to specify additional DNS nameservers. 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 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 the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP
Option 015). 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 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 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: Refer to isc-dhcp's dhcpd.conf manual for more information:
https://kb.isc.org/docs/isc-dhcp-44-manual-pages-dhcpdconf 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 ``&quot;``. They will be replaced with literal quote characters
when generating dhcpd.conf.
Example 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;" .. 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 &quot;pxelinux.cfg/01-00-15-17-44-2d-aa&quot;;"
An option that takes a quoted string is set by replacing all quote characters
with the string ``&quot;`` 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 Operation Mode
-------------- --------------
@ -387,41 +401,41 @@ Configuration Options
Clients receiving advertise messages from multiple servers choose the server Clients receiving advertise messages from multiple servers choose the server
with the highest preference value. The range for this value is ``0...255``. 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 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 supplying a ``default-time``, ``maximum-time`` and ``minimum-time``. All
values need to be supplied in seconds. 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 A :abbr:`NIS (Network Information Service)` domain can be set to be used for
DHCPv6 clients. 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)` The procedure to specify a :abbr:`NIS+ (Network Information Service Plus)`
domain is similar to the NIS domain one: 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. 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. 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 Specify a :abbr:`SIP (Session Initiation Protocol)` server by IPv6 address
for all DHCPv6 clients. 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 Specify a :abbr:`SIP (Session Initiation Protocol)` server by FQDN for all
DHCPv6 clients. 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. A SNTP server address can be specified for DHCPv6 clients.
@ -556,7 +570,7 @@ https://wiki.vyos.net/wiki/Network_address_setup.
Configuration Configuration
------------- -------------
.. cfgcmd:: set service dhcp-relay interface '<interface>' .. cfgcmd:: set service dhcp-relay interface <interface>
Enable the DHCP relay service on the given interface. Enable the DHCP relay service on the given interface.

9
docs/services/dns-forwarding.rst
View File

@ -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> .. cfgcmd:: set service dns forwarding domain <domain-name> server <address>
Forward received queries for a particular domain (specified via `domain-name`) 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> .. 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. as with process.
* **validate** The highest mode of DNSSEC processing. In this mode, all * **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 queries will be validated and will be answered with a SERVFAIL in case of
of bogus data, regardless of the client's request. bogus data, regardless of the client's request.
.. note:: The famous UNIX/Linux ``dig`` tool sets the AD-bit in the query. .. 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`` This might lead to unexpected query results when testing. Set ``+noad``

2
docs/services/index.rst
View File

@ -1,7 +1,5 @@
.. _services: .. _services:
.. include:: references.rst
######## ########
Services Services
######## ########

9
docs/services/ipoe-server.rst
View File

@ -4,9 +4,9 @@ IPoE server
VyOS utilizes `accel-ppp`_ to provide IPoE server functionality. It can be VyOS utilizes `accel-ppp`_ to provide IPoE server functionality. It can be
used with local authentication (mac-address) or a connected RADIUS server. 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, will restart the ppp daemon and will reset existing IPoE sessions,
in order to become effective.** in order to become effective.
Configuration 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 ipoe0 | eth2 | 08:00:27:2f:d8:06 | 192.168.0.2 | | | 500/500 | active | 00:00:05 | dccc870fd31349fb
.. include:: ../common-references.rst
.. _`accel-ppp`: https://accel-ppp.org/

104
docs/services/lldp.rst
View File

@ -40,7 +40,8 @@ Configuration
.. cfgcmd:: set service lldp management-address <address> .. 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> .. cfgcmd:: set service lldp interface <interface>
@ -72,65 +73,64 @@ Operation
Displays information about all neighbors discovered via LLDP. Displays information about all neighbors discovered via LLDP.
.. code-block:: none .. code-block:: none
vyos@vyos:~# show lldp neighbors vyos@vyos:~$ show lldp neighbors
Capability Codes: R - Router, B - Bridge, W - Wlan r - Repeater, S - Station Capability Codes: R - Router, B - Bridge, W - Wlan r - Repeater, S - Station
D - Docsis, T - Telephone, O - Other D - Docsis, T - Telephone, O - Other
Device ID Local Proto Cap Platform Port ID Device ID Local Proto Cap Platform Port ID
--------- ----- ----- --- -------- ------- --------- ----- ----- --- -------- -------
Switch0815 eth0 LLDP B Cisco IOS Software, Gi0/4 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 .. opcmd:: show lldp neighbors detail
Get detailed information about LLDP neighbors. Get detailed information about LLDP neighbors.
.. code-block:: none .. code-block:: none
vyos@vyos:~# show lldp neighbors detail vyos@vyos:~$ show lldp neighbors detail
------------------------------------------------------------------------------- -------------------------------------------------------------------------------
LLDP neighbors: LLDP neighbors:
------------------------------------------------------------------------------- -------------------------------------------------------------------------------
Interface: eth0, via: LLDP, RID: 1, Time: 12 days, xxxx:xxxx:40 Interface: eth0, via: LLDP, RID: 28, Time: 0 day, 00:24:33
Chassis: Chassis:
ChassisID: mac 00:50:40:20:03:00 ChassisID: mac 00:53:00:01:02:c9
SysName: Switch0815 SysName: BR2.vyos.net
SysDescr: Cisco IOS Software, C2960 Software (C2960-LANBASEK9-M), Version 15.0(2)SE11, RELEASE SOFTWARE (fc3) SysDescr: VyOS 1.3-rolling-201912230217
Technical Support: http://www.cisco.com/techsupport MgmtIP: 192.0.2.1
Copyright (c) 1986-2017 by Cisco Systems, Inc. MgmtIP: 2001:db8::ffff
Compiled Sat 19-Aug-17 09:34 by prod_rel_team Capability: Bridge, on
MgmtIP: 192.0.2.201 Capability: Router, on
Capability: Bridge, on Capability: Wlan, off
Port: Capability: Station, off
PortID: ifname Gi0/4 Port:
PortDescr: GigabitEthernet0/4 PortID: mac 00:53:00:01:02:c9
TTL: 120 PortDescr: eth0
PMD autoneg: supported: yes, enabled: yes TTL: 120
Adv: 10Base-T, HD: yes, FD: yes PMD autoneg: supported: no, enabled: no
Adv: 100Base-TX, HD: yes, FD: yes MAU oper type: 10GigBaseCX4 - X copper over 8 pair 100-Ohm balanced cable
Adv: 1000Base-T, HD: no, FD: yes VLAN: 201 eth0.201
MAU oper type: 1000BaseTFD - Four-pair Category 5 UTP, full duplex mode VLAN: 205 eth0.205
VLAN: 1, pvid: yes LLDP-MED:
LLDP-MED: Device Type: Network Connectivity Device
Device Type: Network Connectivity Device Capability: Capabilities, yes
Capability: Capabilities, yes Capability: Policy, yes
Capability: Policy, yes Capability: Location, yes
Capability: Location, yes Capability: MDI/PSE, yes
Capability: Inventory, yes Capability: MDI/PD, yes
LLDP-MED Network Policy for: Voice, Defined: no Capability: Inventory, yes
Priority: Best effort Inventory:
PCP: 0 Hardware Revision: None
DSCP Value: 0 Software Revision: 4.19.89-amd64-vyos
LLDP-MED Network Policy for: Voice Signaling, Defined: no Firmware Revision: 6.00
Priority: Best effort Serial Number: VMware-42 1d 83 b9 fe c1 bd b2-7
PCP: 0 Manufacturer: VMware, Inc.
DSCP Value: 0 Model: VMware Virtual Platform
Inventory: Asset ID: No Asset Tag
Hardware Revision: WS-C2960G-8TC-L (PowerPC405):C0 -------------------------------------------------------------------------------
Software Revision: 15.0(2)SE11
Manufacturer: Cisco Systems, Inc.
Model: WS-C2960G-8TC-L
.. opcmd:: show lldp neighbors interface <interface> .. opcmd:: show lldp neighbors interface <interface>

6
docs/services/pppoe-server.rst
View File

@ -7,9 +7,9 @@ PPPoE Server
VyOS utilizes `accel-ppp`_ to provide PPPoE server functionality. It can be VyOS utilizes `accel-ppp`_ to provide PPPoE server functionality. It can be
used with local authentication or a connected RADIUS server. 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 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 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 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

11
docs/services/references.rst
View File

@ -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

6
docs/services/snmp.rst
View File

@ -254,4 +254,8 @@ following content:
</Commands> </Commands>
</Configuration-Management> </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

10
docs/services/ssh.rst
View File

@ -30,17 +30,17 @@ and integrity of data over an unsecured network, such as the Internet.
Configuration 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. 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 Specify IPv4/IPv6 listen address of SSH server. Multiple addresses can be
defined. 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 Define allowed ciphers used for the SSH connection. A number of allowed ciphers
can be specified, use multiple occurrences to allow multiple 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 Disable the host validation through reverse DNS lookups - can speedup login
time when reverse lookup is not possible. 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. Specifies the available :abbr:`MAC (Message Authentication Code)` algorithms.
The MAC algorithm is used in protocol version 2 for data integrity protection. The MAC algorithm is used in protocol version 2 for data integrity protection.

6
docs/services/sstp-server.rst
View File

@ -6,9 +6,9 @@ SSTP server
VyOS utilizes accel-ppp_ to provide SSTP server functionality. It can be VyOS utilizes accel-ppp_ to provide SSTP server functionality. It can be
used with local authentication or a connected RADIUS server. 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 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 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-cert 'server.crt'
set sstp-settings ssl-certs server-key 'server.key' set sstp-settings ssl-certs server-key 'server.key'
.. include:: references.rst .. include:: ../common-references.rst

8
docs/services/tftp.rst
View File

@ -1,8 +1,8 @@
.. _tftp-server: .. _tftp-server:
#### ###########
TFTP TFTP Server
#### ###########
:abbr:`TFTP (Trivial File Transfer Protocol)` is a simple, lockstep file :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 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 content on image upgrades. Any directory under ``/config`` is save at this
will be migrated. 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 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 IPv6 addresses can be given. There will be one TFTP server instances listening

8
docs/services/udp-broadcast-relay.rst
View File

@ -17,23 +17,23 @@ support 99 IDs!
Configuration 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 A description can be added for each and every unique relay ID. This is
usefull to distinguish between multiple different ports/appliactions. 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 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 want to receive/relay packets on both `eth1` and `eth2` both interfaces need
to be added. 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 The UDP port number used by your apllication. It is mandatory for this kind
of operation. 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 Each broadcast relay instance can be individually disabled without deleting
the configured node by using the following command: the configured node by using the following command:

5
docs/services/webproxy.rst
View File

@ -3,7 +3,7 @@ Webproxy
The proxy service in VyOS is based on Squid3 and some related modules. 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, uses, including speeding up a web server by caching repeated requests,
caching web, DNS and other computer network lookups for a group of people caching web, DNS and other computer network lookups for a group of people
sharing network resources, and aiding security by filtering traffic. Although 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 (This can be useful when a called service has many and/or often changing
destination addresses - e.g. Netflix.) destination addresses - e.g. Netflix.)
.. include:: references.rst .. _Squid3: http://www.squid-cache.org/
.. _Squidguard: http://www.squidguard.org/

2
docs/system/config-management.rst
View File

@ -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 Change the number of commit revisions to `<number>`, the default setting for
this value is to store 20 revisions locally. 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 If you want to save all config changes to a remote destination. Set the
commit-archive location. Every time a commit is successfully the commit-archive location. Every time a commit is successfully the

4
docs/system/default-route.rst
View File

@ -5,13 +5,13 @@ Default Gateway/Route
##################### #####################
In the past (VyOS 1.1) used a gateway-address configured under the system tree 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. and existing configurations are migrated to the new CLI command.
Configuration 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 Specify static route into the routing table sending all non local traffic
to the nexthop address `<address>`. to the nexthop address `<address>`.

131
docs/system/flow-accounting.rst
View File

@ -4,6 +4,20 @@
Flow Accounting 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 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 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 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 * **application**: analyzes received flow data in the context of intrusion
detection or traffic profiling, for example detection or traffic profiling, for example
For connectionless protocols as like ICMP and UDP, a flow is considered complete For connectionless protocols as like ICMP and UDP, a flow is considered
once no more packets for this flow appear after configurable timeout. 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 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 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 In order for flow accounting information to be collected and displayed for an
interface, the interface must be configured for flow accounting. 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 Configure and enable collection of flow information for the interface
identified by `<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 You can configure multiple interfaces which whould participate in flow
accounting. 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 Flow Export
----------- -----------
In addition to displaying flow accounting information locally, one can also In addition to displaying flow accounting information locally, one can also
exported them to a collection server. exported them to a collection server.
.. cfgcmd:: set system flow-accounting netflow version '<version>' NetFlow
^^^^^^^
There are multiple versions available for the NetFlo data. The `<version>` .. cfgcmd:: set system flow-accounting netflow version <version>
There are multiple versions available for the NetFlow data. The `<version>`
used in the exported flow data can be configured here. The following used in the exported flow data can be configured here. The following
versions are supported: versions are supported:
@ -55,20 +95,20 @@ exported them to a collection server.
* **9** - NetFlow version 9 (default) * **9** - NetFlow version 9 (default)
* **10** - :abbr:`IPFIX (IP Flow Information Export)` as per :rfc:`3917` * **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 Configure address of NetFlow collector. NetFlow server at `<address>` can
be both listening on an IPv4 or IPv6 address. 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 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. 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 Use this command to configure the sampling rate for flow accounting. The
system samples one in every `<rate>` packets, where `<rate>` is the value 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). 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 Specifies the interval at which Netflow data will be sent to a collector. As
per default, Netflow data will be sent every 60 seconds. 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: Example:
-------- --------
@ -103,44 +169,33 @@ Operation
Once flow accounting is configured on an interfaces it provides the ability to Once flow accounting is configured on an interfaces it provides the ability to
display captured network traffic information for all configured interfaces. 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>`. Show flow accounting information for given `<interface>`.
.. code-block:: none .. code-block:: none
vyos@vyos:~$ show flow-accounting interface eth0 vyos@vyos:~$ show flow-accounting interface eth0
flow-accounting for [eth0] IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES
Src Addr Dst Addr Sport Dport Proto Packets Bytes Flows ---------- ----------------- ----------------- ------------------------ --------------- ---------- ---------- ---------- ----- --------- ------- -------
0.0.0.0 192.0.2.50 811 811 udp 7733 591576 0 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
0.0.0.0 192.0.2.50 811 811 udp 7669 586558 1 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
192.0.2.200 192.0.2.51 56188 22 tcp 586 36504 1 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
192.0.2.99 192.0.2.51 61636 161 udp 46 6313 4 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
192.0.2.99 192.0.2.51 61638 161 udp 42 5364 9 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
192.0.2.99 192.0.2.51 61640 161 udp 42 5111 3 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
192.0.2.200 192.0.2.51 54702 22 tcp 86 4432 1 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
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>
.. opcmd:: show flow-accounting interface '<interface>' host '<address>'
Show flow accounting information for given `<interface>` for a specific host Show flow accounting information for given `<interface>` for a specific host
only. only.
.. code-block:: none .. code-block:: none
vyos@vyos:~$ show flow-accounting interface eth0 host 192.0.2.200 vyos@vyos:~$ show flow-accounting interface eth0 host 192.0.2.14
flow-accounting for [eth0] IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES
Src Addr Dst Addr Sport Dport Proto Packets Bytes Flows ---------- ----------------- ----------------- ----------- ---------- ---------- ---------- ---------- ----- --------- ------- -------
192.0.2.200 192.0.2.51 56188 22 tcp 586 36504 1 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
192.0.2.200 192.0.2.51 54702 22 tcp 86 4432 1 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

12
docs/system/host-information.rst
View File

@ -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 or over the internet. On the other hand this will be the name which appears on
the command line prompt. 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 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 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 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`. 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 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. 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 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 This section shows how to statically map an IP address to a hostname for local
(meaning on this VyOS instance) name resolution. (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 Create a static hostname mapping which will always resolve the name
`<hostname>` to IP address `<address>`. `<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>`. Create named `<alias>` for the configured static mapping for `<hostname>`.
Thus the address configured as :cfgcmd:`set system static-host-mapping 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. Multiple aliases can pe specified per host-name.

8
docs/system/ntp.rst
View File

@ -33,9 +33,9 @@ in :rfc:`1305`.
Configuration 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)`. an IP address or :abbr:`FQDN (Fully Qualified Domain Name)`.
There are 3 default NTP server set. You are able to change them. There are 3 default NTP server set. You are able to change them.
@ -44,13 +44,13 @@ Configuration
* 1.pool.ntp.org * 1.pool.ntp.org
* 2.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 Setup VyOS as an NTP responder, you must specify the `<address>` and
optionally the permitted clients. Multiple listen addresses can be optionally the permitted clients. Multiple listen addresses can be
configured. 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. List of networks or client addresses permitted to contact this NTP server.
Multiple networks can be configured. Multiple networks can be configured.

8
docs/system/proxy.rst
View File

@ -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 Without this configuration VyOS updates could not be installed directly by
using the :opcmd:`add system image` command (:ref:`update_vyos`). 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 Set proxy for all connections initiated by VyOS, including HTTP, HTTPS, and
FTP (anonymous ftp). 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. 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 Some proxys require/support the "basic" HTTP authentication scheme as per
:rfc:`7617`, thus a username can be configured. :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 Some proxys require/support the "basic" HTTP authentication scheme as per
:rfc:`7617`, thus a password can be configured. :rfc:`7617`, thus a password can be configured.

6
docs/system/serial-console.rst
View File

@ -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. 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 Defines the specified device as a system console. Available console devices
can be (see completion helper): 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 * ``ttyUSBX`` - USB Serial device name
* ``hvc0`` - Xen console * ``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: The speed (baudrate) of the console device. Supported values are:
@ -44,6 +44,6 @@ Network Console
TBD. TBD.
.. cfgcmd:: set system console network '<netconXX>' .. cfgcmd:: set system console network <netconXX>
... and many more commands ... ... and many more commands ...

8
docs/system/task-scheduler.rst
View File

@ -11,7 +11,7 @@ use of UNIX cron_.
be dangerous. Together with :ref:`command-scripting` this can be used for be dangerous. Together with :ref:`command-scripting` this can be used for
automating (re-)configuration. 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 Specify the time interval when `<task>` should be executed. The interval
is specified as number with one of the following suffixes: 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. .. 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 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. ``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 Specify absolute `<path>` to script which will be run when `<task>` is
executed. 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. Arguments which will be passed to the executable.

2
docs/system/time-zone.rst
View File

@ -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 based on the configured zone. Without proper time zone configuration it will
be very difficult to compare logfiles from different systems. 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 Specify the systems `<timezone>` as the Region/Location that best defines
your location. For example, specifying US/Pacific sets the time zone to US your location. For example, specifying US/Pacific sets the time zone to US

26
docs/system/user-management.rst
View File

@ -15,23 +15,23 @@ Authentication Dial-In User Service)` accounts are supported.
Local 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 Create new system user with username `<name>` and real-name specified by
`<string>`. `<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 Specify the plaintext password user by user `<name>` on this system. The
plaintext password will be automatically transferred into a secure hashed plaintext password will be automatically transferred into a secure hashed
password and not saved anywhere in plaintext. 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 Setup encrypted password for given username. This is usefull for
transferring a hashed password from system to system. 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>`. 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. 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. 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 Assign the SSH public key portion `<key>` identified by per-key
`<identifier>` to the local user `<username>`. `<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 Every SSH public key portion referenced by `<identifier>` requires the
configuration of the `<type>` of public-key used. This type can be any of: 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 .. note:: You can assign multiple keys to the same user by using a unique
identifier per SSH key. 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 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 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 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 Specify the `<address>` of the RADIUS server user with the pre-shared-secret
given in `<secret>`. Multiple servers can be specified. 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. Configure the discrete port under which the RADIUS server can be reached.
This defaults to 1812. 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. 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. 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 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 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 You are able to set post-login or pre-login banner messages to display certain
information for this system. 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 Configure `<message>` which is shown during SSH connect and before a user is
logged in. 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. Configure `<message>` which is shown after user has logged in to the system.

9
docs/vpn/l2tp.rst
View File

@ -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 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-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 start 192.168.255.2
set vpn l2tp remote-access client-ip-pool stop 192.168.255.254 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 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 mode local
set vpn l2tp remote-access authentication local-users username test password 'test' 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 In the example above an external IP of 192.0.2.2 is assumed.
192.168.255.1 uses as client tunnel termination point.
If a local firewall policy is in place on your external interface you will need If a local firewall policy is in place on your external interface you will need
to allow the ports below: to allow the ports below:
@ -100,7 +98,6 @@ Below is an example to configure a LNS:
.. code-block:: none .. code-block:: none
set vpn l2tp remote-access outside-address 192.0.2.2 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 start 192.168.255.2
set vpn l2tp remote-access client-ip-pool stop 192.168.255.254 set vpn l2tp remote-access client-ip-pool stop 192.168.255.254
set vpn l2tp remote-access lns shared-secret 'secret' 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 mode local
set vpn l2tp remote-access authentication local-users username test password 'test' 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 The example above uses 192.0.2.2 as external IP address. A LAC normally
to be 192.168.255.1 and is used as client termination point. A LAC normally
requires an authentication password, which is set in the example configuration requires an authentication password, which is set in the example configuration
to ``lns shared-secret 'secret'``. This setup requires the Compression Control to ``lns shared-secret 'secret'``. This setup requires the Compression Control
Protocol (CCP) being disabled, the command ``set vpn l2tp remote-access ccp-disable`` 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 .. code-block:: none
set vpn l2tp remote-access outside-address 192.0.2.2 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 start 192.168.255.2
set vpn l2tp remote-access client-ip-pool stop 192.168.255.254 set vpn l2tp remote-access client-ip-pool stop 192.168.255.254
set vpn l2tp remote-access authentication mode local set vpn l2tp remote-access authentication mode local

6
docs/vpn/openvpn.rst
View File

@ -441,8 +441,8 @@ Options
======= =======
We do not have CLI nodes for every single OpenVPN options. If an option is 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 missing, a feature request should be opened at Phabricator_ so all users can
all users can benefit from it. benefit from it (see :ref:`issues_features`).
If you are a hacker or want to try on your own we support passing raw OpenVPN If you are a hacker or want to try on your own we support passing raw OpenVPN
options to 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 .. 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. This is done through a hack on our config generator. You can pass
quotes using the ``&quot;`` statement. quotes using the ``&quot;`` statement.
.. include:: ../common-references.rst