The_official_online_compendium_for_Mining_the_Soci_

Description =========== Installs runit and provides the `runit_service` service resource for managing processes (services) under runit. This cookbook does not use runit to replace system init, nor are there plans to do so. For more information about runit: * http://smarden.org/runit/ About Runit =========== In brief, Runit is a process supervision suite. It is simple to set up, and doesn't require complex shell scripts to be written to start processes running as system services. To manage a process in runit, create a "service" directory that contains a "`run`" script. In this cookbook we refer to that directory as the `sv_dir` (see __Attributes__ and __Resource/Provider__). That service directory is symbolically linked into runit's own service directory where its `runsvdir` program looks for processes to manage. See the [runit documentation](http://smarden.org/runit/) for detailed information on runit. Supervised processes are analogous to services under other systems such as sysvinit or upstart. Requirements ============ ## Platform: * Debian/Ubuntu * Gentoo * RHEL Attributes ========== See `attributes/default.rb` for defaults generated per platform. * `node['runit']['sv_bin']` - Full path to the `sv` binary. * `node['runit']['chpst_bin']` - Full path to the `chpst` binary. * `node['runit']['service_dir']` - Full path to the default "services" directory where enabled services are linked. * `node['runit']['sv_dir']` - Full path to the directory where service lives, which gets linked to `service_dir`. * `node['runit']['start']` - Command to start the runsvdir service * `node['runit']['stop]` - Command to stop the runsvdir service * `node['runit']['reload']` - Command to reload the runsvdir service Recipes ======= default ------- The default recipe installs runit and starts `runsvdir` to supervise the services in runit's service directory (e.g., `/etc/service`). On RHEL family systems, it will build the runit RPM using [Ian Meyer's runit RPM SPEC](https://github.com/imeyer/runit-rpm). On Debian family systems, the runit packages are maintained by the runit author, Gerrit Pape, and the recipe will use that for installation. On Gentoo, the runit ebuild package is installed. Resource/Provider ================= This cookbook has a resource, `runit_service`, for managing services under runit. This service subclasses the Chef `service` resource. **This resource replaces the runit_service definition. See the CHANGELOG.md file in this cookbook for breaking change information and any actions you may need to take to update cookbooks using runit_service.** ## Actions: - **enable** - enables the service, creating the required run scripts and symlinks. This is the default action. - **start** - starts the service with `sv start` - **stop** - stops the service with `sv stop` - **disable** - stops the service with `sv down` and removes the service symlink - **restart** - restarts the service with `sv restart` - **reload** - reloads the service with `sv force-reload` - **once** - starts the service with `sv once`. - **hup** - sends the `HUP` signal to the service with `sv hup` - **cont** - sends the `CONT` signal to the service - **term** - sends the `TERM` signal to the service - **kill** - sends the `KILL` signal to the service - **up** - starts the service with `sv up` - **down** - downs the service with `sv down` - **usr1** - sends the `USR1` signal to the service with `sv 1` - **usr2** - sends the `USR2` signal to the service with `sv 2` Service management actions are taken with runit's "`sv`" program. Read the `sv(8)` [man page](http://smarden.org/runit/sv.8.html) for more information on the `sv` program. ## Parameter Attributes The first three parameters, `sv_dir`, `service_dir`, and `sv_bin` will attempt to use the corresponding node attributes, and fall back to hardcoded default values that match the settings used on Debian platform systems. Many of these parameters are only used in the `:enable` action. - **sv_dir** - The base "service directory" for the services managed by the resource. By default, this will attempt to use the `node['runit']['sv_dir']` attribute, and falls back to `/etc/sv`. - **service_dir** - The directory where services are symlinked to be supervised by `runsvdir`. By default, this will attempt to use the `node['runit']['service_dir']` attribute, and falls back to `/etc/service`. - **sv_bin** - The path to the `sv` program binary. This will attempt to use the `node['runit']['sv_bin']` attribute, and falls back to `/usr/bin/sv`. - **service_name** - *Name attribute*. The name of the service. This will be used in the directory of the managed service in the `sv_dir` and `service_dir`. - **sv_templates** - If true, the `:enable` action will create the service directory with the appropriate templates. Default is `true`. Set this to `false` if the service has a package that provides its own service directory. See __Usage__ examples. - **options** - Options passed as variables to templates, for compatibility with legacy runit service definition. Default is an empty hash. - **env** - A hash of environment variables with their values as content used in the service's `env` directory. Default is an empty hash. - **log** - Whether to start the service's logger with svlogd, requires a template `sv-service_name-log-run.erb` to configure the log's run script. Default is true. - **default_logger** - Whether a default `log/run` script should be set up. If true, the default content of the run script will use `svlogd` to write logs to `/var/log/service_name`. Default is false. - **cookbook** - A cookbook where templates are located instead of where the resource is used. Applies for all the templates in the `enable` action. - **finish** - whether the service has a finish script, requires a template `sv-service_name-finish.erb` - **control** - An array of signals to customize control of the service, see [runsv man page](http://smarden.org/runit/runsv.8.html) on how to use this. This requires that each template be created with the name `sv-service_name-signal.erb`. - **owner** - user that should own the templates created to enable the service - **group** - group that should own the templates created to enable the service - **run_template_name** - alternate filename of the run run script to use replacing `service_name`. - **log_template_name** - alternate filename of the log run script to use replacing `service_name`. - **finish_script_template_name** - alternate filename of the finish script to use, replacing `service_name`. - **control_template_names** - a hash of control signals (see *control* above) and their alternate template name(s) replacing `service_name`. - **status_command** - The command used to check the status of the service to see if it is enabled/running (if it's running, it's enabled). This hardcodes the location of the sv program to `/usr/bin/sv` due to the aforementioned cookbook load order. Unlike previous versions of the cookbook using the `runit_service` definition, the `runit_service` resource can be notified. See __Usage__ examples below. Usage ===== To get runit installed on supported platforms, use `recipe[runit]`. Once it is installed, use the `runit_service` resource to set up services to be managed by runit. In order to use the `runit_service` resource in your cookbook(s), each service managed will also need to have `sv-service_name-run.erb` and `sv-service_name-log-run.erb` templates created. If the `log` parameter is false, the log run script isn't created. If the `log` parameter is true, and `default_logger` is also true, the log run script will be created with the default content: #!/bin/sh exec svlogd -tt /var/log/service_name Examples -------- These are example use cases of the `runit_service` resource described above. There are others in the `runit_test` cookbook t