doc/xml/QuickStartUnix/appendix.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <appendix id="Legacy">
   3   <title>Appendix B. Configuring Legacy Components</title>
   4
   5   <para>This chapter describes how to configure a number of deprecated
   6   components in OpenAFS. Whilst these components are not recommended for sites
   7   performing new installations, it is recognised that there are a number of
   8   installations which have not yet transitioned from using these, for whom
   9   continued provision of installation instructions my be useful</para>
  10
  11   <sect1 id="KAS001">
  12     <title>kaserver and Legacy Kerberos 4 Authentication</title>
  13
  14     <para>This section contains instructions for installing server and client
  15     machines in sites which use either the deprecated AFS
  16     <emphasis role="bold">kaserver</emphasis> or legacy Kerberos 4
  17     authentication systems</para>
  18
  19     <para>This should be used in conjuction with the installation instructures
  20     in earlier chapters, whose format it mirrors.</para>
  21
  22     <sect2 id="KAS002">
  23       <title>Background</title>
  24
  25       <para>As detailed in the OpenAFS "No more DES" roadmap, OpenAFS is moving
  26       away from the single DES based security models of both
  27       <emphasis role="bold">kaserver</emphasis> and external Kerberos 4 KDCs,
  28       in favour of using external, Kerberos 5 KDCs for authentication.</para>
  29
  30       <para>AFS version 3 was designed and implemented during the late 80s and
  31       early 90s when the state of the art in distributed computer
  32       authentication and data security was Kerberos 4 and single DES. The
  33       RXKAD security class was specified to use a single DES key and the kauth
  34       authentication protocol is a derivative of MIT's Kerberos 4 protocol.
  35       </para>
  36
  37       <para>For the better part of the last decade there has been concern
  38       regarding the cryptographic strength of the DES cipher when used as a
  39       building block within systems intended to prove authentication and/or
  40       data integrity and privacy. Kerberos 4 and RXKAD are not extensible and
  41       cannot negotiate non-DES key types. As a result efforts to migrate away
  42       from Kerberos 4 based authentication at higher risk organizations have
  43       been underway since the mid to late 90s. Ken Hornstein issued the first
  44       of his Kerberos 5 migration kits for AFS in May 1999. </para>
  45
  46       <para>In March 2003, the continued use of single DES and kauth as the
  47       basis for OpenAFS security became a real-world threat when a significant
  48       Kerberos 4 crossrealm vulnerability was published. The OpenAFS community
  49       was notified in security advisory OPENAFS-SA-2003-001 which can be
  50       found at http://www.openafs.org/security.</para>
  51
  52       <para>As a result of the mounting concerns regarding the strength of
  53       DES, NIST announced in May 2003 the withdrawal of FIPS 43-3
  54       "Data Encryption Standard (DES)" as well as the associated FIPS 74 and
  55       FIPS 81. In other words, NIST announced that DES and its derivatives
  56       could no longer be used by the United States Government and should no
  57       longer by those that trust its lead.</para>
  58
  59       <para>In July 2003 MIT announced the end of life of the Kerberos 4
  60       protocol which is distributed for backward compatibility as part of the
  61       MIT Kerberos 5 distribution.</para>
  62     </sect2>
  63     <sect2 id="KAS003">
  64       <title>Using this Appendix</title>
  65
  66       <para>This appendix should be read in conjunction with the instructions
  67       contained in the earlier chapters. It contains additions and in some
  68       cases, modifications, to the directions contained in those
  69       chapters. It is organised into 3 main sections, corresponding to the
  70       topics of the earlier chapters.
  71       <orderedlist>
  72         <listitem>
  73           <para>Installing the First AFS Machine</para>
  74         </listitem>
  75         <listitem>
  76           <para>Installing Additional Server Machines</para>
  77         </listitem>
  78         <listitem>
  79           <para>Installing Additonal Client Machines</para>
  80         </listitem>
  81       </orderedlist></para>
  82
  83       <para>There is an additional section on installing AFS login
  84       functionality, which is relevant to all machines which are operating as
  85       AFS clients</para>
  86
  87       <para>In addition, some general substitions should be made
  88       <itemizedlist>
  89         <listitem>
  90           <para>References to <emphasis role="bold">kinit</emphasis>and
  91           <emphasis role="bold">aklog</emphasis> should be replaced with
  92           a single call to <emphasis role="bold">klog</emphasis></para>
  93           <para>For example
  94 <programlisting>
  95    # <emphasis role="bold">kinit admin</emphasis>
  96    Password:  <replaceable>admin_passwd</replaceable>
  97    # <emphasis role="bold">aklog</emphasis>
  98 </programlisting>
  99           becomes
 100 <programlisting>
 101    # <emphasis role="bold">kinit admin</emphasis>
 102    Password:  <replaceable>admin_passwd</replaceable>
 103 </programlisting></para>
 104         </listitem>
 105       </itemizedlist></para>
 106     </sect2>
 107     <sect2 id="KAS003a">
 108       <title>Installing the First AFS machine</title>
 109
 110       <para>This section details changes to the installation procedure for the
 111       first AFS machine which are required in order to use
 112       <emphasis role="bold">kaserver</emphasis> for authentication. As
 113       detailed above, new sites are strongly discouraged from deploying
 114       kaserver.</para>
 115
 116       <para>The structure of this section follows the structure of the
 117       earlier chapter.</para>
 118
 119       <sect3 id="F">
 120         <title>Overview: Installing Server Functionality</title>
 121
 122         <para>In adddition to the items described, you must also create
 123         the Authentication Server as a database server process. The procedure
 124         for creating the initial security mechanisms is also changed.</para>
 125       </sect3>
 126
 127       <sect3 id="KAS006">
 128         <title>Starting the kaserver Database Server Process</title>
 129         <indexterm>
 130           <primary>Authentication Server</primary>
 131           <secondary>starting</secondary>
 132           <tertiary>first AFS machine</tertiary>
 133         </indexterm>
 134         <indexterm>
 135           <primary>first AFS machine</primary>
 136           <secondary>Authentication Server</secondary>
 137         </indexterm>
 138         <indexterm>
 139           <primary>kaserver process</primary>
 140           <see>Authentication Server</see>
 141         </indexterm>
 142         <indexterm>
 143           <primary>starting</primary>
 144           <secondary>Authentication Server</secondary>
 145           <tertiary>first AFS machine</tertiary>
 146         </indexterm>
 147
 148         <para>In addition to the database server processes described, you
 149         must also use the <emphasis role="bold">bos create</emphasis> command
 150         to create an entry for the following process, which runs on database
 151         server machines only:
 152         <itemizedlist>
 153           <listitem>
 154             <para>The Authentication Server
 155             (the <emphasis role="bold">kaserver</emphasis> process) maintains
 156             the Authentication Database</para>
 157           </listitem>
 158         </itemizedlist></para>
 159
 160         <para>The following instructions include the
 161         <emphasis role="bold">-cell</emphasis> argument on all applicable
 162         commands. Provide the cell name you assigned in
 163         <link linkend="HDRWQ51">Defining Cell Name and Membership for Server
 164         Processes</link>. If a command appears on multiple lines, it is
 165         only for legibility. The following commands should run before any of
 166         the <emphasis role="bold">bos create</emphasis> commands detailed in
 167         <link linkend="HDRWQ52">Starting the Database Server Processes</link>.
 168         </para>
 169
 170         <orderedlist>
 171           <listitem>
 172             <para>
 173             <indexterm>
 174               <primary>commands</primary>
 175               <secondary>bos create</secondary>
 176             </indexterm>
 177             <indexterm>
 178               <primary>bos commands</primary>
 179               <secondary>create</secondary>
 180             </indexterm>
 181             Issue the <emphasis role="bold">bos create</emphasis>
 182             command to start the Authentication Server. The current
 183             working directory is still
 184             <emphasis role="bold">/usr/afs/bin</emphasis>.
 185 <programlisting>
 186    # <emphasis role="bold">./bos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">kaserver simple /usr/afs/bin/kaserver</emphasis>  \
 187  <emphasis role="bold">                 -cell</emphasis> &lt;<replaceable>cell name</replaceable>&gt;  <emphasis role="bold">-noauth</emphasis>
 188 </programlisting>
 189             </para>
 190
 191             <para>You can safely ignore the messages that tell you to add
 192             Kerberos to the <emphasis role="bold">/etc/services</emphasis>
 193             file; AFS uses a default value that makes the addition
 194             unnecessary. You can also ignore messages about the failure of
 195             authentication.</para>
 196           </listitem>
 197           <listitem>
 198             <para>Return to <link linkend="HDRWQ52">Starting the Database Server
 199             Processes</link> and follow the remaining instructions</para>
 200            </listitem>
 201         </orderedlist>
 202       </sect3>
 203       <sect3 id="KAS007">
 204         <title>Initialising Cell Security with kaserver </title>
 205
 206         <note>
 207           <para>The following instructions should be followed in place of
 208           those in <link linkend="HDRWQ53">Initializing Cell Security</link>
 209           </para>
 210         </note>
 211
 212         <para>Begin by creating the following two initial entries in the
 213         Authentication Database:
 214         <itemizedlist>
 215           <listitem>
 216             <para>A generic administrative account, called
 217             <emphasis role="bold">admin</emphasis> by convention. If you
 218             choose to assign a different name, substitute it throughout the
 219             remainder of this document.</para>
 220
 221             <para>After you complete the installation of the first machine,
 222             you can continue to have all administrators use the
 223             <emphasis role="bold">admin</emphasis> account, or you can create
 224             a separate administrative account for each of them. The latter
 225             scheme implies somewhat more overhead, but provides a more
 226             informative audit trail for administrative operations.</para>
 227           </listitem>
 228
 229           <listitem>
 230             <para>The entry for AFS server processes, called
 231             <emphasis role="bold">afs</emphasis>. No user logs in under this
 232             identity, but the Authentication Server's Ticket Granting Service
 233             (TGS) module uses the associated key to encrypt the server
 234             tickets that it grants to AFS clients for presentation to server
 235             processes during mutual authentication. (The chapter in the
 236             <emphasis>OpenAFS Administration Guide</emphasis> about cell
 237             configuration and administration describes the role of server
 238             encryption keys in mutual authentication.)</para>
 239
 240             <para>In Step <link linkend="AppendixLIWQ58">7</link>, you also
 241             place the initial AFS server encryption key into the <emphasis
 242             role="bold">/usr/afs/etc/KeyFile</emphasis> file. The AFS server
 243             processes refer to this file to learn the server
 244             encryption key when they need to decrypt server tickets.</para>
 245           </listitem>
 246         </itemizedlist>
 247         </para>
 248
 249           <para>You also issue several commands that enable the new
 250           <emphasis role="bold">admin</emphasis> user to issue privileged
 251           commands in all of the AFS suites.</para>
 252
 253           <para>The following instructions do not configure all of the security
 254           mechanisms related to the AFS Backup System. See the chapter in the
 255           <emphasis>OpenAFS Administration Guide</emphasis> about configuring
 256           the Backup System.
 257           <orderedlist>
 258             <indexterm>
 259               <primary>commands</primary>
 260               <secondary>kas (interactive)</secondary>
 261             </indexterm>
 262
 263             <indexterm>
 264               <primary>kas commands</primary>
 265               <secondary>interactive mode, entering</secondary>
 266             </indexterm>
 267
 268             <indexterm>
 269               <primary>interactive mode for kas</primary>
 270               <secondary>entering</secondary>
 271             </indexterm>
 272
 273             <listitem>
 274               <para>Enter <emphasis role="bold">kas</emphasis> interactive
 275               mode. Because the machine is in no-authorization checking
 276               mode, include the <emphasis role="bold">-noauth</emphasis> flag
 277               to suppress the Authentication Server's usual prompt for a
 278               password.
 279 <programlisting>
 280    # <emphasis role="bold">kas  -cell</emphasis> &lt;<replaceable>cell name</replaceable>&gt; <emphasis role="bold">-noauth</emphasis>
 281    ka&gt;
 282 </programlisting>
 283               <indexterm>
 284                 <primary>commands</primary>
 285                 <secondary>kas create</secondary>
 286               </indexterm>
 287               <indexterm>
 288                 <primary>kas commands</primary>
 289                 <secondary>create</secondary>
 290               </indexterm>
 291               <indexterm>
 292                 <primary>server encryption key</primary>
 293                 <secondary>in Authentication Database</secondary>
 294               </indexterm>
 295               <indexterm>
 296                 <primary>creating</primary>
 297                 <secondary>server encryption key</secondary>
 298                 <tertiary>Authentication Database</tertiary>
 299               </indexterm>
 300               </para>
 301             </listitem>
 302
 303             <listitem id="AppendixLIWQ54">
 304               <para>Issue the
 305               <emphasis role="bold">kas create</emphasis> command to create
 306               Authentication Database entries called
 307               <emphasis role="bold">admin</emphasis> and
 308               <emphasis role="bold">afs</emphasis>.</para>
 309
 310               <para>Do not provide passwords on the command line. Instead
 311               provide them as <replaceable>afs_passwd</replaceable> and
 312               <replaceable>admin_passwd</replaceable> in response to the
 313               <emphasis role="bold">kas</emphasis> command interpreter's
 314               prompts as shown, so that they do not appear on the standard
 315               output stream.</para>
 316
 317               <para>You need to enter the <replaceable>afs_passwd</replaceable>
 318               string only in this step and in Step
 319               <link linkend="AppendixLIWQ58">7</link>, so provide a value that
 320               is as long and complex as possible, preferably including numerals,
 321               punctuation characters, and both uppercase and lowercase letters.
 322               Also make the <replaceable>admin_passwd</replaceable> as
 323               long and complex as possible, but keep in mind that
 324               administrators need to enter it often. Both passwords must be
 325               at least six characters long.</para>
 326
 327 <programlisting>
 328    ka&gt; <emphasis role="bold">create afs</emphasis>
 329    initial_password:  <replaceable>afs_passwd</replaceable>
 330    Verifying, please re-enter initial_password: <replaceable>afs_passwd</replaceable>
 331    ka&gt; <emphasis role="bold">create admin</emphasis>
 332    initial_password: <replaceable>admin_passwd</replaceable>
 333    Verifying, please re-enter initial_password: <replaceable>admin_passwd</replaceable>
 334 </programlisting>
 335
 336               <indexterm>
 337                 <primary>commands</primary>
 338                 <secondary>kas examine</secondary>
 339               </indexterm>
 340
 341               <indexterm>
 342                 <primary>kas commands</primary>
 343                 <secondary>examine</secondary>
 344               </indexterm>
 345
 346               <indexterm>
 347                 <primary>displaying</primary>
 348                 <secondary>server encryption key</secondary>
 349                 <tertiary>Authentication Database</tertiary>
 350               </indexterm>
 351             </listitem>
 352
 353             <listitem id="AppendixLIWQ55">
 354               <para>Issue the
 355               <emphasis role="bold">kas examine</emphasis> command to display
 356               the <emphasis role="bold">afs</emphasis> entry. The output
 357               includes a checksum generated by encrypting a constant with the
 358               server encryption key derived from the
 359               <replaceable>afs_passwd</replaceable> string. In
 360               Step <link linkend="AppendixLIWQ59">8</link> you issue the
 361               <emphasis role="bold">bos listkeys</emphasis> command to verify
 362               that the checksum in its output matches the checksum in this
 363               output.
 364 <programlisting>
 365    ka&gt; <emphasis role="bold">examine afs</emphasis>
 366    User data for afs
 367     key (0) cksum is <replaceable>checksum</replaceable> . . .
 368 </programlisting>
 369               <indexterm>
 370                 <primary>commands</primary>
 371                 <secondary>kas setfields</secondary>
 372               </indexterm>
 373               <indexterm>
 374                 <primary>kas commands</primary>
 375                 <secondary>setfields</secondary>
 376               </indexterm>
 377               <indexterm>
 378                 <primary>admin account</primary>
 379                 <secondary>setting ADMIN flag on Auth. DB entry</secondary>
 380               </indexterm>
 381               </para>
 382             </listitem>
 383
 384             <listitem id="LIWQ56">
 385               <para>Issue the
 386               <emphasis role="bold">kas setfields</emphasis> command to turn
 387               on the <computeroutput>ADMIN</computeroutput> flag in the
 388               <emphasis role="bold">admin</emphasis> entry. This enables the
 389               <emphasis role="bold">admin</emphasis> user to issue privileged
 390               <emphasis role="bold">kas</emphasis> commands. Then issue
 391               the <emphasis role="bold">kas examine</emphasis> command to verify
 392               that the <computeroutput>ADMIN</computeroutput> flag
 393               appears in parentheses on the first line of the output, as shown
 394               in the example.
 395 <programlisting>
 396    ka&gt; <emphasis role="bold">setfields admin -flags admin</emphasis>
 397    ka&gt; <emphasis role="bold">examine admin</emphasis>
 398    User data for admin (ADMIN) . . .
 399 </programlisting>
 400               <indexterm>
 401                 <primary>commands</primary>
 402                 <secondary>kas quit</secondary>
 403               </indexterm>
 404               <indexterm>
 405                 <primary>kas commands</primary>
 406                 <secondary>quit</secondary>
 407               </indexterm>
 408               <indexterm>
 409                 <primary>interactive mode for kas</primary>
 410                 <secondary>quitting</secondary>
 411               </indexterm>
 412               </para>
 413             </listitem>
 414
 415             <listitem>
 416               <para>Issue the <emphasis role="bold">kas quit</emphasis>
 417               command to leave <emphasis role="bold">kas</emphasis>
 418               interactive mode.
 419 <programlisting>
 420    ka&gt; <emphasis role="bold">quit</emphasis>
 421 </programlisting>
 422               <indexterm>
 423                 <primary>commands</primary>
 424                 <secondary>bos adduser</secondary>
 425               </indexterm>
 426               <indexterm>
 427                 <primary>bos commands</primary>
 428                 <secondary>adduser</secondary>
 429               </indexterm>
 430               <indexterm>
 431                 <primary>usr/afs/etc/UserList</primary>
 432                 <see>UserList file</see>
 433               </indexterm>
 434               <indexterm>
 435                 <primary>UserList file</primary>
 436                 <secondary>first AFS machine</secondary>
 437               </indexterm>
 438               <indexterm>
 439                 <primary>files</primary>
 440                 <secondary>UserList</secondary>
 441               </indexterm>
 442               <indexterm>
 443                 <primary>creating</primary>
 444                 <secondary>UserList file entry</secondary>
 445               </indexterm>
 446               <indexterm>
 447                 <primary>admin account</primary>
 448                 <secondary>adding</secondary>
 449                 <tertiary>to UserList file</tertiary>
 450               </indexterm>
 451               </para>
 452             </listitem>
 453
 454             <listitem id="AppendixLIWQ57">
 455               <para>Issue the
 456               <emphasis role="bold">bos adduser</emphasis> command to add the
 457               <emphasis role="bold">admin</emphasis> user to the
 458               <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file.
 459               This enables the <emphasis role="bold">admin</emphasis> user to
 460               issue privileged <emphasis role="bold">bos</emphasis> and
 461               <emphasis role="bold">vos</emphasis> commands.
 462 <programlisting>
 463    # <emphasis role="bold">./bos adduser</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">admin -cell</emphasis> &lt;<replaceable>cell name</replaceable>&gt; <emphasis
 464                 role="bold">-noauth</emphasis>
 465 </programlisting>
 466               <indexterm>
 467                 <primary>commands</primary>
 468                 <secondary>bos addkey</secondary>
 469               </indexterm>
 470               <indexterm>
 471                 <primary>bos commands</primary>
 472                 <secondary>addkey</secondary>
 473               </indexterm>
 474               <indexterm>
 475                 <primary>creating</primary>
 476                 <secondary>server encryption key</secondary>
 477                 <tertiary>KeyFile file</tertiary>
 478               </indexterm>
 479               <indexterm>
 480                 <primary>server encryption key</primary>
 481                 <secondary>in KeyFile file</secondary>
 482               </indexterm>
 483               </para>
 484             </listitem>
 485
 486             <listitem id="AppendixLIWQ58">
 487               <para>Issue the
 488               <emphasis role="bold">bos addkey</emphasis> command to define
 489               the AFS server encryption key in the
 490               <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> file.
 491               </para>
 492
 493               <para>Do not provide the password on the command line. Instead
 494               provide it as <replaceable>afs_passwd</replaceable> in
 495               response to the <emphasis role="bold">bos</emphasis> command
 496               interpreter's prompts, as shown. Provide the same string as
 497               in Step <link linkend="AppendixLIWQ54">2</link>.</para>
 498
 499 <programlisting>
 500    # <emphasis role="bold">./bos addkey</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-kvno 0 -cell</emphasis> &lt;<replaceable>cell name</replaceable>&gt;  <emphasis
 501               role="bold">-noauth</emphasis>
 502    Input key: <replaceable>afs_passwd</replaceable>
 503    Retype input key: <replaceable>afs_passwd</replaceable>
 504 </programlisting>
 505
 506               <indexterm>
 507                 <primary>commands</primary>
 508                 <secondary>bos listkeys</secondary>
 509               </indexterm>
 510
 511               <indexterm>
 512                 <primary>bos commands</primary>
 513                 <secondary>listkeys</secondary>
 514               </indexterm>
 515
 516               <indexterm>
 517                 <primary>displaying</primary>
 518                 <secondary>server encryption key</secondary>
 519                 <tertiary>KeyFile file</tertiary>
 520               </indexterm>
 521             </listitem>
 522
 523             <listitem id="AppendixLIWQ59">
 524               <para>Issue the
 525               <emphasis role="bold">bos listkeys</emphasis> command to verify
 526               that the checksum for the new key in the
 527               <emphasis role="bold">KeyFile</emphasis> file is the same as the
 528               checksum for the key in the Authentication Database's
 529               <emphasis role="bold">afs</emphasis> entry, which you displayed
 530               in Step <link linkend="AppendixLIWQ55">3</link>.
 531 <programlisting>
 532    # <emphasis role="bold">./bos listkeys</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-cell</emphasis> &lt;<replaceable>ce
 533 ll name</replaceable>&gt; <emphasis
 534                 role="bold">-noauth</emphasis>
 535    key 0 has cksum <replaceable>checksum</replaceable>
 536 </programlisting></para>
 537
 538               <para>You can safely ignore any error messages indicating that
 539               <emphasis role="bold">bos</emphasis> failed to get tickets
 540               or that authentication failed.</para>
 541
 542               <para>If the keys are different, issue the following commands,
 543               making sure that the <replaceable>afs_passwd</replaceable>
 544               string is the same in each case. The
 545               <replaceable>checksum</replaceable> strings reported by the
 546               <emphasis role="bold">kas examine</emphasis> and
 547               <emphasis role="bold">bos listkeys</emphasis> commands must
 548               match; if they do not, repeat these instructions until they do,
 549               using the <emphasis role="bold">-kvno</emphasis> argument to
 550               increment the key version number each time.</para>
 551
 552 <programlisting>
 553    # <emphasis role="bold">./kas  -cell</emphasis> &lt;<replaceable>cell name</replaceable>&gt; <emphasis role="bold">-noauth</emphasis>
 554    ka&gt; <emphasis role="bold">setpassword afs -kvno 1</emphasis>
 555    new_password: <replaceable>afs_passwd</replaceable>
 556    Verifying, please re-enter initial_password: <replaceable>afs_passwd</replaceable>
 557    ka&gt; <emphasis role="bold">examine afs</emphasis>
 558    User data for afs
 559     key (1) cksum is <replaceable>checksum</replaceable> . . .
 560    ka&gt; <emphasis role="bold">quit</emphasis>
 561    # <emphasis role="bold">./bos addkey</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-kvno 1 -cell</emphasis> &lt;<replaceable>cell name</replaceable>&gt; <emphasis
 562               role="bold">-noauth</emphasis>
 563    Input key: <replaceable>afs_passwd</replaceable>
 564    Retype input key: <replaceable>afs_passwd</replaceable>
 565    # <emphasis role="bold">./bos listkeys</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-cell</emphasis> &lt;<replaceable>cell name</replaceable>&gt; <emphasis
 566               role="bold">-noauth</emphasis>
 567    key 1 has cksum <replaceable>checksum</replaceable>
 568 </programlisting>
 569             </listitem>
 570             <listitem>
 571               <para>Proceed to
 572               <link linkend="HDRWQ53a">Initializing the Protection Database</link>
 573               to continue with the installation process</para>
 574             </listitem>
 575           </orderedlist></para>
 576         </sect3>
 577       </sect2>
 578       <sect2 id="KAS009">
 579         <title>Installing Additional Server Machines</title>
 580
 581         <sect3 id="KAS010">
 582           <title>Starting the Authenticxation Service</title>
 583           <indexterm>
 584             <primary>Authentication Server</primary>
 585             <secondary>starting</secondary>
 586             <tertiary>new db-server machine</tertiary>
 587           </indexterm>
 588           <indexterm>
 589             <primary>starting</primary>
 590             <secondary>Authentication Server</secondary>
 591             <tertiary>new db-server machine</tertiary>
 592           </indexterm>
 593           <para>In addition to the instructions in the main guide, you must
 594           also start the Authentication Server on the new database machine,
 595           as detailed below</para>
 596
 597           <orderedlist>
 598             <listitem id="LIWQ118">
 599               <para>Start the Authentication Server
 600               (the <emphasis role="bold">kaserver</emphasis> process).
 601 <programlisting>
 602    % <emphasis role="bold">bos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">kaserver simple /usr/afs/bin/kaserver</emphasis>
 603 </programlisting> </para>
 604            </listitem>
 605
 606            <listitem>
 607              <para>Return to <link linkend="LIWQ119">starting the backup server</link></para>
 608            </listitem>
 609           </orderedlist>
 610         </sect3>
 611       </sect2>
 612
 613       <sect2 id="KAS011">
 614         <title>Enabling AFS login with kaserver</title>
 615         <para>The authentication system of every machine should be modified so
 616         that users obtain an AFS token as they log into the local file system.
 617         Using AFS is simpler and more convenient for your users if you make the
 618         modifications on all client machines. Otherwise users must perform a two
 619         step login procedure (login to the local system, and then issue the
 620         <emphasis role="bold">klog</emphasis> command.</para>
 621
 622         <para>For convenience, the following sections group this procedure by
 623         system type. Proceed to the appropriate section.
 624           <itemizedlist>
 625             <listitem>
 626               <para>
 627                 <link linkend="KAS012">Enabling AFS Login on AIX Systems</link>
 628               </para>
 629             </listitem>
 630             <listitem>
 631               <para>
 632                 <link linkend="KAS013">Enabling AFS Login on HP-UX Systems</link>
 633               </para>
 634             </listitem>
 635             <listitem>
 636               <para>
 637                 <link linkend="KAS015">Enabling AFS Login on Linux Systems</link>
 638               </para>
 639             </listitem>
 640             <listitem>
 641               <para>
 642                 <link linkend="KAS016">Enabling AFS login on Solaris Systems</link>
 643               </para>
 644             </listitem>
 645           </itemizedlist>
 646         </para>
 647       </sect2>
 648       <sect2 id="KAS012">
 649         <title>Enabling kaserver based AFS login</title>
 650
 651         <para>Now incorporate AFS into the AIX secondary authentication system.
 652           <orderedlist>
 653             <listitem>
 654               <para>Issue the <emphasis role="bold">ls</emphasis> command to
 655               verify that the <emphasis role="bold">afs_dynamic_auth</emphasis>
 656               and <emphasis role="bold">afs_dynamic_kerbauth</emphasis>
 657               programs are installed in the local
 658               <emphasis role="bold">/usr/vice/etc</emphasis> directory.
 659 <programlisting>
 660    # <emphasis role="bold">ls /usr/vice/etc</emphasis>
 661 </programlisting>
 662               </para>
 663
 664               <para>If the files do not exist, unpack the
 665               OpenAFS Binary Distribution for AIX (if it is not already),
 666               change directory as indicated, and copy them.</para>
 667
 668 <programlisting>
 669    # <emphasis role="bold">cd /tmp/afsdist/rs_aix42/dest/root.client/usr/vice/etc</emphasis>
 670    # <emphasis role="bold">cp  -p  afs_dynamic*  /usr/vice/etc</emphasis>
 671 </programlisting>
 672             </listitem>
 673
 674             <listitem>
 675               <para>Edit the local
 676               <emphasis role="bold">/etc/security/user</emphasis> file, making
 677               changes to the indicated stanzas:
 678                 <itemizedlist>
 679                   <listitem>
 680                     <para>In the default stanza, set the
 681                     <computeroutput>registry</computeroutput> attribute to
 682                     <emphasis role="bold">DCE</emphasis> (not to
 683                     <emphasis role="bold">AFS</emphasis>), as follows:
 684 <programlisting>
 685    registry = DCE
 686 </programlisting>
 687                     </para>
 688                   </listitem>
 689
 690                   <listitem>
 691                     <para>In the default stanza, set the
 692                     <computeroutput>SYSTEM</computeroutput> attribute as
 693                     indicated.</para>
 694
 695                     <para>If the machine is an AFS client only, set the
 696                     following value:</para>
 697 <programlisting>
 698    SYSTEM = "AFS OR (AFS[UNAVAIL] AND compat[SUCCESS])"
 699 </programlisting>
 700
 701                     <para>If the machine is both an AFS and a DCE client,
 702                     set the following value (it must appear on a single line in
 703                     the file):</para>
 704 <programlisting>
 705    SYSTEM = "DCE OR DCE[UNAVAIL] OR AFS OR (AFS[UNAVAIL]  \
 706        AND compat[SUCCESS])"
 707 </programlisting>
 708                   </listitem>
 709
 710                   <listitem>
 711                     <para>In the <computeroutput>root</computeroutput>
 712                     stanza, set the <computeroutput>registry</computeroutput>
 713                     attribute as follows. It enables the local superuser
 714                     <emphasis role="bold">root</emphasis> to log into the local
 715                     file system only, based on the password listed in the
 716                     local password file.
 717 <programlisting>
 718    root:
 719          registry = files
 720 </programlisting>
 721                     </para>
 722                   </listitem>
 723                 </itemizedlist>
 724               </para>
 725             </listitem>
 726
 727             <listitem>
 728               <para>Edit the local
 729               <emphasis role="bold">/etc/security/login.cfg</emphasis> file,
 730               creating or editing the indicated stanzas:
 731                 <itemizedlist>
 732                   <listitem>
 733                     <para>In the <computeroutput>DCE</computeroutput> stanza,
 734                     set the <computeroutput>program</computeroutput>
 735                     attribute as follows.</para>
 736
 737                     <para>If you use the AFS Authentication Server
 738                     (<emphasis role="bold">kaserver</emphasis> process):</para>
 739 <programlisting>
 740    DCE:
 741         program = /usr/vice/etc/afs_dynamic_auth
 742 </programlisting>
 743
 744                     <para>If you use a Kerberos v4 implementation of AFS
 745                     authentication:</para>
 746
 747 <programlisting>
 748    DCE:
 749         program = /usr/vice/etc/afs_dynamic_kerbauth
 750 </programlisting>
 751                   </listitem>
 752
 753                   <listitem>
 754                     <para>In the <computeroutput>AFS</computeroutput> stanza,
 755                     set the <computeroutput>program</computeroutput>
 756                     attribute as follows.</para>
 757
 758                     <para>If you use the AFS Authentication Server
 759                     (<emphasis role="bold">kaserver</emphasis> process):</para>
 760 <programlisting>
 761    AFS:
 762         program = /usr/vice/etc/afs_dynamic_auth
 763 </programlisting>
 764
 765                     <para>If you use a Kerberos v4 implementation of AFS
 766                     authentication:</para>
 767 <programlisting>
 768    AFS:
 769         program = /usr/vice/etc/afs_dynamic_kerbauth
 770 </programlisting>
 771                 </listitem>
 772                 </itemizedlist>
 773               </para>
 774             </listitem>
 775             <listitem>
 776               <para>Proceed to
 777               <link linkend="HDRWQ50">Starting the BOS Server</link>,
 778               if you are installing your first file server machine;
 779               <link linkend="HDRWQ108">Starting Server Programs</link>,
 780               if you are installing an additional file server machine; or
 781               <link linkend="HDRWQ145">Loading and Creating Client Files</link>
 782               if you are installating a client</para>
 783             </listitem>
 784           </orderedlist>
 785         </para>
 786       </sect2>
 787       <sect2 id="KAS013">
 788         <title>Enabling kaserver based AFS Login on HP-UX systems</title>
 789
 790         <para>At this point you incorporate AFS into the operating system's
 791         Pluggable Authentication Module (PAM) scheme. PAM integrates all
 792         authentication mechanisms on the machine, including login, to provide
 793         the security infrastructure for authenticated access to and from the
 794         machine.</para>
 795
 796         <para>Explaining PAM is beyond the scope of this document. It is
 797         assumed that you understand the syntax and meanings of settings in the
 798         PAM configuration file (for example, how the
 799         <computeroutput>other</computeroutput> entry works, the effect of
 800         marking an entry as <computeroutput>required</computeroutput>,
 801         <computeroutput>optional</computeroutput>, or
 802         <computeroutput>sufficient</computeroutput>, and so on).</para>
 803
 804         <para>The following instructions explain how to alter the entries in
 805         the PAM configuration file for each service for which you
 806         wish to use AFS authentication. Other configurations possibly also
 807         work, but the instructions specify the recommended and
 808         tested configuration.</para>
 809
 810         <note>
 811           <para>The instructions specify that you mark each entry as
 812           <computeroutput>optional</computeroutput>. However, marking some
 813           modules as optional can mean that they grant access to the
 814           corresponding service even when the user does not meet all of the
 815           module's requirements. In some operating system revisions, for
 816           example, if you mark as optional the module that controls
 817           login via a dial-up connection, it allows users to login without
 818           providing a password. See the <emphasis>OpenAFS Release
 819           Notes</emphasis> for a discussion of any limitations that apply to
 820           this operating system.</para>
 821
 822           <para>Also, with some operating system versions you must install
 823           patches for PAM to interact correctly with certain
 824           authentication programs. For details, see the
 825           <emphasis>OpenAFS Release Notes</emphasis>.</para>
 826         </note>
 827
 828         <para>The recommended AFS-related entries in the PAM configuration
 829         file make use of one or more of the following three
 830         attributes.
 831         <variablelist>
 832           <varlistentry>
 833             <term><emphasis role="bold"><computeroutput>try_first_pass</computeroutput></emphasis></term>
 834
 835             <listitem>
 836               <para>This is a standard PAM attribute that can be included on
 837               entries after the first one for a service; it directs
 838               the module to use the password that was provided to the first
 839               module. For the AFS module, it means that AFS
 840               authentication succeeds if the password provided to the module
 841               listed first is the user's correct AFS password. For
 842               further discussion of this attribute and its alternatives, see
 843               the operating system's PAM documentation.</para>
 844             </listitem>
 845           </varlistentry>
 846
 847           <varlistentry>
 848             <term><emphasis role="bold"><computeroutput>ignore_root</computeroutput></emphasis></term>
 849
 850             <listitem>
 851               <para>This attribute, specific to the AFS PAM module, directs it
 852               to ignore not only the local superuser <emphasis
 853               role="bold">root</emphasis>, but also any user with UID 0
 854               (zero).</para>
 855             </listitem>
 856           </varlistentry>
 857
 858           <varlistentry>
 859             <term><emphasis role="bold"><computeroutput>setenv_password_expires</computeroutput></emphasis></term>
 860
 861             <listitem>
 862               <para>This attribute, specific to the AFS PAM module, sets the
 863               environment variable PASSWORD_EXPIRES to the expiration
 864               date of the user's AFS password, which is recorded in the
 865               Authentication Database.</para>
 866             </listitem>
 867           </varlistentry>
 868         </variablelist>
 869         </para>
 870
 871         <para>Perform the following steps to enable AFS login.
 872         <orderedlist>
 873           <listitem>
 874             <para>Unpack the OpenAFS Binary Distribution for HP-UX into the
 875             <emphasis role="bold">/tmp/afsdist</emphasis> directory, if it is
 876             not already.
 877             Then change directory as indicated.
 878 <programlisting>
 879    # <emphasis role="bold">cd /usr/lib/security</emphasis>
 880 </programlisting></para>
 881           </listitem>
 882
 883           <listitem>
 884             <para>Copy the AFS authentication library file to the
 885             <emphasis role="bold">/usr/lib/security</emphasis> directory. Then
 886             create a symbolic link to it whose name does not mention the
 887             version. Omitting the version eliminates the need to edit
 888             the PAM configuration file if you later update the library
 889             file.</para>
 890
 891             <para>If you use the AFS Authentication Server
 892             (<emphasis role="bold">kaserver</emphasis> process) in the cell:</para>
 893
 894 <programlisting>
 895    # <emphasis role="bold">cp /tmp/afsdist/hp_ux110/dest/lib/pam_afs.so.1  .</emphasis>
 896    # <emphasis role="bold">ln -s  pam_afs.so.1  pam_afs.so</emphasis>
 897 </programlisting>
 898
 899             <para>If you use a Kerberos implementation of AFS authentication:</para>
 900
 901 <programlisting>
 902    # <emphasis role="bold">cp /tmp/afsdist/hp_ux110/dest/lib/pam_afs.krb.so.1   .</emphasis>
 903    # <emphasis role="bold">ln -s pam_afs.krb.so.1 pam_afs.so</emphasis>
 904 </programlisting>
 905           </listitem>
 906
 907           <listitem>
 908             <para>Edit the
 909             <computeroutput>Authentication management</computeroutput>
 910             section of the HP-UX PAM configuration file,
 911             <emphasis role="bold">/etc/pam.conf</emphasis> by convention. The
 912             entries in this section have the value
 913             <computeroutput>auth</computeroutput> in their second field.</para>
 914
 915             <para>First edit the standard entries, which refer to the
 916             HP-UX PAM module (usually, the file <emphasis
 917             role="bold">/usr/lib/security/libpam_unix.1</emphasis>) in their
 918             fourth field. For each service for which you want to
 919             use AFS authentication, edit the third field of its entry to read
 920             <computeroutput>optional</computeroutput>. The
 921             <emphasis role="bold">pam.conf</emphasis> file in the HP-UX
 922             distribution usually includes standard entries for the
 923             <emphasis role="bold">login</emphasis> and
 924             <emphasis role="bold">ftp</emphasis> services, for instance.</para>
 925
 926             <para>If there are services for which you want to use AFS
 927             authentication, but for which the <emphasis
 928             role="bold">pam.conf</emphasis> file does not already include a
 929             standard entry, you must create that entry and place the
 930             value <computeroutput>optional</computeroutput> in its third field.
 931             For instance, the HP-UX <emphasis role="bold">pam.conf</emphasis>
 932             file does not usually include standard entries for the <emphasis
 933             role="bold">remsh</emphasis> or
 934             <emphasis role="bold">telnet</emphasis> services.</para>
 935
 936             <para>Then create an AFS-related entry for each service, placing it
 937             immediately below the standard entry. The following
 938             example shows what the
 939             <computeroutput>Authentication Management</computeroutput> section
 940             looks like after you have you
 941             edited or created entries for the services mentioned previously.
 942             Note that the example AFS entries appear on two lines
 943             only for legibility.</para>
 944
 945 <programlisting>
 946    login   auth  optional  /usr/lib/security/libpam_unix.1
 947    login   auth  optional  /usr/lib/security/pam_afs.so      \
 948          try_first_pass  ignore_root  setenv_password_expires
 949    ftp     auth  optional  /usr/lib/security/libpam_unix.1
 950    ftp     auth  optional  /usr/lib/security/pam_afs.so      \
 951          try_first_pass  ignore_root
 952    remsh   auth  optional  /usr/lib/security/libpam_unix.1
 953    remsh   auth  optional  /usr/lib/security/pam_afs.so      \
 954          try_first_pass  ignore_root
 955    telnet  auth  optional  /usr/lib/security/libpam_unix.1
 956    telnet  auth  optional  /usr/lib/security/pam_afs.so      \
 957          try_first_pass  ignore_root  setenv_password_expires
 958 </programlisting>
 959           </listitem>
 960
 961           <listitem>
 962             <para>If you use the Common Desktop Environment (CDE) on the
 963             machine and want users to obtain an AFS token as they log
 964             in, also add or edit the following four entries in the
 965             <computeroutput>Authentication management</computeroutput>
 966             section. Note that the AFS-related entries appear on two lines
 967             here only for legibility.
 968 <programlisting>
 969    dtlogin   auth  optional  /usr/lib/security/libpam_unix.1
 970    dtlogin   auth  optional  /usr/lib/security/pam_afs.so     \
 971          try_first_pass  ignore_root
 972    dtaction  auth  optional  /usr/lib/security/libpam_unix.1
 973    dtaction  auth  optional  /usr/lib/security/pam_afs.so     \
 974          try_first_pass  ignore_root
 975 </programlisting></para>
 976           </listitem>
 977
 978           <listitem>
 979             <para>Proceed to
 980             <link linkend="HDRWQ50">Starting the BOS Server</link> if you
 981             are installing your first file server;
 982             <link linkend="HDRWQ108">Starting Server Programs</link> if you
 983             are installing an additional file server machine; or
 984             <link linkend="HDRWQ145">Loading and Creating Client Files.</link>
 985             if you are installing a client.</para>
 986           </listitem>
 987         </orderedlist>
 988         </para>
 989       </sect2>
 990       <sect2 id="KAS015">
 991         <title>Enabling kaserver based AFS Login on Linux Systems</title>
 992
 993         <para>At this point you incorporate AFS into the operating system's
 994         Pluggable Authentication Module (PAM) scheme. PAM integrates all
 995         authentication mechanisms on the machine, including login, to provide
 996         the security infrastructure for authenticated access to and from the
 997         machine.</para>
 998
 999         <para>Explaining PAM is beyond the scope of this document. It is
1000         assumed that you understand the syntax and meanings of settings in the
1001         PAM configuration file (for example, how the
1002         <computeroutput>other</computeroutput> entry works, the effect of
1003         marking an entry as <computeroutput>required</computeroutput>,
1004         <computeroutput>optional</computeroutput>, or
1005         <computeroutput>sufficient</computeroutput>, and so on).</para>
1006
1007         <para>The following instructions explain how to alter the entries in
1008         the PAM configuration file for each service for which you
1009         wish to use AFS authentication. Other configurations possibly also
1010         work, but the instructions specify the recommended and
1011         tested configuration.</para>
1012
1013         <para>The recommended AFS-related entries in the PAM configuration
1014         file make use of one or more of the following three
1015         attributes.
1016         <variablelist>
1017           <title>Authentication Management</title>
1018
1019           <varlistentry>
1020             <term><emphasis role="bold"><computeroutput>try_first_pass</computeroutput></emphasis></term>
1021
1022             <listitem>
1023               <para>This is a standard PAM attribute that can be included on
1024               entries after the first one for a service; it directs
1025               the module to use the password that was provided to the first
1026               module. For the AFS module, it means that AFS
1027               authentication succeeds if the password provided to the module
1028               listed first is the user's correct AFS password. For
1029               further discussion of this attribute and its alternatives, see
1030               the operating system's PAM documentation.</para>
1031             </listitem>
1032           </varlistentry>
1033
1034           <varlistentry>
1035             <term><emphasis role="bold"><computeroutput>ignore_root</computeroutput></emphasis></term>
1036
1037             <listitem>
1038               <para>This attribute, specific to the AFS PAM module, directs it
1039               to ignore not only the local superuser <emphasis
1040               role="bold">root</emphasis>, but also any user with UID
1041               0 (zero).</para>
1042             </listitem>
1043           </varlistentry>
1044
1045           <varlistentry>
1046             <term><emphasis role="bold"><computeroutput>ignore_uid </computeroutput><emphasis>uid</emphasis></emphasis></term>
1047
1048             <listitem>
1049               <para>This option is an extension of the "ignore_root" switch.
1050               The additional parameter is a limit. Users with a uid
1051               up to the given parameter are ignored by
1052               <emphasis>pam_afs.so</emphasis>. Thus, a system administrator
1053               still has the
1054               opportunity to add local user accounts to his system by choosing
1055               between "low" and "high" user ids. An example
1056               /etc/passwd file for "ignore_uid 100" may have entries like these:
1057 <programlisting>
1058         .
1059         .
1060 afsuserone:x:99:100::/afs/afscell/u/afsuserone:/bin/bash
1061 afsusertwo:x:100:100::/afs/afscell/u/afsusertwo:/bin/bash
1062 localuserone:x:101:100::/home/localuserone:/bin/bash
1063 localusertwo:x:102:100::/home/localusertwo:/bin/bash
1064         .
1065         .
1066 </programlisting>
1067               AFS accounts should be locked in the file /etc/shadow like this:
1068 <programlisting>
1069         .
1070         .
1071 afsuserone:!!:11500:0:99999:7:::
1072 afsusertwo:!!:11500:0:99999:7:::
1073 localuserone:&lt;thelocaluserone'skey&gt;:11500:0:99999:7:::
1074 localusertwo:&lt;thelocalusertwo'skey&gt;:11500:0:99999:7:::
1075         .
1076         .
1077 </programlisting>
1078               There is no need to store a local key in this file since the AFS
1079               password is sent and verfied at the AFS cell server!</para>
1080             </listitem>
1081           </varlistentry>
1082
1083           <varlistentry>
1084             <term><emphasis role="bold"><computeroutput>setenv_password_expires</computeroutput></emphasis></term>
1085
1086             <listitem>
1087               <para>This attribute, specific to the AFS PAM module, sets the
1088               environment variable PASSWORD_EXPIRES to the expiration
1089               date of the user's AFS password, which is recorded in the
1090               Authentication Database.</para>
1091             </listitem>
1092           </varlistentry>
1093
1094           <varlistentry>
1095             <term><emphasis role="bold"><computeroutput>set_token</computeroutput></emphasis></term>
1096
1097             <listitem>
1098               <para>Some applications don't call
1099               <emphasis>pam_setcred()</emphasis> in order to retrieve the
1100               appropriate credentials (here the AFS token) for their session.
1101               This switch sets the credentials already in
1102               <emphasis>pam_sm_authenticate()</emphasis> obsoleting a call to
1103               <emphasis>pam_setcred()</emphasis>. <emphasis
1104               role="bold">Caution: Don't use this switch for applications which
1105               do call <emphasis>pam_setcred()</emphasis>!</emphasis> One
1106               example for an application not calling
1107               <emphasis>pam_setcred()</emphasis> are older versions of the
1108               samba server. Nevertheless, using applications with
1109               working pam session management is recommended as this setup
1110               conforms better with the PAM definitions.</para>
1111             </listitem>
1112           </varlistentry>
1113
1114           <varlistentry>
1115             <term><emphasis role="bold"><computeroutput>refresh_token</computeroutput></emphasis></term>
1116
1117             <listitem>
1118               <para>This options is identical to "set_token" except that no
1119               new PAG is generated. This is necessary to handle
1120               processes like xlock or xscreensaver. It is not enough to just
1121               unlock the screen for a user who
1122               reactivated his session by typing in the correct AFS password, but
1123               one may also need fresh tokens with a full lifetime in
1124               order to work on, and the new token must be refreshed in the
1125               already existing PAG for the processes that have been
1126               started. This is achieved using this option.</para>
1127             </listitem>
1128           </varlistentry>
1129
1130           <varlistentry>
1131             <term><emphasis role="bold"><computeroutput>use_klog</computeroutput></emphasis></term>
1132
1133             <listitem>
1134               <para>Activating this switch causes authentication to be done by
1135               calling the external program "klog". One program requiring
1136               this is for example <emphasis>kdm</emphasis> of KDE 2.x.</para>
1137             </listitem>
1138           </varlistentry>
1139
1140           <varlistentry>
1141             <term><emphasis role="bold"><computeroutput>dont_fork</computeroutput></emphasis></term>
1142
1143             <listitem>
1144               <para>Usually, the password verification and token establishment
1145               is performed in a sub process. Using this option pam_afs does not
1146               fork and performs all actions in a single process.
1147               <emphasis role="bold">Only use this option in cases where you
1148               notice serious problems caused by the sub process.</emphasis>
1149               This option has been developed in respect to
1150               the "mod_auth_pam"-project (see also
1151               <ulink url="http://pam.sourceforge.net/mod_auth_pam/">mod_auth_pam</ulink>).
1152               The mod_auth_pam module enables PAM authentication for the apache
1153               http server package.</para>
1154             </listitem>
1155           </varlistentry>
1156         </variablelist>
1157         <variablelist>
1158           <title>Session Management</title>
1159
1160           <varlistentry>
1161             <term><emphasis role="bold"><computeroutput>no_unlog</computeroutput></emphasis></term>
1162
1163             <listitem>
1164               <para>Normally the tokens are deleted (in memory) after the
1165               session ends. Using this option causes the tokens to be left
1166               untouched. <emphasis role="bold">This behaviour was the default
1167               in pam_afs until openafs-1.1.1!</emphasis></para>
1168             </listitem>
1169           </varlistentry>
1170
1171           <varlistentry>
1172             <term><emphasis role="bold"><computeroutput>remainlifetime</computeroutput> <emphasis>sec</emphasis></emphasis></term>
1173
1174             <listitem>
1175               <para>The tokens are kept active for <emphasis>sec</emphasis>
1176               seconds before they are deleted. X display managers i.e.
1177               are used to inform the applications started in the X session
1178               before the logout and then end themselves. If the token
1179               was deleted immediately the applications would have no chance
1180               to write back their settings to i.e. the user's AFS home
1181               space. This option may help to avoid the problem.</para>
1182             </listitem>
1183           </varlistentry>
1184         </variablelist></para>
1185
1186       <para>Perform the following steps to enable AFS login.
1187         <orderedlist>
1188           <listitem>
1189             <para>Unpack the OpenAFS Binary Distribution for Linux into the
1190             <emphasis role="bold">/tmp/afsdist/</emphasis> directory, if it is
1191             not already.
1192             Then change to the directory for PAM modules, which depends on which Linux distribution you are using.</para>
1193
1194             <para>If you are using a Linux distribution from Red Hat Software:</para>
1195
1196             <programlisting>
1197    # <emphasis role="bold">cd /lib/security</emphasis>
1198 </programlisting>
1199
1200             <para>If you are using another Linux distribution:</para>
1201
1202             <programlisting>
1203    # <emphasis role="bold">cd /usr/lib/security</emphasis>
1204 </programlisting>
1205           </listitem>
1206
1207           <listitem>
1208             <para>Copy the appropriate AFS authentication library file to the
1209             directory to which you changed in the previous step.
1210             Create a symbolic link whose name does not mention the version.
1211             Omitting the version eliminates the need to edit the PAM
1212             configuration file if you later update the library file.</para>
1213
1214             <para>If you use the AFS Authentication Server
1215             (<emphasis role="bold">kaserver</emphasis> process):</para>
1216 <programlisting>
1217    # <emphasis role="bold">cp /cdrom/i386_linux22/lib/pam_afs.so.1  .</emphasis>
1218    # <emphasis role="bold">ln -s pam_afs.so.1 pam_afs.so</emphasis>
1219 </programlisting>
1220
1221             <para>If you use a Kerberos implementation of AFS
1222             authentication:</para>
1223 <programlisting>
1224    # <emphasis role="bold">cp /cdrom/i386_linux22/lib/pam_afs.krb.so.1   .</emphasis>
1225    # <emphasis role="bold">ln -s pam_afs.krb.so.1 pam_afs.so</emphasis>
1226 </programlisting>
1227           </listitem>
1228
1229           <listitem>
1230             <para>For each service with which you want to use AFS
1231             authentication, insert an entry for the AFS PAM module into the
1232             <computeroutput>auth</computeroutput> section of the service's
1233             PAM configuration file. (Linux uses a separate
1234             configuration file for each service, unlike some other operating
1235             systems which list all services in a single file.) Mark
1236             the entry as <computeroutput>sufficient</computeroutput> in the
1237             second field.</para>
1238
1239             <para>Place the AFS entry below any entries that impose conditions
1240             under which you want the service to fail for a user
1241             who does not meet the entry's requirements. Mark these entries
1242             <computeroutput>required</computeroutput>. Place the AFS
1243             entry above any entries that need to execute only if AFS
1244             authentication fails.</para>
1245
1246             <para>Insert the following AFS entry if using the Red Hat
1247             distribution:</para>
1248 <programlisting>
1249    auth  sufficient  /lib/security/pam_afs.so   try_first_pass  ignore_root
1250 </programlisting>
1251
1252             <para>Insert the following AFS entry if using another
1253             distribution:</para>
1254
1255 <programlisting>
1256    auth  sufficient  /usr/lib/security/pam_afs.so  try_first_pass  ignore_root
1257 </programlisting>
1258
1259             <para>Check the PAM config files also for "session" entries. If
1260             there are lines beginning with "session" then please
1261             insert this line too:</para>
1262
1263 <programlisting>
1264    session  optional  /lib/security/pam_afs.so
1265 </programlisting>
1266
1267             <para>or</para>
1268
1269 <programlisting>
1270    session  optional  /usr/lib/security/pam_afs.so
1271 </programlisting>
1272
1273             <para>This guarantees that the user's tokens are deleted from
1274             memory after his session ends so that no other user
1275             coincidently gets those tokens without authorization! The
1276             following examples illustrate the recommended configuration of
1277             the configuration file for several services:
1278               <variablelist>
1279                 <title>Authentication Management</title>
1280
1281                 <varlistentry>
1282                   <term>(<emphasis role="bold">/etc/pam.d/login</emphasis>)</term>
1283
1284                   <listitem>
1285                     <para>
1286 <programlisting>
1287    #%PAM-1.0
1288    auth      required   /lib/security/pam_securetty.so
1289    auth      required   /lib/security/pam_nologin.so
1290    auth      sufficient /lib/security/pam_afs.so try_first_pass ignore_root
1291    #                                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1292    #This enables AFS authentication for every user but root
1293    auth      required   /lib/security/pam_pwdb.so shadow nullok
1294    account   required   /lib/security/pam_pwdb.so
1295    password  required   /lib/security/pam_cracklib.so
1296    password  required   /lib/security/pam_pwdb.so shadow nullok use_authtok
1297    session   optional   /lib/security/pam_afs.so
1298    #Make sure tokens are deleted after the user logs out
1299    session   required   /lib/security/pam_pwdb.so
1300 </programlisting>
1301                     </para>
1302                   </listitem>
1303                 </varlistentry>
1304
1305                 <varlistentry>
1306                   <term>(<emphasis role="bold">/etc/pam.d/samba</emphasis>)</term>
1307
1308                   <listitem>
1309                     <para>
1310 <programlisting>
1311    auth       required     /lib/security/pam_afs.so ignore_uid 100 set_token
1312    #                                                ^^^^^^^^^^^^^^^^^^^^^^^^
1313    #Here, users with uid&gt;100 are considered to belong to the AFS and users
1314    #with uid&lt;=100 are ignored by pam_afs. The token is retrieved already in
1315    #pam_sm_authenticate() (this is an example pam config for a samba version
1316    #that does not call pam_setcred(), it also does no sense to include session
1317    #entries here since they would be ignored by this version of samba ).
1318    account    required     /lib/security/pam_pwdb.so
1319 </programlisting>
1320                     </para>
1321                   </listitem>
1322                 </varlistentry>
1323
1324                 <varlistentry>
1325                   <term>(<emphasis role="bold">/etc/pam.d/xscreensaver</emphasis>)</term>
1326
1327                   <listitem>
1328                     <para>
1329 <programlisting>
1330    auth       sufficient   /lib/security/pam_afs.so ignore_uid 100 refresh_token
1331    #                                                               ^^^^^^^^^^^^^
1332    #Avoid generating a new PAG for the new tokens, use the already existing PAG and
1333    #establish a fresh token in it.
1334    auth       required     /lib/security/pam_pwdb.so try_first_pass
1335 </programlisting>
1336                     </para>
1337                   </listitem>
1338                 </varlistentry>
1339
1340                 <varlistentry>
1341                   <term>(<emphasis role="bold">/etc/pam.d/httpd</emphasis>)</term>
1342
1343                   <listitem>
1344                     <para>
1345 <programlisting>
1346    auth       required   /lib/security/pam_afs.so ignore_uid 100 dont_fork
1347    #                                                             ^^^^^^^^^
1348    #Don't fork for the verification of the password.
1349 </programlisting>
1350                     </para>
1351                   </listitem>
1352                 </varlistentry>
1353               </variablelist>
1354               <variablelist>
1355                 <title>Session Management</title>
1356
1357                 <varlistentry>
1358                   <term>(<emphasis role="bold">/etc/pam.d/su</emphasis>)</term>
1359
1360                   <listitem>
1361                     <para>
1362 <programlisting>
1363    auth       sufficient   /lib/security/pam_afs.so ignore_uid 100
1364    auth       required     /lib/security/pam_pwdb.so try_first_pass
1365    account    required     /lib/security/pam_pwdb.so
1366    password   required     /lib/security/pam_cracklib.so
1367    password   required     /lib/security/pam_pwdb.so use_authtok
1368    session    required     /lib/security/pam_pwdb.so
1369    session    optional     /lib/security/pam_afs.so no_unlog
1370    #                                                ^^^^^^^^
1371    #Don't delete the token in this case, since the user may still
1372    #need it (for example if somebody logs in and changes to root
1373    #afterwards he may still want to access his home space in AFS).
1374    session    required     /lib/security/pam_login_access.so
1375    session    optional     /lib/security/pam_xauth.so
1376 </programlisting>
1377                     </para>
1378                   </listitem>
1379                 </varlistentry>
1380
1381                 <varlistentry>
1382                   <term>(<emphasis role="bold">/etc/pam.d/xdm</emphasis>)</term>
1383
1384                   <listitem>
1385                     <para>
1386 <programlisting>
1387    auth       required     /lib/security/pam_nologin.so
1388    auth       required     /lib/security/pam_login_access.so
1389    auth       sufficient   /lib/security/pam_afs.so ignore_uid 100 use_klog
1390    auth       required     /lib/security/pam_pwdb.so try_first_pass
1391    account    required     /lib/security/pam_pwdb.so
1392    password   required     /lib/security/pam_cracklib.so
1393    password   required     /lib/security/pam_pwdb.so shadow nullok use_authtok
1394    session    optional     /lib/security/pam_afs.so remainlifetime 10
1395    #                                                ^^^^^^^^^^^^^^^^^
1396    #Wait 10 seconds before deleting the AFS tokens in order to give
1397    #the programs of the X session some time to save their settings
1398    #to AFS.
1399    session    required     /lib/security/pam_pwdb.so
1400 </programlisting>
1401                      </para>
1402                   </listitem>
1403                 </varlistentry>
1404               </variablelist></para>
1405           </listitem>
1406           <listitem>
1407             <para>After taking any necessary action, proceed to
1408             <link linkend="HDRWQ50">Starting the BOS Server</link> if you
1409             are installing your first file server;
1410             <link linkend="HDRWQ108">Starting Server Programs</link> if you
1411             are installing an additional file server machine; or
1412             <link linkend="HDRWQ145">Loading and Creating Client Files</link> if you are installing a client.
1413             </para>
1414           </listitem>
1415         </orderedlist>
1416       </para>
1417     </sect2>
1418     <sect2 id="KAS016">
1419       <title>Enabling kaserver based AFS Login on Solaris Systems</title>
1420
1421       <para>At this point you incorporate AFS into the operating system's
1422       Pluggable Authentication Module (PAM) scheme. PAM
1423       integrates all authentication mechanisms on the machine, including
1424       login, to provide the security infrastructure for
1425       authenticated access to and from the machine.</para>
1426
1427       <para>Explaining PAM is beyond the scope of this document. It is
1428       assumed that you understand the syntax and meanings of
1429       settings in the PAM configuration file (for example, how the
1430       <computeroutput>other</computeroutput> entry works, the effect of
1431       marking an entry as <computeroutput>required</computeroutput>,
1432       <computeroutput>optional</computeroutput>, or
1433       <computeroutput>sufficient</computeroutput>, and so on).</para>
1434
1435       <para>The following instructions explain how to alter the entries in the
1436       PAM configuration file for each service for which you
1437       wish to use AFS authentication. Other configurations possibly also
1438       work, but the instructions specify the recommended and
1439       tested configuration.</para>
1440
1441       <note>
1442         <para>The instructions specify that you mark each entry as
1443         <computeroutput>optional</computeroutput>. However, marking some
1444         modules as optional can mean that they grant access to the
1445         corresponding service even when the user does not meet all of the
1446         module's requirements. In some operating system revisions,
1447         for example, if you mark as optional the module that controls
1448         login via a dial-up connection, it allows users to login without
1449         providing a password. See the <emphasis>OpenAFS Release
1450         Notes</emphasis> for a discussion of any limitations that apply to
1451         this operating system.</para>
1452
1453         <para>Also, with some operating system versions you must install
1454         patches for PAM to interact correctly with certain
1455         authentication programs. For details, see the
1456         <emphasis>OpenAFS Release Notes</emphasis>.</para>
1457       </note>
1458
1459       <para>The recommended AFS-related entries in the PAM configuration file
1460       make use of one or more of the following three
1461       attributes.
1462         <variablelist>
1463           <title>Authentication Management</title>
1464
1465           <varlistentry>
1466             <term><emphasis role="bold"><computeroutput>try_first_pass</computeroutput></emphasis></term>
1467
1468             <listitem>
1469               <para>This is a standard PAM attribute that can be included on
1470               entries after the first one for a service; it directs
1471               the module to use the password that was provided to the first
1472               module. For the AFS module, it means that AFS
1473               authentication succeeds if the password provided to the module
1474               listed first is the user's correct AFS password. For
1475               further discussion of this attribute and its alternatives, see
1476               the operating system's PAM documentation.</para>
1477             </listitem>
1478           </varlistentry>
1479
1480           <varlistentry>
1481             <term><emphasis role="bold"><computeroutput>ignore_root</computeroutput></emphasis></term>
1482
1483             <listitem>
1484               <para>This attribute, specific to the AFS PAM module, directs it
1485               to ignore not only the local superuser <emphasis
1486               role="bold">root</emphasis>, but also any user with UID 0
1487               (zero).</para>
1488             </listitem>
1489           </varlistentry>
1490
1491           <varlistentry>
1492             <term><emphasis role="bold"><computeroutput>setenv_password_expires</computeroutput></emphasis></term>
1493
1494             <listitem>
1495               <para>This attribute, specific to the AFS PAM module, sets the
1496               environment variable PASSWORD_EXPIRES to the expiration
1497               date of the user's AFS password, which is recorded in the
1498               Authentication Database.</para>
1499             </listitem>
1500           </varlistentry>
1501         </variablelist></para>
1502
1503       <para>Perform the following steps to enable AFS login. <orderedlist>
1504           <listitem>
1505             <para>Unpack the OpenAFS Binary Distribution for Solaris into the
1506             <emphasis role="bold">/cdrom</emphasis> directory, if it is not
1507             already.
1508             Then change directory as indicated.
1509 <programlisting>
1510    # <emphasis role="bold">cd /usr/lib/security</emphasis>
1511 </programlisting></para>
1512           </listitem>
1513
1514           <listitem>
1515             <para>Copy the AFS authentication library file to the
1516             <emphasis role="bold">/usr/lib/security</emphasis> directory. Then
1517             create a symbolic link to it whose name does not mention the
1518             version. Omitting the version eliminates the need to edit
1519             the PAM configuration file if you later update the library
1520             file.</para>
1521
1522             <para>If you use the AFS Authentication Server
1523             (<emphasis role="bold">kaserver</emphasis> process):</para>
1524
1525 <programlisting>
1526    # <emphasis role="bold">cp /tmp/afsdist/sun4x_56/dest/lib/pam_afs.so.1 .</emphasis>
1527    # <emphasis role="bold">ln -s pam_afs.so.1 pam_afs.so</emphasis>
1528 </programlisting>
1529
1530             <para>If you use a Kerberos implementation of AFS authentication:</para>
1531
1532 <programlisting>
1533    # <emphasis role="bold">cp /tmp/afsdist/sun4x_56/dest/lib/pam_afs.krb.so.1 .</emphasis>
1534    # <emphasis role="bold">ln -s pam_afs.krb.so.1 pam_afs.so</emphasis>
1535 </programlisting>
1536           </listitem>
1537
1538           <listitem>
1539             <para>Edit the
1540             <computeroutput>Authentication management</computeroutput> section
1541             of the Solaris PAM configuration file,
1542             <emphasis role="bold">/etc/pam.conf</emphasis> by convention.
1543             The entries in this section have the value
1544             <computeroutput>auth</computeroutput> in their second field.</para>
1545
1546             <para>First edit the standard entries, which refer to the
1547             Solaris PAM module (usually, the file <emphasis
1548             role="bold">/usr/lib/security/pam_unix.so.1</emphasis>) in their
1549             fourth field. For each service for which you want to
1550             use AFS authentication, edit the third field of its entry to read
1551             <computeroutput>optional</computeroutput>. The
1552             <emphasis role="bold">pam.conf</emphasis> file in the Solaris
1553             distribution usually includes standard entries for the
1554             <emphasis role="bold">login</emphasis>,
1555             <emphasis role="bold">rlogin</emphasis>, and <emphasis
1556             role="bold">rsh</emphasis> services, for instance.</para>
1557
1558             <para>If there are services for which you want to use AFS
1559             authentication, but for which the <emphasis
1560             role="bold">pam.conf</emphasis> file does not already include a
1561             standard entry, you must create that entry and place the
1562             value <computeroutput>optional</computeroutput> in its third field.
1563             For instance, the Solaris
1564             <emphasis role="bold">pam.conf</emphasis> file does not usually
1565             include standard entries for the
1566             <emphasis role="bold">ftp</emphasis> or
1567             <emphasis role="bold">telnet</emphasis> services.</para>
1568
1569             <para>Then create an AFS-related entry for each service, placing it
1570             immediately below the standard entry. The following
1571             example shows what the
1572             <computeroutput>Authentication Management</computeroutput>
1573             section looks like after you have you edited or created entries
1574             for the services mentioned previously. Note that the example AFS
1575             entries appear on two lines
1576             only for legibility.</para>
1577
1578 <programlisting>
1579    login   auth  optional  /usr/lib/security/pam_unix.so.1
1580    login   auth  optional  /usr/lib/security/pam_afs.so       \
1581          try_first_pass  ignore_root  setenv_password_expires
1582    rlogin  auth  optional  /usr/lib/security/pam_unix.so.1
1583    rlogin  auth  optional  /usr/lib/security/pam_afs.so       \
1584          try_first_pass  ignore_root  setenv_password_expires
1585    rsh     auth  optional  /usr/lib/security/pam_unix.so.1
1586    rsh     auth  optional  /usr/lib/security/pam_afs.so       \
1587          try_first_pass  ignore_root
1588    ftp     auth  optional  /usr/lib/security/pam_unix.so.1
1589    ftp     auth  optional  /usr/lib/security/pam_afs.so       \
1590          try_first_pass  ignore_root
1591    telnet  auth  optional  /usr/lib/security/pam_unix.so.1
1592    telnet  auth  optional  /usr/lib/security/pam_afs.so       \
1593          try_first_pass  ignore_root  setenv_password_expires
1594 </programlisting>
1595           </listitem>
1596
1597           <listitem>
1598             <para>If you use the Common Desktop Environment (CDE) on the
1599             machine and want users to obtain an AFS token as they log
1600             in, also add or edit the following four entries in the
1601             <computeroutput>Authentication management</computeroutput>
1602             section. Note that the AFS-related entries appear on two lines
1603             here only for legibility.
1604 <programlisting>
1605    dtlogin   auth  optional  /usr/lib/security/pam_unix.so.1
1606    dtlogin   auth  optional  /usr/lib/security/pam_afs.so     \
1607          try_first_pass  ignore_root
1608    dtsession  auth  optional /usr/lib/security/pam_unix.so.1
1609    dtsession  auth  optional /usr/lib/security/pam_afs.so     \
1610          try_first_pass  ignore_root
1611 </programlisting>
1612             </para>
1613           </listitem>
1614           <listitem>
1615             <para>Proceed to
1616             <link linkend="HDRWQ49a">Editing the File Systems Clean-up Script
1617             on Solaris Systems in the server instructions </link> if you are
1618             installing your first file server;
1619             <link linkend="HDRWQ108">Starting Server Programs</link> if you
1620             are installing an additional file server machine; or
1621             <link linkend="Header_137a">Editing the File Systems Clean-up Script
1622             on Solaris Systems in the client instructions</link> if you are
1623             installing a client.</para>
1624           </listitem>
1625         </orderedlist>
1626       </para>
1627     </sect2>
1628   </sect1>
1629 </appendix>