= 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 and health checks.

[source]

+--------+ | Riffol | +----+---+ | | | +------v------+ | Application | | Group +-------+-------------+ +------+------+ | | | | | | | | | | | +------v------+ +---v----+ +----v-----+ | Application | | Health | | 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].

[source,shell]

cargo install --git https:/github.com/riboseinc/riffol

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:

[source]

init name { application_groups [ applicationgroup.name ]

}

E.g.:

[source]

init web { application_groups ["applicationgroup.webstack"]

}

=== Application Group

[source]

application_group name { applications [ "application.name" ]

}

E.g.:

[source]

application_group webstack { applications [ "application.db" "application.www" ]

}

=== Application

[source]

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.

[source]

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:

[source]

VAR1=value1 VAR2=value2 VAR3

VAR4=

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:

[source]

file [ filename

]

[source]

syslog { socket unixsockaddress facility syslogfacility severity syslogseverity

}

[source]

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.:

[source]

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

[source]

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.:

[source]

healthcheck db { checks [ "df:///var/lib/mysql:512" "proc://mysqld", "tcp://127.0.0.1:3306" ] interval 60 timeout 10

}

=== Resource Limits

[source]

limits name { maxprocs int maxmem int

}

e.g.:

[source]

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.