OpenAFS on non-CSAIL Linux

AFS on non-CSAIL Ubuntu Linux (and similar distributions)

IMPORTANT: TIG supports AFS on our centrally managed CSAIL Linux systems. We do not support AFS on Linux systems we do not manage; therefore, we do not guarantee that any of the instructions here will work for you. Information on this page is provided as a convenience in case it is useful. That said, if you have suggestions or corrections, feel free to let us know. Please include the URL of this page so we know where to make changes.

OpenAFS

These instructions should work as-is on Ubuntu 16.04 and later (including flavors such as Xubuntu, Kubuntu, and Mate). They may work on recent versions of (non-Ubuntu) Debian and other Debian- and Ubuntu-derived distributions as well, depending whether a repository is available with sufficiently recent versions of OpenAFS packages. Versions 1.8.7 and some patched versions of 1.8.6 and later are recent enough; due to a time-processing bug, earlier versions stopped working in January 2021.

These instructions are not needed and should not be used on CSAIL Ubuntu or other Debian/Ubuntu distributions that are already configured to support Kerberos and AFS, such as Athena workstations.

• Add the repository with recent OpenAFS packages

  sudo apt-add-repository ppa:openafs/stable
  

  (Depending what version of Ubuntu you’re running, this may prompt you to also run sudo apt-get install init-system-helpers/VERSION-backports. For instance, on Ubuntu 18.04, you need to sudo apt-get install init-system-helpers/bionic-backports. Read the output of the apt-add-repository command and do so if necessary.)

• Install the necessary packages.

  sudo apt-get install openafs-krb5 openafs-client krb5-user module-assistant openafs-modules-dkms
  

  NOTE: The openafs-modules-dkms package automatically does the compiling and installation of the openafs kernel module. More importantly, it keeps the kernel module up-to-date as software updates upgrade the kernel.

• When asked, supply these answers to the following questions:

  AFS cell this workstation belongs to:	csail.mit.edu
  Size of AFS cache:	512000 (this means 0.5GB, can be higher if you have the space)
  Kerberos servers for your realm:	kerberos-1.csail.mit.edu kerberos-2.csail.mit.edu
  Administrative server for your Kerberos realm:	kerberos.csail.mit.edu
  DB server host names for your home cell:	(blank)
  Run openafs client now and at boot?	(user preference)

• Newer Ubuntu distribution may include a /etc/openafs/CellServDB that has pointers to csail.mit.edu. Remove these lines, if they exist. (This was not necessary on 12.04 beta 1.)

• For some versions of the OpenAFS packages, by default, debconf won’t ask all the necessary questions on the first pass. You’ll need to reconfigure. Run:

  sudo dpkg-reconfigure krb5-config openafs-client
  

  (On recent versions, though, the defaults may be correct.)

• When asked, supply these answers to the following questions:

  Default realm:	CSAIL.MIT.EDU (all caps)
  Does DNS contain pointers to your realm’s Kerberos Servers?	Yes
  AFS cell this workstation belongs to:	csail.mit.edu
  Size of AFS cache:	512000 (this means 0.5GB, can be higher if you have the space)
  Run openafs client now and at boot?	(user preference)
  Look up AFS cells in DNS?	Yes
  Encrypt authenticated traffic with AFS fileserver?	Yes
  Dynamically generate the contents of /afs	Yes
  Use fakestat?	Yes
  DB server host names for your home cell:	(blank)
  Run openafs client now and at boot?	(user preference)

• If you have to start or restart OpenAFS (e.g. if you told the package configuration not to start it automatically at boot and you want to start it manually, of if you need to restart after changing configuration files), you can do so with

  sudo service openafs-client restart
  

  (or start if it’s not already running).

• Things should be working. Test the functionality with the following sequence of commands (obviously giving your CSAIL username after kinit on the first line):

  kinit <csail_username>
  klist
  aklog
  tokens
  

  If your username on the local system happens to be the same as your CSAIL username, you can omit it. (If your username both at CSAIL and on your Ubuntu laptop is jsekora, for instance, you can just type kinit, although kinit jsekora will also work.) Also, once you’ve authenticated to Kerberos once in a session, you can omit the username when renewing your tickets with kinit.

AuriStor filesystem

AuriStor is a commercial, proprietary implementation of AFS, with some performance improvements. If using both AuriStor’s server software (which we have licensed and use at CSAIL) and AuriStor’s client software, you will see faster performance. Kernel upgrades to your system will also be much faster, since AuriStor distributes precompiled binaries. However, the downside of that is that if you happen to upgrade to a new kernel before AuriStor has packaged their corresponding update, AFS will break (until they release new binaries and you upgrade to them). In practice this hasn’t been a big problem at CSAIL but it has bitten us once or twice.

IMPORTANT: TIG provides support for AFS on centrally managed CSAIL Ubuntu systems only, and we have even less experience with the AuriStor client on Ubuntu or Debian systems we do not ourselves administer than with OpenAFS on them. Follow these instructions at your own risk, and we provide no guarantee they will work. That said, if you have corrections to this documentation, feel free to let us know. Please include the URL of this page so we know where to make changes.

Eventually, AuriStor intends to have an installer available for Ubuntu (and Debian), but for now, configuring their repository and installing packages is manual. Here are lightly tested instructions we’ve gotten from AuriStor for this process:

codename=$(lsb_release -c -s)
echo "deb [arch=amd64] https://client-rpm-repo.auristor.com/filesystem/repo/recommended/$codename/ $codename client" > /tmp/auristor.list
sudo cp /tmp/auristor.list /etc/apt/sources.list.d/auristor.list

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 31B87DD6B9539F3E
sudo apt-get update
sudo apt-get install krb5-user auristorfs-modules-dkms auristorfs-client
sudo apt-get autoremove

The first few lines are to create a new (root-owned) file /etc/apt/sources.list.d/auristor.list with just one line in it saying

deb [arch=amd64] https://client-rpm-repo.auristor.com/filesystem/repo/recommended/CODENAME/ CODENAME client

where CODENAME is the name for your Ubuntu or Debian (or other Debian-derived) release, like focal or jammy or bullseye or sid. (If copying and pasting, the double-quotes are important!)

The sudo apt-key line adds and trusts the signature AuriStor uses to sign their repository. (If they change their key, you can find the new key from the warning message sudo apt-get update gives you; add the new key and rerun sudo apt-get update.)

When you sudo apt-get install, you’ll be asked a few questions. The ones that matter most are:

Note that the default Kerberos realm must be in all capitals, while the AuriStorFS (i.e., AFS) cell must be in all lowercase. You may not be asked all these questions, and for the other questions, you can accept the defaults.

As above for OpenAFS, feel free to allocate more space for the cache if you like.

(DISCLAIMER: These instructions were tested on a system that already had OpenAFS installed following the instructions and with the configuration specified above!)

If you already had OpenAFS running before installing AuriStor, you may have to run

kdestroy
unlog
kinit YOURCSAILUSERNAME@csail.mit.edu
aklog

after installing AuriStor before AFS access will work again. The apt-get autoremove at the end is because installing AuriStor disables OpenAFS, but does not remove the OpenAFS kernel modules, which have to be recompiled on every kernel upgrade. If you don’t either apt-get autoremove or apt-get remove openafs-modules-dkms, you’ll still be recompiling OpenAFS kernel modules you never use on every kernel upgrade, which defeats some of the point of using AuriStor instead.