1 line
17 KiB
JSON
1 line
17 KiB
JSON
{"name":"poise-service","version":"1.5.2","description":"A Chef cookbook for managing system services.","long_description":"# Poise-Service Cookbook\n\n[](https://travis-ci.org/poise/poise-service)\n[](https://rubygems.org/gems/poise-service)\n[](https://supermarket.chef.io/cookbooks/poise-service)\n[](https://codecov.io/github/poise/poise-service)\n[](https://gemnasium.com/poise/poise-service)\n[](https://www.apache.org/licenses/LICENSE-2.0)\n\nA [Chef](https://www.chef.io/) cookbook to provide a unified interface for\nservices.\n\n### What is poise-service?\n\nPoise-service is a tool for developers of \"library cookbooks\" to define a\nservice without forcing the end-user of the library to adhere to their choice of\nservice management framework. The `poise_service` resource represents an\nabstract service to be run, which can then be customized by node attributes and\nthe `poise_service_options` resource. This is a technique called [dependency\ninjection](https://en.wikipedia.org/wiki/Dependency_injection), and allows a\nmeasure of decoupling between the library and application cookbooks.\n\n### Why would I use poise-service?\n\nPoise-service is most useful for authors of library-style cookbooks, for example\nthe `apache2`, `mysql`, or `application` cookbooks. When using other service\nmanagement options with Chef, the author of the library cookbook has to add\nspecific code for each service management framework they want to support, often\nresulting in a cookbook only supporting the favorite framework of the author or\ndepending on distribution packages for their init scripts. The `poise_service`\nresource allows library cookbook authors a way to write generic code for all\nservice management frameworks while still allowing users of that cookbook to\nchoose which service management framework best fits their needs.\n\n### How is this different from the built-in service resource?\n\nChef includes a `service` resource which allows interacting with certain\nservice management frameworks such as SysV, Upstart, and systemd.\n`poise-service` goes further in that it actually generates the configuration\nfiles needed for the requested service management framework, as well as offering\na dependency injection system for application cookbooks to customize which\nframework is used.\n\n### What service management frameworks are supported?\n\n* [SysV (aka /etc/init.d)](#sysvinit)\n* [Upstart](#upstart)\n* [systemd](#systemd)\n* [Inittab](#inittab)\n* [Runit](https://github.com/poise/poise-service-runit)\n* [Monit](https://github.com/poise/poise-monit#service-provider)\n* [Solaris](https://github.com/sh9189/poise-service-solaris)\n* [AIX](https://github.com/johnbellone/poise-service-aix)\n* *Supervisor (coming soon!)*\n\n\n## Quick Start\n\nTo create a service user and a service to run Apache2:\n\n```ruby\npoise_service_user 'www-data'\n\npoise_service 'apache2' do\n command '/usr/sbin/apache2 -f /etc/apache2/apache2.conf -DFOREGROUND'\n stop_signal 'WINCH'\n reload_signal 'USR1'\nend\n```\n\nor for a hypothetical Rails web application:\n\n```ruby\npoise_service_user 'myapp'\n\npoise_service 'myapp-web' do\n command 'bundle exec unicorn -p 8080'\n user 'myapp'\n directory '/srv/myapp'\n environment RAILS_ENV: 'production'\nend\n```\n\n## Resources\n\n### `poise_service`\n\nThe `poise_service` resource is the abstract definition of a service.\n\n```ruby\npoise_service 'myapp' do\n command 'myapp --serve'\n environment RAILS_ENV: 'production'\nend\n```\n\n#### Actions\n\n* `:enable` – Create, enable and start the service. *(default)*\n* `:disable` – Stop, disable, and destroy the service.\n* `:start` – Start the service.\n* `:stop` – Stop the service.\n* `:restart` – Stop and then start the service.\n* `:reload` – Send the configured reload signal to the service.\n\n#### Attributes\n\n* `service_name` – Name of the service. *(name attribute)*\n* `command` – Command to run for the service. This command must stay in the\n foreground and not daemonize itself. *(required)*\n* `user` – User to run the service as. See\n [`poise_service_user`](#poise_service_user) for any easy way to create service\n users. *(default: root)*\n* `directory` – Working directory for the service. *(default: home directory for\n user, or / if not found)*\n* `environment` – Environment variables for the service.\n* `stop_signal` – Signal to use to stop the service. Some systems will fall back\n to SIGKILL if this signal fails to stop the process. *(default: TERM)*\n* `reload_signal` – Signal to use to reload the service. *(default: HUP)*\n* `restart_on_update` – If true, the service will be restarted if the service\n definition or configuration changes. If `'immediately'`, the notification will\n happen in immediate mode. *(default: true)*\n\n#### Service Options\n\nThe `poise-service` library offers an additional way to pass configuration\ninformation to the final service called \"options\". Options are key/value pairs\nthat are passed down to the service provider and can be used to control how it\ncreates and manages the service. These can be set in the `poise_service`\nresource using the `options` method, in node attributes or via the\n`poise_service_options` resource. The options from all sources are merged\ntogether in to a single hash.\n\nWhen setting options in the resource you can either set them for all providers:\n\n```ruby\npoise_service 'myapp' do\n command 'myapp --serve'\n options status_port: 8000\nend\n```\n\nor for a single provider:\n\n```ruby\npoise_service 'myapp' do\n command 'myapp --serve'\n options :systemd, after_target: 'network'\nend\n```\n\nSetting via node attributes is generally how an end-user or application cookbook\nwill set options to customize services in the library cookbooks they are using.\nYou can set options for all services or for a single service, by service name\nor by resource name:\n\n```ruby\n# Global, for all services.\noverride['poise-service']['options']['after_target'] = 'network'\n# Single service.\noverride['poise-service']['myapp']['template'] = 'myapp.erb'\n```\n\nThe `poise_service_options` resource is also available to set node attributes\nfor a specific service in a DSL-friendly way:\n\n```ruby\npoise_service_options 'myapp' do\n template 'myapp.erb'\n restart_on_update false\nend\n```\n\nUnlike resource attributes, service options can be different for each provider.\nNot all providers support the same options so make sure to check the\ndocumentation for each provider to see what options are available.\n\n### `poise_service_options`\n\nThe `poise_service_options` resource allows setting per-service options in a\nDSL-friendly way. See [the Service Options](#service-options) section for more\ninformation about service options overall.\n\n```ruby\npoise_service_options 'myapp' do\n template 'myapp.erb'\n restart_on_update false\nend\n```\n\n#### Actions\n\n* `:run` – Apply the service options. *(default)*\n\n#### Attributes\n\n* `resource` – Name of the service. *(name attribute)*\n* `for_provider` – Provider to set options for.\n\nAll other attribute keys will be used as options data.\n\n### `poise_service_user`\n\nThe `poise_service_user` resource is an easy way to create service users. It is\nnot required to use `poise_service`, it is only a helper.\n\n```ruby\npoise_service_user 'myapp' do\n home '/srv/myapp'\nend\n```\n\n#### Actions\n\n* `:create` – Create the user and group. *(default)*\n* `:remove` – Remove the user and group.\n\n#### Attributes\n\n* `user` – Name of the user. *(name attribute)*\n* `group` – Name of the group. Set to `false` to disable group creation. *(name attribute)*\n* `uid` – UID of the user. *(default: automatic)*\n* `gid` – GID of the group. *(default: automatic)*\n* `home` – Home directory of the user.\n* `shell` – Shell of the user. *(default: /bin/nologin if present or /bin/false)*\n\n## Providers\n\n### `sysvinit`\n\nThe `sysvinit` provider supports SystemV-style init systems on Debian-family and\nRHEL-family platforms. It will create the `/etc/init.d/<service_name>` script\nand enable/disable the service using the platform-specific service resource.\n\n```ruby\npoise_service 'myapp' do\n provider :sysvinit\n command 'myapp --serve'\nend\n```\n\nBy default a PID file will be created in `/var/run/service_name.pid`. You can\nuse the `pid_file` option detailed below to override this and rely on your\nprocess creating a PID file in the given path.\n\n#### Options\n\n* `pid_file` – Path to PID file that the service command will create.\n* `pid_file_external` – If true, assume the service will create the PID file\n itself. *(default: true if `pid_file` option is set)*\n* `template` – Override the default script template. If you want to use a\n template in a different cookbook use `'cookbook:template'`.\n* `command` – Override the service command.\n* `directory` – Override the service directory.\n* `environment` – Override the service environment variables.\n* `reload_signal` – Override the service reload signal.\n* `stop_signal` – Override the service stop signal.\n* `user` – Override the service user.\n* `never_start` – Never try to start the service.\n* `never_stop` – Never try to stop the service.\n* `never_restart` – Never try to restart the service.\n* `never_reload` – Never try to reload the service.\n* `script_path` – Override the path to the generated service script.\n\n### `upstart`\n\nThe `upstart` provider supports [Upstart](http://upstart.ubuntu.com/). It will\ncreate the `/etc/init/service_name.conf` configuration.\n\n```ruby\npoise_service 'myapp' do\n provider :upstart\n command 'myapp --serve'\nend\n```\n\nAs a wide variety of versions of Upstart are in use in various Linux\ndistributions, the provider does its best to identify which features are\navailable and provide shims as appropriate. Most of these should be invisible\nhowever Upstart older than 1.10 does not support setting a `reload signal` so\nonly SIGHUP can be used. You can set a `reload_shim` option to enable an\ninternal implementaion of reloading to be used for signals other than SIGHUP,\nhowever as this is implemented inside Chef code, running `initctl reload` would\nstill result in SIGHUP being sent. For this reason, the feature is disabled by\ndefault and will throw an error if a reload signal other than SIGHUP is used.\n\n#### Options\n\n* `reload_shim` – Enable the reload signal shim. See above for a warning about\n this feature.\n* `template` – Override the default configuration template. If you want to use a\n template in a different cookbook use `'cookbook:template'`.\n* `command` – Override the service command.\n* `directory` – Override the service directory.\n* `environment` – Override the service environment variables.\n* `reload_signal` – Override the service reload signal.\n* `stop_signal` – Override the service stop signal.\n* `user` – Override the service user.\n* `never_start` – Never try to start the service.\n* `never_stop` – Never try to stop the service.\n* `never_restart` – Never try to restart the service.\n* `never_reload` – Never try to reload the service.\n\n### `systemd`\n\nThe `systemd` provider supports [systemd](http://www.freedesktop.org/wiki/Software/systemd/).\nIt will create the `/etc/systemd/system/service_name.service` configuration.\n\n\n```ruby\npoise_service 'myapp' do\n provider :systemd\n command 'myapp --serve'\nend\n```\n\n#### Options\n\n* `template` – Override the default configuration template. If you want to use a\n template in a different cookbook use `'cookbook:template'`.\n* `command` – Override the service command.\n* `directory` – Override the service directory.\n* `environment` – Override the service environment variables.\n* `reload_signal` – Override the service reload signal.\n* `stop_signal` – Override the service stop signal.\n* `user` – Override the service user.\n* `never_start` – Never try to start the service.\n* `never_stop` – Never try to stop the service.\n* `never_restart` – Never try to restart the service.\n* `never_reload` – Never try to reload the service.\n* `auto_reload` – Run `systemctl daemon-reload` after changes to the unit file. *(default: true)*\n* `restart_mode` – Restart mode for the generated service unit. *(default: on-failure)*\n\n### `inittab`\n\nThe `inittab` provider supports managing services via `/etc/inittab` using\n[SystemV Init](http://www.nongnu.org/sysvinit/). This can provide basic\nprocess supervision even on very old *nix machines.\n\n```ruby\npoise_service 'myapp' do\n provider :inittab\n command 'myapp --serve'\nend\n```\n\n**NOTE:** Inittab does not allow stopping services, and they are started as soon\nas they are enabled.\n\n#### Options\n\n* `never_start` – Never try to start the service.\n* `never_stop` – Never try to stop the service.\n* `never_restart` – Never try to restart the service.\n* `never_reload` – Never try to reload the service.\n* `pid_file` – Path to PID file that the service command will create.\n* `service_id` – Unique 1-4 character tag for the service. Defaults to an\n auto-generated hash based on the service name. If these collide, bad things\n happen. Don't do that.\n\n### `dummy`\n\nThe `dummy` provider supports launching services directly from Chef itself.\nThis is for testing purposes only and is entirely unsuitable for use in\nproduction. This is mostly useful when used alongside kitchen-docker.\n\n```ruby\npoise_service 'myapp' do\n provider :dummy\n command 'myapp --serve'\nend\n```\n\nThe service information is written to `/var/run`. The PID file is `service_name.pid`,\nthe command output is `service_name.out`, and the service parameters are in\n`service_name.json`.\n\n#### Options\n\n* `never_start` – Never try to start the service.\n* `never_stop` – Never try to stop the service.\n* `never_restart` – Never try to restart the service.\n* `never_reload` – Never try to reload the service.\n* `restart_delay` – Number of seconds to wait between stop and start when\n restarting. *(default: 1)*\n\n## ServiceMixin\n\nFor the common case of a resource (LWRP or plain Ruby) that roughly maps to\n\"some config files and a service\" poise-service provides a mixin module,\n`PoiseService::ServiceMixin`. This mixin adds the standard service actions\n(`enable`, `disable`, `start`, `stop`, `restart`, and `reload`) with basic\nimplementations that call those actions on a `poise_service` resource for you.\nYou customize the service by defining a `service_options` method on your\nprovider class:\n\n```ruby\ndef service_options(service)\n # service is the PoiseService::Resource object instance.\n service.command \"/usr/sbin/#{new_resource.name} -f /etc/#{new_resource.name}/conf/httpd.conf -DFOREGROUND\"\n service.stop_signal 'WINCH'\n service.reload_signal 'USR1'\nend\n```\n\nYou will generally want to override the `enable` action to install things\nrelated to the service like packages, users and configuration files:\n\n```ruby\ndef action_enable\n notifying_block do\n package 'apache2'\n poise_service_user 'www-data'\n template \"/etc/#{new_resource.name}/conf/httpd.conf\" do\n # ...\n end\n end\n # This super call will run the normal service enable,\n # creating the service and starting it.\n super\nend\n```\n\nSee [the poise_service_test_mixin resource](test/cookbooks/poise-service_test/resources/mixin.rb)\nand [provider](test/cookbooks/poise-service_test/providers/mixin.rb) for\nexamples of using `ServiceMixin` in an LWRP.\n\n## Sponsors\n\nDevelopment sponsored by [Bloomberg](http://www.bloomberg.com/company/technology/).\n\nThe Poise test server infrastructure is sponsored by [Rackspace](https://rackspace.com/).\n\n## License\n\nCopyright 2015-2016, Noah Kantrowitz\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\nhttp://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","maintainer":"Noah Kantrowitz","maintainer_email":"noah@coderanger.net","license":"Apache-2.0","platforms":{"ubuntu":">= 0.0.0","debian":">= 0.0.0","centos":">= 0.0.0","redhat":">= 0.0.0","fedora":">= 0.0.0","amazon":">= 0.0.0","suse":">= 0.0.0","opensuse":">= 0.0.0"},"dependencies":{"poise":"~> 2.0"},"recommendations":{},"suggestions":{},"conflicting":{},"providing":{},"replacing":{},"attributes":{},"groupings":{},"recipes":{},"source_url":"https://github.com/poise/poise-service","issues_url":"https://github.com/poise/poise-service/issues","chef_version":[["< 14",">= 12"]],"ohai_version":[]} |