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