Welcome to python-eduvpn-client’s documentation!¶

This is the documentation for the GNU/Linux desktop client and Python API for eduVPN. The Desktop client only works on Linux, but the command-line interface and most parts of the API are usable on other platforms also. Python 3.6+ is required.

Installation¶

The Desktop client only works on Linux. Python 3.6+ is required. It is recommended to use a deb or rpm package to install the eduVPN client. You can also install using pip from pypi or directly from Github. We distribute RPM packages for Fedora, and deb packages for Debian and Ubuntu.

Note

If your target is not supported you can make an issue on the GitHub and we will see if we can provide it. Right now we only provide x86_64 packages (we use a compiled dependency), if you want an ARM package for a certain target you can also make an issue.

Debian 11¶

$ sudo apt update
$ sudo apt install apt-transport-https wget
$ wget -O- https://app.eduvpn.org/linux/v4/deb/app+linux@eduvpn.org.asc | gpg --dearmor | sudo tee /usr/share/keyrings/eduvpn-v4.gpg >/dev/null
$ echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/eduvpn-v4.gpg] https://app.eduvpn.org/linux/v4/deb/ bullseye main" | sudo tee /etc/apt/sources.list.d/eduvpn-v4.list
$ sudo apt update
$ sudo apt install eduvpn-client

Debian 12¶

$ sudo apt update
$ sudo apt install apt-transport-https wget
$ wget -O- https://app.eduvpn.org/linux/v4/deb/app+linux@eduvpn.org.asc | gpg --dearmor | sudo tee /usr/share/keyrings/eduvpn-v4.gpg >/dev/null
$ echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/eduvpn-v4.gpg] https://app.eduvpn.org/linux/v4/deb/ bookworm main" | sudo tee /etc/apt/sources.list.d/eduvpn-v4.list
$ sudo apt update
$ sudo apt install eduvpn-client

Ubuntu 20.04¶

$ sudo apt update
$ sudo apt install apt-transport-https wget
$ wget -O- https://app.eduvpn.org/linux/v4/deb/app+linux@eduvpn.org.asc | gpg --dearmor | sudo tee /usr/share/keyrings/eduvpn-v4.gpg >/dev/null
$ echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/eduvpn-v4.gpg] https://app.eduvpn.org/linux/v4/deb/ focal main" | sudo tee /etc/apt/sources.list.d/eduvpn-v4.list
$ sudo apt update
$ sudo apt install eduvpn-client

Ubuntu 22.04¶

$ sudo apt update
$ sudo apt install apt-transport-https wget
$ wget -O- https://app.eduvpn.org/linux/v4/deb/app+linux@eduvpn.org.asc | gpg --dearmor | sudo tee /usr/share/keyrings/eduvpn-v4.gpg >/dev/null
$ echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/eduvpn-v4.gpg] https://app.eduvpn.org/linux/v4/deb/ jammy main" | sudo tee /etc/apt/sources.list.d/eduvpn-v4.list
$ sudo apt update
$ sudo apt install eduvpn-client

Ubuntu 22.10¶

$ sudo apt update
$ sudo apt install apt-transport-https wget
$ wget -O- https://app.eduvpn.org/linux/v4/deb/app+linux@eduvpn.org.asc | gpg --dearmor | sudo tee /usr/share/keyrings/eduvpn-v4.gpg >/dev/null
$ echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/eduvpn-v4.gpg] https://app.eduvpn.org/linux/v4/deb/ kinetic main" | sudo tee /etc/apt/sources.list.d/eduvpn-v4.list
$ sudo apt update
$ sudo apt install eduvpn-client

Ubuntu 23.04¶

$ sudo apt update
$ sudo apt install apt-transport-https wget
$ wget -O- https://app.eduvpn.org/linux/v4/deb/app+linux@eduvpn.org.asc | gpg --dearmor | sudo tee /usr/share/keyrings/eduvpn-v4.gpg >/dev/null
$ echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/eduvpn-v4.gpg] https://app.eduvpn.org/linux/v4/deb/ lunar main" | sudo tee /etc/apt/sources.list.d/eduvpn-v4.list
$ sudo apt update
$ sudo apt install eduvpn-client

Linux Mint 20.x¶

$ sudo apt update
$ sudo apt install apt-transport-https wget
$ wget -O- https://app.eduvpn.org/linux/v4/deb/app+linux@eduvpn.org.asc | gpg --dearmor | sudo tee /usr/share/keyrings/eduvpn-v4.gpg >/dev/null
$ echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/eduvpn-v4.gpg] https://app.eduvpn.org/linux/v4/deb/ focal main" | sudo tee /etc/apt/sources.list.d/eduvpn-v4.list
$ sudo apt update
$ sudo apt install eduvpn-client

Linux Mint 21.x¶

$ sudo apt update
$ sudo apt install apt-transport-https wget
$ wget -O- https://app.eduvpn.org/linux/v4/deb/app+linux@eduvpn.org.asc | gpg --dearmor | sudo tee /usr/share/keyrings/eduvpn-v4.gpg >/dev/null
$ echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/eduvpn-v4.gpg] https://app.eduvpn.org/linux/v4/deb/ jammy main" | sudo tee /etc/apt/sources.list.d/eduvpn-v4.list
$ sudo apt update
$ sudo apt install eduvpn-client

Fedora (37 & 38)¶

$ curl -O https://app.eduvpn.org/linux/v4/rpm/app+linux@eduvpn.org.asc
$ sudo rpm --import app+linux@eduvpn.org.asc
$ cat << 'EOF' | sudo tee /etc/yum.repos.d/python-eduvpn-client_v4.repo
[python-eduvpn-client_v4]
name=eduVPN for Linux 4.x (Fedora $releasever)
baseurl=https://app.eduvpn.org/linux/v4/rpm/fedora-$releasever-$basearch
gpgcheck=1
EOF
$ sudo dnf install eduvpn-client

CentOS (Stream 9)¶

$ curl -O https://app.eduvpn.org/linux/v4/rpm/app+linux@eduvpn.org.asc
$ sudo rpm --import app+linux@eduvpn.org.asc
$ cat << 'EOF' | sudo tee /etc/yum.repos.d/python-eduvpn-client_v4.repo
[python-eduvpn-client_v4]
name=eduVPN for Linux 4.x (CentOS Stream 9)
baseurl=https://app.eduvpn.org/linux/v4/rpm/centos-stream+epel-next-9-$basearch
gpgcheck=1
EOF
$ sudo dnf install eduvpn-client

Arch (Unofficial)¶

There is an unofficial package in the Arch User Repository (AUR).

Pip installation¶

We also provide pip packages. These are useful if your distro is not officially supported in our packaging (yet).

Dependencies¶

To manually install the eduVPN package via Pip you first need to satisfy the dependencies.

For Debian or Ubuntu:

$ sudo apt update
$ sudo apt install \
            gir1.2-nm-1.0 \
            gir1.2-secret-1 \
            gir1.2-gtk-3.0 \
            gir1.2-notify-0.7 \
            libgirepository1.0-dev \
            libdbus-glib-1-dev \
            python3-gi \
            python3-setuptools \
            python3-pytest \
            python3-wheel \
            python3-dbus \
            network-manager-openvpn-gnome

For Fedora:

$ sudo dnf install \
            libnotify \
            libsecret \
            gtk3 \
            python3-dbus \
            python3-gobject \
            python3-pytest \
            python3-cairo-devel \
            gobject-introspection-devel \
            cairo-gobject-devel \
            dbus-python-devel

Pip commands¶

You can then continue with installing via Pip:

$ pip install "eduvpn-client[gui]"

Or, if you want to try out the bleeding edge development version:

$ pip install git+https://github.com/eduvpn/python-eduvpn-client.git

Issues¶

If you experience any issues you could and should report them at our issue tracker. Please don’t forget to mention your OS, method of installation, eduVPN client version and instructions on how to reproduce the problem. If you have a problem enabling your VPN connection please also examine the journalctl -u NetworkManager logs. The log file of the eduVPN app can also help us figure out the problem, running the gui or cli in debug mode (-d) flag will print debug logging to the log file located at: ~/.config/eduvpn/log or ~/.config/letsconnect/log for Let’s Connect!.

Source code¶

Development of this project takes place on github. You can find the source code and all releases there.

Contributing¶

Contributions are more than welcome! If you experience any problems let us know in the bug tracker. We accept patches in the form of github pull requests. Please make sure your code works with python3 and is pycodestyle (formerly pep8) compatible. Also make sure the test suite actually passes all tests. Translations are also welcome!

Updating¶

Depending on the client that you want to update from, there might be some manual steps required before/after installing.

For most version updates you can simply do an update with your package manager.

Additional instructions when coming from 3.x¶

When upgrading from version 3 to the newest version (currently 4.x), there are some manual steps needed for updating. The main part is that we have moved to a new repository for this major version update. We will go over the distro specific update instructions (distros that are not listed here do not need specific instructions, go to Installation).

Before you continue, it might be wise to close the client if you have it open. Note that once the new client is installed, you will have to add your servers again.

Debian and Ubuntu (both x86_64)¶

First we must remove the old files, repository and associated signing keys:

$ rm -r ~/.config/eduvpn
$ sudo rm /etc/apt/sources.list.d/eduvpn.list
$ sudo rm /etc/apt/trusted.gpg.d/eduvpn-client.gpg
$ sudo rm /usr/share/keyrings/eduvpn.gpg
$ sudo apt-key del 9BF9BF69E5DDE77F5ABE20DC966A924CE91888D2

It’s fine if you get errors that some of these entries don’t exist.

You can then continue installing the new client by adding the new repository if you have Ubuntu 20.04, >= 22.04 or Debian 11/12:

$ sudo apt install apt-transport-https lsb-release wget
$ wget -O- https://app.eduvpn.org/linux/v4/deb/app+linux@eduvpn.org.asc | gpg --dearmor | sudo tee /usr/share/keyrings/eduvpn-v4.gpg >/dev/null
$ echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/eduvpn-v4.gpg] https://app.eduvpn.org/linux/v4/deb/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/eduvpn-v4.list
$ sudo apt update
$ sudo apt upgrade

For other Debian based distros, you can use Pip . If you do the upgrade via Pip, remove the old client first with:

$ sudo apt purge eduvpn-client
$ sudo apt autoremove

Then install via Pip, see Pip Installation

Fedora (37 & 38, x86_64)¶

First we must remove the old files, repository and associated signing keys:

$ rm -r ~/.config/eduvpn
$ sudo dnf copr remove @eduvpn/eduvpn-client

You can then continue installing the new client by adding the new repository:

$ curl -O https://app.eduvpn.org/linux/v4/rpm/app+linux@eduvpn.org.asc
$ sudo rpm --import app+linux@eduvpn.org.asc
$ cat << 'EOF' | sudo tee /etc/yum.repos.d/python-eduvpn-client_v4.repo
[python-eduvpn-client_v4]
name=eduVPN for Linux 4.x (Fedora $releasever)
baseurl=https://app.eduvpn.org/linux/v4/rpm/fedora-$releasever-$basearch
gpgcheck=1
EOF
$ sudo dnf --refresh update

Usage¶

Graphical User Interface¶

If you have used a RPM or DEB package to install eduVPN, a desktop entry is available:

If you installed the package by hand with for example pip, you can run it manually:

$ eduvpn-gui

Command Line Interface¶

There is also a command line interface available for eduVPN since 2.0. To see the available subcommands:

$ eduvpn-cli --help

There is also an interactive mode that is aimed to be more user friendly.

$ eduvpn-cli interactive

Developer notes¶

Notes about code¶

Use the decorator eduvpn.utils.run_in_background_thread to schedule long running action in the background to avoid blocking the main thread.

Never call GTK functions directly from a background thread, use eduvpn.utils.run_in_main_gtk_thread to decorate functions that must run on the main thread (eg. UI updates).

This library closely follows eduvpn-common. To see the API for that, see here

Most of the interaction with this library is in eduvpn.app, the ui is in eduvpn.ui.ui and the cli in eduvpn.cli. In these files you can see lots of state transitions defined. The state transitions that are used are closely in line with the Finite State machine from the eduvpn-common library. A figure for this state machine can be found here.

Running the tests¶

To run the automated tests, use the following command from the root of the project.

$ pytest

How to make a release¶

Prepare the code¶

Determine version number (for example 4.1.3)
Compose a list of changes (check issue tracker)
Make sure the test suite runs with python3
Set version number in setup.py, and eduvpn.spec and ensure eduvpn-common has the targeted version set
add changes to CHANGES.md
Commit
Press release button on github. List all changes here also
Check if GitHub Actions builds.
The release will trigger a build on readthedocs, but the active version still needs to be set manually here: https://readthedocs.org/projects/python-eduvpn-client/versions/

Upload to PyPi¶

do a manual wheel upload using twine:

$ rm dist/*
$ python setup.py bdist_wheel sdist
$ twine upload dist/*

There is also a make shortcut:

$ make twine-upload

You should also make sure that eduvpn-common is updated in PyPi! Update in the test PyPi first so that CI passes.

Building RPMs¶

We use builder.rpm, to build the RPM packages.

Build Debian packages¶

We use nbuilder.deb, to build the DEB packages.

Known issues¶

This chapter contains some known issues for the Linux client that are not possible or hacky to fix in the client itself

OpenVPN <= 2.5.7 and OpenSSL 3¶

When your distribution uses OpenSSL 3 and an OpenVPN version before 2.5.8, you might get the following error in the NetworkManager logging after connecting to a server that uses OpenVPN:

$ Cipher BF-CBC not supported

This means that OpenVPN is trying to initialize this legacy/deprecated cipher, even though it is not used in the config. The fix is in OpenVPN version starting at 2.5.8.

Could not find source connection/NetworkManager not managing connections¶

It could be the case where the client does not work due to the fact that NetworkManager does not manage your connections.

You could see errors such as:

$ nm-manager-error-quark: Could not find source connection.

To fix this, make sure that NetworkManager is managing your primary interface. For e.g. Debian systems you can follow the instructions on The Debian Wiki and then reboot. Pull requests are welcome to make the client work without NetworkManager.

Version GLIBC_2.32 not found¶

If you install the client using instructions for a different distribution, you can have these GLIBC errors showing when the client is trying to load eduvpn-common. To fix this make sure to uninstall all the packages you currently have installed (Pip, DEB/RPM) and then follow the instructions for your appropriate distribution. See Installation.

If you have followed the right instructions and are still getting these errors you can make an issue.

GUI does not launch due to getting attribute errors¶

If your GUI does not launch and you get errors such as:

$ File "/usr/lib/python3/dist-packages/eduvpn/ui/ui.py", line 165, in setup
$ self.common_version.set_text(f"{commonver}")
$ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
$ AttributeError: 'NoneType' object has no attribute 'set_text'

It can mean that you have installed multiple versions of the client. If you’re trying to use the DEB/RPM version see if:

$ pip uninstall eduvpn-client[gui]

Does anything.

Otherwise, if there are files in ~/.local/share/eduvpn try to move them to e.g. ~/.local/share/eduvpn2. If the client then still doesn’t launch you can make an issue.