AFS/DFS Backup Clients


Chapter 5. Using the AFS Volume Backup Agent

Transarc's AFS backup commands back up AFS volumes to tape devices using the BackUp Tape Coordinator (butc) program. The butc program then prompts for the tapes to which it writes the backup data. Each machine running butc is connected to a tape device that can be a simple drive or a stacker. This AFS volume backup system consists of the following commands:

backup
buserver
butc

The TSM agent program, BackUp To TSM (buta), is a replacement for butc, the tape interface program of the volume backup system. The AFS buta program is an interface between the AFS backup commands and a TSM server, and lets you back up and restore AFS data by volume. AFS buta accomplishes these tasks using TSM application program interface (API) function calls. Through the TSM API, each full or incremental volume dump is sent to a TSM server as a file with the same name as the volume.

The volume dump files are stored within a single file space in TSM storage named with the dump ID string. A TSM administrator can delete an AFS backup dump from TSM storage by deleting the file space in which it is stored. When an AFS backup dump is deleted from TSM storage, it is also be removed from the AFS backup database using the AFS backup command. TSM provides a utility program with buta, called delbuta, that performs both of these tasks for you by deleting the unwanted old dumps from both the AFS backup database and the TSM server simultaneously.

To improve the performance of backup operations, start multiple instances of buta at one time, running on the same machine and on different machines.

If you have a small cell and a busy network between file servers and the TSM server, and your TSM server is on AIX, you might want to run only one buta instance on the TSM server to back up all volumes. You can also run one buta instance on each file server machine sequentially, permitting only one buta instance at a time to back up its local volumes to TSM.

If you have a large cell and a dedicated network between file servers and the TSM server, you might want to run one buta instance on every file server, backing up its local volumes so that you can finish the full dumps within the time window available. A large number of buta dumps can be performed simultaneously. The ideal number of concurrent dumps depends on the configurations of your network and servers.

Important:All instances of buta running on one or more machines must use the same TSM node name and password.
Note:System administrators should familiarize themselves with the AFS volume backup system (backup and buserver commands) since the buta program is used as a part of that system and it works like a special version of butc. Refer to the chapters on backup system commands in the AFS manuals.

Setting Up the AFS Volume Backup Agent

Before you start the AFS buta program, you need to define environment variables, install the API, and perform administration tasks. The next sections describe these procedures.

Installation

Install the TSM API and the buta program on selected machines.

Note:The selected machines must also have the AFS Client installed. This then becomes a buta machine. For install procedures, see Tivoli Storage Manager Installing the Clients, SH26-4102.

TSM Buta Client Configuration

Follow the steps below to define TSM environment variables and options.

  1. Specify the client system options file (dsm.sys), the client user options file (dsm.opt), and the API error log file (dsierror.log) that you want to use for buta backups using the dsmi_config, dsmi_dir, and dsmi_log environment variables. For information on how to specify these variables, see Table 8.
    Note:The default paths for dsmi_config and dsmi_dir are different for different versions of the TSM API. See the Readme file for the API version you are using to determine the default locations.

  2. Optionally, specify the central logging file if you want all buta instances to log a summary information line to a centrally located file after each backup and restore command.

    Each buta instance creates a separate log file. If you want the summary of all dumps and restore operations from all buta instances in one file, then you can use the centrallog option to point to that file. You can specify a JFS file if all your buta instances are running on the same machine. If your buta instances are running on different machines and you want the summary from all machines in one file, then you must specify an NFS file with the centrallog option.

  3. Optionally, specify the delbuta configuration file (delbuta.opt) that you want to use to specify delbuta options. If you do not define this variable, delbuta will look for this file in the /usr/afs/buta directory.

    Table 8. How to Specify the Options Files

    Variable What it does Example
    dsmi_config Points to the client user options file (dsm.opt).
    export dsmi_config=/usr/afs/buta/dsm.opt
    

    dsmi_dir Points to the directory that contains the client system options file (dsm.sys).
    export dsmi_dir=/usr/afs/buta
     
    

    dsmi_log Points to the directory that contains the API error log file (dsierror.log).
    export dsmi_log=/usr/afs/buta
    

    centrallog Points to a JFS or NFS central log file where a summary line is logged for each dump or restore from all buta instances.
    export centrallog=/usr/afs/buta/butalogs
    

    delbuta_config Points to the delbuta options file (delbuta.opt).
    export delbuta_config=/usr/afs/buta/delbuta.opt
    

    Note:Do not place a slash (/) at the end of the directory path.

  4. Set the tapeprompt option to no, and the compressalways option to yes in the client user options (dsm.opt) file. For example:
       servername       seaside
       tapeprompt       no
       compressalways   yes
    

  5. Set the passwordaccess option to prompt in the client system options (dsm.sys) file.

  6. Set the compression option to yes in the client system options (dsm.sys) file if you want to compress data before sending it to a TSM server. For example, set the contents of /usr/afs/buta/dsm.sys to:
       servername            seaside
       tcpport               1500
       tcpserveraddress      seaside.almaden.ibm.com
       passwordaccess        prompt
       compression           yes
    

  7. To ensure that language support works correctly, create a symbolic link to the message catalog directory in the dsmi_dir directory. For example, if your dsmi_dir environment variable equals /usr/afs/buta, create the following symbolic link:
       /usr/afs/buta/en_US -> /usr/lpp/adsm/bin/en_US
    

Adding the AFS Backup Host

Follow the steps below to add the buta host to the coordinator host database.

  1. Perform a klog admin first.

  2. Add the buta host to the coordinator host database using this backup command:
       backup> addhost <machine name> <port offset>
    

    The machine name parameter is the same as the buta machine name, and the port offset parameter is the same as the port offset you specify to start buta.

TSM Administration

Follow these steps to perform TSM administration tasks:

  1. Ensure the environment variables dsm_config, dsm_dir and dsm_log (or dsmg_config, dsmg_dir and dsmg_log for the graphical administrative user interface) are set appropriately, or that the defaults are acceptable.

  2. Register a buta node name with a TSM server using this dsmadmc command:
       register node <node name> <passwd> backdelete=yes
    
    Note:Register only one buta node name for all buta instances. The same node name and password should be used for all instances of buta. The node name you select should be different from any of your machine names.

  3. Assign your buta node to a TSM policy domain containing a policy set and a management class with a backup copy group appropriate for your buta needs. This can be the default policy domain.

    A backup copy group contains an attribute specifying the destination for your AFS backup dumps. If you want your AFS backup dumps stored in a storage pool separate from other types of backups, your TSM administrator must define a backup copy group specifying that storage pool in the active policy set of the policy domain to which your buta node is assigned.

Start the Buta Program

To start the buta program on a buta machine, do the following:

  1. Perform a klog admin first.

  2. Select the appropriate version of buta. Two versions of the buta program are installed in the /usr/afs/buta directory. The program named buta.afs34a: works with the AFS 3.4a backup and buserver commands.

    Another program named buta.afs34a.patch works with the AFS 3.4a patch version (AFS 3.4 revision 4.40 and after) backup and buserver commands.

  3. Rename the selected version of the buta program to buta.

  4. Enter this buta command:
    buta -port <port offset> -node <node name> -password <node password> \
        -server <server name>
    

    Where the node name and password are the node name and its password that were registered with a TSM server in "TSM Administration". The server name is the server stanza name from the dsm.sys file rather than a network host name.

Backup Commands

You can now use AFS backup commands as usual, specifying a port offset number you defined for each buta command that you enter.

BACKUP COMMANDS WHICH ARE NOT SUPPORTED

The following AFS backup commands are NOT SUPPORTED by buta:

backup labeltape
backup readlabel
backup restoredb
backup savedb
backup scantape
backup setexp
Note:For instructions on how to install TSM programs, update options files, and register a client node, see Tivoli Storage Manager Installing the Clients, SH26-4102.

Using the Buta Command

The buta command starts a buta process on a buta machine.

Enter the buta command over a connection to a buta machine. You must open a separate connection for each buta instance.

If you run buta in the foreground, the connection on which you enter the command is not available for subsequent commands. The buta program uses the connection as a dedicated monitoring connection/window on which to display trace information or prompts. The monitoring connection/window must remain open as long as buta is running. To stop buta, enter an interrupt signal, such as Ctrl-C, in the monitoring window.

If you run buta in the background, use the -alwaysomit parameter to prevent prompting for options if a volume fails to dump.

The buta command writes output to the following two files on the local disk of the buta machine:

/usr/afs/buta/TL.port offset
A log file that contains information about the processing of operations. For example, when you enter the backup dump command, the log file lists both the names of volumes that are dumped successfully, and the names of volumes that incurred some failures during the dump.

/usr/afs/buta/TE.port offset
An error log file that contains information about any problems encountered during the processing of operations. For example, when you enter the backup dump command, the error log file lists only the names of the volumes that incurred some failures during the dump.

The buta command appends information to the log file each time you enter the command. It also appends information to the error log file whenever it encounters a problem. Check the log files periodically to be sure dumps and restores are completing successfully.

Optionally, buta appends summary information to a centrally located log file each time you enter a backup dump or restore command. The buta command appends the summary log to the file pointed to by the centrallog option.

Syntax

>>-buta---+---------------------+---+---------------------+----->
          '- -port port offset--'   '- -debuglevel level--'
 
>-----+-------------------+---+--------------+------------------>
      '- -cell cell name--'   '- -localauth--'
 
>----- -node node name---+- -password password-------+---------->
                         '- -pipe password file name-'
 
>-----+-----------------------+--------------------------------->
      '- -server server name--'
 
>-----+------------------------------------+-------------------->
      '- -mgmtclass management class name--'
 
>-----+---------------------------+---+-----------+------------->
      '- -buffersize buffer size--'   '- -nodots--'
 
>-----+------------------------------+---+---------------+------>
      '- -maxpass number of retries--'   '- -alwaysomit--'
 
>-----+------------+---+-------------+---+---------+-----------><
      '- -lastlog--'   '- -group id--'   '- -help--'
 
Note:The -node option, and either the -password or -pipe-option, are required.

Parameters

-port port offset
Specifies the port offset number associated with the buta instance to be started.

A port offset number is a unique number assigned to a buta instance. When entering an AFS backup command, specify the port offset number of the buta instance that is to execute the command. The default is 0. Valid values are 0 through 58510. You can assign the port offset numbers in sequence, or you can skip numbers.

-debuglevel level
Determines the amount of information buta displays as the output. The values are 0, 1, and 2, with an increasing amount of debugging information provided. The default is 0.

-cell cell name
The cell against which you want the buta instance to run. You must be listed in the /usr/afs/etc/UserList file in the cell you specify, and you must authenticate to the specified cell before using this argument. The default is the local cell of the machine on which the buta instance is run.

-localauth
Constructs a server ticket using a key from /usr/afs/etc/KeyFile.

-node node name
The TSM node name that the buta program uses.

-password password
The TSM password for the node name used by the buta program. If you do not use this option, you must use the -pipe option.

-pipe password file name
Reads the TSM password for the TSM client node from the specified file. If you do not use this option, you must use the -password option.

-server server name
The TSM server to which you want to send backup dumps. The TSM server name should be a stanza name from the dsm.sys file rather than a network host name. The default is the default server specified in the dsm.sys file.

This parameter is required for all buta command invocations if you use multiple TSM servers for buta backup. If you do not use this command parameter, you might not be able to restore the backups properly.

It is recommended that you always use this parameter even if you are not using multiple TSM servers. This prevents you from encountering any restore problems if you later decide to use multiple TSM servers.

-mgmtclass management class name
The name of the TSM management class to bind to the dump files. A management class contains an attribute that specifies the destination storage pool for the dump. The default is the default management class specified by your TSM administrator.

-buffersize size
The size of the TSM buffer that is used to collect AFS volume dump data from AFS volume servers. Specify the size in kilobytes. The default is 128 Kbytes.

-nodots
Prevents the dump progress indicator dots from being printed. By default, the buta command prints one dot (.) each time a full buffer is dumped to, or restored from, the TSM server.

-maxpass number of retries
The number of automatic retries for dumping a volume before prompting for one of these options:
Retry
Omit the volume
End the dump

-alwaysomit
Prevents prompting for options after the last automatic retry for each volume that failed to dump. Failed volumes are always omitted. Use this option if you run the buta command in the background.

-lastlog
Specifies that buta uses a separate error and log file for the last pass. The file names are the normal file names ending with .lp. For example, TL.0.lp is the name of the last-pass log file for port 0, and TE.1.lp is the name of the last-pass error file for port 1.

-group id
Associates a number of dumps to a specific dump group. This lets you exclude specific groups or dumps from deletion.

-help
Prints the online help for this command. Do not use any other arguments or flags with this argument.

Examples

Table 9. Examples of Tasks and Commands

Task Command
Start an instance of buta at port offset 99. buta -port 99 -node afsback -password secret1
Start an instance of buta at port offset 0 and send the backup dump to a server named jaguar. buta -node afsback -password secret1 -server jaguar

Using Delbuta to Delete Backup Dumps

An AFS backup dump can be deleted from TSM storage by deleting the file space in which it is stored. A TSM administrator with the appropriate authority can delete a file space from within a TSM administrative client session.

When an AFS backup dump is deleted from TSM storage, it should also be deleted from the AFS backup database. An AFS administrator can delete a backup dump from the AFS backup database using an AFS backup command.

To delete an AFS backup dump from both TSM storage and the AFS backup database, the delbuta command is used. To use this command, you must have the appropriate authority to delete file spaces from TSM storage, and you must hold AFS administrative tokens.

Before you use the delbuta command, update the delbuta.opt file. This file is installed in the same directory as that of the buta program. Both the AFS back up commands and the TSM administrative client must be available on the same machine.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]