<para>To continue, proceed to the appropriate section: <itemizedlist>
<listitem>
- <para><link linkend="HDRWQ21">Getting Started on AIX 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/dest/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>
+ <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>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>
- </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/dest/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>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="HDRWQ41">
- <title>Getting Started on Linux Systems</title>
+ <para>At this point you incorporate AFS into the operating system's
+ Pluggable Authentication Module (PAM) scheme. PAM integrates all
+ authentication mechanisms on the machine, including login, to provide
+ the security infrastructure for authenticated access to and from the
+ machine.</para>
- <indexterm>
- <primary>replacing fsck program</primary>
+ <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>
- <secondary>not necessary on Linux</secondary>
- </indexterm>
+ <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>
- <indexterm>
- <primary>fsck program</primary>
+ <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>
- <secondary>on first AFS machine</secondary>
+ <example>
+ <title>Linux PAM session example</title>
+ <literallayout>session required pam_afs_session.so</literallayout>
+ </example>
- <tertiary>Linux</tertiary>
- </indexterm>
+ <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>
- <indexterm>
- <primary>first AFS machine</primary>
+ <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>
- <secondary>fsck program</secondary>
+ <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>
- <tertiary>on Linux</tertiary>
- </indexterm>
+ <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>
- <indexterm>
- <primary>Linux</primary>
+ <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>
- <secondary>fsck program replacement not necessary</secondary>
- </indexterm>
+ <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>
- <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>
+ <sect1 id="HDRWQ45">
+ <title>Getting Started on Solaris Systems</title>
- <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>
+ <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>Linux</tertiary>
+ <tertiary>Solaris</tertiary>
</indexterm> <indexterm>
<primary>AFS kernel extensions</primary>
<secondary>on first AFS machine</secondary>
- <tertiary>Linux</tertiary>
+ <tertiary>Solaris</tertiary>
</indexterm> <indexterm>
<primary>first AFS machine</primary>
<secondary>AFS kernel extensions</secondary>
- <tertiary>on Linux</tertiary>
+ <tertiary>on Solaris</tertiary>
</indexterm> <indexterm>
- <primary>Linux</primary>
+ <primary>Solaris</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>
+ <sect2 id="HDRWQ46">
+ <title>Loading AFS into the Solaris 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>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">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>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 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>
-
+ <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 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.
+ <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/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/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>
+ # <emphasis role="bold">cd /tmp/afsdist/sun4x_56/dest/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/rc.d/init.d</emphasis> on Linux machines). Note the removal of the <emphasis role="bold">.rc</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/rc.d/init.d/afs</emphasis>
+ # <emphasis role="bold">cp -p afs.rc /etc/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>
+ <para>Copy the appropriate AFS kernel library file to the local file <emphasis
+ role="bold">/kernel/fs/afs</emphasis>.</para>
- <tertiary>Linux</tertiary>
- </indexterm>
+ <para>If the machine is running Solaris 11 on the x86_64 platform:</para>
- <indexterm>
- <primary>first AFS machine</primary>
+ <programlisting>
+ # <emphasis role="bold">cp -p modload/libafs64.o /kernel/drv/amd64/afs</emphasis>
+</programlisting>
- <secondary>AFS server partition</secondary>
+ <para>If the machine is running Solaris 10 on the x86_64 platform:</para>
- <tertiary>on Linux</tertiary>
- </indexterm>
+ <programlisting>
+ # <emphasis role="bold">cp -p modload/libafs64.o /kernel/fs/amd64/afs</emphasis>
+</programlisting>
- <indexterm>
- <primary>Linux</primary>
+ <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>
- <secondary>AFS server partition</secondary>
+ <programlisting>
+ # <emphasis role="bold">cp -p modload/libafs.o /kernel/fs/afs</emphasis>
+</programlisting>
- <tertiary>on first AFS machine</tertiary>
- </indexterm>
- </sect3>
- </sect2>
+ <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>
- <sect2 id="HDRWQ43">
- <title>Configuring Server Partitions on Linux Systems</title>
+ <programlisting>
+ # <emphasis role="bold">cp -p modload/libafs.nonfs.o /kernel/fs/afs</emphasis>
+</programlisting>
- <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>
+ <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>
- <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>
+ <programlisting>
+ # <emphasis role="bold">cp -p modload/libafs64.o /kernel/fs/sparcv9/afs</emphasis>
+</programlisting>
- <para>The following is an example for the first partition being configured.</para>
+ <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>
- /dev/sda8 /vicepa ext2 defaults 0 2
+ # <emphasis role="bold">cp -p modload/libafs64.nonfs.o /kernel/fs/sparcv9/afs</emphasis>
</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>
+ <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>
- </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>
+ <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>
- <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>
+ <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>enabling AFS login</primary>
+ <primary>replacing fsck program</primary>
- <secondary>file server machine</secondary>
+ <secondary>first AFS machine</secondary>
- <tertiary>Linux</tertiary>
+ <tertiary>Solaris</tertiary>
</indexterm>
<indexterm>
- <primary>AFS login</primary>
+ <primary>fsck program</primary>
- <secondary>on file server machine</secondary>
+ <secondary>on first AFS machine</secondary>
- <tertiary>Linux</tertiary>
+ <tertiary>Solaris</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>
+ <secondary>fsck program</secondary>
- <tertiary>on file server machine</tertiary>
+ <tertiary>on Solaris</tertiary>
</indexterm>
<indexterm>
- <primary>PAM</primary>
+ <primary>Solaris</primary>
- <secondary>on Linux</secondary>
+ <secondary>fsck program</secondary>
- <tertiary>file server machine</tertiary>
+ <tertiary>on first AFS machine</tertiary>
</indexterm>
</sect2>
- <sect2 id="HDRWQ44">
- <title>Enabling AFS Login on Linux Systems</title>
+ <sect2 id="HDRWQ47">
+ <title>Configuring the AFS-modified fsck Program on Solaris Systems</title>
- <note>
- <para>If you plan to remove client functionality from this machine
- after completing the installation, skip this section and proceed
- to <link linkend="HDRWQ50">Starting the BOS Server</link>.</para>
- </note>
+ <para>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>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><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>
- <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>
+ <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>
- <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>
+ <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>
- <example>
- <title>Linux PAM session example</title>
- <literallayout>session required pam_afs_session.so</literallayout>
- </example>
+ <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>
- <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>
+ <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>
- <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>
+ <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>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>with the following section of code:</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>
+ <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>
- <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>
+ <indexterm>
+ <primary>configuring</primary>
- <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>
+ <secondary>AFS server partition on first AFS machine</secondary>
- <sect1 id="HDRWQ45">
- <title>Getting Started on Solaris Systems</title>
+ <tertiary>Solaris</tertiary>
+ </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>
+ <indexterm>
+ <primary>AFS server partition</primary>
- <secondary>first AFS machine</secondary>
+ <secondary>configuring on first AFS machine</secondary>
<tertiary>Solaris</tertiary>
- </indexterm> <indexterm>
- <primary>AFS kernel extensions</primary>
-
- <secondary>on first AFS machine</secondary>
+ </indexterm>
- <tertiary>Solaris</tertiary>
- </indexterm> <indexterm>
+ <indexterm>
<primary>first AFS machine</primary>
- <secondary>AFS kernel extensions</secondary>
+ <secondary>AFS server partition</secondary>
<tertiary>on Solaris</tertiary>
- </indexterm> <indexterm>
+ </indexterm>
+
+ <indexterm>
<primary>Solaris</primary>
- <secondary>AFS kernel extensions</secondary>
+ <secondary>AFS server partition</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>
+ </indexterm>
+ </sect2>
- <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>
+ <sect2 id="HDRWQ48">
+ <title>Configuring Server Partitions on Solaris Systems</title>
- <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>
+ <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>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/dest/root.client/usr/vice/etc</emphasis>
+ <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>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>
+ <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 appropriate AFS kernel library file to the local file <emphasis
- role="bold">/kernel/fs/afs</emphasis>.</para>
-
- <para>If the machine is running Solaris 11 on the x86_64 platform:</para>
-
- <programlisting>
- # <emphasis role="bold">cp -p modload/libafs64.o /kernel/drv/amd64/afs</emphasis>
-</programlisting>
-
- <para>If the machine is running Solaris 10 on the x86_64 platform:</para>
-
- <programlisting>
- # <emphasis role="bold">cp -p modload/libafs64.o /kernel/fs/amd64/afs</emphasis>
-</programlisting>
-
- <para>If the machine is running Solaris 2.6 or the 32-bit version of Solaris 7, its kernel supports NFS server
- functionality, and the <emphasis role="bold">nfsd</emphasis> process is running:</para>
-
- <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>
+ <para>The following is an example for the first partition being configured.</para>
<programlisting>
- # <emphasis role="bold">cp -p modload/libafs64.nonfs.o /kernel/fs/sparcv9/afs</emphasis>
+ /dev/dsk/c0t6d0s1 /dev/rdsk/c0t6d0s1 /vicepa afs 3 yes
</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>
+ <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>
- <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>
+ <listitem>
+ <para>Issue the <emphasis role="bold">mountall</emphasis> command to mount all partitions at once.</para>
+ </listitem>
- <programlisting>
- login: <emphasis role="bold">root</emphasis>
- Password: <replaceable>root_password</replaceable>
- # <emphasis role="bold">/etc/init.d/afs start</emphasis>
-</programlisting>
+ <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>replacing fsck program</primary>
+ <primary>enabling AFS login</primary>
- <secondary>first AFS machine</secondary>
+ <secondary>file server machine</secondary>
<tertiary>Solaris</tertiary>
</indexterm>
<indexterm>
- <primary>fsck program</primary>
+ <primary>AFS login</primary>
- <secondary>on first AFS machine</secondary>
+ <secondary>on file server machine</secondary>
<tertiary>Solaris</tertiary>
</indexterm>
<indexterm>
<primary>first AFS machine</primary>
- <secondary>fsck program</secondary>
+ <secondary>AFS login</secondary>
<tertiary>on Solaris</tertiary>
</indexterm>
<indexterm>
<primary>Solaris</primary>
- <secondary>fsck program</secondary>
+ <secondary>AFS login</secondary>
- <tertiary>on first AFS machine</tertiary>
+ <tertiary>on file server machine</tertiary>
</indexterm>
- </sect2>
- <sect2 id="HDRWQ47">
- <title>Configuring the AFS-modified fsck Program on Solaris Systems</title>
+ <indexterm>
+ <primary>PAM</primary>
- <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>
+ <secondary>on Solaris</secondary>
- <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>
+ <tertiary>file server machine</tertiary>
+ </indexterm>
- <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>
+ <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>
- <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>
+ <para>At this point you incorporate AFS into the operating system's
+ Pluggable Authentication Module (PAM) scheme. PAM integrates all
+ authentication mechanisms on the machine, including login, to provide
+ the security infrastructure for authenticated access to and from the
+ machine.</para>
+
+ <para>Explaining PAM is beyond the scope of this document. It is
+ assumed that you understand the syntax and meanings of settings in the
+ PAM configuration file (for example, how the
+ <computeroutput>other</computeroutput> entry works, the effect of
+ marking an entry as <computeroutput>required</computeroutput>,
+ <computeroutput>optional</computeroutput>, or
+ <computeroutput>sufficient</computeroutput>, and so on).</para>
+
+ <para>You should first configure your system to obtain Kerberos v5
+ tickets as part of the authentication process, and then run an AFS PAM
+ module to obtain tokens from those tickets after authentication.
+ Current versions of Solaris come with a Kerberos v5 PAM module that
+ will work, or you can download and install <ulink
+ url="http://www.eyrie.org/~eagle/software/pam-krb5">Russ Allbery's
+ Kerberos v5 PAM module</ulink>, which is tested regularly with AFS.
+ See the instructions of whatever PAM module you use for how to
+ configure it.</para>
+
+ <para>Some Kerberos v5 PAM modules do come with native AFS support
+ (usually requiring the Heimdal Kerberos implementation rather than the
+ MIT Kerberos implementation). If you are using one of those PAM
+ modules, you can configure it to obtain AFS tokens. It's more common,
+ however, to separate the AFS token acquisition into a separate PAM
+ module.</para>
+
+ <para>The recommended AFS PAM module is <ulink
+ url="http://www.eyrie.org/~eagle/software/pam-afs-session/">Russ
+ Allbery's pam-afs-session module</ulink>. It should work with any of
+ the Kerberos v5 PAM modules. To add it to the PAM configuration, you
+ often only need to add configuration to the session group in
+ <filename>pam.conf</filename>:</para>
+
+ <example>
+ <title>Solaris PAM session example</title>
+ <literallayout>login session required pam_afs_session.so</literallayout>
+ </example>
+
+ <para>This example enables PAM authentication only for console login.
+ You may want to add a similar line for the ssh service and for any
+ other login service that you use, including possibly the
+ <literal>other</literal> service (which serves as a catch-all). You
+ may also want to add options to the AFS PAM session module
+ (particularly <literal>retain_after_close</literal>, which is
+ necessary for some versions of Solaris.</para>
+
+ <para>For additional configuration examples and the configuration
+ options of the AFS PAM module, see its documentation. For more
+ details on the available options for the PAM configuration, see the
+ <filename>pam.conf</filename> manual page.</para>
+
+ <para>Sites which still require <emphasis
+ role="bold">kaserver</emphasis> or external Kerberos v4 authentication
+ should consult <link linkend="KAS016">"Enabling kaserver based AFS
+ Login on Solaris Systems"</link> for details of how to enable AFS
+ login on Solaris.</para>
+
+ <para>Proceed to <link linkend="HDRWQ49a">Editing the File Systems
+ Clean-up Script on Solaris Systems</link></para>
+ </sect2>
+ <sect2 id="HDRWQ49a">
+ <title>Editing the File Systems Clean-up Script on Solaris Systems</title>
+ <indexterm>
+ <primary>Solaris</primary>
+
+ <secondary>file systems clean-up script</secondary>
+
+ <tertiary>on file server machine</tertiary>
+ </indexterm>
+
+ <indexterm>
+ <primary>file systems clean-up script (Solaris)</primary>
+
+ <secondary>file server machine</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>scripts</primary>
+
+ <secondary>file systems clean-up (Solaris)</secondary>
+
+ <tertiary>file server machine</tertiary>
+ </indexterm>
+
+ <orderedlist>
<listitem>
- <para>Append the following line to the end of the file <emphasis role="bold">/etc/dfs/fstypes</emphasis>.
+ <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>
+
+ <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>
+
<programlisting>
- afs AFS Utilities
-</programlisting></para>
- </listitem>
+ find $dir -local -name .nfs\* -mtime +7 -mount -exec rm -f {} \;
+</programlisting>
- <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>
+ <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>
- <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>
+ <programlisting>
+ find /[A-Zb-z]* <replaceable>remainder of existing command</replaceable>
+</programlisting>
- <para>with the following section of code:</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>
- <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>
+ find / -fstype 4.2 /* <replaceable>do not use</replaceable> */
</programlisting>
- </listitem>
- </itemizedlist></para>
</listitem>
- </orderedlist></para>
+
+ <listitem>
+ <para>Proceed to <link linkend="HDRWQ50">Starting the BOS Server</link> (or if referring to these instructions while
+ installing an additional file server machine, return to <link linkend="HDRWQ108">Starting Server
+ Programs</link>).</para>
+ </listitem>
+ </orderedlist>
<indexterm>
- <primary>configuring</primary>
+ <primary>Basic OverSeer Server</primary>
- <secondary>AFS server partition on first AFS machine</secondary>
+ <see>BOS Server</see>
+ </indexterm>
- <tertiary>Solaris</tertiary>
+ <indexterm>
+ <primary>BOS Server</primary>
+
+ <secondary>starting</secondary>
+
+ <tertiary>first AFS machine</tertiary>
</indexterm>
<indexterm>
- <primary>AFS server partition</primary>
+ <primary>starting</primary>
- <secondary>configuring on first AFS machine</secondary>
+ <secondary>BOS Server</secondary>
- <tertiary>Solaris</tertiary>
+ <tertiary>first AFS machine</tertiary>
</indexterm>
<indexterm>
<primary>first AFS machine</primary>
- <secondary>AFS server partition</secondary>
+ <secondary>BOS Server</secondary>
+ </indexterm>
- <tertiary>on Solaris</tertiary>
+ <indexterm>
+ <primary>authorization checking (disabling)</primary>
+
+ <secondary>first AFS machine</secondary>
</indexterm>
<indexterm>
- <primary>Solaris</primary>
+ <primary>disabling authorization checking</primary>
- <secondary>AFS server partition</secondary>
+ <secondary>first AFS machine</secondary>
+ </indexterm>
- <tertiary>on first AFS machine</tertiary>
+ <indexterm>
+ <primary>first AFS machine</primary>
+
+ <secondary>authorization checking (disabling)</secondary>
</indexterm>
</sect2>
+ </sect1>
- <sect2 id="HDRWQ48">
- <title>Configuring Server Partitions on Solaris Systems</title>
+ <sect1 id="HDRWQ21">
+ <title>Getting Started on AIX 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>
+ <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>incorporating AFS kernel extensions</primary>
+
+ <secondary>first AFS machine</secondary>
+
+ <tertiary>AIX</tertiary>
+ </indexterm> <indexterm>
+ <primary>AFS kernel extensions</primary>
+
+ <secondary>on first AFS machine</secondary>
+
+ <tertiary>AIX</tertiary>
+ </indexterm> <indexterm>
+ <primary>first AFS machine</primary>
+
+ <secondary>AFS kernel extensions</secondary>
+
+ <tertiary>on AIX</tertiary>
+ </indexterm> <indexterm>
+ <primary>AIX</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>
+
+ <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 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>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>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
+ <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>The following is an example for the first partition being configured.</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 is not to function as an NFS/AFS Translator, set the <computeroutput>NFS</computeroutput> variable
+ as follows.</para>
<programlisting>
- /dev/dsk/c0t6d0s1 /dev/rdsk/c0t6d0s1 /vicepa afs 3 yes
+ NFS=$NFS_NONE
</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>
+ <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>
- <listitem>
- <para>Issue the <emphasis role="bold">mountall</emphasis> command to mount all partitions at once.</para>
+ <programlisting>
+ NFS=$NFS_IAUTH
+</programlisting>
</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>
+ <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>
- </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>
+ <primary>configuring</primary>
- <secondary>on file server machine</secondary>
+ <secondary>AFS server partition on first AFS machine</secondary>
- <tertiary>Solaris</tertiary>
+ <tertiary>AIX</tertiary>
</indexterm>
<indexterm>
- <primary>first AFS machine</primary>
+ <primary>AFS server partition</primary>
- <secondary>AFS login</secondary>
+ <secondary>configuring on first AFS machine</secondary>
- <tertiary>on Solaris</tertiary>
+ <tertiary>AIX</tertiary>
</indexterm>
<indexterm>
- <primary>Solaris</primary>
+ <primary>first AFS machine</primary>
- <secondary>AFS login</secondary>
+ <secondary>AFS server partition</secondary>
- <tertiary>on file server machine</tertiary>
+ <tertiary>on AIX</tertiary>
</indexterm>
<indexterm>
- <primary>PAM</primary>
+ <primary>AIX</primary>
- <secondary>on Solaris</secondary>
+ <secondary>AFS server partition</secondary>
- <tertiary>file server machine</tertiary>
+ <tertiary>on first AFS machine</tertiary>
</indexterm>
+ </sect2>
- <note>
- <para>If you plan to remove client functionality from this machine after completing the installation, skip this section and
- proceed to <link linkend="HDRWQ50">Starting the BOS Server</link>.</para>
- </note>
-
- <para>At this point you incorporate AFS into the operating system's
- Pluggable Authentication Module (PAM) scheme. PAM integrates all
- authentication mechanisms on the machine, including login, to provide
- the security infrastructure for authenticated access to and from the
- machine.</para>
-
- <para>Explaining PAM is beyond the scope of this document. It is
- assumed that you understand the syntax and meanings of settings in the
- PAM configuration file (for example, how the
- <computeroutput>other</computeroutput> entry works, the effect of
- marking an entry as <computeroutput>required</computeroutput>,
- <computeroutput>optional</computeroutput>, or
- <computeroutput>sufficient</computeroutput>, and so on).</para>
+ <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">