(no commit message)
[openafs-wiki.git] / GettingStarted.mdwn
index 9dcc47d..83cc206 100644 (file)
@@ -1,8 +1,110 @@
+This page provides information and tips to get started setting up OpenAFS
+clients and servers.  Read the [OpenAFS documentation](http://docs.openafs.org/)
+for detailed instructions for installing and configuring OpenAFS.
+
 [[!toc levels=3]]
 
-(This page will describe how to get started setting up OpenAFS servers and clients.)
+## Planning ##
+
+This section outlines some considerations when planning a new OpenAFS
+installation.
+
+### Server planning ###
+
+An OpenAFS installation requires one or more servers for file storage. These
+may be physical or virtual machines, running a unix-like operating system, such
+as Solaris, Linux, BSD.  Not all the servers for a site need to be running the
+same architecture and operating system, and it is not uncommon to have a
+mixture of file servers running different operating systems or versions.  Each
+file storage servers should have one or more unix filesystem partitions for
+data and AFS-metadata storage. The files stored in these partitions are stored
+in a special format and cannot be accessed directly.
+
+The file server machines must support IPv4 and may have multiple interfaces.
+By default, OpenAFS will try to use all the non-loopback interfaces available
+on a file server machine. A configuration can be used to set which addresses
+are actually reachable by clients. Changing the IP address of a file server
+requires a restart of the file service process.
+
+In addition to file servers, OpenAFS provides a specialized lookup service used
+internally by AFS clients and file servers, called the AFS database servers.
+The database server processes may be run on the same as hosts as the file
+servers, however the recommended configuration is to deploy the database
+service on a set of three dedicated machines.  These hosts may be physical or
+virtual machines, running a unix-like operating system.  Database servers keep
+in sync with each other by exchange of network messages, so network reliability
+between database servers is important.  Each database host must support IPv4
+and must have one IPv4 address.  Once deployed, it is best to avoid changing
+the IP address of an AFS database server.
+
+The AFS database service is a relatively light-weight process, however
+availability of the hosts running the database service is important to the
+reliability of the AFS service.
+
+### Kerberos requirements ###
+
+OpenAFS uses Kerberos v5 to authenticate users and processes accessing files in
+the AFS filesystem, and to authenticate administrators when running
+AFS administrative commands. This security model avoids trusting the client
+machines for user authentication, even if a user is becomes 'root' on a client.
+
+A Kerberos v5 realm needs to be available before setting up OpenAFS.  An
+existing Kerberos realm can be used or a new realm will need to be setup.
+Kerberos 5 implementations such as Active Directory, MIT Kerberos V, or Heimdal
+are commonly used.  A service key will need to be created by the Kerberos
+administrator for the OpenAFS service.
+
+OpenAFS includes a deprecated, Kerberos 4 implementation called `kaserver` for
+compatibility with older versions of AFS.  You may see it mentioned in various
+older documentatin, how-to guides, and mail list archives, however `kaserver`
+should not be used in new installations of OpenAFS.
+
+### Time Synchronization ###
+
+Kerberos requires servers and clients to have good clock synchronization,
+using `ntp` or some other synchronization mechanism. Be sure ntp is installed
+and working on every machine to be used as an OpenAFS client or server.
+
+### DNS ###
+
+You should create a DNS A record and a PTR record for each file and database
+server.  It is recommended to have the PTR record match the A record, and not
+an alias.
+
+OpenAFS clients need to locate the AFS database servers. Modern clients can use
+DNS SRV (service) records to locate the AFS database servers.  You may also
+which to create DNS AFSDB records for older AFS clients, which do not have
+support for the newer AFS SRV records.  You will need to create SRV records
+for the `vlserver` and the `prserver` services.
+
+The following is an example DNS bind configuration.
+
+    afsdb1                IN A              80.80.0.10
+    afsdb2                IN A              80.80.0.20
+    afsdb3                IN A              80.80.0.30
+    @                     IN AFSDB   1      afsdb1
+                          IN AFSDB   1      afsdb2
+                          IN AFSDB   1      afsdb3
+    _afs3-vlserver._udp   IN SRV 10 10 7003 afsdb1
+    _afs3-vlserver._udp   IN SRV 10 10 7003 afsdb2
+    _afs3-vlserver._udp   IN SRV 10 10 7003 afsdb3
+    _afs3-prserver._udp   IN SRV 10 10 7002 afsdb1
+    _afs3-prserver._udp   IN SRV 10 10 7002 afsdb2
+    _afs3-prserver._udp   IN SRV 10 10 7002 afsdb3
+
+
+### Naming considerations ###
+
+OpenAFS servers are administratively grouped into a collection called a 'cell'.
+By convention, a cell name matches an internet domain name registered by the
+organization running the AFS cell. An organization may have multiple cells.
+
+The naming convention for kerberos realms is to use an internet domain name,
+but in uppercase. The convention for AFS cell names is to match the kerberos
+realm name, but the cell name is lower case.  Extra configuration is required
+if the AFS cell name needs to be different than the kerberos realm name.
+Changing these names can be challenging, so careful consideration is needed
+when selecting the kerberos realm and AFS cell names.
 
 
-# See also #
 
-* [[Creating a new AFS cell|CreatingANewCell]]