quickstart-obsolete-appendices-20070423
[openafs.git] / 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>
304               <para><anchor id="AppendixLIWQ54" />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>
354               <para><anchor id="AppendixLIWQ55" />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>
385               <para><anchor id="LIWQ56" />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>
455               <para><anchor id="AppendixLIWQ57" />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>
487               <para><anchor id="AppendixLIWQ58" />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>
524               <para><anchor id="AppendixLIWQ59" />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>
599               <para><anchor id="LIWQ118" />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="KAS014">Enabling AFS Login on IRIX Systems</link>
638               </para>
639             </listitem>
640             <listitem>
641               <para>
642                 <link linkend="KAS015">Enabling AFS Login on Linux Systems</link>
643               </para>
644             </listitem>
645             <listitem>
646               <para>
647                 <link linkend="KAS016">Enabling AFS login on Solaris Systems</link>
648               </para>
649             </listitem>
650           </itemizedlist>
651         </para>
652       </sect2>
653       <sect2 id="KAS012">
654         <title>Enabling kaserver based AFS login</title>
655                 
656         <para>Now incorporate AFS into the AIX secondary authentication system. 
657           <orderedlist>
658             <listitem>
659               <para>Issue the <emphasis role="bold">ls</emphasis> command to 
660               verify that the <emphasis role="bold">afs_dynamic_auth</emphasis> 
661               and <emphasis role="bold">afs_dynamic_kerbauth</emphasis> 
662               programs are installed in the local 
663               <emphasis role="bold">/usr/vice/etc</emphasis> directory. 
664 <programlisting>
665    # <emphasis role="bold">ls /usr/vice/etc</emphasis>   
666 </programlisting>
667               </para>
668
669               <para>If the files do not exist, unpack the 
670               OpenAFS Binary Distribution for AIX (if it is not already), 
671               change directory as indicated, and copy them.</para>
672
673 <programlisting>
674    # <emphasis role="bold">cd /tmp/afsdist/rs_aix42/root.client/usr/vice/etc</emphasis>
675    # <emphasis role="bold">cp  -p  afs_dynamic*  /usr/vice/etc</emphasis>
676 </programlisting>
677             </listitem>
678
679             <listitem>
680               <para>Edit the local 
681               <emphasis role="bold">/etc/security/user</emphasis> file, making 
682               changes to the indicated stanzas:
683                 <itemizedlist>
684                   <listitem>
685                     <para>In the default stanza, set the 
686                     <computeroutput>registry</computeroutput> attribute to 
687                     <emphasis role="bold">DCE</emphasis> (not to 
688                     <emphasis role="bold">AFS</emphasis>), as follows: 
689 <programlisting>
690    registry = DCE
691 </programlisting>
692                     </para>
693                   </listitem>
694
695                   <listitem>
696                     <para>In the default stanza, set the 
697                     <computeroutput>SYSTEM</computeroutput> attribute as 
698                     indicated.</para>
699
700                     <para>If the machine is an AFS client only, set the 
701                     following value:</para>
702 <programlisting>
703    SYSTEM = "AFS OR (AFS[UNAVAIL] AND compat[SUCCESS])"   
704 </programlisting>
705
706                     <para>If the machine is both an AFS and a DCE client, 
707                     set the following value (it must appear on a single line in
708                     the file):</para>
709 <programlisting>
710    SYSTEM = "DCE OR DCE[UNAVAIL] OR AFS OR (AFS[UNAVAIL]  \
711        AND compat[SUCCESS])"
712 </programlisting>
713                   </listitem>
714
715                   <listitem>
716                     <para>In the <computeroutput>root</computeroutput> 
717                     stanza, set the <computeroutput>registry</computeroutput>
718                     attribute as follows. It enables the local superuser 
719                     <emphasis role="bold">root</emphasis> to log into the local
720                     file system only, based on the password listed in the 
721                     local password file. 
722 <programlisting>
723    root:
724          registry = files
725 </programlisting>
726                     </para>
727                   </listitem>
728                 </itemizedlist>
729               </para>
730             </listitem>
731
732             <listitem>
733               <para>Edit the local 
734               <emphasis role="bold">/etc/security/login.cfg</emphasis> file, 
735               creating or editing the indicated stanzas: 
736                 <itemizedlist>
737                   <listitem>
738                     <para>In the <computeroutput>DCE</computeroutput> stanza, 
739                     set the <computeroutput>program</computeroutput>
740                     attribute as follows.</para>
741
742                     <para>If you use the AFS Authentication Server 
743                     (<emphasis role="bold">kaserver</emphasis> process):</para>
744 <programlisting>
745    DCE:
746         program = /usr/vice/etc/afs_dynamic_auth   
747 </programlisting>
748
749                     <para>If you use a Kerberos v4 implementation of AFS 
750                     authentication:</para>
751
752 <programlisting>
753    DCE:
754         program = /usr/vice/etc/afs_dynamic_kerbauth
755 </programlisting>
756                   </listitem>
757
758                   <listitem>
759                     <para>In the <computeroutput>AFS</computeroutput> stanza, 
760                     set the <computeroutput>program</computeroutput>
761                     attribute as follows.</para>
762
763                     <para>If you use the AFS Authentication Server 
764                     (<emphasis role="bold">kaserver</emphasis> process):</para>
765 <programlisting>
766    AFS:
767         program = /usr/vice/etc/afs_dynamic_auth   
768 </programlisting>
769
770                     <para>If you use a Kerberos v4 implementation of AFS 
771                     authentication:</para>
772 <programlisting>
773    AFS:
774         program = /usr/vice/etc/afs_dynamic_kerbauth
775 </programlisting>
776                 </listitem>
777                 </itemizedlist>
778               </para>
779             </listitem>
780             <listitem>
781               <para>Proceed to 
782               <link linkend="HDRWQ50">Starting the BOS Server</link>,
783               if you are installing your first file server machine;
784               <link linkend="HDRWQ108">Starting Server Programs</link>, 
785               if you are installing an additional file server machine; or
786               <link linkend="HDRWQ145">Loading and Creating Client Files</link>
787               if you are installating a client</para>
788             </listitem>
789           </orderedlist>
790         </para>
791       </sect2>
792       <sect2 id="KAS013">
793         <title>Enabling kaserver based AFS Login on HP-UX systems</title>
794         
795         <para>At this point you incorporate AFS into the operating system's 
796         Pluggable Authentication Module (PAM) scheme. PAM integrates all 
797         authentication mechanisms on the machine, including login, to provide 
798         the security infrastructure for authenticated access to and from the 
799         machine.</para>
800
801         <para>Explaining PAM is beyond the scope of this document. It is 
802         assumed that you understand the syntax and meanings of settings in the 
803         PAM configuration file (for example, how the 
804         <computeroutput>other</computeroutput> entry works, the effect of
805         marking an entry as <computeroutput>required</computeroutput>, 
806         <computeroutput>optional</computeroutput>, or
807         <computeroutput>sufficient</computeroutput>, and so on).</para>
808
809         <para>The following instructions explain how to alter the entries in 
810         the PAM configuration file for each service for which you
811         wish to use AFS authentication. Other configurations possibly also 
812         work, but the instructions specify the recommended and
813         tested configuration.</para>
814
815         <note>
816           <para>The instructions specify that you mark each entry as 
817           <computeroutput>optional</computeroutput>. However, marking some
818           modules as optional can mean that they grant access to the 
819           corresponding service even when the user does not meet all of the
820           module's requirements. In some operating system revisions, for 
821           example, if you mark as optional the module that controls
822           login via a dial-up connection, it allows users to login without 
823           providing a password. See the <emphasis>OpenAFS Release
824           Notes</emphasis> for a discussion of any limitations that apply to 
825           this operating system.</para>
826
827           <para>Also, with some operating system versions you must install 
828           patches for PAM to interact correctly with certain
829           authentication programs. For details, see the 
830           <emphasis>OpenAFS Release Notes</emphasis>.</para>
831         </note>
832
833         <para>The recommended AFS-related entries in the PAM configuration 
834         file make use of one or more of the following three
835         attributes. 
836         <variablelist>
837           <varlistentry>
838             <term><emphasis role="bold"><computeroutput>try_first_pass</computeroutput></emphasis></term>
839
840             <listitem>
841               <para>This is a standard PAM attribute that can be included on 
842               entries after the first one for a service; it directs
843               the module to use the password that was provided to the first 
844               module. For the AFS module, it means that AFS
845               authentication succeeds if the password provided to the module 
846               listed first is the user's correct AFS password. For
847               further discussion of this attribute and its alternatives, see 
848               the operating system's PAM documentation.</para>
849             </listitem>
850           </varlistentry>
851
852           <varlistentry>
853             <term><emphasis role="bold"><computeroutput>ignore_root</computeroutput></emphasis></term>
854
855             <listitem>
856               <para>This attribute, specific to the AFS PAM module, directs it 
857               to ignore not only the local superuser <emphasis
858               role="bold">root</emphasis>, but also any user with UID 0 
859               (zero).</para>
860             </listitem>
861           </varlistentry>
862
863           <varlistentry>
864             <term><emphasis role="bold"><computeroutput>setenv_password_expires</computeroutput></emphasis></term>
865
866             <listitem>
867               <para>This attribute, specific to the AFS PAM module, sets the 
868               environment variable PASSWORD_EXPIRES to the expiration
869               date of the user's AFS password, which is recorded in the 
870               Authentication Database.</para>
871             </listitem>
872           </varlistentry>
873         </variablelist>
874         </para>
875
876         <para>Perform the following steps to enable AFS login. 
877         <orderedlist>
878           <listitem>
879             <para>Unpack the OpenAFS Binary Distribution for HP-UX into the 
880             <emphasis role="bold">/tmp/afsdist</emphasis> directory, if it is 
881             not already.
882             Then change directory as indicated. 
883 <programlisting>
884    # <emphasis role="bold">cd /usr/lib/security</emphasis>
885 </programlisting></para>
886           </listitem>
887
888           <listitem>
889             <para>Copy the AFS authentication library file to the 
890             <emphasis role="bold">/usr/lib/security</emphasis> directory. Then
891             create a symbolic link to it whose name does not mention the 
892             version. Omitting the version eliminates the need to edit
893             the PAM configuration file if you later update the library 
894             file.</para>
895
896             <para>If you use the AFS Authentication Server 
897             (<emphasis role="bold">kaserver</emphasis> process) in the cell:</para>
898
899 <programlisting>
900    # <emphasis role="bold">cp /tmp/afsdist/hp_ux110/lib/pam_afs.so.1  .</emphasis>
901    # <emphasis role="bold">ln -s  pam_afs.so.1  pam_afs.so</emphasis>   
902 </programlisting>
903
904             <para>If you use a Kerberos implementation of AFS authentication:</para>
905
906 <programlisting>
907    # <emphasis role="bold">cp /tmp/afsdist/hp_ux110/lib/pam_afs.krb.so.1   .</emphasis>
908    # <emphasis role="bold">ln -s pam_afs.krb.so.1 pam_afs.so</emphasis>
909 </programlisting>
910           </listitem>
911
912           <listitem>
913             <para>Edit the 
914             <computeroutput>Authentication management</computeroutput> 
915             section of the HP-UX PAM configuration file,
916             <emphasis role="bold">/etc/pam.conf</emphasis> by convention. The 
917             entries in this section have the value
918             <computeroutput>auth</computeroutput> in their second field.</para>
919
920             <para>First edit the standard entries, which refer to the 
921             HP-UX PAM module (usually, the file <emphasis
922             role="bold">/usr/lib/security/libpam_unix.1</emphasis>) in their 
923             fourth field. For each service for which you want to
924             use AFS authentication, edit the third field of its entry to read 
925             <computeroutput>optional</computeroutput>. The
926             <emphasis role="bold">pam.conf</emphasis> file in the HP-UX 
927             distribution usually includes standard entries for the
928             <emphasis role="bold">login</emphasis> and 
929             <emphasis role="bold">ftp</emphasis> services, for instance.</para>
930
931             <para>If there are services for which you want to use AFS 
932             authentication, but for which the <emphasis
933             role="bold">pam.conf</emphasis> file does not already include a 
934             standard entry, you must create that entry and place the
935             value <computeroutput>optional</computeroutput> in its third field. 
936             For instance, the HP-UX <emphasis role="bold">pam.conf</emphasis> 
937             file does not usually include standard entries for the <emphasis
938             role="bold">remsh</emphasis> or 
939             <emphasis role="bold">telnet</emphasis> services.</para>
940
941             <para>Then create an AFS-related entry for each service, placing it 
942             immediately below the standard entry. The following
943             example shows what the 
944             <computeroutput>Authentication Management</computeroutput> section 
945             looks like after you have you
946             edited or created entries for the services mentioned previously. 
947             Note that the example AFS entries appear on two lines
948             only for legibility.</para>
949
950 <programlisting>
951    login   auth  optional  /usr/lib/security/libpam_unix.1
952    login   auth  optional  /usr/lib/security/pam_afs.so      \
953          try_first_pass  ignore_root  setenv_password_expires
954    ftp     auth  optional  /usr/lib/security/libpam_unix.1
955    ftp     auth  optional  /usr/lib/security/pam_afs.so      \
956          try_first_pass  ignore_root
957    remsh   auth  optional  /usr/lib/security/libpam_unix.1
958    remsh   auth  optional  /usr/lib/security/pam_afs.so      \
959          try_first_pass  ignore_root            
960    telnet  auth  optional  /usr/lib/security/libpam_unix.1
961    telnet  auth  optional  /usr/lib/security/pam_afs.so      \
962          try_first_pass  ignore_root  setenv_password_expires
963 </programlisting>
964           </listitem>
965
966           <listitem>
967             <para>If you use the Common Desktop Environment (CDE) on the 
968             machine and want users to obtain an AFS token as they log
969             in, also add or edit the following four entries in the 
970             <computeroutput>Authentication management</computeroutput>
971             section. Note that the AFS-related entries appear on two lines 
972             here only for legibility. 
973 <programlisting>
974    dtlogin   auth  optional  /usr/lib/security/libpam_unix.1
975    dtlogin   auth  optional  /usr/lib/security/pam_afs.so     \
976          try_first_pass  ignore_root
977    dtaction  auth  optional  /usr/lib/security/libpam_unix.1
978    dtaction  auth  optional  /usr/lib/security/pam_afs.so     \
979          try_first_pass  ignore_root
980 </programlisting></para>
981           </listitem>
982           
983           <listitem>
984             <para>Proceed to 
985             <link linkend="HDRWQ50">Starting the BOS Server</link> if you
986             are installing your first file server;
987             <link linkend="HDRWQ108">Starting Server Programs</link> if you
988             are installing an additional file server machine; or
989             <link linkend="HDRWQ145">Loading and Creating Client Files.</link> 
990             if you are installing a client.</para>
991           </listitem>
992         </orderedlist>
993         </para>
994       </sect2>
995       <sect2 id="KAS014">
996         <title>Enabling kaserver based AFS Login on IRIX Systems</title>
997         
998         <para>The standard IRIX command-line 
999         <emphasis role="bold">login</emphasis> program and the graphical 
1000         <emphasis role="bold">xdm</emphasis> login program both automatically 
1001         grant an AFS token when AFS is incorporated into the machine's
1002         kernel. However, some IRIX distributions use another login utility by 
1003         default, and it does not necessarily incorporate the required AFS 
1004         modifications. If that is the case, you must disable the default 
1005         utility if you want AFS users to obtain AFS tokens at login. For 
1006         further discussion, see the 
1007         <emphasis>OpenAFS Release Notes</emphasis>.</para>
1008
1009         <para>If you configure the machine to use an AFS-modified login 
1010         utility, then the <emphasis role="bold">afsauthlib.so</emphasis> and 
1011         <emphasis role="bold">afskauthlib.so</emphasis> files (included in the 
1012         AFS distribution) must reside in the 
1013         <emphasis role="bold">/usr/vice/etc</emphasis> directory. Issue the 
1014         <emphasis role="bold">ls</emphasis> command to verify.</para>
1015
1016 <programlisting>
1017    # <emphasis role="bold">ls /usr/vice/etc</emphasis>   
1018 </programlisting>
1019
1020         <para>If the files do not exist, unpack the OpenAFS Binary Distribution
1021         for IRIX (if it is not already), change directory as indicated, and copy
1022         them.</para>
1023
1024 <programlisting>
1025    # <emphasis role="bold">cd /tmp/afsdist/sgi_65/root.client/usr/vice/etc</emphasis>
1026    # <emphasis role="bold">cp  -p  *authlib*  /usr/vice/etc</emphasis>   
1027 </programlisting>
1028
1029         <para>After taking any necessary action, proceed to 
1030         <link linkend="HDRWQ50">Starting the BOS Server</link> if you
1031         are installing your first file server;
1032         <link linkend="HDRWQ108">Starting Server Programs</link> if you
1033         are installing an additional file server machine; or
1034         <link linkend="HDRWQ145">Loading and Creating Client Files</link> 
1035         if you are installing a client.</para>
1036       </sect2>
1037       <sect2 id="KAS015">
1038         <title>Enabling kaserver based AFS Login on Linux Systems</title>
1039         
1040         <para>At this point you incorporate AFS into the operating system's 
1041         Pluggable Authentication Module (PAM) scheme. PAM integrates all 
1042         authentication mechanisms on the machine, including login, to provide 
1043         the security infrastructure for authenticated access to and from the 
1044         machine.</para>
1045
1046         <para>Explaining PAM is beyond the scope of this document. It is 
1047         assumed that you understand the syntax and meanings of settings in the 
1048         PAM configuration file (for example, how the 
1049         <computeroutput>other</computeroutput> entry works, the effect of
1050         marking an entry as <computeroutput>required</computeroutput>, 
1051         <computeroutput>optional</computeroutput>, or
1052         <computeroutput>sufficient</computeroutput>, and so on).</para>
1053
1054         <para>The following instructions explain how to alter the entries in 
1055         the PAM configuration file for each service for which you
1056         wish to use AFS authentication. Other configurations possibly also 
1057         work, but the instructions specify the recommended and
1058         tested configuration.</para>
1059
1060         <para>The recommended AFS-related entries in the PAM configuration 
1061         file make use of one or more of the following three
1062         attributes. 
1063         <variablelist>
1064           <title>Authentication Management</title>
1065
1066           <varlistentry>
1067             <term><emphasis role="bold"><computeroutput>try_first_pass</computeroutput></emphasis></term>
1068
1069             <listitem>
1070               <para>This is a standard PAM attribute that can be included on 
1071               entries after the first one for a service; it directs
1072               the module to use the password that was provided to the first 
1073               module. For the AFS module, it means that AFS
1074               authentication succeeds if the password provided to the module 
1075               listed first is the user's correct AFS password. For
1076               further discussion of this attribute and its alternatives, see 
1077               the operating system's PAM documentation.</para>
1078             </listitem>
1079           </varlistentry>
1080
1081           <varlistentry>
1082             <term><emphasis role="bold"><computeroutput>ignore_root</computeroutput></emphasis></term>
1083
1084             <listitem>
1085               <para>This attribute, specific to the AFS PAM module, directs it 
1086               to ignore not only the local superuser <emphasis
1087               role="bold">root</emphasis>, but also any user with UID 
1088               0 (zero).</para>
1089             </listitem>
1090           </varlistentry>
1091
1092           <varlistentry>
1093             <term><emphasis role="bold"><computeroutput>ignore_uid </computeroutput><emphasis>uid</emphasis></emphasis></term>
1094
1095             <listitem>
1096               <para>This option is an extension of the "ignore_root" switch. 
1097               The additional parameter is a limit. Users with a uid
1098               up to the given parameter are ignored by 
1099               <emphasis>pam_afs.so</emphasis>. Thus, a system administrator 
1100               still has the
1101               opportunity to add local user accounts to his system by choosing 
1102               between "low" and "high" user ids. An example
1103               /etc/passwd file for "ignore_uid 100" may have entries like these: 
1104 <programlisting>
1105         .
1106         .
1107 afsuserone:x:99:100::/afs/afscell/u/afsuserone:/bin/bash
1108 afsusertwo:x:100:100::/afs/afscell/u/afsusertwo:/bin/bash
1109 localuserone:x:101:100::/home/localuserone:/bin/bash
1110 localusertwo:x:102:100::/home/localusertwo:/bin/bash
1111         .
1112         .
1113 </programlisting> 
1114               AFS accounts should be locked in the file /etc/shadow like this: 
1115 <programlisting>
1116         .
1117         .
1118 afsuserone:!!:11500:0:99999:7:::
1119 afsusertwo:!!:11500:0:99999:7:::
1120 localuserone:&lt;thelocaluserone'skey&gt;:11500:0:99999:7:::
1121 localusertwo:&lt;thelocalusertwo'skey&gt;:11500:0:99999:7:::
1122         .
1123         .
1124 </programlisting> 
1125               There is no need to store a local key in this file since the AFS 
1126               password is sent and verfied at the AFS cell server!</para>
1127             </listitem>
1128           </varlistentry>
1129
1130           <varlistentry>
1131             <term><emphasis role="bold"><computeroutput>setenv_password_expires</computeroutput></emphasis></term>
1132
1133             <listitem>
1134               <para>This attribute, specific to the AFS PAM module, sets the 
1135               environment variable PASSWORD_EXPIRES to the expiration
1136               date of the user's AFS password, which is recorded in the 
1137               Authentication Database.</para>
1138             </listitem>
1139           </varlistentry>
1140
1141           <varlistentry>
1142             <term><emphasis role="bold"><computeroutput>set_token</computeroutput></emphasis></term>
1143
1144             <listitem>
1145               <para>Some applications don't call 
1146               <emphasis>pam_setcred()</emphasis> in order to retrieve the 
1147               appropriate credentials (here the AFS token) for their session. 
1148               This switch sets the credentials already in
1149               <emphasis>pam_sm_authenticate()</emphasis> obsoleting a call to 
1150               <emphasis>pam_setcred()</emphasis>. <emphasis
1151               role="bold">Caution: Don't use this switch for applications which 
1152               do call <emphasis>pam_setcred()</emphasis>!</emphasis> One 
1153               example for an application not calling
1154               <emphasis>pam_setcred()</emphasis> are older versions of the 
1155               samba server. Nevertheless, using applications with
1156               working pam session management is recommended as this setup 
1157               conforms better with the PAM definitions.</para>
1158             </listitem>
1159           </varlistentry>
1160
1161           <varlistentry>
1162             <term><emphasis role="bold"><computeroutput>refresh_token</computeroutput></emphasis></term>
1163
1164             <listitem>
1165               <para>This options is identical to "set_token" except that no 
1166               new PAG is generated. This is necessary to handle
1167               processes like xlock or xscreensaver. It is not enough to just
1168               unlock the screen for a user who
1169               reactivated his session by typing in the correct AFS password, but 
1170               one may also need fresh tokens with a full lifetime in
1171               order to work on, and the new token must be refreshed in the 
1172               already existing PAG for the processes that have been
1173               started. This is achieved using this option.</para>
1174             </listitem>
1175           </varlistentry>
1176
1177           <varlistentry>
1178             <term><emphasis role="bold"><computeroutput>use_klog</computeroutput></emphasis></term>
1179
1180             <listitem>
1181               <para>Activating this switch causes authentication to be done by 
1182               calling the external program "klog". One program requiring
1183               this is for example <emphasis>kdm</emphasis> of KDE 2.x.</para>
1184             </listitem>
1185           </varlistentry>
1186
1187           <varlistentry>
1188             <term><emphasis role="bold"><computeroutput>dont_fork</computeroutput></emphasis></term>
1189
1190             <listitem>
1191               <para>Usually, the password verification and token establishment 
1192               is performed in a sub process. Using this option pam_afs does not 
1193               fork and performs all actions in a single process. 
1194               <emphasis role="bold">Only use this option in cases where you 
1195               notice serious problems caused by the sub process.</emphasis> 
1196               This option has been developed in respect to
1197               the "mod_auth_pam"-project (see also 
1198               <ulink url="http://pam.sourceforge.net/mod_auth_pam/">mod_auth_pam</ulink>). 
1199               The mod_auth_pam module enables PAM authentication for the apache 
1200               http server package.</para>
1201             </listitem>
1202           </varlistentry>
1203         </variablelist> 
1204         <variablelist>
1205           <title>Session Management</title>
1206
1207           <varlistentry>
1208             <term><emphasis role="bold"><computeroutput>no_unlog</computeroutput></emphasis></term>
1209
1210             <listitem>
1211               <para>Normally the tokens are deleted (in memory) after the 
1212               session ends. Using this option causes the tokens to be left
1213               untouched. <emphasis role="bold">This behaviour was the default 
1214               in pam_afs until openafs-1.1.1!</emphasis></para>
1215             </listitem>
1216           </varlistentry>
1217
1218           <varlistentry>
1219             <term><emphasis role="bold"><computeroutput>remainlifetime</computeroutput> <emphasis>sec</emphasis></emphasis></term>
1220
1221             <listitem>
1222               <para>The tokens are kept active for <emphasis>sec</emphasis> 
1223               seconds before they are deleted. X display managers i.e.
1224               are used to inform the applications started in the X session 
1225               before the logout and then end themselves. If the token
1226               was deleted immediately the applications would have no chance 
1227               to write back their settings to i.e. the user's AFS home
1228               space. This option may help to avoid the problem.</para>
1229             </listitem>
1230           </varlistentry>
1231         </variablelist></para>
1232
1233       <para>Perform the following steps to enable AFS login. 
1234         <orderedlist>
1235           <listitem>
1236             <para>Unpack the OpenAFS Binary Distribution for Linux into the 
1237             <emphasis role="bold">/tmp/afsdist/</emphasis> directory, if it is 
1238             not already.
1239             Then change to the directory for PAM modules, which depends on which Linux distribution you are using.</para>
1240
1241             <para>If you are using a Linux distribution from Red Hat Software:</para>
1242
1243             <programlisting>
1244    # <emphasis role="bold">cd /lib/security</emphasis>
1245 </programlisting>
1246
1247             <para>If you are using another Linux distribution:</para>
1248
1249             <programlisting>
1250    # <emphasis role="bold">cd /usr/lib/security</emphasis>
1251 </programlisting>
1252           </listitem>
1253
1254           <listitem>
1255             <para>Copy the appropriate AFS authentication library file to the 
1256             directory to which you changed in the previous step.
1257             Create a symbolic link whose name does not mention the version. 
1258             Omitting the version eliminates the need to edit the PAM
1259             configuration file if you later update the library file.</para>
1260
1261             <para>If you use the AFS Authentication Server 
1262             (<emphasis role="bold">kaserver</emphasis> process):</para>
1263 <programlisting>
1264    # <emphasis role="bold">cp /cdrom/i386_linux22/lib/pam_afs.so.1  .</emphasis>
1265    # <emphasis role="bold">ln -s pam_afs.so.1 pam_afs.so</emphasis>
1266 </programlisting>
1267
1268             <para>If you use a Kerberos implementation of AFS 
1269             authentication:</para>
1270 <programlisting>
1271    # <emphasis role="bold">cp /cdrom/i386_linux22/lib/pam_afs.krb.so.1   .</emphasis>
1272    # <emphasis role="bold">ln -s pam_afs.krb.so.1 pam_afs.so</emphasis>
1273 </programlisting>
1274           </listitem>
1275
1276           <listitem>
1277             <para>For each service with which you want to use AFS 
1278             authentication, insert an entry for the AFS PAM module into the
1279             <computeroutput>auth</computeroutput> section of the service's 
1280             PAM configuration file. (Linux uses a separate
1281             configuration file for each service, unlike some other operating 
1282             systems which list all services in a single file.) Mark
1283             the entry as <computeroutput>sufficient</computeroutput> in the 
1284             second field.</para>
1285
1286             <para>Place the AFS entry below any entries that impose conditions 
1287             under which you want the service to fail for a user
1288             who does not meet the entry's requirements. Mark these entries 
1289             <computeroutput>required</computeroutput>. Place the AFS
1290             entry above any entries that need to execute only if AFS 
1291             authentication fails.</para>
1292
1293             <para>Insert the following AFS entry if using the Red Hat 
1294             distribution:</para>
1295 <programlisting>
1296    auth  sufficient  /lib/security/pam_afs.so   try_first_pass  ignore_root
1297 </programlisting>
1298
1299             <para>Insert the following AFS entry if using another 
1300             distribution:</para>
1301
1302 <programlisting>
1303    auth  sufficient  /usr/lib/security/pam_afs.so  try_first_pass  ignore_root
1304 </programlisting>
1305
1306             <para>Check the PAM config files also for "session" entries. If 
1307             there are lines beginning with "session" then please
1308             insert this line too:</para>
1309
1310 <programlisting>
1311    session  optional  /lib/security/pam_afs.so
1312 </programlisting>
1313
1314             <para>or</para>
1315
1316 <programlisting>
1317    session  optional  /usr/lib/security/pam_afs.so
1318 </programlisting>
1319
1320             <para>This guarantees that the user's tokens are deleted from 
1321             memory after his session ends so that no other user
1322             coincidently gets those tokens without authorization! The 
1323             following examples illustrate the recommended configuration of
1324             the configuration file for several services: 
1325               <variablelist>
1326                 <title>Authentication Management</title>
1327
1328                 <varlistentry>
1329                   <term>(<emphasis role="bold">/etc/pam.d/login</emphasis>)</term>
1330
1331                   <listitem>
1332                     <para>
1333 <programlisting>
1334    #%PAM-1.0
1335    auth      required   /lib/security/pam_securetty.so
1336    auth      required   /lib/security/pam_nologin.so
1337    auth      sufficient /lib/security/pam_afs.so try_first_pass ignore_root
1338    #                                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1339    #This enables AFS authentication for every user but root
1340    auth      required   /lib/security/pam_pwdb.so shadow nullok
1341    account   required   /lib/security/pam_pwdb.so
1342    password  required   /lib/security/pam_cracklib.so
1343    password  required   /lib/security/pam_pwdb.so shadow nullok use_authtok
1344    session   optional   /lib/security/pam_afs.so
1345    #Make sure tokens are deleted after the user logs out
1346    session   required   /lib/security/pam_pwdb.so
1347 </programlisting>
1348                     </para>
1349                   </listitem>
1350                 </varlistentry>
1351
1352                 <varlistentry>
1353                   <term>(<emphasis role="bold">/etc/pam.d/samba</emphasis>)</term>
1354
1355                   <listitem>
1356                     <para>
1357 <programlisting>
1358    auth       required     /lib/security/pam_afs.so ignore_uid 100 set_token
1359    #                                                ^^^^^^^^^^^^^^^^^^^^^^^^
1360    #Here, users with uid&gt;100 are considered to belong to the AFS and users
1361    #with uid&lt;=100 are ignored by pam_afs. The token is retrieved already in
1362    #pam_sm_authenticate() (this is an example pam config for a samba version
1363    #that does not call pam_setcred(), it also does no sense to include session
1364    #entries here since they would be ignored by this version of samba ).
1365    account    required     /lib/security/pam_pwdb.so
1366 </programlisting>
1367                     </para>
1368                   </listitem>
1369                 </varlistentry>
1370
1371                 <varlistentry>
1372                   <term>(<emphasis role="bold">/etc/pam.d/xscreensaver</emphasis>)</term>
1373
1374                   <listitem>
1375                     <para>
1376 <programlisting>
1377    auth       sufficient   /lib/security/pam_afs.so ignore_uid 100 refresh_token
1378    #                                                               ^^^^^^^^^^^^^
1379    #Avoid generating a new PAG for the new tokens, use the already existing PAG and
1380    #establish a fresh token in it.
1381    auth       required     /lib/security/pam_pwdb.so try_first_pass
1382 </programlisting>
1383                     </para>
1384                   </listitem>
1385                 </varlistentry>
1386
1387                 <varlistentry>
1388                   <term>(<emphasis role="bold">/etc/pam.d/httpd</emphasis>)</term>
1389
1390                   <listitem>
1391                     <para>
1392 <programlisting>
1393    auth       required   /lib/security/pam_afs.so ignore_uid 100 dont_fork
1394    #                                                             ^^^^^^^^^
1395    #Don't fork for the verification of the password.
1396 </programlisting>
1397                     </para>
1398                   </listitem>
1399                 </varlistentry>
1400               </variablelist>
1401               <variablelist>
1402                 <title>Session Management</title>
1403
1404                 <varlistentry>
1405                   <term>(<emphasis role="bold">/etc/pam.d/su</emphasis>)</term>
1406
1407                   <listitem>
1408                     <para>
1409 <programlisting>
1410    auth       sufficient   /lib/security/pam_afs.so ignore_uid 100
1411    auth       required     /lib/security/pam_pwdb.so try_first_pass
1412    account    required     /lib/security/pam_pwdb.so
1413    password   required     /lib/security/pam_cracklib.so
1414    password   required     /lib/security/pam_pwdb.so use_authtok
1415    session    required     /lib/security/pam_pwdb.so
1416    session    optional     /lib/security/pam_afs.so no_unlog
1417    #                                                ^^^^^^^^
1418    #Don't delete the token in this case, since the user may still
1419    #need it (for example if somebody logs in and changes to root
1420    #afterwards he may still want to access his home space in AFS).
1421    session    required     /lib/security/pam_login_access.so
1422    session    optional     /lib/security/pam_xauth.so
1423 </programlisting>
1424                     </para>
1425                   </listitem>
1426                 </varlistentry>
1427
1428                 <varlistentry>
1429                   <term>(<emphasis role="bold">/etc/pam.d/xdm</emphasis>)</term>
1430
1431                   <listitem>
1432                     <para>
1433 <programlisting>
1434    auth       required     /lib/security/pam_nologin.so
1435    auth       required     /lib/security/pam_login_access.so
1436    auth       sufficient   /lib/security/pam_afs.so ignore_uid 100 use_klog
1437    auth       required     /lib/security/pam_pwdb.so try_first_pass
1438    account    required     /lib/security/pam_pwdb.so
1439    password   required     /lib/security/pam_cracklib.so
1440    password   required     /lib/security/pam_pwdb.so shadow nullok use_authtok
1441    session    optional     /lib/security/pam_afs.so remainlifetime 10
1442    #                                                ^^^^^^^^^^^^^^^^^
1443    #Wait 10 seconds before deleting the AFS tokens in order to give
1444    #the programs of the X session some time to save their settings
1445    #to AFS.
1446    session    required     /lib/security/pam_pwdb.so
1447 </programlisting>
1448                      </para>
1449                   </listitem>
1450                 </varlistentry>
1451               </variablelist></para>
1452           </listitem>
1453           <listitem>        
1454             <para>After taking any necessary action, proceed to 
1455             <link linkend="HDRWQ50">Starting the BOS Server</link> if you
1456             are installing your first file server;
1457             <link linkend="HDRWQ108">Starting Server Programs</link> if you
1458             are installing an additional file server machine; or
1459             <link linkend="HDRWQ145"></link> if you are installing a client.
1460             </para>
1461           </listitem>
1462         </orderedlist>
1463       </para>
1464     </sect2>
1465     <sect2 id="KAS016">
1466       <title>Enabling kaserver based AFS Login on Solaris Systems</title>
1467       
1468       <para>At this point you incorporate AFS into the operating system's 
1469       Pluggable Authentication Module (PAM) scheme. PAM
1470       integrates all authentication mechanisms on the machine, including 
1471       login, to provide the security infrastructure for
1472       authenticated access to and from the machine.</para>
1473
1474       <para>Explaining PAM is beyond the scope of this document. It is 
1475       assumed that you understand the syntax and meanings of
1476       settings in the PAM configuration file (for example, how the 
1477       <computeroutput>other</computeroutput> entry works, the effect of
1478       marking an entry as <computeroutput>required</computeroutput>, 
1479       <computeroutput>optional</computeroutput>, or
1480       <computeroutput>sufficient</computeroutput>, and so on).</para>
1481
1482       <para>The following instructions explain how to alter the entries in the 
1483       PAM configuration file for each service for which you
1484       wish to use AFS authentication. Other configurations possibly also 
1485       work, but the instructions specify the recommended and
1486       tested configuration.</para>
1487
1488       <note>
1489         <para>The instructions specify that you mark each entry as 
1490         <computeroutput>optional</computeroutput>. However, marking some
1491         modules as optional can mean that they grant access to the 
1492         corresponding service even when the user does not meet all of the
1493         module's requirements. In some operating system revisions, 
1494         for example, if you mark as optional the module that controls
1495         login via a dial-up connection, it allows users to login without 
1496         providing a password. See the <emphasis>OpenAFS Release
1497         Notes</emphasis> for a discussion of any limitations that apply to 
1498         this operating system.</para>
1499
1500         <para>Also, with some operating system versions you must install 
1501         patches for PAM to interact correctly with certain
1502         authentication programs. For details, see the 
1503         <emphasis>OpenAFS Release Notes</emphasis>.</para>
1504       </note>
1505
1506       <para>The recommended AFS-related entries in the PAM configuration file 
1507       make use of one or more of the following three
1508       attributes. 
1509         <variablelist>
1510           <title>Authentication Management</title>
1511
1512           <varlistentry>
1513             <term><emphasis role="bold"><computeroutput>try_first_pass</computeroutput></emphasis></term>
1514
1515             <listitem>
1516               <para>This is a standard PAM attribute that can be included on 
1517               entries after the first one for a service; it directs
1518               the module to use the password that was provided to the first 
1519               module. For the AFS module, it means that AFS
1520               authentication succeeds if the password provided to the module 
1521               listed first is the user's correct AFS password. For
1522               further discussion of this attribute and its alternatives, see 
1523               the operating system's PAM documentation.</para>
1524             </listitem>
1525           </varlistentry>
1526
1527           <varlistentry>
1528             <term><emphasis role="bold"><computeroutput>ignore_root</computeroutput></emphasis></term>
1529
1530             <listitem>
1531               <para>This attribute, specific to the AFS PAM module, directs it 
1532               to ignore not only the local superuser <emphasis
1533               role="bold">root</emphasis>, but also any user with UID 0 
1534               (zero).</para>
1535             </listitem>
1536           </varlistentry>
1537
1538           <varlistentry>
1539             <term><emphasis role="bold"><computeroutput>setenv_password_expires</computeroutput></emphasis></term>
1540
1541             <listitem>
1542               <para>This attribute, specific to the AFS PAM module, sets the 
1543               environment variable PASSWORD_EXPIRES to the expiration
1544               date of the user's AFS password, which is recorded in the 
1545               Authentication Database.</para>
1546             </listitem>
1547           </varlistentry>
1548         </variablelist></para>
1549
1550       <para>Perform the following steps to enable AFS login. <orderedlist>
1551           <listitem>
1552             <para>Unpack the OpenAFS Binary Distribution for Solaris into the 
1553             <emphasis role="bold">/cdrom</emphasis> directory, if it is not 
1554             already.
1555             Then change directory as indicated. 
1556 <programlisting>
1557    # <emphasis role="bold">cd /usr/lib/security</emphasis>
1558 </programlisting></para>
1559           </listitem>
1560
1561           <listitem>
1562             <para>Copy the AFS authentication library file to the 
1563             <emphasis role="bold">/usr/lib/security</emphasis> directory. Then
1564             create a symbolic link to it whose name does not mention the 
1565             version. Omitting the version eliminates the need to edit
1566             the PAM configuration file if you later update the library 
1567             file.</para>
1568
1569             <para>If you use the AFS Authentication Server 
1570             (<emphasis role="bold">kaserver</emphasis> process):</para>
1571
1572 <programlisting>
1573    # <emphasis role="bold">cp /tmp/afsdist/sun4x_56/lib/pam_afs.so.1 .</emphasis>
1574    # <emphasis role="bold">ln -s pam_afs.so.1 pam_afs.so</emphasis>   
1575 </programlisting>
1576
1577             <para>If you use a Kerberos implementation of AFS authentication:</para>
1578
1579 <programlisting>
1580    # <emphasis role="bold">cp /tmp/afsdist/sun4x_56/lib/pam_afs.krb.so.1 .</emphasis>
1581    # <emphasis role="bold">ln -s pam_afs.krb.so.1 pam_afs.so</emphasis>
1582 </programlisting>
1583           </listitem>
1584
1585           <listitem>
1586             <para>Edit the 
1587             <computeroutput>Authentication management</computeroutput> section 
1588             of the Solaris PAM configuration file,
1589             <emphasis role="bold">/etc/pam.conf</emphasis> by convention. 
1590             The entries in this section have the value
1591             <computeroutput>auth</computeroutput> in their second field.</para>
1592
1593             <para>First edit the standard entries, which refer to the 
1594             Solaris PAM module (usually, the file <emphasis
1595             role="bold">/usr/lib/security/pam_unix.so.1</emphasis>) in their 
1596             fourth field. For each service for which you want to
1597             use AFS authentication, edit the third field of its entry to read 
1598             <computeroutput>optional</computeroutput>. The
1599             <emphasis role="bold">pam.conf</emphasis> file in the Solaris 
1600             distribution usually includes standard entries for the
1601             <emphasis role="bold">login</emphasis>, 
1602             <emphasis role="bold">rlogin</emphasis>, and <emphasis
1603             role="bold">rsh</emphasis> services, for instance.</para>
1604
1605             <para>If there are services for which you want to use AFS 
1606             authentication, but for which the <emphasis
1607             role="bold">pam.conf</emphasis> file does not already include a 
1608             standard entry, you must create that entry and place the
1609             value <computeroutput>optional</computeroutput> in its third field. 
1610             For instance, the Solaris 
1611             <emphasis role="bold">pam.conf</emphasis> file does not usually 
1612             include standard entries for the 
1613             <emphasis role="bold">ftp</emphasis> or 
1614             <emphasis role="bold">telnet</emphasis> services.</para>
1615
1616             <para>Then create an AFS-related entry for each service, placing it 
1617             immediately below the standard entry. The following
1618             example shows what the 
1619             <computeroutput>Authentication Management</computeroutput> 
1620             section looks like after you have you edited or created entries 
1621             for the services mentioned previously. Note that the example AFS 
1622             entries appear on two lines
1623             only for legibility.</para>
1624
1625 <programlisting>
1626    login   auth  optional  /usr/lib/security/pam_unix.so.1
1627    login   auth  optional  /usr/lib/security/pam_afs.so       \
1628          try_first_pass  ignore_root  setenv_password_expires
1629    rlogin  auth  optional  /usr/lib/security/pam_unix.so.1
1630    rlogin  auth  optional  /usr/lib/security/pam_afs.so       \
1631          try_first_pass  ignore_root  setenv_password_expires
1632    rsh     auth  optional  /usr/lib/security/pam_unix.so.1
1633    rsh     auth  optional  /usr/lib/security/pam_afs.so       \
1634          try_first_pass  ignore_root            
1635    ftp     auth  optional  /usr/lib/security/pam_unix.so.1
1636    ftp     auth  optional  /usr/lib/security/pam_afs.so       \
1637          try_first_pass  ignore_root
1638    telnet  auth  optional  /usr/lib/security/pam_unix.so.1
1639    telnet  auth  optional  /usr/lib/security/pam_afs.so       \
1640          try_first_pass  ignore_root  setenv_password_expires
1641 </programlisting>
1642           </listitem>
1643
1644           <listitem>
1645             <para>If you use the Common Desktop Environment (CDE) on the 
1646             machine and want users to obtain an AFS token as they log
1647             in, also add or edit the following four entries in the 
1648             <computeroutput>Authentication management</computeroutput>
1649             section. Note that the AFS-related entries appear on two lines 
1650             here only for legibility. 
1651 <programlisting>
1652    dtlogin   auth  optional  /usr/lib/security/pam_unix.so.1
1653    dtlogin   auth  optional  /usr/lib/security/pam_afs.so     \
1654          try_first_pass  ignore_root
1655    dtsession  auth  optional /usr/lib/security/pam_unix.so.1
1656    dtsession  auth  optional /usr/lib/security/pam_afs.so     \
1657          try_first_pass  ignore_root
1658 </programlisting>
1659             </para>
1660           </listitem>
1661           <listitem>
1662             <para>Proceed to 
1663             <link linkend="HDRWQ49a">Editing the File Systems Clean-up Script 
1664             on Solaris Systems in the server instructions </link> if you are 
1665             installing your first file server;
1666             <link linkend="HDRWQ108">Starting Server Programs</link> if you
1667             are installing an additional file server machine; or
1668             <link linkend="Header_137a">Editing the File Systems Clean-up Script
1669             on Solaris Systems in the client instructions</link> if you are 
1670             installing a client.</para>
1671           </listitem>
1672         </orderedlist>
1673       </para>
1674     </sect2>
1675   </sect1>
1676 </appendix>