Provided by: lprng_3.8.B-2.2_amd64 bug

NAME

       lpd - line printer daemon

SYNOPSIS

       lpd [-L logfile] [-F] [-V] [-D debugopt] [-p port]

DESCRIPTION

       The  lpd program is the printer server program of the LPRng software suite.  This software is an enhanced
       and modified version of the Berkeley LPD software.

OPTIONS

       -L logfile
              specifies an alternate file to be used for logging error and debugging  messages.   The  syslog(8)
              facility  is  used to log critical messages as well.  Please note that you need to create the file
              by yourself, a 'touch' is sufficient.  This is needed for security reasons.

       -F     Under normal operation, the LPD server will run in background mode.  The -F flag forces it to  run
              in foreground mode, where it is more easily debugged.

       -V     Print program version information.

       -D debugopt
              Debugging  is  controlled  using  the  -D option. This accepts a comma-separated list of debugging
              settings. These settings take one of two forms: facility=value  ,  or  value  to  set  an  overall
              default value.  The available facilities can be determined by invoking LPD with the -D= parameter.

       -p port
              Bind to the specified port rather than port 515 specified by RFC1179.

OPERATION

       Lpd  is the line printer daemon (spool queue handler) and is normally invoked at boot time from the rc(8)
       file; it can also be started by a user.  Note that the lpd server needs only run on systems where  actual
       printing  or  spooling  is  taking place.  lpr(1) and other related programs transfer files using network
       facilities to the lpd.

       When started, lpd reads a configuration file to obtain basic operational parameters and  then  reads  the
       printcap(5)  database  information  to  determine the which printers have spool queues and to start spool
       queue server processes.  If running as a background server, it will disconnect from its control  terminal
       and run in the background.  It uses the system calls listen(2) and accept(2) to receive requests to print
       files in the queue, transfer files to the spooling area, display the queue, remove jobs from  the  queue,
       or  perform  a  spool  queue  control  function.  In each case it creates one or more server processes to
       handle the request and the lpd process will listen for more requests.

       Sending the  server  a  SIGHUP  signal  causes  the  server  to  reread  the  various  configuration  and
       inititialization  files.  This action is similar to that of the INETD and other servers.  The same action
       is taken when sent a reread command by the lpc(1) program.  At an interval  specified  by  the  poll_time
       configuration  variable,  lpd  will  check for spool queues with jobs and no printing activity, and start
       printing.

       LPD access control is done using a rule set and match algorithm similar to a packet filter.  Each request
       for  printing,  status,  or  control  operations is matched against the rule set, and the first ACCEPT or
       REJECT value determines if the operation can be performed.  The following is a typical permissions file:
              # Set default permissions
              DEFAULT ACCEPT
              # Reject any connections from outside our subnet
              REJECT SERVICE=X NOT IP=130.191.0.0/255.255.0.0
              # Only accept Printing (P) and spooling (LPR) from
              # the private network, the 10.0.0.0/8  network and fw
              REJECT SERVICE=P,R NOT REMOTEHOST=*.private,10.0.0.0/8,fw.astart.com
              # Do not accept forwarded jobs for printing
              REJECT SERVICE=P FORWARD
              # Allow only the administrators control access
              ACCEPT SERVICE=C,M REMOTEHOST=spooler.astart.com USER=root,papowell
              ACCEPT SERVICE=C,M SERVER REMOTEUSER=root,papowell
              # Allow only the user on the same host who spooled job to remove it
              ACCEPT SERVICE=M SAMEUSER SAMEHOST
              REJECT SERVICE=M,C

       Permission checking is done by using a set of keys (or  fields)  with  associated  values  to  check  for
       permission.   The  SERVICE  key  has  value  P for printing (i.e.- unspooling), R for spooling (i.e.- LPR
       request), C and S for printer control and status respectively (i.e.- LPC request), M for  removal  (i.e.-
       LPRM  request),  Q  for  queue  information  (i.e.- LPRM request), and so forth.  The X key indicates the
       initial connection to the LPD spooler, and can be used to control connections from remote  systems.   The
       values  of the USER, HOST, and IP keys taken from the control file which is being received or checked for
       permissions.  The REMOTEUSER, REMOTEHOST and REMOTEIP keys are those either sent as part of a command, or
       derived  from  information  about  the  current network connection.  Each line of the permissions file is
       scanned for key names and values, and these are matched against the request keys information.   When  all
       matches  on  a  line  are  made, then search terminates with the specified action (ACCEPT/REJECT).  If no
       match is found the default permission value is used.  The DEFAULT key is  used  to  specify  the  current
       default  permission  to  be used for successful matches or if there is no match after scanning the entire
       permissions database.

       The GROUP entry is used to check that the USER name appears in a group entry in  the  system  user  group
       database.   For  example,  GROUP=student*,staff*  would  check  to  see if any of the group name matching
       student* or staff* have the specified user name in them.  If a system has  the  netgroups  capability,  a
       group  name starting with a @ will be treated as a netgroup name, and current user name from the job file
       will be checked to see if it is in the group.  Similarly, the REMOTEGROUP entry will check a remote  user
       name.   The  PORT entry can be used to ensure that a connection to the server originates from a specified
       range of ports.  For more details, see the lpd.perm(5) man page.

       The permissions database is scanned in order of the fixed file entries and then by invoking the specified
       filters  for  each  of the permissions lists.  It is recommended that the filters be placed at the end of
       the permissions lists.  The user name is one of the parameters passed to the filter, and can be  used  to
       determine if a user has permissions to print a file.

       Key          Match Connect Job   Job    LPQ  LPRM  LPC
                                  Spool Print
       SERVICE      S     'X'     'R'   'P'    'Q'  'M'   'C,S'
       USER         S     -       JUSR  JUSR   JUSR JUSR  JUSR
       HOST         S     RH      JH    JH     JH   JH    JH
       GROUP        S     -       JUSR  JUSR   JUSR JUSR  JUSR
       IP           IP    RIP     JIP   JIP    RIP  JIP   JIP
       PORT         N     PORT    PORT  -      PORT PORT  PORT
       REMOTEUSER   S     -       JUSR  JUSR   JUSR CUSR  CUSR
       REMOTEHOST   S     RH      RH    JH     RH   RH    RH
       REMOTEGROUP  S     -       JUSR  JUSR   JUSR CUSR  CUSR
       REMOTEIP     IP    RIP     RIP   JIP    RIP  RIP   RIP
       CONTROLLINE  S     -       CL    CL     CL   CL    CL
       PRINTER      S     -       PR    PR     PR   PR    PR
       FORWARD      V     -       SA    -      -    SA    SA SA
       SAMEHOST     V     -       SA    -      SA   SA    SA
       SAMEUSER     V     -       -     -      SU   SU    SU
       SERVER       V     -       SV    -      SV   SV    SV
       AUTH         V     -       AU    -      AU   AU    AU
       AUTHTYPE     S     -       AU    -      AU   AU    AU
       AUTHUSER     S     -       AU    -      AU   AU    AU
       FWDUSER      S     -       AU    -      AU   AU    AU

       KEY:
          JH = HOST          host in control file
          RH = REMOTEHOST    connecting host name
          JUSR = USER        user in control file
          CUSR = REMOTEUSER  user from control request
          JIP= IP            IP address of host in control file
          RIP= REMOTEIP      IP address of requesting host
          PORT=              connecting host origination port
          CONTROLLINE=       pattern match of control line in control file
          FW= IP of source of request = IP of host in control file
          SA= IP of source of request = IP of host in control file
          SU= user from request = user in control file
          SA= IP of source of request = IP of server host
          SV= matches if remote host is the server
          AU= authentication information
          IFIP= IP address of remote end of connection

       Match: S = string with wild card, IP = IP address[/netmask],
          N = low[-high] number range, V = exact value match
       SERVICE: 'X' - Connection request; 'R' - lpr request from remote host;
           'P' - print job in queue; 'Q' - lpq request, 'M' - lprm request;
           'C' - lpc spool control request; 'S' - lpc spool status request
       NOTE: when printing (P action), the remote and job check values
          (i.e. - RUSR, JUSR) are identical.

       The special key letter=patterns searches the control file line starting with the (upper case) letter, and
       is usually used with printing and spooling checks.  For example,  C=A*,B*  would  check  that  the  class
       information (i.e.- line in the control file starting with C) had a value starting with A or B.

PERMISSIONS, MULTIHOMED HOSTS, IPV6

       There  is a subtle problem with names and IP addresses which are obtained for 'multi-homed hosts', i.e. -
       those with multiple Ethernet interfaces,  and for IPV6 (IP Version 6),  in which a host can have multiple
       addresses,   and  for the normal host which can have both a short name and a fully qualified domain name.
       In addition, a host can have multiple IP addresses, depending on the complexity of its configuration.

       The IFIP (interface IP) field can be used to check the IP address of the origination of the request,   as
       reported by the information returned by the accept() system call.  Note that this information may be IPV4
       or IPV6 information,  depending  on  the  origination  of  the  system.   This  information  is  used  by
       gethostbyaddr()  to  obtain  the  originating  host  fully  qualified  domain  name  (FQDN) and set of IP
       addresses.  Note that this FQDN will be for the originating interface,  and may not be the canonical host
       name.  Some systems which use the Domain Name Server (DNS) system may add the canonical system name as an
       alias.

       When performing an IP address match,  the entire list of IP addresses for a system will now  be  checked.
       If one of these matches, then success is reported.  Similarly,  the entire list of host names and aliases
       will be checked.  If one of these matches,  then success will be reported.

       In addition,  when checking for printing, if the name lookup for the host reported in  the  control  file
       fails,  then we assume that the host is unknown and all match checks for names or IP addresses will fail.
       You can determine if a host has an entry by using the following check, which  will  reject  all  requests
       from a remotehost which does not have a DNS entry.
         REJECT NOT REMOTEHOST=*

PRINTCAP DATABASE

       Individual  printer  operations  are  controlled by values in the printcap database.  See printcap(5) for
       details of the format and content of the various entries.  The following are typical printer entries  for
       a local and remote printer.

              # main or shared printcap file - usually /etc/printcap
              # remote postscript printer
              fullpage
                 |postscript
                 :lp=postscript@farside.astart.com
              # give access to (remote) hosts
              t1|postscript2
                 :cm=Test Printer 1
                 :lp=postscript2@nearside.astart.com

              # local printcap file
              # specification for local printer on nearside
              t1|postscript2
                 :oh=nearside.astart.com
                 :cd=/usr/spool/LPD/safe
                 :sd=/usr/spool/LPD/t1
              #
              # /usr/spool/LPD/t1/printcap file -
              t1:
                 :lp=/dev/pr
                 :if=/usr/lib/pr/if
                 :of=/usr/lib/pr/if

       Printcap  information  can  be distributed by individual files or shared using NSF, YP, or other methods;
       see lpd.conf(5) for the exact details of the location of  printcap  files  and  programs,  given  by  the
       printcap_path  and  lpd_printcap_path  configuration information.  The usual printcap configuration is to
       have a main (shared) printcap database which is used by all hosts.  The printcap information  is  usually
       extremely simple, consisting only of the printer name and host (i.e. - fullpage printer entry).

       On  hosts which have printers attached or which are to provide spooling queue directories, more extensive
       printcap information is needed.  In the shared database, oh  (options  for  specified  host  only)  field
       restricts  use  of  this  entry to the specified host.  This entry can contain host specific information,
       such as the location of the spool queue and/or actual device to be used for output.

       In the above example, the main printcap file, /etc/printcap has entries  for  all  printers.   Note  that
       these  entries do not specify the spool directories (sd and cd fields), but this could be provided.  On a
       host with a printer specific information can be provided in several ways.  The simplest is to simply  put
       an  additional  entry  in  the  shared printcap file, with the oh field set to the support host name.  An
       alternative would be to specify the spool directories (sd and cd fields) in the shared  information,  and
       to put the printer specific information in a printcap file.

       In addition to the oh flag, the server flag indicates that this entry is for a the LPD server only.  This
       can be used to simplify the management of client and server entries.

       The printcap information is obtained in the following  order.   If  the  lpd_printcap_path  configuration
       value  is  nonblank  then  the  lpd  server  will  process  only  this  information otherwise it uses the
       printcap_path information.  All client programs use  the  contents  of  the  configuration  printcap_path
       variable  to  get  a  list  of  locations of printcap files.  Each of these entries in the path lists are
       processed, and the printcap information is extracted.  Entries which have oh fields are only used by  the
       specified  host.   The  files  and  information  is  processed  in linear order, later entries overriding
       preceeding ones.

       When processing jobs or performing spool queue specific requests, the LPD server will  check  to  see  if
       there is a printcap file in the control directory for the spool queue and the contents will be processed.
       Since only the LPD server has access to the spool and control queues, this information is processed  only
       by the server.

       In  addition  to  files, printcap information can be obtained from programs or filters.  For example, the
       printcap_path of the form /etc/printcap:|/usr/lib/getpr will use the contents of the /etc/printcap  file,
       and  then  use  the /usr/lib/getpr program to get information about a specific printer.  When information
       about a particular spool queue is needed and one or more filters are specified as the source of  printcap
       information,  then  the  filter  will be started and the printer name written on its standard input.  The
       filter must provide a printcap entry for the requested printer on its standard output.

       The filter can be used to interface to databases or nonstandard information sources which do not  produce
       printcap information in an acceptable form.

SPOOL DIRECTORY CONTENTS

       Each  spool  queue  has a spool directory (sd) and optional control directory (cd)  where job and control
       information is kept.  Under normal operation the spool and control directories are identical, but if  the
       spool  directory  is  NFS  exported for use by other printer spoolers which write files directly into the
       spool queue, then it is recommended that the control directory  be  a  separate  directory  and  not  NFS
       mounted.   The  following  files  are  used  for  printer operations.  Per job entries are marked with an
       asterisk (*).

       File Name           Dir     Purpose
       printer             CD      lock file and server process PID
       unspooler.printer   CD      subserver process PID
       control.printer     CD      queue control information
       *hfAnnn             SD      job hold file
       *cfAnnnHOST         SD      job control file
       *dfAnnnHOST         SD      job data file
       *bfAnnn.*           SD      temporary files

       The nnn in the file names stands for the job number.  RFC1179 requires this to be a 3 digit  number,  but
       the longnumber printcap flag or a nonzero longnumber configuration variable will enable 6 digit numbers.

       The  lock  file is used to prevent multiple job queue servers from becoming active simultaneously, and to
       store the server process id.  The lock file name is the name as the printer name; all other control files
       have the printer name appended as indicated above.

       The  printer  spool control file contains information controlling the queue operations.  It consists of a
       series of lines with keywords and values  to  control  printing,  spooling,  and  automatic  job  holding
       operations.  The following is an example of a typical spool control file.

              spooling_disabled 0
              printing_disabled 1
              holdall 0
              redirect p1@host2
              debug 10,log=/tmp/log
              class A

       The  spooling_disabled  and  printing_disabled  entries  control  spooling  and printing; the lpc enable,
       disable, start, and stop command alter these values.  The holdall entry  will  prevent  jobs  from  being
       processed  until  released  with  the lpc hold or release comands; the lpc holdall and noholdall commands
       alter these values.

       The redirect entry causes the lpd server to forward  jobs  to  the  specified  remote  printer;  the  lpc
       redirect  command  alters  this  field.   The  class  field controls the class of jobs being printed.  By
       default, the class value is a pattern that matches the class entry in a job file; however a entry of  the
       form  letter=patterns  will  print  jobs  whose control file line starting with letter matches one of the
       patterns.  The debug line provides a set of debugging  parameters  for  diagnostic  information  for  the
       particular spool queue.

       Each  print  job  consists  of a control file and one or more data files.  Lines in the control file file
       specify the job data files or parameters for the job and the general format of the file is  specified  by
       RFC1179.  Each line consists of a flag character and a parameter; upper case and digit characters specify
       options and lower case letters specify the printing format and names of data files.  The following  is  a
       list of the control file flag characters.

       A      Identifier  A  job  identifier  to  be  used  when  displaying job information and/or status.  The
              insertion of this line is controlled by the use_identifier printcap/configuration variable.

       C      Class String to be used for the class line on the burst page.

       H      Host Name.  Name of the machine where lpr was invoked.

       I      Indent.  The number of characters to indent the output by (in ascii).

       J      Job Name.  String to be used for the job name on the burst page.

       L      Banner user name.  Information for banner page.

       P      Person.  Login name of the person who invoked lpr.  This is used to verify ownership by lprm.

       M      Send mail to the specified user when the current print job completes.

       N      File name.  The original name of a data file which is in the job.

       T      Title.  String to be used as the title for pr(1) when the LPR -p option was specified.

       U      Unlink.  Job file to remove when printing completed.

       W      Width. The page width (in characters) to used for printing.

       Z      zoptions. Options passed by lpr -Zzoptions.   These  are  passed  to  output  filters  to  aid  in
              printing.

       f      Formatted File.  Name of a file to print which is already formatted.

       l      Like ``f'' but passes control characters and does not make page breaks.

       p      Name of a file to print using pr(1) as a filter.

       t      Troff File.  The file contains troff(1) output (cat phototypesetter commands).

       d      DVI File.  The file contains Tex(l) output (DVI format from Stanford).

       g      Graph File.  The file contains data produced by plot(3X).

       c      Cifplot File. The file contains data produced by cifplot.

       v      The file contains a raster image.

       r      The file contains text data with FORTRAN carriage control characters.

       1      Troff Font R. Name of the font file to use instead of the default.  (Obsolete)

       2      Troff Font I. Name of the font file to use instead of the default.  (Obsolete)

       3      Troff Font B. Name of the font file to use instead of the default.  (Obsolete)

       4      Troff Font S. Name of the font file to use instead of the default.  (Obsolete)

       Each  job  in the spool queue can have an associated job hold file which is used by the server process to
       control the printing of the job.  The status file contains information controlling the  job  hold  status
       and  error  status.   The  spool  server  will  attempt  to  print a job a limited number of times before
       abandoning it or setting an error status in the job status file.  The following is  a  typical  job  hold
       file.
              hold        0 priority    0 active      2135 redirect remove      0 error

       A  nonzero hold entry will prevent the job from being processed; the lpc hold and release commands update
       this field.  The priority field overrides the normal first-in first-out printing priority; jobs with non-
       zero priority fields are printed first.  The lpc topq command updates this field.  If the active field is
       non-zero, the job is being printed by the server with the  specified  process  id.   The  redirect  field
       allows  individual  jobs to be forwarded to a different printer; the lpc move command updates this field.
       Finally, the remove and error fields are used to control printing of problem jobs.  The remove  field  is
       set when a job should be removed; the error field records information that would prevent a job from being
       printed.

JOB SUBMISSION

       The LPR program is used to submit a job to the LPRng system.  The LPR program opens a connection  to  the
       LPD  server  and  then transfer the job control file and data files.  The LPD server checks to see if the
       remote host and user has permissions to spool to the requested printer, and then checks  to  see  if  the
       printer  is  accepting  jobs.   If  both conditions are met, the job is accepted and the control and data
       files are placed in the spool directory.  The LPRng software sends the control file  first,  followed  by
       the data files.

       If  the  LPR program is acting as a filter, it is not necessary to temporarily store the print job on the
       local machine.  The input data can be sent directly to the LPD server for spooling using an implicit  job
       size  of  0 and sending data until the connection is terminated to the server.  However, some LPD servers
       do not accept 0 size jobs, even though it is specified by the RFC1179, so by default LPR  will  create  a
       temporary file.  The LPR -k (seKure) option specifies this direct transmission mode be used.

JOB TRANSMISSION

       When  LPR  is to send a job to the server, it must determine the location of the server.  It does this by
       examining the values of the specified printer and host.

       If the printer and host are explicitly specified in the form pr@host then the LPR program will  send  the
       job  to the specified spool queue pr and to the server running on host.  This can be explicitly specified
       by the PRINTER environment variable or by the LPR -P option.

       If the printer is specified only by a name, then the information in the printcap database is  used.   The
       printcap  entry  for  the  printer is searched for and the remote host and printer information extracted.
       The job is sent to the server running on the specified host.

       This action can be modified by the following printcap or configuration tags.

       1. default_host=host
            (Configuration) If there is no printcap entry for the printer, the job is sent  to  the  LPD  server
            running on host.

       2. force_localhost
            (Configuration or printcap) If this flag is specified,  then LPR and other client programs will send
            the job to the server running on the localhost.  This overrides the default_host information.

FORWARDING OPERATIONS

       The LPD system can forward jobs from one spool directory to another.  This is controlled by the following
       options.

       1.   The  forward  field  in  the  spool  control  file has a value rp@rm.  This can be set using the LPC
            forward command.

       2.   The lp (line printer) printcap entry has the form  rp@rm.   There  is  a  rm  (remote  machine)  and
            optional rp (remote printer) printcap entry.

       The first of the above conditions to be met will determine the destination.  If printing is enabled, then
       jobs will be forwarded to the remote destination.  Example:
       # using lp=rp@host
       test:sd=/usr/spool/test
         :lp=test@host
       test:sd=/usr/spool/test
         :lp=test@host%port
       # using :rp:rm:
       test:sd=/usr/spool/test
         :rp=test:rm=host

       3.   The LPD server uses the same algorithm for sending jobs as the LPR program.  A connection is made to
            the  remote  server  and  the  files are copied to the server.  A set of timeouts is used to control
            error recover and retry operations.   The  printcap  and  configuration  variables  connect_timeout,
            connect_interval,  connect_grace,  and send_try control connecting to the remote host.  A connection
            is attempted to the remote server from a random  port  in  the  range  of  ports  specified  by  the
            originate_port  variable.   If  a  connection  is  not completed within connect_timeout seconds, the
            connection is aborted, and then after the connect_interval seconds it  is  retried.   The  procedure
            repeated   indefinitely   for  printing,  but  only  once  for  status  or  control  operations.   A
            connect_timeout value of 0 indicates no timeout; a value of 0 specifies infinite timeout After a job
            has  been  successfully  printed,  the  connection  is closed and the server waits for connect_grace
            seconds before trying to reconnect.

BOUNCE QUEUES

       Normally job files are forwarded to a printer without modification.  The lpd_bounce flag makes the  queue
       a bounce queue and allows banners to be generated and data files to passed through the appropriate format
       filter.  The entire output of this process is then passed to the destination with the format specified by
       the  bq_format  option  (default  l  or binary).  See PRINTING OPERATIONS for details about filters.  For
       example, the following printcap entry will filter format f files.
       testbq:sd=/usr/spool/testbq:
         :lpd_bounce
         :bq_format=l
         :lp=final@host
         :if=/usr/lib/filter_for_f
         :mf=/usr/lib/filter_for_m
         :pf=/usr/lib/filter_for_pr

CHANGING FORMAT OF DATAFILES

       Sometimes only the indicated format of the data files needs to be changed.  This can be  done  using  the
       translate_format option.  This entry consists of pairs of lower case characters of the form SdSd...; S is
       the original and d is the translated format.
       changeformat:
         :sd=/usr/spool/changeformat:
         :translate_format=mfpf
         :lp=final@host

       In the example above, the m format is processed by a filter, and then its format type is  changed  to  f;
       the  p  format  is  processed  similarly.   Note  that  the  lpr -p option specifies that the job will be
       processed by the /bin/pr command - the filter must do both the pr processing  and  any  necessary  format
       conversions.

LPR FILTER PROCESSING

       The  :lpr_bounce: printcap flag will cause LPR to do bounce queue filtering before sending the job to the
       remote queue.  This can have unexpected effects if the filters are not available on the local host.

       A typical entry which will cause LPR to do filtering is shown below.
       testbq:lpr_bounce
         :lp=printer@host
         :if=/usr/lib/filter_for_f
         :vf=/usr/lib/filter_for_v
         :mf=/usr/lib/filter_for_m
         :translate_format=mfvf

       This entry will force LPR to run jobs with formats f, m, and v
       through the appropriate filter.
       It will also rename the formats to the f format.

ROUTING JOBS TO PRINTERS

       When a job is submitted for printing, sometimes it is  desirable  to  have  it  dynamically  rerouted  to
       another  spool  queue,  or  multiple  copies  send  to  various destination.  This can be done by using a
       routing_filter.

       When a job is accepted by the LPD server, part of  the  processing  includes  passing  it  to  a  program
       specified  by the printcap router entry.  This filter is invoked with the original control file as STDIN,
       and the default set of filter options.  The output of the routing filter will be a set of directives used
       by  LPD when forwarding the job to another printer or in processing the job.  The environment and options
       flags are set as for a standard filter.  (See "FILTERS" for details.)  Here is a sample printcap entry:
       t2|Test Printer 2
           :sd=/var/spool/LPD/t2
           :lf=log
           :lp=t2@printserver
           :bq=t1@localhost
           :destinations=t1@localhost,t2@localhost
           :router=/usr/local/libexec/filters/router

       The routing filter exit status is used as follows:
                           0  (JSUCC) - normal processing
                           37 (JHOLD) - job is held
                           any other value - job is deleted from queue

       The router filter returns one or more routing entries with the following format.  Note that  entry  order
       is not important, but each entry will end with the 'end' tag.  dest <destination queue> copies <number of
       copies to be made> X<controlfile modifications> end

       Example of router output:
       dest t1@localhost
       copies 2
       CA
       end
       dest t2@localhost
       CZ
       end

       The above routing information will have copies of the job sent to
       the t1 and t2 spool queue servers.  If no valid routing information
       is returned by the router filter the job will be sent to the default
       bounce queue destination.

REFORMATING CONTROL FILES

       Sometimes it is desirable to reformat a control file before sending to  a  remote  destination.   If  the
       control_filter  printcap  entry  is  present, then the control file is passed through the filter.  If the
       filter exits with status JSUCC, then the job is process normally; status JABORT causes the job processing
       to be aborted, status JREMOVE causes the job processing to be removed, and any other status is treated as
       JFAIL.

       After passing the control file through the control_filter, the LPD server will reread  it,  and  transfer
       only the data files specified in the new control file to the destination.

SPOOL QUEUE NAME OPTION

       The  qq printcap entry and the use_queuename configuration entry causes the name of the spool queue to be
       placed in the job control file.  This value can be used by the filter to determine how to process a  job.
       When  combined  with  the  use  of  the Bounce Queue, this can be used to reformat jobs before sending to
       another printer spooler system.

PRINTING OPERATIONS

       When printing is enabled, the LPD server will create  a  spool  server  process  to  carry  out  printing
       operations.  For each job in the queue, the spool server process will create a subserver process to carry
       out the actual printing operations.  If the subserver process fails, the  server  process  will  initiate
       recovery  operations.   Job  will be attempted to be printed until all are done or a subserver returns an
       ABORT indication; the server will then terminate operations.

       The server process normally scans the queue once, at initiation; if the spool control file  is  modified,
       usually  by  using the lpc command, the spool queue is rescanned.  The overall algorithm for job printing
       is:
       open the print device;
       send some initialization strings;
       send a banner to the device;
       send the job data files to the device;
       send some termination strings;
       close the print device;

       In order to handle the various device requirements, the subserver process in turn uses 'filter'  programs
       specified in the printcap entry to carry out the individual steps.

       OF Filter
            The 'of' filter is used for initialization, banner printing and the termination strings.  It has the
            peculiar property of suspending itself when sent a special escape string, allowing other filters  to
            be used to print the individual job files.

       Data Filters
            Each  data  file  in  a  job has format specified by a lower case character and an associated filter
            specified in the printcap file.  For example, the 'g' format is printed by the 'gf' filter,  and  so
            forth.   By convention, the 'if' filter is used to print 'f' (ordinary text) and 'l' (binary) format
            jobs.

       lp-pipe Filters
            If the printcap device specification has the form |program then the output device is accessed by the
            specified  program.   This  allows  the  program  to  take  care  of  any required initialization or
            communication requirements.

       The following is a concise summary of the actual algorithm used to print files.  Note that LP stands  for
       the  printer  device  or  filter  specified  by  the 'lp' printcap entry; OF stands for the 'of' printcap
       filter; IF is the default 'if' filter; BP is the banner printing filter; and ?F stands for the filter for
       data file.  The '??' values stand for entries from the printcap file.

       LP = open( 'lp' );  // open device, filter, or network connection
       OF = IF = LP;       // set defaults
       set up accounting according to 'af' entry;
       if( 'of' ) OF = filter( 'of' ) -> LP;// make OF filter
       if 'as' then record start of job accounting information.
       if 'achk' then check for accounting limits.
       if( leader on open 'ld' ) `ld` -> OF// send leader
       if( FF on open 'fo' ) `fo` -> OF    // send leader

       // print a banner
       // first check to see if required
       //   and then to see if not suppressed by printcap
       //   or by user
       do_banner =
           (always banner 'ab'
               || (!suppress banner 'sb' && job has banner ));
       if( ! header last 'hl' && do_banner ){
           if( banner program 'bp' ){
               fork and exec bp to generate banner, but into temp file.
               cat temp file -> OF;
           } else {
               short banner info -> OF;
           }
       }

       // now we suspend the OF filter, use other filters
       if( OF != LP ) suspend OF filter;

       for each data file df in job do
           // send FF between files of job
           if( !first job && ! no FF separator 'sf' ){
               if( OF != LP ) wake up OF filter;
               'ff' -> OF;
               if( OF != LP ) suspend OF filter;
           }

           // get filter for job
           format = jobformat;
           if( jobformat == 'f' or jobformat = 'l' ){
               format = 'f';
           }
           filter = check pc for filter for format;
           ?F = LP; // default - no filter
           if( filter ){
               ?F = filter( filter ) -> LP;
           }

           data file -> ?F;
           // note: if :direct_read: flag set, filter input
           // is directly from the file,  otherwise the
           // file contents are written to the filter input.

           if( ?F != LP ) close( ?F )
       endfor

       // finish printing

       if( OF != LP ) wake up OF filter;
       if( header last 'hl' && do_banner ){
           if( ! no FF separator 'sf' ){
               'ff' -> OF;
           }
           if( banner program 'bp' ){
               fork and exec bp to generate banner, but into temp file.
               cat temp file -> OF;
           } else {
               short banner info -> OF;
           }
       }

       if( ff on close 'fq' ){
           'ff' -> OF;
       }

       if( trailer on close 'tr' ){
           tr -> OF;
       }

       if 'ae' then record end of job accounting information.

       if( OF != LP ) close( OF );
       close( LP );

       When  printing  or transferring a job to a spool queue fails, it is retried the number of times specified
       by the rt (or send_try ) printcap variable.  A 0 value specifies an infinite number or retries.  When the
       retry  count  is  exceeded,  then  the  send_failure_action printcap variable determines the action to be
       taken.  The variable can be the values succ , fail , abort , remove , ignore , or hold , which will cause
       the job to be treated as normally completed, retried, aborted, removed, or ignored and retried at a later
       time respectively.  These names correspond to the JSUCC , JFAIL , etc. error codes returned  by  filters.
       If  the  variable has the form |/filter , then the filter is run and passed the number of attempts on the
       standard input.  The filter must exits with a JSUCC, JFAIL, etc., error code and the server will take the
       appropriate action as listed above.

       The  print  filters  normally  have  their  input  provided  by  a  process  via a pipe.  However, if the
       direct_read printcap flag is set, then the filter input is taken directly from the  job  file.   This  is
       compatible with the vintage BSD method, but loses the ability to track the job progress.

       After  the  job  print  or  transfer  attempt,  if  the  job  is  to be removed and the printcap variable
       save_on_error is true, the job will not be removed from the spool queue but only flagged with  an  error.
       The  job  can  then be retried at a later time.  If the job is successfully printed it is usually removed
       from the spool queue.  However, if the printcap variable save_when_done is true the job  will  merely  be
       marked as completed and not removed from the queue.

FILTERS

       As  described  in the previous section, filters are created to handle output to devices or other filters.
       The command line to invoke a filter is generated in the following manner.

       1.   The printcap entry or configuration value defining the filter command is obtained.

       2.   The file to be printed or the banner line/file generated by the banner printer will  be  written  to
            STDIN  (file descriptor 0) of the filter.  The output device (or /dev/null if this is not a printing
            filter) will be be STDOUT  (file descriptor 1) and STDERR (file descriptor 2) will be  connected  to
            the  error logging file.  If this is a printing filter, the error log will be determined by the :af:
            printcap field and FD 3 will be opened and set to the either the file, remote host, or input of  the
            filter program.

       3.   Filter  specifications  starting  with  ROOT  will be run as root (EUID = 0).  This can be a serious
            security loophole and should only be used as a last resort for specific problems.

       4.   The  options  for  the  filter  command  line  will  be  replaced  by  appropriate  values.   Option
            specifications have the form $[0| ][-]X.  The default option expansion has the form $X -> -X'value';
            the form $0X or $(space)X adds a space after  the  -X,  i.e.-  $0X  ->  -X  'value';  the  form  $-X
            suppresses the -X, i.e. - $-X -> value.  The options will be expanded as follows:

            Key  Value
            a    Accounting file (printcap 'af' entry)
            b    Job size, i.e.- total data file size, in bytes
            c    if binary (format 'l') expands to -c
            d    Control directory
            e    job data file
            f    original print file name (control file N field)
            h    Control file hostname
            i    Control file indent (I) field
            j    job number from control file name
            k    Control file name
            l    printcap Page length (pl) value
            m    printcap Cost factor (co) value
            n    Control file user logname (P) field
            p    Remote Printer name for forwarded jobs
            r    Remote Host name for forwarded jobs
            s    printer Status file (ps) value
            t    current time in simple format
            w    printcap Page width (pw) value
            x    printcap x dimension (px) value
            y    printcap y dimension (py) value
            F    data file format character
            P    Printer name
            S    printcap Comment tag (cm) value
            Upper Case   control file line starting with letter
            Digit control file line starting with digit

       5.   The  options  specified by the filter_options (for none OF filters) or of_filter_options (for the OF
            filter) will be appended to the command line and expanded.  To suppress adding options, you can  use
            the  form  '-$  filter',  i.e.  - of=-$/bin/cat.  If the 'bkf' (backwards compatible filter options)
            printcap flag is set, the of filter is given the options specified by bk_of_filter_options and other
            filters  those  by  bk_filter_options.   The  following shows the various combinations possible, and
            typical values for the options.

            Options
            filter_options    $C $F $H $J $L $P $Q $R $Z $a $c $d $e $f $h $i \
                              $j $k $l $n $s $w $x $y $-a
            bk_filter_options $P $w $l $x $y $F $c $L $i $J $C $0n $0h $-a
            bk_of_filter_options $w $l $x $y

       6.   A printing filter which executes correctly and completely should
            exit with a 0 error status.
            A nonzero error status will be interpreted as follows:
            JFAIL    32   failed - retry later
            JABORT   33   aborted - do not try again, but keep job
            JREMOVE  34   failed - remove job

       The JFAIL will cause the job to be retried at a later time.  A limit can  be  placed  on  the  number  of
       retries  using  the  :rt:  or :send_try: printcap entry.  A retry value of 0 will cause infinite retries.
       The JABORT indicates serious problems and will cause  printing  operations  on  the  job  to  stop  until
       restarted by operator intervention.  The JREMOVE status indicates problems, and the job should be removed
       from the spool queue.

       The environment variables for filters are highly restricted, due to the possibility for abuse  by  users.
       The following variables are set:

       USER and LOGNAME
            user name or daemon name.

       LOGDIR
            home directory of user or daemon.

       PATH from the filter_path configuration variable.

       LD_LIBRARY_PATH
            from the filter_ld_path configuration variable.

       SHELL
            set to /bin/sh

       IFS  set to blank and tab.

       TZ   the TZ environment variable.

       SPOOL_DIR
            the spool directory for the printer

       CONTROL_DIR
            the control directory for the printer

       PRINTCAP_ENTRY
            the printcap entry for the printer

       CONTROL
            the control file for the print job

       pass_env environment variables
            Values of environment variables listed in the pass_env configuration variable.

ACCOUNTING

       The  LPRng  software  provides  several  methods  of  performing accounting.  The printcap af (accounting
       field), as and ae (accounting start and end),  and  achk  (accounting  check)  provide  a  basic  set  of
       facilities.   The  af  field specifies a file, filter, or TCP network connection to an accounting server.
       If af has the form |filter or |-$ filter then a filter will be started  and  all  accounting  information
       will  be  sent to the filter.  The first form passes the filter the command line options specified by the
       filter_options configuration variable and the second suppresses option  passing.   If  af  has  the  form
       host%port  then  a  TCP  connection  will  be  opened  to  the  port on the specified host and accounting
       information sent there.  All other forms will be treated as  a  pathname  relative  to  the  queue  spool
       directory.

       If  af  specifies a file, then the accounting information is appended to an existing file; the accounting
       file will not be created.

       When af specifies a filter or network connection and the achk flag is set, then after writing the initial
       accounting  information (see as printcap field below) the server will wait for a reply of the form ACCEPT
       from the filter or server.  If not received, the job will not be printed.

       The as (accounting start) and ae (accounting end) fields can specify a string to be printed or a  filter.
       Options  in  the string will be expanded as for filters, and the strings printed to either the accounting
       information destination.  If the as field specifies a filter, then the print server  will  wait  for  the
       filter  to  exit before printing the job.  If the exit status is 0 (successful), the job will be printed.
       A non-zero JREMOVE status will remove the job, while any  other  status  will  terminate  queue  printing
       operations.   After  printing  the  job, the ae filter will be started and the server will wait for it to
       complete before printing the next job.

       The as and ae filters will have STDOUT set to the printing device and or filter, and the  STDERR  set  to
       the  error log file for the print queue, and file descriptor 3 set to the destination specified by the af
       field.

       As a convenience, all format filters for printing will be started with  file  descriptor  3  set  to  the
       destination  (file  or filter) specified by the printcap af field.  This allows special filters which can
       query devices for page counts  to  pass  their  information  directly  to  an  accounting  program.   The
       descriptor  will  READ/WRITE,  allowing  filters  to  query  the  accounting  program  and/or  update the
       information directly.

LOGGING INFORMATION

       In order to provide a centralized method to track job status and information, the  printcap/configuration
       variable logger_destination enable the send of status and other information to a remote destination.  The
       logger_destination value has the form
              host[%port][,protocol]
          Examples:
              taco%451,UDP
              dickory%2001,TCP
       where host is the host name or IP address, port is an optional port number, and protocol is  an  optional
       protocol   type   such   as   UDP   or   TCP.    The   configuration  variables  default_logger_port  and
       default_logger_protocol can be used to override the default port number (2001) and protocol (UDP)  to  be
       used if none is specified.  Logging information has the format below.
              IDENTIFIER jobid [PRINTER name] at timestamp \
                 STATUS | TRACE | FILTER_STATUS PID nnn
              [ status information]

       The status information format consists of an identifier line, followed by a specifier of the status type.
       The logging information entry is terminated by a line with a single period on it.  Lines with a  starting
       period have the period duplicated.

AUTHENTICATION

       Rather  than  building  authentication  facilties  into LPRng, an interface to authentication programs is
       defined, and will be used as follows.  The printcap and configuration entries  auth,  auth_client_filter,
       auth_forward,  auth_forward_id,  auth_forward_filter,  auth_receive_filter,  and  auth_server_id  entries
       control authentication.  The auth value specifies the type of authentication to be  used  for  client  to
       server  authentication.   Typical  values would be kerberos, md5, etc.  If the authentication type is not
       built-in, the client programs use the auth_client_filter  program  to  perform  authentication.   When  a
       server  gets  and  an  authentication  request,  it  will  use the auth_receive_filter program to perform
       authentication.  The auth_server_id is the remote server id used when a client is  sending  jobs  to  the
       server  or  when  the  server  is  originating  a  request.   When  a  server forwards a request, it uses
       auth_forward value to determine if  authentication  is  to  be  done,  and  the  auth_forward_id  as  the
       destination server id.

Client To Server Authentication

       1.  The  client  will open a connection to the server and sends a command with the following format.  The
           REQ_SECURE field in the command corresponds to the one-byte command type used by the LPR protocol.
              Commands:
                  \REQ_SECUREprinter C user\n
              Print job transfers:
                  \REQ_SECUREprinter C user controfilename\n

       2.  On reception of this command,  the server will send a one byte success code as below.  An error  code
           may be followed by additional error information.  The values used by LPRng include:
              ACK_SUCCESS     0   success, no error
              ACK_STOP_Q      1   failed; no spooling to the remote queue
              ACK_RETRY       2   failed; retry later
              ACK_FAIL        3   failed; job rejected, no retry

       3.  If there is an error the connection will be terminated.  The server will then start an authentication
           process, and provide the following open file descriptors for it.  The authenticator process will  run
           as the UID of the server (i.e.- usually daemon).
              FD    Options Purpose
              0     R/W     socket connection to remote host (R/W)
              1     W       pipe or file descriptor
                            for information for server
              2     W       error log
              3     R       pipe or file descriptor
                            for responses to client

           The command line arguments will have the form:
              program -S -Pprinter -nuser -Rserver_user -Ttempfile

           The  printer  and  user  information  will be obtained from the command line sent to the server.  The
           authenticator can create additional temporary or  working  files  with  the  pathnames  tempfile.ext;
           these should be deleted after the authentication process has been completed.

       4.  After  receiving \ACK_SUCCESS, the client starts an authenticator process, and provides the following
           open file descriptors for it.  The authenticator process will run UID user.
              FD    Options Purpose
              0     R/W     socket connection to remote host (R/W)
              1     W       pipe or file descriptor
                            for responses to client
              2     W       error log

           The command line arguments will have the form:
              program -C -Pprinter -nuser -Rserver_user -Ttempfile

       5.  The authenticator can create additional temporary or working files with the  pathnames  tempfile.ext;
           these  will be deleted after the authentication process has been completed.  The client authenticator
           will be running as the client user.

       6.  After exchanging authentication information, the client authenticator will transfer the  contents  of
           the temporary file to the server authenticator, using FD 0.  It will then wait for reply status on FD
           0.   If the transfer step fails, or there is no reply status  of  the  correct  format,   the  client
           authenticator  will  print any received information on FD 1, error information on FD 2, and then exit
           with error code JFAIL.

       7.  After receiving the files on FD 0,  the server authenticator will perform the required authentication
           procedures  and  leave the results in tempfile.  The server authenticator will write the following to
           FD 1,  for use by the server:
              authentication_info\n

           If the transfer step or authentication fails,  then the server will write an error message  to  FD  2
           and  exit with error code JFAIL.  The server will use this authentication information to determine if
           the remote user has permission to access the system.

       8.  The server authentication process will read input from FD 3 until and end of file, and  then  proceed
           to  transfer  the  input  to the client authenticator.  If the data transfer fails,  then the process
           will exit with error code JFAIL, otherwise it will exit with error code JSUCC.

       9.  The client authenticator  will  read  the  status  information  from  FD  0,   and  after  performing
           authentication  will  write it to FD 1.  If data transfer or authentication fails,  the authenticator
           will write an error message to FD 2 and exit with error code JFAIL, otherwise it will exit with error
           code JSUCC.

Server to Server Authentication

       The  Server  to  Server  authentication  procedure  is  used by one server to forward jobs or commands to
       another server.  It should be noted that this forwarding operation puts an implicit trust in the security
       of  the  client  to  server to server chain.  In the description below, src and dst are the userid of the
       source and destination servers respectively.

       1.  The originating host takes the part of the client, and will transfer a job acting  like  the  client.
           The initial information transfer from the originating (src) server will have the format:
              Commands:
                  \REQ_SECUREprinter F user\n
              Print job transfers:
                  \REQ_SECUREprinter F user controfilename\n

           After  receiving  a  0  acknowledgment  byte,  the  src server will invoke its authenticator with the
           arguments below.  The forward_user value will default to the  server_user  value  if  not  explicitly
           provided.
              program -C -Pprinter -nserver_user \
                  -Rforward_user -Ttempfile

       2.  On the destination server the authenticator is invoked with the arguments:
              program -S -Pprinter -nserver_user \
                  -Rforward_user -Ttempfile

           The  authentication  is performed to determine that the transfer was between the two servers,  rather
           than the user to server.

KERBEROS AUTHENTICATION

       As a convenience, Kerberos 5 authentication has been built into the LPD clients and servers.  If you  are
       not  familiar  with  Kerberos,  then  you  should  obtain  other  documentation  and/or assistance before
       attempting to use this.  The following facilities/configuration values are used to support Kerberos.

       A Kerberos principal is the name used  for  authentication  purposes  by  Kerberos.   For  example,  user
       principals  have the form user@REALM; for example, papowell@ASTART.COM.  Services and/or servers have the
       form service/host@REALM; for example, the lpd server on dickory would have the form:
            lpr/astart2.astart.com@ASTART.COM

       User to server authentication process will use the user's principal name, and generate a service name for
       the server.  The name generation is controlled by the following configuration and/or printcap values.

       service
              The name of the service to be used to identify the service.  This is usually "lpr".

       kerberos_keytab
              The  location  of  the  server keytab file.  The keytab file corresponds to the user password, and
              must  be  considered  a  security  risk.   It  should  be  owned  by  the  LPD  server  user,  and
              readable/writable only by the server.

       kerberos_life
              The lifetime of the authentication ticket used by the server.  This usually defaults to 10 hours.

       kerberos_renew
              The renewal time of the ticket.

       In  addition  to  the  default values, an explicit server principal can be specified in the printcap file
       using the kerberos_server_principal This allows cross domain authentication to be done.

       When setting up Kerberos authentication, you will need to establish principals for each  server,  and  to
       distribute and install the keytab files on each server.

AUTHENTICATION PERMISSIONS

       The following permissions tags are available to check on authentication procedures.
              AUTH=[NONE,USER,FWD]    - authentication
                  AUTH=NONE   - no authentication
                  AUTH=USER   - authentication from a client
                  AUTH=FWD    - forwarded authentication from a lpd server
              AUTHTYPE=globmatch
              AUTHUSER=globmatch
              FWDUSER=globmatch

       1.  The AUTH tag can be used to determine the type of authentication being done.  The AUTHTYPE tag can be
           used to match the authentication type being used or requested by the client or  remote  server.   The
           authentication  process  returns  an  authentication identifier for the user; this information can be
           matched by the AUTHUSER tag.

       2.  For a command sent from a client or forwarded  from  a  server,  AUTHUSER  matches  the  auth_user_id
           provided  for  the  user  when  sent  to  a  server.  (This information will be forwarded by a remote
           server).  For a forwarded command, FWDUSER refers to the authentication information  for  the  server
           doing the forwarding.

       3.  For  example,   to  reject  non-authenticated  operations,  the  following  line  could be put in the
           permissions file.
              REJECT AUTH=NONE

       4.  To reject server forwarded authentication as well, we use REJECT AUTH=NONE,FWD.  If a  remote  server
           with  name serverhost has id information FFEDBEEFDEAF,  then the following will accept only forwarded
           jobs from this server.
              ACCEPT FWDUSER=FFEDBEEFDEAF REMOTEHOST=serverhost
              REJECT AUTH=FWD

ENVIRONMENT

       The lpd action can also be manipulated by using environment variables.

       LPR_TMP

   Authentication
       MD5KEYFILE
              Used for md5 signated file transmission

FILES

       The files used by LPRng are set by values in  the  printer  configuration  file.   The  following  are  a
       commonly used set of default values.
       /etc/lprng/lpd.conf                          LPRng configuration file
       ${HOME}/.printcap                            user printer description file
       /etc/printcap                                printer description file
       /etc/lprng/lpd.perms                         permissions
       /var/run/lprng/lpd                           lock file for queue control
       /var/spool/lpd                               spool directories
       /var/spool/lpd/QUEUE/control                 queue control
       /var/spool/lpd/QUEUE/log                     trace or debug log file
       /var/spool/lpd/QUEUE/acct                    accounting file
       /var/spool/lpd/QUEUE/status                  status file

SEE ALSO

       lpd.conf(5), lpc(8), checkpc(8), lpr(1), lpq(1), lprm(1), printcap(5), lpd.perms(5), pr(1).

AUTHOR

       Patrick Powell <papowell@lprng.com>.

DIAGNOSTICS

       Most  of  the  diagnostics are self explanatory.  If you are puzzled over the exact cause of failure, set
       the debugging level on (-D5) and run again.  The debugging information will  help  you  to  pinpoint  the
       exact cause of failure.

HISTORY

       LPRng  is a enhanced printer spooler system with functionality similar to the Berkeley LPR software.  The
       LPRng   developer   mailing   list   is   lprng-devel@lists.sourceforge.net;   subscribe   by    visiting
       https://lists.sourceforge.net/lists/listinfo/lprng-devel      or      sending      mail     to     lprng-
       request@lists.sourceforge.net with the word subscribe in the body.
       The software is available via http://lprng.sourceforge.net