Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision
Previous revision
wireguard [2020/01/22 14:15]
chewitt created
wireguard [2020/03/17 05:51] (current)
chewitt
Line 1: Line 1:
-** This is a DRAFT article, pending future merge of WireGuard ​functionality **+=== Configuring ​WireGuard ​in LibreELEC (v9.2.1 and newer) ===
  
-LibreELEC can be configured as a WireGuard VPN client allowing you to accessing media in a remote location or tunnel traffic to avoid local inspection of network activity. This guide assumes a single WireGuard tunnel that is persistent, i.e. activated on boot so that Kodi network traffic is normally ​routed through the WireGuard tunnel.+LibreELEC can be configured as a WireGuard VPN client allowing you to accessing media in a remote location or tunnel traffic to avoid local inspection of network activity. This guide assumes ​configuration of a single WireGuard tunnel that is persistent, i.e. activated on device ​boot so that Kodi network traffic is routed through the WireGuard ​VPN tunnel.
  
-WireGuard tunnels are managed by a VPN plugin (connman-vpn.service) that acts as a companion to the main connection manager daemon (connman.service). The VPN plugin ​reads from /​storage/​.config/​wireguard/​*.conf and will attempt to define ConnMan services from the auto-discovered ​configurations (ConnMan watches the folder). Once a valid ConnMan ​service exists ​it can be connected using the scriptable ​connmanctl ​utility, ​or using the LibreELEC settings add-on which controls ​ConnMan services via DBUS.+WireGuard tunnels are managed by a ConnMan ​VPN plugin (connman-vpn.service) that acts as a companion to the main network ​connection manager daemon (connman.service). The VPN plugin ​watches ​/​storage/​.config/​wireguard/​*.config ​and will attempt to define ConnMan services from auto-discovered ​configuration files. Once a valid ConnMan ​WireGuard .config has been imported ​it can be connected; either manually ​using connmanctl ​from the SSH console ​or scripted from a systemd service that runs on boot. Connections can also be controlled manually from the network '​Connections'​ tab in the LibreELEC settings add-on which connects and disconnects WireGuard (ConnManservices via d-bus.
  
-Note: ConnMan uses its own configuration file format, see /storage/.config/wireguard/​wireguard.conf.sample. You will not be able to use the native ​configuration ​file exported from WireGuard server. The native file contains all the information ​you need. You need to transpose the information into the ConnMan format, as shown below:+Note: ConnMan uses its own configuration file format ​(shown below)You cannot import/use the WireGuard ​configuration ​files exported from most WireGuard server ​tools and third-party VPN services - the format is different. The files will contain everything ​you need, but you must transpose the information into the ConnMan format:
  
 <​code>​ <​code>​
 [provider_wireguard] [provider_wireguard]
 Type = WireGuard Type = WireGuard
-Name = WireGuard ​VPN Tunnel +Name = WireGuard ​(Home) 
-Host = 3.2.5.6 +Host = 185.210.30.121 
-Domain = my.home.network+Domain = my.home.vpn
 WireGuard.Address = 10.2.0.2/24 WireGuard.Address = 10.2.0.2/24
 WireGuard.ListenPort = 51820 WireGuard.ListenPort = 51820
Line 27: Line 27:
  
 Name = AnythingYouLike\\ ​ Name = AnythingYouLike\\ ​
-Host = IP or hostname ​of the WireGuard **server**\\+Host = IP of the WireGuard **server**\\
 Domain = must.not.be.blank\\ ​ Domain = must.not.be.blank\\ ​
 WireGuard.Address = The internal IP of the **client** node, usually a /24 address\\ WireGuard.Address = The internal IP of the **client** node, usually a /24 address\\
Line 35: Line 35:
 WireGuard.PresharedKey = The **server** pre-shared key (optional)\\ WireGuard.PresharedKey = The **server** pre-shared key (optional)\\
 WireGuard.DNS = Nameserver to be used with the connection (optional)\\ WireGuard.DNS = Nameserver to be used with the connection (optional)\\
-WireGuard.AllowedIPs = Subnets accessed via the tunnel, 0.0.0.0/0 means "route all traffic ​through tunnel"\\+WireGuard.AllowedIPs = Subnets accessed via the tunnel, 0.0.0.0/0 means "route all traffic"​\\
 WireGuard.EndpointPort = The **server** ListenPort\\ ​ WireGuard.EndpointPort = The **server** ListenPort\\ ​
 WireGuard.PersistentKeepalive = Periodic keepalive in seconds (optional)\\ ​ WireGuard.PersistentKeepalive = Periodic keepalive in seconds (optional)\\ ​
  
-Note: "Domain" can be anything you like in host.domain.tld formate.g. "my.home.vpn" ​or "​alice.loves.bob" ​are valid as they have at least one in their names, but single word "​vpn"​ or underscored "​secret_tunnel" are not validDomain ​is a quirk of how ConnMan internally stores services, and it must exist.+Domain ​is quirk of how ConnMan internally names and stores services, and it must existIt is simply a text field, not a qualified ​domain, ​so "MyVPN" ​and "​alice.loves.bob" ​and "​libreelec.tv" are all valid Domain ​entries.
  
-If you need to create ​WireGuard ​keys, run "​wg-keygen"​ and /​storage/​.cache/​wireguard will contain new Public, Private and Preshared key files. **Caution!** If you run the tool again, existing keys will be overwritten.+=== Creating ​WireGuard ​Keys ===
  
-=== Testing ​the connection ​===+If you need to create some, run "​wg-keygen"​ from the SSH console and /​storage/​.cache/​wireguard will contain new publickey, priatekey, and preshared files with keys inside. Most users will not need to generate WireGuard keys as they will be in the configuration file provided by a VPN service provider.  
 + 
 +=== Testing ​Connections ​===
  
 Once you have saved a configuration file, check it is valid: Once you have saved a configuration file, check it is valid:
Line 53: Line 55:
 </​code>​ </​code>​
  
-In the above example ​Name was '​home'​ and vpn_185_210_30_121_my_home_vpn ​is the service name (vpn_Host_Domain). Test the service will connect using:+In the above example ​"vpn_185_210_30_121_my_home_vpn" was created ​(vpn_Host_Domain) ​as the ConnMan service name. Test the service will connect using:
  
 <​code>​ <​code>​
Line 59: Line 61:
 </​code>​ </​code>​
  
-If the connection was successful, "​ifconfig"​ will show a new wg0 (sometimes wg1, wg2) connection, e.g.+ConnMan will create a new network interfaceso "​ifconfig"​ will show wg0 (sometimes wg1, wg2), e.g.
  
 <​code>​ <​code>​
Line 81: Line 83:
  
 wg0       Link encap:​UNSPEC ​ HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00  ​ wg0       Link encap:​UNSPEC ​ HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00  ​
-          inet addr:10.10.10. ​P-t-P:​10.10.10. ​Mask:​255.255.255.0+          inet addr:10.2.0. ​P-t-P:​10.2.0. ​Mask:​255.255.255.0
           UP POINTOPOINT RUNNING NOARP  MTU:​1420 ​ Metric:1           UP POINTOPOINT RUNNING NOARP  MTU:​1420 ​ Metric:1
           RX packets:​13744 errors:0 dropped:0 overruns:0 frame:0           RX packets:​13744 errors:0 dropped:0 overruns:0 frame:0
Line 89: Line 91:
 </​code>​ </​code>​
  
-You should be able to "​ping"​ the remote side of the tunnel:+You should be able to "​ping"​ the remote ​(server) ​side of the WireGuard VPN tunnel. In our example this is 10.2.0.1:
  
 <​code>​ <​code>​
-RPi4:~ # ping 10.10.10.1 +RPi4:~ # ping 10.2.0.1 
-PING 10.10.10.1 (10.10.10.1): 56 data bytes +PING 10.2.0.1 (10.2.0.1): 56 data bytes 
-64 bytes from 10.10.10.1: seq=0 ttl=64 time=147.936 ms +64 bytes from 10.2.0.1: seq=0 ttl=64 time=147.936 ms 
-64 bytes from 10.10.10.1: seq=1 ttl=64 time=147.955 ms+64 bytes from 10.2.0.1: seq=1 ttl=64 time=147.955 ms
 </​code>​ </​code>​
  
-The routing table will show normall ​traffic routed to the wg0 interface:+The routing table will show normal ​traffic routed to the wg0 interface:
  
 <​code>​ <​code>​
Line 107: Line 109:
 1.1.1.1 ​        ​* ​              ​255.255.255.255 UH    0      0        0 wg0 1.1.1.1 ​        ​* ​              ​255.255.255.255 UH    0      0        0 wg0
 8.8.8.8 ​        ​* ​              ​255.255.255.255 UH    0      0        0 wg0 8.8.8.8 ​        ​* ​              ​255.255.255.255 UH    0      0        0 wg0
-10.10.10.0      *               ​255.255.255.0 ​  ​U ​    ​0 ​     0        0 wg0+10.2.0.0        *               ​255.255.255.0 ​  ​U ​    ​0 ​     0        0 wg0
 192.168.10.0 ​   *               ​255.255.255.0 ​  ​U ​    ​0 ​     0        0 eth0 192.168.10.0 ​   *               ​255.255.255.0 ​  ​U ​    ​0 ​     0        0 eth0
 192.168.10.1 ​   *               ​255.255.255.255 UH    0      0        0 eth0 192.168.10.1 ​   *               ​255.255.255.255 UH    0      0        0 eth0
-185.210.30.121  ​172.16.20.1     ​255.255.255.255 UGH   ​0 ​     0        0 eth0+185.210.30.121  ​192.168.10.1    255.255.255.255 UGH   ​0 ​     0        0 eth0
 </​code>​ </​code>​
  
-Next, disconnect the service:+To disconnect the ConnMan ​service:
  
 <​code>​ <​code>​
Line 119: Line 121:
 </​code>​ </​code>​
  
-If you check "​ifconfig"​ againthe WireGuard interface ​(wg0 or similar) ​will be gone. +Check "​ifconfig"​ again and the WireGuard interface will be gone. 
  
-=== Configuring ​systemd ​===+=== Configuring ​Systemd ​===
  
-To start the connection automatically on boot we need to create a systemd service. This tells systemd which ConnMan service to startand the sequence/​dependencies (when to start it). The sample wireguard.service file looks like:+To start the connection automatically on boot we need to create a systemd ​wireguard.service ​file. This tells ConnMan ​which service to start and the sequence/​dependencies (when to start it). The sample wireguard.service file looks like:
  
 <​code>​ <​code>​
Line 147: Line 149:
 </​code>​ </​code>​
  
-Replace **vpn_service_name_goes_here** with your service name, e.g. vpn_185_210_30_121_my_home_vpnusing nano (ctrl+o to savectrl+x to exit):+Replace **vpn_service_name_goes_here** with your service name, e.g. vpn_185_210_30_121_my_home_vpn using nano. Use "ctrl+o" ​to save changes and "ctrl+x" ​to exit nano:
  
 <​code>​ <​code>​
Line 153: Line 155:
 </​code>​ </​code>​
  
-Enable ​and start the system.d ​service:+Now we can enable ​and start the service:
  
 <​code>​ <​code>​
Line 161: Line 163:
 </​code>​ </​code>​
  
-Congrats! .. Check that the connection ​is active using "​ifconfig"​ and "​ping"​ and if all is good, test a reboot+Congrats! .. all is done. Check the WireGuard tunnel ​is active using "​ifconfig"​ and "​ping"​ and if all is good, reboot to test the WireGuard tunnel ​comes up automatically ​on boot.
- +
-== Known Issues == +
- +
-- The sample WireGuard service is sequenced ​to start the tunnel once the network is active, and before multi-user.target which is responsible for starting userspace applications (Kodi). This does not guarantee that all Kodi traffic runs through the tunnel, only that the WireGuard tunnel ​starts-starting before Kodi. If the tunnel takes time to come up, it is still possible for Kodi to start and transmit data on the normal Internet connection. There are no plans to "​fix"​ this as there are no simple programattic fixes. If this is not acceptable to you, we are not the Linux distro you are looking for (we care about practical not ultimate security). +
- +
-- ConnMan currently supports a single active WireGuard connection via connman-vpn. If you place more than one active WireGuard .conf file in /​storage/​.config/​wireguard directory it will probably throw errors and need restarting. To avoid issues, rename inactive confs to .disabled and ensure there is only one active .conf file in the directory. If you need to restart, run "​systemctl restart connman-vpn"​ and all will be back to normal.+
  
-== Thanks ==+=== Thanks ​===
  
 Big thanks to ConnMan maintainer Daniel Wagner from the Open Source group at Intel who has worked with Team LibreELEC staff to implement WireGuard support in ConnMan (he wrote the code, we tested it). Thanks wagi! Big thanks to ConnMan maintainer Daniel Wagner from the Open Source group at Intel who has worked with Team LibreELEC staff to implement WireGuard support in ConnMan (he wrote the code, we tested it). Thanks wagi!