M ADMIN_API.md => ADMIN_API.md +9 -9
@@ 14,7 14,7 @@ scenario.
**NOTE**: this is a [Preview Feature](PREVIEW_FEATURES.md)!
-# Configuration
+## Configuration
The API is _disabled_ by default, but it is easy to enable.
@@ 66,7 66,7 @@ In order to use the API, the _secret_ you need can be found in
above. Use this value in the `Authorization` (Bearer) header. See the examples
below.
-# API Calls
+## API Calls
Two API calls are provided, `/create` and `/destroy` that can be used to create
a VPN configuration for a particular user (and profile) and to remove the VPN
@@ 76,7 76,7 @@ The `/create` call will transparently create the user if necessary and the
`/destroy` call will delete the account as well as disconnect the client(s) of
that user and delete the configuration(s).
-## Create
+### Create
Create a VPN configuration for a particular user (and profile).
@@ 87,7 87,7 @@ Create a VPN configuration for a particular user (and profile).
| `profile_id` | Yes | The `profile_id` of the VPN profile to create a configuration for |
| `prefer_tcp` | No | Prefer connecting over TCP to the server. Either `yes` or `no`. Defaults to `no` |
-### Request
+#### Request
Connect to the "Employees" profile (`employees`) and specify a WireGuard public
key for when WireGuard will be used:
@@ 101,7 101,7 @@ $ curl \
"https://vpn.example.org/vpn-user-portal/admin/api/v1/create"
```
-## Destroy
+### Destroy
Remove the VPN configurations of a particular user *and* delete their account.
@@ 116,7 116,7 @@ profile?
to the above question is YES then we should probably not (always) delete the
user account
-### Request
+#### Request
```bash
$ curl \
@@ 125,11 125,11 @@ $ curl \
"https://vpn.example.org/vpn-user-portal/admin/api/v1/destroy"
```
-# VPN Client
+## VPN Client
We'll describe how to configure VPN clients with these configuration files.
-## Windows
+### Windows
Complete documentation on how to setup Windows with WireGuard to have VPN
enabled before user authentication can be found
@@ 138,7 138,7 @@ enabled before user authentication can be found
You can deploy the configuration file and MSI through AD/GPO and enable the
service as documented.
-## macOS
+### macOS
Probably using
[this](https://github.com/WireGuard/wireguard-apple/blob/master/MOBILECONFIG.md).
M API_CLIENT_REGISTRATION.md => API_CLIENT_REGISTRATION.md +2 -2
@@ 12,7 12,7 @@ This is done by creating a JSON file in
The format is an _array_ with _objects_. See the full example below.
-# Format
+## Format
The object supports the following fields / types:
@@ 24,7 24,7 @@ The object supports the following fields / types:
| `client_name` | No | `string` | value of `client_id` | `My Application` |
| `requires_approval` | No | `bool` | `true` | `false` |
-# Example
+## Example
As an example we'll list the govVPN OAuth client registrations here. This would
be the full contents of `/etc/vpn-user-portal/oauth_client_db.json`:
M CONTRIBUTE_TRANSLATIONS.md => CONTRIBUTE_TRANSLATIONS.md +4 -8
@@ 1,13 1,9 @@
----
-title: Contribute Translations
-description: Contribute Translations for the User and Admin portal(s)
-category: customization
----
+# Contribute translations
If you'd like to contribute translations to the VPN software this document
explains how.
-# Server
+## Server
You can check which translations are already available, and possibly update
them if they are out of date:
@@ 30,11 26,11 @@ The files use the PHP
The "key" is the English string, the value should be the translation.
-# Apps
+## Apps
TBD.
-# Submitting
+## Submitting
Once you are done, you can submit your translation file either by creating a
"Pull Request" on GitHub, or simply mailing the file with your translations to
M CUSTOM_BRANDING.md => CUSTOM_BRANDING.md +4 -8
@@ 1,13 1,9 @@
----
-title: Custom Branding
-description: Apply your own Branding/Themes
-category: customization
----
+# Custom branding
This document describes how to apply your own branding (style and e.g. logo) to
the portal.
-# Custom Portal Footer
+## Custom Portal Footer
If all you want is to add a simple text at the bottom of (all) pages, you can
use the "custom footer" functionality.
@@ 22,7 18,7 @@ following content:
**NOTE**: this footer is *always* visible, also when VPN apps are being
authorized.
-## Translations
+### Translations
You can also use multi language custom footers. You can use the
`<?=$this->t('Text To Translate');?>` format to make text translatable and
@@ 50,7 46,7 @@ they exist.
escape them by adding a backslash (`\`) in front of them, e.g.
`'Don\'t click here!'`.
-# Template Overriding
+## Template Overriding
The portal uses templates, located in the following folder:
M DEVELOPMENT_REPO.md => DEVELOPMENT_REPO.md +6 -6
@@ 60,30 60,30 @@ hbtNfeBYGPPLFHY/gw7jLsMACApu636zxr77LxzbFgz7
-----END PGP PUBLIC KEY BLOCK-----
```
-# Debian / Ubuntu
+## Debian / Ubuntu
-## Repository Key
+### Repository Key
```bash
$ curl https://repo.tuxed.net/fkooman+repo@tuxed.net.asc | sudo tee /etc/apt/trusted.gpg.d/eduVPN_v3-dev.asc
```
-## Repository Config
+### Repository Config
```bash
echo "deb https://repo.tuxed.net/eduVPN/v3-dev/deb $(/usr/bin/lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/eduVPN_v3-dev.list
```
-# Fedora
+## Fedora
-## Repository Key
+### Repository Key
```bash
$ curl -O https://repo.tuxed.net/fkooman+repo@tuxed.net.asc
$ sudo rpm --import fkooman+repo@tuxed.net.asc
```
-## Repository Config
+### Repository Config
Add the following to the file `/etc/yum.repos.d/eduVPN_v3-dev.repo`:
M DEVELOPMENT_SETUP.md => DEVELOPMENT_SETUP.md +16 -20
@@ 1,8 1,4 @@
----
-title: Development Setup
-description: Setup a Developer Environment
-category: dev
----
+# Development Setup
This document will describe how to set up an Let's Connect! / eduVPN
development environment for easy development and running it on your development
@@ 19,9 15,9 @@ installation of the required software, will be different.
respective OS: for DEB packages you need to be on Debian, for Fedora/CentOS
packages you need to be on Fedora.
-# Requirements
+## Requirements
-## Fedora >= 36
+### Fedora >= 36
If you are not running Fedora as your desktop OS, it is easiest to install a
VM with a desktop. In addition, install the required software (dependencies):
@@ 32,7 28,7 @@ $ sudo dnf -y install golang php-cli git composer php-date php-filter php-hash \
php-curl php-gd unzip qrencode wireguard-tools scdoc sqlite php-ldap
```
-## Debian >= 11, Ubuntu >= 22.04
+### Debian >= 11, Ubuntu >= 22.04
If you are not running Debian/Ubuntu as your desktop OS, it is easiest to
install a VM with a desktop. In addition, install the required software
@@ 44,7 40,7 @@ $ sudo apt install curl git build-essential php-gmp php-sqlite3 composer \
wireguard-tools scdoc sqlite3
```
-# Installation
+## Installation
Download the `development_setup_v3.sh` script from this repository and run it.
It will by default create a directory `${HOME}/Project/eduVPN-v3` under which
@@ 58,7 54,7 @@ $ sh ./development_setup.sh
**NOTE**: running this command can take a long time, this has to do with Go
dependency downloads (almost 1GB) to `$(HOME}/go` for some reason 🤷.
-# Testing
+## Testing
All projects have unit tests included, they can be run from the project folder,
e.g.:
@@ 66,7 62,7 @@ e.g.:
$ cd ${HOME}/Projects/eduVPN-v3/vpn-user-portal
$ make test
-# Using
+## Using
A "launch" script is included to run the PHP built-in web server to be able
to easily test the portals.
@@ 80,7 76,7 @@ Now with your browser you can connect to the user portal on
You can login with the users `foo` with password `bar` (user account) or `admin`
with password `secret` (administrator account).
-# VPN Server Configuration
+## VPN Server Configuration
To generate the OpenVPN server configuration files:
@@ 90,7 86,7 @@ To generate the OpenVPN server configuration files:
The OpenVPN server configuration files will be written to `openvpn-config`, the
WireGuard configuration files will be written to `wg-config`.
-## OpenVPN
+### OpenVPN
Unfortunately it is not that easy to start OpenVPN server processes on your
development machine as it requires certain "libexec" scripts to be in the
@@ 105,7 101,7 @@ OpenVPN, e.g.:
$ sudo systemctl start openvpn-server@default-{0,1}
```
-## WireGuard
+### WireGuard
You can copy `wg-config/wg0.conf` to `/etc/wireguard/wg0.conf` and start
WireGuard using this configuration file.
@@ 124,9 120,9 @@ file as can be found
[here](https://git.sr.ht/~fkooman/vpn-daemon#systemd), but make sure to update
the path at `ExecStart=`.
-# Development
+## Development
-## Composer
+### Composer
We'll depend on a number of packages for development purposes that you can
install first.
@@ 177,7 173,7 @@ development. You can read about their purpose on their respective websites:
The VPN software (and dependencies) contain `Makefile` targets that use this
software.
-# Modifying Code
+## Modifying Code
If you want to modify any of your code, it makes sense to switch to using your
own "fork". We'll only consider the eduVPN/LC components here and not the
@@ 222,7 218,7 @@ package from a commit. For DEB packages you need to make a release first. What
I am doing is developing on CentOS/Fedora and only when considered stable I'll
make a release after which I also create Debian packages.
-# Creating RPM packages
+## Creating RPM packages
First install all requirements on your Fedora system as described
[here](https://git.sr.ht/~fkooman/builder.rpm).
@@ 322,7 318,7 @@ Make sure you update `REPO_URL_BRANCH_LIST` and point it to your fork of the
If all goes well, you'll end up with your own RPM repository with your fork
of the package in it!
-# Software Releases
+## Software Releases
The following script is used to make official releases of the components as
`tar.xz`. It signs the source code with both PGP (for the Debian packages) and
@@ 392,7 388,7 @@ for F in release/*${V}*; do
done
```
-# Creating DEB packages
+## Creating DEB packages
Debian packages currently only work from proper releases. Updating the Debian
packages is described [here](https://git.sr.ht/~fkooman/nbuilder.deb). You can
M INSTALL_UPDATES.md => INSTALL_UPDATES.md +3 -3
@@ 11,7 11,7 @@ These instructions apply to the official installation instructions using the
`deploy_${DIST}.sh` scripts. If you installed the servers in a different way
then some changes MAY be necessary!
-# Single Server
+## Single Server
All that is needed is run the following command on your VPN server:
@@ 27,7 27,7 @@ was up.
**NOTE**: in case there are updates to system components/libraries or the
kernel you MUST reboot the system.
-## Automatic Updates
+### Automatic Updates
Create the file `/etc/cron.weekly/vpn-maint-update-system` with the following
content:
@@ 52,7 52,7 @@ not updated system libraries are used, or you are running the latest kernel.
In case of security updates it MAY be necessary to schedule updates sooner than
the weekly update.
-# Multi Server
+## Multi Server
If you are running a setup with a separate controller and node(s), you will
need to consider some extra things when installing updates. It is best to stop
M INSTANCE_DISCOVERY.md => INSTANCE_DISCOVERY.md +11 -15
@@ 1,8 1,4 @@
----
-title: Instance Discovery
-description: Obtain a list of VPN server Instances
-category: dev
----
+# Instance Discovery
**NOTE**: this is legacy. See [SERVER_DISCOVERY](SERVER_DISCOVERY.md) for the
new server discovery we are implementing in Q1-2020.
@@ 14,7 10,7 @@ VPN server they want to connect to.
This document can be used by application developers implementing the
[API](API.md).
-# Discovery File
+## Discovery File
For eduVPN the discovery file is available
[here](https://static.eduvpn.nl/disco/). Discovery files are JSON files
@@ 22,7 18,7 @@ describing the available VPN servers. The files are accompanied with a file
containing a signature as well, to make sure they were not tampered with on the
server.
-## Types
+### Types
For eduVPN we define two "types" of discovery files. One for "Secure Internet"
and one for "Institute Access".
@@ 37,11 33,11 @@ used to protect (private) networks at an organization.
eduVPN applications MUST support both discovery files and make a clear
distinction in the UI of the application between them.
-## Fetching Frequency
+### Fetching Frequency
The discovery files MUST be obtained according to these rules:
-### "Secure Internet"
+#### "Secure Internet"
This file is obtained when:
@@ 56,12 52,12 @@ This makes sure the user can manually trigger a reload after deleting the
If no "Secure Internet" server was selected, the "Secure Internet" discovery
file is NOT fetched.
-### "Institute Access"
+#### "Institute Access"
This file is ONLY obtained when the user selects to add a "Institute Access"
instance through "Add Provider". There is no automatic update here.
-## Format
+### Format
The JSON file looks like this:
@@ 93,7 89,7 @@ themselves, see [API](API.md).
A `public_key` field MAY be specified, but it is NOT used by the application,
it is only used by other VPN servers.
-## Validation
+### Validation
When downloading the instance discovery file, the signature MUST be verified as
well. The signature file is located in the same folder, but has the `.sig`
@@ 122,9 118,9 @@ The public key that is currently used is
`E5On0JTtyUVZmcWd+I/FXRm32nSq8R2ioyW7dcu/U88=`. This is a Base64-encoded
[Ed25519](https://en.wikipedia.org/wiki/Curve25519) public key.
-# Authorization
+## Authorization
-## Institute Access
+### Institute Access
Every server configured for "Institute Access" has their own OAuth server. The
application needs to (try) to start the authorization flow for each of them
@@ 133,7 129,7 @@ particular server. All "Institute Access" servers are completely independent,
the only thing in common is that they are mentioned in the "Institute Access"
discovery file.
-## Secure Internet
+### Secure Internet
Obtaining an access token from any of the instances listed in the discovery
file is enough and can then be used at all the instances. Typically the user
M LOCAL_DNS.md => LOCAL_DNS.md +8 -8
@@ 18,7 18,7 @@ is provided by your ISP.
use that one! See [Profile Config](PROFILE_CONFIG.md), look for the
`dnsServerList` option.
-# Configuration
+## Configuration
Setting a local recursive DNS server takes a few steps:
@@ 30,9 30,9 @@ Setting a local recursive DNS server takes a few steps:
server;
4. Make the VPN profiles use the "local DNS".
-## Install Unbound
+### Install Unbound
-### Fedora
+#### Fedora
```
$ sudo dnf -y install unbound
@@ 55,13 55,13 @@ $ sudo systemctl daemon-reload
$ sudo systemctl restart systemd-resolved
```
-### Debian
+#### Debian
```
$ sudo apt -y install unbound
```
-## Configure Unbound
+### Configure Unbound
You need to change the Unbound configuration. You can add the following file
to `/etc/unbound/conf.d/VPN.conf` on CentOS/Fedora, and in
@@ 98,7 98,7 @@ $ sudo systemctl enable unbound
$ sudo systemctl restart unbound
```
-## Profile Configuration
+### Profile Configuration
Modify `/etc/vpn-user-portal/config.php` for each of the VPN profiles
where you want to use "local DNS", point the `dnsServerList` entry to
@@ 118,7 118,7 @@ traffic to the DNS server(s) is routed over the VPN if you are not using a
**NOTE**: the template variables `@GW4@` and `@GW6@` are available in
vpn-user-portal >= 3.1.6.
-## Firewall
+### Firewall
In order to allow the VPN clients to reach the DNS server, the firewall needs
to be relaxed to allow traffic to `udp/53` and `tcp/53` coming from the VPN
@@ 126,7 126,7 @@ clients.
Follow the instructions [here](FIREWALL.md#local-dns)
-## Apply
+### Apply
To apply the configuration changes:
M MONITORING.md => MONITORING.md +2 -2
@@ 6,7 6,7 @@ will most likely be improved in the future if there is a need for it.
**NOTE**: this format is NOT "stable". If you depend on this in your scripting
be ready to update when new releases appear!
-# CSV
+## CSV
A simple CSV format:
@@ 23,7 23,7 @@ profiles, you can use this:
$ sudo vpn-user-portal-status | tail -n +2 | cut -d ',' -f 2 | awk '{sum+=$1}END{print sum}'
```
-# JSON
+## JSON
You can also get the output as JSON:
M REPO.md => REPO.md +11 -11
@@ 29,30 29,30 @@ CRLMAwAFCwkIBwICIgIGFQoJCAsCBBYCAwECHgcCF4AACgkQYp1+4rY93nPy0QEA
-----END PGP PUBLIC KEY BLOCK-----
```
-# Debian / Ubuntu
+## Debian / Ubuntu
-## Repository Key
+### Repository Key
```bash
$ curl https://repo.eduvpn.org/v3/deb/repo+v3@eduvpn.org.asc | sudo tee /etc/apt/trusted.gpg.d/repo+v3@eduvpn.org.asc
```
-## Repository Config
+### Repository Config
```bash
echo "deb https://repo.eduvpn.org/v3/deb $(/usr/bin/lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/eduVPN_v3.list
```
-# Fedora
+## Fedora
-## Repository Key
+### Repository Key
```bash
$ curl -O https://repo.eduvpn.org/v3/rpm/repo+v3@eduvpn.org.asc
$ sudo rpm --import repo+v3@eduvpn.org.asc
```
-## Repository Config
+### Repository Config
Add the following to the file `/etc/yum.repos.d/eduVPN_v3.repo`:
@@ 64,16 64,16 @@ gpgcheck=1
enabled=1
```
-# AlmaLinux
+## AlmaLinux
-## Repository Key
+### Repository Key
```bash
$ curl -O https://repo.eduvpn.org/v3/rpm/repo+v3@eduvpn.org.asc
$ sudo rpm --import repo+v3@eduvpn.org.asc
```
-## Repository Config
+### Repository Config
Add the following to the file `/etc/yum.repos.d/eduVPN_v3.repo`:
@@ 85,7 85,7 @@ gpgcheck=1
enabled=1
```
-# Rocky Linux
+## Rocky Linux
```bash
@@ 93,7 93,7 @@ $ curl -O https://repo.eduvpn.org/v3/rpm/repo+v3@eduvpn.org.asc
$ sudo rpm --import repo+v3@eduvpn.org.asc
```
-## Repository Config
+### Repository Config
Add the following to the file `/etc/yum.repos.d/eduVPN_v3.repo`:
M ROADMAP.md => ROADMAP.md +7 -3
@@ 1,4 1,8 @@
-# What to expect in eduVPN / Let's Connect!
+# Roadmap
+
+This document describes the roadmap
+
+## What to expect in eduVPN / Let's Connect!
If you'd like to have something added, removed, changed or change the priority:
please contact us on
@@ 8,7 12,7 @@ make your case :-)
For our current progress see our
[issue tracker](https://todo.sr.ht/~eduvpn/server).
-# Big Things
+## Big Things
Possibly only in 4.x as they are "breaking" changes, or complicated to add
(reliably) to currently installed servers:
@@ 18,7 22,7 @@ Possibly only in 4.x as they are "breaking" changes, or complicated to add
- Allow “User Defined” VPNs
– e.g. private networks for your own devices/servers (possibly P2P)
-# Smaller Things
+## Smaller Things
These may be implemented already in 3.x as they are not necessarily "breaking":
M SCALING.md => SCALING.md +7 -11
@@ 1,8 1,4 @@
----
-title: Scaling
-description: Performance/Scaling Notes
-category: documentation
----
+# Scaling
Most organizations start by deploying a single server, which can scale quite
well to ~1000 simultaneously connected clients assuming >= 16 CPU cores with
@@ 12,13 8,13 @@ There are many aspects of "scaling", and not all will be answered here, but
this document will provide input about how to design and configure your VPN
server(s) in order to handle a large amount of VPN clients.
-# One Server
+## One Server
Most simple deploys have a single server setup. So how well does that scale
with the current software? The important metric here is "concurrent connected
clients".
-## Hardware
+### Hardware
It is recommend to run "bare metal" and not on a virtual platform. One can
start with a virtual machine, and move to bare metal later to increase the
@@ 35,7 31,7 @@ possible to use 2 NICs, one to handle the VPN traffic, and one to handle the
"plain" traffic. This could potentially increase the performance by a factor of
two.
-## Server Configuration
+### Server Configuration
Gathering information from other VPN operators resulted in estimating that one
needs one CPU core for ~64 concurrent client connections. As of now
@@ 103,7 99,7 @@ connect to, and it would be better to allocate 3/4 to UDP and 1/4 to TCP as is
done in the example above. Look [here](MONITORING.md) on how to check the load
distribution on your server.
-### Certificates / Keys
+#### Certificates / Keys
As all keys/certificates are generated on the server, it may make sense to
switch to EC certificates instead of RSA. Generating RSA private keys can take
@@ 112,7 108,7 @@ switch to EC certificates instead of RSA. Generating RSA private keys can take
See the CA section of the [security document](SECURITY.md#ca) for more
information on this.
-## Client
+### Client
In order to distribute client connections over the various ports, the client
configuration is generated with one UDP and TCP port picked at random. So for
@@ 151,7 147,7 @@ remote vpn.example 443 udp
remote vpn.example 80 tcp
```
-# HA
+## HA
See [HA](HA.md) for information on "High Availbility" in order to deploy
multiple "controllers" and/or "nodes".
M SESSION_EXPIRY.md => SESSION_EXPIRY.md +2 -2
@@ 10,7 10,7 @@ authorization, and possibly provide their 2FA credentials/token as well.
The default is 90 days.
-# What to Choose?
+## What to Choose?
The default of 90 days, but you may want to deviate from this. Either by
setting it to a (much) shorter interval, for example if you want your users to
@@ 35,7 35,7 @@ to expire so users can choose a more convenient time to renew their session.
authenticates at 09:30, the next day at 09:30 their session will expire,
meaning the may have to authorize/authenticate during a video call.
-## Changing Session Expiry
+### Changing Session Expiry
You can change the session expiry by modifying
`/etc/vpn-user-portal/config.php` and set `sessionExpiry` to the value you
M SPLIT_TUNNEL.md => SPLIT_TUNNEL.md +3 -3
@@ 18,7 18,7 @@ push DNS servers to the client. If there are, then make sure to also specify
`dnsSearchDomainList`. In addition, make sure the IP address(es) of the DNS
server(s) are also included in the `routeList`.
-# Example
+## Example
We have an organization `example.local` that has two IP ranges, `10.42.42.0/24`
and `10.43.43.0/24` that clients need access to from home. The internal DNS
@@ 26,7 26,7 @@ server, on `10.1.1.1/32` is responsible for resolving the `example.local`
domain for internal servers. Only traffic to these IP ranges and the DNS server
should be allowed from the VPN server.
-# Profile Configuration
+## Profile Configuration
Configure an `office` profile in `/etc/vpn-user-portal/config.php`, e.g.:
@@ 66,7 66,7 @@ To apply the configuration changes:
$ sudo vpn-maint-apply-changes
```
-# Firewall Configuration
+## Firewall Configuration
Restricting network access for VPN clients is already documented in
[FIREWALL.md](FIREWALL.md#reject-forwarding-traffic), but just to be complete,