||5 months ago|
|bin||6 months ago|
|dependencies||5 months ago|
|doc||6 months ago|
|include||5 months ago|
|lib||6 months ago|
|src||5 months ago|
|.gitignore||5 months ago|
|.gitmodules||5 months ago|
|.htaccess||5 months ago|
|AUTHORS||5 months ago|
|Makefile||5 months ago|
|README.md||5 months ago|
|UNLICENSE||5 months ago|
|WAIVER||5 months ago|
|database.sql||5 months ago|
DeadManSwitch is a C++ CGI program to send alerts when a host stops sending keepalives.
This is a statically compiled C++ program that can be used on any host provider that allows CGI programs.
It uses a SQLite database (that can be encrypted due to sqleet) to track the status of each host.
It uses a HTTP POST request to send notifications, allowing for custom notification system.
DeadManSwitch has been released in the public domain under the UNLICENSE license.
Goals of DeadManSwitch
- Able to be used on free hosting providers that support CGI.
- Be statically compiled to not depend on provider libraries.
- Be small and fast as possible, with fastest being the priority.
DeadManSwitch isn't intended to replace any monitorization service, but instead to complement it (although if you only want to know if your hosts are down, this is good enough).
The initial idea was to notify if my homelab prometheus was down (or unable to send notifications because internet was down).
How to use
- Configure for your needs;
- Compile it;
- Create and populate the database;
- Deploy it as a CGI app;
- Set your hosts to send keepalive requests
- Setup Cron
DeadManSwitch can be configured by creating the header file include/deadmanswitch/config.h
|DB_PATH||Any valid path||Path to SQLite database||./deadmanswitch.db|
|DB_KEY||Any string||Key for encrypted database||None|
|LOG_OUTPUT||Any valid path||Path to log file||None|
|LOG_T_FORMAT||A valid strftime format||Time format for logging||%Y-%m-%d %H:%M:%S (%Z)|
|LOG_LEVEL||LOG_DEBUG, LOG_INFO, LOG_WARNING, LOG_ERROR, LOG_CRITICAL||Minimum level to show logs||LOG_INFO|
If you are familiar with Python logging, LOG_LEVEL is similar to level in logging.Logger.setLevel
#define DB_PATH "/var/db/deadmanswitch.db" #define LOG_OUTPUT "/var/log/deadmanswitch.log" #define LOG_T_FORMAT "%d-%m-%Y %H:%M" #define LOG_LEVEL LOG_ERROR
From your system, DeadManSwitch needs:
- cmake (to build SQLiteCpp)
- static libraries for stdc++ and libc
- C and C++ compiler (tested with GCC and Cmake)
The rest of the dependencies are bundled with the repository.
# dnf install -y dnf-plugins-core # dnf config-manager --set-enabled powertools # dnf install -y cmake make patch git glibc-static libstdc++-static gcc gcc-c++ findutils
# dnf install -y cmake make patch git glibc-static libstdc++-static gcc gcc-c++ findutils coreutils
# apt install -y cmake make patch git findutils gcc g++ coreutils
# apk add cmake make patch git findutils coreutils gcc g++
Clone and compile
git clone --recurse-submodules https://gitlab.com/hmrodrigues/deadmanswitch.git cd deadmanswitch make
Note: This commands were tested on Docker images registry.fedoraproject.org/fedora:33, registry.centos.org/centos:8, docker.io/library/debian:10.8-slim and docker.io/library/alpine:3.12.4
On my humble machine (Fedora 33 on Intel(R) Pentium(R) CPU N3700, 8G of RAM and a SSD) it takes about 45 seconds to compile everything
Create a SQLite database and read the file database.sql to create the initial tables.
sqlite3 deadmanswitch.db .read database.sql
If you want an encrypted database (highly recommened if using a shared hosting provider), you can compile SQLite3 using the bundled sqleet
local/bin/sqlite3 deadmanswitch.db PRAGMA rekey "your very secure passphrase" .quit local/bin/sqlite3 deadmanswitch.db PRAGMA key "your very secure passphrase" .read database.sql
Don't forget to set DB_KEY
There are three table that you need to populate in order to start using DeadManSwitch
Only the columns that you need to set are shown.
Bold columns must have unique records
This table holds the hosts that you want to monitor
|uuid||Host unique identifier, used to create pings||None||Yes|
|name||Human friendly name of the host||None||Yes|
|active||Only process host if this column is true||true||Yes|
New host example:
INSERT INTO "hosts" ("uuid", "name", "location", "active") VALUES ("de808aae-a3cb-4ef8-b0f8-3d9a4b28d2aa", "localhost", "Home", true);
Update host example:
UPDATE "hosts" SET "name"="new name" WHERE "uuid"="de808aae-a3cb-4ef8-b0f8-3d9a4b28d2aa";
Holds the users to authenticate the requests
|name||Human friendly name of the user||None||Yes|
|key||Key used by the user to authenticate||None||Yes|
|active||Only process request if user is active||true||Yes|
New user example:
INSERT INTO "users" ("name", "key", "active") VALUES ("user1", "this is a secure key", true);
Update user example:
UPDATE "users" SET "active"=false WHERE "name"="user1";
Holds DeadManSwitch runtime configurations
New configuration example:
INSERT INTO "configs" ("key", "value") VALUES ("config.key", "config value");
Update configuration example:
UPDATE "configs" SET "value"="new config value" WHERE "key"="config.key";
|db.version||Current database version (to be used by future migration feature)|
|notifications.http.endpoint||Endpoint for HTTP notifications|
||Custom headers for HTTP notification.
If you are using a public shared provider, I really recommend you to encrypt your database. Check how on the create step.
After setting up DeadManSwitch you need to configure your hosts. There isn't a client available, but any piece of software that can make HTTP(S) requests this custom headers will work. Curl example:
curl -X PUT -H "KEY: this is a secure key" -H "HOST: de808aae-a3cb-4ef8-b0f8-3d9a4b28d2aa" https://deadmanswitch.example.com/ping
Since this software was intended to be used as CGI, we need to call it from time to time to check the hosts. The cron must be called via HTTP request on path /cron. Why is that? Well, most free hosting providers only allow 2 cron executions per day, and that isn't enough to have a real monitoring system.
You can use one of the following free services run cron (and also check if DeadManSwitch is working):
|Nixstats (EU based)||1 minute|
|How Fast||1 minute|
|Better Uptime||3 minutes|
|And many more|
curl -X PUT -H "KEY: this is a secure key" https://deadmanswitch.example.com/cron
DeadManSwitch is built with the following awesome projects, kudos to them.
- SQLiteCpp by Sébastien Rombauts. MIT License
- sqleet by resilar. Public domain
- json by Niels Lohmann. MIT License
- HTTPRequest by Elviss Strazdins. Public domain
How to contribute
If you are a FSFE supporter (you are awesome by the way), just fork and pull-request your changes
Non FSFE supporter
Send me your patch via email. Be sure to use the git email format (
git show --pretty=email). You can also become a FSFE supporter (just saying)
In any case, please sign the WAIVER file
echo -e "## your email\n" >> AUTHORS gpg --detach-sign --sign --armor --no-version -o - WAIVER >> AUTHORS
And send me the public GPG key for validation.