This is the desktop client for the Private Internet Access VPN service. It consists of an unprivileged thin GUI client (the "client") and a privileged background service/daemon (the "daemon"). The daemon runs a single instance on the machine and is responsible for not only network configuration but also settings and account handling, talking to PIA servers as necessary. The client meanwhile runs in each active user's desktop and consists almost entirely of presentation logic. No matter how many users are active on a machine, they control the same single VPN instance and share a single PIA account.
The project uses Qt 5 for cross-platform development, both in the client and daemon. The client GUI is based on Qt Quick, which uses declarative markup language and JavaScript and offers hardware accelerated rendering when available. Qt and Qt Quick tend to be more memory and CPU efficient compared to web-based UI frameworks like Electron or NW.js.
The client is intended to be built on the target platform; Windows builds are built on Windows, macOS builds on macOS, and Linux builds on Debian.
The entire product is built using rake, using the supporting framework in the rake/
directory.
Dependencies such as OpenVPN and the Windows TAP driver are included as precompiled binaries under the deps
directory in this project for convenience. To recompile any of these, please refer to their corresponding directories and/or repositories for build instructions.
Before cloning the Git repository, first make sure Git LFS is installed and initialized:
> git lfs version
git-lfs/2.3.4 (GitHub; windows amd64; go 1.8.3; git d2f6752f)
> git lfs install
Updated git hooks.
Git LFS initialized.
After this, cloning the repository normally should also fetch the precompiled binaries:
> git clone https://github.com/pia-foss/desktop.git
...
Filtering content: 100% (24/24), 17.13 MiB | 1.89 MiB/s, done.
QTROOT
to C:\Qt\5.15.2
choco
to find out)Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
choco install python
pip install aqtinstall
mkdir C:\Qt-aqt
cd C:\Qt-aqt
aqt install-qt windows desktop 5.15.2 win64_msvc2019_64
QTROOT
to C:\Qt-aqt\5.15.2
brew install ruby
sudo gem install rake
sudo ARCHFLAGS="-arch arm64" gem install nokogiri -v 1.13.10
sudo apt install build-essential rake clang mesa-common-dev libnl-3-dev libnl-route-3-dev libnl-genl-3-dev git git-lfs
sudo pacman -S base-devel git-lfs ruby-rake clang llvm libnl zip
sudo apt install schroot debootstrap
./scripts/chroot/setup.sh
to set up the build chroots, see "Building for Distribution - Linux" belowEach platform requires additional installation steps in order for the client to be usable (e.g. the Windows TAP adapter needs to be installed).
The easiest way to perform these steps is to build and run an installer, after which you can stop and run individual executables in a debugger instead.
To debug your own daemon, the installed daemon must first be stopped:
services.msc
and stop the Private Internet Access Service. Set it to manualsudo launchctl unload /Library/LaunchDaemons/com.privateinternetaccess.vpn.daemon.plist
sudo systemctl stop piavpn
The daemon must run as root. Consult your IDE/debugger documentation for how to safely run the debugger target as root.
Windows only:
C:\Qt\5.15.2\msvc2019_64\bin
to your user environment variable path.pia-client.exe
or pia-service.exe
via command line..\pia-service.exe run
in Powershell with admin privilegesTo check PIA logs, go to your *installation_path*\data
(The default path on Windows is C:\Program Files\Private Internet Access\data
).
In order to enable all the logs, in PIA app Settings page go to Help and select Enable Debug Logging.
rake installer
out/pia_debug_<arch>/installer
rake all
out/pia_debug_<arch>/artifacts
rake
out/pia_debug_<arch>/stage
- run the client or daemon from hererake test
VARIANT=release
with any of the aboveTo open the project in Qt Creator, open CMakeLists.txt as a project. This CMake script defines targets for Qt Creator and hooks them up to the appropriate rake tasks, which allows Qt Creator to build, run, and debug targets.
Some specific configuration changes are useful in Qt Creator:
The file locator (Ctrl+K / Cmd+K) can only locate files referenced by targets by default, so it won't be able to find build system files (.rb), scripts (.sh/.bat), etc. To find any file in the project directory:
Qt Creator's default target is 'all', which is hooked up to rake's default - the staged installation only. (The real 'all' target takes a long time since it builds all tests, installers, tools, etc.)
To run or debug unit tests and other targets from Qt Creator, tell it to build the current executable's target instead:
Qt Creator will still ask to select a kit, which includes a Qt version, compiler, etc. Just select Qt 5.15.2 (on Windows, the MSVC 2019 64-bit target), so the code model will work.
This has no effect on the build output - the Rake scripts find Qt and the compiler on their own, which allows them to be run with no prior setup.
The following targets can be passed to rake
. The default target is stage
, which stages the built client, daemon, and dependencies for local testing (but does not build installers, tests, etc.)
Target | Explanation |
---|---|
(default) | Builds the client and daemon; stages executables with dependencies in out/pia_debug_x86_64/stage for local testing. |
test |
Builds and runs unit tests; produces code coverage artifacts if possible on the current platform (requires clang 6+) |
installer |
Builds the final installer artifact, including code signing if configured. |
export |
Builds extra artifacts needed from CI but not part of any deployable artifact (currently translation exports) |
libs |
Builds the dtop libraries and development artifact (see DTOP-LIBS.md) |
tools |
Builds extra tools for development purposes that are not used as part of the build process or as part of any shipped artifact. |
artifacts |
Builds all artifacts and copies to out/pia_debug_x86_64/artifacts (depends on most other targets, execpt test when coverage measurement isn't possible) |
all |
All targets. |
The build system has several properties that can be configured, either in the environment or by passing the appropriate variables to rake
.
These are implemented in rake/build.rb
. The output directory name includes the current brand, variant, and architecture.
Variable | Values | Default | Explanation |
---|---|---|---|
VARIANT |
debug , release |
debug |
Create a debug build (unoptimized, some compression levels reduced for speed), or release build (optimized, maximum compression). |
ARCHITECTURE |
x86_64 , x86 , arm64 , arm64e , armhf , universal |
Host architecture | Select an alternate architecture. Architecture support varies by platform. |
PLATFORM |
windows , macos , linux , android , ios , iossim |
Host platform | Select an alternate platform. Android and iOS targets only build core libraries and tests. Android builds can be performed from macOS or Linux hosts. iOS and iOS Simulator builds can be performed from macOS hosts. |
BRAND |
(directories in brands/ ) |
pia |
Build an alternate brand. |
Some additional environment variables can be configured:
Variable | Example | Explanation |
---|---|---|
QTROOT |
/opt/Qt/5.15.2 | Path to the installed Qt version, if qt.rb can't find it or you want to force a specific version |
rake artifacts
(or rake all
) produces the final artifacts for distribution, including signing if code signing details are provided. Code signing environment variables are defined below.
Build scripts in the scripts
directory are also provided that clean, then build for all architectures supported on a given platform.
Set environment variables:
Variable | Value |
---|---|
BRAND | (Optional) Brand to build (defaults to pia ) |
PIA_SIGNTOOL_CERTFILE | Path to certificate file (if signing with PFX archived cert) |
PIA_SIGNTOOL_PASSWORD | Password to decrypt cert file (if signing with encrypted PFX archived cert) |
PIA_SIGNTOOL_THUMBRPINT | Thumbprint of certificate - signs with cert from cert store instead of PFX archive |
Then call scripts/build-windows.bat
Set environment variables:
Variable | Value |
---|---|
BRAND | (Optional) Brand to build (defaults to pia ) |
PIA_CODESIGN_CERT | Common name of the signing certificate. Must be the complete common name, not a partial match. |
PIA_APPLE_ID_EMAIL | Apple ID used to notarize build. |
PIA_APPLE_ID_PASSWORD | Password to Apple ID for notarization. |
PIA_APPLE_ID_PROVIDER | (Optional) Provider to use if Apple ID is member of multiple teams. |
Call scripts/build-macos.sh
A certificate is required for the Mac build to be installable (even for local builds), see below to generate a self-signed certificate for local use. Unsigned builds can be manually installed by running the install script with sudo
.
If you have not already done so, set up Debian 9 build chroots. This requires debootstrap
and schroot
.
$ ./scripts/chroot/setup.sh # native x86_64 build environment
$ ./scripts/chroot/setup.sh --cross-target arm64 # arm64 cross build environment
$ ./scripts/chroot/setup.sh --cross-target armhf # armhf cross build environment
Set environment variables:
Variable | Value |
---|---|
BRAND | (Optional) Brand to build (defaults to pia ) |
Then call scripts/build-linux.sh
.
Installation on Mac uses SMJobBless
to install a privileged helper that does the installation.
Mac OS requires the app to be signed in order to install and use the helper. If the app is not signed, it will not be able to install or uninstall itself (you can still install or uninstall manually by running the install script with sudo
.)
PIA_CODESIGN_CERT
must be set to the full common name of the certificate to sign with. (codesign
allows a partial match, but the full CN is needed for various Info.plist files.)
To test installation, you can generate a self-signed certificate and sign with that.
PIA_CODESIGN_CERT
, and set the value to the common name for your certificatebuild-macos.sh
PIA_CODESIGN_CERT
to the common name you gave the certificate when buildingSome core libraries can be built targeting Android and iOS for use in our mobile clients.
sudo apt install rake
sudo pacman -S ruby-rake
brew install ruby
(includes Rake)brew install ruby
(includes Rake)Invoke rake
with PLATFORM=android
or PLATFORM=ios
to target a mobile platform. You can also set ARCHITECTURE
to one of arm64
, armhf
, x86_64
, or x86
- the host architecture is the default. (If you do this a lot, you can place overrides in your environment or .buildenv to use these by default.)
(Qt does not need to be installed for mobile targets.)
The same rake
-based build system is used, but the available targets differ.
Target | Explanation |
---|---|
(default) | Stages core libraries with dependencies in out/pia_debug_<platform>_<arch>/dtop-libs for local testing. |
libs_archive |
Builds the library SDK ZIP containing the built libraries and headers. |
tools |
Builds libraries and internal test harnesses used to test them. |
artifacts |
Builds all artifacts and copies to out/pia_debug_<platform>_<arch>/artifacts (depends on most other targets) |
all |
All targets. |
In the headless_tests
directory you will find a suite of tests written in ruby with the help of RSpec.
They use piactl
in the background to manipulate the state of the daemon and run diverse tests.
The advantage of testing in ruby is mainly simplicity, where doing things like calling API endpoints is much simpler than from C++ code.
With these almost end to end tests we hope to drastically reduce manual testing for releases to the point that we can release more frequently.
Use bundle install
to ensure you get all the dependencies.
Run the tests from within the headless_tests
to pick up configuration in .rspec
and spec_helper
.
Run all tests locally using bundle exec rspec .
.
Add C:\Program Files\Private Internet Access
to your user environment variable Path in order to be able to run piactl
from the command line. (You can still run piactl using the full path, but the headless tests won't work).
By contributing to this project you are agreeing to the terms stated in the Contributor License Agreement. For more details please see our Contribution Guidelines or CONTRIBUTING.
Unless otherwise noted, original source code is licensed under the GPLv3. See LICENSE for more information.