path: root/usr/src/man/man1m/lpadmin.1m

'\" te
.\"  Copyright 1989 AT&T Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH LPADMIN 1M "June 20, 2021"
.SH NAME
lpadmin \- configure the LP print service
.SH SYNOPSIS
.nf
\fBlpadmin\fR \fB-p\fR \fIprinter\fR {\fIoptions\fR}
.fi

.LP
.nf
\fBlpadmin\fR \fB-x\fR \fIdest\fR
.fi

.LP
.nf
\fBlpadmin\fR \fB-d\fR [\fIdest\fR]
.fi

.LP
.nf
\fBlpadmin\fR \fB-S\fR \fIprint-wheel\fR \fB-T\fR [\fB-A\fR \fIalert-type\fR] [\fB-W\fR \fIminutes\fR]
     [\fB-Q\fR \fIrequests\fR]
.fi

.SH DESCRIPTION
\fBlpadmin\fR 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.
.SH OPTIONS
The \fBlpadmin\fR command has options for:
.RS +4
.TP
.ie t \(bu
.el o
Adding or changing a printer
.RE
.RS +4
.TP
.ie t \(bu
.el o
Removing a printer destination
.RE
.RS +4
.TP
.ie t \(bu
.el o
Setting or changing the system default destination
.RE
.RS +4
.TP
.ie t \(bu
.el o
Setting an alert for a print wheel
.RE
.sp
.LP
The options for each of the above categories are specified in the following
subsections.
.sp
.LP
Several options support the use of lists. A list might contain, for example,
user names, printers, printer forms, or content types. A list of multiple items
can have the form of either comma-separated names or have the entire list
enclosed by double quotes with a space between each name. For example, both
lists below are acceptable:
.sp
.in +2
.nf
one,two,three
"one two three"
.fi
.in -2

.SS "Adding or Changing a Printer"
The first form of the \fBlpadmin\fR command (\fBlpadmin\fR \fB-p\fR
\fIprinter\fR {\fIoptions\fR}) configures a new printer or changes the
configuration of an existing printer. It also starts the print scheduler.
.sp
.LP
When creating a new printer, one of three options (\fB-v\fR, \fB-U\fR, or
\fB-s\fR) must be supplied. In addition, only one of the following can be
supplied: \fB-e\fR, \fB-i\fR, or \fB-m\fR; if none of these three options is
supplied, the model standard is used. The \fB-h\fR and \fB-l\fR options are
mutually exclusive. Printer and class names must be no longer than 14
characters and must consist entirely of the characters \fBA\fR-\fBZ\fR,
\fBa\fR-\fBz\fR, \fB0\fR-\fB9\fR, dash (\fB-\fR) and underscore (\fB_\fR). If
\fB-s\fR is specified, the following options are invalid: \fB-A\fR, \fB-e\fR,
\fB-F\fR, \fB-h\fR, \fB-i\fR, \fB-l\fR, \fB-M\fR, \fB-m\fR, \fB-o\fR, \fB-U\fR,
\fB-v\fR, and \fB-W\fR.
.sp
.LP
The following options can appear in any order.
.sp
.ne 2
.na
\fB\fB-A\fR \fIalert-type\fR [\fB-W\fR \fIminutes\fR]\fR
.ad
.sp .6
.RS 4n
The \fB-A\fR 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 \fIalert-types\fR are:
.sp
.ne 2
.na
\fB\fBmail\fR\fR
.ad
.RS 17n
Send the alert message using mail (see \fBmail\fR(1)) to the administrator.
.RE

.sp
.ne 2
.na
\fB\fBwrite\fR\fR
.ad
.RS 17n
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.
.RE

.sp
.ne 2
.na
\fB\fBquiet\fR\fR
.ad
.RS 17n
Do not send messages for the current condition. An administrator can use this
option to temporarily stop receiving further messages about a known problem.
Once the fault has been cleared and printing resumes, messages are sent again
when another fault occurs with the printer.
.RE

.sp
.ne 2
.na
\fB\fBshowfault\fR\fR
.ad
.RS 17n
Attempt to execute a fault handler on each system that has a print job in the
queue. The fault handler is \fB/etc/lp/alerts/printer\fR. It is invoked with
three parameters: \fIprinter_name\fR, \fBdate\fR, \fIfile_name\fR. The
\fIfile_name\fR is the name of a file containing the fault message.
.RE

.sp
.ne 2
.na
\fB\fBnone\fR\fR
.ad
.RS 17n
Do not send messages; any existing alert definition for the printer is removed.
No alert is sent when the printer faults until a different alert-type (except
\fBquiet\fR) is used.
.RE

.sp
.ne 2
.na
\fB\fIshell-command\fR\fR
.ad
.RS 17n
Run the \fIshell-command\fR 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 command in quotes. Notice that the
\fBmail\fR and \fBwrite\fR values for this option are equivalent to the values
\fBmail\fR \fIuser-name\fR and \fBwrite\fR \fIuser-name\fR respectively, where
\fIuser-name\fR is the current name for the administrator. This is the login
name of the person submitting this command unless he or she has used the
\fBsu\fR command to change to another user ID. If the \fBsu\fR command has been
used to change the user ID, then the \fIuser-name\fR for the new ID is used.
.RE

.sp
.ne 2
.na
\fB\fBlist\fR\fR
.ad
.RS 17n
Display the type of the alert for the printer fault. No change is made to the
alert.
.RE

When a fault occurs, the printing subsystem displays a message indicating that
printing for a specified printer has stopped and the reason for the stoppage.
The message also indicates that printing will restart in a few minutes and that
you can enter an \fBenable\fR command if you want to restart sooner than that.
.sp
Following a fault that occurs in the middle of a print job, the job is
reprinted from the beginning. An exception to this occurs when you enter a
command, such as the one shown below, that changes the page list to be printed.
.sp
.in +2
.nf
% \fB\fR\fBlp\fR\fB \fR\fB-i\fR\fB \fIrequest-id\fR \fR\fB-P\fR\fB ...\fR
.fi
.in -2
.sp

For a given print request, the presence of multiple reasons for failure
indicate multiple attempts at printing.
.sp
The \fBLP\fR 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.
.sp
If, instead of a single printer, the keyword \fBall\fR is displayed in an
alert, the alert applies to all printers.
.sp
If the \fB-W\fR option is not used to arrange fault alerting for \fIprinter\fR,
the default procedure is to mail one message to the administrator of
\fIprinter\fR per fault. This is equivalent to specifying \fB-W\fR \fBonce\fR
or \fB-W\fR \fB0\fR. If \fIminutes\fR is a number greater than zero, an alert
is sent at intervals specified by \fIminutes\fR.
.RE

.sp
.ne 2
.na
\fB\fB-c\fR \fIclass\fR\fR
.ad
.sp .6
.RS 4n
Insert \fIprinter\fR into the specified \fIclass\fR. \fIclass\fR is created if
it does not already exist. This option requires the \fB-U\fR \fIdial-info\fR or
\fB-v\fR \fIdevice\fR options.
.RE

.sp
.ne 2
.na
\fB\fB-D\fR \fIcomment\fR\fR
.ad
.sp .6
.RS 4n
Save this \fIcomment\fR for display whenever a user asks for a full description
of \fIprinter\fR (see \fBlpstat\fR(1)). The LP print service does not interpret
this comment.
.RE

.sp
.ne 2
.na
\fB\fB-e\fR \fIprinter\fR\fR
.ad
.sp .6
.RS 4n
Copy the interface program of an existing \fIprinter\fR to be the interface
program for \fIprinter\fR. (Options \fB-i\fR and \fB-m\fR must not be specified
with this option.)
.RE

.sp
.ne 2
.na
\fB\fB-f\fR \fBallow\fR:\fIform-list\fR\fR
.ad
.br
.na
\fB\fB-f\fR \fBdeny\fR:\fIform-list\fR\fR
.ad
.sp .6
.RS 4n
Allow or deny the forms in \fIform-list\fR to be printed on \fIprinter\fR. By
default no forms are allowed on a new printer.
.sp
For each printer, the \fBLP\fR print service keeps two lists of forms: an
``allow-list'' of forms that can be used with the printer, and a ``deny-list''
of forms that cannot be used with the printer. With the \fB\fR\fB-f\fR\fB
allow\fR option, the forms listed are added to the allow-list and removed from
the deny-list. With the \fB-f\fR \fBdeny\fR option, the forms listed are added
to the deny-list and removed from the allow-list.
.sp
If the allow-list is not empty, only the forms in the list can 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 cannot be used with
the printer. All forms can be excluded from a printer by specifying \fB-f\fR
\fBdeny:all\fR. All forms can be used on a printer (provided the printer can
handle all the characteristics of each form) by specifying \fB-f\fR
\fBallow:all\fR.
.sp
The \fBLP\fR 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.
.sp
If the administrator tries to specify a form as acceptable for use on a printer
that does not have the capabilities needed by the form, the command is
rejected.
.sp
Notice the other use of \fB-f\fR, with the \fB-M\fR option, below.
.sp
The \fB-T\fR option must be invoked first with \fBlpadmin\fR to identify the
printer type before the \fB-f\fR option can be used.
.RE

.sp
.ne 2
.na
\fB\fB-F\fR \fIfault-recovery\fR\fR
.ad
.sp .6
.RS 4n
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
\fIfault-recovery\fR:
.sp
.ne 2
.na
\fB\fBcontinue\fR\fR
.ad
.RS 13n
Continue printing on the top of the page where printing stopped. This requires
a filter to wait for the fault to clear before automatically continuing.
.RE

.sp
.ne 2
.na
\fB\fBbeginning\fR\fR
.ad
.RS 13n
Start printing the request again from the beginning.
.RE

.sp
.ne 2
.na
\fB\fBwait\fR\fR
.ad
.RS 13n
Disable printing on \fIprinter\fR and wait for the administrator or a user to
enable printing again.
.sp
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 \fB-i\fR option of the \fBlp\fR 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.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-h\fR\fR
.ad
.sp .6
.RS 4n
Indicate that the device associated with the printer is hardwired. If neither
of the mutually exclusive options, \fB-h\fR and \fB-l\fR, is specified,
\fB-h\fR is assumed.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR \fIinterface\fR\fR
.ad
.sp .6
.RS 4n
Establish a new interface program for \fIprinter\fR. \fIinterface\fR is the
pathname of the new program. (The \fB-e\fR and \fB-m\fR options must not be
specified with this option.)
.RE

.sp
.ne 2
.na
\fB\fB-I\fR \fIcontent-type-list\fR\fR
.ad
.sp .6
.RS 4n
Allow \fIprinter\fR to handle print requests with the content types listed in a
\fIcontent-type-list\fR.
.sp
The type \fBsimple\fR is recognized as the default content type for files in
the UNIX system. A \fBsimple\fR type of file is a data stream containing only
printable \fBASCII\fR characters and the following control characters:
.sp

.sp
.TS
c c c
l l l .
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
.TE

To prevent the print service from considering \fBsimple\fR a valid type for the
printer, specify either an explicit value (such as the printer type) in the
\fIcontent-type-list\fR, or an empty list. If you do want \fBsimple\fR included
along with other types, you must include \fBsimple\fR in the
\fIcontent-type-list\fR.
.sp
In addition to content types defined by the print administrator, the type
\fBPostScript\fR is recognized and supported by the Solaris print subsystem.
This includes filters to support \fBPostScript\fR as the printer content type.
.sp
The type \fBany\fR 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.
.sp
Except for \fBsimple\fR and \fBany\fR, each \fIcontent-type\fR name is
determined by the administrator. If the printer type is specified by the
\fB-T\fR option, then the printer type is implicitly considered to be also a
valid content type.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR\fR
.ad
.sp .6
.RS 4n
Indicate that the device associated with \fIprinter\fR is a login terminal. The
LP scheduler (\fBlpsched\fR) disables all login terminals automatically each
time it is started. (The \fB-h\fR option must not be specified with this
option.)
.RE

.sp
.ne 2
.na
\fB\fB-m\fR \fImodel\fR\fR
.ad
.sp .6
.RS 4n
Select \fImodel\fR interface program, provided with the \fBLP\fR print service,
for the printer. (Options \fB-e\fR and \fB-i\fR must not be specified with this
option.)
.RE

.sp
.ne 2
.na
\fB\fB-M\fR \fB-f\fR \fIform-name\fR [\fB-a\fR [\fB-o\fR \fBfilebreak\fR]]
[\fB-t\fR \fItray-number\fR]]\fR
.ad
.sp .6
.RS 4n
Mount the form \fIform-name\fR on \fIprinter\fR. Print requests that need the
pre-printed form \fIform-name\fR is printed on \fIprinter\fR. If more than one
printer has the form mounted and the user has specified \fBany\fR (with the
\fB-d\fR option of the \fBlp\fR command) as the printer destination, then the
print request is printed on the one printer that also meets the other needs of
the request.
.sp
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 \fBterminfo\fR 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.
.sp
If the \fB-a\fR 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. Printing 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
printing as many alignment patterns as desired. The administrator can quit the
printing of alignment patterns by typing \fBq\fR.
.sp
If the \fB-o\fR \fBfilebreak\fR 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.
.sp
If the \fB-t\fR \fItray-number\fR option is specified, printer tray
\fItray-number\fR is used.
.sp
A form is ``unmounted'' either by mounting a new form in its place or by using
the \fB-f\fR \fBnone\fR option. By default, a new printer has no form mounted.
.sp
Notice the other use of \fB-f\fR without the \fB-M\fR option above.
.RE

.sp
.ne 2
.na
\fB\fB-M\fR \fB-S\fR \fIprint-wheel\fR\fR
.ad
.sp .6
.RS 4n
Mount the \fIprint-wheel\fR on \fIprinter\fR. Print requests that need the
\fIprint-wheel\fR are printed on \fIprinter\fR. If more than one printer has
\fIprint-wheel\fR mounted and the user has specified \fBany\fR (with the
\fB-d\fR option of the \fBlp\fR command) as the printer destination, then the
print request is printed on the one printer that also meets the other needs of
the request.
.sp
If the \fIprint-wheel\fR 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.
.sp
A print wheel is ``unmounted'' either by mounting a new print wheel in its
place or by using the option \fB-S\fR \fBnone\fR. By default, a new printer has
no print wheel mounted.
.sp
Notice the other uses of the \fB-S\fR option without the \fB-M\fR option
described below.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR \fIppdfilename\fR\fR
.ad
.sp .6
.RS 4n
Specify a \fBPPD\fR file for creating and modifying printer queues.
\fIppdfilename\fR is the full path and file name to the \fBPPD\fR file. Used in
conjunction with the \fB-p\fR, \fB-d\fR, \fB-x\fR, or \fB-S\fR options.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR \fIoption\fR\fR
.ad
.sp .6
.RS 4n
The \fB-o\fR option defines default printer configuration values given to an
interface program. The default can be explicitly overwritten for individual
requests by the user (see \fBlp\fR(1)), or taken from a preprinted form
description (see \fBlpforms\fR(1M) and \fBlp\fR(1)).
.sp
There are several options which are predefined by the system. In addition, any
number of key-value pairs can be defined. See the section "Predefined Options
Used with the \fB-o\fR Option", below.
.RE

.sp
.ne 2
.na
\fB\fB-P\fR \fIpaper-name\fR\fR
.ad
.sp .6
.RS 4n
Specify a paper type list that the printer supports.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR \fIclass\fR\fR
.ad
.sp .6
.RS 4n
Remove \fIprinter\fR from the specified \fIclass\fR. If \fIprinter\fR is the
last member of \fIclass\fR, then \fIclass\fR is removed.
.RE

.sp
.ne 2
.na
\fB\fB-S\fR \fIlist\fR\fR
.ad
.sp .6
.RS 4n
Allow either the print wheels or aliases for character sets named in \fIlist\fR
to be used on the printer.
.sp
If the printer is a type that takes print wheels, then \fIlist\fR is a comma or
space separated list of print wheel names. These are 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 are considered mountable on the printer, and print requests that ask for
a particular print wheel with this printer are rejected.
.sp
If the printer is a type that has selectable character sets, then \fIlist\fR is
a list of character set name ``mappings'' or aliases. Each ``mapping'' is of
the form \fIknown-name=alias\fR The \fIknown-name\fR is a character set number
preceded by \fBcs\fR (such as \fBcs3\fR for character set three) or a character
set name from the \fBterminfo\fR database entry \fBcsnm\fR. See
\fBterminfo\fR(4). If this option is not used to specify a list, only the names
already known from the \fBterminfo\fR database or numbers with a prefix of
\fBcs\fR is acceptable for the printer. If \fIlist\fR is the word \fBnone\fR,
any existing print wheel lists or character set aliases are removed.
.sp
Notice the other uses of the \fB-S\fR with the \fB-M\fR option described above.
.sp
The \fB-T\fR option must be invoked first with \fBlpadmin\fR to identify the
printer type before the \fB-S\fR option can be used.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fIsystem-name\fR\fR
.ad
.sp .6
.RS 4n
The \fB-s\fR option can be used for both remote or local printers. For remote
printers:
.sp
.ne 2
.na
\fB\fB-s\fR \fIsystem-name\fR[\fB!\fR\fIprinter-name\fR] (UUCP format)\fR
.ad
.br
.na
\fB\fB-s\fR \fIprinter-name\fR\fB@\fR\fIsystem-name\fR (RCMD format)\fR
.ad
.sp .6
.RS 4n
Make a remote printer (one that must be accessed through another system)
accessible to users on your system. \fIsystem-name\fR is the name of the remote
system on which the remote printer is located it. \fIprinter-name\fR is the
name used on the remote system for that printer. For example, if you want to
access \fIprinter1\fR on \fIsystem1\fR and you want it called \fIprinter2\fR on
your system:
.sp
.in +2
.nf
\fB-p\fR \fIprinter2\fR \fB-s\fR \fIsystem1\fR\fB!\fR\fIprinter1\fR
.fi
.in -2
.sp

.sp
.in +2
.nf
\fB-p\fR \fIprinter2\fR \fB-s\fR \fIprinter1\fR\fB@\fR\fIsystem1\fR
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fIscheme\fR\fB://\fR\fIend-point\fR (URI format)\fR
.ad
.sp .6
.RS 4n
Make a remote printer (one that must be accessed through another system)
accessible to users on your system. The supported schemes include \fBlpd\fR and
\fBipp\fR. Specify URI's using the \fBlpd\fR format as follows:
.sp
.in +2
.nf
\fBlpd://\fR\fIserver\fR/\fIprinters\fR/\fIqueue\fR\fB[#Solaris]\fR
.fi
.in -2
.sp

URI's using the \fBipp\fR format are defined by the remote print server. They
are generally of the format:
.sp
.in +2
.nf
\fBipp://\fR\fIserver\fR\fB/\fR\fIprinters\fR\fB/\fR\fIqueue\fR
.fi
.in -2
.sp

In either case, \fIserver\fR specifies the hostname or IP address of the remote
print server, \fIqueue\fR specifies the name of the print queue on the remote
print server, and the optional \fB#Solaris\fR specifies that the remote print
server is a Solaris server when \fBlpd\fR URI format is being used.
.sp
For example:
.sp
.in +2
.nf
\fB-p\fR \fIprinter\fR \fB-s\fR \fBlpd://\fR\fIserver\fR\fB/\fR\fIprinters\fR\fB/\fR\fIqueue\fR\fB#Solaris\fR
\fB-p\fR \fIprinter\fR \fB-s\fR \fBipp://\fR\fIserver\fR\fB/\fR\fIprinters\fR\fB/\fR\fIqueue\fR
.fi
.in -2
.sp

.RE

For local printers:
.sp
.ne 2
.na
\fB\fB-s\fR "\fBlocalhost\fR"\fR
.ad
.RS 18n
Use \fBlocalhost\fR for the \fIsystem-name\fR to be used by the print service.
In an environment where the nodename is variable, print queues are invalidated
when the nodename changes. Using \fBlocalhost\fR as the \fIsystem-name\fR
allows print queues to be maintained across changing nodenames. The
\fIsystem-name\fR, as used by the print service, is only set to \fBlocalhost\fR
when explicitly set with this option; by default, \fBlpadmin\fR sets
\fIsystem-name\fR to \fInodename\fR. For example, if you want to configure a
new printer on the local system, and want it called \fIprinter3\fR:
.sp
\fB-p\fR \fIprinter3\fR \fB-s\fR \fIlocalhost\fR \fB-v\fR \fIdevice\fR
.sp
This option should never be used when creating name service maps.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-T\fR \fIprinter-type-list\fR\fR
.ad
.sp .6
.RS 4n
Identify the printer as being of one or more \fIprinter-type\fRs. Each
\fIprinter-type\fR is used to extract data from the \fBterminfo\fR database;
this information is used to initialize the printer before printing each user's
request. Some filters might also use a \fIprinter-type\fR to convert content
for the printer. If this option is not used, the default \fIprinter-type\fR is
\fBunknown\fR. No information is extracted from \fBterminfo\fR so each user
request is printed without first initializing the printer. Also, this option
must be used if the following are to work: \fB\fR\fB-o\fR\fB cpi\fR,
\fB\fR\fB-o\fR\fB lpi\fR, \fB\fR\fB-o\fR width, and \fB\fR\fB-o\fR\fB length\fR
options of the \fBlpadmin\fR and \fBlp\fR commands, and the \fB-S\fR and
\fB-f\fR options of the \fBlpadmin\fR command.
.sp
If the \fIprinter-type-list\fR contains more than one type, then the
\fIcontent-type-list\fR of the \fB-I\fR option must either be specified as
\fBsimple\fR, as empty (\fB\fR\fB-I\fR\fB ""\fR), or not specified at all.
.RE

.sp
.ne 2
.na
\fB\fB\fR\fB-t\fR\fInumber-of-trays\fR\fR
.ad
.sp .6
.RS 4n
Specify the number of trays when creating the printer.
.RE

.sp
.ne 2
.na
\fB\fB-u\fR \fBallow:\fR\fIlogin-ID-list\fR\fR
.ad
.br
.na
\fB\fB-u\fR \fBdeny:\fR\fIlogin-ID-list\fR\fR
.ad
.sp .6
.RS 4n
Allow or deny the users in \fIlogin-ID-list\fR access to the printer. By
default all users are allowed on a new printer. The \fIlogin-ID-list\fR
argument can include any or all of the following constructs:
.sp
.ne 2
.na
\fB\fIlogin-ID\fR\fR
.ad
.RS 24n
a user on any system
.RE

.sp
.ne 2
.na
\fB\fIsystem-name\fR\fB!\fR\fIlogin-ID\fR\fR
.ad
.RS 24n
a user on system \fIsystem-name\fR
.RE

.sp
.ne 2
.na
\fB\fIsystem-name\fR\fB!all\fR\fR
.ad
.RS 24n
all users on system \fIsystem-name\fR
.RE

.sp
.ne 2
.na
\fB\fBall!\fR\fIlogin-ID\fR\fR
.ad
.RS 24n
a user on all systems
.RE

.sp
.ne 2
.na
\fB\fBall\fR\fR
.ad
.RS 24n
all users on all systems
.RE

For each printer, the \fBLP\fR 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 \fB\fR\fB-u\fR\fB allow\fR
option, the users listed are added to the allow-list and removed from the
deny-list. With the \fB\fR\fB-u\fR\fB deny\fR option, the users listed are
added to the deny-list and removed from the allow-list.
.sp
If the allow-list is not empty, only the users in the list can 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 cannot use the printer. All
users can be denied access to the printer by specifying \fB\fR\fB-u\fR\fB
deny:all\fR. All users can use the printer by specifying \fB\fR\fB-u\fR\fB
allow:all\fR.
.RE

.sp
.ne 2
.na
\fB\fR
.ad
.sp .6
.RS 4n
The \fB-U\fR option allows your print service to access a remote printer. (It
does not enable your print service to access a remote printer service.)
Specifically, \fB-U\fR assigns the ``dialing'' information \fIdial-info\fR to
the printer. \fIdial-info\fR is used with the \fBdial\fR routine to call the
printer. Any network connection supported by the Basic Networking Utilities
works. \fIdial-info\fR can be either a phone number for a modem connection, or
a system name for other kinds of connections. Or, if \fB-U\fR \fBdirect\fR is
given, no dialing takes place, because the name \fBdirect\fR 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 \fB/etc/uucp/Systems\fR or related
files. The Basic Networking Utilities are required to support this option. By
default, \fB\fR\fB-U\fR\fB direct\fR is assumed.
.RE

.sp
.ne 2
.na
\fB\fB\fR\fB-v\fR \fIdevice\fR\fR
.ad
.sp .6
.RS 4n
Associate a \fIdevice\fR with \fIprinter\fR. \fIdevice\fR is the path name of a
file that is writable by \fBlp\fR. Notice that the same \fIdevice\fR can be
associated with more than one printer.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR \fIscheme\fR\fB://\fR\fIend-point\fR\fR
.ad
.sp .6
.RS 4n
Associate a network attached device with printer.
.sp
\fIscheme\fR is the method or protocol used to access the network attached
device and \fIend-point\fR is the information necessary to contact that network
attached device. Use of this device format requires the use of the \fBuri\fR
interface script and can only be used with the \fBsmb\fR scheme at this time.
.sp
For example:
.sp
.in +2
.nf
# lpadmin \fB-p\fR \fIqueue\fR \fB-v\fR \fBsmb://smb-\fR\fIservice\fR\fB/\fR\fIprinter\fR \fB-m\fR \fBuri\fR
.fi
.in -2
.sp

See the \fBsmbspool\fR man page for details.
.RE

.SS "Removing a Printer Destination"
The \fB-x\fR \fIdest\fR option removes the destination \fIdest\fR (a printer or
a class), from the \fBLP\fR print service. If \fIdest\fR is a printer and is
the only member of a class, then the class is deleted, too. If \fIdest\fR is
\fBall\fR, all printers and classes are removed. If there are no remaining
local printers and the scheduler is still running, the scheduler is shut down.
.sp
.LP
No other \fIoptions\fR are allowed with \fB-x\fR.
.SS "Setting/Changing the System Default Destination"
The \fB-d\fR [\fIdest\fR] option makes \fIdest\fR (an existing printer or
class) the new system default destination. If \fIdest\fR is not supplied, then
there is no system default destination. No other \fIoptions\fR are allowed with
\fB-d\fR.
.SS "Setting an Alert for a Print Wheel"
.ne 2
.na
\fB\fB-S\fR \fIprint-wheel\fR [\fB-A\fR \fIalert-type\fR] [\fB-W\fR
\fIminutes\fR] [\fB-Q\fR \fIrequests\fR] \fB-T\fR\fR
.ad
.sp .6
.RS 4n
The \fB-S\fR \fIprint-wheel\fR option is used with the \fB-A\fR
\fIalert-type\fR option to define an alert to mount the print wheel when there
are jobs queued for it. If this command is not used to arrange alerting for a
print wheel, no alert is sent for the print wheel. Notice the other use of
\fB-A\fR, with the \fB-p\fR option, above.
.sp
The \fIalert-types\fR are:
.sp
.ne 2
.na
\fB\fBmail\fR\fR
.ad
.RS 17n
Send the alert message using the \fBmail\fR command to the administrator.
.RE

.sp
.ne 2
.na
\fB\fBwrite\fR\fR
.ad
.RS 17n
Write the message, using the \fBwrite\fR command, to the terminal on which the
administrator is logged in. If the administrator is logged in on several
terminals, one is arbitrarily chosen.
.RE

.sp
.ne 2
.na
\fB\fBquiet\fR\fR
.ad
.RS 17n
Do not send messages for the current condition. An administrator can use this
option to temporarily stop receiving further messages about a known problem.
Once the \fIprint-wheel\fR has been mounted and subsequently unmounted,
messages are sent again when the number of print requests reaches the threshold
specified by the \fB-Q\fR option.
.RE

.sp
.ne 2
.na
\fB\fBnone\fR\fR
.ad
.RS 17n
Do not send messages until the \fB-A\fR option is given again with a different
\fIalert-type\fR (other than \fBquiet\fR).
.RE

.sp
.ne 2
.na
\fB\fIshell-command\fR\fR
.ad
.RS 17n
Run the \fIshell-command\fR 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
\fBmail\fR and \fBwrite\fR values for this option are equivalent to the values
\fBmail\fR \fIuser-name\fR and \fBwrite\fR \fIuser-name\fR respectively, where
\fIuser-name\fR is the current name for the administrator. This is the login
name of the person submitting this command unless he or she has used the
\fBsu\fR command to change to another user ID. If the \fBsu\fR command has been
used to change the user ID, then the \fIuser-name\fR for the new ID is used.
.RE

.sp
.ne 2
.na
\fB\fBlist\fR\fR
.ad
.RS 17n
Display the type of the alert for the print wheel on standard output. No change
is made to the alert.
.RE

The message sent appears as follows:
.sp
.in +2
.nf
The print wheel \fIprint-wheel\fR needs to be mounted
on the printer(s):
\fIprinter\fR(\fIinteger1\fRrequests) \fIinteger2\fR print requests
await this print wheel.
.fi
.in -2
.sp

The printers listed are those that the administrator had earlier specified were
candidates for this print wheel. The number \fIinteger1\fR listed next to each
printer is the number of requests eligible for the printer. The number
\fIinteger2\fR shown after the printer list is the total number of requests
awaiting the print wheel. It is less than the sum of the other numbers if some
requests can be handled by more than one printer.
.sp
If the \fIprint-wheel\fR is \fBall\fR, the alerting defined in this command
applies to all print wheels already defined to have an alert.
.sp
If the \fB-W\fR option is not given, the default procedure is that only one
message is sent per need to mount the print wheel. Not specifying the \fB-W\fR
option is equivalent to specifying \fB\fR\fB-W\fR\fB once\fR or \fB-W\fR
\fB0\fR. If \fIminutes\fR is a number greater than zero, an alert is sent at
intervals specified by \fIminutes\fR.
.sp
If the \fB-Q\fR option is also given, the alert is sent when a certain number
(specified by the argument \fIrequests\fR) of print requests that need the
print wheel are waiting. If the \fB-Q\fR option is not given, or \fIrequests\fR
is 1 or \fBany\fR (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.
.RE

.SH PREDEFINED OPTIONS USED WITH THE \fB-o\fR OPTION
A number of options, described below, are predefined for use with \fB-o\fR.
These options are used for adjusting printer capabilities, adjusting printer
port characteristics, configuring network printers, and controlling the use of
banner. The \fB-o\fR also supports an arbitrary \fB\fIkeyword\fR=\fIvalue\fR\fR
format, which is referred to below as an undefined option.
.SS "Adjusting Printer Capabilities"
The \fBlength\fR, \fBwidth\fR, \fBcpi\fR, and \fBlpi\fR parameters can be used
in conjunction with the \fB-o\fR option to adjust printer capabilities. The
format of the parameters and their values is as follows:
.sp
.in +2
.nf
length=\fIscaled-decimal-number\fR
width=\fIscaled-decimal-number\fR
cpi=\fIscaled-decimal-number\fR
lpi=\fIscaled-decimal-number\fR
.fi
.in -2
.sp

.sp
.LP
The term \fIscaled-decimal-number\fR 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 \fIscaled-decimal-numbers\fR can be used
with the LP print service: numbers that show sizes in centimeters (marked with
a trailing \fBc\fR); numbers that show sizes in inches (marked with a trailing
\fBi\fR); 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.
.sp
.LP
The option values must agree with the capabilities of the type of physical
printer, as defined in the terminfo database for the printer type. If they do
not, the command is rejected.
.sp
.LP
The defaults are defined in the \fBterminfo\fR entry for the specified printer
type. The defaults can be reset by:
.sp
.in +2
.nf
\fBlpadmin -p \fIprintername\fR -o length=
lpadmin -p \fIprintername\fR -o width=
lpadmin -p \fIprintername\fR -o cpi=
lpadmin -p \fIprintername\fR -o lpi=\fR
.fi
.in -2
.sp

.SS "Adjusting Printer Port Characteristics"
You use the \fBstty\fR keyword in conjunction with the o option to adjust
printer port characteristics. The general form of the \fBstty\fR portion of the
command is:
.sp
.in +2
.nf
\fBstty="'\fR\fIstty-option-list\fR'"
.fi
.in -2
.sp

.sp
.LP
The \fIstty-option-list\fR is not checked for allowed values, but is passed
directly to the \fBstty\fR program by the standard interface program. Any error
messages produced by \fBstty\fR when a request is processed (by the standard
interface program) are mailed to the user submitting the request.
.sp
.LP
The default for \fBstty\fR is:
.sp
.in +2
.nf
stty="'9600 cs8 -cstopb -parenb ixon
     -ixany opost -olcuc onlcr
     -ocrnl -onocr
     -onlret -ofill nl0 cr0 tab0 bs0 vt0 ff0'"
.fi
.in -2
.sp

.sp
.LP
The default can be reset by:
.sp
.in +2
.nf
\fBlpadmin -p \fIprintername\fR -o stty=\fR
.fi
.in -2
.sp

.SS "Configuring Network Printers"
The \fBdest\fR, \fBprotocol\fR, \fBbsdctrl\fR, and \fBtimeout\fR parameters are
used in conjunction with the \fB-o\fR option to configure network printers. The
format of these keywords and their assigned values is as follows:
.sp
.in +2
.nf
dest=\fIstring\fR protocol=\fIstring\fR bsdctrl=\fIstring\fR \e
     timeout=\fInon-negative-integer-seconds\fR
.fi
.in -2
.sp

.sp
.LP
These four options are provided to support network printing. Each option is
passed directly to the interface program; any checking for allowed values is
done there.
.sp
.LP
The value of \fBdest\fR is the name of the destination for the network printer;
the semantics for value \fBdest\fR are dependent on the printer and the
configuration. There is no default.
.sp
.LP
The value of option \fBprotocol\fR sets the over-the-wire protocol to the
printer. The default for option \fBprotocol\fR is \fBbsd\fR. The value of
option \fBbsdctrl\fR sets the print order of control and data files (BSD
protocol only); the default for this option is \fBcontrol file first\fR. The
value of option \fBtimeout\fR sets the seed value for backoff time when the
printer is busy. The default value for the \fBtimeout\fR option is \fB10\fR
seconds. The defaults can be reset by:
.sp
.in +2
.nf
\fBlpadmin -p \fIprintername\fR -o protocol=
lpadmin -p \fIprintername\fR \fR\fB-o bsdctrl=\fR
lpadmin -p \fIprintername\fR -o timeout=
.fi
.in -2
.sp

.SS "Controlling the Use of the Banner Page"
Use the following commands to control the use of the banner page:
.sp
.in +2
.nf
\fBlpadmin -p \fIprinter\fR -o nobanner\fR
\fBlpadmin -p \fIprinter\fR -o banner\fR
\fBlpadmin -p \fIprinter\fR -o banner=always\fR
\fBlpadmin -p \fIprinter\fR -o banner=never\fR
\fBlpadmin -p \fIprinter\fR -o banner=optional\fR
.fi
.in -2
.sp

.sp
.LP
The first and fifth commands (\fB-o\fR \fBnobanner\fR and \fB-o\fR
\fBbanner=optional\fR) are equivalent. The default is to print the banner page,
unless a user specifies \fB-o\fR \fBnobanner\fR on an \fBlp\fR command line.
.sp
.LP
The second and third commands (\fB-o\fR \fBbanner\fR and \fB-o\fR
\fBbanner=always\fR) are equivalent. Both cause a banner page to be printed
always, even if a user specifies \fBlp\fR \fB-o\fR \fBnobanner\fR. The root
user can override this command.
.sp
.LP
The fourth command (\fB-o\fR \fBbanner=never\fR) causes a banner page never to
be printed, even if a user specifies \fBlp\fR \fB-o\fR \fBbanner\fR. The root
user can override this command.
.SS "Undefined Options"
The \fB-o\fR option supports the use of arbitrary, user-defined options with
the following format:
.sp
.ne 2
.na
\fB\fIkey\fR\fB=\fR\fIvalue\fR\fR
.ad
.sp .6
.RS 4n
Each \fIkey\fR\fB=\fR\fIvalue\fR is passed directly to the interface program.
Any checking for allowed values is done in the interface program.
.sp
Any default values for a given \fIkey\fR\fB=\fR\fIvalue\fR option are defined
in the interface program. If a default is provided, it can be reset by typing
the key without any value:
.sp
.in +2
.nf
lpadmin -p \fIprintername\fR -o \fIkey\fR=
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fBlpadmin\fR \fB-p\fR \fIprinter\fR \fB-o\fR \fBfoo | nofoo\fR\fR
.ad
.sp .6
.RS 4n
Sets boolean values \fBfoo=true | foo=false\fR.
.RE

.SH EXAMPLES
In the following examples, \fIprtr\fR can be any name up to 14 characters and
can be the same name as the \fBping\fR(1M) name.
.LP
\fBExample 1 \fRConfiguring an HP Postscript Printer with a Jet Direct Network
Interface
.sp
.LP
The following example configures an HP postscript printer with a jet direct
network interface:

.sp
.in +2
.nf
example# \fBlpadmin -p \fIprtr\fR -v /dev/null -m netstandard \e
          -o dest=\fIping_name_of_prtr\fR:9100 -o protocol=tcp -T PS -I \e
           postscript\fR
example# \fBenable \fIprtr\fR\fR
example# \fBaccept \fIprtr\fR\fR
.fi
.in -2
.sp

.LP
\fBExample 2 \fRConfiguring a Standard Postscript Network Printer
.sp
.LP
The following example configures a standard postscript network printer:

.sp
.in +2
.nf
example# \fBlpadmin -p \fIprtr\fR -v /dev/null -m netstandard \e
         -o dest=\fIping_name_of_prtr\fR -T PS -I postscript\fR
example# \fBenable \fIprtr\fR\fR
example# \fBaccept \fIprtr\fR\fR
.fi
.in -2
.sp

.SH EXIT STATUS
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 12n
Successful completion.
.RE

.sp
.ne 2
.na
\fBnon-zero\fR
.ad
.RS 12n
An error occurred.
.RE

.SH FILES
.ne 2
.na
\fB\fB/var/spool/lp/*\fR\fR
.ad
.RS 26n

.RE

.sp
.ne 2
.na
\fB\fB/etc/lp\fR\fR
.ad
.RS 26n

.RE

.sp
.ne 2
.na
\fB\fB/etc/lp/alerts/printer\fR\fR
.ad
.RS 26n
Fault handler for \fBlpadmin\fR
.RE

.sp
.ne 2
.na
\fB\fB/etc/printers.conf\fR\fR
.ad
.RS 26n
System printer configuration database
.RE

.SH ATTRIBUTES
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Obsolete
.TE

.SH SEE ALSO
\fBenable\fR(1), \fBlp\fR(1), \fBlpstat\fR(1), \fBmail\fR(1), \fBstty\fR(1),
\fBaccept\fR(1M), \fBlpforms\fR(1M), \fBlpsched\fR(1M), \fBlpsystem\fR(1M),
\fBping\fR(1M), \fBdial\fR(3NSL), \fBterminfo\fR(4), \fBattributes\fR(5)
.sp
.LP
\fI\fR
.SH NOTES
When using lpadmin to provide access to a remote printer, remote configuration
data is stored in \fB/etc/printers.conf\fR. This data includes a \fBbsdaddr\fR
and a \fBprinter-uri-supported\fR attribute. The data in this file can be
shared through the use of a network name service or replicated across multiple
systems. If the data is shared, it is important to make sure that the
\fBbsdaddr\fR and \fBprinter-uri-supported\fR contain hostname information that
is correctly resolved on all hosts sharing this data. Also, the
\fBprinter-uri-supported\fR is the preferred means of accessing remote print
service. The \fBbsdaddr\fR is supplied for backward compatibility with Solaris
2.6-10 systems.