source: pst/scanning/sane.xml

trunk
Last change on this file was 8322ac92, checked in by Douglas R. Reno <renodr@…>, 6 weeks ago

sane: minor consistency changes
  • Property mode set to 100644
File size: 21.6 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 &lfs122_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</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 </sect2>
150
151 <sect2 role="kernel" id='sane-kernel'>
152 <title>Kernel Configuration, Drivers and Additional Packages</title>
153
154 <indexterm zone="sane sane-kernel">
155 <primary sortas="d-Scanning-devices">Scanning devices</primary>
156 </indexterm>
157
158 <para>
159 To access your scanner, you will probably need the related kernel
160 drivers and/or additional support packages. A SCSI scanner will need SCSI
161 drivers, a parallel port scanner needs parallel port support (you should
162 use enhanced EPP modes) and perhaps <ulink
163 url="http://cyberelk.net/tim/libieee1284/">libieee1284</ulink>, and a USB
164 scanner will need the <xref linkend="libusb"/> package. For HP devices,
165 you may need <ulink
166 url="https://sourceforge.net/projects/hplip/files/hplip/">hplip</ulink>.
167 Ensure you have the necessary drivers properly configured to access
168 the devices.
169 </para>
170
171 </sect2>
172
173 <sect2 role="installation">
174 <title>Installation of SANE</title>
175
176 <sect3>
177 <title>Installation of SANE Backends</title>
178
179 <para>
180 The <application>SANE</application> daemon should run with its own
181 group. Create this group by issuing the following command as the
182 &root; user:
183 </para>
184
185<screen role="root"><userinput>groupadd -g 70 scanner</userinput></screen>
186
187 <note>
188 <para>
189 <command>configure</command> assumes that the user building
190 <application>SANE</application> Backends is a member of the
191 <systemitem class="groupname">scanner</systemitem> group for testing
192 the existence of this group. As a result, the user building the
193 package needs to be added to the
194 <systemitem class="groupname">scanner</systemitem> group. Add the
195 user to the <systemitem class="groupname">scanner</systemitem> group
196 by issuing the following command as the &root; user:
197 </para>
198
199<screen role="root"><userinput>usermod -G scanner -a <replaceable>username</replaceable></userinput></screen>
200
201 <para>
202 After adding the <systemitem class="groupname">scanner</systemitem>
203 group as above, you will need to log out and back in to activate it.
204 </para>
205
206 </note>
207
208 <para>
209 For a USB scanner, if you are linking to <xref linkend="libusb"/>,
210 include the configure switch --enable-libusb_1_0. Install
211 <application>SANE</application> Backends by running the following
212 commands:
213 </para>
214
215<screen><userinput>sg scanner -c " \
216PYTHON=python3 ./configure --prefix=/usr \
217 --sysconfdir=/etc \
218 --localstatedir=/var \
219 --with-lockdir=/run/lock \
220 --docdir=/usr/share/doc/sane-backends-&sane-version;" &amp;&amp;
221make</userinput></screen>
222
223 <para>
224 To test the results, issue: <command>make check</command>.
225 </para>
226
227 <para>
228 Now, as the <systemitem class="username">root</systemitem> user:
229 </para>
230
231<screen role="root"><userinput>make install &amp;&amp;
232install -m 644 -v tools/udev/libsane.rules \
233 /etc/udev/rules.d/65-scanner.rules &amp;&amp;
234mkdir -p /run/lock/sane &amp;&amp;
235chgrp -v scanner /run/lock/sane</userinput></screen>
236
237 <para>
238 With the scanner on, run <command>scanimage -L</command> and the
239 name and location of the device should appear. Of course, you need the
240 device drivers configured, in order to run this test.
241 </para>
242
243 </sect3>
244
245<!--
246 <sect3>
247 <title>Installation of SANE Front Ends</title>
248
249 <para>
250 The <application>SANE</application>-frontends package
251 includes the graphical frontends <command>xscanimage</command> and
252 <command>xcam</command>, and a command-line frontend
253 <command>scanadf</command>. You don't need this package if you intend
254 to use one of the more advanced graphical frontends like
255 <xref linkend="xsane"/>. For a list of frontend packages, see
256 <ulink url="http://www.sane-project.org/sane-frontends.html"/>.
257 </para>
258
259 <para>
260 To install <application>SANE</application>-frontends,
261 use the following commands:
262 </para>
263
264<screen><userinput>tar -xf ../sane-frontends-&sane-fe-version;.tar.gz &amp;&amp;
265cd sane-frontends-&sane-fe-version; &amp;&amp;
266
267sed -i -e "/SANE_CAP_ALWAYS_SETTABLE/d" src/gtkglue.c &amp;&amp;
268./configure - -prefix=/usr - -mandir=/usr/share/man &amp;&amp;
269make</userinput></screen>
270
271 <para>
272 This package does not come with a test suite.
273 </para>
274
275 <para>
276 Now, as the <systemitem class="username">root</systemitem> user:
277 </para>
278
279<screen role="root"><userinput>make install &amp;&amp;
280install -v -m644 doc/sane.png xscanimage-icon-48x48-2.png \
281 /usr/share/sane</userinput></screen>
282
283 <para>
284 If <application>GIMP</application> was linked into the build and
285 you wish <application>GIMP</application> to use
286 <command>xscanimage</command> as a scanning plugin, issue the following
287 command as the <systemitem class="username">root</systemitem> user:
288 </para>
289
290<screen role="root"><userinput>ln -v -s ../../../../bin/xscanimage /usr/lib/gimp/2.0/plug-ins</userinput></screen>
291
292 <note>
293 <para>
294 If the plugin <command>xscanimage</command> is disabled in
295 <application>GIMP</application>'s menu, in order to enable it,
296 "create" a blank image using the menu or Ctrl-N. After that, it is
297 enabled.
298 </para>
299 </note>
300
301 </sect3>
302-->
303
304 </sect2>
305
306 <sect2 role="commands">
307 <title>Command Explanations</title>
308
309 <para>
310 <command>sg scanner -c "..."</command>: runs the command between double
311 quotes with principal group <systemitem
312 class="groupname">scanner</systemitem>. This may be needed if the user
313 has been newly added to group scanner, and has not logged out and in.
314 </para>
315
316 <para>
317 <parameter>PYTHON=python3</parameter>: This switch forces the build
318 system to use Python 3 instead of Python 2.
319 </para>
320
321 <para>
322 <parameter>--sysconfdir=/etc</parameter>: This switch installs the
323 configuration files in <filename class="directory">/etc/sane.d</filename>
324 instead of <filename class="directory">/usr/etc/sane.d</filename>.
325 </para>
326
327<!-- This option doesn't exist anymore as of 1.2.1, and the udev rule
328 references the usage of 'scanner' everywhere.
329 <para>
330 <parameter>- -with-group=scanner</parameter>: This parameter causes
331 the directory created for the locking files to be group owned by the
332 <systemitem class="groupname">scanner</systemitem> group instead of the
333 default <systemitem class="groupname">uucp</systemitem> group.
334 </para>
335-->
336
337 </sect2>
338
339 <sect2 role="configuration">
340 <title>Configuring SANE</title>
341
342 <sect3 id="sane-config">
343 <title>Config Files</title>
344
345 <para>
346 <filename>/etc/sane.d/*.conf</filename>
347 </para>
348
349 <indexterm zone="sane sane-config">
350 <primary sortas="e-etc-sane.d-conf">/etc/sane.d/*.conf</primary>
351 </indexterm>
352
353 </sect3>
354
355 <sect3>
356 <title>Configuration Information</title>
357
358 <sect4>
359 <title>Backend Configuration</title>
360
361 <para>
362 The backend configuration files are located in
363 <filename class='directory'>/etc/sane.d</filename>. Information
364 for configuring the various backends can be found by using the man(5)
365 page for the desired backend. Run
366 <command>
367 man sane-<replaceable>&lt;backend&gt;</replaceable></command>,
368 substituting the desired backend.
369 </para>
370
371 <para>
372 Add any users that will use a scanner to the <systemitem
373 class="groupname">scanner</systemitem> group.
374 </para>
375
376 <para>
377 If you want to access a network scanner, include two lines in
378 <filename>net.conf</filename>, as the &root; user (make sure to
379 replace &lt;server_ip&gt; by the actual value):
380 </para>
381
382<screen role="root"><userinput>cat &gt;&gt; /etc/sane.d/net.conf &lt;&lt; "EOF"
383<literal>connect_timeout = 60
384&lt;server_ip&gt;</literal>
385EOF</userinput></screen>
386
387 <para>
388 On the server side, include the client ip in the access list of
389 <filename>/etc/sane.d/saned.conf</filename>, restart the
390 <command>saned</command> daemon, and make sure the firewall, if any,
391 is open to the client.
392 </para>
393
394 </sect4>
395
396<!--
397 <sect4>
398 <title>Frontend Configuration</title>
399 <para>
400 If you use a desktop environment like <application>GNOME</application>
401 or <application>KDE</application> you may wish to create a
402 <filename>xscanimage.desktop</filename> file so that
403 <application>xscanimage</application> appears in the panel's menus.
404 Create the desktop file using the following commands as the &root; user:
405 </para>
406
407<screen role="root"><userinput>mkdir -pv /usr/share/{applications,pixmaps} &amp;&amp;
408
409cat &gt; /usr/share/applications/xscanimage.desktop &lt;&lt; "EOF" &amp;&amp;
410<literal>[Desktop Entry]
411Encoding=UTF-8
412Name=XScanImage - Scanning
413Comment=Acquire images from a scanner
414Exec=xscanimage
415Icon=xscanimage
416Terminal=false
417Type=Application
418Categories=Application;Graphics</literal>
419EOF
420
421ln -svf ../sane/xscanimage-icon-48x48-2.png /usr/share/pixmaps/xscanimage.png</userinput></screen>
422
423 </sect4>
424-->
425 <sect4>
426 <title>General Information</title>
427
428 <para>
429 For general information about configuring and using
430 <application>SANE</application>, see <command>man sane</command>.
431 For information about USB scanning devices,
432 run <command>man sane-usb</command>. For information about SCSI
433 devices, run <command>man sane-scsi</command>.
434 </para>
435
436 </sect4>
437
438 <sect4>
439 <title>Configuration and setup of the 'saned' daemon</title>
440
441 <para>
442 The <command>saned</command> daemon is not meant to be used for
443 untrusted clients. You should provide <xref linkend="fw-firewall"/>
444 protection to ensure only trusted clients access the daemon. Due to
445 the complex security requirements to ensure only trusted clients
446 access the daemon, BLFS does not provide
447 instructions to configure the <command>saned</command> daemon.
448 Some good (but outdated)
449 information for setting up and securing the <command>saned</command>
450 daemon can be found at
451 <ulink url="https://penguin-breeder.org/sane/saned/"/>.
452 </para>
453
454 </sect4>
455
456 </sect3>
457
458 </sect2>
459
460 <sect2 role="content">
461 <title>Contents</title>
462
463 <segmentedlist>
464 <segtitle>Installed Programs</segtitle>
465 <segtitle>Installed Libraries</segtitle>
466 <segtitle>Installed Directories</segtitle>
467
468 <seglistitem>
469 <seg>gamma4scanimage,
470 sane-config,
471 saned,
472 sane-find-scanner,
473 scanimage, and
474 umax_pp</seg>
475 <seg>libsane.so and numerous scanner backend modules</seg>
476 <seg>/etc/sane.d,
477 /usr/{include,lib,share}/sane,
478 and /usr/share/doc/sane-&sane-version;</seg>
479 </seglistitem>
480 </segmentedlist>
481
482<!--
483 <bridgehead renderas="sect4">Front Ends:</bridgehead>
484 <segmentedlist>
485 <segtitle>Installed Programs</segtitle>
486 <segtitle>Installed Library</segtitle>
487 <segtitle>Installed Directories</segtitle>
488
489 <seglistitem>
490 <seg>scanadf,
491 xcam, and
492 xscanimage</seg>
493 <seg><application>GIMP</application> plugin embedded in
494 <command>xscanimage</command></seg>
495 <seg>None</seg>
496 </seglistitem>
497 </segmentedlist>
498-->
499
500 <variablelist>
501 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
502 <?dbfo list-presentation="list"?>
503 <?dbhtml list-presentation="table"?>
504
505 <varlistentry id="gamma4scanimage">
506 <term><command>gamma4scanimage</command></term>
507 <listitem>
508 <para>
509 creates a gamma table in the format expected by
510 <command>scanimage</command>
511 </para>
512 <indexterm zone="sane gamma4scanimage">
513 <primary sortas="b-gamma4scanimage">gamma4scanimage</primary>
514 </indexterm>
515 </listitem>
516 </varlistentry>
517
518 <varlistentry id="sane-config-prog">
519 <term><command>sane-config</command></term>
520 <listitem>
521 <para>
522 is a tool used to determine the compiler and linker
523 flags that should be used to compile and link
524 <application>SANE</application>
525 </para>
526 <indexterm zone="sane sane-config-prog">
527 <primary sortas="b-sane-config">sane-config</primary>
528 </indexterm>
529 </listitem>
530 </varlistentry>
531
532 <varlistentry id="saned">
533 <term><command>saned</command></term>
534 <listitem>
535 <para>
536 is the <application>SANE</application> daemon that
537 allows remote clients to access image acquisition devices
538 available on the local host
539 </para>
540 <indexterm zone="sane saned">
541 <primary sortas="b-saned">saned</primary>
542 </indexterm>
543 </listitem>
544 </varlistentry>
545
546 <varlistentry id="sane-find-scanner">
547 <term><command>sane-find-scanner</command></term>
548 <listitem>
549 <para>
550 is a command-line tool to find SCSI and
551 USB scanners and determine their device files. Its primary
552 purpose is to make sure that scanners can be detected by
553 <application>SANE</application> backends
554 </para>
555 <indexterm zone="sane sane-find-scanner">
556 <primary sortas="b-sane-find-scanner">sane-find-scanner</primary>
557 </indexterm>
558 </listitem>
559 </varlistentry>
560
561<!--
562 <varlistentry id="scanadf">
563 <term><command>scanadf</command></term>
564 <listitem>
565 <para>
566 is a command-line interface to control image acquisition
567 devices which are equipped with an automatic document feeder (ADF)
568 </para>
569 <indexterm zone="sane scanadf">
570 <primary sortas="b-scanadf">scanadf</primary>
571 </indexterm>
572 </listitem>
573 </varlistentry>
574-->
575
576 <varlistentry id="scanimage">
577 <term><command>scanimage</command></term>
578 <listitem>
579 <para>
580 is a command line interface for scanning from image acquisition
581 devices such as flatbed scanners or cameras. It is also used to
582 list the available backend devices
583 </para>
584 <indexterm zone="sane scanimage">
585 <primary sortas="b-scanimage">scanimage</primary>
586 </indexterm>
587 </listitem>
588 </varlistentry>
589
590 <varlistentry id="umax_pp">
591 <term><command>umax_pp</command></term>
592 <listitem>
593 <para>
594 is a tool used to read information from UMAX parallel port
595 scanners. It can also be used for performing diagnostics on these
596 scanners
597 </para>
598 <indexterm zone="sane umax_pp">
599 <primary sortas="b-umax_pp">umax_pp</primary>
600 </indexterm>
601 </listitem>
602 </varlistentry>
603
604<!--
605 <varlistentry id="xcam">
606 <term><command>xcam</command></term>
607 <listitem>
608 <para>
609 is a graphical camera front end for
610 <application>SANE</application>
611 </para>
612 <indexterm zone="sane xcam">
613 <primary sortas="b-xcam">xcam</primary>
614 </indexterm>
615 </listitem>
616 </varlistentry>
617
618 <varlistentry id="xscanimage">
619 <term><command>xscanimage</command></term>
620 <listitem>
621 <para>
622 is a graphical user interface for scanning
623 </para>
624 <indexterm zone="sane xscanimage">
625 <primary sortas="b-xscanimage">xscanimage</primary>
626 </indexterm>
627 </listitem>
628 </varlistentry>
629-->
630 <varlistentry id="libsane">
631 <term><filename class="libraryfile">libsane.so</filename></term>
632 <listitem>
633 <para>
634 is the application programming interface that is used to
635 communicate between frontends and backends
636 </para>
637 <indexterm zone="sane libsane">
638 <primary sortas="c-libsane">libsane.so</primary>
639 </indexterm>
640 </listitem>
641 </varlistentry>
642
643 <varlistentry id="libsane-module">
644 <term><filename class="libraryfile">libsane-*.so</filename></term>
645 <listitem>
646 <para>
647 modules are backend scanning library plugins used to interface
648 with scanning devices. See
649 <ulink url="http://www.sane-project.org/sane-supported-devices.html"/>
650 for a list of supported backends
651 </para>
652 <indexterm zone="sane libsane-module">
653 <primary sortas="c-libsane-module">libsane-*.so</primary>
654 </indexterm>
655 </listitem>
656 </varlistentry>
657
658 </variablelist>
659
660 </sect2>
661
662</sect1>
Note: See TracBrowser for help on using the repository browser.