Managing a library by using the ltfsadmintool command

How to manage tape media by using the ltfsadmintool command and the options that can be specified with it.

Note: If your IBM Spectrum Archive™ Library Edition system operates with a non-IBM® tape library, follow the instructions available from the hardware supplier.

The ltfsadmintool command is used on Linux and Windows systems to perform the following operations:

Listing the cartridge location and status
Listing tape drives and drive status
Adding a cartridge to the library
Removing a cartridge from the library
Formatting a cartridge in the library
Adding a drive under Spectrum Archive Library Edition control
Removing a drive under Spectrum Archive Library Edition control
Checking and recovering or rolling back a cartridge in the library

The command can be used with a number of options that are described in the Available command options for ltfsadmintool section.

Attention:

Beginning with version 2.1.1, it is no longer necessary to specify the -s or --server option to connect to the local library server. Instead, this option is now set by default and needs to be modified only if there is a need to access a remote library.
By the Spectrum Archive Library Edition default configuration setting for authorizedclients, localhost is the only host that can connect to Spectrum Archive Library Edition. For more information about changing this setting to authorize other hosts, see Configuring default settings for adminchannel.
Note: Beginning with version 2.1.2.3, the default port number changed to 7600 from 2112.

For LTFS Storage Manager users: Set the port number to the previous default so that LTFS Storage Manager can work with Spectrum Archive Library Edition without any configuration change.

For Windows users:

On a Windows system, the ltfsadmintool command must be preceded by python, as shown in the examples throughout this topic.
On a Windows system, it is possibly to use PowerShell to run the ltfsadmintool. When Windows PowerShell is used for ltfsadmintool, any option that starts with a dash ( - ) needs to be in double quotation marks as shown the following example.
```
# python .\ltfsadmintool "-t" 1FA563L5 "-f" "--" "--force"
```

Listing the cartridge location and status

The -i option is used to list the cartridge and its status in the Spectrum Archive Library Edition inventory. In the following example, five cartridges are inventoried to the library. The first column shows the bar code label for each cartridge. The first cartridge with bar code label YAM060L5 is in slot 17 located in the import/export slot (I/O station). The next two cartridges, YAM061L5 and 068AGWL5, are in slots 256 and 257, located in the data transfer element (tape drive). The remaining two cartridges, E2T101L2 and YL0001L5, are in slots 4096 and 4097, located in the medium storage element (storage slot). The status of the first cartridge is "Unavailable." The status of the next two cartridges is "Valid LTFS", and the data in the folder is accessible. The status of the next cartridge is " Non-supported", and the cartridge is an older generation or a write-once, read-many cartridge. The status of the last cartridge is "Unknown".

Operating system Command

Linux

Operating system	Command
Linux	$ ltfsadmintool -i YAM060L5 -> Location: Import/Export slot, Address: 17, Capacity: 0GB, Remaining: 0GB, Status: Unavailable YAM061L5 -> Location: Data transfer element, Address: 256, Capacity: 1327GB, Remaining: 1326GB, Status: Valid LTFS 068AGWL5 -> Location: Data transfer element, Address: 257, Capacity: 1327GB, Remaining: 1326GB, Status: Valid LTFS E2T101L2 -> Location: Medium storage element, Address: 4096, Capacity: 0GB, Remaining: 0GB, Status: Non-supported YL0001L5 -> Location: Medium storage element, Address: 4097, Capacity: 0GB, Remaining: 0GB, Status: Unknown
Windows	# python ltfsadmintool -i YAM060L5 -> Location: Import/Export slot, Address: 17, Capacity: 0GB, Remaining: 0GB, Status: Unavailable YAM061L5 -> Location: Data transfer element, Address: 256, Capacity: 1327GB, Remaining: 1326GB, Status: Valid LTFS 068AGWL5 -> Location: Data transfer element, Address: 257, Capacity: 1327GB, Remaining: 1326GB, Status: Valid LTFS E2T101L2 -> Location: Medium storage element, Address: 4096, Capacity: 0GB, Remaining: 0GB, Status: Non-supported YL0001L5 -> Location: Medium storage element, Address: 4097, Capacity: 0GB, Remaining: 0GB, Status: Unknown

$ ltfsadmintool -i

YAM060L5 -> Location: Import/Export slot,       Address:   17, Capacity:      0GB, Remaining:      0GB, Status: Unavailable
YAM061L5 -> Location: Data transfer element,    Address:  256, Capacity:   1327GB, Remaining:   1326GB, Status: Valid LTFS
068AGWL5 -> Location: Data transfer element,    Address:  257, Capacity:   1327GB, Remaining:   1326GB, Status: Valid LTFS
E2T101L2 -> Location: Medium storage element,   Address: 4096, Capacity:      0GB, Remaining:      0GB, Status: Non-supported
YL0001L5 -> Location: Medium storage element,   Address: 4097, Capacity:      0GB, Remaining:      0GB, Status: Unknown

Windows

# python ltfsadmintool -i

YAM060L5 -> Location: Import/Export slot,       Address:   17, Capacity:      0GB, Remaining:      0GB, Status: Unavailable
YAM061L5 -> Location: Data transfer element,    Address:  256, Capacity:   1327GB, Remaining:   1326GB, Status: Valid LTFS
068AGWL5 -> Location: Data transfer element,    Address:  257, Capacity:   1327GB, Remaining:   1326GB, Status: Valid LTFS
E2T101L2 -> Location: Medium storage element,   Address: 4096, Capacity:      0GB, Remaining:      0GB, Status: Non-supported
YL0001L5 -> Location: Medium storage element,   Address: 4097, Capacity:      0GB, Remaining:      0GB, Status: Unknown

Table 1 shows the supported cartridge location and Table 2 shows the medium status.

Table 1. Supported location
Location	Description
Medium transport element	The cartridge is in a cartridge mover.
Medium storage element	The cartridge is in a storage slot.
Import/Export slot	The cartridge is in an I/O station.
Data transfer element	The cartridge is in a tape drive.

Table 2. Supported cartridge status
Cartridge Status	File system access	Description	Limited operation	How to recover the cartridge
Valid LTFS	Yes	The cartridge is valid. The index file is extracted to memory so that some file system requests, such as listing directory contents, can be processed without mounting a tape medium to a drive.	Adding the cartridge by using the ltfsadmintool command with the -a option is not allowed for this cartridge because it is already added to the file system. Moving the cartridge to the I/O station by using the ltfsadmintool command with the -m ieslot option is not allowed. The cartridge must be removed from the file system by using the ltfsadmintool command with the -r option before you move it to the I/O station.
In Progress	Yes	The cartridge is being moved by Spectrum Archive from storage slot to drive or from drive to storage slot.	No operation by using the ltfsadmintool command is allowed. When a cartridge is being moved, all I/O requests to the target cartridge are blocked.
Unknown	Yes	The cartridge contents are unknown. The index file must be read on the tape medium before most file system requests can be processed.	Adding the cartridge by using the ltfsadmintool command with the -a option is not allowed for this cartridge because it is already added to the file system. Moving the cartridge to I/O station by using the ltfsadmintool command with the -m ieslot option is not allowed. The cartridge must be removed from the file system by using the ltfsadmintool command with the -r option before you move it to the I/O station.
Write protected	Read-only	The cartridge is physically (or logically) in a write-protected or read-only state because of an absence of capacity. This status is reported only when the cartridge is "Valid." If the cartridge is in any state other than "Valid," the status is reported even though the cartridge is write protected.	Adding the cartridge by using the ltfsadmintool command with the -a option is not allowed for this cartridge because it is already added to the file system. Moving the cartridge to the I/O station by using the ltfsadmintool command with the -m ieslot option is not allowed. The cartridge must be removed from the file system by using the ltfsadmintool command with the -r option before you move it to the I/O station. Formatting the cartridge is not allowed because the cartridge is read-only.
Warning	Yes	A medium error is detected while the medium is being read. However, the operations that can be performed by using this cartridge are the same as for a "Valid" cartridge. This status is reported only when the cartridge is "Valid." If the cartridge is any state other than "Valid," the status is reported even though the cartridge reports a medium error.	Adding the cartridge by using the ltfsadmintool command with the -a option is not allowed for this cartridge because it is already added to the file system. Moving the cartridge to the I/O station by using the ltfsadmintool command with the -m ieslot option is not allowed. The cartridge must be removed from the file system by using the ltfsadmintoolcommand with the -r option before you move it to the I/O station.	A medium error might have occurred. Check the system logs or terminal console outputs. The cartridge status returns to "Valid" by physically removing the medium from the library, then adding it to the library again.
Critical	Read-only	The index on memory is dirty. Data might not be able to be written to the tape medium due to the medium status. The volume is dropped to read-only and the drive is locked so that the cartridge cannot be removed. The drive scheduler excludes the drive from its scheduling to avoid an unexpected cartridge removal with an index write failure. The user can perform any backup operation in this state. When the backup is completed, the user can remove the cartridge from the drive by unlocking the drive with the `-r` option. The cartridge status then changes to an "Error" state.	No operation that uses the ltfsadmintool command is allowed, except removing the cartridge from the file system by using the ltfsadmintool command with the -r option.	Back up the data on the cartridge to another tape medium or hard disk drive. When the backup is completed, remove the cartridge from the file system with the `-r` option. If the cartridge is not removed, file system performance is degraded because the tape drive with the cartridge is locked.
Unavailable	No	The cartridge has no problem, but is removed from Spectrum Archive. The -a option might change the cartridge status to "Valid," "Unknown," "Write Protected," or "Warning".	Removing the cartridge by using the ltfsadmintool command with the -r option is not allowed because the cartridge is not added to the file system.
Invalid LTFS	No	The cartridge is inconsistent with the LTFS format and must be checked by using the -c option.	Removing the cartridge by using the ltfsadmintool command with the -r option is not allowed because the cartridge is not added to the file system.	Check the cartridge. For more information, see Checking and recovering or rolling back a medium in the library. If an error message returns, see Problem analysis procedures on a Linux system to find a solution to the problem.
Unformatted	No	The cartridge is not formatted and must be formatted by using the -f option.	Removing the cartridge by using the ltfsadmintool command with the -r option is not allowed because the cartridge is not added to the file system.	Format the cartridge before you use it. For more information, see Formatting a medium in the library.
Inaccessible	No	The cartridge is not allowed to move in the library or might be stuck in the drive. If the cartridge is stuck in the drive, the drive scheduler excludes this drive from its scheduling.	No operation that uses the ltfsadmintool command is allowed.	The cartridge might be stuck in the library or in one of the tape drives. The tape library or a tape drive must be repaired.
Error	No	The cartridge status is "Critical" and the cartridge is removed from the library. Spectrum Archive does not allow the cartridge to be added to the file system again.	No operation that uses the ltfsadmintool command is allowed, except moving the cartridge to another slot with the -m option.	Check the system logs or terminal console outputs to locate the error message. For more information, see Problem analysis procedures on a Linux system to find a solution to the problem. The cartridge status returns to "Valid" by physically removing the medium from the library, then adding it to the library again.
Non-supported	No	The cartridge is an older generation, an encrypted cartridge in a library with an enabled encryption feature, or a write-once, read-many (WORM) cartridge.	No operation that uses the ltfsadmintool command is allowed, except moving the cartridge to another slot with the -m option.	Spectrum Archive Library Edition supports the following tape cartridges: LTO 6 LTO 5 3592 Advanced data (JC) 3592 Extended data (JB) 3592 Economy data (JK) Cleaning and WORM cartridges are not supported. Check that the bar code label of the cartridge is properly set. Encrypted cartridges can be accessed by using Spectrum Archive Library Edition only when they are in a library with an enabled encryption feature.
Duplicated	No	Two cartridges exist with the same bar code.	No operation that uses the ltfsadmintool command is allowed.	Export one of the cartridges with the same bar code label from the library.
Cleaning	No	The cartridge is a cleaning cartridge.	No operation that uses the ltfsadmintool command is allowed, except moving the cartridge to another slot with the -m option.

Listing tape drives and drive status

The -I option is used to list the tape drives and their status in the Spectrum Archive Library Edition inventory. The following example shows a valid tape drive /dev/IBMtape0 attached to the tape library "1168001144":

Operating system	Command
Linux	`$ ltfsadmintool -I 1168001144 -> Device: /dev/IBMtape0 [ULT3580-TD5], Status: Available`
Windows	`# python ltfsadmintool -I 1168001144 -> Device: 6.0.0.1 [ULT3580-TD5], Status: Available`

Notes:

The drive serial number in this example is 1168001144.
Beginning with code level 2.1.2, the drive type is also displayed.

Table 3 shows the supported drive types and how they are displayed. Table 4 shows the supported drive status.

Table 3. Supported drive types
Drive type	Description
`[ULT3580-TD6]`	IBM LTO Ultrium 6 tape drive
`[ULTRIUM-TD6]`	IBM LTO Ultrium 6 tape drive
`[ULTRIUM-HH6]`	IBM LTO Ultrium 6 tape drive Half High
`[ULT3580-HH6]`
`[HH LTO Gen 6]`
`[ULT3580-TD5]`	IBM LTO Ultrium 5 tape drive
`[ULTRIUM-TD5]`	IBM LTO Ultrium 5 tape drive
`[ULTRIUM-HH5]`	IBM LTO Ultrium 5 tape drive Half High
`[ULT3580-HH5]`
`[HH LTO Gen 5]`
`[03592EH8]`	IBM TS1150 tape drive
`[03592E08]`	IBM TS1150 tape drive
`[03592EH7]`	IBM TS1140 tape drive
`[03592E07]`	IBM TS1140 tape drive

Table 4. Supported drive status
Drive status	Description	How to recover the tape drive
Available	The drive is available.	No recovery is necessary.
Unavailable	The drive is removed from the library inventory by using the ltfsadmintool -r command.	The status changes to "Available" by adding the drive to the library inventory by using the ltfsadmintool -a command.
Error	The tape drive reports a hardware error.	Check the drive error messages on the library operator panel or web GUI. For instructions on how to use the operator panel or web interface, download the applicable guide. For more information, see Accessing operator guides for tape libraries and drives. See the same guide and the tape drive operator guide for troubleshooting information.
Locked	The cartridge is in a critical condition. The tape drive for the cartridge is preserved for maintenance.	Back up the data on another medium. Then, remove the cartridge from the library inventory by using the ltfsadmintool -r command with the -t or --tape-id option to change the status to "Available".
Not installed	If a tape drive is physically removed from the library, the tape drive disappears from the library inventory. But if the library reports an error condition when a drive is removed, the drive status changes to a "Not installed" status.	Check the tape library error messages on the library operator panel or web GUI. For instructions on how to use the operator panel or web interface, download the applicable guide. For more information, see Accessing operator guides for tape libraries and drives. Also, see the same guide for troubleshooting.

Adding a cartridge to the library

The combination of the -a option and -t option is used to add a cartridge to the library. The following example shows how to add a cartridge by using this combination of options:

Operating system	Command
Linux	`$ ltfsadmintool -t D00661L5 -a`
Windows	`# python ltfsadmintool -t D00661L5 -a`

The following example shows all cartridges that are being added from the I/O station:

Operating system	Command
Linux	`$ ltfsadmintool -t @ieslot -a`
Windows	`# python ltfsadmintool -t @ieslot -a`

When a cartridge is added, the volume serial number (VOLSER) is recognized by the tape library as a subdirectory of the file system.

Attention: An unformatted medium cannot be added to the library. Format the medium before you add it by specifying the -f option.

Removing a cartridge from the library

The combination of the -r option and -t option is used to remove a cartridge from the library. The following example shows a cartridge that is being removed by using this combination of options:

Operating system	Command
Linux	`$ ltfsadmintool -t D00661L5 -r`
Windows	`# python ltfsadmintool -t D00661L5 -r`

The following example shows a cartridge that is being removed to the I/O station:

Operating system	Command
Linux	`$ ltfsadmintool -t D00661L5 -r -m ieslot`
Windows	`# python ltfsanmintool -t D00661L5 -r -m ieslot`

If the cartridge is successfully removed, the subdirectory corresponding to the medium VOLSER disappears.

Formatting a cartridge in the library

The -f option can be specified when one or more cartridges in the Spectrum Archive Library Edition inventory must be formatted. This operation is performed when the ltfsadmintool calls mkltfs. Options for mkltfs can be initiated by adding the -- tag to the command line. In the following example, the mkltfs option --rules=size=10M is added after the -- tag to specify the file placement policy that copies the matching files to the index partition. The ltfsadmintool passes the -rules=size=10M option to the mkltfs command.

Operating system	Command
Linux	`$ ltfsadmintool -t D00661L5,D00662L5 -f -- --rules=size=10M`
Windows	`python ltfsadmintool -t D00661L5,D00662L5 -f -- --rules=size=10M`

For more information, see Formatting a medium in the library.

Note: To format a cartridge by using logical block protection (LBP), the -o scsi_lbprotect=on option must be specified with the ltfsadmintool command. For more information, see Enabling logical block protection.

Adding a drive under Spectrum Archive Library Edition control

The combination of the -a option and -d option is used to add a drive under Spectrum Archive Library Edition control. The following example shows a drive that is being added by using this combination of options:

Operating system	Command
Linux	`$ ltfsadmintool -d 1168001144 -a`
Windows	`# python ltfsadmintool -d 1168001144 -a`

If the drive is successfully added, the drive status changes to "Available" on the next drive inventory.

Removing a drive under Spectrum Archive Library Edition control

The combination of the -r option and -d option is used to remove a drive under Spectrum Archive Library Edition control. The following example shows a drive that is being removed by using this combination of options:

Operating system	Command
Linux	`$ ltfsadmintool -d 1168001144 -r`
Windows	`# python ltfsadmintool -d 1168001144 -r`

If the drive is successfully removed, the drive status changes to "Unavailable" on the next drive inventory.

Checking and recovering or rolling back a cartridge in the library

The -c option can be specified to check the medium when one or more cartridges in the library are inconsistent, and it becomes necessary to perform a check and recover operation. In this case, the ltfsadmintool calls ltfsck. The user also has access to a list of other ltfsck options. For more information, see Available command options for ltfsadmintool. In the following example, both ltfsck options, --list-rollback-points and --full-index-info, are added after the -- tag to get a list of rollback points. The ltfsadmintool then passes those --list-rollback-points and --full-index-info options to ltfsck.

Operating system	Command
Linux	`$ ltfsadmintool -t D00661L5,D00662L5 -c -- --list-rollback-points --full-index-info`
Windows	`# python ltfsadmintool -t D00661L5,D00662L5 -c -- --list-rollback-points --full-index-info`

For more information, see Checking and recovering or rolling back a medium in the library.

Note: To check a cartridge by using logical block protection (LBP), the -o scsi_lbprotect=on option must be specified with the ltfsadmintool command. For more information, see Enabling logical block protection.

Available command options for `ltfsadmintool`

The following options are available:

-a, --add

Add the tapes or drives that are identified by --tape-id or --drive-id to the library.

Note: The --drive-id option works only on TS3500 and TS4500 tape libraries. To add a tape drive to other libraries, follow the instructions in the topic TS2900 tape autoloader and TS3100, TS3200, TS3310, and TS4300 tape libraries.

-c, --volume-check [options...]

Check the volumes that are specified by the --tape-id option in the library.

Optional ltfsck parameters can be passed along in [options]. When no option is specified, the hyphen (-) is not required.

-d, --drive=<id>[,id...]

A (comma-separated list of) drive serial numbers.

-f, --volume-format [options...]

Format the volumes that are specified by the --tape-id option in the library.

Optional mkltfs parameters can be passed along in <options>. When no option is specified, the hyphen (-) is not required.

-F, --force-inventory

With the -i or -I option, force the library to get the most current inventory.

-h, --help

This help.

-i, --tape-inventory

Get an inventory of tapes in the library.

-I, --drive-inventory

Get an inventory of drives in the library.

-m, --move-to=<target>

Move the tapes that are specified by the --tape-id option to the specified target.

Available targets are as follows:

homeslot: cartridge's home slot in the library
ieslot: any available import/export slot

Note: If this option is specified without the -a or -r option, only the homeslot target is available. If ieslot is specified as the target when the -a and -r options are not specified, this option is ignored.

-o scsi_lbprotect=on

Enable LBP for all tape drives in the tape library.

-o scsi_lbprotect=off

Disable LBP for all tape drives in the tape library (default).

-p, --password=<password>

Authentication password.

-P -get-data-placement

Get the data placement policy of the tapes that are identified by using the--tape-id option.

-q, --quiet

Operate in quiet mode.

-r, --remove

Remove the tapes or drives that are identified by --tape-id or –drive-id from the Spectrum Archive Library Edition inventory.

Note: Dynamic drive replacement is only supported on TS3500 and TS4500 tape libraries. To physically remove a tape drive from other libraries, unmount the library from Spectrum Archive Library Edition on other tape libraries. For more information, see TS2900 tape autoloader and TS3100, TS3200, TS3310, and TS4300 tape libraries.

-s, --server <hostname:port>

Server to connect to

This option can be omitted when the tape library exists on the local machine and the port number to the library is not changed while you mount a library by using the ltfs command with the -o admin_port option.

-t, --tape-id= <id>[,id...]

A comma-separated list of bar codes. A special identifier @ieslot also can be used to indicate that all tapes in the import/export slot were added by the operator.

-v, --version

Show version.

Attention: The ltfsadmintool might not work properly while the tape library or tape drive firmware is updating.