Horust

Logo

Horust is a supervisor / init system written in rust and designed to be run inside containers.

View the Project on GitHub FedericoPonzi/Horust

Documentation

Table of contents:

When starting horust, you can optionally specify where it should look for services and uses /etc/horust/services by default.

Service configuration

This section describes all the possible options you can put in a service.toml file. You should create one different service.toml for each command you want to run. A part from the user parameter, everything should work even with an unprivileged user.

Main section

# name = "myname"
command = "/bin/bash -c 'echo hello world'"
start-delay = "2s"
start-after = ["another.toml", "second.toml"]
stdout = "STDOUT"
stderr = "/var/logs/hello_world_svc/stderr.log"
user = "root"
working-directory = "/tmp/"

Restart section

[restart]
strategy = "never"
backoff = "0s"
attempts = 0

The delay between attempts is calculated as: backoff * attempts_made + start-delay. For instance, using:

Will wait 1 second and then start the service. If it doesn’t start:

If the attempts are over, then the service will be considered FailedFinished and won’t be restarted. The attempt count is reset as soon as the service’s state changes to running. This state change is driven by the healthcheck component, and a service with no healthcheck will be considered as Healthy and it will immediately pass to the running state.

Healthiness Check

[healthiness]
http-endpoint = "http://localhost:8080/healthcheck"
file-path = "/var/myservice/up"

Failure section

[failure]
successful-exit-code = [ 0, 1, 255]
strategy = "ignore"

Environment section

[environment]
keep-env = false
re-export = [ "PATH", "DB_PASS"]
additional = { key = "value"} 

Termination section

[termination]
signal = "TERM"
wait = "10s"
die-if-failed = ["db.toml"]

State machine

State machine

You can compile this on https://state-machine-cat.js.org/

initial => Initial : "Will eventually be run";
Initial => Starting : "All dependencies are running, a thread has spawned and will run the fork/exec the process";
Initial => Finished : "System shutdown before service had a chance to run (Kill Event)"; 
Starting => Started : "The service has a pid";
Started => Running : "The service has met healthiness policy";
Started => Failed : "Service cannot be started";
Started => Success : "Service finished very quickly";
Failed => FinishedFailed : "Restart policy";
Started => InKilling : "Received a Kill event";
InKilling => Finished : "Successfully killed";
InKilling => FinishedFailed : "Forcefully killed (SIGKILL)";
Running => Failed  : "Exit status is not successful";
Running => Success  : "Exit status == 0";
Running => InKilling: "Received a Kill event";
Success => Initial : "Restart policy applied";
Success => Finished : "Based on restart policy";
Failed => Initial : "restart = always|on-failure";

Horust’s configuration

Horust can be configured by using the following parameters:

# Default time to wait after sending a `sigterm` to a process before sending a SIGKILL.
unsuccessful-exit-finished-failed = true

All the parameters can be passed via the cli (use horust --help) or via a config file. The default path for the config file is /etc/horust/horust.toml.

Single command

It’s already supported, but I think it needs some love. You can wrap a single command with horust by running:

./horust -- bash /tmp/myscript.sh

This is equivalent to running a single service defined as:

command= "bash /tmp/myscript.sh"

This will run the specified command as a one shot service, so it won’t be restarted after exiting. Commands have precedence over services, so if you specify both a command and a services-path, the command will be executed and the services path is ignored.

Plugins

WIP. Horust works via message passing, so it should be fairly easy to have additional components connected to its bus. But I’m not sure at this time, if there is the need for this.

Checking system status

WIP: https://github.com/FedericoPonzi/Horust/issues/31 The idea is to create another binary, which will somehow report the system status. A systemctl for Horust.