Show
Ignore:
Timestamp:
07/24/07 09:58:17 (17 years ago)
Author:
jerome
Message:

Documented the qa-assistant part a bit.

Files:
1 copied

Legend:

Unmodified
Added
Removed
  • pykota/trunk/qa-assistant/README

    r3201 r3212  
    1818Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 
    1919 
    20 ==================================================================== 
     20============================================================================= 
    2121 
    22 READ SPECIAL LICENSING AND REDISTRIBUTION TERMS IN THE FILE 'LICENSE' 
     22This directory contains checklist templates to use with Gnome's qa-assistant 
     23utility. 
    2324 
    24 ==================================================================== 
     25Just copy the XML files from this directory to /usr/share/qa-assistant/data/ 
    2526 
    26 PyKota features : 
    27 ----------------- 
     27If you want to setup PyKota on a new machine, or help somebody do so, 
     28launch qa-assitant, then start a new QA review, and choose any of the  
     29"PyKota Installation" templates. The other templates are unrelated 
     30to PyKota and are installed as part of qa-assistant. 
    2831 
    29         http://www.pykota.com/software/pykota/features/ 
     32Confirm your choice and then apply it. 
    3033 
    31 ==================================================================== 
    32          
    33 Planned features are described in the TODO file. 
     34qa-assistant will then display a checklist describing a step by step 
     35setup guide for PyKota. Moving the mouse cursor over each step will 
     36explain what you have to do before deciding if this particular step 
     37failed or passed. 
    3438 
    35 Actually three (or an infinity of) page accounting methods are 
    36 implemented : 
     39IMPORTANT : currently a single "PyKota Installation" template is provided, 
     40and it is still incomplete : it doesn't contain any database related 
     41instructions. 
    3742 
    38   - The 'hardware' method consists in querying the printer (via SNMP 
    39     or Netatalk or any other method of your choice) for its internal  
    40     pages counter. 
    41     This is done both at the beginning and at the end of a 
    42     print job. The counters difference is then used to  
    43     decrease the user's account balance or increase his quota usage. 
    44      
    45   - The 'software' method consists in delegating the computation of the 
    46     job's size in number of pages to any external command of your choice. 
    47     The command can read the job's data from its standard input and MUST 
    48     output the job's size on its standard output. Changes to the user 
    49     account are reported immediately. PyKota by default internally 
    50     uses the code from pkpgcounter which can handle 
    51     several Page Description Languages : DSC compliant and binary PostScript, 
    52     PDF, PCLXL (aka PCL6), PCL3/4/5, ESC/P2, DVI, TIFF, OpenDocument, 
    53     Zenographics ZjStream, Samsung QPDL,Samsung SPL1, and plain text. 
    54     Of course this means you have to install pkpgcounter if you want to 
    55     use the default PDL parser. 
    56      
    57   - The 'ink' method consists in using pkpgcounter's code to compute   
    58     how much of each page is covered by ink in each color of a particular 
    59     colorspace chosen between CMYK, CMY, RGB, and BW (grayscale). 
    60     These values are then summed up together and multiplied by a set 
    61     of coefficients defined in PyKota's configuration files. 
    62      
    63 PyKota is known to work with most printers, excepted GDI ones (Windows 
    64 only). At least one of the accounting methods above should work 
    65 for you. If it's not the case, please report the problem : tell us 
    66 the exact brand and model of the printer, if possible the driver used, 
    67 and send some test files. 
    68  
    69 ============================================================ 
    70  
    71 SUPPORT CONTRACTS: 
    72 ================== 
    73  
    74   You can now purchase 8x5x365@NextBusinessDay Technical 
    75   Support Contracts from us. The yearly fee is computed with   
    76   the following formula : 
    77  
    78   (100.0 * NbPrintServers) + (2.5 * NbPrinters) + (0.04 * NbUsers) EUROS. 
    79    
    80   This fee includes the VAT, and a free subscription to Official 
    81   PyKota packages. 
    82  
    83   Please send an email to alet@librelogiciel.com if you're 
    84   interested in purchasing such a contract.    
    85  
    86   Remember that purchasing a support contract for Free Software like PyKota 
    87   is a great way to show your appreciation for the work already being done  
    88   on this project, and will help to improve this software in the future. 
    89  
    90 ============================================================ 
    91  
    92 INSTALLATION: 
    93 ============= 
    94  
    95 NB : 
    96 ==== 
    97  
    98   PyKota's documentation is available as DocBook SGML sources 
    99   files in the pykota/docs directory. If you obtained an 
    100   Official package, in the same directory you'll also find 
    101   the documentation in HTML and PDF formats. Otherwise you 
    102   have to compile it into HTML or PDF yourself by using 
    103   the appropriate tools as installed on your system. 
    104    
    105   PyKota's collaborative documentation is available from : 
    106    
    107     http://www.pykota.com/wiki/ 
    108      
    109   You may learn more about PyKota, if it fits your own organization, 
    110   its internal working, and some potential performance drawbacks and 
    111   how to avoid them, in a document created by Ryan Suarez at : 
    112    
    113     http://archive.macosxlabs.org/forum/webcrossing_archive/documentation/Pykota_and_CUPS/Pykota_and_CUPS.html 
    114  
    115   You may also find the following document interesting : 
    116    
    117     http://es.tldp.org/Tutoriales/doc-openldap-samba-cups-python/ 
    118      
    119   This document, written in Spanish by Sergio Gonzalez Gonzalez,   
    120   describes the integration of PyKota into an OpenLDAP + Samba 
    121   + CUPS installation. Even for people who can't read spanish  
    122   this document is really interesting, and contains lots of 
    123   screenshots. 
    124    
    125    
    126 Prerequisite :  
    127 -------------- 
    128     
    129   See : 
    130    
    131     http://www.pykota.com/wiki/Dependencies 
    132      
    133   for an up-to-date list, or see below (maybe not up-to-date) : 
    134    
    135   You need to have the following tools installed on the CUPS Server : 
    136    
    137     - CUPS (http://www.cups.org) 
    138     - Python v2.3 or higher (http://www.python.org) 
    139     - eGenix' mxDateTime Python extension (http://www.egenix.com) 
    140     - The pkpgcounter command line tool, version 1.56 or higher. This 
    141       tool is now mandatory for PyKota to work.  
    142       (http://www.pykota.com/software/pkpgcounter) 
    143     - The pkipplib Python library (http://www.pykota.com/software/pkipplib)   
    144     - The JAXML Python module to be able to dump datas in the XML format. 
    145       (http://www.librelogiciel.com/software/) 
    146     - The Python-PAM module if you need the pknotify command to be able   
    147       to check usernames and passwords. (http://www.pangalactic.org/PyPAM) 
    148     - The Python-SNMP module to query printers for their page counter. 
    149       (http://pysnmp.sourceforge.net)  
    150       IMPORTANT : version 3.4.2 or higher is REQUIRED. 
    151       Versions 2.x won't work. Versions 4.x now work (tested with v4.1.5a). 
    152     - The Python-OSD module to use the graphical print quota reminder. 
    153       (http://repose.cx/pyosd/) 
    154     - The Python-chardet module to autodetect user's character set when   
    155       printing. (http://chardet.feedparser.org) 
    156     - SNMP tools (specifically the snmpget command) if you prefer to 
    157       use your own script to request query printers. 
    158       (http://www.net-snmp.org) 
    159     - Netatalk (specifically the pap command) if you plan to 
    160       request your printer's lifetime page counter via AppleTalk. 
    161       (http://netatalk.sourceforge.net) 
    162     - The ReportLab Python module (http://www.reportlab.org) if you want   
    163       to have PyKota generate nice banners for you. 
    164     - The Python Imaging Library (aka PIL) module  
    165       (http://www.pythonware.com/downloads) if you want to have PyKota  
    166       generate nice banners for you. 
    167     - PostgreSQL's PygreSQL Python extension and the PostgreSQL client 
    168       libraries if you plan to use PostgreSQL as the database backend. 
    169       (http://www.postgresql.org and http://www.pygreql.org) 
    170  or      
    171     - python-ldap Python module and the OpenLDAP client libraries   
    172       if you plan to use an LDAP server as the database backend. 
    173       (http://www.openldap.org and http://python-ldap.sourceforge.net) 
    174  or  
    175     - SQLite v3.2.7 and the SQLite libraries if you plan to use SQLite 
    176       as the database backend (http://www.sqlite.org). You also need the  
    177       PySQLite module v2.0.5 or higher (http://www.pysqlite.org) 
    178  or 
    179     - The MySQL-python bindings.  
    180       IMPORTANT: If you are using MySQL 4.1, then MySQL-python must be  
    181       version 1.2 or greater. Version 1.0 does not work correctly with 4.1. 
    182        
    183      
    184   On Intel i386 architecture, and for performance reasons, it is 
    185   strongly suggested that you install the Python accelerator Psyco,  
    186   available at : 
    187    
    188       http://psyco.sourceforge.net 
    189        
    190   Under Debian :     
    191    
    192       $ apt-get install python-psyco 
    193        
    194   Other architectures may be supported as well in the future, check     
    195   this on Psyco's website. 
    196    
    197   Installing Psyco is not mandatory, but it will speedup PCL5 parsing 
    198   by almost 3 times. PostScript and PDF parsing can also benefit, 
    199   but in an almost unnoticeable manner since this part of the code 
    200   is already optimal. For PCL5 this is a completely different matter, 
    201   and if you install Psyco you will never regret it ! 
    202   Same remark applies for PCL6 (aka PCLXL) : the parser is completely 
    203   different, but the performance gain with Psyco is impressive. 
    204    
    205   You may also benefit from having the following tools installed to 
    206   deal with some printers : 
    207    
    208     - npadmin 
    209     - netcat 
    210     - ghostscript 
    211      
    212   You need to have the following tools installed on the database 
    213   server : 
    214    
    215     - PostgreSQL (http://www.postgresql.org) 
    216      
    217   or   
    218    
    219     - OpenLDAP, or any other LDAP server (http://www.openldap.org) 
    220      
    221   or    
    222    
    223     - SQLite, v3.2.7 or higher (http://www.sqlite.org). 
    224       Beware : with SQLite the database server and the print 
    225       servers MUST be the very same machine. 
    226        
    227   or      
    228    
    229     - MySQL 4.1 or higher. 5.x is recommended. 
    230      
    231   This list of prerequisite software may change in the future, when 
    232   PyKota will support more functionnalities you will be given  
    233   alternatives. 
    234    
    235   Of course the Print Server and the database server can be the  
    236   very same machine if you've got a tiny network, or you can have  
    237   multiple Print Servers all storing their quotas on the same database 
    238   server if you've got a bigger network. (NB : with SQLite, the database 
    239   can't be shared between several print servers) 
    240    
    241 Hint :   
    242 ------ 
    243  
    244   - The Debian GNU/Linux distribution is to our knowledge the  
    245     easiest distribution to install PyKota on, because almost all 
    246     of PyKota dependencies are already included, excepted 
    247     the pkpgcounter utility which for now have to be downloaded 
    248     and installed separately, and maybe one or two other dependencies, 
    249     depending on the version of Debian you are using. 
    250     We recommend you to use Debian's Etch distribution or 
    251     more recent. PyKota works fine on Sarge, but some additional 
    252     dependencies are missing in Sarge and have to be installed 
    253     manually. 
    254  
    255 Then :    
    256 ------ 
    257   
    258 Download the latest PyKota version from the Subversion tree : 
    259  
    260     $ svn co svn://svn.librelogiciel.com/pykota/trunk pykota 
    261  
    262 You can now check if the dependencies are correct by typing : 
    263  
    264     $ python checkdeps.py 
    265      
    266     An availability report for all the software needed by PyKota 
    267     will be displayed : you'll have to install the missing 
    268     software if you want PyKota to work correctly. 
    269      
    270 To install the software, just type : 
    271  
    272     $ python setup.py install 
    273  
    274 You may need to be logged in with sufficient privileges (e.g. root) 
    275  
    276 If you use Debian or Ubuntu, and want to use PostgreSQL as the 
    277 database backend, just type : 
    278  
    279     $ pksetup debian 
    280      
    281 or :     
    282  
    283     $ pksetup ubuntu 
    284      
    285 and follow the instructions to install PyKota in interactive mode, then 
    286 skip the remaining of the section below. 
    287  
    288 Otherwise, you have to setup manually : 
    289  
    290 Create a system user for PyKota : 
    291  
    292     $ adduser --system --group --home /etc/pykota --gecos PyKota pykota 
    293      
    294 Put the user your printing system is run as in the pykota system group : 
    295  
    296     $ adduser lp pykota 
    297      
    298     NB : on our system, the CUPS printing system runs as system user 'lp'. 
    299     Please adapt this to your own system. 
    300  
    301 Go to the initscripts/ subdirectory of PyKota's sources, and choose 
    302 the appropriate storage backend for your configuration. Read carefully 
    303 the associated README file, modify the initialization script to 
    304 change the passwords, or, in the case of the LDAP backend, adapt it 
    305 to your own LDAP DIT, and execute the initialization script 
    306 to create an empty PyKota database. Upgrade scripts may be  
    307 provided as well. NB : if you use PostgreSQL, a good way to 
    308 make PyKota work first time is to modify PostgreSQL's pg_hba.conf 
    309 to allow the 'trust' database connection mode. However once PyKota 
    310 works it is HIGHLY RECOMMENDED TO CHANGE THIS TO A MORE SECURE 
    311 VALUE. Look at the SECURITY document, PyKota's Official documentation 
    312 and PostgreSQL's documentation for details on this subject. 
    313  
    314 Copy the conf/pykota.conf.sample and  conf/pykotadmin.conf.sample  
    315 sample configuration files to ~pykota/pykota.conf and  
    316 ~pykota/pykotadmin.conf   
    317 The installation script usually copies these files into /usr/share/pykota 
    318  
    319 NB : You can move PyKota's configuration files elsewhere, they will 
    320 be searched first in user pykota's home directory, then in /etc/pykota. 
    321  
    322 You need to adapt these files to your own needs. Especially you may  
    323 have to create sections named after your own printers, and change  
    324 the administrator's email address which by default is  
    325 root@localhost. Read and try to understand these two very well  
    326 commented files, so that you'll encounter less problems later.  
    327  
    328 The rest of the installation depends on your printing system : 
    329  
    330   - CUPS Printing System : 
    331    
    332     Once and for all : 
    333      
    334         Create a symbolic link to the cupspykota backend  
    335         in CUPS's backend directory : 
    336          
    337           $ cd /usr/lib/cups/backend 
    338           $ ln -s /usr/share/pykota/cupspykota cupspykota 
    339            
    340         If you use CUPS v1.2 or higher, please do this as well :   
    341          
    342           $ chmod 700 /usr/share/pykota/cupspykota 
    343            
    344           This allows the cupspykota backend to support other 
    345           backends which must be run as user root, like the 
    346           lpd backend for example. 
    347            
    348         Restart CUPS so that the new backend can be detected. 
    349          
    350           $ /etc/init.d/cupsys restart 
    351            
    352           for example under Debian, or any similar command depending  
    353           on your operating system of choice. 
    354            
    355     For new printers : 
    356      
    357         Go to CUPS management interface (http://localhost:631)  
    358         and choose the appropriate PyKota managed device depending 
    359         on the type of printer you use. For example, if your 
    360         printer is waiting on : 
    361          
    362             socket://myprinter.example.com:9100 
    363              
    364         Then choose :     
    365          
    366             cupspykota:socket://myprinter.example.com:9100 
    367              
    368         Configure your printer as usual.     
    369          
    370         Now double check /etc/pykota/pykota.conf  
    371          
    372         You should manually create a section named after the 
    373         printer you've just added, unless you have set 
    374         all options globally. 
    375          
    376         The new pkturnkey command can help you with correct settings  
    377         for your printers. To have pkturnkey give you some hints 
    378         about what to put into pykota.conf for a particular 
    379         print queue, just use its --doconf command line switch : 
    380          
    381           $ pkturnkey --doconf TheNameOfThePrintQueue 
    382          
    383         pkturnkey will try to tell you what is the best accounting 
    384         method for each printer and will print some lines you'll 
    385         just have to copy&paste in the appropriate sections in 
    386         /etc/pykota/pykota.conf 
    387          
    388         For more informations about what pkturnkey can do for you, 
    389         see pkturnkey's manual page or use the --help command 
    390         line switch : 
    391          
    392           $ pkturnkey --help | less 
    393          
    394         That's all. 
    395      
    396     For existing print queues : 
    397      
    398         You want to route the print queue through PyKota, 
    399         and you can do this in several manners. 
    400          
    401           $ pkprinters --add --cups TheNameOfThePrintQueue 
    402            
    403         or    
    404          
    405           if your printer's DeviceURI is something like : 
    406            
    407               socket://myprinter.example.com:9100 
    408                
    409           then you can do this :     
    410            
    411           $ pkprinters --add TheNameOfThePrintQueue 
    412           $ lpadmin -p TheNameOfThePrintQueue \ 
    413                     -v cupspykota://socket://myprinter.example.com:9100 
    414            
    415         Finally, you could do it manually by modifying the  
    416         the DeviceURI lines in /etc/cups/printers.conf : 
    417         You would have to preprend 'cupspykota://' in front  
    418         of what is already on these lines. For example, replace : 
    419      
    420             DeviceURI socket://myprinter.example.com:9100 
    421          
    422         with :     
    423      
    424             DeviceURI cupspykota://socket://myprinter.example.com:9100 
    425              
    426         or :     
    427          
    428             DeviceURI cupspykota://socket://myprinter.example.com:9100 
    429          
    430         Save the file and restart CUPS for the changes to take effect. 
    431          
    432         Here too, you may find it interesting to use the pkturnkey command as 
    433         described above to help with manual configuration of the file 
    434         /etc/pykota/pykota.conf 
    435  
    436   - LPRng Printing System : 
    437    
    438     IMPORTANT : This release of PyKota DOES NOT support LPRng. 
    439      
    440     If you want to use PyKota with LPRng, you have to download 
    441     an earlier release of PyKota, for example v1.22HotFix1. 
    442          
    443 Now you can begin to populate the PyKota's database with printers, 
    444 users and groups : 
    445    
    446 Add printers and users to the quota system and set their quota values :  
    447  
    448 You can either use pkturnkey, or do the same things manually by 
    449 using the pkprinters, pkusers and edpykota command line tools : 
    450  
    451 Create printers : 
    452  
    453     $ pkprinters --help 
    454      
    455     will tell you how to create, manage or delete printers and 
    456     printers groups. 
    457      
    458     $ pkprinters --add --charge 0.05 hp2100 
    459      
    460     would add the printer named hp2100 with a price per page 
    461     of 0.05 unit. 
    462  
    463 Create users : 
    464  
    465     $ pkusers --add --limitby balance --balance 10.0 jerome 
    466      
    467     would create user jerome and give him ten credits to spend 
    468     on any printer. 
    469      
    470 Finally create print quota entries : 
    471  
    472     $ edpykota --add --printer hp2100 john paul george ringo 
    473          
    474     This will create print quota entries for The Beatles on     
    475     printer hp2100. The print quota entry holds the number of 
    476     pages printed on a particular printer for a particular 
    477     user, as well as optional page limits to be used instead 
    478     of balance limits. See pkusers and edpykota's manual 
    479     pages for details. 
    480      
    481 Your users now should be able to print but not exceed their  
    482 printing quota. 
    483  
    484 To see printer quota usage on printer hp2100, you can use : 
    485  
    486     $ repykota --printer hp2100 
    487      
    488 or : 
    489  
    490     $ repykota 
    491      
    492     which will print quota usage for all users on all printers, 
    493     along with totals, if you are a PyKota Administator. If you are 
    494     a regular user, only your own quota report will be produced. 
    495      
    496 You can also use these commands :     
    497  
    498     $ pkusers --list  
    499     $ edpykota --list 
    500      
    501     $ pkusers --list john paul george ringo 
    502     $ edpykota --list --printer hp2100 john paul george ringo 
    503      
    504 Quota reports are also available remotely by using the CGI script 
    505 printquota.cgi provided in the cgi-bin/ subdirectory. You can  
    506 also use the CSS stylesheet present in the stylesheets/ subdirectory 
    507 and put it at your web server's DocumentRoot, to benefit from a nicer  
    508 look, especially quota violations will appear in different colors. 
    509  
    510 For additionnal security concerns, please give a look at the SECURITY 
    511 file which is part of this software. 
    512  
    513 To diagnose a problem when something doesn't work as expected, 
    514 please read this FAQ entry : 
    515  
    516   http://otrs.librelogiciel.com/otrs/public.pl?ID=2 
    517             
    518 ============================================================ 
    519  
    520 Additionnal tools : 
    521 ------------------- 
    522  
    523 Some people have developped tools around PyKota, and make 
    524 them available under the GNU General Public License : 
    525  
    526   - Kanakorn Horsiritham developped phpPykotaAdmin which is  
    527     a web based database independant administrative GUI, 
    528     written in PHP. 
    529    
    530       http://opensource.psu.ac.th/~kanakorn/mambo/ 
    531        
    532     He was also kind enough to write an installation guide   
    533     in english for CUPS and PyKota with phpPykotaAdmin on Fedora 
    534     Core 3. You'll find this document on the same website. 
    535      
    536     This great software currently at version 0.3 is a wonderful 
    537     basis for an administrative GUI since it only depends on  
    538     PyKota commands to be present to successfully manage 
    539     PyKota's database.  
    540      
    541     However this tool is very old now and doesn't work 
    542     with more recent versions of PyKota. It could be 
    543     a good starting point if you planned to develop such 
    544     a web user interface though. 
    545    
    546 Additionnal software will be listed here when they will be   
    547 ready. 
    548  
    549 ============================================================ 
    550  
    551 Mailing list : 
    552 -------------- 
    553  
    554   A mailing list is dedicated to Pykota, you can subscribe to it 
    555   or consult its archives at : 
    556    
    557     http://cgi.librelogiciel.com/mailman/listinfo/pykota 
    558      
    559   The mailing list is the preferred way to obtain support, because   
    560   all members can help and can also benefit from the solutions 
    561   proposed by other members.  
    562    
    563   Posts by non-members are usually rejected. 
    564    
    565   The mailing list language is english and only english. 
    566      
    567 IRC :     
    568 ----- 
    569  
    570   You can also chat with us : 
    571    
    572         /server irc.freenode.net 
    573         /join #pykota 
    574          
    575   Preferred language on this channel is english, but french       
    576   is also accepted. Try to avoid exposing complex problems 
    577   in french because english speaking people on the channel 
    578   wouldn't benefit from the solutions. 
    579    
    580   PyKota's main author is known as 'tamere' on IRC. 
    581      
    582 ============================================================ 
    583      
    584 Please e-mail bugs to the mailing list at : pykota@librelogiciel.com 
    585 or to the main author at : alet@librelogiciel.com (Jerome Alet) 
     43=============================================================================