commit: 14e3359a9e4174da3e422957d9de56907f025875
Author: William Hubbs <w.d.hubbs <AT> gmail <DOT> com>
AuthorDate: Wed Jan 10 19:25:13 2018 +0000
Commit: William Hubbs <williamh <AT> gentoo <DOT> org>
CommitDate: Wed Jan 10 19:25:13 2018 +0000
URL: https://gitweb.gentoo.org/proj/openrc.git/commit/?id=14e3359a
move developer documentation from guide.md to service-script-guide.md
guide.md | 125 ++++--------------------------------------------
service-script-guide.md | 109 +++++++++++++++++++++++++++++++++++++++++
2 files changed, 117 insertions(+), 117 deletions(-)
diff --git a/guide.md b/guide.md
index f8c23194..80c8a7d3 100644
--- a/guide.md
+++ b/guide.md
@@ -27,8 +27,8 @@ openrc scans the runlevels (default: `/etc/runlevels`) and
builds a dependency
graph, then starts the needed service scripts, either serialized (default) or
in
parallel.
-When all the init scripts are started openrc terminates. There is no
persistent
-daemon. (Integration with tools like monit, runit or s6 can be done)
+When all the service scripts are started openrc terminates. There is no
+persistent daemon. (Integration with tools like monit, runit or s6 can be done)
# Shutdown
@@ -63,7 +63,7 @@ own if needed. This allows, for example, to have a default
runlevel with
disabled.
The `rc-status` helper will print all currently active runlevels and the state
-of init scripts in them:
+of services in them:
```
# rc-status
@@ -74,7 +74,7 @@ Runlevel: default
```
All runlevels are represented as folders in `/etc/runlevels/` with symlinks to
-the actual init scripts.
+the actual service scripts.
Calling openrc with an argument (`openrc default`) will switch to that
runlevel; this will start and stop services as needed.
@@ -83,122 +83,13 @@ Managing runlevels is usually done through the `rc-update`
helper, but could of
course be done by hand if desired.
e.g. `rc-update add nginx default` - add nginx to the default runlevel
Note: This will not auto-start nginx! You'd still have to trigger `rc` or run
-the initscript by hand.
+the service script by hand.
FIXME: Document stacked runlevels
The default startup uses the runlevels `boot`, `sysinit` and `default`, in
that
order. Shutdown uses the `shutdown` runlevel.
-
-# Syntax of Service Scripts
-
-Service scripts are shell scripts. OpenRC aims at using only the standardized
-POSIX sh subset for portability reasons. The default interpreter (build-time
-toggle) is `/bin/sh`, so using for example mksh is not a problem.
-
-OpenRC has been tested with busybox sh, ash, dash, bash, mksh, zsh and
possibly
-others. Using busybox sh has been difficult as it replaces commands with
-builtins that don't offer the expected features.
-
-The interpreter for initscripts is `#!/sbin/openrc-run`.
-Not using this interpreter will break the use of dependencies and is not
-supported. (iow: if you insist on using `#!/bin/sh` you're on your own)
-
-A `depend` function declares the dependencies of this service script.
-All scripts must have start/stop/status functions, but defaults are provided.
-Extra functions can be added easily:
-
-```
-extra_commands="checkconfig"
-checkconfig() {
- doSomething
-}
-```
-
-This exports the checkconfig function so that `/etc/init.d/someservice
-checkconfig` will be available, and it "just" runs this function.
-
-While commands defined in `extra_commands` are always available, commands
-defined in `extra_started_commands` will only work when the service is started
-and those defined in `extra_stopped_commands` will only work when the service
is
-stopped. This can be used for implementing graceful reload and similar
-behaviour.
-
-Adding a restart function will not work, this is a design decision within
-OpenRC. Since there may be dependencies involved (e.g. network -> apache) a
-restart function is in general not going to work.
-restart is internally mapped to `stop()` + `start()` (plus handling
dependencies).
-If a service needs to behave differently when it is being restarted vs
-started or stopped, it should test the `$RC_CMD` variable, for example:
-
-```
-[ "$RC_CMD" = restart ] && do_something
-```
-
-# The Depend Function
-
-This function declares the dependencies for a service script. This
-determines the order the service scripts start.
-
-```
-depend() {
- need net
- use dns logger netmount
- want coolservice
-}
-```
-
-`need` declares a hard dependency - net always needs to be started before this
- service does
-
-`use` is a soft dependency - if dns, logger or netmount is in this runlevel
- start it before, but we don't care if it's not in this runlevel.
- `want` is between need and use - try to start coolservice if it is
- installed on the system, regardless of whether it is in the
- runlevel, but we don't care if it starts.
-
-`before` declares that we need to be started before another service
-
-`after` declares that we need to be started after another service, without
- creating a dependency (so on calling stop the two are independent)
-
-`provide` allows multiple implementations to provide one service type, e.g.:
- `provide cron` is set in all cron-daemons, so any one of them started
- satisfies a cron dependency
-
-`keyword` allows platform-specific overrides, e.g. `keyword -lxc` makes this
- service script a noop in lxc containers. Useful for things like
keymaps,
- module loading etc. that are either platform-specific or not available
- in containers/virtualization/...
-
-FIXME: Anything missing in this list?
-
-# The Default Functions
-
-All service scripts are assumed to have the following functions:
-
-```
-start()
-stop()
-status()
-```
-
-There are default implementations in `lib/rc/sh/openrc-run.sh` - this allows
very
-compact service scripts. These functions can be overridden per service script
as
-needed.
-
-The default functions assume the following variables to be set in the service
-script:
-
-```
-command=
-command_args=
-pidfile=
-```
-
-Thus the 'smallest' service scripts can be half a dozen lines long
-
# The Magic of `conf.d`
Most service scripts need default values. It would be fragile to
@@ -217,7 +108,7 @@ start() {
}
```
-The big advantage of this split is that most of the time editing of the init
+The big advantage of this split is that most of the time editing of the
service
script can be avoided.
# Start-Stop-Daemon
@@ -271,7 +162,7 @@ happen automatically when the service is stopped.
# Caching
-For performance reasons OpenRC keeps a cache of pre-parsed initscript metadata
+For performance reasons OpenRC keeps a cache of pre-parsed service metadata
(e.g. `depend`). The default location for this is `/${RC_SVCDIR}/cache`.
The cache uses `mtime` to check for file staleness. Should any service script
@@ -281,5 +172,5 @@ change it'll re-source the relevant files and update the
cache
OpenRC has wrappers for many common output tasks in libeinfo.
This allows to print colour-coded status notices and other things.
-To make the output consistent the bundled initscripts all use ebegin/eend to
+To make the output consistent the bundled service scripts all use ebegin/eend
to
print nice messages.
diff --git a/service-script-guide.md b/service-script-guide.md
index 668d05d4..4839e1b4 100644
--- a/service-script-guide.md
+++ b/service-script-guide.md
@@ -13,6 +13,115 @@ don't consider anything exotic, and assume that you will use
start-stop-daemon to manage a fairly typical long-running UNIX
process.
+## Syntax of Service Scripts
+
+Service scripts are shell scripts. OpenRC aims at using only the standardized
+POSIX sh subset for portability reasons. The default interpreter (build-time
+toggle) is `/bin/sh`, so using for example mksh is not a problem.
+
+OpenRC has been tested with busybox sh, ash, dash, bash, mksh, zsh and
possibly
+others. Using busybox sh has been difficult as it replaces commands with
+builtins that don't offer the expected features.
+
+The interpreter for service scripts is `#!/sbin/openrc-run`.
+Not using this interpreter will break the use of dependencies and is not
+supported. (iow: if you insist on using `#!/bin/sh` you're on your own)
+
+A `depend` function declares the dependencies of this service script.
+All scripts must have start/stop/status functions, but defaults are provided
and should be used unless you have a very strong reason not to use them.
+
+Extra functions can be added easily:
+
+```
+extra_commands="checkconfig"
+checkconfig() {
+ doSomething
+}
+```
+
+This exports the checkconfig function so that `/etc/init.d/someservice
+checkconfig` will be available, and it "just" runs this function.
+
+While commands defined in `extra_commands` are always available, commands
+defined in `extra_started_commands` will only work when the service is started
+and those defined in `extra_stopped_commands` will only work when the service
is
+stopped. This can be used for implementing graceful reload and similar
+behaviour.
+
+Adding a restart function will not work, this is a design decision within
+OpenRC. Since there may be dependencies involved (e.g. network -> apache) a
+restart function is in general not going to work.
+restart is internally mapped to `stop()` + `start()` (plus handling
dependencies).
+If a service needs to behave differently when it is being restarted vs
+started or stopped, it should test the `$RC_CMD` variable, for example:
+
+```
+[ "$RC_CMD" = restart ] && do_something
+```
+
+## The Depend Function
+
+This function declares the dependencies for a service script. This
+determines the order the service scripts start.
+
+```
+depend() {
+ need net
+ use dns logger netmount
+ want coolservice
+}
+```
+
+`need` declares a hard dependency - net always needs to be started before this
+ service does
+
+`use` is a soft dependency - if dns, logger or netmount is in this runlevel
+ start it before, but we don't care if it's not in this runlevel.
+ `want` is between need and use - try to start coolservice if it is
+ installed on the system, regardless of whether it is in the
+ runlevel, but we don't care if it starts.
+
+`before` declares that we need to be started before another service
+
+`after` declares that we need to be started after another service, without
+ creating a dependency (so on calling stop the two are independent)
+
+`provide` allows multiple implementations to provide one service type, e.g.:
+ `provide cron` is set in all cron-daemons, so any one of them started
+ satisfies a cron dependency
+
+`keyword` allows platform-specific overrides, e.g. `keyword -lxc` makes this
+ service script a noop in lxc containers. Useful for things like
keymaps,
+ module loading etc. that are either platform-specific or not available
+ in containers/virtualization/...
+
+FIXME: Anything missing in this list?
+
+## The Default Functions
+
+All service scripts are assumed to have the following functions:
+
+```
+start()
+stop()
+status()
+```
+
+There are default implementations in `lib/rc/sh/openrc-run.sh` - this allows
very
+compact service scripts. These functions can be overridden per service script
as
+needed.
+
+The default functions assume the following variables to be set in the service
+script:
+
+```
+command=
+command_args=
+pidfile=
+```
+
+Thus the 'smallest' service scripts can be half a dozen lines long
+
## Don't write your own start/stop functions
OpenRC is capable of stopping and starting most daemons based on the
