summaryrefslogtreecommitdiff
path: root/debian/libsane.README.Debian
diff options
context:
space:
mode:
Diffstat (limited to 'debian/libsane.README.Debian')
-rw-r--r--debian/libsane.README.Debian172
1 files changed, 172 insertions, 0 deletions
diff --git a/debian/libsane.README.Debian b/debian/libsane.README.Debian
new file mode 100644
index 0000000..70277d0
--- /dev/null
+++ b/debian/libsane.README.Debian
@@ -0,0 +1,172 @@
+libsane (sane-backends) for Debian :
+------------------------------------
+
+GENERAL
+-------
+
+The configuration files for Debian releases of SANE are located in /etc/sane.d.
+
+The dll pseudo-backend is responsible for loading other SANE backends that
+provide support for the actual hardware. Which backends are loaded is
+determined by the contents of the /etc/sane.d/dll.conf file. The dll
+pseudo-backend also checks for dll.conf snippets in /etc/sane.d/dll.d; any
+file in this directory that doesn't look like a backup file will be treated
+as a configuration snippet.
+
+This facility is used by packages providing external backends (like
+hpoj or hplip) to "register" the backends they provide without
+much hassle.
+
+Each backend has a configuration file which specifies which devices,
+access methods, options etc. should be used by this backend. The format
+and content of each configuration file is documented in the manpage for
+the backend, e.g. sane-plustek (5).
+
+For USB and some SCSI scanners, the parameters can be auto-detected, and
+manual configuration is not required. If the auto-detection fails, read
+the next paragraph. Again, see the manpage for your backend for more
+information.
+
+For SCSI devices (mostly scanners), the configuration files use the
+/dev/scanner device; /dev/scanner is a symbolic link to the appropriate
+SCSI device node. It's up to you to create this symbolic link, once you
+will have determined which device node it needs to point to. Use the
+sane-find-scanner command in the sane-utils package to determine which
+SCSI device your scanner is attached to. The sane-find-scanner utility
+also discovers USB scanners.
+
+It can be a good idea to try running sane-find-scanner as root to ensure
+there will be no permissions problems while attempting to detect your
+devices.
+
+
+DOCUMENTATION
+-------------
+
+For information on configuring and trouble-shooting the various SANE
+components, please refer to the manual pages listed below:
+
+ Regarding: Read:
+ ----------------- ------------------------------------------
+ General sane(7) -- your starting point
+
+ scanimage scanimage(1)
+ xscanimage xscanimage(1)
+ saned saned(8)
+ xcam xcam(1)
+
+ Dynamic loading sane-dll(5)
+ Backends See sane-<backend name>(5). Each backend
+ comes with a manual page in section 5 of
+ the manual system.
+
+
+SETUP
+-----
+
+In this day and age, SANE integrates with udev and ConsoleKit/systemd-logind
+seemlessly; this means users physically logged into the machine (as opposed
+to users logged in remotely via SSH) have access to the scanners by default.
+
+The solution proposed below is a legacy setup that remains valid for sharing
+scanners with saned or for systems that don't use ConsoleKit/systemd-logind.
+Note that this is only a proposed solution, you are free to come up with and
+implement whatever access control mechanism you see fit.
+
+This package added a scanner group to your system. We recommend you add to
+this group the users that should be able to access your scanner(s), and
+make sure the appropriate device files (eg. /dev/sg0, ...) are owned by root
+and the scanner group, with permissions set to 0660.
+
+For USB and SCSI scanners, the permissions will be automatically set by udev;
+the /lib/udev/rules.d/60-libsane.rules file contains a list of USB and SCSI
+scanners supported by SANE.
+
+The udev rules now use ACLs instead of standard UNIX permissions; the scanner
+group is added to the ACLs for the corresponding device(s) with read+write
+permissions.
+
+If your scanner is missing from the list, do NOT modify this file; it is not
+a configuration file, which means your changes WILL be overwritten upon
+upgrade. Instead, create /etc/udev/rules.d/60-libsane.rules and add the udev
+rule for your scanner in this file. /lib/udev/rules.d/60-libsane.rules will
+then be ignored by udev and /etc/udev/rules.d/60-libsane.rules will be used
+instead.
+
+Feel free to file a bug report (severity wishlist) against the libsane package
+to get your scanner added; please mention which backend you use and how well
+the scanner is supported (basic, good, ...).
+
+ Note: please do not file bugs requesting the addition of scanners that
+ aren't supported by the libsane package. For these devices, bugs should
+ be filed against the Debian package providing support for the device, if
+ such a package does exist.
+
+udev will automatically set up the permissions and ownership on the device
+node corresponding to your scanner according to the rules defined in the
+libsane.rules file (default is root:scanner, 0664). If you want to execute
+a script when your scanner is plugged in, add RUN+="/path/to/script" to the
+rule matching your scanner.
+
+
+TROUBLESHOOTING
+---------------
+
+If your scanner does not work, edit the file /etc/sane.d/dll.conf.
+Verify that your scanner is not commented out. You may need to
+comment out all other scanners in dll.conf. It shouldn't matter, but
+sometimes it does.
+
+The most common cause for a non-working scanner is inappropriate
+permissions on the device. So your first reflex should be to check the
+permissions of the device used to access your scanner, e.g. /dev/sg0
+or the device pointed to by /dev/scanner.
+
+If running "scanimage > t.pnm" gives an error like "scanimage: open of
+device niash:libusb:002:005 failed: Device busy", powercycling your
+scanner might help.
+
+If you encounter any problems with getting your device(s) recognized,
+try setting the various environment variables that are there to assist
+in debugging such problems. The environment variables are documented
+in the relevant manual pages. For example, to get the maximum amount
+of debug information when testing a Mustek scanner, set environment
+variables SANE_DEBUG_DLL, SANE_DEBUG_MUSTEK, and SANE_DEBUG_SANEI_SCSI
+to 128 and then invoke scanimage or whatever program you're trying to
+debug. For a Mustek SCSI scanner at /dev/scanner, you might want to
+invoke scanimage as follows:
+
+ scanimage -d mustek:/dev/scanner -h
+
+If this works, you could try to acquire an image with:
+
+ scanimage -d mustek:/dev/scanner > t.pnm
+
+If you are not sure what generic SCSI device your scanner is connected
+to, try the command sane-find-scanner (sane-utils package). It is
+normally sufficient to invoke the program without any arguments. Invoking
+this command should produce output similar to this:
+
+ $ sane-find-scanner
+ sane-find-scanner: found "MUSTEK MFC-06000CZ 1.01" at device /dev/sge
+
+sane-find-scanner will help you discover your USB scanner, too.
+
+For some more help can read TROUBLESHOOTING.debian in the doc directory.
+
+
+REPORTING BUGS
+--------------
+
+When reporting a bug, be it to the SANE developers or to the Debian bug
+tracking system, pleases always provide:
+ - the full version of libsane
+ - the backend you're using
+ - the configuration of the backend
+ - the debug output, obtained by setting the environment variable
+ SANE_DEBUG_<backendname> to a value of 255 (see above, TROUBLESHOOTING)
+
+Without that, your bug report will take longer to be processed, because we'll
+need to ask you for each of these items. Please help us help you.
+
+-- Julien BLACHE <jblache@debian.org>, Wed, 16 Feb 2011 19:00:12 +0100