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:

    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.