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 srvtab (for Kerberos v4; Kerberos v4 is used for AFS authentication currently at Stanford). This is essentially a processed form of a password stored in a special disk format. With a srvtab, one can obtain Kerberos tickets and AFS tokens using a program called kstart (or k4start in newer versions).
Obtaining a srvtab
The first step is to get a special Kerberos principal created for the
application and then obtain a srvtab for that principal. The srvtab has
to be kept secure and should not be stored in AFS (how would one
authenticate to AFS to be able to read the srvtab?), so the first step is
to identify the server where the process will be run. The srvtab should
be stored on local disk on that server; traditionally, we put the srvtab
/etc/leland and name it
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
service.logdump is a bad name unless it's for a campus-wide
service.sul-logdump is a better name for a logdump
service run by Stanford University Libraries.
To request the Kerberos principal be created and to get access to download it, choose a name following the above guidelines and send mail to email@example.com requesting that service principal be created. Include the following information:
Principal name: service.service SUNet IDs: Description:
The SUNet IDs are the users who should be allowed to download it, and the description is a brief description of what it will be used for. Be sure to mention that the srvtab will be used to access AFS, since an additional step is needed on the server end to give that principal AFS access.
Once the new principal has been created, you will receive e-mail providing the instructions for how to download the srvtab. They will include a command something like:
/usr/pubsw/sbin/leland_srvtab -f /etc/leland/srvtab.service \ service.service
where service is that short name for the service using this srvtab. Run that command on the system where this application will be running to create the srvtab.
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/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
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
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/pubsw/bin/pagsh (or a local copy) 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 simple way to do all of this without having to write the wrapper
script yourself is to use
/usr/pubsw/bin/runauth to run your
application. See the manual page for runauth for all the details,
including a few examples.
The second way of running the application with Kerberos tickets and a token is to use the latest version of k4start, available in source code from the kstart distribution page and available as a Debian package. This version of k4start can do all the work that runauth would have to do; you can just point it at a srvtab, 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.
This version of k4start is not yet available in pubsw, but hopefully will be soon.