Documentation: Technical

phpPrintAdmin Technical Overview

this is a work in progress...

phpPrintAdmin is a web application for monitoring and administrating multiple print servers in a centralized manner. It is written in PHP for the Apache web server, and requires a MySQL database.

            Here are some of its features:

            Better organization of printer information

            Job/queue control (such as deletion of jobs)

            SNMP printer querying

            Automated printcap/printers.conf files generation and distribution to servers

Technical Overview

            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 npadmin  must 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.

log_lib.php

            Simple class for logging events to the database.