This is a text-only version of the following page on https://raymii.org:

This is a text-only version of the following page on https://raymii.org:
---
Title : Personal Wireguard VPN on a Freedombox with Debian
Author : Remy van Elst
Date : 03-02-2020
URL : https://raymii.org/s/tutorials/Wireguard_VPN_on_Freedombox.html
Format : Markdown/HTML
---

This guide will show you how to set up a personal [Wireguard][4] VPN server on Debian
or Ubuntu with [Freedombox][3]. Freedombox will be used to manage the VPN software,
firewall and users. Wireguard is a relatively new VPN built in to the linux
kernel. Freedombox is a long running project under the Debian umbrella providing
a private server for non experts with focus on user freedom, ease of use and
privacy.

Combined, those two make a great pair. In the past I've [written many articles][5]
on how to setup your own personal VPN server, but those all required manual setup
and maintenance. With freedombox, the updates are automatic and the management
is hidden away behind a convenient web interface.

This personal VPN server can be used to secure your internet connection when on
the road but also to get secure access to your home network while away.

I have this setup running at home on a [Freedombox Pioneer edition][11], very
nice hardware supported and endorsed by the Freedombox Foundation.

If you want to setup everything by hand and not use a web ui, the [debian wiki][10]
has a great guide. If you want to install [Freedombox on your Pioneer, read this][2].

 Recently I removed all Google Ads from this site due to their invasive tracking, as well as Google Analytics. Please, if you found this content useful, consider a small donation using any of the options below: <a href="https://leafnode.nl">I'm developing an open source monitoring app called Leaf Node Monitoring, for windows, linux & android. Go check it out!</a> <a href="https://github.com/sponsors/RaymiiOrg/">Consider sponsoring me on Github. It means the world to me if you show your appreciation and you'll help pay the server costs.</a> <a href="https://www.digitalocean.com/?refcode=7435ae6b8212">You can also sponsor me by getting a Digital Ocean VPS. With this referral link you'll get $100 credit for 60 days. </a> 

Quoting the Freedombox website:

> [FreedomBox][3] is a private server for non-experts: it lets you install and
configure server applications with only a few clicks. It runs on cheap hardware
of your choice, uses your internet connection and power, and is under your
control.

Quoting the Wireguard website:

> [WireGuard][4] is an extremely simple yet fast and modern VPN that utilizes
state-of-the-art cryptography. It aims to be faster, simpler, leaner, and more
useful than IPsec, while avoiding the massive headache. It intends to be
considerably more performant than OpenVPN. WireGuard is designed as a general
purpose VPN for running on embedded interfaces and super computers alike, fit
for many different circumstances. Initially released for the Linux kernel, it is
now cross-platform (Windows, macOS, BSD, iOS, Android) and widely deployable. It
is currently under heavy development, but already it might be regarded as the
most secure, easiest to use, and simplest VPN solution in the industry.

Freedombox has support for [Wireguard since version 20.1][1]. This includes a
grahpical interface to setup and manage Wireguard including user management.

This guide will assume you use a new server which is not in use for anything
else. I use Debian in this guide and include instructions on upgrading to
Debian testing, but it should work on a recent Ubuntu as well. At the time of
writing the `wireguard` package is available only in [Ubuntu 19.10][6] and up (including
the upcoming [20.04 LTS][7].) On Debian the current stable (10/buster) also does
not contain wireguard, but `testing` and `unstable` [do have it.][8]

Since this is still all relatively new, you might experience issues. OpenVPN is
a stable alternative, if you want to go the Freedombox route, that will work
on Debian Stable (10) and Ubuntu LTS (18.04).

The guide first lets you install Freedombox, after that update the entire distro to
`testing` and finaly install wireguard. This order makes sure that Freedombox is
correctly installed and working before we go into uncharted areas (debian testing).

### Install Freedombox

The installation of Freedombox is very easy because all the software is in the
debian repositories. I do assume you use a new, clean server for this since
Freedombox makes many changes to your system including network, firewall and
user management.

Use the following command to install Freedombox and go get
a cup of tea or coffee, it might take a while:

DEBIAN_FRONTEND=noninteractive apt-get install ssl-cert freedombox

In [my other guide][2] on installing Freedombox on the Pioneer Olimex ARM board
I figured out that the extra package is required to start up the webserver.

Navigate to the IP and domainname of your server and follow the instructions.
The web interface is available via `https://your-server/plinth` and will ask
for a secret. That secret can be found with the following command:

cat /var/lib/plinth/firstboot-wizard-secret

![freedombox first screen][9]

When the installation and user setup are finished, you are greeted with a nice
screen suggesting to install apps. Wait a little bit since we're first going to
upgrade the operating system.

### Upgrading debian 10 to testing

The current debian 10 version does not have the `wireguard` package. It is in
debian testing and in unstable. For this guide I'll assume you want to experiment
a bit thus we will upgrade a 'normal' debian 10 instance to debian testing.

I do not recommend doing this to an existing system. Create a [new VPS][99] over
at Digital Ocean (referal link) to test this. I do only have positive
experiences with running Debian testing, but generally I know what I'm doing
with unstable linux systems. If you need a stable system, wait until wireguard
is in Debian.

If you're running Ubuntu 19.10 or higher, the wireguard package is available and
you must make sure that you have Freedombox 20.1 or higher.

Create a backup of your sources.list file:

cp /etc/apt/sources.list /etc/apt/sources.list.bak

Overwrite your sources.list file to only include the testing repositories:

echo 'deb http://deb.debian.org/debian/ testing main contrib non-free' > /etc/apt/sources.list
echo 'deb http://deb.debian.org/debian/ testing-updates main contrib non-free' >> /etc/apt/sources.list
echo 'deb http://deb.debian.org/debian-security testing-security main' >> /etc/apt/sources.list

Upgrade to Debian testing:

apt-get update
DEBIAN_FRONTEND=noninteractive apt-get -y dist-upgrade

Remove any leftovers:

DEBIAN_FRONTEND=noninteractive apt-get autoremove

Reboot your system:

reboot

### Setup Wireguard via Freedombox

Once the update is finished, login to your freedombox again and open the `Apps`
page via the menu. Scroll down and the `wireguard` button should be visible:

![wireguard button][12]

Click the button. On the next page, click the Install button:

![wireguard page][13]

The installation should now start:

![wireguard installation][14]

It does not take long to install wireguard, when the setup is finished the screen
looks like the below image:

![wireguard config page 1][15]

Wireguard pulls in a kernel module via DKMS so make sure you reboot after installing
wireguard:

reboot

Otherwise, you will get errors in the log like below:

Failed to create WireGuard interface 'wg0' for 'WireGuard-Server-wg0':
Operation not supported

That's all there is to the installation.

There is one more step you need to do to get connected and that is to setup
clients. Wireguard requires a client certificate, otherwise it won't allow
connections. You generate a keypair for a client, then configure that client.
This guide has an example for the official [Wireguard android app][16]/

### Android

Installation and configuration on Android involves a bit of back and forth between
the application and the webinterface. Both parties, the mobile and the server,
need one anothers public keys, so be prepared to copy paste (or mail) a few
strings here and there.

Install the [Wireguard app][16] from the play store or via [F-Droid][17].

Open the application and start the configuration with the big blue `+` button.

Choose `Create from scratch`

The first part, under `Interface` is all locally on your device. Enter a name and
click `Generate` for the private key. The public key is derived. Leave the address
and DNS fields empty for now.

![android 1][22]

Save your public key and make sure you can copy-paste it on your computer.

On the freedombox, click `Add allowed client`

![wireguard config page 2][18]

Enter the public key generated on your phone:

![wireguard config page 3][19]

The server now gives you more information, namely the IP it will assign and the
public key.

On Android, edit the configuration again and enter the IP address provided by the
freedombox:

![android 2][23]

Save the configuration, edit it again and click the big blue `Add peer` button.
There you will fill in the configuration regarding the server.

Enter the servers public key and fill in it's IP or hostname under `Endpoint`,
including the port number, for example: `51.15.42.206:51820`.

Under `Allowed IP's` enter the following:

0.0.0.0/0, ::/0

This will forward all traffic to the wireguard server.

Save and enable the connection. You should see an extra item `Transfer` in the list
which shows the amount of traffic via the VPN. If both `rx` and `tx` go up, the
VPN works. If only `tx` goes up, check if you rebooted your server after installing
wireguard. The kernel module might not be loaded and the network interface `wg0`
might not be there.

![android 3][24]

This is the server showing a successfull connection:

![wireguard config page 3][21]

Here is an image of the browser on my mobile phone showing the external IP address
of the VPN server:

![android 4][25]

Do note that all private keys and IP addresses shown in this article were only
used for testing and are not active anymore.

[1]: https://wiki.debian.org/FreedomBox/Manual#FreedomBox.2FReleaseNotes.FreedomBox_20.1_.282020-01-27.29
[2]: /s/tutorials/Installing_Freedombox_On_Armbian_On_The_Olimex_A20_Pioneer.html#toc_2
[3]: https://freedombox.org/
[4]: https://www.wireguard.com/
[5]: https://raymii.org/s/tutorials/IPSEC_vpn_with_Ubuntu_16.04.html
[6]: https://packages.ubuntu.com/eoan/wireguard
[7]: https://packages.ubuntu.com/focal/wireguard
[8]: https://packages.debian.org/search?searchon=names&keywords=wireguard
[9]: /s/inc/img/freedombox-setup.png
[10]: https://wiki.debian.org/Wireguard
[11]: https://freedombox.org/buy/
[12]: /s/inc/img/fdb-wg1.png
[13]: /s/inc/img/fdb-wg2.png
[14]: /s/inc/img/fdb-wg3.png
[15]: /s/inc/img/fdb-wg4.png
[16]: https://play.google.com/store/apps/details?id=com.wireguard.android
[17]: https://f-droid.org/en/packages/com.wireguard.android/
[18]: /s/inc/img/fdb-wg6.png
[19]: /s/inc/img/fdb-wg7.png
[20]: /s/inc/img/fdb-wg8.png
[21]: /s/inc/img/fdb-wg9.png
[22]: /s/inc/img/fdb-a-1.png
[23]: /s/inc/img/fdb-a-2.png
[24]: /s/inc/img/fdb-a-3.png
[25]: /s/inc/img/fdb-a-4.png

---

License:
All the text on this website is free as in freedom unless stated otherwise.
This means you can use it in any way you want, you can copy it, change it
the way you like and republish it, as long as you release the (modified)
content under the same license to give others the same freedoms you've got
and place my name and a link to this site with the article as source.

This site uses Google Analytics for statistics and Google Adwords for
advertisements. You are tracked and Google knows everything about you.
Use an adblocker like ublock-origin if you don't want it.

All the code on this website is licensed under the GNU GPL v3 license
unless already licensed under a license which does not allows this form
of licensing or if another license is stated on that page / in that software:

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.

Just to be clear, the information on this website is for meant for educational
purposes and you use it at your own risk. I do not take responsibility if you
screw something up. Use common sense, do not 'rm -rf /' as root for example.
If you have any questions then do not hesitate to contact me.

See https://raymii.org/s/static/About.html for details.