SCANNER(8)

NAME
scanner - NetWorker media verifier and index rebuilder

SYNOPSIS

scanner [ options ] -B device

scanner [ options ] -B -S ssid [ -im ] 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.

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 contents 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 versions 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 internally 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, Synchronize, 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 absence of the -S option, scanner quickly scans the tape for the start of bootstrap save sets. The program only reads the first record at each file mark on the media to see if a save set with the name ``bootstrap'' exists. When the entire media has been exhausted, the save set id and file location of the most recent bootstrap save set is printed. 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.

-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 online file index.

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

-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 addition 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 bootstrap. Only one ssid is allowed in this case.

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

-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 specified UNIX command. Instead specify conflict resolution parameters 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.

EXAMPLES

Verifying a tape:

    scanner /dev/nrst0

scanner: scanning 8mm tape mars.001 on /dev/nrst0
.nr 3crow 0
client namesave setsave time  levelsizefilesssid S

.nr 3brule 1
.nr 3crow 1
space/export10/07/94 12:38 f1007624601003516983 E

.nr 3brule 1
.nr 3crow 2
space/usr10/07/94 13:14 f27185116318516984 E

.nr 3brule 1
.nr 3crow 3
space/nsr10/07/94 12:40 f77292280843616980 S

.nr 3brule 1
.nr 3crow 4
space/10/07/94 13:22 f169319251816985 S

.nr 3brule 1
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-synchronize 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 processing 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 starting 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 informational, 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 NetWorker services have to be running in order to query these device configurations.

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