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