=head1 NAME

backup savedb - Creates a saved copy of the Backup Database

=head1 SYNOPSIS

backup savedb [B<-portoffset> I<TC port offset>]  [B<-archive> I<date time> ...]
[B<-localauth>]  [B<-cell> I<cell name>]  [B<-help>]

backup sa  [B<-p> I<TC port offset>]  [B<-a> I<date time> ...]
[B<-l>]  [B<-c> I<cell name>]  [B<-h>]

=head1 DESCRIPTION

The C<backup savedb> command creates a backup copy of the entire Backup
Database and writes it to the tape in the device controlled by the
Tape Coordinator indicated with the B<-portoffset> argument. If the
database is damaged (as reported by the C<backup dbverify> command), this
command repairs as much of the corruption as possible as it creates
the saved copy. The Backup Server creates a dump record for the saved
database in the Backup Database (but in the disk version of the
database only, not in the version written to tape).

If the B<FILE YES> instruction appears in the
B</usr/afs/backup/CFG_>I<device_name> file associated with the specified
port offset, then the C<backup savedb> command dumps the database copy to
the backup data file listed for that port offset in the Tape
Coordinator's B</usr/afs/backup/tapeconfig> file, instead of to tape. For
the sake of clarity, the following text refers to tapes only, but the
Backup System handles backup data files in much the same way.

If the B<-archive> flag is provided, after writing the saved copy of the
database the Backup System truncates the copy of the database on disk
by deleting volume dump records with timestamps prior to the specified
date and time (it does not delete the dump records created by previous
C<backup savedb> commands, however).

If the tape to which the database copy is written has an AFS tape
name, it must be B<Ubik_db_dump.1> or C<E<lt>NULLE<gt>>. Any permanent name is
acceptable.

The Tape Coordinator's default response to this command is to access
the first tape by invoking the B<MOUNT> instruction in the local
B</usr/afs/backup/CFG_device_name> file, or by prompting the backup
operator to insert the tape if there is no B<MOUNT> instruction. However,
if the B<AUTOQUERY NO> instruction appears in the B<CFG_>I<device_name> file,
or if the issuer of the B<butc> command included the B<-noautoquery> flag,
the Tape Coordinator instead expects the tape to be in the device
already. If it is not, the Tape Coordinator invokes the B<MOUNT>
instruction or prompts the operator. It also invokes the B<MOUNT>
instruction or prompts for any additional tapes needed to complete the
operation; the backup operator must arrange to provide them.

=head1 OPTIONS

=over 4

=item B<-portoffset> I<TC port offset>

Specifies the port offset number of the Tape Coordinator
handling the tapes for this operation.

=item B<-archive> I<date time> ...

Specifies a date and time; volume dump records with earlier
timestamps are deleted from the disk copy of the Backup
Database after the Backup System dumps the database (a dump's
timestamp appears in the created field of the output from the
C<backup dumpinfo> command). However, if a dump set contains any
dump created after the specified date, none of the dump records
associated with the dump set are deleted. Dump records for
previous dumps of the database (created with the C<backup savedb>
command) are never deleted; use the C<backup deletedump> command
to remove them.

Provide one of two values:

=over

=item *

The string C<NOW> to indicate the current date and time, in
which case the Backup System deletes all dump records except
those for dumps of the Backup Database itself.

=item *

A date value in the format I<mm>/I<dd>/I<yyyy> [I<hh>:I<MM>]. The month
(I<mm>), day (I<dd>), and year (I<yyyy>) are required, and valid
values for the year range from B<1970> to B<2037>; higher values
are not valid because the latest possible date in the
standard UNIX representation is in February 2038. The Backup
System automatically reduces any later date to the maximum
value.

The hour and minutes (I<hh>:I<MM>) are optional, but if provided
must be in 24-hour format (for example, the value B<14:36>
represents 2:36 p.m.). If omitted, the time defaults to 59
seconds after midnight (00:00:59 hours). Similarly, the
C<backup> command interpreter automatically adds 59 seconds to
any time value provided. In both cases, adding 59 seconds
compensates for how the Backup Database and C<backup dumpinfo>
command represent dump creation times in hours and minutes
only. That is, the Database records a creation timestamp of
C<20:55> for any dump created between 20:55:00 and 20:55:59.
Automatically adding 59 seconds to a time thus includes the
records for all dumps created during that minute.

=back

=over

=item B<Note:>

A ... follows this argument in the command's syntax
statement because it accepts a multiword value which does not need to
be enclosed in double quotes or other delimiters, not because it
accepts multiple dates. Provide only one date (and optionally, time)
definition.

=back

=item B<-localauth>

Constructs a server ticket using a key from the local
B</usr/afs/etc/KeyFile> file. The C<backup> command interpreter
presents it to the Backup Server, Volume Server and VL Server
during mutual authentication. Do not combine this flag with the
B<-cell> argument. For more details, see the introductory L<backup(1)>
reference page.

=item B<-cell> I<cell name>

Names the cell in which to run the command. Do not combine this
argument with the B<-localauth> flag. For more details, see the
introductory L<backup(1)> reference page.

=item B<-help>

Prints the online help for this command. All other valid
options are ignored.

=back

=head1 EXAMPLES

The following example writes a copy of the Backup Database to the tape
device controlled by the Tape Coordinator with port offset 1:

    backup savedb -portoffset 1

=head1 PRIVILEGE REQUIRED

The issuer must be listed in the B</usr/afs/etc/UserList> file on every
machine where the Backup Server is running, or must be logged onto a
server machine as the local superuser B<root> if the B<-localauth> flag is
included.

=head1 COPYRIGHT

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.

=head1 SEE ALSO

L<backup(1)>,
L<backup_dbverify(1)>,
L<backup_restoredb(1)>,
L<butc(1)>

=cut
