Authenticate processes

In AFS, data access is granted through "AFS tokens", in-kernel derivatives of the user's Kerberos credentials. Tokens are typically acquired automatically at login time or by running kinit, which at CERN acquires a Kerberos ticket and an AFS token.

For security reasons, Kerberos credentials and AFS tokens have a limited lifetime and can expire. The default lifetime of Kerberos tickets at CERN is 25 hours and because AFS tokens are derived from the Kerberos credentials, tokens expire after 25 hours as well.

It is not uncommon to have processes that need credentials beyond this one-day limit, or that jobs need to be started long after the user credentials have expired. Depending on the situation, AFS at CERN provides different options to deal with these requirements.

acron

The acron facility is an AFS-aware extension of the cron daemon. In addition to cron's ability to run a command at any given time or at regular intervals, acron will schedule the job on a given node and equip the environment with Kerberos credentials and an AFS token on the user's behalf. The user interface to acron is the acrontab command, which resembles the usual System V crontab command:
acrontab -l lists your acron jobs
acrontab -e lets you edit your crontab
acrontab -r deletes all your acron jobs
acrontab (without option) reads your commands from standard input.

The format of the acrontab entries is very similar to the one in Unix System V, with a few additions. For example:
• the hostname of the target host must be specified along with the command
• comments will be removed
• to protect the service, some limits on the frequency of commands are imposed.

An acrontab entry hence follows the schema:

Minute Hour DayOfMonth Month Weekday TargetHost Command

The "*" character is allowed for all fields from Hour to Weekday. The entry would run the command "date >> cron.test" on an lxplus node every day at 10.21 a.m. Because acron jobs are executed relative to a user's home directory, we would expect to find the file cron.test there. Note that a user needs to have a valid Kerberos ticket when editing their acrontab and that the target node must have the arc environment properly set up to accept commands sent by the acrontab server.

Ticket renewal

While acron allows a command to be run at any given time or at regular intervals and can provide the job with the user's credentials, some processes require valid credentials for more than the standard ticket (and token) lifetime of 25 hours. To address this, Kerberos tickets have an attribute "renewal lifetime". If the ticket has not expired, it can be renewed and the validity extended up to five days, which is the value of the Kerberos renewal lifetime at CERN. The renewal is done by running "kinit -R". Note that the renewal has to happen while the ticket is still valid: a ticket cannot be renewed if it has expired, even if the renewal lifetime has not expired yet.

k5reauth

For jobs that need to run longer than this five-day timespan, the tool k5reauth can be used. k5reauth runs a command and periodically provides it with renewed Kerberos and AFS credentials - if desired as long as the command runs. In principal, the tool can be run in two different modes. It either:
• reuses the existing Process Authentication Group (PAG) and renews the existing Kerberos and AFS credentials (until the renewal lifetime expires), or
• creates a new PAG, acquires and renews Kerberos and AFS credentials until the command started by k5reauth ends (initial authentication is done by password or keytab).

Sample calls

Here are some examples to illustrate how to use k5reauth. The command

$ k5reauth

will prompt for the current user's password, create a new PAG and then start a shell (the default command if none given) with forever-renewed Kerberos and AFS credentials.

$ k5reauth -R -- myprog

will reuse the existing PAG and the existing credentials to run the program myprog. The credentials are renewed up to the renewal expiry lifetime (five days after the initial credentials have been acquired). The double dash "--" is used to separate options to k5reauth from the options for the program to be launched.

For programs that need to run longer than the five-day renewal lifetime our sample user Phyllis could use

$ k5reauth -p phyllis -k ./phyllis_keytab -- anotherprog

This will create a new PAG, using Phyllis' keytab (which has to be created beforehand) to acquire credentials for her and then launch the command anotherprog. The credentials are renewed as long as anotherprog runs. Please refer to the k5reauth reference manual pages for advice on how to create a keytab file for a user.

A common pitfall

k5reauth only watches the command being executed and not any child processes that may have been launched by it. Because many daemons fork off a child and then exit in order to disconnect the original process from the terminal, the exiting parent process causes k5reauth to end the renewal of credentials. This leaves the child process running without valid tickets after a while. To address this, k5reauth provides the "-f" option, which mimics the old reauth behaviour of performing the renewal of credentials without the aforementioned cleanup process.

Useful links

The k5reauth man page provides information on all of the available options, along with usage examples.
The openAFS website provides information on all AFS commands: http://docs.openafs.org/Reference/index.html.