New article
Giorgos Keramidas
keramida at FreeBSD.org
Wed Oct 18 22:57:10 UTC 2006
On 2006-10-15 21:35, Yar Tikhiy <yar at comp.chem.msu.su> wrote:
> Hi folks,
>
> I wrote an article on our rc.d subsystem. Its draft in sgml and
> html is available at http://people.freebsd.org/~yar/rcng/ . It has
> been reviewed on freebsd-rc. Now I'd like to add it to our article
> collection. I see that I should commit the article itself, then
> update www/docs/books.sgml. What else?
>
> P.S. Please feel free to review my article WRT its markup. Thanks!
Hi Yar,
First of all, *THANKS*!
This is a great article, and I really enjoyed reading it. One of my
latest commits to doc/ was, in fact, inspired by this article:
# Date: Wed, 18 Oct 2006 20:47:50 +0000 (UTC)
# From: Giorgos Keramidas <keramida at FreeBSD.org>
# Subject: cvs commit: doc/en_US.ISO8859-1/books/handbook/network-servers chapter.sgml
# To: doc-committers at FreeBSD.org, cvs-doc at FreeBSD.org, cvs-all at FreeBSD.org
#
# keramida 2006-10-18 20:47:50 UTC
#
# FreeBSD doc repository
#
# Modified files:
# en_US.ISO8859-1/books/handbook/network-servers chapter.sgml
# Log:
# Suggest using `/etc/rc.d/mountd onereload' instead of `reload',
# to make sure that `mountd' is (re)loaded even if it's not yet
# enabled in `/etc/rc.conf'.
#
# Ideally, `mountd' should already be enabled in `rc.conf', but if
# `mountd_enable' is not set to "YES" in `rc.conf', then running
# the rc.d script with a plain `reload' argument does nothing.
# Using `onereload' (with the rc.d-specific `one' prefix) makes
# sure that `mountd' is temporarily enabled for the run of this
# rc.d script and it does indeed reload its config files.
#
# Suggested by: Volodymyr Kostyrko <arcade at synergetica.dn.ua>
# Mailing List: freebsd-doc
# Message-Id: <452C187F.5030403 at synergetica.dn.ua>
#
# Revision Changes Path
# 1.94 +1 -1 doc/en_US.ISO8859-1/books/handbook/network-servers/chapter.sgml
The idea for replacing "reload" with "onereload" came to me after
reading your article, so you are in part responsible for this fix too :)
Having said that, as I was going through the article, I noticed a few
places where I would probably word things in a slightly different way.
I am not sure if all my changes are ok, but the attached patch shows all
the changes I have made locally.
This is still a work-in-progress, as I am going a second time through
the article, looking for things which I would write in a different way,
or for things which seem cool to add. I'm not done, yet, but here is a
first patch version, so we can work in parallel ;)
If you like any of the changes, feel free to import them in your own
copy of the article. Please, also let em know if you need help while
committing this to doc/.
- Giorgos
-------------- next part --------------
diff -r 92966e501cfc en_US.ISO8859-1/articles/rcng/article.sgml
--- a/en_US.ISO8859-1/articles/rcng/article.sgml Wed Oct 18 22:52:52 2006 +0300
+++ b/en_US.ISO8859-1/articles/rcng/article.sgml Thu Oct 19 00:32:42 2006 +0300
@@ -53,7 +53,7 @@
<para>The historical BSD had a monolithic startup script,
<filename>/etc/rc</filename>. It was invoked by
&man.init.8; at system boot time and performed all userland
- tasks prerequisite to multi-user operation: checking and
+ tasks required for multi-user operation: checking and
mounting file systems, setting up the network, starting
daemons, and so on. The precise list of tasks was not the
same in every system; admins needed to customize it. With
@@ -250,15 +250,15 @@ run_rc_command "$1"<co id="rcng-dummy-ru
them. Theoretically, such scripts can be written in
any language understood by &man.rcorder.8;. However,
non-&man.sh.1; scripts for <filename>rc.d</filename>
- will be welcome neither in the base system nor in ports.
- If you still think you need such a script, most likely
- it should be installed to a different location, e.g.,
- <filename>/usr/local/sbin</filename> or
- <filename>/usr/local/libexec</filename> for a port.</para>
-
- <para>If the previous paragraph did not make sense to you,
- just remember a simple rule: <filename>rc.d</filename>
- scripts are written in &man.sh.1;, period.</para>
+ are not welcome, neither in the base system of &os; nor in the Ports Collection.
+ If you still think you need such a script for one of your ports,
+ it should be installed to a different location,
+ e.g., <filename>/usr/local/sbin</filename> or
+ <filename>/usr/local/libexec</filename>.</para>
+
+ <para>If the previous paragraph does not make sense to you,
+ just remember a simple rule: <emphasis><filename>rc.d</filename>
+ scripts are written in &man.sh.1;, period.</emphasis></para>
</note>
</callout>
@@ -533,26 +533,26 @@ run_rc_command "$1"</programlisting>
<para>The daemon will be started by running
<envar>$command</envar> with command-line flags specified
- by <envar>$mumbled_flags</envar>. I.e., all information
- needed by <option>start</option> is available in the
- variables. Unlike <option>start</option>, the other
- methods will require additional information on the process
- started, if any. In the present case, &man.rc.subr.8;
+ by <envar>$mumbled_flags</envar>. Thus, all the information
+ needed by the <option>start</option> action is available in the
+ variables set by the startup script. Unlike <option>start</option>, the other
+ methods (if any are enabled) will, usually, require additional information on the process
+ started. In the present case, &man.rc.subr.8;
will scan through the list of all processes, looking for
a process with its name equal to <envar>$procname</envar>.
The latter is another variable of meaning to &man.rc.subr.8;,
and its value defaults to that of <envar>command</envar>.
Thus by setting <envar>command</envar> we effectively set
- <envar>procname</envar> as well, and so we enable our
- script not only to start the daemon, but also to kill it
- and check if it still is running.</para>
-
- <note>
- <para>In case the program to start is an interpreted
+ <envar>procname</envar> as well. This means that our script
+ can not only start the daemon, but it can also kill the daemon
+ and check if it is still running.</para>
+
+ <note>
+ <para>When the program we have to start is an interpreted
script, &man.rc.subr.8; will fail to find its process
because its name is that of the interpreter. You should
set <envar>command_interpreter</envar> as well for
- &man.rc.subr.8; to know the actual name of the
+ &man.rc.subr.8; to let <filename>rc.d</filename> know the actual name of the
process.</para>
<para>For each <filename>rc.d</filename> script, there
@@ -568,7 +568,7 @@ run_rc_command "$1"</programlisting>
<para>It is possible to set <envar>${name}_program</envar>
even if the script does not specify <envar>command</envar>
- in the first place. The former variable loses its special
+ in the first place. The <envar>command</envar> variable loses its special
meaning then.</para>
</note>
@@ -582,7 +582,7 @@ run_rc_command "$1"</programlisting>
<title>Startup and shutdown of an advanced daemon</title>
<para>Let us add some meat onto the bones of the previous
- script and make it not so simple. The default methods can
+ script and make it slightly more complex (nad more featureful). The default methods can
do a good job for us, but we may need some of their aspects
tweaked. Now we will learn how to tune the default methods
to our needs.</para>
@@ -646,7 +646,7 @@ run_rc_command "$1"</programlisting>
<callout arearefs="rcng-daemon-adv-args">
<para>Additional arguments to <envar>$command</envar> can
be passed in <envar>command_args</envar>. These will
- appear the last on the command line, after
+ be passed as extra command-line arguments to the start command of our daemon, after
<envar>$mumbled_flags</envar>. Since the final command
line is passed to <command>eval</command> for its actual
execution, input and output redirections can be specified
@@ -656,18 +656,18 @@ run_rc_command "$1"</programlisting>
<para>It would be a poor idea to include flags in
<envar>command_args</envar> because most commands cannot
accept flags intermixed with ordinary arguments. A
- better way of passing additional flags is to prepend
+ better way of passing additional flags is to add
them to <envar>mumbled_flags</envar>.</para>
</note>
</callout>
<callout arearefs="rcng-daemon-adv-pid">
- <para>A good-mannered daemon should create a pidfile so
+ <para>A good-mannered daemon should create a <emphasis>pidfile</emphasis>, so
that its process can be found more easily and reliably.
The variable <envar>pidfile</envar>, if set, tells
- &man.rc.subr.8; where it can find the pidfile for its
- default methods such as <option>stop</option> or
- <option>status</option> to take advantage of.</para>
+ &man.rc.subr.8; where it can find the pidfile which the
+ default methods, such as <option>stop</option> or
+ <option>status</option> can use.</para>
<note>
<para>In fact, &man.rc.subr.8; will also use the pidfile
@@ -680,7 +680,7 @@ run_rc_command "$1"</programlisting>
<callout arearefs="rcng-daemon-adv-reqfiles">
<para>If the daemon cannot run unless certain files exist,
just list them in <envar>required_files</envar>, and
- &man.rc.subr.8; will check for the prerequisite before
+ &man.rc.subr.8; will check that these required files exist before
starting the daemon. There also are <envar>required_dirs</envar>
and <envar>required_vars</envar> for directories and
environment variables, respectively. They all are described
@@ -708,20 +708,21 @@ run_rc_command "$1"</programlisting>
<para>The signal names should be specified to &man.rc.subr.8;
without the <literal>SIG</literal> prefix, as it is
shown in the example. The &os; version of &man.kill.1;
- can recognize the prefix, but the versions from other OS
+ can recognize the <literal>SIG</literal> prefix, but the versions from other OS
types may not.</para>
</note>
</callout>
<callout arearefs="rcng-daemon-adv-precmd rcng-daemon-adv-postcmd">
- <para>Should we want to perform additional complex actions,
- we still do not need to override the default methods.
- For each argument that our <filename>rc.d</filename>
+ <para>Performing additional complex tasks before or after one of the
+ actions supported by our script without overriding the default
+ methods, is also possible.
+ For each action-argument that our <filename>rc.d</filename>
script is prepared to take, we can define
<envar><replaceable>argument</replaceable>_precmd</envar> and
<envar><replaceable>argument</replaceable>_postcmd</envar>.
These &man.sh.1; commands are invoked before and after
- the method, respectively.</para>
+ the respective method, respectively.</para>
<note>
<para>Overriding a default method with a custom
@@ -734,7 +735,7 @@ run_rc_command "$1"</programlisting>
be met before performing the command itself. Using
<envar><replaceable>argument</replaceable>_precmd</envar> along
with <envar><replaceable>argument</replaceable>_cmd</envar>
- allows to logically separate the checks from the
+ lets us logically separate the checks from the
action.</para>
<para>Do not forget that you can cram any valid &man.sh.1;
@@ -765,8 +766,8 @@ run_rc_command "$1"</programlisting>
<para>What do we get from the default method for
<option>reload</option>? Quite often daemons reload
- their configuration upon reception of a signal, mostly
- <symbol>SIGHUP</symbol>. Therefore &man.rc.subr.8;
+ their configuration upon reception of a signal—typically,
+ the <symbol>SIGHUP</symbol> signal. Therefore &man.rc.subr.8;
attempts to reload the daemon by sending a signal to
it. The signal is preset to <symbol>SIGHUP</symbol>
but can be customized via <envar>sig_reload</envar> if
@@ -790,8 +791,8 @@ run_rc_command "$1"</programlisting>
<para>The full list of available commands for a particular
script can be found in the usage line printed by
- &man.rc.subr.8; if no command given — or in the
- script itself.
+ &man.rc.subr.8; if no action-argument is passed to the script
+ — or by reading the source of the script itself.
For example, here is the usage line from the script under
study:</para>
@@ -828,6 +829,27 @@ Usage: /etc/rc.d/mumbled [fast|force|one
<note>
<para>Keep in mind that for &man.sh.1; a zero exit code
means true and a non-zero exit code means false.</para>
+ </note>
+
+ <note>
+ <para>The <function>checkyesno</function> function takes an
+ unquoted, literal <emphasis>variable name</emphasis>. Do not pass
+ the expanded <emphasis>value</emphasis> of a variable to it; it
+ will not work as expected.</para>
+
+ <para>Thus, the following is correct <function>checkyesno</function>
+ usage:</para>
+
+ <programlisting>if checkyesno mumbled_enable ; then
+ foo
+fi</programlisting>
+
+ <para>but calling <function>checkyesno</function> as shown below
+ will not work (at least not as expected):</para>
+
+ <programlisting>if checkyesno "${mumbled_enable}" ; then
+ foo
+fi</programlisting>
</note>
</callout>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20061019/1cbe5e31/attachment.sig>
More information about the freebsd-doc
mailing list