WireGuard quickstart


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. (see this guide)
     
  • 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-6.9 with the Dynamix WireGuard plugin from Community Apps or Unraid 6.10+ (which has the plugin built in).
  • 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

 

  • 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 (there are some caveats to this covered below)
     
  • 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.


 

Complex Networks

 

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, you'll need to make a few changes:

  • In the WireGuard tunnel 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:
    • Destination Network: 10.253.0.0/24 (aka 10.253.0.0 with subnet 255.255.255.0)
    • Gateway / Next Hop: <IP address of your Unraid system>
    • Distance: 1 (your router may not have this option)
    • If you use pfSense, you may also need to check the box for "Static route filtering - bypass firewall rules for traffic on the same interface". See this.
  • If you have Dockers with custom IPs then on the Docker settings page, set "Host access to custom networks" to "Enabled". see this:
    https://forums.unraid.net/topic/84229-dynamix-wireguard-vpn/page/8/?tab=comments#comment-808801

 

There are some configurations you'll want to avoid, here is how a few key settings interact:

 

  • With "Use NAT" = Yes and "Host access to custom networks" = disabled (static route optional)
    • server and dockers on bridge/host - accessible!

    • VMs and other systems on LAN - accessible!

    • dockers with custom IP - NOT accessible

    • (this is the "simple network" setup assumed by the guide above)

  • With "Use NAT" = Yes and "Host access to custom networks" = enabled (static route optional)

    • server and dockers on bridge/host - accessible!

    • VMs and other systems on LAN - NOT accessible

    • dockers with custom IP - NOT accessible

    • (avoid this config)

  • With "Use NAT" = No and no static route

    • server and dockers on bridge/host - accessible!

    • VMs and other systems on LAN - NOT accessible

    • dockers with custom IP - NOT accessible

    • (avoid this, if "Use NAT" = No, you really need to add a static route in your router)

  • With "Use NAT" = No and "Host access to custom networks" = disabled and static route 

    • server and dockers on bridge/host - accessible!

    • VMs and other systems on LAN - accessible!

    • dockers with custom IP - NOT accessible

    • (You've come this far, just set "Host access to custom networks" to enabled you're set)

  • With "Use NAT" = No and "Host access to custom networks" = enabled and static route 

    • server and dockers on bridge/host - accessible!

    • VMs and other systems on LAN - accessible!

    • dockers with custom IP - accessible!

    • (woohoo! the recommended setup for complex networks)

 

About DNS

 

Everything discussed so far should work if you access the devices by IP address or with a Fully Qualified Domain Name such as yourpersonalhash.unraid.net.

 

Short names such as "tower" probably won't work, nor any DNS entries managed by the router.
 

To get those to work over the tunnel, return to the VPN Manager page in Unraid, switch from Basic to Advanced mode, and add the IP address of your desired DNS server into the "Peer DNS Server" field (don't forget to put the updated config file on the client after saving it!) 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

 

 

** "WireGuard" and the "WireGuard" logo are registered trademarks of Jason A. Donenfeld.

  • Like 21
  • Thanks 26
Link to comment

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 (!) on both the Unraid side and the client side. Note that "active" does not mean "connected". It simply means that the tunnel has started from that end. If DDNS/port forwards/etc are all setup correctly then the two ends will connect and the Unraid dashboard will show a "handshake" and data being transferred.
     
  • 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.
     
  • If you are unable to get a handshake between the client and the server, try doing something that actually uses the tunnel. The client may be waiting for traffic before it starts the connection.
     
  • 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 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 are using Cloudflare for DDNS, be sure to configure the Cloudflare "Proxy status" to "DNS only" and not "Proxied". Note that this change takes some time to take effect.
     
  • 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.

 

Still having trouble getting connected? It may help to think about all the places the connection must pass through:

  • The client itself (WireGuard config, network config, DNS, local firewall, power savings mode)
  • The client's local LAN and router config (unless this is a mobile device on a data connection)
  • The client's Internet connection/ISP
  • The Internet between the client and server
  • The server's Internet connection/ISP
  • The server's local LAN and router config
  • The server itself (WireGuard config, network config)
  • Like 1
Link to comment

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
  • Like 1
Link to comment

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!

  • Like 5
Link to comment

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!

Link to comment
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.

Link to comment
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
Link to comment
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. 

Link to comment

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
Link to comment
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
Link to comment
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
Link to comment

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
Link to comment
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.

Link to comment
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

Link to comment
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
Link to comment
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

Link to comment
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 :) 

Link to comment

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.

  • Thanks 1
Link to comment
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 ! 😉

 

  • Thanks 1
Link to comment
  • itimpi pinned this topic

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.