Latest revision as of 18:42, 27 February 2012

Initscript usage

To manage initscripts, you should use service and chkconfig.

service

service is a shell script used to start and stop services, either standalone or run with xinetd. Usage is simple, just use

service <name_of_service> <actiont>

where action can be one of start, stop, status, restart, reload (same as restart if the package doesn't support on-the-fly reloading) or anything the script can support.

Chkconfig

Chkconfig is used to manage the /etc/rc?.d/* and xinetd config files. It removes and adds symlinks in order to start or stop a service at boot for a given runlevel. You should use it to add your script to the system. Macros are provided to wrap the call to chkconfig.

An example

Here is a generic example. You can find others in /etc/init.d/. It should be quite easy to adapt, as you only need to change the variable DAEMON_NAME.

#!/bin/sh
#
### BEGIN INIT INFO
# Provides: some_daemon
# Required-Start: $network
# Required-Stop: $network
# Default-Start: 3 4 5
# Short-Description: nothing
# Description: some_daemon is nothing.
#              Really, nothing.
### END INIT INFO

# Source function library.
. /etc/rc.d/init.d/functions

DAEMON_NAME=some_daemon
DAEMON_PROCESS=some_daemon
DAEMON_BINARY=some_daemon
LOCK_FILE=/var/lock/subsys/$DAEMON_NAME
RETVAL=0

# default option, they can be overriden in /etc/sysconfig/$DAEMON_NAME
# of course, you can place what you want.
OPTIONS=
PORT=1234
# this file should be commented, with proper pointer to the doc, and you
should use
# more than one line of option, if possible.
[ -f /etc/sysconfig/$DAEMON_NAME ] && . /etc/sysconfig/$DAEMON_NAME


# here, you can do what you want with the option

start() {
    # if you cannot start the daemon since something is missing ( like a
path that cannot be set by default
    # , place the test here
    # if [ -z "$SOME_VAR" ]; then
    #     echo "You need to set $SOME_VAR in /etc/sysconfig/$DAEMON_NAME"
    #     RETVAL=1
    #     return
    # fi

    [ -f $LOCK_FILE ] && return

    echo -n "Starting $DAEMON_NAME: "
    # use --user to run the daemon under the specified uid
    daemon $DAEMON_BINARY $OPTIONS -p $PORT
    RETVAL=$?
    echo
    [ $RETVAL -eq 0 ] && touch $LOCK_FILE
}

stop() {
    echo -n "Shutting down $DAEMON_NAME: "
    killproc $DAEMON_PROCESS
    RETVAL=$?
    echo
    [ $RETVAL -eq 0 ] && rm -f $LOCK_FILE
}

reload() {
    echo -n "Reloading $DAEMON_NAME configuration: "
    killproc $DAEMON_PROCESS -HUP
    RETVAL=$?
    echo
}

case "$1" in
    start)
        start
        ;;
    stop)
        stop
        ;;
    status)
        status $DAEMON_PROCESS
        RETVAL=$?
        ;;
    reload)
        reload
        ;;
    restart)
        stop
        start
        ;;
    condrestart)
        if [ -f $LOCK_FILE ]; then
            stop
            start
        fi
        ;;
    *)
        echo "Usage: $0 {start|stop|restart|reload|condrestart|status}"
        RETVAL=1
esac

exit $RETVAL

The header

The initscript header should use LSB tags ( chkconfig headers are deprecated and should not be used anymore). See Initscript Header Format for more details.

First part - Configuration

# Source function library.
. /etc/rc.d/init.d/functions

DAEMON_NAME=some_daemon
DAEMON_PROCESS=some_daemon
DAEMON_BINARY=some_daemon
LOCK_FILE=/var/lock/subsys/$DAEMON_NAME
RETVAL=0

# default option, they can be overriden in /etc/sysconfig/$DAEMON_NAME
# of course, you can place what you want.
OPTIONS=
PORT=1234
# this file should be commented, with proper pointer to the doc, and you
should use
# more than one line of option, if possible.
[ -f /etc/sysconfig/$DAEMON_NAME ] && . /etc/sysconfig/$DAEMON_NAME

# here, you can do what you want with the option

The first part deals with utility functions provided by /etc/rc.d/init.d/functions/.

The second part deals with useful script global variables. $DAEMON_NAME is used for providing user feedback, $DAEMON_BINARY is used to actually launch the service, and $DAEMON_PROCESS to communicate with it once launched. Depending of the service, they may be different or identical. RETVAL is used for action result status.

The third part deals with service configuration. If the service accepts some options, you should place a configuration file in /etc/sysconfig/. In order to ease the administrator duty and prevent namespace clashes, it should have the same name as the service. Placing default values in the script and in the config file is more robust than default value in the config file only.

Second part - Primitives

Using functions for defining primitives, such as start and stop allows to restart the service without reinvocating the script itself. Each of these function should set RETVAL.

A typical script needs the following functions:

start() {
    # if you cannot start the daemon since something is missing ( like a
path that cannot be set by default
    # , place the test here
    # if [ -z "$SOME_VAR" ]; then
    #     echo "You need to set $SOME_VAR in /etc/sysconfig/$DAEMON_NAME"
    #     RETVAL=1
    #     return
    # fi

    [ -f $LOCK_FILE ] && return

    echo -n "Starting $DAEMON_NAME: "
    # use --user to run the daemon under the specified uid
    daemon $DAEMON_BINARY $OPTIONS -p $PORT
    RETVAL=$?
    echo
    [ $RETVAL -eq 0 ] && touch $LOCK_FILE
}

This function is used to start the service. You have to take care of the lock before launching, to avoid having several instances running simultaneously. The "daemon" function takes care of everything (using libsafe, creating a pidfile, etc.), and should return OK only if the startup succedeed. However, some daemons do not crash at the beginning, like older versions of openldap, and still show OK even if they do not work.

stop() {
    echo -n "Shutting down $DAEMON_NAME: "
    killproc $DAEMON_PROCESS
    RETVAL=$?
    echo
    [ $RETVAL -eq 0 ] && rm -f $LOCK_FILE
}

This function is used to stop the service. The "killproc" function takes care of sending SIGSTOP (or any other given signal) to the process. Then you have to remove the lock file.

reload() {
    echo -n "Reloading $DAEMON_NAME configuration: "
    killproc $DAEMON_PROCESS -HUP
    echo
}

This function is used to reload the service, if the daemon supports it.

Last part - Handling arguments

 
case "$1" in
       .....
esac
exit $RETVAL

A typical script accepts the following actions:

start

Call start() function.

stop

Call stop() function.

status

Call status() function.

restart

    restart)
        stop
        start
        ;;

This action simply call stop and start, without checking if the service is currently running.

condrestart

    condrestart)
        if [ -f $LOCK_FILE ]; then
            stop
            start
        fi
        ;;

This action call stop and start, but only if the service is currently running.

reload

Just call reload() functions, if present. Otherwise, you may as well handle "reload" as "restart"

default action

    *)
        echo "Usage: $0 {start|stop|restart|reload|condrestart|status}"
        RETVAL=1

If nothing else matches the action specified, the script should show an error message, and return an exitvalue of 1 to show there is an error. If you add some actions do not forget to add them in the error message. Bash completion uses a regexp matching "Usage: . {.'}", so do not change the format of the messages.

The daemon function

The "daemon" function is defined in /etc/init.d/functions. Right now, there are some arguments to pass:

• --user <uid>: to run the daemon under the specified UID
• --check <name>: to define the name of file with the pid of the process to check (in /var/run/$name.pid )
• +/-[0-9]: to add a nice level. the nice level can also be set in the config file, with the NICELEVEL variable

Integration in a package

In order to integrate your services in a package, you should be sure of the following points:

File naming

The filename should not contain a dot, as chkconfig will not take it into account. And, it should have the same name as the package, in lower case. The file should be in the directory /etc/rc.d/init.d/, which is linked by /etc/init.d. An rpm macro exists for this path, %_initrddir.

/home/misc $ rpm --eval %_initrddir
/etc/rc.d/init.d

Files permissions

The script should be runnable by root, and therefore, the permissions should be rwxr-xr-x. Msec resets the permissions once installed.

Macro in %preun and %post

In order to register your service, you need to place 2 macros, one in the %preun , one in the %post section :

# service_name is the name of the script
%post
%_post_service service_name

%preun
%_preun_service service_name

See the scripts /usr/share/rpm-helper/add-service and del-service. They take care of adding it to the boot sequence, and stopping or restarting the service if needed.

If the service should not be started by default because it misses some configuration, add the logic for checking in the initscript, and provide documentation regarding the setup to finish.

RPM requirements

As the previous macro use rpm-helper script, you need to be sure that rpm-helper is installed before the scripts are run. All you need is to add these tags to the spec:

Requires(post): rpm-helper
Requires(preun): rpm-helper

These indicate that the %post and %preun scripts need rpm-helper installed to be able to run.

Rpmlint errors

rpmlint uses a dedicated module to check the initscript. You can find it in the rpmlint package, file /usr/share/rpmlint/InitScriptCheck.py.

LSB Compliance

The Linux Standard Base proposes the following specs: http://refspecs.linuxbase.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/iniscrptact.html

Localisation issues

ROSA uses gprintf, which calls gettext with the localisation domain of "initscripts" to get the localisation of the first string passed to gprintf, replacing macros (such as %s ) with the remaining arguments. To reduce the load for localisers, it is best to ensure that gprintf calls keep the first string constant, so use:

gprintf "Starting %s: " $DAEMON_NAME

instead of:

gprintf "Starting $DAEMON_NAME: "

This allows just one translation to be maintained for each similar call. White space can have an effect too ... so be careful to ensure the string is kept exactly the same.

Note that the usage of "echo" calls will be replaced with gprintf calls (by /usr/share/spec-helper/gprintify.py which is called from /usr/share/spec-helper/spec-helper which is called from /usr/lib/rpm/brp-mandrake ). Sometimes, gprintify can mess up your good use of gprintf ... in which case you should export DONT_GPRINTIFY in the %install section of your spec file to prevent gprintify.py from being called.

Initscript Header format

Initscripts used in ROSA Linux should be described using LSB headers instead of chkconfig headers. Adding LSB headers will allow having a robust services dependency check, and to provide a base for parallelized initialization, so packagers are all encouraged to add LSB headers to their packages.

Migration to LSB headers

Let's take the previous dm init script as an example.

It contained the following comments:
# chkconfig: 5 30 09
# description: This startup script launches the graphical display manager.

LSB comments

We can add LSB headers in a block delimited by the following lines:

### BEGIN INIT INFO
### END INIT INFO

Facility provides

Each initscript should provide a facility name. The services should be named preferably using this policy: http://www.lanana.org/lsbreg/init/init.txt

Facilities that begin with a $ sign are reserved system facilities, such as $network. A complete list is available here: http://refspecs.linuxbase.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/facilname.html

# Provides: dm

Start dependencies

The services required by an initscript should be described using the Required-Start (mandatory service) or Should-Start (optional service) tags.

# Required-Start: xfs
# Should-Start: $network harddrake

Required services

Required-Start means that the listed services must be available for this service. The initscript system will make sure that they are ( chkconfig will enforce the dependency).

Optional services

Should-Start means that the listed services should be available for this service if possible. If an optional service is enabled in this runlevel, it will be started before. If it is not enabled, its start will not be enforced by the initscript system.

Stop dependencies

If another service has to be available during stop, the mandatory dependency should be described using a Required-Stop tag:

# Required-Stop: xfs

The same is available for optional dependencies, using the Should-Stop flag.

Runlevels

You can specify which runlevels the service should be started in using the Default-Start tag.

# Default-Start: 5

Descriptions

Descriptions have to be provided using the Short-Description and Description (potentially multi-line) tags.

# Short-Description: Launches the graphical display manager
# Description: This startup script launches the graphical display
# manager.

Final result

The dm initscript will finally end up with the following LSB header:

### BEGIN INIT INFO
# Provides: dm
# Required-Start: xfs
# Required-Stop: xfs
# Should-Start: $network harddrake
# Default-Start: 5
# Short-Description: Launches the graphical display manager
# Description: This startup script launches the graphical display manager.
### END INIT INFO

Interactive initscripts

Some initscripts request some user input, such as harddrake when a new device is found. For such scripts, LSB asks to use a tag in X-implementor-extension format. In ROSA Linux, X-ROSA-Interactive is used; for compatibility reasons, X-Mandriva-Interactive is also acceptable.

# X-ROSA-Interactive

References

For a more complete reference about the LSB headers, please see:

• LSB System Initialization
• openSUSE: Packaging init scripts
• Linux Assigned Names And Numbers Authority