stfsdisk

Controls the SAN File System volumes (disks) that a client can access.

Read syntax diagramSkip visual syntax diagram
>>-stfsdisk--+-------------------------------------------+------>
             +- -add--+-------------+--disk_file_name----+
             |        '-client_name-'                    |
             +- -remove--+-------------+--disk_file_name-+
             |           '-client_name-'                 |
             +- -query--+-------------+------------------+
             |          '-client_name-'                  |
             '- -discover--+-------------+---------------'
                           '-client_name-'

>--+-------------+---- -kmname--kernel_ext_name----------------><
   '-client_name-'

Parameters

–add
Adds the specified disk-specific file name to the disk-candidate list.
–remove
Removes the specified disk-specific file name from the disk candidate list. If the disk-specific file name is not in the list, this command does nothing, but does not consider it an error.
–query
Displays the list of disk-specific file names in the current disk-candidate list and the status of each. Possible status values are:
ACTIVE
Indicates that the disk is a valid SAN File System user-data volume and is available to the client to perform file reads and write operations.
INACTIVE
Indicates that the disk is not a valid SAN File System user-data volume and is not available to the client to perform file reads and writes. A disk can be inactive if the disk does not contain a SAN File System label or if the disk's SAN File System label says it is something other than a user-data volume.
–discover
Rebuild the database of usable disks by going through the current candidate-disk list and attempting to access each disk, determine if it is a valid SAN File System user-data volume, and read its SAN File System global disk ID. If a disk has become accessible or inaccessible, or changed its identity since the last time this disk-discovery procedure was run, the virtual client updates its candidate-disk list accordingly.

This parameter causes the disk-discovery procedure to start. The procedure typically ends before the disk-discovery procedure completes. While the disk-discovery procedures are in progress, any file-system access that would fail because the virtual client cannot find a specific disk will wait until the disk-discovery procedure completes, and then proceed on the basis of the new disk-accessibility information.

disk_file_name
Specifies the file name of the disk to add to or remove from the disk candidate list. This must be a raw disk file such as /dev/rhdisk5 or /dev/rvpath5.
client_name
Specifies the name of the virtual client whose disk-access you are controlling.
–kmname kernel_ext_name
Identifies kernel-extension name of the file-system-driver instance associated with the client.

The file-system driver is loaded as a kernel extension. To identify the instance of the file-system drive, you identify the kernel extension. The kernel-extension name is the same as the name and location of the file-system driver that was used to load the driver (for example, /usr/tank/client/bin/stfs for AIX®). Note that the kernel extension name might not be unique.

Prerequisites

You must have root privileges to use this command.

Description

A client reads and writes files by accessing the disks on which the file data resides. To control which disks that a client can access, SAN File System identifies that disk by a SAN File System global disk identifier, and the disk-access subsystem associates that identifier with the name that the AIX operating system uses to identify that disk. The disk-access subsystem maintains a database that correlates global-disk identifiers with AIX device numbers. When the client needs to access a data block of a file, it consults that database.

The disk-access subsystem maintains the database by reading certain disks at certain times and looking for a SAN File System global disk identifier. If it finds the identifier, it determines whether the disk is a SAN File System user-data volume. If the disk is a volume, it adds the disk to its database.

The set of disks that the disk-access subsystem searches is called the disk-candidate list. The stfsclient command creates the disk-candidate list when it creates the virtual client. You can modify the list using the –add and –remove parameters.

The candidate-disk list is a list of unique disk-special file names. Because a disk can be referred to by more than one disk-special file name, the list is not strictly a list of unique devices. Actually examining disks and updating the database of valid user-data volumes is separate from maintaining the candidate-disk list.

When you add a disk to the candidate-disk list, the client immediately tries to read it and adds it to the database. But the disk becomes and stays a candidate regardless of the results of that operation.

You can force the client to rescan the entire list of candidate disks using the –discover parameter. The client updates its database of user-data volumes according to the results of this discovery, adding and removing disks as necessary. The results of the discovery do not affect the candidate-disk list, however.

Note that device file names can change as the client runs. Such a change has no effect on the client unless something causes a disk-discovery procedure to run. For example, if you add /dev/rhdisk35 as a candidate disk, and the client successfully identifies it as a SAN File System user-data volume, and then you delete /dev/rhdisk35, the client continues accessing that disk as before. The disk /dev/rhdisk35 continues to be a candidate. But the next time a disk-discovery procedure runs, the candidate will be found invalid and the client will no longer have access the disk.

Example

Query the disk-candidate list The following example queries disk-candidate list and displays the status of each disk:
stfsdisk -query -kmname /usr/tank/client/bin/stfs

Parent topic: AIX-client commands

Related reference
rmstclient
stfsclient
stfsdriver
stfsmount
stfsumount

Library | Support | Terms of use | Feedback
(C) Copyright IBM Corporation 2003, 2004. All Rights Reserved.
IBM TotalStorage SAN File System v2.2