INSTALLATION:

*   cd to src and run the "configure" script found therein, as
    follows:

	cd src
	sh configure

    If you want to compile in a separate directory from the sources,
    invoke the "configure" script as follows:

	[path-to-src]/configure -srcdir=[path-to-src]

    Configure is generated by GNU autoconf 2.0, so if you know
    what a config.cache file is and you have one, it'll use it.
    If you get the message:

	configure: symbol too long

    it means your shell has an arbitrary limit on string length, and
    you should try running "configure" with a different shell, such as
    /bin/ksh (if available).

*   Due to PLP's use of ioctls, "configure" may decide to use
    'gcc -traditional'. However, it seems that, due to PLP's use of
    varargs/stdargs, this causes coredumps and strange behaviour on
    some systems, notably Suns running SunOS 4.1.x. Due to this,
    "configure" will try to find 'unproto' in order to avoid using
    'gcc -traditional'.

    If you don't have unproto installed, try compiling PLP anyway -- it
    may work. However, if the PLP utilities dump core or behave
    strangely, especially when you use the -D switch, you should fetch
    and install unproto, "make clean", and reconfigure and recompile
    PLP from scratch.

*   "configure" will generate some files: Makefile and config.h .
    Edit the Makefile, and change the variables as you see fit:
    install locations, plp config file location, printcap file lookup
    methods, etc.

    "configure" may set the wrong defaults for your platform, notably
    those that deal with terminal settings, set-uid handling,
    and filesystem free space queries. These can be overridden
    in the Makefile. Check the file "HINTS" for hints on compiling
    PLP on such platforms.

    If you change the CC line in the Makefile, you may also need
    to change the lines for HAVE_INLINE and HAVE_CONST in config.h
    appropriately -- a symptom of this is "undefined keyword" errors
    in 'lp.h'.

*   If you wish to use the GNU Readline library with lpc to provide
    command-line editing, history, etc., get a copy of
    readline-2.0.tar.gz (or a later version), extract its contents, and
    mv them into the "src" directory of PLP, eg:

	gunzip -cd readline-2.0.tar.gz | tar xf -
	mv readline-2.0 src/readline

    Then uncomment the following entries in the Makefile:
    READLINE_LIBRARY and READLINE_CFLAGS .

*   It is STRONGLY suggested that you change CONFIG_FILE to point to a
    non-standard location, such as /tmp/plp.test.cf, if you are already
    running PLP; this allows you to test PLP with a non-standard port
    number, directories, etc. in order to avoid interfering with the
    currently-running version.
   
    If you want to test PLP without using root (ie. superuser)
    permissions, edit the Makefile and uncomment the declaration
    of SUID_CFLAGS. This allows you to run the test procedures
    as yourself, instead of using the "root" and "daemon" users.

*   Run make to cook it all up. If you are using the GNU Readline
    library, and some dependency problems arise while compiling
    the readline code, try using "gmake"; it worked for me,
    at least. ;)
    
    Once that's done, copy the file "test/plp.conf" to the CONFIG_FILE
    location. This version uses /tmp/printcap.{hostname} and
    /tmp/printer_perms.{hostname} and doesn't use the default
    "printer" TCP port. It is a safe way to debug this stuff
    without interfering with the currently-running system lpd.

    Note that SunOS 4.1.x and Solaris 2.x do not support file
    locking in tmpfs filesystems, so if /tmp is a tmpfs filesystem
    and you use /tmp/printcap.{hostname} for the test version,
    things will not work (PLP's lpd locks the printcap file).
    Try a different tmp directory, or your home dir, or something.

*   If you get the warning:

	couldn't get fully-qualified hostname: set `domain-name' in plp.conf

    you should add a "domain-name" directive to the plp.conf file.
    The `domain-name' directive should contain the string necessary to
    make your hostname fully-qualified, eg. if the host "class"
    has a fully-qualified domain name of "class.iona.ie", the
    `domain-name' line should look like this:

	domain-name	iona.ie

    This will probably only affect you if you want to use your
    network's domain name in printer_perms permission lookups, but
    you may as well add one anyway -- it's only used if PLP cannot
    work out your domain any other way. This happens on Solaris 2.x
    systems, unless the fully-qualified name is used in /etc/hosts.

*   Read the test procedures in ./doc/PLP, and try them out.
    The test directory has a set of files and printcaps that
    can be used for test purposes.

*   Still feeling brave?  You should save the existing version of LPD;
    the backup directory has a set of programs (shell scripts) to do this.
    They'll also save the "lp" and "lpstat" binaries, should they exist
    on your system.

	cd ../backup
	save.lpr

    If you want to restore things quickly,  you can do:

	cd ../backup
	restore.lpr <date of save file>

    and you are back to where you were before.

*   Making a working version of PLP:

    cd back into your compile directory (sunos4, sol2, whatever), edit
    the Makefile to change CONFIG_FILE to /etc/plp.conf (or whatever
    you want yourself), comment out SUID_CFLAGS, and do:

	make clean
	make all

*   Print out a copy of the PLP Manual, found in "doc/PLP/manual.ps".
    This explains the PLP functionality in great detail, and will
    more than likely broaden your knowledge of the standard LPD
    functionality as well!

*   Set up a plp.conf file; a full set of defaults is provided, but one
    _must_ be installed in the location specified in the Makefile.
    Anyway, it's handy being able to use more than one printcap
    file, change the paths, and so on. The manual page plp.conf(5) will
    give you all you need to know, but for now, you only need to set
    "printcap-path" and "printer_perms-path"; everything else is set
    to the defaults, which'll work well enough.

*   Set up printcap and printer_perms files. A simple printer_perms
    file can be found in test/printer_perms.proto, and it'll get you
    up to speed until you get around to RTFMing.

*   Check your printer filters. PLP has a vastly expanded
    set of command-line options that extend the BSD set greatly, but
    some filters may not expect unsupported command-line options.
    Filters are now passed lots of extra useful information like the
    print job's filename. You may want to alter some of your printer filters
    to take advantage of this, if you use any. A compatibility wrapper
    is included if you don't want to alter them. See chapter 7 of
    the PLP Manual for more details.

*   If you intend to print from a PLP machine to a non-PLP lpd on
    another machine, check out that queue now using lpr.
    If you have trouble printing either to or from a non-PLP lpd,
    see if the file OTHER-LPDS in the PLP base directory can help.

    If it can't, try setting the "bk" (backward compatability)
    flag in the printcap -- some lpd's are fussy about control files.
    If you find a solution, drop me a line and I'll update the
    OTHER-LPDS file with your advice (and credit you appropriately ;).

*   If you have a heterogenous network with both System V-based and
    BSD-based machines, and intend to use PLP's NFS spool directory
    functionality, you will probably need to set up a new userid to
    replace `daemon', as System V and BSD disagree on the appropriate
    user and group ids for such a user.

    This user is only used as the owner of the spool directories and
    log/lockfiles, so a line such as the following in /etc/passwd will
    do the trick:

	plp:*:67:67:PLP (system):/:/bin/true

    Change any of the above fields according to your preference.
    Change the `user' parameter in your plp.conf file to this new
    user's username ("plp" for the above example). `chown' all the
    spool directories you intend to NFS export/mount to this new
    user, either by hand or by using `checkpc -f'.

*   After you have set up the printcap and other files,  you can try
    installing the PLP software. First, edit the Makefile and fix up
    the locations you want to install it into (OPTIONS section).

	make install

    This will also install two scripts to emulate System V printer
    interface semantics (lp and lpstat). Type
    
	make install.man

    if you want to install the manual pages as well.

*   You should now decide whether you want to run the PLP lpd from
    inetd or standalone -- inetd mode will involve a speed tradeoff,
    as an lpd process will be forked every time a request arrives,
    but will save virtual memory when no spooling is active.

    If you choose to run lpd from inetd, you should NOT put an
    lpd startup line in one of the system startup scripts, as
    step 10 (below) suggests. This is only necessary in standalone
    operation.

*   You'll need to kill off the currently-running lpd (BSD) or lpsched
    (SysV) process:

	ps aux | grep lpd; kill -15 <lpdpid> 	(BSD-style, or)
	/etc/init.d/lp stop			(System V style)

    and edit /etc/rc.local (BSD) or /etc/rc2.d/S*lp (SysV). The file in
    question differs widely from OS to OS, unfortunately. The suggested
    procedure is to comment out the system default lpd invocation, and
    put a line running the PLP lpd in its place. In these short
    examples, it is assumed you've installed the PLP lpd in
    /usr/local/bin; change appropriately.

	SunOS: edit /etc/rc, look for "/usr/lib/lpd", comment and
	    replace with "/usr/local/bin/lpd".

	SVR4/Solaris 2: edit /etc/rc2.d/S80lp, look for "/usr/lib/lpsched",
	    comment and replace with "/usr/local/bin/lpd". The filename
	    of the S*lp startup script may be different.

	HP/UX: edit inetd.conf, comment out the line that reads:
	    "printer stream tcp nowait root /usr/lib/rlpdaemon rlpdaemon -i"
	    and restart inetd (get its pid and "kill -1" it).  Add
	    the line "/usr/local/bin/lpd" to "/etc/rc" in the
	    localrc() function. Also, comment out the "lpsched"
	    line in the lp_start() function.

	Linux: either SunOS-style or SVR4-style, depending on
	    which distribution you use.

    Your mileage may vary -- if none of these examples apply to you,
    see what your system's documentation says.

*   To set up lpd in inetd mode, you should add this line to /etc/inetd.conf:

	printer stream tcp nowait root /usr/local/bin/lpd lpd -i

    (or something similar) and restart inetd (get inetd's pid from "ps",
    and "kill -1" the process).
   
   IMPORTANT NOTE: If you see this message on the syslog:

        getpeername failed - Socket operation on non-socket

    you've set up the line wrong -- you've set it up with the "wait"
    parameter instead of "nowait"!

    If you want to test lpd in inetd mode, you'll need to add a service
    to /etc/services, such as the following:
    
	tstprinter	45322/tcp		# PLP test service

    and edit the inetd.conf line to something like the following:

	tstprinter stream tcp nowait root /home/jmason/tst/lpd lpd -i

    Make sure that the plp.conf file has the line "lpd-port tstprinter",
    otherwise lpr and the other clients won't be able to talk to the
    lpd.

*   Some programs assume that lpr (BSD) or lp (SysV) are installed in
    /bin, /usr/bin, /usr/ucb or whatever.  You may have to make a
    symbolic link from the normal system location (eg. /usr/ucb/lpr) to
    the PLP version's location if you start getting peculiar "cannot
    print" errors from some applications (notably ELM).

*   It's installed! If you should have any trouble later, try killing
    the daemon and running it with the -Ddebuglevel flag for copious
    debugging noise; the output will probably make the cause of the
    problem a little clearer. Also, RTFM!

*   If you intend to use PLP as a client with a non-PLP lpd as a
    server, make sure you read the file "OTHER-LPDS"!

--j.
