From 4a06deda27cd52d6c912ca369fc79372dbcb6640 Mon Sep 17 00:00:00 2001 From: "Daniel T. Thorpe" Date: Wed, 26 Aug 2020 00:15:05 +0100 Subject: docs(syslog.rst): corrected en to an --- docs/system/syslog.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/system/syslog.rst b/docs/system/syslog.rst index 3a8b344a..3449c15b 100644 --- a/docs/system/syslog.rst +++ b/docs/system/syslog.rst @@ -22,7 +22,7 @@ Console .. cfgcmd:: set system syslog console facility level -Log syslog messages to ``/dev/console``, for en explanation on +Log syslog messages to ``/dev/console``, for an explanation on :ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords see tables below. -- cgit v1.2.3 From 43b73bbdf00ae284c6a5375ec7e35a82c941f9c3 Mon Sep 17 00:00:00 2001 From: dus2002 <52572272+dus2002@users.noreply.github.com> Date: Tue, 25 Aug 2020 23:25:03 +0000 Subject: fix bad typing --- docs/contributing/build-vyos.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst index 43c1e608..9af21f51 100644 --- a/docs/contributing/build-vyos.rst +++ b/docs/contributing/build-vyos.rst @@ -154,7 +154,7 @@ in the repository_. The ``./configure`` script will also warn you if any dependencies are missing. Once you have the required dependencies installed, you may proceed with the -steps descirbed in :ref:`build_iso`. +steps described in :ref:`build_iso`. .. _build_iso: -- cgit v1.2.3 From 7f209a2a456ea27a3d7b13b05e78401c48670131 Mon Sep 17 00:00:00 2001 From: kroy Date: Thu, 27 Aug 2020 23:42:57 -0500 Subject: bgp: fix missing ` termination --- docs/routing/bgp.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/routing/bgp.rst b/docs/routing/bgp.rst index 2c5e7089..c576d836 100644 --- a/docs/routing/bgp.rst +++ b/docs/routing/bgp.rst @@ -4,7 +4,7 @@ BGP ### -:abbr:`BGP (Border Gateway Protocol) is one of the Exterior Gateway Protocols +:abbr:`BGP (Border Gateway Protocol)` is one of the Exterior Gateway Protocols and the de facto standard interdomain routing protocol. The latest BGP version is 4. BGP-4 is described in :rfc:`1771` and updated by :rfc:`4271`. :rfc:`2858` adds multiprotocol support to BGP. -- cgit v1.2.3 From 3611f346f0501d174af49935b017a9f1d6694c62 Mon Sep 17 00:00:00 2001 From: Ilaria Luciani Date: Thu, 3 Sep 2020 20:10:16 +0200 Subject: fix: change wording in description --- docs/about.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/about.rst b/docs/about.rst index 0411344b..d892ae4a 100644 --- a/docs/about.rst +++ b/docs/about.rst @@ -8,7 +8,7 @@ VyOS is an open source network operating system based on Debian GNU/Linux. VyOS provides a free routing platform that competes directly with other commercially available solutions from well known network providers. Because -VyOS is run on standard amd64, i586 and ARM systems, it is able to be used +VyOS is run on standard amd64, i586 and ARM systems, it can to be used as a router and firewall platform for cloud deployments. We use multiple live versions of our manual hosted thankfully by -- cgit v1.2.3 From 20f2920d9f95749b247b6e3df92e6768d4a13995 Mon Sep 17 00:00:00 2001 From: Ilaria Luciani Date: Thu, 3 Sep 2020 20:10:39 +0200 Subject: fix: remove typo --- docs/about.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/about.rst b/docs/about.rst index d892ae4a..b9b44351 100644 --- a/docs/about.rst +++ b/docs/about.rst @@ -16,7 +16,7 @@ https://readthedocs.org. We will provide one version of the manual for every VyOS major version starting with VyOS 1.2 which will receive Long-term support (LTS). -The manual version is selected/specified by it's Git branch name. You can +The manual version is selected/specified by its Git branch name. You can switch between versions of the documentation by selecting the appropriate branch on the bottom left corner. -- cgit v1.2.3 From efa25bc32dad395b8fdc8f62b0ed032fa653fa0d Mon Sep 17 00:00:00 2001 From: root Date: Thu, 27 Aug 2020 13:37:11 -0500 Subject: T2810: Docs for vpn anyconnect-server This documentation describes how to configure AnyConnect-Server on VyOS --- docs/vpn/anyconnect.rst | 73 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/vpn/index.rst | 1 + 2 files changed, 74 insertions(+) create mode 100644 docs/vpn/anyconnect.rst (limited to 'docs') diff --git a/docs/vpn/anyconnect.rst b/docs/vpn/anyconnect.rst new file mode 100644 index 00000000..0016cf46 --- /dev/null +++ b/docs/vpn/anyconnect.rst @@ -0,0 +1,73 @@ +.. _vpn-anyconnect: + +AnyConnect +----- + +Cisco AnyConnect-compatible server(based on great OpenConnect software) feature is available from this release. +Anyconnect VPN supports SSL connection and offers full network access. SSL VPN network extension connects the end-user system to the corporate network with access controls based only on network layer information, such as destination IP address and port number. So, it provides safe communication for all types of device traffic across public networks and private networks, also encrypts the traffic with SSL protocol. +The remote user will use the anyconnect client to connect to the router and will receive an IP address from a VPN pool, allowing full access to the network. + +.. note:: All certificates should be stored on VyOS under /config/auth. If certificates are not stored in the /config directory they will not be migrated during a software update. + + +Configuration +^^^^^^^^^^ + +SSL Certificates +---- + +We need to generate the certificate which authenticates users who attempt to access the network resource through the SSL VPN tunnels. +The following command will create a self signed certificates and will be stored in the file path /config/auth + +.. code-block:: none + + openssl req -newkey rsa:4096 -new -nodes -x509 -days 3650 -keyout /config/auth/server.key -out /config/auth/server.crt + openssl req -new -x509 -key /config/auth/server.key -out /config/auth/ca.crt + +We can also create the certificates using Cerbort which is an easy-to-use client that fetches a certificate from Let’s Encrypt—an open certificate authority launched by the EFF, Mozilla, and others—and deploys it to a web server. + +.. code-block:: none + + sudo certbot certonly --standalone --preferred-challenges http -d + +Server Configuration +------------------------- + +.. code-block:: none + + set vpn anyconnect authentication local-users username password + set vpn anyconnect authentication mode + set vpn anyconnect network-settings client-ip-settings subnet + set vpn anyconnect network-settings name-server
+ set vpn anyconnect network-settings name-server
+ set vpn anyconnect ssl ca-cert-file + set vpn anyconnect ssl cert-file + set vpn anyconnect ssl key-file + +Example +---- + +Use local user name "user4" with password "SecretPassword" +Client IP addresses will be provided from pool 100.64.0.0/24 +The Gateway IP Address must be in one of the router´s interfaces. + +.. code-block:: none + + set vpn anyconnect authentication local-users username user4 password 'SecretPassword' + set vpn anyconnect authentication mode 'local' + set vpn anyconnect network-settings client-ip-settings subnet '100.64.0.0/24' + set vpn anyconnect network-settings name-server '1.1.1.1' + set vpn anyconnect network-settings name-server '8.8.8.8' + set vpn anyconnect ssl ca-cert-file '/config/auth/fullchain.pem' + set vpn anyconnect ssl cert-file '/config/auth/cert.pem' + set vpn anyconnect ssl key-file '/config/auth/privkey.pem' + +Verification +---- + +.. code-block:: none + + vyos@RTR1:~$ show anyconnect-server sessions + interface username ip remote IP RX TX state uptime + ----------- ---------- ------------ ------------- -------- -------- --------- -------- + sslvpn0 user4 100.64.0.105 xx.xxx.49.253 127.3 KB 160.0 KB connected 12m:28s diff --git a/docs/vpn/index.rst b/docs/vpn/index.rst index 42a90a3f..aea1ada2 100644 --- a/docs/vpn/index.rst +++ b/docs/vpn/index.rst @@ -15,3 +15,4 @@ VPN site2site_ipsec sstp wireguard + anyconnect -- cgit v1.2.3 From 9971478a6ba830f03493c135019080ae17e0e114 Mon Sep 17 00:00:00 2001 From: currite Date: Mon, 7 Sep 2020 17:12:03 +0200 Subject: installation: add dd parameter for usb creation Add sync to dd command as suggested by John, fix a little typo and restore PXE index hierarchy levels (which got lost with last changes). --- docs/install.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/install.rst b/docs/install.rst index 26d7c7c8..3e31449f 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -217,12 +217,12 @@ stick with with the ``dd`` command: .. code-block:: none - # dd if=/path/to/vyos.iso of=/dev/sdX bs=8M + # dd if=/path/to/vyos.iso of=/dev/sdX bs=8M; sync 5. Wait until you get the outcome (bytes copied). Be patient, in some computers it might take more than one minute. - 6. Once ``dd`` has finished, plug the USB drive out and plug it into + 6. Once ``dd`` has finished, pull the USB drive out and plug it into the powered-off computer where you want to install (or test) VyOS. 7. Power the computer on, making sure it boots from the USB drive (you @@ -239,7 +239,7 @@ macOS and Windows), Rufus_ (for Windows) and `many others`_. You can follow their instructions to create a bootable USB drive from an .iso file. -.. hint:: The default username and password for the live system is ``vyos``. +.. hint:: The default username and password for the live system is *vyos*. .. _permanent_installation: @@ -357,7 +357,7 @@ Configuration ------------- Step 1: DHCP -"""""""""""" +^^^^^^^^^^^^ Configure a DHCP server to provide the client with: @@ -385,7 +385,7 @@ In this example we configured an existent VyOS as the DHCP server: .. _install_from_tftp: Step 2: TFTP -"""""""""""" +^^^^^^^^^^^^ Configure a TFTP server so that it serves the following: @@ -444,7 +444,7 @@ 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 -"""""""""""" +^^^^^^^^^^^^ As you can 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 @@ -455,7 +455,7 @@ First 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. -Second, edit the configuration file at the :ref:`install_from_tftp` so that it shows +Second, edit the configuration file of the :ref:`install_from_tftp` so that it shows the correct URL at ``fetch=http:///filesystem.squashfs``. And third, restart the TFTP service. If you are using VyOS as your TFTP Server, you can restart -- cgit v1.2.3 From 7e5f1b345aa2e99b7bcbcc89a1b7e4498237bbe8 Mon Sep 17 00:00:00 2001 From: Leonardo Rizzi Date: Tue, 8 Sep 2020 05:51:48 +0200 Subject: Docker run command The docker run command was missing of the correct container label. --- docs/contributing/build-vyos.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst index 9af21f51..e8bb9f37 100644 --- a/docs/contributing/build-vyos.rst +++ b/docs/contributing/build-vyos.rst @@ -93,7 +93,7 @@ The container can also be built directly from source: $ cd vyos-build $ docker build -t vyos/vyos-build:crux docker # For VyOS 1.2 - $ docker build -t vyos/vyos-build docker # For rolling release + $ docker build -t vyos/vyos-build:current docker # For rolling release .. note:: Since VyOS has switched to Debian (10) Buster in its ``current`` branch, you will require individual container for `current` and `crux` builds. @@ -184,7 +184,7 @@ Now a fresh build of the VyOS ISO can begin. Change directory to the ``vyos-buil $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:crux bash # For VyOS 1.3 (equuleus, current) - $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build bash + $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:current bash Start the build: @@ -348,7 +348,7 @@ Launch Docker container and build package .. code-block:: none # For VyOS 1.3 (equuleus, current) - $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build bash + $ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:current bash # Change to source directory $ cd vyos-1x -- cgit v1.2.3 From 2e7d4d2ebb24ff6f1dc9e63a03ea4aaad73df96e Mon Sep 17 00:00:00 2001 From: its-ila <45404584+its-ila@users.noreply.github.com> Date: Tue, 8 Sep 2020 22:48:32 +0200 Subject: fix: remove leftover from edit --- docs/about.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/about.rst b/docs/about.rst index b9b44351..383c95eb 100644 --- a/docs/about.rst +++ b/docs/about.rst @@ -8,7 +8,7 @@ VyOS is an open source network operating system based on Debian GNU/Linux. VyOS provides a free routing platform that competes directly with other commercially available solutions from well known network providers. Because -VyOS is run on standard amd64, i586 and ARM systems, it can to be used +VyOS is run on standard amd64, i586 and ARM systems, it can be used as a router and firewall platform for cloud deployments. We use multiple live versions of our manual hosted thankfully by -- cgit v1.2.3 From ec9e4722a78746be3a9efda23a7828f19a4e54d8 Mon Sep 17 00:00:00 2001 From: currite Date: Thu, 10 Sep 2020 02:33:21 +0200 Subject: appendix: reindex to nest virtual environments --- docs/appendix/virtual/index.rst | 12 ++ docs/appendix/virtual/libvirt.rst | 160 ++++++++++++++++++++++ docs/appendix/virtual/vyos-on-gns3.rst | 176 +++++++++++++++++++++++++ docs/appendix/virtual/vyos-on-vmware.rst | 32 +++++ docs/appendix/vyos-on-gns3.rst | 175 ------------------------ docs/appendix/vyos-on-virtual-environments.rst | 172 ------------------------ docs/appendix/vyos-on-vmware.rst | 32 ----- docs/index.rst | 4 +- docs/information.rst | 2 +- 9 files changed, 382 insertions(+), 383 deletions(-) create mode 100644 docs/appendix/virtual/index.rst create mode 100644 docs/appendix/virtual/libvirt.rst create mode 100644 docs/appendix/virtual/vyos-on-gns3.rst create mode 100644 docs/appendix/virtual/vyos-on-vmware.rst delete mode 100644 docs/appendix/vyos-on-gns3.rst delete mode 100644 docs/appendix/vyos-on-virtual-environments.rst delete mode 100644 docs/appendix/vyos-on-vmware.rst (limited to 'docs') diff --git a/docs/appendix/virtual/index.rst b/docs/appendix/virtual/index.rst new file mode 100644 index 00000000..7ede37b5 --- /dev/null +++ b/docs/appendix/virtual/index.rst @@ -0,0 +1,12 @@ +.. _virtual: + +Running on Virtual Environments +=============================== + + +.. toctree:: + :maxdepth: 2 + + libvirt + vyos-on-vmware + vyos-on-gns3 diff --git a/docs/appendix/virtual/libvirt.rst b/docs/appendix/virtual/libvirt.rst new file mode 100644 index 00000000..0d624b94 --- /dev/null +++ b/docs/appendix/virtual/libvirt.rst @@ -0,0 +1,160 @@ +.. _libvirt: + +*************************** +Running on Libvirt Qemu/KVM +*************************** + +Libvirt is an open-source API, daemon and management tool for managing platform virtualization. +There are several ways to deploy VyOS on libvirt kvm. Use Virt-manager and native CLI. +In an example we will be use use 4 gigabytes of memory, 2 cores CPU and default network virbr0. + +CLI +=== + +Deploy from ISO +--------------- + +Create VM name ``vyos_r1``. You must specify the path to the ``ISO`` image, the disk ``qcow2`` will be created automatically. +The ``default`` network is the virtual network (type Virtio) created by the hypervisor with NAT. + +.. code-block:: none + + $ virt-install -n vyos_r1 \ + --ram 4096 \ + --vcpus 2 \ + --cdrom /var/lib/libvirt/images/vyos.iso \ + --os-type linux \ + --os-variant debian10 \ + --network network=default \ + --graphics vnc \ + --hvm \ + --virt-type kvm \ + --disk path=/var/lib/libvirt/images/vyos_r1.qcow2,bus=virtio,size=8 \ + --noautoconsole + +Connect to VM with command ``virsh console vyos_r1`` + +.. code-block:: none + + $ virsh console vyos_r1 + + Connected to domain vyos_r1 + Escape character is ^] + + vyos login: vyos + Password: + + vyos@vyos:~$ install image + +After installation - exit from the console using the key combination ``Ctrl + ]`` and reboot the system. + +Deploy from qcow2 +----------------- +The convenience of using :abbr:`KVM (Kernel-based Virtual Machine)` images is that they don't need to be installed. +Download predefined VyOS.qcow2 image for ``KVM`` + +.. code-block:: none + + curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 + +Create VM with ``import`` qcow2 disk option. + +.. code-block:: none + + $ virt-install -n vyos_r2 \ + --ram 4096 \ + --vcpus 2 \ + --os-type linux \ + --os-variant debian10 \ + --network network=default \ + --graphics vnc \ + --hvm \ + --virt-type kvm \ + --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \ + --import \ + --noautoconsole + +Connect to VM with command ``virsh console vyos_r2`` + +.. code-block:: none + + $ virsh console vyos_r2 + + Connected to domain vyos_r2 + Escape character is ^] + + vyos login: vyos + Password: + + vyos@vyos:~$ + +The system is fully operational. + +Virt-manager +============ +The virt-manager application is a desktop user interface for managing virtual machines through libvirt. +On the linux open :abbr:`VMM (Virtual Machine Manager)`. + +Deploy from ISO +--------------- + +1. Open :abbr:`VMM (Virtual Machine Manager)` and Create a new :abbr:`VM (Virtual Machine)` + +2. Choose ``Local install media`` (ISO) + +.. figure:: /_static/images/virt-libvirt-01.png + +3. Choose path to iso vyos.iso. Operating System can be any Debian based. + +.. figure:: /_static/images/virt-libvirt-02.png + +4. Choose Memory and CPU + +.. figure:: /_static/images/virt-libvirt-03.png + +5. Disk size + +.. figure:: /_static/images/virt-libvirt-04.png + +6. Name of VM and network selection + +.. figure:: /_static/images/virt-libvirt-05.png + +7. Then you will be taken to the console. + +.. figure:: /_static/images/virt-libvirt-06.png + +Deploy from qcow2 +----------------- + +Download predefined VyOS.qcow2 image for ``KVM`` + +.. code-block:: none + + curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 + + +1. Open :abbr:`VMM (Virtual Machine Manager)` and Create a new :abbr:`VM (Virtual Machine)` + +2. Choose ``Import existing disk`` image + +.. figure:: /_static/images/virt-libvirt-qc-01.png + +3. Choose the path to the image ``vyos_kvm.qcow2`` that was previously downloaded . Operation System can be any Debian based. + +.. figure:: /_static/images/virt-libvirt-qc-02.png + +4. Choose Memory and CPU + +.. figure:: /_static/images/virt-libvirt-03.png + +5. Name of VM and network selection + +.. figure:: /_static/images/virt-libvirt-05.png + +6. Then you will be taken to the console. + +.. figure:: /_static/images/virt-libvirt-qc-03.png + + + diff --git a/docs/appendix/virtual/vyos-on-gns3.rst b/docs/appendix/virtual/vyos-on-gns3.rst new file mode 100644 index 00000000..93ea9ae2 --- /dev/null +++ b/docs/appendix/virtual/vyos-on-gns3.rst @@ -0,0 +1,176 @@ +.. _vyos-on-gns3: + +############### +Running on GNS3 +############### + +Sometimes you may want to test VyOS in a lab environment. +`GNS3 `__ is a network emulation software you +might use for it. + +This guide will provide the necessary steps for installing +and setting up VyOS on GNS3. + +Requirements +------------ + +The following items are required: + +* A VyOS installation image (.iso file). + `Here `__ you + can find how to get it. + +* A working GNS3 installation. For further information see the + `GNS3 documentation `__. + +.. _vm_setup: + +VM setup +-------- + +First, a virtual machine (VM) for the VyOS installation must be created +in GNS3. + +Go to the GNS3 **File** menu, click **New template** and choose select +**Manually create a new Template**. + +.. figure:: /_static/images/gns3-01.png + +Select **Quemu VMs** and then click on the ``New`` button. + +.. figure:: /_static/images/gns3-02.png + +Write a name for your VM, for instance "VyOS", and click ``Next``. + +.. figure:: /_static/images/gns3-03.png + +Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM +and click ``Next``. + +.. figure:: /_static/images/gns3-04.png + +Select **telnet** as your console type and click ``Next``. + +.. figure:: /_static/images/gns3-05.png + +Select **New image** for the base disk image of your VM and click +``Create``. + +.. figure:: /_static/images/gns3-06.png + +Use the defaults in the **Binary and format** window and click +``Next``. + +.. figure:: /_static/images/gns3-07.png + +Use the defaults in the **Qcow2 options** window and click ``Next``. + +.. figure:: /_static/images/gns3-08.png + +Set the disk size to 2000 MiB, and click ``Finish`` to end the **Quemu +image creator**. + +.. figure:: /_static/images/gns3-09.png + +Click ``Finish`` to end the **New QEMU VM template** wizard. + +.. figure:: /_static/images/gns3-10.png + +Now the VM settings have to be edited. + +Being again at the **Preferences** window, having **Qemu VMs** +selected and having our new VM selected, click the ``Edit`` button. + +.. figure:: /_static/images/gns3-11.png + +In the **General settings** tab of your **QEMU VM template +configuration**, do the following: + +* Click on the ``Browse...`` button to choose the **Symbol** you want to + have representing your VM. +* In **Category** select in which group you want to find your VM. +* Set the **Boot priority** to **CD/DVD-ROM**. + +.. figure:: /_static/images/gns3-12.png + +At the **HDD** tab, change the Disk interface to **sata** to speed up +the boot process. + +.. figure:: /_static/images/gns3-13.png + +At the **CD/DVD** tab click on ``Browse...`` and locate the VyOS image +you want to install. + +.. figure:: /_static/images/gns3-14.png + +.. note:: You probably will want to accept to copy the .iso file to your + default image directory when you are asked. + +In the **Network** tab, set **0** as the number of adapters, set the +**Name format** to **eth{0}** and the **Type** to **Paravirtualized +Network I/O (virtio-net-pci)**. + +.. figure:: /_static/images/gns3-15.png + +In the **Advanced** tab, unmark the checkbox **Use as a linked base +VM** and click ``OK``, which will save and close the **QEMU VM template +configuration** window. + +.. figure:: /_static/images/gns3-16.png + +At the general **Preferences** window, click ``OK`` to save and close. + +.. figure:: /_static/images/gns3-17.png + + +.. _vyos_installation: + +VyOS installation +----------------- + +* Create a new project. +* Drag the newly created VyOS VM into it. +* Start the VM. +* Open a console. + The console should show the system booting. It will ask for the login + credentials, you are at the VyOS live system. +* `Install VyOS `__ + as normal (that is, using the ``install image`` command). + +* After a successful installation, shutdown the VM with the ``poweroff`` + command. + +* **Delete the VM** from the GNS3 project. + +The *VyOS-hda.qcow2* file now contains a working VyOS image and can be +used as a template. But it still needs some fixes before we can deploy +VyOS in our labs. + +.. _vyos_vm_configuration: + +VyOS VM configuration +--------------------- + +To turn the template into a working VyOS machine, further steps are +necessary as outlined below: + +**General settings** tab: Set the boot priority to **HDD** + +.. figure:: /_static/images/gns3-20.png + +**CD/DVD** tab: Unmount the installation image file by clearing the +**Image** entry field. + +.. figure:: /_static/images/gns3-21.png + +Set the number of required network adapters, for example **4**. + +.. figure:: /_static/images/gns3-215.png + +**Advanced** settings tab: Mark the checkbox **Use as a linked +base VM** and click ``OK`` to save the changes. + +.. figure:: /_static/images/gns3-22.png + +The VyOS VM is now ready to be deployed. + diff --git a/docs/appendix/virtual/vyos-on-vmware.rst b/docs/appendix/virtual/vyos-on-vmware.rst new file mode 100644 index 00000000..c4299cbf --- /dev/null +++ b/docs/appendix/virtual/vyos-on-vmware.rst @@ -0,0 +1,32 @@ +.. _vyosonvmware: + +Running on VMware ESXi +###################### + +ESXi 5.5 or later +***************** + +.ova files are available for supporting users, and a VyOS can also be stood up using a generic Linux instance, and attaching the bootable ISO file and installing from the ISO +using the normal process around `install image`. + +.. NOTE:: There have been previous documented issues with GRE/IPSEC tunneling using the E1000 adapter on the VyOS guest, and use of the VMXNET3 has been advised. + +Memory Contention Considerations +-------------------------------- +When the underlying ESXi host is approaching ~92% memory utilisation it will start the balloon process in s a 'soft' state to start reclaiming memory from guest operating systems. +This causes an artificial pressure using the vmmemctl driver on memory usage on the virtual guest. As VyOS by default does not have a swap file, this vmmemctl pressure is unable to +force processes to move in memory data to the paging file, and blindly consumes memory forcing the virtual guest into a low memory state with no way to escape. The balloon can expand to 65% of +guest allocated memory, so a VyOS guest running >35% of memory usage, can encounter an out of memory situation, and trigger the kernel oom_kill process. At this point a weighted +lottery favouring memory hungry processes will be run with the unlucky winner being terminated by the kernel. + +It is advised that VyOS routers are configured in a resource group with adequate memory reservations so that ballooning is not inflicted on virtual VyOS guests. + + + + + +References +---------- + +https://muralidba.blogspot.com/2018/03/how-does-linux-out-of-memory-oom-killer.html + diff --git a/docs/appendix/vyos-on-gns3.rst b/docs/appendix/vyos-on-gns3.rst deleted file mode 100644 index f17715b2..00000000 --- a/docs/appendix/vyos-on-gns3.rst +++ /dev/null @@ -1,175 +0,0 @@ -.. _vyos-on-gns3: - -VyOS on GNS3 -############ - -Sometimes you may want to test VyOS in a lab environment. -`GNS3 `__ is a network emulation software you -might use for it. - -This guide will provide the necessary steps for installing -and setting up VyOS on GNS3. - -Requirements ------------- - -The following items are required: - -* A VyOS installation image (.iso file). - `Here `__ you - can find how to get it. - -* A working GNS3 installation. For further information see the - `GNS3 documentation `__. - -.. _vm_setup: - -VM setup --------- - -First, a virtual machine (VM) for the VyOS installation must be created -in GNS3. - -Go to the GNS3 **File** menu, click **New template** and choose select -**Manually create a new Template**. - -.. figure:: /_static/images/gns3-01.png - -Select **Quemu VMs** and then click on the ``New`` button. - -.. figure:: /_static/images/gns3-02.png - -Write a name for your VM, for instance "VyOS", and click ``Next``. - -.. figure:: /_static/images/gns3-03.png - -Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM -and click ``Next``. - -.. figure:: /_static/images/gns3-04.png - -Select **telnet** as your console type and click ``Next``. - -.. figure:: /_static/images/gns3-05.png - -Select **New image** for the base disk image of your VM and click -``Create``. - -.. figure:: /_static/images/gns3-06.png - -Use the defaults in the **Binary and format** window and click -``Next``. - -.. figure:: /_static/images/gns3-07.png - -Use the defaults in the **Qcow2 options** window and click ``Next``. - -.. figure:: /_static/images/gns3-08.png - -Set the disk size to 2000 MiB, and click ``Finish`` to end the **Quemu -image creator**. - -.. figure:: /_static/images/gns3-09.png - -Click ``Finish`` to end the **New QEMU VM template** wizard. - -.. figure:: /_static/images/gns3-10.png - -Now the VM settings have to be edited. - -Being again at the **Preferences** window, having **Qemu VMs** -selected and having our new VM selected, click the ``Edit`` button. - -.. figure:: /_static/images/gns3-11.png - -In the **General settings** tab of your **QEMU VM template -configuration**, do the following: - -* Click on the ``Browse...`` button to choose the **Symbol** you want to - have representing your VM. -* In **Category** select in which group you want to find your VM. -* Set the **Boot priority** to **CD/DVD-ROM**. - -.. figure:: /_static/images/gns3-12.png - -At the **HDD** tab, change the Disk interface to **sata** to speed up -the boot process. - -.. figure:: /_static/images/gns3-13.png - -At the **CD/DVD** tab click on ``Browse...`` and locate the VyOS image -you want to install. - -.. figure:: /_static/images/gns3-14.png - -.. note:: You probably will want to accept to copy the .iso file to your - default image directory when you are asked. - -In the **Network** tab, set **0** as the number of adapters, set the -**Name format** to **eth{0}** and the **Type** to **Paravirtualized -Network I/O (virtio-net-pci)**. - -.. figure:: /_static/images/gns3-15.png - -In the **Advanced** tab, unmark the checkbox **Use as a linked base -VM** and click ``OK``, which will save and close the **QEMU VM template -configuration** window. - -.. figure:: /_static/images/gns3-16.png - -At the general **Preferences** window, click ``OK`` to save and close. - -.. figure:: /_static/images/gns3-17.png - - -.. _vyos_installation: - -VyOS installation ------------------ - -* Create a new project. -* Drag the newly created VyOS VM into it. -* Start the VM. -* Open a console. - The console should show the system booting. It will ask for the login - credentials, you are at the VyOS live system. -* `Install VyOS `__ - as normal (that is, using the ``install image`` command). - -* After a successful installation, shutdown the VM with the ``poweroff`` - command. - -* **Delete the VM** from the GNS3 project. - -The *VyOS-hda.qcow2* file now contains a working VyOS image and can be -used as a template. But it still needs some fixes before we can deploy -VyOS in our labs. - -.. _vyos_vm_configuration: - -VyOS VM configuration ---------------------- - -To turn the template into a working VyOS machine, further steps are -necessary as outlined below: - -**General settings** tab: Set the boot priority to **HDD** - -.. figure:: /_static/images/gns3-20.png - -**CD/DVD** tab: Unmount the installation image file by clearing the -**Image** entry field. - -.. figure:: /_static/images/gns3-21.png - -Set the number of required network adapters, for example **4**. - -.. figure:: /_static/images/gns3-215.png - -**Advanced** settings tab: Mark the checkbox **Use as a linked -base VM** and click ``OK`` to save the changes. - -.. figure:: /_static/images/gns3-22.png - -The VyOS VM is now ready to be deployed. - diff --git a/docs/appendix/vyos-on-virtual-environments.rst b/docs/appendix/vyos-on-virtual-environments.rst deleted file mode 100644 index eed82390..00000000 --- a/docs/appendix/vyos-on-virtual-environments.rst +++ /dev/null @@ -1,172 +0,0 @@ -.. _vyos-on-virtual-environments: - -############################### -Running in Virtual Environments -############################### - -**************** -Libvirt Qemu/KVM -**************** - -Libvirt is an open-source API, daemon and management tool for managing platform virtualization. -There are several ways to deploy VyOS on libvirt kvm. Use Virt-manager and native CLI. -In an example we will be use use 4 gigabytes of memory, 2 cores CPU and default network virbr0. - -CLI -=== - -Deploy from ISO ---------------- - -Create VM name ``vyos_r1``. You must specify the path to the ``ISO`` image, the disk ``qcow2`` will be created automatically. -The ``default`` network is the virtual network (type Virtio) created by the hypervisor with NAT. - -.. code-block:: none - - $ virt-install -n vyos_r1 \ - --ram 4096 \ - --vcpus 2 \ - --cdrom /var/lib/libvirt/images/vyos.iso \ - --os-type linux \ - --os-variant debian10 \ - --network network=default \ - --graphics vnc \ - --hvm \ - --virt-type kvm \ - --disk path=/var/lib/libvirt/images/vyos_r1.qcow2,bus=virtio,size=8 \ - --noautoconsole - -Connect to VM with command ``virsh console vyos_r1`` - -.. code-block:: none - - $ virsh console vyos_r1 - - Connected to domain vyos_r1 - Escape character is ^] - - vyos login: vyos - Password: - - vyos@vyos:~$ install image - -After installation - exit from the console using the key combination ``Ctrl + ]`` and reboot the system. - -Deploy from qcow2 ------------------ -The convenience of using :abbr:`KVM (Kernel-based Virtual Machine)` images is that they don't need to be installed. -Download predefined VyOS.qcow2 image for ``KVM`` - -.. code-block:: none - - curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 - -Create VM with ``import`` qcow2 disk option. - -.. code-block:: none - - $ virt-install -n vyos_r2 \ - --ram 4096 \ - --vcpus 2 \ - --os-type linux \ - --os-variant debian10 \ - --network network=default \ - --graphics vnc \ - --hvm \ - --virt-type kvm \ - --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \ - --import \ - --noautoconsole - -Connect to VM with command ``virsh console vyos_r2`` - -.. code-block:: none - - $ virsh console vyos_r2 - - Connected to domain vyos_r2 - Escape character is ^] - - vyos login: vyos - Password: - - vyos@vyos:~$ - -The system is fully operational. - -Virt-manager -============ -The virt-manager application is a desktop user interface for managing virtual machines through libvirt. -On the linux open :abbr:`VMM (Virtual Machine Manager)`. - -Deploy from ISO ---------------- - -1. Open :abbr:`VMM (Virtual Machine Manager)` and Create a new :abbr:`VM (Virtual Machine)` - -2. Choose ``Local install media`` (ISO) - -.. figure:: /_static/images/virt-libvirt-01.png - -3. Choose path to iso vyos.iso. Operating System can be any Debian based. - -.. figure:: /_static/images/virt-libvirt-02.png - -4. Choose Memory and CPU - -.. figure:: /_static/images/virt-libvirt-03.png - -5. Disk size - -.. figure:: /_static/images/virt-libvirt-04.png - -6. Name of VM and network selection - -.. figure:: /_static/images/virt-libvirt-05.png - -7. Then you will be taken to the console. - -.. figure:: /_static/images/virt-libvirt-06.png - -Deploy from qcow2 ------------------ - -Download predefined VyOS.qcow2 image for ``KVM`` - -.. code-block:: none - - curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 - - -1. Open :abbr:`VMM (Virtual Machine Manager)` and Create a new :abbr:`VM (Virtual Machine)` - -2. Choose ``Import existing disk`` image - -.. figure:: /_static/images/virt-libvirt-qc-01.png - -3. Choose the path to the image ``vyos_kvm.qcow2`` that was previously downloaded . Operation System can be any Debian based. - -.. figure:: /_static/images/virt-libvirt-qc-02.png - -4. Choose Memory and CPU - -.. figure:: /_static/images/virt-libvirt-03.png - -5. Name of VM and network selection - -.. figure:: /_static/images/virt-libvirt-05.png - -6. Then you will be taken to the console. - -.. figure:: /_static/images/virt-libvirt-qc-03.png - - -******* -Proxmox -******* - -References -========== - -https://www.proxmox.com/en/proxmox-ve - diff --git a/docs/appendix/vyos-on-vmware.rst b/docs/appendix/vyos-on-vmware.rst deleted file mode 100644 index c4299cbf..00000000 --- a/docs/appendix/vyos-on-vmware.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. _vyosonvmware: - -Running on VMware ESXi -###################### - -ESXi 5.5 or later -***************** - -.ova files are available for supporting users, and a VyOS can also be stood up using a generic Linux instance, and attaching the bootable ISO file and installing from the ISO -using the normal process around `install image`. - -.. NOTE:: There have been previous documented issues with GRE/IPSEC tunneling using the E1000 adapter on the VyOS guest, and use of the VMXNET3 has been advised. - -Memory Contention Considerations --------------------------------- -When the underlying ESXi host is approaching ~92% memory utilisation it will start the balloon process in s a 'soft' state to start reclaiming memory from guest operating systems. -This causes an artificial pressure using the vmmemctl driver on memory usage on the virtual guest. As VyOS by default does not have a swap file, this vmmemctl pressure is unable to -force processes to move in memory data to the paging file, and blindly consumes memory forcing the virtual guest into a low memory state with no way to escape. The balloon can expand to 65% of -guest allocated memory, so a VyOS guest running >35% of memory usage, can encounter an out of memory situation, and trigger the kernel oom_kill process. At this point a weighted -lottery favouring memory hungry processes will be run with the unlucky winner being terminated by the kernel. - -It is advised that VyOS routers are configured in a resource group with adequate memory reservations so that ballooning is not inflicted on virtual VyOS guests. - - - - - -References ----------- - -https://muralidba.blogspot.com/2018/03/how-does-linux-out-of-memory-oom-killer.html - diff --git a/docs/index.rst b/docs/index.rst index bab4f930..ab9d3f66 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -65,14 +65,12 @@ VyOS User Guide appendix/release-notes appendix/examples/index - appendix/vyos-on-vmware appendix/vyos-on-baremetal + appendix/virtual/index appendix/vyos-on-clouds - appendix/vyos-on-virtual-environments appendix/migrate-from-vyatta appendix/command-scripting appendix/http-api - appendix/vyos-on-gns3 .. toctree:: diff --git a/docs/information.rst b/docs/information.rst index 5565163e..02d6f1ec 100644 --- a/docs/information.rst +++ b/docs/information.rst @@ -5,7 +5,7 @@ Information *********** VyOS features a rich set of operational level commands to retrieve arbitrary -infomration about your running system. +information about your running system. ######## Hardware -- cgit v1.2.3 From ca432e2ec6bf8c33c652aee9bc7bc0e2b4a4bd6a Mon Sep 17 00:00:00 2001 From: root Date: Thu, 27 Aug 2020 13:37:11 -0500 Subject: T2810: Docs for vpn anyconnect-server This documentation describes how to configure OpenConnect-Server on VyOS --- docs/vpn/anyconnect.rst | 73 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/vpn/index.rst | 1 + 2 files changed, 74 insertions(+) create mode 100644 docs/vpn/anyconnect.rst (limited to 'docs') diff --git a/docs/vpn/anyconnect.rst b/docs/vpn/anyconnect.rst new file mode 100644 index 00000000..64c3e49f --- /dev/null +++ b/docs/vpn/anyconnect.rst @@ -0,0 +1,73 @@ +.. _vpn-openconnect: + +OpenConnect +----- + +OpenConnect-compatible server feature is available from this release. +Openconnect VPN supports SSL connection and offers full network access. SSL VPN network extension connects the end-user system to the corporate network with access controls based only on network layer information, such as destination IP address and port number. So, it provides safe communication for all types of device traffic across public networks and private networks, also encrypts the traffic with SSL protocol. +The remote user will use the openconnect client to connect to the router and will receive an IP address from a VPN pool, allowing full access to the network. + +.. note:: All certificates should be stored on VyOS under /config/auth. If certificates are not stored in the /config directory they will not be migrated during a software update. + + +Configuration +^^^^^^^^^^ + +SSL Certificates +---- + +We need to generate the certificate which authenticates users who attempt to access the network resource through the SSL VPN tunnels. +The following command will create a self signed certificates and will be stored in the file path /config/auth + +.. code-block:: none + + openssl req -newkey rsa:4096 -new -nodes -x509 -days 3650 -keyout /config/auth/server.key -out /config/auth/server.crt + openssl req -new -x509 -key /config/auth/server.key -out /config/auth/ca.crt + +We can also create the certificates using Cerbort which is an easy-to-use client that fetches a certificate from Let’s Encrypt — an open certificate authority launched by the EFF, Mozilla, and others—and deploys it to a web server. + +.. code-block:: none + + sudo certbot certonly --standalone --preferred-challenges http -d + +Server Configuration +------------------------- + +.. code-block:: none + + set vpn openconnect authentication local-users username password + set vpn openconnect authentication mode + set vpn opneconnect network-settings client-ip-settings subnet + set vpn openconnect network-settings name-server
+ set vpn openconnect network-settings name-server
+ set vpn openconnect ssl ca-cert-file + set vpn openconnect ssl cert-file + set vpn openconnect ssl key-file + +Example +---- + +Use local user name "user4" with password "SecretPassword" +Client IP addresses will be provided from pool 100.64.0.0/24 +The Gateway IP Address must be in one of the router´s interfaces. + +.. code-block:: none + + set vpn openconnect authentication local-users username user4 password 'SecretPassword' + set vpn openconnect authentication mode 'local' + set vpn openconnect network-settings client-ip-settings subnet '100.64.0.0/24' + set vpn openconnect network-settings name-server '1.1.1.1' + set vpn openconnect network-settings name-server '8.8.8.8' + set vpn openconnect ssl ca-cert-file '/config/auth/fullchain.pem' + set vpn openconnect ssl cert-file '/config/auth/cert.pem' + set vpn openconnect ssl key-file '/config/auth/privkey.pem' + +Verification +---- + +.. code-block:: none + + vyos@RTR1:~$ show openconnect-server sessions + interface username ip remote IP RX TX state uptime + ----------- ---------- ------------ ------------- -------- -------- --------- -------- + sslvpn0 user4 100.64.0.105 xx.xxx.49.253 127.3 KB 160.0 KB connected 12m:28s diff --git a/docs/vpn/index.rst b/docs/vpn/index.rst index 42a90a3f..aea1ada2 100644 --- a/docs/vpn/index.rst +++ b/docs/vpn/index.rst @@ -15,3 +15,4 @@ VPN site2site_ipsec sstp wireguard + anyconnect -- cgit v1.2.3 From 82bcd24b34b6f0d5365d096d092cad84da480314 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 13 Sep 2020 15:57:32 +0200 Subject: install: fix WARNING: Title level inconsistent --- docs/install.rst | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) (limited to 'docs') diff --git a/docs/install.rst b/docs/install.rst index 3e31449f..a210c1ad 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -190,7 +190,7 @@ it in your hard drive. **With your downloaded VyOS .iso file you can create a bootable USB drive that will let you boot into a fully functional VyOS system**. Once you have tested it, you can either decide to begin a :ref:`permanent_installation` in your hard drive or power -your system off, remove the USB drive, and leave everythng as it was. +your system off, remove the USB drive, and leave everythng as it was. If you have a GNU+Linux system, you can create your VyOS bootable USB @@ -206,8 +206,8 @@ stick with with the ``dd`` command: all partitions. .. code-block:: none - - $ umount /dev/sdX* + + $ umount /dev/sdX* 4. Write the image (your VyOS .iso file) to the USB drive. Note that here you want to use the device name (e.g. /dev/sdb), not @@ -216,7 +216,7 @@ stick with with the ``dd`` command: **Warning**: This will destroy all data on the USB drive! .. code-block:: none - + # dd if=/path/to/vyos.iso of=/dev/sdX bs=8M; sync 5. Wait until you get the outcome (bytes copied). Be patient, in some @@ -286,19 +286,19 @@ In order to proceed with a permanent installation: Would you like me to try to partition a drive automatically or would you rather partition it manually with parted? If you have already setup your partitions, you may skip this step - + Partition (Auto/Parted/Skip) [Auto]: - + I found the following drives on your system: sda 4294MB - + Install the image on? [sda]: - + This will destroy all data on /dev/sda. Continue? (Yes/No) [No]: Yes - + How big of a root partition should I create? (2000MB - 4294MB) [4294]MB: - + Creating filesystem on /dev/sda1: OK Done! Mounting /dev/sda1... @@ -310,7 +310,7 @@ In order to proceed with a permanent installation: I found the following configuration files: /opt/vyatta/etc/config.boot.default Which one should I copy to sda? [/opt/vyatta/etc/config.boot.default]: - + Copying /opt/vyatta/etc/config.boot.default to sda. Enter password for administrator account Enter password for user 'vyos': @@ -318,9 +318,9 @@ In order to proceed with a permanent installation: I need to install the GRUB boot loader. I found the following drives on your system: sda 4294MB - + Which drive should GRUB modify the boot partition on? [sda]: - + Setting up grub: OK Done! @@ -484,17 +484,17 @@ Known Issues This is a list of known issues that can arise during installation. Black screen on install -^^^^^^^^^^^^^^^^^^^^^^^ +----------------------- GRUB attempts to redirect all output to a serial port for ease of installation on headless hosts. -This appears to cause an hard lockup on some hardware that lacks a serial port, with the result being a +This appears to cause an hard lockup on some hardware that lacks a serial port, with the result being a black screen after selecting the `Live system` option from the installation image. The workaround is to type `e` when the boot menu appears and edit the GRUB boot options. Specifically, remove the: -`console=ttyS0,115200` +`console=ttyS0,115200` -option, and type CTRL-X to boot. +option, and type CTRL-X to boot. Installation can then continue as outlined above. -- cgit v1.2.3 From 7334b4b9baec121569ad0e3015994fa1e10f167c Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 13 Sep 2020 15:58:10 +0200 Subject: vpn: openconnect: fix TOC --- docs/vpn/anyconnect.rst | 78 ------------------------------------------------ docs/vpn/index.rst | 2 +- docs/vpn/openconnect.rst | 45 ++++++++++++++++++---------- 3 files changed, 31 insertions(+), 94 deletions(-) delete mode 100644 docs/vpn/anyconnect.rst (limited to 'docs') diff --git a/docs/vpn/anyconnect.rst b/docs/vpn/anyconnect.rst deleted file mode 100644 index e8945fbb..00000000 --- a/docs/vpn/anyconnect.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. _vpn-openconnect: - -OpenConnect ------ - -OpenConnect-compatible server feature is available from this release. -Openconnect VPN supports SSL connection and offers full network access. SSL VPN network extension connects the end-user system to the corporate network with access controls based only on network layer information, such as destination IP address and port number. So, it provides safe communication for all types of device traffic across public networks and private networks, also encrypts the traffic with SSL protocol. -The remote user will use the openconnect client to connect to the router and will receive an IP address from a VPN pool, allowing full access to the network. - - -.. note:: All certificates should be stored on VyOS under /config/auth. If certificates are not stored in the /config directory they will not be migrated during a software update. - - -Configuration -^^^^^^^^^^ - -SSL Certificates ----- - -We need to generate the certificate which authenticates users who attempt to access the network resource through the SSL VPN tunnels. -The following command will create a self signed certificates and will be stored in the file path /config/auth - -.. code-block:: none - - openssl req -newkey rsa:4096 -new -nodes -x509 -days 3650 -keyout /config/auth/server.key -out /config/auth/server.crt - openssl req -new -x509 -key /config/auth/server.key -out /config/auth/ca.crt - -We can also create the certificates using Cerbort which is an easy-to-use client that fetches a certificate from Let’s Encrypt — an open certificate authority launched by the EFF, Mozilla, and others—and deploys it to a web server. - -.. code-block:: none - - sudo certbot certonly --standalone --preferred-challenges http -d - -Server Configuration -------------------------- - -.. code-block:: none - - set vpn openconnect authentication local-users username password - set vpn openconnect authentication mode - set vpn opneconnect network-settings client-ip-settings subnet - set vpn openconnect network-settings name-server
- set vpn openconnect network-settings name-server
- set vpn openconnect ssl ca-cert-file - set vpn openconnect ssl cert-file - set vpn openconnect ssl key-file - - -Example ----- - -Use local user name "user4" with password "SecretPassword" -Client IP addresses will be provided from pool 100.64.0.0/24 -The Gateway IP Address must be in one of the router´s interfaces. - -.. code-block:: none - - set vpn openconnect authentication local-users username user4 password 'SecretPassword' - set vpn openconnect authentication mode 'local' - set vpn openconnect network-settings client-ip-settings subnet '100.64.0.0/24' - set vpn openconnect network-settings name-server '1.1.1.1' - set vpn openconnect network-settings name-server '8.8.8.8' - set vpn openconnect ssl ca-cert-file '/config/auth/fullchain.pem' - set vpn openconnect ssl cert-file '/config/auth/cert.pem' - set vpn openconnect ssl key-file '/config/auth/privkey.pem' - - -Verification ----- - -.. code-block:: none - - - vyos@RTR1:~$ show openconnect-server sessions - - interface username ip remote IP RX TX state uptime - ----------- ---------- ------------ ------------- -------- -------- --------- -------- - sslvpn0 user4 100.64.0.105 xx.xxx.49.253 127.3 KB 160.0 KB connected 12m:28s diff --git a/docs/vpn/index.rst b/docs/vpn/index.rst index 4441c003..9ba31ae6 100644 --- a/docs/vpn/index.rst +++ b/docs/vpn/index.rst @@ -15,4 +15,4 @@ VPN site2site_ipsec sstp wireguard - OpenConnect + openconnect diff --git a/docs/vpn/openconnect.rst b/docs/vpn/openconnect.rst index 9d6dd6da..a409ed9d 100644 --- a/docs/vpn/openconnect.rst +++ b/docs/vpn/openconnect.rst @@ -1,38 +1,51 @@ .. _vpn-openconnect: +########### OpenConnect ------ +########### OpenConnect-compatible server feature is available from this release. -Openconnect VPN supports SSL connection and offers full network access. SSL VPN network extension connects the end-user system to the corporate network with access controls based only on network layer information, such as destination IP address and port number. So, it provides safe communication for all types of device traffic across public networks and private networks, also encrypts the traffic with SSL protocol. -The remote user will use the openconnect client to connect to the router and will receive an IP address from a VPN pool, allowing full access to the network. +Openconnect VPN supports SSL connection and offers full network access. SSL VPN +network extension connects the end-user system to the corporate network with +access controls based only on network layer information, such as destination IP +address and port number. So, it provides safe communication for all types of +device traffic across public networks and private networks, also encrypts the +traffic with SSL protocol. +The remote user will use the openconnect client to connect to the router and +will receive an IP address from a VPN pool, allowing full access to the network. -.. note:: All certificates should be stored on VyOS under /config/auth. If certificates are not stored in the /config directory they will not be migrated during a software update. - +.. note:: All certificates should be stored on VyOS under /config/auth. If + certificates are not stored in the /config directory they will not be + migrated during a software update. +************* Configuration -^^^^^^^^^^ +************* SSL Certificates ----- +================ -We need to generate the certificate which authenticates users who attempt to access the network resource through the SSL VPN tunnels. -The following command will create a self signed certificates and will be stored in the file path /config/auth +We need to generate the certificate which authenticates users who attempt to +access the network resource through the SSL VPN tunnels. The following command +will create a self signed certificates and will be stored in the file path +`/config/auth`. .. code-block:: none openssl req -newkey rsa:4096 -new -nodes -x509 -days 3650 -keyout /config/auth/server.key -out /config/auth/server.crt openssl req -new -x509 -key /config/auth/server.key -out /config/auth/ca.crt -We can also create the certificates using Cerbort which is an easy-to-use client that fetches a certificate from Let’s Encrypt — an open certificate authority launched by the EFF, Mozilla, and others—and deploys it to a web server. +We can also create the certificates using Cerbort which is an easy-to-use client +that fetches a certificate from Let's Encrypt an open certificate authority +launched by the EFF, Mozilla, and others and deploys it to a web server. .. code-block:: none sudo certbot certonly --standalone --preferred-challenges http -d Server Configuration -------------------------- +==================== .. code-block:: none @@ -46,8 +59,9 @@ Server Configuration set vpn openconnect ssl key-file +******* Example ----- +******* Use local user name "user4" with password "SecretPassword" Client IP addresses will be provided from pool 100.64.0.0/24 @@ -57,7 +71,7 @@ The Gateway IP Address must be in one of the router´s interfaces. set vpn openconnect authentication local-users username user4 password 'SecretPassword' set vpn openconnect authentication mode 'local' - set vpn openconnect network-settings client-ip-settings subnet '100.64.0.0/24' + set vpn openconnect network-settings client-ip-settings subnet '100.64.0.0/24' set vpn openconnect network-settings name-server '1.1.1.1' set vpn openconnect network-settings name-server '8.8.8.8' set vpn openconnect ssl ca-cert-file '/config/auth/fullchain.pem' @@ -65,13 +79,14 @@ The Gateway IP Address must be in one of the router´s interfaces. set vpn openconnect ssl key-file '/config/auth/privkey.pem' +************ Verification ----- +************ .. code-block:: none - vyos@RTR1:~$ show openconnect-server sessions + vyos@RTR1:~$ show openconnect-server sessions interface username ip remote IP RX TX state uptime ----------- ---------- ------------ ------------- -------- -------- --------- -------- -- cgit v1.2.3 From 9982cb495567e107c00c44a3dcc134592997bb1e Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 13 Sep 2020 16:03:16 +0200 Subject: ssh: fix invalid keyword 'cmfcmd' --- docs/services/ssh.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/services/ssh.rst b/docs/services/ssh.rst index c5959e5c..6da8560f 100644 --- a/docs/services/ssh.rst +++ b/docs/services/ssh.rst @@ -99,7 +99,7 @@ Supported algorithms: ``diffie-hellman-group1-sha1``, Set the ``sshd`` log level. The default is ``info``. -.. cmfcmd:: set service ssh vrf +.. cfgcmd:: set service ssh vrf Specify name of the :abbr:`VRF (Virtual Routing and Forwarding)` instance. -- cgit v1.2.3 From 5e86c158b7b7c0d628423405b26aacb6238fba5b Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 13 Sep 2020 16:03:40 +0200 Subject: bonding: add new command for minimum-links --- docs/interfaces/bond.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'docs') diff --git a/docs/interfaces/bond.rst b/docs/interfaces/bond.rst index 74089f96..d697e5d4 100644 --- a/docs/interfaces/bond.rst +++ b/docs/interfaces/bond.rst @@ -159,6 +159,25 @@ Link Administration This mode provides load balancing and fault tolerance. +.. cfgcmd:: set interfaces bonding min-links <0-16> + + Specifies the minimum number of links that must be active before asserting + carrier. It is similar to the Cisco EtherChannel min-links feature. This + allows setting the minimum number of member ports that must be up (link-up + state) before marking the bond device as up (carrier on). This is useful for + situations where higher level services such as clustering want to ensure a + minimum number of low bandwidth links are active before switchover. + + This option only affects 802.3ad mode. + + The default value is 0. This will cause carrier to be asserted (for 802.3ad + mode) whenever there is an active aggregator, regardless of the number of + available links in that aggregator. + + .. note:: Because an aggregator cannot be active without at least one + available link, setting this option to 0 or to 1 has the exact same + effect. + .. cfgcmd:: set interfaces bonding hash-policy * **layer2** - Uses XOR of hardware MAC addresses and packet type ID field -- cgit v1.2.3 From 1ecb077b5fa68e7c96f05bd7e0c9eb26bdb3e256 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 13 Sep 2020 16:03:59 +0200 Subject: Makefile: livebuild: adjust to latest sphinx source (watch over poll) --- docs/Makefile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/Makefile b/docs/Makefile index 5d4864e1..7bc0c5ab 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -8,9 +8,9 @@ SPHINXPROJ = VyOS SOURCEDIR = . BUILDDIR = _build -AUTOHOST =0.0.0.0 -AUTOPORT =8000 -AUTOOPTS =--poll +AUTOHOST = 0.0.0.0 +AUTOPORT = 8000 +AUTOOPTS = --watch . # Put it first so that "make" without argument is like "make help". help: -- cgit v1.2.3 From 2862a9318f8ca8a6c0bd9a8fb6bfda84e8018912 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 13 Sep 2020 16:08:12 +0200 Subject: bonding: extend operational mode commands --- docs/interfaces/bond.rst | 87 +++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 79 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/interfaces/bond.rst b/docs/interfaces/bond.rst index d697e5d4..396242ae 100644 --- a/docs/interfaces/bond.rst +++ b/docs/interfaces/bond.rst @@ -398,12 +398,83 @@ with two interfaces from VyOS to a Aruba/HP 2510G switch. Operation ######### -.. code-block:: none +.. opcmd:: show interfaces bonding + + Show brief interface information. + + .. code-block:: none + + vyos@vyos:~$ show interfaces bonding + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + bond0 - u/u my-sw1 int 23 and 24 + bond0.10 192.168.0.1/24 u/u office-net + bond0.100 10.10.10.1/24 u/u management-net + + +.. opcmd:: show interfaces bonding + + Show detailed information on given `` + + .. code-block:: none + + vyos@vyos:~$ show interfaces bonding bond5 + bond5: mtu 1500 qdisc noqueue state DOWN group default qlen 1000 + link/ether 00:50:56:bf:ef:aa brd ff:ff:ff:ff:ff:ff + inet6 fe80::e862:26ff:fe72:2dac/64 scope link tentative + 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 + 0 0 0 0 0 0 + +.. opcmd:: show interfaces bonding detail + + Show detailed information about the underlaying physical links on given + bond ``. + + .. code-block:: none + + vyos@vyos:~$ show interfaces bonding bond5 detail + Ethernet Channel Bonding Driver: v3.7.1 (April 27, 2011) + + Bonding Mode: IEEE 802.3ad Dynamic link aggregation + Transmit Hash Policy: layer2 (0) + MII Status: down + MII Polling Interval (ms): 100 + Up Delay (ms): 0 + Down Delay (ms): 0 + + 802.3ad info + LACP rate: slow + Min links: 0 + Aggregator selection policy (ad_select): stable + + Slave Interface: eth1 + MII Status: down + Speed: Unknown + Duplex: Unknown + Link Failure Count: 0 + Permanent HW addr: 00:50:56:bf:ef:aa + Slave queue ID: 0 + Aggregator ID: 1 + Actor Churn State: churned + Partner Churn State: churned + Actor Churned Count: 1 + Partner Churned Count: 1 + + Slave Interface: eth2 + MII Status: down + Speed: Unknown + Duplex: Unknown + Link Failure Count: 0 + Permanent HW addr: 00:50:56:bf:19:26 + Slave queue ID: 0 + Aggregator ID: 2 + Actor Churn State: churned + Partner Churn State: churned + Actor Churned Count: 1 + Partner Churned Count: 1 - vyos@vyos:~$ show interfaces bonding - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - bond0 - u/u my-sw1 int 23 and 24 - bond0.10 192.168.0.1/24 u/u office-net - bond0.100 10.10.10.1/24 u/u management-net -- cgit v1.2.3 From 910fa1ab3ac6a26959f0a2fb4915bf3c0791f720 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Mon, 14 Sep 2020 19:58:20 +0200 Subject: openvpn: fix WARNING: Title level inconsistent --- docs/vpn/openvpn.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/vpn/openvpn.rst b/docs/vpn/openvpn.rst index 159366dc..fd6a3a71 100644 --- a/docs/vpn/openvpn.rst +++ b/docs/vpn/openvpn.rst @@ -255,7 +255,7 @@ internally, so we need to create a route to the 10.23.0.0/20 network ourselves: set protocols static interface-route 10.23.0.0/20 next-hop-interface vtun10 Generate X.509 Certificate and Keys -*********************************** +----------------------------------- OpenVPN ships with a set of scripts called Easy-RSA that can generate the appropriate files needed for an OpenVPN setup using X.509 certificates. @@ -338,10 +338,10 @@ For example, Branch 1's router might have the following files: ca.crt branch1.crt branch1.key Client Authentication ---------------------- +===================== LDAP -**** +---- Enterprise installations usually ship a kind of directory service which is used to have a single password store for all employees. VyOS and OpenVPN support using @@ -380,7 +380,7 @@ The required config file may look like: Active Directory -**************** +^^^^^^^^^^^^^^^^ Despite the fact that AD is a superset of LDAP -- cgit v1.2.3 From a010ef519007dc3a4d7c08144a665134617bade2 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Mon, 14 Sep 2020 21:03:33 +0200 Subject: bonding: add example with Arista EOS --- docs/_static/images/vyos_arista_bond_lacp.png | Bin 0 -> 40622 bytes docs/interfaces/bond.rst | 115 ++++++++++++++++++++++++++ 2 files changed, 115 insertions(+) create mode 100644 docs/_static/images/vyos_arista_bond_lacp.png (limited to 'docs') diff --git a/docs/_static/images/vyos_arista_bond_lacp.png b/docs/_static/images/vyos_arista_bond_lacp.png new file mode 100644 index 00000000..6c9ef8ec Binary files /dev/null and b/docs/_static/images/vyos_arista_bond_lacp.png differ diff --git a/docs/interfaces/bond.rst b/docs/interfaces/bond.rst index 396242ae..9e67809a 100644 --- a/docs/interfaces/bond.rst +++ b/docs/interfaces/bond.rst @@ -395,6 +395,121 @@ with two interfaces from VyOS to a Aruba/HP 2510G switch. vlan 10 tagged Trk1 vlan 100 tagged Trk1 +Arista EOS +^^^^^^^^^^ + +When utilizing VyOS in an environment with Arista gear you can use this blue +print as an initial setup to get an LACP bond / port-channel operational between +those two devices. + +Lets assume the following topology: + +.. figure:: /_static/images/vyos_arista_bond_lacp.png + :alt: VyOS Arista EOS setup + +**R1** + + .. code-block:: none + + interfaces { + bonding bond10 { + hash-policy layer3+4 + member { + interface eth1 + interface eth2 + } + mode 802.3ad + vif 100 { + address 192.0.2.1/30 + address 2001:db8::1/64 + } + } + +**R2** + + .. code-block:: none + + interfaces { + bonding bond10 { + hash-policy layer3+4 + member { + interface eth1 + interface eth2 + } + mode 802.3ad + vif 100 { + address 192.0.2.2/30 + address 2001:db8::2/64 + } + } + +**SW1** + + .. code-block:: none + + ! + vlan 100 + name FOO + ! + interface Port-Channel10 + switchport trunk allowed vlan 100 + switchport mode trunk + spanning-tree portfast + ! + interface Port-Channel20 + switchport mode trunk + no spanning-tree portfast auto + spanning-tree portfast network + ! + interface Ethernet1 + channel-group 10 mode active + ! + interface Ethernet2 + channel-group 10 mode active + ! + interface Ethernet3 + channel-group 20 mode active + ! + interface Ethernet4 + channel-group 20 mode active + ! + +**SW2** + + .. code-block:: none + + ! + vlan 100 + name FOO + ! + interface Port-Channel10 + switchport trunk allowed vlan 100 + switchport mode trunk + spanning-tree portfast + ! + interface Port-Channel20 + switchport mode trunk + no spanning-tree portfast auto + spanning-tree portfast network + ! + interface Ethernet1 + channel-group 10 mode active + ! + interface Ethernet2 + channel-group 10 mode active + ! + interface Ethernet3 + channel-group 20 mode active + ! + interface Ethernet4 + channel-group 20 mode active + ! + +.. note:: When using EVE-NG to lab this environment ensure you are using e1000 + as the desired driver for your VyOS network interfaces. When using the regular + virtio network driver no LACP PDUs will be sent by VyOS thus the port-channel + will never become active! + Operation ######### -- cgit v1.2.3 From 7a132cdfdb02fde126c3b5dcda47362ab2331450 Mon Sep 17 00:00:00 2001 From: currite Date: Tue, 15 Sep 2020 02:13:07 +0200 Subject: configuration overview: add missing contents from old wiki. Add commands: commit-confirm, copy, rename, show system commit diff . Add few little clarifications too. --- docs/configuration-overview.rst | 142 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 133 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/configuration-overview.rst b/docs/configuration-overview.rst index ee7f63a2..653c1b6e 100644 --- a/docs/configuration-overview.rst +++ b/docs/configuration-overview.rst @@ -15,18 +15,18 @@ Terminology A VyOS system has three major types of configurations: -* **Active** or **Running** configuration is the system configuration +* **Active** or **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 +* **Working configuration** is the one that 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 +* **Saved configuration** is the one 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 @@ -295,9 +295,13 @@ entered. [edit] vyos@vyos# set interface ethernet eth0 address 192.0.2.100/24 + +.. code-block:: none + [edit interfaces ethernet eth0] vyos@vyos# set address 203.0.113.6/24 + These two commands above are essentially the same, just executed from different levels in the hierarchy. @@ -369,6 +373,105 @@ different levels in the hierarchy. [edit] vyos@vyos# exit discard + +.. cfgcmd:: commit-confirm + + Commit the current set of changes if ``confirm`` is also entered + within 10 minutes. Otherwise the system reboot into the previous + configuration. + + + What if you are doing something dangerous? Suppose you want to setup + a firewall, and you are not sure there are no mistakes that will lock + you out of your system. You can use confirmed commit. If you issue + the ``commit-confirm`` command, your changes will be commited, and if + you don't issue issue the ``confirm`` command in 10 minutes, your + system will reboot into previous config revision. + + .. code-block:: none + + vyos@router# set interfaces ethernet eth0 firewall local name FromWorld + vyos@router# commit-confirm + commit confirm will be automatically reboot in 10 minutes unless confirmed + Proceed? [confirm]y + [edit] + vyos@router# confirm + [edit] + + + .. note:: A reboot because you did not enter ``confirm`` will not + take you necessarily to the *saved configuration*, but to the + point before the unfortunate commit. + + +.. cfgcmd:: copy + + Copy a configuration element. + + You can copy and remove configuration subtrees. Suppose you set up a + firewall ruleset ``FromWorld`` with one rule that allows traffic from + specific subnet. Now you want to setup a similar rule, but for + different subnet. Change your edit level to + ``firewall name FromWorld`` and use ``copy rule 10 to rule 20``, then + modify rule 20. + + + .. code-block:: none + + vyos@router# show firewall name FromWorld + default-action drop + rule 10 { + action accept + source { + address 203.0.113.0/24 + } + } + [edit] + vyos@router# edit firewall name FromWorld + [edit firewall name FromWorld] + vyos@router# copy rule 10 to rule 20 + [edit firewall name FromWorld] + vyos@router# set rule 20 source address 198.51.100.0/24 + [edit firewall name FromWorld] + vyos@router# commit + [edit firewall name FromWorld] + + +.. cfgcmd:: rename + + Rename a configuration element. + + You can also rename config subtrees: + + .. code-block:: none + + vyos@router# rename rule 10 to rule 5 + [edit firewall name FromWorld] + vyos@router# commit + [edit firewall name FromWorld] + + Note that ``show`` command respects your edit level and from this + level you can view the modified firewall ruleset with just ``show`` + with no parameters. + + .. code-block:: none + + vyos@router# show + default-action drop + rule 5 { + action accept + source { + address 203.0.113.0/24 + } + } + rule 20 { + action accept + source { + address 198.51.100.0/24 + } + } + + .. _run_opmode_from_config_mode: Access opmode from config mode @@ -451,12 +554,13 @@ any previous revisions if something goes wrong. 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. + The command :cfgcmd:`compare` allows you to compare different type of + configurations. It also lets you compare different revisions through + the :cfgcmd:`compare N M` command, where N and M are revision + numbers. The output will describe how the configuration N is when + compared to M 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 M. .. code-block:: none @@ -473,6 +577,26 @@ any previous revisions if something goes wrong. - address 192.0.2.4/24 -} + +.. opcmd:: show system commit diff + + Show commit revision difference. + + +The command above also lets you see the difference between two commits. +By default the difference with the running config is shown. + +.. code-block:: none + + vyos@router# run show system commit diff 4 + [edit system] + +ipv6 { + + disable-forwarding + +} + +This means four commits ago we did ``set system ipv6 disable-forwarding``. + + .. cfgcmd:: set system config-management commit-revisions You can specify the number of revisions stored on disk. N can be in -- cgit v1.2.3 From fc94b0cfd7682fc9eacc4fbe506cd55744759703 Mon Sep 17 00:00:00 2001 From: currite Date: Tue, 15 Sep 2020 10:28:07 +0200 Subject: qos: improve hint on choosing policy --- docs/qos.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/qos.rst b/docs/qos.rst index a4e56665..3cd183cf 100644 --- a/docs/qos.rst +++ b/docs/qos.rst @@ -336,12 +336,11 @@ you will only be able to apply one policy per interface and direction Some policies can be combined, you will be able to embed_ a different policy that will be applied to a class of the main policy. -.. hint:: If you are looking for a policy for your outbound traffic but - you do not know what policy you need, you might consider FQ-CoDel_ as - your multipurpose nearly-no-configuration low-delay fair-queue - policy; if delay does not worry you and you want to manually allocate - bandwidth shares to specific traffic, then you should consider - Shaper_. +.. hint:: **If you are looking for a policy for your outbound traffic** + but you don't know which one you need and you don't want to go + through every possible policy shown here, **our bet is that highly + likely you are looking for a** Shaper_ **policy and you want to** + :ref:`set its queues ` **as FQ-CoDel**. Drop Tail --------- -- cgit v1.2.3 From 6782d740ea3b4660606b92b5fc5b069209e9308d Mon Sep 17 00:00:00 2001 From: currite Date: Tue, 15 Sep 2020 13:36:41 +0200 Subject: image management: create system rollback subsection --- docs/image-mgmt.rst | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/image-mgmt.rst b/docs/image-mgmt.rst index 6c1b2587..143d02b2 100644 --- a/docs/image-mgmt.rst +++ b/docs/image-mgmt.rst @@ -26,7 +26,7 @@ This process allows for a system to always boot to a known working state, as the OS image is fixed and non-persistent. It also allows for multiple releases of VyOS to be installed on the same storage device. The image can be selected manually at boot if needed, but the system will otherwise boot the image -configured to be the default (:opcmd:`set system image default-boot`). +configured to be the default. .. opcmd:: show system image @@ -41,12 +41,6 @@ configured to be the default (:opcmd:`set system image default-boot`). 2: 1.2.0-rolling+201810021217 3: 1.2.0-rolling+201809252218 -.. opcmd:: set system image default-boot - - Select the default boot image which will be started on the next boot of the - System. A list of available images can be shown using the :opcmd:`show - system image` - .. opcmd:: delete system image [image-name] @@ -177,5 +171,23 @@ After reboot you might want to verify the version you are running with the :opcmd:`show version` command. +System rollback +=============== + +If you need to rollback to a previous image, you can easily do so. First +check the available images through the :opcmd:`show system image` +command and then select your image with the following command: + +.. opcmd:: set system image default-boot [image-name] + + Select the default boot image which will be started on the next boot + of the system. + +Then reboot the system. +.. note:: VyOS automatically associates the configuration to the image, + so you don't need to worry about that. Each image has a unique copy + of its configuration. +If you have access to the console, there is a another way to select +your booting image: reboot and use the GRUB menu at startup. -- cgit v1.2.3 From e17f32e74345742d9920b055a351bea9005db49d Mon Sep 17 00:00:00 2001 From: currite Date: Wed, 16 Sep 2020 12:40:22 +0200 Subject: configuration overview: create subsection for compare configurations --- docs/configuration-overview.rst | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/configuration-overview.rst b/docs/configuration-overview.rst index 653c1b6e..f8593c95 100644 --- a/docs/configuration-overview.rst +++ b/docs/configuration-overview.rst @@ -529,9 +529,24 @@ any previous revisions if something goes wrong. 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:: 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. The default setting + for this value is to store 20 revisions locally. + + +Compare configurations +---------------------- + +VyOS lets you compare different configurations. + .. cfgcmd:: compare - Compare difference in configuration revisions. + Use this command to spot what the differences are between different + configurations. .. code-block:: none @@ -597,12 +612,8 @@ By default the difference with the running config is shown. This means four commits ago we did ``set system ipv6 disable-forwarding``. -.. 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. The default setting - for this value is to store 20 revisions locally. + Rollback Changes ---------------- -- cgit v1.2.3 From 64a4ac7b7935b9fa3dbd0bb54269be8f346b0a76 Mon Sep 17 00:00:00 2001 From: currite <53279076+currite@users.noreply.github.com> Date: Wed, 16 Sep 2020 13:36:13 +0200 Subject: Update configuration-overview.rst --- docs/configuration-overview.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/configuration-overview.rst b/docs/configuration-overview.rst index f8593c95..06c86e9d 100644 --- a/docs/configuration-overview.rst +++ b/docs/configuration-overview.rst @@ -535,7 +535,7 @@ any previous revisions if something goes wrong. 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. The default setting - for this value is to store 20 revisions locally. + for this value is to store 100 revisions locally. Compare configurations -- cgit v1.2.3 From 1c2a5fb508616131917dfa5146306093cbb1c177 Mon Sep 17 00:00:00 2001 From: currite Date: Wed, 16 Sep 2020 13:59:24 +0200 Subject: configuration overview: add set and comment to editing subsection --- docs/configuration-overview.rst | 90 ++++++++++++++++++++++------------------- 1 file changed, 48 insertions(+), 42 deletions(-) (limited to 'docs') diff --git a/docs/configuration-overview.rst b/docs/configuration-overview.rst index 06c86e9d..85abbfce 100644 --- a/docs/configuration-overview.rst +++ b/docs/configuration-overview.rst @@ -12,7 +12,7 @@ files. Terminology =========== - +live A VyOS system has three major types of configurations: * **Active** or **running configuration** is the system configuration @@ -240,53 +240,21 @@ sub-level takes you back to the top level. vyos@vyos# exit Warning: configuration changes have not been saved. -Comment -------- - -.. cfgcmd:: comment "comment text" - - Add comment as an annotation to a configuration node. - - The ``comment`` command allows you to insert a comment above the - ```` configuration section. When shown, comments are - enclosed with ``/*`` and ``*/`` as open/close delimiters. Comments - need to be commited, just like other config changes. - - To remove an existing comment from your current configuration, - specify an empty string enclosed in double quote marks (``""``) as - the comment text. - - Example: - - .. code-block:: none - - vyos@vyos# comment firewall all-ping "Yes I know this VyOS is cool" - vyos@vyos# commit - vyos@vyos# show - firewall { - /* Yes I know this VyOS is cool */ - all-ping enable - broadcast-ping disable - ... - } - - .. note:: An important thing to note is that since the comment is - added on top of the section, it will not appear if the ``show -
`` command is used. With the above example, the `show - firewall` command would return starting after the ``firewall - {`` line, hiding the comment. - - Editing the configuration ========================= The configuration can be edited 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. +:cfgcmd:`delete` commands from within configuration mode. + +.. cfgcmd:: set + + Use this command to set the value of a parameter or to create a new + element. -Commands are relative to the level where they are executed and all +Configuration commands are flattened from the tree into 'one-liner' +commands shown in :opcmd:`show configuration commands` from operation +mode. Commands are relative to the level where they are executed and all redundant information from the current level is removed from the command entered. @@ -470,6 +438,44 @@ different levels in the hierarchy. address 198.51.100.0/24 } } + + +.. cfgcmd:: comment "comment text" + + Add comment as an annotation to a configuration node. + + The ``comment`` command allows you to insert a comment above the + ```` configuration section. When shown, comments are + enclosed with ``/*`` and ``*/`` as open/close delimiters. Comments + need to be commited, just like other config changes. + + To remove an existing comment from your current configuration, + specify an empty string enclosed in double quote marks (``""``) as + the comment text. + + Example: + + .. code-block:: none + + vyos@vyos# comment firewall all-ping "Yes I know this VyOS is cool" + vyos@vyos# commit + vyos@vyos# show + firewall { + /* Yes I know this VyOS is cool */ + all-ping enable + broadcast-ping disable + ... + } + + .. note:: An important thing to note is that since the comment is + added on top of the section, it will not appear if the ``show +
`` command is used. With the above example, the `show + firewall` command would return starting after the ``firewall + {`` line, hiding the comment. + + + + .. _run_opmode_from_config_mode: -- cgit v1.2.3 From 96f91545fa05efedd7bfdc7a4dfceffb69362ff7 Mon Sep 17 00:00:00 2001 From: currite Date: Thu, 17 Sep 2020 13:32:10 +0200 Subject: mss-clamping: remove unnecessary disable commnad, add directives and explanations --- docs/routing/mss-clamp.rst | 47 +++++++++++++++++++++++++++++++++------------- 1 file changed, 34 insertions(+), 13 deletions(-) (limited to 'docs') diff --git a/docs/routing/mss-clamp.rst b/docs/routing/mss-clamp.rst index 923b1338..a4edf1c6 100644 --- a/docs/routing/mss-clamp.rst +++ b/docs/routing/mss-clamp.rst @@ -1,24 +1,36 @@ -.. include:: ../_include/need_improvement.txt - .. _routing-mss-clamp: TCP-MSS Clamping ---------------- -As Internet wide PMTU discovery rarely works we sometimes need to clamp our TCP -MSS value to a specific value. Starting with VyOS 1.2 there is a firewall option -to clamp your TCP MSS value for IPv4 and IPv6. +As Internet wide PMTU discovery rarely works, we sometimes need to clamp +our TCP MSS value to a specific value. This is a field in the TCP +Options part of a SYN packet. By setting the MSS value, you are telling +the remote side unequivocally 'do not try to send me packets bigger than +this value'. -Clamping can be disabled per interface using the `disable` keyword: +Starting with VyOS 1.2 there is a firewall option to clamp your TCP MSS +value for IPv4 and IPv6. -.. code-block:: none - set firewall options interface pppoe0 disable +.. note:: MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting + in 1452 bytes on a 1492 byte MTU. + IPv4 ^^^^ -Clamp outgoing MSS value in a TCP SYN packet to `1452` for `pppoe0` and `1372` +.. cfgcmd:: set firewall options interface adjust-mss + + Use this command to set the maximum segment size for IPv4 transit + packets on a specific interface (500-1460 bytes). + + +Example +""""""" + +Clamp outgoing MSS value in a TCP SYN packet to `1452` for `pppoe0` and +`1372` for your WireGuard `wg02` tunnel. .. code-block:: none @@ -29,15 +41,24 @@ for your WireGuard `wg02` tunnel. IPv6 ^^^^^ +.. cfgcmd:: set firewall options interface adjust-mss6 + + Use this command to set the maximum segment size for IPv6 transit + packets on a specific interface (1280-1492 bytes). + + +Example +""""""" + Clamp outgoing MSS value in a TCP SYN packet to `1280` for both `pppoe0` and `wg02` interface. -To achieve the same for IPv6 please use: - .. code-block:: none set firewall options interface pppoe0 adjust-mss6 '1280' set firewall options interface wg02 adjust-mss6 '1280' -.. note:: MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting in 1452 - bytes on a 1492 byte MTU. + + +.. hint:: When doing your byte calculations, you might find useful this + `Visual packet size calculator `_. -- cgit v1.2.3 From fe6e27c2c4a767e949669ab55b91387d5adb626d Mon Sep 17 00:00:00 2001 From: currite Date: Thu, 17 Sep 2020 14:46:59 +0200 Subject: configuration-overview: fix commit-confirm definition --- docs/configuration-overview.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/configuration-overview.rst b/docs/configuration-overview.rst index 06c86e9d..680198da 100644 --- a/docs/configuration-overview.rst +++ b/docs/configuration-overview.rst @@ -374,11 +374,12 @@ different levels in the hierarchy. vyos@vyos# exit discard -.. cfgcmd:: commit-confirm +.. cfgcmd:: commit-confirm - Commit the current set of changes if ``confirm`` is also entered - within 10 minutes. Otherwise the system reboot into the previous - configuration. + Use this command to temporarily commit your changes and set the + number of minutes available for validation. ``confirm`` must + be entered within those minutes, otherwise the system will reboot + into the previous configuration. The default value is 10 minutes. What if you are doing something dangerous? Suppose you want to setup -- cgit v1.2.3 From f9cfad8e8fe0e807488b56c8cd55595da7d61c28 Mon Sep 17 00:00:00 2001 From: currite Date: Fri, 18 Sep 2020 01:44:16 +0200 Subject: nptv6: replace outside-interface command with outbound-interface command --- docs/nptv6.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/nptv6.rst b/docs/nptv6.rst index dc725a03..f4e08325 100644 --- a/docs/nptv6.rst +++ b/docs/nptv6.rst @@ -45,10 +45,10 @@ NPTv6 support has been added in VyOS 1.2 (Crux) and is available through .. code-block:: none set rule 10 source prefix 'fc00:dead:beef::/48' - set rule 10 outside-interface 'eth1' + set rule 10 outbound-interface 'eth1' set rule 10 translation prefix '2001:db8:e1::/48' set rule 20 source prefix 'fc00:dead:beef::/48' - set rule 20 outside-interface 'eth2' + set rule 20 outbound-interface 'eth2' set rule 20 translation prefix '2001:db8:e2::/48' Resulting in the following ip6tables rules: -- cgit v1.2.3 From f95ed893ca04a00eafdb665947fdc2c38d4ab397 Mon Sep 17 00:00:00 2001 From: Eron Lloyd Date: Sat, 19 Sep 2020 12:04:04 -0400 Subject: Update quick-start.rst Adding a few minor edits to clean up the descriptions and add some consistency to them. --- docs/quick-start.rst | 52 ++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 36 insertions(+), 16 deletions(-) (limited to 'docs') diff --git a/docs/quick-start.rst b/docs/quick-start.rst index 19ee9f6e..550bfd77 100644 --- a/docs/quick-start.rst +++ b/docs/quick-start.rst @@ -4,7 +4,7 @@ Quick Start ########### -This chapter will guide you on how to get up to speed using your new VyOS +This chapter will guide you on how to get up to speed quickly 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`). @@ -14,6 +14,10 @@ a :ref:`nat` gateway for a device with two network interfaces (`eth0` and Configuration Mode ################## +By default, VyOS is in operational mode, and the command prompt displays a `$`. To configure VyOS, +you will need to enter configuration mode, resulting in the command prompt displaying a `#`, as +demonstrated below: + .. code-block:: none vyos@vyos$ configure @@ -22,13 +26,13 @@ Configuration Mode Commit and Save ################ -After every configuration change you need to apply the changes by using the +After every configuration change, you need to apply the changes by using the following command: .. code-block:: none commit -Once your configuration works as expected you can save it permanently. +Once your configuration works as expected, you can save it permanently by using the following command: .. code-block:: none @@ -37,9 +41,9 @@ Once your configuration works as expected you can save it permanently. 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 +* Your outside/WAN interface will be `eth0`. It will receive its interface address + via DHCP. +* Your internal/LAN interface will be `eth1`. It will use a static IP address of `192.168.0.1/24`. After switching to :ref:`quick-start-configuration-mode` issue the following @@ -69,14 +73,17 @@ on specific addresses only. Configure DHCP/DNS Servers ########################## -* Provide DHCP service on your internal/LAN network where VyOS will act - as the default gateway and DNS server. -* Client IP addresses are assigned from the range ``192.168.0.9 - - 192.168.0.254`` +The following settings will configure DHCP and DNS services on your internal/LAN network, +where VyOS will act as the default gateway and DNS server. + +* The default gateway and DNS recursor address will be `192.168.0.1/24` +* The address range `192.168.0.2/24 - 192.168.0.8/24` will be reserved for static assignments +* DHCP clients will be assigned IP addresses within the range of `192.168.0.9 - 192.168.0.254` + and have a domain name of `internal-network` * 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 +* VyOS will serve as a full DNS recursor, replacing the need to utilize Google, + Cloudflare, or other public DNS servers (which is good for privacy) +* Only hosts from your internal/LAN network can use the DNS recursor .. code-block:: none @@ -95,7 +102,8 @@ Configure DHCP/DNS Servers NAT ### -* Configure :ref:`source-nat` for our internal/LAN network +The following settings will configure :ref:`source-nat` rules for our internal/LAN network, allowing +hosts to communicate through the outside/WAN network via IP masquerade. .. code-block:: none @@ -188,11 +196,23 @@ Set up :ref:`ssh_key_based_authentication`: Finally, try and SSH into the VyOS install as your new user. Once you have confirmed that your new user can access your router without a password, delete -the original ``vyos`` user and probably disable password authentication for -:ref:`ssh` at all: +the original ``vyos`` user and completely disable password authentication for +:ref:`ssh`: .. code-block:: none delete system login user vyos set service ssh disable-password-authentication +As above, commit your changes, save the configuration, and exit configuration mode: + +.. code-block:: none + + vyos@vyos# commit + vyos@vyos# save + Saving configuration to '/config/config.boot'... + Done + vyos@vyos# exit + vyos@vyos$ + +You now should have a simple yet secure and functioning router to experiment with further. Enjoy! -- cgit v1.2.3 From 59fb884e37e84815cd4467dbfc17e23f5fef64bb Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 20 Sep 2020 14:36:33 +0200 Subject: wwan: rename CLI command "ondemand" to "connect-on-demand" --- docs/interfaces/pppoe.rst | 2 +- docs/interfaces/wirelessmodem.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/interfaces/pppoe.rst b/docs/interfaces/pppoe.rst index ae6b11cc..75fe0a40 100644 --- a/docs/interfaces/pppoe.rst +++ b/docs/interfaces/pppoe.rst @@ -79,7 +79,7 @@ Configuration .. cfgcmd:: set interfaces pppoe connect-on-demand - Enables or disables on-demand PPPoE connection on a PPPoE unit. + When set the interface is enabled for "dial-on-demand". Use this command to instruct the system to establish a PPPoE connections automatically once traffic passes through the interface. A disabled on-demand diff --git a/docs/interfaces/wirelessmodem.rst b/docs/interfaces/wirelessmodem.rst index 5cded6c5..c41e71bf 100644 --- a/docs/interfaces/wirelessmodem.rst +++ b/docs/interfaces/wirelessmodem.rst @@ -35,9 +35,9 @@ Address Do not install DNS nameservers received from ISP into system wide nameserver list. -.. cfgcmd:: set interfaces wirelessmodem ondemand +.. cfgcmd:: set interfaces wirelessmodem connect-on-demand - Enables or disables on-demand WWAN connection. + When set the interface is enabled for "dial-on-demand". Use this command to instruct the system to establish a PPP connection automatically once traffic passes through the interface. A disabled on-demand -- cgit v1.2.3 From 7de85e0e9415d01e5cf648789f3a2bc8d0588c86 Mon Sep 17 00:00:00 2001 From: currite Date: Mon, 21 Sep 2020 20:46:26 +0200 Subject: install: pxe: warn about keeping filesytem.squashfs name https://support.sentrium.io/agent/go/ticket/1268 --- docs/install.rst | 70 ++++++++++++++++++++++++++++++++------------------------ 1 file changed, 40 insertions(+), 30 deletions(-) (limited to 'docs') diff --git a/docs/install.rst b/docs/install.rst index a210c1ad..11d0fc88 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -351,7 +351,7 @@ installation method which allows deploying VyOS through the network. * :ref:`tftp-server` * Webserver (HTTP) - optional, but we will use it to speed up installation * VyOS ISO image to be installed (do not use images prior to VyOS 1.2.3) -* Files ``pxelinux.0`` and ``ldlinux.c32`` `from the Syslinux distribution `_ +* Files *pxelinux.0* and *ldlinux.c32* `from the Syslinux distribution `_ Configuration ------------- @@ -363,7 +363,7 @@ Configure a DHCP server to provide the client with: * An IP address * The TFTP server address (DHCP option 66). Sometimes referred as *boot server* -* The *bootfile name* (DHCP option 67), which is ``pxelinux.0`` +* The *bootfile name* (DHCP option 67), which is *pxelinux.0* In this example we configured an existent VyOS as the DHCP server: @@ -389,17 +389,18 @@ Step 2: TFTP Configure a TFTP server so that it serves the following: -* The ``pxelinux.0`` file from the Syslinux distribution -* The ``ldlinux.c32`` file from the Syslinux distribution -* The kernel of the VyOS software you want to deploy. That is the ``vmlinuz`` - file inside the ``/live`` directory of the extracted contents from the ISO - file +* The *pxelinux.0* file from the Syslinux distribution +* The *ldlinux.c32* file from the Syslinux distribution +* The kernel of the VyOS software you want to deploy. That is the + *vmlinuz* file inside the */live* directory of the extracted + contents from the ISO file. * The initial ramdisk of the VyOS ISO you want to deploy. That is the - ``initrd.img`` file inside the ``/live`` directory of the extracted contents - from the ISO file. Do not use an empty (0 bytes) initrd.img file you might - find, the correct file may have a longer name. -* A directory named pxelinux.cfg which must contain the configuration file. - We will use the configuration_ file shown below, which we named default_. + *initrd.img* file inside the */live* directory of the extracted + contents from the ISO file. Do not use an empty (0 bytes) initrd.img + file you might find, the correct file may have a longer name. +* A directory named pxelinux.cfg which must contain the configuration + file. We will use the configuration_ file shown below, which we named + default_. .. _configuration: https://wiki.syslinux.org/wiki/index.php?title=Config .. _default: https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration @@ -446,35 +447,44 @@ Example of simple (no menu) configuration file: Step 3: HTTP ^^^^^^^^^^^^ -As you can 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 -over TFTP. +We also need to provide the *filesystem.squashfs* file. That is a heavy +file and TFTP is slow, so you could send it through HTTP to speed up the +transfer. That is how it is done in our example, you can find that in +the configuration file above. -First run a web server - you can use a simple one like -`Python's SimpleHTTPServer`_ and start serving the ``filesystem.squashfs`` -file. The file can be found inside the ``/live`` directory of the extracted -contents of the ISO file. +**First** run a web server - you can use a simple one like +`Python's SimpleHTTPServer`_ and start serving the `filesystem.squashfs` +file. The file can be found inside the `/live` directory of the +extracted contents of the ISO file. -Second, edit the configuration file of the :ref:`install_from_tftp` so that it shows -the correct URL at ``fetch=http:///filesystem.squashfs``. +**Second**, edit the configuration file of the :ref:`install_from_tftp` +so that it shows the correct URL at +``fetch=http:///filesystem.squashfs``. -And third, restart the TFTP service. If you are using VyOS as your TFTP Server, you can restart -the service with ``sudo service tftpd-hpa restart``. +.. note:: Do not change the name of the *filesystem.squashfs* file. If + you are working with different versions, you can create different + directories instead. -.. note:: Make sure the available directories and files in both TFTP and HTTP - server have the right permissions to be accessed from the booting clients. +And **third**, restart the TFTP service. If you are using VyOS as your +TFTP Server, you can restart the service with +``sudo service tftpd-hpa restart``. + +.. note:: Make sure the available directories and files in both TFTP + and HTTP server have the right permissions to be accessed from the + booting clients. .. _`Python's SimpleHTTPServer`: https://docs.python.org/2/library/simplehttpserver.html Client Boot ----------- -Finally, 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 -automatically taken from the TFTP and HTTP servers. +Finally, 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 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. +Once finished you will be able to proceed with the ``install image`` +command as in a regular VyOS installation. -- cgit v1.2.3 From 6b7cb55d6dcc36edc537cd718c75e8ae17713e89 Mon Sep 17 00:00:00 2001 From: currite Date: Mon, 21 Sep 2020 22:24:28 +0200 Subject: configuration mgmt: add saving and loading manually --- docs/configuration-overview.rst | 47 +++++++++++++++++++++++++++++++++++------ 1 file changed, 40 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/configuration-overview.rst b/docs/configuration-overview.rst index bf9c57d9..71bfc360 100644 --- a/docs/configuration-overview.rst +++ b/docs/configuration-overview.rst @@ -299,11 +299,14 @@ different levels in the hierarchy. Warning: configuration changes have not been saved. vyos@vyos:~$ +.. _save: + .. cfgcmd:: save - 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. + Use this command to preserve configuration changes upon reboot. By + default it is stored at */config/config.boot*. In the case you want + to store the configuration file somewhere else, you can add a local + path, an SCP address, an FTP address or a TFTP address. .. code-block:: none @@ -619,14 +622,11 @@ By default the difference with the running config is shown. This means four commits ago we did ``set system ipv6 disable-forwarding``. - - - Rollback Changes ---------------- You can rollback configuration changes using the rollback command. This -willn apply the selected revision and trigger a system reboot. +will apply the selected revision and trigger a system reboot. .. cfgcmd:: rollback @@ -675,6 +675,39 @@ be ``config.boot-hostname.YYYYMMDD_HHMMSS``. vyos@vyos# ssh-keyscan >> ~/.ssh/known_hosts +Saving and loading manually +--------------------------- + +You can use the ``save`` and ``load`` commands if you want to manually +manage specific configuration files. + +When using the save_ command, you can add a specific location where +to store your configuration file. And, when needed it, you will be able +to load it with the ``load`` command: + +.. cfgcmd:: load + + Use this command to load a configuration which will replace the + running configuration. Define the location of the configuration file + to be loaded. You can use a path to a local file, an SCP address, an + SFTP address, an FTP address, an HTTP address, an HTTPS address or a + TFTP address. + + .. code-block:: none + + vyos@vyos# load + Possible completions: + Load from system config file + Load from file on local machine + scp://:@/ Load from file on remote machine + sftp://:@/ Load from file on remote machine + ftp://:@/ Load from file on remote machine + http:/// Load from file on remote machine + https:/// Load from file on remote machine + tftp:/// Load from file on remote machine + + + Restore Default --------------- -- cgit v1.2.3 From e9171f34fbc21dda1d54dec1c4843fdcde647398 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Thu, 24 Sep 2020 21:16:59 +0200 Subject: build-vyos: add instructions how to build Linux Kernel --- docs/contributing/build-vyos.rst | 299 ++++++++++++++++++++++++++++++++ docs/contributing/upstream-packages.rst | 72 -------- 2 files changed, 299 insertions(+), 72 deletions(-) (limited to 'docs') diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst index e8bb9f37..4ed96dff 100644 --- a/docs/contributing/build-vyos.rst +++ b/docs/contributing/build-vyos.rst @@ -257,6 +257,305 @@ The full and current list can be generated with ``./configure --help``: .. _build_custom_packages: +Linux Kernel +============ + +The Linux Kernel used by VyOS is heavily tied to the ISO build process. The +file ``data/defaults.json`` hosts a JSON definition if the Kernel version used +``kernel_version`` and the ``kernel_flavor`` of the Kernel which represents the +Kernels LOCAL_VERSION. Both together form the Kernel Version variable in the +system: + +.. code-block:: none + + vyos@vyos:~$ uname -r + 4.19.146-amd64-vyos + +Other packages (e.g. vyos-1x) add dependencies to the ISO build procedure on +e.g. the wireguard-modules package which itself adds a dependency on the Kernel +version used due to the module it ships. This may change (for WireGuard) in +future Kernel releases but as long as we have out-of-tree modules. + +* WireGuard +* Accel-PPP +* Intel NIC drivers +* Inter QAT + +Each of those modules holds a dependency on the Kernel Version and if you are +lucky enough to receive an ISO build error which sounds like: + +.. code-block:: none + + I: Create initramfs if it does not exist. + Extra argument '4.19.146-amd64-vyos' + Usage: update-initramfs {-c|-d|-u} [-k version] [-v] [-b directory] + Options: + -k version Specify kernel version or 'all' + -c Create a new initramfs + -u Update an existing initramfs + -d Remove an existing initramfs + -b directory Set alternate boot directory + -v Be verbose + See update-initramfs(8) for further details. + E: config/hooks/live/17-gen_initramfs.chroot failed (exit non-zero). You should check for errors. + +The most obvious reasons could be: + +* ``vyos-build`` repo is outdate, please ``git pull`` to update to the latest + release Kernel version from us. + +* You have your own custom Kernel `*.deb` packages in the `packages` folder but + missed to create all required out-of tree modules like Accel-PPP, WireGuard, + Intel QAT, Intel NIC + +Building The Kernel +------------------- + +The Kernel build is quiet easy, most of the required steps can be found in the +``vyos-build/packages/linux-kernel/Jenkinsfile`` but we will walk you through +it. + +Clone the Kernel source to `vyos-build/packages/linux-kernel/`: + +.. code-block:: none + + $ cd cyos-build/packages/linux-kernel/ + $ git clone https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git + +Checkout the required Kernel version - see ``vyos-build/data/defaults.json`` +file (example uses kernel 4.19.146): + +.. code-block:: none + + $ cd cyos-build/packages/linux-kernel/linux + $ git checkout v4.19.146 + Checking out files: 100% (61536/61536), done. + Note: checking out 'v4.19.146'. + + You are in 'detached HEAD' state. You can look around, make experimental + changes and commit them, and you can discard any commits you make in this + state without impacting any branches by performing another checkout. + + If you want to create a new branch to retain commits you create, you may + do so (now or later) by using -b with the checkout command again. Example: + + git checkout -b + + HEAD is now at 015e94d0e37b Linux 4.19.146 + +Now we can use the helper script ``build-kernel.sh`` which does all the necessary +Voodoo by applying required patches from the `vyos-build/packages/linux-kernell/ +patches` folder, copying our Kernel configuration ``x86_64_vyos_defconfig`` to +the right location, and finally building the Debian packages. + +.. note:: You might grad your self some refreshments as the build will last for + approximately 20 minutes. + +.. code-block:: none + + (18:59) vyos_bld 412374ca36b8:/vyos/vyos-build/packages/linux-kernel [current] # ./build-kernel.sh + I: Copy Kernel config (x86_64_vyos_defconfig) to Kernel Source + I: Apply Kernel patch: /vyos/vyos-build/packages/linux-kernel/patches/kernel/0001-VyOS-Add-linkstate-IP-device-attribute.patch + patching file Documentation/networking/ip-sysctl.txt + patching file include/linux/inetdevice.h + patching file include/linux/ipv6.h + patching file include/uapi/linux/ip.h + patching file include/uapi/linux/ipv6.h + patching file net/ipv4/devinet.c + Hunk #1 succeeded at 2319 (offset 1 line). + patching file net/ipv6/addrconf.c + patching file net/ipv6/route.c + I: Apply Kernel patch: /vyos/vyos-build/packages/linux-kernel/patches/kernel/0002-VyOS-add-inotify-support-for-stackable-filesystems-o.patch + patching file fs/notify/inotify/Kconfig + patching file fs/notify/inotify/inotify_user.c + patching file fs/overlayfs/super.c + Hunk #2 succeeded at 1713 (offset 9 lines). + Hunk #3 succeeded at 1739 (offset 9 lines). + Hunk #4 succeeded at 1762 (offset 9 lines). + patching file include/linux/inotify.h + I: Apply Kernel patch: /vyos/vyos-build/packages/linux-kernel/patches/kernel/0003-RFC-builddeb-add-linux-tools-package-with-perf.patch + patching file scripts/package/builddeb + I: make x86_64_vyos_defconfig + HOSTCC scripts/basic/fixdep + HOSTCC scripts/kconfig/conf.o + YACC scripts/kconfig/zconf.tab.c + LEX scripts/kconfig/zconf.lex.c + HOSTCC scripts/kconfig/zconf.tab.o + HOSTLD scripts/kconfig/conf + # + # configuration written to .config + # + I: Generate environment file containing Kernel variable + I: Build Debian Kernel package + UPD include/config/kernel.release + /bin/sh ./scripts/package/mkdebian + dpkg-buildpackage -r"fakeroot -u" -a$(cat debian/arch) -b -nc -uc + dpkg-buildpackage: info: source package linux-4.19.146-amd64-vyos + dpkg-buildpackage: info: source version 4.19.146-1 + dpkg-buildpackage: info: source distribution buster + dpkg-buildpackage: info: source changed by vyos_bld + dpkg-buildpackage: info: host architecture amd64 + dpkg-buildpackage: warning: debian/rules is not executable; fixing that + dpkg-source --before-build . + debian/rules build + make KERNELRELEASE=4.19.146-amd64-vyos ARCH=x86 KBUILD_BUILD_VERSION=1 KBUILD_SRC= + SYSTBL arch/x86/include/generated/asm/syscalls_32.h + + ... + + + +In the end you will be presented with the Kernel binary packages which you can +then use in your custom ISO build process, by placing all the `*.deb` files in +the vyos-build/packages folder where they will be picked up automatically. + +Building Out-Of-Tree Modules +---------------------------- + +Building the Kernel is one part, but now you also need to build the required +out-of-tree modules so everything is lined up and the ABIs match. To do so, +you can again take a look at ``vyos-build/packages/linux-kernel/Jenkinsfile`` +to see all of the required modules and their selected version. We will show you +once how to build all the current required modules. + +WireGuard +^^^^^^^^^ + +First clone the source code and checkout the appropriate version by running: + +.. code-block:: none + + $ cd vyos-build/packages/linux-kernel + $ git clone https://salsa.debian.org/debian/wireguard-linux-compat.git + $ cd wireguard-linux-compat + $ git checkout debian/1.0.20200712-1_bpo10+1 + +We again make use of a helper script and some patches to make the build work. +Just run the following command: + +.. code-block:: none + + $ cd vyos-build/packages/linux-kernel + $ ./build-wireguard-modules.sh + I: Apply WireGuard patch: /vyos/packages/linux-kernel/patches/wireguard-linux-compat/0001-Debian-build-wireguard-modules-package.patch + patching file debian/control + patching file debian/rules + I: Build Debian WireGuard package + dpkg-buildpackage: info: source package wireguard-linux-compat + dpkg-buildpackage: info: source version 1.0.20200712-1~bpo10+1 + dpkg-buildpackage: info: source distribution buster-backports + dpkg-buildpackage: info: source changed by Unit 193 + dpkg-buildpackage: info: host architecture amd64 + dpkg-source --before-build . + dpkg-source: info: using patch list from debian/patches/series + dpkg-source: info: applying 0001-Makefile-do-not-use-git-to-get-version-number.patch + dpkg-source: info: applying 0002-Avoid-trying-to-compile-on-debian-5.5-kernels-Closes.patch + + ... + +After compiling the packages you will find yourself the newly generated `*.deb` +binaries in ``vyos-build/packages/linux-kernel`` from which you can copy them +to the ``vyos-build/packages`` folder for inclusion during the ISO build. + +Accel-PPP +^^^^^^^^^ + +First clone the source code and checkout the appropriate version by running: + +.. code-block:: none + + $ cd vyos-build/packages/linux-kernel + $ git clone https://github.com/accel-ppp/accel-ppp.git + +We again make use of a helper script and some patches to make the build work. +Just run the following command: + +.. code-block:: none + + $ ./build-accel-ppp.sh + I: Build Accel-PPP Debian package + CMake Deprecation Warning at CMakeLists.txt:3 (cmake_policy): + The OLD behavior for policy CMP0003 will be removed from a future version + of CMake. + + The cmake-policies(7) manual explains that the OLD behaviors of all + policies are deprecated and that a policy should be set to OLD only under + specific short-term circumstances. Projects should be ported to the NEW + behavior and not rely on setting a policy to OLD. + + + -- The C compiler identification is GNU 8.3.0 + -- Check for working C compiler: /usr/bin/cc + -- Check for working C compiler: /usr/bin/cc -- works + -- Detecting C compiler ABI info + -- Detecting C compiler ABI info - done + -- Detecting C compile features + -- Detecting C compile features - done + -- 'x86_64' + -- Found Lua: /usr/lib/x86_64-linux-gnu/liblua5.3.so;/usr/lib/x86_64-linux-gnu/libm.so (found suitable version "5.3.3", minimum required is "5.3") + -- Looking for timerfd_create + -- Looking for timerfd_create - found + -- Looking for linux/netfilter/ipset/ip_set.h + -- Looking for linux/netfilter/ipset/ip_set.h - found + -- Looking for setns + -- Looking for setns - found + + ... + +After compiling the packages you will find yourself the newly generated `*.deb` +binaries in ``vyos-build/packages/linux-kernel`` from which you can copy them +to the ``vyos-build/packages`` folder for inclusion during the ISO build. + +Intel NIC +^^^^^^^^^ + +The Intel NIC drivers do not come from a Git repository, instead we just fetch +the tarballs from our mirror and compile them. + +Simply use our wrapper script to build all of the driver modules. + +.. code-block:: none + + ./build-intel-drivers.sh + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 100 490k 100 490k 0 0 648k 0 --:--:-- --:--:-- --:--:-- 648k + I: Compile Kernel module for Intel ixgbe driver + + ... + +After compiling the packages you will find yourself the newly generated `*.deb` +binaries in ``vyos-build/packages/linux-kernel`` from which you can copy them +to the ``vyos-build/packages`` folder for inclusion during the ISO build. + +Intel QAT +^^^^^^^^^ +The Intel QAT (Quick Assist Technology) drivers do not come from a Git +repository, instead we just fetch the tarballs from 01.org, Intels Open-Source +website. + +Simply use our wrapper script to build all of the driver modules. + +.. code-block:: none + + $ ./build-intel-qat.sh + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 100 5065k 100 5065k 0 0 1157k 0 0:00:04 0:00:04 --:--:-- 1157k + I: Compile Kernel module for Intel qat driver + checking for a BSD-compatible install... /usr/bin/install -c + checking whether build environment is sane... yes + checking for a thread-safe mkdir -p... /bin/mkdir -p + checking for gawk... gawk + checking whether make sets $(MAKE)... yes + + ... + +After compiling the packages you will find yourself the newly generated `*.deb` +binaries in ``vyos-build/packages/linux-kernel`` from which you can copy them +to the ``vyos-build/packages`` folder for inclusion during the ISO build. + + Packages ======== diff --git a/docs/contributing/upstream-packages.rst b/docs/contributing/upstream-packages.rst index d43e61f3..5c48bbb3 100644 --- a/docs/contributing/upstream-packages.rst +++ b/docs/contributing/upstream-packages.rst @@ -59,26 +59,6 @@ reason we debianize that module by hand now, using this procedure: The package ends up in deb_dist dir. -ppp -^^^ - -Properly renaming PPTP and L2TP interfaces to pptpX and l2tpX from generic and -non-informative pppX requires a patch that is neither in the upstream nor in -Debian. - -We keep a fork of Debian's repo at https://github.com/vyos/ppp-debian - -The patches for pre-up renaming are: - -* https://github.com/vyos/ppp-debian/commit/e728180026a051d2a96396276e7e4ae -* https://github.com/vyos/ppp-debian/commit/f29ba8d9ebb043335a096d70bcd07e9 - -Additionally, there's a patch for reopening the log file to better support -logging to files, even though it's less essential: -https://github.com/vyos/ppp-debian/commit/dd2ebd5cdcddb40230dc4cc43d374055f - -The patches were written by Stephen Hemminger back in the Vyatta times. - mdns-repeater ^^^^^^^^^^^^^ @@ -95,58 +75,6 @@ https://github.com/vyos/udp-broadcast-relay No special build procedure is required. -Linux kernel -^^^^^^^^^^^^ - -In the past a fork of the Kernel source code was kept at the well-known -location of https://github.com/vyos/vyos-kernel - where it is kept for history. - -Nowadays the Kernel we use is the upstream source code which is patched -with two additional patches from the good old Vyatta times which never made it -into the mainstream Kernel. The patches can be found here: -https://github.com/vyos/vyos-build-kernel/tree/master/patches/kernel and are -automatically applied to the Kernel by the Jenkins Pipeline which is used to -generate the Kernel binaries. - -The Pipeline script not only builds the Kernel with the configuration named -``x86_64_vyos_defconfig`` which is located in the vyos-build-kernel repository, -too - but in addition also builds some Intel out-of-tree drivers, WireGuard -(as long it is not upstreamed) and Accel-PPP. - -The ``Jenkinsfile`` tries to be as verbose as possible on each individual build -step. - -Linux Firmware -^^^^^^^^^^^^^^ - -More and more hardware cards require an additional firmware which is not open -source. The Kernel community hosts a special linux-firmware Git repository -with all available binary files which can be loaded by the Kernel. - -The ``vyos-build`` repository fetches a specific commit of the linux-firmware -repository and embeds those binaries into the resulting ISO image. This step is -done in the ``data/live-build-config/hooks/live/40-linux-firmware.chroot`` file. - -If the firmware needs to be updated it is sufficient to just exchange the Git -commit id we reference in our build. - -Intel NIC drivers -^^^^^^^^^^^^^^^^^ - -We do not make use of the building Intel NIC drivers except for e1000e. Main -reason is that the out of tree Intel drivers seem be perform a bit better, -e.q. have proper receive-side-scaling and multi-queue support. - -Drivers are build as part of the Kernel Pipeline - read above. - -Accel-PPP -^^^^^^^^^ - -Accel-PPP used to be an upstream fork for quite some time but now has been -converted to make use of the upstream source code and build system. - -It is build as part of the Kernel Pipeline - read above. - hvinfo ^^^^^^ -- cgit v1.2.3 From 7bc844be7fa021d6ae27d7ac21f2534e1d85a7e4 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Thu, 24 Sep 2020 21:37:41 +0200 Subject: build-vyos: kernel: add more verbose build output as example --- docs/contributing/build-vyos.rst | 67 +++++++++++++++++++++++++++++++--------- 1 file changed, 52 insertions(+), 15 deletions(-) (limited to 'docs') diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst index 4ed96dff..6d157f84 100644 --- a/docs/contributing/build-vyos.rst +++ b/docs/contributing/build-vyos.rst @@ -403,6 +403,27 @@ the right location, and finally building the Debian packages. ... + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: package could avoid a useless dependency if /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/trace /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/perf were not linked against libcrypto.so.1.1 (they use none of the library's symbols) + dpkg-shlibdeps: warning: package could avoid a useless dependency if /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/trace /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/perf were not linked against libcrypt.so.1 (they use none of the library's symbols) + dpkg-deb: building package 'linux-tools-4.19.146-amd64-vyos' in '../linux-tools-4.19.146-amd64-vyos_4.19.146-1_amd64.deb'. + dpkg-genbuildinfo --build=binary + dpkg-genchanges --build=binary >../linux-4.19.146-amd64-vyos_4.19.146-1_amd64.changes + dpkg-genchanges: warning: package linux-image-4.19.146-amd64-vyos-dbg in control file but not in files list + dpkg-genchanges: info: binary-only upload (no source code included) + dpkg-source --after-build . + dpkg-buildpackage: info: binary-only upload (no source included) In the end you will be presented with the Kernel binary packages which you can @@ -453,6 +474,15 @@ Just run the following command: ... + dpkg-genchanges: info: binary-only upload (no source code included) + debian/rules clean + dh clean + dh_clean + dpkg-source --after-build . + dpkg-source: info: unapplying 0002-Avoid-trying-to-compile-on-debian-5.5-kernels-Closes.patch + dpkg-source: info: unapplying 0001-Makefile-do-not-use-git-to-get-version-number.patch + dpkg-buildpackage: info: binary-only upload (no source included) + After compiling the packages you will find yourself the newly generated `*.deb` binaries in ``vyos-build/packages/linux-kernel`` from which you can copy them to the ``vyos-build/packages`` folder for inclusion during the ISO build. @@ -483,25 +513,17 @@ Just run the following command: specific short-term circumstances. Projects should be ported to the NEW behavior and not rely on setting a policy to OLD. - -- The C compiler identification is GNU 8.3.0 - -- Check for working C compiler: /usr/bin/cc - -- Check for working C compiler: /usr/bin/cc -- works - -- Detecting C compiler ABI info - -- Detecting C compiler ABI info - done - -- Detecting C compile features - -- Detecting C compile features - done - -- 'x86_64' - -- Found Lua: /usr/lib/x86_64-linux-gnu/liblua5.3.so;/usr/lib/x86_64-linux-gnu/libm.so (found suitable version "5.3.3", minimum required is "5.3") - -- Looking for timerfd_create - -- Looking for timerfd_create - found - -- Looking for linux/netfilter/ipset/ip_set.h - -- Looking for linux/netfilter/ipset/ip_set.h - found - -- Looking for setns - -- Looking for setns - found ... + CPack: Create package using DEB + CPack: Install projects + CPack: - Run preinstall target for: accel-ppp + CPack: - Install project: accel-ppp + CPack: Create package + CPack: - package: /vyos/vyos-build/packages/linux-kernel/accel-ppp/build/accel-ppp.deb generated. + After compiling the packages you will find yourself the newly generated `*.deb` binaries in ``vyos-build/packages/linux-kernel`` from which you can copy them to the ``vyos-build/packages`` folder for inclusion during the ISO build. @@ -524,6 +546,13 @@ Simply use our wrapper script to build all of the driver modules. ... + I: Building Debian package vyos-intel-iavf + Doing `require 'backports'` is deprecated and will not load any backport in the next major release. + Require just the needed backports instead, or 'backports/latest'. + Debian packaging tools generally labels all files in /etc as config files, as mandated by policy, so fpm defaults to this behavior for deb packages. You can disable this default behavior with --deb-no-default-config-files flag {:level=>:warn} + Created package {:path=>"vyos-intel-iavf_4.0.1-0_amd64.deb"} + I: Cleanup iavf source + After compiling the packages you will find yourself the newly generated `*.deb` binaries in ``vyos-build/packages/linux-kernel`` from which you can copy them to the ``vyos-build/packages`` folder for inclusion during the ISO build. @@ -551,6 +580,14 @@ Simply use our wrapper script to build all of the driver modules. ... + I: Building Debian package vyos-intel-qat + Doing `require 'backports'` is deprecated and will not load any backport in the next major release. + Require just the needed backports instead, or 'backports/latest'. + Debian packaging tools generally labels all files in /etc as config files, as mandated by policy, so fpm defaults to this behavior for deb packages. You can disable this default behavior with --deb-no-default-config-files flag {:level=>:warn} + Created package {:path=>"vyos-intel-qat_1.7.l.4.9.0-00008-0_amd64.deb"} + I: Cleanup qat source + + After compiling the packages you will find yourself the newly generated `*.deb` binaries in ``vyos-build/packages/linux-kernel`` from which you can copy them to the ``vyos-build/packages`` folder for inclusion during the ISO build. -- cgit v1.2.3 From ad5f61e19e1c29f6c639762f97126d2d44bb4f65 Mon Sep 17 00:00:00 2001 From: kroy-the-rabbit Date: Thu, 24 Sep 2020 15:48:22 -0500 Subject: build-iso: kernel: small spelling/wording update --- docs/contributing/build-vyos.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst index 6d157f84..c6098763 100644 --- a/docs/contributing/build-vyos.rst +++ b/docs/contributing/build-vyos.rst @@ -319,7 +319,7 @@ Clone the Kernel source to `vyos-build/packages/linux-kernel/`: .. code-block:: none - $ cd cyos-build/packages/linux-kernel/ + $ cd vyos-build/packages/linux-kernel/ $ git clone https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git Checkout the required Kernel version - see ``vyos-build/data/defaults.json`` @@ -327,7 +327,7 @@ file (example uses kernel 4.19.146): .. code-block:: none - $ cd cyos-build/packages/linux-kernel/linux + $ cd vyos-build/packages/linux-kernel/linux $ git checkout v4.19.146 Checking out files: 100% (61536/61536), done. Note: checking out 'v4.19.146'. @@ -344,12 +344,11 @@ file (example uses kernel 4.19.146): HEAD is now at 015e94d0e37b Linux 4.19.146 Now we can use the helper script ``build-kernel.sh`` which does all the necessary -Voodoo by applying required patches from the `vyos-build/packages/linux-kernell/ +Voodoo by applying required patches from the `vyos-build/packages/linux-kernel/ patches` folder, copying our Kernel configuration ``x86_64_vyos_defconfig`` to the right location, and finally building the Debian packages. -.. note:: You might grad your self some refreshments as the build will last for - approximately 20 minutes. +.. note:: Building the kernel will take some time depending on the speed and quantity of your CPU/cores and disk speed. Plan on 20 minutes or even longer on lower end harder .. code-block:: none @@ -428,7 +427,7 @@ the right location, and finally building the Debian packages. In the end you will be presented with the Kernel binary packages which you can then use in your custom ISO build process, by placing all the `*.deb` files in -the vyos-build/packages folder where they will be picked up automatically. +the vyos-build/packages folder where they will be used automatically when building VyOS as documented above. Building Out-Of-Tree Modules ---------------------------- -- cgit v1.2.3 From cbb29ca10c1ec5853d7b665bb36dddf4301e27ff Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Fri, 25 Sep 2020 20:08:59 +0200 Subject: development: update python skeleton --- docs/contributing/development.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst index 17f5cc48..b382b131 100644 --- a/docs/contributing/development.rst +++ b/docs/contributing/development.rst @@ -271,7 +271,7 @@ device if you happen to be a crazy scientist. #!/usr/bin/env python3 # - # Copyright (C) 2019 VyOS maintainers and contributors + # Copyright (C) 2020 VyOS maintainers and contributors # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License version 2 or later as @@ -291,10 +291,16 @@ device if you happen to be a crazy scientist. from vyos import ConfigError def get_config(): - vc = Config() + if config: + conf = config + else: + conf = Config() + + # Base path to CLI nodes + base = ['...', '...'] # Convert the VyOS config to an abstract internal representation - config = ... - return config + config_data = conf.get_config_dict(base, key_mangling=('-', '_'), get_first_key=True) + return config_data def verify(config): # Verify that configuration is valid -- cgit v1.2.3 From 840bfc9e2a51305c68fa09e9cab82a14a9bb16bf Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Fri, 25 Sep 2020 20:10:42 +0200 Subject: development: fix __main__ of Python skeleton --- docs/contributing/development.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst index b382b131..86371845 100644 --- a/docs/contributing/development.rst +++ b/docs/contributing/development.rst @@ -317,8 +317,10 @@ device if you happen to be a crazy scientist. pass try: - config = get_config() - verify(config) + c = get_config() + verify(c) + generate(c) + apply(c) except ConfigError as e: print(e) sys.exit(1) -- cgit v1.2.3 From 71f73a88a040a4d2e24e0e8d029f5067a4a7a94a Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Fri, 2 Oct 2020 17:56:53 +0200 Subject: sstp: T2953: adjust to new ppp-options CLI node --- docs/vpn/sstp.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/vpn/sstp.rst b/docs/vpn/sstp.rst index de13b5ae..486f66e8 100644 --- a/docs/vpn/sstp.rst +++ b/docs/vpn/sstp.rst @@ -23,9 +23,11 @@ certificates as well as a private PKI is required. certificates are not stored in the ``/config`` directory they will not be migrated during a software update. +Certificates +============ -Self Signed CA and Certificates -=============================== +Self Signed CA +-------------- To generate the CA, the server private key and certificates the following commands can be used. @@ -152,23 +154,23 @@ SSL Certificates PPP Settings ------------ -.. cfgcmd:: set vpn sstp ppp-settings lcp-echo-failure +.. cfgcmd:: set vpn sstp ppp-options lcp-echo-failure Defines the maximum `` of unanswered echo requests. Upon reaching the value ``, the session will be reset. -.. cfgcmd:: set vpn sstp ppp-settings lcp-echo-interval +.. cfgcmd:: set vpn sstp ppp-options lcp-echo-interval If this option is specified and is greater than 0, then the PPP module will send LCP pings of the echo request every `` seconds. -.. cfgcmd:: set vpn sstp ppp-settings lcp-echo-timeout +.. cfgcmd:: set vpn sstp ppp-options lcp-echo-timeout Specifies timeout in seconds to wait for any peer activity. If this option specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" is not used. -.. cfgcmd:: set vpn sstp ppp-settings mppe +.. cfgcmd:: set vpn sstp ppp-options mppe Specifies :abbr:`MPPE (Microsoft Point-to-Point Encryption)` negotioation preference. -- cgit v1.2.3 From d0a50a0383d25aa4c14f68e3763800c002d19017 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 4 Oct 2020 20:41:05 +0200 Subject: sstp: adjust to latest CLI commands --- docs/vpn/sstp.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/vpn/sstp.rst b/docs/vpn/sstp.rst index 486f66e8..e5567cb6 100644 --- a/docs/vpn/sstp.rst +++ b/docs/vpn/sstp.rst @@ -100,18 +100,18 @@ Configuration * **local**: All authentication queries are handled locally. -.. cfgcmd:: set vpn sstp network-settings client-ip-settings gateway-address +.. cfgcmd:: set vpn sstp gateway-address Specifies single `` IP address to be used as local address of PPP interfaces. -.. cfgcmd:: set vpn sstp network-settings client-ip-settings subnet +.. cfgcmd:: set vpn sstp client-ip-pool subnet Use `` as the IP pool for all connecting clients. -.. cfgcmd:: set vpn sstp network-settings client-ipv6-pool prefix
mask +.. cfgcmd:: set vpn sstp client-ipv6-pool prefix
mask Use this comand to set the IPv6 address pool from which an SSTP client will get an IPv6 prefix of your defined length (mask) to terminate the @@ -119,7 +119,7 @@ Configuration bit long, the default value is 64. -.. cfgcmd:: set vpn sstp network-settings client-ipv6-pool delegate
delegation-prefix +.. cfgcmd:: set vpn sstp client-ipv6-pool delegate
delegation-prefix Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on SSTP. You will have to set your IPv6 pool and the length of the @@ -128,7 +128,7 @@ Configuration delegation prefix can be set from 32 to 64 bit long. -.. cfgcmd:: set vpn sstp network-settings name-server
+.. cfgcmd:: set vpn sstp name-server
Connected client should use `
` as their DNS server. This command accepts both IPv4 and IPv6 addresses. Up to two nameservers @@ -271,15 +271,15 @@ Example .. code-block:: none - set vpn sstp authentication local-users username foo password 'bar' - set vpn sstp authentication mode 'local' - set vpn sstp network-settings client-ip-settings gateway-address '192.0.2.254' - set vpn sstp network-settings client-ip-settings subnet '192.0.2.0/25' - set vpn sstp network-settings name-server '10.0.0.1' - set vpn sstp network-settings name-server '10.0.0.2' - set vpn sstp ssl ca-cert-file '/config/auth/ca.crt' - set vpn sstp ssl cert-file '/config/auth/server.crt' - set vpn sstp ssl key-file '/config/auth/server.key' + set vpn sstp authentication local-users username vyos password vyos + set vpn sstp authentication mode local + set vpn sstp gateway-address 192.0.2.254 + set vpn sstp client-ip-pool subnet 192.0.2.0/25 + set vpn sstp name-server 10.0.0.1 + set vpn sstp name-server 10.0.0.2 + set vpn sstp ssl ca-cert-file /config/auth/ca.crt + set vpn sstp ssl cert-file /config/auth/server.crt + set vpn sstp ssl key-file /config/auth/server.key Testing SSTP ============ -- cgit v1.2.3 From e2b75f6be4b144cf0d14fb557d791a1e97b7f998 Mon Sep 17 00:00:00 2001 From: currite Date: Tue, 6 Oct 2020 14:03:06 +0200 Subject: qos: fix fq-codel example --- docs/qos.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/qos.rst b/docs/qos.rst index 3cd183cf..447780f1 100644 --- a/docs/qos.rst +++ b/docs/qos.rst @@ -527,8 +527,8 @@ A simple example of an FQ-CoDel policy working inside a Shaper one. .. code-block:: none set traffic-policy shaper FQ-CODEL-SHAPER bandwidth 2gbit - set traffic-policy shaper FQ-CODEL-SHAPER 100% - set traffic-policy shaper FQ-CODEL-SHAPER fq-codel + set traffic-policy shaper FQ-CODEL-SHAPER default bandwidth 100% + set traffic-policy shaper FQ-CODEL-SHAPER default queue-type fq-codel -- cgit v1.2.3 From 61acd8021f8ab7ca502412bc0796a55bf4f1b255 Mon Sep 17 00:00:00 2001 From: root Date: Fri, 16 Oct 2020 08:57:36 -0400 Subject: vxlan syntax correction: link and remote-port parameters are not available in rolling release Replaced "link" with "source-interface" and "remote-port" with "port" .. code-block:: none vyos@vyos# set int vxlan vxlan1 Possible completions: + address IP address description Interface specific description disable Administratively disable interface > firewall Firewall options group Multicast group address for VXLAN interface > ip IPv4 routing parameters > ipv6 IPv6 routing parameters mac Media Access Control (MAC) address mtu Maximum Transmission Unit (MTU) > policy Policy route options port Destination port of VXLAN tunnel (default: 8472) remote Remote address of VXLAN tunnel source-address VXLAN source address source-interface Physical interface used for connection vni Virtual Network Identifier --- docs/interfaces/vxlan.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/interfaces/vxlan.rst b/docs/interfaces/vxlan.rst index a11f4b62..bf3b6dee 100644 --- a/docs/interfaces/vxlan.rst +++ b/docs/interfaces/vxlan.rst @@ -230,7 +230,7 @@ traffic from. set interfaces bridge br241 member interface 'vxlan241' set interfaces vxlan vxlan241 group '239.0.0.241' - set interfaces vxlan vxlan241 link 'eth0' + set interfaces vxlan vxlan241 source-interface 'eth0' set interfaces vxlan vxlan241 vni '241' ! Our seconds vxlan interface @@ -239,7 +239,7 @@ traffic from. set interfaces bridge br242 member interface 'vxlan242' set interfaces vxlan vxlan242 group '239.0.0.242' - set interfaces vxlan vxlan242 link 'eth0' + set interfaces vxlan vxlan242 source-interface 'eth0' set interfaces vxlan vxlan242 vni '242' **Leaf3 configuration:** @@ -255,7 +255,7 @@ traffic from. set interfaces bridge br241 member interface 'vxlan241' set interfaces vxlan vxlan241 group '239.0.0.241' - set interfaces vxlan vxlan241 link 'eth0' + set interfaces vxlan vxlan241 source-interface 'eth0' set interfaces vxlan vxlan241 vni '241' ! Our seconds vxlan interface @@ -264,7 +264,7 @@ traffic from. set interfaces bridge br242 member interface 'vxlan242' set interfaces vxlan vxlan242 group '239.0.0.242' - set interfaces vxlan vxlan242 link 'eth0' + set interfaces vxlan vxlan242 source-interface 'eth0' set interfaces vxlan vxlan242 vni '242' As you can see, Leaf2 and Leaf3 configuration is almost identical. There are @@ -300,7 +300,7 @@ same on all Leafs that has this interface. .. code-block:: none - set interfaces vxlan vxlan241 link 'eth0' + set interfaces vxlan vxlan241 source-interface 'eth0' Sets the interface to listen for multicast packets on. Could be a loopback, not yet tested. @@ -314,7 +314,7 @@ multicast-address. .. code-block:: none - set interfaces vxlan vxlan241 remote-port 12345 + set interfaces vxlan vxlan241 port 12345 The destination port used for creating a VXLAN interface in Linux defaults to its pre-standard value of 8472 to preserve backwards compatibility. A @@ -331,7 +331,7 @@ set directly. Let's change the Multicast example from above: # leaf2 and leaf3 delete interfaces vxlan vxlan241 group '239.0.0.241' - delete interfaces vxlan vxlan241 link 'eth0' + delete interfaces vxlan vxlan241 source-interface 'eth0' # leaf2 set interface vxlan vxlan241 remote 10.1.3.3 @@ -340,4 +340,4 @@ set directly. Let's change the Multicast example from above: set interface vxlan vxlan241 remote 10.1.2.2 The default port udp is set to 8472. -It can be changed with ``set interface vxlan remote-port `` +It can be changed with ``set interface vxlan port `` -- cgit v1.2.3 From ad28f19e2c0765b76b024c40cca7ba29f5edc065 Mon Sep 17 00:00:00 2001 From: Cheeze-It Date: Mon, 19 Oct 2020 04:40:58 -0600 Subject: MPLS: extend documentation with new functionality --- docs/routing/mpls.rst | 160 ++++++++++++++++++++++++++++++++++---------------- 1 file changed, 109 insertions(+), 51 deletions(-) (limited to 'docs') diff --git a/docs/routing/mpls.rst b/docs/routing/mpls.rst index c6d9d0fe..9f0d1a18 100644 --- a/docs/routing/mpls.rst +++ b/docs/routing/mpls.rst @@ -4,104 +4,162 @@ MPLS **** +**Multi-Protocol Label Switching** (initialized as MPLS) is a packet forwarding paradigm +which differs from regular IP forwarding. Instead of IP addresses being used to make the +decision on finding the exit interface, a router will instead use an exact match on a +32 bit/4 byte header called the MPLS label. This label is inserted between the ethernet +(layer 2) header and the IP (layer 3) header. One can statically or dynamically assign +label allocations, but we will focus on dynamic allocation of labels using some sort of +label distribution protocol (such as the aptly named Label Distribution Protocol / LDP, +Resource Reservation Protocol / RSVP, or Segment Routing through OSPF/ISIS). These +protocols allow for the creation of a unidirectional/unicast path called a labeled switched path +(initialized as LSP) throughout the network that operates very much like a tunnel through +the network. An easy way of thinking about how an MPLS LSP actually forwards traffic +throughout a network is to think of a GRE tunnel. They are not the same in how they +operate, but they are the same in how they handle the tunneled packet. It would be +good to think of MPLS as a tunneling technology that can be used to transport many +different types of packets, to aid in traffic engineering by allowing one to specify +paths throughout the network (using RSVP or SR), and to generally allow for easier +intra/inter network transport of data packets. For more information on how MPLS +label switching works, please go `here `__. + + +.. note:: MPLS support in VyOS is not finished yet, and therefore its functionality is limited. Currently there is no support for MPLS enabled VPN services such as L3VPNs, L2VPNs, and mVPNs. RSVP support is also not present as the underlying routing stack (FRR) does not implement it. Currently VyOS can be configured as a label switched router (MPLS P router), in both penultimate and ultimate hop popping operations. + + Label Distribution Protocol =========================== +The **Multi-Protocol Label Switching** (MPLS) architecture does not +assume a single protocol to create MPLS paths. VyOS supports the Label +Distribution Protocol (LDP) as implemented by FRR, based on `RFC 5036 `__. + +LDP is a TCP based MPLS signaling protocol that distributes +labels creating MPLS label switched paths in a dynamic manner. +LDP is not a routing protocol, as it relies on other routing +protocols for forwarding decisions. LDP cannot bootstrap itself, +and therefore relies on said routing protocols for communication +with other routers that use LDP. -.. note:: VyOS' MPLS support is not finished yet, its funcitionality is - limited. Currently it can only be configured as a P router, that is, - an LSR in the core of an MPLS network. +In order to allow for LDP on the local router to exchange label advertisements +with other routers, a TCP session will be established between automatically +discovered and statically assigned routers. LDP will try to establish a TCP +session to the **transport address** of other routers. Therefore for LDP to +function properly please make sure the transport address is shown in the +routing table and reachable to traffic at all times. +It is highly recommended to use the same address for both the LDP router-id and the +discovery transport address, but for VyOS MPLS LDP to work both parameters must +be explicitly set in the configuration. -The **Multi-Protocol Label Switching** (MPLS) architecture does not -assume a single protocol to create MPLS paths. VyOS supports the Label -Distribution Protocol (LDP) as implemented by FRR, based on `RFC 5036 `__. -LDT it is an MPLS signaling protocol that distributes labels creating -MPLS paths in a dynamic manner. LDT is not exactly a routing protocol, -as it relies on other routing protocols for forwarding decisions. +Configuration Options +--------------------- -.. cfgcmd:: set protocols mpls ldp interface +Use this command to enable LDP, and enable MPLS processing on the interface you define. + + .. cfgcmd:: set protocols mpls ldp interface - Use this command to enable LDP in the interface you define. +Use this command to configure the IP address used as the LDP +router-id of the local device. + .. cfgcmd:: set protocols mpls ldp router-id
-.. cfgcmd:: set protocols mpls ldp router-id
+Use this command to set the IPv4 or IPv6 transport-address used by +LDP. - Use this command to configure the IP address used as the LDP - router-id of the local device + .. cfgcmd:: set protocols mpls ldp discovery transport-ipv4-address + .. cfgcmd:: set protocols mpls ldp discovery transport-ipv6-address +Use this command to configure authentication for LDP peers. Set the +IP address of the LDP peer and a password that should be shared in +order to become neighbors. -In order to allow the exchange of label advertisements required for LDP, -a TCP session should be established between routers. Routers will need -to learn each other's **transport address** in order to establish the -TCP session. + .. cfgcmd:: set protocols mpls ldp neighbor password -You may want to use the same address for both the LDP router-id and the -discovery transport address, but for VyOS MPLS LDP to work both -parameters must be explicitely set in the configuration. +Use this command if you would like to set the discovery +hello and hold time parameters. + .. cfgcmd:: set protocols mpls ldp discovery hello-interval + .. cfgcmd:: set protocols mpls ldp discovery hello-holdtime -.. cfgcmd:: set protocols mpls ldp discovery transport-ipv4-address | transport-ipv6-address
+Use this command if you would like to set the TCP session hold time +intervals. + + .. cfgcmd:: set protocols mpls ldp discovery session-ipv4-holdtime + .. cfgcmd:: set protocols mpls ldp discovery session-ipv6-holdtime - Use this command to set the IPv4 or IPv6 transport-address used by - LDP. +Use this command if you would like for the router to advertise FECs with +a label of 0 for explicit null operations. + + .. cfgcmd:: set protocols mpls ldp export ipv4 explicit-null + .. cfgcmd:: set protocols mpls ldp export ipv6 explicit-null -.. cfgcmd:: set protocols mpls ldp neighbor
password - Use this command to configure authentication for LDP peers. Set the - IP address of the LDP peer and a password that should be shared in - order to become neighbors. +Sample configuration to setup LDP on VyOS +--------------------------------------------- -Example -------- + .. code-block:: none -.. code-block:: none + set protocols ospf area 0 network '192.168.255.252/32' <--- Routing for loopback + set protocols ospf area 0 network '192.168.0.5/32' <--- Routing for an interface connecting to the network + set protocols ospf parameters router-id '192.168.255.252' <--- Router ID setting for OSPF + set protocols mpls ldp discovery transport-ipv4-address '192.168.255.252' <--- Transport address for LDP for TCP sessions to connect to + set protocols mpls ldp interface 'eth1' <--- Enable MPLS and LDP for an interface connecting to network + set protocols mpls ldp interface 'lo' <--- Enable MPLS and LDP on loopback for future services connectivity + set protocols mpls ldp router-id '192.168.255.252' <--- Router ID setting for LDP + set interfaces ethernet eth1 address '192.168.0.5/31' <--- Interface IP for connecting to network + set interfaces loopback lo address '192.168.255.252/32' <--- Interface loopback IP for router ID and other uses - set interfaces dummy dum0 address '2.2.2.2/32' - set interfaces ethernet eth1 address '10.0.0.2/24' - set interfaces ethernet eth2 address '10.0.255.1/24' - set protocols mpls ldp discovery transport-ipv4-address '2.2.2.2' - set protocols mpls ldp interface 'eth1' - set protocols mpls ldp interface 'eth2' - set protocols mpls ldp router-id '2.2.2.2' - set protocols ospf area 0 network '0.0.0.0/0' - set protocols ospf parameters router-id '2.2.2.2' -show commands +Show Commands ------------- When LDP is working, you will be able to see label information in the outcome of ``show ip route``. Besides that information, there are also specific *show* commands for LDP: +Use this command to see the Label Information Base. + + .. opcmd:: show mpls ldp binding + + + + +Use this command to see discovery hello information + + .. opcmd:: show mpls ldp discovery + + + -.. opcmd:: show mpls ldp binding +Use this command to see LDP interface information - Use this command to see the Label Information Base. + .. opcmd:: show mpls ldp interface -.. opcmd:: show mpls ldp discovery - Use this command to see Discovery Hello information +Use this command to see LDP neighbor information -.. opcmd:: show mpls ldp interface + .. opcmd:: show mpls ldp neighbor - Use this command to see LDP interface information -.. opcmd:: show mpls ldp neighbor - Uset this command to see LDP neighbor information +Use this command to see detailed LDP neighbor information + .. opcmd:: show mpls ldp neighbor detail -.. opcmd:: show mpls ldp neighbor detail - Uset this command to see detailed LDP neighbor information +Reset Commands +-------------- +Use this command to reset an LDP neighbor/TCP session that is established + + .. opcmd:: reset mpls ldp neighbor -- cgit v1.2.3 From 46d1c9810560c6d3ce6f0646522df841923e811b Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Mon, 19 Oct 2020 12:54:36 +0200 Subject: MPLS: fix op-mode definitions and line breaks --- docs/routing/mpls.rst | 214 ++++++++++++++++++++++++-------------------------- 1 file changed, 103 insertions(+), 111 deletions(-) (limited to 'docs') diff --git a/docs/routing/mpls.rst b/docs/routing/mpls.rst index 9f0d1a18..0ae6094c 100644 --- a/docs/routing/mpls.rst +++ b/docs/routing/mpls.rst @@ -1,46 +1,51 @@ .. _mpls: -**** -MPLS -**** - -**Multi-Protocol Label Switching** (initialized as MPLS) is a packet forwarding paradigm -which differs from regular IP forwarding. Instead of IP addresses being used to make the -decision on finding the exit interface, a router will instead use an exact match on a -32 bit/4 byte header called the MPLS label. This label is inserted between the ethernet -(layer 2) header and the IP (layer 3) header. One can statically or dynamically assign -label allocations, but we will focus on dynamic allocation of labels using some sort of -label distribution protocol (such as the aptly named Label Distribution Protocol / LDP, -Resource Reservation Protocol / RSVP, or Segment Routing through OSPF/ISIS). These -protocols allow for the creation of a unidirectional/unicast path called a labeled switched path -(initialized as LSP) throughout the network that operates very much like a tunnel through -the network. An easy way of thinking about how an MPLS LSP actually forwards traffic -throughout a network is to think of a GRE tunnel. They are not the same in how they -operate, but they are the same in how they handle the tunneled packet. It would be -good to think of MPLS as a tunneling technology that can be used to transport many -different types of packets, to aid in traffic engineering by allowing one to specify -paths throughout the network (using RSVP or SR), and to generally allow for easier -intra/inter network transport of data packets. For more information on how MPLS -label switching works, please go `here `__. - - -.. note:: MPLS support in VyOS is not finished yet, and therefore its functionality is limited. Currently there is no support for MPLS enabled VPN services such as L3VPNs, L2VPNs, and mVPNs. RSVP support is also not present as the underlying routing stack (FRR) does not implement it. Currently VyOS can be configured as a label switched router (MPLS P router), in both penultimate and ultimate hop popping operations. - - +#### +MPLS +#### + +:abbr:`MPLS (Multi-Protocol Label Switching)` is a packet forwarding paradigm +which differs from regular IP forwarding. Instead of IP addresses being used to +make the decision on finding the exit interface, a router will instead use an +exact match on a 32 bit/4 byte header called the MPLS label. This label is +inserted between the ethernet (layer 2) header and the IP (layer 3) header. +One can statically or dynamically assign label allocations, but we will focus +on dynamic allocation of labels using some sort of label distribution protocol +(such as the aptly named Label Distribution Protocol / LDP, Resource Reservation +Protocol / RSVP, or Segment Routing through OSPF/ISIS). These protocols allow +for the creation of a unidirectional/unicast path called a labeled switched +path (initialized as LSP) throughout the network that operates very much like +a tunnel through the network. An easy way of thinking about how an MPLS LSP +actually forwards traffic throughout a network is to think of a GRE tunnel. +They are not the same in how they operate, but they are the same in how they +handle the tunneled packet. It would be good to think of MPLS as a tunneling +technology that can be used to transport many different types of packets, to +aid in traffic engineering by allowing one to specify paths throughout the +network (using RSVP or SR), and to generally allow for easier intra/inter +network transport of data packets. + +For more information on how MPLS label switching works, please go visit +`Wikipedia (MPLS)`_. + +.. note:: MPLS support in VyOS is not finished yet, and therefore its + functionality is limited. Currently there is no support for MPLS enabled VPN + services such as L3VPNs, L2VPNs, and mVPNs. RSVP support is also not present + as the underlying routing stack (FRR) does not implement it. Currently VyOS + can be configured as a label switched router (MPLS P router), in both + penultimate and ultimate hop popping operations. Label Distribution Protocol =========================== -The **Multi-Protocol Label Switching** (MPLS) architecture does not -assume a single protocol to create MPLS paths. VyOS supports the Label -Distribution Protocol (LDP) as implemented by FRR, based on `RFC 5036 `__. +The :abbr: `MPLS (Multi-Protocol Label Switching)` architecture does not assume +a single protocol to create MPLS paths. VyOS supports the Label Distribution +Protocol (LDP) as implemented by FRR, based on :rfc:`5036`. -LDP is a TCP based MPLS signaling protocol that distributes -labels creating MPLS label switched paths in a dynamic manner. -LDP is not a routing protocol, as it relies on other routing -protocols for forwarding decisions. LDP cannot bootstrap itself, -and therefore relies on said routing protocols for communication -with other routers that use LDP. +:abbr:`LDP (Label Distribution Protocol)` is a TCP based MPLS signaling protocol +that distributes labels creating MPLS label switched paths in a dynamic manner. +LDP is not a routing protocol, as it relies on other routing protocols for +forwarding decisions. LDP cannot bootstrap itself, and therefore relies on said +routing protocols for communication with other routers that use LDP. In order to allow for LDP on the local router to exchange label advertisements with other routers, a TCP session will be established between automatically @@ -49,117 +54,104 @@ session to the **transport address** of other routers. Therefore for LDP to function properly please make sure the transport address is shown in the routing table and reachable to traffic at all times. -It is highly recommended to use the same address for both the LDP router-id and the -discovery transport address, but for VyOS MPLS LDP to work both parameters must -be explicitly set in the configuration. - +It is highly recommended to use the same address for both the LDP router-id and +the discovery transport address, but for VyOS MPLS LDP to work both parameters +must be explicitly set in the configuration. Configuration Options ---------------------- - - -Use this command to enable LDP, and enable MPLS processing on the interface you define. - - .. cfgcmd:: set protocols mpls ldp interface - -Use this command to configure the IP address used as the LDP -router-id of the local device. - - .. cfgcmd:: set protocols mpls ldp router-id
+===================== -Use this command to set the IPv4 or IPv6 transport-address used by -LDP. +Use this command to enable LDP, and enable MPLS processing on the interface you +define. - .. cfgcmd:: set protocols mpls ldp discovery transport-ipv4-address - .. cfgcmd:: set protocols mpls ldp discovery transport-ipv6-address +.. cfgcmd:: set protocols mpls ldp interface -Use this command to configure authentication for LDP peers. Set the -IP address of the LDP peer and a password that should be shared in -order to become neighbors. + Use this command to configure the IP address used as the LDP router-id of the + local device. - .. cfgcmd:: set protocols mpls ldp neighbor password +.. cfgcmd:: set protocols mpls ldp router-id
-Use this command if you would like to set the discovery -hello and hold time parameters. + Use this command to set the IPv4 or IPv6 transport-address used by LDP. - .. cfgcmd:: set protocols mpls ldp discovery hello-interval - .. cfgcmd:: set protocols mpls ldp discovery hello-holdtime +.. cfgcmd:: set protocols mpls ldp discovery transport-ipv4-address +.. cfgcmd:: set protocols mpls ldp discovery transport-ipv6-address -Use this command if you would like to set the TCP session hold time -intervals. - - .. cfgcmd:: set protocols mpls ldp discovery session-ipv4-holdtime - .. cfgcmd:: set protocols mpls ldp discovery session-ipv6-holdtime + Use this command to configure authentication for LDP peers. Set the + IP address of the LDP peer and a password that should be shared in + order to become neighbors. -Use this command if you would like for the router to advertise FECs with -a label of 0 for explicit null operations. - - .. cfgcmd:: set protocols mpls ldp export ipv4 explicit-null - .. cfgcmd:: set protocols mpls ldp export ipv6 explicit-null +.. cfgcmd:: set protocols mpls ldp neighbor password + Use this command if you would like to set the discovery hello and hold time + parameters. +.. cfgcmd:: set protocols mpls ldp discovery hello-interval +.. cfgcmd:: set protocols mpls ldp discovery hello-holdtime -Sample configuration to setup LDP on VyOS ---------------------------------------------- - - .. code-block:: none - - set protocols ospf area 0 network '192.168.255.252/32' <--- Routing for loopback - set protocols ospf area 0 network '192.168.0.5/32' <--- Routing for an interface connecting to the network - set protocols ospf parameters router-id '192.168.255.252' <--- Router ID setting for OSPF - set protocols mpls ldp discovery transport-ipv4-address '192.168.255.252' <--- Transport address for LDP for TCP sessions to connect to - set protocols mpls ldp interface 'eth1' <--- Enable MPLS and LDP for an interface connecting to network - set protocols mpls ldp interface 'lo' <--- Enable MPLS and LDP on loopback for future services connectivity - set protocols mpls ldp router-id '192.168.255.252' <--- Router ID setting for LDP - set interfaces ethernet eth1 address '192.168.0.5/31' <--- Interface IP for connecting to network - set interfaces loopback lo address '192.168.255.252/32' <--- Interface loopback IP for router ID and other uses - +Use this command if you would like to set the TCP session hold time intervals. +.. cfgcmd:: set protocols mpls ldp discovery session-ipv4-holdtime +.. cfgcmd:: set protocols mpls ldp discovery session-ipv6-holdtime -Show Commands -------------- - -When LDP is working, you will be able to see label information in the -outcome of ``show ip route``. Besides that information, there are also -specific *show* commands for LDP: - -Use this command to see the Label Information Base. - - .. opcmd:: show mpls ldp binding +Use this command if you would like for the router to advertise FECs with a label +of 0 for explicit null operations. +.. cfgcmd:: set protocols mpls ldp export ipv4 explicit-null +.. cfgcmd:: set protocols mpls ldp export ipv6 explicit-null +Sample configuration to setup LDP on VyOS +----------------------------------------- -Use this command to see discovery hello information +.. code-block:: none - .. opcmd:: show mpls ldp discovery + set protocols ospf area 0 network '192.168.255.252/32' <--- Routing for loopback + set protocols ospf area 0 network '192.168.0.5/32' <--- Routing for an interface connecting to the network + set protocols ospf parameters router-id '192.168.255.252' <--- Router ID setting for OSPF + set protocols mpls ldp discovery transport-ipv4-address '192.168.255.252' <--- Transport address for LDP for TCP sessions to connect to + set protocols mpls ldp interface 'eth1' <--- Enable MPLS and LDP for an interface connecting to network + set protocols mpls ldp interface 'lo' <--- Enable MPLS and LDP on loopback for future services connectivity + set protocols mpls ldp router-id '192.168.255.252' <--- Router ID setting for LDP + set interfaces ethernet eth1 address '192.168.0.5/31' <--- Interface IP for connecting to network + set interfaces loopback lo address '192.168.255.252/32' <--- Interface loopback IP for router ID and other uses +Operational Mode Commands +========================= +When LDP is working, you will be able to see label information in the outcome +of ``show ip route``. Besides that information, there are also specific *show* +commands for LDP: -Use this command to see LDP interface information +Show +---- - .. opcmd:: show mpls ldp interface +.. opcmd:: show mpls ldp binding + Use this command to see the Label Information Base. +.. opcmd:: show mpls ldp discovery + Use this command to see discovery hello information -Use this command to see LDP neighbor information +.. opcmd:: show mpls ldp interface - .. opcmd:: show mpls ldp neighbor + Use this command to see LDP interface information +.. opcmd:: show mpls ldp neighbor + Use this command to see LDP neighbor information +.. opcmd:: show mpls ldp neighbor detail -Use this command to see detailed LDP neighbor information + Use this command to see detailed LDP neighbor information - .. opcmd:: show mpls ldp neighbor detail +Reset +----- +.. opcmd:: reset mpls ldp neighbor + Use this command to reset an LDP neighbor/TCP session that is established -Reset Commands --------------- -Use this command to reset an LDP neighbor/TCP session that is established - - .. opcmd:: reset mpls ldp neighbor +.. _`Wikipedia (MPLS)`: https://en.wikipedia.org/wiki/Multiprotocol_Label_Switching -- cgit v1.2.3 From c44aa8aeac5b3b279d2aca60e3d2bbe74565c2fe Mon Sep 17 00:00:00 2001 From: Cheeze_It Date: Mon, 19 Oct 2020 19:42:40 -0600 Subject: MPLS: fix conf-mode definitions and line breaks Moved the configuration mode commands and descriptions to fit VyOS template. --- docs/routing/mpls.rst | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) (limited to 'docs') diff --git a/docs/routing/mpls.rst b/docs/routing/mpls.rst index 0ae6094c..86221104 100644 --- a/docs/routing/mpls.rst +++ b/docs/routing/mpls.rst @@ -37,7 +37,7 @@ For more information on how MPLS label switching works, please go visit Label Distribution Protocol =========================== -The :abbr: `MPLS (Multi-Protocol Label Switching)` architecture does not assume +The :abbr:`MPLS (Multi-Protocol Label Switching)` architecture does not assume a single protocol to create MPLS paths. VyOS supports the Label Distribution Protocol (LDP) as implemented by FRR, based on :rfc:`5036`. @@ -61,44 +61,44 @@ must be explicitly set in the configuration. Configuration Options ===================== -Use this command to enable LDP, and enable MPLS processing on the interface you -define. - .. cfgcmd:: set protocols mpls ldp interface - Use this command to configure the IP address used as the LDP router-id of the - local device. + Use this command to enable LDP, and enable MPLS processing on the interface you + define. .. cfgcmd:: set protocols mpls ldp router-id
- Use this command to set the IPv4 or IPv6 transport-address used by LDP. + Use this command to configure the IP address used as the LDP router-id of the + local device. .. cfgcmd:: set protocols mpls ldp discovery transport-ipv4-address .. cfgcmd:: set protocols mpls ldp discovery transport-ipv6-address - Use this command to configure authentication for LDP peers. Set the - IP address of the LDP peer and a password that should be shared in - order to become neighbors. + Use this command to set the IPv4 or IPv6 transport-address used by LDP. .. cfgcmd:: set protocols mpls ldp neighbor password - Use this command if you would like to set the discovery hello and hold time - parameters. + Use this command to configure authentication for LDP peers. Set the + IP address of the LDP peer and a password that should be shared in + order to become neighbors. .. cfgcmd:: set protocols mpls ldp discovery hello-interval .. cfgcmd:: set protocols mpls ldp discovery hello-holdtime -Use this command if you would like to set the TCP session hold time intervals. + Use this command if you would like to set the discovery hello and hold time + parameters. .. cfgcmd:: set protocols mpls ldp discovery session-ipv4-holdtime .. cfgcmd:: set protocols mpls ldp discovery session-ipv6-holdtime -Use this command if you would like for the router to advertise FECs with a label -of 0 for explicit null operations. + Use this command if you would like to set the TCP session hold time intervals. .. cfgcmd:: set protocols mpls ldp export ipv4 explicit-null .. cfgcmd:: set protocols mpls ldp export ipv6 explicit-null + Use this command if you would like for the router to advertise FECs with a label + of 0 for explicit null operations. + Sample configuration to setup LDP on VyOS ----------------------------------------- -- cgit v1.2.3 From 439af25b06ccbf15241d430da4a0d8d0bb5fd21e Mon Sep 17 00:00:00 2001 From: Noah Spahn Date: Wed, 21 Oct 2020 22:21:34 -0700 Subject: Minor typo correction harder doesn't make sense. The intention must have been to say 'hardware'. --- docs/contributing/build-vyos.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst index c6098763..627d79d0 100644 --- a/docs/contributing/build-vyos.rst +++ b/docs/contributing/build-vyos.rst @@ -348,7 +348,7 @@ Voodoo by applying required patches from the `vyos-build/packages/linux-kernel/ patches` folder, copying our Kernel configuration ``x86_64_vyos_defconfig`` to the right location, and finally building the Debian packages. -.. note:: Building the kernel will take some time depending on the speed and quantity of your CPU/cores and disk speed. Plan on 20 minutes or even longer on lower end harder +.. note:: Building the kernel will take some time depending on the speed and quantity of your CPU/cores and disk speed. Plan on 20 minutes (or even longer) on lower end hardware. .. code-block:: none -- cgit v1.2.3 From 8295342ac1b4ba0a98d6ce36cba2713903f34bd1 Mon Sep 17 00:00:00 2001 From: Noah Spahn Date: Thu, 22 Oct 2020 12:07:04 -0700 Subject: revisions to the forking instructions main changes include a consistent reference to the branch name installing requirements before building locally an alternate method for adding a commit message --- docs/contributing/documentation.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst index 8102e9a9..2b2d3ba7 100644 --- a/docs/contributing/documentation.rst +++ b/docs/contributing/documentation.rst @@ -35,12 +35,12 @@ access to the official codebase. * Fork this project on GitHub https://github.com/vyos/vyos-documentation/fork -* Clone fork to local machine +* Clone fork to local machine, then change to that directory``$ cd vyos-documentation`` -* Change to your new local directory ``$ cd vyos-documentation`` +* Install the requirements ``$ pip install -r requirements.txt`` (or something similar) * Create new branch for your work, use a descriptive name of your work: - ``$ git checkout -b fix-vxlan-typo`` + ``$ git checkout -b `` * Make all your changes - please keep our commit rules in mind (:ref:`prepare_commit`). This mainly applies to proper commit messages @@ -61,11 +61,12 @@ access to the official codebase. unstaged files ``$ git add .``. All files added to the Git index will be part of you following Git commit. -* Commit your changes ``$ git commit -v`` - your configured editor will now ne - launched where you can type in a commit message. Again please make yourself - comfortable with out rules (:ref:`prepare_commit`). +* Commit your changes with the message, ``$ git commit -m ""`` + or use ``$ git commit -v`` to have your configured editor launched. You can + type in a commit message. Again please make yourself comfortable with out + rules (:ref:`prepare_commit`). -* Push your commits to your GitHub project: ``$ git push -u origin foo-branch`` +* Push commits to your GitHub project: ``$ git push -u origin `` * Submit pull-request. In GitHub visit the main repository and you should see a banner suggesting to make a pull request. Fill out the form and -- cgit v1.2.3 From ed9449fa4745efe46b351e467caff083e40e2d52 Mon Sep 17 00:00:00 2001 From: currite Date: Fri, 23 Oct 2020 19:31:38 +0200 Subject: qos: warning about possible IFB error --- docs/qos.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/qos.rst b/docs/qos.rst index 447780f1..6826b83c 100644 --- a/docs/qos.rst +++ b/docs/qos.rst @@ -1083,9 +1083,9 @@ parameters. .. note:: If you configure a class for **VoIP traffic**, don't give it any - *ceiling*, otherwise new VoIP calls could start when there is available - bandwidth and get suddenly dropped when other classes start using - their bandwidth. + *ceiling*, otherwise new VoIP calls could start when the link is + available and get suddenly dropped when other classes start using + their assigned *bandwidth* share. Example @@ -1182,7 +1182,12 @@ That is how it is possible to do the so-called "ingress shaping". set interfaces input ifb0 traffic-policy out MY-INGRESS-SHAPING set interfaces ethernet eth0 redirect ifb0 +.. warning:: + Do not configure IFB as the first step. First create everything else + of your traffic-policy, and then you can configure IFB. + Otherwise you might get the ``RTNETLINK answer: File exists`` error, + which can be solved with ``sudo ip link delete ifb0``. .. _that can give you a great deal of flexibility: https://blog.vyos.io/using-the-policy-route-and-packet-marking-for-custom-qos-matches -- cgit v1.2.3 From 5f0d33af1a5f709314c046b6dee40a63353f4363 Mon Sep 17 00:00:00 2001 From: Cédric Jeanneret Date: Mon, 26 Oct 2020 19:28:17 +0100 Subject: Correct the scp URI A standard `scp` call implies a ":" between the remote host and the remote path. Let's reflect it in the doc to avoid any confusion. --- docs/configuration-overview.rst | 6 +++--- docs/system/user-management.rst | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/configuration-overview.rst b/docs/configuration-overview.rst index 71bfc360..5658cdbb 100644 --- a/docs/configuration-overview.rst +++ b/docs/configuration-overview.rst @@ -320,7 +320,7 @@ different levels in the hierarchy. Possible completions: Save to system config file Save to file on local machine - scp://:@/ Save to file on remote 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 @@ -659,7 +659,7 @@ be ``config.boot-hostname.YYYYMMDD_HHMMSS``. Specify remote location of commit archive as any of the below :abbr:`URI (Uniform Resource Identifier)` - * ``scp://:@/`` + * ``scp://:@:/`` * ``sftp://:@/`` * ``ftp://:@/`` * ``tftp:///`` @@ -699,7 +699,7 @@ to load it with the ``load`` command: Possible completions: Load from system config file Load from file on local machine - scp://:@/ Load from file on remote machine + scp://:@:/ Load from file on remote machine sftp://:@/ Load from file on remote machine ftp://:@/ Load from file on remote machine http:/// Load from file on remote machine diff --git a/docs/system/user-management.rst b/docs/system/user-management.rst index d3dcc378..6d89735f 100644 --- a/docs/system/user-management.rst +++ b/docs/system/user-management.rst @@ -78,7 +78,7 @@ The third part is simply an identifier, and is for your own reference. using one of the following :abbr:`URIs (Uniform Resource Identifier)`: * ```` - Load from file on local filesystem path - * ``scp://@/`` - Load via SCP from remote machine + * ``scp://@:/`` - Load via SCP from remote machine * ``sftp://@/`` - Load via SFTP from remote machine * ``ftp://@/`` - Load via FTP from remote machine * ``http:///`` - Load via HTTP from remote machine -- cgit v1.2.3 From 8c401562a8e7a928d2efa88f66ee8e186cd7fe1f Mon Sep 17 00:00:00 2001 From: currite Date: Wed, 28 Oct 2020 10:48:59 +0100 Subject: ipoe-server: fix hierarchy tree --- docs/services/ipoe-server.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/services/ipoe-server.rst b/docs/services/ipoe-server.rst index 96c96527..3aedf966 100644 --- a/docs/services/ipoe-server.rst +++ b/docs/services/ipoe-server.rst @@ -119,13 +119,13 @@ example configuration can be used. set service ipoe-server authentication radius-server 10.100.100.1 secret 'password' Bandwidth Shaping -^^^^^^^^^^^^^^^^^ +================= Bandwidth rate limits can be set for local users within the configuration or via RADIUS based attributes. Bandwidth Shaping for local users -================================= +--------------------------------- The rate-limit is set in kbit/sec. -- cgit v1.2.3 From 5b2cde1eaa46968a32e1c84bc9dd4b239b0020b6 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Wed, 28 Oct 2020 20:06:06 +0100 Subject: routing: adjust chapter headers --- docs/routing/index.rst | 2 +- docs/routing/mss-clamp.rst | 13 ++++----- docs/routing/multicast.rst | 15 +++++----- docs/routing/ospf.rst | 7 +++-- docs/routing/pbr.rst | 7 +++-- docs/routing/policy.rst | 65 +++++++++++++++++++++++++++++++++++++++++ docs/routing/rip.rst | 3 +- docs/routing/routing-policy.rst | 60 ------------------------------------- 8 files changed, 89 insertions(+), 83 deletions(-) create mode 100644 docs/routing/policy.rst delete mode 100644 docs/routing/routing-policy.rst (limited to 'docs') diff --git a/docs/routing/index.rst b/docs/routing/index.rst index a34bbfac..7988b230 100644 --- a/docs/routing/index.rst +++ b/docs/routing/index.rst @@ -16,6 +16,6 @@ Routing ospf pbr rip - routing-policy + policy rpki static diff --git a/docs/routing/mss-clamp.rst b/docs/routing/mss-clamp.rst index a4edf1c6..3fdd1153 100644 --- a/docs/routing/mss-clamp.rst +++ b/docs/routing/mss-clamp.rst @@ -1,7 +1,8 @@ .. _routing-mss-clamp: +################ TCP-MSS Clamping ----------------- +################ As Internet wide PMTU discovery rarely works, we sometimes need to clamp our TCP MSS value to a specific value. This is a field in the TCP @@ -18,16 +19,15 @@ value for IPv4 and IPv6. IPv4 -^^^^ +==== .. cfgcmd:: set firewall options interface adjust-mss Use this command to set the maximum segment size for IPv4 transit packets on a specific interface (500-1460 bytes). - Example -""""""" +------- Clamp outgoing MSS value in a TCP SYN packet to `1452` for `pppoe0` and `1372` @@ -39,16 +39,15 @@ for your WireGuard `wg02` tunnel. set firewall options interface wg02 adjust-mss '1372' IPv6 -^^^^^ +==== .. cfgcmd:: set firewall options interface adjust-mss6 Use this command to set the maximum segment size for IPv6 transit packets on a specific interface (1280-1492 bytes). - Example -""""""" +------- Clamp outgoing MSS value in a TCP SYN packet to `1280` for both `pppoe0` and `wg02` interface. diff --git a/docs/routing/multicast.rst b/docs/routing/multicast.rst index d20d8e31..9104b0c9 100644 --- a/docs/routing/multicast.rst +++ b/docs/routing/multicast.rst @@ -7,7 +7,6 @@ Multicast VyOS facilitates IP Multicast by supporting **PIM Sparse Mode**, **IGMP** and **IGMP-Proxy**. - ************ PIM and IGMP ************ @@ -16,7 +15,7 @@ PIM (Protocol Independent Multicast) must be configured in every interface of every participating router. Every router must also have the location of the Rendevouz Point manually configured. Then, unidirectional shared trees rooted at the Rendevouz Point will -automatically be built for multicast distribution. +automatically be built for multicast distribution. Traffic from multicast sources will go to the Rendezvous Point, and receivers will pull it from a shared tree using IGMP (Internet Group @@ -24,7 +23,7 @@ Management Protocol). Multicast receivers will talk IGMP to their local router, so, besides having PIM configured in every router, IGMP must also be configured in -any router where there could be a multicast receiver locally connected. +any router where there could be a multicast receiver locally connected. VyOS supports both IGMP version 2 and version 3 (which allows source-specific multicast). @@ -54,7 +53,7 @@ In the following example we can see a basic multicast setup: set protocols pim interface eth1 set protocols pim interface eth2 set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' - + **Router 3** .. code-block:: none @@ -69,7 +68,7 @@ In the following example we can see a basic multicast setup: set protocols pim interface eth0 set protocols pim interface eth1 set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' - + **Router 2** .. code-block:: none @@ -81,7 +80,7 @@ In the following example we can see a basic multicast setup: set protocols pim interface eth1 set protocols pim interface eth2 set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' - + @@ -103,7 +102,7 @@ These are the commands for a basic setup. that join messages can be sent there. Set the Rendevouz Point address and the matching prefix of group ranges covered. These values must be shared with every router participating in the PIM network. - + .. cfgcmd:: set protocols igmp interface eth1 @@ -163,7 +162,7 @@ You can also tune multicast with the following commands. timed out. -.. cfgcmd:: set protocols igmp interface version +.. cfgcmd:: set protocols igmp interface version Use this command to define in the selected interface whether you choose IGMP version 2 or 3. The default value is 3. diff --git a/docs/routing/ospf.rst b/docs/routing/ospf.rst index fbe8984f..fe05178b 100644 --- a/docs/routing/ospf.rst +++ b/docs/routing/ospf.rst @@ -2,8 +2,9 @@ .. _routing-ospf: +#### OSPF ----- +#### :abbr:`OSPF (Open Shortest Path First)` is a routing protocol for Internet Protocol (IP) networks. It uses a link state routing (LSR) algorithm and falls @@ -16,7 +17,7 @@ addressing model. OSPF is a widely used IGP in large enterprise networks. OSPFv2 (IPv4) -^^^^^^^^^^^^^ +############# In order to have a VyOS system exchanging routes with OSPF neighbors, you will at least need to configure an OSPF area and some network. @@ -68,7 +69,7 @@ address and the node 1 sending the default route: set policy route-map CONNECT rule 10 match interface lo OSPFv3 (IPv6) -^^^^^^^^^^^^^ +############# A typical configuration using 2 nodes. diff --git a/docs/routing/pbr.rst b/docs/routing/pbr.rst index 797f79e3..2a1a56bc 100644 --- a/docs/routing/pbr.rst +++ b/docs/routing/pbr.rst @@ -2,8 +2,9 @@ .. _routing-pbr: +### PBR ---- +### :abbr:`PBR (Policy-Based Routing)` allowing traffic to be assigned to different routing tables. Traffic can be matched using standard 5-tuple @@ -11,7 +12,7 @@ matching (source address, destination address, protocol, source port, destination port). Transparent Proxy -^^^^^^^^^^^^^^^^^ +================= The following example will show how VyOS can be used to redirect web traffic to an external transparent proxy: @@ -45,7 +46,7 @@ interface, we use: Multiple Uplinks -^^^^^^^^^^^^^^^^ +================ VyOS Policy-Based Routing (PBR) works by matching source IP address ranges and forwarding the traffic using different routing tables. diff --git a/docs/routing/policy.rst b/docs/routing/policy.rst new file mode 100644 index 00000000..4eeb40d6 --- /dev/null +++ b/docs/routing/policy.rst @@ -0,0 +1,65 @@ +.. include:: ../_include/need_improvement.txt + +###### +Policy +###### + +Routing Policies could be used to tell the router (self or neighbors) what +routes and their attributes needs to be put into the routing table. + +There could be a wide range of routing policies. Some examples are below: + +* Set some metric to routes learned from a particular neighbor +* Set some attributes (like AS PATH or Community value) to advertised routes to neighbors +* Prefer a specific routing protocol routes over another routing protocol running on the same router + +Example +======= + +**Policy definition:** + +.. code-block:: none + + # Create policy + set policy route-map setmet rule 2 action 'permit' + set policy route-map setmet rule 2 set as-path-prepend '2 2 2' + + # Apply policy to BGP + set protocols bgp 1 neighbor 203.0.113.2 address-family ipv4-unicast route-map import 'setmet' + set protocols bgp 1 neighbor 203.0.113.2 address-family ipv4-unicast soft-reconfiguration 'inbound' + +Using 'soft-reconfiguration' we get the policy update without bouncing the +neighbor. + +**Routes learned before routing policy applied:** + +.. code-block:: none + + vyos@vos1:~$ show ip bgp + BGP table version is 0, local router ID is 192.168.56.101 + Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, + r RIB-failure, S Stale, R Removed + Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path + *> 198.51.100.3/32 203.0.113.2 1 0 2 i < Path + + Total number of prefixes 1 + +**Routes learned after routing policy applied:** + +.. code-block:: none + + vyos@vos1:~$ sho ip b + BGP table version is 0, local router ID is 192.168.56.101 + Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, + r RIB-failure, S Stale, R Removed + Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path + *> 198.51.100.3/32 203.0.113.2 1 0 2 2 2 2 i + + Total number of prefixes 1 + vyos@vos1:~$ + +You now see the longer AS path. diff --git a/docs/routing/rip.rst b/docs/routing/rip.rst index 9cf4f289..68868e37 100644 --- a/docs/routing/rip.rst +++ b/docs/routing/rip.rst @@ -2,8 +2,9 @@ .. _rip: +### RIP ---- +### :abbr:`RIP (Routing Information Protocol)` is a widely deployed interior gateway protocol. RIP was developed in the 1970s at Xerox Labs as part of the XNS diff --git a/docs/routing/routing-policy.rst b/docs/routing/routing-policy.rst deleted file mode 100644 index 461e42d8..00000000 --- a/docs/routing/routing-policy.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. include:: ../_include/need_improvement.txt - -Routing-policy --------------- - -Routing Policies could be used to tell the router (self or neighbors) what routes and their attributes needs to be put into the routing table. - -There could be a wide range of routing policies. Some examples are below: - - * Set some metric to routes learned from a particular neighbor - * Set some attributes (like AS PATH or Community value) to advertised routes to neighbors - * Prefer a specific routing protocol routes over another routing protocol running on the same router - -Routing Policy Example -~~~~~~~~~~~~~~~~~~~~~~ - -**Policy definition:** - -.. code-block:: none - - #Create policy - set policy route-map setmet rule 2 action 'permit' - set policy route-map setmet rule 2 set as-path-prepend '2 2 2' - - #Apply policy to BGP - set protocols bgp 1 neighbor 203.0.113.2 address-family ipv4-unicast route-map import 'setmet' - set protocols bgp 1 neighbor 203.0.113.2 address-family ipv4-unicast soft-reconfiguration 'inbound' <<<< *** - - *** get policy update without bouncing the neighbor - -**Routes learned before routing policy applied:** - -.. code-block:: none - - vyos@vos1:~$ show ip bgp - BGP table version is 0, local router ID is 192.168.56.101 - Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, - r RIB-failure, S Stale, R Removed - Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path - *> 198.51.100.3/32 203.0.113.2 1 0 2 i < Path - - Total number of prefixes 1 - -**Routes learned after routing policy applied:** - -.. code-block:: none - - vyos@vos1:~$ sho ip b - BGP table version is 0, local router ID is 192.168.56.101 - Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, - r RIB-failure, S Stale, R Removed - Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path - *> 198.51.100.3/32 203.0.113.2 1 0 2 2 2 2 i < longer AS_path length - - Total number of prefixes 1 - vyos@vos1:~$ -- cgit v1.2.3 From d8cae2006095d55bcd7e4e1fcecf325da30f8420 Mon Sep 17 00:00:00 2001 From: currite Date: Wed, 28 Oct 2020 20:57:10 +0100 Subject: openvpn: add troubleshooting subsection --- docs/vpn/openvpn.rst | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) (limited to 'docs') diff --git a/docs/vpn/openvpn.rst b/docs/vpn/openvpn.rst index fd6a3a71..b9f5433b 100644 --- a/docs/vpn/openvpn.rst +++ b/docs/vpn/openvpn.rst @@ -542,4 +542,43 @@ Will add ``push "keepalive 1 10"`` to the generated OpenVPN config file. quotes. This is done through a hack on our config generator. You can pass quotes using the ``"`` statement. + +Troubleshooting +=============== + +VyOS provides some operational commands on OpenVPN. + +Check status +------------ + +The following commands let you check tunnel status. + +.. opcmd:: show openvpn client + + Use this command to check the tunnel status for OpenVPN client interfaces. + +.. opcmd:: show openvpn server + + Use this command to check the tunnel status for OpenVPN server interfaces. + +.. opcmd:: show openvpn site-to-site + + Use this command to check the tunnel status for OpenVPN site-to-site interfaces. + + +Reset OpenVPN +------------- + +The following commands let you reset OpenVPN for a specific client or interface. + +.. opcmd:: reset openvpn client + + Use this command to reset specified OpenVPN client. + +.. opcmd:: reset openvpn interface + + Uset this command to reset the OpenVPN process on a specific interface. + + + .. include:: ../common-references.rst -- cgit v1.2.3 From bf45f93b030284029014cba99b722253a29ccd6b Mon Sep 17 00:00:00 2001 From: currite <53279076+currite@users.noreply.github.com> Date: Wed, 28 Oct 2020 21:25:01 +0100 Subject: Update openvpn.rst --- docs/vpn/openvpn.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/vpn/openvpn.rst b/docs/vpn/openvpn.rst index b9f5433b..c6934335 100644 --- a/docs/vpn/openvpn.rst +++ b/docs/vpn/openvpn.rst @@ -569,7 +569,7 @@ The following commands let you check tunnel status. Reset OpenVPN ------------- -The following commands let you reset OpenVPN for a specific client or interface. +The following commands let you reset OpenVPN. .. opcmd:: reset openvpn client -- cgit v1.2.3 From ed86dcfe5f14169f98b78d74e81220ce30e8b8de Mon Sep 17 00:00:00 2001 From: currite Date: Mon, 2 Nov 2020 13:37:53 +0100 Subject: routing/ip-commands: add a collection of IPv4 and IPv6 commands missing in the manual. --- docs/routing/index.rst | 1 + docs/routing/ip-commands.rst | 277 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 278 insertions(+) create mode 100644 docs/routing/ip-commands.rst (limited to 'docs') diff --git a/docs/routing/index.rst b/docs/routing/index.rst index a34bbfac..53a8a6ce 100644 --- a/docs/routing/index.rst +++ b/docs/routing/index.rst @@ -13,6 +13,7 @@ Routing mpls mss-clamp multicast + ip-commands ospf pbr rip diff --git a/docs/routing/ip-commands.rst b/docs/routing/ip-commands.rst new file mode 100644 index 00000000..fbfe2d24 --- /dev/null +++ b/docs/routing/ip-commands.rst @@ -0,0 +1,277 @@ +.. _ip-commands: + +*********** +IP commands +*********** + + +IPv4 +==== + +System configuration commands +----------------------------- + + +.. cfgcmd:: set system ip disable-forwarding + + Use this command to disable IPv4 forwarding on all interfaces. + + +.. cfgcmd:: set system ip arp table-size + + Use this command to define the maximum number of entries to keep in + the ARP cache (1024, 2048, 4096, 8192, 16384, 32768). + + +.. cfgcmd:: set system ip multipath layer4-hashing + + Use this command to use Layer 4 information for IPv4 ECMP hashing. + + +Operational commands +-------------------- + + +show commands +^^^^^^^^^^^^^ + +See below the different parameters available for the IPv4 **show** command: + +.. code-block:: + + vyos@vyos:~$ show ip + Possible completions: + access-list Show all IP access-lists + as-path-access-list + Show all as-path-access-lists + bgp Show Border Gateway Protocol (BGP) information + community-list + Show IP community-lists + extcommunity-list + Show extended IP community-lists + forwarding Show IP forwarding status + groups Show IP multicast group membership + igmp Show IGMP (Internet Group Management Protocol) information + large-community-list + Show IP large-community-lists + multicast Show IP multicast + ospf Show IPv4 Open Shortest Path First (OSPF) routing information + pim Show PIM (Protocol Independent Multicast) information + ports Show IP ports in use by various system services + prefix-list Show all IP prefix-lists + protocol Show IP route-maps per protocol + rip Show Routing Information Protocol (RIP) information + route Show IP routes + + +reset commands +^^^^^^^^^^^^^^ + +And the different IPv4 **reset** commands available: + +.. code-block:: + + vyos@vyos:~$ reset ip + Possible completions: + arp Reset Address Resolution Protocol (ARP) cache + bgp Clear Border Gateway Protocol (BGP) statistics or status + igmp IGMP clear commands + multicast IP multicast routing table + route Reset IP route + + +IPv6 +==== + +System configuration commands +----------------------------- + +.. cfgcmd:: set system ipv6 disable + + Use this command to disable assignment of IPv6 addresses on all + interfaces. + + +.. cfgcmd:: set system ipv6 disable-forwarding + + Use this command to disable IPv6 forwarding on all interfaces. + + +.. cfgcmd:: set system ipv6 neighbor table-size + + Use this command to define the maximum number of entries to keep in + the Neighbor cache (1024, 2048, 4096, 8192, 16384, 32768). + + +.. cfgcmd:: set system ipv6 strict-dad + + Use this command to disable IPv6 operation on interface when + Duplicate Address Detection fails on Link-Local address. + + +.. cfgcmd:: set system ipv6 multipath layer4-hashing + + Use this command to user Layer 4 information for ECMP hashing. + + + +Operational commands +-------------------- + +Show commands +^^^^^^^^^^^^^ + + +.. opcmd:: show ipv6 neighbors + + Use this command to show IPv6 Neighbor Discovery Protocol information. + + +.. opcmd:: show ipv6 groups + + Use this command to show IPv6 multicast group membership. + + +.. opcmd:: show ipv6 forwarding + + Use this command to show IPv6 forwarding status. + +.. opcmd:: show ipv6 route + + Use this command to show IPv6 routes. + + + Check the many parameters available for the `show ipv6 route` command: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 route + Possible completions: + Execute the current command + Show IPv6 routes of given address or prefix + + bgp Show IPv6 BGP routes + cache Show kernel IPv6 route cache + connected Show IPv6 connected routes + forward Show kernel IPv6 route table + isis Show IPv6 ISIS routes + kernel Show IPv6 kernel routes + ospfv3 Show IPv6 OSPF6 routes + ripng Show IPv6 RIPNG routes + static Show IPv6 static routes + summary Show IPv6 routes summary + table Show IP routes in policy table + vrf Show IPv6 routes in VRF + + +.. opcmd:: show ipv6 prefix-list + + Use this command to show all IPv6 prefix lists + + There are different parameters for getting prefix-list information: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 prefix-list + Possible completions: + Execute the current command + Show specified IPv6 prefix-list + detail Show detail of IPv6 prefix-lists + summary Show summary of IPv6 prefix-lists + +.. opcmd:: show ipv6 access-list + + Use this command to show all IPv6 access lists + + You can also specify which IPv6 access-list should be shown: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 access-list + Possible completions: + Execute the current command + Show specified IPv6 access-list + + + +.. opcmd:: show ipv6 bgp + + Use this command to show IPv6 Border Gateway Protocol information. + + + In addition, you can specify many other parameters to get BGP + information: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 bgp + Possible completions: + Execute the current command + Show BGP information for given address or prefix + + community Show routes matching the communities + community-list + Show routes matching the community-list + filter-list Show routes conforming to the filter-list + large-community + Show routes matching the large-community-list + large-community-list + neighbors Show detailed information on TCP and BGP neighbor connections + prefix-list Show routes matching the prefix-list + regexp Show routes matching the AS path regular expression + route-map Show BGP routes matching the specified route map + summary Show summary of BGP neighbor status + + +.. opcmd:: show ipv6 ospfv3 + + Use this command to get information about OSPFv3. + + You can get more specific OSPFv3 information by using the parameters + shown below: + + .. code-block:: + + vyos@vyos:~$ show ipv6 ospfv3 + Possible completions: + Execute the current command + area Show OSPFv3 spf-tree information + border-routers + Show OSPFv3 border-router (ABR and ASBR) information + database Show OSPFv3 Link state database information + interface Show OSPFv3 interface information + linkstate Show OSPFv3 linkstate routing information + neighbor Show OSPFv3 neighbor information + redistribute Show OSPFv3 redistribute External information + route Show OSPFv3 routing table information + +.. opcmd:: show ipv6 ripng + + Use this command to get information about the RIPNG protocol + +.. opcmd:: show ipv6 ripng status + + Use this command to show the status of the RIPNG protocol + + + +Reset commands +^^^^^^^^^^^^^^ + +.. opcmd:: reset ipv6 bgp
+ + Use this command to clear Border Gateway Protocol statistics or + status. + + +.. opcmd:: reset ipv6 neighbors
+ + Use this command to reset IPv6 Neighbor Discovery Protocol cache for + an address or interface. + +.. opcmd:: reset ipv6 route cache + + Use this command to flush the kernel IPv6 route cache. + An address can be added to flush it only for that route. + + -- cgit v1.2.3 From 168247e76ad1b03e4d1dab2631ee970afeb74549 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Tue, 3 Nov 2020 17:04:57 +0100 Subject: ip-commands: add "none" on code-block directives --- docs/routing/ip-commands.rst | 63 ++++++++++++++++---------------------------- 1 file changed, 22 insertions(+), 41 deletions(-) (limited to 'docs') diff --git a/docs/routing/ip-commands.rst b/docs/routing/ip-commands.rst index fbfe2d24..eba4fd90 100644 --- a/docs/routing/ip-commands.rst +++ b/docs/routing/ip-commands.rst @@ -1,9 +1,8 @@ .. _ip-commands: -*********** +########### IP commands -*********** - +########### IPv4 ==== @@ -11,18 +10,15 @@ IPv4 System configuration commands ----------------------------- - .. cfgcmd:: set system ip disable-forwarding Use this command to disable IPv4 forwarding on all interfaces. - .. cfgcmd:: set system ip arp table-size Use this command to define the maximum number of entries to keep in the ARP cache (1024, 2048, 4096, 8192, 16384, 32768). - .. cfgcmd:: set system ip multipath layer4-hashing Use this command to use Layer 4 information for IPv4 ECMP hashing. @@ -31,13 +27,12 @@ System configuration commands Operational commands -------------------- - show commands ^^^^^^^^^^^^^ See below the different parameters available for the IPv4 **show** command: -.. code-block:: +.. code-block:: none vyos@vyos:~$ show ip Possible completions: @@ -62,23 +57,22 @@ See below the different parameters available for the IPv4 **show** command: protocol Show IP route-maps per protocol rip Show Routing Information Protocol (RIP) information route Show IP routes - + reset commands ^^^^^^^^^^^^^^ And the different IPv4 **reset** commands available: -.. code-block:: +.. code-block:: none - vyos@vyos:~$ reset ip + vyos@vyos:~$ reset ip Possible completions: arp Reset Address Resolution Protocol (ARP) cache bgp Clear Border Gateway Protocol (BGP) statistics or status igmp IGMP clear commands multicast IP multicast routing table route Reset IP route - IPv6 ==== @@ -91,61 +85,52 @@ System configuration commands Use this command to disable assignment of IPv6 addresses on all interfaces. - .. cfgcmd:: set system ipv6 disable-forwarding Use this command to disable IPv6 forwarding on all interfaces. - .. cfgcmd:: set system ipv6 neighbor table-size Use this command to define the maximum number of entries to keep in the Neighbor cache (1024, 2048, 4096, 8192, 16384, 32768). - .. cfgcmd:: set system ipv6 strict-dad Use this command to disable IPv6 operation on interface when Duplicate Address Detection fails on Link-Local address. - .. cfgcmd:: set system ipv6 multipath layer4-hashing Use this command to user Layer 4 information for ECMP hashing. - Operational commands -------------------- Show commands ^^^^^^^^^^^^^ - .. opcmd:: show ipv6 neighbors Use this command to show IPv6 Neighbor Discovery Protocol information. - .. opcmd:: show ipv6 groups Use this command to show IPv6 multicast group membership. - .. opcmd:: show ipv6 forwarding - + Use this command to show IPv6 forwarding status. .. opcmd:: show ipv6 route Use this command to show IPv6 routes. - Check the many parameters available for the `show ipv6 route` command: .. code-block:: none - vyos@vyos:~$ show ipv6 route + vyos@vyos:~$ show ipv6 route Possible completions: Execute the current command Show IPv6 routes of given address or prefix @@ -162,7 +147,7 @@ Show commands summary Show IPv6 routes summary table Show IP routes in policy table vrf Show IPv6 routes in VRF - + .. opcmd:: show ipv6 prefix-list @@ -172,13 +157,13 @@ Show commands .. code-block:: none - vyos@vyos:~$ show ipv6 prefix-list + vyos@vyos:~$ show ipv6 prefix-list Possible completions: Execute the current command Show specified IPv6 prefix-list detail Show detail of IPv6 prefix-lists summary Show summary of IPv6 prefix-lists - + .. opcmd:: show ipv6 access-list Use this command to show all IPv6 access lists @@ -187,12 +172,10 @@ Show commands .. code-block:: none - vyos@vyos:~$ show ipv6 access-list + vyos@vyos:~$ show ipv6 access-list Possible completions: Execute the current command Show specified IPv6 access-list - - .. opcmd:: show ipv6 bgp @@ -203,8 +186,8 @@ Show commands information: .. code-block:: none - - vyos@vyos:~$ show ipv6 bgp + + vyos@vyos:~$ show ipv6 bgp Possible completions: Execute the current command Show BGP information for given address or prefix @@ -221,7 +204,7 @@ Show commands regexp Show routes matching the AS path regular expression route-map Show BGP routes matching the specified route map summary Show summary of BGP neighbor status - + .. opcmd:: show ipv6 ospfv3 @@ -229,10 +212,10 @@ Show commands You can get more specific OSPFv3 information by using the parameters shown below: - - .. code-block:: - - vyos@vyos:~$ show ipv6 ospfv3 + + .. code-block:: none + + vyos@vyos:~$ show ipv6 ospfv3 Possible completions: Execute the current command area Show OSPFv3 spf-tree information @@ -244,7 +227,7 @@ Show commands neighbor Show OSPFv3 neighbor information redistribute Show OSPFv3 redistribute External information route Show OSPFv3 routing table information - + .. opcmd:: show ipv6 ripng Use this command to get information about the RIPNG protocol @@ -254,7 +237,6 @@ Show commands Use this command to show the status of the RIPNG protocol - Reset commands ^^^^^^^^^^^^^^ @@ -266,12 +248,11 @@ Reset commands .. opcmd:: reset ipv6 neighbors
- Use this command to reset IPv6 Neighbor Discovery Protocol cache for + Use this command to reset IPv6 Neighbor Discovery Protocol cache for an address or interface. .. opcmd:: reset ipv6 route cache Use this command to flush the kernel IPv6 route cache. - An address can be added to flush it only for that route. - + An address can be added to flush it only for that route. -- cgit v1.2.3 From be51e864e7559a71885d5bc7900df3b991366999 Mon Sep 17 00:00:00 2001 From: Tim Harman Date: Wed, 4 Nov 2020 16:42:00 +1300 Subject: Update conntrack.rst to document Unicast sync Make it clear that it's possible to use the "peer" statement after the interface command, to enable UDP mode instead of Multicast mode. --- docs/services/conntrack.rst | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/services/conntrack.rst b/docs/services/conntrack.rst index 90f062e8..c361d293 100644 --- a/docs/services/conntrack.rst +++ b/docs/services/conntrack.rst @@ -26,6 +26,12 @@ tunnels it can be their tunnel ID, but otherwise is just zero, as if it were not part of the tuple. To be able to inspect the TCP port in all cases, packets will be mandatorily defragmented. +It is possible to use either Multicast or Unicast to sync conntrack traffic. +Most examples below show Multicast, but unicast can be specified by using the +"peer" keywork after the specificed interface, as in the following example: + +set service conntrack-sync interface eth0 peer 192.168.0.250 + Configuration ^^^^^^^^^^^^^ @@ -51,9 +57,12 @@ Configuration # Interface to use for syncing conntrack entries [REQUIRED] set service conntrack-sync interface - + # Multicast group to use for syncing conntrack entries set service conntrack-sync mcast-group + + # Peer to send Unicast UDP conntrack sync entires to, if not using Multicast above + set service conntrack-sync interface peer # Queue size for syncing conntrack entries (in MB) set service conntrack-sync sync-queue-size -- cgit v1.2.3 From a31185f89520300ae370e76bd72634d0239e505c Mon Sep 17 00:00:00 2001 From: currite Date: Wed, 4 Nov 2020 18:09:17 +0100 Subject: wan-load-balancing: add wiki image for sticky connections --- docs/_static/images/sticky-connections.jpg | Bin 0 -> 22252 bytes docs/load-balancing.rst | 6 ++++++ 2 files changed, 6 insertions(+) create mode 100644 docs/_static/images/sticky-connections.jpg (limited to 'docs') diff --git a/docs/_static/images/sticky-connections.jpg b/docs/_static/images/sticky-connections.jpg new file mode 100644 index 00000000..25fd72a9 Binary files /dev/null and b/docs/_static/images/sticky-connections.jpg differ diff --git a/docs/load-balancing.rst b/docs/load-balancing.rst index 07c18217..6b0bede9 100644 --- a/docs/load-balancing.rst +++ b/docs/load-balancing.rst @@ -159,6 +159,12 @@ This works through automatically generated source NAT (SNAT) rules, these rules Sticky Connections ------------------ +Inbound connections to a WAN interface can be improperly handled when the reply is sent back to the client. + +.. image:: /_static/images/sticky-connections.jpg + :width: 80% + :align: center + Upon reception of an incoming packet, when a response is sent, it might be desired to ensure that it leaves from the same interface as the inbound one. This can be achieved by enabling sticky connections in the load balancing: -- cgit v1.2.3 From 486c35233d0969d1d898c8da783d43999be560d4 Mon Sep 17 00:00:00 2001 From: currite Date: Wed, 4 Nov 2020 21:16:38 +0100 Subject: advanced-system: boot options (migrated from old wiki) The following options have not been migrated because we did not find its valid and correct use: no-vyos-configure Do not load the config, leaves you with plain Linux system. no-vyos-rl-system Disables getting the system into clean state before loading the config. --- docs/_static/images/boot-options.png | Bin 0 -> 30582 bytes docs/system/advanced-index.rst | 1 + docs/system/boot-options.rst | 57 +++++++++++++++++++++++++++++++++++ docs/troubleshooting.rst | 2 ++ 4 files changed, 60 insertions(+) create mode 100644 docs/_static/images/boot-options.png create mode 100644 docs/system/boot-options.rst (limited to 'docs') diff --git a/docs/_static/images/boot-options.png b/docs/_static/images/boot-options.png new file mode 100644 index 00000000..b00350bc Binary files /dev/null and b/docs/_static/images/boot-options.png differ diff --git a/docs/system/advanced-index.rst b/docs/system/advanced-index.rst index 36469763..4e9c5699 100644 --- a/docs/system/advanced-index.rst +++ b/docs/system/advanced-index.rst @@ -11,6 +11,7 @@ Advanced System Tweaks flow-accounting ntp options + boot-options proxy serial-console syslog diff --git a/docs/system/boot-options.rst b/docs/system/boot-options.rst new file mode 100644 index 00000000..d054748f --- /dev/null +++ b/docs/system/boot-options.rst @@ -0,0 +1,57 @@ +.. _boot-options: + + +############ +Boot Options +############ + +.. warning:: This function may be highly disruptive. + It may cause major service interruption, so make sure you really + need it and verify your input carefully. + + + +VyOS has several kernel command line options to modify the normal boot +process. +To add an option, select the desired image in GRUB menu at load +time, press **e**, edit the first line, and press **Ctrl-x** to boot when +ready. + +.. image:: /_static/images/boot-options.png + :width: 80% + :align: center + + +Specify custom config file +========================== + +Tells the system to use specified file instead of ``/config/config.boot``. +If specified file does not exist or is not readable, fall back to +default config. No additional verification is performed, so make sure +you specify a valid config file. + +.. code-block:: none + + vyos-config=/path/to/file + +To load the *factory default* config, use: + +.. code-block:: none + + vyos-config=/opt/vyatta/etc/config.boot.default + + +Disable specific boot process steps +=================================== + +These options disable some boot steps. Make sure you understand the +:ref:`boot process ` well before using them! + +.. glossary:: + + no-vyos-migrate + Do not perform config migration. + + no-vyos-firewall + Do not initialize default firewall chains, renders any firewall configuration unusable. + diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index 23248507..2d6532d0 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -362,6 +362,8 @@ to clear counters on firewall rulesets or single rules System Information ****************** +.. _boot-steps: + Boot Steps ========== -- cgit v1.2.3 From 7e35e645268e95e592d47e0450aa07eb8395eb84 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Thu, 5 Nov 2020 13:12:49 +0100 Subject: interfaces: add IPv6 DHCPv6-PD documentation for PPPoE and Ethernet --- docs/interfaces/ethernet.rst | 38 ++++++++++++++++++++++++++++++++++++++ docs/interfaces/pppoe.rst | 28 ++++++++++++++-------------- 2 files changed, 52 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/interfaces/ethernet.rst b/docs/interfaces/ethernet.rst index 0633ad2c..95aef851 100644 --- a/docs/interfaces/ethernet.rst +++ b/docs/interfaces/ethernet.rst @@ -95,6 +95,44 @@ Link Administration Configure :abbr:`MTU (Maximum Transmission Unit)` on given ``. It is the size (in bytes) of the largest ethernet frame sent on this link. +Prefix Delegation (DHCPv6-PD) +----------------------------- + +VyOS 1.3 (equuleus) supports DHCPv6-PD. DHCPv6 Prefix Delegation is supported +by most ISPs who provide native IPv6 for consumers on fixed networks. + +.. cfgcmd:: set interfaces ethernet dhcpv6-option pd length + + Some ISPs by default only delegate a /64 prefix. To request for a specific + prefix size use this option to request for a bigger delegation for this pd + ``. This value + is in the range from 32 - 64 so you could request up to /32 down to a /64 + delegation. + + Default value is 64. + +.. cfgcmd:: set interfaces ethernet dhcpv6-option pd interface address
+ + Specify the interface address used locally on the interfcae where the prefix + has been delegated to. ID must be a decimal integer. + + It will be combined with the delegated prefix and the sla-id to form a complete + interface address. The default is to use the EUI-64 address of the interface. + + Example: + + Using ```` value 65535 will assign IPv6 address ``::ffff`` to the + interface. + +.. cfgcmd:: set interfaces ethernet dhcpv6-option pd interface sla-id + + Specify the identifier value of the site-level aggregator (SLA) on the + interface. ID must be a decimal number greater then 0 which fits in the length + of SLA IDs (see below). For example, if ID is 1 and the client is delegated + an IPv6 prefix 2001:db8:ffff::/48, dhcp6c will combine the two values into a + single IPv6 prefix, 2001:db8:ffff:1::/64, and will configure the prefix on + the specified interface. + Operation ========= diff --git a/docs/interfaces/pppoe.rst b/docs/interfaces/pppoe.rst index 75fe0a40..8fa35492 100644 --- a/docs/interfaces/pppoe.rst +++ b/docs/interfaces/pppoe.rst @@ -183,27 +183,27 @@ by most ISPs who provide native IPv6 for consumers on fixed networks. Default value is 64. -.. cfgcmd:: set interfaces pppoe dhcpv6-option pd interface address +.. cfgcmd:: set interfaces pppoe dhcpv6-option pd interface address
- This statement specifies the interface address used locally on the interfcae - where the prefix has been delegated to. ID must be a decimal integer. - It will be combined with the delegated prefix and the sla-id to form a - complete interface address. The default is to use the EUI-64 address of the - interface. + Specify the interface address used locally on the interfcae where the prefix + has been delegated to. ID must be a decimal integer. + + It will be combined with the delegated prefix and the sla-id to form a complete + interface address. The default is to use the EUI-64 address of the interface. Example: - Using `` value 65535 will assign IPv6 address ::ffff to the + Using ```` value 65535 will assign IPv6 address ``::ffff`` to the interface. -.. cfgcmd:: set interfaces pppoe dhcpv6-option pd interface sla-id +.. cfgcmd:: set interfaces pppoe dhcpv6-option pd interface sla-id - This statement specifies the identifier value of the site-level aggregator - (SLA) on the interface. ID must be a decimal number greater then 0 which - fits in the length of SLA IDs (see below). For example, if ID is 1 and the - client is delegated an IPv6 prefix 2001:db8:ffff::/48, dhcp6c will combine - the two values into a single IPv6 prefix, 2001:db8:ffff:1::/64, and will - configure the prefix on the specified interface. + Specify the identifier value of the site-level aggregator (SLA) on the + interface. ID must be a decimal number greater then 0 which fits in the length + of SLA IDs (see below). For example, if ID is 1 and the client is delegated + an IPv6 prefix 2001:db8:ffff::/48, dhcp6c will combine the two values into a + single IPv6 prefix, 2001:db8:ffff:1::/64, and will configure the prefix on + the specified interface. Operation ========= -- cgit v1.2.3 From b772c4f678ace50280195d9691974dc41cb7ae58 Mon Sep 17 00:00:00 2001 From: currite Date: Thu, 5 Nov 2020 21:52:44 +0100 Subject: system: add system dns page --- docs/system/basic-index.rst | 1 + docs/system/system-dns.rst | 69 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+) create mode 100644 docs/system/system-dns.rst (limited to 'docs') diff --git a/docs/system/basic-index.rst b/docs/system/basic-index.rst index cb030089..b7bbf1c5 100644 --- a/docs/system/basic-index.rst +++ b/docs/system/basic-index.rst @@ -11,3 +11,4 @@ Basic System Tweaks host-information default-route time-zone + system-dns diff --git a/docs/system/system-dns.rst b/docs/system/system-dns.rst new file mode 100644 index 00000000..59cfdb5d --- /dev/null +++ b/docs/system/system-dns.rst @@ -0,0 +1,69 @@ +.. _system-dns: + +########## +System DNS +########## + + +This section describes configuring DNS on the system, namely: + + * DNS name servers + * Domain search order + + +DNS name servers +================ + +.. cfgcmd:: set system name-server
+ + Use this command to specify a DNS server for the system to be used + for DNS lookups. More than one DNS server can be added, configuring + one at a time. Both IPv4 and IPv6 addresses are supported. + + + +Example +------- + +In this example, some *OpenNIC* servers are used, two IPv4 addresses +and two IPv6 addresses: + + +.. code-block:: none + + set system name-server 176.9.37.132 + set system name-server 195.10.195.195 + set system name-server 2a01:4f8:161:3441::1 + set system name-server 2a00:f826:8:2::195 + + +Domain search order +=================== + +In order for the system to use and complete unqualified host names, a +list can be defined which will be used for domain searches. + + +.. cfgcmd:: set system domain-search domain + + Use this command to define domains, one at a time, so that the system + uses them to complete unqualified host names. Maximum: 6 entries. + + +.. note:: Domain names can include letters, numbers, hyphens and periods + with a maximum length of 253 characters. + + +Example +------- + +The system is configured to attempt domain completion in the following +order: vyos.io (first), vyos.net (second) and vyos.network (last): + + +.. code-block:: none + + set system domain-search domain vyos.io + set system domain-search domain vyos.net + set system domain-search domain vyos.network + -- cgit v1.2.3 From 58ab5850f3b6a11d46fdc6b187024fd6f704126d Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 8 Nov 2020 09:07:48 +0100 Subject: documentation: add link to RST directives --- docs/contributing/documentation.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst index 2b2d3ba7..92af881c 100644 --- a/docs/contributing/documentation.rst +++ b/docs/contributing/documentation.rst @@ -46,7 +46,8 @@ access to the official codebase. (:ref:`prepare_commit`). This mainly applies to proper commit messages describing your change (how and why). Please check out the documentation of Sphinx-doc_ or reStructuredText_ if you are not familiar with it. This is used - for writing our docs. + for writing our docs. Additional directives how to write in RST can be obtained + from reStructuredTextDirectives_. * Check your changes by locally building the documentation ``$ make html``. Sphinx will build the html files in the ``docs/_build`` folder. We provide @@ -175,7 +176,7 @@ descriptive way in the resulting HTML/PDF manual. For a inline configuration level command use ``:cfgcmd:`` .. code-block:: none - + :cfgcmd:`set interface ethernet eth0` opcmd @@ -196,7 +197,7 @@ descriptive way in the resulting HTML/PDF manual. For a inline operational level command use ``:opcmd:`` .. code-block:: none - + :opcmd:`add system image` vytask @@ -214,6 +215,7 @@ URL. This is heavily used in the :ref:`release-notes` section. .. _Sphinx-doc: https://www.sphinx-doc.org .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html +.. _reStructuredTextDirectives: https://docutils.sourceforge.io/docs/ref/rst/directives.html .. _README.md: https://github.com/vyos/vyos-documentation/blob/master/README.md .. include:: ../common-references.rst -- cgit v1.2.3 From 50e16ba3bff9581b708b78be68b0525f1189171d Mon Sep 17 00:00:00 2001 From: erkin Date: Mon, 9 Nov 2020 12:13:30 +0300 Subject: dhcp: Remove link to obsolete wiki --- docs/services/dhcp.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/services/dhcp.rst b/docs/services/dhcp.rst index 8655d177..56316793 100644 --- a/docs/services/dhcp.rst +++ b/docs/services/dhcp.rst @@ -629,9 +629,7 @@ If you want your router to forward DHCP requests to an external DHCP server you can configure the system to act as a DHCP relay agent. The DHCP relay agent works with IPv4 and IPv6 addresses. -All interfaces used for the DHCP relay must be configured. See -https://wiki.vyos.net/wiki/Network_address_setup. - +All interfaces used for the DHCP relay must be configured. Configuration ------------- -- cgit v1.2.3 From 696e05e56966c4f235ff014dcd0f49d2dda25081 Mon Sep 17 00:00:00 2001 From: currite Date: Mon, 9 Nov 2020 19:36:25 +0100 Subject: examples: add wan-load-balancing --- docs/_static/images/Wan_load_balancing1.png | Bin 0 -> 373848 bytes .../_static/images/Wan_load_balancing_exclude1.png | Bin 0 -> 382563 bytes docs/appendix/examples/index.rst | 3 +- docs/appendix/examples/wan-load-balancing.rst | 170 +++++++++++++++++++++ 4 files changed, 172 insertions(+), 1 deletion(-) create mode 100644 docs/_static/images/Wan_load_balancing1.png create mode 100644 docs/_static/images/Wan_load_balancing_exclude1.png create mode 100644 docs/appendix/examples/wan-load-balancing.rst (limited to 'docs') diff --git a/docs/_static/images/Wan_load_balancing1.png b/docs/_static/images/Wan_load_balancing1.png new file mode 100644 index 00000000..bde1edb6 Binary files /dev/null and b/docs/_static/images/Wan_load_balancing1.png differ diff --git a/docs/_static/images/Wan_load_balancing_exclude1.png b/docs/_static/images/Wan_load_balancing_exclude1.png new file mode 100644 index 00000000..1111535d Binary files /dev/null and b/docs/_static/images/Wan_load_balancing_exclude1.png differ diff --git a/docs/appendix/examples/index.rst b/docs/appendix/examples/index.rst index ca3a6251..58251378 100644 --- a/docs/appendix/examples/index.rst +++ b/docs/appendix/examples/index.rst @@ -3,7 +3,7 @@ Configuration Blueprints ======================== -This chapter contains various configuration Examples +This chapter contains various configuration examples: .. toctree:: @@ -18,3 +18,4 @@ This chapter contains various configuration Examples azure-vpn-dual-bgp tunnelbroker-ipv6 ha + wan-load-balancing diff --git a/docs/appendix/examples/wan-load-balancing.rst b/docs/appendix/examples/wan-load-balancing.rst new file mode 100644 index 00000000..7093defe --- /dev/null +++ b/docs/appendix/examples/wan-load-balancing.rst @@ -0,0 +1,170 @@ +.. _wan-load-balancing: + +WAN Load Balancer examples +========================== + + +Example 1: Distributing load evenly +----------------------------------- + +The setup used in this example is shown in the following diagram: + +.. image:: /_static/images/Wan_load_balancing1.png + :width: 80% + :align: center + :alt: Network Topology Diagram + + +Overview +^^^^^^^^ + * All traffic coming in trough eth2 is balanced between eth0 and eth1 + on the router. + * Pings will be sent to four targets for health testing (33.44.55.66, + 44.55.66.77, 55.66.77.88 and 66.77.88.99). + * All outgoing packets are assigned the source address of the assigned + interface (SNAT). + * eth0 is set to be removed from the load balancer's interface pool + after 5 ping failures, eth1 will be removed after 4 ping failures. + +Create static routes to ping targets +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Create static routes through the two ISPs towards the ping targets and +commit the changes: + +.. code-block:: none + + set protocols static route 33.44.55.66/32 next-hop 11.22.33.1 + set protocols static route 44.55.66.77/32 next-hop 11.22.33.1 + set protocols static route 55.66.77.88/32 next-hop 22.33.44.1 + set protocols static route 66.77.88.99/32 next-hop 22.33.44.1 + +Configure the load balancer +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Configure the WAN load balancer with the parameters described above: + +.. code-block:: none + + set load-balancing wan interface-health eth0 failure-count 5 + set load-balancing wan interface-health eth0 nexthop 11.22.33.1 + set load-balancing wan interface-health eth0 test 10 type ping + set load-balancing wan interface-health eth0 test 10 target 33.44.55.66 + set load-balancing wan interface-health eth0 test 20 type ping + set load-balancing wan interface-health eth0 test 20 target 44.55.66.77 + set load-balancing wan interface-health eth1 failure-count 4 + set load-balancing wan interface-health eth1 nexthop 22.33.44.1 + set load-balancing wan interface-health eth1 test 10 type ping + set load-balancing wan interface-health eth1 test 10 target 55.66.77.88 + set load-balancing wan interface-health eth1 test 20 type ping + set load-balancing wan interface-health eth1 test 20 target 66.77.88.99 + set load-balancing wan rule 10 inbound-interface eth2 + set load-balancing wan rule 10 interface eth0 + set load-balancing wan rule 10 interface eth1 + +Example 2: Failover based on interface weights +---------------------------------------------- + +This examples uses the failover mode. + +Overview +^^^^^^^^ +In this example eth0 is the primary interface and eth1 is the secondary +interface to provide simple failover functionality. If eth0 fails, eth1 +takes over. + +Create interface weight based configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The configuration steps are the same as in the previous example, except +rule 10 so we keep the configuration, remove rule 10 and add a new rule +for the failover mode: + +.. code-block:: none + + delete load-balancing wan rule 10 + set load-balancing wan rule 10 failover + set load-balancing wan rule 10 inbound-interface eth2 + set load-balancing wan rule 10 interface eth0 weight 10 + set load-balancing wan rule 10 interface eth1 weight 1 + +Example 3: Failover based on rule order +--------------------------------------- + +The previous example used the failover command to send traffic thorugh +eth1 if eth0 fails. In this example failover functionality is provided +by rule order. + +Overview +^^^^^^^^ +Two rules will be created, the first rule directs traffic coming in +from eth2 to eth0 and the second rule directs the traffic to eth1. If +eth0 fails the first rule is bypassed and the second rule matches, +directing traffic to eth1. + +Create rule order based configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +We keep the configurtation from the previous example, delete rule 10 +and create the two new rules as described: + +.. code-block:: none + + delete load-balancing wan rule 10 + set load-balancing wan rule 10 inbound-interface eth2 + set load-balancing wan rule 10 interface eth0 + set load-balancing wan rule 20 inbound-interface eth2 + set load-balancing wan rule 20 interface eth1 + +Example 4: Failover based on rule order - priority traffic +---------------------------------------------------------- + +A rule order for prioritising traffic is useful in scenarios where the +secondary link has a lower speed and should only carry high priority +traffic. It is assumed for this example that eth1 is connected to a +slower connection than eth0 and should prioritise VoIP traffic. + +Overview +^^^^^^^^ +A rule order for prioritising traffic is useful in scenarios where the +secondary link has a lower speed and should only carry high priority +traffic. It is assumed for this example that eth1 is connected to a +slower connection than eth0 and should prioritise VoIP traffic. + +Create rule order based configuration with low speed secondary link +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +We keep the configuration from the previous example, delete rule 20 and +create a new rule as described: + +.. code-block:: none + + delete load-balancing wan rule 20 + set load-balancing wan rule 20 inbound-interface eth2 + set load-balancing wan rule 20 interface eth1 + set load-balancing wan rule 20 destination port sip + set load-balancing wan rule 20 protocol tcp + set protocols static route 0.0.0.0/0 next-hop 11.22.33.1 + +Example 5: Exclude traffic from load balancing +---------------------------------------------- + +In this example two LAN interfaces exist in different subnets instead +of one like in the previous examples: + +.. image:: /_static/images/Wan_load_balancing_exclude1.png + :width: 80% + :align: center + :alt: Network Topology Diagram + +Adding a rule for the second interface +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Based on the previous example, another rule for traffic from the second +interface eth3 can be added to the load balancer. However, traffic meant +to flow between the LAN subnets will be sent to eth0 and eth1 as well. +To prevent this, another rule is required. This rule excludes traffic +between the local subnets from the load balancer. It also excludes +locally-sources packets (required for web caching with load balancing). +eth+ is used as an alias that refers to all ethernet interfaces: + +.. code-block:: none + + set load-balancing wan rule 5 exclude + set load-balancing wan rule 5 inbound-interface eth+ + set load-balancing wan rule 5 destination address 10.0.0.0/8 -- cgit v1.2.3 From c46473a849f20f8587b37ce5996979ea686685fa Mon Sep 17 00:00:00 2001 From: rebortg Date: Mon, 9 Nov 2020 21:16:02 +0100 Subject: docs: add ..cmdinclude:: directive --- docs/_ext/vyos.py | 159 +++++++++++++++++++++++++++++++++++- docs/contributing/documentation.rst | 38 +++++++++ 2 files changed, 195 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/_ext/vyos.py b/docs/_ext/vyos.py index 4ee87d63..e42d4cf0 100644 --- a/docs/_ext/vyos.py +++ b/docs/_ext/vyos.py @@ -1,6 +1,10 @@ -from docutils import nodes, utils +import re +import io +import os +from docutils import io, nodes, utils, statemachine +from docutils.utils.error_reporting import SafeString, ErrorString from docutils.parsers.rst.roles import set_classes -from docutils.parsers.rst import Directive +from docutils.parsers.rst import Directive, directives from sphinx.util.docutils import SphinxDirective @@ -49,6 +53,7 @@ def setup(app): app.add_directive('cfgcmd', CfgCmdDirective) app.add_directive('opcmd', OpCmdDirective) + app.add_directive('cmdinclude', CfgInclude) app.connect('doctree-resolved', process_cmd_nodes) @@ -148,6 +153,156 @@ class inlinecmd(nodes.inline): #self.literal_whitespace -= 1 +class CfgInclude(Directive): + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = { + 'var0': str, + 'var1': str, + 'var2': str, + 'var3': str, + 'var4': str, + 'var5': str, + 'var6': str, + 'var7': str, + 'var8': str, + 'var9': str + } + + def run(self): + ### Copy from include directive docutils + """Include a file as part of the content of this reST file.""" + if not self.state.document.settings.file_insertion_enabled: + raise self.warning('"%s" directive disabled.' % self.name) + source = self.state_machine.input_lines.source( + self.lineno - self.state_machine.input_offset - 1) + source_dir = os.path.dirname(os.path.abspath(source)) + path = directives.path(self.arguments[0]) + if path.startswith('<') and path.endswith('>'): + path = os.path.join(self.standard_include_path, path[1:-1]) + path = os.path.normpath(os.path.join(source_dir, path)) + path = utils.relative_path(None, path) + path = nodes.reprunicode(path) + encoding = self.options.get( + 'encoding', self.state.document.settings.input_encoding) + e_handler=self.state.document.settings.input_encoding_error_handler + tab_width = self.options.get( + 'tab-width', self.state.document.settings.tab_width) + try: + self.state.document.settings.record_dependencies.add(path) + include_file = io.FileInput(source_path=path, + encoding=encoding, + error_handler=e_handler) + except UnicodeEncodeError: + raise self.severe(u'Problems with "%s" directive path:\n' + 'Cannot encode input file path "%s" ' + '(wrong locale?).' % + (self.name, SafeString(path))) + except IOError: + raise self.severe(u'Problems with "%s" directive path.' % + (self.name)) + startline = self.options.get('start-line', None) + endline = self.options.get('end-line', None) + try: + if startline or (endline is not None): + lines = include_file.readlines() + rawtext = ''.join(lines[startline:endline]) + else: + rawtext = include_file.read() + except UnicodeError: + raise self.severe(u'Problem with "%s" directive:\n%s' % + (self.name, ErrorString(error))) + # start-after/end-before: no restrictions on newlines in match-text, + # and no restrictions on matching inside lines vs. line boundaries + after_text = self.options.get('start-after', None) + if after_text: + # skip content in rawtext before *and incl.* a matching text + after_index = rawtext.find(after_text) + if after_index < 0: + raise self.severe('Problem with "start-after" option of "%s" ' + 'directive:\nText not found.' % self.name) + rawtext = rawtext[after_index + len(after_text):] + before_text = self.options.get('end-before', None) + if before_text: + # skip content in rawtext after *and incl.* a matching text + before_index = rawtext.find(before_text) + if before_index < 0: + raise self.severe('Problem with "end-before" option of "%s" ' + 'directive:\nText not found.' % self.name) + rawtext = rawtext[:before_index] + + include_lines = statemachine.string2lines(rawtext, tab_width, + convert_whitespace=True) + if 'literal' in self.options: + # Convert tabs to spaces, if `tab_width` is positive. + if tab_width >= 0: + text = rawtext.expandtabs(tab_width) + else: + text = rawtext + literal_block = nodes.literal_block(rawtext, source=path, + classes=self.options.get('class', [])) + literal_block.line = 1 + self.add_name(literal_block) + if 'number-lines' in self.options: + try: + startline = int(self.options['number-lines'] or 1) + except ValueError: + raise self.error(':number-lines: with non-integer ' + 'start value') + endline = startline + len(include_lines) + if text.endswith('\n'): + text = text[:-1] + tokens = NumberLines([([], text)], startline, endline) + for classes, value in tokens: + if classes: + literal_block += nodes.inline(value, value, + classes=classes) + else: + literal_block += nodes.Text(value, value) + else: + literal_block += nodes.Text(text, text) + return [literal_block] + if 'code' in self.options: + self.options['source'] = path + codeblock = CodeBlock(self.name, + [self.options.pop('code')], # arguments + self.options, + include_lines, # content + self.lineno, + self.content_offset, + self.block_text, + self.state, + self.state_machine) + return codeblock.run() + + new_include_lines = [] + var_value0 = self.options.get('var0', '') + var_value1 = self.options.get('var1', '') + var_value2 = self.options.get('var2', '') + var_value3 = self.options.get('var3', '') + var_value4 = self.options.get('var4', '') + var_value5 = self.options.get('var5', '') + var_value6 = self.options.get('var6', '') + var_value7 = self.options.get('var7', '') + var_value8 = self.options.get('var8', '') + var_value9 = self.options.get('var9', '') + for line in include_lines: + line = re.sub('{{\s?var0\s?}}',var_value0,line) + line = re.sub('{{\s?var1\s?}}',var_value1,line) + line = re.sub('{{\s?var2\s?}}',var_value2,line) + line = re.sub('{{\s?var3\s?}}',var_value3,line) + line = re.sub('{{\s?var4\s?}}',var_value4,line) + line = re.sub('{{\s?var5\s?}}',var_value5,line) + line = re.sub('{{\s?var6\s?}}',var_value6,line) + line = re.sub('{{\s?var7\s?}}',var_value7,line) + line = re.sub('{{\s?var8\s?}}',var_value8,line) + line = re.sub('{{\s?var9\s?}}',var_value9,line) + new_include_lines.append(line) + self.state_machine.insert_input(new_include_lines, path) + return [] + + class CfgcmdlistDirective(Directive): def run(self): diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst index 92af881c..e8d1dba5 100644 --- a/docs/contributing/documentation.rst +++ b/docs/contributing/documentation.rst @@ -200,6 +200,44 @@ For a inline operational level command use ``:opcmd:`` :opcmd:`add system image` +cmdinclude +"""""""""" + +To minimize redundancy there is a special include directive. It include a txt +file and replace the ``{{ var0 }}`` - ``{{ var9 }}`` with the correct value + +.. code-block:: none + + .. cmdinclude:: interface-address.txt + :var0: ethernet + :var1: eth1 + +the content of interface-address.txt looks like this + +.. code-block:: none + + .. cfgcmd:: set interfaces {{ var0 }} address
+ + 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 + * **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 {{ var0 }} {{ var1 }} address 192.0.2.1/24 + set interfaces {{ var0 }} {{ var1 }} address 192.0.2.2/24 + set interfaces {{ var0 }} {{ var1 }} address 2001:db8::ffff/64 + set interfaces {{ var0 }} {{ var1 }} address 2001:db8:100::ffff/64 + vytask """""" -- cgit v1.2.3 From 58b3a577e5386e52ccfade8c5d9c3d5bc36f2839 Mon Sep 17 00:00:00 2001 From: rebortg Date: Mon, 9 Nov 2020 21:30:06 +0100 Subject: Bridge: convert address to cmdinclude --- docs/_include/interface-address.txt | 21 +++++++++++++++++++++ docs/interfaces/bridge.rst | 24 +++--------------------- 2 files changed, 24 insertions(+), 21 deletions(-) create mode 100644 docs/_include/interface-address.txt (limited to 'docs') diff --git a/docs/_include/interface-address.txt b/docs/_include/interface-address.txt new file mode 100644 index 00000000..1de05c31 --- /dev/null +++ b/docs/_include/interface-address.txt @@ -0,0 +1,21 @@ +.. cfgcmd:: set interfaces {{ var0 }} address
+ + 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 + * **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 {{ var0 }} {{ var1 }} address 192.0.2.1/24 + set interfaces {{ var0 }} {{ var1 }} address 192.0.2.2/24 + set interfaces {{ var0 }} {{ var1 }} address 2001:db8::ffff/64 + set interfaces {{ var0 }} {{ var1 }} address 2001:db8:100::ffff/64 \ No newline at end of file diff --git a/docs/interfaces/bridge.rst b/docs/interfaces/bridge.rst index a7343a0d..26e67690 100644 --- a/docs/interfaces/bridge.rst +++ b/docs/interfaces/bridge.rst @@ -20,27 +20,9 @@ Configuration Address ------- -.. cfgcmd:: set interfaces bridge address
- - 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 - * **dhcp** interface address is received by DHCP from a DHCP server - on this segment. - * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 - server on this segment. - - Example: - - .. code-block:: none - - set interfaces bridge br0 address 192.0.2.1/24 - set interfaces bridge br0 address 192.0.2.2/24 - set interfaces bridge br0 address 2001:db8::ffff/64 - set interfaces bridge br0 address 2001:db8:100::ffff/64 +.. cmdinclude:: ../_include/interface-address.txt + :var0: bridge + :var1: br0 .. cfgcmd:: set interfaces bridge ipv6 address autoconf -- cgit v1.2.3 From b7e61a03f09b93cdaa91a3c6b13d967621483f5c Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Tue, 10 Nov 2020 20:02:47 +0100 Subject: interfaces: extend usage of new cmdinclude directive for bridge, bond, eth, peth, vxlan Commit c46473a ("docs: add ..cmdinclude:: directive") added support for including common text but only replacing individual labels so there can be source of truth also for the documentation. --- docs/_include/interface-ipv6-addr-autoconf.txt | 20 +++++++++++++ docs/_include/interface-ipv6-addr-eui64.txt | 8 +++++ docs/interfaces/bond.rst | 41 ++++++-------------------- docs/interfaces/bridge.rst | 21 ++++--------- docs/interfaces/common-ip-ipv6-addr.txt | 8 ----- docs/interfaces/common-ipv6-addr-autoconf.txt | 12 -------- docs/interfaces/ethernet.rst | 32 ++++++-------------- docs/interfaces/pseudo-ethernet.rst | 23 ++++++--------- docs/interfaces/vxlan.rst | 36 ++++++---------------- 9 files changed, 70 insertions(+), 131 deletions(-) create mode 100644 docs/_include/interface-ipv6-addr-autoconf.txt create mode 100644 docs/_include/interface-ipv6-addr-eui64.txt delete mode 100644 docs/interfaces/common-ip-ipv6-addr.txt delete mode 100644 docs/interfaces/common-ipv6-addr-autoconf.txt (limited to 'docs') diff --git a/docs/_include/interface-ipv6-addr-autoconf.txt b/docs/_include/interface-ipv6-addr-autoconf.txt new file mode 100644 index 00000000..22f9ee59 --- /dev/null +++ b/docs/_include/interface-ipv6-addr-autoconf.txt @@ -0,0 +1,20 @@ +.. cfgcmd:: set interfaces {{ var0 }} 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. + + .. note:: This method automatically disables IPv6 traffic forwarding on the + interface in question. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} ipv6 address autoconf diff --git a/docs/_include/interface-ipv6-addr-eui64.txt b/docs/_include/interface-ipv6-addr-eui64.txt new file mode 100644 index 00000000..40f22e5f --- /dev/null +++ b/docs/_include/interface-ipv6-addr-eui64.txt @@ -0,0 +1,8 @@ +.. cfgcmd:: set interfaces {{ var0 }} 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 {{ var0 }} {{ var1 }} ipv6 address eui64 2001:db8:beef::/64 diff --git a/docs/interfaces/bond.rst b/docs/interfaces/bond.rst index 9e67809a..78099f01 100644 --- a/docs/interfaces/bond.rst +++ b/docs/interfaces/bond.rst @@ -16,40 +16,17 @@ Configuration Address ------- -.. cfgcmd:: set interfaces bonding address
+.. cmdinclude:: ../_include/interface-address.txt + :var0: bonding + :var1: bond0 - 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 - * **dhcp** interface address is received by DHCP from a DHCP server on this - segment. - * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 server on - this segment. - - Example: - - .. code-block:: none - - set interfaces bonding bond0 address 192.0.2.1/24 - set interfaces bonding bond0 address 192.0.2.2/24 - set interfaces bonding bond0 address 2001:db8::ffff/64 - set interfaces bonding bond0 address 2001:db8:100::ffff/64 - - -.. cfgcmd:: set interfaces bonding ipv6 address autoconf - - .. include:: common-ipv6-addr-autoconf.txt - -.. cfgcmd:: set interfaces bonding 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 bonding bond0 ipv6 address eui64 2001:db8:beef::/64 +.. cmdinclude:: ../_include/interface-ipv6-addr-autoconf.txt + :var0: bonding + :var1: bond0 +.. cmdinclude:: ../_include/interface-ipv6-addr-eui64.txt + :var0: bonding + :var1: bond0 Link Administration ------------------- diff --git a/docs/interfaces/bridge.rst b/docs/interfaces/bridge.rst index 26e67690..aec1c5d8 100644 --- a/docs/interfaces/bridge.rst +++ b/docs/interfaces/bridge.rst @@ -24,22 +24,13 @@ Address :var0: bridge :var1: br0 +.. cmdinclude:: ../_include/interface-ipv6-addr-autoconf.txt + :var0: bridge + :var1: br0 -.. cfgcmd:: set interfaces bridge ipv6 address autoconf - - .. include:: common-ipv6-addr-autoconf.txt - -.. cfgcmd:: set interfaces bridge 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 bridge br0 ipv6 address eui64 2001:db8:beef::/64 - +.. cmdinclude:: ../_include/interface-ipv6-addr-eui64.txt + :var0: bridge + :var1: br0 .. cfgcmd:: set interfaces bridge aging