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