From 0b8bcc646ad6b9441d6b0224947603bc504f2b58 Mon Sep 17 00:00:00 2001
From: Pea Nut <peanut2@systemli.org>
Date: Wed, 12 Jun 2024 11:18:44 +0200
Subject: [PATCH] Document environment variables
- document environment variables
- add snap install instruction
- standardize a bit
- add PROVIDER= env to build instruction
---
README.md | 53 ++++++++++++++++++++++++++++++--------------------
docs/debug.rst | 42 ++++++++++++++++++---------------------
2 files changed, 51 insertions(+), 44 deletions(-)
diff --git a/README.md b/README.md
index 2cf820ce..623becf8 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,5 @@
+# BitmaskVPN - Desktop client
+
## Supported operating systems
**BitmaskVPN** needs the following minimum versions of supported operating systems:
@@ -18,15 +20,15 @@
## Install
-# arch
+# Arch Linux
-[There's a package in AUR](https://aur.archlinux.org/packages/riseup-vpn-git) that tracks main branch, so expect some instabilities (early birds catch the bugs they say, and we're thankful for that)
+There are two AUR packages for Arch Linux. There is [riseup-vpn-git](https://aur.archlinux.org/packages/riseup-vpn-git) that tracks main branch, so expect some instabilities (early birds catch the bugs they say, and we're thankful for that). There is also [riseup-vpn](https://aur.archlinux.org/packages/riseup-vpn) with the latest stable release.
```
-yaourt -Sy riseup-vpn-git
+yay riseup-vpn
```
-# deb
+# Debian
We haven't updated deb.leap.se repo yet 😞 (see #466), but if you *really* desire a debian
package you can build your own for the time being:
@@ -36,9 +38,11 @@ debuild -us -uc
sudo dpkg -i ../riseup-vpn*.deb
```
-# ubuntu
+You can also run `make package_deb`. You can install the built package with `apt install -f ./deploy/*.deb`.
+
+# Ubuntu
-If you're using ubuntu, you can use [leapcodes ppa](https://launchpad.net/~leapcodes/+archive/ubuntu/riseup-vpn).
+If you're using Ubuntu, you can use [leapcodes ppa](https://launchpad.net/~leapcodes/+archive/ubuntu/riseup-vpn).
```
sudo add-apt-repository ppa:leapcodes/riseup-vpn
@@ -46,16 +50,23 @@ sudo apt update
sudo apt install riseup-vpn
```
+## Snap
+
+There is also a package in the [Snap store](https://snapcraft.io/riseup-vpn).
+
+```
+sudo snap install riseup-vpn
+```
+
## Build
-Clone this repo, install dependencies and build the application. Dependencies
-assume debian packages, or homebrew for osx. For Windows OS see corresponding section below. For other systems try
-manually, or send us a patch.
+Clone this repo, install dependencies and build the application. Dependencies assume debian packages, or homebrew for osx. For Windows OS see corresponding section below. For other systems try manually, or send us a patch. bitmask-vpn can be branded for a specific provider by specifying the env variable PROVIDER during the build process; we currently support three providers: riseup, calyx, and bitmask. To create a client branded for 'riseup', run:
```
- git clone git@0xacab.org:leap/bitmask-vpn.git && cd bitmask-vpn
- sudo make depends # do not use sudo in osx
- make build
+git clone git@0xacab.org:leap/bitmask-vpn.git && cd bitmask-vpn
+sudo make depends # do not use sudo in osx
+PROVIDER=riseup make vendor
+make build
```
You need at least go 1.20.
@@ -65,9 +76,9 @@ You need at least go 1.20.
You can run some tests too.
```
- sudo apt install qml-module-qttest
- make test
- make test_ui
+sudo apt install qml-module-qttest
+make test
+make test_ui
```
## Windows
@@ -85,7 +96,7 @@ You need to have installed and added to your user PATH (mentioned version tested
#### Get Source
```
- git clone git@0xacab.org:leap/bitmask-vpn.git && cd bitmask-vpn
+git clone git@0xacab.org:leap/bitmask-vpn.git && cd bitmask-vpn
```
#### Build
@@ -93,12 +104,12 @@ Build script uses a symbolic link in one of the stages. Unfortunately Cygwin can
admin user due to windows security restriction. To avoid this issue we need to call next target from cygwin terminal as
Administrator. This need to be done only once.
```bash
- make relink_vendor
+make relink_vendor
```
After `relink_vendor` use this to build the app:
```bash
- make build
+make build
```
After successful build application will be available at: `build/qt/release/riseup-vpn.exe`
@@ -107,8 +118,8 @@ After successful build application will be available at: `build/qt/release/riseu
To run tests:
```bash
- make test
- make test_ui
+make test
+make test_ui
```
## Logging
@@ -118,7 +129,7 @@ Linux: `~/.config/leap/systray.log`
Windows: `%LocalAppData%\leap\systray.log `
Mac: `~/Library/Preferences/leap/systray.log`
-Log levels can be set via environment variable (`LOG_LEVEL=TRACE`, `LOG_LEVEL=DEBUG`, default log level is `INFO`). The cpp/qml part logs to stderr if env `DEBUG=1` is set.
+Log levels can be set via environment variable (`LOG_LEVEL=TRACE`, `LOG_LEVEL=DEBUG`, default log level is `INFO`). The cpp/qml part logs to stderr if env `DEBUG=1` is set. If `OPENVPN_LOG_TO_FILE=1` is set, the OpenVPN process writes its logs to [os.TempDir()](https://pkg.go.dev/os#TempDir)/leap-vpn.log. The verbosity of OpenVPN can be specified with env `OPENVPN_VERBOSITY` (sets `--verb`).
Translations
------------
diff --git a/docs/debug.rst b/docs/debug.rst
index 21eca1e9..480479eb 100644
--- a/docs/debug.rst
+++ b/docs/debug.rst
@@ -91,33 +91,29 @@ To force logging:
QT_FORCE_STDERR_LOGGING=1 ./riseup-vpn.exe
+We should probably restrict this to non-release versions only.
-Ciphersuites and other openvpn params
--------------------------------------
-You can specify a custom `openvpn_configuration` block from a local file
-(instead of fetching it from `eip-service.json`) via an environment variable:
-
-.. code:: bash
-
- LEAP_OPENVPN_EXTRA_CONFIG=../extra-config.json ./riseup-vpn
-
-Manual Gateway Selection
-------------------------
-In the same spirit, you can manually override the gateway selection via an
-environment variable that contains the hostname of the gateway:
-
-
-.. code:: bash
+Environment Variables
+~~~~~~~~~~~~~~~~~~~~~
- LEAP_GW=hostname.riseup.net ./riseup.vpn
+The envs are only used for debugging and developing. The envs affecting the logging behavior are documented in the logging section in the `README <https://0xacab.org/leap/bitmask-vpn/-/blob/main/README.md?ref_type=heads#logging>`_.
-Dry run
--------
+- ``SKIP_VERSION_CHECK``: Do not check if there is an update available
+- ``LEAP_DRYRUN``: Don't route traffic over VPN (run openvpn with "--pull-filter ignore route" argument) and do not touch firewall rules
+- ``MOTD_URL``: Overwrite the MOTD (message of the day) url
+- ``SNAP``: If not empty, we expect to be in a Snap environment (client was installed by Snap)
+- ``UDP``: If we use UDP, UDP is set to 1. If we use TCP, UDP is set to 0. The value is read by the bitmask-root helper which sets firewall rules on Linux
+- ``LEAP_PROVIDER``: Select the provider to use. Must be one of the providers listed in ``gui/providers/providers.json``. File is generated by the Makefile which runs ``./branding/scripts/gen-providers-json``
-To avoid setting up the routes, you can pass the LEAP_DRYRUN variable:
+obfs4
+~~~~~
-.. code:: bash
+- ``LEAP_PRIVATE_BRIDGE_CERT``: Specify the cert string for the obfs4 bridge to be used
+- ``LEAP_PRIVATE_BRIDGE``: Specify the host:port for the obfs4 bridge to be used
- LEAP_DRYRUN=1 ./riseup.vpn
+Only implemented in v3/vpnweb:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-We should probably restrict this to non-release versions only.
+- ``LEAP_GW``: Specify the gateway hostname to connect with. It needs to be one of the gateway returned by vpnweb
+- ``LEAP_OPENVPN_EXTRA_CONFIG``: Specify a file with extra OpenVPN arguments to use. File should be in json format (in key value format like {"--dev": "tun"} or {"--persist-key": true})
+- ``LEAP_KCP``: Enforce the use of KCP in obfsvpn
--
GitLab