Welcome to simplevisor’s documentation!¶

pip/easy_install way¶

You can automatically install it through easy_install:

easy_install simplevisor

or pip:

pip install simplevisor

tarball¶

You can install it through the tarball, download the latest one from http://pypi.python.org/pypi/simplevisor, unpack it, cd into the directory and install it:

version=X
wget http://pypi.python.org/packages/source/s/simplevisor/simplevisor-${version}.tar.gz
tar xvzf simplevisor-${version}.tar.gz
cd simplevisor-${version}
# Run the tests
python setup.py test
# Install it
python setup.py install

rpm¶

RPMs are available for Fedora main branches and EPEL 5/6, you can simply install it with yum:

yum install python-simplevisor

SYNOPSIS¶

simplevisor [–conf CONF] [–conftype CONFTYPE] [–daemon] [–interval INTERVAL] [-h] [–log LOG] [–logfile LOGFILE] [–loglevel LOGLEVEL] [–logname LOGNAME] [-p PIDFILE] [–store STORE] [–version] command [path]

DESCRIPTION¶

Simplevisor is a simple daemons supervisor, it is inspired by Erlang OTP and it can supervise hierarchies of services.

COMMANDS

If a path is given or only one service entry is given:

for a given X command

run the service X command where service is the only entry provided or the entry identified by its path

If a path is given and the root entry is a supervisor:

restart_child

tell a running simplevisor process to restart the child identified by the given path; it is different from the restart command as described above because, this way, we are sure that the running simplevisor will not attempt to check/start/stop the child while we restart it

If a path is not given and the root entry is a supervisor:

start

start the simplevisor process which start the supervision. It can be used with –daemon if you want it as daemon

stop

stop the simplevisor process and all its children, if running

status

return the status of the simplevisor process

check

return the comparison between the expected state and the actual state. 0 -> everything is fine 1 -> warning, not expected

single

execute one cycle of supervision and exit. Useful to be run in a cron script

wake_up

tell a running simplevisor process to wake up and supervise

stop_supervisor

only stop the simplevisor process but not the children

stop_children

only stop the children but not the simplevisor process

check_configuration

only check the configuration file

pod

generate pod format help to be used by pod2man to generate man page

rst

generate rst format help to be used in the web doc

help

same as -h/–help, print help page

OPTIONS¶

positional arguments:

command

check, check_configuration, help, pod, restart, restart_child, rst, single, start, status, stop, stop_children, stop_supervisor, wake_up

path

path to a service, subset of commands available: start, stop, status, check, restart

optional arguments:

–conf CONF

configuration file

–conftype CONFTYPE

configuration file type (default: apache)

–daemon

daemonize, ONLY with start

–interval INTERVAL

interval to wait between supervision cycles (default: 60)

-h, –help

print the help page

–log LOG

available: null, file, syslog, stdout (default: stdout)

–logfile LOGFILE

log file, ONLY for file

–loglevel LOGLEVEL

log level (default: warning)

–logname LOGNAME

log name (default: simplevisor)

-p, –pidfile PIDFILE

the pidfile

–store STORE

file where to store the state, it is not mandatory, however recommended to store the simplevisor nodes status between restarts

–version

print the program version

EXAMPLES¶

Create and edit the main configuration file:

## look for simplevisor.conf.example in the examples.

Run it:

simplevisor --conf /path/to/simplevisor.conf start

to run it in daemon mode:

simplevisor --conf /path/to/simplevisor.conf --daemon start

For other commands:

simplevisor --help

Given the example configuration, to start the httpd service:

simplevisor --conf /path/to/simplevisor.conf start svisor1/httpd

AUTHOR¶

Massimo Paladin <massimo.paladin@gmail.com> - Copyright (C) CERN 2013-2016

NAME¶

simplevisor-control - run simplevisor as a service

SYNOPSIS¶

simplevisor-control command [path]

DESCRIPTION¶

simplevisor-control command can be used to run simplevisor as a service.

OPTIONS¶

command one of: start, stop, restart, status, check

path look at simplevisor man page for path behavior

EXAMPLES¶

On linux you can look at the script shipped in the examples folder which is called simplevisor-new-instance, it creates folders and the configuration to run a simplevisor instance.

mkdir -p /var/lib/myinstance/bin
mkdir -p /var/lib/myinstance/data
mkdir -p /var/lib/myinstance/etc

Create a file /var/lib/myinstance/bin/service with content and make it executable:

#!/bin/sh
#
# init script that can be symlinked from /etc/init.d
#

# chkconfig: - 90 15
# description: my simplevisor instance

. "/var/lib/myinstance/etc/simplevisor.profile"
exec "/usr/bin/simplevisor-control" ${1+"$@"}

/var/lib/myinstance/etc/simplevisor.profile could look like:

# main
export SIMPLEVISOR_NAME=myinstance
# if you want to run it as another user:
#export SIMPLEVISOR_USER=games
export SIMPLEVISOR_CONF=/var/lib/myinstance/etc/simplevisor.conf
export SIMPLEVISOR_PIDFILE=/var/lib/myinstance/data/simplevisor.pid
export SIMPLEVISOR_LOCKFILE=/var/lib/myinstance/data/simplevisor.lock

Create /var/lib/myinstance/etc/simplevisor.conf according to simplevisor documentation.

For Red Hat or Fedora you can symlink service script:

ln -s /var/lib/myinstance/bin/service /etc/init.d/myinstance

And use it as a normal service:

/sbin/service myinstance start|stop|status|restart|check

AUTHOR¶

Massimo Paladin <massimo.paladin@gmail.com>

Copyright (C) CERN 2013-2016

Parameters¶

name

unique name of the supervisor.

window

window of supervision cycles which should be considered when defining if a supervisor is in a failing state.

adjustments

maximum number of cycles on which a child adjustment was needed in the given window of supervision cycle in order to consider it a failure.

strategy

• one_for_one: if a child process terminates, only that process is restarted.
• one_for_all: if a child process terminates, all other child processes are terminated and then all child processes, including the terminated one, are restarted.
• rest_for_one: If a child process terminates, the rest of the child processes i.e. the child processes after the terminated process in start order are terminated. Then the terminated child process and the rest of the child processes are restarted.

expected

none|running|stopped

children

children structure.

Required Parameters¶

- children section is required or supervisor is not useful

Default Parameters¶

- name = supervisor
- expected = none
- window = 12
- adjustments = 3
- strategy = one_for_one

Copyright (C) 2013-2016 CERN

Parameters¶

control

the control of the command to run. If specified it will be the prefix of start/stop/status commands.

daemon

if the service command runs in foreground and you wish to daemonize it you can declare this option with value the pidfile path that should be used for the daemonization.

If control is specified this option is ignored.

Given the start command:

start = /path/to/script --conf /path/to/conf

and declaring:

daemon = /path/to/script_pidfile.pid

it is like specifying the following pair of commands/values:

start = /usr/bin/simplevisor-loop -c 1 --pidfile /path/to/script_pidfile.pid --daemon /path/to/script --conf /path/to/conf

stop = /usr/bin/simplevisor-loop --pidfile /path/to/script_pidfile.pid --quit

status = /usr/bin/simplevisor-loop --pidfile /path/to/script_pidfile.pid --status

Hence, if daemon is specified stop and status command are overwritten.

expected

expected state of the service. Valid values are running and stopped.

name

unique name of the worker/service.

path

the path for executing the commands. Multiple values should be separated by colons.

pattern

used to look for the service in the process table for stop and status commands if they are not specified and control is also not specified. Accepted values are valid python regular expressions: re.

restart

specify a custom restart command.

If <control> is specified:

• if <restart> is not specified “<control> restart” is executed
• if <restart> = “stop+start” a “<control> stop” followed by a “<control> start” is executed
• else “<restart>” is executed

If <control> is not specified:

• if <restart> is not specified “<stop>” followed by “<start>” is executed
• else “<restart>” is executed

start

specify a custom start command.

If <control> is specified:

• if <start> is not specified “<control> start” is executed
• else “<start>” is executed

If <control> is not specified:

• “<start>” is executed

status

specify a custom status command.

If <control> is specified:

• “<control> status” is executed

If <control> is not specified:

• if <status> is specified “<status>” is executed
• else it will look for it in the process table either looking for the start command or the provided pattern.

Status commands are expected to exit with return code according to the following following:

• 0: the service is running fine
• 3: the service is stopped
• other: return code is interpreted as dirty/zombie/hang state

stop

specify a custom stop command.

If <control> is specified:

• “<control> stop” is executed

If <control> is not specified:

• if <stop> is specified “<stop>” is executed
• else it will look for it in the process table either looking for the start command or the provided pattern and then kill it.

timeout

the maximum timeout for any service command, set to 60 seconds by default.

Required Parameters¶

- name
- one of: start, control

Default Parameters¶

- expected = running
- timeout = 60
- all the others are default to None

Copyright (C) 2013-2016 CERN