Initial manual page for kasetkey.

1 files changed, 137 insertions, 0 deletions

diff --git a/kasetkey/kasetkey.pod b/kasetkey/kasetkey.pod
new file mode 100644
index 0000000..1cce6a2
--- /dev/null
+++ b/kasetkey/kasetkey.pod
@@ -0,0 +1,137 @@
+=head1 NAME
+
+kasetkey - Manipulate AFS kaserver service principal keys
+
+=head1 SYNOPSIS
+
+B<kasetkey> [B<-dhv>] B<-a> I<admin> B<-i> [B<-p> I<password>]
+    B<-k> I<keyfile>
+
+B<kasetkey> [B<-dhv>] B<-a> I<admin> [B<-k> I<keyfile>] B<-D> I<service>
+
+B<kasetkey> [B<-dhv>] B<-a> I<admin> [B<-k> I<keyfile>]
+    [ B<-c> I<k5srvtab> | B<-r> ] B<-s> I<service> B<-f> I<srvtab>
+
+=head1 DESCRIPTION
+
+B<kasetkey> manipulates principals in an AFS kaserver, usually service
+principals.  It's primarily designed for automatic generation of srvtabs
+for keys without regular passwords, but it can be used to do other
+automated tasks, authenticating from a srvtab.
+
+To start using B<kasetkey>, obtain a srvtab for a principal with the ADMIN
+flag set in the AFS kaserver.  Such a srvtab can be created from the
+password of that principal using B<kasetkey> with the B<-i> flag.  Then,
+use B<-s> to create a srvtab for a particular principal or B<-D> to delete
+a principal from the Kerberos database, passing via B<-k> the path to the
+srvtab containing the key for an ADMIN principal.  If you don't use B<-k>,
+B<kasetkey> will prompt you for the password of the given ADMIN principal.
+
+When generating a srvtab for a particular principal using B<-s>, you have
+your choice of ways of setting the key for that principal.  The default is
+to prompt you for a password, but usually that's not what you want.
+Provide the B<-r> flag to set a random key, which is normally what you
+want to do for a pure Kerberos v4 principal.  When synchronizing Kerberos
+v5 with Kerberos v4, generate a keytab in Kerberos v5, convert it to a
+srvtab using B<ktutil>, and then provide that srvtab to B<kasetkey> with
+the B<-c> flag.  B<kasetkey> will then set the key in the AFS kaserver to
+match.
+
+B<kasetkey> uses a simple, brute-force approach to setting keys in the AFS
+kaserver.  It creates the principal if it doesn't already exist, and if it
+does already exist, it deletes it and then recreates it.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-a> I<admin>
+
+The user as whom changes should be performed.  This user must have the
+ADMIN flag set in the AFS kaserver.
+
+=item B<-c> I<srvtab>
+
+When creating a service principal using B<-s>, take the key for that
+principal from I<srvtab>.  I<srvtab> must contain a DES key and can be
+created via B<ktutil> from a Kerberos v5 keytab.
+
+=item B<-D> I<service>
+
+Delete the principal I<service> from the AFS kaserver.
+
+=item B<-d>
+
+Turn on debugging.  This prints out more information about the exit status
+of all of the API calls used.
+
+=item B<-f> I<srvtab>
+
+Where to write the srvtab for a newly created (or modified) principal.
+Used only with B<-s>.
+
+=item B<-h>
+
+Display an option summary and a few examples and then exit.
+
+=item B<-i>
+
+Initialize a srvtab.  Takes the user from B<-a> and either prompts for the
+password or takes it from the B<-p> flag.  Writes out the srvtab to the
+path given to B<-k>.
+
+=item B<-k> I<srvtab>
+
+The srvtab to use to authenticate.  The key in the srvtab must be the key
+for the user given with B<-a>.
+
+=item B<-p> I<password>
+
+The password for the user for which a srvtab is being initialized.  This
+is only used with the B<-i> flag.
+
+=item B<-r>
+
+When generating a new srvtab with B<-s>, randomize the key for that user.
+
+=item B<-s> I<service>
+
+Create a new srvtab for the principal I<service>.  If this principal
+already exists, it's deleted and recreated.  Takes the key for the
+principal from the srvtab specified with B<-c>, randomizes it if B<-r> is
+given, or prompts for it.
+
+=item B<-v>
+
+Prints the version of B<kasetkey> and exits.
+
+=back
+
+=head1 EXAMPLES
+
+To create a srvtab for rcmd.slapshot and be prompted for the admin
+passowrd:
+
+    kasetkey -f srvtab.rcmd.slapshot -s rcmd.slapshot -r
+
+To create a srvtab from within a script you must stash the DES key
+in a srvtab with:
+
+    kasetkey -a admin -i -k /.adminkey
+
+(which will prompt you for the password) and then create a srvtab for
+rcmd.slapshot with:
+
+    kasetkey -k /.adminkey -a admin -r -f srvtab -s rcmd.slapshot
+
+=head1 AUTHORS
+
+Originally written by Roland Schemers.  Revised to use srvtabs rather than
+simple DES keys and to support principal deletion by Russ Allbery
+<rra@stanford.edu>, who currently maintains it.
+
+=head1 SEE ALSO
+
+kas(8), kaserver(8), ktutil(8)
+
+=cut