8.7. Image Scanners

Written by Marc Fonvieille.

In FreeBSD, access to image scanners is provided by the SANE (Scanner Access Now Easy) API available through the FreeBSD Ports Collection. SANE will also use some FreeBSD device drivers to provide access to the scanner hardware.

FreeBSD supports both SCSI and USB scanners. Be sure the scanner is supported by SANE prior to performing any configuration. Refer to the supported devices list for more information about supported scanners.

8.7.1. Kernel Configuration

Both SCSI and USB interfaces are supported. Depending upon the scanner interface, different device drivers are required. USB Interface

The GENERIC kernel by default includes the device drivers needed to support USB scanners. Users with a custom kernel should ensure that the following lines are present in the custom kernel configuration file:

device usb device uhci device ohci device ehci

Plug in the USB scanner. Use dmesg(8) to determine whether the scanner appears in the system message buffer:

ugen0.2: <EPSON> at usbus0

These messages indicate that the scanner is using either /dev/ugen0.2 or /dev/uscanner0, depending on the FreeBSD version. For this example, a EPSON Perfection® 1650 USB scanner was used. SCSI Interface

If the scanner uses a SCSI interface, it is important to know which SCSI controller board it will use. Depending upon the SCSI chipset, a custom kernel configuration file may be needed. The GENERIC kernel supports the most common SCSI controllers. Refer to /usr/src/sys/conf/NOTES to determine the correct line to add to a custom kernel configuration file. In addition to the SCSI adapter driver, the following lines are needed in the kernel configuration file:

device scbus device pass

Verify that the device is displayed in the system message buffer:

pass2 at aic0 bus 0 target 2 lun 0 pass2: <AGFA SNAPSCAN 600 1.10> Fixed Scanner SCSI-2 device pass2: 3.300MB/s transfers

If the scanner was not powered-on at system boot, it is still possible to manually force the detection by performing a SCSI bus scan with the camcontrol(8) command:

# camcontrol rescan all Re-scan of bus 0 was successful Re-scan of bus 1 was successful Re-scan of bus 2 was successful Re-scan of bus 3 was successful

The scanner should now appear in the SCSI devices list:

# camcontrol devlist <IBM DDRS-34560 S97B> at scbus0 target 5 lun 0 (pass0,da0) <IBM DDRS-34560 S97B> at scbus0 target 6 lun 0 (pass1,da1) <AGFA SNAPSCAN 600 1.10> at scbus1 target 2 lun 0 (pass3) <PHILIPS CDD3610 CD-R/RW 1.00> at scbus2 target 0 lun 0 (pass2,cd0)

Refer to scsi(4) and camcontrol(8) for more details about SCSI devices on FreeBSD.

8.7.2. SANE Configuration

The SANE system is split in two parts: the backends (graphics/sane-backends) and the frontends (graphics/sane-frontends). The backends provide access to the scanner. The SANE's supported devices list specifies which backend will support the image scanner. The correct backend is needed in order to use the scanner. The frontends provide the graphical scanning interface, xscanimage.

After installing the graphics/sane-backends port or package, use sane-find-scanner to check the scanner detection by the SANE system:

# sane-find-scanner -q found SCSI scanner "AGFA SNAPSCAN 600 1.10" at /dev/pass3

The output should show the interface type of the scanner and the device node used to attach the scanner to the system. The vendor and the product model may or may not appear.


Some USB scanners require firmware to be loaded. Refer to sane-find-scanner(1) and sane(7) for details.

Next, check if the scanner will be identified by a scanning frontend. By default, the SANE backends come with a command line tool called scanimage(1). This command can be used to list the devices and perform an image acquisition. Use -L to list the scanner devices:

# scanimage -L device `snapscan:/dev/pass3' is a AGFA SNAPSCAN 600 flatbed scanner

Here is the output for the USB scanner used in Section, “USB Interface”:

# scanimage -L device 'epson2:libusb:/dev/usb:/dev/ugen0.2' is a Epson GT-8200 flatbed scanner

In this output, 'epson2:libusb:/dev/usb:/dev/ugen0.2' is the backend name (epson2) and the device node (/dev/ugen0.2) used by the scanner.


No output or a message saying that no scanners were identified indicates that scanimage(1) is unable to identify the scanner. If this happens, edit the backend configuration file in /usr/local/etc/sane.d/ and define the scanner device used.

In the above example, the USB scanner is perfectly detected and working.

To determine if the scanner is correctly identified:

# scanimage -L No scanners were identified. If you were expecting something different, check that the scanner is plugged in, turned on and detected by the sane-find-scanner tool (if appropriate). Please read the documentation which came with this software (README, FAQ, manpages).

Since the scanner is not identified, edit /usr/local/etc/sane.d/epson2.conf. In this example, the scanner model is EPSON Perfection® 1650 and it uses the epson2 backend. When editing, read the help comments in the backend configuration file. Line changes are simple: comment out all lines that have the wrong interface for the scanner. In this example, comment out all lines starting with the word scsi as the scanner uses the USB interface. Then, at the end of the file, add a line specifying the interface and the device node used. In this case, add the following line:

usb /dev/uscanner0

Save the edits and verify that the scanner is identified:

# scanimage -L device `epson:/dev/uscanner0' is a Epson GT-8200 flatbed scanner

The `epson:/dev/uscanner0' field now gives the right backend name and the device node.

Once scanimage -L sees the scanner, the configuration is complete and the device is now ready to scan.

While scanimage(1) can be used to perform an image acquisition from the command line, it is often preferable to use a graphical interface to perform image scanning. The graphics/sane-frontends package or port installs a simple but efficient graphical interface, xscanimage.

Xsane, which is installed with the graphics/xsane package or port, is another popular graphical scanning frontend. It offers advanced features such as various scanning modes, color correction, and batch scans. Both of these applications are usable as a GIMP plugin.

8.7.3. Giving Other Users Access to the Scanner

In order to have access to the scanner, a user needs read and write permissions to the device node used by the scanner. In the previous example, the USB scanner uses the device node /dev/ugen0.2 which is really a symlink to the real device node /dev/usb/0.2.0. The symlink and the device node are owned, respectively, by the wheel and operator groups. Adding the user to these groups will allow access to the scanner. However, for security reasons, always think twice before adding a user to any group, especially wheel. A better solution is to create a group to make the scanner device accessible to members of this group.

This example creates a group called usb using pw(8):

# pw groupadd usb

Then, make the /dev/ugen0.2 symlink and the /dev/usb/0.2.0 device node accessible to the usb group with write permissions of (0660 or 0664. All of this is done by adding the following lines to /etc/devfs.rules:

[system=5] add path ugen0.2 mode 0660 group usb add path usb/0.2.0 mode 0666 group usb

Finally, add the users to usb in order to allow access to the scanner:

# pw groupmod usb -m joe

For more details refer to pw(8).

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.

Send questions about this document to <freebsd-doc@FreeBSD.org>.