= Riffol
Riffol is a supervising process that can run as a traditional daemon
on Unix-like systems or as an init system for containers (such as
https://github.com/krallin/tini[tini]).
Riffol can be configured by creating application groups that consist of applications, health checks and dependency checks.
+--------+ | Riffol | +----+---+ | | | +------v------+ | Application | | Group +-------+--------------+---------------+ +------+------+ | | | | | | | | | | | | | | | +------v------+ +---v----+ +-----v------+ +----v-----+ | Application | | Health | | Dependency | | Resource | +-------------+ | Check | +------------+ | Limits |
Riffol uses the unified configuration model from https://github.com/riboseinc/event-configuration-models for its configuration syntax definition, startup configuration and also runtime configuration.
Riffol is implemented in Rust.
=== Building From Source
Make sure there is a Rust environment installed. Otherwise follow the https://www.rust-lang.org/en-US/install.html[Rust installation guide].
This command will build a riffol binary and store it in the bin
directory under $CARGO_HOME - usually ~/.cargo/bin/riffol.
== Usage
riffol [-f config-file]
Riffol requires a configuration file. The default location of this
file is /etc/riffol.conf.
This location can be specified either via the RIFFOL_CONFIG
environment variable or by using the -f command line flag.
== Configuration
=== Init
The main configuration to create application groups:
init name { application_groups [ applicationgroup.name ]
E.g.:
init web { application_groups ["applicationgroup.webstack"]
=== Application Group
application_group name { applications [ "application.name" ] dependencies [ "dependency.name" ]
E.g.:
application_group webstack { applications [ "application.db" "application.www" ] dependencies [ "dependency.webstackdependencies" ]
=== Application
application "name" { mode applicationmode requires [other applications] start [executable start args] stop [executable stop args] pidfile file dir workingdirectory env { new var1 value new var2 value pass oldname newname } envfile envfilename stdout streamdestination stderr streamdestination uid int gid int healthchecks [ "healthcheck.name" ]
application_mode can be one of oneshot, simple or forking
Applications are started with a clean environment. Environment
variables can be added with env and env_file fields.
env values can take two forms. env new <name> <value> creates a
new variable with the supplied value. env pass <oldname> <newname>
creates a new variable named newname with the value taken from
Riffol's environment variable oldname.
env { new { VAR1 value1 VAR2 value2 } pass { ENV1 VAR3 ENV2 VAR4 }
This creates two new environment variables, VAR1 and VAR2 with
values value1 and value2 respectively. It also passes the
variables ENV1 and ENV2 into new variables VAR3 nad VAR4
respectively.
env_file <filename> reads a file of environment variables, one per
line in the following format:
VAR1=value1 VAR2=value2 VAR3
VAR1 and VAR2 are set to value1 and value2
respectively. VAR3 and VAR4 are set to the empty value "".
The env_file field is processed before the env field so variables
set up using env will override those read from env_file.
stream_destination can be one of:
file [ filename
syslog { socket unixsockaddress facility syslogfacility severity syslogseverity
rsyslog { address remoteinetaddress local localinetaddress facility syslogfacility severity syslogseverity
syslog_facility is one of kern, user, mail, daemon, auth,
syslog, lpr, news, uucp, cron, authpriv, ftp, local0,
local1, local2, local3, local4, local5, local6 or
local7. (default daemon)
syslog_severity is one of emerg, alert, crit, err,
warning, notice, info or debug (default debug)
healthcheckfail can be one of start, restart or stop.
E.g.:
application www { exec "/etc/init.d/http" dir "/var/www" env { new var1key var1value new var2key var2value pass oldname newname } envfile "/etc/httpd/morevars" start start stop stop restart restart stdout file "/var/log/riffolwww.log" stderr syslog { } uid 0 gid 0 healthchecks [ "healthcheck.www" ] healthcheckfail restart
=== Health Check
healthcheck name { checks [ "class://value" ] interval int timeout int
There are several checks classes:
. df, disk free space
. proc, process name
. tcp, TCP connection
. udp, UDP connection
. http, establish a http connection
. https, establish a https connection
Parameters:
. interval, the interval of the check defined in seconds
. timeout, the timeout of network connections defined in seconds
E.g.:
healthcheck db { checks [ "df:///var/lib/mysql:512" "proc://mysqld", "tcp://127.0.0.1:3306" ] interval 60 timeout 10
=== Dependency
A packages[] dependency is checked via an operating system specific
method.
e.g.: on RHEL/CentOS Riffol will execute rpm -q ${name}
dependency name { packages = [ package_name ]
E.g.:
dependency webstack { packages [ httpd mariadb ]
=== Resource Limits
limits name { maxprocs int maxmem int
e.g.:
limits db { maxprocs 4 maxmem 1024
== ... Riffol?
https://en.wikipedia.org/wiki/Salmonrun#Thespawning
The eggs of a female salmon are called her roe. To lay her roe, the female salmon builds a spawning nest, called a redd, in a riffle with gravel as its streambed. A riffle is a relatively shallow length of stream where the water is turbulent and flows faster.
By spelling "riffol" with an O, we are putting the chemical symbol for oxygen in the word: we are https://en.wikipedia.org/wiki/Redox[oxidising] Riffol. Which makes sense, since Riffol is in Rust.