The System Resource Controller (SRC) defines and manages three object classes:
Together, these object classes represent the domain in which the SRC performs its functions. A predefined set of object-class descriptors comprise the possible set of subsystem configurations supported by the SRC.
Note: Only the SRC Subsystem object class is required. Use of the Subserver Type and Notify object classes is subsystem-dependent.
The Subsystem, Subserver, and Notify Object Definition figure illustrates the relationship between SRC objects.
The subsystem object class contains the descriptors for all SRC subsystems. A subsystem must be configured in this class before it can be recognized by the SRC.
The descriptors for the Subsystem object class are defined in the SRCsubsys structure of the /usr/include/sys/srcobj.h file. The Subsystem Object Descriptors and Default Values table provides a short-form illustration of the subsystem descriptors as well as the mkssys and chssys command flags associated with each descriptor.
| Subsystem Object Descriptors and Default Values | ||
| Descriptors | Default Values | Flags |
| Subsystem name | -s | |
| Path to subsystem command | -p | |
| Command arguments | -a | |
| Execution priority | 20 | -E |
| Multiple instance | NO | -Q -q |
| User ID | -u | |
| Synonym name (key) | -t | |
| Start action | ONCE | -O -R |
| stdin | /dev/console | -i |
| stdout | /dev/console | -o |
| stderr | /dev/console | -e |
| Communication type | Sockets | -K -I -S |
| Subsystem message type | -m | |
| Communication IPC queue key | -l | |
| Group name | -G | |
| SIGNORM signal | -n | |
| SIGFORCE signal | -f | |
| Display | Yes | -D -d |
| Wait time | 20 seconds | -w |
| Auditid | ||
The subsystem object descriptors are defined as follows:
| Subsystem name | Specifies the name of the subsystem object. The name cannot exceed 30 bytes, including the null terminator (29 characters for single-byte character sets, or 14 characters for multibyte character sets). This descriptor must be POSIX-compliant. This field is required. |
| Subsystem command path | Specifies the full path name for the program executed by the subsystem start command. The path name cannot exceed 200 bytes, including the null terminator (199 characters for single-byte character sets, or 99 characters for multibyte character sets). The path name must be POSIX-compliant. This field is required. |
| Command arguments | Specifies any arguments that must be passed to the command that starts the subsystem. The arguments cannot exceed 200 bytes, including the null terminator (199 characters for single-byte character sets, or 99 characters for multibyte character sets). The arguments are parsed by the srcmstr daemon according to the same rules used by shells. For example, quoted strings are passed as a single argument, and blanks outside quoted strings delimit arguments. |
| Execution priority | Specifies the process priority of the subsystem to be run. Subsystems started by the srcmstr daemon run with this priority. The default value is 20. |
| Multiple instance | Specifies the number of instances of a subsystem that can run at one time. A value of NO (the -Q flag) specifies that only one instance of the subsystem can run at one time. Attempts to start this subsystem if it is already running will fail, as will attempts to start a subsystem on the same IPC message queue key. A value of YES (the -q flag) specifies that multiple subsystems may use the same IPC message queue and that there can be multiple instances of the same subsystem. The default value is NO. |
| User ID | Specifies the user ID (numeric) under which the subsystem is run. A value of 0 indicates the root user. |
| Synonym name | Specifies a character string to be used as an alternate name for the subsystem. The character string cannot exceed 30 bytes, including the null terminator (29 characters for single-byte character sets, or 14 characters for multibyte character sets). This field is optional. |
| Start action | Specifies whether the srcmstr daemon should restart the subsystem after an abnormal end. A value of RESPAWN (the -R flag) specifies the srcmstr daemon should restart the subsystem. A value of ONCE (the -O flag) specifies the srcmstr daemon should not attempt to restart the failed system. There is a respawn limit of two restarts within a specified wait time. If the failed subsystem cannot be successfully restarted, the notification method option is consulted. The default value is ONCE. |
| Standard Input File/Device | Specifies the file or device from which the subsystem receives its input. The default is /dev/console. This field cannot exceed 200 bytes, including the null terminator (199 characters for single-byte character sets, or 99 characters for multibyte character sets). This field is ignored if the communication type is sockets. |
| Standard Output File/Device | Specifies the file or device to which the subsystem sends its output. This field cannot exceed 200 bytes, including the null terminator (199 characters for single-byte character sets, or 99 characters for multibyte character sets). The default is /dev/console. |
| Standard Error File/Device | Specifies the file or device to which the subsystem writes its error messages. This field cannot exceed 200 bytes, including the null terminator (199 characters for single-byte character sets, or 99 characters for multibyte character sets). Failures are handled as part of the notify method. The default is /dev/console.
Note: Catastrophic errors are sent to the error log. |
| Communication type | Specifies the communication method between the srcmstr daemon and the subsystem. Three types can be defined: IPC (-I), sockets (-K), or signals (-S). The default is sockets. |
| Communication IPC queue key | Specifies a decimal value that corresponds to the IPC message queue key that the srcmstr daemon uses to communicate to the subsystem. This field is required for subsystems that communicate using IPC message queues. Use the ftok subroutine with a fully qualified path name and an ID parameter to ensure that this key is unique. The srcmstr daemon creates the message queue prior to starting the subsystem. |
| Group name | Designates the subsystem as a member of a group. This field cannot exceed 30 bytes, including the null terminator (29 characters for single-byte character sets, or 14 characters for multibyte character sets). This field is optional. |
| Subsystem message type | Specifies the mtype of the message that is placed on the subsystem's message queue. The subsystem uses this value to retrieve messages by using the msgrcv or msgxrcv subroutine. This field is required if you are using message queues. |
| SIGNORM signal value | Specifies the value to be sent to the subsystem when a stop normal request is sent. This field is required of subsystems using the signals communication type. |
| SIGFORCE signal value | Specifies the value to be sent to the subsystem when a stop force request is sent. This field is required of subsystems using the signals communication type. |
| Display value | Indicates whether the status of an inoperative subsystem can be displayed on lssrc -a or lssrc -g output. The -d flag indicates display; the -D flag indicates do not display. The default is -d (display). |
| Wait time | Specifies the time in seconds that a subsystem has to complete a restart or stop request before alternate action is taken. The default is 20 seconds. |
| Auditid | Specifies the subsystem audit ID. Created automatically by the srcmstr daemon when a subsystem is defined, this field is used by the security system, if configured. This field cannot be set or changed by a program. |
See "Defining Your Subsystem to the SRC" for information on defining and modifying subsystem objects.
An object must be configured in this class if a subsystem has subservers and the subsystem expects to receive subserver-related commands from the srcmstr daemon.
This object class contains three descriptors, which are defined in the SRCsubsvr structure of the srcobj.h file:
| Subserver ID (key) | Specifies the name of the subserver type object identifier. The set of subserver type names defines the allowable values for the -t flag of the subserver commands. The name length cannot exceed 30 bytes, including the terminating null (29 characters for single-byte character sets, or 14 characters for multibyte character sets). |
| Owning subsystem name | Specifies the name of the subsystem that owns the subserver object. This field is defined as a link to the SRC subsystem object class. |
| Code point | Specifies a decimal number that identifies the subserver. The code point is passed to the subsystem controlling the subserver in the object field of the subreq structure of the SRC request structure. If a subserver object name is also provided in the command, the srcmstr daemon forwards the code point to the subsystem in the objname field of the subreq structure. See the "SRC Request Structure Example" in the spc.h file documentation for examples of these elements. |
The commands that reference subservers identify each subserver as a named type of subserver and can also append a name to each instance of a subserver type. The SRC daemon uses the subserver type to determine the controlling subsystem for the subserver, but does not examine the subserver name.
See "Defining Your Subsystem to the SRC" for information on defining and modifying subserver type objects.
This class provides a mechanism for the srcmstr daemon to invoke subsystem-provided routines when the failure of a subsystem is detected. When the SRC daemon receives a SIGCHLD signal indicating the termination of a subsystem process, it checks the status of the subsystem (maintained by the srcmstr daemon) to determine if the termination was caused by a stopsrc command. If no stopsrc command was issued, the termination is interpreted as an abnormal termination. If the restart action in the definition does not specify respawn, or if respawn attempts fail, the srcmstr daemon attempts to read an object associated with the subsystem name from the Notify object class. If such an object is found, the method associated with the subsystem is run.
If no subsystem object is found in the Notify object class, the srcmstr daemon determines whether the subsystem belongs to a group. If so, the srcmstr daemon attempts to read an object of that group name from the Notify object class. If such an object is found, the method associated with it is invoked. In this way, groups of subsystems can share a common method.
Note: The subsystem notify method takes precedence over the group notify method. Therefore, a subsystem can belong to a group that is started together, but still have a specific recovery or cleanup routine defined.
Notify objects are defined by two descriptors:
Such notification is useful when specific recovery or clean-up work needs to be performed before a subsystem can be restarted. It is also a tool for information gathering to determine why a subsystem abnormally stopped.
Notify objects are created with the mknotify command. To modify a notify method, the existing notify object must be removed using the rmnotify command, and then a new notify object created.
| mknotify | Adds a notify method to the SRC configuration database |
| rmnotify | Removes a notify method from the SRC configuration database |
The srcmstr daemon logs subsystem recovery activity. The subsystem is responsible for reporting subsystem failures.
System Resource Controller (SRC) Overview for Programmers
Understanding SRC Communication Types
Defining Your Subsystem to the SRC
mkssys command, mkserver command, mknotify command, rmnotify command
defssys subroutine, addssys subroutine
