2 <!-- SECTION: References -->
4 <TITLE>printers.conf
</TITLE>
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>
16 <P>While the printer configuration file consists of plain text
17 and can be modified using your favorite text editor, you should
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
25 <H2 CLASS=
"title"><A NAME=
"Accepting">Accepting
</A></H2>
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>
44 <KBD>/usr/sbin/accept printername
45 /usr/sbin/reject printername
</KBD>
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>
54 <H2 CLASS=
"title"><A NAME=
"AllowUser">AllowUser
</A></H2>
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>
73 <KBD>/usr/sbin/lpadmin -p printername -u allow:foo_user,@bar_group
</KBD>
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>
83 <H2 CLASS=
"title"><A NAME=
"DefaultPrinter">DefaultPrinter
</A></H2>
88 <DefaultPrinter name
>
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>
100 <PRE CLASS=
"command">
101 <KBD>/usr/sbin/lpadmin -d printername
</KBD>
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>
109 <H2 CLASS=
"title"><A NAME=
"DenyUser">DenyUser
</A></H2>
113 <PRE CLASS=
"command">
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>
127 <PRE CLASS=
"command">
128 <KBD>/usr/sbin/lpadmin -p printername -u deny:foo_user,@bar_group
</KBD>
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>
138 <H2 CLASS=
"title"><A NAME=
"DeviceURI">DeviceURI
</A></H2>
142 <PRE CLASS=
"command">
145 DeviceURI socket://foo.bar.com:
9100
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>
155 <PRE CLASS=
"command">
156 <KBD>/usr/sbin/lpadmin -p printername -v device-uri
</KBD>
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>
165 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
1.2</SPAN><A NAME=
"ErrorPolicy">ErrorPolicy
</A></H2>
169 <PRE CLASS=
"command">
172 ErrorPolicy abort-job
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
183 <PRE CLASS=
"command">
184 <KBD>/usr/sbin/lpadmin -p printername -o printer-error-policy=stop-printer
</KBD>
187 <P>The following values are supported:
</P>
191 <LI><CODE>abort-job
</CODE> - Abort the job and proceed
192 with the next job in the queue
</LI>
194 <LI><CODE>retry-current-job
</CODE> - Retry the current job
197 <LI><CODE>retry-job
</CODE> - Retry the job after waiting
198 for N seconds; the
<VAR>cupsd.conf
</VAR> <A
199 HREF=
"ref-cupsd-conf.html#JobRetryInterval"><CODE>JobRetryInterval
</CODE></A>
200 directive controls the value of N
</LI>
202 <LI><CODE>stop-printer
</CODE> - Stop the printer and keep
203 the job for future printing; this is the default
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>
214 <H2 CLASS=
"title"><A NAME=
"Info">Info
</A></H2>
218 <PRE CLASS=
"command">
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>
231 <PRE CLASS=
"command">
232 <KBD>/usr/sbin/lpadmin -p printername -D
"My Printer"</KBD>
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>
241 <H2 CLASS=
"title"><A NAME=
"JobSheets">JobSheets
</A></H2>
245 <PRE CLASS=
"command">
248 JobSheets none,standard
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
260 <PRE CLASS=
"command">
261 <KBD>/usr/sbin/lpadmin -p printername -o job-sheets-default=none,standard
</KBD>
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>
268 <P>The available banner pages depend on the local system
269 configuration; CUPS includes the following standard banner
274 <LI><CODE>none
</CODE> - Do not produce a banner
277 <LI><CODE>classified
</CODE> - A banner page with a
278 "classified
" label at the top and bottom.
</LI>
280 <LI><CODE>confidential
</CODE> - A banner page with a
281 "confidential
" label at the top and bottom.
</LI>
283 <LI><CODE>secret
</CODE> - A banner page with a
284 "secret
" label at the top and bottom.
</LI>
286 <LI><CODE>standard
</CODE> - A banner page with no label
287 at the top and bottom.
</LI>
289 <LI><CODE>topsecret
</CODE> - A banner page with a
290 "top secret
" label at the top and bottom.
</LI>
292 <LI><CODE>unclassified
</CODE> - A banner page with an
293 "unclassified
" label at the top and bottom.
</LI>
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>
303 <H2 CLASS=
"title"><A NAME=
"KLimit">KLimit
</A></H2>
307 <PRE CLASS=
"command">
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>
320 <PRE CLASS=
"command">
321 <KBD>/usr/sbin/lpadmin -p printername -o job-k-limit=
1234</KBD>
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>
330 <H2 CLASS=
"title"><A NAME=
"Location">Location
</A></H2>
334 <PRE CLASS=
"command">
337 Location Building
3321
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>
347 <PRE CLASS=
"command">
348 <KBD>/usr/sbin/lpadmin -p printername -L
"Building 3321"</KBD>
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>
357 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
1.2</SPAN><A NAME=
"OpPolicy">OpPolicy
</A></H2>
361 <PRE CLASS=
"command">
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>
374 <PRE CLASS=
"command">
375 <KBD>/usr/sbin/lpadmin -p printername -o printer-op-policy=default
</KBD>
378 <P>The default policy is named
"default". All policies correspond
379 to those defined using the
<VAR>cupsd.conf
</VAR> <A
380 HREF=
"ref-cupsd-conf.html#Policy"><CODE>Policy
</CODE></A>
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>
389 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
1.2</SPAN><A NAME=
"Option">Option
</A></H2>
393 <PRE CLASS=
"command">
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>
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>
415 <H2 CLASS=
"title"><A NAME=
"PageLimit">PageLimit
</A></H2>
419 <PRE CLASS=
"command">
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>
432 <PRE CLASS=
"command">
433 <KBD>/usr/sbin/lpadmin -p printername -o job-page-limit=
1234</KBD>
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>
442 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
1.2</SPAN><A NAME=
"PortMonitor">PortMonitor
</A></H2>
446 <PRE CLASS=
"command">
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>
460 <PRE CLASS=
"command">
461 <KBD>/usr/sbin/lpadmin -p printername -o port-monitor=tbcp
</KBD>
464 <P>The following standard port monitors are included with CUPS:
</P>
468 <LI><CODE>bcp
</CODE> - Encode PostScript print data using
469 the Adobe Binary Control Protocol (BCP)
</LI>
471 <LI><CODE>none
</CODE> - Do not use a port monitor
</LI>
473 <LI><CODE>tbcp
</CODE> - Encode PostScript print data
474 using the Adobe Tagged Binary Control Protocol
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>
485 <H2 CLASS=
"title"><A NAME=
"Printer">Printer
</A></H2>
489 <PRE CLASS=
"command">
497 <P>The
<CODE>Printer
</CODE> directive begins a printer
498 definition. Printers are added using the
<CODE>lpadmin(
8)
</CODE>
501 <PRE CLASS=
"command">
502 <KBD>/usr/sbin/lpadmin -p printername ...
</KBD>
506 <H2 CLASS=
"title"><A NAME=
"QuotaPeriod">QuotaPeriod
</A></H2>
510 <PRE CLASS=
"command">
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>
525 <PRE CLASS=
"command">
526 <KBD>/usr/sbin/lpadmin -p printername -o job-quota-period=
604800</KBD>
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>
535 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
1.2</SPAN><A NAME=
"Shared">Shared
</A></H2>
539 <PRE CLASS=
"command">
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>
554 <PRE CLASS=
"command">
555 <KBD>/usr/sbin/lpadmin -p printername -o printer-is-shared=true
</KBD>
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>
564 <H2 CLASS=
"title"><A NAME=
"State">State
</A></H2>
568 <PRE CLASS=
"command">
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>
584 <PRE CLASS=
"command">
585 <KBD>/usr/sbin/cupsenable printername
</KBD>
586 <KBD>/usr/sbin/cupsdisable printername
</KBD>
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>
595 <H2 CLASS=
"title"><A NAME=
"StateMessage">StateMessage
</A></H2>
599 <PRE CLASS=
"command">
602 StateMessage Ready to print.
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>
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
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>
629 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
1.2</SPAN><A NAME=
"StateTime">StateTime
</A></H2>
633 <PRE CLASS=
"command">
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>
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>