doc/xml/AdminReference/sect1/knfs.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <refentry id="knfs1">
   3   <refmeta>
   4     <refentrytitle>knfs</refentrytitle>
   5     <manvolnum>1</manvolnum>
   6   </refmeta>
   7   <refnamediv>
   8     <refname>knfs</refname>
   9     <refpurpose>Establishes authenticated access via the NFS/AFS Translator</refpurpose>
  10   </refnamediv>
  11   <refsect1>
  12     <title>Synopsis</title>
  13     <para><emphasis role="bold">knfs</emphasis> <emphasis role="bold">-host</emphasis> &lt;<emphasis>host name</emphasis>&gt; [<emphasis role="bold">-id</emphasis> &lt;<emphasis>user ID (decimal)</emphasis>&gt;]
  14         [<emphasis role="bold">-sysname</emphasis> &lt;<emphasis>host's '@sys' value</emphasis>&gt;] [<emphasis role="bold">-unlog</emphasis>] [<emphasis role="bold">-tokens</emphasis>]
  15         [<emphasis role="bold">-help</emphasis>]</para>
  16
  17     <para><emphasis role="bold">knfs</emphasis> <emphasis role="bold">-ho</emphasis> &lt;<emphasis>host name</emphasis>&gt; [<emphasis role="bold">-i</emphasis> &lt;<emphasis>user ID (decimal)</emphasis>&gt;]
  18         [<emphasis role="bold">-s</emphasis> &lt;<emphasis>host's '@sys' value</emphasis>&gt;] [<emphasis role="bold">-u</emphasis>] [<emphasis role="bold">-t</emphasis>] [<emphasis role="bold">-he</emphasis>]</para>
  19
  20   </refsect1>
  21   <refsect1>
  22     <title>Description</title>
  23     <para>The <emphasis role="bold">knfs</emphasis> command creates an AFS credential structure on the local
  24     machine, identifying it by a process authentication group (PAG) number
  25     associated with the NFS client machine named by the <emphasis role="bold">-hostname</emphasis> argument
  26     and by default with a local UID on the NFS client machine that matches the
  27     issuer's local UID on the local machine. It places in the credential
  28     structure the AFS tokens that the issuer has previously obtained (by
  29     logging onto the local machine if an AFS-modified login utility is
  30     installed, by issuing the <emphasis role="bold">klog</emphasis> command, or both). To associate the
  31     credential structure with an NFS UID that does not match the issuer's
  32     local UID, use the <emphasis role="bold">-id</emphasis> argument.</para>
  33
  34     <para>Issue this command only on the NFS(R)/AFS translator machine that is
  35     serving the NFS client machine, after obtaining AFS tokens on the
  36     translator machine for every cell to which authenticated access is
  37     required. The Cache Manager on the translator machine uses the tokens to
  38     obtain authenticated AFS access for the designated user working on the NFS
  39     client machine. This command is not effective if issued on an NFS client
  40     machine.</para>
  41
  42     <para>To enable the user on the NFS client machine to issue AFS commands, use
  43     the <emphasis role="bold">-sysname</emphasis> argument to specify the NFS client machine's system type,
  44     which can differ from the translator machine's. The NFS client machine
  45     must be a system type for which AFS is supported.</para>
  46
  47     <para>The <emphasis role="bold">-unlog</emphasis> flag discards the tokens in the credential structure, but
  48     does not destroy the credential structure itself. The Cache Manager on the
  49     translator machine retains the credential structure until the next reboot,
  50     and uses it each time the issuer accesses AFS through the translator
  51     machine. The credential structure only has tokens in it if the user
  52     reissues the <emphasis role="bold">knfs</emphasis> command on the translator machine each time the user
  53     logs into the NFS client machine.</para>
  54
  55     <para>To display the tokens associated with the designated user on the NFS
  56     client machine, include the <emphasis role="bold">-tokens</emphasis> flag.</para>
  57
  58     <para>Users working on NFS client machines of system types for which AFS
  59     binaries are available can use the <emphasis role="bold">klog</emphasis> command rather than the <emphasis role="bold">knfs</emphasis>
  60     command.</para>
  61
  62   </refsect1>
  63   <refsect1>
  64     <title>Cautions</title>
  65     <para>If the translator machine's administrator has enabled UID checking by
  66     issuing the <emphasis role="bold">fs exportafs</emphasis> command with the <emphasis role="bold">-uidcheck on</emphasis> argument, it
  67     is not possible to use the <emphasis role="bold">-id</emphasis> argument to assign the tokens to an NFS
  68     UID that differs from the issuer's local UID. In this case, there is no
  69     point in including the <emphasis role="bold">-id</emphasis> argument, because the only acceptable value
  70     (the issuer's local UID) is the value used when the <emphasis role="bold">-id</emphasis> argument is
  71     omitted. Requiring matching UIDs is effective only when users have the
  72     same local UID on the translator machine as on NFS client machines. In
  73     that case, it guarantees that users assign their tokens only to their own
  74     NFS sessions.</para>
  75
  76     <para>This command does not make it possible for users working on non-supported
  77     system types to issue AFS commands. This is possible only on NFS clients
  78     of a system type for which AFS is available.</para>
  79
  80   </refsect1>
  81   <refsect1>
  82     <title>Options</title>
  83     <variablelist>
  84       <varlistentry>
  85         <term><emphasis role="bold">-host</emphasis> &lt;<emphasis>host name</emphasis>&gt;</term>
  86         <listitem>
  87           <para>Names the NFS client machine on which the issuer is to work.  Providing a
  88           fully-qualified hostname is best, but abbreviated forms are possibly
  89           acceptable depending on the state of the cell's name server at the time
  90           the command is issued.</para>
  91
  92         </listitem>
  93       </varlistentry>
  94       <varlistentry>
  95         <term><emphasis role="bold">-id</emphasis> &lt;<emphasis>user ID (decimal)</emphasis>&gt;</term>
  96         <listitem>
  97           <para>Specifies the local UID on the NFS client to which to assign the
  98           tokens. The NFS client identifies file requests by the NFS UID, so
  99           creating the association enables the Cache Manager on the translator
 100           machine to use the appropriate tokens when filling the requests. If this
 101           argument is omitted, the command interpreter uses an NFS UID that matches
 102           the issuer's local UID on the translator machine (as returned by the
 103           getuid() function).</para>
 104
 105         </listitem>
 106       </varlistentry>
 107       <varlistentry>
 108         <term><emphasis role="bold">-sysname</emphasis> &lt;<emphasis>host's '@sys' value</emphasis>&gt;</term>
 109         <listitem>
 110           <para>Specifies the value that the local (translator) machine's remote executor
 111           daemon substitutes for the <emphasis>@sys</emphasis> variable in pathnames when executing
 112           AFS commands issued on the NFS client machine (which must be a supported
 113           system type). If the NFS user's PATH environment variable uses the <emphasis>@sys</emphasis>
 114           variable in the pathnames for directories that house AFS binaries (as
 115           recommended), then setting this argument enables NFS users to issue AFS
 116           commands by leading the remote executor daemon to access the AFS binaries
 117           appropriate to the NFS client machine even if its system type differs from
 118           the translator machine's.</para>
 119
 120         </listitem>
 121       </varlistentry>
 122       <varlistentry>
 123         <term><emphasis role="bold">-unlog</emphasis></term>
 124         <listitem>
 125           <para>Discards the tokens stored in the credential structure identified by the
 126           PAG associated with the <emphasis role="bold">-host</emphasis> argument and, optionally, the <emphasis role="bold">-id</emphasis>
 127           argument.</para>
 128
 129         </listitem>
 130       </varlistentry>
 131       <varlistentry>
 132         <term><emphasis role="bold">-tokens</emphasis></term>
 133         <listitem>
 134           <para>Displays the AFS tokens assigned to the designated user on the indicated
 135           NFS client machine.</para>
 136
 137         </listitem>
 138       </varlistentry>
 139       <varlistentry>
 140         <term><emphasis role="bold">-help</emphasis></term>
 141         <listitem>
 142           <para>Prints the online help for this command. All other valid options are
 143           ignored.</para>
 144
 145         </listitem>
 146       </varlistentry>
 147     </variablelist>
 148   </refsect1>
 149   <refsect1>
 150     <title>Output</title>
 151     <para>The following error message indicates that UID checking is enabled on the
 152     translator machine and that the value provided for the <emphasis role="bold">-id</emphasis> argument
 153     differs from the issuer's local UID.</para>
 154
 155 <programlisting>
 156    knfs: Translator in 'passwd sync' mode; remote uid must be the same as
 157    local uid
 158
 159 </programlisting>
 160     </refsect1>
 161     <refsect1>
 162       <title>Examples</title>
 163       <para>The following example illustrates a typical use of this command. The
 164       issuer <computeroutput>smith</computeroutput> is working on the machine <computeroutput>nfscli1.abc.com</computeroutput> and has user
 165       ID <computeroutput>1020</computeroutput> on that machine. The translator machine <computeroutput>tx4.abc.com</computeroutput> uses an
 166       AFS-modified login utility, so <computeroutput>smith</computeroutput> obtains tokens for the ABC
 167       Corporation cell automatically upon login via the <emphasis role="bold">telnet</emphasis> program. She
 168       then issues the <emphasis role="bold">klog</emphasis> command to obtain tokens as <computeroutput>admin</computeroutput> in the ABC
 169       Corporation's test cell, <computeroutput>test.abc.com</computeroutput>, and the <emphasis role="bold">knfs</emphasis> command to
 170       associate both tokens with the credential structure identified by machine
 171       name <computeroutput>nfs-cli1</computeroutput> and user ID <computeroutput>1020</computeroutput>. She breaks the connection to <computeroutput>tx4</computeroutput>
 172       and works on <computeroutput>nfscli1</computeroutput>.</para>
 173
 174 <programlisting>
 175    % telnet tx4.abc.com
 176    . . .
 177    login: smith
 178    Password:
 179    AFS(R) login
 180
 181 </programlisting>
 182 <programlisting>
 183    % klog admin -cell test.abc.com
 184    Password:
 185
 186 </programlisting>
 187 <programlisting>
 188    % knfs nfscli1.abc.com 1020
 189
 190 </programlisting>
 191 <programlisting>
 192    % exit
 193
 194 </programlisting>
 195               <para>The following example shows user smith again connecting to the machine
 196               <computeroutput>tx4</computeroutput> via the <emphasis role="bold">telnet</emphasis> program and discarding the tokens.</para>
 197
 198 <programlisting>
 199    % telnet translator4.abc.com
 200    . . .
 201    login: smith
 202    Password:
 203    AFS(R) login
 204
 205 </programlisting>
 206 <programlisting>
 207    % knfs nfscli1.abc.com 1020 -unlog
 208
 209 </programlisting>
 210 <programlisting>
 211    % exit
 212
 213 </programlisting>
 214                   </refsect1>
 215                   <refsect1>
 216                     <title>Privilege Required</title>
 217                     <para>None</para>
 218
 219                   </refsect1>
 220                   <refsect1>
 221                     <title>See Also</title>
 222                     <para><link linkend="klog1">klog(1)</link>,
 223                     <link linkend="pagsh1">pagsh(1)</link></para>
 224
 225                   </refsect1>
 226                   <refsect1>
 227                     <title>Copyright</title>
 228                     <para>IBM Corporation 2000. &lt;http://www.ibm.com/&gt; All Rights Reserved.</para>
 229
 230                     <para>This documentation is covered by the IBM Public License Version 1.0.  It was
 231                     converted from HTML to POD by software written by Chas Williams and Russ
 232                     Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>
 233
 234                   </refsect1>
 235                 </refentry>