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