rcfgadm(1M)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ENVIRONMENT VARIABLES | EXIT STATUS | ATTRIBUTES | SEE ALSO | NOTES

NAME

rcfgadm- remote configuration administration

SYNOPSIS

rcfgadm -d domain_name [-v ] [-a] [-s listing_options] [-o hardware_options] [-l [ap_id| ap_type]]
rcfgadm -d domain_name [-v ] [-o hardware_options] -h [ap_id| ap_type]

DESCRIPTION

The rcfgadm(1M) command provides remote configuration administration operations on dynamically reconfigurable hardware resources from the system services processor (SSP). These operations include displaying status, (-l), and obtaining configuration administration help messages (-h). They are performed on attachment points, which are places where system software supports dynamic reconfiguration of hardware resources during continued operation of the Solaris operating environment.

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

Attachment points have associated state and condition information. A receptacle can exist in one of three states: empty, disconnected, or connected, while an occupant can exist in one of two states: configured or unconfigured.

The empty state is the normal state of a receptacle when the attachment point contains no occupant. A receptacle can also be in the disconnected state if its occupant is isolated from normal system access. Typically this state is used for hardware-specific testing prior to bringing the resources into full use by the system or as a step in preparing an occupant for physical removal or reconfiguration. The connected state enables normal access to hardware resources on the occupant. The connected state is the normal state of a receptacle that contains an occupant and that is not currently undergoing configuration administration operations. In the unconfigured state, the hardware resources are not exposed in the Solaris software data structures; thus, they are not available for use by the Solaris operating environment. In the configured state, hardware resources are exposed in software data structures; thus, they can be in use by the Solaris operating environment.

An attachment point can 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 nonvolatile record keeping. With a configured occupant, the attachment point can be in one of four conditions: unknown, ok, failing, failed. An attachment point can change to failing during the course of operation if a hardware-dependent recoverable error threshold is exceeded. An attachment point can change to failed as a result of an unrecoverable error. With an unconfigured occupant, an attachment point can be in any of the defined conditions. The condition can change from ok to unknown after a system-dependent time threshold.

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

The server also maintains information about in-progress state changes and condition re-evaluations. When they occur on an attachment point, they are represented as being busy in the rcfgadm output.

Attachment points are represented by hardware-specific identifiers (ap_ids) that are related to the type and location of the attachment points in the system device hierarchy. An ap_id cannot 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 path name, while a logical ap_id contains a shorthand notation that identifies an attachment point in a more user-friendly way.

BFor example, an attachment point representing slot number 7 could have a physical ap_id of /devices/central/fhc/sysctrl:SB7 while the logical ap_id could be SB7. Another example, the third receptacle on the second PCI I/O bus on a system could have a logical ap_id of pci2:plug3.

---

Example 1 Physical ap_ids




/devices/pci@71,2000/pci@2/SUNW,isptwo@4:scsi /devices/pci@71,2000/pci@2/SUNW,isptwo@4:scsi::dsk/c0t0d0 /devices/pci@71,2000/pci@2/SUNW,isptwo@4:scsi::dsk/c0t1d0 /devices/pci@71,2000/pci@2/SUNW,isptwo@4:scsi::dsk/c0t2d0 /devices/pci@71,2000/pci@2/SUNW,isptwo@4:scsi::dsk/c0t3d0 /devices/pseudo/ngdr@0:SB0 /devices/pseudo/ngdr@0:SB1 /devices/pseudo/ngdr@0:SB2 /devices/pseudo/ngdr@0:SB3

---

Attachment points can also be created dynamically. A dynamic attachment point is named relative to a base attachment point which is present in the system. ap_ids for dynamic attachment points consist of a base component followed by two colons (::) and a dynamic component. The base component is the base attachment point ap_id. The dynamic component is hardware-specific and generated by the corresponding hardware-specific library.

---

Example 2 Logical ap_ids




c0 c0::dsk/c0t0d0 c0::dsk/c0t1d0 c0::dsk/c0t2d0 c0::dsk/c0t3d0 c0::dsk/c0t4d0 c0::dsk/c0t5d0 c0::dsk/c0t6d0 SB0 SB1 SB2 SB3

---

For example, consider a base attachment point, which represents a SCSI HBA, with the physical ap_id/devices/sbus@1f,0/SUNW,fas@e,8800000:scsi and logical ap_id c0. A disk attached to this SCSI HBA could be represented by a dynamic attachment point with logical ap_id c0::dsk/c0t0d0 where c0 is the base component and dsk/c0t0d0 is the hardware-specific dynamic component. Similarly the physical ap_id for this dynamic attachment point would be:

/devices/sbus@1f,0/SUNW,fas@e,8800000:scsi::dsk/c0t0d0.

An ap_type is a partial form of a logical ap_id that can be ambiguous and not specify a particular attachment point. An ap_type is a substring of the portion of the logical ap_id, up to but not including, the colon (:) separator. For example, an ap_type of pci would show all attachment points whose logical ap_ids begin with pci.

---

Example 3 ap_types




c0 sbd

---

The use of ap_types is discouraged. The new select suboption to the -s option provides a more general and flexible mechanism for selecting attachment points. See OPTIONS.

rcfgadm interacts primarily with hardware-dependent functions contained in hardware-specific libraries and, thus, its behavior is hardware-dependent. Hardware-specific options are supplied as suboptions using the -o option.

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

OPTIONS

The following options are supported:

-a

Specifies that the -l option must also list dynamic attachment points.

-d domain_name

Specifies the ID for a domain.

-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 specified. Attachment points can be filtered by using the -s option and select suboption. Invoking rcfgadm without one of the action options is equivalent to -l without an argument. The format of the list display is controlled by the -v and -s options. When the -a option is specified, attachment points are dynamically expanded.

-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 suboptions are used to specify the attachment point selection criteria (select=select_string), the type of matching desired (match=match_type), order of 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).

When the select suboption is specified, only attachment points which match the specified criteria are listed. The select suboption has the following syntax:

rcfgadm -s select=attr1(value1):attr2(value2)...

where an attr is one of ap_id, class or type. ap_id refers to the logical ap_id field, class refers to attachment point class and type refers to the type field. value1, value2, and so on, are the corresponding values to be matched. The type of match can be specified by the match suboption as follows:

rcfgadm -s match=match_type,select=attr1(value1)...

where match_type can be either exact or partial. The default value is exact. Arguments to the select suboption can be quoted to protect them from the UNIX C shell interpretation.

A field_spec is one or more data-fields concatenated using a 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. If an attachment point has an associated class, the class field lists the class name.

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 suboptions, the fields are printed in the order requested. The order of sorting on a data-field can be reversed by placing a minus (-) before the data-field name within the field_spec for the sort suboption. The default value for sort is ap_id. The default 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 can be a string of arbitrary length. The delimiter cannot include a comma (,) character,; see getsubopt(3C). These listing options can be used to create parsable output. See NOTES.

-v

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

ENVIRONMENT VARIABLES

See environ(5) for descriptions of the following environment variables that affect the execution of command_name: LC_TIME,LC-MESSAGES,TZ.

LC_MESSAGES

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

LC_TIME

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

TZ

Specifies the time zone 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	SUNWsspop

SEE ALSO

cfgadm

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 can be manifested as an operator-initiated command, or it can be by way of an automatic configuring mechanism.

The listing option of the rcfgadm command can be used to provide parsable input for another command, for example, within a shell script. For parsable output, the -s option must be used to select the fields required. The -s option can also be used to 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.

---

Example 4 Finding the First Good Occupant of Type CPU




found=
     rcfgadm -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.

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ENVIRONMENT VARIABLES | EXIT STATUS | ATTRIBUTES | SEE ALSO | NOTES