NAME

scanner − NetWorker media verifier and index rebuilder

SYNOPSIS

scanner [ −Bimnpqv ] [ −s ssid ] [ −c client ] [ −N name ] [ −f file ] [ −r record ] [ −t type ] [ −b pool ] device [ −x command arg ...  ]

DESCRIPTION

The scanner command directly 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 on-line indexes.  Only the super-user (root) may run this command.  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 no options or just −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, for each save set found, one line of information is written to standard output, 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 ad-hoc saves.  The size is the number of bytes in the save set.  The column labeled files gives 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.  At the time 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 one 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
Specify which pool the volume should belong too. This option only applies for versions of NetWorker which did not store the pool information on the media. For such versions, one may 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 Quickly scan the tape looking for the start of bootstrap save sets.  The program will only read the first record of each tape file and see if a save set with the name “bootstrap” starts there.  When the entire tape has been exhausted, the save set id and tape file location of the most recent bootstrap save set is printed. 

−c client
Only process save sets that came from machine client. This option can be used multiple times and is most useful with the −i and −x options and can be used in conjunction with the −N option. 

−f file Start the scan at the specific media file number.  This can save time by avoiding the scan of potentially unused information if the entire volume is not being scanned and you happen to know from already existing NetWorker media information (see mminfo(8)) where the area of interest on the volume starts.  This option does not make sense on some kinds of media, such as optical disks, for example. 

−i Rebuild both the media and the on-line file indexes from the volumes which are read.  If you specify a single save set with the −s ssid option, only entries for the specified save set will be made to the on-line file index. 

−m Rebuild the media indexes for the volumes read. 

−n Go through all the motions, but do nothing with regard to media or index database rebuilding.  When used with the −i option, this provides the most complete media checking available, while not modifying the databases at all. 

−N name
Only process save sets whose name is name. This option can be used multiple times and is most useful with the −i and −x options and can be used in conjunction with the −c option. 

−p Print out information save set notes as they are processed. 

−q Display only errors or very interesting messages. 

−r record
Start the scan at the specific media record number. This can save time by avoiding the scan of potentially unused information if the entire volume is not being scanned and you happen to know from already existing NetWorker media information (see mminfo(8)) where the area of interest on the volume starts. 

−s ssid
Extract the specified save set(s). When used with the −i or −x options, this option can be use multiple times and is addition to any save sets selected by using the −c and −N options.  Otherwise, the volume will be scanned for save set ssid which will be written to the standard output.  Most often this 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).  If the volume information is still in the media database, the user has the option of running recover by save set (see recover(8)). 

−t type
Specify the type of media (for example, optical for an optical disk, or 8mm 5GB for an 8mm 5GB tape).  Normally the type is obtained from the NetWorker server, if one of the known devices is used (see nsr_device(5)). 

−v Display more verbose messages, such as a log of each note chunk, and a message after each hundred media records. When the −i option is used, this prints out a line for each client file, which can produce an enormous amount of output. 

−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 will be connected to a new instance of the command’s stdin. 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)). 

EXAMPLES

Verifying a tape:

scanner /dev/nrst0

scanner: scanning 8mm tape mars.001 on /dev/nrst0

client namesave setsave time  levelsizefilesssid S
space/export10/07/94 12:38 f1007624601003516983 E
space/usr10/07/94 13:14 f27185116318516984 E
space/nsr10/07/94 12:40 f77292280843616980 S
space/10/07/94 13:22 f169319251816985 S

scanner: reached end of 8mm tape mars.001

Rebuilding the on-line file index from a tape:

scanner -i /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]?

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), nsrindexasm(8), nsrmmd(8), nsr_device(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. The case of an unexpected file number is normal when scanner reaches the logical end of a tape which 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 will attempt to re-synchronize and send the rest of the stream.  However, because programs like uasm(8) are unable to handle decoding stream with parts missing in the middle, scanner sends the remainder of the stream to a file.  You can cause this stream to be decoded 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 will normally appear when running in verbose mode on a tape or disk that has been recycled. It does not indicate an error condition, but just 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.  Therefore, it is of dubious value.  If on-line 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 damage tape.  Once this condition is detected, the process rebuilding the indexes for the particular save stream exists; 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. 

must be run by super-user
A normal (non-root) user tried to invoke this command.

cannot convert ‘arg’ to a file number
The −f and −r options take 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. 

NetWorker 4.1.2  —  Last change: May 1995