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 <CODE>lpadmin(8)</CODE> command, web interface,
  19 or any of the available GUIs to manage your printers instead. If
  20 you do choose to edit this file manually, you will need to
  21 restart 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">
  29 Accepting yes
  30 Accepting no
  31 </PRE>
  32
  33 <H4>Description</H4>
  34
  35 <P>The <CODE>Accepting</CODE> directive defines the initial state
  36 of the <VAR>printer-is-accepting-jobs</VAR> attribute. This state
  37 is 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
  46 HREF="#Printer"><CODE>Printer</CODE></A> or <A
  47 HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
  48 directive.</P>
  49
  50
  51 <H3 CLASS="title"><A NAME="AllowUser">AllowUser</A></H3>
  52
  53 <H4>Examples</H4>
  54
  55 <PRE CLASS="command">
  56 AllowUser foo_user
  57 AllowUser @bar_group
  58 </PRE>
  59
  60 <H4>Description</H4>
  61
  62 <P>The <CODE>AllowUser</CODE> directive adds a username or group
  63 name to the <VAR>requesting-user-name-allowed</VAR> attribute
  64 which 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
  71 HREF="#Printer"><CODE>Printer</CODE></A> or <A
  72 HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A> directive.
  73 This directive cannot be used with <A
  74 HREF="#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
  90 definition as the default server destination. The default server
  91 destination can be set using the <CODE>lpadmin(8)</CODE>
  92 command:</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
  99 overridden by the user's default destination settings which are
 100 normally 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">
 108 DenyUser foo_user
 109 DenyUser @bar_group
 110 </PRE>
 111
 112 <H4>Description</H4>
 113
 114 <P>The <CODE>DenyUser</CODE> directive adds a username or group
 115 name to the <VAR>requesting-user-name-denied</VAR> attribute
 116 which 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
 123 HREF="#Printer"><CODE>Printer</CODE></A> or <A
 124 HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A> directive.
 125 This directive cannot be used with <A
 126 HREF="#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">
 134 DeviceURI 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
 141 using 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
 148 HREF="#Printer"><CODE>Printer</CODE></A> or <A
 149 HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
 150 directive.</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">
 158 ErrorPolicy cancel-job
 159 ErrorPolicy retry-job
 160 ErrorPolicy stop-printer
 161 </PRE>
 162
 163 <H4>Description</H4>
 164
 165 <P>The <CODE>ErrorPolicy</CODE> directive defines the policy that
 166 is used when a backend is unable to send a print job to the
 167 printer. The <CODE>lpadmin(8)</CODE> command sets the current
 168 error 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="ref-cupsd-conf.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
 193 HREF="#Printer"><CODE>Printer</CODE></A> or <A
 194 HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
 195 directive.</P>
 196
 197
 198 <H3 CLASS="title"><A NAME="Info">Info</A></H3>
 199
 200 <H4>Examples</H4>
 201
 202 <PRE CLASS="command">
 203 Info 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
 217 HREF="#Printer"><CODE>Printer</CODE></A> or <A
 218 HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
 219 directive.</P>
 220
 221
 222 <H3 CLASS="title"><A NAME="JobSheets">JobSheets</A></H3>
 223
 224 <H4>Examples</H4>
 225
 226 <PRE CLASS="command">
 227 JobSheets none,standard
 228 </PRE>
 229
 230 <H4>Description</H4>
 231
 232 <P>The <CODE>JobSheets</CODE> directive specifies the default
 233 banner pages  to print before and after a print job. In the above
 234 example, only a <VAR>standard</VAR> banner will print after each
 235 job. The <CODE>lpadmin(8)</CODE> command is normally used to set
 236 the 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
 243 before the files in the job. If a second banner file is
 244 specified, it is printed  after the files in the job.</P>
 245
 246 <P>The available banner pages depend on the local system
 247 configuration; CUPS includes the following standard banner
 248 files:</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
 276 HREF="#Printer"><CODE>Printer</CODE></A> or <A
 277 HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
 278 directive.</P>
 279
 280
 281 <H3 CLASS="title"><A NAME="KLimit">KLimit</A></H3>
 282
 283 <H4>Examples</H4>
 284
 285 <PRE CLASS="command">
 286 KLimit 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
 300 HREF="#Printer"><CODE>Printer</CODE></A> or <A
 301 HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
 302 directive.</P>
 303
 304
 305 <H3 CLASS="title"><A NAME="Location">Location</A></H3>
 306
 307 <H4>Examples</H4>
 308
 309 <PRE CLASS="command">
 310 Location 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
 324 HREF="#Printer"><CODE>Printer</CODE></A> or <A
 325 HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
 326 directive.</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">
 334 OpPolicy default
 335 OpPolicy mypolicy
 336 </PRE>
 337
 338 <H4>Description</H4>
 339
 340 <P>The <CODE>OpPolicy</CODE> directive sets the operation policy
 341 that is used for the printer. The <CODE>lpadmin(8)</CODE> command
 342 sets 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
 349 to those defined using the <VAR>cupsd.conf</VAR> <A
 350 HREF="ref-cupsd-conf.html#Policy"><CODE>Policy</CODE></A>
 351 directive.</P>
 352
 353 <P>This directive must appear inside a <A
 354 HREF="#Printer"><CODE>Printer</CODE></A> or <A
 355 HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
 356 directive.</P>
 357
 358
 359 <H3 CLASS="title"><A NAME="PageLimit">PageLimit</A></H3>
 360
 361 <H4>Examples</H4>
 362
 363 <PRE CLASS="command">
 364 PageLimit 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
 378 HREF="#Printer"><CODE>Printer</CODE></A> or <A
 379 HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
 380 directive.</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">
 388 PortMonitor bcp
 389 PortMonitor none
 390 PortMonitor tbcp
 391 </PRE>
 392
 393 <H4>Description</H4>
 394
 395 <P>The <CODE>PortMonitor</CODE> directive sets the filter program that
 396 is used for every print job, typically to encode or package the print
 397 data in a format acceptable for a particular printer interface. It is
 398 set 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
 420 HREF="#Printer"><CODE>Printer</CODE></A> or <A
 421 HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
 422 directive.</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
 438 definition. Printers are added using the <CODE>lpadmin(8)</CODE>
 439 command:
 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">
 451 QuotaPeriod 604800
 452 </PRE>
 453
 454 <H4>Description</H4>
 455
 456 <P>The <CODE>QuotaPeriod</CODE> directive defines the value of
 457 the  <VAR>job-quota-period</VAR> attribute. Typical values are
 458 86400 (1 day), 604800 (1 week), 2592000 (1 month), and 31536000
 459 (1 year). It is set using the <CODE>lpadmin(8)</CODE>
 460 command:</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
 467 HREF="#Printer"><CODE>Printer</CODE></A> or <A
 468 HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
 469 directive.</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">
 477 Shared yes
 478 Shared no
 479 </PRE>
 480
 481 <H4>Description</H4>
 482
 483 <P>The <CODE>Shared</CODE> directive defines the initial value of
 484 the <VAR>printer-is-shared</VAR> attribute. The strings
 485 <VAR>yes</VAR> and <VAR>no</VAR> correspond to the true and false
 486 values, respectively. The <CODE>lpadmin(8)</CODE> command sets
 487 the 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
 494 HREF="#Printer"><CODE>Printer</CODE></A> or <A
 495 HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
 496 directive.</P>
 497
 498
 499 <H3 CLASS="title"><A NAME="State">State</A></H3>
 500
 501 <H4>Examples</H4>
 502
 503 <PRE CLASS="command">
 504 State idle
 505 State stopped
 506 </PRE>
 507
 508 <H4>Description</H4>
 509
 510 <P>The <CODE>State</CODE> directive defines the initial value of
 511 the <VAR>printer-state</VAR> attribute. The strings
 512 <VAR>idle</VAR> and <VAR>stopped</VAR> correspond to the IPP
 513 enumeration values 3 and 5, respectively. The
 514 <CODE>cupsenable(8)</CODE> and <CODE>cupsdisable(8)</CODE>
 515 commands 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
 523 HREF="#Printer"><CODE>Printer</CODE></A> or <A
 524 HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
 525 directive.</P>
 526
 527
 528 <H3 CLASS="title"><A NAME="StateMessage">StateMessage</A></H3>
 529
 530 <H4>Examples</H4>
 531
 532 <PRE CLASS="command">
 533 StateMessage Ready to print.
 534 </PRE>
 535
 536 <H4>Description</H4>
 537
 538 <P>The <CODE>StateMessage</CODE> directive defines the initial
 539 string for the  <VAR>printer-state-message</VAR> attribute. The
 540 following are some example messages:</P>
 541
 542 <PRE CLASS="command">
 543 StateMessage Connected to host_name...
 544 StateMessage Connecting to printer_queue on port port_number...
 545 StateMessage Network host host_name is busy; will retry in 30 seconds...
 546 StateMessage Printer busy; will retry in 10 seconds...
 547 StateMessage Printer is busy; retrying print job...
 548 StateMessage Print file accepted - job ID id_number.
 549 StateMessage Ready to print.
 550 StateMessage Waiting for job to complete
 551 </PRE>
 552
 553 <P>This directive must appear inside a <A
 554 HREF="#Printer"><CODE>Printer</CODE></A> or <A
 555 HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
 556 directive.</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">
 564 StateTime 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
 571 queue. It is mapped to the <VAR>printer-state-change-time</VAR>
 572 attribute.</P>
 573
 574 <P>This directive must appear inside a <A
 575 HREF="#Printer"><CODE>Printer</CODE></A> or <A
 576 HREF="#DefaultPrinter"><CODE>DefaultPrinter</CODE></A>
 577 directive.</P>
 578
 579
 580 </BODY>
 581 </HTML>