1 |
commit: 92cfa0e543d380ab290d06e98e2fef1b283349fe |
2 |
Author: William Hubbs <w.d.hubbs <AT> gmail <DOT> com> |
3 |
AuthorDate: Mon Jan 8 21:33:03 2018 +0000 |
4 |
Commit: William Hubbs <williamh <AT> gentoo <DOT> org> |
5 |
CommitDate: Mon Jan 8 21:33:03 2018 +0000 |
6 |
URL: https://gitweb.gentoo.org/proj/openrc.git/commit/?id=92cfa0e5 |
7 |
|
8 |
service-script-guide.md: formatting changes |
9 |
|
10 |
Add a title, adjust the headings and update the example that referred to |
11 |
"net.lo" to refer to "loopback". |
12 |
|
13 |
service-script-guide.md | 28 +++++++++++++++------------- |
14 |
1 file changed, 15 insertions(+), 13 deletions(-) |
15 |
|
16 |
diff --git a/service-script-guide.md b/service-script-guide.md |
17 |
index 5806b808..668d05d4 100644 |
18 |
--- a/service-script-guide.md |
19 |
+++ b/service-script-guide.md |
20 |
@@ -1,4 +1,6 @@ |
21 |
-This document is aimed at upstream and distribution developers who |
22 |
+# OpenRC Service Script Writing Guide |
23 |
+ |
24 |
+This document is aimed at developers or packagers who |
25 |
write OpenRC service scripts, either for their own projects, or for |
26 |
the packages they maintain. It contains advice, suggestions, tips, |
27 |
tricks, hints, and counsel; cautions, warnings, heads-ups, |
28 |
@@ -11,7 +13,7 @@ don't consider anything exotic, and assume that you will use |
29 |
start-stop-daemon to manage a fairly typical long-running UNIX |
30 |
process. |
31 |
|
32 |
-# Don't write your own start/stop functions |
33 |
+## Don't write your own start/stop functions |
34 |
|
35 |
OpenRC is capable of stopping and starting most daemons based on the |
36 |
information that you give it. For a well-behaved daemon that |
37 |
@@ -113,7 +115,7 @@ To recap, in order of preference: |
38 |
to disable the daemon's PID file (or, to write it straight into the |
39 |
garbage), then do that, and use `command_background=true`. |
40 |
|
41 |
-# Reloading your daemon's configuration |
42 |
+## Reloading your daemon's configuration |
43 |
|
44 |
Many daemons will reload their configuration files in response to a |
45 |
signal. Suppose your daemon will reload its configuration in response |
46 |
@@ -139,7 +141,7 @@ reload() { |
47 |
} |
48 |
``` |
49 |
|
50 |
-# Don't restart/reload with a broken config |
51 |
+## Don't restart/reload with a broken config |
52 |
|
53 |
Often, users will start a daemon, make some configuration change, and |
54 |
then attempt to restart the daemon. If the recent configuration change |
55 |
@@ -187,7 +189,7 @@ reload() { |
56 |
} |
57 |
``` |
58 |
|
59 |
-# PID files should be writable only by root |
60 |
+## PID files should be writable only by root |
61 |
|
62 |
PID files must be writable only by *root*, which means additionally |
63 |
that they must live in a *root*-owned directory. |
64 |
@@ -239,7 +241,7 @@ A decent example of this is the [Nagios core service |
65 |
script](https://github.com/NagiosEnterprises/nagioscore/blob/master/openrc-init.in), |
66 |
where the full path to the PID file is specified at build-time. |
67 |
|
68 |
-# Don't let the user control the PID file location |
69 |
+## Don't let the user control the PID file location |
70 |
|
71 |
It's usually a mistake to let the end user control the PID file |
72 |
location through a conf.d variable, for a few reasons: |
73 |
@@ -267,7 +269,7 @@ pidfile="/run/${RC_SVCNAME}.pid" |
74 |
|
75 |
guarantees that your PID file has a unique name. |
76 |
|
77 |
-# Upstream your service scripts (for distribution developers) |
78 |
+## Upstream your service scripts (for packagers) |
79 |
|
80 |
The ideal place for an OpenRC service script is **upstream**. Much like |
81 |
systemd services, a well-crafted OpenRC service script should be |
82 |
@@ -292,7 +294,7 @@ service script in your own distribution's repository, then you have to |
83 |
keep the command path and package synchronized yourself, and that's no |
84 |
fun. |
85 |
|
86 |
-# Be wary of "need net" dependencies |
87 |
+## Be wary of "need net" dependencies |
88 |
|
89 |
There are two things you need to know about "need net" dependencies: |
90 |
|
91 |
@@ -310,7 +312,7 @@ interface. We'll consider the two most common users of "need net"; |
92 |
network clients who access some network resource, and network servers |
93 |
who provide them. |
94 |
|
95 |
-## Network clients |
96 |
+### Network clients |
97 |
|
98 |
Network clients typically want the WAN interface to be up. That may |
99 |
tempt you to depend on the WAN interface; but first, you should ask |
100 |
@@ -329,7 +331,7 @@ logged. The signature update service will not crash, and—perhaps more |
101 |
importantly—you don't want it to terminate if the administrator turns |
102 |
off the WAN interface for a second. |
103 |
|
104 |
-## Network servers |
105 |
+### Network servers |
106 |
|
107 |
Network servers are generally easier to handle than their client |
108 |
counterparts. Most server daemons listen on `0.0.0.0` (all addresses) |
109 |
@@ -350,7 +352,7 @@ If your daemon can optionally be configured to listen on a particular |
110 |
interface, then please see the "Depending on a particular interface" |
111 |
section. |
112 |
|
113 |
-## Depending on a particular interface |
114 |
+### Depending on a particular interface |
115 |
|
116 |
If you need to depend on one particular interface, usually it's not |
117 |
easy to determine programmatically what that interface is. For |
118 |
@@ -371,8 +373,8 @@ like the following in the service configuration file, |
119 |
```sh |
120 |
# Specify the network service that corresponds to the "bind" setting |
121 |
# in your configuration file. For example, if you bind to 127.0.0.1, |
122 |
-# this should be set to "net.lo" which provides the loopback interface. |
123 |
-rc_need="net.lo" |
124 |
+# this should be set to "loopback" which provides the loopback interface. |
125 |
+rc_need="loopback" |
126 |
``` |
127 |
|
128 |
This is a sensible default for daemons that are happy with `0.0.0.0`, |