Written by Urs-Jakob Rüetschi
as part of the pracc project.
Command-line tools to work with Pracc.
All tools have a -V and a -h option; -V shows the tool's name and version, -h shows a short help message; both print to standard output and then exit successfully.
All tools use these exit codes: 0 for success, 111 for temporary errors, and 127 for permanent errors.
Tools that modify pracc files document their activity by appending a line to the pracc.log file.
Usage: pracc-init [-fF] account balance limit {info}
Create a pracc file for account with the given initial balance (zero or greater) and limit (any integer). A value of "none" (without the quotes) for limit means no limit. Optional info arguments are appended to the pracc file header line.
If -f is specified, re-create the pracc file even if it
already exists.
If -F is specified, quit successfully if the pracc file
already exists.
Otherwise just complain and leave the existing file alone.
Example of an initial pracc file with balance=500 and limit=9 for user wimmer (additional info: Waldemar Immerfroh):
#pracc-v2-0-wimmer Waldemar Immerfroh $9 @4000000042cd8078 root minimum balance =500 @4000000042cd8078 root initial credit
Usage: pracc-edit account action arg {info}
Perform action on account. The action is one of debit, credit, reset, limit, note; it means to atomically append a line of that type to the pracc file. Depending on action, arg is an amount, a balance, or a limit. The special limit "none" (without the quotes) makes the account unlimited.
Must be root or in group pracc to use this tool. Do not install it set-gid pracc!
Usage examples and the corresponding lines that are appended:
# pracc-edit wimmer credit 500 new credits +500 @4000000042d0691c root new credits # pracc-edit wimmer debit 500 storno -500 @4000000042d06951 root storno # pracc-edit wimmer reset 500 new balance =500 @4000000042d06a05 root new balance # pracc-edit wimmer limit none account now unlimited $* @4000000042d06a7b root account now unlimited # pracc-edit wimmer limit -1000000 new limit *-1000000 @4000000042d06ac3 root new limit # pracc-edit wimmer note merry x-mas # merry x-mas
Scripts like this one might be useful:
#!/bin/sh
USAGE="Usage: pracc-credit account amount {info}"
usage() { test "$*" && echo $*; usage $USAGE; exit 127; }
test -n "$1" && ACCOUNT="$1" || usage "missing account"
test -n "$2" && AMOUNT="$2" || usage "missing amount"
shift 2 && pracc-edit "$ACCOUNT" credit "$AMOUNT" $*
Usage: pracc-view [options] account
Print the given account to standard output. Errors in the pracc file are reported to standard error. Use one or more of the following options to view only records that match all of the restrictions specified:
Dates are in yyyy-mm-dd format, e.g., 2005-07-15.
Valid types are: debit, credit, reset, limit, note.
Use -t more than once to select several types.
Usage: pracc-kill [-f] account [comment]
Delete the given account and note this fact, along with any comment arguments, to the common log file. Use -f to really delete the account, without this flag just pretend.
Usage: pracc-sum [options] account
Summarise the given account by printing to standard output its balance B, limit L, sum of credits Sc, sum of debits Sd, and the date/time of the account's last use.
acct name balance B limit L credits Sc debits Sd last yyyy-mm-dd
Optionally, summarise only for a given time period; default is for the whole account.
Dates are in yyyy-mm-dd format, e.g., 2005-07-15.
Return 0 if the balance is greater than the account's limit; otherwise exit with status 1. If there is an error, return 111 (temporary error) or 127 (permanent).
Usage: pracc-credit account < voucher-file
Add credits to the given account by reading a voucher file from stdin, checking its validity, appending a credit record to account, marking the voucher as used, and appending a record to the common log file.
Usage: pracc-purge [options] account date
Purge old records from the given account without changing its balance or limit. A record is old if it is older than date, which must be specified in yyyy-mm-dd format, e.g., 2005-07-15.
It might be useful to keep old records of some types:
Add -l to keep old limit records.
Add -r to keep old reset records.
Add -n to keep old note records.
The purge process works by scanning through the pracc file for account, skipping old records and copying non-old records to a temporary file PRACCDIR/account.purge. After skipping the last old record and before copying the first non-old record to the temporary file, a copy of the most recent limit record and a reset record with the current balance is written to the temporary file. This way, the account's balance and limit remain the same as they were in the original file. When done copying, the temporary file is moved over the original pracc file, which completes the purge process.
Add -D to only create the temporary file but not move it over the original pracc file. This is mainly useful for testing. Note that pracc-purge fails if the temporary file already exists, so remember to delete it yourself.
Note that comment lines do not have a timestamp. For purging, they inherit the timestamp of the most recent line before with a valid timestamp. Initial comment lines are never purged.
Lines longer than MAXLINE (see pracc.h) are
truncated to that length.
Syntactically incorrect lines are silently removed.
This tool does not produce any output to stdout. Error messages go to stderr.
Usage: pracc-check [account]
Check the installation of the pracc system and report any problems found to standard output. What constitutes a correct installation depends on the pracc.h header file and is defined below.
If an optional account is specified, then this account file is checked for syntactical correctness and any errors found are reported to standard output.
| Type | Mode | Owner | Group | Resource | Notes |
|---|---|---|---|---|---|
| d | 2770 | PRACCOWNER | PRACCGROUP | PRACCDIR/ | required |
| r | 660 | PRACCOWNER | PRACCGROUP | PRACCDIR/PRACCDEFLT | required |
| r | 660 | PRACCOWNER | PRACCGROUP | PRACCDIR/account | optional |
| r | 660 | PRACCOWNER | PRACCGROUP | PRACCLOG | required |
| d | any | any | any | PRACCBIN/ | optional |
| r | 755 | any | any | PRACCBIN/tool | optional |
| r | 2755 | PRACCOWNER | PRACCGROUP | PRACCBIN/pracc-credit | optional |
| d | 755 | any | any | PRACCDOC/ | required |
| d | any | any | any | PRACCWEBUI | required |
Usage: pracc-log [options] [account]
Print entries from the common log file to standard output. If account is specified, print only entries pertinent to that account. Use options to restrict output to a certain range of dates. Malformed log lines are silently skipped.
Dates are in yyyy-mm-dd format, e.g., 2005-07-15.
Usage: pracc-pclog [options] [printer]
Read the pc.log file and write statistics per printer to standard output. If no printer argument is specified, look at all printers that have entries in pc.log.
Dates are in yyyy-mm-dd format, e.g., 2005-07-15.
Usage: pracc-scan [options] [file]
Scan a print job file for its page count and information like duplex printing, paper size, etc. Known job formats are: PJL, PCL5, PCLXL (aka PCL6), and PostScript. If file is not specified, read from standard input.
This is a wrapper around joblex, a "lexer" for print jobs, originally written in about 2007 and since extended to support PCL XL. Presently, it produces one line to standard output with this format (# stands for a number):
# pages=# sheets=# copies=# duplex=# color=# struct=foo
Example:
5 pages=5 sheets=3 copies=1 duplex=1 color=-1 struct=UJ6UJU
Joblex believes that this job prints 1 copy of a duplex job, resulting in 5 printed pages on 3 sheets of paper; joblex has no idea if this is a color or monochrome job (color=-1). The print job consists of a UEL (U), some PJL (J), PCL XL (6), followed by UEL @PJL UEL (UJU).
The first number is always the same as pages and for compatibility with cupspracc (which reads the first number of the first line of a job scanner's output).
Presently, color=1 represents @PJL PLANESINUSE = 3 (color) and color=0 represents @PJL SET PLANESINUSE = 1 (monochrome). It seems that many black-and-white jobs have @PJL SET PLANESINUSE = 3.
There is a common log file, where account modifications are recorded. By default, the log file is /var/print/pracc.log, but this can be changed at compile-time. Here is what the tools log: