| pingu |

name:        pingu
version:     0.1.0
description: systemd service ping and recovery system
author:      xdrm-brackets

[TOC]

Pingu allows you to watch important services on your server and send you a mail when one is down. The mail contains a link to restart the failed service.

Notation

Every field enclosed in <, > refers to the configuration file fields.

---

Requirements

You need a recent linux featuring :

• a postfix or any reachable smtp server bound at <mail.host>:<mail.port>
• systemd
• go

---

I. How it works ?

Pingu contains 2 executables :

• pingu-watcher that watches for services' failure. It also waits for incoming HTTP requests for recovery links.
• pingu-trigger that sends messages to the watcher to signal a failed service.

1) Service monitoring

You must directly target the pingu-trigger executable inside each service unit you want to watch inside the ExecStop instruction (cf. ExecStop) ; as a result it will catch normal and unexpected stops of your service. pingu-trigger takes the name of your service as its only argument.

**Example : ** /lib/systemd/system/apache2.service

ExecStop=-/go/bin/pingu-trigger apache2

The executable path must be absolute, in the example we suppose GOPATH=/go. The - right after the equal sign tells the service unit to ignore whether pingu-trigger returns an exit code greater than 0 and we don't want pingu to mess our service.

2) Recovery mail

The mail will contain a link for each failed service and will be sent to the mail address <mail.recipient>. The link follows the syntax http://<http.host>:<http.port>/XXX where the <http.host> and <http.port>. The token XXX is randomly generated for each mail.

Important : The link will only be valid <token.ttl> seconds after you received the mail.

3) Service wrapper

It is possible to wrap the pingu-watcher executable into a service to make it a background process that can be managed with the systemctl or service command.

The project source contains a default service unit (cf. systemd service) that will wrap pingu-watcher as a service. To install the service wrapper simply copy the file from the source to /lib/systemd/system/pingu-wrapper.service. Each time the service will be started, it will use iptables to open the <network.private_port> and close it when the service stops.

Important : You might want to update this file to make the <network.private_port> match your configuration as well as the path to the executable pingu-watcher.

II. Configuration file

Here is a sample configuration file featuring all available fields :

/etc/default/pingu.ini

[mail]
; smtp server host
host = example.com
; smtp server's port
port   = 25
; email recipient
recipient = admin@example.com

[http]
; whether the server uses https (true|1|yes or false|0|no)
tls = true
; server public host (cf. reverse proxy)
host = example.com
; server public port resolving to the private port (cf. reverse proxy)
port = 80

[network]
; private http listening port
private_port = 4123

; available port for internal communication
internal_port = 6789

[token]
; token time to live (seconds)
ttl = 600