1.1. Copyright and Disclaimer

Material included in this document from the ifhp distribution Copyright Patrick Powell 1988-1999, where applicable. The rights to distribute this document complete or in part are hereby granted for non-commercial purposes. Partial reproductions must acknowledge the source. Permission to distribute this file together with LPRng, ifhp and `derived works' is explicitly granted.

THE MATERIAL IN THIS DOCUMENT IS PROVIDED WITHOUT FEE AND AS-IS WITH NO WARRANTY REGARDING FITNESS OF USE FOR ANY PURPOSE. THE AUTHOR AND ALL CONTRIBUTORS ARE NOT LIABLE FOR ANY DAMAGES, DIRECT OR INDIRECT, RESULTING FROM THE USE OF INFORMATION PROVIDED IN THIS DOCUMENT.

1.2. Commercial Support

AStArt Technologies (http://www.astart.com) provides commercial support and enhancements for LPRng, ifhp, and other network software. AStArt provides network and system consulting services for UNIX and NT systems, as well as real time and network software.

1.3. Web Site

Web Page: http://www.lprng.com

1.4. FTP Sites

Main FTP Site:

Mirrors:

1.5. Mailing List

To join the LPRng mailing list, please send mail to lprng-request@lprng.ie with the only the word subscribe in the body of the message.

1.6. PGP Public Key

The LPRng and ifhp distributions have MD5 checksum files which are signed with a PGP public key. Here is the key for validating the checksums:

    Type Bits/KeyID    Date       User ID
    pub  1024/00D95C9D 1997/01/31 Patrick A. Powell <papowell@astart.com>
                                  Patrick A. Powell <papowell@sdsu.edu>
    
    -----BEGIN PGP PUBLIC KEY BLOCK-----
    Version: 2.6.3i
    
    mQCNAzLygTQAAAEEANBW5fPYjN3wSAnP9xWOUc3CvsMUxjip0cN2sY5qrdoJyIhn
    qbAspBopR+tGQfyp5T7C21yfWRRnfXmoJ3FVtgToAsJUYmzoSFY08eDx+rmSqCLe
    rdJjX8aG8jVXpGipEo9U4QsUK+OKzx3/y/OaK4cizoWqKvy1l4lEzDsA2VydAAUT
    tCdQYXRyaWNrIEEuIFBvd2VsbCA8cGFwb3dlbGxAYXN0YXJ0LmNvbT6JAJUDBRA0
    XonoiUTMOwDZXJ0BAQ2cBAC7zU9Fn3sC3x0USJ+3vjhg/qA+Gjb5Fi1dJd4solc4
    vJvtf0UL/1/rGipbR+A0XHpHzJUMP9ZfJzKZjaK/d0ZBNlS3i+JnypypeQiAqo9t
    FV0OyUCwDfWybgAORuAa2V6UJnAhvj/7TpxMmCApolaIb4yFyKunHa8aBxN+17Ro
    rrQlUGF0cmljayBBLiBQb3dlbGwgPHBhcG93ZWxsQHNkc3UuZWR1PokAlQMFEDLy
    gTSJRMw7ANlcnQEBYBYD/0zTeoiDNnI+NjaIei6+6z6oakqO70qFVx0FG3aP3kRH
    WlDhdtFaAuaMRh+RItHfFfcHhw5K7jiJdgKiTgGfj5Vt3OdHYkeeh/sddqgf9YnS
    tpj0u5NfrotPTUw39n6YTgS5/aW0PQfO9dx7jVUcGeod1TGXTe9mIhDMwDJI4J14
    =3Zbp
    -----END PGP PUBLIC KEY BLOCK-----

2.1. Additional Recommended Software

The following software is recommended for use with ifhp. If your printer does not support PostScript, PCL, or text printing directly you will need to install GhostScript to convert from PostScript to the printer format and use a suitable text to PostScript converter.

2.2. Installation

The installation procedure uses the configure facility to generate Makefiles. By convention, these files have the following variables that install the ifhp executables and configuration files in the following locations:

The following files are installed as shown below:

The configuration you choose should match that of the LPRng print spooler. For example:

    ./configure --prefix=/usr --sysconfdir=/etc \
      --mandir=/usr/share/man
    
    executables and files in
       /usr/libexec/filters         ifhp
       /etc                         ifhp.conf
       /usr/share/man/man[0-9]      ifhp.man1

First, we untar, configure, compile, and install the software:

    h4: {1} % gunzip -c ifhp-<version>.tgz | tar xvf -
    h4: {2} % cd ifhp-<version>
    h4: {3} % ./configure  [ ... configuration options ]
    h4: {4} % make clean all
    h4: {5} % su   # you must do the following commands as root
    h4: {6} # make install

Modify your printcap file to use ifhp. Your printcap usually has the following format; older version of lpd require :\ at the end of each line of a printcap entry. The :if and :of filter entries are usually the ones of interest.

    lp:
      :lp=xxxx:sd=xxxx:....
      :if=/usr/local/path_to_old_filters/old_if_filter
      :of=/usr/local/path_to_old_filters/old_of_filter

Your new printcap entry will look like the one below. The MODEL information is described in the next section.

    lp:
      :lp=xxxx:sd=xxxx:....
      #  see text for details about the next line
      :ifhp=model=MODEL,status@
      :filter=/usr/local/libexec/filters/ifhp
      # only if you are using accounting or banners
      #:of=/usr/local/libexec/filters/ifhp

Select a suitable printer from the entries in the configuration file (/usr/local/etc/lpd.conf or /etc/lpd.conf). These are described in more detail in the next section.

Shut down and restart your print spooler and then send a job to the printer. If this works and you do not need any further capabilities of ifhp such as error reporting or printer monitoring, then you are finished.

If you want to use additional capabilities, then you should read the detailed instructions in the next couple of sections.

2.3. Printer Models Supported

There are over 500 different printer models, types and configurations supported by ifhp. If your printer is not currently supported and you have documentation about the printer then send mail to the LPRng Mailing List and support will be added.

The default printer is an HP LaserJet 4MP, which supports PostScript Level 3, PCL5, PJL, and has bidirectional communication and a functional pagecounter.

The ifhp.conf configuration file contains configuration entries for various models of printers. Each entry has a name usually corresponding to the model of printer or its basic capabilities. For example, the HP LaserJet 4 printer has the model=hp4 configuration entry. The default printer configuration covers a wide range of network printers manufactured by Hewlett-Packard, Canon, Epson, and others and is for a printer that has a bidirectional communications connection that allows it to report status information and the following capabilities:

1. PJL support (pjl) compatible with HP 4 family of printers

2. PostScript (PS) support (ps).

3. PCL support (pcl).

4. Text files printed as PCL (text, default_language=pcl).

There is also support for PostScript only printers (model=ps), Tektronics Phasers (model=phaser), QMS (model=qmsXXX) and others. The best way to determine the printers currently supported is to examine the ifhp.conf file. The following is a sample of the various entries in the configuration file.

If your printer is not in this this list then you can use the following guidelines. If you have a PostScript only printer you should use the ps model. If you have a PCL only printer, then pcl is recommended. If you want to process PostScript files on your PCL only printer then install GhostScript and use pcl_ps entry and select the GhostScript driver suitable for your printer.

The other model entries are used when specific printer functionality or features are needed. For example, if you want to do accounting or use landscape mode, then you should check for your specific printer model in the configuration file.

3.1. Input Tray Selection

If a printer supports an input tray selection mechanism, then the following options are recommended for use. Local conditions or printer type may require addition options.

3.2. Output Bin Selection

If a printer has an output bin selection mechanism or some other finishing mechanism, then the following are recommended for use.

3.3. Media Size (Paper) Selection

The paper size selection facilities usually are quite printer dependent, and the input tray selection and paper size selection mechanisms may interact in strange and mysterious ways.

3.4. Media Type Selection

Media Type is not the same as paper size, and corresponds to the name assigned to a particular media. Of course, the issue is complicated by the fact that some media have standard sizes as well. Again, the input tray selection, media size, and media type selection will interact in confusing and mysterious ways, depending on the whim of the printer firmware implementors.

You will also notice that there is no general mediatype=name selection mechanism. This is due to the extremely different way that the media names must be passed for PostScript, PJL, and PCL.

3.5. Duplex and Simplex

Duplex printing is when impressions are placed on both sides of a sheet of media. Due to a general lack of conventions, the orientation of each of the impressions varies from vendor to vendor, and has changed over the years.

3.6. Copies

This option has been provided to effectively allow the printer to make multiple copies of a single page or job. This option tends to be misimplemented on almost all known printers, and it is strongly recommended that users do not use it. However, for completeness, compatibility, and implementor consideration, this is included, even against the better judgement of the implementors of the ifhp software.

4.1. Printer Configurations

A printer consists of a hardware print engine which marks the output page and delivers it, a set of control hardware that takes a print job in a well defined format and operates the hardware to produce output according to information in the print job, and a communication channel from the computer to the control hardware. The control hardware is sometimes called a print engine. In most modern computers the control hardware may consist of multiple microprocessors, each with their own firmware, and each performing a specific printing task. For example, one may control the paper feed path, one may do rasterization, and one may handle communications with the outside world.

In order to set up printing correctly, it is necessary to know the following information about your printer.

1. The capabilities of the hardware. This is dependent on the model of printer, and may be such things as the page feed, output and input tray selection, numbers of columns and/or rows of output available on the output device. This information is readily available from most manufacturers.

2. The print job language recognized by the control hardware. This is the special set of codes, commands, and formats recognized by the control hardware.

3. The protocol used to send jobs to the printer and obtain status about the printing activity.

Usually the capabilities of a modern printer are very well known and documented, and the ifhp filter and most print spooling software has little difficulty working with them.

The following checklist will help you in setting up your printer. The various options that you will need to know about are indicated where appropriate.

1. Printer Model (model=???) What is the exact printer model? Check the serial number or other identification to get this information. You should check the ifhp.conf configuration file to see if your printer is already supported.

2. Print Languages Supported By Your Printer

   1. PJL? (pjl or pjl@) The Printer Job Language (PJL) is a high level language supported by many Hewlett-Packard printers that allows some print system configuration to be performed. Due to historical developments, not all printers support all PJL language facilities, and some support them in different ways than other printers. The ifhp filter can use the PJL support for a printer if it is available.

   2. PostScript (and what version)? (ps or ps@) PostScript is the most common print job language in use. If your printer supports PostScript, then you will have a relatively trouble free time with it. One problem is that it requires a fairly substantial amount of memory and computational support, and is usually not found on the low end (less than $500) printers.

   3. PCL? (pcl or pcl@) PCL is another Print Language supported by many vendors, including Hewlett-Packard, Lexmark, and others. It is essentially text with escape sequences to tell the print engine to place markings on a page at specific places in a specific font. It is the second most common format used with modern printers.

   4. Text? (text or text@) Text is really just PCL without any control sequences. However, it is easy to have ifhp convert ordinary text into PCL by prefixing the appropriate PCL control codes. You may also need to use the crlf option to force CR to CR-LF translation. If you have a simple text printer then you may want to use the much easier to configure lpf filter from the LPRng distribution (http://www.lprng.com).

   5. Vendor Specific There is a growing trend to have very proprietary Print Languages for very low end (less than $300) printers. These printers usually require all of their jobs to be preformated by software running on the host and to have the job delivered to them in a specific manner. If you have one of these printers, you will need to get a rasterizing program that produces the correct format. Check to see if GhostScript, supports your printer. If it does then you can use GhostScript to translate PostScript to your printer's required format.

   
   
   

3. Memory Size. If you are going to be sending large print jobs or ones with a large amount of graphics to the printer, you will need a substantial amount of memory to deal with rasterization. Most high resolution Laser Copier based printers require a minimum of 16 megabytes for adequate performance, and if you are printing complex PostScript or PDF documents you may want at least 32 megabytes. Color printers require substantially more and 64 megabytes is not uncommon.

4. Communications. The connection between your printer and the host computer.

   1. Network Connection This is the most reliable and high speed way to connect a printer to a system. This is especially true if a printer must be accessible to multiple users and is located at a distance from the user.

   2. Parallel Port (status@) The parallel port is a unidirectional communications channel and does not do full duplex bidirectional communications. Some operating system support bidirectional communications, but they do so by requiring write operations to alternate with read operations.

   3. Serial Ports This is the very worst way to communicate at high speed with a printer. Serial ports usually have a high error rate, suffer from data overruns, and have a severe impact on system performance. You will need to configure your printer speed, format (bits per character, parity, stop bit), and flow control method, and then do the same for the host. This can be an endless source of frustration for the novice user.

   4. Print Server Box Many older printers do not directly support a network connection and have an external print server box attached to either their serial or parallel ports. If you have the printer connected to a parallel port, then you will still most likely only have unidirectional communication and no status information will be available from the printer.

   
   
   

4.2. Network Communication Protocols

The most high speed and reliable connection to your printer is using a network connection. The following protocols are usually used to communicate with a network printer: RFC1179 (TCP/IP printing), Socket Protocol (TCP/IP), AppSocket Protocol (TCP/IP), Novell Print Protocol (IPX), SMB Print Protocol (TCP/IP), and AppleTalk Print Protocol (TCP/IP).

It is highly recommended that you use TCP/IP networking to communications to talk to your printer, and that you do not enable any other protocol on your printer. If you have two different systems trying to connect to the same printer using different protocols, a wide range of vendor's hardware will lock up and may require a power up reset to recover. Documented evidence for this behavior includes a wide range of printers, including those from Hewlett-Packard, LexMark, IBM and other vendors.

Only the TCP/IP based network job transfer protocols are discussed in this document. For details on using other protocols, please consult the consult the LPRng documentation.

4.3. RFC1179 (BSD or TCP/IP) Job Transfer Printcap Entry

RFC1179 is used to transfer print jobs between a client (user) and a print spooler, or between two print spoolers. Jobs are transferred as a set of files, and the only information exchanged during the transfer process is the success or failure of the transfer. In order to get status about the actual job printing, a separate query status (lpq) is sent to the print spooler.

Many, if not all, printers with a network interface that supports the TCP/IP protocol support the RFC1179 protocol for job transfer. However, their support for print job status is usually minimal to non-existent. If you want to send a job to a printer using the RFC1179 protocol, please be aware of the following problems.

Normally a print spooler (System 5 lp, BSD lpd, LPRng) does not modify a print job when forwarding it to another print spooler. This means that your print job will normally pass from the originating lp or lpr program to the destination printer with no changes. This can have disastrous results if the job requires filter processing.

If you are using the LPRng print spooler, job transfers using RFC1179 is specified by using :lp=spoolqueue@host or :rp=spoolqueue:rm=host printcap entries. For example:

    raw:
      :lp=raw@host
      :sh:sf:mx=0
      :sd=/var/spool/lp
    cooked:
      :rp=cooked:rm=host
      :sh:sf:mx=0
      :sd=/var/spool/lp
      :filter=/usr/local/libexec/filters/ifhp

The raw queue does not have a filter and jobs sent to the raw are transfered intact from the raw queue to the destination raw printer on the host server.

Jobs sent to the cooked queue will be processed by the program specified by the filter option. For each data file in the job, the lpd print spooler will open a temporary file to hold the filter output, and then run the filter program with its STDIN set to the job's data file file and the STDOUT set to the temporary file. The filter STDERR will be recorded in an error log.

When a job is created a job format may specified (default is f), and an filter can be specified to process job files with this format. The :i<format> option specifies the filter program for use. For example, you can specify a different filter for the n format as shown below. The translate_format option specifies the resulting format for the processed files, and uses a format similar to the UNIX try(1) program. In the example, it specifies that the output of the filter for the n format be renamed as f.

    cooked:
      :rp=cooked:rm=host
      :sh:sf:mx=0
      :sd=/var/spool/lp
      # default filter
      :filter=/usr/local/libexec/filters/ifhp
      # n filter
      :nf=/usr/local/libexec/filters/nfilter
      :translate_format=nf

There is a final option that is used when rather than having a set of job files forwarded to a printer, a single job file is desireable. This is usually the case when sending a job to a host or printer that has a defective RFC1179 spooler implementation, and drops or misprints jobs with multiple files in them. The lpd_bounce option causes the output of all the filters to be put into a single file, and the output is then forwarded to the destination. You can also use the bq_format option to specify the format of the job:

    cooked:
      :rp=cooked:rm=host
      :sh:sf:mx=0
      :sd=/var/spool/lp
      # default filter
      :filter=/usr/local/libexec/filters/ifhp
      :lpd_bounce
      # output has l (literal) or binary output
      :bq_format=l

The lpr -l or lpr -b flag is used to specify the special literal or l job format. Job that have the l format usually have only the most perfunctory processing done by the filter.

4.4. Socket Protocol (TCP/IP) Operation Printcap Entry

Many printers with a network interface provide a TCP/IP port that is a direct connection to the internal print engine. If a TCP/IP connection is made to this port and a file is sent over this connection, then the print engine will process the file. More importantly, the connection is bidirectional, and the printer will report errors and status conditions over the connection. PJL and PostScript status request commands can be sent to the printer and the printer will respond with information.

The ifhp filter makes extensive use of this protocol, and provides support for status and error reporting. In cooperation with the LPRng print spooler, it will provide a detailed description of the actual print job progress and any error conditions that arise.

To use a Socket connection with LPRng, you use the :lp=host%port printcap entry shown below. The lpd print spooler will open a connection to the TCP/IP port on host and passes the (bidirectional) connection to the ifhp filter on file descriptor 1 (STDOUT) and the file to be printed on file descriptor 0 (STDIN). Errors and status information are reported by the ifhp filter on file descriptor 2 (STDOUT) and placed in the error status log by the lpd print spooler.

The connection made by the lpd server to the printer is persistent over the entire job; all file transfers for the same job are made over the same connection. This is important as it prevents other printer users from hijacking the printer in the middle of print a job and getting your job outputs mixed together.

The following is a typical printcap entry using the socket protocol.

    raw:
      :lp=host%9100
      :sh:sf:mx=0
      :sd=/var/spool/lp
      :filter=/usr/local/libexec/filters/ifhp

4.5. Appsocket Protocol (TCP/IP) Operation

The Tektronics Phaser Series printers and QMS printers use the Appsocket protocol when sending a job to the printer. This protocol uses two ports: a TCP/IP listening port which accepts TCP/IP connections and a UDP SNMP query port that is used to obtain status information.

The Appsocket protocol is (briefly):

1. The Simple Network Management Protocol (SNMP) is a UDP protocol. A SNMP Query packet containing a request for information is sent to the printers SNMP Agent port (port 161), and a reply containing the requested information is returned.

2. To send a job to the printer, a TCP/IP connection is opened to the TCP/IP port and job data is sent. Only a single job can be sent at a time - a EOJ in the job, i.e.- CTRL-D for PostScript or ESC E for PCL will cause the printer to terminate reading from the TCP/IP port, and after job processing has finished, to close the TCP/IP connection. All input after the EOJ may be ignored by the printer and not processed.

3. While processing the job, if bidirectional support is available and has been enabled the printer will return job status or information until all of the print job which is has received has been processed. This support is usually not enabled by default and must be enabled by using a specialized administration interface or configuration tool.

4. Unfortunately, some printers will also close the connection when the EOJ has been received. These printers are virtually useless when trying to get error or status information about a job.

5. Even more annoying is the behavior of some printers that insist on the network connection remaining open until the job has been processed. The device sending the job to the printer must do a shutdown on the sending direction of the network connection, and then read status information from the receiving direction until the printer terminates the connection. Unfortunately, some printers do not terminate the connection, and the the user must close the connection after a suitable timeout.

6. There are also printers that insist on the network connection being closed before they will start processing small jobs. The device sending the job to the printer must do a close rather than a shutdown.

7. While processing the job, the printer will ignore any connection requests, and only until the job has been processed will the printer accept connections.

8. During job processing, status and error indications can be obtained by sending a query to the UDP port. However, the error conditions and other information are not very precise as the status may change dramatically during job processing.

9. a query to the UDP port. However, the error conditions and other information are not very precise as the status may change dramatically during job processing.

The Appsocket protocol does not use a persistent connection. If two people are sending jobs to the printer simultaneously it is very likely that the jobs will get intermixed.

The appsocket option causes the ifhp filter to open and close a TCP/IP connection to the printer. In order to reopen the device, ifhp needs the device name. It gets this from the PRINTCAP_ENTRY environment variable which has the device information, or by using the TCP/IP address of the initial end of the connection.

The close_appsocket option causes the ifhp filter to close the connection after sending a job or part of a job. This is necessary with printers that will not start printing small jobs until a sufficient number of pages has been received.

The following is a sample printcap entry for this printer:

    # Phaser Setup
    #  Appsocket
    lp:server  
      :lp=10.0.0.1%9100  
      :sd=spooldir  
      :...  
      :ifhp=model=ps,appsocket
      #path to ifhp filter  
      :filter=/.../ifhp

For your convenience, the model=phaser entry is suitable for use with the appsocket protocol.

4.6. Using SNMP For Status Information

• snmp_monitor FLAG use snmp for status

• snmp_program= path to snmp_printer_status

• snmp_program_cfg= snmp_printer_status configuration file

• snmp_model=snmp model information

• snmp_sync_status=sync indicators

• snmp_end_status=end of job indicators

• snmp_end_status=end of job indicators

The ifhp filter can be configured to use the SNMP helper program snmp_printer_status to obtain SNMP status. This program is supplied as part of the ifhp distribution.

The snmp_monitor flag is used to enable the use of the snmp_printer_status program. The snmp_program specifies the program path and command line to invoke it. The snmp_program_conf specifies the path to the configuration file, snmp_printer_stastus.conf. The configuration file contains information about the operation of the program as well as the SNMP Object Identifiers (OIDs) for the status information.

Since different printers may not support all of the standard Printer MIB Oids, the snmp_printer_status.conf can identify the options on a per-printer model basis, and the appropriate ones can be selected using the snmp_model option.

The snmp_printer_status program returns status information on it STDOUT and errors on its STDERR. The status information has the format:

    PRINTERNAME=HP LaserJet 2200
    DEVICEID=HP LaserJet
    STATUS=Ready
    DEVICESTATUS=running
    PRINTERSTATUS=idle
    PAGECOUNT=30

When using snmp to detect idle or end conditions, the snmp_sync_status and the snmp_end_status values are used. If the retured status matches a field in the snmp_sync_status list, then a idle printer condtion is assumed. If the retured status matches a field in the snmp_end_status list, then an end of job condtion is assumed. For example:

    snmp_end_status=ready idle
    snmp_sync_status=ready power_save_mode

When using SNMP to obtain status, it may be of little benefit to use other methods to obtain sync, pagecount, or end of job (waitend). Also, if a connection is open to the printer then the printer may never indicate idle or non-printing status. This problem can be avoided by using the appsocket protocol. If you use this, then you should also set the sync, waitend, and pagecount values to snmp as well. For example:

    [ printer ]
    snmp_monitor
    appsocket
    sync=snmp
    waitend=snmp
    pagecount=snmp

4.7. Common Print Server Boxes Configuration Information

The following is a list of print server manufacturers, models, and with hints on how to access these boxes with various protocols.

All company, brand, and product names are properties of their respective owners.

4.8. Timeout Problems Sending A Job

The ifhp filter may need to run a program such as ghostscript to do format conversion. For large files this can take quite a bit of time and most network printers have a connection timeout. If no data is received for this time the printer will close the connection. By default this timeout is fairly short: 30 or 90 seconds on most printers.

If you are sending large jobs to the printer using the socket protocol and are getting timeout problems due to conversion timeouts, then there are two solutions: a) use the Appsocket protocol, which will open and close the connection for each file, and only send data when the converted file is available, or b) do your conversions first and then spool the converted job to be sent directly to the printer. The second method requires an LPRng bounce queue.

    # Method a) Appsocket
    lp:server 
      :lp=10.0.0.1%9100
      :sd=spooldir 
      :... 
      :ifhp=model=printer,appsocket
      #path to ifhp filter 
      :filter=/.../ifhp 
    
    # Method b) Bounce Queue
    #  this queue does the conversion if required
    lp:server
      :lpd_bounce 
      :lp=real@localhost
      :sd=spooldir 
      :... 
      :ifhp=model=printer
      #path to ifhp filter 
      :filter=/.../ifhp 
    # this queue does transmission
    real:server 
      :lp=10.0.0.1%9100
      :sd=spooldir 
      :ifhp=model=printer
      #path to ifhp filter 
      :filter=/.../ifhp 

For method a), the Appsocket protocol is used and the ifhp filter will be invoked before sending a job. For method b), you use two queues: a bounce queue that does the format conversion and then sends the job to the real queue, and the real queue that actually talks to the printer.

4.9. Printers With Lockup Problems

Due to firmware problems in some PostScript and PCL printers, they will occasionally lock up and refuse to accept new connections or continue with job processing. This is extremely difficult to diagnose, as the printer appears to be functional but will simply not accept an