SANE-AIRSCAN(5)

✨ NAME ✨

sane-airscan — the SANE backend for AirScan (eSCL) and WSD scanners and MFP 💅

(and yeah bestie, this is the SANE-AIRSCAN(5) manual page, section 5, we're fancy like that 👑

---

🦋 DESCRIPTION 🦋

The sane-airscan is THE universal backend for "driverless" document scanning, no cap. Right now it speaks two protocols:

1. eSCL, also known as AirScan or AirPrint scan 🌸
2. WSD, also known as WS-Scan 🌈

---

🎀 CONFIGURATION 🎀

sane-airscan loads its config files from these places, in order:

1. /etc/sane.d/airscan.conf
2. /etc/sane.d/airscan.d/*

The config file syntax is very similar to .INI file syntax — it's giving old school but make it scan 💖. It's made of sections, and each section holds some variables. Comments start with # or ; and keep going until the end of the line.

# This is a comment
[section 1]
variable 1 = value 1  ; and another comment
variable 2 = value 2

Leading and trailing spaces of a variable name and value get stripped. If you want to keep them (iconic of you), put the name or the value into quotes ("like this").

---

🔥 CONFIGURATION OF DEVICES 🔥

If your scanner and your computer are on the same LAN segment, everything is expected to "just work" out of the box, no manual configuration needed. Slay. ✨

But sometimes manual config is genuinely useful. For example:

1. If the computer and the scanner are connected via an IP router
2. There are a lot of devices on a corporate network, but only a few of them are actually interesting
3. Automatic discovery works unreliably 😭

To manually configure a device, add a section like this to the config file:

[devices]
"Kyocera eSCL" = http://192.168.1.102:9095/eSCL, eSCL
"Kyocera WSD" = http://192.168.1.102:5358/WSDScanner, WSD
"Device I do not want to see" = disable

The [devices] section holds all your manually configured devices, one line per device, and each line has a device name on the left side of the equation and the device URL on the right side, followed by the protocol (eSCL or WSD). If the protocol is omitted, eSCL is assumed. You can also disable a particular device by using the disable keyword instead of a URL. 🚫

In addition, you can manually configure a device by directly passing its URL in a device name, without adding it to the configuration file. That takes the format protocol:Device Name:URL. The examples above could be written as escl:Kyocera eSCL:http://192.168.1.102:9095/eSCL and wsd:Kyocera WSD:http://192.168.1.102:5358/WSDScanner.

To figure out the URLs of available devices, the simplest way is to run the supplied airscan-discover(1) tool on a computer connected to the same LAN segment as the scanner. 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. 🫶

If running airscan-discover(1) on the same LAN segment as the scanner is not possible, you'll have to follow the hard way. Your administrator must know the 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 this way is much harder, because it is very difficult to guess the TCP port and URL path, like in the case of eSCL. 💀

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

By default, sane-airscan treats all scanners as remote devices. This can be undesirable if you're configuring a proxy that translates from eSCL/WSD to the SANE protocol, since saned(8) ignores any device that isn't attached locally. By setting pretend-local = true, sane-airscan can make its devices accessible to the SANE network daemon. 🫡

---

💅 CONFIGURATION OPTIONS 💅

Miscellaneous options all go into the [options] section. Currently the following options are supported:

[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 name (the default) 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.
; It is also possible to disable automatic discovery
; of WSD devices. The default is "fast".
ws-discovery = fast | full | off

; Scanners that use the unix:// schema in their URL can only
; specify a socket name (not a full path). The name will be
; searched for in the directory specified here.
; The default is /var/run.
socket_dir = /path/to/directory

; Configure whether eSCL and WSD devices should be treated as
; if they were attached locally. The default behavior considers
; them as remote devices that are accessed over the network.
; This option has to be changed when exporting a scanner through
; saned. The default is "false"
pretend-local = false | true

Here's the rundown, one by one:

• discovery = enable | disable — if there are a lot of scanners around and you're only interested in a few of them, disable auto discovery and configure your scanners manually. 👀
• model = network | hardware — picks what SANE apps show in the device list: the scanner network name (that's the default) or the hardware model name.
• protocol = auto | manual — if a device supports both eSCL and WSD, sane-airscan can either choose the "best" protocol automatically, or expose all the variants for you so you can pick by hand. The default is auto.
• ws-discovery = fast | full | off — WSD device discovery can be fast or full. fast works as fast as DNS-SD discovery but can be unreliable in some cases. full is slow and reliable. You can also disable automatic discovery of WSD devices entirely. The default is fast.
• socket_dir = /path/to/directory — scanners using the unix:// schema in their URL can only specify a socket name (not a full path), and the name gets searched for in the directory specified here. The default is /var/run.
• pretend-local = false | true — controls whether eSCL and WSD devices are treated as if they were attached locally. Default behavior considers them remote devices accessed over the network. This option has to be changed when exporting a scanner through saned. The default is false.

---

💀 BLACKLISTING DEVICES 💀

This feature is useful if you're on a very big network with a ton of devices around you, and you're interested in only a few of them.

[blacklist]
model = "Xerox*"       ; blacklist by model name
name  = "HP*"          ; blacklist by network name
ip    = 192.168.0.1    ; blacklist by address
ip    = 192.168.0.0/24 ; blacklist the whole subnet

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 the device must be discoverable via DNS-SD (not necessarily as a scanner — it's enough if a WSD scanner is discoverable as a printer via DNS-SD). 🌈

Blacklisting only affects automatic discovery, and does not affect manually configured devices. Periodt. 💅

---

🔍 DEBUGGING 🔍

sane-airscan provides very good instrumentation for troubleshooting without physical access to the problematic device. Main character energy, honestly. 👑

Debugging facilities are controlled using the [debug] section of the configuration file:

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

; Enable protocol trace and configure output directory
; for trace files. Like in shell, to specify path relative to
; the home directory, start it with tilda character, followed
; by slash, i.e., "~/airscan/trace". The directory will
; be created automatically.
trace = path

; Hex dump all traffic to the trace file (very verbose!)
hexdump = false | true

Breaking it down:

• enable = false | true — turn console logging on or off. 🪵
• trace = path — enables the protocol trace and sets the output directory for trace files. Like in shell, to specify a path relative to the home directory, start it with the tilde character followed by a slash, i.e. "~/airscan/trace". The directory will be created automatically. 🎀
• hexdump = false | true — hex dump all traffic to the trace file. Very verbose! 😭

---

📁 FILES 📁

• /etc/sane.d/airscan.conf, /etc/sane.d/airscan.d/* — the backend configuration files
• /usr/LIBDIR/sane/libsane-airscan.so — the shared library implementing this backend 🦋

---

🌸 ENVIRONMENT 🌸

• SANE_DEBUG_AIRSCAN — this variable, if set to true or a non-zero numerical value, enables debug messages that are printed to stderr. 🐛
• SANE_CONFIG_DIR — this variable alters the search path for configuration files. It's 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.
• SANE_AIRSCAN_DEVICE — this variable, if set, overrides all devices manually configured in the configuration files and disables auto discovery.

It consists of three parameters, delimited by the colons (:):

"PROTO:DEVICE NAME:URL"

Where:

• PROTO is either escl or wsd.
• DEVICE NAME will appear in the list of devices.
• URL is the device URL, using http: or https: schemes.

Examples:

"escl:Kyocera eSCL:http://192.168.1.102:9095/eSCL" (eSCL)
"wsd:Kyocera WSD:http://192.168.1.102:5358/WSDScanner" (WSD)

The primary purpose of this variable is the automated testing of the sane-airscan backend. 🧪

---

🫶 BUGS AND SUPPORT 🫶

If you've found a bug, please file a GitHub issue on the GitHub project page: https://github.com/alexpevzner/sane-airscan

---

⭐ SEE ALSO ⭐

sane(7), saned (8), scanimage(1), xsane(1), airscan-discover(1)

---

👑 AUTHOR 👑

Alexander Pevzner <pzz@apevzner.com>

---

and that's the whole page bestie ✨ this was SANE-AIRSCAN(5), dated April 2026 — go scan something iconic, ily 💖🎀🦋