Simple guide to official wg-easy app installation on SCALE

[Black_Duck]

*** Updated 01/01/2024 *** (updates in green)
Wg-easy provides a simple and easy way to provide a WireGuard VPN access to your system. It allows you to securely log into your local network remotely, providing access to all devices on you local network, including your TrueNAS server and File Servers.
Under SCALE, wg-easy is available as an app in the offical iX catalog as well as the Truecharts catalog. There has been a number of threads about issues with the official wg-easy app (iX catalog) installation. For those interested in using this version, I thought it may be beneficial to summarise a number of known issues and associated fixes here. Note, the instructions below are is only for the iX catalog version. It will not work for the Truecharts version.
Note that Version 9 onwards of the WG-EASY app now allows the use of WG_DEV Environment Variable. This is explicitly set by the Application Environment "Device Name" (see below).

• Installation Documentation. The installation documentation found in the Documentation hub is a good start. However, there are a number of know issues that need to be corrected before it will work (see below). Some notes:
  • Recommend you stick to default values, especially for "Clients IP Address Range"
  • Note that if you "Enable Custom Host Path for WG-Easy Configuration Volume" and subsequently edit wg0.conf, any changes will be overwritten on subsequent restarts.
  • Make sure that "Host Network" is ticked.
• Port Number: The default port in the app is (now) 30057. However WireGuard always listens on port 51820 inside the container. You can 'translate' the port at the router (see below), but I recommend using port 51820 throughout to avoid confusion. Make the following changes under "Networking" setting in the app setup:
  1. Set "WireGuard UDP Node Port for WG-Easy" to 51820.
     Note: you will now need to forward port 51820 (instead of 30057) in your router (see below)
  2. Set "WebUI Node Port for WG-Easy" to 51821
     Note: that means the wg-easy web interface is through 51821 (i.e https://[truenas IP address]:51821)
• Network Interface: Set the Allocation Variable "Device Name" to your Network interface Name. If you have the wrong name, you will not be able to access the internet through your vpn.
  • The Network interface Name located under Network/Interfaces in SCALE. It will look something like “enp0s31f6”.
  • If you are using a bridge, use the bridge name (e.g. br0) - see below for more details.
• Duplicates in iptables: At startup, the app appends a number of route rules to the iptable chains, creating duplicate entries. This is not really a “show-stopper”, but if you want to stop this, add the following to the app setup.
  1. Go into the the app setup. Go down to the section “WG-Easy Environment”. Add an Environment variable:
     • Name: WG_PRE_UP
     • Value: iptables -t nat -F; iptables -F;
       This flushes the chains before adding new rules at startup
• Static IP address: to ensure that Port Forwarding works correctly (see below), you need to ensure you have a static address on your TrueNAS server. Follow the instructions outlined here. I noticed the setup is lightly different from the documentation in 22.12.3.3. In that version you need to create an "Alias" with the static IP address.
• Port Forwarding: You need to set up port forwarding on your router. Specifically, forward UDP port 51820 (Source) to [the IP address you set up in Step 5], port 51820 (Destination). Each router is different, so just google how to do it on your device. Note, if you have chosen to keep the default UDP port (30057) or intend to use some other port, you will need to set your Source Port to 30057 (or whatever) and set your Destination port to 51820. The destination port must always be 51820.
• Set up Client: Install WireGuard on your client. See here for downloads.
• Set up VPN: Log into the wg-easy WebUI either by clicking on wg-easy "Web Portal" on the APPS page of your server or via https://[truenas IP address]:51821 (this assumes you are running https on your server). Login using the password you set in the apps setup.
  1. Click on "Add" and enter a name for the Client you are creating. Click enter.
  2. Depending on the client either:
     • download the Configuration file and input the file into the client
     • Click on "Show QR code"; go into your your client; add a new Wireguard Tunnel; then select "Create from QR code"

You should now have a working wg-easy, allowing access to your network from anywhere.

If you have Virtual Machines or Apps using the host network interface (i.e. enp0s31f6 ) and need to access the them through the VPN, you will need to create a bridge and update your wg-easy config accordingly.

1. Set up a bridge (eg. br0) as per the instructions here.
2. Update your VMs or Apps that use a Host Network interface to use the bridge (i.e. br0 interface)
3. Change wg-easy to use the bridge (i.e. Set the Allocation Environment Variable "Device Name" to br0 interface) instead of the of the NIC.

Note: you will need to update your port forward for wg-easy (and any other port forwards you may have for apps on the TrueNAS server) after these changes, as the mac address changes with the creation of the bridge (i.e. its the bridge mac address now).

You should now have access to the VMs and Apps using the host network interface through the VPN.

Let me know if you find something else out that may help others and I’ll add it to the list.

 

[help!]

Hi mate! ive tried all day, Ive followed this from the stat several times and I cant get external access, I have set up wireguard on my router and it works absolutley fine from outside network, vi motbile hotspot,

I've tried tail scale too

totally stuck

 

[Black_Duck]

*** Updated 04/11/2023 ***
Some suggested debugging procedures:
How WireGuard works: The wg-easy config defines the router Domain Name (or IP address) (and port). This is then set in the profile you create for a client (through the wg-easy interface). You then load that profile to your client computer. When you start WireGuard on your client computer, it establishes a link to your router using external IP and port in the profile. The router then forwards that connection to the TrueNAS server (using port forwarding). TrueNAS then forwards it to WireGuard based on the port. That establishes the encrypted "tunnel" between your WireGuard client and WireGuard server (on TrueNAS) using the encryption keys in the profile. Wireguard then sets up a subnet (10.8.0.x) between the client and the server over the tunnel. The Iptable "Masquerade" entry establishes a (NAT) link between this lan (10.8.0.x) and your lan (192.168.1.x).

Debugging: There's multiple possible failure points, so the first step is to determine if the problem is before you get to WireGauard or after.

1. When you try to use the VPN from outside your lan, does the connection show up in the wg-easy webUI? Is there traffic on the connection?
   1. No: The problem is between your client and your WireGuard server. Start from the client and work forward.
      • Incorrect profile in the client. Check you have the correct Domain Name/IP address for your router in the app config. Specifically that the "Endpoint" is [your.domain.name]:51820
      • DDNS not working. Can you ping your router using the DDNS name from outside your network?
      • Incorrect Port Forward on your router. This is the most common issue. Make sure you are forwarding to the your TrueNAS IP address and your port numbers are correct in your router.
      • Confirm the route from your port forward to your TrueNAS. Can you access Truenas from inside your lan?
   2. Yes: The problem is inside WireGuard or the route tables to your lan.
      1. Can you access the Truenas WebUI through the VPN?
         1. Yes: problem is most likely you have the wrong Network Interface specified in the route tables
            • Go into the wg-easy shell and issue the following commands: "iptables -L -v -t nat".
            • Output should be something like:
              
              
            • Note that the "out" should be your Network Interface (see 3 in guide above). Also check "source".
         2. No: app config error or route table error
            • Go into the wg-easy shell and issue the following command "iptables -L -v"
            • 
              • Check you have correct UDP port in the INPUT rule
              • Check you have a FORWARD from any to wg0 and from wg0 to any

If you are having issues accessing some Apps or Virtual Machines, you need to set up a bridge. See the instructions above.

 

[help!]

That is only for here at home to check its working, the offsite location does not have a custom router like i have, and i would like to be able to log into the other locations router if anything does wrong, for this a vpn would be my first choice rather thn buying new hardware to facilitate the connection The vpn feature of TNS would be much prefeered, i wil try all this now thank yoy very much for your repy

 

[help!]

i can access my wireguard UI and through the vpn i can connect and get the true nas ui but no internet of any kind outide the things inside lan

and the ehternet adapter is the same one shown in true nas's UI

still no internet though

 

[help!]

actually none of this was here in chain packets 3314 384K


its just 0

 

[help!]

interstingly i cant get access to my nas network gui from my phone , so i can on my laptop, but on the phone which is essentialy out of the network at that point, there is 0 access

 

[Black_Duck]

actually none of this was here in chain packets 3314 384K


its just 0

This tells you the number of packets going thought the rule. It means that no traffic is going through your Network Interface, which is consistent to no access to the internet.
Can you share your iptables output?

 

[help!]

Hmm I might have to look at the built in ssd function and then replicate over it, going around in circles here, also i went straight to cobia for this new build not knowing that my datasets once upgraded cant be from what ive read or tried t oinnitiate, my pools are invisible to stable version now, and there all set up in their way now, i will loose ev erything and have to reinnitialise to be on stable

is this correct no?

as none of my pools are saw as importable

so downgrade is a no,

nightly is too unpredictable vpn seems like a no

is there any way of remote access other than vpn that im not aware of,

i love the design language of true nas love it so im here to stay, i just need offsight backup

im working in ibiza in 9 days so I need my offsight backup, ready one way or another, and I need to organise my music collection and finalise all my songs before the flight as im my taking my MacBook ,

alas my home network has wireguard so i can punch home and get things,


wireguard wont instal on my remote nas as of last night but i was so tired that i must have misssed something simple,


but I would love offsigh backups to work as i dont want an accednet to cause loss while im working away

 

[tehn00bi]

Hey I really appreciate your write up. I finally got this working.

 

[hiiiroller]

Stuck as well. =(

 

[hiiiroller]

Nevermind, I found the issue. For some reason my router was forwarding IPv6 and not IPv4. Now it’s working fine. Thanks for guide!

 

[Black_Duck]

Nevermind, I found the issue. For some reason my router was forwarding IPv6 and not IPv4. Now it’s working fine. Thanks for guide!

Glad to hear its all working.
By the way, not necessary, but implementing step 4 in the guide would eliminate the duplicate entries in your route tables.

 

[hiiiroller]

Glad to hear its all working.
By the way, not necessary, but implementing step 4 in the guide would eliminate the duplicate entries in your route tables.

Ahh, nice! Thanks! Was so excited to get it working the I forgot to finish up the steps. Thank you!

 

[rvega]

Hey...thanks a lot for the guide!! Almost everything working perfectly.

Only missing thing is to be able to access the VMs I run. I have 2 VMs, one running AgentDVR (the one I'd really like to be able to access from the outside world) and another with some other services (Adguard / heimdall / . I can access TrueNAS GUI no problem. But there is no access to these other machines.

Any hints?

 

[tehn00bi]

Hey I really appreciate your write up. I finally got this working.

Edit, for some reason a few days later it stopped working, I've been trying to read up on what could have gone wrong, fortunately the troubleshooting post above talked about port forwarding. I know I set my router to port forward earlier, but I guess it mysteriously forgot that setting. Anyway, I fixed my port forwarding and it's back up and working. Thanks again.

 

[help!]

I found when i set up a few servers on my network it stopped working for some reason . delete all unneeded servers and just use one, reboot everything try again

hood luck , and

Glad to hear its all working.
By the way, not necessary, but implementing step 4 in the guide would eliminate the duplicate entries in your route tables.

also mate chees for the guide too mat you have been a great help

 

[Black_Duck]

Edit, for some reason a few days later it stopped working, I've been trying to read up on what could have gone wrong, fortunately the troubleshooting post above talked about port forwarding. I know I set my router to port forward earlier, but I guess it mysteriously forgot that setting. Anyway, I fixed my port forwarding and it's back up and working. Thanks again.

Checking if you are connected to wireguard through the webUI quickly determines if the problem is upstream (network problem - port forwarding, DDNS issues, IP address issues), or downstream (usually wg-easy config problem, wrong NIC name, etc..)

 

[Black_Duck]

Hey...thanks a lot for the guide!! Almost everything working perfectly.

Only missing thing is to be able to access the VMs I run. I have 2 VMs, one running AgentDVR (the one I'd really like to be able to access from the outside world) and another with some other services (Adguard / heimdall / . I can access TrueNAS GUI no problem. But there is no access to these other machines.

Any hints?

Although I don't use VMs, I do have adguard running in a docker container using an external interface with a static IP address and I've noted that I can't get to adguard webUI from the VPN. I'd always assumed its because adguard is basically IP aliasing (i.e through the same NIC) that wireguard is using. VMs would have the same issue as they are also IP aliasing.
However, your comment got me thinking and I installed Ubuntu in a VM and I can access the agduard webUI from Ubuntu. In fact it's even using Adguard as my DNS. Clearly IP Aliasing is not the issue. I will look into this in the next few days.
Note you should be able to access other IP addresses on the network (e.g your router). Problem appears to be only accessing IP addresses on the same NIC.

 

[NugentS]

Could it be that you need to setup a bridge to allow VM's & Apps to get access to TN assets?