nsrjb(8)
nsrjb(8)
NAME
nsrjb - NetWorker jukebox control command
SYNOPSIS
nsrjb [ -C ] [ -j name ] [ -s server ] [ -v ] [ -f device ] [ -S slots
| -T Tags | volume names ]
nsrjb -L [ -j name ] [ -s server ] [ -gimnqvG ] [ -Y | -N ] [ -B ]
[ -b pool ] [ -f device | -J hostname ] [ -e forever ] [ -c
capacity ] [ -o mode ] [ -S slots | -T tags ] [ volume names ]
nsrjb -L [ -j name ] [ -s server ] [ -gimnqvG ] [ -Y | -N ] -R [ -b
pool ] [ -f device | -J hostname ] [ -e forever ] [ -c capacity ]
[ -o mode ] [ -S slots | -T Tags | volume names ]
nsrjb -l [ -j name ] [ -s server ] [ -nvqrG ] [ -R [ -b pool ] ] [ -f
device | -J hostname ] [ -S slot | -T tags | volume names ]
nsrjb -u [ -j name ] [ -s server ] [ -qv ] [ -f device ] [ -S slot | -T
tags | volume names ]
nsrjb -I [ -j name ] [ -s server ] [ -Evpq ] [ -I | -f device ] [ -S
slots | -T tags | volume_names ]
nsrjb -p [ -j name ] [ -s server ] [ -vq ] [ -f device ] [ -S slot | -T
tag | volume name ]
nsrjb -o mode [ -j name ] [ -s server ] [ -Y ] [ -S slots | -T tags |
volume names ]
nsrjb -H [ -j name ] [ -s server ] [ -EHvp ]
nsrjb -h [ -j name ] [ -s server ] [ -v ]
nsrjb -U uses [ -j name ] [ -s server ] [ -S slots | -T tags ]
nsrjb -V [ -j name ] [ -s server ]
nsrjb -d [ -j name ] [ -s server ] [ -v ] [ -N ] [ -Y ] [ -P ports ] [
-S slots ] [ -T tags ] [ volume names ]
nsrjb -w [ -j name ] [ -s server ] [ -v ] [ -N ] [ -Y ] [ -P ports ] [
-S slots | -T tags | volume names ]
nsrjb -a [ -j name ] [ -s server ] [ -vd ] [ -T tags | [ -T tags ]
volume names ]
nsrjb -x [ -j name ] [ -s server ] [ -vwX ] [ -T tags | -S slots ]
nsrjb -F [ -j name ] [ -s server ] [ -v ] -f device
DESCRIPTION
The nsrjb program manages resources in two broad classes of jukeboxes,
remotely managed jukeboxes and locally managed jukeboxes. Remotely
managed jukeboxes are controlled through an external agent. nsrjb com-
municates with this agent to gain access to jukebox resources. The
agent allows multiple applications, including multiple NetWorker
servers, to share resources in the jukebox. Examples of agents are
SmartMedia and StorageTek's ACSLS . nsrjb communicates directly with
a locally managed jukebox, there is no intervening agent. Resources in
a locally managed jukebox can be used by only one NetWorker server.
For a locally managed jukebox, the jukebox resource is used to track
the state of the entire jukebox. The resource records the number of
drives and slots in the jukebox. It is also used to track whether
devices are loaded, whether there is media residing the slots, and the
name of any volume on the media, as well as other information. See
nsr_jukebox(5).
The jukebox resource for a remotely managed jukebox does not reflect
the current state of the entire jukebox, only NetWorker's view. Media
must be allocated, before NetWorker may use media in a remotely managed
jukebox the media. For more details, see the description of the -a
option. The number of slots in a remote jukebox resource increases as
media is allocated for NetWorker's use and decreases as media is deal-
located after NetWorker has no further use for the media. The order in
which media is listed in the jukebox resource does not necessarily
reflect physical location within the jukebox. The number of drives in
a remote jukebox is an upper bound on the number of volumes in the
jukebox that NetWorker may access simultaneously.
The nsrjb command is used to manage all jukeboxes for a NetWorker
server. Use this command, rather than nsrmm(8), to label, load, and
unload the volumes contained within a jukebox. Multiple nsrjb commands
may access a jukebox at any given time.
A nsrjb command which requires use of jukebox resources does not
directly perform the requested operation. Instead the command makes a
request of the NetWorker server process, nsrd, which forwards the
request to nsrmmgd for processing.
Since nsrjb does not perform the operation directly, killing nsrjb will
not cause the operation to be aborted. Provision for operation cancel-
lation is built into nsrjb via an interrupt handler that is tied to
SIGINT. This means that if you have a nsrjb command running, and you
want the operation to be cancelled, then you may do it either by means
of Control-C against the nsrjb process, or using the UNIX 'kill' com-
mand to send a SIGINT signal.
A single Control-C or SIGINT will cause the operation to be cancelled,
with nsrjb still monitoring the status of the appropriate NSR jukebox
operation status resource until it is clear that the operation has in
fact terminated. A second Control-C or SIGINT will tell nsrjb to exit
without waiting for confirmation of the operation's termination.
A NSR jukebox operation status resource will be automatically generated
and managed by nsrd for each jukebox operation that is created, regard-
less of whether that operation was initiated automatically by nsrd or
is created explicitly by invoking nsrjb
This NSR jukebox operation status resource tracks the current state of
the operation, holds all messages (error, informational, or verbose)
related to the operation, and generally acts as a communication path
between the nsrjb process that invoked the operation, and the various
Networker programs that carry the operation out. See the nsr_op man
page for more details on this resource.
A volume resides on a side of a physical piece of media. Examples of
piece of media are tape cartridges or optical disks. Tape cartridges
have one side and therefore have one volume residing on each cartridge.
Optical media may have two sides with a volume residing on each side of
the media. Each volume within a jukebox and each jukebox has a name
recognized by NetWorker. A volume name is specified when the volume is
first labeled by NetWorker. You can change the volume name when a vol-
ume is relabeled. NetWorker refers to volumes by their volume names.
For example, when requesting the mount of a volume, NetWorker asks for
it by volume name.
Before using nsrjb, the jukebox and its device resources must be added
to the NetWorker server. Use jbconfig to add the jukebox resource and
its device resources to the NetWorker server. The jukebox resource is
described in nsr_jukebox(5).
When a NetWorker server requires a volume for backup or recovery and an
appropriate volume is not already mounted, the server checks the media
database to verify whether a jukebox contains a volume that satisfies
the media request. If so, nsrd sends a request to nsrmmgd to load the
media into an idle device. The Available Slots attribute specifies the
slots containing volumes available to automatically satisfy NetWorker
requests for writable volumes. When automatically selecting a writable
volume for backup, NetWorker only considers volumes from the list of
available slots. It is important to note that the Available Slots
attribute does not limit what slots the user running nsrjb can operate
on.
nsrjb attempts to determine which 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, the nsrjb program
prompts you to select a jukebox. You can set the NSR_JUKEBOX environ-
ment variable to the name of the jukebox you want the nsrjb program to
use by default.
NOTE: In a clustered configuration, either the -f device or the -J
hostname option must be provided.
OPTIONS
Options are separated into two groups. The first are the options which
specify the operation to be performed, e.g. label or load media. The
second group list the additional options which provide arguments for
the operation, e.g. specifying the media to be labeled or loaded. Note
that option arguments that have spaces, for example, pool name, must be
enclosed in double quotes.
OPERATION OPTIONS
-a This option is used in conjunction with the -T tags option, to
allocate volumes in a remotely managed jukebox. A volume must
be allocated before it can be labeled and used by a NetWorker
server.
For STL silos a -d option can be added for silos that support
depositing (also known as importing or entering) tapes from
their I/O ports. The -d must appear after the -a on the command
line. This function is usually handled by the silo management
software, but is added here for ease of use. This option may
not be supported on all silos supported by NetWorker.
There are two types of volumes which may be allocated or added
to an AlphaStor jukebox resource: scratch or in-use. The term
scratch is used to indicate volumes currently not being used by
NetWorker. An in-use volume is one that was already used by
NetWorker before being imported into AlphaStor.
Use -a in conjunction with -T tags option to allocate volumes
for NetWorker's use. Both scratch and in-use volumes can be
allocated this way. By specifying the barcode or physical car-
tridge label with this option, volumes from specific media car-
tridges may be allocated. In-use volumes will be discovered by
the jukebox inventory operation.
Use -a in conjunction with -T tags and volume names to directly
add in-use volumes to an AlphaStor jukebox resource. The tag
is the name given to the volume when it was imported into
AlphaStor. The volume name is the volume name recorded in Net-
Worker's media database.
See -x for a description of how volumes are removed from a
remote jukebox's list of volumes available for use by a Net-
Worker server.
-C Displays the current volumes in the jukebox and the devices
associated with the jukebox. This is the default command
option, used if no other command options are specified. It dis-
plays a list of slot numbers, volume names, media pools,
optional bar code information, volume ids and volume modes. If
the jukebox attribute Bar Code Reader is enabled and there are
bar code labels on the media volumes, then the bar code label is
included in the list. If Bar Code Reader is set and the volume
does not have a bar code label, a dash prints, indicating that
there is no bar code label on the media. By default the short
volume id of a volume is displayed. Using the verbose option
(-v) displays the long volume id along with other information
described below. The -C option does not perform an actual juke-
box inventory; nsrjb only reports on the volumes currently con-
tained within the jukebox resource. Volumes may be succeeded by
one of the following flags: an (R), to indicate the volume is
read-only; or an (A), to indicate the volume is either an
archive or a migration volume. When combined with the -v
option, the capacity of the volumes that have been filled is
also 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. The Mode field can have one of three values:
manually recyclable to indicate that the volume will not be
automatically recycled or relabeled; recyclable, to indicate
that the volume is eligible for automatic recycling; or blank to
indicate that neither of the other two values apply.
After the slot map prints, a line about each device is dis-
played. For each enabled device, the following information is
provided: drive number, device pathname, 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
number and pathname are displayed, along with the message dis-
abled. When several device resources share a physical drive in
the jukebox, via the same hardware id attribute value, the drive
number is only displayed on the first device pathname sharing
the drive.
-d Deposits (loads into the jukebox) one or more cartridges from
the cartridge access ports (also called import/export elements,
mail slots, or I/E ports).
The number of cartridges to deposit is determined by the number
of specified slots or tags. All empty slots in the jukebox are
deposited, if slots or tags are not specified. Multiple desti-
nation slot ranges may be specified, full slots are skipped. If
all available import ports are empty and there are cartridges to
deposit, the operator will be prompted to fill the import ports.
When the -N option is used in conjunction with the jukebox
polling feature, the jukebox will poll for cartridges in the
import ports until all of the cartridges are deposited or an
error occurs. Exceeding the polling timeout waiting for addi-
tional cartridges is considered an error.
Specifying volume names on the command line is not recommended.
The inventory command should be run to accurately determine the
volume names.
If -d is used with a -T tags option, then the command is assumed
to be running on a silo, and is treated internally as if it had
been run with the -a and -d options. Specified volume tags
(barcodes) will be deposited into the silo and then NetWorker
will attempt to allocate them for its use. Depending on the
exact type of silo used, this allocation step may or may not
succeed. You should verify the success of the allocation, and
retry the command with just the -a option for all of the tag
values specified. If the tags have already been allocated, you
will see a message indicating this. This is not an error, and
only means that the volumes had already been successfully allo-
cated for use by NetWorker.
-F Releases a shared device contained within an STL silo. This
option is only available for tape libraries with device sharing.
See nsr_jukebox(5).
-h Displays the actions and results of the past 120 jukebox com-
mands issued. These include commands issued on the command line
by the user, or requests that were started automatically by Net-
Worker. If you wish to change the number of command lines saved
in the history, you may set the environment variable NSRJB_HIS-
TORY_COUNT to a value between 20 and 2000. Values smaller than
20 will result in 20 being used, and values larger than 2000
will result in 2000 being used.
-H Resets the jukebox hardware (and the NetWorker database repre-
senting the jukebox) to a consistent state. The jukebox clears
the transport and then unmounts and unloads volumes from the
drives to slots. An actual inventory is not performed; (see the
-I option). If the jukebox senses that the inventory is out-of-
date, it prints an appropriate message.
For jukeboxes that do not correctly report whether the drives
are loaded, the -HH option forces an unload of all the drives.
This option is also useful in situations where a tape is still
loaded in a drive, but NetWorker thinks that the drive is empty.
If the device is also specified with the -HH option, nsrjb will
force an unload on the specified device only. Note that certain
jukeboxes have a firmware bug where an attempt to unload a tape
that has not been ejected will cause it to attempt the unload
forever. This will cause nsrjb to hang.
For silos, only devices which NetWorker thinks are loaded are
unloaded. You can use the silo controller to empty other
drives.
For AlphaStor jukeboxes, resets the jukebox devices and the Net-
Worker database representing the jukebox to a consistent state.
The operation synchronizes the state of the devices in the juke-
box and the media in the jukebox resource with AlphaStor. Net-
Worker queries AlphaStor for information about volumes in the
jukebox resource and which volumes are currently mounted. It
uses this information to synchronize the jukebox and device
resources to be consistent with the information reported by
AlphaStor. If the -p option is also specified, a check opera-
tion will be performed on the loaded volumes.
NetWorker automatically queries AlphaStor to synchronize the
jukebox and device resources whenever the server is started.
-I Performs an inventory on the jukebox's contents. Use this option
to ensure that the mapping between slot number and volume name
is correct. If necessary, the volumes in the specified slots
may be loaded into a device, so their labels may be read. This
option can take a long time to complete depending on the type of
jukebox.
If a jukebox has a bar code label reader, and the jukebox
resource attribute Bar Code Reader is set, and Match Bar Code
is set, then the volume name associated with a slot is derived
from the media bar code label.
Tapes are always loaded into drive for labels to be read in the
following conditions:
1) jukebox does not have a barcode reader
2) jukebox has barcode enabled and tape's barcode is not in the
media database
3) jukebox has barcode and match barcode enabled; tape's barcode
is in the media database but location is empty
If a bar code label on the media has changed, then the NetWorker
media database is updated with the new bar code label. Proper
use of a jukebox's bar code reader can minimize the time it
takes to perform an inventory.
The -II option can be used to perform a fast inventory which
operates only on slots with volumes that can be verified without
reading their labels. Since fast inventory does not involve
reading the tapes, this option may not be combined with a device
specification ( -f).
The -Ip option forces tapes to be loaded into the drive for
their label to be read even if the volume's label can be veri-
fied.
For jukeboxes that have element status capability you can use
the -E option in conjunction with the -I option to reinitialize
the jukebox's inventory state. The -E option increases the
amount of time it takes to inventory a jukebox, because the
hardware must check every component, including all slots and
drives, for the presence of media. You should only use this
option if you are manually swapping media in or out of a juke-
box.
For AlphaStor jukeboxes, this operation is used to synchronize
NetWorker and AlphaStor databases. It insures that AlphaStor
and NetWorker agree to the state of all volumes allocated to
this NetWorker server and listed in this jukebox resource. If
the -p option is also specified, nsrjb requests the volumes be
loaded so that labels on each volume may be verified.
To allocate slots in a jukebox for cleaning cartridges, set the
jukebox resource attribute Auto Clean to Yes and the Cleaning
Slots attribute to a non-empty range of slots. For further
information see nsr_jukebox(8). Volumes from slots that are
reserved for cleaning cartridges are not loaded during the
inventory of a jukebox. For jukeboxes that do not support ele-
ment status or have a bar code reader, the -U uses option must
be used to enter a cleaning cartridge into the jukebox's inven-
tory. For jukeboxes that support element status or have a bar
code reader, cleaning cartridge slots that were previously empty
but now contain a cartridge have the number of uses for the
cleaning cartridge is the value set in the jukebox attribute
Default Cleanings.
-l Loads and mounts specified volumes. Volumes are specified by
name, by the slot in which the volume resides, or for remote
jukeboxes by the tag associated with the volume. The operation
fails, if the number of volumes specified is greater than the
number of available drives.
For AlphaStor jukeboxes, the command will attempt to mount vol-
umes into devices accessible from the storage node upon which
nsrjb is running. The -J option can be used to specify a dif-
ferent storage node.
The -f option can be used to specify media devices into which
volumes are loaded.
If loading a device located in a remote jukebox, an NDMP device
for instance, the "-f" option with the "rd=" syntax in the
device name must be specified.
-L Labels the volumes in the specified slots, or for remotely man-
aged jukeboxes, by specified tags. Names for the volumes
labeled are derived from media bar code labels, volume names
specified on the command line, or generated by referencing the
label template resource for the given pool. If you do not spec-
ify any slots, the range of slots is as described in the
NSR_jukebox resource for the jukebox. Labeling a complete juke-
box may take a long time.
If the jukebox has a bar code label reader, and the NSR_jukebox
resource attributes Bar Code Reader and Match Bar Code Labels
are set, then the volume label is derived from the bar code
label on the media. If the jukebox resource attribute Match Bar
Code Labels is not set, or the jukebox does not have a bar code
reader, then the volume label is derived from volume names spec-
ified on the command line. If more volumes are being labeled
then volume names specified on the command line, then the volume
label is derived from the label template. No matter how the
volume label is derived, if the media labeled has a media bar
code label, the bar code is stored in the NetWorker media
database so that it can be used during inventory operations.
Volumes names cannot be used without -S or -R options for regu-
lar jukeboxes. The reason for this is that the volume names do
not exist in the media database in the case of the new or
imported tapes.
Volumes located in slots set aside for cleaning cartridges can-
not be labeled. See -I for a discussion of how the slots of a
jukebox are set aside for cleaning cartridges.
If an empty slot is encountered, an informational message is
displayed and the operation continues.
See the -m option if you want the volume to be automatically
mounted after being labeled.
-o mode
Sets the mode of a volume or range of slots. The following mode
values are available: [not]recyclable, [not]readonly, [not]full,
or [not]manual. The [not]manual mode values are only valid when
used in conjunction with the -L option. If the -Y option is not
used, you are prompted to confirm the operation for each volume.
See nsrim(8) for a discussion of the per-volume flags.
-p Verifies and prints a volume label. A slot or for remotely man-
aged jukeboxes a tag may be specified. The device used to read
the volume may also may be specified. See nsrmm(8).
-u Unloads a volume from a device. To unload a volume from a
device, specify the name of the volume, the device in which the
volume is loaded, or the slot from which the volume was loaded.
If no volume, device or slot is specified, media is unloaded
from all loaded devices.
-U uses
Sets the number of times a cleaning cartridge can be used. Slots
can also be specified. Any slot specified must be in the range
of slots set aside for cleaning cartridges in the jukebox. If a
range of slots is not specified, all slots set aside for clean-
ing cartridges are updated. For slots that are currently empty
in the jukebox's inventory, this option updates the inventory to
indicate that the slot is occupied by a cleaning cartridge. For
a discussion of how slots of a jukebox are set aside for clean-
ing cartridges, see -I.
Uses must be either a positive integer, or the reserved words
remove or default. The reserved word remove can be used (for
example, -U remove) to delete the cleaning cartridge(s) from the
NetWorker inventory. Specifying default sets the number of
times a cleaning cartridge may be used to the value of the
default cleanings attribute for the jukebox. See nsr_juke-
box(5).
You can use the -T option in conjunction with the -U option to
add cleaning cartridges to a Silo Tape Library (STL). This
option sets aside a cleaning slot in the STL each time a clean-
ing cartridge is added. For a description of how to remove
cleaning cartridges from an STL, see -x. See -I for a discus-
sion of how slots in a non-STL jukebox are set aside for clean-
ing cartridges.
-V Display the current jukebox configuration.
-w Withdraws (ejects media from the jukebox) one or more cartridges
to the cartridge access ports.
Cartridges must be specified by slot, volume name or tag. Mul-
tiple slot ranges and volume names may be specified, empty and
duplicate slots are ignored. If the available export ports are
full and there are cartridges to withdraw, the operator will be
prompted to empty the export ports. When the -N option is used
in conjunction with the jukebox polling feature, the jukebox
will poll for empty export ports until all cartridges are with-
drawn or an error occurs. Exceeding the polling timeout waiting
for empty ports is considered an error.
If -w is used with a -T tags option, then the command is assumed
to be running on a silo, and is treated internally the same as
if it had been run with the -x and -w options. Specified volume
tags (barcodes) are withdrawn from the silo. Then NetWorker
deallocates them from its list of volumes for that silo. In
general, you can only withdraw at most about 40 volumes from a
silo at one time, although this limit differs on different silo
models. If a given command does not cause any tapes to be with-
drawn from the silo, try again using fewer tag values on the
command line.
-x This option, when used in conjunction with the -T tags option,
is used to remove volumes from a remote jukebox. The specified
volumes are removed from the remote jukebox's list of volumes
available for use by a NetWorker server.
For STL silos, a -w option can be added to withdraw or eject
tapes from the silo or to physically remove the tapes from the
silo. The -w must appear after the -x on the command line.
This function is normally handled by the silo management soft-
ware, but is added here for ease of use. This option may not be
supported on all silos supported by NetWorker.
See -a for a description of how volumes are allocated for use by
a NetWorker server.
ADDITIONAL OPTIONS
-b pool
Specifies the media pool to which the volume should belong. The
pool may be any pool currently registered with the NetWorker
server. The pool names can be viewed by selecting Media Pools
from the left pane of NetWorker Management Console's Media dis-
play. The pool name is referenced by the NetWorker server when
determining what save sets can reside on the volume. If you
omit this option the volume is automatically assigned to the
Default pool. If you specify a pool name without a volume name,
nsrjb will use the next volume name associated with the speci-
fied pool's label template resource. See nsr_label(5).
-c capacity
Overrides the volume's default capacity. See nsrmm(8).
-B Verifies that the volume currently being labeled does not have a
readable NetWorker label. Before labeling a volume, NetWorker
attempts to read any existing labels written on the volume. If
you specify this option and the volume has a NetWorker label
that is readable by the device currently being used, the label
operation is canceled and an error message is displayed. If the
volume does not have a label, or has a label that is not read-
able by the current device, then the volume can be labeled.
This option is used by nsrd(8) to label volumes automatically
when nsrmmd(8) makes a request for a volume while saving data.
-e forever
Specifies the volume to be an Archive volume. (see nsrmm(8)).
-E Initializes element status for jukeboxes that support this fea-
ture. You can use this option 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. The -V
option may be used to determine whether a jukebox has this capa-
bility. When swapping media into the jukebox where media was
not previously loaded, it may be necessary to reinventory (-I)
the jukebox with the -E option so the jukebox reinitializes its
element status.
-f media device
Specifies a media device to be used for an operation. Use the
pathname of the media device as it is configured in the jukebox
resource. When more than a single media device has been config-
ured for a jukebox, nsrjb selects available devices with the
lowest value for the device resource attribute accesses. See
nsr_device(5). When loading or verifying volumes, the number of
devices available must at least be greater than or equal to the
number of volumes specified for the operation. For other opera-
tions, the value of the jukebox attribute max parallelism is an
upper bound on the number of devices that may be used by any
nsrjb command. See nsr_jukebox(5). You can override the device
selection by using the -f option. You can use this option mul-
tiple times, to specify more than one media device.
For AlphaStor jukeboxes, the device resource is not tied to a
physical device. It is a logical device resource. An associa-
tion between this logical device and the physical device lasts
as long as media is loaded in the device. NetWorker never asks
AlphaStor to load media into a particular device. It allows
AlphaStor to choose the device into which the media is loaded.
Then nsrjb creates an association between the actual device and
NetWorker logical device resource by assigning values to the
device's logical name, logical type, and logical family
attributes. See nsr_device(5). SmartMedia and NetWorker have
different names for device and media types. nsrjb maintains a
table to map between AlphaStor and NetWorker names to be able to
correctly set the values of these attributes. This table can be
updated dynamically to support additional SmartMedia drive
and/or media types. The file /nsr/res/smdevmap.txt is used to
make additions to nsrjb's map table. Each line in this file
contains four columns, SmartMedia cartridge type, SmartMedia
bitformat, NetWorker device resource media type, and NetWorker
device resource family type. The SmartMedia bitformat maybe a
regular expression, all other values are strings. As an example
the line,
DTL7000 DLT8000.* DLT8000 tape
maybe used for the DLT8000 device using SmartMedia DLT7000 car-
tridge type.
-g This option is kept for historical reasons only. It has no
affect.
-G This option is used only by the server to have the autoloader
mount or label a volume in a Network Data Management Protocol
(NDMP) device.
-i This option is kept for historical reasons only. It has no
affect.
-j name
Specifies 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.
-J hostname
Specifies a particular hostname to use. Drive selection by
nsrjb will be restricted to a drive on the given hostname. This
option can be used with the -l (load) or -L (label) options, and
cannot be used with the -f option.
If the jukebox that you manage is connected to a NDMP server
(e.g., a NAS filer), you need to use this option to specify the
NDMP server. See Examples.
-m Mount a volume after it has been labeled. There must be enough
available drives to mount all volumes to be labeled.
-n Loads, but does not mount, the volume when specified with the -l
option.
-N Tells nsrjb to skip the confirmation prompt when used in con-
junction with the -LR options. When NetWorker recycles volumes,
NetWorker prompts you to confirm that it is okay to overwrite
any volumes considered to be nonrecyclable. See nsrim(8) for a
discussion of the per-volume flags.
-P ports
Specifies a cartridge access port or range of ports to deposit
or withdraw volumes.
Ranges are specified as low to 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. You can specify only one port range for a command.
-q Runs the nsrjb program in quiet mode. Turns off all of the mes-
sages normally produced when verifying, labeling, loading, or
unloading volumes, or inventorying a jukebox. You can use this
option only with the -p -L, -l, -u or -I options.
-r Loads the volume as read-only. You can use this option only
with the -l option. See nsrmm(8).
-R Recycles the volume. If the conditions as described for the -L
option are met for using bar codes as labels, then the volume
label is derived from the bar code label on the media (without
exception). If the volume is recycled to a new pool, the label
is generated by referencing the label template resource for
the given pool. Otherwise the volume is relabeled using its
current name. If a volume is recyclable, you are not prompted
for confirmation as to whether or not this volume may be over-
written. See nsrmm(8) for a discussion of the per-volume flags.
-s server
Specifies the controlling server when nsrjb is used on a storage
node. To use nsrjb on a storage node, the command must be run
on the storage node. See nsr_storage_node(5) for additional
information on storage nodes.
-S slots
Specifies a slot or range of slots on which to operate. Specify
the slot range from low to high integer order. 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. You can specify multiple slot ranges
for a command.
-T tags
Specifies tags or barcodes of volumes in a remote jukebox. You
can specify this option more than once for a command.
tags can specify a single volume tag or a volume tag template
similar to a label template. See nsr_label(5). The volume tag
Template is a list of template fields separated by slashes "/".
A template field is a constant alphanumeric string or an alpha-
betic or numeric range represented by the low and high value
separated by "-".
This template differs from the templates used in NetWorker GUI.
Each portion of the template is entered into a separate line in
the GUI's dialog box instead of using "/" as a separator.
The tag is used to identify the media when a request is made of
the agent managing the remote jukebox. This identifier is deter-
mined by the remote agent. A tag often is a bar code label.
When making a request to load media into a device, NetWorker
sends the tag with the request to the agent to identify the
media to be loaded. Volumes in a jukebox resource are listed in
alpha-numeric order of their tags. Therefore, the order in the
jukebox resource may change as media is allocated and deallo-
cated, and has no relation to the slot in which the media may
reside in a physical library.
-v Set the verbosity level by the number of times this flag is
specified on the command line. The maximum verbosity level sup-
ported is 5. See other arguments for specific details on the
verbose output.
-X You can use this option in conjunction with -x to purge a volume
from NetWorker's media database when the volume is being deallo-
cated. A prompt is displayed to confirm that the volume is to
be purged from the media database, unless -Y is also specified.
-Y Disables confirmation prompting. Rather than prompting for con-
firmation, a yes answer is assumed. Prompts are normally gener-
ated when a volume is being relabeled before its expiration
date, or when a volume is still registered in the NetWorker
media database. If the operation is to label ( -L ) a volume or
to load ( -l ) a volume, with the -R option also specified, and
the volume is recyclable, there is no prompt to confirm whether
the volume may be overwritten.
volume name
Specifies the name to be used when labeling a volume. After a
volume has been labeled, the volume name is used to select media
for an operation. Multiple volumes names may be specified for a
single command, and must come at the end of the command line.
EXAMPLES
Labeling volumes:
To label all of the volumes in a jukebox, use the -L option:
nsrjb -L
To specify a particular pool, use the -b option:
nsrjb -L -bOffsite
Labeling the volumes in slots 5 through 19:
To label the volumes in slots 5 through 19, use the -S option:
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 generates the subsequent names.
Mounting a volume after it has been labeled:
To mount a volume after it has been labeled use the -m option:
nsrjb -L -S 20 -m
To mount an NDMP volume after it has been labeled, use either of
the following commands with the -m option:
nsrjb -J -L -S 20 -m
or
nsrjb -L -S 20 -m -f
The command fails if there are not be enough drives to mount all
volumes to be labeled.
Labeling volumes with a standard name:
To label the volumes in slots 21 through 28, starting with a
name different than that referenced by the label template asso-
ciated 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
uses 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
in use, the name is skipped.
Loading a volume:
To load volumes, use the -l option.
nsrjb -l
nsrjb will select volumes to load into selected devices. It
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, include the
-f option.
nsrjb -l -f /dev/nrst1 mars.005
Loading volumes in a jukebox connected to an NDMP server:
To load the volume in slot 1 of jukebox mylibrary (connected to
NDMP server 10.31.32.220), use the -J and -j options.
nsrjb -J 10.31.32.220 -j mylibrary -l -S 1
To load the volume in slot 1 of jukebox mylibrary (connected to
NDMP server 10.31.32.220) to a specific device nrst0l,
nsrjb -l -f "rd=10.31.32.220:nrst0l (NDMP)" -j mylibrary -S 1
Unloading a volume
You can unload a particular volume, slot, or device. To unload
volume mars.0028, use the -u option:
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 to a jukebox's devices, use the -C option:
nsrjb -C
The -C option is the default and is used when no other options
are selected. A range of slots may also be specified. For exam-
ple, to display the volumes in slots 10 through 23, use the -S
option:
nsrjb -S 10-23
Setting the number of uses for a cleaning cartridge:
To set the number of times all cleaning cartridges in a jukebox
may be used to 12, use the -U option:
nsrjb -U 12
To set the number of times the cleaning cartridge in slot 10 may
be used, use the -S option:
nsrjb -U 25 -S 10
Slot 10 must be a slot set aside for cleaning cartridges in the
jukebox.
Inventorying the volumes:
To reconcile the actual volumes and the list of volumes produced
by nsrjb, use the -I option. Each volume may be loaded into a
device and examined for a NetWorker label (depending on bar code
settings and other factors). The internal list is then updated
with the new information. After all volumes have 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, use the -S option:
nsrjb -I -S 17-43
Like labeling, volume inventory may take 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.
Using the cartridge access port:
To withdraw cartridges from jukebox slot 7 through 11 to the
cartridge access port 5 through 10, use the -w option along with
the -S and -P options:
nsrjb -w -S 7-11 -P 5-10
To deposit cartridges into jukebox slot 8 through 10 from the
cartridge access port 3 through 5, use the -d option along with
the -S and -P options:
nsrjb -d -S 8-10 -P 3-5
Using barcode templates on tape libraries:
To add volumes with barcodes D001A, D002A, ..., D100A to the
volumes available for NetWorker in the tape library, use the -a
and -T options:
nsrjb -a -T D/001-100/A
For a SmartMedia jukebox, to allocate 3 volumes from any media
and to make the volumes available for NetWorker, use the -a and
-a options:
nsrjb -a -T +3
To deposit tapes labeled with barcodes D001A, D002A, ..., D012A
To remove volume with barcode D055A from the volumes available
for NetWorker in the tape library, and to withdraw it from the
tape library physically (for example, for off-site storage), use
the -x and -T options, along with the -w option:
nsrjb -x -T D055A -w
To label volumes with barcodes D010A, D011A, ... , D020A, use
the -L and -T options:
nsrjb -L -T D0/10-20/A
To add cleaning cartridge with barcodes C010A, that can be used
the default number of time for this jukebox, use the -U and -T
options:
nsrjb -U default -T C010A
Forcing an unload of all drives on a tape library:
nsrjb -HH
ENVIRONMENT VARIABLES
NSR_JBOX_POLL_JUKEBOX_OP_STATUS
When nsrjb is run to initiate a jukebox operation, a request is
submitted to nsrmmgd, for execution. Status of the operation is
reported by nsrmmgd using a NSR JUKEBOX_OPERATION_STATUS
resource. This resource is stored in the RAP database main-
tained by nsrd. Periodically nsrjb polls nsrd to determine the
status of the request. The default is to poll every 10 seconds.
Set this environment variable to modify the polling interval.
Minimum interval is to poll every 5 seconds and the maximum
interval is 30 seconds.
FILES
/nsr/mm/mmvolume The NetWorker media database.
/nsr/res/nsrdb The configuration database containing resource
descriptors.
/nsr/res/smdevmap.txt
The file used to map from SmartMedia media and drive
types to a NetWorker device resource media type.
jukebox.
SEE ALSO
jbconfig(8), jbexercise(8), mminfo(8), mmlocate(8), nsr(8), nsrmmgd(8),
nsrd(8), nsr_layout(5), nsr_device(5), nsr_jukebox(5), nsr_op(5),
nsr_notification(5), nsr_storage_node(5), nsradmin(8), nsrim(8),
nsrmm(8), nsrmmd(8), nsrwatch(8)
DIAGNOSTICS
The exit code returned by the nsrjb command has one of four possible
values:
0 (success)
A zero exit code indicates successful execution of the command.
1 (not executed)
Indicates that the command caused an error that prevented it
from being submitted for execution. For example, an invalid com-
mand-line argument.
2 (non-retryable)
The command was submitted to nsrmmgd for execution, but a "non-
retryable" error occurred. For instance, the named volume does
not exist.
3 (retryable)
The command was submitted to nsrmmgd for execution, but a
"retryable" error occurred. For instance, a required drive is
busy.
In general, a "retryable" error indicates that if you simply retry the
same nsrjb command again, there is a possibility that it would succeed
this time. Conversely, a "non-retryable" error indicates that some user
intervention is required in order to resolve the issue, before the
nsrjb command should be retried.
NetWorker 7.6.2 Jul 14, 11 nsrjb(8)