GVPE(5)

✨ GVPE(5) — GNU Virtual Private Ethernet ✨

okay bestie, welcome to gvpe(5), the vibe-check document for the GNU Virtual Private Ethernet suite 💖 no cap, this one's a whole journey — intro to VPNs first, then the actual GVPE implementation. let's go 🦋

---

🌸 NAME 🌸

GNU-VPE — it's the overview of the GNU Virtual Private Ethernet suite, periodt ✨

---

🎀 DESCRIPTION 🎀

GVPE is a suite built to give you a virtual private network across multiple nodes over an untrusted network 🫶 This doc first does the lil "what even is a VPN" intro, then gets into how GVPE specifically does the thing.

---

💭 WHAT IS A VPN? 💭

VPN is an acronym — it stands for these three:

🦋 Virtual

Virtual means no physical network gets created (obviously, bestie), but a network is emulated by building a bunch of tunnels between the member nodes — encapsulating data and yeeting it over another transport network.

Usually the emulated network is a normal IP or Ethernet, and the transport network is the Internet. But using a VPN system like GVPE to connect nodes over other untrusted networks — like a Wireless LAN — is not uncommon.

🔒 Private

Private means non-participating nodes can't decode ("sniff") packets and can't inject ("spoof") them either. So nodes can connect over untrusted networks like the public Internet with zero fear of being eavesdropped, while still being able to trust data from the other nodes 💅

And with GVPE specifically? Even participating nodes can't sniff packets headed to other nodes, and they can't spoof packets pretending to come from other nodes. So communication between any two nodes is private to those two nodes. iconic.

🌈 Network

Network means more than two parties can join in — so for example you can hook up multiple branches of a company into one single network. A lot of so-called "VPN" solutions only make point-to-point tunnels, which you then have to stack to build bigger networks.

GVPE gives you a true multi-point network where any number of nodes can participate — at least a few dozen in practise, and the theoretical limit is 4095 nodes 👑

---

👑 GVPE DESIGN GOALS 👑

💜 SIMPLE DESIGN

Cipher, HMAC algorithms and other key parameters have to be selected at compile time — this means only the algorithms you actually need get linked in. It also makes the crypto part of the source super transparent and easy to inspect, and last not least it makes it possible to hardcode the layout of all packets right into the binary. GVPE goes a step further and internally reserves blocks of the same length for all packets, which basically deletes any possibility of buffer overflows, because there's only a single type of buffer and it's always fixed length. slay.

🍓 EASY TO SETUP

A few lines of config — and yes, the config file is shared unmodified between all hosts — plus generating an RSA key-pair on each node is enough to make it work. that's it. that's the whole setup. 🎀

🔥 MAC-BASED SECURITY

Since every host has it's own private key, other hosts can't spoof traffic from this host. That makes it possible to filter packets by MAC address — e.g. to ensure that packets from a specific IP address genuinely come from a specific host associated with that IP, and not from some other host. no impersonation allowed, bestie 💅

---

🌟 PROGRAMS 🌟

Gvpe ships with two programs: one daemon (gvpe) and one control program (gvpectrl).

🧚 gvpectrl

This one is used to generate the keys, check and give an overview of of the configuration, and to control the daemon (restarting etc.). it's the lil remote control 🫶

👑 gvpe

This is the daemon that establishes and maintains connections to the other network nodes. It should be run on the gateway of each VPN subnet. main character energy, honestly.

---

🌈 COMPILETIME CONFIGURATION 🌈

Please have a look at the gvpe.osdep(5) manpage for platform-specific information 👀

Gvpe hardcodes most encryption parameters. While this reduces flexibility, it makes the program much simpler and helps make buffer overflows impossible under most circumstances.

Here are a few recipes for compiling your gvpe, showing the extremes — fast, small, insecure OR slow, large, more secure — between which you should choose:

---

🏃 AS LOW PACKET OVERHEAD AS POSSIBLE

./configure --enable-hmac-length=4 --enable-rand-length=0

Minimize the header overhead of VPN packets — the above will result in only 4 bytes of overhead over the raw ethernet frame.

⚠️ This is an insecure configuration, because a HMAC length of 4 makes collision attacks almost trivial. bestie. do not.

---

⚡ MINIMIZE CPU TIME REQUIRED

./configure --enable-cipher=bf --enable-digest=md4

Use the fastest cipher and digest algorithms currently available in gvpe.

💀 MD4 has been broken and is quite insecure, though, so using another digest algorithm is recommended.

---

🛡️ MAXIMIZE SECURITY

./configure --enable-hmac-length=16 --enable-rand-length=12 --enable-digest=ripemd610

This uses a 16 byte HMAC checksum to authenticate packets (I guess 8-12 would also be pretty secure ;) and will additionally prefix each packet with 12 bytes of random data.

In general, remember that AES-128 seems to be as secure but faster than AES-192 or AES-256, more randomness helps against sniffing, and a longer HMAC helps against spoofing. MD4 is a fast digest, SHA1, RIPEMD160, SHA256 are consecutively better, and Blowfish is a fast cipher (and also quite secure). iykyk 💅

---

🛠️ HOW TO SET UP A SIMPLE VPN 🛠️

In this section I will describe how to get a simple VPN consisting of three hosts up and running. let's build, bestie 🫶

---

🎀 STEP 1: configuration

First you have to create a daemon configuration file and put it into the configuration directory. This is usually /etc/gvpe, depending on how you configured gvpe, and can be overwritten using the -c command line switch.

Put the following lines into /etc/gvpe/gvpe.conf:

udp-port = 50000 # the external port to listen on (configure your firewall)
mtu = 1400       # minimum MTU of all outgoing interfaces on all hosts
ifname = vpn0    # the local network device name

node = first     # just a nickname
hostname = first.example.net # the DNS name or IP address of the host

node = second
hostname = 133.55.82.9

node = third
hostname = third.example.net

The only other file necessary is the if-up script that initializes the virtual ethernet interface on the local host. Put the following lines into /etc/gvpe/if-up and make it executable (chmod 755 /etc/gvpe/if-up):

#!/bin/sh
ip link set $IFNAME address $MAC mtu $MTU up
[ $NODENAME = first  ] && ip addr add 10.0.1.1 dev $IFNAME
[ $NODENAME = second ] && ip addr add 10.0.2.1 dev $IFNAME
[ $NODENAME = third  ] && ip addr add 10.0.3.1 dev $IFNAME
ip route add 10.0.0.0/16 dev $IFNAME

This script will give each node a different IP address in the 10.0/16 network. The internal network (if gvpe runs on a router) should then be set to a subset of that network, e.g. 10.0.1.0/24 on node first, 10.0.2.0/24 on node second, and so on.

By enabling routing on the gateway host that runs gvpe, all nodes will be able to reach the other nodes. You can, of course, also use proxy ARP or other means of pseudo-bridging, or (best) full routing — the choice is yours 🌸

---

🔑 STEP 2: create the RSA key pair for each node

Next you have to generate the RSA keys for the nodes. While you can set up GVPE so you can generate all keys on a single host and centrally distribute all keys, it is safer to generate the key for each node on the node itself, so the secret/private key never has to be copied over the network. protect the bag, bestie 🫶

To do so, run the following command to generate a key pair:

gvpectrl -c /etc/gvpe -g nodekey

This will create two files, nodekey and nodekey.privkey. The former should be copied to /etc/gvpe/pubkey/nodename on the host where your config file is (you will have to create the pubkey directory first):

scp nodekey confighost:/etc/gvpe/pubkey/nodename

The private key nodekey.privkey should be moved to /etc/gvpe/hostkey:

mkdir -p /etc/gvpe
mv nodekey.privkey /etc/gvpe/hostkey

---

📦 STEP 3: distribute the config files to all nodes

Now distribute the config files and public keys to the other nodes.

The example uses rsync-over-ssh to copy the config file and all the public keys:

rsync -avzessh /etc/gvpe first.example.net:/etc/. --exclude hostkey
rsync -avzessh /etc/gvpe 133.55.82.9:/etc/.       --exclude hostkey
rsync -avzessh /etc/gvpe third.example.net:/etc/. --exclude hostkey

You should now check the configuration by issuing the command gvpectrl -c /etc/gvpe -s on each node and verify it's output. 👀

---

🚀 STEP 4: starting gvpe

You should then start gvpe on each node by issuing a command like:

gvpe -D -l info first # first is the nodename

This will make the gvpe daemon stay in foreground. You should then see "connection established" messages. If you don't see them, check your firewall and routing (use tcpdump ;).

If this works you should check your networking setup by pinging various endpoints.

To make gvpe run more permanently you can either run it as a daemon (by starting it without the -D switch), or, much better, from your inittab or equivalent. I use a line like this on all my systems:

t1:2345:respawn:/opt/gvpe/sbin/gvpe -D -L first >/dev/null 2>&1

---

🎉 STEP 5: enjoy

... and play around. Sending a -HUP (gvpectrl -kHUP) to the daemon will make it try to connect to all other nodes again. If you run it from inittab, gvpectrl -k (or simply killall gvpe) will kill the daemon, start it again, making it read it's configuration files again. it's giving self-care 🔥

To run the GVPE daemon permanently from your SysV init, you can add it to your inittab, e.g.:

t1:2345:respawn:/bin/sh -c "exec nice -n-20 /path/to/gvpe -D node >/var/log/gvpe.log 2>&1"

For systems using systemd, you can use a unit file similar to this one:

[Unit]
Description=gvpe
After=network.target
Before=remote-fs.target

[Service]
ExecStart=/path/to/gvpe -D node
KillMode=process
Restart=always

[Install]
WantedBy=multi-user.target

---

👀 SEE ALSO 👀

• gvpe.osdep(5) — for OS-dependent information
• gvpe.conf(5)
• gvpectrl(8)
• gvpe.protocol(7) — for a description of the transports, protocol, and routing algorithm

The GVPE mailing list, at <http://lists.schmorp.de/>, or gvpe@lists.schmorp.de 💌

---

💖 AUTHOR 💖

Marc Lehmann <gvpe@schmorp.de>

---

📜 COPYRIGHTS AND LICENSES 📜

GVPE itself is distributed under the GENERAL PUBLIC LICENSE (see the file COPYING that should be part of your distribution).

In some configurations it uses modified versions of the tinc vpn suite, which is also available under the GENERAL PUBLIC LICENSE.

---

and that's the whole page bestie 🫶 this was version 2.25, dated 2016-11-02, and it's the GVPE(5) page — go forth and tunnel responsibly 💅✨