System Administration Commands cfgadm(1M)
NAME
cfgadm - configuration administration
SYNOPSIS
/usr/sbin/cfgadm [-f] [-y -n] [-v] [-o hardwareoptions]
-c function apid...
/usr/sbin/cfgadm [-f] [-y -n] [-v] [-o hardwareoptions]
-x hardwarefunction apid...
/usr/sbin/cfgadm [-v] [-a] [-s listingoptions]
[-o hardwareoptions] [-l [apid aptype]
/usr/sbin/cfgadm [-v] [-o hardwareoptions] -t apid...
/usr/sbin/cfgadm [-v] [-o hardwareoptions] -h
[apid aptype]
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). Configura-
tion administration is performed at attachment points, which
are places where system software supports dynamic reconfi-
guration 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 visi-
ble to Solaris. The nature of configuration administration
functions are hardware specific, and are performed by cal-
ling hardware specific libraries.
Configuration administration operates on an attachment
point. Hardware resources located at attachment points can
or can not be physically replaceable during system opera-
tion, but are dynamically reconfigurable by way of the con-
figuration administration interfaces.
SunOS 5.11 Last change: 25 Oct 2004 1
System Administration Commands cfgadm(1M)
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 infor-
mation. The configuration administration interfaces provide
control for transitioning attachment point states. A recep-
tacle can exist in one of three states: empty, disconnected
or connected, while an occupant can exist in one of two
states: configured or unconfigured.
A receptacle can provide the empty state, which is the nor-
mal state of a receptacle when the attachment point has no
occupants. A receptacle can also 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 recon-
figuration. A receptacle in the disconnected state isolates
its occupant from the system as much as its hardware allows,
but can 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 con-
nected state is the normal state of a receptacle that con-
tains an occupant and that is not currently undergoing con-
figuration administration operations.
The hardware resources contained on an occupant in the
unconfigured state are not represented by normal Solaris
data structures 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 can be in use by
Solaris. All occupants provide both the configured and
unconfigured states,
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
SunOS 5.11 Last change: 25 Oct 2004 2
System Administration Commands cfgadm(1M)
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 attach-
ment point can change to failing during the course of opera-
tion if a hardware dependent recoverable error threshold is
exceeded. If the condition is not failed an attachment point
can 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 can
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 pro-
vide a test function can leave the attachment point in the
unknown condition. If a test is interrupted, the attachment
point's condition can 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 can 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 condi-
tion is being reevaluated.
Attachment points are referred to using hardware specific
identifiers (apids) that are related to the type and loca-
tion of the attachment points in the system device hierar-
chy. An apid can not be ambiguous, it must identify a sin-
gle attachment point. Two types of apid specifications are
supported: physical and logical. A physical apid contains a
fully specified pathname, while a logical apid contains a
shorthand notation that identifies an attachment point in a
more user-friendly way.
SunOS 5.11 Last change: 25 Oct 2004 3
System Administration Commands cfgadm(1M)
For example, an attachment point representing a system's
backplane slot number 7 could have a physical apid of
/devices/central/fhc/sysctrl:slot7 while the logical apid
could be system:slot7. Another example, the third receptacle
on the second PCI I/O bus on a system could have a logical
apid of pci2:plug3.
Attachment points may also be created dynamically. A dynamic
attachment point is named relative to a base attachment
point which is present in the system. apids 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 apid. The dynamic component is
hardware specific and generated by the corresponding
hardware specific library.
For example, consider a base attachment point, which
represents a SCSI HBA, with the physical apid
/devices/sbus@1f,0/SUNW,fas@e,8800000:scsi and logical apid
c0 . A disk attached to this SCSI HBA could be represented
by a dynamic attachment point with logical apid
c0::dsk/c0t0d0 where c0 is the base component and dsk/c0t0d0
is the hardware specific dynamic component. Similarly the
physical apid for this dynamic attachment point would be:
/devices/sbus@1f,0/SUNW,fas@e,8800000:scsi::dsk/c0t0d0
An aptype is a partial form of a logical apid that can be
ambiguous and not specify a particular attachment point. An
aptype is a substring of the portion of the logical apid
up to but not including the colon (:) separator. For exam-
ple, an aptype of pci would show all attachment points
whose logical apids begin with pci.
The use of aptypes is discouraged. The new select sub-
option to the -s option provides a more general and flexible
mechanism for selecting attachment points. See OPTIONS.
The cfgadm command interacts primarily with hardware depen-
dent functions contained in hardware specific libraries and
thus its behavior is hardware dependent.
For each configuration administration operation a service
interruption can 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
SunOS 5.11 Last change: 25 Oct 2004 4
System Administration Commands cfgadm(1M)
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:
-a
Specifies that the -l option must also list dynamic
attachment points.
-cfunction
Performs the state change function on the attachment
point specified by apid.
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 follow-
ing 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 can have hardware specific side
effects that temporarily 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. Vari-
ous hardware specific errors can cause
this function to fail and set the recep-
tacle condition to unusable.
remove Performs operations that allow the user
to manually remove an occupant or to
activate a hardware supplied mechanism to
SunOS 5.11 Last change: 25 Oct 2004 5
System Administration Commands cfgadm(1M)
perform the physical removal. remove can
have hardware specific side effects that
temporarily 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 can cause this function
to fail and set the receptacle condition
to unusable.
disconnect Performs hardware specific operations to
put a receptacle in the disconnected
state, which can 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. Occu-
pants that are configured are part of the
system configuration and are available
for manipulation by Solaris device mani-
pulation 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 can fail due to the condition
of the attachment point or other hardware dependent con-
siderations. 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
SunOS 5.11 Last change: 25 Oct 2004 6
System Administration Commands cfgadm(1M)
specific library. Attachment point condition does not
prevent a hardware specific library being called for
related to the removal (remove, disconnect and unconfig-
ure), of hardware resources from the system. Hardware
specific libraries can 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 can 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. Forc-
ing a state change operation can 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 [apid aptype ... ]
Prints out the help message text. If apid or aptype is
specified, the help routine of the hardware specific
library for the attachment point indicated by the argu-
ment is called.
-l [apid aptype ... ]
Lists the state and condition of attachment points
specified. Attachment points can be filtered by using
the -s option and select sub-option. Invoking cfgadm
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.
-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 stan-
dard error output and the standard input. If either of
SunOS 5.11 Last change: 25 Oct 2004 7
System Administration Commands cfgadm(1M)
these standard channels does not correspond to a termi-
nal (as determined by isatty(3C)) then the -n option is
assumed.
-ohardwareoptions
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 hardwareoptions conforms to the getsubopt(3C)
syntax convention.
-slistingoptions
Supplies listing options to the list (-l) command.
listingoptions conforms to the getsubopt(3C) syntax
convention. The sub-options are used to specify the
attachment point selection criteria (
select=selectstring), the type of matching desired
(match=matchtype), order of listing (sort=fieldspec),
the data that is displayed (cols=fieldspec and
cols2=fieldspec), the column delimiter (delim=string)
and whether to suppress column headings (noheadings).
When the select sub-option is specified, only attachment
points which match the specified criteria will be
listed. The select sub-option has the following syntax:
cfgadm -s select=attr1(value1):attr2(value2)...
where an attr is one of apid, class or type. apid
refers to the logical apid field, class refers to
attachment point class and type refers to the type
field. value1, value2, etc. are the corresponding values
to be matched. The type of match can be specified by the
match sub-option as follows:
cfgadm -s match=matchtype,select=attr1(value1)...
where matchtype can be either exact or partial. The
default value is exact.
Arguments to the select sub-option can be quoted to pro-
tect them from the shell.
A fieldspec is one or more data-fields concatenated
using colon (:), as in data-field:data-field:data-field.
A data-field is one of apid, physid, rstate, ostate,
SunOS 5.11 Last change: 25 Oct 2004 8
System Administration Commands cfgadm(1M)
condition, type, busy, statustime, statustimep,
class, and info. The apid field output is the logical
name for the attachment point, while the physid field
contains the physical name. The rstate field can be
empty, disconnected or connected. The ostate 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
statustime field provides the time at which either the
rstate, ostate, or condition of the attachment point
last changed. The statustimep field is a parsable ver-
sion of the statustime field. If an attachment point
has an associated class, the class field lists the class
name. If an attachment point does not have an associated
class, the class field lists none.
The order of the fields in fieldspec is significant:
For the sort sub-option, 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 can be reversed by placing a
minus (-) before the data-field name within the
fieldsec for the sort sub-option. The default value for
sort is apid. The defaults values for cols and cols2
depend on whether the -v option is given: Without it
cols is apid:rstate:ostate:condition and cols2 is not
set. With -v cols is
apid:rstate:ostate:condition:info and cols2 is
statustime: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
comma (,) character, see getsubopt(3C). These listing
options can 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
hardwareoptions, the fastest test that identifies hard
faults is used.
More comprehensive tests are hardware specific and are
selected using the hardwareoptions.
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.
SunOS 5.11 Last change: 25 Oct 2004 9
System Administration Commands cfgadm(1M)
If a test is interrupted, the attachment point's condi-
tion can 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 unre-
coverable 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
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.
-xhardwarefunction
Performs hardware specific functions. Private hardware
specific functions can change the state of a receptacle
or occupant. Attachment point conditions can change as
the result of errors encountered during private hardware
specific functions. The format and content of the
hardwarefunction string is completely hardware
specific. The option string hardwarefunction 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 res-
tricts all but the list option to the superuser.
EXAMPLES
Example 1 Listing Attachment Points in the Device Tree
The following example lists all attachment points except
dynamic attachment points.
example# cfgadm
ApId Type Receptacle Occupant Cond
SunOS 5.11 Last change: 25 Oct 2004 10
System Administration Commands cfgadm(1M)
system:slot0 cpu/mem connected configured ok
system:slot1 sbus-upa connected configured ok
system:slot2 cpu/mem connected configured ok
system:slot3 unknown connected unconfigured unknown
system:slot4 dual-sbus connected configured failing
system:slot5 cpu/mem connected configured ok
system:slot6 unknown disconnected unconfigured unusable
system:slot7 unknown empty unconfigured ok
c0 scsi-bus connected configured unknown
c1 scsi-bus connected configured unknown
Example 2 Listing All Configurable Hardware Information
The following example lists all current configurable
hardware information, including those represented by dynamic
attachment points:
example# cfgadm -al
ApId Type Receptacle Occupant Cond
system:slot0 cpu/mem connected configured ok
system:slot1 sbus-upa connected configured ok
system:slot2 cpu/mem connected configured ok
system:slot3 unknown connected unconfigured unknown
system:slot4 dual-sbus connected configured failing
system:slot5 cpu/mem connected configured ok
system:slot6 unknown disconnected unconfigured unusable
system:slot7 unknown empty unconfigured ok
c0 scsi-bus connected configured unknown
c0::dsk/c0t14d0 disk connected configured unknown
c0::dsk/c0t11d0 disk connected configured unknown
c0::dsk/c0t8d0 disk connected configured unknown
c0::rmt/0 tape connected configured unknown
c1 scsi-bus connected configured unknown
Example 3 Listing Selectively, Based on Attachment Point
Attributes
The following example lists all attachment points whose
class begins with scsi, apid begins with c and type field
begins with scsi. The argument to the -s option is quoted to
protect it from the shell.
example# cfgadm -s "match=partial,select=class(scsi):apid(c):type(scsi)"
SunOS 5.11 Last change: 25 Oct 2004 11
System Administration Commands cfgadm(1M)
ApId Type Receptacle Occupant Cond
c0 scsi-bus connected configured unknown
c1 scsi-bus connected configured unknown
Example 4 Listing Current Configurable Hardware Information
in Verbose Mode
The following example lists current configurable hardware
information for ap-type system in verbose mode:
example# cfgadm -v -l system
ApId Receptacle Occupant Condition Information
When Type Busy PhysId
system:slot1 connected configured ok
Apr 4 23:50 sbus-upa n /devices/central/fhc/sysctrl:slot1
system:slot3 connected configured ok non-detachable
Apr 17 11:20 cpu/mem n /devices/central/fhc/sysctrl:slot3
system:slot5 connected configured ok
Apr 4 23:50 cpu/mem n /devices/central/fhc/sysctrl:slot5
system:slot7 connected configured ok
Apr 4 23:50 dual-sbus n /devices/central/fhc/sysctrl:slot7
The When column represents the statustime field.
Example 5 Testing Two Occupants Using the Hardware Specific
Extended Test
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
Example 6 Configuring an Occupant Using the Force Option
The following example configures an occupant in the failing
state to the system using the force option:
SunOS 5.11 Last change: 25 Oct 2004 12
System Administration Commands cfgadm(1M)
example# cfgadm -f -c configure system:slot3
Example 7 Unconfiguring an Occupant From the System
The following example unconfigures an occupant from the sys-
tem:
example# cfgadm -c unconfigure system:slot4
Example 8 Configuring an Occupant at an Attachment Point
The following example configures an occupant:
example# cfgadm -c configure c0::dsk/c0t0d0
ENVIRONMENT VARIABLES
See environ(5) for descriptions of the following environment
variables that affect the execution of cfgadm: LCTIME,
LCMESAGES, NLSPATH and TZ.
LCMESAGES Determines how cfgadm displays column head-
ings and error messages. Listing output data
is not affected by the setting of this vari-
able.
LCTIME Determines how cfgadm displays human readable
status changed time (statustime).
TZ Specifies the timezone used when converting
the status changed time. This applies to both
the human readable (statustime) and parsable
(statustimep) formats.
EXIT STATUS
The following exit values are returned:
0 Successful completion.
SunOS 5.11 Last change: 25 Oct 2004 13
System Administration Commands cfgadm(1M)
1 An error occurred.
2 Configuration administration not supported on specified
target.
3 Usage error.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWcsu
SEE ALSO
cfgadmfp(1M), cfgadmib(1M), cfgadmpci(1M),cfgadmsbd(1M),
cfgadmscsi(1M), cfgadmusb(1M), ifconfig(1M), mount(1M),
prtdiag(1M), psradm(1M), syslogd(1M), configadmin(3CFGADM),
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 are diag-
nostic messages produced by this utility:
cfgadm: Configuration administration not supported onapid
cfgadm: No library found for apid
cfgadm: apidis ambiguous
cfgadm: operation: Insufficient privileges
cfgadm: Attachment point is busy, try again
SunOS 5.11 Last change: 25 Oct 2004 14
System Administration Commands cfgadm(1M)
cfgadm: No attachment points with specified attributes found
cfgadm: System is busy, try again
cfgadm: operation: Operation requires a service interruption
cfgadm: operation: Data error: errortext
cfgadm: operation: Hardware specific failure: errortext
See configadmin(3CFGADM) 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 interven-
tion 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 cfgadm command can be used to pro-
vide 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: apid, physid,
rstate, ostate, condition, busy statustimep, class, 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=apid:rstate:condition:type" \
while read apid rstate cond type
SunOS 5.11 Last change: 25 Oct 2004 15
System Administration Commands cfgadm(1M)
do
if [ "$rstate" = unconfigured -a "$cond" = ok -a "$type" = CPU ]
then
if [ -z "$found" ]
then
found=$apid
fi
fi
done
if [ -n "$found" ]
then
echo "Found CPU $found"
fi
The format of the parsable time field (statustimep) is
YMDhhmmss, giving the year, month, day, hour, minute
and second in a form suitable for string comparison.
Reference should be made to the hardware specific documenta-
tion for details of System Configuration Administration sup-
port.
SunOS 5.11 Last change: 25 Oct 2004 16
|
