source: pst/scanning/sane.xml@ be2215e

<?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 sane-be-download-http "http://fossies.org/linux/misc/sane-backends-&sane-version;.tar.gz">
  <!ENTITY sane-be-download-ftp  " ">
  <!ENTITY sane-be-md5sum        "b10a08785f92a4c07ad961f4d843c934">
  <!ENTITY sane-be-size          "8.2 MB">
  <!ENTITY sane-be-buildsize     "118 MB (with tests)">
  <!ENTITY sane-be-time          "1.0 SBU (with tests)">

  <!ENTITY sane-fe-download-http "&sources-anduin-http;/sane-frontends/sane-frontends-&sane-fe-version;.tar.gz">
  <!ENTITY sane-fe-download-ftp  " ">
  <!ENTITY sane-fe-md5sum        "c63bf7b0bb5f530cf3c08715db721cd3">
  <!ENTITY sane-fe-size          "231 KB">
  <!ENTITY sane-fe-buildsize     "3.0 MB">
  <!ENTITY sane-fe-time          "less than 0.1 SBU">
]>

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

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>SANE-&sane-version;</title>

  <indexterm zone="sane">
    <primary sortas="a-SANE">SANE</primary>
  </indexterm>

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

    <para><application>SANE</application> is short for Scanner Access Now Easy.
    Scanner access, however, is far from easy, since every vendor has their own
    protocols. The only known protocol that should bring some unity into this
    chaos is the TWAIN interface, but this is too imprecise to allow a stable
    scanning framework. Therefore, <application>SANE</application> comes with
    its own protocol, and the vendor drivers can't be used.</para>

    <para><application>SANE</application> is split into back ends and front
    ends. The back ends are drivers for the supported scanners and cameras. The
    front ends are user interfaces to access the backends.</para>

    &lfs84_checked;

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

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

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

    <bridgehead renderas="sect4">Optional (Back Ends)</bridgehead>
    <para role="optional">
      <xref linkend="avahi"/>,
      <xref linkend="cups"/>,
      <xref linkend="libjpeg"/>,
      <xref linkend="libtiff"/>,
      <xref linkend="libusb"/>,
      <xref linkend="v4l-utils"/>,
      <ulink url="http://www.net-snmp.org/">Net-SNMP</ulink>,
      <ulink url="http://cyberelk.net/tim/libieee1284/">libieee1284</ulink>,
      <ulink url="http://www.gphoto.org/">libgphoto2</ulink>, and
      <xref linkend="texlive"/> (or <xref linkend="tl-installer"/>)
    </para>

    <bridgehead renderas="sect4">Optional (Front Ends)</bridgehead>
    <para role="optional">
      <xref linkend="x-window-system"/>,
      <xref linkend="gtk2"/>, and
      <xref linkend="gimp"/>
    </para>

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

  </sect2>

  <sect2 role="kernel" id='sane-kernel'>
    <title>Kernel Configuration, Drivers and Additional Packages</title>

    <indexterm zone="sane sane-kernel">
      <primary sortas="d-Scanning-devices">Scanning devices</primary>
    </indexterm>

    <para>To access your scanner, you will probably need the related kernel
    drivers and/or additional support packages. A SCSI scanner will need SCSI
    drivers, a parallel port scanner needs parallel port support (you should
    use enhanced EPP modes) and perhaps <ulink
    url="http://cyberelk.net/tim/libieee1284/">libieee1284</ulink>, and a USB
    scanner will need the <xref linkend="libusb"/> package. For HP devices, you
    may need <ulink
    url="http://sourceforge.net/projects/hplip/files/hplip/">hplip</ulink>.
    Ensure you have the necessary drivers properly configured to access
    the devices.</para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of SANE</title>

    <sect3>
      <title>Installation of SANE Back Ends</title>

      <para>The <application>SANE</application> daemon should run with its own
      group.  Create this group by issuing the following commands as the
      <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>groupadd -g 70 scanner</userinput></screen>

      <note>
        <para>
          The user building <application>SANE</application>-backends should be
          a member of the <systemitem class="groupname">scanner</systemitem>
          group before proceeding. After you have added the user building the
          package to the <systemitem class="groupname">scanner</systemitem>
          group, issue the following command to create a new shell:
        </para>

<screen><userinput>su $(whoami)</userinput></screen>

        <para>
          Check the output of the <userinput>groups</userinput> command and
          ensure the user is a member of the
          <systemitem class="groupname">scanner</systemitem> group.
        </para>
      </note>

      <para>For a USB scanner, if you are linking to <xref linkend="libusb"/>,
      include the configure switch --enable-libusb_1_0. Install
      <application>SANE</application>-backends by running the following
      commands:</para>

<screen><userinput>./configure --prefix=/usr        \
            --sysconfdir=/etc    \
            --localstatedir=/var \
            --with-group=scanner \
            --with-docdir=/usr/share/doc/sane-backends-&sane-version; &amp;&amp;
make</userinput></screen>

      <para>To test the results, issue: <command>make check</command>.</para>

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

<screen role="root"><userinput>make install                                         &amp;&amp;
install -m 644 -v tools/udev/libsane.rules           \
                  /etc/udev/rules.d/65-scanner.rules &amp;&amp;
chgrp -v scanner  /var/lock/sane</userinput></screen>

      <para>With the scanner on, run <command>scanimage -L</command> and the
      name and location of the device should appear. Of course, you need the
      device drivers configured, in order to run this test.</para>

    </sect3>

    <sect3>
      <title>Installation of SANE Front Ends</title>

      <para>The <application>SANE</application>-frontends package
      includes the graphical frontends <command>xscanimage</command> and
      <command>xcam</command>, and a command-line frontend
      <command>scanadf</command>. You don't need this package if you intend
      to use one of the more advanced graphical frontends like
      <xref linkend="xsane"/>. For a list of frontend packages, see
      <ulink url="http://www.sane-project.org/sane-frontends.html"/>.</para>

      <para>To install <application>SANE</application>-frontends,
      use the following commands:</para>

<screen><userinput>sed -i -e "/SANE_CAP_ALWAYS_SETTABLE/d" src/gtkglue.c &amp;&amp;
./configure --prefix=/usr --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 &amp;&amp;
install -v -m644 doc/sane.png xscanimage-icon-48x48-2.png \
    /usr/share/sane</userinput></screen>

      <para>If <application>GIMP</application> was linked into the build and
      you wish <application>GIMP</application> to use
      <command>xscanimage</command> as a scanning plugin, issue the following
      command as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>ln -v -s ../../../../bin/xscanimage /usr/lib/gimp/2.0/plug-ins</userinput></screen>

      <note>
        <para>
          If the plugin <command>xscanimage</command> is disabled in
          <application>GIMP</application>'s menu, in order to enable it,
          "create" a blank image using the menu or Ctrl-N. After that, it is
          enabled.
        </para>
      </note>

    </sect3>

  </sect2>

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

    <para><parameter>--sysconfdir=/etc</parameter>: This switch installs the
    configuration files in <filename class="directory">/etc/sane.d</filename>
    instead of <filename class="directory">/usr/etc/sane.d</filename>.</para>

    <para><parameter>--with-group=scanner</parameter>: This parameter causes
    the directory created for the locking files to be group owned by the
    <systemitem class="groupname">scanner</systemitem> group instead of the
    default <systemitem class="groupname">uucp</systemitem> group.</para>

    <para><command>exit</command>: This command is used to exit the shell
    created by the <command>su</command> command.</para>
  </sect2>

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

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

      <para><filename>/etc/sane.d/*.conf</filename></para>

      <indexterm zone="sane sane-config">
        <primary sortas="e-etc-sane.d-conf">/etc/sane.d/*.conf</primary>
      </indexterm>

    </sect3>

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

      <sect4>
        <title>Backend Configuration</title>

        <para>The backend configuration files are located in
        <filename class='directory'>/etc/sane.d</filename>. Information
        for configuring the various backends can be found by using the man(5)
        page for the desired backend. Run
        <command>man sane-<replaceable>&lt;backend&gt;</replaceable></command>,
        substituting the desired backend.</para>

        <para>Add any desired users to the <systemitem
        class="groupname">scanner</systemitem> group.</para>

        <para>If you want to access a network scanner, include two lines in
        <filename>net.conf</filename>, as <systemitem class="username">root</systemitem> user
        (make sure to replace &lt;server_ip&gt; by the actual value, below):</para>

<screen role="root"><userinput>cat &gt;&gt; /etc/sane.d/net.conf &lt;&lt; "EOF"
connect_timeout = 60
&lt;server_ip&gt;
EOF</userinput></screen>

        <para>On the server side, include the client ip in the access list of
        <filename>/etc/sane.d/saned.conf</filename>, restart the
        <command>saned</command> daemon, and make sure the firewall, if any, is
        open to the client.</para>

      </sect4>

      <sect4>
        <title>Frontend Configuration</title>
        <para>
          If you use a desktop environment like <application>Gnome</application>
          or <application>KDE</application> you may wish to create a
          <filename>xscanimage.desktop</filename> file so that
          <application>xscanimage</application> appears in the panel's menus.
          As the <systemitem class="username">root</systemitem> user:
        </para>

<screen role="root"><userinput>mkdir -pv /usr/share/{applications,pixmaps}               &amp;&amp;

cat &gt; /usr/share/applications/xscanimage.desktop &lt;&lt; "EOF" &amp;&amp;
[Desktop Entry]
Encoding=UTF-8
Name=XScanImage - Scanning
Comment=Acquire images from a scanner
Exec=xscanimage
Icon=xscanimage
Terminal=false
Type=Application
Categories=Application;Graphics
EOF

ln -svf ../sane/xscanimage-icon-48x48-2.png /usr/share/pixmaps/xscanimage.png</userinput></screen>

      </sect4>

      <sect4>
        <title>General Information</title>

        <para>For general information about configuring and using
        <application>SANE</application>, see <command>man sane</command>.
        Linux-2.6.x brings some special issues into the picture. See
        <ulink url="http://www.sane-project.org/README.linux"/> for
        information about using <application>SANE</application> with the
        Linux-2.6.x kernel. For information about USB scanning devices,
        run <command>man sane-usb</command>. For information about SCSI
        devices, run <command>man sane-scsi</command>.</para>

      </sect4>

      <sect4>
        <title>Configuration and setup of the 'saned' daemon</title>

        <para>The <command>saned</command> daemon is not meant to be used for
        untrusted clients. You should provide <xref linkend="fw-firewall"/>
        protection to ensure only trusted
        clients access the daemon. Due to the complex security requirements to
        ensure only trusted clients access the daemon, BLFS does not provide
        instructions to configure the <command>saned</command> daemon. If you
        desire to make the daemon available, ensure you provide adequate
        security, configure your <filename>[x]inetd.conf</filename> file and
        send a <userinput>SIGHUP</userinput> to the [x]inetd daemon. Some good
        information for setting up and securing the <command>saned</command>
        daemon can be found at
        <ulink url="http://penguin-breeder.org/sane/saned/"/>.</para>

      </sect4>

    </sect3>

  </sect2>

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

    <bridgehead renderas="sect4">Back Ends:</bridgehead>
    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>gamma4scanimage, sane-config, saned, sane-find-scanner,
        and scanimage</seg>
        <seg>libsane.so and numerous scanner backend modules</seg>
        <seg>/etc/sane.d, /usr/{include,lib,share}/sane,
        and /usr/share/doc/sane-&sane-version;</seg>
      </seglistitem>
    </segmentedlist>

    <bridgehead renderas="sect4">Front Ends:</bridgehead>
    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Library</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>scanadf, xcam, and xscanimage</seg>
        <seg><application>GIMP</application> plugin embedded in
        <command>xscanimage</command></seg>
        <seg>None</seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="gamma4scanimage">
        <term><command>gamma4scanimage</command></term>
        <listitem>
          <para>creates a gamma table in the format expected by
          <command>scanimage</command>.</para>
          <indexterm zone="sane gamma4scanimage">
            <primary sortas="b-gamma4scanimage">gamma4scanimage</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="sane-config-prog">
        <term><command>sane-config</command></term>
        <listitem>
          <para>is a tool used to determine the compiler and linker
          flags that should be used to compile and link
          <application>SANE</application>.</para>
          <indexterm zone="sane sane-config-prog">
            <primary sortas="b-sane-config">sane-config</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="saned">
        <term><command>saned</command></term>
        <listitem>
          <para>is the <application>SANE</application> daemon that
          allows remote clients to access image acquisition devices
          available on the local host.</para>
          <indexterm zone="sane saned">
            <primary sortas="b-saned">saned</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="sane-find-scanner">
        <term><command>sane-find-scanner</command></term>
        <listitem>
          <para>is a command-line tool to find SCSI and
          USB scanners and determine their device files. Its primary
          purpose is to make sure that scanners can be detected by
          <application>SANE</application> backends.</para>
          <indexterm zone="sane sane-find-scanner">
            <primary sortas="b-sane-find-scanner">sane-find-scanner</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="scanadf">
        <term><command>scanadf</command></term>
        <listitem>
          <para>is a command-line interface to control image acquisition
          devices which are equipped with an automatic document feeder
          (ADF).</para>
          <indexterm zone="sane scanadf">
            <primary sortas="b-scanadf">scanadf</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="scanimage">
        <term><command>scanimage</command></term>
        <listitem>
          <para>is a command line interface for scanning from image acquisition
          devices such as flatbed scanners or cameras. It is also used to list
          the available backend devices.</para>
          <indexterm zone="sane scanimage">
            <primary sortas="b-scanimage">scanimage</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="xcam">
        <term><command>xcam</command></term>
        <listitem>
          <para>is a graphical camera front end for
          <application>SANE</application>.</para>
          <indexterm zone="sane xcam">
            <primary sortas="b-xcam">xcam</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="xscanimage">
        <term><command>xscanimage</command></term>
        <listitem>
          <para>is a graphical user interface for scanning.</para>
          <indexterm zone="sane xscanimage">
            <primary sortas="b-xscanimage">xscanimage</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libsane">
        <term><filename class='libraryfile'>libsane.so</filename></term>
        <listitem>
          <para>is the application programming interface that is used to
          communicate between frontends and backends.</para>
          <indexterm zone="sane libsane">
            <primary sortas="c-libsane">libsane.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libsane-module">
        <term><filename class='libraryfile'>libsane-*.so</filename></term>
        <listitem>
          <para>modules are backend scanning library plugins used to interface
          with scanning devices. See
          <ulink url="http://www.sane-project.org/sane-supported-devices.html"/>
          for a list of supported backends.</para>
          <indexterm zone="sane libsane-module">
            <primary sortas="c-libsane-module">libsane-*.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>