From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <gentoo-commits+bounces-996869-garchives=archives.gentoo.org@lists.gentoo.org>
Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80])
(using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))
(No client certificate requested)
by finch.gentoo.org (Postfix) with ESMTPS id F3046138330
for <garchives@archives.gentoo.org>; Wed, 10 Jan 2018 19:30:02 +0000 (UTC)
Received: from pigeon.gentoo.org (localhost [127.0.0.1])
by pigeon.gentoo.org (Postfix) with SMTP id 37D3DE09FE;
Wed, 10 Jan 2018 19:30:02 +0000 (UTC)
Received: from smtp.gentoo.org (mail.gentoo.org [IPv6:2001:470:ea4a:1:5054:ff:fec7:86e4])
(using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits))
(No client certificate requested)
by pigeon.gentoo.org (Postfix) with ESMTPS id F378BE09FE
for <gentoo-commits@lists.gentoo.org>; Wed, 10 Jan 2018 19:30:01 +0000 (UTC)
Received: from oystercatcher.gentoo.org (oystercatcher.gentoo.org [148.251.78.52])
(using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits))
(No client certificate requested)
by smtp.gentoo.org (Postfix) with ESMTPS id 262B4335C47
for <gentoo-commits@lists.gentoo.org>; Wed, 10 Jan 2018 19:30:00 +0000 (UTC)
Received: from localhost.localdomain (localhost [IPv6:::1])
by oystercatcher.gentoo.org (Postfix) with ESMTP id 7B930133
for <gentoo-commits@lists.gentoo.org>; Wed, 10 Jan 2018 19:29:58 +0000 (UTC)
From: "William Hubbs" <williamh@gentoo.org>
To: gentoo-commits@lists.gentoo.org
Content-Transfer-Encoding: 8bit
Content-type: text/plain; charset=UTF-8
Reply-To: gentoo-dev@lists.gentoo.org, "William Hubbs" <williamh@gentoo.org>
Message-ID: <1515612313.14e3359a9e4174da3e422957d9de56907f025875.williamh@OpenRC>
Subject: [gentoo-commits] proj/openrc:master commit in: /
X-VCS-Repository: proj/openrc
X-VCS-Files: guide.md service-script-guide.md
X-VCS-Directories: /
X-VCS-Committer: williamh
X-VCS-Committer-Name: William Hubbs
X-VCS-Revision: 14e3359a9e4174da3e422957d9de56907f025875
X-VCS-Branch: master
Date: Wed, 10 Jan 2018 19:29:58 +0000 (UTC)
Precedence: bulk
List-Post: <mailto:gentoo-commits@lists.gentoo.org>
List-Help: <mailto:gentoo-commits+help@lists.gentoo.org>
List-Unsubscribe: <mailto:gentoo-commits+unsubscribe@lists.gentoo.org>
List-Subscribe: <mailto:gentoo-commits+subscribe@lists.gentoo.org>
List-Id: Gentoo Linux mail <gentoo-commits.gentoo.org>
X-BeenThere: gentoo-commits@lists.gentoo.org
X-Archives-Salt: 3129281a-8b89-4f27-aaac-04891b501bb1
X-Archives-Hash: 4d769ce56c2cc937c02eba4f90276ee0
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