This chapter describes the OpenVault cartridge life cycle and the administrative tools used to manage it. More information on the administrative tools is available in the man page for each command.
The life cycle of a cartridge is the chain of states and events that affect a cartridge from the time that it first becomes part of a system until in ceases to be a part of that system. The major events in the life of a cartridge include:
Physical and logical introduction of the cartridge into the system
Assignment of ownership (who or what application gets to use the cartridge)
Use of the cartridge by applications
Recycling of a cartridge when one owner no longer needs it
Disposal of the cartridge either by sending it to another system or removing it for disposal when the media reaches the end of its service life
Figure 3-1, illustrates the life cycle of a cartridge:
During this life cycle, these are the possible cartridge states:
| Unknown | If no information is available about a cartridge, then its state is “unknown.” A new cartridge (one that OpenVault has not seen before) is in the unknown state. OpenVault needs to become aware of a cartridge before it can do anything with it. |
| Defined | OpenVault needs to have certain information about a cartridge before it can be used. The majority of the information must come from a person--the OpenVault administrator--who knows what the cartridge is and can describe it to OpenVault. This includes the physical cartridge label (PCL, usually an optically readable label on the cartridge), the cartridge type, and information on the number of sides on the cartridge. All this information constitutes the cartridge definition. |
| Available | In addition to knowing that a cartridge exists, OpenVault needs to know where information can be written on the cartridge, and whether an application has reserved that area. This information comprises the partition description for the cartridge. Once this information is entered the cartridge may be considered “available.” That is, the cartridge may be assigned (“allocated”) to an application that needs one. |
| Allocated | For applications, OpenVault is a service for allocating and mounting volumes. Applications make a request to write data in a known place and manner. That place is a logical volume on a partition on a cartridge. The application asks the server to allocate a volume for it. The server looks for cartridges with available partitions that are not used by any application. When it finds one, the server modifies cartridge ownership information to show that the requesting application has control over that cartridge. It marks the partition as unavailable, and creates volume information to describe the location of data stored on the cartridge. At this point the cartridge is considered “allocated” and the volume can be used as long as the application desires to do so. |
| Deallocated | When an application is finished with a cartridge, it can “deallocate” it. The server removes volume information for the cartridge; so the application can no longer request mounting of that volume. Information on data location is deleted and becomes unavailable. The application still owns the cartridge, however, giving the administrator some control over how to handle the cartridge thereafter. The “owned and deallocated” state can be used as a marker for a cartridge to be erased, destroyed (if the media is at the end of its useful life), or recycled without erasure. An administrator (or an administrative application) can mark the cartridge as available again without doing anything else to it. The cartridge becomes available for volume allocation, but only to the application that owns it (ownership remains as before). The cartridge must be recycled before other applications can use it. |
| Recycled | An administrator (or an administrative application) may recycle deallocated cartridges. This entails marking the cartridge as available for allocation and removing ownership information. Once the cartridge is recycled, it is again in the “defined” and “available” state, but other information about the cartridge may be retained. This could include a count of the number of times that cartridge has been written so that its remaining life expectancy can be tracked. |
| Purged | All information about a cartridge can be removed from the system, returning the cartridge to “unknown” state. This is typically done only when a cartridge has permanently left the OpenVault system, as when a cartridge has reached the end of its life, or when it is removed from the system for transfer elsewhere. There is no “purged” state as such; this term simply provides a way of referring to cartridges for which there once was descriptive data, all of which has been removed. |
Cartridges are managed in OpenVault through an administrative interface (AAPI). A set of command line tools are included that format requests to the OpenVault server and display the results on a standard terminal window.
Cartridges must be physically placed into a library before they can be used. There are two ways to accomplish this. One is to simply open the door to a library and place cartridges with barcodes in slots in the library. When the door is closed, the library control program (LCP) will command a scan of the slots in the library and report the contents of the library to the OpenVault server. This probably results in the library being offline while the door is open.
A second method is to use the inject/eject slot of the library if it is so equipped. Such a library will remain operational while cartridges are being injected or ejected. Some libraries have an inject slot that is always open and ready to receive cartridges. For these libraries, one can simply insert a cartridge into the slot. The LCP will recognize the event and handle the cartridge appropriately.
Other libraries need to have their inject/eject slot opened under program control. In this case you may use the ov_inject command to instruct a library on how many cartridges to accept. A typical command would be:
ov_inject -l biglib -n 3 |
This tells OpenVault that you wish to insert three cartridges into the inject slot on a library named biglib.
Note that this feature has not been fully implemented for most libraries at the time of this writing. For now, the most reliable method of placing carts into a library is to take the library offline, open the door, and insert cartridges directly into storage slots.
It is often useful to see what a library believes to be contained within it. The ov_stat command performs this function (among others), displaying the contents of the slots in a library as shown in Example 3-1:
A typical ov_stat command would be:
ov_stat -L 9730 -s |
The -s option specifies that a slotmap should be displayed, and the -L9730 indicates that it should be for the library named 9730. It produces the following output:
# ov_stat -L 9730 -s Library Name Broken Disabled State LCP SoftState LCP HardState 9730 false false ready ready ready Library: '9730' Library Slot Name Slot Type Occupied PCL Cart ID 9730 slot 0 DLT false 9730 slot 1 DLT false 9730 slot 10 DLT true 000199 9730 slot 11 DLT true ABN695 9730 slot 12 DLT false 9730 slot 13 DLT true 000195 9730 slot 14 DLT false 9730 slot 15 DLT false 9730 slot 16 DLT true 000193 9730 slot 17 DLT false 9730 slot 18 DLT false 9730 slot 19 DLT false 9730 slot 2 DLT false 9730 slot 20 DLT false 9730 slot 21 DLT false 9730 slot 22 DLT true 000185 9730 slot 23 DLT false 9730 slot 24 DLT false 9730 slot 25 DLT false 9730 slot 26 DLT false 9730 slot 27 DLT false 9730 slot 3 DLT false 9730 slot 4 DLT false 9730 slot 5 DLT false 9730 slot 6 DLT false 9730 slot 7 DLT false 9730 slot 8 DLT true 000194 9730 slot 9 DLT true 000192 Library Bay Name Slot Type Total Slots Free Slots 9730 bay 1 DLT 7 0 |
This example shows a library with 7 slots occupied, with the PCL listed for the cartridge in each occupied slot. The PCL information is needed to enter the data that OpenVault needs to manage cartridges. Note that at this point, the LCP has information about the PCLs of cartridges in this library, but the OpenVault server has no other information about the cartridges. Thus these cartridges are still “unknown” to OpenVault.
The administrator (or an administrative application) must enter descriptive data about cartridges before they can be used. OpenVault provides two methods to enter that data:
The individual commands will be discussed first as they illustrate the types of data needed. The ov_import command combines several steps of the individual commands and is discussed in “Simplified Entry of Media Information”.
Cartridge data is entered with the ov_cart command. When outside of a library, a new cartridge (one with no data on it) could be entered as follows:
ov_cart -n -B ABN695 -T DLT7000 -g default |
This creates an entry in the OpenVault catalog for a cartridge with a PCL of ABN695. The cartridge is a DLT 7000 cartridge, which is indicated to OpenVault with the -T (cartridge type) option and type description string of DLT7000. There is a unique description string for each type of cartridge known to the OpenVault system. Other examples include 8mm-160m, 3590, and STKtimberline. These strings tell OpenVault what kind of drive this tape uses. The -g option is used to specify a cartridge group. Cartridge groups are used to control which cartridges can be allocated by an application. In this case, the cartridge is being assigned to the group default, which would normally be used for cartridges which can be allocated by any application.
The ov_cart command generates output as follows:
New cart created with cartridge ID = `wIS2MTXrMmQAAlYR' |
The cartridge ID is a unique string that identifies a cartridge, and is used to define other cartridge data. A PCL alone cannot be used as a unique identifier because a PCL might not be unique on an OpenVault system--two different types of cartridges could have the same PCL. OpenVault requires that on a given system a PCL must be unique for a single cartridge type (there cannot be two DLT7000 tapes with the same PCL).
If the cartridge was not a new cartridge but rather already belonged to an application and had data on it, one additional item of data would need to be entered. This would be the name of the application that owns the cartridge. For example, if the above cartridge were used by the xfsdump application, the command would be:
ov_cart -n -B ABN695 -T DLT7000 -g default -A xfsdump |
This ensures that no other application can allocate this cartridge and overwrite its data.
When a cartridge is created, OpenVault also creates additional descriptive data about the cartridge based on its knowledge of that cartridge type. This is primarily information about sides on the cartridge, including how many sides the cartridge has, the name of each side, and creation time. Cartridge type information can be seen by running the ov_carttype command with no arguments. For the DLT700, this information displays:
Type Name Media Type Media Length Slot Type Number Sides Side1Name Side2Name DLT7000 DLT Compact IV 100 DLT 1 SideA |
Most magnetic tapes have only one side. Optical and removable magnetic disk cartridges have two sides. At the time of this writing, OpenVault supports single sided media only.
Once data on a cartridge is entered into the system, you can display it with the ov_lscarts command as shown in Example 3-2:
Example 3-2. ov_lscarts Cartridge Data
The first entry provides summary information on cartridges, and the second shows the PCLs of all cartridges known to the system.
# ov_lscarts
num carts num allocd num free
15 7 8
# ov_lscarts '.*'
000185 000193 000197 ABN579 ABN695
000190 000194 000198 ABN580 ABN697
000192 000195 000199 ABN693 |
Without any arguments, ov_lscarts prints a summary of the number of cartridges in a system. This is because the number of cartridges in a system could be very large. If the default behavior was to show all cartridges, the screen could be completely filled with cartridge information. Thus ov_lscarts requires that a cartridge list be provided before it prints detailed information.
The argument `.*' in the second example is a regular expression that matches all cartridge names. This is the standard way of displaying all known cartridges.
You can obtain detailed information on cartridge(s) can be shown in Example 3-3:
Example 3-3. Detailed ov_lscarts Cartridge Data
# ov_lscarts -li ABN695 PCL cart type owner state cartID part volume ABN695 DLT7000 ok wIS2MTXrMmQAAlYR |
In this example, the -l option specifies a long listing, and the -i specifies that the CartridgeID be printed also.
 | Note: The example does not contain any partition or volume information, because it has not yet been entered. |
A partition is a defined area on the media where data can be written. For OpenVault to be able to use a cartridge, at least one partition must be defined on it. Magnetic tape cartridges usually have only one partition. Optical cartridges often have one partition per side. As SGI tape driver software typically does not support multiple partitions per cartridge, one partition is currently the limit for tapes on OpenVault.
Example 3-4 shows how you create a partition with the ov_part administrative command:
Example 3-4. ov_part Partitions Creation
# ov_part -n -C wIS2MTXrMmQAAlYR -s SideA -p "Part 1" -b DLT7000 New partition created: cartridge ID = 'wIS2MTXrMmQAAlYR', partition Name = 'Part 1' |
The -n option indicates that this is a new partition on the cartridge with the CartridgeID wIS2MTXrMmQAAlYR. Note that this is the same CartridgeID reported by ov_cart above when the cartridge data was entered for the cartridge with the PCL of ABN695. The -s option identifies the side of the cartridge on which to put the partition. Since there is only one side on a DLT7000 cartridge, there is no choice of side here--the side name of SideA from the cartridge type table (as shown by ov_carttype above) must be used.
Finally, a name must be provided for the partition. This follows the -p option and in this case is Part 1. Any name may be specified here.
The ov_part command reports whether the partition creation was successful. If it was not, an error message is displayed.
At present there is no easy way for users to display partition information on a cartridge. The information is not needed unless you need to create a volume on the partition. If you need to do this, be sure to remember the name of the partitions you create. By convention, the standard name for the first partition is Part 1 which must by typed in quotes on the command line. The quotes are needed so that the space between “Part” and “1” is not recognized as a delimiter between arguments on the command line.
At this point, the cartridge is fully defined and available. An application that requests a volume be allocated to it could get ownership of this cartridge. That is what we want to have happen for new cartridges that do not have data on them. However, if the cartridge already has data and we do not want it to be overwritten, we need to make sure that no application can allocate it.
The best time to do this is when the partition is created; otherwise, an application may be able to allocate the cartridge before you can type a new command to prevent it. Example 3-5 shows how you can set allocatable status on the ov_part command with the -a option when create the partition is created:
Example 3-5. Setting ov_part Allocatable Status
# ov_part -n -B wIS2MTXrMmQAAlYR -s SideA -p "Part 1" -b DLT7000 -a false |
This command is identical to the ov_part command in “Creating Partitions”, except for the addition of the -a option and its argument.
A better way to define cartridges with pre-existing data is to use the ov_import command, described in “Simplified Entry of Media Information”.
The above steps together fully define a cartridge--OpenVault now has cartridge, side, and partition information. All that is needed for an application to use the cartridge is for a volume to be created on it. Example 3-6 shows how you use the ov_vol administrative command to create a volume.
Example 3-6. ov_vol Volume Allocation
This ov_vol command creates a volume named VolOne that will belong to an application named ov_umsh on the cartridge previously defined:
# ov_vol -n -v VolOne -a ov_umsh -C wIS2MTXrMmQAAlYR -s SideA -p "Part 1" New volume created: volume name = 'VolOne', application name = 'ov_umsh' |
The -n option specified that this is a new volume, with the following argument containing the name for the volume of VolOne. The -a option specifies the owner application, in this case being ov_umsh. The following three option/argument pairs specify where the volume is to be created--on the cartridge with CartridgeID wIS2MTXrMmQAAlYR, on its side SideA and partition “Part 1”.
Applications may also create volumes by issuing an allocate request to OpenVault through the CAPI interface. OpenVault looks for an allocatable partition on a cartridge that is either not owned by any application or is owned by the requesting application. It then creates volume data for one such partition, marks the partition as not allocatable (because there is now a volume allocated on it), and sets the cartridge ownership to the requesting application. See the OpenVault Application Programmer's Guide for further details.
Information on volumes can be displayed with the ov_lsvols command shown in Example 3-7:
Example 3-7. ov_lsvols Volume Data
# ov_lsvols -l VolOne volume cartID owner partition VolOne wIS2MTXrMmQAAlYR ov_umsh Part 1 |
The -l option specifies that a long listing be printed.
This command works similarly to the ov_lscarts command; issuing the command with no arguments causes summary information on volumes to be displayed, and a listing of all volumes requires a `.*' regular expression. The -l option specifies that a long listing be printed.
When an application has no further use for a volume it may give that volume back to OpenVault for reuse. It does this by deallocating the volume, which deletes volume data. The application may do this through the CAPI interface with the deallocate command, or an administrator may perform the deallocation using the ov_vol command as follows:
ov_vol -D -v VolOne -a ov_umsh |
The -D option indicates that the volume should be deleted. The -a option indicates which application owns the volume that is to be deleted. The application name is needed because while volume names must be unique within one application, they do not have to be unique across all applications on an OpenVault system. Specifying the application name indicates which specific volume with the given name is to be deleted.
OpenVault retains a fair amount of information about a cartridge after a volume on it is deallocated. The owner information (that is, which application owned the cartridge while there was a volume allocated on it) remains, as does the side and partition information. This allows administrative operations to be performed on these cartridges. A typical operation might be to erase the tape before it is released for use by other applications or users in order to protect sensitive data. Such operations are optional (and beyond the scope of this document); there is no requirement that they be performed. After such steps are performed, the volume can be recycled, that is made available for allocation again.
The simplest method of recycling allows the owner of the cartridge to allocate another volume on it. To do this, you must tell OpenVault that this operation is allowable. This is done with the ov_part command as follows:
ov_part -C wIS2MTXrMmQAAlYR -s SideA -p "Part 1" -a true |
The CartridgeID identifies the cartridge on which the partition resides. The -s and -p options indicate the side and partition name, as when the partition was created. The -a option allows setting of the allocatable status. Setting it to true allows the partition to be allocated, that is it allows a volume to be created on that partition.
Again, since the application that previously had a volume on the partition still owns the cartridge, only that application can allocate a new volume on that cartridge. Freeing up the cartridge so that any application can use it requires use of the ov_recycle command.
The ov_recycle command looks for cartridges that do not have any volumes on them and which are not available for allocation. The search can be restricted to cartridges belonging to a particular application, or to one or a list of cartridges. A typical ov_recycle command looks like this:
ov_recycle -r -A ov_umsh |
The -A option indicates that all cartridges belonging to application ov_umsh that can be recycled should be recycled. Any such cartridges would have their owner information deleted, and their partitions would become allocatable again. This operation returns the cartridges to the defined and allocatable states described above, just as for a new cartridge with defined cartridge and partition information.
A large amount of data can be entered at once, and data is shared between steps of the definition process so that the administrator does not have to read and re-enter intermediate results.
There is a simpler and faster method to define cartridge, partition, and volume data than the procedure using ov_cart, ov_part, and ov_vol that is described in “Creating Cartridge Data”, through “Allocating Volumes”. The ov_import command may be used to perform these operations simultaneously. Data is shared between steps of the definition process so that the administrator does not have to read and re-enter intermediate results.
The ov_import command accepts a series of command line options that specify a cartridge group name and partition bit format. Then it reads lines from standard input (that is, from the keyboard, pipe, or input file) containing all the information needed to create complete cartridge and volume definitions. The format of the input lines is:
PCL CARTRIDGETYPE [VOLUMENAME APPNAME] |
The volume name and application name are optional, but if used, both must be used together and in order.
In Example 3-8, four cartridges are created with the ov_import command:
Example 3-8. ov_import Cartridge Creation
# ov_import -g default -b DLT7000 test001 DLT7000 test002 DLT7000 test003 DLT7000 vol1 ov_umsh test004 DLT7000 vol2 ov_umsh <EOF> |
This ov_import command creates the cartridge data, a side and a partition on each cartridge with default names, and sets ownership and allocates a volume for the lines where volume name and owner were specified.
Example 3-9 shows the results with the ov_lscarts command:
Example 3-9. ov_lscarts Volume Listing
# ov_lscarts -lig 'test.*' PCL cart type owner group state cartID part volume test001 DLT7000 default ok wIS2MTXt0jIABa6O Part 1 test002 DLT7000 default ok wIS2MTXt0jcACesb Part 1 test003 DLT7000 ov_umsh default ok wIS2MTXt0koADWwM Part 1 vol1 test004 DLT7000 ov_umsh default ok wIS2MTXt0lEAC3I8 Part 1 vol2 |
This output shows that four cartridges now exist with “test” as the prefix of their PCL, that they all are DLT7000 cartridges, and that two of them have volumes and are owned by the application ov_umsh.
The ov_import command is most useful in defining cartridge information for a large number of cartridges at one time, such as when initially configuring an OpenVault system, or when adding a large number of cartridges to a library. In such cases, the ov_stat command can be used to get a list of PCLs of unknown cartridges in a library, and that list can then be edited into input for an ov_import command. This method minimizes the chances for human error in mistyping PCLs when creating cartridges, or entering incorrect CartridgeID strings for ov_part and ov_vol commands after a cartridge is created with ov_cart.
Administrators commonly remove cartridges for one of several reasons. These include disposal of cartridges after they have reached the end of their useful lives, moving cartridges to another library, or sending them to another site. As for the case of inserting cartridges in libraries, they can be removed from a library in two ways:
First, you can simply open the door of a library and remove cartridges. When you close the door, the LCP scans the library and reports changes to the OpenVault server.
The second method is to use the ov_eject command to tell the library which cartridges to move to the library's output port. A cartridge can be ejected by its PCL, CartridgeID, or position in a library, as follows:
ov_eject -B PCL ov_eject -C wIS2MTXrMmQAAlYR ov_eject -l 9730 -b `bay 1' -s `slot 11'
If a cartridge is unknown to OpenVault (that is, present in a library but OpenVault has no data on it), then it must be specified either by PCL or by library slot position. If the PCL is missing or unreadable, then only the library slot form can be used.
When a cartridge has been removed from an OpenVault system and is never expected to return (such as in the case of a cartridge that has reached the end of its useful life), there may be no further need to retain data about that cartridge. The data can be deleted from the OpenVault system with the ov_purge command. This command deletes all cartridge, side, and partition information about a cartridge as shown in Example 3-10:
Example 3-10. ov_purge Cartridge Data
A cartridge cannot be purged if there are allocated volumes on it. This is a safety precaution to ensure that data on cartridges that are still in use are not lost. The ov_purge command also asks for confirmation before it attempts to delete data as an additional check to help prevent inadvertent loss of data.
# ov_purge -C wIS2MTXrMmQAAlYR Are you sure you want to purge all information for cartridge with cartridge ID = wIS2MTXrMmQAAlYR (Y/N)? y Deleted partition Part 1 Deleted cartridge wIS2MTXrMmQAAlYR |
After this command is executed, no data remains in the OpenVault system about the cartridge, which returns to “unknown” state. If the cartridge is at the end of its useful life, the administrator should remove the cartridge from the library and destroy it, thus completing the life cycle for this cartridge.