Source string Read only

(itstool) path: note/para
688/6880
Context English State
Usually a script specifies a single condition provided. However, nothing prevents us from listing several conditions there, e.g., for compatibility reasons.
In any case, the name of the main, or the only, <literal>PROVIDE:</literal> condition should be the same as <envar>${name}</envar>.
So our script indicates which <quote>conditions</quote> provided by other scripts it depends on. According to the lines, our script asks <citerefentry><refentrytitle>rcorder</refentrytitle><manvolnum>8</manvolnum></citerefentry> to put it after the script(s) providing <filename>DAEMON</filename> and <filename>cleanvar</filename>, but before that providing <filename>LOGIN</filename>.
The <literal>BEFORE:</literal> line should not be abused to work around an incomplete dependency list in the other script. The appropriate case for using <literal>BEFORE:</literal> 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 <quote>placeholder</quote> scripts used to ensure that certain groups of operations are performed before others. These are denoted by <filename><replaceable>UPPERCASE</replaceable></filename> names. Their list and purposes can be found in <citerefentry><refentrytitle>rc</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
Keep in mind that putting a service name in the <literal>REQUIRE:</literal> 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 <citerefentry><refentrytitle>rc.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Obviously, <citerefentry><refentrytitle>rcorder</refentrytitle><manvolnum>8</manvolnum></citerefentry> cannot track such details, and <citerefentry><refentrytitle>rc</refentrytitle><manvolnum>8</manvolnum></citerefentry> will not do that either. Consequently, the application started by our script should be able to cope with any required services being unavailable. In certain cases, we can help it as discussed <link linkend="forcedep">below.</link>
<anchor xml:id="keywords"/>As we remember from the above text, <citerefentry><refentrytitle>rcorder</refentrytitle><manvolnum>8</manvolnum></citerefentry> keywords can be used to select or leave out some scripts. Namely any <citerefentry><refentrytitle>rcorder</refentrytitle><manvolnum>8</manvolnum></citerefentry> consumer can specify through <option>-k</option> and <option>-s</option> options which keywords are on the <quote>keep list</quote> and <quote>skip list</quote>, respectively. From all the files to be dependency sorted, <citerefentry><refentrytitle>rcorder</refentrytitle><manvolnum>8</manvolnum></citerefentry> will pick only those having a keyword from the keep list (unless empty) and not having a keyword from the skip list.
In FreeBSD, <citerefentry><refentrytitle>rcorder</refentrytitle><manvolnum>8</manvolnum></citerefentry> is used by <filename>/etc/rc</filename> and <filename>/etc/rc.shutdown</filename>. These two scripts define the standard list of FreeBSD <filename>rc.d</filename> keywords and their meanings as follows:
<literal>nojail</literal>
The service is not for <citerefentry><refentrytitle>jail</refentrytitle><manvolnum>8</manvolnum></citerefentry> environment. The automatic startup and shutdown procedures will ignore the script if inside a jail.
<literal>nostart</literal>
The service is to be started manually or not started at all. The automatic startup procedure will ignore the script. In conjunction with the <literal>shutdown</literal> keyword, this can be used to write scripts that do something only at system shutdown.
<literal>shutdown</literal>
This keyword is to be listed <emphasis>explicitly</emphasis> if the service needs to be stopped before system shutdown.
When the system is going to shut down, <filename>/etc/rc.shutdown</filename> runs. It assumes that most <filename>rc.d</filename> scripts have nothing to do at that time. Therefore <filename>/etc/rc.shutdown</filename> selectively invokes <filename>rc.d</filename> scripts with the <literal>shutdown</literal> keyword, effectively ignoring the rest of the scripts. For even faster shutdown, <filename>/etc/rc.shutdown</filename> passes the <option>faststop</option> command to the scripts it runs so that they skip preliminary checks, e.g., the pidfile check. As dependent services should be stopped before their prerequisites, <filename>/etc/rc.shutdown</filename> runs the scripts in reverse dependency order.
If writing a real <filename>rc.d</filename> script, you should consider whether it is relevant at system shutdown time. E.g., if your script does its work in response to the <option>start</option> command only, then you need not include this keyword. However, if your script manages a service, it is probably a good idea to stop it before the system proceeds to the final stage of its shutdown sequence described in <citerefentry><refentrytitle>halt</refentrytitle><manvolnum>8</manvolnum></citerefentry>. In particular, a service should be stopped explicitly if it needs considerable time or special actions to shut down cleanly. A typical example of such a service is a database engine.
<anchor xml:id="forcedep"/>To begin with, <function>force_depend</function> should be used with much care. It is generally better to revise the hierarchy of configuration variables for your <filename>rc.d</filename> scripts if they are interdependent.
If you still cannot do without <function>force_depend</function>, the example offers an idiom of how to invoke it conditionally. In the example, our <command>mumbled</command> daemon requires that another one, <command>frotz</command>, be started in advance. However, <command>frotz</command> is optional, too; and <citerefentry><refentrytitle>rcorder</refentrytitle><manvolnum>8</manvolnum></citerefentry> knows nothing about such details. Fortunately, our script has access to all <citerefentry><refentrytitle>rc.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> variables. If <envar>frotz_enable</envar> is true, we hope for the best and rely on <filename>rc.d</filename> to have started <command>frotz</command>. Otherwise we forcibly check the status of <command>frotz</command>. Finally, we enforce our dependency on <command>frotz</command> if it is found to be not running. A warning message will be emitted by <function>force_depend</function> because it should be invoked only if a misconfiguration has been detected.
Giving more flexibility to an rc.d script
When invoked during startup or shutdown, an <filename>rc.d</filename> script is supposed to act on the entire subsystem it is responsible for. E.g., <filename>/etc/rc.d/netif</filename> should start or stop all network interfaces described by <citerefentry><refentrytitle>rc.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Either task can be uniquely indicated by a single command argument such as <option>start</option> or <option>stop</option>. Between startup and shutdown, <filename>rc.d</filename> scripts help the admin to control the running system, and it is when the need for more flexibility and precision arises. For instance, the admin may want to add the settings of a new network interface to <citerefentry><refentrytitle>rc.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> and then to start it without interfering with the operation of the existing interfaces. Next time the admin may need to shut down a single network interface. In the spirit of the command line, the respective <filename>rc.d</filename> script calls for an extra argument, the interface name.
Fortunately, <citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</manvolnum></citerefentry> allows for passing any number of arguments to script's methods (within the system limits). Due to that, the changes in the script itself can be minimal.
How can <citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</manvolnum></citerefentry> gain access to the extra command-line arguments. Should it just grab them directly? Not by any means. Firstly, an <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry> function has no access to the positional parameters of its caller, but <citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</manvolnum></citerefentry> is just a sack of such functions. Secondly, the good manner of <filename>rc.d</filename> dictates that it is for the main script to decide which arguments are to be passed to its methods.
So the approach adopted by <citerefentry><refentrytitle>rc.subr</refentrytitle><manvolnum>8</manvolnum></citerefentry> is as follows: <function>run_rc_command</function> passes on all its arguments but the first one to the respective method verbatim. The first, omitted, argument is the name of the method itself: <option>start</option>, <option>stop</option>, etc. It will be shifted out by <function>run_rc_command</function>, so what is <envar>$2</envar> in the original command line will be presented as <envar>$1</envar> to the method, and so on.
To illustrate this opportunity, let us modify the primitive dummy script so that its messages depend on the additional arguments supplied. Here we go:
#!/bin/sh

. /etc/rc.subr

name="dummy"
start_cmd="${name}_start"
stop_cmd=":"
kiss_cmd="${name}_kiss"
extra_commands="kiss"

dummy_start()
{
if [ $# -gt 0 ]; then<co xml:id="rcng-args-start"/>
echo "Greeting message: $*"
else
echo "Nothing started."
fi
}

dummy_kiss()
{
echo -n "A ghost gives you a kiss"
if [ $# -gt 0 ]; then<co xml:id="rcng-args-kiss"/>
echo -n " and whispers: $*"
fi
case "$*" in
*[.!?])
echo
;;
*)
echo .
;;
esac
}

load_rc_config $name
run_rc_command "$@"<co xml:id="rcng-args-all"/>
What essential changes can we notice in the script?
All arguments you type after <option>start</option> can end up as positional parameters to the respective method. We can use them in any way according to our task, skills, and fancy. In the current example, we just pass all of them to <citerefentry><refentrytitle>echo</refentrytitle><manvolnum>1</manvolnum></citerefentry> as one string in the next line — note <envar>$*</envar> within the double quotes. Here is how the script can be invoked now:
<prompt>#</prompt> <userinput>/etc/rc.d/dummy start</userinput>
Nothing started.
<prompt>#</prompt> <userinput>/etc/rc.d/dummy start Hello world!</userinput>
Greeting message: Hello world!
The same applies to any method our script provides, not only to a standard one. We have added a custom method named <option>kiss</option>, and it can take advantage of the extra arguments not less than <option>start</option> does. E.g.:
<prompt>#</prompt> <userinput>/etc/rc.d/dummy kiss</userinput>
A ghost gives you a kiss.
<prompt>#</prompt> <userinput>/etc/rc.d/dummy kiss Once I was Etaoin Shrdlu...</userinput>
A ghost gives you a kiss and whispers: Once I was Etaoin Shrdlu...
If we want just to pass all extra arguments to any method, we can merely substitute <literal>"$@"</literal> for <literal>"$1"</literal> in the last line of our script, where we invoke <function>run_rc_command</function>.

Loading…

No matching activity found.

Browse all component changes

Glossary

English English
No related strings found in the glossary.

Source information

Source string comment
(itstool) path: note/para
Flags
read-only
Source string location
article.translate.xml:1152
String age
a year ago
Source string age
a year ago
Translation file
articles/rc-scripting.pot, string 135