--- /dev/null
+=head1 NAME
+
+asetkey - Add a key from a keytab to an AFS KeyFile
+
+=head1 SYNOPSIS
+
+=for html
+<div class="synopsis">
+
+B<asetkey> add <I<kvno>> <I<keyfile>> <I<principal>>
+
+B<asetkey> delete <I<kvno>>
+
+B<asetkey> list
+
+=for html
+</div>
+
+=head1 DESCRIPTION
+
+The B<asetkey> command is used to add a key to an AFS KeyFile from a
+Kerberos keytab. It is similar to B<bos addkey> except that it must be
+run locally on the system where the KeyFile is located and it takes the
+new key from a Kerberos 5 keytab rather than prompting for the password.
+
+B<asetkey delete> can be used to delete a key (similar to B<bos
+removekeys>), and B<asetkey list> will list the keys in a KeyFile (similar
+to B<bos listkeys>).
+
+B<asetkey> is used when authentication for an AFS cell is provided by a
+Kerberos 5 KDC rather than B<kaserver>. The key for the C<afs> or
+C<afs/I<cell name>> principal in the Kerberos 5 KDC must match the key
+stored in the AFS KeyFile on all AFS database servers and file servers.
+This is done by creating a keytab containing that key using the standard
+Kerberos commands (generally the C<ktadd> function of the B<kadmin>
+command) and then, on each AFS database server and file server, adding
+that key to the KeyFile with B<asetkey add>. The I<kvno> chosen should
+match the kvno in the Kerberos KDC (checked with B<kvno> or the
+C<getprinc> function of B<kadmin>). I<principal> should be the name of
+the AFS principal in the keytab, which must be either C<afs> or
+C<afs/I<cell name>>.
+
+In cells that use the Update Server to distribute the contents of the
+F</usr/afs/etc> directory, it is conventional to run B<asetkey add> only
+on the control machine and then let the Update Server propagate the new
+KeyFile to all other systems.
+
+=head1 CAUTIONS
+
+AFS currently only supports des-cbc-crc:v4 Kerberos keys. Make sure, when
+creating the keytab with C<ktadd>, you pass C<-e des-cbc-crc:v4> to force
+the encryption type. Otherwise, AFS authentication may not work.
+
+As soon as a new keytab is created with C<ktadd>, new AFS service tickets
+will use the new key. However, tokens formed from those service tickets
+will only work if the new key is present in the KeyFile on the AFS file
+server. There is therefore an outage window between when the new keytab
+is created and when the key had been added to the KeyFile of all AFS
+servers with B<asetkey>, during which newly obtained AFS tokens will not
+work properly.
+
+All of the KeyFile entries must match the key in the Kerberos KDC, but
+each time C<ktadd> is run, it creates a new key. Either the Update Server
+must be used to distribute the KeyFile to all servers or the same keytab
+must be used with B<asetkey> on each server.
+
+=head1 EXAMPLES
+
+The following commands create a new keytab for the principal C<afs> and
+then import the key into the KeyFile. Note the kvno in the output from
+C<ktadd>.
+
+ % kadmin
+ Authenticating as principal rra/admin@stanford.edu with password.
+ Password for rra/admin@stanford.edu:
+ kadmin: ktadd -k /tmp/afs.keytab -e des-cbc-crc:v4 afs
+ Entry for principal afs with kvno 3, encryption type DES cbc mode
+ with CRC-32 added to keytab WRFILE:/tmp/afs.keytab.
+ kadmin: exit
+ % asetkey 3 /tmp/afs.keytab afs
+
+You may want to use C<afs/I<cell name>> instead of C<afs>, particularly if
+you may have multiple AFS cells for a single Kerberos realm.
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be able to read (for B<asetkey list>) and write (for
+B<asetkey add> and B<asetkey delete>) the KeyFile, normally
+F</usr/afs/etc/KeyFile>. In practice, this means that the issuer must be
+the local superuser C<root> on the AFS file server or database server.
+For B<asetkey add>, the issuer must also be able to read the specified
+keytab file.
+
+=head1 SEE ALSO
+
+L<KeyFile(5)>,
+L<bos_addkey(8)>,
+L<bos_listkeys(8)>,
+L<bos_removekey(8)>,
+kadmin(8),
+kvno(1)
+
+=head1 COPYRIGHT
+
+Copyright 2006 Russ Allbery <rra@stanford.edu>
+
+This documentation is covered by the IBM Public License Version 1.0. This
+man page was written by Russ Allbery for OpenAFS.
--- /dev/null
+=head1 NAME
+
+ka-forwarder - Forward AFS Authentication Server requests to another server
+
+=head1 SYNOPSIS
+
+=for html
+<div class="synopsis">
+
+B<ka-forwarder> S<<< [B<-p> <I<port>>] >>> <I<server>>[/<I<port>>] [...]
+
+=for html
+</div>
+
+=head1 DESCRIPTION
+
+B<ka-forwarder> listens for requests for an AFS Authentication Server and
+forwards them to a remove B<fakeka> server. B<fakeka> is a server that
+answers AFS Authentication Server protocol requests using a regular
+Kerberos KDC and is provided with some Kerberos 5 implementations.
+B<fakeka> has to run on the same host as the Kerberos KDC, however, and
+AFS clients send all native AFS authentication requests to the AFS
+database servers. If you don't want to run your Kerberos KDCs and your
+AFS database servers on the same host, run B<ka-forwarder> on the AFS
+database servers and point it to B<fakeka> running on the Kerberos KDCs.
+
+B<ka-forwarder> takes one or more servers to which to forward the
+requests. The default port on the remote server to which to forward the
+command is 7004, but a different port can be specified by following the
+server name with a slash (C</>) and the port number. If multiple servers
+are given, B<ka-forwarder> will send queries to each server in turn in a
+round-robin fashion.
+
+=head1 CAUTIONS
+
+Due to the way that B<ka-forwarder> distinguishes from client requests and
+server responses, any messages from one of the servers to which
+B<ka-forwarder> is forwarding will be considered a reply rather than a
+command and will not be forwarded. This means that the servers running
+B<fakeka> will not be able to use native AFS authentication requests and
+rely on B<ka-forwarder> to send the requests to the right server.
+
+B<ka-forwarder> does not background itself. It should either be run in
+the background via the shell, or run via the Basic OverSeer Server (see
+L<bosserver(8)>).
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-p> <I<port>>
+
+By default, B<ka-forwarder> listens to the standard AFS Authentication
+Server port (7004). To listen to a different port, specify it with the
+B<-p> option.
+
+=back
+
+=head1 EXAMPLES
+
+Forward AFS Authentication Server reqests to the B<fakeka> servers on
+kdc1.example.com and kdc2.example.com:
+
+ % ka-forwarder kdc1.example.com kdc2.example.com &
+
+Note the C<&> to tell the shell to run this command in the background.
+
+=head1 PRIVILEGE REQUIRED
+
+B<ka-forwarder> only has to listen to port 7004 and therefore does not
+require any special privileges unless a privileged port is specified with
+the B<-p> option.
+
+=head1 SEE ALSO
+
+L<bosserver(8)>,
+fakeka(8),
+L<kaserver(8)>
+
+=head1 COPYRIGHT
+
+Copyright 2006 Russ Allbery <rra@stanford.edu>
+
+This documentation is covered by the IBM Public License Version 1.0. This
+man page was written by Russ Allbery for OpenAFS.
projects / packages / o / openafs.git / commitdiff