1SANE-AIRSCAN(5)       AirScan (eSCL) and WSD SANE backend      SANE-AIRSCAN(5)
2
3
4

NAME

6       sane-airscan - SANE backend for AirScan (eSCL) and WSD scanners and MFP
7

DESCRIPTION

9       The  sane-airscan  is  the  universal backend for "driverless" document
10       scanning. Currently it supports two protocols:
11
12
13
14           1. eSCL, also known as AirScan or AirPrint scan
15           2. WSD, also known as WS-Scan
16
17
18

CONFIGURATION

20       The sane-airscan loads  its  configuration  files  from  the  following
21       places:
22
23
24
25           1. /etc/sane.d/airscan.conf
26           2. /etc/sane.d/airscan.d/*
27
28
29
30       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
34
35
36           # This is a comment
37           [section 1]
38           variable 1 = value 1  ; and another comment
39           variable 2 = value 2
40
41
42
43       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

CONFIGURATION OF DEVICES

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
51       However, in some cases manual configuration can be useful. For example:
52
53
54
55           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
60
61
62       To manually configure a device, add the following section to  the  con‐
63       figuration file:
64
65
66
67           [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
72
73
74       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
80       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
86       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
92       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
100       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

CONFIGURATION OPTIONS

107       Miscellaneous  options all goes to the [options] section. Currently the
108       following options are supported:
109
110
111
112           [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
118           ; 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
122           ; 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
128           ; 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
135           ; 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
140
141

BLACKLISTING DEVICES

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
146
147
148           [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
154
155
156       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
162       Blacklisting only affects automatic discovery, and doesn´t affect manu‐
163       ally configured devices
164

DEBUGGING

166       sane-airscan provides very  good  instrumentation  for  troubleshooting
167       without physical access to the problemmatic device.
168
169       Debugging facilities can be controlled using the [debug] section of the
170       configuration file:
171
172
173
174           [debug]
175           ; Enable or disable console logging
176           enable = false | true
177
178           ; 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
185           ; Hex dump all traffic to the trace file (very verbose!)
186           hexdump = false | true
187
188
189

FILES

191       /etc/sane.d/airscan.conf, /etc/sane.d/airscan.d/*
192              The backend configuration files
193
194       /usr/LIBDIR/sane/libsane-airscan.so
195              The shared library implementing this backend
196

ENVIRONMENT

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
202       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

BUGS AND SUPPORT

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

SEE ALSO

214       sane(7), scanimage(1), xsane(1), airscan-discover(1)
215

AUTHOR

217       Alexander Pevzner <pzz@apevzner.com>
218
219
220
221                                   May 2021                    SANE-AIRSCAN(5)
Impressum