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
----
+# BBR
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.
M CHANGE_HOSTNAME.md => CHANGE_HOSTNAME.md +1 -1
@@ 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:
M CONTRIBUTE_TRANSLATIONS.md => CONTRIBUTE_TRANSLATIONS.md +1 -1
@@ 1,4 1,4 @@
-# Contribute translations
+# Contribute Translations
If you'd like to contribute translations to the VPN software this document
explains how.
M CUSTOM_BRANDING.md => CUSTOM_BRANDING.md +1 -1
@@ 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.
M DEPLOY_DEBIAN.md => DEPLOY_DEBIAN.md +1 -1
@@ 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
M DEPLOY_FEDORA.md => DEPLOY_FEDORA.md +1 -5
@@ 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.
M INSTALL_UPDATES.md => INSTALL_UPDATES.md +1 -1
@@ 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:
D INSTANCE_DISCOVERY.md => INSTANCE_DISCOVERY.md +0 -148
@@ 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
-[API](API.md).
-
-## 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
-server.
-
-### 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
-[this](https://download.libsodium.org/doc/bindings_for_other_languages/)
-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
- application
-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
-available.
-
-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.
M MOD_AUTH_MELLON.md => MOD_AUTH_MELLON.md +1 -1
@@ 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!
M MOD_AUTH_OPENIDC.md => MOD_AUTH_OPENIDC.md +1 -1
@@ 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:
-
-```
-SSLCertificateChainFile
-SSLCertificateFile
-SSLCertificateKeyFile
-```
-
-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
-certificate.
-
-Now hopefully all works as expected on renew!
-
-### Cleaning
-
-Remove `certbot`:
-
-```
-$ sudo dnf remove certbot
-```
-
-Remove the directory `/etc/letsencrypt` and the file
-`/etc/sysconfig/certbot.rpmsave`.
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
M MULTI_PROFILE.md => MULTI_PROFILE.md +1 -1
@@ 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,
D MULTI_PROFILE_NODE.md => MULTI_PROFILE_NODE.md +0 -8
@@ 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.
M PORTAL_ADMIN.md => PORTAL_ADMIN.md +3 -3
@@ 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
M PORT_SHARING.md => PORT_SHARING.md +1 -1
@@ 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
M RASPBERRY_PI.md => RASPBERRY_PI.md +1 -1
@@ 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
----
+# SAML
This document describes how to configure SAML authentication for deployed
systems. We assume you used the `deploy_${DIST}.sh` script to deploy the
M SCRIPT_CONNECTION_HOOK.md => SCRIPT_CONNECTION_HOOK.md +1 -1
@@ 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
M SERVER_DISCOVERY.md => SERVER_DISCOVERY.md +0 -6
@@ 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
M SERVER_DISCOVERY_SKIP_WAYF.md => SERVER_DISCOVERY_SKIP_WAYF.md +1 -1
@@ 1,4 1,4 @@
-# Skipping the SAML WAYF
+# Server Discovery - Skipping the "WAYF"
This builds on [SERVER_DISCOVERY](SERVER_DISCOVERY.md).
M SHIBBOLETH_SP.md => SHIBBOLETH_SP.md +1 -1
@@ 1,4 1,4 @@
-# Shibboleth SP
+# SAML (Shibboleth SP)
This document describes installing Shibboleth on Debian 11.
M SOURCE_ROUTING.md => SOURCE_ROUTING.md +1 -5
@@ 1,8 1,4 @@
----
-title: Source Routing
-description: Setup Source/Policy Routing
-category: advanced
----
+# Source Routing
**NOTE**: this is a WORK IN PROGRESS!