1 <?xml version=
"1.0" encoding=
"UTF-8"?>
3 <title>Appendix B. Configuring Legacy Components
</title>
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>
12 <title>kaserver and Legacy Kerberos
4 Authentication
</title>
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>
19 <para>This should be used in conjuction with the installation instructures
20 in earlier chapters, whose format it mirrors.
</para>
23 <title>Background
</title>
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>
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.
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>
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>
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>
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>
64 <title>Using this Appendix
</title>
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.
73 <para>Installing the First AFS Machine
</para>
76 <para>Installing Additional Server Machines
</para>
79 <para>Installing Additonal Client Machines
</para>
83 <para>There is an additional section on installing AFS login
84 functionality, which is relevant to all machines which are operating as
87 <para>In addition, some general substitions should be made
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>
95 #
<emphasis role=
"bold">kinit admin
</emphasis>
96 Password:
<replaceable>admin_passwd
</replaceable>
97 #
<emphasis role=
"bold">aklog
</emphasis>
101 #
<emphasis role=
"bold">klog admin
</emphasis>
102 Password:
<replaceable>admin_passwd
</replaceable>
103 </programlisting></para>
105 </itemizedlist></para>
108 <title>Installing the First AFS machine
</title>
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
116 <para>The structure of this section follows the structure of the
117 earlier chapter.
</para>
120 <title>Overview: Installing Server Functionality
</title>
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>
128 <title>Starting the kaserver Database Server Process
</title>
130 <primary>Authentication Server
</primary>
131 <secondary>starting
</secondary>
132 <tertiary>first AFS machine
</tertiary>
135 <primary>first AFS machine
</primary>
136 <secondary>Authentication Server
</secondary>
139 <primary>kaserver process
</primary>
140 <see>Authentication Server
</see>
143 <primary>starting
</primary>
144 <secondary>Authentication Server
</secondary>
145 <tertiary>first AFS machine
</tertiary>
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:
154 <para>The Authentication Server
155 (the
<emphasis role=
"bold">kaserver
</emphasis> process) maintains
156 the Authentication Database
</para>
158 </itemizedlist></para>
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>.
174 <primary>commands
</primary>
175 <secondary>bos create
</secondary>
178 <primary>bos commands
</primary>
179 <secondary>create
</secondary>
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>.
186 #
<emphasis role=
"bold">./bos create
</emphasis> <<replaceable>machine name
</replaceable>> <emphasis role=
"bold">kaserver simple /usr/afs/bin/kaserver
</emphasis> \
187 <emphasis role=
"bold"> -cell
</emphasis> <<replaceable>cell name
</replaceable>> <emphasis role=
"bold">-noauth
</emphasis>
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>
198 <para>Return to
<link linkend=
"HDRWQ52">Starting the Database Server
199 Processes
</link> and follow the remaining instructions
</para>
204 <title>Initialising Cell Security with kaserver
</title>
207 <para>The following instructions should be followed in place of
208 those in
<link linkend=
"HDRWQ53">Initializing Cell Security
</link>
212 <para>Begin by creating the following two initial entries in the
213 Authentication Database:
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>
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>
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>
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>
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>
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
259 <primary>commands
</primary>
260 <secondary>kas (interactive)
</secondary>
264 <primary>kas commands
</primary>
265 <secondary>interactive mode, entering
</secondary>
269 <primary>interactive mode for kas
</primary>
270 <secondary>entering
</secondary>
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
280 #
<emphasis role=
"bold">kas -cell
</emphasis> <<replaceable>cell name
</replaceable>> <emphasis role=
"bold">-noauth
</emphasis>
284 <primary>commands
</primary>
285 <secondary>kas create
</secondary>
288 <primary>kas commands
</primary>
289 <secondary>create
</secondary>
292 <primary>server encryption key
</primary>
293 <secondary>in Authentication Database
</secondary>
296 <primary>creating
</primary>
297 <secondary>server encryption key
</secondary>
298 <tertiary>Authentication Database
</tertiary>
303 <listitem id=
"AppendixLIWQ54">
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>
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>
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>
328 ka
> <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
> <emphasis role=
"bold">create admin
</emphasis>
332 initial_password:
<replaceable>admin_passwd
</replaceable>
333 Verifying, please re-enter initial_password:
<replaceable>admin_passwd
</replaceable>
337 <primary>commands
</primary>
338 <secondary>kas examine
</secondary>
342 <primary>kas commands
</primary>
343 <secondary>examine
</secondary>
347 <primary>displaying
</primary>
348 <secondary>server encryption key
</secondary>
349 <tertiary>Authentication Database
</tertiary>
353 <listitem id=
"AppendixLIWQ55">
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
365 ka
> <emphasis role=
"bold">examine afs
</emphasis>
367 key (
0) cksum is
<replaceable>checksum
</replaceable> . . .
370 <primary>commands
</primary>
371 <secondary>kas setfields
</secondary>
374 <primary>kas commands
</primary>
375 <secondary>setfields
</secondary>
378 <primary>admin account
</primary>
379 <secondary>setting ADMIN flag on Auth. DB entry
</secondary>
384 <listitem id=
"LIWQ56">
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
396 ka
> <emphasis role=
"bold">setfields admin -flags admin
</emphasis>
397 ka
> <emphasis role=
"bold">examine admin
</emphasis>
398 User data for admin (ADMIN) . . .
401 <primary>commands
</primary>
402 <secondary>kas quit
</secondary>
405 <primary>kas commands
</primary>
406 <secondary>quit
</secondary>
409 <primary>interactive mode for kas
</primary>
410 <secondary>quitting
</secondary>
416 <para>Issue the
<emphasis role=
"bold">kas quit
</emphasis>
417 command to leave
<emphasis role=
"bold">kas
</emphasis>
420 ka
> <emphasis role=
"bold">quit
</emphasis>
423 <primary>commands
</primary>
424 <secondary>bos adduser
</secondary>
427 <primary>bos commands
</primary>
428 <secondary>adduser
</secondary>
431 <primary>usr/afs/etc/UserList
</primary>
432 <see>UserList file
</see>
435 <primary>UserList file
</primary>
436 <secondary>first AFS machine
</secondary>
439 <primary>files
</primary>
440 <secondary>UserList
</secondary>
443 <primary>creating
</primary>
444 <secondary>UserList file entry
</secondary>
447 <primary>admin account
</primary>
448 <secondary>adding
</secondary>
449 <tertiary>to UserList file
</tertiary>
454 <listitem id=
"AppendixLIWQ57">
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.
463 #
<emphasis role=
"bold">./bos adduser
</emphasis> <<replaceable>machine name
</replaceable>> <emphasis role=
"bold">admin -cell
</emphasis> <<replaceable>cell name
</replaceable>> <emphasis
464 role=
"bold">-noauth
</emphasis>
467 <primary>commands
</primary>
468 <secondary>bos addkey
</secondary>
471 <primary>bos commands
</primary>
472 <secondary>addkey
</secondary>
475 <primary>creating
</primary>
476 <secondary>server encryption key
</secondary>
477 <tertiary>KeyFile file
</tertiary>
480 <primary>server encryption key
</primary>
481 <secondary>in KeyFile file
</secondary>
486 <listitem id=
"AppendixLIWQ58">
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.
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>
500 #
<emphasis role=
"bold">./bos addkey
</emphasis> <<replaceable>machine name
</replaceable>> <emphasis role=
"bold">-kvno
0 -cell
</emphasis> <<replaceable>cell name
</replaceable>> <emphasis
501 role=
"bold">-noauth
</emphasis>
502 Input key:
<replaceable>afs_passwd
</replaceable>
503 Retype input key:
<replaceable>afs_passwd
</replaceable>
507 <primary>commands
</primary>
508 <secondary>bos listkeys
</secondary>
512 <primary>bos commands
</primary>
513 <secondary>listkeys
</secondary>
517 <primary>displaying
</primary>
518 <secondary>server encryption key
</secondary>
519 <tertiary>KeyFile file
</tertiary>
523 <listitem id=
"AppendixLIWQ59">
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>.
532 #
<emphasis role=
"bold">./bos listkeys
</emphasis> <<replaceable>machine name
</replaceable>> <emphasis role=
"bold">-cell
</emphasis> <<replaceable>ce
533 ll name
</replaceable>> <emphasis
534 role=
"bold">-noauth
</emphasis>
535 key
0 has cksum
<replaceable>checksum
</replaceable>
536 </programlisting></para>
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>
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>
553 #
<emphasis role=
"bold">./kas -cell
</emphasis> <<replaceable>cell name
</replaceable>> <emphasis role=
"bold">-noauth
</emphasis>
554 ka
> <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
> <emphasis role=
"bold">examine afs
</emphasis>
559 key (
1) cksum is
<replaceable>checksum
</replaceable> . . .
560 ka
> <emphasis role=
"bold">quit
</emphasis>
561 #
<emphasis role=
"bold">./bos addkey
</emphasis> <<replaceable>machine name
</replaceable>> <emphasis role=
"bold">-kvno
1 -cell
</emphasis> <<replaceable>cell name
</replaceable>> <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> <<replaceable>machine name
</replaceable>> <emphasis role=
"bold">-cell
</emphasis> <<replaceable>cell name
</replaceable>> <emphasis
566 role=
"bold">-noauth
</emphasis>
567 key
1 has cksum
<replaceable>checksum
</replaceable>
572 <link linkend=
"HDRWQ53a">Initializing the Protection Database
</link>
573 to continue with the installation process
</para>
575 </orderedlist></para>
579 <title>Installing Additional Server Machines
</title>
582 <title>Starting the Authenticxation Service
</title>
584 <primary>Authentication Server
</primary>
585 <secondary>starting
</secondary>
586 <tertiary>new db-server machine
</tertiary>
589 <primary>starting
</primary>
590 <secondary>Authentication Server
</secondary>
591 <tertiary>new db-server machine
</tertiary>
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>
598 <listitem id=
"LIWQ118">
599 <para>Start the Authentication Server
600 (the
<emphasis role=
"bold">kaserver
</emphasis> process).
602 %
<emphasis role=
"bold">bos create
</emphasis> <<replaceable>machine name
</replaceable>> <emphasis role=
"bold">kaserver simple /usr/afs/bin/kaserver
</emphasis>
603 </programlisting> </para>
607 <para>Return to
<link linkend=
"LIWQ119">starting the backup server
</link></para>
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>
622 <para>For convenience, the following sections group this procedure by
623 system type. Proceed to the appropriate section.
627 <link linkend=
"KAS015">Enabling AFS Login on Linux Systems
</link>
632 <link linkend=
"KAS016">Enabling AFS login on Solaris Systems
</link>
639 <title>Enabling kaserver based AFS Login on Linux Systems
</title>
641 <para>At this point you incorporate AFS into the operating system's
642 Pluggable Authentication Module (PAM) scheme. PAM integrates all
643 authentication mechanisms on the machine, including login, to provide
644 the security infrastructure for authenticated access to and from the
647 <para>Explaining PAM is beyond the scope of this document. It is
648 assumed that you understand the syntax and meanings of settings in the
649 PAM configuration file (for example, how the
650 <computeroutput>other
</computeroutput> entry works, the effect of
651 marking an entry as
<computeroutput>required
</computeroutput>,
652 <computeroutput>optional
</computeroutput>, or
653 <computeroutput>sufficient
</computeroutput>, and so on).
</para>
655 <para>The following instructions explain how to alter the entries in
656 the PAM configuration file for each service for which you
657 wish to use AFS authentication. Other configurations possibly also
658 work, but the instructions specify the recommended and
659 tested configuration.
</para>
661 <para>The recommended AFS-related entries in the PAM configuration
662 file make use of one or more of the following three
665 <title>Authentication Management
</title>
668 <term><emphasis role=
"bold"><computeroutput>try_first_pass
</computeroutput></emphasis></term>
671 <para>This is a standard PAM attribute that can be included on
672 entries after the first one for a service; it directs
673 the module to use the password that was provided to the first
674 module. For the AFS module, it means that AFS
675 authentication succeeds if the password provided to the module
676 listed first is the user's correct AFS password. For
677 further discussion of this attribute and its alternatives, see
678 the operating system's PAM documentation.
</para>
683 <term><emphasis role=
"bold"><computeroutput>ignore_root
</computeroutput></emphasis></term>
686 <para>This attribute, specific to the AFS PAM module, directs it
687 to ignore not only the local superuser
<emphasis
688 role=
"bold">root
</emphasis>, but also any user with UID
694 <term><emphasis role=
"bold"><computeroutput>ignore_uid
</computeroutput><emphasis>uid
</emphasis></emphasis></term>
697 <para>This option is an extension of the
"ignore_root" switch.
698 The additional parameter is a limit. Users with a uid
699 up to the given parameter are ignored by
700 <emphasis>pam_afs.so
</emphasis>. Thus, a system administrator
702 opportunity to add local user accounts to his system by choosing
703 between
"low" and
"high" user ids. An example
704 /etc/passwd file for
"ignore_uid 100" may have entries like these:
708 afsuserone:x:
99:
100::/afs/afscell/u/afsuserone:/bin/bash
709 afsusertwo:x:
100:
100::/afs/afscell/u/afsusertwo:/bin/bash
710 localuserone:x:
101:
100::/home/localuserone:/bin/bash
711 localusertwo:x:
102:
100::/home/localusertwo:/bin/bash
715 AFS accounts should be locked in the file /etc/shadow like this:
719 afsuserone:!!:
11500:
0:
99999:
7:::
720 afsusertwo:!!:
11500:
0:
99999:
7:::
721 localuserone:
<thelocaluserone'skey
>:
11500:
0:
99999:
7:::
722 localusertwo:
<thelocalusertwo'skey
>:
11500:
0:
99999:
7:::
726 There is no need to store a local key in this file since the AFS
727 password is sent and verfied at the AFS cell server!
</para>
732 <term><emphasis role=
"bold"><computeroutput>setenv_password_expires
</computeroutput></emphasis></term>
735 <para>This attribute, specific to the AFS PAM module, sets the
736 environment variable PASSWORD_EXPIRES to the expiration
737 date of the user's AFS password, which is recorded in the
738 Authentication Database.
</para>
743 <term><emphasis role=
"bold"><computeroutput>set_token
</computeroutput></emphasis></term>
746 <para>Some applications don't call
747 <emphasis>pam_setcred()
</emphasis> in order to retrieve the
748 appropriate credentials (here the AFS token) for their session.
749 This switch sets the credentials already in
750 <emphasis>pam_sm_authenticate()
</emphasis> obsoleting a call to
751 <emphasis>pam_setcred()
</emphasis>.
<emphasis
752 role=
"bold">Caution: Don't use this switch for applications which
753 do call
<emphasis>pam_setcred()
</emphasis>!
</emphasis> One
754 example for an application not calling
755 <emphasis>pam_setcred()
</emphasis> are older versions of the
756 samba server. Nevertheless, using applications with
757 working pam session management is recommended as this setup
758 conforms better with the PAM definitions.
</para>
763 <term><emphasis role=
"bold"><computeroutput>refresh_token
</computeroutput></emphasis></term>
766 <para>This options is identical to
"set_token" except that no
767 new PAG is generated. This is necessary to handle
768 processes like xlock or xscreensaver. It is not enough to just
769 unlock the screen for a user who
770 reactivated his session by typing in the correct AFS password, but
771 one may also need fresh tokens with a full lifetime in
772 order to work on, and the new token must be refreshed in the
773 already existing PAG for the processes that have been
774 started. This is achieved using this option.
</para>
779 <term><emphasis role=
"bold"><computeroutput>use_klog
</computeroutput></emphasis></term>
782 <para>Activating this switch causes authentication to be done by
783 calling the external program
"klog". One program requiring
784 this is for example
<emphasis>kdm
</emphasis> of KDE
2.x.
</para>
789 <term><emphasis role=
"bold"><computeroutput>dont_fork
</computeroutput></emphasis></term>
792 <para>Usually, the password verification and token establishment
793 is performed in a sub process. Using this option pam_afs does not
794 fork and performs all actions in a single process.
795 <emphasis role=
"bold">Only use this option in cases where you
796 notice serious problems caused by the sub process.
</emphasis>
797 This option has been developed in respect to
798 the
"mod_auth_pam"-project (see also
799 <ulink url=
"http://pam.sourceforge.net/mod_auth_pam/">mod_auth_pam
</ulink>).
800 The mod_auth_pam module enables PAM authentication for the apache
801 http server package.
</para>
806 <title>Session Management
</title>
809 <term><emphasis role=
"bold"><computeroutput>no_unlog
</computeroutput></emphasis></term>
812 <para>Normally the tokens are deleted (in memory) after the
813 session ends. Using this option causes the tokens to be left
814 untouched.
<emphasis role=
"bold">This behaviour was the default
815 in pam_afs until openafs-
1.1.1!
</emphasis></para>
820 <term><emphasis role=
"bold"><computeroutput>remainlifetime
</computeroutput> <emphasis>sec
</emphasis></emphasis></term>
823 <para>The tokens are kept active for
<emphasis>sec
</emphasis>
824 seconds before they are deleted. X display managers i.e.
825 are used to inform the applications started in the X session
826 before the logout and then end themselves. If the token
827 was deleted immediately the applications would have no chance
828 to write back their settings to i.e. the user's AFS home
829 space. This option may help to avoid the problem.
</para>
832 </variablelist></para>
834 <para>Perform the following steps to enable AFS login.
837 <para>Unpack the OpenAFS Binary Distribution for Linux into the
838 <emphasis role=
"bold">/tmp/afsdist/
</emphasis> directory, if it is
840 Then change to the directory for PAM modules, which depends on which Linux distribution you are using.
</para>
842 <para>If you are using a Linux distribution from Red Hat Software:
</para>
845 #
<emphasis role=
"bold">cd /lib/security
</emphasis>
848 <para>If you are using another Linux distribution:
</para>
851 #
<emphasis role=
"bold">cd /usr/lib/security
</emphasis>
856 <para>Copy the appropriate AFS authentication library file to the
857 directory to which you changed in the previous step.
858 Create a symbolic link whose name does not mention the version.
859 Omitting the version eliminates the need to edit the PAM
860 configuration file if you later update the library file.
</para>
862 <para>If you use the AFS Authentication Server
863 (
<emphasis role=
"bold">kaserver
</emphasis> process):
</para>
865 #
<emphasis role=
"bold">cp /cdrom/i386_linux22/lib/pam_afs.so
.1 .
</emphasis>
866 #
<emphasis role=
"bold">ln -s pam_afs.so
.1 pam_afs.so
</emphasis>
869 <para>If you use a Kerberos implementation of AFS
870 authentication:
</para>
872 #
<emphasis role=
"bold">cp /cdrom/i386_linux22/lib/pam_afs.krb.so
.1 .
</emphasis>
873 #
<emphasis role=
"bold">ln -s pam_afs.krb.so
.1 pam_afs.so
</emphasis>
878 <para>For each service with which you want to use AFS
879 authentication, insert an entry for the AFS PAM module into the
880 <computeroutput>auth
</computeroutput> section of the service's
881 PAM configuration file. (Linux uses a separate
882 configuration file for each service, unlike some other operating
883 systems which list all services in a single file.) Mark
884 the entry as
<computeroutput>sufficient
</computeroutput> in the
887 <para>Place the AFS entry below any entries that impose conditions
888 under which you want the service to fail for a user
889 who does not meet the entry's requirements. Mark these entries
890 <computeroutput>required
</computeroutput>. Place the AFS
891 entry above any entries that need to execute only if AFS
892 authentication fails.
</para>
894 <para>Insert the following AFS entry if using the Red Hat
897 auth sufficient /lib/security/pam_afs.so try_first_pass ignore_root
900 <para>Insert the following AFS entry if using another
904 auth sufficient /usr/lib/security/pam_afs.so try_first_pass ignore_root
907 <para>Check the PAM config files also for
"session" entries. If
908 there are lines beginning with
"session" then please
909 insert this line too:
</para>
912 session optional /lib/security/pam_afs.so
918 session optional /usr/lib/security/pam_afs.so
921 <para>This guarantees that the user's tokens are deleted from
922 memory after his session ends so that no other user
923 coincidently gets those tokens without authorization! The
924 following examples illustrate the recommended configuration of
925 the configuration file for several services:
927 <title>Authentication Management
</title>
930 <term>(
<emphasis role=
"bold">/etc/pam.d/login
</emphasis>)
</term>
936 auth required /lib/security/pam_securetty.so
937 auth required /lib/security/pam_nologin.so
938 auth sufficient /lib/security/pam_afs.so try_first_pass ignore_root
939 # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
940 #This enables AFS authentication for every user but root
941 auth required /lib/security/pam_pwdb.so shadow nullok
942 account required /lib/security/pam_pwdb.so
943 password required /lib/security/pam_cracklib.so
944 password required /lib/security/pam_pwdb.so shadow nullok use_authtok
945 session optional /lib/security/pam_afs.so
946 #Make sure tokens are deleted after the user logs out
947 session required /lib/security/pam_pwdb.so
954 <term>(
<emphasis role=
"bold">/etc/pam.d/samba
</emphasis>)
</term>
959 auth required /lib/security/pam_afs.so ignore_uid
100 set_token
960 # ^^^^^^^^^^^^^^^^^^^^^^^^
961 #Here, users with uid
>100 are considered to belong to the AFS and users
962 #with uid
<=
100 are ignored by pam_afs. The token is retrieved already in
963 #pam_sm_authenticate() (this is an example pam config for a samba version
964 #that does not call pam_setcred(), it also does no sense to include session
965 #entries here since they would be ignored by this version of samba ).
966 account required /lib/security/pam_pwdb.so
973 <term>(
<emphasis role=
"bold">/etc/pam.d/xscreensaver
</emphasis>)
</term>
978 auth sufficient /lib/security/pam_afs.so ignore_uid
100 refresh_token
980 #Avoid generating a new PAG for the new tokens, use the already existing PAG and
981 #establish a fresh token in it.
982 auth required /lib/security/pam_pwdb.so try_first_pass
989 <term>(
<emphasis role=
"bold">/etc/pam.d/httpd
</emphasis>)
</term>
994 auth required /lib/security/pam_afs.so ignore_uid
100 dont_fork
996 #Don't fork for the verification of the password.
1003 <title>Session Management
</title>
1006 <term>(
<emphasis role=
"bold">/etc/pam.d/su
</emphasis>)
</term>
1011 auth sufficient /lib/security/pam_afs.so ignore_uid
100
1012 auth required /lib/security/pam_pwdb.so try_first_pass
1013 account required /lib/security/pam_pwdb.so
1014 password required /lib/security/pam_cracklib.so
1015 password required /lib/security/pam_pwdb.so use_authtok
1016 session required /lib/security/pam_pwdb.so
1017 session optional /lib/security/pam_afs.so no_unlog
1019 #Don't delete the token in this case, since the user may still
1020 #need it (for example if somebody logs in and changes to root
1021 #afterwards he may still want to access his home space in AFS).
1022 session required /lib/security/pam_login_access.so
1023 session optional /lib/security/pam_xauth.so
1030 <term>(
<emphasis role=
"bold">/etc/pam.d/xdm
</emphasis>)
</term>
1035 auth required /lib/security/pam_nologin.so
1036 auth required /lib/security/pam_login_access.so
1037 auth sufficient /lib/security/pam_afs.so ignore_uid
100 use_klog
1038 auth required /lib/security/pam_pwdb.so try_first_pass
1039 account required /lib/security/pam_pwdb.so
1040 password required /lib/security/pam_cracklib.so
1041 password required /lib/security/pam_pwdb.so shadow nullok use_authtok
1042 session optional /lib/security/pam_afs.so remainlifetime
10
1044 #Wait
10 seconds before deleting the AFS tokens in order to give
1045 #the programs of the X session some time to save their settings
1047 session required /lib/security/pam_pwdb.so
1052 </variablelist></para>
1055 <para>After taking any necessary action, proceed to
1056 <link linkend=
"HDRWQ50">Starting the BOS Server
</link> if you
1057 are installing your first file server;
1058 <link linkend=
"HDRWQ108">Starting Server Programs
</link> if you
1059 are installing an additional file server machine; or
1060 <link linkend=
"HDRWQ145">Loading and Creating Client Files
</link> if you are installing a client.
1067 <title>Enabling kaserver based AFS Login on Solaris Systems
</title>
1069 <para>At this point you incorporate AFS into the operating system's
1070 Pluggable Authentication Module (PAM) scheme. PAM
1071 integrates all authentication mechanisms on the machine, including
1072 login, to provide the security infrastructure for
1073 authenticated access to and from the machine.
</para>
1075 <para>Explaining PAM is beyond the scope of this document. It is
1076 assumed that you understand the syntax and meanings of
1077 settings in the PAM configuration file (for example, how the
1078 <computeroutput>other
</computeroutput> entry works, the effect of
1079 marking an entry as
<computeroutput>required
</computeroutput>,
1080 <computeroutput>optional
</computeroutput>, or
1081 <computeroutput>sufficient
</computeroutput>, and so on).
</para>
1083 <para>The following instructions explain how to alter the entries in the
1084 PAM configuration file for each service for which you
1085 wish to use AFS authentication. Other configurations possibly also
1086 work, but the instructions specify the recommended and
1087 tested configuration.
</para>
1090 <para>The instructions specify that you mark each entry as
1091 <computeroutput>optional
</computeroutput>. However, marking some
1092 modules as optional can mean that they grant access to the
1093 corresponding service even when the user does not meet all of the
1094 module's requirements. In some operating system revisions,
1095 for example, if you mark as optional the module that controls
1096 login via a dial-up connection, it allows users to login without
1097 providing a password. See the
<emphasis>OpenAFS Release
1098 Notes
</emphasis> for a discussion of any limitations that apply to
1099 this operating system.
</para>
1101 <para>Also, with some operating system versions you must install
1102 patches for PAM to interact correctly with certain
1103 authentication programs. For details, see the
1104 <emphasis>OpenAFS Release Notes
</emphasis>.
</para>
1107 <para>The recommended AFS-related entries in the PAM configuration file
1108 make use of one or more of the following three
1111 <title>Authentication Management
</title>
1114 <term><emphasis role=
"bold"><computeroutput>try_first_pass
</computeroutput></emphasis></term>
1117 <para>This is a standard PAM attribute that can be included on
1118 entries after the first one for a service; it directs
1119 the module to use the password that was provided to the first
1120 module. For the AFS module, it means that AFS
1121 authentication succeeds if the password provided to the module
1122 listed first is the user's correct AFS password. For
1123 further discussion of this attribute and its alternatives, see
1124 the operating system's PAM documentation.
</para>
1129 <term><emphasis role=
"bold"><computeroutput>ignore_root
</computeroutput></emphasis></term>
1132 <para>This attribute, specific to the AFS PAM module, directs it
1133 to ignore not only the local superuser
<emphasis
1134 role=
"bold">root
</emphasis>, but also any user with UID
0
1140 <term><emphasis role=
"bold"><computeroutput>setenv_password_expires
</computeroutput></emphasis></term>
1143 <para>This attribute, specific to the AFS PAM module, sets the
1144 environment variable PASSWORD_EXPIRES to the expiration
1145 date of the user's AFS password, which is recorded in the
1146 Authentication Database.
</para>
1149 </variablelist></para>
1151 <para>Perform the following steps to enable AFS login.
<orderedlist>
1153 <para>Unpack the OpenAFS Binary Distribution for Solaris into the
1154 <emphasis role=
"bold">/cdrom
</emphasis> directory, if it is not
1156 Then change directory as indicated.
1158 #
<emphasis role=
"bold">cd /usr/lib/security
</emphasis>
1159 </programlisting></para>
1163 <para>Copy the AFS authentication library file to the
1164 <emphasis role=
"bold">/usr/lib/security
</emphasis> directory. Then
1165 create a symbolic link to it whose name does not mention the
1166 version. Omitting the version eliminates the need to edit
1167 the PAM configuration file if you later update the library
1170 <para>If you use the AFS Authentication Server
1171 (
<emphasis role=
"bold">kaserver
</emphasis> process):
</para>
1174 #
<emphasis role=
"bold">cp /tmp/afsdist/sun4x_56/dest/lib/pam_afs.so
.1 .
</emphasis>
1175 #
<emphasis role=
"bold">ln -s pam_afs.so
.1 pam_afs.so
</emphasis>
1178 <para>If you use a Kerberos implementation of AFS authentication:
</para>
1181 #
<emphasis role=
"bold">cp /tmp/afsdist/sun4x_56/dest/lib/pam_afs.krb.so
.1 .
</emphasis>
1182 #
<emphasis role=
"bold">ln -s pam_afs.krb.so
.1 pam_afs.so
</emphasis>
1188 <computeroutput>Authentication management
</computeroutput> section
1189 of the Solaris PAM configuration file,
1190 <emphasis role=
"bold">/etc/pam.conf
</emphasis> by convention.
1191 The entries in this section have the value
1192 <computeroutput>auth
</computeroutput> in their second field.
</para>
1194 <para>First edit the standard entries, which refer to the
1195 Solaris PAM module (usually, the file
<emphasis
1196 role=
"bold">/usr/lib/security/pam_unix.so
.1</emphasis>) in their
1197 fourth field. For each service for which you want to
1198 use AFS authentication, edit the third field of its entry to read
1199 <computeroutput>optional
</computeroutput>. The
1200 <emphasis role=
"bold">pam.conf
</emphasis> file in the Solaris
1201 distribution usually includes standard entries for the
1202 <emphasis role=
"bold">login
</emphasis>,
1203 <emphasis role=
"bold">rlogin
</emphasis>, and
<emphasis
1204 role=
"bold">rsh
</emphasis> services, for instance.
</para>
1206 <para>If there are services for which you want to use AFS
1207 authentication, but for which the
<emphasis
1208 role=
"bold">pam.conf
</emphasis> file does not already include a
1209 standard entry, you must create that entry and place the
1210 value
<computeroutput>optional
</computeroutput> in its third field.
1211 For instance, the Solaris
1212 <emphasis role=
"bold">pam.conf
</emphasis> file does not usually
1213 include standard entries for the
1214 <emphasis role=
"bold">ftp
</emphasis> or
1215 <emphasis role=
"bold">telnet
</emphasis> services.
</para>
1217 <para>Then create an AFS-related entry for each service, placing it
1218 immediately below the standard entry. The following
1219 example shows what the
1220 <computeroutput>Authentication Management
</computeroutput>
1221 section looks like after you have you edited or created entries
1222 for the services mentioned previously. Note that the example AFS
1223 entries appear on two lines
1224 only for legibility.
</para>
1227 login auth optional /usr/lib/security/pam_unix.so
.1
1228 login auth optional /usr/lib/security/pam_afs.so \
1229 try_first_pass ignore_root setenv_password_expires
1230 rlogin auth optional /usr/lib/security/pam_unix.so
.1
1231 rlogin auth optional /usr/lib/security/pam_afs.so \
1232 try_first_pass ignore_root setenv_password_expires
1233 rsh auth optional /usr/lib/security/pam_unix.so
.1
1234 rsh auth optional /usr/lib/security/pam_afs.so \
1235 try_first_pass ignore_root
1236 ftp auth optional /usr/lib/security/pam_unix.so
.1
1237 ftp auth optional /usr/lib/security/pam_afs.so \
1238 try_first_pass ignore_root
1239 telnet auth optional /usr/lib/security/pam_unix.so
.1
1240 telnet auth optional /usr/lib/security/pam_afs.so \
1241 try_first_pass ignore_root setenv_password_expires
1246 <para>If you use the Common Desktop Environment (CDE) on the
1247 machine and want users to obtain an AFS token as they log
1248 in, also add or edit the following four entries in the
1249 <computeroutput>Authentication management
</computeroutput>
1250 section. Note that the AFS-related entries appear on two lines
1251 here only for legibility.
1253 dtlogin auth optional /usr/lib/security/pam_unix.so
.1
1254 dtlogin auth optional /usr/lib/security/pam_afs.so \
1255 try_first_pass ignore_root
1256 dtsession auth optional /usr/lib/security/pam_unix.so
.1
1257 dtsession auth optional /usr/lib/security/pam_afs.so \
1258 try_first_pass ignore_root
1264 <link linkend=
"HDRWQ49a">Editing the File Systems Clean-up Script
1265 on Solaris Systems in the server instructions
</link> if you are
1266 installing your first file server;
1267 <link linkend=
"HDRWQ108">Starting Server Programs
</link> if you
1268 are installing an additional file server machine; or
1269 <link linkend=
"Header_137a">Editing the File Systems Clean-up Script
1270 on Solaris Systems in the client instructions
</link> if you are
1271 installing a client.
</para>
HCoop / hcoop / debian / openafs.git / blob