SDB:Print Settings with CUPS
This article addresses experienced Linux users.
It does not provide detailed explanations.
Some details here and there could be a bit outdated (depending on the CUPS version) but in general things are still valid.
This article describes CUPS up to version 2.x under Linux with the traditional filtering system and backends there.
The nowadays driverless printing workflow is rather different.
Symptom
You are in charge of the administration of a CUPS printing system and find it very difficult to keep track of the different print queue settings. For example:
- Different users obtain different printouts (bad quality printouts or no printouts at all), even though they print identical data through the same queue.
- In case of network printing, the printouts differ depending on the client machine used, although the user prints identical data through the same queue.
- Different users have different default queue settings.
- Different users have different default paper size settings or there are different default paper size settings in different application programs for the same user.
- In case of network printing, different users use different CUPS servers.
Cause
The cause is not a bug, but a basic feature of CUPS:
- All users can define their own different settings for each queue.
- In addition, "root" can define different settings for every single machine (not only on client machines, but also on the CUPS server).
There is no such thing as "THE" default settings for a print queue.
Solution
The solution is to know where the settings can be stored and which settings are applied in what situation.
Different default queue settings
There is no such thing as "THE" default print queue.
There is even no such thing as a system default print queue.
The usual system default queue is in /etc/cups/printers.conf stored as "DefaultPrinter queue_name" entry which is usually (but see below!) shown when root runs "lpstat -d". The usual system default queue can be set (as root) via "lpadmin -d queue_name".
Besides this any normal user can have his own default queue which is stored in ~/.cups/lpoptions (since CUPS 1.2 / openSUSE 10.2, it was ~/.lpoptions in CUPS 1.1) when the user runs "lpoptions -d queue_name" so that any user who runs "lpstat -d" could see his own different default queue.
Unfortunately also root can run "lpoptions -d queue_name" which stores a special kind of "semi system default queue" in /etc/cups/lpoptions which may cause confusion because now this queue is shown when root runs "lpstat -d" (and no longer the usual system default queue in /etc/cups/printers.conf). The "semi system default queue" is also used for normal users who do not have their own default queue setting.
Furthermore when a local cupsd is running and accepts CUPS browsing information from remote CUPS print servers about their remote queues, the local cupsd maintains the CUPS browsing information about remote queues in its remote.cache file (/var/cache/cups/remote.cache or /etc/cups/yes/remote.cache).
By default the "DefaultPrinter remote_queue_name" in the remote.cache file is what a remote CUPS server may broadcast as its default queue (but a CUPS server may not have a default queue setting) and this queue may be shown when root runs "lpstat -d" depending on whether or not there are additional system default queue settings at other places.
When several remote CUPS servers broadcast several default queues, it is basically undefined (i.e. an implementation detail of the current local cupsd) which remote default queue will become used as the local default queue (i.e. which queue is shown by the "lpstat -d" command).
It is possible to run as root on the local host the command "lpadmin -d remote_queue_name" and then the local cupsd will store this new kind of system default print queue in its remote.cache file.
Therefore there are three kind of system default print queues:
- A local queue in /etc/cups/printers.conf stored as "DefaultPrinter queue_name".
- A queue in /etc/cups/lpoptions stored as "Default queue_name".
- A remote queue in the remote.cache file stored as "DefaultPrinter queue_name".
But in the end the system default print queue setting does usually not really matter for the users because each user can set and maintain his own default queue so that for the users whatever system default print queue setting is usually irrelevant.
For the default queue setting, there is finally the environment variable "PRINTER". If this environment variable is set to a value other than "lp", this setting determines the default queue with highest priority. If "PRINTER" is set to "lp", it is ignored by CUPS. Reason: For traditional printing systems, there is often an entry in files like /etc/profile or /etc/SuSEconfig/profile which usually sets "PRINTER" to "lp". As this would determine the default queue with highest priority, it would be impossible to set any other default queue with the usual CUPS tools.
If there is no queue set to be the default queue, the first queue in alphabetical order is used by default.
Different default paper size settings
There is no such thing as "THE" default paper size.
There is even no such thing as a system default paper size.
When a print queue is set up, one of the available paper size choices in the PPD file (printer description file) for the particular printer is set as the default paper size for the print queue.
The usual default paper size for a print queue is stored in /etc/cups/ppd/<queue_name>.ppd in the "DefaultPageSize:..." entry. The usual default paper size can be set (as root) for example A4 via "lpadmin -p queue_name -o PageSize=A4" - provided the PPD file for that queue has an option called "PageSize" with a choice "A4", see "Command-line Tools" at SDB:CUPS in a Nutshell.
Usually the "DefaultPageSize" value is either "A4" or "Letter" but there are some printers for which neither "A4" nor "Letter" is an available paper size choice (e.g. small format photo printers) so that there is another default paper size.
It depends on the particular used printer setup tool which default paper size is set automatically when a print queue is set up.
Furthermore the cupsd (which actually writes the config files when a print queue is set up) sets the "DefaultPageSize" value in /etc/cups/ppd/<queue_name>.ppd according to cupsd's "locale" setting. Since CUPS version 1.4 this behaviour can be configured via the "DefaultPaperSize" directive in /etc/cups/cupsd.conf (see http://www.cups.org/documentation.php/doc-1.4/ref-cupsd-conf.html). A "locale" is a set of language and cultural rules, e.g. the usually used paper size in a particular region. Regarding "locale" see "man 7 locale" or have a look at http://en.wikipedia.org/wiki/Locale. The cupsd's locale is usually the locale that system processes run in. This could be different to the locale that the user's desktop and application programs run in. Therefore what a system default paper size should be could be different from the cupsd's point of view compared to the user's point of view.
To avoid unexpected results of the various automated default paper size settings it is recommended to specify the right default paper size (i.e. the size of the paper which is actually loaded in the printer's standard paper input tray) explicitly when a print queue is set up.
Besides this any normal user can have his own default paper size for each print queue stored in ~/.cups/lpoptions (since CUPS 1.2 / openSUSE 10.2, it was ~/.lpoptions in CUPS 1.1) and/or root might have set default paper sizes in /etc/cups/lpoptions for print queues.
Finally any application program and any printing dialog program may use its own default paper size either as hardcoded built-in value or as result of whatever algorithm in the particular program. For example it may depend on the locale setting of the user who runs the program (have a look at SDB:Plain Text versus Locale). It might even happen that an application program uses one default paper size to create a document but then a separated printing dialog program is called which uses another default paper size to print it.
Preferably application programs should query CUPS (more precisely a cupsd which is accessible on localhost or via network) to get the PPD file for a specific print queue and use the "DefaultPageSize" value as default paper size when the application is creating a document which is meant to be printed. Furthermore the application should use the matching "ImageableArea" values in the PPD to make sure that the content of the document does not exceed the actual printable area of the particular printer. Strictly speaking for an application which produces a document which is meant to be printed the page size is irrelevant. Actually only the printable area does matter when it comes to printing a document on a particular printer. Regarding "printable area" and "fit on paper" have a look at SDB:Landscape Printing.
Different CUPS server settings
By default the cupsd which is running on the local client machine is accessed.
But a single remote CUPS server could be specified on a client machine in /etc/cups/client.conf so that this one CUPS server is directly accessed, see the "Client-only configuration" section in the article SDB:CUPS in a Nutshell
Also any individual user can specify his CUPS server via the "CUPS_SERVER" environment variable or a "ServerName host.domain" entry in ~/.cupsrc or since CUPS 1.2 in ~/.cups/client.conf (compare http://www.cups.org/documentation.php/doc-1.2/ref-client-conf.html).
Have in mind that various application programs or destop tools may write to ~/.cupsrc or ~/.cups/client.conf via printing dialogs (e.g. the user may set a print server in his desktop system's printing dialogs).
Different printer specific settings
Example:
For clarification purposes, we have chosen an example of a correct situation that becomes more and more confusing. To keep this example as concise and clear as possible, only command line instructions are used. However, it would make no difference if graphical tools like printer setup tools or printing dialogs in various application programs or the CUPS web frontend were used instead.
Initial state:
The CUPS server is a machine named "sun" to which a color ink jet printer with the queues "mono" and "color" is attached.
Because both queues will be used for the same printer, the same PPD file is used as basis for the two queues, but with different default values preset for each queue.
The PPD files corresponding to the queues /etc/cups/ppd/mono.ppd and /etc/cups/ppd/color.ppd contain the following possible settings and default values:
*DefaultColors: Gray *Colors Gray ... *Colors Color ... ... *DefaultInkCartridge: Black *InkCartridge Black ... *InkCartridge Color ... ... *DefaultResolution: 600dpi *Resolution 150dpi ... *Resolution 300dpi ... *Resolution 600dpi ...
and
*DefaultColors: Color *Colors Gray ... *Colors Color ... ... *DefaultInkCartridge: Color *InkCartridge Black ... *InkCartridge Color ... ... *DefaultResolution: 300dpi *Resolution 150dpi ... *Resolution 300dpi ... *Resolution 600dpi ...
In certain circumstances it makes sense to have several queues with their respective settings for the same printer due to the following reasons:
It might be necessary to change several options when switching between print modes, especially in the case of color ink jet printers, as in the following example:
- For "mono" Colors=Gray and InkCartridge=Black
- For "color" Colors=Color and InkCartridge=Color
Some particular print modes might only work with certain resolutions, especially in the case of color ink jet printers as in the following example:
- The resolutions 150dpi, 300dpi, and 600dpi work for "mono".
- Only the resolutions 150dpi and 300dpi work for "color".
Since SuSE Linux 8.2 (exactly since Foomatic version 3.x) there is the "Printout Mode" option in most of the Foomatic PPD files for inkjet printers. When the user selects a printout mode then all the individual option settigs which are necessary for the particular printing mode are set simulaneously. Therefore one PPD file for one printer is sufficient in this case.
The machines "earth" and "moon" are CUPS clients without queues. In addition to "root", the normal users "tux" and "geeko" are on these machines, too.
Unless the queues have been configured otherwise, the queue "mono" always produces grayscale printouts with a 600 dpi resolution for all machines and the queue "color" always produces color printouts with a 300 dpi resolution.
Now the options will be changed in the following order:
"root" executes the following command on "sun":
lpadmin -p mono -o Resolution=150dpi
to change the default resolution value to 150 dpi in the PPD file /etc/cups/ppd/mono.ppd
*DefaultColors: Gray *Colors Gray ... *Colors Color ... ... *DefaultInkCartridge: Black *InkCartridge Black *InkCartridge Color ... *DefaultResolution: 150dpi *Resolution 150dpi ... *Resolution 300dpi ... *Resolution 600dpi ...
Thus, the queue "mono" prints in grayscale with a 150 dpi resolution for all users on all machines.
Then "root" executes the following command on "sun":
lpoptions -p mono -o Resolution=300dpi
to set the default resolution value to 300 dpi only for the machine "sun" in its file /etc/cups/lpoptions:
Dest mono Resolution=300dpi
Thus, "mono" prints in grayscale with a 300 dpi resolution for all the users on "sun" and in grayscale with a 150 dpi resolution for all users on "earth" and "moon".
Now "root" executes the following command on "earth":
lpoptions -p mono -o Resolution=600dpi
to set the default resolution value to 600 dpi only for the machine "earth" in its file /etc/cups/lpoptions:
Dest mono Resolution=600dpi
Thus, "mono" prints in grayscale with a 600 dpi resolution for all the users on "earth", in grayscale with a 300 dpi resolution for all the users on "sun", and in grayscale with a 150 dpi resolution for all the users on "moon".
The normal user "tux" executes the following command on "earth":
lpoptions -p mono -o Resolution=300dpi
to set his default resolution value as 300dpi in his home directory in the file ~/.cups/lpoptions (since CUPS 1.2 / openSUSE 10.2, it was ~/.lpoptions in CUPS 1.1):
Dest mono Resolution=300dpi
Thus, "mono" prints in grayscale with a 300 dpi resolution for the user "tux" on "earth" and in grayscale with a 600 dpi resolution for the rest of users on "earth". The settings on "sun" and "moon" remain unchanged.
The user "geeko" executes on "earth" the command
lpoptions -p mono -o Colors=Color
to change his settings for the queue "mono". The new settings for the user "geeko" will be saved in the file ~/.cups/lpoptions (or ~/.lpoptions) in his home directory:
Dest mono Colors=Color
Geeko's settings for the queue "mono" on "earth" make no sense, because two contradictory values are used: Colors=Color and InkCartridge=Black.
"geeko" executes the following command on "earth":
lpoptions -p color -o Resolution=600dpi
to set his options for the queue "color" as follows. The new settings will be saved in his file ~/.cups/lpoptions (or ~/.lpoptions):
Dest color Resolution=600dpi Dest mono Colors=Color
The settings of the queue "color" for "geeko" on "earth" are wrong, because the deployed value is Resolution=600dpi, which does not work for this printer (see above). This results in the queue "color" no longer working for "geeko" on "earth".
"geeko" executes the following command on "earth":
lpoptions -p color -o Resolution=1200dpi -o Foo=Bar
to set his options for the queue "color" as follows. The new settings will be saved in his file ~/.cups/lpoptions (or ~/.lpoptions):
Dest color Resolution=1200dpi Foo=Bar Dest mono Colors=Color
It is possible to set values like Resolution=1200dpi and options like Foo=Bar, even though they are not considered in the PPD file. When printing, however, the default value from the PPD file (Resolution=300dpi) will be used and the option (Foo=...) will be ignored. Thus, the queue "color" works again for "geeko" on "earth", but the set values are totally unsuitable.
When "root" deletes the queue "mono" on "sun" with the command "lpadmin -x mono" the now invalid entries in ~/.cups/lpoptions (or ~/.lpoptions) are not deleted, but remain unchanged (files in user's home directories are sacrosanct).
"root" creates again the queue "mono" on "sun", but a different PPD file is used:
*DefaultColours: Gray *Colours Gray ... *Colours Color ... ... *DefaultResolution: 300x300dpi *Resolution 300x300dpi ... *Resolution 600x600dpi ...
None of the previous entries in the user's ~/.cups/lpoptions (or ~/.lpoptions) files are valid for the new queue "mono", since either the option names no longer match ("Colours" instead of "Colors") so the option is ignored or the option values no longer match ("300x300dpi" and "600x600dpi" instead of "150dpi", "300dpi", and "600dpi") so the default value from the PPD file is used.
General Rules for Setting Definitions
- When the user customizes an option (e.g., in his file ~/.cups/lpoptions (or ~/.lpoptions), those settings will be used for the print job.
- If a file /etc/cups/lpoptions is available on the computer, only the options therein which are not already defined by the user will be used for the print job.
- If any invalid option has been defined in the previous steps, it will be ignored. If any option value is invalid, it will be replaced with the default value from the PPD file.
- Default values for the corresponding queue (i.e. the default values from the PPD file) will be used for the remaining options.
The command
lpoptions -p "queue" -l
displays the possible settings. The values that, according to the rules above, will be used for a print job are marked with a preceding asterisk "*".
According to this, the user "geeko" on "earth" might have used the following command
lpoptions -p color -l
to verify which settings would be used for his print job via the queue "color". He would have seen that the actually used settings do not correspond to the settings in his file ~/.cups/lpoptions (or ~/.lpoptions), because the output would be
Colors: Gray *Color InkCartridge: Black *Color Resolution: 150dpi *300dpi 600dpi
Suggestion for Keeping an Overview
Do not define general presettings separately on each machine. Set the default values in the PPD file:
- If possible, do not use any /etc/cups/lpoptions files.
- If possible, do not execute the command "lpoptions" as "root" on each machine. Instead, execute the command "lpadmin" on the CUPS server.
Remove any unsuitable or unwanted setting from the PPD file manually or add appropriate constraints to the PPD file.
For example, to avoid unsuitable settings as described above, "root" can edit the PPD files /etc/cups/ppd/mono.ppd and /etc/cups/ppd/color.ppd manually on the CUPS server as follows:
*DefaultColors: Gray *Colors Gray ... ... *DefaultInkCartridge: Black *InkCartridge Black ... ... *DefaultResolution: 600dpi *Resolution 150dpi ... *Resolution 300dpi ... *Resolution 600dpi ...
and
*DefaultColors: Color *Colors Color ... ... *DefaultInkCartridge: Color *InkCartridge Color ... ... *DefaultResolution: 300dpi *Resolution 150dpi ... *Resolution 300dpi ...
Adding appropriate constraints to the PPD file is another solution. The constraints usually avoid that the user can select incompatible value combinations in graphical printing dialogs but often appropriate constraints are missing in the PPD files. The example PPD file with constraints may look as follows. Note that each constraint must be specified in both ways - for example: When "*Colors Gray" was selected then "*InkCartridge Color" is no longer allowed and when "*InkCartridge Color" was selected then "*Colors Gray" is no longer allowed.
*UIConstraints: *Colors Gray *InkCartridge Color *UIConstraints: *InkCartridge Color *Colors Gray *UIConstraints: *Colors Color *InkCartridge Black *UIConstraints: *InkCartridge Black *Colors Color *UIConstraints: *Colors Color *Resolution 600dpi *UIConstraints: *Resolution 600dpi *Colors Color *UIConstraints: *InkCartridge Color *Resolution 600dpi *UIConstraints: *Resolution 600dpi *InkCartridge Color ... *DefaultColors: Color *Colors Gray ... *Colors Color ... ... *DefaultInkCartridge: Color *InkCartridge Black ... *InkCartridge Color ... ... *DefaultResolution: 300dpi *Resolution 150dpi ... *Resolution 300dpi ... *Resolution 600dpi ...
Some values might be possible for the printer, but unwanted for a particular queue, such as high resolutions for a "draft" queue. Such option settings should be removed from the PPD file for the particular queue. After manually changing PPD files, the CUPS daemon must be forced to reread the files by using the command "rccups reload" or "rccups restart".
The users must be informed about any queue modification on the CUPS server, if the modification leads to the invalidity of the settings in the users' ~/.cups/lpoptions (or ~/.lpoptions) files, in particular when a different PPD file was used for an existing queue.
Then, the users can use the command
lpoptions -x "queue"
(for example "lpoptions -x mono") to remove the corresponding entries from their ~/.cups/lpoptions (or ~/.lpoptions) files and afterwards the users can reconfigure their personal settings for the relevant queue.
"lpoptions -x" does not work for deleted queues. Invalid entries can be either ignored or manually deleted from the ~/.cups/lpoptions (or ~/.lpoptions) file.
If all personal settings should be configured from scratch, the whole file should first be deleted with the command "rm ~/.cups/lpoptions" since CUPS 1.2 / openSUSE 10.2 or with the command "rm ~/.lpoptions" for CUPS 1.1.