'\" te
.\" 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 PRINTERS.CONF 4 "Jun 2, 2006"
.SH NAME
printers.conf \- system printing configuration database
.SH SYNOPSIS
.LP
.nf
\fB/etc/printers.conf\fR
.fi

.SS "LDAP"
.LP
.nf
\fBou=printers\fR
.fi

.SS "NIS"
.LP
.nf
\fBprinters.conf.byname\fR
.fi

.SS "NIS+"
.LP
.nf
\fBprinters.org_dir\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBprinters.conf\fR file is the system printing configuration database.
System administrators use \fBprinters.conf\fR to describe destinations for the
print client commands and the print protocol adaptor. A destination names a
printer or class of printers. See \fBlpadmin\fR(1M). The \fBLP\fR print spooler
uses private \fBLP\fR configuration data for represented in the
\fBprinters.conf\fR database.
.sp
.LP
The \fBlpset\fR command can be used to define the printer table in NIS+. It
checks to see if the NIS+ table (\fBprinters.org_dir\fR) exists and if it does
not it goes ahead and creates it in the correct format. See \fBlpset\fR(1M) for
more information.
.SS "Entries"
.sp
.LP
Each entry in \fBprinters.conf\fR describes one destination. Entries are one
line consisting of any number of fields separated by colons (`\fB:\fR') and
terminated by a NEWLINE. The first field of each entry specifies the name of
the destination and aliases to which the entry describes. Specify one or more
names or aliases of the destination in this first field. Specify the
destination using atomic names. URI-style and POSIX-style names are not
acceptable. See \fBstandards\fR(5). Separate destination names by pipe signs
(`\fB|\fR').
.sp
.LP
Two destination names are reserved for special use in the first entry. Use
\fB_all\fR to specify the interest list for \fBlpget\fR, \fBlpstat\fR, and
\fBcancel\fR. Use \fB_default\fR to specify the default destination.
.sp
.LP
The remaining fields in an entry are \fIkey\fR\fB=\fR\fIvalue\fR pairs. See
\fBSpecifying Configuration Options\fR for details regarding
\fIkey\fR\fB=\fR\fIvalue\fR pairs.
.sp
.LP
Empty lines can be included for readability. Entries can continue on to
multiple lines by adding a backslash (`\fB\e\fR\&') as the last character in
the line. \fBprinters.conf\fR can include comments. Comments have a pound sign
(`\fB#\fR') as the first character in the line, and are terminated by a
NEWLINE. Use the \fBlpset\fR command to create or modify \fBprinters.conf\fR.
See \fBlpset\fR(1M). Do \fBnot\fR make changes in \fBprinters.conf\fR by using
an editor.
.SS "Specifying Configuration Options"
.sp
.LP
\fIkey\fR\fB=\fR\fIvalue\fR pairs are configuration options defined by the
system administrator. \fIkey\fR and \fIvalue\fR can be of arbitrary length.
Separate \fIkey\fR and \fIvalue\fR by the equal (`\fB='\fR) character.
.SS "Client/Server Configuration Options"
.sp
.LP
The following client/server configuration options (represented as
\fIkey\fR\fB=\fR\fIvalue\fR pairs) are supported:
.sp
.ne 2
.na
\fB\fBprinter-uri-supported=\fR\fIscheme\fR\fB://\fR\fIendpoint\fR\fR
.ad
.sp .6
.RS 4n
Provides the information necessary to contact the print service for the entry.
The scheme generally identifies the print service or protocol to use. Currently
this is limited to \fBlpsched\fR, \fBipp\fR, and \fBlpd\fR but might be
expanded in the future. Each of these schemes imposes a set of restrictions for
specifying the endpoint and the functionality provided.
.sp
.ne 2
.na
\fB\fBlpsched://\fR\fIlocalhost\fR\fB/printers/queue\fR\fR
.ad
.sp .6
.RS 4n
 This is URI form is used for print queues that are configured under the local
LP service.
.RE

.sp
.ne 2
.na
\fB\fBipp://\fR\fIserver\fR[:\fIport\fR\fB]/printers/queue\fR\fR
.ad
.br
.na
\fB\fBhttp://server:631/printers/queue\fR\fR
.ad
.br
.na
\fB\fBipp://\fR\fIserver\fR\fB[:\fR\fIport\fR\fB]/...\fR\fR
.ad
.sp .6
.RS 4n
This URI form is used for print queues that are remotely accessible by way of
the Internet Print Protocol. This protocol is the preferred method of accessing
remote print queues because it provides the greatest functionality over the
wire. The \fBipp\fR uri scheme is specified in the internet print protocol
specifications and is much more free form than listed above. The actual content
and format of the endpoint is determined by the remote print service.
.RE

.sp
.ne 2
.na
\fB\fBlpd://\fR\fIserver\fR\fB/printers/queue[#Solaris]\fR\fR
.ad
.sp .6
.RS 4n
This URI form is used for print queues that are remotely accessable by way of
the BSD Print Protocol. Though limited in capability, this protocol is widely
used between client and server. It provides maximium interoperability with
remote print services. When used to communicate with print services on a
Solaris print server, the optional \fB#Solaris\fR component of the URI
indicates that Solaris protcol extensions can be used during print job
submission.
.RE

If an entry does not contain a printer-uri-supported key/value pair, the
bsdaddr value is converted to its equivalent uri form and a
printer-uri-supported key/value pair is added to the resulting data returned to
applications requesting printer configuration data.
.RE

.sp
.ne 2
.na
\fB\fBbsdaddr=\fR\fIserver\fR\fB,\fR\fIdestination\fR[\fB,Solaris\fR]\fR
.ad
.sp .6
.RS 4n
Sets the server and destination name. Sets if the client generates protocol
extensions for use with the \fBlp\fR command (see \fBlp\fR(1)). \fBSolaris\fR
specifies a Solaris print server extension. If \fBSolaris\fR is not specified,
no protocol extensions are generated. \fIserver\fR is the name of the host
containing the queue for \fIdestination\fR. \fIdestination\fR is the atomic
name by which the server knows the destination.  If the configuration file
contents are to be shared with legacy systems (Solaris 2.6 - Solaris 10), this
key/value pair should be provided for backward compatability.
.RE

.sp
.ne 2
.na
\fB\fBuse=\fR\fIdestination\fR\fR
.ad
.sp .6
.RS 4n
Sets the destination to continue searching for configuration information.
\fIdestination\fR is an atomic, URI-style (\fIscheme\fR://\fIendpoint\fR), or
Posix-style name (\fBserver\fR:\fBprinter\fR).
.RE

.sp
.ne 2
.na
\fB\fBall=\fR\fIdestination_list\fR\fR
.ad
.sp .6
.RS 4n
Sets the interest list for the \fBlpget\fR, \fBlpstat\fR, and \fBcancel\fR
commands. \fIdestination_list\fR is a comma-separated list of destinations.
Specify \fIdestination\fR using atomic, URI-style
(\fIscheme\fR://\fIendpoint\fR), or Posix-style names (\fBserver:printer\fR).
See \fBlpget\fR(1M), \fBlpstat\fR(1), and \fBcancel\fR(1).
.RE

.SS "LP Server Options"
.sp
.LP
The following \fBLP\fR configuration options (represented as
\fIkey\fR\fB=\fR\fIvalue\fR pairs) are supported:
.sp
.ne 2
.na
\fB\fBuser-equivalence=\fR\fBtrue\fR|\fBfalse\fR\fR
.ad
.sp .6
.RS 4n
Sets whether or not usernames are considered equivalent when cancelling a print
request submitted from a different host in a networked environment. \fBtrue\fR
means that usernames are considered equivalent, and permits users to cancel a
print requests submitted from a different host. \fBuser-equivalence\fR is set
to \fBfalse\fR by default. \fBfalse\fR means that usernames are not considered
equivalent, and does not permit users cancel a print request submitted from a
different host. If \fBuser-equivalence\fR is set to \fBfalse\fR, print requests
can only be cancelled by the users on the host on whichs the print prequest was
generated or by the superuser on the print server.
.RE

.SS "Print Queue Name Resolution"
.sp
.LP
Applications needing to resolve print queue names (destinations) to the
associated print service and communications endpoint make use of a specific
name resolution ordering. Destination names in URI and POSIX form are complete
unto themselves and require no further resolution.  Names in atomic form are
resolved based on the \fBprinters\fR database entry in the /etc/nsswitch.conf
file. See nsswitch.conf(4)
.SS "Locating the Personal Default Destination"
.sp
.LP
The default destination is located differently depending on the command.
.sp
.LP
The \fBlp\fR command locates the default destination in the following order:
.RS +4
.TP
1.
\fBlp\fR command's \fB-d\fR \fIdestination\fR option.
.RE
.RS +4
.TP
2.
\fBLPDEST\fR environment variable.
.RE
.RS +4
.TP
3.
\fBPRINTER\fR environment variable.
.RE
.RS +4
.TP
4.
\fB_default\fR destination in \fB$HOME/.printers\fR.
.RE
.RS +4
.TP
5.
\fB_default\fR destination in \fB/etc/printers.conf\fR.
.RE
.sp
.LP
The \fBlpr\fR, \fBlpq\fR, and \fBlprm\fR commands locate the default
destination in the following order:
.RS +4
.TP
1.
\fBlpr\fR command's \fB-P\fR \fIdestination\fR option.
.RE
.RS +4
.TP
2.
\fBPRINTER\fR environment variable.
.RE
.RS +4
.TP
3.
\fBLPDEST\fR environment variable.
.RE
.RS +4
.TP
4.
\fB_default\fR destination in \fB$HOME/.printers\fR.
.RE
.RS +4
.TP
5.
\fB_default\fR destination in \fB/etc/printers.conf\fR.
.RE
.SS "Locating the Interest List for lpstat, lpget, and cancel"
.sp
.LP
The \fBlpget\fR, \fBlpstat\fR, and \fBcancel\fR commands locate the interest
list in the following order:
.RS +4
.TP
1.
\fB_all\fR list in \fB$HOME/.printers\fR.
.RE
.RS +4
.TP
2.
\fB_all\fR list in \fB/etc/printers.conf\fR.
.RE
.SH EXAMPLES
.LP
\fBExample 1 \fRSetting the Interest List
.sp
.LP
The following entry sets the interest list for the \fBlpget\fR, \fBlpstat\fR
and \fBcancel\fR commands to \fBprinter1\fR, \fBprinter2\fR and \fBprinter3\fR:

.sp
.in +2
.nf
\fB_all:all=printer1,printer2,printer3\fR
.fi
.in -2
.sp

.LP
\fBExample 2 \fRSetting the Server Name
.sp
.LP
The following entry sets the server name to \fBserver\fR and and printer name
to \fBps_printer\fR for destinations \fBprinter1\fR and \fBps\fR. It does not
generate BSD protocol extensions.

.sp
.in +2
.nf
\fBprinter1|ps:bsdaddr=server,ps_printer\fR
.fi
.in -2
.sp

.LP
\fBExample 3 \fRSetting Server Name and Destination Name
.sp
.LP
The following entry sets the server name to \fBserver\fR and destination name
to \fBpcl_printer\fR, for destination \fBprinter2\fR. It also generates
\fBSolaris\fR protocol extensions.

.sp
.in +2
.nf
\fBprinter2:printer-uri-supported=lpd\://server/printers/pcl_printer#Solaris\fR
.fi
.in -2
.sp

.LP
\fBExample 4 \fRSetting Server Name and Destination Name with Continuous Search
.sp
.LP
The following entry sets the server name to \fBserver\fR and destination name
to \fBnew_printer\fR, for destination \fBprinter3\fR. It also sets the
\fBprinter3\fR to continue searching for configuration information to printer
\fBanother_printer\fR.

.sp
.in +2
.nf
\fBprinter3:bsdaddr=server,new_printer:use=another_printer\fR
.fi
.in -2
.sp

.LP
\fBExample 5 \fRSetting Default Destination
.sp
.LP
The following entry sets the default destination to continue searching for
configuration information to destination \fBprinter1\fR.

.sp
.in +2
.nf
\fB_default:use=printer1\fR
.fi
.in -2
.sp

.LP
\fBExample 6 \fRUsing IPP as the URI
.sp
.LP
The following example uses IPP as the URI:

.sp
.in +2
.nf
\fBprinter4:printer-uri-supported=ipp\e://server/printers/queue\fR
.fi
.in -2
.sp

.SH FILES
.sp
.ne 2
.na
\fB\fB/etc/printers.conf\fR\fR
.ad
.RS 30n
System configuration database
.RE

.sp
.ne 2
.na
\fB\fB$HOME/.printers\fR\fR
.ad
.RS 30n
User-configurable printer database
.RE

.sp
.ne 2
.na
\fB\fBou=printers\fR\fR
.ad
.RS 30n
LDAP version of \fB/etc/printers.conf\fR
.RE

.sp
.ne 2
.na
\fB\fBprinters.conf.byname\fR (\fBNIS\fR)\fR
.ad
.RS 30n
\fBNIS\fR version of \fB/etc/printers.conf\fR
.RE

.sp
.ne 2
.na
\fB\fBprinters.org_dir\fR (\fBNIS+\fR)\fR
.ad
.RS 30n
\fBNIS+\fR version of \fB/etc/printers.conf\fR
.RE

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

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Stability Level	Stable
.TE

.SH SEE ALSO
.sp
.LP
\fBcancel\fR(1), \fBenable\fR(1), \fBenable\fR(1), \fBlp\fR(1), \fBlpq\fR(1B),
\fBlpr\fR(1B), \fBlprm\fR(1B), \fBlpstat\fR(1), \fBaccept\fR(1M),
\fBin.lpd\fR(1M), \fBlpadmin\fR(1M), \fBlpget\fR(1M), \fBlpmove\fR(1M),
\fBlpset\fR(1M), \fBaccept\fR(1M), \fBnsswitch.conf\fR(4), \fBprinters\fR(4),
\fBattributes\fR(5), \fBstandards\fR(5)
.sp
.LP
\fISystem Administration Guide: Basic Administration\fR