Debian Codegraph @

upstream/debian-unstable/man8/lpd.8

raw
1 .TH LPD 8 2008-03-14 "LPRng" "lpd daemon"
2
3 .hy 0
4 .de NP
5 .IP \\n(nP
6 .nr nP \\n(nP+1
7 ..
8 .de np
9 .nr nP 1
10 ..
11 .de L
12 .ie !"\\$1"" \{\
13 .ft CW
14 \&\\s-2\\$1\\s+2\\fP\\$2
15 .ft R
16 .\}
17 .el \{\
18 .ft CW
19 .ps -2
20 .\}
21 ..
22 .SH NAME
23 lpd \- line printer daemon
24 .SH SYNOPSIS
25 .B lpd
26 .RB [ \-L
27 .IR logfile ]
28 .RB [ \-F ]
29 .RB [ \-V ]
30 .RB [ \-D
31 .IR debugopt ]
32 .RB [ -p
33 .IR port ]
34 .SH DESCRIPTION
35 The lpd program is the printer server program of the LPRng software
36 suite.
37 This software is an enhanced and modified version of the Berkeley LPD
38 software.
39 .SH OPTIONS
40 .TP
41 .BI \-L " logfile"
42 specifies an alternate file to be used for logging error and debugging
43 messages.
44 The
45 .IR syslog (8)
46 facility is used to log critical messages as well.
47 Please note that you need to create the file by yourself, a 'touch' is sufficient.
48 This is needed for security reasons.
49 .TP
50 .B \-F
51 Under normal operation, the LPD server will run in
52 background mode.
53 The -F flag forces it to run in foreground mode,
54 where it is more easily debugged.
55 .TP
56 .B \-V
57 Print program version information.
58 .TP
59 .BI \-D " debugopt"
60 Debugging is controlled using the
61 .B \-D
62 option. This accepts a comma-separated list of debugging
63 settings. These settings take one of two forms:
64 .B facility=value ,
65 or
66 .B value
67 to set an overall default value.
68 The available facilities can be determined by
69 invoking LPD with the \-D= parameter.
70 .TP
71 .BI \-p " port"
72 Bind to the specified port rather than port 515 specified by RFC1179.
73 .SH OPERATION
74 .PP
75 .I Lpd
76 is the line printer daemon (spool queue handler) and is normally invoked
77 at boot time from the
78 .IR rc (8)
79 file;
80 it can also be started by a user.
81 Note that the lpd server needs only run on systems where actual printing
82 or spooling is taking place.
83 .IR lpr (1)
84 and other related programs transfer files using network facilities to the
85 .IR lpd .
86 .PP
87 When started,
88 .I lpd
89 reads a configuration file to obtain basic operational parameters
90 and then reads the
91 .IR printcap (5)
92 database information to determine the which printers have spool queues
93 and to start spool queue server processes.
94 If running as a background server,
95 it will disconnect from its control terminal and run in the background.
96 It uses the system calls
97 .IR listen (2)
98 and
99 .IR accept (2)
100 to receive requests to print files in the queue,
101 transfer files to the spooling area,
102 display the queue,
103 remove jobs from the queue,
104 or perform a spool queue control function.
105 In each case it creates one or more server processes to handle
106 the request and the lpd process will listen for more requests.
107 .PP
108 Sending the server a
109 SIGHUP signal causes the server to reread the various configuration
110 and inititialization files.
111 This action is similar to that of the
112 .I INETD
113 and other servers.
114 The same action is taken when sent a
115 .I reread
116 command by the
117 .IR lpc (1)
118 program.
119 At an interval specified by
120 the
121 .I poll_time
122 configuration variable,
123 .I lpd
124 will check for spool queues with jobs and no printing activity,
125 and start printing.
126 .PP
127 LPD access control is done using
128 a rule set and match algorithm similar to a packet filter.
129 Each request for printing, status, or control operations
130 is matched against the rule set,
131 and the first ACCEPT or REJECT value determines
132 if the operation can be performed.
133 The following is a typical permissions file:
134 .RS
135 .nf
136 .L
137 # Set default permissions
138 DEFAULT ACCEPT
139 # Reject any connections from outside our subnet
140 REJECT SERVICE=X NOT IP=130.191.0.0/255.255.0.0
141 # Only accept Printing (P) and spooling (LPR) from
142 # the private network, the 10.0.0.0/8 network and fw
143 REJECT SERVICE=P,R NOT REMOTEHOST=*.private,10.0.0.0/8,fw.astart.com
144 # Do not accept forwarded jobs for printing
145 REJECT SERVICE=P FORWARD
146 # Allow only the administrators control access
147 ACCEPT SERVICE=C,M REMOTEHOST=spooler.astart.com USER=root,papowell
148 ACCEPT SERVICE=C,M SERVER REMOTEUSER=root,papowell
149 # Allow only the user on the same host who spooled job to remove it
150 ACCEPT SERVICE=M SAMEUSER SAMEHOST
151 REJECT SERVICE=M,C
152 .RE
153 .fi
154 .sp
155 .LP
156 Permission checking is done by using a set of keys (or fields)
157 with associated values to check for permission.
158 The SERVICE key has value P for printing (i.e.- unspooling),
159 R for spooling (i.e.- LPR request),
160 C and S for printer control and status respectively (i.e.- LPC request),
161 M for removal (i.e.- LPRM request),
162 Q for queue information (i.e.- LPRM request),
163 and so forth.
164 The
165 .B X
166 key indicates the initial connection to the LPD spooler,
167 and can be used to control connections from remote systems.
168 The
169 values of the USER, HOST, and IP keys taken from the control file
170 which is being received or checked for permissions.
171 The REMOTEUSER, REMOTEHOST and REMOTEIP keys are those either sent
172 as part of a command,
173 or derived from information about the current network connection.
174 Each line of the permissions file is scanned for key names and
175 values, and these are matched against the request keys information.
176 When all matches on a line are made,
177 then search terminates with the specified action (ACCEPT/REJECT).
178 If no match is found the default permission value is used.
179 The
180 DEFAULT key is used to specify the current default permission to
181 be used for successful matches or if there is no match after
182 scanning the entire permissions database.
183 .LP
184 The GROUP entry is used to check that the USER name appears in a
185 group entry in the system user group database.
186 For example,
187 GROUP=student*,staff*
188 would check to see if any of the group name matching
189 student* or staff* have the specified user name in them.
190 If a system has the
191 .I netgroups
192 capability,
193 a group name starting with a
194 \f(CW@\fR
195 will be treated as a netgroup name,
196 and current user name from the job file will be checked to see if
197 it is in the group.
198 Similarly,
199 the
200 REMOTEGROUP entry will check a remote user name.
201 The
202 PORT
203 entry can be used to ensure that a connection to the server
204 originates from a specified range of ports.
205 For more details,
206 see the
207 .BR lpd.perm (5)
208 man page.
209 .LP
210 The permissions database is scanned in order of the fixed file entries
211 and then by invoking the specified filters for each
212 of the permissions lists.
213 It is recommended that the filters be placed at the end of the
214 permissions lists.
215 The user name is one of the parameters passed to the filter,
216 and can be used to determine if a user has permissions to print a file.
217 .sp
218 .nf
219 .ne 20v
220 .ta \w'Key__________'u +\w'Match_'u +\w'Connect_'u +\w'Job___'u +\w'Job____'u +\w'LPQ__'u +\w'LPRM__'u +\w'LPC'u
221 Key Match Connect Job Job LPQ LPRM LPC
222 \0 \0 \0 Spool Print
223 SERVICE S 'X' 'R' 'P' 'Q' 'M' 'C,S'
224 USER S - JUSR JUSR JUSR JUSR JUSR
225 HOST S RH JH JH JH JH JH
226 GROUP S - JUSR JUSR JUSR JUSR JUSR
227 IP IP RIP JIP JIP RIP JIP JIP
228 PORT N PORT PORT - PORT PORT PORT
229 REMOTEUSER S - JUSR JUSR JUSR CUSR CUSR
230 REMOTEHOST S RH RH JH RH RH RH
231 REMOTEGROUP S - JUSR JUSR JUSR CUSR CUSR
232 REMOTEIP IP RIP RIP JIP RIP RIP RIP
233 CONTROLLINE S - CL CL CL CL CL
234 PRINTER S - PR PR PR PR PR
235 FORWARD V - SA - - SA SA SA
236 SAMEHOST V - SA - SA SA SA
237 SAMEUSER V - - - SU SU SU
238 SERVER V - SV - SV SV SV
239 AUTH V - AU - AU AU AU
240 AUTHTYPE S - AU - AU AU AU
241 AUTHUSER S - AU - AU AU AU
242 FWDUSER S - AU - AU AU AU
243
244
245 .ta 3m +\w'RH = REMOTEHOST 'u
246 KEY:
247 JH = HOST host in control file
248 RH = REMOTEHOST connecting host name
249 JUSR = USER user in control file
250 CUSR = REMOTEUSER user from control request
251 JIP= IP IP address of host in control file
252 RIP= REMOTEIP IP address of requesting host
253 PORT= connecting host origination port
254 CONTROLLINE= pattern match of control line in control file
255 FW= IP of source of request = IP of host in control file
256 SA= IP of source of request = IP of host in control file
257 SU= user from request = user in control file
258 SA= IP of source of request = IP of server host
259 SV= matches if remote host is the server
260 AU= authentication information
261 IFIP= IP address of remote end of connection
262
263 Match: S = string with wild card, IP = IP address[/netmask],
264 N = low[-high] number range, V = exact value match
265 SERVICE: 'X' - Connection request; 'R' - lpr request from remote host;
266 'P' - print job in queue; 'Q' - lpq request, 'M' - lprm request;
267 'C' - lpc spool control request; 'S' - lpc spool status request
268 NOTE: when printing (P action), the remote and job check values
269 (i.e. - RUSR, JUSR) are identical.
270 .fi
271 .sp
272 .PP
273 The special key
274 .I letter=patterns
275 searches the control file line starting with the
276 (upper case) letter,
277 and is usually used with printing and spooling checks.
278 For example,
279 C=A*,B*
280 would check that the class information (i.e.- line in the control file
281 starting with C) had a value starting with A or B.
282 .SH "PERMISSIONS, MULTIHOMED HOSTS, IPV6"
283 .PP
284 There is a subtle problem with names and IP addresses which are
285 obtained for 'multi-homed hosts', i.e. - those with multiple
286 Ethernet interfaces, and for IPV6 (IP Version 6), in which a host
287 can have multiple addresses, and for the normal host which can have
288 both a short name and a fully qualified domain name.
289 In addition,
290 a host can have multiple IP addresses,
291 depending on the complexity of its configuration.
292 .PP
293 The IFIP (interface IP) field can be used to check the IP address
294 of the origination of the request, as reported by the information
295 returned by the accept() system call. Note that this information may
296 be IPV4 or IPV6 information, depending on the origination of the
297 system. This information is used by gethostbyaddr() to obtain the
298 originating host fully qualified domain name (FQDN) and set of IP addresses.
299 Note that this FQDN will be for the originating interface, and may
300 not be the canonical host name. Some systems which use the Domain Name Server
301 (DNS) system may add the canonical system name as an alias.
302 .PP
303 When performing an IP address match, the entire list of IP addresses
304 for a system will now be checked. If one of these matches, then success
305 is reported. Similarly, the entire list of host names and aliases will
306 be checked. If one of these matches, then success will be reported.
307 .PP
308 In addition, when checking for printing, if the name lookup for the
309 host reported in the control file fails, then we assume that the host
310 is unknown and all match checks for names or IP addresses will fail.
311 You can determine if a host has an entry by using the following check,
312 which will reject all requests from a remotehost which does not have
313 a DNS entry.
314 .br
315 REJECT NOT REMOTEHOST=*
316 .br
317 .SH "PRINTCAP DATABASE"
318 Individual printer operations are controlled by values in the
319 printcap database.
320 See
321 .IR printcap (5)
322 for details of the format and content of the various entries.
323 The following are typical printer entries for a local and remote printer.
324 .RS
325 .sp
326 .nf
327 .ft CW
328 # main or shared printcap file - usually /etc/printcap
329 # remote postscript printer
330 fullpage
331 |postscript
332 :[email protected]
333 # give access to (remote) hosts
334 t1|postscript2
335 :cm=Test Printer 1
336 :[email protected]
337
338 # local printcap file
339 # specification for local printer on nearside
340 t1|postscript2
341 :oh=nearside.astart.com
342 :cd=/usr/spool/LPD/safe
343 :sd=/usr/spool/LPD/t1
344 #
345 # /usr/spool/LPD/t1/printcap file -
346 t1:
347 :lp=/dev/pr
348 :if=/usr/lib/pr/if
349 :of=/usr/lib/pr/if
350 .RE
351 .sp
352 .fi
353 .PP
354 Printcap information can be distributed by individual files or shared using
355 NSF, YP, or other methods;
356 see
357 .IR lpd.conf (5)
358 for the exact details of the location of printcap files and programs,
359 given by the
360 .I printcap_path
361 and
362 .I lpd_printcap_path
363 configuration information.
364 The usual printcap configuration is to have a main (shared) printcap database
365 which is used by all hosts.
366 The printcap information is usually extremely simple,
367 consisting only of the printer name and host (i.e. - fullpage printer entry).
368 .PP
369 On hosts which have printers attached or which are to provide spooling queue
370 directories,
371 more extensive printcap information is needed.
372 In the shared database,
373 .I oh
374 (options for specified host only) field restricts use of this entry
375 to the specified host.
376 This entry can contain host specific information,
377 such as the location of the spool queue and/or actual device to be used
378 for output.
379 .PP
380 In the above example,
381 the main printcap file, /etc/printcap
382 has entries for all printers.
383 Note that these entries do not specify the spool directories (sd and cd fields),
384 but this could be provided.
385 On a host with a printer specific information can be provided in several ways.
386 The simplest is to simply put an additional entry in the shared printcap file,
387 with the
388 .I oh
389 field set to the support host name.
390 An alternative would be to specify the spool directories (sd and cd fields) in the
391 shared information,
392 and to put the printer specific information in a printcap file.
393 .PP
394 In addition to the
395 .I oh
396 flag,
397 the
398 .I server
399 flag indicates that this entry is for a the LPD server only.
400 This can be used to simplify the management of client and server entries.
401 .PP
402 The printcap information is obtained in the following order.
403 If the lpd_printcap_path configuration value is nonblank
404 then the lpd server will process only this information
405 otherwise it uses the printcap_path information.
406 All client programs use the contents of the configuration
407 printcap_path variable to get a list of locations of printcap files.
408 Each of these entries in the path lists are processed,
409 and the printcap information is extracted.
410 Entries which have
411 .I oh
412 fields are only used by the specified host.
413 The files and information is processed in linear order,
414 later entries overriding preceding ones.
415 .PP
416 When processing jobs or performing spool queue specific requests,
417 the LPD server will check to see if there is a printcap file in the control
418 directory for the spool queue and the contents will be processed.
419 Since only the LPD server has access to the spool and control queues,
420 this information is processed only by the server.
421 .PP
422 In addition to files,
423 printcap information can be obtained from programs or filters.
424 For example,
425 the printcap_path of the form
426 .L /etc/printcap:|/usr/lib/getpr
427 will use the contents of the
428 .L /etc/printcap
429 file,
430 and then use the
431 .L /usr/lib/getpr
432 program to get information about a specific printer.
433 When information about a particular spool queue is needed and
434 one or more filters are specified as the source of printcap information,
435 then the filter will be started and the printer name written on
436 its standard input.
437 The filter must provide a printcap entry for the requested printer on its standard output.
438 .PP
439 The filter can be used to interface to databases or nonstandard information sources
440 which do not produce printcap information in an acceptable form.
441 .SH "SPOOL DIRECTORY CONTENTS"
442 .PP
443 Each spool queue has a spool directory
444 (sd) and optional control
445 directory
446 (cd) where job and control information is kept.
447 Under normal operation the spool and control directories are
448 identical,
449 but if the spool directory is NFS exported for use by other printer
450 spoolers which write files directly into the spool queue,
451 then it is recommended that the control directory be a separate
452 directory and not NFS mounted.
453 The following files are used for printer operations.
454 Per job entries are marked with an asterisk (*).
455 .sp
456 .nf
457 .ta 20n +8n +4n
458 File Name Dir Purpose
459 printer CD lock file and server process PID
460 unspooler.printer CD subserver process PID
461 control.printer CD queue control information
462 *hfAnnn SD job hold file
463 *cfAnnnHOST SD job control file
464 *dfAnnnHOST SD job data file
465 *bfAnnn.* SD temporary files
466 .sp
467 .fi
468 .PP
469 The nnn in the file names stands for the job number.
470 RFC1179 requires this to be a 3 digit number,
471 but the longnumber printcap flag or a nonzero
472 longnumber configuration variable will enable 6 digit numbers.
473 .PP
474 The lock file is used to
475 prevent multiple job queue servers from becoming active simultaneously,
476 and to store the server process id.
477 The lock file name is the name as the printer name;
478 all other control files have the printer name appended as indicated above.
479 .PP
480 The printer spool control file contains information controlling
481 the queue operations.
482 It consists of a series of lines with keywords and values to control
483 printing,
484 spooling,
485 and automatic job holding operations.
486 The following is an example of a typical spool control file.
487 .sp
488 .nf
489 .RS
490 spooling_disabled 0
491 printing_disabled 1
492 holdall 0
493 redirect p1@host2
494 debug 10,log=/tmp/log
495 class A
496 .RE
497 .sp
498 .fi
499 .PP
500 The
501 .I spooling_disabled
502 and
503 .I printing_disabled
504 entries control spooling and printing;
505 the lpc
506 .I enable,
507 .I disable,
508 .I start,
509 and
510 .I stop
511 command alter these values.
512 The
513 .I holdall
514 entry will prevent jobs from being processed until released
515 with the lpc
516 .I hold
517 or
518 .I release
519 comands;
520 the lpc
521 .I holdall
522 and
523 .I noholdall
524 commands alter these values.
525 .PP
526 The
527 .I redirect
528 entry causes the lpd server to forward jobs to the specified
529 remote printer;
530 the lpc
531 .I redirect
532 command alters this field.
533 The
534 .I class
535 field controls the class of jobs being printed.
536 By default,
537 the class value is a pattern that matches the
538 class entry in a job file;
539 however a entry of the form
540 .I letter=patterns
541 will print jobs whose control file line starting with
542 .I letter
543 matches one of the patterns.
544 The
545 .I debug
546 line provides a set of debugging parameters for diagnostic information
547 for the particular spool queue.
548 .PP
549 Each print job consists of a control file and one or more data files.
550 Lines in the control file
551 file specify the job data files or parameters for the job
552 and the general format of the file is specified by RFC1179.
553 Each line consists of a flag character and a parameter;
554 upper case and digit characters specify options and
555 lower case letters specify the printing format and names of data
556 files.
557 The following is a list of the control file flag characters.
558 .sp
559 .IP A
560 Identifier
561 A job identifier to be used when displaying job
562 information and/or status.
563 The insertion of this line is controlled by the
564 .I use_identifier
565 printcap/configuration variable.
566 .sp
567 .IP C
568 Class
569 String to be used for the class line on the burst page.
570 .IP H
571 Host Name. Name of the machine where
572 .I lpr
573 was invoked.
574 .IP I
575 Indent. The number of characters to indent the output by (in ascii).
576 .IP J
577 Job Name. String to be used for the job name on the burst page.
578 .IP L
579 Banner user name.
580 Information for banner page.
581 .IP P
582 Person. Login name of the person who invoked
583 .IR lpr .
584 This is used to verify ownership by
585 .IR lprm .
586 .IP M
587 Send mail to the specified user when the current print job completes.
588 .IP N
589 File name.
590 The original name of a data file which is in the job.
591 .IP T
592 Title. String to be used as the title for
593 .IR pr (1)
594 when the LPR -p option was specified.
595 .IP U
596 Unlink. Job file to remove when printing completed.
597 .IP W
598 Width. The page width (in characters) to used for printing.
599 .IP Z
600 zoptions. Options passed by
601 .IR lpr
602 .IR -Zzoptions.
603 These are passed to output filters to aid in printing.
604 .IP f
605 Formatted File. Name of a file to print which is already formatted.
606 .IP l
607 Like ``f'' but passes control characters and does not make page breaks.
608 .IP p
609 Name of a file to print using
610 .IR pr (1)
611 as a filter.
612 .IP t
613 Troff File. The file contains
614 .IR troff (1)
615 output (cat phototypesetter commands).
616 .IP d
617 DVI File. The file contains
618 .IR Tex (l)
619 output (DVI format from Stanford).
620 .IP g
621 Graph File. The file contains data produced by
622 .IR plot (3X).
623 .IP c
624 Cifplot File. The file contains data produced by
625 .IR cifplot .
626 .IP v
627 The file contains a raster image.
628 .IP r
629 The file contains text data with FORTRAN carriage control characters.
630 .IP 1
631 Troff Font R. Name of the font file to use instead of the default.
632 (Obsolete)
633 .IP 2
634 Troff Font I. Name of the font file to use instead of the default.
635 (Obsolete)
636 .IP 3
637 Troff Font B. Name of the font file to use instead of the default.
638 (Obsolete)
639 .IP 4
640 Troff Font S. Name of the font file to use instead of the default.
641 (Obsolete)
642 .in -5
643 .sp
644 .PP
645 Each job in the spool queue can have an associated job hold file
646 which is used by the server process to control the printing of
647 the job.
648 The status file contains information controlling the job
649 hold status and error status.
650 The spool server will attempt to print a job a limited number of times
651 before abandoning it or setting an error status in the job status file.
652 The following is a typical job hold file.
653 .RS
654 .ft CW
655 hold 0
656 priority 0
657 active 2135
658 redirect
659 remove 0
660 error
661 .RE
662 .PP
663 A nonzero
664 .I hold
665 entry will prevent the job from being processed;
666 the lpc
667 .I hold
668 and release
669 commands update this field.
670 The
671 .I priority
672 field overrides the normal first-in first-out printing priority;
673 jobs with non-zero priority fields are printed first.
674 The lpc
675 .I topq
676 command updates this field.
677 If the
678 .I active
679 field is non-zero, the job is being printed by the server with the
680 specified process id.
681 The
682 .I redirect
683 field allows individual jobs to be forwarded to a different printer;
684 the lpc
685 .I move
686 command updates this field.
687 Finally,
688 the remove and error fields are used to control printing of problem jobs.
689 The
690 .I remove
691 field is set when a job should be removed;
692 the
693 .I error
694 field records information that would prevent a job from being printed.
695 .SH "JOB SUBMISSION"
696 The LPR program is used to submit a job to the LPRng system.
697 The LPR program opens a connection to the LPD server and
698 then transfer the job control file and data files.
699 The LPD server checks to see if the remote host
700 and user has permissions to
701 spool to the requested printer,
702 and then checks to see if the printer is accepting jobs.
703 If both conditions are met,
704 the job is accepted and the control and data files
705 are placed in the spool directory.
706 The LPRng software sends the control file first,
707 followed by the data files.
708 .PP
709 If the LPR program is acting as a filter,
710 it is not necessary to temporarily store the
711 print job on the local machine.
712 The input data can be sent directly to the LPD server for spooling
713 using an implicit job size of 0 and sending data until the connection
714 is terminated to the server.
715 However,
716 some LPD servers do not accept 0 size jobs,
717 even though it is specified by the RFC1179,
718 so by default LPR will create a temporary file.
719 The LPR -k (seKure) option specifies this direct transmission mode
720 be used.
721 .SH "JOB TRANSMISSION"
722 When LPR is to send a job to the server,
723 it must determine the location of the server.
724 It does this by examining the values of the
725 specified printer and host.
726 .PP
727 If the printer and host are explicitly specified in the form
728 .L "pr@host"
729 then the LPR program will send the job to the specified spool queue
730 .L pr
731 and to the server running on
732 .L host .
733 This can be explicitly specified by the PRINTER environment variable
734 or by the LPR -P option.
735 .PP
736 If the printer is specified only by a name,
737 then the information in the printcap database is used.
738 The printcap entry for the printer is searched for and the
739 remote host and printer information extracted.
740 The job is sent to the server running on the specified host.
741 .PP
742 This action can be modified by the following printcap or configuration
743 tags.
744 .IP "1. default_host=host" 5
745 (Configuration)
746 If there is no printcap entry for the printer,
747 the job is sent to the LPD server running on
748 .L host .
749 .IP "2. force_localhost" 5
750 (Configuration or printcap)
751 If this flag is specified, then LPR and other client programs will
752 send the job to the server running on the localhost.
753 This overrides the default_host information.
754 .SH "FORWARDING OPERATIONS"
755 The LPD system can forward jobs from one spool directory to another.
756 This is controlled by the following options.
757 .IP 1. 5
758 The forward field in the spool control file has a value
759 rp@rm.
760 This can be set using the LPC forward command.
761 .IP 2. 5
762 The lp (line printer) printcap entry has the form rp@rm.
763 There is a rm (remote machine) and optional rp (remote printer) printcap entry.
764 .LP
765 The first of the above conditions to be met will determine the
766 destination.
767 If printing is enabled,
768 then jobs will be forwarded to the remote destination.
769 Example:
770 .DS
771 .ft CW
772 .nf
773 # using lp=rp@host
774 test:sd=/usr/spool/test
775 :lp=test@host
776 test:sd=/usr/spool/test
777 :lp=test@host%port
778 # using :rp:rm:
779 test:sd=/usr/spool/test
780 :rp=test:rm=host
781 .ft R
782 .fi
783 .DE
784 .IP 3. 5
785 The LPD server uses the same algorithm for sending jobs as the
786 LPR program.
787 A connection is made to the remote server and the files are copied
788 to the server.
789 A set of timeouts is used to control error recover and retry operations.
790 The printcap and configuration variables
791 .I connect_timeout,
792 .I connect_interval,
793 .I connect_grace,
794 and
795 .I send_try
796 control connecting to the remote host.
797 A connection is attempted to the remote server from a
798 random port in the range of ports specified by the
799 .I originate_port
800 variable.
801 If a connection is not completed within
802 .I connect_timeout
803 seconds,
804 the connection is aborted,
805 and then after the
806 .I connect_interval
807 seconds it is retried.
808 The procedure repeated
809 indefinitely for printing,
810 but only once for status or control operations.
811 A
812 connect_timeout value of 0 indicates no timeout;
813 a value of 0 specifies infinite timeout
814 After a job has been successfully printed,
815 the connection is closed and the server waits for
816 .I connect_grace
817 seconds before trying to reconnect.
818 .SH "BOUNCE QUEUES"
819 .PP
820 Normally job files are forwarded to a printer without
821 modification.
822 The
823 .B lpd_bounce
824 flag makes the queue a
825 .I "bounce queue"
826 and allows banners to be generated and
827 data files to passed through the appropriate format filter.
828 The entire output of this process is then passed to the
829 destination with the format specified by
830 the
831 .B bq_format
832 option (default
833 .B l
834 or binary).
835 See PRINTING OPERATIONS for details about filters.
836 For example,
837 the following printcap entry will filter format f files.
838 .ne 1i
839 .DS
840 .ft CW
841 .nf
842 testbq:sd=/usr/spool/testbq:
843 :lpd_bounce
844 :bq_format=l
845 :lp=final@host
846 :if=/usr/lib/filter_for_f
847 :mf=/usr/lib/filter_for_m
848 :pf=/usr/lib/filter_for_pr
849 .fi
850 .ft R
851 .DE
852 .SH "CHANGING FORMAT OF DATAFILES"
853 .PP
854 Sometimes only the indicated format of the data files needs to be
855 changed.
856 This can be done using the
857 .B translate_format
858 option.
859 This entry consists of pairs of lower case characters of the form SdSd...;
860 S is the original and d is the translated format.
861 .ne 1i
862 .DS
863 .ft CW
864 .nf
865 changeformat:
866 :sd=/usr/spool/changeformat:
867 :translate_format=mfpf
868 :lp=final@host
869 .fi
870 .ft R
871 .DE
872 .PP
873 In the example above,
874 the m format is processed by a filter, and then its format type is changed to f;
875 the p format is processed similarly.
876 Note that the lpr -p option specifies that the job will be processed by the
877 .L /bin/pr
878 command - the filter must do both the pr processing and any necessary format conversions.
879 .SH "LPR FILTER PROCESSING"
880 .PP
881 The
882 .L :lpr_bounce:
883 printcap flag will cause LPR to do bounce queue filtering before sending the
884 job to the remote queue.
885 This can have unexpected effects if the filters are not
886 available on the local host.
887 .PP
888 A typical entry which will cause LPR to do filtering is shown below.
889 .ne 1i
890 .DS
891 .ft CW
892 .nf
893 testbq:lpr_bounce
894 :lp=printer@host
895 :if=/usr/lib/filter_for_f
896 :vf=/usr/lib/filter_for_v
897 :mf=/usr/lib/filter_for_m
898 :translate_format=mfvf
899 .ft R
900 .DE
901 .PP
902 This entry will force LPR to run jobs with formats f, m, and v
903 through the appropriate filter.
904 It will also rename the formats to the f format.
905 .SH "ROUTING JOBS TO PRINTERS"
906 .PP
907 When a job is submitted for printing,
908 sometimes it is desirable to have it dynamically rerouted to another
909 spool queue, or multiple copies send to various destination.
910 This can be done by using a
911 .L routing_filter .
912 .PP
913 When a job is accepted by the LPD server,
914 part of the processing includes passing it to a program specified
915 by the printcap
916 .L router
917 entry.
918 This filter is invoked with the original control file as STDIN,
919 and the default set of filter options.
920 The output of the routing filter will be a set of directives
921 used by LPD when forwarding the job to another printer
922 or in processing the job.
923 The environment and options flags are set as for a standard filter.
924 (See "FILTERS" for details.)
925 Here is a sample printcap entry:
926 .DS
927 .ft CW
928 .nf
929 t2|Test Printer 2
930 :sd=/var/spool/LPD/t2
931 :lf=log
932 :lp=t2@printserver
933 :bq=t1@localhost
934 :destinations=t1@localhost,t2@localhost
935 :router=/usr/local/libexec/filters/router
936 .ft R
937 .DE
938 .PP
939 The routing filter exit status is used as follows:
940 .nf
941 0 (JSUCC) - normal processing
942 37 (JHOLD) - job is held
943 any other value - job is deleted from queue
944 .fi
945 .PP
946 The router filter returns one or more routing entries with the
947 following format. Note that entry order is not important, but each
948 entry will end with the 'end' tag.
949 .DS
950 dest <destination queue>
951 copies <number of copies to be made>
952 X<controlfile modifications>
953 end
954 .DE
955 .PP
956 Example of router output:
957 .DS
958 .ft CW
959 .nf
960 dest t1@localhost
961 copies 2
962 CA
963 end
964 dest t2@localhost
965 CZ
966 end
967 .ft R
968 .DE
969 .PP
970 The above routing information will have copies of the job sent to
971 the t1 and t2 spool queue servers. If no valid routing information
972 is returned by the router filter the job will be sent to the default
973 bounce queue destination.
974 .PP
975 .SH "REFORMATING CONTROL FILES"
976 .PP
977 Sometimes it is desirable to reformat a control file before
978 sending to a remote destination.
979 If the
980 .L control_filter
981 printcap entry is present,
982 then the control file is passed through the filter.
983 If the filter exits with status JSUCC,
984 then the job is process normally;
985 status JABORT causes the job processing to be aborted,
986 status JREMOVE causes the job processing to be removed,
987 and any other status is treated as JFAIL.
988 .PP
989 After passing the control file through the control_filter,
990 the LPD server will reread it,
991 and transfer only the data files specified in the new control file
992 to the destination.
993 .SH "SPOOL QUEUE NAME OPTION"
994 .PP
995 The
996 .L qq
997 printcap entry
998 and the
999 .L use_queuename
1000 configuration entry causes the name of the spool queue
1001 to be placed in the job control file.
1002 This value can be used by the filter to determine how to process a job.
1003 When combined with the use of the Bounce Queue,
1004 this can be used to reformat jobs before sending to another
1005 printer spooler system.
1006 .SH "PRINTING OPERATIONS"
1007 .PP
1008 When printing is enabled,
1009 the LPD server will create a spool server process to carry out
1010 printing operations.
1011 For each job in the queue,
1012 the spool server process will create a subserver process to carry out
1013 the actual printing operations.
1014 If the subserver process fails,
1015 the server process will initiate recovery operations.
1016 Job will be attempted to be printed until all are done or
1017 a subserver returns an ABORT indication;
1018 the server will then terminate operations.
1019 .PP
1020 The server process normally scans the queue once,
1021 at initiation;
1022 if the spool control file is modified,
1023 usually by using the lpc command,
1024 the spool queue is rescanned.
1025 The overall algorithm for job printing is:
1026 .nf
1027 open the print device;
1028 send some initialization strings;
1029 send a banner to the device;
1030 send the job data files to the device;
1031 send some termination strings;
1032 close the print device;
1033 .fi
1034 .PP
1035 In order to handle the various device requirements,
1036 the subserver process in turn uses 'filter' programs specified
1037 in the printcap entry to carry out the individual steps.
1038 .IP "OF Filter" 5
1039 The 'of' filter is used for
1040 initialization,
1041 banner printing and the termination strings.
1042 It has the peculiar property of suspending itself when sent
1043 a special escape string,
1044 allowing other filters to be used to print the individual job files.
1045 .IP "Data Filters" 5
1046 Each data file in a job has format specified by a lower case character
1047 and an associated filter specified in the printcap file.
1048 For example,
1049 the 'g' format is printed by the 'gf' filter,
1050 and so forth.
1051 By convention,
1052 the 'if' filter is used to print 'f' (ordinary text) and 'l'
1053 (binary) format jobs.
1054 .IP "lp-pipe Filters"
1055 If the printcap device specification has the form
1056 .I "|program"
1057 then the output device is accessed by the specified program.
1058 This allows the program to take care of any required initialization
1059 or communication requirements.
1060 .LP
1061 The following is a concise summary of the actual algorithm
1062 used to print files.
1063 Note that LP stands for the printer device or filter specified by
1064 the 'lp' printcap entry;
1065 OF stands for the 'of' printcap filter;
1066 IF is the default 'if' filter;
1067 BP is the banner printing filter;
1068 and
1069 ?F stands for the filter for data file.
1070 The '??' values stand for entries from the printcap file.
1071 .sp
1072 .nf
1073 .ft CW
1074 .ta 4n +4n +4n +4n +4n +4n +4n +4n +4n
1075 .ps -2
1076 .vs -2
1077 LP = open( 'lp' ); // open device, filter, or network connection
1078 OF = IF = LP; // set defaults
1079 set up accounting according to 'af' entry;
1080 if( 'of' ) OF = filter( 'of' ) -> LP; // make OF filter
1081 if 'as' then record start of job accounting information.
1082 if 'achk' then check for accounting limits.
1083 if( leader on open 'ld' ) `ld` -> OF // send leader
1084 if( FF on open 'fo' ) `fo` -> OF // send leader
1085
1086 // print a banner
1087 // first check to see if required
1088 // and then to see if not suppressed by printcap
1089 // or by user
1090 do_banner =
1091 (always banner 'ab'
1092 || (!suppress banner 'sb' && job has banner ));
1093 if( ! header last 'hl' && do_banner ){
1094 if( banner program 'bp' ){
1095 fork and exec bp to generate banner, but into temp file.
1096 cat temp file -> OF;
1097 } else {
1098 short banner info -> OF;
1099 }
1100 }
1101
1102 // now we suspend the OF filter, use other filters
1103 if( OF != LP ) suspend OF filter;
1104
1105 for each data file df in job do
1106 // send FF between files of job
1107 if( !first job && ! no FF separator 'sf' ){
1108 if( OF != LP ) wake up OF filter;
1109 'ff' -> OF;
1110 if( OF != LP ) suspend OF filter;
1111 }
1112
1113 // get filter for job
1114 format = jobformat;
1115 if( jobformat == 'f' or jobformat = 'l' ){
1116 format = 'f';
1117 }
1118 filter = check pc for filter for format;
1119 ?F = LP; // default - no filter
1120 if( filter ){
1121 ?F = filter( filter ) -> LP;
1122 }
1123
1124 data file -> ?F;
1125 // note: if :direct_read: flag set, filter input
1126 // is directly from the file, otherwise the
1127 // file contents are written to the filter input.
1128
1129 if( ?F != LP ) close( ?F )
1130 endfor
1131
1132 // finish printing
1133
1134 if( OF != LP ) wake up OF filter;
1135 if( header last 'hl' && do_banner ){
1136 if( ! no FF separator 'sf' ){
1137 'ff' -> OF;
1138 }
1139 if( banner program 'bp' ){
1140 fork and exec bp to generate banner, but into temp file.
1141 cat temp file -> OF;
1142 } else {
1143 short banner info -> OF;
1144 }
1145 }
1146
1147 if( ff on close 'fq' ){
1148 'ff' -> OF;
1149 }
1150
1151 if( trailer on close 'tr' ){
1152 tr -> OF;
1153 }
1154
1155 if 'ae' then record end of job accounting information.
1156
1157 if( OF != LP ) close( OF );
1158 close( LP );
1159 .ps +2
1160 .vs +2
1161 .sp
1162 .fi
1163 .PP
1164 When printing or transferring a job to a spool queue fails,
1165 it is retried the number of times specified by the
1166 .I rt
1167 (or
1168 .I send_try )
1169 printcap variable.
1170 A 0 value specifies an infinite number or retries.
1171 When the retry count is exceeded,
1172 then the
1173 .I send_failure_action
1174 printcap variable determines the action to be taken.
1175 The variable can be the values
1176 .I succ ,
1177 .I fail ,
1178 .I abort ,
1179 .I remove ,
1180 .I ignore ,
1181 or
1182 .I hold ,
1183 which will cause the job to be treated as normally completed,
1184 retried,
1185 aborted,
1186 removed,
1187 or ignored and retried at a later time respectively.
1188 These names correspond to the
1189 .I JSUCC ,
1190 .I JFAIL ,
1191 etc. error codes returned by filters.
1192 If the variable has the form
1193 .I |/filter ,
1194 then the filter is run and passed the number of attempts
1195 on the standard input.
1196 The filter must exits with a
1197 .I JSUCC,
1198 .I JFAIL,
1199 etc.,
1200 error code and the server will take the appropriate
1201 action as listed above.
1202 .PP
1203 The print filters normally have their input provided by
1204 a process via a pipe.
1205 However,
1206 if the
1207 .I direct_read
1208 printcap flag is set,
1209 then the filter input is taken directly from the job file.
1210 This is compatible with the vintage BSD method,
1211 but loses the ability to track the job progress.
1212 .PP
1213 After the job print or transfer attempt,
1214 if the job is to be removed and the printcap variable
1215 .I "save_on_error"
1216 is true,
1217 the job will not be removed from the spool queue but only flagged with an error.
1218 The job can then be retried at a later time.
1219 If the job is successfully printed it is usually removed from the spool queue.
1220 However,
1221 if the printcap variable
1222 .I "save_when_done"
1223 is true the job will merely be marked as completed and not removed from the queue.
1224 .SH "FILTERS"
1225 .PP
1226 As described in the previous section,
1227 filters are created to handle output to devices or other filters.
1228 The command line to invoke a filter is generated in the following manner.
1229 .IP 1. 5
1230 The printcap entry or configuration value defining the filter command
1231 is obtained.
1232 .IP 2. 5
1233 The file to be printed or the banner line/file
1234 generated by the banner printer
1235 will be written to STDIN (file descriptor 0) of the filter.
1236 The output device
1237 (or /dev/null if this is not a printing filter)
1238 will be be STDOUT (file descriptor 1) and
1239 STDERR (file descriptor 2) will be connected to the error logging file.
1240 If this is a printing filter,
1241 the error log will be determined by the :af: printcap field
1242 and FD 3 will be opened and set to the either the file,
1243 remote host,
1244 or input of the filter program.
1245 .IP 3. 5
1246 Filter specifications starting with ROOT will be
1247 run as root (EUID = 0).
1248 This can be a serious security loophole
1249 and should only be used as a last resort for specific problems.
1250 .IP 4. 5
1251 The options for the filter command line will be replaced by appropriate
1252 values.
1253 Option specifications have the form $[0| ][-]X.
1254 .\" Option specifications have the form $[0| ][-][']X.
1255 The default option expansion has the form $X -> -X'value';
1256 the form $0X or $(space)X adds a space after the -X, i.e.- $0X -> -X 'value';
1257 the form $-X suppresses the -X, i.e. - $-X -> value.
1258 .\" the form $-X suppresses the -X, i.e. - $-X -> 'value';
1259 .\" and the form $'X suppresses the quotes around the value.
1260 .\" Note that the 0,-, and ' can be combined. For example, $-'X -> value.
1261 The options will be expanded as follows:
1262 .RS
1263 .sp
1264 .nf
1265 .ta \w'Key 'u +4n +4n
1266 Key Value
1267 a Accounting file (printcap 'af' entry)
1268 b Job size, i.e.- total data file size, in bytes
1269 c if binary (format 'l') expands to -c
1270 d Control directory
1271 e job data file
1272 f original print file name (control file N field)
1273 h Control file hostname
1274 i Control file indent (I) field
1275 j job number from control file name
1276 k Control file name
1277 l printcap Page length (pl) value
1278 m printcap Cost factor (co) value
1279 n Control file user logname (P) field
1280 p Remote Printer name for forwarded jobs
1281 r Remote Host name for forwarded jobs
1282 s printer Status file (ps) value
1283 t current time in simple format
1284 w printcap Page width (pw) value
1285 x printcap x dimension (px) value
1286 y printcap y dimension (py) value
1287 F data file format character
1288 P Printer name
1289 S printcap Comment tag (cm) value
1290 Upper Case control file line starting with letter
1291 Digit control file line starting with digit
1292 .sp
1293 .RE
1294 .fi
1295 .IP 5. 5
1296 The options specified by the filter_options (for none OF filters)
1297 or of_filter_options (for the OF filter) will
1298 be appended to the command line and expanded.
1299 To suppress adding options,
1300 you can use the form '-$ filter',
1301 i.e. - of=-$/bin/cat.
1302 If the 'bkf' (backwards compatible filter options)
1303 printcap flag is set,
1304 the of filter is given the options specified by
1305 bk_of_filter_options and other filters those by
1306 bk_filter_options.
1307 The following shows the various combinations possible,
1308 and typical values for the options.
1309 .RS
1310 .sp
1311 .nf
1312 .ta \w'default_options 'u +4n +4n +4n
1313 Options
1314 filter_options $C $F $H $J $L $P $Q $R $Z $a $c $d $e $f $h $i \e
1315 $j $k $l $n $s $w $x $y $-a
1316 bk_filter_options $P $w $l $x $y $F $c $L $i $J $C $0n $0h $-a
1317 bk_of_filter_options $w $l $x $y
1318 .RE
1319 .IP 6. 5
1320 A printing filter which executes correctly and completely should
1321 exit with a 0 error status.
1322 A nonzero error status will be interpreted as follows:
1323 .RS
1324 .nf
1325 .ta 9n +4n +4n
1326 JFAIL 32 failed - retry later
1327 JABORT 33 aborted - do not try again, but keep job
1328 JREMOVE 34 failed - remove job
1329 .RE
1330 .fi
1331 .PP
1332 The JFAIL will cause the job to be retried at a later time.
1333 A limit can be placed on the number of retries using the
1334 :rt: or :send_try: printcap entry.
1335 A retry value of 0 will cause infinite retries.
1336 The JABORT indicates serious problems and will cause printing operations
1337 on the job to stop until restarted by operator intervention.
1338 The JREMOVE status indicates problems,
1339 and the job should be removed from the spool queue.
1340 .PP
1341 The environment variables for filters are highly restricted,
1342 due to the possibility for abuse by users.
1343 The following variables are set:
1344 .IP "USER and LOGNAME" 5
1345 user name or daemon name.
1346 .IP "LOGDIR" 5
1347 home directory of user or daemon.
1348 .IP PATH 5
1349 from the
1350 .I filter_path
1351 configuration variable.
1352 .IP LD_LIBRARY_PATH 5
1353 from the
1354 .I filter_ld_path
1355 configuration variable.
1356 .IP SHELL 5
1357 set to
1358 .I /bin/sh
1359 .IP IFS 5
1360 set to blank and tab.
1361 .IP TZ 5
1362 the TZ environment variable.
1363 .IP SPOOL_DIR 5
1364 the spool directory for the printer
1365 .IP CONTROL_DIR 5
1366 the control directory for the printer
1367 .IP PRINTCAP_ENTRY 5
1368 the printcap entry for the printer
1369 .IP CONTROL 5
1370 the control file for the print job
1371 .IP "pass_env environment variables" 5
1372 Values of environment variables listed in the pass_env configuration variable.
1373 .SH ACCOUNTING
1374 .PP
1375 The LPRng software provides several methods of performing accounting.
1376 The printcap
1377 af
1378 (accounting field),
1379 as and ae (accounting start and end),
1380 and
1381 achk (accounting check)
1382 provide a basic set of facilities.
1383 The
1384 af field specifies a file,
1385 filter,
1386 or TCP network connection to an accounting server.
1387 If af has the form
1388 .ft CW
1389 |filter
1390 .ft R
1391 or
1392 .ft CW
1393 |-$ filter
1394 .ft R
1395 then a filter will be started and all accounting information will
1396 be sent to the filter.
1397 The first form passes the filter the command line options specified by the
1398 filter_options configuration variable and the second suppresses option passing.
1399 If af has the form
1400 .ft CW
1401 host%port
1402 .ft R
1403 then a TCP connection will be opened to the port on the specified host
1404 and accounting information sent there.
1405 All other forms will be treated as a pathname relative to the
1406 queue spool directory.
1407 .PP
1408 If af specifies a file,
1409 then the accounting information is appended to an existing file;
1410 the accounting file will not be created.
1411 .PP
1412 When af specifies a filter or network connection and the
1413 achk flag is set,
1414 then after writing the initial accounting information (see as printcap field below)
1415 the server will wait for a reply of the form
1416 ACCEPT from the filter or server.
1417 If not received,
1418 the job will not be printed.
1419 .PP
1420 The as (accounting start) and ae (accounting end) fields can specify
1421 a string to be printed or a filter.
1422 Options in the string will be expanded as for filters,
1423 and the strings printed to either the accounting information destination.
1424 If the as field specifies a filter,
1425 then the print server will wait for the filter to exit
1426 before printing the job.
1427 If the exit status is 0 (successful),
1428 the job will be printed.
1429 A non-zero JREMOVE status will remove the job,
1430 while any other status will terminate queue printing operations.
1431 After printing the job,
1432 the ae filter will be started and the server will wait for it to complete
1433 before printing the next job.
1434 .PP
1435 The as and ae filters will have STDOUT set to the printing device and or filter,
1436 and the STDERR set to the error log file for the print queue,
1437 and file descriptor 3 set to the destination specified by the
1438 af field.
1439 .PP
1440 As a convenience, all format filters for printing will be
1441 started with file descriptor 3 set to the destination
1442 (file or filter)
1443 specified by the printcap af field.
1444 This allows special filters which can query devices for
1445 page counts to pass their information directly to an accounting
1446 program.
1447 The descriptor will READ/WRITE,
1448 allowing filters to query the accounting program and/or update
1449 the information directly.
1450 .SH "LOGGING INFORMATION"
1451 .PP
1452 In order to provide a centralized method to track job status and information,
1453 the printcap/configuration variable
1454 logger_destination enable the send of status and other information to a remote
1455 destination.
1456 The logger_destination value has the form
1457 .RS
1458 .nf
1459 .L host[%port][,protocol]
1460 .ti -4n
1461 Examples:
1462 .L taco%451,UDP
1463 .L dickory%2001,TCP
1464 .RE
1465 .fi
1466 .br
1467 where host is the host name or IP address,
1468 port is an optional port number,
1469 and protocol is an optional protocol type such as UDP or TCP.
1470 The configuration variables
1471 default_logger_port and
1472 default_logger_protocol can be used to override
1473 the default port number (2001) and protocol (UDP)
1474 to be used if none is specified.
1475 Logging information has the format below.
1476 .RS
1477 .nf
1478 IDENTIFIER jobid [PRINTER name] at \fItimestamp\fP \e
1479 STATUS | TRACE | FILTER_STATUS PID nnn
1480 [ status information]
1481 .RE
1482 .fi
1483 .PP
1484 The status information format consists of an identifier line,
1485 followed by a specifier of the status type.
1486 The logging information entry is terminated by a
1487 line with a single period on it.
1488 Lines with a starting period have the period duplicated.
1489 .SH AUTHENTICATION
1490 .PP
1491 Rather than building authentication facilties into LPRng,
1492 an interface to authentication programs is defined,
1493 and will be used as follows.
1494 The printcap and configuration entries
1495 .I auth,
1496 .I auth_client_filter,
1497 .I auth_forward,
1498 .I auth_forward_id,
1499 .I auth_forward_filter,
1500 .I auth_receive_filter,
1501 and
1502 .I auth_server_id
1503 entries control authentication.
1504 The
1505 .I auth
1506 value specifies the type of authentication to be used
1507 for client to server authentication.
1508 Typical values would be
1509 kerberos, md5, etc.
1510 If the authentication type is not built-in,
1511 the client programs use the
1512 .I auth_client_filter
1513 program to perform authentication.
1514 When a server gets and an authentication request,
1515 it will use the
1516 .I auth_receive_filter
1517 program to perform authentication.
1518 The
1519 .I auth_server_id
1520 is the remote server id used when a client
1521 is sending jobs to the server
1522 or when the server is originating a request.
1523 When a server forwards a request,
1524 it uses
1525 .I auth_forward
1526 value to determine if authentication is to be done,
1527 and the
1528 .I auth_forward_id
1529 as the destination server id.
1530 .de NP
1531 .fi
1532 .in 0
1533 .PP
1534 .br
1535 .in +4n
1536 .ti -4n
1537 \\n(nP.\ \ \c
1538 .nr nP \\n(nP+1
1539 ..
1540 .de sP
1541 .fi
1542 .PP
1543 .br
1544 .in +4n
1545 ..
1546 .de np
1547 .nr nP 1
1548 ..
1549 .SH "Client To Server Authentication"
1550 .np
1551 .NP
1552 The client will open a connection to the server
1553 and sends a command with the following format.
1554 The REQ_SECURE field in the command corresponds to the one-byte
1555 command type used by the LPR protocol.
1556 .RS
1557 .nf
1558 Commands:
1559 .ta 4n +4n
1560 \eREQ_SECUREprinter C user\en
1561 Print job transfers:
1562 \eREQ_SECUREprinter C user controfilename\en
1563 .RE
1564 .fi
1565 .NP
1566 On reception of this command, the server will send a one byte
1567 success code as below. An error code may be followed by additional
1568 error information. The values used by LPRng include:
1569 .RS
1570 .nf
1571 .ta 16n +4n +4n
1572 ACK_SUCCESS 0 success, no error
1573 ACK_STOP_Q 1 failed; no spooling to the remote queue
1574 ACK_RETRY 2 failed; retry later
1575 ACK_FAIL 3 failed; job rejected, no retry
1576 .RE
1577 .fi
1578 .NP
1579 If there is an error the connection will be terminated.
1580 The server will then start an authentication process, and provide
1581 the following open file descriptors for it. The authenticator
1582 process will run as the UID of the server (i.e.- usually daemon).
1583 .RS
1584 .nf
1585 .ta 6n +8n +4n
1586 FD Options Purpose
1587 0 R/W socket connection to remote host (R/W)
1588 1 W pipe or file descriptor
1589 for information for server
1590 2 W error log
1591 3 R pipe or file descriptor
1592 for responses to client
1593 .RE
1594 .sP
1595 The command line arguments will have the form:
1596 .RS
1597 .nf
1598 program -S -Pprinter -nuser -Rserver_user -Ttempfile
1599 .RE
1600 .sP
1601 The printer and user information will be obtained from the
1602 command line sent to the server.
1603 The authenticator can create additional temporary or working
1604 files with the pathnames tempfile.ext; these should be deleted
1605 after the authentication process has been completed.
1606 .NP
1607 After receiving \eACK_SUCCESS, the client starts an authenticator
1608 process, and provides the following open file descriptors for
1609 it. The authenticator process will run UID user.
1610 .RS
1611 .nf
1612 .ta 6n +8n +4n
1613 FD Options Purpose
1614 0 R/W socket connection to remote host (R/W)
1615 1 W pipe or file descriptor
1616 for responses to client
1617 2 W error log
1618 .RE
1619 .sP
1620 The command line arguments will have the form:
1621 .RS
1622 .nf
1623 program -C -Pprinter -nuser -Rserver_user -Ttempfile
1624 .RE
1625 .fi
1626 .NP
1627 The authenticator can create additional temporary or working
1628 files with the pathnames tempfile.ext; these will be deleted
1629 after the authentication process has been completed.
1630 The client authenticator will be running as the client user.
1631 .NP
1632 After exchanging authentication information,
1633 the client authenticator will transfer the contents of the
1634 temporary file to the server authenticator, using FD 0. It will
1635 then wait for reply status on FD 0. If the transfer step fails,
1636 or there is no reply status of the correct format, the client
1637 authenticator will print any received information on FD 1,
1638 error information on FD 2, and then exit with error code JFAIL.
1639 .NP
1640 After receiving the files on FD 0, the server authenticator
1641 will perform the required authentication procedures and leave
1642 the results in tempfile. The server authenticator will write
1643 the following to FD 1, for use by the server:
1644 .RS
1645 .nf
1646 authentication_info\en
1647 .RE
1648 .sP
1649 If the transfer step or authentication fails, then the server
1650 will write an error message to FD 2 and exit with error code
1651 JFAIL.
1652 The server will use this authentication information to
1653 determine if the remote user has permission to access the system.
1654 .NP
1655 The server authentication process will read input from FD 3
1656 until and end of file,
1657 and then proceed to transfer the input to the client authenticator.
1658 If the data transfer fails, then the process will exit with
1659 error code JFAIL, otherwise it will exit with error code JSUCC.
1660 .NP
1661 The client authenticator will read the status information from
1662 FD 0, and after performing authentication will write it to FD 1.
1663 If data transfer or authentication fails, the authenticator
1664 will write an error message to FD 2 and exit with error code
1665 JFAIL, otherwise it will exit with error code JSUCC.
1666 .SH "Server to Server Authentication"
1667 .np
1668 .PP
1669 The Server to Server authentication procedure is used by one server
1670 to forward jobs or commands to another server. It should be noted
1671 that this forwarding operation puts an implicit trust in the security
1672 of the client to server to server chain. In the description below,
1673 src and dst are the userid of the source and destination servers
1674 respectively.
1675 .NP
1676 The originating host takes the part of the client, and will
1677 transfer a job acting like the client. The initial information
1678 transfer from the originating (src) server will have the format:
1679 .RS
1680 .nf
1681 .ta 4n +4n
1682 Commands:
1683 \eREQ_SECUREprinter F user\en
1684 Print job transfers:
1685 \eREQ_SECUREprinter F user controfilename\en
1686 .RE
1687 .sP
1688 After receiving a 0 acknowledgment byte,
1689 the src server will invoke its authenticator with the arguments
1690 below.
1691 The forward_user value will default to the
1692 server_user value if not explicitly provided.
1693 .RS
1694 .nf
1695 .ta 4n +4n
1696 .L
1697 program -C -Pprinter -nserver_user \e
1698 -Rforward_user -Ttempfile
1699 .RE
1700 .NP
1701 On the destination server the authenticator is invoked with the arguments:
1702 .RS
1703 .nf
1704 .ta 4n +4n
1705 .L
1706 program -S -Pprinter -nserver_user \e
1707 -Rforward_user -Ttempfile
1708 .RE
1709 .sP
1710 The authentication is performed to determine that the transfer was
1711 between the two servers, rather than the user to server.
1712 .SH "KERBEROS AUTHENTICATION"
1713 .PP
1714 As a convenience,
1715 Kerberos 5 authentication has been built into the LPD clients and
1716 servers.
1717 If you are not familiar with Kerberos,
1718 then you should obtain other documentation and/or assistance
1719 before attempting to use this.
1720 The following facilities/configuration values are used to
1721 support Kerberos.
1722 .PP
1723 A Kerberos principal is the name used for authentication purposes
1724 by Kerberos.
1725 For example,
1726 user principals have the form user@REALM;
1727 for example,
1728 [email protected].
1729 Services and/or servers have the form service/host@REALM;
1730 for example,
1731 the lpd server on dickory would have the form:
1732 .ti +5n
1733 lpr/[email protected]
1734 .PP
1735 User to server authentication process will use the user's principal
1736 name,
1737 and generate a service name for the server.
1738 The name generation is controlled by the following configuration
1739 and/or printcap values.
1740 .IP service
1741 The name of the service to be used to identify the service.
1742 This is usually "lpr".
1743 .IP kerberos_keytab
1744 The location of the server keytab file.
1745 The keytab file corresponds to the user password,
1746 and must be considered a security risk.
1747 It should be owned by the LPD server user,
1748 and readable/writable only by the server.
1749 .IP kerberos_life
1750 The lifetime of the authentication ticket used by the server.
1751 This usually defaults to 10 hours.
1752 .IP kerberos_renew
1753 The renewal time of the ticket.
1754 .PP
1755 In addition to the default values,
1756 an explicit server principal can be specified in the printcap
1757 file using the kerberos_server_principal
1758 This allows cross domain authentication to be done.
1759 .PP
1760 When setting up Kerberos authentication,
1761 you will need to establish principals for each server,
1762 and to distribute and install the keytab files on each server.
1763 .SH "AUTHENTICATION PERMISSIONS"
1764 .PP
1765 The following permissions tags are available to check on authentication
1766 procedures.
1767 .RS
1768 .nf
1769 .ta 4n +12n +4n +4n +4n +4n
1770 AUTH=[NONE,USER,FWD] - authentication
1771 AUTH=NONE - no authentication
1772 AUTH=USER - authentication from a client
1773 AUTH=FWD - forwarded authentication from a lpd server
1774 AUTHTYPE=globmatch
1775 AUTHUSER=globmatch
1776 FWDUSER=globmatch
1777 .RE
1778 .fi
1779 .np
1780 .NP
1781 The AUTH tag can be used to determine the type of authentication
1782 being done.
1783 The AUTHTYPE tag can be used to match the authentication type
1784 being used or requested by the client or remote server.
1785 The authentication process returns an authentication identifier
1786 for the user;
1787 this information can be matched by the AUTHUSER tag.
1788 .NP
1789 For a command sent from a client or forwarded from a server,
1790 AUTHUSER matches the auth_user_id provided for the user when
1791 sent to a server.
1792 (This information will be forwarded by a remote server).
1793 For a forwarded command,
1794 FWDUSER refers to the authentication information
1795 for the server doing the forwarding.
1796 .NP
1797 For example, to reject non-authenticated operations, the following
1798 line could be put in the permissions file.
1799 .RS
1800 .nf
1801 REJECT AUTH=NONE
1802 .RE
1803 .NP
1804 To reject server forwarded authentication as well, we use REJECT AUTH=NONE,FWD.
1805 If a remote server with name
1806 .I serverhost
1807 has id information FFEDBEEFDEAF, then the
1808 following will accept only forwarded jobs from this server.
1809 .RS
1810 .nf
1811 ACCEPT FWDUSER=FFEDBEEFDEAF REMOTEHOST=serverhost
1812 REJECT AUTH=FWD
1813 .RE
1814 .fi
1815
1816 .SH ENVIRONMENT
1817 The lpd action can also be manipulated by using environment variables.
1818
1819 .TP
1820 .B LPR_TMP
1821
1822 .SS Authentication
1823 .TP
1824 .B MD5KEYFILE
1825 Used for md5 signated file transmission
1826
1827 .SH FILES
1828 The files used by LPRng are set by values in the
1829 printer configuration file.
1830 The following are a commonly used set of default values.
1831 .nf
1832 .ta \w'/var/spool/lpd/printcap.<hostname> 'u
1833 /etc/lprng/lpd.conf LPRng configuration file
1834 ${HOME}/.printcap user printer description file
1835 /etc/printcap printer description file
1836 /etc/lprng/lpd.perms permissions
1837 /var/run/lprng/lpd lock file for queue control
1838 /var/spool/lpd spool directories
1839 /var/spool/lpd/QUEUE/control queue control
1840 /var/spool/lpd/QUEUE/log trace or debug log file
1841 /var/spool/lpd/QUEUE/acct accounting file
1842 /var/spool/lpd/QUEUE/status status file
1843 .fi
1844 .SH "SEE ALSO"
1845 .BR lpd.conf (5),
1846 .BR lpc (8),
1847 .BR checkpc (8),
1848 .BR lpr (1),
1849 .BR lpq (1),
1850 .BR lprm (1),
1851 .BR printcap (5),
1852 .BR lpd.perms (5),
1853 .BR pr (1).
1854 .SH "AUTHOR"
1855 Patrick Powell <[email protected]>.
1856 .SH DIAGNOSTICS
1857 Most of the diagnostics are self explanatory.
1858 If you are puzzled over the exact cause of failure,
1859 set the debugging level on (-D5) and run again.
1860 The debugging information will
1861 help you to pinpoint the exact cause of failure.
1862 .SH "HISTORY"
1863 LPRng is a enhanced printer spooler system
1864 with functionality similar to the Berkeley LPR software.
1865 The LPRng developer mailing list is [email protected];
1866 subscribe by visiting
1867 .B https://lists.sourceforge.net/lists/listinfo/lprng-devel
1868 or sending mail to
1869 .B [email protected]
1870 with
1871 the word
1872 .I subscribe
1873 in the body.
1874 .br
1875 The software is available via
1876 .B http://lprng.sourceforge.net