Copyright 2023 Peter Tribble
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]
/usr/sbin/cfgadm [-f] [-n | -y] [-v] [-o hardware_options] -c function ap_id [ap_id]
/usr/sbin/cfgadm [-v] [-a] [-s listing_options] [-o hardware_options] [-l [ap_id]]
/usr/sbin/cfgadm [-v] [-o hardware_options] -h [ap_id]
For Fibre Channel Fabric device node management, each fp 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 ap_ids. Two types of ap_ids are defined: logical and physical. The physical ap_id is based on the physical pathname. The logical ap_id is a shorter, more user-friendly name. For fp port nodes, the logical ap_id is the corresponding disk controller number. For example, c0 is a typical logical ap_id.
Fibre Channel devices are named with a port World Wide Name (WWN). If a disk device is connected to controller c0, its ap_id can be:
c0::50020f2300006077
where 50020f2300006077 identifies the port WWN of a specific Fibre Channel device.
Each device on the Fibre Channel private loop port, Fabric port or public loop port is probed and made available to the operating system by default. Devices connected to the Fibre Channel Fabric port or public loop port can be made unavailable to the operating system 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 /usr/lib/cfgadm/fp.so.1 library to enable libcfgadm to provide interfaces to accomplish this task.
The list of currently connected Fabric devices is generated in the form of the attachment point.
A simple listing of attachment points in the system includes attachment points at fp port nodes but not Fibre Channel devices. The following example uses the list option -l to list Fibre Channel fp port nodes:
# cfgadm -l 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
The following example uses the -a flag in addition to -l to list Fibre Channel devices connected to fp ports.
# cfgadm -al 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
In this example, the fc-fabric type of ap_id c0 indicates that the fp port is connected to Fabric. For an fp port with a Fabric-related type such as fc-fabric and fc-public, device node creation happens by default at the boot time and can be managed by the cfgadm configure and unconfigure operations. The fc-private type of ap_id c1 indicates that fp port is connected to private-loop and device node creation happens by default as well. The fc-pt_to_pt type of ap_id c2 indicates that the fp port is directly connected to another N_port and device node creation also happens by default. The fc type of ap_id c3 indicates that nothing is attached to fp port c2. The Type field of a Fibre Channel device ap_id shows the SCSI device type of LUN 0 in the device.
A Fibre Channel device with multiple FCP SCSI LUNs is configured and each FCP SCSI LUN is available as a device. Suppose that ap_ids c0::50020f2300006077 and c0::50020f23000063a9 represent Fibre Channel devices with multiple FCP SCSI LUNs.
The following example shows how to list ap_ids with FCP SCSI LUN information:
# cfgadm -al -o show_SCSI_LUN
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
In this example, the ap_id c0::50020f2300006077,0 identifies the FCP SCSI LUN 0 of the Fibre Channel device which is represented by port WWN 50020f2300006077. The Fibre Channel device is reported to have 4 FCP SCSI LUNs and they are all configured. 4 FCP SCSI LUN level ap_ids associated with port WWN 50020f2300006077 are listed. The listing also displays FCP SCSI LUNs for unconfigured Fibre Channel devices. The Fibre Channel device represented by c0::50020f2300005f24 is reported to have two FCP SCSI LUNs. The configure operation on c0::50020f2300005f24 creates two devices. The Type field of FCP SCSI LUN level ap_ids show the SCSI device type of each LUN. When a Fibre Channel device has different device type LUNs, the Type field reflects that.
The receptacle and occupant state for attachment points at the fp port have the following meanings: configured
One or more devices configured on the fp port
fp port active
fp port quiesced (IO activity is suspended)
Not applicable
No devices configured on the fp port
The state for individual Fibre Channel devices on an fp port: configured
Device is configured and is available for use
fp port to which the device is connected to is active
fp port to which the device is attached is quiesced
Device is available to be configured
The condition field for attachment points at the fp port has the following meanings: failed
An error condition has prevented the fp port from being able to detect the presence or type of a Fibre Channel connection.
The condition field for individual Fibre Channel devices on an fp port has the following meanings: failed
An error is encountered while probing a device on Fabric.
A device was configured on a host and its state 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.
A device has been configured on the host, but is currently offline or failed.
The unknown condition indicates that probing a device on Fabric completed without an error and the device state within the host is normal if the device was configured previously. The internal condition of the device cannot be guaranteed.
The following options are supported: -c function
The following generic commands are defined for the fp-transport-specific library: For Fibre Channel device attachment points on the fc-fabric type fp port attachment point, the following configuration state change operations are supported: configure
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 (-f) can be used to force the fp 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 fp.conf 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 Dynamic Reconfiguration on the controller that they are connected through. Refer to fp(4D) for additional details on the "pwwn-lun-blacklist" property.
Unconfigure a Fibre Channel Fabric device from a host. This device stays unconfigured until the next reboot or 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 fp.conf file. If the property is set, the device remains unconfigured after reboot. Refer to fp(4D) for additional details on the "manual_configuration_only" property.
Force the configure change state operation to occur irrespective of the condition or type. Refer to the above description of the configure change state operation.
Obtain fp-transport-specific help. Specify any fp attachment point.
The following hardware options are supported. show_SCSI_LUN
Lists ap_ids associated with each FCP SCSI LUN for discovered Fibre Channel devices when specified with the list option -al. 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 NOTES.
For configure, the attachment point is unconditionally added to the repository; for unconfigure, the attachment point is unconditionally deleted.
No update is made to the repository regardless of the operation.
For unconfigure operation, any offlined device nodes for a target device is removed.
Refer to cfgadm(8) for usage information.
No test commands are available at present.
No hardware specific functions are available at present.
All other options have the same meaning as defined in the cfgadm(8) man page.
The following command unconfigures a disk:
# cfgadm -c unconfigure c0::210000203708b606
Example 2 Unconfigure all the Configured Disks under Single Attachment Point
The following command unconfigures all configured disks under the attachment point c0.
# cfgadm -c unconfigure c0
Example 3 Configuring a Disk
The following command configures a disk:
# cfgadm -c configure c0::210000203708b606
Example 4 Configure all the Unconfigured Disks under Single Attachment Point
The following command configures all unconfigured disks under the attachment point c0.
# cfgadm -c configure c0
Example 5 Removing the Fibre Channel Fabric Device Attachment Point from Repository
The following command unconditionally removes the fibre channel fabric device attachment point from the Fabric device repository.
# cfgadm -c unconfigure -o force_update c0::210000203708b606
Example 6 Removing Offlined Device Nodes for a Target Device
The following command removes offlined device nodes for a target device:
# cfgadm -c unconfigure -o unusable_SCSI_LUN c0::210000203708b606
Hardware-specific library for Fibre Channel Fabric device node management.
Repository of physical ap_ids 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" property is set in the /kernel/drv/fp.conf file. See fp(4D).
The configure and unconfigure 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 configure command on the associated port WWN ap_id results in creating a device for each FCP SCSI LUN unless it is specified in the "pwwn-lun-blacklist" property in the fp.conf file. The unconfigure command removes all devices associated with the port WWN ap_id. The FCP SCSI LUN level ap_id is not valid for the configure and unconfigure commands.
The deprecated show_FCP_dev option has been replaced by the new show_SCSI_LUN option, and the deprecated unusable_FCP_dev option has been replaced by the new unusable_SCSI_LUN option.
The cfgadm_fp service is managed by the service management facility, smf(7), under the service identifier:
svc:/system/device/fc-fabric:default
Administrative actions on this service, such as enabling, disabling, or requesting restart, can be performed using svcadm(8). The service's status can be queried using the svcs(1) command.
No administrative actions on this service are required for Fabric device configuration once this service is started on boot time.