From 4523af57f0c8fbcd4ebde3edd35291622576edc9 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sat, 21 Dec 2019 12:11:34 +0100 Subject: image-mgmt: image name can be passed to 'delete system image' --- docs/image-mgmt.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/image-mgmt.rst b/docs/image-mgmt.rst index 245a31b7..3b8f04c3 100644 --- a/docs/image-mgmt.rst +++ b/docs/image-mgmt.rst @@ -48,9 +48,11 @@ configured to be the default (:opcmd:`set system image default-boot`). system image` -.. opcmd:: delete system image +.. opcmd:: delete system image [image-name] - Delete no longer needed images from the system. + Delete no longer needed images from the system. You can specify an optional + image name to delete, the image name can be retrived via a list of available + images can be shown using the :opcmd:`show system image`. .. code-block:: none -- cgit v1.2.3 From 32652cce15d200363c0dbaf5d2c6c41621f51e73 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sat, 21 Dec 2019 18:03:01 +0100 Subject: install: overall chapter improvement --- docs/contributing/issues-features.rst | 2 + docs/install.rst | 94 +++++++++++++++++++---------------- docs/services/dhcp.rst | 2 + docs/services/tftp.rst | 6 +-- 4 files changed, 58 insertions(+), 46 deletions(-) (limited to 'docs') diff --git a/docs/contributing/issues-features.rst b/docs/contributing/issues-features.rst index 3a1738d7..04efbd22 100644 --- a/docs/contributing/issues-features.rst +++ b/docs/contributing/issues-features.rst @@ -3,6 +3,8 @@ Issues/Feature requests ======================= +.. _bug_report: + Bug Report/Issue ---------------- Issues or bugs are found in any software project. VyOS is not an exception. diff --git a/docs/install.rst b/docs/install.rst index 0a36e831..0f6f0f23 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -7,14 +7,14 @@ Installation Requirements ============ -The recommended system requirements are 512 MiB RAM and 2 GiB storage. Depending -on your use you might need additional RAM and CPU resources e.g. when having -multiple BGP full tables in your system. +The recommended system requirements are 512 MiB RAM and 2 GiB storage. +Depending on your use you might need additional RAM and CPU resources e.g. +when having multiple BGP full tables in your system. -Getting the software -==================== +Download +======== -Registered subscribers +Registered Subscribers ---------------------- Registered subscribers can log into https://support.vyos.io/ to have access to @@ -28,23 +28,29 @@ ISOs. Building from source ---------------------- -Non-subscribers can get the LTS release by building it from source. Instruction -can be found here: :ref:`build` and the source repository is available -for everyone at https://github.com/vyos/vyos-build. +Non-subscribers can always get the LTS release by building it from source. +Instruction can be found in the :ref:`build` section of this manual. VyOS +source code repository is available for everyone at +https://github.com/vyos/vyos-build. Rolling Release --------------- -Non-subscribers and subscribers can download bleeding-edge VyOS rolling images -from: https://downloads.vyos.io/ +Everyone can download bleeding-edge VyOS rolling images from: +https://downloads.vyos.io/ -The following link will always fetch the most updated AMD64 image of the -current branch: +.. note:: Rolling releases contain all the latest enhancements and fixes. This + means that there will be new bugs of course. If you think you hit a bug + please follow the guide at :ref:`bug_report`. To improve VyOS we depend on + your feedback! + +The following link will always fetch the most recent VyOS build for AMD64 +systems from the current branch: https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso -Software verification -===================== +Download Verification +--------------------- This subsection and the following one applies to downloaded LTS images, for other versions please jump to :ref:`Install`. @@ -164,12 +170,12 @@ Finally, verify the authencity of the downloaded image: .. _Install: -Install -======= +Installation +============ -VyOS ISO is a Live CD and will boot to a functional VyOS image. +VyOS ISO is a live CD and will boot into a full functional VyOS system. -To login to the system, use the default username and password will be: ``vyos`` +.. hint:: The default username and password for the live system is ``vyos``. .. code-block:: none @@ -251,34 +257,34 @@ the provided default credentials. Setting up grub: OK Done! -After the installation is complete, remove the Live CD and reboot the system: +After the installation is complete, remove the live CD and reboot the system: .. code-block:: none vyos@vyos:~$ reboot Proceed with reboot? (Yes/No) [No] Yes -.. _PXE Install: - -PXE Install ------------ +PXE Boot +-------- VyOS can also be installed through PXE. This is a more complex installation method which allows deploying VyOS through the network. -Requirements -^^^^^^^^^^^^ +**Requirements** + +* :ref:`dhcp-server` +* :ref:`tftp-server` +* Webserver (HTTP) - optional, but we will use it to speed up intallation +* VyOS ISO image to be installed (do not use images prior to VyOS 1.2.3) +* ``pxelinux.0``, ``ldlinux.c32`` from SYSLINUX_ + (https://mirrors.edge.kernel.org/pub/linux/utils/boot/syslinux/) -* **Clients** (where VyOS is to be installed) **with a PXE-enabled NIC** -* A **DHCP server** -* A **TFTP server** -* A **HTTP server** (optional, but we will use it to speed up intallation) -* The **VyOS ISO** image to be installed (do not use images prior to VyOS 1.2.3) -* The ``pxelinux.0`` and ``ldlinux.c32`` files from the Syslinux distribution - https://mirrors.edge.kernel.org/pub/linux/utils/boot/syslinux/ -Step 1: DHCP -^^^^^^^^^^^^ +Configuration +^^^^^^^^^^^^^ + +DHCP +"""" Configure DHCP server to provide the client with: @@ -305,8 +311,8 @@ In this example we configured an existent VyOS as the DHCP server: .. _install_from_tftp: -Step 2: TFTP -^^^^^^^^^^^^ +TFTP +"""" Configure a TFTP server so that it serves the following: @@ -365,8 +371,8 @@ Example of simple (no menu) configuration file: APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence \ noautologin nonetworking fetch=http://address:8000/filesystem.squashfs -Step 3: HTTP -^^^^^^^^^^^^ +HTTP +"""" As you read in the configuration file, we are sending ``filesystem.squashfs`` through HTTP. As that is a heavy file, we choose HTTP to speed up the transfer @@ -375,8 +381,8 @@ over TFTP. Run a web server - you can use a simple one like file. The file can be found inside the ``/live`` directory of the extracted contents of the ISO file. -Edit the configuration file at the :ref:`install_from_tftp` so that it shows the -correct URL at ``fetch=http://address/filesystem.squashfs``. Then restart +Edit the configuration file at the :ref:`install_from_tftp` so that it shows +the correct URL at ``fetch=http://address/filesystem.squashfs``. Then restart the TFTP service. If you are using VyOS as your TFTP Server, you can restart the service with ``sudo service tftpd-hpa restart``. @@ -385,8 +391,8 @@ the service with ``sudo service tftpd-hpa restart``. .. _`Python's SimpleHTTPServer`: https://docs.python.org/2/library/simplehttpserver.html -Step 4: Boot the clients -^^^^^^^^^^^^^^^^^^^^^^^^ +Client Boot +""""""""""" Turn on your PXE-enabled client or clients. They will automatically get an IP address from the DHCP server and start booting into VyOS live from the files @@ -394,3 +400,5 @@ automatically taken from the TFTP and HTTP servers. Once finished you will be able to proceed with the ``install image`` command as in a regular VyOS installation. + +.. _SYSLINUX: http://www.syslinux.org/ diff --git a/docs/services/dhcp.rst b/docs/services/dhcp.rst index 19c92aac..ed5082d4 100644 --- a/docs/services/dhcp.rst +++ b/docs/services/dhcp.rst @@ -6,6 +6,8 @@ DHCP / DHCPv6 VyOS uses ISC DHCPd for both IPv4 and IPv6 address assignment. +.. _dhcp-server: + DHCP Server =========== diff --git a/docs/services/tftp.rst b/docs/services/tftp.rst index c33d6c7c..8647dfa8 100644 --- a/docs/services/tftp.rst +++ b/docs/services/tftp.rst @@ -1,8 +1,8 @@ .. _tftp-server: -#### -TFTP -#### +########### +TFTP Server +########### :abbr:`TFTP (Trivial File Transfer Protocol)` is a simple, lockstep file transfer protocol which allows a client to get a file from or put a file onto -- cgit v1.2.3 From a8409f1eb630b85f18722dfc101605590516aed8 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sat, 21 Dec 2019 18:25:46 +0100 Subject: quick-start: rewrite entire chapter --- docs/nat.rst | 2 + docs/quick-start.rst | 151 +++++++++++++++++++++++++++------------------------ 2 files changed, 82 insertions(+), 71 deletions(-) (limited to 'docs') diff --git a/docs/nat.rst b/docs/nat.rst index 714697d3..f2c89a71 100644 --- a/docs/nat.rst +++ b/docs/nat.rst @@ -3,6 +3,8 @@ NAT === +.. _source-nat: + Source NAT ---------- diff --git a/docs/quick-start.rst b/docs/quick-start.rst index ad0d896f..b1295790 100644 --- a/docs/quick-start.rst +++ b/docs/quick-start.rst @@ -4,17 +4,46 @@ Quick Start ########### -Below is a very basic configuration example that will provide a NAT gateway -for a device with two interfaces. +This chapter will guide you on how to get up to speed using your new VyOS +system. It will show you a very basic configuration example that will provide +a :ref:`nat` gateway for a device with two network interfaces (`eth0` and +`eth1`). -Enter configuration mode: +.. _quick-start-configuration-mode: + +Configuration Mode +################## .. code-block:: none vyos@vyos$ configure vyos@vyos# -Configure network interfaces: +Commit and Save +################ + +After every configuration change you need to apply the changes by using the + +.. code-block:: none + + commit + +Once your configuration works as expected you can save it permanently. + +.. code-block:: none + + save + +Network Interface Configuration +############################### + +* Your outside/WAN interface will be `eth0`, it receives it's interface address + be means of DHCP. +* Your internal/LAN interface is `eth1`. It uses a fixed IP address of + `192.168.0.1/24`. + +After switching to :ref:`quick-start-configuration-mode` issue the following +commands: .. code-block:: none @@ -23,14 +52,30 @@ Configure network interfaces: set interfaces ethernet eth1 address '192.168.0.1/24' set interfaces ethernet eth1 description 'INSIDE' -Enable SSH for remote management: +Enable Management via SSH +######################### + +After switching to :ref:`quick-start-configuration-mode` issue the following +commands, and your system will listen on every interface for incoming SSH +connections. You might want to check the :ref:`ssh` chapter on how to listen +on specific addresses only. .. code-block:: none set service ssh port '22' -Configure DHCP Server and DNS -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Configure DHCP and DNS server +############################# + +* Provide DHCP service on your internal/LAN network where VyOS will act + as the default gateway and DNS server. +* Client IP addresses are assigned from the range ``192.168.0.9 - + 192.168.0.254`` +* DHCP leases will hold for one day (86400 seconds) +* VyOS will server as full DNS recursor - no need to bother the Google or + Cloudflare DNS servers (good for privacy) +* Only clients from your internal/LAN network can use the DNS resolver .. code-block:: none @@ -41,19 +86,14 @@ Configure DHCP Server and DNS set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 range 0 start 192.168.0.9 set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 range 0 stop '192.168.0.254' -And a DNS forwarder: - -.. code-block:: none - set service dns forwarding cache-size '0' set service dns forwarding listen-address '192.168.0.1' - set service dns forwarding name-server '203.0.113.1' - set service dns forwarding name-server '203.0.113.2' + set service dns forwarding allow-from '192.168.0.0/24' -NAT and Firewall -^^^^^^^^^^^^^^^^ +NAT +### -Configure Source NAT for our "Inside" network. +* Configure :ref:`source-nat` for our internal/LAN network .. code-block:: none @@ -61,9 +101,13 @@ Configure Source NAT for our "Inside" network. set nat source rule 100 source address '192.168.0.0/24' set nat source rule 100 translation address masquerade -Add a set of firewall policies for our "Outside" interface. +Firewall +######## -This configuration creates a proper stateful firewall that blocks all traffic: +Add a set of firewall policies for our outside/WAN interface. + +This configuration creates a proper stateful firewall that blocks all traffic +which was not initiated from the internal/LAN side first. .. code-block:: none @@ -71,6 +115,7 @@ This configuration creates a proper stateful firewall that blocks all traffic: set firewall name OUTSIDE-IN rule 10 action 'accept' set firewall name OUTSIDE-IN rule 10 state established 'enable' set firewall name OUTSIDE-IN rule 10 state related 'enable' + set firewall name OUTSIDE-LOCAL default-action 'drop' set firewall name OUTSIDE-LOCAL rule 10 action 'accept' set firewall name OUTSIDE-LOCAL rule 10 state established 'enable' @@ -80,8 +125,8 @@ This configuration creates a proper stateful firewall that blocks all traffic: set firewall name OUTSIDE-LOCAL rule 20 protocol 'icmp' set firewall name OUTSIDE-LOCAL rule 20 state new 'enable' -If you wanted to enable SSH access to your firewall from the Internet, you -could create some additional rules to allow the traffic. +If you wanted to enable SSH access to your firewall from the outside/WAN +interface, you could create some additional rules to allow that kind of traffic. These rules allow SSH traffic and rate limit it to 4 requests per minute. This blocks brute-forcing attempts: @@ -94,6 +139,7 @@ blocks brute-forcing attempts: set firewall name OUTSIDE-LOCAL rule 30 recent count '4' set firewall name OUTSIDE-LOCAL rule 30 recent time '60' set firewall name OUTSIDE-LOCAL rule 30 state new 'enable' + set firewall name OUTSIDE-LOCAL rule 31 action 'accept' set firewall name OUTSIDE-LOCAL rule 31 destination port '22' set firewall name OUTSIDE-LOCAL rule 31 protocol 'tcp' @@ -117,15 +163,13 @@ Commit changes, save the configuration, and exit configuration mode: vyos@vyos# exit vyos@vyos$ -Basic QoS -^^^^^^^^^ +QoS +### -The traffic policy subsystem provides an interface to Linux traffic control -(tc_). -One common use of traffic policy is to limit bandwidth for an interface. In -the example below we limit bandwidth for our LAN connection to 200 Mbit -download and out WAN connection to 50 Mbit upload: +One common use of :ref:`qos` is to limit bandwidth for an interface. In +the example below we limit bandwidth for our internal/LAN connection to 200 +Mbit/s download and our outside/WAN connection to 50 Mbit/s upload: .. code-block:: none @@ -133,35 +177,13 @@ download and out WAN connection to 50 Mbit upload: set traffic-policy shaper WAN-OUT default bandwidth '50%' set traffic-policy shaper WAN-OUT default ceiling '100%' set traffic-policy shaper WAN-OUT default queue-type 'fair-queue' + set traffic-policy shaper LAN-OUT bandwidth '200Mbit' set traffic-policy shaper LAN-OUT default bandwidth '50%' set traffic-policy shaper LAN-OUT default ceiling '100%' set traffic-policy shaper LAN-OUT default queue-type 'fair-queue' -Resulting in the following configuration: - -.. code-block:: none - - traffic-policy { - shaper WAN-OUT { - bandwidth 50Mbit - default { - bandwidth 50% - ceiling 100% - queue-type fair-queue - } - } - shaper LAN-OUT { - bandwidth 200Mbit - default { - bandwidth 50% - ceiling 100% - queue-type fair-queue - } - } - } - -Once defined, a traffic policy can be applied to each interface using the +Once defined, a traffic policy needs to be applied to each interface using the interface-level traffic-policy directive: .. code-block:: none @@ -169,46 +191,33 @@ interface-level traffic-policy directive: set interfaces ethernet eth0 traffic-policy out 'WAN-OUT' set interfaces ethernet eth1 traffic-policy out 'LAN-OUT' -.. note:: A traffic policy can also be defined to match specific traffic - flows using class statements. - -VyOS 1.2 (Crux) also supports HFSC (:code:`set traffic-policy shaper-hfsc`) - -See further information in the :ref:`qos` chapter. - Security Hardening -^^^^^^^^^^^^^^^^^^ +################## -Especially if you are allowing SSH access from the Internet, there are a few -additional configuration steps that should be taken. +Especially if you are allowing SSH remote access from the outside/WAN interface, +there are a few additional configuration steps that should be taken. -Create a user to replace the default `vyos` user: +Replace the default `vyos` system user: .. code-block:: none set system login user myvyosuser level admin set system login user myvyosuser authentication plaintext-password mysecurepassword -Set up SSH key based authentication. For example, on Linux you'd want to run -``ssh-keygen -t rsa``. Then the contents of ``id_rsa.pub`` would be used below: +Set up :ref:`ssh_key_based_authentication`: .. code-block:: none set system login user myvyosuser authentication public-keys myusername@mydesktop type ssh-rsa set system login user myvyosuser authentication public-keys myusername@mydesktop key contents_of_id_rsa.pub -Or you can use the ``loadkey`` command. Commit and save. - Finally, try and SSH into the VyOS install as your new user. Once you have -confirmed that your new user can access your server, without a password, delete +confirmed that your new user can access your router without a password, delete the original ``vyos`` user and probably disable password authentication for -SSH: +:ref:`ssh` at all: .. code-block:: none delete system login user vyos set service ssh disable-password-authentication -Commit and save. - -.. _tc: https://en.wikipedia.org/wiki/Tc_(Linux) -- cgit v1.2.3 From 2aaeedd7c1533a1458b48b57ac9fbccead376261 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sat, 21 Dec 2019 18:57:24 +0100 Subject: interface: split into basic and advanced section --- docs/index.rst | 3 ++- docs/interfaces/basic-index.rst | 52 +++++++++++++++++++++++++++++++++++++++++ docs/interfaces/index.rst | 7 ++---- 3 files changed, 56 insertions(+), 6 deletions(-) create mode 100644 docs/interfaces/basic-index.rst (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index 4d25bb09..93541f39 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -23,7 +23,7 @@ VyOS User Guide :maxdepth: 2 configuration-overview - interfaces/index + interfaces/basic-index system/basic-index image-mgmt @@ -33,6 +33,7 @@ VyOS User Guide :name: advanced :maxdepth: 2 + interfaces/index services/index system/index firewall diff --git a/docs/interfaces/basic-index.rst b/docs/interfaces/basic-index.rst new file mode 100644 index 00000000..67be1a90 --- /dev/null +++ b/docs/interfaces/basic-index.rst @@ -0,0 +1,52 @@ +.. _basic_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 `` +command. + +.. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 + eth0: 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 + ethernet + pppoe diff --git a/docs/interfaces/index.rst b/docs/interfaces/index.rst index 0513adf1..95f60d11 100644 --- a/docs/interfaces/index.rst +++ b/docs/interfaces/index.rst @@ -47,14 +47,11 @@ respective sections. .. toctree:: :maxdepth: 2 - addresses dummy - ethernet - l2tpv3 - pppoe - wireless bridge bond + l2tpv3 + wireless tunnel vlan qinq -- cgit v1.2.3 From e95095d26622fa4cbaa5ab782194ec4607237aa6 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sat, 21 Dec 2019 19:24:09 +0100 Subject: ethernet: document more configuration/operation commands --- docs/interfaces/ethernet.rst | 303 +++++++++++++++++++++++++++++++++---------- 1 file changed, 234 insertions(+), 69 deletions(-) (limited to 'docs') diff --git a/docs/interfaces/ethernet.rst b/docs/interfaces/ethernet.rst index a8cee8c2..4a5abded 100644 --- a/docs/interfaces/ethernet.rst +++ b/docs/interfaces/ethernet.rst @@ -1,72 +1,237 @@ .. _ethernet-interface: +######## Ethernet --------- - -Ethernet interfaces allow for the configuration of speed, duplex, and hw-id -(MAC address). Below is an example configuration: - -.. code-block:: none - - set interfaces ethernet eth1 address '192.168.0.1/24' - set interfaces ethernet eth1 address '2001:db8:1::ffff/64' - set interfaces ethernet eth1 description 'INSIDE' - set interfaces ethernet eth1 duplex 'auto' - set interfaces ethernet eth1 speed 'auto' - -Resulting in: - -.. code-block:: none - - ethernet eth1 { - address 192.168.0.1/24 - address 2001:db8:1::ffff/64 - description INSIDE - duplex auto - hw-id 00:53:29:44:3b:19 - smp_affinity auto - speed auto - } - -In addition, Ethernet interfaces provide the extended operational commands: - -* ``show interfaces ethernet physical`` -* ``show interfaces ethernet statistics`` - -Statistics available are driver dependent. - -.. code-block:: none - - vyos@vyos:~$ show interfaces ethernet eth0 physical - Settings for eth0: - Supported ports: [ TP ] - Supported link modes: 10baseT/Half 10baseT/Full - 100baseT/Half 100baseT/Full - 1000baseT/Full - Supports auto-negotiation: Yes - Advertised link modes: 10baseT/Half 10baseT/Full - 100baseT/Half 100baseT/Full - 1000baseT/Full - Advertised pause frame use: No - Advertised auto-negotiation: Yes - Speed: 1000Mb/s - Duplex: Full - Port: Twisted Pair - PHYAD: 0 - Transceiver: internal - Auto-negotiation: on - MDI-X: Unknown - Supports Wake-on: d - Wake-on: d - Current message level: 0x00000007 (7) - Link detected: yes - driver: e1000 - version: 7.3.21-k8-NAPI - firmware-version: - bus-info: 0000:02:01.0 - - vyos@vyos:~$ show interfaces ethernet eth0 statistics - NIC statistics: - rx_packets: 3530 - tx_packets: 2179 - [...] +######## + +Configuration +############# + +Address +------- + +.. cfgcmd:: set interfaces ethernet '' address
+ + Configure ethernet interface `` with one or more interface + addresses. + + * **address** can be specified multiple times as IPv4 and/or IPv6 address, + e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + * **dhcp** interface address is received by DHCP from a DHCP server on this + segment. + * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 server on + this segment. + + Example: + + .. code-block:: none + + set interfaces ethernet eth0 address 192.0.2.1/24 + set interfaces ethernet eth0 address 192.0.2.2/24 + set interfaces ethernet eth0 address 2001:db8::ffff/64 + set interfaces ethernet eth0 address 2001:db8:100::ffff/64 + +.. cfgcmd:: set interfaces ethernet '' ipv6 address autoconf + + :abbr:`SLAAC (Stateless Address Autoconfiguration)` is specified in + :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. + +.. cfgcmd:: set interfaces ethernet '' ipv6 address eui64 '' + + :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in + :rfc:`4291` allows a host to assign iteslf a unique 64-Bit IPv6 address. + + .. code-block:: none + + set interfaces ethernet eth0 ipv6 address eui64 2001:db8:beef::/64 + +Speed/Duplex +------------ + +.. cfgcmd:: set interfaces ethernet '' duplex + + Configure physical interface duplex setting. + + * auto - interface duplex setting is auto-negotiated + * full - always use full-duplex + * half - always use half-duplex + + VyOS default will be `auto`. + +.. cfgcmd:: set interfaces ethernet '' speed + + Configure physical interface speed setting. + + * auto - interface speed is auto-negotiated + * 10 - 10 MBit/s + * 100 - 100 MBit/s + * 1000 - 1 GBit/s + * 2500 - 2.5 GBit/s + * 5000 - 5 GBit/s + * 10000 - 10 GBit/s + * 25000 - 25 GBit/s + * 40000 - 40 GBit/s + * 50000 - 50 GBit/s + * 100000 - 100 GBit/s + + VyOS default will be `auto`. + +Link Administration +------------------- + +.. cfgcmd:: set interfaces ethernet '' description '' + + Assign given `` to interface. Description will also be passed + to SNMP monitoring systems. + +.. cfgcmd:: set interfaces ethernet '' disable + + Disable given ethernet interface. It will be placed in administratively down + state. + +.. cfgcmd:: set interfaces ethernet '' disable-flow-control + + Disable Ethernet flow control (pause frames). + + +.. cfgcmd:: set interfaces ethernet '' mac '' + + Configure user defined :abbr:`MAC (Media Access Control)` address on given + ``. + +.. cfgcmd:: set interfaces ethernet '' mtu '' + + Configure :abbr:`MTU (Maximum Transmission Unit)` on given ``. 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 '' ipv6 router-advert send-advert + + Enable or disable router advertisements in this ``. + +.. cfgcmd:: set interfaces ethernet '' ipv6 router-advert prefix '' + + Prefix information is described in :rfc:`4861#section-4.6.2`. + +Operation +========= + +.. opcmd:: show interfaces ethernet + + Show Ethernet 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 '' + + Show detailed information on given `` + + .. code-block:: + + vyos@vyos:~$ show interfaces ethernet eth0 + eth0: 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 '' physical + + Show information about physical `` + + .. code-block:: + + 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 '' 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 + -- cgit v1.2.3 From 554e5357b73dc5bae22aa6dc058587e2a1265236 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sat, 21 Dec 2019 19:24:43 +0100 Subject: interface: remove addresses from basic-index --- docs/interfaces/addresses.rst | 3 +-- docs/interfaces/basic-index.rst | 1 - 2 files changed, 1 insertion(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/interfaces/addresses.rst b/docs/interfaces/addresses.rst index 709490c8..3fc9b89b 100644 --- a/docs/interfaces/addresses.rst +++ b/docs/interfaces/addresses.rst @@ -96,8 +96,7 @@ The command is ``set interfaces $type $name ipv6 address autoconf``. Examples: 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 ****** diff --git a/docs/interfaces/basic-index.rst b/docs/interfaces/basic-index.rst index 67be1a90..4f950a2b 100644 --- a/docs/interfaces/basic-index.rst +++ b/docs/interfaces/basic-index.rst @@ -47,6 +47,5 @@ respective sections. .. toctree:: :maxdepth: 2 - addresses ethernet pppoe -- cgit v1.2.3 From d778d022b3f0ca4369b31b9717239e75219aa540 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sat, 21 Dec 2019 19:26:41 +0100 Subject: pppoe: use documented section style guide --- docs/interfaces/pppoe.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/interfaces/pppoe.rst b/docs/interfaces/pppoe.rst index ef595b97..f96beb50 100644 --- a/docs/interfaces/pppoe.rst +++ b/docs/interfaces/pppoe.rst @@ -1,7 +1,8 @@ .. _pppoe-interface: +##### PPPoE -===== +##### :abbr:`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol for encapsulating PPP frames inside Ethernet frames. It appeared in 1999, @@ -14,14 +15,14 @@ PPP facilities for authenticating the user with a username and password, predominately via the PAP protocol and less often via CHAP. Operating Modes ---------------- +=============== VyOS supports setting up PPPoE in two different ways to a PPPoE internet connection. This is due to most ISPs provide a modem that is also a wireless router. Home Users -********** +---------- In this method, the DSL Modem/Router connects to the ISP for you with your credentials preprogrammed into the device. This gives you an :rfc:`1918` @@ -34,7 +35,7 @@ few extra layers of complexity, particularly if you use some NAT or tunnel features. Business Users -************** +-------------- In order to have full control and make use of multiple static public IP addresses, your VyOS will have to initiate the PPPoE connection and control @@ -51,7 +52,7 @@ configure it to open the PPPoE session for you and your DSL Transceiver vDSL/aDSL understands. Configuration Example -~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^ Requirements: @@ -95,7 +96,7 @@ assigning it to the pppoe0 itself as shown here: set interfaces ethernet eth0 pppoe 0 firewall out name NET-OUT VLAN Example -++++++++++++ +"""""""""""" Some recent ISPs require you to build the PPPoE connection through a VLAN interface. One of those ISPs is e.g. Deutsche Telekom in Germany. VyOS @@ -116,7 +117,7 @@ which is the default VLAN for Deutsche Telekom: set interfaces ethernet eth0 vif 7 pppoe 0 password 'secret' Troubleshooting ---------------- +^^^^^^^^^^^^^^^ .. opcmd:: disconnect interface -- cgit v1.2.3 From 52f5d4f1d9400a28d5ab4f8f2e5e45d84d657357 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sat, 21 Dec 2019 19:29:49 +0100 Subject: pppoe: indent opcmd explanations by 3 --- docs/interfaces/pppoe.rst | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) (limited to 'docs') diff --git a/docs/interfaces/pppoe.rst b/docs/interfaces/pppoe.rst index f96beb50..9888d682 100644 --- a/docs/interfaces/pppoe.rst +++ b/docs/interfaces/pppoe.rst @@ -51,8 +51,8 @@ configure it to open the PPPoE session for you and your DSL Transceiver (Modem/Router) just acts to translate your messages in a way that vDSL/aDSL understands. -Configuration Example -^^^^^^^^^^^^^^^^^^^^^ +Example +======= Requirements: @@ -96,7 +96,7 @@ assigning it to the pppoe0 itself as shown here: set interfaces ethernet eth0 pppoe 0 firewall out name NET-OUT VLAN Example -"""""""""""" +------------ Some recent ISPs require you to build the PPPoE connection through a VLAN interface. One of those ISPs is e.g. Deutsche Telekom in Germany. VyOS @@ -117,30 +117,31 @@ which is the default VLAN for Deutsche Telekom: set interfaces ethernet eth0 vif 7 pppoe 0 password 'secret' Troubleshooting -^^^^^^^^^^^^^^^ +=============== .. opcmd:: disconnect interface -Test disconnecting given connection-oriented interface. `` can be -``pppoe0`` as example. + Test disconnecting given connection-oriented interface. `` can be + ``pppoe0`` as example. .. opcmd:: connect interface -Test connecting given connection-oriented interface. `` can be -``pppoe0`` as example. + Test connecting given connection-oriented interface. `` can be + ``pppoe0`` as example. .. opcmd:: show interfaces pppoe -Check PPPoE connection logs with the following command which shows the current -statistics, status and some of the settings (i.e. MTU) for the current -connection on (e.g. ``pppoe0``) + Check PPPoE connection logs with the following command which shows the + current statistics, status and some of the settings (i.e. MTU) for the + current connection on (e.g. ``pppoe0``) .. opcmd:: show interfaces pppoe log -Show entire log for the PPPoE connection starting with the oldest data. Scroll -down with the key to reach the end where the current data is. + Show entire log for the PPPoE connection starting with the oldest data. + Scroll down with the key to reach the end where the current data is. .. opcmd:: show interfaces pppoe log tail -Shows the same log as without the 'tail' option but start with the last few -lines and continues to show added lines until you exit with ``Ctrl + x`` + Shows the same log as without the 'tail' option but start with the last few + lines and continues to show added lines until you exit with ``Ctrl + x`` + -- cgit v1.2.3 From 66c64bd3a30ea8ffbbaf9fa5c8d657d815bb0392 Mon Sep 17 00:00:00 2001 From: Jernej Jakob Date: Sat, 21 Dec 2019 12:08:54 +0100 Subject: dhcp: T1806: explain how to use quote characters inside raw parameters --- docs/services/dhcp.rst | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/services/dhcp.rst b/docs/services/dhcp.rst index ed5082d4..94efeaf1 100644 --- a/docs/services/dhcp.rst +++ b/docs/services/dhcp.rst @@ -317,12 +317,24 @@ Always verify that the parameters are correct before commiting the configuration Refer to isc-dhcp's dhcpd.conf manual for more information: https://kb.isc.org/docs/isc-dhcp-44-manual-pages-dhcpdconf +Quotes can be used inside parameter values by replacing all quote characters +with the string ``"``. They will be replaced with literal quote characters +when generating dhcpd.conf. + Example ^^^^^^^ .. opcmd:: set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option domain-name-servers 192.0.2.11, 192.0.2.12;" - Override the static-mapping's dns-server with a custom one that will be sent only to this host. + Override the static-mapping's dns-server with a custom one that will be sent + only to this host. + +.. opcmd:: set service dhcp-server shared-network-name dhcpexample subnet 192.0.2.0/24 static-mapping example static-mapping-parameters "option pxelinux.configfile "pxelinux.cfg/01-00-15-17-44-2d-aa";" + + An option that takes a quoted string is set by replacing all quote characters + with the string ``"`` inside the static-mapping-parameters value. + The resulting line in dhcpd.conf will be + ``option pxelinux.configfile "pxelinux.cfg/01-00-15-17-44-2d-aa";``. Operation Mode -------------- -- cgit v1.2.3 From fe343f5a824dc663896fb63af33e201cc2146b68 Mon Sep 17 00:00:00 2001 From: Jernej Jakob Date: Sat, 21 Dec 2019 15:45:22 +0100 Subject: contribution: build: add section about building packages This is copied from the vyos-build README.md with some changes and updates. --- docs/contributing/build-vyos.rst | 102 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) (limited to 'docs') diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst index bc113750..d158594e 100644 --- a/docs/contributing/build-vyos.rst +++ b/docs/contributing/build-vyos.rst @@ -121,6 +121,108 @@ Good luck! or ``rolling`` image. Make sure to choose the matching container for the version of VyOS that is being built. +.. _build_packages: + +Build packages +-------------- + +VyOS requires a bunch of packages which are VyOS specific and thus can not be +found in any Debian Upstream mirrror. Those packages can be found at the VyOS +GitHub project (https://github.com/vyos) and there is a nice helper script +available to build and list those individual packages. + +`scripts/build-packages` provides an easy interface to automate the process +of building all VyOS related packages that are not part of the upstream Debian +version. Execute it in the root of the `vyos-build` directory to start +compilation. + +.. code-block:: none + + $ scripts/build-packages -h + usage: build-packages [-h] [-c | -k | -f] [-v] [-l] [-b BUILD [BUILD ...]] + [-p] [--blacklist BLACKLIST [BLACKLIST ...]] + + optional arguments: + -h, --help show this help message and exit + -c, --clean Re-clone required Git repositories + -k, --keep Keep modified Git repositories + -f, --fetch Fetch sources only, no build + -v, --verbose Increase logging verbosity for each occurance + -l, --list-packages List all packages to build + -b BUILD [BUILD ...], --build BUILD [BUILD ...] + Whitespace separated list of packages to build + -p, --parallel Build on all CPUs + --blacklist BLACKLIST [BLACKLIST ...] + Do not build/report packages when calling --list + +Git repositoriers are automatically fetched and build on demand. If you want to +work offline you can fetch all source code first with the `-f` option. + +The easiest way to compile is with the above mentioned Docker +container, it includes all dependencies for compiling supported packages. + +.. code-block:: none + + $ docker run --rm -it -v $(pwd):/vyos -w /vyos \ + --sysctl net.ipv6.conf.lo.disable_ipv6=0 \ + vyos-builder scripts/build-packages + +.. note:: `--sysctl net.ipv6.conf.lo.disable_ipv6=0` is required to build the + `vyos-strongswan` package + +.. note:: Prior to executing this script you need to create or build the Docker + container and checkout all packages you want to compile. + +Building single package(s) +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To build a single package use the same script as above but specify packages with +`-b`: + +Executed from the root of `vyos-build` + +.. code-block:: none + + $ docker run --rm -it -v $(pwd):/vyos -w /vyos/packages/PACKAGENAME \ + --sysctl net.ipv6.conf.lo.disable_ipv6=0 \ + vyos-builder scripts/build-packages -b + +.. 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: -- cgit v1.2.3 From 158bd1f9d4c077368f5850eee485689f19a35202 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sat, 21 Dec 2019 19:54:40 +0100 Subject: dummy: extend interface documentation --- docs/interfaces/dummy.rst | 88 +++++++++++++++++++++++++++++++++++++------- docs/interfaces/ethernet.rst | 4 +- 2 files changed, 77 insertions(+), 15 deletions(-) (limited to 'docs') diff --git a/docs/interfaces/dummy.rst b/docs/interfaces/dummy.rst index 9dbb9668..77bd3cc2 100644 --- a/docs/interfaces/dummy.rst +++ b/docs/interfaces/dummy.rst @@ -1,25 +1,87 @@ .. _dummy-interface: +##### Dummy ------ +##### +The dummy interface is really a little exotic, but rather useful nevertheless. Dummy interfaces are much like the loopback interface, except you can have as many as you want. Dummy interfaces can be used as interfaces that always stay up (in the same fashion to loopbacks in Cisco IOS), or for testing purposes. -Configuration commands: +Configuration +############# -.. code-block:: none +Address +------- + +.. cfgcmd:: set interfaces dummy '' address
+ + Configure dummy 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 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 '' description '' + + Assign given `` to interface. Description will also be passed + to SNMP monitoring systems. + +.. cfgcmd:: set interfaces dummy '' disable + + Disable given ``. 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 '' + + Show detailed information on given `` + + .. code-block:: + + vyos@vyos:~$ show interfaces ethernet eth0 + dum0: 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 diff --git a/docs/interfaces/ethernet.rst b/docs/interfaces/ethernet.rst index 4a5abded..d9d14299 100644 --- a/docs/interfaces/ethernet.rst +++ b/docs/interfaces/ethernet.rst @@ -95,7 +95,7 @@ Link Administration .. cfgcmd:: set interfaces ethernet '' disable - Disable given ethernet interface. It will be placed in administratively down + Disable given ``. It will be placed in administratively down state. .. cfgcmd:: set interfaces ethernet '' disable-flow-control @@ -132,7 +132,7 @@ Operation .. opcmd:: show interfaces ethernet - Show Ethernet interface information + Show brief interface information. .. code-block:: none -- cgit v1.2.3 From 79ccadbccbab3a44fd46b1a25940ffd26bee9554 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sat, 21 Dec 2019 19:56:28 +0100 Subject: interfaces: basic: rename to "Basic Interfaces" --- docs/interfaces/basic-index.rst | 46 +++-------------------------------------- 1 file changed, 3 insertions(+), 43 deletions(-) (limited to 'docs') diff --git a/docs/interfaces/basic-index.rst b/docs/interfaces/basic-index.rst index 4f950a2b..a59d8c47 100644 --- a/docs/interfaces/basic-index.rst +++ b/docs/interfaces/basic-index.rst @@ -1,48 +1,8 @@ .. _basic_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 `` -command. - -.. code-block:: none - - vyos@vyos:~$ show interfaces ethernet eth0 - eth0: 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. - +################ +Basic Interfaces +################ .. toctree:: :maxdepth: 2 -- cgit v1.2.3 From 954ee55be75d799b57350cc3926b2a7e14d85858 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sat, 21 Dec 2019 19:58:15 +0100 Subject: interfaces: rename index to advanced-index --- docs/index.rst | 2 +- docs/interfaces/advanced-index.rst | 19 ++++++++++++ docs/interfaces/index.rst | 59 -------------------------------------- 3 files changed, 20 insertions(+), 60 deletions(-) create mode 100644 docs/interfaces/advanced-index.rst delete mode 100644 docs/interfaces/index.rst (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index 93541f39..affde670 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -33,7 +33,7 @@ VyOS User Guide :name: advanced :maxdepth: 2 - interfaces/index + interfaces/advanced-index services/index system/index firewall diff --git a/docs/interfaces/advanced-index.rst b/docs/interfaces/advanced-index.rst new file mode 100644 index 00000000..9f137198 --- /dev/null +++ b/docs/interfaces/advanced-index.rst @@ -0,0 +1,19 @@ +.. _network-interfaces: + +################## +Network Interfaces +################## + +.. toctree:: + :maxdepth: 2 + + dummy + bridge + bond + l2tpv3 + wireless + tunnel + vlan + qinq + vxlan + geneve diff --git a/docs/interfaces/index.rst b/docs/interfaces/index.rst deleted file mode 100644 index 95f60d11..00000000 --- a/docs/interfaces/index.rst +++ /dev/null @@ -1,59 +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 `` -command. - -.. code-block:: none - - vyos@vyos:~$ show interfaces ethernet eth0 - eth0: 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 - - dummy - bridge - bond - l2tpv3 - wireless - tunnel - vlan - qinq - vxlan - geneve -- cgit v1.2.3 From acd4109c2d4b07ef7427619f93cccbd6c6e68b80 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sat, 21 Dec 2019 19:58:35 +0100 Subject: interfaces: delete obsolete addresses.rst --- docs/interfaces/addresses.rst | 174 ------------------------------------------ 1 file changed, 174 deletions(-) delete mode 100644 docs/interfaces/addresses.rst (limited to 'docs') diff --git a/docs/interfaces/addresses.rst b/docs/interfaces/addresses.rst deleted file mode 100644 index 3fc9b89b..00000000 --- a/docs/interfaces/addresses.rst +++ /dev/null @@ -1,174 +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 - - - -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 ipv6 router-advert send-advert - - -To set the options described in "Router Advertisement Message Format": - -.. code-block:: none - - vyos@vyos# set interfaces 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 ipv6 router-advert prefix - 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..accept_ra value 2 - -- cgit v1.2.3 From e0cc028ed45ff2130ac99d6a9707fca7a47c3e71 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sat, 21 Dec 2019 20:03:00 +0100 Subject: Fix warnings on code-block and inline directives --- docs/interfaces/dummy.rst | 2 +- docs/interfaces/ethernet.rst | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/interfaces/dummy.rst b/docs/interfaces/dummy.rst index 77bd3cc2..1b35cefd 100644 --- a/docs/interfaces/dummy.rst +++ b/docs/interfaces/dummy.rst @@ -69,7 +69,7 @@ Operation Show detailed information on given `` - .. code-block:: + .. code-block:: none vyos@vyos:~$ show interfaces ethernet eth0 dum0: mtu 1500 qdisc noqueue state UNKNOWN group default qlen 1000 diff --git a/docs/interfaces/ethernet.rst b/docs/interfaces/ethernet.rst index d9d14299..d0537b41 100644 --- a/docs/interfaces/ethernet.rst +++ b/docs/interfaces/ethernet.rst @@ -33,10 +33,10 @@ Address .. cfgcmd:: set interfaces ethernet '' ipv6 address autoconf - :abbr:`SLAAC (Stateless Address Autoconfiguration)` is specified in + :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. + (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 @@ -148,7 +148,7 @@ Operation Show detailed information on given `` - .. code-block:: + .. code-block:: none vyos@vyos:~$ show interfaces ethernet eth0 eth0: mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 @@ -165,7 +165,7 @@ Operation Show information about physical `` - .. code-block:: + .. code-block:: none vyos@vyos:~$ show interfaces ethernet eth0 physical Settings for eth0: -- cgit v1.2.3 From e3c3a6917be3a41a48847a7775a1baeb218ef974 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sat, 21 Dec 2019 20:05:03 +0100 Subject: interfaces: set toc maxdepth to 1 --- docs/interfaces/advanced-index.rst | 2 +- docs/interfaces/basic-index.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/interfaces/advanced-index.rst b/docs/interfaces/advanced-index.rst index 9f137198..00c1c73e 100644 --- a/docs/interfaces/advanced-index.rst +++ b/docs/interfaces/advanced-index.rst @@ -5,7 +5,7 @@ Network Interfaces ################## .. toctree:: - :maxdepth: 2 + :maxdepth: 1 dummy bridge diff --git a/docs/interfaces/basic-index.rst b/docs/interfaces/basic-index.rst index a59d8c47..3477b238 100644 --- a/docs/interfaces/basic-index.rst +++ b/docs/interfaces/basic-index.rst @@ -5,7 +5,7 @@ Basic Interfaces ################ .. toctree:: - :maxdepth: 2 + :maxdepth: 1 ethernet pppoe -- cgit v1.2.3 From 46466561cd16890a51a08e93924d6f8d48b5a7b7 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Mon, 23 Dec 2019 09:19:43 +0100 Subject: lldp: we now have multiple IPv4/IPv6 management addresses --- docs/services/lldp.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/services/lldp.rst b/docs/services/lldp.rst index c1f39fba..da52adb0 100644 --- a/docs/services/lldp.rst +++ b/docs/services/lldp.rst @@ -40,7 +40,8 @@ Configuration .. cfgcmd:: set service lldp management-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 -- cgit v1.2.3 From ed9bd9815a1a8341bad29d228015ad536c586cb6 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Mon, 23 Dec 2019 09:28:26 +0100 Subject: lldp: update 'show lldp neighbors' examples --- docs/services/lldp.rst | 103 ++++++++++++++++++++++++------------------------- 1 file changed, 51 insertions(+), 52 deletions(-) (limited to 'docs') diff --git a/docs/services/lldp.rst b/docs/services/lldp.rst index da52adb0..4b1743e6 100644 --- a/docs/services/lldp.rst +++ b/docs/services/lldp.rst @@ -73,65 +73,64 @@ Operation Displays information about all neighbors discovered via LLDP. -.. code-block:: none + .. code-block:: none - vyos@vyos:~# show lldp neighbors - Capability Codes: R - Router, B - Bridge, W - Wlan r - Repeater, S - Station - D - Docsis, T - Telephone, O - Other + vyos@vyos:~$ show lldp neighbors + Capability Codes: R - Router, B - Bridge, W - Wlan r - Repeater, S - Station + D - Docsis, T - Telephone, O - Other - Device ID Local Proto Cap Platform Port ID - --------- ----- ----- --- -------- ------- - Switch0815 eth0 LLDP B Cisco IOS Software, Gi0/4 + Device ID Local Proto Cap Platform Port ID + --------- ----- ----- --- -------- ------- + BR2.vyos.net eth0 LLDP R VyOS 1.2.4 eth1 + BR3.vyos.net eth0 LLDP RB VyOS 1.2.4 eth2 + SW1.vyos.net eth0 LLDP B Cisco IOS Software GigabitEthernet0/6 .. opcmd:: show lldp neighbors detail Get detailed information about LLDP neighbors. -.. code-block:: none - - vyos@vyos:~# show lldp neighbors detail - ------------------------------------------------------------------------------- - LLDP neighbors: - ------------------------------------------------------------------------------- - Interface: eth0, via: LLDP, RID: 1, Time: 12 days, xxxx:xxxx:40 - Chassis: - ChassisID: mac 00:50:40:20:03:00 - SysName: Switch0815 - SysDescr: Cisco IOS Software, C2960 Software (C2960-LANBASEK9-M), Version 15.0(2)SE11, RELEASE SOFTWARE (fc3) - Technical Support: http://www.cisco.com/techsupport - Copyright (c) 1986-2017 by Cisco Systems, Inc. - Compiled Sat 19-Aug-17 09:34 by prod_rel_team - MgmtIP: 192.0.2.201 - Capability: Bridge, on - Port: - PortID: ifname Gi0/4 - PortDescr: GigabitEthernet0/4 - TTL: 120 - PMD autoneg: supported: yes, enabled: yes - Adv: 10Base-T, HD: yes, FD: yes - Adv: 100Base-TX, HD: yes, FD: yes - Adv: 1000Base-T, HD: no, FD: yes - MAU oper type: 1000BaseTFD - Four-pair Category 5 UTP, full duplex mode - VLAN: 1, pvid: yes - LLDP-MED: - Device Type: Network Connectivity Device - Capability: Capabilities, yes - Capability: Policy, yes - Capability: Location, yes - Capability: Inventory, yes - LLDP-MED Network Policy for: Voice, Defined: no - Priority: Best effort - PCP: 0 - DSCP Value: 0 - LLDP-MED Network Policy for: Voice Signaling, Defined: no - Priority: Best effort - PCP: 0 - DSCP Value: 0 - Inventory: - Hardware Revision: WS-C2960G-8TC-L (PowerPC405):C0 - Software Revision: 15.0(2)SE11 - Manufacturer: Cisco Systems, Inc. - Model: WS-C2960G-8TC-L + .. code-block:: none + + vyos@vyos:~$ show lldp neighbors detail + ------------------------------------------------------------------------------- + LLDP neighbors: + ------------------------------------------------------------------------------- + Interface: eth0, via: LLDP, RID: 28, Time: 0 day, 00:24:33 + Chassis: + ChassisID: mac 00:53:00:01:02:c9 + SysName: BR2.vyos.net + SysDescr: VyOS 1.3-rolling-201912230217 + MgmtIP: 192.0.2.1 + MgmtIP: 2001:db8::ffff + Capability: Bridge, on + Capability: Router, on + Capability: Wlan, off + Capability: Station, off + Port: + PortID: mac 00:53:00:01:02:c9 + PortDescr: eth0 + TTL: 120 + PMD autoneg: supported: no, enabled: no + MAU oper type: 10GigBaseCX4 - X copper over 8 pair 100-Ohm balanced cable + VLAN: 201 eth0.201 + VLAN: 205 eth0.205 + LLDP-MED: + Device Type: Network Connectivity Device + Capability: Capabilities, yes + Capability: Policy, yes + Capability: Location, yes + Capability: MDI/PSE, yes + Capability: MDI/PD, yes + Capability: Inventory, yes + Inventory: + Hardware Revision: None + Software Revision: 4.19.89-amd64-vyos + Firmware Revision: 6.00 + Serial Number: VMware-42 1d 83 b9 fe c1 bd b2-7 + Manufacturer: VMware, Inc. + Model: VMware Virtual Platform + Asset ID: No Asset Tag + ------------------------------------------------------------------------------- .. opcmd:: show lldp neighbors interface -- cgit v1.2.3 From b020164f7efb14b85ef436d1cddab17a888236d3 Mon Sep 17 00:00:00 2001 From: zsdc Date: Tue, 24 Dec 2019 23:53:29 +0200 Subject: Extended flow-accounting documentation - added information about sFlow - replaced op-mode examples by modern ones --- docs/system/flow-accounting.rst | 106 ++++++++++++++++++++++++++++++---------- 1 file changed, 80 insertions(+), 26 deletions(-) (limited to 'docs') diff --git a/docs/system/flow-accounting.rst b/docs/system/flow-accounting.rst index 4f566490..6b204ae6 100644 --- a/docs/system/flow-accounting.rst +++ b/docs/system/flow-accounting.rst @@ -4,6 +4,19 @@ Flow Accounting ############### +VyOS supports flow-accounting for both IPv4 and IPv6 traffic. The system acts as a +flow exporter, and you are free to use it with any compatible collector. + +Flows can be exported via two different protocols: NetFlow (versions 5, 9 and 10/IPFIX) +and sFlow. Additionally, you may save flows to an in-memory table internally in a router. + +.. warning:: You need to disable the in-memory table in production environments! + Using :abbr:`IMT (In-Memory Table)` may lead to heavy CPU overloading and + unstable flow-accounting behavior. + + +NetFlow / IPFIX +=============== NetFlow is a feature that was introduced on Cisco routers around 1996 that provides the ability to collect IP network traffic as it enters or exits an interface. By analyzing the data provided by NetFlow, a network administrator @@ -39,15 +52,40 @@ interface, the interface must be configured for flow accounting. You can configure multiple interfaces which whould participate in flow accounting. +.. note:: Will be recorded only packets/flows on **incoming** directinon + 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 '' + +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 '' + + Flow Export ----------- In addition to displaying flow accounting information locally, one can also exported them to a collection server. +NetFlow +^^^^^^^ + .. cfgcmd:: set system flow-accounting netflow version '' - There are multiple versions available for the NetFlo data. The `` + There are multiple versions available for the NetFlow data. The `` used in the exported flow data can be configured here. The following versions are supported: @@ -85,6 +123,31 @@ exported them to a collection server. Specifies the interval at which Netflow data will be sent to a collector. As per default, Netflow data will be sent every 60 seconds. + You may also additionally configure timeouts for different types of connections. + +.. cfgcmd:: set system flow-accounting netflow max-flows '' + + 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 '
' + + Configure address of sFlow collector. sFlow server at `
` 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 '' + + Enable sampling of packets, which will be transmitted to sFlow collectors. + +.. cfgcmd:: set system flow-accounting sflow agent-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: -------- @@ -110,26 +173,16 @@ display captured network traffic information for all configured interfaces. .. code-block:: none vyos@vyos:~$ show flow-accounting interface eth0 - flow-accounting for [eth0] - Src Addr Dst Addr Sport Dport Proto Packets Bytes Flows - 0.0.0.0 192.0.2.50 811 811 udp 7733 591576 0 - 0.0.0.0 192.0.2.50 811 811 udp 7669 586558 1 - 192.0.2.200 192.0.2.51 56188 22 tcp 586 36504 1 - 192.0.2.99 192.0.2.51 61636 161 udp 46 6313 4 - 192.0.2.99 192.0.2.51 61638 161 udp 42 5364 9 - 192.0.2.99 192.0.2.51 61640 161 udp 42 5111 3 - 192.0.2.200 192.0.2.51 54702 22 tcp 86 4432 1 - 192.0.2.99 192.0.2.51 62509 161 udp 24 3540 1 - 192.0.2.99 192.0.2.51 0 0 icmp 49 2989 8 - 192.0.2.99 192.0.2.51 54667 161 udp 18 2658 1 - 192.0.2.99 192.0.2.51 54996 161 udp 18 2622 1 - 192.0.2.99 192.0.2.51 63708 161 udp 18 2622 1 - 192.0.2.99 192.0.2.51 62111 161 udp 18 2622 1 - 192.0.2.99 192.0.2.51 61646 161 udp 16 1977 4 - 192.0.2.99 192.0.2.51 56038 161 udp 10 1256 1 - 192.0.2.99 192.0.2.51 55570 161 udp 6 1146 1 - 192.0.2.99 192.0.2.51 54599 161 udp 6 1134 1 - 192.0.2.99 192.0.2.51 56304 161 udp 8 1029 1 + IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES + ---------- ----------------- ----------------- ------------------------ --------------- ---------- ---------- ---------- ----- --------- ------- ------- + eth0 00:53:01:a8:28:ac ff:ff:ff:ff:ff:ff 192.0.2.2 255.255.255.255 5678 5678 udp 0 1 1 178 + eth0 00:53:01:b2:2f:34 33:33:ff:00:00:00 fe80::253:01ff:feb2:2f34 ff02::1:ff00:0 0 0 ipv6-icmp 0 2 1 144 + eth0 00:53:01:1a:b4:53 33:33:ff:00:00:00 fe80::253:01ff:fe1a:b453 ff02::1:ff00:0 0 0 ipv6-icmp 0 1 1 72 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 39 1 2064 + eth0 00:53:01:c8:33:af ff:ff:ff:ff:ff:ff 192.0.2.3 255.255.255.255 5678 5678 udp 0 1 1 154 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 146 1 9444 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 27 1 4455 + .. opcmd:: show flow-accounting interface '' host '
' @@ -139,8 +192,9 @@ display captured network traffic information for all configured interfaces. .. code-block:: none - vyos@vyos:~$ show flow-accounting interface eth0 host 192.0.2.200 - flow-accounting for [eth0] - Src Addr Dst Addr Sport Dport Proto Packets Bytes Flows - 192.0.2.200 192.0.2.51 56188 22 tcp 586 36504 1 - 192.0.2.200 192.0.2.51 54702 22 tcp 86 4432 1 + vyos@vyos:~$ show flow-accounting interface eth0 host 192.0.2.14 + IN_IFACE SRC_MAC DST_MAC SRC_IP DST_IP SRC_PORT DST_PORT PROTOCOL TOS PACKETS FLOWS BYTES + ---------- ----------------- ----------------- ----------- ---------- ---------- ---------- ---------- ----- --------- ------- ------- + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 197 2 12940 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40152 22 tcp 16 94 1 4924 + eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 36 1 5877 -- cgit v1.2.3 From 49879dfc0cd004d036741456e6412a8dfca3bff7 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sat, 28 Dec 2019 19:33:12 +0100 Subject: flow-accounting: break after 80 characters --- docs/system/flow-accounting.rst | 51 +++++++++++++++++++++-------------------- 1 file changed, 26 insertions(+), 25 deletions(-) (limited to 'docs') diff --git a/docs/system/flow-accounting.rst b/docs/system/flow-accounting.rst index 6b204ae6..52a2a18d 100644 --- a/docs/system/flow-accounting.rst +++ b/docs/system/flow-accounting.rst @@ -4,14 +4,15 @@ 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. +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. +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 + Using :abbr:`IMT (In-Memory Table)` may lead to heavy CPU overloading and unstable flow-accounting behavior. @@ -31,8 +32,8 @@ NetFlow) consists of three main components: * **application**: analyzes received flow data in the context of intrusion detection or traffic profiling, for example -For connectionless protocols as like ICMP and UDP, a flow is considered complete -once no more packets for this flow appear after configurable timeout. +For connectionless protocols as like ICMP and UDP, a flow is considered +complete once no more packets for this flow appear after configurable timeout. NetFlow is usually enabled on a per-interface basis to limit load on the router components involved in NetFlow, or to limit the amount of NetFlow records @@ -52,23 +53,24 @@ interface, the interface must be configured for flow accounting. You can configure multiple interfaces which whould participate in flow accounting. -.. note:: Will be recorded only packets/flows on **incoming** directinon - in configured interfaces. +.. 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: +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: +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 '' -In case, if you need to catch some logs from flow-accounting daemon, you may +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 '' @@ -123,19 +125,20 @@ NetFlow Specifies the interval at which Netflow data will be sent to a collector. As per default, Netflow data will be sent every 60 seconds. - You may also additionally configure timeouts for different types of connections. + You may also additionally configure timeouts for different types of + connections. .. cfgcmd:: set system flow-accounting netflow max-flows '' - If you want to change the maximum number of flows, which are tracking simultaneously, - you may do this with this command (default 8192). + 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 '
' Configure address of sFlow collector. sFlow server at `
` can - be an IPv4 or IPv6 address. But you cannot export to both IPv4 and + 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 '' @@ -144,9 +147,9 @@ sFlow .. cfgcmd:: set system flow-accounting sflow agent-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 + 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: @@ -183,8 +186,6 @@ display captured network traffic information for all configured interfaces. eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 146 1 9444 eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 27 1 4455 - - .. opcmd:: show flow-accounting interface '' host '
' Show flow accounting information for given `` for a specific host -- cgit v1.2.3 From 499f536d5b6b5f5bc45c649abdab5c007cda30a6 Mon Sep 17 00:00:00 2001 From: Daniil Baturin Date: Sun, 29 Dec 2019 04:24:42 +0700 Subject: Add release notes for 1.2.4 --- docs/appendix/releasenotes.rst | 64 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) (limited to 'docs') diff --git a/docs/appendix/releasenotes.rst b/docs/appendix/releasenotes.rst index 13e8fa1c..d2601c2c 100644 --- a/docs/appendix/releasenotes.rst +++ b/docs/appendix/releasenotes.rst @@ -6,6 +6,70 @@ Release notes 1.2 (Crux) ========== +1.2.4 +----- + +1.2.4 is a maintenance release made in December 2019. + +Resolved issues +^^^^^^^^^^^^^^^ + +* `T258 `_ Can not configure wan load-balancing on vyos-1.2 +* `T818 `_ SNMP v3 - remove required engineid from user node +* `T1030 `_ Upgrade ddclient from 3.8.2 to 3.9.0 (support Cloudflare API v4) +* `T1183 `_ BFD Support via FRR +* `T1299 `_ Allow SNMPd to be extended with custom scripts +* `T1351 `_ accel-pppoe adding CIDR based IP pool option +* `T1391 `_ In route-map set community additive +* `T1394 `_ syslog systemd and host_name.py race condition +* `T1401 `_ Copying files with the FTP protocol fails if the password contains special characters +* `T1421 `_ OpenVPN client push-route stopped working, needs added quotes to fix +* `T1447 `_ Python subprocess called without import in host_name.py +* `T1470 `_ improve output of "show dhcpv6 server leases" +* `T1485 `_ Enable 'AdvIntervalOpt' option in for radvd.conf +* `T1496 `_ Separate rolling release and LTS kernel builds +* `T1560 `_ "set load-balancing wan rule 0" causes segfault and prevents load balancing from starting +* `T1568 `_ strip-private command improvement for additional masking of IPv6 and MAC address +* `T1578 `_ completion offers "show table", but show table does not exist +* `T1593 `_ Support ip6gre +* `T1597 `_ /usr/sbin/rsyslogd after deleting "system syslog" +* `T1638 `_ vyos-hostsd not setting system domain name +* `T1678 `_ hostfile-update missing line feed +* `T1694 `_ NTPd: Do not listen on all interfaces by default +* `T1701 `_ Delete domain-name and domain-search won't work +* `T1705 `_ High CPU usage by bgpd when snmp is active +* `T1707 `_ DHCP static mapping and exclude address not working +* `T1708 `_ Update Rolling Release Kernel to 4.19.76 +* `T1709 `_ Update WireGuard to 0.0.20190913 +* `T1716 `_ Update Intel NIC drivers to recent versions +* `T1726 `_ Update Linux Firmware binaries to a more recent version 2019-03-14 -> 2019-10-07 +* `T1728 `_ Update Linux Kernel to 4.19.79 +* `T1737 `_ SNMP tab completion missing +* `T1738 `_ Copy SNMP configuration from node to node raises exception +* `T1740 `_ Broken OSPFv2 virtual-link authentication +* `T1742 `_ NHRP unable to commit. +* `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 +* `T1749 `_ numeric validator doesn't support multiple ranges +* `T1769 `_ Remove complex SNMPv3 Transport Security Model (TSM) +* `T1772 `_ constraints in XML are partially broken +* `T1778 `_ Kilobits/Megabits difference in configuration Vyos/FRR +* `T1780 `_ Adding ipsec ike closeaction +* `T1786 `_ disable-dhcp-nameservers is missed in current host_name.py implementation +* `T1788 `_ Intel QAT (QuickAssist Technology ) implementation +* `T1792 `_ Update WireGuard to Debian release 0.0.20191012-1 +* `T1800 `_ Update Linux Kernel to v4.19.84 +* `T1809 `_ Wireless: SSID scan does not work in AP mode +* `T1811 `_ Upgrade from 1.1.8: Config file migration failed: module=l2tp +* `T1812 `_ DHCP: hostnames of clients not resolving after update v1.2.3 -> 1.2-rolling +* `T1819 `_ Reboot kills SNMPv3 configuration +* `T1822 `_ Priority inversion wireless interface dhcpv6 +* `T1836 `_ import-conf-mode-commands in vyos-1x/scripts fails to create an xml +* `T1839 `_ LLDP shows "VyOS unknown" instead of "VyOS" +* `T1841 `_ PPP ipv6-up.d direcotry missing +* `T1893 `_ igmp-proxy: Do not allow adding unknown interface +* `T1904 `_ update eth1 and eth2 link files for the vep4600 + + 1.2.3 ----- -- cgit v1.2.3 From ef0b747f39b9187bc631442396d2e720f952194f Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sat, 28 Dec 2019 22:59:58 +0100 Subject: dns-forwarding: minor fixes - remove redundant "be" - proper indent note block --- docs/services/dns-forwarding.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/services/dns-forwarding.rst b/docs/services/dns-forwarding.rst index fb996709..a529f6a7 100644 --- a/docs/services/dns-forwarding.rst +++ b/docs/services/dns-forwarding.rst @@ -29,9 +29,10 @@ avoid to be tracked by the provider of your upstream DNS server. .. cfgcmd:: set service dns forwarding domain server
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 @@ -71,8 +72,8 @@ avoid to be tracked by the provider of your upstream DNS server. as with process. * **validate** The highest mode of DNSSEC processing. In this mode, all - queries will be be validated and will be answered with a SERVFAIL in case - of bogus data, regardless of the client's request. + queries will be validated and will be answered with a SERVFAIL in case of + bogus data, regardless of the client's request. .. note:: The famous UNIX/Linux ``dig`` tool sets the AD-bit in the query. This might lead to unexpected query results when testing. Set ``+noad`` -- cgit v1.2.3 From a2e9f5d2030c59908beb3075c53b383d2e454d62 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 29 Dec 2019 09:06:36 +0100 Subject: host-information: fix broken reference --- docs/system/host-information.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/system/host-information.rst b/docs/system/host-information.rst index 89f1c6ad..e4cbd584 100644 --- a/docs/system/host-information.rst +++ b/docs/system/host-information.rst @@ -44,7 +44,7 @@ unqualified name of `crux`, then VyOS qualifies the name to `crux.example.com`. Static Hostname Mapping ======================= -How an IP address is assigned to an interface in :ref:`interfaces-addresses`. +How an IP address is assigned to an interface in :ref:`ethernet-interface`. This section shows how to statically map an IP address to a hostname for local (meaning on this VyOS instance) name resolution. -- cgit v1.2.3 From b61205ca9d5954385e5de5dbfa27446974c0ac7d Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 29 Dec 2019 09:08:49 +0100 Subject: quick-start: rework headlines --- docs/quick-start.rst | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/quick-start.rst b/docs/quick-start.rst index b1295790..253f093e 100644 --- a/docs/quick-start.rst +++ b/docs/quick-start.rst @@ -34,8 +34,8 @@ Once your configuration works as expected you can save it permanently. save -Network Interface Configuration -############################### +Interface Configuration +####################### * Your outside/WAN interface will be `eth0`, it receives it's interface address be means of DHCP. @@ -52,7 +52,8 @@ commands: set interfaces ethernet eth1 address '192.168.0.1/24' set interfaces ethernet eth1 description 'INSIDE' -Enable Management via SSH + +Enable SSH Management SSH ######################### After switching to :ref:`quick-start-configuration-mode` issue the following @@ -65,8 +66,8 @@ on specific addresses only. set service ssh port '22' -Configure DHCP and DNS server -############################# +Configure DHCP/DNS Servers +########################## * Provide DHCP service on your internal/LAN network where VyOS will act as the default gateway and DNS server. @@ -90,6 +91,7 @@ Configure DHCP and DNS server set service dns forwarding listen-address '192.168.0.1' set service dns forwarding allow-from '192.168.0.0/24' + NAT ### @@ -101,6 +103,7 @@ NAT set nat source rule 100 source address '192.168.0.0/24' set nat source rule 100 translation address masquerade + Firewall ######## @@ -163,10 +166,10 @@ Commit changes, save the configuration, and exit configuration mode: vyos@vyos# exit vyos@vyos$ + QoS ### - One common use of :ref:`qos` is to limit bandwidth for an interface. In the example below we limit bandwidth for our internal/LAN connection to 200 Mbit/s download and our outside/WAN connection to 50 Mbit/s upload: @@ -191,6 +194,7 @@ interface-level traffic-policy directive: set interfaces ethernet eth0 traffic-policy out 'WAN-OUT' set interfaces ethernet eth1 traffic-policy out 'LAN-OUT' + Security Hardening ################## -- cgit v1.2.3 From 21aec14168f723a52f3a7a2e90c9a1075d94de0c Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 29 Dec 2019 10:01:21 +0100 Subject: overview: rewrite with new cfgcmd/opcmd syntax --- docs/configuration-overview.rst | 592 +++++++++++++++++++++------------------- 1 file changed, 305 insertions(+), 287 deletions(-) (limited to 'docs') diff --git a/docs/configuration-overview.rst b/docs/configuration-overview.rst index 352f219c..646f4dea 100644 --- a/docs/configuration-overview.rst +++ b/docs/configuration-overview.rst @@ -4,131 +4,129 @@ Configuration Overview ###################### -VyOS makes use of a unified configuration file for all system configuration: -`config.boot`. This allows for easy template creation, backup, and replication -of system configuration. - -The current active configuration -aka running configuration- can be viewed -using the show configuration command. - -.. code-block:: none - - vyos@vyos:~$ show configuration - interfaces { - ethernet eth0 { - address dhcp - hw-id 00:53:dd:44:3b:0f - } - loopback lo { - } - } - service { - ssh { - port 22 - } - } - system { - config-management { - commit-revisions 20 - } - console { - device ttyS0 { - speed 9600 - } - } - login { - user vyos { - authentication { - encrypted-password **************** - } - level admin - } - } - ntp { - server 0.pool.ntp.org { - } - server 1.pool.ntp.org { - } - server 2.pool.ntp.org { - } - } - syslog { - global { - facility all { - level notice - } - facility protocols { - level debug - } - } - } - } - -By default the configuration is displayed in a hierarchy like the example above, -this is only one of the possible ways to display the configuration. When the -configuration is generated and the device is configured, changes are added -through a collection of ``set`` and ``delete`` commands. - -.. opcmd:: show configuration commands - -Get a collection of all the set commands required which led to this -running configuration. - -.. code-block:: none - - vyos@vyos:~$ show configuration commands - set interfaces ethernet eth0 address 'dhcp' - set interfaces ethernet eth0 hw-id '00:53:dd:44:3b:0f' - set interfaces loopback 'lo' - set service ssh port '22' - set system config-management commit-revisions '20' - set system console device ttyS0 speed '9600' - set system login user vyos authentication encrypted-password '' - set system login user vyos level 'admin' - set system ntp server '0.pool.ntp.org' - set system ntp server '1.pool.ntp.org' - set system ntp server '2.pool.ntp.org' - set system syslog global facility all level 'notice' - set system syslog global facility protocols level 'debug' - -Both these commands should be executed when in operational mode, they do not -work in configuration mode. +VyOS makes use of a unified configuration file for the entire systems +configuration: ``/config/config.boot``. This allows easy template creation, +backup, and replication of system configuration. A sytem can thus also be +easily cloned by simply copying the required configuration files. Terminology =========== A VyOS system has three major types of configurations: -Active/Running --------------- +* **Active/Running** configuration is the system configuration that is loaded + and currently active (used by VyOS). Any change in the configuration will + have to be committed to belong to the active/running configuration. + +* **Working** - is the configuration which is currently being modified in + configuration mode. Changes made to the working configuration do not go into + effect until the changes are committed with the :cfgcmd:`commit` command. At + which time the working configuration will become the active or running + configuration. + +* **Saved** - is a configuration saved to a file using the :cfgcmd:`save` + command. It allows you to keep safe a configuration for future uses. There + can be multiple configuration files. The default or "boot" configuration is + saved and loaded from the file ``/config/config.boot``. -The active or running configuration is the system configuration that is loaded -and currently being used by VyOS. Any change in the configuration will have to -be committed to belong to the active/running configuration. +Work the Config +=============== -Working -------- +.. opcmd:: show configuration + + View the current active configuration, also known as the running + configuration. + + .. code-block:: none + + vyos@vyos:~$ show configuration + interfaces { + ethernet eth0 { + address dhcp + hw-id 00:53:00:00:aa:01 + } + loopback lo { + } + } + service { + ssh { + port 22 + } + } + system { + config-management { + commit-revisions 20 + } + console { + device ttyS0 { + speed 9600 + } + } + login { + user vyos { + authentication { + encrypted-password **************** + } + level admin + } + } + ntp { + server 0.pool.ntp.org { + } + server 1.pool.ntp.org { + } + server 2.pool.ntp.org { + } + } + syslog { + global { + facility all { + level notice + } + facility protocols { + level debug + } + } + } + } + +By default, the configuration is displayed in a hierarchy like the above +example, this is only one of the possible ways to display the configuration. +When the configuration is generated and the device is configured, changes are +added through a collection of :cfgcmd:`set` and :cfgcmd:`delete` commands. -The working configuration is the configuration which is currently being -modified in configuration mode. Changes made to the working configuration do -not go into effect until the changes are committed with the `commit` command. -At which time the working configuration will become the active or running -configuration. +.. opcmd:: show configuration commands -Saved ------ + Get a collection of all the set commands required which led to this + running configuration. + + .. code-block:: none + + vyos@vyos:~$ show configuration commands + set interfaces ethernet eth0 address 'dhcp' + set interfaces ethernet eth0 hw-id '00:53:dd:44:3b:0f' + set interfaces loopback 'lo' + set service ssh port '22' + set system config-management commit-revisions '20' + set system console device ttyS0 speed '9600' + set system login user vyos authentication encrypted-password '' + set system login user vyos level 'admin' + set system ntp server '0.pool.ntp.org' + set system ntp server '1.pool.ntp.org' + set system ntp server '2.pool.ntp.org' + set system syslog global facility all level 'notice' + set system syslog global facility protocols level 'debug' -A saved configuration is a configuration saved to a file using the ``save`` -command. It allows you to keep safe a configuration for future uses. There can -be multiple configuration files. The default or "boot" configuration is saved -and loaded from the file config.boot. +Both these commands should be executed when in operational mode, they do not +work directly in configuration mode. The is a special way on how to +:ref:`run_opmode_from_config_mode`. Navigating ========== When entering the configuration mode you are navigating inside the tree structure exported in the overview above, to enter configuration mode enter -the command ``configure`` when in operational mode. +the command :opcmd:`configure` when in operational mode. .. code-block:: none @@ -136,14 +134,11 @@ the command ``configure`` when in operational mode. [edit] vyos@vyos# -.. note:: When going into configuration mode, prompt changes from *$* to *#*. - To exit configuration mode, type `exit`. - All commands executed here are relative to the configuration level you have entered. You can do everything from the top level, but commands will be quite lengthy when manually typing them. -To change the current hierarchy level use the command: ``edit`` +The current hierarchy level can be changed by the :cfgcmd:`edit` command. .. code-block:: none @@ -155,13 +150,19 @@ To change the current hierarchy level use the command: ``edit`` You are now in a sublevel relative to ``interfaces ethernet eth0``, all commands executed from this point on are relative to this sublevel. Use either -the ``top`` or ``exit`` command to go back to the top of the hierarchy. You can -also use the ``up`` command to move only one level up at a time. +the :cfgcmd:`top` or :cfgcmd:`exit` command to go back to the top of the +hierarchy. You can also use the :cfgcmd:`up` command to move only one level up +at a time. -The ``show`` command within configuration mode will show the working +The :cfgcmd:`show` command within configuration mode will show the working configuration indicating line changes with ``+`` for additions, ``>`` for replacements and ``-`` for deletions. +.. note:: When going into configuration mode, prompt changes from + ``$`` to ``#``. + +**Example:** + .. code-block:: none vyos@vyos:~$ configure @@ -192,7 +193,7 @@ replacements and ``-`` for deletions. } It is also possible to display all `set` commands within configuration mode -using ``show | commands`` +using :cfgcmd:`show | commands` .. code-block:: none @@ -210,9 +211,9 @@ configuration blocks will be displayed when entering a sub-level. address dhcp hw-id 00:53:ad:44:3b:03 -Exiting from the configuration mode is done via the ``exit`` command from the -top level, executing `exit` from within a sub-level takes you back to the top -level. +Exiting from the configuration mode is done via the :cfgcmd:`exit` command from +the top level, executing :cfgcmd:`exit` from within a sub-level takes you back +to the top level. .. code-block:: none @@ -225,14 +226,13 @@ level. Managing ======== -The configuration is managed by the use of ``set`` and ``delete`` commands from -within configuration mode. Configuration commands are flattened from the tree -into 'one-liner' commands shown in ``show configuration commands`` from -operation mode. +The configuration is managed by the use of :cfgcmd:`set` and :cfgcmd:`delete` +commands from within configuration mode. Configuration commands are flattened +from the tree into 'one-liner' commands shown in :opcmd:`show configuration +commands` from operation mode. -These commands are also relative to the level where they are executed and all -redundant information from the current level is removed from the command -entered. +Commands are relative to the level where they are executed and all redundant +information from the current level is removed from the command entered. .. code-block:: none @@ -245,197 +245,214 @@ entered. These two commands above are essentially the same, just executed from different levels in the hierarchy. -To delete a configuration entry use the ``delete`` command, this also deletes -all sub-levels under the current level you've specified in the ``delete`` -command. Deleting an entry will also result in the element reverting back to -its default value if one exists. +.. cfgcmd:: delete -.. code-block:: none + To delete a configuration entry use the :cfgcmd:`delete` command, this also + deletes all sub-levels under the current level you've specified in the + :cfgcmd:`delete` command. Deleting an entry will also result in the element + reverting back to its default value if one exists. - [edit interfaces ethernet eth0] - vyos@vyos# delete address 192.0.2.100/24 + .. code-block:: none -Any change you do on the configuration, will not take effect until committed -using the ``commit`` command in configuration mode. + [edit interfaces ethernet eth0] + vyos@vyos# delete address 192.0.2.100/24 -.. code-block:: none +.. cfgcmd:: commit - vyos@vyos# commit - [edit] - vyos@vyos# exit - Warning: configuration changes have not been saved. - vyos@vyos:~$ + Any change you do on the configuration, will not take effect until committed + using the :cfgcmd:`commit` command in configuration mode. -In order to preserve configuration changes upon reboot, the configuration must -also be saved once applied. This is done using the ``save`` command in -configuration mode. + .. code-block:: none -.. code-block:: none + vyos@vyos# commit + [edit] + vyos@vyos# exit + Warning: configuration changes have not been saved. + vyos@vyos:~$ - vyos@vyos# save - Saving configuration to '/config/config.boot'... - Done +.. cfgcmd:: save -Configuration mode can not be exited while uncommitted changes exist. To exit -configuration mode without applying changes, the exit discard command can be -used. + In order to preserve configuration changes upon reboot, the configuration + must also be saved once applied. This is done using the :cfgcmd:`save` + command in configuration mode. -.. code-block:: none + .. code-block:: none - vyos@vyos# exit - Cannot exit: configuration modified. - Use 'exit discard' to discard the changes and exit. - [edit] - vyos@vyos# exit discard + vyos@vyos# save + Saving configuration to '/config/config.boot'... + Done -.. code-block:: none + .. code-block:: none - vyos@vyos# save [tab] - Possible completions: - Save to system config file - Save to file on local machine - scp://:@/ Save to file on remote machine - ftp://:@/ Save to file on remote machine - tftp:/// Save to file on remote machine - vyos@vyos# save tftp://192.168.0.100/vyos-test.config.boot - Saving configuration to 'tftp://192.168.0.100/vyos-test.config.boot'... - ######################################################################## 100.0% - Done - -Access from config mode -======================= + vyos@vyos# save [tab] + Possible completions: + Save to system config file + Save to file on local machine + scp://:@/ Save to file on remote machine + ftp://:@/ Save to file on remote machine + tftp:/// Save to file on remote machine + vyos@vyos# save tftp://192.168.0.100/vyos-test.config.boot + Saving configuration to 'tftp://192.168.0.100/vyos-test.config.boot'... + ######################################################################## 100.0% + Done -When inside configuration mode you are not directly able to execute operational -commands. +.. cfgcmd:: exit [discard] -Access to these commands are possible through the use of the ``run [command]`` -command. From this command you will have access to everything accessible from -operational mode. + Configuration mode can not be exited while uncommitted changes exist. To + exit configuration mode without applying changes, the :cfgcmd:`exit discard` + command must be used. -Command completion and syntax help with ``?`` and ``[tab]`` will also work. + All changes in the working config will thus be lost. -.. code-block:: none - - [edit] - vyos@vyos# run show interfaces - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - eth0 0.0.0.0/0 u/u - -Archive -======= + .. code-block:: none -VyOS automatically maintains backups of previous configurations. + vyos@vyos# exit + Cannot exit: configuration modified. + Use 'exit discard' to discard the changes and exit. + [edit] + vyos@vyos# exit discard -Local archive and revisions ---------------------------- +.. _run_opmode_from_config_mode: -Revisions are stored on disk. You can view them, compare them, and rollback to -previous revisions if anything goes wrong. - -To view existing revisions, use ``show system commit`` operational mode command. - -.. code-block:: none +Access opmode from config mode +============================== - vyos@vyos-test-2# run show system commit - 0 2015-03-30 08:53:03 by vyos via cli - 1 2015-03-30 08:52:20 by vyos via cli - 2 2015-03-26 21:26:01 by root via boot-config-loader - 3 2015-03-26 20:43:18 by root via boot-config-loader - 4 2015-03-25 11:06:14 by root via boot-config-loader - 5 2015-03-25 01:04:28 by root via boot-config-loader - 6 2015-03-25 00:16:47 by vyos via cli - 7 2015-03-24 23:43:45 by root via boot-config-loader - -To compare configuration revisions in configuration mode, use the compare -command: - -.. code-block:: none - - vyos@vyos# compare [tab] - Possible completions: - Compare working & active configurations - saved Compare working & saved configurations - Compare working with revision N - Compare revision N with M - Revisions: - 0 2013-12-17 20:01:37 root by boot-config-loader - 1 2013-12-13 15:59:31 root by boot-config-loader - 2 2013-12-12 21:56:22 vyos by cli - 3 2013-12-12 21:55:11 vyos by cli - 4 2013-12-12 21:27:54 vyos by cli - 5 2013-12-12 21:23:29 vyos by cli - 6 2013-12-12 21:13:59 root by boot-config-loader - 7 2013-12-12 16:25:19 vyos by cli - 8 2013-12-12 15:44:36 vyos by cli - 9 2013-12-12 15:42:07 root by boot-config-loader - 10 2013-12-12 15:42:06 root by init - -Comparing Revisions -^^^^^^^^^^^^^^^^^^^ - -You can compare revisions with ``compare X Y`` command, where X and Y are -revision numbers. The output will describe how the configuration X is when -compared to Y, indicating with a plus sign (``+``) the additional parts X has -when compared to y, and indicating with a minus sign (``-``) the lacking parts -x misses when compared to y. - -.. code-block:: none - - vyos@vyos-test-2# compare 0 6 - [edit interfaces] - +dummy dum1 { - + address 10.189.0.1/31 - +} - [edit interfaces ethernet eth0] - +vif 99 { - + address 10.199.0.1/31 - +} - -vif 900 { - - address 192.0.2.4/24 - -} - -Rolling Back Changes -^^^^^^^^^^^^^^^^^^^^ +When inside configuration mode you are not directly able to execute operational +commands. -You can rollback configuration using the rollback command. This command will +.. cfgcmd:: run + + Access to these commands are possible through the use of the ``run [command]`` + command. From this command you will have access to everything accessible from + operational mode. + + Command completion and syntax help with ``?`` and ``[tab]`` will also work. + + .. code-block:: none + + [edit] + vyos@vyos# run show interfaces + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 0.0.0.0/0 u/u + +Config Archive +============== + +VyOS automatically maintains backups of every previous configurations which +has been comitted to the system. + +Local Archive +------------- + +Revisions are stored on disk. You can view, compare and rollback them to any +previous revisions if something goes wrong. + +.. opcmd:: show system commit + + View all existing revisions on the local system. + + .. code-block:: none + + vyos@vyos:~$ show system commit + 0 2015-03-30 08:53:03 by vyos via cli + 1 2015-03-30 08:52:20 by vyos via cli + 2 2015-03-26 21:26:01 by root via boot-config-loader + 3 2015-03-26 20:43:18 by root via boot-config-loader + 4 2015-03-25 11:06:14 by root via boot-config-loader + 5 2015-03-25 01:04:28 by root via boot-config-loader + 6 2015-03-25 00:16:47 by vyos via cli + 7 2015-03-24 23:43:45 by root via boot-config-loader + +.. cfgcmd:: compare + + Compare difference in configuration revisions. + + .. code-block:: none + + vyos@vyos# compare [tab] + Possible completions: + Compare working & active configurations + saved Compare working & saved configurations + Compare working with revision N + Compare revision N with M + Revisions: + 0 2013-12-17 20:01:37 root by boot-config-loader + 1 2013-12-13 15:59:31 root by boot-config-loader + 2 2013-12-12 21:56:22 vyos by cli + 3 2013-12-12 21:55:11 vyos by cli + 4 2013-12-12 21:27:54 vyos by cli + 5 2013-12-12 21:23:29 vyos by cli + 6 2013-12-12 21:13:59 root by boot-config-loader + 7 2013-12-12 16:25:19 vyos by cli + 8 2013-12-12 15:44:36 vyos by cli + 9 2013-12-12 15:42:07 root by boot-config-loader + 10 2013-12-12 15:42:06 root by init + + Revisions can be compared with :cfgcmd:`compare N M` command, where N and M + are revision numbers. The output will describe how the configuration N is + when compared to YM indicating with a plus sign (``+``) the additional parts + N has when compared to M, and indicating with a minus sign (``-``) the + lacking parts N misses when compared to Y. + + .. code-block:: none + + vyos@vyos# compare 0 6 + [edit interfaces] + +dummy dum1 { + + address 10.189.0.1/31 + +} + [edit interfaces ethernet eth0] + +vif 99 { + + address 10.199.0.1/31 + +} + -vif 900 { + - address 192.0.2.4/24 + -} + +.. cfgcmd:: set system config-management commit-revisions + + You can specify the number of revisions stored on disk. N can be in the + range of 0 - 65535. When the number of revisions exceeds the configured + value, the oldest revision is removed. + +Rollback Changes +---------------- + +You can rollback configuration changes using the rollback command. This will apply the selected revision and trigger a system reboot. -.. code-block:: none +.. cfgcmd:: rollback - vyos@vyos# compare 1 - [edit system] - >host-name vyos-1 - [edit] - vyos@vyos# rollback 1 - Proceed with reboot? [confirm][y] - Broadcast message from root@vyos-1 (pts/0) (Tue Dec 17 21:07:45 2013): - The system is going down for reboot NOW! + Rollback to revision N (currently requires reboot) -Configuring the archive size -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. code-block:: none -You can specify the number of revisions stored on disk with ``set system -config-management commit-revisions X``, where X is a number between 0 and 65535. -When the number of revisions exceeds that number, the oldest revision is -removed. + vyos@vyos# compare 1 + [edit system] + >host-name vyos-1 + [edit] -Remote archive -^^^^^^^^^^^^^^ + vyos@vyos# rollback 1 + Proceed with reboot? [confirm][y] + Broadcast message from root@vyos-1 (pts/0) (Tue Dec 17 21:07:45 2013): + The system is going down for reboot NOW! -VyOS can copy the config to a remote location after each commit. TFTP, FTP, -and SFTP servers are supported. +Remote Archive +-------------- -You can specify the location with: +VyOS can upload the configuration to a remote location after each call to +:cfgcmd:`commit`. TFTP, FTP, and SFTP servers are supported. -* ``set system config-management commit-archive location URL`` +.. cfgcmd set system config-management commit-archive location -For example, ``set system config-management commit-archive location tftp://10.0.0.1/vyos``. + Specify remote location of commit archive. -You can specify the location with ``set system config-management commit-archive -location URL`` command, e.g. ``set system config-management commit-archive -location tftp://10.0.0.1/vyos``. + * scp://:@/ + * sftp://:@/ + * ftp://:@/ + * tftp:/// Restore Default =============== @@ -447,10 +464,11 @@ default one, you can enter the following command in configuration mode: load /opt/vyatta/etc/config.boot.default -You will be asked if you want to continue. If you accept, -you will have to use `commit` if you want to make the changes active. +You will be asked if you want to continue. If you accept, you will have to use + :cfgcmd:`commit` if you want to make the changes active. -Then you may want to ``save`` in order to delete the saved configuration too. +Then you may want to :cfgcmd:`save` in order to delete the saved configuration +too. .. note:: If you are remotely connected, you will lose your connection. You may want to copy first the config, edit it to ensure connectivity, and load the -- cgit v1.2.3 From addb616f6cf862f243e058b9d05da6f7d9422a7a Mon Sep 17 00:00:00 2001 From: Robert Göhler Date: Sun, 29 Dec 2019 10:43:13 +0100 Subject: sphinx: integrate standalone vytask command in conf.py References to VyOS Phabricator can now be build by using the statemenmt: :vytask:`T1234` --- docs/conf.py | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 76293898..539f828d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,6 +16,8 @@ # import sys # sys.path.insert(0, os.path.abspath('.')) +from docutils import nodes, utils +from docutils.parsers.rst.roles import set_classes # -- Project information ----------------------------------------------------- @@ -169,6 +171,22 @@ texinfo_documents = [ 'Miscellaneous'), ] + +def vytask_role(name, rawtext, text, lineno, inliner, options={}, content=[]): + app = inliner.document.settings.env.app + base = app.config.vyos_phabricator_url + ref = base + str(text) + set_classes(options) + node = nodes.reference( + rawtext, utils.unescape(str(text)), refuri=ref, **options) + return [node], [] + + def setup(app): + app.add_config_value( + 'vyos_phabricator_url', + 'https://phabricator.vyos.net/', '' + ) + app.add_role('vytask', vytask_role) app.add_object_type('opcmd', 'opcmd') app.add_object_type('cfgcmd', 'cfgcmd') -- cgit v1.2.3 From 207aceac28624c445c21ec81c6a9f8a3924abefc Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 29 Dec 2019 10:37:31 +0100 Subject: release-notes: Migrate all tasks to new vytask command --- docs/appendix/releasenotes.rst | 316 +++++++++++++++++++++++------------------ 1 file changed, 181 insertions(+), 135 deletions(-) (limited to 'docs') diff --git a/docs/appendix/releasenotes.rst b/docs/appendix/releasenotes.rst index d2601c2c..6f85c103 100644 --- a/docs/appendix/releasenotes.rst +++ b/docs/appendix/releasenotes.rst @@ -1,6 +1,7 @@ -.. _releasenotes: +.. _release-notes: -Release notes +############# +Release Notes ############# 1.2 (Crux) @@ -14,61 +15,71 @@ Release notes Resolved issues ^^^^^^^^^^^^^^^ -* `T258 `_ Can not configure wan load-balancing on vyos-1.2 -* `T818 `_ SNMP v3 - remove required engineid from user node -* `T1030 `_ Upgrade ddclient from 3.8.2 to 3.9.0 (support Cloudflare API v4) -* `T1183 `_ BFD Support via FRR -* `T1299 `_ Allow SNMPd to be extended with custom scripts -* `T1351 `_ accel-pppoe adding CIDR based IP pool option -* `T1391 `_ In route-map set community additive -* `T1394 `_ syslog systemd and host_name.py race condition -* `T1401 `_ Copying files with the FTP protocol fails if the password contains special characters -* `T1421 `_ OpenVPN client push-route stopped working, needs added quotes to fix -* `T1447 `_ Python subprocess called without import in host_name.py -* `T1470 `_ improve output of "show dhcpv6 server leases" -* `T1485 `_ Enable 'AdvIntervalOpt' option in for radvd.conf -* `T1496 `_ Separate rolling release and LTS kernel builds -* `T1560 `_ "set load-balancing wan rule 0" causes segfault and prevents load balancing from starting -* `T1568 `_ strip-private command improvement for additional masking of IPv6 and MAC address -* `T1578 `_ completion offers "show table", but show table does not exist -* `T1593 `_ Support ip6gre -* `T1597 `_ /usr/sbin/rsyslogd after deleting "system syslog" -* `T1638 `_ vyos-hostsd not setting system domain name -* `T1678 `_ hostfile-update missing line feed -* `T1694 `_ NTPd: Do not listen on all interfaces by default -* `T1701 `_ Delete domain-name and domain-search won't work -* `T1705 `_ High CPU usage by bgpd when snmp is active -* `T1707 `_ DHCP static mapping and exclude address not working -* `T1708 `_ Update Rolling Release Kernel to 4.19.76 -* `T1709 `_ Update WireGuard to 0.0.20190913 -* `T1716 `_ Update Intel NIC drivers to recent versions -* `T1726 `_ Update Linux Firmware binaries to a more recent version 2019-03-14 -> 2019-10-07 -* `T1728 `_ Update Linux Kernel to 4.19.79 -* `T1737 `_ SNMP tab completion missing -* `T1738 `_ Copy SNMP configuration from node to node raises exception -* `T1740 `_ Broken OSPFv2 virtual-link authentication -* `T1742 `_ NHRP unable to commit. -* `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 -* `T1749 `_ numeric validator doesn't support multiple ranges -* `T1769 `_ Remove complex SNMPv3 Transport Security Model (TSM) -* `T1772 `_ constraints in XML are partially broken -* `T1778 `_ Kilobits/Megabits difference in configuration Vyos/FRR -* `T1780 `_ Adding ipsec ike closeaction -* `T1786 `_ disable-dhcp-nameservers is missed in current host_name.py implementation -* `T1788 `_ Intel QAT (QuickAssist Technology ) implementation -* `T1792 `_ Update WireGuard to Debian release 0.0.20191012-1 -* `T1800 `_ Update Linux Kernel to v4.19.84 -* `T1809 `_ Wireless: SSID scan does not work in AP mode -* `T1811 `_ Upgrade from 1.1.8: Config file migration failed: module=l2tp -* `T1812 `_ DHCP: hostnames of clients not resolving after update v1.2.3 -> 1.2-rolling -* `T1819 `_ Reboot kills SNMPv3 configuration -* `T1822 `_ Priority inversion wireless interface dhcpv6 -* `T1836 `_ import-conf-mode-commands in vyos-1x/scripts fails to create an xml -* `T1839 `_ LLDP shows "VyOS unknown" instead of "VyOS" -* `T1841 `_ PPP ipv6-up.d direcotry missing -* `T1893 `_ igmp-proxy: Do not allow adding unknown interface -* `T1904 `_ update eth1 and eth2 link files for the vep4600 - +* :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:`T1447` Python subprocess called without import in host_name.py +* :vytask:`T1470` improve output of "show dhcpv6 server leases" +* :vytask:`T1485` Enable 'AdvIntervalOpt' option in for radvd.conf +* :vytask:`T1496` Separate rolling release and LTS kernel builds +* :vytask:`T1560` "set load-balancing wan rule 0" causes segfault and prevents + load balancing from starting +* :vytask:`T1568` strip-private command improvement for additional masking of + IPv6 and MAC address +* :vytask:`T1578` completion offers "show table", but show table does not exist +* :vytask:`T1593` Support ip6gre +* :vytask:`T1597` /usr/sbin/rsyslogd after deleting "system syslog" +* :vytask:`T1638` vyos-hostsd not setting system domain name +* :vytask:`T1678` hostfile-update missing line feed +* :vytask:`T1694` NTPd: Do not listen on all interfaces by default +* :vytask:`T1701` Delete domain-name and domain-search won't work +* :vytask:`T1705` High CPU usage by bgpd when snmp is active +* :vytask:`T1707` DHCP static mapping and exclude address not working +* :vytask:`T1708` Update Rolling Release Kernel to 4.19.76 +* :vytask:`T1709` Update WireGuard to 0.0.20190913 +* :vytask:`T1716` Update Intel NIC drivers to recent versions +* :vytask:`T1726` Update Linux Firmware binaries to a more recent version + 2019-03-14 -> 2019-10-07 +* :vytask:`T1728` Update Linux Kernel to 4.19.79 +* :vytask:`T1737` SNMP tab completion missing +* :vytask:`T1738` Copy SNMP configuration from node to node raises exception +* :vytask:`T1740` Broken OSPFv2 virtual-link authentication +* :vytask:`T1742` NHRP unable to commit. +* :vytask:`T1745` dhcp-server commit fails with "DHCP range stop address x must + be greater or equal to the range start address y!" when static mapping has + same IP as range stop +* :vytask:`T1749` numeric validator doesn't support multiple ranges +* :vytask:`T1769` Remove complex SNMPv3 Transport Security Model (TSM) +* :vytask:`T1772` constraints in XML are partially broken +* :vytask:`T1778` Kilobits/Megabits difference in configuration Vyos/FRR +* :vytask:`T1780` Adding ipsec ike closeaction +* :vytask:`T1786` disable-dhcp-nameservers is missed in current host_name.py + implementation +* :vytask:`T1788` Intel QAT (QuickAssist Technology ) implementation +* :vytask:`T1792` Update WireGuard to Debian release 0.0.20191012-1 +* :vytask:`T1800` Update Linux Kernel to v4.19.84 +* :vytask:`T1809` Wireless: SSID scan does not work in AP mode +* :vytask:`T1811` Upgrade from 1.1.8: Config file migration failed: module=l2tp +* :vytask:`T1812` DHCP: hostnames of clients not resolving after update + v1.2.3 -> 1.2-rolling +* :vytask:`T1819` Reboot kills SNMPv3 configuration +* :vytask:`T1822` Priority inversion wireless interface dhcpv6 +* :vytask:`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:`T1904` update eth1 and eth2 link files for the vep4600 1.2.3 ----- @@ -79,47 +90,59 @@ New features ^^^^^^^^^^^^ * HTTP API -* "set service dns forwarding allow-from " 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) +* :vytask:`T1524` "set service dns forwarding allow-from " + option for limiting queries to specific client networks +* :vytask:`T1503` Functions for checking if a commit is in progress +* :vytask:`T1543` "set system contig-mangement commit-archive source-address" + option +* :vytask:`T1554` Intel NIC drivers now support receive side scaling and + multiqueue Resolved issues ^^^^^^^^^^^^^^^ -* 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 " 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) +* :vytask:`T1209` OSPF max-metric values over 100 no longer causes commit + errors +* :vytask:`T1333` Fixes issue with DNS forwarding not performing recursive + lookups on domain specific forwarders +* :vytask:`T1362` Special characters in VRRP passwords are handled correctly +* :vytask:`T1377` BGP weight is applied properly +* :vytask:`T1420` Fixed permission for log files +* :vytask:`T1425` Wireguard interfaces now support /31 addresses +* :vytask:`T1428` Wireguard correctly handles firewall marks +* :vytask:`T1439` DHCPv6 static mappings now work correctly +* :vytask:`T1450` Flood ping commands now works correctly +* :vytask:`T1460` Op mode "show firewall" commands now support counters longer + than 8 digits (T1460) +* :vytask:`T1465` Fixed priority inversion in VTI commands +* :vytask:`T1468` Fixed remote-as check in the BGP route-reflector-client option +* :vytask:`T1472` It's now possible to re-create VRRP groups with RFC + compatibility mode enabled +* :vytask:`T1527` Fixed a typo in DHCPv6 server help strings +* :vytask:`T1529` Unnumbered BGP peers now support VLAN interfaces +* :vytask:`T1530` Fixed "set system syslog global archive file" command +* :vytask:`T1531` Multiple fixes in cluster configuration scripts +* :vytask:`T1537` Fixed missing help text for "service dns" +* :vytask:`T1541` Fixed input validation in DHCPv6 relay options +* :vytask:`T1551` It's now possible to create a QinQ interface and a firewall + assigned to it in one commit +* :vytask:`T1559` URL filtering now uses correct rule database path and works + again +* :vytask:`T1579` "show log vpn ipsec" command works again +* :vytask:`T1576` "show arp interface " command works again +* :vytask:`T1605` Fixed regression in L2TP/IPsec server +* :vytask:`T1613` Netflow/sFlow captures IPv6 traffic correctly +* :vytask:`T1616` "renew dhcpv6" command now works from op mode +* :vytask:`T1642` BGP remove-private-as option iBGP vs eBGP check works + correctly now +* :vytask:`T1540`, :vytask:`T1360`, :vytask:`T1264`, :vytask:`T1623` Multiple + improvements in name servers and hosts configuration handling Internals ^^^^^^^^^ -/etc/resolv.conf and /etc/hosts files are now managed by the vyos-hostsd service that listens on a ZMQ socket for update messages. +``/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 ----- @@ -132,7 +155,8 @@ 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) +* 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 @@ -144,21 +168,28 @@ 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) +* :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 ----- @@ -168,35 +199,50 @@ 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 `_). -* 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 `_). -* DHCP WPAD URL option works correctly again (`T1330 `_) -* Many to many NAT rules now can use source/destination and translation networks of non-matching size (`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 `_). -* Non-alphanumeric characters such as “>” can now be safely used in PPPoE passwords (`T1308 `_). -* “show | commands” no longer fails when a config section ends with a leaf node such as “timezone” in “show system | commands” (`T1305 `_). -* “show | commands” correctly works in config mode now (`T1235 `_). -* VTI is now compatible with the DHCP-interface IPsec option (`T1298 `_). -* “show dhcp server statistics” command was broken in latest Crux (`T1277 `_). -* An issue with TFTP server refusing to listen on addresses other than loopback was fixed (`T1261 `_). -* Template issue that might cause UDP broadcast relay fail to start is fixed (`T1224 `_). -* VXLAN value validation is improved (`T1067 `_). -* Blank hostnames in DHCP updates no longer can crash DNS forwarding (`T1211 `_). -* Correct configuration is now generated for DHCPv6 relays with more than one upstream interface (`T1322 `_). -* “relay-agents-packets” option works correctly now (`T1234 `_). -* Dynamic DNS data is now cleaned on configuration change (`T1231 `_). -* Remote Syslog can now use a fully qualified domain name (`T1282 `_). -* ACPI power off works again (`T1279 `_). -* Negation in WAN load balancing rules works again (`T1247 `_). -* FRR’s staticd now starts on boot correctly (`T1218 `_). -* The installer now correctly detects SD card devices (`T1296 `_). -* Wireguard peers can be disabled now (`T1225 `_). -* The issue with wireguard interfaces impossible to delete is fixed (`T1217 `_). -* Unintended IPv6 access is fixed in SNMP configuration (`T1160 `_). -* It’s now possible to exclude hosts from the transparent web proxy (`T1060 `_). -* An issue with rules impossible to delete from the zone-based firewall is fixed (`T484 `_). +* 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 ================ -- cgit v1.2.3 From 3918aefbeeeac4ab9844e3528995ae689a9bd952 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 29 Dec 2019 10:41:33 +0100 Subject: vytask: migrate all task references to new command --- docs/appendix/vyos-on-baremetal.rst | 6 ++---- docs/contributing/development.rst | 3 +-- docs/routing/ospf.rst | 4 +--- 3 files changed, 4 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/appendix/vyos-on-baremetal.rst b/docs/appendix/vyos-on-baremetal.rst index 76b5e210..5f20a03f 100644 --- a/docs/appendix/vyos-on-baremetal.rst +++ b/docs/appendix/vyos-on-baremetal.rst @@ -107,7 +107,7 @@ VyOS 1.2 (crux) --------------- Depending on the VyOS versions you intend to install there is a difference in -the serial port settings (T1327_). +the serial port settings (:vytask:`T1327`). Create a bootable USB pendrive using e.g. Rufus_ on a Windows machine. @@ -190,7 +190,7 @@ VyOS 1.2 (rolling) ------------------ Installing the rolling release on an APU2 board does not require any change -on the serial console from your host side as T1327_ was successfully +on the serial console from your host side as :vytask:`T1327` was successfully implemented. Simply proceed with a regular image installation as described in @@ -246,8 +246,6 @@ Desktop :alt: APU4C4 desktop back .. _Rufus: https://rufus.ie/ -.. _T1327: https://phabricator.vyos.net/T1327 - Qotom Q355G4 ************ diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst index 1c257772..35b9e17a 100644 --- a/docs/contributing/development.rst +++ b/docs/contributing/development.rst @@ -486,7 +486,7 @@ GNU Preprocessor ---------------- XML interface definition files use the `xml.in` file extension which was -implemented in T1843_. XML interface definitions tend to have a lot of +implemented in :vytask:`T1843`. XML interface definitions tend to have a lot of duplicated code in areas such as: * VIF (incl. VIF-S/VIF-C) @@ -698,7 +698,6 @@ http://dev.packages.vyos.net/repositories/. .. _Phabricator: https://phabricator.vyos.net/ .. _Jenkins: https://jenkins.io/ .. _Dockerhub: https://hub.docker.com/u/vyos/ -.. _T1843: https://phabricator.vyos.net/T1843 .. _`IPv4, IPv6 and DHCP(v6)`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/address-ipv4-ipv6-dhcp.xml.i .. _`IPv4, IPv6`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/address-ipv4-ipv6.xml.i .. _`VLAN (VIF)`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/vif.xml.i diff --git a/docs/routing/ospf.rst b/docs/routing/ospf.rst index bee70895..acffb7b3 100644 --- a/docs/routing/ospf.rst +++ b/docs/routing/ospf.rst @@ -90,7 +90,7 @@ A typical configuration using 2 nodes. .. note:: You can not easily redistribute IPv6 routes via OSPFv3 on a WireGuard interface link. This requires you to configure link-local addresses manually - on the WireGuard interfaces, see Phabricator task T1483_. + on the WireGuard interfaces, see :vytask:`T1483`. Example configuration for WireGuard interfaces: @@ -136,5 +136,3 @@ Example configuration for WireGuard interfaces: Neighbor ID Pri DeadTime State/IfState Duration I/F[State] 192.168.0.1 1 00:00:39 Full/PointToPoint 00:19:44 wg01[PointToPoint] -.. _T1483: https://phabricator.vyos.net/T1483 - -- cgit v1.2.3 From 37a891f7cf0499c958eb6bbff5699455a4ada01a Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 29 Dec 2019 11:00:16 +0100 Subject: provide common-references file Spinx references used accross different files should be stored here as a single source reference. Include this file as needed by: .. include:: common-references.rst --- docs/common-references.rst | 2 ++ docs/services/index.rst | 2 -- docs/services/ipoe-server.rst | 9 +++------ docs/services/pppoe-server.rst | 6 +++--- docs/services/references.rst | 11 ----------- docs/services/snmp.rst | 6 +++++- docs/services/sstp-server.rst | 6 +++--- docs/services/webproxy.rst | 5 +++-- 8 files changed, 19 insertions(+), 28 deletions(-) create mode 100644 docs/common-references.rst delete mode 100644 docs/services/references.rst (limited to 'docs') diff --git a/docs/common-references.rst b/docs/common-references.rst new file mode 100644 index 00000000..9f0b9b84 --- /dev/null +++ b/docs/common-references.rst @@ -0,0 +1,2 @@ +.. _`accel-ppp`: https://accel-ppp.org/ +.. _`Secure Socket Tunneling Protocol`: https://en.wikipedia.org/wiki/Secure_Socket_Tunneling_Protocol diff --git a/docs/services/index.rst b/docs/services/index.rst index af3e6cb1..e0773090 100644 --- a/docs/services/index.rst +++ b/docs/services/index.rst @@ -1,7 +1,5 @@ .. _services: -.. include:: references.rst - ######## Services ######## diff --git a/docs/services/ipoe-server.rst b/docs/services/ipoe-server.rst index 8e3a88eb..a1144301 100644 --- a/docs/services/ipoe-server.rst +++ b/docs/services/ipoe-server.rst @@ -4,9 +4,9 @@ IPoE server VyOS utilizes `accel-ppp`_ to provide IPoE server functionality. It can be used with local authentication (mac-address) or a connected RADIUS server. -.. note:: **Please be aware, due to an upstream bug, config changes/commits +.. note:: Please be aware, due to an upstream bug, config changes/commits will restart the ppp daemon and will reset existing IPoE sessions, - in order to become effective.** + in order to become effective. Configuration ^^^^^^^^^^^^^ @@ -123,7 +123,4 @@ The rate-limit is set in kbit/sec. -------+------------+-------------------+-------------+-----+--------+------------+--------+----------+------------------ ipoe0 | eth2 | 08:00:27:2f:d8:06 | 192.168.0.2 | | | 500/500 | active | 00:00:05 | dccc870fd31349fb - - - -.. _`accel-ppp`: https://accel-ppp.org/ +.. include:: ../common-references.rst diff --git a/docs/services/pppoe-server.rst b/docs/services/pppoe-server.rst index 481831ba..a229d3f9 100644 --- a/docs/services/pppoe-server.rst +++ b/docs/services/pppoe-server.rst @@ -7,9 +7,9 @@ PPPoE Server VyOS utilizes `accel-ppp`_ to provide PPPoE server functionality. It can be used with local authentication or a connected RADIUS server. -.. note:: **Please be aware, due to an upstream bug, config changes/commits +.. note:: Please be aware, due to an upstream bug, config changes/commits will restart the ppp daemon and will reset existing PPPoE connections from - connected users, in order to become effective.** + connected users, in order to become effective. Configuration ============= @@ -241,4 +241,4 @@ subnet for the clients internal use. --------+----------+-------------+--------------------------+---------------------+-------------------+------------+--------+----------+----------+---------- ppp0 | test | 192.168.0.1 | 2001:db8:8002:0:200::/64 | 2001:db8:8003::1/56 | 00:53:00:12:42:eb | | active | 00:00:49 | 875 B | 2.1 KiB -.. _`accel-ppp`: https://accel-ppp.org/ +.. include:: ../common-references.rst diff --git a/docs/services/references.rst b/docs/services/references.rst deleted file mode 100644 index 704f33f7..00000000 --- a/docs/services/references.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _MIB: https://en.wikipedia.org/wiki/Management_information_base -.. _SNMP: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol -.. _SNMPv2: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2 -.. _SNMPv3: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_3 -.. _SSH: https://en.wikipedia.org/wiki/Secure_Shell -.. _Squid3: http://www.squid-cache.org/ -.. _Squidguard: http://www.squidguard.org/ -.. _TFTP: https://en.wikipedia.org/wiki/Trivial_File_Transfer_Protocol -.. _`arbitrary extension commands`: http://net-snmp.sourceforge.net/docs/man/snmpd.conf.html#lbAZ -.. _`accel-ppp`: https://accel-ppp.org/ -.. _`Secure Socket Tunneling Protocol`: https://en.wikipedia.org/wiki/Secure_Socket_Tunneling_Protocol diff --git a/docs/services/snmp.rst b/docs/services/snmp.rst index c4b8fa32..c27cf02a 100644 --- a/docs/services/snmp.rst +++ b/docs/services/snmp.rst @@ -254,4 +254,8 @@ following content: -.. include:: references.rst +.. _MIB: https://en.wikipedia.org/wiki/Management_information_base +.. _SNMP: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol +.. _SNMPv2: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2 +.. _SNMPv3: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_3 + diff --git a/docs/services/sstp-server.rst b/docs/services/sstp-server.rst index 64a5206b..8e67b95c 100644 --- a/docs/services/sstp-server.rst +++ b/docs/services/sstp-server.rst @@ -6,9 +6,9 @@ SSTP server VyOS utilizes accel-ppp_ to provide SSTP server functionality. It can be used with local authentication or a connected RADIUS server. -.. note:: **Please be aware, due to an upstream bug, config changes/commits +.. note:: Please be aware, due to an upstream bug, config changes/commits will restart the ppp daemon and will reset existing PPPoE connections from - connected users, in order to become effective.** + connected users, in order to become effective. Configuration ^^^^^^^^^^^^^ @@ -73,4 +73,4 @@ looks for all files and directories in ``/config/user-data/sstp``. set sstp-settings ssl-certs server-cert 'server.crt' set sstp-settings ssl-certs server-key 'server.key' -.. include:: references.rst +.. include:: ../common-references.rst diff --git a/docs/services/webproxy.rst b/docs/services/webproxy.rst index b4b20ef5..20e1eb73 100644 --- a/docs/services/webproxy.rst +++ b/docs/services/webproxy.rst @@ -3,7 +3,7 @@ Webproxy The proxy service in VyOS is based on Squid3 and some related modules. -Squid is a caching and forwarding HTTP web proxy. It has a wide variety of +Squid3_ is a caching and forwarding HTTP web proxy. It has a wide variety of uses, including speeding up a web server by caching repeated requests, caching web, DNS and other computer network lookups for a group of people sharing network resources, and aiding security by filtering traffic. Although @@ -149,4 +149,5 @@ So sometimes it is useful to bypass a transparent proxy: (This can be useful when a called service has many and/or often changing destination addresses - e.g. Netflix.) -.. include:: references.rst +.. _Squid3: http://www.squid-cache.org/ +.. _Squidguard: http://www.squidguard.org/ -- cgit v1.2.3 From 1499918804a16051c44d2ee248c067f25e617185 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 29 Dec 2019 11:07:22 +0100 Subject: common-references: migrate all VyOS Phabricator references --- docs/common-references.rst | 1 + docs/contributing/development.rst | 3 ++- docs/contributing/documentation.rst | 3 ++- docs/contributing/issues-features.rst | 10 ++++++---- docs/vpn/openvpn.rst | 6 ++++-- 5 files changed, 15 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/common-references.rst b/docs/common-references.rst index 9f0b9b84..d7e376eb 100644 --- a/docs/common-references.rst +++ b/docs/common-references.rst @@ -1,2 +1,3 @@ .. _`accel-ppp`: https://accel-ppp.org/ .. _`Secure Socket Tunneling Protocol`: https://en.wikipedia.org/wiki/Secure_Socket_Tunneling_Protocol +.. _Phabricator: https://phabricator.vyos.net/ diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst index 35b9e17a..fed06e6f 100644 --- a/docs/contributing/development.rst +++ b/docs/contributing/development.rst @@ -695,10 +695,11 @@ http://dev.packages.vyos.net/repositories/. .. _VyConf: https://github.com/vyos/vyconf/tree/master/data/schemata .. _vyos-1x: https://github.com/vyos/vyos-1x/tree/current/schema .. _Jinja2: https://jinja.palletsprojects.com/ -.. _Phabricator: https://phabricator.vyos.net/ .. _Jenkins: https://jenkins.io/ .. _Dockerhub: https://hub.docker.com/u/vyos/ .. _`IPv4, IPv6 and DHCP(v6)`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/address-ipv4-ipv6-dhcp.xml.i .. _`IPv4, IPv6`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/address-ipv4-ipv6.xml.i .. _`VLAN (VIF)`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/vif.xml.i .. _`MAC address`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/interface-mac.xml.i + +.. include:: ../common-references.rst diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst index 48cc063b..c639651b 100644 --- a/docs/contributing/documentation.rst +++ b/docs/contributing/documentation.rst @@ -171,5 +171,6 @@ be added below this statement. .. _Sphinx-doc: https://www.sphinx-doc.org .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html -.. _Phabricator: https://phabricator.vyos.net .. _README.md: https://github.com/vyos/vyos-documentation/blob/master/README.md + +.. include:: ../common-references.rst diff --git a/docs/contributing/issues-features.rst b/docs/contributing/issues-features.rst index 04efbd22..e208a3e6 100644 --- a/docs/contributing/issues-features.rst +++ b/docs/contributing/issues-features.rst @@ -51,9 +51,10 @@ also contain information that is helpful for the development team. Report a Bug ************ -Create an account on VyOS Phabricator_. Phabricator_ is located at -https://phabricator.vyos.net. To create a bug-report use the quick link in the -left side under the specific project. +In order to open up a bug-report/feature request you need to create yourself +an account on VyOS Phabricator_. On the left side of the specific project (VyOS +1.2 or VyOS 1.3) you will find quick-links for opening a bug-report/feature +request. * Provide as much information as you can * Which version of VyOS are you using? ``run show version`` @@ -71,4 +72,5 @@ the left side under the specific project. .. _documentation: https://docs.vyos.io .. _Slack: https://slack.vyos.io .. _Forum: https://forum.vyos.io -.. _Phabricator: https://phabricator.vyos.net \ No newline at end of file + +.. include:: ../common-references.rst \ No newline at end of file diff --git a/docs/vpn/openvpn.rst b/docs/vpn/openvpn.rst index 69961f0c..cbb89fbe 100644 --- a/docs/vpn/openvpn.rst +++ b/docs/vpn/openvpn.rst @@ -441,8 +441,8 @@ Options ======= We do not have CLI nodes for every single OpenVPN options. If an option is -missing, a feature request should be opened at https://phabricator.vyos.net so -all users can benefit from it. +missing, a feature request should be opened at Phabricator_ so all users can +benefit from it (see :ref:`issues_features`). If you are a hacker or want to try on your own we support passing raw OpenVPN options to OpenVPN. @@ -460,3 +460,5 @@ Will add ``push "keepalive 1 10"`` to the generated OpenVPN config file. .. note:: Sometimes option lines in the generated OpenVPN configurarion require quotes. This is done through a hack on our config generator. You can pass quotes using the ``"`` statement. + +.. include:: ../common-references.rst -- cgit v1.2.3 From ed82d6b00e6ed32b3d056f0623822d61c6c599f6 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 29 Dec 2019 11:10:38 +0100 Subject: issue-feature: use documented section style guide --- docs/contributing/issues-features.rst | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/contributing/issues-features.rst b/docs/contributing/issues-features.rst index e208a3e6..553522a1 100644 --- a/docs/contributing/issues-features.rst +++ b/docs/contributing/issues-features.rst @@ -1,12 +1,14 @@ .. _issues_features: +####################### Issues/Feature requests ======================= .. _bug_report: Bug Report/Issue ----------------- +================ + Issues or bugs are found in any software project. VyOS is not an exception. All issues should be reported to the developers. This lets the developers know @@ -14,7 +16,7 @@ what is not working properly. Without this sort of feedback every developer will believe that everything is working correctly. I have found a bug, what should I do? -************************************* +------------------------------------- When you believe you have found a bug, it is always a good idea to verify the issue prior to opening a bug request. @@ -24,7 +26,7 @@ issue prior to opening a bug request. * Get community support via Slack_ or our Forum_ Ensure the problem is reproducible -********************************** +---------------------------------- When you are able to verify that it is actually a bug, spend some time to document how to reproduce the issue. This documentation can be invaluable. @@ -40,7 +42,7 @@ information can be very useful. * What commands did you use? Use e.g. ``run show configuration commands`` Include output -************** +-------------- The output you get when you find a bug can provide lots of information. If you get an error message on the screen, copy it exactly. Having the exact message @@ -49,7 +51,7 @@ messages that also are from the time of the issue, include those. They may also contain information that is helpful for the development team. Report a Bug -************ +------------ In order to open up a bug-report/feature request you need to create yourself an account on VyOS Phabricator_. On the left side of the specific project (VyOS @@ -60,8 +62,10 @@ request. * Which version of VyOS are you using? ``run show version`` * How can we reproduce this Bug? +.. _feature_request: + Feature Request ---------------- +=============== You have an idea of how to make VyOS better or you are in need of a specific feature which all users of VyOS would benefit from? To send a feature request -- cgit v1.2.3 From 63d79bfbc887f306bca842986b823a1ee38ace13 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 29 Dec 2019 17:13:44 +0100 Subject: issue-feature: fix title overline & underline mismatch --- docs/contributing/issues-features.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/contributing/issues-features.rst b/docs/contributing/issues-features.rst index 553522a1..1c6563b9 100644 --- a/docs/contributing/issues-features.rst +++ b/docs/contributing/issues-features.rst @@ -2,7 +2,7 @@ ####################### Issues/Feature requests -======================= +####################### .. _bug_report: -- cgit v1.2.3 From 37850e2f6f9efed96c9e807fd98623465337d330 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Mon, 30 Dec 2019 11:28:52 +0100 Subject: remove all enclosing '' from cfgcmd/opcmd --- docs/appendix/examples/dmvpn.rst | 4 ++-- docs/configuration-overview.rst | 2 +- docs/interfaces/dummy.rst | 8 ++++---- docs/interfaces/ethernet.rst | 30 +++++++++++++++--------------- docs/routing/bgp.rst | 10 +++++----- docs/routing/static.rst | 32 ++++++++++++++++---------------- docs/services/dhcp.rst | 26 +++++++++++++------------- docs/services/ssh.rst | 10 +++++----- docs/services/tftp.rst | 2 +- docs/services/udp-broadcast-relay.rst | 8 ++++---- docs/system/config-management.rst | 2 +- docs/system/default-route.rst | 4 ++-- docs/system/flow-accounting.rst | 30 +++++++++++++++--------------- docs/system/host-information.rst | 10 +++++----- docs/system/ntp.rst | 8 ++++---- docs/system/proxy.rst | 8 ++++---- docs/system/serial-console.rst | 6 +++--- docs/system/task-scheduler.rst | 8 ++++---- docs/system/time-zone.rst | 2 +- docs/system/user-management.rst | 26 +++++++++++++------------- 20 files changed, 118 insertions(+), 118 deletions(-) (limited to 'docs') diff --git a/docs/appendix/examples/dmvpn.rst b/docs/appendix/examples/dmvpn.rst index cbb9f300..49b1fcaa 100644 --- a/docs/appendix/examples/dmvpn.rst +++ b/docs/appendix/examples/dmvpn.rst @@ -17,7 +17,7 @@ Configuration set interfaces tunnel tun100 multicast 'enable' set interfaces tunnel tun100 parameters ip key '1' - set protocols nhrp tunnel tun100 cisco-authentication '' + set protocols nhrp tunnel tun100 cisco-authentication set protocols nhrp tunnel tun100 holding-time '300' set protocols nhrp tunnel tun100 multicast 'dynamic' set protocols nhrp tunnel tun100 redirect @@ -43,7 +43,7 @@ Configuration set vpn ipsec ipsec-interfaces interface 'eth0' set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' - set vpn ipsec profile NHRPVPN authentication pre-shared-secret '' + set vpn ipsec profile NHRPVPN authentication pre-shared-secret set vpn ipsec profile NHRPVPN bind tunnel 'tun100' set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' diff --git a/docs/configuration-overview.rst b/docs/configuration-overview.rst index 646f4dea..0ee4e0f5 100644 --- a/docs/configuration-overview.rst +++ b/docs/configuration-overview.rst @@ -109,7 +109,7 @@ added through a collection of :cfgcmd:`set` and :cfgcmd:`delete` commands. 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 '' + 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' diff --git a/docs/interfaces/dummy.rst b/docs/interfaces/dummy.rst index 1b35cefd..c74e5f48 100644 --- a/docs/interfaces/dummy.rst +++ b/docs/interfaces/dummy.rst @@ -16,7 +16,7 @@ Configuration Address ------- -.. cfgcmd:: set interfaces dummy '' address
+.. cfgcmd:: set interfaces dummy address
Configure dummy interface `` with one or more interface addresses. @@ -40,12 +40,12 @@ Address Link Administration ------------------- -.. cfgcmd:: set interfaces dummy '' description '' +.. cfgcmd:: set interfaces dummy description Assign given `` to interface. Description will also be passed to SNMP monitoring systems. -.. cfgcmd:: set interfaces dummy '' disable +.. cfgcmd:: set interfaces dummy disable Disable given ``. It will be placed in administratively down state. @@ -65,7 +65,7 @@ Operation --------- ---------- --- ----------- dum0 172.18.254.201/32 u/u -.. opcmd:: show interfaces dummy '' +.. opcmd:: show interfaces dummy Show detailed information on given `` diff --git a/docs/interfaces/ethernet.rst b/docs/interfaces/ethernet.rst index d0537b41..693634fb 100644 --- a/docs/interfaces/ethernet.rst +++ b/docs/interfaces/ethernet.rst @@ -10,7 +10,7 @@ Configuration Address ------- -.. cfgcmd:: set interfaces ethernet '' address
+.. cfgcmd:: set interfaces ethernet address
Configure ethernet interface `` with one or more interface addresses. @@ -31,7 +31,7 @@ Address set interfaces ethernet eth0 address 2001:db8::ffff/64 set interfaces ethernet eth0 address 2001:db8:100::ffff/64 -.. cfgcmd:: set interfaces ethernet '' ipv6 address autoconf +.. cfgcmd:: set interfaces ethernet ipv6 address autoconf :abbr:`SLAAC (Stateless Address Autoconfiguration)` :rfc:`4862`. IPv6 hosts can configure themselves automatically when connected @@ -45,7 +45,7 @@ Address .. note:: This method automatically disables IPv6 traffic forwarding on the interface in question. -.. cfgcmd:: set interfaces ethernet '' ipv6 address eui64 '' +.. cfgcmd:: set interfaces ethernet ipv6 address eui64 :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. @@ -57,7 +57,7 @@ Address Speed/Duplex ------------ -.. cfgcmd:: set interfaces ethernet '' duplex +.. cfgcmd:: set interfaces ethernet duplex Configure physical interface duplex setting. @@ -67,7 +67,7 @@ Speed/Duplex VyOS default will be `auto`. -.. cfgcmd:: set interfaces ethernet '' speed +.. cfgcmd:: set interfaces ethernet speed Configure physical interface speed setting. @@ -88,27 +88,27 @@ Speed/Duplex Link Administration ------------------- -.. cfgcmd:: set interfaces ethernet '' description '' +.. cfgcmd:: set interfaces ethernet description Assign given `` to interface. Description will also be passed to SNMP monitoring systems. -.. cfgcmd:: set interfaces ethernet '' disable +.. cfgcmd:: set interfaces ethernet disable Disable given ``. It will be placed in administratively down state. -.. cfgcmd:: set interfaces ethernet '' disable-flow-control +.. cfgcmd:: set interfaces ethernet disable-flow-control Disable Ethernet flow control (pause frames). -.. cfgcmd:: set interfaces ethernet '' mac '' +.. cfgcmd:: set interfaces ethernet mac Configure user defined :abbr:`MAC (Media Access Control)` address on given ``. -.. cfgcmd:: set interfaces ethernet '' mtu '' +.. cfgcmd:: set interfaces ethernet mtu Configure :abbr:`MTU (Maximum Transmission Unit)` on given ``. It is the size (in bytes) of the largest ethernet frame sent on this link. @@ -119,11 +119,11 @@ 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 '' ipv6 router-advert send-advert +.. cfgcmd:: set interfaces ethernet ipv6 router-advert send-advert Enable or disable router advertisements in this ``. -.. cfgcmd:: set interfaces ethernet '' ipv6 router-advert prefix '' +.. cfgcmd:: set interfaces ethernet ipv6 router-advert prefix Prefix information is described in :rfc:`4861#section-4.6.2`. @@ -144,7 +144,7 @@ Operation eth1 172.18.202.11/24 u/u WAN eth2 - u/D -.. opcmd:: show interfaces ethernet '' +.. opcmd:: show interfaces ethernet Show detailed information on given `` @@ -161,7 +161,7 @@ Operation TX: bytes packets errors dropped carrier collisions 5601460 62595 0 0 0 0 -.. opcmd:: show interfaces ethernet '' physical +.. opcmd:: show interfaces ethernet physical Show information about physical `` @@ -200,7 +200,7 @@ Operation supports-register-dump: yes supports-priv-flags: no -.. opcmd:: show interfaces ethernet '' transceiver +.. opcmd:: show interfaces ethernet transceiver Show transceiver information from plugin modules, e.g SFP+, QSFP diff --git a/docs/routing/bgp.rst b/docs/routing/bgp.rst index d8860e15..14ea1238 100644 --- a/docs/routing/bgp.rst +++ b/docs/routing/bgp.rst @@ -159,14 +159,14 @@ BGP Router Configuration ASN and Router ID ----------------- -.. cfgcmd:: set protocols bgp '' +.. cfgcmd:: set protocols bgp First of all you must configure BGP router with the :abbr:`ASN (Autonomous System Number)`. The AS number is an identifier for the autonomous system. The BGP protocol uses the AS number for detecting whether the BGP connection is internal or external. -.. cfgcmd:: set protocols bgp '' parameters router-id +.. cfgcmd:: set protocols bgp parameters router-id This command specifies the router-ID. If router ID is not specified it will use the highest interface IP address. @@ -174,19 +174,19 @@ ASN and Router ID Route Selection --------------- -.. cfgcmd:: set protocols bgp '' parameters bestpath as-path confed +.. cfgcmd:: set protocols bgp parameters bestpath as-path confed This command specifies that the length of confederation path sets and sequences should should be taken into account during the BGP best path decision process. -.. cfgcmd:: set protocols bgp '' parameters bestpath as-path multipath-relax +.. cfgcmd:: set protocols bgp parameters bestpath as-path multipath-relax This command specifies that BGP decision process should consider paths of equal AS_PATH length candidates for multipath computation. Without the knob, the entire AS_PATH must match for multipath computation. -.. cfgcmd:: set protocols bgp '' parameters bestpath as-path ignore +.. cfgcmd:: set protocols bgp parameters bestpath as-path ignore Ignore AS_PATH length when selecting a route diff --git a/docs/routing/static.rst b/docs/routing/static.rst index cebe42fa..52a73354 100644 --- a/docs/routing/static.rst +++ b/docs/routing/static.rst @@ -18,32 +18,32 @@ used to determine the forwarding table used for unicast packet forwarding. Static Routes ############# -.. cfgcmd:: set protocols static route '' next-hop '
' +.. cfgcmd:: set protocols static route next-hop
Configure next-hop `
` for an IPv4 static route. Multiple static routes can be created. -.. cfgcmd:: set protocols static route '' next-hop '
' disable +.. cfgcmd:: set protocols static route next-hop
disable Disable this IPv4 static route entry. -.. cfgcmd:: set protocols static route '' next-hop '
' distance '' +.. cfgcmd:: set protocols static route next-hop
distance Defines next-hop distance for this route, routes with smaller administrative distance are elected prior those with a higher distance. Range is 1 to 255, default is 1. -.. cfgcmd:: set protocols static route6 '' next-hop '
' +.. cfgcmd:: set protocols static route6 next-hop
Configure next-hop `
` for an IPv6 static route. Multiple static routes can be created. -.. cfgcmd:: set protocols static route6 '' next-hop '
' disable +.. cfgcmd:: set protocols static route6 next-hop
disable Disable this IPv6 static route entry. -.. cfgcmd:: set protocols static route6 '' next-hop '
' distance '' +.. cfgcmd:: set protocols static route6 next-hop
distance Defines next-hop distance for this route, routes with smaller administrative distance are elected prior those with a higher distance. @@ -57,34 +57,34 @@ Static Routes Interface Routes ================ -.. cfgcmd:: set protocols static interface-route '' next-hop-interface '' +.. cfgcmd:: set protocols static interface-route next-hop-interface Allows you to configure the next-hop interface for an interface-based IPv4 static route. `` will be the next-hop interface where trafic is routed for the given ``. -.. cfgcmd:: set protocols static interface-route '' next-hop-interface '' disable +.. cfgcmd:: set protocols static interface-route next-hop-interface disable Disables interface-based IPv4 static route. -.. cfgcmd:: set protocols static interface-route '' next-hop-interface '' distance '' +.. cfgcmd:: set protocols static interface-route next-hop-interface distance Defines next-hop distance for this route, routes with smaller administrative distance are elected prior those with a higher distance. Range is 1 to 255, default is 1. -.. cfgcmd:: set protocols static interface-route6 '' next-hop-interface '' +.. cfgcmd:: set protocols static interface-route6 next-hop-interface Allows you to configure the next-hop interface for an interface-based IPv6 static route. `` will be the next-hop interface where trafic is routed for the given ``. -.. cfgcmd:: set protocols static interface-route6 '' next-hop-interface '' disable +.. cfgcmd:: set protocols static interface-route6 next-hop-interface disable Disables interface-based IPv6 static route. -.. cfgcmd:: set protocols static interface-route6 '' next-hop-interface '' distance '' +.. cfgcmd:: set protocols static interface-route6 next-hop-interface distance Defines next-hop distance for this route, routes with smaller administrative distance are elected prior those with a higher distance. @@ -95,7 +95,7 @@ Interface Routes Blackhole ========= -.. cfgcmd:: set protocols static route '' blackhole +.. cfgcmd:: set protocols static route blackhole Use this command to configure a "black-hole" route on the router. A black-hole route is a route for which the system silently discard packets @@ -103,12 +103,12 @@ Blackhole it does not prevent them from being used as a more specific route inside your network. -.. cfgcmd:: set protocols static route '' blackhole distance '' +.. cfgcmd:: set protocols static route blackhole distance Defines blackhole distance for this route, routes with smaller administrative distance are elected prior those with a higher distance. -.. cfgcmd:: set protocols static route6 '' blackhole +.. cfgcmd:: set protocols static route6 blackhole Use this command to configure a "black-hole" route on the router. A black-hole route is a route for which the system silently discard packets @@ -116,7 +116,7 @@ Blackhole it does not prevent them from being used as a more specific route inside your network. -.. cfgcmd:: set protocols static route6 '' blackhole distance '' +.. cfgcmd:: set protocols static route6 blackhole distance Defines blackhole distance for this route, routes with smaller administrative distance are elected prior those with a higher distance. diff --git a/docs/services/dhcp.rst b/docs/services/dhcp.rst index 94efeaf1..bcadb673 100644 --- a/docs/services/dhcp.rst +++ b/docs/services/dhcp.rst @@ -146,23 +146,23 @@ inside the subnet definition but can be outside of the range statement. DHCP Options ------------ -.. cfgcmd:: set service dhcp-server shared-network-name '' subnet 192.0.2.0/24 default-router '
' +.. cfgcmd:: set service dhcp-server shared-network-name subnet 192.0.2.0/24 default-router
Specify the default routers IPv4 address which should be used in this subnet. This can - of course - be a VRRP address (DHCP option 003). -.. cfgcmd:: set service dhcp-server shared-network-name '' subnet 192.0.2.0/24 dns-server '
' +.. cfgcmd:: set service dhcp-server shared-network-name subnet 192.0.2.0/24 dns-server
Specify the DNS nameservers used (Option 006). This option may be used mulltiple times to specify additional DNS nameservers. -.. cfgcmd:: set service dhcp-server shared-network-name '' subnet 192.0.2.0/24 domain-name '' +.. cfgcmd:: set service dhcp-server shared-network-name subnet 192.0.2.0/24 domain-name The domain-name parameter should be the domain name that will be appended to the client's hostname to form a fully-qualified domain-name (FQDN) (DHCP Option 015). -.. cfgcmd:: set service dhcp-server shared-network-name '' subnet 192.0.2.0/24 domain-search '' +.. cfgcmd:: set service dhcp-server shared-network-name subnet 192.0.2.0/24 domain-search 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 @@ -401,41 +401,41 @@ Configuration Options Clients receiving advertise messages from multiple servers choose the server with the highest preference value. The range for this value is ``0...255``. -.. cfgcmd:: set service dhcpv6-server shared-network-name '' subnet '' lease-time {default | maximum | minimum} +.. cfgcmd:: set service dhcpv6-server shared-network-name subnet lease-time {default | maximum | minimum} The default lease time for DHCPv6 leases is 24 hours. This can be changed by supplying a ``default-time``, ``maximum-time`` and ``minimum-time``. All values need to be supplied in seconds. -.. cfgcmd:: set service dhcpv6-server shared-network-name '' subnet '' nis-domain '' +.. cfgcmd:: set service dhcpv6-server shared-network-name subnet nis-domain A :abbr:`NIS (Network Information Service)` domain can be set to be used for DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name '' subnet '' nisplus-domain '' +.. cfgcmd:: set service dhcpv6-server shared-network-name subnet nisplus-domain The procedure to specify a :abbr:`NIS+ (Network Information Service Plus)` domain is similar to the NIS domain one: -.. cfgcmd:: set service dhcpv6-server shared-network-name '' subnet '' nis-server '
' +.. cfgcmd:: set service dhcpv6-server shared-network-name subnet nis-server
Specify a NIS server address for DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name '' subnet '' nisplus-server '
' +.. cfgcmd:: set service dhcpv6-server shared-network-name subnet nisplus-server
Specify a NIS+ server address for DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name '' subnet '' sip-server-address '
' +.. cfgcmd:: set service dhcpv6-server shared-network-name subnet sip-server-address
Specify a :abbr:`SIP (Session Initiation Protocol)` server by IPv6 address for all DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name '' subnet '' sip-server-name '' +.. cfgcmd:: set service dhcpv6-server shared-network-name subnet sip-server-name Specify a :abbr:`SIP (Session Initiation Protocol)` server by FQDN for all DHCPv6 clients. -.. cfgcmd:: set service dhcpv6-server shared-network-name '' subnet '' sntp-server-address '
' +.. cfgcmd:: set service dhcpv6-server shared-network-name subnet sntp-server-address
A SNTP server address can be specified for DHCPv6 clients. @@ -570,7 +570,7 @@ https://wiki.vyos.net/wiki/Network_address_setup. Configuration ------------- -.. cfgcmd:: set service dhcp-relay interface '' +.. cfgcmd:: set service dhcp-relay interface Enable the DHCP relay service on the given interface. diff --git a/docs/services/ssh.rst b/docs/services/ssh.rst index fde575ea..1dd996d4 100644 --- a/docs/services/ssh.rst +++ b/docs/services/ssh.rst @@ -30,17 +30,17 @@ and integrity of data over an unsecured network, such as the Internet. Configuration ============= -.. cfgcmd:: set service ssh port '' +.. cfgcmd:: set service ssh port -Enabling SSH only requires you to specify the port ```` you want SSH to +Enabling SSH only requires you to specify the port ```` you want SSH to listen on. By default, SSH runs on port 22. -.. cfgcmd:: set service ssh listen-address '
' +.. cfgcmd:: set service ssh listen-address
Specify IPv4/IPv6 listen address of SSH server. Multiple addresses can be defined. -.. cfgcmd:: set service ssh ciphers '' +.. cfgcmd:: set service ssh ciphers Define allowed ciphers used for the SSH connection. A number of allowed ciphers can be specified, use multiple occurrences to allow multiple ciphers. @@ -71,7 +71,7 @@ security! Disable the host validation through reverse DNS lookups - can speedup login time when reverse lookup is not possible. -.. cfgcmd:: set service ssh macs '' +.. cfgcmd:: set service ssh macs Specifies the available :abbr:`MAC (Message Authentication Code)` algorithms. The MAC algorithm is used in protocol version 2 for data integrity protection. diff --git a/docs/services/tftp.rst b/docs/services/tftp.rst index 8647dfa8..ce87011c 100644 --- a/docs/services/tftp.rst +++ b/docs/services/tftp.rst @@ -22,7 +22,7 @@ files. content on image upgrades. Any directory under ``/config`` is save at this will be migrated. -.. cfgcmd:: set service tftp-server listen-address '
' +.. cfgcmd:: set service tftp-server listen-address
Configure the IPv4 or IPv6 listen address of the TFTP server. Multiple IPv4 and IPv6 addresses can be given. There will be one TFTP server instances listening diff --git a/docs/services/udp-broadcast-relay.rst b/docs/services/udp-broadcast-relay.rst index 10939c9d..f9e1b03e 100644 --- a/docs/services/udp-broadcast-relay.rst +++ b/docs/services/udp-broadcast-relay.rst @@ -17,23 +17,23 @@ support 99 IDs! Configuration ------------- -.. cfgcmd:: set service broadcast-relay id '' description '' +.. cfgcmd:: set service broadcast-relay id description A description can be added for each and every unique relay ID. This is usefull to distinguish between multiple different ports/appliactions. -.. cfgcmd:: set service broadcast-relay id '' interface '' +.. cfgcmd:: set service broadcast-relay id interface The interface used to receive and relay individual broadcast packets. If you want to receive/relay packets on both `eth1` and `eth2` both interfaces need to be added. -.. cfgcmd:: set service broadcast-relay id '' port '' +.. cfgcmd:: set service broadcast-relay id port The UDP port number used by your apllication. It is mandatory for this kind of operation. -.. cfgcmd:: set service broadcast-relay id '' disable +.. cfgcmd:: set service broadcast-relay id disable Each broadcast relay instance can be individually disabled without deleting the configured node by using the following command: diff --git a/docs/system/config-management.rst b/docs/system/config-management.rst index df2a80aa..9d65adb3 100644 --- a/docs/system/config-management.rst +++ b/docs/system/config-management.rst @@ -13,7 +13,7 @@ stored on a remote host for archiving/backup reasons. Change the number of commit revisions to ``, the default setting for this value is to store 20 revisions locally. -.. cfgcmd:: set system config-management commit-archive location '' +.. cfgcmd:: set system config-management commit-archive location If you want to save all config changes to a remote destination. Set the commit-archive location. Every time a commit is successfully the diff --git a/docs/system/default-route.rst b/docs/system/default-route.rst index a46790e4..27c74188 100644 --- a/docs/system/default-route.rst +++ b/docs/system/default-route.rst @@ -5,13 +5,13 @@ Default Gateway/Route ##################### In the past (VyOS 1.1) used a gateway-address configured under the system tree -(:cfgcmd:`set system gateway-address '
'`), this is no longer supported +(:cfgcmd:`set system gateway-address
`), this is no longer supported and existing configurations are migrated to the new CLI command. Configuration ============= -.. cfgcmd:: set protocols static route 0.0.0.0/0 next-hop '
' +.. cfgcmd:: set protocols static route 0.0.0.0/0 next-hop
Specify static route into the routing table sending all non local traffic to the nexthop address `
`. diff --git a/docs/system/flow-accounting.rst b/docs/system/flow-accounting.rst index 52a2a18d..df58e1f3 100644 --- a/docs/system/flow-accounting.rst +++ b/docs/system/flow-accounting.rst @@ -45,7 +45,7 @@ Configururation In order for flow accounting information to be collected and displayed for an interface, the interface must be configured for flow accounting. -.. cfgcmd:: set system flow-accounting interface '' +.. cfgcmd:: set system flow-accounting interface Configure and enable collection of flow information for the interface identified by ``. @@ -68,12 +68,12 @@ 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 '' +.. cfgcmd:: set system flow-accounting 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 '' +.. cfgcmd:: set system flow-accounting syslog-facility Flow Export @@ -85,7 +85,7 @@ exported them to a collection server. NetFlow ^^^^^^^ -.. cfgcmd:: set system flow-accounting netflow version '' +.. cfgcmd:: set system flow-accounting netflow version There are multiple versions available for the NetFlow data. The `` used in the exported flow data can be configured here. The following @@ -95,20 +95,20 @@ NetFlow * **9** - NetFlow version 9 (default) * **10** - :abbr:`IPFIX (IP Flow Information Export)` as per :rfc:`3917` -.. cfgcmd:: set system flow-accounting netflow server '
' +.. cfgcmd:: set system flow-accounting netflow server
Configure address of NetFlow collector. NetFlow server at `
` can be both listening on an IPv4 or IPv6 address. -.. cfgcmd:: set system flow-accounting netflow source-ip '
' +.. cfgcmd:: set system flow-accounting netflow source-ip
IPv4 or IPv6 source address of NetFlow packets -.. cfgcmd:: set system flow-accounting netflow engine-id '' +.. cfgcmd:: set system flow-accounting netflow engine-id NetFlow engine-id which will appear in NetFlow data. The range is 0 to 255. -.. cfgcmd:: set system flow-accounting netflow sampling-rate '' +.. cfgcmd:: set system flow-accounting netflow sampling-rate Use this command to configure the sampling rate for flow accounting. The system samples one in every `` packets, where `` is the value @@ -120,7 +120,7 @@ NetFlow Per default every packet is sampled (that is, the sampling rate is 1). -.. cfgcmd:: set system flow-accounting netflow timeout expiry interval '' +.. cfgcmd:: set system flow-accounting netflow timeout expiry interval Specifies the interval at which Netflow data will be sent to a collector. As per default, Netflow data will be sent every 60 seconds. @@ -128,24 +128,24 @@ NetFlow You may also additionally configure timeouts for different types of connections. -.. cfgcmd:: set system flow-accounting netflow max-flows '' +.. cfgcmd:: set system flow-accounting netflow max-flows 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 '
' +.. cfgcmd:: set system flow-accounting sflow server
Configure address of sFlow collector. sFlow server at `
` 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 '' +.. cfgcmd:: set system flow-accounting sflow sampling-rate Enable sampling of packets, which will be transmitted to sFlow collectors. -.. cfgcmd:: set system flow-accounting sflow agent-address '
' +.. cfgcmd:: set system flow-accounting sflow agent-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 @@ -169,7 +169,7 @@ Operation Once flow accounting is configured on an interfaces it provides the ability to display captured network traffic information for all configured interfaces. -.. opcmd:: show flow-accounting interface '' +.. opcmd:: show flow-accounting interface Show flow accounting information for given ``. @@ -186,7 +186,7 @@ display captured network traffic information for all configured interfaces. eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 40006 22 tcp 16 146 1 9444 eth0 00:53:01:b2:22:48 00:53:02:58:a2:92 192.0.2.100 192.0.2.14 0 0 icmp 192 27 1 4455 -.. opcmd:: show flow-accounting interface '' host '
' +.. opcmd:: show flow-accounting interface host
Show flow accounting information for given `` for a specific host only. diff --git a/docs/system/host-information.rst b/docs/system/host-information.rst index e4cbd584..30efe01e 100644 --- a/docs/system/host-information.rst +++ b/docs/system/host-information.rst @@ -20,7 +20,7 @@ network and is used to distinguish one device from another on specific networks or over the internet. On the other hand this will be the name which appears on the command line prompt. -.. cfgcmd:: set system host-name '' +.. cfgcmd:: set system host-name Set system hostname. The hostname can be up to 63 characters. A hostname must start and end with a letter or digit, and have as interior characters @@ -36,7 +36,7 @@ unique. VyOS appends the domain name as a suffix to any unqualified name. For example, if you set the domain name `example.com`, and you would ping the unqualified name of `crux`, then VyOS qualifies the name to `crux.example.com`. -.. cfgcmd:: set system domain-name '' +.. cfgcmd:: set system domain-name 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. @@ -48,16 +48,16 @@ How an IP address is assigned to an interface in :ref:`ethernet-interface`. This section shows how to statically map an IP address to a hostname for local (meaning on this VyOS instance) name resolution. -.. cfgcmd:: set system static-host-mapping host-name '' inet '
' +.. cfgcmd:: set system static-host-mapping host-name inet
Create a static hostname mapping which will always resolve the name `` to IP address `
`. -.. cfgcmd:: set system static-host-mapping host-name '' alias '' +.. cfgcmd:: set system static-host-mapping host-name alias Create named `` for the configured static mapping for ``. Thus the address configured as :cfgcmd:`set system static-host-mapping - host-name '' inet '
'` can be reached via multiple names. + host-name inet
` can be reached via multiple names. Multiple aliases can pe specified per host-name. diff --git a/docs/system/ntp.rst b/docs/system/ntp.rst index 0836f2fa..5fd1837f 100644 --- a/docs/system/ntp.rst +++ b/docs/system/ntp.rst @@ -33,9 +33,9 @@ in :rfc:`1305`. Configuration ============= -.. cfgcmd:: set system ntp server '
' +.. cfgcmd:: set system ntp server
- Configure one or more servers for synchronisation. Server name cen be either + Configure one or more servers for synchronisation. Server name can be either an IP address or :abbr:`FQDN (Fully Qualified Domain Name)`. There are 3 default NTP server set. You are able to change them. @@ -44,13 +44,13 @@ Configuration * 1.pool.ntp.org * 2.pool.ntp.org -.. cfgcmd:: set system ntp listen-address '
' +.. cfgcmd:: set system ntp listen-address
Setup VyOS as an NTP responder, you must specify the `
` and optionally the permitted clients. Multiple listen addresses can be configured. -.. cfgcmd:: set system ntp allow-clients address '
' +.. cfgcmd:: set system ntp allow-clients address
List of networks or client addresses permitted to contact this NTP server. Multiple networks can be configured. diff --git a/docs/system/proxy.rst b/docs/system/proxy.rst index 40bdf998..8e0339a7 100644 --- a/docs/system/proxy.rst +++ b/docs/system/proxy.rst @@ -8,21 +8,21 @@ Some IT environments require the use of a proxy to connect to the Internet. Without this configuration VyOS updates could not be installed directly by using the :opcmd:`add system image` command (:ref:`update_vyos`). -.. cfgcmd:: set system proxy url '' +.. cfgcmd:: set system proxy url Set proxy for all connections initiated by VyOS, including HTTP, HTTPS, and FTP (anonymous ftp). -.. cfgcmd:: set system proxy port '' +.. cfgcmd:: set system proxy port Configure proxy port if it does not listen to the default port 80. -.. cfgcmd:: set system proxy username '' +.. cfgcmd:: set system proxy username Some proxys require/support the "basic" HTTP authentication scheme as per :rfc:`7617`, thus a username can be configured. -.. cfgcmd:: set system proxy password '' +.. cfgcmd:: set system proxy password Some proxys require/support the "basic" HTTP authentication scheme as per :rfc:`7617`, thus a password can be configured. diff --git a/docs/system/serial-console.rst b/docs/system/serial-console.rst index cd27fa21..309c6ad2 100644 --- a/docs/system/serial-console.rst +++ b/docs/system/serial-console.rst @@ -16,7 +16,7 @@ access to the console is the only way to diagnose and correct software failures. Major upgrades to the installed distribution may also require console access. -.. cfgcmd:: set system console device '' +.. cfgcmd:: set system console device Defines the specified device as a system console. Available console devices can be (see completion helper): @@ -25,7 +25,7 @@ Major upgrades to the installed distribution may also require console access. * ``ttyUSBX`` - USB Serial device name * ``hvc0`` - Xen console -.. cfgcmd:: set system console device '' speed '' +.. cfgcmd:: set system console device speed The speed (baudrate) of the console device. Supported values are: @@ -44,6 +44,6 @@ Network Console TBD. -.. cfgcmd:: set system console network '' +.. cfgcmd:: set system console network ... and many more commands ... \ No newline at end of file diff --git a/docs/system/task-scheduler.rst b/docs/system/task-scheduler.rst index 869a0600..382da39f 100644 --- a/docs/system/task-scheduler.rst +++ b/docs/system/task-scheduler.rst @@ -11,7 +11,7 @@ use of UNIX cron_. be dangerous. Together with :ref:`command-scripting` this can be used for automating (re-)configuration. -.. cfgcmd:: set system task-scheduler task '' interval '' +.. cfgcmd:: set system task-scheduler task interval Specify the time interval when `` should be executed. The interval is specified as number with one of the following suffixes: @@ -23,17 +23,17 @@ use of UNIX cron_. .. note:: If suffix is omitted, minutes are implied. -.. cfgcmd:: set system task-scheduler task '' crontab-spec '' +.. cfgcmd:: set system task-scheduler task crontab-spec Set execution time in common cron_ time format. A cron `` of ``30 */6 * * *`` would execute the `` at minute 30 past every 6th hour. -.. cfgcmd:: set system task-scheduler task '' executable path '' +.. cfgcmd:: set system task-scheduler task executable path Specify absolute `` to script which will be run when `` is executed. -.. cfgcmd:: set system task-scheduler task '' executable arguments '' +.. cfgcmd:: set system task-scheduler task executable arguments Arguments which will be passed to the executable. diff --git a/docs/system/time-zone.rst b/docs/system/time-zone.rst index d65e1d78..025c4376 100644 --- a/docs/system/time-zone.rst +++ b/docs/system/time-zone.rst @@ -8,7 +8,7 @@ Time Zone setting is very important as e.g all your logfile entries will be based on the configured zone. Without proper time zone configuration it will be very difficult to compare logfiles from different systems. -.. cfgcmd:: set system time-zone '' +.. cfgcmd:: set system time-zone Specify the systems `` as the Region/Location that best defines your location. For example, specifying US/Pacific sets the time zone to US diff --git a/docs/system/user-management.rst b/docs/system/user-management.rst index b2dd3d08..bb9a6e90 100644 --- a/docs/system/user-management.rst +++ b/docs/system/user-management.rst @@ -15,23 +15,23 @@ Authentication Dial-In User Service)` accounts are supported. Local ===== -.. cfgcmd:: set system login user '' full-name "" +.. cfgcmd:: set system login user full-name "" Create new system user with username `` and real-name specified by ``. -.. cfgcmd:: set system login user '' authentication plaintext-password '' +.. cfgcmd:: set system login user authentication plaintext-password Specify the plaintext password user by user `` on this system. The plaintext password will be automatically transferred into a secure hashed password and not saved anywhere in plaintext. -.. cfgcmd:: set system login user '' authentication encrypted-password '' +.. cfgcmd:: set system login user authentication encrypted-password Setup encrypted password for given username. This is usefull for transferring a hashed password from system to system. -.. cfgcmd:: set system login user '' group '' +.. cfgcmd:: set system login user group Specify additional group membership for given username ``. @@ -55,12 +55,12 @@ and paste it. Some terminal emulators may accidentally split this over several lines. Be attentive when you paste it that it only pastes as a single line. The third part is simply an identifier, and is for your own reference. -.. cfgcmd:: set system login user '' authentication public-keys '' key '' +.. cfgcmd:: set system login user authentication public-keys key Assign the SSH public key portion `` identified by per-key `` to the local user ``. -.. cfgcmd:: set system login user '' authentication public-keys '' type '' +.. cfgcmd:: set system login user authentication public-keys type Every SSH public key portion referenced by `` requires the configuration of the `` of public-key used. This type can be any of: @@ -75,7 +75,7 @@ The third part is simply an identifier, and is for your own reference. .. note:: You can assign multiple keys to the same user by using a unique identifier per SSH key. -.. cfgcmd:: loadkey '' '' +.. cfgcmd:: loadkey SSH keys can not only be specified on the command-line but also loaded for a given user with `` from a file pointed to by `.` Keys @@ -113,17 +113,17 @@ Dial-In User Service)` servers as backend for user authentication. Configuration ------------- -.. cfgcmd:: set system login radius server '
' secret '' +.. cfgcmd:: set system login radius server
secret Specify the `
` of the RADIUS server user with the pre-shared-secret given in ``. Multiple servers can be specified. -.. cfgcmd:: set system login radius server '
' port '' +.. cfgcmd:: set system login radius server
port Configure the discrete port under which the RADIUS server can be reached. This defaults to 1812. -.. cfgcmd:: set system login radius server '
' timeout '' +.. cfgcmd:: set system login radius server
timeout Setup the `` in seconds when querying the RADIUS server. @@ -132,7 +132,7 @@ Configuration the attribute you will only get regular, non privilegued, system users. -.. cfgcmd:: set system login radius source-address '
' +.. cfgcmd:: set system login radius source-address
RADIUS servers could be hardened by only allowing certain IP addresses to connect. As of this the source address of each RADIUS query can be @@ -148,12 +148,12 @@ Login Banner You are able to set post-login or pre-login banner messages to display certain information for this system. -.. cfgcmd:: set system login banner pre-login '' +.. cfgcmd:: set system login banner pre-login Configure `` which is shown during SSH connect and before a user is logged in. -.. cfgcmd:: set system login banner post-login '' +.. cfgcmd:: set system login banner post-login Configure `` which is shown after user has logged in to the system. -- cgit v1.2.3 From 92f65db0256c6f3bef42c62cb32ce02512944743 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Mon, 30 Dec 2019 12:13:36 +0100 Subject: loopback: add missing interface description --- docs/interfaces/basic-index.rst | 1 + docs/interfaces/loopback.rst | 69 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+) create mode 100644 docs/interfaces/loopback.rst (limited to 'docs') diff --git a/docs/interfaces/basic-index.rst b/docs/interfaces/basic-index.rst index 3477b238..c652c7bb 100644 --- a/docs/interfaces/basic-index.rst +++ b/docs/interfaces/basic-index.rst @@ -8,4 +8,5 @@ Basic Interfaces :maxdepth: 1 ethernet + loopback pppoe diff --git a/docs/interfaces/loopback.rst b/docs/interfaces/loopback.rst new file mode 100644 index 00000000..ccdc88e5 --- /dev/null +++ b/docs/interfaces/loopback.rst @@ -0,0 +1,69 @@ +.. _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. + +Configuration +============= + +Address +------- + +.. cfgcmd:: set interfaces loopback lo 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 + + Assign given `` 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: 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 -- cgit v1.2.3 From d1d636612fbf4bb80ad9097ed451f845ab4690c7 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Mon, 30 Dec 2019 12:14:06 +0100 Subject: dummy: add reference to loopback interface --- docs/interfaces/dummy.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/interfaces/dummy.rst b/docs/interfaces/dummy.rst index c74e5f48..3bf7bc1d 100644 --- a/docs/interfaces/dummy.rst +++ b/docs/interfaces/dummy.rst @@ -5,10 +5,10 @@ Dummy ##### The dummy interface is really a little exotic, but rather useful nevertheless. -Dummy interfaces are much like the loopback interface, except you can have -as many as you want. Dummy interfaces can be used as interfaces that always -stay up (in the same fashion to loopbacks in Cisco IOS), or for testing -purposes. +Dummy interfaces are much like the :ref:`loopback-interface` interface, except +you can have as many as you want. Dummy interfaces can be used as interfaces +that always stay up (in the same fashion to loopbacks in Cisco IOS), or for +testing purposes. Configuration ############# -- cgit v1.2.3 From 158b50d2476d5e5efe3189f4a933aa480f9b0a43 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Mon, 30 Dec 2019 12:15:24 +0100 Subject: geneve: add Configuration headline --- docs/interfaces/geneve.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs') diff --git a/docs/interfaces/geneve.rst b/docs/interfaces/geneve.rst index dc762738..b0bfde06 100644 --- a/docs/interfaces/geneve.rst +++ b/docs/interfaces/geneve.rst @@ -32,6 +32,9 @@ Geneve Header: | Variable Length Options | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +Configuration +============= + .. cfgcmd:: set interfaces geneve gnv0 address '192.0.2.2/24' Create GENEVE tunnel listening on local address `192.0.2.2/24`. -- cgit v1.2.3 From 5a09b36ecbcfcfa3f71861d7c586b9edee73b61a Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Mon, 30 Dec 2019 12:17:20 +0100 Subject: vxlan: use documented section style guide --- docs/interfaces/vxlan.rst | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/interfaces/vxlan.rst b/docs/interfaces/vxlan.rst index e597e167..04e38f7e 100644 --- a/docs/interfaces/vxlan.rst +++ b/docs/interfaces/vxlan.rst @@ -1,7 +1,8 @@ .. _vxlan-interface: +##### VXLAN ------ +##### :abbr:`VXLAN (Virtual Extensible LAN)` is a network virtualization technology that attempts to address the scalability problems associated with large cloud @@ -33,7 +34,7 @@ may be blocked by the hypervisor. per VXLAN interface basis to get it working accross multiple vendors. Multicast VXLAN -^^^^^^^^^^^^^^^^ +=============== Example Topology: @@ -65,8 +66,8 @@ For optimal scalability Multicast shouldn't be used at all, but instead use BGP to signal all connected devices between leafs. Unfortunately, VyOS does not yet support this. -Configuration commands -^^^^^^^^^^^^^^^^^^^^^^ +Configuration +============= .. code-block:: none @@ -83,8 +84,8 @@ Configuration commands remote # Remote address of the VXLAN tunnel, used for PTP instead of multicast vni <1-16777215> # Virtual Network Identifier (required) -Configuration Example -^^^^^^^^^^^^^^^^^^^^^ +Example +------- The setup is this: @@ -239,7 +240,7 @@ configuration directive to support a user-specified destination port to override that behavior is available using the above command. Older Examples -^^^^^^^^^^^^^^ +-------------- Example for bridging normal L2 segment and vxlan overlay network, and using a vxlan interface as routing interface. @@ -304,7 +305,7 @@ gateway. You can add an IP to a bridge to create a gateway. } Unicast VXLAN -^^^^^^^^^^^^^ +============= Alternative to multicast, the remote IPv4 address of the VXLAN tunnel can set directly. Let's change the Multicast example from above: -- cgit v1.2.3 From ce35b285a9a90c73343d32165f25991ea6b63ab8 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Mon, 30 Dec 2019 12:42:41 +0100 Subject: dummy: smoothen IPv6 address description --- docs/interfaces/dummy.rst | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/interfaces/dummy.rst b/docs/interfaces/dummy.rst index 3bf7bc1d..7fee2700 100644 --- a/docs/interfaces/dummy.rst +++ b/docs/interfaces/dummy.rst @@ -19,14 +19,8 @@ Address .. cfgcmd:: set interfaces dummy address
Configure dummy 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. + 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: -- cgit v1.2.3 From 460c8b7a43434d1c914b654f5940a087bbe9019e Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Mon, 30 Dec 2019 12:42:58 +0100 Subject: loopback: smoothen IPv6 address description --- docs/interfaces/loopback.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/interfaces/loopback.rst b/docs/interfaces/loopback.rst index ccdc88e5..2d554de4 100644 --- a/docs/interfaces/loopback.rst +++ b/docs/interfaces/loopback.rst @@ -21,9 +21,8 @@ Address .. cfgcmd:: set interfaces loopback lo 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 + 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 ------------------- -- cgit v1.2.3 From 779858390878e81e16fa02347182da52547bef05 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Mon, 30 Dec 2019 12:43:20 +0100 Subject: ethernet: add (A/D) shortcut for admin down --- docs/interfaces/ethernet.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/interfaces/ethernet.rst b/docs/interfaces/ethernet.rst index 693634fb..0c2347e4 100644 --- a/docs/interfaces/ethernet.rst +++ b/docs/interfaces/ethernet.rst @@ -96,7 +96,7 @@ Link Administration .. cfgcmd:: set interfaces ethernet disable Disable given ``. It will be placed in administratively down - state. + (``A/D``) state. .. cfgcmd:: set interfaces ethernet disable-flow-control -- cgit v1.2.3 From 5811a15d43b7d58796bdbe80e4dfb66c36d6d579 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Mon, 30 Dec 2019 12:43:45 +0100 Subject: vxlan: use documented section style guide --- docs/interfaces/vxlan.rst | 204 ++++++++++++++++++++++++---------------------- 1 file changed, 107 insertions(+), 97 deletions(-) (limited to 'docs') diff --git a/docs/interfaces/vxlan.rst b/docs/interfaces/vxlan.rst index 04e38f7e..927eb40b 100644 --- a/docs/interfaces/vxlan.rst +++ b/docs/interfaces/vxlan.rst @@ -33,12 +33,108 @@ may be blocked by the hypervisor. for VXLAN, VyOS uses a default port of 8472. You can change the port on a per VXLAN interface basis to get it working accross multiple vendors. +Configuration +============= + +Address +------- + +.. cfgcmd:: set interfaces vxlan address
+ + Configure VXLAN 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 ipv6 address autoconf + + :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. + + +.. cfgcmd:: set interfaces vxlan ipv6 address eui64 + + :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 link + + 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 group
+ + Multicast group address for VXLAN interface. VXLAN tunnels can be built + either via Multicast or via Unicast. + + +.. cfgcmd:: set interfaces vxlan remote
+ + IPv4 remote address of the VXLAN tunnel. Alternative to multicast, the + remote IPv4 address of the VXLAN tunnel can set directly. + + +.. cfgcmd:: set interfaces vxlan 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 vni + + 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 description + + Assign given `` to interface. Description will also be passed + to SNMP monitoring systems. + +.. cfgcmd:: set interfaces vxlan disable + + Disable given ``. It will be placed in administratively down + (``A/D``) state. + +.. cfgcmd:: set interfaces vxlan mtu + + Configure :abbr:`MTU (Maximum Transmission Unit)` on given ``. 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 =============== -Example Topology: - -PC4 - Leaf2 - Spine1 - Leaf3 - PC5 +Topology: PC4 - Leaf2 - Spine1 - Leaf3 - PC5 PC4 has IP 10.0.0.4/24 and PC5 has IP 10.0.0.5/24, so they believe they are in the same broadcast domain. @@ -66,30 +162,10 @@ For optimal scalability Multicast shouldn't be used at all, but instead use BGP to signal all connected devices between leafs. Unfortunately, VyOS does not yet support this. -Configuration -============= - -.. code-block:: none - - interfaces - vxlan - address # IP address of the VXLAN interface - description # Description - group # IPv4 Multicast group address (required) - ip # IPv4 routing options - ipv6 # IPv6 routing options - link # 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) - Example ------- -The setup is this: - -Leaf2 - Spine1 - Leaf3 +The setup is this: Leaf2 - Spine1 - Leaf3 Spine1 is a Cisco IOS router running version 15.4, Leaf2 and Leaf3 is each a VyOS router running 1.2. @@ -112,7 +188,7 @@ Topology: Eth0 towards Spine1, IP-address 10.1.3.3/24 Eth1 towards a vlan-aware switch -Spine1 Configuration: +**Spine1 Configuration:** .. code-block:: none @@ -132,10 +208,10 @@ Spine1 Configuration: Multicast-routing is required for the leafs to forward traffic between each other in a more scalable way. This also requires PIM to be enabled towards the -Leafs so that the Spine can learn what multicast groups each Leaf expect traffic -from. +Leafs so that the Spine can learn what multicast groups each Leaf expect +traffic from. -Leaf2 configuration: +**Leaf2 configuration:** .. code-block:: none @@ -160,7 +236,7 @@ Leaf2 configuration: set interfaces vxlan vxlan242 link 'eth0' set interfaces vxlan vxlan242 vni '242' -Leaf3 configuration: +**Leaf3 configuration:** .. code-block:: none @@ -239,77 +315,11 @@ its pre-standard value of 8472 to preserve backwards compatibility. A configuration directive to support a user-specified destination port to override that behavior is available using the above command. -Older Examples --------------- - -Example for bridging normal L2 segment and vxlan overlay network, and using a -vxlan interface as routing interface. - -.. code-block:: none - - interfaces { - bridge br0 { - member { - interface vxlan0 { - } - } - } - ethernet eth0 { - address dhcp - } - loopback lo { - } - vxlan vxlan0 { - group 239.0.0.1 - vni 0 - } - vxlan vxlan1 { - address 192.168.0.1/24 - link eth0 - group 239.0.0.1 - vni 1 - } - } - -Here is a working configuration that creates a VXLAN between two routers. Each -router has a VLAN interface (26) facing the client devices and a VLAN interface -(30) that connects it to the other routers. With this configuration, traffic -can flow between both routers' VLAN 26, but can't escape since there is no L3 -gateway. You can add an IP to a bridge to create a gateway. - -.. code-block:: none - - interfaces { - bridge br0 { - member { - interface eth0.26 { - } - interface vxlan0 { - } - } - } - ethernet eth0 { - duplex auto - smp-affinity auto - speed auto - vif 30 { - address 10.7.50.6/24 - } - } - loopback lo { - } - vxlan vxlan0 { - group 239.0.0.241 - vni 241 - } - } - Unicast VXLAN ============= -Alternative to multicast, the remote IPv4 address of the VXLAN tunnel can set directly. -Let's change the Multicast example from above: - +Alternative to multicast, the remote IPv4 address of the VXLAN tunnel can be +set directly. Let's change the Multicast example from above: .. code-block:: none -- cgit v1.2.3 From 0632e8d8d0c2f2eb70ede5f02aa9c77cab2be2d0 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Mon, 30 Dec 2019 12:44:44 +0100 Subject: bridge: use documented section style guide --- docs/interfaces/bridge.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/interfaces/bridge.rst b/docs/interfaces/bridge.rst index a7bbbca6..50f0a58c 100644 --- a/docs/interfaces/bridge.rst +++ b/docs/interfaces/bridge.rst @@ -1,7 +1,8 @@ .. _bridge-interface: +###### Bridge ------- +###### Interfaces in VyOS can be bridged together to provide software switching of Layer-2 traffic. -- cgit v1.2.3 From cd5f73a781c46ee6b702e4056e769a5a66cffdc9 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Mon, 30 Dec 2019 13:18:24 +0100 Subject: ethernet: use common wording on interface address --- docs/interfaces/ethernet.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/interfaces/ethernet.rst b/docs/interfaces/ethernet.rst index 0c2347e4..1a1edb32 100644 --- a/docs/interfaces/ethernet.rst +++ b/docs/interfaces/ethernet.rst @@ -12,8 +12,7 @@ Address .. cfgcmd:: set interfaces ethernet address
- Configure ethernet interface `` with one or more interface - addresses. + Configure 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 -- cgit v1.2.3 From 37ad1d5bc694daf3ffd7ad8ef317cdb42735c425 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Mon, 30 Dec 2019 13:19:01 +0100 Subject: bridge: rewrite with new cfgcmd/opcmd syntax --- docs/interfaces/bridge.rst | 308 +++++++++++++++++++++++++++++++++------------ 1 file changed, 230 insertions(+), 78 deletions(-) (limited to 'docs') diff --git a/docs/interfaces/bridge.rst b/docs/interfaces/bridge.rst index 50f0a58c..18fb19ba 100644 --- a/docs/interfaces/bridge.rst +++ b/docs/interfaces/bridge.rst @@ -4,110 +4,262 @@ Bridge ###### -Interfaces in VyOS can be bridged together to provide software switching of -Layer-2 traffic. +A Bridge is a way to connect two Ethernet segments together in a protocol +independent way. Packets are forwarded based on Ethernet address, rather than +IP address (like a router). Since forwarding is done at Layer 2, all protocols +can go transparently through a bridge. The Linux bridge code implements a +subset of the ANSI/IEEE 802.1d standard. -A bridge is created when a bridge interface is defined. In the example below -we create a bridge named br100 with eth1 and eth2 as the bridge member ports. +Configuration +############# -.. code-block:: none +Address +------- - set interfaces bridge 'br100' - set interfaces bridge br100 member interface eth1 - set interfaces bridge br100 member interface eth2 +.. cfgcmd:: set interfaces bridge address
-Each bridge member can be assiged a port cost and priority using the following -commands: + Configure interface `` with one or more interface addresses. -.. code-block:: none + * **address** can be specified multiple times as IPv4 and/or IPv6 address, + e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + * **dhcp** interface address is received by DHCP from a DHCP server on this + segment. + * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 server on + this segment. - set interfaces bridge br100 member interface eth1 cost 10 - set interfaces bridge br100 member interface eth1 priority 1024 + Example: -Interfaces assigned to a bridge do not have address configuration. An IP -address can be assigned to the bridge interface itself, however, like any -normal interface. + .. code-block:: none -.. code-block:: none + set interfaces bridge br0 address 192.0.2.1/24 + set interfaces bridge br0 address 192.0.2.2/24 + set interfaces bridge br0 address 2001:db8::ffff/64 + set interfaces bridge br0 address 2001:db8:100::ffff/64 - set interfaces bridge br100 address '192.168.100.1/24' - set interfaces bridge br100 address '2001:db8:100::1/64' -Example Result: +.. cfgcmd:: set interfaces bridge ipv6 address autoconf -.. code-block:: none + :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. - bridge br100 { - address 192.168.100.1/24 - address 2001:db8:100::1/64 - member { - interface eth1 { - cost 10 - priority 1024 - } - interface eth2 { - } - } + .. note:: This method automatically disables IPv6 traffic forwarding on the + interface in question. - } - [...] -In addition to normal IP interface configuration, bridge interfaces support -Spanning-Tree Protocol. STP is disabled by default. +.. cfgcmd:: set interfaces bridge ipv6 address eui64 -.. note:: Please use caution when introducing spanning-tree protocol on a - network as it may result in topology changes. + :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. -To enable spanning-tree use the `set interfaces bridge stp` command: + .. code-block:: none -.. code-block:: none + set interfaces bridge eth0 ipv6 address eui64 2001:db8:beef::/64 - set interfaces bridge br100 stp -STP `priority`, `forwarding-delay`, `hello-time`, and `max-age` can be -configured for the bridge. The MAC aging time can also be configured -using the `aging` directive. +.. cfgcmd:: set interfaces bridge aging