WireGuard: T1802: add mobile client config generation command

(cherry picked from commit d24b81bed22231d6efc561604809e3dacf2aa0e5)

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
+WireGuard requires the generation of a keypair, which includes a private
-decrypt incoming traffic and a public key, which the peer(s) will use to
+key to decrypt incoming traffic, and a public key for peer(s) to encrypt
-encrypt traffic.
+traffic.
 
-Generate keypair
+Generate Keypair
-----------------
+================
 
 .. opcmd:: generate wireguard default-keypair
 
-   It generates the keypair, that is its public and private part and stores
+   It generates the keypair, which includes the public and private parts,
-   it within VyOS. It will be used per default on any configured WireGuard
+   and stores it within VyOS. It will be used per default on any configured
-   interface, even if multiple interfaces are being 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
+   It shows the public key to be shared with your peer(s). Your peer will
-   peer will encrypt all traffic to your system using this public key.
+   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
+The commands below generates 2 keypairs unrelated to each other.
-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
+the listen port and address/port is optional; however, if you act as a
-and endpoints initiate the connections to your system, you need to
+server and endpoints initiate the connections to your system, you need to
-define a port your clients can connect to, otherwise it's randomly
+define a port your clients can connect to, otherwise the port is randomly
-chosen and may make it difficult with firewall rules, since the port may
+chosen and may make connection difficult with firewall rules, since the port
-be a different one when you reboot your system.
+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
+Copy the key, as it is not stored on the local filesystem. Because it
-you distribute that key in a safe manner, it's a symmetric key, so only
+is a symmetric key, only you and your peer should have knowledge of
-you and your peer should have knowledge of its content.
+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
+======
 
-.. code-block:: none
+.. opcmd:: show interfaces wireguard
 
-  vyos@wg01# run show interfaces wireguard wg01
+  Get a list of all wireguard interfaces
-  interface: wg1
+
-      description: VPN-to-wg01
+  .. code-block:: none
-      address: 10.2.0.1/24
+
-      public key: RIbtUTCfgzNjnLNPQ/asldkfjhaERDFl2H/xUfbyjc=
+    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: 53665
+      listening port: 41751
-      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**
+        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
 
-.. code-block:: none
+Encryption Keys
+===============
 
-  vyos@wg01# run show wireguard keypair pubkey default
+.. opcmd:: show wireguard keypair pubkey <name>
-  FAXCPb6EbTlSH5200J5zTopt9AYXneBthAySPBLbZwM=
 
-**Show public key of a named key**
+  Show public key portion for specified key. This can be either the ``default``
+  key, or any other named key-pair.
 
-.. code-block:: none
+  The ``default`` keypair
 
-  vyos@wg01# run show wireguard keypair pubkey KP01
+  .. code-block:: none
-  HUtsu198toEnm1poGoRTyqkUKfKUdyh54f45dtcahDM=
+
+    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
 
 
-**Delete wireguard keypairs**
+Mobile "RoadWarrior" clients
+============================
 
-.. code-block:: none
+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.
 
-  vyos@wg01# wireguard keypair default
+.. 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.
+
+  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
+.. start_vyoslinter