[openafs.git] / doc / html / ReleaseNotes-3.6 / aurns004.htm
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=""><B></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=""><B></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 or higher of the AIX
349 <B></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></B>
356 fileset is installed, issue the following command:
357 <PRE>   # <B>lslpp -L</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></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=""><B></B>&lt;/A>
538 <P><LI>In Europe: &lt;A
539 HREF=""><B></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>
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 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></B> or one of its
605 mirror sites. There is also kernel upgrade information at &lt;A
606 HREF=""><B></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=""><B></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=""><B></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/</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 or higher of the AIX
731 <B></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 or higher of the AIX
747 <B></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
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>
861    # <B>cd</B> <VAR>format_name</VAR>
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:
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></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></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.
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
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=""><B></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>  
1385    % <B>cp -rp  etc  /afs/.</B><VAR>cellname</VAR><B>/temp</B>  
1387    % <B>cp -rp  include  /afs/.</B><VAR>cellname</VAR><B>/temp</B>  
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>
1492    # <B>mv  bin  bin.old</B>
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>   
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>   
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>
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>
1765    # <B>rm  rc.afs</B>
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>
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>
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>
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>
1929    # <B>rm  afs.rc</B>
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>
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>
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>
2023    # <B>rm afs.rc</B>
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>
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>
2069    # <B>cd /</B>
2071    # <B>shutdown -r now</B>             
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></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  /var/sysgen/system</B>
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>
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>
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>
2287    # <B>rm afs.rc</B>
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>
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>
2383    # <B>rm afs.rc afs.conf</B>
2385    # <B>ln -s  /etc/rc.d/init.d/afs  afs.rc</B>
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>
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>
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>
2483    # <B>rm afs.rc</B>
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>
2534    % <B>vos release root.cell</B>
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> 
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>
2552    # <B>cd</B>  <VAR>format_name</VAR>
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.
2650 </B><DD>Controls whether the Tape Coordinator prompts for the first tape.
2651 Does not apply to XBSA servers.
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.
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).
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.
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.
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.
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.