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.
- 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
- 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.
- 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 |
|
Windows |
|
Table 1 shows the supported cartridge location and Table 2 shows the medium status.
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. |
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:
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 |
|
Windows |
|
- 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.
Drive type | Description |
---|---|
[ULT3580-TD6] | IBM LTO Ultrium 6 tape drive |
[ULTRIUM-TD6] | |
[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] | |
[ULTRIUM-HH5] | IBM LTO Ultrium 5 tape drive Half High |
[ULT3580-HH5] | |
[HH LTO Gen 5] | |
[03592EH8] | IBM TS1150 tape drive |
[03592E08] | |
[03592EH7] | IBM TS1140 tape drive |
[03592E07] |
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 |
|
Windows |
|
Operating system | Command |
---|---|
Linux |
|
Windows |
|
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 |
|
Windows |
|
Operating system | Command |
---|---|
Linux |
|
Windows |
|
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 |
|
Windows |
|
Adding a drive under Spectrum Archive Library Edition control
Operating system | Command |
---|---|
Linux | $ ltfsadmintool -d 1168001144 -a |
Windows | # python ltfsadmintool -d 1168001144 -a |
Removing a drive under Spectrum Archive Library Edition control
Operating system | Command |
---|---|
Linux | $ ltfsadmintool -d 1168001144 -r |
Windows | # python ltfsadmintool -d 1168001144 -r |
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 |
|
Windows |
|
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.