ipp-usb.8

IPP−USB

NAME
DESCRIPTION
SYNOPSIS
NETWORKING
DNS−SD (AVAHI INTEGRATION)
CONFIGURATION
FILES
COPYRIGHT
SEE ALSO

---

NAME

ipp−usb − Daemon for IPP over USB printer support

DESCRIPTION

ipp−usb daemon enables driver−less printing and scanning on USB−only AirPrint−compatible printers and MFPs.

It works by connecting to the device by USB using IPP−over−USB protocol, and exposing the device to the network, including DNS−SD (ZeroConf) advertising.

IPP printing, eSCL scanning and web console are fully supported.

SYNOPSIS

Usage:

ipp−usb mode [options]

Modes are:

**
standalone**

run forever, automatically discover IPP−over−USB devices and serve them all

NETWORKING

Essentially, ipp−usb makes printer or scanner accessible from the network, converting network−side HTTP operations to the USB operations.

By default, ipp−usb exposes device only to the loopback interface, using the localhost address (both 127.0.0.1 and ::1, for IPv4 and IPv6, respectively). TCP ports are allocated automatically, and allocation is persisted in the association with the particular device, so the next time the device is plugged on, it will get the same port. The default port range for TCP ports allocation is 60000−65535.

This default behavior can be changed, using configuration file. See CONFIGURATION section below for details.

If you decide to publish your device to the real network, the following things should be taken into consideration:

DNS−SD (AVAHI INTEGRATION)

IPP over USB is intended to be used with the automatic device discovery, and for this purpose ipp−usb advertises all devices it handles, using DNS−SD protocol. On Linux, DNS−SD is handled with a help of Avahi daemon.

DNS−SD advertising can be disabled via configuration file. Also, if Avahi is not installed or not running, ipp−usb will still work correctly, although DNS−SD advertising will not work.

For every device the following services will be advertised:

Notes:

CONFIGURATION

ipp−usb searched for its configuration file in two places:

Configuration file syntax is very similar to .INI files syntax. It consist of named sections, and each section contains a set of named variables. Comments are started from # or ; characters and continues until end of line:

[section 1]
variable 1 = value 1 ; and another comment
variable 2 = value 2

Network parameters

Network parameters are all in the [network] section:

TCP ports for HTTP will be automatically allocated in the

following range

http−min−port = 60000
http−max−port = 65535

Enable or disable DNS−SD advertisement

dns−sd = enable # enable | disable

Network interface to use. Set to ‘all‘ if you want to expose you

printer to the local network. This way you can share your printer

with other computers in the network, as well as with iOS and

Android devices.

interface = loopback # all | loopback

Enable or disable IPv6

ipv6 = enable # enable | disable

Authentication

By default, ipp−usb exposes locally connected USB printer to all users of the system.

Though this is reasonable behavior in most cases, when computer and printer are both in personal use, for bigger installation this approach can be too simple and primitive.

ipp−usb provides a mechanism, which allows to control local clients access based on UID the client program runs under.

Please note, this mechanism will not work for remote connections (disabled by default but supported). Authentication of remote users requires some different mechanism, which is under consideration but is not yet implemented.

Note also, this mechanism may or may not work in containerized installation (i.e., snap, flatpak and similar). The container namespace may be isolated from the system and/or user’s namespaces, so even for local clients the UID as seen by the ipp−usb may be different from the system−wide UID.

Authentication parameters are all in the [auth uid] section:

[auth uid]

Syntax:

operations = users

Operations are comma−separated list of following operations:

all − all operations

config − configuration web−console

fax − faxing

print − printing

scan − scanning

Users have the following suntax:

user − user name

@group − all users that belongs to the group

Users and groups may be specified either by names or by

numbers. ”*” means any

Note, if user/group is not known in the context of request

(for example, in the case of non−local network connection),

”*” used for matching, which will only match wildcard

rules.

User/group names are resolved at the moment of request

processing (and cached for a couple of seconds), so running

daemon will see changes to the /etc/passwd and /etc/group

Examples:

fax, print = lp, @lp # Allow CUPS to do its work

scan = * # Allow any user to scan

config = @wheel # Only wheel group members can do that

all = *

Logging configuration

Logging parameters are all in the [logging] section:

device−log − what logs are generated per device

main−log − what common logs are generated

console−log − what of generated logs goes to console

parameter contains a comma−separated list of

the following keywords:

error − error messages

info − informative messages

debug − debug messages

trace−ipp, trace−escl, trace−http − very detailed

per−protocol traces

trace−usb − hex dump of all USB traffic

all − all logs

trace−all − alias to all

Note, trace−* implies debug, debug implies info, info implies

error

device−log = all
main−log = debug
console−log = debug

Log rotation parameters:

log−file−size − max log file before rotation. Use suffix

M for megabytes or K for kilobytes

log−backup−files − how many backup files to preserve during

rotation

max−file−size = 256K
max−backup−files = 5

Enable or disable ANSI colors on console

console−color = enable # enable | disable

ipp−usb queries IPP printer attributes at the initialization time

for its own purposes and writes received attributes to the log.

By default, only necessary attributes are requested from device.

If this parameter is set to true, all printer attributes will

be requested. Normally, it only affects the logging. However,

some enterprise−level HP printers returns such huge amount of

data and do it so slowly, so it can cause initialization timeout.

This is why this feature is not enabled by default

get−all−printer−attrs = false # false | true

Quirks

Some devices, due to their firmware bugs, require special handling, called device−specific quirks. ipp−usb loads quirks from the /usr/share/ipp−usb/quirks/*.conf files and from the /etc/ipp−usb/quirks/*.conf files. The /etc/ipp−usb/quirks directory is for system quirks overrides or admin changes. These files have .INI−file syntax with the content that looks like this:

http−connection = keep−alive

[HP OfficeJet Pro 8730]
http−connection = close

[HP Inc. HP Laser MFP 135a]
blacklist = true

Default configuration

[*]
http−connection = ""

For each discovered device, its model name is matched against sections of the quirks files. Section names may contain glob−style wildcards: * that matches any sequence of characters and ? , that matches any single character. To match one of these characters (* and ?) literally, use backslash as escape.

Note, the simplest way to guess the exact model name for the particular device is to use ipp−usb check command, which prints a list of all connected devices.

All matching sections from all quirks files are taken in consideration, and applied in priority order. Priority is computed using the following algorithm:

If some parameter exist in multiple sections, used its value from the most priority section

The following parameters are defined:

If true, the matching device is ignored by the ipp−usb

Some devices send buggy (malformed) IPP responses that violate IPP specification. ipp−usb may reject these responses (so ipp−usb initialization will fail), allow them (ipp−usb initialization will succeed, but CUPS needs to accept them as well) or sanitize them (fix IPP specs violations).

If true, the matching device’s fax capability is ignored

Set XXX header of the HTTP requests forwarded to device to YYY. If YYY is empty string, XXX header is removed

If true, IPP status of IPP requests sent by the ipp−usb by itself will be ignored. This quirk is useful, when device correctly handles IPP request but returned status is not reliable. Affects only ipp−usb initialization.

Delay, in milliseconds, between device is opened and, optionally, reset, and the first request is sent to device

How to reset device during initialization. Default is none

Delay, in milliseconds, between subsequent requests

Don’t use more that N USB interfaces, even if more is available

If you found out about your device that it needs a quirk to work properly or it does not work with ipp−usb at all, although it provides IPP−over−USB interface, please report the issue at https://github.com/OpenPrinting/ipp−usb. It will let us to update our collection of quirks, so helping other owners of such a device.

FILES

COPYRIGHT

Copyright (c) by Alexander Pevzner (pzz@apevzner.com, pzz@pzz.msk.ru)
All rights reserved.

This program is licensed under 2−Clause BSD license. See LICENSE file for details.

SEE ALSO

cups(1)

---