HOWTO Make an rc script

From Gentoo Linux Wiki

[edit] Introduction

rc scripts are used to launch programs which are called daemons or services. These programs are started during the boot process and do not exit until deliberately stopped. An example of a daemon is the Apache Web service or an email service, these services typically run whenever your server is running.

Gentoo includes a very sophisticated and powerful facility for managing the daemon services. This system is similar to but not compatible with the rc system that is used by other versions of *nix. The Gentoo rc scripts are quite easy to make and a simple script can be written in under 5 min.

This wiki page gives an overview of a typical rc script, for a more in-depth technical discussion be sure to also read the manual

[edit] Required Functions

• start()
  • this is what will be run when the script is started

[edit] Optional Functions

• depend()
  • this is used for service dependencies and handles service run order (see example below)
• stop()
  • this will be run when the script is stopped
• restart()
  • this will be run when the service is restarted
• checkconfig()
  • this is to have a config file at /etc/conf.d/servicename

[edit] Example rc script

For this example we will make a script to run the "example" daemon. This example should be called /etc/init.d/example

#!/sbin/runscript

depend() {
        # the daemon needs the internet to function
        need net  
        # the daemon should run before mta
        before mta
        # the daemon uses logger
        use logger
        # the daemon should run after domainname
        after domainname
}

checkconfig() {
        if [ -z "$VAR_FROM_CONFIG" ] || [ -z "$VAR2_FROM_CONFIG" ] ; then
          eerror "You must set config options in /etc/conf.d/example first"
          return 1
        fi
}

start() {        
        # display to the user what you're doing
        ebegin "Starting Example daemon"  
        #run the checkconfig function
        checkconfig || return 1
        # Start the process as a daemon and record the pid number
        start-stop-daemon --start --background --pidfile /var/run/example.pid --make-pidfile --exec /usr/bin/example  
        # output success or failure
        eend $?
}

stop() {
        # display a message to the user
        ebegin "Stopping example daemon"
        # stop the daemon using the pid recorded from the start() function
        start-stop-daemon --stop --pidfile /var/run/example.pid --name example
        # output success or failure
        eend $?
}

This is the /etc/conf.d/example file

#/etc/conf.d/example - configuration variables
VAR_FROM_CONFIG="EXAMPLE"
VAR2_FROM_CONFIG="EXAMPLE2"

If you need to pass arguments to the executable using the start-stop-daemon the start section of your rc-script will look like the following. In this example we'll be running /usr/bin/example -d

start() {
        # display to the user what you're doing
        ebegin "Starting Example daemon"  
        # Start the process as a daemon with the arguement "-d" and recording the pid number
        start-stop-daemon --start --background --pidfile /var/run/example.pid --make-pidfile --exec /usr/bin/example -- -d
        # output success or failure
        eend $?
}

If you have problems stopping your script after it's started, try using the following as an example:

#!/sbin/runscript

depend() {
        # the daemon needs the internet to function
        need net
}

start() {
        ebegin "Starting Example daemon"
        start-stop-daemon --start --exec /usr/bin/example
        eend $?
}

stop() {
        ebegin "Stopping Example daemon"
        start-stop-daemon --stop --exec /usr/sbin/example
        eend $?
}

[edit] Making Your Script Run

You may need to make the script executable before it will run.

user@machine $ chmod +x example

[edit] One Time

• make sure the script is in /etc/init.d/
• run "/etc/init.d/example start"

[edit] On Boot

• make sure the script is in /etc/init.d/
• use rc-update "rc-update add example defaults"

[edit] Stopping The Script

• to stop it "/etc/init.d/example stop"
• to stop a defunct script "/etc/init.d/example zap" this will remove the pid file

[edit] See Also

• runscript
• rc-update
• rc-status