6324 Add an `ndp' tool for manipulating the neighbors table

[illumos-gate.git] / usr / src / man / man1m / cfgadm.1m

'\" te
.\"  Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH CFGADM 1M "Oct 25, 2004"
.SH NAME
cfgadm \- configuration administration
.SH SYNOPSIS
.LP
.nf
\fB/usr/sbin/cfgadm\fR [\fB-f\fR] [\fB-y\fR | \fB-n\fR] [\fB-v\fR] [\fB-o\fR \fIhardware_options\fR]
     \fB-c\fR \fIfunction\fR \fIap_id\fR...
.fi

.LP
.nf
\fB/usr/sbin/cfgadm\fR [\fB-f\fR] [\fB-y\fR | \fB-n\fR] [\fB-v\fR] [\fB-o\fR \fIhardware_options\fR]
     \fB-x\fR \fIhardware_function\fR \fIap_id\fR...
.fi

.LP
.nf
\fB/usr/sbin/cfgadm\fR [\fB-v\fR] [\fB-a\fR] [\fB-s\fR \fIlisting_options\fR]
     [\fB-o\fR \fIhardware_options\fR] [\fB-l\fR [\fIap_id\fR | \fIap_type\fR]]
.fi

.LP
.nf
\fB/usr/sbin/cfgadm\fR [\fB-v\fR] [\fB-o\fR \fIhardware_options\fR] \fB-t\fR \fIap_id\fR...
.fi

.LP
.nf
\fB/usr/sbin/cfgadm\fR [\fB-v\fR] [\fB-o\fR \fIhardware_options\fR] \fB-h\fR
     [\fIap_id\fR | \fIap_type\fR]
.fi

.SH DESCRIPTION
.sp
.LP
The \fBcfgadm\fR command provides configuration administration operations on
dynamically reconfigurable hardware resources. These operations include
displaying status, (\fB-l\fR), initiating testing, (\fB-t\fR), invoking
configuration state changes, (\fB-c\fR), invoking hardware specific functions,
(\fB-x\fR), and obtaining configuration administration help messages
(\fB-h\fR). Configuration administration is performed at \fBattachment
points\fR, which are places where system software supports dynamic
reconfiguration of hardware resources during continued operation of Solaris.
.sp
.LP
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.
.sp
.LP
Configuration administration operates on an \fBattachment point\fR. Hardware
resources located at attachment points can or can not be physically replaceable
during system operation, but are dynamically reconfigurable by way of the
configuration administration interfaces.
.sp
.LP
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 \fBreceptacle\fR and an \fBoccupant\fR. 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.
.sp
.LP
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:
\fBempty\fR, \fBdisconnected\fR or \fBconnected\fR, while an occupant can exist
in one of two states: \fBconfigured\fR or \fBunconfigured\fR.
.sp
.LP
A receptacle can provide the \fBempty\fR state, which is the normal state of a
receptacle when the attachment point has no occupants. A receptacle can also
provide the \fBdisconnected\fR 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 can provide access
for testing and setup. A receptacle must provide the \fBconnected\fR 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.
.sp
.LP
The hardware resources contained on an occupant in the \fBunconfigured\fR 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 \fBconfigured\fR 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 \fBconfigured\fR and
\fBunconfigured\fR states,
.sp
.LP
An attachment point can be in one of five conditions: \fBunknown\fR, \fBok\fR,
\fBfailing\fR, \fBfailed\fR, or \fBunusable\fR. An attachment point can enter
the system in any condition depending upon results of power-on tests and
non-volatile record keeping.
.sp
.LP
An attachment point with an occupant in the \fBconfigured\fR state is in one of
four conditions: \fBunknown\fR, \fBok\fR, \fBfailing\fR, or \fBfailed\fR. If
the condition is not \fBfailing\fR or \fBfailed\fR an attachment point can
change to \fBfailing\fR during the course of operation if a hardware dependent
recoverable error threshold is exceeded. If the condition is not \fBfailed\fR
an attachment point can change to \fBfailed\fR during operation as a result of
an unrecoverable error.
.sp
.LP
An attachment point with an occupant in the \fBunconfigured\fR state can be in
any of the defined conditions. The condition of an attachment point with an
\fBunconfigured\fR occupant can decay from \fBok\fR to \fBunknown\fR after a
machine dependent time threshold. Initiating a test function changes the
attachment point's condition to \fBok\fR, \fBfailing\fR or \fBfailed\fR
depending on the outcome of the test. An attachment point that does not provide
a test function can leave the attachment point in the \fBunknown\fR condition.
If a test is interrupted, the attachment point's condition can be set to the
previous condition, \fBunknown\fR or \fBfailed\fR. An attachment point in the
\fBunknown\fR, \fBok\fR, \fBfailing\fR, or \fBfailed\fR conditions can be
re-tested.
.sp
.LP
An attachment point can exist in the \fBunusable\fR 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 \fBunusable\fR condition can never be used by the system. It
typically remains in this condition until the physical cause is remedied.
.sp
.LP
An attachment point also maintains busy information that indicates when a state
change is in progress or the condition is being reevaluated.
.sp
.LP
Attachment points are referred to using hardware specific identifiers
(\fIap_id\fRs) that are related to the type and location of the attachment
points in the system device hierarchy. An \fIap_id\fR can not be ambiguous, it
must identify a single attachment point. Two types of \fIap_id\fR
specifications are supported: physical and logical. A physical \fIap_id\fR
contains a fully specified pathname, while a logical \fIap_id\fR contains a
shorthand notation that identifies an attachment point in a more user-friendly
way.
.sp
.LP
For example, an attachment point representing a system's backplane slot number
\fB7\fR could have a physical \fIap_id\fR of
\fB/devices/central/fhc/sysctrl:slot7\fR while the logical \fIap_id\fR could be
\fBsystem:slot7\fR. Another example, the third receptacle on the second \fBPCI
I/O\fR bus on a system could have a logical \fIap_id\fR of \fBpci2:plug3\fR.
.sp
.LP
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.
\fBap_id\fRs for dynamic attachment points consist of a base component followed
by two colons (\fB::\fR) and a dynamic component. The base component is the
base attachment point \fBap_id\fR. The dynamic component is hardware specific
and generated by the corresponding hardware specific library.
.sp
.LP
For example, consider a base attachment point, which represents a \fBSCSI
HBA\fR, with the physical \fBap_id\fR
\fB/devices/sbus@1f,0/SUNW,fas@e,8800000:scsi\fR and logical \fBap_id c0\fR . A
disk attached to this \fBSCSI HBA\fR could be represented by a dynamic
attachment point with logical \fBap_id\fR \fBc0::dsk/c0t0d0\fR where \fBc0\fR
is the base component and \fBdsk/c0t0d0\fR is the hardware specific dynamic
component. Similarly the physical \fBap_id\fR for this dynamic attachment point
would be: \fB/devices/sbus@1f,0/SUNW,fas@e,8800000:scsi::dsk/c0t0d0\fR
.sp
.LP
An \fIap_type\fR is a partial form of a logical \fBap_id\fR that can be
ambiguous and not specify a particular attachment point. An \fIap_type\fR is a
substring of the portion of the logical \fBap_id\fR up to but not including the
colon (\fB:\fR) separator. For example, an \fIap_type\fR of \fBpci\fR would
show all attachment points whose logical \fIap_id\fRs begin with \fBpci\fR.
.sp
.LP
The use of \fIap_types\fR is discouraged. The new select sub-option to the
\fB-s\fR option provides a more general and flexible mechanism for selecting
attachment points. See \fBOPTIONS\fR.
.sp
.LP
The \fBcfgadm\fR command interacts primarily with hardware dependent functions
contained in hardware specific libraries and thus its behavior is hardware
dependent.
.sp
.LP
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 the function is
started. Confirmation can be overridden using the \fB-y\fR or \fB-n\fR options
to always answer yes or no respectively. Hardware specific options, such as
test level, are supplied as sub-options using the \fB-o\fR option.
.sp
.LP
Operations that change the state of the system configuration are audited by the
system log daemon \fBsyslogd\fR(1M).
.sp
.LP
The arguments for this command conform to the \fBgetopt\fR(3C) and
\fBgetsubopt\fR(3C) syntax convention.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-a\fR\fR
.ad
.sp .6
.RS 4n
Specifies that the \fB-l\fR option must also list dynamic attachment points.
.RE

.sp
.ne 2
.na
\fB\fB-c\fR\fIfunction\fR\fR
.ad
.sp .6
.RS 4n
Performs the state change \fIfunction\fR on the attachment point specified by
\fIap_id.\fR
.sp
Specify \fIfunction\fR as \fBinsert\fR, \fBremove\fR, \fBdisconnect\fR,
\fBconnect\fR, \fBconfigure\fR or \fBunconfigure\fR. These functions cause
state transitions at the attachment point by calling hardware specific library
routines and are defined in the following list.
.sp
.ne 2
.na
\fB\fBinsert\fR\fR
.ad
.RS 15n
Performs operations that allows the user to manually insert an occupant or to
activate a hardware supplied mechanism that performs the physical insertion.
\fBinsert\fR 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
\fBunusable\fR.
.RE

.sp
.ne 2
.na
\fB\fBremove\fR\fR
.ad
.RS 15n
Performs operations that allow the user to manually remove an occupant or to
activate a hardware supplied mechanism to perform the physical removal.
\fBremove\fR 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.
.RE

.sp
.ne 2
.na
\fB\fBdisconnect\fR\fR
.ad
.RS 15n
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.
.RE

.sp
.ne 2
.na
\fB\fBconnect\fR\fR
.ad
.RS 15n
Performs hardware specific operations to put the receptacle in the
\fBconnected\fR state, which allows an occupant to operate in a normal fashion
through the receptacle.
.RE

.sp
.ne 2
.na
\fB\fBconfigure\fR\fR
.ad
.RS 15n
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: \fBpsradm\fR(1M), \fBmount\fR(1M),
\fBifconfig\fR(1M)).
.RE

.sp
.ne 2
.na
\fB\fBunconfigure\fR\fR
.ad
.RS 15n
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.
.RE

State transition functions can fail due to the condition of the attachment
point or other hardware dependent considerations. All state change
\fIfunction\fRs in the direction of adding resources, \fB(insert,\fR
\fBconnect\fR and \fBconfigure)\fR are passed onto the hardware specific
library when the attachment point is in the \fBok\fR or \fBunknown\fR
condition. All other conditions require the use of the force option to allow
these \fIfunction\fRs 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 (\fBremove,\fR \fBdisconnect\fR and
\fBunconfigure\fR), of hardware resources from the system. Hardware specific
libraries can reject state change \fIfunction\fRs if the attachment point is in
the \fBunknown\fR condition.
.sp
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 (\fB-f\fR). Hardware specific safety and integrity checks can prevent
the force option from having any effect.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.sp .6
.RS 4n
Forces the specified action to occur. Typically, this is a hardware dependent
override of a safety feature. Forcing a state change operation can allow use of
the hardware resources of occupant that is not in the \fBok\fR or \fBunknown\fR
conditions, at the discretion of any hardware dependent safety checks.
.RE

.sp
.ne 2
.na
\fB\fB\fR\fB-h\fR [\fIap_id\fR | \fIap_type\fR \|.\|.\|. ]\fR
.ad
.sp .6
.RS 4n
Prints out the help message text. If \fIap_id\fR or \fIap_type\fR is specified,
the help routine of the hardware specific library for the attachment point
indicated by the argument is called.
.RE

.sp
.ne 2
.na
\fB\fB\fR\fB-l\fR [\fIap_id\fR | \fIap_type\fR \|.\|.\|. ]\fR
.ad
.sp .6
.RS 4n
Lists the state and condition of attachment points specified. Attachment points
can be filtered by using the \fB-s\fR option and \fBselect\fR sub-option.
Invoking \fBcfgadm\fR without one of the action options is equivalent to
\fB-l\fR without an argument. The format of the list display is controlled by
the \fB-v\fR and \fB-s\fR options. When the \fB-a\fR option is specified
attachment points are dynamically expanded.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.sp .6
.RS 4n
Suppress any interactive confirmation and assume that the answer is \fIno\fR.
If neither \fB-n\fR or \fB-y\fR 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
\fBisatty\fR(3C)) then the \fB-n\fR option is assumed.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR\fIhardware_options\fR\fR
.ad
.sp .6
.RS 4n
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 \fIhardware_options\fR conforms to the \fBgetsubopt\fR(3C) syntax
convention.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fIlisting_options\fR\fR
.ad
.sp .6
.RS 4n
Supplies listing options to the list (\fB-l\fR) command. \fIlisting_options\fR
conforms to the \fBgetsubopt\fR(3C) syntax convention. The sub-options are used
to specify the attachment point selection criteria (
\fBselect\fR=\fIselect_string\fR), the type of matching desired
(\fBmatch\fR=\fImatch_type\fR), order of listing (\fBsort\fR=\fIfield_spec\fR),
the data that is displayed (\fBcols=\fR\fIfield_spec\fR and
\fBcols2=\fR\fIfield_spec\fR), the column delimiter (\fBdelim=\fR\fIstring\fR)
and whether to suppress column headings (\fBnoheadings\fR).
.sp
When the \fBselect\fR sub-option is specified, only attachment points which
match the specified criteria will be listed. The \fBselect\fR sub-option has
the following syntax:
.sp
.in +2
.nf
cfgadm \fB-s\fR select=attr1(value1):attr2(value2)...
.fi
.in -2
.sp

where an \fIattr\fR is one of \fBap_id\fR, \fBclass\fR or \fBtype\fR.
\fBap_id\fR refers to the logical \fIap_id\fR field, \fBclass\fR refers to
attachment point class and \fBtype\fR refers to the type field. \fIvalue1\fR,
\fIvalue2\fR, etc. are the corresponding values to be matched. The type of
match can be specified by the \fBmatch\fR sub-option as follows:
.sp
.in +2
.nf
cfgadm \fB-s\fR match=\fImatch_type\fR,select=attr1(value1)...
.fi
.in -2
.sp

where \fImatch_type\fR can be either \fBexact\fR or \fBpartial\fR. The default
value is \fBexact\fR.
.sp
Arguments to the \fBselect\fR sub-option can be quoted to protect them from the
shell.
.sp
A \fIfield_spec\fR is one or more \fIdata-field\fRs concatenated using colon
(\fB:\fR), as in \fIdata-field\fR:\fIdata-field\fR:\fIdata-field\fR. A
\fIdata-field\fR is one of \fBap_id\fR, \fBphysid\fR, \fBr_state\fR,
\fBo_state\fR, \fBcondition\fR, \fBtype\fR, \fBbusy\fR, \fBstatus_time\fR,
\fBstatus_time_p\fR, \fBclass\fR, and \fBinfo\fR. The \fBap_id\fR field output
is the logical name for the attachment point, while the \fBphysid\fR field
contains the physical name. The \fBr_state\fR field can be \fBempty\fR,
\fBdisconnected\fR or \fBconnected\fR. The \fBo_state\fR field can be
\fBconfigured\fR or \fBunconfigured\fR. The \fBbusy\fR field can be either
\fBy\fR if the attachment point is busy, or \fBn\fR if it is not. The
\fBtype\fR and \fBinfo\fR fields are hardware specific. The \fBstatus_time\fR
field provides the time at which either the \fBr_state\fR, \fBo_state\fR, or
condition of the attachment point last changed. The \fBstatus_time_p\fR field
is a parsable version of the \fBstatus_time\fR field. If an attachment point
has an associated class, the \fBclass\fR field lists the class name. If an
attachment point does not have an associated class, the \fBclass\fR field lists
\fBnone\fR.
.sp
The order of the fields in \fIfield_spec\fR is significant: For the \fBsort\fR
sub-option, the first field given is the primary sort key. For the \fBcols\fR
and \fBcols2\fR sub-options, the fields are printed in the order requested. The
order of sorting on a \fIdata-field\fR can be reversed by placing a minus
(\fB\(mi\fR) before the \fIdata-field\fR name within the \fIfield_sec\fR for
the \fBsort\fR sub-option. The default value for \fBsort\fR is \fBap_id\fR. The
defaults values for \fBcols\fR and \fBcols2\fR depend on whether the \fB-v\fR
option is given: Without it \fBcols\fR is \fBap_id:r_state:o_state:condition\fR
and \fBcols2\fR is not set. With \fB-v\fR \fBcols\fR is
\fBap_id:r_state:o_state:condition:info\fR and \fBcols2\fR is
\fBstatus_time:type:busy:physid:\fR. The default value for \fBdelim\fR is a
single space. The value of \fBdelim\fR can be a string of arbitrary length. The
delimiter cannot include comma (\fB,\fR) character, see \fBgetsubopt\fR(3C).
These listing options can be used to create parsable output. See \fBNOTES\fR.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR\fR
.ad
.sp .6
.RS 4n
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 \fIhardware_options\fR, the fastest test that identifies hard
faults is used.
.sp
More comprehensive tests are hardware specific and are selected using the
\fIhardware_options\fR.
.sp
The results of the test is used to update the condition of the specified
occupant to either \fBok\fR if no faults are found, \fBfailing\fR if
recoverable faults are found or \fBfailed\fR if any unrecoverable faults are
found.
.sp
If a test is interrupted, the attachment point's condition can be restored to
its previous value or set to \fBunknown\fR if no errors were found or
\fBfailing\fR if only recoverable errors were found or to \fBfailed\fR if any
unrecoverable errors were found. The attachment point should only be set to
\fBok\fR upon normal completion of testing with no errors.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.sp .6
.RS 4n
Executes in verbose mode. For the \fB-c\fR, \fB-t\fR and \fB-x\fR options
outputs a message giving the results of each attempted operation. Outputs
detailed help information for the \fB-h\fR option. Outputs verbose information
for each attachment point for the \fB-l\fR option.
.RE

.sp
.ne 2
.na
\fB\fB-x\fR\fIhardware_function\fR\fR
.ad
.sp .6
.RS 4n
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 \fIhardware_function\fR string is
completely hardware specific. The option string \fIhardware_function\fR
conforms to the \fBgetsubopt\fR(3C) syntax convention.
.RE

.sp
.ne 2
.na
\fB\fB-y\fR\fR
.ad
.sp .6
.RS 4n
Suppresses any interactive confirmation and assume that the answer is
\fByes\fR.
.RE

.SH USAGE
.sp
.LP
The required privileges to use this command are hardware dependent. Typically,
a default system configuration restricts all but the list option to the
superuser.
.SH EXAMPLES
.LP
\fBExample 1 \fRListing Attachment Points in the Device Tree
.sp
.LP
The following example lists all attachment points except dynamic attachment
points.

.sp
.in +2
.nf
example# cfgadm

  Ap_Id         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
c1              scsi-bus    connected       configured     unknown
.fi
.in -2
.sp

.LP
\fBExample 2 \fRListing All Configurable Hardware Information
.sp
.LP
The following example lists all current configurable hardware information,
including those represented by dynamic attachment points:

.sp
.in +2
.nf
example# cfgadm -al

  Ap_Id            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
.fi
.in -2
.sp

.LP
\fBExample 3 \fRListing Selectively, Based on Attachment Point Attributes
.sp
.LP
The following example lists all attachment points whose class begins with
\fBscsi\fR, \fBap_id\fR begins with \fBc\fR and \fBtype\fR field begins with
\fBscsi\fR. The argument to the \fB-s\fR option is quoted to protect it from
the shell.

.sp
.in +2
.nf
example# cfgadm -s "match=partial,select=class(scsi):ap_id(c):type(scsi)"

Ap_Id         Type          Receptacle      Occupant           Cond
 c0          scsi-bus      connected       configured         unknown
 c1          scsi-bus      connected       configured         unknown
.fi
.in -2
.sp

.LP
\fBExample 4 \fRListing Current Configurable Hardware Information in Verbose
Mode
.sp
.LP
The following example lists current configurable hardware information for
\fIap-type\fR \fBsystem\fR in verbose mode:

.sp
.in +2
.nf
example# cfgadm -v -l system
Ap_Id                      Receptacle Occupant   Condition Information
When         Type      Busy     Phys_Id
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
.fi
.in -2
.sp

.sp
.LP
The \fBWhen\fR column represents the \fBstatus_time\fR field.
.LP
\fBExample 5 \fRTesting Two Occupants Using the Hardware Specific
\fBExtended\fR Test
.sp
.LP
The following example tests two occupants using the hardware specific
\fBextended\fR test:

.sp
.in +2
.nf
example# cfgadm -v -o extended -t system:slot3 system:slot5
Testing attachment point system:slot3 ...  ok
Testing attachment point system:slot5 ...  ok
.fi
.in -2
.sp

.LP
\fBExample 6 \fRConfiguring an Occupant Using the Force Option
.sp
.LP
The following example configures an occupant in the \fBfailing\fR state to the
system using the force option:

.sp
.in +2
.nf
example# cfgadm -f -c configure system:slot3
.fi
.in -2
.sp

.LP
\fBExample 7 \fRUnconfiguring an Occupant From the System
.sp
.LP
The following example unconfigures an occupant from the system:

.sp
.in +2
.nf
example# cfgadm -c unconfigure system:slot4
.fi
.in -2
.sp

.LP
\fBExample 8 \fRConfiguring an Occupant at an Attachment Point
.sp
.LP
The following example configures an occupant:

.sp
.in +2
.nf
example# cfgadm -c configure c0::dsk/c0t0d0
.fi
.in -2
.sp

.SH ENVIRONMENT VARIABLES
.sp
.LP
See \fBenviron\fR(5) for descriptions of the following environment variables
that affect the execution of \fBcfgadm\fR: \fBLC_TIME\fR, \fBLC_MESSAGES\fR,
\fBNLSPATH\fR and \fBTZ\fR.
.sp
.ne 2
.na
\fB\fBLC_MESSAGES\fR\fR
.ad
.RS 15n
Determines how \fBcfgadm\fR displays column headings and error messages.
Listing output data is not affected by the setting of this variable.
.RE

.sp
.ne 2
.na
\fB\fBLC_TIME\fR\fR
.ad
.RS 15n
Determines how \fBcfgadm\fR displays human readable status changed time
(\fBstatus_time\fR).
.RE

.sp
.ne 2
.na
\fB\fBTZ\fR\fR
.ad
.RS 15n
Specifies the timezone used when converting the status changed time. This
applies to both the human readable (\fBstatus_time\fR) and parsable
(\fBstatus_time_p\fR) formats.
.RE

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 5n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.RS 5n
An error occurred.
.RE

.sp
.ne 2
.na
\fB\fB2\fR\fR
.ad
.RS 5n
Configuration administration not supported on specified target.
.RE

.sp
.ne 2
.na
\fB\fB3\fR\fR
.ad
.RS 5n
Usage error.
.RE

.SH SEE ALSO
.sp
.LP
\fBcfgadm_fp\fR(1M), \fBcfgadm_ib\fR(1M),
\fBcfgadm_pci\fR(1M),\fBcfgadm_sbd\fR(1M), \fBcfgadm_scsi\fR(1M),
\fBcfgadm_usb\fR(1M), \fBifconfig\fR(1M), \fBmount\fR(1M), \fBprtdiag\fR(1M),
\fBpsradm\fR(1M), \fBsyslogd\fR(1M), \fBconfig_admin\fR(3CFGADM),
\fBgetopt\fR(3C), \fBgetsubopt\fR(3C), \fBisatty\fR(3C), \fBattributes\fR(5),
\fBenviron\fR(5)
.SH DIAGNOSTICS
.sp
.LP
Diagnostic messages appear on the standard error output. Other than options and
usage errors, the following are diagnostic messages produced by this utility:
.sp
.in +2
.nf
cfgadm: Configuration administration not supported on\fIap_id\fR
.fi
.in -2
.sp

.sp
.in +2
.nf
cfgadm: No library found for \fIap_id\fR
.fi
.in -2
.sp

.sp
.in +2
.nf
cfgadm: \fIap_id\fRis ambiguous
.fi
.in -2
.sp

.sp
.in +2
.nf
cfgadm: \fIoperation\fR: Insufficient privileges
.fi
.in -2
.sp

.sp
.in +2
.nf
cfgadm: Attachment point is busy, try again
.fi
.in -2
.sp

.sp
.in +2
.nf
cfgadm: No attachment points with specified attributes found
.fi
.in -2
.sp

.sp
.in +2
.nf
cfgadm: System is busy, try again
.fi
.in -2
.sp

.sp
.in +2
.nf
cfgadm: \fIoperation\fR: Operation requires a service interruption
.fi
.in -2
.sp

.sp
.in +2
.nf
cfgadm: \fIoperation\fR: Data error: \fIerror_text\fR
.fi
.in -2
.sp

.sp
.in +2
.nf
cfgadm: \fIoperation\fR: Hardware specific failure: \fIerror_text\fR
.fi
.in -2
.sp

.sp
.LP
See \fBconfig_admin\fR(3CFGADM) for additional details regarding error
messages.
.SH NOTES
.sp
.LP
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 \fBunconfigured\fR
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.
.sp
.LP
The listing option of the \fBcfgadm\fR command can be used to provide parsable
input for another command, for example within a shell script. For parsable
output, the \fB-s\fR option must be used to select the fields required. The
\fB-s\fR option can also be used to suppress the column headings. The following
fields always produce parsable output: \fBap_id\fR, \fBphysid\fR,
\fBr_state\fR, \fBo_state\fR, \fBcondition\fR, \fBbusy\fR \fBstatus_time_p\fR,
\fBclass\fR, and \fBtype\fR. Parsable output never has white-space characters
embedded in the field value.
.sp
.LP
The following shell script fragment finds the first good \fBunconfigured\fR
occupant of type \fBCPU.\fR
.sp
.in +2
.nf
found=
cfgadm -l -s "noheadings,cols=ap_id:r_state:condition:type" | \e
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
.fi
.in -2
.sp

.sp
.LP
The format of the parsable time field (\fBstatus_time_p\fR) is
\fIYYYYMMDDhhmmss\fR, giving the year, month, day, hour, minute and second in a
form suitable for string comparison.
.sp
.LP
Reference should be made to the hardware specific documentation for details of
System Configuration Administration support.