OpenAFS-mini-guide for newbies (mostly for Debian) -------------------------------------------------- Revision: 2 Date: 2003-03-10 Author: peter.schuller@infidyne.com Changelog: Rev 1-2: Corrected vlserver setup instructions. While this deals with Debian specifics, it may be useful on other platforms aswell. Hopefully it can be improved and made more informative by adding instructions for other platforms, or generalizing those already there. First of all, this guide assumes you don't have any old OpenAFS/Kerberos config files lying around. If you do, and you don't need them, I suggesting purging (not just removing) all installed openafs/kerberos packages prior to following the instructions in this guide. Much of this guide was inspired by the following article: http://www.debianplanet.org/node.php?id=816 Most information here is covered, but with less verbosity, in that article. I am still fuzzy on some of the things documented here. You'll notice comments to the effect that I don't know what something is for exactly. I hope to improve upon that in the future. I realize that plain text is not the best format for this. I will convert it to something else - sometime. $ apt-get install krb5-admin-server krb5-doc krb5-kdc Default realm: YOURDOMAIN.TLD (suggested, not required) Krb4 compat: nopreauth Note the comment about DNS; supposedly forward/reverse must be working and be consistent. Servers: hostname of your server (`hostname`) $ krb5_newrealm KDC database master key: $ kadmin.local Make sure it does not output any error message. Then quit. Kerberos should now be up and running. If you wish to read about how kadmin.local works in more detail, refer to the man page for "kadmin". kadmin.local is just a local version of that. We now need to create an 'afs' principle in Kerberos. I am not yet sure when exactly it is used, but I assume it's required for the integration to work. $ kadmin.local -q "addprinc -randkey afs" -q is just a short form to execute commands, suitable for scripts. $ kadmin.local -q "ktadd -e des-cbc-crc:afs3 afs" Note the "kvno " in the output. You'll need later on. Install OpenAFS packages (could have been done prior to this; doesn't matter). $ apt-get install openafs-krb5 openafs-fileserver openafs-dbserver Choose an AFS cell name and accept the defaults for the rest unless you explicitly wish to do something else. Note that the Debian packages depend on the client package; thus removing arla if you have that installed. A client is needed to bootstrap a few things later on. I assume this can be done using the arla clients and/or a remote client; but the packages depend on it. So to keep things simple, let's do it the way it was intended. When the openafs-fileserver package attempts to start bossserver, it may hang. If that happens, do a "pkill bos" in parallel to enable the installation scrpt and thus apt-get/dpkg to continue. (Poor advice, I know. But I never investigated why it hung.) $ asetkey add /etc/krb5.keytab afs is the number from the kadmin.local command above. /etc/krb5.keytab should be the default location of the file. It can also be specified with the "-k" switch to the ktadd kadmin command invoked above. Now it's time to start the bosserver. Because authentication has not yet been configured, we need the -noauth switch. In this mode, it will honor any requests coming in (i.e., it's extremely insecure if left in this state). $ bosserver -noauth & $ bos listhosts -noauth "servername" is the hostname you chose to use for the server you are installing it on (the name you've given to the various package install questions previously). It's not the cell name, but the name of the server (in case they are not the same). Now, this command is supposed to list one host according to all guides I've read, but I have never seen that happening the first time I run it. After everything else is set up, it starts listing the host properly. It should complete without error though, stating just the cell name. This is a command meant as a sanity check; it doesn't change anything. Now lets tell bos how to launch ptserver, which handles authentication/authorization, or is involved somehow. I am not sure exactly what role it plays, other than handling users and groups (I believe?). $ bos create -server -instance ptserver -type simple -cmd /usr/lib/openafs/ptserver -cell -noauth Create an admin user (both kerberos and afs): $ kadmin.local -q "addprinc admin" $ bos adduser admin -cell -noauth The latter command means "add the user admin to the super-user list". The admin user can be considered the "root" user of AFS (you do not need to name it admin though). Sanity check: $ bos listkeys -cell -noauth No errors should be reported. It should find a key with the number you got from kadmin.local way back above. (At this point I copied /etc/openafs/ThisCell and CellServDB to /etc/openafs/server in an effect to debug a problem I had. I mention it for completeness.) Create an actual afs admin user: $ pts createuser -name admin -cell -noauth At this point I had a kind-of-difficult-to-debug problem. pts createuser blocked because ptserver was not running, and the error message in /var/log/openafs/PtLog was quite strange - but that turned out to be a general logging problem for PtLog, which I still haven't figured out. The problem however turned out to have to to with DNS. Make sure that the machine's hostname (as output by "hostname") matches the server name you've used previously. If not, you might want to change it. ptserver must be able to obtain the server host name AND resolv it correctly by DNS (it seems to bypass /etc/hosts in the look-up stage too, so in my case it barfed because I had not configured my machine with the correct fully qualified host name). If pts blocks, try "bos status -long" and see what it reports. It may report something about incorrect permissions, but that error is not fatal (albeit something one should fix). It will tell you whether or not ptserver is up and running correctly. Alternatively, see if `ps aux | grep ptserver` reports anything of interest. Add the admin user to the adimistrator group: $ pts adduser admin system:administrators -cell -noauth Sanity check: $ pts membership admin -cell -noauth Restart bosserver (not sure why this is needed): $ bos restart -all -cell -noauth More server starting: $ bos create -server -instance fs -type fs -cmd /usr/lib/openafs/fileserver -cmd /usr/lib/openafs/volserver -cmd /usr/lib/openafs/salvager -cell -noauth Note that vlserver should *not* be part of the above command, contrary to the first revision of this guide and the Debian planet article. Instead, vlserver should be set up as follows: $ bos create -server -instance vlserver -type simple -cmd /usr/lib/openafs/vlserver -cell -noauth I'm not sure what/how to set up buserver - TODO for future revision. Sanity check: $ bos status fs -long -noauth fileserver/volserver/salvager should be running okay. Create vicep mountpoint: $ mkdir /vicepa Create a filesystem on a device or a file; whever you want the AFS data to be stored (multiple instances of these can be added later): $ mkdir /var/afs Where I happened to put it. Put it wherever you like. $ mke2fs /var/afs/partition I'm not certain which filesystems are actually supported; so I am being conservative and using ext2fs. ReiserFS okay, anyone? (TODO) Add an entry to fstab: $ /var/afs/partition /vicepa ext2 defaults,loop 0 2 Modify this to suit your needs; don't just copy it blindly. If you do, I won't be held responsible if you break something. Create the root AFS volume using vos: $ vos create -server -partition /vicepa -name root.afs -cell -noauth Shutdown bosserver: $ bos shutdown -wait $ pkill bosserver I believe bosserver will sometimes (always?) remain running by design, the shutdown command seemingly only shutting down the pt/vl/etc services. Start bosserver: $ /etc/init.d/openafs-fileserver start Bosserver should now be running in normal mode, requireing authentication. Soon you will start the OpenAFS client. If you wish to use arla or do the rest remotely, you're no your own. Now, let's prepare for starting the client by creating the openafs kernel module: $ cd /usr/src && tar -xzvf openafs.tar.gz openafs.tar.gz should have come with the openafs-modules-source package. If you don't have it already: $ apt-get install kernel-package Now create a Debian package with a custom made kernel module for your kernel: $ cd /usr/src/ $ make-kpkg modules_image Substitute for the location of the source of the kernel you're using. If you're using a stock kernel, I'm not sure what the easiet way is. You can probably build the source manually as long as you have the kernel include files somewhere (but don't quote me on that). You should now have a file openafs-*.deb in /usr/src. dpkg --install it: $ dpkg --install /usr/src/openafs-<...>.deb Start the client (for initializing stuff below): $ /etc/init.d/openafs-client start If you are having trouble, manually make sure the openafs.o or openafs_mp.o module is loaded correctly, and if not, insmod it. Then you can start the "afsd" daemon manually (again, if the script doesn't do it). Obtain a kerberos ticket and convert it to an AFS ticket: $ kinit admin $ klist $ aklog -k $ tokens The parameters to aklog aren't supposed to be necessary I believe. You might try just "aklog", and if it complains, try with the parameters. Sanity check (might be required too; I once had a volume appearing empty until I ran this command): $ fs checkvolumes Set permissions on /afs (the root cell): $ fs setacl /afs system:anyuser rl Meaning anyone can read and list files in /afs. $ fs mkmount /afs/ root.cell Create a link to your home cell in AFS space. $ fs setacl /afs/ system:anyuser rl Meaning anyone can browse the root of the cell's root volume. $ fs mkmount /afs/. root.cell Mount in force read/write mode. I'm not sure why this is needed/suggested; I suspect it's a matter of convention. At this point, you should be ready to start using AFS. Have a look at 'pts' for information on how to manage AFS users and groups. You can then start building a proper hierarchy of files in your cell (home directories, etc), making sure you set permissions properly with 'fs setacl'.