sane-airscan.5

.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "SANE\-AIRSCAN" "5" "May 2020" "" "AirScan (eSCL) and WSD SANE backend"
.
.SH "NAME"
\fBsane\-airscan\fR \- SANE backend for AirScan (eSCL) and WSD scanners and MFP
.
.SH "DESCRIPTION"
The \fBsane\-airscan\fR is the universal backend for "driverless" document scanning\. Currently it supports two protocols:
.
.IP "" 4
.
.nf

1\. eSCL, also known as AirScan or AirPrint scan
2\. WSD, also known as WS\-Scan
.
.fi
.
.IP "" 0
.
.SH "CONFIGURATION"
The sane\-airscan loads its configuration files from the following places:
.
.IP "" 4
.
.nf

1\. /etc/sane\.d/airscan\.conf
2\. /etc/sane\.d/airscan\.d/*
.
.fi
.
.IP "" 0
.
.P
The configuration file syntax is very similar to the \.INI file syntax\. It consist of sections, each section contains some variables\. Comments are started from # or ; characters and continies until end of line
.
.IP "" 4
.
.nf

# This is a comment
[section 1]
variable 1 = value 1  ; and another comment
variable 2 = value 2
.
.fi
.
.IP "" 0
.
.P
Leading and trailing spaces of variable name and value are striped\. If you want to preserve them, put name or value into quotes ("like this")\.
.
.SH "CONFIGURATION OF DEVICES"
If scanner and computer are connected to the same LAN segment, everything expected to "just work" out of box, without any need of manual configuration\.
.
.P
However, in some cases manual configuration can be useful\. For example:
.
.IP "" 4
.
.nf

1\. If computer and scanner are connected via IP router
2\. There are a lot of devices on a corporate network, but
   only few of them are interesting
3\. Automatic discovery works unreliable
.
.fi
.
.IP "" 0
.
.P
To manually configure a device, add the following section to the configuration file:
.
.IP "" 4
.
.nf

[devices]
"Kyocera eSCL" = http://192\.168\.1\.102:9095/eSCL, eSCL
"Kyocera WSD" = http://192\.168\.1\.102:5358/WSDScanner, WSD
"Device I don\'t want to see" = disable
.
.fi
.
.IP "" 0
.
.P
The \fB[devices]\fR section contains all manually configured devices, one line per device, and each line contains a device name on a left side of equation and device URL on a rights side, followed by protocol (eSCL or WSD)\. If protocol is ommited, eSCL is assumed\. You may also disable particular device by using the \fBdisable\fR keyword instead of URL\.
.
.P
To figure out URLs of available devices, the simplest way is to run a supplied \fBairscan\-discover\fR tool on a computer connected with scanner to the same LAN segment\. On success, this program will dump to its standard output a list of discovered devices in a format suitable for inclusion into the configuration file\.
.
.P
If running \fBairscan\-discover\fR on same LAN segment as a scanner is not possible, you will have to follow a hard way\. Your administrator must know device IP address, consult your device manual for the eSCL port, and the URL path component most likely is the "/eSCL", though on some devices it may differ\. Discovering WSD URLs doing this way is much harder, because it is very difficult to guess TCP port and URL path, that in a case of eSCL\.
.
.SH "CONFIGURATION OPTIONS"
Miscellaneous options all goes to the \fB[options]\fR section\. Currently the following options are supported:
.
.IP "" 4
.
.nf

[options]
; If there are a lot of scanners around and you are only
; interested in few of them, disable auto discovery and
; configure scanners manually
discovery = enable | disable

; Choose what SANE apps will show in a list of devices:
; scanner network (the default) name or hardware model name
model = network | hardware

; If device supports both eSCL and WSD protocol, sane\-airscan
; may either choose the "best" protocol automatically, or
; expose all variants for user, allowing manual protocol selection\.
; The default is "auto"
protocol = auto | manual

; Discovery of WSD devices may be "fast" or "full"\. The "fast"
; mode works as fast as DNS\-SD discovery, but in some cases
; may be unreliable\. The "full" mode is slow and reliable\.
; This is also possible to disable automatic discovery
; of WSD devices\. The default is "fast"\.
ws\-discovery = fast | full | off
.
.fi
.
.IP "" 0
.
.SH "DEBUGGING"
sane\-airscan provides very good instrumentation for troubleshooting without physical access to the problemmatic device\.
.
.P
Debuggung facilities can be controlled using the \fB[debug]\fR section of the configuration file:
.
.IP "" 4
.
.nf

[debug]
; Enable or disable console logging
enable = false | true

; Enable protocol trace and configure output directory
; for trace files\. To specify path relative to user\'s
; home directory, start it with tilda character, followed
; by slash, i\.e\., "~/airscan/trace"\. The directory will
; be created automatically\.
trace = path
.
.fi
.
.IP "" 0
.
.SH "FILES"
.
.TP
\fB/etc/sane\.d/airscan\.conf\fR, \fB/etc/sane\.d/airscan\.d/*\fR
The backend configuration files
.
.TP
\fB/usr/LIBDIR/sane/libsane\-airscan\.so\fR
The shared library implementing this backend
.
.SH "ENVIRONMENT"
.
.TP
\fBSANE_DEBUG_AIRSCAN\fR
This variable if set to \fBtrue\fR or non\-zero numerical value, enables debug messages, that are printed to stdout
.
.TP
\fBSANE_CONFIG_DIR\fR
This variable alters the search path for configuration files\. This is a colon\-separated list of directories\. These directories are searched for the airscan\.conf configuration file and for the airscan\.d subdirectory, before the standard path (/etc/sane\.d) is searched\.
.
.SH "BUGS AND SUPPORT"
If you have found a bug, please file a GitHub issue on a GitHub project page: \fBhttps://github\.com/alexpevzner/sane\-airscan\fR
.
.SH "SEE ALSO"
sane(7), scanimage(1), xscane(1), airscan\-discover(1)
.
.SH "AUTHOR"
Alexander Pevzner <pzz@apevzner\.com>