Using the Backup System's Interfaces

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

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

  1. 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>
    
  2. 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

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

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

  1. 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
    
  2. 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

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

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

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

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

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

  1. 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>
    
  2. 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.