From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <gentoo-commits+bounces-996348-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 E217A138330
for <garchives@archives.gentoo.org>; Tue, 9 Jan 2018 01:50:02 +0000 (UTC)
Received: from pigeon.gentoo.org (localhost [127.0.0.1])
by pigeon.gentoo.org (Postfix) with SMTP id 52558E08EC;
Tue, 9 Jan 2018 01:50:02 +0000 (UTC)
Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183])
(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 22971E08EC
for <gentoo-commits@lists.gentoo.org>; Tue, 9 Jan 2018 01:50:02 +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 84564335CE2
for <gentoo-commits@lists.gentoo.org>; Mon, 8 Jan 2018 21:34:23 +0000 (UTC)
Received: from localhost.localdomain (localhost [IPv6:::1])
by oystercatcher.gentoo.org (Postfix) with ESMTP id 0F2CA186
for <gentoo-commits@lists.gentoo.org>; Mon, 8 Jan 2018 21:34:22 +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: <1515447183.92cfa0e543d380ab290d06e98e2fef1b283349fe.williamh@OpenRC>
Subject: [gentoo-commits] proj/openrc:master commit in: /
X-VCS-Repository: proj/openrc
X-VCS-Files: service-script-guide.md
X-VCS-Directories: /
X-VCS-Committer: williamh
X-VCS-Committer-Name: William Hubbs
X-VCS-Revision: 92cfa0e543d380ab290d06e98e2fef1b283349fe
X-VCS-Branch: master
Date: Mon, 8 Jan 2018 21:34:22 +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: ebd274df-6ccf-4e78-813f-fcfba775c3f0
X-Archives-Hash: 57b1e991814a2bad6dc82de76cb9fa60
commit: 92cfa0e543d380ab290d06e98e2fef1b283349fe
Author: William Hubbs <w.d.hubbs <AT> gmail <DOT> com>
AuthorDate: Mon Jan 8 21:33:03 2018 +0000
Commit: William Hubbs <williamh <AT> gentoo <DOT> org>
CommitDate: Mon Jan 8 21:33:03 2018 +0000
URL: https://gitweb.gentoo.org/proj/openrc.git/commit/?id=92cfa0e5
service-script-guide.md: formatting changes
Add a title, adjust the headings and update the example that referred to
"net.lo" to refer to "loopback".
service-script-guide.md | 28 +++++++++++++++-------------
1 file changed, 15 insertions(+), 13 deletions(-)
diff --git a/service-script-guide.md b/service-script-guide.md
index 5806b808..668d05d4 100644
--- a/service-script-guide.md
+++ b/service-script-guide.md
@@ -1,4 +1,6 @@
-This document is aimed at upstream and distribution developers who
+# OpenRC Service Script Writing Guide
+
+This document is aimed at developers or packagers who
write OpenRC service scripts, either for their own projects, or for
the packages they maintain. It contains advice, suggestions, tips,
tricks, hints, and counsel; cautions, warnings, heads-ups,
@@ -11,7 +13,7 @@ don't consider anything exotic, and assume that you will use
start-stop-daemon to manage a fairly typical long-running UNIX
process.
-# Don't write your own start/stop functions
+## Don't write your own start/stop functions
OpenRC is capable of stopping and starting most daemons based on the
information that you give it. For a well-behaved daemon that
@@ -113,7 +115,7 @@ To recap, in order of preference:
to disable the daemon's PID file (or, to write it straight into the
garbage), then do that, and use `command_background=true`.
-# Reloading your daemon's configuration
+## Reloading your daemon's configuration
Many daemons will reload their configuration files in response to a
signal. Suppose your daemon will reload its configuration in response
@@ -139,7 +141,7 @@ reload() {
}
```
-# Don't restart/reload with a broken config
+## Don't restart/reload with a broken config
Often, users will start a daemon, make some configuration change, and
then attempt to restart the daemon. If the recent configuration change
@@ -187,7 +189,7 @@ reload() {
}
```
-# PID files should be writable only by root
+## PID files should be writable only by root
PID files must be writable only by *root*, which means additionally
that they must live in a *root*-owned directory.
@@ -239,7 +241,7 @@ A decent example of this is the [Nagios core service
script](https://github.com/NagiosEnterprises/nagioscore/blob/master/openrc-init.in),
where the full path to the PID file is specified at build-time.
-# Don't let the user control the PID file location
+## Don't let the user control the PID file location
It's usually a mistake to let the end user control the PID file
location through a conf.d variable, for a few reasons:
@@ -267,7 +269,7 @@ pidfile="/run/${RC_SVCNAME}.pid"
guarantees that your PID file has a unique name.
-# Upstream your service scripts (for distribution developers)
+## Upstream your service scripts (for packagers)
The ideal place for an OpenRC service script is **upstream**. Much like
systemd services, a well-crafted OpenRC service script should be
@@ -292,7 +294,7 @@ service script in your own distribution's repository, then you have to
keep the command path and package synchronized yourself, and that's no
fun.
-# Be wary of "need net" dependencies
+## Be wary of "need net" dependencies
There are two things you need to know about "need net" dependencies:
@@ -310,7 +312,7 @@ interface. We'll consider the two most common users of "need net";
network clients who access some network resource, and network servers
who provide them.
-## Network clients
+### Network clients
Network clients typically want the WAN interface to be up. That may
tempt you to depend on the WAN interface; but first, you should ask
@@ -329,7 +331,7 @@ logged. The signature update service will not crash, and—perhaps more
importantly—you don't want it to terminate if the administrator turns
off the WAN interface for a second.
-## Network servers
+### Network servers
Network servers are generally easier to handle than their client
counterparts. Most server daemons listen on `0.0.0.0` (all addresses)
@@ -350,7 +352,7 @@ If your daemon can optionally be configured to listen on a particular
interface, then please see the "Depending on a particular interface"
section.
-## Depending on a particular interface
+### Depending on a particular interface
If you need to depend on one particular interface, usually it's not
easy to determine programmatically what that interface is. For
@@ -371,8 +373,8 @@ like the following in the service configuration file,
```sh
# Specify the network service that corresponds to the "bind" setting
# in your configuration file. For example, if you bind to 127.0.0.1,
-# this should be set to "net.lo" which provides the loopback interface.
-rc_need="net.lo"
+# this should be set to "loopback" which provides the loopback interface.
+rc_need="loopback"
```
This is a sensible default for daemons that are happy with `0.0.0.0`,