Oclc Cups

<b>Matthias Apitz, guru@OCLC.org, guru@unixarea.de</b>


== Why CUPS? Overview about CUPS ==

thumb|300px|right|Basic organization of CUPS

1. Because CUPS (Common Unix Printing System) allows a <b>computer to act as a print server</b>. A computer running CUPS is a host that can accept print jobs from client computers, process them, and send them to the appropriate printer.

2. Because CUPS has a web-based administration interface that runs on port 631 (default) and which is easy to use.

3. An overview about the basic organization of CUPS is shown here. It was stolen from [http://www.cups.org/documentation.php/doc-1.5/spec-design.html http://www.cups.org/documentation.php/doc-1.5/spec-design.html] where you might find a full description and how the pieces fit together.

4. Because we U+2665 (<font size="+2" color="red">♥</font>) Unicode: To print Unicode text CUPS translates the text to Postscript with its filter component <b>texttops</b>. As of CUPS version 1.3, texttops itself accepts <b>only</b> Unicode as input and needs fonts to print Unicode characters. OCLC delivers additional FreeFonts wich cover more glyphs as CUPS do;

5. Because CUPS is well documented and OpsenSource maintained; see here: <br> [http://www.cups.org/ http://www.cups.org/] - complete documentation<br> SISIS-SunRise_-_Printing_with_CUPS - OCLC documentation and FAQ

== Installation of CUPS based on sisis-pap/cups ==

1. install sisis-pap which brings all CUPS in /usr/local/sisis-pap/cups/

2. unpack the FreeFonts:

 # <b>cd /usr/local/sisis-pap/cups/share/cups</b>
 # <b>tar xzf /usr/local/sisis-pap/FreeFonts/freefonts.tar.gz</b>

3. fix the permissions of CUPS installation:

 # <b>sh /opt/lib/sisis/tool/unsupported/fixCupsPerms-linux.sh</b>

4. revoke permissions of the system lpr command

 # <b>chmod 0000 /usr/bin/lpr</b>

5. On Linux: remove old CUPS version preinstalled within SUSE Linux by deinstalling packages "cups", "cups-backends" and "cups-client" via YAST.

6. activate CUPS start in /etc/init.d/SunRiseServer by removing the "#" character in

 # /usr/local/sisis-pap/cups/etc/init.d/cups $1

7. additional hints/remarks:

== Configuration of CUPS ==

1. Configure the CUPS daemon "cupsd":

 # <b>cd /usr/local/sisis-pap</b>
 # <b>cp -p cups/etc/cups/cupsd.conf cups/etc/cups/cupsd.conf.ORIG</b>
 # <b>vi cups/etc/cups/cupsd.conf </b>

and make the following changes:

Change the line

 Listen localhost:631


  <b>Listen *:631</b>

Insert after each line of

  Order ....

the following additional line (there are about 15 places to insert and the yy-p of "vi" is as usual your friend)

  <b>Allow all</b>

With this method, you configure CUPS to be administrated from any point of your network; you <b>must</b> later restrict this again! For details about this read the CUPS documentation.

2. Start the CUPS daemon with /etc/init.d/SunRiseServer or with:

 # <b>LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib; export LD_LIBRARY_PATH</b>
 # <b>/usr/local/sisis-pap/cups/etc/init.d/cups start</b>

3. additional hints:

  • again: how to configure and start an older CUPS installation is covered in our central doc

== Adding printers using the web interface ==

1. Start the CUPS daemon cupsd

2. Gather the information for your printer(s), as:

 Protocol URI: socket://  (od lpd://....)
     PPD file: you must have this local on your browser's PC or use <b>Generic Postscript</b>

(I prepared a PPD file here: [http://albatros/~guru/kyocera.ppd http://albatros/~guru/kyocera.ppd]

3. Gather the root-pw of the server

4. Use a browser and go to <code><nowiki>http://</nowiki><i>host</i>:631</code>, we will do it on [http://gonzales.Sisis.de:631/ http://gonzales.Sisis.de:631/]

5. Add the printer using the above information

6. test the printer from the web interface or simple with:

 $ <b>/usr/local/sisis-pap/cups/bin/lpr -P <i>printername</i> /usr/local/sisis-pap/cups/share/cups/CUPS-UTF8.txt</b>

== Using the command line (for experts) ==

1. SSH to the server from UTF-8 ready terminal and be root

2. set environment for the rest:

 # <b>LANG{{=}}de_DE.UTF-8; export LANG</b>
 # <b>unset LC_ALL</b>

 # <b>PATH=/usr/local/sisis-pap/cups/sbin:$PATH; export PATH</b>

3. Gather the information for your printer(s), as above;

4. copy the PPD file to the server

5. you can add a printer with:

 # <b>lpadmin -U root                                        -p myPrinter                                -D "new printer"                            -L "located in my office"                   -E                                          -v lpd://               -P /tmp/foo.ppd</b>

6. you can delete a printer with:

 # <b>lpadmin -U root -x myPrinter</b>

== Testing printers for compatibility with SISIS-SunRise ==

1. run a test with some UTF-8 text file, for example:

 $ <b>/usr/local/sisis-pap/cups/bin/lpr -P <i>printername</i> /usr/local/sisis-pap/cups/share/cups/CUPS-UTF8.txt</b>

2. additional hints:

  • on older CUPS versions pre 1.3.7 you must set the LANG if you want to print Unicode text files to Postscript (i.e. this is not necessary for 'raw' printing); set:
 $ <b>LANG{{=}}de_DE.UTF-8; export LANG</b>
 $ <b>unset LC_ALL</b>
 $ <b>/usr/bin/lpr -P <i>printername</i> /usr/local/sisis-pap/cups/share/cups/CUPS-UTF8.txt</b>

== It does not print what I was expecting, and now? ==

If a printer does not print at all or does not print Unicode output correctly check:

1. the configuration of the printer in <code> <nowiki>http://</nowiki><i>host</i>:631/printers/<i>printername</i></code> <br> 2. does the <i>printername</i> respond on ping from the host? <br> 3. is the configured port (9100 or 515, for LPD) reachable by telnet? <br> 4. print the "Printer Test Page" which can be created by clicking the button "Drucker Testseite" on page<code> <nowiki>http://</nowiki><i>host</i>:631/printers/<i>printername</i></code> <br> 5. does the printer has a PPD file or is Generic Postscript? if not CUPS can't print UTF-8 on the fly; <br> 6. enable debug in cupsd.conf, restart cupsd and look into the file /usr/local/sisis-pap/cups/var/log/cups/error_log; check if texttops is called at all (grep is your friend) <br>

 # <b>vi /usr/local/sisis-pap/cups/etc/cups/cupsd.conf</b>
 # ...
 # Log general information in error_log - change "warn" to "debug"
 # for troubleshooting...
 LogLevel warn

== Frequently Asked Questions (FAQ) ==

=== Changing URL when using CUPS web interface with hostname ===

With the CUPS standard configuration you may only access the CUPS web interface using the IP address of the host on which CUPS is running. By adding the following line in the configuration file "cupsd.conf"

 ServerAlias *

you will be able to access the CUPS web interface by IP address of the host as well as by its name:


You may also control the entries in your file "/etc/hosts" which should contain the full name of your host. If the file only contains an entry like test22

this may result in the error message "Fehler: Server nicht gefunden. Der Server unter test22 konnte nicht gefunden werden." To avoid this, complete the line with the full server name, for example test22.<i>yourdomain</i>.xx test22

=== Access to CUPS web interface by OCLC for support purposes ===

If an OCLC employee needs to access the CUPS web interface of a customer host, he needs to execute an ssh command like the following on internal host "kerry":

 ssh -t -C -g -L 4631:xx.xx.xx.xx:631 sisis@yy.yy.yy.yy

Thus you will be able to access the CUPS web interface by an URL like the following:


While doing this, <code>xx.xx.xx.xx</code> must be the actual IP address of the customer host as seen in file "/etc/hosts" or its DNS FQDN, and especially must <b>not</b> not be "localhost" or

Also, on the customer host the file "cupsd.conf" must contain the following line:

 <b>vi /usr/local/sisis-pap/cups/etc/cups/cupsd.conf</b>
 ServerAlias kerry

=== Error page when adding new printer ===

Suppose you have started the CUPS daemon and connected with your web browser to port 631 of the host, trying to configure a printer. When asked for the protocol, the name of the printer and some comments, the system renders an "error page" instead of allowing you to enter the printer model or the PPD file. What is wrong?

Make sure the CUPS daemon is started with the variable "LD_LIBRARY_PATH" set correctly as described above:

 # <b>LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib; export LD_LIBRARY_PATH</b>
 # <b>cd /usr/local/sisis-pap</b>
 # <b>cups/etc/init.d/cups start</b>

=== Which protocol to use with a new printer ===

Basically, you may use one of the protocols that is supported by the actual printer - usually you will find more information on this in the accompanying guide or in the configuration used up to now.

In most cases it will be the best choice to use protocol LPD (<code>lpd://<i>host</i>/...</code>). Nevertheless if you decide to use protocol socket, make sure to extend your URL with "?waiteof=false" (<code>socket://<i>host</i>:9100/?waiteof=false</code>).

You will find more on protocols to be used with CUPS in the document http://www.cups.org/documentation.php/doc-1.4/network.html

=== Slow printing when using protocol "socket" ===

The CUPS backend (e. g. "socket") asks the printer via SNMP for various characteristics - many older printers don't understand these requests and thus won't answer, or a firewall prevents the request to the printer on port 161. Unfortunately this feature can't be deactivated in CUPS at the moment, but is it planned to include a corresponding parameter in the file "cupsd.conf" of CUPS 1.4.7.

There is a workaround to nevertheless deactivate these SNMP requests which result in a waiting time of about 4 seconds per print job.

 Printer configured with PPD file 

Add the following line in the respective PPD file:

 *cupsSNMPSupplies: False

This line should be included at the very end just <b>before</b> the following final comment line:

 *% End of PPD file for

 Printer configured without PPD file 

Create CUPS filter file "dummy" with the following content.

 # a dummy Filer for CUPS, see also PPD file dummy.ppd
 cat $6

Install the CUPS filter "dummy" as follows.

 $ <b>cp dummy /usr/local/sisis-pap/cups/lib/cups/filter/dummy</b>
 $ <b>chown root:root /usr/local/sisis-pap/cups/lib/cups/filter/dummy</b>
 $ <b>chmod 0555 /usr/local/sisis-pap/cups/lib/cups/filter/dummy</b>

Create PPD file "dummy.ppd" with the following content.

 *PPD-Adobe: "4.3"
 *% Dummy PPD
 *FormatVersion: "4.3"
 *FileVersion:   "1.1"
 *LanguageVersion: English
 *LanguageEncoding: ISOLatin1
 *PCFileName:    "dummy.ppd"
 *Manufacturer:  "Test"
 *Product:       "(SNMPOFF)"
 *cupsFilter:    "text/plain 0 dummy"
 *cupsSNMPSupplies: False
 *ModelName:     "SNMPOFF"
 *ShortNickName: "SNMPOFF"
 *NickName:      "SNMPOFF"

Now reconfigure the respective printer using PPD file "dummy.ppd".

=== PPD files for HP printers ===

CUPS 1.4.3 coming with package "sisis-pap" V4.1 does not include Foomatic filters. If you try to configure HP (Hewlett-Packard) printers you may instead use the driver "Generic PostScript Printer" from the group "Generic".

When printing preformatted PCL files you will need to add option "-l" to suppress processing by the filter "Generic".

=== Controlling Font Size ===

use -o cpi=nn (chars per inch), like:

 $ <b>/var/spool/sisis-pap/cups/bin/lpr -o cpi=10 -P<i>printername</i></b>

=== Printing of Unicode text via CUPS takes longer time than before ===

UTF-8 text files from within SISIS-SunRise (acquisition letters, catalogue lists etc) are sent to the printer via CUPS (which processes all text data as Postscript) and FreeFonts; the necessary fonts (glyphs) are sent to the printer together with the data; the resulting file is about 1 MB of size; the printing of such a file takes about 200 seconds for 10 separate files of one A4 page each, thus printing of one page takes about 20 seconds and so takes definitely longer than in SISIS-SunRise pre-V4.0.

To shorten printing time you may print Unicode text using the character set ISO 8859-1 (see Using of character set ISO 8859-1).

A different approach to significantly increase printing speed of UTF-8 text files is proceeding as follows. You may include the following commands in scripts which are then used as printer command within SISIS-SunRise.

  • Direct SISIS-SunRise printing output not to CUPS but into file "file.utf8"
  • Convert file "file.utf8" to Postscript. File "xxx.ppd" is any existing PPD file of the matching target printer.
 $ <b>CHARSET=utf-8; export CHARSET</b>
 $ <b>PPD=/usr/local/sisis-pap/cups/etc/cups/ppd/xxx.ppd; export PPD</b>
 $ <b>/usr/local/sisis-pap/cups/lib/cups/filter/texttops 1 rleigh myfile 1 "" file.utf8 > file.ps</b>
  • Convert Postscript file "file.ps" to PCL. Te resulting file "file.pcl" is only about 200 KB of size. The necessary command "gs" is not part of package "sisis-pap" but can be obtained for SLES as RPM resp. for Solaris as pkg.
 $ <b>gs -dBATCH -dNOPAUSE -sDEVICE=ljet4 -sOutputFile=file.pcl -sPAPERSIZE=a4 file.ps</b>
  • Print the resulting PCL file "file.pcl" in raw mode. The printing of 10 such PCL files will take only about 50 seconds, thus about 5 seconds per page.
 $ <b>/usr/local/sisis-pap/cups/bin/lpr -P<i>printername</i> -l file.pcl</b>

A working example script to do this all in one step was attached in JIRA to [https://issues.oclcpica.org/browse/SRP-16389 SRP-16389] as file "utf8TextToPCL.sh" for use as:

 $ <b>utf8TextToPCL.sh <i>printername</i> < utf8-file</b>

{{Info|The above method creates a raster image of the output and sends this as PCL. You must not have 'LF->CRLF' or any other conversion enabled at the printer of Windows print spooler.}}

=== Using of character set ISO 8859-1 ===

Using SISIS-SunRise V4.x you may still apply character set ISO 8859-1 to print Unicode text (see Using lpr option "-l"). In this case, of course, all genuine Unicode characters will be lost!

To print the Unicode text file "file.utf8" applying the character set ISO 8859-1 you may use the following printing command:

 $ <b>iconv -c -f utf-8 -t iso-8859-1 < file.utf8 |      /usr/local/sisis-pap/cups/bin/lpr -P <i>printername</i> -l</b>

=== Using lpr option "-l" ===

{{Info|Usage of lpr option "-l" won't affect printing PCL and Postscript files!}}

When printing ISO 8859-1 text files using the lpr option "-l" (literal) you may experience the following problems.

; Problem : The ISO 8859-1 umlauts are mutilated. ; Solution : The internally configured code page of your printer is not "ISO 8859-1" (resp. "latin1" in some printers). You have to configure the correct code page in your printer.

; Problem

You experience the so called "staircase effect" which could look like this
<br><br><tt>abcd<br>    efgh<br>        ijkl<br>            and so on, right off the page.</tt><br>

; Solution

The printer is not correctly configured concerning <b>End-of-line Termination</b>, esp. is should have
 CR  --> CR
 LF  --> CR+LF
 FF  --> CR+FF 

(CR means CarriageReturn, LF means LineFeed and FF means FormFeed; and the expression should be read as "when the printer receives a LF he should carry out CR+LF). Best solution is to correctly configure your printer! If this is not possible you may use one of the following printing commands which embed PCL sequences before the to be printed data to switch the printer to the code page ISO 8859-1 (using file "iso.pcl") or to set the correct handling for "LF" (using file "lfcr.pcl"):

 $ <b>( cat iso.pcl ; iconv -c -f utf-8 -t iso-8859-1 < file.utf8 ) |      /usr/local/sisis-pap/cups/bin/lpr -P <i>printername</i> -l</b>

 $ <b>( cat iso.pcl lfcr.pcl ; iconv -c -f utf-8 -t iso-8859-1 < file.utf8 ) |      /usr/local/sisis-pap/cups/bin/lpr -P <i>printername</i> -l</b>

; Problem : You need to increase or decrease the font size of your printer output but the lpr option "-o cpi=<i>nn</i>" can only be used when printing Postscript files, it cannot be combined with lpr option "-l". ; Solution

Per default most printers print 8 chars per inch (cpi). To get printer output using a 12 cpi you may use a command like the following one (which just extends the command above with the file "cpi12.pcl")
 $ <b>( cat iso.pcl lfcr.pcl cpi12.pcl ; iconv -c -f utf8 -t iso-8859-1 < text.utf8 ) |      /usr/local/sisis-pap/cups/bin/lpr -P <i>printername</i> -l</b>

; General hint about how to produce such PCL files.

The following command gives (as an example) the mentioned file "cpi12.pcl"
 $ <b>printf "\033(s12H" > cpi12.pcl</b>
 $ <b>printf "\033(0N"   > iso.pcl</b>
 $ <b>printf "\033&k2G"  > lfcr.pcl</b>
And you should check the result with (for example)
 $ <b>od -c cpi12.pcl</b>
 0000000  033   (   s   1   2   H

: About such PCL sequences you have to consult a HP User's Reference Manual or your local printer guru. The full set of the PCL is out of the scope of this wiki.

=== Postscript prints are looking rare ===

When you print a Postscript file (or an UTF-8 text file which is converted on the fly by CUPS to Postscript) and the printout looks somewhat "rare" to you, i.e. beginning like this:<br><br><tt> %!PS-Adobe-3.0<br> BoundingBox: 0 0 595 842<br> %cupsRotation: 0<br> Creator: texttops/CUPS v1.4.6<br> CreationDate: miercoles 27 jul 13:25:13 2011<br> Title: (myfile)<br> </tt><br> or even like this (because there is always a good chance that things happen even worser):<br><br><tt> %!PS-Adobe-3.0<br>               BoundingBox: 0 0 595 842<br>                                         %cupsRotation: 0<br>                                                         Creator: texttops/CUPS v1.4.6<br> </tt><br> then this could mean, either

  • your printer does not detect and switches automagically to Postscript (check the printers manual for this, this is most of the times an option in the configuration of the printer)
  • or your printer does not understand Postscript at all.

In the latter example above, in addition it has the already described so called "staircase effect" enabled. The solution is to raster Postscript files to PCL as described above.

=== The filter "texttops" is not called and not visible in the file error_log ===

As its name suggests, the CUPS's filter "texttops" translates "text" to "ps" (Postscript). This only makes sense and will work if the <b>printer is really a and defined as a Postscript printer</b>. It must be configured in CUPS as such and especially a <b>PPD</b> (Postscript Printer Definition) must exist in "/usr/local/sisis-pap/cups/etc/cups/ppd/<i>printername</i>.ppd .

== Small Reference Table of known working printers ==

During implementation projects customers or we as OCLC configured the following printers in CUPS to work with SunRise. This table can be consulted in case of doubts or trouble. By no means it is complete. If you have configured another printer just let us know the details and we will add your printer here.

{| cellspacing="0" cellpadding="2px" border="1" class="sortable" |- align="left" style="background: none repeat scroll 0% 0% lightgrey; color: black;" | width="200" align="LEFT" | <b>Printer model / Type</b> | width="400" align="LEFT" | <b>Configuration in CUPS</b> | width="100" align="LEFT" | <b>Emulation</b> | width="100" align="LEFT" | <b>Contact in OCLC and/or Customer</b> | width="500" align="LEFT" | <b>Remarks</b> |-

| Kyocera Mita FS1010 | Model: Generic<br>PPD: dummy.ppd<br>URI: <code>socket://AE-01071:5555/?waiteof=false</code> | PCL4, PCL6, Postscript | [matthias.apitz@oclc.org matthias.apitz@oclc.org] for BSB |

  • the unusual port 5555 is the one used by a Windows print spooler (Multi-TE) to which the printer is attached via USB; prints a PCL4 page in 15 secs.


| Canon iR3225N | URI: <code>lpd://<i>ip-address</i>/</code><br>Marke: Raw<br>Modell: Raw Queue (en) | PCL4, Postscript is unknown | [michael.kuhn@oclc.org michael.kuhn@oclc.org] for BTU Cottbus |

  • Actually only printing of ISO 8859-1 files was tested
  • also the files "iso.pcl" and "lfcr.pcl" were used since it was not wanted to change codepage and sawtooth distortion on the printer itself.


| Lexmark T640 | URI: <code>lpd://<i>ip-address</i>/</code><br>Marke: Generic<br>Modell: Generic PostScript Printer (en) | PCL?, Postscript | [michael.kuhn@oclc.org michael.kuhn@oclc.org] for Riehen and Schwyz |

  • tested: Postscript and PCL



<!-- scheint nicht zu taugen: === "Laufzettel" (acquisition) ===

{| cellspacing="0" cellpadding="2px" border="1" class="sortable" |- align="left" style="background: none repeat scroll 0% 0% lightgrey; color: black;" | width="200" align="LEFT" | <b>Printer model / Type</b> | width="400" align="LEFT" | <b>Configuration in CUPS</b> | width="100" align="LEFT" | <b>Printer command</b> | width="100" align="LEFT" | <b>Contact in OCLC and/or Customer</b> | width="500" align="LEFT" | <b>Remarks</b> |-

| Müller Hardware MH832 | Verbindung: <code>lpd://<i>ip-address</i>/</code><br>Marke: Raw<br>Modell: Raw Queue (en) | <code>/usr/local/sisis-pap/cups/bin/lpr -l -P <i>printername</i> <i>file</i></code> | [michael.kuhn@oclc.org michael.kuhn@oclc.org] for BTU Cottbus | Printer connected via print server |-


<!-- scheint nicht zu taugen: === "Magazinzettel" (circulation) ===

{| cellspacing="0" cellpadding="2px" border="1" class="sortable" |- align="left" style="background: none repeat scroll 0% 0% lightgrey; color: black;" | width="200" align="LEFT" | <b>Printer model / Type</b> | width="400" align="LEFT" | <b>Configuration in CUPS</b> | width="100" align="LEFT" | <b>Printer command</b> | width="100" align="LEFT" | <b>Contact in OCLC and/or Customer</b> | width="500" align="LEFT" | <b>Remarks</b> |-

| Müller Hardware MH832 | Verbindung: <code>lpd://<i>ip-address</i>/</code><br>Marke: Raw<br>Modell: Raw Queue (en) | <code>/usr/local/sisis-pap/cups/bin/lpr -l -P <i>printername</i> <i>file</i></code> | [michael.kuhn@oclc.org michael.kuhn@oclc.org] for BTU Cottbus | Printer connected via print server |-


== Questions? ==

Category:SISIS-SunRise C C C Category:SISIS-SunRise customer Wiki page