source: general/sysutils/autofs.xml@ 89265b09

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

  <!ENTITY autofs-download-http "&kernel-dl;/linux/daemons/autofs/v5/autofs-&autofs-version;.tar.xz">
  <!ENTITY autofs-download-ftp  " ">
  <!ENTITY autofs-md5sum        "6bd1ea8a9e5dc3a7dc95119e3bbaf52c">
  <!ENTITY autofs-size          "324 KB">
  <!ENTITY autofs-buildsize     "6.7 MB">
  <!ENTITY autofs-time          "0.1 SBU">
]>

<sect1 id="autofs" xreflabel="Autofs-&autofs-version;">
  <?dbhtml filename="autofs.html"?>

  <sect1info>
    <date>$Date$</date>
  </sect1info>

  <title>autofs-&autofs-version;</title>

  <indexterm zone="autofs">
    <primary sortas="a-Autofs">Autofs</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Autofs</title>

    <para>
      <application>Autofs</application> controls the operation of the automount
      daemons. The automount daemons automatically mount filesystems when they
      are accessed and unmount them after a period of inactivity. This is done
      based on a set of pre-configured maps.
    </para>

    &lfs101_checked;

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

    <bridgehead renderas="sect3">Autofs Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="libtirpc"/> and
      <xref linkend="rpcsvc-proto"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="nfs-utils"/>,
      <xref linkend="libnsl"/>,
      <xref linkend="libxml2"/>,
      <xref linkend="mitkrb"/>,
      <xref linkend="openldap"/> (client only), and
      <xref linkend="cyrus-sasl"/>
    </para>

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

  </sect2>

  <sect2 role="kernel" id="autofs-kernel">
    <title>Kernel Configuration</title>

    <indexterm zone="autofs autofs-kernel">
      <primary sortas="d-Automounter">Automounter</primary>
    </indexterm>

    <para>
      Verify that automounter kernel support has been enabled:
    </para>

<screen><literal>File systems ---&gt;
  &lt;*/M&gt; Kernel automounter support (supports v3, v4, and v5) [CONFIG_AUTOFS_FS]</literal></screen>

    <para>
      Optionally, enable the following options in the kernel configuration:
    </para>

<screen><literal>File systems  ---&gt;
  [*] Network File Systems  ---&gt;                                      [CONFIG_NETWORK_FILESYSTEMS]
    &lt;*/M&gt; NFS client support                                          [CONFIG_NFS_FS]
    &lt;*/M&gt; SMB3 and CIFS support (advanced network filesystem)         [CONFIG_CIFS]</literal></screen>

    <para>
      Recompile and install the new kernel, if necessary.
    </para>

  </sect2>

  <sect2 role="installation">

    <title>Installation of Autofs</title>

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

<screen revision="sysv"><userinput>./configure --prefix=/usr             \
            --with-mapdir=/etc/autofs \
            --with-libtirpc           \
            --without-openldap        \
            --mandir=/usr/share/man &amp;&amp;
make</userinput></screen>

<screen revision="systemd"><userinput>./configure --prefix=/usr             \
            --with-mapdir=/etc/autofs \
            --with-libtirpc           \
            --with-systemd            \
            --without-openldap        \
            --mandir=/usr/share/man &amp;&amp;
make</userinput></screen>

    <para>
      This package does not come with a test suite.
    </para>

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

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

<!-- As of version 5.1.5, the configuration files are not installed anymore -->
    <caution>
      <para>
        If <application>autofs</application> is already installed on your
        system, be sure to backup your configuration files. They'll be
        overwritten by the following command.
      </para>
    </caution>

    <para>
      Install the default configuration files, still as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make install_samples</userinput></screen>

  </sect2>

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

    <para>
      <parameter>--with-libtirpc</parameter>: This switch forces the package to
      use libtirpc for RPC functionality instead of relying on implementation
      from Glibc, which was removed in LFS 8.1.
    </para>

    <para revision="systemd">
      <parameter>--with-systemd</parameter>: This switch enables installation
      of the bundled systemd units.
    </para>

    <para>
      <parameter>--without-openldap</parameter>: This switch disables openldap
      if found.  If openldap is desired, omit this switch.  Note that openldap
      support in autofs requires <xref linkend="mitkrb"/>.
    </para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring Autofs</title>

    <sect3 id="autofs-config">
      <title>Config Files</title>

      <para>
        <filename>/etc/sysconfig/autofs.conf</filename>,
        <filename>/etc/autofs/auto.master</filename>,
        <filename>/etc/autofs/auto.misc</filename>, and
        <filename>/etc/autofs/auto.net</filename>
      </para>

      <indexterm zone="autofs autofs-config" >
        <primary sortas="e-etc-sysconfig-autofs.conf">/etc/sysconfig/autofs.conf</primary>
      </indexterm>

      <indexterm zone="autofs autofs-config">
        <primary sortas="e-etc-auto.master">/etc/autofs/auto.master</primary>
      </indexterm>

      <indexterm zone="autofs autofs-config">
        <primary sortas="e-etc-auto.misc">/etc/autofs/auto.misc</primary>
      </indexterm>

      <indexterm zone="autofs autofs-config">
        <primary sortas="e-etc-auto.net">/etc/autofs/auto.net</primary>
      </indexterm>

    </sect3>

    <sect3>
      <title>Configuration Information</title>

      <para>
        The installation process creates <filename>auto.master</filename>,
        <filename>auto.misc</filename>,  <filename>auto.smb</filename>, and
        <filename>auto.net</filename>. Replace the
        <filename>auto.master</filename> file with the following commands
        as the <systemitem class="username">root</systemitem> user:
      </para>

<screen role="root"><userinput>mv /etc/autofs/auto.master /etc/autofs/auto.master.bak &amp;&amp;
cat &gt; /etc/autofs/auto.master &lt;&lt; "EOF"
<literal># Begin /etc/autofs/auto.master

/media/auto  /etc/autofs/auto.misc  --ghost
#/home        /etc/autofs/auto.home

# End /etc/autofs/auto.master</literal>
EOF</userinput></screen>

      <para>
        This file creates a new media directory,
        <filename>/media/auto</filename> that will overlay any existing
        directory of the same name.  In this example, the file,
        <filename>/etc/autofs/auto.misc</filename>, has a line:
      </para>

<screen>cd   -fstype=iso9660,ro,nosuid,nodev :/dev/cdrom</screen>

      <para>
        that will mount a cdrom as <filename>/media/auto/cd</filename> if
        that directory is accessed.  The <option>--ghost</option> option tells
        the automounter to create <quote>ghost</quote> versions (i.e. empty
        directories) of all the mount points listed in the configuration file
        regardless whether any of the file systems are actually mounted or not.
        This is very convenient and highly recommended, because it will show
        you the available auto-mountable file systems as existing directories,
        even when their file systems aren't currently mounted. Without the
        <option>--ghost</option> option, you'll have to remember the names of
        the directories. As soon as you try to access one of them, the
        directory will be created and the file system will be mounted. When
        the file system gets unmounted again, the directory is destroyed too,
        unless the <option>--ghost</option> option was given.
      </para>

      <note>
        <para>
          An alternative method would be to specify another automount
          location such as <filename
          class='directory'>/var/lib/auto/cdrom</filename> and create a
          symbolic link from <filename
          class='directory'>/media/cdrom</filename> to the automount location.
        </para>
      </note>

      <para>
        The <filename>auto.misc</filename> file must be configured to your
        working hardware. The loaded configuration file should load your cdrom
        if <filename>/dev/cdrom</filename> is active or it can be edited to
        match your device setup.  Examples for floppies are available in the
        file and easily activated. Documentation for this file is available
        using the <command>man 5 autofs</command> command.
      </para>

      <para>
        In the second line, if enabled, a user's home directory would be
        mounted via NFS upon login.  The <filename>/etc/home.auto</filename>
        would need to exist and have an entry similar to:
      </para>

<screen>joe  example.org:/export/home/joe</screen>

      <para>
        where the directory <filename>/export/home/joe</filename> is
        exported via NFS from the system example.org.  NFS shares
        are covered on the next page.
      </para>

      <para>
        This package could also be used to mount SMB shares, however that
        feature is not configured in these instructions.  For additional
        configuration information, see the man pages for auto.master(5). There
        are also web resources such as this <ulink
        url='http://wiki.gentoo.org/wiki/AutoFS'>AUTOFS
        HOWTO</ulink> available.
      </para>

    </sect3>

    <sect3  id="autofs-init">
      <title><phrase revision="sysv">Boot Script</phrase>
             <phrase revision="systemd">Systemd Unit</phrase></title>

      <para revision="sysv">
        <application>autofs</application> installs its own
        boot script, but it has no capability for logging or visual conformance
        with other BLFS scripts. It will be replaced by an enhanced version.
      </para>

      <para revision="sysv">
        Install the <filename>/etc/init.d/autofs</filename>
        mount script included with the <xref linkend="bootscripts"/>
        package.
      </para>

      <para revision="systemd">
        To start <application>Autofs</application> at boot, enable the
        previously installed systemd unit by running the following command as
        the <systemitem class="username">root</systemitem> user:
      </para>

      <indexterm zone="autofs autofs-init">
        <primary sortas="f-autofs-init">autofs</primary>
      </indexterm>

<screen role="root" revision="sysv"><userinput>make install-autofs</userinput></screen>

<screen role="root" revision="systemd"><userinput>systemctl enable autofs</userinput></screen>

      <para revision="sysv">
        The time-out variable is set in
        <filename>/etc/sysconfig/autofs.conf</filename>. The installed file sets
        a default of 60 seconds of inactivity before unmounting the device.  A
        much shorter time may be necessary to protect buffer writing to a floppy
        if users tend to remove the media prior to the timeout setting.
      </para>

      <note revision="systemd">
        <para>
          You can also specify <envar>OPTIONS</envar> variable in the
          <filename>/etc/sysconfig/autofs</filename> file with any additional
          parameters that you might want to pass to the automount daemon.
        </para>
      </note>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Program</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>automount</seg>
        <seg>
          lookup_dir.so, lookup_file.so, lookup_files.so, lookup_hosts.so,
          lookup_ldap.so, lookup_multi.so, lookup_nis.so, lookup_nisplus.so,
          lookup_program.so, lookup_userhome.so, lookup_yp.so, mount_afs.so,
          mount_autofs.so, mount_bind.so, mount_changer.so, mount_ext2.so,
          mount_ext3.so, mount_ext4.so, mount_generic.so, mount_nfs.so,
          mount_nfs4.so, parse_amd.so, and parse_sun.so
           </seg>
        <seg>/usr/lib/autofs, /etc/autofs</seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="automount">
        <term><command>automount</command></term>
        <listitem>
          <para>
            is the daemon that performs the mounting when a request is
            made for the device
          </para>
          <indexterm zone="autofs automount">
            <primary sortas="b-automount">automount</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>