source: server/major/nfs-utils.xml@ 0aeb696

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

    <!-- Inserted as a reminder to do this. The mention of a test suite
         is usually right before the root user installation commands. Please
         delete these 12 (including one blank) lines after you are done.-->

    <!-- Use one of the two mentions below about a test suite,
         delete the line that is not applicable. Of course, if the
         test suite uses syntax other than "make check", revise the
         line to reflect the actual syntax to run the test suite -->

    <!-- <para>This package does not come with a test suite.</para> -->
    <!-- <para>To test the results, issue: <command>make check</command>.</para> -->

  <!ENTITY nfs-utils-download-http "http://ftp.kernel.org/pub/linux/utils/nfs/nfs-utils-&nfs-utils-version;.tar.gz">
  <!ENTITY nfs-utils-download-ftp  "ftp://ftp.kernel.org/pub/linux/utils/nfs/nfs-utils-&nfs-utils-version;.tar.gz">
  <!ENTITY nfs-utils-md5sum        "8f863120261cd572ad320a9152581e11">
  <!ENTITY nfs-utils-size          "396 KB">
  <!ENTITY nfs-utils-buildsize     "5.8 MB">
  <!ENTITY nfs-utils-time          "0.2 SBU">
]>

<sect1 id="nfs-utils" xreflabel="NFS Utilities-&nfs-utils-version;">
  <?dbhtml filename="nfs-utils.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
    <keywordset>
      <keyword role="package">nfs-utils-&nfs-utils-version;.tar</keyword>
      <keyword role="ftpdir">nfs-utils</keyword>
    </keywordset>
  </sect1info>

  <title>NFS Utilities-&nfs-utils-version;</title>

  <indexterm zone="nfs-utils">
    <primary sortas="a-Nfs-utils">NFS Utilities</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to NFS Utilities</title>

    <para>The <application>NFS Utilities</application> package contains the
    userspace server and client tools necessary to use the kernel's nfs
    abilities. NFS is a protocol that allows sharing file systems over the
    network.</para>

    <bridgehead renderas="sect3">Package information</bridgehead>
    <itemizedlist spacing='compact'>
      <listitem>
        <para>Download (HTTP): <ulink url="&nfs-utils-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&nfs-utils-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &nfs-utils-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &nfs-utils-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &nfs-utils-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &nfs-utils-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing='compact'>
      <listitem>
        <para>Required patch: <ulink
        url="&patch-root;/nfs-utils-&nfs-utils-version;-gcc4-1.patch"/></para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">NFS Utilities Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required"><xref linkend="portmap"/></para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><ulink
    url="http://www.monkey.org/~provos/libevent/">libevent</ulink> and <ulink
    url="http://www.citi.umich.edu/projects/nfsv4/linux/libnfsidmap/">libnsfidmap</ulink>
    for nfsv4 support, and <xref linkend="mitkrb"/> or <xref linkend="heimdal"/>
    for gss (RPC Security) support.</para>

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/nfs-utils"/></para>

  </sect2>

  <sect2 role="kernel" id='nfs-utils-kernel'>
    <title>Kernel Configuration</title>

    <para>Enable the following options in the kernel configuration
    and recompile the kernel if necessary:</para>

<screen><literal>File systems:
  Network File Systems:
    NFS File System Support: M or Y
    NFS Server Support: M or Y</literal></screen>

    <para>Select the appropriate sub-options that appear when the above options
    are selected.</para>

    <indexterm zone="nfs-utils nfs-utils-kernel">
      <primary sortas="d-nfs-utils">NFS Utilities</primary>
    </indexterm>

  </sect2>

  <sect2 role="installation" id='nfs-utils-install' xreflabel='NFS Utilities Installation'>
    <title>Installation of NFS Utilities</title>

    <para>Before you compile the program, you need to be sure the
    <systemitem class="username">nobody</systemitem> user and
    <systemitem class="groupname">nogroup</systemitem> group are available.
    You can add these by running the following commands as the
    <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>groupadd -g 99 nogroup &amp;&amp;
useradd -c "Unprivileged Nobody" -d /dev/null -g nogroup \
    -s /bin/false -u 99 nobody</userinput></screen>

    <note>
      <para>The classic uid and gid values are 65534 which is also -2 when
      interpreted as a signed 16-bit number.  These values impact other files
      on some filesystems that do not have support for sparse files.  The
      <systemitem class="username">nobody</systemitem> and <systemitem
      class="groupname">nogroup</systemitem> values are relatively arbitrary.
      The impact on a server is nil if the exports file is configured
      correctly.  If it is misconfigured, the <command>ls -l</command> or
      <command>ps</command> listing will show a uid or gid number of 65534
      instead of a name. The client uses <systemitem
      class="username">nobody</systemitem> only as the user running
      <command>rpc.statd</command>.</para>
    </note>

    <para>Install <application>NFS Utilities</application> by running
    the following commands:</para>

<screen><userinput>patch -Np1 -i ../nfs-utils-&nfs-utils-version;-gcc4-1.patch &amp;&amp;
./configure --prefix=/usr --sysconfdir=/etc \
    --disable-nfsv4 --disable-gss &amp;&amp;
make</userinput></screen>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role='root'><userinput>make install</userinput></screen>

    <note>
      <para>If your <filename class="directory">/usr</filename> directory
      is NFS mounted, you should install the executables in
      <filename class="directory">/sbin</filename> by passing
      an additional parameter <option>--sbindir=/sbin</option> to the
      above <command>./configure</command> command.</para>
    </note>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para><parameter>--disable-nfsv4</parameter>: Disables support
    for NFS Version 4.</para>

    <para><parameter>--disable-gss</parameter>: Disables support for
    RPCSEC GSS (RPC Security).</para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring NFS Utilities</title>

    <sect3 id='nfs-utils-server-config'>
      <title>Server Configuration</title>

      <para><filename>/etc/exports</filename> contains the exported directories
      on NFS servers. Refer to the exports manual page for the syntax of this
      file. Also refer to the "NFS HowTo" available at <ulink
      url="http://nfs.sourceforge.net/nfs-howto/"/> on how to configure the
      servers and clients in a secure manner. For example, for sharing the
      <filename class="directory">/home</filename> directory over the local
      network, the following line may be added:</para>

<screen role="root"><userinput>/home 192.168.0.0/255.255.255.0(rw,anonuid=99,anongid=99)</userinput></screen>

      <indexterm zone="nfs-utils nfs-utils-server-config">
        <primary sortas="e-etc-exportfs">/etc/exportfs</primary>
      </indexterm>

      <sect4  id="nfs-utils-server-init">
        <title>Boot Script</title>

        <para>Install the <filename>/etc/rc.d/init.d/nfs-server</filename>
        init script included in the <xref
        linkend="bootscripts"/> package to start the server
        at boot.</para>

<screen role="root"><userinput>make install-nfs-server</userinput></screen>

        <indexterm zone="nfs-utils nfs-utils-server-init">
          <primary sortas="f-nfs-server">nfs-server</primary>
        </indexterm>

        <para>Now create the <filename>/etc/sysconfig/nfs-server</filename>
        configuration file:</para>

<screen role="root"><userinput>cat &gt; /etc/sysconfig/nfs-server &lt;&lt; "EOF"
<literal>PORT="2049"
PROCESSES="8"
QUOTAS="no"
KILLDELAY="10"</literal>
EOF</userinput></screen>

        <indexterm zone="nfs-utils nfs-utils-server-init">
          <primary
          sortas="e-etc-sysconfig-nfs-server">/etc/sysconfig/nfs-server</primary>
        </indexterm>

      </sect4>

    </sect3>

    <sect3 id='nfs-utils-client-config'>
      <title>Client Configuration</title>

      <para><filename>/etc/fstab</filename> contains the directories that
      are to be mounted on the client. Alternately the partitions can be
      mounted by using the <command>mount</command> command with the proper
      options. To mount the <filename class="directory">/home</filename>
      and <filename class="directory">/usr</filename> partitions, add the
      following to the <filename>/etc/fstab</filename>:</para>

<screen role="root"><userinput>&lt;server-name&gt;:/home  /home nfs   rw,_netdev,rsize=8192,wsize=8192 0 0
&lt;server-name&gt;:/usr   /usr  nfs   ro,_netdev,rsize=8192            0 0</userinput></screen>

      <indexterm zone="nfs-utils nfs-utils-client-config">
        <primary sortas="e-etc-fstab">/etc/fstab</primary>
      </indexterm>

      <sect4  id="nfs-utils-client-init">
        <title>Boot Script</title>


        <para>Install the <filename>/etc/rc.d/init.d/nfs-client</filename>
        init script included in the
        <xref linkend="bootscripts"/> package to
        start the client services at boot.</para>

<screen role="root"><userinput>make install-nfs-client</userinput></screen>

        <indexterm zone="nfs-utils nfs-utils-client-config">
          <primary sortas="f-nfs-client">nfs-client</primary>
        </indexterm>

        <para>To automatically mount <systemitem
        class="filesystem">nfs</systemitem> filesystems, clients will also
        need to install the <filename>netfs</filename> bootscript as described
        in <xref linkend='postlfs-config-netfs'/>.</para>

        <indexterm zone="nfs-utils nfs-utils-client-config">
          <primary sortas="f-netfs">netfs</primary>
        </indexterm>

      </sect4>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>
    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>exportfs, nfsstat, nhfsgraph, nhfsnums, nhfsrun, nhfsstone,
        rpc.lockd, rpc.mountd, rpc.nfsd, rpc.rquotad, rpc.statd,
        and showmount</seg>
        <seg>None</seg>
        <seg>/var/lib/nfs</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="exportfs">
        <term><command>exportfs</command></term>
        <listitem>
          <para>maintains a list of NFS exported file systems.</para>
          <indexterm zone="nfs-utils exportfs">
            <primary sortas="b-exportfs">exportfs</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="nfsstat">
        <term><command>nfsstat</command></term>
        <listitem>
          <para>prints NFS statistics.</para>
          <indexterm zone="nfs-utils nfsstat">
            <primary sortas="b-nfsstat">nfsstat</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="nhfsgraph">
        <term><command>nhfsgraph</command></term>
        <listitem>
          <para>runs <command>nhfsstone</command> over multiple loads.</para>
          <indexterm zone="nfs-utils nhfsgraph">
            <primary sortas="b-nhfsgraph">nhfsgraph</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="nhfsnums">
        <term><command>nhfsnums</command></term>
        <listitem>
          <para>converts raw numbers from <command>nhfsstone</command>
          output into plot format.</para>
          <indexterm zone="nfs-utils nhfsnums">
            <primary sortas="b-nhfsnums">nhfsnums</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="nhfsrun">
        <term><command>nhfsrun</command></term>
        <listitem>
          <para>executes <command>nhfsstone</command> with a range of
          different loads.</para>
          <indexterm zone="nfs-utils nhfsrun">
            <primary sortas="b-nhfsrun">nhfsrun</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="nhfsstone">
        <term><command>nhfsstone</command></term>
        <listitem>
          <para>is used on a NFS client to generate an artificial load
          with a particular mix of NFS operations.</para>
          <indexterm zone="nfs-utils nhfsstone">
            <primary sortas="b-nhfsstone">nhfsstone</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="rpclockd">
        <term><command>rpc.lockd</command></term>
        <listitem>
          <para>starts the NFS lock manager (NLM) on kernels that don't
          start it automatically. However, since most kernels do start it
          automatically it is usually not required.</para>
          <indexterm zone="nfs-utils rpclockd">
            <primary sortas="b-rpclockd">rpc.lockd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="rpcmountd">
        <term><command>rpc.mountd</command></term>
        <listitem>
          <para>implements the NFS mount protocol on an NFS server.</para>
          <indexterm zone="nfs-utils rpcmountd">
            <primary sortas="b-rpcmountd">rpc.mountd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="rpcnfsd">
        <term><command>rpc.nfsd</command></term>
        <listitem>
          <para>implements the user level part of the NFS
          service on the server.</para>
          <indexterm zone="nfs-utils rpcnfsd">
            <primary sortas="b-rpcnfsd">rpc.nfsd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="rpcrquotad">
        <term><command>rpc.rquotad</command></term>
        <listitem>
          <para>is an rpc server which returns quotas for a user of a
          local file system which is mounted by a remote machine over
          the NFS.</para>
          <indexterm zone="nfs-utils rpcrquotad">
            <primary sortas="b-rpcrquotad">rpc.rquotad</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="rpcstatd">
        <term><command>rpc.statd</command></term>
        <listitem>
          <para>is used by the NFS file locking service,
          <command>rpc.lockd</command>, to implement lock recovery when
          the NFS server machine crashes and reboots. Runs on the NFS
          server only.</para>
          <indexterm zone="nfs-utils rpcstatd">
            <primary sortas="b-rpcstatd">rpc.statd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="showmount">
        <term><command>showmount</command></term>
        <listitem>
          <para>displays mount information for an NFS server.</para>
          <indexterm zone="nfs-utils showmount">
            <primary sortas="b-showmount">showmount</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>