#, fuzzy msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" "POT-Creation-Date: 2018-12-08 14:45-0200\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #. Put one translator per line, in the form NAME , YEAR1, YEAR2 msgctxt "_" msgid "translator-credits" msgstr "" #. (itstool) path: info/title #: article.translate.xml:4 msgid "Practical rc.d scripting in BSD" msgstr "" #. (itstool) path: affiliation/address #: article.translate.xml:8 #, no-wrap msgid "yar@FreeBSD.org" msgstr "" #. (itstool) path: info/author #: article.translate.xml:7 msgid "" "YarTikhiy <_:address-1/> " msgstr "" #. (itstool) path: info/copyright #: article.translate.xml:11 msgid "" "2005 2006 2012 The FreeBSD " "Project" msgstr "" #. (itstool) path: legalnotice/para #: article.translate.xml:20 msgid "FreeBSD is a registered trademark of the FreeBSD Foundation." msgstr "" #. (itstool) path: legalnotice/para #: article.translate.xml:22 msgid "NetBSD is a registered trademark of the NetBSD Foundation." msgstr "" #. (itstool) path: legalnotice/para #: article.translate.xml:24 msgid "" "Many of the designations used by manufacturers and sellers to distinguish " "their products are claimed as trademarks. Where those designations appear in " "this document, and the FreeBSD Project was aware of the trademark claim, the " "designations have been followed by the or the ® symbol." msgstr "" #. (itstool) path: info/pubdate #. (itstool) path: info/releaseinfo #: article.translate.xml:32 article.translate.xml:34 msgid "" "$FreeBSD: head/en_US.ISO8859-1/articles/rc-scripting/article.xml 44709 2014-" "04-29 21:39:27Z wblock $" msgstr "" #. (itstool) path: abstract/para #: article.translate.xml:37 msgid "" "Beginners may find it difficult to relate the facts from the formal " "documentation on the BSD rc.d framework with the " "practical tasks of rc.d scripting. In this article, we " "consider a few typical cases of increasing complexity, show rc.d features suited for each case, and discuss how they work. Such an " "examination should provide reference points for further study of the design " "and efficient application of rc.d." msgstr "" #. (itstool) path: sect1/title #: article.translate.xml:50 msgid "Introduction" msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:52 msgid "" "The historical BSD had a monolithic startup script, /etc/rc. It was invoked by init8 at system boot time " "and performed all userland 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 few exceptions, /etc/rc " "had to be modified, and true hackers liked it." msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:62 msgid "" "The real problem with the monolithic approach was that it provided no " "control over the individual components started from /etc/rc. For instance, /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 /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. In a few words, the single script failed to fulfil what " "scripts are for: to make the system admin's life easier." msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:76 msgid "" "Later there was an attempt to split out some parts of /etc/rc for the sake of starting the most important subsystems separately. " "The notorious example was /etc/netstart to bring up " "networking. It did allow for accessing the network from single-user mode, " "but it did not integrate well into the automatic startup process because " "parts of its code needed to interleave with actions essentially unrelated to " "networking. That was why /etc/netstart mutated into " "/etc/rc.network. The latter was no longer an ordinary " "script; it comprised of large, tangled sh1 functions called from " "/etc/rc at different stages of system startup. However, " "as the startup tasks grew diverse and sophisticated, the quasi-" "modular approach became even more of a drag than the monolithic " "/etc/rc had been." msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:94 msgid "" "Without a clean and well-designed framework, the startup scripts had to bend " "over backwards to satisfy the needs of rapidly developing BSD-based " "operating systems. It became obvious at last that more steps are necessary " "on the way to a fine-grained and extensible rc system. " "Thus BSD rc.d was born. Its acknowledged fathers were " "Luke Mewburn and the NetBSD community. Later it was imported into FreeBSD. " "Its name refers to the location of system scripts for individual services, " "which is in /etc/rc.d. Soon we will learn about more " "components of the rc.d system and see how the " "individual scripts are invoked." msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:107 msgid "" "The basic ideas behind BSD rc.d are fine " "modularity and code reuse. Fine " "modularity means that each basic service such as a " "system daemon or primitive startup task gets its own " "sh1 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 /etc/rc script still drives system " "startup, but now it merely invokes the smaller scripts one by one with the " " argument. It is easy to perform shutdown tasks as " "well by running the same set of scripts with the " "argument, which is done by /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 " "sh1 functions and collected in /etc/rc.subr. " "Now a typical script can be just a few lines' worth of " "sh1 code. Finally, an important part of the rc.d framework is rcorder8, which helps " "/etc/rc to run the small scripts orderly with respect " "to dependencies between them. It can help /etc/rc.shutdown, too, because the proper order for the shutdown sequence is " "opposite to that of startup." msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:133 msgid "" "The BSD rc.d design is described in the original article by Luke Mewburn, and the rc." "d components are documented in great detail in the respective manual pages. However, it might not " "appear obvious to an rc.d newbie how to tie the " "numerous bits and pieces together in order to create a well-styled script " "for a particular task. Therefore this article will try a different approach " "to describe rc.d. It will show which features should be " "used in a number of typical cases, and why. Note that this is not a how-to " "document because our aim is not at giving ready-made recipes, but at showing " "a few easy entrances into the rc.d realm. Neither is " "this article a replacement for the relevant manual pages. Do not hesitate to " "refer to them for more formal and complete documentation while reading this " "article." msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:151 msgid "" "There are prerequisites to understanding this article. First of all, you " "should be familiar with the sh1 scripting language in " "order to master rc.d. In addition, you should know how " "the system performs userland startup and shutdown tasks, which is described " "in rc8." msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:158 msgid "" "This article focuses on the FreeBSD branch of rc.d. " "Nevertheless, it may be useful to NetBSD developers, too, because the two " "branches of BSD rc.d not only share the same design but " "also stay similar in their aspects visible to script authors." msgstr "" #. (itstool) path: sect1/title #: article.translate.xml:167 msgid "Outlining the task" msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:169 msgid "" "A little consideration before starting $EDITOR will not hurt. " "In order to write a well-tempered rc.d script for a " "system service, we should be able to answer the following questions first:" msgstr "" #. (itstool) path: listitem/para #: article.translate.xml:177 msgid "Is the service mandatory or optional?" msgstr "" #. (itstool) path: listitem/para #: article.translate.xml:181 msgid "" "Will the script serve a single program, e.g., a daemon, or perform more " "complex actions?" msgstr "" #. (itstool) path: listitem/para #: article.translate.xml:186 msgid "Which other services will our service depend on, and vice versa?" msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:191 msgid "" "From the examples that follow we will see why it is important to know the " "answers to these questions." msgstr "" #. (itstool) path: sect1/title #: article.translate.xml:196 msgid "A dummy script" msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:198 msgid "" "The following script just emits a message each time the system boots up:" msgstr "" #. (itstool) path: informalexample/programlisting #: article.translate.xml:202 #, no-wrap msgid "" "#!/bin/sh\n" "\n" ". /etc/rc.subr\n" "\n" "name=\"dummy\"\n" "start_cmd=\"${name}_start\"\n" "stop_cmd=\":\"\n" "\n" "dummy_start()\n" "{\n" " echo \"Nothing started.\"\n" "}\n" "\n" "load_rc_config $name\n" "run_rc_command \"$1\"" msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:219 msgid "Things to note are:" msgstr "" #. (itstool) path: callout/para #: article.translate.xml:223 msgid "" "An interpreted script should begin with the magic shebang " "line. That line specifies the interpreter program for the script. Due to the " "shebang line, the script can be invoked exactly like a binary program " "provided that it has the execute bit set. (See " "chmod1.) For example, a system admin can run our script manually, " "from the command line:" msgstr "" #. (itstool) path: callout/screen #: article.translate.xml:232 #, no-wrap msgid "# /etc/rc.d/dummy start" msgstr "" #. (itstool) path: note/para #: article.translate.xml:235 msgid "" "In order to be properly managed by the rc.d framework, " "its scripts need to be written in the sh1 language. If you have " "a service or port that uses a binary control utility or a startup routine " "written in another language, install that element in /usr/sbin (for the system) or /usr/local/sbin (for " "ports) and call it from a sh1 script in the " "appropriate rc.d directory." msgstr "" #. (itstool) path: tip/para #: article.translate.xml:247 msgid "" "If you would like to learn the details of why rc.d " "scripts must be written in the sh1 language, see how " "/etc/rc invokes them by means of " "run_rc_script, then study the implementation of " "run_rc_script in /etc/rc.subr." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:258 msgid "" "In /etc/rc.subr, a number of " "sh1 functions are defined for an rc.d script " "to use. The functions are documented in rc." "subr8. While it is " "theoretically possible to write an rc.d script without " "ever using rc.subr8, its functions prove extremely handy and make the " "job an order of magnitude easier. So it is no surprise that everybody " "resorts to rc.subr8 in rc.d scripts. We are not " "going to be an exception." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:269 msgid "" "An rc.d script must source /" "etc/rc.subr (include it using .) before it calls rc." "subr8 functions so " "that sh1 has an opportunity to learn the functions. The " "preferred style is to source /etc/rc.subr first of all." msgstr "" #. (itstool) path: note/para #: article.translate.xml:278 msgid "" "Some useful functions related to networking are provided by another include " "file, /etc/network.subr." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:285 msgid "" "The mandatory variable name " "specifies the name of our script. It is required by " "rc.subr8. That is, each rc.d script " "must set name before it calls " "rc.subr8 functions." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:292 msgid "" "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. For a " "start, let us give the same name to the script file, too." msgstr "" #. (itstool) path: note/para #: article.translate.xml:298 msgid "" "The current style of rc.d scripting is to enclose " "values assigned to variables in double quotes. Keep in mind that it is just " "a style issue that may not always be applicable. You can safely omit quotes " "from around simple words without sh1 metacharacters in " "them, while in certain cases you will need single quotes to prevent any " "interpretation of the value by sh1. A programmer should " "be able to tell the language syntax from style conventions and use both of " "them wisely." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:312 msgid "" "The main idea behind rc.subr8 is that an " "rc.d script provides handlers, or methods, for " "rc.subr8 to invoke. In particular, , " ", and other arguments to an rc.d " "script are handled this way. A method is a sh1 expression stored in a " "variable named argument_cmd, where " "argument corresponds to what can be specified on " "the script's command line. We will see later how " "rc.subr8 provides default methods for the standard " "arguments." msgstr "" #. (itstool) path: note/para #: article.translate.xml:326 msgid "" "To make the code in rc.d more uniform, it is common to " "use ${name} wherever appropriate. Thus a number of lines can " "be just copied from one script to another." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:334 msgid "" "We should keep in mind that rc.subr8 provides default " "methods for the standard arguments. Consequently, we must override a " "standard method with a no-op sh1 expression if we want " "it to do nothing." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:341 msgid "" "The body of a sophisticated method can be implemented as a function. It is a " "good idea to make the function name meaningful." msgstr "" #. (itstool) path: important/para #: article.translate.xml:346 msgid "" "It is strongly recommended to add the prefix ${name} to the " "names of all functions defined in our script so they never clash with the " "functions from rc.subr8 or another common " "include file." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:355 msgid "" "This call to rc.subr8 loads " "rc.conf5 variables. Our script makes no use of them yet, " "but it still is recommended to load rc.conf5 because there can be " "rc.conf5 variables controlling " "rc.subr8 itself." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:363 msgid "" "Usually this is the last command in an rc.d script. It " "invokes the rc.subr8 machinery to perform " "the requested action using the variables and methods our script has provided." "" msgstr "" #. (itstool) path: sect1/title #: article.translate.xml:372 msgid "A configurable dummy script" msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:374 msgid "" "Now let us add some controls to our dummy script. As you may know, " "rc.d scripts are controlled with " "rc.conf5. Fortunately, rc." "subr8 hides all the " "complications from us. The following script uses " "rc.conf5 via rc.subr8 to see whether it is " "enabled in the first place, and to fetch a message to show at boot time. " "These two tasks in fact are independent. On the one hand, an rc.d script can just support enabling and disabling its service. On the " "other hand, a mandatory rc.d script can have " "configuration variables. We will do both things in the same script though:" msgstr "" #. (itstool) path: informalexample/programlisting #: article.translate.xml:388 #, no-wrap msgid "" "#!/bin/sh\n" "\n" ". /etc/rc.subr\n" "\n" "name=dummy\n" "rcvar=dummy_enable\n" "\n" "start_cmd=\"${name}_start\"\n" "stop_cmd=\":\"\n" "\n" "load_rc_config $name\n" ": ${dummy_enable:=no} \n" ": ${dummy_msg=\"Nothing started.\"}\n" "\n" "dummy_start()\n" "{\n" " echo \"$dummy_msg\"\n" "}\n" "\n" "run_rc_command \"$1\"" msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:410 msgid "What changed in this example?" msgstr "" #. (itstool) path: callout/para #: article.translate.xml:414 msgid "" "The variable rcvar specifies the name of the ON/OFF knob " "variable." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:419 msgid "" "Now load_rc_config is invoked earlier in the script, " "before any rc.conf5 variables are accessed." msgstr "" #. (itstool) path: note/para #: article.translate.xml:424 msgid "" "While examining rc.d scripts, keep in mind that " "sh1 defers the evaluation of expressions in a function until the " "latter is called. Therefore it is not an error to invoke " "load_rc_config as late as just before " "run_rc_command and still access " "rc.conf5 variables from the method functions exported to " "run_rc_command. This is because the method functions " "are to be called by run_rc_command, which is invoked " "after load_rc_config." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:440 msgid "" "A warning will be emitted by run_rc_command if " "rcvar itself is set, but the indicated knob variable is unset." " If your rc.d script is for the base system, you should " "add a default setting for the knob to /etc/defaults/rc.conf and document it in rc.conf5. Otherwise it is your " "script that should provide a default setting for the knob. The canonical " "approach to the latter case is shown in the example." msgstr "" #. (itstool) path: note/para #: article.translate.xml:451 msgid "" "You can make rc.subr8 act as though the knob " "is set to ON, irrespective of its current setting, by " "prefixing the argument to the script with one or " "force, as in or " ". Keep in mind though that force has other dangerous effects we will touch upon below, while " "one just overrides the ON/OFF knob. E.g., assume that " "dummy_enable is OFF. The following command " "will run the method in spite of the setting:" msgstr "" #. (itstool) path: note/screen #: article.translate.xml:464 #, no-wrap msgid "# /etc/rc.d/dummy onestart" msgstr "" #. (itstool) path: callout/para #: article.translate.xml:469 msgid "" "Now the message to be shown at boot time is no longer hard-coded in the " "script. It is specified by an rc.conf5 variable named " "dummy_msg. This is a trivial example of how " "rc.conf5 variables can control an rc.d " "script." msgstr "" #. (itstool) path: important/para #: article.translate.xml:476 msgid "" "The names of all rc.conf5 variables used " "exclusively by our script must have the same prefix: " "${name}_. For example: dummy_mode, " "dummy_state_file, and so on." msgstr "" #. (itstool) path: note/para #: article.translate.xml:484 msgid "" "While it is possible to use a shorter name internally, e.g., just " "msg, adding the unique prefix ${name}_ to all " "global names introduced by our script will save us from possible collisions " "with the rc.subr8 namespace." msgstr "" #. (itstool) path: note/para #: article.translate.xml:490 msgid "" "As a rule, rc.d scripts of the base system need not " "provide defaults for their rc.conf5 variables because the " "defaults should be set in /etc/defaults/rc.conf instead." " On the other hand, rc.d scripts for ports should " "provide the defaults as shown in the example." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:501 msgid "" "Here we use dummy_msg to actually control our script, i.e., " "to emit a variable message. Use of a shell function is overkill here, since " "it only runs a single command; an equally valid alternative is:" msgstr "" #. (itstool) path: callout/programlisting #: article.translate.xml:506 #, no-wrap msgid "start_cmd=\"echo \\\"$dummy_msg\\\"\"" msgstr "" #. (itstool) path: sect1/title #: article.translate.xml:512 msgid "Startup and shutdown of a simple daemon" msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:514 msgid "" "We said earlier that rc.subr8 could provide default " "methods. Obviously, such defaults cannot be too general. They are suited for " "the common case of starting and shutting down a simple daemon program. Let " "us assume now that we need to write an rc.d script for " "such a daemon called mumbled. Here it is:" msgstr "" #. (itstool) path: informalexample/programlisting #: article.translate.xml:522 #, no-wrap msgid "" "#!/bin/sh\n" "\n" ". /etc/rc.subr\n" "\n" "name=mumbled\n" "rcvar=mumbled_enable\n" "\n" "command=\"/usr/sbin/${name}\"\n" "\n" "load_rc_config $name\n" "run_rc_command \"$1\"" msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:535 msgid "" "Pleasingly simple, isn't it? Let us examine our little script. The only new " "thing to note is as follows:" msgstr "" #. (itstool) path: callout/para #: article.translate.xml:540 msgid "" "The command variable is meaningful to " "rc.subr8. If it is set, rc." "subr8 will act " "according to the scenario of serving a conventional daemon. In particular, " "the default methods will be provided for such arguments: , , ." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:548 msgid "" "The daemon will be started by running $command with command-" "line flags specified by $mumbled_flags. Thus all the input " "data for the default method are available in the " "variables set by our script. Unlike , other methods " "may require additional information about the process started. For instance, " " must know the PID of the process to terminate it. In " "the present case, rc.subr8 will scan through the " "list of all processes, looking for a process with its name equal to " "$procname. The latter is another variable of meaning to " "rc.subr8, and its value defaults to that of command. In other words, when we set command, procname is effectively set to the same value. This enables our script to kill " "the daemon and to check if it is running in the first place." msgstr "" #. (itstool) path: note/para #: article.translate.xml:567 msgid "" "Some programs are in fact executable scripts. The system runs such a script " "by starting its interpreter and passing the name of the script to it as a " "command-line argument. This is reflected in the list of processes, which can " "confuse rc.subr8. You should additionally set " "command_interpreter to let rc." "subr8 know the actual " "name of the process if $command is a script." msgstr "" #. (itstool) path: note/para #: article.translate.xml:576 msgid "" "For each rc.d script, there is an optional " "rc.conf5 variable that takes precedence over " "command. Its name is constructed as follows: " "${name}_program, where name is the mandatory " "variable we discussed earlier. E.g., in " "this case it will be mumbled_program. It is " "rc.subr8 that arranges ${name}_program to " "override command." msgstr "" #. (itstool) path: note/para #: article.translate.xml:587 msgid "" "Of course, sh1 will permit you to set ${name}_program from rc.conf5 or the script itself " "even if command is unset. In that case, the special " "properties of ${name}_program are lost, and it becomes an " "ordinary variable your script can use for its own purposes. However, the " "sole use of ${name}_program is discouraged because using it " "together with command became an idiom of rc.d scripting." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:599 msgid "" "For more detailed information on default methods, refer to " "rc.subr8." msgstr "" #. (itstool) path: sect1/title #: article.translate.xml:606 msgid "Startup and shutdown of an advanced daemon" msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:608 msgid "" "Let us add some meat onto the bones of the previous script and make it more " "complex and 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." msgstr "" #. (itstool) path: informalexample/programlisting #: article.translate.xml:615 #, no-wrap msgid "" "#!/bin/sh\n" "\n" ". /etc/rc.subr\n" "\n" "name=mumbled\n" "rcvar=mumbled_enable\n" "\n" "command=\"/usr/sbin/${name}\"\n" "command_args=\"mock arguments > /dev/null 2>&1\"\n" "\n" "pidfile=\"/var/run/${name}.pid\"\n" "\n" "required_files=\"/etc/${name}.conf /usr/share/misc/${name}.rules\"\n" "\n" "sig_reload=\"USR1\"\n" "\n" "start_precmd=\"${name}_prestart\"\n" "stop_postcmd=\"echo Bye-bye\"\n" "\n" "extra_commands=\"reload plugh xyzzy\"\n" "\n" "plugh_cmd=\"mumbled_plugh\"\n" "xyzzy_cmd=\"echo 'Nothing happens.'\"\n" "\n" "mumbled_prestart()\n" "{\n" " if checkyesno mumbled_smart; then\n" " rc_flags=\"-o smart ${rc_flags}\"\n" " fi\n" " case \"$mumbled_mode\" in\n" " foo)\n" " rc_flags=\"-frotz ${rc_flags}\"\n" " ;;\n" " bar)\n" " rc_flags=\"-baz ${rc_flags}\"\n" " ;;\n" " *)\n" " warn \"Invalid value for mumbled_mode\"\n" " return 1\n" " ;;\n" " esac\n" " run_rc_command xyzzy\n" " return 0\n" "}\n" "\n" "mumbled_plugh()\n" "{\n" " echo 'A hollow voice says \"plugh\".'\n" "}\n" "\n" "load_rc_config $name\n" "run_rc_command \"$1\"" msgstr "" #. (itstool) path: callout/para #: article.translate.xml:671 msgid "" "Additional arguments to $command can be passed in " "command_args. They will be added to the command line after " "$mumbled_flags. Since the final command line is passed to " "eval for its actual execution, input and output " "redirections can be specified in command_args." msgstr "" #. (itstool) path: note/para #: article.translate.xml:679 msgid "" "Never include dashed options, like " "or , in command_args. The contents of " "command_args will appear at the end of the final command " "line, hence they are likely to follow arguments present in " "${name}_flags; but most commands will not recognize dashed " "options after ordinary arguments. A better way of passing additional options " "to $command is to add them to the beginning of " "${name}_flags. Another way is to modify rc_flags as shown later." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:695 msgid "" "A good-mannered daemon should create a pidfile so that " "its process can be found more easily and reliably. The variable " "pidfile, if set, tells rc.subr8 where it can find the " "pidfile for its default methods to use." msgstr "" #. (itstool) path: note/para #: article.translate.xml:703 msgid "" "In fact, rc.subr8 will also use the pidfile to see if the daemon is " "already running before starting it. This check can be skipped by using the " " argument." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:711 msgid "" "If the daemon cannot run unless certain files exist, just list them in " "required_files, and rc.subr8 will check that those " "files do exist before starting the daemon. There also are " "required_dirs and required_vars for " "directories and environment variables, respectively. They all are described " "in detail in rc.subr8." msgstr "" #. (itstool) path: note/para #: article.translate.xml:720 msgid "" "The default method from rc.subr8 can be forced to skip " "the prerequisite checks by using as the argument " "to the script." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:728 msgid "" "We can customize signals to send to the daemon in case they differ from the " "well-known ones. In particular, sig_reload specifies the " "signal that makes the daemon reload its configuration; it is SIGHUP by default. Another signal is sent to stop the daemon process; the " "default is SIGTERM, but this can be changed by setting " "sig_stop appropriately." msgstr "" #. (itstool) path: note/para #: article.translate.xml:738 msgid "" "The signal names should be specified to rc." "subr8 without the " "SIG prefix, as it is shown in the example. The FreeBSD " "version of kill1 can recognize the SIG prefix, " "but the versions from other OS types may not." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:747 msgid "" "Performing additional tasks before or after the default methods is easy. For " "each command-argument supported by our script, we can define " "argument_precmd and " "argument_postcmd. These " "sh1 commands are invoked before and after the respective method, " "as it is evident from their names." msgstr "" #. (itstool) path: note/para #: article.translate.xml:757 msgid "" "Overriding a default method with a custom argument_cmd still does not prevent us from making use of " "argument_precmd or " "argument_postcmd if we need to. In " "particular, the former is good for checking custom, sophisticated conditions " "that should be met before performing the command itself. Using " "argument_precmd along with " "argument_cmd lets us logically " "separate the checks from the action." msgstr "" #. (itstool) path: note/para #: article.translate.xml:770 msgid "" "Do not forget that you can cram any valid sh1 expressions into the " "methods, pre-, and post-commands you define. Just invoking a function that " "makes the real job is a good style in most cases, but never let style limit " "your understanding of what is going on behind the curtain." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:780 msgid "" "If we would like to implement custom arguments, which can also be thought of " "as commands to our script, we need to list them in " "extra_commands and provide methods to handle them." msgstr "" #. (itstool) path: note/para #: article.translate.xml:787 msgid "" "The command is special. On the one hand, it has a " "preset method in rc.subr8. On the other hand, " " is not offered by default. The reason is that not " "all daemons use the same reload mechanism and some have nothing to reload at " "all. So we need to ask explicitly that the builtin functionality be provided." " We can do so via extra_commands." msgstr "" #. (itstool) path: note/para #: article.translate.xml:796 msgid "" "What do we get from the default method for ? Quite " "often daemons reload their configuration upon reception of a signal — " "typically, SIGHUP. Therefore " "rc.subr8 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." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:808 msgid "" "Our script supports two non-standard commands, and " ". We saw them listed in extra_commands, " "and now it is time to provide methods for them. The method for " " is just inlined while that for " "is implemented as the mumbled_plugh function." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:816 msgid "" "Non-standard commands are not invoked during startup or shutdown. Usually " "they are for the system admin's convenience. They can also be used from " "other subsystems, e.g., devd8 if specified in " "devd.conf5." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:821 msgid "" "The full list of available commands can be found in the usage line printed " "by rc.subr8 when the script is invoked without arguments. For " "example, here is the usage line from the script under study:" msgstr "" #. (itstool) path: callout/screen #: article.translate.xml:826 #, no-wrap msgid "" "# /etc/rc.d/mumbled\n" "Usage: /etc/rc.d/mumbled " "[fast|force|one](start|stop|restart|rcvar|reload|plugh|xyzzy|status|poll)" msgstr "" #. (itstool) path: callout/para #: article.translate.xml:831 msgid "" "A script can invoke its own standard or non-standard commands if needed. " "This may look similar to calling functions, but we know that commands and " "shell functions are not always the same thing. For instance, xyzzy is not implemented as a function here. In addition, there can be a " "pre-command and post-command, which should be invoked orderly. So the proper " "way for a script to run its own command is by means of " "rc.subr8, as shown in the example." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:843 msgid "" "A handy function named checkyesno is provided by " "rc.subr8. It takes a variable name as its argument and " "returns a zero exit code if and only if the variable is set to YES, or TRUE, or ON, or " "1, case insensitive; a non-zero exit code is returned " "otherwise. In the latter case, the function tests the variable for being set " "to NO, FALSE, OFF, " "or 0, case insensitive; it prints a warning message if " "the variable contains anything else, i.e., junk." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:856 msgid "" "Keep in mind that for sh1 a zero exit code means " "true and a non-zero exit code means false." msgstr "" #. (itstool) path: important/para #: article.translate.xml:860 msgid "" "The checkyesno function takes a variable " "name. Do not pass the expanded value of a " "variable to it; it will not work as expected." msgstr "" #. (itstool) path: important/para #: article.translate.xml:865 msgid "The following is the correct usage of checkyesno:" msgstr "" #. (itstool) path: important/programlisting #: article.translate.xml:868 #, no-wrap msgid "if checkyesno mumbled_enable; then\n" " foo\n" "fi" msgstr "" #. (itstool) path: important/para #: article.translate.xml:872 msgid "" "On the contrary, calling checkyesno as shown below will " "not work — at least not as expected:" msgstr "" #. (itstool) path: important/programlisting #: article.translate.xml:876 #, no-wrap msgid "if checkyesno \"${mumbled_enable}\"; then\n" " foo\n" "fi" msgstr "" #. (itstool) path: callout/para #: article.translate.xml:883 msgid "" "We can affect the flags to be passed to " "$command by modifying rc_flags in " "$start_precmd." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:889 msgid "" "In certain cases we may need to emit an important message that should go to " "syslog as well. This can be done easily with the " "following rc.subr8 functions: debug, " "info, warn, and err. The latter function then exits the script with the code specified." "" msgstr "" #. (itstool) path: callout/para #: article.translate.xml:899 msgid "" "The exit codes from methods and their pre-commands are not just ignored by " "default. If argument_precmd " "returns a non-zero exit code, the main method will not be performed. In " "turn, argument_postcmd will not be " "invoked unless the main method returns a zero exit code." msgstr "" #. (itstool) path: note/para #: article.translate.xml:909 msgid "" "However, rc.subr8 can be instructed from the command line to ignore " "those exit codes and invoke all commands anyway by prefixing an argument " "with force, as in ." msgstr "" #. (itstool) path: sect1/title #: article.translate.xml:920 msgid "Connecting a script to the rc.d framework" msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:922 msgid "" "After a script has been written, it needs to be integrated into rc." "d. The crucial step is to install the script in /etc/rc." "d (for the base system) or /usr/local/etc/rc.d (for ports). Both <bsd.prog.mk> and " "<bsd.port.mk> provide convenient hooks for that, " "and usually you do not have to worry about the proper ownership and mode. " "System scripts should be installed from src/etc/rc.d " "through the Makefile found there. Port scripts can be " "installed using USE_RC_SUBR as described in the Porter's Handbook." msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:936 msgid "" "However, we should consider beforehand the place of our script in the system " "startup sequence. The service handled by our script is likely to depend on " "other services. For instance, a network daemon cannot function without the " "network interfaces and routing up and running. Even if a service seems to " "demand nothing, it can hardly start before the basic filesystems have been " "checked and mounted." msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:944 msgid "" "We mentioned rcorder8 already. Now it is " "time to have a close look at it. In a nutshell, " "rcorder8 takes a set of files, examines their contents, and " "prints a dependency-ordered list of files from the set to stdout. The point is to keep dependency information inside the files so that each file can speak for itself only. A file can " "specify the following information:" msgstr "" #. (itstool) path: listitem/para #: article.translate.xml:955 msgid "" "the names of the conditions (which means services to us) it " "provides;" msgstr "" #. (itstool) path: listitem/para #: article.translate.xml:960 msgid "" "the names of the conditions it requires;" msgstr "" #. (itstool) path: listitem/para #: article.translate.xml:965 msgid "" "the names of the conditions this file should run " "before;" msgstr "" #. (itstool) path: listitem/para #: article.translate.xml:970 msgid "" "additional keywords that can be used to select a subset " "from the whole set of files (rcorder8 can be instructed via " "options to include or omit the files having particular keywords listed.)" msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:977 msgid "" "It is no surprise that rcorder8 can handle only text " "files with a syntax close to that of sh1. That is, special " "lines understood by rcorder8 look like " "sh1 comments. The syntax of such special lines is rather rigid to " "simplify their processing. See rcorder8 for details." msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:984 msgid "" "Besides using rcorder8 special lines, a " "script can insist on its dependency upon another service by just starting it " "forcibly. This can be needed when the other service is optional and will not " "start by itself because the system admin has disabled it mistakenly in " "rc.conf5." msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:990 msgid "" "With this general knowledge in mind, let us consider the simple daemon " "script enhanced with dependency stuff:" msgstr "" #. (itstool) path: informalexample/programlisting #: article.translate.xml:994 #, no-wrap msgid "" "#!/bin/sh\n" "\n" "# PROVIDE: mumbled oldmumble \n" "# REQUIRE: DAEMON cleanvar frotz\n" "# BEFORE: LOGIN\n" "# KEYWORD: nojail shutdown\n" "\n" ". /etc/rc.subr\n" "\n" "name=mumbled\n" "rcvar=mumbled_enable\n" "\n" "command=\"/usr/sbin/${name}\"\n" "start_precmd=\"${name}_prestart\"\n" "\n" "mumbled_prestart()\n" "{\n" " if ! checkyesno frotz_enable && \\\n" " ! /etc/rc.d/frotz forcestatus 1>/dev/null 2>&1; then\n" " force_depend frotz || return 1\n" " fi\n" " return 0\n" "}\n" "\n" "load_rc_config $name\n" "run_rc_command \"$1\"" msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:1022 msgid "As before, detailed analysis follows:" msgstr "" #. (itstool) path: callout/para #: article.translate.xml:1026 msgid "" "That line declares the names of conditions our script " "provides. Now other scripts can record a dependency on our script by those " "names." msgstr "" #. (itstool) path: note/para #: article.translate.xml:1031 msgid "" "Usually a script specifies a single condition provided. However, nothing " "prevents us from listing several conditions there, e.g., for compatibility " "reasons." msgstr "" #. (itstool) path: note/para #: article.translate.xml:1036 msgid "" "In any case, the name of the main, or the only, PROVIDE: " "condition should be the same as ${name}." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:1043 msgid "" "So our script indicates which conditions provided by other " "scripts it depends on. According to the lines, our script asks " "rcorder8 to put it after the script(s) providing " "DAEMON and cleanvar, but before " "that providing LOGIN." msgstr "" #. (itstool) path: note/para #: article.translate.xml:1051 msgid "" "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. 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." msgstr "" #. (itstool) path: note/para #: article.translate.xml:1063 msgid "" "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 UPPERCASE names. Their " "list and purposes can be found in rc8." msgstr "" #. (itstool) path: note/para #: article.translate.xml:1072 msgid "" "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 rc.conf5. Obviously, " "rcorder8 cannot track such details, and " "rc8 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 below." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:1086 msgid "" "As we remember from the above text, " "rcorder8 keywords can be used to select or leave out some " "scripts. Namely any rcorder8 consumer can specify " "through and options which keywords " "are on the keep list and skip list, " "respectively. From all the files to be dependency sorted, " "rcorder8 will pick only those having a keyword from the " "keep list (unless empty) and not having a keyword from the skip list." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:1096 msgid "" "In FreeBSD, rcorder8 is used by /" "etc/rc and /etc/rc.shutdown. These two " "scripts define the standard list of FreeBSD rc.d " "keywords and their meanings as follows:" msgstr "" #. (itstool) path: varlistentry/term #: article.translate.xml:1104 msgid "nojail" msgstr "" #. (itstool) path: listitem/para #: article.translate.xml:1107 msgid "" "The service is not for jail8 environment. The " "automatic startup and shutdown procedures will ignore the script if inside a " "jail." msgstr "" #. (itstool) path: varlistentry/term #: article.translate.xml:1114 msgid "nostart" msgstr "" #. (itstool) path: listitem/para #: article.translate.xml:1117 msgid "" "The service is to be started manually or not started at all. The automatic " "startup procedure will ignore the script. In conjunction with the " "shutdown keyword, this can be used to write scripts that " "do something only at system shutdown." msgstr "" #. (itstool) path: varlistentry/term #: article.translate.xml:1127 msgid "shutdown" msgstr "" #. (itstool) path: listitem/para #: article.translate.xml:1130 msgid "" "This keyword is to be listed explicitly if the service " "needs to be stopped before system shutdown." msgstr "" #. (itstool) path: note/para #: article.translate.xml:1135 msgid "" "When the system is going to shut down, /etc/rc.shutdown " "runs. It assumes that most rc.d scripts have nothing to " "do at that time. Therefore /etc/rc.shutdown selectively " "invokes rc.d scripts with the shutdown keyword, effectively ignoring the rest of the scripts. For even " "faster shutdown, /etc/rc.shutdown passes the " " 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, /etc/rc.shutdown " "runs the scripts in reverse dependency order." msgstr "" #. (itstool) path: note/para #: article.translate.xml:1152 msgid "" "If writing a real rc.d script, you should consider " "whether it is relevant at system shutdown time. E.g., if your script does " "its work in response to the 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 " "halt8. 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." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:1173 msgid "" "To begin with, force_depend should be used with much care. It is generally better to revise " "the hierarchy of configuration variables for your rc.d " "scripts if they are interdependent." msgstr "" #. (itstool) path: callout/para #: article.translate.xml:1179 msgid "" "If you still cannot do without force_depend, the " "example offers an idiom of how to invoke it conditionally. In the example, " "our mumbled daemon requires that another one, " "frotz, be started in advance. However, frotz is optional, too; and rcorder8 knows nothing about " "such details. Fortunately, our script has access to all " "rc.conf5 variables. If frotz_enable is true, " "we hope for the best and rely on rc.d to have started " "frotz. Otherwise we forcibly check the status of " "frotz. Finally, we enforce our dependency on " "frotz if it is found to be not running. A warning message " "will be emitted by force_depend because it should be " "invoked only if a misconfiguration has been detected." msgstr "" #. (itstool) path: sect1/title #: article.translate.xml:1201 msgid "Giving more flexibility to an rc.d script" msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:1203 msgid "" "When invoked during startup or shutdown, an rc.d script " "is supposed to act on the entire subsystem it is responsible for. E.g., " "/etc/rc.d/netif should start or stop all network " "interfaces described by rc.conf5. Either task can be " "uniquely indicated by a single command argument such as . Between startup and shutdown, rc." "d 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 " "rc.conf5 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 rc.d script calls for an extra argument, the " "interface name." msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:1221 msgid "" "Fortunately, rc.subr8 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." msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:1225 msgid "" "How can rc.subr8 gain access to the extra command-line arguments. " "Should it just grab them directly? Not by any means. Firstly, an " "sh1 function has no access to the positional parameters of its " "caller, but rc.subr8 is just a sack of such " "functions. Secondly, the good manner of rc.d dictates " "that it is for the main script to decide which arguments are to be passed to " "its methods." msgstr "" #. (itstool) path: sect1/para #: article.translate.xml:1235 msgid "" "So the approach adopted by rc.subr8 is as follows: " "run_rc_command 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: ,