1SANE-AIRSCAN(5) AirScan (eSCL) and WSD SANE backend SANE-AIRSCAN(5)
2
6 sane-airscan - SANE backend for AirScan (eSCL) and WSD scanners and MFP
7
9 The sane-airscan is the universal backend for "driverless" document
10 scanning. Currently it supports two protocols:
11 1. eSCL, also known as AirScan or AirPrint scan
15 2. WSD, also known as WS-Scan
16
20 The sane-airscan loads its configuration files from the following
21 places:
22 1. /etc/sane.d/airscan.conf
26 2. /etc/sane.d/airscan.d/*
27 The configuration file syntax is very similar to the .INI file syntax.
31 It consist of sections, each section contains some variables. Comments
32 are started from # or ; characters and continies until end of line
33 # This is a comment
37 [section 1]
38 variable 1 = value 1 ; and another comment
39 variable 2 = value 2
40 Leading and trailing spaces of variable name and value are striped. If
44 you want to preserve them, put name or value into quotes ("like this").
45
47 If scanner and computer are connected to the same LAN segment, every‐
48 thing expected to "just work" out of box, without any need of manual
49 configuration.
50 However, in some cases manual configuration can be useful. For example:
52 1. If computer and scanner are connected via IP router
56 2. There are a lot of devices on a corporate network, but
57 only few of them are interesting
58 3. Automatic discovery works unreliable
59 To manually configure a device, add the following section to the con‐
63 figuration file:
64 [devices]
68 "Kyocera eSCL" = http://192.168.1.102:9095/eSCL, eSCL
69 "Kyocera WSD" = http://192.168.1.102:5358/WSDScanner, WSD
70 "Device I do not want to see" = disable
71 The [devices] section contains all manually configured devices, one
75 line per device, and each line contains a device name on a left side of
76 equation and device URL on a rights side, followed by protocol (eSCL or
77 WSD). If protocol is omitted, eSCL is assumed. You may also disable
78 particular device by using the disable keyword instead of URL.
79 In addition, you can manually configure a device by directly passing
81 its URL in a device name without adding it to the configuration file.
82 This takes the format protocol:Device Name:URL. The examples above
83 could be written as escl:Kyocera eSCL:http://192.168.1.102:9095/eSCL
84 and wsd:Kyocera WSD:http://192.168.1.102:5358/WSDScanner.
85 To figure out URLs of available devices, the simplest way is to run a
87 supplied airscan-discover tool on a computer connected with scanner to
88 the same LAN segment. On success, this program will dump to its stan‐
89 dard output a list of discovered devices in a format suitable for in‐
90 clusion into the configuration file.
91 If running airscan-discover on same LAN segment as a scanner is not
93 possible, you will have to follow a hard way. Your administrator must
94 know device IP address, consult your device manual for the eSCL port,
95 and the URL path component most likely is the "/eSCL", though on some
96 devices it may differ. Discovering WSD URLs doing this way is much
97 harder, because it is very difficult to guess TCP port and URL path,
98 that in a case of eSCL.
99 For eSCL devices, the URL can also use the unix:// scheme, such as
101 unix://scanner.sock/eSCL. The "host" from the URL is a file name that
102 will be searched for in the directory specified by socket_dir (see be‐
103 low). When connecting to the scanner, all traffic will be sent to the
104 specified UNIX socket instead of a TCP connection.
105
107 Miscellaneous options all goes to the [options] section. Currently the
108 following options are supported:
109 [options]
113 ; If there are a lot of scanners around and you are only
114 ; interested in few of them, disable auto discovery and
115 ; configure scanners manually
116 discovery = enable | disable
117 ; Choose what SANE apps will show in a list of devices:
119 ; scanner network name (the default) or hardware model name
120 model = network | hardware
121 ; If device supports both eSCL and WSD protocol, sane-airscan
123 ; may either choose the "best" protocol automatically, or
124 ; expose all variants for user, allowing manual protocol selection.
125 ; The default is "auto"
126 protocol = auto | manual
127 ; Discovery of WSD devices may be "fast" or "full". The "fast"
129 ; mode works as fast as DNS-SD discovery, but in some cases
130 ; may be unreliable. The "full" mode is slow and reliable.
131 ; This is also possible to disable automatic discovery
132 ; of WSD devices. The default is "fast".
133 ws-discovery = fast | full | off
134 ; Scanners that use the unix:// schema in their URL can only specify a
136 ; socket name (not a full path). The name will be searched for in the
137 ; directory specified here. The default is /var/run.
138 socket_dir = /path/to/directory
139
143 This feature can be useful, if you are on a very big network and have a
144 lot of devices around you, while interesting only in a few of them.
145 [blacklist]
149 model = "Xerox*" ; blacklist by model name
150 name = "HP*" ; blacklist by network name
151 ip = 192.168.0.1 ; blacklist by address
152 ip = 192.168.0.0/24 ; blacklist the whole subnet
153 Network names come from DNS-SD, WS-Discovery doesn´t provide this in‐
157 formation. For filtering by network name to work, Avahi must be enabled
158 and device must be discoverable via DNS-SD (not necessarily as a scan‐
159 ner, it´s enough if WSD scanner is discoverable as a printer via
160 DNS-SD).
161 Blacklisting only affects automatic discovery, and doesn´t affect manu‐
163 ally configured devices
164
166 sane-airscan provides very good instrumentation for troubleshooting
167 without physical access to the problemmatic device.
168 Debugging facilities can be controlled using the [debug] section of the
170 configuration file:
171 [debug]
175 ; Enable or disable console logging
176 enable = false | true
177 ; Enable protocol trace and configure output directory
179 ; for trace files. Like in shell, to specify path relative to
180 ; the home directory, start it with tilda character, followed
181 ; by slash, i.e., "~/airscan/trace". The directory will
182 ; be created automatically.
183 trace = path
184 ; Hex dump all traffic to the trace file (very verbose!)
186 hexdump = false | true
187
191 /etc/sane.d/airscan.conf, /etc/sane.d/airscan.d/*
192 The backend configuration files
193 /usr/LIBDIR/sane/libsane-airscan.so
195 The shared library implementing this backend
196
198 SANE_DEBUG_AIRSCAN
199 This variable if set to true or non-zero numerical value, en‐
200 ables debug messages, that are printed to stdout
201 SANE_CONFIG_DIR
203 This variable alters the search path for configuration files.
204 This is a colon-separated list of directories. These directories
205 are searched for the airscan.conf configuration file and for the
206 airscan.d subdirectory, before the standard path (/etc/sane.d)
207 is searched.
208
210 If you have found a bug, please file a GitHub issue on a GitHub project
211 page: https://github.com/alexpevzner/sane-airscan
212
214 sane(7), scanimage(1), xsane(1), airscan-discover(1)
215
217 Alexander Pevzner <pzz@apevzner.com>
218 May 2021 SANE-AIRSCAN(5)