Sections: App Installation; Periodic Scheduling - Systemd, Cron;

PyIA is intended to be run periodically, to first create, and then maintain a VPN connection. Because of this, the installation process consists of two main parts: installing the app and its dependencies, and setting the system up to run it periodically. The instructions below outline the recommended way to install the app in a Python venv, and two options for scheduling the app to run periodically, systemd and cron. Note that the instructions are for a Debian-based system, and while other distros will likely require similar steps, the specific commands may be different.

Basic System Requirement:

• Python 3.9+
• Wireguard
• wg-quick

The first step is to install some system dependencies. The first command below install Python, Pip, Python venv, Git, and Wireguard. The second command first checks for resolvconf, a requirement of the wg-quick script, and if it is not found creates a symlink to resolvectl. This is commonly needed on Debian systems.

sudo apt install python3 python3-pip python3-venv git wireguard
(sudo resolvconf -h &> /dev/null && echo resolfconf present) || \
(sudo ln -s /usr/bin/resolvectl /usr/local/bin/resolvconf  && echo link created)

Then we will clone the repository, create a Python venv, and install the Python dependencies. A venv is recommended as the app needs to run as root to interface with Wireguard, and install Python packages globally as root can lead to broken permissions.

sudo git clone https://github.com/jobymatwick/PyIA.git /opt/PyIA
cd /opt/PyIA
sudo python3 -m venv .
sudo ./bin/pip3 install -r requirements.txt

The last step is creating a configuration file. This is optional and only required if you choose not to set configuration options with command-line arguments or environment variables. For more information on configuration, see the configuration page.

sudo cp config-template.yml config.yml
sudo chmod 600 config.yml
sudo nano config.yml

As mentioned earlier, two methods of scheduling the app to run periodically are described below. Both methods run the app every 15 minutes as root. 15 minutes was chosen because the PIA requires that the port forwarding binding be refreshed every 15 minutes. Note that only one or the other of the options below should be used.

NOTE: The command sudo /opt/PyIA/bin/python3 pyia.py -s can be used to check the status of the connection as well as the last time the connection was maintained. Use it to make sure the app is working properly and the periodic scheduling is working too.

Systemd unit file templates are included in the systemd folder. There is a oneshot unit that simply runs the app once as root, and a timer unit that triggers the oneshot unit every 15 minutes. To install the units, first copy them into you systemd directory. If you installed the app to a different directory, are using command-line arguments to configure, or using a different configuration file location than the one described above, you will need to edit pyia.service to reflect those changes.

sudo cp systemd/* /etc/systemd/system/
# Make any required changes to pyia.service now
sudo systemctl daemon-reload

Now enable and start the oneshot and timer units. Enabling them means that on boot the app will be run and a VPN connection established and maintained every 15 minutes. Starting them means that the connection will be started and maintained right now too.

sudo systemctl enable pyia.service
sudo systemctl enable pyia.timer
sudo systemctl start pyia.service
sudo systemctl start pyia.timer

To schedule the app using cron, an entry needs to be added to the root users crontab. The instructions to do this are shown below. Make changes to the command in the crontab as necessary depending the specifics of your installation.

sudo crontab -e

# Copy the line below into the bottom of the file opened in the editor,
# then save and exit the editor
*/15 * * * * cd /opt/PyIA && ./bin/python3 pyia.py -c config.yml

The cron statement above will run the app every 15th minute (e.g. 1:00, 1:15, 1:30, etc.). To start the connection now run the command in the cron statement manually, for example in the case of the statement above, run:

cd /opt/PyIA && ./bin/python3 pyia.py -c config.yml