Essentially, phpPrintAdmin is designed to run
on top of a Unix server running LPRng, IFHP and Samba. Since it is a php web
application, it requires a web server. Because of certain authentication
features, it can only run on Apache for the time being. Later versions of
phpPrintAdmin may switch to using session-based authentication for greater
flexibility.

It uses MySQL for storing, among
other things, printer, server, and user information. Additionally, the utility
npadminmust be installed in /usr/bin (or a link to it) for the
snmp printer query feature to work.

Why MySQL?

Given that we have about 400 or so printing
queues in the organization (at least), it seemed appropriate to use a data
storage facility more elaborate than a flat text file, which is what a printcap/printers.conf
essentially is (if used independent of a database).

MySQL is easy to use and install, and is well
supported by the open source community. Additionally, PHP and MySQL are well
integrated together, and PHPs native libraries support MySQL.

How it works:

The "primary" server acts as a repository (MySQL) for
information on all the printers in the organization. All administration is done
via the primary server using any web browser, such as the adding of print
queues, and job control. Printer configuration files can then be automatically
generated from the database on demand. The "client" servers are basically just
regular print servers, but with the exception of running a web server to receive
a "sync signal" to initiate a synchronization with the "primary" server.

The Printer Database:

In the MySQL database, the most important table
is the "printers" table. In it is stored, for example, the IP address, name,
and ifhp model of a certain printer. Additionally, detailed information about
printers is available, such as how much RAM it has, or if it can duplex. While
most of this information is not used currently, it is none the less available
for future additions to the application. A future feature I would like to see
is an automatic printer discovery feature, which would import a jetDirect
generated CSV file of printers it discovered, and add them to the database.

Automatic printcap/printers.conf generation

Printcaps and printers.conf files are generated
from the database using "template" files containing example entries to be used.
These can be viewed in

/www/pa/sys/templates

The filenames are long, but they were an
attempt to make the templates self-descriptive. If you look in a template file,
you might see something like:

[name]

:server

:force_localhost@

:filter=/usr/libexec/filters/ifhp

:ifhp=model=[ifhp_model],status@,sync@,pagecount@,waitend@

Anything enclosed in [ ] is a variable, which is
substituted with real names, models, etc at the time of execution. These can be
edited if need be.

The "clientonly" templates are template files for "remote"
or "bounce" queues. See below for an explanation of remote queues.

How the synchronization works

The "force_sync" script (on the primary
server) opens up an http connection to each of the "secondary servers", which in
turn executes a php script on them. The script on the secondary server simply
writes a "1" to a file, which is periodically read (once a minute) by a cron job
(do_sync.pl). If the script reads a "1" on the first line of the file, then code
is executed which copies new information on the primary server to the secondary
server. The sync is done with rsync using ssh.

Information that is synchronized is the
printcap file, the printers.conf file, and (optionally) a samba directory.
Anything can be added to the do_sync.pl file if more files/data needs to be
transferred during the sync.

Sync execution steps:

1) Administrator executes "force_sync.php"
after confirming that they wish to do a sync.

2) "force_sync.php" opens an http connection to
each of the secondary servers, executing "activate_sync.php".

3) On the secondary server, activate_sync.php
simply writes a "1" to the file "flag_file"

4) A cron job called "do_sync.pl" periodically
(once a minute) reads the flag_file. If the first line is a "1", then some code
is executed.

5) This "code" are rsync commands, which copy
the printcap and printers.conf (for example) out of the secondary serverís
export directory on the primary server.

6) LPD and Samba processes are sent a "HUP"
signal to reread their config files.

7) "do_sync.pl" then writes a "0" to the
flag_file, thereby preventing another execution of the sync until a "sync
signal" is sent out again.

8) Thatís it!

PHP structure:

The root directory for the application on atlas is /www/pa
(these are sym links).

The files users directly access are all directly under the
root directory.

lib/ Library files

conf/ The menu file (included in all pages) and the css
definition file

images/ Images

logs/ (deprecated Ė logs are in the database now)

sys/ SQL dumps are put here for backup purposes, and the
template directory is in here.

exports/ contains a directory for each server, which in
turn contain their respective printers.conf and printcap files
for synchronization

util/ miscellaneous utility scripts

temp/ place for testing things out

Page construction logic:

All pages initially include the "config.php" file, which
contains variables and code which are to be global to phpPrintAdmin. This
include the username/password to the MySQL database, inclusions of files in the
lib/ directory, and the authentication mechanism. This should be made secure
because of the information it contains (readable only by web server user).

The menu is included from conf/menu.php, to ease the
changing of menu items.

Future versions of the application will completely template
out the pages, thus making changes to the GUI simpler.

Library files (lib/):

printer_lib.php

Contains the printerDB class, which creates an
object representation of the printers table for access. This can then be used
in conjunction with the display_lib.php functions to display information, create
forms, etc.

Spec:

Class printerDB

function printerDB($sort_by="name")

// initiates the printerDB
based on the printers table from the database

function addPrinter($printer,$is_remote)

/// adds a printer based on
$printer, which should be a hashed array

according to spec (see
below)

function delPrinter($printerID)

/// deletes a printer
according to itís printerID

function selectPrinters($by_field, $field, $search_type="exact",

$server_filter = "all")

/// copies a printer entry(s)
into the $selectedPrinters var for operations according to the search criteria

///
imagine this as a kind of "temp" space for changing values

function sortBy($sortby)

/// re-sorts the printerDB
object according to the given database field

function updatePrinter($printer)

//// modifies a printer
entry with the given $printer hash array (again,

//// $printer must meet spec

db_functions.php

Functions that printer_lib.php calls upon for
access to the database. Things were getting messy in printer_lib so I decided
to move some of the db functions out to another file.

display_lib.php

Various functions for displaying information,
or formatting it for output.

Spec:

Function

display_lib2.php

A "transitional" display library, now holding a
hacked display function for displaying job information. Eventually, I would
like to remake the display library as a class, and this is where itís going to
go. Code will be migrated to using display_lib2, and once all of it has been
converted, display_lib will be deprecated.

lpd_lib.php

This contains two classes, "queue" and
"server", which queries a LPRng lpd server about information on queues. The
class "server" creates "queue" objects for a given lpd server. lpd_lib can run
independent of phpPrintAdmin, should someone wish to build a different
application based on it. lpd_lib is thoroughly documented in the source code of
the file.

sync_lib.php

Functions for generating the printcap and
printers.conf files for the servers, and also initiating a synchronization

user_lib.php

Contains one class Ė userDB Ė which creates an
object representation of the users table in the printadmin database.
Corresponding methods are in it for adding and deleting users.

There is a function called "check_auth_page),
as well, apart from the class that checks if a given user has the appropriate
access rights to a page.

misc_functions.php

Various functions that did not warrant their
own library file. There is an array search function (searchExact), a function
that returns active servers, the function that checks the LPD/Samba status of a
server, and so forth.