File README-beh.html of Package cups-backends
<html><head>
<meta name="description" content="<!-- content: undefined tag: description -->"><title>beh - The Backend Error Handler</title></head><body bgcolor="#ffffff">
<table border="0" cellpadding="6" cellspacing="0" width="100%">
<tbody><tr>
<td bgcolor="#ffffff" width="100%"> <!-- top bar -->
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tbody><tr>
<td><font size="+3">
<a href="http://www.linuxprinting.org/beh.html">beh</a> -
The Backend Error Handler</font></td>
<!-- could put other stuff here flush right in with title -->
</tr>
</tbody></table>
</td>
</tr>
<tr>
<td height="100%" valign="top" width="100%"> <!-- contents -->
<!-- header/announcementy things go here -->
Very annoying with CUPS is that when an error on the communication
between the CUPS backend and the printer occurs, CUPS disables the
print queue and to be able to continue printing an administrator (root
access required) has to re-enable the queue. It is not enough to
simply fix the printer's communication problem (like turning it on,
fixing the network connection, ...).<p>
This is especially a very bad design for desktop/home users. They
often only turn on their printers when they really want to print (to
save energy). Then it happens easily that they send a job and forget
to turn on the printer. CUPS disables the queue and the annoying
re-enabling procedure has to be done. And many users even do not know
about the problem. So the printer does not print and the queue gets
nuked and re-created. Or the people cry on the help forums or at the
installation support of their distributions.</p><p>
This problem can be easily worked around by installing <tt><a href="http://www.linuxprinting.org/download.cgi?filename=beh&show=0">beh</a></tt>, the
<b>B</b>ackend <b>E</b>rror <b>H</b>andler. This script makes the
handling of such backend errors configurable, so that the problem can
easily be worked around. The new possibilities are:</p><p>
</p><ul>
<li> Let queues simply not being disabled. Simple approach, but job gets
lost.
</li><li> Repeat a given number of times.
</li><li> Repeat infinitely often, until the job gets finally through. This
is the standard of LPRng, and it eliminates loss of the job.
</li><li> The interval between two attempts to run the backend can also be
configured.
</li><li> Configuration is done independently for each print queue. So local
printers and network printers can be treated differently.
</li></ul><p>
Simply <a href="http://www.linuxprinting.org/download.cgi?filename=beh&show=0">download</a> the
script, copy it into the CUPS backend directory (normally
<tt>/usr/lib/cups/backend/</tt>), and make it executable with
"<tt>chmod 755 beh</tt>. Then restart CUPS that it registers the new
backend, usually with "<tt>killall -HUP cupsd</tt>" or
"/etc/init.d/cups restart". If you did all correctly, there must be a
line containing "<tt>beh</tt>" in the output of "<tt>lpinfo
-v</tt>".</p><p>
<tt>beh</tt> is a wrapper which is called by CUPS in place of the usual backend, which is called by <tt>beh</tt> now. This way <tt>beh</tt>
can, depending on its configuration, repeat the call of the backend or
simply hide the error status of the backend from being seen by the CUPS
daemon.</p><p>
To make a print queue usinf <tt>beh</tt>, get root and call a command as follows:</p><p>
<tt>lpadmin -p <queue name> -E -v beh:/<dd>/<att>/<delay>/<originaluri></tt></p><p>
with</p><p>
</p><dl>
<dt><tt><queue name></tt>:
</dt><dd>The name of your print queue<p>
</p></dd><dt><tt><dd></tt>:
</dt><dd>Don't Disable, if "<tt>1</tt>", <tt>beh</tt> always exits with
zero status, so the queue gets never disabled when the original
backend exits with an error. "<tt>0</tt>" carries the error
status of the last call of the backend (after
<tt><att></tt> retries) on to CUPS, so the queue usually
gets disabled.<p>
</p></dd><dt><tt><att></tt>:
</dt><dd>Attempts, number of attempts to recall the backend in case of
an error. "<tt>0</tt>" means infinite retries. In this case
<tt><dd></tt> gets meaningless.<p>
</p></dd><dt><tt><delay></tt>:
</dt><dd>Delay between two attempts to call the beckend, to be given in
seconds and as an integer number. Meaningless if
<tt><att></tt> is one.<p>
</p></dd><dt><tt><originaluri></tt>:
</dt><dd>The original URI, which your queue had before (use "<tt>lpstat
-v</tt>" to get your queue's URI shown).<p>
</p></dd></dl><p>
All parameters, especially, <tt><dd></tt>,
<tt><att></tt>, and <tt><delay></tt> have always to be
specified, even if one of them is meaningless due to the setting of
the others.</p><p>
<tt>beh</tt> works with every backend except the <tt>hp</tt> backend
from <a href="http://hpinkjet.sf.net/">HPLIP</a>. If <tt>beh</tt> is
used with the <tt>hp</tt> backend, the HP Toolbox will not find the
printers any more.</p><p>
Example URIs:</p><p>
</p><dl>
<dt><tt>beh:/1/3/5/socket://printer:9100</tt>
</dt><dd>On the network printer with host name "<tt>printer</tt>" it is
tried to access 3 times with 5 second delays between the
attempts. If the job still fails, the queue is not disabled
(and the job discarded).<p>
</p></dd><dt><tt>beh:/0/10/60/socket://printer:9100</tt>
</dt><dd>Retry 10 times in one minute intervals, disable the queue when
still not succeeding.<p>
</p></dd><dt><tt>beh:/1/0/60/usb://Brother/HL-5040%20series</tt>
</dt><dd>On a Brother HL-5040 on the USB try infinitely often until the
printer comes back, in intervals of one minute. This way the
job does not get lost when the printer is turned off and one
can intendedly delay printing by simply switching off the
printer. The ideal configuration for desktop printers and/or
home users.<p>
</p></dd></dl><p>
Report bugs in <tt><a href="http://www.linuxprinting.org/forums.cgi?group=linuxprinting.foomatic.devel">linuxprinting.foomatic.devel</a></tt>.
</p></td>
</tr>
</tbody></table>
</body></html>
