Data Management

This section provides a command line reference for Backup commands to use for data management. Many of these commands are also automatically invoked by the Backup server during scheduled backups. The commands for HSM and Archive are only available when you enable the optional modules for these features on the Backup server.

savegrp

The savegrp program runs a group of Backup clients through the save process to back up filesystem data. The group of clients is selected by the name assigned (see "NSR group "). Typically, savegrp is invoked automatically, as specified by each group's NSR group resource.

If you do not specify a group name, the Backup group named Default is used. If you specify a group name, clients whose nsr_client resources specify the named group in their Group attribute are included. If you specify an explicit client list with the -c client-name option, the savegrp program only includes the named clients in the backup and ignores other members of the group.

If you enable the Clone attribute for the named group, the savegrp program automatically invokes a clone of the save sets backed up during the save session. The client save sets and their associated file indexes are cloned before the bootstrap save set is generated, which allows the bootstrap to track both the original save sets and their clones. The bootstrap save set is cloned as well. Cloned save sets are sent volumes assigned to the clone pool specified in the NSR group resource.

If a client's Save Set attribute specifies "All," the savegrp program requests a list of the filesystems to perform the save program on (this is called a probe). The probe expands "All" into a list by searching for local and automatically mounted filesystems on the client machine (NFS mount points and manually mounted filesystems are generally not included in the list gathered by the probe).

You cannot run more than one occurrence of the savegrp program on the same group at the same time; the program exits with an error message. If you run different groups at the same time, each group runs save program sessions up to the limit specified in the Parallelism attribute for the nsr_client resource (the default value for Parallelism is 4). However, the Backup server only allows save program sessions up to the limit specified in the server's Parallelism attribute to write to one backup device at a time. Each save set generates a separate save program session, regardless of the client it originates from.

When the save process (and, if enabled, clone process) is complete, a notification with an Event value of "savegrp" and a Priority value of "notice" is sent to the nsr_notification system. This is generally set up to send e-mail to the root user to indicate the success or failure of the backup, the clients backed up during the savegrp execution, and the data saved.

The following example describes the format and options available for the savegrp program:

savegrp [see "Options"] [-R | -G] [group-name]

Options:

[-EIOmnpv] [-l level | -C schedule]

[- e expiration] [- t date] [-r retries]

[-P printer] [-W width] [-c client [-c client...]]

• Use the -c client option to run savegrp on a specific client or clients. When you specify this option, only the named clients from the specified group-name are run.

• Use the -C schedule option to specify the name of the nsr_schedule resource to use for the automatic save level selection process.

• Use the -e expiration option to specify the date when the saved data is to expire. If you use the special value of "forever" for expiration, the volume the data resides on never expires. This is typically used for migration or archive volumes. By default, no explicit expiration date is assigned.

• Use the -E option to estimate the amount of data that is generated by each save set before the save operation is performed. This option results in a double traversal of the filesystems: once to generate an estimate and again to perform the actual save operation. The data itself is only read from the disk on the final pass, because the estimate is performed by accessing the anode information.

• Use the -G option to run only the group, without restart semantics.

• Use the -I option to disable the save operation performed on each client's file index.

• Use the -l level option to specify the level of the save.

• Use the -m option to disable monitor status reports, including all the nsr_notification actions.

• Use the -n option to cause save to perform an estimate as described for the -E option, but not to perform an actual save after it generates the estimate. The -m option is implied when you use the -n option.

• Use the -O option to only save each client's file index. For the server, this results in a save of the bootstrap as well. By default, the Backup server's bootstrap is backed up any time a group that it is a member of runs through a scheduled or manually invoked savegrp execution. The client file indexes and server bootstrap are a vital part of the disaster recovery procedure.

• Use the -p option to run the probe on each client. This provides information on the filesystems and level of save to perform on each client, without an actual save of the data. The -m option is implied when you use the -p option.

• Use the -P printer option to specify the printer that the savegrp program should send bootstrap information to upon completion of the backup.

• Use the -r retries option to specify the number of times the Backup server should retry failed clients before the savegrp program declares the client backup failed. The default value for this option is taken from the NSR group resource. Abandoned saves are not retried, because they may eventually be completed. A retry is not attempted if the -p option is specified.

• Use the -R option to use the information stored on the Backup server to restart a group that was previously terminated (generally, this is due to a crash of the Backup server during a backup).

• Use the -v option to run the savegrp program in verbose mode.

• Use the -W width option to format the savegrp output or notification messages. The default width is 80.

save

The save program, which resides on each Backup client, saves files. You can monitor the progress of a save operation using the X Window System-based nwadmin program or the curses (3X)-based nsrwatchAdministration program.

If you do not specify a path argument either on the command line or through the -I option, the current directory that save is invoked from is saved. The save program saves a directory by saving all the files and subdirectories it contains. The save program does not cross mount points, and it does not follow symbolic links. If you mount the paths indicated from a network file server, the save program instructs you to run the save program on the remote machine, or use the -L option.

Each file in the subdirectory structures specified by the path option is encapsulated in a Backup save stream. This stream of data is sent to a receiving process on the Backup server, which processes the data and adds entries to the client file index for each file in the stream. The data is then directed to long-term storage, either on the server or the designated storage node.

The server's bootstrap and the client file indexes are only backed up automatically during a scheduled or manual backup that invokes the savegrp program. If you never run the savegrp program, either a scheduled or manually invoked backup, you do not have the server bootstrap or client file indexes that are vital to the disaster recovery process.

The following example describes the format and options available for the save program:

save [-BEiLnqvx] [-s server] [-c client-name]

[- N name] [-e expiration] [-f directory-file]

[-b pool] [-F file] [-I input-file] [-g group]

[-l level] [-t date] [-m masquerade] [-W width]

[path...]

• Use the -b pool option to specify a particular destination pool for the save sets.

• Use the -B option to force a save of all connecting directory information, from the root (/)to the point of invocation.

• Use the -c client-name option to specify the client name that starts the save session. This is useful for clients with multiple network interfaces and, hence, multiple hostnames. You can use the option to create multiple client file indexes for the same physical client machine. This option does not specify the network interface to use; the network interface is specified in the Network Interface attribute of the nsr_client resource.

• Use the -e expiration option to set the date when the save set expires. When a save set has an explicit expiration date, the save set remains both browsable and nonrecyclable until it expires. After the expiration date, the save set is nonbrowsable. If it has expired and also passed its retention time, the save set becomes recyclable. By default, explicit save set expiration dates are not used.

• Use the -E option to estimate the amount of data that is generated by each save set before the save operation is actually performed. This option results in a double traversal of the filesystems: once to generate an estimate and again to perform the save operation. The data itself is only read from the disk on the final pass, because the estimate is performed by accessing the inode information.

• Use the -f dirfile option to specify the file from which the save program should read the prototype default directives. A dirfile value of - causes the default directives to be read from standard input.

• Use the -F file option to save only files whose change time is newer than the file modification date of the specified file.

• Use the -g group option to denote the group to save. Use this option to determine the specific pool to which save sets from the specified group should be written.

• Use the -i option to instruct the save command to ignore any.nsr directive files encountered in the subdirectory structures saved.

• Use the -I input-file option to read the paths to save from the named text file, in addition to the paths listed on the command line. The paths must be listed one per line. If no paths are listed on the command line, only the files contained in the paths listed in input-file are saved.

• Use the -l level option to specify the level of the save.

• Use the -L option to perform a save from the local Backup client, even when files are from a network fileserver. To recover files, you must run the recover program with the same -c client argument used to save the data.

• Use the -LL option to treat the backup as a local save and print an extra line at the end of the completion report in the form complete savetime=number where number is the savetime of the save set created by this backup. This option is meant for use by the savegrp command for automatic cloning.

• Use the -m masquerade option to specify the tag to precede the summary line in the savegroup completion report.

• Use the -n option to estimate the amount of data that will be saved, without performing a save operation.

• Use the -N option to specify the symbolic name of the save set. By default, the most common prefix of the path argument is used as the save set name.

• Use the -q option to run the save program in quiet mode. This option generates only summary information and error messages.

• Use the -t date option, in nsr_getdate(3) format,to specify the date after which files must have been modified to qualify for a save.

• Use the -v option to run the save program in verbose mode.

• Use the -W width option to format summary information output.

• Use the -x option to cross mount points during the save operation.

savefs

The savefs program is used by the savegrp program to probe a client for its filesystems and recent save times. Running savefs directly to perform a save is not recommended. However, you can safely invoke savefs manually with the -p option to probe the client and produce a preview report of the save sets (and levels) that a savegrp will back up. When probing, savefs does not actually save data, but instead produces a machine-parsable report that describes the layout of the client's filesystems. The -p option provides command line access to the same information you obtain with the Group Control>Preview feature available in the GUI version of the Administration program.

If a filesystem argument is not provided with the savefs command line, the filesystems listed in the Save Set attribute are probed. If the save set list consists of the keyword "All," then the filesystem tables (/etc/vfstab on Solaris)are examined to determine which filesystems to save. Only local, mounted filesystems are considered by the probe.

Metadevices within the Sun Solaris: Online DiskSuite are treated similar to independent disks. This approach allows each to be saved in its own session, assuming sufficient parallelism.

Care should be taken when the Clients resource explicitly lists the save sets, for two primary reasons. First, this list must be manually updated when new filesystems that need saving are added. Second, since savefs only stops at the end of a path or a mount point, if you list two save sets in the same filesystem and one is a subdirectory of the other, the subdirectory is saved twice.

You can specify filesystem arguments to limit the filesystem saves to only those specified, but the specified filesystems must appear on a Save Set list for this client (see the -F option).

The following example describes the format and options available for the savefs program:

savefs -p [options] [filesystem...]

[-M filesystem...]

The following lists the valid values for options:

[-BEFnpqRv] [-s server] [-N name] [-g group]

[-l level | -C schedule] [-e expiration]

[-f filename] [-W width] [-t date] [-T seconds] 

• Use the -B option to force a save of all connecting directory information from root (/)down to the point of invocation. This option is used by savegrp, for example, when saving the server's bootstrap information.

• Use the -C schedule option to specify the name of the schedule to use when automatically determining the save level. If this option is not specified, savefs uses the schedule named by the Clients resource for the specified filesystem.

• Use the -e expiration option to specify the expiration date for the saved data (in nsr_getdate format). By default, no explicit expiration date is used.

• Use the -E option to walk the filesystems specified and estimate the amount of data that the save will generate. Without this flag, the estimated size is zero. Note that this flag consumes an amount of time proportional to the number of files in each filesystem. This is because the entire directory is walked before any saving begins and walked again when actually saving the directory. The file data is only read from the disk the last time. In many cases, the overhead for using this flag is small and is well justified.

• Use the -f filename flag to specify the file from which application-specific modules (ASMs) should take their directives. By default, these are taken from the Directives resource named by the Directive attribute in the Clients resource for each client.

• Use the -F option to save every argument like a filesystem, even if the arguments are not listed in the filesystem tables or the Clients resource.

• Use the -M option, as part of a probe, to signify that all subsequent filesystems should be probed for their ability to be migrated. This option is quietly ignored on systems that do not support file migration.

• Use the -g group option to restrict the scope of the client to a particular group. If this option is not specified, save sets from all instances of the Clients resource for this client are used, regardless of the group. This value is also passed on to save, which uses it to select a specific media pool.

• Use the -l level option to specify the level of save to perform. There are 12 levels: full, levels 1 though 9, incr, and skip. Full specifies that all files are to be saved. Incr specifies incremental saves in which only those files modified since the most recent save, at any level, are saved. Skip causes no files to be saved. Levels 1 through 9 save all files modified since any lower level save was performed. For example, if you did a Full on Monday, followed by a level 3 save on Tuesday, a subsequent level 3 save on Wednesday contains all files modified or added since the Monday Full save. If you do not specify a level, the save level is determined automatically from the Backup client's schedule. Using the history of previous saves maintained by nsrmmd on the Backup server, savefs accurately computes the time for the given level. When tapes are deleted, savefs uses media information on the server to automatically adjust the time computed for saves based on previous save levels.

• Use the -n option to have savefs accurately estimate the amount of data generated, as described for -E, but not actually save any data.

• Use the -N name option to assign the symbolic name for the save sets. By default, the first filesystem argument is used as the name.

• Use the -p option to list the name of the filesystems, the level of save that would be performed, and the file modification time of files to be saved, but not actually perform the save. This information is gleaned from an operating system-specific file and the Schedules resource.

• Use the -q option to run savefs in quite mode. Only summary information and error messages are displayed.

• Use the -qq option to run savefs in really quiet mode, and display only error messages.

• Use the -R option to cause savefs to echo a simple succeeded or failed message as it is completed. This option is automatically used by the savegrp program when it runs savefs.

• Use the -s server option to specify the Backup server for savefs to use.

• Use the -t date option to specify the date (in nsr_getdate format)for savefs to use as a base for calculating the level. If this option is not specified, the current time is used.

• Use the -T seconds option to specify the inactivity timeout, in seconds, for savefs. If savefs detects that the local server has not made progress in the specified time, it concludes that the save program is not responding. A message is printed to stderr and savefs exits normally. This option should only be used on Backup server machines.

• Use the -v option to run savefs in verbose mode. This option results in a lot of debug-style output. This option is automatically used by the savegrp program when it probes for the ability of the client's savefs to support multiple versions.

• Use the -W width option to specify the width used for formatting output or notification messages. The default value for width is 80.

savepnpc

The savepnpc program, like the save program, saves files to long-term storage. Before performing a save operation, savepnpc performs any pre-processing commands that exist in the /nsr/res/group_name.res file. If the pre-processing command fails, savepnpc exits with an error code and save is not performed. At the end of a successful save of the last save set on the client, savepnpc performs any post-processing commands that exist in the /nsr/res/group_name.res file. An optional timeout condition may be set to indicate at which point in the post-processing commands must be run without waiting for the last save set to back up. The Timeout attribute is set in the same /nsr/res/group_name.res file as the pre- and post-processing commands. All of the results from the savepnpc program are logged in the /nsr/res/savepnpc.log file.

The /nsr/res/group_name.res file is automatically created the first time you run a backup group with a client that has the savepnpc command entered in the Backup Command attribute of the Clients resource. The format looks similar to the following:

type: savepnpc;
precmd: /bin/true;
pstcmd: /bin/true, "/bin/sleep 5";
timeout: "12:00pm"; 

You can edit the Precmd field to contain any number of commands, separated by commas, to run prior to the start of the save operation on the client's first save set. You can also edit the Postcmd field to contain any number of commands, separated by commas, to run at the end of the save operation on the client's last save set or the timeout condition indicated in the Timeout field, whichever comes first. All fields in the file must terminate with a semicolon (;).

The command syntax for savepnpc is identical to the syntax described for "save ". If you create a customized script to enter in the client's Backup Command attribute, the following rules apply:

• The savepnpc command must be part of the script.

• The filename of the script must begin with save or nsr, and cannot exceed 64 characters in length.

• The script must reside in the same directory as the save program (typically, /usr/bin).

recover

The recover program searches (browses) the client file index for a specified client and recovers files from backup volumes to the specified client. The client file index entries are created when the files are backed up with the save command. When you use the interactive version of the recover program, nwrecover, the client file index is presented in a graphical display format that is similar to a UNIX filesystem.

In the automatic mode (-a option) or save set recover mode (-S option), the files specified on the command line are recovered immediately without browsing the client file index. Use of the save set recover mode (-S option) is restricted to users in the operator group. If you run the recover program without the -S option, and users in the operator group can recover any file.

You can specify one or more path arguments to limit the directories and files to just those you want to recover. If you specify the path argument, the beginning of each path name as it exists in the save set must exactly match one of the paths before it can be recovered. Filename matching using meta characters (for example, *, ?, or [...]) is not allowed. You can use a path that ends with a slash character to force a match to a specific directory.

The following example describes the format and options available for the recover program:

recover [-f] [-n] [-q] [-i {nNyYrR}]

[-d destination] [-c client] [-t date]

[-s server] [dir]
recover [-f] [-n] [-q] [-i {nNyYrR}]

[-d destination] [-c client] [-t date]

[-s server] -a path
recover [-f] [-n] [-q] [-i {nNyYrR}]

[-d destination] [-t date] -s server

-S ssid[/cloneid] [-S ssid[/cloneid]] [path]

• Use the -a option to cause the recover program to automatically recover files without browsing the client file index.

• Use the -c client to specify the name of the machine from which the save sets were originally saved. When you browse a directory that was saved by a different client, the pathnames displayed reflect the filesystem of the client that saved the files. By default, the save and recover programs determine the client machine name from the filesystem table. If you specified the -L option with the save program, the -c client option may not be necessary (see "save " for information about the options available for the save program). You cannot use the -c client option in conjunction with the -S ssid[/cloneid] option.

• Use the -d destination option to specify the destination directory where you relocate the recovered file. Relative paths are interpreted in relation to the current working directory.

• Use the -f option to force recovered files to overwrite any existing files whenever a filename conflict occurs. This option is the equivalent of specifying the combined -iY option.

• Use the -i option with one of the following choices to specify the initial default overwrite response to use when a file name conflict occurs: nNyYrR. You can only specify one letter choice in conjunction with the -i option. The -i option produces the same results as the uasm -i option when you run uasm in recover mode.

• Use the -n option to use the recover program without creating any directories or files.

• Use the -q option to turn off the default verbose mode for the recover program.

• Use the -s server option to specify the Backup server from which you want to recover data. This option is required when you use the save set recover mode (-S). If you omit the -s server option, the default is the server of the first directory marked for recovery, if the server is a network file server as well as a Backup server. If the server is not a network file server or a Backup server, the current server or a machine with a logical name of nsrhost entered in the host table is considered.

• Use the -S ssid[/cloneid] option to use the recover program in save set recover mode. Use this mode to implement batch file recovery without the need for client file indexes. The value of ssid specifies the save set IDs for the save sets you want to recover. When multiple clone instances exist for a save set, you can specify a clone ID to select the particular clone instance you want to recover. If you do not specify the path argument, the entire contents of the save set are recovered.

• Use the -t date option to display or recover files as of the specified date. You cannot use this option in conjunction with the -S ssid option.

  Refer to the recover(1m) man page for more information on how to use the recover program in interactive mode, as well as to view a listing of the more common error messages encountered.

nsrmig

The nsrmig program migrates files to the volumes labeled for a Migration pool type. The migrated files are replaced with a stub (a symbolic link) that points to a copy of the file made during premigration with the nsrpmig program. If you access the stub later, the file is automatically recalled to disk from the migration volume by the Backup server or storage node.

The criteria for migration is defined in the Migration resource on the Backup server. Migration is usually an automatic process controlled by the Backup server. The criteria most often employed is last access time. Only regular files are premigrated and, ultimately, migrated.

If you do not specify a path argument, the current directory is migrated. The nsrmig program does not cross mount points, and it does not follow symbolic links.

The following example describes the format and options available for the nsrmig program:

nsrmig [-nvx] [-l percent] -s server] [-t savetime] [-W width] [path]

• Use the -l percent option to specify a goal percentage for the nsrmig program to use. Migration stops when the goal percentage is reached. If the goal percentage is already reached before you invoke nsrmig, the program exits without performing any further migration. If you do not specify the -l option, the goal percentage is read from the appropriate migration client resource.

• Use the -n option to estimate the number of files and total size that are freed by replacing the files that qualify for migration with a stub, but do not replace the files with stubs.

• Use the -s server option to specify the machine to use as the Backup server. If you omit this option, the default machine considered is either the current machine (if it is a Backup server) or a machine with the logical name of nsrhost entered in the host table.

• Use the -t savetime option to migrate files that were premigrated at the specified savetime.

• Use the -v option to cause the save program invoked by nsrpmig to provide detailed information as it proceeds.

• Use the -W width option to specify the width that nsrmig should use to format summary information to standard output. The default width used is 80.

• Use the -x option to instruct nsrmig to cross mount points.

  Refer to the nsrmig(1m) man page for further details and common error messages encountered.

nsrpmig

The nsrpmig program premigrates files that are identified as candidates for migration, as defined in the Backup server's Migration resource. The premigration process invokes the save program to immediately make a copy of the specified file to a backup volume labeled for migration data. When the file is later migrated, the resident file is replaced with a marker that refers to the premigrated copy on volume. You can only premigrate regular files.

The nsrpmig program does not cross mount points or follow symbolic links. If you mount the path to be saved from a network file server, the nsrpmig program issues a message that instructs the user to run the save program on the remote machine or use the -L option with nsrpmig.

The nsrpmig program examines the directive files (.nsrhsm) encountered in each directory to determine any special instructions to apply when saving files (for example, compression and skip directives). The directive files ordinarily used by Backup for save and recover operations (.nsr) are ignored by the nsrpmig program.

The nsrpmig program is only available for use when an enabler code for the Backup HSM is present on the Backup server.

The following example describes the format and options available for the nsrpmig program:

nsrpmig [-BEiLnpqvx] [-s server] [-N name]

[- f dirfile] [-b pool] [-g group]

[-m masquerade] [-W width] [-C clone-pool]

[-I input-file] path

• Use the -b pool option to specify the volume pool to which the premigrated data should be saved. Migrated data must reside on separate volumes from either backed-up data or archived data. If you do not specify a pool, the Migration pool is selected by default.

• Use the -B option to force a save of all connecting directory information, from the root (/) to the point of invocation.

• Use the -C clone-pool option to generate a clone of the premigrated save set to the specified clone pool. Clones of migrated data must reside on separate volumes from either backed-up or archived clone data. If you do not specify a clone pool, the Migration Clone pool is selected by default.

• Use the -E option to instruct nsrpmig to estimate the amount of data that the save program generates, then perform the save operation. The estimate is generated from the inode information, so the data is only read once.

• Use the -f dirfile option to specify a file that nsrpmig should read prototype default directives from [refer to the nsr(5) man page for more information on the default directives]. A value of - for dirfile causes the default directives to be read from standard input.

• Use -g group option to denote the group name to which the save set should belong. The Backup server uses this option to select a specific media pool.

• Use the -i option to instruct nsrpmig to ignore any .nsrhsm directive files encountered during the premigration process.

• Use the -I input-file option to instruct nsrpmig to read the paths to save from the file specified as input-file in addition to those listed on the nsrpmig command line. List each path on a separate line in the file specified by input-file. If you do not also specify paths on the command line, only the paths specified in input-file are saved.

• Use the -L option to instruct nsrpmig to perform a local save from the Backup client, even if the files originate from a network fileserver. To recover files that have been locally premigrated, run the recover program with the -c client option, where the value for client is the machine name of the Backup client that performed the save operation.

• Use the -LL option to instruct nsrpmig to perform a local save and print an extra line at the end of the completion in the format complete savetime=number where number is the save time of the save set created. The savegrp program uses this option when you specify automatic cloning.

• Use the -m masquerade option to specify a tag to precede the savegroup summary notification line. The savegrp and savefs programs use this option to aid in savegroup summary notifications.

• Use the -n option to estimate the amount of data that is generated by the save without performing the save. This option is similar to the -E option, except that data is not saved to a volume after the estimate is completed.

• Use the -N name option to instruct nsrpmig to use the symbolic name of the save set. By default, the path argument is used as the save set name.

• Use the -p option to cause the save program invoked by nsrpmig to exit with a status value of 0. The server uses this option to determine whether a client is installed properly.

• Use the -q option to cause the save program invoked by nsrpmig to display only summary information and error messages.

• Use the -s server option to specify the machine to use as the Backup server. If you omit this option, the default machine considered is either the current machine (if it is a Backup server) or a machine with the logical name of nsrhost entered in the host table.

• Use the -v option to cause the save program invoked by nsrpmig to provide detailed information as it proceeds.

• Use the -W width option to specify the width that nsrpmig should use to format summary information to standard output. The default width used is 80.

• Use the -x option to instruct nsrpmig to cross mount points.

  See "save " and "savegrp " for more information on the save and savegrp program options described in this section. Refer to the nsrpmig(1m) man page for further details and common error messages encountered.

nsrhsmck

The nsrhsmck program checks and corrects the consistency between the file stubs and the client file index entries for files migrated by HSM. The nsrhsmck program handles four situations:

• The first situation occurs when you rename the stub for a migrated file. In this situation, the stub with the original filename no longer exists. The nsrhsmck program corrects this situation by updating the client file index entry to reflect the new name given to the stub.

• The second situation occurs when you create a symbolic link that points to the same name in the Backup Instruction Buffer (IB) namespace as another symbolic link. The nsrhsmck program corrects this situation by replacing the duplicate with a symbolic link that points to the original symbolic link, rather than pointing directly to the Backup IB namespace.

• The third situation occurs when you delete the stub that points to a migrated file. This is known as the possible delete case. The term "possible" implies that the stub may reappear later, for example, if the stub is recovered using Backup. The nsrhsmck program corrects this situation by marking the index entry for the migrated file as a possible deletion after 60 days. Note that if a file marked as possibly deleted is detected on disk before the index entry is later deleted, the index entry is unmarked as a possible deletion.

• The fourth situation handled by nsrhsmck occurs when an index entry that is marked as a possible deletion that has passed the 60 day expiration time. The nsrhsmck program corrects this situation by removing the expired entries from the HSM file index. Before it deletes an entry from the HSM file index, nsrhsmck makes a final check to make sure the file does not exist on disk.

  You must specify a path on the command-line when you run nsrhsmck. Only files and index entries that fall under the path specified are examined for consistency.

  The following example describes the options available for the nsrhsmck program:

• Use the -c option to instruct the nsrhsmck program to walk the HSM file index and delete entries marked as possibly deleted that have passed the 60-day expiration period.

• Use the -d option to instruct the nsrhsmck program to walk the HSM file index and mark any possible deletions that are detected.

• Use the -f option to instruct the nsrhsmck program to walk the filesystem on disk and search for duplicated links and renamed stubs.

• Use the -M option to tell the nsrhsmck program that it is being run in master mode by nsrexecd or another Backup daemon, and, therefore, to log messages with timestamps as well as perform other behavior expected by nsrexecd. This option is not advised for manual operation; it is used by the Backup server when nsrhsmck is automatically invoked.

• Use the -n option to instruct the nsrhsmck program to report on any inconsistencies found, without correcting them.

• Use the -s server option to specify the machine to use as the Backup server. If you omit this option, the default machine considered is either the current machine (if it is a Backup server) or a machine with the logical name of nsrhost entered in the host table.

• Use the -v option to run nsrhsmck in verbose mode. You can specify this flag up to three times on the command-line to achieve the highest level of verbosity. Note that the verbose mode can produce an extremely large quantity of output and is not recommended for use in most situations.

nsrarchive

The nsrarchive program archives files, including directories or entire filesystems, to the Backup server. You can use the nwadmin or nsrwatch programs to monitor the progress of an archive operation. Only users on the Administrator and Archive Users lists have the required privileges to run the nsrarchive program. Additionally, you can allow or disallow public archives through an option in the NSR (or Server) resource, which enables other clients to recover data archived from a particular client machine.

If you do not specify a path argument, the current directory is archived. The nsrarchive program archives all the files and subdirectories contained in a directory, but does not cross mount points or follow symbolic links. If the paths to be archived are mounted from a network fileserver, the nsrarchive program returns a message that instructs you to run the nsrarchive program on the remote machine or use the -L option.

The .nsr directive files encountered in each directory are read by default. The directive files contain instructions on how specific files should be archived (for example, compression).

Each file in the subdirectory structures specified by the path option is encapsulated in a Backup save stream. This stream of data is sent to a receiving process on the Backup server, which processes the data and adds entries to the client file index for each file in the stream. The data is then directed to long-term storage, either on the server or the designated storage node.

The following example describes the format and options available for the nsrarchive program:

nsrarchive [-BiLnpqvxVy] [-b pool] [-C clone-pool]

[-f filename] [-G remove] [-N name] [-R name]

[-s server] [-T annotation] [-W width] [path...]

• Use the -b pool option to specify a destination pool for the archive save sets. This option overrides the automatic pool selection typically used by the server. Archive data must be directed to volumes specifically labeled for a pool type of Archive. If you do not specify a pool, the Archive pool is selected by default.

• Use the -B option to force an archive of all the connecting directory information, from root (/) to the point of invocation.

• Use the -C clone-pool option to automatically generate a clone of the archived save sets to the specified clone pool. Cloned archive data must be directed to volumes specifically labeled for a pool type of Archive Clone. If you do not specify a clone pool, the Archive Clone pool is selected by default.

• Use the -E option to estimate the amount of data that the archive generates, followed by the archive. Note that the estimate is generated from the inode information; therefore, the data is only read once.

• Use the -f filename option to specify a file from which nsrarchive should read the default directives to apply to the archive data (refer to the nsr(5) man page for further information on directives). A value of - for filename causes the default directives to be read from standard input.

• Use the -G remove option to groom (remove) files after they are successfully archived. If you specify cloning or verification options as well, the groom operation is not performed until those operations are completed successfully. Unless you also specify the -y option, you are prompted for removal of top-level directories. The nsrarchive program creates a temporary file that contains a list of all the files and directories to be groomed. The temporary file is placed in the directory specified by the TMPDIR environment variable, or in the /tmp directory if the environment variable is not defined.

• Use the -i option to instruct the nsrarchive program to ignore any directive files encountered in the subdirectories that are archived.

• Use the -L option to perform a local archive from the Backup client, even when the files are from a network file server.

• Use the -n option to estimate the amount of data that is generated by the archive without performing the actual archive. This option is similar to the -E option, except that data is not saved to a volume after the estimate is completed.

• Use the -N name option to instruct nsrarchive to use the symbolic name of the archive save set. By default, the first path argument is used as the value for name.

• Use the -p option to instruct nsrarchive to exit with a status of 0. This Backup server uses this option to determine whether the client is properly installed.

• Use the -q option to cause nsrarchive to run in quiet mode and display only summary information and error messages.

• The -R name option should only be used by the nsralist program, which handles the execution of the archive requests. Updates to the named archive request resource occur when the Backup server specifies this option.

• Use the -s server option to specify the machine to use as the Backup server. If you omit this option, the default machine considered is either the current machine (if it is a Backup server) or a machine with the logical name of nsrhost entered in the host table.

• Use the -T annotation option to assign an arbitrary text string of 1024 characters or fewer to the archive save set. The string specified as annotation is used by the nsrretrieve program to browse the media database for archive save set entries to retrieve back to local disk. The annotation is a mandatory requirement for all archive save sets; if you omit this option, you are prompted for it before the process continues.

• Use the -v option to cause nsrarchive to run in verbose mode.

• Use the -V option to verify each archive save set.

• Use the -W width option to specify the width that nsrarchive should use to format summary information to standard output. The default width used is 80.

• Use the -x option to instruct nsrarchive to cross mount points.

• Use the -y option to automatically enter an affirmative response to any queries generated by the nsrarchive program.

nsrretrieve

The nsrretrieve program is used to restore archived save sets from the archive volumes managed by the Backup server or storage node. You do not browse client file index entries for archived save sets as you do for regular save sets; you search for a specific annotation string to identify the archive save set you want to retrieve.

The use of nsrretrieve is restricted to users on the Backup server's Administrators and Archive Users list. If the nsrretrieve program is not run by root or a user defined in the operator group, or the Public Archives attribute of the Server resource is not enabled, only the owner of the archived files can retrieve them.

The following example describes the format and options available for the nsrretrieve program:

nsrretrieve [-f] [-n] [-q] [-i {nNyYrR}] [-d destination] -s server [-
S ssid[/cloneid]]... [-A annotation]...

[path]...

• Use the -A annotation option to specify the archive save set to retrieve. An annotation is a regular expression that uniquely identifies a single archive save set. The regular expression is of the form used by the grep(1) command.

• Use the -d destination option to specify the destination directory where you want to relocate the retrieved files.

• Use the -f option to force retrieved files to overwrite any existing files whenever a filename conflict occurs. This option is the equivalent of specifying the combined -iY option.

• Use the -i option with one of the following choices to specify the initial default overwrite response to use when a filename conflict occurs: nNyYrR. You can only specify one letter choice in conjunction with the -i option. The -i option produces the same results as the uasm -i option when you run uasm in recover mode. Refer to the usam(1m) man page for a detailed explanation of how to use the uasm -i option.

• Use the -n option to use the nsrretrieve program without actually creating any directories or files.

• Use the -q option to cause nsrretrieve to run in quiet mode and display only summary information and error messages.

• Use the -s server option to specify the machine to use as the Backup server. If you omit this option, the default machine considered is either the current machine (if it is a Backup server) or a machine with the logical name of nsrhost entered in the host table.

• Use the -S ssid[/cloneid] option to specify the ssid for the save set to retrieve. If multiple clone instances exist for an archive save set, you can also specify the clone ID, to select the clone instance that you want to retrieve the data from. If you do not specify a path argument, the entire contents of the archive save set are retrieved. To restrict the retrieval to particular directories or files that match a given path prefix, specify the exact pathname.

nsrclone

The nsrclone program makes new copies of existing save sets. The operation is automatic when you enable the Clones attribute of a NSR group resource. You can also run nsrclone on a manual basis from the command line.

Although the command line options enable you to specify a volume name or identifier, nsrclone always copies complete save sets, regardless of how many volumes the save set components reside on. The nsrclone program does not copy volumes; instead, it copies the original save sets specified from one volume to a volume assigned to a special pool for clones. If the first destination volume cannot hold all the save sets to be cloned, another volume from the same clone pool is chosen.

If you use the -c and -N options together, nsrclone creates a super-full copy for the given client save set. The super-full copy is a feature that is supported only under HSM. It automatically creates a clone of the most recent complete full backup of the named client and save set, along with any HSM migration save sets referred to by the full backup. Super-full copies should be cloned to a volume from a migration clone pool. If no migration save sets are referenced by the most recent full backup, only the full set is cloned.

The nsrclone program, in cooperation with the nsrmmd daemon, guarantees that each save set has only one clone on a given volume. When you specify a volume name or identifier, the copy of the save sets on that volume are used as the source. When you specify save sets explicitly, those with existing multiple copies are automatically chosen; copies of save sets that exist on volumes in an autochanger or silo are chosen over those that require operator intervention. You can also specify which copy of a save set to use as the source, with the -S option.

The following example describes the format and options available for the nsrclone program:

nsrclone [-v] [-s server] [-b pool]

{-f file | volume-name}
nsrclone [-v] [-s server] [-b pool] -S

{-f file | ssid}
nsrclone [-v] [-s server] [-b pool] -V

{-f file | volumeid}
nsrclone [-v] [-s server] [-b pool]

-c client -N saveset

• Use the -b pool option to specify the name of the clone pool to which the data should be migrated. If you omit this option, the cloned save sets are automatically sent to the Default Clone pool.

• Use the -c client option, in conjunction with the -N option, to specify a client whose save sets should be considered for a super-full copy.

• Use the -f file option to instruct nsrclone to read the volume names, volume identifiers, or ssids from the text file specified.

• Use the -s server option to specify a Backup server to migrate save sets from. If you omit this option, the current machine is selected by default.

• Use the -S option to specify one or more specific ssids. You can issue the mminfo -v command to determine the value to use for ssid (see "mminfo " for details).

• Use the -v option to run nsrclone in verbose mode. This mode provides additional information during the process, for example, messages about save sets that cross volumes.

• Use the -V volid option to specify the name of the volume.

  Refer to the nsrclone(1m) man page for examples and error messages for the nsrclone program.

nsrstage

The nsrstage program is used on a manual basis to migrate existing save sets from one volume to another. The process begins with a clone of the specific save sets to the new volume specified, followed by deletion of the save set entries from the media database, and finally a removal of the save sets from the original source volume, if possible. The media database entries and save sets are not removed if the clone to the new volume does not succeed.

You can migrate save sets onto volumes that belong to any of the media types supported by Backup (for example, save sets on a file volume may be migrated to an optical disk). However, all volumes used as the destination of a nsrstage operation must belong to a Clone pool type. Refer to the nsr_pool(1m) man page for a description of the various pool types.

The nsrstage program does not perform simple volume migration; it migrates complete save sets. You can specify the copy (clone) of a save set to use as the migration source with the -S ssid option.

The following example describes the format and options available for the nsrstage program:

nsrstage [-v] [-s server] [-b pool] -m

[-S {ssid/cloneid}]
nsrstage [-v] [-s server] -C -V volume

• Use the -b pool option to specify the name of the clone pool to which the data should be migrated. If you omit this option, the cloned save sets are automatically sent to the Default Clone pool.

• Use the -C option to instruct nsrstage to perform a volume cleaning operation after the save sets have been migrated and their associated entries removed from the media database. You can only use this option with entries that are migrated from a file volume.

• Use the -m option to perform the actual migration.

• Use the -s server option to specify a Backup server to migrate save sets from. If you omit this option, the current machine is selected by default.

• Use the -S ssid (or ssid/cloneid) option to specify one or more specific ssids and clone IDs that you want to migrate. The ssid option is useful when you want to migrate individual save sets from a volume. The cloneid option is useful when you want to specify a particular copy of a save set for migration. The value of either identifier is an unsigned integer; when you specify both you must separate them with a slash (/)character. You can issue the mminfo -v command to determine the value to use for ssid or cloneid (see "mminfo " for details).

• Use the -v option to run nsrstage in verbose mode. This mode provides additional information during the process, for example, messages about save sets that cross volumes.

• Use the -V volume option to specify the name of the volume that nsrstage should clean. You cannot use this option in conjunction with the -S or -m options.

  Refer to the nsrstage(1m) man page for examples and error messages for the nsrstage program.

scanner

The scanner program directly reads Backup media (such as backup tapes, optical disks, or files) to confirm the contents of a volume, to extract a save set from a volume, or to rebuild the Backup online indexes. You can only run this command as root. You must specify a device, which is usually one of the device names used by the Backup server. If the device is a tape drive, it must be a nonrewinding type.

If you invoke the scanner program without options (or only the -v option), the volume on the specified device is 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 on the volume. The information provides the client name, save set name, save time, level, size, files, ssid, and flag.

The following example describes the format and options available for the scanner program:

scanner [-Bimnpqv] [-s server] [-S ssid]

[-c client] [-N name] [-f file] [-r record]

[-t type] [-b pool] device [-x command argument-list] 

• Use the -b pool option to specify the pool to which the volume should belong. This option only applies to volumes backed up by versions of Backup that did not store pool information on the media.

• Use the -B option, without the -S option, to quickly scan the tape to the location of the start of the bootstrap save sets. When the entire tape has been scanned, the ssid and tape file location of the most recent bootstrap save set is printed to standard output.

• Use the -c client option to instruct scanner to only process save sets that came from the machine specified by client. You can specify more than one client name in the same command line. You can also use the -c option in conjunction with the -N option, but only if you also specify the -i or -x option.

• Use the -f file option to start the scan at a specific media file number. See "mminfo " for information on how to determine the media file number.

• Use the -i option to instruct scanner to rebuild both the client file indexes and media database from the volumes that are read. If you specify a single save set with the -S ssid option, only the entries from the specified save set are made to the client file index.

• Use the -m option to instruct scanner to rebuild only the media database for the volumes that are read.

• Use the -n option to run scanner without rebuilding the client file indexes or media database. This option provides a way to check the media without modifying the client file indexes or media database.

• Use the -N name option to process only save sets that match the specified name. The value of name should be a literal string. You can specify multiple names when you use this option in conjunction with the -c client option, but only if you also specify the -i or -x option.

• Use the -p option to print out information about each save set as it is processed.

• Use the -q option to display only error messages or messages of significance.

• Use the -r record option to start the scan at a specific media record number, to avoid a scan of potentially unused information. See "mminfo " for information on how to determine the media record number.

• Use the -s server option when you run the scanner program on a storage node, to specify the controlling Backup server.

• Use the -S ssid option to extract the save set specified by ssid. When you use this option in conjunction with the -i or -x options, you can specify multiple ssid values. The save sets selected are in addition to any selected by the use of the -c and -N options. If you also specify the -B option, the value of ssid is assumed to be that of the bootstrap save set; only one ssid can be specified in this case.

• Use the -x command option, with an optional list of command arguments, to specify a UNIX command to execute on each save set scanned. This option can only be specified once per scanner command line, after the device specification.

  Refer to the scanner(1m) man page for examples of scanner command usage and a list of common error messages.