# Installation Overview

This chapter describes the type of instructions provided in this guide and the hardware and software requirements for installing AFS.

Before beginning the installation of your cell's first machine, read this chapter and the material from the OpenAFS Administration Guide listed in Recommended Reading List. It is also best to read the entirety of certain sections of this document, in particular Installing the First AFS Machine, before beginning the installation, so that you understand the overall scope of the installation procedure. Similarly, before installing additional server or client machines it is best to read through Installing Additional Server Machines and Installing Additional Client Machines.

If you are already running a version of AFS, consult the upgrade instructions in the OpenAFS Release Notes before proceeding with the installation.

If you are working with an existing cell that uses kaserver or external Kerberos v4 for authentication, please see the notes in kaserver and legacy Kerberos 5 authentication and the rest of Appendix B for how the installation steps will differ from those described in the rest of this guide. Do not use the kaserver for new deployments of AFS; it uses extremely insecure cryptography.

## The Procedures Described in this Guide

This guide describes two types of installation procedures: initial procedures (such as installing the first AFS machine or incorporating AFS into the kernel) and as-needed procedures (such as installing additional server machines or client machines).

### Required Initial Procedures

You must perform the following basic procedures to start using AFS.

#### Incorporating AFS Into the Kernel

You must incorporate AFS modifications into the kernel of every client machine. Depending on the operating system, you either use a program for dynamic kernel loading, build a new static kernel, or can choose between the two. For your convenience, the instructions for incorporating AFS into the kernel appear in full in every chapter where you need to use them.

#### Installing the First AFS Machine

You install the first AFS machine in your cell to function as both an AFS server and client machine. You can disable the client functionality after completing the installation, if you wish.

The first server machine in a cell performs several functions:

- It acts as the first database server machine, running the server processes that maintain the AFS administrative databases

- It may act as the system control machine, distributing certain configuration files to the other server machines in the cell

- It may act as the binary distribution machine for its system type, distributing AFS binaries to other server machines of its system type

The latter two functions are performed by the Update Server, which is considered to be deprecated and may be removed in a future release.

After you install server and client functionality, you complete other procedures specific to the first machine, including setting up the top levels of your cell's AFS filespace.

### As-needed Procedures

#### Upgrading the Operating System

Upgrading the operating system requires you to take several steps to protect data and AFS-modified binaries from being lost or overwritten. For guidelines, see About Upgrading the Operating System.

#### Installing Additional File Server Machines

See Installing an Additional File Server Machine.

#### Configuring or Decommissioning Database Server Machines

See Installing Database Server Functionality and Removing Database Server Functionality.

#### Installing Additional AFS Client Machines

See Installing Additional Client Machines.

#### Building AFS from Source Code

See Appendix A, Building AFS from Source Code

#### Configuring Legacy Components

See Appendix B, Configuring Legacy Components

## Recommended Reading List

To develop the best understanding of the overall scope of an installation procedure, read through the entire chapter or section that describes it before performing any actions.

In addition, familiarity with some basic AFS concepts can make the installation more efficient, because you understand better the purpose of the steps. The following is a prioritized list of material to read before installing the first AFS machine. At minimum, read the first chapter of the OpenAFS Administration Guide. Then continue your reading in the indicated order, as extensively as you can. It is more important at this point to read the conceptual material in each section than the instructions.

Selected Topics in the OpenAFS Administration Guide

- The chapter titled An Overview of AFS Administration

- Selected sections in the Administering Server Machines chapter: Local Disk Files on a Server Machine, The Four Roles for a Server Machine, Maintaining the Server CellServDB File

- Selected sections in the Monitoring and Controlling Server Processes chapter: Controlling and Checking Process Status

- Selected sections in the Managing Server Encryption Keys chapter: About Server Encryption Keys

- Selected sections in the Managing Volumes chapter: About Volumes, Creating Read/write Volumes, Clones and Cloning, Mounting Volumes

- Selected sections in the Administering Client Machines and the Cache Manager chapter: Overview of Cache Manager Customization, Configuration and Cache-related Files on the Local Disk, Determining the Cache Type, Size, and Location

- Selected sections in the Managing Access Control Lists chapter: Protecting Data in AFS

More Selected Topics in the OpenAFS Administration Guide

- Selected sections in the Managing Volumes chapter: Creating and Releasing Read-only Volumes (Replication), Creating Backup Volumes

- Selected sections in the Administering the Protection Database chapter: About the Protection Database

- Selected sections in the Administering User Accounts chapter: The Components of an AFS User Account

- Selected sections in the Managing Administrative Privilege chapter: An Overview of Administrative Privilege

## Requirements

You must comply with the following requirements to install AFS successfully.

### Login Identity

Log into the machine you are installing as the local superuser root. When instructed, also authenticate to AFS using Kerberos as the administrative user admin.

### General Requirements

- You must have a Kerberos 5 realm running for your site, and the ability to create new principals within that realm. If you are working with an existing cell using the deprecated kaserver or Kerberos v4 authentication, please see kaserver and legacy Kerberos 4 authentication for modifications to the following instructions.

- You must have a NTP, or similar, timeservice running. Each AFS machine should derive its system time from this timeservice. If you are working with an existing cell, and wish to use AFS's internal time service, please see Appendix B for modifications to the following instructions.

- You must have an OpenAFS Binary Distribution for each system type you are installing, or have built a binary from the supplied source code. Unless otherwise noted, the Binary Distribution includes software for both client and server machines.

- All AFS machines that belong to a cell must be able to access each other via the network.

- The machine must be running the standard, vendor-supplied version of the operating system supported by the current version of AFS. The operating system must already be installed on the machine's root partition.

- You must be familiar with the current operating system and disk configuration of the machine you are installing.

- All hardware and non-AFS software on the machine must be functioning normally.

- No critical processes can be running on the machine you are installing, because you may need to reboot it during the installation.

### File Server Machine Requirements

- Cell configuration is simplest if the first machine you install has the lowest IP address of any database server machine you currently plan to install. If you later configure a machine with a lower IP address as a database server machine, you must update the /usr/vice/etc/CellServDB file on all of your cell's client machines before the installation. For further discussion, see Installing Database Server Functionality.

- The partition mounted on the /usr directory must have a sufficient amount of space to hold the AFS binaries that will be used; a few hundred MB should be more than sufficient.

  More significant amounts of space on the partition are required by the administrative databases stored in the /usr/afs/db directory and the server process log files stored in the /usr/afs/logs directory. The exact requirement depends on many factors, such as the size of your cell and how often you truncate the log files.

- There should be at least one partition (or logical volume, if the operating system and AFS support them) dedicated exclusively to storing AFS volumes. Special configuration is required to use non-dedicated partitions as the backing store for AFS file data. The total number and size of server partitions on all file server machines in the cell determines how much space is available for AFS files.

### Client Machine Requirements

- The partition mounted on the /usr directory must have a sufficient amount of disk space to store the AFS binaries that will be used; a few hundred MB should be more than sufficient.

- On a client machine that uses a disk cache, there must be enough free space on the cache partition (by convention, mounted on the /usr/vice/cache directory) to accommodate the cache. The minimum recommended cache size is 50 MB, but larger caches generally perform better. It is recommended to have a dedicated partition for this cache, as the client does not degrade gracefully when the partition containing the cache is filled by other processes.

- On a client machine that uses a memory cache, there must be at least 50 MB of machine memory to devote to caching, but again more memory generally leads to better performance. For further discussion, see the sections in Installing Additional Client Machines about configuring the cache.

## Supported System Types

The OpenAFS Release Notes for each AFS release list the supported system types. Support for subsequent revisions of an operating system often becomes available between AFS releases. The OpenAFS mailing lists can provide information regarding this interim support

It is the goal of OpenAFS to support AFS on a wide range of popular system types. Furthermore, each time an operating system vendor releases a new general availability version of a supported operating system, 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 generate completely new binaries.

It is not always possible to support AFS on every intermediate version of an operating system or for certain processor types. In some cases, platform limitations make certain AFS functionality (such as file server or NFS/AFS translator functionality) unavailable on one or more platforms. For a list of limitations, see the OpenAFS Release Notes or ask on the OpenAFS mailing lists.

## About Upgrading the Operating System

On most modern systems, using Kerberos 5 for authentication and the namei fileserver backend, no particular precautions need to be taken across operating system upgrades. Legacy confiruations involving kaserver authentication or inode fileserver backends will need to undertake the following precautions.

These actions include, but are not necessarily limited to, the following.

- On platforms running the inode fileserver, unmount the AFS server partitions (mounted at /vicep xx directories) on all file server machines, to prevent the vendor-supplied fsck program from running on them when you reboot the machine during installation of the new operating system. Before upgrading the operating system, it is prudent to comment out commands in the machine's initialization file that remount the server partitions, to prevent them from being remounted until you can replace the standard fsck program with the AFS-modified version. The instructions in this guide for installing AFS server machines explain how to replace the fsck program. If you are unsure if your platform uses the inode fileserver, it is worth following this advice for all platforms.

- Protect the AFS-modified versions of commands and configuration files from being overwritten by vendor-supplied versions. These include vfsck (the AFS version of fsck), and configuration files such as the one for the Pluggable Authentication Module (PAM). After you have successfully installed the operating system, remember to move the AFS-modified commands and files back to the locations where they are accessed during normal functioning.

## The OpenAFS Binary Distribution

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.

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

## How to Continue

If you are installing the first AFS machine in your cell, proceed to Installing the First AFS Machine.

If you are installing an additional file server machine, or configuring or decommissioning a database server machine, proceed to Installing Additional Server Machines.

If you are installing an additional client machine, proceed to Installing Additional Client Machines.