5.7. Command-Line Tools for the CUPS Printing System

The command-line tools of the CUPS printing system and their manual pages are included in cups-client. Further documentation is provided by cups and installed in /usr/share/doc/packages/cups, in particular the CUPS Software Users Manual, found at /usr/share/doc/packages/cups/sum.html and the CUPS Software Administrators Manual at /usr/share/doc/packages/cups/sam.html. If a CUPS daemon runs locally on your host, you should also be able to access the documentation at http://localhost:631/documentation.html.

As a general rule, it is useful to remember that CUPS command-line tools sometimes require options be supplied in a certain order. Consult the corresponding manual pages if you are unsure about specific options.

5.7.1. Managing Local Queues

5.7.1.1. Printing Files

To print a file, enter the System V style print command lp -d queuename file or a Berkeley style command like lpr -Pqueuename file.

Additional information can be obtained with man lpr and man lp as well as in the section Using the Printing System of the CUPS Software Users Manual (/usr/share/doc/packages/cups/sum.html#USING_SYSTEM).

The -o parameter allows specification of a number of important options, some of which directly influence the type of printout. More information is available in the manual page of lpr and lp as well as in the section Standard Printer Options of the CUPS Software Users Manual (/usr/share/doc/packages/cups/sum.html#STANDARD_OPTIONS).

5.7.1.2. Checking the Status

To check the status of a queue, enter the System V style command lpstat -o queuename -p queuename or the Berkeley style command lpq -Pqueuename. If you do not specify a queue name, the commands display information about all queues.

With lpstat -o, the output shows all active print jobs in the form of a queuename-jobnumber listing. With lpstat -l -o queuename -p queuename, the output is more verbose. lpstat -t or lpstat -l -t displays the maximum amount of available information.

For additional information, consult the manual page of lpq, lpstat, and the section Using the Printing System of the CUPS Software Users Manual (/usr/share/doc/packages/cups/sum.html#USING_SYSTEM).

5.7.1.3. Removing Jobs from the Queue

Enter the System V style command cancel queuename-job number or the Berkeley style command lprm -Pqueuename job number to remove the job with the specified number from the specified queue. For additional information, consult the manual page of lprm, cancel, and the section Using the Printing System of the CUPS Software Users Manual (/usr/share/doc/packages/cups/sum.html#USING_SYSTEM).

5.7.1.4. Specifying Options for Queues

To see how to specify hardware-independent options that affect the type of printout, read the section Standard Printer Options in the CUPS Software Users Manual (/usr/share/doc/packages/cups/sum.html#STANDARD_OPTIONS). The section Saving Printer Options and Defaults, which is found at /usr/share/doc/packages/cups/sum.html#SAVING_OPTION, explains how to save option settings.

Printer-specific options affecting the type of printout are stored in the PPD file for the queue in question. List them with the command lpoptions -p queuename -l. The output has the following form:

option/text: value value value ...

The currently active setting is marked with an asterisk (*) to the left, for example:

PageSize/Page Size: A3 *A4 A5 Legal Letter
Resolution/Resolution: 150 *300 600

According to the above output, the PageSize is set to A4 and the Resolution to 300 dpi.

The command lpoptions -p queuename -o option=value changes the value for the given option. With the above sample settings in mind, use the following command to set the paper size for the specified queue to Letter:

lpoptions -p <queuename> -o PageSize=Letter

If the above lpoptions command is entered by a normal user, the new settings are stored for that user only in the file ~/.lpoptions. In contrast, if the lpoptions command is entered by root, the settings specified are stored in /etc/cups/lpoptions and become the default for all local users of the queue. The PPD file is not touched by this, however.

If (and only if) you change the contents of a PPD file for a given queue, the new settings apply to all users in the local network who print through this queue. The system administrator can change the defaults of a PPD file with a command like:

lpadmin -p <queuename> -o PageSize=Letter

For more information, refer to the Support Database article Print Settings with CUPS.

5.7.2. Managing Remote Queues

For each of the commands explained below, replace printserver with the name or IP address of your print server. queuename must be a queue on the print server. This section merely covers the basic commands. Additional options and information sources are referred to in Section 5.7.1. “Managing Local Queues”.

5.7.2.1. Printing Files

You can use the System V style command lp -d queuename -h printserver file to generate a print job for the specified queue on the specified print server. This is only possible if the print server was configured to accept remote print jobs on its queues. This is not enabled by default in CUPS, but can easily be configured in the CUPS server settings in the YaST printer configuration module.

5.7.2.2. Checking the Status

Check the status of a queue on the print server with the System V style command lpstat -h printserver -o queuename -p queuename.

5.7.2.3. Removing Jobs from the Queue

The System V style command cancel -h printserver queuename-jobnumber removes the print job with the specified job number from the specified queue on the print server.

5.7.3. Using Command-Line Tools for CUPS Troubleshooting

Print jobs will be kept in the printer queue if you shut down the system while a job is being processed. This means a broken print job will still be there even after rebooting and you need to remove it from the queue manually with the commands mentioned above.

Other problems occur if there is some fault in the physical data link between the computer and the printer. The printer may then be unable to make sense of the data it receives and start spitting out lots of pages with garbage on them.

  1. To make sure the printer stops working, first remove all paper from it (in the case of inkjet printers) or open the paper trays (laser printers).

  2. At this point, the print job will often still be in the queue, because jobs are only removed from the queue when all data has been sent to the device. Check which queue is currently printing by entering lpstat -o (or lpstat -h printserver -o) then remove the problematic print job with cancel queuename-jobnumber (or with cancel -h printserver queuename-jobnumber).

  3. Some data might still find their way to the printer in spite of the job having been deleted. To stop this, enter the command fuser -k /dev/lp0 (for a printer at the parallel port) or fuser -k /dev/usb/lp0 (for a USB printer). This kills any processes still using the printer device.

  4. Do a complete reset of the printer by disconnecting it from power for some time. Then put in the paper and switch the printer back on.

You should also be aware that if data cannot get through to the printer or if there is some other major trouble with the data transfer (such as a longer interruption of the data link), the CUPS back-end responsible for the data transfer may abort with an error code. The exact circumstances of this depend on the back-end used (whether it is the back-end for the parallel or the USB port, for the LPD or the IPP server, or the one for direct data transfer via TCP sockets). If a back-end aborts, the CUPS server ceases to print via the queue affected and mark it as disabled or stopped. The system administrator, after having removed the cause of the trouble, must reenable these queues with the command /usr/bin/enable queuename (or with /usr/bin/enable -h printserver queuename).