3.2 Start-up/Shutdown Specifications

3.2.1 Execution Scripts

The /sbin/init.d directory contains all scripts used to start up and shutdown various subsystems. No script may invoke any of the other scripts in this directory. Scripts obtain configuration data from variables in /etc/rc.config.d (more on this later), which must be sourced by the execution script. All files in the /etc/rc.config.d directory may be read by sourcing the single file /etc/rc.config.

	NOTE: The start-up and shutdown scripts shipped by HP in /sbin/init.d must not be edited. Any changes made to these scripts will be overwritten when a new software release is installed. Modifying the behavior of a subsystem script is accomplished by using configuration variables, discussed in Section 2.3.4, “Configuration Files.”

In general, each script under /sbin/init.d should perform both the start-up and shutdown functions. In order to control the functionality within the script, each must also support standard arguments and exit codes. Scripts must be written for the POSIX shell. A template script may be found in /sbin/init.d/template.

3.2.1.4 Exit values

Exit values for start-up scripts are as follows:

0

script exited without error. This causes the status “OK” to appear in the checklist.

1

script encountered errors. This causes the status “FAIL” to appear in the checklist.

2

script was skipped due to overriding control variables from /etc/rc.config.d files or for other reasons, and did not actually do anything. This causes the status “N/A” to appear in the checklist.

3

script executed normally and requires an immediate system reboot for the changes to take effect (Reserved for key system components).

	CAUTION: These are the only exit values acceptable. Returning an arbitrary non-zero exit value from a command to indicate failure may cause the script to appear to have been skipped in the checklist, or may cause the system to reboot!

3.2.2 Configuration Variable Scripts

Instead of spreading configuration data throughout the various rc files in the system, configuration data is structured as a directory of files that allows developers to create and manage their own configuration files, without the complications of shared file ownership. The directory that holds the configuration variable scripts is /etc/rc.config.d. The configuration variable scripts will be sourced by the start-up and shutdown execution scripts in /sbin/init.d during system start-up and shutdown. This configuration information is used by the execution scripts to enable/disable and configure subsystems (such as IP addresses).

Examples of these variables include:

Each execution script may source its variables in one of two ways. If the execution script only needs the variables delivered with its product or fileset, it may explicitly source the file in /etc/rc.config.d. If the script requires variables that are delivered by other products or filesets, it may just source /etc/rc.config, which is a script that sources all the files below /etc/rc.config.d.

	NOTE: There are no requirements on the order of the files sourced. This means configuration files must not refer to variables defined in other configuration files, since there is no guarantee that the variable being referenced is currently defined.

Configuration variable scripts are written for the POSIX sh (/usr/bin/sh or /sbin/sh), and not the Bourne sh, ksh, or csh. In some cases, these files must also be read, and possibly modified by other scripts or the SAM program. For this reason, each variable definition must appear on a separate line, in the syntax:

variable=value

No trailing comments may appear on a variable definition line. Comment statements must be on separate lines, with the “#” comment character in column 1. An example of the required syntax for configuration files is given below:

# Cron configuration. See cron(1m) 
#
   
# CRON: Set to 1 to start cron daemon    
#
   
CRON=1

The name of a configuration script in /etc/rc.config.d corresponds to the names of the associated start-up and shutdown scripts found in /sbin/init.d.

3.2.3 Sequencing Scripts with Link Files

The third aspect of the start-up/shutdown scheme is controlling the order of script execution with link files. An important feature enables developers to control individual subsystems among run-levels. This is accomplished by providing link files in run level directories that point to the scripts in /sbin/init.d.

3.2.3.1 Run-level Directories: /sbin/rc#.d

The /sbin/rc#.d (where # is a run-level) directories are start-up and shutdown sequencer directories. They contain only symbolic links to start-up/shutdown scripts in /sbin/init.d that are executed by /sbin/rc on transition to a specific run level. For example, the /sbin/rc3.d directory contains symlinks to scripts that are executed when entering run level 3. (There is more information on /sbin/rc in Section 3.2.4, “Run Levels and /sbin/rc”).

These directories contain two types of link files: start links and kill links. Start links have names beginning with the capital letter “S” and are invoked with the “start” argument at system boot time or on transition to a higher run level. Kill links have names beginning with the capital letter “K” and are invoked with the “stop” argument at system shutdown time, or when moving to a lower run level.

Further, all link files in a sequencer directory are numbered to ensure a particular execution sequence. Each script has, as part of its name, a three digit sequence number. This, in combination with the start and kill notation, provides all the information necessary to properly start-up and shutdown a system.

Figure 3-2 Start-up/Shutdown Component Relationships

K180sendmail and S460sendmail are linked to sendmail.

	NOTE: The sequence numbers above are only for example and may not accurately represent your system.

Figure 3-2 shows the run-level directories and the relationship of the link files to the scripts. Because each script in /sbin/init.d performs both the start-up and shutdown functions, each will have two links pointing towards the script from /sbin/rc*.d; one for the start action and one for the stop action.

3.2.3.2 Naming Conventions

The naming conventions for the link files are as follows:

The various components have the following meanings:

1. Run Level Number (2): The sequencer directory is numbered to reflect the run-level for which its contents will be executed. In this case, Start scripts in this directory will be executed upon entering run-level 2 from run-level 1, and Kill scripts will be executed upon entering run-level 2 from run-level 3.

2. Sequencing Type (S): The first character of a sequencer link name determines whether the script is executed as a start script (if the character is “S”), or as a kill script (if the character is “K”).

3. Sequence Number (060): A three digit number is used for sequencing scripts within the sequencer directory. Scripts are executed by type (start or kill) in lexicographical order.

4. Script Name (cron): Following the sequence number is the name of the start-up script. This name must be the same name as the script to which this sequencer entry is linked. In this example, the link points to /sbin/init.d/cron.

Scripts are executed in lexicographical order. The entire file name of the link is used for ordering purposes. When adding new sequencer entries, sequencer numbers are chosen to allow for gaps so that future entries may be inserted without requiring renumbering of existing entries. HP-supplied sequencer entries will all have unique numbers. (There is more information on sequence numbers in Section 3.2.5, “Link File Sequence Number Rationale and Assignment”).

Subsystems are killed in the opposite order they were started. This implies that kill scripts will generally not have the same numbers as their start script counterparts. For example, if two subsystems must be started in a given order due to dependencies (e.g., S111fubar followed by S222uses_fubar), the counterparts to these scripts must be numbered so that the subsystems are stopped in the opposite order in which they were started (e.g., K555uses_fubar followed by K777fubar).

Also, kill scripts for start scripts in directory /sbin/rcN.d reside in /sbin/rc(N-1).d. For example /sbin/rc3.d/S123foobar and /sbin/rc2.d/K654foobar might be start/kill counterparts.

	NOTE: HP-UX will continue to support short filenames (i.e. 14 characters). Because of the filename place holders for `K', `S' and the 3 digit sequence numbers, subsystem script names in /etc/init.d are restricted to 10 characters in length.

3.2.4 Run Levels and /sbin/rc

In previous HP-UX releases, /etc/rc was run only once. Now it may run several times during the execution of a system, sequencing the execution scripts when transitioning run levels. However, only the subsystems configured for execution, through configuration variables in /etc/rc.config.d, are started or stopped when transitioning the run levels.

/sbin/rc sequences the start-up and shutdown scripts in the appropriate sequencer directories in lexicographical order. Upon transition from a lower to a higher run level, the start scripts for the new run level and all intermediate levels between the old and new level are executed. Upon transition from a higher to a lower run level, the kill scripts for the new run level and all intermediate levels between the old and new level are executed.

When a system is booted to a particular run level, it will execute start-up scripts for all run levels up to and including the specified level (except run level 0). For example, if booting to run level 4, /sbin/rc looks at the old run level (S) and the new run level (4) and executes all start scripts in states 1, 2, 3, and 4. Within each level, the start scripts are sorted lexicographically and executed in that order. Each level is sorted and executed separately to ensure that the lower level subsystems are started before the higher level subsystems.

Consequently, when shutting down a system, the reverse takes place. The kill scripts are executed in lexicographical order starting at the highest run level and working down, as to stop the subsystems in the reverse order they were started. As mentioned earlier, the numbering is reversed from the start-up order.

States 0 and S are special cases. When entering state 0 or S, /sbin/rc will run start scripts in /sbin/rc0.d. Start scripts in state 0 are quick system administration scripts that prepare the system for a shutdown. When entering state S, all processes are killed and the system is in single user state. When entering state 0, the system is halted. The table below summarizes the run level definitions.

	NOTE: For run levels 1 through 6: when entering from lower state, all start scripts are executed, and when entering from higher states, all kill scripts are executed.

3.2.5 Link File Sequence Number Rationale and Assignment

To enable proper system start-up and shutdown, execution scripts must be invoked in the correct order. This is accomplished by assigning sequence numbers for the link files (e.g., S300cron) contained in the sequencer directories (i.e., /sbin/rc2.d). The HP-UX 10.x operating system and its associated products have been structured using a paradigm that groups various related functions into the same run state. This is accomplished by reserving blocks of sequence numbers for these functions. The paradigm is described in the sections below. Some entries provide examples of subsystems that are started at a particular level. Please consult an HP-UX 10.x system for a complete and accurate listing.

3.2.6 Adding Your Own Subsystems

System administrators and software product developers may have a need to add their subsystem(s) to this model. This may be easily accomplished by following a few steps.

A good place to start is with the execution script. This may be derived from any of the system execution scripts found in /sbin/init.d. There is also a blank template in /sbin/init.d/template. The guidelines for execution scripts must be strictly followed such that the interface with /sbin/rc is correctly maintained. Any failure to do so will likely cause the execution script to fail.

A configuration file should also be added to /etc/rc.config.d. This file should contain a variable assignment that enables the user or system administrator to enable or disable the particular subsystem. The file should also contain any other variable assignments required by the subsystem during start-up. The configuration file should not contain any executable script code other than variable assignments.

Selecting a run state and a sequence number should probably be done last. Many times it is difficult to determine exactly where the subsystem should fit until it has been coded and tested.

3.2.7 An Illustrative Example

Figure 6 below depicts a simple example of the start up of cron. The relationships of the files between the static and dynamic file system is also shown.

When entering run state 2 from a lower level, the 'S' scripts are executed. In the example, S700cron is a link to the cron script under /sbin/init.d. cron will start because the configuration variable in /etc/rc.config.d/cron is set to 1. A value of 0 would not start cron.

Figure 3-3 Implementing CRON in the New Model

	NOTE: S700cron is linked to /sbin/init.d/cron. /sbin contains the minimum commands to boot and mount other filesystems, and /etc contains the system configuration files.

3.2.8 Guidelines for Start-up/Shutdown Scripts

System execution scripts are installed in the /sbin/init.d directory directly from update media. Sequencer links for execution scripts are also installed into the various sequencer directories directly from update media. In the new scheme, system execution scripts are not customer editable. No provisions are made to keep newconfig versions of the scripts; any changes made by a customer to a system execution script are overwritten and lost when an update occurs.

Customers are warned of the following:

	NOTE: All HP-supplied start-up scripts are meant to be present in sequencer directories as installed. They should not be removed or renamed (to change the relative sequencing). Execution control should be performed via control variables in /etc/rc.config.d/*.