Jump to content
ljm42

WireGuard quickstart

162 posts in this topic Last Reply

Recommended Posts

Note: this community guide is offered in the hope that it is helpful, but comes with no warranty/guarantee/etc. Follow at your own risk.

 

 

What can you do with WireGuard? Let's walk through each of the connection types:

 

  • Remote access to server: Use your phone or computer to remotely access your Unraid server, including:
    • Unraid administration via the webgui
    • Access dockers, VMs, and network shares as though you were physically connected to the network
       
  • Remote access to LAN: Builds on "Remote access to server", allowing you to access your entire LAN as well.
     
  • Server to server access: Allows two Unraid servers to connect to each other. 
     
  • LAN to LAN access: Builds on "Server to server access", allowing two entire networks to communicate. May require additional settings, TBD.
     
  • Server hub & spoke access: Builds on "Remote access to server", except that all of the VPN clients can connect to each other as well.  Note that all traffic passes through the server.
     
  • LAN hub & spoke access: Builds on "Server hub & spoke access", allowing you to access your entire LAN as well.
     
  • VPN tunneled access: Route traffic for specific Dockers and VMs through a commercial WireGuard VPN provider (see this guide)
     
  • Remote tunneled access: Securely access the Internet from untrusted networks by routing all of your traffic through the VPN and out Unraid's Internet connection


wireguard-help.png.453a3c3e8373a35d11debf9ba1bf7e7a.png

 

 

In this guide we will walk through how to setup WireGuard so that your trusted devices can VPN into your home network to access Unraid and the other systems on your network.

 

Prerequisites

 

  • You must be running Unraid 6.8 with the Dynamix WireGuard plugin from Community Apps
     
  • Be aware that WireGuard is is technically classified as experimental. It has not gone through a full security audit yet and has not reached 1.0 status. But it is the first open source VPN solution that is extremely simple to install, fast, and designed from the ground up to be secure.
     
  • Understand that giving someone VPN access to your LAN is just like giving them physical access to your LAN, except they have it 24x7 when you aren't around to supervise.  Only give access to people and devices that you trust, and make certain that the configuration details (particularly the private keys) are not passed around insecurely. Regardless of the "connection type" you choose, assume that anyone who gets access to this configuration information will be able to get full access to your network. 
     
  • This guide works great for simple networks. But if you have Dockers with custom IPs or VMs with strict networking requirements, please see the "Complex Networks" section below.
     
  • Unraid will automatically configure your WireGuard clients to connect to Unraid using your current public IP address, which will work until that IP address changes. To future-proof the setup, you can use Dynamic DNS instead.  There are many ways to do this, probably the easiest is described in this 2 minute video from SpaceInvaderOne
     
  • If your router has UPnP enabled, Unraid will be able to automatically forward the port for you.  If not, you will need to know how to configure your router to forward a port.
     
  • You will need to install WireGuard on a client system. It is available for many operating systems:
      https://www.wireguard.com/install/
    Android or iOS make good first systems, because you can get all the details via QR code.


Setting up the Unraid side of the VPN tunnel

 

  • First, go to Settings -> Network Settings -> Interface eth0. If "Enable bridging" is "Yes", then WireGuard will work as described below.  If bridging is disabled, then none of the "Peer type of connections" that involve the local LAN will work properly.  As a general rule, bridging should be enabled in Unraid.
    enable-bridging.png.4a78438488d709e01f8ac0a0efacd199.png
     
  • If UPnP is enabled on your router and you want to use it in Unraid, go to Settings -> Management Access and confirm "Use UPnP" is set to Yes
     
  • On Unraid 6.8, go to Settings -> VPN Manager
    wg0.png.6c5620fdb35ee3c01993b2be2220dd6b.png
     
  • Give the VPN Tunnel a name, such as "MyHome VPN"
     
  • Press "Generate Keypair". This will generate a set of public and private keys for Unraid. Take care not to inadvertently share the private key with anyone (such as in a screenshot like this)
     
  • By default the local endpoint will be configured with your current public IP address. If you chose to setup DDNS earlier, change the IP address to the DDNS address.
     
  • Unraid will recommend a port to use. You typically won't need to change this unless you already have WireGuard running elsewhere on your network.
     
  • Hit Apply
     
  • If Unraid detects that your router supports UPnP, it will automatically setup port forwarding for you:
    upnp-yes.png.9593a57b739d464dab2630f036da5b17.png

    If you see a note that says "configure your router for port forwarding..." you will need to login to your router and setup the port forward as directed by the note:
    upnp-no.png.dffeaeb0e69b3288f61bf80767cf4823.png

    Some tips for setting up the port forward in your router:
    • Both the external (source) and internal (target/local) ports should be the set to the value Unraid provides. If your router interface asks you to put in a range, use the same port for both the starting and ending values.  Be sure to specify that it is a UDP port and not a TCP port.
    • For the internal (target/local) address, use the IP address of your Unraid system shown in the note.
    • Google can help you find instructions for your specific router, i.e. "how to port forward Asus RT-AC68U"
       
  • Note that after hitting Apply, the public and private keys are removed from view. If you ever need to access them, click the "key" icon on the right hand side.
    key.png.23377737a782efd9261e936df3fafbfe.png
     
  • Similarly, you can access other advanced setting by pressing the "down chevron" on the right hand side. They are beyond the scope of this guide, but you can turn on help to see what they do.
     
  • In the upper right corner of the page, change the Inactive slider to Active to start WireGuard. You can optionally set the tunnel to Autostart when Unraid boots.
    activate.png.1bda1b3d9e839a06bc1ec4e707935706.png

 

Defining a Peer (client)

 

  • Click "Add Peer"
    peer-add.png.561adbf6ea35752f2242b5025b0604a1.png
     
  • Give it a name, such as "MyAndroid"
     
  • For the initial connection type, choose "Remote access to LAN". This will give your device access to Unraid and other items on your network.
     
  • Click "Generate Keypair" to generate public and private keys for the client. The private key will be given to the client / peer, but take care not to share it with anyone else (such as in a screenshot like this)
     
  • For an additional layer of security, click "Generate Key" to generate a preshared key. Again, this should only be shared with this client / peer.
     
  • Click Apply.
     
  • Note: Technically, the peer should generate these keys and not give the private key to Unraid. You are welcome to do that, but it is less convenient as the config files Unraid generates will not be complete and you will have to finish configuring the client manually.
     

Configuring a Peer (client)
 

  • Click the "eye" icon to view the peer configuration.  If the button is not clickable, you need to apply or reset your unsaved changes first.
    peer-eye.png.0f5cd3e53a678e89c07502e0b58258de.png

    peer-view.png.b46fbf8d038915e2c2c0f00e7953bd6f.png
     
  • If you are setting up a mobile device, choose the "Create from QR code" option in the mobile app and take a picture of the QR code. Give it a name and make the connection.  The VPN tunnel starts almost instantaneously, once it is up you can open a browser and connect to Unraid or another system on your network. Be careful not to share screenshots of the QR code with anyone, or they will be able to use it to access your VPN.
     
  • If you are setting up another type of device, download the file and transfer it to the remote computer via trusted email or dropbox, etc. Then unzip it and load the configuration into the client. Protect this file, anyone who has access to it will be able to access your VPN.

 

About DNS

 

The 2019.10.20 release of the Dynamix Wireguard plugin includes a "Peer DNS Server" option (thanks @bonienl!)

 

If you are having trouble with DNS resolution on the WireGuard client, return to the VPN Manager page in Unraid and switch from Basic to Advanced mode, add the IP address of your desired DNS server into the "Peer DNS Server" field, then install the updated config file on the client. You may want to use the IP address of the router on the LAN you are connecting to, or you could use a globally available IP like 8.8.8.8

 

This is required for "Remote tunneled access" mode, if the client's original DNS server is no longer accessible after all traffic is routed through the tunnel.

 

If you are using any of the split tunneling modes, adding a DNS server may provide name resolution on the remote network, although you will lose name resolution on the client's local network in the process. The simplest solution is to add a hosts file on the client that provides name resolution for both networks.

 

 

Complex Networks (added Oct 24)

 

The instructions above should work out of the box for simple networks. With "Use NAT" defaulted to Yes, all network traffic on Unraid uses Unraid's IP, and that works fine if you have a simple setup.

However, if you have Dockers with custom IPs or VMs with strict networking requirements, things may not work right (I know, kind of vague, but feel free to read the two WireGuard threads for examples)

 

A partial solution is:

  • In the WireGuard config, set "Use NAT" to No
  • In your router, add a static route that lets your network access the WireGuard "Local tunnel network pool" through the IP address of your Unraid system. For instance, for the default pool of 10.253.0.0/24 you should add this static route:
    • Network: 10.253.0.0/16 (aka 10.253.0.0 with subnet 255.255.0.0)
    • Gateway: <IP address of your Unraid system>

      (Note that this covers the entire class B 10.253.x.x network, so you can add other WireGuard tunnels without having to modify your router setup again.)
       

With these changes, your network should work normally. However, your WireGuard clients still may not be able to access Dockers on custom IPs or VMs. If you find a solution to this, please comment!

Edited by ljm42
  • Like 7
  • Thanks 5

Share this post


Link to post

Troubleshooting WireGuard

 

WireGuard is not a chatty protocol, in fact it is designed to be invisible! There aren't really any error messages if things aren't working, it either works or it doesn't. It cannot be detected by a port scanner.

 

If you can't connect, it will mainly be an exercise in double-checking your work:

 

  • Confirm that the tunnel is active (!)
     
  • Confirm that your DDNS is pointed at your current public IP address, and is assigned to your "Local endpoint"
     
  • Confirm that you forwarded the correct UDP port through your router to Unraid, and assigned that same port to the "Local endpoint"
     
  • If you made any changes to your configuration after setting up your clients, you will need to set the clients up again so they have the latest config.
     
  • Be sure you save your changes before you press "View Peer Config", otherwise your QR codes / files will not have the latest data.

 

A few other ideas:
 

  • For your first client, setup a phone using its data connection (not wifi). This eliminates issues related to the client network, and the QR code is the easiest way to transfer settings. Once you have it working from your phone, move on to other clients.
  • Disable any energy saving features on the client, phones in particular may not use VPNs properly when in low power mode. Also, you may need to disable any "Data Saver" features on the phone so that VPN is not throttled.  See this post.
     
  • If your "Peer type of connection" includes one of the LAN options but you can only access Unraid, go to Settings -> Network Settings and see whether "Enable bridging" is yes.  If bridging is disabled, you will not be able to access your LAN over WireGuard.
     
  • If you are connecting from another network over the Internet, be sure that the networks on both sides use different subnets. You can't connect two networks that both use 192.168.1.0/24, for instance.
     
  • If you can connect from some locations but not others, keep in mind that the "broken" remote locations may have a firewall that blocks UDP traffic. Hopefully WireGuard will support TCP in the future, but currently there is no workaround for this.
     
  • If nothing is working properly, switch to advanced mode and confirm that the "Local tunnel network pool" is not already in use on your network or on one of the networks you are connecting to. If there is a conflict you will need to change it to a different private network (10.0.0.0 to 10.255.255.255 | 172.16.0.0 to 172.31.255.255 | 192.168.0.0 to 192.168.255.255)
     
  • If you can't reach the Unraid webgui for some reason and you need to prevent a WireGuard tunnel from automatically starting, delete this file from your flash drive and reboot:
      /boot/config/wireguard/autostart
     
  • Note that if you have Dockers with custom IPs or VMs with strict networking requirements, you will likely have issues. Please see the "Complex Networks" section above.
Edited by ljm42

Share this post


Link to post

Support

 

Feel free to add comments here if you have questions following this guide or implementing WireGuard. This is new to all of us, so have patience :) 

 

Find a bug? Or want to suggest an improvement? Head over to this thread:

 

thanks!

Edited by ljm42

Share this post


Link to post

Thanks for the quick writeup! I was scratching my head for a good 10 minutes until I realized I had to toggle Inactive to Active. Not sure why my mind read that as clicking inactive would inactivate it. 

 

Once I properly toggled that setting, my phone immediately connected. I can access my network devices by IP address, but didn't have any luck by local hostname. Not sure if its a config issue on my router (pfsense) or just how it is with Wireguard. No issue with that though when connecting via openvpn on pfsense.

 

This is a great method to get secure access to your server/network without much fuss, and am looking forward to seeing how the implementation progresses! I think it will help a lot of unRAID users!

Share this post


Link to post

I unfortunately can't get this to work at all, but I hope someone else can.

 

I can access my dockers through my dns:port, as I could before, but not the unraid GUI unfortunately. Port 51820 gives me "this site can't be reached".  I've tried all the steps repeatedly, but no joy.

 

Good luck to everyone else!

Share this post


Link to post
36 minutes ago, Whiskeyjack said:

I can access my dockers through my dns:port, as I could before, but not the unraid GUI unfortunately. Port 51820 gives me "this site can't be reached".  I've tried all the steps repeatedly, but no joy.

Sorry, but which step are you on that gives you a "this site can't be reached" message? That sounds like an error message from a browser, but this guide does not tell you to put port 51820 into the address bar of your browser, so I'm confused :) 

 

This guide does not setup a reverse proxy for the webui. It sets up a VPN tunnel between a remote machine and your Unraid box, once the tunnel is connected you can access Unraid from a remote location as though you were on the same network.

Share this post


Link to post
1 hour ago, H2O_King89 said:

I can't get remote tunneled access to work. Gives Invalided QR Code

yep, the ip address is missing from the config/qr

Share this post


Link to post
6 hours ago, Whiskeyjack said:

I unfortunately can't get this to work at all, but I hope someone else can.

 

I can access my dockers through my dns:port, as I could before, but not the unraid GUI unfortunately. Port 51820 gives me "this site can't be reached".  I've tried all the steps repeatedly, but no joy.

 

Good luck to everyone else!

Not necessarily your issue, but when using my phone, I cannot access my server if wireguard is connected if I'm on the same network  (no biggie -> I just disable wireguard when at home, and I had the same problem with OpenVPN).  My wife's phone however has no problem.

Edited by Squid

Share this post


Link to post
3 minutes ago, Squid said:

Not necessarily your issue, but when using my phone, I cannot access my server if wireguard is connected if I'm on the same network  (no biggie -> I just disable wireguard when at home, and I had the same problem with OpenVPN).  My wife's phone however has no problem.

Set the allowed IPs in your wireguard app to "0.0.0.0/0, ::/0" that will allow you to get to your server. 

Share this post


Link to post

I would like to see an option to configure the DNS resolver manually once a peer is connected to a tunnel. This would enable local hostname resolution. I'm not sure what dns currently being used, but it looks like not the default one. 

11 hours ago, kaiguy said:

but didn't have any luck by local hostname. Not sure if its a config issue on my router (pfsense)...

Looks like its not only me who has this issue. 

 

Another thing is that I can see that I have the option to connect to the server and lan via ipv4 OR ipv6 but no possibility to have both. Would like to see an option to add the possibility to have dual stack implementation. 

Edited by busa1

Share this post


Link to post
12 hours ago, kaiguy said:

I can access my network devices by IP address, but didn't have any luck by local hostname.

 

1 hour ago, busa1 said:

I would like to see an option to configure the DNS resolver manually once a peer is connected to a tunnel. This would enable local hostname resolution. I'm not sure what dns currently being used, but it looks like not the default one. 

 

This guide covers how to create a "split tunnel" VPN connection. Meaning only the traffic destined for Unraid's LAN goes through the tunnel. All of your other traffic for browsing the web (or DNS resolution), uses your existing routes.

 

If you change the client's DNS resolver to the remote LAN's router, that will prevent the client from doing DNS resolution on their local LAN. But if you aren't concerned about that...

 

The WireGuard config files for your clients are editable once you download them, you could try adding this to the [Interface] section of the client's config:

DNS = <IP Address of the LAN's router>

Personally, I just use IP addresses or a local host file for name resolution on my LAN so I've not experimented with this.

 

 

Since I mentioned split tunneling, I'll also point out that if you choose the "Remote tunneled access" option instead of "Remote access to LAN", that will change the AllowedIPs line in your client config file to:

AllowedIPs=0.0.0.0/0

(slightly different if IPV6 is enabled) which forces all traffic through the tunnel. This can be useful if you are on an untrusted network and want all of your traffic to run through your LAN's Internet connection

Edited by ljm42

Share this post


Link to post
7 hours ago, H2O_King89 said:

I can't get remote tunneled access to work. Gives Invalided QR Code

 

6 hours ago, hotio said:

yep, the ip address is missing from the config/qr

 

Hmm... I am not able to reproduce this. Please toggle from "basic" to "advanced" mode and post a screenshot of your configuration. Feel free to anonymize the values first, just confirm that the anonymized values also cause the problem so we can reproduce it.

 

Oh I see it now. yep. choosing the "remote tunneled access" option creates a config that is missing the ip. Reported in the plugin thread: https://forums.unraid.net/topic/84229-dynamix-wireguard-vpn/?tab=comments#comment-780414

 

Edited by ljm42

Share this post


Link to post

ljm42, thanks for your guide, its running well in my tower.

and waitting for VPN tunneled access, hahahaha~

2019-10-13_012411.png.124721026305746f1c01f5b6f19e2002.png

Share this post


Link to post

Hi All, 

 

Love the guide, I'n having a little issue getting it setup. I read through all the troubleshooting and all the replies so far. 

 

I forwarded the port, and confirmed with ipfingerprints tool ( https://www.ipfingerprints.com/portscan.php ). Duckdns and openvpn are running in a docker container and are both working properly. The tunnel is active. Should I change the local tunnel network pool / address? I tried changing peer allowed ips to 0.0.0.0/0 still no luck. 

 

Just checked on the dashboard and it says handshake not received. 

 

Edited by blackrabbit

Share this post


Link to post
6 minutes ago, blackrabbit said:

still no luck. 

So the issue is that your client isn't able to make a wireguard connection to the server? What error messages does the client give?

 

What client are you using? I'd recommend starting with Android or iPhone that is NOT connected via wifi
 

6 minutes ago, blackrabbit said:

I forwarded the port, and confirmed with ipfingerprints tool

What did you confirm? Wireguard will not respond to requests that don't include the right public keys, so the only way to confirm it is working is by successfully making a connection with a WireGuard client. A port scanner should not be able to detect that WireGuard is running.

Share this post


Link to post
1 minute ago, ljm42 said:

So the issue is that your client isn't able to make a wireguard connection to the server? What error messages does the client give?

 

What client are you using? I'd recommend starting with Android or iPhone that is NOT connected via wifi

I am setting it up on an iPhone, I scan the QR code, the tunnel, and switch it on. When trying to connect to anything on my network by ip it won't connect. 

 

3 minutes ago, ljm42 said:

What did you confirm? Wireguard will not respond to requests that don't include the right public keys, so the only way to confirm it is working is by successfully making a connection with a WireGuard client. A port scanner should not be able to detect that WireGuard is running.

 

You are completely right, I didn't know that. Now I do. Thanks

Share this post


Link to post
25 minutes ago, blackrabbit said:

I am setting it up on an iPhone, I scan the QR code, the tunnel, and switch it on. When trying to connect to anything on my network by ip it won't connect. 

Interesting. So the WireGuard app on the phone says it connects? 


What about on the Unraid dashboard, does it show a "handshake" with your client or any activity?

image.png.424fb1eea9c55c2132ade2f6c06216ec.png

 

 

Edit - I'd recommend trying to connect to your Unraid webgui as a first step once the tunnel is up

Edited by ljm42

Share this post


Link to post
10 hours ago, H2O_King89 said:

I can't get remote tunneled access to work. Gives Invalided QR Code

 

3 hours ago, ljm42 said:

 

 

Hmm... I am not able to reproduce this. Please toggle from "basic" to "advanced" mode and post a screenshot of your configuration. Feel free to anonymize the values first, just confirm that the anonymized values also cause the problem so we can reproduce it.

 

Oh I see it now. yep. choosing the "remote tunneled access" option creates a config that is missing the ip. Reported in the plugin thread: https://forums.unraid.net/topic/84229-dynamix-wireguard-vpn/?tab=comments#comment-780414

 

Just add the 'peer tunnel address' manually.

Says its not used

 

788242136_ScreenShot2019-10-12at20_08_53.thumb.png.5817e9d68e997ec8b049329ff2121eed.png

 

but add as below then will conif and QR code will be made  and work fine.

 

 

296075022_ScreenShot2019-10-12at20_04_30.thumb.png.d3cbcdba51c8c8c2ea1aab2593b16554.png

Share this post


Link to post
29 minutes ago, ljm42 said:

Interesting. So the WireGuard app on the phone says it connects? 


What about on the Unraid dashboard, does it show a "handshake" with your client or any activity?

image.png.424fb1eea9c55c2132ade2f6c06216ec.png

 

It says handshake not received on the dashboard, andon my phone it connects and doesn't throw any errors. :( 

 

30 minutes ago, ljm42 said:

Edit - I'd recommend trying to connect to your Unraid webgui as a first step once the tunnel is up

That has been my go to this far :) 

Share this post


Link to post

@ljm42 I have attached some screenshots that show what we are talking about. 

 

1. Active Connection on Phone

 

IMG_0735.thumb.jpeg.b2b9f2d5587f198a9ea6e9712047676e.jpeg

 

2. Connection timed out when I tried to reach the unraid server. 

IMG_0737.thumb.jpeg.0eeda8435ddd227a512ea5a282f7c283.jpeg
3. Settings for WireGuard

Capture.thumb.PNG.8ce786f9fe8d98cf43fa410731cffe3b.PNG

 

4. Dashboard VPN module

 

 Capture2.PNG.055afd89e899d386522137fbbf8a4a5d.PNG

Share this post


Link to post

W T F, was that easy. LOL

 

Working 1000%.

 

Easy to use.

 

Question left is, how secure is it?

Share this post


Link to post

I use a remote Unraid server in another state as a backup and I also manage the server.  I've been using Wireguard since it was first introduced in the beta testing of 6.8 and I find it to be incredibly easy to set up and very reliable.  A lot simpler than OpenVPN to setup, and appears to be much faster.

 

14 minutes ago, nuhll said:

Question left is, how secure is it?

It is still in development and I don't think it has been certified yet.  The developers warn that is not fully ready for prime time and should not be used in production.  I personally don't think that is a problem for us.  If I were a financial institution, I would not use it until it has been certified.  The bad guys are lazy and won't spend much time trying to hack into our networks, Wireguard will discourage them and they'll move on.

Share this post


Link to post
15 minutes ago, nuhll said:

W T F, was that easy. LOL

 

Working 1000%.

 

Easy to use.

 

Question left is, how secure is it?

Its still in heavy developement and hasn't reached 1.0 yet. But people do think that it is very secure and it uses proven cryptographic protocols. The peers are identified to other peers using small public keys a bit like key-based authentication in ssh. It is very difficult to see it running on another machine even because it doesnt respond to packets from peers it doesn't know making a network scan not show that wireguard is running.
 

.................but............lol   shouldn't you have asked that before setting it up ! 😉

 

Share this post


Link to post

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.
Note: Your post will require moderator approval before it will be visible.

Guest
Reply to this topic...

×   Pasted as rich text.   Restore formatting

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.