Configuration is build the way that user program(s) can share the same configuration file(s) with Ramona system. Configuration is compatible with Python ConfigParser. These are basic configuration files that use structure similar to what you would find on Microsoft Windows INI files.
Note
You are free to blend configuration options of your application with Ramona ones. This is the design intention and it simplifies the structure of a configuration and therefore it makes maintenance significantly easier.
Ideally there should be only one application level configuration file and maybe another one for site level in a whole application.
Ramona supports split of configuration options into application and site level configuration. In this concept, application development team provides application level configuration as a part of source code and users are given by an option to provide their own site level configurations that can override or enhance application level configurations.
Both application and site level configuration are supplied in form of files. Name (including full file path) of application level configuration file is provided by user application. Site configuration file name is derived based on table bellow.
Application and site level configuration as syntactically equal.
See [general] include <siteconf> option for implementation details.
Sometimes you wish to have different configurations for different platforms (basically OSes). This is possible thru platform selector postfix mechanism that is provided by Ramona. You can define platform-specific values optinally together with generic ones. In such a case, matching platform value is used instead of generic option.
Syntax is option@selector=value.
List of selectors:
System Selector Linux linux Windows windows Mac OS X darwin
Note
Platform names are based on Python platform.system() call. Lowercase form is used.
Examples:
[program:ping]
cmd=/sbin/ping
cmd@windows=C:\Windows\System32\ping.exe
[program:foolinux]
disabled@windows=True
This section provides general configuration of Ramona-equiped application.
Note
Feel free to add any other configuration values that are usefull for your application. Ramona will silently ignore them. Also your application can of course use configuration values required by Ramona.
Specifies name of application.
Note
Use of whitespaces is discourages (although possible). This value can become part of various file names, therefore it needs to respect syntax of file path and name.
Type: string
Required: Yes
Example:
[general]
appname=foobarapp
Ordered list of configuration files that should be loaded by Ramona. Separator of individual list items in this list is ‘;’.
Magic value <siteconf> is expanded to following site level configuration file names:
- ./site.conf
- ./[appname]-site.conf
- /etc/[appname].conf
- ~/.[appname].conf
Placeholder [appname] is expanded to value of [general] appname option. Relative path is evaluated from location of application main executable (e.g. containing ramona.console_app).
Default: <siteconf>
Required: No
Example:
[general]
include=<siteconf>
[general]
include=/etc/foo.conf;/etc/bar.conf
Specifies path of a log directory on a filesystem. This value is then stored as a <logdir> magic value and can be used in other log configuration options.
It allows you to ensure that all logs that are produced by Ramona (including logs from program standard streams) will be stored in single directory.
Default: <env>
Required: Yes (but default works fine)
Example:
[general]
logdir=/var/log/foo
Maximum log file size prior being rotated.
Basically a log file grows without bound unless action is taken and this can cause problems. A solution to this generic problem of log file growth is log rotation. This involves t moving of an existing log file that reach certain size to some other file name and starting fresh with an empty log file. After a period the old log files get thrown away.
The pattern is that if a log file name is foobar.log then the first (the freshest) rotated log file name is foobar.log.1, the second freshest is foobar.log.2 and so on. Rotated log files are renamed in a process of a log rotation increasing a tail number by one to make a space for a newly rotated file.
Default: 536870912 (512Mb)
Required: Yes (but default works fine)
Example:
[general]
logmaxsize=1000000000
Number of archived rotated log files, rotated log files with a higher tail number that this config value will be removed.
Default: 3
Required: Yes (but default works fine)
Example:
[general]
logmaxsize=1000000
logbackups=2
Then
foobar.log
foobar.log.1
foobar.log.2
foobar.log.3 <-- this one will be removed
Note
Extensive logging can lead to unwanted loss of log files due to the rotation mechanism (e.g. log files quickly exceeding logmaxsize). To prevent this loss, set logbackups to inf and remove log files manually.
If this configuration option is enabled, rotated log files foobar.log.2+ will be compressed using gzip compression.
Default: “on”
Required: No
Example:
[general]
logmaxsize=1000000
logbackups=5
logcompress=off
Environment variables section allows to specify environment variables that will be added to the environment of Ramona server. These will be also propagated to supervised programs during their start.
These variables can be also used in other options via ${VARNAME} placeholders.
Environment variable section example:
[env]
VARIABLE=value
PYTHONPATH=./mylibs
CLASSPATH=./myjars
This section configures Ramona server.
One or multiple ‘socket URIs’ specifying where Ramona server should listen for console connections. You can specify more network interfaces, protocols or ports, URIs are comma-separated. It should be synchronized with [ramona:console] serveruri option where configuration of Ramona client is specified, otherwise console connection fails.
Supported connection variants:
Default: unix://.ramona.sock
Default on Windows: tcp://localhost:7788
Required: Yes (but default will work)
Example:
[ramona:server]
consoleuri=unix:///tmp/demoramona.sock?mode=0600,tcp://localhost:5566
Specifies location of file with process identified of Ramona server. This file can be eventually used by other processes or users to look it up.
If no or empty value is provided, no pid file is created.
Note
You can use environment variables in form of ${VARNAME}.
Default: (empty)
Required: No
Example:
[ramona:server]
pidfile=${TMP}/testramona.pid
Specifies where to store a log file of Ramona server.
Default: <logdir>
Required: Yes
Example:
[ramona:server]
log=/var/log/foo.log
[general]
logdir=./log
[ramona:server]
log=<logdir>
Will result in ./log/ramona.log
[general]
logdir=./log
[ramona:server]
log=<logdir>/foo.log
Will result in ./log/foo.log
Defines a log level respectively a verbosity of Ramona server.
| Level | Meaning |
|---|---|
| DEBUG | Detailed information, typically of interest only when diagnosing problems. |
| INFO | Confirmation that things are working as expected. |
| WARNING | An indication that something unexpected happened, or indicative of some problem in the near future. The software is still working as expected. |
| ERROR | Due to a more serious problem, the software has not been able to perform some function. |
| CRITICAL | A serious error, indicating that the program itself may be unable to continue running. |
Default: INFO
Required: No
Example:
[ramona:server]
loglevel=DEBUG
This section contains configuration used by Ramona console.
One ‘socket URIs’ specifying Ramona server connection where Ramona console should connect to. It should be synchronized with [ramona:server] consoleuri option where relevant configuration of Ramona server is specified, otherwise console connection fails.
Supported connection variants:
Default: unix://.ramona.sock
Default on Windows: tcp://localhost:7788
Required: Yes (but default will work)
Example:
[ramona:console]
serveruri=unix:///tmp/demoramona.sock
Specifies the location of a command history file that will be used by Ramona console to store commands issued by its user. It allows users to use cursor keys to navigate up and down through the history list and re-use commands found there. History list is persistent and is available across program restarts.
Generic description of command history feature can be found here: http://en.wikipedia.org/wiki/Command_history
Empty configuration value disables history function completely.
Default: (command history disabled)
Required: No
Example:
[ramona:console]
history=./.appcmdhistory
This is configuration of Ramona notification sub-system. This component (part of Ramona server) is reponsible for sending out email notifications about pre-configured events.
Note
Python smtplib module is used to handle SMTP connectivity.
Deleayed notifications are stored in stashes which can be optionally persistent (survives eventual restart of a box).
URL specifies a default delivery method for notifications.
A missing or empty value efectively disables default delivery option.
Default: (empty)
Required: No
Example:
[ramona:notify]
delivery=smtp://mail.example.com/
For real-life examples, see SMTP configurations.
The email address of a sender which will be used in From: field of the notification email.
Magic value <user> will result in email address constructed from a name of an OS user used to launch Ramona server.
Default: <user>
Required: No
Examples:
[ramona:notify]
sender=ramona@app.foobar.com
The default email address of an recipient of notifications.
You can provide multiple email addresses separated by comma (,).
Default: (empty)
Required: No
Examples:
[ramona:notify]
receiver=admin@foobar.com,moniting@foobar.com
Configure notification, that will be eventually triggered when any supervised program unexpectedly terminates and ends in FATAL state. This is done by specifying the action.
You can override this option by notify_fatal entry in given [program:...] section.
Default: now
Required: No
Examples:
[ramona:notify]
notify_fatal=now:admin@foo.bar.com
At what time the notifications should be used when daily is used. The value is in the local timezone of your computer. Use the format HH:MM (24-hours).
Default: 09:00
Required: No
Example:
[ramona:notify]
dailyat=23:00
Specify the directory where persistent stashes (files) are stored.
Default: <none>
Required: No
Example:
[ramona:notify]
stashdir=/var/spool/ramona/stash
Global defaults for configuration values in [program:...] section. If given, they will be used when program specific ones are not stated.
This section of an configuration allows to define program, that will be supervised by Ramona (started, monitored and eventually stopped) including various parameters that describes intended runtime behaviour of given program.
The ... in [program:...] section name should be substituted by name of supervised program. Name should be in ASCII using uppercase and lowecase letters, numbers, underscore (_) but no whitespaces.
Note
Common configuration of Ramona typically contains more than one of [program:...] section.
Example:
[program:frontend]
cmd=./frontend.py
[program:backend]
cmd=./backend.py
[program:integration1]
cmd=./integration1.py
The command that is used to start a program. Ramona server will issue this command in order to change state of a program to STARTING (and eventual RUNNING) status.
The command can be either absolute (e.g. /path/to/foobarapp), relative (./bin/foobarapp) or just application executable name (e.g. foobarapp). If last option is used, the environment variable ${PATH} will be searched for the executable. Programs can accept arguments, e.g. /path/to/foobarapp foo bar.
Supervised programs should themselves not be daemons, as Ramona server assumes it is responsible for daemonizing itself. See Nondaemonizing of Programs section for more details.
Default: (none)
Required: Yes
Example:
[program:dirlist]
command=ls -l /
command@windows=dir c:\
Note
You can take benefit of environment variables expansion when defining this option.
[program:fooapp]
command=./fooapp -t ${TMPDIR}
The directory that program should be started in. Ramona server will change a working directory to this value just prior launching relevant program. Change of directory is local only for given program.
If no or empty value is given, no change of directory is performed, th program will be launched in a working directory of Ramona server.
Default: (none)
Required: No
Note
You can take benefit of environment variables expansion when defining this option.
[program:fooapp]
directory=${TMPDIR}
Specifies mask of the program. Mask controls which file permissions are set for files and directories when they are created.
If no or empty value is given, to umask is set.
Available only on POSIX platforms.
Default: (none)
Required: No
Example:
[program:foobarapp]
umask=002
The sequence of signals that will be used to terminate a given program. Ramona server, when asked to stop a program, will send first signal (using POSIX kill functionality) from this sequence to given program and set its status to STOPPING. If the program doesn’t terminate, next signal from this sequence is sent after time defined by stoptimeout.
POSIX signal names are used.
When end of this sequence is reached, the KILL signal sent periodically to force program exit.
Default: TERM, INT, TERM, INT, TERM, INT, KILL
Required: No
Example:
[program:foobarapp]
killby=TERM,KILL
List of useful signals:
| Signal | Description |
|---|---|
| TERM | The SIGTERM signal is sent to a process to request its termination. Unlike the SIGKILL signal, it can be caught and interpreted or ignored by the process. This allows the process to perform nice termination releasing resources and saving state if appropriate. It should be noted that SIGINT is nearly identical to SIGTERM. |
| INT | The SIGINT signal is sent to a process when a user wishes to interrupt the process. This is equivalent to pressing Control-C. |
| KILL | The SIGKILL signal is sent to a process to cause it to terminate immediately. In contrast to SIGTERM and SIGINT, this signal cannot be caught or ignored, and the receiving process cannot perform any clean-up upon receiving this signal. |
| QUIT | The SIGQUIT signal is sent to a process when the user requests that the process perform a core dump. See coredump. |
| ABRT | The SIGABRT signal is sent to a process to tell it to abort, i.e. to terminate. The signal is usually initiated by the process itself, but it can be sent to the process from Ramona server as well. |
This defines a timeout interval between each terminate/kill attempt during STOPPING phase of a program life cycle.
Default: 3 seconds
Required: No
How long to keep the program in a STARTING status prior switching in to RUNNING. The program termination during STARTING period is considered as a fatal error, the termination during RUNNING period is considered as likely recoverable and restart attempt will be triggered.
Value is in seconds and is an integer or a floating point number.
Default: 0.5 second
Required: No
Configures how to handle standard output stream of a program. Use one of magic values or specify filesystem path to file, where to store log of a stream.
Default: <stderr>
Required: No
Configures how to handle standard error stream of a program. Use one of magic values or specify filesystem path to file, where to store log of a stream.
Default: <logdir>
Required: No
Priority is used to determine a sequence in which programs are started. Higher priority ensures sooner position in start sequence.
Value has to be an integer, can be negative.
Default: 100
Required: No
Set program state to DISABLED - efectively excludes any option to start this program by Ramona server.
Default: no
Required: No
Example:
[program:foobarposix]
disabled@windows=yes
If enabled, Ramona server sets ulimit (user limit) for core file size (RLIMIT_CORE) to infinite, efectively enabling creation of core dump file when process is terminated by QUIT signal. Actual core dump is requested by -c argument in stop (command-line).
Default: no
Required: No
Enables/disables auto-restart of the program. If enabled, Ramona server will automatically start the relevant supervised program when it terminates unexpectedly (e.g. crash of the program). If program is terminated using stop (command-line) command, it will not be restarted.
Default: no
Required: No
If enabled, program will be started in dedicated process group by using POSIX setsid(2) call. If disabled, program will stay in process group of Ramona server.
Default: yes
Required: No
Available only on POSIX platforms.
Configures log scanner for standard output stream. See Logging and log scanning for more details.
Stream is scanned even if stdout is set to <null>.
Value is sequence of comma-separated (,) scanner rules. Each rule consist of keyword and action in format keyword>action.
Example:
logscan_stdout=error>now:foo2@bar.com,fatal>now,exception>now,warn>daily:foo3@bar.com
Same as logscan_stdout, just scanning standard error stream.
Configure notification, that will be eventually triggered when this program unexpectedly terminates and ends in FATAL state. This is done by specifying the action.
Default: <global>
Required: No
Examples:
[program:foobarcrasher]
notify_fatal=daily:admin@foo.bar.com
The HTTP frontend is added to configuration file as any other program, only with the special option command=<httpfend>.
By default configuration, it is available at http://localhost:5588
Example:
[program:ramonahttpfend]
command=<httpfend>
# Where the HTTP frontend will listen
listen=tcp://localhost:5588
# Use username and password options only if you want to enable basic authentication
username=admin
# Can get either plain text or a SHA1 hash, if the password starts with {SHA} prefix
password=password
One or multiple ‘socket URIs’, where the Ramona HTTP frontend will listen. You can specify more network interfaces, protocols or ports, URIs are comma-separated.
Supported connection variants:
Default: tcp://localhost:5588
Required: No
Username used for authentication to Ramona HTTP frontend. The authentication will be required only if the username option is used.
Default: No default
Required: No
Password to be used in combination with username for authentication. If username option is used, the the password has to be specified as well – Ramona HTTP frontend will fail to start otherwise.
The value can be either a plain text password or a SHA hash of the password. The SHA password hash has to be prefixed with {SHA} prefix, for example:
password={SHA}e5e9fa1ba31ecd1ae84f75caaa474f3a663f05f4
which is a hash for word secret. To generate the hash to be used for the configuration, you can use the following command (works on Linux):
echo -n "secret" | sha1sum
Default: No default
Required: No