NetWorker command: scanner
NAME
scanner - NetWorker media verifier and index rebuilder
SYNOPSIS
scanner [ options ] -B -S ssid [ -im ] [ -z ] device
scanner [ options ] -i [ -S ssid ] [ -c client ] [ -N name ] device
scanner [ options ] -m [ -S ssid ] device
scanner [ options ] [ -S ssid ] [ -c client ] [ -N name ] device [
command ]
options: [ -npqv ] [ -f file ] [ -r record ] [ -s server ] [ -t type ]
[ -b pool ]
command: -x command [ arg ... ]
DESCRIPTION
The scanner command reads NetWorker media, such as backup tapes or
disks, to confirm the contents of a volume, to extract a save set from
a volume, or to rebuild the NetWorker online indexes. As installed,
only the super-user may run this command. However, the command's modes
can be modified such that normal users may run the command while
retaining root privileges; see nsr(8) for more details. The device
must always be specified, and is usually one of the device names used
by the NetWorker server. For tape drives, it must be the name of a
'no-rewind on close' device. For adv_file type device, read-write
device name will be used when read-only device name is specified.
When scanner is invoked with either no options or -v, the volume on the
indicated device is opened for reading, scanned, and a table of con-
tents is generated. The table of contents contains information about
each save set found on the volume. By default, one line of information
is written to standard output for each save set found containing the
client name, save set name, save time, level, size, files, ssid and a
flag. The client name is the name of the system that created this save
set. The name is the label given to this save set by save(8), usually
the path name of a file system. The save time is the date and time the
save set was created. The level values are one-letter abbreviated ver-
sions of full, incremental, levels 0 through 9, or blank for manual
saves. The size is the number of bytes in the save set. The files
labeled by column provide the number of client files contained in the
save set. The ssid (save set identifier) is an identifier used inter-
nally to reference and locate this save set. This same identifier may
be specified explicitly with the -S option to extract a particular save
set.
The table of contents is based on synchronization (sometimes called
'note') chunks (see mm_data(5)) interspersed with the actual save set
data. There are four types of note chunks: Begin, Continue, Synchro-
nize, and End, symbolized by a flag of B, C, S or E respectively. The
Begin note is used to mark the start of a save set. When a beginning
chunk is written, the save set size and number of files are not known.
The Continue note is used to indicate that this save set started on a
different volume. The Synchronize note marks locations in the save set
where you may resume extracting data in the event of previous media
damage (a client file boundary). The End note marks the end of the
save set, and causes the table of contents line to be printed. The
other notes are displayed only when the -v option is selected.
OPTIONS
-b pool
Specifies which pool the volume should belong to. This option
only applies for versions of NetWorker that do not store the
pool information on the media. For these versions, you might
need to specify the media pool the volume should belong to if
the user does not want the volume to be a member of the Default
pool. For volumes where the pool information is stored on the
media, the media must be relabeled (destroying all data on the
media) to assign the media to a different pool.
-B When used in conjunction with the -S option, the save set id
specified is flagged as that of a bootstrap.
-c client
Process only save sets that come from the specified NetWorker
client machine. This option can be used multiple times and in
conjunction with the -N option, but only in presence of the -i
or -x option.
-f file
Starts the scan at the specific media file number. This option
is not useful on media such as optical disks and file device
types, for example.
-i Rebuilds both the media and the online file indexes from the
volumes read. If you specify a single save set with the -S ssid
option, only entries for the specified save set are copied to
the online file index. Note that for version 6.0 and later, if
you have the tape that contain the index backups that go along
with the data backups, the recommended way of restoring your
indexes is to run scanner -m to reload the media database
entries for the index and data backups. Once that is done, you
should run nsrck -L7 -t date <clientname> to recover the index
for the client as of the time of the backups on the tape. This
will roll the index entries for that time back into the index.
However, if you have tapes for which there are no index backups,
then you will need to use the -i option to reconstruct the index
entries.
Note:
For NDMP save sets or DSA save sets, this option does not recon-
struct the index entries from the volume. However, if you have
index backups, use scanner and nsrck as said above. For volumes
that have a combination of DSA save sets and regular NetWorker
save sets, scanner -i will skip over the DSA save sets with an
error.
-m Rebuild the media indexes for the volumes read. If you specify a
single save set with the -S ssid option, only entries for the
specified save set are copied to the media index, the save set
data will be written to standard output which may be redirected
as needed. The media database will not retain the "scanned-in"
status. There is no longer a flag to show that status in the
"ssflags" field. The saveset gets a new browse and retention
policy depending on the time that it was scanned in and the
clock starts ticking for the saveset.
-n Checks all media without rebuilding the media or index
databases. When used with the -i option, this option provides
the most complete media checking available, while not modifying
the databases at all.
-N name
Only processes save sets specified by name (a literal string
only). This option can be used multiple times and in conjunc-
tion with the -c option, but only in presence of the -i or -x
option.
-p Prints out information save set notes as they are processed.
-q Displays only errors or important messages.
-r record
Starts the scan at the specific media record number.
-s server
Specifies the controlling server when using scanner on a storage
node. See nsr_storage_node(5) for additional detail on storage
nodes.
-y retention time
Specifies the retention time for completed clone instance of
save sets in the volume(s) being scanned in. This option is
valid only with -i or -m option. If save sets have been speci-
fied using -S option, the retention time of the clone instance
of those save sets will be set to the specified value. Note
that retention time of clone instances not belonging to the vol-
umes being scanned in will not be modified.
-z This end-silently option will cause the scanner to not prompt
for the next volume when the saveset spans onto another volume.
It will not wait for user input, but, will just quit when its
done reading the first volume.
-S ssid
Extracts the specified save set(s). When used with the -i or -x
option, this option can be used multiple times and is in addi-
tion to any save sets selected using the -c and -N options.
Otherwise, the volume is scanned for save set ssid, which will
be written to the standard output. Most often this is piped to
a uasm(8) program running in recover mode to process the save
set (potentially with a directory list to limit the files to be
recovered and potentially using a -m argument to map the file
location). When using -S without -i or -m, scanner prompts for
the volume block size if the volume label is not readable. If
the volume information is still in the media database, the user
has the option of running recover by save set (see recover(8)).
When -B is also specified, ssid is taken to be that of a boot-
strap. Only one ssid is allowed in this case.
Note:
Piping NDMP save set or DSA save set save streams to any recover
program such as uasm(8) is not supported.
-t type
Specifies the type of media, for example, optical for an optical
disk, or 8mm 5GB for an 8mm 5GB tape). Normally the media type
is obtained from the NetWorker server, if a known device is
being used (see nsr_device(5)).
-v Displays more verbose messages, such as a log of each note
chunk, and a message after every 100 media records. When the -i
option is used, a line is printed for each client file (an
enormous amount of output can be produced).
-k This option should only be used when requested by technical sup-
port.
-x command arg ...
Specifies an arbitrary UNIX command to process each new selected
save set. This argument can only occur once at the end of the
argument list (after device). The save stream for each save set
is connected to the stdin of a new instance of the command.
Most often this command is uasm(8) running in recover mode to
process each save set (potentially using a -m argument to map
the file location). If the volume information is still in the
media database, the user has the option of running recover by
save set (see recover(8)). Do not attempt console I/O by speci-
fied UNIX command. Instead specify conflict resolution parame-
ters as arguments passed to the command (e.g.: scanner -S <ssid>
-x uasm -iR -rv). If console interaction is required, pipe
scanner output to the desired Unix command instead of invoking
the command using the -x option.
Note:
Piping NDMP save set or DSA save set save streams to any recover
program such as uasm (8) is not supported.
EXAMPLES
Verifying a tape:
scanner /dev/nrst0
scanner: scanning 8mm tape mars.001 on /dev/nrst0
client name save set save time level size files ssid S
space /export 10/07/94 12:38 f 100762460 10035 16983 E
space /usr 10/07/94 13:14 f 27185116 3185 16984 E
space /nsr 10/07/94 12:40 f 77292280 8436 16980 S
space / 10/07/94 13:22 f 1693192 518 16985 S
scanner: reached end of 8mm tape mars.001
Rebuilding the online file index for a client from a tape:
scanner -m /dev/nrst8
scanner: scanning 4mm tape monday.fulls on /dev/nrst8
scanner: ssid 17458697: scan complete
scanner: ssid 17458694: scan complete
scanner: ssid 17458698: scan complete
scanner: ssid 17458693: NOT complete
scanner: reached end of 4mm tape monday.fulls
scanner: when next tape is ready, enter device name [/dev/nrst8]?
nsrck -L7 -t "06/07/99" supernova
nsrck: checking index for 'supernova'
nsrck: The file index for client 'supernova' will be recovered.
nsrck: Recovering index savesets of 'supernova' from 'quasar'
Recover completion time: Fri Jun 16 14:03:16 2000
nsrck: completed recovery of index for client 'supernova'
nsrck: /disk1/nsr/index/supernova contains 85782 records occupying 14 MB
nsrck: Completed checking 1 client(s)
Extracting a save set for /usr and relocating to /mnt:
scanner -S 637475597 /dev/nrst8 | uasm -rv -m /usr=/mnt
or
scanner -S 637475597 /dev/nrst8 -x uasm -rv -m /usr=/mnt
Extracting all save sets from client mars and relocating to /a:
scanner -c mars /dev/nrst8 -x uasm -rv -m/=/a
SEE ALSO
mm_data(5), mminfo(8), nsrmmdbasm(8), nsr(8), nsrck(8), nsrindexasm(8),
nsrmmd(8), nsr_device(5), nsr_storage_node(5), uasm(8).
DIAGNOSTICS
xdr conversion error, fn %d, rn %d, chunk %d out of %d
unexpected file number, wanted %d got %d
unexpected record number, wanted %d got %d
All three preceding messages are indicative of media errors
(tape blocks are either lost or damaged). In the case of an xdr
conversion error, a non-zero 'chunk' number means that the
block may be partially salvageable. Unexpected file numbers are
normal when scanner reaches the logical end of the media that
has been recycled.
continuation of data in nsrscan.NNNNN.MMMMMM
After an XDR decode error (an error denoted by one or more of
the messages described above), scanner attempts to re-synchro-
nize and send the rest of the stream. However, because programs
like uasm(8) are unable to handle decoding streams with parts
missing in the middle, scanner sends the remainder of the stream
to a file. You can decode this stream manually. For example,
if your original command was:
scanner -S ssid | uasm -r
and a synchronization error occurs, you can decode the rest of
the stream with the following command:
uasm -r < nsrscan.NNNNN.MMMMMM
where the file name you enter corresponds to the name printed in
the diagnostic message.
unexpected volume id, wanted volid1 got volid2
This message normally appears when running in verbose mode on a
tape or disk that has been recycled. It does not indicate an
error condition, but details the conditions normally treated as
the end of the volume.
ssid %d: finished, but incomplete
Scanner has detected the end of a save stream, but the stream
was aborted, and is of dubious value. If online indexes are
being rebuilt, the end of the aborted stream may precipitate the
next message.
(ssid %d): error decoding save stream
As indexes are being rebuilt, scanner detected that the bytes in
the save stream are invalid. This is usually caused by process-
ing an aborted save stream. Other causes may include a damaged
tape. Once this condition is detected, the process of
rebuilding the indexes for the particular save stream exits.
This may precipitate the next message.
write failed, Broken pipe
Printed by scanner when a process rebuilding a save stream's
indexes exits before consuming the entire stream.
You are not authorized to run this command
A normal (non-root) user invoked this command.
could not convert 'arg' to a file number
The -f and -r options require a numeric argument for the start-
ing file or record number of the media.
already exists in the media index
The -i or -m option was specified and the volume was already
listed in the media database. This message is purely informa-
tional, and means that the volume is not being added to the
media database because it is already listed there.
fn %d rn 0 read error I/O error
done with tape_type tape volid volume_name
These messages, when occurring together, are a consequence of
scanner encountering consecutive filemarks at end of the media.
They do not indicate an error condition and can be ignored.
LIMITATIONS
scanner can run without the NetWorker services (for example, nsrd(8)
and nsrmmdbd(8)) when not reconstructing the media or the online file
indexes with most device types. For logical and NDMP devices, the Net-
Worker services have to be running in order to query these device con-
figurations.
File index backups imported from volumes from other NetWorker servers
cannot be recovered by nsrck -L7. You must use mmrecov to recover the
Bootstrap of that NetWorker server before the file indexes can be
recovered.
When scanning a relabeled optical volume (that is, a re-writable opti-
cal volume that had been written once, then re-labeled and used again),
scanner may read off the end of the new data, and attempt to read the
old data from the previous version of the volume, terminating with an
'unexpected volume id' error. This error occurs after all the good
data has been read, and can be ignored.
NetWorker 7.5.1 Mar 21, 09