GettingStarted.mdwn

   1 This page provides information and tips to get started setting up OpenAFS
   2 clients and servers.  Read the [OpenAFS documentation](http://docs.openafs.org/)
   3 for detailed instructions for installing and configuring OpenAFS.
   4
   5 [[!toc levels=3]]
   6
   7 ## Planning ##
   8
   9 This section outlines some considerations when planning a new OpenAFS
  10 installation.
  11
  12 ### Server planning ###
  13
  14 An OpenAFS installation requires one or more servers for file storage. These
  15 may be physical or virtual machines, running a unix-like operating system, such
  16 as Solaris, Linux, *BSD.  Not all the servers for a site need to be running the
  17 same architecture and operating system, and it is not uncommon to have a
  18 mixture of file servers running different operating systems or versions.  Each
  19 file storage servers should have one or more unix filesystem partitions for
  20 data and AFS-metadata storage. The files stored in these partitions are stored
  21 in a special format and cannot be accessed directly.
  22
  23 The file server machines must support IPv4 and may have multiple interfaces.
  24 By default, OpenAFS will try to use all the non-loopback interfaces available
  25 on a file server machine. A configuration can be used to set which addresses
  26 are actually reachable by clients. Changing the IP address of a file server
  27 requires a restart of the file service process.
  28
  29 In addition to file servers, OpenAFS provides a specialized lookup service used
  30 internally by AFS clients and file servers, called the AFS database servers.
  31 The database server processes may be run on the same as hosts as the file
  32 servers, however the recommended configuration is to deploy the database
  33 service on a set of three dedicated machines.  These hosts may be physical or
  34 virtual machines, running a unix-like operating system.  Database servers keep
  35 in sync with each other by exchange of network messages, so network reliability
  36 between database servers is important.  Each database host must support IPv4
  37 and must have one IPv4 address.  Once deployed, it is best to avoid changing
  38 the IP address of an AFS database server.
  39
  40 The AFS database service is a relatively light-weight process, however
  41 availability of the hosts running the database service is important to the
  42 reliability of the AFS service.
  43
  44 ### Kerberos requirements ###
  45
  46 OpenAFS uses Kerberos v5 to authenticate users and processes accessing files in
  47 the AFS filesystem, and to authenticate administrators when running
  48 AFS administrative commands. This security model avoids trusting the client
  49 machines for user authentication, even if a user is becomes 'root' on a client.
  50
  51 A Kerberos v5 realm needs to be available before setting up OpenAFS.  An
  52 existing Kerberos realm can be used or a new realm will need to be setup.
  53 Kerberos 5 implementations such as Active Directory, MIT Kerberos V, or Heimdal
  54 are commonly used.  A service key will need to be created by the Kerberos
  55 administrator for the OpenAFS service.
  56
  57 OpenAFS includes a deprecated, Kerberos 4 implementation called `kaserver` for
  58 compatibility with older versions of AFS.  You may see it mentioned in various
  59 older documentatin, how-to guides, and mail list archives, however `kaserver`
  60 should not be used in new installations of OpenAFS.
  61
  62 ### Time Synchronization ###
  63
  64 Kerberos requires servers and clients to have good clock synchronization,
  65 using `ntp` or some other synchronization mechanism. Be sure ntp is installed
  66 and working on every machine to be used as an OpenAFS client or server.
  67
  68 ### DNS ###
  69
  70 You should create a DNS A record and a PTR record for each file and database
  71 server.  It is recommended to have the PTR record match the A record, and not
  72 an alias.
  73
  74 OpenAFS clients need to locate the AFS database servers. Modern clients can use
  75 DNS SRV (service) records to locate the AFS database servers.  You may also
  76 which to create DNS AFSDB records for older AFS clients, which do not have
  77 support for the newer AFS SRV records.  You will need to create SRV records
  78 for the `vlserver` and the `prserver` services.
  79
  80 The following is an example DNS bind configuration.
  81
  82     afsdb1                IN A              80.80.0.10
  83     afsdb2                IN A              80.80.0.20
  84     afsdb3                IN A              80.80.0.30
  85     @                     IN AFSDB   1      afsdb1
  86                           IN AFSDB   1      afsdb2
  87                           IN AFSDB   1      afsdb3
  88     _afs3-vlserver._udp   IN SRV 10 10 7003 afsdb1
  89     _afs3-vlserver._udp   IN SRV 10 10 7003 afsdb2
  90     _afs3-vlserver._udp   IN SRV 10 10 7003 afsdb3
  91     _afs3-prserver._udp   IN SRV 10 10 7002 afsdb1
  92     _afs3-prserver._udp   IN SRV 10 10 7002 afsdb2
  93     _afs3-prserver._udp   IN SRV 10 10 7002 afsdb3
  94
  95
  96 ### Naming considerations ###
  97
  98 OpenAFS servers are administratively grouped into a collection called a 'cell'.
  99 By convention, a cell name matches an internet domain name registered by the
 100 organization running the AFS cell. An organization may have multiple cells.
 101
 102 The naming convention for kerberos realms is to use an internet domain name,
 103 but in uppercase. The convention for AFS cell names is to match the kerberos
 104 realm name, but the cell name is lower case.  Extra configuration is required
 105 if the AFS cell name needs to be different than the kerberos realm name.
 106 Changing these names can be challenging, so careful consideration is needed
 107 when selecting the kerberos realm and AFS cell names.
 108
 109
 110