ppad - PPR administrator's utility
ppad [--help] [--version] [-M] [-d debuglevel] [subcommand] [parameters ...]
Ppad is the utility used to manage PPR, that is, to create and delete printers and groups, to set their parameters, and to define known types of media.
The --version switch prints the PPR version number.
The --help switch prints abreviated instructions for use and direction for obtaining additional help.
The -d option can be used to turn on messages which describe what ppad is doing. The default level is 0. Using -d 1 will cause ppad to tell what printer and group configuration files it is examining and editing. Higher levels display more information. A level 2 and above ppad will display information about what it learns from PPD files and /usr/share/ppr/lib/mfmodes.conf. At level 3 and above it will display every mode line in mfmodes.conf and every line read from or written to the printer or group configuration file. Level 6 and above shows most of the lines in every PPD file that is read.
Most operations performed by this command require PPR administrator privileges. Only those operations which make no changes to the spooler configuration may be performed by non-privileged users. This command defines a privileged user as the user ``ppr'', a user with a UID of 0 (root), a user listed in the file ``/etc/ppr/acl/ppad.allow'', or (for compatibility with previous versions of PPR) a user who is a member of the group ``ppad''.
Ppad has a number of subcommands. Each subcommand has zero or more parameters. The subcommands are described below.
If the ppad command is invoked without sub-command arguments it will enter interactive mode. In interactive mode it reads commands from stdin and executes them.
If the -M switch is used, ppad will adopt a terser style of output, more suitable to parsing by other programs.
The interfaces supplied with the current distribution are simple, serial, parallel, dummy, atalk, tcpip, lpr, clispool, smb, gssimple, gsserial, gsparallel, gsatalk. gstcpip, gslpr, and gssmb.
These interfaces are described in the ppad-interfaces(8) manpage.
Here is a sample ``ppad options'' command. This one sets the options for a printer with a serial interface:
$ ppad options myprn 'speed=19200 bits=7 parity=even'
The available options depend on which interface was selected. See the appropriate section in the ppad-interfaces.8 manpage to learn what options are available for any given interface.
The options can be removed either by specifying an empty string or omitting the options string entirely.
The possible settings are as follows:
To return to the default job break method, set it to ``default''.
For any given printer interface program and PPD file there is a default setting for ppad codes. To revert to the default setting for the interface and PPD file, set use the command ppad codes printer default.
The ppad codes setting is new in PPR version 1.40. Setting it to UNKNOWN causes PPR to behave as it did in previous versions. If the setting is anything other than UNKNOWN then PPR will not attempt to print PostScript files which claim to require a more extensive byte value set. For example, if a printer's codes setting is Clean8Bit and the print job contains a DSC comment which says ``%%DocumentData: Binary'' then PPR will not attempt to print the job on that printer. Hopefully the job was submitted to a group and some other member will have a less restrictive codes setting.
Here are the possible settings:
The parameter rip indicates the Raster Image Processor to use. Normally you will want to use a value of ppr-gs. The ppr-gs RIP is a small wrapper program for Ghostscript.
The parameter output_language is the name of the printer language which the selected Ghostscript driver will produce output in. It is used as the parameter to the PJL @PJL ENTER LANGUAGE command. If you will not be using the pjl or signal/pjl jobbreak method, then the actual value doesn't matter, you can set it to ``x''.
The option options contains options for the RIP. When using the ppr-gs RIP these should include the Ghostscript option to select the proper output device driver.
Here is an example command which will choose ppr-gs as the RIP and select Ghostscript's driver for a HP DeskJet 500:
$ ppad rip myprn ppr-gs pcl -sDEVICE=djet500
You should include such other Ghostscript options as well help to configure Ghostscript for your particular printer. You should not include options such as -sOutputFile=, -q, or -dSAFER since these are supplied automatically by ppr-gs.
The RIP ppr-gs also supports CUPS drivers. Simply select the special CUPS PPD file. PPR understands the special lines in a CUPS PPD file that identify the CUPS driver program that converts the output of Ghostscript to the printer's language. CUPS drivers will not work unless their PPD files are selected using the ppad ppd command, so there generally isn't much need to using the ppad rip command with them as PPR reads the RIP information right out of the PPD file. Use ppad show to see what it comes up with. You will notice that CUPS drivers use an option called cups= which specifies the name of the CUPS driver program.
The RIP ppr-gs also supports IJS drivers. To select an IJS driver, use a command like this one:
$ ppad rip myprn ppr-gs escp ijs=ijsgimpprint,EPSON,escp2-c60
The ijs= option takes three arguments. They are IJS program name, printer make, and printer model. The set of allowable values for the last two depends on the IJS program. The example above is for an Epson C60 inkjet printer. Of course, additional options may be specified:
$ ppad rip myprn ppr-gs escp ijs=ijsgimpprint,EPSON,escp2-c60 \ -sIjsParams=ImageType=2,MediaType=Photo,Quality=720hq2
You will have to consult the documentation for the IJS driver to find out about available options.
If you are writing a PPD file and want to include default PPR RIP information, you should include a line like this one.
*pprRIP: ppr-gs pcl -sDEVICE=djet500
If you assign a PPD file with this line to a new printer but don't use the ppad rip command, it will behave as if you had entered a ppad rip command like this:
$ ppad rip myprn ppr-gs pcl -sDEVICE=djet500
Remember though that this is a default which the system administrator will be able to override using the ppad rip command. If he does override the default and later wants to revert to the default, he can use this command.
$ ppad rip myprn
Of course, if he were using a different PPD file, one with no RIP settings, then this command would disable the external RIP and the printer will be expected to handle PostScript itself. To see if an external RIP is being used, run ppad show and look for a line begining with ``RIP:''. If a default from the PPD file is being used, there will be a note that so indicates.
If you want make a RIP that you can use instead of ppr-gs, you should create a program and put it in /usr/lib/ppr/lib/. It should connect stdin, stdout, and stderr to the cooresponding file descriptors of the PostScript interpreter and should send the print date to file descriptor 3. See the PPR Hackers Guide for details.
Note that while this command currently allows you to specify the path to a copy of Ghostscript as the RIP name, you should not rely on this as it may be removed in a future version of PPR.
Using the ``ppad ppd'' command has the side effect of undoing any previous ``ppad ppdopts'' command. Therefor, you should run ``ppad ppdopts'' after using ``ppad ppd'' to set the PPD file.
Note that this command will likely fail if necessary interface options have not yet been set with the ppad options command. It is intended to help you select the best PPD file for a print queue that is already configured sufficiently correctly that documents can be printed (using the default PPD file).
If you wish to probe a printer without first creating a queue for it, you should use the ppad ppd query command.
If the alert frequency is negative, it has special meaning. The absolute value is used. When that many alerts have been posted, a message is despatched by the method described above. The posting of additional alerts do not result in more messages. When and if the printer successfully prints a job, a message is sent indicating that the error has cleared up.
A setting of ``never'' means to not print the flag page even if the user requests it. A setting of ``no'' means to not print the flag page unless the user specifically requests it. A setting of ``yes'' means to print the flag page unless the user specifically requests that be suppressed. A setting of ``always'' means to print the flag page even if the user tries to suppress it.
In general, a job which requires a specific type of medium will not be printed until that medium is mounted on one or more bins. (A medium is mounted using the ppop mount command.)
The first exception to this rule occurs when a printer has no bins in its bin list. In this case, it will print any job immediately without regard to the job's media requirments.
The second exception is the bin name ``AutoSelect'' which has a special status. Regardless of what medium is mounted on it, all jobs will be printed immediately even if the proper medium is not explicitly mounted. Pages which require a medium which is not among those explicitly mounted will be directed to the AutoSelect bin.
For example, if you keep duplicate print servers and have set up a printers on one of them, you can then copy the configuration file to the second server and run ppad touch to tell pprd about the new printer.
You can also use ppad touch to duplicate a queue. For example, if you have a printer called ``lab_1'', you might use these commands to create ``lab_2'':
$ cp /etc/ppr/printers/lab_1 /etc/ppr/printers/lab_2 $ ppad touch lab_2 $ ppad interface lab_2 tcpip lab_2.prn.myorg.org:9100
Of course, there really should be a command to do this, but there isn't.
If the switches are omited, then the switchset is deleted.
Switchsets can be used to set defaults for a printer which the user can generally override with contradictory options on the ppr command line. They are also handy when the user can't select the desired options directly, such as when the job is being submitted through Samba, lprsrv in the lprsrv.8 manpage, or lprsrv in the papsrv.8 manpage.
Notice that if the job is submitted to a group of which this printer is a member, the printer's switchset will not be used, rather, the switchset from the group (if there are any) will be used. Switchsets for groups are established with the ppad group switchset command.
Here are some examples. If we have a printer ``myprn'' and want to make duplex the default we can do this:
$ ppad switchset myprn -F '*Duplex DuplexNoTumble'
Now, if we use the command:
$ ppr -d myprn /etc/profile
the file will be printed in duplex mode. We will get the results we could get formerly by typing.
$ ppr -F '*Duplex DuplexNoTumble' -d myprn /etc/profile
But suppose we want to print in simplex mode? We can make a group that contains only ``myprn'' and give that group a different switchset:
$ ppad group add myprn_sim myprn $ ppad group switchset -F '*Duplex None"
Now, if we use the command:
$ ppr -d myprn_sim /etc/profile
then the switchset from the group ``myprn_sim'' will be used.
So you see, groups with one member can be used as printer aliases. A set of ppr options can then be assigned to each of these aliases.
(We should note that PPR version 1.40 introduced explicit support aliases. An alias could be used in the above example instead of a single member group. Switchsets for aliases are set with the ppad alias switchset command. However, while alias support in the PPR core is complete, ppr2samba and papsrv don't support them yet, so you should probably avoid them for now.)
It is possible to abuse the ppad switchset, ppad group switchset, and ppad alias switchset commands. In the most obvious case, one could include -d option (presumably in attempt to redirect the print jobs to a different queue). Fortunately, ppr will ignore it.
Another option one should not include in a switchset is -m (which sets the responder method). Why? Because the method by which PPR should send messages to the person who submitted the job depends very much on how the job arrived. For example, if the job was submitted by a Unix shell user on the server, then the write command can be used to send a message to his terminal. But if the user is Microsoft Windows user connecting through Samba, then the smbclient program should be used to send messages. For this reason, network servers such as Samba, lprsrv in the lprsrv.8 manpage, and papsrv.8/papsrv set the -m and -r options themselves thereby overriding any settings in the switchset.
If you want to disable responder messages, don't put -r none in the switchset. Instead put an appropriate --responder-options in the switchset. These option should work with whatever responder is selected.
$ ppad passthru adshp4m pcl hpgl2
will set the printer queue ``adshp4m'' so that it passes files in HP's PCL and HPGL2 printer languages directly through to the printer.
The file type names are the same as those one would use with the ppr -T switch. (Except MIME type names, even though the -T switch now supports some.)
There is no need to use the ppr -T switch in order for a passthru setting to be effective. If PPR's automatic file type detection is working with your files, then using the ppr -T switch is unnecessary and potentially confusing.
Some have tried to create a `transparent' print queue by setting a passthru list which contains some type, say ``pcl'', and then setting a -T option, say -T pcl in the switchset. They hope that through this queue they will be able to print files, of all the types which the printer can interpret, without PPR re-writing the files in any way. They are supprised when PostScript files sent through this queue are interpreted as though they were PCL. They have outsmarted themselves. It does not do to lyingly tell PPR that a file is PCL, because PPR will, if possible, pass this information on to the printer and the printer will believe. If one wants transparent mode, one should use the ppr -H transparent option.
Note that the passthru setting of a printer queue does not apply to jobs submitted to a group of which the printer is a member. In that case, the passthru setting for the group applies.
The ``DefFiltOpts:'' line contains a list of default options which will be passed to filters which are invoked to convert other file formats to PostScript. These default options are amoung the information displayed by the ``ppad show'' command.
If you wish to charge a different amount for a duplex sheet as opposed to a simplex sheet you may specify two amounts. The first is the amount to charge for each sheet printed on both sides, the second is the amount to charge for each sheet printed on one side. For instance, if you want to provide a small incentive to use duplex mode you can do this:
$ ppad charge myprn 0.07 0.05
On the other hand, if you want to charge per side you can do this:
$ ppad charge myprn 0.10 0.05
If a printer has a per-page charge, even if it is zero, it is considered a protected printer. If a printer is protected, then only users who appear in the PPR accounts database may print on it.
The per page charge may be removed from a printer by setting it to ``none''.
Either the upper or lower limit or both may be removed by setting it to zero.
In the current implementation, the number of PostScript page descriptions in the job is compared to the pages limits. Future implementations will likely take multiple copies and n-up into account.
Either the upper or lower limit or both may be removed by setting it to zero.
The purpose of this parameter is to keep grayscale jobs off of an expensive colour printer. If both a colour printer with ``grayok'' set to false and a grayscale printer are in the same group and jobs are submitted to the group, only the colour printer will be eligible for printing the jobs which declare themselves to be colour and only the grayscale printer will be eligible for printing those jobs which do not declare themselves to be colour.
Unfortunately, very few printer drivers label colour jobs as colour jobs, so the value of this feature is presently doubtful. On possible solution is to develop editps filters for each printer driver. These filters would have to detect the commands or procedure sets associated with colour printing and add a ``%%Requirements: color'' line to the job's header comments.
This limit will only be enforced if PPR can determine when the printer goes on-line or off-line and when it finishes each page. Currently this is only possible with printers which implement HP's PJL, including the status reporting features.
If the printer meets the above requirements, then PPR will run a ``stopwatch'' while it is printing a job. This stopwatch will be reset every time the printer reports that it has completed a page. The stopwatch will be stopped whenever the printer goes off-line and started again when the printer goes back on-line. If the stopwatch reaches the limit, then printing is aborted.
If your printer supports this ``stopwatch'' feature, then you will be able to see the stopwatch in the ppop status output.
To remove this limit, set it to 0.
PPR ACLs are stored in files in /etc/ppr/acl. To create a new ACL, say professors, create a file called /etc/ppr/acl/professors.allow and enter the usernames of the members, one per line.
This is a new feature, so the list of allowed options has not yet been established.
Addon parameters are used by programs which are not part of PPR's core services. For example, ppr2samba uses the parameter ``ppr2samba:'' to tell whether it should share a given queue with Samba. This command will set the parameter to exclude the printer ``privateprn'':
$ ppad addon privateprn ppr2samba 0
Next time ppr2samba is run, it will exclude this queue from the smb-include.conf file that it generates.
These subcommands are used to create, modify and destroy printer groups.
Even though all members may be deleted from a group, it will continue to exist and jobs may still be queued for it, they just won't print until it has some idle members again.
To remove a switchset, set it but ommit the switches.
Please see ppad switchset for an explaination of printer and group switchsets.
Notice that a printer might have a language such as PCL passed through to it when the job is submitted to one group of which it is a member but not when the job is submitted to another group of which it is also a member. In fact, groups with only one member may be used as printer aliases, aliases with different passthru rules.
See ppad acls for more information about ACLs.
See ppad addon for an explanation of this this command's purpose.
The ppad alias commands are used to create, edit, and delete aliases for queues.
For an explanation of the purposes of switchsets, see ppad switchset.
See ppad addon for an explanation of this this command's purpose.
The ppad media commands are used to manipulate the media database. The media database is a list of media types such as ``US letter size 20 lb. white paper''. Each of these types is assigned a name. These names are used as arguments to the ppop mount command and the ppr -D switch.
$ ppad ppd list laserwriter "Apple LaserWriter v23.0" "Apple LaserWriter II NT v47.0" "Apple LaserWriter Plus v38.0" "Apple LaserWriter Plus v42.2" "Apple Personal LaserWriter NTR v2010.129" "Apple LaserWriter Select 360 v2013.112" "Apple Personal LaserWriter 320 v2013.112"
$ ppad ppd list ""HP*4m*" "HP LaserJet 4M DSC" "HP LaserJet 4M Plus DSC" "HP LaserJet 4/4M PS 600 dpi" "HP LaserJet 4ML PostScript" "HP LaserJet 4P/4MP PS 600 dpi" "HP LaserJet 4V/4MV PostScript"
ppad ppd query jetdirect david-hp4.prn.notanorg.org
If the interface program's default options will not enable it to communicate with the printer, you should supply the necessary options as a quoted list. For example, if you have a serial printer connected to the first serial port of your Linux system, you could do this:
ppad ppd query serial /dev/ttyS0 "online=none"
The option ``online=none'' tells the serial interface program to ignore the fact that DSR and CTS seem indicate that the printer isn't ready.
This command is intended to enable you to determine the type of a printer without first creating a queue for it. If you have already created a queue, it will likely be easier to use the ppad ppdq command which reads the interface name and address from the print queue's configuration.
Exit codes for ppad are defined in the source code file include/util_exits.h.
the ppr.1 manpage, the ppop.1 manpage, the papsrv.8 manpage, the lprsrv.8 manpage, ``PPR, a PostScript Print Spooler'', ``Installing and Using PPR''.
PPR was written at Trinity College during 1993--2003. It was first released to the public on 26 April 1995.
David Chappell, Trinity College Computing Center, Hartford Connecticut.