=head1 NAME

dlog - Authenticates to the DCE Security Service

=head1 SYNOPSIS

dlog [B<-principal> I<user name>]  [B<-cell> I<cell name>]
[B<-password> I<user's password>]  [B<-servers> I<servers> [I<servers> ...]]
[B<-lifetime> I<ticket lifetime in hh:mm[:ss]>]
[B<-setpag>]  [B<-pipe>]  [B<-help>]

dlog [B<-pr> I<user name>]  [B<-c> I<cell name>]  [B<-pw> I<user's password>]
[B<-ser> I<servers> [I<servers> ...]]
[B<-l> I<ticket lifetime in hh:mm[:ss]>]  [B<-set>]  [B<-pi>]  [B<-h>]

=head1 DESCRIPTION

The C<dlog> command obtains DCE credentials for the issuer from the DCE
Security Service in the cell named by the B<-cell> argument, and stores
them on the AFS client machine on which the user issues the command.
The AFS/DFS Migration Toolkit Protocol Translator processes running on
machines in the DCE cell accept the credentials, which enables the
user to access the DCE cell's filespace from the AFS client. The
user's identity in the local file system is unchanged.

If the issuer does not provide the B<-principal> argument, the C<dlog>
command interpreter uses the user name under which the issuer is
logged into the local file system. Provide the DCE password for the
appropriate user name. As with the C<klog> command, the password does not
cross the network in clear text (unless the issuer is logged into the
AFS client from a remote machine).

The credentials are valid for a lifetime equivalent to the smallest of
the following, all but the last of which is defined by the DCE cell's
Security Server:

=over

=item *

The maximum certificate lifetime for the issuer's DCE account

=item *

The maximum certificate lifetime for the B<afs> principal's DCE
account

=item *

The registry-wide maximum certificate lifetime

=item *

The registry-wide default certificate lifetime

=item *

The lifetime requested using the B<-lifetime> argument

=back

If the previous maximum certificate lifetime values are set to
B<default-policy>, the maximum possible ticket lifetime is defined by the
default certificate lifetime. Refer to the DCE vendor's administration
guide for more information before setting any of these values.

The AFS Cache Manager stores the ticket in a credential structure
associated with the name of the issuer (or the user named by the
B<-principal> argument. If the user already has a ticket for the DCE
cell, the ticket resulting from this command replaces it in the
credential structure.

The AFS C<tokens> command displays the ticket obtained by the C<dlog>
command for the server principal B<afs>, regardless of the principal to
which it is actually granted. Note that the tokens command does not
distinguish tickets for a DFS(TM) File Server from tickets for an AFS
File Server.

=head1 OPTIONS

=over 4

=item B<-principal> I<user name>

Specifies the DCE user name for which to obtain DCE
credentials. If this option is omitted, the C<dlog> command
interpreter uses the name under which the issuer is logged into
the local file system.

=item B<-cell> I<cell name>

Specifies the DCE cell in which to authenticate. During a
single login session on a given machine, a user can
authenticate in multiple cells simultaneously, but can have
only one ticket at a time for each cell (that is, it is
possible to authenticate under only one identity per cell per
machine). It is legal to abbreviate the cell name to the
shortest form that distinguishes it from the other cells listed
in the B</usr/vice/etc/CellServDB> file on the local client
machine.

If the issuer does not provide the B<-cell> argument, the C<dlog>
command attempts to authenticate with the DCE Security Server
for the cell defined by

=over

=item 1.

The value of the environment variable AFSCELL on the local
AFS client machine, if defined. The issuer can set the
AFSCELL environment variable to name the desired DCE cell.

=item 2.

The cell name in the B</usr/vice/etc/ThisCell> file on the local
AFS client machine. The machine's administrator can place the
desired DCE cell's name in the file.

=back

=item B<-password> I<user's password>

Specifies the password for the issuer (or for the user named by
the B<-principal> argument). Using this argument is not
recommended, because it makes the password visible on the
command line. If this argument is omitted, the command prompts
for the password and does not echo it visibly.

=item B<-servers> I<explicit list of servers> ...

Specifies a list of DFS database server machines running the
Translator Server through which the AFS client machine can
attempt to authenticate. Specify each server by hostname,
shortened machine name, or IP address. If this argument is
omitted, the C<dlog> command interpreter randomly selects a
machine from the list of DFS Fileset Location (FL) Servers in
the B</usr/vice/etc/CellServDB> file for the DCE cell specified by
the B<-cell> argument. This argument is useful for testing when
authentication seems to be failing on certain server machines.

=item B<-lifetime> I<ticket lifetime in hh:mm[:ss]>

Requests a ticket lifetime using the format I<hh>:I<mm>[:I<ss>] (hours,
minutes, and optionally a number seconds between 00 and 59).
For example, the value B<168:30> requests a ticket lifetime of 7
days and 30 minutes, and B<96:00> requests a lifetime of 4 days.
Acceptable values range from B<00:05> (5 minutes) to B<720:00> (30
days). If this argument is not provided and no other
determinants of ticket lifetime have been changed from their
defaults, ticket lifetime is 10 hours.

The requested lifetime must be smaller than any of the DCE
cell's determinants for ticket lifetime; see the discussion in
the preceding L</"DESCRIPTION"> section.

=item B<-setpag>

Creates a process authentication group (PAG) in which the newly
created ticket is placed. If this flag is omitted, the ticket
is instead associated with the issuers' local user ID (UID).

=item B<-pipe>

Suppresses any prompts that the command interpreter otherwise
produces, including the prompt for the issuer's password.
Instead, the command interpreter accepts the password via the
standard input stream.

=item B<-help>

Prints the online help for this command. All other valid
options are ignored.

=back

=head1 OUTPUT

If the C<dlog> command interpreter cannot contact a Translator Server, it
produces a message similar to the following:

   dlog: server or network not responding -- failed to contact
   authentication service

=head1 EXAMPLES

The following command authenticates the issuer as B<cell_admin> in the
B<dce.abc.com> cell.

    dlog -principal cell_admin -cell dce.abc.com
   Password: cell_admin's password

In the following example, the issuer authenticates as B<cell_admin> to
the B<dce.abc.com> cell and request a ticket lifetime of 100 hours. The
C<tokens> command confirms that the user obtained DCE credentials as the
user B<cell_admin>: the AFS ID is equivalent to the UNIX ID of B<1> assigned
to B<cell_admin> in B<dce.abc.com> cell's DCE registry.

    dlog -principal cell_admin -cell dce.abc.com -lifetime 100
   Password: cell_admin's password


    tokens
   Tokens held by the Cache Manager:

   User's (AFS ID 1) tokens for afs@dce.abc.com [Expires Jul 6 14:12]
   User's (AFS ID 4758) tokens for afs@abc.com [Expires Jul 2 13:14]

      --End of list--

=head1 PRIVILEGE REQUIRED

None

=head1 COPYRIGHT

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
Stanford Linear Accelerator Center, a department of Stanford University.

=head1 SEE ALSO

L<dpass(1)>,
L<klog(1)>,
L<tokens(1)>,
L<unlog(1)>

=cut
