Clsure

Complex? Simplicial.

---

Provision a fresh Ubuntu install as a Hub, Spoke, or hybrid of both!

You can run WireGuard with Docker or on the host. If you run it with Docker (beta, available for armv7+ and amd64), you'll also get Unbound and Pi-hole v5, which will come with pihole-speedtest and pihole-updatelists. In either case, Kodi will be installed with the Jellyfin add-on source, for your convenience. You can also choose between Netplan and hostapd for your access point needs.

Getting Started

Install. Configure. Reboot.

Definitions

One of the variables you'll set in env.sh will be CLS_TYPE_NODE, which is the type of node you're setting up. The options are:

• Hub: A WireGuard server through which peers can route traffic. It just listens for incoming connections.
• Spoke: A WireGuard client that connects, and can route traffic, to a Hub or HaaS.
• HaaS: A special Hub that routes traffic to a special Spoke, a SaaH.
• SaaH: A WireGuard client through which a HaaS routes traffic. It initiates the connection to a HaaS.

A SaaH-HaaS[-Spoke] topology may be useful when you can't forward the WireGuard port at the location you'd like to have a Hub, but can where you'd otherwise have a stationary, always-on Spoke. While a Spoke can route traffic to a Hub or HaaS, a HaaS can only route traffic to a SaaH.

Note

If your Hub or HaaS is behind a dynamic public IP address, sign up for a DDNS provider like freedns.afraid.org and set CLS_DYN_DNS to the update URL.

Caution

If you use freeDNS, or another provider with a similar option, unlink updates of the same IP address.

Configuration

When completing step 2 below, move everything in examples/ out to the parent directory first. The files to edit are:

• dhcp/*dhcp*: optional DHCP server config, if you don't want to use Pi-hole for that
• resolv.conf: optional DNS client config
• netplan.yml: primary network config
• env.sh: environment variables for the scripts
• compose.yml: environment variables for the services and bare WireGuard
• hooks/{pre,post}-{up,down}.sh: scripts that run from the active user's home directory before and after everything is started or stopped, respectively
• hostapd/*.conf: hostapd configs for your non-netplan APs, for more control and AP+STA mode support

Keep in mind that:

• The default DHCP config doesn't enable it.
• Unbound connects to Cloudflare's servers using DoT by default, but you can uncomment its volume in compose.yml to use it as a recursive resolver.
• To configure Pi-hole more extensively, such as by enabling DHCP, see the Pi-hole documentation.
• The hooks may be useful, for example, if you'd like to coordinate with an external, outbound VPN on a Hub or SaaH. All arguments given to start.shand stop.sh are passed to their respective hooks.
• For AP+STA mode, define as many X@[iface].conf files as bands the device supports, where X is an integer band.

Note

The WireGuard service in the Compose file must be configured whether or not you'll use Docker (docs).

Warning

If a user you specify in env.sh doesn't exist, it will be created. By default, the password will be the same as the username; change it!

Deployment

Create or update a node in two or three steps:

1. Install the package by either:
   • pasting the one-liner or block below;
   • downloading it from Releases; or
   • copying this repo to /opt/closure, then ensuring rc.local is executable and moved to /etc.

curl -sSLNZ https://ipitio.github.io/closure/i | sudo bash

sudo apt-get update
sudo DEBIAN_FRONTEND=noninteractive apt-get install -qq gpg wget
sudo mkdir -m 0755 -p /etc/apt/keyrings/
wget -qO- https://ipitio.github.io/closure/gpg.key | gpg --dearmor | sudo tee /etc/apt/keyrings/closure.gpg > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/closure.gpg] https://ipitio.github.io/closure master main" | sudo tee /etc/apt/sources.list.d/closure.list &>/dev/null
sudo chmod 644 /etc/apt/keyrings/closure.gpg
sudo chmod 644 /etc/apt/sources.list.d/closure.list
sudo apt-get update
sudo DEBIAN_FRONTEND=noninteractive apt-get install --no-install-recommends -qq closure

2. Edit the files above and reboot. This boot, as well as those after upgrading, may take a while as everything is set up, but the subsequent ones will be much faster. The SaaH peer will be created on a HaaS if it doesn't exist.
3. On a Hub or HaaS, add Spokes you didn't define in compose.yml by running add.sh as described below.

Set a Hub or HaaS up first, so SaaH and Spoke peer configurations can be generated, then drop those in their wireguard/config/wg_confs directories before rebooting them. This AllowedIPs Calculator is pretty nifty, if you need it.

Note

Any arguments passed to kickstart.sh are passed to start.sh, which can add or edit wifi networks -- useful on a Raspberry Pi Zero (2) W! See the top of start.sh for the arguments it takes.

Important

Remember to forward a port to your Hub or HaaS, which listens on 51820 by default. Use 443 on your router to bypass some basic firewall filters.

Maintenance

You can (re)configure WireGuard peers; add WireGuard peers or modify the AllowedIPs of existing ones, show peer config QR codes, and delete peers with:

sudo bash wireguard/add.sh <peer_name> [option] [-- args]
sudo bash wireguard/get.sh <peer_name>
sudo bash wireguard/del.sh <peer_name> [args]

By default, add.sh sets the peer to route outgoing traffic through the VPN. You can change this default by modifying AllowedIPs in compose.yml. The option it takes may be one of:

-e, --internet    Route all traffic through the VPN
-a, --intranet    Allow access to the internal space
-l, --link        Allow access to just the VPN
-o, --outgoing    Route outgoing traffic through the VPN

The args are passed to re/start.sh.

Note

While start.sh brings everything up, restart.sh only restarts WireGuard unless CLS_WG_ONLY=false is exported first.

Tip

Don't forget to share an updated config with its peer.