NSRJB(8)
NAME
nsrjb − NetWorker jukebox-control command
SYNOPSIS
nsrjb
[ −C ] [ −j name ] [ −v ] [ −f media device ] [ −S slots ] [ volume name ]
nsrjb
−L [ −j name ] [ −gnqvRY ] [ −b pool ] [ −f media device ] [ −e expire ] [ −c capacity ] [ −o mode ] [ −S slots ] [ volume name ]
nsrjb
−l [ −j name ] [ −nvqrMR ] [ −f media device ] { −S slot | volume name }
nsrjb
−u [ −j name ] [ −qvM ] [ −f media device ] [ −S slot ] [ volume name ]
nsrjb
−I [ −j name ] [ −Ev ] [ −f media device ] [ −S slots ]
nsrjb
−p [ −j name ] [ −v ] [ −f media device ] [ −S slot ]
nsrjb
−o mode [ −j name ] [ −Y ] { −S slots | volume name }
nsrjb
−H [ −j name ] [ −E ] [ −v ]
nsrjb
−h [ −j name ] [ −v ]
nsrjb
−V [ −j name ] [ −v ]
DESCRIPTION
The nsrjb command manages jukeboxes for NetWorker servers. The nsrjb command, rather than nsrmm(8), should be used to label, load, and unload the volumes contained within a jukebox. Typically, nsrjb is invoked via the NetWorker notification system and is rarely used directly. Only one nsrjb command can be accessing the jukeboxes at a time. They are synchronized using a file lock on the file ’/nsr/tmp/.nsrjb.’.
A volume is a physical piece of media, for example, a tape cartridge or optical disk. A jukebox is a machine containing volumes, a mechanism to manipulate the volumes, and devices to access the volumes. Each volume in a jukebox and each jukebox has a name recognized by NetWorker. A volume name is specified when the volume is first labeled by NetWorker. It may be changed when a volume is relabeled. The volume should have an external label displaying its volume name for future reference. NetWorker refers to volumes by their volume names. For example, when requesting a mount of a volume, NetWorker asks for it by volume name.
When a NetWorker server needs a volume for backup or recovery and an appropriate volume is not already mounted, NetWorker generates an event. These events can be used to invoke the nsrjb command (see nsr_notification(5), nwadmin(8) and nsrwatch(8)). If a jukebox has a volume stored in it which satisfies the media request, nsrjb will load the media into an idle device.
Before using nsrjb, the jukebox and its device resources must be added to the NetWorker configuration. To add the jukebox and its device resources to the NetWorker configuration, use either the nwadmin or nsradmin commands to create the device resources and then use jb_config to create the jukebox resource. The jukebox resource is described in nsr_jukebox(5). It is important to note that the ’available slots’ attribute does not limit what slots the user running nsrjb can operate on. The only limitation enforced against the user is the physical range of slots which exists in the jukebox. The ’available slots’ attribute specifies the slots containing volumes available to automatically satisfy NetWorker requests for writable volumes. When automatically selecting a writable volume, nsrjb will only consider volumes from the list of available slots.
nsrjb attempts to determine what jukebox to use based on the options -j, -f, or a volume name. If one or more of these options do not uniquely identify a jukebox and one must be selected, nsrjb will prompt the user to choose a jukebox to operate on. Alternatively, one can set the environment variable NSR_JUKEBOX to the name of the jukebox to be used by default.
OPTIONS
−b pool
Specifies the media pool to which the volume should belong. The pool may be any pool currently registered with nsrd. The possible values can be viewed by selecting the Pools menu item from the Media menu of nwadmin(8). The pool name is referenced by nsrd when determining what save sets can reside on the volume. If this option is omitted, the volume is automatically assigned to the Default pool. Specifying a pool name and no volume name causes nsrjb to use the next volume name associated with the specified pool’s label template resource. (See nsr_label(5).)
−c Override the volume’s default capacity (see nsrmm(8)).
−C Display the current volumes in the jukebox and the jukebox’s associated devices. This is the default option. A list of slot numbers, volume names, media pools, optional bar code information, and volume modes is produced. If the jukebox attribute ‘bar code reader’ is enabled and there are bar code labels on the media volumes, then the bar code label will be included in the list. If ‘bar code reader’ is set and the volume does not have a bar code label, a ‘−’ will be printed indicating that there is not a bar code label on the media. The -C option does not cause an actual jukebox inventory to be done. That is, nsrjb only tells you what it thinks is currently contained within the jukebox. Volumes may be succeeded by one of the following flags: an (R), indicating the volume is read-only; or an (A), indicating it is an archive volume. If combined with the −v option, the filled capacity of the volumes will also be displayed. Volumes that are not contained in the NetWorker media database are marked with an asterisk, ‘∗’. The mode column contains additional information about the mode of the volume listed. The mode field can have one of three values: manually recyclable, indicating that the volume will not be automatically recycled/relabeled; recyclable, indicating that the volume is eligible for automatic recycling; or, the mode field can be blank, indicating that neither of the other two states applies. After the slot map is printed, a line about each device is displayed. For each enabled device, the following information is provided: the drive name, the device pathname, the slot number and name of the currently loaded volume, and an indication if NetWorker has the volume mounted. If the device is disabled, only the drive name and pathname are displayed along with the word disabled.
−e Override the default expiration date (see nsrmm(8)).
−E Initialize element status. This option can be used in conjunction with the −I or −H options. Some jukeboxes have the ability to keep track of whether or not there is media in a component in the jukebox. This feature is known as an "element status" capability (known to exist on the EXB-120, EXB-60, HP optical, and Lago Datawheel jukeboxes). When swapping media into the jukebox where no media has previously been loaded, it may be necessary to re-inventory (−I) the jukebox with the −E option so the jukebox re-initializes its element status.
−f media device
Specify a media device (not the jukebox control port). The argument given should be the pathname of the media device as it has been configured in the jukebox resource. When more than one media device has been configured for a jukebox, nsrjb will select the first available media device by default. The default device may be overridden by using the −f option.
−g Do not generate the next unused name for the label template at the end of the labeling operation.
−h History. A list of the past 100 messages is displayed.
−H Reset the jukebox hardware and the NetWorker database representing the jukebox to a consistent state. The jukebox will be told to clear the transport and unmount and unload volumes from the drives to slots. An actual inventory is not done; see the −I option. If the jukebox believes the inventory is out-of-date, an appropriate message is printed.
−I Inventory the jukebox. The volumes in the specified slots are loaded into a device and their labels are read. This option may be used to ensure that the mapping between slot number and volume name is correct. This option may take a long time to complete. For jukeboxes which have the element status capability(e.g. EXB-120, EXB-60, or HP optical), the −E option can be used in conjunction with the −I option to reinitialize the jukebox’s notion of what is stored inside the jukebox. This option will increase the time it takes to inventory the jukebox as the hardware must check every component, including all slots and drives, for the presence of media. This option should only have to be used when the operator manually swaps media in or out of the jukebox. If the jukebox has a bar code label reader and the jukebox resource attribute ‘bar code reader’ is set, a slot’s volume name will be derived from the media bar code label. If the bar code label is not unique or does not exist in the NetWorker media database, the volume name will be read from the media. Successful use of a jukebox’s bar code reader can decrease the amount of time it takes to do an inventory operation. If a bar code label on the media has changed, then the NetWorker media database will be updated with the new bar code label.
−j name
Specify a particular jukebox to use. The given name is the one assigned by the user when the jukebox resource is created. This option overrides the NSR_JUKEBOX environmental variable.
−l Load and mount a volume. A specific volume or slot must by specified. The −f option may be used to specify a media device.
−L Label the volumes in the specified slots. Names for volumes are generated by referencing the label template resource for the given pool. When no slots are specified, the range of slots is determined by the resource describing the jukebox. When more than one volume is being labeled and a starting volume name is specified, the volume name must match the template of the given pool. If just one volume is being labeled, only the normal NetWorker volume name restrictions apply. Labeling a complete jukebox may take a long time. If the jukebox has a bar code label reader and the jukebox resource attributes ‘bar code reader’ and ‘match bar code labels’ are set, then the volume label will be derived from the bar code label on the media, and the media bar code label will be stored in the NetWorker media database. If the jukebox resource attribute ‘match bar code labels’ is not set, then the volume label will be derived from the label template, although the media bar code label will still be stored in the NetWorker media database so that it can be used during inventory operations.
−M Send messages to the NetWorker daemon reporting progress and errors. This is used by nsrd(8) when mounting and unmounting volumes on behalf of nsrmmd(8) requests, and is not normally needed for manual requests.
−n When specified with the −l option, load, but don’t mount, the volume. NetWorker will not be notified that this volume has been loaded. This allows nsrjb to control a jukebox containing non-NetWorker volumes.
−o mode
Set the mode of a volume or range of slots. The mode may be one of [not]recyclable, [not]readonly, [not]full or [not]manual. The [not]manual modes are the only valid modes when used with −l. If the −Y option is not given, the user will be prompted to confirm the operation for each volume. See nsrim(8) for a discussion of the per-volume flags.
−p Verify and print a volume’s label. A slot and/or device may be specified (see nsrmm(8)).
−q Run in quiet mode. Turns off all of the messages normally produced when labeling, loading, or unloading volumes. May only be used with −L, −l, and −u.
−R Recycle the volume(s) (see nsrmm(8)).
−r Load the volume read-only. May only be used with −l. See nsrmm(8).
−S Slots. Specify a slot or range of slots to operate on. The −l and −u options will only accept one slot, while the other options will accept a range of slots. Ranges are specified as low-high. Both low and high must be integers; low must be less than or equal to high. Both numbers are checked for validity against the resource describing the jukebox. Only one slot range is allowed to be specified at a time.
−u Unload a volume. A device, slot, or volume may be specified.
−v Verbose. (See other arguments for specific details.)
−V Display vendor-specific status information. When combined with the −v option, the configuration of the jukebox will be displayed.
−Y Disables confirmation prompting. Rather than prompting for confirmation, a yes answer is assumed. Prompts are normally generated when a volume is being relabeled before its expiration date or when a volume is still registered in the NetWorker media database.
EXAMPLES
Labeling volumes:
To label all of the volumes in a jukebox, use the −L option.
nsrjb −L
You may want to specify a particular pool using the −b option.
nsrjb −L −bOffsite
Labeling the volumes in slots 5 through 19:
To label the volumes in slots 5 through 19, invoke:
nsrjb −L −S 5−19
Labeling a volume with a non-standard name:
To label the volume in slot 20 with a name that does not match the label template associated with a pool, specify the name along with the −L option.
nsrjb −L −S 20 mars.special
When more than one volume is to be labeled, the name must match the label template associated with the pool. This ensures that nsrjb can generate the subsequent names.
Labeling volumes with a standard name:
To label the volumes in slots 21 through 28, starting with a different name than referenced by the label template associated with the pool resource, specify the first name along with the −L option. In order for nsrjb to generate the additional names, the specified name must match the layout of the label template.
nsrjb −L −bOffsite −S 21−28 Offsite.501
After labeling the volume in slot 21 with ‘Offsite.501’ nsrjb will use the label template to generate names for the volumes in slots 22 (‘Offsite.502’) through 28 (‘Offsite.508’). If the next volume name in the sequence for a label template is already used, the name is skipped.
Loading a volume:
To load volumes, use the −l option.
nsrjb −l
nsrjb will select volumes to load and devices to load them into. nsrjb will continue loading volumes until all of the devices are loaded.
Loading specific volumes:
To load a volume named mars.001, specify the volume name along with the −l option.
nsrjb −l mars.001
To load the volume in slot 5, use the −S option.
nsrjb −l −S 5
To load the selected volume into device /dev/nrst1 also include the −f option.
nsrjb −l −f /dev/nrst1 mars.0005
Unloading a volume:
Like loading, one may unload a particular volume, slot, or device. To unload volume mars.0028, run:
nsrjb −u mars.0028
To unload the volume in slot 28, use the −S option.
nsrjb −u −S 28
To unload the volume in device /dev/nrst3, use the −f option.
nsrjb −u −f /dev/nrst3
Displaying the jukebox’s current volumes:
To display a list of slots and volumes, and which volumes are loaded in a jukebox’s devices, run:
nsrjb −C
The −C is the default option and is used when no other options are selected. A range of slots may also be specified. For example, running
nsrjb −S 10−23
will display the volumes in slots 10 through 23.
Inventorying the volumes:
To reconcile the actual volumes and nsrjb’s list of volumes, use the −I option. Each volume may (depending on bar code settings and other factors) be loaded into a device and examined for a NetWorker label. nsrjb’s internal list is then updated with the new information. After the volumes have all been examined, the new list is compared to the NetWorker media database, and a message listing any volumes located in the jukebox but not in the database is produced. To inventory the volumes in slots 17 through 43, run
nsrjb −I −S 17−43
Like labeling, taking an inventory involves considerable time.
Using the NetWorker notification system:
When NetWorker needs a volume a ‘media event’ is generated. To have nsrjb automatically respond to these events, the NetWorker notification system is used. This notification resource is automatically generated for you.
FILES
/nsr/mm/mmvolume
The NetWorker media database.
/nsr/res/nsrjb.res
The jukebox resource descriptors.
/nsr/tmp/.nsrjb.jukebox
The file used to synchronize nsrjb commands for the jukebox.
SEE ALSO
jbexercise(8), mminfo(8), nwadmin(8), nsr(8), nsrd(8), nsr_layout(5), nsr_device(5), nsr_jukebox(5), nsr_notification(5), nsradmin(8), nsrim(8), nsrmm(8), nsrmmd(8), nsrwatch(8)
DIAGNOSTICS
Some errors have been classified and can be identified by the last three digits of the error number returned by the nsrjb command. Non-classified errors are listed first.
must be run by root
A normal (non-super) user tried to invoke this command.
No drives are available for use (busy, secure, or disabled).
This message is logged when the jukebox is trying to acquire a drive to satisfy a backup or recover media request. If the drives are not actively saving or recovering, then the device is secured or disabled. Devices are secured in the pool resources. Devices are enabled or disabled in the device resources.
All drives are busy or disabled.
If the drives are not actively saving or recovering, then the device is disabled. Devices are enabled or disabled in the devices window.
/dev/nrst2: verifying label, error opening: waiting to become ready
Some tape drives take some time to position to the beginning of the tape. While this is occurring, the device cannot be accessed. After the tape has wound to the correct position it becomes available for use and nsrjb continues on. If the device does not have a tape loaded, an I/O error message similar to the following will appear: read open error, I/O error (5).
All volume names for ‘xyz’ are in use
All the volume names for the given template have been used. The operator should change the template to accommodate more volume names.
No volumes found in the media database...continuing.
The media database is empty. The user will typically see this message when the module has been newly installed or all volumes have been deleted.
Another nsrjb is already running, please wait...
Another nsrjb command is accessing a jukebox. The current command will keep attempting to access the device periodically. Once it has acquired the jukebox device, it will display the message ’Continuing.’.
slot ‘xyz’ doesn’t have a bar code label
This means that an inventory operation was attempted with the jukebox resource attribute ‘match bar code labels’ enabled and the media did not have a label on it. Either disable the attribute with nsradmin or nwadmin, or place a bar code label on the media.
slot ‘xyz’ has a duplicate bar code label ‘xyz‘
This means that two or more media volumes have the same bar code label attached. Either disable the attribute with nsradmin or nwadmin, or place a unique bar code label on the media volume.
(001) Unknown jukebox model
The model for this jukebox is not known to the NetWorker jukebox module.
(006) Unknown control port
There is no control port listed for this jukebox.
(007) Invalid range
The given range could not be parsed by nsrjb.
(010) Source component empty
The jukebox attempted to move media between components in the jukebox, e.g. from a slot to a drive, but found nothing in the source component.
(011) Destination component full
The jukebox attempted to move media between components in the jukebox, e.g. from a slot to a drive, but found something already in the destination component.
(012) All slots full
The jukebox attempted to unload a drive as part of a reset (−H) operation. It found all slots to contain media. The operator should empty one of the slots or remove the media located in the drive from the jukebox.
(013) Slot xxx is empty.
This error may be seen during a label operation. The labeling process stops as soon as an empty slot is encountered. If attempting to label a range of slots on jukeboxes with the ability to sense whether or not slots are loaded, the error message is as follows:
Slot xxx is empty, attempted to label the slot range xxx-yyy. Specify a slot range which is full of volumes. No volumes were labeled.
(016) Slot empty
The source slot did not have a volume in it.
(017) Unsupported operation
This jukebox does not have the functionality to support the requested operation.
(025) Vendor error occurred
Normally in this case you will not see the message ’Vendor error occurred’. Instead, you will see an error string retrieved directly from the jukebox or device driver. The operator should consult the hardware/driver manual to determine the cause of the error.
(027) All drives full/busy
All drives are loaded and/or busy at the moment. The operator should free up one of the drives by unloading the device. If all drives are currently in use, the operator will have to wait for a drive to become idle.
(029) Unable to retrieve any volume information from the media database
This message indicates that nsrjb could not access any volumes in the media database.
(036) All of the devices are in use by nsrmmd
The jukebox could not acquire a drive to use for a save or recover.
(038) All drives must be unloaded before jukebox resource can be deleted
The user cannot delete a jukebox resource if any volumes are loaded in the media drives. Unload all media drives before attempting to delete the jukebox resource. If it does not appear that any of the devices are loaded, issue the nsrjb command with the −H option.
(039) This command only valid with a single slot specified
Only a single slot is allowed to be specified. The operator cannot specify a range of slots, e.g. -S 4-6, to operate on.
(040) The drive is loaded with a volume from a different slot
The user specified both a volume and the −f option, but the drive already has a volume loaded from a different slot.
(041) The drive is empty
The drive has no volume loaded to operate on.
(042) Will not over-write volume without confirmation
NetWorker does not allow a user to over-write a volume with a valid NetWorker label without confirmation.
(043) The volume name does not match what has been inventoried. Please re-inventory the volume.
The jukebox encountered a volume with a different label than what was expected. The operator should re-inventory the jukebox.
(044) The volume from that slot is loaded in another drive
The user specified both the −f and −s options, but the volume from the given slot is loaded in another drive.
(045) The volume does not exist in the jukebox
The named volume is not loaded in the jukebox.
(047) The alternate side of the media is busy
The other side of the optical media is in use. The side we are trying to access is unavailable until the alternate side is idle.
(048) Too many devices
The user tried to add too many devices during the creation of the jukebox.
(049) Unlabeled volume, loaded but not mounted
The user tried to load a volume but no label was found on the media.
(050) Drive door closed
The user was trying to perform an unload operation. When the jukebox went to move the media from the drive to a slot, the transport found the media drive door closed.
(051) Unable to select a suitable volume in response to media request
The jukebox module could not find any volumes in the devices to respond to a media request.
(054) The drive is busy. Please try again later.
The media device an operation was attempted on was assigned a save or recover session. The user should try the operation again later when the media drive is free.
(055) No element status capability for this jukebox. -E ignored.
The jukebox does not have the element status capability, so the -E option is ignored.
(056) The drive is disabled. Enable the drive or choose another.
The media drive specified is disabled. If this media device is the only one in the jukebox, then it must be enabled for nsrjb to use it. If there are other media devices enabled, the user can try selecting one of them.
(057) The media pool is not allowed on this device.
The media drive specified is not allowed to mount volumes from the media pool specified. Either change the media pool configuration to allow mounts of the pool on this device, or try using another device.
(058) All the media drives are disabled.
All the media drives are disabled. Enable one or more devices or select another jukebox or media device outside the currently selected jukebox.
(059) The media pool is not allowed on any of the drives.
None of the media drives in this jukebox are allowed to mount volumes from the media pool specified. Either change the media pool configuration to allow mounts of the pool on these devices, or try using another jukebox device or media device outside the currently selected jukebox.
(060) All drives are busy, disabled, or do not allow media from this pool.
See error descriptions (027), (058), and (059). There is some combination of these three errors preventing the operation from occurring.
(062) Can only reset jukebox when all drives are idle.
When attempting to unload a media device, the device was found to be busy. Wait for the device to become idle and reattempt the reset operation.
NetWorker 4.1.2 — Last change: May 1995