tree: aa9ecb304fb21713491835ae1f3da5e3bf9966ed [path history] [tgz]
  1. BUILD.gn
  2. OWNERS
  3. README.md
  4. etc/
  5. fuzzers/
  6. ippusb_manager.cc
  7. overview_diagram.dot
  8. overview_diagram.png
  9. seccomp/
  10. socket_manager.cc
  11. socket_manager.h
  12. udev/
  13. usb.cc
  14. usb.h
  15. usb_test.cc
ippusb_manager/README.md

Ippusb Manager

ippusb_manager provides support for IPP-over-USB printing in Chrome OS. This is jointly achieved with CUPS and with ippusbxd.

In addition, ippusbxd is partially documented here.

Overview

ippusb_manager overview diagram

  • The entities involved:
    • CUPS - the print spooler that wants to print via IPP-over-USB.
    • ippusb_manager - service that helps establish communication between the print spooler and ippusbxd. Developed specifically for IPP-over-USB printing in Chromium OS.
    • ippusbxd - service that facilitates IPP-over-USB communication. Heavily patched for use in Chromium OS. Known to differ substantially from upstream.

Closer look: CUPS

  • The print queue URI format used for IPP-over-USB printing is ippusb://<VID>_<PID>/ipp/print.
  • We have patched CUPS in Chromium OS to support the ippusb:// scheme.
    • These changes apply to lpadmin and to the ipp backend.
    • If a printer uses the ippusb:// scheme, then CUPS sends a request to ippusb_manager to broker a socket for communication with the printer by way of ippusbxd.
  • The usage of the ippusb:// scheme is specific to Chromium OS.
    • As this is a non-standard extension, printers don't know how to respond to this.
    • We retain the ippusb:// scheme in CUPS configuration etc. on-device, but rewrite the URI to use the ipp:// scheme before communicating with the printer.

Closer look: ippusb_manager

Closer look: keep-alive messages

  • These messages are a feature specific to Chromium OS.
  • Sent from ippusb_manager to ippusbxd to preempt the latter from its timed idle exit.
  • ippusb_manager listens for an explicit acknowledgement before declaring ippusbxd alive and reusing the extant sockets.
  • If no acknowledgement comes, ippusb_manager tries to wait for the sockets to disappear (i.e. that ippusbxd has exited) before spawning a new instance of ippusbxd.

Closer look: ippusbxd

  • Is started by ippusb_manager, as mentioned above.
  • Is always waiting to exit when idle.
  • Blindly shuttles IPP messages between CUPS and the printer.
    • Allocates a pair of threads for every available ippusb interface on a given printer: one for each direction of communication.
    • Does not inspect contents of messages passed.
    • There are no “turns” or state; both threads poll continuously for data and pass it along as quickly as they are able.
  • Holds all available ippusb interfaces on the printer until exit.
    • Some printers (e.g. the Canon DX570) are known to behave erratically if we attempt to release interfaces when we were done with them.
  • Patched in Chromium OS to use UNIX domain sockets rather than network sockets.

Appendix: minijail usage

  • Both ippusb_manager and ippusbxd are run from inside minijail instances and retain their own seccomp filters.
  • Forked processes inherit seccomp policies from their parents. Since ippusb_manager forks ippusbxd, the former seccomp filter must be a superset of the latter.

Appendix: Q&A

How much of ippusbxd do we use?

We don't use any of the avahi code.

(WRT ippusb_manager) why Unix sockets; why not D-Bus?

We didn't consider D-Bus at the time. The messages are quite simple and CUPS already had code for dealing with Unix sockets.

Can a user plug in more than one USB printer?

Yes, as long as they do not appear to be the same (i.e. present identical VIDs and PIDs). We opine that this is an uncommon enough use case to be an issue.

Can ippusb_manager and ippusbxd have multiple clients?

Preliminary testing indicates that this should work. Sockets are connection-oriented.

Internal Documentation

See the design doc for information about the overall design and how ippusb_manager fits into it. This is accessible only within google.

Code Overview

This repository contains the following subdirectories:

SubdirectoryDescription
etc/initUpstart config files for launching ippusb_manager
udev/udev rules for setting group permissions on ipp-usb printers