diff options
| -rw-r--r-- | docs/_static/images/wireguard_site2site_diagram.jpg | bin | 0 -> 19987 bytes | |||
| -rw-r--r-- | docs/configuration/cluster/index.rst (renamed from docs/clustering.removed) | 0 | ||||
| -rw-r--r-- | docs/configuration/index.rst | 1 | ||||
| -rw-r--r-- | docs/configuration/interfaces/wireguard.rst | 333 | ||||
| -rw-r--r-- | docs/introducing/about.rst | 2 |
5 files changed, 254 insertions, 82 deletions
diff --git a/docs/_static/images/wireguard_site2site_diagram.jpg b/docs/_static/images/wireguard_site2site_diagram.jpg Binary files differnew file mode 100644 index 00000000..4a7a95e4 --- /dev/null +++ b/docs/_static/images/wireguard_site2site_diagram.jpg diff --git a/docs/clustering.removed b/docs/configuration/cluster/index.rst index 97678445..97678445 100644 --- a/docs/clustering.removed +++ b/docs/configuration/cluster/index.rst diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst index ee2c6354..afab98a6 100644 --- a/docs/configuration/index.rst +++ b/docs/configuration/index.rst @@ -8,6 +8,7 @@ The following structure respresent the cli structure. :maxdepth: 1 :includehidden: + cluster/index firewall/index highavailability/index interfaces/index diff --git a/docs/configuration/interfaces/wireguard.rst b/docs/configuration/interfaces/wireguard.rst index a7241613..d738c017 100644 --- a/docs/configuration/interfaces/wireguard.rst +++ b/docs/configuration/interfaces/wireguard.rst @@ -1,148 +1,319 @@ .. _wireguard: -WireGuard VPN Interface ------------------------ +######### +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. +**************** +Site to Site VPN +**************** + +This diagram corresponds with the example site to site configuration below. + +.. figure:: /_static/images/wireguard_site2site_diagram.jpg + +************* 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 a keypair -~~~~~~~~~~~~~~~~~~ -Generate the keypair, which creates a 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. +******** +Keypairs +******** -.. code-block:: none +WireGuard requires the generation of a keypair, which includes a private +key to decrypt incoming traffic, and a public key for peer(s) to encrypt +traffic. - wg01:~$ configure - wg01# run generate wireguard keypair +Generate Keypair +================ -The public key is being shared with your peer(s), your peer will encrypt all -traffic to your system using this public key. +.. opcmd:: generate wireguard keypair -.. code-block:: none + It generates the keypair, which includes the public and private parts, + 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 pubkey + + It shows the public key to be shared with your peer(s). Your peer will + encrypt all traffic to your system using this public key. - wg01# run show wireguard pubkey - u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk= + .. code-block:: none -Wireguard Interface configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + vyos@vyos:~$ show wireguard pubkey + hW17UxY7zeydJNPIyo3UtGnBHkzTK/NeBOrDSIU9Tx0= -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 endpoint 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. +*********************** +Interface configuration +*********************** -**local side** +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; however, if you act as a +server and endpoints initiate the connections to your system, you need to +define a port your clients can connect to, otherwise the port is randomly +chosen and may make connection difficult with firewall rules, since the port +may be different each time the system is rebooted. + +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 - commands** .. code-block:: none - set interfaces wireguard wg01 address '10.1.0.1/24' + set interfaces wireguard wg01 address '10.1.0.1/30' set interfaces wireguard wg01 description 'VPN-to-wg02' - set interfaces wireguard wg01 peer to-wg02 allowed-ips '10.2.0.0/24' - set interfaces wireguard wg01 peer to-wg02 endpoint '192.168.0.142:12345' + set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.2.0/24' + set interfaces wireguard wg01 peer to-wg02 endpoint '<Site1 Pub IP:51820> set interfaces wireguard wg01 peer to-wg02 pubkey 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=' - set interfaces wireguard wg01 port '12345' - set protocols static interface-route 10.2.0.0/24 next-hop-interface wg01 + set interfaces wireguard wg01 port '51820' + set protocols static route 192.168.2.0/24 interface wg01 -.. note:: The `endpoint` must be an IP and not a fully qualified domain name (FQDN). Using a FQDN will result in unexpected behavior. +**local side - annotated commands** -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. +.. code-block:: none + + set interfaces wireguard wg01 address '10.1.0.1/30' # Address of the wg01 tunnel interface. + set interfaces wireguard wg01 description 'VPN-to-wg02' + set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.2.0/24' # Subnets that are allowed to travel over the tunnel + set interfaces wireguard wg01 peer to-wg02 endpoint '<Site1 Pub IP:51820> + set interfaces wireguard wg01 peer to-wg02 pubkey '<pubkey>' # Public Key of the Peer + set interfaces wireguard wg01 port '51820' # Port of own server + set protocols static route 192.168.2.0/24 interface wg01 # Static route to remote subnet + +The last step is to define an interface route for 10.2.0.0/24 to get +through the WireGuard interface `wg01`. Multiple IPs or networks can be +defined and routed. The last check is allowed-ips which either prevents +or allows the traffic. -**remote side** + +**remote side - commands** .. code-block:: none - set interfaces wireguard wg01 address '10.2.0.1/24' + set interfaces wireguard wg01 address '10.1.0.2/30' set interfaces wireguard wg01 description 'VPN-to-wg01' - set interfaces wireguard wg01 peer to-wg02 allowed-ips '10.1.0.0/24' - set interfaces wireguard wg01 peer to-wg02 endpoint '192.168.0.124:12345' + set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.1.0/24' + set interfaces wireguard wg01 peer to-wg02 endpoint '<Site1 Pub IP:51820> set interfaces wireguard wg01 peer to-wg02 pubkey 'u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk=' - set interfaces wireguard wg01 port '12345' - set protocols static interface-route 10.1.0.0/24 next-hop-interface wg01 + set interfaces wireguard wg01 port '51820' + set protocols static route 192.168.1.0/24 interface wg01 + +**remote side - annotated commands** + +.. code-block:: none + + set interfaces wireguard wg01 address '10.1.0.2/30' # Address of the wg01 tunnel interface. + set interfaces wireguard wg01 description 'VPN-to-wg01' + set interfaces wireguard wg01 peer to-wg02 allowed-ips '192.168.1.0/24' # Subnets that are allowed to travel over the tunnel + set interfaces wireguard wg01 peer to-wg02 endpoint '<Site1 Pub IP:51820> + set interfaces wireguard wg01 peer to-wg02 pubkey '<pubkey>' # Public key of the Peer + set interfaces wireguard wg01 port '51820' # Port of own server + set protocols static route 192.168.1.0/24 interface wg01 # Static route to remote subnet + +******************* +Firewall Exceptions +******************* + +For the WireGuard traffic to pass through the WAN interface, you must create a firewall exception. + +.. code-block:: none + + set firewall name OUTSIDE_LOCAL rule 10 action accept + set firewall name OUTSIDE_LOCAL rule 10 description 'Allow established/related' + set firewall name OUTSIDE_LOCAL rule 10 state established enable + set firewall name OUTSIDE_LOCAL rule 10 state related enable + set firewall name OUTSIDE_LOCAL rule 20 action accept + set firewall name OUTSIDE_LOCAL rule 20 description WireGuard_IN + set firewall name OUTSIDE_LOCAL rule 20 destination port 51820 + set firewall name OUTSIDE_LOCAL rule 20 log enable + set firewall name OUTSIDE_LOCAL rule 20 protocol udp + set firewall name OUTSIDE_LOCAL rule 20 source + +You should also ensure that the OUTISDE_LOCAL firewall group is applied to the WAN interface and a direction (local). + +.. code-block:: none + + set interfaces ethernet eth0 firewall local name 'OUTSIDE-LOCAL' -Assure that your firewall rules allow the traffic, in which case you have a -working VPN using wireguard. +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 + wg01# ping 192.168.1.1 + PING 192.168.1.1 (192.168.1.1) 56(84) bytes of data. + 64 bytes from 192.168.1.1: icmp_seq=1 ttl=64 time=1.16 ms + 64 bytes from 192.168.1.1: icmp_seq=2 ttl=64 time=1.77 ms - wg02# ping 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 + wg02# ping 192.168.2.1 + PING 192.168.2.1 (192.168.2.1) 56(84) bytes of data. + 64 bytes from 192.168.2.1: icmp_seq=1 ttl=64 time=4.40 ms + 64 bytes from 192.168.2.1: icmp_seq=2 ttl=64 time=1.02 ms An additional layer of symmetric-key crypto can be used on top of the -asymmetric crypto, which is optional. +asymmetric crypto. This 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. +Copy the key, as it is not stored on the local filesystem. Because it +is a symmetric key, only you and your peer should have knowledge of +its content. Make sure you distribute the key in a safe manner, .. 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=' -Operational commands -^^^^^^^^^^^^^^^^^^^^ -**Show interface status** +*********************************** +Remote Access "RoadWarrior" Example +*********************************** + +With WireGuard, a Road Warrior VPN config is similar to a site-to-site +VPN. It just lacks the ``address`` and ``port`` statements. + +In the following example, the IPs for the remote clients are defined in +the peers. This allows the peers to interact with one another. .. code-block:: none - vyos@wg01# run show interfaces wireguard wg01 + 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::20/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`` wildcard setting directs all IPv4 and IPv6 traffic +through the connection. + +.. code-block:: none - interface: wg01 - public key: xHvgSJC8RTClfvjc0oX6OALxU6GGLapjthjw7x82CSw= - private key: (hidden) - listening port: 12345 + [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: 9Ek3R30mG6Vk+GHsENtPF0b9Ul+ftxx4dDBa1bdBxX8= - endpoint: 192.168.0.142:12345 - allowed ips: 10.2.0.0/24 - latest handshake: 4 minutes, 22 seconds ago - transfer: 860 B received, 948 B sent + [Peer] + PublicKey = RIbtUTCfgzNjnLNPQ/ulkGnnB2vMWHm7l2H/xUfbyjc= + AllowedIPs = 0.0.0.0/0, ::/0 + Endpoint = 192.0.2.1:2224 + PersistentKeepalive = 25 -**Show public key of the default key** +However, split-tunneling can be achieved by specifing the remote subnets. +This ensures that only traffic destined for the remote site is sent over the tunnel. +All other traffic is unaffected. .. code-block:: none - vyos@wg01# run show wireguard keypair pubkey default - FAXCPb6EbTlSH5200J5zTopt9AYXneBthAySPBLbZwM= + [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 -**Delete wireguard keypairs** -.. code-block:: none +******************** +Operational Commands +******************** + +Status +====== + +.. opcmd:: show interfaces wireguard + + Get a list of all wireguard interfaces + + .. code-block:: none + + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + wg0 10.0.0.1/24 u/u + + +.. opcmd:: show interfaces wireguard <interface> + + Show general information about specific WireGuard interface + + .. code-block:: none + + vyos@vyos:~$ show interfaces wireguard wg01 + interface: wg0 + address: 10.0.0.1/24 + public key: h1HkYlSuHdJN6Qv4Hz4bBzjGg5WUty+U1L7DJsZy1iE= + private key: (hidden) + listening port: 41751 + + 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 + +*************** +Encryption Keys +*************** + +.. opcmd:: show wireguard keypair pubkey <name> + + Show public key portion for specified key. This can be either the ``default`` + key, or any other named key-pair. + + The ``default`` keypair + + .. code-block:: none + + vyos@vyos:~$ show wireguard keypair pubkey default + FAXCPb6EbTlSH5200J5zTopt9AYXneBthAySPBLbZwM= + + Name keypair ``KP01`` + + .. code-block:: none + + vyos@vyos:~$ show wireguard keypair pubkey KP01 + HUtsu198toEnm1poGoRTyqkUKfKUdyh54f45dtcahDM= + +.. opcmd:: delete wireguard keypair pubkey <name> + + Delete a keypair, this can be either the ``default`` key, or any other + named key-pair. + + .. code-block:: none + + vyos@vyos:~$ delete wireguard keypair default + +.. stop_vyoslinter - vyos@wg01# wireguard keypair default +.. _`WireGuard mailing list`: https://lists.zx2c4.com/pipermail/wireguard/2018-December/003704.html +.. start_vyoslinter diff --git a/docs/introducing/about.rst b/docs/introducing/about.rst index 0411344b..5707b80f 100644 --- a/docs/introducing/about.rst +++ b/docs/introducing/about.rst @@ -16,7 +16,7 @@ https://readthedocs.org. We will provide one version of the manual for every VyOS major version starting with VyOS 1.2 which will receive Long-term support (LTS). -The manual version is selected/specified by it's Git branch name. You can +The manual version is selected/specified by its Git branch name. You can switch between versions of the documentation by selecting the appropriate branch on the bottom left corner. |
