Tech Notes

Tech Note #20130002

Unfortunately, Apple has decided to hand over the support of many CUPS filters to The Linux Foundation OpenPrinting Project, which is also responsible for CUPS PPDs. On the one hand, this is probably a good thing, since an independant body whose mandate is to support every kind of printer known to man is also more likely to support all MIME types known to man.

The unfortunate part is that the filter for banner pages has been handed over to the OpenPrinting Project. The really unfortunate part is that the printer test page is also a banner. This means that, when you install CUPS from source, and set up a printer, you can't print a test page to see if the printer works.

Problem Description:

CUPS banner pages, including the printer test page, are created from a simple set of instructions which must be interpreted by a print filter to be turned into an actual, printable page.

Traditionally, this task was handled by a filter called bannertops, which was included in the CUPS build. However, as of CUPS 1.6, the bannertops filter has been unbundled and handed off to The Linux Foundation OpenPrinting Project. Here is the relevant note from the CUPS 1.6 release notes: The parallel and serial backends, php_cups scripting module, and bannertops, commandtoescpx, commandtopclx, imagetops, imagetoraster, pdftops, rastertoescpx, rastertopclx, and texttops filters are now provided as part of a separate cups-filters project hosted by The Linux Foundation..

While later CUPS installations still seem to include support for banner pages in their MIME types list (mime.types, which is typically found in /usr/share/cups/mime/mime.types), the banner filter actually has been removed and there is no hope of this MIME type being printed. On the other hand, the conversion rule for banner pages has disappeared from the MIME conversions list (mime.convs, which is typically found in /usr/share/cups/mime/mime.convs) which would imply that "not working" is the most likely outcome. This is indeed the case. If one tries to print banner pages or a printer test page, one receives an error that reads: Unsupported format "application/vnd.cups-banner".

Bonus points are awarded for the fact that bannertops has been eliminated altogether so you can't just go and find it and build it. As part of the new PDF workflow scheme that is promoted by Canonical, bannertops has been replaced by bannertopdf which converts banners into PDF files. These PDF flies must them be converted by pdftops into printable postscript. In addition, bannertopdf uses completely different banner/test pages so the rule for matching banner pages in mime.types must be changed and the new banner/test pages must be installed.

Problem Resolution:

This note describes two ways to fix the problem. The easiest way to fix just the printer test page is simply to revert to the old postscript test page, which will just be sent directly to your printer, no extra filters necessary. The less friendly way is to actually obtain and install the missing filters, update the MIME types and conversions configurations, and make the current test/banner page scheme work.

Incidentally, as if doing a whole lot of work to just make the test page print weren't reason enough to make you want to revert to the old test page, the new PDF-based test page can be huge, compared to the previous test page and, not only that, it may crash some older postscript printers (some test, huh).

However, if you wish to print banner pages on your print jobs, you pretty much have to use the second method, since banner pages are only printed from PDF templates. Mind you, you still may want to use the first method for the printer test page, due to the aforementioned problems with crashing certain printers.

OK, having said that, here are the two ways to fix the missing test page. You make the choice.

Revert To The Old Test Page:

Begin by downloading the postscript printer test page testprint-1.6.ps.gz.

The printer test page is normally found in the /usr/share/cups/data directory. You will see a file named "testprint". You can overwrite it or you can rename it to something like "testprint.pdf" to keep it around for posterity. Unzip the downloaded file and copy it to the directory, renaming it on the way:

su
mv /usr/share/cups/data/testprint /usr/share/cups/data/testprint.pdf
gunzip -c testprint-1.6.ps.gz >/usr/share/cups/data/testprint

That's all there is to it. You should now be able to print the postscript printer test page using the Web UI or by entering "lpr /usr/share/cups/data/testprint" at the command line.

Make The New PDF-based Test/Banner Pages Work:

Download the latest cups-filters from The Linux Foundation OpenPrinting Project:

http://www.openprinting.org/download/cups-filters/

Unpack the build files:

tar -xvjf cups-filters-1.0.34.tar.bz2

On certain operating systems (e.g. CentOS 6.3), building the filters is a real goat rope, since the prerequisites for the build libraries are way too high for the usual, out of date stuff that RedHat uses. However, it is possible to get by with what's there by bypassing pkg-config.

Begin by finding the libraries and link options to use when building modules that use glib-2.0, IJS and poppler:

pkg-config --libs --cflags glib-2.0
ijs-config --libs --cflags
pkg-config --libs --cflags poppler

The results of these commands are dropped into the configure command:

cd cups-filters-1.0.34
GLIB_CFLAGS="-I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include" \
  GLIB_LIBS=-lglib-2.0 IJS_CFLAGS=-I/usr/include/ijs IJS_LIBS=-lijs \
  POPPLER_CFLAGS=-I/usr/include/poppler POPPLER_LIBS=-lpoppler \
  LIBQPDF_CFLAGS=-I/usr/local/include/qpdf LIBQPDF_LIBS=-lqpdf \
  ./configure

If you don't have all of the prerequisites (i.e. the latest QPDF and poppler), you can fix that situation like so (almost all systems will come with glib-2.0 and IJS already installed).

Since QPDF is used to do all of the heavy lifting in the new PDF workflow scheme of things, you will need to obtain the latest one (older versions generally won't do) from:

http://sourceforge.net/projects/qpdf/files/qpdf/

Extract and build it:

tar -xvzf qpdf-4.1.0.tar.gz
cd qpdf-4.1.0
./configure
su
make install
/sbin/ldconfig

In the case of poppler, our friends at Redhat/CentOS have decided that to install a number of header files in /usr/include, you need to install a whole raft of extra junk, including but not limited to lynx. You've got to be kidding.

If you don't care or you use some other OS, you can just go ahead and slap poppler on using the system's package manager but, if you do care, the solution to this little quandry is to download the RPM by hand from:

http://pkgs.org/centos-6-rhel-6/centos-rhel-i386/\
  poppler-devel-0.12.4-3.el6_0.1.i686.rpm/download/

Make sure you click on the correct "download" link because there are a lot of advertisemens on that page that say "Download" but they ain't what you want.

Install the RPM by hand (look Ma, no lynx):

su
rpm -i --nodeps poppler-devel-0.12.4-3.el6_0.1.i686.rpm

Now, we should be good to go but, since the prerequisites aren't actually met, it is not possible to go ahead with a normal build. Instead we just build the pieces that we need:

cd cups-filters-1.0.34
make bannertopdf
make pdftops

The install won't work either but we can install the filter modules by hand:

su
cp bannertopdf /usr/lib/cups/filter
cp pdftops /usr/lib/cups/filter
chmod u=rwx,go=rx /usr/lib/cups/filter/*

We need to get rid of the CUPS-provided banners and test page and replace them with the new PDF-based ones:

su
rm -f /usr/share/cups/banners/*
rm -f /usr/share/cups/data/*
cp banners/* /usr/share/cups/banners
cp data/* /usr/share/cups/data
chmod ugo=r /usr/share/cups/banners/*
chmod ugo=r /usr/share/cups/data/*

Now, we need to create two config files to override the banner handling (mishandling) in the CUPS installation.

/etc/cups/local.types:


#
#   Local MIME types file for CUPS Filters.
#
#   This file does two things:
#
#        Identifies MIME types that can be printed by CUPS.  If a file
#        with a particular MIME type is found herein, CUPS can print it.
#        If not, it is an unsupported type.
#
#        Employs rules that look into the file to be printed, to
#        automatically determine what MIME type a file should be
#        given.
#
#   Note that a MIME type doesn't have to have a rule associated with
#   it.  If it doesn't, the file must have been determined to be of
#   that MIME type through some other means (e.g. a filter has
#   converted a file to a known type).
#

########################################################################
#
# Banner types...
#

application/vnd.cups-pdf-banner     string(0,'#PDF-BANNER')

/etc/cups/local.convs:


#
#   Local MIME conversions file for CUPS Filters.
#
#   This file describes how to convert files of one MIME type to files
#   of another.
#

########################################################################
#
# Text filters...
#

application/x-cshell    application/pdf              0    texttopdf
application/x-csource   application/pdf              0    texttopdf
application/x-perl      application/pdf              0    texttopdf
application/x-shell     application/pdf              0    texttopdf
text/plain              application/pdf              0    texttopdf
text/html               application/pdf              0    texttopdf

########################################################################
#
# PDF filters
#

application/pdf   application/postscript             66   pdftops

########################################################################
#
# Banner types...
#

application/vnd.cups-pdf-banner   application/pdf    33   bannertopdf

After the two files are created, set their ownership and perms:

su
root:lp /etc/cups/local*
u=rw,g=r,o= /etc/cups/local*

Restarting the CUPS scheduler should make the test/banner pages start working. If not, you might want to read the notes in Tech_20130003 about how to troubleshoot CUPS filter and backend problems.

And, to be fair, the PDF-based test/banner pages do not necessarily crash older postscript printers. Its just that, in some cases, the print file that is generated is so large (e.g. 35MB for the printer test page) that it looks like the printer has crashed, although it eventually prints the page, if you wait long enough. Given this situation, you might also want to read the notes in Tech_20130005 about how to make sure that PDF and text files print properly on older printers.