From 9f3929188c64a36544d3218f84acdf44e78bb7c4 Mon Sep 17 00:00:00 2001 From: Tom Rhodes Date: Fri, 10 Sep 2004 06:20:22 +0000 Subject: [PATCH] For my RE task: rewrite about 90% of the starting services section purposely leaving 3 paragraphs. The paragraphs should be reworded and get a kick with the whitespace boot but I would rather not affect translators that much. --- .../books/handbook/config/chapter.sgml | 183 +++++++++++++----- 1 file changed, 136 insertions(+), 47 deletions(-) diff --git a/en_US.ISO8859-1/books/handbook/config/chapter.sgml b/en_US.ISO8859-1/books/handbook/config/chapter.sgml index 8287924f00..7f750a9ce7 100644 --- a/en_US.ISO8859-1/books/handbook/config/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/config/chapter.sgml @@ -320,38 +320,77 @@ + + + + Tom + Rhodes + Contributed by + + + + Starting Services services - It is common for a system to host a number of services. - These may be started in several different fashions, each having - different advantages. + Many users choose to install third party software on &os; + from the ports collection. In many of these situations it + may be necessary to configure the software in a manner which + will allow it to be started upon system initialization. Services, + such as mail/postfix or + www/apache13 are just two + of the many software packages which may be started during system + initialization. Thus it is only fair that an explanation be + provided on the procedures available for working with third + party software, in the rare cases something goes wrong and the + application does not start up properly. - /usr/local/etc/rc.d + In &os;, most included services, such as &man.cron.8;, are + started through the system start up scripts. These scripts may + different depending on &os; or vendor version; however, the most + important aspect to consider is that their start up configuration + can be handled through simple startup scripts. - Software installed from a port or the packages collection - will often place a script in - /usr/local/etc/rc.d which is invoked at - system startup with a argument, and at - system shutdown with a argument. - This is the recommended way for - starting system-wide services that are to be run as - root, or that - expect to be started as root. + Since the advent of rcNG, it became clear that system + initialization for third party utilities could be simplified. + For years applications would drop a simple start up script into + the /usr/local/etc/rc.d + directory which would be read by the system initialization + scripts. These scripts would then be executed during the latter + stages of system start up. - A generic startup script in - /usr/local/etc/rc.d looks similar to: + While many individuals have spent hours trying to merge the + old configuration style into the new system, the fact remains + that some third party utilities still require a script simply + dropped into the aforementioned directory. The subtle differences + in the scripts depend whether or not rcNG is being used. Any + version of &os; prior to 5.1 will not require the extra bit of + configuration; indeed, in almost all cases the soon to be + recognized script would do just fine. + + While every script must meet some minimal requirements, most + of the time these requirements are &os; version + agnostic. Each script must have a .sh + extension appended to the end and every script must be + executable by the system. The latter may be achieved by using + the chmod and setting the unique permissions + of 755. There should also be, at minimal, + an option to start the application and an + option to stop the application. + + The simplest start up script would probably look a little + bit like this one: #!/bin/sh -echo -n ' FooBar' +echo -n ' utility' case "$1" in start) - /usr/local/bin/foobar + /usr/local/bin/utility ;; stop) - kill -9 `cat /var/run/foobar.pid` + kill -9 `cat /var/run/utility.pid` ;; *) echo "Usage: `basename $0` {start|stop}" >&2 @@ -359,33 +398,87 @@ stop) ;; esac -exit 0 - +exit 0 - The startup scripts of &os; will look in - /usr/local/etc/rc.d for scripts that have an - .sh extension and are executable by - root. Those scripts that are found are called with - an option at startup, and - at shutdown to allow them to carry out their purpose. So if you wanted - the above sample script to be picked up and run at the proper time during - system startup, you should save it to a file called - FooBar.sh in - /usr/local/etc/rc.d and make sure it is - executable. You can make a shell script executable with &man.chmod.1; - as shown below: + This script provides for a stop and + start option for + the application hereto referred simply as + utility. This application + could then have the following lines placed in + /etc/rc.conf: - &prompt.root; chmod 755 FooBar.sh + utility_enable="YES" - This convention does not always apply; however, as - &os; 5.X progresses, the method of starting software has - slowly been merged into the rc.conf file. - For instance, to start the - www/apache13 web server during - system initialization, append the following line to the - rc.conf file: + Could be started manually with: - apache_enable="YES" + &prompt.root; /usr/local/etc/rc.d/utility.sh start + + While not all third party software requires the line in + rc.conf, almost every day a new port will + be modified to accept this configuration. Check the final output + of the installation for more information on a specific + application. Some third party software will provide start up + scripts which permit the application to be used with + rcNG; although, this will be discussed in the next section. + + + Extended Application Configuration + + Now that &os; includes rcNG, configuration of application + start up has become more optimal; indeed, it has become a bit + more in depth. Using the key words discussed in the + rcNG section, + applications may now be set to start after certain other + services for example DNS; may permit extra + flags to be passed through rc.conf in + place of hard coded flags in the start up script, etc. A + basic script may look similar to the following: + + #!/bin/sh +# +# PROVIDE: utility +# REQUIRE: DAEMON +# BEFORE: LOGIN +# KEYWORD: FreeBSD shutdown + +# +# DO NOT CHANGE THESE DEFAULT VALUES HERE +# SET THEM IN THE /etc/rc.conf FILE +# +utility_enable=${utility_enable-"NO"} +utility_flags=${utility_flags-""} +utility_pidfile=${utility_pidfile-"/var/run/utility.pid"} + +. /etc/rc.subr + +name="utility" +rcvar=`set_rcvar` +command="/usr/local/sbin/utility" + +load_rc_config $name + +pidfile="${utility_pidfile}" + +start_cmd="echo \"Starting ${name}.\"; /usr/bin/nice -5 ${command} ${utility_flags} ${command_args}" + +run_rc_command "$1" + + This script will ensure that the provided + utility will be started before the + login service but after the + daemon service. It also provides a method + for setting and tracking the PID, or process + ID file. + + This new method also allows for easier manipulation of the + command line arguments, inclusion of the default functions + provided in /etc/rc.subr, compatibility + with the &man.rcorder.8; utility and provide for easier + configuration via the rc.conf file. In + essence, this script could even be placed in + /etc/rc.d directory. + Yet, that has the potential to upset the &man.mergemaster.8; + utility when used in conjunction with software upgrades. Some services expect to be invoked by &man.inetd.8; when a connection is received on a suitable port. This is common for @@ -393,12 +486,6 @@ exit 0 enabled by editing the file /etc/inetd.conf. See &man.inetd.8; for details on editing this file. - Do not place any commands in - /etc/rc.conf. To start daemons, or - run any commands at boot time, place a script in - /usr/local/etc/rc.d or /etc/rc.d instead. - - It is also possible to use the &man.cron.8; daemon to start system services. This approach has a number of advantages, not least being that because &man.cron.8; runs these processes as the @@ -410,6 +497,8 @@ exit 0 which will cause the job to be run when &man.cron.8; is started shortly after system boot. + +