lfs-ru/chapter12/pst/scanning/sane.xml
2024-04-09 10:13:26 +05:00

672 lines
22 KiB
XML

<?xml version="1.0" encoding="UTF-8"?>
<!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 "&sources-anduin-http;/sane/sane-backends-&sane-version;.tar.gz">
<!ENTITY sane-be-download-ftp " ">
<!ENTITY sane-be-md5sum "302159419ed1ee216c6e1edbe97c2a8c">
<!ENTITY sane-be-size "6.9 MB">
<!ENTITY sane-be-buildsize "311 MB (with tests)">
<!ENTITY sane-be-time "0.7 SBU (Using parallelism=4; with tests)">
<!--
<!ENTITY sane-fe-download-http "&sources-anduin-http;/sane/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"?>
<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>
&lfs121_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">Additional Downloads (Front Ends)</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>
Download 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>
-->
<note>
<para>
The upstream location for this file is at
<ulink url="https://gitlab.com/sane-project"/> but
the file URL uses an embedded md5sum. For convenience,
the package has been copied to the location above.
</para>
</note>
<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>
-->
</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="https://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 command as the
&root; user:
</para>
<screen role="root"><userinput>groupadd -g 70 scanner</userinput></screen>
<note>
<para>
<command>configure</command> assumes that the user building
<application>SANE</application>-backends is a member of the
<systemitem class="groupname">scanner</systemitem> group for testing
the existence of this group. As a result, the user building the
package needs to be added to the
<systemitem class="groupname">scanner</systemitem> group. Add the
user to the <systemitem class="groupname">scanner</systemitem> group
by issuing the following command as the &root; user:
</para>
<screen role="root"><userinput>usermod -G scanner -a <replaceable>username</replaceable></userinput></screen>
<para>
After adding the <systemitem class="groupname">scanner</systemitem>
group as above, you will need to log out and back in to activate it.
</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>sg scanner -c " \
PYTHON=python3 ./configure --prefix=/usr \
--sysconfdir=/etc \
--localstatedir=/var \
--with-lockdir=/run/lock \
--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;
mkdir -p /run/lock/sane &amp;&amp;
chgrp -v scanner /run/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>tar -xf ../sane-frontends-&sane-fe-version;.tar.gz &amp;&amp;
cd sane-frontends-&sane-fe-version; &amp;&amp;
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>
<command>sg scanner -c "..."</command>: runs the command between double
quotes with principal group <systemitem
class="groupname">scanner</systemitem>. This may be needed if the user
has been newly added to group scanner, and has not logged out and in.
</para>
<para>
<parameter>PYTHON=python3</parameter>: This switch forces the build
system to use Python 3 instead of Python 2.
</para>
<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>
<!-- This option doesn't exist anymore as of 1.2.1, and the udev rule
references the usage of 'scanner' everywhere.
<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>
-->
</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 users that will use a scanner 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 the &root; user (make sure to
replace &lt;server_ip&gt; by the actual value):
</para>
<screen role="root"><userinput>cat &gt;&gt; /etc/sane.d/net.conf &lt;&lt; "EOF"
<literal>connect_timeout = 60
&lt;server_ip&gt;</literal>
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.
Create the desktop file using the following commands as the &root; 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;
<literal>[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</literal>
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>.
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.
Some good (but outdated)
information for setting up and securing the <command>saned</command>
daemon can be found at
<ulink url="https://penguin-breeder.org/sane/saned/"/>.
</para>
</sect4>
</sect3>
</sect2>
<sect2 role="content">
<title>Contents</title>
<segmentedlist>
<segtitle>Installed Programs</segtitle>
<segtitle>Installed Libraries</segtitle>
<segtitle>Installed Directories</segtitle>
<seglistitem>
<seg>gamma4scanimage,
sane-config,
saned,
sane-find-scanner,
scanimage, and
umax_pp</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="umax_pp">
<term><command>umax_pp</command></term>
<listitem>
<para>
is a tool used to read information from UMAX parallel port
scanners. It can also be used for performing diagnostics on these
scanners
</para>
<indexterm zone="sane umax_pp">
<primary sortas="b-umax_pp">umax_pp</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>