Authenticating daemons to AFS
In normal situations, daemons that are (for example) run as background processes, do not have authenticated access to AFS. This document describes a mechanism for running background daemons so that they can obtain such access. It is assumed that the reader has a working knowledge of AFS as described in the Facilities AFS documentation and has read the documentation on how the AFS cache manager handles authentication. The procedures described here are for Facilitized hosts.
How to do itThe basic procedure for running authenticated daemons involves the following steps (steps 1-4 are setup steps that should only have to be done once):
- Use the Instance Manager to create a <username>.daemon Kerberos instance (where "username" is your SCS username).
- Contact the SCS Help Desk to key your <username>.daemon instance and define the corresponding AFS identity.
- Add that instance to the ACLs for the AFS directories it will need to access.
- Create key and keytab files for the daemon instance you created.
- Run the daemon in a way such that it gets its own PAG and (after the PAG is created) Kerberos and AFS tokens.
1. Use the Instance Manager to create a <username>.daemon Kerberos instance
2. Contact the SCS Help Desk to key your <username>.daemon instance and define the corresponding AFS identity
Once you have created your <username>.daemon instance, send an email to firstname.lastname@example.org requesting that the instance be keyed and defined.
3. Add the <username>.daemon instance to AFS ACLs as necessary
To minimize any potential security risks, you should only add this instance to the ACLs of directories that the daemon needs to access. See the documentation on AFS ACLs for instructions on how to change ACLs.
4. Create key and keytab files
To do this step, you will need to know the 16 character hex string for the Kerberos key of the .daemon instance you created in step 1. You must be your root instance to perform this task.
- Login to the machine that will be running the daemon and run the following two commands:
umask 077 cd /etc/not-backed-upThis is to ensure that the keyfiles are not readable and will not be backed up (since backed-up data goes over the network in the clear). If you need to use a more convenient name or location for the files you will create in this directory, use a symbolic link.
- Rename/remove any existing <username>.daemon.* in that directory.
- Run the following command:
/usr/local/etc/ksrvhost <username> =daemonand type in the Kerberos hex string you got from Jeeves at the prompt.
- Run the following command to create the Kerberos 5 keytab file:
/usr/local/etc/dokeytab <username>.daemon.keytab <username>.daemon
Both files should be readable only by the owner of the files, and the owner should be the same as the Unix user which the daemon will be running as. If that is not the case, use chmod and chown to change ownership and modes to the correct ones. If you are on a platform the still runs the old backup system (eg SunOS), you should make sure that these files are in the "nobackup" group.
5. Running the daemon
It is important that the daemon is run in a way that it gets its own PAG before starting. If it does not do so, all processes without a PAG with the same Unix user ID as the daemon will share the same token and perhaps have undesired authenticated access to AFS. The general procedure to follow is: Before starting the daemon:
- Get a new PAG.
- Set unique names for KRBTKFILE and KRB5CCNAME in the process environment.
- Obtain the Kerberos tickets, including an AFS service ticket and store the AFS token.
Now execute the daemon. At this point, the daemon will inherit the Kerberos tickets (via the KRBTKFILE and KRB5CCNAME in the environment) and the AFS tokens (via the PAG which is shared by all descendents of the PAG creator).
After the daemon is running:
- Have some mechanism to periodically renew tickets before they expire (the default ticket lifetime is usually 25 hours).
- Have some mechanism to detect when the daemon has exited, either via looking for a /var/run/<daemon>.pid file or through some other means.
As long as the process that is maintaining the tickets has the same PAG and the same KRBTKFILE and KRB5CCNAME then tickets for the daemon process can be maintained forever.
The following wrapper Perl script is an example of how to do the above steps: run_with_tickets
Before using this script, you should read through it and modify variables appropriately for your application. This script has not been extensively tested.
The sample "run_with_tickets" script uses a child watcher process to maintain the tickets. It exits when it detects that its parent process is gone. The parent process is assumed to be the daemon (or some indefinately running process) which is exec-ed to replace the parent perl process.
It is common for daemon processes to use a paradigm where the daemon will fork, the parent will exit, and the child will continue execution thus placing itself in the background. Such daemon processes must be started with a switch so that the daemon does not perform this forking operation.
If the daemon does not support startup without placing itself in the background, then you will need maintain your own script using the above guidelines.
If the daemon does support the "run_with_tickets" script, then you can start your daemon with a "launch_daemon" script that contains the following:
/usr/mypkg/etc/run_with_tickets /usr/mkpkg/bin/my_daemon arg1 arg2 >/some/log/file 2>&1 &
The above example assumes a sh-based script with associated files located under "/usr/mypkg"