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