NSRJB(8) Legato NetWorker 4.1.1 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 mecha
nism 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
Licensed material--property of copyright holder(s) 1
NSRJB(8) Legato NetWorker 4.1.1 NSRJB(8)
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 nwad
min 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 run
ning 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 refer
enced by nsrd when determining what save sets can reside on
the volume. If this option is omitted, the volume is automat
ically 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 cur
rently 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
Licensed material--property of copyright holder(s) 2
NSRJB(8) Legato NetWorker 4.1.1 NSRJB(8)
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, indicat
ing 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 indica
tion 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 con
junction 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 "ele
ment status" capability (known to exist on the EXB-120,
EXB-60, HP optical, and Lago Datawheel jukeboxes). When swap
ping 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 repre
senting 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
Licensed material--property of copyright holder(s) 3
NSRJB(8) Legato NetWorker 4.1.1 NSRJB(8)
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 capa
bility(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 juke
box 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 vol
ume 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 juke
box 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 inven
tory operations.
-M Send messages to the NetWorker daemon reporting progress and
errors. This is used by nsrd(8) when mounting and unmounting
Licensed material--property of copyright holder(s) 4
NSRJB(8) Legato NetWorker 4.1.1 NSRJB(8)
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 contain
ing 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 expira
tion date or when a volume is still registered in the Net
Worker media database.
EXAMPLES
Labeling volumes:
To label all of the volumes in a jukebox, use the -L option.
nsrjb -L
Licensed material--property of copyright holder(s) 5
NSRJB(8) Legato NetWorker 4.1.1 NSRJB(8)
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 associ
ated 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/rmt/1 also
include the -f option.
nsrjb -l -f /dev/rmt/1 mars.0005
Licensed material--property of copyright holder(s) 6
NSRJB(8) Legato NetWorker 4.1.1 NSRJB(8)
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/rmt/3, use the -f option.
nsrjb -u -f /dev/rmt/3
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 exam
ined 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 Net
Worker 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.
Licensed material--property of copyright holder(s) 7
NSRJB(8) Legato NetWorker 4.1.1 NSRJB(8)
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/rmt/2: 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 simi
lar 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 vol
umes 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 periodi
cally. Once it has acquired the jukebox device, it will dis
play 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
Licensed material--property of copyright holder(s) 8
NSRJB(8) Legato NetWorker 4.1.1 NSRJB(8)
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 nsrad
min 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 juke
box 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.
Licensed material--property of copyright holder(s) 9
NSRJB(8) Legato NetWorker 4.1.1 NSRJB(8)
(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 deter
mine 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 juke
box.
(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.
Licensed material--property of copyright holder(s) 10
NSRJB(8) Legato NetWorker 4.1.1 NSRJB(8)
(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 con
figuration 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 cur
rently 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
Licensed material--property of copyright holder(s) 11
NSRJB(8) Legato NetWorker 4.1.1 NSRJB(8)
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.
Licensed material--property of copyright holder(s) 12