 ***************************************************************************
 * LPRng - An Extended Print Spooler System
 *
 * Copyright 1988-1995 Patrick Powell, San Diego, CA
 *     papowell@astart.com
 * See LICENSE for conditions of use.
 *
 ***************************************************************************
 * MODULE: INFORMATION
 * PURPOSE: Overview of Software
 * INFORMATION,v 3.4 1997/12/16 15:06:06 papowell Exp
 **************************************************************************/

The LPRng software has evolved from the Berkeley LPR software.

Berkeley LPR
  -> <hacked LPR>        - University of Waterloo, 1986 for printers
  -> PLP Version 3.0     - University of Minnesota 
                           Note: this version had some derived code
                           in it that did not allow it to be CopyLeft
  -> PLP Version 4.0     - Justin Mason <jmason@iona.ie>
                           PLP hacked, ported, and bug fixed for problems
                           that are truly amazing.
  -> LPRng Version Alpha Minus
                         - Trial version of software

LPRng Functionality

The LPRng functionality is based on the Berkeley LPD.  The implementation
of that functionality is radically different.  The following core
programs and databases are used:

                Databases Used
Programs    config printcap perms

lpd         yes    yes      yes
lpr          *      *       no
lprm         *      *       no
lpq          *      *       no
lpc          *      *       no
checkpc     yes    yes      yes

LPD- Print Spooler Server

LPD uses a configuration file (default:  /etc/lpd.conf,
/usr/etc/lpd.conf, /usr/spool/lpd/lpd.conf) to set up the defaults for
operation.  One of the parameters is the location of the printcap
files,  which contain database information about each printer spool.
LPD operates only on printers which have a spool directory where files
for printing are stored.

lpr, lprm, lprq, lpc - Client programs

These programs forward requests to the LPD server over a TCP/IP
connection.  The are 'lightweight' in that you do not need to have
a configuration database or printcap database in order to use them.
For example,  the command
  lpr -Ppr@host file
will open a connection to the LPD server on host and send a print
job for printer 'pr'. This greatly simplifies database configuration
and printer sharing.  In addition,  the various client programs
do not require ROOT permissions,  and run as regular users processes.
In a later version of LPRng,  end to end authentication will be
added by using an encryption based method such as Kerberos or PGP.

The checkpc program performs database consistency checking.
The program greatly simplifies administration of the print spooler:
 checkpc -f (fix)  fixes permissions
 checkpc -r -A time  removes 'stale' jobs and junk files
 checkpc -t len    truncates log files


Configuration Files

The configuration files have the format shown below:  a keword
followed by a value.  The keywords are case insensitive, and
'-' or '_' can be used interchanably.  The lpd.conf man page
documents the meanings and uses of the various configuration entries.
Unrecognized entries are ignored.

	default_printer          lp@astart.com
	default_banner_printer   /tmp/LPD/lpbanner
	lockfile                 /tmp/LPD/lpd.lock.%H
	logfile                  /tmp/LPD/lpd.log.%H
	lpd_port                 4000
	originate_port           2000 3000
	# try using the filter printcap access
	# replace the 'printcap_path' with the filter specification
	printcap_path            /tmp/LPD/printcap.%H
	#printcap_path            |/tmp/LPD/dbserver /tmp/LPD/printcap.db.%H
	#perms_path       /tmp/LPD/printer_perms.%H
	perms_path         |/tmp/LPD/dbserver /tmp/LPD/printer_perms.db.%H
	user                     papowell
	group                    0
	# test include facility
	include                  /tmp/LPD/common.conf

Note that a file include facility is available; all paths must be absolute.

Printcap Files

Each entry in a printcap file defines a printer information entry.
Some information entries simply specify the location of an printer
while others specify its spool queue name and other attributes.

The following is a sample of a printcap file suitable for use by
client programs:

	#printer 1
	pr1:lp=pr1@host
	# printer 2
	pr2
    |postscript
    |lj4
    |Laserjet in Office
    #use the multiline form
	:rp=pr2
	:rm=host
	:tc=genpr
    #genpr information
    genpr:sd=/usr/spool/LPD/$P.$H

The lp=printer@host form is equivalent to rp=printer:rm=host.
The lp field has precedence over the rp/rm fields.
The above example also shows the relaxed form of the printcap files.
Each entry starts with a printer name,  followed by a set of
alternate names,  followed by information fields.

The 'tc' information field acts as an 'include', but for printcap
information.  For example,  the pr2 entry above would consist of
the information in the pr2 together with information in the genpr
entry.  Printcap information is processed in the order it is
read from the printcap file,  and a variable value is set by the
last processed entry.

The sd or 'spool directory' field is given special handling to
allow a generalized form of printcap entry to be used.  The
string is scanned for tokens of the form $X, and these are replaced
with the following information:
  $P - printer name
  $H - fully qualified host name
  $h - short host name

In addition to the spool directory where job files are placed,
each printer can have a 'control directory' where control information
is placed.  This, by default, is the same directory as the spool directory,
but on systems where security and NFS mounting of spool direcotories
is a problem,  this can provide a higher level of security.

The LPD server (i.e.- not the client programs) searches the control directory
for a 'printcap' file which can be used to provide additional information.
spooling information.

For various historical reasons,  some sites require the use of
a central shared database system such as HESIOD or NIS (Yellow Pages).
Rather than build access to these systems into the LPRng code,
a more general access systems was provided.  Instead of
a printcap file,  a 'printcap filter' can be specified which will
be called to access printcap information.  This filter can then be
programmed to meet local site requirements.

Permissions Files

Access to various LPRng facilities is done by the server (LPD) using a
permissions file.  Permissions are checked by the use of 'keys' and
matches. Here is a sample permissions file:

# Permissions file
# reject everything unless accepted
DEFAULT REJECT
# keep others off our site, or thier jobs as well
#
REJECT SERVICE=* NOT IP=130.0.0.56/255.255.0.0
# allow this person control when he is coming from a privileged port
ACCEPT SERVICE=C REMOTEUSER=papowell HOST=astart1.astart.com PORT=0-1023
#
ACCEPT REMOVTEHOST=*.ee.astart.com 

For each of the following LPR activities,  the following keys
have a value

## Key          Match Connect Job   Job    LPQ  LPRM  LPC
##                            Spool Print
## SERVICE      S     'X'     'R'   'P'    'Q'  'M'   'C,S'
## USER         S     -       JUSR  JUSR   JUSR JUSR  JUSR
## HOST         S     RH      JH    JH     JH   JH    JH
## GROUP        S     -       JUSR  JUSR   JUSR JUSR  JUSR
## IP           IP    RIP     JIP   JIP    RIP  JIP   JIP
## PORT         N     PORT    PORT  -      PORT PORT  PORT
## REMOTEUSER   S     -       JUSR  JUSR   JUSR CUSR  CUSR
## REMOTEHOST   S     RH      RH    JH     RH   RH    RH
## REMOTEGROUP  S     -       JUSR  JUSR   JUSR CUSR  CUSR
## REMOTEIP     IP    RIP     RIP   JIP    RIP  RIP   RIP
## CONTROLLINE  S     -       CL    CL     CL   CL    CL
## PRINTER      S     -       PR    PR     PR   PR    PR
## FORWARD      V     -       SA    -      -    SA    SA
## SAMEHOST     V     -       SA    -      SA   SA    SA
## SAMEUSER     V     -       -     -      SU   SU    SU
## SERVER       V     -       SV    -      SV   SV    SV
## 
## KEY:
##   JH = HOST          host in control file
##   RH = REMOTEHOST    connecting host name
##   JUSR = USER        user in control file
##   CUSR = REMOTEUSER  user from control request
##   JIP= IP            IP address of host in control file
##   RIP= REMOTEIP      IP address of requesting host
##   PORT=              connecting host origination port
##   CONTROLLINE=       pattern match of control line in control file
##   FW= IP of source of request = IP of host in control file
##   SA= IP of source of request = IP of host in control file
##   SU= user from request = user in control file
##   SA= IP of source of request = IP of server host
## 
## Match: S = string with wild card, IP = IPaddress[/netmask],
##   N = low[-high] number range, V = exact value match.
## SERVICE: 'X' - Connection request; 'R' - lpr request from remote host;
##    'P' - print job in queue; 'Q' - lpq request, 'M' - lprm request;
##    'C' - lpc spool control request; 'S' - lpc spool status request
## NOTE: when printing (P action), the remote and job check values
##   (i.e. - RUSR, JUSR) are identical.

A permission line consists of list of tests and an a result value
If all of the tests succeed,  then a match has been found and the
permission testing completes with the result value.  You use the
DEFAULT reserved word to set the default ACCEPT/DENY result.
The NOT keyword will reverse the sense of a test.

Each test can have one or more optional values separated by
commas. For example USER=john,paul,mark has 3 test values.

The Match type specifies how the matching is done.
S = string type match - string match with glob.
    Format:  string with wildcards (*)
             * matches 0 or more chars
    Character comparison is case insensitive.
    For example - USER=th*s matches uTHS, This, This, Theses

IP = IP address and submask.  IP address must be in dotted form.
     Format: x.x.x.x[/y.y.y.y]  x.x.x.x is IP address
             y.y.y.y is optional submask, default is 255.255.255.255
     Match is done by converting to 32 bit x, y, and IP value and using:
        success = ((x ^ IP ) & y) == 0   (C language notation)
    i.e.- only bits where mask is non-zero are used in comparison.
    For example - IP=130.191.0.0/255.255.0.0 matches all address 130.191.X.X
         
N = numerical range  -  low-high integer range.
     Format: low[-high]
     Example: PORT=0-1023 matches a port in range 0 - 1023 (privileged)

The SAMEUSER and SAMEHOST are options that form values from information
in control files or connections.

Example Permissions

Reject connections all users not on subnet 130.191.0.0
  REJECT SERVICE=X NOT IP=130.191.0.0/255.255.0.0
Do not allow anybody but root on astart1.astart.com to use control
  facilities.  The first line accepts the user, second rejects
  all others
  ACCEPT SERVICE=C HOST=astart1.astart.com USER=papowell
  REJECT SERVICE=C

Allow root on talker.astart.com to control printer hpjet
  ACCEPT SERVICE=C HOST=talker.astart.com PRINTER=hpjet USER=root

Do not allow forwarded jobs
  REJECT FORWARD

#start all
DEFAULT ACCEPT
#end all
#start t1
PRINTER=t1 ACCEPT
#end t1
