<chapter id="HDRWQ17">
<title>Installing the First AFS Machine</title>
+ <para>
<indexterm>
<primary>file server machine</primary>
<secondary>first AFS machine</secondary>
</indexterm>
- <para>This chapter describes how to install the first AFS machine in your cell, configuring it as both a file server machine and a
+ This chapter describes how to install the first AFS machine in your cell, configuring it as both a file server machine and a
client machine. After completing all procedures in this chapter, you can remove the client functionality if you wish, as described
in <link linkend="HDRWQ98">Removing Client Functionality</link>.</para>
</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
+ <para>You have NTP or a similar time service deployed to ensure
rough clock syncronistation between your clients and servers.</para>
</listitem>
</itemizedlist></para>
</listitem>
<listitem>
- <para>Start the server portion of the Update Server</para>
+ <para>Optionally, start the server portion of the Update Server</para>
</listitem>
</orderedlist></para>
<para>The <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> directories must reside in the file server
machine's root directory, not in one of its subdirectories (for example, <emphasis role="bold">/usr/vicepa</emphasis> is
- not an acceptable directory location).</para>
+ not an acceptable directory location).
+
+ The <emphasis role="bold">fileserver</emphasis> will refuse to
+ mount
+ any <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>
+ folders that are not separate partitions. </para>
+
+ <warning>
+ <para>The separate partition requirement may be overridden by
+ creating a file named
+ <emphasis role="bold">/vicep<replaceable>xx</replaceable>/AlwaysAttach</emphasis>;
+ however, mixed-use partitions, whether cache or fileserver,
+ have the risk that a non-AFS use will fill the partition and
+ not leave enough free space for AFS. Even though it is
+ allowed, be wary of configuring a mixed-use partition
+ without understanding the ramifications of doing so with the
+ workload on your filesystem.
+ <indexterm>
+ <primary>AFS server partition</primary>
+ <secondary>AlwaysAttach</secondary>
+ </indexterm>
+ </para>
+ </warning>
<para>You can also add or remove server partitions on an existing file server machine. For instructions, see the chapter
in the <emphasis>OpenAFS Administration Guide</emphasis> about maintaining server machines.</para>
</listitem>
<listitem>
- <para>On some system types, install and configure a modified <emphasis role="bold">fsck</emphasis> program which
+ <para>On system types using the <emphasis role="bold">inode</emphasis> storage format, install and configure a modified <emphasis role="bold">fsck</emphasis> program which
recognizes the structures that the File Server uses to organize volume data on AFS server partitions. The <emphasis
role="bold">fsck</emphasis> program provided with the operating system does not understand the AFS data structures, and so
removes them to the <emphasis role="bold">lost+found</emphasis> directory.</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>
</listitem>
<listitem>
- <para><link linkend="HDRWQ31">Getting Started on HP-UX Systems</link></para>
- </listitem>
-
- <listitem>
- <para><link linkend="HDRWQ36">Getting Started on IRIX Systems</link></para>
- </listitem>
-
- <listitem>
<para><link linkend="HDRWQ41">Getting Started on Linux Systems</link></para>
</listitem>
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>
+ # <emphasis role="bold">cd /tmp/afsdist/rs_aix42/dest/root.client/usr/vice/etc</emphasis>
</programlisting></para>
</listitem>
<secondary>fsck program</secondary>
- <tertiary>on AIX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>AIX</primary>
-
- <secondary>fsck program</secondary>
-
- <tertiary>on first AFS machine</tertiary>
- </indexterm>
- </sect2>
-
- <sect2 id="HDRWQ24">
- <title>Replacing the fsck Program Helper on AIX Systems</title>
-
- <note><para>The AFS modified fsck program is not required on AIX 5.1
- systems, and the <emphasis role="bold">v3fshelper</emphasis> program
- refered to below is not shipped for these systems.</para></note>
-
- <para>In this section, you make modifications to guarantee that the appropriate <emphasis role="bold">fsck</emphasis> program
- runs on AFS server partitions. The <emphasis role="bold">fsck</emphasis> program provided with the operating system must never
- run on AFS server partitions. Because it does not recognize the structures that the File Server uses to organize volume data,
- it removes all of the data. To repeat:</para>
-
- <para><emphasis role="bold">Never run the standard fsck program on AFS server partitions. It discards AFS
- volumes.</emphasis></para>
-
- <para>On AIX systems, you do not replace the <emphasis role="bold">fsck</emphasis> binary itself, but rather the
- <emphasis>program helper</emphasis> file included in the AIX distribution as <emphasis
- role="bold">/sbin/helpers/v3fshelper</emphasis>. <orderedlist>
- <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.
-<programlisting>
- # <emphasis role="bold">cd /sbin/helpers</emphasis>
- # <emphasis role="bold">mv v3fshelper v3fshelper.noafs</emphasis>
- # <emphasis role="bold">cp -p /tmp/afsdist/rs_aix42/root.server/etc/v3fshelper v3fshelper</emphasis>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>If you plan to retain client functionality on this machine after completing the installation, proceed to <link
- linkend="HDRWQ25">Enabling AFS Login on AIX Systems</link>. Otherwise, proceed to <link linkend="HDRWQ50">Starting the
- BOS Server</link>.</para>
- </listitem>
- </orderedlist></para>
-
- <indexterm>
- <primary>enabling AFS login</primary>
-
- <secondary>file server machine</secondary>
-
- <tertiary>AIX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>AFS login</primary>
-
- <secondary>on file server machine</secondary>
-
- <tertiary>AIX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>first AFS machine</primary>
-
- <secondary>AFS login</secondary>
-
- <tertiary>on AIX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>AIX</primary>
-
- <secondary>AFS login</secondary>
-
- <tertiary>on file server machine</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>secondary authentication system (AIX)</primary>
-
- <secondary>server machine</secondary>
- </indexterm>
- </sect2>
-
- <sect2 id="HDRWQ25">
- <title>Enabling AFS Login on AIX 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>
- </note>
-
- <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>
-
-<!--
- 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>
- -->
- </sect2>
- </sect1>
-
- <sect1 id="HDRWQ31">
- <title>Getting Started on HP-UX Systems</title>
-
- <para>Begin by building AFS modifications into a new kernel; HP-UX does not support dynamic loading. Then create partitions for
- storing AFS volumes, and install and configure the AFS-modified <emphasis role="bold">fsck</emphasis> program to run on AFS
- server partitions. If the machine is to remain an AFS client machine, incorporate AFS into the machine's Pluggable
- Authentication Module (PAM) scheme. <indexterm>
- <primary>incorporating AFS kernel extensions</primary>
-
- <secondary>first AFS machine</secondary>
-
- <tertiary>HP-UX</tertiary>
- </indexterm> <indexterm>
- <primary>AFS kernel extensions</primary>
-
- <secondary>on first AFS machine</secondary>
-
- <tertiary>HP-UX</tertiary>
- </indexterm> <indexterm>
- <primary>first AFS machine</primary>
-
- <secondary>AFS kernel extensions</secondary>
-
- <tertiary>on HP-UX</tertiary>
- </indexterm> <indexterm>
- <primary>HP-UX</primary>
-
- <secondary>AFS-modified kernel</secondary>
-
- <tertiary>on first AFS machine</tertiary>
- </indexterm></para>
-
- <sect2 id="HDRWQ32">
- <title>Building AFS into the HP-UX Kernel</title>
-
- <para>Use the following instructions to build AFS modifications into the kernel on an HP-UX system. <orderedlist>
- <listitem>
- <para>Move the existing kernel-related files to a safe location. <programlisting>
- # <emphasis role="bold">cp /stand/vmunix /stand/vmunix.noafs</emphasis>
- # <emphasis role="bold">cp /stand/system /stand/system.noafs</emphasis>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <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>
-
- <listitem>
- <para>Copy the AFS initialization file to the local directory for initialization files (by convention, <emphasis
- role="bold">/sbin/init.d</emphasis> on HP-UX machines). Note the removal of the <emphasis role="bold">.rc</emphasis>
- extension as you copy the file. <programlisting>
- # <emphasis role="bold">cp usr/vice/etc/afs.rc /sbin/init.d/afs</emphasis>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Copy the file <emphasis role="bold">afs.driver</emphasis> to the local <emphasis
- role="bold">/usr/conf/master.d</emphasis> directory, changing its name to <emphasis role="bold">afs</emphasis> as you
- do. <programlisting>
- # <emphasis role="bold">cp usr/vice/etc/afs.driver /usr/conf/master.d/afs</emphasis>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Copy the AFS kernel module to the local <emphasis role="bold">/usr/conf/lib</emphasis> directory.</para>
-
- <para>If the machine's kernel supports NFS server functionality:</para>
-
- <programlisting>
- # <emphasis role="bold">cp bin/libafs.a /usr/conf/lib</emphasis>
-</programlisting>
-
- <para>If the machine's kernel does not support NFS server functionality, change the file's name as you copy it:</para>
-
- <programlisting>
- # <emphasis role="bold">cp bin/libafs.nonfs.a /usr/conf/lib/libafs.a</emphasis>
-</programlisting>
- </listitem>
-
- <listitem>
- <para>Incorporate the AFS driver into the kernel, either using the <emphasis role="bold">SAM</emphasis> program or a
- series of individual commands. <itemizedlist>
- <listitem>
- <para>To use the <emphasis role="bold">SAM</emphasis> program: <orderedlist>
- <listitem>
- <para>Invoke the <emphasis role="bold">SAM</emphasis> program, specifying the hostname of the local machine
- as <replaceable>local_hostname</replaceable>. The <emphasis role="bold">SAM</emphasis> graphical user
- interface pops up. <programlisting>
- # <emphasis role="bold">sam -display</emphasis> <replaceable>local_hostname</replaceable><emphasis role="bold">:0</emphasis>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Choose the <emphasis role="bold">Kernel Configuration</emphasis> icon, then the <emphasis
- role="bold">Drivers</emphasis> icon. From the list of drivers, select <emphasis
- role="bold">afs</emphasis>.</para>
- </listitem>
-
- <listitem>
- <para>Open the pull-down <emphasis role="bold">Actions</emphasis> menu and choose the <emphasis
- role="bold">Add Driver to Kernel</emphasis> option.</para>
- </listitem>
-
- <listitem>
- <para>Open the <emphasis role="bold">Actions</emphasis> menu again and choose the <emphasis
- role="bold">Create a New Kernel</emphasis> option.</para>
- </listitem>
-
- <listitem>
- <para>Confirm your choices by choosing <emphasis role="bold">Yes</emphasis> and <emphasis
- role="bold">OK</emphasis> when prompted by subsequent pop-up windows. The <emphasis
- role="bold">SAM</emphasis> program builds the kernel and reboots the system.</para>
- </listitem>
-
- <listitem>
- <para>Login again as the superuser <emphasis role="bold">root</emphasis>. <programlisting>
- login: <emphasis role="bold">root</emphasis>
- Password: <replaceable>root_password</replaceable>
-</programlisting></para>
- </listitem>
- </orderedlist></para>
- </listitem>
-
- <listitem>
- <para>To use individual commands: <orderedlist>
- <listitem>
- <para>Edit the file <emphasis role="bold">/stand/system</emphasis>, adding an entry for <emphasis
- role="bold">afs</emphasis> to the <computeroutput>Subsystems</computeroutput> section.</para>
- </listitem>
-
- <listitem>
- <para>Change to the <emphasis role="bold">/stand/build</emphasis> directory and issue the <emphasis
- role="bold">mk_kernel</emphasis> command to build the kernel. <programlisting>
- # <emphasis role="bold">cd /stand/build</emphasis>
- # <emphasis role="bold">mk_kernel</emphasis>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Move the new kernel to the standard location (<emphasis role="bold">/stand/vmunix</emphasis>), reboot
- the machine to start using it, and login again as the superuser <emphasis role="bold">root</emphasis>.
- <programlisting>
- # <emphasis role="bold">mv /stand/build/vmunix_test /stand/vmunix</emphasis>
- # <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>
- </orderedlist></para>
- </listitem>
- </itemizedlist></para>
- </listitem>
- </orderedlist></para>
-
- <indexterm>
- <primary>configuring</primary>
-
- <secondary>AFS server partition on first AFS machine</secondary>
-
- <tertiary>HP-UX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>AFS server partition</primary>
-
- <secondary>configuring on first AFS machine</secondary>
-
- <tertiary>HP-UX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>first AFS machine</primary>
-
- <secondary>AFS server partition</secondary>
-
- <tertiary>on HP-UX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>HP-UX</primary>
-
- <secondary>AFS server partition</secondary>
-
- <tertiary>on first AFS machine</tertiary>
- </indexterm>
- </sect2>
-
- <sect2 id="HDRWQ33">
- <title>Configuring Server Partitions on HP-UX Systems</title>
-
- <para>Every AFS file server machine must have at least one partition or logical volume dedicated to storing AFS volumes. Each
- server partition is mounted at a directory named <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>, where
- <replaceable>xx</replaceable> is one or two lowercase letters. The <emphasis
- role="bold">/vicep</emphasis><replaceable>xx</replaceable> directories must reside in the file server machine's root
- directory, not in one of its subdirectories (for example, <emphasis role="bold">/usr/vicepa</emphasis> is not an acceptable
- directory location). For additional information, see <link linkend="HDRWQ20">Performing Platform-Specific Procedures</link>.
- <orderedlist>
- <listitem>
- <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>
- # <emphasis role="bold">mkdir /vicep</emphasis><replaceable>xx</replaceable>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Use the <emphasis role="bold">SAM</emphasis> program to create a file system on each partition. For instructions,
- consult the HP-UX documentation.</para>
- </listitem>
-
- <listitem>
- <para>On some HP-UX systems that use logical volumes, the <emphasis role="bold">SAM</emphasis> program automatically
- mounts the partitions. If it has not, mount each partition by issuing either the <emphasis role="bold">mount
- -a</emphasis> command to mount all partitions at once or the <emphasis role="bold">mount</emphasis> command to mount
- each partition in turn.</para>
- </listitem>
- </orderedlist></para>
-
- <indexterm>
- <primary>replacing fsck program</primary>
-
- <secondary>first AFS machine</secondary>
-
- <tertiary>HP-UX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>fsck program</primary>
-
- <secondary>on first AFS machine</secondary>
-
- <tertiary>HP-UX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>first AFS machine</primary>
-
- <secondary>fsck program</secondary>
-
- <tertiary>on HP-UX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>HP-UX</primary>
-
- <secondary>fsck program</secondary>
-
- <tertiary>on first AFS machine</tertiary>
- </indexterm>
- </sect2>
-
- <sect2 id="HDRWQ34">
- <title>Configuring the AFS-modified fsck Program on HP-UX Systems</title>
-
- <para>In this section, you make modifications to guarantee that the appropriate <emphasis role="bold">fsck</emphasis> program
- runs on AFS server partitions. The <emphasis role="bold">fsck</emphasis> program provided with the operating system must never
- run on AFS server partitions. Because it does not recognize the structures that the File Server uses to organize volume data,
- it removes all of the data. To repeat:</para>
-
- <para><emphasis role="bold">Never run the standard fsck program on AFS server partitions. It discards AFS
- volumes.</emphasis></para>
-
- <para>On HP-UX systems, there are several configuration files to install in addition to the AFS-modified <emphasis
- role="bold">fsck</emphasis> program (the <emphasis role="bold">vfsck</emphasis> binary). <orderedlist>
- <listitem>
- <para>Create the command configuration file <emphasis role="bold">/sbin/lib/mfsconfig.d/afs</emphasis>. Use a text
- editor to place the indicated two lines in it: <programlisting>
- format_revision 1
- fsck 0 m,P,p,d,f,b:c:y,n,Y,N,q,
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Create and change directory to an AFS-specific command directory called <emphasis
- role="bold">/sbin/fs/afs</emphasis>. <programlisting>
- # <emphasis role="bold">mkdir /sbin/fs/afs</emphasis>
- # <emphasis role="bold">cd /sbin/fs/afs</emphasis>
-</programlisting></para>
- </listitem>
-
- <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 /tmp/afsdist/hp_ux110/root.server/etc/* .</emphasis>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Change the <emphasis role="bold">vfsck</emphasis> binary's name to <emphasis role="bold">fsck</emphasis> and set
- the mode bits appropriately on all of the files in the <emphasis role="bold">/sbin/fs/afs</emphasis> directory.
- <programlisting>
- # <emphasis role="bold">mv vfsck fsck</emphasis>
- # <emphasis role="bold">chmod 755 *</emphasis>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Edit the <emphasis role="bold">/etc/fstab</emphasis> file, changing the file system type for each AFS server
- partition from <computeroutput>hfs</computeroutput> to <computeroutput>afs</computeroutput>. This ensures that the
- AFS-modified <emphasis role="bold">fsck</emphasis> program runs on the appropriate partitions.</para>
-
- <para>The sixth line in the following example of an edited file shows an AFS server partition, <emphasis
- role="bold">/vicepa</emphasis>.</para>
-
- <programlisting>
- /dev/vg00/lvol1 / hfs defaults 0 1
- /dev/vg00/lvol4 /opt hfs defaults 0 2
- /dev/vg00/lvol5 /tmp hfs defaults 0 2
- /dev/vg00/lvol6 /usr hfs defaults 0 2
- /dev/vg00/lvol8 /var hfs defaults 0 2
- /dev/vg00/lvol9 /vicepa afs defaults 0 2
- /dev/vg00/lvol7 /usr/vice/cache hfs defaults 0 2
-</programlisting>
- </listitem>
-
- <listitem>
- <para>If you plan to retain client functionality on this machine after completing the installation, proceed to <link
- linkend="HDRWQ35">Enabling AFS Login on HP-UX Systems</link>. Otherwise, proceed to <link linkend="HDRWQ50">Starting the
- BOS Server</link>.</para>
- </listitem>
- </orderedlist></para>
-
- <indexterm>
- <primary>enabling AFS login</primary>
-
- <secondary>file server machine</secondary>
-
- <tertiary>HP-UX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>AFS login</primary>
-
- <secondary>on file server machine</secondary>
-
- <tertiary>HP-UX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>first AFS machine</primary>
-
- <secondary>AFS login</secondary>
-
- <tertiary>on HP-UX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>HP-UX</primary>
-
- <secondary>AFS login</secondary>
-
- <tertiary>on file server machine</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>PAM</primary>
-
- <secondary>on HP-UX</secondary>
-
- <tertiary>file server machine</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>Pluggable Authentication Module</primary>
-
- <see>PAM</see>
- </indexterm>
- </sect2>
-
- <sect2 id="HDRWQ35">
- <title>Enabling AFS Login on HP-UX 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></note>
-
- <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>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>
-
-<!--
- <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>
-
- <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>
-
- </sect2>
- </sect1>
-
- <sect1 id="HDRWQ36">
- <title>Getting Started on IRIX Systems</title>
-
- <indexterm>
- <primary>incorporating AFS kernel extensions</primary>
-
- <secondary>first AFS machine</secondary>
-
- <tertiary>IRIX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>AFS kernel extensions</primary>
-
- <secondary>on first AFS machine</secondary>
-
- <tertiary>IRIX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>first AFS machine</primary>
-
- <secondary>AFS kernel extensions</secondary>
-
- <tertiary>on IRIX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>replacing fsck program</primary>
-
- <secondary>not necessary on IRIX</secondary>
- </indexterm>
-
- <indexterm>
- <primary>fsck program</primary>
-
- <secondary>on first AFS machine</secondary>
-
- <tertiary>IRIX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>first AFS machine</primary>
-
- <secondary>fsck program</secondary>
-
- <tertiary>on IRIX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>IRIX</primary>
-
- <secondary>fsck program replacement not necessary</secondary>
- </indexterm>
-
- <para>To incorporate AFS into the kernel on IRIX systems, choose one of two methods: <itemizedlist>
- <listitem>
- <para>Run the AFS initialization script to invoke the <emphasis role="bold">ml</emphasis> program distributed by Silicon
- Graphics, Incorporated (SGI), which dynamically loads AFS modifications into the kernel</para>
- </listitem>
-
- <listitem>
- <para>Build a new static kernel</para>
- </listitem>
- </itemizedlist></para>
-
- <para>Then create partitions for storing AFS volumes. You do not need to replace the IRIX <emphasis role="bold">fsck</emphasis>
- program because SGI has already modified it to handle AFS volumes properly. If the machine is to remain an AFS client machine,
- verify that the IRIX login utility installed on the machine grants an AFS token.</para>
-
- <para>In preparation for either dynamic loading or kernel building, perform the following procedures: <orderedlist>
- <listitem>
- <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>
- extension as you copy the script. <programlisting>
- # <emphasis role="bold">cp -p usr/vice/etc/afs.rc /etc/init.d/afs</emphasis>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Issue the <emphasis role="bold">uname -m</emphasis> command to determine the machine's CPU board type. The <emphasis
- role="bold">IP</emphasis><replaceable>xx</replaceable> value in the output must match one of the supported CPU board types
- listed in the <emphasis>OpenAFS Release Notes</emphasis> for the current version of AFS. <programlisting>
- # <emphasis role="bold">uname -m</emphasis>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Proceed to either <link linkend="HDRWQ37">Loading AFS into the IRIX Kernel</link> or <link
- linkend="HDRWQ38">Building AFS into the IRIX Kernel</link>.</para>
- </listitem>
- </orderedlist></para>
-
- <indexterm>
- <primary>IRIX</primary>
-
- <secondary>AFS kernel extensions</secondary>
-
- <tertiary>on first AFS machine</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>afsml variable (IRIX)</primary>
-
- <secondary>first AFS machine</secondary>
- </indexterm>
-
- <indexterm>
- <primary>variables</primary>
-
- <secondary>afsml (IRIX)</secondary>
-
- <tertiary>first AFS machine</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>IRIX</primary>
-
- <secondary>afsml variable</secondary>
-
- <tertiary>first AFS machine</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>afsxnfs variable (IRIX)</primary>
-
- <secondary>first AFS machine</secondary>
- </indexterm>
-
- <indexterm>
- <primary>variables</primary>
-
- <secondary>afsxnfs (IRIX)</secondary>
-
- <tertiary>first AFS machine</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>IRIX</primary>
-
- <secondary>afsxnfs variable</secondary>
-
- <tertiary>first AFS machine</tertiary>
- </indexterm>
-
- <sect2 id="HDRWQ37">
- <title>Loading AFS into the IRIX Kernel</title>
-
- <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
- activated. In this section you activate the variable and run the script.</para>
-
- <para>In later sections you verify that the script correctly initializes all AFS components, then create the links that
- incorporate AFS into the IRIX startup and shutdown sequence. <orderedlist>
- <listitem>
- <para>Create the local <emphasis role="bold">/usr/vice/etc/sgiload</emphasis> directory to house the AFS kernel library
- file. <programlisting>
- # <emphasis role="bold">mkdir /usr/vice/etc/sgiload</emphasis>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Copy the appropriate AFS kernel library file to the <emphasis role="bold">/usr/vice/etc/sgiload</emphasis>
- directory. The <emphasis role="bold">IP</emphasis><replaceable>xx</replaceable> portion of the library file name must
- match the value previously returned by the <emphasis role="bold">uname -m</emphasis> command. Also choose the file
- appropriate to whether the machine's kernel supports NFS server functionality (NFS must be supported for the machine to
- act as an NFS/AFS Translator). Single- and multiprocessor machines use the same library file.</para>
-
- <para>(You can choose to copy all of the kernel library files into the <emphasis
- role="bold">/usr/vice/etc/sgiload</emphasis> directory, but they require a significant amount of space.)</para>
-
- <para>If the machine's kernel supports NFS server functionality:</para>
-
- <programlisting>
- # <emphasis role="bold">cp -p usr/vice/etc/sgiload/libafs.IP</emphasis><replaceable>xx</replaceable><emphasis role="bold">.o /usr/vice/etc/sgiload</emphasis>
-</programlisting>
-
- <para>If the machine's kernel does not support NFS server functionality:</para>
-
- <programlisting>
- # <emphasis role="bold">cp -p usr/vice/etc/sgiload/libafs.IP</emphasis><replaceable>xx</replaceable><emphasis role="bold">.nonfs.o</emphasis> \
- <emphasis role="bold">/usr/vice/etc/sgiload</emphasis>
-</programlisting>
- </listitem>
-
- <listitem>
- <para>Issue the <emphasis role="bold">chkconfig</emphasis> command to activate the <emphasis
- role="bold">afsml</emphasis> configuration variable. <programlisting>
- # <emphasis role="bold">/etc/chkconfig -f afsml on</emphasis>
-</programlisting></para>
-
- <para>If the machine is to function as an NFS/AFS Translator and the kernel supports NFS server functionality, activate
- the <emphasis role="bold">afsxnfs</emphasis> variable.</para>
-
- <programlisting>
- # <emphasis role="bold">/etc/chkconfig -f afsxnfs on</emphasis>
-</programlisting>
- </listitem>
-
- <listitem>
- <para>Run the <emphasis role="bold">/etc/init.d/afs</emphasis> script to load AFS extensions into the kernel. The script
- invokes the <emphasis role="bold">ml</emphasis> command, automatically determining which kernel library file to use
- based on this machine's CPU type and the activation state of the <emphasis role="bold">afsxnfs</emphasis>
- variable.</para>
-
- <para>You can ignore any error messages about the inability to start the BOS Server or the Cache Manager or AFS
- client.</para>
-
- <programlisting>
- # <emphasis role="bold">/etc/init.d/afs start</emphasis>
-</programlisting>
- </listitem>
-
- <listitem>
- <para>Proceed to <link linkend="HDRWQ39">Configuring Server Partitions on IRIX Systems</link>.</para>
- </listitem>
- </orderedlist></para>
-
- <indexterm>
- <primary>IRIX</primary>
-
- <secondary>AFS-modified kernel</secondary>
-
- <tertiary>on first AFS machine</tertiary>
- </indexterm>
- </sect2>
-
- <sect2 id="HDRWQ38">
- <title>Building AFS into the IRIX Kernel</title>
-
- <para>Use the following instructions to build AFS modifications into the kernel on an IRIX system. <orderedlist>
- <listitem>
- <para>Copy the kernel initialization file <emphasis role="bold">afs.sm</emphasis> to the local <emphasis
- role="bold">/var/sysgen/system</emphasis> directory, and the kernel master file <emphasis role="bold">afs</emphasis> to
- the local <emphasis role="bold">/var/sysgen/master.d</emphasis> directory. <programlisting>
- # <emphasis role="bold">cp -p bin/afs.sm /var/sysgen/system</emphasis>
- # <emphasis role="bold">cp -p bin/afs /var/sysgen/master.d</emphasis>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Copy the appropriate AFS kernel library file to the local file <emphasis
- role="bold">/var/sysgen/boot/afs.a</emphasis>; the <emphasis role="bold">IP</emphasis><replaceable>xx</replaceable>
- portion of the library file name must match the value previously returned by the <emphasis role="bold">uname
- -m</emphasis> command. Also choose the file appropriate to whether the machine's kernel supports NFS server
- functionality (NFS must be supported for the machine to act as an NFS/AFS Translator). Single- and multiprocessor
- machines use the same library file.</para>
-
- <para>If the machine's kernel supports NFS server functionality:</para>
-
- <programlisting>
- # <emphasis role="bold">cp -p bin/libafs.IP</emphasis><replaceable>xx</replaceable><emphasis role="bold">.a /var/sysgen/boot/afs.a</emphasis>
-</programlisting>
-
- <para>If the machine's kernel does not support NFS server functionality:</para>
-
- <programlisting>
- # <emphasis role="bold">cp -p bin/libafs.IP</emphasis><replaceable>xx</replaceable><emphasis role="bold">.nonfs.a /var/sysgen/boot/afs.a</emphasis>
-</programlisting>
- </listitem>
-
- <listitem>
- <para>Issue the <emphasis role="bold">chkconfig</emphasis> command to deactivate the <emphasis
- role="bold">afsml</emphasis> configuration variable. <programlisting>
- # <emphasis role="bold">/etc/chkconfig -f afsml off</emphasis>
-</programlisting></para>
-
- <para>If the machine is to function as an NFS/AFS Translator and the kernel supports NFS server functionality, activate
- the <emphasis role="bold">afsxnfs</emphasis> variable.</para>
-
- <programlisting>
- # <emphasis role="bold">/etc/chkconfig -f afsxnfs on</emphasis>
-</programlisting>
- </listitem>
-
- <listitem>
- <para>Copy the existing kernel file, <emphasis role="bold">/unix</emphasis>, to a safe location. Compile the new kernel,
- which is created in the file <emphasis role="bold">/unix.install</emphasis>. It overwrites the existing <emphasis
- role="bold">/unix</emphasis> file when the machine reboots in the next step. <programlisting>
- # <emphasis role="bold">cp /unix /unix_noafs</emphasis>
- # <emphasis role="bold">autoconfig</emphasis>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Reboot the machine to start using the new kernel, and login again as the superuser <emphasis
- role="bold">root</emphasis>. <programlisting>
- # <emphasis role="bold">cd /</emphasis>
- # <emphasis role="bold">shutdown -i6 -g0 -y</emphasis>
- login: <emphasis role="bold">root</emphasis>
- Password: <replaceable>root_password</replaceable>
-</programlisting></para>
- </listitem>
- </orderedlist></para>
-
- <indexterm>
- <primary>configuring</primary>
-
- <secondary>AFS server partition on first AFS machine</secondary>
-
- <tertiary>IRIX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>AFS server partition</primary>
-
- <secondary>configuring on first AFS machine</secondary>
-
- <tertiary>IRIX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>first AFS machine</primary>
-
- <secondary>AFS server partition</secondary>
-
- <tertiary>on IRIX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>IRIX</primary>
-
- <secondary>AFS server partition</secondary>
-
- <tertiary>on first AFS machine</tertiary>
- </indexterm>
- </sect2>
-
- <sect2 id="HDRWQ39">
- <title>Configuring Server Partitions on IRIX Systems</title>
-
- <para>Every AFS file server machine must have at least one partition or logical volume dedicated to storing AFS volumes. Each
- server partition is mounted at a directory named <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>, where
- <replaceable>xx</replaceable> is one or two lowercase letters. The <emphasis
- role="bold">/vicep</emphasis><replaceable>xx</replaceable> directories must reside in the file server machine's root
- directory, not in one of its subdirectories (for example, <emphasis role="bold">/usr/vicepa</emphasis> is not an acceptable
- directory location). For additional information, see <link linkend="HDRWQ20">Performing Platform-Specific
- Procedures</link>.</para>
-
- <para>AFS supports use of both EFS and XFS partitions for housing AFS volumes. SGI encourages use of XFS partitions.
- <orderedlist>
- <listitem>
- <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>
- # <emphasis role="bold">mkdir /vicep</emphasis><replaceable>xx</replaceable>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Add a line with the following format to the file systems registry file, <emphasis
- role="bold">/etc/fstab</emphasis>, for each partition (or logical volume created with the XLV volume manager) to be
- mounted on one of the directories created in the previous step.</para>
-
- <para>For an XFS partition or logical volume:</para>
-
- <programlisting>
- /dev/dsk/<replaceable>disk</replaceable> /vicep<replaceable>xx</replaceable> xfs rw,raw=/dev/rdsk/<replaceable>disk</replaceable> 0 0
-</programlisting>
-
- <para>For an EFS partition:</para>
-
- <programlisting>
- /dev/dsk/<replaceable>disk</replaceable> /vicep<replaceable>xx</replaceable> efs rw,raw=/dev/rdsk/<replaceable>disk</replaceable> 0 0
-</programlisting>
-
- <para>The following are examples of an entry for each file system type:</para>
-
- <programlisting>
- /dev/dsk/dks0d2s6 /vicepa xfs rw,raw=/dev/rdsk/dks0d2s6 0 0
- /dev/dsk/dks0d3s1 /vicepb efs rw,raw=/dev/rdsk/dks0d3s1 0 0
-</programlisting>
- </listitem>
+ <tertiary>on AIX</tertiary>
+ </indexterm>
- <listitem>
- <para>Create a file system on each partition that is to be mounted on a <emphasis
- role="bold">/vicep</emphasis><replaceable>xx</replaceable> directory. The following commands are probably appropriate,
- but consult the IRIX documentation for more information. In both cases, <replaceable>raw_device</replaceable> is a raw
- device name like <emphasis role="bold">/dev/rdsk/dks0d0s0</emphasis> for a single disk partition or <emphasis
- role="bold">/dev/rxlv/xlv0</emphasis> for a logical volume.</para>
+ <indexterm>
+ <primary>AIX</primary>
- <para>For XFS file systems, include the indicated options to configure the partition or logical volume with inodes large
- enough to accommodate AFS-specific information:</para>
+ <secondary>fsck program</secondary>
- <programlisting>
- # <emphasis role="bold">mkfs -t xfs -i size=512 -l size=4000b</emphasis> <replaceable>raw_device</replaceable>
-</programlisting>
+ <tertiary>on first AFS machine</tertiary>
+ </indexterm>
+ </sect2>
- <para>For EFS file systems:</para>
+ <sect2 id="HDRWQ24">
+ <title>Replacing the fsck Program Helper on AIX Systems</title>
- <programlisting>
- # <emphasis role="bold">mkfs -t efs</emphasis> <replaceable>raw_device</replaceable>
-</programlisting>
- </listitem>
+ <note><para>The AFS modified fsck program is not required on AIX 5.1
+ systems, and the <emphasis role="bold">v3fshelper</emphasis> program
+ refered to below is not shipped for these systems.</para></note>
+
+ <para>In this section, you make modifications to guarantee that the appropriate <emphasis role="bold">fsck</emphasis> program
+ runs on AFS server partitions. The <emphasis role="bold">fsck</emphasis> program provided with the operating system must never
+ run on AFS server partitions. Because it does not recognize the structures that the File Server uses to organize volume data,
+ it removes all of the data. To repeat:</para>
- <listitem>
- <para>Mount each partition by issuing either the <emphasis role="bold">mount -a</emphasis> command to mount all
- partitions at once or the <emphasis role="bold">mount</emphasis> command to mount each partition in turn.</para>
- </listitem>
+ <para><emphasis role="bold">Never run the standard fsck program on AFS server partitions. It discards AFS
+ volumes.</emphasis></para>
+ <para>On AIX systems, you do not replace the <emphasis role="bold">fsck</emphasis> binary itself, but rather the
+ <emphasis>program helper</emphasis> file included in the AIX distribution as <emphasis
+ role="bold">/sbin/helpers/v3fshelper</emphasis>. <orderedlist>
<listitem>
- <para><emphasis role="bold">(Optional)</emphasis> If you have configured partitions or logical volumes to use XFS, issue
- the following command to verify that the inodes are configured properly (are large enough to accommodate AFS-specific
- information). If the configuration is correct, the command returns no output. Otherwise, it specifies the command to run
- in order to configure each partition or logical volume properly. <programlisting>
- # <emphasis role="bold">/usr/afs/bin/xfs_size_check</emphasis>
+ <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.
+<programlisting>
+ # <emphasis role="bold">cd /sbin/helpers</emphasis>
+ # <emphasis role="bold">mv v3fshelper v3fshelper.noafs</emphasis>
+ # <emphasis role="bold">cp -p /tmp/afsdist/rs_aix42/dest/root.server/etc/v3fshelper v3fshelper</emphasis>
</programlisting></para>
</listitem>
<listitem>
<para>If you plan to retain client functionality on this machine after completing the installation, proceed to <link
- linkend="HDRWQ40">Enabling AFS Login on IRIX Systems</link>. Otherwise, proceed to <link linkend="HDRWQ50">Starting the
+ linkend="HDRWQ25">Enabling AFS Login on AIX Systems</link>. Otherwise, proceed to <link linkend="HDRWQ50">Starting the
BOS Server</link>.</para>
</listitem>
</orderedlist></para>
<secondary>file server machine</secondary>
- <tertiary>IRIX</tertiary>
+ <tertiary>AIX</tertiary>
</indexterm>
<indexterm>
<secondary>on file server machine</secondary>
- <tertiary>IRIX</tertiary>
+ <tertiary>AIX</tertiary>
</indexterm>
<indexterm>
<secondary>AFS login</secondary>
- <tertiary>on IRIX</tertiary>
+ <tertiary>on AIX</tertiary>
</indexterm>
<indexterm>
- <primary>IRIX</primary>
+ <primary>AIX</primary>
<secondary>AFS login</secondary>
+
+ <tertiary>on file server machine</tertiary>
+ </indexterm>
+
+ <indexterm>
+ <primary>secondary authentication system (AIX)</primary>
+
+ <secondary>server machine</secondary>
</indexterm>
</sect2>
- <sect2 id="HDRWQ40">
- <title>Enabling AFS Login on IRIX Systems</title>
+ <sect2 id="HDRWQ25">
+ <title>Enabling AFS Login on AIX 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>
</note>
- <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>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>
-
- <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>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>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>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>
RedHat Enterprise Linux packages distributed by OpenAFS. Additional
instructions are provided for those building from source.</para>
- <para>Begin by running the AFS client startup scripts, which call the <emphasis role="bold">modprobe</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. If the machine is to remain an AFS client machine, incorporate AFS into
- the machine's Pluggable Authentication Module (PAM) scheme. <indexterm>
+ <para>Begin by running the AFS client startup scripts, which call the
+ <emphasis role="bold">modprobe</emphasis> program to dynamically
+ load the 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. If the machine is to remain an
+ AFS client machine, incorporate AFS into the machine's Pluggable
+ Authentication Module (PAM) scheme. <indexterm>
<primary>incorporating AFS kernel extensions</primary>
<secondary>first AFS machine</secondary>
<para>The procedure for starting up OpenAFS depends upon your distribution</para>
<sect3>
<title>Fedora and RedHat Enterprise Linux</title>
- <para>OpenAFS ship RPMS for all current Fedora and RHEL releases.
+ <para>OpenAFS provides RPMS for all current Fedora and RedHat Enterprise Linux (RHEL) releases on the OpenAFS web site and the OpenAFS yum repository.
<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>
- <emphasis role="bold">openafs-client></emphasis>
- <emphasis role="bold">openafs-server</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>
+ <para>Browse to
+ http://dl.openafs.org/dl/openafs/<replaceable>VERSION</replaceable>,
+ where VERSION is the latest stable release of
+ OpenAFS. Download the
+ openafs-repository-<replaceable>VERSION</replaceable>.noarch.rpm
+ file for Fedora systems or the
+ openafs-repository-rhel-<replaceable>VERSION</replaceable>.noarch.rpm
+ file for RedHat-based systems.
+ </para>
+ </listitem>
+ <listitem>
+ <para>Install the downloaded RPM file using the following command:
+ <programlisting>
+ # rpm -U openafs-repository*.rpm
+ </programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>Install the RPM set for your operating system using the yum command as follows:
+ <programlisting>
+ # yum -y install openafs-client openafs-server openafs-krb5 kmod-openafs
+ </programlisting>
+
+ </para>
+ <para>Alternatively, you may use dynamically-compiled kernel
+ modules if you have the kernel headers, a compiler, and the
+ dkms package from
+ <ulink url="http://fedoraproject.org/wiki/EPEL"><citetitle>EPEL</citetitle></ulink> installed.
+
+ </para>
+ <para>To use dynamically-compiled kernel modules instead of statically compiled modules, use the following command instead of the kmod-openafs as shown above:
+ <programlisting>
+ # yum install openafs-client openafs-server openafs-krb5 dkms-openafs
+ </programlisting>
+ </para>
</listitem>
<!-- If you do this with current RHEL and Fedora releases you end up with
a dynroot'd client running - this breaks setting up the root.afs volume
<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
+ <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>
+ # <emphasis role="bold">cd /tmp/afsdist/linux/dest/root.client/usr/vice/etc</emphasis>
</programlisting></para>
</listitem>
<title>Enabling AFS Login on Linux 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>
+ <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>
</note>
- <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>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>
-
- <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>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>You should first configure your system to obtain Kerberos v5
+ tickets as part of the authentication process, and then run an AFS PAM
+ module to obtain tokens from those tickets after authentication. Many
+ Linux distributions come with a Kerberos v5 PAM module (usually called
+ pam-krb5 or pam_krb5), or you can download and install <ulink
+ url="http://www.eyrie.org/~eagle/software/pam-krb5">Russ Allbery's
+ Kerberos v5 PAM module</ulink>, which is tested regularly with AFS.
+ See the instructions of whatever PAM module you use for how to
+ configure it.</para>
+
+ <para>Some Kerberos v5 PAM modules do come with native AFS support
+ (usually requiring the Heimdal Kerberos implementation rather than the
+ MIT Kerberos implementation). If you are using one of those PAM
+ modules, you can configure it to obtain AFS tokens. It's more common,
+ however, to separate the AFS token acquisition into a separate PAM
+ module.</para>
+
+ <para>The recommended AFS PAM module is <ulink
+ url="http://www.eyrie.org/~eagle/software/pam-afs-session/">Russ
+ Allbery's pam-afs-session module</ulink>. It should work with any of
+ the Kerberos v5 PAM modules. To add it to the PAM configuration, you
+ often only need to add configuration to the session group:</para>
+
+ <example>
+ <title>Linux PAM session example</title>
+ <literallayout>session required pam_afs_session.so</literallayout>
+ </example>
+
+ <para>If you also want to obtain AFS tokens for <command>scp</command>
+ and similar commands that don't open a session, you will also need to
+ add the AFS PAM module to the auth group so that the PAM
+ <function>setcred</function> call will obtain tokens. The
+ <literal>pam_afs_session</literal> module will always return success
+ for authentication so that it can be added to the auth group only for
+ <function>setcred</function>, so make sure that it's not marked as
+ <literal>sufficient</literal>.</para>
+
+ <example>
+ <title>Linux PAM auth example</title>
+<literallayout>auth [success=ok default=1] pam_krb5.so
+auth [default=done] pam_afs_session.so
+auth required pam_unix.so try_first_pass</literallayout>
+ </example>
+
+ <para>This example will work if you want to try Kerberos v5 first and
+ then fall back to regular Unix authentication.
+ <literal>success=ok</literal> for the Kerberos PAM module followed by
+ <literal>default=done</literal> for the AFS PAM module will cause a
+ successful Kerberos login to run the AFS PAM module and then skip the
+ Unix authentication module. <literal>default=1</literal> on the
+ Kerberos PAM module causes failure of that module to skip the next
+ module (the AFS PAM module) and fall back to the Unix module. If you
+ want to try Unix authentication first and rearrange the order, be sure
+ to use <literal>default=die</literal> instead.</para>
+
+ <para>The PAM configuration is stored in different places in different
+ Linux distributions. On Red Hat, look in
+ <filename>/etc/pam.d/system-auth</filename>. On Debian and
+ derivatives, look in <filename>/etc/pam.d/common-session</filename>
+ and <filename>/etc/pam.d/common-auth</filename>.</para>
+
+ <para>For additional configuration examples and the configuration
+ options of the AFS PAM module, see its documentation. For more
+ details on the available options for the PAM configuration, see the
+ Linux PAM documentation.</para>
+
+ <para>Sites which still require <command>kaserver</command> 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>
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>
+ # <emphasis role="bold">cd /tmp/afsdist/sun4x_56/dest/root.client/usr/vice/etc</emphasis>
</programlisting></para>
</listitem>
<para>Copy the appropriate AFS kernel library file to the local file <emphasis
role="bold">/kernel/fs/afs</emphasis>.</para>
+ <para>If the machine is running Solaris 11 on the x86_64 platform:</para>
+
+ <programlisting>
+ # <emphasis role="bold">cp -p modload/libafs64.o /kernel/drv/amd64/afs</emphasis>
+</programlisting>
+
+ <para>If the machine is running Solaris 10 on the x86_64 platform:</para>
+
+ <programlisting>
+ # <emphasis role="bold">cp -p modload/libafs64.o /kernel/fs/amd64/afs</emphasis>
+</programlisting>
+
<para>If the machine is running Solaris 2.6 or the 32-bit version of Solaris 7, its kernel supports NFS server
functionality, and the <emphasis role="bold">nfsd</emphasis> process is running:</para>
<listitem>
<para>Copy the <emphasis role="bold">vfsck</emphasis> binary to the newly created directory, changing the name as you do
so. <programlisting>
- # <emphasis role="bold">cp /tmp/afsdist/sun4x_56/root.server/etc/vfsck fsck</emphasis>
+ # <emphasis role="bold">cp /tmp/afsdist/sun4x_56/dest/root.server/etc/vfsck fsck</emphasis>
</programlisting></para>
</listitem>
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>
+ <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>
+ </note>
+
+ <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>You should first configure your system to obtain Kerberos v5
+ tickets as part of the authentication process, and then run an AFS PAM
+ module to obtain tokens from those tickets after authentication.
+ Current versions of Solaris come with a Kerberos v5 PAM module that
+ will work, or you can download and install <ulink
+ url="http://www.eyrie.org/~eagle/software/pam-krb5">Russ Allbery's
+ Kerberos v5 PAM module</ulink>, which is tested regularly with AFS.
+ See the instructions of whatever PAM module you use for how to
+ configure it.</para>
+
+ <para>Some Kerberos v5 PAM modules do come with native AFS support
+ (usually requiring the Heimdal Kerberos implementation rather than the
+ MIT Kerberos implementation). If you are using one of those PAM
+ modules, you can configure it to obtain AFS tokens. It's more common,
+ however, to separate the AFS token acquisition into a separate PAM
+ module.</para>
+
+ <para>The recommended AFS PAM module is <ulink
+ url="http://www.eyrie.org/~eagle/software/pam-afs-session/">Russ
+ Allbery's pam-afs-session module</ulink>. It should work with any of
+ the Kerberos v5 PAM modules. To add it to the PAM configuration, you
+ often only need to add configuration to the session group in
+ <filename>pam.conf</filename>:</para>
+
+ <example>
+ <title>Solaris PAM session example</title>
+ <literallayout>login session required pam_afs_session.so</literallayout>
+ </example>
+
+ <para>This example enables PAM authentication only for console login.
+ You may want to add a similar line for the ssh service and for any
+ other login service that you use, including possibly the
+ <literal>other</literal> service (which serves as a catch-all). You
+ may also want to add options to the AFS PAM session module
+ (particularly <literal>retain_after_close</literal>, which is
+ necessary for some versions of Solaris.</para>
+
+ <para>For additional configuration examples and the configuration
+ options of the AFS PAM module, see its documentation. For more
+ details on the available options for the PAM configuration, see the
+ <filename>pam.conf</filename> manual page.</para>
+
+ <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 AFS
+ login on Solaris.</para>
+
+ <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>
<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>
- </note>
- <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>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>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 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>
--->
<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
</indexterm> <orderedlist>
<listitem>
<para>Issue the <emphasis role="bold">bos create</emphasis> command to start the Backup Server. <programlisting>
- # <emphasis role="bold">./bos create</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">buserver simple /usr/afs/bin/buserver</emphasis> \
- <emphasis role="bold"> -cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis role="bold">-noauth</emphasis>
+ # <emphasis role="bold">./bos create</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">buserver simple /usr/afs/bin/buserver</emphasis> <emphasis role="bold">-noauth</emphasis>
</programlisting></para>
</listitem>
<listitem>
<para>Issue the <emphasis role="bold">bos create</emphasis> command to start the Protection Server. <programlisting>
- # <emphasis role="bold">./bos create</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">ptserver simple /usr/afs/bin/ptserver</emphasis> \
- <emphasis role="bold"> -cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis role="bold">-noauth</emphasis>
+ # <emphasis role="bold">./bos create</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">ptserver simple /usr/afs/bin/ptserver</emphasis> <emphasis role="bold">-noauth</emphasis>
</programlisting></para>
</listitem>
<listitem>
<para>Issue the <emphasis role="bold">bos create</emphasis> command to start the VL Server. <programlisting>
- # <emphasis role="bold">./bos create</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">vlserver simple /usr/afs/bin/vlserver</emphasis> \
- <emphasis role="bold"> -cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis role="bold">-noauth</emphasis>
+ # <emphasis role="bold">./bos create</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">vlserver simple /usr/afs/bin/vlserver</emphasis> <emphasis role="bold">-noauth</emphasis>
</programlisting></para>
</listitem>
</orderedlist></para>
</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 entry for AFS server processes, called either
<emphasis role="bold">afs</emphasis> or
<emphasis role="bold">afs/<replaceable>cell</replaceable></emphasis>.
+ The latter form is preferred since it works regardless of whether
+ your cell name matches your Kerberos realm name and allows multiple
+ AFS cells to be served from a single Kerberos realm.
No user logs in under this identity, but it is used to encrypt the
server tickets that granted to AFS clients for presentation to
server processes during mutual authentication. (The
<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></para>
</listitem>
- <listitem>
- <para><anchor id="LIWQ54" />Issue the
+ <listitem id="LIWQ54">
+ <para>Issue the
<emphasis role="bold">add_principal</emphasis> command to create
Kerberos Database entries called
<emphasis role="bold">admin</emphasis> and
</indexterm>
</listitem>
- <listitem>
- <para><anchor id="LIWQ55" />Issue the <emphasis role="bold">kadmin
+ <listitem id="LIWQ55">
+ <para>Issue the <emphasis role="bold">kadmin
get_principal</emphasis> command to display the <emphasis
role="bold">afs/</emphasis><<replaceable>cell name</replaceable>> entry.
<programlisting>
</listitem>
<listitem>
- <para>Issue the <emphasis role="bold">kadmin quit</emphasis> command to leave <emphasis role="bold">kadmin</emphasis>
+ <para>Issue the <emphasis role="bold">quit</emphasis> command to leave <emphasis role="bold">kadmin</emphasis>
interactive mode. <programlisting>
kadmin: <emphasis role="bold">quit</emphasis>
</programlisting> <indexterm>
</indexterm></para>
</listitem>
- <listitem>
- <para><anchor id="LIWQ57" />Issue the <emphasis role="bold">bos adduser</emphasis> command to add the <emphasis
+ <listitem id="LIWQ57">
+ <para>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>
+ # <emphasis role="bold">./bos adduser</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">admin -noauth</emphasis>
</programlisting>
<indexterm>
<primary>commands</primary>
</indexterm></para>
</listitem>
- <listitem>
- <para><anchor id="LIWQ58" />Issue the
+ <listitem id="LIWQ58">
+ <para>Issue the
<emphasis role="bold">asetkey</emphasis> command to set the AFS
server encryption key in the
<emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> file. This key
<para>asetkey requires the key version number (or kvno) of the
<emphasis role="bold">afs/</emphasis><replaceable>cell</replaceable>
- key. You should have noted this down when creating the key earlier.
- The key version number can also be found by running the
+ key. You should have made note of the kvno when creating the key
+ earlier. The key version number can also be found by running the
<emphasis role="bold">kvno</emphasis> command</para>
<programlisting>
- # <emphasis role="bold">kvno afs/</emphasis><<replaceable>cell name</replaceable>>
+ # <emphasis role="bold">kvno -k /etc/afs.keytab afs/</emphasis><<replaceable>cell name</replaceable>>
</programlisting>
<para>Once the kvno is known, the key can then be extracted using
asetkey</para>
<programlisting>
- # <emphasis role="bold">asetkey</emphasis> <<replaceable>kvno</replaceable>> <emphasis role="bold">/etc/afs.keytab afs/</emphasis><<replaceable>cell name</replaceable>>
+ # <emphasis role="bold">asetkey add</emphasis> <<replaceable>kvno</replaceable>> <emphasis role="bold">/etc/afs.keytab afs/</emphasis><<replaceable>cell name</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="LIWQ59" />Issue the
+ <listitem id="LIWQ59">
+ <para>Issue the
<emphasis role="bold">bos listkeys</emphasis> command to verify that
the key version number for the new key in the
<emphasis role="bold">KeyFile</emphasis> file is the same as the key
<emphasis role="bold">afs/<replaceable>cell name</replaceable></emphasis>
entry, which you displayed in Step <link linkend="LIWQ55">3</link>.
<programlisting>
- # <emphasis role="bold">./bos listkeys</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">-cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis
- role="bold">-noauth</emphasis>
+ # <emphasis role="bold">./bos listkeys</emphasis> <<replaceable>machine 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>
+ </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>
to accept the default.</para>
<programlisting>
- # <emphasis role="bold">pts createuser -name admin -cell</emphasis> <<replaceable>cell name</replaceable>> [<emphasis
+ # <emphasis role="bold">pts createuser -name admin</emphasis> [<emphasis
role="bold">-id</emphasis> <<replaceable>AFS UID</replaceable>>] <emphasis role="bold">-noauth</emphasis>
User admin has id <replaceable>AFS UID</replaceable>
</programlisting>
<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>
membership</emphasis> command to verify the new membership. Membership in the group enables the <emphasis
role="bold">admin</emphasis> user to issue privileged <emphasis role="bold">pts</emphasis> commands and some privileged
<emphasis role="bold">fs</emphasis> commands. <programlisting>
- # <emphasis role="bold">./pts adduser admin system:administrators -cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis
- role="bold">-noauth</emphasis>
- # <emphasis role="bold">./pts membership admin -cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis
- role="bold">-noauth</emphasis>
+ # <emphasis role="bold">./pts adduser admin system:administrators</emphasis> <emphasis role="bold">-noauth</emphasis>
+ # <emphasis role="bold">./pts membership admin</emphasis> <emphasis role="bold">-noauth</emphasis>
Groups admin (id: 1) is a member of:
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>
<listitem>
<para>Issue the <emphasis role="bold">bos restart</emphasis> command with the <emphasis role="bold">-all</emphasis> flag
to restart the database server processes, so that they start using the new server encryption key. <programlisting>
- # <emphasis role="bold">./bos restart</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">-all -cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis
- role="bold">-noauth</emphasis>
+ # <emphasis role="bold">./bos restart</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">-all</emphasis>
+ <emphasis role="bold">-noauth</emphasis>
</programlisting></para>
</listitem>
</orderedlist>
</sect1>
<sect1 id="HDRWQ60">
- <title>Starting the File Server, Volume Server, and Salvager</title>
-
- <para>Start the <emphasis role="bold">fs</emphasis> process, which consists of the File Server, Volume Server, and Salvager
- (<emphasis role="bold">fileserver</emphasis>, <emphasis role="bold">volserver</emphasis> and <emphasis
- role="bold">salvager</emphasis> processes). <orderedlist>
+ <title>Starting the File Server processes</title>
+
+ <para>Start either the <emphasis role="bold">fs</emphasis> process or, if you want to run the Demand-Attach File Server, the
+ <emphasis role="bold">dafs</emphasis> process. The <emphasis role="bold">fs</emphasis> process consists of the File Server,
+ Volume Server, and Salvager (<emphasis role="bold">fileserver</emphasis>, <emphasis role="bold">volserver</emphasis> and
+ <emphasis role="bold">salvager</emphasis> processes). The <emphasis role="bold">dafs</emphasis> process consists of the
+ Demand-Attach File Server, Volume Server, Salvage Server, and Salvager (<emphasis role="bold">dafileserver</emphasis>,
+ <emphasis role="bold"> davolserver</emphasis>, <emphasis role="bold">salvageserver</emphasis>, and <emphasis
+ role="bold">dasalvager</emphasis> processes). For information about the Demand-Attach File Server and to see whether or not
+ you should run it, see <link linkend="DAFS">Appendix C, The Demand-Attach File Server</link>.
+ <orderedlist>
<listitem>
<para>Issue the <emphasis role="bold">bos create</emphasis> command to start the <emphasis role="bold">fs</emphasis>
- process. The command appears here on multiple lines only for legibility. <programlisting>
+ process or the <emphasis role="bold">dafs</emphasis> process. The commands appear here on multiple lines only for legibility.
+
+ <itemizedlist>
+ <listitem>
+ <para>If you are not planning on running the Demand-Attach File Server, create the <emphasis role="bold">fs</emphasis>
+ process:
+ <programlisting>
# <emphasis role="bold">./bos create</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">fs fs /usr/afs/bin/fileserver</emphasis> \
<emphasis role="bold">/usr/afs/bin/volserver /usr/afs/bin/salvager</emphasis> \
- <emphasis role="bold">-cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis role="bold">-noauth</emphasis>
+ <emphasis role="bold">-noauth</emphasis>
</programlisting></para>
+ </listitem>
+ <listitem>
+ <para>If you are planning on running the Demand-Attach File Server, create the <emphasis
+ role="bold">dafs</emphasis> process:
+ <programlisting>
+ # <emphasis role="bold">./bos create</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">dafs dafs /usr/afs/bin/dafileserver</emphasis> \
+ <emphasis role="bold">/usr/afs/bin/davolserver /usr/afs/bin/salvageserver</emphasis> \
+ <emphasis role="bold">/usr/afs/bin/dasalvager</emphasis> <emphasis role="bold">-noauth</emphasis>
+</programlisting></para>
+ </listitem>
+ </itemizedlist>
+ </para>
<para>Sometimes a message about Volume Location Database (VLDB) initialization appears, along with one or more instances
of an error message similar to the following:</para>
<secondary>status</secondary>
</indexterm></para>
- <para>You can verify that the <emphasis role="bold">fs</emphasis> process has started successfully by issuing the
- <emphasis role="bold">bos status</emphasis> command. Its output mentions two <computeroutput>proc
+ <para>You can verify that the <emphasis role="bold">fs</emphasis> or <emphasis role="bold">dafs</emphasis> process has started
+ successfully by issuing the <emphasis role="bold">bos status</emphasis> command. Its output mentions two <computeroutput>proc
starts</computeroutput>.</para>
+ <itemizedlist>
+ <listitem>
+ <para>If you are not running the Demand-Attach File Server:
+
<programlisting>
# <emphasis role="bold">./bos status</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">fs -long -noauth</emphasis>
-</programlisting>
+</programlisting></para></listitem>
+
+ <listitem>
+ <para>If you are running the Demand-Attach File Server:
+ <programlisting>
+ # <emphasis role="bold">./bos status</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">dafs -long -noauth</emphasis>
+</programlisting></para></listitem>
+ </itemizedlist>
+
</listitem>
<listitem>
<programlisting>
# <emphasis role="bold">./vos create</emphasis> <<replaceable>machine name</replaceable>> <<replaceable>partition name</replaceable>> <emphasis
role="bold">root.afs</emphasis> \
- <emphasis role="bold">-cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis role="bold">-noauth</emphasis>
+ <emphasis role="bold">-noauth</emphasis>
</programlisting>
<para>The Volume Server produces a message confirming that it created the volume on the specified partition. You can
syncvldb</emphasis> and <emphasis role="bold">vos syncserv</emphasis> commands to synchronize the VLDB with the
actual state of volumes on the local machine. To follow the progress of the synchronization operation, which can
take several minutes, use the <emphasis role="bold">-verbose</emphasis> flag. <programlisting>
- # <emphasis role="bold">./vos syncvldb</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">-cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis
+ # <emphasis role="bold">./vos syncvldb</emphasis> <<replaceable>machine name</replaceable>> <emphasis
role="bold">-verbose -noauth</emphasis>
- # <emphasis role="bold">./vos syncserv</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">-cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis
+ # <emphasis role="bold">./vos syncserv</emphasis> <<replaceable>machine name</replaceable>> <emphasis
role="bold">-verbose -noauth</emphasis>
</programlisting></para>
process. <programlisting>
# <emphasis role="bold">./bos create</emphasis> <<replaceable>machine name></replaceable> <emphasis role="bold">upserver simple</emphasis> \
<emphasis role="bold">"/usr/afs/bin/upserver -crypt /usr/afs/etc</emphasis> \
- <emphasis role="bold">-clear /usr/afs/bin" -cell</emphasis> <<replaceable>cell name</replaceable>> <emphasis
- role="bold">-noauth</emphasis>
+ <emphasis role="bold">-clear /usr/afs/bin"</emphasis> <emphasis role="bold">-noauth</emphasis>
</programlisting></para>
</listitem>
</orderedlist></para>
</sect1>
<sect1 id="HDRWQ62">
- <title>Starting the Controller for NTPD</title>
+ <title>Clock Sync Considerations</title>
<para>Keeping the clocks on all server and client machines in your cell synchronized is crucial to several functions, and in
particular to the correct operation of AFS's distributed database technology, Ubik. The chapter in the <emphasis>OpenAFS
Administration Guide</emphasis> about administering server machines explains how time skew can disturb Ubik's performance and
cause service outages in your cell.</para>
- <para>Historically, AFS used to distribute its own version of the Network
-Time Protocol Daemon. Whilst this is still provided for existing sites, we
-recommend that you configure and install your time service independently of
-AFS. A reliable timeservice will also be required by your Kerberos realm,
-and so may already be available at your site.</para>
+ <para>You should install and configure your time service independently of
+ AFS. Your Kerberos realm will also require a reliable time source, so your site
+ may already have one available.</para>
<indexterm>
<primary>overview</primary>
<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,
192.12.105.3 #db1.example.com
192.12.105.4 #db2.example.com
192.12.105.55 #db3.example.com
- >stateu.edu #State University cell
- 138.255.68.93 #serverA.stateu.edu
- 138.255.68.72 #serverB.stateu.edu
- 138.255.33.154 #serverC.stateu.edu
+ >example.org #Example Organization cell
+ 138.255.68.93 #serverA.example.org
+ 138.255.68.72 #serverB.example.org
+ 138.255.33.154 #serverC.example.org
</programlisting>
<indexterm>
<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
role="bold">system:administrators</emphasis> group. It is a default entry that AFS places on every new volume's root
directory.</para>
+ <para>The top-level AFS directory, typically /afs, is a special case:
+ when the client is configured to run in dynroot mode (e.g.
+ <emphasis role="bold">afsd -dynroot</emphasis>, attempts to set
+ the ACL on this directory will return <emphasis role="bold">
+ Connection timed out</emphasis>. This is because the dynamically-
+ generated root directory is not a part of the global AFS space,
+ and cannot have an access control list set on it.</para>
+
<programlisting>
# <emphasis role="bold">/usr/afs/bin/fs setacl /afs system:anyuser rl</emphasis>
</programlisting>
</indexterm>
</listitem>
- <listitem>
- <para><anchor id="LIWQ81" />Issue the <emphasis role="bold">vos create</emphasis> command to create the <emphasis
+ <listitem id="LIWQ81">
+ <para>Issue the <emphasis role="bold">vos create</emphasis> command to create the <emphasis
role="bold">root.cell</emphasis> volume. Then issue the <emphasis role="bold">fs mkmount</emphasis> command to mount it as
a subdirectory of the <emphasis role="bold">/afs</emphasis> directory, where it serves as the root of your cell's local
AFS filespace. Finally, issue the <emphasis role="bold">fs setacl</emphasis> command to create an ACL entry for the
<para>For the <replaceable>partition name</replaceable> argument, substitute the name of one of the machine's AFS server
partitions (such as <emphasis role="bold">/vicepa</emphasis>). For the <replaceable>cellname</replaceable> argument,
- substitute your cell's fully-qualified Internet domain name (such as <emphasis role="bold">abc.com</emphasis>).</para>
+ substitute your cell's fully-qualified Internet domain name (such as <emphasis role="bold">example.com</emphasis>).</para>
<programlisting>
# <emphasis role="bold">/usr/afs/bin/vos create</emphasis> <<replaceable>machine name</replaceable>> <<replaceable>partition name</replaceable>> <emphasis
<listitem>
<para><emphasis role="bold">(Optional)</emphasis> Create a symbolic link to a shortened cell name, to reduce the length of
- pathnames for users in the local cell. For example, in the <emphasis role="bold">abc.com</emphasis> cell, <emphasis
- role="bold">/afs/abc</emphasis> is a link to <emphasis role="bold">/afs/abc.com</emphasis>. <programlisting>
+ pathnames for users in the local cell. For example, in the <emphasis role="bold">example.com</emphasis> cell, <emphasis
+ role="bold">/afs/example</emphasis> is a link to <emphasis role="bold">/afs/example.com</emphasis>. <programlisting>
# <emphasis role="bold">cd /afs</emphasis>
# <emphasis role="bold">ln -s</emphasis> <replaceable>full_cellname</replaceable> <replaceable>short_cellname</replaceable>
</programlisting> <indexterm>
</indexterm>
</listitem>
- <listitem>
- <para><anchor id="LIWQ82" />Issue the <emphasis role="bold">vos addsite</emphasis> command to define a replication site
+ <listitem id="LIWQ82">
+ <para>Issue the <emphasis role="bold">vos addsite</emphasis> command to define a replication site
for both the <emphasis role="bold">root.afs</emphasis> and <emphasis role="bold">root.cell</emphasis> volumes. In each
case, substitute for the <replaceable>partition name</replaceable> argument the partition where the volume's read/write
version resides. When you install additional file server machines, it is a good idea to create replication sites on them
<tertiary>volume for AFS binaries</tertiary>
</indexterm>
- <listitem>
- <para><anchor id="LIWQ84" />Issue the <emphasis role="bold">vos create</emphasis> command to create volumes for storing
+ <listitem id="LIWQ84">
+ <para>Issue the <emphasis role="bold">vos create</emphasis> command to create volumes for storing
the AFS client binaries for this system type. The following example instruction creates volumes called
<replaceable>sysname</replaceable>, <replaceable>sysname</replaceable>.<emphasis role="bold">usr</emphasis>, and
<replaceable>sysname</replaceable>.<emphasis role="bold">usr.afsws</emphasis>. Refer to the <emphasis>OpenAFS Release
</indexterm></para>
</listitem>
- <listitem>
- <para><anchor id="LIWQ85" />Issue the <emphasis role="bold">fs setquota</emphasis> command to set an unlimited quota on
+ <listitem id="LIWQ85">
+ <para>Issue the <emphasis role="bold">fs setquota</emphasis> command to set an unlimited quota on
the volume mounted at the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/usr/afsws</emphasis> directory. This
enables you to copy all of the appropriate files from the CD-ROM into the volume without exceeding the volume's
</indexterm></para>
</listitem>
- <listitem>
- <para><anchor id="LIWQ86" />Create <emphasis role="bold">/usr/afsws</emphasis> on the local disk as a symbolic link to the
+ <listitem id="LIWQ86">
+ <para>Create <emphasis role="bold">/usr/afsws</emphasis> on the local disk as a symbolic link to the
directory <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
role="bold">/@sys/usr/afsws</emphasis>. You can specify the actual system name instead of <emphasis
role="bold">@sys</emphasis> if you wish, but the advantage of using <emphasis role="bold">@sys</emphasis> is that it
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,
</indexterm>
</listitem>
- <listitem>
- <para><anchor id="LIWQ92" />If this machine is going to remain an AFS client after you complete the installation, verify
+ <listitem id="LIWQ92">
+ <para>If this machine is going to remain an AFS client after you complete the installation, verify
that the local <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file includes an entry for each foreign
cell.</para>
# <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>
git://git.openafs.org / openafs.git / blobdiff