lpadmin(ADM)

lpadmin -- configure the print service

Syntax

/usr/lib/lpadmin -p printer options

/usr/lib/lpadmin -x destination

/usr/lib/lpadmin -d [ destination ]

/usr/lib/lpadmin -S print_wheel -A alert_type [ -W n1 ] [ -Q n2 ]

Description

lpadmin configures the LP print service; it adds, changes and removes printers from the service, sets or changes the system default destination, and defines alerts for print wheels.

Adding or changing a printer

The first form of the lpadmin command (lpadmin -p printer options) configures a new printer or changes the configuration of an existing printer. The following options may appear in any order:

-A alert_type [ -W n ]

Sends the alert alert_type to the administrator when a printer fault is first detected and periodically thereafter until the printer fault is cleared by the administrator.

Possible alert_types are:

mail: Mails the alert message (using mail(C)) to the administrator who issued this command.
write: Writes the message to the administrator's terminal. If the administrator is logged in on several terminals, one is chosen arbitrarily.
quiet: Disables messages for the current alert condition. Once the fault has been cleared and printing resumes, messages will be re-enabled.
none: Sends no messages until an alert_type other than quiet is set; any existing alert definition is removed.
cmd: Runs the shell command cmd each time the alert needs to be sent. cmd should expect the message as standard input. Enclose the command in quotes if it contains whitespace. By default, the commands mail and write(C) send their output to the current user ID of the administrator who issued this command.
list: Display the alert type on the standard output. No change is made to the alert.

The following are possible alert messages:

The printer name has stopped printing for the reason given below. reason . . . Fix the problem and bring the printer back on line.

Printing has stopped but will be restarted in a few minutes; issue an enable command if you want to restart sooner.

Unless someone issues a change request lp -i request-id -P ... to change the page-list to print, the current request will be repeated from the beginning.

The print service can detect printer faults only through an adequate fast filter (see lpfilter(ADM)), and only when the standard interface program or a suitable customized interface program is used. The level of recovery after a fault depends on the capabilities of the filter.

If printer is set to all, the alerting defined is applied to all existing printers.

-W n specifies that n messages are to be sent per fault. If -W is not given or n is zero, only one message is sent per fault by default.

If fault alerting is not specified, the default behavior is to mail one message per fault to the printer administrator.

-b number

Specify the number of banner pages to be printed for each print request on a specified printer. If number is 0, no banner pages are printed.

If -o nobanner is specified as well, a user can opt to print either number or no banner pages.

If the number of banner pages is not specified using -b, the printer interface programs (supplied with the system) use the value of BANNERS defined in the file /etc/default/lpd instead.

-c class

Inserts printer into the specified class. class will be created if it does not already exist.

-D comment

Saves comment for display whenever a user asks for a full description of printer (see lpstat(C)). The print service does not interpret this comment.

-e prt

Copies the interface program of an existing printer (prt) to be the new interface program for printer.

-f allow:forms
-f deny:forms: Allows (-f allow) or denies (-f deny) the printing of the listed forms on printer.

: -f deny:any excludes all forms from a printer.
: -f allow:any allows all forms to be used on a printer, assuming that the printer can handle all the characteristics of the forms.

Administrators can overrule these settings and mount a form on any printer.

A user's print or change request which disagrees with these settings is accepted only if the form is currently mounted on the printer. If the form is unmounted before the request can print, the request is canceled, and the user is notified by mail unless the file /etc/default/lpd contains CANCEL_MAIL=NO.

lpadmin will reject a form being named for use on a printer that is not capable of printing it.

-F fault_recovery

Restores the print service after a printer fault according to the value of fault_recovery:

continue: Continues printing on the top of the page where printing stopped. The default filter used by the print service cannot do this. It requires a specialized filter which can tell exactly where printing ceased (see lpfilter(ADM)). The filter then waits for the fault to clear before continuing automatically.
beginning: Starts printing the request again from the beginning.
wait: Disables printing on the printer and waits for the administrator or a user to enable printing again.
During the wait, the administrator or user who submitted the stopped print request can issue a change request that specifies where printing should resume. If no change request is made before printing is enabled, printing resumes at the top of the page where stopped if the filter allows; otherwise, the request prints from the beginning.

-h

Indicates that the device associated with printer is hardwired. This option is assumed when adding a new printer unless the -l option is supplied.

-i pathname

Establishes the full pathname of a new interface program for printer.

-I type ...

Defines printer as being able to handle print requests of the content types listed.

simple is the default content type for files. Such files must contain only printable ASCII characters and the following control characters:

Control character Octal value Meaning

backspace 010 move back to previous column, except at beginning of line

tab 011 move to next tab stop

linefeed (newline) 012 move to beginning of next line

form feed 014 move to beginning of next page

carriage return 015 move to beginning of current line

Control character	Octal value	Meaning
backspace	010	move back to previous column, except at beginning of line
tab	011	move to next tab stop
linefeed (newline)	012	move to beginning of next line
form feed	014	move to beginning of next page
carriage return	015	move to beginning of current line

Content types may be freely defined by the administrator, except for the reserved type simple. By default, every printer includes its printer type in the list of content types it will accept.

To force the print service to exclude simple as a valid type for the printer, specify an arbitrary type (for example, the printer type) in the list of content types. simple must be included in a list if it is to be one of the possible types.

-l

Flags the device associated with printer as a login terminal. The scheduler, lpsched(ADM), disables terminals flagged as such when it is started. Before re-enabling printer, its current device should be established using lpadmin.

-M -f form [ -a [ -o filebreak ]]

Mounts the named form on printer in place of any existing form. Print requests to be printed with the pre-printed form will be printed on printer.

-f none specifies no form. By default, a new printer has no form mounted.

If more than one printer has the form mounted and the printer destination is any, (specified using lp -d any), then each print request is printed on the printer that meets the other needs of the request.

The page length and width and character and line pitches needed by the form are compared with those allowed for the printer in the terminfo(F) database. If the form requires attributes that are not available with the printer, the administrator is warned, but the mount is accepted. If the form lists a particular print wheel as mandatory but the print wheel mounted on the printer is different, the administrator is also warned but the mount is accepted.

-a prints an alignment pattern. The printer is initialized but no banner page is printed. Printing starts at the top of the first page of the form. Adjust the form after printing the pattern. Press <Return> to print another alignment pattern (the printer is not initialized this time), or ``q'' to quit.

-o filebreak inserts a formfeed between each copy of the alignment pattern. By default, no formfeed is added since the alignment pattern is assumed to completely fill a form.

-M -S print_wheel

Mounts the print wheel print_wheel on printer. Print requests to be printed with print_wheel will be printed on that printer. If more than one printer has the print_wheel mounted and the printer destination is any, (specified using lp -d any), then each print request is printed on the printer that meets the other needs of the request.

If the print_wheel is not listed as acceptable for the printer, the administrator is warned, but the mount is accepted. The command is rejected if the printer does not take print wheels.

Unmount a print wheel by mounting a new print wheel in its place or by specifying -S none.

By default, a new printer has no special print wheel mounted; print requests needing a specific print wheel will not be printed on it.

-m model

Selects a model interface program provided with the print service for a given printer.

-o printing_option

Each -o option in the list below is the default given to an interface program if the option is not taken from a preprinted form description or is not explicitly given by the user submitting a request (see lp(C)). The only -o options that can have defaults defined are:

cpi=sdn
length=sdn
lpi=sdn
width=sdn
stty=settings

sdn is a scaled decimal number; a size given as non-negative number with units shown by an optional trailing letter. There are three types of unit:

centimeters indicated by ``c''
inches indicated by ``i''
default units are assumed when no letter is given (for example, number of lines or columns, characters per inch (cpi), or lines per inch (lpi))

Default values entered for cpi, length, lpi, and width should agree with the printer capabilities defined in terminfo. If they do not, the command is rejected.

If not specified using -o, the defaults for cpi, length, lpi, and width are read from the terminfo entry for the printer type.

When processing a request, the standard interface program does not check the settings for stty=; they are passed directly to the stty(C) command. Any error messages produced by stty are mailed to the user submitting the request.

The default stty settings are:

9600 cs8 -cstopb -parenb -paroff ixon -ixany opost -olcuc
-onlcr -ocrnl -onocr -onlret -ofill nl0 cr0 tab0 bs0 vt0 ff0

You can set any of the -o options to the default values (which vary for different types of printers) by not assigning them a value. For example:

length=

-o banner

Forces a banner page to be printed with every print request, even when a user asks for no banner page. This is the default; you must specify -o nobanner if you want to allow users to specify -o nobanner with the lp command.

-o nobanner

Allows users to submit a print request asking that no banner pages be printed.

-r class

Removes a given printer from the specified class. If the printer is the last member of the class, then the class will be removed.

-S list

Allows the aliases for character sets or print wheels named in list to be used with a given printer.

-S none removes all previous print wheel list or character set aliases.

If the printer takes print wheels, list consists of the names of mountable print wheels separated by commas or spaces. (You can always force a different print wheel to be mounted, however.)

No print wheels will be considered mountable until list is specified; print requests requiring a particular print wheel with this printer will be rejected.

If the printer is a type that has selectable character sets, then list consists of character set aliases, separated by commas or spaces.

Each alias has the form known_name=synonym.

known_name is a character set number preceded by ``cs'', such as ``cs3'' for character set three, or a character set name from the terminfo database ``csnm'' entry. If this option is not used to specify a list, only the names already known from the terminfo database or numbers with a prefix of ``cs'' will be acceptable for the printer.

-T type

Initializes printer using the information in terminfo(F) for the given printer type. Some filters may also use type to convert content for the printer. If this option is not used, the default type is unknown; each user request is printed without first initializing the printer.

This option must be used if the following are to work:

options cpi=, length=, lpi=, and width to lpadmin -o and lp -o
options -S and -f to lpadmin

-u allow:names
-u deny:names: Allows (-u allow) or denies (-u deny) access to printer to the users listed by names. -u deny:any denies access to all users except the print service administrator.

-u allow:any allows access to everyone.

-U dial_info

dial_info is one of:

direct for a directly connected printer (the default)
a phone number for a modem connection
a system name; connection details for this system are in the file /usr/lib/uucp/Systems or related files

If the printer is not directly connected, the dial(S) routine uses the dialing information to call the printer. Any network connection supported by the Basic Networking Utilities will work. (The Basic Networking Utilities are required to support this option.)

-v device

Associates a new device with printer. device is the pathname of a device special file writable by lp. Note that device can be associated with only one printer.

Removing a printer destination

The second form of the lpadmin command (lpadmin -xdestination) removes the destination from the print service. If destination is a printer and is the only member of a class, then the class will be deleted too. If destination is all, all printers and classes are removed. No other options are allowed with -x.

Changing the system default destination

The third form of the lpadmin command (lpadmin -d [ destination ]) defines an existing destination as the new system default destination. If destination is not supplied, then there is no system default destination. No other options are allowed with -d.

Setting an alert for a print wheel

The fourth form of the lpadmin command (lpadmin -S print_wheel -A alert_type [ -W n1 ] [ -Q n2 ]) sends the alert alert_type to the administrator as soon as the print_wheel needs to be mounted and periodically thereafter.

The possible alert_types are the same as when the -A option is used in combination with the -p option. See the description of the -A option under ``Adding or changing a printer.'' Note that the behavior of the alert_type quiet changes slightly; quiet disables messages until the print_wheel has been mounted and subsequently unmounted. Messages will be sent again when the number of print requests again exceeds the threshold n2 specified by the -Q option.

The message sent appears as follows:

   The print wheel print_wheel needs to be mounted
   on the printer(s):
   printer n
   .
   .
   .
   N print requests await this print_wheel.

This lists the printers previously specified as candidates for this print wheel. n is the number of requests eligible for each printer. N is the total number of requests awaiting the print wheel. It will be less than the sum of the other numbers if some requests can be handled by more than one printer.

If the print_wheel is all, the alerting defined in this command applies to all print wheels already defined to have an alert.

If this command is run by more than one administrator for the same print wheel, only the last administrator to run the command is alerted.

The following options are relevant here:

-W n1: Specifies the number n1 of messages to be sent per request to mount a print wheel. If the -W option is not given or n1 is 0 (interpreted as once; the default), only one message will be sent per request. If this command is not used to arrange alerting for a print wheel, no alerts will be sent for the print wheel.
-Q n2: Delays the alert message until n2 print requests that need the print wheel are queued. If the -Q option is not given, or n2 is 1 or the word any, a message is sent for the first request.

Limitations

When creating a new printer, either the -v or the -U option must be supplied.

The -e, -i, and -m options are mutually exclusive; the standard printer interface program is used if none of these options is specified.

The -h and -l options are mutually exclusive.

Printer and class names may be no longer than 14 characters and must consist entirely of the characters A-Z, a-z, 0-9 and ``_'' (underscore).

Authorization

Permission to use this utility requires the lp authorization in authorize(F).

Users with lp authorization may not use the -i option. Only root and lp may use this option.

Files

/usr/spool/lp/