~fkooman/vpn-documentation

6f9b0dfe65f87fc0b857519b3b26c11bdb852231 — jwijenbergh 1 year, 3 months ago e359f38
Fix more headings
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,