source: pst/scanning/sane.xml

trunk
Last change on this file was 6b33b5b, checked in by Bruce Dubbs <bdubbs@…>, 2 months ago

Finish tagging for chapters 46-50.
  • Property mode set to 100644
File size: 21.9 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY sane-be-download-http "&sources-anduin-http;/sane/sane-backends-&sane-version;.tar.gz">
8 <!ENTITY sane-be-download-ftp " ">
9 <!ENTITY sane-be-md5sum "302159419ed1ee216c6e1edbe97c2a8c">
10 <!ENTITY sane-be-size "6.9 MB">
11 <!ENTITY sane-be-buildsize "311 MB (with tests)">
12 <!ENTITY sane-be-time "0.7 SBU (Using parallelism=4; with tests)">
13
14<!--
15 <!ENTITY sane-fe-download-http "&sources-anduin-http;/sane/sane-frontends-&sane-fe-version;.tar.gz">
16 <!ENTITY sane-fe-download-ftp " ">
17 <!ENTITY sane-fe-md5sum "c63bf7b0bb5f530cf3c08715db721cd3">
18 <!ENTITY sane-fe-size "231 KB">
19 <!ENTITY sane-fe-buildsize "3.0 MB">
20 <!ENTITY sane-fe-time "less than 0.1 SBU">
21-->
22]>
23
24<sect1 id="sane" xreflabel="SANE-&sane-version;">
25 <?dbhtml filename="sane.html"?>
26
27
28 <title>SANE-&sane-version;</title>
29
30 <indexterm zone="sane">
31 <primary sortas="a-SANE">SANE</primary>
32 </indexterm>
33
34 <sect2 role="package">
35 <title>Introduction to SANE</title>
36
37 <para>
38 <application>SANE</application> is short for Scanner Access Now Easy.
39 Scanner access, however, is far from easy, since every vendor has their
40 own protocols. The only known protocol that should bring some unity into
41 this chaos is the TWAIN interface, but this is too imprecise to allow a
42 stable scanning framework. Therefore, <application>SANE</application>
43 comes with its own protocol, and the vendor drivers can't be used.
44 </para>
45
46 <para>
47 <application>SANE</application> is split into back ends and front ends.
48 The back ends are drivers for the supported scanners and cameras. The
49 front ends are user interfaces to access the backends.
50 </para>
51
52 &lfs121_checked;
53
54 <bridgehead renderas="sect3">Back Ends Package Information</bridgehead>
55 <itemizedlist spacing='compact'>
56 <listitem>
57 <para>
58 Download (HTTP): <ulink url="&sane-be-download-http;"/>
59 </para>
60 </listitem>
61 <listitem>
62 <para>
63 Download (FTP): <ulink url="&sane-be-download-ftp;"/>
64 </para>
65 </listitem>
66 <listitem>
67 <para>
68 Download MD5 sum: &sane-be-md5sum;
69 </para>
70 </listitem>
71 <listitem>
72 <para>
73 Download size: &sane-be-size;
74 </para>
75 </listitem>
76 <listitem>
77 <para>
78 Estimated disk space required: &sane-be-buildsize;
79 </para>
80 </listitem>
81 <listitem>
82 <para>
83 Estimated build time: &sane-be-time;
84 </para>
85 </listitem>
86 </itemizedlist>
87
88<!--
89 <bridgehead renderas="sect3">Additional Downloads (Front Ends)</bridgehead>
90 <itemizedlist spacing='compact'>
91 <listitem>
92 <para>
93 Download (HTTP): <ulink url="&sane-fe-download-http;"/>
94 </para>
95 </listitem>
96 <listitem>
97 <para>
98 Download (FTP): <ulink url="&sane-fe-download-ftp;"/>
99 </para>
100 </listitem>
101 <listitem>
102 <para>
103 Download MD5 sum: &sane-fe-md5sum;
104 </para>
105 </listitem>
106 <listitem>
107 <para>
108 Download size: &sane-fe-size;
109 </para>
110 </listitem>
111 <listitem>
112 <para>
113 Estimated disk space required: &sane-fe-buildsize;
114 </para>
115 </listitem>
116 <listitem>
117 <para>
118 Estimated build time: &sane-fe-time;
119 </para>
120 </listitem>
121 </itemizedlist>
122-->
123
124 <note>
125 <para>
126 The upstream location for this file is at
127 <ulink url="https://gitlab.com/sane-project"/> but
128 the file URL uses an embedded md5sum. For convenience,
129 the package has been copied to the location above.
130 </para>
131 </note>
132
133 <bridgehead renderas="sect3">SANE Dependencies</bridgehead>
134
135 <bridgehead renderas="sect4">Optional (Back Ends)</bridgehead>
136 <para role="optional">
137 <xref linkend="avahi"/>,
138 <xref linkend="cups"/>,
139 <xref linkend="libjpeg"/>,
140 <xref linkend="libtiff"/>,
141 <xref linkend="libusb"/>,
142 <xref linkend="v4l-utils"/>,
143 <ulink url="http://www.net-snmp.org/">Net-SNMP</ulink>,
144 <ulink url="http://cyberelk.net/tim/libieee1284/">libieee1284</ulink>,
145 <ulink url="http://www.gphoto.org/">libgphoto2</ulink>, and
146 <xref linkend="texlive"/> (or <xref linkend="tl-installer"/>)
147 </para>
148
149<!--
150 <bridgehead renderas="sect4">Optional (Front Ends)</bridgehead>
151 <para role="optional">
152 <xref linkend="x-window-system"/>,
153 <xref linkend="gtk2"/>, and
154 <xref linkend="gimp"/>
155 </para>
156-->
157
158 </sect2>
159
160 <sect2 role="kernel" id='sane-kernel'>
161 <title>Kernel Configuration, Drivers and Additional Packages</title>
162
163 <indexterm zone="sane sane-kernel">
164 <primary sortas="d-Scanning-devices">Scanning devices</primary>
165 </indexterm>
166
167 <para>
168 To access your scanner, you will probably need the related kernel
169 drivers and/or additional support packages. A SCSI scanner will need SCSI
170 drivers, a parallel port scanner needs parallel port support (you should
171 use enhanced EPP modes) and perhaps <ulink
172 url="http://cyberelk.net/tim/libieee1284/">libieee1284</ulink>, and a USB
173 scanner will need the <xref linkend="libusb"/> package. For HP devices,
174 you may need <ulink
175 url="https://sourceforge.net/projects/hplip/files/hplip/">hplip</ulink>.
176 Ensure you have the necessary drivers properly configured to access
177 the devices.
178 </para>
179
180 </sect2>
181
182 <sect2 role="installation">
183 <title>Installation of SANE</title>
184
185 <sect3>
186 <title>Installation of SANE Back Ends</title>
187
188 <para>
189 The <application>SANE</application> daemon should run with its own
190 group. Create this group by issuing the following command as the
191 &root; user:
192 </para>
193
194<screen role="root"><userinput>groupadd -g 70 scanner</userinput></screen>
195
196 <note>
197 <para>
198 <command>configure</command> assumes that the user building
199 <application>SANE</application>-backends is a member of the
200 <systemitem class="groupname">scanner</systemitem> group for testing
201 the existence of this group. As a result, the user building the
202 package needs to be added to the
203 <systemitem class="groupname">scanner</systemitem> group. Add the
204 user to the <systemitem class="groupname">scanner</systemitem> group
205 by issuing the following command as the &root; user:
206 </para>
207
208<screen role="root"><userinput>usermod -G scanner -a <replaceable>username</replaceable></userinput></screen>
209
210 <para>
211 After adding the <systemitem class="groupname">scanner</systemitem>
212 group as above, you will need to log out and back in to activate it.
213 </para>
214
215 </note>
216
217 <para>
218 For a USB scanner, if you are linking to <xref linkend="libusb"/>,
219 include the configure switch --enable-libusb_1_0. Install
220 <application>SANE</application>-backends by running the following
221 commands:
222 </para>
223
224<screen><userinput>sg scanner -c " \
225PYTHON=python3 ./configure --prefix=/usr \
226 --sysconfdir=/etc \
227 --localstatedir=/var \
228 --with-lockdir=/run/lock \
229 --docdir=/usr/share/doc/sane-backends-&sane-version;" &amp;&amp;
230make</userinput></screen>
231
232 <para>
233 To test the results, issue: <command>make check</command>.
234 </para>
235
236 <para>
237 Now, as the <systemitem class="username">root</systemitem> user:
238 </para>
239
240<screen role="root"><userinput>make install &amp;&amp;
241install -m 644 -v tools/udev/libsane.rules \
242 /etc/udev/rules.d/65-scanner.rules &amp;&amp;
243mkdir -p /run/lock/sane &amp;&amp;
244chgrp -v scanner /run/lock/sane</userinput></screen>
245
246 <para>
247 With the scanner on, run <command>scanimage -L</command> and the
248 name and location of the device should appear. Of course, you need the
249 device drivers configured, in order to run this test.
250 </para>
251
252 </sect3>
253
254<!--
255 <sect3>
256 <title>Installation of SANE Front Ends</title>
257
258 <para>
259 The <application>SANE</application>-frontends package
260 includes the graphical frontends <command>xscanimage</command> and
261 <command>xcam</command>, and a command-line frontend
262 <command>scanadf</command>. You don't need this package if you intend
263 to use one of the more advanced graphical frontends like
264 <xref linkend="xsane"/>. For a list of frontend packages, see
265 <ulink url="http://www.sane-project.org/sane-frontends.html"/>.
266 </para>
267
268 <para>
269 To install <application>SANE</application>-frontends,
270 use the following commands:
271 </para>
272
273<screen><userinput>tar -xf ../sane-frontends-&sane-fe-version;.tar.gz &amp;&amp;
274cd sane-frontends-&sane-fe-version; &amp;&amp;
275
276sed -i -e "/SANE_CAP_ALWAYS_SETTABLE/d" src/gtkglue.c &amp;&amp;
277./configure - -prefix=/usr - -mandir=/usr/share/man &amp;&amp;
278make</userinput></screen>
279
280 <para>
281 This package does not come with a test suite.
282 </para>
283
284 <para>
285 Now, as the <systemitem class="username">root</systemitem> user:
286 </para>
287
288<screen role="root"><userinput>make install &amp;&amp;
289install -v -m644 doc/sane.png xscanimage-icon-48x48-2.png \
290 /usr/share/sane</userinput></screen>
291
292 <para>
293 If <application>GIMP</application> was linked into the build and
294 you wish <application>GIMP</application> to use
295 <command>xscanimage</command> as a scanning plugin, issue the following
296 command as the <systemitem class="username">root</systemitem> user:
297 </para>
298
299<screen role="root"><userinput>ln -v -s ../../../../bin/xscanimage /usr/lib/gimp/2.0/plug-ins</userinput></screen>
300
301 <note>
302 <para>
303 If the plugin <command>xscanimage</command> is disabled in
304 <application>GIMP</application>'s menu, in order to enable it,
305 "create" a blank image using the menu or Ctrl-N. After that, it is
306 enabled.
307 </para>
308 </note>
309
310 </sect3>
311-->
312
313 </sect2>
314
315 <sect2 role="commands">
316 <title>Command Explanations</title>
317
318 <para>
319 <command>sg scanner -c "..."</command>: runs the command between double
320 quotes with principal group <systemitem
321 class="groupname">scanner</systemitem>. This may be needed if the user
322 has been newly added to group scanner, and has not logged out and in.
323 </para>
324
325 <para>
326 <parameter>PYTHON=python3</parameter>: This switch forces the build
327 system to use Python 3 instead of Python 2.
328 </para>
329
330 <para>
331 <parameter>--sysconfdir=/etc</parameter>: This switch installs the
332 configuration files in <filename class="directory">/etc/sane.d</filename>
333 instead of <filename class="directory">/usr/etc/sane.d</filename>.
334 </para>
335
336<!-- This option doesn't exist anymore as of 1.2.1, and the udev rule
337 references the usage of 'scanner' everywhere.
338 <para>
339 <parameter>- -with-group=scanner</parameter>: This parameter causes
340 the directory created for the locking files to be group owned by the
341 <systemitem class="groupname">scanner</systemitem> group instead of the
342 default <systemitem class="groupname">uucp</systemitem> group.
343 </para>
344-->
345
346 </sect2>
347
348 <sect2 role="configuration">
349 <title>Configuring SANE</title>
350
351 <sect3 id="sane-config">
352 <title>Config Files</title>
353
354 <para>
355 <filename>/etc/sane.d/*.conf</filename>
356 </para>
357
358 <indexterm zone="sane sane-config">
359 <primary sortas="e-etc-sane.d-conf">/etc/sane.d/*.conf</primary>
360 </indexterm>
361
362 </sect3>
363
364 <sect3>
365 <title>Configuration Information</title>
366
367 <sect4>
368 <title>Backend Configuration</title>
369
370 <para>
371 The backend configuration files are located in
372 <filename class='directory'>/etc/sane.d</filename>. Information
373 for configuring the various backends can be found by using the man(5)
374 page for the desired backend. Run
375 <command>
376 man sane-<replaceable>&lt;backend&gt;</replaceable></command>,
377 substituting the desired backend.
378 </para>
379
380 <para>
381 Add any users that will use a scanner to the <systemitem
382 class="groupname">scanner</systemitem> group.
383 </para>
384
385 <para>
386 If you want to access a network scanner, include two lines in
387 <filename>net.conf</filename>, as the &root; user (make sure to
388 replace &lt;server_ip&gt; by the actual value):
389 </para>
390
391<screen role="root"><userinput>cat &gt;&gt; /etc/sane.d/net.conf &lt;&lt; "EOF"
392<literal>connect_timeout = 60
393&lt;server_ip&gt;</literal>
394EOF</userinput></screen>
395
396 <para>
397 On the server side, include the client ip in the access list of
398 <filename>/etc/sane.d/saned.conf</filename>, restart the
399 <command>saned</command> daemon, and make sure the firewall, if any,
400 is open to the client.
401 </para>
402
403 </sect4>
404
405<!--
406 <sect4>
407 <title>Frontend Configuration</title>
408 <para>
409 If you use a desktop environment like <application>GNOME</application>
410 or <application>KDE</application> you may wish to create a
411 <filename>xscanimage.desktop</filename> file so that
412 <application>xscanimage</application> appears in the panel's menus.
413 Create the desktop file using the following commands as the &root; user:
414 </para>
415
416<screen role="root"><userinput>mkdir -pv /usr/share/{applications,pixmaps} &amp;&amp;
417
418cat &gt; /usr/share/applications/xscanimage.desktop &lt;&lt; "EOF" &amp;&amp;
419<literal>[Desktop Entry]
420Encoding=UTF-8
421Name=XScanImage - Scanning
422Comment=Acquire images from a scanner
423Exec=xscanimage
424Icon=xscanimage
425Terminal=false
426Type=Application
427Categories=Application;Graphics</literal>
428EOF
429
430ln -svf ../sane/xscanimage-icon-48x48-2.png /usr/share/pixmaps/xscanimage.png</userinput></screen>
431
432 </sect4>
433-->
434 <sect4>
435 <title>General Information</title>
436
437 <para>
438 For general information about configuring and using
439 <application>SANE</application>, see <command>man sane</command>.
440 For information about USB scanning devices,
441 run <command>man sane-usb</command>. For information about SCSI
442 devices, run <command>man sane-scsi</command>.
443 </para>
444
445 </sect4>
446
447 <sect4>
448 <title>Configuration and setup of the 'saned' daemon</title>
449
450 <para>
451 The <command>saned</command> daemon is not meant to be used for
452 untrusted clients. You should provide <xref linkend="fw-firewall"/>
453 protection to ensure only trusted clients access the daemon. Due to
454 the complex security requirements to ensure only trusted clients
455 access the daemon, BLFS does not provide
456 instructions to configure the <command>saned</command> daemon.
457 Some good (but outdated)
458 information for setting up and securing the <command>saned</command>
459 daemon can be found at
460 <ulink url="https://penguin-breeder.org/sane/saned/"/>.
461 </para>
462
463 </sect4>
464
465 </sect3>
466
467 </sect2>
468
469 <sect2 role="content">
470 <title>Contents</title>
471
472 <segmentedlist>
473 <segtitle>Installed Programs</segtitle>
474 <segtitle>Installed Libraries</segtitle>
475 <segtitle>Installed Directories</segtitle>
476
477 <seglistitem>
478 <seg>gamma4scanimage,
479 sane-config,
480 saned,
481 sane-find-scanner,
482 scanimage, and
483 umax_pp</seg>
484 <seg>libsane.so and numerous scanner backend modules</seg>
485 <seg>/etc/sane.d,
486 /usr/{include,lib,share}/sane,
487 and /usr/share/doc/sane-&sane-version;</seg>
488 </seglistitem>
489 </segmentedlist>
490
491<!--
492 <bridgehead renderas="sect4">Front Ends:</bridgehead>
493 <segmentedlist>
494 <segtitle>Installed Programs</segtitle>
495 <segtitle>Installed Library</segtitle>
496 <segtitle>Installed Directories</segtitle>
497
498 <seglistitem>
499 <seg>scanadf,
500 xcam, and
501 xscanimage</seg>
502 <seg><application>GIMP</application> plugin embedded in
503 <command>xscanimage</command></seg>
504 <seg>None</seg>
505 </seglistitem>
506 </segmentedlist>
507-->
508
509 <variablelist>
510 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
511 <?dbfo list-presentation="list"?>
512 <?dbhtml list-presentation="table"?>
513
514 <varlistentry id="gamma4scanimage">
515 <term><command>gamma4scanimage</command></term>
516 <listitem>
517 <para>
518 creates a gamma table in the format expected by
519 <command>scanimage</command>
520 </para>
521 <indexterm zone="sane gamma4scanimage">
522 <primary sortas="b-gamma4scanimage">gamma4scanimage</primary>
523 </indexterm>
524 </listitem>
525 </varlistentry>
526
527 <varlistentry id="sane-config-prog">
528 <term><command>sane-config</command></term>
529 <listitem>
530 <para>
531 is a tool used to determine the compiler and linker
532 flags that should be used to compile and link
533 <application>SANE</application>
534 </para>
535 <indexterm zone="sane sane-config-prog">
536 <primary sortas="b-sane-config">sane-config</primary>
537 </indexterm>
538 </listitem>
539 </varlistentry>
540
541 <varlistentry id="saned">
542 <term><command>saned</command></term>
543 <listitem>
544 <para>
545 is the <application>SANE</application> daemon that
546 allows remote clients to access image acquisition devices
547 available on the local host
548 </para>
549 <indexterm zone="sane saned">
550 <primary sortas="b-saned">saned</primary>
551 </indexterm>
552 </listitem>
553 </varlistentry>
554
555 <varlistentry id="sane-find-scanner">
556 <term><command>sane-find-scanner</command></term>
557 <listitem>
558 <para>
559 is a command-line tool to find SCSI and
560 USB scanners and determine their device files. Its primary
561 purpose is to make sure that scanners can be detected by
562 <application>SANE</application> backends
563 </para>
564 <indexterm zone="sane sane-find-scanner">
565 <primary sortas="b-sane-find-scanner">sane-find-scanner</primary>
566 </indexterm>
567 </listitem>
568 </varlistentry>
569
570<!--
571 <varlistentry id="scanadf">
572 <term><command>scanadf</command></term>
573 <listitem>
574 <para>
575 is a command-line interface to control image acquisition
576 devices which are equipped with an automatic document feeder (ADF)
577 </para>
578 <indexterm zone="sane scanadf">
579 <primary sortas="b-scanadf">scanadf</primary>
580 </indexterm>
581 </listitem>
582 </varlistentry>
583-->
584
585 <varlistentry id="scanimage">
586 <term><command>scanimage</command></term>
587 <listitem>
588 <para>
589 is a command line interface for scanning from image acquisition
590 devices such as flatbed scanners or cameras. It is also used to
591 list the available backend devices
592 </para>
593 <indexterm zone="sane scanimage">
594 <primary sortas="b-scanimage">scanimage</primary>
595 </indexterm>
596 </listitem>
597 </varlistentry>
598
599 <varlistentry id="umax_pp">
600 <term><command>umax_pp</command></term>
601 <listitem>
602 <para>
603 is a tool used to read information from UMAX parallel port
604 scanners. It can also be used for performing diagnostics on these
605 scanners
606 </para>
607 <indexterm zone="sane umax_pp">
608 <primary sortas="b-umax_pp">umax_pp</primary>
609 </indexterm>
610 </listitem>
611 </varlistentry>
612
613<!--
614 <varlistentry id="xcam">
615 <term><command>xcam</command></term>
616 <listitem>
617 <para>
618 is a graphical camera front end for
619 <application>SANE</application>
620 </para>
621 <indexterm zone="sane xcam">
622 <primary sortas="b-xcam">xcam</primary>
623 </indexterm>
624 </listitem>
625 </varlistentry>
626
627 <varlistentry id="xscanimage">
628 <term><command>xscanimage</command></term>
629 <listitem>
630 <para>
631 is a graphical user interface for scanning
632 </para>
633 <indexterm zone="sane xscanimage">
634 <primary sortas="b-xscanimage">xscanimage</primary>
635 </indexterm>
636 </listitem>
637 </varlistentry>
638-->
639 <varlistentry id="libsane">
640 <term><filename class="libraryfile">libsane.so</filename></term>
641 <listitem>
642 <para>
643 is the application programming interface that is used to
644 communicate between frontends and backends
645 </para>
646 <indexterm zone="sane libsane">
647 <primary sortas="c-libsane">libsane.so</primary>
648 </indexterm>
649 </listitem>
650 </varlistentry>
651
652 <varlistentry id="libsane-module">
653 <term><filename class="libraryfile">libsane-*.so</filename></term>
654 <listitem>
655 <para>
656 modules are backend scanning library plugins used to interface
657 with scanning devices. See
658 <ulink url="http://www.sane-project.org/sane-supported-devices.html"/>
659 for a list of supported backends
660 </para>
661 <indexterm zone="sane libsane-module">
662 <primary sortas="c-libsane-module">libsane-*.so</primary>
663 </indexterm>
664 </listitem>
665 </varlistentry>
666
667 </variablelist>
668
669 </sect2>
670
671</sect1>
Note: See TracBrowser for help on using the repository browser.