doc: fix kindle builds of documentation
[openafs.git] / doc / xml / QuickStartUnix / auqbg004.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <chapter id="HDRWQ6">
3   <title>Installation Overview</title>
4
5   <para>This chapter describes the type of instructions provided in this
6   guide and the hardware and software requirements for installing
7   <trademark class="registered">AFS</trademark>.</para>
8
9   <para>Before beginning the installation of your cell's first machine,
10   read this chapter and the material from the <citetitle>OpenAFS
11   Administration Guide</citetitle> listed in <link
12   linkend="HDRWQ8">Recommended Reading List</link>. It is also best to
13   read through <link linkend="HDRWQ17">Installing the First AFS
14   Machine</link> before beginning the installation, so that you understand
15   the overall scope of the installation procedure. Similarly, before
16   installing additional server or client machines it is best to read
17   through <link linkend="HDRWQ99">Installing Additional Server
18   Machines</link> and <link linkend="HDRWQ133">Installing Additional
19   Client Machines</link>.</para>
20
21   <para>If you are already running a version of AFS, consult the upgrade
22   instructions in the <citetitle>OpenAFS Release Notes</citetitle> before
23   proceeding with the installation.</para>
24   
25   <para>If you are working with an existing cell that uses
26   <emphasis role="bold">kaserver</emphasis> or external Kerberos v4 for
27   authentication, please see the notes in 
28   <link linkend="KAS001">kaserver and legacy Kerberos 5 authentication</link>
29   and the rest of Appendix B for how the installation
30   steps will differ from those described in the rest of this guide.</para>
31
32   <sect1 id="HDRWQ7">
33     <title>The Procedures Described in this Guide</title>
34
35     <para>This guide describes two types of installation procedures:
36     initial procedures (such as installing the first AFS machine or
37     incorporating AFS into the kernel) and as-needed procedures (such as
38     installing additional server machines or client machines).</para>
39
40     <sect2 id="Header_9">
41       <title>Required Initial Procedures</title>
42
43       <para>You must perform the following basic procedures to start using
44       AFS.</para>
45
46       <sect3 id="Header_10">
47         <title>Incorporating AFS Into the Kernel</title>
48
49         <para>You must incorporate AFS modifications into the kernel of
50         every client machine. On some operating systems you must also 
51         incorporate these modifications into the kernels of server machines. 
52         Depending on 
53         the operating system, you either use a program for dynamic kernel
54         loading, build a new static kernel, or can choose between the
55         two. For your convenience, the instructions for incorporating AFS
56         into the kernel appear in full in every chapter where you need to
57         use them.
58           <indexterm>
59             <primary>roles for first AFS machine</primary>
60           </indexterm>
61           <indexterm>
62             <primary>first AFS machine</primary>
63             <secondary>roles</secondary>
64           </indexterm>
65         </para>
66       </sect3>
67
68       <sect3 id="Header_11">
69         <title>Installing the First AFS Machine</title>
70
71         <para>You install the first AFS machine in your cell to function
72         as both an AFS server and client machine.  You can disable the
73         client functionality after completing the installation, if you
74         wish.</para>
75
76         <para>The first server machine in a cell performs several
77         functions:
78           <itemizedlist>
79             <listitem>
80               <para>It may act as the <emphasis>system control
81               machine</emphasis>, distributing certain
82               configuration files to the other server machines in the
83               cell</para>
84             </listitem>
85
86             <listitem>
87               <para>It may act as the <emphasis>binary distribution
88               machine</emphasis> for its system type, distributing AFS
89               binaries to other server machines of its system type</para>
90             </listitem>
91
92             <listitem>
93               <para>It acts as the first <emphasis>database server
94               machine</emphasis>, running the server processes that
95               maintain the AFS administrative databases</para>
96             </listitem>
97           </itemizedlist>
98         </para>
99
100         <para>After you install server and client functionality, you
101         complete other procedures specific to the first machine, including
102         setting up the top levels of your cell's AFS filespace.</para>
103       </sect3>
104     </sect2>
105
106     <sect2 id="Header_12">
107       <title>As-needed Procedures</title>
108
109       <sect3 id="Header_13">
110         <title>Upgrading the Operating System</title>
111
112         <para>Upgrading the operating system requires you to take several
113         steps to protect data and AFS-modified binaries from being lost or
114         overwritten. For guidelines, see <link linkend="HDRWQ14">About
115         Upgrading the Operating System</link>.</para>
116       </sect3>
117
118       <sect3 id="Header_14">
119         <title>Installing Additional File Server Machines</title>
120
121         <para>See <link linkend="HDRWQ100">Installing an Additional File
122         Server Machine</link>.</para>
123       </sect3>
124
125       <sect3 id="Header_15">
126         <title>Configuring or Decommissioning Database Server Machines</title>
127
128         <para>See <link linkend="HDRWQ114">Installing Database Server
129         Functionality</link> and <link linkend="HDRWQ125">Removing
130         Database Server Functionality</link>.</para>
131       </sect3>
132
133       <sect3 id="Header_16">
134         <title>Installing Additional AFS Client Machines</title>
135
136         <para>See <link linkend="HDRWQ133">Installing Additional Client
137         Machines</link>.</para>
138       </sect3>
139
140       <sect3 id="Header_17">
141         <title>Building AFS from Source Code</title>
142
143         <para>See <link linkend="HDRWQ163">Appendix A, Building AFS from
144         Source Code</link></para>
145       </sect3>
146       
147       <sect3 id="Header_17a">
148         <title>Configuring Legacy Components</title>
149         <para>See <link linkend="Legacy">Appendix B, Configuring Legacy
150         Components</link>
151           <indexterm>
152             <primary>background reading list</primary>
153           </indexterm>
154           <indexterm>
155             <primary>reading list for background information</primary>
156           </indexterm>
157         </para>
158       </sect3>
159     </sect2>
160   </sect1>
161
162   <sect1 id="HDRWQ8">
163     <title>Recommended Reading List</title>
164
165     <para>To develop the best understanding of the overall scope of an
166     installation procedure, read through the entire chapter or section
167     that describes it before performing any actions.</para>
168
169     <para>In addition, familiarity with some basic AFS concepts can make
170     the installation more efficient, because you understand better the
171     purpose of the steps. The following is a prioritized list of material
172     to read before installing the first AFS machine. At minimum, read the
173     first chapter of the <citetitle>OpenAFS Administration
174     Guide</citetitle>.  Then continue your reading in the indicated order,
175     as extensively as you can. It is more important at this point to read
176     the conceptual material in each section than the instructions.</para>
177
178     <para><emphasis role="bold">Selected Topics in the <emphasis>OpenAFS
179     Administration Guide</emphasis></emphasis>
180       <itemizedlist>
181         <listitem>
182           <para>The chapter titled <emphasis>An Overview of AFS
183           Administration</emphasis></para>
184         </listitem>
185
186         <listitem>
187           <para>Selected sections in the <emphasis>Administering Server
188           Machines</emphasis> chapter: <emphasis>Local Disk Files on a
189           Server Machine</emphasis>, <emphasis>The Four Roles for a Server
190           Machine</emphasis>, <emphasis>Maintaining the Server CellServDB
191           File</emphasis></para>
192         </listitem>
193
194         <listitem>
195           <para>Selected sections in the <emphasis>Monitoring and
196           Controlling Server Processes</emphasis> chapter:
197           <emphasis>Controlling and Checking Process
198           Status</emphasis></para>
199         </listitem>
200
201         <listitem>
202           <para>Selected sections in the <emphasis>Managing Server
203           Encryption Keys</emphasis> chapter: <emphasis>About Server
204           Encryption Keys</emphasis></para>
205         </listitem>
206
207         <listitem>
208           <para>Selected sections in the <emphasis>Managing
209           Volumes</emphasis> chapter: <emphasis>About Volumes</emphasis>,
210           <emphasis>Creating Read/write Volumes</emphasis>,
211           <emphasis>Clones and Cloning</emphasis>, <emphasis>Mounting
212           Volumes</emphasis></para>
213         </listitem>
214
215         <listitem>
216           <para>Selected sections in the <emphasis>Administering Client
217           Machines and the Cache Manager</emphasis> chapter:
218           <emphasis>Overview of Cache Manager Customization</emphasis>,
219           <emphasis>Configuration and Cache-related Files on the Local
220           Disk</emphasis>, <emphasis>Determining the Cache Type, Size, and
221           Location</emphasis></para>
222         </listitem>
223
224         <listitem>
225           <para>Selected sections in the <emphasis>Managing Access Control
226           Lists</emphasis> chapter: <emphasis>Protecting Data in
227           AFS</emphasis></para>
228         </listitem>
229       </itemizedlist></para>
230
231     <para><emphasis role="bold">More Selected Topics in the
232     <emphasis>OpenAFS Administration Guide</emphasis></emphasis> 
233       <itemizedlist>
234         <listitem>
235           <para>Selected sections in the <emphasis>Managing
236           Volumes</emphasis> chapter: <emphasis>Creating and Releasing
237           Read-only Volumes (Replication)</emphasis>, <emphasis>Creating
238           Backup Volumes</emphasis></para>
239         </listitem>
240
241         <listitem>
242           <para>Selected sections in the <emphasis>Administering the
243           Protection Database</emphasis> chapter: <emphasis>About the
244           Protection Database</emphasis></para>
245         </listitem>
246
247         <listitem>
248           <para>Selected sections in the <emphasis>Administering User
249           Accounts</emphasis> chapter: <emphasis>The Components of an AFS
250           User Account</emphasis></para>
251         </listitem>
252
253         <listitem>
254           <para>Selected sections in the <emphasis>Managing Administrative
255           Privilege</emphasis> chapter: <emphasis>An Overview of
256           Administrative Privilege</emphasis></para>
257         </listitem>
258       </itemizedlist>
259     </para>
260   </sect1>
261
262   <sect1 id="HDRWQ9">
263     <title>Requirements</title>
264
265     <para>You must comply with the following requirements to install AFS successfully. <indexterm>
266         <primary>root superuser</primary>
267
268         <secondary>as installer's login identity</secondary>
269       </indexterm></para>
270
271     <sect2 id="Header_20">
272       <title>Login Identity</title>
273
274       <para>Log into the machine you are installing as the local superuser <emphasis role="bold">root</emphasis>. When instructed,
275       also authenticate with AFS as the administrative user <emphasis role="bold">admin</emphasis>. <indexterm>
276           <primary>overview</primary>
277
278           <secondary>general installation requirements</secondary>
279         </indexterm> <indexterm>
280           <primary>requirements</primary>
281
282           <secondary>general</secondary>
283         </indexterm></para>
284     </sect2>
285
286     <sect2 id="HDRWQ10">
287       <title>General Requirements</title>
288
289       <itemizedlist>
290         <listitem>
291           <para>You must have a Kerberos 5 realm running for your site, and
292           the ability to create new principals within that realm. If you are
293           working with an existing cell using <emphasis>kaserver</emphasis>
294           or Kerberos v4 authentication, please see 
295           <link linkend="KAS001">kaserver and legacy Kerberos 4 authentication</link> 
296           for modifications to the following instructions.</para>
297         </listitem>
298
299         <listitem>
300           <para>You must have a NTP, or similar, timeservice running. Each AFS
301           machine should derive its system time from this timeservice. If you
302           are working with an existing cell, and wish to use AFS's internal
303           time service, please see Appendix B for modifications to the following
304           instructions.</para>
305         </listitem>
306
307         <listitem>
308           <para>You must have an OpenAFS Binary Distribution for each system 
309           type you are installing, or have built a binary from the supplied 
310           source code. Unless otherwise noted, the Binary Distribution 
311           includes software for both client and server machines.</para>
312         </listitem>
313
314         <listitem>
315           <para>All AFS machines that belong to a cell must be able to access each other via the network.</para>
316         </listitem>
317
318         <listitem>
319           <para>The machine must be running the standard, vendor-supplied version of the operating system supported by the current
320           version of AFS. The operating system must already be installed on the machine's root partition.</para>
321         </listitem>
322
323         <listitem>
324           <para>You must be familiar with the current operating system and disk configuration of the machine you are
325           installing.</para>
326         </listitem>
327
328         <listitem>
329           <para>All hardware and non-AFS software on the machine must be functioning normally.</para>
330         </listitem>
331
332         <listitem>
333           <para>No critical processes can be running on the machine you are installing, because you may need to reboot it during the
334           installation.</para>
335         </listitem>
336       </itemizedlist>
337
338       <indexterm>
339         <primary>file server machine</primary>
340
341         <secondary>requirements for installation</secondary>
342       </indexterm>
343
344       <indexterm>
345         <primary>requirements</primary>
346
347         <secondary>file server machine (general)</secondary>
348       </indexterm>
349     </sect2>
350
351     <sect2 id="HDRWQ11">
352       <title>File Server Machine Requirements</title>
353
354       <itemizedlist>
355         <listitem>
356           <para>Cell configuration is simplest if the first machine you install has the lowest IP address of any database server
357           machine you currently plan to install. If you later configure a machine with a lower IP address as a database server
358           machine, you must update the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on all of your cell's client
359           machines before the installation. For further discussion, see <link linkend="HDRWQ114">Installing Database Server
360           Functionality</link>.</para>
361         </listitem>
362
363         <listitem>
364           <para>The partition mounted on the <emphasis role="bold">/usr</emphasis> directory must have at least 18 MB of disk space
365         <!-- XXX - Is this still true - how big are our binaries these days? -->
366           available for storing the AFS server binaries (stored by convention in the <emphasis role="bold">/usr/afs/bin</emphasis>
367           directory). If the machine is also a client, there must be additional local disk space available, as specified in <link
368           linkend="HDRWQ12">Client Machine Requirements</link>. The complete set of AFS binaries requires yet more space, but they
369           are normally stored in an AFS volume rather than on a machine's local disk.</para>
370
371           <para>More significant amounts of space on the partition are required by the administrative databases stored in the
372           <emphasis role="bold">/usr/afs/db</emphasis> directory and the server process log files stored in the <emphasis
373           role="bold">/usr/afs/logs</emphasis> directory. The exact requirement depends on many factors, such as the size of your
374           cell and how often you truncate the log files.</para>
375         </listitem>
376
377         <listitem>
378           <para>There must be at least one partition (or logical volume, if the operating system and AFS support them) dedicated
379           exclusively to storing AFS volumes. The total number and size of server partitions on all file server machines in the cell
380           determines how much space is available for AFS files.</para>
381         </listitem>
382       </itemizedlist>
383
384       <indexterm>
385         <primary>client machine</primary>
386
387         <secondary>requirements for installation</secondary>
388       </indexterm>
389
390       <indexterm>
391         <primary>requirements</primary>
392
393         <secondary>client machine</secondary>
394       </indexterm>
395     </sect2>
396
397     <sect2 id="HDRWQ12">
398       <title>Client Machine Requirements</title>
399
400       <itemizedlist>
401         <listitem>
402           <para>The partition mounted on the <emphasis role="bold">/usr</emphasis> directory must have at least 4 MB of disk space
403           available for storing the AFS client binaries and kernel library files (stored by convention in the <emphasis
404           role="bold">/usr/vice/etc</emphasis> directory). The complete set of AFS binaries requires more space, but they are
405           normally stored in an AFS volume rather than on a machine's local disk. For most system types, the instructions have you
406           copy only the one kernel library file appropriate for the machine you are installing. If you choose to store all of the
407           library files on the local disk, the space requirement can be significantly greater.</para>
408         </listitem>
409
410         <listitem>
411           <para>On a client machine that uses a disk cache, there must be enough free space on the cache partition (by convention,
412           mounted on the <emphasis role="bold">/usr/vice/cache</emphasis> directory) to accommodate the cache. The minimum
413           recommended cache size is 10 MB, but larger caches generally perform better.</para>
414         </listitem>
415
416         <listitem>
417           <para>On a client machine that uses a memory cache, there must be at least 5 MB of machine memory to devote to caching,
418           but again more memory generally leads to better performance. For further discussion, see the sections in <link
419           linkend="HDRWQ133">Installing Additional Client Machines</link> about configuring the cache.</para>
420         </listitem>
421       </itemizedlist>
422
423       <indexterm>
424         <primary>system types supported</primary>
425       </indexterm>
426
427       <indexterm>
428         <primary>supported system types</primary>
429       </indexterm>
430     </sect2>
431   </sect1>
432
433   <sect1 id="HDRWQ13">
434     <title>Supported System Types</title>
435
436     <para>The <emphasis>OpenAFS Release Notes</emphasis> for each AFS release list the supported system types. Support for
437     subsequent revisions of an operating system often becomes available between AFS releases. The OpenAFS mailing lists can provide information regarding this interim support</para>
438
439     <para>It is the goal of OpenAFS to support AFS on a wide range of popular system types.
440     Furthermore, each time an operating system vendor releases a new general availability version of a supported operating system,
441     it is a goal to support AFS on it within a short time. Support can be delayed a bit longer if it is necessary to
442     generate completely new binaries.</para>
443
444     <para>It is not always possible to support AFS on every intermediate version of an operating system or for certain processor
445     types. In some cases, platform limitations make certain AFS functionality (such as file server or NFS/AFS translator
446     functionality) unavailable on one or more platforms. For a list of limitations, see the <emphasis>OpenAFS Release
447     Notes</emphasis> or ask on the OpenAFS mailing lists. <indexterm>
448         <primary>operating system upgrades</primary>
449       </indexterm> <indexterm>
450         <primary>upgrading the operating system</primary>
451       </indexterm> <indexterm>
452         <primary>AFS server partition</primary>
453
454         <secondary>protecting during operating system upgrade</secondary>
455       </indexterm> <indexterm>
456         <primary>files</primary>
457
458         <secondary>protecting during operating system upgrade</secondary>
459       </indexterm></para>
460   </sect1>
461
462   <sect1 id="HDRWQ14">
463     <title>About Upgrading the Operating System</title>
464
465     <para>Whenever you upgrade an AFS machine to a different operating system, you must take several actions to maintain proper AFS
466     functionality. These actions include, but are not necessarily limited to, the following. <itemizedlist>
467         <listitem>
468           <para>On platforms running the inode fileserver, unmount the AFS server partitions (mounted at <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>
469           directories) on all file server machines, to prevent the vendor-supplied <emphasis role="bold">fsck</emphasis> program
470           from running on them when you reboot the machine during installation of the new operating system. Before upgrading the
471           operating system, it is prudent to comment out commands in the machine's initialization file that remount the server
472           partitions, to prevent them from being remounted until you can replace the standard <emphasis role="bold">fsck</emphasis>
473           program with the AFS-modified version. The instructions in this guide for installing AFS server machines explain how to
474           replace the <emphasis role="bold">fsck</emphasis> program. If you are unsure if your platform uses the inode fileserver, it is worth following this advice for all platforms.</para>
475         </listitem>
476
477         <listitem>
478           <para>Protect the AFS-modified versions of commands and configuration files from being overwritten by vendor-supplied
479           versions. These include <emphasis role="bold">vfsck</emphasis> (the AFS version of <emphasis role="bold">fsck</emphasis>), and configuration files such as the
480           one for the Pluggable Authentication Module (PAM). After you have successfully installed the operating system, remember to
481           move the AFS-modified commands and files back to the locations where they are accessed during normal functioning.</para>
482         </listitem>
483
484 <!-- 
485 I don't think OpenAFS has ever required the server partitions be reformatted
486         <listitem>
487           <para>Reformat the server partitions to accommodate AFS-specific information, in certain cases. The upgrade instructions
488           that accompany the new AFS binaries for an affected platform always detail the required procedure.</para>
489         </listitem>
490 -->
491       </itemizedlist></para>
492
493     <indexterm>
494       <primary>AFS Binary Distribution</primary>
495     </indexterm>
496
497     <indexterm>
498       <primary>Binary Distribution (AFS)</primary>
499     </indexterm>
500
501     <indexterm>
502       <primary>CD-ROM</primary>
503
504       <secondary>packaging of AFS Binary Distribution</secondary>
505     </indexterm>
506
507     <indexterm>
508       <primary>encryption files</primary>
509
510       <secondary>in AFS Binary Distribution</secondary>
511     </indexterm>
512   </sect1>
513
514   <sect1 id="HDRWQ15">
515     <title>The OpenAFS Binary Distribution</title>
516
517     <para>Binary Distributions for supported systems may be downloaded from the OpenAFS website. The distributions are in the native packaging format for the system in question, and should generally be installed using your system's package management tools.</para>
518
519 <para>For those distributions provided as tar files, or those built from source, the instructions in this guide specify how to copy out both binaries and configuration files</para>
520
521   </sect1>
522
523   <sect1 id="HDRWQ16">
524     <title>How to Continue</title>
525
526     <para>If you are installing the first AFS machine in your cell, proceed to <link linkend="HDRWQ17">Installing the First AFS
527     Machine</link>.</para>
528
529     <para>If you are installing an additional file server machine, or configuring or decommissioning a database server machine,
530     proceed to <link linkend="HDRWQ99">Installing Additional Server Machines</link>.</para>
531
532     <para>If you are installing an additional client machine, proceed to <link linkend="HDRWQ133">Installing Additional Client
533     Machines</link>.</para>
534   </sect1>
535 </chapter>