This chapter describes the optional command-line interface (CLI), lib_cmd. This tool is primarily intended for use for administering logical libraries in ACSLS, but some commands may be useful as an alternative to the ACSLS GUI or to cmd_proc in certain specific contexts. The lib_cmd CLI supports eject operations, including the ability to specify long (greater than 42) volume lists.
ACSLS introduced the concept of logical libraries in Version 8.0. Logical Library client operation is accessed using SCSI commands through the SCSI Media Changer Emulation (SMCE) over a fibre-channel connection. Clients can mount, dismount, enter and eject tapes, and manage their own tape inventory using the SMCE interface, operating as if the library were directly connected to the client application.
Until ACSLS 8.2, logical library administrative setup functions were accomplished through the ACSLS Graphical User Interface (also introduced in ACSLS 8.0). Such tasks include creating a logical tape library with a desired number of storage cells and tape-drive slots, establishing a client initiator-target relationship, assigning physical drives to the library, and assigning tape volumes.
These administrative tasks can also be accomplished through a UNIX command-line interface (CLI). The CLI extends the usability of logical libraries, providing a faster path to critical administrative functions, and providing the means to administer logical libraries using batch processing UNIX shell scripts.
lib_cmd
lib_cmd
lib_cmd [-f infile]
lib_cmd assign drive drive_id lib_id
lib_cmd assign volume [vol_id | vol-range] lib_id
lib_cmd unassign volume [ vol_id | vol-range ] lib_id
lib_cmd unassign drive lib_id logical_drive_id
lib_cmd create library lib_name backing_acs cell_capacity drive_capacity
lib_cmd create mapping initiator_id target_id library_id
lib_cmd edit initiator initiator_id alias
lib_cmd edit library lib_id [-n name ]
[-c capacity ]
[-d drive_slots ]
[-f volume_label_format [6|8p|8s|all]
[-x imp/exp_cell_count ]
lib_cmd edit target target_id alias
lib_cmd refresh initiator
lib_cmd refresh target
lib_cmd delete initiator initiator_id (y/n)
lib_cmd delete library lib_id (y/n)
lib_cmd delete mapping lib_id (y/n)
lib_cmd delete target target_id (y/n)
lib_cmd display drive [drive_id ]
[-p acs_id | all ]
[-l lib_id | all ]
[-t drive_type ]
[-u acs_id ]
lib_cmd display initiator
lib_cmd display library [ -p acs_id | all ]
[ -l lib_id | all ]
lib_cmd display mapping [ lib_id | all ]
lib_cmd display target
lib_cmd display volume [ vol_id ] | vol-range ]
[ -p acs_id | all ]
[ -l lib_id | all ]
[ -u acs_id ]
lib_cmd eject cap <cap_id> [-verbose] volume <vol_id...vol_id> | file <path_to_volume_list>
lib_cmd vary library lib_id [online|offline|diagnostic]
lib_cmd vary drive lib_id drive_id [online|offline|diagnostic]
lib_cmd [ exit | quit | log ]
The lib_cmd command-line utility is an alternative to the ACSLS GUI for managing and monitoring resources in ACSLS logical libraries. With lib_cmd, the ACSLS administrator can create, edit, or delete a logical library; assign or un-assign volumes or tape drives to a logical library; refresh initiators or targets; create initiator-target mappings for client communication; display the status of logical libraries; or display the status of volumes or drives within the configured physical or logical libraries.
In addition to logical library administration, lib_cmd offers a small set of general library commands that can be used in lieu of cmd_proc for displaying the contents of the library or for ejecting large amounts of volumes to a single cap (such as the SL3000 AEM).
These operations can be performed by any user in the ACSLS group, including root.
The lib_cmd can be operated in interactive mode or batch mode. Interactive mode is invoked by the command alone, without arguments.
lib_cmd
Interactive mode supports 'help' functions which list all of the possible sub-commands and arguments. Within the context of each sub-command, a list of possible arguments and options can be displayed upon request. When unsure of possible valid input strings, you can press <Enter> to get a list of all possible arguments for the immediate context.
No inter-activity is offered in batch mode to better support the use of this utility with user-generated scripts. In batch mode, all of the desired options and arguments must be submitted with the command. Otherwise, an error message is returned.
-f (Command file input specification)
When the -f option is requested, the utility executes the set of commands it finds in the specified input file. The input file must contain only fully-formed requests.
This section discusses the sub-commands.
assign drive drive_id lib_id
Assigns the specified drive to the specified library. The drive_id is expressed by the standard notation for drives in a physical library (acs,lsm,panel,drive). The argument lib_id is the assigned ID of the logical library. Logical library IDs begin at 1001 and increase incrementally as libraries are created.
unassign drive lib_id logical_drive_id
Removes the specified logical drive from the logical library configuration. The drive is specified by its logical address (starting at address 500). The logical library ID is a four digit number (starting at 1001).
assign volume vol_id | vol-range lib_id
Assigns a volume for exclusive use within a logical library. The volume is expressed by its standard six or bar-code label format. The library is expressed by its numerical logical library ID. The volume must be 'assignable'. That is, it is not already assigned, is un-owned, and is not mounted, reserved, in transit, or otherwise in use.
A range is specified by a low ACSII value string and high ASCII value string separated by a dash. When a volume range is requested, lib_cmd searches the backing ACS for volumes in the specified range. Any assignable volume in the range is assigned to the specified logical library.
unassign volume vol_id | vol-range lib_id
Removes a volume from the logical library inventory. The volume must reside in its home cell and cannot be reserved for a pending move operation.
A range is specified by a low ACSII value string and high ASCII value string separated by a dash. When a volume range is requested, lib_cmd searches the specified logical library for volumes in the specified range. Any assigned volumes in the range that are not in use are unassigned from the library.
create library lib_name backing_acs cell_capacity drive_capacity
Creates a new logical library. Following create library, four arguments are required in this order: library alias name (string); backing ACS ID (integer); number of storage cells (integer); and number of drive slots (integer).
create mapping initiator_id target_id library_id
Establishes an initiator-target (client-server) relationship for the specified library.
edit library lib_id [-n name ] [-c capacity ] [-d drive_slots ] [-f volume_label_format [6|8p|8s|all] [-x imp/exp_cell_count ]
Alters the configuration of an existing logical library. The specific library is expressed by its four-digit numerical ID. Any single option may be supplied and only that single field is changed using the argument supplied with the option. Options include:
-n library alias name
-c logical storage cell capacity
-d number of logical drive slots
-f volume label format
-x number of logical import/export (CAP) cells
Volume label format may be expressed with any of the following:
6 six character legacy volume labels
8p eight character prefixed with media type code
8s eight character suffixed with media type code
all accept all label formats
refresh initiator
Retrieves all initiators currently known to ACSLS.
refresh target
Retrieves all targets currently known to ACSLS.
delete initiator initiator_id (y/n)
Removes the specified initiator from the configuration. Confirmation (y) is required in order to commit the specified deletion.
delete library lib_id (y/n)
Removes the specified logical library from the ACSLS configuration. This creates a cascading delete, disassociating any assigned volumes and drives from the library. The library must be taken offline before the deletion is attempted. Removal fails if one or more of the logical volumes in the library are currently in use. Confirmation (y) is required in order to commit the specified deletion.
delete mapping lib_id (y/n)
Removes all initiator-target mappings from the specified logical library. The operation disables any current client connections. Confirmation (y) is required in order to commit the specified deletion.
delete target target_id (y/n)
Removes the specified target from the configuration. Confirmation (y) is required in order to commit the specified deletion.
display drive drive_id [-t drive_type ] [-p acs_id | all ] [-l lib_id | all ] [-u acs_id ]
Generates a summary of the specified drive, or all drives in the specified library.
The display includes the drives' physical and logical address, drive type, drive state, drive status, and if drive_status shows in_use, the VOLSER of the mounted cartridge is displayed.
------------------------ Example ---------------------------- $ lib_cmd display drive 0,0,10,1 Physical Logical Drive Drive Drive Mounted Location Address Type State Status Volume 0,0,10,1 1001:502 9840 Online in use RIFF21 -------------------------------------------------------------
If display drive all is submitted without options, the utility generates a listing of all volumes contained in each physical ACS.
If the -t option is passed, only drives of the specified drive type are displayed.
The -p option limits the display to drives in the specified physical ACS.
If the -l option is included, then only the drives assigned to the specified logical library are displayed. If all is specified following the -l option, then a display is generated showing all of the drives associated with each of the configured logical libraries.
The -u option displays only unassigned drives in the associated ACS. This option must be followed with an argument specifying the desired ACS.
display initiator
Generates a list of all initiators identified by ACSLS. Each initiator is listed by its world-wide name and the alias name.
display library [ -l lib_id | all ][ -p acs_id | all ]
Displays the attributes of the requested library ID. Specify -l for logical libraries or '-p' for physical ACSs.
If -l is specified, the utility generates a summary of the logical library configuration, as follows:
Numeric id, name, State (Desired state)
Backing ACS ID, State (Desired state).
Number of allocated import/export cells
Number of allocated drive slots
Number of assigned drives
Number of allocated storage cells
Number of free cells
Number of assigned volumes (of these, how many are inaccessible)
Volume Label Format
-----------------Example----------------------------------- ACS 1001 'logLib01' Offline (Desired Online) Backing ACS 0 Offline (Desired Online) 2 import/export cells 5 Tape Drive Slots 2 Tape Drives 999 Storage Cells 993 Free Cells 106 Volumes (6 Inaccessible): Volume Label Format: Six character (classic) --------------------------------------------------------
Inaccessible volumes are assigned volumes that are out of reach from the logical library, for any of the following reasons:
The volume has been ejected from the physical library.
The volume has been marked for eject by the client application.
The assigned volume resides in the physical library, but the logical library exceeds its storage capacity.
If the argument all is specified in lieu of the numeric lib_id, then the display repeats for each configured logical library. In batch mode, passing -l with no argument has the same effect as if the argument all were used.
When the option -p is specified with a specified ACS ID, the utility generates a display summarizing the library configuration for that ACS:
-------------------------------- Example ---------------------------------- $ lib_cmd display lib -p 0 Physical ACS 0 Online 56 Drives: 1 LSM: LSM Library LSM LSM Drive Vol Free Cell ID Type Status State Count Count Count 0,0 SL3000 Normal Online 56 62 4321 10 CAPs: ID Mode State Status Condition Size Availability 0,0,1 Manual Online Available Operative 26 shared 0,0,2 Manual Online Available Operative 26 shared 0,0,3 Manual Online Available Operative 26 shared 0,0,4 Manual Online Available Operative 26 shared 0,0,5 Manual Online Available Operative 26 shared 0,0,6 Automatic Online Available Operative 26 shared 0,0,7 Manual Online Available Operative 26 shared 0,0,8 Manual Online Available Operative 26 shared 0,0,9 Manual Online Available Operative 26 shared 0,0,10 Manual Online Available Operative 26 shared --------------------------------------------------------------------------
If the argument all is passed with the -p option, the display is repeated for each configured physical ACS.
The all argument is the default display for requests in batch mode. The -p option with no argument has the same effect as if all had been requested.
display mapping [ lib_id | all ]
Generates a list of initiator-target mappings for each library ID (or all libraries).
display volume [ vol_id ] | vol-range ] [ -p [ acs_id | all ] [ -l [ lib_id | all ] [ -u acs_id ]
Generates summary information for the specified volume or volume set:
----------------------Example -----------------------------
$ lib_cmd display volume ST0212
Volume media current physical logical
ID type status location address
ST0212 STK1R Home 0,0,2,6,0 1001:100
-------------------------------------------------------------
If the volume is mounted, the logical address and physical location reflects the address of the drive to which the volume is mounted. Otherwise, the volumes' logical and physical home addresses are listed. The logical address is populated only in cases where the volume has been assigned to a logical library.
A volume range can be specified by a low ACSII value string, and high ASCII value string separated by a dash. The display shows a status summary for each volume in the specified range.
If display volume all is submitted without options, the display shows all of the volumes contained in each physical ACS.
If the physical ACS ID is passed with the -p option, the list is limited to the volumes that reside in that specified physical ACS. If all is submitted with
-p, the volumes contained in all physical ACSs are displayed.
If the numeric id of a logical library (lib_id) is passed with the -l option, only the set of the volumes associated with that specific logical library are displayed. If the word all is passed with the -l option, the utility displays all of the volumes associated with each configured logical library.
The -u option generates a display that is limited to unassigned volumes contained in the specified physical ACS.
eject cap <cap_id> [-verbose] volume <vol_id...vol_id> | file <path_to_volume_list>
The lib_cmd eject supports eject operations, including the ability to specify long (greater than 42) volume lists. Volumes can be entered as user input, or by specifying the path to a text file containing a volume list. Multiple volumes can be entered on a line, in upper or lower case.
<cap_id>
It must be a specific and existing CAP in the library configuration.
Wild cards are not supported.
A list of CAPs is available.
[-verbose | -v]
The verbose option specifies that all volumes be displayed.
The default is NOT verbose and displays up to 10 volumes plus a count.
<vol_id>
One or more volume identifiers can be specified per line.
When running in interactive mode, press <Return> to end the list.
<path_to_volume_list>
Specify as relative or full path to the text file.
Multiple volume identifiers can be specified per line.
All comment lines (beginning with ”#”) or blank lines are ignored.
There is no known limit to the number of volumes that can be specified in either form. A single eject operation is carried out by ACSLS once all volumes have been supplied, and it keeps filling the specified CAP as needed until all possible volumes have been ejected.
The output display includes a reporting of volume counts (volumes specified, volumes ejected and/or not ejected). The verbose option produces output showing all volumes (by default, a 10-volume preview is produced for each list). For any volumes not ejected, a line indicating the volume identifier and the reason is displayed.
vary drive lib_id drive_id [online|offline|diagnostic]
Changes the desired state of the logical drive to the specified (online, offline, diagnostic) state.
vary library lib_id [online|offline|diagnostic]
Changes the desired state of the logical library to the specified (online, offline, diagnostic) state.
Using lib_cmd in batch mode allows you to perform more complex administrative tasks. For example, operations that assign or un-assign multiple volumes or multiple drives are often most efficiently accomplished in batch mode.
In this example, we will assign all of the 9840 drives on rail-2 of an SL8500 module to logical library 1002.
Using lib_cmd, list all of the unassigned drives in acs-0 and, using grep, filter only the 9840 drives that reside on rail-2 (acs-0, lsm-1).
$ lib_cmd display drive -u 0 | grep 9840 | grep 0,1,.,.
All of the unassigned drives on rail-2 will be listed in a five-field display:
Physical Logical Drive Drive Drive Mounted Location Address Type State Status Volume 0,1,1,0 9840 Online available 0,1,1,1 9840 Online available 0,1,1,2 9840 Online available 0,1,1,3 9840 Online available 0,1,1,4 9840 Online available
For our purposes, only the drive id is required from this display, so we print only the first field, using awk.
$ lib_cmd display drive -u 0 | grep 9840|grep 0,1,.,.|awk ’{print $1}'
0,1,1,0
0,1,1,1
0,1,1,2
0,1,1,3
0,1,1,4
Within the same awk print statement, we can add text to construct the necessary commands that assign the drives to logical library 1002.
$ lib_cmd display drive -u 0 | grep 9840|grep 0,1,.,.|awk ’{print ”assign drive ”$1”1002}'
assign drive 0,1,1,0 1002
assign drive 0,1,1,1 1002
assign drive 0,1,1,2 1002
assign drive 0,1,1,3 1002
assign drive 0,1,1,4 1002
Satisfied with the command text, we can now direct the output to a text file:
$ lib_cmd display drive -u 0 | grep 9840 | grep 0,1,.,. | awk '{print "assign drive "$1" 1002"}' > /tmp/assignDr
Finally, we can edit any changes to the command file, then execute the file using lib_cmd:
$ lib_cmd -f ./tmp./assignDr --ACSLS 8.2.0-- Copyright (c) 2012 Oracle and/or its affiliates. All rights reserved. Drive 0,1,1,0 now assigned to logLib02 at 1002:500 Drive 0,1,1,1 now assigned to logLib02 at 1002:501 Drive 0,1,1,2 now assigned to logLib02 at 1002:502 Drive 0,1,1,3 now assigned to logLib02 at 1002:503 Drive 0,1,1,4 now assigned to logLib02 at 1002:504
Using the lib_cmd display command, we confirm the assignment:
$ lib_cmd display drives -l 1002 ACS 1002 LOG lIB02:20 Drive Slots 5 Drives Physical Logical Drive Drive Drive Mounted Location Address Type State Status Volume 0,1,1,0 1002:500 9840 Online available 0,1,1,1 1002:501 9840 Online available 0,1,1,2 1002:502 9840 Online available 0,1,1,3 1002:503 9840 Online available 0,1,1,4 1002:504 9840 Online available