View source for Matrix Synapse and mautrix-whatsapp in a VPN

'''WhatsApp''' is a popular communication app for Android and iOS. It is owned by Facebook, which has a hostile attitude towards alternative clients and open source software, along with [https://stallman.org/facebook.html being notorious for its egregious privacy violations (and de-facto support of white supremacy and fascism)]. It stands to reason, then, that WhatsApp is not an app that any privacy-conscious individual should want to have installed on their mobile phone, which typically holds a vast quantity of personal data. However, the unfortunate truth is that it tends to be virtually impossible for many of us to stop using WhatsApp without permanently losing contact with several friends, family members, clients or colleagues. Thus, one may seek to find a middle ground: keeping WhatsApp well away from one's personal devices, but somehow still connecting to its network using these devices. Given Facebook's hostile attitude to third-party clients, one might expect such a task to be impossible... or is it?

'''Enter the Matrix.''' [https://matrix.org/ Matrix] is a free (as in speech), feature-rich decentralised communication ecosystem that can serve as a platform for instant messaging, e.g. using [https://www.element.io/ Element] as a client. Although I would highly encourage switching from WhatsApp to Element whenever possible, it turns out Matrix is in fact capable of communicating with the WhatsApp network. This is done using [https://github.com/tulir/mautrix-whatsapp mautrix-whatsapp], which masquerades as a WhatsApp Web client and uses it to communicate with the actual WhatsApp client running on a phone or emulator.

'''A note:''' this guide is essentially an amalgamation of the most relevant bits of various other guides: [https://wiki.debian.org/OpenVPN the Debian OpenVPN guide], [https://openvpn.net/community-resources/how-to/#installing-openvpn the OpenVPN community installation guide], [https://www.natrius.eu/dokuwiki/doku.php?id=digital:server:matrixsynapse the Synapse installation guide by '''natrius'''], the [https://gist.github.com/marcopaganini/0823d31d43557f9711e21b43a3223fce Nginx/TLS reverse proxy guide by '''Marco Paganini'''], [http://blog.hoxnox.com/inet/ssl_nginx.md.html the Nginx/easy-rsa guide by '''hoxnox'''], and the [https://github.com/tulir/mautrix-whatsapp/wiki/Bridge-setup official mautrix-whatsapp bridge setup guide by '''Tulir Asokan''']. These individual guides explain their steps in greater depth than I do here, and I highly, highly recommend reading through all of them before tackling a project like this one. '''Also be very aware that I am not an expert in any of this. If you need enterprise-grade security, close this browser tab now and consult an actual expert.''' That said, I have made an honest attempt to hammer down any security holes I could think of, and I am presently running this set-up myself.

=The set-up=
[[File:Mautrix-whatsapp-setup-pathified.svg]]

This guide will explain one possible configuration to use WhatsApp from a Matrix client. In this configuration, a Matrix homeserver (Synapse) and mautrix-whatsapp will be installed on a (virtual) private server, along with OpenVPN. The setup is completely contained within the virtual private network (VPN) created by OpenVPN, and does not require any entrypoints from the outside world except through the VPN (although you may want to enable SSH access for setup and administration). It therefore has a high degree of inherent security. A reverse HTTPS proxy is set up using Nginx with certificates generated by easy-rsa: this is necessary for some clients to be able to connect.

<code>iptables</code> is used for setting up routing and firewalling of the server, and only IPv4 is considered for the time being. I wish to ''eventually'' migrate to <code>nftables</code> and a dual IPv4/IPv6 stack, however this will take more time and effort than I have available, especially considering the current setup "just works" for me.

This guide is primarily focussed on a "single owner, multiple devices" configuration: extra security precautions should be taken if one wants to allow multiple individuals in the VPN, and using multiple WhatsApp accounts in particular is beyond the scope of this guide.

N.B. it is up to you to decide where WhatsApp (the actual proprietary app) goes in the graphic above: as shown, it is put on the VPS (in an emulator or VM), but it is also possible to leave it off the VPS, e.g. running on a normal phone. Off the VPS, you additionally have the choice of whether you want to route its traffic through the VPN (recommended) or not.

==Requirements==
* A WhatsApp account, and the WhatsApp app running either on a phone or in an emulator on a device with a webcam
* A (virtual) private server ((V)PS) with the following specs:
** A static IPv4 address
** Linux, ideally Debian 10
** root/<code>sudo</code> access
** At least 1 GB RAM
** At least 5 GB disk space for the software and text message storage
** More disk space for the media (videos, etc.) you send and receive
* Decent knowledge of Linux administration
* A free weekend or so to set up, test and tweak everything

The environment used in this guide is a VPS running Debian 10 with full root access; all commands are run as root unless otherwise stated. It is assumed that the VPS is in a fresh-off-the-shelf state with little more than <code>sshd</code> installed and running.

=Step 0: iptables and OpenVPN=
The first and foremost things to get working are the firewall and VPN server. ''Henceforth, we shall use '''192.168.16.0/24''' as the OpenVPN address space, and '''port 1194''' (UDP or TCP) as the OpenVPN port. Take extra care if you want to use something else. We shall use '''123.123.123.123''' as the externally reachable IP of the server; always replace this by whatever the actual address is.''

Log in to your VPS and install iptables as follows:
<syntaxhighlight lang="bash">
apt install iptables iptables-persistent
</syntaxhighlight>

Let us begin by setting up some basic security:
<syntaxhighlight lang="bash" line>
iptables -A INPUT -i lo -j ACCEPT
iptables -A INPUT -s 127.0.0.1/32 -j ACCEPT
iptables -A INPUT -m state --state RELATED,ESTABLISHED -j ACCEPT
iptables -A INPUT -p icmp -m icmp --icmp-type 8 -j ACCEPT
iptables -A INPUT -p icmp -m icmp --icmp-type 11 -j ACCEPT
iptables -A INPUT -p icmp -m icmp --icmp-type 3 -j ACCEPT
iptables -A INPUT -p tcp -m tcp --dport 22 -j ACCEPT
iptables -A INPUT -j DROP
iptables-save >/etc/iptables/rules.v4
</syntaxhighlight>

This will drop all incoming connections apart from SSH and a few ICMP messages. The last line preserves your iptables rules when rebooting.

The next step is to install OpenVPN. The instructions provided here mostly follow [https://wiki.debian.org/OpenVPN Debian's OpenVPN guide]; see that page for more in-depth information. Start by installing the required packages:
<syntaxhighlight lang="bash">
apt install easy-rsa openvpn
</syntaxhighlight>
Next, we create a certificate authority directory in <code>/etc/openvpn</code> and edit the config:
<syntaxhighlight lang="bash" line>
make-cadir /etc/openvpn/easy-rsa
cd /etc/openvpn/easy-rsa
editor vars
</syntaxhighlight>

The <code>vars</code> file has sensible defaults, but you may want to make a few changes (see the inline documentation if you are unsure):
# uncomment the line with <code>set_var EASYRSA_DN    "cn_only"</code>
# set the key size to 4096: <code>set_var EASYRSA_KEY_SIZE      4096</code>
# set the CA validity to something long, like 10 years: <code>set_var EASYRSA_CA_EXPIRE     3650</code>
# set the certificate validity to something similar: <code>set_var EASYRSA_CERT_EXPIRE   3650</code>

After writing the vars file, create the certificate authority, a server certificate and Diffie-Hellman parameters:
<syntaxhighlight lang="bash" line>
./easyrsa init-pki
./easyrsa build-ca
./easyrsa build-server-full server nopass
./easyrsa gen-dh
</syntaxhighlight>
The <code>build-ca</code> step will prompt you for a name and password. The name can be whatever you like, e.g. "My OpenVPN CA". Choose something strong but memorable as the password. Every further interaction with the certificate authority will require this password.

Now create a certificate for every client (desktop, laptop, tablet, mobile phone, refrigerator...) you want to have access to the VPN/your WhatsApp account. It's a good idea to use a file name that allows you to tell these certificates apart, e.g. <code>hostname.n</code>, where <code>hostname</code> is the hostname of the device and <code>n</code> is a number indicating this is the n'th certificate issued for that hostname:
<syntaxhighlight lang="bash" line>
./easyrsa build-client-full alpha.0 nopass
./easyrsa build-client-full bravo.0 nopass
# And so on...
</syntaxhighlight>

Finally, per the [https://openvpn.net/community-resources/how-to/#installing-openvpn OpenVPN community installation guide], generate a shared secret TLS key:
<syntaxhighlight lang="bash" line>
cd /etc/openvpn/easy-rsa/pki/private
openvpn --genkey --secret ta.key
</syntaxhighlight>

Now edit the OpenVPN configuration file:
<syntaxhighlight lang="bash" line>
cd /etc/openvpn
editor server.conf
</syntaxhighlight>

A viable example configuration file follows. See <code>openvpn(8)</code> if it is unclear what an option does. Be sure to save this file as /etc/openvpn/server.conf.
<syntaxhighlight lang="cfg" line>
mode server
# Enable TLS encryption.
tls-server
# Listen on port 1194 (the default).
port 1194
# Set the protocol here. UDP is the default, but it may give you trouble
# connecting on low-quality public Wi-Fi. You can use `proto tcp-server'
# here instead, but note that this causes extra overhead.
# Choose `proto tcp-server' if you want to redirect port 443 to OpenVPN
# to allow connecting over some poorly configured public WiFi networks.
proto udp

# Use TUN device, as opposed to TAP. In 99% of cases, TUN is what you want.
# TAP configuration is outside the scope of this article.
dev tun
# IP pool to be used for OpenVPN. The parameters as given will put the server
# at 192.168.16.1 and clients at addresses up to 192.168.16.255.
server 192.168.16.0 255.255.255.0

# ca.crt file of the certificate authority we just set up.
ca /etc/openvpn/easy-rsa/pki/ca.crt
# Server certificate.
cert /etc/openvpn/easy-rsa/pki/issued/server.crt
# Server private key.
key /etc/openvpn/easy-rsa/pki/private/server.key
# Diffie-Hellman parameters.
dh /etc/openvpn/easy-rsa/pki/dh.pem
# TLS key.
tls-auth /etc/openvpn/easy-rsa/pki/private/ta.key 0

# Timeout parameters for sending pings/restarting OpenVPN. See openvpn(8).
keepalive 20 120
# Enable the following if you want clients to be able to address
# one another directly.
#client-to-client

# Compress the stream with LZO to limit bandwidth.
comp-lzo
# Allow at most 10 clients to connect at the same time.
# Increase if necessary, but make sure your network and server can handle
# the load.
max-clients 10

# Drop root privileges.
user nobody
group nogroup

# Persist keys and TUN device across restarts, since we are dropping root.
persist-key
persist-tun

# Status file.
status /var/log/openvpn-status.log
</syntaxhighlight>

Next, configure the firewall to allow OpenVPN clients. The first step depends on the protocol you chose set in the OpenVPN server configuration. If you chose UDP:
<syntaxhighlight lang="bash">
iptables -I INPUT 1 -p udp -m udp --dport 1194 -j ACCEPT
</syntaxhighlight>
OR, if you chose TCP:
<syntaxhighlight lang="bash">
iptables -I INPUT 1 -p tcp -m tcp --dport 1194 -j ACCEPT
</syntaxhighlight>

Next, set up forwarding and masquerading, and start the server! N.B. it is assumed here that the ethernet device of your server is eth0, and that OpenVPN creates the device <code>tun0</code> (i.e. nothing else sets up a TUN device before OpenVPN). Change tun0 and/or eth0 as necessary if this is not true.
<syntaxhighlight lang="bash" line>
iptables -A FORWARD -i tun0 -j ACCEPT
iptables -A FORWARD -i tun0 -o eth0 -m state --state RELATED,ESTABLISHED -j ACCEPT
iptables -A FORWARD -i eth0 -o tun0 -m state --state RELATED,ESTABLISHED -j ACCEPT
iptables -A POSTROUTING -s 192.168.16.0/24 -o eth0 -j MASQUERADE
iptables-save >/etc/iptables/rules.v4
echo "net.ipv4.ip_forward = 1" >>/etc/sysctl.conf
sysctl -p
systemctl enable openvpn.service
systemctl restart openvpn.service
ifconfig
ss -plunt
</syntaxhighlight>

Make sure OpenVPN starts correctly: <code>ifconfig</code> should show <code>tun0</code>, along with something like <code>inet 192.168.16.1  netmask 255.255.255.255  destination 192.168.16.2</code>. <code>ss -plunt</code> should show <code>0.0.0.0:1194</code> somewhere in the column labelled "Local Address:Port". If this is not the case, check <code>/var/log/daemon.log</code> for entries containing <code>ovpn-server</code>.

You must now copy some certificate files to your clients. As an example, if you have a Linux client named "alpha" and can access your server as root via SSH on 123.123.123.123, run the following commands as root on "alpha" (assuming OpenVPN is already installed):
<syntaxhighlight lang="bash" line>
cd /etc/openvpn
scp 123.123.123.123:/etc/openvpn/easy-rsa/pki/'{ca.crt,issued/alpha.0.crt,private/alpha.0.key,private/ta.key}' .
</syntaxhighlight>

An example of a client configuration file (save as <code>/etc/openvpn/client.conf</code>) is listed below.
<syntaxhighlight lang="cfg" line>
client
dev tun
# Use `proto udp' if that's what the server uses.
# Else use `proto tcp-client'.
proto udp
remote 123.123.123.123 1194
resolv-retry infinite
nobind

user nobody
group nobody
persist-key
persist-tun

ca /etc/openvpn/ca.crt
cert /etc/openvpn/alpha.0.crt
key /etc/openvpn/alpha.0.key

ns-cert-type server

tls-auth /etc/openvpn/ta.key 1

comp-lzo

# Uncomment the following if you want to redirect all client traffic through
# the VPN. (Without it, only 192.168.16.0/24 will be routed through the VPN.)
#redirect-gateway def1
</syntaxhighlight>

On "alpha", run <code>openvpn --config /etc/openvpn/client.conf</code> and check if it will connect. Running <code>ifconfig</code> on "alpha" should show a <code>tun0</code> with an IP in 129.168.16.0/24 and a destination of 192.168.16.1. You should be able to SSH over the VPN too, using
<syntaxhighlight lang="bash">
ssh root@192.168.16.1
</syntaxhighlight>

If this connects, your VPN works and you're done with this step!

=Step 1: PostgreSQL and Synapse=
Synapse is the name of the Matrix homeserver reference implementation, which we will be installing in this section. This procedure loosely follows [https://www.natrius.eu/dokuwiki/doku.php?id=digital:server:matrixsynapse the guide by '''natrius'''], with some key differences:
# We will thoroughly disable federation.
# We will use easy-rsa to add self-signed certificates to the Nginx reverse proxy.
# We will use <code>iptables</code> instead of <code>ufw</code>.

Before installing Synapse, first install PostgreSQL and its Python binding:
<syntaxhighlight lang="bash">
apt install postgresql python3-psycopg2
</syntaxhighlight>

Now <code>su</code> to the PostgreSQL admin account and start the PostgreSQL shell:
<syntaxhighlight lang="bash" line>
su - postgres
psql
</syntaxhighlight>

As in natrius' guide, create the synapse database and a user to own it:
<syntaxhighlight lang="sql" line>
CREATE USER "synapse" WITH PASSWORD 'password';
CREATE DATABASE synapse ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' template=template0 OWNER "synapse";
\q
</syntaxhighlight>
Replace 'password' with a strong, ideally random password. That's all that's needed as far as PostgreSQL goes, so log out of the <code>postgres</code> account.

As in the aforementioned guide, first add the relevant repositories and perform any necessary updates, and then install Synapse:
<syntaxhighlight lang="bash" line>
apt install lsb-release wget apt-transport-https
wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/matrix-org.list
apt update && apt upgrade
apt install matrix-synapse-py3
</syntaxhighlight>

When asked for a hostname, enter <code>localhost</code>. Next, edit the configuration file, <code>/etc/matrix-synapse/homeserver.yaml</code>. In the <code>listeners</code> section, change the uncommented lines to the following:
<syntaxhighlight lang="yaml" line>
  - port: 8008
    tls: false
    type: http
    x_forwarded: true
    bind_addresses: ['0.0.0.0']

    resources:
      - names: [client]
        compress: false
</syntaxhighlight>
That is, we bind 0.0.0.0 (to listen to the whole network for client connections) and remove federation.

We will be even more thorough in disabling federation: search for <code>federation_domain_whitelist</code>, which (for the Debian 10 configuration file of Synapse 1.23) should be a commented line with a few domains under it. Add a new line after that comment section:
<syntaxhighlight lang="yaml">
federation_domain_whitelist: []
</syntaxhighlight>

Next scroll down to <code>federation_ip_range_blacklist</code> and remove the IPs underneath that line. Replace them with the IPv4 and IPv6 catchalls:
<syntaxhighlight lang="yaml" line>
  - '0.0.0.0/0'
  - '::/0'
</syntaxhighlight>

With federation now thoroughly disabled, look for <code>enable_registration: false</code> and uncomment this line. As in natrius' guide, look for <code>registration_shared_secret: <PRIVATE STRING></code>, uncomment it, and replace <code><PRIVATE STRING></code> with a long, randomly generated alphanumeric string, e.g. generated by the command
<syntaxhighlight lang="bash">
cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1
</syntaxhighlight>

Write out the configuration file and exit your editor. We now need to open port 8008 to VPN clients:
<syntaxhighlight lang="bash" line>
iptables -I INPUT 1 -s 192.168.16.0/24 -i tun0 -p tcp -m tcp --dport 8008 -j ACCEPT
iptables-save >/etc/iptables/rules.v4
</syntaxhighlight>

Now start Synapse and check if it is running:
<syntaxhighlight lang="bash" line>
systemctl start matrix-synapse.service
ss -plunt
</syntaxhighlight>

The last command should show that Synapse is listening on port 8008.

You can now create an account on your homeserver:
<syntaxhighlight lang="bash">
register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml http://localhost:8008
</syntaxhighlight>
This will prompt for a username and password, as well as the shared secret you entered into the configuration file earlier.

If you have a PC or laptop that you've given access to the VPN, you can install the '''desktop''' [https://element.io/get-started Element] client on it. You should then be able to connect to <code>http://192.168.16.1:8008</code> using the account you just created. At this moment, the Android and Web clients do NOT support HTTP connections, so these clients cannot connect to your Synapse installation yet. Which brings us to...

=Step 2: Nginx and TLS=
To allow most clients to connect to your homeserver (provided they have access to the VPN), you will need to set up a reverse proxy that adds a TLS layer so they can communicate over HTTPS. While the Synapse guide by natrius recommends Let's Encrypt certificates, in a fully private context like we are considering, it makes sense to set up your own certificate authority.

I opted to build a new certificate authority in the Synapse configuration directory and reuse the configuration I picked for OpenVPN:
<syntaxhighlight lang="bash" line>
make-cadir /etc/matrix-synapse/easy-rsa
cd /etc/matrix-synapse/easy-rsa
cp /etc/openvpn/easy-rsa/vars .
./easyrsa init-pki
./easyrsa --subject-alt-name="IP:192.168.16.1" build-ca
# Choose a new CA name when prompted. The password you are prompted for
# should ideally also be different from the one you used for OpenVPN.
./easyrsa --subject-alt-name="IP:192.168.16.1" build-server-full matrix-synapse nopass
# For all clients:
./easyrsa --subject-alt-name="IP:192.168.16.1" build-client-full alpha.0 nopass
./easyrsa --subject-alt-name="IP:192.168.16.1" build-client-full bravo.0 nopass
# ...and so on
</syntaxhighlight>

Note that we are now including <code>--subject-alt-name="IP:192.168.16.1"</code> in our commands. HTTPS requires certificates to be bound to a domain or IP, and browsers tend to get ornery if they are not. We do not need Diffie-Hellman parameters now, but we do need to generate a certificate revocation list so Nginx will be able to reject revoked certificates, and we must also export our client certificates in a format browsers and mobile OSes understand:
<syntaxhighlight lang="bash" list>
# For all clients:
./easyrsa export-p12 alpha.0
./easyrsa export-p12 bravo.0
# ...and so on
./easyrsa gen-crl
</syntaxhighlight>
The export step asks you to provide a password, which allows you to securely transport the exported certificates to the clients they are to be installed on.

Next up, Nginx. Install the package, remove the default configuration, and create a new one:
<syntaxhighlight lang="bash" line>
apt install nginx
systemctl stop nginx.service
unlink /etc/nginx/sites-enabled/default
ln -s /etc/nginx/sites-available/synapse /etc/nginx/sites-enabled/synapse
editor /etc/nginx/sites-available/synapse
</syntaxhighlight>

An example configuration that sets up an HTTPS reverse proxy on port 10443 is
given below.
<syntaxhighlight lang="nginx" line>
server {
    listen 10443 ssl;
    server_name localhost;

    ssl on;
    ssl_certificate /etc/matrix-synapse/easy-rsa/pki/issued/matrix-synapse.crt;
    ssl_certificate_key /etc/matrix-synapse/easy-rsa/pki/private/matrix-synapse.key;
    ssl_client_certificate /etc/matrix-synapse/easy-rsa/pki/ca.crt;
    ssl_crl /etc/matrix-synapse/easy-rsa/pki/crl.pem;
    # Enable mutual TLS. This option provides maximal security by requiring
    # per-client certificates. Unfortunately, client-side support for this
    # tends to be shaky at best, so turn it off and restart Nginx if you are
    # not able to connect.
    ssl_verify_client on;

    access_log /var/log/nginx-synapse-access_log.log;
    error_log /var/log/nginx-synapse-error_log.log;

    # There is no need to serve files, and we will not be using
    # .well-known, since we don't use federation. So we just reverse-proxy
    # Synapse's HTTP at the root and that's it.
    location / {
        proxy_pass http://127.0.0.1:8008;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}
</syntaxhighlight>

Now unblock port 10443 for the VPN and start Nginx:
<syntaxhighlight lang="bash" line>
iptables -I INPUT 1 -s 192.168.16.0/24 -i tun0 -p tcp -m tcp --dport 10443 -j ACCEPT
iptables-save >/etc/iptables/rules.v4
systemctl enable nginx.service
systemctl start nginx.service
# Check if it's running
ss -plunt
</syntaxhighlight>

The last command should show Nginx listening on port 10443. Now copy <code>/etc/matrix-synapse/easy-rsa/pki/ca.crt</code> to all clients and import it as a trusted system certificate. Also copy each <code>p12</code> certificate in <code>/etc/matrix-synapse/easy-rsa/pki/private/</code> to its respective client and import it.

The desktop and android apps should now be able to at least communicate with the server via HTTPS at <code>https://192.168.16.1:10443</code>. If, however, you get an error stating the client did not send the correct certificate, you may have to disable <code>ssl_verify_client</code> in the Nginx configuration file and restart Nginx. Note that the canonical Element-web implementation at app.element.io may not be able to talk to your server regardless; I believe this is because browsers will restrict accessing local networks from sites loaded from remote servers. Installing element-web locally will help; see Optional Extras at the end of this guide.

=Step 3: mautrix-whatsapp=
Being a rather niche package, mautrix-whatsapp is not in the Debian repositories and must be self-compiled. It also has some dependencies on versions of packages too recent to be found in the repositories of Debian 10 (buster)

First and foremost, version 1.14 of Go (<code>golang-1.14</code>) is needed at the time of writing, which has been backported to buster. If you are running buster, install Go as follows:
<syntaxhighlight lang="bash" line>
echo 'deb http://deb.debian.org/debian buster-backports main' >>/etc/apt/sources.list
apt update
apt install -t buster-backports golang
</syntaxhighlight>

Alternatively, if you are using Debian 11 (bullseye) or Unstable (sid), simply install golang directly:
<syntaxhighlight lang="bash">
apt install golang
</syntaxhighlight>

Regardless of your Debian version, you will need to install <code>ffmpeg</code>, a GNU toolchain, and <code>git</code>, if they are not already installed:
<syntaxhighlight lang="bash">
apt install ffmpeg make autoconf automake libtool gcc cmake git
</syntaxhighlight>

Next, we need to install a very recent version of <code>olm</code>, which must be hand-compiled at the time of writing. It is probably best to perform the following steps as a regular user instead of root, but I couldn't be bothered creating a new user. Caveat emptor.
<syntaxhighlight lang="bash">
cd
git clone https://gitlab.matrix.org/matrix-org/olm.git
cd olm
cmake . -Bbuild
cd build
make
# if you dropped root, use `sudo make install' here instead
make install
</syntaxhighlight>

We are now ready to compile mautrix-whatsapp. The following steps may also be executed as a regular user if you want. Clone the repo and compile:
<syntaxhighlight lang="bash" line>
cd
git clone https://github.com/tulir/mautrix-whatsapp.git
cd mautrix-whatsapp
export LD_LIBRARY_PATH=/usr/local/lib
./build.sh
# Only execute the following if you executed the above as a regular user
cd ..
sudo cp -r mautrix-whatsapp /root/mautrix-whatsapp
</syntaxhighlight>

Again as root, copy <code>/root/mautrix-whatsapp/example-config.yaml</code> to <code>/root/mautrix-whatsapp/config.yaml</code> and edit the latter.
* Under <code>homeserver</code>, set <code>address</code> to <code>http://localhost:8008</code> and <code>domain</code> to <code>localhost</code>.
* Under <code>appservice</code>, set <code>hostname</code> to <code>127.0.0.1</code>.
* Under <code>database</code> (in the <code>appservice</code> section), set <code>type</code> to <code>postgres</code> and <code>uri</code> to <code>postgres://synapse:<password>@localhost/synapse?sslmode=disable</code>, where <code><password></code> should be replaced with the PostgreSQL password you picked earlier.
* Under <code>bridge</code>, set <code>private_chat_portal_meta</code> to <code>true</code>.

The <code>permissions</code> block under <code>bridge</code> should be something like this:
<syntaxhighlight lang="yaml" line>
    permissions:
        "*": relaybot
        "localhost": user
        "@alice:localhost": admin
</syntaxhighlight>
Here <code>alice</code> should be replaced with the username you chose when issuing the <code>register_new_matrix_user</code> command in Step 1.

Finally, set <code>directory</code> under <code>logging</code> to something more suitable, like <code>/var/log/mautrix-whatsapp</code>.

Now generate the appservice registration file, copy it to the Synapse configuration directory, and change its ownership so Synapse can read it:
<syntaxhighlight lang="bash" line>
cd /root/mautrix-whatsapp
export LD_LIBRARY_PATH=/usr/local/lib
./mautrix-whatsapp -g
cp registration.yaml /etc/matrix-synapse/wa_registration.yaml
chown matrix-synapse /etc/matrix-synapse/wa_registration.yaml
</syntaxhighlight>

Edit <code>/etc/matrix-synapse/homeserver.yaml</code>. Find the line with <code>app_service_config_files</code> (which is commented out) and, below the comment, add
<syntaxhighlight lang="yaml" line>
app_service_config_files:
   - "/etc/matrix-synapse/wa_registration.yaml"
</syntaxhighlight>

Now restart Synapse:
<syntaxhighlight lang="bash">
systemctl restart matrix-synapse.service
</syntaxhighlight>

It is now time to test mautrix-whatsapp. For testing purposes, start the bridge in the foreground:
<syntaxhighlight lang="bash">
/root/mautrix-whatsapp/mautrix-whatsapp
</syntaxhighlight>

Connect to your homeserver with Element-Desktop or Element-Android and start a direct chat with <code>@whatsappbot:localhost</code>. You should get a message saying the room has been set up as the bridge management/status room. Type <code>help</code> and send the message. If the bot replies, you're good; if not, check the logs, and check/adjust your configuration carefully and restart Synapse and mautrix-whatsapp.

If all is working, go back to the terminal where you started <code>/root/mautrix-whatsapp/mautrix-whatsapp</code> and terminate the process with Ctrl-C. Now create a new file <code>/etc/systemd/system/mautrix-whatsapp.service</code> and enter the following:
<syntaxhighlight lang="ini" line>
[Unit]
Description=WhatsApp to Matrix bridge
Wants=matrix-synapse.service

[Service]
Type=exec
Environment="LD_LIBRARY_PATH=/usr/local/lib"
WorkingDirectory=/root/mautrix-whatsapp
ExecStart=/root/mautrix-whatsapp/mautrix-whatsapp
Restart=always
RestartSec=10
SyslogIdentifier=mautrix-whatsapp

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

You should now be able to start mautrix-whatsapp using systemd:
<syntaxhighlight lang="bash" line>
systemctl start mautrix-whatsapp.service
systemctl enable mautrix-whatsapp.service
</syntaxhighlight>

Wait a few seconds for mautrix-whatsapp to finish loading, then message <code>help</code> to your bot again to make sure it still works. If it does, send it <code>login</code>, and use the actual (official) WhatsApp client to scan the WhatsApp Web QR code that the bot sends you. It should immediately start pulling a few chats, but most likely not your entire history. Ignore it for now. Open your Element client's settings, go to Help & Advanced, and find your access token. Copy it. Then send the bridge bot <code>login-matrix <access_token></code>, replacing <code><access_token></code> with the access token you just copied. This will enable double puppeting; see [https://github.com/tulir/mautrix-whatsapp/wiki/Authentication the Authentication guide].

If you are not content with the meagre amount of chats/messages pulled by the bot, go into each room it created and send <code>!wa delete-portal</code>. Then go back to your terminal/SSH session and edit <code>/root/mautrix-whatsapp/config.yaml</code> again. In the <code>bridge</code> section, edit these settings:
* <code>initial_chat_sync_count</code> -- this is the amount of WhatsApp group portals that should be created. You probably want to set this to at least the number of WhatsApp groups you're in, including "one-on-one" groups for people you've direct-messaged. If unsure, just pick a number that's definitely larger than that.
* <code>initial_history_fill_count</code> -- this is the amount of old messages that will be fetched. If you have some very active or old rooms, you will need a very large number here. One caveat: mautrix-whatsapp can get a bit wonky if it's syncing a large amount of messages, and may need to be killed and restarted a few times for the process to complete. That means you should also be monitoring the sync process.
* <code>sync_max_chat_age</code> -- this is the age cutoff in seconds for synced messages. Set it to something like 2000000000 (two billion seconds, or roughly 63 years) to effectively disable the age cutoff.
* <code>initial_history_disable_notifications</code> -- this determines whether you get a "new message" notification for every synced old message. If you set <code>initial_history_fill_count</code> to a large number, do yourself a ''huge'' favour and set this to <code>true</code>.

Now restart mautrix-whatsapp:
<syntaxhighlight lang="bash">
systemctl restart mautrix-whatsapp.service
</syntaxhighlight>

Finally, send the bridge bot <code>sync --create-all</code>. It will now start to pull the chats you chose. Bear in mind that this can take a very long time. If you notice it stops making progress, restart mautrix-whatsapp and send <code>sync --create-all</code> again: it will continue at the point it was stopped.

You are now basically done, although you probably still have WhatsApp running on your phone. The next step will explain how to migrate it to a VM.

=Step 4: migrate WhatsApp proper to a VM=
To be added. [https://github.com/tulir/mautrix-whatsapp/wiki/Android-VM-Setup The official guide by '''Alistair Francis'''] should get you quite far.

Caveat: if you do not have access to KVM on your server, you will need to use an ARM AVD in softemu mode. In my experience, Android versions higher than 4.1.x are too slow to be usable. However, 4.1.2 on an emulated Nexus One API 16 (WVGA) in softemu mode can run WhatsApp on a very modest VPS (albeit slowly).

=Step 5: optional extras=
Finally, there are a few things you can do to extend this setup.

==Redirect port 443 to OpenVPN==
Some public Wi-Fi networks only allow access to a very restricted set of ports so clients are limited to web-browsing and checking email. This annoying bit of shit-tier network administration is easily circumvented by piping your traffic through a VPN, which, of course, you just set up -- but you have to be able to connect to the VPN in the first place, and port 1194 (OpenVPN's default port) is practically guaranteed to be blocked by such networks. Luckily, the default HTTPS port, TCP 443, is practically guaranteed to NOT be blocked, so if your OpenVPN server is using TCP, you can just redirect traffic from 443 to 1194 and log in to your VPN on basically any network. ''N.B. switch your OpenVPN over to TCP if you want to do this but chose UDP earlier.''

A few commands are all that's needed:
<syntaxhighlight lang="bash" line>
iptables -A PREROUTING -i eth0 -p tcp -m tcp --dport 443 -j REDIRECT --to-ports 1194
iptables -I INPUT 1 -p tcp -m tcp --dport 443 -j ACCEPT
iptables-save >/etc/iptables/rules.v4
</syntaxhighlight>

You can now use <code>remote 123.123.123.123 443</code> in your client configuration files. Also be sure to add <code>redirect-gateway def1</code> on clients that connect to public Wi-Fi!

==Install element-web==
The official element-web implementation at app.element.io does not work with a private homeserver, but element-web ''will'' work if you install it on your homeserver. '''Note that the authors of element-web specifically recommend against running element-web on the same domain as the homeserver.''' However, as access is limited to the VPN, the risk should be limited as long as only trusted and experienced users are allowed access to the VPN in the first place.

Download the latest release (1.75-rc1 at the time of writing; replace the version as necessary in what follows, obviously) from [https://github.com/vector-im/element-web/releases], extract it, move it to the proper place, and create the config file:
<syntaxhighlight lang="bash" line>
wget https://github.com/vector-im/element-web/releases/download/v1.7.15-rc.1/element-v1.7.15-rc.1.tar.gz
tar -xvzf element-v1.7.15-rc.1.tar.gz
mv element-v1.7.15-rc.1 /var/www/element-web
cd /var/www/element-web
cp config.sample.json config.json
</syntaxhighlight>

Edit <code>config.json</code>. Set <code>"base_url"</code> to <code>"https://192.168.16.1:10443"</code> and <code>"server_name"</code> to <code>"localhost"</code> in the <code>"m.homeserver"</code> block near the top. In the root block, set <code>"disable_custom_urls"</code> to <code>true</code> and <code>"default_federate"</code> to <code>false</code>.

Since we've already set up Nginx, we can just tell it to serve element-web as well, and we can even reuse the certificate authority. Edit the configuration file you created earlier, <code>/etc/nginx/sites-available/synapse</code> and add the following block at the end:
<syntaxhighlight lang="nginx" line>
server {
    listen 10444 ssl;
    server_name localhost;

    root /var/www/element-web;
    index index.html;

    ssl on;
    ssl_certificate /etc/matrix-synapse/easy-rsa/pki/issued/element-web.crt;
    ssl_certificate_key /etc/matrix-synapse/easy-rsa/pki/private/element-web.key;
    ssl_client_certificate /etc/matrix-synapse/easy-rsa/pki/ca.crt;
    ssl_crl /etc/matrix-synapse/easy-rsa/pki/crl.pem;
    ssl_verify_client on;

    access_log /var/log/nginx-element-web-access_log.log;
    error_log /var/log/nginx-element-web-error_log.log;
}
</syntaxhighlight>

If you did not manage to get <code>ssl_verify_client</code> to work earlier, remove that line here too. Also, if you did not use port 443 for OpenVPN, you may use <code>listen 443 ssl;</code> instead of <code>listen 10444 ssl;</code> if you want (so you can just point your browser at https://192.168.16.1). Finally, add an iptables rule to allow connecting from within the VPN, and restart Nginx:
<syntaxhighlight lang="bash" line>
# Replace 10444 with 443 if necessary
iptables -I INPUT 1 -s 192.168.16.0/24 -i tun0 -p tcp -m tcp --dport 10444 -j ACCEPT
iptables-save >/etc/iptables/rules.v4
systemctl restart nginx.service
</syntaxhighlight>

==Block Facebook on clients==
On all clients (except the phone running WhatsApp, if you have not moved it to a VM on the server yet), you can now completely block all Facebook-owned IPs and still retain access to WhatsApp using your Matrix homeserver. While tedious to do by hand (considering Facebook's IP pool grows like an aggressive tumour), it is easily automated on Linux with a cron job and iptables.

First of all, create a new iptables chain that will be used for automated IP blocking, and add it to the front of your INPUT and OUTPUT chains:
<syntaxhighlight lang="bash" line>
iptables -N BLOCK
iptables -I INPUT 1 -j BLOCK
iptables -I OUTPUT 1 -j BLOCK
</syntaxhighlight>

Next, we will create a script that finds the list of IPs owned by Facebook and adds them to the BLOCK chain. N.B. this requires <code>whois</code>, which should be available in any package manager under that name, so install it first if necessary. Then create the file <code>/etc/cron.hourly/ipblock.sh</code> with the following contents:
<syntaxhighlight lang="bash" line>
#!/bin/bash
iptables=/sbin/iptables

$iptables -F BLOCK

asns="AS32934"
for asn in asns
do
    ips="$(whois -h whois.radb.net -- -i origin -T route $asn | grep route: | awk '{print $2}')"
    for i in $ips
    do
        $iptables -A BLOCK -d $i -j REJECT --reject-with icmp-host-unreachable
        $iptables -A BLOCK -s $i -j REJECT --reject-with icmp-host-unreachable
    done
done
</syntaxhighlight>

This script queries whois.radb.net to find all IPs registered under the [https://en.wikipedia.org/wiki/Autonomous_system_(Internet) autonomous system number] AS32934, which is Facebook. You may add other ASNs too if you want. Note that although the list "only" contains 200 entries or so (at the time of writing), they include mask bits in CIDR notation: this list in fact represents tens of thousands of IP addresses, all owned by Facebook.

Make sure to make the script executable, and run it once if you don't want to wait until the next hour for cron to do it.
<syntaxhighlight lang="bash" line>
chmod +x /etc/cron.hourly/ipblock.sh
/etc/cron.hourly/ipblock.sh
iptables-save >/etc/iptables/rules.v4
</syntaxhighlight>

==Honourable mention: Pi-hole==
This is an honourable mention because I will not describe the installation process here and it is not related to mautrix-whatsapp. Nevertheless, as following this guide leaves you with a perfectly usable VPN server, and people reading this are likely to be privacy-conscious, I feel it is worthwhile to link [https://pi-hole.net/ Pi-hole] here. Pi-hole is a very powerful ad-blocking framework acting at DNS level. Like Synapse, you can configure Pi-hole to only be accessible to clients inside your VPN (by allowing only connections from 192.168.16.0/24 on device tun0). On your VPN clients, you can set 192.168.16.1 as your primary DNS server, so all clients are protected from malicious ads when connected to the VPN.

==Honourable mention: Tor proxy==
Your VPS can also serve as a VPN-wide proxy that sends traffic through [https://www.torproject.org/ Tor]. [https://www.marcus-povey.co.uk/2016/03/24/using-tor-as-a-http-proxy/ '''Marcus Povey''' has created a guide on how to set up a Tor proxy with polipo.]

Considering Tor's abysmal transfer speed, you probably don't ''always'' want to redirect traffic over Tor. Most browsers support [https://en.wikipedia.org/wiki/Proxy_auto-config proxy auto-config] (PAC), which allows you to fine-tune which sites get piped through the proxy. For example, the following PAC uses the Tor proxy to handle [https://en.wikipedia.org/wiki/.onion .onion] domains:
<syntaxhighlight lang="javascript" line>
function FindProxyForURL (url, host)
{
    if (shExpMatch (host, "*.onion"))
    {
        return "PROXY 192.168.16.1:8123"
    }
    return "DIRECT;"
}
</syntaxhighlight>

Much more advanced configurations are possible with proxy auto-config, e.g. redirecting all HTTP traffic but not HTTPS, whitelisting/blacklisting domains.