c6ae75db1a16970c361f6025a45c4d4984c2d14e — François Kooman 2 months ago 9d0c45f
fix some more headers, delete some obsolete docs
M BBR.md => BBR.md +1 -5
@@ 1,8 1,4 @@
title: Bottleneck Bandwidth and Round-trip propagation time (BBR)
description: Changing Congestion Control Algorithm
category: advanced

There's this shiny 
[BBR](https://en.wikipedia.org/wiki/TCP_congestion_control#TCP_BBR) congestion 

M BRANDING.md => BRANDING.md +1 -1
@@ 1,4 1,4 @@
# Change branding
# Portal Branding

This document describes how to add the Let's Connect! or eduVPN branding to 
your server installation. By default a simple "plain" branding is used.

@@ 1,4 1,4 @@
# Change Hostname
# Changing Server Hostname

In case you want to change the hostname of your VPN server, you need to follow
these steps:

@@ 1,4 1,4 @@
# Contribute translations
# Contribute Translations

If you'd like to contribute translations to the VPN software this document
explains how.

@@ 1,4 1,4 @@
# Custom branding
# Custom Branding

This document describes how to apply your own branding (style and e.g. logo) to
the portal.

@@ 1,4 1,4 @@
# Deploy Debian
# Deploying on Debian

For simple one server deployments and tests, we have a deploy script available 
you can run on a fresh Debian 11 or Ubuntu 22.04 installation. It will 

M DEPLOY_EL.md => DEPLOY_EL.md +1 -5
@@ 1,8 1,4 @@
title: Deploying on EL
description: Install and Maintain eduVPN/Let's Connect! on EL
category: installation
# Deploying on Enterprise Linux

For simple one server deployments and tests, we have a deploy script available 
you can run on a fresh EL installation. It will configure all components 

@@ 1,8 1,4 @@
title: Deploying on Fedora
description: Install and Maintain eduVPN/Let's Connect! on Fedora
category: installation
# Deploying on Fedora

For simple one server deployments and tests, we have a deploy script available 
you can run on a fresh Fedora installation. It will configure all components 

M FROM_2_TO_3.md => FROM_2_TO_3.md +1 -1
@@ 1,4 1,4 @@
# From v2 to v3 server
# Server Upgrade from 2.x to 3.x

This document will help you migrate your existing server from eduVPN / Let's 
Connect! 2.x to 3.x.

M HTTP_PROXY.md => HTTP_PROXY.md +1 -5
@@ 1,8 1,4 @@
title: HTTP Proxy
description: Redirect VPN traffic over a HTTP proxy
category: advanced
# HTTP Proxy

Today we will setup a HTTP proxy to tunnel OpenVPN client traffic over. We only
care about CentOS 7 at this stage.

@@ 1,4 1,4 @@
# Install Updates
# Installing Updates

This document will explain how to update your VPN server(s). This document is 
split in two parts:

@@ 1,148 0,0 @@
# Instance Discovery

**NOTE**: this is legacy. See [SERVER_DISCOVERY](SERVER_DISCOVERY.md) for the 
new server discovery we are implementing in Q1-2020.

Applications can use "Instance Discovery" to obtain a list of known servers to
show in the application instead of asking the user to provide the FQDN of the
VPN server they want to connect to.

This document can be used by application developers implementing the 

## Discovery File

For eduVPN the discovery file is available 
[here](https://static.eduvpn.nl/disco/). Discovery files are JSON files 
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

### Types

For eduVPN we define two "types" of discovery files. One for "Secure Internet" 
and one for "Institute Access".

The "Secure Internet" list contains VPN servers the user can connect to after 
"authorizing" at one of the listed servers. See [Guest Usage](GUEST_USAGE.md).

The "Institute Access" list contains VPN servers that typically only allow 
users from the organization itself to connect to it. These servers are 
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

The discovery files MUST be obtained according to these rules:

#### "Secure Internet"

This file is obtained when:

1. no "Secure Internet" instance is configured yet (or were removed) and the 
   user selects to add a "Secure Internet" instance through "Add Provider";
2. a "Secure Internet" instance is already configured, in that case it is 
   fetched automatically, but NOT more than once a week (7 days).

This makes sure the user can manually trigger a reload after deleting the 
"Secure Internet" server and then trying to add it again.

If no "Secure Internet" server was selected, the "Secure Internet" discovery 
file is NOT fetched.

#### "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

The JSON file looks like this:

        "authorization_type": "...",
        "instances": [

The `authorization_type` can be either `local` or `distributed` indicating 
whether or not the OAuth tokens obtained from those servers can be used at 
other VPN servers or not. See [Authorization](#authorization).

The `instances` key has an array with objects, in the most simple form:

        "base_uri": "https://demo.eduvpn.nl/",
        "display_name": "Demo",
        "logo": "https://static.eduvpn.nl/disco/img/demo.png"

The API's [Multi Language Support](API.md#multi-language-support) also applies 
here for both the `display_name` and `logo` fields!

The `base_uri` field can be used to perform the API Discovery of the instances 
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

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` 
extension, e.g. `https://static.eduvpn.nl/disco/secure_internet.json.sig`.

These signatures can be verified by e.g. using 
[libsodium](https://download.libsodium.org/doc/). The signature file contains a
Base64 encoded string string. See 
document for various language bindings.

The flow:

1. Download e.g. `secure_internet.json`;
2. Download matching signature file, e.g. `secure_internet.json.sig`;
3. Verify the signature using libsodium and the public key stored in your 
4. If you already downloaded the file before, verify the `seq` field of the new 
   file is higher than in the current file;
5. Overwrite the file you already have if `seq` was incremented.

The `signed_at` key is just informational and MUST NOT be relied on to be 

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

### 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 
individually. This of course only succeeds if the user has an account at that 
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

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
has the ability to obtain only an access token at one of the listed instances, 
because only there they have an account, so the user MUST obtain an access 
token at that instance.

This is a bit messy from a UX perspective, as the user does not necessarily 
know for which instance they have an account. In case of eduVPN this will most
likely be the instance operated in their institute's home country. So students
of the University of Amsterdam will have to choose "The Netherlands" first.

When API discovery is performed, the keys for 
`authorization_endpoint` and `token_endpoint` for the specific instance MUST
be ignored. Refreshing access tokens MUST also be done at the original OAuth
server that was used to obtain the access token.

@@ 1,4 1,4 @@
# Mod auth mellon
# SAML (mod_auth_mellon)

Below we assume you use `vpn.example`, but modify this domain to your own 
domain name!

@@ 1,4 1,4 @@
# Mod Auth OpenIDC
# OpenID Connect (mod_auth_openidc)

This module configures the Apache web server to operate as an OpenID Connect 
Relying Party (RP) towards an OpenID Connect Provider (OP) using 

D MOD_MD.md => MOD_MD.md +0 -60
@@ 1,60 0,0 @@
# Apache mod_md

**NOTE**: I am experimenting with this since 2021-08-08!

It is possible to manage SSL certificates from Let's Encrypt through Apache 
directly with [mod_md](https://httpd.apache.org/docs/2.4/mod/mod_md.html) 
without the need for `certbot`. This should make things more robust.

$ sudo dnf -y install mod_md

In `/etc/httpd/conf.d/vpn.example.org.conf`, outside the `<VirtualHost>`:

MDomain vpn.example.org
MDContactEmail admin@example.org
MDCertificateAgreement accepted
MDStapling on

From the `<VirtualHost>` section you can remove the following lines:


You can remove the following lines from `/etc/httpd/conf.d/ssl.conf`:

SSLUseStapling          on
SSLStaplingResponderTimeout 5
SSLStaplingReturnResponderErrors off
SSLStaplingCache shmcb:/run/httpd/ssl_stapling(128000)

Restart Apache:

$ sudo systemctl restart httpd && sleep 5 && sudo systemctl reload httpd

On the first (re)start the certificat is obtained from Let's Encrypt, after
that succeeds a (graceful) restart is required in order to active the 

Now hopefully all works as expected on renew!

### Cleaning

Remove `certbot`:

$ sudo dnf remove certbot

Remove the directory `/etc/letsencrypt` and the file 

M MULTI_NODE.md => MULTI_NODE.md +1 -1
@@ 1,4 1,4 @@
# Multi Node
# Multi Node Deployments

Setting up multiple VPN nodes is one part of making the VPN service 
"High Available". The other is setting up a redundant portal. A complete 

@@ 1,4 1,4 @@
# Multi Profile
# Multi Profile Deployments

It is possible to add additional "profiles" to a VPN service. This is useful 
when you for example have two categories of users using the same VPN server,

@@ 1,8 0,0 @@
# Multi Profile Node

As shown in the [Multi Profile](MULTI_PROFILE.md) and 
[Multi Node](MULTI_NODE.md) documentation it is possible to define multiple 
profiles, and run those profiles on multiple nodes.

We updated [Multi Node](MULTI_NODE.md) to also include the scenario where 
you have multiple profiles, so this document is obsolete.

M PHP_SAML_SP.md => PHP_SAML_SP.md +1 -1
@@ 1,4 1,4 @@
# PHP Saml SP
# SAML (php-saml-sp)

Very simple, secure SAML SP written in PHP.

@@ 1,4 1,4 @@
# Portal admin
# Portal Administration

Certain users can be "promoted" to admin in the VPN portal. This can be done in
two ways, based on either

@@ 10,7 10,7 @@ The User ID based "admin" authorization is the simplest. However, if the
admins regularly change, or are already based on a certain role exposed through 
the identity management system, using permissions may make more sense.

### User ID
## User ID

Modify `/etc/vpn-user-portal/config.php` and add the user IDs to the 
`adminUserIdList`, e.g.:

@@ 22,7 22,7 @@ Modify `/etc/vpn-user-portal/config.php` and add the user IDs to the
This is the simplest solution. To view the user ID of your account, you can use 
the "Account" page when logged into the portal.

### Permission
## Permission

When the "admins" are already decided on through the identity management 
system, e.g. LDAP or SAML, it makes sense to use that "permission" / "role" to 

@@ 1,4 1,4 @@
# Port sharing
# Port Sharing

This document describes how to configure your VPN server in such a way as to
make it most likely people can connect to it. This is done by making it 

@@ 1,4 1,4 @@
# Deployment on a Raspberry Pi
# Raspberry Pi Deployment

Because, why not. When developing technology, what use is it when you can't 
run it on the smallest and cheapest of devices? Why do we always need the 

M SAML.md => SAML.md +1 -5
@@ 1,8 1,4 @@
title: SAML
description: Enable SAML Authentication
category: authentication

This document describes how to configure SAML authentication for deployed
systems. We assume you used the `deploy_${DIST}.sh` script to deploy the 

@@ 1,4 1,4 @@
# Script connection hook
# Script Connection Hook

This page documents how to launch a (custom) script when a VPN client connects, 
and/or disconnects. This can for example be used to verify if a user still 

@@ 1,9 1,3 @@
title: Server Discovery
description: Server Discovery for VPN Applications
category: dev

# Server Discovery

**NOTE**: the format of `v2` is stable as of 2020-08-26. Format changes will

@@ 1,4 1,4 @@
# Skipping the SAML WAYF
# Server Discovery - Skipping the "WAYF"


@@ 1,4 1,4 @@
# Shibboleth SP
# SAML (Shibboleth SP)

This document describes installing Shibboleth on Debian 11.

@@ 1,8 1,4 @@
title: Source Routing
description: Setup Source/Policy Routing
category: advanced
# Source Routing

**NOTE**: this is a WORK IN PROGRESS!