1<?xml version="1.0" encoding="iso-8859-1"?> 2<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> 3<chapter id="CUPS-printing"> 4 5<chapterinfo> 6 7 <author> 8 <firstname>Kurt</firstname><surname>Pfeifle</surname> 9 <affiliation> 10 <orgname>Danka Deutschland GmbH </orgname> 11 <address><email>kpfeifle@danka.de</email></address> 12 </affiliation> 13 </author> 14 <author> 15 <firstname>Ciprian</firstname><surname>Vizitiu</surname> 16 <affiliation> 17 <address><email>CVizitiu@gbif.org</email></address> 18 </affiliation> 19 <contrib>drawings</contrib> 20 </author> 21 22 <author>&person.jelmer;<contrib>drawings</contrib></author> 23 24 <pubdate> (27 Jan 2004) </pubdate> 25</chapterinfo> 26 27<title>CUPS Printing Support</title> 28 29<sect1> 30 31 <title>Introduction</title> 32 33 <sect2> 34 <title>Features and Benefits</title> 35 36 <para> 37<indexterm><primary>default printing</primary></indexterm> 38 The Common UNIX Print System (<ulink url="http://www.cups.org/">CUPS</ulink>) 39 has become quite popular. All major Linux distributions now ship it as their default printing 40 system. To many, it is still a mystical tool. Mostly, it just works. People tend to regard 41 it as a <quote>black box</quote> that they do not want to look into as long as it works. But once 42 there is a little problem, they have trouble finding out where to start debugging it. Refer to 43 <link linkend="classicalprinting">Classical Printing</link>, which contains much information 44 that is also relevant to CUPS. 45 </para> 46 47 <para> 48<indexterm><primary>CUPS</primary></indexterm> 49 CUPS sports quite a few unique and powerful features. While its basic functions may be grasped quite 50 easily, they are also new. Because it is different from other, more traditional printing systems, it is best 51 not to try to apply any prior knowledge about printing to this new system. Rather, try to understand CUPS from 52 the beginning. This documentation will lead you to a complete understanding of CUPS. Let's start with the most 53 basic things first. 54 </para> 55 56 </sect2> 57 58 <sect2> 59 <title>Overview</title> 60 61 <para> 62<indexterm><primary>print spooling system</primary></indexterm> 63<indexterm><primary>CUPS</primary></indexterm> 64<indexterm><primary>printer management system</primary></indexterm> 65<indexterm><primary>IETF</primary></indexterm> 66<indexterm><primary>Internet Printing Protocol</primary><see>IPP</see></indexterm> 67<indexterm><primary>Internet Engineering Task Force</primary><see>IETF</see></indexterm> 68<indexterm><primary>GUI</primary></indexterm> 69<indexterm><primary>KDEPrint</primary></indexterm> 70 CUPS is more than just a print spooling system. It is a complete printer management system that 71 complies with the new Internet Printing Protocol (IPP). IPP is an industry and Internet Engineering Task Force 72 (IETF) standard for network printing. Many of its functions can be managed remotely (or locally) via a Web 73 browser (giving you platform-independent access to the CUPS print server). Additionally, it has the 74 traditional command line and several more modern GUI interfaces (GUI interfaces developed by third parties, 75 like KDE's overwhelming <ulink url="http://printing.kde.org/">KDEPrint</ulink>). 76 </para> 77 78 <para> 79<indexterm><primary>raw printers</primary></indexterm> 80<indexterm><primary>smart printers</primary></indexterm> 81 CUPS allows creation of <emphasis>raw</emphasis> printers (i.e., no print file format translation) as 82 well as <emphasis>smart</emphasis> printers (i.e., CUPS does file format conversion as required for the 83 printer). In many ways, this gives CUPS capabilities similar to the MS Windows print monitoring system. Of 84 course, if you are a CUPS advocate, you would argue that CUPS is better! In any case, let us now explore how 85 to configure CUPS for interfacing with MS Windows print clients via Samba. 86 </para> 87 88 </sect2> 89 90</sect1> 91 92<sect1> 93 <title>Basic CUPS Support Configuration</title> 94 95 <para> 96<indexterm><primary>CUPS</primary></indexterm> 97<indexterm><primary>cupsd.conf</primary></indexterm> 98<indexterm><primary>/etc/printcap</primary></indexterm> 99<indexterm><primary>Printcap</primary></indexterm> 100<indexterm><primary>PrintcapFormat</primary></indexterm> 101Printing with CUPS in the most basic &smb.conf; setup in Samba-3.0 (as was true for 2.2.x) requires just two 102parameters: <smbconfoption name="printing">cups</smbconfoption> and <smbconfoption 103name="printcap">cups</smbconfoption>. CUPS does not need a printcap file. However, the 104<filename>cupsd.conf</filename> configuration file knows of two related directives that control how such a 105file will be automatically created and maintained by CUPS for the convenience of third-party applications 106(example: <parameter>Printcap /etc/printcap</parameter> and <parameter>PrintcapFormat BSD</parameter>). 107Legacy programs often require the existence of a printcap file containing printer names or they will refuse to 108print. Make sure CUPS is set to generate and maintain a printcap file. For details, see <command>man 109cupsd.conf</command> and other CUPS-related documentation, like the wealth of documents regarding the CUPS 110server itself available from the <ulink noescape="1" 111url="http://localhost:631/documentation.html">CUPS</ulink> web site. 112 </para> 113 114 <sect2> 115 <title>Linking smbd with libcups.so</title> 116 117 <para> 118<indexterm><primary>libcups.so</primary></indexterm> 119 Samba has a special relationship to CUPS. Samba can be compiled with CUPS library support. 120 Most recent installations have this support enabled. By default, CUPS linking is compiled 121 into smbd and other Samba binaries. Of course, you can use CUPS even 122 if Samba is not linked against <filename>libcups.so</filename> &smbmdash; but 123 there are some differences in required or supported configuration. 124 </para> 125 126 <para> 127<indexterm><primary>libcups</primary></indexterm> 128<indexterm><primary>ldd</primary></indexterm> 129 When Samba is compiled and linked with <filename>libcups</filename>, <smbconfoption name="printcap">cups</smbconfoption> 130 uses the CUPS API to list printers, submit jobs, query queues, and so on. Otherwise it maps to the System V 131 commands with an additional <command>-oraw</command> option for printing. On a Linux 132 system, you can use the <command>ldd</command> utility to find out if smbd has been linked with the 133 libcups library (<command>ldd</command> may not be present on other OS platforms, or its function may be embodied 134 by a different command): 135<screen> 136&rootprompt;<userinput>ldd `which smbd`</userinput> 137libssl.so.0.9.6 => /usr/lib/libssl.so.0.9.6 (0x4002d000) 138libcrypto.so.0.9.6 => /usr/lib/libcrypto.so.0.9.6 (0x4005a000) 139libcups.so.2 => /usr/lib/libcups.so.2 (0x40123000) 140[....] 141</screen> 142 </para> 143 144 <para> 145<indexterm><primary>libcups.so.2</primary></indexterm> 146 The line <computeroutput>libcups.so.2 => /usr/lib/libcups.so.2 (0x40123000)</computeroutput> shows 147 there is CUPS support compiled into this version of Samba. If this is the case, and printing = cups 148 is set, then <emphasis>any otherwise manually set print command in &smb.conf; is ignored</emphasis>. 149 This is an important point to remember! 150 </para> 151 152 <tip><para> Should it be necessary, for any reason, to set your own print commands, you can do this by setting 153 <smbconfoption name="printing">sysv</smbconfoption>. However, you will lose all the benefits 154 of tight CUPS-Samba integration. When you do this, you must manually configure the printing system commands 155 (most important: 156 <smbconfoption name="print command"/>; other commands are 157 <smbconfoption name="lppause command"/>, 158 <smbconfoption name="lpresume command"/>, 159 <smbconfoption name="lpq command"/>, 160 <smbconfoption name="lprm command"/>, 161 <smbconfoption name="queuepause command"/> and 162 <smbconfoption name="queue resume command"/>). 163 </para></tip> 164 165 </sect2> 166 167 <sect2> 168 <title>Simple &smb.conf; Settings for CUPS</title> 169 170 <para> 171 To summarize, <link linkend="cups-exam-simple">the Simplest Printing-Related 172 &smb.conf; file</link> shows the simplest printing-related setup for &smb.conf; to 173 enable basic CUPS support: 174 </para> 175 176 <example id="cups-exam-simple"> 177 <title>Simplest Printing-Related smb.conf</title> 178 <smbconfblock> 179 <smbconfsection name="[global]"/> 180 <smbconfoption name="load printers">yes</smbconfoption> 181 <smbconfoption name="printing">cups</smbconfoption> 182 <smbconfoption name="printcap name">cups</smbconfoption> 183 184 <smbconfsection name="[printers]"/> 185 <smbconfoption name="comment">All Printers</smbconfoption> 186 <smbconfoption name="path">/var/spool/samba</smbconfoption> 187 <smbconfoption name="browseable">no</smbconfoption> 188 <smbconfoption name="guest ok">yes</smbconfoption> 189 <smbconfoption name="writable">no</smbconfoption> 190 <smbconfoption name="printable">yes</smbconfoption> 191 <smbconfoption name="printer admin">root, @ntadmins, @smbprintadm</smbconfoption> 192 </smbconfblock> 193 </example> 194 195 <para> 196<indexterm><primary>PDF</primary></indexterm> 197<indexterm><primary>PostScript</primary></indexterm> 198<indexterm><primary>printer driver</primary></indexterm> 199 This is all you need for basic printing setup for CUPS. It will print all graphic, text, PDF, and PostScript 200 files submitted from Windows clients. However, most of your Windows users would not know how to send these 201 kinds of files to print without opening a GUI application. Windows clients tend to have local printer drivers 202 installed, and the GUI application's print buttons start a printer driver. Your users also rarely send files 203 from the command line. Unlike UNIX clients, they rarely submit graphic, text, or PDF formatted files directly 204 to the spooler. They nearly exclusively print from GUI applications with a <quote>printer driver</quote> 205 hooked between the application's native format and the print data stream. If the backend printer is not a 206 PostScript device, the print data stream is <quote>binary,</quote> sensible only for the target printer. Read 207 on to learn what problem this may cause and how to avoid it. 208 </para> 209 210 </sect2> 211 212 <sect2> 213 <title>More Complex CUPS &smb.conf; Settings</title> 214 215 <para> 216 <link linkend="overridesettings">The Overriding Global CUPS Settings for One Printer example</link> 217 is a slightly more complex printing-related setup for &smb.conf;. It enables general CUPS printing 218 support for all printers, but defines one printer share, which is set up differently. 219 </para> 220 221 <example id="overridesettings"> 222 <title>Overriding Global CUPS Settings for One Printer</title> 223 <smbconfblock> 224 <smbconfsection name="[global]"/> 225 <smbconfoption name="printing">cups</smbconfoption> 226 <smbconfoption name="printcap name">cups</smbconfoption> 227 <smbconfoption name="load printers">yes</smbconfoption> 228 229 <smbconfsection name="[printers]"/> 230 <smbconfoption name="comment">All Printers</smbconfoption> 231 <smbconfoption name="path">/var/spool/samba</smbconfoption> 232 <smbconfoption name="guest ok">yes</smbconfoption> 233 <smbconfoption name="writable">no</smbconfoption> 234 <smbconfoption name="printable">yes</smbconfoption> 235 <smbconfoption name="printer admin">root, @ntadmins, @smbprintadm</smbconfoption> 236 237 <smbconfsection name="[special_printer]"/> 238 <smbconfoption name="comment">A special printer with his own settings</smbconfoption> 239 <smbconfoption name="path">/var/spool/samba-special</smbconfoption> 240 <smbconfoption name="printing">sysv</smbconfoption> 241 <smbconfoption name="printcap">lpstat</smbconfoption> 242 <smbconfoption name="print command">echo "NEW: `date`: printfile %f" >> /tmp/smbprn.log ; echo " `date`: p-%p s-%s f-%f" >> /tmp/smbprn.log ; echo " `date`: j-%j J-%J z-%z c-%c" >> /tmp/smbprn.log ; rm %f </smbconfoption> 243 <smbconfoption name="guest ok">no</smbconfoption> 244 <smbconfoption name="writable">no</smbconfoption> 245 <smbconfoption name="printable">yes</smbconfoption> 246 <smbconfoption name="printer admin">kurt</smbconfoption> 247 <smbconfoption name="hosts deny">0.0.0.0</smbconfoption> 248 <smbconfoption name="hosts allow">turbo_xp, 10.160.50.23, 10.160.51.60</smbconfoption> 249 </smbconfblock> 250 </example> 251 252 <para> 253 This special share is only for testing purposes. It does not write the print job to a file. It just logs the job parameters 254 known to Samba into the <filename>/tmp/smbprn.log</filename> file and deletes the job-file. Moreover, the 255 <smbconfoption name="printer admin"/> of this share is <quote>kurt</quote> (not the <quote>@ntadmins</quote> group), 256 guest access is not allowed, the share isn't published to the Network Neighborhood (so you need to know it is there), and it 257 allows access from only three hosts. To prevent CUPS from kicking in and taking over the print jobs for that share, we need to set 258 <smbconfoption name="printing">sysv</smbconfoption> and <smbconfoption name="printcap">lpstat</smbconfoption>. 259 </para> 260 261 </sect2> 262 263</sect1> 264 265<sect1> 266 <title>Advanced Configuration</title> 267 268 <para> 269 Before we delve into all the configuration options, let us clarify a few points. <emphasis>Network printing 270 needs to be organized and set up correctly</emphasis>. This frequently doesn't happen. Legacy systems or small 271 business LAN environments often lack design and good housekeeping. 272 </para> 273 274 275 <sect2> 276 <title>Central Spooling vs. <quote>Peer-to-Peer</quote> Printing</title> 277 278 279 <para> 280<indexterm><primary>spooling</primary></indexterm> 281 <indexterm><primary>spooling</primary><secondary>central</secondary></indexterm> 282 <indexterm><primary>spooling</primary><secondary>peer-to-peer</secondary></indexterm> 283 Many small office or home networks, as well as badly organized larger environments, allow each client a direct 284 access to available network printers. This is generally a bad idea. It often blocks one client's access to the 285 printer when another client's job is printing. It might freeze the first client's application while it is 286 waiting to get rid of the job. Also, there are frequent complaints about various jobs being printed with their 287 pages mixed with each other. A better concept is the use of a print server: it routes all jobs through one 288 central system, which responds immediately, takes jobs from multiple concurrent clients, and transfers them to 289 the printer(s) in the correct order. 290 </para> 291 292 </sect2> 293 294 <sect2> 295 <title>Raw Print Serving: Vendor Drivers on Windows Clients</title> 296 297 <para> 298 <indexterm><primary>spooling-only</primary></indexterm> 299 <indexterm><primary>raw printing</primary></indexterm> 300 Most traditionally configured UNIX print servers acting on behalf of 301 Samba's Windows clients represented a really simple setup. Their only 302 task was to manage the <quote>raw</quote> spooling of all jobs handed to them by 303 Samba. This approach meant that the Windows clients were expected to 304 prepare the print job file that is ready to be sent to the printing 305 device. In this case, a native (vendor-supplied) Windows printer driver needs to 306 be installed on each and every client for the target device. 307 </para> 308 309 <para> 310<indexterm><primary>render</primary></indexterm> 311<indexterm><primary>vendor-provided drivers</primary></indexterm> 312 It is possible to configure CUPS, Samba, and your Windows clients in the 313 same traditional and simple way. When CUPS printers are configured 314 for raw print-through mode operation, it is the responsibility of the 315 Samba client to fully render the print job (file). The file must be 316 sent in a format that is suitable for direct delivery to the 317 printer. Clients need to run the vendor-provided drivers to do 318 this. In this case, CUPS will not do any print file format conversion 319 work. 320 </para> 321 322 <para> 323 The easiest printing configuration possible is raw print-through. 324 This is achieved by installation of the printer as if it were physically 325 attached to the Windows client. You then redirect output to a raw network 326 print queue. This procedure may be followed to achieve this: 327 </para> 328 329 <procedure> 330 <title>Configuration Steps for Raw CUPS Printing Support</title> 331 332 <step><para> 333<indexterm><primary>/etc/cups/mime.types</primary></indexterm> 334 Edit <filename>/etc/cups/mime.types</filename> to uncomment the line 335 near the end of the file that has: 336<screen> 337#application/octet-... 338</screen> 339 </para></step> 340 341 <step><para> 342<indexterm><primary>/etc/cups/mime.convs</primary></indexterm> 343 Do the same for the file <filename>/etc/cups/mime.convs</filename>. 344 </para></step> 345 346 <step><para> 347 Add a raw printer using the Web interface. Point your browser at 348 <constant>http://localhost:631</constant>. Enter Administration, and add 349 the printer following the prompts. Do not install any drivers for it. 350 Choose Raw. Choose queue name <constant>Raw Queue</constant>. 351 </para></step> 352 353 <step><para> 354 In the &smb.conf; file <constant>[printers]</constant> section add 355 <smbconfoption name="use client driver">Yes</smbconfoption>, 356 and in the <constant>[global]</constant> section add 357 <smbconfoption name="printing">CUPS</smbconfoption>, plus 358 <smbconfoption name="printcap">CUPS</smbconfoption>. 359 </para></step> 360 361 <step><para> 362 Install the printer as if it is a local printer, that is, Printing to <constant>LPT1:</constant>. 363 </para></step> 364 365 <step><para> 366 Edit the configuration under the <guimenu>Detail</guimenu> tab and create a 367 <constant>local port</constant> that points to the raw printer queue that 368 you have configured above. Example: <constant>\\server\raw_q</constant>. 369 Here, the name <constant>raw_q</constant> is the name you gave the print 370 queue in the CUPS environment. 371 </para></step> 372 </procedure> 373 374 </sect2> 375 376 <sect2> 377 <title>Installation of Windows Client Drivers</title> 378 379 <para> 380 The printer drivers on the Windows clients may be installed 381 in two functionally different ways: 382 </para> 383 384 <itemizedlist> 385 <listitem><para>Manually install the drivers locally on each client, 386 one by one; this yields the old LanMan style 387 printing and uses a <filename>\\sambaserver\printershare</filename> 388 type of connection.</para></listitem> 389 390 391 <listitem><para> 392 <indexterm><primary>point 'n' print</primary></indexterm> 393 Deposit and prepare the drivers (for later download) on 394 the print server (Samba); this enables the clients to use 395 <quote>Point'n'Print</quote> to get drivers semi-automatically installed the 396 first time they access the printer; with this method NT/200x/XP 397 clients use the <emphasis>SPOOLSS/MS-RPC</emphasis> 398 type printing calls.</para></listitem> 399 </itemizedlist> 400 401 <para> 402 The second method is recommended for use over the first as it reduces the 403 administrative efforts and prevents that different versions of the drivers 404 are used accidentally. 405 </para> 406 </sect2> 407 408 <sect2 id="cups-raw"> 409 <title>Explicitly Enable <quote>raw</quote> Printing for <emphasis>application/octet-stream</emphasis></title> 410 411 412 <para> 413 <indexterm><primary>application/octet-stream</primary></indexterm> 414 <indexterm><primary>raw printing</primary></indexterm> 415 <indexterm><primary>MIME</primary><secondary>raw</secondary></indexterm> 416 If you use the first option (drivers are installed on the client 417 side), there is one setting to take care of: CUPS needs to be told 418 that it should allow <quote>raw</quote> printing of deliberate (binary) file 419 formats. The CUPS files that need to be correctly set for raw mode 420 printers to work are: 421 </para> 422 423 <itemizedlist> 424 <listitem><para><filename>/etc/cups/mime.types</filename></para></listitem> 425 <listitem><para><filename>/etc/cups/mime.convs</filename></para></listitem> 426 </itemizedlist> 427 428 <para> 429 Both contain entries (at the end of the respective files) that must be uncommented to allow RAW mode 430 operation. In <filename>/etc/cups/mime.types</filename>, make sure this line is present: 431<programlisting> 432application/octet-stream 433</programlisting> 434 <indexterm><primary>/etc/cups/mime.convs</primary></indexterm> 435 <indexterm><primary>/etc/cups/mime.types</primary></indexterm> 436 In <filename>/etc/cups/mime.convs</filename>, have this line: 437 <indexterm><primary>application/vnd.cups-raw</primary></indexterm> 438<programlisting> 439application/octet-stream application/vnd.cups-raw 0 - 440</programlisting> 441 If these two files are not set up correctly for raw Windows client 442 printing, you may encounter the dreaded <computeroutput>Unable to 443 convert file 0</computeroutput> in your CUPS <filename>error_log</filename> file. 444 </para> 445 446 <note><para> 447 Editing the <filename>mime.convs</filename> and the <filename>mime.types</filename> file does 448 not <emphasis>enforce</emphasis> <quote>raw</quote> printing, it only <emphasis>allows</emphasis> it. 449 </para></note> 450 451 <formalpara><title>Background</title> 452 453 <para> 454 <indexterm><primary>application/octet-stream</primary></indexterm> 455<indexterm><primary>MIME type</primary></indexterm> 456 That CUPS is a more security-aware printing system than traditional ones does not by default allow a user to 457 send deliberate (possibly binary) data to printing devices. This could be easily abused to launch a 458 <quote>Denial of Service</quote> attack on your printer(s), causing at least the loss of a lot of paper and 459 ink. <quote>Unknown</quote> data are tagged by CUPS as <parameter>MIME type: application/octet-stream</parameter> 460 and not allowed to go to the printer. By default, you can only send other (known) MIME types <quote>raw.</quote> 461 Sending data <quote>raw</quote> means that CUPS does not try to convert them and passes them to the printer 462 untouched. 463 </para> 464 </formalpara> 465 466 <para> 467 This is all you need to know to get the CUPS/Samba combo printing 468 <quote>raw</quote> files prepared by Windows clients, which have vendor drivers 469 locally installed. If you are not interested in background information about 470 more advanced CUPS/Samba printing, simply skip the remaining sections 471 of this chapter. 472 </para> 473 474 </sect2> 475 476 <sect2> 477 <title>Driver Upload Methods</title> 478 479 <para> 480 This section describes three familiar methods, plus one new one, by which 481 printer drivers may be uploaded. 482 </para> 483 484 <para> 485 <indexterm><primary>point'n'print</primary></indexterm> 486 If you want to use the MS-RPC-type printing, you must upload the 487 drivers onto the Samba server first (<smbconfsection name="[print$]"/> 488 share). For a discussion on how to deposit printer drivers on the 489 Samba host (so the Windows clients can download and use them via 490 <quote>Point'n'Print</quote>), please refer to the <link linkend="classicalprinting">Classical Printing 491 chapter</link> of this book. There you will find a description or reference to 492 three methods of preparing the client drivers on the Samba server: 493 </para> 494 495 <itemizedlist> 496 <listitem><para> 497 <indexterm><primary>add printer wizard</primary></indexterm> 498 The GUI, <quote>Add Printer Wizard</quote> <emphasis>upload-from-a-Windows-client</emphasis> method. 499 </para></listitem> 500 501 <listitem><para> 502 The command line, <quote>smbclient/rpcclient</quote> upload-from-a-UNIX-workstation method. 503 </para></listitem> 504 505 <listitem><para> 506 <indexterm><primary>imprints</primary></indexterm> 507 The Imprints tool set method. 508 </para></listitem> 509 </itemizedlist> 510 511 <para> 512<indexterm><primary>cupsaddsmb</primary></indexterm> 513 These three methods apply to CUPS all the same. The <command>cupsaddsmb</command> utility is a new and more 514 convenient way to load the Windows drivers into Samba and is provided if you use CUPS. 515 </para> 516 517 <para> 518 <command>cupsaddsmb</command> is discussed in much detail later in this chapter. But we first 519 explore the CUPS filtering system and compare the Windows and UNIX printing architectures. 520 </para> 521 522 </sect2> 523 524</sect1> 525 526<sect1> 527 <title>Advanced Intelligent Printing with PostScript Driver Download</title> 528 529 <para> 530 <indexterm><primary>PostScript</primary><seealso>Ghostscript</seealso></indexterm> 531 We now know how to set up a <quote>dump</quote> print server, that is, a server that spools 532 print jobs <quote>raw</quote>, leaving the print data untouched. 533 </para> 534 535 <para> 536 You might need to set up CUPS in a smarter way. The reasons could be manifold: 537 </para> 538 539<indexterm><primary>print statistics</primary></indexterm> 540<indexterm><primary>average print run</primary></indexterm> 541<indexterm><primary>print quota</primary></indexterm> 542 <itemizedlist> 543 <listitem><para>Maybe your boss wants to get monthly statistics: Which 544 printer did how many pages? What was the average data size of a job? 545 What was the average print run per day? What are the typical hourly 546 peaks in printing? Which department prints how much?</para></listitem> 547 548 <listitem><para>Maybe you are asked to set up a print quota system: 549 Users should not be able to print more jobs once they have surpassed 550 a given limit per period.</para></listitem> 551 552 <listitem><para>Maybe your previous network printing setup is a mess 553 and must be re-organized from a clean beginning.</para></listitem> 554 555 <listitem><para>Maybe you are experiencing too many <quote>blue screens</quote> 556 originating from poorly debugged printer drivers running in NT <quote>kernel mode</quote>?</para></listitem> 557 </itemizedlist> 558 559 <para> 560 These goals cannot be achieved by a raw print server. To build a 561 server meeting these requirements, you'll first need to learn 562 how CUPS works and how you can enable its features. 563 </para> 564 565 <para> 566 What follows is the comparison of some fundamental concepts for 567 Windows and UNIX printing, then a description of the 568 CUPS filtering system, how it works, and how you can tweak it. 569 </para> 570 571 <sect2 id="gdipost"> 572 <title>GDI on Windows, PostScript on UNIX</title> 573 574 <para> 575 <indexterm><primary>GDI</primary></indexterm> 576 <indexterm><primary>PostScript</primary></indexterm> 577 Network printing is one of the most complicated and error-prone 578 day-to-day tasks any user or administrator may encounter. This is 579 true for all OS platforms, and there are reasons it is so. 580 </para> 581 582 583 <para> 584 <indexterm><primary>PCL</primary></indexterm> 585 <indexterm><primary>PDL</primary></indexterm> 586<indexterm><primary>PostScript</primary></indexterm> 587<indexterm><primary>Adobe</primary></indexterm> 588<indexterm><primary>page description languages</primary><see>PDL</see></indexterm> 589 You can't expect to throw just any file format at a printer and have it get printed. A file format conversion 590 must take place. The problem is that there is no common standard for print file formats across all 591 manufacturers and printer types. While PostScript (trademark held by Adobe) and, to an extent, PCL (trademark 592 held by Hewlett-Packard) have developed into semi-official <quote>standards</quote> by being the most widely 593 used page description languages (PDLs), there are still many manufacturers who <quote>roll their own</quote> 594 (their reasons may be unacceptable license fees for using printer-embedded PostScript interpreters, and so on). 595 </para> 596 597 </sect2> 598 599 <sect2> 600 <title>Windows Drivers, GDI, and EMF</title> 601 602 <para> 603 <indexterm><primary>GDI</primary></indexterm> 604 <indexterm><primary>EMF</primary></indexterm> 605 <indexterm><primary>WYSIWYG</primary></indexterm> 606<indexterm><primary>Enhanced MetaFile</primary><see>EMF</see></indexterm> 607 In Windows OS, the format conversion job is done by the printer drivers. On MS Windows OS platforms all 608 application programmers have at their disposal a built-in API, the graphical device interface (GDI), as part 609 and parcel of the OS itself to base themselves on. This GDI core is used as one common unified ground for all 610 Windows programs to draw pictures, fonts, and documents <emphasis>on screen</emphasis> as well as <emphasis>on 611 paper</emphasis> (print). Therefore, printer driver developers can standardize on a well-defined GDI output 612 for their own driver input. Achieving WYSIWYG (What You See Is What You Get) is relatively easy, because the 613 on-screen graphic primitives, as well as the on-paper drawn objects, come from one common source. This source, 614 the GDI, often produces a file format called Enhanced MetaFile (EMF). The EMF is processed by the printer 615 driver and converted to the printer-specific file format. 616 </para> 617 618 <note><para> 619 <indexterm><primary>PDF</primary></indexterm> 620<indexterm><primary>Xprint</primary></indexterm> 621<indexterm><primary>core graphic engine</primary></indexterm> 622 To the GDI foundation in MS Windows, Apple has chosen to put paper and screen output on a common foundation 623 for its (BSD-UNIX-based, did you know?) Mac OS X and Darwin operating <indexterm><primary>X Window 624 System</primary></indexterm> <indexterm><primary>PostScript</primary></indexterm> 625 <indexterm><primary>PCL</primary></indexterm> <indexterm><primary>Xprint</primary></indexterm> systems. 626 Apple's <emphasis>core graphic engine</emphasis> uses a <emphasis>PDF</emphasis> derivative for all display work. 627 </para></note> 628 629 <para> 630 The example in <link linkend="f1small">Windows Printing to a Local Printer</link> illustrates local Windows 631 printing. 632 </para> 633 634 <figure id="f1small"> 635 <title>Windows Printing to a Local Printer.</title> 636 <imagefile>1small</imagefile> 637 </figure> 638 639 </sect2> 640 641 <sect2> 642 <title>UNIX Printfile Conversion and GUI Basics</title> 643 644 <para> 645 <indexterm><primary>X Window System</primary></indexterm> 646 <indexterm><primary>PostScript</primary></indexterm> 647 <indexterm><primary>PCL</primary></indexterm> 648 <indexterm><primary>Xprint</primary></indexterm> 649 In UNIX and Linux, there is no comparable layer built into the OS kernel(s) or the X (screen display) server. 650 Every application is responsible for itself to create its print output. Fortunately, most use PostScript and 651 that at least gives some common ground. Unfortunately, there are many different levels of quality for this 652 PostScript. And worse, there is a huge difference (and no common root) in the way the same document is 653 displayed on screen and how it is presented on paper. WYSIWYG is more difficult to achieve. This goes back to 654 the time, decades ago, when the predecessors of X.org, designing the UNIX foundations and protocols for 655 graphical user interfaces, refused to take responsibility for <quote>paper output</quote>, as some had 656 demanded at the time, and restricted itself to <quote>on-screen only.</quote> (For some years now, the 657 <quote>Xprint</quote> project has been under development, attempting to build printing support into the X 658 framework, including a PostScript and a PCL driver, but it is not yet ready for prime time.) You can see this 659 unfavorable inheritance up to the present day by looking into the various <quote>font</quote> directories on 660 your system; there are separate ones for fonts used for X display and fonts to be used on paper. 661 </para> 662 663 <formalpara> 664 <title>Background</title> 665 666 <para> 667 <indexterm><primary>PostScript</primary></indexterm> 668<indexterm><primary>color</primary></indexterm> 669<indexterm><primary>linewidth</primary></indexterm> 670<indexterm><primary>scale</primary></indexterm> 671<indexterm><primary>distort</primary></indexterm> 672<indexterm><primary>rotate</primary></indexterm> 673<indexterm><primary>shift</primary></indexterm> 674<indexterm><primary>raster images</primary></indexterm> 675<indexterm><primary>display PostScript</primary></indexterm> 676<indexterm><primary>graphical objects</primary></indexterm> 677 The PostScript programming language is an <quote>invention</quote> by Adobe, but its specifications have been 678 published extensively. Its strength lies in its powerful abilities to describe graphical objects (fonts, 679 shapes, patterns, lines, curves, and dots), their attributes (color, linewidth), and the way to manipulate 680 (scale, distort, rotate, shift) them. Because of its open specification, anybody with the skill can start 681 writing his or her own implementation of a PostScript interpreter and use it to display PostScript files on 682 screen or on paper. Most graphical output devices are based on the concept of <quote>raster images</quote> or 683 <quote>pixels</quote> (one notable exception is pen plotters). Of course, you can look at a PostScript file in 684 its textual form and you will be reading its PostScript code, the language instructions that need to be 685 interpreted by a rasterizer. Rasterizers produce pixel images, which may be displayed on screen by a viewer 686 program or on paper by a printer. 687 </para> 688 </formalpara> 689 </sect2> 690 691 <sect2 id="post-and-ghost"> 692 <title>PostScript and Ghostscript</title> 693 694 <para> 695 <indexterm><primary>PostScript</primary></indexterm> 696 <indexterm><primary>GhostScript</primary><seealso>PostScript</seealso></indexterm> 697 <indexterm><primary>PostScript</primary><secondary>RIP</secondary></indexterm> 698<indexterm><primary>PostScript interpreter</primary></indexterm> 699<indexterm><primary>raster image processor</primary><see>RIP</see></indexterm> 700 So UNIX is lacking a common ground for printing on paper and displaying on screen. Despite this unfavorable 701 legacy for UNIX, basic printing is fairly easy if you have PostScript printers at your disposal. The reason is 702 that these devices have a built-in PostScript language <quote>interpreter,</quote> also called a raster image 703 processor (RIP), (which makes them more expensive than other types of printers; throw PostScript toward them, 704 and they will spit out your printed pages. The RIP does all the hard work of converting the PostScript drawing 705 commands into a bitmap picture as you see it on paper, in a resolution as done by your printer. This is no 706 different than PostScript printing a file from a Windows origin. 707 </para> 708 709 <note><para> 710 <indexterm><primary>PPD</primary></indexterm> 711<indexterm><primary>PPD-aware</primary></indexterm> 712<indexterm><primary>PostScript Printer Description</primary><see>PPD</see></indexterm> 713 Traditional UNIX programs and printing systems &smbmdash; while using PostScript &smbmdash; are largely not 714 PPD-aware. PPDs are <quote>PostScript Printer Description</quote> files. They enable you to specify and 715 control all options a printer supports: duplexing, stapling, and punching. Therefore, UNIX users for a long 716 time couldn't choose many of the supported device and job options, unlike Windows or Apple users. But now 717 there is CUPS. as illustrated in <link linkend="f2small">Printing to a PostScript Printer</link>. 718 </para> 719 </note> 720 721 <figure id="f2small"> 722 <title>Printing to a PostScript Printer.</title> 723 <imagefile>2small</imagefile> 724 </figure> 725 726 <para> 727 <indexterm><primary>PDL</primary></indexterm> 728 However, there are other types of printers out there. These do not know how to print PostScript. They use 729 their own PDL, often proprietary. To print to them is much more demanding. Since your UNIX applications mostly 730 produce PostScript, and since these devices do not understand PostScript, you need to convert the print files 731 to a format suitable for your printer on the host before you can send it away. 732 </para> 733 734 </sect2> 735 736 <sect2> 737 <title>Ghostscript: The Software RIP for Non-PostScript Printers</title> 738 739 <para> 740 <indexterm><primary>GhostScript</primary></indexterm> 741 Here is where Ghostscript kicks in. Ghostscript is the traditional (and quite powerful) PostScript interpreter 742 used on UNIX platforms. It is a RIP in software, capable of doing a <emphasis>lot</emphasis> of file format 743 conversions for a very broad spectrum of hardware devices as well as software file formats. Ghostscript 744 technology and drivers are what enable PostScript printing to non-PostScript hardware. This is shown in 745 <link linkend="f3small">Ghostscript as a RIP for Non-PostScript Printers</link>. 746 </para> 747 748 <figure id="f3small"> 749 <title>Ghostscript as a RIP for Non-PostScript Printers.</title> 750 <imagefile>3small</imagefile> 751 </figure> 752 753 <tip><para> 754<indexterm><primary>PNG</primary></indexterm> 755<indexterm><primary>AFPL</primary></indexterm> 756<indexterm><primary>ESP</primary></indexterm> 757 Use the <quote>gs -h</quote> command to check for all built-in <quote>devices</quote> on your Ghostscript 758 version. If you specify a parameter of <parameter>-sDEVICE=png256</parameter> on your Ghostscript command 759 line, you are asking Ghostscript to convert the input into a PNG file. Naming a <quote>device</quote> on the 760 command line is the most important single parameter to tell Ghostscript exactly how it should render the 761 input. New Ghostscript versions are released at fairly regular intervals, now by artofcode LLC. They are 762 initially put under the <quote>AFPL</quote> license, but re-released under the GNU GPL as soon as the next 763 AFPL version appears. GNU Ghostscript is probably the version installed on most Samba systems. But it has some 764 deficiencies. <indexterm><primary>Ghostscript</primary><secondary>ESP</secondary><see>ESP 765 GhostScript</see></indexterm> Therefore, ESP Ghostscript was developed as an enhancement over GNU Ghostscript, 766 with lots of bug-fixes, additional devices, and improvements. It is jointly maintained by developers from 767 CUPS, Gutenprint, MandrakeSoft, SuSE, Red Hat, and Debian. It includes the <quote>cups</quote> device 768 (essential to print to non-PS printers from CUPS). 769 </para></tip> 770 771 </sect2> 772 773 <sect2> 774 <title>PostScript Printer Description (PPD) Specification</title> 775 776 <para> 777 <indexterm><primary>PPD</primary></indexterm> 778<indexterm><primary>PDL</primary></indexterm> 779<indexterm><primary>PostScript</primary></indexterm> 780 While PostScript in essence is a PDL to represent the page layout in a device-independent way, real-world 781 print jobs are always ending up being output on hardware with device-specific features. To take care of all 782 the differences in hardware and to allow for innovations, Adobe has specified a syntax and file format for 783 PostScript Printer Description (PPD) files. Every PostScript printer ships with one of these files. 784 </para> 785 786 <para> 787 PPDs contain all the information about general and special features of the 788 given printer model: Which different resolutions can it handle? Does 789 it have a duplexing unit? How many paper trays are there? What media 790 types and sizes does it take? For each item, it also names the special 791 command string to be sent to the printer (mostly inside the PostScript 792 file) in order to enable it. 793 </para> 794 795 <para> 796 Information from these PPDs is meant to be taken into account by the 797 printer drivers. Therefore, installed as part of the Windows 798 PostScript driver for a given printer is the printer's PPD. Where it 799 makes sense, the PPD features are presented in the drivers' UI dialogs 800 to display to the user a choice of print options. In the end, the 801 user selections are somehow written (in the form of special 802 PostScript, PJL, JCL, or vendor-dependent commands) into the PostScript 803 file created by the driver. 804 </para> 805 806 <warning><para> 807 <indexterm><primary>PDF</primary></indexterm> 808<indexterm><primary>PDF distilling</primary></indexterm> 809 A PostScript file that was created to contain device-specific commands 810 for achieving a certain print job output (e.g., duplexed, stapled, and 811 punched) on a specific target machine may not print as expected, or 812 may not be printable at all on other models; it also may not be fit 813 for further processing by software (e.g., by a PDF distilling program). 814 </para></warning> 815 </sect2> 816 817 <sect2> 818 <title>Using Windows-Formatted Vendor PPDs</title> 819 820 <para> 821<indexterm><primary>CUPS</primary></indexterm> 822<indexterm><primary>PPDs</primary></indexterm> 823<indexterm><primary>PostScript</primary></indexterm> 824 CUPS can handle all spec-compliant PPDs as supplied by the manufacturers for their PostScript models. Even if 825 a vendor does not mention our favorite OS in his or her manuals and brochures, you can safely trust this: 826 <emphasis>If you get the Windows NT version of the PPD, you can use it unchanged in CUPS</emphasis> and thus 827 access the full power of your printer just like a Windows NT user could! 828 </para> 829 830 <tip><para> 831 To check the spec compliance of any PPD online, go to <ulink noescape="1" 832 url="http://www.cups.org/testppd.php">http://www.cups.org/testppd.php</ulink> and upload your PPD. You will 833 see the results displayed immediately. CUPS in all versions after 1.1.19 has a much stricter internal PPD 834 parsing and checking code enabled; in case of printing trouble, this online resource should be one of your 835 first pit stops. 836 </para></tip> 837 838 <warning><para> 839 <indexterm><primary>foomatic</primary></indexterm> 840 <indexterm><primary>cupsomatic</primary></indexterm> 841 For real PostScript printers, <emphasis>do not</emphasis> use the <emphasis>Foomatic</emphasis> or 842 <emphasis>cupsomatic</emphasis> PPDs from Linuxprinting.org. With these devices, the original vendor-provided 843 PPDs are always the first choice. 844 </para></warning> 845 846 <tip><para> 847<indexterm><primary>W32X86/2</primary></indexterm> 848 If you are looking for an original vendor-provided PPD of a specific device, and you know that an NT4 box (or 849 any other Windows box) on your LAN has the PostScript driver installed, just use <command>smbclient 850 //NT4-box/print\$ -U username</command> to access the Windows directory where all printer driver files are 851 stored. First look in the <filename>W32X86/2</filename> subdirectory for the PPD you are seeking. 852 </para></tip> 853 </sect2> 854 855 <sect2> 856 <title>CUPS Also Uses PPDs for Non-PostScript Printers</title> 857 858 <para> 859<indexterm><primary>non-PostScript</primary></indexterm> 860<indexterm><primary>PPD</primary></indexterm> 861<indexterm><primary>CUPS filtering</primary></indexterm> 862 CUPS also uses specially crafted PPDs to handle non-PostScript printers. These PPDs are usually not available 863 from the vendors (and no, you can't just take the PPD of a PostScript printer with the same model name and 864 hope it works for the non-PostScript version too). To understand how these PPDs work for non-PS printers, we 865 first need to dive deeply into the CUPS filtering and file format conversion architecture. Stay tuned. 866 </para> 867 868 </sect2> 869 870</sect1> 871 872<sect1> 873<title>The CUPS Filtering Architecture</title> 874 875<para> 876<indexterm><primary>CUPS filtering</primary></indexterm> 877<indexterm><primary>Ghostscript</primary></indexterm> 878<indexterm><primary>MIME type</primary></indexterm> 879<indexterm><primary>MIME recognition</primary></indexterm> 880<indexterm><primary>MIME conversion rules</primary></indexterm> 881The core of the CUPS filtering system is based on Ghostscript. In addition to Ghostscript, CUPS uses some 882other filters of its own. You (or your OS vendor) may have plugged in even more filters. CUPS handles all data 883file formats under the label of various MIME types. Every incoming print file is subjected to an initial 884autotyping. The autotyping determines its given MIME type. A given MIME type implies zero or more possible 885filtering chains relevant to the selected target printer. This section discusses how MIME types recognition 886and conversion rules interact. They are used by CUPS to automatically set up a working filtering chain for any 887given input data format. 888</para> 889 890<para> 891If CUPS rasterizes a PostScript file natively to a bitmap, this is done in two stages: 892</para> 893 894<itemizedlist> 895 <listitem><para> 896<indexterm><primary>generic raster format</primary></indexterm> 897<indexterm><primary>CUPS raster</primary></indexterm> 898 The first stage uses a Ghostscript device named <quote>cups</quote> 899 (this is since version 1.1.15) and produces a generic raster format 900 called <quote>CUPS raster</quote>. 901 </para></listitem> 902 903 <listitem><para> 904<indexterm><primary>raster driver</primary></indexterm> 905 The second stage uses a <quote>raster driver</quote> that converts 906 the generic CUPS raster to a device-specific raster. 907 </para></listitem> 908</itemizedlist> 909 910<para> 911<indexterm><primary>Ghostscript</primary></indexterm> 912<indexterm><primary>GNU Ghostscript</primary></indexterm> 913<indexterm><primary>ESP Ghostscript</primary></indexterm> 914Make sure your Ghostscript version has the <quote>cups</quote> device compiled in (check with <command>gs -h | 915grep cups</command>). Otherwise you may encounter the dreaded <computeroutput>Unable to convert file 9160</computeroutput> in your CUPS error_log file. To have <quote>cups</quote> as a device in your Ghostscript, 917you either need to patch GNU Ghostscript and recompile or use 918<indexterm><primary>ESP</primary><secondary>Ghostscript</secondary></indexterm><ulink 919url="http://www.cups.org/ghostscript.php">ESP Ghostscript</ulink>. The superior alternative is ESP 920Ghostscript. It supports not just CUPS, but 300 other devices (while GNU Ghostscript supports only about 180). 921Because of this broad output device support, ESP Ghostscript is the first choice for non-CUPS spoolers, too. 922It is now recommended by Linuxprinting.org for all spoolers. 923</para> 924 925<para> 926<indexterm><primary>cupsomatic</primary></indexterm> 927<indexterm><primary>foomatic</primary></indexterm> 928<indexterm><primary>foomatic-rip</primary></indexterm> 929<indexterm><primary>ESP Ghostscript</primary></indexterm> 930CUPS printers may be set up to use external rendering paths. One of the most common is provided by the 931Foomatic/cupsomatic concept from <ulink url="http://www.linuxprinting.org/">Linuxprinting.org</ulink>. This 932uses the classical Ghostscript approach, doing everything in one step. It does not use the 933<quote>cups</quote> device, but one of the many others. However, even for Foomatic/cupsomatic usage, best 934results and <indexterm><primary>ESP</primary><secondary>Ghostscript</secondary></indexterm> broadest printer 935model support is provided by ESP Ghostscript (more about Foomatic/cupsomatic, particularly the new version 936called now <emphasis>foomatic-rip</emphasis>, follows). 937</para> 938 939 <sect2> 940 <title>MIME Types and CUPS Filters</title> 941 942 943 <para> 944 <indexterm><primary>MIME</primary><secondary>filters</secondary></indexterm> 945 <indexterm><primary>MIME</primary></indexterm> 946<indexterm><primary>mime.types</primary></indexterm> 947<indexterm><primary>application/pdf</primary></indexterm> 948<indexterm><primary>autotyping</primary></indexterm> 949 CUPS reads the file <filename>/etc/cups/mime.types</filename> (and all other files carrying a 950 <filename>*.types</filename> suffix in the same directory) upon startup. These files contain the MIME type 951 recognition rules that are applied when CUPS runs its autotyping routines. The rule syntax is explained in the 952 man page for <filename>mime.types</filename> and in the comments section of the 953 <filename>mime.types</filename> file itself. A simple rule reads like this: 954 <indexterm><primary>application/pdf</primary></indexterm> 955<programlisting> 956application/pdf pdf string(0,%PDF) 957</programlisting> 958<indexterm><primary>%PDF</primary></indexterm> 959<indexterm><primary>.pdf</primary></indexterm> 960 This means if a filename has a <filename>.pdf</filename> suffix or if the magic string 961 <emphasis>%PDF</emphasis> is right at the beginning of the file itself (offset 0 from the start), then it is a 962 PDF file (<parameter>application/pdf</parameter>). Another rule is this: 963<programlisting> 964application/postscript ai eps ps string(0,%!) string(0,<04>%!) 965</programlisting> 966<indexterm><primary>suffixes</primary></indexterm> 967<indexterm><primary>.ai</primary></indexterm> 968<indexterm><primary>.eps</primary></indexterm> 969<indexterm><primary>.ps</primary></indexterm> 970<indexterm><primary>generic PostScript</primary></indexterm> 971<indexterm><primary>application/postscript</primary></indexterm> 972 If the filename has one of the suffixes <filename>.ai</filename>, <filename>.eps</filename>, 973 <filename>.ps</filename>, or if the file itself starts with one of the strings <emphasis>%!</emphasis> or 974 <emphasis><![CDATA[<04>%!]]></emphasis>, it is a generic PostScript file 975 (<parameter>application/postscript</parameter>). 976 </para> 977 978 <warning><para> 979<indexterm><primary>/etc/cups/</primary></indexterm> 980 Don't confuse the other mime.types files your system might be using 981 with the one in the <filename>/etc/cups/</filename> directory. 982 </para></warning> 983 984 <note><para> 985<indexterm><primary>application/postscript</primary></indexterm> 986<indexterm><primary>PostScript</primary></indexterm> 987<indexterm><primary>filter</primary></indexterm> 988<indexterm><primary>PPD</primary></indexterm> 989<indexterm><primary>transformation</primary></indexterm> 990 There is an important difference between two similar MIME types in CUPS: one is 991 <parameter>application/postscript</parameter>, the other is 992 <parameter>application/vnd.cups-postscript</parameter>. While <parameter>application/postscript</parameter> is 993 meant to be device-independent, job options for the file are still outside the PS file content, embedded in 994 command line or environment variables by CUPS, <parameter>application/vnd.cups-postscript</parameter> may have 995 the job options inserted into the PostScript data itself (where applicable). The transformation of the generic 996 PostScript (<parameter>application/postscript</parameter>) to the device-specific version 997 (<parameter>application/vnd.cups-postscript</parameter>) is the responsibility of the CUPS 998 <parameter>pstops</parameter> filter. pstops uses information contained in the PPD to do the transformation. 999 </para></note> 1000 1001 <para> 1002<indexterm><primary>ASCII</primary></indexterm> 1003<indexterm><primary>HP-GL</primary></indexterm> 1004<indexterm><primary>PDF</primary></indexterm> 1005<indexterm><primary>PostScript</primary></indexterm> 1006<indexterm><primary>DVI</primary></indexterm> 1007<indexterm><primary>GIF</primary></indexterm> 1008<indexterm><primary>PNG</primary></indexterm> 1009<indexterm><primary>TIFF</primary></indexterm> 1010<indexterm><primary>JPEG</primary></indexterm> 1011<indexterm><primary>Photo-CD</primary></indexterm> 1012<indexterm><primary>SUN-Raster</primary></indexterm> 1013<indexterm><primary>PNM</primary></indexterm> 1014<indexterm><primary>PBM</primary></indexterm> 1015<indexterm><primary>SGI-RGB</primary></indexterm> 1016<indexterm><primary>MIME</primary></indexterm> 1017<indexterm><primary>filters</primary></indexterm> 1018 CUPS can handle ASCII text, HP-GL, PDF, PostScript, DVI, and 1019 many image formats (GIF, PNG, TIFF, JPEG, Photo-CD, SUN-Raster, 1020 PNM, PBM, SGI-RGB, and more) and their associated MIME types 1021 with its filters. 1022 </para> 1023 1024 </sect2> 1025 1026 <sect2> 1027 <title>MIME Type Conversion Rules</title> 1028 1029 1030 <para> 1031 <indexterm><primary>MIME</primary></indexterm> 1032 <indexterm><primary>application/pdf</primary></indexterm> 1033<indexterm><primary>/etc/cups/mime.convs</primary></indexterm> 1034<indexterm><primary>application/pdf</primary></indexterm> 1035<indexterm><primary>application/postscript</primary></indexterm> 1036 CUPS reads the file <filename>/etc/cups/mime.convs</filename> 1037 (and all other files named with a <filename>*.convs</filename> 1038 suffix in the same directory) upon startup. These files contain 1039 lines naming an input MIME type, an output MIME type, a format 1040 conversion filter that can produce the output from the input type, 1041 and virtual costs associated with this conversion. One example line 1042 reads like this: 1043<programlisting> 1044application/pdf application/postscript 33 pdftops 1045</programlisting> 1046<indexterm><primary>pdftops</primary></indexterm> 1047 This means that the <parameter>pdftops</parameter> filter will take 1048 <parameter>application/pdf</parameter> as input and produce 1049 <parameter>application/postscript</parameter> as output; the virtual 1050 cost of this operation is 33 CUPS-$. The next filter is more 1051 expensive, costing 66 CUPS-$: 1052 <indexterm><primary>pdf</primary></indexterm> 1053<programlisting> 1054application/vnd.hp-HPGL application/postscript 66 hpgltops 1055</programlisting> 1056<indexterm><primary>hpgltops</primary></indexterm> 1057 This is the <parameter>hpgltops</parameter>, which processes HP-GL 1058 plotter files to PostScript. 1059 <indexterm><primary>application/octet-stream</primary></indexterm> 1060<programlisting> 1061application/octet-stream 1062</programlisting> 1063 Here are two more examples: 1064 <indexterm><primary>text/plain</primary></indexterm> 1065<indexterm><primary>application/x-shell</primary></indexterm> 1066<indexterm><primary>text/plain</primary></indexterm> 1067<indexterm><primary>texttops</primary></indexterm> 1068<programlisting> 1069application/x-shell application/postscript 33 texttops 1070text/plain application/postscript 33 texttops 1071</programlisting> 1072<indexterm><primary>application/x-shell</primary></indexterm> 1073 The last two examples name the <parameter>texttops</parameter> filter to work on 1074 <parameter>text/plain</parameter> as well as on <parameter>application/x-shell</parameter>. (Hint: This 1075 differentiation is needed for the syntax highlighting feature of <parameter>texttops</parameter>). 1076 </para> 1077 </sect2> 1078 1079 <sect2> 1080 <title>Filtering Overview</title> 1081 1082 <para> 1083 <indexterm><primary>MIME</primary></indexterm> 1084 There are many more combinations named in <filename>mime.convs</filename>. However, you are not limited to use 1085 the ones predefined there. You can plug in any filter you like to the CUPS framework. It must meet, or must be 1086 made to meet, some minimal requirements. If you find (or write) a cool conversion filter of some kind, make 1087 sure it complies with what CUPS needs and put in the right lines in <filename>mime.types</filename> and 1088 <filename>mime.convs</filename>; then it will work seamlessly inside CUPS. 1089 </para> 1090 1091 <sect3> 1092 <title>Filter Requirements</title> 1093 1094 <para> 1095 The <quote>CUPS requirements</quote> for filters are simple. Take filenames or <filename>stdin</filename> as 1096 input and write to <filename>stdout</filename>. They should take these arguments: 1097 </para> 1098 1099 <variablelist> 1100 <varlistentry><term>printer</term> 1101 <listitem><para> 1102 The name of the printer queue (normally this is the name of the filter being run). 1103 </para></listitem> 1104 </varlistentry> 1105 1106 <varlistentry><term>job</term> 1107 <listitem><para> 1108 The numeric job ID for the job being printed. 1109 </para></listitem> 1110 </varlistentry> 1111 1112 <varlistentry><term>user</term> 1113 <listitem><para> 1114 The string from the originating-user-name attribute. 1115 </para></listitem> 1116 </varlistentry> 1117 1118 <varlistentry><term>title</term> 1119 <listitem><para> 1120 The string from the job-name attribute. 1121 </para></listitem> 1122 </varlistentry> 1123 1124 <varlistentry><term>copies</term> 1125 <listitem><para> 1126 The numeric value from the number-copies attribute. 1127 </para></listitem> 1128 </varlistentry> 1129 1130 <varlistentry><term>options</term> 1131 <listitem><para> 1132 The job options. 1133 </para></listitem> 1134 </varlistentry> 1135 1136 <varlistentry><term>filename</term> 1137 <listitem><para> 1138 (optionally) The print request file (if missing, filters expect data 1139 fed through <filename>stdin</filename>). In most cases, it is easy to 1140 write a simple wrapper script around existing filters to make them work with CUPS. 1141 </para></listitem> 1142 </varlistentry> 1143 </variablelist> 1144 1145 </sect3> 1146 1147 </sect2> 1148 1149 <sect2> 1150 <title>Prefilters</title> 1151 1152 <para> 1153 <indexterm><primary>PostScript</primary></indexterm> 1154<indexterm><primary>non-PostScript printers</primary></indexterm> 1155<indexterm><primary>raster</primary></indexterm> 1156 As previously stated, PostScript is the central file format to any UNIX-based 1157 printing system. From PostScript, CUPS generates raster data to feed 1158 non-PostScript printers. 1159 </para> 1160 1161 <para> 1162<indexterm><primary>prefilters</primary></indexterm> 1163<indexterm><primary>PostScript</primary></indexterm> 1164<indexterm><primary>ASCII text</primary></indexterm> 1165<indexterm><primary>PDF</primary></indexterm> 1166<indexterm><primary>DVI</primary></indexterm> 1167<indexterm><primary>HP-GL.</primary></indexterm> 1168<indexterm><primary>MIME type</primary></indexterm> 1169<indexterm><primary>application/postscript</primary></indexterm> 1170<indexterm><primary>pstops</primary></indexterm> 1171<indexterm><primary>application/vnd.cups-postscript</primary></indexterm> 1172 But what happens if you send one of the supported non-PS formats to print? Then CUPS runs 1173 <quote>prefilters</quote> on these input formats to generate PostScript first. There are prefilters to create 1174 PostScript from ASCII text, PDF, DVI, or HP-GL. The outcome of these filters is always of MIME type 1175 <parameter>application/postscript</parameter> (meaning that any device-specific print options are not yet 1176 embedded into the PostScript by CUPS and that the next filter to be called is pstops). Another prefilter is 1177 running on all supported image formats, the <parameter>imagetops</parameter> filter. Its outcome is always of 1178 MIME type <parameter>application/vnd.cups-postscript</parameter> (not application/postscript), meaning it has 1179 the print options already embedded into the file. This is shown in <link linkend="f4small">Prefiltering in 1180 CUPS to Form PostScript</link>. 1181 </para> 1182 1183 <figure id="f4small"> 1184 <title>Prefiltering in CUPS to Form PostScript.</title> 1185 <imagefile scale="25">4small</imagefile> 1186 </figure> 1187 1188 </sect2> 1189 1190 <sect2> 1191 <title>pstops</title> 1192 1193 <para> 1194<indexterm><primary>pstops</primary></indexterm> 1195<indexterm><primary>application/postscript</primary></indexterm> 1196<indexterm><primary>application/vnd.cups-postscript</primary></indexterm> 1197<indexterm><primary>output duplexing</primary></indexterm> 1198<indexterm><primary>stapling</primary></indexterm> 1199<indexterm><primary>punching</primary></indexterm> 1200<indexterm><primary>PostScript</primary></indexterm> 1201 <emphasis>pstops</emphasis> is a filter that is used to convert <parameter>application/postscript</parameter> to 1202 <parameter>application/vnd.cups-postscript</parameter>. As stated earlier, this filter inserts all 1203 device-specific print options (commands to the printer to ask for the duplexing of output, or stapling and 1204 punching it, and so on) into the PostScript file. An example is illustrated in <link 1205 linkend="f5small">Adding Device-Specific Print Options</link>. 1206 </para> 1207 1208 <figure id="f5small"> 1209 <title>Adding Device-Specific Print Options.</title> 1210 <imagefile scale="25">5small</imagefile> 1211 </figure> 1212 1213 <para> 1214 This is not all. Other tasks performed by it are: 1215 </para> 1216 1217 <itemizedlist> 1218 <listitem><para> 1219 Selecting the range of pages to be printed (e.g., you can choose to 1220 print only pages <quote>3, 6, 8-11, 16, and 19-21</quote>, or only odd-numbered 1221 pages). 1222 </para></listitem> 1223 1224 <listitem><para> 1225 Putting two or more logical pages on one sheet of paper (the 1226 so-called <quote>number-up</quote> function). 1227 </para></listitem> 1228 1229 <listitem><para>Counting the pages of the job to insert the accounting 1230 information into the <filename>/var/log/cups/page_log</filename>. 1231 </para></listitem> 1232 </itemizedlist> 1233 </sect2> 1234 1235 <sect2> 1236 <title>pstoraster</title> 1237 1238 <para> 1239<indexterm><primary>pstoraster</primary></indexterm> 1240<indexterm><primary>rasterization</primary></indexterm> 1241<indexterm><primary>raster drivers</primary></indexterm> 1242 <parameter>pstoraster</parameter> is at the core of the CUPS filtering system. It is responsible for the first 1243 stage of the rasterization process. Its input is of MIME type application/vnd.cups-postscript; its output is 1244 application/vnd.cups-raster. This output format is not yet meant to be printable. Its aim is to serve as a 1245 general-purpose input format for more specialized <emphasis>raster drivers</emphasis> that are able to 1246 generate device-specific printer data. This is shown in <link linkend="cups-raster">the PostScript to 1247 Intermediate Raster Format diagram</link>. 1248 </para> 1249 1250 <figure id="cups-raster"> 1251 <title>PostScript to Intermediate Raster Format.</title> 1252 <imagefile scale="25">6small</imagefile> 1253 </figure> 1254 1255 <para> 1256<indexterm><primary>CUPS raster</primary></indexterm> 1257<indexterm><primary>generic raster</primary></indexterm> 1258<indexterm><primary>IANA</primary></indexterm> 1259<indexterm><primary>raster drivers</primary></indexterm> 1260 CUPS raster is a generic raster format with powerful features. It is able to include per-page information, 1261 color profiles, and more, to be used by the downstream raster drivers. Its MIME type is registered with IANA 1262 and its specification is, of course, completely open. It is designed to make it quite easy and inexpensive for 1263 manufacturers to develop Linux and UNIX raster drivers for their printer models should they choose to do so. 1264 CUPS always takes care of the first stage of rasterization so these vendors do not need to care about 1265 Ghostscript complications (in fact, there are currently more than one vendor financing the development of CUPS 1266 raster drivers). This is illustrated in <link linkend="cups-raster2">the CUPS-Raster Production Using 1267 Ghostscript illustration</link>. 1268 </para> 1269 1270 <figure id="cups-raster2"> 1271 <title>CUPS-Raster Production Using Ghostscript.</title> 1272 <imagefile>7small</imagefile> 1273 </figure> 1274 1275 <para> 1276<indexterm><primary>pstoraster</primary></indexterm> 1277<indexterm><primary>GNU Ghostscript</primary></indexterm> 1278<indexterm><primary>AFPL Ghostscript</primary></indexterm> 1279<indexterm><primary>standalone filter</primary></indexterm> 1280 CUPS versions before version 1.1.15 shipped a binary (or source code) standalone filter, named 1281 <parameter>pstoraster</parameter>. <parameter>pstoraster</parameter>, which was derived from GNU Ghostscript 1282 5.50 and could be installed instead of and in addition to any GNU or AFPL Ghostscript package without 1283 conflicting. 1284 </para> 1285 1286 <para> 1287 Since version 1.1.15, this feature has changed. The functions for this filter have been integrated back 1288 into Ghostscript (now based on GNU Ghostscript version 7.05). The <parameter>pstoraster</parameter> filter is 1289 now a simple shell script calling <command>gs</command> with the <command>-sDEVICE=cups</command> parameter. 1290 If your Ghostscript fails when this command is executed: <command>gs -h |grep cups</command>, you might not 1291 be able to print, update your Ghostscript. 1292 </para> 1293 </sect2> 1294 1295 <sect2> 1296 <title>imagetops and imagetoraster</title> 1297 1298 <para> 1299<indexterm><primary>prefilter</primary></indexterm> 1300<indexterm><primary>imagetoraster</primary></indexterm> 1301 In the section about prefilters, we mentioned the prefilter 1302 that generates PostScript from image formats. The <parameter>imagetoraster</parameter> 1303 filter is used to convert directly from image to raster, without the 1304 intermediate PostScript stage. It is used more often than the previously 1305 mentioned prefilters. We summarize in a flowchart the image file 1306 filtering in <link linkend="small8">the Image Format to CUPS-Raster Format Conversion illustration</link>. 1307 </para> 1308 1309 <figure id="small8"> 1310 <title>Image Format to CUPS-Raster Format Conversion.</title> 1311 <imagefile>8small</imagefile> 1312 </figure> 1313 1314 </sect2> 1315 1316 <sect2> 1317 <title>rasterto [printers specific]</title> 1318 1319 <para> 1320<indexterm><primary>rastertoalps</primary></indexterm> 1321<indexterm><primary>rastertobj</primary></indexterm> 1322<indexterm><primary>rastertoepson</primary></indexterm> 1323<indexterm><primary>rastertoescp</primary></indexterm> 1324<indexterm><primary>rastertopcl</primary></indexterm> 1325<indexterm><primary>rastertoturboprint</primary></indexterm> 1326<indexterm><primary>rastertoescp</primary></indexterm> 1327<indexterm><primary>rastertohp</primary></indexterm> 1328<indexterm><primary>rastertoprinter</primary></indexterm> 1329<indexterm><primary>rastertoprinter</primary></indexterm> 1330<indexterm><primary>Gutenprint</primary></indexterm> 1331 CUPS ships with quite a variety of raster drivers for processing CUPS raster. On my system, I find in 1332 /usr/lib/cups/filter/ the following: <parameter>rastertoalps</parameter>, <parameter>rastertobj</parameter>, 1333 <parameter>rastertoepson</parameter>, <parameter>rastertoescp</parameter>, <parameter>rastertopcl</parameter>, 1334 <parameter>rastertoturboprint</parameter>, <parameter>rastertoapdk</parameter>, 1335 <parameter>rastertodymo</parameter>, <parameter>rastertoescp</parameter>, <parameter>rastertohp</parameter>, 1336 and <parameter>rastertoprinter</parameter>. Don't worry if you have fewer drivers than this; some of these are 1337 installed by commercial add-ons to CUPS (like <parameter>rastertoturboprint</parameter>), and others (like 1338 <parameter>rastertoprinter</parameter>) by third-party driver development projects (such as Gutenprint) 1339 wanting to cooperate as closely as possible with CUPS. See <link linkend="small9">the Raster to 1340 Printer-Specific Formats illustration</link>. 1341 </para> 1342 1343 <figure id="small9"> 1344 <title>Raster to Printer-Specific Formats.</title> 1345 <imagefile>9small</imagefile> 1346 </figure> 1347 </sect2> 1348 1349 <sect2> 1350 <title>CUPS Backends</title> 1351 1352 <para> 1353<indexterm><primary>CUPS filtering chain</primary></indexterm> 1354<indexterm><primary>print queue</primary></indexterm> 1355 The last part of any CUPS filtering chain is a backend. Backends 1356 are special programs that send the print-ready file to the final 1357 device. There is a separate backend program for any transfer 1358 protocol for sending print jobs over the network, and one for every local 1359 interface. Every CUPS print queue needs to have a CUPS <quote>device-URI</quote> 1360 associated with it. The device URI is the way to encode the backend 1361 used to send the job to its destination. Network device-URIs use 1362 two slashes in their syntax, local device URIs only one, as you can 1363 see from the following list. Keep in mind that local interface names 1364 may vary greatly from my examples, if your OS is not Linux: 1365 </para> 1366 1367 <variablelist> 1368 <varlistentry><term>usb</term> 1369 <listitem><para> 1370 This backend sends print files to USB-connected printers. An 1371 example for the CUPS device-URI to use is 1372 <filename>usb:/dev/usb/lp0</filename>. 1373 </para></listitem></varlistentry> 1374 1375 <varlistentry><term>serial</term> 1376 <listitem><para> 1377 This backend sends print files to serially connected printers. 1378 An example for the CUPS device-URI to use is 1379 <filename>serial:/dev/ttyS0?baud=11500</filename>. 1380 </para></listitem></varlistentry> 1381 1382 <varlistentry><term>parallel</term> 1383 <listitem><para> 1384 This backend sends print files to printers connected to the 1385 parallel port. An example for the CUPS device-URI to use is 1386 <filename>parallel:/dev/lp0</filename>. 1387 </para></listitem></varlistentry> 1388 1389 <varlistentry><term>SCSI</term> 1390 <listitem><para> 1391 This backend sends print files to printers attached to the 1392 SCSI interface. An example for the CUPS device-URI to use is 1393 <filename>scsi:/dev/sr1</filename>. 1394 </para></listitem></varlistentry> 1395 1396 <varlistentry><term>lpd</term> 1397 <listitem><para> 1398 This backend sends print files to LPR/LPD-connected network 1399 printers. An example for the CUPS device-URI to use is 1400 <filename>lpd://remote_host_name/remote_queue_name</filename>. 1401 </para></listitem></varlistentry> 1402 1403 <varlistentry><term>AppSocket/HP JetDirect</term> 1404 <listitem><para> 1405 This backend sends print files to AppSocket (a.k.a., HP 1406 JetDirect) connected network printers. An example for the CUPS 1407 device-URI to use is 1408 <filename>socket://10.11.12.13:9100</filename>. 1409 </para></listitem></varlistentry> 1410 1411 <varlistentry><term>ipp</term> 1412 <listitem><para> 1413 This backend sends print files to IPP-connected network 1414 printers (or to other CUPS servers). Examples for CUPS device-URIs 1415 to use are 1416 <filename>ipp:://192.193.194.195/ipp</filename> 1417 (for many HP printers) and 1418 <filename>ipp://remote_cups_server/printers/remote_printer_name</filename>. 1419 </para></listitem></varlistentry> 1420 1421 <varlistentry><term>http</term> 1422 <listitem><para> 1423 This backend sends print files to HTTP-connected printers. 1424 (The http:// CUPS backend is only a symlink to the ipp:// backend.) 1425 Examples for the CUPS device-URIs to use are 1426 <filename>http:://192.193.194.195:631/ipp</filename> 1427 (for many HP printers) and 1428 <filename>http://remote_cups_server:631/printers/remote_printer_name</filename>. 1429 </para></listitem></varlistentry> 1430 1431 <varlistentry><term>smb</term> 1432 <listitem><para> 1433 This backend sends print files to printers shared by a Windows 1434 host. Examples of CUPS device-URIs that may be used includes: 1435 </para> 1436 1437 <para> 1438 <simplelist> 1439 <member><filename>smb://workgroup/server/printersharename</filename></member> 1440 <member><filename>smb://server/printersharename</filename></member> 1441 <member><filename>smb://username:password@workgroup/server/printersharename</filename></member> 1442 <member><filename>smb://username:password@server/printersharename</filename></member> 1443 </simplelist> 1444 </para> 1445 1446 <para> 1447 The smb:// backend is a symlink to the Samba utility 1448 <parameter>smbspool</parameter> (does not ship with CUPS). If the 1449 symlink is not present in your CUPS backend directory, have your 1450 root user create it: <command>ln -s `which smbspool' 1451 /usr/lib/cups/backend/smb</command>. 1452 </para></listitem></varlistentry> 1453 </variablelist> 1454 1455 <para> 1456 It is easy to write your own backends as shell or Perl scripts if you 1457 need any modification or extension to the CUPS print system. One 1458 reason could be that you want to create <quote>special</quote> printers that send 1459 the print jobs as email (through a <quote>mailto:/</quote> backend), convert them to 1460 PDF (through a <quote>pdfgen:/</quote> backend) or dump them to <quote>/dev/null</quote>. (In 1461 fact, I have the systemwide default printer set up to be connected to 1462 a devnull:/ backend: there are just too many people sending jobs 1463 without specifying a printer, and scripts and programs that do not name 1464 a printer. The systemwide default deletes the job and sends a polite 1465 email back to the $USER asking him or her to always specify the correct 1466 printer name.) 1467 </para> 1468 1469 <para> 1470<indexterm><primary>lpinfo</primary></indexterm> 1471<indexterm><primary>CUPS backends</primary></indexterm> 1472 Not all of the mentioned backends may be present on your system or 1473 usable (depending on your hardware configuration). One test for all 1474 available CUPS backends is provided by the <emphasis>lpinfo</emphasis> 1475 utility. Used with the <option>-v</option> parameter, it lists 1476 all available backends: 1477 </para> 1478 1479 <para><screen> 1480 &prompt;<userinput>lpinfo -v</userinput> 1481 </screen></para> 1482 </sect2> 1483 1484 <sect2> 1485 <title>The Role of <parameter>cupsomatic/foomatic</parameter></title> 1486 1487 <para> 1488 <indexterm><primary>cupsomatic</primary></indexterm> 1489 <indexterm><primary>foomatic</primary></indexterm> 1490<indexterm><primary>PPDs</primary></indexterm> 1491<indexterm><primary>Foomatic Printer</primary></indexterm> 1492<indexterm><primary>Linuxprinting.org</primary></indexterm> 1493 <parameter>cupsomatic</parameter> filters may be the most widely used on CUPS 1494 installations. You must be clear that these were not 1495 developed by the CUPS people. They are a third-party add-on to 1496 CUPS. They utilize the traditional Ghostscript devices to render jobs 1497 for CUPS. When troubleshooting, you should know about the 1498 difference. Here the whole rendering process is done in one stage, 1499 inside Ghostscript, using an appropriate device for the target 1500 printer. <parameter>cupsomatic</parameter> uses PPDs that are generated from the Foomatic 1501 Printer & Driver Database at Linuxprinting.org. 1502 </para> 1503 1504 <para> 1505 You can recognize these PPDs from the line calling the 1506 <parameter>cupsomatic</parameter> filter: 1507<programlisting> 1508*cupsFilter: "application/vnd.cups-postscript 0 cupsomatic" 1509</programlisting> 1510 You may find this line among the first 40 or so lines of the PPD 1511 file. If you have such a PPD installed, the printer shows up in the 1512 CUPS Web interface with a <parameter>foomatic</parameter> namepart for 1513 the driver description. <parameter>cupsomatic</parameter> is a Perl script that runs 1514 Ghostscript with all the complicated command line options 1515 autoconstructed from the selected PPD and command line options given to 1516 the print job. 1517 </para> 1518 1519 <para> 1520 <indexterm><primary>point'n'print</primary></indexterm> 1521<indexterm><primary>foomatic-rip</primary></indexterm> 1522<indexterm><primary>Adobe specifications</primary></indexterm> 1523<indexterm><primary>hi-res photo</primary></indexterm> 1524<indexterm><primary>normal color</primary></indexterm> 1525<indexterm><primary>grayscale</primary></indexterm> 1526<indexterm><primary>draft</primary></indexterm> 1527<indexterm><primary>media type</primary></indexterm> 1528<indexterm><primary>resolution</primary></indexterm> 1529<indexterm><primary>inktype</primary></indexterm> 1530<indexterm><primary>dithering algorithm</primary></indexterm> 1531 However, <parameter>cupsomatic</parameter> is now deprecated. Its PPDs (especially the first 1532 generation of them, still in heavy use out there) are not meeting the 1533 Adobe specifications. You might also suffer difficulties when you try 1534 to download them with <quote>Point'n'Print</quote> to Windows clients. A better 1535 and more powerful successor is now available: it is called <parameter>foomatic-rip</parameter>. To use 1536 <parameter>foomatic-rip</parameter> as a filter with CUPS, you need the new type of PPDs, which 1537 have a similar but different line: 1538<programlisting> 1539*cupsFilter: "application/vnd.cups-postscript 0 foomatic-rip" 1540</programlisting> 1541 The PPD-generating engine at Linuxprinting.org has been revamped. 1542 The new PPDs comply with the Adobe spec. They also provide a 1543 new way to specify different quality levels (hi-res photo, normal 1544 color, grayscale, and draft) with a single click, whereas before you 1545 could have required five or more different selections (media type, 1546 resolution, inktype, and dithering algorithm). There is support for 1547 custom-size media built in. There is support to switch 1548 print options from page to page in the middle of a job. And the 1549 best thing is that the new <constant>foomatic-rip</constant> works seamlessly with all 1550 legacy spoolers too (like LPRng, BSD-LPD, PDQ, PPR, and so on), providing 1551 for them access to use PPDs for their printing. 1552 </para> 1553 </sect2> 1554 1555 <sect2> 1556 <title>The Complete Picture</title> 1557 1558 <para> 1559 If you want to see an overview of all the filters and how they 1560 relate to each other, the complete picture of the puzzle is at the end 1561 of this chapter. 1562 </para> 1563 </sect2> 1564 1565 <sect2> 1566 <title><filename>mime.convs</filename></title> 1567 1568 <para> 1569 CUPS autoconstructs all possible filtering chain paths for any given 1570 MIME type and every printer installed. But how does it decide in 1571 favor of or against a specific alternative? (There may be cases 1572 where there is a choice of two or more possible filtering chains for 1573 the same target printer.) Simple. You may have noticed the figures in 1574 the third column of the mime.convs file. They represent virtual costs 1575 assigned to this filter. Every possible filtering chain will sum up to 1576 a total <quote>filter cost.</quote> CUPS decides for the most <quote>inexpensive</quote> route. 1577 </para> 1578 1579 <tip><para> 1580<indexterm><primary>cupsd.conf</primary></indexterm> 1581<indexterm><primary>FilterLimit</primary></indexterm> 1582 Setting <parameter>FilterLimit 1000</parameter> in 1583 <filename>cupsd.conf</filename> will not allow more filters to 1584 run concurrently than will consume a total of 1000 virtual filter 1585 cost. This is an efficient way to limit the load of any CUPS 1586 server by setting an appropriate <quote>FilterLimit</quote> value. A FilterLimit of 1587 200 allows roughly one job at a time, while a FilterLimit of 1000 allows 1588 approximately five jobs maximum at a time. 1589 </para></tip> 1590 </sect2> 1591 1592 <sect2> 1593 <title><quote>Raw</quote> Printing</title> 1594 1595 <para> 1596<indexterm><primary>PPD</primary></indexterm> 1597<indexterm><primary>lpadmin</primary></indexterm> 1598<indexterm><primary>rawprinter</primary></indexterm> 1599 You can tell CUPS to print (nearly) any file <quote>raw</quote>. <quote>Raw</quote> means it will not be 1600 filtered. CUPS will send the file to the printer <quote>as is</quote> without bothering if the printer is able 1601 to digest it. Users need to take care themselves that they send sensible data formats only. Raw printing can 1602 happen on any queue if the <quote><parameter>-o raw</parameter></quote> option is specified on the command 1603 line. You can also set up raw-only queues by simply not associating any PPD with it. This command: 1604<screen> 1605&prompt;<userinput>lpadmin -P rawprinter -v socket://11.12.13.14:9100 -E</userinput> 1606</screen> 1607 sets up a queue named <quote>rawprinter</quote>, connected via the <quote>socket</quote> protocol (a.k.a. 1608 <quote>HP JetDirect</quote>) to the device at IP address 11.12.1.3.14, using port 9100. (If you had added a 1609 PPD with <command>-P /path/to/PPD</command> to this command line, you would have installed a 1610 <quote>normal</quote> print queue.) 1611 </para> 1612 1613 <para> 1614 CUPS will automatically treat each job sent to a queue as a <quote>raw</quote> one 1615 if it can't find a PPD associated with the queue. However, CUPS will 1616 only send known MIME types (as defined in its own mime.types file) and 1617 refuse others. 1618 </para> 1619 </sect2> 1620 1621 <sect2> 1622 <title>application/octet-stream Printing</title> 1623 1624 <para> 1625<indexterm><primary>/etc/cups/mime.types</primary></indexterm> 1626<indexterm><primary>application/octet-stream</primary></indexterm> 1627 Any MIME type with no rule in the <filename>/etc/cups/mime.types</filename> file is regarded as unknown 1628 or <parameter>application/octet-stream</parameter> and will not be 1629 sent. Because CUPS refuses to print unknown MIME types by default, 1630 you will probably have experienced that print jobs originating 1631 from Windows clients were not printed. You may have found an error 1632 message in your CUPS logs like: 1633 </para> 1634 1635 <para><computeroutput> 1636 Unable to convert file 0 to printable format for job 1637 </computeroutput></para> 1638 1639 <para> 1640 To enable the printing of <parameter>application/octet-stream</parameter> files, edit 1641 these two files: 1642 </para> 1643 1644 <itemizedlist> 1645 <listitem><para><filename>/etc/cups/mime.convs</filename></para></listitem> 1646 1647 <listitem><para><filename>/etc/cups/mime.types</filename></para></listitem> 1648 </itemizedlist> 1649 1650 <para> 1651<indexterm><primary>raw mode</primary></indexterm> 1652 Both contain entries (at the end of the respective files) that must be uncommented to allow raw mode 1653 operation for <parameter>application/octet-stream</parameter>. In <filename>/etc/cups/mime.types</filename> 1654 make sure this line is present: 1655 <indexterm><primary>application/octet-stream</primary></indexterm> 1656<programlisting> 1657application/octet-stream 1658</programlisting> 1659 This line (with no specific autotyping rule set) makes all files 1660 not otherwise auto-typed a member of <parameter>application/octet-stream</parameter>. In 1661 <filename>/etc/cups/mime.convs</filename>, have this 1662 line: 1663<programlisting> 1664application/octet-stream application/vnd.cups-raw 0 - 1665</programlisting> 1666 <indexterm><primary>MIME</primary></indexterm> 1667 This line tells CUPS to use the <emphasis>Null Filter</emphasis> 1668 (denoted as <quote>-</quote>, doing nothing at all) on 1669 <parameter>application/octet-stream</parameter>, and tag the result as 1670 <parameter>application/vnd.cups-raw</parameter>. This last one is 1671 always a green light to the CUPS scheduler to now hand the file over 1672 to the backend connecting to the printer and sending it over. 1673 </para> 1674 1675 <note><para> 1676 Editing the <filename>mime.convs</filename> and the <filename>mime.types</filename> file does not 1677 <emphasis>enforce</emphasis> <quote>raw</quote> printing, it only <emphasis>allows</emphasis> it. 1678 </para></note> 1679 1680 <formalpara> 1681 <title>Background</title> 1682 1683 <para> 1684<indexterm><primary>security-aware</primary></indexterm> 1685<indexterm><primary>MIME type</primary></indexterm> 1686<indexterm><primary>/etc/cups/mime.types</primary></indexterm> 1687<indexterm><primary>/etc/cups/mime.convs</primary></indexterm> 1688 That CUPS is a more security-aware printing system than traditional ones 1689 does not by default allow one to send deliberate (possibly binary) 1690 data to printing devices. (This could be easily abused to launch a 1691 Denial of Service attack on your printer(s), causing at least the loss 1692 of a lot of paper and ink.) <quote>Unknown</quote> data are regarded by CUPS 1693 as <emphasis>MIME type</emphasis> <emphasis>application/octet-stream</emphasis>. While you 1694 <emphasis>can</emphasis> send data <quote>raw</quote>, the MIME type for these must 1695 be one that is known to CUPS and allowed by it. The file 1696 <filename>/etc/cups/mime.types</filename> defines the <quote>rules</quote> of how CUPS 1697 recognizes MIME types. The file <filename>/etc/cups/mime.convs</filename> decides which file 1698 conversion filter(s) may be applied to which MIME types. 1699 </para> 1700 </formalpara> 1701 </sect2> 1702 1703 <sect2> 1704 <title>PostScript Printer Descriptions for Non-PostScript Printers</title> 1705 1706 <para> 1707 <indexterm><primary>PPD</primary></indexterm> 1708<indexterm><primary>non-PostScript</primary></indexterm> 1709<indexterm><primary>PostScript</primary></indexterm> 1710<indexterm><primary>RIP</primary></indexterm> 1711<indexterm><primary>Ghostscript</primary></indexterm> 1712<indexterm><primary>device-specific commands</primary></indexterm> 1713 Originally PPDs were meant to be used for PostScript printers 1714 only. Here, they help to send device-specific commands and settings 1715 to the RIP, which processes the job file. CUPS has extended this 1716 scope for PPDs to cover non-PostScript printers too. This was not 1717 difficult, because it is a standardized file format. In a way 1718 it was logical too: CUPS handles PostScript and uses a PostScript 1719 RIP (Ghostscript) to process the job files. The only difference is that 1720 a PostScript printer has the RIP built-in, for other types of 1721 printers the Ghostscript RIP runs on the host computer. 1722 </para> 1723 1724 <para> 1725 PPDs for a non-PostScript printer have a few lines that are unique to 1726 CUPS. The most important one looks similar to this: 1727 <indexterm><primary>application/vnd.cups-raster</primary></indexterm> 1728<programlisting> 1729*cupsFilter: application/vnd.cups-raster 66 rastertoprinter 1730</programlisting> 1731 It is the last piece in the CUPS filtering puzzle. This line tells the 1732 CUPS daemon to use as a last filter <parameter>rastertoprinter</parameter>. This filter 1733 should be served as input an <parameter>application/vnd.cups-raster</parameter> MIME type 1734 file. Therefore, CUPS should autoconstruct a filtering chain, which 1735 delivers as its last output the specified MIME type. This is then 1736 taken as input to the specified <parameter>rastertoprinter</parameter> filter. After 1737 the last filter has done its work (<parameter>rastertoprinter</parameter> is a Gutenprint 1738 filter), the file should go to the backend, which sends it to the 1739 output device. 1740 </para> 1741 1742 <para> 1743 CUPS by default ships only a few generic PPDs, but they are good for 1744 several hundred printer models. You may not be able to control 1745 different paper trays, or you may get larger margins than your 1746 specific model supports. See Table 21.1<link linkend="cups-ppds"></link> for summary information. 1747 </para> 1748 1749 <table frame="all" id="cups-ppds"> 1750 <title>PPDs Shipped with CUPS</title> 1751 <tgroup cols="2" align="left"> 1752 <colspec align="left"/> 1753 <colspec align="justify" colwidth="1*"/> 1754 <thead><row><entry>PPD file</entry><entry>Printer type</entry></row></thead> 1755 <tbody> 1756 <row><entry>deskjet.ppd</entry><entry>older HP inkjet printers and compatible</entry></row> 1757 1758 <row><entry>deskjet2.ppd</entry> <entry>newer HP inkjet printers and compatible </entry> </row> 1759 1760 <row><entry>dymo.ppd</entry> <entry>label printers </entry> </row> 1761 1762 <row><entry>epson9.ppd</entry> <entry>Epson 24-pin impact printers and compatible </entry> </row> 1763 1764 <row><entry>epson24.ppd</entry> <entry>Epson 24-pin impact printers and compatible </entry> </row> 1765 1766 <row><entry>okidata9.ppd</entry> <entry>Okidata 9-pin impact printers and compatible </entry> </row> 1767 1768 <row><entry>okidat24.ppd</entry> <entry>Okidata 24-pin impact printers and compatible </entry> </row> 1769 1770 <row><entry>stcolor.ppd</entry> <entry>older Epson Stylus Color printers </entry> </row> 1771 1772 <row><entry>stcolor2.ppd</entry> <entry>newer Epson Stylus Color printers </entry> </row> 1773 1774 <row><entry>stphoto.ppd</entry> <entry>older Epson Stylus Photo printers </entry> </row> 1775 1776 <row><entry>stphoto2.ppd</entry> <entry>newer Epson Stylus Photo printers </entry> </row> 1777 1778 <row><entry>laserjet.ppd</entry> <entry>all PCL printers </entry> </row> 1779 1780 </tbody> 1781 </tgroup> 1782 </table> 1783 1784 </sect2> 1785 1786 <sect2> 1787 <title><emphasis>cupsomatic/foomatic-rip</emphasis> Versus <emphasis>Native CUPS</emphasis> Printing</title> 1788 1789 <para> 1790 <indexterm><primary>cupsomatic</primary></indexterm> 1791 <indexterm><primary>foomatic-rip</primary></indexterm> 1792 Native CUPS rasterization works in two steps: 1793 </para> 1794 1795 <itemizedlist> 1796 <listitem><para> 1797<indexterm><primary>pstoraster</primary></indexterm> 1798 First is the <parameter>pstoraster</parameter> step. It uses the special CUPS 1799 <indexterm><primary>ESP</primary><secondary>Ghostscript</secondary></indexterm> 1800 device from ESP Ghostscript 7.05.x as its tool. 1801 </para></listitem> 1802 1803 <listitem><para> 1804 Second is the <parameter>rasterdriver</parameter> step. It uses various 1805 device-specific filters; there are several vendors who provide good 1806 quality filters for this step. Some are free software, some are 1807 shareware, and some are proprietary. 1808 </para></listitem> 1809 </itemizedlist> 1810 1811 <para> 1812 Often this produces better quality (and has several more advantages) than other methods. 1813 This is shown in <link linkend="cupsomatic-dia"> the cupsomatic/foomatic Processing Versus Native CUPS 1814 illustration</link>. 1815 </para> 1816 1817 <figure id="cupsomatic-dia"> 1818 <title>cupsomatic/foomatic Processing Versus Native CUPS.</title> 1819 <imagefile>10small</imagefile> 1820 </figure> 1821 1822 <para> 1823 One other method is the <parameter>cupsomatic/foomatic-rip</parameter> 1824 way. Note that <parameter>cupsomatic</parameter> is <emphasis>not</emphasis> made by the CUPS 1825 developers. It is an independent contribution to printing development, 1826 made by people from Linuxprinting.org.<footnote><para>See also <ulink 1827 noescape="1" url="http://www.cups.org/cups-help.html">http://www.cups.org/cups-help.html</ulink></para></footnote> 1828 <parameter>cupsomatic</parameter> is no longer developed, maintained, or supported. It now been 1829 replaced by <parameter>foomatic-rip</parameter>. <parameter>foomatic-rip</parameter> is a complete rewrite 1830 of the old <parameter>cupsomatic</parameter> idea, but very much improved and generalized to 1831 other (non-CUPS) spoolers. An upgrade to <parameter>foomatic-rip</parameter> is strongly 1832 advised, especially if you are upgrading to a recent version of CUPS, 1833 too. 1834 </para> 1835 1836 <para> 1837 <indexterm><primary>cupsomatic</primary></indexterm> 1838 <indexterm><primary>foomatic</primary></indexterm> 1839 Like the old <parameter>cupsomatic</parameter> method, the <parameter>foomatic-rip</parameter> (new) method 1840 from Linuxprinting.org uses the traditional Ghostscript print file processing, doing everything in a single 1841 step. It therefore relies on all the other devices built into Ghostscript. The quality is as good (or bad) as 1842 Ghostscript rendering is in other spoolers. The advantage is that this method supports many printer models not 1843 supported (yet) by the more modern CUPS method. 1844 </para> 1845 1846 <para> 1847 Of course, you can use both methods side by side on one system (and even for one printer, if you set up 1848 different queues) and find out which works best for you. 1849 </para> 1850 1851 <para> 1852<indexterm><primary>cupsomatic</primary></indexterm> 1853<indexterm><primary>pstoraster</primary></indexterm> 1854<indexterm><primary>rastertosomething</primary></indexterm> 1855<indexterm><primary>rasterization</primary></indexterm> 1856<indexterm><primary>Foomatic/cupsomatic</primary></indexterm> 1857<indexterm><primary>rendering</primary></indexterm> 1858 <parameter>cupsomatic</parameter> kidnaps the print file after the 1859 <parameter>application/vnd.cups-postscript</parameter> stage and deviates it through the CUPS-external, 1860 systemwide Ghostscript installation. Therefore, the print file bypasses the <parameter>pstoraster</parameter> 1861 filter (and also bypasses the CUPS raster drivers <parameter>rastertosomething</parameter>). After Ghostscript 1862 finished its rasterization, <parameter>cupsomatic</parameter> hands the rendered file directly to the CUPS 1863 backend. <link linkend="cupsomatic-dia">cupsomatic/foomatic Processing Versus Native 1864 CUPS</link>, illustrates the difference between native CUPS rendering and the 1865 <parameter>Foomatic/cupsomatic</parameter> method. 1866 </para> 1867 </sect2> 1868 1869 <sect2> 1870 <title>Examples for Filtering Chains</title> 1871 1872 <para> 1873 Here are a few examples of commonly occurring filtering chains to 1874 illustrate the workings of CUPS. 1875 </para> 1876 1877 <para> 1878<indexterm><primary>HP JetDirect</primary></indexterm> 1879<indexterm><primary>PostScript</primary></indexterm> 1880<indexterm><primary>two-up</primary></indexterm> 1881<indexterm><primary>duplex</primary></indexterm> 1882 Assume you want to print a PDF file to an HP JetDirect-connected 1883 PostScript printer, but you want to print pages 3-5, 7, and 11-13 1884 only, and you want to print them <quote>two-up</quote> and <quote>duplex</quote>: 1885 </para> 1886 1887 <itemizedlist> 1888 <listitem><para>Your print options (page selection as required, two-up, 1889 duplex) are passed to CUPS on the command line.</para></listitem> 1890 1891 <listitem><para>The (complete) PDF file is sent to CUPS and autotyped as 1892 <parameter>application/pdf</parameter>.</para></listitem> 1893 1894 <listitem><para>The file therefore must first pass the 1895 <parameter>pdftops</parameter> prefilter, which produces PostScript 1896 MIME type <parameter>application/postscript</parameter> (a preview here 1897 would still show all pages of the original PDF).</para></listitem> 1898 1899 <listitem><para>The file then passes the <parameter>pstops</parameter> 1900 filter that applies the command line options: it selects pages 1901 2-5, 7, and 11-13, creates the imposed layout <quote>two pages on one sheet</quote>, and 1902 inserts the correct <quote>duplex</quote> command (as defined in the printer's 1903 PPD) into the new PostScript file; the file is now of PostScript MIME 1904 type 1905 <parameter>application/vnd.cups-postscript</parameter>.</para></listitem> 1906 1907 <listitem><para>The file goes to the <parameter>socket</parameter> 1908 backend, which transfers the job to the printers.</para></listitem> 1909 </itemizedlist> 1910 1911 <para> 1912 The resulting filter chain, therefore, is as shown in <link linkend="pdftosocket">the PDF to socket chain 1913 illustration</link>. 1914 </para> 1915 1916<indexterm><primary>pdftosocket</primary></indexterm> 1917 <figure id="pdftosocket"> 1918 <title>PDF to Socket Chain.</title> 1919 <imagefile>pdftosocket</imagefile> 1920 </figure> 1921 1922 <para> 1923<indexterm><primary>USB</primary></indexterm> 1924<indexterm><primary>Epson Stylus</primary></indexterm> 1925<indexterm><primary>stphoto2.ppd</primary></indexterm> 1926 Assume you want to print the same filter to an USB-connected Epson Stylus Photo Printer installed with the CUPS 1927 <filename>stphoto2.ppd</filename>. The first few filtering stages are nearly the same: 1928 </para> 1929 1930 <itemizedlist> 1931 <listitem><para> 1932 Your print options (page selection as required, two-up, 1933 duplex) are passed to CUPS on the command line. 1934 </para></listitem> 1935 1936 <listitem><para> 1937 The (complete) PDF file is sent to CUPS and autotyped as 1938 <parameter>application/pdf</parameter>. 1939 </para></listitem> 1940 1941 <listitem><para> 1942<indexterm><primary>pdftops</primary></indexterm> 1943<indexterm><primary>PDF</primary></indexterm> 1944 The file must first pass the <parameter>pdftops</parameter> prefilter, which produces PostScript 1945 MIME type <parameter>application/postscript</parameter> (a preview here would still show all 1946 pages of the original PDF). 1947 </para></listitem> 1948 1949 <listitem><para> 1950<indexterm><primary>pstops</primary></indexterm> 1951<indexterm><primary>duplex printing</primary></indexterm> 1952 The file then passes the <quote>pstops</quote> filter that applies 1953 the command line options: it selects the pages 2-5, 7, and 11-13, 1954 creates the imposed layout <quote>two pages on one sheet,</quote> and inserts the 1955 correct <quote>duplex</quote> command (oops &smbmdash; this printer and PPD 1956 do not support duplex printing at all, so this option will 1957 be ignored) into the new PostScript file; the file is now of PostScript 1958 MIME type <parameter>application/vnd.cups-postscript</parameter>. 1959 </para></listitem> 1960 1961 <listitem><para> 1962 The file then passes the <parameter>pstoraster</parameter> stage and becomes MIME type 1963 <parameter>application/cups-raster</parameter>. 1964 </para></listitem> 1965 1966 <listitem><para> 1967<indexterm><primary>rastertoepson</primary></indexterm> 1968 Finally, the <parameter>rastertoepson</parameter> filter 1969 does its work (as indicated in the printer's PPD), creating the 1970 printer-specific raster data and embedding any user-selected 1971 print options into the print data stream. 1972 </para></listitem> 1973 1974 <listitem><para> 1975 The file goes to the <parameter>usb</parameter> backend, which transfers the job to the printers. 1976 </para></listitem> 1977 </itemizedlist> 1978 1979 <para> 1980 The resulting filter chain therefore is as shown in <link linkend="pdftoepsonusb">the PDF to USB Chain 1981 illustration</link>. 1982 </para> 1983 1984 <figure id="pdftoepsonusb"> 1985 <title>PDF to USB Chain.</title> 1986 <imagefile>pdftoepsonusb</imagefile> 1987 </figure> 1988 </sect2> 1989 1990 <sect2> 1991 <title>Sources of CUPS Drivers/PPDs</title> 1992 1993 <para> 1994 On the Internet you can now find many thousands of CUPS-PPD files 1995 (with their companion filters), in many national languages 1996 supporting more than 1,000 non-PostScript models. 1997 </para> 1998 1999 <itemizedlist> 2000 <indexterm><primary>ESP</primary><secondary>Print Pro</secondary></indexterm> 2001 <indexterm><primary>PrintPro</primary><see>ESP Print Pro</see></indexterm> 2002 <listitem><para> 2003 <ulink url="http://www.easysw.com/printpro/">ESP PrintPro</ulink> 2004 (commercial, non-free) is packaged with more than 3,000 PPDs, ready for 2005 successful use <quote>out of the box</quote> on Linux, Mac OS X, IBM-AIX, 2006 HP-UX, Sun-Solaris, SGI-IRIX, Compaq Tru64, Digital UNIX, and 2007 other commercial Unices (it is written by the CUPS developers 2008 themselves and its sales help finance the further development of 2009 CUPS, as they feed their creators). 2010 </para></listitem> 2011 2012 <listitem><para> 2013 The <ulink url="http://gimp-print.sourceforge.net/">Gutenprint Project</ulink> 2014 (GPL, free software) provides around 140 PPDs (supporting nearly 400 printers, many driven 2015 to photo quality output), to be used alongside the Gutenprint CUPS filters. 2016 </para></listitem> 2017 2018 <listitem><para> 2019 <ulink url="http://www.turboprint.de/english.html/">TurboPrint </ulink> (shareware, non-free) supports 2020 roughly the same number of printers in excellent quality. 2021 </para></listitem> 2022 2023 <listitem><para> 2024 <ulink url="http://www-124.ibm.com/developerworks/oss/linux/projects/omni/">OMNI </ulink> 2025 (LPGL, free) is a package made by IBM, now containing support for more 2026 than 400 printers, stemming from the inheritance of IBM OS/2 know-how 2027 ported over to Linux (CUPS support is in a beta stage at present). 2028 </para></listitem> 2029 2030 <listitem><para> 2031 <ulink url="http://hpinkjet.sourceforge.net/">HPIJS </ulink> (BSD-style licenses, free) 2032 supports approximately 150 of HP's own printers and also provides 2033 excellent print quality now (currently available only via the Foomatic path). 2034 </para></listitem> 2035 2036 <listitem><para> 2037 <ulink url="http://www.linuxprinting.org/">Foomatic/cupsomatic </ulink> 2038 (LPGL, free) from Linuxprinting.org provide PPDs for practically every Ghostscript 2039 filter known to the world (including Omni, Gutenprint, and HPIJS). 2040 </para></listitem> 2041 </itemizedlist> 2042 2043 </sect2> 2044 2045 <sect2> 2046 <title>Printing with Interface Scripts</title> 2047 2048 <para> 2049<indexterm><primary>PCL</primary></indexterm> 2050<indexterm><primary>lpadmin</primary></indexterm> 2051 CUPS also supports the use of <quote>interface scripts</quote> as known from 2052 System V AT&T printing systems. These are often used for PCL 2053 printers, from applications that generate PCL print jobs. Interface 2054 scripts are specific to printer models. They have a role similar to 2055 PPDs for PostScript printers. Interface scripts may inject the Escape 2056 sequences as required into the print data stream if the user, for example, selects 2057 a certain paper tray, or changes paper orientation, or uses A3 2058 paper. Interface scripts are practically unknown in the Linux 2059 realm. On HP-UX platforms they are more often used. You can use any 2060 working interface script on CUPS too. Just install the printer with 2061 the <command>-i</command> option: 2062<screen> 2063&rootprompt;<userinput>lpadmin -p pclprinter -v socket://11.12.13.14:9100 \ 2064 -i /path/to/interface-script</userinput> 2065</screen></para> 2066 2067 <para> 2068 Interface scripts might be the <quote>unknown animal</quote> to many. However, 2069 with CUPS they provide the easiest way to plug in your own custom-written filtering 2070 script or program into one specific print queue (some information about the traditional 2071 use of interface scripts is found at 2072 <ulink noescape="1" url="http://playground.sun.com/printing/documentation/interface.html"> 2073 http://playground.sun.com/printing/documentation/interface.html</ulink>). 2074 </para> 2075 </sect2> 2076</sect1> 2077 2078<sect1> 2079<title>Network Printing (Purely Windows)</title> 2080 2081<para> 2082Network printing covers a lot of ground. To understand what exactly 2083goes on with Samba when it is printing on behalf of its Windows 2084clients, let's first look at a <quote>purely Windows</quote> setup: Windows clients 2085with a Windows NT print server. 2086</para> 2087 2088<sect2> 2089<title>From Windows Clients to an NT Print Server</title> 2090 2091<para> 2092Windows clients printing to an NT-based print server have two 2093options. They may: 2094<indexterm><primary>GDI</primary></indexterm> 2095<indexterm><primary>EMF</primary></indexterm> 2096</para> 2097 2098 2099<itemizedlist> 2100 <listitem><para>Execute the driver locally and render the GDI output 2101 (EMF) into the printer-specific format on their own. 2102 </para></listitem> 2103 2104 <listitem><para>Send the GDI output (EMF) to the server, where the 2105 driver is executed to render the printer-specific output. 2106 </para></listitem> 2107</itemizedlist> 2108 2109<para> 2110Both print paths are shown in the flowcharts in <link linkend="small11"> 2111Print Driver Execution on the Client</link>, and 2112<link linkend="small12">Print Driver Execution on the Server</link>. 2113</para> 2114</sect2> 2115 2116<sect2> 2117<title>Driver Execution on the Client</title> 2118 2119<para> 2120In the first case, the print server must spool the file as raw, meaning it shouldn't touch the job file and try 2121to convert it in any way. This is what a traditional UNIX-based print server can do too, and at a better 2122performance and more reliably than an NT print server. This is what most Samba administrators probably are 2123familiar with. One advantage of this setup is that this <quote>spooling-only</quote> print server may be used 2124even if no driver(s) for UNIX is available. It is sufficient to have the Windows client drivers available and 2125installed on the clients. This is illustrated in <link linkend="small11">the Print Driver Execution on the 2126Client diagram</link>. 2127</para> 2128 2129<figure id="small11"> 2130 <title>Print Driver Execution on the Client.</title> 2131 <imagefile>11small</imagefile> 2132</figure> 2133 2134</sect2> 2135 2136<sect2> 2137<title>Driver Execution on the Server</title> 2138 2139 2140<para> 2141<indexterm><primary>PostScript</primary></indexterm> 2142<indexterm><primary>PCL</primary></indexterm> 2143<indexterm><primary>ESC/P</primary></indexterm> 2144<indexterm><primary>EMF</primary></indexterm> 2145<indexterm><primary>GDI</primary></indexterm> 2146The other path executes the printer driver on the server. The client transfers print files in EMF format to 2147the server. The server uses the PostScript, PCL, ESC/P, or other driver to convert the EMF file into the 2148printer-specific language. It is not possible for UNIX to do the same. Currently, there is no program or 2149method to convert a Windows client's GDI output on a UNIX server into something a printer could understand. 2150This is illustrated in <link linkend="small12">the Print Driver Execution on the Server diagram</link>. 2151</para> 2152 2153 <figure id="small12"> 2154 <title>Print Driver Execution on the Server.</title> 2155 <imagefile>12small</imagefile> 2156 </figure> 2157 2158<para> 2159However, something similar is possible with CUPS, so read on. 2160</para> 2161</sect2> 2162</sect1> 2163 2164<sect1> 2165<title>Network Printing (Windows Clients and UNIX/Samba Print 2166Servers)</title> 2167 2168<para> 2169Since UNIX print servers <emphasis>cannot</emphasis> execute the Win32 2170program code on their platform, the picture is somewhat 2171different. However, this does not limit your options all that 2172much. On the contrary, you may have a way here to implement printing 2173features that are not possible otherwise. 2174</para> 2175 2176<sect2> 2177<title>From Windows Clients to a CUPS/Samba Print Server</title> 2178 2179<para> 2180Here is a simple recipe showing how you can take advantage of CUPS's 2181powerful features for the benefit of your Windows network printing 2182clients: 2183</para> 2184 2185<itemizedlist> 2186 <listitem><para>Let the Windows clients send PostScript to the CUPS 2187 server.</para></listitem> 2188 2189 <listitem><para>Let the CUPS server render the PostScript into device-specific raster format.</para></listitem> 2190</itemizedlist> 2191 2192<para> 2193This requires the clients to use a PostScript driver (even if the 2194printer is a non-PostScript model. It also requires that you have a 2195driver on the CUPS server. 2196</para> 2197 2198<para> 2199First, to enable CUPS-based printing through Samba, the following options should be set in your &smb.conf; 2200file <parameter>[global]</parameter> section: 2201</para> 2202 2203<smbconfblock> 2204<smbconfoption name="printing">cups</smbconfoption> 2205<smbconfoption name="printcap">cups</smbconfoption> 2206</smbconfblock> 2207 2208<para> 2209When these parameters are specified, all manually set print directives (like <smbconfoption name="print 2210command"/> or <smbconfoption name="lppause command"/>) in &smb.conf; (as well as in Samba itself) will be 2211ignored. Instead, Samba will directly interface with CUPS through its application program interface (API), as 2212long as Samba has been compiled with CUPS library (libcups) support. If Samba has not been compiled with CUPS 2213support, and if no other print commands are set up, then printing will use the <emphasis>System V</emphasis> 2214AT&T command set, with the -oraw option automatically passing through (if you want your own defined print 2215commands to work with a Samba server that has CUPS support compiled in, simply use <smbconfoption 2216name="classicalprinting">sysv</smbconfoption>). This is illustrated in <link linkend="f13small">the Printing via 2217CUPS/Samba Server diagram</link>. 2218</para> 2219 2220 <figure id="f13small"> 2221 <title>Printing via CUPS/Samba Server.</title> 2222 <imagefile>13small</imagefile> 2223 </figure> 2224</sect2> 2225 2226<sect2> 2227<title>Samba Receiving Job-Files and Passing Them to CUPS</title> 2228 2229<para> 2230Samba <emphasis>must</emphasis> use its own spool directory (it is set by a line similar to <smbconfoption 2231name="path">/var/spool/samba</smbconfoption>, in the <smbconfsection name="[printers]"/> or <smbconfsection 2232name="[printername]"/> section of &smb.conf;). Samba receives the job in its own spool space and passes it 2233into the spool directory of CUPS (the CUPS spool directory is set by the <parameter>RequestRoot</parameter> 2234directive in a line that defaults to <parameter>RequestRoot /var/spool/cups</parameter>). CUPS checks the 2235access rights of its spool directory and resets it to healthy values with every restart. We have seen quite a 2236few people who used a common spooling space for Samba and CUPS, and struggled for weeks with this 2237<quote>problem.</quote> 2238</para> 2239 2240<para> 2241A Windows user authenticates only to Samba (by whatever means is 2242configured). If Samba runs on the same host as CUPS, you only need to 2243allow <quote>localhost</quote> to print. If it runs on different machines, you 2244need to make sure the Samba host gets access to printing on CUPS. 2245</para> 2246</sect2> 2247</sect1> 2248 2249<sect1> 2250<title>Network PostScript RIP</title> 2251 2252<para> 2253This section discusses the use of CUPS filters on the server &smbmdash; configuration where 2254clients make use of a PostScript driver with CUPS-PPDs. 2255</para> 2256 2257 2258<para> 2259<indexterm><primary>PostScript</primary></indexterm> 2260<indexterm><primary>PCL</primary></indexterm> 2261<indexterm><primary>PJL</primary></indexterm> 2262PPDs can control all print device options. They are usually provided by the manufacturer &smbmdash; if you own 2263a PostScript printer, that is. PPD files are always a component of PostScript printer drivers on MS Windows or 2264Apple Mac OS systems. They are ASCII files containing user-selectable print options, mapped to appropriate 2265PostScript, PCL, or PJL commands for the target printer. Printer driver GUI dialogs translate these options 2266<quote>on the fly</quote> into buttons and drop-down lists for the user to select. 2267</para> 2268 2269<para> 2270CUPS can load, without any conversions, the PPD file from any Windows (NT is recommended) PostScript driver 2271and handle the options. There is a Web browser interface to the print options (select <ulink noescape="1" 2272url="http://localhost:631/printers/">http://localhost:631/printers/</ulink> and click on one 2273<guibutton>Configure Printer</guibutton> button to see it) or a command line interface (see <command>man 2274lpoptions</command> or see if you have <command>lphelp</command> on your system). There are also some 2275different GUI front-ends on Linux/UNIX, which can present PPD options to users. PPD options are normally meant 2276to be evaluated by the PostScript RIP on the real PostScript printer. 2277</para> 2278 2279<sect2> 2280<title>PPDs for Non-PS Printers on UNIX</title> 2281 2282 2283<para> 2284<indexterm><primary>PPD</primary></indexterm> 2285CUPS does not limit itself to <quote>real</quote> PostScript printers in its use of PPDs. The CUPS developers 2286have extended the scope of the PPD concept to also describe available device and driver options for 2287non-PostScript printers through CUPS-PPDs. 2288</para> 2289 2290<para> 2291This is logical, because CUPS includes a fully featured PostScript interpreter (RIP). This RIP is based on 2292Ghostscript. It can process all received PostScript (and additionally many other file formats) from clients. 2293All CUPS-PPDs geared to non-PostScript printers contain an additional line, starting with the keyword 2294<parameter>*cupsFilter</parameter>. This line tells the CUPS print system which printer-specific filter to use 2295for the interpretation of the supplied PostScript. Thus CUPS lets all its printers appear as PostScript 2296devices to its clients, because it can act as a PostScript RIP for those printers, processing the received 2297PostScript code into a proper raster print format. 2298</para> 2299</sect2> 2300 2301<sect2> 2302<title>PPDs for Non-PS Printers on Windows</title> 2303 2304<para> 2305<indexterm><primary>PPD</primary></indexterm> 2306CUPS-PPDs can also be used on Windows clients, on top of a <quote>core</quote> PostScript driver (now 2307recommended is the CUPS PostScript Driver for Windows NT/200x/XP; you can also use the Adobe one, with 2308limitations). This feature enables CUPS to do a few tricks no other spooler can do: 2309</para> 2310 2311<itemizedlist> 2312 <listitem><para> 2313 Act as a networked PostScript RIP handling print files from all client platforms in a uniform way. 2314 </para></listitem> 2315 2316 <listitem><para> 2317 Act as a central accounting and billing server, since all files are passed through the pstops filter and are therefore 2318 logged in the CUPS <filename>page_log</filename> file. <emphasis>Note:</emphasis> this cannot happen with 2319 <quote>raw</quote> print jobs, which always remain unfiltered per definition. 2320 </para></listitem> 2321 2322 <listitem><para> 2323 Enable clients to consolidate on a single PostScript driver, even for many different target printers. 2324 </para></listitem> 2325</itemizedlist> 2326 2327<para> 2328Using CUPS PPDs on Windows clients enables them to control all print job settings just as a UNIX client can do. 2329</para> 2330</sect2> 2331</sect1> 2332 2333<sect1> 2334<title>Windows Terminal Servers (WTS) as CUPS Clients</title> 2335 2336<para> 2337This setup may be of special interest to people experiencing major problems in WTS environments. WTS often 2338need a multitude of non-PostScript drivers installed to run their clients' variety of different printer 2339models. This often imposes the price of much increased instability. 2340</para> 2341 2342<sect2> 2343<title>Printer Drivers Running in <quote>Kernel Mode</quote> Cause Many 2344Problems</title> 2345 2346<para> 2347Windows NT printer drivers, which run in <quote>kernel mode</quote>, introduce a high risk for the stability 2348of the system if the driver is not really stable and well-tested. And there are a lot of bad drivers out 2349there! Especially notorious is the example of the PCL printer driver that had an additional sound module 2350running to notify users via soundcard of their finished jobs. Do I need to say that this one was also reliably 2351causing <quote>blue screens of death</quote> on a regular basis? 2352</para> 2353 2354<para> 2355PostScript drivers are generally well-tested. They are not known to cause any problems, even though they also 2356run in kernel mode. This might be because until now there have been only two different PostScript drivers: the 2357one from Adobe and the one from Microsoft. Both are well-tested and are as stable as you can imagine on 2358Windows. The CUPS driver is derived from the Microsoft one. 2359</para> 2360</sect2> 2361 2362<sect2> 2363<title>Workarounds Impose Heavy Limitations</title> 2364 2365<para> 2366In an attempt to work around problems, site administrators have resorted to restricting the 2367allowed drivers installed on their WTS to one generic PCL and one PostScript driver. This, however, restricts 2368the number of printer options available for clients to use. Often they can't get out more than simplex 2369prints from one standard paper tray, while their devices could do much better if driven by a different driver! 2370</para> 2371</sect2> 2372 2373<sect2> 2374<title>CUPS: A <quote>Magical Stone</quote>?</title> 2375 2376<para> 2377<indexterm><primary>PPD</primary></indexterm> 2378<indexterm><primary>PostScript</primary></indexterm> 2379Using a PostScript driver, enabled with a CUPS-PPD, seems to be a very elegant way to overcome all these 2380shortcomings. There are, depending on the version of Windows OS you use, up to three different PostScript 2381drivers now available: Adobe, Microsoft, and CUPS PostScript drivers. None of them is known to cause major 2382stability problems on WTS (even if used with many different PPDs). The clients will be able to (again) choose 2383paper trays, duplex printing, and other settings. However, there is a certain price for this too: a CUPS 2384server acting as a PostScript RIP for its clients requires more CPU and RAM than when just acting as a 2385<quote>raw spooling</quote> device. Plus, this setup is not yet widely tested, although the first feedbacks 2386look very promising. 2387</para> 2388</sect2> 2389 2390<sect2> 2391<title>PostScript Drivers with No Major Problems, Even in Kernel 2392Mode</title> 2393 2394<para> 2395<indexterm><primary>DDK</primary></indexterm> 2396<indexterm><primary>W32X86</primary></indexterm> 2397<indexterm><primary>PostScript</primary></indexterm> 2398<indexterm><primary>Visual Studio</primary></indexterm> 2399<indexterm><primary>Microsoft driver</primary></indexterm> 2400<indexterm><primary>Adobe</primary></indexterm> 2401More recent printer drivers on W200x and XP no longer run in kernel mode (unlike Windows NT). However, both 2402operating systems can still use the NT drivers, running in kernel mode (you can roughly tell which is which as 2403the drivers in subdirectory <quote>2</quote> of <quote>W32X86</quote> are <quote>old</quote> ones). As was 2404said before, the Adobe as well as the Microsoft PostScript drivers are not known to cause any stability 2405problems. The CUPS driver is derived from the Microsoft one. There is a simple reason for this: the MS DDK 2406(Device Development Kit) for Windows NT (which used to be available at no cost to licensees of Visual Studio) 2407includes the source code of the Microsoft driver, and licensees of Visual Studio are allowed to use and modify 2408it for their own driver development efforts. This is what the CUPS people have done. The license does not 2409allow them to publish the whole of the source code. However, they have released the <quote>diff</quote> under 2410the GPL, and if you are the owner of an <quote>MS DDK for Windows NT,</quote> you can check the driver 2411yourself. 2412</para> 2413</sect2> 2414</sect1> 2415 2416<sect1> 2417<title>Configuring CUPS for Driver Download</title> 2418 2419<para> 2420As we have said before, all previously known methods to prepare client printer drivers on the Samba server for 2421download and Point'n'Print convenience of Windows workstations are working with CUPS, too. These methods were 2422described in <link linkend="classicalprinting">Classical Printing</link>. In reality, this is a pure Samba 2423business and relates only to the Samba-Windows client relationship. 2424</para> 2425 2426<sect2> 2427<title><emphasis>cupsaddsmb</emphasis>: The Unknown Utility</title> 2428 2429 2430<para> 2431<indexterm><primary>cupsaddsmb</primary></indexterm> 2432The <parameter>cupsaddsmb</parameter> utility (shipped with all current CUPS versions) is an alternative 2433method to transfer printer drivers into the Samba <smbconfsection name="[print$]"/> share. Remember, this 2434share is where clients expect drivers deposited and set up for download and installation. It makes the sharing 2435of any (or all) installed CUPS printers quite easy. <command>cupsaddsmb</command> can use the Adobe PostScript 2436driver as well as the newly developed CUPS PostScript driver for Windows NT/200x/XP. 2437<parameter>cupsaddsmb</parameter> does <emphasis>not</emphasis> work with arbitrary vendor printer drivers, 2438but only with the <emphasis>exact</emphasis> driver files that are named in its man page. 2439</para> 2440 2441<para> 2442The CUPS printer driver is available from the CUPS download site. Its package name is 2443<filename>cups-samba-[version].tar.gz</filename>. It is preferred over the Adobe drivers because it has a 2444number of advantages: 2445</para> 2446 2447<itemizedlist> 2448 <listitem><para>It supports a much more accurate page accounting.</para></listitem> 2449 2450 <listitem><para>It supports banner pages and page labels on all printers.</para></listitem> 2451 2452 <listitem><para>It supports the setting of a number of job IPP attributes 2453 (such as job priority, page label, and job billing).</para></listitem> 2454</itemizedlist> 2455 2456<para> 2457However, currently only Windows NT, 2000, and XP are supported by the 2458CUPS drivers. You will also need to get the respective part of the Adobe driver 2459if you need to support Windows 95, 98, and Me clients. 2460</para> 2461</sect2> 2462 2463<sect2> 2464<title>Prepare Your &smb.conf; for <command>cupsaddsmb</command></title> 2465 2466<para> 2467Prior to running <command>cupsaddsmb</command>, you need the settings in 2468&smb.conf; as shown in <link linkend="cupsadd-ex">the &smb.conf; for cupsaddsmb Usage</link>. 2469</para> 2470 2471<example id="cupsadd-ex"> 2472<title>smb.conf for cupsaddsmb Usage</title> 2473<smbconfblock> 2474<smbconfsection name="[global]"/> 2475<smbconfoption name="load printers">yes</smbconfoption> 2476<smbconfoption name="printing">cups</smbconfoption> 2477<smbconfoption name="printcap name">cups</smbconfoption> 2478 2479<smbconfsection name="[printers]"/> 2480<smbconfoption name="comment">All Printers</smbconfoption> 2481<smbconfoption name="path">/var/spool/samba</smbconfoption> 2482<smbconfoption name="browseable">no</smbconfoption> 2483<smbconfcomment>setting depends on your requirements</smbconfcomment> 2484<smbconfoption name="guest ok">yes</smbconfoption> 2485<smbconfoption name="writable">no</smbconfoption> 2486<smbconfoption name="printable">yes</smbconfoption> 2487<smbconfoption name="printer admin">root</smbconfoption> 2488 <smbconfsection name="[print$]"/> 2489<smbconfoption name="comment">Printer Drivers</smbconfoption> 2490<smbconfoption name="path">/etc/samba/drivers</smbconfoption> 2491<smbconfoption name="browseable">yes</smbconfoption> 2492<smbconfoption name="guest ok">no</smbconfoption> 2493<smbconfoption name="read only">yes</smbconfoption> 2494<smbconfoption name="write list">root, @smbprintadm</smbconfoption> 2495</smbconfblock> 2496</example> 2497</sect2> 2498 2499<sect2> 2500<title>CUPS <quote>PostScript Driver for Windows NT/200x/XP</quote></title> 2501 2502<para> 2503<indexterm><primary>PostScript</primary></indexterm> 2504CUPS users may get the exact same package from <ulink noescape="1" 2505url="http://www.cups.org/software.html">http://www.cups.org/software.html</ulink>. It is a separate package 2506from the CUPS-based software files, tagged as CUPS 1.1.x Windows NT/200x/XP Printer Driver for Samba (tar.gz, 2507192k). The filename to download is <filename>cups-samba-1.1.x.tar.gz</filename>. Upon untar and unzipping, it 2508will reveal these files: 2509<screen> 2510&rootprompt;<userinput>tar xvzf cups-samba-1.1.19.tar.gz</userinput> 2511cups-samba.install 2512cups-samba.license 2513cups-samba.readme 2514cups-samba.remove 2515cups-samba.ss 2516</screen></para> 2517 2518<para> 2519<indexterm><primary>ESP</primary><secondary>meta packager</secondary></indexterm> 2520<indexterm><primary>EPM</primary><see>ESP meta packager</see></indexterm> 2521These have been packaged with the ESP meta-packager software EPM. The <filename>*.install</filename> and 2522<filename>*.remove</filename> files are simple shell scripts, which untar the <filename>*.ss</filename> (the 2523<filename>*.ss</filename> is nothing else but a tar archive, which can be untarred by <quote>tar</quote> too). 2524Then it puts the content into <filename>/usr/share/cups/drivers/</filename>. This content includes three 2525files: 2526<screen> 2527&rootprompt;<userinput>tar tv cups-samba.ss</userinput> 2528cupsdrvr.dll 2529cupsui.dll 2530cups.hlp 2531</screen></para> 2532 2533<para> 2534The <parameter>cups-samba.install</parameter> shell scripts are easy to 2535handle: 2536<screen> 2537&rootprompt;<userinput>./cups-samba.install</userinput> 2538[....] 2539Installing software... 2540Updating file permissions... 2541Running post-install commands... 2542Installation is complete. 2543</screen></para> 2544 2545<para> 2546The script should automatically put the driver files into the 2547<filename>/usr/share/cups/drivers/</filename> directory: 2548<screen> 2549&rootprompt;<userinput>cp /usr/share/drivers/cups.hlp /usr/share/cups/drivers/</userinput> 2550</screen></para> 2551 2552<warning><para> 2553Due to a bug, one recent CUPS release puts the <filename>cups.hlp</filename> driver file 2554into<filename>/usr/share/drivers/</filename> instead of <filename>/usr/share/cups/drivers/</filename>. To work 2555around this, copy/move the file (after running the <command>./cups-samba.install</command> script) manually to 2556the correct place. 2557</para></warning> 2558 2559<para> 2560<indexterm><primary>DDK</primary></indexterm> 2561This new CUPS PostScript driver is currently binary only, but free of charge. No complete source code is 2562provided (yet). The reason is that it has been developed with the help of the Microsoft DDK and compiled with 2563Microsoft Visual Studio 6. Driver developers are not allowed to distribute the whole of the source code as 2564free software. However, CUPS developers released the <quote>diff</quote> in source code under the GPL, so 2565anybody with a license for Visual Studio and a DDK will be able to compile for himself or herself. 2566</para> 2567</sect2> 2568 2569<sect2> 2570<title>Recognizing Different Driver Files</title> 2571 2572<para> 2573The CUPS drivers do not support the older Windows 95/98/Me, but only the Windows NT/2000/XP client. 2574</para> 2575 2576<para>Windows NT, 2000, and XP are supported by:</para> 2577 2578<itemizedlist> 2579 <listitem><para>cups.hlp</para></listitem> 2580 <listitem><para>cupsdrvr.dll</para></listitem> 2581 <listitem><para>cupsui.dll</para></listitem> 2582</itemizedlist> 2583 2584<para> 2585Adobe drivers are available for the older Windows 95/98/Me as well as 2586for Windows NT/2000/XP clients. The set of files is different from the 2587different platforms. 2588</para> 2589 2590<para>Windows 95, 98, and ME are supported by:</para> 2591 2592<itemizedlist> 2593 <listitem><para>ADFONTS.MFM</para></listitem> 2594 <listitem><para>ADOBEPS4.DRV</para></listitem> 2595 <listitem><para>ADOBEPS4.HLP</para></listitem> 2596 <listitem><para>DEFPRTR2.PPD</para></listitem> 2597 <listitem><para>ICONLIB.DLL</para></listitem> 2598 <listitem><para>PSMON.DLL</para></listitem> 2599</itemizedlist> 2600 2601<para>Windows NT, 2000, and XP are supported by:</para> 2602 2603<itemizedlist> 2604 <listitem><para>ADOBEPS5.DLL</para></listitem> 2605 <listitem><para>ADOBEPSU.DLL</para></listitem> 2606 <listitem><para>ADOBEPSU.HLP</para></listitem> 2607</itemizedlist> 2608 2609<note><para> 2610<indexterm><primary>Adobe driver files</primary></indexterm> 2611If both the Adobe driver files and the CUPS driver files for the support of Windows NT/200x/XP are presently 2612installed on the server, the Adobe files will be ignored and the CUPS files will be used. If you prefer 2613&smbmdash; for whatever reason &smbmdash; to use Adobe-only drivers, move away the three CUPS driver files. 2614The Windows 9x/Me clients use the Adobe drivers in any case. 2615</para></note> 2616</sect2> 2617 2618<sect2> 2619<title>Acquiring the Adobe Driver Files</title> 2620 2621<para> 2622Acquiring the Adobe driver files seems to be unexpectedly difficult for many users. They are not available on 2623the Adobe Web site as single files, and the self-extracting and/or self-installing Windows-.exe is not easy to 2624locate either. You probably need to use the included native installer and run the installation process on one 2625client once. This will install the drivers (and one generic PostScript printer) locally on the client. When 2626they are installed, share the generic PostScript printer. After this, the client's <smbconfsection 2627name="[print$]"/> share holds the Adobe files, which you can get with smbclient from the CUPS host. 2628</para> 2629</sect2> 2630 2631<sect2> 2632<title>ESP Print Pro PostScript Driver for Windows NT/200x/XP</title> 2633 2634<para> 2635<indexterm><primary>ESP</primary><secondary>Print Pro</secondary></indexterm> 2636Users of the ESP Print Pro software are able to install the ESP print drivers package as an alternative to the 2637Adobe PostScript drivers. To do so, retrieve the driver files from the normal download area of the ESP Print 2638Pro software at <ulink noescape="1" url="http://www.easysw.com/software.html">Easy Software</ulink> web site. 2639You need to locate the link labeled <quote>SAMBA</quote> among the <guilabel>Download Printer Drivers for ESP 2640Print Pro 4.x</guilabel> area and download the package. Once installed, you can prepare any driver by simply 2641highlighting the printer in the Printer Manager GUI and selecting <guilabel>Export Driver...</guilabel> from 2642the menu. Of course, you need to have prepared Samba beforehand to handle the driver files; that is, set up 2643the <smbconfsection name="[print$]"/> share, and so on. The ESP Print Pro package includes the CUPS driver 2644files as well as a (licensed) set of Adobe drivers for the Windows 95/98/Me client family. 2645</para> 2646</sect2> 2647 2648<sect2> 2649<title>Caveats to Be Considered</title> 2650 2651 2652<para> 2653<indexterm><primary>cupsaddsmb</primary></indexterm> 2654<indexterm><primary>cups.hlp</primary></indexterm> 2655<indexterm><primary>WIN40</primary></indexterm> 2656<indexterm><primary>W32X86</primary></indexterm> 2657Once you have run the install script (and possibly manually moved the <filename>cups.hlp</filename> file to 2658<filename>/usr/share/cups/drivers/</filename>), the driver is ready to be put into Samba's <smbconfsection 2659name="[print$]"/> share (which often maps to <filename>/etc/samba/drivers/</filename> and contains a 2660subdirectory tree with <emphasis>WIN40</emphasis> and <emphasis>W32X86</emphasis> branches). You do this by 2661running <command>cupsaddsmb</command> (see also <command>man cupsaddsmb</command> for CUPS since release 26621.1.16). 2663</para> 2664 2665<tip><para> 2666<indexterm><primary>Single Sign-On</primary></indexterm> 2667<indexterm><primary>Domain Controller</primary></indexterm> 2668You may need to put root into the smbpasswd file by running <command>smbpasswd</command>; this is especially 2669important if you should run this whole procedure for the first time and are not working in an environment 2670where everything is configured for <emphasis>single sign-on</emphasis> to a Windows Domain Controller. 2671</para></tip> 2672 2673<para> 2674Once the driver files are in the <smbconfsection name="[print$]"/> share and are initialized, they are ready 2675to be downloaded and installed by the Windows NT/200x/XP clients. 2676</para> 2677 2678<note><para> 2679Win 9x/Me clients will not work with the CUPS PostScript driver. For these you still need to use the 2680<filename>ADOBE*.*</filename> drivers, as previously stated. 2681</para></note> 2682 2683<note> 2684<para> 2685It is not harmful if you still have the <filename>ADOBE*.*</filename> driver files from previous installations 2686in the <filename>/usr/share/cups/drivers/</filename> directory. The new <command>cupsaddsmb</command> (from 26871.1.16) will automatically prefer its own drivers if it finds both. 2688</para></note> 2689 2690<note><para> 2691<indexterm><primary>"Printers" folder</primary></indexterm> 2692<indexterm><primary>Adobe PostScript</primary></indexterm> 2693Should your Windows clients have had the old <filename>ADOBE*.*</filename> files for the Adobe PostScript 2694driver installed, the download and installation of the new CUPS PostScript driver for Windows NT/200x/XP will 2695fail at first. You need to wipe the old driver from the clients first. It is not enough to 2696<quote>delete</quote> the printer, because the driver files will still be kept by the clients and re-used if 2697you try to re-install the printer. To really get rid of the Adobe driver files on the clients, open the 2698<guilabel>Printers</guilabel> folder (possibly via <guilabel>Start -> Settings -> Control Panel -> 2699Printers</guilabel>), right-click on the folder background, and select <guimenuitem>Server 2700Properties</guimenuitem>. When the new dialog opens, select the <guilabel>Drivers</guilabel> tab. On the list 2701select the driver you want to delete and click the <guilabel>Delete</guilabel> button. This will only work if 2702there is not one single printer left that uses that particular driver. You need to <quote>delete</quote> all 2703printers using this driver in the <guilabel>Printers</guilabel> folder first. You will need Administrator 2704privileges to do this. 2705</para></note> 2706 2707<note><para> 2708<indexterm><primary>rpcclient</primary><secondary>setdriver</secondary></indexterm> 2709<indexterm><primary>CUPS PostScript</primary></indexterm> 2710Once you have successfully downloaded the CUPS PostScript driver to a client, you can easily switch all 2711printers to this one by proceeding as described in <link linkend="classicalprinting">Classical Printing 2712Support</link>. Either change a driver for an existing printer by running the <guilabel>Printer 2713Properties</guilabel> dialog, or use <command>rpcclient</command> with the <command>setdriver</command> 2714subcommand. 2715</para></note> 2716</sect2> 2717 2718<sect2> 2719<title>Windows CUPS PostScript Driver Versus Adobe Driver</title> 2720 2721<para> 2722Are you interested in a comparison between the CUPS and the Adobe PostScript drivers? For our purposes, these 2723are the most important items that weigh in favor of CUPS: 2724</para> 2725 2726<itemizedlist> 2727 <listitem><para>No hassle with the Adobe EULA.</para></listitem> 2728 2729 <listitem><para>No hassle with the question, <quote>Where do I 2730 get the ADOBE*.* driver files?</quote></para></listitem> 2731 2732 <listitem><para> 2733 <indexterm><primary>PJL</primary></indexterm> 2734 The Adobe drivers (on request of the printer PPD associated with them) often put a PJL header in front of the 2735 main PostScript part of the print file. Thus, the print file starts with <parameter><1B 2736 >%-12345X</parameter> or <parameter><escape>%-12345X</parameter> instead of 2737 <parameter>%!PS</parameter>. This leads to the CUPS daemon autotyping the incoming file as a print-ready file, 2738 not initiating a pass through the <parameter>pstops</parameter> filter (to speak more technically, it is not 2739 regarded as the generic MIME-type <indexterm><primary>application/postscript</primary></indexterm> 2740 <parameter>application/postscript</parameter>, but as the more special MIME type 2741 <indexterm><primary>application/cups.vnd-postscript</primary></indexterm> 2742 <parameter>application/cups.vnd-postscript</parameter>), which therefore also leads to the page accounting in 2743 <parameter>/var/log/cups/page_log</parameter> not receiving the exact number of pages; instead the dummy page 2744 number of <quote>1</quote> is logged in a standard setup). 2745 </para></listitem> 2746 2747 <listitem><para>The Adobe driver has more options to misconfigure the 2748<indexterm><primary>Adobe driver</primary></indexterm> 2749 PostScript generated by it (like setting it inadvertently to 2750 <guilabel>Optimize for Speed</guilabel> instead of 2751 <guilabel>Optimize for Portability</guilabel>, which 2752 could lead to CUPS being unable to process it).</para></listitem> 2753 2754 <listitem><para>The CUPS PostScript driver output sent by Windows 2755<indexterm><primary>CUPS PostScript driver</primary></indexterm> 2756 clients to the CUPS server is guaranteed to autotype 2757 as the generic MIME type <parameter>application/postscript</parameter>, 2758 thus passing through the CUPS <parameter>pstops</parameter> filter and logging the 2759 correct number of pages in the <filename>page_log</filename> for 2760 accounting and quota purposes.</para></listitem> 2761 2762 <listitem><para> 2763 <indexterm><primary>banner pages</primary></indexterm> 2764 The CUPS PostScript driver supports the sending of additional standard (IPP) print options by Windows 2765 NT/200x/XP clients. Such additional print options are naming the CUPS standard <emphasis>banner 2766 pages</emphasis> (or the custom ones, should they be installed at the time of driver download), using the CUPS 2767 page-label option, setting a job priority, and setting the scheduled time of printing (with the option to 2768 support additional useful IPP job attributes in the future). 2769 </para></listitem> 2770 2771 <listitem><para>The CUPS PostScript driver supports the inclusion of 2772 the new <parameter>*cupsJobTicket</parameter> comments at the 2773 beginning of the PostScript file (which could be used in the future 2774 for all sorts of beneficial extensions on the CUPS side, but which will 2775 not disturb any other applications because they will regard it as a comment 2776 and simply ignore it).</para></listitem> 2777 2778 <listitem><para>The CUPS PostScript driver will be the heart of the 2779 fully fledged CUPS IPP client for Windows NT/200x/XP to be released soon 2780 (probably alongside the first beta release for CUPS 1.2).</para></listitem> 2781</itemizedlist> 2782 2783</sect2> 2784 2785<sect2> 2786<title>Run cupsaddsmb (Quiet Mode)</title> 2787 2788 2789<para> 2790<indexterm><primary>cupsaddsmb</primary></indexterm> 2791<indexterm><primary>point 'n' print</primary></indexterm> 2792The <command>cupsaddsmb</command> command copies the needed files into your <smbconfsection name="[print$]"/> 2793share. Additionally, the PPD associated with this printer is copied from <filename>/etc/cups/ppd/</filename> 2794to <smbconfsection name="[print$]"/>. There the files wait for convenient Windows client installations via 2795Point'n'Print. Before we can run the command successfully, we need to be sure that we can authenticate toward 2796Samba. If you have a small network, you are probably using user-level security (<smbconfoption 2797name="security">user</smbconfoption>). 2798</para> 2799 2800<para> 2801Here is an example of a successfully run <command>cupsaddsmb</command> command: 2802<indexterm><primary>banner pages</primary></indexterm> 2803<indexterm><primary>cupsaddsmb</primary></indexterm> 2804<screen> 2805&rootprompt;<userinput>cupsaddsmb -U root infotec_IS2027</userinput> 2806Password for root required to access localhost via Samba: <userinput>['secret']</userinput> 2807</screen></para> 2808 2809<para> 2810<indexterm><primary>cupsaddsmb</primary></indexterm> 2811To share <emphasis>all</emphasis> printers and drivers, use the 2812<option>-a</option> parameter instead of a printer name. Since 2813<command>cupsaddsmb</command> <quote>exports</quote> the printer drivers to Samba, it should be 2814obvious that it only works for queues with a CUPS driver associated. 2815</para> 2816</sect2> 2817 2818<sect2> 2819<title>Run cupsaddsmb with Verbose Output</title> 2820 2821 2822<para> 2823<indexterm><primary>cupsaddsmb</primary></indexterm> 2824Probably you want to see what's going on. Use the 2825<option>-v</option> parameter to get a more verbose output. The 2826output below was edited for better readability: all <quote>\</quote> at the end of 2827a line indicate that I inserted an artificial line break plus some 2828indentation here: 2829<indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm> 2830<indexterm><primary>rpcclient</primary><secondary>setdriver</secondary></indexterm> 2831<screen> 2832&rootprompt;<userinput>cupsaddsmb -U root -v infotec_2105</userinput> 2833Password for root required to access localhost via &example.server.samba;: 2834Running command: smbclient //localhost/print\$ -N -U'root%secret' \ 2835 -c 'mkdir W32X86; \ 2836 put /var/spool/cups/tmp/3e98bf2d333b5 W32X86/infotec_2105.ppd; \ 2837 put /usr/share/cups/drivers/cupsdrvr.dll W32X86/cupsdrvr.dll; \ 2838 put /usr/share/cups/drivers/cupsui.dll W32X86/cupsui.dll; \ 2839 put /usr/share/cups/drivers/cups.hlp W32X86/cups.hlp' 2840added interface ip=10.160.51.60 bcast=10.160.51.255 nmask=255.255.252.0 2841Domain=[CUPS-PRINT] OS=[UNIX] Server=[Samba 2.2.7a] 2842NT_STATUS_OBJECT_NAME_COLLISION making remote directory \W32X86 2843putting file /var/spool/cups/tmp/3e98bf2d333b5 as \W32X86/infotec_2105.ppd 2844putting file /usr/share/cups/drivers/cupsdrvr.dll as \W32X86/cupsdrvr.dll 2845putting file /usr/share/cups/drivers/cupsui.dll as \W32X86/cupsui.dll 2846putting file /usr/share/cups/drivers/cups.hlp as \W32X86/cups.hlp 2847 2848Running command: rpcclient localhost -N -U'root%secret' 2849 -c 'adddriver "Windows NT x86" \ 2850 "infotec_2105:cupsdrvr.dll:infotec_2105.ppd:cupsui.dll:cups.hlp:NULL: \ 2851 RAW:NULL"' 2852cmd = adddriver "Windows NT x86" \ 2853 "infotec_2105:cupsdrvr.dll:infotec_2105.ppd:cupsui.dll:cups.hlp:NULL: \ 2854 RAW:NULL" 2855Printer Driver infotec_2105 successfully installed. 2856 2857Running command: smbclient //localhost/print\$ -N -U'root%secret' \ 2858-c 'mkdir WIN40; \ 2859 put /var/spool/cups/tmp/3e98bf2d333b5 WIN40/infotec_2105.PPD; \ 2860 put /usr/share/cups/drivers/ADFONTS.MFM WIN40/ADFONTS.MFM; \ 2861 put /usr/share/cups/drivers/ADOBEPS4.DRV WIN40/ADOBEPS4.DRV; \ 2862 put /usr/share/cups/drivers/ADOBEPS4.HLP WIN40/ADOBEPS4.HLP; \ 2863 put /usr/share/cups/drivers/DEFPRTR2.PPD WIN40/DEFPRTR2.PPD; \ 2864 put /usr/share/cups/drivers/ICONLIB.DLL WIN40/ICONLIB.DLL; \ 2865 put /usr/share/cups/drivers/PSMON.DLL WIN40/PSMON.DLL;' 2866 added interface ip=10.160.51.60 bcast=10.160.51.255 nmask=255.255.252.0 2867 Domain=[CUPS-PRINT] OS=[UNIX] Server=[Samba 2.2.7a] 2868 NT_STATUS_OBJECT_NAME_COLLISION making remote directory \WIN40 2869 putting file /var/spool/cups/tmp/3e98bf2d333b5 as \WIN40/infotec_2105.PPD 2870 putting file /usr/share/cups/drivers/ADFONTS.MFM as \WIN40/ADFONTS.MFM 2871 putting file /usr/share/cups/drivers/ADOBEPS4.DRV as \WIN40/ADOBEPS4.DRV 2872 putting file /usr/share/cups/drivers/ADOBEPS4.HLP as \WIN40/ADOBEPS4.HLP 2873 putting file /usr/share/cups/drivers/DEFPRTR2.PPD as \WIN40/DEFPRTR2.PPD 2874 putting file /usr/share/cups/drivers/ICONLIB.DLL as \WIN40/ICONLIB.DLL 2875 putting file /usr/share/cups/drivers/PSMON.DLL as \WIN40/PSMON.DLL 2876 2877 Running command: rpcclient localhost -N -U'root%secret' \ 2878 -c 'adddriver "Windows 4.0" \ 2879 "infotec_2105:ADOBEPS4.DRV:infotec_2105.PPD:NULL:ADOBEPS4.HLP: \ 2880 PSMON.DLL:RAW:ADOBEPS4.DRV,infotec_2105.PPD,ADOBEPS4.HLP,PSMON.DLL, \ 2881 ADFONTS.MFM,DEFPRTR2.PPD,ICONLIB.DLL"' 2882 cmd = adddriver "Windows 4.0" "infotec_2105:ADOBEPS4.DRV:\ 2883 infotec_2105.PPD:NULL:ADOBEPS4.HLP:PSMON.DLL:RAW:ADOBEPS4.DRV,\ 2884 infotec_2105.PPD,ADOBEPS4.HLP,PSMON.DLL,ADFONTS.MFM,DEFPRTR2.PPD,\ 2885 ICONLIB.DLL" 2886 Printer Driver infotec_2105 successfully installed. 2887 2888 Running command: rpcclient localhost -N -U'root%secret' \ 2889 -c 'setdriver infotec_2105 infotec_2105' 2890 cmd = setdriver infotec_2105 infotec_2105 2891 Successfully set infotec_2105 to driver infotec_2105. 2892</screen></para> 2893 2894<warning><para> 2895You will see the root password for the Samba account printed on screen. 2896</para></warning> 2897 2898<para> 2899If you look closely, you'll discover your root password was transferred unencrypted over the wire, so beware! 2900Also, if you look further, you may discover error messages like NT_STATUS_OBJECT_NAME_COLLISION in the output. 2901This will occur when the directories WIN40 and W32X86 already existed in the <smbconfsection name="[print$]"/> 2902driver download share (from a previous driver installation). These are harmless warning messages. 2903</para> 2904</sect2> 2905 2906<sect2> 2907<title>Understanding cupsaddsmb</title> 2908 2909<para> 2910<indexterm><primary>cupsaddsmb</primary></indexterm> 2911What has happened? What did <command>cupsaddsmb</command> do? There are five stages of the procedure: 2912</para> 2913 2914<orderedlist> 2915 <listitem><para> 2916 <indexterm><primary>IPP</primary></indexterm> 2917 Call the CUPS server via IPP and request the driver files and the PPD file for the named printer.</para></listitem> 2918 2919 <listitem><para>Store the files temporarily in the local TEMPDIR (as defined in <filename>cupsd.conf</filename>).</para></listitem> 2920 2921 <listitem><para>Connect via smbclient to the Samba server's <smbconfsection name="[print$]"/> share and put the files into the 2922 share's WIN40 (for Windows 9x/Me) and W32X86 (for Windows NT/200x/XP) subdirectories.</para></listitem> 2923 2924 <listitem><para> 2925 <indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm> 2926 Connect via rpcclient to the Samba server and execute the <command>adddriver</command> command with the correct parameters. 2927 </para></listitem> 2928 2929 <listitem><para> 2930 <indexterm><primary>rpcclient</primary><secondary>setdriver</secondary></indexterm> 2931 Connect via rpcclient to the Samba server a second time and execute the <command>setdriver</command> command.</para></listitem> 2932</orderedlist> 2933 2934<note> 2935<para> 2936You can run the <command>cupsaddsmb</command> utility with parameters to specify one remote host as Samba host 2937and a second remote host as CUPS host. Especially if you want to get a deeper understanding, it is a good idea 2938to try it and see more clearly what is going on (though in real life most people will have their CUPS and 2939Samba servers run on the same host): 2940<screen> 2941&rootprompt;<userinput>cupsaddsmb -H sambaserver -h cupsserver -v printer</userinput> 2942</screen> 2943</para></note> 2944 2945</sect2> 2946 2947<sect2> 2948<title>How to Recognize If cupsaddsmb Completed Successfully</title> 2949 2950<para> 2951You <emphasis>must</emphasis> always check if the utility completed 2952successfully in all fields. You need at minimum these three messages 2953among the output: 2954</para> 2955 2956<orderedlist> 2957 <listitem><para><emphasis>Printer Driver infotec_2105 successfully 2958 installed.</emphasis> # (for the W32X86 == Windows NT/200x/XP 2959 architecture).</para></listitem> 2960 2961 <listitem><para><emphasis>Printer Driver infotec_2105 successfully 2962 installed.</emphasis> # (for the WIN40 == Windows 9x/Me 2963 architecture).</para></listitem> 2964 2965 <listitem><para><emphasis>Successfully set [printerXPZ] to driver 2966 [printerXYZ].</emphasis></para></listitem> 2967</orderedlist> 2968 2969<para> 2970These messages are probably not easily recognized in the general 2971output. If you run <command>cupsaddsmb</command> with the <option>-a</option> 2972parameter (which tries to prepare <emphasis>all</emphasis> active CUPS 2973printer drivers for download), you might miss if individual printer 2974drivers had problems installing properly. A redirection of the 2975output will help you analyze the results in retrospective. 2976</para> 2977 2978<para> 2979If you get: 2980<screen> 2981SetPrinter call failed! 2982result was WERR_ACCESS_DENIED 2983</screen> 2984it means that you might have set <smbconfoption name="use client driver">yes</smbconfoption> for this printer. 2985Setting it to <quote>no</quote> will solve the problem. Refer to the &smb.conf; man page for explanation of 2986the <parameter>use client driver</parameter>. 2987</para> 2988 2989<note><para> 2990It is impossible to see any diagnostic output if you do not run <command>cupsaddsmb</command> in verbose mode. 2991Therefore, we strongly recommend against use of the default quiet mode. It will hide any problems from you that 2992might occur. 2993</para></note> 2994</sect2> 2995 2996<sect2> 2997<title>cupsaddsmb with a Samba PDC</title> 2998 2999<para> 3000<indexterm><primary>cupsaddsmb</primary></indexterm> 3001<indexterm><primary>PDC</primary></indexterm> 3002Can't get the standard <command>cupsaddsmb</command> command to run on a Samba PDC? Are you asked for the 3003password credential again and again, and the command just will not take off at all? Try one of these 3004variations: 3005</para> 3006 3007<para><screen> 3008&rootprompt;<userinput>cupsaddsmb -U &example.workgroup;\\root -v printername</userinput> 3009&rootprompt;<userinput>cupsaddsmb -H &example.pdc.samba; -U &example.workgroup;\\root -v printername</userinput> 3010&rootprompt;<userinput>cupsaddsmb -H &example.pdc.samba; -U &example.workgroup;\\root -h cups-server -v printername</userinput> 3011</screen></para> 3012 3013<para> 3014(Note the two backslashes: the first one is required to <quote>escape</quote> the second one). 3015</para> 3016</sect2> 3017 3018<sect2> 3019<title>cupsaddsmb Flowchart</title> 3020 3021<para> 3022<indexterm><primary>cupsaddsmb</primary></indexterm> 3023<indexterm><primary>raw print</primary></indexterm> 3024<link linkend="small14">The cupsaddsmb Flowchart</link> shows a chart about the procedures, command flows, and 3025data flows of the <command>cupaddsmb</command> command. Note again: cupsaddsmb is 3026not intended to, and does not work with, raw print queues! 3027</para> 3028 3029 <figure id="small14"> 3030 <title>cupsaddsmb Flowchart.</title> 3031 <imagefile>14small</imagefile></figure> 3032</sect2> 3033 3034<sect2> 3035<title>Installing the PostScript Driver on a Client</title> 3036 3037<para> 3038<indexterm><primary>point'n'print</primary></indexterm> 3039<indexterm><primary>cupsaddsmb</primary></indexterm> 3040After <command>cupsaddsmb</command> is completed, your driver is prepared for the clients to use. Here are the 3041steps you must perform to download and install it via Point'n'Print. From a Windows client, browse to the 3042CUPS/Samba server: 3043</para> 3044 3045<itemizedlist> 3046 3047 <listitem><para> 3048 <indexterm><primary>"Printers" folder</primary></indexterm> 3049 Open the <guilabel>Printers</guilabel> share of Samba in Network Neighborhood.</para></listitem> 3050 3051 <listitem><para>Right-click on the printer in question.</para></listitem> 3052 3053 <listitem><para>From the opening context menu select 3054 <guimenuitem>Install...</guimenuitem> or 3055 <guimenuitem>Connect...</guimenuitem> (depending on the Windows version you use).</para></listitem> 3056</itemizedlist> 3057 3058<para> 3059After a few seconds, there should be a new printer in your client's <emphasis>local</emphasis> 3060<guilabel>Printers</guilabel> folder. On Windows XP it will follow a naming convention of 3061<emphasis>PrinterName on SambaServer</emphasis>. (In my current case it is infotec_2105 on kde-bitshop). If 3062you want to test it and send your first job from an application like Microsoft Word, 3063the new printer appears in a 3064<filename>\\SambaServer\PrinterName</filename> entry in the drop-down list of available printers. 3065</para> 3066 3067<para> 3068<indexterm><primary>PPD</primary></indexterm> 3069<indexterm><primary>Adobe PostScript driver</primary></indexterm> 3070<indexterm><primary>net use lpt1:</primary></indexterm> 3071<command>cupsaddsmb</command> will only reliably work with CUPS version 1.1.15 or higher and with Samba 3072version 2.2.4, or later. If it does not work, or if the automatic printer driver download to the clients does 3073not succeed, you can still manually install the CUPS printer PPD on top of the Adobe PostScript driver on 3074clients. Then point the client's printer queue to the Samba printer share for a UNC type of connection: 3075<screen> 3076&dosprompt;<userinput>net use lpt1: \\sambaserver\printershare /user:ntadmin</userinput> 3077</screen> 3078should you desire to use the CUPS networked PostScript RIP functions. (Note that user <quote>ntadmin</quote> 3079needs to be a valid Samba user with the required privileges to access the printershare.) This sets up the 3080printer connection in the traditional LanMan way (not using MS-RPC). 3081</para> 3082</sect2> 3083 3084<sect2 id="cups-avoidps1"> 3085<title>Avoiding Critical PostScript Driver Settings on the Client</title> 3086 3087<para> 3088Printing works, but there are still problems. Most jobs print well, some do not print at all. Some jobs have 3089problems with fonts, which do not look very good. Some jobs print fast and some are dead-slow. Many of these 3090problems can be greatly reduced or even completely eliminated if you follow a few guidelines. Remember, if 3091your print device is not PostScript-enabled, you are treating your Ghostscript installation on your CUPS host 3092with the output your client driver settings produce. Treat it well: 3093</para> 3094 3095<itemizedlist> 3096 <listitem><para> 3097 Avoid the PostScript Output Option: Optimize for Speed setting. Use the Optimize for Portability instead 3098 (Adobe PostScript driver).</para></listitem> 3099 3100 <listitem><para> 3101 Don't use the Page Independence: NO setting. Instead, use Page Independence: YES (CUPS PostScript Driver). 3102 </para></listitem> 3103 3104 <listitem><para> 3105 Recommended is the True Type Font Downloading Option: Native True Type over Automatic and Outline; 3106 you should by all means avoid Bitmap (Adobe PostScript Driver).</para></listitem> 3107 3108 <listitem><para> 3109 Choose True Type Font: Download as Softfont into Printer over the default Replace by Device 3110 Font (for exotic fonts, you may need to change it back to get a printout at all; Adobe).</para></listitem> 3111 3112 <listitem><para> 3113 Sometimes you can choose PostScript Language Level: in case of problems try 2 3114 instead of 3 (the latest ESP Ghostscript package handles Level 3 PostScript very well; Adobe). 3115 </para></listitem> 3116 3117 <listitem><para> 3118 Say Yes to PostScript Error Handler (Adobe).</para></listitem> 3119</itemizedlist> 3120 3121</sect2> 3122</sect1> 3123 3124<sect1> 3125<title>Installing PostScript Driver Files Manually Using rpcclient</title> 3126 3127<para> 3128Of course, you can run all the commands that are embedded into the 3129cupsaddsmb convenience utility yourself, one by one, and upload 3130and prepare the driver files for future client downloads. 3131</para> 3132 3133<orderedlist> 3134 <listitem><para>Prepare Samba (a CUPS print queue with the name of the 3135 printer should be there. We are providing the driver now).</para></listitem> 3136 3137 <listitem><para>Copy all files to <smbconfsection name="[print$]"/>.</para></listitem> 3138 3139 <listitem><para> 3140 <indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm> 3141 Run <command>rpcclient adddriver</command> 3142 (for each client architecture you want to support).</para></listitem> 3143 3144 <listitem><para> 3145 <indexterm><primary>rpcclient</primary><secondary>setdriver</secondary></indexterm> 3146 Run <command>rpcclient setdriver.</command></para></listitem> 3147</orderedlist> 3148 3149<para> 3150<indexterm><primary>rpcclient</primary><secondary>enumports</secondary></indexterm> 3151<indexterm><primary>rpcclient</primary><secondary>enumprinters</secondary></indexterm> 3152<indexterm><primary>rpcclient</primary><secondary>enumdrivers</secondary></indexterm> 3153<indexterm><primary>rpcclient</primary><secondary>setdriver</secondary></indexterm> 3154<indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm> 3155We are going to do this now. First, read the man page on <parameter>rpcclient</parameter> to get a first idea. 3156Look at all the printing-related subcommands: <command>enumprinters</command>, <command>enumdrivers</command>, 3157<command>enumports</command>, <command>adddriver</command>, and <command>setdriver</command> are among the 3158most interesting ones. <parameter>rpcclient</parameter> implements an important part of the MS-RPC protocol. 3159You can use it to query (and command) a Windows NT (or 200x/XP) PC, too. MS-RPC is used by Windows clients, 3160among other things, to benefit from the Point'n'Print features. Samba can now mimic this as well. 3161</para> 3162 3163<sect2> 3164<title>A Check of the rpcclient man Page</title> 3165 3166<para> 3167First let's check the <parameter>rpcclient</parameter> man page. Here are two relevant passages: 3168</para> 3169 3170<para> 3171<indexterm><primary>adddriver</primary></indexterm> 3172<indexterm><primary>AddPrinterDriver()</primary></indexterm> 3173<indexterm><primary>getdriverdir</primary></indexterm> 3174<command>adddriver <arch> <config></command> Execute an <command>AddPrinterDriver()</command> RPC 3175to install the printer driver information on the server. The driver files should already exist in the 3176directory returned by <command>getdriverdir</command>. Possible values for <parameter>arch</parameter> are the 3177same as those for the <command>getdriverdir</command> command. The <parameter>config</parameter> parameter is 3178defined as follows: 3179<screen> 3180Long Printer Name:\ 3181Driver File Name:\ 3182Data File Name:\ 3183Config File Name:\ 3184Help File Name:\ 3185Language Monitor Name:\ 3186Default Data Type:\ 3187Comma Separated list of Files 3188</screen></para> 3189 3190<para> 3191Any empty fields should be entered as the string <quote>NULL</quote>. 3192</para> 3193 3194<para> 3195Samba does not need to support the concept of print monitors, since these only apply to local printers whose 3196drivers can use a bidirectional link for communication. This field should be <quote>NULL</quote>. On a remote 3197NT print server, the print monitor for a driver must already be installed before adding the driver or else the 3198RPC will fail. 3199</para> 3200 3201<para> 3202<indexterm><primary>setdriver</primary></indexterm> 3203<indexterm><primary>SetPrinter()</primary></indexterm> 3204<command>setdriver <printername> <drivername></command> Execute a <command>SetPrinter()</command> 3205command to update the printer driver associated with an installed printer. The printer driver must already be 3206correctly installed on the print server. 3207</para> 3208 3209<para> 3210<indexterm><primary>enumprinters</primary></indexterm> 3211<indexterm><primary>enumdrivers</primary></indexterm> 3212See also the <command>enumprinters</command> and <command>enumdrivers</command> commands to 3213obtain a list of installed printers and drivers. 3214</para> 3215 3216</sect2> 3217 3218<sect2> 3219<title>Understanding the rpcclient man Page</title> 3220 3221<para> 3222<indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm> 3223The <emphasis>exact</emphasis> format isn't made too clear by the man page, since you have to deal with some 3224parameters containing spaces. Here is a better description for it. We have line-broken the command and 3225indicated the breaks with <quote>\</quote>. Usually you would type the command in one line without the line 3226breaks: 3227<screen> 3228adddriver "Architecture" \ 3229 "LongPrinterName:DriverFile:DataFile:ConfigFile:HelpFile:\ 3230 LanguageMonitorFile:DataType:ListOfFiles,Comma-separated" 3231</screen></para> 3232 3233<para> 3234What the man pages denote as a simple <parameter><config></parameter> keyword in reality consists of 3235eight colon-separated fields. The last field may take multiple (in some very insane cases, even 20 different 3236additional) files. This might sound confusing at first. What the man pages call the 3237<quote>LongPrinterName</quote> in reality should be called the <quote>Driver Name</quote>. You can name it 3238anything you want, as long as you use this name later in the <command>rpcclient ... setdriver</command> 3239command. For practical reasons, many name the driver the same as the printer. 3240</para> 3241 3242<para> 3243It isn't simple at all. I hear you asking: <quote>How do I know which files are Driver File</quote>, 3244<quote>Data File</quote>, <quote>Config File</quote>, <quote>Help File</quote> and <quote>Language Monitor 3245File in each case?</quote> For an answer, you may want to have a look at how a Windows NT box with a shared 3246printer presents the files to us. Remember that this whole procedure has to be developed by the Samba Team by 3247listening to the traffic caused by Windows computers on the wire. We may as well turn to a Windows box now and 3248access it from a UNIX workstation. We will query it with <command>rpcclient</command> to see what it tells us 3249and try to understand the man page more clearly. 3250</para> 3251</sect2> 3252 3253<sect2> 3254<title>Producing an Example by Querying a Windows Box</title> 3255 3256<para> 3257<indexterm><primary>rpcclient</primary><secondary>getdriver</secondary></indexterm> 3258<indexterm><primary>rpcclient</primary><secondary>getprinter</secondary></indexterm> 3259We could run <command>rpcclient</command> with a <command>getdriver</command> or a 3260<command>getprinter</command> subcommand (in level 3 verbosity) against it. Just sit down at a UNIX or Linux 3261workstation with the Samba utilities installed, then type the following command: 3262<screen> 3263&rootprompt;<userinput>rpcclient -U'user%secret' NT-SERVER -c 'getdriver printername 3'</userinput> 3264</screen></para> 3265 3266<para> 3267From the result it should become clear which is which. Here is an example from my installation: 3268<indexterm><primary>rpcclient</primary><secondary>getdriver</secondary></indexterm> 3269<screen> 3270&rootprompt;<userinput>rpcclient -U'Danka%xxxx' W200xSERVER \ 3271 -c'getdriver "DANKA InfoStream Virtual Printer" 3'</userinput> 3272 cmd = getdriver "DANKA InfoStream Virtual Printer" 3 3273 3274 [Windows NT x86] 3275 Printer Driver Info 3: 3276 Version: [2] 3277 Driver Name: [DANKA InfoStream] 3278 Architecture: [Windows NT x86] 3279 Driver Path: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\PSCRIPT.DLL] 3280 Datafile: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\INFOSTRM.PPD] 3281 Configfile: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\PSCRPTUI.DLL] 3282 Helpfile: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\PSCRIPT.HLP] 3283 3284 Dependentfiles: [] 3285 Dependentfiles: [] 3286 Dependentfiles: [] 3287 Dependentfiles: [] 3288 Dependentfiles: [] 3289 Dependentfiles: [] 3290 Dependentfiles: [] 3291 3292 Monitorname: [] 3293 Defaultdatatype: [] 3294</screen></para> 3295 3296<para> 3297Some printer drivers list additional files under the label <parameter>Dependentfiles</parameter>, and these 3298would go into the last field <parameter>ListOfFiles,Comma-separated</parameter>. For the CUPS PostScript 3299drivers, we do not need any (nor would we for the Adobe PostScript driver); therefore, the field will get a 3300<quote>NULL</quote> entry. 3301</para> 3302</sect2> 3303 3304<sect2> 3305<title>Requirements for adddriver and setdriver to Succeed</title> 3306 3307<para> 3308<indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm> 3309<indexterm><primary>cupsaddsmb</primary></indexterm> 3310<indexterm><primary>setdriver</primary></indexterm> 3311From the man page (and from the quoted output of <command>cupsaddsmb</command> above) it becomes clear that 3312you need to have certain conditions in order to make the manual uploading and initializing of the driver files 3313succeed. The two <command>rpcclient</command> subcommands (<command>adddriver</command> and 3314<command>setdriver</command>) need to encounter the following preconditions to complete successfully: 3315</para> 3316 3317<itemizedlist> 3318 <listitem><para>You are connected as <smbconfoption name="printer admin"/> or root (this is 3319 <emphasis>not</emphasis> the <quote>Printer Operators</quote> group in NT, but the <emphasis>printer 3320 admin</emphasis> group as defined in the <smbconfsection name="[global]"/> section of &smb.conf;). 3321 </para></listitem> 3322 3323 <listitem><para>Copy all required driver files to <filename>\\SAMBA\print$\w32x86</filename> and 3324 <filename>\\SAMBA\print$\win40</filename> as appropriate. They will end up in the <quote>0</quote> respective 3325 <quote>2</quote> subdirectories later. For now, <emphasis>do not</emphasis> put them there; they'll be 3326 automatically used by the <command>adddriver</command> subcommand. (If you use <command>smbclient</command> to 3327 put the driver files into the share, note that you need to escape the <quote>$</quote>: <command>smbclient 3328 //sambaserver/print\$ -U root.</command>)</para></listitem> 3329 3330 <listitem><para>The user you're connecting as must be able to write to 3331 the <smbconfsection name="[print$]"/> share and create 3332 subdirectories.</para></listitem> 3333 3334 <listitem><para>The printer you are going to set up for the Windows 3335 clients needs to be installed in CUPS already.</para></listitem> 3336 3337 <listitem><para> 3338 <indexterm><primary>rpcclient</primary><secondary>setdriver</secondary></indexterm> 3339 <indexterm><primary>rpcclient</primary><secondary>enumprinters</secondary></indexterm> 3340 The CUPS printer must be known to Samba; otherwise the <command>setdriver</command> subcommand fails with an 3341 NT_STATUS_UNSUCCESSFUL error. To check if the printer is known by Samba, you may use the 3342 <command>enumprinters</command> subcommand to <command>rpcclient</command>. A long-standing bug prevented a 3343 proper update of the printer list until every smbd process had received a SIGHUP or was restarted. Remember 3344 this in case you've created the CUPS printer just recently and encounter problems: try restarting Samba. 3345 </para></listitem> 3346</itemizedlist> 3347</sect2> 3348 3349<sect2> 3350<title>Manual Driver Installation in 15 Steps</title> 3351 3352<para> 3353We are going to install a printer driver now by manually executing all 3354required commands. Because this may seem a rather complicated process at 3355first, we go through the procedure step by step, explaining every 3356single action item as it comes up. 3357</para> 3358 3359<procedure> 3360<title>Manual Driver Installation</title> 3361 3362 <step> 3363 <title>Install the printer on CUPS.</title> 3364 3365 <para><screen> 3366 &rootprompt;<userinput>lpadmin -p mysmbtstprn -v socket://10.160.51.131:9100 -E \ 3367 -P canonIR85.ppd</userinput> 3368 </screen></para> 3369 3370 <para> 3371 This installs a printer with the name <parameter>mysmbtstprn</parameter> 3372 to the CUPS system. The printer is accessed via a socket 3373 (a.k.a. JetDirect or Direct TCP/IP) connection. You need to be root 3374 for this step. 3375 </para> 3376 </step> 3377 3378 <step> 3379 <title>(Optional.) Check if the printer is recognized by Samba.</title> 3380 3381 <para> 3382 <indexterm><primary>rpcclient</primary><secondary>enumprinters</secondary></indexterm> 3383<screen> 3384&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'enumprinters' localhost \ 3385 | grep -C2 mysmbtstprn</userinput> 3386flags:[0x800000] 3387name:[\\kde-bitshop\mysmbtstprn] 3388description:[\\kde-bitshop\mysmbtstprn,,mysmbtstprn] 3389comment:[mysmbtstprn] 3390</screen> 3391 </para> 3392 3393 <para> 3394 This should show the printer in the list. If not, stop and restart the Samba daemon (smbd) or send a HUP signal: 3395<screen> 3396&rootprompt;<userinput>kill -HUP `pidof smbd`</userinput> 3397</screen> 3398 Check again. Troubleshoot and repeat until successful. Note the <quote>empty</quote> field between the two 3399 commas in the <quote>description</quote> line. The driver name would appear here if there was one already. You 3400 need to know root's Samba password (as set by the <command>smbpasswd</command> command) for this step and most 3401 of the following steps. Alternatively, you can authenticate as one of the users from the <quote>write 3402 list</quote> as defined in &smb.conf; for <smbconfsection name="[print$]"/>. 3403 </para> 3404 </step> 3405 3406 <step> 3407 <title>(Optional.) Check if Samba knows a driver for the printer.</title> 3408 3409 <para> 3410 <indexterm><primary>rpcclient</primary><secondary>getprinter</secondary></indexterm> 3411 <indexterm><primary>rpcclient</primary><secondary>getdriver</secondary></indexterm> 3412<screen> 3413&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'getprinter mysmbtstprn 2'\ 3414 localhost | grep driver </userinput> 3415 3416drivername:[] 3417 3418&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'getprinter mysmbtstprn 2' \ 3419 localhost | grep -C4 driv</userinput> 3420 3421servername:[\\kde-bitshop] 3422printername:[\\kde-bitshop\mysmbtstprn] 3423sharename:[mysmbtstprn] 3424portname:[Samba Printer Port] 3425drivername:[] 3426comment:[mysmbtstprn] 3427location:[] 3428sepfile:[] 3429printprocessor:[winprint] 3430 3431&rootprompt;<userinput>rpcclient -U root%xxxx -c 'getdriver mysmbtstprn' localhost</userinput> 3432 result was WERR_UNKNOWN_PRINTER_DRIVER 3433</screen></para> 3434 3435<para> 3436None of the three commands shown above should show a driver. 3437This step was done for the purpose of demonstrating this condition. An 3438attempt to connect to the printer at this stage will prompt a 3439message along the lines of, <quote>The server does not have the required printer 3440driver installed.</quote> 3441</para> 3442</step> 3443 3444<step> 3445<title>Put all required driver files into Samba's 3446[print$].</title> 3447 3448<para><screen> 3449&rootprompt;<userinput>smbclient //localhost/print\$ -U 'root%xxxx' \ 3450 -c 'cd W32X86; \ 3451 put /etc/cups/ppd/mysmbtstprn.ppd mysmbtstprn.PPD; \ 3452 put /usr/share/cups/drivers/cupsui.dll cupsui.dll; \ 3453 put /usr/share/cups/drivers/cupsdrvr.dll cupsdrvr.dll; \ 3454 put /usr/share/cups/drivers/cups.hlp cups.hlp'</userinput> 3455</screen></para> 3456 3457<para> 3458(This command should be entered in one long single line. Line breaks and the line ends indicated by 3459<quote>\</quote> have been inserted for readability reasons.) This step is <emphasis>required</emphasis> for 3460the next one to succeed. It makes the driver files physically present in the <smbconfsection name="[print$]"/> 3461share. However, clients would still not be able to install them, because Samba does not yet treat them as 3462driver files. A client asking for the driver would still be presented with a <quote>not installed here</quote> 3463message. 3464</para> 3465</step> 3466 3467<step> 3468<title>Verify where the driver files are now.</title> 3469 3470<para><screen> 3471&rootprompt;<userinput>ls -l /etc/samba/drivers/W32X86/</userinput> 3472total 669 3473drwxr-sr-x 2 root ntadmin 532 May 25 23:08 2 3474drwxr-sr-x 2 root ntadmin 670 May 16 03:15 3 3475-rwxr--r-- 1 root ntadmin 14234 May 25 23:21 cups.hlp 3476-rwxr--r-- 1 root ntadmin 278380 May 25 23:21 cupsdrvr.dll 3477-rwxr--r-- 1 root ntadmin 215848 May 25 23:21 cupsui.dll 3478-rwxr--r-- 1 root ntadmin 169458 May 25 23:21 mysmbtstprn.PPD 3479</screen></para> 3480 3481<para> 3482The driver files now are in the W32X86 architecture <quote>root</quote> of 3483<smbconfsection name="[print$]"/>. 3484</para> 3485</step> 3486 3487<step> 3488<title>Tell Samba that these are driver files (<command>adddriver</command>).</title> 3489 3490<para> 3491<indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm> 3492<screen> 3493&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'adddriver "Windows NT x86" \ 3494 "mydrivername:cupsdrvr.dll:mysmbtstprn.PPD: \ 3495 cupsui.dll:cups.hlp:NULL:RAW:NULL"' \ 3496 localhost</userinput> 3497Printer Driver mydrivername successfully installed. 3498</screen></para> 3499 3500<para> 3501You cannot repeat this step if it fails. It could fail even as a result of a simple typo. It will most likely 3502have moved a part of the driver files into the <quote>2</quote> subdirectory. If this step fails, you need to 3503go back to the fourth step and repeat it before you can try this one again. In this step, you need to choose a 3504name for your driver. It is normally a good idea to use the same name as is used for the printer name; 3505however, in big installations you may use this driver for a number of printers that obviously have different 3506names, so the name of the driver is not fixed. 3507</para> 3508</step> 3509 3510<step> 3511<title>Verify where the driver files are now.</title> 3512 3513<para><screen> 3514&rootprompt;<userinput>ls -l /etc/samba/drivers/W32X86/</userinput> 3515total 1 3516drwxr-sr-x 2 root ntadmin 532 May 25 23:22 2 3517drwxr-sr-x 2 root ntadmin 670 May 16 03:15 3 3518 3519&rootprompt;<userinput>ls -l /etc/samba/drivers/W32X86/2</userinput> 3520total 5039 3521[....] 3522-rwxr--r-- 1 root ntadmin 14234 May 25 23:21 cups.hlp 3523-rwxr--r-- 1 root ntadmin 278380 May 13 13:53 cupsdrvr.dll 3524-rwxr--r-- 1 root ntadmin 215848 May 13 13:53 cupsui.dll 3525-rwxr--r-- 1 root ntadmin 169458 May 25 23:21 mysmbtstprn.PPD 3526</screen></para> 3527 3528<para> 3529Notice how step 6 also moved the driver files to the appropriate 3530subdirectory. Compare this with the situation after step 5. 3531</para> 3532</step> 3533 3534<step> 3535<title>(Optional.) Verify if Samba now recognizes the driver.</title> 3536 3537<para> 3538<indexterm><primary>rpcclient</primary><secondary>enumdrivers</secondary></indexterm> 3539<screen> 3540&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'enumdrivers 3' \ 3541 localhost | grep -B2 -A5 mydrivername</userinput> 3542Printer Driver Info 3: 3543Version: [2] 3544Driver Name: [mydrivername] 3545Architecture: [Windows NT x86] 3546Driver Path: [\\kde-bitshop\print$\W32X86\2\cupsdrvr.dll] 3547Datafile: [\\kde-bitshop\print$\W32X86\2\mysmbtstprn.PPD] 3548Configfile: [\\kde-bitshop\print$\W32X86\2\cupsui.dll] 3549Helpfile: [\\kde-bitshop\print$\W32X86\2\cups.hlp] 3550</screen></para> 3551 3552<para> 3553Remember, this command greps for the name you chose for the 3554driver in step 6. This command must succeed before you can proceed. 3555</para> 3556</step> 3557 3558<step> 3559<title>Tell Samba which printer should use these driver files (<command>setdriver</command>).</title> 3560 3561<para> 3562<indexterm><primary>rpcclient</primary><secondary>setdriver</secondary></indexterm> 3563<screen> 3564&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'setdriver mysmbtstprn mydrivername' \ 3565 localhost</userinput> 3566Successfully set mysmbtstprn to driver mydrivername 3567</screen></para> 3568 3569<para> 3570Since you can bind any printer name (print queue) to any driver, this is a convenient way to set up many 3571queues that use the same driver. You do not need to repeat all the previous steps for the setdriver command to 3572succeed. The only preconditions are that <command>enumdrivers</command> must find the driver and 3573<command>enumprinters</command> must find the printer. 3574</para> 3575</step> 3576 3577<step> 3578<title>(Optional) Verify if Samba has recognized this association.</title> 3579 3580<para> 3581<indexterm><primary>rpcclient</primary><secondary>getprinter</secondary></indexterm> 3582<indexterm><primary>rpcclient</primary><secondary>getdriver</secondary></indexterm> 3583<indexterm><primary>rpcclient</primary><secondary>enumprinters</secondary></indexterm> 3584<screen> 3585&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'getprinter mysmbtstprn 2' localhost \ 3586 | grep driver</userinput> 3587drivername:[mydrivername] 3588 3589&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'getprinter mysmbtstprn 2' localhost \ 3590 | grep -C4 driv</userinput> 3591servername:[\\kde-bitshop] 3592printername:[\\kde-bitshop\mysmbtstprn] 3593sharename:[mysmbtstprn] 3594portname:[Done] 3595drivername:[mydrivername] 3596comment:[mysmbtstprn] 3597location:[] 3598sepfile:[] 3599printprocessor:[winprint] 3600 3601&rootprompt;<userinput>rpcclient -U root%xxxx -c 'getdriver mysmbtstprn' localhost</userinput> 3602[Windows NT x86] 3603Printer Driver Info 3: 3604 Version: [2] 3605 Driver Name: [mydrivername] 3606 Architecture: [Windows NT x86] 3607 Driver Path: [\\kde-bitshop\print$\W32X86\2\cupsdrvr.dll] 3608 Datafile: [\\kde-bitshop\print$\W32X86\2\mysmbtstprn.PPD] 3609 Configfile: [\\kde-bitshop\print$\W32X86\2\cupsui.dll] 3610 Helpfile: [\\kde-bitshop\print$\W32X86\2\cups.hlp] 3611 Monitorname: [] 3612 Defaultdatatype: [RAW] 3613 Monitorname: [] 3614 Defaultdatatype: [RAW] 3615 3616&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'enumprinters' localhost \ 3617 | grep mysmbtstprn</userinput> 3618 name:[\\kde-bitshop\mysmbtstprn] 3619 description:[\\kde-bitshop\mysmbtstprn,mydrivername,mysmbtstprn] 3620 comment:[mysmbtstprn] 3621 3622</screen></para> 3623 3624<para> 3625<indexterm><primary>rpcclient</primary><secondary>enumprinters</secondary></indexterm> 3626Compare these results with the ones from steps 2 and 3. Every one of these commands show the driver is installed. Even 3627the <command>enumprinters</command> command now lists the driver 3628on the <quote>description</quote> line. 3629</para> 3630</step> 3631 3632<step> 3633<title>(Optional.) Tickle the driver into a correct 3634device mode.</title> 3635 3636<para> 3637<indexterm><primary>"Printers" folder</primary></indexterm> 3638You certainly know how to install the driver on the client. In case 3639you are not particularly familiar with Windows, here is a short 3640recipe: Browse the Network Neighborhood, go to the Samba server, and look 3641for the shares. You should see all shared Samba printers. 3642Double-click on the one in question. The driver should get 3643installed and the network connection set up. Another way is to 3644open the <guilabel>Printers (and Faxes)</guilabel> folder, right-click on the printer in 3645question, and select <guilabel>Connect</guilabel> or <guilabel>Install</guilabel>. As a result, a new printer 3646should appear in your client's local <guilabel>Printers (and Faxes)</guilabel> 3647folder, named something like <guilabel>printersharename on Sambahostname</guilabel>. 3648</para> 3649 3650<para> 3651It is important that you execute this step as a Samba printer admin 3652(as defined in &smb.conf;). Here is another method 3653to do this on Windows XP. It uses a command line, which you may type 3654into the <quote>DOS box</quote> (type root's smbpassword when prompted): 3655</para> 3656 3657<para><screen> 3658&dosprompt;<userinput>runas /netonly /user:root "rundll32 printui.dll,PrintUIEntry \ 3659 /in /n \\sambaserver\mysmbtstprn"</userinput> 3660</screen></para> 3661 3662<para> 3663Change any printer setting once (like changing <emphasis><guilabel>portrait</guilabel> to 3664<guilabel>landscape</guilabel></emphasis>), click on <guibutton>Apply</guibutton>, and change the setting back. 3665</para> 3666</step> 3667 3668<step> 3669<title>Install the printer on a client (Point'n'Print).</title> 3670 3671<para> 3672<indexterm significance="preferred"><primary>point 'n' print</primary></indexterm> 3673<screen> 3674&dosprompt;<userinput>rundll32 printui.dll,PrintUIEntry /in /n "\\sambaserver\mysmbtstprn"</userinput> 3675</screen> 3676If it does not work, it could be a permissions problem with the <smbconfsection name="[print$]"/> share. 3677</para> 3678</step> 3679 3680<step> 3681<title>(Optional) Print a test page.</title> 3682 3683<indexterm><primary>rundll32</primary></indexterm> 3684<para><screen> 3685&dosprompt;<userinput>rundll32 printui.dll,PrintUIEntry /p /n "\\sambaserver\mysmbtstprn"</userinput> 3686</screen></para> 3687 3688<para> 3689Then hit [TAB] five times, [ENTER] twice, [TAB] once, and [ENTER] again, and march to the printer. 3690</para> 3691</step> 3692 3693<step> 3694<title>(Recommended.) Study the test page.</title> 3695 3696<para> 3697Hmmm. Just kidding! By now you know everything about printer installations and you do not need to read a word. 3698Just put it in a frame and bolt it to the wall with the heading "MY FIRST RPCCLIENT-INSTALLED PRINTER" 3699&smbmdash; why not just throw it away! 3700</para> 3701</step> 3702 3703<step> 3704<title>(Obligatory.) Enjoy. Jump. Celebrate your success.</title> 3705 3706<para><screen> 3707&rootprompt;<userinput>echo "Cheeeeerioooooo! Success..." >> /var/log/samba/log.smbd</userinput> 3708</screen></para> 3709</step> 3710</procedure> 3711</sect2> 3712 3713<sect2> 3714<title>Troubleshooting Revisited</title> 3715 3716<para> 3717<indexterm><primary>adddriver</primary></indexterm> 3718The setdriver command will fail if in Samba's mind the queue is not 3719already there. A successful installation displys the promising message that the: 3720<screen> 3721Printer Driver ABC successfully installed. 3722</screen> 3723following the <command>adddriver</command> parts of the procedure. But you may also see 3724a disappointing message like this one: 3725<computeroutput> 3726result was NT_STATUS_UNSUCCESSFUL 3727</computeroutput></para> 3728 3729<para> 3730<indexterm><primary>lpstat</primary></indexterm> 3731<indexterm><primary>rpcclient</primary></indexterm> 3732It is not good enough that you can see the queue in CUPS, using the <command>lpstat -p ir85wm</command> 3733command. A bug in most recent versions of Samba prevents the proper update of the queue list. The recognition 3734of newly installed CUPS printers fails unless you restart Samba or send a HUP to all smbd processes. To verify 3735if this is the reason why Samba does not execute the <command>setdriver</command> command successfully, check 3736if Samba <quote>sees</quote> the printer: 3737<indexterm><primary>rpcclient</primary><secondary>enumprinters</secondary></indexterm> 3738<screen> 3739&rootprompt;<userinput>rpcclient transmeta -N -U'root%xxxx' -c 'enumprinters 0'|grep ir85wm</userinput> 3740 printername:[ir85wm] 3741</screen></para> 3742 3743<para> 3744An alternate command could be this: 3745<indexterm><primary>rpcclient</primary><secondary>getprinter</secondary></indexterm> 3746<screen> 3747&rootprompt;<userinput>rpcclient transmeta -N -U'root%secret' -c 'getprinter ir85wm' </userinput> 3748 cmd = getprinter ir85wm 3749 flags:[0x800000] 3750 name:[\\transmeta\ir85wm] 3751 description:[\\transmeta\ir85wm,ir85wm,DPD] 3752 comment:[CUPS PostScript-Treiber for Windows NT/200x/XP] 3753</screen></para> 3754 3755<para> 3756By the way, you can use these commands, plus a few more, of course, to install drivers on remote Windows NT print servers too! 3757</para> 3758</sect2> 3759</sect1> 3760 3761<sect1> 3762<title>The Printing <filename>*.tdb</filename> Files</title> 3763 3764<para> 3765<indexterm><primary>TDB</primary></indexterm> 3766<indexterm><primary>connections.tdb</primary><seealso>TDB</seealso></indexterm> 3767<indexterm><primary>printing.tdb</primary><seealso>TDB</seealso></indexterm> 3768<indexterm><primary>share_info.tdb</primary><seealso>TDB</seealso></indexterm> 3769<indexterm><primary>ntdrivers.tdb</primary><seealso>TDB</seealso></indexterm> 3770<indexterm><primary>unexpected.tdb</primary><seealso>TDB</seealso></indexterm> 3771<indexterm><primary>brlock.tdb</primary><seealso>TDB</seealso></indexterm> 3772<indexterm><primary>locking.tdb</primary><seealso>TDB</seealso></indexterm> 3773<indexterm><primary>ntforms.tdb</primary><seealso>TDB</seealso></indexterm> 3774<indexterm><primary>messages.tdb</primary><seealso>TDB</seealso></indexterm> 3775<indexterm><primary>ntprinters.tdb</primary><seealso>TDB</seealso></indexterm> 3776<indexterm><primary>sessionid.tdb</primary><seealso>TDB</seealso></indexterm> 3777<indexterm><primary>secrets.tdb</primary><seealso>TDB</seealso></indexterm> 3778Some mystery is associated with the series of files with a tdb suffix appearing in every Samba installation. 3779They are <filename>connections.tdb</filename>, <filename>printing.tdb</filename>, 3780<filename>share_info.tdb</filename>, <filename>ntdrivers.tdb</filename>, <filename>unexpected.tdb</filename>, 3781<filename>brlock.tdb</filename>, <filename>locking.tdb</filename>, <filename>ntforms.tdb</filename>, 3782<filename>messages.tdb</filename> , <filename>ntprinters.tdb</filename>, <filename>sessionid.tdb</filename>, 3783and <filename>secrets.tdb</filename>. What is their purpose? 3784</para> 3785 3786<sect2> 3787<title>Trivial Database Files</title> 3788 3789<para> 3790<indexterm><primary>TDB</primary></indexterm> 3791A Windows NT (print) server keeps track of all information needed to serve its duty toward its clients by 3792storing entries in the Windows registry. Client queries are answered by reading from the registry, 3793Administrator or user configuration settings that are saved by writing into the registry. Samba and UNIX 3794obviously do not have such a Registry. Samba instead keeps track of all client-related information in a series 3795of <filename>*.tdb</filename> files. (TDB stands for trivial data base). These are often located in 3796<filename>/var/lib/samba/</filename> or <filename>/var/lock/samba/</filename>. The printing-related files are 3797<filename>ntprinters.tdb</filename>, <filename>printing.tdb</filename>,<filename>ntforms.tdb</filename>, and 3798<filename>ntdrivers.tdb</filename>. 3799</para> 3800</sect2> 3801 3802<sect2> 3803<title>Binary Format</title> 3804 3805<para> 3806<filename>*.tdb</filename> files are not human readable. They are written in a binary format. <quote>Why not 3807ASCII?</quote>, you may ask. <quote>After all, ASCII configuration files are a good and proven tradition on 3808UNIX.</quote> The reason for this design decision by the Samba Team is mainly performance. Samba needs to be 3809fast; it runs a separate <command>smbd</command> process for each client connection, in some environments many 3810thousands of them. Some of these <command>smbds</command> might need to write-access the same 3811<filename>*.tdb</filename> file <emphasis>at the same time</emphasis>. The file format of Samba's 3812<filename>*.tdb</filename> files allows for this provision. Many smbd processes may write to the same 3813<filename>*.tdb</filename> file at the same time. This wouldn't be possible with pure ASCII files. 3814</para> 3815</sect2> 3816 3817<sect2> 3818<title>Losing <filename>*.tdb</filename> Files</title> 3819 3820<para> 3821It is very important that all <filename>*.tdb</filename> files remain consistent over all write and read 3822accesses. However, it may happen that these files <emphasis>do</emphasis> get corrupted. (A <command>kill -9 3823`pidof smbd'</command> while a write access is in progress could do the damage, as could a power interruption, 3824etc.). In cases of trouble, a deletion of the old printing-related <filename>*.tdb</filename> files may be the 3825only option. After that, you need to re-create all print-related setups unless you have made a backup of the 3826<filename>*.tdb</filename> files in time. 3827</para> 3828</sect2> 3829 3830<sect2> 3831<title>Using <command>tdbbackup</command></title> 3832 3833<para> 3834<indexterm><primary>TDB</primary><secondary>backing up</secondary><see>tdbbackup</see></indexterm> 3835<indexterm><primary>tdbbackup</primary></indexterm> 3836Samba ships with a little utility that helps the root user of your system to backup your 3837<filename>*.tdb</filename> files. If you run it with no argument, it prints a usage message: 3838<screen> 3839&rootprompt;<userinput>tdbbackup</userinput> 3840 Usage: tdbbackup [options] <fname...> 3841 3842 Version:3.0a 3843 -h this help message 3844 -s suffix set the backup suffix 3845 -v verify mode (restore if corrupt) 3846</screen></para> 3847 3848<para> 3849Here is how I backed up my <filename>printing.tdb</filename> file: 3850</para> 3851 3852<para><screen> 3853&rootprompt;<userinput>ls</userinput> 3854. browse.dat locking.tdb ntdrivers.tdb printing.tdb 3855.. share_info.tdb connections.tdb messages.tdb ntforms.tdb 3856printing.tdbkp unexpected.tdb brlock.tdb gmon.out namelist.debug 3857ntprinters.tdb sessionid.tdb 3858 3859&rootprompt;<userinput>tdbbackup -s .bak printing.tdb</userinput> 3860 printing.tdb : 135 records 3861 3862&rootprompt;<userinput>ls -l printing.tdb*</userinput> 3863 -rw------- 1 root root 40960 May 2 03:44 printing.tdb 3864 -rw------- 1 root root 40960 May 2 03:44 printing.tdb.bak 3865 3866</screen></para> 3867</sect2> 3868</sect1> 3869 3870<sect1> 3871<title>CUPS Print Drivers from Linuxprinting.org</title> 3872 3873<para> 3874<indexterm><primary>Linuxprinting.org</primary></indexterm> 3875CUPS ships with good support for HP LaserJet-type printers. You can install the generic driver as follows: 3876<indexterm><primary>lpadmin</primary></indexterm> 3877<screen> 3878&rootprompt;<userinput>lpadmin -p laserjet4plus -v parallel:/dev/lp0 -E -m laserjet.ppd</userinput> 3879</screen></para> 3880 3881<para> 3882The <option>-m</option> switch will retrieve the <filename>laserjet.ppd</filename> from the standard 3883repository for not-yet-installed PPDs, which CUPS typically stores in 3884<filename>/usr/share/cups/model</filename>. Alternatively, you may use <option>-P /path/to/your.ppd</option>. 3885</para> 3886 3887<para> 3888The generic <filename>laserjet.ppd,</filename> however, does not support every special option for every 3889LaserJet-compatible model. It constitutes a sort of <quote>least common denominator</quote> of all the models. 3890If for some reason you must pay for the commercially available ESP Print Pro drivers, your first move should 3891be to consult the database on the <ulink noescape="1" 3892url="http://www.linuxprinting.org/printer_list.cgi">Linuxprinting</ulink> Web site. Linuxprinting.org has 3893excellent recommendations about which driver is best used for each printer. Its database is kept current by 3894the tireless work of Till Kamppeter from Mandrakesoft, who is also the principal author of the 3895<command>foomatic-rip</command> utility. 3896</para> 3897 3898<note><para> 3899<indexterm><primary>foomatic-rip</primary></indexterm> 3900<indexterm><primary>cupsomatic</primary></indexterm> 3901<indexterm><primary>Adobe PPD</primary></indexterm> 3902The former <command>cupsomatic</command> concept is now being replaced by the new successor, a much more 3903powerful <command>foomatic-rip</command>. <command>cupsomatic</command> is no longer maintained. Here is the 3904new URL to the <ulink noescape="1" url="http://www.linuxprinting.org/driver_list.cgi">Foomatic-3.0</ulink> 3905database. If you upgrade to <command>foomatic-rip</command>, remember to also upgrade to the new-style PPDs 3906for your Foomatic-driven printers. foomatic-rip will not work with PPDs generated for the old 3907<command>cupsomatic</command>. The new-style PPDs are 100% compliant with the Adobe PPD specification. They 3908are also intended to be used by Samba and the cupsaddsmb utility, to provide the driver files for the Windows 3909clients! 3910</para></note> 3911 3912<sect2> 3913<title>foomatic-rip and Foomatic Explained</title> 3914 3915 3916<para> 3917<indexterm significance="preferred"><primary>foomatic</primary></indexterm> 3918<indexterm significance="preferred"><primary>foomatic-rip</primary></indexterm> 3919Nowadays, most Linux distributions rely on the utilities from the <ulink 3920url="http://www.linuxprinting.org/">Linuxprinting.org</ulink> to create their printing-related software 3921(which, by the way, works on all UNIXes and on Mac OS X and Darwin, too). The utilities from this sire have a 3922very end-user-friendly interface that allows for an easy update of drivers and PPDs for all supported models, 3923all spoolers, all operating systems, and all package formats (because there is none). Its history goes back a 3924few years. 3925</para> 3926 3927<para> 3928Recently, Foomatic has achieved the astonishing milestone of <ulink 3929url="http://www.linuxprinting.org/printer_list.cgi?make=Anyone">1,000 listed</ulink> printer models. 3930Linuxprinting.org keeps all the important facts about printer drivers, supported models, and which options are 3931available for the various driver/printer combinations in its <ulink 3932url="http://www.linuxprinting.org/foomatic.html">Foomatic</ulink> database. Currently there are <ulink 3933url="http://www.linuxprinting.org/driver_list.cgi">245 drivers</ulink> in the database. Many drivers support 3934various models, and many models may be driven by different drivers &smbmdash; its your choice! 3935</para> 3936 3937<sect3> 3938<title>690 <quote>Perfect</quote> Printers</title> 3939 3940<para> 3941<indexterm><primary>Windows PPD</primary></indexterm> 3942At present, there are 690 devices dubbed as working perfectly: 181 are <emphasis>mostly</emphasis> perfect, 96 3943are <emphasis>partially</emphasis> perfect, and 46 are paperweights. Keeping in mind that most of these are 3944non-PostScript models (PostScript printers are automatically supported by CUPS to perfection by using their 3945own manufacturer-provided Windows PPD), and that a multifunctional device never qualifies as working perfectly 3946if it does not also scan and copy and fax under GNU/Linux &smbmdash; then this is a truly astonishing 3947achievement! Three years ago the number was not more than 500, and Linux or UNIX printing at the time wasn't 3948anywhere near the quality it is today. 3949</para> 3950</sect3> 3951 3952<sect3> 3953<title>How the Printing HOWTO Started It All</title> 3954 3955<para> 3956A few years ago <ulink url="http://www2.picante.com/">Grant Taylor</ulink> started it all. The 3957roots of today's Linuxprinting.org are in the first <ulink 3958url="http://www.linuxprinting.org/foomatic2.9/howto/">Linux Printing HOWTO</ulink> that he authored. As a 3959side-project to this document, which served many Linux users and admins to guide their first steps in this 3960complicated and delicate setup (to a scientist, printing is <quote>applying a structured deposition of 3961distinct patterns of ink or toner particles on paper substrates</quote>), he started to build in a little 3962Postgres database with information about the hardware and driver zoo that made up Linux printing of the time. 3963This database became the core component of today's Foomatic collection of tools and data. In the meantime, it 3964has moved to an XML representation of the data. 3965</para> 3966</sect3> 3967 3968<sect3> 3969<title>Foomatic's Strange Name</title> 3970 3971 3972<para> 3973<indexterm><primary>foomatic</primary></indexterm> 3974<quote>Why the funny name?</quote> you ask. When it really took off, around spring 2000, CUPS was far less 3975popular than today, and most systems used LPD, LPRng, or even PDQ to print. CUPS shipped with a few generic 3976drivers (good for a few hundred different printer models). These didn't support many device-specific options. 3977CUPS also shipped with its own built-in rasterization filter (<parameter>pstoraster</parameter>, derived from 3978Ghostscript). On the other hand, CUPS provided brilliant support for <emphasis>controlling</emphasis> all 3979printer options through standardized and well-defined PPD files. Plus, CUPS was designed to be easily 3980extensible. 3981</para> 3982 3983<para> 3984Taylor already had in his database a respectable compilation of facts about many more printers and the 3985Ghostscript <quote>drivers</quote> they run with. His idea, to generate PPDs from the database information and 3986use them to make standard Ghostscript filters work within CUPS, proved to work very well. It also killed 3987several birds with one stone: 3988</para> 3989 3990<itemizedlist> 3991 <listitem><para>It made all current and future Ghostscript filter 3992 developments available for CUPS.</para></listitem> 3993 3994 <listitem><para>It made available a lot of additional printer models 3995 to CUPS users (because often the traditional Ghostscript way of 3996 printing was the only one available).</para></listitem> 3997 3998 <listitem><para>It gave all the advanced CUPS options (Web interface, 3999 GUI driver configurations) to users wanting (or needing) to use 4000 Ghostscript filters.</para></listitem> 4001</itemizedlist> 4002</sect3> 4003 4004<sect3> 4005<title>cupsomatic, pdqomatic, lpdomatic, directomatic</title> 4006 4007<para> 4008<indexterm><primary>cupsomatic</primary></indexterm> 4009<indexterm><primary>CUPS-PPD</primary></indexterm> 4010<indexterm><primary>PPD</primary><secondary>CUPS</secondary><see>CUPS-PPD</see></indexterm> 4011CUPS worked through a quickly hacked-up filter script named <ulink 4012url="http://www.linuxprinting.org/download.cgi?filename=cupsomatic&show=0">cupsomatic</ulink>. cupsomatic 4013ran the printfile through Ghostscript, constructing automatically the rather complicated command line needed. 4014It just needed to be copied into the CUPS system to make it work. To configure the way cupsomatic controls the 4015Ghostscript rendering process, it needs a CUPS-PPD. This PPD is generated directly from the contents of the 4016database. For CUPS and the respective printer/filter combo, another Perl script named CUPS-O-Matic did the PPD 4017generation. After that was working, Taylor implemented within a few days a similar thing for two other 4018spoolers. Names chosen for the config-generator scripts were <ulink 4019url="http://www.linuxprinting.org/download.cgi?filename=lpdomatic&show=0">PDQ-O-Matic</ulink> (for PDQ) 4020and <ulink url="http://www.linuxprinting.org/download.cgi?filename=lpdomatic&show=0">LPD-O-Matic</ulink> 4021(for &smbmdash; you guessed it &smbmdash; LPD); the configuration here didn't use PPDs but other 4022spooler-specific files. 4023</para> 4024 4025<para> 4026From late summer of that year, <ulink url="http://www.linuxprinting.org/till/">Till Kamppeter</ulink> started 4027to put work into the database. Kamppeter had been newly employed by <ulink 4028url="http://www.mandrakesoft.com/">Mandrakesoft</ulink> to convert its printing system over to CUPS, after 4029they had seen his <ulink url="http://www.fltk.org/">FLTK</ulink>-based <ulink 4030url="http://cups.sourceforge.net/xpp/">XPP</ulink> (a GUI front-end to the CUPS lp-command). He added a huge 4031amount of new information and new printers. He also developed the support for other spoolers, like <ulink 4032url="http://ppr.sourceforge.net/">PPR</ulink> (via ppromatic), <ulink 4033url="http://sourceforge.net/projects/lpr/">GNUlpr</ulink>, and <ulink 4034url="http://www.lprng.org/">LPRng</ulink> (both via an extended lpdomatic) and spooler-less printing (<ulink 4035url="http://www.linuxprinting.org/download.cgi?filename=directomatic&show=0">directomatic</ulink>). 4036</para> 4037 4038<para> 4039So, to answer your question, <quote>Foomatic</quote> is the general name for all the overlapping code and data 4040behind the <quote>*omatic</quote> scripts. Foomatic, up to versions 2.0.x, required (ugly) Perl data 4041structures attached to Linuxprinting.org PPDs for CUPS. It had a different <quote>*omatic</quote> script for 4042every spooler, as well as different printer configuration files. 4043</para> 4044</sect3> 4045 4046<sect3> 4047<title>The <emphasis>Grand Unification</emphasis> Achieved</title> 4048 4049<para> 4050<indexterm><primary>foomatic-rip</primary></indexterm> 4051This has all changed in Foomatic versions 2.9 (beta) and released as <quote>stable</quote> 3.0. It has now 4052achieved the convergence of all *omatic scripts and is called the <ulink 4053url="http://www.linuxprinting.org/foomatic2.9/download.cgi?filename=foomatic-rip&show=0">foomatic-rip</ulink>. 4054This single script is the unification of the previously different spooler-specific *omatic scripts. 4055foomatic-rip is used by all the different spoolers alike, and because it can read PPDs (both the original 4056PostScript printer PPDs and the Linuxprinting.org-generated ones), all of a sudden all supported spoolers can 4057have the power of PPDs at their disposal. Users only need to plug foomatic-rip into their system. For users 4058there is improved media type and source support &smbmdash; paper sizes and trays are easier to configure. 4059</para> 4060 4061<para> 4062<indexterm><primary>PPDs</primary></indexterm> 4063<indexterm><primary>Foomatic tutorial</primary></indexterm> 4064<indexterm><primary>LinuxKongress2002</primary></indexterm> 4065Also, the new generation of Linuxprinting.org PPDs no longer contains Perl data structures. If you are a 4066distro maintainer and have used the previous version of Foomatic, you may want to give the new one a spin, but 4067remember to generate a new-version set of PPDs via the new <ulink 4068url="http://www.linuxprinting.org/download/foomatic/foomatic-db-engine-3.0.0beta1.tar.gz">foomatic-db-engine!</ulink>. 4069Individual users just need to generate a single new PPD specific to their model by <ulink 4070url="http://www.linuxprinting.org/kpfeifle/LinuxKongress2002/Tutorial/II.Foomatic-User/II.tutorial-handout-foomatic-user.html">following 4071the steps</ulink> outlined in the Foomatic tutorial or in this chapter. This new development is truly amazing. 4072</para> 4073 4074<para> 4075<indexterm><primary>foomatic-rip</primary></indexterm> 4076<indexterm><primary>Adobe</primary></indexterm> 4077<indexterm><primary>printer drivers</primary></indexterm> 4078foomatic-rip is a very clever wrapper around the need to run Ghostscript with a different syntax, options, 4079device selections, and/or filters for each different printer or spooler. At the same time, it can read the PPD 4080associated with a print queue and modify the print job according to the user selections. Together with this 4081comes the 100% compliance of the new Foomatic PPDs with the Adobe spec. Some innovative features of the 4082Foomatic concept may surprise users. It will support custom paper sizes for many printers and will support 4083printing on media drawn from different paper trays within the same job (in both cases, even where there is no 4084support for this from Windows-based vendor printer drivers). 4085</para> 4086</sect3> 4087 4088<sect3> 4089<title>Driver Development Outside</title> 4090 4091<para> 4092<indexterm><primary>Linuxprinting.org</primary></indexterm> 4093Most driver development itself does not happen within Linuxprinting.org. Drivers are written by independent 4094maintainers. Linuxprinting.org just pools all the information and stores it in its database. In addition, it 4095also provides the Foomatic glue to integrate the many drivers into any modern (or legacy) printing system 4096known to the world. 4097</para> 4098 4099<para> 4100Speaking of the different driver development groups, most of the work is currently done in three projects: 4101</para> 4102 4103<itemizedlist> 4104 <listitem><para> 4105<indexterm><primary>Omni</primary></indexterm> 4106 <ulink url="http://www-124.ibm.com/developerworks/oss/linux/projects/omni/">Omni</ulink> 4107 &smbmdash; a free software project by IBM that tries to convert its printer 4108 driver knowledge from good-ol' OS/2 times into a modern, modular, 4109 universal driver architecture for Linux/UNIX (still beta). This 4110 currently supports 437 models.</para></listitem> 4111 4112 <listitem><para> 4113<indexterm><primary>HPIJS</primary></indexterm> 4114 <ulink url="http://hpinkjet.sf.net/">HPIJS</ulink> &smbmdash; 4115 a free software project by HP to provide the support for its own 4116 range of models (very mature, printing in most cases is perfect and 4117 provides true photo quality). This currently supports 369 4118 models.</para></listitem> 4119 4120 <listitem><para> 4121<indexterm><primary>Gutenprint</primary></indexterm> 4122 <ulink url="http://gimp-print.sourceforge.net/">Gutenprint</ulink> &smbmdash; a free software 4123 effort, started by Michael Sweet (also lead developer for CUPS), now 4124 directed by Robert Krawitz, which has achieved an amazing level of 4125 photo print quality (many Epson users swear that its quality is 4126 better than the vendor drivers provided by Epson for the Microsoft 4127 platforms). This currently supports 522 models.</para></listitem> 4128</itemizedlist> 4129</sect3> 4130 4131<sect3> 4132<title>Forums, Downloads, Tutorials, Howtos (Also for Mac OS X and Commercial UNIX)</title> 4133 4134<para> 4135Linuxprinting.org today is the one-stop shop to download printer drivers. Look for printer information and 4136<ulink url="http://www.linuxprinting.org//kpfeifle/LinuxKongress2002/Tutorial/">tutorials</ulink> or solve 4137printing problems in its popular <ulink url="http://www.linuxprinting.org/newsportal/">forums</ulink>. This 4138forum is not just for GNU/Linux users, but admins of <ulink url="http://www.linuxprinting.org/macosx/"> 4139commercial UNIX systems</ulink> are also going there, and the relatively new 4140<ulink url="http://www.linuxprinting.org/newsportal/thread.php3?name=linuxprinting.macosx.general">Mac OS X 4141forum</ulink> has turned out to be one of the most frequented forums after only a few weeks. 4142</para> 4143 4144<para> 4145<indexterm><primary>Mandriva</primary></indexterm> 4146<indexterm><primary>Mandrake</primary></indexterm> 4147<indexterm><primary>Conectiva</primary></indexterm> 4148Linuxprinting.org and the Foomatic driver wrappers around Ghostscript are now a standard tool-chain for 4149printing on all the important distros. Most of them also have CUPS underneath. While in recent years most 4150printer data had been added by Kamppeter, many additional contributions came from engineers with SuSE, Red 4151Hat, Conectiva, Debian, and others. Vendor-neutrality is an important goal of the Foomatic project. Mandrake 4152and Conectiva have merged and are now called Mandriva. 4153</para> 4154 4155<note><para> 4156Till Kamppeter from Mandrakesoft is doing an excellent job in his spare time to maintain Linuxprinting.org and 4157Foomatic. So if you use it often, please send him a note showing your appreciation. 4158</para></note> 4159</sect3> 4160 4161<sect3> 4162<title>Foomatic Database-Generated PPDs</title> 4163 4164<para> 4165<indexterm><primary>Foomatic database</primary></indexterm> 4166<indexterm><primary>XML-based datasets</primary></indexterm> 4167<indexterm><primary>kprinter</primary></indexterm> 4168<indexterm><primary>gtklp</primary></indexterm> 4169<indexterm><primary>xpp</primary></indexterm> 4170<indexterm><primary>HP Photosmart</primary></indexterm> 4171<indexterm><primary>Epson Stylus inkjet</primary></indexterm> 4172<indexterm><primary>non-PostScript printers</primary></indexterm> 4173<indexterm><primary>raster</primary></indexterm> 4174The Foomatic database is an amazing piece of ingenuity in itself. Not only does it keep the printer and driver 4175information, but it is organized in a way that it can generate PPD files on the fly from its internal 4176XML-based datasets. While these PPDs are modeled to the Adobe specification of PPDs, the 4177Linuxprinting.org/Foomatic-PPDs do not normally drive PostScript printers. They are used to describe all the 4178bells and whistles you could ring or blow on an Epson Stylus inkjet, or an HP Photosmart, or what-have-you. 4179The main trick is one little additional line, not envisaged by the PPD specification, starting with the 4180<parameter>*cupsFilter</parameter> keyword. It tells the CUPS daemon how to proceed with the PostScript print 4181file (old-style Foomatic-PPDs named the cupsomatic filter script, while the new-style PPDs are now call 4182foomatic-rip). This filter script calls Ghostscript on the host system (the recommended variant is ESP 4183Ghostscript) to do the rendering work. foomatic-rip knows which filter or internal device setting it should 4184ask from Ghostscript to convert the PostScript print job into a raster format ready for the target device. 4185This usage of PPDs to describe the options of non-PostScript printers was the invention of the CUPS 4186developers. The rest is easy. GUI tools (like KDE's marvelous <ulink 4187url="http://printing.kde.org/overview/kprinter.phtml">kprinter</ulink> or the GNOME <ulink 4188url="http://gtklp.sourceforge.net/">gtklp</ulink> xpp and the CUPS Web interface) read the PPD as well and use 4189this information to present the available settings to the user as an intuitive menu selection. 4190</para> 4191</sect3> 4192</sect2> 4193 4194<sect2> 4195<title>foomatic-rip and Foomatic PPD Download and Installation</title> 4196 4197<para> 4198Here are the steps to install a foomatic-rip-driven LaserJet 4 Plus-compatible 4199printer in CUPS (note that recent distributions of SuSE, UnitedLinux and 4200Mandrake may ship with a complete package of Foomatic-PPDs plus the 4201<command>foomatic-rip</command> utility. Going directly to 4202Linuxprinting.org ensures that you get the latest driver/PPD files). 4203</para> 4204 4205<itemizedlist> 4206 <listitem><para>Open your browser at the Linuxprinting.org printer list <ulink url="http://www.linuxprinting.org/printer_list.cgi">page.</ulink> 4207 </para></listitem> 4208 4209 <listitem><para>Check the complete list of printers in the 4210 <ulink url="http://www.linuxprinting.org/printer_list.cgi?make=Anyone">database.</ulink>. 4211 </para></listitem> 4212 4213 <listitem><para>Select your model and click on the link. 4214 </para></listitem> 4215 4216 <listitem><para>You'll arrive at a page listing all drivers working with this 4217 model (for all printers, there will always be <emphasis>one</emphasis> 4218 recommended driver. Try this one first). 4219 </para></listitem> 4220 4221 <listitem><para>In our case (HP LaserJet 4 Plus), we'll arrive at the default driver for the 4222 <ulink url="http://www.linuxprinting.org/show_printer.cgi?recnum=HP-LaserJet_4_Plus">HP-LaserJet 4 Plus.</ulink> 4223 </para></listitem> 4224 4225 <listitem><para>The recommended driver is ljet4.</para></listitem> 4226 4227 <listitem><para>Several links are provided here. You should visit them all if you 4228 are not familiar with the Linuxprinting.org database. 4229 </para></listitem> 4230 4231 <listitem><para>There is a link to the database page for the 4232 <ulink url="http://www.linuxprinting.org/show_driver.cgi?driver=ljet4">ljet4</ulink>. 4233 On the driver's page, you'll find important and detailed information 4234 about how to use that driver within the various available 4235 spoolers.</para></listitem> 4236 4237 <listitem><para>Another link may lead you to the home page of the 4238 author of the driver.</para></listitem> 4239 4240 <listitem><para>Important links are the ones that provide hints with 4241 setup instructions for <ulink noescape="1" url="http://www.linuxprinting.org/cups-doc.html">CUPS</ulink>; 4242 <ulink url="http://www.linuxprinting.org/pdq-doc.html">PDQ</ulink>; 4243 <ulink url="http://www.linuxprinting.org/lpd-doc.html">LPD, LPRng, and GNUlpr</ulink>); 4244 as well as <ulink url="http://www.linuxprinting.org/ppr-doc.html">PPR</ulink> 4245 or <quote>spoolerless</quote> <ulink url="http://www.linuxprinting.org/direct-doc.html">printing</ulink>. 4246 </para></listitem> 4247 4248 <listitem><para>You can view the PPD in your browser through this link: 4249 <ulink noescape="1" url="http://www.linuxprinting.org/ppd-o-matic.cgi?driver=ljet4&printer=HP-LaserJet_4_Plus&show=1">http://www.linuxprinting.org/ppd-o-matic.cgi?driver=ljet4&printer=HP-LaserJet_4_Plus&show=1</ulink> 4250 </para></listitem> <listitem><para>Most importantly, you can also generate and download 4251 the <ulink url="http://www.linuxprinting.org/ppd-o-matic.cgi?driver=ljet4&printer=HP-LaserJet_4_Plus&show=0">PPD</ulink>. 4252 </para></listitem> 4253 4254 <listitem><para>The PPD contains all the information needed to use our 4255 model and the driver; once installed, this works transparently 4256 for the user. Later you'll only need to choose resolution, paper size, 4257 and so on, from the Web-based menu, or from the print dialog GUI, or from 4258 the command line.</para></listitem> 4259 4260 <listitem><para>If you ended up on the drivers 4261 <ulink url="http://www.linuxprinting.org/show_driver.cgi?driver=ljet4">page</ulink>, 4262 you can choose to use the <quote>PPD-O-Matic</quote> online PPD generator 4263 program.</para></listitem> 4264 4265 <listitem><para>Select the exact model and check either <guilabel>Download</guilabel> or 4266 <guilabel>Display PPD file</guilabel> and click <guilabel>Generate PPD file</guilabel>.</para></listitem> 4267 4268 <listitem><para>If you save the PPD file from the browser view, please 4269 do not use cut and paste (since it could possibly damage line endings 4270 and tabs, which makes the PPD likely to fail its duty), but use <guimenuitem>Save 4271 as...</guimenuitem> in your browser's menu. (It is best to use the <guilabel>Download</guilabel> option 4272 directly from the Web page.)</para></listitem> 4273 4274 <listitem><para>Another interesting part on each driver page is 4275 the <guimenuitem>Show execution details</guimenuitem> button. If you 4276 select your printer model and click on that button, 4277 a complete Ghostscript command line will be displayed, enumerating all options 4278 available for that combination of driver and printer model. This is a great way to 4279 <quote>learn Ghostscript by doing</quote>. It is also an excellent cheat sheet 4280 for all experienced users who need to reconstruct a good command line 4281 for that darned printing script, but can't remember the exact 4282 syntax. </para></listitem> 4283 4284 <listitem><para>Sometime during your visit to Linuxprinting.org, save 4285 the PPD to a suitable place on your hard disk, say 4286 <filename>/path/to/my-printer.ppd</filename> (if you prefer to install 4287 your printers with the help of the CUPS Web interface, save the PPD to 4288 the <filename>/usr/share/cups/model/</filename> path and restart 4289 cupsd).</para></listitem> 4290 4291 <listitem><para>Then install the printer with a suitable command line, 4292 like this: 4293 </para> 4294 4295 <para><screen> 4296 &rootprompt;<userinput>lpadmin -p laserjet4plus -v parallel:/dev/lp0 -E \ 4297 -P path/to/my-printer.ppd</userinput> 4298 </screen></para></listitem> 4299 4300 <listitem><para>For all the new-style <quote>Foomatic-PPDs</quote> 4301 from Linuxprinting.org, you also need a special CUPS filter named 4302 foomatic-rip. 4303 </para></listitem> 4304 4305 <listitem><para>The foomatic-rip Perl script itself also makes some 4306 interesting <ulink url="http://www.linuxprinting.org/foomatic2.9/download.cgi?filename=foomatic-rip&show=1">reading</ulink> 4307 because it is well documented by Kamppeter's in-line comments (even 4308 non-Perl hackers will learn quite a bit about printing by reading 4309 it).</para></listitem> 4310 4311 <listitem><para>Save foomatic-rip either directly in 4312 <filename>/usr/lib/cups/filter/foomatic-rip</filename> or somewhere in 4313 your $PATH (and remember to make it world-executable). Again, 4314 do not save by copy and paste but use the appropriate link or the 4315 <guimenuitem>Save as...</guimenuitem> menu item in your browser.</para></listitem> 4316 4317 <listitem><para>If you save foomatic-rip in your $PATH, create a symlink: 4318 <screen> 4319 &rootprompt;<userinput>cd /usr/lib/cups/filter/ ; ln -s `which foomatic-rip'</userinput> 4320 </screen> 4321 </para> 4322 4323 <para> 4324 CUPS will discover this new available filter at startup after restarting 4325 cupsd.</para></listitem> 4326</itemizedlist> 4327 4328<para> 4329Once you print to a print queue set up with the Foomatic PPD, CUPS will insert the appropriate commands and 4330comments into the resulting PostScript job file. foomatic-rip is able to read and act upon these and uses some 4331specially encoded Foomatic comments embedded in the job file. These in turn are used to construct 4332(transparently for you, the user) the complicated Ghostscript command line telling the printer driver exactly 4333how the resulting raster data should look and which printer commands to embed into the data stream. You need: 4334</para> 4335 4336<itemizedlist> 4337 <listitem><para>A <quote>foomatic+something</quote> PPD &smbmdash; but this is not enough 4338 to print with CUPS (it is only <emphasis>one</emphasis> important 4339 component).</para></listitem> 4340 4341 <listitem><para>The <parameter>foomatic-rip</parameter> filter script (Perl) in 4342 <filename>/usr/lib/cups/filters/</filename>.</para></listitem> 4343 4344 <listitem><para>Perl to make foomatic-rip run.</para></listitem> 4345 4346 <listitem><para>Ghostscript (because it is doing the main work, 4347 controlled by the PPD/foomatic-rip combo) to produce the raster data 4348 fit for your printer model's consumption.</para></listitem> 4349 4350 <listitem><para>Ghostscript <emphasis>must</emphasis> (depending on 4351 the driver/model) contain support for a certain device representing 4352 the selected driver for your model (as shown by <command>gs -h</command>).</para></listitem> 4353 4354 <listitem><para>foomatic-rip needs a new version of PPDs (PPD versions 4355 produced for cupsomatic do not work with foomatic-rip).</para></listitem> 4356</itemizedlist> 4357</sect2> 4358</sect1> 4359 4360<sect1> 4361<title>Page Accounting with CUPS</title> 4362 4363 4364<para> 4365<indexterm><primary>CUPS</primary><secondary>Page Accounting</secondary></indexterm> 4366Often there are questions regarding print quotas where Samba users (that is, Windows clients) should not be 4367able to print beyond a certain number of pages or data volume per day, week, or month. This feature is 4368dependent on the real print subsystem you're using. Samba's part is always to receive the job files from the 4369clients (filtered <emphasis>or</emphasis> unfiltered) and hand them over to this printing subsystem. 4370</para> 4371 4372<para> 4373Of course one could hack things with one's own scripts. But then there is CUPS. CUPS supports quotas that can 4374be based on the size of jobs or on the number of pages or both, and can span any time period you want. 4375</para> 4376 4377<sect2> 4378<title>Setting Up Quotas</title> 4379 4380<para> 4381<indexterm><primary>CUPS</primary><secondary>quotas</secondary></indexterm> 4382This is an example command of how root would set a print quota in CUPS, assuming an existing printer named 4383<quote>quotaprinter</quote>: 4384<indexterm><primary>lpadmin</primary></indexterm> 4385<screen> 4386&rootprompt;<userinput>lpadmin -p quotaprinter -o job-quota-period=604800 \ 4387 -o job-k-limit=1024 -o job-page-limit=100</userinput> 4388</screen></para> 4389 4390<para> 4391This would limit every single user to print no more than 100 pages or 1024 KB of 4392data (whichever comes first) within the last 604,800 seconds ( = 1 week). 4393</para> 4394</sect2> 4395 4396<sect2> 4397<title>Correct and Incorrect Accounting</title> 4398 4399<para> 4400For CUPS to count correctly, the printfile needs to pass the CUPS pstops filter; otherwise it uses a dummy 4401count of <quote>one</quote>. Some print files do not pass it (e.g., image files), but then those are mostly 4402one-page jobs anyway. This also means that proprietary drivers for the target printer running on the client 4403computers and CUPS/Samba, which then spool these files as <quote>raw</quote> (i.e., leaving them untouched, 4404not filtering them), will be counted as one-pagers too! 4405</para> 4406 4407<para> 4408You need to send PostScript from the clients (i.e., run a PostScript driver there) to have the chance to get 4409accounting done. If the printer is a non-PostScript model, you need to let CUPS do the job to convert the file 4410to a print-ready format for the target printer. This is currently working for about a thousand different 4411printer models. Linuxprinting.org has a driver <ulink url="http://www.linuxprinting.org/printer_list.cgi">list</ulink>. 4412</para> 4413</sect2> 4414 4415<sect2> 4416<title>Adobe and CUPS PostScript Drivers for Windows Clients</title> 4417 4418<para> 4419<indexterm><primary>Adobe PostScript</primary></indexterm> 4420<indexterm><primary>pstops</primary></indexterm> 4421<indexterm><primary>PPD</primary></indexterm> 4422<indexterm><primary>pstoraster</primary></indexterm> 4423<indexterm><primary>PJL-header</primary></indexterm> 4424Before CUPS 1.1.16, your only option was to use the Adobe PostScript driver on the Windows clients. The output 4425of this driver was not always passed through the <command>pstops</command> filter on the CUPS/Samba side, and 4426therefore was not counted correctly (the reason is that it often, depending on the PPD being used, wrote a 4427PJL-header in front of the real PostScript, which caused CUPS to skip <command>pstops</command> and go 4428directly to the <command>pstoraster</command> stage). 4429</para> 4430 4431<para> 4432From CUPS 1.1.16 and later releases, you can use the CUPS PostScript driver for Windows NT/200x/XP 4433clients (which is tagged in the download area of <filename>http://www.cups.org/</filename> as the 4434<filename>cups-samba-1.1.16.tar.gz</filename> package). It does <emphasis>not</emphasis> work for Windows 44359x/Me clients, but it guarantees: 4436</para> 4437 4438<itemizedlist> 4439 <listitem><para> <indexterm><primary>PJL</primary></indexterm> To not write a PJL-header.</para></listitem> 4440 4441 <listitem><para>To still read and support all PJL-options named in the 4442 driver PPD with its own means.</para></listitem> 4443 4444 <listitem><para>That the file will pass through the <command>pstops</command> filter 4445 on the CUPS/Samba server.</para></listitem> 4446 4447 <listitem><para>To page-count correctly the print file.</para></listitem> 4448</itemizedlist> 4449 4450<para> 4451You can read more about the setup of this combination in the man page for <command>cupsaddsmb</command> (which 4452is only present with CUPS installed, and only current from CUPS 1.1.16). 4453</para> 4454</sect2> 4455 4456<sect2> 4457<title>The page_log File Syntax</title> 4458 4459<para> 4460<indexterm><primary>page_log</primary></indexterm> 4461These are the items CUPS logs in the <filename>page_log</filename> for every page of a job: 4462</para> 4463 4464<itemizedlist> 4465 <listitem><para>Printer name</para></listitem> 4466 4467 <listitem><para>User name</para></listitem> 4468 4469 <listitem><para>Job ID</para></listitem> 4470 4471 <listitem><para>Time of printing</para></listitem> 4472 4473 <listitem><para>Page number</para></listitem> 4474 4475 <listitem><para>Number of copies</para></listitem> 4476 4477 <listitem><para>A billing information string (optional)</para></listitem> 4478 4479 <listitem><para>The host that sent the job (included since version 1.1.19)</para></listitem> 4480</itemizedlist> 4481 4482<para> 4483Here is an extract of my CUPS server's <filename>page_log</filename> file to illustrate the 4484format and included items: 4485</para> 4486 4487<para><screen> 4488tec_IS2027 kurt 401 [22/Apr/2003:10:28:43 +0100] 1 3 #marketing 10.160.50.13 4489tec_IS2027 kurt 401 [22/Apr/2003:10:28:43 +0100] 2 3 #marketing 10.160.50.13 4490tec_IS2027 kurt 401 [22/Apr/2003:10:28:43 +0100] 3 3 #marketing 10.160.50.13 4491tec_IS2027 kurt 401 [22/Apr/2003:10:28:43 +0100] 4 3 #marketing 10.160.50.13 4492Dig9110 boss 402 [22/Apr/2003:10:33:22 +0100] 1 440 finance-dep 10.160.51.33 4493</screen></para> 4494 4495<para> 4496This was job ID <parameter>401</parameter>, printed on <parameter>tec_IS2027</parameter> 4497by user <parameter>kurt</parameter>, a 64-page job printed in three copies, billed to 4498<parameter>#marketing</parameter>, and sent from IP address <constant>10.160.50.13.</constant> 4499 The next job had ID <parameter>402</parameter>, was sent by user <parameter>boss</parameter> 4500from IP address <constant>10.160.51.33</constant>, printed from one page 440 copies, and 4501is set to be billed to <parameter>finance-dep</parameter>. 4502</para> 4503</sect2> 4504 4505<sect2> 4506<title>Possible Shortcomings</title> 4507 4508<para> 4509What flaws or shortcomings are there with this quota system? 4510</para> 4511 4512<itemizedlist> 4513 <listitem><para>The ones named above (wrongly logged job in case of 4514 printer hardware failure, and so on).</para></listitem> 4515 4516 <listitem><para>In reality, CUPS counts the job pages that are being 4517 processed in <emphasis>software</emphasis> (that is, going through the 4518 RIP) rather than the physical sheets successfully leaving the 4519 printing device. Thus, if there is a jam while printing the fifth sheet out 4520 of 1,000 and the job is aborted by the printer, the page count will 4521 still show the figure of 1,000 for that job.</para></listitem> 4522 4523 <listitem><para>All quotas are the same for all users (no flexibility 4524 to give the boss a higher quota than the clerk) and no support for 4525 groups.</para></listitem> 4526 4527 <listitem><para>No means to read out the current balance or the 4528 <quote>used-up</quote> number of current quota.</para></listitem> 4529 4530 <listitem><para>A user having used up 99 sheets of a 100 quota will 4531 still be able to send and print a 1,000 sheet job.</para></listitem> 4532 4533 <listitem><para>A user being denied a job because of a filled-up quota 4534 does not get a meaningful error message from CUPS other than 4535 <quote>client-error-not-possible</quote>.</para></listitem> 4536</itemizedlist> 4537</sect2> 4538 4539<sect2> 4540<title>Future Developments</title> 4541 4542<para> 4543This is the best system currently available, and there are huge 4544improvements under development for CUPS 1.2: 4545</para> 4546 4547<itemizedlist> 4548 <listitem><para>Page counting will go into the backends (these talk 4549 directly to the printer and will increase the count in sync with the 4550 actual printing process; thus, a jam at the fifth sheet will lead to a 4551 stop in the counting).</para></listitem> 4552 4553 <listitem><para>Quotas will be handled more flexibly.</para></listitem> 4554 4555 <listitem><para>Probably there will be support for users to inquire 4556 about their accounts in advance.</para></listitem> 4557 4558 <listitem><para>Probably there will be support for some other tools 4559 around this topic.</para></listitem> 4560</itemizedlist> 4561</sect2> 4562 4563<sect2> 4564<title>Other Accounting Tools</title> 4565 4566<para> 4567Other accounting tools that can be used includes: PrintAnalyzer, pyKota, printbill, LogReport. 4568For more information regarding these tools you can try a Google search. 4569</para> 4570 4571</sect2> 4572</sect1> 4573 4574<sect1> 4575<title>Additional Material</title> 4576 4577<para> 4578A printer queue with <emphasis>no</emphasis> PPD associated to it is a 4579<quote>raw</quote> printer, and all files will go directly there as received by the 4580spooler. The exceptions are file types <parameter>application/octet-stream</parameter> 4581that need the pass-through feature enabled. <quote>Raw</quote> queues do not do any 4582filtering at all; they hand the file directly to the CUPS backend. 4583This backend is responsible for sending the data to the device 4584(as in the <quote>device URI</quote> notation: <filename>lpd://, socket://, 4585smb://, ipp://, http://, parallel:/, serial:/, usb:/</filename>, and so on). 4586</para> 4587 4588<para> 4589cupsomatic/Foomatic are <emphasis>not</emphasis> native CUPS drivers 4590and they do not ship with CUPS. They are a third-party add-on 4591developed at Linuxprinting.org. As such, they are a brilliant hack to 4592make all models (driven by Ghostscript drivers/filters in traditional 4593spoolers) also work via CUPS, with the same (good or bad!) quality as 4594in these other spoolers. <parameter>cupsomatic</parameter> is only a vehicle to execute a 4595Ghostscript command line at that stage in the CUPS filtering chain 4596where normally the native CUPS <parameter>pstoraster</parameter> filter would kick 4597in. <parameter>cupsomatic</parameter> bypasses <parameter>pstoraster</parameter>, kidnaps the print file from CUPS, 4598and redirects it to go through Ghostscript. CUPS accepts this 4599because the associated cupsomatic/foomatic-PPD specifies: 4600 4601<programlisting> 4602*cupsFilter: "application/vnd.cups-postscript 0 cupsomatic" 4603</programlisting> 4604 4605This line persuades CUPS to hand the file to <parameter>cupsomatic</parameter> once it has 4606successfully converted it to the MIME type 4607<parameter>application/vnd.cups-postscript</parameter>. This conversion will not happen for 4608jobs arriving from Windows that are autotyped 4609<parameter>application/octet-stream</parameter>, with the according changes in 4610<filename>/etc/cups/mime.types</filename> in place. 4611</para> 4612 4613<para> 4614CUPS is widely configurable and flexible, even regarding its filtering 4615mechanism. Another workaround in some situations would be to have in 4616<filename>/etc/cups/mime.types</filename> entries as follows: 4617 4618<programlisting> 4619application/postscript application/vnd.cups-raw 0 - 4620application/vnd.cups-postscript application/vnd.cups-raw 0 - 4621</programlisting> 4622 4623This would prevent all PostScript files from being filtered (rather, 4624they will through the virtual <emphasis>nullfilter</emphasis> 4625denoted with <quote>-</quote>). This could only be useful for PostScript printers. If you 4626want to print PostScript code on non-PostScript printers (provided they support ASCII 4627text printing), an entry as follows could be useful: 4628 4629<programlisting> 4630*/* application/vnd.cups-raw 0 - 4631</programlisting> 4632 4633and would effectively send <emphasis>all</emphasis> files to the 4634backend without further processing. 4635</para> 4636 4637<para> 4638You could have the following entry: 4639 4640<programlisting> 4641application/vnd.cups-postscript application/vnd.cups-raw 0 \ 4642 my_PJL_stripping_filter 4643</programlisting> 4644 4645You will need to write a <parameter>my_PJL_stripping_filter</parameter> 4646(which could be a shell script) that parses the PostScript and removes the 4647unwanted PJL. This needs to conform to CUPS filter design 4648(mainly, receive and pass the parameters printername, job-id, 4649username, jobtitle, copies, print options, and possibly the 4650filename). It is installed as world executable into 4651<filename>/usr/lib/cups/filters/</filename> and is called by CUPS 4652if it encounters a MIME type <parameter>application/vnd.cups-postscript</parameter>. 4653</para> 4654 4655<para> 4656CUPS can handle <parameter>-o job-hold-until=indefinite</parameter>. 4657This keeps the job in the queue on hold. It will only be printed 4658upon manual release by the printer operator. This is a requirement in 4659many central reproduction departments, where a few operators manage 4660the jobs of hundreds of users on some big machine, where no user is 4661allowed to have direct access (such as when the operators often need 4662to load the proper paper type before running the 10,000 page job 4663requested by marketing for the mailing, and so on). 4664</para> 4665</sect1> 4666 4667<sect1> 4668<title>Autodeletion or Preservation of CUPS Spool Files</title> 4669 4670<para> 4671<indexterm><primary>/var/spool/samba</primary></indexterm> 4672<indexterm><primary>/var/spool/cups/</primary></indexterm> 4673<indexterm><primary>cupsd.conf</primary></indexterm> 4674Samba print files pass through two spool directories. One is the incoming directory managed by Samba (set in 4675the <smbconfoption name="path">/var/spool/samba</smbconfoption> directive in the <smbconfsection 4676name="[printers]"/> section of &smb.conf;). The other is the spool directory of your UNIX print subsystem. For 4677CUPS it is normally <filename>/var/spool/cups/</filename>, as set by the <filename>cupsd.conf</filename> 4678directive <filename>RequestRoot /var/spool/cups</filename>. 4679</para> 4680 4681<sect2> 4682<title>CUPS Configuration Settings Explained</title> 4683 4684<para> 4685Some important parameter settings in the CUPS configuration file 4686<filename>cupsd.conf</filename> are: 4687</para> 4688 4689<variablelist> 4690 4691 <varlistentry><term>PreserveJobHistory Yes</term> 4692 <listitem><para> 4693 This keeps some details of jobs in cupsd's mind (well, it keeps the 4694 c12345, c12346, and so on, files in the CUPS spool directory, which does a 4695 similar job as the old-fashioned BSD-LPD control files). This is set 4696 to <quote>Yes</quote> as a default. 4697 </para></listitem></varlistentry> 4698 4699 <varlistentry><term>PreserveJobFiles Yes</term> 4700 <listitem><para> 4701 This keeps the job files themselves in cupsd's mind 4702 (it keeps the d12345, d12346, etc., files in the CUPS spool 4703 directory). This is set to <quote>No</quote> as the CUPS 4704 default. 4705 </para></listitem></varlistentry> 4706 4707 <varlistentry><term><quote>MaxJobs 500</quote></term> 4708 <listitem><para> 4709 This directive controls the maximum number of jobs 4710 that are kept in memory. Once the number of jobs reaches the limit, 4711 the oldest completed job is automatically purged from the system to 4712 make room for the new one. If all of the known jobs are still 4713 pending or active, then the new job will be rejected. Setting the 4714 maximum to 0 disables this functionality. The default setting is 4715 0. 4716 </para></listitem></varlistentry> 4717</variablelist> 4718 4719<para> 4720(There are also additional settings for <parameter>MaxJobsPerUser</parameter> and 4721<parameter>MaxJobsPerPrinter</parameter>.) 4722</para> 4723</sect2> 4724 4725<sect2> 4726<title>Preconditions</title> 4727 4728<para> 4729For everything to work as it should, you need to have three things: 4730</para> 4731 4732<itemizedlist> 4733 <listitem><para>A Samba smbd that is compiled against <filename>libcups</filename> (check 4734 on Linux by running <userinput>ldd `which smbd'</userinput>).</para></listitem> 4735 4736 <listitem><para>A Samba-&smb.conf; setting of 4737 <smbconfoption name="printing">cups</smbconfoption>.</para></listitem> 4738 4739 <listitem><para>Another Samba &smb.conf; setting of 4740 <smbconfoption name="printcap">cups</smbconfoption>.</para></listitem> 4741</itemizedlist> 4742 4743<note><para> 4744In this case, all other manually set printing-related commands (like 4745<smbconfoption name="print command"/>, 4746<smbconfoption name="lpq command"/>, 4747<smbconfoption name="lprm command"/>, 4748<smbconfoption name="lppause command"/>, and 4749<smbconfoption name="lpresume command"/>) are ignored, and they should normally have no 4750influence whatsoever on your printing. 4751</para></note> 4752</sect2> 4753 4754<sect2> 4755<title>Manual Configuration</title> 4756 4757<para> 4758If you want to do things manually, replace the <smbconfoption name="printing">cups</smbconfoption> 4759by <smbconfoption name="printing">bsd</smbconfoption>. Then your manually set commands may work 4760(I haven't tested this), and a <smbconfoption name="print command">lp -d %P %s; rm %s</smbconfoption> 4761may do what you need. 4762</para> 4763</sect2> 4764</sect1> 4765 4766<sect1> 4767<title>Printing from CUPS to Windows-Attached Printers</title> 4768 4769<para> 4770<indexterm><primary>smbspool</primary></indexterm> 4771<indexterm><primary>backends</primary></indexterm> 4772From time to time the question arises, how can you print <emphasis>to</emphasis> a Windows-attached printer 4773<emphasis>from</emphasis> Samba? Normally the local connection from Windows host to printer would be done by 4774USB or parallel cable, but this does not matter to Samba. From here only an SMB connection needs to be opened 4775to the Windows host. Of course, this printer must be shared first. As you have learned by now, CUPS uses 4776<emphasis>backends</emphasis> to talk to printers and other servers. To talk to Windows shared printers, you 4777need to use the <filename>smb</filename> (surprise, surprise!) backend. Check if this is in the CUPS backend 4778directory. This usually resides in <filename>/usr/lib/cups/backend/</filename>. You need to find an 4779<filename>smb</filename> file there. It should be a symlink to <filename>smbspool</filename>, and the file 4780must exist and be executable: 4781<screen> 4782&rootprompt;<userinput>ls -l /usr/lib/cups/backend/</userinput> 4783total 253 4784drwxr-xr-x 3 root root 720 Apr 30 19:04 . 4785drwxr-xr-x 6 root root 125 Dec 19 17:13 .. 4786-rwxr-xr-x 1 root root 10692 Feb 16 21:29 canon 4787-rwxr-xr-x 1 root root 10692 Feb 16 21:29 epson 4788lrwxrwxrwx 1 root root 3 Apr 17 22:50 http -> ipp 4789-rwxr-xr-x 1 root root 17316 Apr 17 22:50 ipp 4790-rwxr-xr-x 1 root root 15420 Apr 20 17:01 lpd 4791-rwxr-xr-x 1 root root 8656 Apr 20 17:01 parallel 4792-rwxr-xr-x 1 root root 2162 Mar 31 23:15 pdfdistiller 4793lrwxrwxrwx 1 root root 25 Apr 30 19:04 ptal -> /usr/sbin/ptal-cups 4794-rwxr-xr-x 1 root root 6284 Apr 20 17:01 scsi 4795lrwxrwxrwx 1 root root 17 Apr 2 03:11 smb -> /usr/bin/smbspool 4796-rwxr-xr-x 1 root root 7912 Apr 20 17:01 socket 4797-rwxr-xr-x 1 root root 9012 Apr 20 17:01 usb 4798 4799&rootprompt;<userinput>ls -l `which smbspool`</userinput> 4800-rwxr-xr-x 1 root root 563245 Dec 28 14:49 /usr/bin/smbspool 4801</screen></para> 4802 4803<para> 4804If this symlink does not exist, create it: 4805<screen> 4806&rootprompt;<userinput>ln -s `which smbspool` /usr/lib/cups/backend/smb</userinput> 4807</screen></para> 4808 4809<para> 4810<indexterm><primary>smbspool</primary></indexterm> 4811<indexterm><primary>troubleshooting</primary></indexterm> 4812<command>smbspool</command> was written by Mike Sweet from the CUPS folks. It is included and ships with 4813Samba. It may also be used with print subsystems other than CUPS, to spool jobs to Windows printer shares. To 4814set up printer <replaceable>winprinter</replaceable> on CUPS, you need to have a driver for it. Essentially 4815this means to convert the print data on the CUPS/Samba host to a format that the printer can digest (the 4816Windows host is unable to convert any files you may send). This also means you should be able to print to the 4817printer if it were hooked directly at your Samba/CUPS host. For troubleshooting purposes, this is what you 4818should do to determine if that part of the process chain is in order. Then proceed to fix the network 4819connection/authentication to the Windows host, and so on. 4820</para> 4821 4822<para> 4823To install a printer with the <parameter>smb</parameter> backend on CUPS, use this command: 4824</para> 4825 4826<para><screen> 4827&rootprompt;<userinput>lpadmin -p winprinter -v smb://WINDOWSNETBIOSNAME/printersharename \ 4828 -P /path/to/PPD</userinput> 4829</screen></para> 4830 4831<para> 4832<indexterm><primary>PostScript printers</primary></indexterm> 4833<indexterm><primary>PPD</primary></indexterm> 4834<indexterm><primary>Windows NT PostScript driver</primary></indexterm> 4835The PPD must be able to direct CUPS to generate the print data for the target model. For PostScript printers, 4836just use the PPD that would be used with the Windows NT PostScript driver. But what can you do if the printer 4837is only accessible with a password? Or if the printer's host is part of another workgroup? This is provided 4838for: You can include the required parameters as part of the <filename>smb://</filename> device-URI like this: 4839</para> 4840 4841<itemizedlist> 4842 <listitem><para><filename>smb://WORKGROUP/WINDOWSNETBIOSNAME/printersharename</filename></para></listitem> 4843 <listitem><para><filename>smb://username:password@WORKGROUP/WINDOWSNETBIOSNAME/printersharename</filename></para></listitem> 4844 <listitem><para><filename>smb://username:password@WINDOWSNETBIOSNAME/printersharename</filename></para></listitem> 4845</itemizedlist> 4846 4847<para> 4848Note that the device URI will be visible in the process list of the Samba server (e.g., when someone uses the 4849<command>ps -aux</command> command on Linux), even if the username and passwords are sanitized before they get 4850written into the log files. This is an inherently insecure option; however, it is the only one. Don't use it 4851if you want to protect your passwords. Better share the printer in a way that does not require a password! 4852Printing will only work if you have a working NetBIOS name resolution up and running. Note that this is a 4853feature of CUPS and you do not necessarily need to have smbd running. 4854 4855</para> 4856</sect1> 4857 4858<sect1> 4859<title>More CUPS Filtering Chains</title> 4860 4861<para> 4862The diagrams in <link linkend="cups1">Filtering Chain 1</link> and <link linkend="cups2">Filtering Chain with 4863cupsomatic</link> show how CUPS handles print jobs. 4864</para> 4865 4866<figure id="cups1"> 4867 <title>Filtering Chain 1.</title> 4868 <imagefile>cups1</imagefile> 4869</figure> 4870 4871<!-- JJJ --> 4872<figure id="cups2"> 4873 <title>Filtering Chain with cupsomatic</title> 4874 <imagefile scale="45">cups2</imagefile> 4875</figure> 4876 4877</sect1> 4878 4879<sect1> 4880<title>Common Errors</title> 4881 4882 <sect2> 4883 <title>Windows 9x/Me Client Can't Install Driver</title> 4884 4885 <para>For Windows 9x/Me, clients require the printer names to be eight 4886 characters (or <quote>8 plus 3 chars suffix</quote>) max; otherwise, the driver files 4887 will not get transferred when you want to download them from Samba.</para> 4888 4889 </sect2> 4890 4891 <sect2 id="root-ask-loop"> 4892 <title><quote>cupsaddsmb</quote> Keeps Asking for Root Password in Never-ending Loop</title> 4893 4894 <para>Have you set <smbconfoption name="security">user</smbconfoption>? Have 4895 you used <command>smbpasswd</command> to give root a Samba account? 4896 You can do two things: open another terminal and execute 4897 <command>smbpasswd -a root</command> to create the account and 4898 continue entering the password into the first terminal. Or, break 4899 out of the loop by pressing Enter twice (without trying to type a 4900 password).</para> 4901 4902 <para> 4903 If the error is <quote>Tree connect failed: NT_STATUS_BAD_NETWORK_NAME</quote>, 4904 you may have forgotten to create the <filename>/etc/samba/drivers</filename> directory. 4905 </para> 4906 </sect2> 4907 4908 <sect2> 4909 <title><quote>cupsaddsmb</quote> or <quote>rpcclient addriver</quote> Emit Error</title> 4910 4911 <para> 4912 If <command>cupsaddsmb</command>, or <command>rpcclient addriver</command> emit the error message 4913 WERR_BAD_PASSWORD, refer to <link linkend="root-ask-loop">the previous common error</link>. 4914 </para> 4915 4916 </sect2> 4917 4918 <sect2> 4919 <title><quote>cupsaddsmb</quote> Errors</title> 4920 4921 <para> 4922 The use of <quote>cupsaddsmb</quote> gives <quote>No PPD file for printer...</quote> 4923 message while PPD file is present. What might the problem be? 4924 </para> 4925 4926 <para> 4927 Have you enabled printer sharing on CUPS? This means, do you have a <literal><Location 4928 /printers>....</Location></literal> section in CUPS server's <filename>cupsd.conf</filename> that 4929 does not deny access to the host you run <quote>cupsaddsmb</quote> from? It <emphasis>could</emphasis> be an 4930 issue if you use cupsaddsmb remotely, or if you use it with a <option>-h</option> parameter: 4931 <userinput>cupsaddsmb -H sambaserver -h cupsserver -v printername</userinput>. 4932 </para> 4933 4934 <para>Is your <parameter>TempDir</parameter> directive in 4935 <filename>cupsd.conf</filename> set to a valid value, and is it writable? 4936 </para> 4937 4938 </sect2> 4939 4940 <sect2> 4941 <title>Client Can't Connect to Samba Printer</title> 4942 4943 <para>Use <command>smbstatus</command> to check which user 4944 you are from Samba's point of view. Do you have the privileges to 4945 write into the <smbconfsection name="[print$]"/> 4946 share?</para> 4947 4948 </sect2> 4949 4950 <sect2> 4951 <title>New Account Reconnection from Windows 200x/XP Troubles</title> 4952 4953<para> 4954Once you are connected as the wrong user (for example, as <constant>nobody</constant>, which often occurs if 4955you have <smbconfoption name="map to guest">bad user</smbconfoption>), Windows Explorer will not accept an 4956attempt to connect again as a different user. There will not be any bytes transferred on the wire to Samba, 4957but still you'll see a stupid error message that makes you think Samba has denied access. Use 4958<command>smbstatus</command> to check for active connections. Kill the PIDs. You still can't re-connect, and 4959you get the dreaded <computeroutput>You can't connect with a second account from the same 4960machine</computeroutput> message as soon as you try. And you do not see a single byte arriving at Samba (see 4961logs; use <quote>ethereal</quote>) indicating a renewed connection attempt. Shut all Explorer Windows. This 4962makes Windows forget what it has cached in its memory as established connections. Then reconnect as the right 4963user. The best method is to use a DOS terminal window and <emphasis>first</emphasis> do <userinput>net use z: 4964\\&example.server.samba;\print$ /user:root</userinput>. Check with <command>smbstatus</command> that you are 4965connected under a different account. Now open the <guilabel>Printers</guilabel> folder (on the Samba server in 4966the <guilabel>Network Neighborhood</guilabel>), right-click on the printer in question, and select 4967<guibutton>Connect....</guibutton>. 4968</para> 4969</sect2> 4970 4971<sect2> 4972<title>Avoid Being Connected to the Samba Server as the Wrong User</title> 4973 4974<para> 4975<indexterm><primary>smbstatus</primary></indexterm> 4976You see per <command>smbstatus</command> that you are connected as user nobody, but you want to be root or 4977printer admin. This is probably due to <smbconfoption name="map to guest">bad user</smbconfoption>, which 4978silently connected you under the guest account when you gave (maybe by accident) an incorrect username. Remove 4979<smbconfoption name="map to guest"/> if you want to prevent this. 4980</para> 4981</sect2> 4982 4983<sect2> 4984<title>Upgrading to CUPS Drivers from Adobe Drivers</title> 4985 4986<para> 4987This information came from a mailing list posting regarding problems experienced when 4988upgrading from Adobe drivers to CUPS drivers on Microsoft Windows NT/200x/XP clients. 4989</para> 4990 4991<para>First delete all old Adobe-using printers. Then delete all old Adobe drivers. (On Windows 200x/XP, right-click in 4992the background of <guilabel>Printers</guilabel> folder, select <guimenuitem>Server Properties...</guimenuitem>, select 4993tab <guilabel>Drivers</guilabel>, and delete here).</para> 4994</sect2> 4995 4996<sect2> 4997<title>Can't Use <quote>cupsaddsmb</quote> on Samba Server, Which Is a PDC</title> 4998 4999<para>Do you use the <quote>naked</quote> root user name? Try to do it 5000this way: <userinput>cupsaddsmb -U <replaceable>DOMAINNAME</replaceable>\\root -v 5001<replaceable>printername</replaceable></userinput>> (note the two backslashes: the first one is 5002required to <quote>escape</quote> the second one).</para> 5003 5004</sect2> 5005 5006<sect2> 5007<title>Deleted Windows 200x Printer Driver Is Still Shown</title> 5008 5009<para>Deleting a printer on the client will not delete the 5010driver too (to verify, right-click on the white background of the 5011<guilabel>Printers</guilabel> folder, select <guimenuitem>Server Properties</guimenuitem> and click on the 5012<guilabel>Drivers</guilabel> tab). These same old drivers will be re-used when you try to 5013install a printer with the same name. If you want to update to a new 5014driver, delete the old ones first. Deletion is only possible if no 5015other printer uses the same driver.</para> 5016</sect2> 5017 5018<sect2> 5019<title>Windows 200x/XP Local Security Policies</title> 5020 5021<indexterm><primary>Local security policies</primary></indexterm> 5022<indexterm><primary>unsigned drivers</primary></indexterm> 5023<para>Local security policies may not allow the installation of unsigned drivers &smbmdash; <quote>local 5024security policies</quote> may not allow the installation of printer drivers at all.</para> 5025 5026</sect2> 5027 5028<sect2> 5029<title>Administrator Cannot Install Printers for All Local Users</title> 5030 5031<para> 5032<indexterm><primary>SMB printers</primary></indexterm> 5033<indexterm><primary>IPP client</primary></indexterm> 5034Windows XP handles SMB printers on a <quote>per-user</quote> basis. 5035This means every user needs to install the printer himself or herself. To have a printer available for 5036everybody, you might want to use the built-in IPP client capabilities of Win XP. Add a printer with the print 5037path of <parameter>http://cupsserver:631/printers/printername</parameter>. We're still looking into this one. 5038Maybe a logon script could automatically install printers for all users. 5039</para> 5040 5041</sect2> 5042 5043<sect2> 5044<title>Print Change, Notify Functions on NT Clients</title> 5045 5046<para>For print change, notify functions on NT++ clients. These need to run the <command>Server</command> 5047service first (renamed to <command>File & Print Sharing for MS Networks</command> in XP).</para> 5048 5049</sect2> 5050 5051<sect2> 5052<title>Windows XP SP1</title> 5053 5054<para>Windows XP SP1 introduced a Point and Print Restriction Policy (this restriction does not apply to 5055<quote>Administrator</quote> or <quote>Power User</quote> groups of users). In Group Policy Object Editor, go 5056to <guimenu>User Configuration -> Administrative Templates -> Control Panel -> Printers</guimenu>. The policy 5057is automatically set to <constant>Enabled</constant> and the <constant>Users can only Point and Print to 5058machines in their Forest</constant> . You probably need to change it to <constant>Disabled</constant> or 5059<constant>Users can only Point and Print to these servers</constant> to make driver downloads from Samba 5060possible. 5061</para> 5062</sect2> 5063 5064<sect2> 5065<title>Print Options for All Users Can't Be Set on Windows 200x/XP</title> 5066 5067<para>How are you doing it? I bet the wrong way (it is not easy to find out, though). There are three 5068different ways to bring you to a dialog that <emphasis>seems</emphasis> to set everything. All three dialogs 5069<emphasis>look</emphasis> the same, yet only one of them does what you intend. You need to be Administrator or 5070Print Administrator to do this for all users. Here is how I do it on XP: 5071</para> 5072 5073<orderedlist numeration="upperalpha"> 5074 5075 <listitem><para>The first wrong way: 5076 5077 <orderedlist> 5078 <listitem><para>Open the <guilabel>Printers</guilabel> 5079 folder.</para></listitem> 5080 5081 <listitem><para>Right-click on the printer 5082 (<guilabel>remoteprinter on cupshost</guilabel>) and 5083 select in context menu <guimenuitem>Printing 5084 Preferences...</guimenuitem></para></listitem>. 5085 5086 <listitem><para>Look at this dialog closely and remember what it looks like.</para></listitem> 5087 </orderedlist> 5088 </para></listitem> 5089 5090 <listitem><para>The second wrong way: 5091 <orderedlist> 5092 <listitem><para>Open the <guilabel>Printers</guilabel> folder.</para></listitem> 5093 5094 <listitem><para>Right-click on the printer (<guilabel>remoteprinter on 5095 cupshost</guilabel>) and select the context menu 5096 <guimenuitem>Properties</guimenuitem>.</para></listitem> 5097 5098 <listitem><para>Click on the <guilabel>General</guilabel> tab.</para></listitem> 5099 5100 <listitem><para>Click on the button <guibutton>Printing 5101 Preferences...</guibutton></para></listitem>. 5102 5103 <listitem><para>A new dialog opens. Keep this dialog open and go back 5104 to the parent dialog.</para></listitem> 5105 </orderedlist> 5106 </para></listitem> 5107 5108 <listitem><para>The third and correct way: 5109 <orderedlist> 5110 <listitem><para>Open the <guilabel>Printers</guilabel> folder.</para></listitem> 5111 5112 <listitem><para>Right-click on the printer (<guilabel>remoteprinter on 5113 cupshost</guilabel>) and select the context menu 5114 <guimenuitem>Properties</guimenuitem>.</para></listitem> 5115 5116 <listitem><para>Click on the <guilabel>Advanced</guilabel> 5117 tab. (If everything is <quote>grayed out,</quote> then you are not logged 5118 in as a user with enough privileges).</para></listitem> 5119 5120 <listitem><para>Click on the <guibutton>Printing 5121 Defaults...</guibutton> button.</para></listitem> 5122 5123 <listitem><para>On any of the two new tabs, click on the 5124 <guibutton>Advanced...</guibutton> button.</para></listitem> 5125 5126 <listitem><para>A new dialog opens. Compare this one to the other 5127 identical-looking one from step <quote>B.5</quote> or A.3".</para></listitem> 5128 </orderedlist> 5129 </para></listitem> 5130</orderedlist> 5131 5132<para> 5133Do you see any difference? I don't either. However, only the last one, which you arrived at with steps 5134<quote>C.1. to C.6.</quote>, will save any settings permanently and be the defaults for new users. If you want 5135all clients to get the same defaults, you need to conduct these steps <emphasis>as Administrator</emphasis> 5136(<smbconfoption name="printer admin"/> in &smb.conf;) <emphasis>before</emphasis> a client downloads the 5137driver (the clients can later set their own <emphasis>per-user defaults</emphasis> by following the procedures 5138<emphasis>A</emphasis> or <emphasis>B</emphasis>). 5139</para> 5140 5141</sect2> 5142 5143<sect2> 5144<title>Most Common Blunders in Driver Settings on Windows Clients</title> 5145 5146<para> 5147Don't use <parameter>Optimize for Speed</parameter>, but use <parameter>Optimize for Portability</parameter> 5148instead (Adobe PS Driver). Don't use <parameter>Page Independence: No</parameter>. Always settle with 5149<parameter>Page Independence: Yes</parameter> (Microsoft PS Driver and CUPS PS Driver for Windows NT/200x/XP). 5150If there are problems with fonts, use <parameter>Download as Softfont into printer</parameter> (Adobe PS 5151Driver). For <guilabel>TrueType Download Options</guilabel> choose <constant>Outline</constant>. Use 5152PostScript Level 2 if you are having trouble with a non-PS printer and if there is a choice. 5153</para> 5154 5155</sect2> 5156 5157<sect2> 5158<title><command>cupsaddsmb</command> Does Not Work with Newly Installed Printer</title> 5159 5160<para> 5161Symptom: The last command of <command>cupsaddsmb</command> does not complete successfully. If the <command>cmd 5162= setdriver printername printername</command> result was NT_STATUS_UNSUCCESSFUL, then possibly the printer was 5163not yet recognized by Samba. Did it show up in Network Neighborhood? Did it show up in <command>rpcclient 5164hostname -c `enumprinters'</command>? Restart smbd (or send a <command>kill -HUP</command> to all processes 5165listed by <command>smbstatus</command>, and try again. 5166</para></sect2> 5167 5168<sect2> 5169<title>Permissions on <filename>/var/spool/samba/</filename> Get Reset After Each Reboot</title> 5170 5171<para> 5172Have you ever by accident set the CUPS spool directory to the same location (<parameter>RequestRoot 5173/var/spool/samba/</parameter> in <filename>cupsd.conf</filename> or the other way round: 5174<filename>/var/spool/cups/</filename> is set as <smbconfoption name="path"/>> in the <smbconfsection 5175name="[printers]"/> section)? These <parameter>must</parameter> be different. Set <parameter>RequestRoot 5176/var/spool/cups/</parameter> in <filename>cupsd.conf</filename> and <smbconfoption name="path"> 5177/var/spool/samba</smbconfoption> in the <smbconfsection name="[printers]"/> section of &smb.conf;. Otherwise, 5178cupsd will sanitize permissions to its spool directory with each restart and printing will not work reliably. 5179</para> 5180 5181</sect2> 5182 5183<sect2> 5184<title>Print Queue Called <quote>lp</quote> Mishandles Print Jobs</title> 5185 5186<para> 5187In this case a print queue called <quote>lp</quote> intermittently swallows jobs and 5188spits out completely different ones from what was sent. 5189</para> 5190 5191<para> 5192<indexterm><primary>lp</primary></indexterm> 5193<indexterm><primary>Implicit Classes</primary></indexterm> 5194<indexterm><primary>BrowseShortNames</primary></indexterm> 5195It is a bad idea to name any printer <quote>lp</quote>. This is the traditional UNIX name for the default 5196printer. CUPS may be set up to do an automatic creation of Implicit Classes. This means, to group all printers 5197with the same name to a pool of devices and load-balance the jobs across them in a round-robin fashion. 5198Chances are high that someone else has a printer named <quote>lp</quote> too. You may receive that person's 5199jobs and send your own to his or her device unwittingly. To have tight control over the printer names, set 5200<parameter>BrowseShortNames No</parameter>. It will present any printer as 5201<replaceable>printername@cupshost</replaceable>, which gives you better control over what may happen in a 5202large networked environment. 5203</para> 5204 5205</sect2> 5206 5207<sect2> 5208<title>Location of Adobe PostScript Driver Files for <quote>cupsaddsmb</quote></title> 5209 5210<para> 5211Use <command>smbclient</command> to connect to any Windows box with a shared PostScript printer: 5212<command>smbclient //windowsbox/print\$ -U guest</command>. You can navigate to the 5213<filename>W32X86/2</filename> subdir to <command>mget ADOBE*</command> and other files or to 5214<filename>WIN40/0</filename> to do the same. Another option is to download the <filename>*.exe</filename> 5215packaged files from the Adobe Web site. 5216</para> 5217 5218</sect2> 5219 5220</sect1> 5221 5222<sect1> 5223<title>Overview of the CUPS Printing Processes</title> 5224 5225<para> 5226A complete overview of the CUPS printing processes can be found in <link linkend="a_small">the CUPS 5227Printing Overview diagram</link>. 5228</para> 5229 5230<figure id="a_small"> 5231 <title>CUPS Printing Overview.</title> 5232 <imagefile scale="45">a_small</imagefile> 5233</figure> 5234</sect1> 5235 5236</chapter> 5237