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

Merge branch 'master' into misc

Browse Source
This commit is contained in:
Robert Göhler 2021-06-30 14:49:40 +02:00 committed by GitHub
commit e58574d80d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
27 changed files with 616 additions and 155 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
docs/_ext/vyos.py
View File

@ -1,6 +1,7 @@
import re import re
import json import json
import os import os
from datetime import datetime
from docutils import io, nodes, utils, statemachine from docutils import io, nodes, utils, statemachine
from docutils.parsers.rst.roles import set_classes from docutils.parsers.rst.roles import set_classes
from docutils.parsers.rst import Directive, directives, states from docutils.parsers.rst import Directive, directives, states
@ -9,6 +10,9 @@ from sphinx.util.docutils import SphinxDirective
from testcoverage import get_working_commands from testcoverage import get_working_commands
from sphinx.util import logging
logger = logging.getLogger(__name__)
def setup(app): def setup(app):
@ -74,6 +78,7 @@ def setup(app):
app.add_directive('opcmd', OpCmdDirective) app.add_directive('opcmd', OpCmdDirective)
app.add_directive('cmdinclude', CfgInclude) app.add_directive('cmdinclude', CfgInclude)
app.connect('doctree-resolved', process_cmd_nodes) app.connect('doctree-resolved', process_cmd_nodes)
app.connect('doctree-read', handle_document_meta_data)
class CfgcmdList(nodes.General, nodes.Element): class CfgcmdList(nodes.General, nodes.Element):
pass pass
@ -640,4 +645,23 @@ def vytask_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
def cmd_role(name, rawtext, text, lineno, inliner, options={}, content=[]): def cmd_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
node = nodes.literal(text, text) node = nodes.literal(text, text)
return [node], [] return [node], []
def handle_document_meta_data(app, document):
docname = app.env.docname
lastproofread = app.env.metadata[docname].get('lastproofread', False)
if lastproofread:
try:
lastproofread_time = datetime.strptime(lastproofread, '%Y-%m-%d')
delta = datetime.now() - lastproofread_time
if delta.days > 180:
logger.warning(f'{delta.days} days since last proofread {app.env.doc2path(docname)}')
except Exception as e:
logger.warning(f'lastproofread meta data error in {app.env.doc2path(docname)}: {e}')
else:
pass
#logger.warning(f'lastproofread meta data missing in {app.env.doc2path(docname)}')

2
docs/_include/vyos-1x

@ -1 +1 @@
Subproject commit 78099bccc510c90ad7cfa5f56475ba024d5d53a7 Subproject commit 09efa0550dd169e30a851513781b611dd84e9c79

28
docs/automation/cloud-init.rst
View File

@ -1,29 +1,31 @@
.. _cloud-init: :lastproofread: 2021-06-27
. _cloud-init:
############### ###############
VyOS cloud-init VyOS cloud-init
############### ###############
Cloud instances of VyOS are initialized using the industry-standard cloud-init. Cloud instances of VyOS are initialized using the industry-standard
Via cloud-init, the system performs tasks such as injecting SSH keys and cloud-init. Via cloud-init, the system performs tasks such as injecting
configuring the network. In addition, the user can supply a custom SSH keys and configuring the network. In addition, the user can supply a custom
configuration at the time of instance launch. configuration at the time of instance launch.
************** **************
Config Sources Config Sources
************** **************
VyOS support three type of config sources. VyOS support three types of config sources.
.. stop_vyoslinter * Metadata - Metadata is sourced by the cloud platform or hypervisor.
In some clouds, there is implemented as an HTTP endpoint at
http://169.254.169.254.
* Metadata - Metadata is sourced by the cloud platform or hypervisor. In some clouds, there is implemented as an HTTP endpoint at http://169.254.169.254. * Network configuration - This config source informs the system about the
network.
* Network configuration - Ths config source informs the system about the network. * User-data - User-data is specified by the user. This config source offers the
most flexibility and will be the focus of this documentation.
* User-data - User-data is specified by the user. This config source offers the most flexibility and will be the focus of this documentation.
.. start_vyoslinter
********* *********
@ -86,7 +88,7 @@ These are the VyOS defaults and fallbacks.
* DHCP on first Ethernet interface if no network configuration is provided * DHCP on first Ethernet interface if no network configuration is provided
All of these can be overridden using configuration in user-data. All of these can be overridden using the configuration in user-data.
*************** ***************

69
docs/automation/command-scripting.rst
View File

@ -1,3 +1,5 @@
:lastproofread: 2021-06-27
.. _command-scripting: .. _command-scripting:
Command Scripting Command Scripting
@ -34,7 +36,7 @@ example, if you want to disable a BGP peer on VRRP transition to backup:
Run operational commands Run operational commands
------------------------ ------------------------
Unlike a normal configuration sessions, all operational commands must be Unlike a normal configuration session, all operational commands must be
prepended with ``run``, even if you haven't created a session with configure. prepended with ``run``, even if you haven't created a session with configure.
.. code-block:: none .. code-block:: none
@ -44,8 +46,8 @@ prepended with ``run``, even if you haven't created a session with configure.
run show interfaces run show interfaces
exit exit
Other script language Other script languages
--------------------- ----------------------
If you want to script the configs in a language other than bash you can have If you want to script the configs in a language other than bash you can have
your script output commands and then source them in a bash script. your script output commands and then source them in a bash script.
@ -105,14 +107,71 @@ group, the script can be safeguarded like this:
exec sg vyattacfg -c "/bin/vbash $(readlink -f $0) $@" exec sg vyattacfg -c "/bin/vbash $(readlink -f $0) $@"
fi fi
Executing pre-hooks/post-hooks Scripts
--------------------------------------
VyOS has the ability to run custom scripts before and after each commit
The default directories where your custom Scripts should be located are:
.. code-block:: none
/config/scripts/commit/pre-hooks.d - Directory with scripts that run before
each commit.
/config/scripts/commit/post-hooks.d - Directory with scripts that run after
each commit.
Scripts are run in alphabetical order. Their names must consist entirely of
ASCII upper- and lower-case letters,ASCII digits, ASCII underscores, and
ASCII minus-hyphens.No other characters are allowed.
.. note:: Custom scripts are not executed with root privileges
(Use sudo inside if this is necessary).
A simple example is shown below, where the ops command executed in
the post-hook script is "show interfaces".
.. code-block:: none
vyos@vyos# set interfaces ethernet eth1 address 192.0.2.3/24
vyos@vyos# commit
Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
Interface IP Address S/L Description
--------- ---------- --- -----------
eth0 198.51.100.10/24 u/u
eth1 192.0.2.3/24 u/u
eth2 - u/u
eth3 - u/u
lo 203.0.113.5/24 u/u
Preconfig on boot
-----------------
The ``/config/scripts/vyos-preconfig-bootup.script`` script is called on boot
before the VyOS configuration during boot process.
Any modifications were done to work around unfixed bugs and implement
enhancements that are not complete in the VyOS system can be placed here.
The default file looks like this:
.. code-block:: none
#!/bin/sh
# This script is executed at boot time before VyOS configuration is applied.
# Any modifications required to work around unfixed bugs or use
# services not available through the VyOS CLI system can be placed here.
Postconfig on boot Postconfig on boot
------------------ ------------------
The ``/config/scripts/vyos-postconfig-bootup.script`` script is called on boot The ``/config/scripts/vyos-postconfig-bootup.script`` script is called on boot
after the VyOS configuration is fully applied. after the VyOS configuration is fully applied.
Any modifications done to work around unfixed bugs and implement enhancements Any modifications were done to work around unfixed bugs and implement
which are not complete in the VyOS system can be placed here. enhancements that are not complete in the VyOS system can be placed here.
The default file looks like this: The default file looks like this:

2
docs/automation/vyos-ansible.rst
View File

@ -1,3 +1,5 @@
:lastproofread: 2021-06-28
.. _vyos-ansible: .. _vyos-ansible:
Ansible Ansible

21
docs/automation/vyos-api.rst
View File

@ -1,3 +1,5 @@
:lastproofread: 2021-06-28
.. _vyosapi: .. _vyosapi:
######## ########
@ -10,11 +12,11 @@ For configuration and enabling the API see :ref:`http-api`
Authentication Authentication
************** **************
All Endpoint only listen on HTTP POST requests and the API KEY must set as All endpoints only listen on HTTP POST requests and the API KEY must set as
``key`` in the formdata. ``key`` in the formdata.
Below see one example for curl and one for python. Below see one example for curl and one for python.
In the following, the documentation is reduced to curl. The rest of the documentation is reduced to curl.
.. code-block:: none .. code-block:: none
@ -74,8 +76,7 @@ To get the whole configuration, pass an empty list to the ``path`` field
} }
only get a part of the configuration, To only get a part of the configuration, for example ``system syslog``.
for example ``system syslog``.
.. code-block:: none .. code-block:: none
@ -105,7 +106,7 @@ for example ``system syslog``.
if you just want the Value of a multi-valued node, use the ``returnValues`` if you just want the Value of a multi-valued node, use the ``returnValues``
operation. operation.
for example get the addresses of a ``dum0`` interface For example, get the addresses of a ``dum0`` interface.
.. code-block:: none .. code-block:: none
@ -165,9 +166,9 @@ delete an image, for example ``1.3-rolling-202006070117``
/show /show
===== =====
The ``/show`` endpoint is to show everthing in operational mode The ``/show`` endpoint is to show everything in the operational mode.
for example which images are installed For example, show which images are installed.
.. code-block:: none .. code-block:: none
@ -189,7 +190,7 @@ for example which images are installed
/generate /generate
========= =========
to run a ``generate`` command use the THe ``generate`` endpoint run a ``generate`` command.
.. code-block:: none .. code-block:: none
@ -242,10 +243,10 @@ You can pass a ``set``, ``delete`` or ``comment`` command to the
"error": null "error": null
} }
The API push every request to a session and commit it. The API pushes every request to a session and commit it.
But some of VyOS components like DHCP and PPPoE Servers, IPSec, VXLAN, and But some of VyOS components like DHCP and PPPoE Servers, IPSec, VXLAN, and
other tunnels require full configuration for commit. other tunnels require full configuration for commit.
The Endpoint will process multiple commands when you pass them as a list to The endpoint will process multiple commands when you pass them as a list to
the ``data`` field. the ``data`` field.
.. code-block:: none .. code-block:: none

55
docs/changelog/1.3.rst
View File

@ -8,6 +8,59 @@
_ext/releasenotes.py _ext/releasenotes.py
2021-06-27
==========
* :vytask:`T3653` (default): Cloudinit subnet error if a cidr (/24) is used instead of a subnet mask (255.255.255.0)
2021-06-25
==========
* :vytask:`T3650` (bug): OpenVPN: Upgrade package to 2.5.1 before releasing VyOS 1.3.0
* :vytask:`T3649` (feature): Add bonding additional hash-policy
2021-06-24
==========
* :vytask:`T2722` (bug): get_config_dict() and key_mangling=('-', '_') will alter CLI data for tagNodes
2021-06-22
==========
* :vytask:`T3629` (bug): IPoE server shifting address in the range
* :vytask:`T3582` (default): 'delete log file' does not work
2021-06-19
==========
* :vytask:`T3633` (feature): Add LRO offload for interface ethernet
* :vytask:`T3632` (bug): policy: route-map: unable to configure route-target / site-of-origin
2021-06-18
==========
* :vytask:`T3634` (feature): Add op command option for ping for do not fragment bit to be set
2021-06-17
==========
* :vytask:`T3631` (feature): route-map: migrate "set extcommunity-rt" and "set extcommunity-soo" to "set extcommunity rt|soo" to match FRR syntax
2021-06-16
==========
* :vytask:`T3623` (default): Fix for dummy interface option in the operational command "clear interfaces dummy"
* :vytask:`T2425` (feature): Rewrite all policy zebra filters to XML/Python style
* :vytask:`T3630` (feature): op-mode: add "show version kernel" command
2021-06-13 2021-06-13
========== ==========
@ -528,7 +581,7 @@
2021-02-16 2021-02-16
========== ==========
* :vytask:`T3318` (feature): Update Linux Kernel to v5.4.125 / 5.10.43 * :vytask:`T3318` (feature): Update Linux Kernel to v5.4.128 / 5.10.46
2021-02-14 2021-02-14

72
docs/changelog/1.4.rst
View File

@ -8,6 +8,76 @@
_ext/releasenotes.py _ext/releasenotes.py
2021-06-27
==========
* :vytask:`T3653` (default): Cloudinit subnet error if a cidr (/24) is used instead of a subnet mask (255.255.255.0)
2021-06-25
==========
* :vytask:`T3641` (feature): Upgrade base system from Debian Buster -> Debian Bullseye
* :vytask:`T3649` (feature): Add bonding additional hash-policy
2021-06-23
==========
* :vytask:`T3647` (feature): Bullseye: gcc defaults to passing --as-needed to linker
* :vytask:`T3644` (default): Replace GCC with a simpler preprocessor for including nested XML snippets in XML documents
* :vytask:`T3356` (feature): Script for remote file transfers
2021-06-22
==========
* :vytask:`T3629` (bug): IPoE server shifting address in the range
* :vytask:`T3645` (feature): Bullseye: ethtool changed output for ring-buffer information
* :vytask:`T3582` (default): 'delete log file' does not work
2021-06-21
==========
* :vytask:`T3628` (bug): commit-archive source-address Interface Broken
* :vytask:`T3563` (default): commit-archive breaks with IPv6 source addresses
2021-06-20
==========
* :vytask:`T3637` (bug): vrf: bind-to-all didn't work properly
* :vytask:`T3639` (default): GCC preprocessor clobbers C comments
2021-06-19
==========
* :vytask:`T3633` (feature): Add LRO offload for interface ethernet
* :vytask:`T3632` (bug): policy: route-map: unable to configure route-target / site-of-origin
2021-06-18
==========
* :vytask:`T3634` (feature): Add op command option for ping for do not fragment bit to be set
* :vytask:`T3599` (default): Migrate NHRP to XML/Python
2021-06-17
==========
* :vytask:`T3624` (feature): BGP: add support for extended community bandwidth definition
2021-06-16
==========
* :vytask:`T3623` (default): Fix for dummy interface option in the operational command "clear interfaces dummy"
* :vytask:`T3630` (feature): op-mode: add "show version kernel" command
2021-06-13 2021-06-13
========== ==========
@ -621,7 +691,7 @@
========== ==========
* :vytask:`T3313` (bug): ospfv3 interface missing options * :vytask:`T3313` (bug): ospfv3 interface missing options
* :vytask:`T3318` (feature): Update Linux Kernel to v5.4.125 / 5.10.43 * :vytask:`T3318` (feature): Update Linux Kernel to v5.4.128 / 5.10.46
2021-02-15 2021-02-15

2
docs/configexamples/azure-vpn-bgp.rst
View File

@ -1,3 +1,5 @@
:lastproofread: 2021-06-28
.. _examples-azure-vpn-bgp: .. _examples-azure-vpn-bgp:
Route-Based Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) Route-Based Site-to-Site VPN to Azure (BGP over IKEv2/IPsec)

2
docs/configexamples/azure-vpn-dual-bgp.rst
View File

@ -1,3 +1,5 @@
:lastproofread: 2021-06-28
.. _examples-azure-vpn-dual-bgp: .. _examples-azure-vpn-dual-bgp:
Route-Based Redundant Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) Route-Based Redundant Site-to-Site VPN to Azure (BGP over IKEv2/IPsec)

2
docs/configexamples/bgp-ipv6-unnumbered.rst
View File

@ -1,3 +1,5 @@
:lastproofread: 2021-06-28
.. _examples-bgp-ipv6-unnumbered: .. _examples-bgp-ipv6-unnumbered:
######################################### #########################################

5
docs/configexamples/dhcp-relay-through-gre-bridge.rst
View File

@ -1,7 +1,4 @@
:lastproofread: 2021-06-28
.. _examples-dhcp-relay-through-gre-bridge: .. _examples-dhcp-relay-through-gre-bridge:

46
docs/configexamples/ha.rst
View File

@ -1,24 +1,26 @@
:lastproofread: 2021-06-28
############################# #############################
High Availability Walkthrough High Availability Walkthrough
############################# #############################
This document walks you through a complete HA setup of two VyOS machines. This This document walks you through a complete HA setup of two VyOS machines. This
design is based on a VM as the primary router, and a physical machine as a design is based on a VM as the primary router and a physical machine as a
backup, using VRRP, BGP, OSPF and conntrack sharing. backup, using VRRP, BGP, OSPF, and conntrack sharing.
The aim of this document is to walk you through setting everything up, so This document aims to walk you through setting everything up, so
at a point where you can reboot any machine and not lose more than a few at a point where you can reboot any machine and not lose more than a few
seconds worth of connectivity. seconds worth of connectivity.
Design Design
====== ======
This is based on a real life, in production design. One of the complex issues This is based on a real-life production design. One of the complex issues
is ensuring you have redundant data INTO your network. We do this with a pair is ensuring you have redundant data INTO your network. We do this with a pair
of Cisco Nexus switches, and using Virtual PortChannels that are spanned across of Cisco Nexus switches and using Virtual PortChannels that are spanned across
them. This as an added bonus, also allows for complete switch failure without them. As a bonus, this also allows for complete switch failure without
an outage. How you achieve this yourself is left as an exercise to the reader an outage. How you achieve this yourself is left as an exercise to the reader.
but our setup is documented here. But our setup is documented here.
Walkthrough suggestion Walkthrough suggestion
---------------------- ----------------------
@ -31,7 +33,7 @@ If you are following through this document, it is strongly suggested you
complete the entire document, ONLY doing the virtual router1 steps, and then complete the entire document, ONLY doing the virtual router1 steps, and then
come back and walk through it AGAIN on the backup hardware router. come back and walk through it AGAIN on the backup hardware router.
This ensures you don't go to fast, or miss a step. However, it will make your This ensures you don't go too fast or miss a step. However, it will make your
life easier to configure the fixed IP address and default route now on the life easier to configure the fixed IP address and default route now on the
hardware router. hardware router.
@ -43,7 +45,7 @@ provider, which we are publishing on VLAN100.
They want us to establish a BGP session to their routers on 192.0.2.11 and They want us to establish a BGP session to their routers on 192.0.2.11 and
192.0.2.12 from our routers 192.0.2.21 and 192.0.2.22. They are AS 65550 and 192.0.2.12 from our routers 192.0.2.21 and 192.0.2.22. They are AS 65550 and
we are AS65551. we are AS 65551.
Our routers are going to have a floating IP address of 203.0.113.1, and use Our routers are going to have a floating IP address of 203.0.113.1, and use
.2 and .3 as their fixed IPs. .2 and .3 as their fixed IPs.
@ -54,13 +56,13 @@ When traffic is originated from the 10.200.201.0/24 network, it will be
masqueraded to 203.0.113.1 masqueraded to 203.0.113.1
For connection between sites, we are running a WireGuard link to two REMOTE For connection between sites, we are running a WireGuard link to two REMOTE
routers, and using OSPF over those links to distribute routes. That remote routers and using OSPF over those links to distribute routes. That remote
site is expected to send traffic from anything in 10.201.0.0/16 site is expected to send traffic from anything in 10.201.0.0/16
VLANs VLANs
----- -----
These are the vlans we wll be using: These are the vlans we will be using:
* 50: Upstream, using the 192.0.2.0/24 network allocated by them. * 50: Upstream, using the 192.0.2.0/24 network allocated by them.
* 100: 'Public' network, using our 203.0.113.0/24 network. * 100: 'Public' network, using our 203.0.113.0/24 network.
@ -95,7 +97,7 @@ of scope of this.
.. note:: Our implementation uses VMware's Distributed Port Groups, which allows .. note:: Our implementation uses VMware's Distributed Port Groups, which allows
VMware to use LACP. This is a part of the ENTERPRISE licence, and is not VMware to use LACP. This is a part of the ENTERPRISE licence, and is not
available on a Free licence. If you are implementing this and do not have available on a free licence. If you are implementing this and do not have
access to DPGs, you should not use VMware, and use some other virtualization access to DPGs, you should not use VMware, and use some other virtualization
platform instead. platform instead.
@ -103,7 +105,7 @@ of scope of this.
Basic Setup (via console) Basic Setup (via console)
========================= =========================
Create your router1 VM so it is able to withstand a VM Host failing, or a Create your router1 VM. So it can withstand a VM Host failing or a
network link failing. Using VMware, this is achieved by enabling vSphere DRS, network link failing. Using VMware, this is achieved by enabling vSphere DRS,
vSphere Availability, and creating a Distributed Port Group that uses LACP. vSphere Availability, and creating a Distributed Port Group that uses LACP.
@ -177,7 +179,7 @@ Enable SSH so you can now SSH into the routers, rather than using the console.
commit commit
save save
At this point you should be able to SSH into both of them, and will no longer At this point, you should be able to SSH into both of them, and will no longer
need access to the console (unless you break something!) need access to the console (unless you break something!)
@ -417,9 +419,9 @@ Make sure you can ping 10.254.60.1 and .2 from both routers.
Create Export Filter Create Export Filter
-------------------- --------------------
We only want to export the networks we know we should be exporting. Always We only want to export the networks we know. Always do a whitelist on your route
whitelist your route filters, both importing and exporting. A good rule of filters, both importing and exporting. A good rule of thumb is
thumb is **'If you are not the default router for a network, don't advertise **'If you are not the default router for a network, don't advertise
it'**. This means we explicitly do not want to advertise the 192.0.2.0/24 it'**. This means we explicitly do not want to advertise the 192.0.2.0/24
network (but do want to advertise 10.200.201.0 and 203.0.113.0, which we ARE network (but do want to advertise 10.200.201.0 and 203.0.113.0, which we ARE
the default route for). This filter is applied to ``redistribute connected``. the default route for). This filter is applied to ``redistribute connected``.
@ -448,7 +450,7 @@ default again. This is called 'flapping'.
Create Import Filter Create Import Filter
-------------------- --------------------
We only want to import networks we know about. Our OSPF peer should only be We only want to import networks we know. Our OSPF peer should only be
advertising networks in the 10.201.0.0/16 range. Note that this is an INVERSE advertising networks in the 10.201.0.0/16 range. Note that this is an INVERSE
MATCH. You deny in access-list 100 to accept the route. MATCH. You deny in access-list 100 to accept the route.
@ -491,7 +493,7 @@ Test OSPF
When you have enabled OSPF on both routers, you should be able to see each When you have enabled OSPF on both routers, you should be able to see each
other with the command ``show ip ospf neighbour``. The state must be 'Full' other with the command ``show ip ospf neighbour``. The state must be 'Full'
or '2-Way', if it is not then there is a network connectivity issue between the or '2-Way'. If it is not, then there is a network connectivity issue between the
hosts. This is often caused by NAT or MTU issues. You should not see any new hosts. This is often caused by NAT or MTU issues. You should not see any new
routes (unless this is the second pass) in the output of ``show ip route`` routes (unless this is the second pass) in the output of ``show ip route``
@ -514,8 +516,8 @@ You should now be able to see the advertised network on the other host.
Duplicate configuration Duplicate configuration
----------------------- -----------------------
At this pont you now need to create the X link between all four routers. Use a At this point, you now need to create the X link between all four routers.
different /30 for each link. Use amdifferent /30 for each link.
Priorities Priorities
---------- ----------

2
docs/configexamples/ospf-unnumbered.rst
View File

@ -1,3 +1,5 @@
:lastproofread: 2021-06-29
.. _examples-ospf-unnumbered: .. _examples-ospf-unnumbered:
######################### #########################

24
docs/configexamples/pppoe-ipv6-basic.rst
View File

@ -1,3 +1,5 @@
:lastproofread: 2021-06-29
.. _examples-pppoe-ipv6-basic: .. _examples-pppoe-ipv6-basic:
####################################### #######################################
@ -5,9 +7,9 @@ PPPoE IPv6 Basic Setup for Home Network
####################################### #######################################
This document is to describe a basic setup using PPPoE with DHCPv6-PD + This document is to describe a basic setup using PPPoE with DHCPv6-PD +
SLAAC to construct a typical home network. The user can follow steps described SLAAC to construct a typical home network. The user can follow the steps
here to quickly setup a working network and use this as a starting point to described here to quickly setup a working network and use this as a starting
further configure or fine tune other settings. point to further configure or fine-tune other settings.
To achieve this, your ISP is required to support DHCPv6-PD. If you're not sure, To achieve this, your ISP is required to support DHCPv6-PD. If you're not sure,
please contact your ISP for more information. please contact your ISP for more information.
@ -40,8 +42,8 @@ DHCPv6-PD Setup
--------------- ---------------
During address configuration, in addition to assigning an address to the WAN During address configuration, in addition to assigning an address to the WAN
interface, ISP also provides a prefix to allow router to configure addresses of interface, ISP also provides a prefix to allow the router to configure addresses
LAN interface and other nodes connecting to LAN, which is called prefix of LAN interface and other nodes connecting to LAN, which is called prefix
delegation (PD). delegation (PD).
.. code-block:: none .. code-block:: none
@ -49,8 +51,8 @@ delegation (PD).
set interfaces pppoe pppoe0 ipv6 address autoconf set interfaces pppoe pppoe0 ipv6 address autoconf
set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth1 address '100' set interfaces pppoe pppoe0 dhcpv6-options pd 0 interface eth1 address '100'
* Here we use prefix to configure the address of eth1 (LAN) to form ``<prefix>::64``, * Here we use the prefix to configure the address of eth1 (LAN) to form
where ``64`` is hexadecimal of address 100. ``<prefix>::64``, where ``64`` is hexadecimal of address 100.
* For home network users, most of time ISP only provides /64 prefix, hence * For home network users, most of time ISP only provides /64 prefix, hence
there is no need to set SLA ID and prefix length. See :ref:`pppoe-interface` there is no need to set SLA ID and prefix length. See :ref:`pppoe-interface`
for more information. for more information.
@ -59,7 +61,7 @@ Router Advertisement
-------------------- --------------------
We need to enable router advertisement for LAN network so that PC can receive We need to enable router advertisement for LAN network so that PC can receive
the prefix and use SLAAC to configure address automatically. the prefix and use SLAAC to configure the address automatically.
.. code-block:: none .. code-block:: none
@ -68,8 +70,8 @@ the prefix and use SLAAC to configure address automatically.
set service router-advert interface eth1 prefix ::/64 valid-lifetime '172800' set service router-advert interface eth1 prefix ::/64 valid-lifetime '172800'
* Set MTU in advertisement to 1492 because of PPPoE header overhead. * Set MTU in advertisement to 1492 because of PPPoE header overhead.
* Set DNS server address in advertisement so that clients can obtain it by using * Set DNS server address in the advertisement so that clients can obtain it by
RDNSS option. Most operating systems (Windows, Linux, Mac) should using RDNSS option. Most operating systems (Windows, Linux, Mac) should
already support it. already support it.
* Here we set the prefix to ``::/64`` to indicate advertising any /64 prefix * Here we set the prefix to ``::/64`` to indicate advertising any /64 prefix
the LAN interface is assigned. the LAN interface is assigned.
@ -106,5 +108,5 @@ To have basic protection while keeping IPv6 network functional, we need to:
set interfaces pppoe pppoe0 firewall in ipv6-name 'WAN_IN' set interfaces pppoe pppoe0 firewall in ipv6-name 'WAN_IN'
set interfaces pppoe pppoe0 firewall local ipv6-name 'WAN_LOCAL' set interfaces pppoe pppoe0 firewall local ipv6-name 'WAN_LOCAL'
Note to allow router to receive DHCPv6 response from ISP, we need to allow Note to allow the router to receive DHCPv6 response from ISP. We need to allow
packets with source port 547 (server) and destination port 546 (client). packets with source port 547 (server) and destination port 546 (client).

10
docs/configexamples/tunnelbroker-ipv6.rst
View File

@ -1,3 +1,5 @@
:lastproofread: 2021-06-29
.. _examples-tunnelbroker-ipv6: .. _examples-tunnelbroker-ipv6:
.. stop_vyoslinter .. stop_vyoslinter
@ -6,7 +8,7 @@
Tunnelbroker.net (IPv6) Tunnelbroker.net (IPv6)
####################### #######################
This guides walks through the setup of https://www.tunnelbroker.net/ for an This guide walks through the setup of https://www.tunnelbroker.net/ for an
IPv6 Tunnel. IPv6 Tunnel.
Prerequisites Prerequisites
@ -78,12 +80,12 @@ You should now be able to ping something by IPv6 DNS name:
2 packets transmitted, 2 received, 0% packet loss, time 1001ms 2 packets transmitted, 2 received, 0% packet loss, time 1001ms
rtt min/avg/max/mdev = 16.880/17.153/17.426/0.273 ms rtt min/avg/max/mdev = 16.880/17.153/17.426/0.273 ms
Assuming everything works, you can proceed to client configuration Assuming everything works, you can proceed to the client configuration
LAN Configuration LAN Configuration
================= =================
At this point your VyOS install should have full IPv6, but now your LAN devices At this point, your VyOS install should have full IPv6, but now your LAN devices
need access. need access.
With Tunnelbroker.net, you have two options: With Tunnelbroker.net, you have two options:
@ -140,7 +142,7 @@ The format of these addresses:
In the above examples, 1,2,ffff are all chosen by you. You can use 1-ffff In the above examples, 1,2,ffff are all chosen by you. You can use 1-ffff
(1-65535). (1-65535).
So, when your LAN is eth1, your DMZ is eth2, your cameras live on eth3, etc: So, when your LAN is eth1, your DMZ is eth2, your cameras are on eth3, etc:
.. code-block:: none .. code-block:: none

25
docs/configexamples/wan-load-balancing.rst
View File

@ -1,3 +1,5 @@
:lastproofread: 2021-06-29
.. _wan-load-balancing: .. _wan-load-balancing:
.. stop_vyoslinter # pictures and text have to change .. stop_vyoslinter # pictures and text have to change
@ -65,21 +67,20 @@ Configure the WAN load balancer with the parameters described above:
Example 2: Failover based on interface weights Example 2: Failover based on interface weights
---------------------------------------------- ----------------------------------------------
This examples uses the failover mode. This example uses the failover mode.
.. _wan:example2_overwiew: .. _wan:example2_overwiew:
Overview Overview
^^^^^^^^ ^^^^^^^^
In this example eth0 is the primary interface and eth1 is the secondary In this example, eth0 is the primary interface and eth1 is the secondary
interface to provide simple failover functionality. If eth0 fails, eth1 interface. To provide simple failover functionality. If eth0 fails, eth1
takes over. takes over.
Create interface weight based configuration Create interface weight based configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The configuration steps are the same as in the previous example, except 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 rule 10. So we keep the configuration, remove rule 10 and add a new rule
for the failover mode: for the failover mode:
.. code-block:: none .. code-block:: none
@ -93,8 +94,8 @@ for the failover mode:
Example 3: Failover based on rule order Example 3: Failover based on rule order
--------------------------------------- ---------------------------------------
The previous example used the failover command to send traffic thorugh The previous example used the failover command to send traffic through
eth1 if eth0 fails. In this example failover functionality is provided eth1 if eth0 fails. In this example, failover functionality is provided
by rule order. by rule order.
.. _wan:example3_overwiew: .. _wan:example3_overwiew:
@ -108,7 +109,7 @@ directing traffic to eth1.
Create rule order based configuration Create rule order based configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
We keep the configurtation from the previous example, delete rule 10 We keep the configuration from the previous example, delete rule 10
and create the two new rules as described: and create the two new rules as described:
.. code-block:: none .. code-block:: none
@ -122,20 +123,20 @@ and create the two new rules as described:
Example 4: Failover based on rule order - priority traffic Example 4: Failover based on rule order - priority traffic
---------------------------------------------------------- ----------------------------------------------------------
A rule order for prioritising traffic is useful in scenarios where the A rule order for prioritizing traffic is useful in scenarios where the
secondary link has a lower speed and should only carry high priority 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 traffic. It is assumed for this example that eth1 is connected to a
slower connection than eth0 and should prioritise VoIP traffic. slower connection than eth0 and should prioritize VoIP traffic.
.. _wan:example4_overwiew: .. _wan:example4_overwiew:
Overview Overview
^^^^^^^^ ^^^^^^^^
A rule order for prioritising traffic is useful in scenarios where the A rule order for prioritizing traffic is useful in scenarios where the
secondary link has a lower speed and should only carry high priority 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 traffic. It is assumed for this example that eth1 is connected to a
slower connection than eth0 and should prioritise VoIP traffic. slower connection than eth0 and should prioritize VoIP traffic.
Create rule order based configuration with low speed secondary link Create rule order based configuration with low speed secondary link
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

6
docs/configexamples/zone-policy.rst
View File

@ -1,3 +1,5 @@
:lastproofread: 2021-06-29
.. _examples-zone-policy: .. _examples-zone-policy:
Zone-Policy example Zone-Policy example
@ -132,7 +134,7 @@ To add logging to the default rule, do:
set firewall name <ruleSet> enable-default-log set firewall name <ruleSet> enable-default-log
By default, iptables does not allow traffic for established session to By default, iptables does not allow traffic for established sessions to
return, so you must explicitly allow this. I do this by adding two rules return, so you must explicitly allow this. I do this by adding two rules
to every ruleset. 1 allows established and related state packets through to every ruleset. 1 allows established and related state packets through
and rule 2 drops and logs invalid state packets. We place the and rule 2 drops and logs invalid state packets. We place the
@ -367,7 +369,7 @@ IPv6 Tunnel
^^^^^^^^^^^ ^^^^^^^^^^^
If you are using a IPv6 tunnel from HE.net or someone else, the basis is If you are using a IPv6 tunnel from HE.net or someone else, the basis is
the same except you have two WAN interface. One for v4 and one for v6. the same except you have two WAN interfaces. One for v4 and one for v6.
You would have 5 zones instead of just 4 and you would configure your v6 You would have 5 zones instead of just 4 and you would configure your v6
ruleset between your tunnel interface and your LAN/DMZ zones instead of ruleset between your tunnel interface and your LAN/DMZ zones instead of

143
docs/configuration/container/index.rst Normal file
View File

@ -0,0 +1,143 @@
.. include:: /_include/need_improvement.txt
.. _container:
#########
Container
#########
*************
Configuration
*************
.. cfgcmd:: set container <name>
Set an named container.
.. cfgcmd:: set container network <networkname>
Creates a named container network
.. cfgcmd:: set container registry <name>
Adds registry to list of unqualified-search-registries. By default, for any
image that does not include the registry in the image name, Vyos will use
docker.io as the container registry.
.. cfgcmd:: set container <name> image
Sets the image name in the hub registry
.. code-block:: none
set container name mysql-server image mysql:8.0
If a registry is not specefied, Docker.io will be used as the container
registry unless an alternative registry is specefied using
**set container registry <name>** or the registry is included in the image name
.. code-block:: none
set container name mysql-server image quay.io/mysql:8.0
.. cfgcmd:: set container <name> allow-host-networks
Allow host networking in container. The network stack of the container is
not isolated from the host and will use the host IP.
The following commands translates to "--net host" when the container is created
.. note:: **allow-host-networks** cannot be used with **network**
.. cfgcmd:: set container <name> description <text>
Sets the container description
.. cfgcmd:: set container <name> environment '<key>' value '<value>'
Adds a custom environment variables. Multiple enviroment variables are allowed. The following commands translates to "-e key=value" when container is created.
.. code-block:: none
set container name mysql-server environment 'MYSQL_DATABASE' value 'zabbix'
set container name mysql-server environment 'MYSQL_USER' value 'zabbix'
set container name mysql-server environment 'MYSQL_PASSWORD' value 'zabbix_pwd'
set container name mysql-server environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd'
.. cfgcmd:: set container <name> network <networkname>
Attaches user defined network to container. Only one network must be specefied and must already exist.
Optionally a specific static IPv4 or IPv6 address can be set for the container. This address must be within the named network.
.. code-block:: none
set container <name> network <networkname> address <address>
.. note:: The first IP in the container network is reserved by the engine and cannot be used
.. cfgcmd:: set container <name> port <portname> [source | destination ] <portnumber>
Publishes a port for the container
.. code-block:: none
set container name zabbix-web-nginx-mysql port http source 80
set container name zabbix-web-nginx-mysql port http destination 8080
.. cfgcmd:: set container <name> volume <volumename> [source | destination ] <path>
Mount a volume into the container
.. code-block:: none
set container name coredns volume 'corefile' source /config/coredns/Corefile
set container name coredns volume 'corefile' destination /etc/Corefile
*********************
Example Configuration
*********************
For the sake of demonstration, `example #1 in the official documentation <https://www.zabbix.com/documentation/current/manual/installation/containers>`_ to the declarative VyOS CLI syntax.
.. code-block:: none
set container network zabbix-net prefix 172.20.0.0/16
set container network zabbix-net description 'Network for Zabbix component containers'
set container name mysql-server image mysql:8.0
set container name mysql-server network zabbix-net
set container name mysql-server environment 'MYSQL_DATABASE' value 'zabbix'
set container name mysql-server environment 'MYSQL_USER' value 'zabbix'
set container name mysql-server environment 'MYSQL_PASSWORD' value 'zabbix_pwd'
set container name mysql-server environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd'
set container name zabbix-java-gateway image zabbix/zabbix-java-gateway:alpine-5.2-latest
set container name zabbix-java-gateway network zabbix-net
set container name zabbix-server-mysql image zabbix/zabbix-server-mysql:alpine-5.2-latest
set container name zabbix-server-mysql network zabbix-net
set container name zabbix-server-mysql environment 'DB_SERVER_HOST' value 'mysql-server'
set container name zabbix-server-mysql environment 'MYSQL_DATABASE' value 'zabbix'
set container name zabbix-server-mysql environment 'MYSQL_USER' value 'zabbix'
set container name zabbix-server-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd'
set container name zabbix-server-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd'
set container name zabbix-server-mysql environment 'ZBX_JAVAGATEWAY' value 'zabbix-java-gateway'
set container name zabbix-server-mysql port zabbix source 10051
set container name zabbix-server-mysql port zabbix destination 10051
set container name zabbix-web-nginx-mysql image zabbix/zabbix-web-nginx-mysql:alpine-5.2-latest
set container name zabbix-web-nginx-mysql network zabbix-net
set container name zabbix-web-nginx-mysql environment 'MYSQL_DATABASE' value 'zabbix'
set container name zabbix-web-nginx-mysql environment 'ZBX_SERVER_HOST' value 'zabbix-server-mysql'
set container name zabbix-web-nginx-mysql environment 'DB_SERVER_HOST' value 'mysql-server'
set container name zabbix-web-nginx-mysql environment 'MYSQL_USER' value 'zabbix'
set container name zabbix-web-nginx-mysql environment 'MYSQL_PASSWORD' value 'zabbix_pwd'
set container name zabbix-web-nginx-mysql environment 'MYSQL_ROOT_PASSWORD' value 'root_pwd'
set container name zabbix-web-nginx-mysql port http source 80
set container name zabbix-web-nginx-mysql port http destination 8080

60
docs/configuration/firewall/index.rst
View File

@ -1,3 +1,5 @@
:lastproofread: 2021-06-29
.. _firewall: .. _firewall:
######## ########
@ -29,7 +31,7 @@ or zone based firewall policy.
Global settings Global settings
*************** ***************
Some firewall settings are global and have a affect on the whole system. Some firewall settings are global and have an affect on the whole system.
.. cfgcmd:: set firewall all-ping [enable | disable] .. cfgcmd:: set firewall all-ping [enable | disable]
@ -89,7 +91,7 @@ Some firewall settings are global and have a affect on the whole system.
.. cfgcmd:: set firewall send-redirects [enable | disable] .. cfgcmd:: set firewall send-redirects [enable | disable]
enable or disable of ICMPv4 redirect messages send by VyOS enable or disable ICMPv4 redirect messages send by VyOS
The following system parameter will be altered: The following system parameter will be altered:
* ``net.ipv4.conf.all.send_redirects`` * ``net.ipv4.conf.all.send_redirects``
@ -127,7 +129,7 @@ Some firewall settings are global and have a affect on the whole system.
.. cfgcmd:: set firewall state-policy established log enable .. cfgcmd:: set firewall state-policy established log enable
Set the global setting for a established connections. Set the global setting for an established connection.
.. cfgcmd:: set firewall state-policy invalid action [accept | drop | reject] .. cfgcmd:: set firewall state-policy invalid action [accept | drop | reject]
@ -163,8 +165,8 @@ names.
Address Groups Address Groups
============== ==============
In a **address group** a single IP adresses or IP address ranges are In an **address group** a single IP address or IP address ranges are
definded. defined.
.. cfgcmd:: set firewall group address-group <name> address [address | .. cfgcmd:: set firewall group address-group <name> address [address |
address range] address range]
@ -221,7 +223,7 @@ filtering unnecessary ports. Ranges of ports can be specified by using
.. cfgcmd:: set firewall group port-group <name> port .. cfgcmd:: set firewall group port-group <name> port
[portname | portnumber | startport-endport] [portname | portnumber | startport-endport]
Define a port group. A port name are any name defined in Define a port group. A port name can be any name defined in
/etc/services. e.g.: http /etc/services. e.g.: http
.. code-block:: none .. code-block:: none
@ -240,10 +242,10 @@ Rule-Sets
********* *********
A rule-set is a named collection of firewall rules that can be applied A rule-set is a named collection of firewall rules that can be applied
to an interface or zone. Each rule is numbered, has an action to apply to an interface or a zone. Each rule is numbered, has an action to apply
if the rule is matched, and the ability to specify the criteria to if the rule is matched, and the ability to specify the criteria to
match. Data packets go through the rules from 1 - 9999, at the first match match. Data packets go through the rules from 1 - 9999, at the first match
the action of the rule will executed. the action of the rule will be executed.
.. cfgcmd:: set firewall name <name> description <text> .. cfgcmd:: set firewall name <name> description <text>
.. cfgcmd:: set firewall ipv6-name <name> description <text> .. cfgcmd:: set firewall ipv6-name <name> description <text>
@ -267,7 +269,7 @@ the action of the rule will executed.
.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> action [drop | reject | .. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> action [drop | reject |
accept] accept]
This required setting define the action of the current rule. This required setting defines the action of the current rule.
.. cfgcmd:: set firewall name <name> rule <1-9999> description <text> .. cfgcmd:: set firewall name <name> rule <1-9999> description <text>
.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> description <text> .. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> description <text>
@ -287,7 +289,7 @@ the action of the rule will executed.
Matching criteria Matching criteria
================= =================
There are a lot of matching criteria gainst which the package can be tested. There are a lot of matching criteria against which the package can be tested.
.. cfgcmd:: set firewall name <name> rule <1-9999> source address .. cfgcmd:: set firewall name <name> rule <1-9999> source address
@ -299,7 +301,7 @@ There are a lot of matching criteria gainst which the package can be tested.
.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> destination address .. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> destination address
[address | addressrange | CIDR] [address | addressrange | CIDR]
This is similiar to the network groups part, but here you are able to negate This is similar to the network groups part, but here you are able to negate
the matching addresses. the matching addresses.
.. code-block:: none .. code-block:: none
@ -315,7 +317,7 @@ There are a lot of matching criteria gainst which the package can be tested.
.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> source mac-address .. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> source mac-address
<mac-address> <mac-address>
Only in the source criteria you can specify a mac-address Only in the source criteria, you can specify a mac-address.
.. code-block:: none .. code-block:: none
@ -331,7 +333,7 @@ There are a lot of matching criteria gainst which the package can be tested.
.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> destination port .. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> destination port
[1-65535 | portname | start-end] [1-65535 | portname | start-end]
A port can be set with a portnumber or a name which is here A port can be set with a port number or a name which is here
defined: ``/etc/services``. defined: ``/etc/services``.
.. code-block:: none .. code-block:: none
@ -410,9 +412,9 @@ There are a lot of matching criteria gainst which the package can be tested.
set firewall name WAN-IN-v4 rule 13 tcp flags 'SYN,!ACK,!FIN,!RST' set firewall name WAN-IN-v4 rule 13 tcp flags 'SYN,!ACK,!FIN,!RST'
.. cfgcmd:: set firewall name <name> rule <1-9999> state [established | .. cfgcmd:: set firewall name <name> rule <1-9999> state [established |
invalid | new | related] [enable | disable ] invalid | new | related] [enable | disable]
.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> state [established | .. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> state [established |
invalid | new | related] [enable | disable ] invalid | new | related] [enable | disable]
Match against the state of a packet. Match against the state of a packet.
@ -423,8 +425,8 @@ Applying a Rule-Set to an Interface
A Rule-Set can be applied to every interface: A Rule-Set can be applied to every interface:
* ``in``: Ruleset for forwarded packets on inbound interface * ``in``: Ruleset for forwarded packets on an inbound interface
* ``out``: Ruleset for forwarded packets on outbound interface * ``out``: Ruleset for forwarded packets on an outbound interface
* ``local``: Ruleset for packets destined for this router * ``local``: Ruleset for packets destined for this router
.. cfgcmd:: set interface ethernet <ethN> firewall [in | out | local] .. cfgcmd:: set interface ethernet <ethN> firewall [in | out | local]
@ -451,7 +453,7 @@ Zone-based Firewall Policy
As an alternative to applying policy to an interface directly, a As an alternative to applying policy to an interface directly, a
zone-based firewall can be created to simplify configuration when zone-based firewall can be created to simplify configuration when
multiple interfaces belong to the same security zone. Instead of multiple interfaces belong to the same security zone. Instead of
applying rulesets to interfaces, they are applied to source applying rule-sets to interfaces, they are applied to source
zone-destination zone pairs. zone-destination zone pairs.
An basic introduction to zone-based firewalls can be found `here An basic introduction to zone-based firewalls can be found `here
@ -465,12 +467,12 @@ To define a zone setup either one with interfaces or a local zone.
.. cfgcmd:: set zone-policy zone <name> interface <interfacenames> .. cfgcmd:: set zone-policy zone <name> interface <interfacenames>
Set a interfaces to a zone. A zone can have multiple interfaces. Set interfaces to a zone. A zone can have multiple interfaces.
But a interface can only be member in one zone. But an interface can only be a member in one zone.
.. cfgcmd:: set zone-policy zone <name> local-zone .. cfgcmd:: set zone-policy zone <name> local-zone
Define the Zone as a local zone. A local zone have no interfaces and Define the zone as a local zone. A local zone has no interfaces and
will be applied to the router itself. will be applied to the router itself.
.. cfgcmd:: set zone-policy zone <name> default-action [drop | reject] .. cfgcmd:: set zone-policy zone <name> default-action [drop | reject]
@ -486,14 +488,14 @@ Applying a Rule-Set to a Zone
============================= =============================
Before you are able to apply a rule-set to a zone you have to create the zones Before you are able to apply a rule-set to a zone you have to create the zones
first. first.
.. cfgcmd:: set zone-policy zone <name> from <name> firewall name .. cfgcmd:: set zone-policy zone <name> from <name> firewall name
<rule-set> <rule-set>
.. cfgcmd:: set zone-policy zone <name> from <name> firewall ipv6-name .. cfgcmd:: set zone-policy zone <name> from <name> firewall ipv6-name
<rule-set> <rule-set>
You apply a rule-set always to a zone from a other zone, it is recommended You apply a rule-set always to a zone from an other zone, it is recommended
to create one rule-set for each zone pair. to create one rule-set for each zone pair.
.. code-block:: none .. code-block:: none
@ -577,7 +579,7 @@ Rule-set overview
.. opcmd:: show firewall summary .. opcmd:: show firewall summary
This will show you a summary about rule-sets and groups This will show you a summary of rule-sets and groups
.. code-block:: none .. code-block:: none
@ -630,7 +632,7 @@ Rule-set overview
.. opcmd:: show firewall [name | ipv6name] <name> rule <1-9999> .. opcmd:: show firewall [name | ipv6name] <name> rule <1-9999>
This command will give an overview about a rule in a single rule-set This command will give an overview of a rule in a single rule-set
.. opcmd:: show firewall group <name> .. opcmd:: show firewall group <name>
@ -658,7 +660,7 @@ Rule-set overview
.. opcmd:: show firewall [name | ipv6name] <name> .. opcmd:: show firewall [name | ipv6name] <name>
This command will give an overview about a single rule-set This command will give an overview of a single rule-set.
.. opcmd:: show firewall [name | ipv6name] <name> statistics .. opcmd:: show firewall [name | ipv6name] <name> statistics
@ -666,7 +668,7 @@ Rule-set overview
.. opcmd:: show firewall [name | ipv6name] <name> rule <1-9999> .. opcmd:: show firewall [name | ipv6name] <name> rule <1-9999>
This command will give an overview about a rule in a single rule-set This command will give an overview of a rule in a single rule-set.
Zone-Policy Overview Zone-Policy Overview
@ -674,7 +676,7 @@ Zone-Policy Overview
.. opcmd:: show zone-policy zone <name> .. opcmd:: show zone-policy zone <name>
Use this command to get an overview about a zone Use this command to get an overview of a zone.
.. code-block:: none .. code-block:: none
@ -695,7 +697,7 @@ Show Firewall log
.. opcmd:: show log firewall [name | ipv6name] <name> .. opcmd:: show log firewall [name | ipv6name] <name>
Show the logs of a specific Rule-Set Show the logs of a specific Rule-Set.
.. note:: .. note::
At the moment it not possible to look at the whole firewall log with VyOS At the moment it not possible to look at the whole firewall log with VyOS

3
docs/configuration/index.rst
View File

@ -8,6 +8,7 @@ The following structure respresent the cli structure.
:maxdepth: 1 :maxdepth: 1
:includehidden: :includehidden:
container/index
firewall/index firewall/index
highavailability/index highavailability/index
interfaces/index interfaces/index
@ -20,4 +21,4 @@ The following structure respresent the cli structure.
trafficpolicy/index trafficpolicy/index
vpn/index vpn/index
vrf/index vrf/index
zonepolicy/index zonepolicy/index

30
docs/configuration/service/ssh.rst
View File

@ -156,3 +156,33 @@ Operation
Two new files ``/config/auth/id_rsa_rpki`` and Two new files ``/config/auth/id_rsa_rpki`` and
``/config/auth/id_rsa_rpki.pub`` ``/config/auth/id_rsa_rpki.pub``
will be created. will be created.
.. opcmd:: generate public-key-commands name <username> path <location>
Generate the configuration mode commands to add a public key for
:ref:`ssh_key_based_authentication`.
``<location>`` can be a local path or a URL pointing at a remote file.
Supported remote protocols are FTP, HTTP, HTTPS, SCP/SFTP and TFTP.
Example:
.. code-block:: none
alyssa@vyos:~$ generate public-key-commands name alyssa path sftp://example.net/home/alyssa/.ssh/id_rsa.pub
# To add this key as an embedded key, run the following commands:
configure
set system login user alyssa authentication public-keys alyssa@example.net key AAA...
set system login user alyssa authentication public-keys alyssa@example.net type ssh-rsa
commit
save
exit
ben@vyos:~$ generate public-key-command user ben path ~/.ssh/id_rsa.pub
# To add this key as an embedded key, run the following commands:
configure
set system login user ben authentication public-keys ben@vyos key AAA...
set system login user ben authentication public-keys ben@vyos type ssh-dss
commit
save
exit

4
docs/configuration/system/login.rst
View File

@ -76,6 +76,10 @@ The third part is simply an identifier, and is for your own reference.
.. cfgcmd:: loadkey <username> <location> .. cfgcmd:: loadkey <username> <location>
**Deprecation notice:** ``loadkey`` has been deprecated in favour of
:opcmd:`generate public-key-commands` and will be removed in a future
version. See :ref:`ssh`.
SSH keys can not only be specified on the command-line but also loaded for SSH keys can not only be specified on the command-line but also loaded for
a given user with `<username>` from a file pointed to by `<location>.` Keys a given user with `<username>` from a file pointed to by `<location>.` Keys
can be either loaded from local filesystem or any given remote location can be either loaded from local filesystem or any given remote location

68
docs/documentation.rst
View File

@ -1,3 +1,5 @@
:lastproofread: 2021-06-25
.. _documentation: .. _documentation:
############# #############
@ -5,7 +7,7 @@ Documentation
############# #############
We encourage every VyOS user to help us improve our documentation as we have We encourage every VyOS user to help us improve our documentation as we have
a deficit like most software projects. This not only be helps you when reading, a deficit like most software projects. This not only helps you when reading
but also everyone else. but also everyone else.
If you are willing to contribute to our documentation this is the definite If you are willing to contribute to our documentation this is the definite
@ -18,7 +20,7 @@ guide how to do so.
Forking Workflow Forking Workflow
================ ================
The Forking Workflow is fundamentally different than other popular Git The Forking Workflow is fundamentally different from other popular Git
workflows. Instead of using a single server-side repository to act as the workflows. Instead of using a single server-side repository to act as the
"central" codebase, it gives every developer their own server-side repository. "central" codebase, it gives every developer their own server-side repository.
This means that each contributor has not one, but two Git repositories: a This means that each contributor has not one, but two Git repositories: a
@ -42,7 +44,7 @@ access to the official codebase.
* Install the requirements ``$ pip install -r requirements.txt`` * Install the requirements ``$ pip install -r requirements.txt``
(or something similar) (or something similar)
* Create new branch for your work, use a descriptive name of your work: * Create a new branch for your work, use a descriptive name of your work:
``$ git checkout -b <branch-name>`` ``$ git checkout -b <branch-name>``
* Make all your changes - please keep our commit rules in mind * Make all your changes - please keep our commit rules in mind
@ -54,7 +56,7 @@ access to the official codebase.
* Check your changes by locally building the documentation ``$ make html``. * Check your changes by locally building the documentation ``$ make html``.
Sphinx will build the html files in the ``docs/_build`` folder. We provide Sphinx will build the html files in the ``docs/_build`` folder. We provide
you with a Docker container for an easy to use user experience. Check the you with a Docker container for an easy-to-use user experience. Check the
README.md_ file of this repository. README.md_ file of this repository.
* View modified files by calling ``$ git status``. You will get an overview of * View modified files by calling ``$ git status``. You will get an overview of
@ -67,7 +69,7 @@ access to the official codebase.
* Commit your changes with the message, ``$ git commit -m "<commit message>"`` * Commit your changes with the message, ``$ git commit -m "<commit message>"``
or use ``$ git commit -v`` to have your configured editor launched. You can 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 type in a commit message. Again please make yourself comfortable without
rules (:ref:`prepare_commit`). rules (:ref:`prepare_commit`).
* Push commits to your GitHub project: ``$ git push -u origin <branch-name>`` * Push commits to your GitHub project: ``$ git push -u origin <branch-name>``
@ -76,7 +78,7 @@ access to the official codebase.
see a banner suggesting to make a pull request. Fill out the form and see a banner suggesting to make a pull request. Fill out the form and
describe what you do. describe what you do.
* Once pull resquests have been approved, you may want to locally update * Once pull requests have been approved, you may want to locally update
your forked repository too. First you'll have to add a second remote your forked repository too. First you'll have to add a second remote
called `upstream` which points to our main repository. ``$ git remote add called `upstream` which points to our main repository. ``$ git remote add
upstream https://github.com/vyos/vyos-documentation.git`` upstream https://github.com/vyos/vyos-documentation.git``
@ -141,7 +143,7 @@ Cross-References
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
A plugin will be used to generate a reference label for each headline. A plugin will be used to generate a reference label for each headline.
to reference a page or a section in the documentation use the To reference a page or a section in the documentation use the
``:ref:`` command. ``:ref:`` command.
For example, you want to reference the headline **VLAN** in the For example, you want to reference the headline **VLAN** in the
@ -150,7 +152,7 @@ the headline and the file path.
``:ref:`configuration/interfaces/ethernet:vlan`` ``:ref:`configuration/interfaces/ethernet:vlan``
to use a alternative Hyperlink use it this way: to use an alternative hyperlink use it this way:
``:ref:`Check out VLAN<configuration/interfaces/ethernet:vlan>`` ``:ref:`Check out VLAN<configuration/interfaces/ethernet:vlan>``
@ -158,10 +160,10 @@ handle build errors
""""""""""""""""""" """""""""""""""""""
The plugin will warn on build if a headline has a duplicate name in the The plugin will warn on build if a headline has a duplicate name in the
same document. To prevent this warning you have to put a custom link on same document. To prevent this warning, you have to put a custom link on
top of the headline. top of the headline.
.. code-block:: .. code-block:: none
Section A Section A
========== ==========
@ -186,10 +188,6 @@ top of the headline.
Lorem ipsum dolor sit amet, consetetur sadipscing elitr Lorem ipsum dolor sit amet, consetetur sadipscing elitr
Address space Address space
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
@ -221,10 +219,10 @@ renders the same line format from the source rst file.
Autolinter Autolinter
^^^^^^^^^^ ^^^^^^^^^^
Each GitHub Pull request is automatically linted to check the Address space and Each GitHub pull request is automatically linted to check the address space and
line length. line length.
Sometimes it is necessary to provide real IP Addresses like in the Sometimes it is necessary to provide real IP addresses like in the
:ref:`examples`. For this, please use the sphinx comment syntax :ref:`examples`. For this, please use the sphinx comment syntax
``.. stop_vyoslinter`` to stop the linter and ``.. start_vyoslinter`` to start. ``.. stop_vyoslinter`` to stop the linter and ``.. start_vyoslinter`` to start.
@ -242,19 +240,19 @@ cfgcmd
When documenting CLI commands, use the ``.. cfgcmd::`` directive When documenting CLI commands, use the ``.. cfgcmd::`` directive
for all configuration mode commands. An explanation of the described command for all configuration mode commands. An explanation of the described command
should be added below this statement. should be added below this statement.
Replace all variable contents with <value> or somthing similar. Replace all variable contents with <value> or something similar.
With those custom commands it will be possible to render them in a more With those custom commands, it will be possible to render them in a more
descriptive way in the resulting HTML/PDF manual. descriptive way in the resulting HTML/PDF manual.
.. code-block:: none .. code-block:: none
.. cfgcmd:: protocols static arp <ipaddress> hwaddr <macaddress> .. cfgcmd:: protocols static arp <ipaddress> hwaddr <macaddress>
This will configure a static ARP entry always resolving `192.0.2.100` to This will configure a static ARP entry, always resolving `192.0.2.100` to
`00:53:27:de:23:aa`. `00:53:27:de:23:aa`.
For a inline configuration level command, use ``:cfgcmd:`` For an inline configuration level command, use ``:cfgcmd:``
.. code-block:: none .. code-block:: none
@ -275,7 +273,7 @@ descriptive way in the resulting HTML/PDF manual.
Display all known ARP table entries spanning across all interfaces Display all known ARP table entries spanning across all interfaces
For a inline operational level command, use ``:opcmd:`` For an inline operational level command, use ``:opcmd:``
.. code-block:: none .. code-block:: none
@ -284,8 +282,8 @@ For a inline operational level command, use ``:opcmd:``
cmdinclude cmdinclude
"""""""""" """"""""""
To minimize redundancy, there is a special include directive. It include a txt To minimize redundancy, there is a special include directive. It includes a txt
file and replace the ``{{ var0 }}`` - ``{{ var9 }}`` with the correct value file and replace the ``{{ var0 }}`` - ``{{ var9 }}`` with the correct value.
.. code-block:: none .. code-block:: none
@ -348,44 +346,44 @@ All RST files must follow the same TOC Level syntax and have to start with
Configuration mode pages Configuration mode pages
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
A configuration mode folder and article covers a specific level of a command. The configuration mode folder and the articles cover the specific level of
The exact level depends on the command. This should provide stability for URLs the commands. The exact level depends on the command. This should provide
used in the forum or blogpost. stability for URLs used in the forum or blogpost.
For example: For example:
* ``set zone-policy`` is written in ``zone-policy/index.rst`` * ``set zone-policy`` is written in ``zone-policy/index.rst``
* ``set interfaces ethernet`` is written in ``interfaces/ethernet.rst`` * ``set interfaces ethernet`` is written in ``interfaces/ethernet.rst``
The article starts with a short intruducing about the command or the The article starts with a short introduction about the command or the
technologie. Please include some helpfull links or background informations. technology. Please include some helpful links or background information.
An optional section follows. Some commands have requirements like compatible An optional section follows. Some commands have requirements like compatible
hardware (e.g. Wifi) or some commands you have to set before. For hardware (e.g. Wifi) or some commands you have to set before. For
example, it is recommended to set a route-map before configure BGP. example, it is recommended to set a route-map before configuring BGP.
In the configuration part of the page, all possible confiuration options In the configuration part of the page, all possible configuration options
should be documented. Use ``.. cfgcmd::`` described above. should be documented. Use ``.. cfgcmd::`` described above.
Related Operation command must be documented in the next part of the article. Related operation command must be documented in the next part of the article.
Use ``::opcmd..`` for these commands. Use ``::opcmd..`` for these commands.
If there some troubleshooting guides releated to the commands. Explain it in the If there some troubleshooting guides related to the commands. Explain it in the
next optional part. next optional part.
Operation mode pages Operation mode pages
^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^
Operation mode commands that does not fit in a related configuraton mode command Operation mode commands that do not fit in a related configuration mode command
must be documented in this part of the documentation. must be documented in this part of the documentation.
General concepts for troubleshooting, and detailed process descriptions belong General concepts for troubleshooting and detailed process descriptions belong
here. here.
Anything else Anything else
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
Anything else that is not a configuration or an operation command have no Anything else that is not a configuration or an operation command has no
predefined structure. predefined structure.

6
docs/installation/install.rst
View File

@ -35,7 +35,7 @@ Building from source
---------------------- ----------------------
Non-subscribers can always get the LTS release by building it from source. Non-subscribers can always get the LTS release by building it from source.
Instruction can be found in the :ref:`build` section of this manual. VyOS Instructions can be found in the :ref:`build` section of this manual. VyOS
source code repository is available for everyone at source code repository is available for everyone at
https://github.com/vyos/vyos-build. https://github.com/vyos/vyos-build.
@ -58,7 +58,7 @@ https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso
Download Verification Download Verification
--------------------- ---------------------
LTS images are signed by VyOS lead package-maintainer private key. With LTS images are signed by the VyOS lead package-maintainer private key. With
the official public key, the authenticity of the package can be the official public key, the authenticity of the package can be
verified. :abbr:`GPG (GNU Privacy Guard)` is used for verification. verified. :abbr:`GPG (GNU Privacy Guard)` is used for verification.
@ -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 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 functional VyOS system**. Once you have tested it, you can either decide
to begin a :ref:`permanent_installation` in your hard drive or power 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 everything as it was.
If you have a GNU+Linux system, you can create your VyOS bootable USB If you have a GNU+Linux system, you can create your VyOS bootable USB

57
docs/operation/information.rst
View File

@ -94,3 +94,60 @@ For additional details you can refer to https://phabricator.vyos.net/T2490.
usb0b2.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd usb0b2.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd
usb0b2.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd usb0b2.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd
usb0b2.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd usb0b2.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd
.. _information_version:
########
Version
########
.. opcmd:: show version
Return the current running VyOS version and build information. This includes
also the name of the release train which is ``crux`` on VyOS 1.2, ``equuleus``
on VyOS 1.3 and ``sagitta`` on VyOS 1.4.
.. code-block:: none
vyos@vyos:~$ show version
Version: VyOS 1.4-rolling-202106270801
Release Train: sagitta
Built by: autobuild@vyos.net
Built on: Sun 27 Jun 2021 09:50 UTC
Build UUID: ab43e735-edcb-405a-9f51-f16a1b104e52
Build Commit ID: f544d75eab758f
Architecture: x86_64
Boot via: installed image
System type: KVM guest
Hardware vendor: QEMU
Hardware model: Standard PC (i440FX + PIIX, 1996)
Hardware S/N:
Hardware UUID: Unknown
Copyright: VyOS maintainers and contributors
.. opcmd:: show version kernel
Return version number of the Linux Kernel used in this release.
.. code-block:: none
vyos@vyos:~$ show version kernel
5.10.46-amd64-vyos
.. opcmd:: show version frr
Return version number of FRR (Free Range Routing - https://frrouting.org/)
used in this release. This is the routing control plane and a successor to GNU
Zebra and Quagga.
.. code-block:: none
vyos@vyos:~$ show version frr
FRRouting 7.5.1-20210625-00-gf07d935a2 (vyos).
Copyright 1996-2005 Kunihiro Ishiguro, et al.

1
docs/troubleshooting/index.rst
View File

@ -36,6 +36,7 @@ section and are omitted from the output here):
bypass-route bypass-route
count count
deadline deadline
do-not-fragment
flood flood
interface interface
interval interval