[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 cancel-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>cancel-job</CODE> - Cancel the job and proceed
	with the next job in the queue</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>
	171	...
	172	ErrorPolicy cancel-job
	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
	191	<LI><CODE>cancel-job</CODE> - Cancel the job and proceed
	192	with the next job in the queue</LI>
	193
	194	<LI><CODE>retry-job</CODE> - Retry the job after waiting
	195	for N seconds; the <VAR>cupsd.conf</VAR> <A
4744bd90	196	HREF="ref-cupsd-conf.html#JobRetryInterval"><CODE>JobRetryInterval</CODE></A>
ef416fc2	197	directive controls the value of N</LI>
	198
	199	<LI><CODE>stop-printer</CODE> - Stop the printer and keep
	200	the job for future printing; this is the default
	201	value</LI>
	202
	203	</UL>
	204
	205	<P>This directive must appear inside a <A
	206	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	207	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	208	section.</P>
ef416fc2	209
ef416fc2	210
480ef0fe	211	<H2 CLASS="title"><A NAME="Info">Info</A></H2>
ef416fc2	212
480ef0fe	213	<H3>Examples</H3>
ef416fc2	214
ef416fc2	215	<PRE CLASS="command">
480ef0fe	216	<Printer name>
	217	...
	218	Info My Printer
	219	</Printer>
ef416fc2	220	</PRE>
ef416fc2	221
480ef0fe	222	<H3>Description</H3>
ef416fc2	223
	224	<P>The <CODE>Info</CODE> directive defines the string for the
	225	<VAR>printer-info</VAR> attribute. It is normally set using the
	226	<CODE>lpadmin(8)</CODE> command:</P>
	227
	228	<PRE CLASS="command">
	229	<KBD>/usr/sbin/lpadmin -p printername -D "My Printer"</KBD>
	230	</PRE>
	231
	232	<P>This directive must appear inside a <A
	233	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	234	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	235	section.</P>
ef416fc2	236
ef416fc2	237
480ef0fe	238	<H2 CLASS="title"><A NAME="JobSheets">JobSheets</A></H2>
ef416fc2	239
480ef0fe	240	<H3>Examples</H3>
ef416fc2	241
ef416fc2	242	<PRE CLASS="command">
480ef0fe	243	<Printer name>
	244	...
	245	JobSheets none,standard
	246	</Printer>
ef416fc2	247	</PRE>
ef416fc2	248
480ef0fe	249	<H3>Description</H3>
ef416fc2	250
	251	<P>The <CODE>JobSheets</CODE> directive specifies the default
	252	banner pages to print before and after a print job. In the above
	253	example, only a <VAR>standard</VAR> banner will print after each
	254	job. The <CODE>lpadmin(8)</CODE> command is normally used to set
	255	the default banners:
	256
	257	<PRE CLASS="command">
	258	<KBD>/usr/sbin/lpadmin -p printername -o job-sheets-default=none,standard</KBD>
	259	</PRE>
	260
	261	<P>If only one banner file is specified, it will be printed
	262	before the files in the job. If a second banner file is
	263	specified, it is printed after the files in the job.</P>
	264
	265	<P>The available banner pages depend on the local system
	266	configuration; CUPS includes the following standard banner
	267	files:</P>
	268
	269	<UL>
	270
	271	<LI><CODE>none</CODE> - Do not produce a banner
	272	page.</LI>
	273
	274	<LI><CODE>classified</CODE> - A banner page with a
	275	"classified" label at the top and bottom.</LI>
	276
	277	<LI><CODE>confidential</CODE> - A banner page with a
	278	"confidential" label at the top and bottom.</LI>
	279
	280	<LI><CODE>secret</CODE> - A banner page with a
	281	"secret" label at the top and bottom.</LI>
	282
	283	<LI><CODE>standard</CODE> - A banner page with no label
	284	at the top and bottom.</LI>
	285
	286	<LI><CODE>topsecret</CODE> - A banner page with a
	287	"top secret" label at the top and bottom.</LI>
	288
	289	<LI><CODE>unclassified</CODE> - A banner page with an
	290	"unclassified" label at the top and bottom.</LI>
	291
	292	</UL>
	293
	294	<P>This directive must appear inside a <A
	295	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	296	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	297	section.</P>
ef416fc2	298
ef416fc2	299
480ef0fe	300	<H2 CLASS="title"><A NAME="KLimit">KLimit</A></H2>
ef416fc2	301
480ef0fe	302	<H3>Examples</H3>
ef416fc2	303
ef416fc2	304	<PRE CLASS="command">
480ef0fe	305	<Printer name>
	306	...
	307	KLimit 1234
	308	</Printer>
ef416fc2	309	</PRE>
ef416fc2	310
480ef0fe	311	<H3>Description</H3>
ef416fc2	312
	313	<P>The <CODE>KLimit</CODE> directive defines the value of the
	314	<VAR>job-k-limit</VAR> attribute. It is normally set using the
	315	<CODE>lpadmin(8)</CODE> command:</P>
	316
	317	<PRE CLASS="command">
	318	<KBD>/usr/sbin/lpadmin -p printername -o job-k-limit=1234</KBD>
	319	</PRE>
	320
	321	<P>This directive must appear inside a <A
	322	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	323	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	324	section.</P>
ef416fc2	325
ef416fc2	326
480ef0fe	327	<H2 CLASS="title"><A NAME="Location">Location</A></H2>
ef416fc2	328
480ef0fe	329	<H3>Examples</H3>
ef416fc2	330
ef416fc2	331	<PRE CLASS="command">
480ef0fe	332	<Printer name>
	333	...
	334	Location Building 3321
	335	</Printer>
ef416fc2	336	</PRE>
ef416fc2	337
480ef0fe	338	<H3>Description</H3>
ef416fc2	339
	340	<P>The <CODE>Location</CODE> directive defines the string for the
	341	<VAR>printer-location</VAR> attribute. It is normally set using the
	342	<CODE>lpadmin(8)</CODE> command:</P>
	343
	344	<PRE CLASS="command">
	345	<KBD>/usr/sbin/lpadmin -p printername -L "Building 3321"</KBD>
	346	</PRE>
	347
	348	<P>This directive must appear inside a <A
	349	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	350	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	351	section.</P>
ef416fc2	352
ef416fc2	353
480ef0fe	354	<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="OpPolicy">OpPolicy</A></H2>
ef416fc2	355
480ef0fe	356	<H3>Examples</H3>
ef416fc2	357
ef416fc2	358	<PRE CLASS="command">
480ef0fe	359	<Printer name>
	360	...
	361	OpPolicy default
	362	</Printer>
ef416fc2	363	</PRE>
ef416fc2	364
480ef0fe	365	<H3>Description</H3>
ef416fc2	366
	367	<P>The <CODE>OpPolicy</CODE> directive sets the operation policy
	368	that is used for the printer. The <CODE>lpadmin(8)</CODE> command
	369	sets the current operation policy:</P>
	370
	371	<PRE CLASS="command">
	372	<KBD>/usr/sbin/lpadmin -p printername -o printer-op-policy=default</KBD>
	373	</PRE>
	374
	375	<P>The default policy is named "default". All policies correspond
	376	to those defined using the <VAR>cupsd.conf</VAR> <A
4744bd90	377	HREF="ref-cupsd-conf.html#Policy"><CODE>Policy</CODE></A>
480ef0fe	378	section.</P>
ef416fc2	379
	380	<P>This directive must appear inside a <A
	381	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	382	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	383	section.</P>
ef416fc2	384
ef416fc2	385
480ef0fe	386	<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="Option">Option</A></H2>
ef416fc2	387
480ef0fe	388	<H3>Examples</H3>
ef416fc2	389
ef416fc2	390	<PRE CLASS="command">
480ef0fe	391	<Printer name>
	392	...
	393	Option name value
	394	Option scaling 100
	395	Option page-left 72
	396	</Printer>
ef416fc2	397	</PRE>
ef416fc2	398
480ef0fe	399	<H3>Description</H3>
	400
	401	<P>The <CODE>Option</CODE> directive specifies a default job
	402	template attribute value. It is mapped to
	403	<CODE>name-default</CODE> in the printer attributes and applied
	404	to jobs as <CODE>name</CODE>.</P>
	405
	406	<P>This directive must appear inside a <A
	407	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	408	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
	409	section.</P>
	410
	411
	412	<H2 CLASS="title"><A NAME="PageLimit">PageLimit</A></H2>
	413
	414	<H3>Examples</H3>
	415
	416	<PRE CLASS="command">
	417	<Printer name>
	418	...
	419	PageLimit 1234
	420	</Printer>
	421	</PRE>
	422
	423	<H3>Description</H3>
ef416fc2	424
	425	<P>The <CODE>PageLimit</CODE> directive defines the value of the
	426	<VAR>job-page-limit</VAR> attribute. It can be set using the
	427	<CODE>lpadmin(8)</CODE> command:</P>
	428
	429	<PRE CLASS="command">
	430	<KBD>/usr/sbin/lpadmin -p printername -o job-page-limit=1234</KBD>
	431	</PRE>
	432
	433	<P>This directive must appear inside a <A
	434	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	435	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	436	section.</P>
ef416fc2	437
ef416fc2	438
480ef0fe	439	<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="PortMonitor">PortMonitor</A></H2>
ef416fc2	440
480ef0fe	441	<H3>Examples</H3>
ef416fc2	442
ef416fc2	443	<PRE CLASS="command">
480ef0fe	444	<Printer name>
	445	...
	446	PortMonitor bcp
	447	</Printer>
ef416fc2	448	</PRE>
ef416fc2	449
480ef0fe	450	<H3>Description</H3>
ef416fc2	451
	452	<P>The <CODE>PortMonitor</CODE> directive sets the filter program that
	453	is used for every print job, typically to encode or package the print
	454	data in a format acceptable for a particular printer interface. It is
	455	set using the <CODE>lpadmin(8)</CODE> command:</P>
	456
	457	<PRE CLASS="command">
	458	<KBD>/usr/sbin/lpadmin -p printername -o port-monitor=tbcp</KBD>
	459	</PRE>
	460
	461	<P>The following standard port monitors are included with CUPS:</P>
	462
	463	<UL>
	464
	465	<LI><CODE>bcp</CODE> - Encode PostScript print data using
	466	the Adobe Binary Control Protocol (BCP)</LI>
	467
	468	<LI><CODE>none</CODE> - Do not use a port monitor</LI>
	469
	470	<LI><CODE>tbcp</CODE> - Encode PostScript print data
	471	using the Adobe Tagged Binary Control Protocol
	472	(TBCP)</LI>
	473
	474	</UL>
	475
	476	<P>This directive must appear inside a <A
	477	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	478	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	479	section.</P>
ef416fc2	480
ef416fc2	481
480ef0fe	482	<H2 CLASS="title"><A NAME="Printer">Printer</A></H2>
ef416fc2	483
480ef0fe	484	<H3>Examples</H3>
ef416fc2	485
	486	<PRE CLASS="command">
	487	<Printer name>
480ef0fe	488	...
ef416fc2	489	</Printer>
	490	</PRE>
	491
480ef0fe	492	<H3>Description</H3>
ef416fc2	493
	494	<P>The <CODE>Printer</CODE> directive begins a printer
	495	definition. Printers are added using the <CODE>lpadmin(8)</CODE>
	496	command:
	497
	498	<PRE CLASS="command">
	499	<KBD>/usr/sbin/lpadmin -p printername ...</KBD>
	500	</PRE>
	501
	502
480ef0fe	503	<H2 CLASS="title"><A NAME="QuotaPeriod">QuotaPeriod</A></H2>
ef416fc2	504
480ef0fe	505	<H3>Examples</H3>
ef416fc2	506
ef416fc2	507	<PRE CLASS="command">
480ef0fe	508	<Printer name>
	509	...
	510	QuotaPeriod 604800
	511	</Printer>
ef416fc2	512	</PRE>
ef416fc2	513
480ef0fe	514	<H3>Description</H3>
ef416fc2	515
	516	<P>The <CODE>QuotaPeriod</CODE> directive defines the value of
	517	the <VAR>job-quota-period</VAR> attribute. Typical values are
	518	86400 (1 day), 604800 (1 week), 2592000 (1 month), and 31536000
	519	(1 year). It is set using the <CODE>lpadmin(8)</CODE>
	520	command:</P>
	521
	522	<PRE CLASS="command">
	523	<KBD>/usr/sbin/lpadmin -p printername -o job-quota-period=604800</KBD>
	524	</PRE>
	525
	526	<P>This directive must appear inside a <A
	527	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	528	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	529	section.</P>
ef416fc2	530
ef416fc2	531
480ef0fe	532	<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="Shared">Shared</A></H2>
ef416fc2	533
480ef0fe	534	<H3>Examples</H3>
ef416fc2	535
ef416fc2	536	<PRE CLASS="command">
480ef0fe	537	<Printer name>
	538	...
	539	Shared yes
	540	</Printer>
ef416fc2	541	</PRE>
ef416fc2	542
480ef0fe	543	<H3>Description</H3>
ef416fc2	544
	545	<P>The <CODE>Shared</CODE> directive defines the initial value of
	546	the <VAR>printer-is-shared</VAR> attribute. The strings
	547	<VAR>yes</VAR> and <VAR>no</VAR> correspond to the true and false
	548	values, respectively. The <CODE>lpadmin(8)</CODE> command sets
	549	the current state:</P>
	550
	551	<PRE CLASS="command">
	552	<KBD>/usr/sbin/lpadmin -p printername -o printer-is-shared=true</KBD>
	553	</PRE>
	554
	555	<P>This directive must appear inside a <A
	556	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	557	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	558	section.</P>
ef416fc2	559
ef416fc2	560
480ef0fe	561	<H2 CLASS="title"><A NAME="State">State</A></H2>
ef416fc2	562
480ef0fe	563	<H3>Examples</H3>
ef416fc2	564
ef416fc2	565	<PRE CLASS="command">
480ef0fe	566	<Printer name>
	567	...
	568	State idle
	569	</Printer>
ef416fc2	570	</PRE>
ef416fc2	571
480ef0fe	572	<H3>Description</H3>
ef416fc2	573
	574	<P>The <CODE>State</CODE> directive defines the initial value of
	575	the <VAR>printer-state</VAR> attribute. The strings
	576	<VAR>idle</VAR> and <VAR>stopped</VAR> correspond to the IPP
	577	enumeration values 3 and 5, respectively. The
	578	<CODE>cupsenable(8)</CODE> and <CODE>cupsdisable(8)</CODE>
	579	commands set the current state:</P>
	580
	581	<PRE CLASS="command">
	582	<KBD>/usr/sbin/cupsenable printername</KBD>
	583	<KBD>/usr/sbin/cupsdisable printername</KBD>
	584	</PRE>
	585
	586	<P>This directive must appear inside a <A
	587	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	588	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	589	section.</P>
ef416fc2	590
ef416fc2	591
480ef0fe	592	<H2 CLASS="title"><A NAME="StateMessage">StateMessage</A></H2>
ef416fc2	593
480ef0fe	594	<H3>Examples</H3>
ef416fc2	595
ef416fc2	596	<PRE CLASS="command">
480ef0fe	597	<Printer name>
	598	...
	599	StateMessage Ready to print.
	600	</Printer>
ef416fc2	601	</PRE>
ef416fc2	602
480ef0fe	603	<H3>Description</H3>
ef416fc2	604
	605	<P>The <CODE>StateMessage</CODE> directive defines the initial
	606	string for the <VAR>printer-state-message</VAR> attribute. The
	607	following are some example messages:</P>
	608
	609	<PRE CLASS="command">
	610	StateMessage Connected to host_name...
	611	StateMessage Connecting to printer_queue on port port_number...
	612	StateMessage Network host host_name is busy; will retry in 30 seconds...
	613	StateMessage Printer busy; will retry in 10 seconds...
	614	StateMessage Printer is busy; retrying print job...
	615	StateMessage Print file accepted - job ID id_number.
	616	StateMessage Ready to print.
	617	StateMessage Waiting for job to complete
	618	</PRE>
	619
	620	<P>This directive must appear inside a <A
	621	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	622	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	623	section.</P>
ef416fc2	624
ef416fc2	625
480ef0fe	626	<H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="StateTime">StateTime</A></H2>
ef416fc2	627
480ef0fe	628	<H3>Examples</H3>
ef416fc2	629
ef416fc2	630	<PRE CLASS="command">
480ef0fe	631	<Printer name>
	632	...
	633	StateTime 1133542425
	634	</Printer>
ef416fc2	635	</PRE>
ef416fc2	636
480ef0fe	637	<H3>Description</H3>
ef416fc2	638
	639	<P>The <CODE>StateTime</CODE> directive defines the UNIX time
	640	(seconds since Jan 1, 1970) for the last state change of the
	641	queue. It is mapped to the <VAR>printer-state-change-time</VAR>
	642	attribute.</P>
	643
	644	<P>This directive must appear inside a <A
	645	HREF="#Printer"><CODE>Printer</CODE></A> or <A
	646	HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
480ef0fe	647	section.</P>
ef416fc2	648
	649
	650	</BODY>
	651	</HTML>