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, but the command-line interface and most parts of the API are usable on other platforms also. 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.

The eduVPN client has been tested with:

  • Debian 10 (Buster)
  • Ubuntu 20.04 LTS and 18.04 LTS
  • CentOS 8
  • Fedora 34 and 35

Note

If you target is not supported the client might still work with limited functionality. You need to have Network Manager and OpenVPN 2.4.0+ installed.

Debian and Ubuntu

You can install the latest release on Debian or Ubuntu using the eduVPN packaging repository by running these commands:

$ sudo apt install apt-transport-https curl
$ curl -L https://app.eduvpn.org/linux/deb/eduvpn.key | sudo apt-key add -
$ echo "deb https://app.eduvpn.org/linux/deb/ stable main" | sudo tee -a /etc/apt/sources.list.d/eduvpn.list
$ sudo apt update
$ sudo apt install eduvpn-client

Fedora and CentOS

You can install the latest release of the eduVPN client on Fedora or CentOS by running these commands :

$ sudo dnf install dnf-plugins-core
$ sudo dnf copr enable @eduvpn/eduvpn-client
$ sudo dnf install eduvpn-client

More information is available at fedora copr.

Manual source installation

Dependencies

To manually install the eduVPN package you first need to satisfy the build requirements.

For Debian or Ubuntu:

$ sudo apt install build-essential git make

For fedora:

$ sudo dnf install git make

For Debian or Ubuntu we made a make target to install the required debian packages:

$ sudo make deb

For fedora we did the same:

$ sudo make dnf

Pip

You can install the client API from pypi:

$ 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

Note

This requires the installation of system packages using your distributions package manager. Consult the Makefile for the complete list.

Development version

You first need to obtain the code:

$ git clone https://github.com/eduvpn/python-eduvpn-client.git
$ cd python-eduvpn-client

We’ve made various Makefile targets to quickly get started. For example to start the eduVPN GUI:

$ make eduvpn-gui

Please have a look in the Makefile to find out the available targets.

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.

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!

Usage

Graphical User Interface

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

The eduVPN desktop entry

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

For example, to refresh your configured configuration and certicates one can run the refresh subcommand:

$ eduvpn-cli refresh
INFO:eduvpn.remote:Requesting https://demo.eduvpn.nl/.well-known/vpn-user-portal
INFO:eduvpn.storage:updating token for https://demo.eduvpn.nl/

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).

eduvpn.actions are the entrypoints to the application and are triggered from the main menu or a VPN status change.

eduvpn.remote contains all remote requests.

Flow schema

The application flow

Running the tests

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

$ pytest

To include integration tests against an actual server, you’ll need to provide the address and login credentials in an environment variable.

$ TEST_SERVER=username:password@example.com pytest

How to make a release

Prepare the code

  • Determine version number (for example 1.0.2)
  • 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
  • add changes to CHANGES.md
  • Commit
  • Press release button on github. List all changes here also
  • Check if github actions builds.

Upload to pypi

do a manual wheel upload using twine:

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

Build on copr for RPMs

Build packages to the COPR repository:

You can also trigger this build from the cli. First fetch your token from the COPR api page and dump this in ~/.config/copr. Next, you install the copr cli and trigger the build with:

$ venv/bin/pip install copr-cli
$ copr-cli buildscm \
   --clone-url https://github.com/edupvn/python-eduvpn-client \
   --commit <version> \
   --spec eduvpn.spec
   @eduvpn/eduvpn-client

where <version> is the tag/version of the release.

Build Debian packages

Indices and tables