Changeset 1186

Timestamp:

11/15/03 15:26:45 (21 years ago)

Author:

jalet

Message:

General improvements to the documentation.
Email address changed in sample configuration file, because
I receive low quota messages almost every day...

Location:

pykota/trunk

Files:

• bin/cupspykota (modified) (2 diffs)
• conf/pykota.conf.sample (modified) (3 diffs)
• FAQ (modified) (3 diffs)
• README (modified) (6 diffs)
• SECURITY (modified) (3 diffs)

pykota/trunk/bin/cupspykota

@@ -24 +24 @@
 #
 # $Log$
+# Revision 1.8  2003/11/15 14:26:44  jalet
+# General improvements to the documentation.
+# Email address changed in sample configuration file, because
+# I receive low quota messages almost every day...
+#
 # Revision 1.7  2003/11/14 22:05:12  jalet
 # New CUPS backend fully functionnal.
@@ -158 +163 @@
     # It's there just in case this changes in the future.
     # But here we will IGNORE SIGTERM for now, and see
-    # if we shouldn't pass it to the original backend
-    # instead.
+    # in a future release if we shouldn't pass it to the 
+    # original backend instead.
     signal.signal(signal.SIGPIPE, signal.SIG_IGN)
     signal.signal(signal.SIGTERM, signal.SIG_IGN)
     
     #
-    # Get the last page counter and last username from the Quota Storage backend
+    # retrieve some informations on the current printer and user
+    # from the Quota Storage.
     printer = thebackend.storage.getPrinter(thebackend.printername)
     if not printer.Exists :

pykota/trunk/conf/pykota.conf.sample

@@ -57 +57 @@
 # but may be really interesting only with OpenLDAP.
 #
-# ACTIVATING CACHE IS HEAVILY RECOMMANDED WITH THE LDAP BACKEND !
+# ACTIVATING CACHE MAY CAUSE PRECISION PROBLEMS IN PRINT ACCOUNTING
+# IF AN USER PRINTS ON SEVERAL PRINTERS AT THE SAME TIME.
+# YOU MAY FIND IT INTERESTING ANYWAY, ESPECIALLY FOR LDAP.
 #
 storagecaching: No
@@ -120 +122 @@
 logger: system
 
-# Enable debugging ? Put YES instead here,
-# but only if something went wrong and you want
-# to learn from where the problem comes from.
+# Enable debugging ? Put YES or NO there.
+# From now on, YES is the default in this sample
+# configuration file, so that debugging is activated
+# when configuring PyKota. After all works, just
+# put NO instead to save some disk space in your
+# logs.
 # Actually only database queries are logged.
 debug : No
@@ -175 +180 @@
 # If these values are not set, the default admin root 
 # and the default adminmail root@localhost are used.
-admin: Jerome Alet
-adminmail: alet@librelogiciel.com
+admin: John Doe
+adminmail: root@localhost
 
 #

pykota/trunk/FAQ

@@ -27 +27 @@
     CUPS ?  
   
-    You have to define a new filtering chain for this, because most
-    probably your printer's PPD file already contain a *cupsFilter
-    line and only one is allowed. So it's impossible to plug PyKota
-    there. Search the mailing list archives to learn how to do.
+    From version 1.16alpha7, PyKota includes a CUPS backend which
+    allows you to use any type of printer and any driver.
     
   * How can I diagnose the problem when something goes wrong ?  
@@ -48 +46 @@
   * Some, not all, print jobs are never accounted for, why ?
   
-    Probably because some jobs were printed in raw mode.
-    Job printed this way are never filtered, and so PyKota
-    doesn't see them.
-    If you print to a CUPS server through Samba, delete the
-    "-o raw" command line option in smb.conf's print command 
-    entry, and restart Samba. Gimp also sets the "-o raw"
-    command line option some times. Be sure to disable
-    raw mode in CUPS configuration. Eventually recompile
-    CUPS without raw mode support at all.
+    From version 1.16alpha7, you can now use the cupspykota
+    CUPS backend, which ensures that all print jobs will be
+    accounted for. The use of the old pykota filter is deprecated
+    with CUPS. It remains the filter of choice for LPRng though.
     
   * When printing from Windows, the jobs are never accounted for,
@@ -74 +67 @@
     very specific, it will probably be added to this document.
     
+    You can also ask questions by IRC :
+    
+        /server irc.freenode.net
+        /join #pykota
+        
+    

pykota/trunk/README

@@ -161 +161 @@
   - The 'querying' method consists in querying the printer (via SNMP
     or Netatalk or any other method of your choice) for its total pages 
-    counter, just before the beginning of a job, and use this to modify 
-    the *preceding* user's quota. So you're always late of one print job, 
-    but this is generally ok, especially because a check is also done to 
-    see if the current user is allowed or not to print. 
+    counter.
+    
+    With CUPS, this is done both at the beginning and at the end of a
+    print job. The counters difference is then immediately used to 
+    decrease the user's account balance or increase his quota usage.
+    
+    With LPRng, this is done just before the beginning of a job, and used 
+    this to modify the *preceding* user's quota. So you're always late 
+    of one print job, but this is generally ok, especially because a 
+    check is also done to see if the current user is allowed or not to 
+    print. 
     
   - The 'external' method consists in delegating the computation of the
     job's size in number of pages to any external command of your choice.
     The command can read the job's data from its standard input and MUST
-    output the job's size on its standard output.
+    output the job's size on its standard output. Changes to the user
+    account are reported immediately, both with CUPS and LPRng.
     
   - The 'stupid' method consists in counting the 'showpage' PostSript  
     statements in the job. THIS IS UNRELIABLE, but can serve as an
     example if you plan to write your own accounting method for
-    integration into PyKota.
+    integration into PyKota. It basically works like the 'external'
+    method, but does the computation internally.
   
 PyKota is known to work fine with HP Laserjet 2100 and 2200, and 
@@ -189 +198 @@
 =============
 
-WARNING :
-=========
-
-  If you run a PyKota version lower than 1.03, you definitely have to 
-  upgrade you Quota Storage Database. Please read the documentation 
-  included in the initscripts subdirectory first ! 
-  
+NB :
+====
+
   Users of MacOS-X may find the following tutorial useful :
 
@@ -219 +224 @@
       if you plan to use OpenLDAP as the Quota Storage backend.
     
+  You may also benefit from having the following tools installed to
+  deal with some printers :
+  
+    - npadmin
+    - netcat
+    - ghostscript
+    
   You need to have the following tools installed on the Quota Storage  
   Server :
@@ -272 +284 @@
 provided as well.
 
-Copy the conf/pykota.conf.sample and  conf/pykotadmin.conf.sample
+Copy the conf/pykota.conf.sample and  conf/pykotadmin.conf.sample 
 sample configuration files to /etc/pykota/pykota.conf and 
-/etc/pykota/pykotadmin.conf. The installation script tries to do this 
-for you if needed and you agreed to this action.
-You need to adapt these files to your own needs.
-Especially you have to create sections named after your own
-printers, and change the administrator's email address.
+/etc/pykota/pykotadmin.conf. The installation script tries to do 
+this for you if needed and you agreed to this action. You need to 
+adapt these files to your own needs. Especially you have to create 
+sections named after your own printers, and change the 
+administrator's email address which by default is root@localhost.
+Read and try to understand these two very well commented files,
+so that you'll encounter less problems later.
+Also be sure to double check that commands to query printers
+for their internal page counter work from the command line
+before using them in PyKota's configuration.
+
+The rest of the installation depends on your printing system :
 
   - CUPS Printing System :
@@ -309 +328 @@
         Configure your printer as usual.    
         
+        Now double check /etc/pykota/pykota.conf 
+        This file should contain a section named after the
+        printer you've just added.
+        
         That's all.
     
     For existing printers :
     
-        If you had already installed PyKota, then remove
-        the *cupsFilter lines in your PPD files for each
-        printer already managed printers. Each line to
-        remove is of the form :
+        If you had already installed a version of PyKota earlier 
+        than 1.16alpha7, then remove the *cupsFilter lines in your 
+        PPD files for each printer already managed printers. Each 
+        line to remove is of the form :
         
           *cupsFilter: "application/vnd.cups-postscript 0 /usr/bin/pykota"
         
         Don't touch anything else, especially any other *cupsFilter line.
-        Then save each of these files and restart CUPS.
+        Then save each of these files.
         
         Then, the easiest is to directly modify the DeviceURI lines 
@@ -344 +367 @@
     
     For each printer on which you want to use print accounting.
+    
+    And then save the file and restart LPRng :
+    
+        $ /etc/init.d/lprng restart
+        
+Now you can begin to populate the PyKota's database with printers,
+users and groups :
   
 Add printers and users to the quota system and set their quota values : 

pykota/trunk/SECURITY

@@ -30 +30 @@
 ----------------------------------
 
-  - In CUPS disable RAW printing, so that users can't bypass the accounting
-    filter.
-    
-  - Ensure that only the user your printing system is run as can
-    execute the pykota filter. Depending on your system's configuration,
-    this may give something like :
-    
-      $ chown lp.daemon /usr/bin/pykota
-      $ chmod 700 /usr/bin/pykota
-      
-    If any user could run the pykota filter, then he theorically could 
-    forbid any other user to print by incorrectly charging them for
-    pages they would never have printed.
-    
-  - Ensure that only the print quota administrator (e.g. root) can 
-    execute the edpykota and warnpykota commands. Depending on your 
-    system's configuration, this may give something like :
-    
-      $ chown root.root /usr/bin/edpykota /usr/bin/warnpykota
-      $ chmod 700 /usr/bin/edpykota /usr/bin/warnpykota
-      
-    or   
-    
-      $ chown root.lpadmin /usr/bin/edpykota /usr/bin/warnpykota
-      $ chmod 750 /usr/bin/edpykota /usr/bin/warnpykota
-      
-    If any user could run warnpykota, then he could fill the mailboxes
-    of all users who are above quota, by repeatedly running warnpykota.
-    
-    If any user could run edpykota, then he could, in the better case,
-    set his account to noquota mode. In the worst case he could render
-    PyKota and/or your printing system completely inoperative.
+  - Most of the stuff which was there was deleted because PyKota's
+    configuration files permissions should take care of most
+    security problems. BUT of course, you have to set them correctly !
     
   - Ensure that no regular user can read PyKota administrator's 
@@ -75 +46 @@
     
     Letting any user read PyKota administrator's configuration file may 
-    expose passwords or database information which would allow direct 
-    connections to it if the user can write and execute his own scripts 
-    or download and execute his own version of PyKota. 
+    expose passwords or database information which would allow write
+    access to the database, and so may transform your print quota
+    management in a nightmare.
   
     If you want to let users generate their own print quota reports, 
@@ -115 +86 @@
     Otherwise they could modify their quota at will.
     
+    You also have to define two binding DNs in your LDAP tree,
+    one of them should be able to have a read only access to
+    everything. The other one should be able to write, for 
+    example your LDAP admin user is fine for this.
+    Now put the readonly user in /etc/pykota/pykota.conf
+    and the read-write one in /etc/pykota/pykotadmin.conf
+    
 ====================================================================