Updated documentation and sample systemd/UDEV config files

doc/ippusbxd.8

@@ -20,9 +20,9 @@ ippusbxd \- Communication driver for IPP-over-USB class printers
 [\fB\-N\fR|\fB--no-printer\fR]
 .SH DESCRIPTION
 .B ippusbxd
-connects to a IPP-over-USB printer and exposes it to a network interface (like localhost or dummy0) on a given port, so that the printer can be accessed like an IPP network printer. If the selected network interface does multicasting the printer is also advertised via DNS-SD on the interface, so \fBCUPS\fP and \fBcups-browsed(8)\fP will auto-discover the printer for easy setup of a print queue.
+connects to a IPP-over-USB printer and exposes it to a network interface (like localhost or dummy0) on a given port, so that the printer can be accessed like an IPP network printer. The printer is also registered at Avahi to be advertised via DNS-SD on the interface, so \fBCUPS\fP and \fBcups-browsed(8)\fP will auto-discover the printer for easy setup of a print queue. This requires avahi-daemon to be running and the network interface to be supported by the Avahi version in use.
 
-Upon successful startup the TCP port it is listening on and the process ID of the daemon are printed to stdout. It will shut itself down when the connected printer disconnects. When not specifying information about the desired printer, \fBippusbxd\fR scans the USB and connects to the first available IPP-over-USB printer.
+Upon successful startup the TCP port it is listening on and the process ID of the daemon are printed to stdout. \fBippusbxd\fR will shut itself down when the connected printer disconnects. When not specifying information about the desired printer, \fBippusbxd\fR scans the USB and connects to the first available IPP-over-USB printer.
 .SH OPTIONS
 .TP
 .B
@@ -55,7 +55,7 @@ Port number \fBippusbxd\fP will expose the printer over. If this port is already
 .TP
 .B
 \fB-i\fP \fIINTERFACE\fR, \fB--interface\fP \fIINTERFACE\fR
-Network interface to use. Default is the loopback interface (lo, localhost). As the loopback interface does not allow DNS-SD broadcasting with Avahi, set up the dummy interface (dummy0) for DNS-SD broadcasting.
+Network interface to use. Default is the loopback interface (lo, localhost).
 .TP
 .B
 \fB-l\fP, \fB--logging\fP
@@ -83,3 +83,5 @@ No-broadcast mode, do not DNS-SD-broadcast
 .B
 \fB-N\fP, \fB--no-printer\fP
 No-printer mode, debug/developer mode which makes \fBippusbxd\fP run without IPP-over-USB printer
+.SH BUGS
+\fBippusbxd\fR does not detect whether a USB printer is already connected by another instance of \fBippusbxd\fR, so the system/the user has to take care to not start \fBippusbxd\fR more than once for one and the same printer. Especially one should never start \fBippusbxd\fR repeatedly without specifying a printer to assure that all connected IPP-over-USB printers get their \fBippusbxd\fR instance.

readme.md

@@ -46,8 +46,9 @@ Under Fedora:
 Once the dependencies are installed simply run:
   make
 
-That will run a makefile which will inturn run cmake. This makefile also
-supports several GNU-style make commands such as clean, and redep.
+That will run a makefile which will in turn run cmake. This makefile
+also supports several GNU-style make commands such as clean, and
+redep.
 
 Installation on a system with systemd, UDEV, and cups-filters
 =======
@@ -59,15 +60,15 @@ provide non-Mac-OS filters, backends, and cups-browsed. Therefore we
 explain only a method using systemd and UDEV here.
 
 In these systems it is recommended to start ippusbxd via systemd when
-an appropriate printer is connected and discovered by
-UDEV. cups-filters from version 1.13.2 on and CUPS from version 2.2.2
-has everything needed to for driverless printer setup. "driverless"
-means that no printer driver, with the driver being any software or
-data specific to (a) certain printer model(s) is needed. driverless
+an appropriate printer is connected and discovered by UDEV.
+cups-filters from version 1.13.2 on and CUPS from version 2.2.2 has
+everything needed for driverless printer setup. "driverless" means
+that no printer driver, with the driver being any software or data
+specific to (a) certain printer model(s) is needed. driverless
 printing makes use of IPP to allow the client to query the printer's
 capabilities and IPP-over-USB was developed to allow these queries
-also if the printer is not on the network but connected via
-USB. Therefore we can assume that all IPP-over-USB printers support
+also if the printer is not on the network but connected via USB.
+Therefore we can assume that all IPP-over-USB printers support
 driverless printing.
 
 A remark to driverless printing: There are two very similar standards:
@@ -87,6 +88,23 @@ Ubuntu. On other distributions there are perhaps some changes needed,
 for example of the directories where to place the file and of paths in
 the files.
 
+There are two methods to install ippusbxd, one exposing the printer
+on localhost. and one exposing the printer on the dummy0 interface.
+
+Exposing the printer on localhost is the way how the IPP-over-USB
+standard is intended and therefore this how it is intended to proceed
+on production system and especially on Linux distributions.
+Disadvantage of this method is that Avahi needs to be modified so that
+it advertises services on localhost and these only on the local
+machine.
+
+Exposing the printer on the dummy0 interface does not require any
+changes on Avahi, but it is more awkward to set up the syetm and to
+access the printer and its web administration interface.
+
+1. Expose the printer on localhost
+----------------------------------
+
 First, install ippusbxd:
 
 sudo cp exe/ippusbxd /usr/sbin
@@ -108,6 +126,140 @@ minutes. Out of UDEV rules you can only start programs which do not
 need to keep running permanently, like daemons. Therefore we use
 systemd here.
 
+Apply the following patch to the source code of Avahi:
+
+----------
+--- avahi-core/iface-linux.c~	2016-02-09 04:12:59.295979998 -0200
++++ avahi-core/iface-linux.c	2017-04-13 11:25:52.103355254 -0300
+@@ -104,8 +104,8 @@
+         hw->flags_ok =
+             (ifinfomsg->ifi_flags & IFF_UP) &&
+             (!m->server->config.use_iff_running || (ifinfomsg->ifi_flags & IFF_RUNNING)) &&
+-            !(ifinfomsg->ifi_flags & IFF_LOOPBACK) &&
+-            (ifinfomsg->ifi_flags & IFF_MULTICAST) &&
++            ((ifinfomsg->ifi_flags & IFF_LOOPBACK) ||
++             (ifinfomsg->ifi_flags & IFF_MULTICAST)) &&
+             (m->server->config.allow_point_to_point || !(ifinfomsg->ifi_flags & IFF_POINTOPOINT));
+
+         /* Handle interface attributes */
+--- avahi-core/iface-pfroute.c~	2015-04-01 01:58:14.149727123 -0300
++++ avahi-core/iface-pfroute.c	2017-04-13 11:28:47.547016465 -0300
+@@ -80,8 +80,8 @@
+   hw->flags_ok =
+     (ifm->ifm_flags & IFF_UP) &&
+     (!m->server->config.use_iff_running || (ifm->ifm_flags & IFF_RUNNING)) &&
+-    !(ifm->ifm_flags & IFF_LOOPBACK) &&
+-    (ifm->ifm_flags & IFF_MULTICAST) &&
++    ((ifm->ifm_flags & IFF_LOOPBACK) ||
++     (ifm->ifm_flags & IFF_MULTICAST)) &&
+     (m->server->config.allow_point_to_point || !(ifm->ifm_flags & IFF_POINTOPOINT));
+
+   avahi_free(hw->name);
+@@ -427,8 +427,8 @@
+         hw->flags_ok =
+             (flags & IFF_UP) &&
+             (!m->server->config.use_iff_running || (flags & IFF_RUNNING)) &&
+-            !(flags & IFF_LOOPBACK) &&
+-            (flags & IFF_MULTICAST) &&
++            ((flags & IFF_LOOPBACK) ||
++             (flags & IFF_MULTICAST)) &&
+             (m->server->config.allow_point_to_point || !(flags & IFF_POINTOPOINT));
+         hw->name = avahi_strdup(lifreq->lifr_name);
+         hw->mtu = mtu;
+----------
+
+Build and install Avahi. This makes Avahi not only advertising
+services on the usual network interfaces but also on the "lo"
+(loopback) interface (localhost). The services on the loopback
+interface (on localhost) are only advertised on the local machine, so
+no additional info gets exposed to the network, especially no
+local-only service gets shared by this.
+
+This works well as long as your machine is connected to some kind of
+network (does not necessarily need to be a connection to the Internet,
+a virtual network interface to virtual machines running locally is
+enough). It is possible that the advertising of the printer stops if
+the loopback interface is the only network interface running due to
+lack of a multicast-capable interface.
+
+Now we can restart systemd and UDEV to activate all this:
+
+sudo systemctl daemon-reload
+sudo systemctl restart udev
+
+If we connect and turn on an IPP-over-USB printer, ippusbxd gets
+started and makes the printer available under the IPP URI
+
+ipp://localhost:60000/ipp/print
+
+and its web administration interface under
+
+http://localhost:60000/
+
+(if you have problems with the Chrome browser, use Firefox).
+
+It is also DNS-SD-broadcasted via our modified Avahi on the lo interface.
+
+To set up a print queue you could simply run
+
+lpadmin -p printer -E -v ipp://localhost:60000/ipp/print -meverywhere
+
+The "-meverywhere" makes CUPS auto-generate the PPD file for the
+printer, based on an IPP query of the printer's capabilities,
+independent whether the printer is an IPP Everywhere printer or an
+AirPrint printer.
+
+To create a print queue with the web interface of CUPS
+(http://localhost:631/), look for your printer under the discovered
+network printers (CUPS does not see that it is USB in reality) and
+select the entry which contains "driverless". On the page to select
+the models/PPDs/drivers, also select the entry containing
+"driverless". Then complete the setup as ususal.
+
+The best solution is to let cups-browsed auto-create a print queue
+when the printer gets connected and remove it when the printer gets
+turned off or disconnected (do not worry about option settings,
+cups-browsed saves them).
+
+To do so, edit /etc/cups/cups-browsed.conf making sure that there is a
+line
+
+CreateIPPPrinterQueues driverless
+
+or
+
+CreateIPPPrinterQueues all
+
+and no other line beginning with
+
+CreateIPPPrinterQueues
+
+After editing the file restart cups-browsed with
+
+sudo systemctl stop cups-browsed
+sudo systemctl start cups-browsed
+
+Now you have a print queue whenever the printer is available and no
+print queue cluttering your print dialogs when the printer is not
+available.
+
+2. Expose the printer on the dummy0 interface
+---------------------------------------------
+
+First, install ippusbxd:
+
+sudo cp exe/ippusbxd /usr/sbin
+
+Make sure that this file is owned by root and world-readable and
+-executable.
+
+Now install the files to manage the automatic start of ippusbxd:
+
+sudo cp systemd-udev/55-ippusbxd.rules /lib/udev/rules.d/
+sudo cp systemd-udev/[email protected] /lib/systemd/system/[email protected]
+
+Make sure that they are owned by root and world-readable.
+
 Now create a "dummy0" network interface:
 
 sudo modprobe dummy

systemd-udev/ippusbxd@.service

@@ -4,5 +4,5 @@ Description=Daemon to make IPP-over-USB printers available as network printers (
 [Service]
 Type=forking
 GuessMainPID=true
-ExecStart=/usr/sbin/ippusbxd --bus-device %I --from-port 60000 --interface dummy0 --logging
+ExecStart=/usr/sbin/ippusbxd --bus-device %I --from-port 60000 --logging
 # ExecStop= Not needed, ippusbxd stops by itself on shutdown of the printer

systemd-udev/ippusbxd@.service.dummy0

@@ -0,0 +1,8 @@
+[Unit]
+Description=Daemon to make IPP-over-USB printers available as network printers (%i)
+
+[Service]
+Type=forking
+GuessMainPID=true
+ExecStart=/usr/sbin/ippusbxd --bus-device %I --from-port 60000 --interface dummy0 --logging
+# ExecStop= Not needed, ippusbxd stops by itself on shutdown of the printer