[thirdparty/cups.git] / doc / help / ref-printers-conf.html

<HTML>
<!-- SECTION: References -->
<HEAD>
	<TITLE>printers.conf</TITLE>
</HEAD>
<BODY>

<P>The CUPS scheduler (cupsd) uses the
<VAR>/etc/cups/printers.conf</VAR> file to store the list of
available printers. This file contains only locally defined
printers, not remote printers that are created automatically via
browsing. Each directive is listed on a line by itself followed
by its value. Comments are introduced using the number sign ("#")
character at the beginning of a line.</P>

<P>While the printer configuration file consists of plain text
and can be modified using your favorite text editor, you should
normally use the <A HREF="man-lpadmin.html">lpadmin(8)</A>
command, web interface, or any of the available GUIs to manage
your printers instead. If you do choose to edit this file
manually, you will need to restart the scheduler to make them
active.</P>


<H2 CLASS="title"><A NAME="Accepting">Accepting</A></H2>

<H3>Examples</H3>

<PRE CLASS="command">
&lt;Printer name&gt;
  ...
  Accepting yes
&lt;/Printer&gt;
</PRE>

<H3>Description</H3>

<P>The <CODE>Accepting</CODE> directive defines the initial state
of the <VAR>printer-is-accepting-jobs</VAR> attribute. This state
is also set by the <CODE>accept(8)</CODE> and
<CODE>reject(8)</CODE> commands:</P>

<PRE CLASS="command">
<KBD>/usr/sbin/accept printername
/usr/sbin/reject printername</KBD>
</PRE>

<P>This directive must appear inside a <A
HREF="#Printer"><CODE>Printer</CODE></A> or <A
HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
section.</P>


<H2 CLASS="title"><A NAME="AllowUser">AllowUser</A></H2>

<H3>Examples</H3>

<PRE CLASS="command">
&lt;Printer name&gt;
  ...
  AllowUser foo_user
  AllowUser @bar_group
&lt;/Printer&gt;
</PRE>

<H3>Description</H3>

<P>The <CODE>AllowUser</CODE> directive adds a username or group
name to the <VAR>requesting-user-name-allowed</VAR> attribute
which can be set by the <CODE>lpadmin(8)</CODE> command:</P>

<PRE CLASS="command">
<KBD>/usr/sbin/lpadmin -p printername -u allow:foo_user,@bar_group</KBD>
</PRE>

<P>This directive must appear inside a <A
HREF="#Printer"><CODE>Printer</CODE></A> or <A
HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A> directive.
This directive cannot be used with <A
HREF="#DenyUser"><CODE>DenyUser</CODE></A>.</P>


<H2 CLASS="title"><A NAME="DefaultPrinter">DefaultPrinter</A></H2>

<H3>Examples</H3>

<PRE CLASS="command">
&lt;DefaultPrinter name&gt;
  ...
&lt;/Printer&gt;
</PRE>

<H3>Description</H3>

<P>The <CODE>DefaultPrinter</CODE> directive begins a printer
definition as the default server destination. The default server
destination can be set using the <CODE>lpadmin(8)</CODE>
command:</P>

<PRE CLASS="command">
<KBD>/usr/sbin/lpadmin -d printername</KBD>
</PRE>

<P>Note that the server default destination settings can be
overridden by the user's default destination settings which are
normally set using the <CODE>lpoptions(1)</CODE> command.</P>


<H2 CLASS="title"><A NAME="DenyUser">DenyUser</A></H2>

<H3>Examples</H3>

<PRE CLASS="command">
&lt;Printer name&gt;
  ...
  DenyUser foo_user
  DenyUser @bar_group
&lt;/Printer&gt;
</PRE>

<H3>Description</H3>

<P>The <CODE>DenyUser</CODE> directive adds a username or group
name to the <VAR>requesting-user-name-denied</VAR> attribute
which can be set by the <CODE>lpadmin(8)</CODE> command:</P>

<PRE CLASS="command">
<KBD>/usr/sbin/lpadmin -p printername -u deny:foo_user,@bar_group</KBD>
</PRE>

<P>This directive must appear inside a <A
HREF="#Printer"><CODE>Printer</CODE></A> or <A
HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A> directive.
This directive cannot be used with <A
HREF="#AllowUser"><CODE>AllowUser</CODE></A></P>


<H2 CLASS="title"><A NAME="DeviceURI">DeviceURI</A></H2>

<H3>Examples</H3>

<PRE CLASS="command">
&lt;Printer name&gt;
  ...
  DeviceURI socket://foo.bar.com:9100
&lt;/Printer&gt;
</PRE>

<H3>Description</H3>

<P>The <CODE>DeviceURI</CODE> directive defines the value of the 
<VAR>device-uri-attribute</VAR> attribute. It is normally set
using the <CODE>lpadmin(8)</CODE> command:</P>

<PRE CLASS="command">
<KBD>/usr/sbin/lpadmin -p printername -v device-uri</KBD>
</PRE>

<P>This directive must appear inside a <A
HREF="#Printer"><CODE>Printer</CODE></A> or <A
HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
section.</P>


<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="ErrorPolicy">ErrorPolicy</A></H2>

<H3>Examples</H3>

<PRE CLASS="command">
&lt;Printer name&gt;
  ...
  ErrorPolicy abort-job
&lt;/Printer&gt;
</PRE>

<H3>Description</H3>

<P>The <CODE>ErrorPolicy</CODE> directive defines the policy that
is used when a backend is unable to send a print job to the
printer. The <CODE>lpadmin(8)</CODE> command sets the current
error policy:</P>

<PRE CLASS="command">
<KBD>/usr/sbin/lpadmin -p printername -o printer-error-policy=stop-printer</KBD>
</PRE>

<P>The following values are supported:</P>

<UL>

	<LI><CODE>abort-job</CODE> - Abort the job and proceed
	with the next job in the queue</LI>

	<LI><CODE>retry-current-job</CODE> - Retry the current job
	immediately</LI>

	<LI><CODE>retry-job</CODE> - Retry the job after waiting
	for N seconds; the <VAR>cupsd.conf</VAR> <A
	HREF="ref-cupsd-conf.html#JobRetryInterval"><CODE>JobRetryInterval</CODE></A>
	directive controls the value of N</LI>

	<LI><CODE>stop-printer</CODE> - Stop the printer and keep
	the job for future printing; this is the default
	value</LI>

</UL>

<P>This directive must appear inside a <A
HREF="#Printer"><CODE>Printer</CODE></A> or <A
HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
section.</P>


<H2 CLASS="title"><A NAME="Info">Info</A></H2>

<H3>Examples</H3>

<PRE CLASS="command">
&lt;Printer name&gt;
  ...
  Info My Printer
&lt;/Printer&gt;
</PRE>

<H3>Description</H3>

<P>The <CODE>Info</CODE> directive defines the string for the 
<VAR>printer-info</VAR> attribute. It is normally set using the
<CODE>lpadmin(8)</CODE> command:</P>

<PRE CLASS="command">
<KBD>/usr/sbin/lpadmin -p printername -D "My Printer"</KBD>
</PRE>

<P>This directive must appear inside a <A
HREF="#Printer"><CODE>Printer</CODE></A> or <A
HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
section.</P>


<H2 CLASS="title"><A NAME="JobSheets">JobSheets</A></H2>

<H3>Examples</H3>

<PRE CLASS="command">
&lt;Printer name&gt;
  ...
  JobSheets none,standard
&lt;/Printer&gt;
</PRE>

<H3>Description</H3>

<P>The <CODE>JobSheets</CODE> directive specifies the default
banner pages  to print before and after a print job. In the above
example, only a <VAR>standard</VAR> banner will print after each
job. The <CODE>lpadmin(8)</CODE> command is normally used to set
the default banners:

<PRE CLASS="command">
<KBD>/usr/sbin/lpadmin -p printername -o job-sheets-default=none,standard</KBD>
</PRE>

<P>If only one banner file is specified, it will be printed
before the files in the job. If a second banner file is
specified, it is printed  after the files in the job.</P>

<P>The available banner pages depend on the local system
configuration; CUPS includes the following standard banner
files:</P>

<UL>

	<LI><CODE>none</CODE> - Do not produce a banner
	page.</LI>

	<LI><CODE>classified</CODE> - A banner page with a
	&quot;classified&quot; label at the top and bottom.</LI>

	<LI><CODE>confidential</CODE> - A banner page with a
	&quot;confidential&quot; label at the top and bottom.</LI>

	<LI><CODE>secret</CODE> - A banner page with a
	&quot;secret&quot; label at the top and bottom.</LI>

	<LI><CODE>standard</CODE> - A banner page with no label
	at the top and bottom.</LI>

	<LI><CODE>topsecret</CODE> - A banner page with a
	&quot;top secret&quot; label at the top and bottom.</LI>

	<LI><CODE>unclassified</CODE> - A banner page with an
	&quot;unclassified&quot; label at the top and bottom.</LI>

</UL>

<P>This directive must appear inside a <A
HREF="#Printer"><CODE>Printer</CODE></A> or <A
HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
section.</P>


<H2 CLASS="title"><A NAME="KLimit">KLimit</A></H2>

<H3>Examples</H3>

<PRE CLASS="command">
&lt;Printer name&gt;
  ...
  KLimit 1234
&lt;/Printer&gt;
</PRE>

<H3>Description</H3>

<P>The <CODE>KLimit</CODE> directive defines the value of the 
<VAR>job-k-limit</VAR> attribute. It is normally set using the
<CODE>lpadmin(8)</CODE> command:</P>

<PRE CLASS="command">
<KBD>/usr/sbin/lpadmin -p printername -o job-k-limit=1234</KBD>
</PRE>

<P>This directive must appear inside a <A
HREF="#Printer"><CODE>Printer</CODE></A> or <A
HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
section.</P>


<H2 CLASS="title"><A NAME="Location">Location</A></H2>

<H3>Examples</H3>

<PRE CLASS="command">
&lt;Printer name&gt;
  ...
  Location Building 3321
&lt;/Printer&gt;
</PRE>

<H3>Description</H3>

<P>The <CODE>Location</CODE> directive defines the string for the 
<VAR>printer-location</VAR> attribute. It is normally set using the
<CODE>lpadmin(8)</CODE> command:</P>

<PRE CLASS="command">
<KBD>/usr/sbin/lpadmin -p printername -L "Building 3321"</KBD>
</PRE>

<P>This directive must appear inside a <A
HREF="#Printer"><CODE>Printer</CODE></A> or <A
HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
section.</P>


<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="OpPolicy">OpPolicy</A></H2>

<H3>Examples</H3>

<PRE CLASS="command">
&lt;Printer name&gt;
  ...
  OpPolicy default
&lt;/Printer&gt;
</PRE>

<H3>Description</H3>

<P>The <CODE>OpPolicy</CODE> directive sets the operation policy
that is used for the printer. The <CODE>lpadmin(8)</CODE> command
sets the current operation policy:</P>

<PRE CLASS="command">
<KBD>/usr/sbin/lpadmin -p printername -o printer-op-policy=default</KBD>
</PRE>

<P>The default policy is named "default". All policies correspond
to those defined using the <VAR>cupsd.conf</VAR> <A
HREF="ref-cupsd-conf.html#Policy"><CODE>Policy</CODE></A>
section.</P>

<P>This directive must appear inside a <A
HREF="#Printer"><CODE>Printer</CODE></A> or <A
HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
section.</P>


<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="Option">Option</A></H2>

<H3>Examples</H3>

<PRE CLASS="command">
&lt;Printer name&gt;
  ...
  Option name value
  Option scaling 100
  Option page-left 72
&lt;/Printer&gt;
</PRE>

<H3>Description</H3>

<P>The <CODE>Option</CODE> directive specifies a default job
template attribute value. It is mapped to
<CODE>name-default</CODE> in the printer attributes and applied
to jobs as <CODE>name</CODE>.</P>

<P>This directive must appear inside a <A
HREF="#Printer"><CODE>Printer</CODE></A> or <A
HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
section.</P>


<H2 CLASS="title"><A NAME="PageLimit">PageLimit</A></H2>

<H3>Examples</H3>

<PRE CLASS="command">
&lt;Printer name&gt;
  ...
  PageLimit 1234
&lt;/Printer&gt;
</PRE>

<H3>Description</H3>

<P>The <CODE>PageLimit</CODE> directive defines the value of the 
<VAR>job-page-limit</VAR> attribute. It can be set using the
<CODE>lpadmin(8)</CODE> command:</P>

<PRE CLASS="command">
<KBD>/usr/sbin/lpadmin -p printername -o job-page-limit=1234</KBD>
</PRE>

<P>This directive must appear inside a <A
HREF="#Printer"><CODE>Printer</CODE></A> or <A
HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
section.</P>


<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="PortMonitor">PortMonitor</A></H2>

<H3>Examples</H3>

<PRE CLASS="command">
&lt;Printer name&gt;
  ...
  PortMonitor bcp
&lt;/Printer&gt;
</PRE>

<H3>Description</H3>

<P>The <CODE>PortMonitor</CODE> directive sets the filter program that
is used for every print job, typically to encode or package the print
data in a format acceptable for a particular printer interface. It is
set using the <CODE>lpadmin(8)</CODE> command:</P>

<PRE CLASS="command">
<KBD>/usr/sbin/lpadmin -p printername -o port-monitor=tbcp</KBD>
</PRE>

<P>The following standard port monitors are included with CUPS:</P>

<UL>

	<LI><CODE>bcp</CODE> - Encode PostScript print data using
	the Adobe Binary Control Protocol (BCP)</LI>

	<LI><CODE>none</CODE> - Do not use a port monitor</LI>

	<LI><CODE>tbcp</CODE> - Encode PostScript print data
	using the Adobe Tagged Binary Control Protocol
	(TBCP)</LI>

</UL>

<P>This directive must appear inside a <A
HREF="#Printer"><CODE>Printer</CODE></A> or <A
HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
section.</P>


<H2 CLASS="title"><A NAME="Printer">Printer</A></H2>

<H3>Examples</H3>

<PRE CLASS="command">
&lt;Printer name&gt;
  ...
&lt;/Printer&gt;
</PRE>

<H3>Description</H3>

<P>The <CODE>Printer</CODE> directive begins a printer
definition. Printers are added using the <CODE>lpadmin(8)</CODE>
command:

<PRE CLASS="command">
<KBD>/usr/sbin/lpadmin -p printername ...</KBD>
</PRE>


<H2 CLASS="title"><A NAME="QuotaPeriod">QuotaPeriod</A></H2>

<H3>Examples</H3>

<PRE CLASS="command">
&lt;Printer name&gt;
  ...
  QuotaPeriod 604800
&lt;/Printer&gt;
</PRE>

<H3>Description</H3>

<P>The <CODE>QuotaPeriod</CODE> directive defines the value of
the  <VAR>job-quota-period</VAR> attribute. Typical values are
86400 (1 day), 604800 (1 week), 2592000 (1 month), and 31536000
(1 year). It is set using the <CODE>lpadmin(8)</CODE>
command:</P>

<PRE CLASS="command">
<KBD>/usr/sbin/lpadmin -p printername -o job-quota-period=604800</KBD>
</PRE>

<P>This directive must appear inside a <A
HREF="#Printer"><CODE>Printer</CODE></A> or <A
HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
section.</P>


<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="Shared">Shared</A></H2>

<H3>Examples</H3>

<PRE CLASS="command">
&lt;Printer name&gt;
  ...
  Shared yes
&lt;/Printer&gt;
</PRE>

<H3>Description</H3>

<P>The <CODE>Shared</CODE> directive defines the initial value of
the <VAR>printer-is-shared</VAR> attribute. The strings
<VAR>yes</VAR> and <VAR>no</VAR> correspond to the true and false
values, respectively. The <CODE>lpadmin(8)</CODE> command sets
the current state:</P>

<PRE CLASS="command">
<KBD>/usr/sbin/lpadmin -p printername -o printer-is-shared=true</KBD>
</PRE>

<P>This directive must appear inside a <A
HREF="#Printer"><CODE>Printer</CODE></A> or <A
HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
section.</P>


<H2 CLASS="title"><A NAME="State">State</A></H2>

<H3>Examples</H3>

<PRE CLASS="command">
&lt;Printer name&gt;
  ...
  State idle
&lt;/Printer&gt;
</PRE>

<H3>Description</H3>

<P>The <CODE>State</CODE> directive defines the initial value of
the <VAR>printer-state</VAR> attribute. The strings
<VAR>idle</VAR> and <VAR>stopped</VAR> correspond to the IPP
enumeration values 3 and 5, respectively. The
<CODE>cupsenable(8)</CODE> and <CODE>cupsdisable(8)</CODE>
commands set the current state:</P>

<PRE CLASS="command">
<KBD>/usr/sbin/cupsenable printername</KBD>
<KBD>/usr/sbin/cupsdisable printername</KBD>
</PRE>

<P>This directive must appear inside a <A
HREF="#Printer"><CODE>Printer</CODE></A> or <A
HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
section.</P>


<H2 CLASS="title"><A NAME="StateMessage">StateMessage</A></H2>

<H3>Examples</H3>

<PRE CLASS="command">
&lt;Printer name&gt;
  ...
  StateMessage Ready to print.
&lt;/Printer&gt;
</PRE>

<H3>Description</H3>

<P>The <CODE>StateMessage</CODE> directive defines the initial
string for the  <VAR>printer-state-message</VAR> attribute. The
following are some example messages:</P>

<PRE CLASS="command">
StateMessage Connected to host_name...
StateMessage Connecting to printer_queue on port port_number...
StateMessage Network host host_name is busy; will retry in 30 seconds...
StateMessage Printer busy; will retry in 10 seconds...
StateMessage Printer is busy; retrying print job...
StateMessage Print file accepted - job ID id_number.
StateMessage Ready to print.
StateMessage Waiting for job to complete
</PRE>

<P>This directive must appear inside a <A
HREF="#Printer"><CODE>Printer</CODE></A> or <A
HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
section.</P>


<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="StateTime">StateTime</A></H2>

<H3>Examples</H3>

<PRE CLASS="command">
&lt;Printer name&gt;
  ...
  StateTime 1133542425
&lt;/Printer&gt;
</PRE>

<H3>Description</H3>

<P>The <CODE>StateTime</CODE> directive defines the UNIX time
(seconds since Jan 1, 1970) for the last state change of the
queue. It is mapped to the <VAR>printer-state-change-time</VAR>
attribute.</P>

<P>This directive must appear inside a <A
HREF="#Printer"><CODE>Printer</CODE></A> or <A
HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
section.</P>


</BODY>
</HTML>
Commit	Line	Data
ef416fc2	1	<HTML>
	2	<!-- SECTION: References -->
	3	<HEAD>
	4	<TITLE>printers.conf</TITLE>
	5	</HEAD>
	6	<BODY>
	7
	8	<P>The CUPS scheduler (cupsd) uses the
	9	<VAR>/etc/cups/printers.conf</VAR> file to store the list of
	10	available printers. This file contains only locally defined
	11	printers, not remote printers that are created automatically via
	12	browsing. Each directive is listed on a line by itself followed
	13	by its value. Comments are introduced using the number sign ("#")
	14	character at the beginning of a line.</P>
	15
	16	<P>While the printer configuration file consists of plain text
	17	and can be modified using your favorite text editor, you should
480ef0fe	18	normally use the <A HREF="man-lpadmin.html">lpadmin(8)</A>
	19	command, web interface, or any of the available GUIs to manage
	20	your printers instead. If you do choose to edit this file
	21	manually, you will need to restart the scheduler to make them
	22	active.</P>
ef416fc2	23
ef416fc2	24
480ef0fe	25	<H2 CLASS="title"><A NAME="Accepting">Accepting</A></H2>
ef416fc2	26
480ef0fe	27	<H3>Examples</H3>
ef416fc2	28
ef416fc2	29	<PRE CLASS="command">
480ef0fe	30	<Printer name>
	31	...
	32	Accepting yes
	33	</Printer>
ef416fc2	34	</PRE>
ef416fc2	35
480ef0fe	36	<H3>Description</H3>
ef416fc2	37
	38	<P>The <CODE>Accepting</CODE> directive defines the initial state
	39	of the <VAR>printer-is-accepting-jobs</VAR> attribute. This state
	40	is also set by the <CODE>accept(8)</CODE> and
	41	<CODE>reject(8)</CODE> commands:</P>
	42
	43	<PRE CLASS="command">
	44	<KBD>/usr/sbin/accept printername
	45	/usr/sbin/reject printername</KBD>
	46	</PRE>
	47
	48	<P>This directive must appear inside a <A
	49	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	50	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	51	section.</P>
ef416fc2	52
ef416fc2	53
480ef0fe	54	<H2 CLASS="title"><A NAME="AllowUser">AllowUser</A></H2>
ef416fc2	55
480ef0fe	56	<H3>Examples</H3>
ef416fc2	57
ef416fc2	58	<PRE CLASS="command">
480ef0fe	59	<Printer name>
	60	...
	61	AllowUser foo_user
	62	AllowUser @bar_group
	63	</Printer>
ef416fc2	64	</PRE>
ef416fc2	65
480ef0fe	66	<H3>Description</H3>
ef416fc2	67
	68	<P>The <CODE>AllowUser</CODE> directive adds a username or group
	69	name to the <VAR>requesting-user-name-allowed</VAR> attribute
	70	which can be set by the <CODE>lpadmin(8)</CODE> command:</P>
	71
	72	<PRE CLASS="command">
	73	<KBD>/usr/sbin/lpadmin -p printername -u allow:foo_user,@bar_group</KBD>
	74	</PRE>
	75
	76	<P>This directive must appear inside a <A
	77	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	78	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A> directive.
	79	This directive cannot be used with <A
	80	HREF="#DenyUser"><CODE>DenyUser</CODE></A>.</P>
	81
	82
480ef0fe	83	<H2 CLASS="title"><A NAME="DefaultPrinter">DefaultPrinter</A></H2>
ef416fc2	84
480ef0fe	85	<H3>Examples</H3>
ef416fc2	86
	87	<PRE CLASS="command">
	88	<DefaultPrinter name>
480ef0fe	89	...
ef416fc2	90	</Printer>
	91	</PRE>
	92
480ef0fe	93	<H3>Description</H3>
ef416fc2	94
	95	<P>The <CODE>DefaultPrinter</CODE> directive begins a printer
	96	definition as the default server destination. The default server
	97	destination can be set using the <CODE>lpadmin(8)</CODE>
	98	command:</P>
	99
	100	<PRE CLASS="command">
	101	<KBD>/usr/sbin/lpadmin -d printername</KBD>
	102	</PRE>
	103
	104	<P>Note that the server default destination settings can be
	105	overridden by the user's default destination settings which are
	106	normally set using the <CODE>lpoptions(1)</CODE> command.</P>
	107
	108
480ef0fe	109	<H2 CLASS="title"><A NAME="DenyUser">DenyUser</A></H2>
ef416fc2	110
480ef0fe	111	<H3>Examples</H3>
ef416fc2	112
ef416fc2	113	<PRE CLASS="command">
480ef0fe	114	<Printer name>
	115	...
	116	DenyUser foo_user
	117	DenyUser @bar_group
	118	</Printer>
ef416fc2	119	</PRE>
ef416fc2	120
480ef0fe	121	<H3>Description</H3>
ef416fc2	122
	123	<P>The <CODE>DenyUser</CODE> directive adds a username or group
	124	name to the <VAR>requesting-user-name-denied</VAR> attribute
	125	which can be set by the <CODE>lpadmin(8)</CODE> command:</P>
	126
	127	<PRE CLASS="command">
	128	<KBD>/usr/sbin/lpadmin -p printername -u deny:foo_user,@bar_group</KBD>
	129	</PRE>
	130
	131	<P>This directive must appear inside a <A
	132	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	133	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A> directive.
	134	This directive cannot be used with <A
	135	HREF="#AllowUser"><CODE>AllowUser</CODE></A></P>
	136
	137
480ef0fe	138	<H2 CLASS="title"><A NAME="DeviceURI">DeviceURI</A></H2>
ef416fc2	139
480ef0fe	140	<H3>Examples</H3>
ef416fc2	141
ef416fc2	142	<PRE CLASS="command">
480ef0fe	143	<Printer name>
	144	...
	145	DeviceURI socket://foo.bar.com:9100
	146	</Printer>
ef416fc2	147	</PRE>
ef416fc2	148
480ef0fe	149	<H3>Description</H3>
ef416fc2	150
	151	<P>The <CODE>DeviceURI</CODE> directive defines the value of the
	152	<VAR>device-uri-attribute</VAR> attribute. It is normally set
	153	using the <CODE>lpadmin(8)</CODE> command:</P>
	154
	155	<PRE CLASS="command">
	156	<KBD>/usr/sbin/lpadmin -p printername -v device-uri</KBD>
	157	</PRE>
	158
	159	<P>This directive must appear inside a <A
	160	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	161	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	162	section.</P>
ef416fc2	163
ef416fc2	164
480ef0fe	165	<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="ErrorPolicy">ErrorPolicy</A></H2>
ef416fc2	166
480ef0fe	167	<H3>Examples</H3>
ef416fc2	168
ef416fc2	169	<PRE CLASS="command">
480ef0fe	170	<Printer name>
480ef0fe	171	...
07725fee	172	ErrorPolicy abort-job
480ef0fe	173	</Printer>
ef416fc2	174	</PRE>
ef416fc2	175
480ef0fe	176	<H3>Description</H3>
ef416fc2	177
	178	<P>The <CODE>ErrorPolicy</CODE> directive defines the policy that
	179	is used when a backend is unable to send a print job to the
	180	printer. The <CODE>lpadmin(8)</CODE> command sets the current
	181	error policy:</P>
	182
	183	<PRE CLASS="command">
	184	<KBD>/usr/sbin/lpadmin -p printername -o printer-error-policy=stop-printer</KBD>
	185	</PRE>
	186
	187	<P>The following values are supported:</P>
	188
	189	<UL>
	190
07725fee	191	<LI><CODE>abort-job</CODE> - Abort the job and proceed
ef416fc2	192	with the next job in the queue</LI>
ef416fc2	193
ee571f26 MS	194	<LI><CODE>retry-current-job</CODE> - Retry the current job
	195	immediately</LI>
	196
ef416fc2	197	<LI><CODE>retry-job</CODE> - Retry the job after waiting
ef416fc2	198	for N seconds; the <VAR>cupsd.conf</VAR> <A
4744bd90	199	HREF="ref-cupsd-conf.html#JobRetryInterval"><CODE>JobRetryInterval</CODE></A>
ef416fc2	200	directive controls the value of N</LI>
	201
	202	<LI><CODE>stop-printer</CODE> - Stop the printer and keep
	203	the job for future printing; this is the default
	204	value</LI>
	205
	206	</UL>
	207
	208	<P>This directive must appear inside a <A
	209	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	210	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	211	section.</P>
ef416fc2	212
ef416fc2	213
480ef0fe	214	<H2 CLASS="title"><A NAME="Info">Info</A></H2>
ef416fc2	215
480ef0fe	216	<H3>Examples</H3>
ef416fc2	217
ef416fc2	218	<PRE CLASS="command">
480ef0fe	219	<Printer name>
	220	...
	221	Info My Printer
	222	</Printer>
ef416fc2	223	</PRE>
ef416fc2	224
480ef0fe	225	<H3>Description</H3>
ef416fc2	226
	227	<P>The <CODE>Info</CODE> directive defines the string for the
	228	<VAR>printer-info</VAR> attribute. It is normally set using the
	229	<CODE>lpadmin(8)</CODE> command:</P>
	230
	231	<PRE CLASS="command">
	232	<KBD>/usr/sbin/lpadmin -p printername -D "My Printer"</KBD>
	233	</PRE>
	234
	235	<P>This directive must appear inside a <A
	236	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	237	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	238	section.</P>
ef416fc2	239
ef416fc2	240
480ef0fe	241	<H2 CLASS="title"><A NAME="JobSheets">JobSheets</A></H2>
ef416fc2	242
480ef0fe	243	<H3>Examples</H3>
ef416fc2	244
ef416fc2	245	<PRE CLASS="command">
480ef0fe	246	<Printer name>
	247	...
	248	JobSheets none,standard
	249	</Printer>
ef416fc2	250	</PRE>
ef416fc2	251
480ef0fe	252	<H3>Description</H3>
ef416fc2	253
	254	<P>The <CODE>JobSheets</CODE> directive specifies the default
	255	banner pages to print before and after a print job. In the above
	256	example, only a <VAR>standard</VAR> banner will print after each
	257	job. The <CODE>lpadmin(8)</CODE> command is normally used to set
	258	the default banners:
	259
	260	<PRE CLASS="command">
	261	<KBD>/usr/sbin/lpadmin -p printername -o job-sheets-default=none,standard</KBD>
	262	</PRE>
	263
	264	<P>If only one banner file is specified, it will be printed
	265	before the files in the job. If a second banner file is
	266	specified, it is printed after the files in the job.</P>
	267
	268	<P>The available banner pages depend on the local system
	269	configuration; CUPS includes the following standard banner
	270	files:</P>
	271
	272	<UL>
	273
	274	<LI><CODE>none</CODE> - Do not produce a banner
	275	page.</LI>
	276
	277	<LI><CODE>classified</CODE> - A banner page with a
	278	"classified" label at the top and bottom.</LI>
	279
	280	<LI><CODE>confidential</CODE> - A banner page with a
	281	"confidential" label at the top and bottom.</LI>
	282
	283	<LI><CODE>secret</CODE> - A banner page with a
	284	"secret" label at the top and bottom.</LI>
	285
	286	<LI><CODE>standard</CODE> - A banner page with no label
	287	at the top and bottom.</LI>
	288
	289	<LI><CODE>topsecret</CODE> - A banner page with a
	290	"top secret" label at the top and bottom.</LI>
	291
	292	<LI><CODE>unclassified</CODE> - A banner page with an
	293	"unclassified" label at the top and bottom.</LI>
	294
	295	</UL>
	296
	297	<P>This directive must appear inside a <A
	298	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	299	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	300	section.</P>
ef416fc2	301
ef416fc2	302
480ef0fe	303	<H2 CLASS="title"><A NAME="KLimit">KLimit</A></H2>
ef416fc2	304
480ef0fe	305	<H3>Examples</H3>
ef416fc2	306
ef416fc2	307	<PRE CLASS="command">
480ef0fe	308	<Printer name>
	309	...
	310	KLimit 1234
	311	</Printer>
ef416fc2	312	</PRE>
ef416fc2	313
480ef0fe	314	<H3>Description</H3>
ef416fc2	315
	316	<P>The <CODE>KLimit</CODE> directive defines the value of the
	317	<VAR>job-k-limit</VAR> attribute. It is normally set using the
	318	<CODE>lpadmin(8)</CODE> command:</P>
	319
	320	<PRE CLASS="command">
	321	<KBD>/usr/sbin/lpadmin -p printername -o job-k-limit=1234</KBD>
	322	</PRE>
	323
	324	<P>This directive must appear inside a <A
	325	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	326	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	327	section.</P>
ef416fc2	328
ef416fc2	329
480ef0fe	330	<H2 CLASS="title"><A NAME="Location">Location</A></H2>
ef416fc2	331
480ef0fe	332	<H3>Examples</H3>
ef416fc2	333
ef416fc2	334	<PRE CLASS="command">
480ef0fe	335	<Printer name>
	336	...
	337	Location Building 3321
	338	</Printer>
ef416fc2	339	</PRE>
ef416fc2	340
480ef0fe	341	<H3>Description</H3>
ef416fc2	342
	343	<P>The <CODE>Location</CODE> directive defines the string for the
	344	<VAR>printer-location</VAR> attribute. It is normally set using the
	345	<CODE>lpadmin(8)</CODE> command:</P>
	346
	347	<PRE CLASS="command">
	348	<KBD>/usr/sbin/lpadmin -p printername -L "Building 3321"</KBD>
	349	</PRE>
	350
	351	<P>This directive must appear inside a <A
	352	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	353	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	354	section.</P>
ef416fc2	355
ef416fc2	356
480ef0fe	357	<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="OpPolicy">OpPolicy</A></H2>
ef416fc2	358
480ef0fe	359	<H3>Examples</H3>
ef416fc2	360
ef416fc2	361	<PRE CLASS="command">
480ef0fe	362	<Printer name>
	363	...
	364	OpPolicy default
	365	</Printer>
ef416fc2	366	</PRE>
ef416fc2	367
480ef0fe	368	<H3>Description</H3>
ef416fc2	369
	370	<P>The <CODE>OpPolicy</CODE> directive sets the operation policy
	371	that is used for the printer. The <CODE>lpadmin(8)</CODE> command
	372	sets the current operation policy:</P>
	373
	374	<PRE CLASS="command">
	375	<KBD>/usr/sbin/lpadmin -p printername -o printer-op-policy=default</KBD>
	376	</PRE>
	377
	378	<P>The default policy is named "default". All policies correspond
	379	to those defined using the <VAR>cupsd.conf</VAR> <A
4744bd90	380	HREF="ref-cupsd-conf.html#Policy"><CODE>Policy</CODE></A>
480ef0fe	381	section.</P>
ef416fc2	382
	383	<P>This directive must appear inside a <A
	384	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	385	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	386	section.</P>
ef416fc2	387
ef416fc2	388
480ef0fe	389	<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="Option">Option</A></H2>
ef416fc2	390
480ef0fe	391	<H3>Examples</H3>
ef416fc2	392
ef416fc2	393	<PRE CLASS="command">
480ef0fe	394	<Printer name>
	395	...
	396	Option name value
	397	Option scaling 100
	398	Option page-left 72
	399	</Printer>
ef416fc2	400	</PRE>
ef416fc2	401
480ef0fe	402	<H3>Description</H3>
	403
	404	<P>The <CODE>Option</CODE> directive specifies a default job
	405	template attribute value. It is mapped to
	406	<CODE>name-default</CODE> in the printer attributes and applied
	407	to jobs as <CODE>name</CODE>.</P>
	408
	409	<P>This directive must appear inside a <A
	410	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	411	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
	412	section.</P>
	413
	414
	415	<H2 CLASS="title"><A NAME="PageLimit">PageLimit</A></H2>
	416
	417	<H3>Examples</H3>
	418
	419	<PRE CLASS="command">
	420	<Printer name>
	421	...
	422	PageLimit 1234
	423	</Printer>
	424	</PRE>
	425
	426	<H3>Description</H3>
ef416fc2	427
	428	<P>The <CODE>PageLimit</CODE> directive defines the value of the
	429	<VAR>job-page-limit</VAR> attribute. It can be set using the
	430	<CODE>lpadmin(8)</CODE> command:</P>
	431
	432	<PRE CLASS="command">
	433	<KBD>/usr/sbin/lpadmin -p printername -o job-page-limit=1234</KBD>
	434	</PRE>
	435
	436	<P>This directive must appear inside a <A
	437	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	438	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	439	section.</P>
ef416fc2	440
ef416fc2	441
480ef0fe	442	<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="PortMonitor">PortMonitor</A></H2>
ef416fc2	443
480ef0fe	444	<H3>Examples</H3>
ef416fc2	445
ef416fc2	446	<PRE CLASS="command">
480ef0fe	447	<Printer name>
	448	...
	449	PortMonitor bcp
	450	</Printer>
ef416fc2	451	</PRE>
ef416fc2	452
480ef0fe	453	<H3>Description</H3>
ef416fc2	454
	455	<P>The <CODE>PortMonitor</CODE> directive sets the filter program that
	456	is used for every print job, typically to encode or package the print
	457	data in a format acceptable for a particular printer interface. It is
	458	set using the <CODE>lpadmin(8)</CODE> command:</P>
	459
	460	<PRE CLASS="command">
	461	<KBD>/usr/sbin/lpadmin -p printername -o port-monitor=tbcp</KBD>
	462	</PRE>
	463
	464	<P>The following standard port monitors are included with CUPS:</P>
	465
	466	<UL>
	467
	468	<LI><CODE>bcp</CODE> - Encode PostScript print data using
	469	the Adobe Binary Control Protocol (BCP)</LI>
	470
	471	<LI><CODE>none</CODE> - Do not use a port monitor</LI>
	472
	473	<LI><CODE>tbcp</CODE> - Encode PostScript print data
	474	using the Adobe Tagged Binary Control Protocol
	475	(TBCP)</LI>
	476
	477	</UL>
	478
	479	<P>This directive must appear inside a <A
	480	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	481	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	482	section.</P>
ef416fc2	483
ef416fc2	484
480ef0fe	485	<H2 CLASS="title"><A NAME="Printer">Printer</A></H2>
ef416fc2	486
480ef0fe	487	<H3>Examples</H3>
ef416fc2	488
	489	<PRE CLASS="command">
	490	<Printer name>
480ef0fe	491	...
ef416fc2	492	</Printer>
	493	</PRE>
	494
480ef0fe	495	<H3>Description</H3>
ef416fc2	496
	497	<P>The <CODE>Printer</CODE> directive begins a printer
	498	definition. Printers are added using the <CODE>lpadmin(8)</CODE>
	499	command:
	500
	501	<PRE CLASS="command">
	502	<KBD>/usr/sbin/lpadmin -p printername ...</KBD>
	503	</PRE>
	504
	505
480ef0fe	506	<H2 CLASS="title"><A NAME="QuotaPeriod">QuotaPeriod</A></H2>
ef416fc2	507
480ef0fe	508	<H3>Examples</H3>
ef416fc2	509
ef416fc2	510	<PRE CLASS="command">
480ef0fe	511	<Printer name>
	512	...
	513	QuotaPeriod 604800
	514	</Printer>
ef416fc2	515	</PRE>
ef416fc2	516
480ef0fe	517	<H3>Description</H3>
ef416fc2	518
	519	<P>The <CODE>QuotaPeriod</CODE> directive defines the value of
	520	the <VAR>job-quota-period</VAR> attribute. Typical values are
	521	86400 (1 day), 604800 (1 week), 2592000 (1 month), and 31536000
	522	(1 year). It is set using the <CODE>lpadmin(8)</CODE>
	523	command:</P>
	524
	525	<PRE CLASS="command">
	526	<KBD>/usr/sbin/lpadmin -p printername -o job-quota-period=604800</KBD>
	527	</PRE>
	528
	529	<P>This directive must appear inside a <A
	530	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	531	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	532	section.</P>
ef416fc2	533
ef416fc2	534
480ef0fe	535	<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="Shared">Shared</A></H2>
ef416fc2	536
480ef0fe	537	<H3>Examples</H3>
ef416fc2	538
ef416fc2	539	<PRE CLASS="command">
480ef0fe	540	<Printer name>
	541	...
	542	Shared yes
	543	</Printer>
ef416fc2	544	</PRE>
ef416fc2	545
480ef0fe	546	<H3>Description</H3>
ef416fc2	547
	548	<P>The <CODE>Shared</CODE> directive defines the initial value of
	549	the <VAR>printer-is-shared</VAR> attribute. The strings
	550	<VAR>yes</VAR> and <VAR>no</VAR> correspond to the true and false
	551	values, respectively. The <CODE>lpadmin(8)</CODE> command sets
	552	the current state:</P>
	553
	554	<PRE CLASS="command">
	555	<KBD>/usr/sbin/lpadmin -p printername -o printer-is-shared=true</KBD>
	556	</PRE>
	557
	558	<P>This directive must appear inside a <A
	559	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	560	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	561	section.</P>
ef416fc2	562
ef416fc2	563
480ef0fe	564	<H2 CLASS="title"><A NAME="State">State</A></H2>
ef416fc2	565
480ef0fe	566	<H3>Examples</H3>
ef416fc2	567
ef416fc2	568	<PRE CLASS="command">
480ef0fe	569	<Printer name>
	570	...
	571	State idle
	572	</Printer>
ef416fc2	573	</PRE>
ef416fc2	574
480ef0fe	575	<H3>Description</H3>
ef416fc2	576
	577	<P>The <CODE>State</CODE> directive defines the initial value of
	578	the <VAR>printer-state</VAR> attribute. The strings
	579	<VAR>idle</VAR> and <VAR>stopped</VAR> correspond to the IPP
	580	enumeration values 3 and 5, respectively. The
	581	<CODE>cupsenable(8)</CODE> and <CODE>cupsdisable(8)</CODE>
	582	commands set the current state:</P>
	583
	584	<PRE CLASS="command">
	585	<KBD>/usr/sbin/cupsenable printername</KBD>
	586	<KBD>/usr/sbin/cupsdisable printername</KBD>
	587	</PRE>
	588
	589	<P>This directive must appear inside a <A
	590	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	591	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	592	section.</P>
ef416fc2	593
ef416fc2	594
480ef0fe	595	<H2 CLASS="title"><A NAME="StateMessage">StateMessage</A></H2>
ef416fc2	596
480ef0fe	597	<H3>Examples</H3>
ef416fc2	598
ef416fc2	599	<PRE CLASS="command">
480ef0fe	600	<Printer name>
	601	...
	602	StateMessage Ready to print.
	603	</Printer>
ef416fc2	604	</PRE>
ef416fc2	605
480ef0fe	606	<H3>Description</H3>
ef416fc2	607
	608	<P>The <CODE>StateMessage</CODE> directive defines the initial
	609	string for the <VAR>printer-state-message</VAR> attribute. The
	610	following are some example messages:</P>
	611
	612	<PRE CLASS="command">
	613	StateMessage Connected to host_name...
	614	StateMessage Connecting to printer_queue on port port_number...
	615	StateMessage Network host host_name is busy; will retry in 30 seconds...
	616	StateMessage Printer busy; will retry in 10 seconds...
	617	StateMessage Printer is busy; retrying print job...
	618	StateMessage Print file accepted - job ID id_number.
	619	StateMessage Ready to print.
	620	StateMessage Waiting for job to complete
	621	</PRE>
	622
	623	<P>This directive must appear inside a <A
	624	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	625	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	626	section.</P>
ef416fc2	627
ef416fc2	628
480ef0fe	629	<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="StateTime">StateTime</A></H2>
ef416fc2	630
480ef0fe	631	<H3>Examples</H3>
ef416fc2	632
ef416fc2	633	<PRE CLASS="command">
480ef0fe	634	<Printer name>
	635	...
	636	StateTime 1133542425
	637	</Printer>
ef416fc2	638	</PRE>
ef416fc2	639
480ef0fe	640	<H3>Description</H3>
ef416fc2	641
	642	<P>The <CODE>StateTime</CODE> directive defines the UNIX time
	643	(seconds since Jan 1, 1970) for the last state change of the
	644	queue. It is mapped to the <VAR>printer-state-change-time</VAR>
	645	attribute.</P>
	646
	647	<P>This directive must appear inside a <A
	648	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	649	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	650	section.</P>
ef416fc2	651
	652
	653	</BODY>
	654	</HTML>