docs/docs/tunneling/fastd.md

# Fastd tunneling

This document will help you get peered over a layer-2/3 VPN using `fastd`.

## Installing dependencies

This document assumes that you are using a Linux system (as one should) and a systemd-based system, the latter part is not really a requirement but it just for having things start on system startup.

The following need to be installed:

1. `fastd`
    * This is the layer 2 tunnelling daemon we use to link up machines essentially providing a virtual ethernet network between the two nodes we want to link.
2. Optional: `yggdrasil`, `cjdns`
    * These are both overlay networks that can be used if clear-net access is not possible.
    * We recommend you still use them as they can run without internet access too and redundancy is a goal of CRXN and having a diverse peering setup

## Setting up a tunnel

The next step is to setup a tunnel. You will have to contact someone to get the following:

1. `ip:port` pairing details
    * The endpoint of their *fastd* instance
2. `public key`
    * You will need their public key which will be used to secure the connection to them such that traffic is encrypted (CRXN traffic and babeld router messages)

Create a file with the template and instructions below in `/etc/fastd/crxn/fastd.conf`:

```
# The interface that will connect to the virtual ethernet network fastd connects us to
mode multitap;

# The encryption method (don't change this unless you need to)
method "salsa2012+umac";
method "salsa2012+poly1305";
method "salsa20+umac";
method "salsa20+poly1305";

# Bind to and listen for incoming connections on this address and port
bind [::]:<port>;

# Secret key (you generate this)
secret "<secret key>";

# Do not forward traffic for others
forward no;

# Setup a peer to allow incoming connections from or initiate a connection too
peer "<peerName>"
{
    remote <type> "<hostname>" port <port>;
    key "<peer's public key>";
    interface "%n";
    float yes;
}

```

If your system uses ifconfig append
```
# On interface rise run
on up "ifconfig $INTERFACE up";
on down "ifconfig $INTERFACE down";
```

If your system uses ip append
```
on up "ip link set dev $INTERFACE up";
on down "ip link set dev $INTERFACE down";
```

The template needs to have the following filled in:

1. `<port>`
    * The port to bind to and listen on for incoming connections from your peer's daemon (if his daemon initiates the connection first)

Now you must run the following:

```
fastd --generate-key
```

Then save the *public key* and the *private key*. **Note:** You must give your peer your *public key*.

2. `"<secret key>"`
    * This must be the *private key* you generated earlier


Now we need to fill in the peer details of the node you are connecting to:

1. `"<peerName>"`
    * Sets the interface name of the connection with the peer to crxn`<peerName>`
2. `<type>`
    * Set this to either `ipv4` or `ipv6` depending of the address being used to connect to the remote peer. This parameter is optional and can be omitted.
3. `"<hostname>"`
    * Set this to the remote peer's fastd address
4. `"<port>`
    * Set this to the remote peer's fastd port
5. `"<peer's public key>"`
    * Set this to your peer's public key
6. `interface "%n";`
    * This sets the peer name as the interface name. If this interface name should be different, it can be adjusted here.

> The `float yes` is to allow the peer with the provided public key to connect to you using a source address **other** than the one specified (as fastd does authenticate against that). The parameter is optional.

### Modes

Fastd can provide a tunnel with `multitap` mode on layer 2 or a tunnel with `tun` mode on layer 3. Note that the fatsd has 20 bytes less overhead when using tun.

### Methods

fastd supports various transmission encryptions. The encryption and authentication recommended by fastd is `salsa2012+umac`. If you specify multiple encryption methods, the first one specified is preferred. The others are used as fallbacks if the peer does not support the preferred one.
fastd has three groups of transmission ciphers:
  - Encrypt and Authenticate
  - Authenticate Only
  - Transfer Only without Authentication

It should be noted that poly1305 is very slow on embedded systems and AES is very slow without OpenSSL.
When fastd is used without encryption or authentication, the data is authenticated only by the sender IP address. This authentication can be disabled with `float yes;`.

### MTU

The default MTU of a fastd tunnel is 1500 bytes. However, this can be problematic if the Internet uplink also has an MTU of 1500 or less. In this case IP fragmentation can occur. This is usually something you want to avoid.

To calculate the appropriate MTU, you must first calculate the fastd overhead:
The default overhead is 28. If the `null` method is used, add 1, if the `null@l2tp` method is used, add 8, and for all other methods, add 24. If TAP is used instead of TUN, add 14. If the tunnel is established over IPv6, add 20.
Now calculate the MTU of the uplink (often 1500) minus the number you just calculated and you get the MTU that must be used in the fastd tunnel.
You can configure this with the parameter `mtu`:
```
mtu <mtu>;
```
Replace `<mtu>` with the calculated number.

You can either write this statement in the configuration file. Then it applies to all configured peers. Alternatively, you can put it in the `peer` block on a per-peer basis.

### Starting and maintaining the daemon

You can then start the daemon as follows:

```
sudo fastd -c /etc/fastd/crxn/fastd.conf
```

### Systemd unit

Fastd can also be set up with systemd units.

Run `systemctl start fastd@crxn` to bring up the tunnel
Run `systemctl stop fastd@crxn` to bring down the tunnel

To enable the systemd unit on startup run `systemctl enable fastd@crxn`

## Further links

- [fastd documentation](https://fastd.readthedocs.io/en/stable/)
- [fastd mtu documentation](https://fastd.readthedocs.io/en/stable/manual/mtu.html)
- [Encryption & authentication methods in fastd](https://fastd.readthedocs.io/en/stable/manual/methods.html)