path: root/usr/src/man/man8/cfgadm_fp.8

'\" te
.\" Copyright (c) 2008, 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_FP 8 "Jan 10, 2008"
.SH NAME
cfgadm_fp \- driver specific commands for cfgadm
.SH SYNOPSIS
.LP
.nf
\fB/usr/sbin/cfgadm\fR [\fB-f\fR] [\fB-n\fR | \fB-y\fR] [\fB-v\fR] [\fB-o\fR \fIhardware_options\fR]
     \fB-c\fR \fIfunction\fR \fIap_id\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]]
.fi

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

.SH DESCRIPTION
.sp
.LP
The \fBfp\fR port driver plug-in \fB/usr/lib/cfgadm/fp.so.1\fR provides the
functionality for Fibre Channel Fabric device node management through
\fBcfgadm\fR(8). \fBcfgadm\fR operates on attachment points. Attachment points
are locations in the system where hardware resources can be dynamically
reconfigured. Refer to \fBcfgadm\fR(8) for additional details on attachment
points.
.sp
.LP
For Fibre Channel Fabric device node management, each \fBfp\fR port node is
represented by an attachment point in the device tree. In addition, each Fibre
Channel device is represented by a dynamic attachment point. Attachment points
are named through \fBap_ids\fR. Two types of \fBap_ids\fR are defined: logical
and physical. The physical \fBap_id\fR is based on the physical pathname. The
logical \fBap_id\fR is a shorter, more user-friendly name. For \fBfp\fR port
nodes, the logical \fBap_id\fR is the corresponding disk controller number. For
example, \fBc0\fR is a typical logical \fBap_id\fR.
.sp
.LP
Fibre Channel devices are named with a port World Wide Name (WWN). If a disk
device is connected to controller \fBc0\fR, its \fBap_id\fR can be:
.sp
.in +2
.nf
c0::50020f2300006077
.fi
.in -2
.sp

.sp
.LP
where \fB50020f2300006077\fR identifies the port WWN of a specific Fibre
Channel device.
.sp
.LP
Each device on the Fibre Channel private loop port, Fabric port or public loop
port is probed and made available to Solaris by default. Devices connected to
the Fibre Channel Fabric port or public loop port can be made unavailable to
Solaris by initiating an application or an end user operation. The operation is
similar to the hot unplugging of devices by way of management user interfaces.
Applications or users can use the \fB/usr/lib/cfgadm/fp.so.1\fR library to
enable \fBlibcfgadm\fR to provide interfaces to accomplish this task.
.sp
.LP
The list of currently connected Fabric devices is generated in the form of the
attachment point.
.sp
.LP
A simple listing of attachment points in the system includes attachment points
at \fBfp\fR port nodes but not Fibre Channel devices. The following example
uses the \fB-a\fR flag to the list option (\fB-l\fR) to list Fibre Channel
devices:
.sp
.in +2
.nf
# \fBcfgadm -l\fR
     Ap_Id                Type         Receptacle   Occupant     Condition
     c0                   fc-fabric    connected    configured   unknown
     c1                   fc-private   connected    configured   unknown
     c2                   fc-pt_to_pt  connected    configured   unknown
     c3                   fc           connected    unconfigured unknown
     sysctrl0:slot0       cpu/mem      connected    configured   ok
     sysctrl0:slot1       sbus-upa     connected    configured   ok
.fi
.in -2
.sp

.sp
.LP
The following example lists Fibre Channel devices connected to \fBfp\fR ports.
.sp
.in +2
.nf
# \fBcfgadm -al\fR
     Ap_Id                Type         Receptacle   Occupant     Condition
     c0                   fc-fabric    connected    configured   unknown
     c0::50020f2300006077 disk         connected    configured   unknown
     c0::50020f23000063a9 disk         connected    configured   unknown
     c0::50020f2300005f24 disk         connected    configured   unknown
     c0::50020f2300006107 disk         connected    configured   unknown
     c1                   fc-private   connected    configured   unknown
     c1::220000203708b69c disk         connected    configured   unknown
     c1::220000203708ba7d disk         connected    configured   unknown
     c1::220000203708b8d4 disk         connected    configured   unknown
     c1::220000203708b9b2 disk         connected    configured   unknown
     c2                   fc-pt_to_pt  connected    configured   unknown
     c2::500104f000937528 tape         connected    configured   unknown
     c3                   fc           connected    unconfigured unknown
     sysctrl0:slot0       cpu/mem      connected    configured   ok
     sysctrl0:slot1       sbus-upa     connected    configured   ok
.fi
.in -2
.sp

.sp
.LP
In this example, the \fBfc-fabric\fR type of \fBap_id\fR \fBc0\fR indicates
that the \fBfp\fR port is connected to Fabric. For an \fBfp\fR port with a
Fabric-related type such as \fBfc-fabric\fR and \fBfc-public\fR, device node
creation happens by default at the boot time and can be managed by the
\fBcfgadm\fR configure and unconfigure operations. The  \fBfc-private\fR  type
of \fBap_id c1\fR indicates that \fBfp\fR port is connected to private-loop and
device node creation happens by default as well. The \fBfc-pt_to_pt\fR type of
\fBap_id c2\fR indicates that the \fBfp\fR port is directly connected to
another \fBN_port\fR and device node creation also happens by default. The
\fBfc\fR type of \fBap_id c3\fR indicates that nothing is attached to \fBfp\fR
port \fBc2\fR. The Type field of a Fibre Channel  device \fBap_id\fR shows the
SCSI device type of LUN 0 in the device.
.sp
.LP
A Fibre Channel device with multiple FCP SCSI LUNs is configured into Solaris
and each \fBFCP SCSI LUN\fR is available as a Solaris device. Suppose that
ap_ids \fBc0::50020f2300006077\fR and \fBc0::50020f23000063a9\fR represent
Fibre Channel devices with multiple \fBFCP SCSI LUN\fRs.
.sp
.LP
The following example shows how to list ap_ids with \fBFCP\fR \fBSCSI\fR
\fBLUN\fR information:
.sp
.in +2
.nf
# \fBcfgadm -al -o show_SCSI_LUN\fR
     Ap_Id                  Type         Receptacle   Occupant     Condition
     c0                     fc-fabric    connected    configured   unknown
     c0::50020f2300006077,0 disk         connected    configured   unknown
     c0::50020f2300006077,1 disk         connected    configured   unknown
     c0::50020f2300006077,2 disk         connected    configured   unknown
     c0::50020f2300006077,3 disk         connected    configured   unknown
     c0::50020f23000063a9,0 disk         connected    configured   unknown
     c0::50020f23000063a9,1 disk         connected    configured   unknown
     c0::50020f23000063a9,2 disk         connected    configured   unknown
     c0::50020f23000063a9,3 disk         connected    configured   unknown
     c0::50020f2300005f24,0 disk         connected    unconfigured unknown
     c0::50020f2300005f24,1 disk         connected    unconfigured unknown
     c0::50020f2300006107,0 disk         connected    unconfigured unknown
     c0::50020f2300006107,1 disk         connected    unconfigured unknown
     c1                     fc-private   connected    configured   unknown
     c1::220000203708b69c,0 disk         connected    configured   unknown
     c1::220000203708ba7d,0 disk         connected    configured   unknown
     c1::220000203708b8d4,0 disk         connected    configured   unknown
     c1::220000203708b9b2,0 disk         connected    configured   unknown
     c2                     fc-pt_to_pt  connected    configured   unknown
     c2::500104f000937528,0 tape         connected    configured   unknown
     c3                     fc           connected    unconfigured unknown
.fi
.in -2
.sp

.sp
.LP
In this example, the \fBap_id c0::50020f2300006077,0\fR identifies the \fBFCP
SCSI LUN 0\fR of the Fibre Channel device which is represented by port \fBWWN
50020f2300006077\fR. The Fibre Channel device is reported to have 4 \fBFCP SCSI
LUN\fRs and they are all configured. \fB4 FCP SCSI LUN\fR level ap_ids
associated with port \fBWWN 50020f2300006077\fR are listed. The listing also
displays \fBFCP SCSI LUN\fRs for unconfigured Fibre Channel devices. The Fibre
Channel device represented by \fBc0::50020f2300005f24\fR is reported to have
two \fBFCP SCSI LUN\fRs. The configure operation \fBon c0::50020f2300005f24\fR
creates two Solaris devices. The \fBType\fR field of \fBFCP\fR \fBSCSI\fR
\fBLUN\fR level ap_ids show the \fBSCSI\fR device type of each \fBLUN\fR. When
a Fibre Channel device has different device type \fBLUN\fRs, the \fBType\fR
field reflects that.
.sp
.LP
The receptacle and occupant state for attachment points at the \fBfp\fR port
have the following meanings:
.sp
.ne 2
.na
\fBconfigured\fR
.ad
.sp .6
.RS 4n
One or more devices configured on the \fBfp\fR port
.RE

.sp
.ne 2
.na
\fBconnected\fR
.ad
.sp .6
.RS 4n
\fBfp\fR port active
.RE

.sp
.ne 2
.na
\fBdisconnected\fR
.ad
.sp .6
.RS 4n
\fBfp\fR port quiesced (IO activity is suspended)
.RE

.sp
.ne 2
.na
\fBempty\fR
.ad
.sp .6
.RS 4n
Not applicable
.RE

.sp
.ne 2
.na
\fBunconfigured\fR
.ad
.sp .6
.RS 4n
No devices configured on the \fBfp\fR port
.RE

.sp
.LP
The state for individual Fibre Channel devices on an \fBfp\fR port:
.sp
.ne 2
.na
\fBconfigured\fR
.ad
.sp .6
.RS 4n
Device is configured into Solaris and is available for use
.RE

.sp
.ne 2
.na
\fBconnected\fR
.ad
.sp .6
.RS 4n
\fBfp\fR port to which the device is connected to is active
.RE

.sp
.ne 2
.na
\fBdisconnected\fR
.ad
.sp .6
.RS 4n
\fBfp\fR port to which the device is attached is quiesced
.RE

.sp
.ne 2
.na
\fBunconfigured\fR
.ad
.sp .6
.RS 4n
Device is available to be configured
.RE

.sp
.LP
The \fBcondition\fR field for attachment points at the \fBfp\fR port has the
following meanings:
.sp
.ne 2
.na
\fBfailed\fR
.ad
.sp .6
.RS 4n
An error condition has prevented the \fBfp\fR port from being able to detect
the presence or type of a Fibre Channel connection.
.RE

.sp
.LP
The \fBcondition\fR field for individual Fibre Channel devices on an \fBfp\fR
port has the following meanings:
.sp
.ne 2
.na
\fBfailed\fR
.ad
.sp .6
.RS 4n
An error is encountered while probing a device on Fabric.
.RE

.sp
.ne 2
.na
\fBfailing\fR
.ad
.sp .6
.RS 4n
A device was configured on a host and its state as seen by Solaris appears to
be normal (i.e., online) but it is either not currently present or visible in
the fabric or its presence could not be verified due to an error condition on
the local port through which the device was configured.
.RE

.sp
.ne 2
.na
\fBunusable\fR
.ad
.sp .6
.RS 4n
A device has been configured on the host, but is currently offline or failed.
.RE

.sp
.LP
The unknown \fBcondition\fR indicates that probing a device on Fabric completed
without an error and the device state within Solaris host is normal if the
device was configured previously. The internal condition of the device cannot
be guaranteed.
.SH OPTIONS
.sp
.LP
\fBcfgadm\fR defines several types of operations in addition to listing
(\fB-l\fR). These operations include invoking configuration state changes and
obtaining configuration administration help messages (\fB-h\fR).
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-c\fR \fIfunction\fR\fR
.ad
.sp .6
.RS 4n
The following generic commands are defined for the \fBfp\fR-transport-specific
library:
.sp
For Fibre Channel device attachment points on the \fBfc-fabric\fR type \fBfp\fR
port attachment point, the following configuration state change operations are
supported:
.sp
.ne 2
.na
\fB\fBconfigure\fR\fR
.ad
.sp .6
.RS 4n
Configure a connected Fibre Channel Fabric device to a host. When a Fibre
Channel device is listed as an unknown type in the output of the list operation
the device might not be configurable. No attempt is made to configure devices
with unknown types. The force option (\fB-f\fR) can be used to force the
\fBfp\fR port driver plug-in to make an attempt to configure any devices. Any
errors in the process are reported. By default, each FCP SCSI LUN that is
discovered on a Fibre channel Fabric device is configured. However, FCP SCSI
LUNs that are specified in the "pwwn-lun-blacklist" property in the
\fBfp.conf\fR file will remain unconfigured. The FCP SCSI LUN level listing
reflects the state of such FCP SCSI LUNs. They stay in the "unconfigured" state
after reboot or Solaris Dynamic Reconfiguration on the controller that they are
connected through. Refer to \fBfp\fR(4D) for additional details on the
"pwwn-lun-blacklist" property.
.RE

.sp
.ne 2
.na
\fB\fBunconfigure\fR\fR
.ad
.sp .6
.RS 4n
Unconfigure a Fibre Channel Fabric device from a host. This device stays
unconfigured until the next reboot or Solaris Dynamic Reconfiguration on the
controller that the device is connected, at which time all fabric devices are
automatically enumerated. The default behavior may be changed through the use
of the "manual_configuration_only" property in the \fBfp.conf\fR file. If the
property is set, the device remains unconfigured after reboot. Refer to
\fBfp\fR(4D) for additional details on the "manual_configuration_only"
property.
.RE

For Fibre Channel private loop devices and \fBN_Port\fR point-to-point devices,
the \fBconfigure\fR command returns success without doing any operation. The
\fBunconfigure\fR command is not supported on the private loop devices and
\fBN_Port\fR point-to-point devices. The private loop  devices and \fBN_Port\fR
point-to-point devices are configured by Solaris Fibre Channel drivers by
default and are not managed through end user- or application-initiated
operations. The \fBpwwn-lun-blacklist\fR  property in the \fBfp.conf\fR  file
is applied to the private loop device and \fBN_Port\fR point-to-point device in
the same way it is applied to a Fabric device.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.sp .6
.RS 4n
Force the \fBconfigure\fR change state operation to occur irrespective of the
\fBcondition\fR or \fBtype\fR. Refer to the above description of the
\fBconfigure\fR change state operation.
.RE

.sp
.ne 2
.na
\fB\fB-h\fR \fIap_id\fR\fR
.ad
.sp .6
.RS 4n
Obtain \fBfp\fR\(emtransport-specific help. Specify any \fBfp\fR attachment
point.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR \fIhardware_options\fR\fR
.ad
.sp .6
.RS 4n
The following hardware options are supported.
.sp
.ne 2
.na
\fBshow_SCSI_LUN\fR
.ad
.sp .6
.RS 4n
Lists ap_ids associated with each FCP SCSI LUN for discovered Fibre Channel
devices when specified with the \fBlist\fR option \fB-al\fR. Refer to the
previously mentioned description and example of FCP SCSI LUN level listing.
Device node creation is not supported on the FCP SCSI LUN level. See
\fBNOTES\fR.
.RE

All Fibre Channel devices are available to Solaris by default. Enabling only a
subset of Fabric devices available to Solaris by default can be accomplished by
setting the property "manual_configuration_only" in \fB/kernel/drv/fp.conf\fR
file. When "manual_configuration_only" in \fBfp.conf\fR is set, all Fabric
devices are not available to Solaris unless an application or an end user had
previously requested the device be configured into Solaris. The \fBconfigure\fR
state-change command makes the device available to Solaris. After a successful
\fBconfigure\fR operation on a Fabric device, the associated links are added to
the \fB/dev\fR namespace. The \fBunconfigure\fR state-change command makes a
device unavailable to Solaris.
.sp
When a Fibre Channel Fabric device is configured successfully to a host using
the \fB-c\fR \fBconfigure\fR operation, its physical \fBap_id\fR is stored in a
repository. When a Fibre Channel Fabric device is unconfigured using the
\fB-c\fR \fBunconfigure\fR operation, its physical \fBap_id\fR is deleted from
the same repository. All fabric devices are automatically enumerated by default
and the repository is used only if the \fBfp.conf\fR
"manual_configuration_only" property is set. Refer to \fBfp\fR(4D) for
additional details on the "manual_configuration_only" property.
.sp
You can specify the following commands with the \fB-c\fR option to control the
update behavior of the repository:
.sp
.ne 2
.na
\fB\fBforce_update\fR\fR
.ad
.sp .6
.RS 4n
For \fBconfigure\fR, the attachment point is unconditionally added to the
repository; for \fBunconfigure\fR, the attachment point is unconditionally
deleted.
.RE

.sp
.ne 2
.na
\fB\fBno_update\fR\fR
.ad
.sp .6
.RS 4n
No update is made to the repository regardless of the operation.
.RE

These options should not be used for normal \fBconfigure\fR and
\fBunconfigure\fR operations. See \fBWARNINGS\fR.
.sp
When a Fibre Channel device has multiple \fBFCP SCSI LUN\fRs configured and any
Solaris device associated with its \fBFCP SCSI LUN\fR is in the unusable
condition, the whole Fibre Channel device is reported as unusable. The
following option with the \fB-c\fR unconfigure command removes only Solaris
devices with the unusable condition for a Fibre Channel device.
.sp
.ne 2
.na
\fB\fBunusable_SCSI_LUN\fR\fR
.ad
.sp .6
.RS 4n
For \fBunconfigure\fR operation, any offlined device nodes for a target device
is removed.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fIlisting_options\fR\fR
.ad
.sp .6
.RS 4n
Refer to \fBcfgadm\fR(8) for usage information.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR \fIap_id\fR\fR
.ad
.sp .6
.RS 4n
No test commands are available at present.
.RE

.sp
.ne 2
.na
\fB\fB-x\fR \fIhardware_function\fR\fR
.ad
.sp .6
.RS 4n
No hardware specific functions are available at present.
.RE

.sp
.LP
All other options have the same meaning as defined in the \fBcfgadm\fR(8) man
page.
.SH EXAMPLES
.LP
\fBExample 1 \fRUnconfiguring a Disk
.sp
.LP
The following command unconfigures a disk:

.sp
.in +2
.nf
# cfgadm -c unconfigure c0::210000203708b606
.fi
.in -2
.sp

.LP
\fBExample 2 \fRUnconfigure all the Configured Disks under Single Attachment
Point
.sp
.LP
The following command unconfigures all configured disks under the attachment
point \fBc0\fR.

.sp
.in +2
.nf
# cfgadm -c unconfigure c0
.fi
.in -2
.sp

.LP
\fBExample 3 \fRConfiguring a Disk
.sp
.LP
The following command configures a disk:

.sp
.in +2
.nf
# cfgadm -c configure c0::210000203708b606
.fi
.in -2
.sp

.LP
\fBExample 4 \fRConfigure all the Unconfigured Disks under Single Attachment
Point
.sp
.LP
The following command configures all unconfigured disks under the attachment
point \fBc0\fR.

.sp
.in +2
.nf
# cfgadm -c configure c0
.fi
.in -2
.sp

.LP
\fBExample 5 \fRRemoving the Fibre Channel Fabric Device Attachment Point from
Repository
.sp
.LP
The following command unconditionally removes the fibre channel fabric device
attachment point from the Fabric device repository.

.sp
.in +2
.nf
# cfgadm -c unconfigure -o force_update c0::210000203708b606
.fi
.in -2
.sp

.LP
\fBExample 6 \fRRemoving Offlined Solaris Device Nodes for a Target Device
.sp
.LP
The following command removes offlined Solaris device nodes for a target
device:

.sp
.in +2
.nf
# cfgadm -c unconfigure -o unusable_SCSI_LUN c0::210000203708b606
.fi
.in -2
.sp

.SH FILES
.sp
.ne 2
.na
\fB\fB/usr/lib/cfgadm/fp.so.1\fR\fR
.ad
.sp .6
.RS 4n
Hardware-specific library for Fibre Channel Fabric device node management.
.RE

.sp
.ne 2
.na
\fB\fB/etc/cfg/fp/fabric_WWN_map\fR\fR
.ad
.sp .6
.RS 4n
Repository of physical \fBap_id\fRs of Fabric devices currently configured. It
is used only to reconfigure those Fabric devices at boot time. This repository
is only used when the "manual_configuration_only" \fB/kernel/drv/fp.conf\fR
file is set.
.RE

.sp
.ne 2
.na
\fB\fB/etc/rcS.d/fdevattach\fR\fR
.ad
.sp .6
.RS 4n
Reconfigures Fabric device(s) of which physical \fBap_id\fR is listed in
\fB/etc/cfg/fp/fabric_WWN_map\fR on boot time.
.RE

.SH SEE ALSO
.sp
.LP
.BR svcs (1),
.BR config_admin (3CFGADM),
.BR libcfgadm (3LIB),
.BR fp (4D),
.BR attributes (7),
.BR smf (7),
.BR cfgadm (8),
.BR svcadm (8)
.SH WARNINGS
.sp
.LP
Do not use hardware-specific options for the repository update under normal
\fBconfigure\fR/\fBunconfigure\fR operations. The hardware-specific options are
expected to be used when the node creation of a Fabric device fails at boot
time and the error condition is considered to be permanent. The
\fBunconfigure\fR command with \fBforce_update\fR hardware-specific option
unconditionally removes the attachment point of a failing Fabric device from
the repository.
.SH NOTES
.sp
.LP
For devices with unknown or no SCSI device type (for example, a Fibre Channel
Host Bus Adapter), the \fBconfigure\fR operation might not be applicable.
.sp
.LP
The \fBconfigure\fR and \fBunconfigure\fR commands operate on the Fibre Channel
device level which is represented by port WWN ap_id. If a Fibre Channel device
has multiple FCP SCSI LUNs configured, the \fBconfigure\fR command on the
associated port WWN ap_id results in creating a Solaris device for each \fBFCP
SCSI LUN\fR unless it is specified in the "pwwn-lun-blacklist" property in the
\fBfp.conf\fR file. The \fBunconfigure\fR command removes all Solaris devices
associated with the port WWN ap_id. The \fBFCP SCSI LUN\fR level ap_id is not
valid for the \fBconfigure\fR and \fBunconfigure\fR commands.
.sp
.LP
The deprecated \fBshow_FCP_dev\fR option has been replaced by the new
\fBshow_SCSI_LUN\fR option, and the deprecated \fBunusable_FCP_dev\fR option
has been replaced by the new \fBunusable_SCSI_LUN\fR option.
.sp
.LP
The \fBcfgadm_fp\fR service is managed by the service management facility,
\fBsmf\fR(7), under the service identifier:
.sp
.in +2
.nf
svc:/system/device/fc-fabric:default
.fi
.in -2
.sp

.sp
.LP
Administrative actions on this service, such as enabling, disabling, or
requesting restart, can be performed using \fBsvcadm\fR(8). The service's
status can be queried using the \fBsvcs\fR(1) command.
.sp
.LP
No administrative actions on this service are required for Fabric device
configuration once this service is started on boot time.