lpadmin(1M)
NAME
lpadmin - configure the LP print service
SYNOPSIS
lpadmin -p printer options
lpadmin -x dest
lpadmin -d [dest]
lpadmin -n [ppdfilename]
lpadmin -S print-wheel -A alert-type [-W minutes] [-
Q requests]
lpadmin -M -f form-name [ -a [ -o filebreak] [-t tray-
number]]
DESCRIPTION
lpadmin configures the LP print service by defining printers
and devices. It is used to add and change printers, to
remove printers from service, to set or change the system
default destination, to define alerts for printer faults,
and to mount print wheels.
OPTIONS
Adding or Changing a Printer
The first form of the lpadmin command (lpadmin -p printer
options) configures a new printer or changes the configura-
tion of an existing printer. It also starts the print
scheduler.
When creating a new printer, one of three options (-v, -U,
or -s) must be supplied. In addition, only one of the fol-
lowing may be supplied: -e, -i, or -m; if none of these
three options is supplied, the model standard is used. 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, dash (-) and
underscore (_). If -s is specified, the following options
are invalid: -A, -e, -F, -h, -i, -l, -M, -m, -o, -U, -v, and
-W.
The following printer options may appear in any order.
-A alert-type [-W minutes]
The -A option is used to define an alert that
informs the administrator when a printer fault is
detected, and periodically thereafter, until the
printer fault is cleared by the administrator.
The alert-types are:
mail Send the alert message using mail (see mail(1))
to the administrator.
write Write the message to the terminal on which the
administrator is logged in. If the administrator
is logged in on several terminals, one is chosen
arbitrarily.
quiet Do not send messages for the current condition.
An administrator can use this option to tem-
porarily stop receiving further messages about a
known problem. Once the fault has been cleared
and printing resumes, messages will again be sent
when another fault occurs with the printer.
showfault
Attempt to execute a fault handler on each system
that has a print job in the queue. The fault
handler is /etc/lp/alerts/printer. It is invoked
with three parameters: printer_name, date,
file_name. The file_name is the name of a file
containing the fault message.
none Do not send messages; any existing alert defini-
tion for the printer will be removed. No alert
will be sent when the printer faults until a dif-
ferent alert-type (except quiet) is used.
shell-command
Run the shell-command each time the alert needs
to be sent. The shell command should expect the
message in standard input. If there are blank
spaces embedded in the command, enclose the com-
mand in quotes. Notice that the mail and write
values for this option are equivalent to the
values mail user-name and write user-name respec-
tively, where user-name is the current name for
the administrator. This will be the login name of
the person submitting this command unless he or
she has used the su command to change to another
user ID. If the su command has been used to
change the user ID, then the user-name for the
new ID is used.
list Display the type of the alert for the printer
fault. No change is made to the alert.
The message sent appears as follows:
The printer printer has stopped printing for the reason given below.
Fix the problem and bring the printer back on line.
Printing has stopped, but will be restarted in a few minutes;
issue an enable commant if you want to restart sooner.
Unless someone issues the change request:
lp -i request-id -P ...
to change the page list to print, the current request will
be reprinted from the beginning. The reason(s) it stopped
(multiple reasons indicate reprinted attempts):reason
The LP print service can detect printer faults only through
an adequate fast filter and only when the standard interface
program or a suitable customized interface program is used.
Furthermore, the level of recovery after a fault depends on
the capabilities of the filter.
If the printer is all, the alerting defined in this command
applies to all existing printers.
If the -W option is not used to arrange fault alerting
for printer, the default procedure is to mail one mes-
sage to the administrator of printer per fault. This
is equivalent to specifying -W once or -W 0. If
minutes is a number greater than zero, an alert will be
sent at intervals specified by minutes.
-c class
Insert printer into the specified class. class will be
created if it does not already exist.
-D comment
Save this comment for display whenever a user asks for
a full description of printer (see lpstat(1)). The LP
print service does not interpret this comment.
-e printer
Copy the interface program of an existing printer to
be the interface program for printer. (Options -i and
-m may not be specified with this option.)
-f allow:form-list
-f deny:form-list
Allow or deny the forms in form-list to be printed on
printer. By default no forms are allowed on a new
printer.
For each printer, the LP print service keeps two lists
of forms: an ``allow-list'' of forms that may be used
with the printer, and a ``deny-list'' of forms that
may not be used with the printer. With the -f allow
option, the forms listed are added to the allow-list
and removed from the deny-list. With the -f deny
option, the forms listed are added to the deny-list
and removed from the allow-list.
If the allow-list is not empty, only the forms in the
list may be used on the printer, regardless of the
contents of the deny-list. If the allow-list is empty,
but the deny-list is not, the forms in the deny-list
may not be used with the printer. All forms can be
excluded from a printer by specifying -f deny:all. All
forms can be used on a printer (provided the printer
can handle all the characteristics of each form) by
specifying -f allow:all.
The LP print service uses this information as a set of
guidelines for determining where a form can be
mounted. Administrators, however, are not restricted
from mounting a form on any printer. If mounting a
form on a particular printer is in disagreement with
the information in the allow-list or deny-list, the
administrator is warned but the mount is accepted.
Nonetheless, if a user attempts to issue a print or
change request for a form and printer combination that
is in disagreement with the information, the request
is accepted only if the form is currently mounted on
the printer. If the form is later unmounted before
the request can print, the request is canceled and the
user is notified by mail.
If the administrator tries to specify a form as
acceptable for use on a printer that doesn't have the
capabilities needed by the form, the command is
rejected.
Notice the other use of -f, with the -M option, below.
The -T option must be invoked first with lpadmin to
identify the printer type before the -f option can be
used.
-F fault-recovery
This option specifies the recovery to be used for any
print request that is stopped because of a printer
fault, according to the value of fault-recovery:
continue
Continue printing on the top of the page where
printing stopped. This requires a filter to wait
for the fault to clear before automatically con-
tinuing.
beginning
Start printing the request again from the begin-
ning.
wait Disable printing on printer and wait for the
administrator or a user to enable printing
again.
During the wait, the administrator or the user
who submitted the stopped print request can
issue a change request that specifies where
printing should resume. (See the -i option of
the lp command.) 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 is printed from
the beginning.
-h Indicate that the device associated with the printer
is hardwired. If neither of the mutually exclusive
options, -h and -l, is specified, -h is assumed.
-i interface
Establish a new interface program for printer. inter-
face is the pathname of the new program. (The -e and
-m options may not be specified with this option.)
-I content-type-list
Allow printer to handle print requests with the con-
tent types listed in a content-type-list. If the list
includes names of more than one type, the names must
be separated by commas or blank spaces. (If they are
separated by blank spaces, the entire list must be
enclosed in double quotes.)
The type simple is recognized as the default content
type for files in the UNIX system. A simple type of
file is a data stream containing only printable ASCII
characters and the following control characters:
Control Char Octal Value Meaning
BACKSPACE 10 Move back one char, except
at beginning of line
TAB 11 Move to next tab stop
LINEFEED 12 Move to beginning of
(newline) next line
FORMFEED 14 Move to beginning of
next page
RETURN 15 Move to beginning of
current line
To prevent the print service from considering simple a
valid type for the printer, specify either an explicit
value (such as the printer type) in the content-type-
list, or an empty list. If you do want simple included
along with other types, you must include simple in the
content-type-list.
In addition to content types defined by the print
administrator, the type PostScript is recognized and
supported by the Solaris print subsystem. This
includes filters to support PostScript as the printer
content type.
The type any is recognized as a special content type
for files. When declared as the input type for a
printer, it signals the print sub-system not to do any
filtering on the file before sending it to the
printer.
Except for simple and any, each content-type name is
freely determined by the administrator. If the
printer type is specified by the -T option, then the
printer type is implicitly considered to be also a
valid content type.
-l Indicate that the device associated with printer is a
login terminal. The LP scheduler (lpsched) disables
all login terminals automatically each time it is
started. (The -h option may not be specified with this
option.)
-m model
Select model interface program, provided with the LP
print service, for the printer. (Options -e and -i may
not be specified with this option.)
-M -f form-name [-a [-o filebreak]] [-t tray-number]]
Mount the form form-name on printer. Print requests
that need the pre-printed form form-name will be
printed on printer. If more than one printer has the
form mounted and the user has specified any (with the
-d option of the lp command) as the printer destina-
tion, then the print request will be printed on the
one printer that also 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, by checking the capabilities
in the terminfo database for the type of printer. 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 print wheel as
mandatory, but the print wheel mounted on the printer
is different, the administrator is also warned but the
mount is accepted.
If the -a option is given, an alignment pattern is
printed, preceded by the same initialization of the
physical printer that precedes a normal print request,
with one exception: no banner page is printed. Print-
ing is assumed to start at the top of the first page
of the form. After the pattern is printed, the
administrator can adjust the mounted form in the
printer and press return for another alignment pattern
(no initialization this time), and can continue print-
ing as many alignment patterns as desired. The
administrator can quit the printing of alignment pat-
terns by typing q.
If the -o filebreak option is given, a formfeed is
inserted between each copy of the alignment pattern.
By default, the alignment pattern is assumed to
correctly fill a form, so no formfeed is added.
If the -t tray-number option is specified, printer
tray tray-number will used.
A form is ``unmounted'' either by mounting a new form
in its place or by using the -f none option. By
default, a new printer has no form mounted.
Notice the other use of -f without the -M option
above.
-M -S print-wheel
Mount the print-wheel on printer. Print requests that
need the print-wheel will be printed on printer. If
more than one printer has print-wheel mounted and the
user has specified any (with the -d option of the lp
command) as the printer destination, then the print
request will be printed on the one printer that also
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. If the printer does not take print wheels,
the command is rejected.
A print wheel is ``unmounted'' either by mounting a
new print wheel in its place or by using the option -S
none. By default, a new printer has no print wheel
mounted.
Notice the other uses of the -S option without the -M
option described below.
-n ppdfilename
Specify a PPD file for creating and modifying printer
queues. ppdfilename is the full path and file name to
the PPD file.
-o option
The -o option defines default printer configuration
values given to an interface program. The default may
be explicitly overwritten for individual requests by
the user (see lp(1)), or taken from a preprinted form
description (see lpforms(1M) and lp(1)).
There are several options which are pre-defined by the
system. In addition, any number of key-value pairs may
be defined. Each of the predefined and undefined
options are described.
The Predefined Options
The following options are predefined: adjusting
printer capabilities, adjusting printer port charac-
teristics, configuring network printers, and control-
ling the use of banner.
Adjusting Printer Capabilities
length=scaled-decimal-number
width=scaled-decimal-number
cpi=scaled-decimal-number
lpi=scaled-decimal-number
The term scaled-decimal-number refers to a non-
negative number used to indicate a unit of size. The
type of unit is shown by a ``trailing'' letter
attached to the number. Three types of scaled-
decimal-numbers can be used with the LP print service:
numbers that show sizes in centimeters (marked with a
trailing c); numbers that show sizes in inches (marked
with a trailing i); and numbers that show sizes in
units appropriate to use (without a trailing letter),
that is, lines, characters, lines per inch, or
characters per inch.
The option values must agree with the capabilities of
the type of physical printer, as defined in the ter-
minfo database for the printer type. If they do not,
the command is rejected.
The defaults are defined in the terminfo entry for the
specified printer type. The defaults may be reset by:
lpadmin -p printername -o length=
lpadmin -p printername -o width=
lpadmin -p printername -o cpi=
lpadmin -p printername -o lpi=
Adjusting Printer Port Characteristics
stty="'stty-option-list'"
The stty-option-list is not checked for allowed
values, but is passed directly to the stty program by
the standard interface program. Any error messages
produced by stty when a request is processed (by the
standard interface program) are mailed to the user
submitting the request.
The default for stty is:
stty="'9600 cs8 -cstopb -parenb ixon
-ixany opost -olcuc onlcr
-ocrnl -onocr
-onlret -ofill nl0 cr0 tab0 bs0 vt0 ff0'"
The default may be reset by:
lpadmin -p printername -o stty=
Configuring Network Printers
dest=string protocol=string bsdctrl=string \
timeout=non-negative-integer-seconds
These four options are provided to support network
printing. Each option is passed directly to the inter-
face program; any checking for allowed values is done
there.
The value of dest is the name of the destination for
the network printer; the semantics for value dest are
dependent on the printer and the configuration. There
is no default.
The value of option protocol sets the over-the-wire
protocol to the printer. The default for option proto-
col is bsd. The value of option bsdctrl sets the print
order of control and data files (BSD protocol only);
the default for this option is control file first. The
value of option timeout sets the seed value for back-
off time when the printer is busy. The default value
for the timeout option is 10 seconds. The defaults may
be reset by:
lpadmin -p printername -o protocol=
lpadmin -p printername -o bsdctrl=
lpadmin -p printername -o timeout=
Controlling the Use of the Banner Page
Use the following commands to control the use of the
banner page:
lpadmin -p printer -o nobanner
lpadmin -p printer -o banner
lpadmin -p printer -o banner=always
lpadmin -p printer -o banner=never
lpadmin -p printer -o banner=optional
The first and fifth commands (-o nobanner and -o
banner=optional) are equivalent. The default is to
print the banner page, unless a user specifies -o
nobanner on an lp command line.
The second and third commands (-o banner and -o
banner=always) are equivalent. Both cause a banner
page to be printed always, even if a user specifies lp
-o nobanner. The root user can override this command.
The fourth command (-o banner=never) causes a banner
page never to be printed, even if a user specifies lp
-o banner. The root user can override this command.
Undefined Options
key=value
Each key=value is passed directly to the interface
program. Any checking for allowed values is done in
the interface program.
Any default values for a given key=value option are
defined in the interface program. If a default is pro-
vided, it may be reset by typing the key without any
value:
lpadmin -p printername -o key=
-P paper-name
Specify a paper type list that the printer supports.
-r class
Remove printer from the specified class. If printer is
the last member of class, then class will be removed.
-S list
Allow either the print wheels or aliases for character
sets named in list to be used on the printer.
If the printer is a type that takes print wheels, then
list is a comma or space separated list of print wheel
names. (Enclose the list with quotes if it contains
blank spaces.) These will be the only print wheels
considered mountable on the printer. (You can always
force a different print wheel to be mounted.) Until
the option is used to specify a list, no print wheels
will be considered mountable on the printer, and print
requests that ask for a particular print wheel with
this printer will be rejected.
If the printer is a type that has selectable character
sets, then list is a comma or blank separated list of
character set name ``mappings'' or aliases. (Enclose
the list with quotes if it contains blank spaces.)
Each ``mapping'' is of the form known-name=alias The
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 entry csnm. See
terminfo(4). 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. If list is the word none,
any existing print wheel lists or character set
aliases will be removed.
Notice the other uses of the -S with the -M option
described above.
The -T option must be invoked first with lpadmin to
identify the printer type before the -S option can be
used.
-s system-name[!printer-name]
Make a remote printer (one that must be accessed
through another system) accessible to users on your
system. system-name is the name of the remote system
on which the remote printer is located it. printer-
name is the name used on the remote system for that
printer. For example, if you want to access printer1
on system1 and you want it called printer2 on your
system:
-p printer2 -s system1!printer1
-T printer-type-list
Identify the printer as being of one or more printer-
types. Each printer-type is used to extract data from
the terminfo database; this information is used to
initialize the printer before printing each user's
request. Some filters may also use a printer-type to
convert content for the printer. If this option is not
used, the default printer-type will be unknown; no
information will be extracted from terminfo so each
user request will be printed without first initializ-
ing the printer. Also, this option must be used if the
following are to work: -o cpi, -o lpi, -o width, and
-o length options of the lpadmin and lp commands, and
the -S and -f options of the lpadmin command.
If the printer-type-list contains more than one type,
then the content-type-list of the -I option must
either be specified as simple, as empty (-I ""), or
not specified at all.
-t number-of-trays
Specify the number of trays when creating the printer.
-u allow:login-ID-list
-u deny:login-ID-list
Allow or deny the users in login-ID-list access to the
printer. By default all users are allowed on a new
printer. The login-ID-list argument may include any or
all of the following constructs:
login-ID
a user on any system
system-name!login-ID
a user on system system-name
system-name!all
all users on system system-name
all!login-ID
a user on all systems
all all users on all systems
For each printer, the LP print service keeps two lists of
users: an ``allow-list'' of people allowed to use the
printer, and a ``deny-list'' of people denied access to the
printer. With the -u allow option, the users listed are
added to the allow-list and removed from the deny-list. With
the -u deny option, the users listed are added to the deny-
list and removed from the allow-list.
If the allow-list is not empty, only the users in the list
may use the printer, regardless of the contents of the
deny-list. If the allow-list is empty, but the deny-list is
not, the users in the deny-list may not use the printer. All
users can be denied access to the printer by specifying -u
deny:all. All users may use the printer by specifying -u
allow:all.
-U dial-info
The -U option allows your print service to access a
remote printer. (It does not enable your print service
to access a remote printer service.) Specifically, -U
assigns the ``dialing'' information dial-info to the
printer. dial-info is used with the dial routine to
call the printer. Any network connection supported by
the Basic Networking Utilities will work. dial-info
can be either a phone number for a modem connection,
or a system name for other kinds of connections. Or,
if -U direct is given, no dialing will take place,
because the name direct is reserved for a printer that
is directly connected. If a system name is given, it
is used to search for connection details from the file
/etc/uucp/Systems or related files. The Basic Network-
ing Utilities are required to support this option. By
default, -U direct is assumed.
-v device
Associate a device with printer. device is the path
name of a file that is writable by lp. Notice that the
same device can be associated with more than one
printer.
Removing a Printer Destination
The -x dest option removes the destination dest (a printer
or a class), from the LP print service. If dest is a printer
and is the only member of a class, then the class will be
deleted, too. If dest is all, all printers and classes are
removed. If there are no remaining local printers and the
scheduler is still running, the scheduler is shut down.
No other options are allowed with -x.
Setting/Changing the System Default Destination
The -d [dest] option makes dest (an existing printer or
class) the new system default destination. If dest is not
supplied, then there is no system default destination. No
other options are allowed with -d.
Setting an Alert for a Print Wheel
-S print-wheel -A alert-type [-W minutes] [-Q requests]
The -S print-wheel option is used with the -A alert-
type option to define an alert to mount the print
wheel when there are jobs queued for it. If this com-
mand is not used to arrange alerting for a print
wheel, no alert will be sent for the print wheel.
Notice the other use of -A, with the -p option, above.
The alert-types are:
mail Send the alert message using the mail command to
the administrator.
write Write the message, using the write command, to
the terminal on which the administrator is
logged in. If the administrator is logged in on
several terminals, one is arbitrarily chosen.
quiet Do not send messages for the current condition.
An administrator can use this option to tem-
porarily stop receiving further messages about a
known problem. Once the print-wheel has been
mounted and subsequently unmounted, messages
will again be sent when the number of print
requests reaches the threshold specified by the
-Q option.
none Do not send messages until the -A option is
given again with a different alert-type (other
than quiet).
shell-command
Run the shell-command each time the alert needs
to be sent. The shell command should expect the
message in standard input. If there are blanks
embedded in the command, enclose the command in
quotes. Notice that the mail and write values
for this option are equivalent to the values
mail user-name and write user-name respectively,
where user-name is the current name for the
administrator. This will be the login name of
the person submitting this command unless he or
she has used the su command to change to another
user ID. If the su command has been used to
change the user ID, then the user-name for the
new ID is used.
list Display the type of the alert for the print
wheel on standard output. No change is made to
the alert.
The message sent appears as follows:
The print wheel print-wheel needs to be mounted
on the printer(s):
printer(integer1requests) integer2 print requests
await this print wheel.
The printers listed are those that the administrator had
earlier specified were candidates for this print wheel. The
number integer1 listed next to each printer is the number of
requests eligible for the printer. The number integer2
shown after the printer list 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 com-
mand applies to all print wheels already defined to have an
alert.
If the -W option is not given, the default procedure is that
only one message will be sent per need to mount the print
wheel. Not specifying the -W option is equivalent to speci-
fying -W once or -W 0. If minutes is a number greater than
zero, an alert will be sent at intervals specified by
minutes.
If the -Q option is also given, the alert will be sent
when a certain number (specified by the argument
requests) of print requests that need the print wheel
are waiting. If the -Q option is not given, or
requests is 1 or any (which are both the default), a
message is sent as soon as anyone submits a print
request for the print wheel when it is not mounted.
EXAMPLES
In the following examples, prtr can be any name up to 14
characters and can be the same name as the ping(1M) name.
Example 1: Configuring an HP Postscript Printer with a Jet
Direct Network Interface
The following example configures an HP postscript printer
with a jet direct network interface:
example# lpadmin -p prtr -v /dev/null -m netstandard \
-o dest=ping_name_of_prtr:9100 -o protocol=tcp -T PS -I postscript
example# enable prtr
example# accept prtr
Example 2: Configuring a Standard Postscript Network Printer
The following example configures a standard postscript net-
work printer:
example# lpadmin -p prtr -v /dev/null -m netstandard \
-o dest=ping_name_of_prtr -T PS -I postscript
example# enable prtr
example# accept prtr
EXIT STATUS
The following exit values are returned:
0 Successful completion.
non-zero
An error occurred.
FILES
/var/spool/lp/*
/etc/lp
/etc/lp/alerts/printer
fault handler for lpadmin.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWpcu |
|_____________________________|_____________________________|
SEE ALSO
enable(1), lp(1), lpstat(1), mail(1), stty(1), accept(1M),
lpforms(1M), lpsched(1M), lpsystem(1M), ping(1M),
dial(3NSL), terminfo(4), attributes(5)
System Administration Guide: Basic Administration
Man(1) output converted with
man2html