diff options
Diffstat (limited to 'docs/configuration/interfaces')
| -rw-r--r-- | docs/configuration/interfaces/bonding.rst | 575 | ||||
| -rw-r--r-- | docs/configuration/interfaces/bridge.rst | 316 | ||||
| -rw-r--r-- | docs/configuration/interfaces/dummy.rst | 79 | ||||
| -rw-r--r-- | docs/configuration/interfaces/ethernet.rst | 315 | ||||
| -rw-r--r-- | docs/configuration/interfaces/geneve.rst | 61 | ||||
| -rw-r--r-- | docs/configuration/interfaces/index.rst | 28 | ||||
| -rw-r--r-- | docs/configuration/interfaces/l2tpv3.rst | 192 | ||||
| -rw-r--r-- | docs/configuration/interfaces/loopback.rst | 71 | ||||
| -rw-r--r-- | docs/configuration/interfaces/macsec.rst | 191 | ||||
| -rw-r--r-- | docs/configuration/interfaces/openvpn.rst | 590 | ||||
| -rw-r--r-- | docs/configuration/interfaces/pppoe.rst | 317 | ||||
| -rw-r--r-- | docs/configuration/interfaces/pseudo-ethernet.rst | 65 | ||||
| -rw-r--r-- | docs/configuration/interfaces/tunnel.rst | 265 | ||||
| -rw-r--r-- | docs/configuration/interfaces/vti.rst | 22 | ||||
| -rw-r--r-- | docs/configuration/interfaces/vxlan.rst | 295 | ||||
| -rw-r--r-- | docs/configuration/interfaces/wireguard.rst | 269 | ||||
| -rw-r--r-- | docs/configuration/interfaces/wireless.rst | 590 | ||||
| -rw-r--r-- | docs/configuration/interfaces/wirelessmodem.rst | 128 |
18 files changed, 4369 insertions, 0 deletions
diff --git a/docs/configuration/interfaces/bonding.rst b/docs/configuration/interfaces/bonding.rst new file mode 100644 index 00000000..bf7cfc2c --- /dev/null +++ b/docs/configuration/interfaces/bonding.rst @@ -0,0 +1,575 @@ +.. _bond-interface: + +####################### +Bond / Link Aggregation +####################### + +The bonding interface provides a method for aggregating multiple network +interfaces into a single logical "bonded" interface, or LAG, or ether-channel, +or port-channel. The behavior of the bonded interfaces depends upon the mode; +generally speaking, modes provide either hot standby or load balancing services. +Additionally, link integrity monitoring may be performed. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: bond + :var1: bond0 + +Member Interfaces +================= + +.. cfgcmd:: set interfaces bonding <interface> member interface <member> + + Enslave `<member>` interface to bond `<interface>`. + +Bond options +============ + +.. cfgcmd:: set interfaces bonding <interface> mode <802.3ad | active-backup | + broadcast | round-robin | transmit-load-balance | adaptive-load-balance | + xor-hash> + + Specifies one of the bonding policies. The default is 802.3ad. Possible + values are: + + * ``802.3ad`` - IEEE 802.3ad Dynamic link aggregation. Creates aggregation + groups that share the same speed and duplex settings. Utilizes all slaves + in the active aggregator according to the 802.3ad specification. + + Slave selection for outgoing traffic is done according to the transmit + hash policy, which may be changed from the default simple XOR policy via + 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 + of the 802.3ad standard. + + * ``active-backup`` - Active-backup policy: Only one slave in the bond is + active. A different slave becomes active if, and only if, the active slave + fails. The bond's MAC address is externally visible on only one port + (network adapter) to avoid confusing the switch. + + When a failover occurs in active-backup mode, bonding will issue one or + more gratuitous ARPs on the newly active slave. One gratuitous ARP is + issued for the bonding master interface and each VLAN interfaces + configured above it, provided that the interface has at least one IP + address configured. Gratuitous ARPs issued for VLAN interfaces are tagged + with the appropriate VLAN id. + + This mode provides fault tolerance. The :cfgcmd:`primary` option, + documented below, affects the behavior of this mode. + + * ``broadcast`` - Broadcast policy: transmits everything on all slave + interfaces. + + This mode provides fault tolerance. + + * ``round-robin`` - Round-robin policy: Transmit packets in sequential + order from the first available slave through the last. + + This mode provides load balancing and fault tolerance. + + * ``transmit-load-balance`` - Adaptive transmit load balancing: channel + bonding that does not require any special switch support. + + Incoming traffic is received by the current slave. If the receiving slave + fails, another slave takes over the MAC address of the failed receiving + slave. + + * ``adaptive-load-balance`` - Adaptive load balancing: includes + transmit-load-balance plus receive load balancing for IPV4 traffic, and + does not require any special switch support. The receive load balancing + is achieved by ARP negotiation. The bonding driver intercepts the ARP + Replies sent by the local system on their way out and overwrites the + source hardware address with the unique hardware address of one of the + slaves in the bond such that different peers use different hardware + addresses for the server. + + Receive traffic from connections created by the server is also balanced. + When the local system sends an ARP Request the bonding driver copies and + saves the peer's IP information from the ARP packet. When the ARP Reply + arrives from the peer, its hardware address is retrieved and the bonding + driver initiates an ARP reply to this peer assigning it to one of the + slaves in the bond. A problematic outcome of using ARP negotiation for + balancing is that each time that an ARP request is broadcast it uses the + hardware address of the bond. Hence, peers learn the hardware address + of the bond and the balancing of receive traffic collapses to the current + slave. This is handled by sending updates (ARP Replies) to all the peers + with their individually assigned hardware address such that the traffic + is redistributed. Receive traffic is also redistributed when a new slave + is added to the bond and when an inactive slave is re-activated. The + receive load is distributed sequentially (round robin) among the group + of highest speed slaves in the bond. + + When a link is reconnected or a new slave joins the bond the receive + traffic is redistributed among all active slaves in the bond by initiating + ARP Replies with the selected MAC address to each of the clients. The + updelay parameter (detailed below) must be set to a value equal or greater + than the switch's forwarding delay so that the ARP Replies sent to the + peers will not be blocked by the switch. + + * ``xor-hash`` - XOR policy: Transmit based on the selected transmit + hash policy. The default policy is a simple [(source MAC address XOR'd + with destination MAC address XOR packet type ID) modulo slave count]. + Alternate transmit policies may be selected via the :cfgcmd:`hash-policy` + option, described below. + + This mode provides load balancing and fault tolerance. + +.. cfgcmd:: set interfaces bonding <interface> min-links <0-16> + + Specifies the minimum number of links that must be active before asserting + carrier. It is similar to the Cisco EtherChannel min-links feature. This + allows setting the minimum number of member ports that must be up (link-up + state) before marking the bond device as up (carrier on). This is useful for + situations where higher level services such as clustering want to ensure a + minimum number of low bandwidth links are active before switchover. + + This option only affects 802.3ad mode. + + The default value is 0. This will cause carrier to be asserted (for 802.3ad + mode) whenever there is an active aggregator, regardless of the number of + available links in that aggregator. + + .. note:: Because an aggregator cannot be active without at least one + available link, setting this option to 0 or to 1 has the exact same + effect. + +.. cfgcmd:: set interfaces bonding <interface> hash-policy <policy> + + * **layer2** - Uses XOR of hardware MAC addresses and packet type ID field + to generate the hash. The formula is + + .. code-block:: none + + hash = source MAC XOR destination MAC XOR packet type ID + slave number = hash modulo slave count + + This algorithm will place all traffic to a particular network peer on + the same slave. + + This algorithm is 802.3ad compliant. + + * **layer2+3** - This policy uses a combination of layer2 and layer3 + protocol information to generate the hash. Uses XOR of hardware MAC + addresses and IP addresses to generate the hash. The formula is: + + .. code-block:: none + + hash = source MAC XOR destination MAC XOR packet type ID + hash = hash XOR source IP XOR destination IP + hash = hash XOR (hash RSHIFT 16) + hash = hash XOR (hash RSHIFT 8) + + And then hash is reduced modulo slave count. + + If the protocol is IPv6 then the source and destination addresses are + first hashed using ipv6_addr_hash. + + This algorithm will place all traffic to a particular network peer on the + same slave. For non-IP traffic, the formula is the same as for the layer2 + transmit hash policy. + + This policy is intended to provide a more balanced distribution of traffic + than layer2 alone, especially in environments where a layer3 gateway + device is required to reach most destinations. + + This algorithm is 802.3ad compliant. + + * **layer3+4** - This policy uses upper layer protocol information, when + available, to generate the hash. This allows for traffic to a particular + network peer to span multiple slaves, although a single connection will + not span multiple slaves. + + The formula for unfragmented TCP and UDP packets is + + .. code-block:: none + + hash = source port, destination port (as in the header) + hash = hash XOR source IP XOR destination IP + hash = hash XOR (hash RSHIFT 16) + hash = hash XOR (hash RSHIFT 8) + + And then hash is reduced modulo slave count. + + If the protocol is IPv6 then the source and destination addresses are + first hashed using ipv6_addr_hash. + + For fragmented TCP or UDP packets and all other IPv4 and IPv6 protocol + traffic, the source and destination port information is omitted. For + non-IP traffic, the formula is the same as for the layer2 transmit hash + policy. + + 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 + fragments traffic, and most UDP traffic is not involved in extended + conversations. Other implementations of 802.3ad may or may not tolerate + this noncompliance. + +.. cfgcmd:: set interfaces bonding <interface> primary <interface> + + An `<interface>` specifying which slave is the primary device. The specified + device will always be the active slave while it is available. Only when the + primary is off-line will alternate devices be used. This is useful when one + slave is preferred over another, e.g., when one slave has higher throughput + than another. + + The primary option is only valid for active-backup, transmit-load-balance, + and adaptive-load-balance mode. + +.. cfgcmd:: set interfaces bonding <interface> arp-monitor interval <time> + + Specifies the ARP link monitoring `<time>` in seconds. + + The ARP monitor works by periodically checking the slave devices to determine + whether they have sent or received traffic recently (the precise criteria + depends upon the bonding mode, and the state of the slave). Regular traffic + is generated via ARP probes issued for the addresses specified by the + :cfgcmd:`arp-monitor target` option. + + If ARP monitoring is used in an etherchannel compatible mode (modes + round-robin and xor-hash), the switch should be configured in a mode that + evenly distributes packets across all links. If the switch is configured to + distribute the packets in an XOR fashion, all replies from the ARP targets + will be received on the same link which could cause the other team members + to fail. + + A value of 0 disables ARP monitoring. The default value is 0. + +.. cfgcmd:: set interfaces bonding <interface> arp-monitor target <address> + + Specifies the IP addresses to use as ARP monitoring peers when + :cfgcmd:`arp-monitor interval` option is > 0. These are the targets of the + ARP request sent to determine the health of the link to the targets. + + Multiple target IP addresses can be specified. At least one IP address must + 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. + +Offloading +---------- + +.. cmdinclude:: /_include/interface-xdp.txt + :var0: bonding + :var1: bond0 + +VLAN +==== + +.. cmdinclude:: /_include/interface-vlan-8021q.txt + :var0: bond + :var1: bond0 + +Port Mirror (SPAN) +================== + +.. cmdinclude:: ../../_include/interface-mirror.txt + :var0: bonding + :var1: bond1 + :var2: eth3 + +******* +Example +******* + +The following configuration on VyOS applies to all following 3rd party vendors. +It creates a bond with two links and VLAN 10, 100 on the bonded interfaces with +a per VIF IPv4 address. + +.. code-block:: none + + # Create bonding interface bond0 with 802.3ad LACP + set interfaces bonding bond0 hash-policy 'layer2' + set interfaces bonding bond0 mode '802.3ad' + + # Add the required vlans and IPv4 addresses on them + set interfaces bonding bond0 vif 10 address 192.168.0.1/24 + set interfaces bonding bond0 vif 100 address 10.10.10.1/24 + + # Add the member interfaces to the bonding interface + set interfaces bonding bond0 member interface eth1 + set interfaces bonding bond0 member interface eth2 + +Cisco Catalyst +============== + +Assign member interfaces to PortChannel + +.. code-block:: none + + interface GigabitEthernet1/0/23 + description VyOS eth1 + channel-group 1 mode active + ! + interface GigabitEthernet1/0/24 + description VyOS eth2 + channel-group 1 mode active + ! + +A new interface becomes present ``Port-channel1``, all configuration like +allowed VLAN interfaces, STP will happen here. + +.. code-block:: none + + interface Port-channel1 + description LACP Channel for VyOS + switchport trunk encapsulation dot1q + switchport trunk allowed vlan 10,100 + switchport mode trunk + spanning-tree portfast trunk + ! + + +Juniper EX Switch +================= + +For a headstart you can use the below example on how to build a bond with two +interfaces from VyOS to a Juniper EX Switch system. + +.. code-block:: none + + # Create aggregated ethernet device with 802.3ad LACP and port speeds of 10gbit/s + set interfaces ae0 aggregated-ether-options link-speed 10g + set interfaces ae0 aggregated-ether-options lacp active + + # Create layer 2 on the aggregated ethernet device with trunking for our vlans + set interfaces ae0 unit 0 family ethernet-switching port-mode trunk + + # Add the required vlans to the device + set interfaces ae0 unit 0 family ethernet-switching vlan members 10 + set interfaces ae0 unit 0 family ethernet-switching vlan members 100 + + # Add the two interfaces to the aggregated ethernet device, in this setup both + # ports are on the same switch (switch 0, module 1, port 0 and 1) + set interfaces xe-0/1/0 ether-options 802.3ad ae0 + set interfaces xe-0/1/1 ether-options 802.3ad ae0 + + # But this can also be done with multiple switches in a stack, a virtual + # chassis on Juniper (switch 0 and switch 1, module 1, port 0 on both switches) + set interfaces xe-0/1/0 ether-options 802.3ad ae0 + set interfaces xe-1/1/0 ether-options 802.3ad ae0 + +Aruba/HP +======== + +For a headstart you can use the below example on how to build a +bond,port-channel with two interfaces from VyOS to a Aruba/HP 2510G switch. + +.. code-block:: none + + # Create trunk with 2 member interfaces (interface 1 and 2) and LACP + trunk 1-2 Trk1 LACP + + # Add the required vlans to the trunk + vlan 10 tagged Trk1 + vlan 100 tagged Trk1 + +Arista EOS +========== + +When utilizing VyOS in an environment with Arista gear you can use this blue +print as an initial setup to get an LACP bond / port-channel operational between +those two devices. + +Lets assume the following topology: + +.. figure:: /_static/images/vyos_arista_bond_lacp.png + :alt: VyOS Arista EOS setup + +**R1** + + .. code-block:: none + + interfaces { + bonding bond10 { + hash-policy layer3+4 + member { + interface eth1 + interface eth2 + } + mode 802.3ad + vif 100 { + address 192.0.2.1/30 + address 2001:db8::1/64 + } + } + +**R2** + + .. code-block:: none + + interfaces { + bonding bond10 { + hash-policy layer3+4 + member { + interface eth1 + interface eth2 + } + mode 802.3ad + vif 100 { + address 192.0.2.2/30 + address 2001:db8::2/64 + } + } + +**SW1** + + .. code-block:: none + + ! + vlan 100 + name FOO + ! + interface Port-Channel10 + switchport trunk allowed vlan 100 + switchport mode trunk + spanning-tree portfast + ! + interface Port-Channel20 + switchport mode trunk + no spanning-tree portfast auto + spanning-tree portfast network + ! + interface Ethernet1 + channel-group 10 mode active + ! + interface Ethernet2 + channel-group 10 mode active + ! + interface Ethernet3 + channel-group 20 mode active + ! + interface Ethernet4 + channel-group 20 mode active + ! + +**SW2** + + .. code-block:: none + + ! + vlan 100 + name FOO + ! + interface Port-Channel10 + switchport trunk allowed vlan 100 + switchport mode trunk + spanning-tree portfast + ! + interface Port-Channel20 + switchport mode trunk + no spanning-tree portfast auto + spanning-tree portfast network + ! + interface Ethernet1 + channel-group 10 mode active + ! + interface Ethernet2 + channel-group 10 mode active + ! + interface Ethernet3 + channel-group 20 mode active + ! + interface Ethernet4 + channel-group 20 mode active + ! + +.. note:: When using EVE-NG to lab this environment ensure you are using e1000 + as the desired driver for your VyOS network interfaces. When using the regular + virtio network driver no LACP PDUs will be sent by VyOS thus the port-channel + will never become active! + +********* +Operation +********* + +.. opcmd:: show interfaces bonding + + Show brief interface information. + + .. code-block:: none + + vyos@vyos:~$ show interfaces bonding + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + bond0 - u/u my-sw1 int 23 and 24 + bond0.10 192.168.0.1/24 u/u office-net + bond0.100 10.10.10.1/24 u/u management-net + + +.. opcmd:: show interfaces bonding <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces bonding bond5 + bond5: <NO-CARRIER,BROADCAST,MULTICAST,MASTER,UP> mtu 1500 qdisc noqueue state DOWN group default qlen 1000 + link/ether 00:50:56:bf:ef:aa brd ff:ff:ff:ff:ff:ff + inet6 fe80::e862:26ff:fe72:2dac/64 scope link tentative + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 0 0 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 0 0 0 0 0 0 + +.. opcmd:: show interfaces bonding <interface> detail + + Show detailed information about the underlaying physical links on given + bond `<interface>`. + + .. code-block:: none + + vyos@vyos:~$ show interfaces bonding bond5 detail + Ethernet Channel Bonding Driver: v3.7.1 (April 27, 2011) + + Bonding Mode: IEEE 802.3ad Dynamic link aggregation + Transmit Hash Policy: layer2 (0) + MII Status: down + MII Polling Interval (ms): 100 + Up Delay (ms): 0 + Down Delay (ms): 0 + + 802.3ad info + LACP rate: slow + Min links: 0 + Aggregator selection policy (ad_select): stable + + Slave Interface: eth1 + MII Status: down + Speed: Unknown + Duplex: Unknown + Link Failure Count: 0 + Permanent HW addr: 00:50:56:bf:ef:aa + Slave queue ID: 0 + Aggregator ID: 1 + Actor Churn State: churned + Partner Churn State: churned + Actor Churned Count: 1 + Partner Churned Count: 1 + + Slave Interface: eth2 + MII Status: down + Speed: Unknown + Duplex: Unknown + Link Failure Count: 0 + Permanent HW addr: 00:50:56:bf:19:26 + Slave queue ID: 0 + Aggregator ID: 2 + Actor Churn State: churned + Partner Churn State: churned + Actor Churned Count: 1 + Partner Churned Count: 1 + diff --git a/docs/configuration/interfaces/bridge.rst b/docs/configuration/interfaces/bridge.rst new file mode 100644 index 00000000..7f49f9a8 --- /dev/null +++ b/docs/configuration/interfaces/bridge.rst @@ -0,0 +1,316 @@ +.. _bridge-interface: + +###### +Bridge +###### + +A Bridge is a way to connect two Ethernet segments together in a +protocol independent way. Packets are forwarded based on Ethernet +address, rather than IP address (like a router). Since forwarding is +done at Layer 2, all protocols can go transparently through a bridge. +The Linux bridge code implements a subset of the ANSI/IEEE 802.1d +standard. + +.. note:: Spanning Tree Protocol is not enabled by default in VyOS. + :ref:`stp` can be easily enabled if needed. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: bridge + :var1: br0 + +Member Interfaces +================= + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + + Assign `<member>` interface to bridge `<interface>`. A completion + helper will help you with all allowed interfaces which can be + bridged. This includes :ref:`ethernet-interface`, + :ref:`bond-interface`, :ref:`l2tpv3-interface`, :ref:`openvpn`, + :ref:`vxlan-interface`, :ref:`wireless-interface`, + :ref:`tunnel-interface` and :ref:`geneve-interface`. + + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + priority <priority> + + Configure individual bridge port `<priority>`. + + Each bridge has a relative priority and cost. Each interface is + associated with a port (number) in the STP code. Each has a priority + 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 + performance. + + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + cost <cost> + + Path `<cost>` value for Spanning Tree Protocol. Each interface in a + bridge could have a different speed and this value is used when + deciding which link to use. Faster interfaces should have lower + costs. + +Bridge Options +============== + +.. cfgcmd:: set interfaces bridge <interface> aging <time> + + MAC address aging `<time`> in seconds (default: 300). + +.. cfgcmd:: set interfaces bridge <interface> max-age <time> + + Bridge maximum aging `<time>` in seconds (default: 20). + + If a 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 + + Enable IGMP querier + +.. _stp: + +STP Parameter +------------- + +:abbr:`STP (Spanning Tree Protocol)` is a network protocol that builds a +loop-free logical topology for Ethernet networks. The basic function of +STP is to prevent bridge loops and the broadcast radiation that results +from them. Spanning tree also allows a network design to include backup +links providing fault tolerance if an active link fails. + +.. cfgcmd:: set interfaces bridge <interface> stp + + Enable spanning tree protocol. STP is disabled by default. + + +.. cfgcmd:: set interfaces bridge <interface> forwarding-delay <delay> + + 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 + so that when a new bridge comes onto a busy network it looks at some + traffic before participating. + + +.. cfgcmd:: set interfaces bridge <interface> hello-time <interval> + + Spanning Tree Protocol hello advertisement `<interval>` in seconds + (default: 2). + + Periodically, a hello packet is sent out by the Root Bridge and the + Designated Bridges. Hello packets are used to communicate information + about the topology throughout the entire Bridged Local Area Network. + +VLAN +==== + +Enable VLAN-Aware Bridge +------------------------ + +.. cfgcmd:: set interfaces bridge <interface> enable-vlan + + To activate the VLAN aware bridge, you must activate this setting to use VLAN + settings for the bridge + +VLAN Options +------------ + +.. note:: It is not valid to use the `vif 1` option for VLAN aware bridges + because VLAN aware bridges assume that all unlabeled packets belong to + the default VLAN 1 member and that the VLAN ID of the bridge's parent + interface is always 1 + +.. cmdinclude:: /_include/interface-vlan-8021q.txt + :var0: bridge + :var1: br0 + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + native-vlan <vlan-id> + + Set the native VLAN ID flag of the interface. When a data packet without a + VLAN tag enters the port, the data packet will be forced to add a tag of a + specific vlan id. When the vlan id flag flows out, the tag of the vlan id + will be stripped + + Example: Set `eth0` member port to be native VLAN 2 + + .. code-block:: none + + set interfaces bridge br1 member interface eth0 native-vlan 2 + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> + allowed-vlan <vlan-id> + + Allows specific VLAN IDs to pass through the bridge member interface. This + can either be an individual VLAN id or a range of VLAN ids delimited by a + hyphen. + + Example: Set `eth0` member port to be allowed VLAN 4 + + .. code-block:: none + + set interfaces bridge br1 member interface eth0 allowed-vlan 4 + + Example: Set `eth0` member port to be allowed VLAN 6-8 + + .. code-block:: none + + set interfaces bridge br1 member interface eth0 allowed-vlan 6-8 + +Port Mirror (SPAN) +================== +.. cmdinclude:: ../../_include/interface-mirror.txt + :var0: bridge + :var1: br1 + :var2: eth3 + +******** +Examples +******** + +Create a basic bridge +===================== + +Creating a bridge interface is very simple. In this example we will +have: + +* A bridge named `br100` +* Member interfaces `eth1` and VLAN 10 on interface `eth2` +* Enable STP +* Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64 + +.. code-block:: none + + set interfaces bridge br100 address 192.0.2.1/24 + set interfaces bridge br100 address 2001:db8::ffff/64 + set interfaces bridge br100 member interface eth1 + set interfaces bridge br100 member interface eth2.10 + set interfaces bridge br100 stp + +This results in the active configuration: + +.. code-block:: none + + vyos@vyos# show interfaces bridge br100 + address 192.0.2.1/24 + address 2001:db8::ffff/64 + member { + interface eth1 { + } + interface eth2.10 { + } + } + stp + + +Using VLAN aware Bridge +======================= + +An example of creating a VLAN-aware bridge is as follows: + +* A bridge named `br100` +* The member interface `eth1` is a trunk that allows VLAN 10 to pass +* VLAN 10 on member interface `eth2` (ACCESS mode) +* Enable STP +* Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64 + +.. code-block:: none + + set interfaces bridge br100 enable-vlan + set interfaces bridge br100 member interface eth1 allowed-vlan 10 + set interfaces bridge br100 member interface eth2 native-vlan 10 + set interfaces bridge br100 vif 10 address 192.0.2.1/24 + set interfaces bridge br100 vif 10 address 2001:db8::ffff/64 + set interfaces bridge br100 stp + +This results in the active configuration: + +.. code-block:: none + + vyos@vyos# show interfaces bridge br100 + enable-vlan + member { + interface eth1 { + allowed-vlan 10 + } + interface eth2 { + native-vlan 10 + } + } + stp + vif 10 { + address 192.0.2.1/24 + address 2001:db8::ffff/64 + } + + +Using the operation mode command to view Bridge Information +=========================================================== + +.. opcmd:: show bridge + + The `show bridge` operational command can be used to display + configured bridges: + + .. code-block:: none + + vyos@vyos:~$ show bridge + bridge name bridge id STP enabled interfaces + br100 8000.0050569d11df yes eth1 + eth2.10 + +.. opcmd:: show bridge <name> spanning-tree + + Show bridge `<name>` STP configuration. + + .. code-block:: none + + vyos@vyos:~$ show bridge br100 spanning-tree + br100 + bridge id 8000.0050569d11df + designated root 8000.0050569d11df + root port 0 path cost 0 + max age 20.00 bridge max age 20.00 + hello time 2.00 bridge hello time 2.00 + forward delay 14.00 bridge forward delay 14.00 + ageing time 300.00 + hello timer 0.06 tcn timer 0.00 + topology change timer 0.00 gc timer 242.02 + flags + + eth1 (1) + port id 8001 state disabled + designated root 8000.0050569d11df path cost 100 + designated bridge 8000.0050569d11df message age timer 0.00 + designated port 8001 forward delay timer 0.00 + designated cost 0 hold timer 0.00 + flags + + eth2.10 (2) + port id 8002 state disabled + designated root 8000.0050569d11df path cost 100 + designated bridge 8000.0050569d11df message age timer 0.00 + designated port 8002 forward delay timer 0.00 + designated cost 0 hold timer 0.00 + +.. opcmd: show bridge <name> macs + + Show bridge Media Access Control (MAC) address table + + .. code-block:: none + + vyos@vyos:~$ show bridge br100 macs + port no mac addr is local? ageing timer + 1 00:53:29:44:3b:19 yes 0.00 diff --git a/docs/configuration/interfaces/dummy.rst b/docs/configuration/interfaces/dummy.rst new file mode 100644 index 00000000..c9845230 --- /dev/null +++ b/docs/configuration/interfaces/dummy.rst @@ -0,0 +1,79 @@ +.. _dummy-interface: + +##### +Dummy +##### + +The dummy interface is really a little exotic, but rather useful nevertheless. +Dummy interfaces are much like the :ref:`loopback-interface` interface, except +you can have as many as you want. + +.. note:: Dummy interfaces can be used as interfaces that always stay up (in + the same fashion to loopbacks in Cisco IOS), or for testing purposes. + +.. hint:: A Dummy interface is always up, thus it could be used for + management traffic or as source/destination for and :abbr:`IGP (Interior + Gateway Protocol)` like :ref:`bgp` so your internal BGP link is not dependent + on physical link states and multiple routes can be chosen to the + destination. A :ref:`dummy-interface` Interface should always be preferred + over a :ref:`loopback-interface` interface. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-address.txt + :var0: dummy + :var1: dum0 + +.. cmdinclude:: /_include/interface-description.txt + :var0: dummy + :var1: dum0 + +.. cmdinclude:: /_include/interface-disable.txt + :var0: dummy + :var1: dum0 + +.. cmdinclude:: /_include/interface-vrf.txt + :var0: dummy + :var1: dum0 + +********* +Operation +********* + +.. opcmd:: show interfaces dummy + + Show brief interface information.information + + .. code-block:: none + + vyos@vyos:~$ show interfaces dummy + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + dum0 172.18.254.201/32 u/u + +.. opcmd:: show interfaces dummy <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 + dum0: <BROADCAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN group default qlen 1000 + link/ether 26:7c:8e:bc:fc:f5 brd ff:ff:ff:ff:ff:ff + inet 172.18.254.201/32 scope global dum0 + valid_lft forever preferred_lft forever + inet6 fe80::247c:8eff:febc:fcf5/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 0 0 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 1369707 4267 0 0 0 0 + + diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst new file mode 100644 index 00000000..1d99019c --- /dev/null +++ b/docs/configuration/interfaces/ethernet.rst @@ -0,0 +1,315 @@ +.. _ethernet-interface: + +######## +Ethernet +######## + +This will be the most widely used interface on a router carrying traffic to the +real world. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: ethernet + :var1: eth0 + +Ethernet options +================ + +.. cfgcmd:: set interfaces ethernet <interface> duplex <auto | full | half> + + Configure physical interface duplex setting. + + * auto - interface duplex setting is auto-negotiated + * full - always use full-duplex + * half - always use half-duplex + + VyOS default will be `auto`. + +.. cfgcmd:: set interfaces ethernet <interface> speed <auto | 10 | 100 | 1000 | + 2500 | 5000 | 10000 | 25000 | 40000 | 50000 | 100000> + + Configure physical interface speed setting. + + * auto - interface speed is auto-negotiated + * 10 - 10 MBit/s + * 100 - 100 MBit/s + * 1000 - 1 GBit/s + * 2500 - 2.5 GBit/s + * 5000 - 5 GBit/s + * 10000 - 10 GBit/s + * 25000 - 25 GBit/s + * 40000 - 40 GBit/s + * 50000 - 50 GBit/s + * 100000 - 100 GBit/s + + VyOS default will be `auto`. + + +.. cfgcmd:: set interfaces ethernet <interface> mirror <interface> + + Use this command to mirror the inbound traffic from one Ethernet interface to + another interface. This feature is typically used to provide a copy of traffic + inbound on one interface to a system running a monitoring or IPS application + on another interface. The benefit of mirroring the traffic is that the + application is isolated from the source traffic and so application processing + does not affect the traffic or the system performance. + + Example: + + .. code-block:: none + + set interfaces ethernet eth0 mirror eth1 + +Offloading +---------- + +.. cfgcmd:: set interfaces ethernet <interface> offload <gro | gso | sg | tso | + ufo | rps> + + Enable different types of hardware offloading on the given NIC. + + :abbr:`GSO (Generic Segmentation Offload)` is a pure software offload that is + meant to deal with cases where device drivers cannot perform the offloads + described above. What occurs in GSO is that a given skbuff will have its data + broken out over multiple skbuffs that have been resized to match the MSS + provided via skb_shinfo()->gso_size. + + Before enabling any hardware segmentation offload a corresponding software + offload is required in GSO. Otherwise it becomes possible for a frame to be + re-routed between devices and end up being unable to be transmitted. + + :abbr:`GRO (Generic receive offload)` is the complement to GSO. Ideally any + frame assembled by GRO should be segmented to create an identical sequence of + frames using GSO, and any sequence of frames segmented by GSO should be able + to be reassembled back to the original by GRO. The only exception to this is + IPv4 ID in the case that the DF bit is set for a given IP header. If the + value of the IPv4 ID is not sequentially incrementing it will be altered so + that it is when a frame assembled via GRO is segmented via GSO. + + :abbr:`RPS (Receive Packet Steering)` is logically a software implementation + of :abbr:`RSS (Receive Side Scaling)`. Being in software, it is necessarily + called later in the datapath. Whereas RSS selects the queue and hence CPU that + will run the hardware interrupt handler, RPS selects the CPU to perform + protocol processing above the interrupt handler. This is accomplished by + placing the packet on the desired CPU's backlog queue and waking up the CPU + for processing. RPS has some advantages over RSS: + + - it can be used with any NIC, + - software filters can easily be added to hash over new protocols, + - it does not increase hardware device interrupt rate (although it does + introduce inter-processor interrupts (IPIs)). + + +.. cmdinclude:: /_include/interface-xdp.txt + :var0: ethernet + :var1: eth0 + +Authentication (EAPoL) +---------------------- + +.. cmdinclude:: /_include/interface-eapol.txt + :var0: ethernet + :var1: eth0 + + +VLAN +==== + +Regular VLANs (802.1q) +---------------------- + +.. cmdinclude:: /_include/interface-vlan-8021q.txt + :var0: ethernet + :var1: eth0 + +QinQ (802.1ad) +-------------- + +.. cmdinclude:: /_include/interface-vlan-8021ad.txt + :var0: ethernet + :var1: eth0 + +Port Mirror (SPAN) +================== +.. cmdinclude:: ../../_include/interface-mirror.txt + :var0: ethernet + :var1: eth1 + :var2: eth3 + +********* +Operation +********* + +.. opcmd:: show interfaces ethernet + + Show brief interface information. + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 172.18.201.10/24 u/u LAN + eth1 172.18.202.11/24 u/u WAN + eth2 - u/D + +.. opcmd:: show interfaces ethernet <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 + eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 + link/ether 00:50:44:00:f5:c9 brd ff:ff:ff:ff:ff:ff + inet6 fe80::250:44ff:fe00:f5c9/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 56735451 179841 0 0 0 142380 + TX: bytes packets errors dropped carrier collisions + 5601460 62595 0 0 0 0 + +.. stop_vyoslinter + +.. opcmd:: show interfaces ethernet <interface> physical + + Show information about physical `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 physical + Settings for eth0: + Supported ports: [ TP ] + Supported link modes: 1000baseT/Full + 10000baseT/Full + Supported pause frame use: No + Supports auto-negotiation: No + Supported FEC modes: Not reported + Advertised link modes: Not reported + Advertised pause frame use: No + Advertised auto-negotiation: No + Advertised FEC modes: Not reported + Speed: 10000Mb/s + Duplex: Full + Port: Twisted Pair + PHYAD: 0 + Transceiver: internal + Auto-negotiation: off + MDI-X: Unknown + Supports Wake-on: uag + Wake-on: d + Link detected: yes + driver: vmxnet3 + version: 1.4.16.0-k-NAPI + firmware-version: + expansion-rom-version: + bus-info: 0000:0b:00.0 + supports-statistics: yes + supports-test: no + supports-eeprom-access: no + supports-register-dump: yes + supports-priv-flags: no + +.. start_vyoslinter + +.. opcmd:: show interfaces ethernet <interface> physical offload + + Show available offloading functions on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 physical offload + rx-checksumming on + tx-checksumming on + tx-checksum-ip-generic on + scatter-gather off + tx-scatter-gather off + tcp-segmentation-offload off + tx-tcp-segmentation off + tx-tcp-mangleid-segmentation off + tx-tcp6-segmentation off + udp-fragmentation-offload off + generic-segmentation-offload off + generic-receive-offload off + large-receive-offload off + rx-vlan-offload on + tx-vlan-offload on + ntuple-filters off + receive-hashing on + tx-gre-segmentation on + tx-gre-csum-segmentation on + tx-udp_tnl-segmentation on + tx-udp_tnl-csum-segmentation on + tx-gso-partial on + tx-nocache-copy off + rx-all off + +.. opcmd:: show interfaces ethernet <interface> transceiver + + Show transceiver information from plugin modules, e.g SFP+, QSFP + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth5 transceiver + Identifier : 0x03 (SFP) + Extended identifier : 0x04 (GBIC/SFP defined by 2-wire interface ID) + Connector : 0x07 (LC) + Transceiver codes : 0x00 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00 + Transceiver type : Ethernet: 1000BASE-SX + Encoding : 0x01 (8B/10B) + BR, Nominal : 1300MBd + Rate identifier : 0x00 (unspecified) + Length (SMF,km) : 0km + Length (SMF) : 0m + Length (50um) : 550m + Length (62.5um) : 270m + Length (Copper) : 0m + Length (OM3) : 0m + Laser wavelength : 850nm + Vendor name : CISCO-FINISAR + Vendor OUI : 00:90:65 + Vendor PN : FTRJ-8519-7D-CS4 + Vendor rev : A + Option values : 0x00 0x1a + Option : RX_LOS implemented + Option : TX_FAULT implemented + Option : TX_DISABLE implemented + BR margin, max : 0% + BR margin, min : 0% + Vendor SN : FNS092xxxxx + Date code : 0506xx + +.. stop_vyoslinter + +.. opcmd:: show interfaces ethernet <interface> xdp + + Display XDP forwarding statistics + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth1 xdp + + Collecting stats from BPF map + - BPF map (bpf_map_type:6) id:176 name:xdp_stats_map key_size:4 value_size:16 max_entries:5 + XDP-action + XDP_ABORTED 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250340 + XDP_DROP 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250317 + XDP_PASS 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250314 + XDP_TX 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250313 + XDP_REDIRECT 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250313 + + XDP-action + XDP_ABORTED 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000410 + XDP_DROP 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000414 + 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 new file mode 100644 index 00000000..9e00d621 --- /dev/null +++ b/docs/configuration/interfaces/geneve.rst @@ -0,0 +1,61 @@ +.. _geneve-interface: + +###### +GENEVE +###### + +:abbr:`GENEVE (Generic Network Virtualization Encapsulation)` supports all of +the capabilities of :abbr:`VXLAN (Virtual Extensible LAN)`, :abbr:`NVGRE +(Network Virtualization using Generic Routing Encapsulation)`, and :abbr:`STT +(Stateless Transport Tunneling)` and was designed to overcome their perceived +limitations. Many believe GENEVE could eventually replace these earlier formats +entirely. + +GENEVE is designed to support network virtualization use cases, where tunnels +are typically established to act as a backplane between the virtual switches +residing in hypervisors, physical switches, or middleboxes or other appliances. +An arbitrary IP network can be used as an underlay although Clos networks - A +technique for composing network fabrics larger than a single switch while +maintaining non-blocking bandwidth across connection points. ECMP is used to +divide traffic across the multiple links and switches that constitute the +fabric. Sometimes termed "leaf and spine" or "fat tree" topologies. + +Geneve Header: + +.. code-block:: none + + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + |Ver| Opt Len |O|C| Rsvd. | Protocol Type | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Virtual Network Identifier (VNI) | Reserved | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Variable Length Options | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-without-dhcp.txt + :var0: geneve + :var1: gnv0 + +GENEVE options +============== + +.. cfgcmd:: set interfaces geneve gnv0 remote <address> + + Configure GENEVE tunnel far end/remote tunnel endpoint. + +.. cfgcmd:: set interfaces geneve gnv0 vni <vni> + + :abbr:`VNI (Virtual Network Identifier)` is an identifier for a unique + element of a virtual network. In many situations this may represent an L2 + segment, however, the control plane defines the forwarding semantics of + decapsulated packets. The VNI MAY be used as part of ECMP forwarding + decisions or MAY be used as a mechanism to distinguish between overlapping + address spaces contained in the encapsulated packet when load balancing + across CPUs. diff --git a/docs/configuration/interfaces/index.rst b/docs/configuration/interfaces/index.rst new file mode 100644 index 00000000..85d2c177 --- /dev/null +++ b/docs/configuration/interfaces/index.rst @@ -0,0 +1,28 @@ +########## +Interfaces +########## + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + bonding + bridge + dummy + ethernet + geneve + l2tpv3 + loopback + macsec + openvpn + pppoe + pseudo-ethernet + tunnel + vti + vxlan + wireguard + wireless + wirelessmodem + + diff --git a/docs/configuration/interfaces/l2tpv3.rst b/docs/configuration/interfaces/l2tpv3.rst new file mode 100644 index 00000000..a4b7be36 --- /dev/null +++ b/docs/configuration/interfaces/l2tpv3.rst @@ -0,0 +1,192 @@ +.. include:: /_include/need_improvement.txt + +.. _l2tpv3-interface: + +###### +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 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 +effort, at the cost of losing some technical features considered less important +in the market. + +In the case of L2TPv3, the features lost are teletraffic engineering features +considered important in MPLS. However, there is no reason these features could +not be re-engineered in or on top of L2TPv3 in later products. + +The protocol overhead of L2TPv3 is also significantly bigger than MPLS. + +L2TPv3 is described in :rfc:`3921`. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-without-dhcp.txt + :var0: l2tpv3 + :var1: l2tpeth0 + +L2TPv3 options +============== + +.. cfgcmd:: set interfaces l2tpv3 <interface> encapsulation <udp | ip> + + Set the encapsulation type of the tunnel. Valid values for encapsulation are: + udp, ip. + + This defaults to UDP + +.. cfgcmd:: set interfaces l2tpv3 <interface> local-ip <address> + + 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. + +.. cfgcmd:: set interfaces l2tpv3 <interface> remote-ip <address> + + Set the IP address of the remote peer. May be specified as an IPv4 address or + an IPv6 address. + +.. cfgcmd:: set interfaces l2tpv3 <interface> session-id <id> + + Set the session id, which is a 32-bit integer value. Uniquely identifies the + session being created. The value used must match the peer_session_id value + being used at the peer. + +.. cfgcmd:: set interfaces l2tpv3 <interface> peer-session-id <id> + + 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. + +.. cfgcmd:: set interfaces l2tpv3 <interface> tunnel-id <id> + + Set the tunnel id, which is a 32-bit integer value. Uniquely identifies the + tunnel into which the session will be created. + +.. cfgcmd:: set interfaces l2tpv3 <interface> peer-tunnel-id <id> + + Set the tunnel id, which is a 32-bit integer value. Uniquely identifies the + tunnel into which the session will be created. + +******* +Example +******* + +Over IP +======= + +.. code-block:: none + + # show interfaces l2tpv3 + l2tpv3 l2tpeth10 { + address 192.168.37.1/27 + encapsulation ip + local-ip 192.0.2.1 + peer-session-id 100 + peer-tunnel-id 200 + remote-ip 203.0.113.24 + session-id 100 + tunnel-id 200 + } + +Inverse configuration has to be applied to the remote side. + +Over UDP +======== + +UDP mode works better with NAT: + +* Set local-ip to your local IP (LAN). +* Add a forwarding rule matching UDP port on your internet router. + +.. code-block:: none + + # show interfaces l2tpv3 + l2tpv3 l2tpeth10 { + address 192.168.37.1/27 + destination-port 9001 + encapsulation udp + local-ip 192.0.2.1 + peer-session-id 100 + peer-tunnel-id 200 + remote-ip 203.0.113.24 + session-id 100 + source-port 9000 + tunnel-id 200 + } + +To create more than one tunnel, use distinct UDP ports. + + +Over IPSec, L2 VPN (bridge) +=========================== + +This is the LAN extension use case. The eth0 port of the distant VPN peers +will be directly connected like if there was a switch between them. + +IPSec: + +.. code-block:: none + + set vpn ipsec ipsec-interfaces <VPN-interface> + set vpn ipsec esp-group test-ESP-1 compression 'disable' + set vpn ipsec esp-group test-ESP-1 lifetime '3600' + set vpn ipsec esp-group test-ESP-1 mode 'transport' + set vpn ipsec esp-group test-ESP-1 pfs 'enable' + set vpn ipsec esp-group test-ESP-1 proposal 1 encryption 'aes128' + set vpn ipsec esp-group test-ESP-1 proposal 1 hash 'sha1' + set vpn ipsec ike-group test-IKE-1 ikev2-reauth 'no' + set vpn ipsec ike-group test-IKE-1 key-exchange 'ikev1' + set vpn ipsec ike-group test-IKE-1 lifetime '3600' + set vpn ipsec ike-group test-IKE-1 proposal 1 dh-group '5' + set vpn ipsec ike-group test-IKE-1 proposal 1 encryption 'aes128' + set vpn ipsec ike-group test-IKE-1 proposal 1 hash 'sha1' + set vpn ipsec site-to-site peer <peer-ip> authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer <peer-ip> authentication pre-shared-secret <pre-shared-key> + set vpn ipsec site-to-site peer <peer-ip> connection-type 'initiate' + set vpn ipsec site-to-site peer <peer-ip> ike-group 'test-IKE-1' + set vpn ipsec site-to-site peer <peer-ip> ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer <peer-ip> local-address <local-ip> + set vpn ipsec site-to-site peer <peer-ip> tunnel 1 allow-nat-networks 'disable' + set vpn ipsec site-to-site peer <peer-ip> tunnel 1 allow-public-networks 'disable' + set vpn ipsec site-to-site peer <peer-ip> tunnel 1 esp-group 'test-ESP-1' + set vpn ipsec site-to-site peer <peer-ip> tunnel 1 protocol 'l2tp' + +Bridge: + +.. code-block:: none + + set interfaces bridge br0 description 'L2 VPN Bridge' + # remote side in this example: + # set interfaces bridge br0 address '172.16.30.18/30' + set interfaces bridge br0 address '172.16.30.17/30' + set interfaces bridge br0 member interface eth0 + set interfaces ethernet eth0 description 'L2 VPN Physical port' + +L2TPv3: + +.. code-block:: none + + set interfaces bridge br0 member interface 'l2tpeth0' + set interfaces l2tpv3 l2tpeth0 description 'L2 VPN Tunnel' + set interfaces l2tpv3 l2tpeth0 destination-port '5000' + set interfaces l2tpv3 l2tpeth0 encapsulation 'ip' + set interfaces l2tpv3 l2tpeth0 local-ip <local-ip> + set interfaces l2tpv3 l2tpeth0 mtu '1500' + set interfaces l2tpv3 l2tpeth0 peer-session-id '110' + set interfaces l2tpv3 l2tpeth0 peer-tunnel-id '10' + set interfaces l2tpv3 l2tpeth0 remote-ip <peer-ip> + set interfaces l2tpv3 l2tpeth0 session-id '110' + set interfaces l2tpv3 l2tpeth0 source-port '5000' + set interfaces l2tpv3 l2tpeth0 tunnel-id '10' diff --git a/docs/configuration/interfaces/loopback.rst b/docs/configuration/interfaces/loopback.rst new file mode 100644 index 00000000..f7386c62 --- /dev/null +++ b/docs/configuration/interfaces/loopback.rst @@ -0,0 +1,71 @@ +.. _loopback-interface: + +######## +Loopback +######## + +The loopback networking interface is a virtual network device implemented +entirely in software. All traffic sent to it "loops back" and just targets +services on your local machine. + +.. note:: There can only be one loopback ``lo`` interface on the system. If + you need multiple interfaces, please use the :ref:`dummy-interface` + interface type. + +.. hint:: A lookback interface is always up, thus it could be used for + management traffic or as source/destination for and :abbr:`IGP (Interior + Gateway Protocol)` like :ref:`bgp` so your internal BGP link is not dependent + on physical link states and multiple routes can be chosen to the + destination. A :ref:`dummy-interface` Interface should always be preferred + over a :ref:`loopback-interface` interface. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-address.txt + :var0: loopback + :var1: lo + +.. cmdinclude:: /_include/interface-description.txt + :var0: loopback + :var1: lo + +********* +Operation +********* + +.. opcmd:: show interfaces loopback + + Show brief interface information. + + .. code-block:: none + + vyos@vyos:~$ show interfaces loopback + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + lo 127.0.0.1/8 u/u + ::1/128 + +.. opcmd:: show interfaces loopback lo + + Show detailed information on given loopback interface `lo`. + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 + lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 + inet 127.0.0.1/8 scope host lo + valid_lft forever preferred_lft forever + inet6 ::1/128 scope host + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 300 6 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 300 6 0 0 0 0 diff --git a/docs/configuration/interfaces/macsec.rst b/docs/configuration/interfaces/macsec.rst new file mode 100644 index 00000000..2bf643aa --- /dev/null +++ b/docs/configuration/interfaces/macsec.rst @@ -0,0 +1,191 @@ +.. _macsec-interface: + +###### +MACsec +###### + +MACsec is an IEEE standard (IEEE 802.1AE) for MAC security, introduced in 2006. +It defines a way to establish a protocol independent connection between two +hosts with data confidentiality, authenticity and/or integrity, using +GCM-AES-128. MACsec operates on the Ethernet layer and as such is a layer 2 +protocol, which means it's designed to secure traffic within a layer 2 network, +including DHCP or ARP requests. It does not compete with other security +solutions such as IPsec (layer 3) or TLS (layer 4), as all those solutions are +used for their own specific use cases. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: macsec + :var1: macsec0 + +MACsec options +============== + +.. cfgcmd:: set interfaces macsec <interface> security cipher [gcm-aes-128] + + Select cipher suite used for cryptographic operations. This setting is + mandatory. + + .. note:: gcm-aes-256 support planned once iproute2 package is updated to + version >=5.2. + +.. cfgcmd:: set interfaces macsec <interface> security encrypt + + MACsec only provides authentication by default, encryption is optional. This + command will enable encryption for all outgoing packets. + +.. 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. + +Key Management +-------------- + +:abbr:`MKA (MACsec Key Agreement protocol)` is used to synchronize keys between +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 + a pre-shared key using a (CAK,CKN) pair. + +.. cfgcmd:: set interfaces macsec <interface> security mka ckn <key> + + CAK Name + +.. cfgcmd:: set interfaces macsec <interface> security mka priority <priority> + + The peer with lower priority will become the key server and start + distributing SAKs. + +Replay protection +----------------- + +.. cfgcmd:: set interfaces macsec <interface> security replay-window <window> + + IEEE 802.1X/MACsec replay protection window. This determines a window in which + replay is tolerated, to allow receipt of frames that have been misordered by + the network. + + - ``0``: No replay window, strict check + - ``1-4294967295``: Number of packets that could be misordered + +********* +Operation +********* + +.. opcmd:: run generate macsec mka-cak + + Generate :abbr:`MKA (MACsec Key Agreement protocol)` CAK key + + .. code-block:: none + + vyos@vyos:~$ generate macsec mka-cak + 20693b6e08bfa482703a563898c9e3ad + + +.. opcmd:: run generate macsec mka-ckn + + Generate :abbr:`MKA (MACsec Key Agreement protocol)` CAK key + + .. code-block:: none + + vyos@vyos:~$ generate macsec mka-ckn + 88737efef314ee319b2cbf30210a5f164957d884672c143aefdc0f5f6bc49eb2 + +.. opcmd:: show interfaces macsec + + List all MACsec interfaces + + .. code-block:: none + + vyos@vyos:~$ show interfaces macsec + 17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off + cipher suite: GCM-AES-128, using ICV length 16 + TXSC: 005056bfefaa0001 on SA 0 + 20: macsec0: protect on validate strict sc off sa off encrypt off send_sci on end_station off scb off replay off + cipher suite: GCM-AES-128, using ICV length 16 + TXSC: 005056bfefaa0001 on SA 0 + +.. opcmd:: show interfaces macsec <interface> + + Show specific MACsec interface information + + .. code-block:: none + + vyos@vyos:~$ show interfaces macsec macsec1 + 17: macsec1: protect on validate strict sc off sa off encrypt on send_sci on end_station off scb off replay off + cipher suite: GCM-AES-128, using ICV length 16 + TXSC: 005056bfefaa0001 on SA 0 + +******** +Examples +******** + +* Two routers connected both via eth1 through an untrusted switch +* R1 has 192.0.2.1/24 & 2001:db8::1/64 +* R2 has 192.0.2.2/24 & 2001:db8::2/64 + +**R1** + +.. code-block:: none + + set interfaces macsec macsec1 address '192.0.2.1/24' + set interfaces macsec macsec1 address '2001:db8::1/64' + set interfaces macsec macsec1 security cipher 'gcm-aes-128' + set interfaces macsec macsec1 security encrypt + set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' + set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' + set interfaces macsec macsec1 source-interface 'eth1' + +**R2** + +.. code-block:: none + + set interfaces macsec macsec1 address '192.0.2.2/24' + set interfaces macsec macsec1 address '2001:db8::2/64' + set interfaces macsec macsec1 security cipher 'gcm-aes-128' + set interfaces macsec macsec1 security encrypt + set interfaces macsec macsec1 security mka cak '232e44b7fda6f8e2d88a07bf78a7aff4' + set interfaces macsec macsec1 security mka ckn '40916f4b23e3d548ad27eedd2d10c6f98c2d21684699647d63d41b500dfe8836' + set interfaces macsec macsec1 source-interface 'eth1' + +Pinging (IPv6) the other host and intercepting the traffic in ``eth1`` will +show you the content is encrypted. + +.. code-block:: none + + 17:35:44.586668 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: + 0x0000: 2c00 0000 000a 0050 56bf efaa 0001 d9fb ,......PV....... + 0x0010: 920a 8b8d 68ed 9609 29dd e767 25a4 4466 ....h...)..g%.Df + 0x0020: 5293 487b 9990 8517 3b15 22c7 ea5c ac83 R.H{....;."..\.. + 0x0030: 4c6e 13cf 0743 f917 2c4e 694e 87d1 0f09 Ln...C..,NiN.... + 0x0040: 0f77 5d53 ed75 cfe1 54df 0e5a c766 93cb .w]S.u..T..Z.f.. + 0x0050: c4f2 6e23 f200 6dfe 3216 c858 dcaa a73b ..n#..m.2..X...; + 0x0060: 4dd1 9358 d9e4 ed0e 072f 1acc 31c4 f669 M..X...../..1..i + 0x0070: e93a 9f38 8a62 17c6 2857 6ac5 ec11 8b0e .:.8.b..(Wj..... + 0x0080: 6b30 92a5 7ccc 720b k0..|.r. + +Disabling the encryption on the link by removing ``security encrypt`` will show +the unencrypted but authenticated content. + +.. code-block:: none + + 17:37:00.746155 00:50:56:bf:ef:aa > 00:50:56:b3:ad:d6, ethertype Unknown (0x88e5), length 150: + 0x0000: 2000 0000 0009 0050 56bf efaa 0001 86dd .......PV....... + 0x0010: 6009 86f3 0040 3a40 2001 0db8 0000 0000 `....@:@........ + 0x0020: 0000 0000 0000 0001 2001 0db8 0000 0000 ................ + 0x0030: 0000 0000 0000 0002 8100 d977 0f30 0003 ...........w.0.. + 0x0040: 1ca0 c65e 0000 0000 8d93 0b00 0000 0000 ...^............ + 0x0050: 1011 1213 1415 1617 1819 1a1b 1c1d 1e1f ................ + 0x0060: 2021 2223 2425 2627 2829 2a2b 2c2d 2e2f .!"#$%&'()*+,-./ + 0x0070: 3031 3233 3435 3637 87d5 eed3 3a39 d52b 01234567....:9.+ + 0x0080: a282 c842 5254 ef28 ...BRT.( + diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/openvpn.rst new file mode 100644 index 00000000..8b32743f --- /dev/null +++ b/docs/configuration/interfaces/openvpn.rst @@ -0,0 +1,590 @@ +.. _openvpn: + +####### +OpenVPN +####### + +Traditionally hardware routers implement IPsec exclusively due to relative +ease of implementing it in hardware and insufficient CPU power for doing +encryption in software. Since VyOS is a software router, this is less of a +concern. OpenVPN has been widely used on UNIX platform for a long time and is +a popular option for remote access VPN, though it's also capable of +site-to-site connections. + +Advantages of OpenVPN are: + +* It uses a single TCP or UDP connection and does not rely on packet source + addresses, so it will work even through a double NAT: perfect for public + hotspots and such + +* It's easy to setup and offers very flexible split tunneling + +* There's a variety of client GUI frontends for any platform + +Disadvantages are: + +* It's slower than IPsec due to higher protocol overhead and the fact it runs + in user mode while IPsec, on Linux, is in kernel mode + +* None of the operating systems have client software installed by default + +In the VyOS CLI, a key point often overlooked is that rather than being +configured using the `set vpn` stanza, OpenVPN is configured as a network +interface using `set interfaces openvpn`. + +Site-To-Site +============ + +While many are aware of OpenVPN as a Client VPN solution, it is often +overlooked as a site-to-site VPN solution due to lack of support for this mode +in many router platforms. + +Site-to-site mode supports x.509 but doesn't require it and can also work with +static keys, which is simpler in many cases. In this example, we'll configure +a simple site-to-site OpenVPN tunnel using a 2048-bit pre-shared key. + +First, one of the systems generate the key using the operational command +``generate openvpn key <filename>``. This will generate a key with the name +provided in the ``/config/auth/`` directory. Once generated, you will need to +copy this key to the remote router. + +In our example, we used the filename ``openvpn-1.key`` which we will reference +in our configuration. + +* The public IP address of the local side of the VPN will be 198.51.100.10 +* The remote will be 203.0.113.11 +* The tunnel will use 10.255.1.1 for the local IP and 10.255.1.2 for the remote. +* OpenVPN allows for either TCP or UDP. UDP will provide the lowest latency, + while TCP will work better for lossy connections; generally UDP is preferred + when possible. +* The official port for OpenVPN is 1194, which we reserve for client VPN; we + will use 1195 for site-to-site VPN. +* The ``persistent-tunnel`` directive will allow us to configure tunnel-related + attributes, such as firewall policy as we would on any normal network + interface. +* If known, the IP of the remote router can be configured using the + ``remote-host`` directive; if unknown, it can be omitted. We will assume a + dynamic IP for our remote router. + +Local Configuration: + +.. code-block:: none + + set interfaces openvpn vtun1 mode site-to-site + set interfaces openvpn vtun1 protocol udp + set interfaces openvpn vtun1 persistent-tunnel + set interfaces openvpn vtun1 local-host '198.51.100.10' + set interfaces openvpn vtun1 local-port '1195' + set interfaces openvpn vtun1 remote-port '1195' + set interfaces openvpn vtun1 shared-secret-key-file '/config/auth/openvpn-1.key' + set interfaces openvpn vtun1 local-address '10.255.1.1' + set interfaces openvpn vtun1 remote-address '10.255.1.2' + +Remote Configuration: + +.. code-block:: none + + set interfaces openvpn vtun1 mode site-to-site + set interfaces openvpn vtun1 protocol udp + set interfaces openvpn vtun1 persistent-tunnel + set interfaces openvpn vtun1 remote-host '198.51.100.10' + set interfaces openvpn vtun1 local-port '1195' + set interfaces openvpn vtun1 remote-port '1195' + set interfaces openvpn vtun1 shared-secret-key-file '/config/auth/openvpn-1.key' + set interfaces openvpn vtun1 local-address '10.255.1.2' + 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. +SHA-1 is considered weak, but other hashing algorithms are available, as are +encryption algorithms: + +For Encryption: + +This sets the cipher when NCP (Negotiable Crypto Parameters) is disabled or +OpenVPN version < 2.4.0. + +.. code-block:: none + + vyos@vyos# set interfaces openvpn vtun1 encryption cipher + Possible completions: + des DES algorithm + 3des DES algorithm with triple encryption + bf128 Blowfish algorithm with 128-bit key + bf256 Blowfish algorithm with 256-bit key + aes128 AES algorithm with 128-bit key CBC + aes128gcm AES algorithm with 128-bit key GCM + aes192 AES algorithm with 192-bit key CBC + aes192gcm AES algorithm with 192-bit key GCM + aes256 AES algorithm with 256-bit key CBC + 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 +aes256gcm. The first cipher in this list is what server pushes to clients. + +.. code-block:: none + + vyos@vyos# set int open vtun0 encryption ncp-ciphers + Possible completions: + des DES algorithm + 3des DES algorithm with triple encryption + aes128 AES algorithm with 128-bit key CBC + aes128gcm AES algorithm with 128-bit key GCM + aes192 AES algorithm with 192-bit key CBC + aes192gcm AES algorithm with 192-bit key GCM + aes256 AES algorithm with 256-bit key CBC + aes256gcm AES algorithm with 256-bit key GCM + +For Hashing: + +.. code-block:: none + + vyos@vyos# set interfaces openvpn vtun1 hash + Possible completions: + md5 MD5 algorithm + sha1 SHA-1 algorithm + sha256 SHA-256 algorithm + sha512 SHA-512 algorithm + +If you change the default encryption and hashing algorithms, be sure that the +local and remote ends have matching configurations, otherwise the tunnel will +not come up. + +Static routes can be configured referencing the tunnel interface; for example, +the local router will use a network of 10.0.0.0/16, while the remote has a +network of 10.1.0.0/16: + +Local Configuration: + +.. code-block:: none + + set protocols static route 10.1.0.0/16 interface vtun1 + +Remote Configuration: + +.. code-block:: none + + 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. + +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 +referencing IP address or port number. One option is to dedicate a public IP +to each tunnel. Another option is to dedicate a port number to each tunnel +(e.g. 1195,1196,1197...). + +OpenVPN status can be verified using the `show openvpn` operational commands. +See the built-in help for a complete list of options. + +Server +====== + +Multi-client server is the most popular OpenVPN mode on routers. It always uses +x.509 authentication and therefore requires a PKI setup. Refer this section +**Generate X.509 Certificate and Keys** to generate a CA certificate, +a server certificate and key, a certificate revocation list, a Diffie-Hellman +key exchange parameters file. You do not need client certificates and keys for +the server setup. + +In this example we will use the most complicated case: a setup where each +client is a router that has its own subnet (think HQ and branch offices), since +simpler setups are subsets of it. + +Suppose you want to use 10.23.1.0/24 network for client tunnel endpoints and +all client subnets belong to 10.23.0.0/20. All clients need access to the +192.168.0.0/16 network. + +First we need to specify the basic settings. 1194/UDP is the default. The +``persistent-tunnel`` option is recommended, it prevents the TUN/TAP device from +closing on connection resets or daemon reloads. + +.. note:: Using **openvpn-option -reneg-sec** can be tricky. This option is + used to renegotiate data channel after n seconds. When used at both server + and client, the lower value will trigger the renegotiation. If you set it to + 0 on one side of the connection (to disable it), the chosen value on the + other side will determine when the renegotiation will occur. + +.. code-block:: none + + set interfaces openvpn vtun10 mode server + set interfaces openvpn vtun10 local-port 1194 + set interfaces openvpn vtun10 persistent-tunnel + set interfaces openvpn vtun10 protocol udp + +Then we need to specify the location of the cryptographic materials. Suppose +you keep the files in `/config/auth/openvpn` + +.. code-block:: none + + set interfaces openvpn vtun10 tls ca-cert-file /config/auth/openvpn/ca.crt + set interfaces openvpn vtun10 tls cert-file /config/auth/openvpn/server.crt + set interfaces openvpn vtun10 tls key-file /config/auth/openvpn/server.key + set interfaces openvpn vtun10 tls crl-file /config/auth/openvpn/crl.pem + set interfaces openvpn vtun10 tls dh-file /config/auth/openvpn/dh2048.pem + +Now we need to specify the server network settings. In all cases we need to +specify the subnet for client tunnel endpoints. Since we want clients to access +a specific network behind out router, we will use a push-route option for +installing that route on clients. + +.. code-block:: none + + set interfaces openvpn vtun10 server push-route 192.168.0.0/16 + set interfaces openvpn vtun10 server subnet 10.23.1.0/24 + +Since it's a HQ and branch offices setup, we will want all clients to have +fixed addresses and we will route traffic to specific subnets through them. We +need configuration for each client to achieve this. + +.. note:: Clients are identified by the CN field of their x.509 certificates, + in this example the CN is ``client0``: + +.. code-block:: none + + set interfaces openvpn vtun10 server client client0 ip 10.23.1.10 + set interfaces openvpn vtun10 server client client0 subnet 10.23.2.0/25 + +OpenVPN **will not** automatically create routes in the kernel for client +subnets when they connect and will only use client-subnet association +internally, so we need to create a route to the 10.23.0.0/20 network ourselves: + +.. code-block:: none + + set protocols static route 10.23.0.0/20 interface vtun10 + +Generate X.509 Certificate and Keys +----------------------------------- + +OpenVPN ships with a set of scripts called Easy-RSA that can generate the +appropriate files needed for an OpenVPN setup using X.509 certificates. +Easy-RSA comes installed by default on VyOS routers. + +Copy the Easy-RSA scripts to a new directory to modify the values. + +.. code-block:: none + + cp -r /usr/share/easy-rsa/ /config/my-easy-rsa-config + cd /config/my-easy-rsa-config + +To ensure the consistent use of values when generating the PKI, set default +values to be used by the PKI generating scripts. Rename the vars.example +filename to vars + +.. code-block:: none + + mv vars.example vars + +Following is the instance of the file after editing. You may also change other +values in the file at your discretion/need, though for most cases the defaults +should be just fine. (do not leave any of these parameters blank) + +.. code-block:: none + + set_var EASYRSA_DN "org" + set_var EASYRSA_REQ_COUNTRY "US" + set_var EASYRSA_REQ_PROVINCE "California" + set_var EASYRSA_REQ_CITY "San Francisco" + set_var EASYRSA_REQ_ORG "Copyleft Certificate Co" + set_var EASYRSA_REQ_EMAIL "me@example.net" + set_var EASYRSA_REQ_OU "My Organizational Unit" + set_var EASYRSA_KEY_SIZE 2048 + + +init-pki option will create a new pki directory or will delete any previously +generated certificates stored in that folder. The term 'central' is used to +refer server and 'branch' for client + +.. note:: Remember the “CA Key Passphrase” prompted in build-ca command, + as it will be asked in signing the server/client certificate. + +.. code-block:: none + + vyos@vyos:/config/my-easy-rsa-config$./easyrsa init-pki + vyos@vyos:/config/my-easy-rsa-config$./easyrsa build-ca + vyos@vyos:/config/my-easy-rsa-config$./easyrsa gen-req central nopass + vyos@vyos:/config/my-easy-rsa-config$./easyrsa sign-req server central + vyos@vyos:/config/my-easy-rsa-config$./easyrsa gen-dh + vyos@vyos:/config/my-easy-rsa-config$./easyrsa build-client-full branch1 nopass + +To generate a certificate revocation list for any client, execute these +commands: + +.. code-block:: none + + vyos@vyos:/config/my-easy-rsa-config$./easyrsa revoke client1 + vyos@vyos:/config/my-easy-rsa-config$ ./easyrsa gen-crl + +Copy the files to /config/auth/openvpn/ to use in OpenVPN tunnel creation + +.. code-block:: none + + vyos@vyos:/config/my-easy-rsa-config$ sudo mkdir /config/auth/openvpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/ca.crt /config/auth/openvpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/dh.pem /config/auth/openvpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/private/central.key /config/auth/openvpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/issued/central.crt /config/auth/openvpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/crl.pem /config/auth/openvpn + +Additionally, each client needs a copy of ca.crt and its own client key and +cert files. The files are plaintext so they may be copied either manually, +or through a remote file transfer tool like scp. Whichever method you use, +the files need to end up in the proper location on each router. +For example, Branch 1's router might have the following files: + +.. code-block:: none + + vyos@branch1-rtr:$ ls /config/auth/openvpn + ca.crt branch1.crt branch1.key + +Client Authentication +===================== + +LDAP +---- + +Enterprise installations usually ship a kind of directory service which is used +to have a single password store for all employees. VyOS and OpenVPN support +using LDAP/AD as single user backend. + +Authentication is done by using the ``openvpn-auth-ldap.so`` plugin which is +shipped with every VyOS installation. A dedicated configuration file is +required. It is best practise to store it in ``/config`` to survive image +updates + +.. code-block:: none + + 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: + +.. code-block:: none + + <LDAP> + # LDAP server URL + URL ldap://ldap.example.com + # Bind DN (If your LDAP server doesn't support anonymous binds) + BindDN cn=LDAPUser,dc=example,dc=com + # Bind Password password + Password S3cr3t + # Network timeout (in seconds) + Timeout 15 + </LDAP> + + <Authorization> + # Base DN + BaseDN "ou=people,dc=example,dc=com" + # User Search Filter + SearchFilter "(&(uid=%u)(objectClass=shadowAccount))" + # Require Group Membership - allow all users + RequireGroup false + </Authorization> + +Active Directory +^^^^^^^^^^^^^^^^ + +Despite the fact that AD is a superset of LDAP + +.. code-block:: none + + <LDAP> + # LDAP server URL + URL ldap://dc01.example.com + # Bind DN (If your LDAP server doesn’t support anonymous binds) + BindDN CN=LDAPUser,DC=example,DC=com + # Bind Password + Password mysecretpassword + # Network timeout (in seconds) + Timeout 15 + # Enable Start TLS + TLSEnable no + # Follow LDAP Referrals (anonymously) + FollowReferrals no + </LDAP> + + <Authorization> + # Base DN + BaseDN "DC=example,DC=com" + # User Search Filter, user must be a member of the VPN AD group + SearchFilter "(&(sAMAccountName=%u)(memberOf=CN=VPN,OU=Groups,DC=example,DC=com))" + # Require Group Membership + RequireGroup false # already handled by SearchFilter + <Group> + BaseDN "OU=Groups,DC=example,DC=com" + SearchFilter "(|(cn=VPN))" + MemberAttribute memberOf + </Group> + </Authorization> + +If you only want to check if the user account is enabled and can authenticate +(against the primary group) the following snipped is sufficient: + +.. code-block:: none + + <LDAP> + URL ldap://dc01.example.com + BindDN CN=SA_OPENVPN,OU=ServiceAccounts,DC=example,DC=com + Password ThisIsTopSecret + Timeout 15 + TLSEnable no + FollowReferrals no + </LDAP> + + <Authorization> + BaseDN "DC=example,DC=com" + SearchFilter "sAMAccountName=%u" + RequireGroup false + </Authorization> + +A complete LDAP auth OpenVPN configuration could look like the following +example: + +.. code-block:: none + + vyos@vyos# show interfaces openvpn + openvpn vtun0 { + mode server + openvpn-option "--tun-mtu 1500 --fragment 1300 --mssfix" + openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" + openvpn-option "--push redirect-gateway" + openvpn-option --duplicate-cn + openvpn-option --client-cert-not-required + openvpn-option --comp-lzo + openvpn-option --persist-key + openvpn-option --persist-tun + server { + domain-name example.com + max-connections 5 + name-server 203.0.113.0.10 + name-server 198.51.100.3 + subnet 172.18.100.128/29 + } + tls { + ca-cert-file /config/auth/ca.crt + cert-file /config/auth/server.crt + dh-file /config/auth/dh1024.pem + key-file /config/auth/server.key + } + } + +Client +====== + +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 +static client IP address to the OpenVPN client. Remember, clients are identified +using their CN attribute in the SSL certificate. + +Server +------ + +.. code-block:: none + + set interfaces openvpn vtun10 encryption cipher 'aes256' + set interfaces openvpn vtun10 hash 'sha512' + set interfaces openvpn vtun10 local-host '172.18.201.10' + set interfaces openvpn vtun10 local-port '1194' + set interfaces openvpn vtun10 mode 'server' + set interfaces openvpn vtun10 persistent-tunnel + set interfaces openvpn vtun10 protocol 'udp' + set interfaces openvpn vtun10 server client client1 ip '10.10.0.10' + set interfaces openvpn vtun10 server domain-name 'vyos.net' + set interfaces openvpn vtun10 server max-connections '250' + set interfaces openvpn vtun10 server name-server '172.16.254.30' + set interfaces openvpn vtun10 server subnet '10.10.0.0/24' + set interfaces openvpn vtun10 server topology 'subnet' + set interfaces openvpn vtun10 tls ca-cert-file '/config/auth/ca.crt' + set interfaces openvpn vtun10 tls cert-file '/config/auth/server.crt' + set interfaces openvpn vtun10 tls dh-file '/config/auth/dh.pem' + set interfaces openvpn vtun10 tls key-file '/config/auth/server.key' + set interfaces openvpn vtun10 use-lzo-compression + +Client +------ + +.. code-block:: none + + set interfaces openvpn vtun10 encryption cipher 'aes256' + set interfaces openvpn vtun10 hash 'sha512' + set interfaces openvpn vtun10 mode 'client' + set interfaces openvpn vtun10 persistent-tunnel + set interfaces openvpn vtun10 protocol 'udp' + set interfaces openvpn vtun10 remote-host '172.18.201.10' + set interfaces openvpn vtun10 remote-port '1194' + set interfaces openvpn vtun10 tls ca-cert-file '/config/auth/ca.crt' + set interfaces openvpn vtun10 tls cert-file '/config/auth/client1.crt' + set interfaces openvpn vtun10 tls key-file '/config/auth/client1.key' + set interfaces openvpn vtun10 use-lzo-compression + +Options +======= + +We do not have CLI nodes for every single OpenVPN options. If an option is +missing, a feature request should be opened at Phabricator_ so all users can +benefit from it (see :ref:`issues_features`). + +If you are a hacker or want to try on your own we support passing raw OpenVPN +options to OpenVPN. + +.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option 'persistent-key' + +Will add ``persistent-key`` at the end of the generated OpenVPN configuration. +Please use this only as last resort - things might break and OpenVPN won't start +if you pass invalid options/syntax. + +.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option + 'push "keepalive 1 10"' + +Will add ``push "keepalive 1 10"`` to the generated OpenVPN config file. + +.. note:: Sometimes option lines in the generated OpenVPN configurarion require + quotes. This is done through a hack on our config generator. You can pass + quotes using the ``"`` statement. + + +Troubleshooting +=============== + +VyOS provides some operational commands on OpenVPN. + +Check status +------------ + +The following commands let you check tunnel status. + +.. opcmd:: show openvpn client + + Use this command to check the tunnel status for OpenVPN client interfaces. + +.. opcmd:: show openvpn server + + Use this command to check the tunnel status for OpenVPN server interfaces. + +.. opcmd:: show openvpn site-to-site + + Use this command to check the tunnel status for OpenVPN site-to-site + interfaces. + + +Reset OpenVPN +------------- + +The following commands let you reset OpenVPN. + +.. opcmd:: reset openvpn client <text> + + Use this command to reset specified OpenVPN client. + +.. opcmd:: reset openvpn interface <interface> + + Uset this command to reset the OpenVPN process on a specific interface. + + + +.. include:: /_include/common-references.txt diff --git a/docs/configuration/interfaces/pppoe.rst b/docs/configuration/interfaces/pppoe.rst new file mode 100644 index 00000000..1bbccc0c --- /dev/null +++ b/docs/configuration/interfaces/pppoe.rst @@ -0,0 +1,317 @@ +.. _pppoe-interface: + +##### +PPPoE +##### + +:abbr:`PPPoE (Point-to-Point Protocol over Ethernet)` is a network protocol +for encapsulating PPP frames inside Ethernet frames. It appeared in 1999, +in the context of the boom of DSL as the solution for tunneling packets +over the DSL connection to the :abbr:`ISPs (Internet Service Providers)` +IP network, and from there to the rest of the Internet. A 2005 networking +book noted that "Most DSL providers use PPPoE, which provides authentication, +encryption, and compression." Typical use of PPPoE involves leveraging the +PPP facilities for authenticating the user with a username and password, +predominately via the PAP protocol and less often via CHAP. + +*************** +Operating Modes +*************** + +VyOS supports setting up PPPoE in two different ways to a PPPoE internet +connection. This is due to most ISPs provide a modem that is also a wireless +router. + +Home Users +========== + +In this method, the DSL Modem/Router connects to the ISP for you with your +credentials preprogrammed into the device. This gives you an :rfc:`1918` +address, such as ``192.168.1.0/24`` by default. + +For a simple home network using just the ISP's equipment, this is usually +desirable. But if you want to run VyOS as your firewall and router, this +will result in having a double NAT and firewall setup. This results in a +few extra layers of complexity, particularly if you use some NAT or +tunnel features. + +Business Users +============== + +In order to have full control and make use of multiple static public IP +addresses, your VyOS will have to initiate the PPPoE connection and control +it. In order for this method to work, you will have to figure out how to make +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. + +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 +(Modem/Router) just acts to translate your messages in a way that +vDSL/aDSL understands. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-description.txt + :var0: pppoe + :var1: pppoe0 + +.. cmdinclude:: /_include/interface-disable.txt + :var0: pppoe + :var1: pppoe0 + +.. cmdinclude:: /_include/interface-vrf.txt + :var0: pppoe + :var1: pppoe0 + +PPPoE options +============= + +.. cfgcmd:: set interfaces pppoe <interface> access-concentrator <name> + + Use this command to restrict the PPPoE session on a given access + concentrator. Normally, a host sends a PPPoE initiation packet to start the + PPPoE discovery process, a number of access concentrators respond with offer + packets and the host selects one of the responding access concentrators to + serve this session. + + This command allows you to select a specific access concentrator when you + know the access concentrators `<name>`. + +.. cfgcmd:: set interfaces pppoe <interface> authentication user <username> + + Use this command to set the username for authenticating with a remote PPPoE + endpoint. Authentication is optional from the system's point of view but + most service providers require it. + +.. cfgcmd:: set interfaces pppoe <interface> authentication password <password> + + Use this command to set the password for authenticating with a remote PPPoE + endpoint. Authentication is optional from the system's point of view but + most service providers require it. + +.. cfgcmd:: set interfaces pppoe <interface> connect-on-demand + + When set the interface is enabled for "dial-on-demand". + + Use this command to instruct the system to establish a PPPoE connections + automatically once traffic passes through the interface. A disabled on-demand + connection is established at boot time and remains up. If the link fails for + any reason, the link is brought back up immediately. + + Enabled on-demand PPPoE connections bring up the link only when traffic needs + to pass this link. If the link fails for any reason, the link is brought + back up automatically once traffic passes the interface again. If you + configure an on-demand PPPoE connection, you must also configure the idle + timeout period, after which an idle PPPoE link will be disconnected. A + non-zero idle timeout will never disconnect the link after it first came up. + +.. cfgcmd:: set interfaces pppoe <interface> default-route [auto | force | none] + + Use this command to specify whether to automatically add a default route + pointing to the endpoint of the PPPoE when the link comes up. The default + route is only added if no other default route already exists in the system. + + **default:** A default route to the remote endpoint is automatically added + when the link comes up (i.e. auto). + + * auto: A default route is added if no other default route (From any + source) already exists. + * force: A default route is added after removing *all* existing default + routes. + * none: No default route is installed. + +.. note:: In all modes except 'none', all default routes using this interface + will be removed when the interface is torn down - even manually installed + static routes. + +.. cfgcmd:: set interfaces pppoe <interface> idle-timeout <time> + + Use this command to set the idle timeout interval to be used with on-demand + PPPoE sessions. When an on-demand connection is established, the link is + brought up only when traffic is sent and is disabled when the link is idle + for the interval specified. + + If this parameter is not set or 0, an on-demand link will not be taken down + when it is idle and after the initial establishment of the connection. It + will stay up forever. + +.. cfgcmd:: set interfaces pppoe <interface> local-address <address> + + Use this command to set the IP address of the local endpoint of a PPPoE + session. If it is not set it will be negotiated. + +.. cfgcmd:: set interfaces pppoe <interface> mtu <mtu> + + Configure :abbr:`MTU (Maximum Transmission Unit)` on given `<interface>`. It + is the size (in bytes) of the largest ethernet frame sent on this link. + +.. cfgcmd:: set interfaces pppoe <interface> no-peer-dns + + Use this command to not install advertised DNS nameservers into the local + system. + +.. cfgcmd:: set interfaces pppoe <interface> remote-address <address> + + Use this command to set the IP address of the remote endpoint of a PPPoE + session. If it is not set it will be negotiated. + +.. cfgcmd:: set interfaces pppoe <interface> service-name <name> + + Use this command to specify a service name by which the local PPPoE interface + can select access concentrators to connect with. It will connect to any + access concentrator if not set. + +.. cfgcmd:: set interfaces pppoe <interface> source-interface <source-interface> + + Use this command to link the PPPoE connection to a physical interface. Each + PPPoE connection must be established over a physical interface. Interfaces + can be regular Ethernet interfaces, VIFs or bonding interfaces/VIFs. + +IPv6 +---- + +.. cfgcmd:: set interfaces pppoe <interface> ipv6 address autoconf + + Use this command to enable acquisition of IPv6 address using stateless + autoconfig (SLAAC). + +.. cmdinclude:: /_include/interface-dhcpv6-prefix-delegation.txt + :var0: pppoe + :var1: pppoe0 + +********* +Operation +********* + +.. opcmd:: show interfaces pppoe <interface> + + Show detailed information on given `<interface>` + + .. code-block:: none + + vyos@vyos:~$ show interfaces pppoe pppoe0 + pppoe0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1492 qdisc pfifo_fast state UNKNOWN group default qlen 3 + link/ppp + inet 192.0.2.1 peer 192.0.2.255/32 scope global pppoe0 + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 7002658233 5064967 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 533822843 1620173 0 0 0 0 + +.. opcmd:: show interfaces pppoe <interface> queue + + Displays queue information for a PPPoE interface. + + .. code-block:: none + + vyos@vyos:~$ show interfaces pppoe pppoe0 queue + qdisc pfifo_fast 0: root refcnt 2 bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 + Sent 534625359 bytes 1626761 pkt (dropped 62, overlimits 0 requeues 0) + backlog 0b 0p requeues 0 + +Connect/Disconnect +================== + +.. opcmd:: disconnect interface <interface> + + Test disconnecting given connection-oriented interface. `<interface>` can be + ``pppoe0`` as example. + +.. opcmd:: connect interface <interface> + + Test connecting given connection-oriented interface. `<interface>` can be + ``pppoe0`` as example. + +******* +Example +******* + +Requirements: + +* Your ISPs modem is connected to port ``eth0`` of your VyOS box. +* No VLAN tagging required by your ISP. +* You need your PPPoE credentials from your DSL ISP in order to configure + this. The usual username is in the form of name@host.net but may vary + depending on ISP. +* The largest MTU size you can use with DSL is 1492 due to PPPoE overhead. + If you are switching from a DHCP based ISP like cable then be aware that + things like VPN links may need to have their MTU sizes adjusted to work + within this limit. +* With the ``default-route`` option set to ``auto``, VyOS will only add the + default gateway you receive from your DSL ISP to the routing table if you + have no other WAN connections. If you wish to use a dual WAN connection, + 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 + have configured statically. + +.. note:: Syntax has changed from VyOS 1.2 (crux) and it will be automatically + migrated during an upgrade. + +.. code-block:: none + + set interfaces pppoe pppoe0 default-route 'auto' + set interfaces pppoe pppoe0 mtu 1492 + set interfaces pppoe pppoe0 authentication user 'userid' + set interfaces pppoe pppoe0 authentication password 'secret' + set interfaces pppoe pppoe0 source-interface 'eth0' + + +You should add a firewall to your configuration above as well by +assigning it to the pppoe0 itself as shown here: + +.. code-block:: none + + set interfaces pppoe pppoe0 firewall in name NET-IN + set interfaces pppoe pppoe0 firewall local name NET-LOCAL + set interfaces pppoe pppoe0 firewall out name NET-OUT + +VLAN Example +============ + +Some recent ISPs require you to build the PPPoE connection through a VLAN +interface. One of those ISPs is e.g. Deutsche Telekom in Germany. VyOS +can easily create a PPPoE session through an encapsulated VLAN interface. +The following configuration will run your PPPoE connection through VLAN7 +which is the default VLAN for Deutsche Telekom: + +.. code-block:: none + + set interfaces pppoe pppoe0 default-route 'auto' + set interfaces pppoe pppoe0 mtu 1492 + set interfaces pppoe pppoe0 authentication user 'userid' + set interfaces pppoe pppoe0 authentication password 'secret' + set interfaces pppoe pppoe0 source-interface 'eth0.7' + + +IPv6 DHCPv6-PD Example +---------------------- + +.. stop_vyoslinter + +The following configuration will assign a /64 prefix out of a /56 delegation +to eth0. The IPv6 address assigned to eth0 will be <prefix>::ffff/64. +If you do not know the prefix size delegated to you, start with sla-len 0. + +.. start_vyoslinter + +.. code-block:: none + + set interfaces pppoe pppoe0 authentication user vyos + set interfaces pppoe pppoe0 authentication password vyos + set interfaces pppoe pppoe0 dhcpv6-options prefix-delegation interface eth0 address 65535 + set interfaces pppoe pppoe0 dhcpv6-options prefix-delegation interface eth0 sla-id 0 + set interfaces pppoe pppoe0 dhcpv6-options prefix-delegation interface eth0 sla-len 8 + set interfaces pppoe pppoe0 ipv6 address autoconf + set interfaces pppoe pppoe0 source-interface eth1 diff --git a/docs/configuration/interfaces/pseudo-ethernet.rst b/docs/configuration/interfaces/pseudo-ethernet.rst new file mode 100644 index 00000000..0471d2e1 --- /dev/null +++ b/docs/configuration/interfaces/pseudo-ethernet.rst @@ -0,0 +1,65 @@ +.. _pseudo-ethernet-interface: + +####################### +Pseudo Ethernet/MACVLAN +####################### + +Pseudo-Ethernet or MACVLAN interfaces can be seen as subinterfaces to regular +ethernet interfaces. Each and every subinterface is created a different media +access control (MAC) address, for a single physical Ethernet port. Pseudo- +Ethernet interfaces have most of their application in virtualized environments, + +By using Pseudo-Ethernet interfaces there will be less system overhead compared +to running a traditional bridging approach. Pseudo-Ethernet interfaces can also +be used to workaround the general limit of 4096 virtual LANs (VLANs) per +physical Ethernet port, since that limit is with respect to a single MAC +address. + +Every Virtual Ethernet interfaces behaves like a real Ethernet interface. They +can have IPv4/IPv6 addresses configured, or can request addresses by DHCP/ +DHCPv6 and are associated/mapped with a real ethernet port. This also makes +Pseudo-Ethernet interfaces interesting for testing purposes. A Pseudo-Ethernet +device will inherit characteristics (speed, duplex, ...) from its physical +parent (the so called link) interface. + +Once created in the system, Pseudo-Ethernet interfaces can be referenced in +the exact same way as other Ethernet interfaces. Notes about using Pseudo- +Ethernet interfaces: + +* Pseudo-Ethernet interfaces can not be reached from your internal host. This + means that you can not try to ping a Pseudo-Ethernet interface from the host + system on which it is defined. The ping will be lost. +* Loopbacks occurs at the IP level the same way as for other interfaces, + ethernet frames are not forwarded between Pseudo-Ethernet interfaces. +* Pseudo-Ethernet interfaces may not work in environments which expect a + :abbr:`NIC (Network Interface Card)` to only have a single address. This + 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 + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: pseudo-ethernet + :var1: peth0 + +Pseudo Ethernet/MACVLAN options +=============================== + +.. cfgcmd:: set interfaces pseudo-ethernet <interface> source-interface <ethX> + + Specifies the physical `<ethX>` Ethernet interface associated with a Pseudo + Ethernet `<interface>`. + +VLAN +==== + +.. cmdinclude:: /_include/interface-vlan-8021q.txt + :var0: pseudo-ethernet + :var1: peth0 diff --git a/docs/configuration/interfaces/tunnel.rst b/docs/configuration/interfaces/tunnel.rst new file mode 100644 index 00000000..d2d63ce2 --- /dev/null +++ b/docs/configuration/interfaces/tunnel.rst @@ -0,0 +1,265 @@ +.. _tunnel-interface: + +Tunnel +====== + +This article touches on 'classic' IP tunneling protocols. + +GRE is often seen as a one size fits all solution when it comes to classic IP +tunneling protocols, and for a good reason. However, there are more specialized +options, and many of them are supported by VyOS. There are also rather obscure +GRE options that can be useful. + +All those protocols are grouped under ``interfaces tunnel`` in VyOS. Let's take +a closer look at the protocols and options currently supported by VyOS. + +Common interface configuration +------------------------------ + +.. cmdinclude:: /_include/interface-common-without-dhcp.txt + :var0: tunnel + :var1: tun0 + +IPIP +---- + +This is one of the simplest types of tunnels, as defined by :rfc:`2003`. +It takes an IPv4 packet and sends it as a payload of another IPv4 packet. For +this reason, there are no other configuration options for this kind of tunnel. + +An example: + +.. code-block:: none + + set interfaces tunnel tun0 encapsulation ipip + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 203.0.113.20 + set interfaces tunnel tun0 address 192.168.100.200/24 + +IP6IP6 +------ + +This is the IPv6 counterpart of IPIP. I'm not aware of an RFC that defines this +encapsulation specifically, but it's a natural specific case of IPv6 +encapsulation mechanisms described in :rfc:2473`. + +It's not likely that anyone will need it any time soon, but it does exist. + +An example: + +.. code-block:: none + + set interfaces tunnel tun0 encapsulation ip6ip6 + set interfaces tunnel tun0 local-ip 2001:db8:aa::1 + set interfaces tunnel tun0 remote-ip 2001:db8:aa::2 + set interfaces tunnel tun0 address 2001:db8:bb::1/64 + +IPIP6 +----- + +In the future this is expected to be a very useful protocol (though there are +`other proposals`_). + +As the name implies, it's IPv4 encapsulated in IPv6, as simple as that. + +An example: + +.. code-block:: none + + set interfaces tunnel tun0 encapsulation ipip6 + set interfaces tunnel tun0 local-ip 2001:db8:aa::1 + set interfaces tunnel tun0 remote-ip 2001:db8:aa::2 + set interfaces tunnel tun0 address 192.168.70.80/24 + +6in4 (SIT) +---------- + +6in4 uses tunneling to encapsulate IPv6 traffic over IPv4 links as defined in +:rfc:`4213`. The 6in4 traffic is sent over IPv4 inside IPv4 packets whose IP +headers have the IP protocol number set to 41. This protocol number is +specifically designated for IPv6 encapsulation, the IPv4 packet header is +immediately followed by the IPv6 packet being carried. The encapsulation +overhead is the size of the IPv4 header of 20 bytes, therefore with an MTU of +1500 bytes, IPv6 packets of 1480 bytes can be sent without fragmentation. This +tunneling technique is frequently used by IPv6 tunnel brokers like `Hurricane +Electric`_. + +An example: + +.. code-block:: none + + set interfaces tunnel tun0 encapsulation sit + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 192.0.2.20 + set interfaces tunnel tun0 address 2001:db8:bb::1/64 + +A full example of a Tunnelbroker.net config can be found at +:ref:`here <examples-tunnelbroker-ipv6>`. + +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 +multiple protocols inside the same tunnel. GRE also supports multicast traffic +and supports routing protocols that leverage multicast to form neighbor +adjacencies. + +A VyOS GRE tunnel can carry both IPv4 and IPv6 traffic and can also be created +over either IPv4 (gre) or IPv6 (ip6gre). + + +Configuration +^^^^^^^^^^^^^ + +A basic configuration requires a tunnel source (local-ip), a tunnel destination +(remote-ip), 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:** + +.. code-block:: none + + set interfaces tunnel tun100 address '10.0.0.1/30' + set interfaces tunnel tun100 encapsulation 'gre' + set interfaces tunnel tun100 local-ip '198.51.100.2' + set interfaces tunnel tun100 remote-ip '203.0.113.10' + +**Cisco IOS Router:** + +.. code-block:: none + + interface Tunnel100 + ip address 10.0.0.2 255.255.255.252 + tunnel source 203.0.113.10 + tunnel destination 198.51.100.2 + +Here is a second example of a dual-stack tunnel over IPv6 between a VyOS router +and a Linux host using systemd-networkd. + +**VyOS Router:** + +.. code-block:: none + + set interfaces tunnel tun101 address '2001:db8:feed:beef::1/126' + set interfaces tunnel tun101 address '192.168.5.1/30' + set interfaces tunnel tun101 encapsulation 'ip6gre' + set interfaces tunnel tun101 local-ip '2001:db8:babe:face::3afe:3' + set interfaces tunnel tun101 remote-ip '2001:db8:9bb:3ce::5' + +**Linux systemd-networkd:** + +This requires two files, one to create the device (XXX.netdev) and one +to configure the network on the device (XXX.network) + +.. code-block:: none + + # cat /etc/systemd/network/gre-example.netdev + [NetDev] + Name=gre-example + Kind=ip6gre + MTUBytes=14180 + + [Tunnel] + Remote=2001:db8:babe:face::3afe:3 + + + # cat /etc/systemd/network/gre-example.network + [Match] + Name=gre-example + + [Network] + Address=2001:db8:feed:beef::2/126 + + [Address] + Address=192.168.5.2/30 + +Tunnel keys +^^^^^^^^^^^ + +GRE is also the only classic protocol that allows creating multiple tunnels +with the same source and destination due to its support for tunnel keys. +Despite its name, this feature has nothing to do with security: it's simply +an identifier that allows routers to tell one tunnel from another. + +An example: + +.. code-block:: none + + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 192.0.2.20 + set interfaces tunnel tun0 address 10.40.50.60/24 + set interfaces tunnel tun0 parameters ip key 10 + +.. code-block:: none + + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 192.0.2.20 + set interfaces tunnel tun0 address 172.16.17.18/24 + set interfaces tunnel tun0 parameters ip key 20 + + +Troubleshooting +^^^^^^^^^^^^^^^ + +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. + +**1. Confirm IP connectivity between tunnel local-ip and remote-ip:** + +.. code-block:: none + + vyos@vyos:~$ ping 203.0.113.10 interface 198.51.100.2 count 4 + PING 203.0.113.10 (203.0.113.10) from 198.51.100.2 : 56(84) bytes of data. + 64 bytes from 203.0.113.10: icmp_seq=1 ttl=254 time=0.807 ms + 64 bytes from 203.0.113.10: icmp_seq=2 ttl=254 time=1.50 ms + 64 bytes from 203.0.113.10: icmp_seq=3 ttl=254 time=0.624 ms + 64 bytes from 203.0.113.10: icmp_seq=4 ttl=254 time=1.41 ms + + --- 203.0.113.10 ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3007ms + rtt min/avg/max/mdev = 0.624/1.087/1.509/0.381 ms + +**2. Confirm the link type has been set to GRE:** + +.. code-block:: none + + vyos@vyos:~$ show interfaces tunnel tun100 + tun100@NONE: <POINTOPOINT,NOARP,UP,LOWER_UP> mtu 1476 qdisc noqueue state UNKNOWN group default qlen 1000 + link/gre 198.51.100.2 peer 203.0.113.10 + inet 10.0.0.1/30 brd 10.0.0.3 scope global tun100 + valid_lft forever preferred_lft forever + inet6 fe80::5efe:c612:2/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 2183 27 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 836 9 0 0 0 0 + +**3. Confirm IP connectivity across the tunnel:** + +.. code-block:: none + + vyos@vyos:~$ ping 10.0.0.2 interface 10.0.0.1 count 4 + PING 10.0.0.2 (10.0.0.2) from 10.0.0.1 : 56(84) bytes of data. + 64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=1.05 ms + 64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=1.88 ms + 64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=1.98 ms + 64 bytes from 10.0.0.2: icmp_seq=4 ttl=255 time=1.98 ms + + --- 10.0.0.2 ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3008ms + rtt min/avg/max/mdev = 1.055/1.729/1.989/0.395 ms + +.. note:: There is also a GRE over IPv6 encapsulation available, it is + called: ``ip6gre``. + +.. _`other proposals`: https://www.isc.org/othersoftware/ +.. _`Hurricane Electric`: https://tunnelbroker.net/ diff --git a/docs/configuration/interfaces/vti.rst b/docs/configuration/interfaces/vti.rst new file mode 100644 index 00000000..62cd13f3 --- /dev/null +++ b/docs/configuration/interfaces/vti.rst @@ -0,0 +1,22 @@ +############################## +Virtual Tunnel Interface (VTI) +############################## + + +Set Virtual Tunnel Interface + +.. code-block:: none + + set interfaces vti vti0 address 192.168.2.249/30 + set interfaces vti vti0 address 2001:db8:2::249/64 + +Results in: + +.. code-block:: none + + vyos@vyos# show interfaces vti + vti vti0 { + address 192.168.2.249/30 + address 2001:db8:2::249/64 + description "Description" + }
\ No newline at end of file diff --git a/docs/configuration/interfaces/vxlan.rst b/docs/configuration/interfaces/vxlan.rst new file mode 100644 index 00000000..ca25d21e --- /dev/null +++ b/docs/configuration/interfaces/vxlan.rst @@ -0,0 +1,295 @@ +.. _vxlan-interface: + +##### +VXLAN +##### + +:abbr:`VXLAN (Virtual Extensible LAN)` is a network virtualization technology +that attempts to address the scalability problems associated with large cloud +computing deployments. It uses a VLAN-like encapsulation technique to +encapsulate OSI layer 2 Ethernet frames within layer 4 UDP datagrams, using +4789 as the default IANA-assigned destination UDP port number. VXLAN +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 +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. + +The VXLAN specification was originally created by VMware, Arista Networks +and Cisco. Other backers of the VXLAN technology include Huawei, Broadcom, +Citrix, Pica8, Big Switch Networks, Cumulus Networks, Dell EMC, Ericsson, +Mellanox, FreeBSD, OpenBSD, Red Hat, Joyent, and Juniper Networks. + +VXLAN was officially documented by the IETF in :rfc:`7348`. + +If configuring VXLAN in a VyOS virtual machine, ensure that MAC spoofing +(Hyper-V) or Forged Transmits (ESX) are permitted, otherwise forwarded frames +may be blocked by the hypervisor. + +.. note:: As VyOS is based on Linux and there was no official IANA port assigned + for VXLAN, VyOS uses a default port of 8472. You can change the port on a + per VXLAN interface basis to get it working across multiple vendors. + +Configuration +============= + +Common interface configuration +------------------------------ + +.. cmdinclude:: /_include/interface-common-without-dhcp.txt + :var0: vxlan + :var1: vxlan0 + +VXLAN specific options +----------------------- + +.. cfgcmd:: set interfaces vxlan <interface> vni <number> + + Each VXLAN segment is identified through a 24-bit segment ID, termed the + :abbr:`VNI (VXLAN Network Identifier (or VXLAN Segment ID))`, This allows + up to 16M VXLAN segments to coexist within the same administrative domain. + +.. cfgcmd:: set interfaces vxlan <interface> port <port> + + Configure port number of remote VXLAN endpoint. + + .. note:: As VyOS is Linux based the default port used is not using 4789 + as the default IANA-assigned destination UDP port number. Instead VyOS + uses the Linux default port of 8472. + +.. cfgcmd:: set interfaces vxlan <interface> source-address <interface> + + Source IP address used for VXLAN underlay. This is mandatory when using VXLAN + via L2VPN/EVPN. + +Unicast +^^^^^^^ + +.. cfgcmd:: set interfaces vxlan <interface> remote <address> + + IPv4/IPv6 remote address of the VXLAN tunnel. Alternative to multicast, the + remote IPv4/IPv6 address can set directly. + +Multicast +^^^^^^^^^ + +.. cfgcmd:: set interfaces vxlan <interface> source-interface <interface> + + Interface used for VXLAN underlay. This is mandatory when using VXLAN via + a multicast network. VXLAN traffic will always enter and exit this interface. + + +.. cfgcmd:: set interfaces vxlan <interface> group <address> + + Multicast group address for VXLAN interface. VXLAN tunnels can be built + either via Multicast or via Unicast. + + Both IPv4 and IPv6 multicast is possible. + +Multicast VXLAN +=============== + +Topology: PC4 - Leaf2 - Spine1 - Leaf3 - PC5 + +PC4 has IP 10.0.0.4/24 and PC5 has IP 10.0.0.5/24, so they believe they are in +the same broadcast domain. + +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 +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. + +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 +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 +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 +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 +support this. + +Example +------- + +The setup is this: Leaf2 - Spine1 - Leaf3 + +Spine1 is a Cisco IOS router running version 15.4, Leaf2 and Leaf3 is each a +VyOS router running 1.2. + +This topology was built using GNS3. + +Topology: + +.. code-block:: none + + Spine1: + fa0/2 towards Leaf2, IP-address: 10.1.2.1/24 + fa0/3 towards Leaf3, IP-address: 10.1.3.1/24 + + Leaf2: + Eth0 towards Spine1, IP-address: 10.1.2.2/24 + Eth1 towards a vlan-aware switch + + Leaf3: + Eth0 towards Spine1, IP-address 10.1.3.3/24 + Eth1 towards a vlan-aware switch + +**Spine1 Configuration:** + +.. code-block:: none + + conf t + ip multicast-routing + ! + interface fastethernet0/2 + ip address 10.1.2.1 255.255.255.0 + ip pim sparse-dense-mode + ! + interface fastethernet0/3 + ip address 10.1.3.1 255.255.255.0 + ip pim sparse-dense-mode + ! + 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 +other in a more scalable way. This also requires PIM to be enabled towards the +Leafs so that the Spine can learn what multicast groups each Leaf expect +traffic from. + +**Leaf2 configuration:** + +.. code-block:: none + + set interfaces ethernet eth0 address '10.1.2.2/24' + set protocols ospf area 0 network '10.0.0.0/8' + + ! Our first vxlan interface + set interfaces bridge br241 address '172.16.241.1/24' + set interfaces bridge br241 member interface 'eth1.241' + set interfaces bridge br241 member interface 'vxlan241' + + set interfaces vxlan vxlan241 group '239.0.0.241' + set interfaces vxlan vxlan241 source-interface 'eth0' + set interfaces vxlan vxlan241 vni '241' + + ! Our seconds vxlan interface + set interfaces bridge br242 address '172.16.242.1/24' + set interfaces bridge br242 member interface 'eth1.242' + set interfaces bridge br242 member interface 'vxlan242' + + set interfaces vxlan vxlan242 group '239.0.0.242' + set interfaces vxlan vxlan242 source-interface 'eth0' + set interfaces vxlan vxlan242 vni '242' + +**Leaf3 configuration:** + +.. code-block:: none + + set interfaces ethernet eth0 address '10.1.3.3/24' + set protocols ospf area 0 network '10.0.0.0/8' + + ! Our first vxlan interface + set interfaces bridge br241 address '172.16.241.1/24' + set interfaces bridge br241 member interface 'eth1.241' + set interfaces bridge br241 member interface 'vxlan241' + + set interfaces vxlan vxlan241 group '239.0.0.241' + set interfaces vxlan vxlan241 source-interface 'eth0' + set interfaces vxlan vxlan241 vni '241' + + ! Our seconds vxlan interface + set interfaces bridge br242 address '172.16.242.1/24' + set interfaces bridge br242 member interface 'eth1.242' + set interfaces bridge br242 member interface 'vxlan242' + + set interfaces vxlan vxlan242 group '239.0.0.242' + set interfaces vxlan vxlan242 source-interface 'eth0' + set interfaces vxlan vxlan242 vni '242' + +As you can see, Leaf2 and Leaf3 configuration is almost identical. There are +lots of commands above, I'll try to into more detail below, command +descriptions are placed under the command boxes: + +.. code-block:: none + + 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 +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 +OSPF network from '10.0.0.0/8' to '0.0.0.0/0' to allow 172.16/12-networks to be +advertised. + +.. code-block:: none + + set interfaces bridge br241 member interface 'eth1.241' + set interfaces bridge br241 member interface 'vxlan241' + +Binds eth1.241 and vxlan241 to each other by making them both member +interfaces of the same bridge. + +.. code-block:: none + + 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. + +.. code-block:: none + + set interfaces vxlan vxlan241 source-interface 'eth0' + +Sets the interface to listen for multicast packets on. Could be a loopback, not +yet tested. + +.. code-block:: none + + set interfaces vxlan vxlan241 vni '241' + +Sets the unique id for this vxlan-interface. Not sure how it correlates with +multicast-address. + +.. code-block:: none + + 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 +configuration directive to support a user-specified destination port to override +that behavior is available using the above command. + +Unicast VXLAN +============= + +Alternative to multicast, the remote IPv4 address of the VXLAN tunnel can be +set directly. Let's change the Multicast example from above: + +.. code-block:: none + + # leaf2 and leaf3 + delete interfaces vxlan vxlan241 group '239.0.0.241' + delete interfaces vxlan vxlan241 source-interface 'eth0' + + # leaf2 + set interface vxlan vxlan241 remote 10.1.3.3 + + # leaf3 + set interface vxlan vxlan241 remote 10.1.2.2 + +The default port udp is set to 8472. +It can be changed with ``set interface vxlan <vxlanN> port <port>`` diff --git a/docs/configuration/interfaces/wireguard.rst b/docs/configuration/interfaces/wireguard.rst new file mode 100644 index 00000000..852ff520 --- /dev/null +++ b/docs/configuration/interfaces/wireguard.rst @@ -0,0 +1,269 @@ +.. _wireguard: + +######### +WireGuard +######### + +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. + +Configuration +============= + +WireGuard requires the generation of a keypair, a private key which will +decrypt incoming traffic and a public key, which the peer(s) will use to +encrypt traffic. + +Generate keypair +---------------- + +.. opcmd:: generate wireguard default-keypair + + It generates the keypair, that is its public and private part and stores + it within VyOS. It will be used per default on any configured WireGuard + interface, even if multiple interfaces are being configured. + +.. opcmd:: show wireguard keypairs pubkey default + + It shows the public key which needs to be shared with your peer(s). Your + peer will encrypt all traffic to your system using this public key. + + .. code-block:: none + + vyos@vyos:~$ show wireguard keypairs pubkey default + hW17UxY7zeydJNPIyo3UtGnBHkzTK/NeBOrDSIU9Tx0= + + +Generate named keypair +---------------------- + +Named keypairs can be used on a interface basis, if configured. If +multiple WireGuard interfaces are being configured, each can have their +own keypairs. + +The commands below will generate 2 keypairs, which are not related to +each other. + +.. code-block:: none + + vyos@vyos:~$ generate wireguard named-keypairs KP01 + 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, +the listen port and address/port is optional, if you however act as a server +and endpoints initiate the connections to your system, you need to +define a port your clients can connect to, otherwise it's randomly +chosen and may make it difficult with firewall rules, since the port may +be a different one when you reboot your system. + +You will also need the public key of your peer as well as the network(s) +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** + +.. code-block:: none + + set interfaces wireguard wg01 address '10.1.0.1/24' + 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 pubkey 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=' + set interfaces wireguard wg01 port '12345' + set protocols static route 10.2.0.0/24 interface wg01 + +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 +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 + check the `WireGuard mailing list`_. + + +To use a named key on an interface, the option private-key needs to be +set. + +.. code-block:: none + + set interfaces wireguard wg01 private-key KP01 + set interfaces wireguard wg02 private-key KP02 + +The command ``run show wireguard keypairs pubkey KP01`` will then show +the public key, which needs to be shared with the peer. + + +**remote side** + +.. code-block:: none + + set interfaces wireguard wg01 address '10.2.0.1/24' + 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 pubkey 'u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk=' + set interfaces wireguard wg01 port '12345' + set protocols static route 10.1.0.0/24 interface wg01 + +Assure that your firewall rules allow the traffic, in which case you +have a working VPN using WireGuard + +.. 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 + + 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 + +An additional layer of symmetric-key crypto can be used on top of the +asymmetric crypto, which is optional. + +.. code-block:: none + + wg01# run generate wireguard preshared-key + rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc= + +Copy the key, as it is not stored on the local file system. Make sure +you distribute that key in a safe manner, it's a symmetric key, so only +you and your peer should have knowledge of its content. + +.. code-block:: none + + 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 +-------------------- + +With WireGuard, a Road Warrior VPN config is similar to a site-to-site +VPN. It just lacks the ``address`` and ``port`` statements. + +In the following example, the IPs for the remote clients are defined in +the peers. This would allow the peers to interact with one another. + +.. code-block:: none + + wireguard wg0 { + address 10.172.24.1/24 + address 2001:DB8:470:22::1/64 + description RoadWarrior + peer MacBook { + allowed-ips 10.172.24.30/32 + allowed-ips 2001:DB8:470:22::30/128 + persistent-keepalive 15 + pubkey F5MbW7ye7DsoxdOaixjdrudshjjxN5UdNV+pGFHqehc= + } + peer iPhone { + allowed-ips 10.172.24.20/32 + allowed-ips 2001:DB8:470:22::30/128 + persistent-keepalive 15 + pubkey BknHcLFo8nOo8Dwq2CjaC/TedchKQ0ebxC7GYn7Al00= + } + port 2224 + } + +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 +through the connection. + +.. code-block:: none + + [Interface] + PrivateKey = ARAKLSDJsadlkfjasdfiowqeruriowqeuasdf= + Address = 10.172.24.20/24, 2001:DB8:470:22::20/64 + DNS = 10.0.0.53, 10.0.0.54 + + [Peer] + PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= + AllowedIPs = 0.0.0.0/0, ::/0 + 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. + +.. code-block:: none + + [Interface] + PrivateKey = 8Iasdfweirousd1EVGUk5XsT+wYFZ9mhPnQhmjzaJE6Go= + Address = 10.172.24.30/24, 2001:DB8:470:22::30/64 + + [Peer] + PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= + AllowedIPs = 10.172.24.30/24, 2001:DB8:470:22::/64 + Endpoint = 192.0.2.1:2224 + PersistentKeepalive = 25 + + +Operational commands +==================== + +**Show interface status** + +.. code-block:: none + + vyos@wg01# run show interfaces wireguard wg01 + interface: wg1 + description: VPN-to-wg01 + address: 10.2.0.1/24 + public key: RIbtUTCfgzNjnLNPQ/asldkfjhaERDFl2H/xUfbyjc= + private key: (hidden) + listening port: 53665 + peer: to-wg02 + public key: u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk= + latest handshake: 0:01:20 + status: active + endpoint: 192.168.0.124:12345 + allowed ips: 10.2.0.0/24 + transfer: 42 GB received, 487 MB sent + persistent keepalive: every 15 seconds + RX: + bytes packets errors dropped overrun mcast + 45252407916 31192260 0 244493 0 0 + TX: + bytes packets errors dropped carrier collisions + 511649780 5129601 24465 0 0 0 + +**Show public key of the default key** + +.. code-block:: none + + vyos@wg01# run show wireguard keypair pubkey default + FAXCPb6EbTlSH5200J5zTopt9AYXneBthAySPBLbZwM= + +**Show public key of a named key** + +.. code-block:: none + + vyos@wg01# run show wireguard keypair pubkey KP01 + HUtsu198toEnm1poGoRTyqkUKfKUdyh54f45dtcahDM= + + +**Delete wireguard keypairs** + +.. code-block:: none + + vyos@wg01# wireguard keypair default + + +.. stop_vyoslinter + +.. _`WireGuard mailing list`: https://lists.zx2c4.com/pipermail/wireguard/2018-December/003704.html + +.. start_vyoslinter
\ No newline at end of file diff --git a/docs/configuration/interfaces/wireless.rst b/docs/configuration/interfaces/wireless.rst new file mode 100644 index 00000000..097d7c49 --- /dev/null +++ b/docs/configuration/interfaces/wireless.rst @@ -0,0 +1,590 @@ +.. _wireless-interface: + +################### +Wireless LAN (WiFi) +################### + +:abbr:`WLAN (Wireless LAN)` interface provide 802.11 (a/b/g/n/ac) wireless +support (commonly referred to as Wi-Fi) by means of compatible hardware. If your +hardware supports it, VyOS supports multiple logical wireless interfaces per +physical device. + +There are three modes of operation for a wireless interface: + +* :abbr:`WAP (Wireless Access-Point)` provides network access to connecting + stations if the physical hardware supports acting as a WAP + +* A station acts as a Wi-Fi client accessing the network through an available + WAP + +* Monitor, the system passively monitors any kind of wireless traffic + +If the system detects an unconfigured wireless device, it will be automatically +added the configuration tree, specifying any detected settings (for example, +its MAC address) and configured to run in monitor mode. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-common-with-dhcp.txt + :var0: wireless + :var1: wlan0 + +Wireless options +================ + +.. cfgcmd:: set interfaces wireless <interface> channel <number> + + Channel number (IEEE 802.11), for 2.4Ghz (802.11 b/g/n) channels range from + 1-14. On 5Ghz (802.11 a/h/j/n/ac) channels available are 0, 34 to 173 + +.. cfgcmd:: set interfaces wireless <interface> country-code <cc> + + Country code (ISO/IEC 3166-1). Used to set regulatory domain. Set as needed + to indicate country in which device is operating. This can limit available + channels and transmit power. + + .. note:: This option is mandatory in Access-Point mode. + +.. cfgcmd:: set interfaces wireless <interface> disable-broadcast-ssid + + Send empty SSID in beacons and ignore probe request frames that do not specify + full SSID, i.e., require stations to know SSID. + +.. cfgcmd:: set interfaces wireless <interface> expunge-failing-stations + + Disassociate stations based on excessive transmission failures or other + indications of connection loss. + + This depends on the driver capabilities and may not be available with all + drivers. + +.. cfgcmd:: set interfaces wireless <interface> isolate-stations + + Client isolation can be used to prevent low-level bridging of frames between + associated stations in the BSS. + + By default, this bridging is allowed. + +.. cfgcmd:: set interfaces wireless <interface> max-stations + + Maximum number of stations allowed in station table. New stations will be + rejected after the station table is full. IEEE 802.11 has a limit of 2007 + different association IDs, so this number should not be larger than that. + + This defaults to 2007. + +.. cfgcmd:: set interfaces wireless <interface> mgmt-frame-protection + + Management Frame Protection (MFP) according to IEEE 802.11w + +.. cfgcmd:: set interfaces wireless <interface> mode <a | b | g | n | ac> + + Operation mode of wireless radio. + + * ``a`` - 802.11a - 54 Mbits/sec + * ``b`` - 802.11b - 11 Mbits/sec + * ``g`` - 802.11g - 54 Mbits/sec (default) + * ``n`` - 802.11n - 600 Mbits/sec + * ``ac`` - 802.11ac - 1300 Mbits/sec + +.. cfgcmd:: set interfaces wireless <interface> physical-device <device> + + Wireless hardware device used as underlay radio. + + This defaults to phy0. + +.. cfgcmd:: set interfaces wireless <interface> reduce-transmit-power <number> + + Add Power Constraint element to Beacon and Probe Response frames. + + This option adds Power Constraint element when applicable and Country element + is added. Power Constraint element is required by Transmit Power Control. + + Valid values are 0..255. + +.. cfgcmd:: set interfaces wireless <interface> ssid <ssid> + + SSID to be used in IEEE 802.11 management frames + +.. cfgcmd:: set interfaces wireless <interface> type + <access-point | station | monitor> + + Wireless device type for this interface + + * ``access-point`` - Access-point forwards packets between other nodes + * ``station`` - Connects to another access point + * ``monitor`` - Passively monitor all packets on the frequency/channel + +PPDU +---- + +.. cfgcmd:: set interfaces wireless <interface> capabilities require-ht + +.. cfgcmd:: set interfaces wireless <interface> capabilities require-hvt + +HT (High Throughput) capabilities (802.11n) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht 40mhz-incapable + + Device is incapable of 40 MHz, do not advertise. This sets ``[40-INTOLERANT]`` + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht auto-powersave + + WMM-PS Unscheduled Automatic Power Save Delivery [U-APSD] + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht + channel-set-width <ht20 | ht40+ | ht40-> + + Supported channel width set. + + * ``ht40-`` - Both 20 MHz and 40 MHz with secondary channel below the primary + channel + * ``ht40+`` - Both 20 MHz and 40 MHz with secondary channel above the primary + channel + + .. note:: There are limits on which channels can be used with HT40- and HT40+. + Following table shows the channels that may be available for HT40- and HT40+ + use per IEEE 802.11n Annex J: + + Depending on the location, not all of these channels may be available for + use! + + .. code-block:: none + + freq HT40- HT40+ + 2.4 GHz 5-13 1-7 (1-9 in Europe/Japan) + 5 GHz 40,48,56,64 36,44,52,60 + + .. note:: 40 MHz channels may switch their primary and secondary channels if + needed or creation of 40 MHz channel maybe rejected based on overlapping + BSSes. These changes are done automatically when hostapd is setting up the + 40 MHz channel. + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht + delayed-block-ack + + Enable HT-delayed Block Ack ``[DELAYED-BA]`` + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht dsss-cck-40 + + DSSS/CCK Mode in 40 MHz, this sets ``[DSSS_CCK-40]`` + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht greenfield + + This enables the greenfield option which sets the ``[GF]`` option + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht ldpc + + Enable LDPC coding capability + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht lsig-protection + + Enable L-SIG TXOP protection capability + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht max-amsdu + <3839 | 7935> + + Maximum A-MSDU length 3839 (default) or 7935 octets + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht + short-gi <20 | 40> + + Short GI capabilities for 20 and 40 MHz + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht + smps <static | dynamic> + + Spatial Multiplexing Power Save (SMPS) settings + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc rx <num> + + Enable receiving PPDU using STBC (Space Time Block Coding) + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc tx + + Enable sending PPDU using STBC (Space Time Block Coding) + +VHT (Very High Throughput) capabilities (802.11ac) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht antenna-count + + Number of antennas on this card + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + antenna-pattern-fixed + + Set if antenna pattern does not change during the lifetime of an association + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht beamform + <single-user-beamformer | single-user-beamformee | multi-user-beamformer | + multi-user-beamformee> + + Beamforming capabilities: + + * ``single-user-beamformer`` - Support for operation as single user beamformer + * ``single-user-beamformee`` - Support for operation as single user beamformee + * ``multi-user-beamformer`` - Support for operation as single user beamformer + * ``multi-user-beamformee`` - Support for operation as single user beamformer + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + center-channel-freq <freq-1 | freq-2> <number> + + VHT operating channel center frequency - center freq 1 + (for use with 80, 80+80 and 160 modes) + + VHT operating channel center frequency - center freq 2 + (for use with the 80+80 mode) + + <number> must be from 34 - 173. For 80 MHz channels it should be channel + 6. + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + channel-set-width <0 | 1 | 2 | 3> + + * ``0`` - 20 or 40 MHz channel width (default) + * ``1`` - 80 MHz channel width + * ``2`` - 160 MHz channel width + * ``3`` - 80+80 MHz channel width + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht ldpc + + Enable LDPC (Low Density Parity Check) coding capability + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht link-adaptation + + VHT link adaptation capabilities + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + max-mpdu <value> + + Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets) + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + max-mpdu-exp <value> + + Set the maximum length of A-MPDU pre-EOF padding that the station can receive + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht + short-gi <80 | 160> + + Short GI capabilities + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc rx <num> + + Enable receiving PPDU using STBC (Space Time Block Coding) + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc tx + + Enable sending PPDU using STBC (Space Time Block Coding) + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht tx-powersave + + Enable VHT TXOP Power Save Mode + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht vht-cf + + Station supports receiving VHT variant HT Control field + +Wireless options (Station/Client) +================================= + +The example creates a wireless station (commonly referred to as Wi-Fi client) +that accesses the network through the WAP defined in the above example. The +default physical device (``phy0``) is used. + +.. code-block:: none + + set interfaces wireless wlan0 type station + set interfaces wireless wlan0 address dhcp + set interfaces wireless wlan0 ssid Test + set interfaces wireless wlan0 security wpa + +Resulting in + +.. code-block:: none + + interfaces { + [...] + wireless wlan0 { + address dhcp + security { + wpa { + passphrase "12345678" + } + } + ssid TEST + type station + } + +Security +======== + +:abbr:`WPA (Wi-Fi Protected Access)` and WPA2 Enterprise in combination with +802.1x based authentication can be used to authenticate users or computers +in a domain. + +The wireless client (supplicant) authenticates against the RADIUS server +(authentication server) using an :abbr:`EAP (Extensible Authentication +Protocol)` method configured on the RADIUS server. The WAP (also referred +to as authenticator) role is to send all authentication messages between the +supplicant and the configured authentication server, thus the RADIUS server +is responsible for authenticating the users. + +The WAP in this example has the following characteristics: + +* IP address ``192.168.2.1/24`` +* Network ID (SSID) ``Enterprise-TEST`` +* WPA passphrase ``12345678`` +* Use 802.11n protocol +* Wireless channel ``1`` +* RADIUS server at ``192.168.3.10`` with shared-secret ``VyOSPassword`` + +.. code-block:: none + + set interfaces wireless wlan0 address '192.168.2.1/24' + set interfaces wireless wlan0 type access-point + set interfaces wireless wlan0 channel 1 + set interfaces wireless wlan0 mode n + set interfaces wireless wlan0 ssid 'TEST' + set interfaces wireless wlan0 security wpa mode wpa2 + set interfaces wireless wlan0 security wpa cipher CCMP + set interfaces wireless wlan0 security wpa radius server 192.168.3.10 key 'VyOSPassword' + set interfaces wireless wlan0 security wpa radius server 192.168.3.10 port 1812 + +Resulting in + +.. code-block:: none + + interfaces { + [...] + wireless wlan0 { + address 192.168.2.1/24 + channel 1 + mode n + security { + wpa { + cipher CCMP + mode wpa2 + radius { + server 192.168.3.10 { + key 'VyOSPassword' + port 1812 + } + } + } + } + ssid "Enterprise-TEST" + type access-point + } + } + system { + [...] + wifi-regulatory-domain DE + } + + +VLAN +==== + +Regular VLANs (802.1q) +---------------------- + +.. cmdinclude:: /_include/interface-vlan-8021q.txt + :var0: wireless + :var1: wlan0 + +QinQ (802.1ad) +-------------- + +.. cmdinclude:: /_include/interface-vlan-8021ad.txt + :var0: wireless + :var1: wlan0 + +********* +Operation +********* + +.. opcmd:: show interfaces wireless info + +Use this command to view operational status and wireless-specific information +about all wireless interfaces. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless info + Interface Type SSID Channel + wlan0 access-point VyOS-TEST-0 1 + +.. opcmd:: show interfaces wireless detail + +Use this command to view operational status and detailes wireless-specific +information about all wireless interfaces. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless detail + wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.99.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 66072 282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 83413 430 0 0 0 0 + + wlan1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.100.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:ffff:2ed3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 166072 5282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 183413 5430 0 0 0 0 + +.. opcmd:: show interfaces wireless <wlanX> + +This command shows both status and statistics on the specified wireless +interface. The wireless interface identifier can range from wlan0 to wlan999. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless wlan0 + wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.99.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 66072 282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 83413 430 0 0 0 0 + + +.. opcmd:: show interfaces wireless <wlanX> brief + +This command gives a brief status overview of a specified wireless interface. +The wireless interface identifier can range from wlan0 to wlan999. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless wlan0 brief + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + wlan0 192.168.2.254/24 u/u + + +.. opcmd:: show interfaces wireless <wlanX> queue + +Use this command to view wireless interface queue information. +The wireless interface identifier can range from wlan0 to wlan999. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless wlan0 queue + qdisc pfifo_fast 0: root bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 + Sent 810323 bytes 6016 pkt (dropped 0, overlimits 0 requeues 0) + rate 0bit 0pps backlog 0b 0p requeues 0 + + +.. opcmd:: show interfaces wireless <wlanX> scan + +This command is used to retrieve information about WAP within the range of your +wireless interface. This command is useful on wireless interfaces configured +in station mode. + +.. note:: Scanning is not supported on all wireless drivers and wireless + hardware. Refer to your driver and wireless hardware documentation for + further details. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless wlan0 scan + Address SSID Channel Signal (dbm) + 00:53:3b:88:6e:d8 WLAN-576405 1 -64.00 + 00:53:3b:88:6e:da Telekom_FON 1 -64.00 + 00:53:00:f2:c2:a4 BabyView_F2C2A4 6 -60.00 + 00:53:3b:88:6e:d6 Telekom_FON 100 -72.00 + 00:53:3b:88:6e:d4 WLAN-576405 100 -71.00 + 00:53:44:a4:96:ec KabelBox-4DC8 56 -81.00 + 00:53:d9:7a:67:c2 WLAN-741980 1 -75.00 + 00:53:7c:99:ce:76 Vodafone Homespot 1 -86.00 + 00:53:44:a4:97:21 KabelBox-4DC8 1 -78.00 + 00:53:44:a4:97:21 Vodafone Hotspot 1 -79.00 + 00:53:44:a4:97:21 Vodafone Homespot 1 -79.00 + 00:53:86:40:30:da Telekom_FON 1 -86.00 + 00:53:7c:99:ce:76 Vodafone Hotspot 1 -86.00 + 00:53:44:46:d2:0b Vodafone Hotspot 1 -87.00 + + +******** +Examples +******** + +The following example creates a WAP. When configuring multiple WAP interfaces, +you must specify unique IP addresses, channels, Network IDs commonly referred +to as :abbr:`SSID (Service Set Identifier)`, and MAC addresses. + +The WAP in this example has the following characteristics: + +* IP address ``192.168.2.1/24`` +* Network ID (SSID) ``TEST`` +* WPA passphrase ``12345678`` +* Use 802.11n protocol +* Wireless channel ``1`` + +.. code-block:: none + + set interfaces wireless wlan0 address '192.168.2.1/24' + set interfaces wireless wlan0 type access-point + set interfaces wireless wlan0 channel 1 + set interfaces wireless wlan0 mode n + set interfaces wireless wlan0 ssid 'TEST' + set interfaces wireless wlan0 security wpa mode wpa2 + set interfaces wireless wlan0 security wpa cipher CCMP + set interfaces wireless wlan0 security wpa passphrase '12345678' + +Resulting in + +.. code-block:: none + + interfaces { + [...] + wireless wlan0 { + address 192.168.2.1/24 + channel 1 + mode n + security { + wpa { + cipher CCMP + mode wpa2 + passphrase "12345678" + } + } + ssid "TEST" + type access-point + } + } + system { + [...] + wifi-regulatory-domain DE + } + +To get it to work as a access point with this configuration you will need +to set up a DHCP server to work with that network. You can - of course - also +bridge the Wireless interface with any configured bridge +(:ref:`bridge-interface`) on the system. diff --git a/docs/configuration/interfaces/wirelessmodem.rst b/docs/configuration/interfaces/wirelessmodem.rst new file mode 100644 index 00000000..a65a47f4 --- /dev/null +++ b/docs/configuration/interfaces/wirelessmodem.rst @@ -0,0 +1,128 @@ +.. _wwan-interface: + +#################### +WirelessModem (WWAN) +#################### + +The wirelessmodem interface provides access (through a wireless modem/wwan) +to wireless networks provided by various cellular providers. VyOS uses the +interfaces wirelessmodem subsystem for configuration. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-description.txt + :var0: wirelessmodem + :var1: wlm0 + +.. cmdinclude:: /_include/interface-disable.txt + :var0: wirelessmodem + :var1: wlm0 + +.. cmdinclude:: /_include/interface-vrf.txt + :var0: wirelessmodem + :var1: wlm0 + +WirelessModem (WWAN) options +============================ + +.. cfgcmd:: set interfaces wirelessmodem <interface> apn <apn> + + Every WWAN connection requires an :abbr:`APN (Access Point Name)` which is + used by the client to dial into the ISPs network. This is a mandatory + parameter. Contact your Service Provider for correct APN. + +.. cfgcmd:: set interfaces wirelessmodem <interface> backup distance <metric> + + Configure metric of the default route added via the Wireless Modem interface. + The default metric if not specified is 10. + +.. cfgcmd:: set interfaces wirelessmodem <interface> device <tty> + + Device identifier of the underlaying physical interface. This is usually a + ttyUSB device, if not configured this defaults to ttyUSB2. + +.. cfgcmd:: set interfaces wirelessmodem <interface> no-peer-dns + + Do not install DNS nameservers received from ISP into system wide nameserver + list. + +.. cfgcmd:: set interfaces wirelessmodem <interface> connect-on-demand + + When set the interface is enabled for "dial-on-demand". + + Use this command to instruct the system to establish a PPP connection + automatically once traffic passes through the interface. A disabled on-demand + connection is established at boot time and remains up. If the link fails for + any reason, the link is brought back up immediately. + +********* +Operation +********* + +.. opcmd:: show interfaces wirelessmodem <interface> + + Retrive interface information from given WWAN interface. + + .. code-block:: none + + vyos@vyos:~$ show interfaces wirelessmodem wlm0 + wlm0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master black state UNKNOWN group default qlen 3 + link/ppp + inet 10.26.238.93 peer 10.64.64.64/32 scope global wlm0 + valid_lft forever preferred_lft forever + Description: baaar + + RX: bytes packets errors dropped overrun mcast + 38 5 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 217 8 0 0 0 0 + +.. opcmd:: show interfaces wirelessmodem <interface> statistics + + Retrive interface statistics from given WWAN interface. + + .. code-block:: none + + vyos@vyos:~$ show interfaces wirelessmodem wlm0 statistics + IN PACK VJCOMP VJUNC VJERR | OUT PACK VJCOMP VJUNC NON-VJ + 38 5 0 0 0 | 217 8 0 0 8 + +.. opcmd:: show interfaces wirelessmodem <interface> log + + Displays log information for a WWAN interface. + + +******* +Example +******* + +The following example is based on a Sierra Wireless MC7710 miniPCIe card (only +the form factor in reality it runs UBS) and Deutsche Telekom as ISP. The card +is assembled into a :ref:`pc-engines-apu4`. + +.. code-block:: none + + set interfaces wirelessmodem wlm0 apn 'internet.telekom' + set interfaces wirelessmodem wlm0 backup distance '100' + set interfaces wirelessmodem wlm0 device 'ttyUSB2' + set interfaces wirelessmodem wlm0 disable + set interfaces wirelessmodem wlm0 no-peer-dns + +***************** +Supported Modules +***************** + +The following hardware modules have been tested successfully in an +:ref:`pc-engines-apu4` board: + +* Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) +* Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) +* Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) +* Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) +* Huawei ME909u-521 miniPCIe card (LTE) +* Huawei ME909s-120 miniPCIe card (LTE) |