root / pykota / trunk / conf / pykota.conf.sample @ 3547

# PyKota sample configuration file
#
#
# File format :
#
#   - A mandatory [global] section :
#
#     Contains configuration directives which apply for all printers.
#     Some directives MUST be set in the [global] section, e.g.
#     database related directives.
#
#   - Any number of optional [PrintQueueName] sections :
#
#     Contain directives which apply for a particular print queue only.
#
#     Override the values of the same directives present in [global].
#
#
# Directives format :
#
#   - Directive's name, followed by ':' followed by the directive's value.
#
#   - No leading whitespace : leading whitespace tell the parser that the
#     current directive is the continuation of the previous one. Use with
#     care and only when you need it.
#
#
# PyKota - Print Quotas for CUPS
#
# (c) 2003-2009 Jerome Alet <alet@librelogiciel.com>
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
#
# $Id$
#


#
# All directives must be placed below the following line
[global]

# This directive configures the charset to use when reading PyKota's
# configuration files. All directives values will be decoded and
# interpreted using the character set defined here.
# This value can only be present in the [global] section.
#
# When not set, the default value 'UTF-8' is used.
config_charset : UTF-8

####################################################################
# SQLite3 : comment this section out if you use another backend    #
####################################################################

#storagebackend : sqlitestorage
#storagename: /etc/pykota/pykota.db

####################################################################



############################################################################
# PostgreSQL or MySQL: comment this section out if you use another backend #
############################################################################
storagebackend: pgstorage
# storagebackend: mysqlstorage

# Quota Storage Server hostname (and optional port)
# e.g. db.example.com:5432 (for PostgreSQL) or db.example.com:3306 (for MySQL)
# NB : leave the directive empty to use unix sockets (same host only)
# NB : Using the word 'localhost' for MySQL defaults to a UNIX socket
#      connection, which may be unexpected. Using 127.0.0.1 avoids this issue.
#      See http://bugs.mysql.com/bug.php?id=31577 for more information.
storageserver: 127.0.0.1

#
# name of the Quota Storage Database
storagename: pykota

#
# Quota Storage normal user's name and password
# These two fields contain a username and optional password
# which may give readonly access to your print quota database.
#
# PLEASE ENSURE THAT THIS USER CAN'T WRITE TO YOUR PRINT QUOTA
# DATABASE, OTHERWISE ANY USER WHO COULD READ THIS CONFIGURATION
# FILE COULD CHANGE HIS PRINT QUOTA.
#
storageuser : pykotauser
# In the line below change the password's value if needed.
storageuserpw : readonlypw

############################################################################



####################################################################
# LDAP : comment this section out if you use another backend       #
####################################################################
# LDAP example, uncomment and adapt it to your own configuration :
#
#storagebackend: ldapstorage
#storageserver: ldap://ldap.example.com:389
#storagename: dc=example,dc=com
#
# NB : the user and password below are the ones contained in
# the sample LDIF file pykota/initscripts/ldap/pykota-sample.ldif
# Please adapt these lines to your own needs.
#
#storageuser: cn=pykotauser,dc=example,dc=com
#storageuserpw: ls88DT5j



# TLS support for LDAP
#
# ldaptls can be set to either Yes or No
# the default value when not set is No, meaning that TLS won't be used.
#
#ldaptls: No
#
# cacert points to the CA Certificate file to use for TLS.
# Ensure that every user who can launch PyKota commands can read this file.
# There's NO default value for this directive.
#
#cacert: /etc/pykota/mycertfile



# Here we define some helpers to know where
# to plug into an existing LDAP directory
# NB : THE DIRECTIVES BELOW MUST BE PRESENT WITH AN LDAP BACKEND
# BUT YOU ARE FREE TO CHANGE THE VALUES.
#
#userbase: ou=People,dc=example,dc=com
#userrdn: uid
#balancebase: ou=People,dc=example,dc=com
#balancerdn: uid
#groupbase: ou=Groups,dc=example,dc=com
#grouprdn: cn
#printerbase: ou=Printers,ou=PyKota,dc=example,dc=com
#printerrdn: cn
#jobbase: ou=Jobs,ou=PyKota,dc=example,dc=com
#lastjobbase: ou=LastJobs,ou=PyKota,dc=example,dc=com
#billingcodebase: ou=BillingCodes,ou=PyKota,dc=example,dc=com

# These two fields are special, they either accept a branch
# dn, like an ou for example, or the special keywords 'user'
# and 'group'. If 'user' or 'group' is used, the print quota
# entries will be created below the user or group entry itself,
# which will then be used like a branch (you can mix and match
# different values depending on what you want to do).
#
# NB : YOU MUST CHOOSE A VALUE FOR USERQUOTABASE AND A VALUE
# FOR GROUPQUOTABASE, BUT ONLY ONE LINE OF EACH MUST BE PRESENT.
#userquotabase: user
#userquotabase: ou=UQuotas,ou=PyKota,dc=example,dc=com
#groupquotabase: group
#groupquotabase: ou=GQuotas,ou=PyKota,dc=example,dc=com



# How to create new accounts and groups
# authorized values are "below" and "attach(objectclass name [, fail|warn])"
#
# "below" creates the new accounts/groups as standalone entries
# below the above defined 'userbase' ou
#
# attach(objectclass name [, action]) tries to find some existing user/group
# using the above defined 'userrdn' or 'grouprdn' and 'userbase'
# 'groupbase', and attach the PyKota specific entries to it.
# if action is "warn" and no entry exists to attach to, a new
# entry is created, and a message is logged.
# if action is "fail" and no entry exists to attach to, program
# logs an error message and aborts.
# if action is not set, the default value is "fail".
#
# a possible value:  newuser: attach(posixAccount, warn)
#
#newuser : below
#newgroup : below



# LDAP attribute which stores the user's email address
#
#usermail : mail



# Choose what attribute contains the list of group members
# common values are : memberUid, uniqueMember, member
#
#groupmembers: memberUid



# Activate low-level LDAP cache yes/no
# Nothing to do with "storagecaching" which is higher level
# and database independant.
# This saves some search queries and may help with heavily
# loaded LDAP servers.
# This is EXPERIMENTAL.
#
# BEWARE : SETTING THIS TO 'YES' CAUSES PROBLEMS FOR NOW
# BETTER TO LET IT SET TO 'NO'
#
# ldapcache: no

####################################################################

#############################################################
# END of database specific directives                       #
#############################################################



# Should the database caching mechanism be enabled or not ?
# If unset, caching is disabled. Possible values Y/N/YES/NO
# caching mechanism works with both relationnal and OpenLDAP backends
# but may be really interesting only with OpenLDAP.
#
# 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.
#
# THERE'S NO GUARANTEE THAT THIS CACHING MECHANISM WILL IMPROVE
# PERFORMANCE WITH RELATIONNAL BACKENDS. IT MIGHT EVEN MAKE
# PERFORMANCE DECREASE. AS ALWAYS : YMMV.
#
# FYI, I ALWAYS SET IT TO YES !
#
storagecaching: No



# Should full job history be disabled ?
# If unset or set to No, full job history is kept in the database.
# Disabling the job history can be useful with heavily loaded
# LDAP servers, to not make the LDAP tree grow out of control.
# Disabling the job history with a relationnal backend works too
# but it's probably less useful than with LDAP.
#
disablehistory: No



# Where to log ?
# supported values : stderr, system (system means syslog, but don't use
# 'syslog' here). if the value is not set then the default SYSTEM applies.
#
logger: system



# Enable debugging ? Put YES or NO there.
# debug is set to YES in this sample configuration file, so debugging
# is activated when configuring PyKota, which helps a lot. After all
# works, just put NO instead to save some disk space in your logs.
# NB : When set to YES, there is a very significant impact on performance
# when managing many users, printers or billing codes at once, because
# hundreds of thousands of log lines can be generated.
# When printing a job, typically around 250-300 log lines are generated,
# so the impact per job is really minimal. Note however that this will
# add up over a large number of jobs.
#
debug : Yes



# The URL to PyKota's logo when used from the CGI scripts.
# You can use your own logo by modifying the URL below.
# If not defined, the default URL is the same as the
# one defined below :
#
logourl : http://www.pykota.com/pykota.png



# The destination to which the web browser will be redirected
# when you click on the logo defined above.
# If not defined, the default URL is the same as the
# one defined below :
#
logolink : http://www.pykota.com/



# Mail server to use to warn users
# If the value is not set then localhost is used.
#
smtpserver: localhost



# Crash messages' recipient : in addition to the log files
# each software crash can be sent to the author of PyKota
# or any other person of your choice. By default this
# is disabled for privacy concerns (see below). The address
# pykotacrashed@librelogiciel.com reaches PyKota's author.
# The 'adminmail' (defined a bit below) is CCed.
#
# Privacy concerns : what is sent is only :
#
#        - a copy of the software's traceback
#        - a copy of the software's command line arguments
#        - a copy of the software's environment variables
#
# suggested value :
#
# crashrecipient: pykotacrashed@librelogiciel.com



# Email domain
# If the value is not set, and the mail attribute for the user
# is not set in the PyKota storage, be it LDAP (see usermail directive
# above) or a relationnal one, then email messages are sent to
# username@smtpserver
#
# If the value is set, then email messages are sent to
# username@maildomain using the SMTP server defined above
#
# Set the appropriate value below, example.com set as per RFC2606.
#
maildomain: example.com



# Should we modify usernames when printing ?
# Default is native, meaning usernames won't be modified.
# This is a [global] option only.
# Some people reported that WinXP sends mixed case usernames,
# setting usernamecase to 'upper' or 'lower' solves the problem.
# Of course you have to use uppercase or lowercase only when managing
# users with pkusers, because ALL database accesses are
# still case sensitive.
#
# If usernamecase is 'upper' or 'lower', the usernames received
# from the printing system are converted to uppercase or lowercase,
# respectively, at the start of printing, BUT ONLY when printing.
#
# If usernamecase is 'native', which is the default, strict case checking
# is done, this means that users 'Jerome' and 'jerome' are
# different. Printer and groups names are ALWAYS case sensitive.
#
# usernamecase : upper
# usernamecase : lower
usernamecase: native



# Should we split usernames on a specific separator when printing ?
# Default is No, i.e. if the value is unset.
# This is a [global] option only.
# This option adds support for Samba's Winbind utility, which
# prefixes usernames with domain name and separator character.
# Of course if you set this then you have to use NO separator when
# adding users with edpykota.
#
# If winbind_separator is set, the usernames received from the printing
# system are split on the separator's value, and only the last part
# (real username) is used.
#
# If winbind_separator is not set, which is the default, strict
# username equality checking will be done (modulo the setting
# of the 'usernamecase' directive), this means that users 'DOMAIN1/jerome',
# 'Domain2/jerome' and 'jerome' are different.
#
# winbind_separator: /



# When creating users or groups accounts, should we reject users
# or groups which are unknown from the system ?
# The default if unset is NO. This means that by default, you
# can create users or groups for which `getent passwd username`
# or `getent group groupname` returns nothing.
#
# Allowed values : Yes | No
# Default value : No
#
# reject_unknown: No



# Do we want to hide jobs' title, filename and options for privacy
# reasons ?
# This may be required in some countries (Italy comes to mind).
# Allowed values are YES and NO.
# If unset, the default value is NO, meaning that jobs' title, filename
# and options will be saved into the history.
# This option can't be set on a per printer basis, only into the
# [global] section.
#
privacy : no



# When the real CUPS backend fail, should we modify the
# user's page counters and account balance or not ?
# Also should we retry and if yes then how often and how many times ?
# If you trust your users, set it to "nocharge".
# If you think they found some mean to kill the real CUPS backend,
# then set it to "charge".
# If your print queues get regularly disabled by CUPS when the printers
# are switched off, you might want to set it to "retry:N:S" where
# N is the number of times the operation should be retried, and S is
# the delay in seconds during which PyKota will sleep before trying again.
# This 'retry' feature works in a way similar to Till Kamppeter's beh
# backend wrapper which offers this functionnality but is actually not
# compatible with PyKota (because of my own inability to master regular
# expressions).
# If N is 0, PyKota will retry indefinitely each S seconds until the
# backend succeeds, so you should use this with caution. If N is 0,
# of course neither "charge" nor "nocharge" will be honored.
# You can combine "charge" or "nocharge" with "retry:N:S" if you want,
# by separating the values with a comma as shown in the examples below.
# If unset, the default value is "nocharge", meaning that users won't be
# charged whenever a CUPS backend fails. This is the OPPOSITE
# behavior compared to PyKota versions prior to 1.24alpha2.
# This value can be set either globally or on a per printer basis
# If both are defined, the printer option has priority.
#
# onbackenderror : charge,retry:5:60
# onbackenderror : retry:0:300
# onbackenderror : retry:3:300,nocharge
# onbackenderror : charge
onbackenderror : nocharge



# Should we strip off some characters from the beginning of
# print jobs' titles ? This can be used to remove smbprn.??????
# which sometimes appear when printing in raw mode from Windows
# through Samba.
# This setting only applies at printing time.
# When not set, titles are used as received from the printing system.
# The default is to not strip any character off of jobs' titles.
# This value can be set either globally or on a per printer basis
# If both are defined, the printer option has priority.
#
# striptitle : smbprn.??????



# Should we launch a command to overwrite the job's ticket ?
# This allows a command to overwrite the username and/or the
# billing code used, or to deny or cancel the job.
# If unset no command is launched and the job's username and
# billing code are used as they are received.
# To overwrite the job's ticket, the command has to print
# on its standard output one or more of the following lines,
# without any prefix or space character :
#
#    USERNAME=the_username_we_want_to_overwrite_with
#    BILLINGCODE=the_billingcode_we_want_to_overwrite_with
#    REASON=reason_we_chose_deny_or_cancel
#    AUTH=NO (equivalent to DENY below)
#    DENY
#    CANCEL
#
# NB : the output of your command is entirely read, and the latest
# value seen is used, so you command can output several usernames
# or billing codes and only the latest ones will be used.
# If only USERNAME= lines are printed, the billing code,
# if any, is used unchanged.
# If only BILLINGCODE= lines are printed, the username is
# used unchanged.
# If DENY or CANCEL is output, neither the username nor the
# billing code can be overwritten.
# If REASON is output, that will be used in the notification in the case of
# DENY or CANCEL. Otherwise, the built-in reasons will be used.
#
# This value can be set either globally or on a per printer basis
# If both are defined, the printer option has priority.
#
# IMPORTANT :
#
#       If you use this directive to interact with the end user in
#       some way, for example through pknotify+pykoticon or similar
#       tools, you have to keep in mind that this directive, as all
#       the directives in pykota*.conf, is processed at the time
#       the print job reaches the top of the print queue, and not
#       at the time it enters the print queue. For heavily loaded
#       systems where several jobs are in the print queue at a given
#       time, there may be a significant delay between the moment the
#       user submits the print job, and the moment this directive is
#       processed.
#
# examples :
#
# overwrite_jobticket : /usr/bin/pknotify --destination $PYKOTAJOBORIGINATINGHOSTNAME:7654 --timeout 180 --denyafter 3 --checkauth --ask "Username:username:$PYKOTAUSERNAME" "Password:password:" "Billing code:billingcode:$PYKOTAJOBBILLING"
# overwrite_jobticket : /path/to/some/script/or/command



# Should we ask the end user for a confirmation about their print job ?
#
# Any script can be launched here. If your script prints CANCEL on
# its standard output, the job is cancelled, else processing of the
# job continues to next step.
#
# NB : the output of your command is read until CANCEL is found
# or all lines have been read.
#
# This value can be set either globally or on a per printer basis
# If both are defined, the printer option has priority.
#
# examples :
#
# askconfirmation : /usr/bin/pknotify --destination $PYKOTAJOBORIGINATINGHOSTNAME:7654 --timeout 120 --confirm "Hello $PYKOTAUSERNAME.\nPrint job $PYKOTAJOBID send to printer $PYKOTAPRINTERNAME is $PYKOTAPRECOMPUTEDJOBSIZE pages long\nand will cost you $PYKOTAPRECOMPUTEDJOBPRICE credits.\n\nYou currently have $PYKOTABALANCE credits.\n\nDo you really want to print ?"



# What should we do when we print and the billing code used is
# not present in the database ?
# The default value is 'create' which adds the billing code to the
# database.
# Other values can be :
#       deny
#     which silently rejects the job.
# or :
#       deny(your script here)
#     if you put the path to a script or command here, it is executed, for
#     example you can open a popup window explaining why the job was
#     rejected.
#
# This value can be set either globally or on a per printer basis
# If both are defined, the printer option has priority.
#
# unknown_billingcode : deny
# unknown_billingcode : deny(/usr/bin/pknotify --destination $PYKOTAJOBORIGINATINGHOSTNAME:7654 --timeout 60 --notify "The billing code specified is not allowed")
# unknown_billingcode : deny(/path/to/some/script)
# unknown_billingcode : create



# Where should we store our (temporary) files when printing ?
# if unset, defaults to a system directory dedicated to temporary
# files and evaluated at runtime (see Python's documentation
# for the tempfile.gettempdir() function).
# This value can be set either globally or on a per printer basis
# If both are defined, the printer option has priority.
# On my system, when not set, the /var/spool/cups/tmp directory is used.
# directory : /tmp
# directory : /var/spool/cups



# Should we keep our work files on disk after printing ?
# If unset, temporary files are deleted once the work is finished.
# If set to yes, files are kept on disk in the 'directory'
# named with the previous directive.
# This value can be set either globally or on a per printer basis
# If both are defined, the printer option has priority.
# Default value is No, meaning temporary files are deleted
# You should set it to yes only during installation to not
# waste disk space during normal use.
#
# keepfiles : yes
keepfiles : no



# What is the accounting backend to use : this defines the way PyKota
# will compute the number of pages printed. This directive is the most
# important one in PyKota's configuration.
#
# NB : This directive is MANDATORY, there's no default value when not set.
#
# Supported values :
#
# - software([/path/to/some/script[ --with-args]])
# - hardware(snmp[:community]|pjl[:port]|/path/to/some/script[ --with-args])
#
# Hardware asks the printer for its lifetime page counter through either
# SNMP, PJL-over-TCP, or through any command of your choice. This is
# the recommended way to use PyKota, although it might not work with some
# printers. The page counter is asked twice per job : before the job
# is sent to the printer, and after it has been entirely sent.
# The big advantages of hardware accounting are lighter CPU usage compared
# to software accounting described below, although it can take more time
# because of necessary internal counter stabilization delays, and the fact
# that paper jams don't cause users to be charged for pages they couldn't
# print.
# For hardware accounting, two special values are accepted in addition
# to a script name : snmp and pjl. 'snmp' asks PyKota to use its internal
# SNMP code, 'pjl' asks PyKota to internally send a specially crafter PJL
# job to the printer's TCP port 9100 (by default).
#
# Software counts pages by parsing the print job's datas, either internally
# when no script is specified, or through any script of your choice.
# This works with ALL printers, provided you've got a script to parse
# datas produced by your printer driver. PyKota's internal parser, also
# available under the name 'pkpgcounter', recognizes several page description
# languages, but may occasionally fail for some printer drivers.
# You can however use any other command, provided it can read the datas to
# parse from the file pointed to by the PYKOTADATAFILE environment
# variable, and prints a single integer on its standard
# output, representing the number of pages in the print job.
# Software accounting unfortunately may overcharge users in case of paper
# jams.
#
# Ink computes the price of a print job by parsing the job's datas
# through pkpgcounter, and using the percents of ink coverage returned
# for each color in the specified colorspace.

# Supported colorspaces for ink accounting currently are :
#
#       bw      ===> Black & White
#       cmyk    ===> Cyan, Magenta, Yellow, Black
#       cmy     ===> Cyan, Magenta, Yellow
#       rgb     ===> Red, Green, Blue
#       gc      ===> Grayscale, Colored : this is a pseudo colorspace useful
#                    if all you need is differentiating grayscale from
#                    colored pages.
#
# Supported resolutions for ink accounting are any number of dots
# per inch comprised between 72 and 1200.
# IMPORTANT : increasing the resolution increases precision, but
# increase CPU load a lot at the same time. The default resolution
# if unset is 72, for 72 dpi.
# If you want to use ink accounting, you have to define a set of
# coefficients for each color in the colorspace, as explained
# further below in this file.
#
# You can get hints on which configuration is best for your printers by
# typing : pkturnkey --doconf
#
# In the lines below "%(printer)s" is automatically replaced at run time
# with your printer's Fully Qualified Domain Name for network printers,
# if PyKota can extract it from its environment.
#
# Examples :
#
# accounter : hardware(snmp)
# accounter : hardware(snmp:private)
# accounter : hardware(pjl)
# accounter : hardware(pjl:9101)
# accounter : hardware(/usr/share/pykota/waitprinter.sh %(printer)s && /usr/bin/snmpget -v1 -c public -Ov %(printer)s mib-2.43.10.2.1.4.1.1 | cut -f 2,2 -d " ")
# accounter : hardware(/usr/bin/npadmin --pagecount %(printer)s)
# accounter : hardware(/usr/share/pykota/papwaitprinter.sh "MyPrinter:LaserWriter@*" && /usr/bin/pap -p "MyPrinter:LaserWriter@*" /usr/share/pykota/pagecount.ps  2>/dev/null | /bin/grep -v status | /bin/grep -v Connect | /usr/bin/tail -1)
# accounter : hardware(/bin/cat /usr/share/pykota/pagecount.pjl >/dev/lp0 && /usr/bin/head -2 </dev/lp0 | /usr/bin/tail -1)
# accounter : hardware(/opt/local/net-snmp/bin/snmpwalk -v 1 -Cc -c public %(printer)s | grep mib-2.43.10.2.1.4.1.1 | cut -d " " -f4)
# accounter : hardware(/opt/local/net-snmp/bin/snmpwalk -v 1 -Cc -c public -Ov %(printer)s | grep Counter32 | tail -2 | head -1 | cut -d " " -f2)
# accounter : software(/usr/bin/pkpgcounter "$PYKOTADATAFILE")
# accounter : software()
# accounter : ink(cmyk, 150)
# accounter : ink(bw, 300)
# accounter : ink(bw)
# accounter : ink(cmy, 72)
# accounter : ink(gc, 72)
#
# This directive can be set either globally or per printer or both.
# If both are defined, the printer option has priority.
#
# IF YOU PLAN TO USE YOUR OWN SCRIPTS FOR HARDWARE ACCOUNTING,
# YOU ABSOLUTELY HAVE TO BE SURE YOU HAVE A SCRIPT WHICH WAITS FOR THE
# PRINTER BEING READY BEFORE ASKING FOR ITS INTERNAL PAGE COUNTER.
#
# PYKOTA'S 'snmp' and 'pjl' HARDWARE ACCOUNTING METHODS DO THE CORRECT WORK
# INTERNALLY, BUT SOME OF THE EXAMPLES ABOVE DON'T, YOU HAVE BEEN WARNED.
#
# WITH THE SPECIAL MAGIC hardware(snmp) AND hardware(pjl) VALUES, PYKOTA
# TAKES CARE OF ALL THIS FOR YOU, SO PLEASE UNDERSTAND THAT IT IS PREFERABLE
# TO USE THESE TWO METHODS : THEY WORK FINE, REQUIRE LITTLE TO NO CPU,
# AND DO ALL THE HARD WORK AUTOMATICALLY. IF YOU REALLY NEED TO YOU CAN USE
# YOUR OWN EXTERNAL COMMANDS AS DESCRIBED ABOVE, JUST BE CAREFUL WITH THIS.
#
# Sane default :
#
accounter: software()

# Should we ensure that the printer really is idle before
# sending the job's datas to it ?
#
# This directive is only used when you use an internal
# hardware accounting mechanism, like hardware(snmp) or
# hardware(pjl), and is not used for external hardware
# accounting mechanisms or for software or ink accounting.
#
# If PyKota and CUPS are properly configured, i.e. a single
# computer (the print server) can access to a particular physical
# printer, or all CUPS+PyKota print servers which access to the
# same physical printer share a common network directory used
# by PyKota to lock this printer resource, then it is not necessary
# to really ensure the printer is idle before the job, because
# this is already the case : we already wait at the end of the
# preceding job for the printer to be idle before reading its
# internal page counter. So setting this value to Yes usually
# saves a lot of time between jobs, generally around 30 seconds.
#
# If you're not sure, leave this value to the default which is No,
# meaning that before sending the job's datas to the printer, PyKota
# will ensure this printer is in idle state.
#
# If not defined, a value of No is assumed.
#
# This value can be set either globally or on a per printer basis
# If both are defined, the printer option has priority.
#
# Sane default :
#
skipinitialwait : no

# What is the "pre"-accounter used for precomputing the job's size.
#
# Supported values are :
#
#  preaccounter: software()
#  preaccounter: software(/path/to/your/script)
#  preaccounter: ink(colorspace, resolution)
#
# NB : the preaccounter directive doesn't support hardware() for obvious
# reasons. If unset, "software()" is assumed. If you use your own script,
# ensure that it only prints the job's number of pages (or an estimation
# of it) on its standard output, and that it reads the print job's datas
# from the file pointed to by the PYKOTADATAFILE environment variable.
#
# You may want to define for example 'preaccounter : software(/bin/echo 1)'
# in the case your printer supports an hardware accounter but pkpgcounter
# can't parse your printer driver's datas.
#
# Supported colorspaces for ink accounting currently are :
#
#       bw      ===> Black & White
#       cmyk    ===> Cyan, Magenta, Yellow, Black
#       cmy     ===> Cyan, Magenta, Yellow
#       rgb     ===> Red, Green, Blue
#       gc      ===> Grayscale, Colored : this is a pseudo colorspace useful
#                    if all you need is differentiating grayscale from
#                    colored pages.
#
# Supported resolutions for ink accounting are any number of dots
# per inch comprised between 72 and 1200.
# IMPORTANT : increasing the resolution increases precision, but
# increase CPU load a lot at the same time. The default resolution
# if unset is 72, for 72 dpi.
#
# This value can be set either globally or on a per printer basis
# If both are defined, the printer option has priority.
#
# Sane default :
#
preaccounter: software()



# What should we do if the accounter's subprocess doesn't return
# a valid result (for example doesn't return an integer on its stdout)
#
# Valid values are : 'continue' and 'stop'. 'stop' is the default
# if unset.
#
# 'continue' means try to process as usual, this may introduce
# accounting errors and free jobs. This was the default behavior
# until v1.20alpha5.
#
# 'stop' means fail and stop the print queue. If an accounter
# error occurs, most of the time this is a misconfiguration, so
# stopping the print queue is usually the best thing to do
# until the admin has fixed the configuration.
#
# This value can be set either globally or on a per printer basis
# If both are defined, the printer option has priority.
#
# NB : This directive shouldn't do much now because in case
# of external accounter error, PyKota just loops.
#
# onaccountererror: continue
onaccountererror: stop



# Print Quota administrator
# These values can be set either globally or per printer or both.
# If both are defined, the printer option has priority.
# If these values are not set, the default admin root
# and the default adminmail root@localhost are used.
admin: John Doe
adminmail: root@localhost



# Who should we send an email to in case a quota is reached ?
# possible values are : DevNull, User, Admin, Both, External(some command)
# The Both value means that the User and the Admin will receive
# an email message.
# The DevNull value means no email message will be sent.
# This value can be set either globally or per printer or both.
# If both are defined, the printer option has priority.
# If the value is not set, then the default BOTH applies.
#
#   Format of the external syntax :
#
#       mailto: external(/usr/bin/mycommand >/dev/null)
#
#   You can use :
#
#       '%(action)s'            will contain either WARN or DENY
#       '%(username)s'          will contain the user's name
#       '%(printername)s'       will contain the printer's name
#       '%(email)s'             will contain the user's email address
#       '%(message)s'           will contain the message if you want
#                               to use it.
#
#   on your command line, to pass arguments to your command.
#   Examples :
#
#     mailto: external(/usr/bin/callpager %(username)s "Quota problem on %(printername)s" >/dev/null)
#
#   To automatically send a WinPopup message (this may only work with a PDC,
#   here the same machine does Samba as PDC + CUPS) :
#
#     mailto: external(echo "%(message)s" | /usr/bin/iconv --to-code utf-8 --from-code iso-8859-15 | /usr/bin/smbclient -M "%(username)s" 2>&1 >/dev/null)
#
#   NB : I use ISO-8859-15, but Windows expects UTF-8, so we pipe the message
#        into iconv before sending it to the Windows user.
#
# or more simply :
#
#     mailto: external(/usr/share/pykota/mailandpopup.sh %(username)s %(printername)s "%(email)s" "%(message)s" 2>&1 >/dev/null)
#
#   NB : The mailandpopup.sh shell script is now included in PyKota
#
#   NB : in ANY case, don't forget to redirect your command's standard output
#        somewhere (e.g. >/dev/null) so that there's no perturbation to the
#        underlying layer (filter or backend)
#
mailto : both



# The value of the zero for account balance limitations.
# If a user is limited by balance, he can print until
# his balance reaches the value defined here. If unset,
# the default value is 0. Any floating point value
# is accepted.
# You'll want to use this to give free credits to your users
# at the start of the year for example.
#
# This option can only appear in the global section
#
# balancezero : -0.25
#
balancezero: 0.0



# Grace delay in days
# This value can be set either globally or per printer or both.
# If both are defined, the printer option has priority.
# If the value is not set then the default seven (7) days applies.
#
gracedelay : 7



# Poor man's threshold
# If account balance reaches below this amount, a warning message
# is sent through the 'mailto' directive above.
#
# If unset, default poor man's threshold is 1.0.
# This option can only appear in the global section
#
poorman : 1.0



# Poor man's warning message
# The warning message that is sent if the "poorman" value is reached
# Again this must appear in the global section
#
poorwarn : Your Print Quota account balance is low.
 Soon you'll not be allowed to print anymore.



# Soft limit reached warning message
# The warning message that is sent if the soft quota limit is reached
# May appear either globally or on a per-printer basis
#
softwarn: Your Print Quota Soft Limit is reached.
 This means that you may still be allowed to print for some
 time, but you must contact your administrator to purchase
 more print quota.



# Hard limit reached error message
# The error message that is sent if the hard quota limit is reached
# May appear either globally or on a per-printer basis
#
hardwarn: Your Print Quota Hard Limit is reached.
 This means that you are not allowed to print anymore.
 Please contact your administrator at root@localhost
 as soon as possible to solve the problem.



# Default policy to apply when either :
#
#       - Printer doesn't exist in PyKota's database
#       - User doesn't exist in PyKota's database
#       - User has no quota entry for this Printer in PyKota's database
#
# Value can be either 'allow' or 'deny' or 'external(some command here)'
#
# 'Allow' means that the job will be printed even if the printer, the
# user or this user's print quota entry on this printer doesn't exist
# in PyKota's database. But the job won't appear in the printing history.
#
# 'Deny' means the job will be rejected if any of these three conditions
# is met.
#
# 'External' means any command of your choice will be launched if any
# of these three conditions is met. Once your command has ended, PyKota
# will try again to retrieve the printer, user or user's print quota
# entry from its database. If it fails to find any of them again, the
# job will be rejected.
#
# This value can be set either globally or per printer or both.
# If both are defined, the printer option has priority.
# If the value is not set then the default policy DENY applies.
# There's no policy wrt inexistant groups, they are ignored.
#
# external policy can be used to launch any external command of your choice,
# for example to automatically add the user to the quota database, and set
# page limits on the current printer if he is unknown :
#
#   policy: external(/usr/bin/pkusers --add --skipexisting %(username)s && /usr/bin/edpykota --add --skipexisting --printer %(printername)s --softlimit 50 --hardlimit 60 %(username)s)
#
# NB : If you want to limit users by their account balance value, it is preferable to
# use the following policy to automate user account creation on first print :
#
#   policy: external(/usr/bin/autopykota --initbalance 25.0)
#
#   This will automatically add the user if he doesn't already exist, and
#   set his initial balance value to 25.0 (for example). If the user already
#   exists then his balance value will not be modified.
#   Please don't use autopykota if you want to limit your users by page
#   quota, and in any case, carefully read autopykota's help or manpage
#   and understand its goal before using it in your own configuration.
#
# Of course you can launch any command of your choice with this, e.g. :
#
#   policy: external(/usr/local/bin/myadminscript.sh %(username)s)
#
# You can use :
#
#       '%(username)s'          will contain the user's name
#       '%(printername)s'       will contain the printer's name
#
#   On your command line, to pass arguments to your command.
#
# If the printer, user, or user quota entry still doesn't exist after
# external policy command was launched (the external command didn't add it),
# or if an error occured during the execution of the external policy
# command, then the job is rejected.
#
# By default, we reject all jobs from users not in the database :
#
policy: deny



# Pre and Post Hooks
# These directives allow the easy plug-in of any command of your choice
# at different phases of PyKota's execution.
# Pre and Post Hooks can access some of PyKota's internal information
# by reading environment variables as described below.
# The actual phase of PyKota's execution is available in the
# PYKOTAPHASE environment variable.
# Pre and Post Hooks can be defined either globally, per printer,
# or both. If both are defined, the printer specific hook has
# priority.
#
# List of available environment variables :
# NB : Most of these variables are also available during the execution
# of external commands defined in the accounter and mailto
# directives.
#
# PYKOTADIRECTORY : The directory containing cupspykota's temporary files
# PYKOTADATAFILE : The name of the temporary file which contains the
#                  job's datas
# PYKOTAFILENAME : The name of the file which contains the job's datas or
#                  empty if datas come from stdin
# PYKOTAMD5SUM : Contains an hexadecimal digest of the md5 sum of the job's datas
# PYKOTAPHASE : BEFORE or AFTER the job is sent to the printer
# PYKOTAACTION : ALLOW or DENY or WARN for current print job
# PYKOTAUSERNAME : user's name, possibly modified through the overwrite_jobticket directive.
# PYKOTAORIGINALUSERNAME : user's name, unmodified.
# PYKOTAPRINTERNAME : printer's name
# PYKOTAPGROUPS : list of printers groups the current printer is a member of
# PYKOTAJOBID : job's id
# PYKOTATITLE : job's title
# PYKOTACOPIES : number of copies
# PYKOTAOPTIONS : job's options
# PYKOTABALANCE : user's account balance
# PYKOTALIFETIMEPAID : user's grand total paid
# PYKOTALIMITBY : user print limiting factor, for example 'quota' or 'balance'
# PYKOTAPAGECOUNTER : user's page counter on this printer
# PYKOTALIFEPAGECOUNTER : user's life time page counter on this printer
# PYKOTASOFTLIMIT : user's soft page limit on this printer
# PYKOTAHARDLIMIT : user's hard page limit on this printer
# PYKOTADATELIMIT : user's soft to hard limit date limit on this printer
# PYKOTASTATUS : contains "CANCELLED" when SIGTERM was received by PyKota
#                else is not set.
# PYKOTAJOBSIZEBYTES : contains the job's size in bytes. Always available.
# PYKOTAPRECOMPUTEDJOBSIZE : contains the precomputed job's size
# PYKOTAPRECOMPUTEDJOBPRICE : contains the precomputed job's price
# PYKOTAJOBORIGINATINGHOSTNAME : contains the client's hostname if
#                                it is possible to retrieve it.
# PYKOTAPRINTERHOSTNAME : the printer's hostname or IP address for network
#                         printers, or "localhost" if not defined or not
#                         meaningful.
# PYKOTAWARNCOUNT : the number of times the user was forbidden to print but a banner
#                   page was still printed on the current printer.
# PYKOTAOVERCHARGE : user's overcharging factor.
# PYKOTAJOBBILLING : Job's billing code if present, possibly modified through the overwrite_jobticket directive.
# PYKOTAORIGINALJOBBILLING : Job's billing code if present, unmodified.
# PYKOTAREASON : if the job was denied or a warning needs to be issued, contains
#                the message to send to the user.
# PYKOTAUSERDESCRIPTION : the user's textual description
# PYKOTAPRINTERDESCRIPTION : the printer's textual description
# PYKOTAPRINTERPASSTHROUGHMODE : the printer's passthrough mode
# PYKOTAPRINTERMAXJOBSIZE : the printer's maximal job size
# PYKOTAPRICEPERJOB : the printer's price per job
# PYKOTAPRICEPERPAGE : the printer's price per page
#


# PreHook : gets executed after being sure the user, printer and user quota
# entry on the printer both exist in the PyKota database, and after
# checking if the user is allowed to print or not, but just before
# the job is sent to the printer (if allowed)
# prehook has access to many environment variables :
#
# PYKOTAACTION contains either "ALLOW", "WARN" or "DENY" and
# represents the action which is to be done wrt the print job.
# PYKOTAPHASE contains 'BEFORE' during execution of prehook
#
# uncomment the line below to see what environment variables are available
# prehook: /usr/bin/printenv >/tmp/before



# PostHook : gets executed after the job has been added to the history.
# posthook has access to all the environment variables defined above,
# as well as two additionnal environment variables : PYKOTAJOBPRICE
# and PYKOTAJOBSIZE.
# PYKOTAPHASE contains 'AFTER' during execution of posthook.
#
# uncomment the line below to see what environment variables are available
# posthook: /usr/bin/printenv >/tmp/after



# AccountBanner : how should banner accounting be done ?
#
# If enabled, banner pages printed from StartingBanner and/or EndingBanner
# (depending on the value) will be included in the accounting for the
# print job
#
# If disabled, banner pages printed from StartingBanner and EndingBanner will
# *not* be included in the accounting for the print job
#
# IMPORTANT : CUPS generated banners are ALWAYS accounted for, although you
#             can refund them by using negative prices on printers.
#
# Allowed values : Starting | Ending | None | Both
#
#       - Starting : only the starting banner will be accounted for.
#       - Ending : only the ending banner will be accounted for.
#       - Both : both starting and ending banners will be accounted for.
#       - None : banners will not be accounted for.
#
# Default value :
# accountbanner: Both



# Maximal number of times the banner will still be printed if
# the user is forbidden to print.
#
# This option can be set either globally or on a per printer basis.
# Allowed values are 0 or any positive integer.
# Default value is 0, which means that the banner won't be printed
# at all if the user is forbidden to print.
#
maxdenybanners: 0



# If a job is cancelled, should any start or end banners still be printed
#
# This option can be set either globally or on a per printer basis.
# If set to yes, any defined banners will be printed
# If set to no, no banners will be printed
#
# This value defaults to yes
# printcancelledbanners: yes


# If a job is printed by the same person as the last job on the same printer,
# should banners be avoided to save some paper
#
# This option can be set either globally or on a per printer basis.
# If set to yes, any duplicate banners will be avoided forever
# If set to no or 0, no banners will be avoided (they will all be printed)
# If set to any positive integer, banners will be avoided if printed within
#     'integer' seconds of the last job
#
# This value defaults to no
# avoidduplicatebanners: yes
# avoidduplicatebanners: no
# avoidduplicatebanners: 600


# StartingBanner : if defined will print a banner before the rest of the job
# is printed. The argument can be a printable file, or an executable file.
# If not executable, the file will be printed as is. If executable, the
# file will be executed and its standard output will be sent to the printer.
#
# In any case, the banner content which will be sent to the printer
# MUST be in a format your printer will accept !!!
#
# The pkbanner command included in PyKota can automatically generate
# starting and ending banners in the PostScript format. You can use
# this command in a pipe through GhostScript if your printer doesn't
# accept PostScript as an input format.
# NB : pkbanner's default page size is A4
#
# startingbanner: /home/joe/mystaticbanner.ps
# startingbanner: /usr/bin/pkbanner --pagesize=A4 --logo="/home/joe/mylogo.jpeg" --url="http://tech.example.com"
# startingbanner: /usr/bin/pkbanner | gs -q -dNOPAUSE -dBATCH -dPARANOIDSAFER -sOutputFile=- -sDEVICE=lj5mono -
# startingbanner: /usr/bin/pkbanner



# EndingBanner : if defined will print a banner after the job
# has been printed. The argument can be a printable file, or an executable file.
# If not executable, the file will be printed as is. If executable, the
# file will be executed and its standard output will be sent to the printer.
#
# In any case, the banner content which will be sent to the printer
# MUST be in a format your printer will accept !!!
#
# The pkbanner command included in PyKota can automatically generate
# starting and ending banners in the PostScript format. You can use
# this command in a pipe through GhostScript if your printer doesn't
# accept PostScript as an input format.
# NB : pkbanner's default page size is A4
#
# A static banner page
# endingbanner: /home/joe/mystaticbanner.ps
#
# A banner with personnalized logo and url
# endingbanner: /usr/bin/pkbanner --pagesize=A4 --logo="/home/joe/mylogo.jpeg" --url="http://tech.example.com"
#
# A banner in the format accepted by the printer
# endingbanner: /usr/bin/pkbanner | gs -q -dNOPAUSE -dBATCH -dPARANOIDSAFER -sOutputFile=- -sDEVICE=lj5mono -
#
# A banner with more info on it, extracted from the yellow pages.
# the string "Phone 111222333444" will be added to the banner page
# if extractphone.sh returns 111222333444 for the current user.
# endingbanner: /usr/bin/pkbanner Phone `extractphone.sh $PYKOTAUSERNAME`
#
# Default PyKota banner
# endingbanner: /usr/bin/pkbanner



# How should enforcement be done for this printer ?
#
# "laxist" is the default if value is not set, and allows users
# to be over quota on their last job.
#
# "strict" tries to prevent users from ever being over quota.
#
# Enforcement can be defined either globally, per printer,
# or both. If both are defined, the printer specific enforcement
# setting has priority.
#
# valid values : "strict" or "laxist"
#
# default value when not set is "laxist"
#
# enforcement : laxist
enforcement : strict



# Should we trust the job size on this printer ?
#
# "trustjobsize : yes" is the default, the jobsize, either computed
# by the hardware or by software is trusted.
#
# "trustjobsize : >N:precomputed" : uses the precomputed value
#                                   if jobsize > N pages
# "trustjobsize : >N:25" : uses 25 if jobsize is >N pages
#
# General form : ">n:m" where n is a positive integer, and m is
# either the word 'precomputed' or a positive integer.
# The special form "yes" is also accepted and is the default.
#
# This directive can be set either globally or on a per printer
# basis. Use this directive when hardware accounting for a particular
# printer produces some glitches due to the printer returning
# incorrect answers.
#
# NB : DON'T MODIFY THIS IF YOU DON'T NEED TO. THIS IS ONLY TO BE USED
# AS A WORKAROUND FOR SOME PRINTERS. IT'S PROBABLY BETTER TO ALWAYS
# SET THIS DIRECTIVE TO 'yes'. THIS DIRECTIVE WILL ONLY BE HONORED
# IF PYKOTA DETECTS A DIFFERENCE BETWEEN THE PRECOMPUTED JOB SIZE
# AND THE JOB SIZE AS COMPUTED BY PYKOTA EITHER USING HARDWARE OR
# SOFTWARE.
#
trustjobsize : yes



# Should we deny duplicate jobs ?
#
# A duplicate is a job sent twice (or more) in a row to the same printer
# by the same user.
#
# This can be defined either globally or on a per printer basis
# The default value is 'no', meaning that duplicate jobs are
# allowed.
#
# NB : if an user prints a job, a second user prints another
#      job, and the first user prints the first job again,
#      this is NOT considered as a duplicate since the two
#      identical jobs printed by the first user are not
#      one just after the other.
#
# Possible values are 'yes', 'no', or any other string.
# If the string is not recognized as a truth value,
# it is considered to be a command to launch.
# PyKota launches the command and parses its standard
# output. The special keywords 'ALLOW' and 'DENY' are
# recognized, allowing an external tool to decide if
# the job is to be allowed or denied.
#
# denyduplicates : /usr/bin/myowncommand with some arguments
# denyduplicates : yes
denyduplicates : no



# Sets the delay in seconds after which two identical jobs are
# not considered as being a duplicate.
#
# This can be defined either globally or on a per printer basis
# The default value if not set is 0, for 0 seconds.
# duplicatesdelay : 300
duplicatesdelay : 0



# Sets the maximum number of seconds to wait for the printer
# being in 'printing' mode once the job has been sent to it.
# Once this delay is expired, PyKota will consider this job
# will never be printed, aborts the hardware accounting
# process, and uses the latest internal page counter value seen.
#
# Increasing this value, or setting it to 0, may help with some
# printers which don't conform to RFC3805. Problem reported on a
# Samsung ML2551n gave a way for clever students to bypass
# hardware accounting entirely by removing the paper from
# the paper tray before the job had begun to print, then
# waiting 60 seconds, and putting the paper back in the tray...
#
# IMPORTANT : always ensure that your printers' firmware is up
# to date.
#
# This directive can be set either globally or on a per printer
# basis.
#
# When not set, an hardcoded value of 60 seconds is used.
# When set to 0, PyKota will wait indefinitely until the
# printer switches to the 'printing' status.
noprintingmaxdelay : 60



# Defines the number of times the 'idle' printer status
# has to be reported before it being considered stable.
# Each check is done every 'statusstabilizationdelay' seconds
# as defined below.
#
# This directive can be set either globally or on a per printer
# basis.
#
# When not set, an hardcoded value of 5 times is used.
# The value must be a strictly positive integer.
statusstabilizationloops : 5



# Defines the number of seconds to wait between two consecutive
# checks of the printer's status when using hardware accounting.
#
# Each check is done up to 'statusstabilizationloops' times.
#
# This directive can be set either globally or on a per printer
# basis.
#
# When not set, an hardcoded value of 4.0 seconds is used.
# The value must be a positive floating point value greater
# than or equal to 0.25 seconds.
statusstabilizationdelay : 4.0



# Defines a (16 bits) bit mask to specify the set of error conditions
# reported through SNMP for which PyKota has to wait indefinitely
# until such an error is fixed before continuing with printing
# and/or accounting.
#
# This directive can be set either globally or on a per printer
# basis.
#
# The 16 bit values are specified as in RFC3805 (Printer MIB v2),
# as an ORed value of one or more of the following conditions :
#
#       1000 0000 0000 0000 : Low Paper
#       0100 0000 0000 0000 : No Paper
#       0010 0000 0000 0000 : Low Toner
#       0001 0000 0000 0000 : No Toner
#       0000 1000 0000 0000 : Door Open
#       0000 0100 0000 0000 : Jammed
#       0000 0010 0000 0000 : Offline
#       0000 0001 0000 0000 : Service Requested
#       0000 0000 1000 0000 : Input Tray Missing
#       0000 0000 0100 0000 : Output Tray Missing
#       0000 0000 0010 0000 : Marker Supply Missing
#       0000 0000 0001 0000 : Output Near Full
#       0000 0000 0000 1000 : Output Full
#       0000 0000 0000 0100 : Input Tray Empty
#       0000 0000 0000 0010 : Overdue Preventive Maintainance
#       0000 0000 0000 0001 : Not assigned
#
# When not set, an hardcoded value of hexadecimal 0x4FCC is used,
# which means that PyKota will wait indefinitely when using SNMP
# hardware accounting if one of the following conditions is met :
#
#   No Paper, Door Open, Jammed, Offline, Service Requested,
#   Input Tray Missing, Output Tray Missing, Output Full, Input Tray Empty
#
# This value can be specified either in hexadecimal (prefixed with 0x),
# in octal (prefixed with 0) or in decimal (no prefix).
#
snmperrormask : 0x4FCC



# Defines a set of coefficients for ink accounting.
#
# Each ink coefficient is the factor of the price per page
# you set with pkprinters which would represent the cost
# of a page covered at 100% with ink in this particular color.
#
# With these coefficients, the exact cost of each page
# can be computed : for each ink color in the colorspace specified
# in the preaccounter and/or accounter directives, we multiply the
# base cost per page set with pkprinters by this ink color's coefficient
# and by the percent of that page covered with such ink. Then we
# sum the values, and repeat the operation for each page. We then
# add the base cost per job set with pkprinters, and repeat
# the operation recursively in case of nested printers groups.
#
# The names of the coefficients you should set depend on the colorspace
# you want to use for ink accounting :
#
#       cmyk :
#               coefficient_cyan
#               coefficient_magenta
#               coefficient_yellow
#               coefficient_black
#
#       cmy :
#               coefficient_cyan
#               coefficient_magenta
#               coefficient_yellow
#
#       rgb :
#               coefficient_red
#               coefficient_green
#               coefficient_blue
#
#       bw :
#               coefficient_black
#
#       gc :
#               coefficient_grayscale
#               coefficient_colored
#
# Any coefficient which is not set is considered to be equal to 1.0
#
# Coefficients can be set either in the [global] section or in any
# [printqueuename] section. The latter taking precedence, as always.
#
#coefficient_cyan : 1.2
#coefficient_magenta : 3
#coefficient_yellow : 1.1
#coefficient_black : 1.0