doc/help/ref-printers-conf.html

   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
  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>
  23
  24
  25 <H2 CLASS="title"><A NAME="Accepting">Accepting</A></H2>
  26
  27 <H3>Examples</H3>
  28
  29 <PRE CLASS="command">
  30 &lt;Printer name&gt;
  31   ...
  32   Accepting yes
  33 &lt;/Printer&gt;
  34 </PRE>
  35
  36 <H3>Description</H3>
  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>
  51 section.</P>
  52
  53
  54 <H2 CLASS="title"><A NAME="AllowUser">AllowUser</A></H2>
  55
  56 <H3>Examples</H3>
  57
  58 <PRE CLASS="command">
  59 &lt;Printer name&gt;
  60   ...
  61   AllowUser foo_user
  62   AllowUser @bar_group
  63 &lt;/Printer&gt;
  64 </PRE>
  65
  66 <H3>Description</H3>
  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
  83 <H2 CLASS="title"><A NAME="DefaultPrinter">DefaultPrinter</A></H2>
  84
  85 <H3>Examples</H3>
  86
  87 <PRE CLASS="command">
  88 &lt;DefaultPrinter name&gt;
  89   ...
  90 &lt;/Printer&gt;
  91 </PRE>
  92
  93 <H3>Description</H3>
  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
 109 <H2 CLASS="title"><A NAME="DenyUser">DenyUser</A></H2>
 110
 111 <H3>Examples</H3>
 112
 113 <PRE CLASS="command">
 114 &lt;Printer name&gt;
 115   ...
 116   DenyUser foo_user
 117   DenyUser @bar_group
 118 &lt;/Printer&gt;
 119 </PRE>
 120
 121 <H3>Description</H3>
 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
 138 <H2 CLASS="title"><A NAME="DeviceURI">DeviceURI</A></H2>
 139
 140 <H3>Examples</H3>
 141
 142 <PRE CLASS="command">
 143 &lt;Printer name&gt;
 144   ...
 145   DeviceURI socket://foo.bar.com:9100
 146 &lt;/Printer&gt;
 147 </PRE>
 148
 149 <H3>Description</H3>
 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>
 162 section.</P>
 163
 164
 165 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="ErrorPolicy">ErrorPolicy</A></H2>
 166
 167 <H3>Examples</H3>
 168
 169 <PRE CLASS="command">
 170 &lt;Printer name&gt;
 171   ...
 172   ErrorPolicy abort-job
 173 &lt;/Printer&gt;
 174 </PRE>
 175
 176 <H3>Description</H3>
 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>abort-job</CODE> - Abort 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
 196         HREF="ref-cupsd-conf.html#JobRetryInterval"><CODE>JobRetryInterval</CODE></A>
 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>
 208 section.</P>
 209
 210
 211 <H2 CLASS="title"><A NAME="Info">Info</A></H2>
 212
 213 <H3>Examples</H3>
 214
 215 <PRE CLASS="command">
 216 &lt;Printer name&gt;
 217   ...
 218   Info My Printer
 219 &lt;/Printer&gt;
 220 </PRE>
 221
 222 <H3>Description</H3>
 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>
 235 section.</P>
 236
 237
 238 <H2 CLASS="title"><A NAME="JobSheets">JobSheets</A></H2>
 239
 240 <H3>Examples</H3>
 241
 242 <PRE CLASS="command">
 243 &lt;Printer name&gt;
 244   ...
 245   JobSheets none,standard
 246 &lt;/Printer&gt;
 247 </PRE>
 248
 249 <H3>Description</H3>
 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         &quot;classified&quot; label at the top and bottom.</LI>
 276
 277         <LI><CODE>confidential</CODE> - A banner page with a
 278         &quot;confidential&quot; label at the top and bottom.</LI>
 279
 280         <LI><CODE>secret</CODE> - A banner page with a
 281         &quot;secret&quot; 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         &quot;top secret&quot; label at the top and bottom.</LI>
 288
 289         <LI><CODE>unclassified</CODE> - A banner page with an
 290         &quot;unclassified&quot; 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>
 297 section.</P>
 298
 299
 300 <H2 CLASS="title"><A NAME="KLimit">KLimit</A></H2>
 301
 302 <H3>Examples</H3>
 303
 304 <PRE CLASS="command">
 305 &lt;Printer name&gt;
 306   ...
 307   KLimit 1234
 308 &lt;/Printer&gt;
 309 </PRE>
 310
 311 <H3>Description</H3>
 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>
 324 section.</P>
 325
 326
 327 <H2 CLASS="title"><A NAME="Location">Location</A></H2>
 328
 329 <H3>Examples</H3>
 330
 331 <PRE CLASS="command">
 332 &lt;Printer name&gt;
 333   ...
 334   Location Building 3321
 335 &lt;/Printer&gt;
 336 </PRE>
 337
 338 <H3>Description</H3>
 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>
 351 section.</P>
 352
 353
 354 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="OpPolicy">OpPolicy</A></H2>
 355
 356 <H3>Examples</H3>
 357
 358 <PRE CLASS="command">
 359 &lt;Printer name&gt;
 360   ...
 361   OpPolicy default
 362 &lt;/Printer&gt;
 363 </PRE>
 364
 365 <H3>Description</H3>
 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
 377 HREF="ref-cupsd-conf.html#Policy"><CODE>Policy</CODE></A>
 378 section.</P>
 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>
 383 section.</P>
 384
 385
 386 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="Option">Option</A></H2>
 387
 388 <H3>Examples</H3>
 389
 390 <PRE CLASS="command">
 391 &lt;Printer name&gt;
 392   ...
 393   Option name value
 394   Option scaling 100
 395   Option page-left 72
 396 &lt;/Printer&gt;
 397 </PRE>
 398
 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 &lt;Printer name&gt;
 418   ...
 419   PageLimit 1234
 420 &lt;/Printer&gt;
 421 </PRE>
 422
 423 <H3>Description</H3>
 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>
 436 section.</P>
 437
 438
 439 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="PortMonitor">PortMonitor</A></H2>
 440
 441 <H3>Examples</H3>
 442
 443 <PRE CLASS="command">
 444 &lt;Printer name&gt;
 445   ...
 446   PortMonitor bcp
 447 &lt;/Printer&gt;
 448 </PRE>
 449
 450 <H3>Description</H3>
 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>
 479 section.</P>
 480
 481
 482 <H2 CLASS="title"><A NAME="Printer">Printer</A></H2>
 483
 484 <H3>Examples</H3>
 485
 486 <PRE CLASS="command">
 487 &lt;Printer name&gt;
 488   ...
 489 &lt;/Printer&gt;
 490 </PRE>
 491
 492 <H3>Description</H3>
 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
 503 <H2 CLASS="title"><A NAME="QuotaPeriod">QuotaPeriod</A></H2>
 504
 505 <H3>Examples</H3>
 506
 507 <PRE CLASS="command">
 508 &lt;Printer name&gt;
 509   ...
 510   QuotaPeriod 604800
 511 &lt;/Printer&gt;
 512 </PRE>
 513
 514 <H3>Description</H3>
 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>
 529 section.</P>
 530
 531
 532 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="Shared">Shared</A></H2>
 533
 534 <H3>Examples</H3>
 535
 536 <PRE CLASS="command">
 537 &lt;Printer name&gt;
 538   ...
 539   Shared yes
 540 &lt;/Printer&gt;
 541 </PRE>
 542
 543 <H3>Description</H3>
 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>
 558 section.</P>
 559
 560
 561 <H2 CLASS="title"><A NAME="State">State</A></H2>
 562
 563 <H3>Examples</H3>
 564
 565 <PRE CLASS="command">
 566 &lt;Printer name&gt;
 567   ...
 568   State idle
 569 &lt;/Printer&gt;
 570 </PRE>
 571
 572 <H3>Description</H3>
 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>
 589 section.</P>
 590
 591
 592 <H2 CLASS="title"><A NAME="StateMessage">StateMessage</A></H2>
 593
 594 <H3>Examples</H3>
 595
 596 <PRE CLASS="command">
 597 &lt;Printer name&gt;
 598   ...
 599   StateMessage Ready to print.
 600 &lt;/Printer&gt;
 601 </PRE>
 602
 603 <H3>Description</H3>
 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>
 623 section.</P>
 624
 625
 626 <H2 CLASS="title"><SPAN CLASS="info">CUPS 1.2</SPAN><A NAME="StateTime">StateTime</A></H2>
 627
 628 <H3>Examples</H3>
 629
 630 <PRE CLASS="command">
 631 &lt;Printer name&gt;
 632   ...
 633   StateTime 1133542425
 634 &lt;/Printer&gt;
 635 </PRE>
 636
 637 <H3>Description</H3>
 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>
 647 section.</P>
 648
 649
 650 </BODY>
 651 </HTML>