🔔 Belltower 🔔

Belltower is a simple HTTP-based relay for sending Wake-on-LAN requests (and pings) to private subnets. Also includes a proxy mode for use in subnets that cannot be reached by WoL packets directly (usually due to filtering of broadcast packets).

All communication is encrypted and authenticated via the XChaCha20Poly1305 scheme using pre-shared keys. Keys for this scheme can be generated conveniently via belltower keygen.

Check belltower --help for a full overview on how to use this program. Note that the Belltower server itself does not come with a web frontend and is instead intended to be used as a backend for some other application.

The implementation is currently limited to Unix systems. Feel free to open an issue (or a PR!) if you need Windows support.

API

Belltower is intended to be used in internal networks and thus does not use HTTPS encryption to spare you the hassle of wrangling TLS certificates. Instead, Belltower listens for plain HTTP requests that are encrypted with the XChaCha20Poly1305 scheme. The nonce used for this encryption and authentication scheme must be given in the Nonce HTTP header in base64 encoding. The request body simply contains the encrypted payload (see below) encoded in whatever encoding scheme is set in the HTTP headers. Since the encryption is symmetric, the secret key needs to be shared beforehand (see example config files).

The encrypted payload is a JSON object that has the following shape:

{
    "method": "<GET or POST>",
    "endpoint": "<name of API endpoint>",
    "timestamp": "<current time to prevent replay attacks>",
    "parameters": {
        "<some_paramter>": "<some value>"
    }
}

The following endpoints are defined for Belltower running as a master relay:

The response is a JSON encoded object sent back with the same encryption schemes as above.

Demo

An example for a frontend written in PHP can be found in the frontend folder. This frontend is designed to work with the example configs in the example_config folder. The encryption is handled by libsodium, so this frontend requires the sodium PHP module to be installed. Check php -m to see if this module is active. If not, consult installation instructions for your distribution and ensure that the module is enabled in the php.ini file.

For a quick test, run these three commands in different shells:

cargo run --release -- -c example_config/belltower_localtest_master.toml -l /tmp/master.log master
cargo run --release -- -c example_config/belltower_localtest_proxy.toml -l /tmp/proxy.log -p 41781 proxy
cd frontend && php -S localhost:8080

Note: running the master relay and a proxy on the same computer does not make much sense usually, but this is just a demonstration.

IF YOU COPY THE EXAMPLE CONFIGS FOR AN ACTUAL DEPLOYMENT, REMEMBER TO CHANGE THE ENCRYPTION KEYS. YOU HAVE BEEN WARNED!