~fkooman/vpn-documentation

e359f383dab8973a353c83cec464fd7ec1cf42ab — jwijenbergh 1 year, 3 months ago 2421aca
Markdown: Fix headings for static site
M API.md => API.md +26 -26
@@ 1,4 1,4 @@
# Introduction
# API

This document describes version 3 of the API provided by eduVPN and 
Let's Connect! servers.


@@ 14,7 14,7 @@ servers with version >= 2.4.1.

The API design was finalized and is considered _stable_ from 2022-01-27.

# Standards
## Standards

We use a simple HTTP API protected by OAuth 2, following all recommendations 
of the [OAuth 2.1](https://datatracker.ietf.org/doc/draft-ietf-oauth-v2-1/) 


@@ 29,7 29,7 @@ of the changes from OAuth 2, it basically boils down:

All HTTP request MUST use HTTPS.

# Server Discovery
## Server Discovery

As there are many servers running eduVPN / Let's Connect! you need to know 
which server you need to connect to. This can be either hard-coded in the 


@@ 39,7 39,7 @@ can be implemented.
For eduVPN specific we implement "server discovery" as documented 
[here](SERVER_DISCOVERY.md).

# Server Endpoint Discovery
## Server Endpoint Discovery

A "well-known" URL is provided to figure out the OAuth and API endpoint one
has to use. The document can be retrieved from `/.well-known/vpn-user-portal`, 


@@ 64,13 64,13 @@ this API.
This file MUST be freshly retrieved before all attempts to connect to a server 
to make sure any updates to this file are discovered.

## Endpoint Location
### Endpoint Location

When fetching this document, _redirects_, e.g. `301`, `302`, `303`, MUST be 
followed, but MUST NOT allow redirect to anything else than other `https://` 
URLs, e.g. redirects to `http://` MUST be rejected.

# Authorization Endpoint
## Authorization Endpoint

The `authorization_endpoint` is used to obtain an authorization code through an
"Authorization Request". All query parameters as defined by the OAuth 


@@ 97,7 97,7 @@ a location the application can intercept.
All error conditions, both during the authorization phase AND when talking 
to the API endpoint MUST be handled according to the OAuth specification(s).

# Token Endpoint
## Token Endpoint

The `token_endpoint` is used to exchange the authorization code, as obtained
through the `redirect_uri` as part of the authorization, for an access and 


@@ 107,7 107,7 @@ access token expires.
All error conditions, both during the authorization phase AND when talking 
to the API endpoint MUST be handled according to the OAuth specification(s).

# Using the API
## Using the API

Every API call below will include a cURL example, and an example response that 
can be expected.


@@ 123,16 123,16 @@ documented above. The following API calls are available:
- "Connect" to a VPN profile (`/connect`);
- "Disconnect" from a VPN profile (`/disconnect`)

# API Calls
## API Calls

## Info
### Info

This call will show the available VPN profiles for this instance. This will 
allow the application to show the user which profiles are available.

This `GET` call has no parameters.

### Request
#### Request

Request all available VPN profiles:



@@ 142,7 142,7 @@ $ curl \
    https://vpn.example.org/vpn-user-portal/api/v3/info
```

### Response
#### Response

```
HTTP/1.1 200 OK


@@ 190,11 190,11 @@ omitted, or marked as unsupported in that VPN client. Currently `openvpn` and
`wireguard` values are supported. As an example: a WireGuard only client 
SHOULD NOT list VPN profiles that only support OpenVPN.

## Connect
### Connect

Get the profile configuration for the profile you want to connect to.

### Request
#### Request

Connect to the "Employees" profile (`employees`) and specify a WireGuard public 
key for when WireGuard will be used:


@@ 224,12 224,12 @@ header. To add it to the cURL example use e.g.
`-H "Accept: application/x-openvpn-profile"` to indicate your client only 
supports OpenVPN.

#### Profile ID
##### Profile ID

The value of `profile_id` MUST be of one of the identifiers for the profiles 
returned in the `/info` response.

#### Public Key
##### Public Key

When the WireGuard protocol is expected to be used, the `public_key` parameter 
MUST be set. The value of `public_key` MUST be a valid WireGuard public key. It 


@@ 250,7 250,7 @@ servers, generate one *per server*.
**NOTE**: a VPN client MAY opt to generate a new public / private key for 
every new call to `/connect` instead of storing it.

#### Prefer TCP
##### Prefer TCP

The `prefer_tcp` parameter is a hint for the VPN server, currently only for the 
OpenVPN protocol.


@@ 262,7 262,7 @@ The server MAY accept this and return an OpenVPN configuration with the TCP
The server MAY ignore the option, for example when the profile only supports
WireGuard, or the OpenVPN server configuration does not use TCP.

### Response
#### Response

If the profile is an OpenVPN profile you'll get the complete OpenVPN client
configuration with `Content-Type: application/x-openvpn-profile`, e.g.:


@@ 368,7 368,7 @@ PrivateKey = AJmdZTXhNRwMT1CEvXys2T9SNYnXUG2niJVT4biXaX0=
...
```

## Disconnect
### Disconnect

This call is to indicate to the server that the VPN session(s) belonging to 
this OAuth authorization can be terminated. This MUST ONLY be called when the 


@@ 398,7 398,7 @@ When talking about "System VPNs", i.e. VPN connections that are not controlled
by the user, but by the device administrator, or possibly explicitly configured
as a "System VPN" by the user, if available, these rules do not apply.

### Request
#### Request

```bash
$ curl -X POST \


@@ 408,14 408,14 @@ $ curl -X POST \

This `POST` call has no parameters.

### Response
#### Response

```
HTTP/1.1 204 No Content

```

## Error Responses
### Error Responses

Do **NOT** use the exact "Message" for string comparison in your application 
code, getting any of these (4xx) errors below indicates a problem in the 


@@ 450,7 450,7 @@ the user if so instructed by the support desk, and MAY be shown to the user in
full, however a generic "Server Error" could be considered as well, perhaps 
with a "Details..." button.

# VPN Protocol Selection
## VPN Protocol Selection

The VPN server decides which protocol will be used for the VPN connection. This
can be either OpenVPN or WireGuard. The client _is_ able to influence this 


@@ 518,7 518,7 @@ Accept: application/x-openvpn-profile, application/x-wireguard-profile
**NOTE**: if the `Accept` request header is missing, it is assumed that the 
VPN client supports both OpenVPN and WireGuard.

# Application Flow
## Application Flow

Below we describe how the application MUST interact with the API. It does NOT
include information on how to handle OAuth. The application MUST properly 


@@ 569,7 569,7 @@ application if not yet open. This allows the user to (manually)
disconnect/connect again restoring the VPN and possibly renewing the 
authorization when e.g. the authorization was revoked.

# Session Expiry
## Session Expiry

All VPN sessions have an expiry. The default (as set by the server) is 90 days. 
The server operator is able to change this. Some organizations set the session


@@ 618,7 618,7 @@ this order:
The OS notification shown to the user _MAY_ offer the "Renew Session" button 
inside the notification as well, if supported by the OS.

# History
## History

The changes made to the API documentation.


M ARCH.md => ARCH.md +1 -6
@@ 1,8 1,4 @@
---
title: Architecture
description: Description of Service Architecture
category: documentation
---
# Architecture

This is a very short overview of the server architecture for version 1.0 of 
eduVPN.


@@ 70,4 66,3 @@ machine. When run on multiple machines, the portal and server API are installed
on 1 machine, and the server node on the other machine(s).

![Architecture](img/ARCH.png)


M BGP.md => BGP.md +1 -11
@@ 1,19 1,9 @@
---
title: BGP
description: Use BGP announcements
category: advanced
author: Jørn Åne (Uninett)
---

# BGP

## Warning
*Warning*

This guide is provided as is.  The eduVPN project provides no support for BGP.


## Introduction

If your network allows it, the IP ranges used by your vpn-server-node can be obtained through BGP.  For this to work, you must know the following:

  * `neighbor` IP-address of your routers (this may differ from the default gateway)

M BRANDING.md => BRANDING.md +6 -4
@@ 1,19 1,21 @@
# Change 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.

# Installation
## Installation

## Fedora / Enterprise Linux
### Fedora / Enterprise Linux

    $ sudo dnf -y install vpn-portal-artwork-LC
    $ sudo dnf -y install vpn-portal-artwork-eduVPN

## Debian / Ubuntu
### Debian / Ubuntu

    $ sudo apt -y install vpn-portal-artwork-lc
    $ sudo apt -y install vpn-portal-artwork-eduvpn

# Configuration
## Configuration

Now you can enable the `styleName` in `/etc/vpn-user-portal/config.php`. Set it 
to `LC` (or `eduVPN`).

M CHANGE_HOSTNAME.md => CHANGE_HOSTNAME.md +10 -8
@@ 1,3 1,5 @@
# Change Hostname

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



@@ 13,30 15,30 @@ Please adapt the hostname as appropriate.

This instruction is for a _single_ server deployment.

# Hostname
## Hostname

```bash
$ sudo hostnamectl set-hostname vpn.example.com
```

# DNS
## DNS

Make sure the new hostname has an A (and AAAA) record to your VPN server IPs.

# TLS
## TLS

When your DNS is correct you can use Let's Encrypt to obtain new certificates,
or manually obtain them from your CA and install them.

# Apache
## Apache

## Fedora / EL
### Fedora / EL

Rename `/etc/httpd/conf.d/vpn.example.org.conf` to 
`/etc/httpd/conf.d/vpn.example.com.conf`. Replace all occurrences of 
`vpn.example.org` with `vpn.example.com` in this file.

## Debian / Ubuntu
### Debian / Ubuntu

Disable the old site:



@@ 49,12 51,12 @@ $ sudo a2ensite vpn.example.com
Modify `/etc/apache2/sites-available/vpn.example.com.conf` and replace all 
occurrences of `vpn.example.org` with `vpn.example.com`.

# Server Configuration
## Server Configuration

Modify `/etc/vpn-user-portal/config.php` and look at all `hostName` entries and
change them to the new hostname.

# Apply
## Apply

Run:


M DATABASE.md => DATABASE.md +17 -17
@@ 1,4 1,4 @@
# Introduction
# Database

The VPN server supports other databases than just the default 
[SQLite](https://sqlite.org/). For SQLite, no configuration is needed, it works 


@@ 21,12 21,12 @@ MariaDB/MySQL.
**NOTE (4)**: we assume you used `deploy_${DIST}_controller.sh` and 
`deploy_${DIST}_node.sh` to install the VPN service.

# Configuration
## Configuration

You can configure the database in `/etc/vpn-user-portal/config.php`, replace 
the `host`, `dbname` with the values obtained from your database administrator. 

## PostgreSQL
### PostgreSQL

Make sure you have the `php-pgsql` package installed, on Debian use `apt` 
instead of `dfn`:


@@ 46,7 46,7 @@ In `/etc/vpn-user-portal/config.php`:
Replace `host`, `dbname`, `user` and `password` with the values you obtained 
from your database administrator.

## MariaDB/MySQL
### MariaDB/MySQL

Make sure you have the `php-mysqlnd` package installed:



@@ 67,7 67,7 @@ In `/etc/vpn-user-portal/config.php`:
Replace `host`, `dbname`, `dbUser` and `dbPass` with the values you obtained 
from your database administrator.

## Database Info
### Database Info

You can show the current status of your database, this will tell you whether 
the configuration was done properly, i.e. we are able to connect to the 


@@ 80,7 80,7 @@ Required Schema Version: 2022010202
Status                 : **OK**
```

## Database Initialization
### Database Initialization

If you need to initialize the database:



@@ 92,7 92,7 @@ You can override your database configuration with `--dsn`, `--user`, `--pass`
options in case you need different credentials to perform a database 
initialization.

## Database Migration
### Database Migration

Updates to the VPN software MAY require database migrations. This will be 
indicated in the release notes of newer versions.


@@ 110,7 110,7 @@ migration.
If a migration is needed, but not performed the VPN portal will give a clear 
error message.

## Manual Initialization / Migration
### Manual Initialization / Migration

If you really want to perform every step manually, you need to look in 
`/usr/share/vpn-user-portal/schema` for the SQL schema files. The latest 


@@ 126,26 126,26 @@ CREATE TABLE version (current_version TEXT NOT NULL);
INSERT INTO version VALUES('2021123001');
```

# Database Server Installation
## Database Server Installation

As mentioned above, this is only for testing!

## PostgreSQL Installation
### PostgreSQL Installation

### Fedora
#### Fedora

```
$ sudo dnf -y install postgresql-server 
$ sudo postgresql-setup --initdb
```

### Debian
#### Debian

```
$ sudo apt -y install postgresql 
```

## PostgreSQL Configuration
### PostgreSQL Configuration

First we'll allow password authentication. Modify 
`/var/lib/pgsql/data/pg_hba.conf`. On Debian this is 


@@ 219,7 219,7 @@ vpn=>

All good!

# MariaDB Installation
## MariaDB Installation

Follow the instructions below to configure your MariaDB server:



@@ 232,7 232,7 @@ $ sudo mysql_secure_installation
You can leave most things at their defaults, but set a `root` password when 
asked, you will need it below.

## MariaDB Configuration
### MariaDB Configuration

Now you need to create a database and a user with a password.



@@ 243,7 243,7 @@ $ mysql -u root -p
Provide the `root` password, and run the following commands. Replace the name 
of the database and user if you want. Make sure you choose your own password.

### Local Access
#### Local Access

If you install the MariaDB on the same system as your VPN service, run the 
following commands:


@@ 262,7 262,7 @@ account:
$ mysql vpn -u vpn -p
```

### Remote Access
#### Remote Access

If you install the MariaDB on a different system from your VPN service, as you
SHOULD, run the following commands:

M DEPLOY_DEBIAN.md => DEPLOY_DEBIAN.md +2 -0
@@ 1,3 1,5 @@
# Deploy 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 
configure all components and will be ready for use after running!

M FIREWALL.md => FIREWALL.md +11 -11
@@ 1,4 1,4 @@
# Introduction
# Firewall

A very simple static firewall based on `iptables` is installed when running the 
deploy scripts. It allows connections to the VPN, SSH, HTTP and HTTPS ports. In 


@@ 70,7 70,7 @@ addresses in the IPv4 firewall, and the IPv6 style addresses in the IPv6
firewall. In addition, the ICMP type is different, i.e. `icmp` for IPv4 and 
`ipv6-icmp` for IPv6, see the `iptables` and `ip6tables` for examples.

# Improving the Defaults
## Improving the Defaults

The default firewall works well, but can be improved upon by updating it to 
match your deployment.


@@ 97,7 97,7 @@ This allows only SSH connections coming from `192.0.2.0/24` and
`198.51.100.0/24`. This will also prevent VPN clients from accessing the SSH 
server.

# Opening Additional VPN Ports
## Opening Additional VPN Ports

By default, one port, both for TCP and UDP are open for OpenVPN 
connections:


@@ 114,7 114,7 @@ You can easily add more by using "ranges", e.g.
-A INPUT -p tcp -m state --state NEW -m tcp --dport 1194:1197 -j ACCEPT
```

# NAT to Multiple Public IP Addresses
## NAT to Multiple Public IP Addresses

When using NAT with many clients, it makes sense to "share" the traffic over
multiple public IP addresses.


@@ 141,7 141,7 @@ specified `--to-source` range will be used, specified IPs included.
**NOTE**: for IPv6 the situation is similar, except you'd use the IPv6 range(s) 
and address(es).

# NAT to Different Public IP Addresses per Profile
## NAT to Different Public IP Addresses per Profile

When using [Multiple Profiles](MULTI_PROFILE.md), you may want to NAT to 
different public IP addresses. You could for example use:


@@ 159,7 159,7 @@ IP addresses.
**NOTE**: for IPv6 the situation is similar, except you'd use the IPv6 range(s) 
and address(es).

# Allow Client to Client Traffic
## Allow Client to Client Traffic

By default, client-to-client traffic is not allowed:



@@ 192,7 192,7 @@ the Internet, and the second only allows connectivity between the clients.
-A FORWARD -i wg0 -s 10.100.100.0/24 -d 10.100.100.0/24 -i wg0 -o wg0 -j ACCEPT
```

# Reject Forwarding Traffic
## Reject Forwarding Traffic

Sometimes you want to prevent VPN clients from reaching certain network, or 
allow them to reach only certain networks. For example in the "split tunnel" 


@@ 214,7 214,7 @@ your VPN clients, you can use the following:

**NOTE**: for IPv6 the situation is similar.

# Reject IPv6 Client Traffic
## Reject IPv6 Client Traffic

As the VPN server is "dual stack" throughout, it is not possible to "disable" 
IPv6. However, one can easily modify the firewall to prevent all IPv6 traffic


@@ 230,7 230,7 @@ This will cause all IPv6 to be rejected. The VPN becomes thus effectively
IPv4 only. You can of course also use it to reject IPv4 traffic to create an
IPv6-only VPN.

# Public IP Addresses for VPN Clients
## Public IP Addresses for VPN Clients

If you want to use [Public Addresses](PUBLIC_ADDR.md) for the VPN clients, this 
has some implications for the firewall:


@@ 241,12 241,12 @@ has some implications for the firewall:
**NOTE**: it is possible to use NAT for IPv4 and public IP addresses for IPv6,
actually this is recommended over using IPv6 NAT!

## Disabling NAT
### Disabling NAT

By removing all `POSTROUTING` rules from the "NAT" table takes care of 
disabling NAT.

## Allowing Incoming Traffic
### Allowing Incoming Traffic

The default `FORWARD` rules used are:


M FROM_2_TO_3.md => FROM_2_TO_3.md +2 -0
@@ 1,3 1,5 @@
# From v2 to v3 server

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


M GUEST_ACCESS.md => GUEST_ACCESS.md +9 -9
@@ 1,4 1,4 @@
# Introduction
# Guest Access

This document describes how to enable "Guest Access". This is a feature 
provided to the eduVPN community. It is NOT available for Let's Connect!.


@@ 13,7 13,7 @@ Netherlands by SURF can access the VPN server in Germany hosted by DFN.
this purpose. It MUST NOT be used for any other purpose like providing 
access to restricted resources on the network!

# Eligibility / Requirements
## Eligibility / Requirements

Only NRENs are able to register a server for "Guest Access". 



@@ 29,7 29,7 @@ Currently we do NOT recommend registering your VPN server in eduGAIN!
In order to enable "Guest Access" on your server you MUST have 
`vpn-user-portal` >= 3.1. In older versions it will NOT work.

# Configuration
## Configuration

The "Guest Access" functionality MUST be manually enabled.



@@ 64,7 64,7 @@ list the new "User IDs". Have your admins look on their "Account" page in the
portal so you can add them. For more information on admin accounts you can 
look [here](https://github.com/eduvpn/documentation/blob/v3/PORTAL_ADMIN.md).

# Public Key
## Public Key

We need to register your OAuth public key in our "discovery" file 
to allow all participating servers to fetch it and allow users from


@@ 80,7 80,7 @@ k7.pub.ozEaVoU0p1HezQ41.HmV1WLVuRDoPiYoa2pP0qxP1YpWdKr5AoMdV_ZWl4i4

Make note of this public key as you need it for your server's registration.

# Registration
## Registration

Please contact 
[eduvpn-support@lists.geant.org](mailto:eduvpn-support@lists.geant.org) and 


@@ 113,7 113,7 @@ provide use with the following information:

Use "_Add [${FQDN}] to Secure Internet eduVPN_" as "Subject" of the mail.
  
## Template
### Template

Subject: `Add [vpn.example.org] to Secure Internet eduVPN`



@@ 137,12 137,12 @@ Public Key: k7.pub.ozEaVoU0p1HezQ41.HmV1WLVuRDoPiYoa2pP0qxP1YpWdKr5AoMdV_ZWl4i4

Do **NOT** forget to attach the signed copy of the policy document!

# Usage
## Usage

Once deployed, it may be interesting to figure out whether your service is used
and by whom.

## Guest Users
### Guest Users

To show how many guest users there are, you can use the including tooling, 
e.g.:


@@ 172,7 172,7 @@ $ sudo sqlite3 \
    "SELECT DATE(connected_at) AS date, COUNT(DISTINCT user_id) as unique_guest_user_count FROM connection_log WHERE user_id LIKE '%@%' GROUP BY date ORDER BY connected_at"
```

## Local Users
### Local Users

When "Guest Access" is enabled, and you also have local users, you can also 
figure out who they are, depending on your server's configuration. For example,

M HA.md => HA.md +4 -4
@@ 1,4 1,4 @@
# Introduction
# High Availability (HA)

The easiest way to install the VPN service is using the `deploy_${DIST}.sh` 
script. This will install the service on a single machine. This work really 


@@ 22,7 22,7 @@ Of course, everything has trade-offs. If you are not careful, your service
could easily become _less_ available, than simply running everything on a 
Raspberry Pi in your office closet 😊

# Terminology
## Terminology

The software conceptually consists of two components that can be "split" and 
which can then run on different (virtual) systems.


@@ 54,7 54,7 @@ WireGuard, reporting to the Portal and handling the VPN connections themselves.
'----'------------'-------'-----------'---------'
```

# Handling More VPN Connections (Multi Node)
## Handling More VPN Connections (Multi Node)

If you are not so worried about _availability_, but just want to be able to 
handle more VPN connections than can be offered by a single system, e.g. you 


@@ 102,7 102,7 @@ the VPN client would simply pick another node and connect to that one.
which Node to connect to, this means if one of the nodes goes down, the client
talks again to the Portal to obtain a new configuration file.

# Making the Portal Redundant (HA Portal)
## Making the Portal Redundant (HA Portal)

If you _are_ worried about _availability_, you may want to duplicate the Portal 
as well. Obviously, this only makes sense if you have more than one node, 

M HA_PORTAL.md => HA_PORTAL.md +10 -10
@@ 1,4 1,4 @@
# Introduction
# HA Portal

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


@@ 16,7 16,7 @@ few steps:

We'll walk you through all steps in the rest of this document.

# Installation
## Installation

You can configure the "Controller / Portal" on multiple systems, using the 
`deploy_${DIST}_controller.sh`, and your node(s) using 


@@ 31,12 31,12 @@ The machines themselves SHOULD have the names `p1.vpn.example.org`,
You perform all configuration on one of the "Controllers / Portal", and then 
simple copy the configuration / data to the other(s).

# Database
## Database

In order to configure the database, perform that from one of the portals you 
just set up and follow the instructions [here](DATABASE.md).

# Memcached
## Memcached

On all of your "Controller / Portal" machines:



@@ 45,12 45,12 @@ $ sudo apt -y install memcached php-memcached
$ sudo systemctl restart php$(/usr/sbin/phpquery -V)-fpm
```

## Configuration
### Configuration

By default Memcached only listens on `localhost`. For our purpose however each
installation of the portal should be able to reach all Memcached servers. 

### Debian / Ubuntu
#### Debian / Ubuntu

Modify `/etc/memcached.conf` and change the `-l` line from `-l 127.0.0.1` to
`-l 0.0.0.0,::`


@@ 64,7 64,7 @@ $ sudo systemctl restart memcached
**NOTE**: you MUST make sure you use your firewall to prevent systems on the 
Internet from reaching your Memcached service!

### Fedora 
#### Fedora 

Modify `/etc/sysconfig/memcached` and change the `OPTIONS` line from 
`OPTIONS="-l 127.0.0.1,::1"` to `OPTIONS=""` to listen on all interfaces.


@@ 95,7 95,7 @@ Memcache again:
$ sudo systemctl restart memcached
```

### Portal
#### Portal

Modify the session configuration in `/etc/vpn-user-portal/config.php`:



@@ 113,7 113,7 @@ Modify the session configuration in `/etc/vpn-user-portal/config.php`:
first, and on `p2.vpn.example.org`, the server `p2.vpn.example.org` SHOULD come
first.

# Synchronize Configuration
## Synchronize Configuration

Some files need to be copied from one of the portals to the other(s), e.g. VPN 
CA, OAuth key, OpenVPN/WireGuard key material and HTTPS certificate.


@@ 138,7 138,7 @@ If you are using
`/etc/letsencrypt` folder to your other portals. Make sure you do this at least
every 90 days (the expiry of Let's Encrypt certificates)!

# keepalived
## keepalived

Install `keepalived`:


M IPV6.md => IPV6.md +2 -2
@@ 1,7 1,7 @@
**WORK IN PROGRESS**

# IPv6

**WORK IN PROGRESS**

The VPN server software supports both IPv4 and IPv6. We've reached a point 
in the "evolution" of the Internet that IPv4 NAT is unavoidable, but for IPv6
there is no excuse to not issue proper public IPv6 addresses to the VPN 

M LDAP.md => LDAP.md +13 -11
@@ 1,3 1,5 @@
# LDAP

This document describes how to configure LDAP. We assume you used the 
`deploy_${DIST}.sh` script to deploy the software.



@@ 6,9 8,9 @@ The LDAP integration can be used both for _authentication_ and _authorization_.
This document talks about _authentication_. See [ACL](ACL.md) for more on 
_authorization_.

# Important Notes
## Important Notes

## 3.0.2
### 3.0.2

There was an issue in `vpn-user-portal` before 3.0.2 where, when 
`userIdAttribute` was set, but not available in the LDAP result set, the user 


@@ 31,7 33,7 @@ In case you were depending on this unintended behavior, your VPN server
installation may fail to allow users to authenticate with version 3.0.2, even 
though it worked with previous versions.

# Introduction
## Introduction

It is a good idea to try with `ldapsearch` if you are not absolutely sure what
to configure. Once `ldapsearch` works, it becomes easier to configure the LDAP


@@ 58,7 60,7 @@ administrator, you need _at least_:
* The attribute to use for user authentication;
* Whether or not this attribute is part of the user's DN.

## FreeIPA
### FreeIPA

For simple [FreeIPA](https://www.freeipa.org/page/Main_Page) setups these are
sufficient. Here the `uid` we want to use for users to authenticate is part of 


@@ 75,7 77,7 @@ $ ldapsearch \
After providing the user's password, you should see all the LDAP attributes 
associated with that user account, e.g. `memberOf`, `mail`, `uid`.

## Active Directory
### Active Directory

If you are using 
[Active Directory](https://en.wikipedia.org/wiki/Active_Directory), it is 


@@ 105,7 107,7 @@ $ ldapsearch \
        "(userPrincipalName=fkooman@example.org)"
```

## Search First
### Search First

If you want to use an attribute that is NOT part of the DN, you first need to 
perform a search for the user's DN, based on the attribute + value you 


@@ 140,7 142,7 @@ $ ldapsearch \
If this works, we can use this information as explained below in the 
configuration examples.

# Configuration
## Configuration

You can configure the portal to use LDAP. This is configured in the file 
`/etc/vpn-user-portal/config.php`.


@@ 239,7 241,7 @@ or not results are returned.

This should be all to configure your LDAP!

# LDAPS
## LDAPS

In order to use LDAPS, you can use the LDAPS scheme in the `baseUri`
configuration option, e.g.:


@@ 264,7 266,7 @@ You can copy/paste the CA certificate from the certificates shown.
**NOTE**: make sure you validate this CA out of band! You MUST be sure this 
is the actual CA!

## Fedora / EL
### Fedora / EL

If you use a self signed certificate for your LDAP server perform these steps. 
If your certificate is signed by a trusted CA you do not need to do this, it


@@ 286,7 288,7 @@ You **MUST** restart `php-fpm` to pick up the changes:
$ sudo systemctl restart php-fpm
```

## Debian / Ubuntu
### Debian / Ubuntu

If you use a self signed certificate for your LDAP server perform these steps. 
If your certificate is signed by a trusted CA you do not need to do this, it


@@ 308,7 310,7 @@ You **MUST** restart `php-fpm` to pick up the changes:
$ sudo systemctl restart php$(/usr/sbin/phpquery -V)-fpm
```

# Troubleshooting
## Troubleshooting

You can use `ldapsearch` to figure out what would be the required values for
the various configuration options and test them independently of the VPN 

M MOD_AUTH_MELLON.md => MOD_AUTH_MELLON.md +10 -8
@@ 1,25 1,27 @@
# Mod auth mellon

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

This document describes how to use/configure 
[mod_auth_mellon](https://github.com/latchset/mod_auth_mellon).

# Installation
## Installation

## Fedora / Enterprise Linux
### Fedora / Enterprise Linux

First install `mod_auth_mellon`:

    $ sudo dnf -y install mod_auth_mellon

## Debian  / Ubuntu
### Debian  / Ubuntu

    $ sudo apt -y install libapache2-mod-auth-mellon

In the examples below you will not use `/etc/httpd` but `/etc/apache2` as the
base path, and for `systemctl` you use `apache2` instead of `httpd`.

# Configuration
## Configuration

Generate an SP signing key:



@@ 75,7 77,7 @@ If you also want to use authorization based on an attribute, e.g.
`eduPersonEntitlement` or `eduPersonAffiliation` you can set the 
`permissionAttributeList` as well.

## Examples
### Examples

Using `uid`:



@@ 115,9 117,9 @@ This will _serialize_ the XML node to a string using the IdP and SP entity ID
together with the eduPersonTargetedId _value_. If you are using the "Name ID", 
very much not recommended, you can set `userIdAttribute` to `MELLON_NAME_ID`.

# Apache
## Apache

## Fedora / Enterprise Linux
### Fedora / Enterprise Linux

    <VirtualHost *:443>



@@ 167,7 169,7 @@ very much not recommended, you can set `userIdAttribute` to `MELLON_NAME_ID`.

    </VirtualHost>

## Debian / Ubuntu
### Debian / Ubuntu

    <VirtualHost *:443>


M MOD_AUTH_OPENIDC.md => MOD_AUTH_OPENIDC.md +8 -8
@@ 1,28 1,28 @@
# Introduction
# 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 
[mod_auth_openidc](https://github.com/zmartzone/mod_auth_openidc).

# Installation
## Installation

## Fedora
### Fedora

```
$ sudo dnf install mod_auth_openidc
$ sudo systemctl restart httpd
```

## Debian / Ubuntu
### Debian / Ubuntu

```
$ sudo apt install libapache2-mod-auth-openidc
$ sudo systemctl restart apache2
```

# Configuration
## Configuration

## OpenID Connect
### OpenID Connect

The below instructions will show you what to do at the _minimum_ to get your
RP working.


@@ 43,7 43,7 @@ $ pwgen -s 64 -n 1

Once you have/know all values configure the "VirtualHost" as mentioned below.

## Virtual Host
### Virtual Host

Modify your Apache "Virtual Host" by changing 
`/etc/apache2/sites-available/vpn.example.org.conf` (Debian / Ubuntu) or 


@@ 101,7 101,7 @@ On Debian / Ubuntu:
$ sudo systemctl restart apache2
```
    
## VPN Portal
### VPN Portal

Modify `/etc/vpn-user-portal/config.php` and set:


M MOD_MD.md => MOD_MD.md +1 -1
@@ 1,4 1,4 @@
### mod_md
# Apache mod_md

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


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

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 +3 -3
@@ 1,4 1,4 @@
# Introduction
# Multi Profile

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,


@@ 16,7 16,7 @@ Below, we will end up with two profiles:
You may also need to take a look at the [SELinux](SELINUX.md) instructions when
running on Fedora.

# Configuration
## Configuration

The configuration file `/etc/vpn-user-portal/config.php` needs to be 
modified, you can remove the `default` profile that was there if you didn't


@@ 55,7 55,7 @@ more flexibility to move to a setup with multiple machines in the future.
**NOTE**: if you add/modify UDP and TCP ports you may also need to update the 
[firewall](FIREWALL.md)!

## Apply Changes
### Apply Changes

To apply the configuration changes:


M MULTI_PROFILE_NODE.md => MULTI_PROFILE_NODE.md +1 -1
@@ 1,4 1,4 @@
# Introduction
# 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 

M PHP_SAML_SP.md => PHP_SAML_SP.md +1 -7
@@ 1,10 1,4 @@
---
title: PHP-SAML-SP
description: SAML Authentication using php-saml-sp
category: authentication
---

## Introduction
# PHP Saml SP

Very simple, secure SAML SP written in PHP.


M PORTAL_ADMIN.md => PORTAL_ADMIN.md +2 -0
@@ 1,3 1,5 @@
# Portal admin

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


M PORT_SHARING.md => PORT_SHARING.md +2 -0
@@ 1,3 1,5 @@
# 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 
possible to connect to the VPN service using both `udp/443` and `tcp/443`. A 

M RADIUS.md => RADIUS.md +3 -1
@@ 1,3 1,5 @@
# Radius

This document describes how to configure RADIUS for deployed systems. We assume 
you used the `deploy_${DIST}.sh` script to deploy the software. Below we assume 
you use `vpn.example`, but modify this domain to your own domain name!


@@ 25,7 27,7 @@ for instructions on how to configure LDAP.
**NOTE**: RADIUS authentication is no longer supported on PHP 8.x so it will
only work on Debian 11 as of this moment and not on Fedora or Ubuntu.

# Configuration
## Configuration

First install the PHP module for RADIUS:


M README.md => README.md +11 -11
@@ 1,4 1,4 @@
# Introduction
# About

This is the eduVPN/Let's Connect! documentation repository. This repository 
targets administrators and developers. It contains information on how to deploy 


@@ 17,7 17,7 @@ try to find the contact information of your organization
contact us at 
[eduvpn-support@lists.geant.org](mailto:eduvpn-support@lists.geant.org).

# Supported Versions
## Supported Versions

| Version                                              | Release Date | OS Support                                                   |  EOL*      |
| ---------------------------------------------------- | ------------ | ------------------------------------------------------------ | ---------- |


@@ 32,7 32,7 @@ running that version anymore, whichever comes first.
We **only** support the particular release on operating systems that are still 
supported by their vendor!

# Features
## Features

This is an (incomplete) list of features of the VPN software:



@@ 63,12 63,12 @@ This is an (incomplete) list of features of the VPN software:
- Support multiple deployment scenarios [simultaneously](MULTI_PROFILE.md);
- [SELinux](SELINUX.md) fully enabled (on Fedora);

# Client Support
## Client Support

See [Client Compatibility](CLIENT_COMPAT.md) for more information about the 
supported VPN clients.

# Deployment
## Deployment

**NOTE**: if you plan to install and run a eduVPN/Let's Connect! server please 
subscribe to the mailing list 


@@ 76,7 76,7 @@ subscribe to the mailing list
for announcements of updates and discussion about running 
eduVPN/Let's Connect!.

# IRC Contact
## IRC Contact

You can also join IRC for _technical_ questions/discussions/feedback on 
[Libera.Chat](https://libera.chat/), channel `#eduvpn`. Please stick around for 


@@ 85,7 85,7 @@ a while to wait for a response!
You can also easily use the [Web Chat](https://web.libera.chat/#eduvpn) if you 
can't be bothered to setup an IRC client. See you there!

## Instruction Videos
### Instruction Videos

**NOTE**: these videos are for eduVPN / Let's Connect 2.x and still need to
be updated for 3.x:


@@ 93,7 93,7 @@ be updated for 3.x:
- [Basic eduVPN/Let's Connect! Server Installation](https://www.youtube.com/watch?v=yBItHovq4AU)
- [Integrate your Active Directory via LDAP with eduVPN/Let's Connect!](https://www.youtube.com/watch?v=qwf0RZ8YK9A)

## Supported Operating Systems
### Supported Operating Systems

- [Debian](DEPLOY_DEBIAN.md) 11 (`x86_64`) 
- [Ubuntu](DEPLOY_DEBIAN.md) 22.04 (`x86_64`) 


@@ 110,12 110,12 @@ rebooted before you install the software!
**NOTE**: if you want to deploy on multiple machines for load balancing, please 
follow [these](HA.md) instructions!

# Development
## Development

If you want to set up your own server development environment see 
[DEVELOPMENT_SETUP](DEVELOPMENT_SETUP.md).

# License 
## License 

This work (this documentation repository) is licensed under a Creative Commons 
Attribution-ShareAlike 4.0 International License.


@@ 125,7 125,7 @@ See [LICENSE](LICENSE).
The VPN server software is licensed under the 
[AGPLv3+](https://www.gnu.org/licenses/agpl-3.0.en.html).

# Security Contact
## Security Contact

If you find a security problem in the code, the deployed service(s) and want to
report it responsibly, contact [fkooman@tuxed.net](mailto:fkooman@tuxed.net). 

M SBOM.md => SBOM.md +1 -1
@@ 1,4 1,4 @@
# Introduction
# SBOM

This page lists ALL software, including dependencies, of the _production_ 
releases of eduVPN / Let's Connect! It does _not_ include installation or 

M SCRIPT_CONNECTION_HOOK.md => SCRIPT_CONNECTION_HOOK.md +2 -0
@@ 1,3 1,5 @@
# 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 
exists in the LDAP server, or trigger firewall modifications in a remote 

M SELINUX.md => SELINUX.md +3 -1
@@ 1,9 1,11 @@
# SELinux

If you used the `deploy_${DIST}.sh` script on CentOS, Red Hat Enterprise Linux 
or Fedora, your VPN server has SELinux fully enabled and configured. If you 
make changes to the configuration, you MAY need to update the SELinux 
configuration.

# OpenVPN 
## OpenVPN 

By default, OpenVPN is not allowed to listen on any other ports than `udp/1194` 
and `tcp/1194`.

M SERVER_DISCOVERY_SKIP_WAYF.md => SERVER_DISCOVERY_SKIP_WAYF.md +0 -9
@@ 1,16 1,7 @@
---
title: Avoid Organization Selection
description: Avoid Browser Organization Selection in Identity Federations
category: dev
---


# Skipping the SAML WAYF

This builds on [SERVER_DISCOVERY](SERVER_DISCOVERY.md).

## Introduction

Most "Secure Internet" servers use SAML to authenticate users and have a WAYF 
(Where Are You From) in the browser to redirect users to the 
IdP of the organization chosen by the user for the actual authentication. 

M SHIBBOLETH_SP.md => SHIBBOLETH_SP.md +7 -5
@@ 1,8 1,10 @@
# Shibboleth SP

This document describes installing Shibboleth on Debian 11.

# Installation
## Installation

## Debian 11
### Debian 11

```
$ sudo apt install libapache2-mod-shib


@@ 10,7 12,7 @@ $ sudo shib-keygen -n sp-encrypt
$ sudo shib-keygen -n sp-signing
```

# Configuration
## Configuration

Modify `/etc/shibboleth/shibboleth2.xml`:



@@ 46,7 48,7 @@ $ sudo systemctl restart shibd
Next: register your SP in your identity federation, or in your IdP. The
metadata URL is typically `https://vpn.example.org/Shibboleth.sso/Metadata`.

### Apache
#### Apache

In `/etc/apache2/sites-available/vpn.example.org.conf` add the following:



@@ 100,7 102,7 @@ $ sudo systemctl restart apache2
make sure they are correctly enabled/set in 
`/etc/shibboleth/attribute-map.xml`.

### Portal
#### Portal

In order to configure the VPN portal, modify `/etc/vpn-user-portal/config.php`
and set the `authModule` and `ShibAuthModule` options:

M TRACEABLE_NAT.md => TRACEABLE_NAT.md +1 -10
@@ 1,14 1,5 @@
---
title: Traceable NAT
description: Make NAT users tracable using a static iptables configuration
category: advanced
author: Jørn Åne de Jong (Uninett)
---

# Traceable NAT

## Introduction

When using NAT, it is hard to identify the user behind an action, because every uses has the same outgoing IP address.
A solution to this could be Netflow, but that requires Netflow to be installed on every eduVPN host, which can be a hassle.



@@ 116,7 107,7 @@ You will see a lot of lines such as
Port ranges are shown at the end of the line. Scroll with the arrow keys or PgUp/PgDown and find the line that matches your source port number.
You have now found the internal IPv4 address that was involved in the incident.  This internal IP address (on the left) can be matched to a user through the eduVPN portal (webinterface).

# Example Script
## Example Script

`vpn-generate-natfw.php`:


M WIREGUARD.md => WIREGUARD.md +4 -4
@@ 1,22 1,22 @@
# Introduction
# WireGuard

As WireGuard is new in 3.x, this document will try to dive into some more 
detail regarding how it works.

# Configuration
## Configuration

WireGuard in eduVPN / Let's Connect! has a lot less toggles than OpenVPN so 
should be easier to configure. See the "WireGuard" 
[section](PROFILE_CONFIG.md#wireguard) for more information. There is also the
"global" option to set the WireGuard port. By default this is `51820`.

# Comparison with OpenVPN
## Comparison with OpenVPN

There are a number of differences between OpenVPN and WireGuard. Most of them 
are summed up in 
[this](https://www.tuxed.net/fkooman/blog/taming_wireguard.html) blog post.

# What to Use?
## What to Use?

It is possible to configure profiles to support both OpenVPN and WireGuard 
simultaneously. We recommend to use WireGuard whenever possible, and only