DEV Community: Ihor Kalnytskyi

Setup a WireGuard client using systemd-networkd

Ihor Kalnytskyi — Sat, 03 Sep 2022 00:00:00 +0000

Please check out «Setup a WireGuard server using systemd-networkd» to learn more about WireGuard in general and network topology outlined in this post.

On Feb 24, 2022, Russia began a full scale invasion of Ukraine. The terror they brought to my country is devastating, and so publication of this post has been postponed till better times. Only now I finally found some strength inside to finish and publish this writing.

WireGuard is a great VPN choice for your home, and maybe even for your company. It's simple, fast, built into Linux kernel 5.6 and above, and can be configured via systemd-networkd in no time. The systemd suite supports WireGuard starting with v237 and is most likely installed on your Linux machine.

Let us try to setup a wireguard 'client' for the following VPN network:

Option	Value
Network	`10.0.0.0/24`
Server	`10.0.0.1`
Client	`10.0.0.20`

First thing to do is to set up a virtual network device for a WireGuard tunnel. This can be achieved by means of a systemd.netdev(5) unit that must be created in /etc/systemd/network/ directory. The WireGuard network device must know about number of things:

The private key of the peer.
The endpoint of the 'server' peer and its public key.

Unlike 'server', a 'client' peer doesn't require port configuration because it's the 'client' that initiates connection not the other way round. This is how some /etc/systemd/network/wg0.netdev could look like:

[NetDev]
Name=wg0
Kind=wireguard
Description=wg0 - wireguard tunnel

[WireGuard]
PrivateKeyFile=/etc/systemd/network/wireguard-keys/wg0
FirewallMark=0x8888

[WireGuardPeer]
PublicKey=TPouHhVqvgAMfa9mNwZOh59kifUAsdn9Vtgsj2IsKVU=
AllowedIPs=0.0.0.0/0
Endpoint=vpn.example.com:51820

The content of /etc/systemd/network/wg0.key can be generated by invoking$ wg genkey command and must be readable by the systemd-network user.

There are couple of things to note:

The FirewallMark option takes a number and is used to mark outgoing WireGuard packets. Please remember that mark, it will be later used for network configuration.
The AllowedIPs option is set to 0.0.0.0/0 because we're interested to route all the traffic via the tunnel, i.e. surfing the Internet via VPN. If your plans for the VPN is to connect multiple devices into a single network, you should go with the network address only, e.g. 10.0.0.0/24.
The Endpoint option takes a wireguard 'server' IP address or hostname, followed by a colon, and then a port the 'server' accepts connection on. The endpoint must be reachable from 'client' peers even when VPN is down.

Next thing to do is to use a systemd.network(5) unit to setup a network. The purpose of the network is to assign a proper IP address on the network device, set proper routes and so on.

This how some /etc/systemd/network/wg0.network could look like:

[Match]
Name=wg0

[Network]
Address=10.0.0.20/24
DNSDefaultRoute=true
DNS=1.1.1.1

[Link]
ActivationPolicy=manual

[RoutingPolicyRule]
FirewallMark=0x8888
InvertRule=true
Table=1000
Priority=10

[Route]
Gateway=10.0.0.1
GatewayOnLink=true
Table=1000

There are a bunch of important stuff going on:

Since /24 network mask is used, systemd-networkd will automatically add a route for the whole network to be routed via the WireGuard tunnel. Without that mask, it'd be up to a user to properly configure routing on the system.
With ActivationPolicy set to manual, the VPN is not brought up on system boot, and requires manual activation via $ networkctl up wg0. One case use the up value to always activate VPN on system boot.
Both RoutingPolicyRule and Route come together and are only required if you want to route all the traffic over the tunnel. The Route section essentially creates a default route that routes packets to the wireguard server. The RoutingPolicyRule section, on the other hand, says that this new default route should be applied only for the packets not coming from the wireguard network device (i.e. not being marked with a firewall mark).
When VPN is used as a gateway for the Internet, it's quite common to set some non default DNS servers to resolve domain names. It could be your own VPN server, or some third-party provider such as Cloudflare. In order to set custom DNS servers when VPN connection is up, one can use DNSDefaultRoute and DNS options. The former tells the system to use the latter to resolve all domain names.

When both the network device and the network are configured, the only remained step is to run $ networkctl reload to pipe in and apply latest configuration followed by $networkctl up wg0 to bring the VPN up.

Setup a WireGuard server using systemd-networkd

Ihor Kalnytskyi — Mon, 07 Feb 2022 00:00:00 +0000

Please check out «Setup a WireGuard client using systemd-networkd» to learn about client-side configuration of your Linux machine.

WireGuard is an extremely simple, fast and modern VPN that is built into Linux kernel 5.6 (released on Mar 29, 2020) and above. It mimics the model of SSH and requires VPN peers to know each others public keys. I highly recommend to read https://www.wireguard.com regardless of this post.

When it comes to WireGuard, there's one interesting aspect: it has no notion of 'server', it's distributed by design and no blockchain is involved. Blockchain enthusiasts may found this surprising but distributed software were invented long before the blockchain 😅. Each peer may connect to other peers assuming they know each other (i.e. public key, IP) and there's a connectivity between them. The 'server' is rather a behaviour one may expect from a certain peer. There are 3 key points that are normally expected from a 'server' peer:

The peer is publicly available, so other peers may connect to it even when behind SNAT.
The peer can act as a proxy and connect other peers into a single network.
The peer can act as a gateway to the Internet.

There are number of ways to configure WireGuard on a Linux machine. My favorite one is to use systemd-networkd, a system service that manages both networks and network devices. It's distributed as part of systemd suite, so most likely you have it installed, and it supports WireGuard starting with v237. It's a good choice for a Linux server because it requires no extra software.

For instance we want to setup the following VPN network:

Option	Value
Network	`10.0.0.0/24`
Server	`10.0.0.1`
Peer A	`10.0.0.20`
Peer B	`10.0.0.30`

The port to accept new connections on.
The private key of the server.
The list of known peers and their public keys.

This is how some /etc/systemd/network/wg0.netdev could look like:

[NetDev]
Name=wg0
Kind=wireguard
Description=wg0 - wireguard tunnel

[WireGuard]
ListenPort=51820
PrivateKeyFile=/etc/systemd/network/wg0.key

[WireGuardPeer]
AllowedIPs=10.0.0.20/32
PublicKey=9vzzasvYciJLmhjrt9Aj9aQYe1gnUxI44ShVLQPrDQA=

[WireGuardPeer]
AllowedIPs=10.0.0.30/32
PublicKey=9vzzasvYciJLmhjrt9Aj9aQYe1gnUxI44ShVLQPrDQA=

The content of /etc/systemd/network/wg0.key can be generated by invoking$ wg genkey command and must be readable by the systemd-network user. What's notable here is that $ wg genkey can be executed anywhere, even on your laptop, there's no need to install extra software on the server.

Next thing to do is to use a systemd.network(5) unit to setup a network. The purpose of the network is to assign a proper IP address on the network device, set proper routes and so on.

This how some /etc/systemd/network/wg0.network could look like:

[Match]
Name=wg0

[Network]
Address=10.0.0.1/24
IPMasquerade=both

There are couple of things to note:

Since /24 network mask is used, systemd-networkd will automatically add a route for the whole network to be routed via the WireGuard tunnel. Without that mask, it'd be up to a user to properly configure routing on the system.
The IPMasquerade setting is only needed if the server is expected to be used as a gateway to the Internet. Without this option, it'd be up to a user to properly configure the firewall.

When both the network device and the network are configured, the only remained step is to run $ networkctl reload to pipe in and apply latest configuration.

Setup CORS in Caddy 2

Ihor Kalnytskyi — Wed, 12 Jan 2022 00:00:00 +0000

Caddy 2 is an open source web server with automatic HTTPS. It's a wise choice for pet projects or self-hosted services, since you are free from managing TLS certs on your own and wiring things up can be super annoying.

One missing feature in Caddy 2, however, is cross-origin resource sharing (CORS) support. For a "batteries included" web server, it's rather surprising. Fortunately, one can use the following Caddy snippet to augment any site with CORS headers without repeating oneself over and over again.

You might want to update the list of headers returned byAccess-Control-Allow-Headers or Access-Control-Expose-Headers HTTP headers according to your application needs. Please refer to the CORS documentation to learn more what they are about.

(cors) {
  @cors_preflight method OPTIONS
  @cors header Origin {args.0}

  handle @cors_preflight {
    header Access-Control-Allow-Origin "{args.0}"
    header Access-Control-Allow-Methods "GET, POST, PUT, PATCH, DELETE"
    header Access-Control-Allow-Headers "Content-Type"
    header Access-Control-Max-Age "3600"
    respond "" 204
  }

  handle @cors {
    header Access-Control-Allow-Origin "{args.0}"
    header Access-Control-Expose-Headers "Link"
  }
}

example.com {
  import cors https://example.com
  reverse_proxy localhost:8080
}

The nice part about this snippet is that CORS headers are only returned for HTTP requests with the Origin HTTP header. That header is normally used by browsers only, which means you won't see CORS headers in responses for requests sent by curl or your-programming-language-of-choice.

I've been successfully using this snippet for quite a while now to protect api.xsnippet.org, so it can be accessed by xsnippet.org.

Setup PostgreSQL for Linux, Windows and macOS using GitHub Actions

Ihor Kalnytskyi — Wed, 24 Nov 2021 00:00:00 +0000

GitHub Actions is a CI/CD platform that is widely used among open-source software hosted on GitHub. If you happened to host your software there, you may end up needing a SQL server to test your application. PostgreSQL is the most common choice nowadays.

As of today (Nov 24, 2021), there's only one action on the marketplace to setup a PostgreSQL server for Linux, Windows and macOS action runners. If you among those who want to test their software on all major platforms, you have no option but to use ikalnytskyi/action-setup-postgres. Below is the typical usage example:

steps:
  - name: Setup PostgreSQL
    uses: ikalnytskyi/action-setup-postgres@v1
    id: postgres

  - name: Run tests
    env:
      CONNECTION_URI: ${{ steps.postgres.outputs.connection-uri }}
    run: pytest -vv tests/

So why use that exact action and no other?

Runs on Linux, macOS and Windows action runners.
Fast! Preinstalled binaries are used.
Easy to audit, just 4 steps YAML!

Enable CSD in GNOME Terminal

Ihor Kalnytskyi — Sun, 24 Oct 2021 00:00:00 +0000

Client-side decoration (CSD) is the concept of allowing a graphical application software to be responsible for drawing its own window decorations, historically the responsibility of the window manager. GNOME applications is slowly migrating to client-side decoration. While some applications use CSD by default, others draw them only while running in GNOME session.

Unfortunately, CSD is not used by GNOME Terminal if you launch it outside of GNOME session. Fortunately, there's a configuration option you can use to explicitly enable it. In order to do that just run the following command in your terminal:

$ gsettings set org.gnome.Terminal.Legacy.Settings headerbar true

The setting won't be applied as long as there's a running copy ofgnome-terminal-server process. You have to terminate it and restart the terminal.

The configuration option is tested with gnome-terminal 3.40. It might or might not work with other versions.