Chapter 3. Cartridge Life Cycle
Prev |  | Next

## Chapter 3. Cartridge Life Cycle

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

## Cartridge States

Figure 3-1, illustrates the life cycle of a cartridge:

Figure 3-1. Cartridge Life Cycle (Simplified)

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.

## Managing Cartridges

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.

### Physical Entry into a Library

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.

A second method is to use the inject/eject slot of the library if it is so equipped. 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.

### Examining the Contents of a Library

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:

Example 3-1. Library Contents

A typical `ov_stat` command would be:

    ov_stat -L 9730 -s

The `-s` option specifies that a slotmap should be displayed, and the `-L` `9730` 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.

### Creating Cartridge Data

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:

- Individual commands to enter facts about the cartridge, partitions, and volumes on the cartridge (using `ov_cart`, `ov_part`, and `ov_vol`)

- `ov_import`, a tool that enters several of these facts at once

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 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 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.

### Displaying Cartridge Data

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.

### Creating Partitions

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 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.

### Controlling Allocation Status

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 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”.

### Allocating Volumes

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 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.

### Displaying Volume Data

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.

### Deallocating Volumes

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 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.

### Recycling Cartridges

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 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 -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.

### Simplified Entry of Media 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`.

### Removing Cartridges from Libraries

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 ABN695
      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.

### Purging Cartridge Data

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.

Prev | Table of Contents | Next
Chapter 2. Installing OpenVault |  | Chapter 4. Administering OpenVault