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 'vyos:master' into patch-2

Browse Source
This commit is contained in:
ekhudiyev 2021-12-01 12:59:53 +04:00 committed by GitHub
commit 80c25fa38b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
13 changed files with 995 additions and 486 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/_include/vyos-1x

@ -1 +1 @@
Subproject commit 22e3558834784a8ca37f6335c15c58a631a7fe10
Subproject commit b675c8b6187c4b77759e3f96c9c92dd382dabeae

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

@ -19,7 +19,7 @@ VyOS support three types of config sources.
* 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```.
``http://169.254.169.254``.
* Network configuration - This config source informs the system about the
network settings like IP addresses, routes, DNS. Available only in several
cloud and virtualization platforms.
@ -44,13 +44,14 @@ described below.
Cloud-config modules
********************
In VyOS, by default, enabled only two modules:
In VyOS, by default, enables only two modules:
* ``write_files`` - this module allows to insert any files into the filesystem
before the first boot, for example, pre-generated encryption keys,
certificates, or even a whole ``config.boot`` file.
* ``vyos_userdata`` - the module accepts a list of CLI configuration commands in
a ``vyos_config_commands`` section, which gives an easy way to configure the
system during deployment.
************************
@ -169,6 +170,51 @@ obtained from the EC2 metadata service.
commit
exit
*******
NoCloud
*******
Injecting configuration data is not limited to cloud platforms. Users can
employ the NoCloud data source to inject user-data and meta-data on
virtualization platforms such as VMware, Hyper-V and KVM.
While other methods exist, the most straightforward method for using the
NoCloud data source is creating a seed ISO and attaching it to the virtual
machine as a CD drive. The volume must be formatted as a vfat or ISO 9660
file system with the label "cidata" or "CIDATA".
Create text files named user-data and meta-data. On linux-based systems,
the mkisofs utility can be used to create the seed ISO. The following
syntax will add these files to the ISO 9660 file system.
.. code-block:: none
mkisofs -joliet -rock -volid "cidata" -output seed.iso meta-data user-data
The seed.iso file can be attached to the virtual machine. As an example,
the method with KVM to attach the ISO as a CD drive follows.
.. code-block:: none
$ virt-install -n vyos_r1 \
--ram 4096 \
--vcpus 2 \
--cdrom seed.iso \
--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
For more information on the NoCloud data source, visit its
`page <https://cloudinit.readthedocs.io/en/latest/topics/datasources/nocloud.html>`_
in the cloud-init documentation.
***************
Troubleshooting
***************

33
docs/changelog/1.3.rst
View File

@ -8,6 +8,37 @@
_ext/releasenotes.py
2021-11-28
==========
* :vytask:`T3999` (bug): show lldp neighbor Traceback error
2021-11-26
==========
* :vytask:`T4019` (bug): Smoketests for SSTP and openconnect fails
2021-11-25
==========
* :vytask:`T4005` (feature): Feature Request: IPsec IKEv1 + IKEv2 for one peer
2021-11-24
==========
* :vytask:`T4015` (feature): Update Accel-PPP to a newer revision
* :vytask:`T1083` (feature): Implement persistent/random address and port mapping options for NAT rules
2021-11-23
==========
* :vytask:`T3990` (bug): WATCHFRR: crashlog and per-thread log buffering unavailable (due to files left behind in /var/tmp/frr/ after reboot)
2021-11-20
==========
@ -1141,7 +1172,7 @@
2021-02-16
==========
* :vytask:`T3318` (feature): Update Linux Kernel to v5.4.160 / 5.10.80
* :vytask:`T3318` (feature): Update Linux Kernel to v5.4.162 / 5.10.82
2021-02-14

43
docs/changelog/1.4.rst
View File

@ -8,6 +8,47 @@
_ext/releasenotes.py
2021-11-28
==========
* :vytask:`T3999` (bug): show lldp neighbor Traceback error
* :vytask:`T3928` (feature): Add OSPFv3 VRF support
2021-11-27
==========
* :vytask:`T3755` (feature): ospf: adjust to new FRR 8 syntax where "no passive-interface " moved to interface section
* :vytask:`T3753` (feature): frr: upgrade to stable/8.1 release train
2021-11-26
==========
* :vytask:`T3978` (bug): containers add network without declaring prefix raise ConfigError
2021-11-25
==========
* :vytask:`T4006` (default): Add additional Linux capabilities to container configuration
* :vytask:`T3986` (bug): Incorrect description for vpn ipsec site-to-site authentication and connection
2021-11-24
==========
* :vytask:`T4015` (feature): Update Accel-PPP to a newer revision
* :vytask:`T3865` (bug): loadkey command help text missing escape sequence
* :vytask:`T1083` (feature): Implement persistent/random address and port mapping options for NAT rules
2021-11-23
==========
* :vytask:`T3990` (bug): WATCHFRR: crashlog and per-thread log buffering unavailable (due to files left behind in /var/tmp/frr/ after reboot)
2021-11-20
==========
@ -1290,7 +1331,7 @@
==========
* :vytask:`T3313` (bug): ospfv3 interface missing options
* :vytask:`T3318` (feature): Update Linux Kernel to v5.4.160 / 5.10.80
* :vytask:`T3318` (feature): Update Linux Kernel to v5.4.162 / 5.10.82
2021-02-15

105
docs/cli.rst
View File

@ -228,6 +228,111 @@ special way on how to :ref:`run_opmode_from_config_mode`.
.. _`forum`: https://forum.vyos.io
.. opcmd:: show configuration json
View the current active configuration in JSON format.
.. code-block:: none
{"interfaces": {"ethernet": {"eth0": {"address": ["192.0.2.11/24", "192.0.2.35/24"], "hw-id": "52:54:00:48:a0:c6"}, "eth1": {"address": ["203.0.113.1/24"], "hw-id": "52:54:00:fc:50:0b"}}, "loopback": {"lo": {}}}, "protocols": {"static": {"route": {"0.0.0.0/0": {"next-hop": {"192.0.2.254": {}}}}}}, "service": {"ssh": {"disable-host-validation": {}}}, "system": {"config-management": {"commit-revisions": "100"}, "console": {"device": {"ttyS0": {"speed": "115200"}}}, "host-name": "r11-vyos", "login": {"user": {"vyos": {"authentication": {"encrypted-password": "$6$Vt68...F0", "plaintext-password": "", "public-keys": {"vyos@vyos": {"key": "AAAAxxx=", "type": "ssh-rsa"}}}}}}, "name-server": ["203.0.113.254"], "ntp": {"server": {"time1.vyos.net": {}, "time2.vyos.net": {}, "time3.vyos.net": {}}}, "syslog": {"global": {"facility": {"all": {"level": "info"}, "protocols": {"level": "debug"}}}}, "time-zone": "America/New_York"}}
.. opcmd:: show configuration json pretty
View the current active configuration in readable JSON format.
.. code-block:: none
{
"interfaces": {
"ethernet": {
"eth0": {
"address": [
"192.0.2.11/24",
"192.0.2.35/24"
],
"hw-id": "52:54:00:48:a0:c6"
},
"eth1": {
"address": [
"203.0.113.1/24"
],
"hw-id": "52:54:00:fc:50:0b"
}
},
"loopback": {
"lo": {}
}
},
"protocols": {
"static": {
"route": {
"0.0.0.0/0": {
"next-hop": {
"192.0.2.254": {}
}
}
}
}
},
"service": {
"ssh": {
"disable-host-validation": {}
}
},
"system": {
"config-management": {
"commit-revisions": "100"
},
"console": {
"device": {
"ttyS0": {
"speed": "115200"
}
}
},
"host-name": "r11-vyos",
"login": {
"user": {
"vyos": {
"authentication": {
"encrypted-password": "$6$Vt68...F0",
"plaintext-password": "",
"public-keys": {
"vyos@vyos": {
"key": "AAAAxxx=",
"type": "ssh-rsa"
}
}
}
}
}
},
"name-server": [
"203.0.113.254"
],
"ntp": {
"server": {
"time1.vyos.net": {},
"time2.vyos.net": {},
"time3.vyos.net": {}
}
},
"syslog": {
"global": {
"facility": {
"all": {
"level": "info"
},
"protocols": {
"level": "debug"
}
}
}
},
"time-zone": "America/New_York"
}
}
The config mode
---------------

1079
docs/configexamples/autotest/Wireguard/Wireguard.log
View File

File diff suppressed because it is too large Load Diff

32
docs/configexamples/autotest/Wireguard/Wireguard.rst
View File

@ -3,8 +3,8 @@ Wireguard
#########
| Testdate: 2021-11-23
| Version: 1.4-rolling-202106170808
| Testdate: 2021-11-30
| Version: 1.4-rolling-202104132216
This simple structure show how to connect two offices. One remote branch and the
@ -46,7 +46,7 @@ After this, the public key can be displayed, to save for later.
vyos@central:~$ generate wireguard default-keypair
vyos@central:~$ show wireguard keypairs pubkey default
+mLLOGxR37k3EsWba7+G7vIDq6yW4t0s549rNVShWy4=
P9y9TTRzIOVl27Ij9n/BXjZUdQFADZ5WnHV0kQr1ulQ=
After you have each public key. The wireguard interfaces can be setup.
@ -65,6 +65,20 @@ Branch
:lines: 4-11
To reach the network, a route must be set on each VyOS host.
In this structure, a static interface route will fit the requirements.
Central
.. literalinclude:: _include/central.conf
:language: none
:lines: 13
Branch
.. literalinclude:: _include/branch.conf
:language: none
:lines: 13
*********************
Testing and debugging
@ -88,11 +102,11 @@ And ping the Branch PC from your central router to check the response.
vyos@central:~$ ping 10.0.2.100 count 4
PING 10.0.2.100 (10.0.2.100) 56(84) bytes of data.
64 bytes from 10.0.2.100: icmp_seq=1 ttl=63 time=0.609 ms
64 bytes from 10.0.2.100: icmp_seq=2 ttl=63 time=0.871 ms
64 bytes from 10.0.2.100: icmp_seq=3 ttl=63 time=0.937 ms
64 bytes from 10.0.2.100: icmp_seq=4 ttl=63 time=0.746 ms
64 bytes from 10.0.2.100: icmp_seq=1 ttl=63 time=0.526 ms
64 bytes from 10.0.2.100: icmp_seq=2 ttl=63 time=0.583 ms
64 bytes from 10.0.2.100: icmp_seq=3 ttl=63 time=0.873 ms
64 bytes from 10.0.2.100: icmp_seq=4 ttl=63 time=0.753 ms
--- 10.0.2.100 ping statistics ---
4 packets transmitted, 4 received, 0% packet loss, time 4ms
rtt min/avg/max/mdev = 0.609/0.790/0.937/0.130 ms
4 packets transmitted, 4 received, 0% packet loss, time 48ms
rtt min/avg/max/mdev = 0.526/0.683/0.873/0.141 ms

2
docs/configexamples/autotest/Wireguard/_include/branch.conf
View File

@ -7,7 +7,7 @@ set interfaces wireguard wg01 peer central allowed-ips 10.0.1.0/24
set interfaces wireguard wg01 peer central allowed-ips 192.168.0.0/24
set interfaces wireguard wg01 peer central address 198.51.100.1
set interfaces wireguard wg01 peer central port 51820
set interfaces wireguard wg01 peer central pubkey "+mLLOGxR37k3EsWba7+G7vIDq6yW4t0s549rNVShWy4="
set interfaces wireguard wg01 peer central pubkey "P9y9TTRzIOVl27Ij9n/BXjZUdQFADZ5WnHV0kQr1ulQ="
set interfaces wireguard wg01 port 51820
set protocols static route 10.0.1.0/24 interface wg01

2
docs/configexamples/autotest/Wireguard/_include/central.conf
View File

@ -7,7 +7,7 @@ set interfaces wireguard wg01 peer branch allowed-ips 10.0.2.0/24
set interfaces wireguard wg01 peer branch allowed-ips 192.168.0.0/24
set interfaces wireguard wg01 peer branch address 198.51.100.2
set interfaces wireguard wg01 peer branch port 51820
set interfaces wireguard wg01 peer branch pubkey "HF1LJSEgAtknAtkqK2d12DzfuPlx475Y+I4SpJiBWzs="
set interfaces wireguard wg01 peer branch pubkey "iUUItk5zA22azMltN+Kpp7Bh4g2mf1ea3liSEp9eQEs="
set interfaces wireguard wg01 port 51820
set protocols static route 10.0.2.0/24 interface wg01

37
docs/configuration/protocols/ospf.rst
View File

@ -145,12 +145,16 @@ Optional
This command should NOT be set normally.
.. cfgcmd:: set protocols ospf passive-interface <interface>
.. cfgcmd:: set protocols ospf interface <interface> passive [disable]
This command specifies interface as passive. Passive interface advertises
its address, but does not run the OSPF protocol (adjacencies are not formed
and hello packets are not generated).
The optional `disable` option allows to exclude interface from passive state.
This command is used if the command :cfgcmd:`passive-interface default` was
configured.
.. cfgcmd:: set protocols ospf passive-interface default
This command specifies all interfaces as passive by default. Because this
@ -158,11 +162,6 @@ Optional
interfaces where router adjacencies are expected need to be configured
with the :cfgcmd:`passive-interface-exclude` command.
.. cfgcmd:: set protocols ospf passive-interface-exclude <interface>
This command allows exclude interface from passive state. This command is
used if the command :cfgcmd:`passive-interface default` was configured.
.. cfgcmd:: set protocols ospf refresh timers <seconds>
The router automatically updates link-state information with its neighbors.
@ -549,12 +548,12 @@ Operational Mode Commands
This command displays the neighbors information in a detailed form for a
neighbor whose IP address is specified.
.. opcmd:: show ip ospf neighbor <intname>
.. opcmd:: show ip ospf neighbor <interface>
This command displays the neighbors status for a neighbor on the specified
interface.
.. opcmd:: show ip ospf interface [<intname>]
.. opcmd:: show ip ospf interface [<interface>]
This command displays state and configuration of OSPF the specified
interface, or all interfaces if no interface is given.
@ -754,6 +753,8 @@ address and the node 1 sending the default route:
set policy route-map CONNECT rule 10 match interface lo
.. _routing-ospfv3:
*************
OSPFv3 (IPv6)
*************
@ -826,20 +827,20 @@ Area Configuration
Interface Configuration
-----------------------
.. cfgcmd:: set protocols ospfv3 interface <intname> ipv6 cost <number>
.. cfgcmd:: set protocols ospfv3 interface <interface> ipv6 cost <number>
This command sets link cost for the specified interface. The cost value is
set to router-LSA’s metric field and used for SPF calculation. The cost
range is 1 to 65535.
.. cfgcmd:: set protocols ospfv3 interface <intname> dead-interval <number>
.. cfgcmd:: set protocols ospfv3 interface <interface> dead-interval <number>
Set number of seconds for router Dead Interval timer value used for Wait
Timer and Inactivity Timer. This value must be the same for all routers
attached to a common network. The default value is 40 seconds. The
interval range is 1 to 65535.
.. cfgcmd:: set protocols ospfv3 interface <intname> hello-interval
.. cfgcmd:: set protocols ospfv3 interface <interface> hello-interval
<number>
Set number of seconds for Hello Interval timer value. Setting this value,
@ -848,14 +849,14 @@ Interface Configuration
common network. The default value is 10 seconds. The interval range is 1
to 65535.
.. cfgcmd:: set protocols ospfv3 interface <intname> mtu-ignore
.. cfgcmd:: set protocols ospfv3 interface <interface> mtu-ignore
This command disables check of the MTU value in the OSPF DBD packets.
Thus, use of this command allows the OSPF adjacency to reach the FULL
state even though there is an interface MTU mismatch between two OSPF
routers.
.. cfgcmd:: set protocols ospfv3 interface <intname> network <type>
.. cfgcmd:: set protocols ospfv3 interface <interface> network <type>
This command allows to specify the distribution type for the network
connected to this interface:
@ -863,20 +864,20 @@ Interface Configuration
**broadcast** – broadcast IP addresses distribution.
**point-to-point** – address distribution in point-to-point networks.
.. cfgcmd:: set protocols ospfv3 interface <intname> priority <number>
.. cfgcmd:: set protocols ospfv3 interface <interface> priority <number>
This command sets Router Priority integer value. The router with the
highest priority will be more eligible to become Designated Router.
Setting the value to 0, makes the router ineligible to become Designated
Router. The default value is 1. The interval range is 0 to 255.
.. cfgcmd:: set protocols ospfv3 interface <intname> passive
.. cfgcmd:: set protocols ospfv3 interface <interface> passive
This command specifies interface as passive. Passive interface advertises
its address, but does not run the OSPF protocol (adjacencies are not formed
and hello packets are not generated).
.. cfgcmd:: set protocols ospfv3 interface <intname> retransmit-interval
.. cfgcmd:: set protocols ospfv3 interface <interface> retransmit-interval
<number>
This command sets number of seconds for RxmtInterval timer value. This
@ -884,7 +885,7 @@ Interface Configuration
Request packets if acknowledge was not received. The default value is 5
seconds. The interval range is 3 to 65535.
.. cfgcmd:: set protocols ospfv3 interface <intname> transmit-delay
.. cfgcmd:: set protocols ospfv3 interface <interface> transmit-delay
<number>
This command sets number of seconds for InfTransDelay value. It allows to
@ -927,7 +928,7 @@ Operational Mode Commands
This command displays the neighbor DR choice information.
.. opcmd:: show ipv6 ospfv3 interface [prefix]|[<intname> [prefix]]
.. opcmd:: show ipv6 ospfv3 interface [prefix]|[<interface> [prefix]]
This command displays state and configuration of OSPF the specified
interface, or all interfaces if no interface is given. Whith the argument

8
docs/configuration/service/tftp-server.rst
View File

@ -28,6 +28,14 @@ Configure the IPv4 or IPv6 listen address of the TFTP server. Multiple IPv4 and
IPv6 addresses can be given. There will be one TFTP server instances listening
on each IP address.
.. cfgcmd:: set service tftp-server listen-address <address> vrf <name>
.. stop_vyoslinter
Additional option to run TFTP server in the :abbr:`VRF (Virtual Routing and Forwarding)` context
.. start_vyoslinter
.. note:: Configuring a listen-address is essential for the service to work.
.. cfgcmd:: set service tftp-server allow-upload

82
docs/configuration/vpn/ipsec.rst
View File

@ -29,6 +29,88 @@ for the cipher and hash. Adjust this as necessary.
.. NOTE:: VMware users should ensure that a VMXNET3 adapter is used. E1000
adapters have known issues with GRE processing.
**************************************
IKE (Internet Key Exchange) Attributes
**************************************
IKE performs mutual authentication between two parties and establishes
an IKE security association (SA) that includes shared secret information
that can be used to efficiently establish SAs for Encapsulating Security
Payload (ESP) or Authentication Header (AH) and a set of cryptographic
algorithms to be used by the SAs to protect the traffic that they carry.
https://datatracker.ietf.org/doc/html/rfc5996
In VyOS, IKE attributes are specified through IKE groups.
Multiple proposals can be specified in a single group.
VyOS IKE group has the next options:
* ``close-action`` defines the action to take if the remote peer unexpectedly
closes a CHILD_SA:
* ``none`` set action to none (default);
* ``hold`` set action to hold;
* ``clear`` set action to clear;
* ``restart`` set action to restart;
* ``dead-peer-detection`` controls the use of the Dead Peer Detection protocol
(DPD, RFC 3706) where R_U_THERE notification messages (IKEv1) or empty
INFORMATIONAL messages (IKEv2) are periodically sent in order to check the
liveliness of the IPsec peer:
* ``action`` keep-alive failure action:
* ``hold`` set action to hold (default)
* ``clear`` set action to clear;
* ``restart`` set action to restart;
* ``interval`` keep-alive interval in seconds <2-86400> (default 30);
* ``timeout`` keep-alive timeout in seconds <2-86400> (default 120) IKEv1 only
* ``ikev2-reauth`` whether rekeying of an IKE_SA should also reauthenticate
the peer. In IKEv1, reauthentication is always done:
* ``yes`` enable remote host re-authentication during an IKE rekey;
* ``no`` disable remote host re-authenticaton during an IKE rekey;
* ``key-exchange`` which protocol should be used to initialize the connection
If not set both protocols are handled and connections will use IKEv2 when
initiating, but accept any protocol version when responding:
* ``ikev1`` use IKEv1 for Key Exchange;
* ``ikev2`` use IKEv2 for Key Exchange;
* ``lifetime`` IKE lifetime in seconds <30-86400> (default 28800);
* ``mobike`` enable MOBIKE Support. MOBIKE is only available for IKEv2:
* ``enable`` enable MOBIKE (default for IKEv2);
* ``disable`` disable MOBIKE;
* ``mode`` IKEv1 Phase 1 Mode Selection:
* ``main`` use Main mode for Key Exchanges in the IKEv1 Protocol
(Recommended Default);
* ``aggressive`` use Aggressive mode for Key Exchanges in the IKEv1 protocol
aggressive mode is much more insecure compared to Main mode;
* ``proposal`` the list of proposals and their parameters:
* ``dh-group`` dh-group;
* ``encryption`` encryption algorithm;
* ``hash`` hash algorithm.
*************************
IPsec policy matching GRE
*************************

2
docs/configuration/vrf/index.rst
View File

@ -62,6 +62,7 @@ Currently dynamic routing is supported for the following protocols:
- :ref:`routing-bgp`
- :ref:`routing-isis`
- :ref:`routing-ospf`
- :ref:`routing-ospfv3`
- :ref:`routing-static`
The CLI configuration is same as mentioned in above articles. The only
@ -77,6 +78,7 @@ routing protocol inside a given vrf:
- :ref:`routing-bgp`: ``set vrf name <name> protocols bgp ...``
- :ref:`routing-isis`: ``set vrf name <name> protocols isis ...``
- :ref:`routing-ospf`: ``set vrf name <name> protocols ospf ...``
- :ref:`routing-ospfv3`: ``set vrf name <name> protocols ospfv3 ...``
- :ref:`routing-static`: ``set vrf name <name> protocols static ...``
Operation