How to fix 404 errors on the CUPS web administration page

Thu 19 January 2012

A bizarre bug I ran into today has lots of CUPS users scratching their head, but I’ve fortunately found the problem.

In this particular bug, going to the CUPS web admin page (typically accessed at http://localhost:631/) gives you a 404 error. But here’s the unusual part - going to localhost:631/printers/ brings you to the printer page. Now one issue that happens to be the case for some of the more esoteric distros is that they improperly set the DocumentRoot when they build CUPS. It should be in a CUPS directory in /usr/share (the default is /usr/share/doc/cups), and the correct folder should have an index.html file and a cups.css file. This can be fixed by simply adding the following lines to /etc/cups/cupsd.conf:

# Set the document root for the web interface
# Note - /usr/share/cups/www is the root for Fedora/Red Hat,
# yours may be different
DocumentRoot /usr/share/cups/www

Now, if you thought that was hairy, it can always get worse. As it turns out, the Red Hat and Fedora RPM’s consider several of the web admin files (such as index.html) as documentation - not totally crazy as the CUPS folks thinks so as well. As such, if you happen to have —excludedocs as an RPM/YUM/kickstart argument, this will break the CUPS web admin panel, and you will get the 404 error. Simply reinstall but with the argument removed, and you should be fine.