2 <!-- SECTION: References -->
4 <TITLE>printers.conf
</TITLE>
5 <LINK REL=
"STYLESHEET" TYPE=
"text/css" HREF=
"../cups-printable.css">
9 <H1 CLASS=
"title">printers.conf
</H1>
11 <P>The CUPS scheduler (cupsd) uses the
12 <VAR>/etc/cups/printers.conf
</VAR> file to store the list of
13 available printers. This file contains only locally defined
14 printers, not remote printers that are created automatically via
15 browsing. Each directive is listed on a line by itself followed
16 by its value. Comments are introduced using the number sign (
"#")
17 character at the beginning of a line.
</P>
19 <P>While the printer configuration file consists of plain text
20 and can be modified using your favorite text editor, you should
21 normally use the
<A HREF=
"man-lpadmin.html">lpadmin(
8)
</A>
22 command, web interface, or any of the available GUIs to manage
23 your printers instead. If you do choose to edit this file
24 manually, you will need to stop the scheduler first, make your
25 changes, and then start the scheduler to make them active.
</P>
28 <H2 CLASS=
"title"><A NAME=
"Accepting">Accepting
</A></H2>
41 <P>The
<CODE>Accepting
</CODE> directive defines the initial state
42 of the
<VAR>printer-is-accepting-jobs
</VAR> attribute. This state
43 is also set by the
<CODE>cupsaccept(
8)
</CODE> and
44 <CODE>cupsreject(
8)
</CODE> commands:
</P>
47 <KBD>/usr/sbin/cupsaccept printername
48 /usr/sbin/cupsreject printername
</KBD>
51 <P>This directive must appear inside a
<A
52 HREF=
"#Printer"><CODE>Printer
</CODE></A> or
<A
53 HREF=
"#DefaultPrinter"><CODE>DefaultPrinter
</CODE></A>
57 <H2 CLASS=
"title"><A NAME=
"AllowUser">AllowUser
</A></H2>
71 <P>The
<CODE>AllowUser
</CODE> directive adds a username or group
72 name to the
<VAR>requesting-user-name-allowed
</VAR> attribute
73 which can be set by the
<CODE>lpadmin(
8)
</CODE> command:
</P>
76 <KBD>/usr/sbin/lpadmin -p printername -u allow:foo_user,@bar_group
</KBD>
79 <P>This directive must appear inside a
<A
80 HREF=
"#Printer"><CODE>Printer
</CODE></A> or
<A
81 HREF=
"#DefaultPrinter"><CODE>DefaultPrinter
</CODE></A> directive.
82 This directive cannot be used with
<A
83 HREF=
"#DenyUser"><CODE>DenyUser
</CODE></A>.
</P>
86 <H2 CLASS=
"title"><A NAME=
"DefaultPrinter">DefaultPrinter
</A></H2>
91 <DefaultPrinter name
>
98 <P>The
<CODE>DefaultPrinter
</CODE> directive begins a printer
99 definition as the default server destination. The default server
100 destination can be set using the
<CODE>lpadmin(
8)
</CODE>
103 <PRE CLASS=
"command">
104 <KBD>/usr/sbin/lpadmin -d printername
</KBD>
107 <P>Note that the server default destination settings can be
108 overridden by the user's default destination settings which are
109 normally set using the
<CODE>lpoptions(
1)
</CODE> command.
</P>
112 <H2 CLASS=
"title"><A NAME=
"DenyUser">DenyUser
</A></H2>
116 <PRE CLASS=
"command">
126 <P>The
<CODE>DenyUser
</CODE> directive adds a username or group
127 name to the
<VAR>requesting-user-name-denied
</VAR> attribute
128 which can be set by the
<CODE>lpadmin(
8)
</CODE> command:
</P>
130 <PRE CLASS=
"command">
131 <KBD>/usr/sbin/lpadmin -p printername -u deny:foo_user,@bar_group
</KBD>
134 <P>This directive must appear inside a
<A
135 HREF=
"#Printer"><CODE>Printer
</CODE></A> or
<A
136 HREF=
"#DefaultPrinter"><CODE>DefaultPrinter
</CODE></A> directive.
137 This directive cannot be used with
<A
138 HREF=
"#AllowUser"><CODE>AllowUser
</CODE></A></P>
141 <H2 CLASS=
"title"><A NAME=
"DeviceURI">DeviceURI
</A></H2>
145 <PRE CLASS=
"command">
148 DeviceURI socket://foo.bar.com:
9100
154 <P>The
<CODE>DeviceURI
</CODE> directive defines the value of the
155 <VAR>device-uri-attribute
</VAR> attribute. It is normally set
156 using the
<CODE>lpadmin(
8)
</CODE> command:
</P>
158 <PRE CLASS=
"command">
159 <KBD>/usr/sbin/lpadmin -p printername -v device-uri
</KBD>
162 <P>This directive must appear inside a
<A
163 HREF=
"#Printer"><CODE>Printer
</CODE></A> or
<A
164 HREF=
"#DefaultPrinter"><CODE>DefaultPrinter
</CODE></A>
168 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
1.2</SPAN><A NAME=
"ErrorPolicy">ErrorPolicy
</A></H2>
172 <PRE CLASS=
"command">
175 ErrorPolicy abort-job
181 <P>The
<CODE>ErrorPolicy
</CODE> directive defines the policy that
182 is used when a backend is unable to send a print job to the
183 printer. The
<CODE>lpadmin(
8)
</CODE> command sets the current
186 <PRE CLASS=
"command">
187 <KBD>/usr/sbin/lpadmin -p printername -o printer-error-policy=stop-printer
</KBD>
190 <P>The following values are supported:
</P>
194 <LI><CODE>abort-job
</CODE> - Abort the job and proceed
195 with the next job in the queue
</LI>
197 <LI><CODE>retry-current-job
</CODE> - Retry the current job
200 <LI><CODE>retry-job
</CODE> - Retry the job after waiting
201 for N seconds; the
<VAR>cupsd.conf
</VAR> <A
202 HREF=
"ref-cupsd-conf.html#JobRetryInterval"><CODE>JobRetryInterval
</CODE></A>
203 directive controls the value of N
</LI>
205 <LI><CODE>stop-printer
</CODE> - Stop the printer and keep
206 the job for future printing; this is the default
211 <P>This directive must appear inside a
<A
212 HREF=
"#Printer"><CODE>Printer
</CODE></A> or
<A
213 HREF=
"#DefaultPrinter"><CODE>DefaultPrinter
</CODE></A>
217 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
1.4</SPAN><A NAME=
"Filter">Filter
</A></H2>
221 <PRE CLASS=
"command">
224 Filter mime/type
100 program
230 <P>The
<CODE>Filter
</CODE> directive lists a single filter program as defined
231 in the printer's PPD file.
</P>
233 <P>This directive must appear inside a
234 <A HREF=
"#Printer"><CODE>Printer
</CODE></A> or
235 <A HREF=
"#DefaultPrinter"><CODE>DefaultPrinter
</CODE></A> section.
</P>
238 <H2 CLASS=
"title"><A NAME=
"Info">Info
</A></H2>
242 <PRE CLASS=
"command">
251 <P>The
<CODE>Info
</CODE> directive defines the string for the
252 <VAR>printer-info
</VAR> attribute. It is normally set using the
253 <CODE>lpadmin(
8)
</CODE> command:
</P>
255 <PRE CLASS=
"command">
256 <KBD>/usr/sbin/lpadmin -p printername -D
"My Printer"</KBD>
259 <P>This directive must appear inside a
<A
260 HREF=
"#Printer"><CODE>Printer
</CODE></A> or
<A
261 HREF=
"#DefaultPrinter"><CODE>DefaultPrinter
</CODE></A>
265 <H2 CLASS=
"title"><A NAME=
"JobSheets">JobSheets
</A></H2>
269 <PRE CLASS=
"command">
272 JobSheets none,standard
278 <P>The
<CODE>JobSheets
</CODE> directive specifies the default
279 banner pages to print before and after a print job. In the above
280 example, only a
<VAR>standard
</VAR> banner will print after each
281 job. The
<CODE>lpadmin(
8)
</CODE> command is normally used to set
284 <PRE CLASS=
"command">
285 <KBD>/usr/sbin/lpadmin -p printername -o job-sheets-default=none,standard
</KBD>
288 <P>If only one banner file is specified, it will be printed
289 before the files in the job. If a second banner file is
290 specified, it is printed after the files in the job.
</P>
292 <P>The available banner pages depend on the local system
293 configuration; CUPS includes the following standard banner
298 <LI><CODE>none
</CODE> - Do not produce a banner
301 <LI><CODE>classified
</CODE> - A banner page with a
302 "classified
" label at the top and bottom.
</LI>
304 <LI><CODE>confidential
</CODE> - A banner page with a
305 "confidential
" label at the top and bottom.
</LI>
307 <LI><CODE>secret
</CODE> - A banner page with a
308 "secret
" label at the top and bottom.
</LI>
310 <LI><CODE>standard
</CODE> - A banner page with no label
311 at the top and bottom.
</LI>
313 <LI><CODE>topsecret
</CODE> - A banner page with a
314 "top secret
" label at the top and bottom.
</LI>
316 <LI><CODE>unclassified
</CODE> - A banner page with an
317 "unclassified
" label at the top and bottom.
</LI>
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>
327 <H2 CLASS=
"title"><A NAME=
"KLimit">KLimit
</A></H2>
331 <PRE CLASS=
"command">
340 <P>The
<CODE>KLimit
</CODE> directive defines the value of the
341 <VAR>job-k-limit
</VAR> attribute. It is normally set using the
342 <CODE>lpadmin(
8)
</CODE> command:
</P>
344 <PRE CLASS=
"command">
345 <KBD>/usr/sbin/lpadmin -p printername -o job-k-limit=
1234</KBD>
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>
354 <H2 CLASS=
"title"><A NAME=
"Location">Location
</A></H2>
358 <PRE CLASS=
"command">
361 Location Building
3321
367 <P>The
<CODE>Location
</CODE> directive defines the string for the
368 <VAR>printer-location
</VAR> attribute. It is normally set using the
369 <CODE>lpadmin(
8)
</CODE> command:
</P>
371 <PRE CLASS=
"command">
372 <KBD>/usr/sbin/lpadmin -p printername -L
"Building 3321"</KBD>
375 <P>This directive must appear inside a
<A
376 HREF=
"#Printer"><CODE>Printer
</CODE></A> or
<A
377 HREF=
"#DefaultPrinter"><CODE>DefaultPrinter
</CODE></A>
381 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
1.2</SPAN><A NAME=
"OpPolicy">OpPolicy
</A></H2>
385 <PRE CLASS=
"command">
394 <P>The
<CODE>OpPolicy
</CODE> directive sets the operation policy
395 that is used for the printer. The
<CODE>lpadmin(
8)
</CODE> command
396 sets the current operation policy:
</P>
398 <PRE CLASS=
"command">
399 <KBD>/usr/sbin/lpadmin -p printername -o printer-op-policy=default
</KBD>
402 <P>The default policy is named
"default". All policies correspond
403 to those defined using the
<VAR>cupsd.conf
</VAR> <A
404 HREF=
"ref-cupsd-conf.html#Policy"><CODE>Policy
</CODE></A>
407 <P>This directive must appear inside a
<A
408 HREF=
"#Printer"><CODE>Printer
</CODE></A> or
<A
409 HREF=
"#DefaultPrinter"><CODE>DefaultPrinter
</CODE></A>
413 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
1.2</SPAN><A NAME=
"Option">Option
</A></H2>
417 <PRE CLASS=
"command">
428 <P>The
<CODE>Option
</CODE> directive specifies a default job
429 template attribute value. It is mapped to
430 <CODE>name-default
</CODE> in the printer attributes and applied
431 to jobs as
<CODE>name
</CODE>.
</P>
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>
439 <H2 CLASS=
"title"><A NAME=
"PageLimit">PageLimit
</A></H2>
443 <PRE CLASS=
"command">
452 <P>The
<CODE>PageLimit
</CODE> directive defines the value of the
453 <VAR>job-page-limit
</VAR> attribute. It can be set using the
454 <CODE>lpadmin(
8)
</CODE> command:
</P>
456 <PRE CLASS=
"command">
457 <KBD>/usr/sbin/lpadmin -p printername -o job-page-limit=
1234</KBD>
460 <P>This directive must appear inside a
<A
461 HREF=
"#Printer"><CODE>Printer
</CODE></A> or
<A
462 HREF=
"#DefaultPrinter"><CODE>DefaultPrinter
</CODE></A>
466 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
1.2</SPAN><A NAME=
"PortMonitor">PortMonitor
</A></H2>
470 <PRE CLASS=
"command">
479 <P>The
<CODE>PortMonitor
</CODE> directive sets the filter program that
480 is used for every print job, typically to encode or package the print
481 data in a format acceptable for a particular printer interface. It is
482 set using the
<CODE>lpadmin(
8)
</CODE> command:
</P>
484 <PRE CLASS=
"command">
485 <KBD>/usr/sbin/lpadmin -p printername -o port-monitor=tbcp
</KBD>
488 <P>The following standard port monitors are included with CUPS:
</P>
492 <LI><CODE>bcp
</CODE> - Encode PostScript print data using
493 the Adobe Binary Control Protocol (BCP)
</LI>
495 <LI><CODE>none
</CODE> - Do not use a port monitor
</LI>
497 <LI><CODE>tbcp
</CODE> - Encode PostScript print data
498 using the Adobe Tagged Binary Control Protocol
503 <P>This directive must appear inside a
<A
504 HREF=
"#Printer"><CODE>Printer
</CODE></A> or
<A
505 HREF=
"#DefaultPrinter"><CODE>DefaultPrinter
</CODE></A>
509 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
1.4</SPAN><A NAME=
"PreFilter">PreFilter
</A></H2>
513 <PRE CLASS=
"command">
516 PreFilter mime/type
100 program
522 <P>The
<CODE>PreFilter
</CODE> directive lists a single pre-filter program as
523 defined in the printer's PPD file.
</P>
525 <P>This directive must appear inside a
526 <A HREF=
"#Printer"><CODE>Printer
</CODE></A> or
527 <A HREF=
"#DefaultPrinter"><CODE>DefaultPrinter
</CODE></A> section.
</P>
530 <H2 CLASS=
"title"><A NAME=
"Printer">Printer
</A></H2>
534 <PRE CLASS=
"command">
542 <P>The
<CODE>Printer
</CODE> directive begins a printer
543 definition. Printers are added using the
<CODE>lpadmin(
8)
</CODE>
546 <PRE CLASS=
"command">
547 <KBD>/usr/sbin/lpadmin -p printername ...
</KBD>
551 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
1.4</SPAN><A NAME=
"Product">Product
</A></H2>
555 <PRE CLASS=
"command">
558 Product Acme PaperWriter
564 <P>The
<CODE>Product
</CODE> directive defines the main product string from the
565 printer's PPD file and is used when advertising the queue via DNS-SD.
</P>
567 <P>This directive must appear inside a
568 <A HREF=
"#Printer"><CODE>Printer
</CODE></A> or
569 <A HREF=
"#DefaultPrinter"><CODE>DefaultPrinter
</CODE></A> section.
</P>
572 <H2 CLASS=
"title"><A NAME=
"QuotaPeriod">QuotaPeriod
</A></H2>
576 <PRE CLASS=
"command">
585 <P>The
<CODE>QuotaPeriod
</CODE> directive defines the value of
586 the
<VAR>job-quota-period
</VAR> attribute. Typical values are
587 86400 (
1 day),
604800 (
1 week),
2592000 (
1 month), and
31536000
588 (
1 year). It is set using the
<CODE>lpadmin(
8)
</CODE>
591 <PRE CLASS=
"command">
592 <KBD>/usr/sbin/lpadmin -p printername -o job-quota-period=
604800</KBD>
595 <P>This directive must appear inside a
<A
596 HREF=
"#Printer"><CODE>Printer
</CODE></A> or
<A
597 HREF=
"#DefaultPrinter"><CODE>DefaultPrinter
</CODE></A>
601 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
1.2</SPAN><A NAME=
"Shared">Shared
</A></H2>
605 <PRE CLASS=
"command">
614 <P>The
<CODE>Shared
</CODE> directive defines the initial value of
615 the
<VAR>printer-is-shared
</VAR> attribute. The strings
616 <VAR>yes
</VAR> and
<VAR>no
</VAR> correspond to the true and false
617 values, respectively. The
<CODE>lpadmin(
8)
</CODE> command sets
618 the current state:
</P>
620 <PRE CLASS=
"command">
621 <KBD>/usr/sbin/lpadmin -p printername -o printer-is-shared=true
</KBD>
624 <P>This directive must appear inside a
<A
625 HREF=
"#Printer"><CODE>Printer
</CODE></A> or
<A
626 HREF=
"#DefaultPrinter"><CODE>DefaultPrinter
</CODE></A>
630 <H2 CLASS=
"title"><A NAME=
"State">State
</A></H2>
634 <PRE CLASS=
"command">
643 <P>The
<CODE>State
</CODE> directive defines the initial value of
644 the
<VAR>printer-state
</VAR> attribute. The strings
645 <VAR>idle
</VAR> and
<VAR>stopped
</VAR> correspond to the IPP
646 enumeration values
3 and
5, respectively. The
647 <CODE>cupsenable(
8)
</CODE> and
<CODE>cupsdisable(
8)
</CODE>
648 commands set the current state:
</P>
650 <PRE CLASS=
"command">
651 <KBD>/usr/sbin/cupsenable printername
</KBD>
652 <KBD>/usr/sbin/cupsdisable printername
</KBD>
655 <P>This directive must appear inside a
<A
656 HREF=
"#Printer"><CODE>Printer
</CODE></A> or
<A
657 HREF=
"#DefaultPrinter"><CODE>DefaultPrinter
</CODE></A>
661 <H2 CLASS=
"title"><A NAME=
"StateMessage">StateMessage
</A></H2>
665 <PRE CLASS=
"command">
668 StateMessage Printer is lonely.
674 <P>The
<CODE>StateMessage
</CODE> directive defines the initial
675 string for the
<VAR>printer-state-message
</VAR> attribute. The
676 following are some example messages:
</P>
678 <PRE CLASS=
"command">
679 StateMessage Connected to host_name...
680 StateMessage Connecting to printer_queue on port port_number...
681 StateMessage Network host host_name is busy; will retry in
30 seconds...
682 StateMessage Printer busy; will retry in
10 seconds...
683 StateMessage Printer is busy; retrying print job...
684 StateMessage Print file accepted - job ID id_number.
685 StateMessage Waiting for job to complete
688 <P>This directive must appear inside a
<A
689 HREF=
"#Printer"><CODE>Printer
</CODE></A> or
<A
690 HREF=
"#DefaultPrinter"><CODE>DefaultPrinter
</CODE></A>
694 <H2 CLASS=
"title"><SPAN CLASS=
"info">CUPS
1.2</SPAN><A NAME=
"StateTime">StateTime
</A></H2>
698 <PRE CLASS=
"command">
707 <P>The
<CODE>StateTime
</CODE> directive defines the UNIX time
708 (seconds since Jan
1,
1970) for the last state change of the
709 queue. It is mapped to the
<VAR>printer-state-change-time
</VAR>
712 <P>This directive must appear inside a
<A
713 HREF=
"#Printer"><CODE>Printer
</CODE></A> or
<A
714 HREF=
"#DefaultPrinter"><CODE>DefaultPrinter
</CODE></A>