--- /dev/null
+
+This is a step-by-step guide to installing OpenAFS and setting up an AFS cell
+on RedHat Enterprise Linux, Fedora, or CentOS. This guide is current as of
+OpenAFS version 1.6.21 on CentOS 6.
+
+This document is based on [[Steven Pelley's guide for installing OpenAFS 1.4.x on Fedora|FedoraAFSInstall]].
+
+[[!toc levels=1]]
+
+## Differences from older guides
+
+### Non-DES Kerberos service key
+
+As of OpenAFS version 1.6.5, non-DES encryption keys are supported and should
+be used for the long term AFS service key. The `asetkey` program is no longer
+needed to import the Kerberos service key. The OpenAFS servers read a Kerberos
+keytab file directly. Special changes to the Kerberos configuration files to
+allow weak crypto and weak enctypes are no longer needed.
+
+The OpenAFS `kaserver` should not be used in new installations. This guide
+shows how to install MIT Kerberos.
+
+### -noauth server mode
+
+Older versions of OpenAFS required the `-noauth` flag to be used when first
+setting up the system. This entailed starting the `bosserver` in `-noauth` mode
+to disable authorization during the initial setup. Modern versions of OpenAFS
+can be installed without the `-noauth`, making the initial setup more secure
+and without the need to restart the server processes.
+
+### -dynroot client mode
+
+This guide assumes the OpenAFS cache manager is started with `-dynroot` mode
+enabled, which is the default these days. This guide shows how to create the
+initial top level AFS volumes when the cache manager is in `-dynroot` mode.
+
+### Recommended options
+
+This guide recommends using the `bosserver` restricted mode to improve security.
+
+The default options for the fileserver are rather out of date for modern
+hardware. This guide provides some examples of more suitable options for
+the fileserver.
+
+This guide shows how to setup the Demand Attach Fileserver.
+
+## Naming conventions
+
+When setting up an AFS cell on the internet, the convention is to user your
+internet domain name for your Kerberos realm and AFS cell name. The Kerberos
+realm name should be uppercase and the AFS cell name should be lowercase.
+
+Note, it is possible to create a AFS cell with a different name than the
+Kerberos realm (or even use a single Kerberos realm in multiple cells). See
+the documentation for the OpenAFS `krb.conf` server configuration file for
+details on mapping realms to cell names.
+
+## Server setup
+
+A minimal OS install is sufficient.
+
+For a simple installation, you may use a single server to host the Kerberos
+KDC, OpenAFS database server, and OpenAFS fileserver. For a production
+environment, it is recommended that the Kerberos KDC be deployed on a
+dedicated, secure server, the OpenAFS database servers be deployed on three
+separate machines, and multiple file servers deployed as needed.
+
+### Disk Partitions
+
+An important thing to keep in mind is that you'll need at least one partition
+on the file server to store volumes for AFS. This will be mounted at
+`/vicepa`. If you have multiple partitions they can be mounted at `/vicepb`,
+`/vicepc`, etc. The file server uses file-based storage (not block based).
+`ext3`, `ext4`, and `xfs` are commonly used filesystems on the vicep
+partitions.
+
+Clients should have a dedicated partition for the file cache. The cache
+partition is traditionally mounted at `/usr/vice/cache`.
+
+### Networking
+
+DNS should be working correctly for forward and reverse name lookups before you
+begin the Kerberos and OpenAFS installation. `bind` can be installed if you
+need a local DNS server. Use `system-config-bind` to add a zone and entries.
+
+Servers need at least one IPv4 interface that is accessible by the AFS clients.
+IPv6 interfaces are not yet supported.
+
+### Time keeping
+
+Kerberos, and therefore OpenAFS, requires good clock synchronization between
+clients and servers. Be sure to install and configure `ntp` and verify the
+clocks are automatically kept in sync.
+
+ # yum install -y ntp
+ # service ntpd start
+ # chkconfig ntpd on
+
+### Firewall
+
+The default firewall settings on RHEL will block the network ports used by
+Kerberos and OpenAFS. You will need to adjust the firewall rules on the
+servers to allow traffic on these ports.
+
+On the Kerberos server, open udp ports 88 and 646:
+
+ # iptables -A INPUT -p udp --dport 88 -j ACCEPT
+ # iptables -A INPUT -p udp --dport 646 -j ACCEPT
+ # service iptables save
+
+On the OpenAFS database servers, open the udp ports 7002, 7003, and 7007:
+
+ # iptables -A INPUT -p udp --dport 7002 -j ACCEPT
+ # iptables -A INPUT -p udp --dport 7003 -j ACCEPT
+ # iptables -A INPUT -p udp --dport 7007 -j ACCEPT
+ # service iptables save
+
+On the OpenAFS file servers, open the udp ports 7000, 7005, and 7007:
+
+ # iptables -A INPUT -p udp --dport 7000 -j ACCEPT
+ # iptables -A INPUT -p udp --dport 7005 -j ACCEPT
+ # iptables -A INPUT -p udp --dport 7007 -j ACCEPT
+ # service iptables save
+
+OpenAFS clients use udp port 7001. Open udp port 7001 on any system that will
+have the OpenAFS client installed.
+
+ # iptables -A INPUT -p udp --dport 7001 -j ACCEPT
+ # service iptables save
+
+### SELinux
+
+Ideally, SELinux should be kept in enforcing mode. SELinux may be set to
+enforcing for the OpenAFS client, but unfortunately, for the servers, there are
+still several [issues][1] remaining before the servers can run out the box with
+SELinux in enforcing mode.
+
+For test installations, SELinux can be set into permissive mode, which will
+print warnings instead of blocking:
+
+ # setenforce 0
+ # sed -i -e 's/SELINUX=enforcing/SELINUX=permissive/' /etc/selinux/config
+
+See [this report][1] for workarounds if you need to run in enforcing mode.
+
+[1]: https://bugzilla.redhat.com/show_bug.cgi?id=1136396
+
+## Installing Kerberos
+
+Install the Kerberos server and client packages with the command:
+
+ # yum install -y krb5-server krb5-workstation krb5-libs
+
+Replace every instance of `EXAMPLE.COM` with your realm name in the following
+configuration files:
+
+ * `/etc/krb5.conf`
+ * `/var/kerberos/krb5kdc/kdc.conf`
+ * `/var/kerberos/krb5kdc/kadm5.acl`
+
+Replace every instance of the example hostname `kerberos.example.com` with
+the actual hostname of your Kerberos server in the file `/etc/krb5.conf`.
+
+Create the Kerberos database using the `krb5_util` command. You will be
+prompted for a master principal password. Choose a password, keep it secret,
+and keep it safe.
+
+ # /usr/sbin/kdb5_util create -s
+
+Start the Kerberos servers.
+
+ # service krb5kdc start
+ # service kadmin start
+ # chkconfig krb5kdc on
+ # chkconfig kadmin on
+
+## Installing OpenAFS servers
+
+### Installing servers
+
+OpenAFS RPM packages for RHEL 6 are available on the [[OpenAFS]] website. The
+packages may be installed using `yum`. First, install the repository
+definition with
+
+ # version=<version>
+ # rpm -i http://openafs.org/dl/openafs/${version}/openafs-release-rhel-${version}-1.noarch.rpm
+
+where `<version>` is the OpenAFS version you wish to install, e.g. "1.6.21".
+
+Use `yum` to install the OpenAFS server packages:
+
+ # yum install -y openafs openafs-server openafs-docs openafs-krb5
+
+Create the Kerberos AFS service key and export it to a keytab file:
+
+ # cellname=<cellname>
+ # kadmin.local -q "addprinc -randkey afs/${cellname}"
+ # kadmin.local -q "ktadd -k /usr/afs/etc/rxkad.keytab afs/${cellname}"
+
+where `<cellname>` is the name of your cell. Start the OpenAFS servers:
+
+ # service openafs-server start
+
+Check the server log `/usr/afs/logs/BosLog` to verify the OpenAFS `bosserver`
+process started. Set the cell name with the command:
+
+ # bos setcellname localhost ${cellname} -localauth
+
+### Starting the database services
+
+The `ptserver` process stores the AFS users and group names in your cell. The
+`vlserver` process stores the file server locations of the AFS volumes in your
+cell. Start the OpenAFS database processes with the commands:
+
+ # bos create localhost ptserver simple -cmd /usr/afs/bin/ptserver -localauth
+ # bos create localhost vlserver simple -cmd /usr/afs/bin/vlserver -localauth
+
+Check the log files `BosLog`, `PTLog`, `VLLog` in the `/usr/afs/logs`
+directory to verify the `ptserver` and `vlserver` started.
+
+### Starting the file server
+
+Start the file server. This is a rather long command line.
+
+ # bos create localhost \
+ dafs dafs -cmd \
+ "/usr/afs/bin/dafileserver -p 123 -L -busyat 200 -rxpck 2000 -cb 4000000 -vattachpar 128 -vlruthresh 1440 -vlrumax 8 -vhashsize 11" \
+ "/usr/afs/bin/davolserver -p 64 -log" \
+ "/usr/afs/bin/salvageserver" \
+ "/usr/afs/bin/dasalvager -parallel all32" \
+ -localauth
+
+Check the servers logs `BosLog`, `FileLog`, `VolserLog`, and `SalsrvLog`, in
+`/usr/afs/logs' to verify the file server started. At this point the OpenAFS
+server processes should be running.
+
+### Creating the admin account
+
+Create a user account for Kerberos and AFS administration.
+
+ # myname=<username>
+ # kadmin.local -q "addprinc ${myname}/admin"
+ Enter password: <password>
+ Re-enter password: <password>
+ # pts createuser ${myname}.admin -localauth
+ # pts adduser ${myname}.admin system:administrators -localauth
+ # bos adduser localhost ${myname}.admin -localauth
+
+where `<myname>` is your user name and `<password>` is your chosen password.
+
+The admin principal can be any name you want. The recommended practice is to
+create two principals for admins: one for your normal user, and an additional
+admin account. For example, I may have `steve` and `steve/admin`. Note that for
+Kerberos 5, the name is `steve/admin@REALM`, whereas in AFS, the name is
+`steve.admin`. Use `steve.admin` for all AFS commands. Since this is to be an
+administrator we will also register it as such with the `bos` server. We can give
+it administrator rights by adding it to the group `system:administrators`. This
+is an AFS default group. The `pts membership` command will list all the groups
+that your user is a member of. Verify that it lists `system:administrators`.
+
+### Create the root volumes
+
+At this point we need our `/vicepa` partition. You should have done this when
+installing the operating system. If you have not, do it now, then restart the
+fileserver with `service openafs-server restart`. (If this is only a test
+system you may create a pseudo partition without needing to create an actual
+separate filesystem. To do this, create an empty directory called `/vicepa` and
+then create an empty file called `/vicepa/AlwaysAttach`, then restart the file
+server with `service openafs-server restart`.)
+
+Create the root volumes with the commands:
+
+ # vos create localhost a root.afs -localauth
+ # vos create localhost a root.cell -localauth
+
+Check the volume location database to verify the two volumes are listed.
+
+ # vos listvldb
+
+Finally, now that the server configuration is done, put the `bosserver` into
+the more secure restricted mode, which disables several bos commands which are
+strictly not needed for normal operation.
+
+ # bos setrestricted localhost -mode 1 -localauth
+
+This completes the server side setup. At this point will need to install the
+OpenAFS cache manager (client), setup the top level directories, and then start
+adding files to your new cell. The cache manager may be installed on a
+separate machine (for example, your laptop.) Also, you will no longer be using
+the `root` user to run OpenAFS commands, but instead from this point forward
+you should use your Kerberos credentials.
+
+## Installing OpenAFS Client
+
+### Kernel Module
+
+If installing the cache manager on an OpenAFS server, first remove the symlinks
+created by `bosserver`. These will be in the way if the client is installed.
+
+ # test -h /usr/vice/etc/ThisCell && rm /usr/vice/etc/ThisCell
+ # test -h /usr/vice/etc/CellServDB && rm /usr/vice/etc/CellServDB
+
+Install the OpenAFS client with yum:
+
+ # yum install -y openafs openafs-client openafs-krb5 kmod-openafs
+
+You may need to reboot you system if the kernel version was updated.
+
+The OpenAFS kernel module must match your kernel version. If a pre-built
+module is not available for the kernel version you are running, the yum install
+of kmod-openafs will fail. If this happens, then you may use
+[DKMS to build and install|RpmClientInstallationWithDKMS]] a kernel module
+that matches your kernel version.
+
+ # yum install -y dkms gcc
+ # yum install -y openafs openafs-client openafs-krb5 dkms-openafs
+
+Alternately, you can build the kernel module from the source rpm. You will
+need to download the OpenAFS SRPM file from OpenAFS.org, install the
+`kernel-devel` package that matches your kernel version, and the necessary
+build tools. Use the `rpmbuild` command to build the kernel module.
+
+ # rpmbuild --rebuild -bb \
+ --define 'build_userspace 0' \
+ --define 'build_modules 1' \
+ openafs-<version>-1.src.rpm
+
+### Client side configuration
+
+`/usr/afs/etc` is the location for the server files. We also need to configure
+the client. The client files are located in `/usr/vice/etc`. RPM based OpenAFS
+packages are set up in such a way that there are two `CellServDB` client
+files in `/usr/vice/etc`: `CellServDB.dist` and `CellServDB.local`. We will
+copy ours to the local list.
+
+ # cp /usr/afs/etc/CellServDB /usr/vice/etc/CellServDB.local
+ # cp /usr/afs/etc/ThisCell /usr/vice/etc/ThisCell
+
+The RPM based `openafs-client` init script will combine the `CellServDB.dist`
+and `CellServDB.local` files into the `CellServDB` file, which the cache
+manager reads on startup.
+
+### Start the cache manager
+
+Start the cache manager with the command:
+
+ # service openafs-client start
+
+Run the `mount` command to verify the AFS filesystem is mounted at `/afs`.
+
+Try logging in to AFS. `kinit` logs you into Kerberos (this is the normal
+Kerberos utility). `aklog` gets you an AFS token. The `tokens` command lists
+the tokens you have. You should see `afs@<cellname>`. If you run into problems, you
+can use `klist` to list your Kerberos tickets, or `aklog` with the `-d` flag.
+
+ $ kinit <username>/admin
+ <password>
+ $ aklog
+ $ tokens
+
+## Setting up the cell root directory
+
+Now we will set up the root directories. The root directory for the AFS
+namespace is in the volume called `root.afs`. The root directory of your cell
+should be in a volume called `root.cell`. You will need to set the ACLs for
+these directories. AFS access rights are rather different from those in UNIX.
+I suggest reading the IBM documentation for this; it still applies.
+
+The cache manager is started in `-dynroot` mode on RPM-based installations.
+This allows the cache manager to mount the AFS filesystem without the need to
+contact the OpenAFS servers. The side-effect of `-dynroot` is the `root.afs`
+volume cannot be accessed directly. Fortunately, we can use "magic" `.:mount`
+directory to access the `root.afs` volume.
+
+Set up the top level directories.
+
+ $ cellname=$(cat /usr/vice/etc/ThisCell)
+
+ $ cd /afs/.:mount/${cellname}:root.afs/
+ $ fs mkmount ${cellname} root.cell -cell ${cellname}
+ $ fs mkmount .${cellname} root.cell -cell ${cellname} -rw
+ $ fs setacl . system:anyuser read
+
+ $ cd /afs/.:mount/${cellname}:root.cell/
+ $ fs setacl . system:anyuser read
+
+Replicate the root volumes so that you have read only copies. Later, if more
+file servers are added to the cell, additional read-only copies should be made.
+
+ $ server=<hostname of the fileserver>
+ $ vos addsite ${server} a root.afs
+ $ vos release root.afs
+ $ vos addsite ${server} a root.cell
+ $ vos release root.cell
+
+## Adding users and volumes
+
+Now that OpenAFS is installed, the site specific AFS volumes and directory
+structure can be set up. Users should be made, along with their home
+volumes. ACLs for the volume directories should be established.
+
+This section provides an example setup. The names of the volumes and
+directories can be specific to your needs.
+
+You must first authenticate as a Kerberos/AFS admin to run the commands
+shown in this section.
+
+ $ kadmin <username>/admin
+ $ aklog
+
+### Creating user accounts
+
+We can create a user by registering it to Kerberos and the `ptserver` database.
+If you use integrated login, make sure that the users' UNIX uids and pts ids
+match.
+
+ $ kadmin -q "addprinc <username>"
+ <enter password for username>
+ $ pts createuser <username> -id <numeric uid>
+
+If you use integrated login, make sure that you add an entry to /etc/passwd or
+whatever means you use of distributing user information.
+
+### Setting up volumes for users
+
+First, we can make a top level volume to contain the mount points to volumes
+for individuals. The IBM documentation suggests making a directory
+`/afs/<cellname>/user` with volume name user for all of your AFS users. Some
+sites have adopted the directory `home` instead of `user`. If you use `home`,
+your users may feel more comfortable, as this is the convention in Linux and
+most UNIXes.
+
+The following commands create the `home` volume and make a read-only replica:
+
+ $ vos create <fileserver> a home
+ $ cd /afs/.<cellname>
+ $ fs mkmount home home
+ $ vos addsite <fileserver> a home
+ $ vos release root.cell
+ $ vos release home
+
+Now you can create directories for any of your users. We will not replicate
+these volumes. By not replicating them, we force the cache manager to access a
+read/write volume. This means that even if we access the cell through the
+read-only volume we can still access our read/write user directories (this is
+what you want). Maxquota 0 means that there is no size restriction to the
+volume. You can give it a restriction if you like (the default is 5mb). Do
+these commands for every directory you like.
+
+ $ vos create <fileserver> a home.<uid> -maxquota 0
+ $ cd /afs/.<cellname>/home
+ $ fs mkmount <user> home.<uid>
+ $ vos release home
+
+The home volume is released to make the new directories are visible from the
+read only mount point.
+
+### Setting ACLs
+
+Now that we have volumes, we should set some restrictions on those volumes.
+If you trust the users not to make directories *world writable*, you
+can give the user of the directory full rights.
+
+ $ cd /afs/.<cellname>/home
+ $ fs setacl -dir <user> -acl <user> all
+
+To give the users read and write access, but not rights to change ACLs,
+
+ $ cd /afs/.<cellname>/home
+ $ fs setacl -dir <user> -acl <user> write
+
git://git.openafs.org / openafs-wiki.git / blobdiff