NAME

cfgadm - configuration administration

SYNOPSIS

/usr/sbin/cfgadm [ -f ] [ -y | -n ] [ -v ] [ -o hardware_options ] [ -c function ap_id

[ ap_id . . . ]

/usr/sbin/cfgadm [ -f ] [ -y | -n ] [ -v ] [ -o hardware_options ]

-x hardware_function ap_id [ ap_id . . . ]

/usr/sbin/cfgadm [ -v ] [ -s listing_options ] [ -o hardware_options ]

[ -l [ ap_id | ap_type . . . ]]

/usr/sbin/cfgadm [ -v ] [ -o hardware_options ] -t ap_id [ ap_id . . ] /usr/sbin/cfgadm [ -v ] [ -o hardware_options ] -h [ ap_id | ap_type . . . ]

DESCRIPTION

The cfgadm command provides configuration administration operations on dynamically reconfigurable hardware resources. These operations include displaying status, ( -l ), initiating testing, ( -t ), invoking configuration state changes, ( -c ), invoking hardware specific functions, ( -x ), and obtaining configuration administration help messages ( -h ). Configuration administration is performed at attachment points which are places where system software supports dynamic reconfiguration of hardware resources during continued operation of Solaris.

Configuration administration makes a distinction between hardware resources that are physically present in the machine and hardware resources that are configured and visible to Solaris. The nature of configuration administration functions are hardware specific, and are performed by calling hardware specific libraries.

Configuration administration operates on an attachment point. Hardware resources located at attachment points may or may not be physically replaceable during system operation, but are dynamically reconfigurable by way of the configuration administration interfaces. Attachment points are represented in the device tree by a unique nodetype (DDI_NT_ATTACHMENT_POINT ).

An attachment point defines two unique elements, which are distinct from the hardware resources that exist beyond the attachment point. The two elements of an attachment point are a receptacle and an occupant. Physical insertion or removal of hardware resources occurs at attachment points and results in a receptacle gaining or losing an occupant. Configuration administration supports the physical insertion and removal operations as well as other configuration administration functions at an attachment point.

Attachment points have associated state and condition information. The configuration administration interfaces provide control for transitioning attachment point states. A receptacle can exist in one of three states: empty, disconnected or connected, while an occupant exist in one of two states: configured or unconfigured.

A receptacle must provide the empty state, which is the normal state of a receptacle when the attachment point has no occupants. A receptacle may provide the disconnected state if it has the capability of isolating its occupants from normal system access. Typically this state is used for various hardware specific testing prior to bringing the occupant's resources into full use by the system, or as a step in preparing an occupant for physical removal or reconfiguration. A receptacle in the disconnected state isolates its occupant

from the system as much as its hardware allows, but may provide access for testing and setup. A receptacle must provide the connected state, which allows normal access to hardware resources contained on any occupants. The connected state is the normal state of a receptacle that contains an occupant and that is not currently undergoing configuration administration operations.

The hardware resources contained on an occupant in the unconfigured state are not represented by normal Solaris data structures (such as device tree nodes) and are thus not available for use by Solaris. Operations allowed on an unconfigured occupant are limited to configuration administration operations. The hardware resources of an occupant in the configured state are represented by normal Solaris data structures and thus some or all of those hardware resources may be in use by Solaris. An occupant is required to provide both the configured and unconfigured states,

An attachment point may be in one of five conditions: unknown, ok, failing, failed, or unusable. An attachment point can enter the system in any condition depending upon results of power-on tests and non-volatile record keeping.

An attachment point with an occupant in the configured state is in one of four conditions: unknown, ok, failing, or failed. If the condition is not failing or failed an attachment point may change to failing during the course of operation if a hardware dependent recoverable error threshold is exceeded. If the condition is not failed an attachment point may change to failed during operation as a result of an unrecoverable error.

An attachment point with an occupant in the unconfigured state can be in any of the defined conditions. The condition of an attachment point with an unconfigured occupant may decay from ok to unknown after a machine dependent time threshold. Initiating a test function changes the attachment point's condition to ok, failing or failed depending on the outcome of the test. An attachment point that does not provide a test function may leave the attachment point in the unknown condition. If a test is interrupted, the attachment point's condition may be set to the previous condition, unknown or failed. An attachment point in the unknown, ok, failing, or failed conditions can be re-tested.

An attachment point may exist in the unusable condition for a variety of reasons, such as inadequate power or cooling for the receptacle, an occupant that is unidentifiable, unsupported, incorrectly configured, etc. An attachment point in the unusable condition can never be used by the system. It typically remains in this condition until the physical cause is remedied.

An attachment point also maintains busy information that indicates when a state change is in progress or the condition is being reevaluated.

Attachment points are referred to using hardware specific identifiers (ap_id) that are related to the type and location of the attachment points in the system device hierarchy. An ap_id may not be ambiguous, it must identify a single attachment point. Two types of ap_id specifications are supported: physical and logical. A physical ap_id contains a fully specified pathname, while a logical ap_id contains a shorthand notation to identify an attachment point in a more user-friendly way. Both types of ap_ids share a common format, with the name and instance forming the initial part followed by a colon (: )and the

specific attachment point name. For example, a receptacle representing a system's backplane slot number 7 might have a physical ap_id of /central/fhc/sysctrl:slot7 while the logical ap_id might be system:slot7. Another example, the third receptacle on the second PCI I/O bus on a system might have a logical ap_id of pci2:plug3.

The cfgadm command parses an ap_id and uses the name portion to locate and dynamically load the hardware specific library that supports that type of attachment point. The hardware specific libraries are located by searching the device tree for node of type DDI_NT_ATTACHMENT_POINT .The nodename is used to search for a hardware specific library, named lib${name}.so.1 first in /usr/platform/${machine}/lib/cfgadm/, then in /usr/platform/${arch}/lib/cfgadm/, and lastly in /usr/lib/cfgadm/. Failing that the same search is conducted using the driver name. The ap_id is passed on to the hardware specific library to perform operations. The hardware specific library validates that the ap_id is complete and identifies a single attachment point to operate on.

An ap_type is a partial form of an ap_id that may be ambiguous and not specify a particular attachment point. The ap_type is used by the list function to allow listing of all attachment points of the same type, and by the help operation to request help on attachment points of that type. It consists of the name portion of an ap_id and may omit the instance, the colon separator and the specific attachment point identifier. For example, an ap_type of pci would show all attachment points whose nodenames or driver names contain pci.

The cfgadm command parses an ap_type and uses the name portion to locate and dynamically load the hardware specific libraries that supports attachment points of that type. The ap_type is passed to the hardware specific library to perform listing operations.

The cfgadm command interacts primarily with hardware dependent functions contained in hardware specific libraries and thus its behavior is hardware dependent.

For each configuration administration operation a service interruption may be required. Should the completion of the function requested require a noticeable service interruption to interactive users, a prompt is output on the standard error output for confirmation on the standard input before the function is started. Confirmation can be overridden using the -y or -n options to always answer yes or no respectively. Hardware specific options, such as test level, are supplied as sub-options using the -o option.

Operations that change the state of the system configuration are audited by the system log daemon syslogd (1M).

The arguments for this command conform to the getopt(3C) and getsubopt(3C) syntax convention.

OPTIONS

The following options are supported:

-c function

Performs the state change function on the attachment point specified by ap_id.

Specify function as insert, remove, disconnect, connect, configure or unconfigure . These functions cause state transitions at the attachment point by calling hardware specific library routines and are defined in the following list.

insert

Performs operations that allows the user to manually

insert an occupant or to activate a hardware supplied

mechanism that performs the physical insertion. insert

may have hardware specific side effects that tem-

porarily suspend activity in portions of the system. In

such cases the hardware specific library generates

appropriate warning messages and informs the user of

any special considerations or procedures unique to that

hardware. Various hardware specific errors may cause

this function to fail and set the receptacle condition to

unusable.

remove

Performs operations that allow the user to manually

remove an occupant or to activate a hardware supplied

mechanism to perform the physical removal. remove

may have hardware specific side effects that tem-

porarily suspend activity in portions of the system. In

such cases the hardware specific library generates

appropriate warning messages and informs the user of

any special considerations or procedures unique to that

hardware. Various hardware specific errors may cause

this function to fail and set the receptacle condition to

unusable.

disconnect

Performs hardware specific operations to put a recepta-

cle in the disconnected state, which may prevent an

occupant from operating in a normal fashion through

the receptacle.

connect

Performs hardware specific operations to put the

receptacle in the connected state, which allows an

occupant to operate in a normal fashion through the

receptacle.

configure

Performs hardware specific operations that allow an

occupant's hardware resources to be usable by Solaris.

Occupants that are configured are part of the system

configuration and are available for manipulation by

Solaris device manipulation maintenance commands

(eg: psradm(1M), mount (1M),ifconfig (1M)).

unconfigure Performs hardware specific operations that logically

remove an occupant's hardware resources from the

system. The occupant must currently be configured

and its hardware resources must not be in use by

Solaris.

State transition functions may fail due to the condition of the attachment point or other hardware dependent considerations. All state

change functions in the direction of adding resources, (insert, connect and configure) are passed onto the hardware specific library when the attachment point is in the ok or unknown condition. All other conditions require the use of the force option to allow these functions to be passed on to the hardware specific library. Attachment point condition does not prevent a hardware specific library being called for related to the removal functions related to the removal (remove, disconnect and unconfigure), of hardware resources from the system. Hardware specific libraries may reject state change functions if the attachment point is in the unknown condition.

The condition of an attachment point is not necessarily changed by the state change functions, however errors during state change operations can change the attachment point condition. An attempt to override a condition and force a state change that would otherwise fail can be made by specifying the force option (-f). Hardware specific safety and integrity checks may prevent the force option from having any effect.

-f

Forces the specified action to occur. Typically, this is a hardware dependent override of a safety feature. Forcing a state change operation may allow use of the hardware resources of occupant that is not in the ok or unknown conditions, at the discretion of any hardware dependent safety checks.

-h [ap_id | ap_type . . . ]

Prints out the help message text. If ap_id or ap_type is specified, the help routine of the hardware specific library for the attachment point indicated by the argument is called.

-l [ap_id | ap_type . . . ]

Lists the state and condition of attachment points. If ap_id or ap_type is specified, the listing is limited to attachment points indicated by the argument is called. If ap_id is specified, the listing is limited to those particular attachment points. Invoking cfgadm without one of the action options is equivalent to -l without an ap_id or an ap_type argument. The format of the display is controlled by the -v and -s options.

-n

Suppress any interactive confirmation and assume that the answer is no. If neither -n or -y is specified, interactive confirmation is obtained through the standard error output and the standard input. If either of these standard channels does not correspond to a terminal (as determined by isatty(3C)) then the -n option is assumed.

-o hardware_options Supplies hardware specific options to the main command option.

The format and content of the hardware option string is completely hardware specific. The option string hardware_options conforms to the getsubopt(3C) syntax convention.

-s listing_options

Supplies listing options to the list (-l) command. listing_options conforms to the getsubopt(3C) syntax convention. The sub-options are used to control the order of the listing (sort=field_spec), the data that is displayed (cols=field_spec and cols2=field_spec), the column delimiter (delim=string) and whether to suppress column headings (noheadings). A field_spec is one or more data-fields concatenated using : (colon) as in data-field: data-field: data-field. A data-field is one of ap_id, physid, r_state, o_state, condition, type ,busy, status_time, status_time_p and info. The ap_id field output is the logical name for the attachment point, while the physid field contains the physical name. The r_state field can be empty, disconnected or connected. The o_state field can be configured or unconfigured. The busy field can be either y if the attachment point is busy, or n if it is not. The type and info fields are hardware specific. The status_time_p field is a parsable version of the status_time field.

The order of the fields in field_spec is significant: For the sort suboption, the first field given is the primary sort key. For the cols and cols2 sub-options, the fields are printed in the order requested. The order of sorting on a data-field may be reversed by placing a -(minus) before the data-field name within the field_sec for the sort sub-option. The default value for sort is ap_id. The defaults values for cols and cols2 depend on whether the -v option is given: Without it cols is ap_id:r_state:o_state:condition and cols2 is not set. With -v cols is ap_id:r_state:o_state:condition:info and cols2 is status_time:type:busy:physid:. The default value for delim is a single space. The value of delim may be a string of arbitrary length. The delimiter cannot include comma character, see getsubopt(3C). These listing options may be used to create parsable output. See NOTES.

-t

Performs a test of one or more attachment points. The test function is used to re-evaluate the condition of the attachment point. Without a test level specifier in hardware_options, the fastest test that identifies hard faults is used.

More comprehensive tests are hardware specific and are selected using the hardware_options.

The results of the test is used to update the condition of the specified occupant to either ok if no faults are found, failing if recoverable faults are found or failed if any unrecoverable faults are found.

If a test is interrupted, the attachment point's condition may be restored to its previous value or set to unknown if no errors were found or failing if only recoverable errors were found or to failed if any unrecoverable errors were found. The attachment point should only be set to ok upon normal completion of testing with no errors.

-v

Executes in verbose mode. For the -c, -t and -x options output a message giving the results of each attempted operation. For the -h option output detailed help information. For the -l option output full information for each attachment point.

-x hardware_function

Performs hardware specific functions. Private hardware specific functions should not normally change the state of a receptacle or occupant. Attachment point conditions may change as the result of errors encountered during private hardware specific functions. The format and content of the hardware_function string is completely hardware specific. The option string hardware_function conforms to the getsubopt(3C) syntax convention.

-y

Suppresses any interactive confirmation and assume that the answer is yes.

USAGE

The required privileges to use this command are hardware dependent. Typically, a default system configuration restricts all but the list option to the superuser.

EXAMPLES

The following example lists current configurable hardware information:

example# cfgadm
   Ap_Id         Receptacle       Occupant         Cond

system:slot0

connected

configured

ok

system:slot1   connected        configured        ok
system:slot2   connected        configured        ok
system:slot3   connected        unconfigured      unknown
system:slot4   connected        configured        failing
system:slot5   connected        configured        ok
system:slot6   disconnected     unconfigured      unusable
system:slot7   empty            unconfigured      ok

The following example lists current configurable hardware information in verbose mode:

example# cfgadm -v -l system

Status of system configuration at Wed Nov 13 17:26:17 PST 1996

   Ap_Id         Receptacle       Occupant         Cond                   Info
                   When             Type           Busy                 Physid

system:slot0

connected

configured

ok

SUNW,UltraSPARC ,168MH z

               Nov 5           CPU              n             /central/fhc/sysctrl:slot0
system:slot1   connected        configured        ok           512mb, 2 way interleaved
               Nov 5           MEMORY           n             /central/fhc/sysctrl:slot1
system:slot2   connected        configured        ok           PCI
               Nov 5           IO               n             /central/fhc/sysctrl:slot2
system:slot3   connected        unconfigured      unknown      512mb, 2 way interleaved
               Nov 5           MEMORY           y             /central/fhc/sysctrl:slot3
system:slot4   connected        configured        failing      512mb, 2 way interleaved
               Nov 5           MEMORY           n             /central/fhc/sysctrl:slot4
system:slot5   connected        configured        ok           PCI
               Nov 5           IO               n             /central/fhc/sysctrl:slot5
system:slot6   disconnected     unconfigured      unusable     unsupported option
               Nov 5                            n             /central/fhc/sysctrl:slot6
system:slot7   empty            unconfigured      ok
               Nov 5                            n             /central/fhc/sysctrl:slot7

The following example tests two occupants using the hardware specific extended test:

example# cfgadm -v -o extended -t system:slot3 system:slot5
Testing attachment point system:slot3 ... ok
Testing attachment point system:slot5 ... ok

The following example configures an occupant in the failing state to the system using the force option:

example# cfgadm -f -c configure system:slot3

The following example unconfigures an occupant from the system:

example# cfgadm -c unconfigure system:slot4

ENVIRONMENT

See environ(5) for descriptions of the following environment variables that affect the execution of cfgadm: LC_TIME ,LC_MESSAGES ,NLSPATH and TZ .

LC_MESSAGES

Determines how cfgadm displays column headings and error messages. Listing output data is not affected by the setting of this variable.

LC_TIME

Determines how cfgadm displays human readable status changed time (status_time).

TZ

Specifies the timezone used when converting the status changed time. This applies to both the human readable (status_time) and

parsable (status_time_p) formats.

EXIT STATUS

The following exit values are returned:

0

Successful completion.

1

An error occurred.

2

Configuration administration not supported on specified target.

3

Usage error.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWcsu

SEE ALSO

ifconfig (1M),mount (1M),prtdiag(1M), psradm(1M), syslogd (1M),config_admin(3X), getopt(3C), getsubopt(3C), isatty(3C), attributes(5), environ(5),

DIAGNOSTICS

Diagnostic messages appear on the standard error output. Other than options and usage errors, the following may be seen:

cfgadm: Configuration administration not supported on ap_id
cfgadm: No library found for ap_id
cfgadm: ap_id is ambiguous
cfgadm: operation: Insufficient privileges
cfgadm: Attachment point is busy, try again
cfgadm: System is busy, try again
cfgadm: operation: Operation requires a service interruption
cfgadm: operation: Data error: error_text
cfgadm: operation: Hardware specific failure: error_text

See config_admin(3X) for additional details regarding error messages.

NOTES

Hardware resources enter the unconfigured pool in a hardware specific manner. This can occur at various times such as: system initialization or as a result of an unconfigure operation. An occupant that is in the unconfigured state is not available for use by the system until specific intervention occurs. This intervention may be manifested as an operator initiated command or it may be by way of an automatic configuring mechanism.

The listing option of the cfgadm command can be used to provide parsable input for another command, for example within a shell script. The -s option can be used to select the fields required and suppress the column headings. The following fields always produce parsable output: ap_id, physid, r_state, o_state, condition, busy status_time_p and type . Parsable output never has white-space characters embedded in the field value.

The following shell script fragment finds the first good unconfigured occupant of type CPU .

found=
cfgadm -l -s "noheadings,cols=ap_id:r_state:condition:type" | \

while read ap_id r_state cond type
do
        if [ "$r_state" = unconfigured -a "$cond" = ok -a "$type" = CPU ]
        then
                if [ -z "$found" ]
                then
                        found=$ap_id
                fi
        fi
done
if [ -n "$found" ]
then
        echo "Found CPU $found"
fi

The format of the parsable time field (status_time_p) is YYYYMMDDhhmmss, giving the year, month, day, hour, minute and second in a form suitable for string comparison.

Reference should be made to the hardware specific documentation for details of System Configuration Administration support.