BOOK = auqbg000.xml
IDX = auqbg009.xml
SRCS = $(BOOK) auqbg003.xml auqbg004.xml auqbg005.xml auqbg006.xml \
- auqbg007.xml auqbg008.xml
+ auqbg007.xml auqbg008.xml appendix.xml
FLAGS = -e no-idref
all: pdf html
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<appendix id="Legacy">
+ <title>Appendix B. Configuring Legacy Components</title>
+
+ <para>This chapter describes how to configure a number of deprecated
+ components in OpenAFS. Whilst these components are not recommended for sites
+ performing new installations, it is recognised that there are a number of
+ installations which have not yet transitioned from using these, for whom
+ continued provision of installation instructions my be useful</para>
+
+ <sect1 id="KAS001">
+ <title>kaserver and Legacy Kerberos 4 Authentication</title>
+
+ <para>This section contains instructions for installing server and client
+ machines in sites which use either the deprecated AFS
+ <emphasis role="bold">kaserver</emphasis> or legacy Kerberos 4
+ authentication systems</para>
+
+ <para>This should be used in conjuction with the installation instructures
+ in earlier chapters, whose format it mirrors.</para>
+
+ <sect2 id="KAS002">
+ <title>Background</title>
+
+ <para>As detailed in the OpenAFS "No more DES" roadmap, OpenAFS is moving
+ away from the single DES based security models of both
+ <emphasis role="bold">kaserver</emphasis> and external Kerberos 4 KDCs,
+ in favour of using external, Kerberos 5 KDCs for authentication.</para>
+
+ <para>AFS version 3 was designed and implemented during the late 80s and
+ early 90s when the state of the art in distributed computer
+ authentication and data security was Kerberos 4 and single DES. The
+ RXKAD security class was specified to use a single DES key and the kauth
+ authentication protocol is a derivative of MIT's Kerberos 4 protocol.
+ </para>
+
+ <para>For the better part of the last decade there has been concern
+ regarding the cryptographic strength of the DES cipher when used as a
+ building block within systems intended to prove authentication and/or
+ data integrity and privacy. Kerberos 4 and RXKAD are not extensible and
+ cannot negotiate non-DES key types. As a result efforts to migrate away
+ from Kerberos 4 based authentication at higher risk organizations have
+ been underway since the mid to late 90s. Ken Hornstein issued the first
+ of his Kerberos 5 migration kits for AFS in May 1999. </para>
+
+ <para>In March 2003, the continued use of single DES and kauth as the
+ basis for OpenAFS security became a real-world threat when a significant
+ Kerberos 4 crossrealm vulnerability was published. The OpenAFS community
+ was notified in security advisory OPENAFS-SA-2003-001 which can be
+ found at http://www.openafs.org/security.</para>
+
+ <para>As a result of the mounting concerns regarding the strength of
+ DES, NIST announced in May 2003 the withdrawal of FIPS 43-3
+ "Data Encryption Standard (DES)" as well as the associated FIPS 74 and
+ FIPS 81. In other words, NIST announced that DES and its derivatives
+ could no longer be used by the United States Government and should no
+ longer by those that trust its lead.</para>
+
+ <para>In July 2003 MIT announced the end of life of the Kerberos 4
+ protocol which is distributed for backward compatibility as part of the
+ MIT Kerberos 5 distribution.</para>
+ </sect2>
+ <sect2 id="KAS003">
+ <title>Using this Appendix</title>
+
+ <para>This appendix should be read in conjunction with the instructions
+ contained in the earlier chapters. It contains additions and in some
+ cases, modifications, to the directions contained in those
+ chapters. It is organised into 3 main sections, corresponding to the
+ topics of the earlier chapters.
+ <orderedlist>
+ <listitem>
+ <para>Installing the First AFS Machine</para>
+ </listitem>
+ <listitem>
+ <para>Installing Additional Server Machines</para>
+ </listitem>
+ <listitem>
+ <para>Installing Additonal Client Machines</para>
+ </listitem>
+ </orderedlist></para>
+
+ <para>There is an additional section on installing AFS login
+ functionality, which is relevant to all machines which are operating as
+ AFS clients</para>
+
+ <para>In addition, some general substitions should be made
+ <itemizedlist>
+ <listitem>
+ <para>References to <emphasis role="bold">kinit</emphasis>and
+ <emphasis role="bold">aklog</emphasis> should be replaced with
+ a single call to <emphasis role="bold">klog</emphasis></para>
+ <para>For example
+<programlisting>
+ # <emphasis role="bold">kinit admin</emphasis>
+ Password: <replaceable>admin_passwd</replaceable>
+ # <emphasis role="bold">aklog</emphasis>
+</programlisting>
+ becomes
+<programlisting>
+ # <emphasis role="bold">kinit admin</emphasis>
+ Password: <replaceable>admin_passwd</replaceable>
+</programlisting></para>
+ </listitem>
+ </itemizedlist></para>
+ </sect2>
+ <sect2 id="KAS003a">
+ <title>Installing the First AFS machine</title>
+
+ <para>This section details changes to the installation procedure for the
+ first AFS machine which are required in order to use
+ <emphasis role="bold">kaserver</emphasis> for authentication. As
+ detailed above, new sites are strongly discouraged from deploying
+ kaserver.</para>
+
+ <para>The structure of this section follows the structure of the
+ earlier chapter.</para>
+
+ <sect3 id="F">
+ <title>Overview: Installing Server Functionality</title>
+
+ <para>In adddition to the items described, you must also create
+ the Authentication Server as a database server process. The procedure
+ for creating the initial security mechanisms is also changed.</para>
+ </sect3>
+
+ <sect3 id="KAS006">
+ <title>Starting the kaserver Database Server Process</title>
+ <indexterm>
+ <primary>Authentication Server</primary>
+ <secondary>starting</secondary>
+ <tertiary>first AFS machine</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>first AFS machine</primary>
+ <secondary>Authentication Server</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>kaserver process</primary>
+ <see>Authentication Server</see>
+ </indexterm>
+ <indexterm>
+ <primary>starting</primary>
+ <secondary>Authentication Server</secondary>
+ <tertiary>first AFS machine</tertiary>
+ </indexterm>
+
+ <para>In addition to the database server processes described, you
+ must also use the <emphasis role="bold">bos create</emphasis> command
+ to create an entry for the following process, which runs on database
+ server machines only:
+ <itemizedlist>
+ <listitem>
+ <para>The Authentication Server
+ (the <emphasis role="bold">kaserver</emphasis> process) maintains
+ the Authentication Database</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>The following instructions include the
+ <emphasis role="bold">-cell</emphasis> argument on all applicable
+ commands. Provide the cell name you assigned in
+ <link linkend="HDRWQ51">Defining Cell Name and Membership for Server
+ Processes</link>. If a command appears on multiple lines, it is
+ only for legibility. The following commands should run before any of
+ the <emphasis role="bold">bos create</emphasis> commands detailed in
+ <link linkend="HDRWQ52">Starting the Database Server Processes</link>.
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>commands</primary>
+ <secondary>bos create</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>bos commands</primary>
+ <secondary>create</secondary>
+ </indexterm>
+ Issue the <emphasis role="bold">bos create</emphasis>
+ command to start the Authentication Server. The current
+ working directory is still
+ <emphasis role="bold">/usr/afs/bin</emphasis>.
+<programlisting>
+ # <emphasis role="bold">./bos create</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">kaserver simple /usr/afs/bin/kaserver</emphasis> \
+ <emphasis role="bold"> -cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis role="bold">-noauth</emphasis>
+</programlisting>
+ </para>
+
+ <para>You can safely ignore the messages that tell you to add
+ Kerberos to the <emphasis role="bold">/etc/services</emphasis>
+ file; AFS uses a default value that makes the addition
+ unnecessary. You can also ignore messages about the failure of
+ authentication.</para>
+ </listitem>
+ <listitem>
+ <para>Return to <link linkend="HDRWQ52">Starting the Database Server
+ Processes</link> and follow the remaining instructions</para>
+ </listitem>
+ </orderedlist>
+ </sect3>
+ <sect3 id="KAS007">
+ <title>Initialising Cell Security with kaserver </title>
+
+ <note>
+ <para>The following instructions should be followed in place of
+ those in <link linkend="HDRWQ53">Initializing Cell Security</link>
+ </para>
+ </note>
+
+ <para>Begin by creating the following two initial entries in the
+ Authentication Database:
+ <itemizedlist>
+ <listitem>
+ <para>A generic administrative account, called
+ <emphasis role="bold">admin</emphasis> by convention. If you
+ choose to assign a different name, substitute it throughout the
+ remainder of this document.</para>
+
+ <para>After you complete the installation of the first machine,
+ you can continue to have all administrators use the
+ <emphasis role="bold">admin</emphasis> account, or you can create
+ a separate administrative account for each of them. The latter
+ scheme implies somewhat more overhead, but provides a more
+ informative audit trail for administrative operations.</para>
+ </listitem>
+
+ <listitem>
+ <para>The entry for AFS server processes, called
+ <emphasis role="bold">afs</emphasis>. No user logs in under this
+ identity, but the Authentication Server's Ticket Granting Service
+ (TGS) module uses the associated key to encrypt the server
+ tickets that it grants to AFS clients for presentation to server
+ processes during mutual authentication. (The chapter in the
+ <emphasis>OpenAFS Administration Guide</emphasis> about cell
+ configuration and administration describes the role of server
+ encryption keys in mutual authentication.)</para>
+
+ <para>In Step <link linkend="AppendixLIWQ58">7</link>, you also
+ place the initial AFS server encryption key into the <emphasis
+ role="bold">/usr/afs/etc/KeyFile</emphasis> file. The AFS server
+ processes refer to this file to learn the server
+ encryption key when they need to decrypt server tickets.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>You also issue several commands that enable the new
+ <emphasis role="bold">admin</emphasis> user to issue privileged
+ commands in all of the AFS suites.</para>
+
+ <para>The following instructions do not configure all of the security
+ mechanisms related to the AFS Backup System. See the chapter in the
+ <emphasis>OpenAFS Administration Guide</emphasis> about configuring
+ the Backup System.
+ <orderedlist>
+ <indexterm>
+ <primary>commands</primary>
+ <secondary>kas (interactive)</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>kas commands</primary>
+ <secondary>interactive mode, entering</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>interactive mode for kas</primary>
+ <secondary>entering</secondary>
+ </indexterm>
+
+ <listitem>
+ <para>Enter <emphasis role="bold">kas</emphasis> interactive
+ mode. Because the machine is in no-authorization checking
+ mode, include the <emphasis role="bold">-noauth</emphasis> flag
+ to suppress the Authentication Server's usual prompt for a
+ password.
+<programlisting>
+ # <emphasis role="bold">kas -cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis role="bold">-noauth</emphasis>
+ ka>
+</programlisting>
+ <indexterm>
+ <primary>commands</primary>
+ <secondary>kas create</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>kas commands</primary>
+ <secondary>create</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>server encryption key</primary>
+ <secondary>in Authentication Database</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>creating</primary>
+ <secondary>server encryption key</secondary>
+ <tertiary>Authentication Database</tertiary>
+ </indexterm>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><anchor id="AppendixLIWQ54" />Issue the
+ <emphasis role="bold">kas create</emphasis> command to create
+ Authentication Database entries called
+ <emphasis role="bold">admin</emphasis> and
+ <emphasis role="bold">afs</emphasis>.</para>
+
+ <para>Do not provide passwords on the command line. Instead
+ provide them as <replaceable>afs_passwd</replaceable> and
+ <replaceable>admin_passwd</replaceable> in response to the
+ <emphasis role="bold">kas</emphasis> command interpreter's
+ prompts as shown, so that they do not appear on the standard
+ output stream.</para>
+
+ <para>You need to enter the <replaceable>afs_passwd</replaceable>
+ string only in this step and in Step
+ <link linkend="AppendixLIWQ58">7</link>, so provide a value that
+ is as long and complex as possible, preferably including numerals,
+ punctuation characters, and both uppercase and lowercase letters.
+ Also make the <replaceable>admin_passwd</replaceable> as
+ long and complex as possible, but keep in mind that
+ administrators need to enter it often. Both passwords must be
+ at least six characters long.</para>
+
+<programlisting>
+ ka> <emphasis role="bold">create afs</emphasis>
+ initial_password: <replaceable>afs_passwd</replaceable>
+ Verifying, please re-enter initial_password: <replaceable>afs_passwd</replaceable>
+ ka> <emphasis role="bold">create admin</emphasis>
+ initial_password: <replaceable>admin_passwd</replaceable>
+ Verifying, please re-enter initial_password: <replaceable>admin_passwd</replaceable>
+</programlisting>
+
+ <indexterm>
+ <primary>commands</primary>
+ <secondary>kas examine</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>kas commands</primary>
+ <secondary>examine</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>displaying</primary>
+ <secondary>server encryption key</secondary>
+ <tertiary>Authentication Database</tertiary>
+ </indexterm>
+ </listitem>
+
+ <listitem>
+ <para><anchor id="AppendixLIWQ55" />Issue the
+ <emphasis role="bold">kas examine</emphasis> command to display
+ the <emphasis role="bold">afs</emphasis> entry. The output
+ includes a checksum generated by encrypting a constant with the
+ server encryption key derived from the
+ <replaceable>afs_passwd</replaceable> string. In
+ Step <link linkend="AppendixLIWQ59">8</link> you issue the
+ <emphasis role="bold">bos listkeys</emphasis> command to verify
+ that the checksum in its output matches the checksum in this
+ output.
+<programlisting>
+ ka> <emphasis role="bold">examine afs</emphasis>
+ User data for afs
+ key (0) cksum is <replaceable>checksum</replaceable> . . .
+</programlisting>
+ <indexterm>
+ <primary>commands</primary>
+ <secondary>kas setfields</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>kas commands</primary>
+ <secondary>setfields</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>admin account</primary>
+ <secondary>setting ADMIN flag on Auth. DB entry</secondary>
+ </indexterm>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><anchor id="LIWQ56" />Issue the
+ <emphasis role="bold">kas setfields</emphasis> command to turn
+ on the <computeroutput>ADMIN</computeroutput> flag in the
+ <emphasis role="bold">admin</emphasis> entry. This enables the
+ <emphasis role="bold">admin</emphasis> user to issue privileged
+ <emphasis role="bold">kas</emphasis> commands. Then issue
+ the <emphasis role="bold">kas examine</emphasis> command to verify
+ that the <computeroutput>ADMIN</computeroutput> flag
+ appears in parentheses on the first line of the output, as shown
+ in the example.
+<programlisting>
+ ka> <emphasis role="bold">setfields admin -flags admin</emphasis>
+ ka> <emphasis role="bold">examine admin</emphasis>
+ User data for admin (ADMIN) . . .
+</programlisting>
+ <indexterm>
+ <primary>commands</primary>
+ <secondary>kas quit</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>kas commands</primary>
+ <secondary>quit</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>interactive mode for kas</primary>
+ <secondary>quitting</secondary>
+ </indexterm>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Issue the <emphasis role="bold">kas quit</emphasis>
+ command to leave <emphasis role="bold">kas</emphasis>
+ interactive mode.
+<programlisting>
+ ka> <emphasis role="bold">quit</emphasis>
+</programlisting>
+ <indexterm>
+ <primary>commands</primary>
+ <secondary>bos adduser</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>bos commands</primary>
+ <secondary>adduser</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>usr/afs/etc/UserList</primary>
+ <see>UserList file</see>
+ </indexterm>
+ <indexterm>
+ <primary>UserList file</primary>
+ <secondary>first AFS machine</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>files</primary>
+ <secondary>UserList</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>creating</primary>
+ <secondary>UserList file entry</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>admin account</primary>
+ <secondary>adding</secondary>
+ <tertiary>to UserList file</tertiary>
+ </indexterm>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><anchor id="AppendixLIWQ57" />Issue the
+ <emphasis role="bold">bos adduser</emphasis> command to add the
+ <emphasis role="bold">admin</emphasis> user to the
+ <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file.
+ This enables the <emphasis role="bold">admin</emphasis> user to
+ issue privileged <emphasis role="bold">bos</emphasis> and
+ <emphasis role="bold">vos</emphasis> commands.
+<programlisting>
+ # <emphasis role="bold">./bos adduser</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">admin -cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis
+ role="bold">-noauth</emphasis>
+</programlisting>
+ <indexterm>
+ <primary>commands</primary>
+ <secondary>bos addkey</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>bos commands</primary>
+ <secondary>addkey</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>creating</primary>
+ <secondary>server encryption key</secondary>
+ <tertiary>KeyFile file</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>server encryption key</primary>
+ <secondary>in KeyFile file</secondary>
+ </indexterm>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><anchor id="AppendixLIWQ58" />Issue the
+ <emphasis role="bold">bos addkey</emphasis> command to define
+ the AFS server encryption key in the
+ <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> file.
+ </para>
+
+ <para>Do not provide the password on the command line. Instead
+ provide it as <replaceable>afs_passwd</replaceable> in
+ response to the <emphasis role="bold">bos</emphasis> command
+ interpreter's prompts, as shown. Provide the same string as
+ in Step <link linkend="AppendixLIWQ54">2</link>.</para>
+
+<programlisting>
+ # <emphasis role="bold">./bos addkey</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">-kvno 0 -cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis
+ role="bold">-noauth</emphasis>
+ Input key: <replaceable>afs_passwd</replaceable>
+ Retype input key: <replaceable>afs_passwd</replaceable>
+</programlisting>
+
+ <indexterm>
+ <primary>commands</primary>
+ <secondary>bos listkeys</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>bos commands</primary>
+ <secondary>listkeys</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>displaying</primary>
+ <secondary>server encryption key</secondary>
+ <tertiary>KeyFile file</tertiary>
+ </indexterm>
+ </listitem>
+
+ <listitem>
+ <para><anchor id="AppendixLIWQ59" />Issue the
+ <emphasis role="bold">bos listkeys</emphasis> command to verify
+ that the checksum for the new key in the
+ <emphasis role="bold">KeyFile</emphasis> file is the same as the
+ checksum for the key in the Authentication Database's
+ <emphasis role="bold">afs</emphasis> entry, which you displayed
+ in Step <link linkend="AppendixLIWQ55">3</link>.
+<programlisting>
+ # <emphasis role="bold">./bos listkeys</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">-cell</emphasis> <<replaceable>ce
+ll name</replaceable>> <emphasis
+ role="bold">-noauth</emphasis>
+ key 0 has cksum <replaceable>checksum</replaceable>
+</programlisting></para>
+
+ <para>You can safely ignore any error messages indicating that
+ <emphasis role="bold">bos</emphasis> failed to get tickets
+ or that authentication failed.</para>
+
+ <para>If the keys are different, issue the following commands,
+ making sure that the <replaceable>afs_passwd</replaceable>
+ string is the same in each case. The
+ <replaceable>checksum</replaceable> strings reported by the
+ <emphasis role="bold">kas examine</emphasis> and
+ <emphasis role="bold">bos listkeys</emphasis> commands must
+ match; if they do not, repeat these instructions until they do,
+ using the <emphasis role="bold">-kvno</emphasis> argument to
+ increment the key version number each time.</para>
+
+<programlisting>
+ # <emphasis role="bold">./kas -cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis role="bold">-noauth</emphasis>
+ ka> <emphasis role="bold">setpassword afs -kvno 1</emphasis>
+ new_password: <replaceable>afs_passwd</replaceable>
+ Verifying, please re-enter initial_password: <replaceable>afs_passwd</replaceable>
+ ka> <emphasis role="bold">examine afs</emphasis>
+ User data for afs
+ key (1) cksum is <replaceable>checksum</replaceable> . . .
+ ka> <emphasis role="bold">quit</emphasis>
+ # <emphasis role="bold">./bos addkey</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">-kvno 1 -cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis
+ role="bold">-noauth</emphasis>
+ Input key: <replaceable>afs_passwd</replaceable>
+ Retype input key: <replaceable>afs_passwd</replaceable>
+ # <emphasis role="bold">./bos listkeys</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">-cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis
+ role="bold">-noauth</emphasis>
+ key 1 has cksum <replaceable>checksum</replaceable>
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>Proceed to
+ <link linkend="HDRWQ53a">Initializing the Protection Database</link>
+ to continue with the installation process</para>
+ </listitem>
+ </orderedlist></para>
+ </sect3>
+ </sect2>
+ <sect2 id="KAS009">
+ <title>Installing Additional Server Machines</title>
+
+ <sect3 id="KAS010">
+ <title>Starting the Authenticxation Service</title>
+ <indexterm>
+ <primary>Authentication Server</primary>
+ <secondary>starting</secondary>
+ <tertiary>new db-server machine</tertiary>
+ </indexterm>
+ <indexterm>
+ <primary>starting</primary>
+ <secondary>Authentication Server</secondary>
+ <tertiary>new db-server machine</tertiary>
+ </indexterm>
+ <para>In addition to the instructions in the main guide, you must
+ also start the Authentication Server on the new database machine,
+ as detailed below</para>
+
+ <orderedlist>
+ <listitem>
+ <para><anchor id="LIWQ118" />Start the Authentication Server
+ (the <emphasis role="bold">kaserver</emphasis> process).
+<programlisting>
+ % <emphasis role="bold">bos create</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">kaserver simple /usr/afs/bin/kaserver</emphasis>
+</programlisting> </para>
+ </listitem>
+
+ <listitem>
+ <para>Return to <link linkend="LIWQ119">starting the backup server</link></para>
+ </listitem>
+ </orderedlist>
+ </sect3>
+ </sect2>
+
+ <sect2 id="KAS011">
+ <title>Enabling AFS login with kaserver</title>
+ <para>The authentication system of every machine should be modified so
+ that users obtain an AFS token as they log into the local file system.
+ Using AFS is simpler and more convenient for your users if you make the
+ modifications on all client machines. Otherwise users must perform a two
+ step login procedure (login to the local system, and then issue the
+ <emphasis role="bold">klog</emphasis> command.</para>
+
+ <para>For convenience, the following sections group this procedure by
+ system type. Proceed to the appropriate section.
+ <itemizedlist>
+ <listitem>
+ <para>
+ <link linkend="KAS012">Enabling AFS Login on AIX Systems</link>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="KAS013">Enabling AFS Login on HP-UX Systems</link>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="KAS014">Enabling AFS Login on IRIX Systems</link>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="KAS015">Enabling AFS Login on Linux Systems</link>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="KAS016">Enabling AFS login on Solaris Systems</link>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+ <sect2 id="KAS012">
+ <title>Enabling kaserver based AFS login</title>
+
+ <para>Now incorporate AFS into the AIX secondary authentication system.
+ <orderedlist>
+ <listitem>
+ <para>Issue the <emphasis role="bold">ls</emphasis> command to
+ verify that the <emphasis role="bold">afs_dynamic_auth</emphasis>
+ and <emphasis role="bold">afs_dynamic_kerbauth</emphasis>
+ programs are installed in the local
+ <emphasis role="bold">/usr/vice/etc</emphasis> directory.
+<programlisting>
+ # <emphasis role="bold">ls /usr/vice/etc</emphasis>
+</programlisting>
+ </para>
+
+ <para>If the files do not exist, unpack the
+ OpenAFS Binary Distribution for AIX (if it is not already),
+ change directory as indicated, and copy them.</para>
+
+<programlisting>
+ # <emphasis role="bold">cd /tmp/afsdist/rs_aix42/root.client/usr/vice/etc</emphasis>
+ # <emphasis role="bold">cp -p afs_dynamic* /usr/vice/etc</emphasis>
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>Edit the local
+ <emphasis role="bold">/etc/security/user</emphasis> file, making
+ changes to the indicated stanzas:
+ <itemizedlist>
+ <listitem>
+ <para>In the default stanza, set the
+ <computeroutput>registry</computeroutput> attribute to
+ <emphasis role="bold">DCE</emphasis> (not to
+ <emphasis role="bold">AFS</emphasis>), as follows:
+<programlisting>
+ registry = DCE
+</programlisting>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>In the default stanza, set the
+ <computeroutput>SYSTEM</computeroutput> attribute as
+ indicated.</para>
+
+ <para>If the machine is an AFS client only, set the
+ following value:</para>
+<programlisting>
+ SYSTEM = "AFS OR (AFS[UNAVAIL] AND compat[SUCCESS])"
+</programlisting>
+
+ <para>If the machine is both an AFS and a DCE client,
+ set the following value (it must appear on a single line in
+ the file):</para>
+<programlisting>
+ SYSTEM = "DCE OR DCE[UNAVAIL] OR AFS OR (AFS[UNAVAIL] \
+ AND compat[SUCCESS])"
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>In the <computeroutput>root</computeroutput>
+ stanza, set the <computeroutput>registry</computeroutput>
+ attribute as follows. It enables the local superuser
+ <emphasis role="bold">root</emphasis> to log into the local
+ file system only, based on the password listed in the
+ local password file.
+<programlisting>
+ root:
+ registry = files
+</programlisting>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Edit the local
+ <emphasis role="bold">/etc/security/login.cfg</emphasis> file,
+ creating or editing the indicated stanzas:
+ <itemizedlist>
+ <listitem>
+ <para>In the <computeroutput>DCE</computeroutput> stanza,
+ set the <computeroutput>program</computeroutput>
+ attribute as follows.</para>
+
+ <para>If you use the AFS Authentication Server
+ (<emphasis role="bold">kaserver</emphasis> process):</para>
+<programlisting>
+ DCE:
+ program = /usr/vice/etc/afs_dynamic_auth
+</programlisting>
+
+ <para>If you use a Kerberos v4 implementation of AFS
+ authentication:</para>
+
+<programlisting>
+ DCE:
+ program = /usr/vice/etc/afs_dynamic_kerbauth
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>In the <computeroutput>AFS</computeroutput> stanza,
+ set the <computeroutput>program</computeroutput>
+ attribute as follows.</para>
+
+ <para>If you use the AFS Authentication Server
+ (<emphasis role="bold">kaserver</emphasis> process):</para>
+<programlisting>
+ AFS:
+ program = /usr/vice/etc/afs_dynamic_auth
+</programlisting>
+
+ <para>If you use a Kerberos v4 implementation of AFS
+ authentication:</para>
+<programlisting>
+ AFS:
+ program = /usr/vice/etc/afs_dynamic_kerbauth
+</programlisting>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ <listitem>
+ <para>Proceed to
+ <link linkend="HDRWQ50">Starting the BOS Server</link>,
+ if you are installing your first file server machine;
+ <link linkend="HDRWQ108">Starting Server Programs</link>,
+ if you are installing an additional file server machine; or
+ <link linkend="HDRWQ145">Loading and Creating Client Files</link>
+ if you are installating a client</para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </sect2>
+ <sect2 id="KAS013">
+ <title>Enabling kaserver based AFS Login on HP-UX systems</title>
+
+ <para>At this point you incorporate AFS into the operating system's
+ Pluggable Authentication Module (PAM) scheme. PAM integrates all
+ authentication mechanisms on the machine, including login, to provide
+ the security infrastructure for authenticated access to and from the
+ machine.</para>
+
+ <para>Explaining PAM is beyond the scope of this document. It is
+ assumed that you understand the syntax and meanings of settings in the
+ PAM configuration file (for example, how the
+ <computeroutput>other</computeroutput> entry works, the effect of
+ marking an entry as <computeroutput>required</computeroutput>,
+ <computeroutput>optional</computeroutput>, or
+ <computeroutput>sufficient</computeroutput>, and so on).</para>
+
+ <para>The following instructions explain how to alter the entries in
+ the PAM configuration file for each service for which you
+ wish to use AFS authentication. Other configurations possibly also
+ work, but the instructions specify the recommended and
+ tested configuration.</para>
+
+ <note>
+ <para>The instructions specify that you mark each entry as
+ <computeroutput>optional</computeroutput>. However, marking some
+ modules as optional can mean that they grant access to the
+ corresponding service even when the user does not meet all of the
+ module's requirements. In some operating system revisions, for
+ example, if you mark as optional the module that controls
+ login via a dial-up connection, it allows users to login without
+ providing a password. See the <emphasis>OpenAFS Release
+ Notes</emphasis> for a discussion of any limitations that apply to
+ this operating system.</para>
+
+ <para>Also, with some operating system versions you must install
+ patches for PAM to interact correctly with certain
+ authentication programs. For details, see the
+ <emphasis>OpenAFS Release Notes</emphasis>.</para>
+ </note>
+
+ <para>The recommended AFS-related entries in the PAM configuration
+ file make use of one or more of the following three
+ attributes.
+ <variablelist>
+ <varlistentry>
+ <term><emphasis role="bold"><computeroutput>try_first_pass</computeroutput></emphasis></term>
+
+ <listitem>
+ <para>This is a standard PAM attribute that can be included on
+ entries after the first one for a service; it directs
+ the module to use the password that was provided to the first
+ module. For the AFS module, it means that AFS
+ authentication succeeds if the password provided to the module
+ listed first is the user's correct AFS password. For
+ further discussion of this attribute and its alternatives, see
+ the operating system's PAM documentation.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold"><computeroutput>ignore_root</computeroutput></emphasis></term>
+
+ <listitem>
+ <para>This attribute, specific to the AFS PAM module, directs it
+ to ignore not only the local superuser <emphasis
+ role="bold">root</emphasis>, but also any user with UID 0
+ (zero).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold"><computeroutput>setenv_password_expires</computeroutput></emphasis></term>
+
+ <listitem>
+ <para>This attribute, specific to the AFS PAM module, sets the
+ environment variable PASSWORD_EXPIRES to the expiration
+ date of the user's AFS password, which is recorded in the
+ Authentication Database.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>Perform the following steps to enable AFS login.
+ <orderedlist>
+ <listitem>
+ <para>Unpack the OpenAFS Binary Distribution for HP-UX into the
+ <emphasis role="bold">/tmp/afsdist</emphasis> directory, if it is
+ not already.
+ Then change directory as indicated.
+<programlisting>
+ # <emphasis role="bold">cd /usr/lib/security</emphasis>
+</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>Copy the AFS authentication library file to the
+ <emphasis role="bold">/usr/lib/security</emphasis> directory. Then
+ create a symbolic link to it whose name does not mention the
+ version. Omitting the version eliminates the need to edit
+ the PAM configuration file if you later update the library
+ file.</para>
+
+ <para>If you use the AFS Authentication Server
+ (<emphasis role="bold">kaserver</emphasis> process) in the cell:</para>
+
+<programlisting>
+ # <emphasis role="bold">cp /tmp/afsdist/hp_ux110/lib/pam_afs.so.1 .</emphasis>
+ # <emphasis role="bold">ln -s pam_afs.so.1 pam_afs.so</emphasis>
+</programlisting>
+
+ <para>If you use a Kerberos implementation of AFS authentication:</para>
+
+<programlisting>
+ # <emphasis role="bold">cp /tmp/afsdist/hp_ux110/lib/pam_afs.krb.so.1 .</emphasis>
+ # <emphasis role="bold">ln -s pam_afs.krb.so.1 pam_afs.so</emphasis>
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>Edit the
+ <computeroutput>Authentication management</computeroutput>
+ section of the HP-UX PAM configuration file,
+ <emphasis role="bold">/etc/pam.conf</emphasis> by convention. The
+ entries in this section have the value
+ <computeroutput>auth</computeroutput> in their second field.</para>
+
+ <para>First edit the standard entries, which refer to the
+ HP-UX PAM module (usually, the file <emphasis
+ role="bold">/usr/lib/security/libpam_unix.1</emphasis>) in their
+ fourth field. For each service for which you want to
+ use AFS authentication, edit the third field of its entry to read
+ <computeroutput>optional</computeroutput>. The
+ <emphasis role="bold">pam.conf</emphasis> file in the HP-UX
+ distribution usually includes standard entries for the
+ <emphasis role="bold">login</emphasis> and
+ <emphasis role="bold">ftp</emphasis> services, for instance.</para>
+
+ <para>If there are services for which you want to use AFS
+ authentication, but for which the <emphasis
+ role="bold">pam.conf</emphasis> file does not already include a
+ standard entry, you must create that entry and place the
+ value <computeroutput>optional</computeroutput> in its third field.
+ For instance, the HP-UX <emphasis role="bold">pam.conf</emphasis>
+ file does not usually include standard entries for the <emphasis
+ role="bold">remsh</emphasis> or
+ <emphasis role="bold">telnet</emphasis> services.</para>
+
+ <para>Then create an AFS-related entry for each service, placing it
+ immediately below the standard entry. The following
+ example shows what the
+ <computeroutput>Authentication Management</computeroutput> section
+ looks like after you have you
+ edited or created entries for the services mentioned previously.
+ Note that the example AFS entries appear on two lines
+ only for legibility.</para>
+
+<programlisting>
+ login auth optional /usr/lib/security/libpam_unix.1
+ login auth optional /usr/lib/security/pam_afs.so \
+ try_first_pass ignore_root setenv_password_expires
+ ftp auth optional /usr/lib/security/libpam_unix.1
+ ftp auth optional /usr/lib/security/pam_afs.so \
+ try_first_pass ignore_root
+ remsh auth optional /usr/lib/security/libpam_unix.1
+ remsh auth optional /usr/lib/security/pam_afs.so \
+ try_first_pass ignore_root
+ telnet auth optional /usr/lib/security/libpam_unix.1
+ telnet auth optional /usr/lib/security/pam_afs.so \
+ try_first_pass ignore_root setenv_password_expires
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>If you use the Common Desktop Environment (CDE) on the
+ machine and want users to obtain an AFS token as they log
+ in, also add or edit the following four entries in the
+ <computeroutput>Authentication management</computeroutput>
+ section. Note that the AFS-related entries appear on two lines
+ here only for legibility.
+<programlisting>
+ dtlogin auth optional /usr/lib/security/libpam_unix.1
+ dtlogin auth optional /usr/lib/security/pam_afs.so \
+ try_first_pass ignore_root
+ dtaction auth optional /usr/lib/security/libpam_unix.1
+ dtaction auth optional /usr/lib/security/pam_afs.so \
+ try_first_pass ignore_root
+</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>Proceed to
+ <link linkend="HDRWQ50">Starting the BOS Server</link> if you
+ are installing your first file server;
+ <link linkend="HDRWQ108">Starting Server Programs</link> if you
+ are installing an additional file server machine; or
+ <link linkend="HDRWQ145">Loading and Creating Client Files.</link>
+ if you are installing a client.</para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </sect2>
+ <sect2 id="KAS014">
+ <title>Enabling kaserver based AFS Login on IRIX Systems</title>
+
+ <para>The standard IRIX command-line
+ <emphasis role="bold">login</emphasis> program and the graphical
+ <emphasis role="bold">xdm</emphasis> login program both automatically
+ grant an AFS token when AFS is incorporated into the machine's
+ kernel. However, some IRIX distributions use another login utility by
+ default, and it does not necessarily incorporate the required AFS
+ modifications. If that is the case, you must disable the default
+ utility if you want AFS users to obtain AFS tokens at login. For
+ further discussion, see the
+ <emphasis>OpenAFS Release Notes</emphasis>.</para>
+
+ <para>If you configure the machine to use an AFS-modified login
+ utility, then the <emphasis role="bold">afsauthlib.so</emphasis> and
+ <emphasis role="bold">afskauthlib.so</emphasis> files (included in the
+ AFS distribution) must reside in the
+ <emphasis role="bold">/usr/vice/etc</emphasis> directory. Issue the
+ <emphasis role="bold">ls</emphasis> command to verify.</para>
+
+<programlisting>
+ # <emphasis role="bold">ls /usr/vice/etc</emphasis>
+</programlisting>
+
+ <para>If the files do not exist, unpack the OpenAFS Binary Distribution
+ for IRIX (if it is not already), change directory as indicated, and copy
+ them.</para>
+
+<programlisting>
+ # <emphasis role="bold">cd /tmp/afsdist/sgi_65/root.client/usr/vice/etc</emphasis>
+ # <emphasis role="bold">cp -p *authlib* /usr/vice/etc</emphasis>
+</programlisting>
+
+ <para>After taking any necessary action, proceed to
+ <link linkend="HDRWQ50">Starting the BOS Server</link> if you
+ are installing your first file server;
+ <link linkend="HDRWQ108">Starting Server Programs</link> if you
+ are installing an additional file server machine; or
+ <link linkend="HDRWQ145">Loading and Creating Client Files</link>
+ if you are installing a client.</para>
+ </sect2>
+ <sect2 id="KAS015">
+ <title>Enabling kaserver based AFS Login on Linux Systems</title>
+
+ <para>At this point you incorporate AFS into the operating system's
+ Pluggable Authentication Module (PAM) scheme. PAM integrates all
+ authentication mechanisms on the machine, including login, to provide
+ the security infrastructure for authenticated access to and from the
+ machine.</para>
+
+ <para>Explaining PAM is beyond the scope of this document. It is
+ assumed that you understand the syntax and meanings of settings in the
+ PAM configuration file (for example, how the
+ <computeroutput>other</computeroutput> entry works, the effect of
+ marking an entry as <computeroutput>required</computeroutput>,
+ <computeroutput>optional</computeroutput>, or
+ <computeroutput>sufficient</computeroutput>, and so on).</para>
+
+ <para>The following instructions explain how to alter the entries in
+ the PAM configuration file for each service for which you
+ wish to use AFS authentication. Other configurations possibly also
+ work, but the instructions specify the recommended and
+ tested configuration.</para>
+
+ <para>The recommended AFS-related entries in the PAM configuration
+ file make use of one or more of the following three
+ attributes.
+ <variablelist>
+ <title>Authentication Management</title>
+
+ <varlistentry>
+ <term><emphasis role="bold"><computeroutput>try_first_pass</computeroutput></emphasis></term>
+
+ <listitem>
+ <para>This is a standard PAM attribute that can be included on
+ entries after the first one for a service; it directs
+ the module to use the password that was provided to the first
+ module. For the AFS module, it means that AFS
+ authentication succeeds if the password provided to the module
+ listed first is the user's correct AFS password. For
+ further discussion of this attribute and its alternatives, see
+ the operating system's PAM documentation.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold"><computeroutput>ignore_root</computeroutput></emphasis></term>
+
+ <listitem>
+ <para>This attribute, specific to the AFS PAM module, directs it
+ to ignore not only the local superuser <emphasis
+ role="bold">root</emphasis>, but also any user with UID
+ 0 (zero).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold"><computeroutput>ignore_uid </computeroutput><emphasis>uid</emphasis></emphasis></term>
+
+ <listitem>
+ <para>This option is an extension of the "ignore_root" switch.
+ The additional parameter is a limit. Users with a uid
+ up to the given parameter are ignored by
+ <emphasis>pam_afs.so</emphasis>. Thus, a system administrator
+ still has the
+ opportunity to add local user accounts to his system by choosing
+ between "low" and "high" user ids. An example
+ /etc/passwd file for "ignore_uid 100" may have entries like these:
+<programlisting>
+ .
+ .
+afsuserone:x:99:100::/afs/afscell/u/afsuserone:/bin/bash
+afsusertwo:x:100:100::/afs/afscell/u/afsusertwo:/bin/bash
+localuserone:x:101:100::/home/localuserone:/bin/bash
+localusertwo:x:102:100::/home/localusertwo:/bin/bash
+ .
+ .
+</programlisting>
+ AFS accounts should be locked in the file /etc/shadow like this:
+<programlisting>
+ .
+ .
+afsuserone:!!:11500:0:99999:7:::
+afsusertwo:!!:11500:0:99999:7:::
+localuserone:<thelocaluserone'skey>:11500:0:99999:7:::
+localusertwo:<thelocalusertwo'skey>:11500:0:99999:7:::
+ .
+ .
+</programlisting>
+ There is no need to store a local key in this file since the AFS
+ password is sent and verfied at the AFS cell server!</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold"><computeroutput>setenv_password_expires</computeroutput></emphasis></term>
+
+ <listitem>
+ <para>This attribute, specific to the AFS PAM module, sets the
+ environment variable PASSWORD_EXPIRES to the expiration
+ date of the user's AFS password, which is recorded in the
+ Authentication Database.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold"><computeroutput>set_token</computeroutput></emphasis></term>
+
+ <listitem>
+ <para>Some applications don't call
+ <emphasis>pam_setcred()</emphasis> in order to retrieve the
+ appropriate credentials (here the AFS token) for their session.
+ This switch sets the credentials already in
+ <emphasis>pam_sm_authenticate()</emphasis> obsoleting a call to
+ <emphasis>pam_setcred()</emphasis>. <emphasis
+ role="bold">Caution: Don't use this switch for applications which
+ do call <emphasis>pam_setcred()</emphasis>!</emphasis> One
+ example for an application not calling
+ <emphasis>pam_setcred()</emphasis> are older versions of the
+ samba server. Nevertheless, using applications with
+ working pam session management is recommended as this setup
+ conforms better with the PAM definitions.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold"><computeroutput>refresh_token</computeroutput></emphasis></term>
+
+ <listitem>
+ <para>This options is identical to "set_token" except that no
+ new PAG is generated. This is necessary to handle
+ processes like xlock or xscreensaver. It is not enough to just
+ unlock the screen for a user who
+ reactivated his session by typing in the correct AFS password, but
+ one may also need fresh tokens with a full lifetime in
+ order to work on, and the new token must be refreshed in the
+ already existing PAG for the processes that have been
+ started. This is achieved using this option.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold"><computeroutput>use_klog</computeroutput></emphasis></term>
+
+ <listitem>
+ <para>Activating this switch causes authentication to be done by
+ calling the external program "klog". One program requiring
+ this is for example <emphasis>kdm</emphasis> of KDE 2.x.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold"><computeroutput>dont_fork</computeroutput></emphasis></term>
+
+ <listitem>
+ <para>Usually, the password verification and token establishment
+ is performed in a sub process. Using this option pam_afs does not
+ fork and performs all actions in a single process.
+ <emphasis role="bold">Only use this option in cases where you
+ notice serious problems caused by the sub process.</emphasis>
+ This option has been developed in respect to
+ the "mod_auth_pam"-project (see also
+ <ulink url="http://pam.sourceforge.net/mod_auth_pam/">mod_auth_pam</ulink>).
+ The mod_auth_pam module enables PAM authentication for the apache
+ http server package.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <variablelist>
+ <title>Session Management</title>
+
+ <varlistentry>
+ <term><emphasis role="bold"><computeroutput>no_unlog</computeroutput></emphasis></term>
+
+ <listitem>
+ <para>Normally the tokens are deleted (in memory) after the
+ session ends. Using this option causes the tokens to be left
+ untouched. <emphasis role="bold">This behaviour was the default
+ in pam_afs until openafs-1.1.1!</emphasis></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold"><computeroutput>remainlifetime</computeroutput> <emphasis>sec</emphasis></emphasis></term>
+
+ <listitem>
+ <para>The tokens are kept active for <emphasis>sec</emphasis>
+ seconds before they are deleted. X display managers i.e.
+ are used to inform the applications started in the X session
+ before the logout and then end themselves. If the token
+ was deleted immediately the applications would have no chance
+ to write back their settings to i.e. the user's AFS home
+ space. This option may help to avoid the problem.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist></para>
+
+ <para>Perform the following steps to enable AFS login.
+ <orderedlist>
+ <listitem>
+ <para>Unpack the OpenAFS Binary Distribution for Linux into the
+ <emphasis role="bold">/tmp/afsdist/</emphasis> directory, if it is
+ not already.
+ Then change to the directory for PAM modules, which depends on which Linux distribution you are using.</para>
+
+ <para>If you are using a Linux distribution from Red Hat Software:</para>
+
+ <programlisting>
+ # <emphasis role="bold">cd /lib/security</emphasis>
+</programlisting>
+
+ <para>If you are using another Linux distribution:</para>
+
+ <programlisting>
+ # <emphasis role="bold">cd /usr/lib/security</emphasis>
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>Copy the appropriate AFS authentication library file to the
+ directory to which you changed in the previous step.
+ Create a symbolic link whose name does not mention the version.
+ Omitting the version eliminates the need to edit the PAM
+ configuration file if you later update the library file.</para>
+
+ <para>If you use the AFS Authentication Server
+ (<emphasis role="bold">kaserver</emphasis> process):</para>
+<programlisting>
+ # <emphasis role="bold">cp /cdrom/i386_linux22/lib/pam_afs.so.1 .</emphasis>
+ # <emphasis role="bold">ln -s pam_afs.so.1 pam_afs.so</emphasis>
+</programlisting>
+
+ <para>If you use a Kerberos implementation of AFS
+ authentication:</para>
+<programlisting>
+ # <emphasis role="bold">cp /cdrom/i386_linux22/lib/pam_afs.krb.so.1 .</emphasis>
+ # <emphasis role="bold">ln -s pam_afs.krb.so.1 pam_afs.so</emphasis>
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>For each service with which you want to use AFS
+ authentication, insert an entry for the AFS PAM module into the
+ <computeroutput>auth</computeroutput> section of the service's
+ PAM configuration file. (Linux uses a separate
+ configuration file for each service, unlike some other operating
+ systems which list all services in a single file.) Mark
+ the entry as <computeroutput>sufficient</computeroutput> in the
+ second field.</para>
+
+ <para>Place the AFS entry below any entries that impose conditions
+ under which you want the service to fail for a user
+ who does not meet the entry's requirements. Mark these entries
+ <computeroutput>required</computeroutput>. Place the AFS
+ entry above any entries that need to execute only if AFS
+ authentication fails.</para>
+
+ <para>Insert the following AFS entry if using the Red Hat
+ distribution:</para>
+<programlisting>
+ auth sufficient /lib/security/pam_afs.so try_first_pass ignore_root
+</programlisting>
+
+ <para>Insert the following AFS entry if using another
+ distribution:</para>
+
+<programlisting>
+ auth sufficient /usr/lib/security/pam_afs.so try_first_pass ignore_root
+</programlisting>
+
+ <para>Check the PAM config files also for "session" entries. If
+ there are lines beginning with "session" then please
+ insert this line too:</para>
+
+<programlisting>
+ session optional /lib/security/pam_afs.so
+</programlisting>
+
+ <para>or</para>
+
+<programlisting>
+ session optional /usr/lib/security/pam_afs.so
+</programlisting>
+
+ <para>This guarantees that the user's tokens are deleted from
+ memory after his session ends so that no other user
+ coincidently gets those tokens without authorization! The
+ following examples illustrate the recommended configuration of
+ the configuration file for several services:
+ <variablelist>
+ <title>Authentication Management</title>
+
+ <varlistentry>
+ <term>(<emphasis role="bold">/etc/pam.d/login</emphasis>)</term>
+
+ <listitem>
+ <para>
+<programlisting>
+ #%PAM-1.0
+ auth required /lib/security/pam_securetty.so
+ auth required /lib/security/pam_nologin.so
+ auth sufficient /lib/security/pam_afs.so try_first_pass ignore_root
+ # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ #This enables AFS authentication for every user but root
+ auth required /lib/security/pam_pwdb.so shadow nullok
+ account required /lib/security/pam_pwdb.so
+ password required /lib/security/pam_cracklib.so
+ password required /lib/security/pam_pwdb.so shadow nullok use_authtok
+ session optional /lib/security/pam_afs.so
+ #Make sure tokens are deleted after the user logs out
+ session required /lib/security/pam_pwdb.so
+</programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>(<emphasis role="bold">/etc/pam.d/samba</emphasis>)</term>
+
+ <listitem>
+ <para>
+<programlisting>
+ auth required /lib/security/pam_afs.so ignore_uid 100 set_token
+ # ^^^^^^^^^^^^^^^^^^^^^^^^
+ #Here, users with uid>100 are considered to belong to the AFS and users
+ #with uid<=100 are ignored by pam_afs. The token is retrieved already in
+ #pam_sm_authenticate() (this is an example pam config for a samba version
+ #that does not call pam_setcred(), it also does no sense to include session
+ #entries here since they would be ignored by this version of samba ).
+ account required /lib/security/pam_pwdb.so
+</programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>(<emphasis role="bold">/etc/pam.d/xscreensaver</emphasis>)</term>
+
+ <listitem>
+ <para>
+<programlisting>
+ auth sufficient /lib/security/pam_afs.so ignore_uid 100 refresh_token
+ # ^^^^^^^^^^^^^
+ #Avoid generating a new PAG for the new tokens, use the already existing PAG and
+ #establish a fresh token in it.
+ auth required /lib/security/pam_pwdb.so try_first_pass
+</programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>(<emphasis role="bold">/etc/pam.d/httpd</emphasis>)</term>
+
+ <listitem>
+ <para>
+<programlisting>
+ auth required /lib/security/pam_afs.so ignore_uid 100 dont_fork
+ # ^^^^^^^^^
+ #Don't fork for the verification of the password.
+</programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <variablelist>
+ <title>Session Management</title>
+
+ <varlistentry>
+ <term>(<emphasis role="bold">/etc/pam.d/su</emphasis>)</term>
+
+ <listitem>
+ <para>
+<programlisting>
+ auth sufficient /lib/security/pam_afs.so ignore_uid 100
+ auth required /lib/security/pam_pwdb.so try_first_pass
+ account required /lib/security/pam_pwdb.so
+ password required /lib/security/pam_cracklib.so
+ password required /lib/security/pam_pwdb.so use_authtok
+ session required /lib/security/pam_pwdb.so
+ session optional /lib/security/pam_afs.so no_unlog
+ # ^^^^^^^^
+ #Don't delete the token in this case, since the user may still
+ #need it (for example if somebody logs in and changes to root
+ #afterwards he may still want to access his home space in AFS).
+ session required /lib/security/pam_login_access.so
+ session optional /lib/security/pam_xauth.so
+</programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>(<emphasis role="bold">/etc/pam.d/xdm</emphasis>)</term>
+
+ <listitem>
+ <para>
+<programlisting>
+ auth required /lib/security/pam_nologin.so
+ auth required /lib/security/pam_login_access.so
+ auth sufficient /lib/security/pam_afs.so ignore_uid 100 use_klog
+ auth required /lib/security/pam_pwdb.so try_first_pass
+ account required /lib/security/pam_pwdb.so
+ password required /lib/security/pam_cracklib.so
+ password required /lib/security/pam_pwdb.so shadow nullok use_authtok
+ session optional /lib/security/pam_afs.so remainlifetime 10
+ # ^^^^^^^^^^^^^^^^^
+ #Wait 10 seconds before deleting the AFS tokens in order to give
+ #the programs of the X session some time to save their settings
+ #to AFS.
+ session required /lib/security/pam_pwdb.so
+</programlisting>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist></para>
+ </listitem>
+ <listitem>
+ <para>After taking any necessary action, proceed to
+ <link linkend="HDRWQ50">Starting the BOS Server</link> if you
+ are installing your first file server;
+ <link linkend="HDRWQ108">Starting Server Programs</link> if you
+ are installing an additional file server machine; or
+ <link linkend="HDRWQ145"></link> if you are installing a client.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </sect2>
+ <sect2 id="KAS016">
+ <title>Enabling kaserver based AFS Login on Solaris Systems</title>
+
+ <para>At this point you incorporate AFS into the operating system's
+ Pluggable Authentication Module (PAM) scheme. PAM
+ integrates all authentication mechanisms on the machine, including
+ login, to provide the security infrastructure for
+ authenticated access to and from the machine.</para>
+
+ <para>Explaining PAM is beyond the scope of this document. It is
+ assumed that you understand the syntax and meanings of
+ settings in the PAM configuration file (for example, how the
+ <computeroutput>other</computeroutput> entry works, the effect of
+ marking an entry as <computeroutput>required</computeroutput>,
+ <computeroutput>optional</computeroutput>, or
+ <computeroutput>sufficient</computeroutput>, and so on).</para>
+
+ <para>The following instructions explain how to alter the entries in the
+ PAM configuration file for each service for which you
+ wish to use AFS authentication. Other configurations possibly also
+ work, but the instructions specify the recommended and
+ tested configuration.</para>
+
+ <note>
+ <para>The instructions specify that you mark each entry as
+ <computeroutput>optional</computeroutput>. However, marking some
+ modules as optional can mean that they grant access to the
+ corresponding service even when the user does not meet all of the
+ module's requirements. In some operating system revisions,
+ for example, if you mark as optional the module that controls
+ login via a dial-up connection, it allows users to login without
+ providing a password. See the <emphasis>OpenAFS Release
+ Notes</emphasis> for a discussion of any limitations that apply to
+ this operating system.</para>
+
+ <para>Also, with some operating system versions you must install
+ patches for PAM to interact correctly with certain
+ authentication programs. For details, see the
+ <emphasis>OpenAFS Release Notes</emphasis>.</para>
+ </note>
+
+ <para>The recommended AFS-related entries in the PAM configuration file
+ make use of one or more of the following three
+ attributes.
+ <variablelist>
+ <title>Authentication Management</title>
+
+ <varlistentry>
+ <term><emphasis role="bold"><computeroutput>try_first_pass</computeroutput></emphasis></term>
+
+ <listitem>
+ <para>This is a standard PAM attribute that can be included on
+ entries after the first one for a service; it directs
+ the module to use the password that was provided to the first
+ module. For the AFS module, it means that AFS
+ authentication succeeds if the password provided to the module
+ listed first is the user's correct AFS password. For
+ further discussion of this attribute and its alternatives, see
+ the operating system's PAM documentation.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold"><computeroutput>ignore_root</computeroutput></emphasis></term>
+
+ <listitem>
+ <para>This attribute, specific to the AFS PAM module, directs it
+ to ignore not only the local superuser <emphasis
+ role="bold">root</emphasis>, but also any user with UID 0
+ (zero).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><emphasis role="bold"><computeroutput>setenv_password_expires</computeroutput></emphasis></term>
+
+ <listitem>
+ <para>This attribute, specific to the AFS PAM module, sets the
+ environment variable PASSWORD_EXPIRES to the expiration
+ date of the user's AFS password, which is recorded in the
+ Authentication Database.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist></para>
+
+ <para>Perform the following steps to enable AFS login. <orderedlist>
+ <listitem>
+ <para>Unpack the OpenAFS Binary Distribution for Solaris into the
+ <emphasis role="bold">/cdrom</emphasis> directory, if it is not
+ already.
+ Then change directory as indicated.
+<programlisting>
+ # <emphasis role="bold">cd /usr/lib/security</emphasis>
+</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>Copy the AFS authentication library file to the
+ <emphasis role="bold">/usr/lib/security</emphasis> directory. Then
+ create a symbolic link to it whose name does not mention the
+ version. Omitting the version eliminates the need to edit
+ the PAM configuration file if you later update the library
+ file.</para>
+
+ <para>If you use the AFS Authentication Server
+ (<emphasis role="bold">kaserver</emphasis> process):</para>
+
+<programlisting>
+ # <emphasis role="bold">cp /tmp/afsdist/sun4x_56/lib/pam_afs.so.1 .</emphasis>
+ # <emphasis role="bold">ln -s pam_afs.so.1 pam_afs.so</emphasis>
+</programlisting>
+
+ <para>If you use a Kerberos implementation of AFS authentication:</para>
+
+<programlisting>
+ # <emphasis role="bold">cp /tmp/afsdist/sun4x_56/lib/pam_afs.krb.so.1 .</emphasis>
+ # <emphasis role="bold">ln -s pam_afs.krb.so.1 pam_afs.so</emphasis>
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>Edit the
+ <computeroutput>Authentication management</computeroutput> section
+ of the Solaris PAM configuration file,
+ <emphasis role="bold">/etc/pam.conf</emphasis> by convention.
+ The entries in this section have the value
+ <computeroutput>auth</computeroutput> in their second field.</para>
+
+ <para>First edit the standard entries, which refer to the
+ Solaris PAM module (usually, the file <emphasis
+ role="bold">/usr/lib/security/pam_unix.so.1</emphasis>) in their
+ fourth field. For each service for which you want to
+ use AFS authentication, edit the third field of its entry to read
+ <computeroutput>optional</computeroutput>. The
+ <emphasis role="bold">pam.conf</emphasis> file in the Solaris
+ distribution usually includes standard entries for the
+ <emphasis role="bold">login</emphasis>,
+ <emphasis role="bold">rlogin</emphasis>, and <emphasis
+ role="bold">rsh</emphasis> services, for instance.</para>
+
+ <para>If there are services for which you want to use AFS
+ authentication, but for which the <emphasis
+ role="bold">pam.conf</emphasis> file does not already include a
+ standard entry, you must create that entry and place the
+ value <computeroutput>optional</computeroutput> in its third field.
+ For instance, the Solaris
+ <emphasis role="bold">pam.conf</emphasis> file does not usually
+ include standard entries for the
+ <emphasis role="bold">ftp</emphasis> or
+ <emphasis role="bold">telnet</emphasis> services.</para>
+
+ <para>Then create an AFS-related entry for each service, placing it
+ immediately below the standard entry. The following
+ example shows what the
+ <computeroutput>Authentication Management</computeroutput>
+ section looks like after you have you edited or created entries
+ for the services mentioned previously. Note that the example AFS
+ entries appear on two lines
+ only for legibility.</para>
+
+<programlisting>
+ login auth optional /usr/lib/security/pam_unix.so.1
+ login auth optional /usr/lib/security/pam_afs.so \
+ try_first_pass ignore_root setenv_password_expires
+ rlogin auth optional /usr/lib/security/pam_unix.so.1
+ rlogin auth optional /usr/lib/security/pam_afs.so \
+ try_first_pass ignore_root setenv_password_expires
+ rsh auth optional /usr/lib/security/pam_unix.so.1
+ rsh auth optional /usr/lib/security/pam_afs.so \
+ try_first_pass ignore_root
+ ftp auth optional /usr/lib/security/pam_unix.so.1
+ ftp auth optional /usr/lib/security/pam_afs.so \
+ try_first_pass ignore_root
+ telnet auth optional /usr/lib/security/pam_unix.so.1
+ telnet auth optional /usr/lib/security/pam_afs.so \
+ try_first_pass ignore_root setenv_password_expires
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>If you use the Common Desktop Environment (CDE) on the
+ machine and want users to obtain an AFS token as they log
+ in, also add or edit the following four entries in the
+ <computeroutput>Authentication management</computeroutput>
+ section. Note that the AFS-related entries appear on two lines
+ here only for legibility.
+<programlisting>
+ dtlogin auth optional /usr/lib/security/pam_unix.so.1
+ dtlogin auth optional /usr/lib/security/pam_afs.so \
+ try_first_pass ignore_root
+ dtsession auth optional /usr/lib/security/pam_unix.so.1
+ dtsession auth optional /usr/lib/security/pam_afs.so \
+ try_first_pass ignore_root
+</programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>Proceed to
+ <link linkend="HDRWQ49a">Editing the File Systems Clean-up Script
+ on Solaris Systems in the server instructions </link> if you are
+ installing your first file server;
+ <link linkend="HDRWQ108">Starting Server Programs</link> if you
+ are installing an additional file server machine; or
+ <link linkend="Header_137a">Editing the File Systems Clean-up Script
+ on Solaris Systems in the client instructions</link> if you are
+ installing a client.</para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </sect2>
+ </sect1>
+</appendix>
\ No newline at end of file
<!ENTITY chapter3 SYSTEM "auqbg006.xml">
<!ENTITY chapter4 SYSTEM "auqbg007.xml">
<!ENTITY appendixA SYSTEM "auqbg008.xml">
+<!ENTITY appendixB SYSTEM "appendix.xml">
<!ENTITY index SYSTEM "auqbg009.xml">
]>
&chapter3;
&chapter4;
&appendixA;
+ &appendixB;
&index;
</book>
<!-- Keep this comment at the end of the file
<para>If you are already running a version of AFS, consult the upgrade
instructions in the <citetitle>OpenAFS Release Notes</citetitle> before
proceeding with the installation.</para>
+
+ <para>If you are working with an existing cell that uses
+ <emphasis role="bold">kaserver</emphasis> or external Kerberos v4 for
+ authentication, please see the notes in
+ <link linkend="KAS001">kaserver and legacy Kerberos 5 authentication</link>
+ and the rest of Appendix B for how the installation
+ steps will differ from those described in the rest of this guide.</para>
<sect1 id="HDRWQ7">
<title>The Procedures Described in this Guide</title>
<title>Building AFS from Source Code</title>
<para>See <link linkend="HDRWQ163">Appendix A, Building AFS from
- Source Code</link>.
+ Source Code</link></para>
+ </sect3>
+
+ <sect3 id="Header_17a">
+ <title>Configuring Legacy Components</title>
+ <para>See <link linkend="Legacy">Appendix B, Configuring Legacy
+ Components</link>
<indexterm>
<primary>background reading list</primary>
</indexterm>
<itemizedlist>
<listitem>
<para>You must have a Kerberos 5 realm running for your site, and
- the ability to create new principals within that realm</para>
+ the ability to create new principals within that realm. If you are
+ working with an existing cell using <emphasis>kaserver</emphasis>
+ or Kerberos v4 authentication, please see
+ <link linkend="KAS001">kaserver and legacy Kerberos 4 authentication</link>
+ for modifications to the following instructions.</para>
</listitem>
<listitem>
<para>You must have a NTP, or similar, timeservice running. Each AFS
- machine should derive its system time from this timeservice</para>
+ machine should derive its system time from this timeservice. If you
+ are working with an existing cell, and wish to use AFS's internal
+ time service, please see Appendix B for modifications to the following
+ instructions.</para>
</listitem>
<listitem>
</listitem>
<listitem>
- <para>You have a Kerberos v5 realm running for your site</para>
+ <para>You have a Kerberos v5 realm running for your site. If you are
+ working with an existing cell which uses
+ <emphasis role="bold">kaserver</emphasis> or Kerberos v4 for
+ authentication, please see
+ <link linkend="KAS001">kaserver and Legacy Kerberos v4 Authentication</link>
+ for the modifications required to this installation procedure.</para>
</listitem>
<listitem>
<para>You have a NTP, or similar, time service deployed to ensure
- rough clock syncronistation between your clients and servers.</para>
+ rough clock syncronistation between your clients and servers. If you
+ wish to use AFS's built in timeservice (which is deprecated) please
+ see Appendix B for the necessary modifications to this installation
+ procedure.</para>
</listitem>
</itemizedlist></para>
<listitem>
<para>If the machine is to remain an AFS client machine, modify the machine's authentication system so that users obtain
an AFS token as they log into the local file system. Using AFS is simpler and more convenient for your users if you make
- the modifications on all client machines. Otherwise, users must perform a two-step login procedure (login to the local
- file system and then issue the <emphasis role="bold">aklog</emphasis> command). For further discussion of AFS
+ the modifications on all client machines. Otherwise, users must perform a two or three step login procedure (login to the local
+ system, then obtain Kerberos credentials, and then issue the <emphasis role="bold">aklog</emphasis> command). For further discussion of AFS
authentication, see the chapter in the <emphasis>OpenAFS Administration Guide</emphasis> about cell configuration and
administration issues.</para>
</listitem>
automatically obtain AFS tokens at login. Following login, users can
obtain tokens by running the <emphasis role="bold">aklog</emphasis>
command</para>
+
+ <para>Sites which still require <emphasis role="bold">kaserver</emphasis>
+ or external Kerberos v4 authentication should consult
+ <link linkend="KAS012">Enabling kaserver based AFS login on AIX systems</link>
+ for details of how to enable AIX login.</para>
-<!--
- Follow the instructions in this section to incorporate AFS modifications into the AIX secondary authentication system.
- <orderedlist>
- <listitem>
- <para>Issue the <emphasis role="bold">ls</emphasis> command to verify that the <emphasis
- role="bold">afs_dynamic_auth</emphasis> and <emphasis role="bold">afs_dynamic_kerbauth</emphasis> programs are installed
- in the local <emphasis role="bold">/usr/vice/etc</emphasis> directory. <programlisting>
- # <emphasis role="bold">ls /usr/vice/etc</emphasis>
-</programlisting></para>
-
- <para>If the files do not exist, change directory as indicated and
- copy them.</para>
-
- <programlisting>
- # <emphasis role="bold">cd /tmp/afsdist/rs_aix42/root.client/usr/vice/etc</emphasis>
- # <emphasis role="bold">cp -p afs_dynamic* /usr/vice/etc</emphasis>
-</programlisting>
- </listitem>
-
- <listitem>
- <para>Edit the local <emphasis role="bold">/etc/security/user</emphasis> file, making changes to the indicated stanzas:
- <itemizedlist>
- <listitem>
- <para>In the default stanza, set the <computeroutput>registry</computeroutput> attribute to <emphasis
- role="bold">DCE</emphasis> (not to <emphasis role="bold">AFS</emphasis>), as follows: <programlisting>
- registry = DCE
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>In the default stanza, set the <computeroutput>SYSTEM</computeroutput> attribute as indicated.</para>
-
- <para>If the machine is an AFS client only, set the following value:</para>
-
- <programlisting>
- SYSTEM = "AFS OR (AFS[UNAVAIL] AND compat[SUCCESS])"
-</programlisting>
-
- <para>If the machine is both an AFS and a DCE client, set the following value (it must appear on a single line in
- the file):</para>
-
- <programlisting>
- SYSTEM = "DCE OR DCE[UNAVAIL] OR AFS OR (AFS[UNAVAIL] \
- AND compat[SUCCESS])"
-</programlisting>
- </listitem>
-
- <listitem>
- <para>In the <computeroutput>root</computeroutput> stanza, set the <computeroutput>registry</computeroutput>
- attribute as follows. It enables the local superuser <emphasis role="bold">root</emphasis> to log into the local
- file system only, based on the password listed in the local password file. <programlisting>
- root:
- registry = files
-</programlisting></para>
- </listitem>
- </itemizedlist></para>
- </listitem>
-
- <listitem>
- <para>Edit the local <emphasis role="bold">/etc/security/login.cfg</emphasis> file, creating or editing the indicated
- stanzas: <itemizedlist>
- <listitem>
- <para>In the <computeroutput>DCE</computeroutput> stanza, set the <computeroutput>program</computeroutput>
- attribute as follows.</para>
-
- <programlisting>
- DCE:
- program = /usr/vice/etc/afs_dynamic_kerbauth
-</programlisting>
- </listitem>
-
- <listitem>
- <para>In the <computeroutput>AFS</computeroutput> stanza, set the <computeroutput>program</computeroutput>
- attribute as follows.</para>
-
- <programlisting>
- AFS:
- program = /usr/vice/etc/afs_dynamic_kerbauth
-</programlisting>
- </listitem>
- </itemizedlist></para>
- </listitem>
-
- <listitem>
- <para>Proceed to <link linkend="HDRWQ50">Starting the BOS Server</link> (or if referring to these instructions while
- installing an additional file server machine, return to <link linkend="HDRWQ108">Starting Server
- Programs</link>).</para>
- </listitem>
- </orderedlist>
- -->
+ <para>Proceed to <link linkend="HDRWQ50">Starting the BOS Server</link>
+ (or if referring to these instructions while installing an additional
+ file server machine, return to <link linkend="HDRWQ108">Starting Server
+ Programs</link>).</para>
</sect2>
</sect1>
integrates all authentication mechanisms on the machine, including login, to provide the security infrastructure for
authenticated access to and from the machine.</para>
- <para>Explaining PAM is beyond the scope of this document. It is assumed that you understand the syntax and meanings of
- settings in the PAM configuration file (for example, how the <computeroutput>other</computeroutput> entry works, the effect of
- marking an entry as <computeroutput>required</computeroutput>, <computeroutput>optional</computeroutput>, or
- <computeroutput>sufficient</computeroutput>, and so on).</para>
-
<para>In modern AFS installations, you should be using Kerberos v5
for user login, and obtaining AFS tokens subsequent to this authentication
step. OpenAFS does not currently distribute a PAM module allowing AFS
obtain tokens by running the <emphasis role="bold">aklog</emphasis>
command</para>
-<!--
- <note>
- <para>The instructions specify that you mark each entry as <computeroutput>optional</computeroutput>. However, marking some
- modules as optional can mean that they grant access to the corresponding service even when the user does not meet all of the
- module's requirements. In some operating system revisions, for example, if you mark as optional the module that controls
- login via a dial-up connection, it allows users to login without providing a password. See the <emphasis>OpenAFS Release
- Notes</emphasis> for a discussion of any limitations that apply to this operating system.</para>
- </note>
-
- <para>Also, with some operating system versions you must install patches for PAM to interact correctly with certain
- authentication programs. For details, see the <emphasis>OpenAFS Release Notes</emphasis>.</para>
-
- <para>The recommended AFS-related entries in the PAM configuration file make use of one or more of the following three
- attributes. <variablelist>
- <varlistentry>
- <term><emphasis role="bold"><computeroutput>try_first_pass</computeroutput></emphasis></term>
-
- <listitem>
- <para>This is a standard PAM attribute that can be included on entries after the first one for a service; it directs
- the module to use the password that was provided to the first module. For the AFS module, it means that AFS
- authentication succeeds if the password provided to the module listed first is the user's correct AFS password. For
- further discussion of this attribute and its alternatives, see the operating system's PAM documentation.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="bold"><computeroutput>ignore_root</computeroutput></emphasis></term>
-
- <listitem>
- <para>This attribute, specific to the AFS PAM module, directs it to ignore not only the local superuser <emphasis
- role="bold">root</emphasis>, but also any user with UID 0 (zero).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="bold"><computeroutput>setenv_password_expires</computeroutput></emphasis></term>
-
- <listitem>
- <para>This attribute, specific to the AFS PAM module, sets the environment variable PASSWORD_EXPIRES to the expiration
- date of the user's AFS password, which is recorded in the Authentication Database.</para>
- </listitem>
- </varlistentry>
- </variablelist></para>
-
- <para>Perform the following steps to enable AFS login. <orderedlist>
- <listitem>
- <para>Change directory as indicated. <programlisting>
- # <emphasis role="bold">cd /usr/lib/security</emphasis>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Copy the AFS authentication library file to the <emphasis role="bold">/usr/lib/security</emphasis> directory. Then
- create a symbolic link to it whose name does not mention the version. Omitting the version eliminates the need to edit
- the PAM configuration file if you later update the library file.</para>
-
- <para>If you use the AFS Authentication Server (<emphasis role="bold">kaserver</emphasis> process) in the cell:</para>
-
- <programlisting>
- # <emphasis role="bold">cp /cdrom/hp_ux110/lib/pam_afs.so.1 .</emphasis>
- # <emphasis role="bold">ln -s pam_afs.so.1 pam_afs.so</emphasis>
-</programlisting>
-
- <para>If you use a Kerberos implementation of AFS authentication:</para>
-
- <programlisting>
- # <emphasis role="bold">cp /cdrom/hp_ux110/lib/pam_afs.krb.so.1 .</emphasis>
- # <emphasis role="bold">ln -s pam_afs.krb.so.1 pam_afs.so</emphasis>
-</programlisting>
- </listitem>
-
- <listitem>
- <para>Edit the <computeroutput>Authentication management</computeroutput> section of the HP-UX PAM configuration file,
- <emphasis role="bold">/etc/pam.conf</emphasis> by convention. The entries in this section have the value
- <computeroutput>auth</computeroutput> in their second field.</para>
-
- <para>First edit the standard entries, which refer to the HP-UX PAM module (usually, the file <emphasis
- role="bold">/usr/lib/security/libpam_unix.1</emphasis>) in their fourth field. For each service for which you want to
- use AFS authentication, edit the third field of its entry to read <computeroutput>optional</computeroutput>. The
- <emphasis role="bold">pam.conf</emphasis> file in the HP-UX distribution usually includes standard entries for the
- <emphasis role="bold">login</emphasis> and <emphasis role="bold">ftp</emphasis> services, for instance.</para>
-
- <para>If there are services for which you want to use AFS authentication, but for which the <emphasis
- role="bold">pam.conf</emphasis> file does not already include a standard entry, you must create that entry and place the
- value <computeroutput>optional</computeroutput> in its third field. For instance, the HP-UX <emphasis
- role="bold">pam.conf</emphasis> file does not usually include standard entries for the <emphasis
- role="bold">remsh</emphasis> or <emphasis role="bold">telnet</emphasis> services.</para>
-
- <para>Then create an AFS-related entry for each service, placing it immediately below the standard entry. The following
- example shows what the <computeroutput>Authentication Management</computeroutput> section looks like after you have you
- edited or created entries for the services mentioned previously. Note that the example AFS entries appear on two lines
- only for legibility.</para>
-
- <programlisting>
- login auth optional /usr/lib/security/libpam_unix.1
- login auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root setenv_password_expires
- ftp auth optional /usr/lib/security/libpam_unix.1
- ftp auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root
- remsh auth optional /usr/lib/security/libpam_unix.1
- remsh auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root
- telnet auth optional /usr/lib/security/libpam_unix.1
- telnet auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root setenv_password_expires
-</programlisting>
- </listitem>
+ <para>Sites which still require <emphasis role="bold">kaserver</emphasis>
+ or external Kerberos v4 authentication should consult
+ <link linkend="KAS013">Enabling kaserver based AFS login on HP-UX systems</link>
+ for details of how to enable HP-UX login.</para>
- <listitem>
- <para>If you use the Common Desktop Environment (CDE) on the machine and want users to obtain an AFS token as they log
- in, also add or edit the following four entries in the <computeroutput>Authentication management</computeroutput>
- section. Note that the AFS-related entries appear on two lines here only for legibility. <programlisting>
- dtlogin auth optional /usr/lib/security/libpam_unix.1
- dtlogin auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root
- dtaction auth optional /usr/lib/security/libpam_unix.1
- dtaction auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root
-</programlisting></para>
- </listitem>
--->
- <para>Proceed to <link linkend="HDRWQ50">Starting the BOS Server</link> (or if referring to these instructions while
- installing an additional file server machine, return to <link linkend="HDRWQ108">Starting Server
- Programs</link>).</para>
-
+ <para>Proceed to <link linkend="HDRWQ50">Starting the BOS Server</link>
+ (or if referring to these instructions while installing an additional
+ file server machine, return to <link linkend="HDRWQ108">Starting Server
+ Programs</link>).</para>
</sect2>
</sect1>
<emphasis role="bold">login</emphasis> program and the
graphical <emphasis role="bold">xdm</emphasis> login program both have
the ability to grant AFS tokens, this ability relies upon the deprecated
- kaserver authentication system. As this system is not recommended for
- new installations, this is not documented here.</para>
+ kaserver authentication system.</para>
<para>Users who have been successfully authenticated via Kerberos 5
authentication may obtain AFS tokens following login by running the
<emphasis role="bold">aklog</emphasis> command.</para>
-
-<!--
- <para>The standard IRIX command-line <emphasis role="bold">login</emphasis> program and the graphical <emphasis
- role="bold">xdm</emphasis> login program both automatically grant an AFS token when AFS is incorporated into the machine's
- kernel. However, some IRIX distributions use another login utility by default, and it does not necessarily incorporate the
- required AFS modifications. If that is the case, you must disable the default utility if you want AFS users to obtain AFS
- tokens at login. For further discussion, see the <emphasis>OpenAFS Release Notes</emphasis>.</para>
-
- <para>If you configure the machine to use an AFS-modified login utility, then the <emphasis
- role="bold">afsauthlib.so</emphasis> and <emphasis role="bold">afskauthlib.so</emphasis> files (included in the AFS
- distribution) must reside in the <emphasis role="bold">/usr/vice/etc</emphasis> directory. Issue the <emphasis
- role="bold">ls</emphasis> command to verify.</para>
- <programlisting>
- # <emphasis role="bold">ls /usr/vice/etc</emphasis>
-</programlisting>
-
- <para>If the files do not exist, change directory as indicated, and copy
- them.</para>
+ <para>Sites which still require <emphasis role="bold">kaserver</emphasis>
+ or external Kerberos v4 authentication should consult
+ <link linkend="KAS014">Enabling kaserver based AFS Login on IRIX Systems</link>
+ for details of how to enable IRIX login.</para>
- <programlisting>
- # <emphasis role="bold">cd /tmp/afsdist/sgi_65/root.client/usr/vice/etc</emphasis>
- # <emphasis role="bold">cp -p *authlib* /usr/vice/etc</emphasis>
-</programlisting>
--->
- <para>After taking any necessary action, proceed to <link linkend="HDRWQ50">Starting the BOS Server</link>.</para>
+ <para>After taking any necessary action, proceed to
+ <link linkend="HDRWQ50">Starting the BOS Server</link>.</para>
</sect2>
</sect1>
integrates all authentication mechanisms on the machine, including login, to provide the security infrastructure for
authenticated access to and from the machine.</para>
- <para>Explaining PAM is beyond the scope of this document. It is assumed that you understand the syntax and meanings of
- settings in the PAM configuration file (for example, how the <computeroutput>other</computeroutput> entry works, the effect of
- marking an entry as <computeroutput>required</computeroutput>, <computeroutput>optional</computeroutput>, or
- <computeroutput>sufficient</computeroutput>, and so on).</para>
-
<para>At this time, we recommend that new sites requiring AFS credentials
to be gained as part of PAM authentication use Russ Alberry's
pam_afs_session, rather than utilising the bundled pam_afs2 module.
Kerberos V service, and then use the AFS PAM module to obtain AFS
credentials in the <computeroutput>session</computeroutput> section</para>
- <orderedlist>
- <listitem>
- <para>Proceed to <link linkend="HDRWQ50">Starting the BOS Server</link> (or if referring to these instructions while
- installing an additional file server machine, return to <link linkend="HDRWQ108">Starting Server
- Programs</link>).</para>
- </listitem>
- </orderedlist>
+ <para>Sites which still require <emphasis role="bold">kaserver</emphasis>
+ or external Kerberos v4 authentication should consult
+ <link linkend="KAS015">Enabling kaserver based AFS Login on Linux Systems</link>
+ for details of how to enable AFS login on Linux.</para>
+
+ <para>Proceed to <link linkend="HDRWQ50">Starting the BOS Server</link>
+ (or if referring to these instructions while installing an additional
+ file server machine, return to <link linkend="HDRWQ108">Starting Server
+ Programs</link>).</para>
</sect2>
</sect1>
proceed to <link linkend="HDRWQ50">Starting the BOS Server</link>.</para>
</listitem>
</orderedlist></para>
+ </sect2>
+ <sect2 id="HDRWQ49">
+ <title>Enabling AFS Login on Solaris Systems</title>
<indexterm>
<primary>enabling AFS login</primary>
<tertiary>file server machine</tertiary>
</indexterm>
- <indexterm>
- <primary>Solaris</primary>
-
- <secondary>file systems clean-up script</secondary>
-
- <tertiary>on file server machine</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>file systems clean-up script (Solaris)</primary>
-
- <secondary>file server machine</secondary>
- </indexterm>
-
- <indexterm>
- <primary>scripts</primary>
-
- <secondary>file systems clean-up (Solaris)</secondary>
-
- <tertiary>file server machine</tertiary>
- </indexterm>
- </sect2>
-
- <sect2 id="HDRWQ49">
- <title>Enabling AFS Login and Editing the File Systems Clean-up Script on Solaris Systems</title>
-
<note>
<para>If you plan to remove client functionality from this machine after completing the installation, skip this section and
proceed to <link linkend="HDRWQ50">Starting the BOS Server</link>.</para>
obtain tokens by running the <emphasis role="bold">aklog</emphasis>
command</para>
-<!--
- <para>The following instructions explain how to alter the entries in the PAM configuration file for each service for which you
- wish to use AFS authentication. Other configurations possibly also work, but the instructions specify the recommended and
- tested configuration.</para>
-
- <note>
- <para>The instructions specify that you mark each entry as <computeroutput>optional</computeroutput>. However, marking some
- modules as optional can mean that they grant access to the corresponding service even when the user does not meet all of the
- module's requirements. In some operating system revisions, for example, if you mark as optional the module that controls
- login via a dial-up connection, it allows users to login without providing a password. See the <emphasis>OpenAFS Release
- Notes</emphasis> for a discussion of any limitations that apply to this operating system.</para>
-
- <para>Also, with some operating system versions you must install patches for PAM to interact correctly with certain
- authentication programs. For details, see the <emphasis>OpenAFS Release Notes</emphasis>.</para>
- </note>
+ <para>Sites which still require <emphasis role="bold">kaserver</emphasis>
+ or external Kerberos v4 authentication should consult
+ <link linkend="KAS016">Enabling kaserver based AFS Login on Solaris Systems"</link>
+ for details of how to enable AIX login.</para>
- <para>The recommended AFS-related entries in the PAM configuration file make use of one or more of the following three
- attributes. <variablelist>
- <varlistentry>
- <term><emphasis role="bold"><computeroutput>try_first_pass</computeroutput></emphasis></term>
-
- <listitem>
- <para>This is a standard PAM attribute that can be included on entries after the first one for a service; it directs
- the module to use the password that was provided to the first module. For the AFS module, it means that AFS
- authentication succeeds if the password provided to the module listed first is the user's correct AFS password. For
- further discussion of this attribute and its alternatives, see the operating system's PAM documentation.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="bold"><computeroutput>ignore_root</computeroutput></emphasis></term>
-
- <listitem>
- <para>This attribute, specific to the AFS PAM module, directs it to ignore not only the local superuser <emphasis
- role="bold">root</emphasis>, but also any user with UID 0 (zero).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="bold"><computeroutput>setenv_password_expires</computeroutput></emphasis></term>
-
- <listitem>
- <para>This attribute, specific to the AFS PAM module, sets the environment variable PASSWORD_EXPIRES to the expiration
- date of the user's AFS password, which is recorded in the Authentication Database.</para>
- </listitem>
- </varlistentry>
- </variablelist></para>
-
- <para>Perform the following steps to enable AFS login. <orderedlist>
- <listitem>
- <para>Mount the AFS CD-ROM for Solaris on the <emphasis role="bold">/cdrom</emphasis> directory, if it is not already.
- Then change directory as indicated. <programlisting>
- # <emphasis role="bold">cd /usr/lib/security</emphasis>
-</programlisting></para>
- </listitem>
+ <para>Proceed to <link linkend="HDRWQ49a">Editing the File Systems
+ Clean-up Script on Solaris Systems</link></para>
+ </sect2>
+ <sect2 id="HDRWQ49a">
+ <title>Editing the File Systems Clean-up Script on Solaris Systems</title>
+ <indexterm>
+ <primary>Solaris</primary>
- <listitem>
- <para>Copy the AFS authentication library file to the <emphasis role="bold">/usr/lib/security</emphasis> directory. Then
- create a symbolic link to it whose name does not mention the version. Omitting the version eliminates the need to edit
- the PAM configuration file if you later update the library file.</para>
+ <secondary>file systems clean-up script</secondary>
- <para>If you use the AFS Authentication Server (<emphasis role="bold">kaserver</emphasis> process):</para>
+ <tertiary>on file server machine</tertiary>
+ </indexterm>
- <programlisting>
- # <emphasis role="bold">cp /cdrom/sun4x_56/lib/pam_afs.so.1 .</emphasis>
- # <emphasis role="bold">ln -s pam_afs.so.1 pam_afs.so</emphasis>
-</programlisting>
+ <indexterm>
+ <primary>file systems clean-up script (Solaris)</primary>
- <para>If you use a Kerberos implementation of AFS authentication:</para>
+ <secondary>file server machine</secondary>
+ </indexterm>
- <programlisting>
- # <emphasis role="bold">cp /cdrom/sun4x_56/lib/pam_afs.krb.so.1 .</emphasis>
- # <emphasis role="bold">ln -s pam_afs.krb.so.1 pam_afs.so</emphasis>
-</programlisting>
- </listitem>
+ <indexterm>
+ <primary>scripts</primary>
- <listitem>
- <para>Edit the <computeroutput>Authentication management</computeroutput> section of the Solaris PAM configuration file,
- <emphasis role="bold">/etc/pam.conf</emphasis> by convention. The entries in this section have the value
- <computeroutput>auth</computeroutput> in their second field.</para>
-
- <para>First edit the standard entries, which refer to the Solaris PAM module (usually, the file <emphasis
- role="bold">/usr/lib/security/pam_unix.so.1</emphasis>) in their fourth field. For each service for which you want to
- use AFS authentication, edit the third field of its entry to read <computeroutput>optional</computeroutput>. The
- <emphasis role="bold">pam.conf</emphasis> file in the Solaris distribution usually includes standard entries for the
- <emphasis role="bold">login</emphasis>, <emphasis role="bold">rlogin</emphasis>, and <emphasis
- role="bold">rsh</emphasis> services, for instance.</para>
-
- <para>If there are services for which you want to use AFS authentication, but for which the <emphasis
- role="bold">pam.conf</emphasis> file does not already include a standard entry, you must create that entry and place the
- value <computeroutput>optional</computeroutput> in its third field. For instance, the Solaris <emphasis
- role="bold">pam.conf</emphasis> file does not usually include standard entries for the <emphasis
- role="bold">ftp</emphasis> or <emphasis role="bold">telnet</emphasis> services.</para>
-
- <para>Then create an AFS-related entry for each service, placing it immediately below the standard entry. The following
- example shows what the <computeroutput>Authentication Management</computeroutput> section looks like after you have you
- edited or created entries for the services mentioned previously. Note that the example AFS entries appear on two lines
- only for legibility.</para>
+ <secondary>file systems clean-up (Solaris)</secondary>
- <programlisting>
- login auth optional /usr/lib/security/pam_unix.so.1
- login auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root setenv_password_expires
- rlogin auth optional /usr/lib/security/pam_unix.so.1
- rlogin auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root setenv_password_expires
- rsh auth optional /usr/lib/security/pam_unix.so.1
- rsh auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root
- ftp auth optional /usr/lib/security/pam_unix.so.1
- ftp auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root
- telnet auth optional /usr/lib/security/pam_unix.so.1
- telnet auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root setenv_password_expires
-</programlisting>
- </listitem>
+ <tertiary>file server machine</tertiary>
+ </indexterm>
- <listitem>
- <para>If you use the Common Desktop Environment (CDE) on the machine and want users to obtain an AFS token as they log
- in, also add or edit the following four entries in the <computeroutput>Authentication management</computeroutput>
- section. Note that the AFS-related entries appear on two lines here only for legibility. <programlisting>
- dtlogin auth optional /usr/lib/security/pam_unix.so.1
- dtlogin auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root
- dtsession auth optional /usr/lib/security/pam_unix.so.1
- dtsession auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root
-</programlisting></para>
- </listitem>
--->
+
<orderedlist>
<listitem>
<para>Some Solaris distributions include a script that locates and removes unneeded files from various file systems. Its
them. For a description of the contents and function of these directories and files, see the chapter in the <emphasis>OpenAFS
Administration Guide</emphasis> about administering server machines. For further discussion of the mode bit settings, see <link
linkend="HDRWQ96">Protecting Sensitive AFS Directories</link>. <indexterm>
- <primary>CD-ROM</primary>
+ <primary>Binary Distribution</primary>
<secondary>copying server files from</secondary>
kaserver was based on <emphasis>Kerberos v4</emphasis>, as such, it is
not recommended for new cells. This guide assumes you have already
configured a Kerberos v5 realm for your site, and details the procedures
- required to use AFS with this realm.</para>
+ required to use AFS with this realm. If you do wish to use
+ <emphasis role="bold">kaserver</emphasis>, please see the modifications
+ to these instructions detailed in
+ <link linkend="KAS006">Starting the kaserver Database Server Process</link>
+ </para>
</note>
<para>The remaining instructions in this chapter include the <emphasis role="bold">-cell</emphasis> argument on all applicable
</sect1>
<sect1 id="HDRWQ53">
- <title>Initializing Cell Security</title>
+ <title>Initializing Cell Security </title>
+ <para>If you are working with an existing cell which uses
+ <emphasis role="bold">kaserver</emphasis> or Kerberos v4 for authentication,
+ please see
+ <link linkend="HDRWQ53">Initializing Cell Security with kaserver</link>
+ for installation instructions which replace this section.</para>
+
<para>Now initialize the cell's security mechanisms. Begin by creating the following two entires in your site's Kerberos database: <itemizedlist>
<listitem>
<para>A generic administrative account, called <emphasis role="bold">admin</emphasis> by convention. If you choose to
<para>The following instructions do not configure all of the security mechanisms related to the AFS Backup System. See the
chapter in the <emphasis>OpenAFS Administration Guide</emphasis> about configuring the Backup System.</para>
- <para>The examples below assume you are using MIT Kerberos. Please refer to the documentation for your KDC's administrative interface if you are using a different vendor</para>
+ <para>The examples below assume you are using MIT Kerberos. Please refer
+ to the documentation for your KDC's administrative interface if you are
+ using a different vendor</para>
-<orderedlist>
+ <orderedlist>
<listitem>
<para>Enter <emphasis role="bold">kadmin</emphasis> interactive mode.
<programlisting>
<indexterm>
<primary>commands</primary>
-
<secondary>bos listkeys</secondary>
</indexterm>
<indexterm>
<primary>bos commands</primary>
-
<secondary>listkeys</secondary>
</indexterm>
<indexterm>
<primary>displaying</primary>
-
<secondary>server encryption key</secondary>
-
<tertiary>KeyFile file</tertiary>
</indexterm>
</listitem>
<para>You can safely ignore any error messages indicating that <emphasis role="bold">bos</emphasis> failed to get tickets
or that authentication failed.</para>
-
-<!--
- <para>If the keys are different, issue the following commands, making sure that the <replaceable>afs_passwd</replaceable>
- string is the same in each case. The <replaceable>checksum</replaceable> strings reported by the <emphasis role="bold">kas
- examine</emphasis> and <emphasis role="bold">bos listkeys</emphasis> commands must match; if they do not, repeat these
- instructions until they do, using the <emphasis role="bold">-kvno</emphasis> argument to increment the key version number
- each time.</para>
-
- <programlisting>
- # <emphasis role="bold">./kas -cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis role="bold">-noauth</emphasis>
- ka> <emphasis role="bold">setpassword afs -kvno 1</emphasis>
- new_password: <replaceable>afs_passwd</replaceable>
- Verifying, please re-enter initial_password: <replaceable>afs_passwd</replaceable>
- ka> <emphasis role="bold">examine afs</emphasis>
- User data for afs
- key (1) cksum is <replaceable>checksum</replaceable> . . .
- ka> <emphasis role="bold">quit</emphasis>
- # <emphasis role="bold">./bos addkey</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">-kvno 1 -cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis
- role="bold">-noauth</emphasis>
- Input key: <replaceable>afs_passwd</replaceable>
- Retype input key: <replaceable>afs_passwd</replaceable>
- # <emphasis role="bold">./bos listkeys</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">-cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis
- role="bold">-noauth</emphasis>
- key 1 has cksum <replaceable>checksum</replaceable>
-</programlisting>
--->
+ </listitem>
+ </orderedlist>
+ </sect1>
+ <sect1 id="HDRWQ53a">
+ <title>Initializing the Protection Database</title>
+
+ <para>Now continue to configure your cell's security systems by
+ populating the Protection Database with the newly created
+ <emphasis role="bold">admin</emphasis> user, and permitting it
+ to issue priviledged commands on the AFS filesystem.</para>
+
+ <orderedlist>
+ <listitem>
<indexterm>
<primary>commands</primary>
-
<secondary>pts createuser</secondary>
</indexterm>
<indexterm>
<primary>pts commands</primary>
-
<secondary>createuser</secondary>
</indexterm>
<indexterm>
<primary>Protection Database</primary>
</indexterm>
- </listitem>
-
- <listitem>
<para>Issue the <emphasis role="bold">pts createuser</emphasis> command to create a Protection Database entry for the
<emphasis role="bold">admin</emphasis> user.</para>
<indexterm>
<primary>commands</primary>
-
<secondary>pts adduser</secondary>
</indexterm>
<indexterm>
<primary>pts commands</primary>
-
<secondary>adduser</secondary>
</indexterm>
<indexterm>
<primary>admin account</primary>
-
<secondary>adding</secondary>
-
<tertiary>to system:administrators group</tertiary>
</indexterm>
</listitem>
system:administrators
</programlisting> <indexterm>
<primary>commands</primary>
-
<secondary>bos restart</secondary>
-
<tertiary>on first AFS machine</tertiary>
</indexterm> <indexterm>
<primary>bos commands</primary>
-
<secondary>restart</secondary>
-
<tertiary>on first AFS machine</tertiary>
</indexterm> <indexterm>
<primary>restarting server process</primary>
-
<secondary>on first AFS machine</secondary>
</indexterm> <indexterm>
<primary>server process</primary>
-
<secondary>restarting</secondary>
-
<tertiary>on first AFS machine</tertiary>
</indexterm></para>
</listitem>
<emphasis role="bold">fs newcell</emphasis> command to update the list in kernel memory directly; see the chapter in the
<emphasis>OpenAFS Administration Guide</emphasis> about administering client machines.</para>
- <para>The AFS distribution includes the file <emphasis role="bold">CellServDB.dist</emphasis>. It includes an entry for all AFS cells that agreed to share
- their database server machine information at the time the distribution was
- created. A copy of this file is maintained at grand.central.org, from where
- updates may also be obtained.</para>
+ <para>The AFS distribution includes the file
+ <emphasis role="bold">CellServDB.dist</emphasis>. It includes an entry for
+ all AFS cells that agreed to share their database server machine
+ information at the time the distribution was
+ created. The definitive copy of this file is maintained at
+ grand.central.org, and updates may be obtained from
+ /afs/grand.central.org/service/CellServDB or
+ <ulink url="http://grand.central.org/dl/cellservdb/CellServDB">
+ http://grand.central.org/dl/cellservdb/CellServDB</ulink></para>
<para>The <emphasis role="bold">CellServDB.dist</emphasis> file can be a
good basis for the client <emphasis role="bold">CellServDB</emphasis> file,
<note>
<para>If you are running on a Fedora or RHEL based system, the
- openafs-client initilization script behaves differently from that
+ openafs-client initialization script behaves differently from that
described above. It sources /etc/sysconfig/openafs, in which the
AFSD_ARGS variable may be set to contain any, or all, of the afsd options
detailed. Note that this script does not support setting an OPTIONS
a synthetic root (as discussed in <link linkend="HDRWQ91">Enabling Access
to Foreign Cells</link>). As some distributions ship with this enabled, it
may be necessary to remove any occurences of the
- <emhpasis role="bold">-dynroot</emphasis> and
+ <emphasis role="bold">-dynroot</emphasis> and
<emphasis role="bold">-afsdb</emphasis> options from both the AFS
initialisation script and options file. If this functionality is
required it may be renabled as detailed in
</programlisting></para>
</listitem>
</orderedlist></para>
-
- <indexterm>
- <primary>commands</primary>
-
- <secondary>klog</secondary>
- </indexterm>
-
- <indexterm>
- <primary>klog command</primary>
- </indexterm>
</listitem>
<listitem>
role="bold">V</emphasis><replaceable>n</replaceable> files in the cache directory. Subsequent Cache Manager
initializations do not take nearly as long, because the <emphasis role="bold">V</emphasis><replaceable>n</replaceable>
files already exist.</para>
+ </listitem>
+ <listitem>
+
+ <indexterm>
+ <primary>commands</primary>
+ <secondary>aklog</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>aklog command</primary>
+ </indexterm>
+
+ <para>If you are working with an existing cell which uses
+ <emphasis role="bold">kaserver</emphasis> for authentication,
+ please recall the note in
+ <link linkend="KAS003">Using this Appendix</link> detailing the
+ substitution of <emphasis role="bold">kinit</emphasis> and
+ <emphasis role="bold">aklog</emphasis> with
+ <emphasis role="bold">klog</emphasis>.</para>
+
<para>As a basic test of correct AFS functioning, issue the
<emphasis role="bold">kinit</emphasis> and
<emphasis role="bold">aklog</emphasis> commands to authenticate
addition to this enables DNS lookups for any cells that are not found in
the client's CellServDB file. Both of these options are added to the AFS
initialisation script, or options file, as detailed in
- <link linked="HDRWQ70">Configuring the Cache Manager</link>.
+ <link linkend="HDRWQ70">Configuring the Cache Manager</link>.</para>
</sect2>
<sect2>
- <title>Adding foreign cells to a conventional root volume</root>
+ <title>Adding foreign cells to a conventional root volume</title>
<para>In this section you create a mount point in your AFS filespace for the <emphasis role="bold">root.cell</emphasis> volume
of each foreign cell that you want to enable your users to access. For users working on a client machine to access the cell,
# <emphasis role="bold">ls /afs/</emphasis><replaceable>foreign_cell</replaceable>
</programlisting></para>
</listitem>
-
- <!-- XXX - Add stuff about registering your cell with
- grand.central.org, and about configuring your DNS -->
<listitem>
<para>If you wish to participate in the global AFS namespace, and only
intend running one database server, please
register your cell with grand.central.org at this time.
To do so, email the <emphasis role="bold">CellServDB</emphasis> fragment
- describing your cell to <!-- XXX - where does this get sent -->. If you intend
- on deploying multiple database servers, please wait until you have installed
- all of them before registering your cell.</para>
+ describing your cell, together with a contact name and email address
+ for any queries, to cellservdb@grand.central.org. If you intend
+ on deploying multiple database servers, please wait until you have
+ installed all of them before registering your cell.</para>
</listitem>
<listitem>
<para>If you wish to allow your cell to be located through DNS lookups,
at this time you should also add the necessary configuration to your
- DNS. <!-- XXX - detail what this is -->
+ DNS.</para>
+
+ <para>AFS database servers may be located by creating AFSDB records
+ in the DNS for the domain name corresponding to the name of your cell.
+ It's outside the scope of this guide to give an indepth description of
+ managing, or configuring, your site's DNS. You should consult the
+ documentation for your DNS server for further details on AFSDB
+ records.</para>
</listitem>
</orderedlist></para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="HDRWQ93">
+ <title>Improving Cell Security</title>
<indexterm>
<primary>cell</primary>
<secondary>controlling access by root superuser</secondary>
</indexterm>
- </sect1>
-
- <sect1 id="HDRWQ93">
- <title>Improving Cell Security</title>
<para>This section discusses ways to improve the security of AFS data
in your cell. Also see the chapter in the <emphasis>OpenAFS
<para>Following are suggestions for managing AFS administrative privilege: <itemizedlist>
<listitem>
- <para>Create an administrative account for each administrator named something like
- <replaceable>username</replaceable><emphasis role="bold">.admin</emphasis>. Administrators authenticate under these
- identities only when performing administrative tasks, and destroy the administrative tokens immediately after finishing
- the task (either by issuing the <emphasis role="bold">unlog</emphasis> command, or the <emphasis
- role="bold">aklog</emphasis> command to adopt their regular identity).</para>
+ <para>Create an administrative account for each administrator named
+ something like
+ <replaceable>username</replaceable><emphasis role="bold">.admin</emphasis>.
+ Administrators authenticate under these identities only when
+ performing administrative tasks, and destroy the administrative
+ tokens immediately after finishing the task (either by issuing the
+ <emphasis role="bold">unlog</emphasis> command, or the
+ <emphasis role="bold">kinit</emphasis> and
+ <emphasis role="bold">aklog</emphasis> commands to adopt their
+ regular identity).</para>
</listitem>
<listitem>
</listitem>
<listitem>
- <para>You can access the data on the AFS CD-ROMs, either through a local CD-ROM drive or via an NFS mount of a CD-ROM drive
- attached to a machine that is accessible by network</para>
+ <para>You can access the data on the OpenAFS Binary Distribution for
+ your operating system, either on the local filesystem or via an NFS
+ mount of the distribution's contents.</para>
</listitem>
</itemizedlist></para>
existing file server machine or is the first file server machine of its system type in your cell. The differences mostly concern
the source for the needed binaries and files, and what portions of the Update Server you install: <itemizedlist>
<listitem>
- <para>On a new system type, you must load files and binaries from the AFS CD-ROM. You install the server portion of the
- Update Server to make this machine the binary distribution machine for its system type.</para>
+ <para>On a new system type, you must load files and binaries from the
+ OpenAFS distribution. You may install the server portion of the
+ Update Server to make this machine the binary distribution machine
+ for its system type.</para>
</listitem>
<listitem>
- <para>On an existing system type, you can copy files and binaries from a previously installed file server machine, rather
- than from the CD-ROM. You install the client portion of the Update Server to accept updates of binaries, because a
- previously installed machine of this type was installed as the binary distribution machine.</para>
+ <para>On an existing system type, you can copy files and binaries
+ from a previously installed file server machine, rather
+ than from the OpenAFS distribution. You may install the client
+ portion of the Update Server to accept updates of binaries, because a
+ previously installed machine of this type was installed as the binary
+ distribution machine.</para>
+ </listitem>
+ <listitem>
+ <para>On some system types, distribtution of the appropriate binaries
+ may be acheived using the system's own package management system. In
+ these cases, it is recommended that this system is used, rather than
+ installing the binaries by hand.</para>
</listitem>
</itemizedlist></para>
<para>To install a new file server machine, perform the following procedures: <orderedlist>
<listitem>
- <para>Copy needed binaries and files onto this machine's local disk</para>
+ <para>Copy needed binaries and files onto this machine's local disk,
+ as required.</para>
</listitem>
<listitem>
</listitem>
<listitem>
- <para>Start the appropriate portion of the Update Server</para>
+ <para>Start the appropriate portion of the Update Server, if
+ required</para>
</listitem>
<listitem>
<para>Start the <emphasis role="bold">fs</emphasis> process, which incorporates three component processes: the File
Server, Volume Server, and Salvager</para>
</listitem>
-
- <listitem>
- <para>Start the controller process (called <emphasis role="bold">runntp</emphasis>) for the Network Time Protocol Daemon,
- which synchronizes clocks</para>
- </listitem>
</orderedlist></para>
<para>After completing the instructions in this section, you can install database server functionality on the machine according
to the instructions in <link linkend="HDRWQ114">Installing Database Server Functionality</link>. <indexterm>
- <primary>CD-ROM</primary>
-
- <secondary>creating /cdrom directory</secondary>
-
- <tertiary>server machine after first</tertiary>
- </indexterm> <indexterm>
- <primary>cdrom directory</primary>
-
- <secondary>server machine after first</secondary>
- </indexterm> <indexterm>
- <primary>file server machine, additional</primary>
-
- <secondary>/cdrom directory</secondary>
- </indexterm> <indexterm>
- <primary>creating</primary>
-
- <secondary>/cdrom directory</secondary>
-
- <tertiary>server machine after first</tertiary>
- </indexterm> <indexterm>
<primary>usr/afs directory</primary>
<secondary>server machine after first</secondary>
<sect2 id="Header_99">
<title>Creating AFS Directories and Performing Platform-Specific Procedures</title>
+ <para>If your operating systems AFS distribution is supplied as packages,
+ such as .rpms or .debs, you should just install those packages as detailed
+ in the previous chapter.</para>
+
<para>Create the <emphasis role="bold">/usr/afs</emphasis> and <emphasis role="bold">/usr/vice/etc</emphasis> directories on
- the local disk. Subsequent instructions copy files from the AFS distribution CD-ROM into them, at the appropriate point for
+ the local disk. Subsequent instructions copy files from the AFS distribution into them, at the appropriate point for
each system type.</para>
<programlisting>
# <emphasis role="bold">mkdir /usr/afs/bin</emphasis>
# <emphasis role="bold">mkdir /usr/vice</emphasis>
# <emphasis role="bold">mkdir /usr/vice/etc</emphasis>
- # <emphasis role="bold">mkdir /cdrom</emphasis>
+ # <emphasis role="bold">mkdir /tmp/afsdist</emphasis>
</programlisting>
<para>As on the first file server machine, the initial procedures in installing an additional file server machine vary a good
</indexterm>
<listitem>
- <para>Mount the AFS CD-ROM for AIX on the local <emphasis role="bold">/cdrom</emphasis> directory. For instructions on
- mounting CD-ROMs (either locally or remotely via NFS), see your AIX documentation. Then change directory as indicated.
- <programlisting>
- # <emphasis role="bold">cd /cdrom/rs_aix42/root.client/usr/vice/etc</emphasis>
+ <para>Unpack the distribution tarball. The examples below assume
+ that you have unpacked the files into the
+ <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you
+ pick a different location, substitute this in all of the following
+ examples. Once you have unpacked the distribution,
+ change directory as indicated.
+<programlisting>
+ # <emphasis role="bold">cd /tmp/afsdist/rs_aix42/root.client/usr/vice/etc</emphasis>
</programlisting></para>
</listitem>
</listitem>
<listitem>
- <para>Move the AIX <emphasis role="bold">fsck</emphasis> program helper to a safe location and install the version
- from the AFS distribution in its place. The AFS CD-ROM must still be mounted at the <emphasis
- role="bold">/cdrom</emphasis> directory. <programlisting>
+ <para>On systems prior to AIX 5.1, move the AIX
+ <emphasis role="bold">fsck</emphasis> program helper to a safe
+ location and install the version from the AFS distribution in
+ its place. Note that on AIX 5.1, and later, systems this step is
+ not required, and the <emphasis role="bold">v3fshelper</emphasis>
+ program is not shipped for these systems.</para>
+
+ <para>The AFS binary distribution must still be available in the
+ <emphasis role="bold">/tmp/afsdist</emphasis> directory.
+<programlisting>
# <emphasis role="bold">cd /sbin/helpers</emphasis>
# <emphasis role="bold">mv v3fshelper v3fshelper.noafs</emphasis>
- # <emphasis role="bold">cp -p /cdrom/rs_aix42/root.server/etc/v3fshelper v3fshelper</emphasis>
+ # <emphasis role="bold">cp -p /tmp/afsdist/rs_aix42/root.server/etc/v3fshelper v3fshelper</emphasis>
</programlisting></para>
</listitem>
<para>If the machine's hardware and software configuration exactly matches another HP-UX machine on which AFS is already
built into the kernel, you can copy the kernel from that machine to this one. In general, however, it is better to build AFS
- modifications into the kernel on each machine according to the following instructions. <orderedlist>
+ modifications into the kernel on each machine according to the following instructions.
+ <orderedlist>
<indexterm>
<primary>incorporating AFS kernel extensions</primary>
</listitem>
<listitem>
- <para>Mount the AFS CD-ROM for HP-UX on the local <emphasis role="bold">/cdrom</emphasis> directory. For instructions
- on mounting CD-ROMs (either locally or remotely via NFS), see your HP-UX documentation. Then change directory as
- indicated. <programlisting>
- # <emphasis role="bold">cd /cdrom/hp_ux110/root.client</emphasis>
+ <para>Unpack the OpenAFS HP-UX distribution tarball. The examples
+ below assume that you have unpacked the files into the
+ <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you
+ pick a different location, substitute this in all of the following
+ examples. Once you have unpacked the distribution, change
+ directory as indicated.
+<programlisting>
+ # <emphasis role="bold">cd /tmp/afsdist/hp_ux110/root.client</emphasis>
</programlisting></para>
</listitem>
<para>Copy the AFS-modified version of the <emphasis role="bold">fsck</emphasis> program (the <emphasis
role="bold">vfsck</emphasis> binary) and related files from the distribution directory to the new AFS-specific command
directory. <programlisting>
- # <emphasis role="bold">cp -p /cdrom/hp_ux110/root.server/etc/* .</emphasis>
+ # <emphasis role="bold">cp -p /tmp/afsdist/hp_ux110/root.server/etc/* .</emphasis>
</programlisting></para>
</listitem>
<listitem>
<para>Prepare for incorporating AFS into the kernel by performing the following procedures. <orderedlist>
<listitem>
- <para>Mount the AFS CD-ROM for IRIX on the <emphasis role="bold">/cdrom</emphasis> directory. For instructions
- on mounting CD-ROMs (either locally or remotely via NFS), see your IRIX documentation. Then change directory as
- indicated. <programlisting>
- # <emphasis role="bold">cd /cdrom/sgi_65/root.client</emphasis>
+ <para>Unpack the OpenAFS IRIX distribution tarball. The
+ examples below assume that you have unpacked the files into
+ the <emphasis role="bold">/tmp/afsdist</emphasis>
+ directory. If you pick a different location, substitue this
+ in all of the following examples. Once you have unpacked
+ the distribution, change directory as indicated.
+<programlisting>
+ # <emphasis role="bold">cd /tmp/afsdist/sgi_65/root.client</emphasis>
</programlisting></para>
</listitem>
<para>Begin by running the AFS initialization script to call the <emphasis role="bold">insmod</emphasis> program, which
dynamically loads AFS modifications into the kernel. Then create partitions for storing AFS volumes. You do not need to
- replace the Linux <emphasis role="bold">fsck</emphasis> program. <orderedlist>
+ replace the Linux <emphasis role="bold">fsck</emphasis> program.</para>
+
+ <para> The procedure for starting up OpenAFS depends upon your distribution</para>
+ <orderedlist>
+ <listitem>
+ <para>For Fedora and RedHat Enterprise Linux systems (or their
+ derivateds), download and install the RPM set for your operating system
+ from the OpenAFS distribution site. You will need the
+ <emphasis role="bold">openafs</emphasis> and
+ <emphasis role="bold">openafs-server</emphasis> packages, along
+ with an <emphasis role="bold">openafs-kernel</emphasis> package
+ matching your current, running, kernel. If you wish to install
+ client functionality, you will also require the
+ <emphasis role="bold">openafs-client</emphasis> package.</para>
+
+ <para>You can find the version of your current kernel by running
+<programlisting>
+ # uname -r
+<replaceable>2.6.20-1.2933.fc6</replaceable>
+</programlisting></para>
+
+ <para>Once downloaded, the packages may be installed with the
+ <emphasis role="bold">rpm</emphasis> command
+<programlisting>
+ # rpm -U openafs-* openafs-client-* openafs-server-* openafs-kernel-*
+</programlisting></para>
+ </listitem>
+ <listitem>
<indexterm>
<primary>incorporating AFS kernel extensions</primary>
<tertiary>on add'l server machine</tertiary>
</indexterm>
-
- <listitem>
- <para>Mount the AFS CD-ROM for Linux on the local <emphasis role="bold">/cdrom</emphasis> directory. For instructions
- on mounting CD-ROMs (either locally or remotely via NFS), see your Linux documentation. Then change directory as
- indicated. <programlisting>
- # <emphasis role="bold">cd /cdrom/i386_linux22/root.client/usr/vice/etc</emphasis>
+ <para>For systems which are provided as a tarball, or built from
+ source, unpack the distribution tarball. The examples below assume
+ that you have unpacked the files into the
+ <emphasis role="bold">/tmp/afsdist</emphasis>directory. If you
+ pick a different location, substitute this in all of the following
+ examples. Once you have unpacked the distribution,
+ change directory as indicated.
+<programlisting>
+ # <emphasis role="bold">cd /tmp/afsdist/linux/root.client/usr/vice/etc</emphasis>
</programlisting></para>
- </listitem>
- <listitem>
<para>Copy the AFS kernel library files to the local <emphasis role="bold">/usr/vice/etc/modload</emphasis> directory.
The filenames for the libraries have the format <emphasis
role="bold">libafs-</emphasis><replaceable>version</replaceable><emphasis role="bold">.o</emphasis>, where
kernel. <programlisting>
# <emphasis role="bold">cp -rp modload /usr/vice/etc</emphasis>
</programlisting></para>
- </listitem>
-
- <listitem>
+
<para>Copy the AFS initialization script to the local directory for initialization files (by convention, <emphasis
role="bold">/etc/rc.d/init.d</emphasis> on Linux machines). Note the removal of the <emphasis
role="bold">.rc</emphasis> extension as you copy the script. <programlisting>
# <emphasis role="bold">cp -p afs.rc /etc/rc.d/init.d/afs</emphasis>
</programlisting></para>
</listitem>
-
<listitem>
- <para>Run the AFS initialization script to load AFS extensions into the kernel. You can ignore any error messages
- about the inability to start the BOS Server or the Cache Manager or AFS client. <programlisting>
- # <emphasis role="bold">/etc/rc.d/init.d/afs start</emphasis>
-</programlisting> <indexterm>
+ <indexterm>
<primary>configuring</primary>
<secondary>AFS server partition on server machine after first</secondary>
<secondary>AFS server partition</secondary>
<tertiary>on add'l server machine</tertiary>
- </indexterm></para>
- </listitem>
-
- <listitem>
+ </indexterm>
<para>Create a directory called <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> for each AFS
server partition you are configuring (there must be at least one). Repeat the command for each partition.
<programlisting>
<listitem>
<para>Proceed to <link linkend="HDRWQ108">Starting Server Programs</link>.</para>
</listitem>
- </orderedlist></para>
+ </orderedlist>
</sect3>
<sect3 id="HDRWQ107">
</indexterm>
<listitem>
- <para>Mount the AFS CD-ROM for Solaris on the <emphasis role="bold">/cdrom</emphasis> directory. For instructions on
- mounting CD-ROMs (either locally or remotely via NFS), see your Solaris documentation. Then change directory as
- indicated. <programlisting>
- # <emphasis role="bold">cd /cdrom/sun4x_56/root.client/usr/vice/etc</emphasis>
+ <para>Unpack the OpenAFS Solaris distribution tarball. The examples
+ below assume that you have unpacked the files into the
+ <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you
+ pick a diferent location, substitute this in all of the following
+ exmaples. Once you have unpacked the distribution, change directory
+ as indicated.
+<programlisting>
+ # <emphasis role="bold">cd /tmp/afsdist/sun4x_56/root.client/usr/vice/etc</emphasis>
</programlisting></para>
</listitem>
</indexterm>
<indexterm>
- <primary>CD-ROM</primary>
+ <primary>Binary Distribution</primary>
<secondary>copying server files from</secondary>
<listitem>
<para>Copy file server binaries to the local <emphasis role="bold">/usr/afs/bin</emphasis> directory. <itemizedlist>
<listitem>
- <para>On a machine of an existing system type, you can either load files from the AFS CD-ROM or use a remote file
- transfer protocol to copy files from an existing server machine of the same system type. To load from the CD-ROM,
- see the instructions just following for a machine of a new system type. If using a remote file transfer protocol,
- copy the complete contents of the existing server machine's <emphasis role="bold">/usr/afs/bin</emphasis>
+ <para>On a machine of an existing system type, you can either
+ copy files from the OpenAFS binary distribution or use a
+ remote file transfer protocol to copy files from an existing
+ server machine of the same system type. To load from the
+ binary distribution, see the instructions just following for
+ a machine of a new system type. If using a remote file
+ transfer protocol, copy the complete contents of the
+ existing server machine's
+ <emphasis role="bold">/usr/afs/bin</emphasis>
directory.</para>
</listitem>
<listitem>
- <para>On a machine of a new system type, you must use the following instructions to copy files from the AFS
- CD-ROM. <orderedlist>
+ <para>If you are working from a tarball distribtion, rather
+ than one distributed in a packaged format, you must use the
+ following instructions to copy files from
+ the OpenAFS Binary Distribution.
+ <orderedlist>
<listitem>
- <para>On the local <emphasis role="bold">/cdrom</emphasis> directory, mount the AFS CD-ROM for this
- machine's system type, if it is not already. For instructions on mounting CD-ROMs (either locally or
- remotely via NFS), consult the operating system documentation.</para>
+ <para>Unpack the distribution tarball. The examples
+ below assume that you have unpacked the files into the
+ <emphasis role="bold">/tmp/afsdist</emphasis>
+ directory. If you pick a different location, substitute
+ this in all of the following examples.</para>
</listitem>
<listitem>
- <para>Copy files from the CD-ROM to the local <emphasis role="bold">/usr/afs</emphasis> directory.
+ <para>Copy files from the distribution to the local <emphasis role="bold">/usr/afs</emphasis> directory.
<programlisting>
- # <emphasis role="bold">cd /cdrom/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/root.server/usr/afs</emphasis>
+ # <emphasis role="bold">cd /tmp/afsdist/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/root.server/usr/afs</emphasis>
# <emphasis role="bold">cp -rp * /usr/afs</emphasis>
</programlisting></para>
</listitem>
</listitem>
<listitem>
- <para>Copy the contents of the <emphasis role="bold">/usr/afs/etc</emphasis> directory from an existing file server
- machine, using a remote file transfer protocol such as <emphasis role="bold">ftp</emphasis> or NFS. If you use a system
- control machine, it is best to copy the contents of its <emphasis role="bold">/usr/afs/etc</emphasis> directory. If you
- choose not to run a system control machine, copy the directory's contents from any existing file server machine.
+ <para>Copy the contents of the
+ <emphasis role="bold">/usr/afs/etc</emphasis> directory from an
+ existing file server machine, using a remote file transfer protocol
+ such as <emphasis role="bold">sftp</emphasis> or
+ <emphasis role="bold">scp</emphasis>. If you use a system
+ control machine, it is best to copy the contents of its
+ <emphasis role="bold">/usr/afs/etc</emphasis> directory. If you
+ choose not to run a system control machine, copy the directory's
+ contents from any existing file server machine.
<indexterm>
<primary>BOS Server</primary>
</listitem>
<listitem>
- <para><anchor id="LIWQ110" />Create an instance of the Update Server to handle distribution of the file server binaries
- stored in the <emphasis role="bold">/usr/afs/bin</emphasis> directory. <itemizedlist>
+ <para><anchor id="LIWQ110" />Create an instance of the Update
+ Server to handle distribution of the file server binaries
+ stored in the <emphasis role="bold">/usr/afs/bin</emphasis>
+ directory. If your architecture using a package management system
+ such as 'rpm' or 'apt' to maintain its binaries, note that
+ distributing binaries via this system may interfere with your local
+ package management tools.
+ </para>
+
+ <itemizedlist>
<listitem>
<para>If this is the first file server machine of its AFS system type, create the <emphasis
role="bold">upserver</emphasis> process as an instance of the server portion of the Update Server. It distributes
<para>By default, the Update Server performs updates every 300 seconds (five minutes). Use the <emphasis
role="bold">-t</emphasis> argument to specify an different number of seconds.</para>
- <programlisting>
+<programlisting>
# <emphasis role="bold">./bos create</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">upclientbin simple</emphasis> \
<emphasis role="bold">"/usr/afs/bin/upclient</emphasis> <<replaceable>binary distribution machine</replaceable>> \
[<emphasis role="bold">-t</emphasis> <<replaceable>time</replaceable>>] <emphasis role="bold">-clear /usr/afs/bin" -cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis
role="bold">-noauth</emphasis>
</programlisting>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
<indexterm>
<primary>runntp process</primary>
</listitem>
<listitem>
+
+ <note>
+ <para>Historically, AFS provided its own version of the
+ Network Time Protocol Daemon. Whilst this is still provided for
+ existing sites, we recommend that you configure and run your
+ own timeservice independently of AFS. The instructions below are
+ provided for those sites still reliant upon OpenAFS's ntp system.
+ </para>
+ </note>
+
<para>Start the <emphasis role="bold">runntp</emphasis> process, which configures the Network Time Protocol Daemon
(NTPD) to choose a database server machine chosen randomly from the local <emphasis
role="bold">/usr/afs/etc/CellServDB</emphasis> file as its time source. In the standard configuration, the first
role="bold">/usr/afsws</emphasis> to the appropriate location in the AFS file tree) on this machine itself. If you also want
to create AFS volumes to house UNIX system binaries for the new system type, see <link linkend="HDRWQ88">Storing System
Binaries in AFS</link>. <indexterm>
- <primary>CD-ROM</primary>
+ <primary>Binary Distribution</primary>
<secondary>copying client files from</secondary>
<listitem>
<para>Copy client binaries and files to the local disk. <itemizedlist>
<listitem>
- <para>On a machine of an existing system type, you can either load files from the AFS CD-ROM or use a remote file
- transfer protocol to copy files from an existing server machine of the same system type. To load from the CD-ROM,
- see the instructions just following for a machine of a new system type. If using a remote file transfer protocol,
- copy the complete contents of the existing client machine's <emphasis role="bold">/usr/vice/etc</emphasis>
+ <para>On a machine of an existing system type, you can either
+ load files from the OpenAFS Binary Distribution or use a
+ remote file transfer protocol to copy files from an existing
+ server machine of the same system type. To load from the
+ binary distribution, see the instructions just following
+ for a machine of a new system type. If using a remote file
+ transfer protocol, copy the complete contents of the existing
+ client machine's
+ <emphasis role="bold">/usr/vice/etc</emphasis>
directory.</para>
</listitem>
<listitem>
- <para>On a machine of a new system type, you must use the following instructions to copy files from the AFS
- CD-ROM. <orderedlist>
+ <para>On a machine of a new system type, you must use the
+ following instructions to copy files from the OpenAFS
+ Binary Distribution. If your distribution is provided in
+ a packaged format, then simply installing the packages will
+ perform the necessary actions.
+ <orderedlist>
<listitem>
- <para>On the local <emphasis role="bold">/cdrom</emphasis> directory, mount the AFS CD-ROM for this
- machine's system type, if it is not already. For instructions on mounting CD-ROMs (either locally or
- remotely via NFS), consult the operating system documentation.</para>
+ <para>Unpack the distribution tarball. The examples
+ below assume that you have unpacked the files into the
+ <emphasis role="bold">/tmp/afsdist</emphasis>
+ directory. If you pick a different location, substitute
+ this in all of the following examples.</para>
</listitem>
<listitem>
command.</para>
<programlisting>
- # <emphasis role="bold">cd /cdrom/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/root.client/usr/vice/etc</emphasis>
+ # <emphasis role="bold">cd /tmp/afsdist/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/root.client/usr/vice/etc</emphasis>
# <emphasis role="bold">cp -p * /usr/vice/etc</emphasis>
# <emphasis role="bold">cp -rp C /usr/vice/etc</emphasis>
</programlisting>
</listitem>
<listitem>
- <para>Create the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file. Use a network file transfer program
- such as <emphasis role="bold">ftp</emphasis> or NFS to copy it from one of the following sources, which are listed in
- decreasing order of preference: <itemizedlist>
+ <para>Create the
+ <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file.
+ Use a network file transfer program such as
+ <emphasis role="bold">sftp</emphasis> or
+ <emphasis role="bold">scp</emphasis> to copy it from
+ one of the following sources, which are listed in
+ decreasing order of preference:
+ <itemizedlist>
<listitem>
<para>Your cell's central <emphasis role="bold">CellServDB</emphasis> source file (the conventional location is
<emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
</listitem>
<listitem>
- <para>The global <emphasis role="bold">CellServDB</emphasis> file maintained by the AFS Product Support
- group</para>
+ <para>The global <emphasis role="bold">CellServDB</emphasis>
+ file maintained at grand.central.org</para>
</listitem>
<listitem>
</listitem>
<listitem>
- <para>The <emphasis role="bold">CellServDB.sample</emphasis> file included in the
- <replaceable>sysname</replaceable><emphasis role="bold">/root.client/usr/vice/etc</emphasis> directory of each AFS
- CD-ROM; add an entry for the local cell by following the instructions in <link linkend="HDRWQ66">Creating the
- Client CellServDB File</link></para>
+ <para>The <emphasis role="bold">CellServDB.sample</emphasis>
+ file included in the
+ <replaceable>sysname</replaceable><emphasis role="bold">/root.client/usr/vice/etc</emphasis>
+ directory of each OpenAFS distribution; add an entry for the
+ local cell by following the instructions in
+ <link linkend="HDRWQ66">Creating the Client CellServDB File</link>
+ </para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
<indexterm>
<primary>cache</primary>
</listitem>
<listitem>
- <para>On Linux systems, copy the <emphasis role="bold">afsd</emphasis> options file from the <emphasis
+ <para>On non-packaged Linux systems, copy the <emphasis role="bold">afsd</emphasis> options file from the <emphasis
role="bold">/usr/vice/etc</emphasis> directory to the <emphasis role="bold">/etc/sysconfig</emphasis> directory,
removing the <emphasis role="bold">.conf</emphasis> extension as you do so. <programlisting>
# <emphasis role="bold">cp /usr/vice/etc/afs.conf /etc/sysconfig/afs</emphasis>
</listitem>
<listitem>
- <para>On Linux systems, <emphasis role="bold">/etc/sysconfig/afs</emphasis> (the <emphasis
+ <para>On Fedora and RHEL systems,
+ <emphasis role="bold">/etc/sysconfig/openafs</emphasis>.
+ Note that this file has a different format from a standard
+ afsd options file.</para>
+ </listitem>
+
+ <listitem>
+ <para>On non-packaged Linux systems, <emphasis role="bold">/etc/sysconfig/afs</emphasis> (the <emphasis
role="bold">afsd</emphasis> options file)</para>
</listitem>
+
<listitem>
<para>On Solaris systems, <emphasis role="bold">/etc/init.d/afs</emphasis></para>
<para>Use one of the methods described in <link linkend="HDRWQ70">Configuring the Cache Manager</link> to add the
following flags to the <emphasis role="bold">afsd</emphasis> command line. If you intend for the machine to remain an
AFS client, also set any performance-related arguments you wish. <itemizedlist>
+ <!-- nosetime is now the default
<listitem>
<para>Add the <emphasis role="bold">-nosettime</emphasis> flag, because this is a file server machine that is also
a client.</para>
- </listitem>
+ </listitem> -->
<listitem>
<para>Add the <emphasis role="bold">-memcache</emphasis> flag if the machine is to use a memory cache.</para>
<para>Add the <emphasis role="bold">-verbose</emphasis> flag to display a trace of the Cache Manager's
initialization on the standard output stream.</para>
</listitem>
+ <listitem>
+ <para>Add the <emphasis role="bold">--dynroot</emphasis> or
+ <emphasis role="bold">--afsdb</emphasis> options if you
+ wish to have a synthetic AFS root, as discussed in
+ <link linkend="HDRWQ91">Enabling Access to Foreign Cells</link>
+ </para>
+ </listitem>
</itemizedlist></para>
</listitem>
<tertiary>on add'l server machine</tertiary>
</indexterm>
+ <para><emphasis role="bold">On Fedora or RHEL Linux systems:</emphasis>
+ <orderedlist>
+ <listitem>
+ <para>Reboot the machine and log in again as the local superuser <emphasis role="bold">root</emphasis>.
+ <programlisting>
+ # <emphasis role="bold">cd /</emphasis>
+ # <emphasis role="bold">shutdown -r now</emphasis>
+ login: <emphasis role="bold">root</emphasis>
+ Password: <replaceable>root_password</replaceable>
+</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>Run the OpenAFS initialization scripts. <programlisting>
+ # <emphasis role="bold">/etc/rc.d/init.d/openafs-client start</emphasis>
+ # <emphasis role="bold">/etc/rc.d/init.d/openafs-server start</emphasis>
+</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>Issue the <emphasis role="bold">chkconfig</emphasis>
+ command to activate the
+ <emphasis role="bold">openafs-client</emphasis> and
+ <emphasis role="bold">openafs-server</emphasis> configuration
+ variables. Based on the instruction in the AFS initialization
+ files that begins with the string
+ <computeroutput>#chkconfig</computeroutput>, the command
+ automatically creates the symbolic links that incorporate the
+ script into the Linux startup and shutdown sequence.
+<programlisting>
+ # <emphasis role="bold">/sbin/chkconfig --add openafs-client</emphasis>
+ # <emphasis role="bold">/sbin/chkconfig --add openafs-server</emphasis>
+</programlisting></para>
+ </listitem>
+ </orderedlist>
+ </para>
<para><emphasis role="bold">On Linux systems:</emphasis> <orderedlist>
<listitem>
<para>Reboot the machine and log in again as the local superuser <emphasis role="bold">root</emphasis>.
</listitem>
<listitem>
- <para>Run the AFS initialization script. <programlisting>
+ <para>Run the OpenAFS initialization script. <programlisting>
# <emphasis role="bold">/etc/rc.d/init.d/afs start</emphasis>
</programlisting></para>
</listitem>
<para><emphasis role="bold">(Optional)</emphasis> There are now copies of the AFS initialization file in both the
<emphasis role="bold">/usr/vice/etc</emphasis> and <emphasis role="bold">/etc/init.d</emphasis> directories. If
you want to avoid potential confusion by guaranteeing that they are always the same, create a link between them.
- You can always retrieve the original script from the AFS CD-ROM if necessary. <programlisting>
+ You can always retrieve the original script from the OpenAFS Binary Distribution if necessary. <programlisting>
# <emphasis role="bold">cd /usr/vice/etc</emphasis>
# <emphasis role="bold">rm afs.rc</emphasis>
# <emphasis role="bold">ln -s /etc/init.d/afs afs.rc</emphasis>
<title>Installing Database Server Functionality</title>
<para>This section explains how to install database server functionality. Database server machines have two defining
- characteristics. First, they run the Authentication Server, Protection Server, and Volume Location (VL) Server processes. They
+ characteristics. First, they run the Protection Server, and Volume Location (VL) Server processes. They
also run the Backup Server if the cell uses the AFS Backup System, as is assumed in these instructions. Second, they appear in
the <emphasis role="bold">CellServDB</emphasis> file of every machine in the cell (and of client machines in foreign cells, if
they are to access files in this cell).</para>
Guide</emphasis> about maintaining server encryption keys.</para>
<para>The instructions in this section assume that the machine on which you are installing database server functionality
- is already a file server machine. Contact the AFS Product Support group to learn how to install database server
+ is already a file server machine. Contact the OpenAFS mailing list to learn how to install database server
functionality on a non-file server machine.</para>
</listitem>
</listitem>
<listitem>
- <para>Start the database server processes (Authentication Server, Backup Server, Protection Server, and Volume Location
+ <para>Start the database server processes (Backup Server, Protection Server, and Volume Location
Server)</para>
</listitem>
</listitem>
<listitem>
- <para>Notify the AFS Product Support group that you have installed a new database server machine</para>
+ <para>If required, request that grand.central.org add details of
+ your new database server machine to the global CellServDB</para>
</listitem>
+
+ <listitem>
+ <para>If required, add details of your new database server to the
+ AFS database location records in your site's DNS</para>
+ </listitem>
+
</orderedlist></para>
<indexterm>
<orderedlist>
<listitem>
<para>You can perform the following instructions on either a server or client machine. Login as an AFS administrator who
- is listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file on all server machines. <programlisting>
- % <emphasis role="bold">klog</emphasis> <replaceable>admin_user</replaceable>
+ is listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file on all server machines.
+<programlisting>
+ % <emphasis role="bold">kinit</emphasis> <replaceable>admin_user</replaceable>
Password: <replaceable>admin_password</replaceable>
-</programlisting></para>
+ % <emphasis role="bold">aklog</emphasis>
+</programlisting>
+ </para>
</listitem>
<listitem>
option is to copy over the central update source (which you updated in Step <link linkend="LIWQ116">5</link>), with or
without using the <emphasis role="bold">package</emphasis> program. To update the machine's kernel memory list, you can
either reboot after changing the <emphasis role="bold">CellServDB</emphasis> file or issue the <emphasis role="bold">fs
- newcell</emphasis> command. <indexterm>
- <primary>Authentication Server</primary>
-
- <secondary>starting</secondary>
-
- <tertiary>new db-server machine</tertiary>
- </indexterm> <indexterm>
- <primary>starting</primary>
-
- <secondary>Authentication Server</secondary>
-
- <tertiary>new db-server machine</tertiary>
- </indexterm> <indexterm>
+ newcell</emphasis> command.
+ <indexterm>
<primary>database server machine</primary>
<secondary>starting database server processes</secondary>
<tertiary>database server machine</tertiary>
</indexterm></para>
</listitem>
-
+
<listitem>
- <para><anchor id="LIWQ118" />Start the Authentication Server (the <emphasis role="bold">kaserver</emphasis> process).
- <programlisting>
- % <emphasis role="bold">bos create</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">kaserver simple /usr/afs/bin/kaserver</emphasis>
-</programlisting> <indexterm>
- <primary>Backup Server</primary>
-
- <secondary>starting</secondary>
-
- <tertiary>new db-server machine</tertiary>
- </indexterm> <indexterm>
- <primary>starting</primary>
-
- <secondary>Backup Server</secondary>
-
- <tertiary>new db-server machine</tertiary>
- </indexterm></para>
+ <para>If you are running a cell which still relies upon
+ <emphasis role="bold">kaserver</emphasis> see
+ <link linkend="KAS010">Starting the Authentication Service</link>
+ for an additional installation step.</para>
</listitem>
<listitem>
+ <indexterm>
+ <primary>Backup Server</primary>
+ <secondary>starting</secondary>
+ <tertiary>new db-server machine</tertiary>
+ </indexterm> <indexterm>
+ <primary>starting</primary>
+ <secondary>Backup Server</secondary>
+ <tertiary>new db-server machine</tertiary>
+ </indexterm>
+
<para><anchor id="LIWQ119" />Start the Backup Server (the <emphasis role="bold">buserver</emphasis> process). You must
perform other configuration procedures before actually using the AFS Backup System, as detailed in the <emphasis>OpenAFS
Administration Guide</emphasis>. <programlisting>
</listitem>
<listitem>
- <para><anchor id="LIWQ124" />Send the new database server machine's name and IP address to the AFS Product Support
- group.</para>
-
- <para>If you wish to participate in the AFS global name space, your cell's entry appear in a <emphasis
- role="bold">CellServDB</emphasis> file that the AFS Product Support group makes available to all AFS sites. Otherwise,
- they list your cell in a private file that they do not share with other AFS sites.</para>
+ <para><anchor id="LIWQ124" />If you wish to participate in the AFS
+ global name space, send the new database server machine's name and
+ IP address to grand.central.org. Do so, by emailing an updated
+ <emphasis role="bold">CellServDB</emphasis> fragment for your cell
+ to cellservdb@grand.central.org</para>
+ <para>More details on the registration procedures for the
+ CellServDB maintained by grand.central.org are available from
+ <ulink url="http://grand.central.org/csdb.html">
+ http://grand.central.org/csdb.html</ulink></para>
</listitem>
</orderedlist>
</listitem>
<listitem>
- <para>Notify the AFS Product Support group that you are decommissioning a database server machine</para>
+ <para>If you participate in the global AFS namespace, notify
+ grand.central.org that you are decommissioning a database server
+ machine</para>
</listitem>
<listitem>
<orderedlist>
<listitem>
<para>You can perform the following instructions on either a server or client machine. Login as an AFS administrator who
- is listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file on all server machines. <programlisting>
- % <emphasis role="bold">klog</emphasis> <replaceable>admin_user</replaceable>
+ is listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file on all server machines.
+<programlisting>
+ % <emphasis role="bold">kinit</emphasis> <replaceable>admin_user</replaceable>
Password: <replaceable>admin_password</replaceable>
+ % <emphasis role="bold">aklog</emphasis>
</programlisting></para>
</listitem>
</listitem>
<listitem>
- <para><anchor id="LIWQ126" />Send the revised list of your cell's database server machines to the AFS Product Support
- group.</para>
+ <para><anchor id="LIWQ126" />If your cell is included in the global
+ <emphasis role="bold">CellServDB</emphasis>, send the revised list of
+ your cell's database server machines to grand.central.org</para>
- <para>This step is particularly important if your cell is included in the global <emphasis
- role="bold">CellServDB</emphasis> file. If the administrators in foreign cells do not learn about the change in your cell,
+ <para>If the administrators in foreign cells do not learn about the change in your cell,
they cannot update the <emphasis role="bold">CellServDB</emphasis> file on their client machines. Users in foreign cells
continue to send database requests to the decommissioned machine, which creates needless network traffic and activity on
the machine. Also, the users experience time-out delays while their request is forwarded to a valid database server
delete</emphasis> command to remove the entries for database server processes from the <emphasis
role="bold">BosConfig</emphasis> file. This step is unnecessary if you plan to restart the database server functionality
on this machine in future. <programlisting>
- % <emphasis role="bold">bos delete</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">kaserver buserver ptserver vlserver</emphasis>
+ % <emphasis role="bold">bos delete</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">buserver ptserver vlserver</emphasis>
</programlisting> <indexterm>
<primary>commands</primary>
<listitem>
<para><anchor id="LIWQ132" />Issue the <emphasis role="bold">bos restart</emphasis> command on every database server
- machine in the cell, to restart the Authentication, Backup, Protection, and VL Servers. This forces the election of a Ubik
+ machine in the cell, to restart the Backup, Protection, and VL Servers. This forces the election of a Ubik
coordinator for each process, ensuring that the remaining database server processes recognize that the machine is no
longer a database server.</para>
the lowest IP address.</para>
<programlisting>
- % <emphasis role="bold">bos restart</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">kaserver buserver ptserver vlserver</emphasis>
+ % <emphasis role="bold">bos restart</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">buserver ptserver vlserver</emphasis>
</programlisting>
<para>If an error occurs, restart all server processes on the database server machines again by using one of the following
</orderedlist>
<indexterm>
- <primary>CD-ROM</primary>
+ <primary>Binary Distribution</primary>
- <secondary>creating /cdrom directory</secondary>
+ <secondary>creating /tmp/afsdist directory</secondary>
<tertiary>client machine</tertiary>
</indexterm>
<indexterm>
- <primary>cdrom directory</primary>
+ <primary>afsdist directory</primary>
<secondary>client machine</secondary>
</indexterm>
<indexterm>
<primary>client machine</primary>
- <secondary>/cdrom directory</secondary>
+ <secondary>/tmp/afsdist directory</secondary>
</indexterm>
<indexterm>
<primary>creating</primary>
- <secondary>/cdrom directory</secondary>
+ <secondary>/tmp/afsdist directory</secondary>
<tertiary>client machine</tertiary>
</indexterm>
<sect1 id="HDRWQ134">
<title>Creating AFS Directories on the Local Disk</title>
- <para>Create the <emphasis role="bold">/usr/vice/etc</emphasis> directory on the local disk, to house client binaries and
- configuration files. Subsequent instructions copy files from the AFS CD-ROM into them. Create the <emphasis
- role="bold">/cdrom</emphasis> directory as a mount point for the CD-ROM, if it does not already exist.</para>
+ <para>If you are not installing from a packaged distribution, create the <emphasis role="bold">/usr/vice/etc</emphasis> directory on the local disk, to house client binaries and
+ configuration files. Subsequent instructions copy files from the OpenAFS binary distribution into them. Create the <emphasis
+ role="bold">/tmp/afsdist</emphasis> directory as a location to uncompress this distribution, if it does not already exist.</para>
<programlisting>
# <emphasis role="bold">mkdir /usr/vice</emphasis>
# <emphasis role="bold">mkdir /usr/vice/etc</emphasis>
- # <emphasis role="bold">mkdir /cdrom</emphasis>
+ # <emphasis role="bold">mkdir /tmp/afsdist</emphasis>
</programlisting>
</sect1>
<para>Also modify the machine's authentication system so that users obtain an AFS token as they log into the local file system.
Using AFS is simpler and more convenient for your users if you make the modifications on all client machines. Otherwise, users
- must perform a two-step login procedure (login to the local file system and then issue the <emphasis role="bold">klog</emphasis>
+ must perform a two or three step login procedure (login to the local system, obtain Kerberos credentials, and then issue the <emphasis role="bold">klog</emphasis>
command). For further discussion of AFS authentication, see the chapter in the <emphasis>OpenAFS Administration Guide</emphasis>
about cell configuration and administration issues.</para>
correctly initializes the Cache Manager, then configure the AIX <emphasis role="bold">inittab</emphasis> file so that the
script runs automatically at reboot. <orderedlist>
<listitem>
- <para>Mount the AFS CD-ROM for AIX on the local <emphasis role="bold">/cdrom</emphasis> directory. For instructions on
- mounting CD-ROMs (either locally or remotely via NFS), see your AIX documentation. Then change directory as indicated.
- <programlisting>
- # <emphasis role="bold">cd /cdrom/rs_aix42/root.client/usr/vice/etc</emphasis>
+ <para>Unpack the distribution tarball. The examples below assume
+ that you have unpacked the files into the
+ <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you
+ pick a different location, substitute this in all of the following
+ examples. Once you have unpacked the distribution,
+ change directory as indicated.
+<programlisting>
+ # <emphasis role="bold">cd /tmp/afsdist/rs_aix42/root.client/usr/vice/etc</emphasis>
</programlisting></para>
</listitem>
-
<listitem>
<para>Copy the AFS kernel library files to the local <emphasis role="bold">/usr/vice/etc/dkload</emphasis> directory,
and the AFS initialization script to the <emphasis role="bold">/etc</emphasis> directory. <programlisting>
<sect2 id="Header_121">
<title>Enabling AFS Login on AIX Systems</title>
- <para>Now incorporate AFS into the AIX secondary authentication system. <orderedlist>
- <listitem>
- <para>Issue the <emphasis role="bold">ls</emphasis> command to verify that the <emphasis
- role="bold">afs_dynamic_auth</emphasis> and <emphasis role="bold">afs_dynamic_kerbauth</emphasis> programs are installed
- in the local <emphasis role="bold">/usr/vice/etc</emphasis> directory. <programlisting>
- # <emphasis role="bold">ls /usr/vice/etc</emphasis>
-</programlisting></para>
+ <para>In modern AFS installations, you should be using Kerberos v5
+ for user login, and obtaining AFS tokens following this authentication
+ step.</para>
+
+ <para>There are currently no instructions available on configuring AIX to
+ automatically obtain AFS tokens at login. Following login, users can
+ obtain tokens by running the <emphasis role="bold">aklog</emphasis>
+ command</para>
- <para>If the files do not exist, mount the AFS CD-ROM for AIX (if it is not already), change directory as indicated, and
- copy them.</para>
-
- <programlisting>
- # <emphasis role="bold">cd /cdrom/rs_aix42/root.client/usr/vice/etc</emphasis>
- # <emphasis role="bold">cp -p afs_dynamic* /usr/vice/etc</emphasis>
-</programlisting>
- </listitem>
-
- <listitem>
- <para>Edit the local <emphasis role="bold">/etc/security/user</emphasis> file, making changes to the indicated stanzas:
- <itemizedlist>
- <listitem>
- <para>In the default stanza, set the <computeroutput>registry</computeroutput> attribute to <emphasis
- role="bold">DCE</emphasis> (not to <emphasis role="bold">AFS</emphasis>), as follows: <programlisting>
- registry = DCE
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>In the default stanza, set the <computeroutput>SYSTEM</computeroutput> attribute as indicated.</para>
-
- <para>If the machine is an AFS client only, set the following value:</para>
-
- <programlisting>
- SYSTEM = "AFS OR (AFS[UNAVAIL] AND compat[SUCCESS])"
-</programlisting>
-
- <para>If the machine is both an AFS and a DCE client, set the following value (it must appear on a single line in
- the file):</para>
-
- <programlisting>
- SYSTEM = "DCE OR DCE[UNAVAIL] OR AFS OR (AFS[UNAVAIL] \
- AND compat[SUCCESS])"
-</programlisting>
- </listitem>
-
- <listitem>
- <para>In the <computeroutput>root</computeroutput> stanza, set the <computeroutput>registry</computeroutput>
- attribute as follows. It enables the local superuser <emphasis role="bold">root</emphasis> to log into the local
- file system only, based on the password listed in the local password file. <programlisting>
- root:
- registry = files
-</programlisting></para>
- </listitem>
- </itemizedlist></para>
- </listitem>
-
- <listitem>
- <para>Edit the local <emphasis role="bold">/etc/security/login.cfg</emphasis> file, creating or editing the indicated
- stanzas: <itemizedlist>
- <listitem>
- <para>In the <computeroutput>DCE</computeroutput> stanza, set the <computeroutput>program</computeroutput>
- attribute as follows.</para>
-
- <para>If you use the AFS Authentication Server (<emphasis role="bold">kaserver</emphasis> process):</para>
-
- <programlisting>
- DCE:
- program = /usr/vice/etc/afs_dynamic_auth
-</programlisting>
-
- <para>If you use a Kerberos implementation of AFS authentication:</para>
-
- <programlisting>
- DCE:
- program = /usr/vice/etc/afs_dynamic_kerbauth
-</programlisting>
- </listitem>
-
- <listitem>
- <para>In the <computeroutput>AFS</computeroutput> stanza, set the <computeroutput>program</computeroutput>
- attribute as follows.</para>
-
- <para>If you use the AFS Authentication Server (<emphasis role="bold">kaserver</emphasis> process):</para>
-
- <programlisting>
- AFS:
- program = /usr/vice/etc/afs_dynamic_auth
-</programlisting>
-
- <para>If you use a Kerberos implementation of AFS authentication:</para>
-
- <programlisting>
- AFS:
- program = /usr/vice/etc/afs_dynamic_kerbauth
-</programlisting>
- </listitem>
- </itemizedlist></para>
- </listitem>
+ <para>Sites which still require <emphasis role="bold">kaserver</emphasis>
+ or external Kerberos v4 authentication should consult
+ <link linkend="KAS012">Enabling kaserver based AFS Login on AIX Systems</link>
+ for details of how to enable AIX login.</para>
+ <para><orderedlist>
<listitem>
<para>Proceed to <link linkend="HDRWQ145">Loading and Creating Client Files</link>.</para>
</listitem>
</listitem>
<listitem>
- <para>Mount the AFS CD-ROM for HP-UX on the local <emphasis role="bold">/cdrom</emphasis> directory. For instructions on
- mounting CD-ROMs (either locally or remotely via NFS), see your HP-UX documentation. Then change directory as indicated.
+ <para>Unpack the OpenAFS HP-UX distribution tarball. The examples
+ below assume that you have unpacked the files into the
+ <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you
+ pick a different location, substitute this in all of the following
+ examples. Once you have unpacked the distribution, change directory
+ as indicated.
<programlisting>
- # <emphasis role="bold">cd /cdrom/hp_ux110/root.client</emphasis>
+ # <emphasis role="bold">cd /tmp/afsdist/hp_ux110/root.client</emphasis>
</programlisting></para>
</listitem>
integrates all authentication mechanisms on the machine, including login, to provide the security infrastructure for
authenticated access to and from the machine.</para>
- <para>Explaining PAM is beyond the scope of this document. It is assumed that you understand the syntax and meanings of
- settings in the PAM configuration file (for example, how the <computeroutput>other</computeroutput> entry works, the effect of
- marking an entry as <computeroutput>required</computeroutput>, <computeroutput>optional</computeroutput>, or
- <computeroutput>sufficient</computeroutput>, and so on).</para>
-
- <para>The following instructions explain how to alter the entries in the PAM configuration file for each service for which you
- wish to use AFS authentication. Other configurations possibly also work, but the instructions specify the recommended and
- tested configuration.</para>
-
- <note>
- <para>The instructions specify that you mark each entry as <computeroutput>optional</computeroutput>. However, marking some
- modules as optional can mean that they grant access to the corresponding service even when the user does not meet all of the
- module's requirements. In some operating system revisions, for example, if you mark as optional the module that controls
- login via a dial-up connection, it allows users to login without providing a password. See the <emphasis>OpenAFS Release
- Notes</emphasis> for a discussion of any limitations that apply to this operating system.</para>
-
- <para>Also, with some operating system versions you must install patches for PAM to interact correctly with certain
- authentication programs. For details, see the <emphasis>OpenAFS Release Notes</emphasis>.</para>
- </note>
-
- <para>The recommended AFS-related entries in the PAM configuration file make use of one or more of the following three
- attributes. <variablelist>
- <varlistentry>
- <term><emphasis role="bold"><computeroutput>try_first_pass</computeroutput></emphasis></term>
-
- <listitem>
- <para>This is a standard PAM attribute that can be included on entries after the first one for a service; it directs
- the module to use the password that was provided to the first module. For the AFS module, it means that AFS
- authentication succeeds if the password provided to the module listed first is the user's correct AFS password. For
- further discussion of this attribute and its alternatives, see the operating system's PAM documentation.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="bold"><computeroutput>ignore_root</computeroutput></emphasis></term>
-
- <listitem>
- <para>This attribute, specific to the AFS PAM module, directs it to ignore not only the local superuser <emphasis
- role="bold">root</emphasis>, but also any user with UID 0 (zero).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="bold"><computeroutput>setenv_password_expires</computeroutput></emphasis></term>
-
- <listitem>
- <para>This attribute, specific to the AFS PAM module, sets the environment variable PASSWORD_EXPIRES to the expiration
- date of the user's AFS password, which is recorded in the Authentication Database.</para>
- </listitem>
- </varlistentry>
- </variablelist></para>
-
- <para>Perform the following steps to enable AFS login. <orderedlist>
- <listitem>
- <para>Mount the AFS CD-ROM for HP-UX on the <emphasis role="bold">/cdrom</emphasis> directory, if it is not already.
- Then change directory as indicated. <programlisting>
- # <emphasis role="bold">cd /usr/lib/security</emphasis>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Copy the AFS authentication library file to the <emphasis role="bold">/usr/lib/security</emphasis> directory. Then
- create a symbolic link to it whose name does not mention the version. Omitting the version eliminates the need to edit
- the PAM configuration file if you later update the library file.</para>
-
- <para>If you use the AFS Authentication Server (<emphasis role="bold">kaserver</emphasis> process) in the cell:</para>
-
- <programlisting>
- # <emphasis role="bold">cp /cdrom/hp_ux110/lib/pam_afs.so.1 .</emphasis>
- # <emphasis role="bold">ln -s pam_afs.so.1 pam_afs.so</emphasis>
-</programlisting>
-
- <para>If you use a Kerberos implementation of AFS authentication:</para>
-
- <programlisting>
- # <emphasis role="bold">cp /cdrom/hp_ux110/lib/pam_afs.krb.so.1 .</emphasis>
- # <emphasis role="bold">ln -s pam_afs.krb.so.1 pam_afs.so</emphasis>
-</programlisting>
- </listitem>
-
- <listitem>
- <para>Edit the <computeroutput>Authentication management</computeroutput> section of the HP-UX PAM configuration file,
- <emphasis role="bold">/etc/pam.conf</emphasis> by convention. The entries in this section have the value
- <computeroutput>auth</computeroutput> in their second field.</para>
-
- <para>First edit the standard entries, which refer to the HP-UX PAM module (usually, the file <emphasis
- role="bold">/usr/lib/security/libpam_unix.1</emphasis>) in their fourth field. For each service for which you want to
- use AFS authentication, edit the third field of its entry to read <computeroutput>optional</computeroutput>. The
- <emphasis role="bold">pam.conf</emphasis> file in the HP-UX distribution usually includes standard entries for the
- <emphasis role="bold">login</emphasis> and <emphasis role="bold">ftp</emphasis> services, for instance.</para>
-
- <para>If there are services for which you want to use AFS authentication, but for which the <emphasis
- role="bold">pam.conf</emphasis> file does not already include a standard entry, you must create that entry and place the
- value <computeroutput>optional</computeroutput> in its third field. For instance, the HP-UX <emphasis
- role="bold">pam.conf</emphasis> file does not usually include standard entries for the <emphasis
- role="bold">remsh</emphasis> or <emphasis role="bold">telnet</emphasis> services.</para>
-
- <para>Then create an AFS-related entry for each service, placing it immediately below the standard entry. The following
- example shows what the <computeroutput>Authentication Management</computeroutput> section looks like after you have you
- edited or created entries for the services mentioned previously. Note that the example AFS entries appear on two lines
- only for legibility.</para>
-
- <programlisting>
- login auth optional /usr/lib/security/libpam_unix.1
- login auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root setenv_password_expires
- ftp auth optional /usr/lib/security/libpam_unix.1
- ftp auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root
- remsh auth optional /usr/lib/security/libpam_unix.1
- remsh auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root
- telnet auth optional /usr/lib/security/libpam_unix.1
- telnet auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root setenv_password_expires
-</programlisting>
- </listitem>
-
- <listitem>
- <para>If you use the Common Desktop Environment (CDE) on the machine and want users to obtain an AFS token as they log
- in, also add or edit the following four entries in the <computeroutput>Authentication management</computeroutput>
- section. Note that the AFS-related entries appear on two lines here only for legibility. <programlisting>
- dtlogin auth optional /usr/lib/security/libpam_unix.1
- dtlogin auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root
- dtaction auth optional /usr/lib/security/libpam_unix.1
- dtaction auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root
-</programlisting></para>
- </listitem>
-
+ <para>In modern AFS installations, you should be using Kerberos v5
+ for user login, and obtaining AFS tokens subsequent to this authentication
+ step. OpenAFS does not currently distribute a PAM module allowing AFS
+ tokens to be automatically gained at login. Whilst there are a number of
+ third party modules providing this functionality, it is not know if these
+ have been tested with HP/UX.</para>
+
+ <para>Following login, users can
+ obtain tokens by running the <emphasis role="bold">aklog</emphasis>
+ command</para>
+
+ <para>If you are at a site which still requires
+ <emphasis role="bold">kaserver</emphasis> or external Kerberos v4 based
+ authentication, please consult
+ <link linkend="KAS014">Enabling kaserver based AFS Login on HP-UX systems</link>
+ for further installation instructions.
+ <orderedlist>
<listitem>
<para>Proceed to <link linkend="HDRWQ145">Loading and Creating Client Files</link>.</para>
</listitem>
- </orderedlist></para>
+ </orderedlist>
+ </para>
<indexterm>
<primary>incorporating AFS kernel extensions</primary>
<para>In preparation for either dynamic loading or kernel building, perform the following procedures: <orderedlist>
<listitem>
- <para>Mount the AFS CD-ROM for IRIX on the <emphasis role="bold">/cdrom</emphasis> directory. For instructions on mounting
- CD-ROMs (either locally or remotely via NFS), see your IRIX documentation. Then change directory as indicated.
- <programlisting>
- # <emphasis role="bold">cd /cdrom/sgi_65/root.client</emphasis>
+ <para>Unpack the OpenAFS IRIX distribution tarball. The examples
+ below assume that you have unpacked the files into the
+ <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you
+ pick a different location, substitue this in all of the following
+ examples. Once you have unpacked the distribution, change directory
+ as indicated.
+<programlisting>
+ # <emphasis role="bold">cd /tmp/afsdist/sgi_65/root.client</emphasis>
</programlisting></para>
</listitem>
-
<listitem>
<para>Copy the AFS initialization script to the local directory for initialization files (by convention, <emphasis
role="bold">/etc/init.d</emphasis> on IRIX machines). Note the removal of the <emphasis role="bold">.rc</emphasis>
<para>The <emphasis role="bold">ml</emphasis> program is the dynamic kernel loader provided by SGI for IRIX systems. If you
use it rather than building AFS modifications into a static kernel, then for AFS to function correctly the <emphasis
role="bold">ml</emphasis> program must run each time the machine reboots. Therefore, the AFS initialization script (included
- on the AFS CD-ROM) invokes it automatically when the <emphasis role="bold">afsml</emphasis> configuration variable is
+ in the OpenAFS Binary Distribution) invokes it automatically when the <emphasis role="bold">afsml</emphasis> configuration variable is
activated. In this section you activate the variable and run the script.</para>
<para>In a later section you verify that the script correctly initializes the Cache Manager, then create the links that
<sect2 id="HDRWQ142">
<title>Enabling AFS Login on IRIX Systems</title>
- <para>The standard IRIX command-line <emphasis role="bold">login</emphasis> program and the graphical <emphasis
- role="bold">xdm</emphasis> login program both automatically grant an AFS token when AFS is incorporated into the machine's
- kernel. However, some IRIX distributions use another login utility by default, and it does not necessarily incorporate the
- required AFS modifications. If that is the case, you must disable the default utility if you want AFS users to obtain AFS
- tokens at login. For further discussion, see the <emphasis>OpenAFS Release Notes</emphasis>.</para>
-
- <para>If you configure the machine to use an AFS-modified login utility, then the <emphasis
- role="bold">afsauthlib.so</emphasis> and <emphasis role="bold">afskauthlib.so</emphasis> files (included in the AFS
- distribution) must reside in the <emphasis role="bold">/usr/vice/etc</emphasis> directory. Issue the <emphasis
- role="bold">ls</emphasis> command to verify.</para>
-
- <programlisting>
- # <emphasis role="bold">ls /usr/vice/etc</emphasis>
-</programlisting>
-
- <para>If the files do not exist, mount the AFS CD-ROM for IRIX (if it is not already), change directory as indicated, and copy
- them.</para>
-
- <programlisting>
- # <emphasis role="bold">cd /cdrom/sgi_65/root.client/usr/vice/etc</emphasis>
- # <emphasis role="bold">cp -p *authlib* /usr/vice/etc</emphasis>
-</programlisting>
-
- <para>After taking any necessary action, proceed to <link linkend="HDRWQ145">Loading and Creating Client Files</link>.
+ <para>Whilst the standard IRIX command-line
+ <emphasis role="bold">login</emphasis> program and the
+ graphical <emphasis role="bold">xdm</emphasis> login program both have
+ the ability to grant AFS tokens, this ability relies upon the deprecated
+ kaserver authentication system. As this system is not recommended for
+ new installations, this is not documented here.</para>
+
+ <para>Users who have been successfully authenticated via Kerberos 5
+ authentication may obtain AFS tokens following login by running the
+ <emphasis role="bold">aklog</emphasis> command.</para>
+
+ <para>If you are at a site which still requires
+ <emphasis role="bold">kaserver</emphasis> or external Kerberos v4 based
+ authentication, please consult
+ <link linkend="KAS014">Enabling kaserver based AFS Login on Linux Systems</link>
+ for further installation instructions.</para>
+
+ <para>Proceed to <link linkend="HDRWQ145">Loading and Creating Client Files</link>.
<indexterm>
<primary>incorporating AFS kernel extensions</primary>
<sect2 id="Header_133">
<title>Loading AFS into the Linux Kernel</title>
- <para>The <emphasis role="bold">insmod</emphasis> program is the dynamic kernel loader for Linux. Linux does not support
+ <para>The <emphasis role="bold">modprobe</emphasis> program is the dynamic kernel loader for Linux. Linux does not support
incorporation of AFS modifications during a kernel build.</para>
- <para>For AFS to function correctly, the <emphasis role="bold">insmod</emphasis> program must run each time the machine
- reboots, so the AFS initialization script (included on the AFS CD-ROM) invokes it automatically. The script also includes
+ <para>For AFS to function correctly, the <emphasis role="bold">modprobe</emphasis> program must run each time the machine
+ reboots, so your distributions's AFS initialization script invokes it automatically. The script also includes
commands that select the appropriate AFS library file automatically. In this section you run the script.</para>
<para>In a later section you also verify that the script correctly initializes the Cache Manager, then activate a
- configuration variable, which results in the script being incorporated into the Linux startup and shutdown sequence.
- <orderedlist>
- <listitem>
- <para>Mount the AFS CD-ROM for Linux on the local <emphasis role="bold">/cdrom</emphasis> directory. For instructions on
- mounting CD-ROMs (either locally or remotely via NFS), see your Linux documentation. Then change directory as indicated.
- <programlisting>
- # <emphasis role="bold">cd /cdrom/i386_linux22/root.client/usr/vice/etc</emphasis>
+ configuration variable, which results in the script being incorporated into the Linux startup and shutdown sequence.</para>
+
+ <para>The procedure for starting up OpenAFS depends upon your distribution</para>
+ <sect3>
+ <title>Fedora and RedHat Enterprise Linux</title>
+ <para>OpenAFS ships RPMS for all current Fedora and RHEL releases.
+ <orderedlist>
+ <listitem>
+ <para>Download and install the RPM set for your operating system.
+ RPMs are available from the OpenAFS web site. You will need the
+ <emphasis role="bold">openafs</emphasis> and
+ <emphasis role="bold">openfs-client</emphasis> packages, along
+ with an <emphasis role="bold">openafs-kernel</emphasis> package
+ matching your current, running ,kernel.</para>
+
+ <para>You can find the version of your current kernel by running
+<programlisting>
+ # uname -r
+<replaceable>2.6.20-1.2933.fc6</replaceable>
+</programlisting></para>
+
+ <para>Once downloaded, the packages may be installed with the
+ <emphasis role="bold">rpm</emphasis> command
+<programlisting>
+ # rpm -U openafs-* openafs-client-* openafs-server-* openafs-kernel-*
+</programlisting></para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </sect3>
+ <sect3>
+ <title>Systems packaged as tar files</title>
+ <para>If you are running a system where the OpenAFS Binary Distribution
+ is provided as a tar file, or where you have built the system from
+ source yourself, you need to install the relevant components by hand
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>Unpack the distribution tarball. The examples below assume
+ that you have unpacked the files into the
+ <emphasis role="bold">/tmp/afsdist</emphasis>directory. If you
+ pick a different location, substitute this in all of the following
+ examples. Once you have unpacked the distribution,
+ change directory as indicated.
+<programlisting>
+ # <emphasis role="bold">cd /tmp/afsdist/linux/root.client/usr/vice/etc</emphasis>
</programlisting></para>
</listitem>
</programlisting></para>
</listitem>
+<!--
<listitem>
<para>Run the AFS initialization script to load AFS extensions into the kernel. You can ignore any error messages about
the inability to start the BOS Server or the Cache Manager or AFS client. <programlisting>
# <emphasis role="bold">/etc/rc.d/init.d/afs start</emphasis>
</programlisting></para>
</listitem>
- </orderedlist></para>
+-->
+ </orderedlist>
+ </sect3>
</sect2>
<sect2 id="Header_134">
integrates all authentication mechanisms on the machine, including login, to provide the security infrastructure for
authenticated access to and from the machine.</para>
- <para>Explaining PAM is beyond the scope of this document. It is assumed that you understand the syntax and meanings of
- settings in the PAM configuration file (for example, how the <computeroutput>other</computeroutput> entry works, the effect of
- marking an entry as <computeroutput>required</computeroutput>, <computeroutput>optional</computeroutput>, or
- <computeroutput>sufficient</computeroutput>, and so on).</para>
-
- <para>The following instructions explain how to alter the entries in the PAM configuration file for each service for which you
- wish to use AFS authentication. Other configurations possibly also work, but the instructions specify the recommended and
- tested configuration.</para>
-
- <para>The recommended AFS-related entries in the PAM configuration file make use of one or more of the following three
- attributes. <variablelist>
- <title>Authentication Management</title>
-
- <varlistentry>
- <term><emphasis role="bold"><computeroutput>try_first_pass</computeroutput></emphasis></term>
-
- <listitem>
- <para>This is a standard PAM attribute that can be included on entries after the first one for a service; it directs
- the module to use the password that was provided to the first module. For the AFS module, it means that AFS
- authentication succeeds if the password provided to the module listed first is the user's correct AFS password. For
- further discussion of this attribute and its alternatives, see the operating system's PAM documentation.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="bold"><computeroutput>ignore_root</computeroutput></emphasis></term>
-
- <listitem>
- <para>This attribute, specific to the AFS PAM module, directs it to ignore not only the local superuser <emphasis
- role="bold">root</emphasis>, but also any user with UID 0 (zero).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="bold"><computeroutput>ignore_uid </computeroutput><emphasis>uid</emphasis></emphasis></term>
-
- <listitem>
- <para>This option is an extension of the "ignore_root" switch. The additional parameter is a limit. Users with a uid
- up to the given parameter are ignored by <emphasis>pam_afs.so</emphasis>. Thus, a system administrator still has the
- opportunity to add local user accounts to his system by choosing between "low" and "high" user ids. An example
- /etc/passwd file for "ignore_uid 100" may have entries like these: <programlisting>
- .
- .
-afsuserone:x:99:100::/afs/afscell/u/afsuserone:/bin/bash
-afsusertwo:x:100:100::/afs/afscell/u/afsusertwo:/bin/bash
-localuserone:x:101:100::/home/localuserone:/bin/bash
-localusertwo:x:102:100::/home/localusertwo:/bin/bash
- .
- .
-</programlisting> AFS accounts should be locked in the file /etc/shadow like this: <programlisting>
- .
- .
-afsuserone:!!:11500:0:99999:7:::
-afsusertwo:!!:11500:0:99999:7:::
-localuserone:<thelocaluserone'skey>:11500:0:99999:7:::
-localusertwo:<thelocalusertwo'skey>:11500:0:99999:7:::
- .
- .
-</programlisting> There is no need to store a local key in this file since the AFS password is sent and verfied at the AFS cell
- server!</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="bold"><computeroutput>setenv_password_expires</computeroutput></emphasis></term>
-
- <listitem>
- <para>This attribute, specific to the AFS PAM module, sets the environment variable PASSWORD_EXPIRES to the expiration
- date of the user's AFS password, which is recorded in the Authentication Database.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="bold"><computeroutput>set_token</computeroutput></emphasis></term>
-
- <listitem>
- <para>Some applications don't call <emphasis>pam_setcred()</emphasis> in order to retrieve the appropriate credentials
- (here the AFS token) for their session. This switch sets the credentials already in
- <emphasis>pam_sm_authenticate()</emphasis> obsoleting a call to <emphasis>pam_setcred()</emphasis>. <emphasis
- role="bold">Caution: Don't use this switch for applications which do call
- <emphasis>pam_setcred()</emphasis>!</emphasis> One example for an application not calling
- <emphasis>pam_setcred()</emphasis> are older versions of the samba server. Nevertheless, using applications with
- working pam session management is recommended as this setup conforms better with the PAM definitions.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="bold"><computeroutput>refresh_token</computeroutput></emphasis></term>
-
- <listitem>
- <para>This options is identical to "set_token" except that no new PAG is generated. This is necessary to handle
- processes like xlock or xscreensaver. It is not enough to give the screen and the keyboard free for the user who
- reactivated his screen typing in the correct AFS password, but one may also need fresh tokens with full livetime in
- order to work on, and the new token must be refreshed in the already existing PAG for the processes that have been
- started. This is achieved using this option.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="bold"><computeroutput>use_klog</computeroutput></emphasis></term>
-
- <listitem>
- <para>Activating this switch the authentication is done by calling the external program "klog". One program requiring
- this is for example <emphasis>kdm</emphasis> of KDE 2.x.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="bold"><computeroutput>dont_fork</computeroutput></emphasis></term>
-
- <listitem>
- <para>Usually, the password verification and the establishment of the token is performed in a sub process. Using this
- option pam_afs does not fork and performs all actions in a single process. <emphasis role="bold">Only use this options
- in case you notice serious problems caused by the sub process.</emphasis> This option has been developed in respect to
- the "mod_auth_pam"-project (see also <ulink url="http://pam.sourceforge.net/mod_auth_pam/">mod_auth_pam</ulink>). The
- mod_auth_pam module enables PAM authentication for the apache http server package.</para>
- </listitem>
- </varlistentry>
- </variablelist> <variablelist>
- <title>Session Management</title>
-
- <varlistentry>
- <term><emphasis role="bold"><computeroutput>no_unlog</computeroutput></emphasis></term>
-
- <listitem>
- <para>Normally the tokens are deleted (in memory) after the session ends. Using this options the tokens are left
- untouched. <emphasis role="bold">This behaviour has been the default in pam_afs until openafs-1.1.1!</emphasis></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="bold"><computeroutput>remainlifetime</computeroutput> <emphasis>sec</emphasis></emphasis></term>
-
- <listitem>
- <para>The tokens are kept active for <emphasis>sec</emphasis> seconds before they are deleted. X display managers i.e.
- are used to inform the applications started in the X session before the logout and then end themselves. If the token
- was deleted immediately the applications would have no chance to write back their settings to i.e. the user's AFS home
- space. This option may help to avoid the problem.</para>
- </listitem>
- </varlistentry>
- </variablelist></para>
-
- <para>Perform the following steps to enable AFS login. <orderedlist>
- <listitem>
- <para>Mount the AFS CD-ROM for Linux on the <emphasis role="bold">/cdrom</emphasis> directory, if it is not already.
- Then change to the directory for PAM modules, which depends on which Linux distribution you are using.</para>
-
- <para>If you are using a Linux distribution from Red Hat Software:</para>
-
- <programlisting>
- # <emphasis role="bold">cd /lib/security</emphasis>
-</programlisting>
-
- <para>If you are using another Linux distribution:</para>
-
- <programlisting>
- # <emphasis role="bold">cd /usr/lib/security</emphasis>
-</programlisting>
- </listitem>
-
- <listitem>
- <para>Copy the appropriate AFS authentication library file to the directory to which you changed in the previous step.
- Create a symbolic link whose name does not mention the version. Omitting the version eliminates the need to edit the PAM
- configuration file if you later update the library file.</para>
-
- <para>If you use the AFS Authentication Server (<emphasis role="bold">kaserver</emphasis> process):</para>
-
- <programlisting>
- # <emphasis role="bold">cp /cdrom/i386_linux22/lib/pam_afs.so.1 .</emphasis>
- # <emphasis role="bold">ln -s pam_afs.so.1 pam_afs.so</emphasis>
-</programlisting>
-
- <para>If you use a Kerberos implementation of AFS authentication:</para>
-
- <programlisting>
- # <emphasis role="bold">cp /cdrom/i386_linux22/lib/pam_afs.krb.so.1 .</emphasis>
- # <emphasis role="bold">ln -s pam_afs.krb.so.1 pam_afs.so</emphasis>
-</programlisting>
- </listitem>
-
- <listitem>
- <para>For each service with which you want to use AFS authentication, insert an entry for the AFS PAM module into the
- <computeroutput>auth</computeroutput> section of the service's PAM configuration file. (Linux uses a separate
- configuration file for each service, unlike some other operating systems which list all services in a single file.) Mark
- the entry as <computeroutput>sufficient</computeroutput> in the second field.</para>
-
- <para>Place the AFS entry below any entries that impose conditions under which you want the service to fail for a user
- who does not meet the entry's requirements. Mark these entries <computeroutput>required</computeroutput>. Place the AFS
- entry above any entries that need to execute only if AFS authentication fails.</para>
+ <para>At this time, we recommend that new sites requiring AFS credentials
+ to be gained as part of PAM authentication use Russ Alberry's
+ pam_afs_session, rather than utilising the bundled pam_afs2 module.
+ A typical PAM stack should authenticate the user using an external
+ Kerberos V service, and then use the AFS PAM module to obtain AFS
+ credentials in the <computeroutput>session</computeroutput> section</para>
- <para>Insert the following AFS entry if using the Red Hat distribution:</para>
-
- <programlisting>
- auth sufficient /lib/security/pam_afs.so try_first_pass ignore_root
-</programlisting>
-
- <para>Insert the following AFS entry if using another distribution:</para>
-
- <programlisting>
- auth sufficient /usr/lib/security/pam_afs.so try_first_pass ignore_root
-</programlisting>
-
- <para>Check the PAM config files also for "session" entries. If there are lines beginning with "session" then please
- insert this line too:</para>
-
- <programlisting>
- session optional /lib/security/pam_afs.so
-</programlisting>
-
- <para>or</para>
-
- <programlisting>
- session optional /usr/lib/security/pam_afs.so
-</programlisting>
-
- <para>This guarantees that the user's tokens are deleted from memory after his session ends so that no other user
- coincidently gets those tokens without authorization! The following examples illustrate the recommended configuration of
- the configuration file for several services: <variablelist>
- <title>Authentication Management</title>
-
- <varlistentry>
- <term>(<emphasis role="bold">/etc/pam.d/login</emphasis>)</term>
-
- <listitem>
- <para><programlisting>
- #%PAM-1.0
- auth required /lib/security/pam_securetty.so
- auth required /lib/security/pam_nologin.so
- auth sufficient /lib/security/pam_afs.so try_first_pass ignore_root
- # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- #This enables AFS authentication for every user but root
- auth required /lib/security/pam_pwdb.so shadow nullok
- account required /lib/security/pam_pwdb.so
- password required /lib/security/pam_cracklib.so
- password required /lib/security/pam_pwdb.so shadow nullok use_authtok
- session optional /lib/security/pam_afs.so
- #Make sure tokens are deleted after the user logs out
- session required /lib/security/pam_pwdb.so
-</programlisting></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>(<emphasis role="bold">/etc/pam.d/samba</emphasis>)</term>
-
- <listitem>
- <para><programlisting>
- auth required /lib/security/pam_afs.so ignore_uid 100 set_token
- # ^^^^^^^^^^^^^^^^^^^^^^^^
- #Here, users with uid>100 are considered to belong to the AFS and users
- #with uid<=100 are ignored by pam_afs. The token is retrieved already in
- #pam_sm_authenticate() (this is an example pam config for a samba version
- #that does not call pam_setcred(), it also does no sense to include session
- #entries here since they would be ignored by this version of samba ).
- account required /lib/security/pam_pwdb.so
-</programlisting></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>(<emphasis role="bold">/etc/pam.d/xscreensaver</emphasis>)</term>
-
- <listitem>
- <para><programlisting>
- auth sufficient /lib/security/pam_afs.so ignore_uid 100 refresh_token
- # ^^^^^^^^^^^^^
- #Avoid generating a new PAG for the new tokens, use the already existing PAG and
- #establish a fresh token in it.
- auth required /lib/security/pam_pwdb.so try_first_pass
-</programlisting></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>(<emphasis role="bold">/etc/pam.d/httpd</emphasis>)</term>
-
- <listitem>
- <para><programlisting>
- auth required /lib/security/pam_afs.so ignore_uid 100 dont_fork
- # ^^^^^^^^^
- #Don't fork for the verification of the password.
-</programlisting></para>
- </listitem>
- </varlistentry>
- </variablelist> <variablelist>
- <title>Session Management</title>
-
- <varlistentry>
- <term>(<emphasis role="bold">/etc/pam.d/su</emphasis>)</term>
-
- <listitem>
- <para><programlisting>
- auth sufficient /lib/security/pam_afs.so ignore_uid 100
- auth required /lib/security/pam_pwdb.so try_first_pass
- account required /lib/security/pam_pwdb.so
- password required /lib/security/pam_cracklib.so
- password required /lib/security/pam_pwdb.so use_authtok
- session required /lib/security/pam_pwdb.so
- session optional /lib/security/pam_afs.so no_unlog
- # ^^^^^^^^
- #Don't delete the token in this case, since the user may still
- #need it (for example if somebody logs in and changes to root
- #afterwards he may still want to access his home space in AFS).
- session required /lib/security/pam_login_access.so
- session optional /lib/security/pam_xauth.so
-</programlisting></para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>(<emphasis role="bold">/etc/pam.d/xdm</emphasis>)</term>
-
- <listitem>
- <para><programlisting>
- auth required /lib/security/pam_nologin.so
- auth required /lib/security/pam_login_access.so
- auth sufficient /lib/security/pam_afs.so ignore_uid 100 use_klog
- auth required /lib/security/pam_pwdb.so try_first_pass
- account required /lib/security/pam_pwdb.so
- password required /lib/security/pam_cracklib.so
- password required /lib/security/pam_pwdb.so shadow nullok use_authtok
- session optional /lib/security/pam_afs.so remainlifetime 10
- # ^^^^^^^^^^^^^^^^^
- #Wait 10 seconds before deleting the AFS tokens in order to give
- #the programs of the X session some time to save their settings
- #to AFS.
- session required /lib/security/pam_pwdb.so
-</programlisting></para>
- </listitem>
- </varlistentry>
- </variablelist></para>
- </listitem>
-
- <listitem>
- <para>Proceed to <link linkend="HDRWQ145">Loading and Creating Client Files</link>.</para>
- </listitem>
- </orderedlist></para>
+ <para>If you are at a site which still requires
+ <emphasis role="bold">kaserver</emphasis> or external Kerberos v4 based
+ authentication, please consult
+ <link linkend="KAS015">Enabling kaserver based AFS Login on Linux Systems</link>
+ for further installation instructions.</para>
+
+ <para>Proceed to
+ <link linkend="HDRWQ145">Loading and Creating Client Files</link>.</para>
<indexterm>
<primary>incorporating AFS kernel extensions</primary>
<para>In a later section you verify that the script correctly initializes the Cache Manager, then create the links that
incorporate AFS into the Solaris startup and shutdown sequence. <orderedlist>
<listitem>
- <para>Mount the AFS CD-ROM for Solaris on the <emphasis role="bold">/cdrom</emphasis> directory. For instructions on
- mounting CD-ROMs (either locally or remotely via NFS), see your Solaris documentation. Then change directory as
- indicated. <programlisting>
- # <emphasis role="bold">cd /cdrom/sun4x_56/root.client/usr/vice/etc</emphasis>
+ <para>Unpack the OpenAFS Solaris distribution tarball. The examples
+ below assume that you have unpacked the files into the
+ <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you
+ pick a diferent location, substitute this in all of the following
+ exmaples. Once you have unpacked the distribution, change directory
+ as indicated.
+<programlisting>
+ # <emphasis role="bold">cd /tmp/afsdist/sun4x_56/root.client/usr/vice/etc</emphasis>
</programlisting></para>
- </listitem>
+ </listitem>
<listitem>
<para>Copy the AFS initialization script to the local directory for initialization files (by convention, <emphasis
integrates all authentication mechanisms on the machine, including login, to provide the security infrastructure for
authenticated access to and from the machine.</para>
- <para>Explaining PAM is beyond the scope of this document. It is assumed that you understand the syntax and meanings of
- settings in the PAM configuration file (for example, how the <computeroutput>other</computeroutput> entry works, the effect of
- marking an entry as <computeroutput>required</computeroutput>, <computeroutput>optional</computeroutput>, or
- <computeroutput>sufficient</computeroutput>, and so on).</para>
-
- <para>The following instructions explain how to alter the entries in the PAM configuration file for each service for which you
- wish to use AFS authentication. Other configurations possibly also work, but the instructions specify the recommended and
- tested configuration.</para>
-
- <note>
- <para>The instructions specify that you mark each entry as <computeroutput>optional</computeroutput>. However, marking some
- modules as optional can mean that they grant access to the corresponding service even when the user does not meet all of the
- module's requirements. In some operating system revisions, for example, if you mark as optional the module that controls
- login via a dial-up connection, it allows users to login without providing a password. See the <emphasis>OpenAFS Release
- Notes</emphasis> for a discussion of any limitations that apply to this operating system.</para>
-
- <para>Also, with some operating system versions you must install patches for PAM to interact correctly with certain
- authentication programs. For details, see the <emphasis>OpenAFS Release Notes</emphasis>.</para>
- </note>
-
- <para>The recommended AFS-related entries in the PAM configuration file make use of one or more of the following three
- attributes. <variablelist>
- <title>Authentication Management</title>
-
- <varlistentry>
- <term><emphasis role="bold"><computeroutput>try_first_pass</computeroutput></emphasis></term>
-
- <listitem>
- <para>This is a standard PAM attribute that can be included on entries after the first one for a service; it directs
- the module to use the password that was provided to the first module. For the AFS module, it means that AFS
- authentication succeeds if the password provided to the module listed first is the user's correct AFS password. For
- further discussion of this attribute and its alternatives, see the operating system's PAM documentation.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="bold"><computeroutput>ignore_root</computeroutput></emphasis></term>
-
- <listitem>
- <para>This attribute, specific to the AFS PAM module, directs it to ignore not only the local superuser <emphasis
- role="bold">root</emphasis>, but also any user with UID 0 (zero).</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis role="bold"><computeroutput>setenv_password_expires</computeroutput></emphasis></term>
-
- <listitem>
- <para>This attribute, specific to the AFS PAM module, sets the environment variable PASSWORD_EXPIRES to the expiration
- date of the user's AFS password, which is recorded in the Authentication Database.</para>
- </listitem>
- </varlistentry>
- </variablelist></para>
-
- <para>Perform the following steps to enable AFS login. <orderedlist>
- <listitem>
- <para>Mount the AFS CD-ROM for Solaris on the <emphasis role="bold">/cdrom</emphasis> directory, if it is not already.
- Then change directory as indicated. <programlisting>
- # <emphasis role="bold">cd /usr/lib/security</emphasis>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Copy the AFS authentication library file to the <emphasis role="bold">/usr/lib/security</emphasis> directory. Then
- create a symbolic link to it whose name does not mention the version. Omitting the version eliminates the need to edit
- the PAM configuration file if you later update the library file.</para>
-
- <para>If you use the AFS Authentication Server (<emphasis role="bold">kaserver</emphasis> process):</para>
-
- <programlisting>
- # <emphasis role="bold">cp /cdrom/sun4x_56/lib/pam_afs.so.1 .</emphasis>
- # <emphasis role="bold">ln -s pam_afs.so.1 pam_afs.so</emphasis>
-</programlisting>
-
- <para>If you use a Kerberos implementation of AFS authentication:</para>
-
- <programlisting>
- # <emphasis role="bold">cp /cdrom/sun4x_56/lib/pam_afs.krb.so.1 .</emphasis>
- # <emphasis role="bold">ln -s pam_afs.krb.so.1 pam_afs.so</emphasis>
-</programlisting>
- </listitem>
-
- <listitem>
- <para>Edit the <computeroutput>Authentication management</computeroutput> section of the Solaris PAM configuration file,
- <emphasis role="bold">/etc/pam.conf</emphasis> by convention. The entries in this section have the value
- <computeroutput>auth</computeroutput> in their second field.</para>
-
- <para>First edit the standard entries, which refer to the Solaris PAM module (usually, the file <emphasis
- role="bold">/usr/lib/security/pam_unix.so.1</emphasis>) in their fourth field. For each service for which you want to
- use AFS authentication, edit the third field of its entry to read <computeroutput>optional</computeroutput>. The
- <emphasis role="bold">pam.conf</emphasis> file in the Solaris distribution usually includes standard entries for the
- <emphasis role="bold">login</emphasis>, <emphasis role="bold">rlogin</emphasis>, and <emphasis
- role="bold">rsh</emphasis> services, for instance.</para>
-
- <para>If there are services for which you want to use AFS authentication, but for which the <emphasis
- role="bold">pam.conf</emphasis> file does not already include a standard entry, you must create that entry and place the
- value <computeroutput>optional</computeroutput> in its third field. For instance, the Solaris <emphasis
- role="bold">pam.conf</emphasis> file does not usually include standard entries for the <emphasis
- role="bold">ftp</emphasis> or <emphasis role="bold">telnet</emphasis> services.</para>
-
- <para>Then create an AFS-related entry for each service, placing it immediately below the standard entry. The following
- example shows what the <computeroutput>Authentication Management</computeroutput> section looks like after you have you
- edited or created entries for the services mentioned previously. Note that the example AFS entries appear on two lines
- only for legibility.</para>
-
- <programlisting>
- login auth optional /usr/lib/security/pam_unix.so.1
- login auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root setenv_password_expires
- rlogin auth optional /usr/lib/security/pam_unix.so.1
- rlogin auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root setenv_password_expires
- rsh auth optional /usr/lib/security/pam_unix.so.1
- rsh auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root
- ftp auth optional /usr/lib/security/pam_unix.so.1
- ftp auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root
- telnet auth optional /usr/lib/security/pam_unix.so.1
- telnet auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root setenv_password_expires
-</programlisting>
- </listitem>
-
- <listitem>
- <para>If you use the Common Desktop Environment (CDE) on the machine and want users to obtain an AFS token as they log
- in, also add or edit the following four entries in the <computeroutput>Authentication management</computeroutput>
- section. Note that the AFS-related entries appear on two lines here only for legibility. <programlisting>
- dtlogin auth optional /usr/lib/security/pam_unix.so.1
- dtlogin auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root
- dtsession auth optional /usr/lib/security/pam_unix.so.1
- dtsession auth optional /usr/lib/security/pam_afs.so \
- try_first_pass ignore_root
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Some Solaris distributions include a script that locates and removes unneeded files from various file systems. Its
- conventional location is <emphasis role="bold">/usr/lib/fs/nfs/nfsfind</emphasis>. The script generally uses an argument
- to the <emphasis role="bold">find</emphasis> command to define which file systems to search. In this step you modify the
- command to exclude the <emphasis role="bold">/afs</emphasis> directory. Otherwise, the command traverses the AFS
+ <para>In modern AFS installations, you should be using Kerberos v5
+ for user login, and obtaining AFS tokens subsequent to this authentication
+ step. OpenAFS does not currently distribute a PAM module allowing AFS
+ tokens to be automatically gained at login. Whilst there are a number of
+ third party modules providing this functionality, it is not know if these
+ have been tested with Solaris.</para>
+
+ <para>If you are at a site which still requires
+ <emphasis role="bold">kaserver</emphasis> or external Kerberos v4 based
+ authentication, please consult
+ <link linkend="KAS016">Enabling kaserver based AFS Login on Solaris Systems</link>
+ for further installation instructions.</para>
+ </sect2>
+ <sect2 id="Header_137a">
+ <title>Editing the File Systems Clean-up Script on Solaris Systems</title>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>Some Solaris distributions include a script that locates
+ and removes unneeded files from various file systems. Its
+ conventional location is
+ <emphasis role="bold">/usr/lib/fs/nfs/nfsfind</emphasis>. The
+ script generally uses an argument to the
+ <emphasis role="bold">find</emphasis> command to define which file
+ systems to search. In this step you modify the
+ command to exclude the <emphasis role="bold">/afs</emphasis>
+ directory. Otherwise, the command traverses the AFS
filespace of every cell that is accessible from the machine, which can take many hours. The following alterations are
possibilities, but you must verify that they are appropriate for your cell.</para>
</orderedlist></para>
<indexterm>
- <primary>CD-ROM</primary>
+ <primary>Binary Distribution</primary>
<secondary>copying client files from</secondary>
<sect1 id="HDRWQ145">
<title>Loading and Creating Client Files</title>
- <para>Now copy files from the AFS CD-ROM to the <emphasis role="bold">/usr/vice/etc</emphasis> directory. On some platforms that
- use a dynamic loader program to incorporate AFS modifications into the kernel, you have already copied over some the files.
+ <para>If you are using a non-packaged distribution (that is, one provided as
+ a tarball) you should now copy files from the istribution to the
+ <emphasis role="bold">/usr/vice/etc</emphasis> directory. On some platforms
+ that use a dynamic loader program to incorporate AFS modifications into the
+ kernel, you have already copied over some the files.
Copying them again does no harm.</para>
<para>Every AFS client machine has a copy of the <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> file on its local disk
</listitem>
<listitem>
- <para>The cell in which users authenticate by default when they issue the <emphasis role="bold">klog</emphasis>
+ <para>The cell in which users authenticate by default when they issue the <emphasis role="bold">aklog</emphasis>
command</para>
</listitem>
Administration Guide</emphasis> about administering client machines for instructions on updating this file, with or without
rebooting. <orderedlist>
<listitem>
- <para>On the local <emphasis role="bold">/cdrom</emphasis> directory, mount the AFS CD-ROM for this machine's system type,
- if it is not already. For instructions on mounting CD-ROMs (either locally or remotely via NFS), consult the operating
- system documentation.</para>
+ <para>If you have not already done so, unpack the distribution
+ tarball for this machine's system type into a suitable location on
+ the filesystem, such as <emphasis role="bold">/tmp/afsdist</emphasis>.
+ If you use a different location, substitue that in the examples that
+ follow.</para>
</listitem>
<listitem>
</listitem>
<listitem>
- <para>Create the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file. Use a network file transfer program such
- as <emphasis role="bold">ftp</emphasis> or NFS to copy it from one of the following sources, which are listed in
- decreasing order of preference: <itemizedlist>
+ <para>Create the
+ <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file. Use a
+ network file transfer program such as
+ <emphasis role="bold">sftp</emphasis> or
+ <emphasis role="bold">scp</emphasis> to copy it from one of the
+ following sources, which are listed in decreasing order of
+ preference: <itemizedlist>
<listitem>
<para>Your cell's central <emphasis role="bold">CellServDB</emphasis> source file (the conventional location is
<emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
</listitem>
<listitem>
- <para>The global <emphasis role="bold">CellServDB</emphasis> file maintained by the AFS Product Support group</para>
+ <para>The global <emphasis role="bold">CellServDB</emphasis>
+ file maintained at grand.central.org</para>
</listitem>
<listitem>
</listitem>
<listitem>
- <para>The <emphasis role="bold">CellServDB.sample</emphasis> file included in the
- <replaceable>sysname</replaceable><emphasis role="bold">/root.client/usr/vice/etc</emphasis> directory of each AFS
- CD-ROM; add an entry for the local cell by following the instructions in <link linkend="HDRWQ66">Creating the Client
- CellServDB File</link></para>
+ <para>The <emphasis role="bold">CellServDB.sample</emphasis>
+ file included in the
+ <replaceable>sysname</replaceable><emphasis role="bold">/root.client/usr/vice/etc</emphasis>
+ directory of each OpenAFS distribution; add an entry for the
+ local cell by following the instructions in
+ <link linkend="HDRWQ66">Creating the Client CellServDB File</link>
+ </para>
</listitem>
</itemizedlist></para>
</listitem>
default values. For a discussion of all of the <emphasis role="bold">afsd</emphasis> command's arguments, see its reference page
in the <emphasis>OpenAFS Administration Reference</emphasis>.</para>
- <para>The <emphasis role="bold">afsd</emphasis> command line in the AFS initialization script on each system type includes an
- <computeroutput>OPTIONS</computeroutput> variable. You can use it to set nondefault values for the command's arguments, in one
+ <para>On platforms using the standard 'afs' initialisation script (this does
+ not apply to Fedora or RHEL based distributions), the
+ <emphasis role="bold">afsd</emphasis> command line in the AFS
+ initialization script on each system type includes an
+ <computeroutput>OPTIONS</computeroutput> variable. You can use it to set
+ nondefault values for the command's arguments, in one
of the following ways: <itemizedlist>
<listitem>
<para>You can create an <emphasis role="bold">afsd</emphasis> <emphasis>options file</emphasis> that sets values for
role="bold">afsd</emphasis> command line in the script, or set no arguments (and so accept default values for all Cache
Manager parameters).</para>
</listitem>
- </itemizedlist> <orderedlist>
+ </itemizedlist>
+
+ <note>
+ <para>If you are running on a Fedora or RHEL based system, the
+ openafs-client initialization script behaves differently from that
+ described above. It sources
+ <emphasis role="bold">/etc/sysconfig/openafs</emphasis>, in which the
+ AFSD_ARGS variable may be set to contain any, or all, of the afsd
+ options detailed above. Note that this script does not support setting
+ an <computeroutput>OPTIONS</computeroutput> variable, or the
+ <computeroutput>SMALL</computeroutput>,
+ <computeroutput>MEDIUM</computeroutput> and
+ <computeroutput>LARGE</computeroutput> methods of defining cache size.
+ </para>
+ </note>
+
+ <orderedlist>
<listitem>
<para>Create the local directory on which to mount the AFS filespace, by convention <emphasis role="bold">/afs</emphasis>.
If the directory already exists, verify that it is empty. <programlisting>
</listitem>
<listitem>
- <para>On Linux systems, copy the <emphasis role="bold">afsd</emphasis> options file from the <emphasis
+ <para>On non-package based Linux systems, copy the <emphasis role="bold">afsd</emphasis> options file from the <emphasis
role="bold">/usr/vice/etc</emphasis> directory to the <emphasis role="bold">/etc/sysconfig</emphasis> directory, removing
the <emphasis role="bold">.conf</emphasis> extension as you do so. <programlisting>
# <emphasis role="bold">cp /usr/vice/etc/afs.conf /etc/sysconfig/afs</emphasis>
</listitem>
<listitem>
+ <para>On Fedora and RHEL systems, <emphasis role="bold">/etc/sysconfig/openafs</emphasis></para>
+ </listitem>
+
+ <listitem>
<para>On Linux systems, <emphasis role="bold">/etc/sysconfig/afs</emphasis> (the <emphasis
role="bold">afsd</emphasis> options file)</para>
</listitem>
</indexterm>
</sect2>
+ <sect2>
+ <title>Running the Script on Fedora / RHEL Systems</title>
+
+ <orderedlist>
+ <listitem>
+ <para>Reboot the machine and log in again as the local superuser <emphasis role="bold">root</emphasis>. <programlisting>
+ # <emphasis role="bold">cd /</emphasis>
+ # <emphasis role="bold">shutdown -r now</emphasis>
+ login: <emphasis role="bold">root</emphasis>
+ Password: <replaceable>root_password</replaceable>
+</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>Run the AFS initialization script.
+<programlisting>
+ # <emphasis role="bold">/etc/rc.d/init.d/openafs-client start</emphasis>
+</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>Issue the <emphasis role="bold">chkconfig</emphasis> command to activate the <emphasis role="bold">openafs-client</emphasis>
+ configuration variable. Based on the instruction in the AFS initialization file that begins with the string
+ <computeroutput>#chkconfig</computeroutput>, the command automatically creates the symbolic links that incorporate the
+ script into the Linux startup and shutdown sequence. <programlisting>
+ # <emphasis role="bold">/sbin/chkconfig --add openafs-client</emphasis>
+</programlisting></para>
+ </listitem>
+ </orderedlist>
+ </sect2>
+
<sect2 id="HDRWQ155">
- <title>Running the Script on Linux Systems</title>
+ <title>Running the Script on other Linux Systems</title>
<orderedlist>
<listitem>
<para><emphasis role="bold">(Optional)</emphasis> There are now copies of the AFS initialization file in both the
<emphasis role="bold">/usr/vice/etc</emphasis> and <emphasis role="bold">/etc/init.d</emphasis> directories. If you want
to avoid potential confusion by guaranteeing that they are always the same, create a link between them. You can always
- retrieve the original script from the AFS CD-ROM if necessary. <programlisting>
+ retrieve the original script from the OpenAFS Binary Distribution if necessary. <programlisting>
# <emphasis role="bold">cd /usr/vice/etc</emphasis>
# <emphasis role="bold">rm afs.rc</emphasis>
# <emphasis role="bold">ln -s /etc/init.d/afs afs.rc</emphasis>
<sect1 id="HDRWQ157">
<title>Setting Up Volumes and Loading Binaries into AFS</title>
+ <note><para>If you are using an operating system which uses packaged
+ binaries, such as .rpms or .debs, you should allow these package management
+ systems to maintain your AFS binaries, rather than following the
+ instructions in this section.</para></note>
+
<para>In this section, you link <emphasis role="bold">/usr/afsws</emphasis> on the local disk to the directory in AFS that
houses AFS binaries for this system type. The conventional name for the AFS directory is <emphasis
role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
<para>If this client machine is a new system type, you must create and mount volumes for its binaries before you can link the
local <emphasis role="bold">/usr/afsws</emphasis> directory to an AFS directory.</para>
- <para>To create and mount the volumes, you use the <emphasis role="bold">klog</emphasis> command to authenticate as an
- administrator and then issue commands from the <emphasis role="bold">vos</emphasis> and <emphasis role="bold">fs</emphasis>
- command suites. However, the command binaries are not yet available on this machine (by convention, they are accessible via
- the <emphasis role="bold">/usr/afsws</emphasis> link that you are about to create). You have two choices: <itemizedlist>
+ <para>To create and mount the volumes, you use the
+ <emphasis role="bold">kinit</emphasis> command to authenticate as an
+ administrator, followed by the <emphasis role="bold">aklog</emphasis>
+ command to gain tokens, and then issue commands from the
+ <emphasis role="bold">vos</emphasis> and
+ <emphasis role="bold">fs</emphasis> command suites. However, the
+ command binaries are not yet available on this machine (by convention,
+ they are accessible via the <emphasis role="bold">/usr/afsws</emphasis>
+ link that you are about to create). You have two choices:
+ <itemizedlist>
<listitem>
<para>Perform all steps except the last one (Step <link linkend="LIWQ162">10</link>) on an existing AFS machine. On a
- file server machine, the <emphasis role="bold">klog</emphasis>, <emphasis role="bold">fs</emphasis> and <emphasis
+ file server machine, the <emphasis role="bold">aklog</emphasis>, <emphasis role="bold">fs</emphasis> and <emphasis
role="bold">vos</emphasis> binaries reside in the <emphasis role="bold">/usr/afs/bin</emphasis> directory. On client
- machines, the <emphasis role="bold">klog</emphasis> and <emphasis role="bold">fs</emphasis> binaries reside in the
+ machines, the <emphasis role="bold">aklog</emphasis> and <emphasis role="bold">fs</emphasis> binaries reside in the
<emphasis role="bold">/usr/afsws/bin</emphasis> directory and the <emphasis role="bold">vos</emphasis> binary in the
<emphasis role="bold">/usr/afsws/etc</emphasis> directory. Depending on how your PATH environment variable is set, you
possibly need to precede the command names with a pathname.</para>
<para>Perform the following steps to create a volume for housing AFS binaries. <orderedlist>
<listitem>
- <para>Working either on the local machine or another AFS machine, mount the AFS CD-ROM for the new system type on the
- <emphasis role="bold">/cdrom</emphasis> directory, if it is not already. For instructions on mounting CD-ROMs (either
- locally or remotely via NFS), consult the operating system documentation.</para>
+ <para>Working either on the local machine or another AFS machine,
+ extract the Open AFS distribtion tarball onto a directory on that
+ machine. The following instructions assume that you are using the
+ <emphasis role="bold">/tmp/afsdist</emphasis> directory.</para>
</listitem>
<listitem>
<para>If working on the local machine, copy the necessary binaries to a temporary location on the local disk. Substitute
a different directory name for <emphasis role="bold">/tmp</emphasis> if you wish. <programlisting>
- # <emphasis role="bold">cd /cdrom/</emphasis><replaceable>new_sysname</replaceable><emphasis role="bold">/root.server/usr/afs/bin</emphasis>
- # <emphasis role="bold">cp -p klog /tmp</emphasis>
+ # <emphasis role="bold">cd /tmp/afsdist/</emphasis><replaceable>new_sysname</replaceable><emphasis role="bold">/root.server/usr/afs/bin</emphasis>
+ # <emphasis role="bold">cp -p aklog /tmp</emphasis>
# <emphasis role="bold">cp -p fs /tmp</emphasis>
# <emphasis role="bold">cp -p vos /tmp</emphasis>
</programlisting></para>
</listitem>
<listitem>
- <para>Authenticate as the user <emphasis role="bold">admin</emphasis>. <programlisting>
- # <emphasis role="bold">klog admin</emphasis>
+ <para>Authenticate as the user <emphasis role="bold">admin</emphasis>.
+<programlisting>
+ # <emphasis role="bold">kinit admin</emphasis>
Password: <replaceable>admin_password</replaceable>
+ # <emphasis role="bold">aklog</emphasis>
</programlisting></para>
</listitem>
</listitem>
<listitem>
- <para><anchor id="LIWQ161" />Copy the contents of the indicated directories from the CD-ROM into the <emphasis
- role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
+ <para><anchor id="LIWQ161" />Copy the contents of the indicated
+ directories from the OpenAFS binary distribution into the
+ <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/usr/afsws</emphasis> directory.
<programlisting>
# <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis
</listitem>
<listitem>
- <para>Issue the <emphasis role="bold">fs setacl</emphasis> command to set the ACL on each directory appropriately. To
- comply with the terms of your AFS License agreement, you must prevent unauthorized users from accessing AFS software. To
- enable access for locally authenticated users only, set the ACL on the <emphasis role="bold">etc</emphasis>, <emphasis
- role="bold">include</emphasis>, and <emphasis role="bold">lib</emphasis> subdirectories to grant the <emphasis
- role="bold">l</emphasis> and <emphasis role="bold">r</emphasis> permissions to the <emphasis
- role="bold">system:authuser</emphasis> group rather than the <emphasis role="bold">system:anyuser</emphasis> group. The
- <emphasis role="bold">system:anyuser</emphasis> group must retain the <emphasis role="bold">l</emphasis> and <emphasis
- role="bold">r</emphasis> permissions on the <emphasis role="bold">bin</emphasis> subdirectory to enable unauthenticated
- users to access the <emphasis role="bold">klog</emphasis> binary. To ensure that unauthorized users are not accessing
- AFS software, check periodically that the ACLs on these directories are set properly. <programlisting>
+ <para>Issue the <emphasis role="bold">fs setacl</emphasis> command
+ to set the ACL on each directory appropriately. If you wish to
+ enable access to the software for locally authenticated users only,
+ set the ACL on the <emphasis role="bold">etc</emphasis>,
+ <emphasis role="bold">include</emphasis>, and
+ <emphasis role="bold">lib</emphasis> subdirectories to grant the
+ <emphasis role="bold">l</emphasis> and
+ <emphasis role="bold">r</emphasis> permissions to the
+ <emphasis role="bold">system:authuser</emphasis> group rather than
+ the <emphasis role="bold">system:anyuser</emphasis> group. The
+ <emphasis role="bold">system:anyuser</emphasis> group must retain
+ the <emphasis role="bold">l</emphasis> and
+ <emphasis role="bold">r</emphasis> permissions on the
+ <emphasis role="bold">bin</emphasis> subdirectory to enable
+ unauthenticated users to access the
+ <emphasis role="bold">aklog</emphasis> binary.
+<programlisting>
# <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis
role="bold">/usr/afsws</emphasis>
# <emphasis role="bold">fs setacl -dir etc include lib -acl system:authuser rl</emphasis> \
git://git.openafs.org / openafs.git / commitdiff