Debian Codegraph @

upstream/debian-unstable/man5/sane-airscan.5

raw
1 .\" generated with Ronn-NG/v0.10.1
2 .\" http://github.com/apjanke/ronn-ng/tree/0.10.1
3 .TH "SANE\-AIRSCAN" "5" "July 2025" "" "AirScan (eSCL) and WSD SANE backend"
4 .SH "NAME"
5 \fBsane\-airscan\fR \- SANE backend for AirScan (eSCL) and WSD scanners and MFP
6 .SH "DESCRIPTION"
7 The \fBsane\-airscan\fR is the universal backend for "driverless" document scanning\. Currently it supports two protocols:
8 .IP "" 4
9 .nf
10 1\. eSCL, also known as AirScan or AirPrint scan
11 2\. WSD, also known as WS\-Scan
12 .fi
13 .IP "" 0
14 .SH "CONFIGURATION"
15 The sane\-airscan loads its configuration files from the following places:
16 .IP "" 4
17 .nf
18 1\. /etc/sane\.d/airscan\.conf
19 2\. /etc/sane\.d/airscan\.d/*
20 .fi
21 .IP "" 0
22 .P
23 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
24 .IP "" 4
25 .nf
26 # This is a comment
27 [section 1]
28 variable 1 = value 1 ; and another comment
29 variable 2 = value 2
30 .fi
31 .IP "" 0
32 .P
33 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")\.
34 .SH "CONFIGURATION OF DEVICES"
35 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\.
36 .P
37 However, in some cases manual configuration can be useful\. For example:
38 .IP "" 4
39 .nf
40 1\. If computer and scanner are connected via IP router
41 2\. There are a lot of devices on a corporate network, but
42 only few of them are interesting
43 3\. Automatic discovery works unreliable
44 .fi
45 .IP "" 0
46 .P
47 To manually configure a device, add the following section to the configuration file:
48 .IP "" 4
49 .nf
50 [devices]
51 "Kyocera eSCL" = http://192\.168\.1\.102:9095/eSCL, eSCL
52 "Kyocera WSD" = http://192\.168\.1\.102:5358/WSDScanner, WSD
53 "Device I do not want to see" = disable
54 .fi
55 .IP "" 0
56 .P
57 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 omitted, eSCL is assumed\. You may also disable particular device by using the \fBdisable\fR keyword instead of URL\.
58 .P
59 In addition, you can manually configure a device by directly passing its URL in a device name without adding it to the configuration file\. This takes the format \fBprotocol:Device Name:URL\fR\. The examples above could be written as \fBescl:Kyocera eSCL:http://192\.168\.1\.102:9095/eSCL\fR and \fBwsd:Kyocera WSD:http://192\.168\.1\.102:5358/WSDScanner\fR\.
60 .P
61 To figure out URLs of available devices, the simplest way is to run the supplied \fBairscan\-discover(1)\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\.
62 .P
63 If running \fBairscan\-discover(1)\fR on the 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\.
64 .P
65 For eSCL devices, the URL can also use the unix:// scheme, such as unix://scanner\.sock/eSCL\. The "host" from the URL is a file name that will be searched for in the directory specified by socket_dir (see below)\. When connecting to the scanner, all traffic will be sent to the specified UNIX socket instead of a TCP connection\.
66 .P
67 By default, sane\-airscan treats all scanners as remote devices\. This can be undesirable, if configuring a proxy that translates from eSCL/WSD to the SANE protocol, as \fBsaned(8)\fR ignores any device that isn't attached locally\. By setting \fBpretend\-local = true\fR, sane\-airscan can make its devices accessible to the SANE network daemon\.
68 .SH "CONFIGURATION OPTIONS"
69 Miscellaneous options all goes to the \fB[options]\fR section\. Currently the following options are supported:
70 .IP "" 4
71 .nf
72 [options]
73 ; If there are a lot of scanners around and you are only
74 ; interested in few of them, disable auto discovery and
75 ; configure scanners manually\.
76 discovery = enable | disable
77
78 ; Choose what SANE apps will show in a list of devices:
79 ; scanner network name (the default) or hardware model name\.
80 model = network | hardware
81
82 ; If device supports both eSCL and WSD protocol, sane\-airscan
83 ; may either choose the "best" protocol automatically, or
84 ; expose all variants for user, allowing manual protocol selection\.
85 ; The default is "auto"\.
86 protocol = auto | manual
87
88 ; Discovery of WSD devices may be "fast" or "full"\. The "fast"
89 ; mode works as fast as DNS\-SD discovery, but in some cases
90 ; may be unreliable\. The "full" mode is slow and reliable\.
91 ; It is also possible to disable automatic discovery
92 ; of WSD devices\. The default is "fast"\.
93 ws\-discovery = fast | full | off
94
95 ; Scanners that use the unix:// schema in their URL can only
96 ; specify a socket name (not a full path)\. The name will be
97 ; searched for in the directory specified here\.
98 ; The default is /var/run\.
99 socket_dir = /path/to/directory
100
101 ; Configure whether eSCL and WSD devices should be treated as
102 ; if they were attached locally\. The default behavior considers
103 ; them as remote devices that are accessed over the network\.
104 ; This option has to be changed when exporting a scanner through
105 ; saned\. The default is "false"
106 pretend\-local = false | true
107 .fi
108 .IP "" 0
109 .SH "BLACKLISTING DEVICES"
110 This feature can be useful, if you are on a very big network and have a lot of devices around you, while interesting only in a few of them\.
111 .IP "" 4
112 .nf
113 [blacklist]
114 model = "Xerox*" ; blacklist by model name
115 name = "HP*" ; blacklist by network name
116 ip = 192\.168\.0\.1 ; blacklist by address
117 ip = 192\.168\.0\.0/24 ; blacklist the whole subnet
118 .fi
119 .IP "" 0
120 .P
121 Network names come from DNS\-SD, WS\-Discovery doesn't provide this information\. For filtering by network name to work, Avahi must be enabled and device must be discoverable via DNS\-SD (not necessarily as a scanner, it's enough if WSD scanner is discoverable as a printer via DNS\-SD)\.
122 .P
123 Blacklisting only affects automatic discovery, and doesn't affect manually configured devices\.
124 .SH "DEBUGGING"
125 sane\-airscan provides very good instrumentation for troubleshooting without physical access to the problemmatic device\.
126 .P
127 Debugging facilities can be controlled using the \fB[debug]\fR section of the configuration file:
128 .IP "" 4
129 .nf
130 [debug]
131 ; Enable or disable console logging
132 enable = false | true
133
134 ; Enable protocol trace and configure output directory
135 ; for trace files\. Like in shell, to specify path relative to
136 ; the home directory, start it with tilda character, followed
137 ; by slash, i\.e\., "~/airscan/trace"\. The directory will
138 ; be created automatically\.
139 trace = path
140
141 ; Hex dump all traffic to the trace file (very verbose!)
142 hexdump = false | true
143 .fi
144 .IP "" 0
145 .SH "FILES"
146 .TP
147 \fB/etc/sane\.d/airscan\.conf\fR, \fB/etc/sane\.d/airscan\.d/*\fR
148 The backend configuration files
149 .TP
150 \fB/usr/LIBDIR/sane/libsane\-airscan\.so\fR
151 The shared library implementing this backend
152 .SH "ENVIRONMENT"
153 .TP
154 \fBSANE_DEBUG_AIRSCAN\fR
155 This variable if set to \fBtrue\fR or non\-zero numerical value, enables debug messages, that are printed to stderr
156 .TP
157 \fBSANE_CONFIG_DIR\fR
158 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\.
159 .TP
160 \fBSANE_AIRSCAN_DEVICE\fR
161 This variable, if set, overrides all devices, manually configured in the configuration files and disables auto discovery\.
162 .IP
163 It consists of three parameters, delimited by the colons (\fB:\fR):
164 .IP
165 \fB"PROTO:DEVICE NAME:URL"\fR
166 .IP
167 Where:
168 .IP
169 \- \fBPROTO\fR is either \fBescl\fR or \fBwsd\fR\.
170 .br
171 \- \fBDEVICE NAME\fR will appear in the list of devices\.
172 .br
173 \- \fBURL\fR is the device URL, using \fBhttp:\fR or \fBhttps:\fR schemes\.
174 .br
175 .IP
176 Examples:
177 .IP
178 \fB"escl:Kyocera eSCL:http://192\.168\.1\.102:9095/eSCL"\fR (eSCL)
179 .br
180 \fB"wsd:Kyocera WSD:http://192\.168\.1\.102:5358/WSDScanner"\fR (WSD)
181 .br
182 .IP
183 The primary purpose of this variable is the automated testing of the \fBsane\-airscan\fR backend\.
184 .SH "BUGS AND SUPPORT"
185 If you have found a bug, please file a GitHub issue on a GitHub project page: \fBhttps://github\.com/alexpevzner/sane\-airscan\fR
186 .SH "SEE ALSO"
187 \fBsane(7), saned (8), scanimage(1), xsane(1), airscan\-discover(1)\fR
188 .SH "AUTHOR"
189 Alexander Pevzner <pzz@apevzner\.com>