supervisors

Synopsis

Provide a list of supervisor instances

This is a reference part. Refer to the associated overview for a more synthetical view.

Attributes

Each item of the list has the following attribute:

Name	req?	Description
name	yes	Name of the supervisor.
scope	yes	On which target does this supervisor be deployed? May be: A single `host` name A single `host_group` name Several `hosts` or `host_groups`, separated by the character ':'
user	yes	The owner of this supervisor. This account will be allowed to fully control all associated `supervisor_programs`.
group	yes	The group of the owner.
managed	no	Boolean. Did this supervisor under the control of HADeploy ? If `no`, it will only act as a description to be referenced by `supervisor_programs` You will find more information on what this attribute is intended for in Supervisor overview / Non-root deployment Default: `yes`
no_remove	no	Boolean: Prevent this supervisor to be removed when HADeploy will be used with `--action remove`. Default: `no`
enabled	no	Is this supervisord instance daemon start on system boot ? Default: `yes`.
state	no	`started`: The supervisors instance daemon will be started on deployment `stopped`: The supervisord instance daemon will be stopped on deployment. `current`: The supervisord instance daemon state will be left unchanged during deployment. (stopped on initial creation). Default value: `started`.
http_server	no	Allow a management HTTP server to be exposed. See Web Interface below to see how to activate and configure it.
when	no	Boolean. Allow conditional deployment of this item. Default `True`

Based on these parameters, HADeploy will instanciate a specific supervisord daemon, with the following characteristics:

The deamon is a systemd service of name supervisord_<name>.service.
Its associated supervisorctl client is named supervisorctl_<name>
As a general rules, all associated files and folders layout are the same than the original supervisor, except postfixed by _<name>. (See the default value of the supplementary attributes below).

If you need to modify this layout, you can use the following supplementary attributes:

Name	req?	Description
conf_file_dst	no	Define the location of the supervisor instance configuration file. Default is `/etc/supervisord_<name>.conf`
logs_dir	no	Define the location of the supervisor instance logs folder. Default is `/var/log/supervisor_<name>/`
pid_dir	no	Define the location of the supervisor instance pid folder. Default is `/var/run/supervisor_<name>/`
socks_dir	no	Communication between supervisord daemon and the supervisorctl client use a local UNIX domain socket file located in this folder. Default is `/var/run/supervisor_<name>`
supervisorctl	no	For each supervisor instance, HADeploy will generate a shortcut for the command line management tool, build from the supervisor name. Default is `/usr/bin/supervisorctl_<name>`
conf_file_src	no	All supervisor instance parameters are stored in a configuration file. Such file is generated by HADeploy from a template, populated with attributes described in this page. If you need deeper control, you can provide our own template. See Provided configuration file below.

Web interface

Each supervisor instance can expose a small admin Web interface like this: Screenshot

To activate this interface, you need to define the attribute http_server as a map with the following sub-attribute:

Name	req?	Description
endpoint	no	The bind address and port of this web server. Default is `127.0.0.0:9001` (Can be only acceded locally, on port 9001). If you want this web server to be accesible remotly, you must modify this value. For example, `0.0.0.0:9001` will bind on all interfaces, on port 9001.
username	no	Used to force a login to protect this interface. Default is open interface if no password is provided, or the supervisor's user if a password is provided.
password	no	Used to force a login to protect this interface. Can be a clear text password (to be avoided!) or an SHA-1 value. See below.

One limit of this interface is it manage only a single server. If you have a cluster of nodes with installed supervisors, there is several third party products which will provide you with centralized view of your application. Check this link

Password

An obvious good practice is to not put clear text password in configuration file. Fortunatly, supervisor allow to provide the password as its SHA-1 hash value, prefixed by {SHA}.

For example, {SHA}82ab876d1387bfafe46cc1c8a2ef074eae50cb1d is the SHA-stored version of the password thepassword.

Here is a trick to generate such password. Just enter:

python -c 'import hashlib; print "{SHA}" + hashlib.sha1("thepassword").hexdigest()'

Example

Here is a typical supervisor definition, with an HTTP server exposed on port 9003.

supervisors:
- name: tech1 
  scope: all
  user: tsup
  group: tsup
  http_server: 
    endpoint: 0.0.0.0:9003
    username: admin
    password: "{SHA}d033e22ae348aeb5660fc2140aec35850c4da997"

Once logged on the target node under the tsup account, you can launch the client command line interface:

[tsup@dg17 ~]$ supervisorctl_tech1
program1                         STOPPED   Not started
program2                         RUNNING   pid 10623, uptime 0:33:30
program3                         RUNNING   pid 23687, uptime 21:09:50
supervisor> help

default commands (type help <topic>):
=====================================
add    clear  fg        open  quit    remove  restart   start   stop  update
avail  exit   maintail  pid   reload  reread  shutdown  status  tail  version

Of course, here there is already some programs launched. See supervisor_programs

Here is another example where one want to relocate all related file in a specific folder:

folders:
- { scope: all, path: /opt/tech2, owner: tsup, group: tsup, mode: "0755" } 

supervisors:
- name: tech2
  scope: all
  user: tsup
  group: tsup
  conf_file_dst: /opt/tech2/supervisord.conf
  logs_dir: /opt/tech2/logs
  pid_dir: /opt/tech2/run
  socks_dir: /opt/tech2/pid
  include_dir: /opt/tech2/supervisord.d
  supervisorctl: /opt/tech2/supervisorctl

Then, the command line interface will be launched using:

[tsup@dg17 ~]$ /opt/tech2/supervisorctl
program4                         RUNNING   pid 23701, uptime 21:17:01

System instance

When installing its own instance of the supervisor program, HADeploy will first install the supervisor system package. This will create a first, system default, instance.

By default, this instance is not activated:

[root@dg17:~]# systemctl status supervisord
● supervisord.service - Process Monitoring and Control Daemon
   Loaded: loaded (/usr/lib/systemd/system/supervisord.service; disabled; vendor preset: disabled)
   Active: inactive (dead)

It is up to the user to activate it if needed. But keep in mind this instance is under root control, and as such can't be managed by non-priviledged users.

Provided configuration file.

This is Advanded configuration.

At the hearth of each instance of supervisor is a main configuration file, used by both the supervisord_<name> daemon and the supervisorctl_<name> command line interface.

Such file is generated by HADeploy by populating a template from the values provided as attributes.

In most case this will be sufficient. But if, for some specifics cases, you need to modify other parameters of this configuration file, you can provide your own template.

Of course, you should be familiar with the original supervisor configuration syntax.

Then, you can provide your own file using the conf_file_sr attribute, by providing it as a file, or as a template, such as:

supervisors:
- name: tech2
  ...
  conf_file_src: tmpl://supervisord_tech2.conf.jj2
  ...

This will be handled as usual files or template ressource (See here)

_{NB: Only file:// or tmpl:// schema are allowed here.}

As a starting point, here is the provided template:

;  supervisor_{{{name}}}.conf (HADeploy generated) 

[unix_http_server]
file={{{socks_dir}}}/supervisor.sock   ; (the path to the socket file)
chmod=0700                 ; sockef file mode (default 0700)
chown={{{user}}}           ; socket file uid:gid owner
chgrp={{{group}}}
;username=user              ; (default is no username (open server))
;password=123               ; (default is no password (open server))

{{% if http_server is defined %}}
[inet_http_server]         ; inet (TCP) server disabled by default
port={{{ http_server.endpoint }}}        ; (ip_address:port specifier, *:port for all iface)
{{% if http_server.password is defined %}}
username={{{ http_server.username }}}              ; (default is no username (open server))
password={{{ http_server.password }}}               ; (default is no password (open server))
{{% endif %}}
{{% endif %}}

[supervisord]
logfile={{{logs_dir}}}/supervisord.log  ; (main log file;default $CWD/supervisord.log)
logfile_maxbytes=50MB       ; (max main logfile bytes b4 rotation;default 50MB)
logfile_backups=10          ; (num of main logfile rotation backups;default 10)
loglevel=debug               ; (log level;default info; others: debug,warn,trace)
pidfile={{{pid_dir}}}/supervisord.pid ; (supervisord pidfile;default supervisord.pid)
nodaemon=false              ; (start in foreground if true;default false)
minfds=1024                 ; (min. avail startup file descriptors;default 1024)
minprocs=200                ; (min. avail process descriptors;default 200)
umask=022                  ; (process file creation umask;default 022)
user={{{user}}}                 ; (default is current user, required if root)
identifier=supervisor_{{{name}}}       ; (supervisord identifier, default is 'supervisor')
;directory=/tmp              ; (default is not to cd during start)
;nocleanup=true              ; (don't clean up tempfiles at start;default false)
;childlogdir=/tmp            ; ('AUTO' child log dir, default $TEMP)
;environment=KEY=value       ; (key value pairs to add to environment)
;strip_ansi=false            ; (strip ansi escape codes in logs; def. false)

; the below section must remain in the config file for RPC
; (supervisorctl/web interface) to work, additional interfaces may be
; added by defining them in separate rpcinterface: sections
[rpcinterface:supervisor]
supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface

[supervisorctl]
serverurl=unix://{{{socks_dir}}}/supervisor.sock ; use a unix:// URL  for a unix socket
;serverurl=http://127.0.0.1:9001 ; use an http:// url to specify an inet socket
;username=chris              ; should be same as http_username if set
;password=123                ; should be same as http_password if set
;prompt=mysupervisor         ; cmd line prompt (default "supervisor")
;history_file=~/.sc_history  ; use readline history if available


[include]
files = {{{include_dir}}}/*.ini

You can see than variable hosting configuration attribute are of the form {{{...}}}. If you want to use your own variable (Set in the vars:block), you must use the {{...}}notation. More information on variable syntax in Under the hood

You should note also there is no part about the managed programs themself. (No [program:x] section). Such part will be managed by 'supervisor_programs`, by adding files in the include folder defined at the end.

Also, another better starting point if you plan to provide you own template would be to use the one corresponding to you version of HADeploy. You can easely grab it from Github, by setting the tag corresponding to your version.