<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 NTP, or similar, time service deployed to ensure
- rough clock syncronistation between your clients and servers. If you
- wish to use AFS's built in timeservice (which is deprecated) please
- see Appendix B for the necessary modifications to this installation
- procedure.</para>
+ <para>You have NTP or a similar time service deployed to ensure
+ rough clock syncronistation between your clients and servers.</para>
</listitem>
</itemizedlist></para>
<para>To continue, proceed to the appropriate section: <itemizedlist>
<listitem>
- <para><link linkend="HDRWQ21">Getting Started on AIX Systems</link></para>
- </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>
+ <para><link linkend="HDRWQ41">Getting Started on Linux Systems</link></para>
</listitem>
<listitem>
- <para><link linkend="HDRWQ41">Getting Started on Linux Systems</link></para>
+ <para><link linkend="HDRWQ45">Getting Started on Solaris Systems</link></para>
</listitem>
<listitem>
- <para><link linkend="HDRWQ45">Getting Started on Solaris Systems</link></para>
+ <para><link linkend="HDRWQ21">Getting Started on AIX Systems</link></para>
</listitem>
</itemizedlist></para>
</sect1>
- <sect1 id="HDRWQ21">
- <title>Getting Started on AIX Systems</title>
+ <sect1 id="HDRWQ41">
+ <title>Getting Started on Linux Systems</title>
+
+ <indexterm>
+ <primary>replacing fsck program</primary>
+
+ <secondary>not necessary on Linux</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>fsck program</primary>
+
+ <secondary>on first AFS machine</secondary>
+
+ <tertiary>Linux</tertiary>
+ </indexterm>
+
+ <indexterm>
+ <primary>first AFS machine</primary>
+
+ <secondary>fsck program</secondary>
+
+ <tertiary>on Linux</tertiary>
+ </indexterm>
- <para>Begin by running the AFS initialization script to call the AIX kernel extension facility, which dynamically loads AFS
- modifications into the kernel. Then use the <emphasis role="bold">SMIT</emphasis> program to configure partitions for storing
- AFS volumes, and replace the AIX <emphasis role="bold">fsck</emphasis> program helper with a version that correctly handles AFS
- volumes. If the machine is to remain an AFS client machine, incorporate AFS into the AIX secondary authentication system.
<indexterm>
+ <primary>Linux</primary>
+
+ <secondary>fsck program replacement not necessary</secondary>
+ </indexterm>
+
+ <para>Since this guide was originally written, the procedure for starting
+ OpenAFS has diverged significantly between different Linux distributions.
+ The instructions that follow are appropriate for both the Fedora and
+ 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 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>
- <tertiary>AIX</tertiary>
+ <tertiary>Linux</tertiary>
</indexterm> <indexterm>
<primary>AFS kernel extensions</primary>
<secondary>on first AFS machine</secondary>
- <tertiary>AIX</tertiary>
+ <tertiary>Linux</tertiary>
</indexterm> <indexterm>
<primary>first AFS machine</primary>
<secondary>AFS kernel extensions</secondary>
- <tertiary>on AIX</tertiary>
+ <tertiary>on Linux</tertiary>
</indexterm> <indexterm>
- <primary>AIX</primary>
+ <primary>Linux</primary>
<secondary>AFS kernel extensions</secondary>
<tertiary>on first AFS machine</tertiary>
</indexterm></para>
- <sect2 id="HDRWQ22">
- <title>Loading AFS into the AIX Kernel</title>
+ <sect2 id="HDRWQ42">
+ <title>Loading AFS into the Linux Kernel</title>
- <para>The AIX kernel extension facility is the dynamic kernel loader
- provided by IBM Corporation. AIX does not support incorporation of
- AFS modifications during a kernel build.</para>
+ <para>The <emphasis role="bold">modprobe</emphasis> program is the dynamic kernel loader for Linux. Linux does not support
+ incorporation of AFS modifications during a kernel build.</para>
- <para>For AFS to function correctly, the kernel extension facility must run each time the machine reboots, so the AFS
- initialization script (included in the AFS distribution) invokes it automatically. In this section you copy the script to the
- conventional location and edit it to select the appropriate options depending on whether NFS is also to run.</para>
+ <para>For AFS to function correctly, the <emphasis role="bold">modprobe</emphasis> program must run each time the machine
+ reboots, so your distribution's AFS initialization script invokes it automatically. The script also includes
+ commands that select the appropriate AFS library file automatically. In this section you run the script.</para>
- <para>After editing the script, you run it to incorporate AFS into the kernel. In later sections you verify that the script
- correctly initializes all AFS components, then configure the AIX <emphasis role="bold">inittab</emphasis> file so that the
- script runs automatically at reboot. <orderedlist>
+ <para>In later sections you verify that the script correctly initializes all AFS components, then activate a configuration
+ variable, which results in the script being incorporated into the Linux startup and shutdown sequence.</para>
+
+ <para>The procedure for starting up OpenAFS depends upon your distribution</para>
+ <sect3>
+ <title>Fedora and RedHat Enterprise Linux</title>
+ <para>OpenAFS 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>Unpack the distribution tarball. The examples below assume
- that you have unpacked the files into the
- <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you
- pick a different location, substitute this in all of the following
- examples. Once you have unpacked the distribution,
+ <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
+ as described later in this guide
+ <listitem>
+ <para>Run the AFS initialization script to load AFS extensions into
+ the kernel. You can ignore any error messages about the inability
+ to start the BOS Server or the Cache Manager or AFS client.</para>
+<programlisting>
+ # <emphasis role="bold">/etc/rc.d/init.d/openafs-client start</emphasis>
+</programlisting>
+ </listitem>
+-->
+ </orderedlist>
+ </para>
+ </sect3>
+ <sect3>
+ <title>Systems packaged as tar files</title>
+ <para>If you are running a system where the OpenAFS Binary Distribution
+ is provided as a tar file, or where you have built the system from
+ source yourself, you need to install the relevant components by hand
+ </para>
+ <orderedlist>
+
+ <listitem>
+ <para>Unpack the distribution tarball. The examples below assume
+ that you have unpacked the files into the
+ <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you
+ pick a different location, substitute this in all of the following
+ examples. Once you have unpacked the distribution,
change directory as indicated.
<programlisting>
- # <emphasis role="bold">cd /tmp/afsdist/rs_aix42/root.client/usr/vice/etc</emphasis>
+ # <emphasis role="bold">cd /tmp/afsdist/linux/dest/root.client/usr/vice/etc</emphasis>
</programlisting></para>
</listitem>
-
+
<listitem>
- <para>Copy the AFS kernel library files to the local <emphasis role="bold">/usr/vice/etc/dkload</emphasis> directory,
- and the AFS initialization script to the <emphasis role="bold">/etc</emphasis> directory. <programlisting>
- # <emphasis role="bold">cp -rp dkload /usr/vice/etc</emphasis>
- # <emphasis role="bold">cp -p rc.afs /etc/rc.afs</emphasis>
+ <para>Copy the AFS kernel library files to the local <emphasis role="bold">/usr/vice/etc/modload</emphasis> directory.
+ The filenames for the libraries have the format <emphasis
+ role="bold">libafs-</emphasis><replaceable>version</replaceable><emphasis role="bold">.o</emphasis>, where
+ <replaceable>version</replaceable> indicates the kernel build level. The string <emphasis role="bold">.mp</emphasis> in
+ the <replaceable>version</replaceable> indicates that the file is appropriate for machines running a multiprocessor
+ kernel. <programlisting>
+ # <emphasis role="bold">cp -rp modload /usr/vice/etc</emphasis>
</programlisting></para>
</listitem>
<listitem>
- <para>Edit the <emphasis role="bold">/etc/rc.afs</emphasis> script, setting the <computeroutput>NFS</computeroutput>
- variable as indicated.</para>
-
- <para>If the machine is not to function as an NFS/AFS Translator, set the <computeroutput>NFS</computeroutput> variable
- as follows.</para>
-
- <programlisting>
- NFS=$NFS_NONE
-</programlisting>
-
- <para>If the machine is to function as an NFS/AFS Translator and is running AIX 4.2.1 or higher, set the
- <computeroutput>NFS</computeroutput> variable as follows. Note that NFS must already be loaded into the kernel, which
- happens automatically on systems running AIX 4.1.1 and later, as long as the file <emphasis
- role="bold">/etc/exports</emphasis> exists.</para>
-
- <programlisting>
- NFS=$NFS_IAUTH
-</programlisting>
+ <para>Copy the AFS initialization script to the local directory for initialization files (by convention, <emphasis
+ role="bold">/etc/rc.d/init.d</emphasis> on Linux machines). Note the removal of the <emphasis role="bold">.rc</emphasis>
+ extension as you copy the script. <programlisting>
+ # <emphasis role="bold">cp -p afs.rc /etc/rc.d/init.d/afs</emphasis>
+</programlisting></para>
</listitem>
+<!-- I don't think we need to do this for Linux, and it complicates things if
+ dynroot is enabled ...
<listitem>
- <para>Invoke the <emphasis role="bold">/etc/rc.afs</emphasis> script to load AFS modifications into the kernel. You can
- ignore any error messages about the inability to start the BOS Server or the Cache Manager or AFS client.
- <programlisting>
- # <emphasis role="bold">/etc/rc.afs</emphasis>
-</programlisting></para>
+ <para>Run the AFS initialization script to load AFS extensions into the kernel. You can ignore any error messages about
+ the inability to start the BOS Server or the Cache Manager or AFS client.</para>
+<programlisting>
+ # <emphasis role="bold">/etc/rc.d/init.d/afs start</emphasis>
+</programlisting>
</listitem>
- </orderedlist></para>
+-->
+ </orderedlist>
<indexterm>
<primary>configuring</primary>
-
+
<secondary>AFS server partition on first AFS machine</secondary>
- <tertiary>AIX</tertiary>
+ <tertiary>Linux</tertiary>
</indexterm>
<indexterm>
<secondary>configuring on first AFS machine</secondary>
- <tertiary>AIX</tertiary>
+ <tertiary>Linux</tertiary>
</indexterm>
<indexterm>
<secondary>AFS server partition</secondary>
- <tertiary>on AIX</tertiary>
+ <tertiary>on Linux</tertiary>
</indexterm>
<indexterm>
- <primary>AIX</primary>
+ <primary>Linux</primary>
<secondary>AFS server partition</secondary>
<tertiary>on first AFS machine</tertiary>
</indexterm>
+ </sect3>
</sect2>
- <sect2 id="HDRWQ23">
- <title>Configuring Server Partitions on AIX Systems</title>
+ <sect2 id="HDRWQ43">
+ <title>Configuring Server Partitions on Linux 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>To configure server partitions on an AIX system, perform the following procedures: <orderedlist>
+ 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>
</listitem>
<listitem>
- <para>Use the <emphasis role="bold">SMIT</emphasis> program to create a journaling file system on each partition to be
- configured as an AFS server partition.</para>
+ <para>Add a line with the following format to the file systems registry file, <emphasis
+ role="bold">/etc/fstab</emphasis>, for each directory just created. The entry maps the directory name to the disk
+ partition to be mounted on it. <programlisting>
+ /dev/<replaceable>disk</replaceable> /vicep<replaceable>xx</replaceable> ext2 defaults 0 2
+</programlisting></para>
+
+ <para>The following is an example for the first partition being configured.</para>
+
+ <programlisting>
+ /dev/sda8 /vicepa ext2 defaults 0 2
+</programlisting>
</listitem>
<listitem>
- <para>Mount each partition at one of the <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>
- directories. Choose one of the following three methods: <itemizedlist>
- <listitem>
- <para>Use the <emphasis role="bold">SMIT</emphasis> program</para>
- </listitem>
-
- <listitem>
- <para>Use the <emphasis role="bold">mount -a</emphasis> command to mount all partitions at once</para>
- </listitem>
-
- <listitem>
- <para>Use the <emphasis role="bold">mount</emphasis> command on each partition in turn</para>
- </listitem>
- </itemizedlist></para>
-
- <para>Also configure the partitions so that they are mounted automatically at each reboot. For more information, refer
- to the AIX documentation.</para>
+ <para>Create a file system on each partition that is to be mounted at a <emphasis
+ role="bold">/vicep</emphasis><replaceable>xx</replaceable> directory. The following command is probably appropriate, but
+ consult the Linux documentation for more information. <programlisting>
+ # <emphasis role="bold">mkfs -v /dev/</emphasis><replaceable>disk</replaceable>
+</programlisting></para>
</listitem>
- </orderedlist></para>
-
- <indexterm>
- <primary>replacing fsck program</primary>
-
- <secondary>first AFS machine</secondary>
-
- <tertiary>AIX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>fsck program</primary>
-
- <secondary>on first AFS machine</secondary>
-
- <tertiary>AIX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>first AFS machine</primary>
-
- <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>
+ <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>
<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
+ linkend="HDRWQ44">Enabling AFS Login on Linux Systems</link>. Otherwise, proceed to <link linkend="HDRWQ50">Starting the
BOS Server</link>.</para>
</listitem>
</orderedlist></para>
<secondary>file server machine</secondary>
- <tertiary>AIX</tertiary>
+ <tertiary>Linux</tertiary>
</indexterm>
<indexterm>
<secondary>on file server machine</secondary>
- <tertiary>AIX</tertiary>
+ <tertiary>Linux</tertiary>
</indexterm>
<indexterm>
<secondary>AFS login</secondary>
- <tertiary>on AIX</tertiary>
+ <tertiary>on Linux</tertiary>
</indexterm>
<indexterm>
- <primary>AIX</primary>
+ <primary>Linux</primary>
<secondary>AFS login</secondary>
</indexterm>
<indexterm>
- <primary>secondary authentication system (AIX)</primary>
+ <primary>PAM</primary>
- <secondary>server machine</secondary>
+ <secondary>on Linux</secondary>
+
+ <tertiary>file server machine</tertiary>
</indexterm>
</sect2>
- <sect2 id="HDRWQ25">
- <title>Enabling AFS Login on AIX Systems</title>
+ <sect2 id="HDRWQ44">
+ <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>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>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>
+ <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="HDRWQ31">
- <title>Getting Started on HP-UX Systems</title>
+ <sect1 id="HDRWQ45">
+ <title>Getting Started on Solaris 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>
+ <para>Begin by running the AFS initialization script to call the <emphasis role="bold">modload</emphasis> program distributed by
+ Sun Microsystems, which dynamically loads AFS modifications into the kernel. 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>
+ <tertiary>Solaris</tertiary>
</indexterm> <indexterm>
<primary>AFS kernel extensions</primary>
<secondary>on first AFS machine</secondary>
- <tertiary>HP-UX</tertiary>
+ <tertiary>Solaris</tertiary>
</indexterm> <indexterm>
<primary>first AFS machine</primary>
<secondary>AFS kernel extensions</secondary>
- <tertiary>on HP-UX</tertiary>
+ <tertiary>on Solaris</tertiary>
</indexterm> <indexterm>
- <primary>HP-UX</primary>
+ <primary>Solaris</primary>
- <secondary>AFS-modified kernel</secondary>
+ <secondary>AFS kernel extensions</secondary>
<tertiary>on first AFS machine</tertiary>
</indexterm></para>
- <sect2 id="HDRWQ32">
- <title>Building AFS into the HP-UX Kernel</title>
+ <sect2 id="HDRWQ46">
+ <title>Loading AFS into the Solaris 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>
+ <para>The <emphasis role="bold">modload</emphasis> program is the dynamic kernel loader provided by Sun Microsystems for
+ Solaris systems. Solaris does not support incorporation of AFS modifications during a kernel build.</para>
+
+ <para>For AFS to function correctly, the <emphasis role="bold">modload</emphasis> program must run each time the machine
+ reboots, so the AFS initialization script (included on the AFS CD-ROM) invokes it automatically. In this section you copy the
+ appropriate AFS library file to the location where the <emphasis role="bold">modload</emphasis> program accesses it and then
+ 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 Solaris startup and shutdown sequence. <orderedlist>
<listitem>
- <para>Unpack the OpenAFS HP-UX distribution tarball. The examples
+ <para>Unpack the OpenAFS Solaris distribution tarball. The examples
below assume that you have unpacked the files into the
<emphasis role="bold">/tmp/afsdist</emphasis> directory. If you
- pick a 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>
+ pick a diferent location, substitute this in all of the following
+ exmaples. Once you have unpacked the distribution, change directory
+ as indicated.
+<programlisting>
+ # <emphasis role="bold">cd /tmp/afsdist/sun4x_56/dest/root.client/usr/vice/etc</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>
+ <para>Copy the AFS initialization script to the local directory for initialization files (by convention, <emphasis
+ role="bold">/etc/init.d</emphasis> on Solaris machines). Note the removal of the <emphasis role="bold">.rc</emphasis>
+ extension as you copy the script. <programlisting>
+ # <emphasis role="bold">cp -p afs.rc /etc/init.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>Copy the appropriate AFS kernel library file to the local file <emphasis
+ role="bold">/kernel/fs/afs</emphasis>.</para>
- <para>If the machine's kernel supports NFS server functionality:</para>
+ <para>If the machine is running Solaris 11 on the x86_64 platform:</para>
<programlisting>
- # <emphasis role="bold">cp bin/libafs.a /usr/conf/lib</emphasis>
+ # <emphasis role="bold">cp -p modload/libafs64.o /kernel/drv/amd64/afs</emphasis>
</programlisting>
- <para>If the machine's kernel does not support NFS server functionality, change the file's name as you copy it:</para>
+ <para>If the machine is running Solaris 10 on the x86_64 platform:</para>
<programlisting>
- # <emphasis role="bold">cp bin/libafs.nonfs.a /usr/conf/lib/libafs.a</emphasis>
+ # <emphasis role="bold">cp -p modload/libafs64.o /kernel/fs/amd64/afs</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>
+ <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>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>
+ <programlisting>
+ # <emphasis role="bold">cp -p modload/libafs.o /kernel/fs/afs</emphasis>
+</programlisting>
- <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>
+ <para>If the machine is running Solaris 2.6 or the 32-bit version of Solaris 7, and its kernel does not support NFS
+ server functionality or the <emphasis role="bold">nfsd</emphasis> process is not running:</para>
+
+ <programlisting>
+ # <emphasis role="bold">cp -p modload/libafs.nonfs.o /kernel/fs/afs</emphasis>
+</programlisting>
+
+ <para>If the machine is running the 64-bit version of Solaris 7, its kernel supports NFS server functionality, and the
+ <emphasis role="bold">nfsd</emphasis> process is running:</para>
+
+ <programlisting>
+ # <emphasis role="bold">cp -p modload/libafs64.o /kernel/fs/sparcv9/afs</emphasis>
+</programlisting>
+
+ <para>If the machine is running the 64-bit version of Solaris 7, and its kernel does not support NFS server
+ functionality or the <emphasis role="bold">nfsd</emphasis> process is not running:</para>
+
+ <programlisting>
+ # <emphasis role="bold">cp -p modload/libafs64.nonfs.o /kernel/fs/sparcv9/afs</emphasis>
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>Run the AFS initialization script to load AFS modifications into the kernel. You can ignore any error messages
+ about the inability to start the BOS Server or the Cache Manager or AFS client. <programlisting>
+ # <emphasis role="bold">/etc/init.d/afs start</emphasis>
+</programlisting></para>
+
+ <para>When an entry called <computeroutput>afs</computeroutput> does not already exist in the local <emphasis
+ role="bold">/etc/name_to_sysnum</emphasis> file, the script automatically creates it and reboots the machine to start
+ using the new version of the file. If this happens, log in again as the superuser <emphasis role="bold">root</emphasis>
+ after the reboot and run the initialization script again. This time the required entry exists in the <emphasis
+ role="bold">/etc/name_to_sysnum</emphasis> file, and the <emphasis role="bold">modload</emphasis> program runs.</para>
+
+ <programlisting>
login: <emphasis role="bold">root</emphasis>
Password: <replaceable>root_password</replaceable>
-</programlisting></para>
- </listitem>
- </orderedlist></para>
- </listitem>
- </itemizedlist></para>
+ # <emphasis role="bold">/etc/init.d/afs start</emphasis>
+</programlisting>
</listitem>
</orderedlist></para>
<indexterm>
- <primary>configuring</primary>
+ <primary>replacing fsck program</primary>
- <secondary>AFS server partition on first AFS machine</secondary>
+ <secondary>first AFS machine</secondary>
- <tertiary>HP-UX</tertiary>
+ <tertiary>Solaris</tertiary>
</indexterm>
<indexterm>
- <primary>AFS server partition</primary>
+ <primary>fsck program</primary>
- <secondary>configuring on first AFS machine</secondary>
+ <secondary>on first AFS machine</secondary>
- <tertiary>HP-UX</tertiary>
+ <tertiary>Solaris</tertiary>
</indexterm>
<indexterm>
<primary>first AFS machine</primary>
- <secondary>AFS server partition</secondary>
+ <secondary>fsck program</secondary>
- <tertiary>on HP-UX</tertiary>
+ <tertiary>on Solaris</tertiary>
</indexterm>
<indexterm>
- <primary>HP-UX</primary>
+ <primary>Solaris</primary>
- <secondary>AFS server partition</secondary>
+ <secondary>fsck program</secondary>
<tertiary>on first AFS machine</tertiary>
</indexterm>
</sect2>
- <sect2 id="HDRWQ33">
- <title>Configuring Server Partitions on HP-UX Systems</title>
+ <sect2 id="HDRWQ47">
+ <title>Configuring the AFS-modified fsck Program on Solaris 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>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>
<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>
+ <para>Create the <emphasis role="bold">/usr/lib/fs/afs</emphasis> directory to house the AFS-modified <emphasis
+ role="bold">fsck</emphasis> program and related files. <programlisting>
+ # <emphasis role="bold">mkdir /usr/lib/fs/afs</emphasis>
+ # <emphasis role="bold">cd /usr/lib/fs/afs</emphasis>
+</programlisting></para>
+ </listitem>
+
+ <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/dest/root.server/etc/vfsck fsck</emphasis>
+</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>Working in the <emphasis role="bold">/usr/lib/fs/afs</emphasis> directory, create the following links to Solaris
+ libraries: <programlisting>
+ # <emphasis role="bold">ln -s /usr/lib/fs/ufs/clri</emphasis>
+ # <emphasis role="bold">ln -s /usr/lib/fs/ufs/df</emphasis>
+ # <emphasis role="bold">ln -s /usr/lib/fs/ufs/edquota</emphasis>
+ # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ff</emphasis>
+ # <emphasis role="bold">ln -s /usr/lib/fs/ufs/fsdb</emphasis>
+ # <emphasis role="bold">ln -s /usr/lib/fs/ufs/fsirand</emphasis>
+ # <emphasis role="bold">ln -s /usr/lib/fs/ufs/fstyp</emphasis>
+ # <emphasis role="bold">ln -s /usr/lib/fs/ufs/labelit</emphasis>
+ # <emphasis role="bold">ln -s /usr/lib/fs/ufs/lockfs</emphasis>
+ # <emphasis role="bold">ln -s /usr/lib/fs/ufs/mkfs</emphasis>
+ # <emphasis role="bold">ln -s /usr/lib/fs/ufs/mount</emphasis>
+ # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ncheck</emphasis>
+ # <emphasis role="bold">ln -s /usr/lib/fs/ufs/newfs</emphasis>
+ # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quot</emphasis>
+ # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quota</emphasis>
+ # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quotaoff</emphasis>
+ # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quotaon</emphasis>
+ # <emphasis role="bold">ln -s /usr/lib/fs/ufs/repquota</emphasis>
+ # <emphasis role="bold">ln -s /usr/lib/fs/ufs/tunefs</emphasis>
+ # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ufsdump</emphasis>
+ # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ufsrestore</emphasis>
+ # <emphasis role="bold">ln -s /usr/lib/fs/ufs/volcopy</emphasis>
</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>
+ <para>Append the following line to the end of the file <emphasis role="bold">/etc/dfs/fstypes</emphasis>.
+ <programlisting>
+ afs AFS Utilities
+</programlisting></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>
+ <para>Edit the <emphasis role="bold">/sbin/mountall</emphasis> file, making two changes. <itemizedlist>
+ <listitem>
+ <para>Add an entry for AFS to the <computeroutput>case</computeroutput> statement for option 2, so that it reads
+ as follows: <programlisting>
+ case "$2" in
+ ufs) foptions="-o p"
+ ;;
+ afs) foptions="-o p"
+ ;;
+ s5) foptions="-y -t /var/tmp/tmp$$ -D"
+ ;;
+ *) foptions="-y"
+ ;;
+</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>Edit the file so that all AFS and UFS partitions are checked in parallel. Replace the following section of
+ code: <programlisting>
+ # For fsck purposes, we make a distinction between ufs and
+ # other file systems
+ #
+ if [ "$fstype" = "ufs" ]; then
+ ufs_fscklist="$ufs_fscklist $fsckdev"
+ saveentry $fstype "$OPTIONS" $special $mountp
+ continue
+ fi
+</programlisting></para>
+
+ <para>with the following section of code:</para>
+
+ <programlisting>
+ # For fsck purposes, we make a distinction between ufs/afs
+ # and other file systems.
+ #
+ if [ "$fstype" = "ufs" -o "$fstype" = "afs" ]; then
+ ufs_fscklist="$ufs_fscklist $fsckdev"
+ saveentry $fstype "$OPTIONS" $special $mountp
+ continue
+ fi
+</programlisting>
+ </listitem>
+ </itemizedlist></para>
</listitem>
</orderedlist></para>
<indexterm>
- <primary>replacing fsck program</primary>
+ <primary>configuring</primary>
- <secondary>first AFS machine</secondary>
+ <secondary>AFS server partition on first AFS machine</secondary>
- <tertiary>HP-UX</tertiary>
+ <tertiary>Solaris</tertiary>
</indexterm>
<indexterm>
- <primary>fsck program</primary>
+ <primary>AFS server partition</primary>
- <secondary>on first AFS machine</secondary>
+ <secondary>configuring on first AFS machine</secondary>
- <tertiary>HP-UX</tertiary>
+ <tertiary>Solaris</tertiary>
</indexterm>
<indexterm>
<primary>first AFS machine</primary>
- <secondary>fsck program</secondary>
+ <secondary>AFS server partition</secondary>
- <tertiary>on HP-UX</tertiary>
+ <tertiary>on Solaris</tertiary>
</indexterm>
<indexterm>
- <primary>HP-UX</primary>
+ <primary>Solaris</primary>
- <secondary>fsck program</secondary>
+ <secondary>AFS server partition</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>
+ <sect2 id="HDRWQ48">
+ <title>Configuring Server Partitions on Solaris Systems</title>
- <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>
+ <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 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,
+ <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>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>
+ <para>Add a line with the following format to the file systems registry file, <emphasis
+ role="bold">/etc/vfstab</emphasis>, for each partition to be mounted on a directory created in the previous step. Note
+ the value <computeroutput>afs</computeroutput> in the fourth field, which tells Solaris to use the AFS-modified
+ <emphasis role="bold">fsck</emphasis> program on this partition. <programlisting>
+ /dev/dsk/<replaceable>disk</replaceable> /dev/rdsk/<replaceable>disk</replaceable> /vicep<replaceable>xx</replaceable> afs <replaceable>boot_order</replaceable> yes
</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>
+ <para>The following is an example for the first partition being configured.</para>
+
+ <programlisting>
+ /dev/dsk/c0t6d0s1 /dev/rdsk/c0t6d0s1 /vicepa afs 3 yes
+</programlisting>
</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>
+ <para>Create a file system on each partition that is to be mounted at a <emphasis
+ role="bold">/vicep</emphasis><replaceable>xx</replaceable> directory. The following command is probably appropriate, but
+ consult the Solaris documentation for more information. <programlisting>
+ # <emphasis role="bold">newfs -v /dev/rdsk/</emphasis><replaceable>disk</replaceable>
</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>
+ <para>Issue the <emphasis role="bold">mountall</emphasis> command to mount all partitions at once.</para>
</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>
+ linkend="HDRWQ49">Enabling AFS Login and Editing the File Systems Clean-up Script on Solaris Systems</link>. Otherwise,
+ 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>
<secondary>file server machine</secondary>
- <tertiary>HP-UX</tertiary>
+ <tertiary>Solaris</tertiary>
</indexterm>
<indexterm>
<secondary>on file server machine</secondary>
- <tertiary>HP-UX</tertiary>
+ <tertiary>Solaris</tertiary>
</indexterm>
<indexterm>
<secondary>AFS login</secondary>
- <tertiary>on HP-UX</tertiary>
+ <tertiary>on Solaris</tertiary>
</indexterm>
<indexterm>
- <primary>HP-UX</primary>
+ <primary>Solaris</primary>
<secondary>AFS login</secondary>
<indexterm>
<primary>PAM</primary>
- <secondary>on HP-UX</secondary>
+ <secondary>on Solaris</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>
+ <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>
+ 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>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>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>Sites which still require <emphasis
- role="bold">kaserver</emphasis> or external Kerberos v4
- authentication should consult <link linkend="KAS013">Enabling
- kaserver based AFS login on HP-UX systems</link> for details of how
- to enable HP-UX login.</para>
+ <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>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>
+ <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>
- <sect1 id="HDRWQ36">
- <title>Getting Started on IRIX Systems</title>
+ <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>
- <indexterm>
- <primary>incorporating AFS kernel extensions</primary>
+ <example>
+ <title>Solaris PAM session example</title>
+ <literallayout>login session required pam_afs_session.so</literallayout>
+ </example>
- <secondary>first AFS machine</secondary>
+ <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>
- <tertiary>IRIX</tertiary>
- </indexterm>
+ <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>
- <indexterm>
- <primary>AFS kernel extensions</primary>
+ <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>
- <secondary>on first AFS machine</secondary>
+ <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>IRIX</tertiary>
- </indexterm>
+ <secondary>file systems clean-up script</secondary>
- <indexterm>
- <primary>first AFS machine</primary>
+ <tertiary>on file server machine</tertiary>
+ </indexterm>
- <secondary>AFS kernel extensions</secondary>
+ <indexterm>
+ <primary>file systems clean-up script (Solaris)</primary>
- <tertiary>on IRIX</tertiary>
- </indexterm>
+ <secondary>file server machine</secondary>
+ </indexterm>
- <indexterm>
- <primary>replacing fsck program</primary>
+ <indexterm>
+ <primary>scripts</primary>
- <secondary>not necessary on IRIX</secondary>
- </indexterm>
+ <secondary>file systems clean-up (Solaris)</secondary>
- <indexterm>
- <primary>fsck program</primary>
+ <tertiary>file server machine</tertiary>
+ </indexterm>
- <secondary>on first AFS machine</secondary>
+
+ <orderedlist>
+ <listitem>
+ <para>Some Solaris distributions include a script that locates and removes unneeded files from various file systems. Its
+ conventional location is <emphasis role="bold">/usr/lib/fs/nfs/nfsfind</emphasis>. The script generally uses an argument
+ to the <emphasis role="bold">find</emphasis> command to define which file systems to search. In this step you modify the
+ command to exclude the <emphasis role="bold">/afs</emphasis> directory. Otherwise, the command traverses the AFS
+ filespace of every cell that is accessible from the machine, which can take many hours. The following alterations are
+ possibilities, but you must verify that they are appropriate for your cell.</para>
- <tertiary>IRIX</tertiary>
- </indexterm>
+ <para>The first possible alteration is to add the <emphasis role="bold">-local</emphasis> flag to the existing command,
+ so that it looks like the following:</para>
- <indexterm>
- <primary>first AFS machine</primary>
+ <programlisting>
+ find $dir -local -name .nfs\* -mtime +7 -mount -exec rm -f {} \;
+</programlisting>
- <secondary>fsck program</secondary>
+ <para>Another alternative is to exclude any directories whose names begin with the lowercase letter <emphasis
+ role="bold">a</emphasis> or a non-alphabetic character.</para>
- <tertiary>on IRIX</tertiary>
- </indexterm>
+ <programlisting>
+ find /[A-Zb-z]* <replaceable>remainder of existing command</replaceable>
+</programlisting>
- <indexterm>
- <primary>IRIX</primary>
+ <para>Do not use the following command, which still searches under the <emphasis role="bold">/afs</emphasis> directory,
+ looking for a subdirectory of type <emphasis role="bold">4.2</emphasis>.</para>
- <secondary>fsck program replacement not necessary</secondary>
- </indexterm>
+ <programlisting>
+ find / -fstype 4.2 /* <replaceable>do not use</replaceable> */
+</programlisting>
+ </listitem>
- <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>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>
- <listitem>
- <para>Build a new static kernel</para>
- </listitem>
- </itemizedlist></para>
+ <indexterm>
+ <primary>Basic OverSeer Server</primary>
- <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>
+ <see>BOS Server</see>
+ </indexterm>
- <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>
+ <indexterm>
+ <primary>BOS Server</primary>
- <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>
+ <secondary>starting</secondary>
- <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>
+ <tertiary>first AFS machine</tertiary>
+ </indexterm>
- <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>starting</primary>
- <indexterm>
- <primary>IRIX</primary>
+ <secondary>BOS Server</secondary>
- <secondary>AFS kernel extensions</secondary>
+ <tertiary>first AFS machine</tertiary>
+ </indexterm>
- <tertiary>on first AFS machine</tertiary>
- </indexterm>
+ <indexterm>
+ <primary>first AFS machine</primary>
- <indexterm>
- <primary>afsml variable (IRIX)</primary>
+ <secondary>BOS Server</secondary>
+ </indexterm>
- <secondary>first AFS machine</secondary>
- </indexterm>
+ <indexterm>
+ <primary>authorization checking (disabling)</primary>
- <indexterm>
- <primary>variables</primary>
+ <secondary>first AFS machine</secondary>
+ </indexterm>
- <secondary>afsml (IRIX)</secondary>
+ <indexterm>
+ <primary>disabling authorization checking</primary>
- <tertiary>first AFS machine</tertiary>
- </indexterm>
+ <secondary>first AFS machine</secondary>
+ </indexterm>
- <indexterm>
- <primary>IRIX</primary>
+ <indexterm>
+ <primary>first AFS machine</primary>
- <secondary>afsml variable</secondary>
+ <secondary>authorization checking (disabling)</secondary>
+ </indexterm>
+ </sect2>
+ </sect1>
- <tertiary>first AFS machine</tertiary>
- </indexterm>
+ <sect1 id="HDRWQ21">
+ <title>Getting Started on AIX Systems</title>
+ <para>Begin by running the AFS initialization script to call the AIX kernel extension facility, which dynamically loads AFS
+ modifications into the kernel. Then use the <emphasis role="bold">SMIT</emphasis> program to configure partitions for storing
+ AFS volumes, and replace the AIX <emphasis role="bold">fsck</emphasis> program helper with a version that correctly handles AFS
+ volumes. If the machine is to remain an AFS client machine, incorporate AFS into the AIX secondary authentication system.
<indexterm>
- <primary>afsxnfs variable (IRIX)</primary>
+ <primary>incorporating AFS kernel extensions</primary>
- <secondary>first AFS machine</secondary>
- </indexterm>
+ <secondary>first AFS machine</secondary>
- <indexterm>
- <primary>variables</primary>
+ <tertiary>AIX</tertiary>
+ </indexterm> <indexterm>
+ <primary>AFS kernel extensions</primary>
- <secondary>afsxnfs (IRIX)</secondary>
+ <secondary>on first AFS machine</secondary>
- <tertiary>first AFS machine</tertiary>
- </indexterm>
+ <tertiary>AIX</tertiary>
+ </indexterm> <indexterm>
+ <primary>first AFS machine</primary>
- <indexterm>
- <primary>IRIX</primary>
+ <secondary>AFS kernel extensions</secondary>
- <secondary>afsxnfs variable</secondary>
+ <tertiary>on AIX</tertiary>
+ </indexterm> <indexterm>
+ <primary>AIX</primary>
- <tertiary>first AFS machine</tertiary>
- </indexterm>
+ <secondary>AFS kernel extensions</secondary>
- <sect2 id="HDRWQ37">
- <title>Loading AFS into the IRIX Kernel</title>
+ <tertiary>on first AFS machine</tertiary>
+ </indexterm></para>
- <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>
+ <sect2 id="HDRWQ22">
+ <title>Loading AFS into the AIX Kernel</title>
- <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>
+ <para>The AIX kernel extension facility is the dynamic kernel loader
+ provided by IBM Corporation. AIX does not support incorporation of
+ AFS modifications during a kernel build.</para>
+
+ <para>For AFS to function correctly, the kernel extension facility must run each time the machine reboots, so the AFS
+ initialization script (included in the AFS distribution) invokes it automatically. In this section you copy the script to the
+ conventional location and edit it to select the appropriate options depending on whether NFS is also to run.</para>
+
+ <para>After editing the script, you run it to incorporate AFS into the kernel. In later sections you verify that the script
+ correctly initializes all AFS components, then configure the AIX <emphasis role="bold">inittab</emphasis> file so that the
+ script runs automatically at reboot. <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>
+ <para>Unpack the distribution tarball. The examples below assume
+ that you have unpacked the files into the
+ <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you
+ pick a different location, substitute this in all of the following
+ examples. Once you have unpacked the distribution,
+ change directory as indicated.
+<programlisting>
+ # <emphasis role="bold">cd /tmp/afsdist/rs_aix42/dest/root.client/usr/vice/etc</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>Copy the AFS kernel library files to the local <emphasis role="bold">/usr/vice/etc/dkload</emphasis> directory,
+ and the AFS initialization script to the <emphasis role="bold">/etc</emphasis> directory. <programlisting>
+ # <emphasis role="bold">cp -rp dkload /usr/vice/etc</emphasis>
+ # <emphasis role="bold">cp -p rc.afs /etc/rc.afs</emphasis>
+</programlisting></para>
+ </listitem>
- <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>
+ <listitem>
+ <para>Edit the <emphasis role="bold">/etc/rc.afs</emphasis> script, setting the <computeroutput>NFS</computeroutput>
+ variable as indicated.</para>
- <para>If the machine's kernel supports NFS server functionality:</para>
+ <para>If the machine is not to function as an NFS/AFS Translator, set the <computeroutput>NFS</computeroutput> variable
+ as follows.</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>
+ NFS=$NFS_NONE
</programlisting>
- <para>If the machine's kernel does not support NFS server functionality:</para>
+ <para>If the machine is to function as an NFS/AFS Translator and is running AIX 4.2.1 or higher, set the
+ <computeroutput>NFS</computeroutput> variable as follows. Note that NFS must already be loaded into the kernel, which
+ happens automatically on systems running AIX 4.1.1 and later, as long as the file <emphasis
+ role="bold">/etc/exports</emphasis> exists.</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>
+ NFS=$NFS_IAUTH
</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>
+ <para>Invoke the <emphasis role="bold">/etc/rc.afs</emphasis> script to load AFS modifications into the kernel. You can
+ ignore any error messages about the inability to start the BOS Server or the Cache Manager or AFS client.
+ <programlisting>
+ # <emphasis role="bold">/etc/rc.afs</emphasis>
</programlisting></para>
+ </listitem>
+ </orderedlist></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>
-
- <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>
-
- <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>
-
- <programlisting>
- # <emphasis role="bold">mkfs -t xfs -i size=512 -l size=4000b</emphasis> <replaceable>raw_device</replaceable>
-</programlisting>
-
- <para>For EFS file systems:</para>
-
- <programlisting>
- # <emphasis role="bold">mkfs -t efs</emphasis> <replaceable>raw_device</replaceable>
-</programlisting>
- </listitem>
-
- <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>
-
- <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>
-</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
- BOS Server</link>.</para>
- </listitem>
- </orderedlist></para>
-
- <indexterm>
- <primary>enabling AFS login</primary>
-
- <secondary>file server machine</secondary>
-
- <tertiary>IRIX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>AFS login</primary>
-
- <secondary>on file server machine</secondary>
-
- <tertiary>IRIX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>first AFS machine</primary>
-
- <secondary>AFS login</secondary>
-
- <tertiary>on IRIX</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>IRIX</primary>
-
- <secondary>AFS login</secondary>
- </indexterm>
- </sect2>
-
- <sect2 id="HDRWQ40">
- <title>Enabling AFS Login on IRIX 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.</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>Sites which still require <emphasis role="bold">kaserver</emphasis>
- or external Kerberos v4 authentication should consult
- <link linkend="KAS014">Enabling kaserver based AFS Login on IRIX Systems</link>
- for details of how to enable IRIX login.</para>
-
- <para>After taking any necessary action, proceed to
- <link linkend="HDRWQ50">Starting the BOS Server</link>.</para>
- </sect2>
- </sect1>
-
- <sect1 id="HDRWQ41">
- <title>Getting Started on Linux Systems</title>
-
- <indexterm>
- <primary>replacing fsck program</primary>
-
- <secondary>not necessary on Linux</secondary>
- </indexterm>
-
- <indexterm>
- <primary>fsck program</primary>
-
- <secondary>on first AFS machine</secondary>
-
- <tertiary>Linux</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>first AFS machine</primary>
-
- <secondary>fsck program</secondary>
-
- <tertiary>on Linux</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>Linux</primary>
-
- <secondary>fsck program replacement not necessary</secondary>
- </indexterm>
-
- <para>Since this guide was originally written, the procedure for starting
- OpenAFS has diverged significantly between different Linux distributions.
- The instructions that follow are appropriate for both the Fedora and
- 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 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>
-
- <tertiary>Linux</tertiary>
- </indexterm> <indexterm>
- <primary>AFS kernel extensions</primary>
-
- <secondary>on first AFS machine</secondary>
-
- <tertiary>Linux</tertiary>
- </indexterm> <indexterm>
- <primary>first AFS machine</primary>
-
- <secondary>AFS kernel extensions</secondary>
-
- <tertiary>on Linux</tertiary>
- </indexterm> <indexterm>
- <primary>Linux</primary>
-
- <secondary>AFS kernel extensions</secondary>
-
- <tertiary>on first AFS machine</tertiary>
- </indexterm></para>
-
- <sect2 id="HDRWQ42">
- <title>Loading AFS into the Linux Kernel</title>
-
- <para>The <emphasis role="bold">modprobe</emphasis> program is the dynamic kernel loader for Linux. Linux does not support
- incorporation of AFS modifications during a kernel build.</para>
-
- <para>For AFS to function correctly, the <emphasis role="bold">modprobe</emphasis> program must run each time the machine
- reboots, so your distribution's AFS initialization script invokes it automatically. The script also includes
- commands that select the appropriate AFS library file automatically. In this section you run the script.</para>
-
- <para>In later sections you verify that the script correctly initializes all AFS components, then activate a configuration
- variable, which results in the script being incorporated into the Linux startup and shutdown sequence.</para>
-
- <para>The procedure for starting up OpenAFS depends upon your distribution</para>
- <sect3>
- <title>Fedora and RedHat Enterprise Linux</title>
- <para>OpenAFS 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>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
- as described later in this guide
- <listitem>
- <para>Run the AFS initialization script to load AFS extensions into
- the kernel. You can ignore any error messages about the inability
- to start the BOS Server or the Cache Manager or AFS client.</para>
-<programlisting>
- # <emphasis role="bold">/etc/rc.d/init.d/openafs-client start</emphasis>
-</programlisting>
- </listitem>
--->
- </orderedlist>
- </para>
- </sect3>
- <sect3>
- <title>Systems packaged as tar files</title>
- <para>If you are running a system where the OpenAFS Binary Distribution
- is provided as a tar file, or where you have built the system from
- source yourself, you need to install the relevant components by hand
- </para>
- <orderedlist>
-
- <listitem>
- <para>Unpack the distribution tarball. The examples below assume
- that you have unpacked the files into the
- <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you
- pick a different location, substitute this in all of the following
- examples. Once you have unpacked the distribution,
- change directory as indicated.
-<programlisting>
- # <emphasis role="bold">cd /tmp/afsdist/linux/root.client/usr/vice/etc</emphasis>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Copy the AFS kernel library files to the local <emphasis role="bold">/usr/vice/etc/modload</emphasis> directory.
- The filenames for the libraries have the format <emphasis
- role="bold">libafs-</emphasis><replaceable>version</replaceable><emphasis role="bold">.o</emphasis>, where
- <replaceable>version</replaceable> indicates the kernel build level. The string <emphasis role="bold">.mp</emphasis> in
- the <replaceable>version</replaceable> indicates that the file is appropriate for machines running a multiprocessor
- kernel. <programlisting>
- # <emphasis role="bold">cp -rp modload /usr/vice/etc</emphasis>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Copy the AFS initialization script to the local directory for initialization files (by convention, <emphasis
- role="bold">/etc/rc.d/init.d</emphasis> on Linux machines). Note the removal of the <emphasis role="bold">.rc</emphasis>
- extension as you copy the script. <programlisting>
- # <emphasis role="bold">cp -p afs.rc /etc/rc.d/init.d/afs</emphasis>
-</programlisting></para>
- </listitem>
-
-<!-- I don't think we need to do this for Linux, and it complicates things if
- dynroot is enabled ...
- <listitem>
- <para>Run the AFS initialization script to load AFS extensions into the kernel. You can ignore any error messages about
- the inability to start the BOS Server or the Cache Manager or AFS client.</para>
-<programlisting>
- # <emphasis role="bold">/etc/rc.d/init.d/afs start</emphasis>
-</programlisting>
- </listitem>
--->
- </orderedlist>
-
- <indexterm>
- <primary>configuring</primary>
-
- <secondary>AFS server partition on first AFS machine</secondary>
-
- <tertiary>Linux</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>AFS server partition</primary>
-
- <secondary>configuring on first AFS machine</secondary>
-
- <tertiary>Linux</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>first AFS machine</primary>
-
- <secondary>AFS server partition</secondary>
-
- <tertiary>on Linux</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>Linux</primary>
-
- <secondary>AFS server partition</secondary>
-
- <tertiary>on first AFS machine</tertiary>
- </indexterm>
- </sect3>
- </sect2>
-
- <sect2 id="HDRWQ43">
- <title>Configuring Server Partitions on Linux 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>Add a line with the following format to the file systems registry file, <emphasis
- role="bold">/etc/fstab</emphasis>, for each directory just created. The entry maps the directory name to the disk
- partition to be mounted on it. <programlisting>
- /dev/<replaceable>disk</replaceable> /vicep<replaceable>xx</replaceable> ext2 defaults 0 2
-</programlisting></para>
-
- <para>The following is an example for the first partition being configured.</para>
-
- <programlisting>
- /dev/sda8 /vicepa ext2 defaults 0 2
-</programlisting>
- </listitem>
-
- <listitem>
- <para>Create a file system on each partition that is to be mounted at a <emphasis
- role="bold">/vicep</emphasis><replaceable>xx</replaceable> directory. The following command is probably appropriate, but
- consult the Linux documentation for more information. <programlisting>
- # <emphasis role="bold">mkfs -v /dev/</emphasis><replaceable>disk</replaceable>
-</programlisting></para>
- </listitem>
-
- <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>
-
- <listitem>
- <para>If you plan to retain client functionality on this machine after completing the installation, proceed to <link
- linkend="HDRWQ44">Enabling AFS Login on Linux 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>Linux</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>AFS login</primary>
-
- <secondary>on file server machine</secondary>
-
- <tertiary>Linux</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>first AFS machine</primary>
-
- <secondary>AFS login</secondary>
-
- <tertiary>on Linux</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>Linux</primary>
-
- <secondary>AFS login</secondary>
-
- <tertiary>on file server machine</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>PAM</primary>
-
- <secondary>on Linux</secondary>
-
- <tertiary>file server machine</tertiary>
- </indexterm>
- </sect2>
-
- <sect2 id="HDRWQ44">
- <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>
- </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>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>
-
- <sect1 id="HDRWQ45">
- <title>Getting Started on Solaris Systems</title>
-
- <para>Begin by running the AFS initialization script to call the <emphasis role="bold">modload</emphasis> program distributed by
- Sun Microsystems, which dynamically loads AFS modifications into the kernel. 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>Solaris</tertiary>
- </indexterm> <indexterm>
- <primary>AFS kernel extensions</primary>
-
- <secondary>on first AFS machine</secondary>
-
- <tertiary>Solaris</tertiary>
- </indexterm> <indexterm>
- <primary>first AFS machine</primary>
-
- <secondary>AFS kernel extensions</secondary>
-
- <tertiary>on Solaris</tertiary>
- </indexterm> <indexterm>
- <primary>Solaris</primary>
-
- <secondary>AFS kernel extensions</secondary>
-
- <tertiary>on first AFS machine</tertiary>
- </indexterm></para>
-
- <sect2 id="HDRWQ46">
- <title>Loading AFS into the Solaris Kernel</title>
-
- <para>The <emphasis role="bold">modload</emphasis> program is the dynamic kernel loader provided by Sun Microsystems for
- Solaris systems. Solaris does not support incorporation of AFS modifications during a kernel build.</para>
-
- <para>For AFS to function correctly, the <emphasis role="bold">modload</emphasis> program must run each time the machine
- reboots, so the AFS initialization script (included on the AFS CD-ROM) invokes it automatically. In this section you copy the
- appropriate AFS library file to the location where the <emphasis role="bold">modload</emphasis> program accesses it and then
- 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 Solaris startup and shutdown sequence. <orderedlist>
- <listitem>
- <para>Unpack the OpenAFS Solaris distribution tarball. The examples
- below assume that you have unpacked the files into the
- <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you
- pick a diferent location, substitute this in all of the following
- exmaples. Once you have unpacked the distribution, change directory
- as indicated.
-<programlisting>
- # <emphasis role="bold">cd /tmp/afsdist/sun4x_56/root.client/usr/vice/etc</emphasis>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Copy the AFS initialization script to the local directory for initialization files (by convention, <emphasis
- role="bold">/etc/init.d</emphasis> on Solaris machines). Note the removal of the <emphasis role="bold">.rc</emphasis>
- extension as you copy the script. <programlisting>
- # <emphasis role="bold">cp -p afs.rc /etc/init.d/afs</emphasis>
-</programlisting></para>
- </listitem>
-
- <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 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>
-
- <programlisting>
- # <emphasis role="bold">cp -p modload/libafs.o /kernel/fs/afs</emphasis>
-</programlisting>
-
- <para>If the machine is running Solaris 2.6 or the 32-bit version of Solaris 7, and its kernel does not support NFS
- server functionality or the <emphasis role="bold">nfsd</emphasis> process is not running:</para>
-
- <programlisting>
- # <emphasis role="bold">cp -p modload/libafs.nonfs.o /kernel/fs/afs</emphasis>
-</programlisting>
-
- <para>If the machine is running the 64-bit version of Solaris 7, its kernel supports NFS server functionality, and the
- <emphasis role="bold">nfsd</emphasis> process is running:</para>
-
- <programlisting>
- # <emphasis role="bold">cp -p modload/libafs64.o /kernel/fs/sparcv9/afs</emphasis>
-</programlisting>
-
- <para>If the machine is running the 64-bit version of Solaris 7, and its kernel does not support NFS server
- functionality or the <emphasis role="bold">nfsd</emphasis> process is not running:</para>
-
- <programlisting>
- # <emphasis role="bold">cp -p modload/libafs64.nonfs.o /kernel/fs/sparcv9/afs</emphasis>
-</programlisting>
- </listitem>
-
- <listitem>
- <para>Run the AFS initialization script to load AFS modifications into the kernel. You can ignore any error messages
- about the inability to start the BOS Server or the Cache Manager or AFS client. <programlisting>
- # <emphasis role="bold">/etc/init.d/afs start</emphasis>
-</programlisting></para>
-
- <para>When an entry called <computeroutput>afs</computeroutput> does not already exist in the local <emphasis
- role="bold">/etc/name_to_sysnum</emphasis> file, the script automatically creates it and reboots the machine to start
- using the new version of the file. If this happens, log in again as the superuser <emphasis role="bold">root</emphasis>
- after the reboot and run the initialization script again. This time the required entry exists in the <emphasis
- role="bold">/etc/name_to_sysnum</emphasis> file, and the <emphasis role="bold">modload</emphasis> program runs.</para>
-
- <programlisting>
- login: <emphasis role="bold">root</emphasis>
- Password: <replaceable>root_password</replaceable>
- # <emphasis role="bold">/etc/init.d/afs start</emphasis>
-</programlisting>
- </listitem>
- </orderedlist></para>
-
- <indexterm>
- <primary>replacing fsck program</primary>
-
- <secondary>first AFS machine</secondary>
-
- <tertiary>Solaris</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>fsck program</primary>
-
- <secondary>on first AFS machine</secondary>
-
- <tertiary>Solaris</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>first AFS machine</primary>
-
- <secondary>fsck program</secondary>
-
- <tertiary>on Solaris</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>Solaris</primary>
-
- <secondary>fsck program</secondary>
-
- <tertiary>on first AFS machine</tertiary>
- </indexterm>
- </sect2>
-
- <sect2 id="HDRWQ47">
- <title>Configuring the AFS-modified fsck Program on Solaris 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>
- <orderedlist>
- <listitem>
- <para>Create the <emphasis role="bold">/usr/lib/fs/afs</emphasis> directory to house the AFS-modified <emphasis
- role="bold">fsck</emphasis> program and related files. <programlisting>
- # <emphasis role="bold">mkdir /usr/lib/fs/afs</emphasis>
- # <emphasis role="bold">cd /usr/lib/fs/afs</emphasis>
-</programlisting></para>
- </listitem>
-
- <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>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Working in the <emphasis role="bold">/usr/lib/fs/afs</emphasis> directory, create the following links to Solaris
- libraries: <programlisting>
- # <emphasis role="bold">ln -s /usr/lib/fs/ufs/clri</emphasis>
- # <emphasis role="bold">ln -s /usr/lib/fs/ufs/df</emphasis>
- # <emphasis role="bold">ln -s /usr/lib/fs/ufs/edquota</emphasis>
- # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ff</emphasis>
- # <emphasis role="bold">ln -s /usr/lib/fs/ufs/fsdb</emphasis>
- # <emphasis role="bold">ln -s /usr/lib/fs/ufs/fsirand</emphasis>
- # <emphasis role="bold">ln -s /usr/lib/fs/ufs/fstyp</emphasis>
- # <emphasis role="bold">ln -s /usr/lib/fs/ufs/labelit</emphasis>
- # <emphasis role="bold">ln -s /usr/lib/fs/ufs/lockfs</emphasis>
- # <emphasis role="bold">ln -s /usr/lib/fs/ufs/mkfs</emphasis>
- # <emphasis role="bold">ln -s /usr/lib/fs/ufs/mount</emphasis>
- # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ncheck</emphasis>
- # <emphasis role="bold">ln -s /usr/lib/fs/ufs/newfs</emphasis>
- # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quot</emphasis>
- # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quota</emphasis>
- # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quotaoff</emphasis>
- # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quotaon</emphasis>
- # <emphasis role="bold">ln -s /usr/lib/fs/ufs/repquota</emphasis>
- # <emphasis role="bold">ln -s /usr/lib/fs/ufs/tunefs</emphasis>
- # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ufsdump</emphasis>
- # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ufsrestore</emphasis>
- # <emphasis role="bold">ln -s /usr/lib/fs/ufs/volcopy</emphasis>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Append the following line to the end of the file <emphasis role="bold">/etc/dfs/fstypes</emphasis>.
- <programlisting>
- afs AFS Utilities
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Edit the <emphasis role="bold">/sbin/mountall</emphasis> file, making two changes. <itemizedlist>
- <listitem>
- <para>Add an entry for AFS to the <computeroutput>case</computeroutput> statement for option 2, so that it reads
- as follows: <programlisting>
- case "$2" in
- ufs) foptions="-o p"
- ;;
- afs) foptions="-o p"
- ;;
- s5) foptions="-y -t /var/tmp/tmp$$ -D"
- ;;
- *) foptions="-y"
- ;;
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Edit the file so that all AFS and UFS partitions are checked in parallel. Replace the following section of
- code: <programlisting>
- # For fsck purposes, we make a distinction between ufs and
- # other file systems
- #
- if [ "$fstype" = "ufs" ]; then
- ufs_fscklist="$ufs_fscklist $fsckdev"
- saveentry $fstype "$OPTIONS" $special $mountp
- continue
- fi
-</programlisting></para>
-
- <para>with the following section of code:</para>
-
- <programlisting>
- # For fsck purposes, we make a distinction between ufs/afs
- # and other file systems.
- #
- if [ "$fstype" = "ufs" -o "$fstype" = "afs" ]; then
- ufs_fscklist="$ufs_fscklist $fsckdev"
- saveentry $fstype "$OPTIONS" $special $mountp
- continue
- fi
-</programlisting>
- </listitem>
- </itemizedlist></para>
- </listitem>
- </orderedlist></para>
-
- <indexterm>
- <primary>configuring</primary>
+ <indexterm>
+ <primary>configuring</primary>
<secondary>AFS server partition on first AFS machine</secondary>
- <tertiary>Solaris</tertiary>
+ <tertiary>AIX</tertiary>
</indexterm>
<indexterm>
<secondary>configuring on first AFS machine</secondary>
- <tertiary>Solaris</tertiary>
+ <tertiary>AIX</tertiary>
</indexterm>
<indexterm>
<secondary>AFS server partition</secondary>
- <tertiary>on Solaris</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>Solaris</primary>
-
- <secondary>AFS server partition</secondary>
-
- <tertiary>on first AFS machine</tertiary>
- </indexterm>
- </sect2>
-
- <sect2 id="HDRWQ48">
- <title>Configuring Server Partitions on Solaris 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>Add a line with the following format to the file systems registry file, <emphasis
- role="bold">/etc/vfstab</emphasis>, for each partition to be mounted on a directory created in the previous step. Note
- the value <computeroutput>afs</computeroutput> in the fourth field, which tells Solaris to use the AFS-modified
- <emphasis role="bold">fsck</emphasis> program on this partition. <programlisting>
- /dev/dsk/<replaceable>disk</replaceable> /dev/rdsk/<replaceable>disk</replaceable> /vicep<replaceable>xx</replaceable> afs <replaceable>boot_order</replaceable> yes
-</programlisting></para>
-
- <para>The following is an example for the first partition being configured.</para>
-
- <programlisting>
- /dev/dsk/c0t6d0s1 /dev/rdsk/c0t6d0s1 /vicepa afs 3 yes
-</programlisting>
- </listitem>
-
- <listitem>
- <para>Create a file system on each partition that is to be mounted at a <emphasis
- role="bold">/vicep</emphasis><replaceable>xx</replaceable> directory. The following command is probably appropriate, but
- consult the Solaris documentation for more information. <programlisting>
- # <emphasis role="bold">newfs -v /dev/rdsk/</emphasis><replaceable>disk</replaceable>
-</programlisting></para>
- </listitem>
-
- <listitem>
- <para>Issue the <emphasis role="bold">mountall</emphasis> command to mount all partitions at once.</para>
- </listitem>
-
- <listitem>
- <para>If you plan to retain client functionality on this machine after completing the installation, proceed to <link
- linkend="HDRWQ49">Enabling AFS Login and Editing the File Systems Clean-up Script on Solaris Systems</link>. Otherwise,
- 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>
-
- <secondary>file server machine</secondary>
-
- <tertiary>Solaris</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>AFS login</primary>
-
- <secondary>on file server machine</secondary>
-
- <tertiary>Solaris</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>first AFS machine</primary>
-
- <secondary>AFS login</secondary>
-
- <tertiary>on Solaris</tertiary>
- </indexterm>
-
- <indexterm>
- <primary>Solaris</primary>
-
- <secondary>AFS login</secondary>
-
- <tertiary>on file server machine</tertiary>
+ <tertiary>on AIX</tertiary>
</indexterm>
- <indexterm>
- <primary>PAM</primary>
-
- <secondary>on Solaris</secondary>
-
- <tertiary>file server machine</tertiary>
- </indexterm>
+ <indexterm>
+ <primary>AIX</primary>
- <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>
+ <secondary>AFS server partition</secondary>
- <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>
+ <tertiary>on first AFS machine</tertiary>
+ </indexterm>
+ </sect2>
- <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>
+ <sect2 id="HDRWQ23">
+ <title>Configuring Server Partitions on AIX Systems</title>
- <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>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>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>To configure server partitions on an AIX system, perform the following procedures: <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>
- <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>
+ <listitem>
+ <para>Use the <emphasis role="bold">SMIT</emphasis> program to create a journaling file system on each partition to be
+ configured as an AFS server partition.</para>
+ </listitem>
- <example>
- <title>Solaris PAM session example</title>
- <literallayout>login session required pam_afs_session.so</literallayout>
- </example>
+ <listitem>
+ <para>Mount each partition at one of the <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>
+ directories. Choose one of the following three methods: <itemizedlist>
+ <listitem>
+ <para>Use the <emphasis role="bold">SMIT</emphasis> program</para>
+ </listitem>
- <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>
+ <listitem>
+ <para>Use the <emphasis role="bold">mount -a</emphasis> command to mount all partitions at once</para>
+ </listitem>
- <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>
+ <listitem>
+ <para>Use the <emphasis role="bold">mount</emphasis> command on each partition in turn</para>
+ </listitem>
+ </itemizedlist></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>Also configure the partitions so that they are mounted automatically at each reboot. For more information, refer
+ to the AIX documentation.</para>
+ </listitem>
+ </orderedlist></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>
+ <primary>replacing fsck program</primary>
- <secondary>file systems clean-up script</secondary>
+ <secondary>first AFS machine</secondary>
- <tertiary>on file server machine</tertiary>
+ <tertiary>AIX</tertiary>
</indexterm>
<indexterm>
- <primary>file systems clean-up script (Solaris)</primary>
+ <primary>fsck program</primary>
- <secondary>file server machine</secondary>
+ <secondary>on first AFS machine</secondary>
+
+ <tertiary>AIX</tertiary>
</indexterm>
<indexterm>
- <primary>scripts</primary>
+ <primary>first AFS machine</primary>
- <secondary>file systems clean-up (Solaris)</secondary>
+ <secondary>fsck program</secondary>
- <tertiary>file server machine</tertiary>
+ <tertiary>on AIX</tertiary>
</indexterm>
-
- <orderedlist>
- <listitem>
- <para>Some Solaris distributions include a script that locates and removes unneeded files from various file systems. Its
- conventional location is <emphasis role="bold">/usr/lib/fs/nfs/nfsfind</emphasis>. The script generally uses an argument
- to the <emphasis role="bold">find</emphasis> command to define which file systems to search. In this step you modify the
- command to exclude the <emphasis role="bold">/afs</emphasis> directory. Otherwise, the command traverses the AFS
- filespace of every cell that is accessible from the machine, which can take many hours. The following alterations are
- possibilities, but you must verify that they are appropriate for your cell.</para>
+ <indexterm>
+ <primary>AIX</primary>
- <para>The first possible alteration is to add the <emphasis role="bold">-local</emphasis> flag to the existing command,
- so that it looks like the following:</para>
+ <secondary>fsck program</secondary>
- <programlisting>
- find $dir -local -name .nfs\* -mtime +7 -mount -exec rm -f {} \;
-</programlisting>
+ <tertiary>on first AFS machine</tertiary>
+ </indexterm>
+ </sect2>
- <para>Another alternative is to exclude any directories whose names begin with the lowercase letter <emphasis
- role="bold">a</emphasis> or a non-alphabetic character.</para>
+ <sect2 id="HDRWQ24">
+ <title>Replacing the fsck Program Helper on AIX Systems</title>
- <programlisting>
- find /[A-Zb-z]* <replaceable>remainder of existing command</replaceable>
-</programlisting>
+ <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>Do not use the following command, which still searches under the <emphasis role="bold">/afs</emphasis> directory,
- looking for a subdirectory of type <emphasis role="bold">4.2</emphasis>.</para>
+ <para><emphasis role="bold">Never run the standard fsck program on AFS server partitions. It discards AFS
+ volumes.</emphasis></para>
- <programlisting>
- find / -fstype 4.2 /* <replaceable>do not use</replaceable> */
-</programlisting>
+ <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/dest/root.server/etc/v3fshelper v3fshelper</emphasis>
+</programlisting></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>
+ <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>
-
- <indexterm>
- <primary>Basic OverSeer Server</primary>
-
- <see>BOS Server</see>
- </indexterm>
+ </orderedlist></para>
<indexterm>
- <primary>BOS Server</primary>
+ <primary>enabling AFS login</primary>
- <secondary>starting</secondary>
+ <secondary>file server machine</secondary>
- <tertiary>first AFS machine</tertiary>
+ <tertiary>AIX</tertiary>
</indexterm>
<indexterm>
- <primary>starting</primary>
+ <primary>AFS login</primary>
- <secondary>BOS Server</secondary>
+ <secondary>on file server machine</secondary>
- <tertiary>first AFS machine</tertiary>
+ <tertiary>AIX</tertiary>
</indexterm>
<indexterm>
<primary>first AFS machine</primary>
- <secondary>BOS Server</secondary>
+ <secondary>AFS login</secondary>
+
+ <tertiary>on AIX</tertiary>
</indexterm>
<indexterm>
- <primary>authorization checking (disabling)</primary>
+ <primary>AIX</primary>
- <secondary>first AFS machine</secondary>
+ <secondary>AFS login</secondary>
+
+ <tertiary>on file server machine</tertiary>
</indexterm>
<indexterm>
- <primary>disabling authorization checking</primary>
+ <primary>secondary authentication system (AIX)</primary>
- <secondary>first AFS machine</secondary>
+ <secondary>server machine</secondary>
</indexterm>
+ </sect2>
- <indexterm>
- <primary>first AFS machine</primary>
+ <sect2 id="HDRWQ25">
+ <title>Enabling AFS Login on AIX Systems</title>
- <secondary>authorization checking (disabling)</secondary>
- </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>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>
<sect1 id="HDRWQ50">
<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
</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>
</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
</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
</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>
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>
</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
</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>
git://git.openafs.org / openafs.git / blobdiff