1 <?xml version="1.0" encoding="UTF-8"?>
3 <title>Installation Overview</title>
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>
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>
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>
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>
33 <title>The Procedures Described in this Guide</title>
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>
41 <title>Required Initial Procedures</title>
43 <para>You must perform the following basic procedures to start using
46 <sect3 id="Header_10">
47 <title>Incorporating AFS Into the Kernel</title>
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.
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
59 <primary>roles for first AFS machine</primary>
62 <primary>first AFS machine</primary>
63 <secondary>roles</secondary>
68 <sect3 id="Header_11">
69 <title>Installing the First AFS Machine</title>
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
76 <para>The first server machine in a cell performs several
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
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>
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>
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>
106 <sect2 id="Header_12">
107 <title>As-needed Procedures</title>
109 <sect3 id="Header_13">
110 <title>Upgrading the Operating System</title>
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>
118 <sect3 id="Header_14">
119 <title>Installing Additional File Server Machines</title>
121 <para>See <link linkend="HDRWQ100">Installing an Additional File
122 Server Machine</link>.</para>
125 <sect3 id="Header_15">
126 <title>Configuring or Decommissioning Database Server Machines</title>
128 <para>See <link linkend="HDRWQ114">Installing Database Server
129 Functionality</link> and <link linkend="HDRWQ125">Removing
130 Database Server Functionality</link>.</para>
133 <sect3 id="Header_16">
134 <title>Installing Additional AFS Client Machines</title>
136 <para>See <link linkend="HDRWQ133">Installing Additional Client
137 Machines</link>.</para>
140 <sect3 id="Header_17">
141 <title>Building AFS from Source Code</title>
143 <para>See <link linkend="HDRWQ163">Appendix A, Building AFS from
144 Source Code</link></para>
147 <sect3 id="Header_17a">
148 <title>Configuring Legacy Components</title>
149 <para>See <link linkend="Legacy">Appendix B, Configuring Legacy
152 <primary>background reading list</primary>
155 <primary>reading list for background information</primary>
163 <title>Recommended Reading List</title>
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>
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>
178 <para><emphasis role="bold">Selected Topics in the <emphasis>OpenAFS
179 Administration Guide</emphasis></emphasis>
182 <para>The chapter titled <emphasis>An Overview of AFS
183 Administration</emphasis></para>
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>
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>
202 <para>Selected sections in the <emphasis>Managing Server
203 Encryption Keys</emphasis> chapter: <emphasis>About Server
204 Encryption Keys</emphasis></para>
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>
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>
225 <para>Selected sections in the <emphasis>Managing Access Control
226 Lists</emphasis> chapter: <emphasis>Protecting Data in
227 AFS</emphasis></para>
229 </itemizedlist></para>
231 <para><emphasis role="bold">More Selected Topics in the
232 <emphasis>OpenAFS Administration Guide</emphasis></emphasis>
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>
242 <para>Selected sections in the <emphasis>Administering the
243 Protection Database</emphasis> chapter: <emphasis>About the
244 Protection Database</emphasis></para>
248 <para>Selected sections in the <emphasis>Administering User
249 Accounts</emphasis> chapter: <emphasis>The Components of an AFS
250 User Account</emphasis></para>
254 <para>Selected sections in the <emphasis>Managing Administrative
255 Privilege</emphasis> chapter: <emphasis>An Overview of
256 Administrative Privilege</emphasis></para>
263 <title>Requirements</title>
265 <para>You must comply with the following requirements to install AFS successfully. <indexterm>
266 <primary>root superuser</primary>
268 <secondary>as installer's login identity</secondary>
271 <sect2 id="Header_20">
272 <title>Login Identity</title>
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>
278 <secondary>general installation requirements</secondary>
279 </indexterm> <indexterm>
280 <primary>requirements</primary>
282 <secondary>general</secondary>
287 <title>General Requirements</title>
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>
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
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>
315 <para>All AFS machines that belong to a cell must be able to access each other via the network.</para>
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>
324 <para>You must be familiar with the current operating system and disk configuration of the machine you are
329 <para>All hardware and non-AFS software on the machine must be functioning normally.</para>
333 <para>No critical processes can be running on the machine you are installing, because you may need to reboot it during the
339 <primary>file server machine</primary>
341 <secondary>requirements for installation</secondary>
345 <primary>requirements</primary>
347 <secondary>file server machine (general)</secondary>
352 <title>File Server Machine Requirements</title>
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>
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>
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>
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>
385 <primary>client machine</primary>
387 <secondary>requirements for installation</secondary>
391 <primary>requirements</primary>
393 <secondary>client machine</secondary>
398 <title>Client Machine Requirements</title>
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>
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>
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>
424 <primary>system types supported</primary>
428 <primary>supported system types</primary>
434 <title>Supported System Types</title>
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>
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>
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>
454 <secondary>protecting during operating system upgrade</secondary>
455 </indexterm> <indexterm>
456 <primary>files</primary>
458 <secondary>protecting during operating system upgrade</secondary>
463 <title>About Upgrading the Operating System</title>
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>
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>
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>
485 I don't think OpenAFS has ever required the server partitions be reformatted
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>
491 </itemizedlist></para>
494 <primary>AFS Binary Distribution</primary>
498 <primary>Binary Distribution (AFS)</primary>
502 <primary>CD-ROM</primary>
504 <secondary>packaging of AFS Binary Distribution</secondary>
508 <primary>encryption files</primary>
510 <secondary>in AFS Binary Distribution</secondary>
515 <title>The OpenAFS Binary Distribution</title>
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>
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>
524 <title>How to Continue</title>
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>
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>
532 <para>If you are installing an additional client machine, proceed to <link linkend="HDRWQ133">Installing Additional Client
533 Machines</link>.</para>