Introduction
Occasionally it's necessary for automated processes to be able to authenticate to AFS. This mostly comes up in the context of either web servers serving content out of AFS or periodic processing such as cron jobs, although may come up in other cases as well. There is a separate page on serving web content out of AFS; this page describes how to authenticate an automated process to AFS.
In order to access AFS, one has to have an AFS token, obtained from a Kerberos ticket. Users obtain Kerberos tickets with their username and password. Automated processes don't use passwords; instead, they use a file known as a keytab. This is essentially a processed form of a password stored in a special disk format. With a keytab, one can obtain Kerberos tickets and AFS tokens using a program called kstart (or k5start).
Obtaining a keytab
The first step is to get a special Kerberos principal created for the
application and then obtain a keytab for that principal. The keytab has
to be kept secure and should not be stored in AFS (how would one
authenticate to AFS to be able to read the keytab?), so the first step is
to identify the server where the process will be run. The keytab should
be stored on local disk on that server; traditionally, we put the keytab
into /etc/
and name it keytab.service
where
service
is a short name for the service.
The Kerberos principals for such uses are named service.service
where service is a short name for the application that is using
these AFS credentials. Please note that everyone in the university shares
the same namespace here, so please make the service name specific enough
that one could determine what group it is associated with. In other
words, service.logdump
is a bad name unless it's for a campus-wide
logdump service; service.sul-logdump
is a better name for a logdump
service run by Stanford University Libraries.
See An Introduction to Keytabs for more information and how to request a service principal keytab with AFS access.
Setting ACLs
Next, you have to identify what directories the application will need to modify while it's running and make sure that this new Kerberos principal has the appropriate access to those directories.
The first step is to give the application access to those directories where it needs to read or write files. This can be done with the regular file permission commands. The application will be accessing AFS as service.service, that Kerberos principal that was created earlier, and can add that principal to AFS ACLs just like you would add any other user. You can also add it to AFS PTS groups if appropriate.
Also make sure that the application can get to the directories where it
needs to do work. This means that it must have at least list (l) access
to every parent directory all the way up to /afs/ir
. The basic
top-level directories of AFS like /afs/ir/dept
or
/afs/ir/data
are all open to the public, so you only need to check
up to one of those top-level directories. If anyone (system:anyuser), any
Stanford system (system:campushosts), or any authenticated user
(system:authuser) has l permissions, that directory is fine. Otherwise,
you need to grant at least l permissions to your new Kerberos principal
(or to some broader set of users including it, such as the above general
groups).
Running the application
Finally, you're ready to run the application.
There are two ways to do this. One is to obtain a Kerberos ticket cache
using kstart
, either running in daemon mode to maintain the cache
all the time or running immediately before the application runs, and then
point the application at that ticket cache by setting KRBTKFILE. If using
this approach, you need to run aklog
before running the
application, and you probably want to run the application from a shell
script that uses /usr/bin/pagsh
as the
shell. This keeps the AFS tokens for this run of the application isolated
from anything else that's going on at the system at the same time.
The best way to run the application with Kerberos tickets and a token is to use the latest version of k5start, available in source code from the kstart distribution page and available as a Debian package. You can just point k5start at a keytab, make sure you have aklog installed, and it will then obtain tickets, isolate the application from other AFS users, obtain tokens, and then run the application, refreshing the tickets and tokens until the application completes. See the k5start man page for instructions and examples.