1IPP-USB(8) ipp-usb.8 IPP-USB(8)
2
6 ipp-usb - Daemon for IPP over USB printer support
7
9 ipp-usb daemon enables driver-less printing and scanning on USB-only
10 AirPrint-compatible printers and MFPs.
11 It works by connecting to the device by USB using IPP-over-USB proto‐
13 col, and exposing the device to the network, including DNS-SD (Zero‐
14 Conf) advertising.
15 IPP printing, eSCL scanning and web console are fully supported.
17
19 Usage:
20 ipp-usb mode [options]
21 Modes are:
23 standalone
24 run forever, automatically discover IPP-over-USB devices and
25 serve them all
26 udev like standalone, but exit when last IPP-over-USB device is dis‐
28 connected
29 debug logs duplicated on console, -bg option is ignored
31 check check configuration and exit. It also prints a list of all con‐
33 nected devices
34 status print status of the running ipp-usb daemon, including informa‐
36 tion of all connected devices
37 Options are
39 -bg run in background (ignored in debug mode)
40
42 Essentially, ipp-usb makes printer or scanner accessible from the net‐
43 work, converting network-side HTTP operations to the USB operations.
44 By default, ipp-usb exposes device only to the loopback interface, us‐
46 ing the localhost address (both 127.0.0.1 and ::1, for IPv4 and IPv6,
47 respectively). TCP ports are allocated automatically, and allocation is
48 persisted in the association with the particular device, so the next
49 time the device is plugged on, it will get the same port. The default
50 port range for TCP ports allocation is 60000-65535.
51 This default behavior can be changed, using configuration file. See
53 CONFIGURATION section below for details.
54 If you decide to publish your device to the real network, the following
56 things should be taken into consideration:
57 1. Your private device will become public and it will become accessi‐
59 ble by other computers from the network
60 2. Firewall rules needs to be updated appropriately. The ipp-usb dae‐
62 mon will not do it automatically by itself
63 3. IPP over USB specification explicitly require that the Host field
65 in the HTTP request is set to localhost or localhost:port. If de‐
66 vice is accessed from the real network, Host header will reflect
67 the real network address. Most of devices allow it, but some are
68 more restrictive and will not work in this configuration.
69
73 IPP over USB is intended to be used with the automatic device discov‐
74 ery, and for this purpose ipp-usb advertises all devices it handles,
75 using DNS-SD protocol. On Linux, DNS-SD is handled with a help of Avahi
76 daemon.
77 DNS-SD advertising can be disabled via configuration file. Also, if
79 Avahi is not installed or not running, ipp-usb will still work cor‐
80 rectly, although DNS-SD advertising will not work.
81 For every device the following services will be advertised:
83 ┌────────────┬───────────────┬───────────────────────────┐
85 │Instance │ Type │ Subtypes │
86 ├────────────┼───────────────┼───────────────────────────┤
87 │Device name │ _ipp._tcp │ _universal._sub._ipp._tcp │
88 ├────────────┼───────────────┼───────────────────────────┤
89 │Device name │ _printer._tcp │ │
90 ├────────────┼───────────────┼───────────────────────────┤
91 │Device name │ _uscan._tcp │ │
92 ├────────────┼───────────────┼───────────────────────────┤
93 │Device name │ _http._tcp │ │
94 ├────────────┼───────────────┼───────────────────────────┤
95 │BBPP │ _ipp-usb._tcp │ │
96 └────────────┴───────────────┴───────────────────────────┘
97 Notes:
98 ○ Device name is the name under which device appears in the list of
100 available devices, for example, in the printing dialog (it is
101 DNS-SD device name, in another words), and for most of devices will
102 match the device´s model name. It is appended with the " (USB)"
103 suffix, so if device is connected via network and via USB simulta‐
104 neously, these two connections can be easily distinguished. If
105 there are two devices with the same name connected simultaneously,
106 the suffix becomes " (USB NNN)", with NNN number unique for each
107 device, for disambiguation. In another words, the single "Kyocera
108 ECOSYS M2040dn" device will be listed as "Kyocera ECOSYS M2040dn
109 (USB)", and two such a devices will be listed as "Kyocera ECOSYS
110 M2040dn (USB 1)" and "Kyocera ECOSYS M2040dn (USB 2)"
111 ○ _ipp._tcp and _printer._tcp are only advertises for printer devices
113 and MFPs
114 ○ _uscan._tcp is only advertised for scanner devices and MFPs
116 ○ for the _ipp._tcp service, the _universal._sub._ipp._tcp subtype is
118 also advertised for iOS compatibility
119 ○ _printer._tcp is advertised with TCP port set to 0. Other services
121 are advertised with the actual port number
122 ○ _http._tcp is device web-console. It is always advertises in as‐
124 sumption it is always exist
125 ○ BBPP, used for the _ipp-usb._tcp service, is the USB bus (BB) and
127 port (PP) numbers in hex. The purpose of this advertising is to
128 help CUPS and other possible "clients" to guess which devices are
129 handled by the ipp-usb service, to avoid possible conflicts with
130 the legacy USB drivers.
131
135 ipp-usb searched for its configuration file in two places:
136 1. /etc/ipp-usb/ipp-usb.conf
138 2. ipp-usb.conf in the directory where executable file is located
140 Configuration file syntax is very similar to .INI files syntax. It con‐
144 sist of named sections, and each section contains a set of named vari‐
145 ables. Comments are started from # or ; characters and continues until
146 end of line:
147 # This is a comment
150 [section 1]
151 variable 1 = value 1 ; and another comment
152 variable 2 = value 2
153 Network parameters
157 Network parameters are all in the [network] section:
158 [network]
161 # TCP ports for HTTP will be automatically allocated in the
162 # following range
163 http-min-port = 60000
164 http-max-port = 65535
165 # Enable or disable DNS-SD advertisement
167 dns-sd = enable # enable | disable
168 # Network interface to use. Set to `all` if you want to expose you
170 # printer to the local network. This way you can share your printer
171 # with other computers in the network, as well as with iOS and
172 # Android devices.
173 interface = loopback # all | loopback
174 # Enable or disable IPv6
176 ipv6 = enable # enable | disable
177 Logging configuration
181 Logging parameters are all in the [logging] section:
182 [logging]
185 # device-log - what logs are generated per device
186 # main-log - what common logs are generated
187 # console-log - what of generated logs goes to console
188 #
189 # parameter contains a comma-separated list of
190 # the following keywords:
191 # error - error messages
192 # info - informative messages
193 # debug - debug messages
194 # trace-ipp, trace-escl, trace-http - very detailed
195 # per-protocol traces
196 # trace-usb - hex dump of all USB traffic
197 # all - all logs
198 # trace-all - alias to all
199 #
200 # Note, trace-* implies debug, debug implies info, info implies
201 # error
202 device-log = all
203 main-log = debug
204 console-log = debug
205 # Log rotation parameters:
207 # log-file-size - max log file before rotation. Use suffix
208 # M for megabytes or K for kilobytes
209 # log-backup-files - how many backup files to preserve during
210 # rotation
211 #
212 max-file-size = 256K
213 max-backup-files = 5
214 # Enable or disable ANSI colors on console
216 console-color = enable # enable | disable
217 Quirks
221 Some devices, due to their firmware bugs, require special handling,
222 called device-specific quirks. ipp-usb loads quirks from the
223 /usr/share/ipp-usb/quirks/*.conf files and from the
224 /etc/ipp-usb/quirks/*.conf files. The /etc/ipp-usb/quirks directory is
225 for system quirks overrides or admin changes. These files have
226 .INI-file syntax with the content that looks like this:
227 [HP LaserJet MFP M28-M31]
230 http-connection = keep-alive
231 [HP OfficeJet Pro 8730]
233 http-connection = close
234 [HP Inc. HP Laser MFP 135a]
236 blacklist = true
237 # Default configuration
239 [*]
240 http-connection = ""
241 For each discovered device, its model name is matched against sections
245 of the quirks files. Section names may contain glob-style wildcards: *
246 that matches any sequence of characters and ? , that matches any single
247 character. To match one of these characters (* and ?) literally, use
248 backslash as escape.
249 Note, the simplest way to guess the exact model name for the particular
251 device is to use ipp-usb check command, which prints a list of all con‐
252 nected devices.
253 All matching sections from all quirks files are taken in consideration,
255 and applied in priority order. Priority is computed using the following
256 algorithm:
257 ○ When matching model name against section name, amount of non-wild‐
259 card matched characters is counted, and the longer match wins
260 ○ Otherwise, section loaded first wins. Files are loaded in alphabet‐
262 ical order, sections read sequentially
263 If some parameter exist in multiple sections, used its value from the
267 most priority section
268 The following parameters are defined:
270 ○ blacklist = true | false
272 If true, the matching device is ignored by the ipp-usb
273 ○ http-XXX = YYY
275 Set XXX header of the HTTP requests forwarded to device to YYY. If
276 YYY is empty string, XXX header is removed
277 ○ usb-max-interfaces = N
279 Don´t use more that N USB interfaces, even if more is available
280 ○ disable-fax = true | false
282 If true, the matching device´s fax capability is ignored
283 ○ init-reset = none | soft | hard
285 How to reset device during initialization. Default is none
286 ○ init-delay = NNN
288 Delay, in milliseconds, between device is opened and, optionally,
289 reset, and the first request is sent to device
290 ○ request-delay = NNN
292 Delay, in milliseconds, between subsequent requests
293 If you found out about your device that it needs a quirk to work prop‐
297 erly or it does not work with ipp-usb at all, although it provides
298 IPP-over-USB interface, please report the issue at
299 https://github.com/OpenPrinting/ipp-usb. It will let us to update our
300 collection of quirks, so helping other owners of such a device.
301
303 ○ /etc/ipp-usb/ipp-usb.conf: the daemon configuration file
304 ○ /var/log/ipp-usb/main.log: the main log file
306 ○ /var/log/ipp-usb/<DEVICE>.log: per-device log files
308 ○ /var/ipp-usb/dev/<DEVICE>.state: device state (HTTP port alloca‐
310 tion, DNS-SD name)
311 ○ /var/ipp-usb/lock/ipp-usb.lock: lock file, that helps to prevent
313 multiple copies of daemon to run simultaneously
314 ○ /var/ipp-usb/ctrl: ipp-usb control socket. Currently only used to
316 obtain the per-device status (printed by ipp-usb status), but its
317 functionality may be extended in a future
318 ○ /usr/share/ipp-usb/quirks/*.conf: device-specific quirks (see
320 above)
321 ○ /etc/ipp-usb/quirks/*.conf: device-specific quirks defined by
323 sysadmin (see above)
324
328 Copyright (c) by Alexander Pevzner (pzz@apevzner.com, pzz@pzz.msk.ru)
329 All rights reserved.
330 This program is licensed under 2-Clause BSD license. See LICENSE file
332 for details.
333
335 cups(1)
336 May 2022 IPP-USB(8)