Provided by: lprng_3.8.B-2.2_amd64 
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