ipp-usb - Man Page

ipp-usb mode [options]

standalone

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

udev

like standalone, but exit when last IPP-over-USB device is disconnected

debug

logs duplicated on console, -bg option is ignored

check

check configuration and exit. It also prints a list of all connected devices

status

print status of the running ipp-usb daemon, including information of all connected devices

-bg

run in background (ignored in debug mode)

Network parameters are all in the [network] section:

[network]
  # 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

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:

# Local user authentication by UID/GID
[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 parameters are all in the [logging] section:

[logging]
  # 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

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:

[HP LaserJet MFP M28-M31]
  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:

• When matching model name against section name, amount of non-wildcard matched characters is counted, and the longer match wins
• Otherwise, section loaded first wins. Files are loaded in alphabetical order, sections read sequentially

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

The following parameters are defined:

• blacklist = true | false
  If true, the matching device is ignored by the ipp-usb
• buggy-ipp-responses = reject | allow | sanitize
  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).
• disable-fax = true | false
  If true, the matching device's fax capability is ignored
• http-XXX = YYY
  Set XXX header of the HTTP requests forwarded to device to YYY. If YYY is empty string, XXX header is removed
• ignore-ipp-status = true | false
  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.
• init-delay = NNN
  Delay, in milliseconds, between device is opened and, optionally, reset, and the first request is sent to device
• init-reset = none | soft | hard
  How to reset device during initialization. Default is none
• request-delay = NNN
  Delay, in milliseconds, between subsequent requests
• usb-max-interfaces = N
  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.