doc/html/AdminReference/auarf060.htm

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
   2 <HTML><HEAD>
   3 <TITLE>Administration Reference</TITLE>
   4 <!-- Begin Header Records  ========================================== -->
   5 <!-- /tmp/idwt3672/auarf000.scr converted by idb2h R4.2 (359) ID      -->
   6 <!-- Workbench Version (AIX) on 3 Oct 2000 at 16:18:30                -->
   7 <META HTTP-EQUIV="updated" CONTENT="Tue, 03 Oct 2000 16:18:29">
   8 <META HTTP-EQUIV="review" CONTENT="Wed, 03 Oct 2001 16:18:29">
   9 <META HTTP-EQUIV="expires" CONTENT="Thu, 03 Oct 2002 16:18:29">
  10 </HEAD><BODY>
  11 <!-- (C) IBM Corporation 2000. All Rights Reserved    -->
  12 <BODY bgcolor="ffffff">
  13 <!-- End Header Records  ============================================ -->
  14 <A NAME="Top_Of_Page"></A>
  15 <H1>Administration Reference</H1>
  16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf059.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auarf061.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
  17 <P>
  18 <H2><A NAME="HDRBK_INTRO" HREF="auarf002.htm#ToC_74">backup</A></H2>
  19 <A NAME="IDX4203"></A>
  20 <A NAME="IDX4204"></A>
  21 <A NAME="IDX4205"></A>
  22 <A NAME="IDX4206"></A>
  23 <A NAME="IDX4207"></A>
  24 <P><STRONG>Purpose</STRONG>
  25 <P>Introduction to the <B>backup</B> command suite
  26 <P><STRONG>Description</STRONG>
  27 <P>The commands in the <B>backup</B> command suite are the administrative
  28 interface to the AFS Backup System. There are several categories of
  29 commands in the suite:
  30 <UL>
  31 <P><LI>Commands to copy data from AFS volumes to tape or a backup data file, and
  32 to restore it to the file system: <B>backup diskrestore</B>,
  33 <B>backup dump</B>, <B>backup volrestore</B>, and <B>backup
  34 volsetrestore</B>
  35 <P><LI>Commands to administer the records in the Backup Database:
  36 <B>backup adddump</B>, <B>backup addhost</B>, <B>backup
  37 addvolentry</B>, <B>backup addvolset</B>, <B>backup deldump</B>,
  38 <B>backup deletedump</B>, <B>backup delhost</B>, <B>backup
  39 delvolentry</B>, <B>backup delvolset</B>, <B>backup dumpinfo</B>,
  40 <B>backup listdumps</B>, <B>backup listhosts</B>, <B>backup
  41 listvolsets</B>, <B>backup scantape</B>, <B>backup setexp</B>, and
  42 <B>backup volinfo</B>
  43 <P><LI>Commands to write and read tape labels: <B>backup labeltape</B>
  44 and <B>backup readlabel</B>
  45 <P><LI>Commands to list and change the status of backup operations and the
  46 machines performing them: <B>(backup) jobs</B>, <B>(backup)
  47 kill</B>, and <B>backup status</B>
  48 <P><LI>Commands to enter and leave interactive mode: <B>backup
  49 (interactive)</B> and <B>(backup) quit</B>
  50 <P><LI>Commands to check for and repair corruption in the Backup Database:
  51 <B>backup dbverify</B>, <B>backup restoredb</B>, and <B>backup
  52 savedb</B>
  53 <P><LI>Commands to obtain help: <B>backup apropos</B> and <B>backup
  54 help</B>
  55 </UL>
  56 <P>The <B>backup</B> command interpreter interacts with two other
  57 processes:
  58 <A NAME="IDX4208"></A>
  59 <A NAME="IDX4209"></A>
  60 <UL>
  61 <P><LI>The Backup Server (<B>buserver</B>) process. It maintains the
  62 Backup Database, which stores most of the administrative information used by
  63 the Backup System. In the standard configuration, the Backup Server
  64 runs on each database server machine in the cell, and uses AFS's
  65 distributed database technology, Ubik, to synchronize its copy of the database
  66 with the copies on the other database server machines.
  67 <P><LI>The Backup Tape Coordinator (<B>butc</B>) process. A separate
  68 instance of the process controls each tape device or backup data file used to
  69 dump or restore data. The Tape Coordinator runs on a Tape Coordinator
  70 machine, which is an AFS server or client machine that has one or more tape
  71 devices attached, or has sufficient disk space to accommodate one or more
  72 backup data files on its local disk.
  73 <P>Each Tape Coordinator must be registered in the Backup Database and in the
  74 <B>/usr/afs/backup/tapeconfig</B> configuration file on the Tape
  75 Coordinator machine's local disk, and information in the two places must
  76 be consistent for proper Backup System performance. The optional
  77 <B>/usr/afs/backup/CFG_</B><VAR>device_name</VAR> for each Tape Coordinator
  78 records information used to automate its operation.
  79 </UL>
  80 <P>In addition to the standard command line interface, the <B>backup</B>
  81 command suite provides an <I>interactive</I> interface, which has several
  82 useful features described on the <B>backup (interactive)</B> reference
  83 page. Three of the commands in the suite are available only in
  84 interactive mode: <B>(backup) jobs</B>, <B>(backup) kill</B>,
  85 and <B>(backup) quit</B>.
  86 <P><STRONG>Options</STRONG>
  87 <P>The following options are available on many commands in the
  88 <B>backup</B> suite. The reference page for each command also lists
  89 them, but they are described here in greater detail.
  90 <A NAME="IDX4210"></A>
  91 <A NAME="IDX4211"></A>
  92 <A NAME="IDX4212"></A>
  93 <DL>
  94 <P><DT><B>-cell &lt;<VAR>cell name</VAR>>
  95 </B><DD>Names the cell in which to run the command. It is acceptable to
  96 abbreviate the cell name to the shortest form that distinguishes it from the
  97 other entries in the <B>/usr/vice/etc/CellServDB</B> file on the local
  98 machine. If the <B>-cell</B> argument is omitted, the command
  99 interpreter determines the name of the local cell by reading the following in
 100 order:
 101 <OL TYPE=1>
 102 <P><LI>The value of the AFSCELL environment variable
 103 <P><LI>The local <B>/usr/vice/etc/ThisCell</B> file
 104 </OL>
 105 <P>
 106 <P>Do not combine the <B>-cell</B> and <B>-localauth</B>
 107 options. A command on which the <B>-localauth</B> flag is included
 108 always runs in the local cell (as defined in the server machine's local
 109 <B>/usr/afs/etc/ThisCell</B> file), whereas a command on which the
 110 <B>-cell</B> argument is included runs in the specified foreign
 111 cell.
 112 <P>The <B>-cell</B> argument is not available on commands issued in
 113 interactive mode. The cell defined when the <B>backup</B> command
 114 interpreter enters interactive mode applies to all commands issued during the
 115 interactive session.
 116 <A NAME="IDX4213"></A>
 117 <P><DT><B>-help
 118 </B><DD>Prints a command's online help message on the standard output
 119 stream. Do not combine this flag with any of the command's other
 120 options; when it is provided, the command interpreter ignores all other
 121 options, and only prints the help message.
 122 <P><DT><B>
 123 <A NAME="IDX4214"></A>
 124 -localauth
 125 </B><DD>Constructs a server ticket using the server encryption key with the
 126 highest key version number in the local <B>/usr/afs/etc/KeyFile</B>
 127 file. The <B>backup</B> command interpreter presents the ticket,
 128 which never expires, to the Backup Server, Volume Server and Volume Location
 129 (VL) Server during mutual authentication.
 130 <P>Use this flag only when issuing a command on a server machine; client
 131 machines do not usually have a <B>/usr/afs/etc/KeyFile</B> file.
 132 The issuer of a command that includes this flag must be logged on to the
 133 server machine as the local superuser <B>root</B>. The flag is
 134 useful for commands invoked by an unattended application program, such as a
 135 process controlled by the UNIX <B>cron</B> utility or by a cron entry in
 136 the machine's <B>/usr/afs/local/BosConfig</B> file. It is also
 137 useful if an administrator is unable to authenticate to AFS but is logged in
 138 as the local superuser <B>root</B>.
 139 <P>Do not combine the <B>-cell</B> and <B>-localauth</B>
 140 options. A command on which the <B>-localauth</B> flag is included
 141 always runs in the local cell (as defined in the server machine's local
 142 <B>/usr/afs/etc/ThisCell</B> file), whereas a command on which the
 143 <B>-cell</B> argument is included runs in the specified foreign
 144 cell.
 145 <P>The <B>-localauth</B> argument is not available on commands issued in
 146 interactive mode. The local identity and AFS tokens with which the
 147 <B>backup</B> command interpreter enters interactive mode apply to all
 148 commands issued during the interactive session.
 149 <P><DT><B>
 150 <A NAME="IDX4215"></A>
 151 -portoffset &lt;<VAR>TC port offset</VAR>>
 152 </B><DD>Specifies the port offset number of the Tape Coordinator that is to
 153 execute the <B>backup</B> command. The port offset number uniquely
 154 identifies a pairing of a Tape Coordinator (<B>butc</B>) process and tape
 155 device or backup data file.
 156 <P>The <B>backup</B> command interpreter and Tape Coordinator process
 157 communicate via a UDP socket, or port. Before issuing a
 158 <B>backup</B> command that involves reading or writing a tape, the backup
 159 operator must start a <B>butc</B> process that controls the appropriate
 160 tape device and listens for requests sent to its port number. If a
 161 Backup System machine has multiple tape devices attached, they can perform
 162 backup operations simultaneously because each device has its own associated
 163 <B>butc</B> process and port offset number.
 164 <P>The Backup System associates a tape capacity and file mark size with each
 165 port offset (as defined in the <B>tapeconfig</B> file). For a
 166 compressing tape device, the capacity and file mark values differ for
 167 compression and non-compression modes, so the two modes have distinct port
 168 offset numbers.
 169 <P>The Backup Database can store up to 58,511 port offsets, so the legal
 170 values for this argument are the integers <B>0</B> through
 171 <B>58510</B>. If the issuer omits the argument, it defaults to
 172 <B>0</B>. (The limit of 58,511 port offsets results from the fact
 173 that UDP socket numbers are identified by a 16-bit integer, and the lowest
 174 socket number used by the Backup System is 7025. The largest number
 175 that a 16-bit integer can represent is 65,535. Subtracting 7,025 yields
 176 58,510. The addition of port offset 0 (zero) increases the maximum to
 177 58,511.)
 178 <P>Although it is possible to define up to 58,511 port offset numbers for a
 179 cell, it is not possible to run 58,511 tape devices simultaneously, due to the
 180 following limits:
 181 <UL>
 182 <P><LI>The maximum number of dump or restore operations that can run
 183 simultaneously is 64.
 184 <P><LI>The maximum number of tape devices that can work together on a restore
 185 operation is 128 (that is the maximum number of values that can be provided
 186 for the <B>-portoffset</B> argument to the <B>backup diskrestore</B>,
 187 <B>backup volrestore</B>, or <B>backup volsetrestore</B>
 188 command).
 189 </UL>
 190 <P>
 191 <P>The Backup System does not reserve UDP sockets. If another
 192 application is already using the Tape Coordinator's socket when it tries
 193 to start, the <B>butc</B> process fails and the following error message
 194 appears at the shell prompt:
 195 <PRE>   bind: Address already in use
 196    rxi_GetUDPSocket: bind failed
 197
 198 </PRE>
 199 </DL>
 200 <P><STRONG>Privilege Required</STRONG>
 201 <A NAME="IDX4216"></A>
 202 <A NAME="IDX4217"></A>
 203 <P>To issue any <B>backup</B> command that accesses the Backup Database
 204 only, the issuer must be listed in the <B>/usr/afs/etc/UserList</B> file
 205 on every machine where the Backup Server is running. To issue any
 206 <B>backup</B> command that accesses volume data, the issuer must appear in
 207 the <B>UserList</B> file on every Backup Server machine, every Volume
 208 Location (VL) Server machine, and every file server machine that houses
 209 affected volumes. By convention, a common <B>UserList</B> file is
 210 distributed to all database server and file server machines in the
 211 cell. See the chapter on privileged users in the <I>IBM AFS
 212 Administration Guide</I> for more information on this type of
 213 privilege.
 214 <P>If the <B>-localauth</B> flag is included, the user must instead be
 215 logged on as the local superuser <B>root</B> on the server machine where
 216 the <B>backup</B> command is issued.
 217 <P><STRONG>Related Information</STRONG>
 218 <P><A HREF="auarf016.htm#HDRBOSCONFIG">BosConfig</A>
 219 <P><A HREF="auarf018.htm#HDRCFG">CFG_<I>device_name</I></A>
 220 <P><A HREF="auarf019.htm#HDRCLI_CSDB">CellServDB (client version)</A>
 221 <P><A HREF="auarf023.htm#HDRKEYFILE">KeyFile</A>
 222 <P><A HREF="auarf032.htm#HDRCLI_THISCELL">ThisCell (client version)</A>
 223 <P><A HREF="auarf033.htm#HDRSV_THISCELL">ThisCell (server version)</A>
 224 <P><A HREF="auarf035.htm#HDRUSERLIST">UserList</A>
 225 <P><A HREF="auarf050.htm#HDRTAPECONFIG">tapeconfig</A>
 226 <P><A HREF="auarf061.htm#HDRBK_ADDDUMP">backup adddump</A>
 227 <P><A HREF="auarf062.htm#HDRBK_ADDHOST">backup addhost</A>
 228 <P><A HREF="auarf063.htm#HDRBK_ADDVOLENTRY">backup addvolentry</A>
 229 <P><A HREF="auarf064.htm#HDRBK_ADDVOLSET">backup addvolset</A>
 230 <P><A HREF="auarf066.htm#HDRBK_DBVERIFY">backup dbverify</A>
 231 <P><A HREF="auarf067.htm#HDRBK_DELDUMP">backup deldump</A>
 232 <P><A HREF="auarf068.htm#HDRBK_DELETEDUMP">backup deletedump</A>
 233 <P><A HREF="auarf069.htm#HDRBK_DELHOST">backup delhost</A>
 234 <P><A HREF="auarf070.htm#HDRBK_DELVOLENTRY">backup delvolentry</A>
 235 <P><A HREF="auarf071.htm#HDRBK_DELVOLSET">backup delvolset</A>
 236 <P><A HREF="auarf072.htm#HDRBK_DISKRESTORE">backup diskrestore</A>
 237 <P><A HREF="auarf073.htm#HDRBK_DUMP">backup dump</A>
 238 <P><A HREF="auarf074.htm#HDRBK_DUMPINFO">backup dumpinfo</A>
 239 <P><A HREF="auarf075.htm#HDRBK_HELP">backup help</A>
 240 <P><A HREF="auarf076.htm#HDRBK_INTERACTIVE">backup interactive</A>
 241 <P><A HREF="auarf077.htm#HDRBK_JOBS">backup jobs</A>
 242 <P><A HREF="auarf078.htm#HDRBK_KILL">backup kill</A>
 243 <P><A HREF="auarf079.htm#HDRBK_LABELTAPE">backup labeltape</A>
 244 <P><A HREF="auarf080.htm#HDRBK_LISTDUMPS">backup listdumps</A>
 245 <P><A HREF="auarf081.htm#HDRBK_LISTHOSTS">backup listhosts</A>
 246 <P><A HREF="auarf082.htm#HDRBK_LISTVOLSETS">backup listvolsets</A>
 247 <P><A HREF="auarf083.htm#HDRBK_QUIT">backup quit</A>
 248 <P><A HREF="auarf084.htm#HDRBK_READLABEL">backup readlabel</A>
 249 <P><A HREF="auarf085.htm#HDRBK_RESTOREDB">backup restoredb</A>
 250 <P><A HREF="auarf086.htm#HDRBK_SAVEDB">backup savedb</A>
 251 <P><A HREF="auarf087.htm#HDRBK_SCANTAPE">backup scantape</A>
 252 <P><A HREF="auarf088.htm#HDRBK_SETEXP">backup setexp</A>
 253 <P><A HREF="auarf089.htm#HDRBK_STATUS">backup status</A>
 254 <P><A HREF="auarf090.htm#HDRBK_VOLINFO">backup volinfo</A>
 255 <P><A HREF="auarf091.htm#HDRBK_VOLRESTORE">backup volrestore</A>
 256 <P><A HREF="auarf092.htm#HDRBK_VOLSETRESTORE">backup volsetrestore</A>
 257 <P><A HREF="auarf125.htm#HDRBUSERVER">buserver</A>
 258 <P><A HREF="auarf126.htm#HDRBUTC">butc</A>
 259 <P>
 260 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf059.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auarf061.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
 261 <!-- Begin Footer Records  ========================================== -->
 262 <P><HR><B>
 263 <br>&#169; <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A>  All Rights Reserved
 264 </B>
 265 <!-- End Footer Records  ============================================ -->
 266 <A NAME="Bot_Of_Page"></A>
 267 </BODY></HTML>