Skip to content

Commit

Permalink
rc-scripting: Strip whitespace and fix typos
Browse files Browse the repository at this point in the history
Fixes:	e9bc86f rc scripting article: file naming convention and "instancing"
  • Loading branch information
0mp committed Jul 16, 2024
1 parent 42e5985 commit 3122fb5
Showing 1 changed file with 16 additions and 16 deletions.
32 changes: 16 additions & 16 deletions documentation/content/en/articles/rc-scripting/_index.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ With few exceptions, [.filename]#/etc/rc# had to be modified, and true hackers l
The real problem with the monolithic approach was that it provided no control over the individual components started from [.filename]#/etc/rc#.
For instance, [.filename]#/etc/rc# could not restart a single daemon.
The system admin had to find the daemon process by hand, kill it, wait until it actually exited, then browse through [.filename]#/etc/rc# for the flags, and finally type the full command line to start the daemon again.
The task would become even more difficult and prone to errors if the service to restart consisted of more than one daemon or demanded additional actions.
The task would become even more difficult and prone to errors if the service to restart consisted of more than one daemon or demanded additional actions.
In a few words, the single script failed to fulfil what scripts are for: to make the system admin's life easier.

Later there was an attempt to split out some parts of [.filename]#/etc/rc# for the sake of starting the most important subsystems separately.
Expand All @@ -84,7 +84,7 @@ The basic ideas behind BSD [.filename]#rc.d# are _fine modularity_ and __code re
_Fine modularity_ means that each basic "service" such as a system daemon or primitive startup task gets its own man:sh[1] script able to start the service, stop it, reload it, check its status.
A particular action is chosen by the command-line argument to the script.
The [.filename]#/etc/rc# script still drives system startup, but now it merely invokes the smaller scripts one by one with the `start` argument.
It is easy to perform shutdown tasks as well by running the same set of scripts with the `stop` argument, which is done by [.filename]#/etc/rc.shutdown#.
It is easy to perform shutdown tasks as well by running the same set of scripts with the `stop` argument, which is done by [.filename]#/etc/rc.shutdown#.
Note how closely this follows the Unix way of having a set of small specialized tools, each fulfilling its task as well as possible.
_Code reuse_ means that common operations are implemented as man:sh[1] functions and collected in [.filename]#/etc/rc.subr#.
Now a typical script can be just a few lines' worth of man:sh[1] code.
Expand Down Expand Up @@ -186,8 +186,8 @@ That is, each [.filename]#rc.d# script _must_ set `name` before it calls man:rc.
Now it is the right time to choose a unique name for our script once and for all.
We will use it in a number of places while developing the script.
The content of the name variable needs to match the script name,
some parts of FreeBSD (e.g. <<rcng-service-jails, service jails>> and the cpuset feature of the rc framework) depend upon this.
As such the filename shall also not contain characters which may be troublesome in scripting (e.g. do not use a hyphen "-" and others).
some parts of FreeBSD (e.g., <<rcng-service-jails, service jails>> and the cpuset feature of the rc framework) depend upon this.
As such the filename shall also not contain characters which may be troublesome in scripting (e.g., do not use a hyphen "-" and others).

[NOTE]
====
Expand Down Expand Up @@ -506,7 +506,7 @@ The reason is that not all daemons use the same reload mechanism and some have n
So we need to ask explicitly that the builtin functionality be provided.
We can do so via `extra_commands`.
What do we get from the default method for `reload`? Quite often daemons reload their configuration upon reception of a signal - typically, SIGHUP.
What do we get from the default method for `reload`? Quite often daemons reload their configuration upon reception of a signal - typically, SIGHUP.
Therefore man:rc.subr[8] attempts to reload the daemon by sending a signal to it.
The signal is preset to SIGHUP but can be customized via `sig_reload` if necessary.
====
Expand Down Expand Up @@ -666,14 +666,14 @@ According to the lines, our script asks man:rcorder[8] to put it after the scrip
[NOTE]
====
The `BEFORE:` line should not be abused to work around an incomplete dependency list in the other script.
The appropriate case for using `BEFORE:` is when the other script does not care about ours, but our script can do its task better if run before the other one.
The appropriate case for using `BEFORE:` is when the other script does not care about ours, but our script can do its task better if run before the other one.
A typical real-life example is the network interfaces vs. the firewall: While the interfaces do not depend on the firewall in doing their job, the system security will benefit from the firewall being ready before there is any network traffic.
Besides conditions corresponding to a single service each, there are meta-conditions and their "placeholder" scripts used to ensure that certain groups of operations are performed before others.
These are denoted by [.filename]#UPPERCASE# names.
Their list and purposes can be found in man:rc[8].
Keep in mind that putting a service name in the `REQUIRE:` line does not guarantee that the service will actually be running by the time our script starts.
Keep in mind that putting a service name in the `REQUIRE:` line does not guarantee that the service will actually be running by the time our script starts.
The required service may fail to start or just be disabled in man:rc.conf[5].
Obviously, man:rcorder[8] cannot track such details, and man:rc[8] will not do that either.
Consequently, the application started by our script should be able to cope with any required services being unavailable.
Expand Down Expand Up @@ -882,15 +882,15 @@ As such it is highly recommended to add such an empty config in such a case.
The most common option to use is "net_basic", which enables the use of the hosts IPv4 and IPv6 addresses.
All possible options are explained in man:rc.conf[5].

If a setting for the start/stop depends on variables from the rc-framework (e.g. set inside man:rc.conf[5]), this needs to be handled by ``load_rc_config`` and ``run_rc_command`` instead of inside a precommand.
If a setting for the start/stop depends on variables from the rc-framework (e.g., set inside man:rc.conf[5]), this needs to be handled by ``load_rc_config`` and ``run_rc_command`` instead of inside a precommand.

If for some reason a script can not be run within a service jail, e.g. because it is not possible to run or it does not make sense to run it in a jail, use the following:
If for some reason a script can not be run within a service jail, e.g., because it is not possible to run or it does not make sense to run it in a jail, use the following:

[.programlisting]
....
....
#!/bin/sh
. /etc/rc.subr
. /etc/rc.subr
name="dummy"
start_cmd="${name}_start"
Expand All @@ -912,7 +912,7 @@ run_rc_command "$1"
== Advanced rc-scripting: Instancing

Sometimes it is useful to run several instances of a service.
Typically you want ot be able to start/stop such instances independently,
Typically you want to be able to start/stop such instances independently,
and you want to have a separate config file for each instance.
Each instance should be started at boot,
survive updates,
Expand Down Expand Up @@ -950,14 +950,14 @@ case $0 in <.>
name=$0
;;
esac
name=${name##*/} <.>
rcvar="${name}_enable" <.>
desc="Short description of this service"
command="/usr/local/sbin/dummy"
load_rc_config "$name"
eval "${rcvar}=\${${rcvar}:-'NO'}" <.>
eval "${name}_svcj_options=\${${name}_svcj_options:-'net_basic'}" <.>
eval "_dummy_user=\${${name}_user:-'www'}" <.>
Expand Down Expand Up @@ -989,7 +989,7 @@ The part in &#10126; is for variables which are not used inside the script itsel
All the variables which are used as parameters somewhere in the script are assigned to a generic variable like in &#10128; to make it more easy to reference them (no need to eval them at each place of use).

This script will now behave differently if the start script has a different name.
This allows to creaty symlinks to it:
This allows to create symlinks to it:

[source,shell]
....
Expand All @@ -1002,7 +1002,7 @@ The above creates an instance of the dummy service with the name dummy_foo.
It does not use the config file [.filename]#/usr/local/etc/dummy.cfg# but the config file [.filename]#/usr/local/etc/dummy_foo.cfg# (&#10128;),
and it uses the PID file [.filename]#/var/run/dummy/dummy_foo.pid# instead of [.filename]#/var/run/dummy/dummy.pid#.

The services dummy and dummy_foo can be managend indepently of each other,
The services dummy and dummy_foo can be managed independently of each other,
while having the start script update itself on package update (due to the symlink).
This does not update the REQUIRE line,
as such there is no easy way of depending on a specific instance.
Expand Down

0 comments on commit 3122fb5

Please sign in to comment.