Using the Backup System's Interfaces

Using the Backup System's Interfaces
	Chapter 7. Backing Up and Restoring AFS Data

When performing backup operations, you interact with three Backup System components:

You initiate backup operations by issuing commands from the backup suite. You can issue the commands in a command shell (or invoke them in a shell script) on any AFS client or server machine from which you can access the backup binary. In the conventional configuration, the binary resides in the /usr/afs/bin directory on a server machine and the /usr/afsws/etc directory on a client machine.
The suite provides an interactive mode, in which you can issue multiple commands over a persistent connection to the Backup Server and the Volume Location (VL) Server. Interactive mode has several convenient features. For a discussion and instructions, see Using Interactive and Regular Command Mode.
Note that some operating systems include a backup command of their own. You must configure machines that run such an operating system to ensure that you are accessing the desired backup binary.
Before you perform a backup operation that involves reading or writing to a tape device or backup data file, you must open a dedicated connection to the appropriate Tape Coordinator machine and start the Tape Coordinator (butc) process that handles the device or file. The butc process must continue to run over the dedicated connection as long as it is executing an operation or is to be available to execute one. For further discussion and instructions, see Starting and Stopping the Tape Coordinator Process.
The Backup Server (buserver) process must be running on database server machines, because most backup operations require accessing or changing information in the Backup Database. The OpenAFS Quick Beginnings explains how to configure the Backup Server.

For consistent Backup System performance, the AFS build level of all three binaries (backup, butc, and buserver) must match. For instructions on displaying the build level, see Displaying A Binary File's Build Level.

Performing Backup Operations as the Local Superuser Root or in a Foreign Cell

By default, the volumes and Backup Database involved in a backup operation must reside on server machines that belong to the cell named in the /usr/vice/etc/ThisCell files on both the Tape Coordinator machine and the machine where you issue the backup command. Also, to issue most backup commands you must have AFS tokens for an identity listed in the local cell's /usr/afs/etc/UserList file (which by convention is the same on every server machine in a cell). You can, however, perform backup operations on volumes or the Backup Database from a foreign cell, or perform backup operations while logged in as the local superuser root rather than as a privileged AFS identity.

To perform backup operations on volumes that reside in a foreign cell using machines from the local cell, you must designate the foreign cell as the cell of execution for both the Tape Coordinator and the backup command interpreter. Use one of the two following methods. For either method, you must also have tokens as an administrator listed in the foreign cell's /usr/afs/etc/UserList file.

Before issuing backup commands and the butc command, set the AFSCELL environment variable to the foreign cell name in both command shells.
Include the -cell argument to the butc and all backup commands. If you include the argument on the backup (interactive) command, it applies to all commands issued during the interactive session.

To perform backup operations without having administrative AFS tokens, you must log on as the local superuser root on both the Tape Coordinator machine and the machine where you issue backup commands. Both machines must be server machines, or at least have a /usr/afs/etc/KeyFile file that matches the file on other server machines. Then include the -localauth argument on both the butc command and all backup commands (or the backup (interactive) command). The Tape Coordinator and backup command interpreter construct a server ticket using the server encryption key with the highest key version number in the local /usr/afs/etc/KeyFile file, and present it to the Backup Server, Volume Server, and VL Server that belong to the cell named in the local /usr/afs/etc/ThisCell file. The ticket never expires.

You cannot combine the -cell and -localauth options on the same command. Also, each one overrides the local cell setting defined by the AFSCELL environment variable or the /usr/vice/etc/ThisCell file.

Using Interactive and Regular Command Mode

The backup command suite provides an interactive mode, in which you can issue multiple commands over a persistent connection to the Backup Server and the VL Server. Interactive mode provides the following features:

The backup> prompt replaces the usual command shell prompt.
You omit the initial backup string from command names. Type only the operation code and option names.
You cannot issue commands that do not belong to the backup suite.
If you assume an administrative AFS identity or specify a foreign cell as you enter interactive mode, it applies to all commands issued during the interactive session. See Performing Backup Operations as the Local Superuser Root or in a Foreign Cell.
You do not need to enclose shell metacharacters in double quotes.

When you initiate a backup operation in interactive mode, the Backup System assigns it a job ID number. You can display the list of current and pending operations with the (backup) jobs command, for which instructions appear in To display pending or running jobs in interactive mode. (In both regular and interactive modes, the Tape Coordinator also assigns a task ID number to each operation you initiate with a backup command. You can track task ID numbers with the backup status command. See Starting and Stopping the Tape Coordinator Process.)

You can cancel an operation in interactive mode with the (backup) kill command, for which instructions appear in To cancel operations in interactive mode. However, it is best not to interrupt a dump operation because the resulting dump is incomplete, and interrupting a restore operation can leave volumes in an inconsistent state, or even completely remove them from the server machine. For further discussion, see Backing Up Data and Restoring and Recovering Data.

The (backup) jobs and (backup) kill commands are available only in interactive mode and there is no equivalent functionality in regular command mode.

To enter interactive mode

Verify that you are authenticated as a user listed in the /usr/afs/etc/UserList file. Entering interactive mode does not itself require privilege, but most other backup commands do, and the AFS identity you assume when entering the mode applies to all commands you issue within it. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.
```
   % bos listusers <machine name>
```
Issue the backup (interactive) command at the system prompt. The backup> prompt appears. You can include either, but not both, of the -localauth and -cell options, as discussed in Performing Backup Operations as the Local Superuser Root or in a Foreign Cell.
```
   % backup
   backup>
```

To exit interactive mode

Issue the quit command at the backup> prompt. The command shell prompt reappears when the command succeeds, which it does only if there are no jobs pending or currently running. To display and cancel pending or running jobs, follow the instructions in To display pending or running jobs in interactive mode and To cancel operations in interactive mode.
```
   backup> quit
   %
```

To display pending or running jobs in interactive mode

Issue the jobs command at the backup> prompt.
```
   backup> jobs
```
where
j
Is the shortest acceptable abbreviation of jobs.

The output always includes the expiration date and time of the tokens that the backup command interpreter is using during the current interactive session, in the following format:

   date   time: TOKEN EXPIRATION

If the execution date and time specified for a scheduled dump operation is later than date time, then its individual line (as described in the following paragraphs) appears below this line to indicate that the current tokens will not be available to it.

If the issuer of the backup command included the -localauth flag when entering interactive mode, the line instead reads as follows:

   :  TOKEN NEVER EXPIRES

The entry for a scheduled dump operation has the following format:

   Job job_ID:  timestamp:  dump  volume_set  dump_level

where

job_ID: Is a job identification number assigned by the Backup System.
timestamp: Indicates the date and time the dump operation is to begin, in the format month/date/year hours:minutes (in 24-hour format)
volume_set: Indicates the volume set to dump.
dump_level: Indicates the dump level at which to perform the dump operation.

The line for a pending or running operation of any other type has the following format:

   Job job_ID:  operation  status

where

job_ID

Is a job identification number assigned by the Backup System.

operation

Identifies the operation the Tape Coordinator is performing, which is initiated by the indicated command:

Dump (dump name)

Initiated by the backup dump command. The dump name has the following format:

volume_set_name.dump_level_name

Restore

Initiated by the backup diskrestore, backup volrestore, or backup volsetrestore command.

Labeltape (tape_label)

Initiated by the backup labeltape command. The tape_label is the name specified by the backup labeltape command's -name or -pname argument.

Scantape

Initiated by the backup scantape command.

SaveDb

Initiated by the backup savedb command.

RestoreDb

Initiated by the backup restoredb command.

status

Indicates the job's current status in one of the following messages. If no message appears, the job is either still pending or has finished.

number Kbytes, volume volume_name: For a running dump operation, indicates the number of kilobytes copied to tape or a backup data file so far, and the volume currently being dumped.
number Kbytes, restore.volume: For a running restore operation, indicates the number of kilobytes copied into AFS from a tape or a backup data file so far.
[abort requested]: The (backup) kill command was issued, but the termination signal has yet to reach the Tape Coordinator.
[abort sent]: The operation is canceled by the (backup) kill command. Once the Backup System removes an operation from the queue or stops it from running, it no longer appears at all in the output from the command.
[butc contact lost]: The backup command interpreter cannot reach the Tape Coordinator. The message can mean either that the Tape Coordinator handling the operation was terminated or failed while the operation was running, or that the connection to the Tape Coordinator timed out.
[done]: The Tape Coordinator has finished the operation.
[drive wait]: The operation is waiting for the specified tape drive to become free.
[operator wait]: The Tape Coordinator is waiting for the backup operator to insert a tape in the drive.

To cancel operations in interactive mode

Issue the jobs command at the backup> prompt, to learn the job ID number of the operation you want to cancel. For details, see To display pending or running jobs in interactive mode.
```
   backup> jobs
```
Issue the (backup) kill command to cancel the operation.
```
   backup> kill <job ID or dump set name>
```
where
k
Is the shortest acceptable abbreviation of kill.
job ID or dump set name
Specifies either the job ID number of the operation to cancel, as reported by the jobs command, or for a dump operation only, the dump name in the format volume_set_name.dump_level_name.

Starting and Stopping the Tape Coordinator Process

Before performing a backup operation that reads from or writes to a tape device or backup data file, you must start the Tape Coordinator (butc) process that handles the drive or file. This section explains how to start, stop, and check the status of a Tape Coordinator process. To use these instructions, you must have already configured the Tape Coordinator machine and created a Tape Coordinator entry in the Backup Database, as instructed in Configuring Tape Coordinator Machines and Tape Devices.

The Tape Coordinator assigns a task ID number to each operation it performs. The number is distinct from the job ID number assigned by the backup command interpreter in interactive mode (which is discussed in Using Interactive and Regular Command Mode). The Tape Coordinator reports the task ID number in its onscreen trace and in the messages that it writes to its log and error files. To view the task ID numbers of a Tape Coordinator's running or pending operations, issue the backup status command.

To start a Tape Coordinator process

Verify that you are authenticated as a user listed in the /usr/afs/etc/UserList file of the cell in which the Tape Coordinator is to access volume data and the Backup Database. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.
```
   % bos listusers <machine name>
```
Alternately, you can log into a file server machine as the local superuser root in Step 3.
Verify that you can write to the Tape Coordinator's log and error files in the local /usr/afs/backup directory (the TE_device_name and TL_device_name files). If the log and error files do not already exist, you must be able to insert and write to files in the /usr/afs/backup directory.
Open a connection (using a command such as telnet or rlogin) to the Tape Coordinator machine that drives the tape device, or whose local disk houses the backup data file. The Tape Coordinator uses a devoted connection or window that must remain open for the Tape Coordinator to accept requests and while it is executing them.
If you plan to include the -localauth flag to the butc command in the next step, log in as the local superuser root.
Issue the butc command to start the Tape Coordinator. You can include either, but not both, of the -localauth and -cell options, as discussed in Performing Backup Operations as the Local Superuser Root or in a Foreign Cell.
```
   % butc [<port offset>]  [-debuglevel <trace level>]  \
          [-cell <cellname>] [-noautoquery] [-localauth]
```
where
butc
Must be typed in full.
port offset
Specifies the Tape Coordinator's port offset number. You must provide this argument unless the default value of 0 (zero) is appropriate.
-debuglevel
Specifies the type of trace messages that the Tape Coordinator writes to the standard output stream (stdout). Provide one of the following three values, or omit this argument to display the default type of messages (equivalent to setting a value of 0 [zero]):
0: The Tape Coordinator generates only the minimum number of messages necessary to communicate with the backup operator, including prompts for insertion of additional tapes and messages that indicate errors or the beginning or completion of operations.
1: In addition to the messages displayed at level 0, the Tape Coordinator displays the name of each volume being dumped or restored.
2: In addition to the messages displayed at levels 0 and 1, the Tape Coordinator displays all of the messages it is also writing to its log file (/usr/afs/backup/TL_device_name).
cellname
Names the cell in which to perform the backup operations (the cell where the relevant volumes reside and the Backup Server process is running). If you omit this argument, the Tape Coordinator uses its home cell, as defined in the local /usr/vice/etc/ThisCell file. Do not combine this argument with the -localauth flag.
-noautoquery
Disables the Tape Coordinator's prompt for the first tape it needs for each operation. For a description of the advantages and consequences of including this flag, see Eliminating the Search or Prompt for the Initial Tape.
-localauth
Constructs a server ticket using a key from the local /usr/afs/etc/KeyFile file. The butc process presents it to the Backup Server, Volume Server, and VL Server during mutual authentication. You must be logged into a file server machine as the local superuser root to include this flag, and cannot combine it with the -cell argument.

To stop a Tape Coordinator process

Enter an interrupt signal such as <Ctrl-c> over the dedicated connection to the Tape Coordinator.

To check the status of a Tape Coordinator process

Verify that you are authenticated as a user listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.
```
   % bos listusers <machine name>
```
Issue the backup status command.
```
   % backup status [<TC port offset>]
```
where
st
Is the shortest acceptable abbreviation of status.
TC port offset
Specifies the Tape Coordinator's port offset number. You must provide this argument unless the default value of 0 (zero) is appropriate.

The following message indicates that the Tape Coordinator is not currently performing an operation:

   Tape coordinator is idle

Otherwise, the output includes a message of the following format for each running or pending operation:

   Task task_ID:  operation:   status

where

task_ID

Is a task identification number assigned by the Tape Coordinator. It begins with the Tape Coordinator's port offset number.

operation

Identifies the operation the Tape Coordinator is performing, which is initiated by the indicated command:

Dump (the backup dump command)
Restore (the backup diskrestore, backup volrestore, or backup volsetrestore commands)
Labeltape (the backup labeltape command)
Scantape (the backup scantape command)
SaveDb (the backup savedb command)
RestoreDb (the backup restoredb command)

status

Indicates the job's current status in one of the following messages.

number Kbytes transferred, volume volume_name: For a running dump operation, indicates the number of kilobytes copied to tape or a backup data file so far, and the volume currently being dumped.
number Kbytes, restore.volume: For a running restore operation, indicates the number of kilobytes copied into AFS from a tape or a backup data file so far.
[abort requested]: The (backup) kill command was issued, but the termination signal has yet to reach the Tape Coordinator.
[abort sent]: The operation is canceled by the (backup) kill command. Once the Backup System removes an operation from the queue or stops it from running, it no longer appears at all in the output from the command.
[butc contact lost]: The backup command interpreter cannot reach the Tape Coordinator. The message can mean either that the Tape Coordinator handling the operation was terminated or failed while the operation was running, or that the connection to the Tape Coordinator timed out.
[done]: The Tape Coordinator has finished the operation.
[drive wait]: The operation is waiting for the specified tape drive to become free.
[operator wait]: The Tape Coordinator is waiting for the backup operator to insert a tape in the drive.

If the Tape Coordinator is communicating with an XBSA server (a third-party backup utility that implements the Open Group's Backup Service API [XBSA]), the following message appears last in the output:

   XBSA_program Tape coordinator

where XBSA_program is the name of the XBSA-compliant program.