doc/html/ReleaseNotes-3.6/aurns004.htm

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
   2 <HTML><HEAD>
   3 <TITLE>Release Notes</TITLE>
   4 <!-- Begin Header Records  ========================================== -->
   5 <!-- /tmp/idwt3575/aurns000.scr converted by idb2h R4.2 (359) ID      -->
   6 <!-- Workbench Version (AIX) on 2 Oct 2000 at 12:27:59                -->
   7 <META HTTP-EQUIV="updated" CONTENT="Mon, 02 Oct 2000 12:27:58">
   8 <META HTTP-EQUIV="review" CONTENT="Tue, 02 Oct 2001 12:27:58">
   9 <META HTTP-EQUIV="expires" CONTENT="Wed, 02 Oct 2002 12:27:58">
  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>Release Notes</H1>
  16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="aurns002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="aurns003.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> <P>
  17 <HR><H1><A NAME="Header_6" HREF="aurns002.htm#ToC_6">AFS 3.6 Release Notes</A></H1>
  18 <P>This file documents new features, upgrade procedures, and remaining
  19 limitations associated with the initial General Availability (GA) release of
  20 AFS<SUP><SUP>(R)</SUP></SUP> 3.6 (build level <B>afs3.6
  21 2.0</B>).
  22 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">This document includes all product information available at the time the
  23 document was produced. For additional information that became available
  24 later, see the <B>README.txt</B> file included on the AFS
  25 CD-ROM.
  26 </TD></TR></TABLE>
  27 <HR><H2><A NAME="HDRSUMMARY" HREF="aurns002.htm#ToC_7">Summary of New Features</A></H2>
  28 <P>AFS 3.6 includes the following new features.
  29 <UL>
  30 <P><LI>Support for the 64-bit version of Solaris 7.
  31 <P><LI>Support for the 64-bit version of HP-UX 11.0.
  32 <P><LI>The HP-UX 11.0 File Server uses the POSIX-compliant threading
  33 package provided with HP-UX. (Other supported operating systems started
  34 using native threads in AFS 3.5.) See <A HREF="#HDRREQ_HP">Product Notes for HP-UX Systems</A>.
  35 <P><LI>There is a single edition of AFS 3.6, instead of separate United
  36 States and international editions as in previous releases. The United
  37 States government now permits export outside North America of the encryption
  38 software that the Update Server uses to protect user-level data. With
  39 AFS 3.6, cells outside North America can run a system control machine
  40 to distribute the contents of the <B>/usr/afs/etc</B> directory among
  41 server machines.
  42 <P>The AFS 3.6 distribution includes a single CD-ROM for each system
  43 type, which contains all AFS software. There is no CD-ROM labeled
  44 <B>Encryption Files</B> or <B>Domestic Edition</B> in the AFS
  45 3.6 distribution.
  46 <P>Because they were produced before the change in export restrictions, the
  47 <I>IBM AFS Administration Guide</I> and <I>IBM AFS Administration
  48 Reference</I> still distinguish between United States and international
  49 editions of AFS. However, AFS customers in any country can ignore the
  50 distinction and use the United States instructions if they choose.
  51 <P><LI>Support for volumes up to 8 GB in size. In previous versions of
  52 AFS, the limit was 2 GB.
  53 <P>Note that smaller volumes are still more practical than large ones in
  54 general. The larger a volume, the longer it takes to move or clone it,
  55 which introduces greater potential for an outage to halt the operation before
  56 it completes.
  57 <P><LI>Support for backing up AFS data to the Tivoli Storage Manager (TSM),
  58 formerly called the ADSTAR Distributed Storage Manager (ADSM). TSM
  59 implements the Open Group's Backup Service application programming
  60 interface (API), also called XBSA. Support for additional
  61 XBSA-compliant programs in future releases of AFS is possible. See <A HREF="#HDRTSM">Support for Backup to TSM</A>.
  62 <P><LI>A new command and new options to existing commands. See <A HREF="#HDRCMD-CHANGES">Changes to AFS Commands, Files, and Functionality</A>.
  63 </UL>
  64 <HR><H2><A NAME="HDRSYSTYPES" HREF="aurns002.htm#ToC_8">Supported System Types</A></H2>
  65 <P>AFS supports the following system types.
  66 <BR>
  67 <TABLE WIDTH="100%">
  68 <TR>
  69 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><B>alpha_dux40</B>
  70 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%">DEC AXP system with one or more processors running Digital UNIX
  71 4.0d, 4.0e, or 4.0f
  72 </TD></TR><TR>
  73 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><B>hp_ux110</B>
  74 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%">Hewlett-Packard system with one or more processors running the 32-bit or
  75 64-bit version of HP-UX 11.0
  76 </TD></TR><TR>
  77 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><B>i386_linux22</B>
  78 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%">IBM-compatible PC with one or more processors running Linux kernel
  79 version 2.2.5-15 (the version in Red Hat Linux 6.0),
  80 2.2.10, 2.2.12, 2.2.12-20 (the
  81 version in Red Hat Linux 6.1), 2.2.13, or
  82 2.2.14
  83 </TD></TR><TR>
  84 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><B>rs_aix42</B>
  85 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%">IBM RS/6000 with one or more 32-bit or 64-bit processors running AIX
  86 4.2, 4.2.1, 4.3, 4.3.1,
  87 4.3.2, or 4.3.3
  88 </TD></TR><TR>
  89 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><B>sgi_65</B>
  90 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%">Silicon Graphics system with one or more processors running IRIX
  91 6.5 or 6.5.4. Support is provided for the
  92 following CPU board types, as reported by the IRIX <B>uname -m</B>
  93 command: IP19, IP20, IP21, IP22, IP25, IP26, IP27, IP28, IP30, IP32
  94 </TD></TR><TR>
  95 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><B>sun4x_56</B>
  96 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%">Sun SPARCstation with one or more processors running Solaris 2.6
  97 </TD></TR><TR>
  98 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="20%"><B>sun4x_57</B>
  99 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="80%">Sun SPARCstation with one or more processors running the 32-bit or 64-bit
 100 version of Solaris 7
 101 </TD></TR></TABLE>
 102 <HR><H2><A NAME="HDRHWARE_REQS" HREF="aurns002.htm#ToC_9">Hardware and Software Requirements</A></H2>
 103 <P>For a list of requirements for both server and client
 104 machines, see the chapter titled <I>Installation Overview</I> in the
 105 <I>IBM AFS Quick Beginnings</I> document.
 106 <HR><H2><A NAME="HDRDOC" HREF="aurns002.htm#ToC_10">Accessing the AFS Binary Distribution and Documentation</A></H2>
 107 <P>The AFS Binary Distribution includes a separate CD-ROM for
 108 each supported operating system, containing all AFS binaries and files for
 109 both server and client machines, plus the documentation set in multiple
 110 formats. At the top level of the CD-ROM is a directory called
 111 <B>Documentation</B> plus a directory containing the system-specific AFS
 112 binaries, named using the values listed in <A HREF="#HDRSYSTYPES">Supported System Types</A>. The CD-ROM for some operating systems has more than
 113 one system-specific directory; for example, the Solaris CD-ROM has
 114 <B>sun4x_56</B> and <B>sun4x_57</B>.
 115 <P>The instructions in <A HREF="#HDRINSTALL">Upgrading Server and Client Machines to AFS 3.6</A> specify when to mount the CD-ROM and which files or
 116 directories to copy to the local disk or into an AFS volume.
 117 <P>The documents are also available online at &lt;A
 118 HREF="http://www.transarc.com/Library/documentation/afs_doc.html"><B>http://www.transarc.com/Library/documentation/afs_doc.html</B>&lt;/A>.
 119 The documentation set includes the following documents:
 120 <UL>
 121 <P><LI><I>IBM AFS Release Notes</I> (this document)
 122 <P><LI><I>IBM AFS Administration Guide</I> (called <I>AFS System
 123 Administrator's Guide</I> in previous releases)
 124 <P><LI><I>IBM AFS Administration Reference</I> (called <I>AFS Command
 125 Reference Manual</I> in previous releases)
 126 <P><LI><I>IBM AFS Quick Beginnings</I> (called <I>AFS Installation
 127 Guide</I> in previous releases)
 128 <P><LI><I>IBM AFS User Guide</I> (called <I>AFS User's Guide</I> in
 129 previous releases)
 130 </UL>
 131 <P>Documents are provided in the following formats:
 132 <UL>
 133 <P><LI>HTML, suitable for online viewing in a Web browser or other HTML viewer
 134 <P><LI>PDF, suitable for online viewing or for printing using the Acrobat Reader
 135 program from Adobe
 136 </UL>
 137 <P>If you do not already have the Acrobat Reader program, you can download it
 138 for free at &lt;A
 139 HREF="http://www.adobe.com/products/acrobat/readstep.html"><B>http://www.adobe.com/products/acrobat/readstep.html</B>&lt;/A>.
 140 <P>Adobe provides only an English-language version of Acrobat Reader for UNIX
 141 platforms. The program can display PDF files written in any
 142 language. It is the program interface (menus, messages, and so on) that
 143 is available in English only.
 144 <P>To make Reader's interface display properly in non-English language
 145 locales, use one of two methods to set the program's language environment
 146 to English:
 147 <UL>
 148 <P><LI>Set the LANG environment variable in the Reader initialization
 149 script. The advantage of this method is that it ensures proper behavior
 150 even when Reader is launched by other applications, such as a browser or an
 151 application's Help menu. Editing the script usually requires local
 152 superuser <B>root</B> privilege, however.
 153 <P>If your Reader distribution includes the script, it is installed by
 154 convention as <VAR>AcroRead_Dir</VAR><B>/bin/acroread</B>, where
 155 <VAR>AcroRead_Dir</VAR> is the installation directory for Reader files.
 156 <P>Add the following line to the script, directly after the
 157 <TT>#!/bin/sh</TT> statement:
 158 <PRE>   LANG=C; export LANG
 159 </PRE>
 160 <P><LI>Set the LANG environment variable to the value <B>C</B> in the command
 161 shell before starting the Reader program. The following is the
 162 appropriate command for some shells.
 163 <PRE>   % <B>setenv LANG C</B>
 164 </PRE>
 165 <P>Note that this setting affects all programs started in the command shell,
 166 with possibly undesirable results if they also use the LANG variable.
 167 The preceding method affects Reader only.
 168 </UL>
 169 <HR><H2><A NAME="HDRLIMITS" HREF="aurns002.htm#ToC_11">Product Notes</A></H2>
 170 <P>The following sections summarize limitations and
 171 requirements that pertain to all system types and to individual system types,
 172 and describe revisions to the AFS documents:
 173 <UL>
 174 <P><LI><A HREF="#HDRREQ_ALL">Product Notes for All System Types</A>
 175 <P><LI><A HREF="#HDRREQ_AIX">Product Notes for AIX Systems</A>
 176 <P><LI><A HREF="#HDRREQ_DUX">Product Notes for Digital UNIX Systems</A>
 177 <P><LI><A HREF="#HDRREQ_HP">Product Notes for HP-UX Systems</A>
 178 <P><LI><A HREF="#HDRREQ_IRIX">Product Notes for IRIX Systems</A>
 179 <P><LI><A HREF="#HDRREQ_LNX">Product Notes for Linux Systems</A>
 180 <P><LI><A HREF="#HDRREQ_SOL">Product Notes for Solaris Systems</A>
 181 <P><LI><A HREF="#HDRDOC_NOTES">Documentation Notes</A>
 182 </UL>
 183 <P><H3><A NAME="HDRREQ_ALL" HREF="aurns002.htm#ToC_12">Product Notes for All System Types</A></H3>
 184 <UL>
 185 <P><LI><B>Limit on number of file server machine interfaces</B>
 186 <P>AFS supports up to 15 addresses on a multihomed file server machine.
 187 If more interfaces are configured with the operating system, AFS uses only the
 188 first 15.
 189 <P><LI><B>Limit on number of client machine interfaces</B>
 190 <P>AFS supports up to 32 addresses on a multihomed client machine. Do
 191 not configure more interfaces.
 192 <P><LI><B>Limit on number of AFS server partitions</B>
 193 <P>AFS supports up to 256 server (<B>/vicep</B>) partitions on a file
 194 server machine. This corresponds to directory names <B>/vicepa</B>
 195 through <B>/vicepz</B> and <B>/vicepaa</B> through
 196 <B>/vicepiv</B>.
 197 <P><LI><B>Limit on number of file server machines</B>
 198 <P>The VLDB can store up to 255 server entries, each representing one file
 199 server machine (single- or multihomed). This effectively determines the
 200 maximum number of file server machines in the cell. To make room in the
 201 VLDB for new server entries, use the <B>vos changeaddr</B> command's
 202 <B>-remove</B> argument to remove the entries for decommissioned file
 203 server machines.
 204 <P><LI><B>Limit on file size</B>
 205 <P>AFS supports a maximum file size of 2 GB.
 206 <P><LI><B>Limit on volume and partition size</B>
 207 <P>AFS supports a maximum volume size of 8 GB. In AFS version
 208 3.5 and earlier, the limit is 2 GB. There is no limit on
 209 partition size other than the one imposed by the operating system.
 210 <P><LI><B>Limit on cache size</B>
 211 <P>AFS supports a maximum disk cache size of 1 GB. In AFS version
 212 3.1 and earlier, the limit is 700 MB.
 213 <P><LI><B>Limit on number of File Server threads</B>
 214 <P>The File Server (<B>fileserver</B> process) can use up to 128 threads,
 215 unless the operating system imposes a lower limit. Testing for the AFS
 216 3.6 GA release indicates that HP-UX sometimes imposes a lower limit,
 217 depending on the resources available on a machine. See <A HREF="#HDRREQ_HP">Product Notes for HP-UX Systems</A>.
 218 <P>The File Server always reserves seven threads for special uses, so the
 219 maximum effective value for the <B>fileserver</B> command's
 220 <B>-p</B> argument is seven less than the actual limit. On most
 221 systems, the effective maximum is therefore <B>121</B>.
 222 <P><LI><B>Limit on number of volume site definitions</B>
 223 <P>The VLDB entry for a volume can accommodate a maximum of 13 site
 224 definitions. The site housing the read/write and backup versions of the
 225 volume counts as one site, and each read-only site counts as an additional
 226 site (even the read-only site defined on the same partition as the read/write
 227 site counts as a separate site).
 228 <P><LI><B>No support for VxFS as server or cache partition</B>
 229 <P>AFS does not support use of the VxFS file system as either a client cache
 230 partition or server (<B>/vicep</B>) partition. It is acceptable to
 231 use both VxFS and AFS on the same machine, but the cache partition and all AFS
 232 server partitions must use a supported file system type such as UFS.
 233 See the following sections of this document for similar restrictions affecting
 234 particular operating systems.
 235 <P><LI><B>Run same version of a server process on all server machines</B>
 236 <P>For predictable performance, run the same version of an AFS server process
 237 on all server machines in a cell. For example, if you upgrade the
 238 Volume Location Server process on a database server machine to AFS 3.6,
 239 you must upgrade it on all of them. The upgrade instructions in <A HREF="#HDRINSTALL">Upgrading Server and Client Machines to AFS 3.6</A> have you upgrade the binaries for all server processes on
 240 all machines to the same version, and in general that is the best
 241 policy. Unless otherwise noted, it is acceptable to run different build
 242 levels of a major version on different machines (for example, AFS 3.5
 243 build 3.0 on one machine and AFS 3.5 build 3.11 on
 244 another).
 245 <P><LI><B>Single edition of AFS for all countries</B>
 246 <P>There is a single edition of AFS 3.6 for both North American and
 247 international customers. For details, see <A HREF="#HDRSUMMARY">Summary of New Features</A>.
 248 <P><LI><B>TSM is the supported XBSA server</B>
 249 <P>The AFS 3.6 Backup System can communicate with one XBSA server, the
 250 Tivoli Storage Manager (TSM). There are several requirements and
 251 limitations associated with its use, as detailed in <A HREF="#HDRTSM_REQ">Product Notes for Use of TSM</A>.
 252 <P><LI><B>Use Netscape 4.0 or higher</B>
 253 <P>If using a Netscape browser to read the HTML version of an AFS document,
 254 use version 4.0 or higher. Some fonts used in the documents
 255 possibly do not display properly in earlier versions.
 256 <P><LI><B>Set the Acrobat Reader environment to English</B>
 257 <P>The user interface to the Adobe Acrobat Reader program for displaying PDF
 258 files works correctly only when the program's language environment is set
 259 to English. Users in non-English language locales probably need to
 260 adjust the language setting. See <A HREF="#HDRDOC">Accessing the AFS Binary Distribution and Documentation</A>.
 261 <P><LI><B>No support for IPv6</B>
 262 <P>AFS does not support version 6 of the Internet Protocol (IPv6). You
 263 must continue to specify the IPv4 protocol names <TT>udp</TT> and
 264 <TT>tcp</TT> in the entries for AFS-modified services in the
 265 <B>inetd</B> configuration file, rather than the IPv6 names
 266 <TT>upd6</TT> and <TT>tcp6</TT>. If you use the IPv6 version, the
 267 AFS-modified <B>inetd</B> daemon cannot locate the service and does not
 268 open the service's port.
 269 <P>The <B>inetd</B> configuration file included with some operating system
 270 revisions possibly specifies IPv6 protocols by default. You must modify
 271 or replace the file in order to use the AFS-modified version of remote
 272 services.
 273 <P><LI><B>Limit on directory size when element names are long</B>
 274 <P>If the name of every file system element (file, link, or subdirectory) in a
 275 directory is 16 characters or more, then when there are about 31,700 elements
 276 it becomes impossible to create any more elements with long names. It
 277 is still possible to create elements with names shorter than 16
 278 characters. This limitation is due to the way AFS implements
 279 directories. For a more detailed explanation, contact your AFS product
 280 support representative.
 281 <P><LI><B>Setting setuid or setgid bit on file fails silently</B>
 282 <P>Only members of the <B>system:administrators</B> group can turn
 283 on the setuid or setgid mode bit on an AFS file or directory. However,
 284 AFS generates an error message only when a regular user attempts to set the
 285 bit on a directory. Attempts on a file fail silently.
 286 <P><LI><B>The add instruction in the uss bulk input file does not work as
 287 documented</B>
 288 <P>The documentation specifies the following syntax for creating an
 289 authentication-only account (entries in the Authentication and Protection
 290 Databases only) by using an <B>add</B> instruction in the <B>uss</B>
 291 bulk template file:
 292 <PRE>   add <VAR>username</VAR>[:]
 293 </PRE>
 294 <P>However, you must in fact follow the <VAR>username</VAR> value with two
 295 colons for the <B>uss bulk</B> command to create the account:
 296 <PRE>   add <VAR>username</VAR>::
 297 </PRE>
 298 <P><LI><B>Running the backup savedb command blocks other Backup System
 299 operations</B>
 300 <P>The Backup Server locks the Backup Database as it performs the <B>backup
 301 savedb</B> command, which can take a long time. Because other backup
 302 operations cannot access the database during this time, they appear to
 303 hang. Avoid running other backup operations after issuing the
 304 <B>backup savedb</B> command.
 305 <P>Actually, this limitation applies to any operation that locks the Backup
 306 Database for a significant amount of time, but most other operations do
 307 not. In any case, running the <B>backup savedb</B> command is
 308 appropriate only in the rare case when the Backup Database is corrupted, so
 309 this limitation usually does not have a significant impact.
 310 <P><LI><B>NFS/AFS Translator sometimes performs poorly under heavy load</B>
 311 <P>The NFS/AFS Translator does not always perform well under heavy
 312 load. Sometimes the translator machine hangs, and sometimes NFS client
 313 machines display the following error message.
 314 <PRE>   NFS Stale File Handle
 315 </PRE>
 316 <P><LI><B>Sample files for package program not included</B>
 317 <P>The AFS distribution does not include the sample files referred to in the
 318 chapter of the <I>IBM AFS Administration Guide</I> about the
 319 <B>package</B> program (the files formerly installed by convention in the
 320 <B>etc</B>, <B>lib</B>, and <B>src</B> subdirectories of the
 321 <B>/afs/</B><VAR>cellname</VAR><B>/wsadmin</B> directory).
 322 <I>IBM AFS Quick Beginnings</I> therefore does not include instructions
 323 for installing the sample files. If you wish to use the
 324 <B>package</B> program and the discussion in the <I>IBM AFS
 325 Administration Guide</I> is not sufficient to guide you, contact your AFS
 326 product support representative for assistance.
 327 </UL>
 328 <P><H3><A NAME="HDRREQ_AIX" HREF="aurns002.htm#ToC_13">Product Notes for AIX Systems</A></H3>
 329 <UL>
 330 <P><LI><B>The klog command's -setpag flag is supported on AIX
 331 4.2.1 and 4.3.3 only</B>
 332 <P>To use the <B>klog</B> command's <B>-setpag</B> flag, you must
 333 install the indicated AIX APAR (Authorized Program Analysis Report), available
 334 from IBM, on a machine running the indicated AIX version:
 335 <UL>
 336 <P><LI>APAR IY07834 on AIX 4.2.1 machines
 337 <P><LI>APAR IY07835 on AIX 4.3.3 machines
 338 </UL>
 339 <P>To determine if the APAR is installed, issue the following command:
 340 <PRE>   % <B>instfix -i -k</B> <VAR>APAR_identifier</VAR>
 341 </PRE>
 342 <P>IBM provides an APAR for the indicated (latest) AIX versions only.
 343 Therefore, the <B>-setpag</B> flag does not work correctly on machines
 344 running the base level of AIX 4.2 or 4.3, or AIX
 345 4.3.1 or 4.3.2.
 346 <P><LI><B>Change to AFS installation procedure for AIX
 347 4.3.3</B>
 348 <P>If version 4.3.3.0 or higher of the AIX
 349 <B>bos.rte.security</B> fileset is installed (usually true
 350 on a machine using the AIX 4.3.3 kernel), you must modify the
 351 procedure documented in <I>IBM AFS Quick Beginnings</I> for enabling
 352 integrated AFS login. Instead of editing the
 353 <B>/etc/security/login.cfg</B> file, you edit the
 354 <B>/usr/lib/security/methods.cfg</B> file.
 355 <P>To determine which version of the <B>bos.rte.security</B>
 356 fileset is installed, issue the following command:
 357 <PRE>   # <B>lslpp -L bos.rte.security</B>
 358 </PRE>
 359 <P>The change affects Step 3 in the section titled <I>Enabling AFS Login on
 360 AIX Systems</I> in each of two chapters in <I>IBM AFS Quick
 361 Beginnings</I>: <I>Installing the First AFS Machine</I> and
 362 <I>Installing Additional Client Machines</I>. For the complete text
 363 of the modified step, see <A HREF="#HDRDOC_NOTES">Documentation Notes</A>.
 364 <P><LI><B>No support for the NFS/AFS Translator with base level of AIX
 365 4.2</B>
 366 <P>AFS does not support the use of machines running the base level of AIX
 367 4.2 as NFS/AFS Translator machines. The AFS distribution does
 368 not include the required kernel extensions file, formerly installed by
 369 convention as
 370 <B>/usr/vice/etc/dkload/afs.ext.trans</B>. Do not set
 371 the NFS variable to the value <B>$NFS_NFS</B> in the AFS initialization
 372 script (by convention, <B>/etc/rc.afs</B>).
 373 <P>Machines running AIX 4.2.1 and higher are supported as
 374 NFS/AFS Translator machines. They use the
 375 <B>afs.ext.iauth</B> kernel extensions file instead.
 376 <P><LI><B>NFS/AFS Translator cannot coexist with NFS/DFS Gateway</B>
 377 <P>A machine running AIX 4.2.1 or higher cannot act as both an
 378 NFS/AFS Translator and a NFS/DFS Gateway Server at the same time, because both
 379 translation protocols must have exclusive access to the AIX <B>iauth</B>
 380 interface. An attempt by either file system to access the
 381 <B>iauth</B> interface when the other file system is already using it
 382 fails with an error message.
 383 <P><LI><B>No support for NFS Version 3 software on NFS clients</B>
 384 <P>Do not run NFS Version 3 software on NFS client machines that use an
 385 NFS/AFS Translator machine running AIX. The NFS3 client software uses
 386 the <B>readdir+</B> NFS command on directories, which can cause excessive
 387 volume lookups on the translator machine. This can lead to timeouts,
 388 especially when used in the <B>/afs</B> directory or other directories
 389 with many volume mount points. Use NFS Version 2 instead.
 390 <P><LI><B>No support for Large File Enabled Journalled File System as AFS
 391 server partition</B>
 392 <P>AFS does not support use of AIX's Large File Enabled Journalled File
 393 System as an AFS server (<B>/vicep</B>) partition. If you configure
 394 a partition that uses that file system as an AFS server partition, the File
 395 Server ignores it and writes the following message to the
 396 <B>/usr/afs/logs/FileLog</B> file:
 397 <PRE>   /vicep<VAR>xx</VAR> is a big files filesystem, ignoring it
 398 </PRE>
 399 <P>AFS supports use of the Large File Enabled Journalled File System as the
 400 cache partition on a client machine.
 401 <P><LI><B>PASSWORD_EXPIRES variable not set on AIX</B>
 402 <P>The AIX secondary authentication system does not support setting the
 403 PASSWORD_EXPIRES environment variable during login.
 404 <P><LI><B>The chuser, chfn and chsh commands are inoperative</B>
 405 <P>The <B>chuser</B>, <B>chfn</B>, and <B>chsh</B> commands are
 406 inoperative on AFS machines running AIX. AFS authentication uses the
 407 AIX secondary authentication system, and sets the <TT>registry</TT> variable
 408 in the <B>/etc/security/user</B> file to <TT>DCE</TT> for the default
 409 user. That is, the setting is
 410 <PRE>   registry = DCE
 411 </PRE>
 412 <P>as described in the sections of <I>IBM AFS Quick Beginnings</I> that
 413 discuss enabling AFS login on AIX systems. However, when the
 414 <TT>registry</TT> variable has any value other than <TT>registry =
 415 files</TT>, AIX does not allow edits to <B>/etc/passwd</B> and related
 416 files, and so disallows the <B>chuser</B>, <B>chfn</B> and
 417 <B>chsh</B> commands. Attempts to edit entries by running these
 418 commands on the command line result in error messages like the
 419 following.
 420 <UL>
 421 <P><LI>From the <B>chuser</B> command:
 422 <PRE>   You can only change the HOME directory on the name server.
 423 </PRE>
 424 <P><LI>From the <B>chfn</B> command:
 425 <PRE>   You can only change the User INFORMATION on the name server.
 426 </PRE>
 427 <P><LI>From the <B>chsh</B> command:
 428 <PRE>   You can only change the Initial PROGRAM on the name server.
 429 </PRE>
 430 </UL>
 431 <P>From within SMIT, using the <B>chuser</B> function results in an error
 432 message like the following:
 433 <P>
 434 <PRE>    3004-716: You can only change the HOME directory on the name server
 435 </PRE>
 436 <P>It is not possible for AFS Development to alter this behavior, because AIX
 437 imposes the restriction. Sites that wish to run these commands must
 438 develop a solution appropriate for their needs.
 439 </UL>
 440 <P><H3><A NAME="HDRREQ_DUX" HREF="aurns002.htm#ToC_14">Product Notes for Digital UNIX Systems</A></H3>
 441 <UL>
 442 <P><LI><B>No support for the NFS/AFS Translator</B>
 443 <P>AFS does not support use of Digital UNIX machines as NFS/AFS Translator
 444 machines.
 445 <P><LI><B>No support for AdvFS as server or cache partition</B>
 446 <P>AFS does not support use of Digital UNIX's Advanced File System
 447 (AdvFS) as either a client cache partition or a server (<B>/vicep</B>)
 448 partition. It is acceptable to use both AdvFS and AFS on the same
 449 machine, but the cache partition and all AFS server partitions must be UFS
 450 partitions.
 451 <P><LI><B>No support for real-time kernel preemption or related lock
 452 modes</B>
 453 <P>AFS does not function correctly on a Digital UNIX machine when real-time
 454 preemption of system calls is enabled in the kernel. Do not enable this
 455 feature in any manner, including the following:
 456 <UL>
 457 <P><LI>By including the following statement in the <B>/usr/sys/conf/AFS</B>
 458 file:
 459 <PRE>   options RT_PREEMPT_OPT
 460 </PRE>
 461 <P><LI>By including either of the following instructions in the
 462 <B>/etc/sysconfigtab</B> file:
 463 <PRE>   rt_preempt_opt=1
 464    rt-preempt-opt=1
 465 </PRE>
 466 </UL>
 467 <P>Also, AFS does not function correctly when the value of the kernel
 468 <B>lockmode</B> option is other than <B>0</B> (zero, the default) or
 469 <B>2</B>. Lock mode values <B>1</B>, <B>3</B>, and
 470 <B>4</B> are unsupported because they imply that real-time preemption is
 471 enabled (indeed, enabling real-time preemption sets the lock mode to
 472 <B>1</B> automatically).
 473 <P><LI><B>Building AFS from source requires /usr/sys/AFS directory</B>
 474 <P>Building AFS from source for Digital UNIX requires that certain header
 475 files (such as <B>cpus.h</B>) reside in the local
 476 <B>/usr/sys/AFS</B> directory. This directory exists only if you
 477 have previously incorporated AFS modifications into the kernel of the machine
 478 on which you are performing the compilation. Otherwise, the required
 479 header files reside only in the local directory called
 480 <B>/usr/sys/</B><VAR>machine_name</VAR>.
 481 <P>If the <B>/usr/sys/AFS</B> directory does not exist, issue the
 482 following command to create it as a link:
 483 <PRE>    # <B>ln -s  /usr/sys/</B><VAR>machine_name</VAR>  <B>/usr/sys/AFS</B>
 484 </PRE>
 485 <P>When the compilation is complete, remove the link.
 486 </UL>
 487 <P><H3><A NAME="HDRREQ_HP" HREF="aurns002.htm#ToC_15">Product Notes for HP-UX Systems</A></H3>
 488 <UL>
 489 <P><LI><B>No support for the NFS/AFS Translator</B>
 490 <P>AFS does not support use of HP-UX 11.0 machines as NFS/AFS
 491 Translator machines.
 492 <P><LI><B>Upgrade kernel extensions when upgrading the File Server</B>
 493 <P>The AFS 3.6 version of the File Server uses the native HP-UX
 494 threading package. When upgrading to the new File Server on a machine
 495 that previously ran File Server version 3.5 or earlier, you must also
 496 upgrade the AFS kernel extensions to the AFS 3.6 version.
 497 <P>For instructions on upgrading server and client machines, see <A HREF="#HDRINSTALL">Upgrading Server and Client Machines to AFS 3.6</A>.
 498 <P><LI><B>Possible lower limit on number of File Server threads</B>
 499 <P>On some machines, HP-UX reduces the number of threads available to the File
 500 Server to fewer than the AFS default of 128. To determine the maximum
 501 number of threads available to the File Server (or any single process) on an
 502 HP-UX machine, issue the following command:
 503 <PRE>   % <B>getconf _SC_THREAD_THREADS_MAX</B>
 504 </PRE>
 505 <P>As on other system types, the HP-UX File Server reserves seven threads for
 506 special uses, so the maximum effective value for the <B>fileserver</B>
 507 command's <B>-p</B> argument is seven less than the number reported
 508 by the <B>getconf</B> command.
 509 <P><LI><B>PAM can succeed inappropriately when pam_dial_auth module is
 510 optional</B>
 511 <P>For AFS authentication to work correctly for a service, all entries for the
 512 service in the HP-UX PAM configuration file (<B>/etc/pam.conf</B>
 513 by convention) must have the value <TT>optional</TT> in the third field, as
 514 specified in <I>IBM AFS Quick Beginnings</I>. However, when you
 515 make the <B>login</B> entry that invokes the <B>pam_dial_auth</B>
 516 module optional in this way, it can mean that PAM succeeds (the user can
 517 login) even when the user does not meet all of the <B>pam_dial_auth</B>
 518 module's requirements. This is not usually considered
 519 desirable.
 520 <P>If you do not use dial-up authentication, comment out or remove the entry
 521 for the <B>login</B> service that invokes the <B>pam_dial_auth</B>
 522 module. If you do use dial-up authentication, you must develop a
 523 configuration that meets your needs; consult the HP-UX documentation for
 524 PAM and the <B>pam_dial_auth</B> module.
 525 <P><LI><B>HP patch PHCO_18572 enables PAM to change to home directory</B>
 526 <P>You must install Hewlett-Packard patch PHCO_18572 to enable HP-UX's
 527 standard PAM to change to a user's home directory during login.
 528 The patch is accessible for download via the UNIX File Transfer Protocol
 529 (<B>ftp</B>) at the following address:
 530 <DL>
 531 <DD><P><B>ftp://hpatlse.atl.hp.com/hp-ux_patches/s700_800/11.X/PHCO_18572</B>
 532 </DL>
 533 <P>The patch is also available from HP Electronic Support Centers at the
 534 following URLs.
 535 <UL>
 536 <P><LI>In the Americas and Asia Pacific: &lt;A
 537 HREF="http://us-support.external.hp.com"><B>http://us-support.external.hp.com</B>&lt;/A>
 538 <P><LI>In Europe: &lt;A
 539 HREF="http://europe-support.external.hp.com"><B>http://europe-support.external.hp.com</B>&lt;/A>
 540 </UL>
 541 </UL>
 542 <P><H3><A NAME="HDRREQ_IRIX" HREF="aurns002.htm#ToC_16">Product Notes for IRIX Systems</A></H3>
 543 <UL>
 544 <P><LI><B>kdump program does not work with dynamically loaded kernels</B>
 545 <P>The AFS kernel dump program, <B>kdump</B>, cannot retrieve kernel
 546 information from an IRIX system on which the dynamic kernel loader,
 547 <B>ml</B>, was used to load AFS extensions. The <B>kdump</B>
 548 program can read only static kernels into which AFS is built.
 549 <P><LI><B>No AFS-modified remote commands</B>
 550 <P>The AFS distribution for IRIX machines does not include AFS-modified
 551 versions of any of the remote (<B>r*</B>) commands except
 552 <B>inetd.afs</B>. Silicon Graphics has already modified the
 553 IRIX versions of the remote commands to be compatible with AFS.
 554 <P><LI><B>Do not run the fsr program</B>
 555 <P>Do not run the IRIX File System Reorganizer (<B>fsr</B> program) on a
 556 client cache partition (<B>/usr/vice/cache</B> directory or equivalent) or
 557 AFS server partition (<B>/vicep</B> directory). The program can
 558 corrupt or remove AFS data.
 559 <P><LI><B>The timed daemon runs by default</B>
 560 <P>The IRIX 6.5 distribution includes and starts the <B>timed</B>
 561 time-synchronization daemon by default. If you want to use the
 562 <B>runntp</B> program and the Network Time Protocol Daemon (NTPD) on AFS
 563 server machines, as documented in <I>IBM AFS Quick Beginnings</I>, issue
 564 the following commands. They disable the <B>timed</B> daemon and
 565 remove it from the machine's startup sequence.
 566 <PRE>   # <B>/etc/chkconfig -f timed off</B>
 567
 568    # <B>/sbin/killall timed</B>
 569 </PRE>
 570 <P><LI><B>Default login program does not grant AFS tokens</B>
 571 <P>The IRIX 6.5 distribution includes the <B>clogin</B> program as
 572 the default login utility. This graphical utility does not grant AFS
 573 tokens. If you want your users to obtain tokens during login, you must
 574 disable the <B>clogin</B> program and substitute either the standard
 575 command-line <B>login</B> program or the <B>xdm</B> graphical login
 576 utility, both of which grant AFS tokens if AFS modifications have been
 577 incorporated into the kernel. Issue the following command to disable
 578 the <B>clogin</B> program.
 579 <PRE>   # <B>/etc/chkconfig -f visuallogin off</B>
 580 </PRE>
 581 </UL>
 582 <P><H3><A NAME="HDRREQ_LNX" HREF="aurns002.htm#ToC_17">Product Notes for Linux Systems</A></H3>
 583 <UL>
 584 <P><LI><B>Supported kernel versions</B>
 585 <P>The General Availability release of AFS 3.6 supports Red Hat
 586 Software's Linux 6.0 (which incorporates kernel version
 587 2.2.5-15) and Linux 6.1 (which incorporates kernel
 588 version 2.2.12-20). The distribution also includes
 589 AFS kernel extensions for kernel versions 2.2.10,
 590 2.2.12, 2.2.13, and 2.2.14.
 591 The AFS initialization script included in the AFS 3.6 distribution
 592 automatically selects the appropriate kernel extensions for the kernel version
 593 in use on the local machine.
 594 <P>Red Hat Linux 6.0 and 6.1 include a compiled kernel, but for
 595 the other supported kernel versions you must obtain kernel source and compile
 596 the kernel yourself. In this case, you must use version
 597 2.7.2.3 or higher of the <B>gcc</B> program, which is
 598 part of the Linux distribution. Do not use other compilers.
 599 <P>The Linux kernel-building tools by default create a symmetric
 600 multiprocessor (SMP) kernel, which can run on both uniprocessor and
 601 multiprocessor machines. However, a uniprocessor machine generally
 602 performs best with a uniprocessor kernel.
 603 <P>You can obtain Linux kernel source via the UNIX File Transfer Protocol
 604 (<B>ftp</B>) at <B>ftp.kernel.org</B> or one of its
 605 mirror sites. There is also kernel upgrade information at &lt;A
 606 HREF="http://www.kernel.org"><B>http://www.kernel.org</B>&lt;/A>.
 607 <P><LI><B>AFS requires libc6</B>
 608 <P>For correct AFS performance, the operating system must use the C library
 609 called <B>libc6</B> (or <B>glibc2</B>), rather than <B>libc5</B>
 610 (<B>glibc1</B>).
 611 <P><LI><B>Modified insmod program required with some kernels</B>
 612 <P>If using an SMP kernel or a uniprocessor kernel configured to use more than
 613 1 GB of memory, you must use a modified version of the <B>insmod</B>
 614 program. You do not need the modified program if using a standard
 615 uniprocessor kernel.
 616 <P>You can download the modified <B>insmod</B> program at the following
 617 URLs:
 618 <UL>
 619 <P><LI>&lt;A
 620 HREF="http://www.transarc.com/Support/afs/index.html"><B>http://www.transarc.com/Support/afs/index.html</B>&lt;/A>.
 621 See the <B>Downloads</B> section of the page. To comply with the
 622 GNU Public License (GPL), the download site also makes available the complete
 623 modified <B>insmod.c</B> source file and a source-code patch
 624 against the original <B>insmod.c</B> file.
 625 <P><LI>&lt;A
 626 HREF="http://www.pi.se/blox/modutils/index.html"><B>http://www.pi.se/blox/modutils/index.html</B>&lt;/A>.
 627 Select the file listed at the top of the index. This is a site for
 628 Linux <B>modutils</B> source code.
 629 </UL>
 630 <P><LI><B>No support for the NFS/AFS Translator</B>
 631 <P>AFS does not support the use of Linux machines as NFS/AFS Translator
 632 machines.
 633 <P><LI><B>No AuthLog database</B>
 634 <P>The Authentication Server running on a Linux machine creates and writes
 635 messages to the <B>/usr/afs/logs/AuthLog</B> file, just as on other system
 636 types. However, it does not create or use the two files which
 637 constitute the auxiliary AuthLog database on other system types
 638 (<B>AuthLog.dir</B> and <B>AuthLog.pag</B>). The
 639 <B>kdb</B> command is therefore inoperative on Linux machines. The
 640 auxiliary database is useful mostly for debugging and is not required for
 641 normal operations.
 642 <P><LI><B>Curses utility required for monitoring programs</B>
 643 <P>For the <B>afsmonitor</B>, <B>scout</B> and <B>fms</B> programs
 644 to work properly, the dynamic library <B>/usr/lib/libncurses.so</B>
 645 must be installed on the machine. It is available in most Linux
 646 distributions.
 647 </UL>
 648 <P><H3><A NAME="HDRREQ_SOL" HREF="aurns002.htm#ToC_18">Product Notes for Solaris Systems</A></H3>
 649 <UL>
 650 <P><LI><B>Different location for 64-bit Solaris 7 kernel extensions</B>
 651 <P>
 652 <P>As noted in <A HREF="#HDRINSTALL">Upgrading Server and Client Machines to AFS 3.6</A>, the 64-bit version of Solaris 7 uses a different
 653 location for kernel extension library files than previous versions of
 654 Solaris: <B>/kernel/fs/sparcv9/afs</B>. The 32-bit
 655 version of Solaris 7 uses the same location as Solaris 2.6,
 656 <B>/kernel/fs/afs</B>.
 657 <P><LI><B>SunSoft Patch 106541 for Solaris 7 replaces the /sbin/mountall
 658 script</B>
 659 <P>As part of replacing the standard <B>fsck</B> program on an AFS file
 660 server machine that runs Solaris, you make two changes in the
 661 <B>/sbin/mountall</B> script. If you use Solaris 7 and apply
 662 SunSoft Patch 10654, it replaces the <B>/sbin/mountall</B> script.
 663 This has two implications:
 664 <OL TYPE=1>
 665 <P><LI>If you apply the patch on an existing file server machine, the changes you
 666 already made in the <B>/sbin/mountall</B> script are overwritten.
 667 You must make the changes again in the new (replacement) script.
 668 <P><LI>In the replacement script, the appearance of one of the sections of code
 669 that you must alter is different than in the original script and as specified
 670 in <I>IBM AFS Quick Beginnings</I>.
 671 </OL>
 672 <P>For more details, see <A HREF="#HDRDOC_NOTES">Documentation Notes</A>.
 673 <P><LI><B>PAM can succeed inappropriately when pam_dial_auth module is
 674 optional</B>
 675 <P>For AFS authentication to work correctly for a service, all entries for the
 676 service in the Solaris PAM configuration file (<B>/etc/pam.conf</B>
 677 by convention) must have the value <TT>optional</TT> in the third field, as
 678 specified in <I>IBM AFS Quick Beginnings</I>. However, when you
 679 make the <B>login</B> entry that invokes the <B>pam_dial_auth</B>
 680 module optional in this way, it can mean that PAM succeeds (the user can
 681 login) even when the user does not meet all of the <B>pam_dial_auth</B>
 682 module's required conditions. This is not usually considered
 683 desirable.
 684 <P>If you do not use dial-up authentication, comment out or remove the entry
 685 for the <B>login</B> service that invokes the <B>pam_dial_auth</B>
 686 module. If you do use dial-up authentication, you must develop a
 687 configuration that meets your needs; consult the Solaris documentation
 688 for PAM and the <B>pam_dial_auth</B> module.
 689 <P>The AFS Development group has filed a Request for Enhancement (RFE
 690 #4122186) with SunSoft for a design change that eliminates this problem with
 691 the <B>pam_dial_auth</B> module. There is no projected solution
 692 date. For further information, contact your AFS product support
 693 representative.
 694 <P><LI><B>Solaris 2.6 patches are required for CDE</B>
 695 <P>There were several defects in the initial release of the Solaris 2.6
 696 implementation of the Common Desktop Environment (CDE). They prevented
 697 integrated AFS login from working consistently under CDE. SunSoft now
 698 provides patches that correct the problems. You must install them in
 699 order to obtain support for use of CDE from your AFS product support
 700 representative.
 701 <UL>
 702 <P><LI>If using version 1.2 of the Solaris CDE, install SunSoft patches
 703 105703-03 and 106027-01 (or later revisions).
 704 <P><LI>If using version 1.3 of the Solaris CDE, which is included on the
 705 SDE CD-ROM, install SunSoft patch 106661-04 (or a later
 706 revision).
 707 </UL>
 708 <P>Use the following command to determine which version of CDE you are
 709 running:
 710 <PRE>   % <B>pkginfo  -l  SUNWdtdte</B>
 711 </PRE>
 712 </UL>
 713 <P><H3><A NAME="HDRDOC_NOTES" HREF="aurns002.htm#ToC_19">Documentation Notes</A></H3>
 714 <UL>
 715 <P><LI><B>Instructions for international edition of AFS are obsolete</B>
 716 <P>As noted in <A HREF="#HDRSUMMARY">Summary of New Features</A>, the <I>IBM AFS Administration Guide</I> and <I>IBM
 717 AFS Administration Reference</I> distinguish between United States and
 718 international editions of AFS, because the documents were produced before a
 719 relaxation of United States government export restrictions. AFS
 720 3.6 includes just one edition. AFS customers in any country can
 721 ignore the documented distinction between editions and use the United States
 722 instructions if they choose.
 723 <P><LI><B>Clarification on obtaining technical support</B>
 724 <P>The AFS documents refer you to the <I>AFS Product Support group</I> for
 725 technical assistance with AFS problems and questions. This is intended
 726 to be a generic term. To learn how to obtain technical support, consult
 727 your AFS license agreement or other materials from your AFS vendor.
 728 <P><LI><B>Change to</B> <I>IBM AFS Quick Beginnings</I> <B>instructions
 729 for enabling AFS login on AIX machines</B>
 730 <P>If version 4.3.3.0 or higher of the AIX
 731 <B>bos.rte.security</B> fileset is installed (usually true
 732 on a machine using the AIX 4.3.3 kernel), edit the
 733 <B>/usr/lib/security/methods.cfg</B> file instead of the
 734 <B>/etc/security/login.cfg</B> file as documented in <I>IBM AFS
 735 Quick Beginnings</I>.
 736 <P>The change affects Step 3 in the section titled <I>Enabling AFS Login on
 737 AIX Systems</I> in each of two chapters in <I>IBM AFS Quick
 738 Beginnings</I>: <I>Installing the First AFS Machine</I> and
 739 <I>Installing Additional Client Machines</I>. The corrected text
 740 follows.
 741 <P>
 742 <P>Create or edit the <TT>DCE</TT> and <TT>AFS</TT> stanzas in one of two
 743 files on the local disk:
 744 <UL>
 745 <P><LI>The <B>/usr/lib/security/methods.cfg</B> file, if version
 746 4.3.3.0 or higher of the AIX
 747 <B>bos.rte.security</B> fileset is installed on the machine
 748 (usually true on a machine using the AIX 4.3.3 kernel)
 749 <P><LI>The <B>/etc/security/login.cfg</B> file, if an earlier version
 750 of the fileset is installed
 751 </UL>
 752 <P>Edit the stanzas as follows:
 753 <UL>
 754 <P><LI>In the <TT>DCE</TT> stanza, set the <TT>program</TT> attribute as
 755 indicated.
 756 <P>If you use the AFS Authentication Server (<B>kaserver</B>
 757 process):
 758 <PRE>   DCE:
 759         program = /usr/vice/etc/afs_dynamic_auth
 760 </PRE>
 761 <P>If you use a Kerberos implementation of AFS authentication:
 762 <PRE>   DCE:
 763         program = /usr/vice/etc/afs_dynamic_kerbauth
 764 </PRE>
 765 <P><LI>In the <TT>AFS</TT> stanza, set the <TT>program</TT> attribute as
 766 indicated.
 767 <P>If you use the AFS Authentication Server (<B>kaserver</B>
 768 process):
 769 <PRE>   AFS:
 770         program = /usr/vice/etc/afs_dynamic_auth
 771 </PRE>
 772 <P>If you use a Kerberos implementation of AFS authentication:
 773 <PRE>   AFS:
 774         program = /usr/vice/etc/afs_dynamic_kerbauth
 775 </PRE>
 776 </UL>
 777 <P><LI><B>Change to</B> <I>IBM AFS Quick Beginnings</I> <B>instructions
 778 for replacing Solaris fsck program</B>
 779 <P>In two sections of <I>IBM AFS Quick Beginnings</I>, there are
 780 instructions for editing the <B>/sbin/mountall</B> script on Solaris
 781 machines as part of replacing the standard <B>fsck</B> program. The
 782 two sections are <I>Configuring the AFS-modified fsck Program on Solaris
 783 Systems</I> in the chapter about the first AFS machine and <I>Getting
 784 Started on Solaris Systems</I> in the chapter about additional server
 785 machines.
 786 <P>If you use Solaris 7 and apply SunSoft Patch 10654, it replaces the
 787 <B>/sbin/mountall</B> script. In the replacement script, the
 788 appearance of one of the sections of code that you must alter is different
 789 than in the original script and as specified in <I>IBM AFS Quick
 790 Beginnings</I>, which is as follows:
 791 <PRE>   # For fsck purposes, we make a distinction between ufs and
 792    # other file systems
 793    #
 794    if [ "$fstype" = "ufs" ]; then
 795         ufs_fscklist="$ufs_fscklist $fsckdev"
 796         saveentry $fstype "$OPTIONS" $special $mountp
 797         continue
 798    fi
 799 </PRE>
 800 <P>In the replacement script, the code is instead similar to the
 801 following:
 802 <PRE>   # For fsck purposes, we make a distinction between ufs and
 803    # other file systems.  Here we check that the file system is
 804    # not mounted using fsck -m before adding it to the list to
 805    # be checked
 806    #
 807    if [ "$fstype" = "ufs" ]; then
 808         /usr/sbin/fsck -m -F $fstype $fsckdev >/dev/null 2>&amp;1
 809         if [ $? != 33 ]; then
 810                 ufs_fscklist="$ufs_fscklist $fsckdev"
 811                 saveentry $fstype "$OPTIONS" $special $mountp
 812                 continue
 813         else
 814                 echo "$fsckdev already mounted"
 815                 continue
 816         fi
 817    fi
 818
 819 </PRE>
 820 <P>You still need to change the first <TT>if</TT> statement (the one
 821 directly after the comment) to check for both the UFS and AFS file system
 822 types, as specified in <I>IBM AFS Quick Beginnings</I>:
 823 <PRE>   if [ "$fstype" = "ufs" -o "$fstype" = "afs" ]; then
 824 </PRE>
 825 <P><LI><B>Correction to</B> <I>IBM AFS Quick Beginnings</I>
 826 <B>instructions for accessing AFS documents</B>
 827 <P>The section of <I>IBM AFS Quick Beginnings</I> titled <I>Storing AFS
 828 Documents in AFS</I> (in the chapter about the first AFS machine)
 829 incorrectly describes the organization of the top-level
 830 <B>Documentation</B> directory on the AFS CD-ROM. It states that
 831 there is a subdirectory for each document format. Instead, there is a
 832 subdirectory for each language in which the documents are available, named
 833 using the following codes:
 834 <DL>
 835 <DD><P><B>de_DE</B> for German
 836 <DD><P><B>en_US</B> for United States English
 837 <DD><P><B>es_ES</B> for Spanish
 838 <DD><P><B>ko_KR</B> for Korean
 839 <DD><P><B>pt_BR</B> for Brazilian Portuguese
 840 <DD><P><B>zh_CN</B> for Simplified Chinese
 841 <DD><P><B>zh_TW</B> for Traditional Chinese
 842 </DL>
 843 <P>In each language directory is a subdirectory for each available document
 844 format. In each format directory is a subdirectory for each
 845 document. For example, the path on the CD-ROM to the English-language
 846 HTML version of the <I>IBM AFS Quick Beginnings</I> is
 847 <B>Documentation/en_US/HTML/QkBegin</B>.
 848 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">Not all documents are available in every language, as determined by the IBM
 849 translation center responsible for each language. All documents are
 850 available in English.
 851 </TD></TR></TABLE>
 852 <P>Assuming that you want to install the documentation for one language only,
 853 substitute the following text for Step 5 in the instructions in <I>Storing
 854 AFS Documents in AFS</I>:
 855 <P>
 856 <P>Copy the AFS documents in one or more formats from the CD-ROM into
 857 subdirectories of the <B>/afs/</B><VAR>cellname</VAR><B>/afsdoc</B>
 858 directory. Repeat the commands for each format.
 859 <PRE>   # <B>mkdir</B> <VAR>format_name</VAR>
 860
 861    # <B>cd</B> <VAR>format_name</VAR>
 862
 863    # <B>cp -rp /cdrom/Documentation/</B><VAR>language_code</VAR><B>/</B><VAR>format</VAR>  <B>.</B>
 864 </PRE>
 865 <P>If you choose to store the HTML version of the documents in AFS, note that
 866 in addition to a subdirectory for each document there are several files with a
 867 <B>.gif</B> extension, which enable readers to move easily between
 868 sections of a document. The file called <B>index.htm</B> is
 869 an introductory HTML page that contains a hyperlink to each of the
 870 documents. For online viewing to work properly, these files must remain
 871 in the top-level HTML directory (the one named, for example,
 872 <B>/afs/</B><VAR>cellname</VAR><B>/afsdoc/HTML</B>).
 873 <P><LI><B>Revised reference page for NetRestrict files</B>
 874 <P>The <I>IBM AFS Administration Guide</I> and <I>IBM AFS Administration
 875 Reference</I> incorrectly state that the value <B>255</B> acts as a
 876 wildcard in IP addresses that appear in the <B>NetRestrict</B> file
 877 (client or server version). Wildcarding does not work and is not
 878 supported. For corrected documentation, see <A HREF="#HDRCLI_NETRESTRICT">NetRestrict (client version)</A> and <A HREF="#HDRSV_NETRESTRICT">NetRestrict (server version)</A>.
 879 <P><LI><B>Revised reference pages for backup commands and configuration
 880 file</B>
 881 <P>The <I>IBM AFS Administration Guide</I> and <I>IBM AFS Administration
 882 Reference</I> do not document the interoperation of the AFS Backup System
 883 and the Tivoli Storage Manager (TSM), because support for TSM was added after
 884 the documents were produced.
 885 <P>For a complete description of the new TSM-related features and
 886 configuration procedures, see <A HREF="#HDRTSM">Support for Backup to TSM</A> and the indicated reference pages:
 887 <DL>
 888 <DD><P><A HREF="#HDRBK_DELETEDUMP">backup deletedump</A>
 889 <DD><P><A HREF="#HDRBK_DUMPINFO">backup dumpinfo</A>
 890 <DD><P><A HREF="#HDRBK_STATUS">backup status</A>
 891 <DD><P><A HREF="#HDRCFG">CFG_<I>tcid</I></A>
 892 </DL>
 893 <P><LI><B>Revised reference page for vos delentry command</B>
 894 <P>The <I>IBM AFS Administration Guide</I> and <I>IBM AFS Administration
 895 Reference</I> incorrectly state that the <B>vos delentry</B> command
 896 accepts the name or volume ID number of any type of volume (read/write,
 897 read-only, or backup). In fact, it accepts only a read/write
 898 volume's name or ID. Because a single VLDB entry represents all
 899 versions of a volume (read/write, readonly, and backup), the command removes
 900 the entire entry even though only the read/write volume is specified.
 901 For complete documentation, see <A HREF="#HDRVOS_DELENTRY">vos delentry</A>.
 902 </UL>
 903 <HR><H2><A NAME="HDRCMD-CHANGES" HREF="aurns002.htm#ToC_20">Changes to AFS Commands, Files, and Functionality</A></H2>
 904 <P>This section briefly describes commands, command
 905 options, and functionality that are new or changed in AFS 3.6.
 906 Unless otherwise noted, the <I>IBM AFS Administration Guide</I> and
 907 <I>IBM AFS Administration Reference</I> include complete documentation of
 908 these items.
 909 <P><H3><A NAME="Header_21" HREF="aurns002.htm#ToC_21">A New Command</A></H3>
 910 <P>AFS 3.6 includes the new <B>fs flushmount</B>
 911 command. The command's intended use is to discard information
 912 about mount points that has become corrupted in the cache. The next
 913 time an application accesses the mount point, the Cache Manager must fetch the
 914 most current version of it from a File Server. Data cached from files
 915 or directories in the volume is not affected. The only other way to
 916 discard the information is to reinitialize the Cache Manager by rebooting the
 917 machine.
 918 <P>Symptoms of a corrupted mount point included garbled output from the
 919 <B>fs lsmount</B> command, and failed attempts to change directory to or
 920 list the contents of the volume root directory represented by the mount
 921 point.
 922 <P><H3><A NAME="HDRNEW_CMDS" HREF="aurns002.htm#ToC_22">New File or Command Functionality</A></H3>
 923 <P>AFS 3.6 adds the following new options and
 924 functionality to existing commands and files.
 925 <UL>
 926 <P><LI><B>Changes that support XBSA servers</B>
 927 <P>Several <B>backup</B> commands and configuration files include new
 928 features that support backup to XBSA servers such as TSM. See <A HREF="#HDRTSM_NEW">New Command and File Features that Support TSM</A>.
 929 <P><LI><B>New instructions in the CFG_</B><VAR>tcid</VAR> <B>file</B>
 930 <P>There are new instructions in the <B>CFG_</B><VAR>tcid</VAR> file that
 931 apply to all types of backup media: <B>CENTRALLOG</B>,
 932 <B>GROUPID</B>, <B>LASTLOG</B>, <B>MAXPASS</B>, and
 933 <B>STATUS</B>. (There are also new instructions that apply only to
 934 XBSA servers, as documented in <A HREF="#HDRTSM_NEW">New Command and File Features that Support TSM</A>.)
 935 <P>The new instructions are not documented in the <I>IBM AFS Administration
 936 Guide</I> or <I>IBM AFS Administration Reference</I>. See <A HREF="#HDRCFG">CFG_<I>tcid</I></A>. (Note that this is a new way of referring to this
 937 file, called <B>CFG_</B><VAR>device_name</VAR> in the <I>IBM AFS
 938 Administration Guide</I> and <I>IBM AFS Administration
 939 Reference</I>. For a Tape Coordinator that communicates with an XBSA
 940 server, the variable part of the filename is a port offset number rather than
 941 a device name, so the more generic <VAR>tcid</VAR> is a better description of
 942 possible values in this part of the filename.)
 943 <P><LI><B>New -temporary flag to backup addvolset command</B>
 944 <P>The <B>backup addvolset</B> command has a new <B>-temporary</B>
 945 flag. A temporary volume set is not recorded in the Backup Database and
 946 exists only during the lifetime of the interactive session in which it is
 947 created.
 948 <P><LI><B>New options to the backup deletedump command</B>
 949 <P>There are new options to the <B>backup deletedump</B> command:
 950 the <B>-groupid</B> argument specifies the group ID number associated with
 951 the dump records to delete, and the <B>-noexecute</B> flag displays a list
 952 of the records to be deleted rather than actually deleting them. (There
 953 are also new options that apply only to records for data dumped to an XBSA
 954 server, as documented in <A HREF="#HDRTSM_NEW">New Command and File Features that Support TSM</A>.)
 955 <P>The new options are not documented in the <I>IBM AFS Administration
 956 Guide</I> or <I>IBM AFS Administration Reference</I>. See <A HREF="#HDRBK_DELETEDUMP">backup deletedump</A>.
 957 <P><LI><B>New output from the backup dumpinfo command</B>
 958 <P>When both the <B>-id</B> and <B>-verbose</B> options to the
 959 <B>backup dumpinfo</B> command are provided, the output is divided into
 960 several sections. In the first section, headed by the label
 961 <TT>Dump</TT>, the new <TT>Group id</TT> field replaces the <TT>id</TT>
 962 field that previously appeared about halfway down the list of fields (the
 963 first field in the section is still labeled <TT>id</TT>). The
 964 <TT>Group id</TT> field reports the dump's group ID number, which is
 965 recorded in the Backup Database if the <B>GROUPID</B> instruction appears
 966 in the Tape Coordinator's <B> /usr/afs/backup/CFG_</B><VAR>tcid</VAR>
 967 file when the dump is created.
 968 <P>(The command's output also includes a new message that reports whether
 969 the dump data is stored on an XBSA server, as detailed in <A HREF="#HDRTSM_NEW">New Command and File Features that Support TSM</A>.)
 970 <P>The new output is not documented in the <I>IBM AFS Administration
 971 Guide</I> or <I>IBM AFS Administration Reference</I>. See <A HREF="#HDRBK_DUMPINFO">backup dumpinfo</A>.
 972 <P><LI><B>BOS Server sends additional field to notifier programs</B>
 973 <P>The AFS 3.6 BOS Server sends additional information to notifier
 974 programs when an AFS server process exits. The <B>bnode_proc</B>
 975 structure now includes the <B>lastExit</B> field, which reports the exit
 976 code associated with the process's most recent exit. Previously,
 977 the only information about exit codes available to the notifier program was in
 978 the <B>bnode</B> structure's <B>errorCode</B> field, which
 979 records the exit code generated when the process last exited due to an
 980 error. The BOS Server does not clear the <B>errorCode</B> field, so
 981 the value set at the last exit due to error is reported even for exits that
 982 are not due to error.
 983 <P>If your notifier program currently checks the <B>errorCode</B> field
 984 but you really want a notification only when the most recent exit is due to an
 985 error, change the program to check the <B>lastExit</B> field in the
 986 <B>bnode_proc</B> structure instead. An error code appears in the
 987 <B>lastExit</B> field only if the most recent exit really was due to an
 988 error (in which case the same code also appears in the <B>errorCode</B>
 989 field).
 990 <P>The <B>bos create</B> command's reference page in the <I>IBM AFS
 991 Administration Reference</I> describes all of the fields that the BOS Server
 992 can include in the <B>bnode_proc</B> and <B>bnode</B>
 993 structures. As noted there, the BOS Server does not necessarily include
 994 every field in the structures it sends to a notifier program, because some of
 995 them are for internal use. For best results, the notifier program must
 996 correctly handle the absence of a field that it expects to find.
 997 <P><LI><B>Only administrators can use kas examine command's -showkey
 998 flag</B>
 999 <P>As in AFS 3.5, the AFS 3.6 Authentication Server does not
1000 require that you disable authorization checking on its database server machine
1001 before it returns the octal digits that constitute the encrypted password or
1002 key stored in an Authentication Database entry, which was the requirement with
1003 earlier versions of AFS. Instead, it always returns the octal digits,
1004 as long as the connection between the <B>kas</B> command interpreter and
1005 Authentication Server is encrypted. AFS 3.5 introduced the
1006 <B>-showkey</B> flag to make the <B>kas examine</B> command display
1007 the octal digits.
1008 <P>This change in requirements creates a potential security exposure, however,
1009 in that earlier versions of the <B>kas examine</B> command always display
1010 the octal digits (instead of a checksum) when directed to an AFS 3.5 or
1011 3.6 Authentication Server. To eliminate this exposure, in AFS
1012 3.6 the Authentication Server returns octal digits only for a principal
1013 that has the <TT>ADMIN</TT> flag in its Authentication Database
1014 entry.
1015 <P>The main effect of the new requirement is that only administrators can
1016 include the <B>-showkey</B> flag on the AFS 3.6 <B>kas
1017 examine</B> command. It does not effectively change the privilege
1018 required to display the octal digits when using versions of the <B>kas
1019 examine</B> command before AFS 3.5 Patch 2 (build level
1020 <B>afs3.5 3.17</B>), because it was assumed with earlier
1021 versions that only administrators were able to disable authorization
1022 checking. It also does not affect the automated installation and
1023 configuration tool provided for AFS for Windows, which still can be used only
1024 by administrators.
1025 <P><LI><B>The vos delentry command accepts only read/write volume names</B>
1026 <P>The AFS 3.6 version of the <B>vos delentry</B> command accepts
1027 only read/write volume names or volume ID numbers as values for its
1028 <B>-id</B> or <B>-prefix</B> arguments. The new restriction is
1029 not documented in the <I>IBM AFS Administration Guide</I> or <I>IBM AFS
1030 Administration Reference</I>. See <A HREF="#HDRVOS_DELENTRY">vos delentry</A>.
1031 </UL>
1032 <HR><H2><A NAME="HDRTSM" HREF="aurns002.htm#ToC_23">Support for Backup to TSM</A></H2>
1033 <P>AFS 3.6 introduces support for backing up AFS data to
1034 media managed by the Tivoli Storage Manager (TSM), a third-party backup
1035 program which implements the Open Group's Backup Service application
1036 programming interface (API), also called <I>XBSA</I>. TSM was
1037 formerly called the ADSTAR Distributed Storage Manager, or ADSM. It is
1038 assumed that the administrator is familiar with TSM; explaining TSM or
1039 XBSA concepts or terminology is beyond the scope of this document.
1040 <P>See the following subsections:
1041 <UL>
1042 <P><LI><A HREF="#HDRTSM_NEW">New Command and File Features that Support TSM</A>
1043 <P><LI><A HREF="#HDRTSM_REQ">Product Notes for Use of TSM</A>
1044 <P><LI><A HREF="#HDRTSM_CONFIG">Configuring the Backup System and TSM</A>
1045 </UL>
1046 <P><H3><A NAME="HDRTSM_NEW" HREF="aurns002.htm#ToC_24">New Command and File Features that Support TSM</A></H3>
1047 <P>The AFS 3.6 version of the following commands and
1048 configuration files include new options or instructions to support backup to
1049 TSM.
1050 <UL>
1051 <P><LI><B>New XBSA-related instructions in the CFG_</B><VAR>tcid</VAR>
1052 <B>file</B>
1053 <P>Several new or modified instructions in the <B>CFG_</B><VAR>tcid</VAR>
1054 file support backup of AFS data to XBSA servers such as TSM:
1055 <B>MGMTCLASS</B>, <B>NODE</B>, <B>PASSFILE</B>,
1056 <B>PASSWORD</B>, <B>SERVER</B>, and <B>TYPE</B>. (There are
1057 also new instructions that apply to automated tape devices and backup data
1058 files as well as XBSA servers, as detailed in <A HREF="#HDRNEW_CMDS">New File or Command Functionality</A>.)
1059 <P>The new instructions are not documented in the <I>IBM AFS Administration
1060 Guide</I> or <I>IBM AFS Administration Reference</I>. See <A HREF="#HDRCFG">CFG_<I>tcid</I></A>. (Note that this is a new way of referring to this
1061 file, called <B>CFG_</B><VAR>device_name</VAR> in the <I>IBM AFS
1062 Administration Guide</I> and <I>IBM AFS Administration
1063 Reference</I>. For a Tape Coordinator that communicates with XBSA
1064 server such as TSM, the variable part of the filename is a port offset number
1065 rather than a device name, so the more generic <VAR>tcid</VAR> is a better
1066 description of possible values in this part of the filename.)
1067 <P><LI><B>New options to the backup deletedump command</B>
1068 <P>The <B>backup deletedump</B> command has new options that enable you to
1069 delete dump records stored on an XBSA server such as TSM, as well as the
1070 corresponding Backup Database records:
1071 <UL>
1072 <P><LI>The <B>-dbonly</B> flag deletes Backup Database records without
1073 attempting to delete the corresponding records stored on the XBSA
1074 server.
1075 <P><LI>The <B>-force</B> flag deletes Backup Database records even if it is
1076 not possible to delete the corresponding records stored on the XBSA
1077 server.
1078 <P><LI>The <B>-port</B> argument identifies the Tape Coordinator that
1079 communicates with the XBSA server on which to delete records.
1080 </UL>
1081 <P>There are also two new options that apply to automated tape devices and
1082 backup data files as well as XBSA servers, as detailed in <A HREF="#HDRNEW_CMDS">New File or Command Functionality</A>.
1083 <P>The new options are not documented in the <I>IBM AFS Administration
1084 Guide</I> or <I>IBM AFS Administration Reference</I>. See <A HREF="#HDRBK_DELETEDUMP">backup deletedump</A>.
1085 <P><LI><B>New output from the backup dumpinfo command</B>
1086 <P>When the <B>-id</B> option is provided to the <B>backup
1087 dumpinfo</B> command, the following line appears in the output if a TSM
1088 server was the backup medium for the dump:
1089 <PRE>   Backup Service: TSM: Server: <VAR>hostname</VAR>
1090 </PRE>
1091 <P>where <VAR>hostname</VAR> is the name of the TSM server machine.
1092 (There is also new output for dumps to all types of backup media, as detailed
1093 in <A HREF="#HDRNEW_CMDS">New File or Command Functionality</A>.)
1094 <P>The new output is not documented in the <I>IBM AFS Administration
1095 Guide</I> or <I>IBM AFS Administration Reference</I>. See <A HREF="#HDRBK_DUMPINFO">backup dumpinfo</A>.
1096 <P><LI><B>New output from the backup status command</B>
1097 <P>If the Tape Coordinator is communicating with a TSM server, the following
1098 message appears last in the output from the <B>backup status</B>
1099 command:
1100 <PRE>   TSM Tape coordinator
1101 </PRE>
1102 <P>The new output is not documented in the <I>IBM AFS Administration
1103 Guide</I> or <I>IBM AFS Administration Reference</I>. See <A HREF="#HDRBK_STATUS">backup status</A>.
1104 </UL>
1105 <P><H3><A NAME="HDRTSM_REQ" HREF="aurns002.htm#ToC_25">Product Notes for Use of TSM</A></H3>
1106 <UL>
1107 <P><LI><B>Supported Tape Coordinator machine types</B>
1108 <P>To communicate with a TSM server, the Tape Coordinator must run on a
1109 machine that uses one of the following operating systems: AIX 4.3
1110 or higher, Solaris 2.6, Solaris 7.
1111 <P><LI><B>Supported version of TSM API</B>
1112 <P>The AFS 3.6 Tape Coordinator uses version 3.7.1
1113 (Version 3, Release 7) of the TSM client API. Use of other versions of
1114 the API is not supported or tested. For instructions on obtaining the
1115 API, see <A HREF="#HDRTSM_CONFIG">Configuring the Backup System and TSM</A>.
1116 <P><LI><B>CFG_</B><VAR>tcid</VAR> <B>file is required for TSM servers</B>
1117 <P>To communicate with a TSM server, a Tape Coordinator must have a
1118 <B>CFG_</B><VAR>tcid</VAR> file that includes the following fields:
1119 <B>SERVER</B>, <B>TYPE</B>, and <B>PASSWORD</B> or
1120 <B>PASSFILE</B>. For instructions on creating the file, see <A HREF="#HDRTSM_CONFIG">Configuring the Backup System and TSM</A>.
1121 <P><LI><B>No entry in tapeconfig file for TSM servers</B>
1122 <P>Do not create an entry in the <B>/usr/afs/backup/tapeconfig</B> file
1123 for a Tape Coordinator that communicates with an XBSA server such as
1124 TSM. Creating the <B>CFG_</B><VAR>tcid</VAR> file is
1125 sufficient.
1126 <P><LI><B>Acceptable value for the TYPE instruction</B>
1127 <P>In AFS 3.6, there is one acceptable value for the <B>TYPE</B>
1128 instruction in the <B>CFG_</B><VAR>tcid</VAR> file:
1129 <B>tsm</B>.
1130 <P><LI><B>TSM node name must be defined</B>
1131 <P>If the <B>NODE</B> instruction is not included in the
1132 <B>/usr/afs/backup/CFG_</B><VAR>tcid</VAR> file, the TSM
1133 <B>dsm.sys</B> file must define a value for the NODENAME
1134 variable.
1135 <P><LI><B>Unsupported backup commands and options</B>
1136 <P>The following commands are not supported for XBSA servers such as
1137 TSM. In other words, the commands fail with an error message when their
1138 <B>-port</B> argument specifies a Tape Coordinator that communicates with
1139 an XBSA server:
1140 <UL>
1141 <P><LI><B>backup labeltape</B>
1142 <P><LI><B>backup readlabel</B>
1143 <P><LI><B>backup restoredb</B>
1144 <P><LI><B>backup savedb</B>
1145 <P><LI><B>backup scantape</B>
1146 </UL>
1147 <P>In addition, the <B>-append</B> flag to the <B>backup dump</B>
1148 command is ignored when the <B>-port</B> argument specifies a Tape
1149 Coordinator that communicates with an XBSA server (the notion of appended
1150 dumps does not apply to XBSA servers).
1151 </UL>
1152 <P><H3><A NAME="HDRTSM_CONFIG" HREF="aurns002.htm#ToC_26">Configuring the Backup System and TSM</A></H3>
1153 <P>Perform the following steps to configure TSM and the
1154 AFS Backup System for interoperation.
1155 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">You possibly need to perform additional TSM configuration procedures
1156 unrelated to AFS. See the TSM documentation.
1157 </TD></TR></TABLE>
1158 <OL TYPE=1>
1159 <P><LI>Become the local superuser <B>root</B>, if you are not already.
1160 <P>
1161 <PRE>   % <B>su root</B>
1162    Password: <VAR>root_password</VAR>
1163 </PRE>
1164 <P><LI>Install version 3.7.1 of the TSM client API on the local
1165 disk of the Tape Coordinator machine. If you do not already have the
1166 API, you can use the following instructions to download it using the UNIX File
1167 Transfer Protocol (<B>ftp</B>).
1168 <OL TYPE=a>
1169 <P><LI>Verify that there is enough free space on the local disk to accommodate
1170 the API package:
1171 <UL>
1172 <P><LI>On AIX systems, 4 MB on the disk that houses the <B>/usr/tivoli</B>
1173 directory
1174 <P><LI>On Solaris systems, 13 MB on the disk that houses the
1175 <B>/opt/tivoli</B> directory
1176 </UL>
1177 <P><LI>Connect to the <B>ftp</B> server called
1178 <B>ftp.software.ibm.com</B>, logging in as
1179 <B>anonymous</B> and providing your electronic mail address as the
1180 password.
1181 <P><LI>Switch to binary mode.
1182 <PRE>   ftp> <B>bin</B>
1183 </PRE>
1184 <P><LI>Change directory as indicated:
1185 <PRE>   ftp> <B>cd storage/tivoli-storage-management-maintenance/client/v3r7</B>
1186 </PRE>
1187 <P><LI>Change to the appropriate directory and retrieve the API file.
1188 <UL>
1189 <P><LI>On an AIX 4.3 system:
1190 <PRE>   ftp> <B>cd AIX/v371</B>
1191    ftp> <B>get tivoli.tsm.client.api.aix43.32bit</B>
1192 </PRE>
1193 <P><LI>On a Solaris 2.6 or 7 system:
1194 <PRE>   ftp> <B>cd Solaris/v371</B>
1195    ftp> <B>get IP21804.tar.Z</B>
1196 </PRE>
1197 </UL>
1198 <P><LI>Use the appropriate tool to install the TSM API package locally:
1199 <UL>
1200 <P><LI>On AIX machines, use <B>smit</B>, which installs the files in the
1201 <B>/usr/tivoli/tsm/client/api/bin</B> directory
1202 <P><LI>On Solaris machines, use the following command, which installs the files
1203 in the <B>/opt/tivoli/tsm/client/api/bin</B> directory:
1204 <PRE>   # <B>uncompress IP21804.tar.Z | tar xvf -</B>
1205 </PRE>
1206 </UL>
1207 </OL>
1208 <P><LI>Set the following TSM environment variables as indicated. If you do
1209 not set them, you must use the default values specified in the TSM
1210 documentation.
1211 <DL>
1212 <P><DT><B>DSMI_DIR
1213 </B><DD>Specifies the pathname of the directory that contains the TSM client
1214 system options file, <B>dsm.sys</B>. The directory must have
1215 a subdirectory (which can be a symbolic link) called <B>en_US</B> that
1216 contains the <B>dsmclientV3.cat</B> catalog file.
1217 <P>Do not put a final slash ( <B>/</B> ) on the directory name.
1218 Examples of appropriate values are <B>/opt/tivoli/tsm/client/api/bin</B>
1219 on Solaris machines and <B>/usr/tivoli/tsm/client/api/bin</B> on AIX
1220 machines.
1221 <P><DT><B>DSMI_CONFIG
1222 </B><DD>Specifies the pathname of the directory that contains the TSM client user
1223 options file, <B>dsm.opt</B>. The value can be the same as
1224 for the <B>DSMI_DIR</B> variable. Do not put a final slash (
1225 <B>/</B> ) on the directory name.
1226 <P><DT><B> DSMI_LOG
1227 </B><DD>Specifies the full pathname (including the filename) of the log file for
1228 error messages from the API. An appropriate value is
1229 <B>/usr/afs/backup/butc.TSMAPI.log</B>.
1230 </DL>
1231 <P><LI><A NAME="LIWQ5"></A>Verify that the <B>dsm.sys</B> file includes the
1232 following instructions. For a description of the fields, see the TSM
1233 documentation.
1234 <PRE>   ServerName           <VAR>machine_name</VAR>
1235       CommMethod        tcpip
1236       TCPPort           <VAR>TSM_port</VAR>
1237       TCPServerAddress  <VAR>full_machine_name</VAR>
1238       PasswordAccess    prompt
1239       Compression       yes
1240 </PRE>
1241 <P>The following is an example of appropriate values:
1242 <PRE>   ServerName tsm3
1243       CommMethod tcpip
1244       TCPPort 1500
1245       TCPServerAddress  tsm3.abc.com
1246       PasswordAccess  prompt
1247       Compression  yes
1248 </PRE>
1249 <P><LI>Verify that the <B>dsm.opt</B> file includes the following
1250 instructions. For a description of the fields, see the TSM
1251 documentation.
1252 <PRE>   ServerName        <VAR>machine_name</VAR>
1253       tapeprompt     no
1254       compressalways yes
1255 </PRE>
1256 <P><LI><A NAME="LITSM_BK_ADDHOST"></A>Create a Backup Database entry for each Tape
1257 Coordinator that is to communicate with the TSM server. Multiple Tape
1258 Coordinators can interact with the same TSM server if the server has
1259 sufficient capacity.
1260 <PRE>   # <B>backup addhost</B> &lt;<VAR>tape&nbsp;machine&nbsp;name</VAR>> &lt;<VAR>TC&nbsp;port&nbsp;offset</VAR>>
1261 </PRE>
1262 <P>where
1263 <DL>
1264 <P><DT><B><VAR>tape machine name</VAR>
1265 </B><DD>Specifies the fully qualified hostname of the Tape Coordinator
1266 machine.
1267 <P><DT><B><VAR>TC port offset</VAR>
1268 </B><DD>Specifies the Tape Coordinator's port offset number.
1269 Acceptable values are integers in the range from <B>0</B> (zero) through
1270 <B>58510</B>.
1271 </DL>
1272 <P><LI>Create a device configuration file for the Tape Coordinator called
1273 <B>/usr/afs/backup/CFG_</B><VAR>tcid</VAR>, where <VAR>tcid</VAR> is the Tape
1274 Coordinator's port offset number as defined in Step <A HREF="#LITSM_BK_ADDHOST">6</A>. The file must include the following
1275 instructions:
1276 <UL>
1277 <P><LI><B>SERVER</B>, which takes as its argument the fully qualified
1278 hostname of the TSM server machine. It matches the value in the
1279 <VAR>full_machine_name</VAR> field of the <B>dsm.sys</B> file, as
1280 defined in Step <A HREF="#LIWQ5">4</A>.
1281 <P><LI><B>TYPE</B>, which takes as its argument the string <B>tsm</B>
1282 (the only acceptable value in AFS 3.6).
1283 <P><LI>One of <B>PASSWORD</B> or <B>PASSFILE</B>, to define the password
1284 which the Tape Coordinator uses when communicating with the TSM server.
1285 <B>PASSWORD</B> takes as its argument the actual password character
1286 string. <B>PASSFILE</B> takes as its argument the complete pathname
1287 of the file that contains the string on its first line.
1288 </UL>
1289 <P>For more detailed descriptions of the instructions, and of other
1290 instructions you can include in the configuration file, see <A HREF="#HDRCFG">CFG_<I>tcid</I></A>.
1291 </OL>
1292 <HR><H2><A NAME="HDRINSTALL" HREF="aurns002.htm#ToC_27">Upgrading Server and Client Machines to AFS 3.6</A></H2>
1293 <P>This section explains how to upgrade server and client
1294 machines from AFS 3.5 or AFS 3.6 Beta to AFS 3.6.
1295 Before performing an upgrade, please read all of the introductory material in
1296 this section.
1297 <P>If you are installing AFS for the first time, skip this chapter and refer
1298 to the <I>IBM AFS Quick Beginnings</I> document for AFS 3.6.
1299 <P>AFS provides backward compatibility to the previous release only: AFS
1300 3.6 is certified to be compatible with AFS 3.5 but not
1301 necessarily with earlier versions.
1302 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">This document does not provide instructions for upgrading from AFS
1303 3.4a or earlier directly to AFS 3.6. A file system
1304 conversion is required on some system types. See the <I>AFS Release
1305 Notes</I> for AFS 3.5 and contact your AFS product support
1306 representative for assistance.
1307 </TD></TR></TABLE>
1308 <P><H3><A NAME="Header_28" HREF="aurns002.htm#ToC_28">Prerequisites for Upgrading</A></H3>
1309 <P>You must meet the following requirements to upgrade successfully to AFS
1310 3.6:
1311 <UL>
1312 <P><LI>You can access the AFS 3.6 binaries by network, or have the CD-ROM
1313 labeled <B>AFS Version 3.6</B> for each system type you need to
1314 upgrade. See <A HREF="#HDRGETBIN">Obtaining the Binary Distribution</A>.
1315 <P><LI>You have access to the <I>IBM AFS Quick Beginnings</I> document for
1316 AFS 3.6, either in hardcopy (for English, IBM document number
1317 SC09-4560-00, part number CT6Q7NA) or at &lt;A
1318 HREF="http://www.transarc.com/Library/documentation/afs_doc.html"><B>http://www.transarc.com/Library/documentation/afs_doc.html</B>&lt;/A>.
1319 See also <A HREF="#HDRDOC">Accessing the AFS Binary Distribution and Documentation</A>.
1320 <P><LI>The partition that houses the <B>/usr/afs/bin</B> directory on each
1321 server machine has at least 18 MB of disk space for storing the AFS server
1322 binaries.
1323 <P><LI>The partition that houses the <B>/usr</B> directory on each client
1324 machine has at least 4 MB of disk space for storing the AFS client binaries
1325 and kernel library files (stored by convention in the <B>/usr/vice/etc</B>
1326 directory).
1327 <P><LI>You can log into all server and client machines as the local superuser
1328 <B>root</B>.
1329 <P><LI>You are listed in the cell's <B>/usr/afs/etc/UserList</B> file
1330 and can authenticate as a member of the <B>system:administrators</B>
1331 group.
1332 </UL>
1333 <P><H3><A NAME="HDRGETBIN" HREF="aurns002.htm#ToC_29">Obtaining the Binary Distribution</A></H3>
1334 <P>Use one of the following methods to obtain the AFS
1335 distribution of each system type for which you are licensed.
1336 <UL>
1337 <P><LI>Working with your AFS Sales Representative, obtain the AFS 3.6
1338 CD-ROM for each system type.
1339 <P><LI>Access the distribution by network in IBM's Electronic Software
1340 Distribution system.
1341 </UL>
1342 <P><H3><A NAME="HDRSTOREBIN" HREF="aurns002.htm#ToC_30">Storing Binaries in AFS</A></H3>
1343 <P>It is conventional to store many of the programs and
1344 files from the AFS binary distribution in a separate volume for each system
1345 type, mounted in your AFS filespace at
1346 <B>/afs/</B><VAR>cellname</VAR><B>/</B><VAR>sysname</VAR><B>/usr/afsws</B>.
1347 These instructions rename the volume currently mounted at this location and
1348 create a new volume for AFS 3.6 binaries.
1349 <P>Repeat the instructions for each system type.
1350 <OL TYPE=1>
1351 <P><LI>Authenticate as an administrator listed in the
1352 <B>/usr/afs/etc/UserList</B> file.
1353 <P><LI>Issue the <B>vos create</B> command to create a new volume for AFS
1354 3.6 binaries called
1355 <VAR>sysname</VAR><B>.3.6</B>. Set an unlimited quota
1356 on the volume to avoid running out of space as you copy files from the
1357 distribution.
1358 <PRE>   % <B>vos create</B> &lt;<VAR>machine&nbsp;name</VAR>> &lt;<VAR>partition&nbsp;name</VAR>> <VAR>sysname</VAR><B>.3.6  -maxquota  0</B>
1359 </PRE>
1360 <P><LI>Issue the <B>fs mkmount</B> command to mount the volume at a temporary
1361 location.
1362 <PRE>   % <B>fs mkmount  /afs/.</B><VAR>cellname</VAR><B>/temp</B>  <VAR>sysname</VAR><B>.3.6</B>
1363 </PRE>
1364 <P><LI>Prepare to access the files using the method you have selected:
1365 <UL>
1366 <P><LI>If copying files from the CD-ROM, mount the CD-ROM for this machine's
1367 system type on the local <B>/cdrom</B> directory. For instructions
1368 on mounting CD-ROMs (either locally or remotely via NFS), consult the
1369 operating system documentation. Then change directory as
1370 indicated.
1371 <PRE>   % <B>cd /cdrom/</B><VAR>sysname</VAR>
1372 </PRE>
1373 <P><LI>If accessing the distribution electronically, download the necessary file
1374 or files. If necessary, use commands such as <B>gunzip</B> and
1375 <B>tar xvf</B> to uncompress and unpack the distribution. Place the
1376 contents in a temporary location (<VAR>temp_afs36_dir</VAR>) and change
1377 directory to that location.
1378 <PRE>   %  <B>cd</B>  <VAR>temp_afs36_dir</VAR>
1379 </PRE>
1380 </UL>
1381 <P><LI>Copy files from the distribution into the
1382 <VAR>sysname</VAR><B>.3.6</B> volume.
1383 <PRE>   % <B>cp -rp  bin  /afs/.</B><VAR>cellname</VAR><B>/temp</B>
1384
1385    % <B>cp -rp  etc  /afs/.</B><VAR>cellname</VAR><B>/temp</B>
1386
1387    % <B>cp -rp  include  /afs/.</B><VAR>cellname</VAR><B>/temp</B>
1388
1389    % <B>cp -rp  lib  /afs/.</B><VAR>cellname</VAR><B>/temp</B>
1390 </PRE>
1391 <P><LI><A NAME="LISTOREBIN-CLIENT"></A><B>(Optional)</B> By convention, the contents of
1392 the distribution's <B>root.client</B> directory are not stored
1393 in AFS. However, if you are upgrading client functionality on many
1394 machines, it can be simpler to copy the client files from your local AFS space
1395 than from the CD-ROM or from IBM's Electronic Software Distribution
1396 system. If you wish to store the contents of the
1397 <B>root.client</B> directory in AFS temporarily, copy them
1398 now.
1399 <PRE>   % <B>cp -rp  root.client  /afs/.</B><VAR>cellname</VAR><B>/temp</B>
1400 </PRE>
1401 <P><LI>Issue the <B>vos rename</B> command to change the name of the volume
1402 currently mounted at the
1403 <B>/afs/</B><I>cellname</I><B>/</B><I>sysname</I><B>/usr/afsws</B>
1404 directory. A possible value for the <VAR>extension</VAR> reflects the AFS
1405 version and build level (for example:
1406 <B>3.5-bld3.32</B>).
1407 <P>If you do not plan to retain the old volume, you can substitute the
1408 <B>vos remove</B> command in this step.
1409 <PRE>   %  <B>vos rename</B> <VAR>sysname</VAR><B>.usr.afsws</B>  <VAR>sysname</VAR><B>.usr.afsws.</B><VAR>extension</VAR>
1410 </PRE>
1411 <P><LI>Issue the <B>vos rename</B> command to change the name of the
1412 <VAR>sysname</VAR><B>.3.6</B> volume to
1413 <VAR>sysname</VAR><B>.usr.afsws</B>.
1414 <PRE>   %  <B>vos rename</B> <VAR>sysname</VAR><B>.3.6</B>  <VAR>sysname</VAR><B>.usr.afsws</B>
1415 </PRE>
1416 <P><LI>Issue the <B>fs rmmount</B> command to remove the temporary mount
1417 point for the <VAR>sysname</VAR><B>.3.6</B> volume.
1418 <PRE>    % <B>fs rmmount  /afs/.</B><VAR>cellname</VAR><B>/temp</B>
1419 </PRE>
1420 </OL>
1421 <P><H3><A NAME="HDROS-UP" HREF="aurns002.htm#ToC_31">Upgrading the Operating System</A></H3>
1422 <P>AFS 3.6 supports the 64-bit version of HP-UX
1423 11.0 and Solaris 7. To upgrade from the 32-bit version,
1424 you possibly need to reinstall the operating system completely before
1425 installing AFS 3.6. When performing any operating system
1426 upgrade, you must take several actions to preserve AFS functionality,
1427 including the following:
1428 <UL>
1429 <P><LI>Unmount the AFS server partitions (those mounted on <B>/vicep</B>
1430 directories) on all file server machines, to prevent the standard vendor
1431 version of the <B>fsck</B> program from running on them when you reboot
1432 the machine during installation of the new operating system. On several
1433 operating systems, the standard <B>fsck</B> program does not recognize AFS
1434 volume data and discards it. Also, disable automatic mounting of the
1435 partitions during reboot until you have substituted the AFS <B>vfsck</B>
1436 program for the vendor <B>fsck</B> program.
1437 <P><LI>Create copies of the AFS-modified versions of binaries or files so that
1438 they are not overwritten by the standard versions during the operating system
1439 upgrade, particularly if you are not performing an immediate AFS
1440 upgrade. Examples include the remote commands (<B>ftpd</B>,
1441 <B>inetd</B>, <B>rcp</B>, <B>rsh</B>, and so on) and the
1442 <B>vfsck</B> binary. After you have successfully installed the new
1443 version of the operating system, move the AFS-modified files and commands back
1444 to the directories from which they are accessed during normal use.
1445 </UL>
1446 <P><H3><A NAME="HDRSV-BIN" HREF="aurns002.htm#ToC_32">Distributing Binaries to Server Machines</A></H3>
1447 <P>The instructions in this section explain how to use the
1448 Update Server to distribute server binaries from a binary distribution machine
1449 of each system type.
1450 <P>Repeat the steps on each binary distribution machine in your cell.
1451 If you do not use the Update Server, repeat the steps on every server machine
1452 in your cell. If you are copying files from the AFS product tree, the
1453 server machine must also be configured as an AFS client machine.
1454 <OL TYPE=1>
1455 <P><LI>Become the local superuser <B>root</B>, if you are not already.
1456 <P>
1457 <PRE>   % <B>su root</B>
1458    Password: <VAR>root_password</VAR>
1459 </PRE>
1460 <P><LI>Create a temporary subdirectory of the <B>/usr/afs/bin</B> directory
1461 to store the AFS 3.6 server binaries.
1462 <PRE>   # <B>mkdir /usr/afs/bin.36</B>
1463 </PRE>
1464 <P><LI>Prepare to access server files using the method you have selected from
1465 those listed in <A HREF="#HDRGETBIN">Obtaining the Binary Distribution</A>:
1466 <UL>
1467 <P><LI>If copying files from the CD-ROM, mount the CD-ROM for this machine's
1468 system type on the local <B>/cdrom</B> directory. For instructions
1469 on mounting CD-ROMs (either locally or remotely via NFS), consult the
1470 operating system documentation. Then change directory as
1471 indicated.
1472 <PRE>   # <B>cd /cdrom/</B><VAR>sysname</VAR><B>/root.server/usr/afs/bin</B>
1473 </PRE>
1474 <P><LI>If accessing the distribution electronically, you possibly already
1475 downloaded it in <A HREF="#HDRSTOREBIN">Storing Binaries in AFS</A>. If so, it is still in the <VAR>temp_afs36_dir</VAR>
1476 directory. If not, download it and run any commands necessary to
1477 uncompress or unpack the distribution. Place it in a temporary location
1478 (<VAR>temp_afs36_dir</VAR>), and change directory to the indicated
1479 subdirectory.
1480 <PRE>   # <B>cd</B>  <VAR>temp_afs36_dir</VAR><B>/root.server/usr/afs/bin</B>
1481 </PRE>
1482 </UL>
1483 <P><LI>Copy the server binaries from the distribution into the
1484 <B>/usr/afs/bin.36</B> directory.
1485 <PRE>   # <B>cp -p  *  /usr/afs/bin.36</B>
1486 </PRE>
1487 <P><LI><A NAME="LISV-BIN-NEWDIRS"></A>Rename the current <B>/usr/afs/bin</B> directory
1488 to <B>/usr/afs/bin.old</B> and the
1489 <B>/usr/afs/bin.36</B> directory to the standard location.
1490 <PRE>   # <B>cd /usr/afs</B>
1491
1492    # <B>mv  bin  bin.old</B>
1493
1494    # <B>mv  bin.36  bin</B>
1495 </PRE>
1496 </OL>
1497 <P><H3><A NAME="HDRSV-UP" HREF="aurns002.htm#ToC_33">Upgrading Server Machines</A></H3>
1498 <P>Repeat the following instructions on each server
1499 machine. Perform them first on the database server machine with the
1500 lowest IP address, next on the other database server machines, and finally on
1501 other server machines.
1502 <P>The AFS data stored on a server machine is inaccessible to client machines
1503 during the upgrade process, so it is best to perform it at the time and in the
1504 manner that disturbs your users least.
1505 <OL TYPE=1>
1506 <P><LI><A NAME="LISVUP-UPCLIENTBIN"></A>If you have just followed the steps in <A HREF="#HDRSV-BIN">Distributing Binaries to Server Machines</A> to install the server binaries on binary distribution
1507 machines, wait the required interval (by default, five minutes) for the local
1508 <B>upclientbin</B> process to retrieve the binaries.
1509 <P>If you do not use binary distribution machines, perform the instructions in
1510 <A HREF="#HDRSV-BIN">Distributing Binaries to Server Machines</A> on this machine.
1511 <P><LI>Become the local superuser <B>root</B>, if you are not already, by
1512 issuing the <B>su</B> command.
1513 <PRE>   % <B>su root</B>
1514    Password: <VAR>root_password</VAR>
1515 </PRE>
1516 <P><LI>If the machine also functions as a client machine, prepare to access
1517 client files using the method you have selected from those listed in <A HREF="#HDRGETBIN">Obtaining the Binary Distribution</A>:
1518 <UL>
1519 <P><LI>If you copied the contents of the <B>root.client</B> directory
1520 into AFS (in Step <A HREF="#LISTOREBIN-CLIENT">6</A> of <A HREF="#HDRSTOREBIN">Storing Binaries in AFS</A>), change directory as indicated.
1521 <PRE>   # <B>cd /afs/</B><VAR>cellname</VAR><B>/</B><VAR>sysname</VAR><B>/usr/afsws/root.client</B>
1522 </PRE>
1523 <P><LI>If copying files from the CD-ROM, mount the CD-ROM for this machine's
1524 system type on the local <B>/cdrom</B> directory. For instructions
1525 on mounting CD-ROMs (either locally or remotely via NFS), consult the
1526 operating system documentation. Then change directory as
1527 indicated.
1528 <PRE>   # <B>cd /cdrom/</B><VAR>sysname</VAR><B>/root.client</B>
1529 </PRE>
1530 <P><LI>If accessing the distribution electronically, you possibly already
1531 downloaded it in <A HREF="#HDRSTOREBIN">Storing Binaries in AFS</A>. If so, it is still in the <VAR>temp_afs36_dir</VAR>
1532 directory. If not, download it and run any commands necessary to
1533 uncompress or unpack the distribution. Place it in a temporary location
1534 (<VAR>temp_afs36_dir</VAR>), and change directory to the indicated
1535 subdirectory.
1536 <PRE>   # <B>cd</B>  <VAR>temp_afs36_dir</VAR><B>/root.client</B>
1537 </PRE>
1538 </UL>
1539 <P><LI>If the machine also functions as a client machine, copy the AFS 3.6
1540 version of the <B>afsd</B> binary and other files to the
1541 <B>/usr/vice/etc</B> directory.
1542 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">Some files in the <B>/usr/vice/etc</B> directory, such as the AFS
1543 initialization file (called <B>afs.rc</B> on many system types), do
1544 not necessarily need to change for a new release. It is a good policy
1545 to compare the contents of the distribution directory and the
1546 <B>/usr/vice/etc</B> directory before performing the copying
1547 operation. If there are files in the <B>/usr/vice/etc</B> directory
1548 that you created for AFS 3.5 or 3.6 Beta and that you want to
1549 retain, either move them to a safe location before performing the following
1550 instructions, or alter the following instructions to copy over only the
1551 appropriate files.
1552 </TD></TR></TABLE>
1553 <PRE>   # <B>cp  -p  usr/vice/etc/*   /usr/vice/etc</B>
1554
1555    # <B>cp  -rp  usr/vice/etc/C  /usr/vice/etc</B>
1556 </PRE>
1557 <P>If you have not yet incorporated AFS into the machine's authentication
1558 system, perform the instructions in the section titled <I>Enabling AFS
1559 Login</I> for this system type in the <I>IBM AFS Quick Beginnings</I>
1560 chapter about configuring client machines. If this machine was running
1561 the same operating system revision with AFS 3.5 or AFS 3.6 Beta,
1562 you presumably already incorporated AFS into its authentication system.
1563 <P><LI>AFS performance is most dependable if the AFS release version of the
1564 kernel extensions and server processes is the same. Therefore, it is
1565 best to incorporate the AFS 3.6 kernel extensions into the kernel at
1566 this point.
1567 <P>First issue the following command to shut down the server processes,
1568 preventing them from restarting accidently before you incorporate the AFS
1569 3.6 extensions into the kernel.
1570 <PRE>   # <B>bos shutdown</B> &lt;<VAR>machine&nbsp;name</VAR>> <B>-localauth -wait</B>
1571 </PRE>
1572 <P>Then perform the instructions in <A HREF="#HDRKERNEL">Incorporating AFS into the Kernel and Enabling the AFS Initialization Script</A>, which have you reboot the machine. Assuming that the
1573 machine's AFS initialization script is configured to invoke the
1574 <B>bosserver</B> command as specified in <I>IBM AFS Quick
1575 Beginnings</I>, the BOS Server starts itself and then the other AFS server
1576 processes listed in its local <B>/usr/afs/local/BosConfig</B> file.
1577 <P>There are two circumstances in which you must incorporate the kernel
1578 extensions and reboot now rather than later:
1579 <UL>
1580 <P><LI>You are upgrading the File Server on an HP-UX machine
1581 <P><LI>The machine also serves as a client, you upgraded the client files in the
1582 previous step, and you want the new Cache Manager to become operative right
1583 away
1584 </UL>
1585 <P>In any other circumstances, you can choose to upgrade the kernel extensions
1586 later. Choose one of the following options:
1587 <UL>
1588 <P><LI>Restart all server processes by issuing the <B>bos restart</B> command
1589 with the <B>-bosserver</B> flag.
1590 <PRE>   # <B>bos restart</B> &lt;<VAR>machine&nbsp;name</VAR>> <B>-localauth -bosserver</B>
1591 </PRE>
1592 <P><LI>Wait to start using the new binaries until the processes restart
1593 automatically at the binary restart time specified in the
1594 <B>/usr/afs/local/BosConfig</B> file.
1595 </UL>
1596 <P><LI><A NAME="LISV-UP-PRUNE"></A>Once you are satisfied that the machine is functioning
1597 correctly at AFS 3.6, there is no need to retain previous versions of
1598 the server binaries in the <B>/usr/afs/bin</B> directory. (You can
1599 always use the <B>bos install</B> command to reinstall them if it becomes
1600 necessary to downgrade). If you use the Update Server, the
1601 <B>upclientbin</B> process renamed them with a <B>.old</B>
1602 extension in Step <A HREF="#LISVUP-UPCLIENTBIN">1</A>. To reclaim the disk space occupied in the
1603 <B>/usr/afs/bin</B> directory by <B>.bak</B> and
1604 <B>.old</B> files, you can use the following command:
1605 <PRE>   # <B>bos prune</B> &lt;<VAR>machine&nbsp;name</VAR>> <B>-bak -old -localauth</B>
1606 </PRE>
1607 <P>Step <A HREF="#LISV-BIN-NEWDIRS">5</A> of <A HREF="#HDRSV-BIN">Distributing Binaries to Server Machines</A> had you move the previous version of the
1608 binaries to the <B>/usr/afs/bin.old</B> directory. You can
1609 also remove that directory on any machine where you created it.
1610 <PRE>   # <B>rm -rf  /usr/afs/bin.old</B>
1611 </PRE>
1612 </OL>
1613 <P><H3><A NAME="HDRCLI-UP" HREF="aurns002.htm#ToC_34">Upgrading Client Machines</A></H3>
1614 <OL TYPE=1>
1615 <P><LI>Become the local superuser <B>root</B>, if you are not already, by
1616 issuing the <B>su</B> command.
1617 <PRE>   % <B>su root</B>
1618    Password: <VAR>root_password</VAR>
1619 </PRE>
1620 <P><LI>Prepare to access client files using the method you have selected from
1621 those listed in <A HREF="#HDRGETBIN">Obtaining the Binary Distribution</A>:
1622 <UL>
1623 <P><LI>If you copied the contents of the <B>root.client</B> directory
1624 into AFS (in Step <A HREF="#LISTOREBIN-CLIENT">6</A> of <A HREF="#HDRSTOREBIN">Storing Binaries in AFS</A>), change directory as indicated.
1625 <PRE>   # <B>cd /afs/</B><VAR>cellname</VAR><B>/</B><VAR>sysname</VAR><B>/usr/afsws/root.client</B>
1626 </PRE>
1627 <P><LI>If copying files from the CD-ROM, mount the CD-ROM for this machine's
1628 system type on the local <B>/cdrom</B> directory. For instructions
1629 on mounting CD-ROMs (either locally or remotely via NFS), consult the
1630 operating system documentation. Then change directory as
1631 indicated.
1632 <PRE>   # <B>cd /cdrom/</B><VAR>sysname</VAR><B>/root.client</B>
1633 </PRE>
1634 <P><LI>If accessing the distribution electronically, you possibly already
1635 downloaded it in <A HREF="#HDRSTOREBIN">Storing Binaries in AFS</A>. If so, it is still in the <VAR>temp_afs36_dir</VAR>
1636 directory. If not, download it and run any commands necessary to
1637 uncompress or unpack the distribution. Place it in a temporary location
1638 (<VAR>temp_afs36_dir</VAR>), and change directory to the indicated
1639 subdirectory.
1640 <PRE>   # <B>cd</B>  <VAR>temp_afs36_dir</VAR><B>/root.client</B>
1641 </PRE>
1642 </UL>
1643 <P><LI>Copy the AFS 3.6 version of the <B>afsd</B> binary and other
1644 files to the <B>/usr/vice/etc</B> directory.
1645 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">Some files in the <B>/usr/vice/etc</B> directory, such as the AFS
1646 initialization file (called <B>afs.rc</B> on many system types), do
1647 not necessarily need to change for a new release. It is a good policy
1648 to compare the contents of the distribution directory and the
1649 <B>/usr/vice/etc</B> directory before performing the copying
1650 operation. If there are files in the <B>/usr/vice/etc</B> directory
1651 that you created for AFS 3.5 or 3.6 Beta and that you want to
1652 retain, either move them to a safe location before performing the following
1653 instructions, or alter the following instructions to copy over only the
1654 appropriate files.
1655 </TD></TR></TABLE>
1656 <PRE>   # <B>cp  -p  usr/vice/etc/*   /usr/vice/etc</B>
1657
1658    # <B>cp  -rp  usr/vice/etc/C  /usr/vice/etc</B>
1659 </PRE>
1660 <P>If you have not yet incorporated AFS into the machine's authentication
1661 system, perform the instructions in the section titled <I>Enabling AFS
1662 Login</I> for this system type in the <I>IBM AFS Quick Beginnings</I>
1663 chapter about configuring client machines. If this machine was running
1664 the same operating system revision with AFS 3.5 or AFS 3.6 Beta,
1665 you presumably already incorporated AFS into its authentication system.
1666 <P><LI>Perform the instructions in <A HREF="#HDRKERNEL">Incorporating AFS into the Kernel and Enabling the AFS Initialization Script</A> to incorporate AFS extensions into the kernel. The
1667 instructions conclude with a reboot of the machine, which starts the new Cache
1668 Manager.
1669 </OL>
1670 <P><H3><A NAME="HDRKERNEL" HREF="aurns002.htm#ToC_35">Incorporating AFS into the Kernel and Enabling the AFS Initialization Script</A></H3>
1671 <P>As part of upgrading a machine to AFS 3.6, you must
1672 incorporate AFS 3.6 extensions into its kernel and verify that the AFS
1673 initialization script is included in the machine's startup
1674 sequence. Proceed to the instructions for your system type:
1675 <UL>
1676 <P><LI><A HREF="#HDRKERN_AIX">Loading AFS into the AIX Kernel</A>
1677 <P><LI><A HREF="#HDRKERN_DUX">Building AFS into the Digital UNIX Kernel</A>
1678 <P><LI><A HREF="#HDRKERN_HP">Building AFS into the HP-UX Kernel</A>
1679 <P><LI><A HREF="#HDRKERN_IRIX">Incorporating AFS into the IRIX Kernel</A>
1680 <P><LI><A HREF="#HDRKERN_LNX">Loading AFS into the Linux Kernel</A>
1681 <P><LI><A HREF="#HDRKERN_SOL">Loading AFS into the Solaris Kernel</A>
1682 </UL>
1683 <P><H3><A NAME="HDRKERN_AIX" HREF="aurns002.htm#ToC_36">Loading AFS into the AIX Kernel</A></H3>
1684 <P>The AIX kernel extension facility is the dynamic kernel
1685 loader provided by IBM Corporation. AIX does not support incorporation
1686 of AFS modifications during a kernel build.
1687 <P>For AFS to function correctly, the kernel extension facility must run each
1688 time the machine reboots, so the AFS initialization script (included in the
1689 AFS distribution) invokes it automatically. In this section you copy
1690 the script to the conventional location and edit it to select the appropriate
1691 options depending on whether NFS is also to run.
1692 <P>After editing the script, you verify that there is an entry in the AIX
1693 <B>inittab</B> file that invokes it, then reboot the machine to
1694 incorporate the new AFS extensions into the kernel and restart the Cache
1695 Manager.
1696 <OL TYPE=1>
1697 <P><LI>Access the AFS distribution by changing directory as indicated.
1698 Substitute <B>rs_aix42</B> for the <VAR>sysname</VAR> variable.
1699 <UL>
1700 <P><LI>If you copied the contents of the <B>root.client</B> directory
1701 into AFS (in Step <A HREF="#LISTOREBIN-CLIENT">6</A> of <A HREF="#HDRSTOREBIN">Storing Binaries in AFS</A>), change directory as indicated.
1702 <PRE>   # <B>cd /afs/</B><VAR>cellname</VAR><B>/</B><VAR>sysname</VAR><B>/usr/afsws/root.client</B>
1703 </PRE>
1704 <P><LI>If copying files from the CD-ROM, mount the CD-ROM for this machine's
1705 system type on the local <B>/cdrom</B> directory. For instructions
1706 on mounting CD-ROMs (either locally or remotely via NFS), consult the
1707 operating system documentation. Then change directory as
1708 indicated.
1709 <PRE>   # <B>cd /cdrom/</B><VAR>sysname</VAR><B>/root.client</B>
1710 </PRE>
1711 <P><LI>If accessing the distribution electronically, you possibly already
1712 downloaded it in <A HREF="#HDRSTOREBIN">Storing Binaries in AFS</A>. If so, it is still in the <VAR>temp_afs36_dir</VAR>
1713 directory. If not, download it and run any commands necessary to
1714 uncompress or unpack the distribution. Place it in a temporary location
1715 (<VAR>temp_afs36_dir</VAR>), and change directory to the indicated
1716 subdirectory.
1717 <PRE>   # <B>cd</B>  <VAR>temp_afs36_dir</VAR><B>/root.client</B>
1718 </PRE>
1719 </UL>
1720 <P><LI>Copy the AFS kernel library files to the local
1721 <B>/usr/vice/etc/dkload</B> directory.
1722 <PRE>   # <B>cd  usr/vice/etc</B>
1723
1724    # <B>cp -rp  dkload  /usr/vice/etc</B>
1725 </PRE>
1726 <P><LI>Because you ran AFS 3.5 on this machine, the appropriate AFS
1727 initialization file possibly already exists as
1728 <B>/etc/rc.afs</B>. Compare it to the version in the
1729 <B>root.client/usr/vice/etc</B> directory of the AFS 3.6
1730 distribution to see if any changes are needed.
1731 <P>If the initialization file is not already in place, copy it now.
1732 <PRE>   # <B>cp -p  rc.afs  /etc/rc.afs</B>
1733 </PRE>
1734 <P><LI>Edit the <B>/etc/rc.afs</B> script, setting the <TT>NFS</TT>
1735 variable if it is not already.
1736 <UL>
1737 <P><LI>If the machine is not to function as an NFS/AFS Translator, set the NFS
1738 variable as follows:
1739 <PRE>   NFS=$NFS_NONE
1740 </PRE>
1741 <P><LI>If the machine is to function as an NFS/AFS Translator and is running AIX
1742 4.2.1 or higher, set the NFS variable as follows. Only
1743 sites that have a license for the NFS/AFS Translator are allowed to run
1744 translator machines. Machines running the base level of AIX 4.2
1745 cannot be translator machines.
1746 <P>NFS must already be loaded into the kernel. It is loaded
1747 automatically on machines running AIX 4.1.1 and later, as long
1748 as the file <B>/etc/exports</B> exists.
1749 <PRE>   NFS=$NFS_IAUTH
1750 </PRE>
1751 </UL>
1752 <P><LI>Place the following line in the AIX initialization file,
1753 <B>/etc/inittab</B>, if it is not already. It invokes the AFS
1754 initialization script and needs to appear just after the line that starts NFS
1755 daemons.
1756 <PRE>   rcafs:2:wait:/etc/rc.afs > /dev/console 2>&amp;1 # Start AFS services
1757 </PRE>
1758 <P><LI><B>(Optional)</B> There are now copies of the AFS initialization file
1759 in both the <B>/usr/vice/etc</B> and <B>/etc</B> directories.
1760 If you want to avoid potential confusion by guaranteeing that they are always
1761 the same, create a link between them. You can always retrieve the
1762 original script from the AFS distribution if necessary.
1763 <PRE>   # <B>cd  /usr/vice/etc</B>
1764
1765    # <B>rm  rc.afs</B>
1766
1767    # <B>ln -s  /etc/rc.afs</B>
1768 </PRE>
1769 <P><LI>Reboot the machine.
1770 <PRE>      # <B>shutdown -r now</B>
1771 </PRE>
1772 <P><LI>If you are upgrading a server machine, login again as the local superuser
1773 <B>root</B>, then return to Step <A HREF="#LISV-UP-PRUNE">6</A> in <A HREF="#HDRSV-UP">Upgrading Server Machines</A>.
1774 <PRE>   login: <B>root</B>
1775    Password: <VAR>root_password</VAR>
1776 </PRE>
1777 </OL>
1778 <P><H3><A NAME="HDRKERN_DUX" HREF="aurns002.htm#ToC_37">Building AFS into the Digital UNIX Kernel</A></H3>
1779 <P>On Digital UNIX machines, you must build AFS
1780 modifications into a new static kernel; Digital UNIX does not support
1781 dynamic loading. If the machine's hardware and software
1782 configuration exactly matches another Digital UNIX machine on which AFS
1783 3.6 is already built into the kernel, you can choose to copy the kernel
1784 from that machine to this one. In general, however, it is better to
1785 build AFS modifications into the kernel on each machine according to the
1786 following instructions.
1787 <P>If the machine was running a version of Digital UNIX 4.0 with a
1788 previous version of AFS, the configuration changes specified in Step <A HREF="#LIDUX-CONFAFS">1</A> through Step <A HREF="#LIDUX-VFSCONF">4</A> are presumably already in place.
1789 <OL TYPE=1>
1790 <P><LI><A NAME="LIDUX-CONFAFS"></A>Create a copy called <B>AFS</B> of the basic kernel
1791 configuration file included in the Digital UNIX distribution as
1792 <B>/usr/sys/conf/</B><VAR>machine_name</VAR>, where <VAR>machine_name</VAR> is
1793 the machine's hostname in all uppercase letters.
1794 <PRE>   # <B>cd /usr/sys/conf</B>
1795
1796    # <B>cp</B> <VAR>machine_name</VAR> <B>AFS</B>
1797 </PRE>
1798 <P><LI>Add AFS to the list of options in the configuration file you created in
1799 the previous step, so that the result looks like the following:
1800 <PRE>          .                   .
1801           .                   .
1802        options               UFS
1803        options               NFS
1804        options               AFS
1805           .                   .
1806           .                   .
1807 </PRE>
1808 <P><LI>Add an entry for AFS to two places in the <B>/usr/sys/conf/files</B>
1809 file.
1810 <UL>
1811 <P><LI>Add a line for AFS to the list of <TT>OPTIONS</TT>, so that the result
1812 looks like the following:
1813 <PRE>             .              .        .
1814              .              .        .
1815       OPTIONS/nfs        optional nfs define_dynamic
1816       OPTIONS/afs        optional afs define_dynamic
1817       OPTIONS/cdfs       optional cdfs define_dynamic
1818              .              .        .
1819              .              .        .
1820 </PRE>
1821 <P><LI>Add an entry for AFS to the list of <TT>MODULES</TT>, so that the result
1822 looks like the following:
1823 <PRE>             .            .        .          .
1824              .            .        .          .
1825       #
1826       MODULE/nfs_server         optional nfs_server Binary
1827       nfs/nfs_server.c          module nfs_server optimize -g3
1828       nfs/nfs3_server.c         module nfs_server optimize -g3
1829       #
1830       MODULE/afs                optional afs Binary
1831       afs/libafs.c              module afs
1832       #
1833 </PRE>
1834 </UL>
1835 <P><LI><A NAME="LIDUX-VFSCONF"></A>Add an entry for AFS to two places in the
1836 <B>/usr/sys/vfs/vfs_conf.c</B> file.
1837 <UL>
1838 <P><LI>Add AFS to the list of defined file systems, so that the result looks like
1839 the following:
1840 <PRE>        .       .
1841         .       .
1842      #include &lt;afs.h>
1843      #if defined(AFS) &amp;&amp; AFS
1844             extern struct vfsops afs_vfsops;
1845      #endif
1846         .       .
1847         .       .
1848 </PRE>
1849 <P><LI>Put a declaration for AFS in the <B>vfssw[]</B> table's
1850 MOUNT_ADDON slot, so that the result looks like the following:
1851 <PRE>        .                          .              .
1852         .                          .              .
1853       &amp;fdfs_vfsops,         "fdfs",   /* 12 = MOUNT_FDFS */
1854    #if  defined(AFS)
1855       &amp;afs_vfsops,          "afs",
1856    #else
1857       (struct vfsops *)0,   "",       /* 13 = MOUNT_ADDON */
1858    #endif
1859    #if NFS &amp;&amp; INFS_DYNAMIC
1860        &amp;nfs3_vfsops,        "nfsv3",  /* 14 = MOUNT_NFS3 */
1861 </PRE>
1862 </UL>
1863 <P><LI>Access the AFS distribution by changing directory as indicated.
1864 Substitute <B>alpha_dux40</B> for the <VAR>sysname</VAR> variable.
1865 <UL>
1866 <P><LI>If you copied the contents of the <B>root.client</B> directory
1867 into AFS (in Step <A HREF="#LISTOREBIN-CLIENT">6</A> of <A HREF="#HDRSTOREBIN">Storing Binaries in AFS</A>), change directory as indicated.
1868 <PRE>   # <B>cd /afs/</B><VAR>cellname</VAR><B>/</B><VAR>sysname</VAR><B>/usr/afsws/root.client</B>
1869 </PRE>
1870 <P><LI>If copying files from the CD-ROM, mount the CD-ROM for this machine's
1871 system type on the local <B>/cdrom</B> directory. For instructions
1872 on mounting CD-ROMs (either locally or remotely via NFS), consult the
1873 operating system documentation. Then change directory as
1874 indicated.
1875 <PRE>   # <B>cd /cdrom/</B><VAR>sysname</VAR><B>/root.client</B>
1876 </PRE>
1877 <P><LI>If accessing the distribution electronically, you possibly already
1878 downloaded it in <A HREF="#HDRSTOREBIN">Storing Binaries in AFS</A>. If so, it is still in the <VAR>temp_afs36_dir</VAR>
1879 directory. If not, download it and run any commands necessary to
1880 uncompress or unpack the distribution. Place it in a temporary location
1881 (<VAR>temp_afs36_dir</VAR>), and change directory to the indicated
1882 subdirectory.
1883 <PRE>   # <B>cd</B>  <VAR>temp_afs36_dir</VAR><B>/root.client</B>
1884 </PRE>
1885 </UL>
1886 <P><LI>Because you ran AFS 3.5 on this machine, the appropriate AFS
1887 initialization file possibly already exists as
1888 <B>/sbin/init.d/afs</B>. Compare it to the version in the
1889 <B>root.client/usr/vice/etc</B> directory of the AFS 3.6
1890 distribution to see if any changes are needed.
1891 <P>If the initialization file is not already in place, copy it now.
1892 Note the removal of the <B>.rc</B> extension as you copy.
1893 <PRE>    # <B>cp  -p  usr/vice/etc/afs.rc  /sbin/init.d/afs</B>
1894 </PRE>
1895 <P><LI>Copy the AFS kernel module to the local <B>/usr/sys/BINARY</B>
1896 directory.
1897 <P>The AFS 3.6 distribution includes only the
1898 <B>libafs.nonfs.o</B> version of the library, because
1899 Digital UNIX machines are not supported as NFS/AFS Translator machines.
1900 <PRE>   # <B>cp  -p  bin/libafs.nonfs.o  /usr/sys/BINARY/afs.mod</B>
1901 </PRE>
1902 <P><LI>Configure and build the kernel. Respond to any prompts by pressing
1903 &lt;<B>Return</B>>. The resulting kernel is in the file
1904 <B>/sys/AFS/vmunix</B>.
1905 <PRE>   # <B>doconfig -c AFS</B>
1906 </PRE>
1907 <P><LI>Rename the existing kernel file and copy the new, AFS-modified file to the
1908 standard location.
1909 <PRE>   # <B>mv  /vmunix  /vmunix_orig</B>
1910
1911    # <B>cp  -p  /sys/AFS/vmunix  /vmunix</B>
1912 </PRE>
1913 <P><LI>Verify the existence of the symbolic links specified in the following
1914 commands, which incorporate the AFS initialization script into the Digital
1915 UNIX startup and shutdown sequence. If necessary, issue the commands to
1916 create the links.
1917 <PRE>   # <B>ln -s  ../init.d/afs  /sbin/rc3.d/S67afs</B>
1918
1919    # <B>ln -s  ../init.d/afs  /sbin/rc0.d/K66afs</B>
1920 </PRE>
1921 <P><LI><B>(Optional)</B> If the machine is configured as a client, there are
1922 now copies of the AFS initialization file in both the <B>/usr/vice/etc</B>
1923 and <B>/sbin/init.d</B> directories. If you want to avoid
1924 potential confusion by guaranteeing that they are always the same, create a
1925 link between them. You can always retrieve the original script from the
1926 AFS distribution if necessary.
1927 <PRE>   # <B>cd  /usr/vice/etc</B>
1928
1929    # <B>rm  afs.rc</B>
1930
1931    # <B>ln -s  /sbin/init.d/afs  afs.rc</B>
1932 </PRE>
1933 <P><LI>Reboot the machine.
1934 <PRE>   # <B>shutdown -r now</B>
1935 </PRE>
1936 <P><LI>If you are upgrading a server machine, login again as the local superuser
1937 <B>root</B>, then return to Step <A HREF="#LISV-UP-PRUNE">6</A> in <A HREF="#HDRSV-UP">Upgrading Server Machines</A>.
1938 <PRE>   login: <B>root</B>
1939    Password: <VAR>root_password</VAR>
1940 </PRE>
1941 </OL>
1942 <P><H3><A NAME="HDRKERN_HP" HREF="aurns002.htm#ToC_38">Building AFS into the HP-UX Kernel</A></H3>
1943 <P>On HP-UX machines, you must build AFS modifications into a
1944 new kernel; HP-UX does not support dynamic loading. If the
1945 machine's hardware and software configuration exactly matches another
1946 HP-UX machine on which AFS 3.6 is already built into the kernel, you
1947 can choose to copy the kernel from that machine to this one. In
1948 general, however, it is better to build AFS modifications into the kernel on
1949 each machine according to the following instructions.
1950 <OL TYPE=1>
1951 <P><LI>Move the existing kernel-related files to a safe location.
1952 <PRE>   # <B>cp -p  /stand/vmunix  /stand/vmunix.noafs</B>
1953
1954    # <B>cp -p  /stand/system  /stand/system.noafs</B>
1955 </PRE>
1956 <P><LI>Access the AFS distribution by changing directory as indicated.
1957 Substitute <B>hp_ux110</B> for the <VAR>sysname</VAR> variable.
1958 <UL>
1959 <P><LI>If you copied the contents of the <B>root.client</B> directory
1960 into AFS (in Step <A HREF="#LISTOREBIN-CLIENT">6</A> of <A HREF="#HDRSTOREBIN">Storing Binaries in AFS</A>), change directory as indicated.
1961 <PRE>   # <B>cd /afs/</B><VAR>cellname</VAR><B>/</B><VAR>sysname</VAR><B>/usr/afsws/root.client</B>
1962 </PRE>
1963 <P><LI>If copying files from the CD-ROM, mount the CD-ROM for this machine's
1964 system type on the local <B>/cdrom</B> directory. For instructions
1965 on mounting CD-ROMs (either locally or remotely via NFS), consult the
1966 operating system documentation. Then change directory as
1967 indicated.
1968 <PRE>   # <B>cd /cdrom/</B><VAR>sysname</VAR><B>/root.client</B>
1969 </PRE>
1970 <P><LI>If accessing the distribution electronically, you possibly already
1971 downloaded it in <A HREF="#HDRSTOREBIN">Storing Binaries in AFS</A>. If so, it is still in the <VAR>temp_afs36_dir</VAR>
1972 directory. If not, download it and run any commands necessary to
1973 uncompress or unpack the distribution. Place it in a temporary location
1974 (<VAR>temp_afs36_dir</VAR>), and change directory to the indicated
1975 subdirectory.
1976 <PRE>   # <B>cd</B>  <VAR>temp_afs36_dir</VAR><B>/root.client</B>
1977 </PRE>
1978 </UL>
1979 <P><LI>Because you ran AFS 3.5 on this machine, the appropriate AFS
1980 initialization file possibly already exists as
1981 <B>/sbin/init.d/afs</B>. Compare it to the version in the
1982 <B>root.client/usr/vice/etc</B> directory of the AFS 3.6
1983 distribution to see if any changes are needed.
1984 <P>If the initialization file is not already in place, copy it now.
1985 Note the removal of the <B>.rc</B> extension as you copy.
1986 <PRE>   # <B>cp  -p  usr/vice/etc/afs.rc  /sbin/init.d/afs</B>
1987 </PRE>
1988 <P><LI>Copy the file <B>afs.driver</B> to the local
1989 <B>/usr/conf/master.d</B> directory, changing its name to
1990 <B>afs</B> as you do so.
1991 <PRE>   # <B>cp  -p  usr/vice/etc/afs.driver  /usr/conf/master.d/afs</B>
1992 </PRE>
1993 <P><LI>Copy the AFS kernel module to the local <B>/usr/conf/lib</B>
1994 directory.
1995 <P>HP-UX machines are not supported as NFS/AFS Translator machines, so AFS
1996 3.6 includes only libraries called
1997 <B>libafs.nonfs.a</B> (for the 32-bit version of
1998 HP-UX) and <B>libafs64.nonfs.a</B> (for the 64-bit
1999 version of HP-UX). Change the library's name to
2000 <B>libafs.a</B> as you copy it.
2001 <P>For the 32-bit version of HP-UX:
2002 <PRE>   # <B>cp  -p   bin/libafs.nonfs.a   /usr/conf/lib/libafs.a</B>
2003 </PRE>
2004 <P>For the 64-bit version of HP-UX:
2005 <PRE>   # <B>cp  -p  bin/libafs64.nonfs.a   /usr/conf/lib/libafs.a</B>
2006 </PRE>
2007 <P><LI>Verify the existence of the symbolic links specified in the following
2008 commands, which incorporate the AFS initialization script into the HP-UX
2009 startup and shutdown sequence. If necessary, issue the commands to
2010 create the links.
2011 <PRE>   # <B>ln -s ../init.d/afs /sbin/rc2.d/S460afs</B>
2012
2013    # <B>ln -s ../init.d/afs /sbin/rc2.d/K800afs</B>
2014 </PRE>
2015 <P><LI><B>(Optional)</B> If the machine is configured as a client, there are
2016 now copies of the AFS initialization file in both the <B>/usr/vice/etc</B>
2017 and <B>/sbin/init.d</B> directories. If you want to avoid
2018 potential confusion by guaranteeing that they are always the same, create a
2019 link between them. You can always retrieve the original script from the
2020 AFS distribution if necessary.
2021 <PRE>   # <B>cd /usr/vice/etc</B>
2022
2023    # <B>rm afs.rc</B>
2024
2025    # <B>ln -s  /sbin/init.d/afs  afs.rc</B>
2026 </PRE>
2027 <P><LI>Incorporate the AFS driver into the kernel, either using the
2028 <B>SAM</B> program or a series of individual commands. Both methods
2029 reboot the machine, which loads the new kernel and starts the Cache
2030 Manager.
2031 <UL>
2032 <P><LI>To use the <B>SAM</B> program:
2033 <OL TYPE=a>
2034 <P><LI>Invoke the <B>SAM</B> program, specifying the hostname of the local
2035 machine as <VAR>local_hostname</VAR>. The <B>SAM</B> graphical user
2036 interface pops up.
2037 <PRE>    # <B>sam -display</B> <VAR>local_hostname</VAR><B>:0</B>
2038 </PRE>
2039 <P><LI>Choose the <B>Kernel Configuration</B> icon, then the
2040 <B>Drivers</B> icon. From the list of drivers, select
2041 <B>afs</B>.
2042 <P><LI>Open the pull-down <B>Actions</B> menu and choose the <B>Add Driver
2043 to Kernel</B> option.
2044 <P><LI>Open the <B>Actions</B> menu again and choose the <B>Create a New
2045 Kernel</B> option.
2046 <P><LI>Confirm your choices by choosing <B>Yes</B> and <B>OK</B> when
2047 prompted by subsequent pop-up windows. The <B>SAM</B> program
2048 builds the kernel and reboots the system.
2049 <P><LI>Login again as the superuser <B>root</B>.
2050 <PRE>   login: <B>root</B>
2051    Password: <VAR>root_password</VAR>
2052 </PRE>
2053 </OL>
2054 <P><LI>To use individual commands:
2055 <OL TYPE=a>
2056 <P><LI>Edit the file <B>/stand/system</B>, adding an entry for <B>afs</B>
2057 to the <TT>Subsystems</TT> section.
2058 <P><LI>Change to the <B>/stand/build</B> directory and issue the
2059 <B>mk_kernel</B> command to build the kernel.
2060 <PRE>   # <B>cd /stand/build</B>
2061
2062    # <B>mk_kernel</B>
2063 </PRE>
2064 <P><LI>Move the new kernel to the standard location (<B>/stand/vmunix</B>),
2065 reboot the machine to start using it, and login again as the superuser
2066 <B>root</B>.
2067 <PRE>   # <B>mv /stand/build/vmunix_test /stand/vmunix</B>
2068
2069    # <B>cd /</B>
2070
2071    # <B>shutdown -r now</B>
2072
2073    login: <B>root</B>
2074    Password: <VAR>root_password</VAR>
2075 </PRE>
2076 </OL>
2077 </UL>
2078 <P><LI>If you are upgrading a server machine, login again as the local superuser
2079 <B>root</B>, then return to Step <A HREF="#LISV-UP-PRUNE">6</A> in <A HREF="#HDRSV-UP">Upgrading Server Machines</A>.
2080 <PRE>   login: <B>root</B>
2081    Password: <VAR>root_password</VAR>
2082 </PRE>
2083 </OL>
2084 <P><H3><A NAME="HDRKERN_IRIX" HREF="aurns002.htm#ToC_39">Incorporating AFS into the IRIX Kernel</A></H3>
2085 <P>To incorporate AFS into the kernel on IRIX machines,
2086 choose one of two methods:
2087 <UL>
2088 <P><LI>Dynamic loading using the <B>ml</B> program distributed by Silicon
2089 Graphics, Incorporated (SGI).
2090 <P><LI>Building a new static kernel. Proceed to <A HREF="#HDRBUILD-IRIX">Building AFS into the IRIX Kernel</A>.
2091 </UL>
2092 <P><H4><A NAME="Header_40">Loading AFS into the IRIX Kernel</A></H4>
2093 <P>The <B>ml</B> program is the dynamic kernel loader provided by SGI
2094 for IRIX systems. If you use it rather than building AFS modifications
2095 into a static kernel, then for AFS to function correctly the <B>ml</B>
2096 program must run each time the machine reboots. Therefore, the AFS
2097 initialization script (included on the AFS CD-ROM) invokes it automatically
2098 when the <B>afsml</B> configuration variable is activated. In this
2099 section you activate the variable and run the script.
2100 <OL TYPE=1>
2101 <P><LI>Issue the <B>uname -m</B> command to determine the machine's CPU
2102 type. The <B>IP</B><VAR>xx</VAR> value in the output must match one
2103 of the supported CPU types listed in <A HREF="#HDRSYSTYPES">Supported System Types</A>.
2104 <PRE>   # <B>uname -m</B>
2105 </PRE>
2106 <P><LI>Access the AFS distribution by changing directory as indicated.
2107 Substitute <B>sgi_65</B> for the <VAR>sysname</VAR> variable.
2108 <UL>
2109 <P><LI>If you copied the contents of the <B>root.client</B> directory
2110 into AFS (in Step <A HREF="#LISTOREBIN-CLIENT">6</A> of <A HREF="#HDRSTOREBIN">Storing Binaries in AFS</A>), change directory as indicated.
2111 <PRE>   # <B>cd /afs/</B><VAR>cellname</VAR><B>/</B><VAR>sysname</VAR><B>/usr/afsws/root.client</B>
2112 </PRE>
2113 <P><LI>If copying files from the CD-ROM, mount the CD-ROM for this machine's
2114 system type on the local <B>/cdrom</B> directory. For instructions
2115 on mounting CD-ROMs (either locally or remotely via NFS), consult the
2116 operating system documentation. Then change directory as
2117 indicated.
2118 <PRE>   # <B>cd /cdrom/</B><VAR>sysname</VAR><B>/root.client</B>
2119 </PRE>
2120 <P><LI>If accessing the distribution electronically, you possibly already
2121 downloaded it in <A HREF="#HDRSTOREBIN">Storing Binaries in AFS</A>. If so, it is still in the <VAR>temp_afs36_dir</VAR>
2122 directory. If not, download it and run any commands necessary to
2123 uncompress or unpack the distribution. Place it in a temporary location
2124 (<VAR>temp_afs36_dir</VAR>), and change directory to the indicated
2125 subdirectory.
2126 <PRE>   # <B>cd</B>  <VAR>temp_afs36_dir</VAR><B>/root.client</B>
2127 </PRE>
2128 </UL>
2129 <P><LI>Copy the appropriate AFS kernel library file to the local
2130 <B>/usr/vice/etc/sgiload</B> directory; the <B>IP</B><VAR>xx</VAR>
2131 portion of the library file name must match the value returned by the
2132 <B>uname -m</B> command. Also choose the file appropriate to
2133 whether the machine's kernel supports NFS server functionality (NFS must
2134 be supported for the machine to act as an NFS/AFS Translator). Single-
2135 and multiprocessor machines use the same library file.
2136 <P>You can choose to copy all of the kernel library files into the
2137 <B>/usr/vice/etc/sgiload</B> directory, but they require a significant
2138 amount of space.
2139 <PRE>   # <B>cd  usr/vice/etc/sgiload</B>
2140 </PRE>
2141 <P>If the machine is not to act as an NFS/AFS translator:
2142 <PRE>   # <B>cp -p  libafs.IP<VAR>xx</VAR>.nonfs.o  /usr/vice/etc/sgiload</B>
2143 </PRE>
2144 <P>If the machine is to act as an NFS/AFS translator, in which case its kernel
2145 must support NFS server functionality:
2146 <PRE>   # <B>cp -p   libafs.IP<VAR>xx</VAR>.o   /usr/vice/etc/sgiload</B>
2147 </PRE>
2148 <P><LI>Proceed to <A HREF="#HDRIRIX-SCRIPT">Enabling the AFS Initialization Script on IRIX Systems</A>.
2149 </OL>
2150 <P><H4><A NAME="HDRBUILD-IRIX">Building AFS into the IRIX Kernel</A></H4>
2151 <P>If you prefer to build a kernel, and the machine's
2152 hardware and software configuration exactly matches another IRIX machine on
2153 which AFS 3.6 is already built into the kernel, you can choose to copy
2154 the kernel from that machine to this one. In general, however, it is
2155 better to build AFS modifications into the kernel on each machine according to
2156 the following instructions.
2157 <OL TYPE=1>
2158 <P><LI>Access the AFS distribution by changing directory as indicated.
2159 Substitute <B>sgi_65</B> for the <VAR>sysname</VAR> variable.
2160 <UL>
2161 <P><LI>If you copied the contents of the <B>root.client</B> directory
2162 into AFS (in Step <A HREF="#LISTOREBIN-CLIENT">6</A> of <A HREF="#HDRSTOREBIN">Storing Binaries in AFS</A>), change directory as indicated.
2163 <PRE>   # <B>cd /afs/</B><VAR>cellname</VAR><B>/</B><VAR>sysname</VAR><B>/usr/afsws/root.client</B>
2164 </PRE>
2165 <P><LI>If copying files from the CD-ROM, mount the CD-ROM for this machine's
2166 system type on the local <B>/cdrom</B> directory. For instructions
2167 on mounting CD-ROMs (either locally or remotely via NFS), consult the
2168 operating system documentation. Then change directory as
2169 indicated.
2170 <PRE>   # <B>cd /cdrom/</B><VAR>sysname</VAR><B>/root.client</B>
2171 </PRE>
2172 <P><LI>If accessing the distribution electronically, you possibly already
2173 downloaded it in <A HREF="#HDRSTOREBIN">Storing Binaries in AFS</A>. If so, it is still in the <VAR>temp_afs36_dir</VAR>
2174 directory. If not, download it and run any commands necessary to
2175 uncompress or unpack the distribution. Place it in a temporary location
2176 (<VAR>temp_afs36_dir</VAR>), and change directory to the indicated
2177 subdirectory.
2178 <PRE>   # <B>cd</B>  <VAR>temp_afs36_dir</VAR><B>/root.client</B>
2179 </PRE>
2180 </UL>
2181 <P><LI>Issue the <B>uname -m</B> command to determine the machine's CPU
2182 type. The <B>IP</B><VAR>xx</VAR> value in the output must match one
2183 of the supported CPU types listed in the <I>IBM AFS Release Notes</I> for
2184 the current version of AFS.
2185 <PRE>   # <B>uname -m</B>
2186 </PRE>
2187 <P><LI>Copy the appropriate AFS kernel library file to the local file
2188 <B>/var/sysgen/boot/afs.a</B>; the <B>IP</B><VAR>xx</VAR>
2189 portion of the library file name must match the value returned by the
2190 <B>uname -m</B> command. Also choose the file appropriate to
2191 whether the machine's kernel supports NFS server functionality (NFS must
2192 be supported for the machine to act as an NFS/AFS Translator). Single-
2193 and multiprocessor machines use the same library file.
2194 <PRE>   # <B>cd  bin</B>
2195 </PRE>
2196 <P>If the machine is not to act as an NFS/AFS translator:
2197 <PRE>   # <B>cp -p  libafs.IP<VAR>xx</VAR>.nonfs.a   /var/sysgen/boot/afs.a</B>
2198 </PRE>
2199 <P>If the machine is to act as an NFS/AFS translator, in which case its kernel
2200 must support NFS server functionality:
2201 <PRE>   # <B>cp -p   libafs.IP<VAR>xx</VAR>.a   /var/sysgen/boot/afs.a</B>
2202 </PRE>
2203 <P><LI>Copy the kernel initialization file <B>afs.sm</B> to the local
2204 <B>/var/sysgen/system</B> directory, and the kernel master file
2205 <B>afs</B> to the local <B>/var/sysgen/master.d</B>
2206 directory.
2207 <PRE>   # <B>cp -p  afs.sm  /var/sysgen/system</B>
2208
2209    # <B>cp -p  afs  /var/sysgen/master.d</B>
2210 </PRE>
2211 <P><LI>Copy the existing kernel file, <B>/unix</B>, to a safe location and
2212 compile the new kernel. It is created as
2213 <B>/unix.install</B>, and overwrites the existing <B>/unix</B>
2214 file when the machine reboots.
2215 <PRE>   # <B>cp -p  /unix  /unix_orig</B>
2216
2217    # <B>autoconfig</B>
2218 </PRE>
2219 <P><LI>Proceed to <A HREF="#HDRIRIX-SCRIPT">Enabling the AFS Initialization Script on IRIX Systems</A>.
2220 </OL>
2221 <P><H4><A NAME="HDRIRIX-SCRIPT">Enabling the AFS Initialization Script on IRIX Systems</A></H4>
2222 <OL TYPE=1>
2223 <P><LI>Because you ran AFS 3.5 on this machine, the appropriate AFS
2224 initialization file possibly already exists as
2225 <B>/etc/init.d/afs</B>. Compare it to the version in the
2226 <B>root.client/usr/vice/etc</B> directory of the AFS 3.6
2227 distribution to see if any changes are needed.
2228 <P>If the initialization file is not already in place, copy it now. If
2229 the machine is configured as a client machine, you already copied the script
2230 to the local <B>/usr/vice/etc</B> directory. Otherwise, change
2231 directory as indicated, substituting <B>sgi_65</B> for the
2232 <VAR>sysname</VAR> variable.
2233 <UL>
2234 <P><LI>If you copied the contents of the <B>root.client</B> directory
2235 into AFS (in Step <A HREF="#LISTOREBIN-CLIENT">6</A> of <A HREF="#HDRSTOREBIN">Storing Binaries in AFS</A>), change directory as indicated.
2236 <PRE>   # <B>cd /afs/</B><VAR>cellname</VAR><B>/</B><VAR>sysname</VAR><B>/usr/afsws/root.client</B>
2237 </PRE>
2238 <P><LI>If copying files from the CD-ROM, mount the CD-ROM for this machine's
2239 system type on the local <B>/cdrom</B> directory. For instructions
2240 on mounting CD-ROMs (either locally or remotely via NFS), consult the
2241 operating system documentation. Then change directory as
2242 indicated.
2243 <PRE>   # <B>cd /cdrom/</B><VAR>sysname</VAR><B>/root.client</B>
2244 </PRE>
2245 <P><LI>If accessing the distribution electronically, you possibly already
2246 downloaded it in <A HREF="#HDRSTOREBIN">Storing Binaries in AFS</A>. If so, it is still in the <VAR>temp_afs36_dir</VAR>
2247 directory. If not, download it and run any commands necessary to
2248 uncompress or unpack the distribution. Place it in a temporary location
2249 (<VAR>temp_afs36_dir</VAR>), and change directory to the indicated
2250 subdirectory.
2251 <PRE>   # <B>cd</B>  <VAR>temp_afs36_dir</VAR><B>/root.client</B>
2252 </PRE>
2253 </UL>
2254 <P>Now copy the script. Note the removal of the <B>.rc</B>
2255 extension as you copy.
2256 <PRE>   # <B>cp -p</B>  <VAR>script_location</VAR><B>/afs.rc  /etc/init.d/afs</B>
2257 </PRE>
2258 <P><LI>If the <B>afsml</B> configuration variable is not already set
2259 appropriately, issue the <B>chkconfig</B> command.
2260 <P>If you are using the <B>ml</B> program:
2261 <PRE>   # <B>/etc/chkconfig -f afsml on</B>
2262 </PRE>
2263 <P>If you built AFS into a static kernel:
2264 <PRE>   # <B>/etc/chkconfig -f afsml off</B>
2265 </PRE>
2266 <P>If the machine is to function as an NFS/AFS Translator, the kernel supports
2267 NFS server functionality, and the <B>afsxnfs</B> variable is not already
2268 set appropriately, set it now.
2269 <PRE>   # <B>/etc/chkconfig -f afsxnfs on</B>
2270 </PRE>
2271 <P><LI>Verify the existence of the symbolic links specified in the following
2272 commands, which incorporate the AFS initialization script into the IRIX
2273 startup and shutdown sequence. If necessary, issue the commands to
2274 create the links.
2275 <PRE>   # <B>ln -s ../init.d/afs /etc/rc2.d/S35afs</B>
2276
2277    # <B>ln -s ../init.d/afs /etc/rc0.d/K35afs</B>
2278 </PRE>
2279 <P><LI><B>(Optional)</B> If the machine is configured as a client, there are
2280 now copies of the AFS initialization file in both the <B>/usr/vice/etc</B>
2281 and <B>/etc/init.d</B> directories. If you want to avoid
2282 potential confusion by guaranteeing that they are always the same, create a
2283 link between them. You can always retrieve the original script from the
2284 AFS distribution if necessary.
2285 <PRE>   # <B>cd /usr/vice/etc</B>
2286
2287    # <B>rm afs.rc</B>
2288
2289    # <B>ln -s  /etc/init.d/afs  afs.rc</B>
2290 </PRE>
2291 <P><LI>Reboot the machine.
2292 <P>
2293 <PRE>   # <B>shutdown -i6 -g0 -y</B>
2294 </PRE>
2295 <P><LI>If you are upgrading a server machine, login again as the local superuser
2296 <B>root</B>, then return to Step <A HREF="#LISV-UP-PRUNE">6</A> in <A HREF="#HDRSV-UP">Upgrading Server Machines</A>.
2297 <PRE>   login: <B>root</B>
2298    Password: <VAR>root_password</VAR>
2299 </PRE>
2300 </OL>
2301 <P><H3><A NAME="HDRKERN_LNX" HREF="aurns002.htm#ToC_43">Loading AFS into the Linux Kernel</A></H3>
2302 <P>The <B>insmod</B> program is the dynamic kernel
2303 loader for Linux. Linux does not support incorporation of AFS
2304 modifications during a kernel build.
2305 <P>For AFS to function correctly, the <B>insmod</B> program must run each
2306 time the machine reboots, so the AFS initialization script (included on the
2307 AFS CD-ROM) invokes it automatically. The script also includes commands
2308 that select the appropriate AFS library file automatically. In this
2309 section you run the script.
2310 <OL TYPE=1>
2311 <P><LI>Access the AFS distribution by changing directory as indicated.
2312 Substitute <B>i386_linux22</B> for the <VAR>sysname</VAR> variable.
2313 <UL>
2314 <P><LI>If you copied the contents of the <B>root.client</B> directory
2315 into AFS (in Step <A HREF="#LISTOREBIN-CLIENT">6</A> of <A HREF="#HDRSTOREBIN">Storing Binaries in AFS</A>), change directory as indicated.
2316 <PRE>   # <B>cd /afs/</B><VAR>cellname</VAR><B>/</B><VAR>sysname</VAR><B>/usr/afsws/root.client</B>
2317 </PRE>
2318 <P><LI>If copying files from the CD-ROM, mount the CD-ROM for this machine's
2319 system type on the local <B>/cdrom</B> directory. For instructions
2320 on mounting CD-ROMs (either locally or remotely via NFS), consult the
2321 operating system documentation. Then change directory as
2322 indicated.
2323 <PRE>   # <B>cd /cdrom/</B><VAR>sysname</VAR><B>/root.client</B>
2324 </PRE>
2325 <P><LI>If accessing the distribution electronically, you possibly already
2326 downloaded it in <A HREF="#HDRSTOREBIN">Storing Binaries in AFS</A>. If so, it is still in the <VAR>temp_afs36_dir</VAR>
2327 directory. If not, download it and run any commands necessary to
2328 uncompress or unpack the distribution. Place it in a temporary location
2329 (<VAR>temp_afs36_dir</VAR>), and change directory to the indicated
2330 subdirectory.
2331 <PRE>   # <B>cd</B>  <VAR>temp_afs36_dir</VAR><B>/root.client</B>
2332 </PRE>
2333 </UL>
2334 <P><LI>Copy the AFS kernel library files to the local
2335 <B>/usr/vice/etc/modload</B> directory. The filenames for the
2336 libraries have the format
2337 <B>libafs-</B><VAR>version</VAR><B>.o</B>, where <VAR>version</VAR>
2338 indicates the kernel build level. The string <B>.mp</B> in
2339 the <VAR>version</VAR> indicates that the file is appropriate for use with
2340 symmetric multiprocessor (SMP) kernels.
2341 <PRE>   # <B>cd  usr/vice/etc</B>
2342
2343    # <B>cp -rp  modload  /usr/vice/etc</B>
2344 </PRE>
2345 <P><LI>The AFS 3.6 distribution includes a new AFS initialization file
2346 that can select automatically from the kernel extensions included in AFS
2347 3.6. Copy it to the <B>/etc/rc.d/init.d</B>
2348 directory, removing the <B>.rc</B> extension as you do.
2349 <PRE>   # <B>cp -p   afs.rc  /etc/rc.d/init.d/afs</B>
2350 </PRE>
2351 <P>The <B>afsd</B> options file possibly already exists as
2352 <B>/etc/sysconfig/afs</B> from running a previous version of AFS on this
2353 machine. Compare it to the version in the
2354 <B>root.client/usr/vice/etc</B> directory of the AFS 3.6
2355 distribution to see if any changes are needed.
2356 <P>If the options file is not already in place, copy it now. Note the
2357 removal of the <B>.conf</B> extension as you copy.
2358 <PRE>   # <B>cp  -p  afs.conf  /etc/sysconfig/afs</B>
2359 </PRE>
2360 <P>If necessary, edit the options file to invoke the desired arguments on the
2361 <B>afsd</B> command in the initialization script. For further
2362 information, see the section titled <I>Configuring the Cache Manager</I>
2363 in the <I>IBM AFS Quick Beginnings</I> chapter about configuring client
2364 machines.
2365 <P><LI>Issue the <B>chkconfig</B> command to activate the <B>afs</B>
2366 configuration variable, if it is not already. Based on the instruction
2367 in the AFS initialization file that begins with the string
2368 <TT>#chkconfig</TT>, the command automatically creates the symbolic links
2369 that incorporate the script into the Linux startup and shutdown
2370 sequence.
2371 <PRE>   # <B>/sbin/chkconfig  --add afs</B>
2372 </PRE>
2373 <P><LI><B>(Optional)</B> If the machine is configured as a client, there are
2374 now copies of the AFS initialization file in both the <B>/usr/vice/etc</B>
2375 and <B>/etc/init.d</B> directories, and copies of the
2376 <B>afsd</B> options file in both the <B>/usr/vice/etc</B> and
2377 <B>/etc/sysconfig</B> directories. If you want to avoid potential
2378 confusion by guaranteeing that the two copies of each file are always the
2379 same, create a link between them. You can always retrieve the original
2380 script or options file from the AFS distribution if necessary.
2381 <PRE>   # <B>cd /usr/vice/etc</B>
2382
2383    # <B>rm afs.rc afs.conf</B>
2384
2385    # <B>ln -s  /etc/rc.d/init.d/afs  afs.rc</B>
2386
2387    # <B>ln -s  /etc/sysconfig/afs  afs.conf</B>
2388 </PRE>
2389 <P><LI>Reboot the machine.
2390 <PRE>   # <B>shutdown -r now</B>
2391 </PRE>
2392 <P><LI>If you are upgrading a server machine, login again as the local superuser
2393 <B>root</B>, then return to Step <A HREF="#LISV-UP-PRUNE">6</A> in <A HREF="#HDRSV-UP">Upgrading Server Machines</A>.
2394 <PRE>   login: <B>root</B>
2395    Password: <VAR>root_password</VAR>
2396 </PRE>
2397 </OL>
2398 <P><H3><A NAME="HDRKERN_SOL" HREF="aurns002.htm#ToC_44">Loading AFS into the Solaris Kernel</A></H3>
2399 <P>The <B>modload</B> program is the dynamic kernel
2400 loader provided by Sun Microsystems for Solaris systems. Solaris does
2401 not support incorporation of AFS modifications during a kernel build.
2402 <P>For AFS to function correctly, the <B>modload</B> program must run each
2403 time the machine reboots, so the AFS initialization script (included on the
2404 AFS CD-ROM) invokes it automatically. In this section you copy the
2405 appropriate AFS library file to the location where the <B>modload</B>
2406 program accesses it and then run the script.
2407 <OL TYPE=1>
2408 <P><LI>Access the AFS distribution by changing directory as indicated.
2409 Substitute <B>sun4x_56</B> or <B>sun4x_57</B> for the <VAR>sysname</VAR>
2410 variable.
2411 <UL>
2412 <P><LI>If you copied the contents of the <B>root.client</B> directory
2413 into AFS (in Step <A HREF="#LISTOREBIN-CLIENT">6</A> of <A HREF="#HDRSTOREBIN">Storing Binaries in AFS</A>), change directory as indicated.
2414 <PRE>   # <B>cd /afs/</B><VAR>cellname</VAR><B>/</B><VAR>sysname</VAR><B>/usr/afsws/root.client</B>
2415 </PRE>
2416 <P><LI>If copying files from the CD-ROM, mount the CD-ROM for this machine's
2417 system type on the local <B>/cdrom</B> directory. For instructions
2418 on mounting CD-ROMs (either locally or remotely via NFS), consult the
2419 operating system documentation. Then change directory as
2420 indicated.
2421 <PRE>   # <B>cd /cdrom/</B><VAR>sysname</VAR><B>/root.client</B>
2422 </PRE>
2423 <P><LI>If accessing the distribution electronically, you possibly already
2424 downloaded it in <A HREF="#HDRSTOREBIN">Storing Binaries in AFS</A>. If so, it is still in the <VAR>temp_afs36_dir</VAR>
2425 directory. If not, download it and run any commands necessary to
2426 uncompress or unpack the distribution. Place it in a temporary location
2427 (<VAR>temp_afs36_dir</VAR>), and change directory to the indicated
2428 subdirectory.
2429 <PRE>   # <B>cd</B>  <VAR>temp_afs36_dir</VAR><B>/root.client</B>
2430 </PRE>
2431 </UL>
2432 <P><LI>If this machine is running Solaris 2.6 or the 32-bit version
2433 of Solaris 7, and ran that operating system with AFS 3.5, the
2434 appropriate AFS initialization file possibly already exists as
2435 <B>/etc/init.d/afs</B>. Compare it to the version in the
2436 <B>root.client/usr/vice/etc</B> directory of the AFS 3.6
2437 distribution to see if any changes are needed.
2438 <P>If this machine is running the 64-bit version of Solaris 7, the AFS
2439 initialization file differs from the AFS 3.5 version. Copy it
2440 from the AFS 3.6 distribution.
2441 <P>Note the removal of the <B>.rc</B> extension as you copy.
2442 <PRE>   # <B>cd  usr/vice/etc</B>
2443
2444    # <B>cp  -p  afs.rc  /etc/init.d/afs</B>
2445 </PRE>
2446 <P><LI>Copy the appropriate AFS kernel library file to the appropriate file in a
2447 subdirectory of the local <B>/kernel/fs</B> directory.
2448 <P>If the machine is running Solaris 2.6 or the 32-bit version of
2449 Solaris 7 and is not to act as an NFS/AFS translator:
2450 <PRE>   # <B>cp  -p  modload/libafs.nonfs.o  /kernel/fs/afs</B>
2451 </PRE>
2452 <P>If the machine is running Solaris 2.6 or the 32-bit version of
2453 Solaris 7 and is to act as an NFS/AFS translator, in which case its kernel
2454 must support NFS server functionality and the <B>nfsd</B> process must be
2455 running:
2456 <PRE>   # <B>cp  -p  modload/libafs.o  /kernel/fs/afs</B>
2457 </PRE>
2458 <P>If the machine is running the 64-bit version of Solaris 7 and is not
2459 to act as an NFS/AFS translator:
2460 <PRE>   # <B>cp  -p  modload/libafs64.nonfs.o  /kernel/fs/sparcv9/afs</B>
2461 </PRE>
2462 <P>If the machine is running the 64-bit version of Solaris 7 and is to
2463 act as an NFS/AFS translator, in which case its kernel must support NFS server
2464 functionality and the <B>nfsd</B> process must be running:
2465 <PRE>   # <B>cp  -p  modload/libafs64.o  /kernel/fs/sparcv9/afs</B>
2466 </PRE>
2467 <P><LI>Verify the existence of the symbolic links specified in the following
2468 commands, which incorporate the AFS initialization script into the Solaris
2469 startup and shutdown sequence. If necessary, issue the commands to
2470 create the links.
2471 <PRE>   # <B>ln -s ../init.d/afs /etc/rc3.d/S99afs</B>
2472
2473    # <B>ln -s ../init.d/afs /etc/rc0.d/K66afs</B>
2474 </PRE>
2475 <P><LI><B>(Optional)</B> If the machine is configured as a client, there are
2476 now copies of the AFS initialization file in both the <B>/usr/vice/etc</B>
2477 and <B>/etc/init.d</B> directories. If you want to avoid
2478 potential confusion by guaranteeing that they are always the same, create a
2479 link between them. You can always retrieve the original script from the
2480 AFS distribution if necessary.
2481 <PRE>   # <B>cd /usr/vice/etc</B>
2482
2483    # <B>rm afs.rc</B>
2484
2485    # <B>ln -s  /etc/init.d/afs  afs.rc</B>
2486 </PRE>
2487 <P><LI>Reboot the machine.
2488 <PRE>   # <B>shutdown -i6 -g0 -y</B>
2489 </PRE>
2490 <P><LI>If you are upgrading a server machine, login again as the local superuser
2491 <B>root</B>, then return to Step <A HREF="#LISV-UP-PRUNE">6</A> in <A HREF="#HDRSV-UP">Upgrading Server Machines</A>.
2492 <PRE>   login: <B>root</B>
2493    Password: <VAR>root_password</VAR>
2494 </PRE>
2495 </OL>
2496 <HR><H2><A NAME="HDRDOC_VOL" HREF="aurns002.htm#ToC_45">Storing AFS Documents in AFS</A></H2>
2497 <P>This section explains how to create and mount a volume to
2498 house AFS documents. The recommended mount point for the volume is
2499 <B>/afs/</B><VAR>cellname</VAR><B>/afsdoc</B>. If you ran AFS
2500 3.5, the volume possibly already exists. You can choose to
2501 overwrite its contents with the AFS 3.6 version of documents, or can
2502 create a new volume for the AFS 3.6 documents and mount it at
2503 <B>/afs/</B><VAR>cellname</VAR><B>/afsdoc</B> instead of the volume of
2504 AFS 3.5 documents. Alter the following instructions as
2505 necessary.
2506 <P>If you wish, you can create a link to the mount point on each client
2507 machine's local disk, called <B>/usr/afsdoc</B>.
2508 Alternatively, you can create a link to the mount point in each user's
2509 home directory. You can also choose to permit users to access only
2510 certain documents (most probably, the <I>IBM AFS User Guide</I>) by
2511 creating different mount points or setting different ACLs on different
2512 document directories.
2513 <P>To create a new volume for storing AFS documents:
2514 <OL TYPE=1>
2515 <P><LI>Issue the <B>vos create</B> command to create a volume for storing the
2516 AFS documentation. Include the <B>-maxquota</B> argument to set an
2517 unlimited quota on the volume.
2518 <P>If you wish, you can set the volume's quota to a finite value after
2519 you complete the copying operations. At that point, use the <B>vos
2520 examine</B> command to determine how much space the volume is
2521 occupying. Then issue the <B>fs setquota</B> command to set a quota
2522 value that is slightly larger.
2523 <PRE>   % <B>vos create</B> &lt;<VAR>machine&nbsp;name</VAR>> &lt;<VAR>partition&nbsp;name</VAR>>  <B>afsdoc  -maxquota 0</B>
2524 </PRE>
2525 <P><LI>Issue the <B>fs mkmount</B> command to mount the new volume. If
2526 your <B>root.cell</B> volume is replicated, you must precede the
2527 <I>cellname</I> with a period to specify the read/write mount point, as
2528 shown. Then issue the <B>vos release</B> command to release a new
2529 replica of the <B>root.cell</B> volume, and the <B>fs
2530 checkvolumes</B> command to force the local Cache Manager to access
2531 them.
2532 <PRE>   % <B>fs mkmount -dir /afs/.</B><VAR>cellname</VAR><B>/afsdoc</B> <B>-vol</B> <B>afsdoc</B>
2533
2534    % <B>vos release root.cell</B>
2535
2536    % <B>fs checkvolumes</B>
2537 </PRE>
2538 <P><LI>Issue the <B>fs setacl</B> command to grant the <B>rl</B>
2539 permissions to the <B>system:anyuser</B> group on the new
2540 directory's ACL.
2541 <PRE>   % <B>cd /afs/.</B><VAR>cellname</VAR><B>/afsdoc</B>
2542
2543    % <B>fs setacl  .  system:anyuser rl</B>
2544 </PRE>
2545 <P><LI>Access the documents via one of the sources listed in <A HREF="#HDRDOC">Accessing the AFS Binary Distribution and Documentation</A>. Copy the documents in one more formats from a
2546 <VAR>source_format</VAR> directory into subdirectories of the
2547 <B>/afs/</B><VAR>cellname</VAR><B>/afsdoc</B> directory. Repeat
2548 the commands for each format. Suggested substitutions for the
2549 <VAR>format_name</VAR> variable are <B>HTML</B> and <B>PDF</B>.
2550 <PRE>   # <B>mkdir</B> <VAR>format_name</VAR>
2551
2552    # <B>cd</B>  <VAR>format_name</VAR>
2553
2554    # <B>cp -rp /cdrom/Documentation/</B><VAR>language_code</VAR><B>/</B><VAR>source_format</VAR>  <B>.</B>
2555 </PRE>
2556 <P>If you copy the HTML version of the documents, note that in addition to a
2557 subdirectory for each document there are several files with a
2558 <B>.gif</B> extension, which enable readers to move easily between
2559 sections of a document. The file called <B>index.htm</B> is
2560 an introductory HTML page that has a hyperlink to the documents. For
2561 HTML viewing to work properly, these files must remain in the top-level HTML
2562 directory (the one named, for example,
2563 <B>/afs/</B><VAR>cellname</VAR><B>/afsdoc/Html</B>).
2564 <P><LI><B>(Optional)</B> If you believe it is helpful to your users to access
2565 AFS documents via a local disk directory, create <B>/usr/afsdoc</B> on the
2566 local disk as a symbolic link to the directory housing the desired format
2567 (probably HTML or PDF).
2568 <PRE>   # <B>ln -s /afs/</B><VAR>cellname</VAR><B>/afsdoc/</B><VAR>format_name</VAR>  <B>/usr/afsdoc</B>
2569 </PRE>
2570 <P>An alternative is to create a link in each user's home directory to
2571 the documentation directory in AFS.
2572 </OL>
2573 <HR><H2><A NAME="HDRREFPAGES" HREF="aurns002.htm#ToC_46">Reference Pages</A></H2>
2574 <P>Following are reference pages that include new
2575 information not included in <I>IBM AFS Administration
2576 Reference</I>.
2577 <P>
2578 <H3><A NAME="HDRCFG" HREF="aurns002.htm#ToC_47">CFG_<I>tcid</I></A></H3>
2579 <P><STRONG>Purpose</STRONG>
2580 <P>Defines Tape Coordinator configuration instructions for automated tape
2581 devices, backup data files, or XBSA server programs
2582 <P><STRONG>Description</STRONG>
2583 <P>A <B>CFG_</B><VAR>tcid</VAR> file includes instructions that configure a
2584 Tape Coordinator for more automated operation and for transferring AFS data to
2585 and from a certain type of backup media:
2586 <UL>
2587 <P><LI>An automated tape device, such as a stacker or jukebox. The file is
2588 optional for a Tape Coordinator that writes to such a device, and unnecessary
2589 if the default value for all types of instruction are appropriate for the
2590 device.
2591 <P><LI>A <I>backup data file</I> on a local disk device. The
2592 configuration file is mandatory and must include the <B>FILE</B>
2593 instruction at least.
2594 <P><LI>A third-party backup utility that implements the Open Group's Backup
2595 Service API (XBSA), hereafter referred to as an <I>XBSA server</I>.
2596 The file is mandatory and must include the <B>SERVER</B>, <B>TYPE</B>,
2597 and <B>PASSFILE</B> or <B>PASSWORD</B> instructions. The
2598 General Availability release of AFS 3.6 can communicate with one XBSA
2599 server, the Tivoli Storage Manager (TSM).
2600 </UL>
2601 <P>The configuration file is in ASCII-format and must reside in the
2602 <B>/usr/afs/backup</B> directory on the Tape Coordinator machine.
2603 Each Tape Coordinator has its own configuration file (multiple Tape
2604 Coordinators cannot use the same file), and only a single Tape Coordinator in
2605 a cell can write to a given tape device or backup data file. Multiple
2606 Tape Coordinators can interact with the same XBSA server if the server has
2607 sufficient capacity, and in this case the configuration file for each Tape
2608 Coordinator refers to the same XBSA server.
2609 <P>The Tape Coordinator for a tape device or backup data file must also have
2610 an entry in the Backup Database and in the
2611 <B>/usr/afs/backup/tapeconfig</B> file on the Tape Coordinator
2612 machine. The Tape Coordinator for an XBSA server has only an entry in
2613 the Backup Database, not in the <B>tapeconfig</B> file.
2614 <P><B>Naming the Configuration File</B>
2615 <P>For a Tape Coordinator that communicates with an XBSA server, the
2616 <VAR>tcid</VAR> portion of the configuration file's name is the Tape
2617 Coordinator's port offset number as defined in the Backup
2618 Database. An example filename is <B>CFG_22</B>.
2619 <P>For the Tape Coordinator for a tape device or backup data file, there are
2620 two possible types of values for the <VAR>tcid</VAR> portion of the
2621 filename. The Tape Coordinator first attempts to open a file with a
2622 <VAR>tcid</VAR> portion that is the Tape Coordinator's port offset number
2623 as defined in the Backup Database and <B>tapeconfig</B> file. If
2624 there is no such file, the Tape Coordinator attempts to access a file with a
2625 <VAR>tcid</VAR> portion that is based on the tape device's device name the
2626 backup data file's filename. To enable the Tape Coordinator to
2627 locate the file, construct the <VAR>tcid</VAR> portion of the filename as
2628 follows:
2629 <UL>
2630 <P><LI>For a tape device, strip off the initial <B>/dev/</B> string from the
2631 device name, and replace any other slashes in the name with
2632 underscores. For example, <B>CFG_rmt_4m</B> is the appropriate
2633 filename for a device called <B>/dev/rmt/4m</B>.
2634 <P><LI>For a backup data file, strip off the initial slash (/) and replace any
2635 other slashes in the name with underscores. For example,
2636 <B>CFG_var_tmp_FILE</B> is the appropriate filename for a backup data file
2637 called <B>/var/tmp/FILE</B>.
2638 </UL>
2639 <P><B>Summary of Instructions</B>
2640 <P>The following list briefly describes the instructions that can appear in a
2641 configuration file. Each instruction appears on its own line, in any
2642 order. Unless otherwise noted, the instructions apply to all backup
2643 media (automated tape device, backup data file, and XBSA server). A
2644 more detailed description of each instruction follows the list.
2645 <DL>
2646 <P><DT><B>ASK
2647 </B><DD>Controls whether the Tape Coordinator prompts for guidance when it
2648 encounters error conditions.
2649 <P><DT><B>AUTOQUERY
2650 </B><DD>Controls whether the Tape Coordinator prompts for the first tape.
2651 Does not apply to XBSA servers.
2652 <P><DT><B>BUFFERSIZE
2653 </B><DD>Sets the size of the memory buffer the Tape Coordinator uses when dumping
2654 data to or restoring data from a backup medium.
2655 <P><DT><B>CENTRALLOG
2656 </B><DD>Names a log file in which to record a status message as each dump or
2657 restore operation completes. The Tape Coordinator also writes to its
2658 standard log and error files.
2659 <P><DT><B>FILE
2660 </B><DD>Determines whether the Tape Coordinator uses a backup data file as the
2661 backup medium.
2662 <P><DT><B>GROUPID
2663 </B><DD>Sets an identification number recorded in the Backup Database for all
2664 dumps performed by the Tape Coordinator.
2665 <P><DT><B>LASTLOG
2666 </B><DD>Controls whether the Tape Coordinator creates and writes to a separate log
2667 file during its final pass through the set of volumes to be included in a
2668 dump.
2669 <P><DT><B>MAXPASS
2670 </B><DD>Specifies how many times the Tape Coordinator attempts to access a volume
2671 during a dump operation if the volume is inaccessible on the first attempt
2672 (which is included in the count).
2673 <P><DT><B>MGMTCLASS
2674 </B><DD>Specifies which of an XBSA server's management classes to use, which
2675 often indicates the type of backup medium the XBSA server uses. Applies
2676 only to XBSA servers.
2677 <P><DT><B>MOUNT
2678 </B><DD>Identifies the file that contains routines for inserting tapes into a tape
2679 device or controlling how the Tape Coordinator handles a backup data
2680 file. Does not apply to XBSA servers.
2681 <P><DT><B>NAME_CHECK
2682 </B><DD>Controls whether the Tape Coordinator verifies that a tape or backup data
2683 file has the expected name. Does not apply to XBSA servers.
2684 <P><DT><B>NODE
2685 </B><DD>Names which node associated with an XBSA server to use. Applies
2686 only to XBSA servers.
2687 <P><DT><B>PASSFILE
2688 </B><DD>Names the file that contains the password or security code for the Tape
2689 Coordinator to pass to an XBSA server. Applies only to XBSA
2690 servers.
2691 <P><DT><B>PASSWORD
2692 </B><DD>Specifies the password or security code for the Tape Coordinator to pass
2693 to an XBSA server. Applies only to XBSA servers.
2694 <P><DT><B>SERVER
2695 </B><DD>Names the XBSA server machine with which the Tape Coordinator
2696 communicates. Applies only to XBSA servers.
2697 <P><DT><B>STATUS
2698 </B><DD>Controls how often the Tape Coordinator writes a status message in its
2699 window during an operation.
2700 <P><DT><B>TYPE
2701 </B><DD>Defines which XBSA-compliant program (third-party backup utility) is
2702 running on the XBSA server. Applies only to XBSA servers.
2703 <P><DT><B>UNMOUNT
2704 </B><DD>Identifies the file that contains routines for removing tapes from a tape
2705 device or controlling how the Tape Coordinator handles a backup data
2706 file. Does not apply to XBSA servers.
2707 </DL>
2708 <P><B>The ASK Instruction</B>
2709 <P>The <B>ASK</B> instruction takes a boolean value as its argument, in
2710 the following format:
2711 <PRE>   ASK {<B>YES</B> | <B>NO</B>}
2712 </PRE>
2713 <P>When the value is <B>YES</B>, the Tape Coordinator generates a prompt
2714 in its window, requesting a response to the error cases described in the
2715 following list. This is the default behavior if the <B>ASK</B>
2716 instruction does not appear in the <B>CFG_</B><VAR>tcid</VAR> file.
2717 <P>When the value is <B>NO</B>, the Tape Coordinator does not prompt in
2718 error cases, but instead uses the automatic default responses described in the
2719 following list. The Tape Coordinator also logs the error in its
2720 <B>/usr/afs/backup/TE_</B><VAR>tcid</VAR> file. Suppressing the
2721 prompts enables the Tape Coordinator to run unattended, though it still
2722 prompts for insertion of tapes unless the <B>MOUNT</B> instruction is
2723 used.
2724 <P>The error cases controlled by this instruction are the following:
2725 <UL>
2726 <P><LI>The Backup System is unable to dump a volume while running the <B>backup
2727 dump</B> command. With a <B>YES</B> value, the Tape Coordinator
2728 prompts to offer three choices: try to dump the volume again
2729 immediately, omit the volume from the dump but continue the operation, or
2730 terminate the operation. With a <B>NO</B> value, the Tape
2731 Coordinator omits the volume from the dump and continues the operation.
2732 <P><LI>The Backup System is unable to restore a volume while running the
2733 <B>backup diskrestore</B>, <B>backup volrestore</B>, or <B>backup
2734 volsetrestore</B> command. With a <B>YES</B> value, the Tape
2735 Coordinator prompts to offer two choices: omit the volume and continue
2736 restoring the other volumes, or terminate the operation. With a
2737 <B>NO</B> value, it continues the operation without prompting, omitting
2738 the problematic volume but restoring the remaining ones.
2739 <P><LI>The Backup System cannot determine if the dump set includes any more
2740 tapes, while running the <B>backup scantape</B> command (the reference
2741 page for that command discusses possible reasons for this problem).
2742 With a <B>YES</B> value, the Tape Coordinator prompts to ask if there are
2743 more tapes to scan. With a <B>NO</B> value, it proceeds as though
2744 there are more tapes and invokes the routine named by the <B>MOUNT</B>
2745 instruction in the configuration file, or prompts the operator to insert the
2746 next tape.
2747 <P><LI>The Backup System determines that the tape contains an unexpired dump
2748 while running the <B>backup labeltape</B> command. With a
2749 <B>YES</B> value, the Tape Coordinator prompts to offer two choices:
2750 continue or terminate the labeling operation. With a <B>NO</B>
2751 value, it terminates the operation without relabeling the tape.
2752 </UL>
2753 <P><B>The AUTOQUERY Instruction</B>
2754 <P>The <B>AUTOQUERY</B> instruction takes a boolean value as its argument,
2755 in the following format:
2756 <PRE>   AUTOQUERY {<B>YES</B> | <B>NO</B>}
2757 </PRE>
2758 <P>When the value is <B>YES</B>, the Tape Coordinator checks for the
2759 <B>MOUNT</B> instruction in the configuration file when it needs to read
2760 the first tape involved in an operation. As described for that
2761 instruction, it then either prompts for the tape or invokes the specified
2762 routine to mount the tape. This is the default behavior if the
2763 <B>AUTOQUERY</B> instruction does not appear in the configuration
2764 file.
2765 <P>When the value is <B>NO</B>, the Tape Coordinator assumes that the
2766 first tape required for an operation is already in the drive. It does
2767 not prompt the operator or invoke the <B>MOUNT</B> routine unless there is
2768 an error in accessing the first tape. This setting is equivalent in
2769 effect to including the <B>-noautoquery</B> flag to the <B>butc</B>
2770 command.
2771 <P>Note that the setting of the <B>AUTOQUERY</B> instruction controls the
2772 Tape Coordinator's behavior only with respect to the first tape required
2773 for an operation. For subsequent tapes, the Tape Coordinator always
2774 checks for the <B>MOUNT</B> instruction. It also refers to the
2775 <B>MOUNT</B> instruction if it encounters an error while attempting to
2776 access the first tape. The instruction does not apply to XBSA
2777 servers.
2778 <P><B>The BUFFERSIZE Instruction</B>
2779 <P>The <B>BUFFERSIZE</B> instruction takes an integer or decimal value,
2780 and optionally units, in the following format:
2781 <PRE>   BUFFERSIZE <VAR>size</VAR>[{<B>k</B> | <B>K</B> | <B>m</B> | <B>M</B> | <B>g</B> | <B>G</B> | <B>t</B> | <B>T</B>}]
2782 </PRE>
2783 <P>where <VAR>size</VAR> specifies the amount of memory the Tape Coordinator
2784 allocates to use as a buffer during both dump and restore operations.
2785 If <VAR>size</VAR> is a decimal number, the number of digits after the decimal
2786 point must not translate to fractions of bytes. The default unit is
2787 bytes, but use <B>k</B> or <B>K</B> to specify kilobytes, <B>m</B>
2788 or <B>M</B> for megabytes, <B>g</B> or <B>G</B> for gigabytes, and
2789 <B>t</B> or <B>T</B> for terabytes. There is no space between
2790 the <VAR>size</VAR> value and the units letter.
2791 <P>As the Tape Coordinator receives volume data from the Volume Server during
2792 a dump operation, it gathers the specified amount of data in the buffer before
2793 transferring the entire amount to the backup medium. Similarly, during
2794 a restore operation the Tape Coordinator by default buffers data from the
2795 backup medium before transferring the entire amount to the Volume Server for
2796 restoration into the file system.
2797 <P>The default buffer size is 16 KB, which is usually large enough to promote
2798 tape streaming in a normal network configuration. If the network
2799 connection between the Tape Coordinator machine and file server machines is
2800 slow, it can help to increase the buffer size.
2801 <P>For XBSA servers, the range of acceptable values is <B>1K</B> through
2802 <B>64K</B>. For tape devices and backup data files, the minimum
2803 acceptable value is <B>16K</B>, and if the specified value is not a
2804 multiple of 16 KB, the Tape Coordinator automatically rounds it up to the next
2805 such multiple.
2806 <P><B>The CENTRALLOG Instruction</B>
2807 <P>The <B>CENTRALLOG</B> instruction takes a pathname as its argument, in
2808 the following format:
2809 <PRE>   CENTRALLOG  <VAR>filename</VAR>
2810 </PRE>
2811 <P>where <VAR>filename</VAR> is the full pathname of a local disk file in which
2812 to record a status message as each dump or restore operation completes.
2813 It is acceptable to have multiple Tape Coordinators write to the same log
2814 file. Each Tape Coordinator also writes to its own standard error and
2815 log files (the <B>TE_</B><VAR>tcid</VAR> and <B>TL_</B><VAR>tcid</VAR>
2816 files in the <B>/usr/afs/backup</B> directory). This instruction is
2817 always optional.
2818 <P>The line for each dump operation has the following format:
2819 <PRE>   <VAR>task_ID</VAR>   <VAR>start_time</VAR>   <VAR>complete_time</VAR>   <VAR>duration</VAR>  <VAR>volume_set</VAR>  \
2820          <VAR>success</VAR> of <VAR>total</VAR> volumes dumped (<VAR>data_dumped</VAR> KB)
2821 </PRE>
2822 <P>The line for each restore operation has the following format:
2823 <PRE>   <VAR>task_ID</VAR>   <VAR>start_time</VAR>   <VAR>complete_time</VAR>   <VAR>duration</VAR>  <VAR>success</VAR> of <VAR>total</VAR> volumes restored
2824 </PRE>
2825 <P>where
2826 <DL>
2827 <P><DT><B><VAR>task_ID</VAR>
2828 </B><DD>Is the task identification number assigned to the operation by the Tape
2829 Coordinator. The first digits in the number are the Tape
2830 Coordinator's port offset number.
2831 <P><DT><B><VAR>start_time</VAR>
2832 </B><DD>The time at which the operation started, in the format
2833 <VAR>month</VAR>/<VAR>day</VAR>/<VAR>year</VAR>
2834 <VAR>hours</VAR>:<VAR>minutes</VAR>:<VAR>seconds</VAR>.
2835 <P><DT><B><VAR>complete_time</VAR>
2836 </B><DD>Is the time at which the operation completed, in the same format as the
2837 <VAR>start_time</VAR> field.
2838 <P><DT><B><VAR>duration</VAR>
2839 </B><DD>Is the amount of time it took to complete the operation, in the format
2840 <VAR>hours</VAR>:<VAR>minutes</VAR>:<VAR>seconds</VAR>.
2841 <P><DT><B><VAR>volume_set</VAR>
2842 </B><DD>Is the name of the volume set being dumped during this operation (for dump
2843 operations only).
2844 <P><DT><B><VAR>success</VAR>
2845 </B><DD>Is the number of volumes successfully dumped or restored.
2846 <P><DT><B><VAR>total</VAR>
2847 </B><DD>Is the total number of volumes the Tape Coordinator attempted to dump or
2848 restore.
2849 <P><DT><B><VAR>data_dumped</VAR>
2850 </B><DD>Is the number of kilobytes of data transferred to the backup medium (for
2851 dump operations only).
2852 </DL>
2853 <P><B>The FILE Instruction</B>
2854 <P>The <B>FILE</B> instruction takes a boolean value as its argument, in
2855 the following format:
2856 <PRE>   FILE {<B>NO</B> | <B>YES</B>}
2857 </PRE>
2858 <P>When the value is <B>NO</B> and the <B>SERVER</B> instruction does
2859 not appear in the configuration file, the Tape Coordinator uses a tape device
2860 as the backup medium. If the <B>SERVER</B> instruction does appear,
2861 the Tape Coordinator communicates with the XBSA server that it names.
2862 This is the default behavior if the <B>FILE</B> instruction does not
2863 appear in the file.
2864 <P>When the value is <B>YES</B>, the Tape Coordinator uses a backup data
2865 file on the local disk as the backup medium. If the file does not exist
2866 when the Tape Coordinator attempts to write a dump, the Tape Coordinator
2867 creates it. For a restore operation to succeed, the file must exist and
2868 contain volume data previously written to it by a <B>backup dump</B>
2869 operation.
2870 <P>When the value is <B>YES</B>, the backup data file's complete
2871 pathname must appear (instead of a tape drive device name) in the third field
2872 of the corresponding port offset entry in the local
2873 <B>/usr/afs/backup/tapeconfig</B> file. If the field instead refers
2874 to a tape device, dump operations appear to succeed but are
2875 inoperative. It is not possible to restore data that is accidently
2876 dumped to a tape device while the <B>FILE</B> instruction is set to
2877 <B>YES</B>. (In the same way, if the <B>FILE</B> instruction is
2878 set to <B>NO</B> and there is no <B>SERVER</B> instruction, the
2879 <B>tapeconfig</B> entry must refer to an actual tape device.)
2880 <P>Rather than put an actual file pathname in the third field of the
2881 <B>tapeconfig</B> file, however, the recommended configuration is to
2882 create a symbolic link in the <B>/dev</B> directory that points to the
2883 actual file pathname, and record the symbolic link's name in this
2884 field. This configuration has a couple of advantages:
2885 <UL>
2886 <P><LI>It makes the <VAR>tcid</VAR> portion of the <B>CFG_</B><VAR>tcid</VAR>,
2887 <B>TE_</B><VAR>tcid</VAR>, and <B>TL_</B><VAR>tcid</VAR> names as short as
2888 possible. Because the symbolic link is in the <B>/dev</B> directory
2889 as though it were a tape device, the device configuration file's name is
2890 constructed by stripping off the entire <B>/dev/</B> prefix, instead of
2891 just the initial slash. If, for example, the symbolic link is called
2892 <B>/dev/FILE</B>, the device configuration file name is
2893 <B>CFG_FILE</B>, whereas if the actual pathname <B>/var/tmp/FILE</B>
2894 appears in the <B>tapeconfig</B> file, the file's name must be
2895 <B>CFG_var_tmp_FILE</B>.
2896 <P><LI>It provides for a more graceful, and potentially automated, recovery if
2897 the Tape Coordinator cannot write a complete dump into the backup data file
2898 (because the partition housing the backup data file becomes full, for
2899 example). The Tape Coordinator's reaction to this problem is to
2900 invoke the <B>MOUNT</B> script, or to prompt the operator if the
2901 <B>MOUNT</B> instruction does not appear in the configuration file.
2902 <UL>
2903 <P><LI>If there is a <B>MOUNT</B> routine, the operator can prepare for this
2904 situation by adding a subroutine that changes the symbolic link to point to
2905 another backup data file on a partition where there is space available.
2906 <P><LI>If there is no <B>MOUNT</B> instruction, the prompt enables the
2907 operator manually to change the symbolic link to point to another backup data
2908 file, then press &lt;<B>Return</B>> to signal that the Tape Coordinator
2909 can continue the operation.
2910 </UL>
2911 </UL>
2912 <P>If the third field in the <B>tapeconfig</B> file names the actual file,
2913 there is no way to recover from exhausting the space on the partition that
2914 houses the backup data file. It is not possible to change the
2915 <B>tapeconfig</B> file in the middle of an operation.
2916 <P>When writing to a backup data file, the Tape Coordinator writes data at 16
2917 KB offsets. If a given block of data (such as the marker that signals
2918 the beginning or end of a volume) does not fill the entire 16 KB, the Tape
2919 Coordinator still skips to the next offset before writing the next
2920 block. In the output of a <B>backup dumpinfo</B> command issued
2921 with the <B>-id</B> option, the value in the <TT>Pos</TT> column is the
2922 ordinal of the 16-KB offset at which the volume data begins, and so is not
2923 generally only one higher than the position number on the previous line, as it
2924 is for dumps to tape.
2925 <P><B>The GROUPID Instruction</B>
2926 <P>The <B>GROUPID</B> instruction takes an integer as its argument, in the
2927 following format:
2928 <PRE>   GROUPID <VAR>integer</VAR>
2929 </PRE>
2930 <P>where <VAR>integer</VAR> is in the range from <B>1</B> through
2931 <B>2147483647</B> (one less than 2 GB). The value is recorded in
2932 the Backup Database record for each dump created by this Tape
2933 Coordinator. It appears in the <TT>Group id</TT> field in the output
2934 from the <B>backup dumpinfo</B> command when the command's
2935 <B>-verbose</B> and <B>-id</B> options are provided. It can be
2936 specified as the value of the <B>-groupid</B> argument to the <B>backup
2937 deletedump</B> command to delete only records marked with the group
2938 ID. This instruction is always optional.
2939 <P><B>The LASTLOG Instruction</B>
2940 <P>The <B>LASTLOG</B> instruction takes a boolean value as its argument,
2941 in the following format:
2942 <PRE>   LASTLOG  {<B>YES</B> | <B>NO</B>}
2943 </PRE>
2944 <P>When the value is <B>YES</B>, the Tape Coordinator creates and writes
2945 to a separate log file during the final pass through the volumes to be
2946 included in a dump operation. The log file name is
2947 <B>/usr/afs/backup/TL_</B><VAR>tcid</VAR><B>.lp</B>, where
2948 <VAR>tcid</VAR> is either the Tape Coordinator's port offset number or a
2949 value derived from the device name or backup data filename.
2950 <P>When the value is <B>NO</B>, the Tape Coordinator writes to its
2951 standard log files (the <B>TE_</B><VAR>tcid</VAR> and
2952 <B>TL_</B><VAR>tcid</VAR> files in the <B>/usr/afs/backup</B> directory)
2953 for all passes. This is the behavior if the instruction does not appear
2954 in the file.
2955 <P><B>The MAXPASS Instruction</B>
2956 <P>The <B>MAXPASS</B> instruction takes an integer as its argument, in the
2957 following format:
2958 <PRE>   MAXPASS <VAR>integer</VAR>
2959 </PRE>
2960 <P>where <VAR>integer</VAR> specifies how many times the Tape Coordinator
2961 attempts to access a volume during a dump operation if the volume is
2962 inaccessible on the first attempt (which is included in the count).
2963 Acceptable values are in the range from <B>1</B> through
2964 <B>10</B>. The default value is <B>2</B> if this instruction
2965 does not appear in the file.
2966 <P><B>The MGMTCLASS Instruction</B>
2967 <P>The <B>MGMTCLASS</B> instruction takes a character string as its
2968 argument, in the following format:
2969 <PRE>   MGMTCLASS <VAR>class_name</VAR>
2970 </PRE>
2971 <P>where <VAR>class_name</VAR> is the XBSA server's management class, which
2972 often indicates the type of backup medium it is using. For a list of
2973 the possible management classes, see the XBSA server documentation.
2974 This instruction applies only to XBSA servers and is always optional;
2975 there is no default value if it is omitted.
2976 <P><B>The MOUNT Instruction</B>
2977 <P>The <B>MOUNT</B> instruction takes a pathname as its argument, in the
2978 following format:
2979 <PRE>   MOUNT <VAR>filename</VAR>
2980 </PRE>
2981 <P>where <VAR>filename</VAR> is the full pathname of an executable file on the
2982 local disk that contains a shell script or program (for clarity, the following
2983 discussion refers to scripts only). If the configuration file is for an
2984 automated tape device, the script invokes the routine or command provided by
2985 the device's manufacturer for mounting a tape (inserting it into the tape
2986 reader). If the configuration file is for a backup data file, it can
2987 instruct the Tape Coordinator to switch automatically to another backup data
2988 file when the current one becomes full; for further discussion, see the
2989 preceding description of the <B>FILE</B> instruction. This
2990 instruction does not apply to XBSA servers.
2991 <P>The administrator must write the script, including the appropriate routines
2992 and logic. The AFS distribution does not include any scripts, although
2993 an example appears in the following <B>Examples</B> section. The
2994 command or routines invoked by the script inherit the local identity (UNIX
2995 UID) and AFS tokens of the <B>butc</B> command's issuer.
2996 <P>When the Tape Coordinator needs to mount a tape or access another backup
2997 data file, it checks the configuration file for a <B>MOUNT</B>
2998 instruction. If there is no instruction, the Tape Coordinator prompts
2999 the operator to insert a tape before it attempts to open the tape
3000 device. If there is a <B>MOUNT</B> instruction, the Tape
3001 Coordinator executes the routine in the referenced script.
3002 <P>There is an exception to this sequence: if the <B>AUTOQUERY
3003 NO</B> instruction appears in the configuration file, or the
3004 <B>-noautoquery</B> flag was included on the <B>butc</B> command, then
3005 the Tape Coordinator assumes that the operator has already inserted the first
3006 tape needed for a given operation. It attempts to read the tape
3007 immediately, and only checks for the <B>MOUNT</B> instruction or prompts
3008 the operator if the tape is missing or is not the required one.
3009 <P>The Tape Coordinator passes the following parameters to the script
3010 indicated by the <B>MOUNT</B> instruction, in the indicated order:
3011 <OL TYPE=1>
3012 <P><LI>The tape device or backup data file's pathname, as recorded in the
3013 <B>/usr/afs/backup/tapeconfig</B> file.
3014 <P><LI>The tape operation, which generally matches the <B>backup</B> command
3015 operation code used to initiate the operation (the following list notes the
3016 exceptional cases) :
3017 <UL>
3018 <P><LI><B>appenddump</B> (when a <B>backup dump</B> command includes the
3019 <B>-append</B> flag)
3020 <P><LI><B>dump</B> (when a <B>backup dump</B> command does not include
3021 the <B>-append</B> flag)
3022 <P><LI><B>labeltape</B>
3023 <P><LI><B>readlabel</B>
3024 <P><LI><B>restore</B> (for a <B>backup diskrestore</B>, <B>backup
3025 volrestore</B>, or <B>backup volsetrestore</B> command)
3026 <P><LI><B>restoredb</B>
3027 <P><LI><B>savedb</B>
3028 <P><LI><B>scantape</B>
3029 </UL>
3030 <P><LI>The number of times the Tape Coordinator has attempted to open the tape
3031 device or backup data file. If the open attempt returns an error, the
3032 Tape Coordinator increments this value by one and again invokes the
3033 <B>MOUNT</B> instruction.
3034 <P><LI>The tape name. For some operations, the Tape Coordinator passes the
3035 string <TT>none</TT>, because it does not know the tape name (when running
3036 the <B>backup scantape</B> or <B>backup readlabel</B>, for example),
3037 or because the tape does not necessarily have a name (when running the
3038 <B>backup labeltape</B> command, for example).
3039 <P><LI>The tape ID recorded in the Backup Database. As with the tape name,
3040 the Backup System passes the string <TT>none</TT> for operations where it
3041 does not know the tape ID or the tape does not necessarily have an ID.
3042 </OL>
3043 <P>The routine invoked by the <B>MOUNT</B> instruction must return an exit
3044 code to the Tape Coordinator:
3045 <UL>
3046 <P><LI>Code <B>0</B> (zero) indicates that the routine successfully mounted
3047 the tape or opened the backup data file. The Tape Coordinator continues
3048 the backup operation. If the routine invoked by the <B>MOUNT</B>
3049 instruction does not return this exit code, the Tape Coordinator never calls
3050 the <B>UNMOUNT</B> instruction.
3051 <P><LI>Code <B>1</B> (one) indicates that the routine failed to mount the
3052 tape or open the backup data file. The Tape Coordinator terminates the
3053 operation.
3054 <P><LI>Any other code indicates that the routine was not able to access the
3055 correct tape or backup data file. The Tape Coordinator prompts the
3056 operator to insert the correct tape.
3057 </UL>
3058 <P>If the <B>backup</B> command was issued in interactive mode and the
3059 operator issues the <B>(backup) kill</B> command while the
3060 <B>MOUNT</B> routine is running, the Tape Coordinator passes the
3061 termination signal to the routine; the entire operation
3062 terminates.
3063 <P><B>The NAME_CHECK Instruction</B>
3064 <P>The <B>NAME_CHECK</B> instruction takes a boolean value as its
3065 argument, in the following format:
3066 <PRE>   NAME_CHECK {<B>YES</B> | <B>NO</B>}
3067 </PRE>
3068 <P>When the value is <B>YES</B> and there is no permanent name on the
3069 label of the tape or backup data file, the Tape Coordinator checks the AFS
3070 tape name on the label when dumping a volume in response to the <B>backup
3071 dump</B> command. The AFS tape name must be <TT>&lt;NULL></TT> or
3072 match the name that the <B>backup dump</B> operation constructs based on
3073 the volume set and dump level names. This is the default behavior if
3074 the <B>NAME_CHECK</B> instruction does not appear in the configuration
3075 file.
3076 <P>When the value is <B>NO</B>, the Tape Coordinator does not check the
3077 AFS tape name before writing to the tape.
3078 <P>The Tape Coordinator always checks that all dumps on the tape are expired,
3079 and refuses to write to a tape that contains unexpired dumps. This
3080 instruction does not apply to XBSA servers.
3081 <P><B>The NODE Instruction</B>
3082 <P>The <B>NODE</B> instruction takes a character string as its argument,
3083 in the following format:
3084 <PRE>   NODE <VAR>node_name</VAR>
3085 </PRE>
3086 <P>where <VAR>node_name</VAR> names the node associated with the XBSA server
3087 named by the <B>SERVER</B> instruction. To determine if the XBSA
3088 server uses nodes, see its documentation. This instruction applies only
3089 to XBSA servers, and there is no default if it is omitted. However, TSM
3090 requires that a NODENAME instruction appear in its <B>dsm.sys</B>
3091 configuration file in that case.
3092 <P><B>The PASSFILE Instruction</B>
3093 <P>The <B>PASSFILE</B> instruction takes a pathname as its argument, in
3094 the following format:
3095 <PRE>   PASSFILE <VAR>filename</VAR>
3096 </PRE>
3097 <P>where <VAR>filename</VAR> is the full pathname of a file on the local disk
3098 that records the password for the Tape Coordinator to use when communicating
3099 with the XBSA server. The password string must appear on the first line
3100 in the file, and have a newline character only at the end. The mode
3101 bits on the file must enable the Tape Coordinator to read it.
3102 <P>This instruction applies only to XBSA servers, and either it or the
3103 <B>PASSWORD</B> instruction must be provided along with the
3104 <B>SERVER</B> instruction. (If both this instruction and the
3105 <B>PASSWORD</B> instruction are included, the Tape Coordinator uses only
3106 the one that appears first in the file.)
3107 <P><B>The PASSWORD Instruction</B>
3108 <P>The <B>PASSWORD</B> instruction takes a character string as its
3109 argument, in the following format:
3110 <PRE>   PASSWORD <VAR>string</VAR>
3111 </PRE>
3112 <P>where <VAR>string</VAR> is the password for the Tape Coordinator to use when
3113 communicating with the XBSA server. It must appear on the first line in
3114 the file, and have a newline character only at the end.
3115 <P>This instruction applies only to XBSA servers, and either it or the
3116 <B>PASSFILE</B> instruction must be provided along with the
3117 <B>SERVER</B> instruction. (If both this instruction and the
3118 <B>PASSFILE</B> instruction are included, the Tape Coordinator uses only
3119 the one that appears first in the file.)
3120 <P><B>The SERVER Instruction</B>
3121 <P>The <B>SERVER</B> instruction takes a character string as its argument,
3122 in the following format:
3123 <PRE>   SERVER <VAR>machine_name</VAR>
3124 </PRE>
3125 <P>where <VAR>machine_name</VAR> is the fully qualified hostname of the machine
3126 where an XBSA server is running. This instruction is required for XBSA
3127 servers, and applies only to them.
3128 <P><B>The STATUS Instruction</B>
3129 <P>The <B>STATUS</B> instruction takes an integer as its argument, in the
3130 following format:
3131 <PRE>   STATUS <VAR>integer</VAR>
3132 </PRE>
3133 <P>where <VAR>integer</VAR> expresses how often the Tape Coordinator writes a
3134 status message to its window during an operation, in terms of the number of
3135 buffers of data that have been dumped or restored. Acceptable values
3136 range from <B>1</B> through <B>8192</B>. The size of the
3137 buffers is determined by the <B>BUFFERSIZE</B> instruction if it is
3138 included.
3139 <P>As an example, the value <B>512</B> means that the Tape Coordinator
3140 writes a status message after each 512 buffers of data. It also writes
3141 a status message as it completes the dump of each volume.
3142 <P>The message has the following format:
3143 <PRE>   <VAR>time_stamp</VAR>: Task <VAR>task_ID</VAR>: <VAR>total</VAR> KB: <VAR>volume</VAR>: <VAR>volume_total</VAR> B
3144 </PRE>
3145 <P>where
3146 <DL>
3147 <P><DT><B><VAR>time_stamp</VAR>
3148 </B><DD>Records the time at which the message is printed, in the format
3149 <VAR>hours</VAR>:<VAR>minutes</VAR>:<VAR>seconds</VAR>.
3150 <P><DT><B><VAR>task_ID</VAR>
3151 </B><DD>Is the task identification number assigned to the operation by the Tape
3152 Coordinator. The first digits in the number are the Tape
3153 Coordinator's port offset number.
3154 <P><DT><B><VAR>total</VAR>
3155 </B><DD>Is the total number of kilobytes transferred to the backup medium during
3156 the current dump operation.
3157 <P><DT><B><VAR>volume</VAR>
3158 </B><DD>Names the volume being dumped as the message is written.
3159 <P><DT><B><VAR>volume_total</VAR>
3160 </B><DD>Is the total number of bytes dumped so far from the volume named in the
3161 <VAR>volume</VAR> field.
3162 </DL>
3163 <P>This instruction is intended for use with XBSA servers. For tape
3164 devices and backup data files, the value in the <VAR>volume_total</VAR> field is
3165 not necessarily as expected. It does not include certain kinds of
3166 Backup System metadata (markers at the beginning and end of each volume, for
3167 example), so summing together the final <VAR>volume_total</VAR> value for each
3168 volume does not necessarily equal the running total in the <VAR>total</VAR>
3169 field. Also, the Tape Coordinator does not write a message at all if it
3170 is dumping metadata rather than actual volume data as it reaches the end of
3171 the last buffer in each set of <VAR>integer</VAR> buffers.
3172 <P><B>The TYPE Instruction</B>
3173 <P>The <B>TYPE</B> instruction takes a character string as its argument,
3174 in the following format:
3175 <PRE>   TYPE <VAR>program_name</VAR>
3176 </PRE>
3177 <P>where <VAR>program_name</VAR> names the XBSA server program that is running
3178 on the machine named by the <B>SERVER</B> instruction. This
3179 instruction is mandatory when the <B>SERVER</B> instruction appears in the
3180 file. The acceptable values depend on which XBSA servers are supported
3181 in the current AFS release. In the General Availability release of AFS
3182 3.6, the only acceptable value is <B>tsm</B>.
3183 <P><B>The UNMOUNT Instruction</B>
3184 <P>The <B>UNMOUNT</B> instruction takes a pathname as its argument, in the
3185 following format:
3186 <PRE>   UNMOUNT <VAR>filename</VAR>
3187 </PRE>
3188 <P>where <VAR>filename</VAR> is the full pathname of an executable file on the
3189 local disk that contains a shell script or program (for clarity, the following
3190 discussion refers to scripts only). If the configuration file is for an
3191 automated tape device, the script invokes the routine or command provided by
3192 the device's manufacturer for unmounting a tape (removing it from the
3193 tape reader). If the configuration file is for a backup data file, it
3194 can instruct the Tape Coordinator to perform additional actions after closing
3195 the backup data file. This instruction does not apply to XBSA
3196 servers.
3197 <P>The administrator must write the script, including the appropriate routines
3198 and logic. The AFS distribution does not include any scripts, although
3199 an example appears in the following <B>Examples</B> section. The
3200 command or routines invoked by the script inherit the local identity (UNIX
3201 UID) and AFS tokens of the <B>butc</B> command's issuer.
3202 <P>After closing a tape device or backup data file, the Tape Coordinator
3203 checks the configuration file for an <B>UNMOUNT</B> instruction, whether
3204 or not the <B>close</B> operation succeeds. If there is no
3205 <B>UNMOUNT</B> instruction, the Tape Coordinator takes no action, in which
3206 case the operator must take the action necessary to remove the current tape
3207 from the drive before another can be inserted. If there is an
3208 <B>UNMOUNT</B> instruction, the Tape Coordinator executes the referenced
3209 file. It invokes the routine only once, passing in the following
3210 parameters:
3211 <UL>
3212 <P><LI>The tape device pathname (as specified in the
3213 <B>/usr/afs/backup/tapeconfig</B> file)
3214 <P><LI>The tape operation (always <B>unmount</B>)
3215 </UL>
3216 <P><STRONG>Privilege Required</STRONG>
3217 <P>The file is protected by UNIX mode bits. Creating the file requires
3218 the <B>w</B> (<B>write</B>) and <B>x</B> (<B>execute</B>)
3219 permissions on the <B>/usr/afs/backup</B> directory. Editing the
3220 file requires the <B>w</B> (<B>write</B>) permission on the
3221 file.
3222 <P><STRONG>Examples</STRONG>
3223 <P>The following example configuration files demonstrate one way to structure
3224 a configuration file for a stacker or backup dump file. The examples
3225 are not necessarily appropriate for a specific cell; if using them as
3226 models, be sure to adapt them to the cell's needs and equipment.
3227 <P><B>Example</B> <B>CFG_</B><VAR>tcid</VAR> <B>File for
3228 Stackers</B>
3229 <P>In this example, the administrator creates the following entry for a tape
3230 stacker called <B>stacker0.1</B> in the
3231 <B>/usr/afs/backup/tapeconfig</B> file. It has port offset
3232 0.
3233 <PRE>   2G   5K   /dev/stacker0.1   0
3234 </PRE>
3235 <P>The administrator includes the following five lines in the
3236 <B>/usr/afs/backup/CFG_stacker0.1</B> file. To review the
3237 meaning of each instruction, see the preceding <B>Description</B>
3238 section.
3239 <PRE>   MOUNT /usr/afs/backup/stacker0.1
3240    UNMOUNT /usr/afs/backup/stacker0.1
3241    AUTOQUERY NO
3242    ASK NO
3243    NAME_CHECK NO
3244 </PRE>
3245 <P>Finally, the administrator writes the following executable routine in the
3246 <B>/usr/afs/backup/stacker0.1</B> file referenced by the
3247 <B>MOUNT</B> and <B>UNMOUNT</B> instructions in the
3248 <B>CFG_stacker0.1</B> file.
3249 <PRE>   #! /bin/csh -f
3250
3251    set devicefile = $1
3252    set operation = $2
3253    set tries = $3
3254    set tapename = $4
3255    set tapeid = $5
3256
3257    set exit_continue = 0
3258    set exit_abort = 1
3259    set exit_interactive = 2
3260
3261    #--------------------------------------------
3262
3263    if (${tries} > 1) then
3264       echo "Too many tries"
3265       exit ${exit_interactive}
3266    endif
3267
3268    if (${operation} == "unmount") then
3269       echo "UnMount: Will leave tape in drive"
3270       exit ${exit_continue}
3271    endif
3272
3273    if ((${operation} == "dump")     |\
3274        (${operation} == "appenddump")     |\
3275        (${operation} == "savedb"))  then
3276
3277        stackerCmd_NextTape ${devicefile}
3278        if (${status} != 0)exit${exit_interactive}
3279        echo "Will continue"
3280        exit ${exit_continue}
3281    endif
3282
3283    if ((${operation} == "labeltape")    |\
3284        (${operation} == "readlabel")) then
3285       echo "Will continue"
3286       exit ${exit_continue}
3287    endif
3288
3289    echo "Prompt for tape"
3290    exit ${exit_interactive}
3291 </PRE>
3292 <P>This routine uses two of the parameters passed to it by the Backup
3293 System: <TT>tries</TT> and <TT>operation</TT>. It follows the
3294 recommended practice of prompting for a tape if the value of the
3295 <TT>tries</TT> parameter exceeds one, because that implies that the stacker
3296 is out of tapes.
3297 <P>For a <B>backup dump</B> or <B>backup savedb</B> operation, the
3298 routine calls the example <B>stackerCmd_NextTape</B> function provided by
3299 the stacker's manufacturer. Note that the final lines in the file
3300 return the exit code that prompts the operator to insert a tape; these
3301 lines are invoked when either the stacker cannot load a tape or the operation
3302 being performed is not one of those explicitly mentioned in the file (such as
3303 a restore operation).
3304 <P><B>Example CFG_</B><VAR>tcid</VAR> <B>File for Dumping to a Backup Data
3305 File</B>
3306 <P>In this example, the administrator creates the following entry for a backup
3307 data file called <B>HSM_device</B> in the
3308 <B>/usr/afs/backup/tapeconfig</B> file. It has port offset
3309 20.
3310 <PRE>   1G   0K   /dev/HSM_device   20
3311 </PRE>
3312 <P>The administrator chooses to name the configuration file
3313 <B>/usr/afs/backup/CFG_20</B>, using the port offset number rather than
3314 deriving the <VAR>tcid</VAR> portion of the name from the backup data
3315 file's name. She includes the following lines in the file.
3316 To review the meaning of each instruction, see the preceding
3317 <B>Description</B> section.
3318 <PRE>   MOUNT /usr/afs/backup/file
3319    FILE YES
3320    ASK NO
3321 </PRE>
3322 <P>Finally, the administrator writes the following executable routine in the
3323 <B>/usr/afs/backup/file</B> file referenced by the <B>MOUNT</B>
3324 instruction in the <B>CFG_HSM_device</B> file, to control how the Tape
3325 Coordinator handles the file.
3326 <PRE>   #! /bin/csh -f
3327    set devicefile = $1
3328    set operation = $2
3329    set tries = $3
3330    set tapename = $4
3331    set tapeid = $5
3332
3333    set exit_continue = 0
3334    set exit_abort = 1
3335    set exit_interactive = 2
3336
3337    #--------------------------------------------
3338
3339    if (${tries} > 1) then
3340       echo "Too many tries"
3341       exit ${exit_interactive}
3342    endif
3343
3344    if (${operation} == "labeltape") then
3345       echo "Won't label a tape/file"
3346       exit ${exit_abort}
3347    endif
3348
3349    if ((${operation} == "dump")   |\
3350        (${operation} == "appenddump")   |\
3351        (${operation} == "restore")   |\
3352        (${operation} == "savedb")    |\
3353        (${operation} == "restoredb")) then
3354
3355       /bin/rm -f ${devicefile}
3356       /bin/ln -s /hsm/${tapename}_${tapeid} ${devicefile}
3357       if (${status} != 0) exit ${exit_abort}
3358    endif
3359
3360    exit ${exit_continue}
3361 </PRE>
3362 <P>Like the example routine for a tape stacker, this routine uses the
3363 <TT>tries</TT> and <TT>operation</TT> parameters passed to it by the
3364 Backup System. The <TT>tries</TT> parameter tracks how many times the
3365 Tape Coordinator has attempted to access the file. A value greater than
3366 one indicates that the Tape Coordinator cannot access it, and the routine
3367 returns exit code 2 (<TT>exit_interactive</TT>), which results in a prompt
3368 for the operator to load a tape. The operator can use this opportunity
3369 to change the name of the backup data file specified in the
3370 <B>tapeconfig</B> file.
3371 <P>The primary function of this routine is to establish a link between the
3372 device file and the file to be dumped or restored. When the Tape
3373 Coordinator is executing a <B>backup dump</B>, <B>backup restore</B>,
3374 <B>backup savedb</B>, or <B>backup restoredb</B> operation, the
3375 routine invokes the UNIX <B>ln -s</B> command to create a symbolic link
3376 from the backup data file named in the <B>tapeconfig</B> file to the
3377 actual file to use (this is the recommended method). It uses the value
3378 of the <TT>tapename</TT> and <TT>tapeid</TT> parameters to construct the
3379 file name.
3380 <P><B>Example</B> <B>CFG_</B><VAR>tcid</VAR> <B>File for an XBSA
3381 Server</B>
3382 <P>The following is an example of a configuration file called
3383 <B>/usr/afs/backup/CFG_22</B>, for a Tape Coordinator with port offset 22
3384 that communicates with an Tivoli Storage Management (TSM) server. The
3385 combination of <B>BUFFERSIZE</B> and <B>STATUS</B> instructions
3386 results in a status message after each 16 MB of data are dumped. To
3387 review the meaning of the other instructions, see the preceding
3388 <B>Description</B> section.
3389 <PRE>   SERVER tsmserver1.abc.com
3390    TYPE tsm
3391    PASSWORD  TESTPASS
3392    NODE testnode
3393    MGMTCLASS standard
3394    MAXPASS 1
3395    GROUPID 1000
3396    CENTRALLOG /usr/afs/backup/centrallog
3397    BUFFERSIZE 16K
3398    STATUS 1024
3399 </PRE>
3400 <P><STRONG>Related Information</STRONG>
3401 <P><B>tapeconfig</B>
3402 <P><B>backup deletedump</B>
3403 <P><B>backup diskrestore</B>
3404 <P><B>backup dump</B>
3405 <P><B>backup dumpinfo</B>
3406 <P><B>backup restoredb</B>
3407 <P><B>backup savedb</B>
3408 <P><B>backup volrestore</B>
3409 <P><B>backup volsetrestore</B>
3410 <P>
3411 <H3><A NAME="HDRCLI_NETRESTRICT" HREF="aurns002.htm#ToC_48">NetRestrict (client version)</A></H3>
3412 <P><STRONG>Purpose</STRONG>
3413 <P>Defines client interfaces not to register with the File Server
3414 <P><STRONG>Description</STRONG>
3415 <P>The <B>NetRestrict</B> file, if present in a client machine's
3416 <B>/usr/vice/etc</B> directory, defines the IP addresses of the interfaces
3417 that the local Cache Manager does not register with a File Server when first
3418 establishing a connection to it. For an explanation of how the File
3419 Server uses the registered interfaces, see the reference page for the client
3420 version of the <B>NetInfo</B> file.
3421 <P>As it initializes, the Cache Manager constructs a list of interfaces to
3422 register, from the <B>/usr/vice/etc/NetInfo</B> file if it exists, or from
3423 the list of interfaces configured with the operating system otherwise.
3424 The Cache Manager then removes from the list any addresses that appear in the
3425 <B>NetRestrict</B> file, if it exists. The Cache Manager records
3426 the resulting list in kernel memory.
3427 <P>The <B>NetRestrict</B> file is in ASCII format. One IP address
3428 appears on each line, in dotted decimal format. The order of the
3429 addresses is not significant.
3430 <P>To display the addresses the Cache Manager is currently registering with
3431 File Servers, use the <B>fs getclientaddrs</B> command.
3432 <P><STRONG>Related Information</STRONG>
3433 <P><B>NetInfo</B> (client version)
3434 <P><B>fs getclientaddrs</B>
3435 <P>
3436 <H3><A NAME="HDRSV_NETRESTRICT" HREF="aurns002.htm#ToC_49">NetRestrict (server version)</A></H3>
3437 <P><STRONG>Purpose</STRONG>
3438 <P>Defines interfaces that File Server does not register in VLDB and Ubik does
3439 not use for database server machines
3440 <P><STRONG>Description</STRONG>
3441 <P>The <B>NetRestrict</B> file, if present in the
3442 <B>/usr/afs/local</B> directory, defines the following:
3443 <UL>
3444 <P><LI>On a file server machine, the local interfaces that the File Server
3445 (<B>fileserver</B> process) does not register in the Volume Location
3446 Database (VLDB) at initialization time
3447 <P><LI>On a database server machine, the local interfaces that the Ubik
3448 synchronization library does not use when communicating with the database
3449 server processes running on other database server machines
3450 </UL>
3451 <P>As it initializes, the File Server constructs a list of interfaces to
3452 register, from the <B>/usr/afs/local/NetInfo</B> file if it exists, or
3453 from the list of interfaces configured with the operating system
3454 otherwise. The File Server then removes from the list any addresses
3455 that appear in the <B>NetRestrict</B> file, if it exists. The File
3456 Server records the resulting list in the <B>/usr/afs/local/sysid</B> file
3457 and registers the interfaces in the VLDB. The database server processes
3458 use a similar procedure when initializing, to determine which interfaces to
3459 use for communication with the peer processes on other database machines in
3460 the cell.
3461 <P>The <B>NetRestrict</B> file is in ASCII format. One IP address
3462 appears on each line, in dotted decimal format. The order of the
3463 addresses is not significant.
3464 <P>To display the File Server interface addresses registered in the VLDB, use
3465 the <B>vos listaddrs</B> command.
3466 <P><STRONG>Related Information</STRONG>
3467 <P><B>NetInfo</B> (server version)
3468 <P><B>sysid</B>
3469 <P><B>vldb.DB0</B> and <B>vldb.DBSYS1</B>
3470 <P><B>fileserver</B>
3471 <P><B>vos listaddrs</B>
3472 <P>
3473 <H3><A NAME="HDRBK_DELETEDUMP" HREF="aurns002.htm#ToC_50">backup deletedump</A></H3>
3474 <P><STRONG>Purpose</STRONG>
3475 <P>Deletes one or more dump records from the Backup Database
3476 <P><STRONG>Synopsis</STRONG>
3477 <PRE><B>backup deletedump</B> [<B>-dumpid</B> &lt;<VAR>dump&nbsp;id</VAR>><SUP>+</SUP>]  [<B>-from</B> &lt;<VAR>date&nbsp;time</VAR>><SUP>+</SUP>]  [<B>-to</B> &lt;<VAR>date&nbsp;time</VAR>><SUP>+</SUP>]
3478                   [<B>-port</B> &lt;<VAR>TC&nbsp;port&nbsp;offset</VAR>>]  [<B>-groupid</B> &lt;<VAR>group&nbsp;ID</VAR>>]
3479                   [<B>-dbonly</B>]  [<B>-force</B>]  [<B>-noexecute</B>]
3480                   [<B>-localauth</B>]  [<B>-cell</B> &lt;<VAR>cell&nbsp;name</VAR>>]  [<B>-help</B>]
3481
3482 <B>backup dele</B> [<B>-du</B> &lt;<VAR>dump&nbsp;id</VAR>><SUP>+</SUP>]  [<B>-fr</B> &lt;<VAR>date&nbsp;time</VAR>><SUP>+</SUP>]  [<B>-t</B> &lt;<VAR>date&nbsp;time</VAR>><SUP>+</SUP>]
3483             [<B>-p</B> &lt;<VAR>TC&nbsp;port&nbsp;offset</VAR>>]  [<B>-g</B> &lt;<VAR>group&nbsp;ID</VAR>>]  [<B>-db</B>]  [<B>-fo</B>]  [<B>-n</B>]
3484             [<B>-l</B>]  [<B>-c</B> &lt;<VAR>cell&nbsp;name</VAR>>]  [<B>-h</B>]
3485 </PRE>
3486 <P><STRONG>Description</STRONG>
3487 <P>The <B>backup deletedump</B> command deletes one or more dump records
3488 from the Backup Database. Using this command is appropriate when dump
3489 records are incorrect (possibly because a dump operation was interrupted or
3490 failed), or when they represent dumps that are expired or otherwise no longer
3491 needed.
3492 <P>To specify the records to delete, use one of the following arguments or
3493 combinations of arguments:
3494 <UL>
3495 <P><LI>The <B>-dumpid</B> argument deletes the record for each specified dump
3496 ID number.
3497 <P><LI>The <B>-groupid</B> argument deletes each record with the specified
3498 group ID number. A group ID number is associated with a record if the
3499 <B>GROUPID</B> instruction appears in the Tape Coordinator's <B>
3500 /usr/afs/backup/CFG_</B><VAR>tcid</VAR> file when the dump is created.
3501 To display a dump set's group ID, include the <B>-verbose</B> and
3502 <B>-id</B> options to the <B>backup dumpinfo</B> command; the
3503 group ID appears in the output's <TT>Group id</TT> field.
3504 <P><LI>The <B>-from</B> and <B>-to</B> arguments delete the records for
3505 all regular dumps created during the time period bracketed by the specified
3506 values. The <B>-from</B> argument can be omitted, in which case the
3507 command deletes records created before the time specified by the
3508 <B>-to</B> argument.
3509 <P><LI>The combination of the <B>-groupid</B>, <B>-to</B> and optionally
3510 <B>-from</B> arguments deletes the records for all regular dumps created
3511 during the specified time period that are also marked with the specified group
3512 ID number.
3513 </UL>
3514 <P>The command can also delete dump records maintained by an XBSA server at
3515 the same time as the corresponding Backup Database records. (An
3516 <I>XBSA server</I> is a third-party backup utility that implements the
3517 Open Group's Backup Service API [XBSA].) Include the
3518 <B>-port</B> argument to identify the Tape Coordinator that communicates
3519 with the XBSA server. To delete the Backup Database records without
3520 attempting to delete the records at the XBSA server, include the
3521 <B>-dbonly</B> flag. To delete the Backup Database records even if
3522 an attempt to delete the records at the XBSA server fails, include the
3523 <B>-force</B> flag.
3524 <P><STRONG>Cautions</STRONG>
3525 <P>The only way to remove the dump record for an appended dump is to remove
3526 the record for its initial dump, and doing so removes the records for all
3527 dumps appended to the initial dump.
3528 <P>The only way to remove the record for a Backup Database dump (created with
3529 the <B>backup savedb</B> command) is to specify its dump ID number with
3530 the <B>-dumpid</B> argument. Using the <B>-from</B> and
3531 <B>-to</B> arguments never removes database dump records.
3532 <P>Removing a dump's record makes it impossible to restore data from it
3533 or from any dump that refers to the deleted dump as its parent, directly or
3534 indirectly. That is, restore operations must begin with a full dump and
3535 continue with each incremental dump in order. If the records for a
3536 specific dump are removed, it is not possible to restore data from later
3537 incremental dumps. If necessary, use the <B>-dbadd</B> flag to the
3538 <B>backup scantape</B> command to regenerate a dump record so that the
3539 dump can act as a parent again.
3540 <P>If a dump set contains any dumps that were created outside the time range
3541 specified by the <B>-from</B> and <B>-to</B> arguments, the command
3542 does not delete any of the records associated with the dump set, even if some
3543 of them represent dumps created during the time range.
3544 <P><STRONG>Options</STRONG>
3545 <DL>
3546 <P><DT><B>-dumpid
3547 </B><DD>Specifies the dump ID of each dump record to delete. The
3548 corresponding dumps must be initial dumps; it is not possible to delete
3549 appended dump records directly, but only by deleting the record of their
3550 associated initial dump. Using this argument is the only way to delete
3551 records of Backup Database dumps (created with the <B>backup savedb</B>
3552 command).
3553 <P>Provide either this argument, the <B>-to</B> (and optionally
3554 <B>-from</B>) argument, or the <B>-groupid</B> argument.
3555 <P><DT><B>-from
3556 </B><DD>Specifies the beginning of a range of dates; the record for any dump
3557 created during the indicated period of time is deleted.
3558 <P>Omit this argument to indicate the default of midnight (00:00 hours)
3559 on 1 January 1970 (UNIX time zero), or provide a date value in the format
3560 <VAR>mm/dd/yyyy</VAR> [<VAR>hh:MM</VAR>]. The month (<VAR>mm</VAR>),
3561 day (<VAR>dd</VAR>), and year (<VAR>yyyy</VAR>) are required. The hour and
3562 minutes (<VAR>hh</VAR>:<VAR>MM</VAR>) are optional, but if provided must be
3563 in 24-hour format (for example, the value <B>14:36</B> represents
3564 2:36 p.m.). If omitted, the time defaults to
3565 midnight (00:00 hours).
3566 <P>The <B>-to</B> argument must be provided along with this one.
3567 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">A plus sign follows this argument in the command's syntax statement
3568 because it accepts a multiword value which does not need to be enclosed in
3569 double quotes or other delimiters, not because it accepts multiple
3570 dates. Provide only one date (and optionally, time) definition.
3571 </TD></TR></TABLE>
3572 <P><DT><B>-to
3573 </B><DD>Specifies the end of a range of dates; the record of any regular dump
3574 created during the range is deleted from the Backup Database.
3575 <P>Provide either the value <B>NOW</B> to indicate the current date and
3576 time, or a date value in the same format as for the <B>-from</B>
3577 argument. Valid values for the year (<VAR>yyyy</VAR>) range from
3578 <B>1970</B> to <B>2037</B>; higher values are not valid because
3579 the latest possible date in the standard UNIX representation is in February
3580 2038. The command interpreter automatically reduces any later date to
3581 the maximum value.
3582 <P>If the time portion (<VAR>hh:MM</VAR>) is omitted, it defaults to 59
3583 seconds after midnight (00:00:59 hours). Similarly, the
3584 <B>backup</B> command interpreter automatically adds 59 seconds to any
3585 time value provided. In both cases, adding 59 seconds compensates for
3586 how the Backup Database and <B>backup dumpinfo</B> command represent dump
3587 creation times in hours and minutes only. For example, the Database
3588 records a creation timestamp of <TT>20:55</TT> for any dump operation
3589 that begins between 20:55:00 and 20:55:59.
3590 Automatically adding 59 seconds to a time thus includes the records for all
3591 dumps created during that minute.
3592 <P>Provide either this argument, the <B>-dumpid</B> argument, or the
3593 <B>-groupid</B> argument, or combine this argument and the
3594 <B>-groupid</B> argument. This argument is required if the
3595 <B>-from</B> argument is provided.
3596 <P><B>Caution:</B> Specifying the value <B>NOW</B> for this
3597 argument when the <B>-from</B> argument is omitted deletes all dump
3598 records from the Backup Database (except for Backup Database dump records
3599 created with the <B>backup savedb</B> command).
3600 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">A plus sign follows this argument in the command's syntax statement
3601 because it accepts a multiword value which does not need to be enclosed in
3602 double quotes or other delimiters, not because it accepts multiple
3603 dates. Provide only one date (and optionally, time) definition.
3604 </TD></TR></TABLE>
3605 <P><DT><B>-port
3606 </B><DD>Specifies the port offset number of the Tape Coordinator that communicates
3607 with the XBSA server that maintains the records to delete. It must be
3608 the Tape Coordinator that transferred AFS data to the XBSA server when the
3609 dump was created. The corresponding records in the Backup Database are
3610 also deleted.
3611 <P>This argument is meaningful only when deleting records maintained by an
3612 XBSA server. Do not combine it with the <B>-dbonly</B> flag.
3613 If this argument is omitted when other options pertinent to an XBSA server are
3614 included, the Tape Coordinator with port offset 0 (zero) is used.
3615 <P><DT><B>-groupid
3616 </B><DD>Specifies the group ID number that is associated with the records to
3617 delete. The Tape Coordinator ignores group IDs if this argument is
3618 omitted.
3619 <P>Provide either this argument, the <B>-dumpid</B> argument, or the
3620 <B>-to</B> argument, or combine this argument and the <B>-to</B>
3621 argument with any options other than the <B>-dumpid</B> argument.
3622 <P><DT><B>-dbonly
3623 </B><DD>Deletes records from the Backup Database without attempting to delete the
3624 corresponding records maintained by an XBSA server. Do not combine this
3625 flag with the <B>-port</B> argument or the <B>-force</B> flag.
3626 <P><DT><B>-force
3627 </B><DD>Deletes the specified records from the Backup Database even when the
3628 attempt to delete the corresponding records maintained by an XBSA server
3629 fails. Do not combine this flag with the <B>-dbonly</B>
3630 flag. To identify the Tape Coordinator when this argument is used,
3631 either provide the <B>-port</B> argument or omit it to specify the Tape
3632 Coordinator with port offset 0 (zero).
3633 <P><DT><B>-noexecute
3634 </B><DD>Displays a list of the dump records to be deleted, without actually
3635 deleting them. Combine it with the options to be included on the actual
3636 command.
3637 <P><DT><B>-localauth
3638 </B><DD>Constructs a server ticket using a key from the local
3639 <B>/usr/afs/etc/KeyFile</B> file. The <B>backup</B> command
3640 interpreter presents it to the Backup Server, Volume Server and VL Server
3641 during mutual authentication. Do not combine this flag with the
3642 <B>-cell</B> argument. For more details, see the introductory
3643 <B>backup</B> reference page.
3644 <P><DT><B>-cell
3645 </B><DD>Names the cell in which to run the command. Do not combine this
3646 argument with the <B>-localauth</B> flag. For more details, see the
3647 introductory <B>backup</B> reference page.
3648 <P><DT><B>-help
3649 </B><DD>Prints the online help for this command. All other valid options
3650 are ignored.
3651 </DL>
3652 <P><STRONG>Output</STRONG>
3653 <P>If the <B>-noexecute</B> flag is not included, the output generated at
3654 the conclusion of processing lists the dump IDs of all deleted dump records,
3655 in the following format:
3656 <PRE>   The following dumps were deleted:
3657         <VAR>dump ID 1</VAR>
3658         <VAR>dump ID 2</VAR>
3659         <VAR>etc.</VAR>
3660 </PRE>
3661 <P>If the <B>-noexecute</B> flag is included, the output instead lists the
3662 dump IDs of all dump records to be deleted, in the following format:
3663 <PRE>   The following dumps would have been deleted:
3664         <VAR>dump ID 1</VAR>
3665         <VAR>dump ID 2</VAR>
3666         <VAR>etc.</VAR>
3667 </PRE>
3668 <P>The notation <TT>Appended Dump</TT> after a dump ID indicates that the
3669 dump is to be deleted because it is appended to an initial dump that also
3670 appears in the list, even if the appended dump's dump ID or group ID
3671 number was not specified on the command line. For more about deleting
3672 appended dumps, see the preceding <B>Cautions</B> section of this
3673 reference page.
3674 <P><STRONG>Examples</STRONG>
3675 <P>The following command deletes the dump record with dump ID 653777462, and
3676 for any appended dumps associated with it:
3677 <PRE>   % <B>backup deletedump -dumpid 653777462</B>
3678    The following dumps were deleted:
3679         653777462
3680 </PRE>
3681 <P>The following command deletes the Backup Database record of all dumps
3682 created between midnight on 1 January 1999 and 23:59:59 hours on
3683 31 December 1999:
3684 <PRE>   % <B>backup deletedump -from 01/01/1999 -to 12/31/1999</B>
3685    The following dumps were deleted:
3686         598324045
3687         598346873
3688            ...
3689            ...
3690         653777523
3691         653779648
3692 </PRE>
3693 <P><STRONG>Privilege Required</STRONG>
3694 <P>The issuer must be listed in the <B>/usr/afs/etc/UserList</B> file on
3695 every machine where the Backup Server is running, or must be logged onto a
3696 server machine as the local superuser <B>root</B> if the
3697 <B>-localauth</B> flag is included.
3698 <P><STRONG>Related Information</STRONG>
3699 <P><B>CFG_</B><VAR>tcid</VAR>
3700 <P><B>backup</B>
3701 <P><B>backup dumpinfo</B>
3702 <P><B>backup scantape</B>
3703 <P>
3704 <H3><A NAME="HDRBK_DUMPINFO" HREF="aurns002.htm#ToC_51">backup dumpinfo</A></H3>
3705 <P><STRONG>Purpose</STRONG>
3706 <P>Displays a dump record from the Backup Database
3707 <P><STRONG>Synopsis</STRONG>
3708 <PRE><B>backup dumpinfo</B> [<B>-ndumps</B> &lt;<VAR>no.&nbsp;of&nbsp;dumps</VAR>>]  [<B>-id</B> &lt;<VAR>dump&nbsp;id</VAR>>]
3709                 [<B>-verbose</B>]  [<B>-localauth</B>]  [<B>-cell</B> &lt;<VAR>cell&nbsp;name</VAR>>]  [<B>-help</B> ]
3710
3711 <B>backup dumpi</B> [<B>-n</B> &lt;<VAR>no.&nbsp;of&nbsp;dumps</VAR>>]  [<B>-i</B> &lt;<VAR>dump&nbsp;id</VAR>>]
3712              [<B>-v</B>]  [<B>-l</B>]  [<B>-c</B> &lt;<VAR>cell&nbsp;name</VAR>>]  [<B>-h</B>]
3713 </PRE>
3714 <P><STRONG>Description</STRONG>
3715 <P>The <B>backup dumpinfo</B> command formats and displays the Backup
3716 Database record for the specified dumps. To specify how many of the
3717 most recent dumps to display, starting with the newest one and going back in
3718 time, use the <B>-ndumps</B> argument. To display more detailed
3719 information about a single dump, use the <B>-id</B> argument. To
3720 display the records for the 10 most recent dumps, omit both the
3721 <B>-ndumps</B> and <B>-id</B> arguments.
3722 <P>The <B>-verbose</B> flag produces very detailed information that is
3723 useful mostly for debugging purposes. It can be combined only with the
3724 <B>-id</B> argument.
3725 <P><STRONG>Options</STRONG>
3726 <DL>
3727 <P><DT><B>-ndumps
3728 </B><DD>Displays the Backup Database record for each of the specified number of
3729 dumps that were most recently performed. If the database contains fewer
3730 dumps than are requested, the output includes the records for all existing
3731 dumps. Do not combine this argument with the <B>-id</B> or
3732 <B>-verbose</B> options; omit all options to display the records for
3733 the last 10 dumps.
3734 <P><DT><B>-id
3735 </B><DD>Specifies the dump ID number of a single dump for which to display the
3736 Backup Database record. Precede the <VAR>dump id</VAR> value with the
3737 <B>-id</B> switch; otherwise, the command interpreter interprets it
3738 as the value of the <B>-ndumps</B> argument. Combine this argument
3739 with the <B>-verbose</B> flag if desired, but not with the
3740 <B>-ndumps</B> argument; omit all options to display the records for
3741 the last 10 dumps.
3742 <P><DT><B>-verbose
3743 </B><DD>Provides more detailed information about the dump specified with the
3744 <B>-id</B> argument, which must be provided along with it. Do not
3745 combine this flag with the <B>-ndumps</B> argument.
3746 <P><DT><B>-localauth
3747 </B><DD>Constructs a server ticket using a key from the local
3748 <B>/usr/afs/etc/KeyFile</B> file. The <B>backup</B> command
3749 interpreter presents it to the Backup Server, Volume Server and VL Server
3750 during mutual authentication. Do not combine this flag with the
3751 <B>-cell</B> argument. For more details, see the introductory
3752 <B>backup</B> reference page.
3753 <P><DT><B>-cell
3754 </B><DD>Names the cell in which to run the command. Do not combine this
3755 argument with the <B>-localauth</B> flag. For more details, see the
3756 introductory <B>backup</B> reference page.
3757 <P><DT><B>-help
3758 </B><DD>Prints the online help for this command. All other valid options
3759 are ignored.
3760 </DL>
3761 <P><STRONG>Output</STRONG>
3762 <P>If the <B>-ndumps</B> argument is provided, the output presents the
3763 following information in table form, with a separate line for each dump:
3764 <DL>
3765 <P><DT><B><TT>dumpid</TT>
3766 </B><DD>The dump ID number.
3767 <P><DT><B><TT>parentid</TT>
3768 </B><DD>The dump ID number of the dump's parent dump. A value of
3769 <TT>0</TT> (zero) identifies a full dump.
3770 <P><DT><B><TT>lv</TT>
3771 </B><DD>The depth in the dump hierarchy of the dump level used to create the
3772 dump. A value of <TT>0</TT> (zero) identifies a full dump, in which
3773 case the value in the <TT>parentid</TT> field is also <TT>0</TT>. A
3774 value of <TT>1</TT> or greater indicates an incremental dump made at the
3775 corresponding level in the dump hierarchy.
3776 <P><DT><B><TT>created</TT>
3777 </B><DD>The date and time at which the Backup System started the dump operation
3778 that created the dump.
3779 <P><DT><B><TT>nt</TT>
3780 </B><DD>The number of tapes that contain the data in the dump. A value of
3781 <TT>0</TT> (zero) indicates that the dump operation was terminated or
3782 failed. Use the <B>backup deletedump</B> command to remove such
3783 entries.
3784 <P><DT><B><TT>nvols</TT>
3785 </B><DD>The number of volumes from which the dump includes data. If a
3786 volume spans tapes, it is counted twice. A value of <TT>0</TT> (zero)
3787 indicates that the dump operation was terminated or failed; the value in
3788 the <TT>nt</TT> field is also <TT>0</TT> in this case.
3789 <P><DT><B><TT>dump name</TT>
3790 </B><DD>The dump name in the form
3791 <PRE>   <VAR>volume_set_name</VAR>.<VAR>dump_level_name</VAR> (<VAR>initial_dump_ID</VAR>)
3792
3793 </PRE>
3794 <P>
3795 <P>where <VAR>volume_set_name</VAR> is the name of the volume set, and
3796 <VAR>dump_level_name</VAR> is the last element in the dump level pathname at
3797 which the volume set was dumped.
3798 <P>The <VAR>initial_dump_ID</VAR>, if displayed, is the dump ID of the initial
3799 dump in the dump set to which this dump belongs. If there is no value
3800 in parentheses, the dump is the initial dump in a dump set that has no
3801 appended dumps.
3802 </DL>
3803 <P>If the <B>-id</B> argument is provided alone, the first line of output
3804 begins with the string <TT>Dump</TT> and reports information for the entire
3805 dump in the following fields:
3806 <DL>
3807 <P><DT><B><TT>id</TT>
3808 </B><DD>The dump ID number.
3809 <P><DT><B><TT>level</TT>
3810 </B><DD>The depth in the dump hierarchy of the dump level used to create the
3811 dump. A value of <TT>0</TT> (zero) identifies a full dump. A
3812 value of <TT>1</TT> (one) or greater indicates an incremental dump made at
3813 the specified level in the dump hierarchy.
3814 <P><DT><B><TT>volumes</TT>
3815 </B><DD>The number of volumes for which the dump includes data.
3816 <P><DT><B><TT>created</TT>
3817 </B><DD>The date and time at which the dump operation began.
3818 </DL>
3819 <P>If an XBSA server was the backup medium for the dump (rather than a tape
3820 device or backup data file), the following line appears next:
3821 <PRE>   Backup Service: <VAR>XBSA_program</VAR>: Server: <VAR>hostname</VAR>
3822 </PRE>
3823 <P>where <VAR>XBSA_program</VAR> is the name of the XBSA-compliant program and
3824 <VAR>hostname</VAR> is the name of the machine on which the program runs.
3825 <P>Next the output includes an entry for each tape that houses volume data
3826 from the dump. Following the string <TT>Tape</TT>, the first two
3827 lines of each entry report information about that tape in the following
3828 fields:
3829 <DL>
3830 <P><DT><B><TT>name</TT>
3831 </B><DD>The tape's permanent name if it has one, or its AFS tape name
3832 otherwise, and its tape ID number in parentheses.
3833 <P><DT><B><TT>nVolumes</TT>
3834 </B><DD>The number of volumes for which this tape includes dump data.
3835 <P><DT><B><TT>created</TT>
3836 </B><DD>The date and time at which the Tape Coordinator began writing data to this
3837 tape.
3838 </DL>
3839 <P>Following another blank line, the tape-specific information concludes with
3840 a table that includes a line for each volume dump on the tape. The
3841 information appears in columns with the following headings:
3842 <DL>
3843 <P><DT><B><TT>Pos</TT>
3844 </B><DD>The relative position of each volume in this tape or file. On a
3845 tape, the counter begins at position 2 (the tape label occupies position 1),
3846 and increments by one for each volume. For volumes in a backup data
3847 file, the position numbers start with 1 and do not usually increment only by
3848 one, because each is the ordinal of the 16 KB offset in the file at which the
3849 volume's data begins. The difference between the position numbers
3850 therefore indicates how many 16 KB blocks each volume's data
3851 occupies. For example, if the second volume is at position 5 and the
3852 third volume in the list is at position 9, that means that the dump of the
3853 second volume occupies 64 KB (four 16-KB blocks) of space in the file.
3854 <P><DT><B><TT>Clone time</TT>
3855 </B><DD>For a backup or read-only volume, the time at which it was cloned from its
3856 read/write source. For a Read/Write volume, it is the same as the dump
3857 creation date reported on the first line of the output.
3858 <P><DT><B><TT>Nbytes</TT>
3859 </B><DD>The number of bytes of data in the dump of the volume.
3860 <P><DT><B><TT>Volume</TT>
3861 </B><DD>The volume name, complete with <TT>.backup</TT> or
3862 <TT>.readonly</TT> extension if appropriate.
3863 </DL>
3864 <P>If both the <B>-id</B> and <B>-verbose</B> options are provided,
3865 the output is divided into several sections:
3866 <UL>
3867 <P><LI>The first section, headed by the underlined string <TT>Dump</TT>,
3868 includes information about the entire dump. The fields labeled
3869 <TT>id</TT>, <TT>level</TT>, <TT>created</TT>, and <TT>nVolumes</TT>
3870 report the same values (though in a different order) as appear on the first
3871 line of output when the <B>-id</B> argument is provided by itself.
3872 Other fields of potential interest to the backup operator are:
3873 <DL>
3874 <P><DT><B><TT>Group id</TT>
3875 </B><DD>The dump's <I>group ID number</I>, which is recorded in the
3876 dump's Backup Database record if the <B>GROUPID</B> instruction
3877 appears in the Tape Coordinator's <B>
3878 /usr/afs/backup/CFG_</B><VAR>tcid</VAR> file when the dump is created.
3879 <P><DT><B><TT>maxTapes</TT>
3880 </B><DD>The number of tapes that contain the dump set to which this dump
3881 belongs.
3882 <P><DT><B><TT>Start Tape Seq</TT>
3883 </B><DD>The ordinal of the tape on which this dump begins in the set of tapes that
3884 contain the dump set.
3885 </DL>
3886 <P><LI>For each tape that contains data from this dump, there follows a section
3887 headed by the underlined string <TT>Tape</TT>. The fields labeled
3888 <TT>name</TT>, <TT>written</TT>, and <TT>nVolumes</TT> report the same
3889 values (though in a different order) as appear on the second and third lines
3890 of output when the <B>-id</B> argument is provided by itself. Other
3891 fields of potential interest to the backup operator are:
3892 <DL>
3893 <P><DT><B><TT>expires</TT>
3894 </B><DD>The date and time when this tape can be recycled, because all dumps it
3895 contains have expired.
3896 <P><DT><B><TT>nMBytes Data</TT> and <TT>nBytes Data</TT>
3897 </B><DD>Summed together, these fields represent the total amount of dumped data
3898 actually from volumes (as opposed to labels, filemarks, and other
3899 markers).
3900 <P><DT><B><TT>KBytes Tape Used</TT>
3901 </B><DD>The number of kilobytes of tape (or disk space, for a backup data file)
3902 used to store the dump data. It is generally larger than the sum of the
3903 values in the <TT>nMBytes Data</TT> and <TT>nBytes Data</TT> fields,
3904 because it includes the space required for the label, file marks and other
3905 markers, and because the Backup System writes data at 16 KB offsets, even if
3906 the data in a given block doesn't fill the entire 16 KB.
3907 </DL>
3908 <P><LI>For each volume on a given tape, there follows a section headed by the
3909 underlined string <TT>Volume</TT>. The fields labeled
3910 <TT>name</TT>, <TT>position</TT>, <TT>clone</TT>, and <TT>nBytes</TT>
3911 report the same values (though in a different order) as appear in the table
3912 that lists the volumes in each tape when the <B>-id</B> argument is
3913 provided by itself. Other fields of potential interest to the backup
3914 operator are:
3915 <DL>
3916 <P><DT><B><TT>id</TT>
3917 </B><DD>The volume ID.
3918 <P><DT><B><TT>tape</TT>
3919 </B><DD>The name of the tape containing this volume data.
3920 </DL>
3921 </UL>
3922 <P><STRONG>Examples</STRONG>
3923 <P>The following example displays information about the last five dumps:
3924 <P>The following example displays a more detailed record for a single
3925 dump.
3926 <PRE>   % <B>backup dumpinfo -id 922097346</B>
3927    Dump: id 922097346, level 0, volumes 1, created Mon Mar 22 05:09:06 1999
3928    Tape: name monday.user.backup (922097346)
3929    nVolumes 1, created 03/22/1999 05:09
3930     Pos       Clone time   Nbytes Volume
3931       1 03/22/1999 04:43 27787914 user.pat.backup
3932 </PRE>
3933 <P>The following example displays even more detailed information about the
3934 dump displayed in the previous example (dump ID 922097346). This
3935 example includes only one exemplar of each type of section (<TT>Dump</TT>,
3936 <TT>Tape</TT>, and <TT>Volume</TT>):
3937 <PRE>   % <B>backup dumpinfo -id 922097346 -verbose</B>
3938    Dump
3939    ----
3940    id = 922097346
3941    Initial id = 0
3942    Appended id = 922099568
3943    parent = 0
3944    level = 0
3945    flags = 0x0
3946    volumeSet = user
3947    dump path = /monday1
3948    name = user.monday1
3949    created = Mon Mar 22 05:09:06 1999
3950    nVolumes = 1
3951    Group id  = 10
3952    tapeServer =
3953    format= user.monday1.%d
3954    maxTapes = 1
3955    Start Tape Seq = 1
3956    name = pat
3957    instance =
3958    cell =
3959    Tape
3960    ----
3961    tape name = monday.user.backup
3962    AFS tape name = user.monday1.1
3963    flags = 0x20
3964    written = Mon Mar 22 05:09:06 1999
3965    expires = NEVER
3966    kBytes Tape Used = 121
3967    nMBytes Data = 0
3968    nBytes  Data = 19092
3969    nFiles = 0
3970    nVolumes = 1
3971    seq = 1
3972    tapeid = 0
3973    useCount = 1
3974    dump = 922097346
3975    Volume
3976    ------
3977    name = user.pat.backup
3978    flags = 0x18
3979    id = 536871640
3980    server =
3981    partition = 0
3982    nFrags = 1
3983    position = 2
3984    clone = Mon Mar 22 04:43:06 1999
3985    startByte = 0
3986    nBytes = 19092
3987    seq = 0
3988    dump = 922097346
3989    tape = user.monday1.1
3990 </PRE>
3991 <P><STRONG>Privilege Required</STRONG>
3992 <P>The issuer must be listed in the <B>/usr/afs/etc/UserList</B> file on
3993 every machine where the Backup Server is running, or must be logged onto a
3994 server machine as the local superuser <B>root</B> if the
3995 <B>-localauth</B> flag is included.
3996 <P><STRONG>Related Information</STRONG>
3997 <P><B>backup</B>
3998 <P><B>backup deletedump</B>
3999 <P>
4000 <H3><A NAME="HDRBK_STATUS" HREF="aurns002.htm#ToC_52">backup status</A></H3>
4001 <P><STRONG>Purpose</STRONG>
4002 <P>Reports a Tape Coordinator's status
4003 <P><STRONG>Synopsis</STRONG>
4004 <PRE><B>backup status</B> [<B>-portoffset</B> &lt;<VAR>TC&nbsp;port&nbsp;offset</VAR>>]
4005               [<B>-localauth</B>]  [<B>-cell</B> &lt;<VAR>cell&nbsp;name</VAR>>]  [<B>-help</B>]
4006
4007 <B>backup st</B> [<B>-p</B> &lt;<VAR>TC&nbsp;port&nbsp;offset</VAR>>]  [<B>-l</B>]  [<B>-c</B> &lt;<VAR>cell&nbsp;name</VAR>>]  [<B>-h</B>]
4008 </PRE>
4009 <P><STRONG>Description</STRONG>
4010 <P>The <B>backup status</B> command displays which operation, if any, the
4011 indicated Tape Coordinator is currently executing.
4012 <P><STRONG>Options</STRONG>
4013 <DL>
4014 <P><DT><B>-portoffset
4015 </B><DD>Specifies the port offset number of the Tape Coordinator for which to
4016 report the status.
4017 <P><DT><B>-localauth
4018 </B><DD>Constructs a server ticket using a key from the local
4019 <B>/usr/afs/etc/KeyFile</B> file. The <B>backup</B> command
4020 interpreter presents it to the Backup Server, Volume Server and VL Server
4021 during mutual authentication. Do not combine this flag with the
4022 <B>-cell</B> argument. For more details, see the introductory
4023 <B>backup</B> reference page.
4024 <P><DT><B>-cell
4025 </B><DD>Names the cell in which to run the command. Do not combine this
4026 argument with the <B>-localauth</B> flag. For more details, see the
4027 introductory <B>backup</B> reference page.
4028 <P><DT><B>-help
4029 </B><DD>Prints the online help for this command. All other valid options
4030 are ignored.
4031 </DL>
4032 <P><STRONG>Output</STRONG>
4033 <P>The following message indicates that the Tape Coordinator is not currently
4034 performing an operation:
4035 <PRE>   Tape coordinator is idle
4036 </PRE>
4037 <P>Otherwise, the output includes a message of the following format for each
4038 running or pending operation:
4039 <PRE>   Task <VAR>task_ID</VAR>:  <VAR>operation</VAR>:   <VAR>status</VAR>
4040 </PRE>
4041 <P>where
4042 <DL>
4043 <P><DT><B><VAR>task_ID</VAR>
4044 </B><DD>Is a task identification number assigned by the Tape Coordinator.
4045 It begins with the Tape Coordinator's port offset number.
4046 <P><DT><B><VAR>operation</VAR>
4047 </B><DD>Identifies the operation the Tape Coordinator is performing, which is
4048 initiated by the indicated command:
4049 <UL>
4050 <P><LI><TT>Dump</TT> (the <B>backup dump</B> command)
4051 <P><LI><TT>Restore</TT> (the <B>backup diskrestore</B>, <B>backup
4052 volrestore</B>, or <B>backup volsetrestore</B> commands)
4053 <P><LI><TT>Labeltape</TT> (the <B>backup labeltape</B> command)
4054 <P><LI><TT>Scantape</TT> (the <B>backup scantape</B> command)
4055 <P><LI><TT>SaveDb</TT> (the <B>backup savedb</B> command)
4056 <P><LI><TT>RestoreDb</TT> (the <B>backup restoredb</B> command)
4057 </UL>
4058 <P><DT><B><VAR>status</VAR>
4059 </B><DD>Indicates the job's current status in one of the following
4060 messages.
4061 <DL>
4062 <P><DT><B><VAR>number</VAR> <TT>Kbytes transferred, volume</TT> <VAR>volume_name</VAR>
4063 </B><DD>For a running dump operation, indicates the number of kilobytes copied to
4064 tape or a backup data file so far, and the volume currently being
4065 dumped.
4066 <P><DT><B><VAR>number</VAR> <TT>Kbytes, restore.volume</TT>
4067 </B><DD>For a running restore operation, indicates the number of kilobytes copied
4068 into AFS from a tape or a backup data file so far.
4069 <P><DT><B><TT>[abort requested]</TT>
4070 </B><DD>The <B>(backup) kill</B> command was issued, but the termination
4071 signal has yet to reach the Tape Coordinator.
4072 <P><DT><B><TT>[abort sent]</TT>
4073 </B><DD>The operation is canceled by the <B>(backup) kill</B> command.
4074 Once the Backup System removes an operation from the queue or stops it from
4075 running, it no longer appears at all in the output from the command.
4076 <P><DT><B><TT>[butc contact lost]</TT>
4077 </B><DD>The <B>backup</B> command interpreter cannot reach the Tape
4078 Coordinator. The message can mean either that the Tape Coordinator
4079 handling the operation was terminated or failed while the operation was
4080 running, or that the connection to the Tape Coordinator timed out.
4081 <P><DT><B><TT>[done]</TT>
4082 </B><DD>The Tape Coordinator has finished the operation.
4083 <P><DT><B><TT>[drive wait]</TT>
4084 </B><DD>The operation is waiting for the specified tape drive to become
4085 free.
4086 <P><DT><B><TT>[operator wait]</TT>
4087 </B><DD>The Tape Coordinator is waiting for the backup operator to insert a tape
4088 in the drive.
4089 </DL>
4090 </DL>
4091 <P>If the Tape Coordinator is communicating with an XBSA server (a third-party
4092 backup utility that implements the Open Group's Backup Service API
4093 [XBSA]), the following message appears last in the output:
4094 <PRE>   <VAR>XBSA_program</VAR> Tape coordinator
4095 </PRE>
4096 <P>where <VAR>XBSA_program</VAR> is the name of the XBSA-compliant
4097 program.
4098 <P><STRONG>Examples</STRONG>
4099 <P>The following example shows that the Tape Coordinator with port offset 4
4100 has so far dumped about 1.5 MB of data for the current dump operation,
4101 and is currently dumping the volume named
4102 <B>user.pat.backup</B>:
4103 <PRE>   % <B>backup status -portoffset 4</B>
4104    Task 4001:  Dump:   1520 Kbytes transferred,  volume user.pat.backup
4105 </PRE>
4106 <P><STRONG>Privilege Required</STRONG>
4107 <P>The issuer must be listed in the <B>/usr/afs/etc/UserList</B> file on
4108 every machine where the Backup Server is running, or must be logged onto a
4109 server machine as the local superuser <B>root</B> if the
4110 <B>-localauth</B> flag is included.
4111 <P><STRONG>Related Information</STRONG>
4112 <P><B>backup</B>
4113 <P><B>butc</B>
4114 <P>
4115 <H3><A NAME="HDRVOS_DELENTRY" HREF="aurns002.htm#ToC_53">vos delentry</A></H3>
4116 <P><STRONG>Purpose</STRONG>
4117 <P>Removes a volume entry from the VLDB.
4118 <P><STRONG>Synopsis</STRONG>
4119 <PRE><B>vos delentry</B> [<B>-id</B> &lt;<VAR>volume&nbsp;name&nbsp;or&nbsp;ID</VAR>><SUP>+</SUP>]
4120              [<B>-prefix</B> &lt;<VAR>prefix&nbsp;of&nbsp;volume&nbsp;whose&nbsp;VLDB&nbsp;entry&nbsp;is&nbsp;to&nbsp;be&nbsp;deleted</VAR>>]
4121              [<B>-server</B> &lt;<VAR>machine&nbsp;name</VAR>>]  [<B>-partition</B> &lt;<VAR>partition&nbsp;name</VAR>>]
4122              [<B>-cell</B> &lt;<VAR>cell&nbsp;name</VAR>>]  [<B>-noauth</B>]  [<B>-localauth</B>]  [<B>-verbose</B>]  [<B>-help</B>]
4123
4124 <B>vos de</B> [<B>-i</B> &lt;<VAR>volume&nbsp;name&nbsp;or&nbsp;ID</VAR>><SUP>+</SUP>]
4125        [<B>-pr</B> &lt;<VAR>prefix&nbsp;of&nbsp;volume&nbsp;whose&nbsp;VLDB&nbsp;entry&nbsp;is&nbsp;to&nbsp;be&nbsp;deleted</VAR>>]
4126        [<B>-s</B> &lt;<VAR>machine&nbsp;name</VAR>>]  [<B>-pa</B> &lt;<VAR>partition&nbsp;name</VAR>>]  [<B>-c</B> &lt;<VAR>cell&nbsp;name</VAR>>]
4127        [<B>-n</B>]  [<B>-l</B>]  [<B>-v</B>]  [<B>-h</B>]
4128 </PRE>
4129 <P><STRONG>Description</STRONG>
4130 <P>The <B>vos delentry</B> command removes the Volume Location Database
4131 (VLDB) entry for each specified volume. Specify one or more read/write
4132 volumes; specifying a read-only or backup volume results in an
4133 error. The command has no effect on the actual volumes on file server
4134 machines, if they exist.
4135 <P>This command is useful if a volume removal operation did not update the
4136 VLDB (perhaps because the <B>vos zap</B> command was used), but the system
4137 administrator does not feel it is necessary to use the <B>vos syncserv</B>
4138 and <B>vos syncvldb</B> commands to synchronize an entire file server
4139 machine.
4140 <P>To remove the VLDB entry for a single volume, use the <B> -id</B>
4141 argument. To remove groups of volumes, combine the <B> -prefix</B>,
4142 <B>-server</B>, and <B>-partition</B> arguments. The following
4143 list describes how to remove the VLDB entry for the indicated group of
4144 volumes:
4145 <UL>
4146 <P><LI>For every volume whose name begins with a certain character string (for
4147 example, <B>sys.</B> or <B>user.</B>): use the
4148 <B>-prefix</B> argument.
4149 <P><LI>Every volume for which the VLDB lists a site on a certain file server
4150 machine: specify the file server name with the <B>-server</B>
4151 argument.
4152 <P><LI>Every volume for which the VLDB lists a site on a partition of the same
4153 name (for instance, on the <B>/vicepa</B> partition on any file server
4154 machine): specify the partition name with the <B> -partition</B>
4155 argument.
4156 <P><LI>Every volume for which the VLDB lists a site one a specific partition of a
4157 file server machine: specify both the <B>-server</B> and
4158 <B>-partition</B> arguments.
4159 <P><LI>Every volume whose name begins with a certain prefix and for which the
4160 VLDB lists a site on a file server machine: combine the
4161 <B>-prefix</B> and <B>-server</B> arguments. Combine the
4162 <B>-prefix</B> argument with the <B>-partition</B> argument, or both
4163 the <B>-server</B> and <B>-partition</B> arguments, to remove a more
4164 specific group of volumes.
4165 </UL>
4166 <P><STRONG>Cautions</STRONG>
4167 <P>A single VLDB entry represents all versions of a volume (read/write,
4168 readonly, and backup). The command removes the entire entry even though
4169 only the read/write volume is specified.
4170 <P>Do not use this command to remove a volume in normal circumstances; it
4171 does not remove a volume from the file server machine, and so is likely to
4172 make the VLDB inconsistent with state of the volumes on server
4173 machines. Use the <B>vos remove</B> command to remove both the
4174 volume and its VLDB entry.
4175 <P><STRONG>Options</STRONG>
4176 <DL>
4177 <P><DT><B>-id
4178 </B><DD>Specifies the complete name or volume ID number of each read/write volume
4179 for which to remove the VLDB entry. The entire entry is removed.
4180 Provide this argument or some combination of the <B>-prefix</B>,
4181 <B>-server</B>, and <B>-partition</B> arguments.
4182 <P><DT><B>-prefix
4183 </B><DD>Specifies a character string of any length; the VLDB entry for a
4184 volume whose name begins with the string is removed. Include field
4185 separators (such as periods) if appropriate. Combine this argument with
4186 the <B>-server</B> argument, <B>-partition</B> argument, or
4187 both.
4188 <P><DT><B>-server
4189 </B><DD>Identifies a file server machine; if a volume's VLDB entry lists
4190 a site on the machine, the entry is removed. Provide the machine's
4191 IP address or its host name (either fully qualified or using an unambiguous
4192 abbreviation). For details, see the introductory reference page for the
4193 <B>vos</B> command suite.
4194 <P>Combine this argument with the <B>-prefix</B> argument, the
4195 <B>-partition</B> argument, or both.
4196 <P><DT><B>-partition
4197 </B><DD>Identifies a partition; if a volume's VLDB entry lists a site on
4198 the partition, the entry is removed. Provide the partition's
4199 complete name with preceding slash (for example, <B>/vicepa</B>) or use
4200 one of the three acceptable abbreviated forms. For details, see the
4201 introductory reference page for the <B>vos</B> command suite.
4202 <P>Combine this argument with the <B>-prefix</B> argument, the
4203 <B>-server</B> argument, or both.
4204 <P><DT><B>-cell
4205 </B><DD>Names the cell in which to run the command. Do not combine this
4206 argument with the <B>-localauth</B> flag. For more details, see the
4207 introductory <B>vos</B> reference page.
4208 <P><DT><B>-noauth
4209 </B><DD>Assigns the unprivileged identity <B>anonymous</B> to the
4210 issuer. Do not combine this flag with the <B>-localauth</B>
4211 flag. For more details, see the introductory <B>vos</B> reference
4212 page.
4213 <P><DT><B>-localauth
4214 </B><DD>Constructs a server ticket using a key from the local
4215 <B>/usr/afs/etc/KeyFile</B> file. The <B>vos</B> command
4216 interpreter presents it to the Volume Server and Volume Location Server during
4217 mutual authentication. Do not combine this flag with the
4218 <B>-cell</B> argument or <B>-noauth</B> flag. For more details,
4219 see the introductory <B>vos</B> reference page.
4220 <P><DT><B>-verbose
4221 </B><DD>Produces on the standard output stream a detailed trace of the
4222 command's execution. If this argument is omitted, only warnings
4223 and error messages appear.
4224 <P><DT><B>-help
4225 </B><DD>Prints the online help for this command. All other valid options
4226 are ignored.
4227 </DL>
4228 <P><STRONG>Output</STRONG>
4229 <P>The following message confirms the success of the command by indicating how
4230 many VLDB entries were removed.
4231 <PRE>   Deleted <VAR>number</VAR> VLDB entries
4232 </PRE>
4233 <P><STRONG>Examples</STRONG>
4234 <P>The following command removes the VLDB entry for the volume
4235 <B>user.temp</B>.
4236 <PRE>   % <B>vos delentry user.temp</B>
4237 </PRE>
4238 <P>The following command removes the VLDB entry for every volume whose name
4239 begins with the string <B>test</B> and for which the VLDB lists a site on
4240 the file server machine <B>fs3.abc.com</B>.
4241 <PRE>   % <B>vos delentry -prefix test -server fs3.abc.com</B>
4242 </PRE>
4243 <P><STRONG>Privilege Required</STRONG>
4244 <P>The issuer must be listed in the <B>/usr/afs/etc/UserList</B> file on
4245 the machine specified with the <B>-server</B> argument and on each
4246 database server machine. If the <B>-localauth</B> flag is included,
4247 the issuer must instead be logged on to a server machine as the local
4248 superuser <B>root</B>.
4249 <P><STRONG>Related Information</STRONG>
4250 <P><B>vos</B>
4251 <P><B>vos remove</B>
4252 <P><B>vos syncserv</B>
4253 <P><B>vos syncvldb</B>
4254 <P><B>vos zap</B>
4255 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="aurns002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="aurns003.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> <P>
4256 <!-- Begin Footer Records  ========================================== -->
4257 <P><HR><B>
4258 <br>&#169; <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A>  All Rights Reserved
4259 </B>
4260 <!-- End Footer Records  ============================================ -->
4261 <A NAME="Bot_Of_Page"></A>
4262 </BODY></HTML>