** Please note - most of this HOWTO is Linux/BSD-oriented. If you know
enough to administer a commercial Unix, you should be able to work out what
needs to be changed :-)

So, You Want To Be A Fasicst Administrator By Charging For Toner
================================================================

Good on you. Let the glory of free-market capitalism shine through, and make
the suckers pay for their printing. Because if they don't, you surely will.
We had one fellow that thought inverse video was easier on the eyes. Maybe
it is, but it sure goes through a hell of a lot of toner if you want to
print it out. If you have to pay a dollar per page to print such a document
it makes people think about their resource consumption, which is good for
the environment, and for your printing budget.

It's also good for you, the lazy system administrator. As it says in the
Camel book, Laziness is one of the three great programmer virtues (hubris
and impatience are the other two). Exploit my hubris and impatience to
enhance your laziness experience!

Pre-printing billing
====================

This option is the most appropriate for untrusted environments. Jobs will be
billed and the cost deducted from the users quota before being sent to
the printer.

0). Before even thinking about printbill, make sure you can print. That
means getting lprng installed, installing magicfilter (if your printer isn't
postscript and/or you want to print non-postscript stuff on it) and
verifying that stuff actually comes out of the printer when you try to
print. Figure out whether or not you want to make it available over the
network (that's an lprng issue) and work out which anything ->
printer_language print filter you need (if any) and which anything ->
postscript filter you want to use for printbill. Customise and re-name one
of the magicfilter ones if you like (that's what I did). Lets suppose the
any -> PS filter is called psonly600-filter and the any -> printer_language
filter is called stylus600_720dpi-filter, and they both live in
/etc/magicfilter. In other words, you can print using a printcap entry like
this:

lp|Epson Stylus Color 600
	:lp=/dev/lp0
	:sd=/var/spool/lpd/lp
	:sh:pw#80:pl#66:px#1440:mx#0
	:if=/etc/magicfilter/stylus600_720dpi-filter
	:af=/var/log/lp-acct
	:lf=/var/log/lp-errs

1). Install printbill. If you're using Debian this should be a piece of
steaming rich chocolate mud cake with ice cream, hopefully it should be a
similarly enjoyable experience for RedHat users (although perhaps without
the ice cream). Otherwise, download the source archive, edit Config to suit
your local environment, type "make" followed by "make install".

If you're building it yourself, you'll want to have libpng2 (and its
headers) or possibly libpng3, plus Ghostscript (5.x or later recommended),
gsfonts (yes you *really* want these). Also re-read section 0 regarding
lprng...

2a). If you're using Debian, see 1). Debconf now asks you the important
questions, if you have any requirements not covered by debconf's questions,
well, that's what printbillrc(5) is there for.

2b). There is now a really handy little perl script called
printbill_configure. It asks you a bunch of questions about your system (and
makes a few discrete enqiries of its own) and basically fills in a
printbillrc file for you. What's more, if you have a working printcap file,
it will generate a new one based on the old one plus your answers to the
interrogation. The files end up as printbillrc.new and printcap.new. Move
the printbillrc.new file to /etc/printbill/printbillrc, and the printcap.new
to /etc/printcap (after backing up the old one, as you obviously should do -
unless you trust my hacked-up perl code with your computer's life, which
quite frankly I find rather disturbing). Restart your lpd service
(/etc/init.d/lprng restart for Debian or /etc/init.d/lpd restart for
RedHat).

If that all works, type "pqm --init", unless you already have a populated
/var/lib/printbill. If you want to blow your database away you can run it
anyway - but do make a backup first :)

Both Debian and RedHat's init scripts for lprng will create missing
/var/spool/lpd/* directories - Slackware and various others probably do not
by default. Needless to say, if the printcap file lists new spool
directories (of course it will if you've printbilled any existing printers)
then create and populate them by hand. Of course, if you are a Slackware
user you'll know how to do that already...

2c. a) If you're a paranoid "I'm doing everything by hand because I don't
trust them new-fangled perl scripts" sort, then you can manually set up your
printcap file to use printbill. Edit the entry in section 0 so it is now
called "lp-real":

lp-real|Epson Stylus Color 600 - destination print queue (don't print to this)
	:lp=/dev/lp0
	:achk=true
	:as=|/usr/sbin/printbill_printer
	:sd=/var/spool/lpd/lp-real
	:sh:pw#80:pl#66:px#1440:mx#0
	:if=/etc/magicfilter/stylus600_720dpi-filter
	:af=/var/log/lp-acct
	:lf=/var/log/lp-errs
	
Obviously, change the :as=|/usr... line to point to the correct location for
printbill_printer. Of course, if=blah is optional - if you're only printing
postscript to a postscript printer then you will never need it - this is the
case if you are printing from Windows via Samba.

Now add a new entry for your user-accessible print queue:

lp|Epson Stylus Color 600 - user print queue
	:lp=/dev/null
	:achk=true
	:as=|/usr/sbin/printbill --type bill --printbill_secondary lp-real
	:sd=/var/spool/lpd/lp
	:sh:pw#80:pl#66:px#1440:mx#0
	:af=/var/log/lp-acct
	:lf=/var/log/lp-errs

Users will print to this queue (lp -Plp filename or just lp filename), where
jobs will be queued for billing. Once jobs have been billed they are sent to
the secondary print queue. NOTE: you better put lp=/dev/null in this print
queue or you'll get two copies of each successful print job :) Also note
that we have no input/output filters. The input filter gets used later by
printbill itself.

Don't forget to restart lprng, as discussed in section 2a...

2c. b) Still with me? Now you need to do some calculations. How much are you
going to charge?

Our printer is a colour inkjet printer, so we have two kinds of cartridges -
black and colour (CMY). The black one costs $A25 and claims to be able to
print 540 pages and 5% coverage, for a total of 2700% coverage (27 black
pages) while the colour cartridge costs $65 and claims 300 pages at 5%
coverage per colour (3 * 5 * 300 = 4500% or 15 cyan, 15 magenta and 15
yellow pages). Thus black ink costs $0.009259 per percent coverage, while
colour ink costs $0.014444 per percent covarge. Paper works out at around
$0.01200 per sheet. The price calculation is simple

price = number of pages * price per sheet +
	% black coverage * price per percent black +
	(total % cyan, magenta and yellow) * price per percent colour.

2c. c) Customise the configuration file. If you have just one printer, you
can set the default parameters at the top of the file to look like this:

colourspace:			cmyk
price_per_percent_black:	0.009259
price_per_percent_colour:	0.014444
price_per_page:			0.012
estimated_total_percent_black:	2700
estimated_total_percent_colour:	4500

On the other hand, if you have multiple (not necessarily local) printers,
you can specify them on a per-printer basis, by creating a file in
/etc/printbill/printers with the same name as your printer (e.g., "bob")
which contains a list of the parameters you wish to override:

colourspace:			cmyk
price_per_percent_black:	0.009254
price_per_percent_colour:	0.014444
price_per_page:			0.012
estimated_total_percent_black:	2700
estimated_total_percent_colour:	4500

the name on the first line should match the name in /etc/printcap.

Other things you may need/wish to edit in this configuration file include:

* The user under which the printbill daemon printbilld is suppsed to run.
This should probably be the same as the UID under which lpd runs - to find
out, do this:

ps aux | grep -i lpd.

On Debian systems this is "daemon". If you don't get this right I guarantee
that nothing will print (at least with the '--bill' option - lazybill will
probably be OK). Set "printbilld_user" to this name:

printbilld_user:		daemon

* The group under which printbilld should run. If you want to use the web
interface, add a group called 'pbill' or similar and add both
printbilld_user and web_user (the username under which Apache runs -
typically 'www-data' or 'www') to the group. Then set the files/directories
in db_home group-writable. Set it like this:

printbill_group:		pbill

* The optional anything -> PS converter. Change the "filter" line to point
to your chosen filter:

filter:			/etc/magicfilter/psonly600-filter

For the other entries, read the man page (man printbillrc).

* The dots-per-inch used by GhostScript to generate the PNG images - larger
values are more accurate but much slower. 100 dpi seems a good compromise
(note that lower dpi tends to overcharge people - in one test (predominantly
plain text), I found that in going from 100 to 750 dpi, the resulting charge
changed by about 30% (but the execution time went up about a hundredfold).
This is mainly due to the lack of anti-aliasing in ghostscript's png driver
(at least as of gs 6.50). Note that some cynics would also call this error
your profit margin, but then the real capitalists amongst us would have
already taken that into account when determining the price for toner and
paper. If you're a non-profit organisation, just roll any surplus over into
the New Printer fund.

Sigh. It really is easier to use the printbill_configure script. But you
insisted.

3) Start your brand new printbill daemon - run /etc/init.d/printbill for
Debian, /etc/rc.d/init.d/printbill for RedHat and /etc/rc.d/rc.printbill for
Slackware. A quick ps aux | grep printbilld should confirm that it is
running.

4) Once all is ready (and you did remember to restart lprng after fiddling
with the printcap file, didn't you?) you can add a user to the billing
system and give them some initial quota. For a user with the login "tux",
do this

pqm --add tux
pqm --inc tux --amount 10

pqm accepts decimals too, so you can add 0.3 dollars if you like. Anyway,
the penguin should now be able to print, provided it is within his budget.
What's the dollar to herring exchange rate anyway?

Note: you can now just run

pqm --inc tux --amount 10

(i.e. without running --add), which will automatically add tux to the
system with initial quota of 10 herring.

Troubleshooting
===============

Verify that your perl modules are functional by trying to run printquote. If
this fails, the problem is probably mis-installed modules or a faulty
/etc/printbill/printbillrc. You may also have permissions problem - check
/etc/printbill and the files within, and check the permissions on the
binaries and modules.

If that works but your print filters won't work, check the permissions on
/var/lib/printbill (or wherever you put it) and the files and directories
within. Check the user under which your lprng daemon is running. Verify that
tmpfs is writable by the lpd user, and check that /tmp is writable too (yes
we use both... although we probably shouldn't).

Try running printbilld with the -stay option instead of using the startup
script. If it's exploding while trying to start, you will see the output on
the console. Try printing while it's running with -stay - you should see any
horrible error/warning messages.

Make sure that printbill and printbill_printer (or any other filter invoked
by lpd) are executable (and readable) by the lpd user. There is no problem
making them chmod 0755 (after all, users can just download printbill and
install it themselves, so it makes no difference if they can run the system
one ;-)

Does the printcap file actually have an ":achk=true" line? It needs one, for
both printbill and printbill_printer.

Make sure lprng is doing logging - check the output in /var/log/lpr.log (or
whatever syslog writes out for lpr logs) and the individual printer logs
(such as /var/spool/lpd/printer_name/*.

You may test whether or not your secondary queue works by su-ing to "daemon"
or whatever user under which lpd runs and attempting to print to the queue.
Try printing to this queue as an ordinary user - it should not work.

printbill assumes your perl binary is /usr/bin/perl. You may have yours
installed in another location (Solaris and *BSD, plus if you install it
yourself from source under another Linux distribution). If this is the case
(type "which perl" in bash or zsh to find it) then you'll need to edit the
perl scripts and change the first line in each. Or install perl in the usual
place, or symlink, or whatever.

If everything else appears correct, try setting the save_bad_path option in
printbillrc. This will save jobs which are causing problems so you can
fiddle with them later (if a user tries to print 30 files in one job and
they all cause problems, only the first one is saved - billing will stop at
that point). Try running gs on the faulty jobs - if it can't grok it,
there's your problem. The 'file' utility should tell you what file it is, if
gs doesn't recognise it.

If you're not sure of the best place to install your perl modules, you may
wish to try the following command:

perl -we 'for $path (@INC) { print "$path\n"; }'

which will dump the search path. The perl modules should go in one of these
directories, in a subdirectory called "Printbill".

If all else fails, make sure your file is something that gs can understand
(or make sure that your print filter generates valid postscript code). Run
it through gs or gv or similar - if you don't see anything, neither will
printbill.

Oh yes, and one other possible problem - make sure syslog is running.
Printbill does extensive logging, and you *must* have syslog working for
printbill to work. We had a machine where syslog kept dying every few
weeks... printbill mysteriously stopped working until we re-started syslogd.

Post-printing billing with printbill --type lazybill
====================================================

This option is best for environments where users are trusted to some extent,
but still need to actually pay for their printing. It is also appropriate
where speed is of the essense and where people are printing very large
volumes. The principle is that the user can print almost immediately
(provided that they have some quota), but their job will be copied and
billed at a later time. You can limit the maximum number of jobs which are
billed concurrently (even limit this to one job at a time if necessary) - if
the queue of pending bill processes builds up, there should be no problem
(most of them will just be sleeping) - just make sure you have enough disk
space to cope with the demand. The queue will eventually get processed
overnight (and users may well end up with a large deficit as a result).

This print filter is a little easier to use than printbill_scheduler.

lazylp|Epson Stylus Color 600 - user print queue
	:lp=/dev/lp0
	:achk=true
	:as=|/usr/sbin/printbill --type lazybill
	:if=/etc/magicfilter/stylus600_720dpi-filter
	:sd=/var/spool/lpd/lp-acctonly
	:sh:pw#80:pl#66:px#1440:mx#0
	:af=/var/log/lp-acct
	:lf=/var/log/lp-errs
	
Print via lp -Plazylp filename

So, You Want To Be A Fasicst Administrator By Tracking Printing Habits
======================================================================

Oooh you Orwellian authoritarian bastard. Well, at least the users know you
won't be charging them for their printing. But you want to see who's been
churning through forests of dead trees and burning buckets of toner late at
night...

Fine - you can use printbill --type account. The only major difference here
is that you don't need to worry about quota. Like printbill --type lazybill,
there is no delay while the document is being billed - that happens in the
background. Of course, since it uses CPU (a valuable resource by any
measure), it adheres to the same processing limits (maximum concurrent
processes and adjustable niceness) as the regular printbill_scheduler. Any
number of jobs may be printed, but only a maximum of max_bill_processes will
actually calculate simultaneously at any time (others will just copy the
files and sleep). Of course, if the printer can print faster than the
billing processer can bill, the disk may get full (but people don't usually
print at midnight, so a couple of GB of disk space should be enough to
buffer the print jobs, even if they are billed afterwards).

The printcap entry would look like this:

acct|Epson Stylus Color 600 - user print queue
	:lp=/dev/lp0
	:achk=true
	:as=|/usr/sbin/printbill --type account
	:if=/etc/magicfilter/stylus600_720dpi-filter
	:sd=/var/spool/lpd/lp-acctonly
	:sh:pw#80:pl#66:px#1440:mx#0
	:af=/var/log/lp-acct
	:lf=/var/log/lp-errs

Naturally, print via lpr -Pacct filename. Stats and logfile entries will be
generated almost exactly the same as for printbill_scheduler.

Printing from Windows
=====================

Apparently some strange people like to use an operating system called
'Windows' from some commercial software vendor or other. If this is the case
in your environment, you may quite happily use printbill with Samba. From
the Unix end, you need to configure Samba to use lprng-style printing. From
the Windows perspective you will need to install some generic PostScript
printer driver - as long as it generates postscript which is understood by
gs, printbill should work. Verify this by printing to file and viewing the
.prn file in gs under Linux.

In a similar vein, it is conceivably possible that Macintosh machines can
print to printbill via netatalk, but I've never tried it so you're on your
own here. OSX machines may be able to run some sort of BSD-style print
spooler rather than using Ethertalk, so who knows (apparently lprng compiles
on OSX).

It seems that many Windows printer drivers actually generate PCL even when
told to generate Postscript, and many prepend a few lines of crap at the top
of the file, which may be enough to stop gs or the anything -> postscript
filter from working. Based on feedback from users of printbill, I recommend
using one of the Apple PostScript drivers - these seem to work quite well,
and generate fairly good PostScript. As long as the target printer
understands PostScript, you should be OK (if it doesn't, you'll need a print
filter for the secondary queue). Please note that there is little prospect
of printbill ever working with Windows PCL drivers (it can of course
generate PCL, but if jobs are sent to it as PCL it won't be able to process
them - at least not until someone sits down to write a PCL -> png
converter).

Other Tricks, Hacks and Suggestions
===================================

But wait! There's even MORE! That's right, not only can you bill people,
account without billing, print from Windows, and get a free set of steak
knives, you also get

* A printbill option which calculates the bill for a job and mails you the
quote (printbill --type quote) or even pops up a Winpopup message via
smbclient (mainly for Windows users)

* A script which lets users do this via the command line (printquote
file.ps) - Unix-savvy users will tend to prefer this

* A print filter and accompanying script which allows people to make certain
fixed deductions from their quota (printbill_billme and buy)

* A web interface for basic administration (webpqadmin.pl)

* A web interface for users to check their quota (webpqcheck.pl)

* The option of providing read-only access to database and configuration
files via ftp or http - man 5 printbillrc for details. This is useful if
people want to be able to run printquote or pqcheck from their own machine -
the printbill server can expose the printbillrc file (and user databases) on
a web or ftp site, and the users can run various scripts read-only from
their clients.