Startup Items

By: James Reynolds - Revised: 2006-05-25 devin

Introduction

Learn about startup items—parent folders, scripts, /etc/rc.common, resources, and StartupParameters.plist.

What are startup items?

Here are some examples of startup items:

Apple/System

Network
Disks
Apache
ssh
loginwindow

3rd party

PostgreSQL
Timbuktu

A startup item has these components:

Parent folder
Script (must have the exact name as the parent folder)
Resources
Description (StartupItems.plist)

Parent folder

This folder should contain everything used by the startup item. It should have a self explanitory name.

There are 2 locations where these folders are stored: /Library/StartupItems and /System/Library/StartupItems. The System folder contains Apple's startup items. 3rd party startup items go in /Library/StartupItems. This folder does not exist after a vanilla install. You must create it. If you make an installer with PackageMaker, you must keep this in mind...

The script

The script file must have the user exectuable set. All startup items are launched with one parameter: "start", "stop", or "restart". This is how the startup item script is executed:

/sbin/SystemStarter start "Some Startup Script"

Or to restart Apache:

/sbin/SystemStarter restart "Web Server"

"Web Server" is the name of the Apache startup item. This name is the value for the "Provides" key listed in the StartupParameters.plist. This will be explained below.

If your startup script works from the command line, but not at startup, instead debugging by rebooting constantly, you can use the above syntax to debug it.

The script can be any type of executable, but is best to use BASH (/bin/sh) because there is a BASH script skeleton and there is a common file with useful functions.

Here is the script skeleton:

#!/bin/sh

##
# Your script name
##

. /etc/rc.common

StartService ()
{
}

StopService ()
{
}

RestartService ()
{
}

RunService "$1"

Startup code should go in StartService.

StopService is used for daemons, like apache, so that they shutdown correctly. Currently, shutdown or restart does not call this function, but it should be called, especially for databases. And hopefully Apple may eventually add a StopService call when the Mac shutsdown.

RestartService is similarly used for daemons, like apache.

What does ". /etc/rc.common" do?

Export Paths

/bin
/sbin
/usr/bin
/usr/sbin
/usr/libexec
/System/Library/CoreServices

Imports /etc/hostconfig (this is how the system knows if it should launch daemons or not)
Enables CoreDumps

Contains these functions you can use:

ConsoleMessage() - Prints message to the startup console. Usage:

ConsoleMessage "Restarting Apache web server"

CheckForNetwork() - Returns the status of the network. Usage:

CheckForNetwork
if [ "${NETWORKUP}" = "-NO-" ]; then exit; fi

GetPID() - Returns the PID

RunService($1)

Calls StartService if $1 is "start".
Calls StopService if $1 is "stop".
Calls RestartService if $1 is "restart".

purgedir() - Delete contents of directory, but leaves directory structure alone.

Example startup script

Here is the Apache startup item script:

#!/bin/sh

##
# Apache HTTP Server
##

. /etc/rc.common

StartService ()
{
    if [ "${WEBSERVER:=-NO-}" = "-YES-" ]; then
        ConsoleMessage "Starting Apache web server"
        apachectl start
    fi
}

StopService ()
{
    ConsoleMessage "Stopping Apache web server"
    apachectl stop
}
v RestartService ()
{
    if [ "${WEBSERVER:=-NO-}" = "-YES-" ]; then
        ConsoleMessage "Restarting Apache web server"
        apachectl restart
    else
        StopService
    fi
}

RunService "$1"

For more examples of StartupItems, just look at everything in /System/Library/StartupItems/

Resources

Put images, Localizations, other scripts, daemons, and anything you want in the "Resources" folder. This folder isn't required, but it is where extra files should go.

StartupParameters.plist

This file is a specially formated file (OpenStep format) with several required keys:

Description - A short description of the startup item. This is what is displayed in the console startup window.
Provides - The service(s) provided by this startup item. This is what other scripts may "Require" or "Use". It should be unique. If 2 startup items have the same "provides", the first startup item encountered will be executed and the second will be ignored.
Requires - The "provides" of other startup items that MUST finish before this one can run. If the required services are not available, this startup item is not run.
Uses - The "provides" of other startup items that should finish before this startup item, but which are not mandatory. The startup item should be able to start without the availability of these services.
OrderPreference - Advisory value if 2 startup items have identical "Requires" and "Uses". This value might be ignored.

"First"
"Early"
"None" (default)
"Late"
"Last"

Here is the StartupParameters.plist for the Apache startup item.

{
Description     = "Apache web server";
Provides        = ("Web Server");
Requires        = ("DirectoryServices");
Uses            = ("Disks", "NFS", "Network Time");
OrderPreference = "None";
}

When do startup items execute?

Here is the boot process and the exact execute location of the startup items.

BootROM (located in hardware)
/System/Library/CoreServices/BootX
    /sbin/mach_init
      /sbin/init
        /private/etc/rc.boot
        /private/etc/rc
          /System/Library/CoreServices/SystemStarter
            /System/Library/StartupItems/*
            /Library/StartupItems/*

SystemStarter is what executes valid startup items in /System/Library/StartupItems and /Library/StartupItems.

SystemStarter reads the StartupParameters.plist and determines the startup order. Scripts with no "Requires" or "Uses" executed first. The only script with no requirements is "System Tuning". The typical startup order is something like this: "System Tuning", "ConfigServer", "Network", "Disks" and then startup items that require network and disks.