diff options
| -rw-r--r-- | docs/_static/images/wireguard_qrcode.jpg | bin | 0 -> 127083 bytes | |||
| -rw-r--r-- | docs/configuration/interfaces/wireguard.rst | 181 |
2 files changed, 112 insertions, 69 deletions
diff --git a/docs/_static/images/wireguard_qrcode.jpg b/docs/_static/images/wireguard_qrcode.jpg Binary files differnew file mode 100644 index 00000000..8b03e4d3 --- /dev/null +++ b/docs/_static/images/wireguard_qrcode.jpg diff --git a/docs/configuration/interfaces/wireguard.rst b/docs/configuration/interfaces/wireguard.rst index c4dfbee7..07ced733 100644 --- a/docs/configuration/interfaces/wireguard.rst +++ b/docs/configuration/interfaces/wireguard.rst @@ -8,26 +8,27 @@ 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. +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. -Generate keypair ----------------- +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. + 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 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. + 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. .. code-block:: none @@ -35,15 +36,14 @@ Generate keypair hW17UxY7zeydJNPIyo3UtGnBHkzTK/NeBOrDSIU9Tx0= -Generate named keypair ----------------------- +Generate Named Keypair +====================== -Named keypairs can be used on a interface basis, if configured. If +Named keypairs can be used on a interface basis when 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. +The commands below generates 2 keypairs unrelated to each other. .. code-block:: none @@ -52,15 +52,15 @@ each other. 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. +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 @@ -78,11 +78,11 @@ one. 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 interface-route 10.2.0.0/24 next-hop-interface wg01 + 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 +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 @@ -113,10 +113,10 @@ the public key, which needs to be shared with the peer. 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 interface-route 10.1.0.0/24 next-hop-interface wg01 + 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 +have a working VPN using WireGuard. .. code-block:: none @@ -131,16 +131,16 @@ have a working VPN using WireGuard 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. +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 @@ -154,7 +154,7 @@ 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. +the peers. This allows the peers to interact with one another. .. code-block:: none @@ -170,7 +170,7 @@ the peers. This would allow the peers to interact with one another. } peer iPhone { allowed-ips 10.172.24.20/32 - allowed-ips 2001:DB8:470:22::30/128 + allowed-ips 2001:DB8:470:22::20/128 persistent-keepalive 15 pubkey BknHcLFo8nOo8Dwq2CjaC/TedchKQ0ebxC7GYn7Al00= } @@ -211,59 +211,102 @@ to the server go over the connection. PersistentKeepalive = 25 -Operational commands -==================== +******************** +Operational Commands +******************** -**Show interface status** +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 -.. 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= +.. 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: 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** + listening port: 41751 -.. code-block:: none + 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 - vyos@wg01# run show wireguard keypair pubkey default - FAXCPb6EbTlSH5200J5zTopt9AYXneBthAySPBLbZwM= +Encryption Keys +=============== -**Show public key of a named key** +.. opcmd:: show wireguard keypair pubkey <name> -.. code-block:: none + Show public key portion for specified key. This can be either the ``default`` + key, or any other named key-pair. - vyos@wg01# run show wireguard keypair pubkey KP01 - HUtsu198toEnm1poGoRTyqkUKfKUdyh54f45dtcahDM= + The ``default`` keypair + .. code-block:: none -**Delete wireguard keypairs** + vyos@vyos:~$ show wireguard keypair pubkey default + FAXCPb6EbTlSH5200J5zTopt9AYXneBthAySPBLbZwM= -.. code-block:: none + 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 + + +Mobile "RoadWarrior" clients +============================ + +Some users tend to connect their mobile devices using WireGuard to their VyOS +router. To ease deployment one can generate a "per mobile" configuration from +the VyOS CLI. + +.. warning:: From a security perspective it is not recommended to let a third + party create the private key for a secured connection. You should create the + private portion on your own and only hand out the public key. Please keep this + in mind when using this convenience feature. + +.. opcmd:: generate wireguard mobile-config <interface> server <ip | fqdn> address <client ip> + + Using this command you will create a client configuration which can connect to + ``interface`` on this router. The public key from the specified interface is + automatically extracted and embedded into the configuration. - vyos@wg01# wireguard keypair default + In addition you will specifiy the IP address or FQDN for the client where it + will connect to. The address parameter is used to assign a given client an + IPv4 or IPv6 address. + .. figure:: /_static/images/wireguard_qrcode.jpg + :alt: WireGuard Client QR code .. stop_vyoslinter .. _`WireGuard mailing list`: https://lists.zx2c4.com/pipermail/wireguard/2018-December/003704.html -.. start_vyoslinter
\ No newline at end of file +.. start_vyoslinter |
