#
# $Id: klog.ctx,v 1.1 2000/06/01 18:38:34 lha Exp $
#

%name description

	get AFS tokens

%name os

	"Arla, KTH"

%name section

	1

%section history

	Written by Chris Wing <wingc@engin.umich.edu>. Made nonworking
	by Love Hörnquist-Åstrand <lha@stacken.kth.se> serveral times.
	
%section see also

	.Xr kauth 1 ,
	.Xr kinit 1 ,
	.Xr kauthd 8 ,
	.Xr unlog 1 ,
	.Xr tokens 1 ,
	.Xr afslog 1

%section authors

	Chris Wing <wingc@engin.umich.edu>
	\&...

%section description

	Get you a token from a kerberos server (not kaserver).

%section bugs

	The 
	.Ar servers
	option only affects where the AFS ID is looked up, not
	which servers are actually contacted to get the TGT or token.
	.Pp
	.Nm
	should automatically deal with the case where the Kerberos realm is not
	the same as the AFS cell name.

%command _main

	.Nm
	obtains AFS tokens and possibly a Kerberos ticket granting ticket
	as well. By default it only gets an AFS token for the named
	principal and cell.
	.Pp
	.Nm
	can be invoked more than once to acquire AFS
	tokens in multiple cells. There is no way at present to write
	Kerberos TGTs for different realms into the same ticket file.
	.Pp
	If
	.Nm
	is successful in getting a token and you already have a token for the same
	cell in your current PAG, it will be overwritten by the new token. An
	existing token will not be erased if a new token cannot be
	acquired.
	.Pp
	You can specify part or whole of a Kerberos principal on the command line;
	for instance:
	.Pp
	.Nm
	username
	.Pp
	or
	.Nm
	username@cell.name
	.Pp
	or just
	.Nm
	@cell.name
	.Pp
	If neither is specified, the default is your current user name and the
	local AFS cell.
	.Pp
	The following flags are supported:
	.Bl -tag -width principal
	.It Fl principal
	Principal to get tokens for. If not specified,
	.Nm
	tries to use your user name, which is guessed from $USER or from the UID
	that
	.Nm
	is run as.
	.It Fl lifetime
	Lifetime for the Kerberos TGT and/or AFS token. This can be specified as:
	.Nm
	.Ar lifetime
	hours
	.Pp
	or
	.Nm
	.Ar lifetime
	hours:minutes
	.Pp
	or
	.Nm
	.Ar lifetime
	hours:minutes:seconds
	.Pp
	If this option is not specified, the default lifetime of 720 hours (30
	days) is used; however, the administrators of your cell may
	have chosen a lesser maximum lifetime.
	.Pp
	Please note that in Kerberos 4, only 255 discrete lifetimes are possible
	spanning the range from 5 minutes to 30 days. The lifetime
	that you specify will be rounded up to the next possible lifetime.
	.It Fl cell
	AFS cell to get tokens for. If not specified,
	.Nm
	guesses your local cell.
	.It Fl password
	You can specify the Kerberos password on the command line. This is a
	really, really, really, bad idea on most systems out there, since any user
	can use the 
	.Xr ps(1)
	command to examine the command line of any running process.
	.Pp
	You should not use this option.
	.It Fl realm
	Most AFS cells are set up in such a way that the Kerberos realm name is
	the same as the cell name (except in upper case). If the name
	of your AFS cell differs from your Kerberos realm, however,
	.Nm
	may not be able to automatically fetch your tokens without specifying the
	correct realm name with this option.
	.It Fl servers
	You can list one or more kaservers to contact directly here.
	.Nm
	will attempt to contact each of them until it finds one that works.
	.It Fl timeout
	You can specify the number of seconds that
	.Nm
	will wait for a network operation to complete. (there are 3 network
	operations peformed by
	.Nm
	- the AFS ID is looked up from the dbserver, the Kerberos 4 TGT must be
	obtained, and the AFS token must be fetched.
	.Pp
	If you do not use this option,
	.Nm
	will wait forever if necessary.
	.It Fl silent
	This causes
	.Nm
	not to write to the standard error channel. By default, error
	messages are sent to stderr.
	.It Fl pipe
	If this flag is given, then
	.Nm
	will not write to the standard output, and will only accept a password
	written to the standard input. Error messages will still be
	printed to standard error unless the
	.Ar silent
	option is also specified.
	.Pp
	Because it does not attempt to verify that the TTY is safe, this should
	only be used from scripts.
	.It Fl setpag
	Stores the AFS token in a new PAG, and then
	.Fn exec
	s a shell. The environment variable
	.Ev KRBTKFILE
	is set to point
	to a unique name in
	.Va /ticket,
	so that the Kerberos TGT gathered (if any) is written to a
	safe place.  The shell is chosen via
	.Fn getpwnam
	called with the principal's name; if that fails, then
	.Fn getpwuid
	is tried with your current UID; if this fails,
	.Nm
	attempts to execute
	.Va /bin/sh.
	.It Fl tmp
	Actually get a Kerberos TGT and writes it to 
	.Pa /tmp
	(or the file specified in the 
	.Ev KRBTKFILE
	environment variable). By default, only an AFS token is	acquired.
	.Pp
	This is a poor choice of name, as in reality writing Kerberos tickets to
	.Pa /tmp
	is a bad idea and often a security risk. This name is only here for
	compatibility with other AFS implementations. (
	.Ar tgt
	would have been a better choice of name)
	.It Fl help
	Prints out a help message.
	.El
	.Sh EXIT STATUS
	.Nm
	returns with exit status 0 (true) if and only if a Kerberos 4 TGT was
	successfully acquired and an AFS token was successfully stored. In all
	other cases, the return value is non-zero.
	.Pp
	It is possible to call
	.Nm
	from scripts or other programs for automated authentication with the
	.Ar pipe
	option, although discretion and caution is advised when doing so.
	.Sh NOTES
	By default,
	.Nm
	tries to look up your Kerberos principal in the kaserver's database to
	figure out the proper AFSId to use. As far as I know, this only affects
	the output of the 
	.Xr tokens(1)
	program.
