diff options
Diffstat (limited to 'docs/configuration')
24 files changed, 568 insertions, 140 deletions
diff --git a/docs/configuration/container/index.rst b/docs/configuration/container/index.rst new file mode 100644 index 00000000..ed510477 --- /dev/null +++ b/docs/configuration/container/index.rst @@ -0,0 +1,153 @@ +:lastproofread: 2021-06-30 + +.. include:: /_include/need_improvement.txt + +.. _container: + +######### +Container +######### + +************* +Configuration +************* + +.. cfgcmd:: set container <name> + + Set a 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 specified, Docker.io will be used as the container + registry unless an alternative registry is specified 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 a container. The network stack of the container is + not isolated from the host and will use the host IP. + + The following commands translate 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>' + + Add custom environment variables. + Multiple environment variables are allowed. + The following commands translate to "-e key=value" when the 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 a container. + Only one network must be specified 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
\ No newline at end of file diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst index 667a4653..d52d6f2a 100644 --- a/docs/configuration/firewall/index.rst +++ b/docs/configuration/firewall/index.rst @@ -1,3 +1,5 @@ +:lastproofread: 2021-06-29 + .. _firewall: ######## @@ -29,7 +31,7 @@ or zone based firewall policy. 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] @@ -89,7 +91,7 @@ Some firewall settings are global and have a affect on the whole system. .. 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: * ``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 - 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] @@ -163,8 +165,8 @@ names. Address Groups ============== -In a **address group** a single IP adresses or IP address ranges are -definded. +In an **address group** a single IP address or IP address ranges are +defined. .. cfgcmd:: set firewall group address-group <name> address [address | 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 [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 .. code-block:: none @@ -240,10 +242,10 @@ Rule-Sets ********* 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 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 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 | 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 ipv6-name <name> rule <1-9999> description <text> @@ -287,7 +289,7 @@ the action of the rule will executed. 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 @@ -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 [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. .. 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 <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 @@ -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 [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``. .. 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' .. 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 | - invalid | new | related] [enable | disable ] + invalid | new | related] [enable | disable] 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: -* ``in``: Ruleset for forwarded packets on inbound interface -* ``out``: Ruleset for forwarded packets on outbound interface +* ``in``: Ruleset for forwarded packets on an inbound interface +* ``out``: Ruleset for forwarded packets on an outbound interface * ``local``: Ruleset for packets destined for this router .. 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 zone-based firewall can be created to simplify configuration when 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. 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> - Set a interfaces to a zone. A zone can have multiple interfaces. - But a interface can only be member in one zone. + Set interfaces to a zone. A zone can have multiple interfaces. + But an interface can only be a member in one 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. .. 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 -first. +first. .. cfgcmd:: set zone-policy zone <name> from <name> firewall name <rule-set> .. cfgcmd:: set zone-policy zone <name> from <name> firewall ipv6-name <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. .. code-block:: none @@ -577,7 +579,7 @@ Rule-set overview .. 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 @@ -630,7 +632,7 @@ Rule-set overview .. 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> @@ -658,7 +660,7 @@ Rule-set overview .. 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 @@ -666,7 +668,7 @@ Rule-set overview .. 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 @@ -674,7 +676,7 @@ Zone-Policy Overview .. 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 @@ -695,7 +697,7 @@ Show Firewall log .. opcmd:: show log firewall [name | ipv6name] <name> - Show the logs of a specific Rule-Set + Show the logs of a specific Rule-Set. .. note:: At the moment it not possible to look at the whole firewall log with VyOS diff --git a/docs/configuration/highavailability/index.rst b/docs/configuration/highavailability/index.rst index c3a821c2..884e7065 100644 --- a/docs/configuration/highavailability/index.rst +++ b/docs/configuration/highavailability/index.rst @@ -1,3 +1,5 @@ +:lastproofread: 2021-06-30 + .. _high-availability: High availability @@ -113,7 +115,7 @@ In the following example, when VLAN9 transitions, VLAN20 will also transition: .. warning:: All items in a sync group should be similarly configured. - If one VRRP group is set to a different premption delay or priority, + If one VRRP group is set to a different preemption delay or priority, it would result in an endless transition loop. @@ -157,7 +159,7 @@ rfc3768-compatibility RFC 3768 defines a virtual MAC address to each VRRP virtual router. This virtual router MAC address will be used as the source in all periodic VRRP -messages sent by the active node. When the rfc3768-compatibilty option is set, +messages sent by the active node. When the rfc3768-compatibility option is set, a new VRRP interface is created, to which the MAC address and the virtual IP address is automatically assigned. diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst index bce013cb..0fe481da 100644 --- a/docs/configuration/index.rst +++ b/docs/configuration/index.rst @@ -8,6 +8,7 @@ The following structure respresent the cli structure. :maxdepth: 1 :includehidden: + container/index firewall/index highavailability/index interfaces/index @@ -20,4 +21,4 @@ The following structure respresent the cli structure. trafficpolicy/index vpn/index vrf/index - zonepolicy/index
\ No newline at end of file + zonepolicy/index diff --git a/docs/configuration/interfaces/bonding.rst b/docs/configuration/interfaces/bonding.rst index d19ecb59..13203d15 100644 --- a/docs/configuration/interfaces/bonding.rst +++ b/docs/configuration/interfaces/bonding.rst @@ -1,3 +1,5 @@ +:lastproofread: 2021-06-30 + .. _bond-interface: ####################### @@ -47,7 +49,7 @@ Bond options the :cfgcmd:`hash-policy` option, documented below. .. note:: Not all transmit policies may be 802.3ad compliant, particularly - in regards to the packet mis-ordering requirements of section 43.2.4 + in regards to the packet misordering requirements of section 43.2.4 of the 802.3ad standard. * ``active-backup`` - Active-backup policy: Only one slave in the bond is @@ -133,9 +135,9 @@ Bond options This option only affects 802.3ad mode. - The default value is 0. This will cause carrier to be asserted (for 802.3ad - mode) whenever there is an active aggregator, regardless of the number of - available links in that aggregator. + The default value is 0. This will cause the carrier to be asserted + (for 802.3ad mode) whenever there is an active aggregator, + regardless of the number of available links in that aggregator. .. note:: Because an aggregator cannot be active without at least one available link, setting this option to 0 or to 1 has the exact same @@ -222,7 +224,7 @@ Bond options This algorithm is not fully 802.3ad compliant. A single TCP or UDP conversation containing both fragmented and unfragmented packets will see packets striped across two interfaces. This may result in out of order - delivery. Most traffic types will not meet this criteria, as TCP rarely + delivery. Most traffic types will not meet these criteria, as TCP rarely fragments traffic, and most UDP traffic is not involved in extended conversations. Other implementations of 802.3ad may or may not tolerate this noncompliance. @@ -267,7 +269,7 @@ Bond options be given for ARP monitoring to function. The maximum number of targets that can be specified is 16. The default value - is no IP addresses. + is no IP address. Offloading ---------- @@ -498,9 +500,9 @@ Lets assume the following topology: ! .. note:: When using EVE-NG to lab this environment ensure you are using e1000 - as the desired driver for your VyOS network interfaces. When using the regular - virtio network driver no LACP PDUs will be sent by VyOS thus the port-channel - will never become active! + as the desired driver for your VyOS network interfaces. When using the + regular virtio network driver no LACP PDUs will be sent by VyOS thus the + port-channel will never become active! ********* Operation diff --git a/docs/configuration/interfaces/bridge.rst b/docs/configuration/interfaces/bridge.rst index 7f49f9a8..2374da4d 100644 --- a/docs/configuration/interfaces/bridge.rst +++ b/docs/configuration/interfaces/bridge.rst @@ -1,3 +1,5 @@ +:lastproofread: 2021-06-30 + .. _bridge-interface: ###### @@ -48,7 +50,7 @@ Member Interfaces and a cost, that is used to decide which is the shortest path to forward a packet. The lowest cost path is always used unless the other path is down. If you have multiple bridges and interfaces then - you may need to adjust the priorities to achieve optimium + you may need to adjust the priorities to achieve optimum performance. @@ -71,7 +73,7 @@ Bridge Options Bridge maximum aging `<time>` in seconds (default: 20). - If a another bridge in the spanning tree does not send out a hello + If an another bridge in the spanning tree does not send out a hello packet for a long period of time, it is assumed to be dead. .. cfgcmd:: set interfaces bridge <interface> igmp querier @@ -98,8 +100,8 @@ links providing fault tolerance if an active link fails. Spanning Tree Protocol forwarding `<delay>` in seconds (default: 15). - Forwarding delay time is the time spent in each of the Listening and - Learning states before the Forwarding state is entered. This delay is + The forwarding delay time is the time spent in each of the listening and + learning states before the Forwarding state is entered. This delay is so that when a new bridge comes onto a busy network it looks at some traffic before participating. @@ -183,7 +185,7 @@ Examples Create a basic bridge ===================== -Creating a bridge interface is very simple. In this example we will +Creating a bridge interface is very simple. In this example, we will have: * A bridge named `br100` diff --git a/docs/configuration/interfaces/dummy.rst b/docs/configuration/interfaces/dummy.rst index f5b72e0c..8440feca 100644 --- a/docs/configuration/interfaces/dummy.rst +++ b/docs/configuration/interfaces/dummy.rst @@ -1,3 +1,5 @@ +:lastproofread: 2021-06-30 + .. _dummy-interface: ##### @@ -50,7 +52,7 @@ Operation .. opcmd:: show interfaces dummy - Show brief interface information.information + Show brief interface information. .. code-block:: none diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst index 1d99019c..dcc9e529 100644 --- a/docs/configuration/interfaces/ethernet.rst +++ b/docs/configuration/interfaces/ethernet.rst @@ -1,3 +1,5 @@ +:lastproofread: 2021-06-30 + .. _ethernet-interface: ######## @@ -312,4 +314,3 @@ Operation XDP_PASS 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000414 XDP_TX 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000414 XDP_REDIRECT 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000414 - diff --git a/docs/configuration/interfaces/geneve.rst b/docs/configuration/interfaces/geneve.rst index 9e00d621..b13e2ece 100644 --- a/docs/configuration/interfaces/geneve.rst +++ b/docs/configuration/interfaces/geneve.rst @@ -1,3 +1,5 @@ +:lastproofread: 2021-06-30 + .. _geneve-interface: ###### diff --git a/docs/configuration/interfaces/index.rst b/docs/configuration/interfaces/index.rst index 3c75f482..23792203 100644 --- a/docs/configuration/interfaces/index.rst +++ b/docs/configuration/interfaces/index.rst @@ -16,12 +16,12 @@ Interfaces loopback macsec openvpn + wireguard pppoe pseudo-ethernet tunnel vti vxlan - wireguard wireless wwan diff --git a/docs/configuration/interfaces/l2tpv3.rst b/docs/configuration/interfaces/l2tpv3.rst index 8fe905a1..ca0ce2c9 100644 --- a/docs/configuration/interfaces/l2tpv3.rst +++ b/docs/configuration/interfaces/l2tpv3.rst @@ -1,3 +1,5 @@ +:lastproofread: 2021-06-30 + .. include:: /_include/need_improvement.txt .. _l2tpv3-interface: @@ -9,7 +11,7 @@ L2TPv3 Layer 2 Tunnelling Protocol Version 3 is an IETF standard related to L2TP that can be used as an alternative protocol to :ref:`mpls` for encapsulation of multiprotocol Layer 2 communications traffic over IP networks. Like L2TP, -L2TPv3 provides a pseudo-wire service, but scaled to fit carrier requirements. +L2TPv3 provides a pseudo-wire service but is scaled to fit carrier requirements. L2TPv3 can be regarded as being to MPLS what IP is to ATM: a simplified version of the same concept, with much of the same benefit achieved at a fraction of the @@ -49,13 +51,13 @@ L2TPv3 options Set the IP address of the local interface to be used for the tunnel. - This address must be the address of a local interface. May be specified as an - IPv4 address or an IPv6 address. + This address must be the address of a local interface. It may be specified as + an IPv4 address or an IPv6 address. .. cfgcmd:: set interfaces l2tpv3 <interface> remote <address> - Set the IP address of the remote peer. May be specified as an IPv4 address or - an IPv6 address. + Set the IP address of the remote peer. It may be specified as + an IPv4 address or an IPv6 address. .. cfgcmd:: set interfaces l2tpv3 <interface> session-id <id> @@ -65,7 +67,7 @@ L2TPv3 options .. cfgcmd:: set interfaces l2tpv3 <interface> peer-session-id <id> - Set the peer session id, which is a 32-bit integer value assigned to the + Set the peer-session-id, which is a 32-bit integer value assigned to the session by the peer. The value used must match the session_id value being used at the peer. @@ -100,7 +102,7 @@ Over IP tunnel-id 200 } -Inverse configuration has to be applied to the remote side. +The inverse configuration has to be applied to the remote side. Over UDP ======== diff --git a/docs/configuration/interfaces/loopback.rst b/docs/configuration/interfaces/loopback.rst index 4d0c8fb6..ec2976b6 100644 --- a/docs/configuration/interfaces/loopback.rst +++ b/docs/configuration/interfaces/loopback.rst @@ -1,3 +1,5 @@ +:lastproofread: 2021-06-30 + .. _loopback-interface: ######## @@ -53,7 +55,7 @@ Operation .. opcmd:: show interfaces loopback lo - Show detailed information on given loopback interface `lo`. + Show detailed information on the given loopback interface `lo`. .. code-block:: none diff --git a/docs/configuration/interfaces/macsec.rst b/docs/configuration/interfaces/macsec.rst index 9a20c425..544bd4fc 100644 --- a/docs/configuration/interfaces/macsec.rst +++ b/docs/configuration/interfaces/macsec.rst @@ -1,3 +1,5 @@ +:lastproofread: 2021-07-05 + .. _macsec-interface: ###### @@ -40,7 +42,7 @@ MACsec options .. cfgcmd:: set interfaces macsec <interface> source-interface <physical-source> A physical interface is required to connect this MACsec instance to. Traffic - leaving this interfac will now be authenticated/encrypted. + leaving this interface will now be authenticated/encrypted. Key Management -------------- @@ -50,7 +52,7 @@ individual peers. .. cfgcmd:: set interfaces macsec <interface> security mka cak <key> - IEEE 802.1X/MACsec pre-shared key mode. This allows to configure MACsec with + IEEE 802.1X/MACsec pre-shared key mode. This allows configuring MACsec with a pre-shared key using a (CAK,CKN) pair. .. cfgcmd:: set interfaces macsec <interface> security mka ckn <key> diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/openvpn.rst index a30a0b81..877b5d60 100644 --- a/docs/configuration/interfaces/openvpn.rst +++ b/docs/configuration/interfaces/openvpn.rst @@ -1,3 +1,5 @@ +:lastproofread: 2021-07-05 + .. _openvpn: ####### @@ -95,7 +97,7 @@ Remote Configuration: set interfaces openvpn vtun1 remote-address '10.255.1.1' The configurations above will default to using 256-bit AES in GCM mode -for encryption (if both sides supports NCP) and SHA-1 for HMAC authentication. +for encryption (if both sides support NCP) and SHA-1 for HMAC authentication. SHA-1 is considered weak, but other hashing algorithms are available, as are encryption algorithms: @@ -120,7 +122,7 @@ OpenVPN version < 2.4.0. aes256gcm AES algorithm with 256-bit key GCM This sets the accepted ciphers to use when version => 2.4.0 and NCP is -enabled (which is default). Default NCP cipher for versions >= 2.4.0 is +enabled (which is the default). Default NCP cipher for versions >= 2.4.0 is aes256gcm. The first cipher in this list is what server pushes to clients. .. code-block:: none @@ -168,7 +170,7 @@ Remote Configuration: set protocols static route 10.0.0.0/16 interface vtun1 Firewall policy can also be applied to the tunnel interface for `local`, `in`, -and `out` directions and function identically to ethernet interfaces. +and `out` directions and functions identically to ethernet interfaces. If making use of multiple tunnels, OpenVPN must have a way to distinguish between different tunnels aside from the pre-shared-key. This is either by @@ -358,7 +360,7 @@ updates set interfaces openvpn vtun0 openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" -The required config file may look like: +The required config file may look like this: .. code-block:: none @@ -472,12 +474,12 @@ example: Client ====== -VyOS can not only act as an OpenVPN site-to-site or Server for multiple clients. +VyOS can not only act as an OpenVPN site-to-site or server for multiple clients. You can indeed also configure any VyOS OpenVPN interface as an OpenVPN client connecting to a VyOS OpenVPN server or any other OpenVPN server. Given the following example we have one VyOS router acting as OpenVPN server -and another VyOS router acting as OpenVPN client. The Server also pushes a +and another VyOS router acting as OpenVPN client. The server also pushes a static client IP address to the OpenVPN client. Remember, clients are identified using their CN attribute in the SSL certificate. @@ -529,7 +531,7 @@ Client Options ======= -We do not have CLI nodes for every single OpenVPN options. If an option is +We do not have CLI nodes for every single OpenVPN option. If an option is missing, a feature request should be opened at Phabricator_ so all users can benefit from it (see :ref:`issues_features`). @@ -547,7 +549,7 @@ if you pass invalid options/syntax. Will add ``push "keepalive 1 10"`` to the generated OpenVPN config file. -.. note:: Sometimes option lines in the generated OpenVPN configurarion require +.. note:: Sometimes option lines in the generated OpenVPN configuration require quotes. This is done through a hack on our config generator. You can pass quotes using the ``"`` statement. @@ -583,11 +585,11 @@ The following commands let you reset OpenVPN. .. opcmd:: reset openvpn client <text> - Use this command to reset specified OpenVPN client. + Use this command to reset the specified OpenVPN client. .. opcmd:: reset openvpn interface <interface> - Uset this command to reset the OpenVPN process on a specific interface. + Use this command to reset the OpenVPN process on a specific interface. diff --git a/docs/configuration/interfaces/pppoe.rst b/docs/configuration/interfaces/pppoe.rst index 64aca858..41f22ed6 100644 --- a/docs/configuration/interfaces/pppoe.rst +++ b/docs/configuration/interfaces/pppoe.rst @@ -1,3 +1,5 @@ +:lastproofread: 2021-07-09 + .. _pppoe-interface: ##### @@ -19,7 +21,7 @@ Operating Modes *************** VyOS supports setting up PPPoE in two different ways to a PPPoE internet -connection. This is due to most ISPs provide a modem that is also a wireless +connection. This is because most ISPs provide a modem that is also a wireless router. Home Users @@ -45,7 +47,7 @@ your DSL Modem/Router switch into a Bridged Mode so it only acts as a DSL Transceiver device to connect between the Ethernet link of your VyOS and the phone cable. Once your DSL Transceiver is in Bridge Mode, you should get no IP address from it. Please make sure you connect to the Ethernet Port 1 if -your DSL Transeiver has a switch, as some of them only work this way. +your DSL Transceiver has a switch, as some of them only work this way. Once you have an Ethernet device connected, i.e. `eth0`, then you can configure it to open the PPPoE session for you and your DSL Transceiver @@ -101,7 +103,7 @@ PPPoE options When set the interface is enabled for "dial-on-demand". - Use this command to instruct the system to establish a PPPoE connections + Use this command to instruct the system to establish a PPPoE connection automatically once traffic passes through the interface. A disabled on-demand connection is established at boot time and remains up. If the link fails for any reason, the link is brought back up immediately. @@ -225,12 +227,12 @@ Connect/Disconnect .. opcmd:: disconnect interface <interface> Test disconnecting given connection-oriented interface. `<interface>` can be - ``pppoe0`` as example. + ``pppoe0`` as the example. .. opcmd:: connect interface <interface> Test connecting given connection-oriented interface. `<interface>` can be - ``pppoe0`` as example. + ``pppoe0`` as the example. ******* Example @@ -253,7 +255,7 @@ Requirements: change the ``default-route`` option to ``force``. You could also install a static route and set the ``default-route`` option to ``none``. * With the ``name-server`` option set to ``none``, VyOS will ignore the - nameservers your ISP sens you and thus you can fully rely on the ones you + nameservers your ISP sends you and thus you can fully rely on the ones you have configured statically. .. note:: Syntax has changed from VyOS 1.2 (crux) and it will be automatically diff --git a/docs/configuration/interfaces/pseudo-ethernet.rst b/docs/configuration/interfaces/pseudo-ethernet.rst index 06b7bd86..b2849772 100644 --- a/docs/configuration/interfaces/pseudo-ethernet.rst +++ b/docs/configuration/interfaces/pseudo-ethernet.rst @@ -1,3 +1,5 @@ +:lastproofread: 2021-07-09 + .. _pseudo-ethernet-interface: ######################### @@ -36,7 +38,7 @@ Ethernet interfaces: applies to: - VMware machines using default settings - Network switches with security settings allowing only a single MAC address - - xDSL modems that try to lear the MAC address of the NIC + - xDSL modems that try to learn the MAC address of the NIC ************* Configuration diff --git a/docs/configuration/interfaces/tunnel.rst b/docs/configuration/interfaces/tunnel.rst index 7f7cd709..6a5fb171 100644 --- a/docs/configuration/interfaces/tunnel.rst +++ b/docs/configuration/interfaces/tunnel.rst @@ -1,3 +1,5 @@ +:lastproofread: 2021-07-09 + .. _tunnel-interface: Tunnel @@ -99,8 +101,8 @@ A full example of a Tunnelbroker.net config can be found at Generic Routing Encapsulation (GRE) ----------------------------------- -A GRE tunnel operates at layer 3 of the OSI model and is repsented by IP -protocol 47.The main benefit of a GRE tunnel is that you are able to carry +A GRE tunnel operates at layer 3 of the OSI model and is represented by IP +protocol 47. The main benefit of a GRE tunnel is that you are able to carry multiple protocols inside the same tunnel. GRE also supports multicast traffic and supports routing protocols that leverage multicast to form neighbor adjacencies. @@ -112,12 +114,12 @@ over either IPv4 (gre) or IPv6 (ip6gre). Configuration ^^^^^^^^^^^^^ -A basic configuration requires a tunnel source (source-address), a tunnel destination -(remote), an encapsulation type (gre), and an address (ipv4/ipv6).Below is a -basic IPv4 only configuration example taken from a VyOS router and a Cisco IOS -router. The main difference between these two configurations is that VyOS -requires you explicitly configure the encapsulation type. The Cisco router -defaults to gre ip otherwise it would have to be configured as well. +A basic configuration requires a tunnel source (source-address), a tunnel +destination (remote), an encapsulation type (gre), and an address (ipv4/ipv6). +Below is a basic IPv4 only configuration example taken from a VyOS router and +a Cisco IOS router. The main difference between these two configurations is +that VyOS requires you explicitly configure the encapsulation type. The Cisco +router defaults to GRE IP otherwise it would have to be configured as well. **VyOS Router:** @@ -224,7 +226,7 @@ GRE is a well defined standard that is common in most networks. While not inherently difficult to configure there are a couple of things to keep in mind to make sure the configuration performs as expected. A common cause for GRE tunnels to fail to come up correctly include ACL or Firewall configurations -that are discarding IP protocol 47 or blocking your source/desintation traffic. +that are discarding IP protocol 47 or blocking your source/destination traffic. **1. Confirm IP connectivity between tunnel source-address and remote:** diff --git a/docs/configuration/interfaces/vxlan.rst b/docs/configuration/interfaces/vxlan.rst index ca25d21e..9b2f42a1 100644 --- a/docs/configuration/interfaces/vxlan.rst +++ b/docs/configuration/interfaces/vxlan.rst @@ -1,3 +1,5 @@ +:lastproofread: 2021-07-09 + .. _vxlan-interface: ##### @@ -12,8 +14,8 @@ encapsulate OSI layer 2 Ethernet frames within layer 4 UDP datagrams, using endpoints, which terminate VXLAN tunnels and may be either virtual or physical switch ports, are known as :abbr:`VTEPs (VXLAN tunnel endpoints)`. -VXLAN is an evolution of efforts to standardize on an overlay encapsulation -protocol. It increases scalability up to 16 million logical networks and +VXLAN is an evolution of efforts to standardize an overlay encapsulation +protocol. It increases the scalability up to 16 million logical networks and allows for layer 2 adjacency across IP networks. Multicast or unicast with head-end replication (HER) is used to flood broadcast, unknown unicast, and multicast (BUM) traffic. @@ -100,10 +102,10 @@ the same broadcast domain. Let's assume PC4 on Leaf2 wants to ping PC5 on Leaf3. Instead of setting Leaf3 as our remote end manually, Leaf2 encapsulates the packet into a UDP-packet and sends it to its designated multicast-address via Spine1. When Spine1 receives -this packet it forwards it to all other Leafs who has joined the same +this packet it forwards it to all other leaves who has joined the same multicast-group, in this case Leaf3. When Leaf3 receives the packet it forwards it, while at the same time learning that PC4 is reachable behind Leaf2, because -the encapsulated packet had Leaf2's IP-address set as source IP. +the encapsulated packet had Leaf2's IP address set as source IP. PC5 receives the ping echo, responds with an echo reply that Leaf3 receives and this time forwards to Leaf2's unicast address directly because it learned the @@ -111,13 +113,13 @@ location of PC4 above. When Leaf2 receives the echo reply from PC5 it sees that it came from Leaf3 and so remembers that PC5 is reachable via Leaf3. Thanks to this discovery, any subsequent traffic between PC4 and PC5 will not -be using the multicast-address between the Leafs as they both know behind which +be using the multicast-address between the leaves as they both know behind which Leaf the PCs are connected. This saves traffic as less multicast packets sent -reduces the load on the network, which improves scalability when more Leafs are +reduces the load on the network, which improves scalability when more leaves are added. -For optimal scalability Multicast shouldn't be used at all, but instead use BGP -to signal all connected devices between leafs. Unfortunately, VyOS does not yet +For optimal scalability, Multicast shouldn't be used at all, but instead use BGP +to signal all connected devices between leaves. Unfortunately, VyOS does not yet support this. Example @@ -164,9 +166,9 @@ Topology: router ospf 1 network 10.0.0.0 0.255.255.255 area 0 -Multicast-routing is required for the leafs to forward traffic between each +Multicast-routing is required for the leaves to forward traffic between each other in a more scalable way. This also requires PIM to be enabled towards the -Leafs so that the Spine can learn what multicast groups each Leaf expect +leaves so that the Spine can learn what multicast groups each Leaf expects traffic from. **Leaf2 configuration:** @@ -228,7 +230,7 @@ descriptions are placed under the command boxes: set interfaces bridge br241 address '172.16.241.1/24' This commands creates a bridge that is used to bind traffic on eth1 vlan 241 -with the vxlan241-interface. The IP-address is not required. It may however be +with the vxlan241-interface. The IP address is not required. It may however be used as a default gateway for each Leaf which allows devices on the vlan to reach other subnets. This requires that the subnets are redistributed by OSPF so that the Spine will learn how to reach it. To do this you need to change the @@ -247,8 +249,8 @@ interfaces of the same bridge. set interfaces vxlan vxlan241 group '239.0.0.241' -The multicast-group used by all Leafs for this vlan extension. Has to be the -same on all Leafs that has this interface. +The multicast-group used by all leaves for this vlan extension. Has to be the +same on all leaves that has this interface. .. code-block:: none @@ -269,7 +271,7 @@ multicast-address. set interfaces vxlan vxlan241 port 12345 The destination port used for creating a VXLAN interface in Linux defaults to -its pre-standard value of 8472 to preserve backwards compatibility. A +its pre-standard value of 8472 to preserve backward compatibility. A configuration directive to support a user-specified destination port to override that behavior is available using the above command. diff --git a/docs/configuration/interfaces/wireguard.rst b/docs/configuration/interfaces/wireguard.rst index ddfbe620..bb2418b1 100644 --- a/docs/configuration/interfaces/wireguard.rst +++ b/docs/configuration/interfaces/wireguard.rst @@ -1,7 +1,5 @@ .. _wireguard: -.. include:: /_include/need_improvement.txt - ######### WireGuard ######### @@ -10,10 +8,24 @@ WireGuard is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography. See https://www.wireguard.com for more information. +**************** +Site to Site VPN +**************** + +This diagram corresponds with the example site to site configuration below. + +.. figure:: /_static/images/wireguard_site2site_diagram.jpg + ************* Configuration ************* + + +******** +Keypairs +******** + WireGuard requires the generation of a keypair, which includes a private key to decrypt incoming traffic, and a public key for peer(s) to encrypt traffic. @@ -55,8 +67,9 @@ own keypairs. vyos@vyos:~$ generate wireguard named-keypairs KP02 +*********************** Interface configuration -======================= +*********************** The next step is to configure your local side as well as the policy based trusted destination addresses. If you only initiate a connection, @@ -71,18 +84,31 @@ you want to tunnel (allowed-ips) to configure a WireGuard tunnel. The public key below is always the public key from your peer, not your local one. -**local side** +**local side - commands** .. code-block:: none - set interfaces wireguard wg01 address '10.1.0.1/24' + set interfaces wireguard wg01 address '10.1.0.1/30' set interfaces wireguard wg01 description 'VPN-to-wg02' - set interfaces wireguard wg01 peer to-wg02 allowed-ips '10.2.0.0/24' - set interfaces wireguard wg01 peer to-wg02 address '192.168.0.142' - set interfaces wireguard wg01 peer to-wg02 port '12345' + set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.2.0/24' + set interfaces wireguard wg01 peer to-wg02 address '<Site1 Pub IP>' + set interfaces wireguard wg01 peer to-wg02 port '51820' set interfaces wireguard wg01 peer to-wg02 pubkey 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=' - set interfaces wireguard wg01 port '12345' - set protocols static route 10.2.0.0/24 interface wg01 + set interfaces wireguard wg01 port '51820' + set protocols static route 192.168.2.0/24 interface wg01 + +**local side - annotated commands** + +.. code-block:: none + + set interfaces wireguard wg01 address '10.1.0.1/30' # Address of the wg01 tunnel interface. + set interfaces wireguard wg01 description 'VPN-to-wg02' + set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.2.0/24' # Subnets that are allowed to travel over the tunnel + set interfaces wireguard wg01 peer to-wg02 address '<Site2 Pub IP>' # Public IP of the peer + set interfaces wireguard wg01 peer to-wg02 port '58120' # Port of the Peer + set interfaces wireguard wg01 peer to-wg02 pubkey '<pubkey>' # Public Key of the Peer + set interfaces wireguard wg01 port '51820' # Port of own server + set protocols static route 192.168.2.0/24 interface wg01 # Static route to remote subnet The last step is to define an interface route for 10.2.0.0/24 to get through the WireGuard interface `wg01`. Multiple IPs or networks can be @@ -90,7 +116,7 @@ defined and routed. The last check is allowed-ips which either prevents or allows the traffic. .. note:: You can not assign the same allowed-ips statement to multiple - WireGuard peers. This a a design decission. For more information please + WireGuard peers. This a a design decision. For more information please check the `WireGuard mailing list`_. .. cfgcmd:: set interfaces wireguard <interface> private-key <name> @@ -106,33 +132,70 @@ or allows the traffic. public key, which needs to be shared with the peer. -**remote side** +**remote side - commands** .. code-block:: none - set interfaces wireguard wg01 address '10.2.0.1/24' + set interfaces wireguard wg01 address '10.1.0.2/30' set interfaces wireguard wg01 description 'VPN-to-wg01' - set interfaces wireguard wg01 peer to-wg02 allowed-ips '10.1.0.0/24' - set interfaces wireguard wg01 peer to-wg02 address '192.168.0.124' - set interfaces wireguard wg01 peer to-wg02 port '12345' + set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.1.0/24' + set interfaces wireguard wg01 peer to-wg02 address '<Site1 Pub IP>' + set interfaces wireguard wg01 peer to-wg02 port '51820' set interfaces wireguard wg01 peer to-wg02 pubkey 'u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk=' - set interfaces wireguard wg01 port '12345' - set protocols static route 10.1.0.0/24 interface wg01 + set interfaces wireguard wg01 port '51820' + set protocols static route 192.168.1.0/24 interface wg01 + +**remote side - annotated commands** + +.. code-block:: none + + set interfaces wireguard wg01 address '10.1.0.2/30' # Address of the wg01 tunnel interface. + set interfaces wireguard wg01 description 'VPN-to-wg01' + set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.1.0/24' # Subnets that are allowed to travel over the tunnel + set interfaces wireguard wg01 peer to-wg02 address 'Site1 Pub IP' # Public IP address of the Peer + set interfaces wireguard wg01 peer to-wg02 port '51820' # Port of the Peer + set interfaces wireguard wg01 peer to-wg02 pubkey '<pubkey>' # Public key of the Peer + set interfaces wireguard wg01 port '51820' # Port of own server + set protocols static route 192.168.1.0/24 interface wg01 # Static route to remote subnet + +******************* +Firewall Exceptions +******************* -Assure that your firewall rules allow the traffic, in which case you -have a working VPN using WireGuard. +For the WireGuard traffic to pass through the WAN interface, you must create a firewall exception. .. code-block:: none - wg01# ping 10.2.0.1 - PING 10.2.0.1 (10.2.0.1) 56(84) bytes of data. - 64 bytes from 10.2.0.1: icmp_seq=1 ttl=64 time=1.16 ms - 64 bytes from 10.2.0.1: icmp_seq=2 ttl=64 time=1.77 ms + set firewall name OUTSIDE_LOCAL rule 10 action accept + set firewall name OUTSIDE_LOCAL rule 10 description 'Allow established/related' + set firewall name OUTSIDE_LOCAL rule 10 state established enable + set firewall name OUTSIDE_LOCAL rule 10 state related enable + set firewall name OUTSIDE_LOCAL rule 20 action accept + set firewall name OUTSIDE_LOCAL rule 20 description WireGuard_IN + set firewall name OUTSIDE_LOCAL rule 20 destination port 51820 + set firewall name OUTSIDE_LOCAL rule 20 log enable + set firewall name OUTSIDE_LOCAL rule 20 protocol udp + set firewall name OUTSIDE_LOCAL rule 20 source - wg02# ping 10.1.0.1 - PING 10.1.0.1 (10.1.0.1) 56(84) bytes of data. - 64 bytes from 10.1.0.1: icmp_seq=1 ttl=64 time=4.40 ms - 64 bytes from 10.1.0.1: icmp_seq=2 ttl=64 time=1.02 ms +You should also ensure that the OUTISDE_LOCAL firewall group is applied to the WAN interface and a direction (local). + +.. code-block:: none + + set interfaces ethernet eth0 firewall local name 'OUTSIDE-LOCAL' + +Assure that your firewall rules allow the traffic, in which case you have a working VPN using WireGuard. + +.. code-block:: none + + wg01# ping 192.168.1.1 + PING 192.168.1.1 (192.168.1.1) 56(84) bytes of data. + 64 bytes from 192.168.1.1: icmp_seq=1 ttl=64 time=1.16 ms + 64 bytes from 192.168.1.1: icmp_seq=2 ttl=64 time=1.77 ms + + wg02# ping 192.168.2.1 + PING 192.168.2.1 (192.168.2.1) 56(84) bytes of data. + 64 bytes from 192.168.2.1: icmp_seq=1 ttl=64 time=4.40 ms + 64 bytes from 192.168.2.1: icmp_seq=2 ttl=64 time=1.02 ms An additional layer of symmetric-key crypto can be used on top of the asymmetric crypto. This is optional. @@ -151,8 +214,10 @@ its content. Make sure you distribute the key in a safe manner, wg01# set interfaces wireguard wg01 peer to-wg02 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' wg02# set interfaces wireguard wg01 peer to-wg01 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' -Road Warrior Example --------------------- + +*********************************** +Remote Access "RoadWarrior" Example +*********************************** With WireGuard, a Road Warrior VPN config is similar to a site-to-site VPN. It just lacks the ``address`` and ``port`` statements. @@ -182,7 +247,7 @@ the peers. This allows the peers to interact with one another. } The following is the config for the iPhone peer above. It's important to -note that the ``AllowedIPs`` setting directs all IPv4 and IPv6 traffic +note that the ``AllowedIPs`` wildcard setting directs all IPv4 and IPv6 traffic through the connection. .. code-block:: none @@ -198,9 +263,9 @@ through the connection. Endpoint = 192.0.2.1:2224 PersistentKeepalive = 25 - -This MacBook peer is doing split-tunneling, where only the subnets local -to the server go over the connection. +However, split-tunneling can be achieved by specifing the remote subnets. +This ensures that only traffic destined for the remote site is sent over the tunnel. +All other traffic is unaffected. .. code-block:: none @@ -222,6 +287,25 @@ Operational Commands Status ====== +.. opcmd:: show interfaces wireguard wg0 summary + + Show info about the Wireguard service. + Also shows the latest handshake. + + .. code-block:: none + + vyos@vyos:~$ show interfaces wireguard wg0 summary + interface: wg0 + public key: + private key: (hidden) + listening port: 51820 + + peer: <peer pubkey> + endpoint: <peer public IP> + allowed ips: 10.69.69.2/32 + latest handshake: 23 hours, 45 minutes, 26 seconds ago + transfer: 1.26 MiB received, 6.47 MiB sent + .. opcmd:: show interfaces wireguard Get a list of all wireguard interfaces @@ -252,8 +336,9 @@ Status TX: bytes packets errors dropped carrier collisions 0 0 0 0 0 0 +*************** Encryption Keys -=============== +*************** .. opcmd:: show wireguard keypair pubkey <name> @@ -284,15 +369,16 @@ Encryption Keys vyos@vyos:~$ delete wireguard keypair default -Mobile "RoadWarrior" clients -============================ +*********************************** +Remote Access "RoadWarrior" clients +*********************************** Some users tend to connect their mobile devices using WireGuard to their VyOS router. To ease deployment one can generate a "per mobile" configuration from the VyOS CLI. .. warning:: From a security perspective it is not recommended to let a third - party create the private key for a secured connection. You should create the + party create and share the private key for a secured connection. You should create the private portion on your own and only hand out the public key. Please keep this in mind when using this convenience feature. diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst index a6f64aa4..943e8241 100644 --- a/docs/configuration/service/dhcp-server.rst +++ b/docs/configuration/service/dhcp-server.rst @@ -574,6 +574,7 @@ be created. The following example explains the process. **Example:** * IPv6 address ``2001:db8::101`` shall be statically mapped +* IPv6 prefix ``2001:db8:0:101::/64`` shall be statically mapped * Host specific mapping shall be named ``client1`` .. hint:: The identifier is the device's DUID: colon-separated hex list (as @@ -585,6 +586,7 @@ be created. The following example explains the process. .. code-block:: none set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 ipv6-address 2001:db8::101 + set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 ipv6-prefix 2001:db8:0:101::/64 set service dhcpv6-server shared-network-name 'NET1' subnet 2001:db8::/64 static-mapping client1 identifier 00:01:00:01:12:34:56:78:aa:bb:cc:dd:ee:ff The configuration will look as follows: diff --git a/docs/configuration/service/ssh.rst b/docs/configuration/service/ssh.rst index 6b09d40d..40ec62f5 100644 --- a/docs/configuration/service/ssh.rst +++ b/docs/configuration/service/ssh.rst @@ -156,3 +156,33 @@ Operation Two new files ``/config/auth/id_rsa_rpki`` and ``/config/auth/id_rsa_rpki.pub`` 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 diff --git a/docs/configuration/system/login.rst b/docs/configuration/system/login.rst index 0492f4d1..09b6e68b 100644 --- a/docs/configuration/system/login.rst +++ b/docs/configuration/system/login.rst @@ -76,6 +76,10 @@ The third part is simply an identifier, and is for your own reference. .. 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 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 diff --git a/docs/configuration/vpn/index.rst b/docs/configuration/vpn/index.rst index abaca198..3cd9e50d 100644 --- a/docs/configuration/vpn/index.rst +++ b/docs/configuration/vpn/index.rst @@ -15,7 +15,6 @@ VPN sstp - pages to sort .. toctree:: @@ -23,4 +22,4 @@ pages to sort :includehidden: dmvpn - site2site_ipsec
\ No newline at end of file + site2site_ipsec diff --git a/docs/configuration/vrf/index.rst b/docs/configuration/vrf/index.rst index a65f0073..23bc5422 100644 --- a/docs/configuration/vrf/index.rst +++ b/docs/configuration/vrf/index.rst @@ -183,9 +183,133 @@ For VRF maintenance the following operational commands are in place. .. opcmd:: traceroute vrf <name> [ipv4 | ipv6] <host> Displays the route packets taken to a network host utilizing VRF instance - identified by `<name>`. When using the IPv4 or IPv6 option, displays the + identified by `<name>`. When using the IPv4 or IPv6 option, displays the route packets taken to the given hosts IP address family. This option is useful when the host is specified as a hostname rather than an IP address. +Example +======= + +VRF route leaking +----------------- + +The following example topology was build using EVE-NG. + +.. figure:: /_static/images/vrf-example-topology-01.png + :alt: VRF topology example + + VRF route leaking + +* PC1 is in the ``default`` VRF and acting as e.g. a "fileserver" +* PC2 is in VRF ``blue`` which is the development department +* PC3 and PC4 are connected to a bridge device on router ``R1`` which is in VRF + ``red``. Say this is the HR department. +* R1 is managed through an out-of-band network that resides in VRF ``mgmt`` + +Configuration +^^^^^^^^^^^^^ + + .. code-block:: none + + set interfaces bridge br10 address '10.30.0.254/24' + set interfaces bridge br10 member interface eth3 + set interfaces bridge br10 member interface eth4 + set interfaces bridge br10 vrf 'red' + + set interfaces ethernet eth0 address 'dhcp' + set interfaces ethernet eth0 vrf 'mgmt' + set interfaces ethernet eth1 address '10.0.0.254/24' + set interfaces ethernet eth2 address '10.20.0.254/24' + set interfaces ethernet eth2 vrf 'blue' + + set protocols static route 10.20.0.0/24 interface eth2 vrf 'blue' + set protocols static route 10.30.0.0/24 interface br10 vrf 'red' + + set service ssh disable-host-validation + set service ssh vrf 'mgmt' + + set system name-servers-dhcp 'eth0' + + set vrf name blue protocols static route 10.0.0.0/24 interface eth1 vrf 'default' + set vrf name blue table '3000' + set vrf name mgmt table '1000' + set vrf name red protocols static route 10.0.0.0/24 interface eth1 vrf 'default' + set vrf name red table '2000' + +Operation +^^^^^^^^^ + +After committing the configuration we can verify all leaked routes are installed, +and try to ICMP ping PC1 from PC3. + + .. code-block:: none + + PCS> ping 10.0.0.1 + + 84 bytes from 10.0.0.1 icmp_seq=1 ttl=63 time=1.943 ms + 84 bytes from 10.0.0.1 icmp_seq=2 ttl=63 time=1.618 ms + 84 bytes from 10.0.0.1 icmp_seq=3 ttl=63 time=1.745 ms + + .. code-block:: none + + VPCS> show ip + + NAME : VPCS[1] + IP/MASK : 10.30.0.1/24 + GATEWAY : 10.30.0.254 + DNS : + MAC : 00:50:79:66:68:0f + +VRF default routing table +""""""""""""""""""""""""" + + .. code-block:: none + + vyos@R1:~$ show ip route + Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + + C>* 10.0.0.0/24 is directly connected, eth1, 00:07:44 + S>* 10.20.0.0/24 [1/0] is directly connected, eth2 (vrf blue), weight 1, 00:07:38 + S>* 10.30.0.0/24 [1/0] is directly connected, br10 (vrf red), weight 1, 00:07:38 + +VRF red routing table +""""""""""""""""""""" + + .. code-block:: none + + vyos@R1:~$ show ip route vrf red + Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + + VRF red: + K>* 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 00:07:57 + S>* 10.0.0.0/24 [1/0] is directly connected, eth1 (vrf default), weight 1, 00:07:40 + C>* 10.30.0.0/24 is directly connected, br10, 00:07:54 + +VRF blue routing table +"""""""""""""""""""""" + + .. code-block:: none + + vyos@R1:~$ show ip route vrf blue + Codes: K - kernel route, C - connected, S - static, R - RIP, + O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP, + T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP, + F - PBR, f - OpenFabric, + > - selected route, * - FIB route, q - queued, r - rejected, b - backup + + VRF blue: + K>* 0.0.0.0/0 [255/8192] unreachable (ICMP unreachable), 00:08:00 + S>* 10.0.0.0/24 [1/0] is directly connected, eth1 (vrf default), weight 1, 00:07:44 + C>* 10.20.0.0/24 is directly connected, eth2, 00:07:53 + + .. include:: /_include/common-references.txt |