doc/xml/AdminReference/sect1/dlog.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <refentry id="dlog1">
   3   <refmeta>
   4     <refentrytitle>dlog</refentrytitle>
   5     <manvolnum>1</manvolnum>
   6   </refmeta>
   7   <refnamediv>
   8     <refname>dlog</refname>
   9     <refpurpose>Authenticates to the DCE Security Service</refpurpose>
  10   </refnamediv>
  11   <refsect1>
  12     <title>Synopsis</title>
  13     <para><emphasis role="bold">dlog</emphasis> [<emphasis role="bold">-principal</emphasis> &lt;<emphasis>user name</emphasis>&gt;] [<emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;]
  14         [<emphasis role="bold">-password</emphasis> &lt;<emphasis>user's password</emphasis>&gt;]
  15         [<emphasis role="bold">-servers</emphasis> &lt;<emphasis>explicit list of servers</emphasis>&gt;+]
  16         [<emphasis role="bold">-lifetime</emphasis> &lt;<emphasis>ticket lifetime in hh[:mm[:ss]]</emphasis>&gt;]
  17         [<emphasis role="bold">-setpag</emphasis>] [<emphasis role="bold">-pipe</emphasis>] [<emphasis role="bold">-help</emphasis>]</para>
  18
  19     <para><emphasis role="bold">dlog</emphasis> [<emphasis role="bold">-pr</emphasis> &lt;<emphasis>user name</emphasis>&gt;] [<emphasis role="bold">-c</emphasis> &lt;<emphasis>cell name</emphasis>&gt;]
  20         [<emphasis role="bold">-pw</emphasis> &lt;<emphasis>user's password</emphasis>&gt;]
  21         [<emphasis role="bold">-ser</emphasis> &lt;<emphasis>explicit list of servers</emphasis>&gt;+]
  22         [<emphasis role="bold">-l</emphasis> &lt;<emphasis>ticket lifetime in hh[:mm[:ss]]</emphasis>&gt;]
  23         [<emphasis role="bold">-set</emphasis>] [<emphasis role="bold">-pi</emphasis>] [<emphasis role="bold">-h</emphasis>]</para>
  24
  25   </refsect1>
  26   <refsect1>
  27     <title>Description</title>
  28     <para>The <emphasis role="bold">dlog</emphasis> command obtains DCE credentials for the issuer from the DCE
  29     Security Service in the cell named by the <emphasis role="bold">-cell</emphasis> argument, and stores
  30     them on the AFS client machine on which the user issues the command. The
  31     AFS/DFS Migration Toolkit Protocol Translator processes running on
  32     machines in the DCE cell accept the credentials, which enables the user to
  33     access the DCE cell's filespace from the AFS client. The user's identity
  34     in the local file system is unchanged.</para>
  35
  36     <para>If the issuer does not provide the <emphasis role="bold">-principal</emphasis> argument, the <emphasis role="bold">dlog</emphasis>
  37     command interpreter uses the user name under which the issuer is logged
  38     into the local file system. Provide the DCE password for the appropriate
  39     user name. As with the <emphasis role="bold">klog</emphasis> command, the password does not cross the
  40     network in clear text (unless the issuer is logged into the AFS client
  41     from a remote machine).</para>
  42
  43     <para>The credentials are valid for a lifetime equivalent to the smallest of the
  44     following, all but the last of which is defined by the DCE cell's Security
  45     Server:</para>
  46
  47     <itemizedlist>
  48       <listitem>
  49         <para>The maximum certificate lifetime for the issuer's DCE account.</para>
  50
  51       </listitem>
  52       <listitem>
  53         <para>The maximum certificate lifetime for the AFS principal's DCE account.</para>
  54
  55       </listitem>
  56       <listitem>
  57         <para>The registry-wide maximum certificate lifetime.</para>
  58
  59       </listitem>
  60       <listitem>
  61         <para>The registry-wide default certificate lifetime.</para>
  62
  63       </listitem>
  64       <listitem>
  65         <para>The lifetime requested using the <emphasis role="bold">-lifetime</emphasis> argument.</para>
  66
  67       </listitem>
  68     </itemizedlist>
  69     <para>If the previous maximum certificate lifetime values are set to
  70     <computeroutput>default-policy</computeroutput>, the maximum possible ticket lifetime is defined by the
  71     default certificate lifetime. Refer to the DCE vendor's administration
  72     guide for more information before setting any of these values.</para>
  73
  74     <para>The AFS Cache Manager stores the ticket in a credential structure
  75     associated with the name of the issuer (or the user named by the
  76     <emphasis role="bold">-principal</emphasis> argument. If the user already has a ticket for the DCE cell,
  77     the ticket resulting from this command replaces it in the credential
  78     structure.</para>
  79
  80     <para>The AFS tokens command displays the ticket obtained by the <emphasis role="bold">dlog</emphasis> command
  81     for the server principal <computeroutput>afs</computeroutput>, regardless of the principal to which it
  82     is actually granted. Note that the <emphasis role="bold">tokens</emphasis> command does not distinguish
  83     tickets for a DFSTM File Server from tickets for an AFS File Server.</para>
  84
  85   </refsect1>
  86   <refsect1>
  87     <title>Options</title>
  88     <variablelist>
  89       <varlistentry>
  90         <term><emphasis role="bold">-principal</emphasis> &lt;<emphasis>user name</emphasis>&gt;</term>
  91         <listitem>
  92           <para>Specifies the DCE user name for which to obtain DCE credentials. If this
  93           option is omitted, the <emphasis role="bold">dlog</emphasis> command interpreter uses the name under
  94           which the issuer is logged into the local file system.</para>
  95
  96         </listitem>
  97       </varlistentry>
  98       <varlistentry>
  99         <term><emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;</term>
 100         <listitem>
 101           <para>Specifies the DCE cell in which to authenticate. During a single login
 102           session on a given machine, a user can authenticate in multiple cells
 103           simultaneously, but can have only one ticket at a time for each cell (that
 104           is, it is possible to authenticate under only one identity per cell per
 105           machine). It is legal to abbreviate the cell name to the shortest form
 106           that distinguishes it from the other cells listed in the
 107           <replaceable>/usr/vice/etc/CellServDB</replaceable> file on the local client machine.</para>
 108
 109           <para>If the issuer does not provide the <emphasis role="bold">-cell</emphasis> argument, the <emphasis role="bold">dlog</emphasis> command
 110           attempts to authenticate with the DCE Security Server for the cell defined
 111           by</para>
 112
 113           <itemizedlist>
 114             <listitem>
 115               <para>The value of the environment variable AFSCELL on the local AFS client
 116               machine, if defined. The issuer can set the AFSCELL environment variable
 117               to name the desired DCE cell.</para>
 118
 119             </listitem>
 120             <listitem>
 121               <para>The cell name in the <replaceable>/usr/vice/etc/ThisCell</replaceable> file on the local AFS
 122               client machine. The machine's administrator can place the desired DCE
 123               cell's name in the file.</para>
 124
 125             </listitem>
 126           </itemizedlist>
 127         </listitem>
 128       </varlistentry>
 129       <varlistentry>
 130         <term><emphasis role="bold">-password</emphasis> &lt;<emphasis>user's password</emphasis>&gt;</term>
 131         <listitem>
 132           <para>Specifies the password for the issuer (or for the user named by the
 133           <emphasis role="bold">-principal</emphasis> argument). Using this argument is not recommended, because
 134           it makes the password visible on the command line.  If this argument is
 135           omitted, the command prompts for the password and does not echo it
 136           visibly.</para>
 137
 138         </listitem>
 139       </varlistentry>
 140       <varlistentry>
 141         <term><emphasis role="bold">-servers</emphasis> &lt;<emphasis>list of servers</emphasis>&gt;+</term>
 142         <listitem>
 143           <para>Specifies a list of DFS database server machines running the Translator
 144           Server through which the AFS client machine can attempt to
 145           authenticate. Specify each server by hostname, shortened machine name, or
 146           IP address. If this argument is omitted, the <emphasis role="bold">dlog</emphasis> command interpreter
 147           randomly selects a machine from the list of DFS Fileset Location (FL)
 148           Servers in the <replaceable>/usr/vice/etc/CellServDB</replaceable> file for the DCE cell specified
 149           by the <emphasis role="bold">-cell</emphasis> argument. This argument is useful for testing when
 150           authentication seems to be failing on certain server machines.</para>
 151
 152         </listitem>
 153       </varlistentry>
 154       <varlistentry>
 155         <term><emphasis role="bold">-lifetime</emphasis> &lt;<emphasis>ticket lifetime</emphasis>&gt;</term>
 156         <listitem>
 157           <para>Requests a ticket lifetime using the format <emphasis>hh</emphasis><emphasis role="bold">:</emphasis><emphasis>mm</emphasis>[<emphasis role="bold">:</emphasis><emphasis>ss</emphasis>]
 158           (hours, minutes, and optionally a number seconds between 00 and 59).  For
 159           example, the value <computeroutput>168:30</computeroutput> requests a ticket lifetime of 7 days and 30
 160           minutes, and <computeroutput>96:00</computeroutput> requests a lifetime of 4 days. Acceptable values
 161           range from <computeroutput>00:05</computeroutput> (5 minutes) to <computeroutput>720:00</computeroutput> (30 days). If this argument
 162           is not provided and no other determinants of ticket lifetime have been
 163           changed from their defaults, ticket lifetime is 10 hours.</para>
 164
 165           <para>The requested lifetime must be smaller than any of the DCE cell's
 166           determinants for ticket lifetime; see the discussion in the preceding
 167           <emphasis role="bold">Description</emphasis> section.</para>
 168
 169         </listitem>
 170       </varlistentry>
 171       <varlistentry>
 172         <term><emphasis role="bold">-setpag</emphasis></term>
 173         <listitem>
 174           <para>Creates a process authentication group (PAG) in which the newly created
 175           ticket is placed. If this flag is omitted, the ticket is instead
 176           associated with the issuers' local user ID (UID).</para>
 177
 178         </listitem>
 179       </varlistentry>
 180       <varlistentry>
 181         <term><emphasis role="bold">-pipe</emphasis></term>
 182         <listitem>
 183           <para>Suppresses any prompts that the command interpreter otherwise produces,
 184           including the prompt for the issuer's password. Instead, the command
 185           interpreter accepts the password via the standard input stream.</para>
 186
 187         </listitem>
 188       </varlistentry>
 189       <varlistentry>
 190         <term><emphasis role="bold">-help</emphasis></term>
 191         <listitem>
 192           <para>Prints the online help for this command. All other valid options are
 193           ignored.</para>
 194
 195         </listitem>
 196       </varlistentry>
 197     </variablelist>
 198   </refsect1>
 199   <refsect1>
 200     <title>Output</title>
 201     <para>If the dlog command interpreter cannot contact a Translator
 202     Server, it produces a message similar to the following:</para>
 203
 204 <programlisting>
 205    dlog: server or network not responding -- failed to contact
 206    authentication service
 207
 208 </programlisting>
 209     </refsect1>
 210     <refsect1>
 211       <title>Examples</title>
 212       <para>The following command authenticates the issuer as cell_admin in the
 213       <computeroutput>dce.abc.com</computeroutput> cell.</para>
 214
 215 <programlisting>
 216    % dlog -principal cell_admin -cell dce.abc.com
 217    Password: &amp;lt;cell_admin's password&amp;gt;
 218
 219 </programlisting>
 220         <para>In the following example, the issuer authenticates as cell_admin to the
 221         <computeroutput>dce.abc.com</computeroutput> cell and request a ticket lifetime of 100 hours. The
 222         <emphasis role="bold">tokens</emphasis> command confirms that the user obtained DCE credentials as the
 223         user <computeroutput>cell_admin</computeroutput>: the AFS ID is equivalent to the UNIX ID of <computeroutput>1</computeroutput>
 224         assigned to <computeroutput>cell_admin</computeroutput> in <computeroutput>dce.abc.com</computeroutput> cell's DCE registry.</para>
 225
 226 <programlisting>
 227    % dlog -principal cell_admin -cell dce.abc.com -lifetime 100
 228    Password: &amp;lt;cell_admin's password&amp;gt;
 229
 230 </programlisting>
 231 <programlisting>
 232    % tokens
 233    Tokens held by the Cache Manager:
 234
 235 </programlisting>
 236 <programlisting>
 237    User's (AFS ID 1) tokens for afs@dce.abc.com [Expires Jul 6 14:12]
 238    User's (AFS ID 4758) tokens for afs@abc.com [Expires Jul 2 13:14]
 239
 240 </programlisting>
 241 <programlisting>
 242       --End of list--
 243
 244 </programlisting>
 245               </refsect1>
 246               <refsect1>
 247                 <title>Privilege Required</title>
 248                 <para>None</para>
 249
 250               </refsect1>
 251               <refsect1>
 252                 <title>See Also</title>
 253                 <para><link linkend="dpass1">dpass(1)</link>,
 254                 <link linkend="klog1">klog(1)</link>,
 255                 <link linkend="tokens1">tokens(1)</link>,
 256                 <link linkend="unlog1">unlog(1)</link></para>
 257
 258               </refsect1>
 259               <refsect1>
 260                 <title>Copyright</title>
 261                 <para>IBM Corporation 2000. &lt;http://www.ibm.com/&gt; All Rights Reserved.</para>
 262
 263                 <para>This documentation is covered by the IBM Public License Version 1.0.  It was
 264                 converted from HTML to POD by software written by Chas Williams and Russ
 265                 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>
 266
 267               </refsect1>
 268             </refentry>