diff options
Diffstat (limited to 'docs/docbook/projdoc/CUPS-printing.xml')
| -rw-r--r-- | docs/docbook/projdoc/CUPS-printing.xml | 5406 |
1 files changed, 0 insertions, 5406 deletions
diff --git a/docs/docbook/projdoc/CUPS-printing.xml b/docs/docbook/projdoc/CUPS-printing.xml deleted file mode 100644 index 5a8e9f5846..0000000000 --- a/docs/docbook/projdoc/CUPS-printing.xml +++ /dev/null @@ -1,5406 +0,0 @@ -<chapter id="CUPS-printing"> - -<chapterinfo> - - <author> - <firstname>Kurt</firstname><surname>Pfeifle</surname> - <affiliation> - <orgname>Danka Deutschland GmbH </orgname> - <address><email>kpfeifle@danka.de</email></address> - </affiliation> - </author> - <author> - <firstname>Ciprian</firstname><surname>Vizitiu</surname> - <affiliation> - <address><email>CVizitiu@gbif.org</email></address> - </affiliation> - <contrib>drawings</contrib> - </author> - - <author>&person.jelmer;<contrib>drawings</contrib></author> - - <pubdate> (3 June 2003) </pubdate> -</chapterinfo> - -<title>CUPS Printing Support</title> - -<sect1> - - <title>Introduction</title> - - <sect2> - <title>Features and Benefits</title> - - <para> - The Common UNIX Print System (<ulink url="http://www.cups.org/">CUPS</ulink>) - has become quite popular. All major Linux distributions now ship it as their default printing - system. To many, it is still a mystical tool. Mostly, it just works. - People tend to regard it as a <quote>black box</quote> - that they do not want to look into as long as it works. But once - there is a little problem, they are in trouble to find out where to - start debugging it. Refer to the chapter <quote>Classical Printing</quote> that - contains a lot of information that is relevant for CUPS. - </para> - - <para> - CUPS sports quite a few unique and powerful features. While their - basic functions may be grasped quite easily, they are also - new. Because they are different from other, more traditional printing - systems, it is best not to try and apply any prior knowledge about - printing to this new system. Rather, try to understand CUPS - from the beginning. This documentation will lead you to a - complete understanding of CUPS. Let's start with the most basic - things first. - </para> - - </sect2> - - <sect2> - <title>Overview</title> - - <para> - CUPS is more than just a print spooling system. It is a complete - printer management system that complies with the new - Internet Printing Protocol (IPP). IPP is an industry - and Internet Engineering Task Force (IETF) - standard for network printing. Many of its functions can be managed - remotely (or locally) via a Web browser (giving you a - platform-independent access to the CUPS print server). Additionally, it - has the traditional command line and several more modern GUI interfaces - (GUI interfaces developed by third parties, like KDE's - overwhelming <ulink url="http://printing.kde.org/">KDEPrint</ulink>). - </para> - - <para> - CUPS allows creation of <quote>raw</quote> printers (i.e., no print file - format translation) as well as <quote>smart</quote> printers (i.e., CUPS does - file format conversion as required for the printer). In many ways - this gives CUPS similar capabilities to the MS Windows print - monitoring system. Of course, if you are a CUPS advocate, you would - argue that CUPS is better! In any case, let us now move on to - explore how one may configure CUPS for interfacing with MS Windows - print clients via Samba. - </para> - </sect2> -</sect1> - -<sect1> - <title>Basic CUPS Support Configuration</title> - - <para> - Printing with CUPS in the most basic &smb.conf; setup in Samba-3.0 (as was true for 2.2.x) only needs two - settings: <smbconfoption><name>printing</name><value>cups</value></smbconfoption> and - <smbconfoption><name>printcap</name><value>cups</value></smbconfoption>. CUPS does not need a printcap file. - However, the <filename>cupsd.conf</filename> configuration file knows of two related directives that control - how such a file will be automatically created and maintained by CUPS for the convenience of third-party - applications (example: <parameter>Printcap /etc/printcap</parameter> and <parameter>PrintcapFormat BSD</parameter>). - Legacy programs often require the existence of a printcap file containing printer names or they will refuse to - print. Make sure CUPS is set to generate and maintain a printcap file. For details, see - <command>man cupsd.conf</command> and other CUPS-related documentation, like the wealth of documents on your CUPS server - itself: <ulink noescape="1" url="http://localhost:631/documentation.html">http://localhost:631/documentation.html</ulink>. - </para> - - <sect2> - <title>Linking smbd with libcups.so</title> - - <para> - Samba has a special relationship to CUPS. Samba can be compiled with CUPS library support. - Most recent installations have this support enabled. Per default, CUPS linking is compiled - into smbd and other Samba binaries. Of course, you can use CUPS even - if Samba is not linked against <filename>libcups.so</filename> &smbmdash; but - there are some differences in required or supported configuration. - </para> - - <para> - When Samba is compiled against <filename>libcups</filename>, <smbconfoption><name>printcap</name><value>cups</value></smbconfoption> - uses the CUPS API to list printers, submit jobs, query queues, and so on. Otherwise it maps to the System V - commands with an additional <command>-oraw</command> option for printing. On a Linux - system, you can use the <command>ldd</command> utility to find out details (ldd may not be present on - other OS platforms, or its function may be embodied by a different command): - </para> - -<para><screen> -&rootprompt;<userinput>ldd `which smbd`</userinput> -libssl.so.0.9.6 => /usr/lib/libssl.so.0.9.6 (0x4002d000) -libcrypto.so.0.9.6 => /usr/lib/libcrypto.so.0.9.6 (0x4005a000) -libcups.so.2 => /usr/lib/libcups.so.2 (0x40123000) -[....] -</screen></para> - - <para> - The line <computeroutput>libcups.so.2 => /usr/lib/libcups.so.2 (0x40123000)</computeroutput> shows - there is CUPS support compiled into this version of Samba. If this is the case, and printing = cups - is set, then <emphasis>any otherwise manually set print command in &smb.conf; is ignored</emphasis>. - This is an important point to remember! - </para> - - <tip><para> Should it be necessary, for any reason, to set your own print commands, you can do this by setting - <smbconfoption><name>printing</name><value>sysv</value></smbconfoption>. However, you will loose all the benefits - of tight CUPS/Samba integration. When you do this you must manually configure the printing system commands - (most important: - <smbconfoption><name>print command</name></smbconfoption>; other commands are - <smbconfoption><name>lppause command</name></smbconfoption>, - <smbconfoption><name>lpresume command</name></smbconfoption>, - <smbconfoption><name>lpq command</name></smbconfoption>, - <smbconfoption><name>lprm command</name></smbconfoption>, - <smbconfoption><name>queuepause command</name></smbconfoption> and - <smbconfoption><name>queue resume command</name></smbconfoption>).</para></tip> - </sect2> - - <sect2> - <title>Simple &smb.conf; Settings for CUPS</title> - - <para> - To summarize, <link linkend="cups-exam-simple"/> shows simplest printing-related setup for &smb.conf; to enable basic CUPS support: - </para> - - <para><smbconfexample id="cups-exam-simple"> - <title>Simplest printing-related smb.conf</title> - <smbconfsection>[global]</smbconfsection> - <smbconfoption><name>load printers</name><value>yes</value></smbconfoption> - <smbconfoption><name>printing</name><value>cups</value></smbconfoption> - <smbconfoption><name>printcap name</name><value>cups</value></smbconfoption> - - <smbconfsection>[printers]</smbconfsection> - <smbconfoption><name>comment</name><value>All Printers</value></smbconfoption> - <smbconfoption><name>path</name><value>/var/spool/samba</value></smbconfoption> - <smbconfoption><name>browseable</name><value>no</value></smbconfoption> - <smbconfoption><name>public</name><value>yes</value></smbconfoption> - <smbconfoption><name>guest ok</name><value>yes</value></smbconfoption> - <smbconfoption><name>writable</name><value>no</value></smbconfoption> - <smbconfoption><name>printable</name><value>yes</value></smbconfoption> - <smbconfoption><name>printer admin</name><value>root, @ntadmins</value></smbconfoption> - - </smbconfexample></para> - - <para> - This is all you need for basic printing setup for CUPS. It will print - all graphic, text, PDF, and PostScript files submitted from Windows - clients. However, most of your Windows users would not know how to - send these kinds of files to print without opening a GUI - application. Windows clients tend to have local printer drivers - installed, and the GUI application's print buttons start a printer - driver. Your users also rarely send files from the command - line. Unlike UNIX clients, they hardly submit graphic, text or PDF - formatted files directly to the spooler. They nearly exclusively print - from GUI applications with a <quote>printer driver</quote> hooked in between the - application's native format and the print-data-stream. If the backend - printer is not a PostScript device, the print data stream is <quote>binary,</quote> - sensible only for the target printer. Read on to learn which problem - this may cause and how to avoid it. - </para> - </sect2> - - <sect2> - <title>More Complex CUPS &smb.conf; Settings</title> - - <para> - <link linkend="overridesettings"/> is a slightly more complex printing-related setup - for &smb.conf;. It enables general CUPS printing - support for all printers, but defines one printer share, which is set - up differently. - </para> - - <para><smbconfexample id="overridesettings"> - <title>Overriding global CUPS settings for one printer</title> - <smbconfsection>[global]</smbconfsection> - <smbconfoption><name>printing</name><value>cups</value></smbconfoption> - <smbconfoption><name>printcap name</name><value>cups</value></smbconfoption> - <smbconfoption><name>load printers</name><value>yes</value></smbconfoption> - - <smbconfsection>[printers]</smbconfsection> - <smbconfoption><name>comment</name><value>All Printers</value></smbconfoption> - <smbconfoption><name>path</name><value>/var/spool/samba</value></smbconfoption> - <smbconfoption><name>public</name><value>yes</value></smbconfoption> - <smbconfoption><name>guest ok</name><value>yes</value></smbconfoption> - <smbconfoption><name>writable</name><value>no</value></smbconfoption> - <smbconfoption><name>printable</name><value>yes</value></smbconfoption> - <smbconfoption><name>printer admin</name><value>root, @ntadmins</value></smbconfoption> - - <smbconfsection>[special_printer]</smbconfsection> - <smbconfoption><name>comment</name><value>A special printer with his own settings</value></smbconfoption> - <smbconfoption><name>path</name><value>/var/spool/samba-special</value></smbconfoption> - <smbconfoption><name>printing</name><value>sysv</value></smbconfoption> - <smbconfoption><name>printcap</name><value>lpstat</value></smbconfoption> - <smbconfoption><name>print command</name><value>echo "NEW: `date`: printfile %f" >> /tmp/smbprn.log ; \</value></smbconfoption> - <member><parameter>echo " `date`: p-%p s-%s f-%f" >> /tmp/smbprn.log ; \</parameter></member> - <member><parameter>echo " `date`: j-%j J-%J z-%z c-%c" >> /tmp/smbprn.log : rm %f</parameter></member> - <smbconfoption><name>public</name><value>no</value></smbconfoption> - <smbconfoption><name>guest ok</name><value>no</value></smbconfoption> - <smbconfoption><name>writeable</name><value>no</value></smbconfoption> - <smbconfoption><name>printable</name><value>yes</value></smbconfoption> - <smbconfoption><name>printer admin</name><value>kurt</value></smbconfoption> - <smbconfoption><name>hosts deny</name><value>0.0.0.0</value></smbconfoption> - <smbconfoption><name>hosts allow</name><value>turbo_xp, 10.160.50.23, 10.160.51.60</value></smbconfoption> - </smbconfexample></para> - - <para> - This special share is only there for testing purposes. It does not write the print job to a file. It just logs the job parameters - known to Samba into the <filename>/tmp/smbprn.log</filename> file and deletes the jobfile. Moreover, the - <smbconfoption><name>printer admin</name></smbconfoption> of this share is <quote>kurt</quote> (not the <quote>@ntadmins</quote> group), - guest access is not allowed, the share isn't published to the Network Neighborhood (so you need to know it is there), and it only - allows access from only three hosts. To prevent CUPS kicking in and taking over the print jobs for that share, we need to set - <smbconfoption><name>printing</name><value>sysv</value></smbconfoption> and - <smbconfoption><name>printcap</name><value>lpstat</value></smbconfoption>. - </para> - </sect2> -</sect1> - -<sect1> - <title>Advanced Configuration</title> - - <para> - Before we delve into all the configuration options, let us clarify a few - points. <emphasis>Network printing needs to be organized and setup - correctly</emphasis>. This frequently doesn't happen. Legacy systems - or small business LAN environments often lack design and good housekeeping. - </para> - - - <sect2> - <title>Central Spooling vs. <quote>Peer-to-Peer</quote> Printing</title> - - - <para> -<indexterm><primary>spooling</primary><secondary>central</secondary></indexterm> -<indexterm><primary>spooling</primary><secondary>peer-to-peer</secondary></indexterm> - Many small office or home networks, as well as badly organized larger - environments, allow each client a direct access to available network - printers. This is generally a bad idea. It often blocks one client's - access to the printer when another client's job is printing. It might - freeze the first client's application while it is waiting to get - rid of the job. Also, there are frequent complaints about various jobs - being printed with their pages mixed with each other. A better concept - is the usage of a print server: it routes all jobs through one - central system, which responds immediately, takes jobs from multiple - concurrent clients at the same time, and in turn transfers them to the - printer(s) in the correct order. - </para> - </sect2> - - <sect2> - <title>Raw Print Serving &smbmdash; Vendor Drivers on Windows Clients</title> - - - <para> - <indexterm><primary>spooling-only</primary></indexterm> - <indexterm><primary>"raw" printing</primary></indexterm> - Most traditionally configured UNIX print servers acting on behalf of - Samba's Windows clients represented a really simple setup. Their only - task was to manage the <quote>raw</quote> spooling of all jobs handed to them by - Samba. This approach meant that the Windows clients were expected to - prepare the print job file that its ready to be sent to the printing - device. Here is a native (vendor-supplied) Windows printer - driver for the target device needed to be installed on each and every - client. - </para> - - <para> - It is possible to configure CUPS, Samba and your Windows clients in the - same traditional and simple way. When CUPS printers are configured - for RAW print-through mode operation, it is the responsibility of the - Samba client to fully render the print job (file). The file must be - sent in a format that is suitable for direct delivery to the - printer. Clients need to run the vendor-provided drivers to do - this. In this case, CUPS will not do any print file format conversion - work. - </para> - </sect2> - - <sect2> - <title>Installation of Windows Client Drivers</title> - - <para> - The printer drivers on the Windows clients may be installed - in two functionally different ways: - </para> - - <itemizedlist> - <listitem><para>Manually install the drivers locally on each client, - one by one; this yields the old <emphasis>LanMan</emphasis> style - printing and uses a <filename>\\sambaserver\printershare</filename> - type of connection.</para></listitem> - - - <listitem><para> - <indexterm><primary>point 'n' print</primary></indexterm> - Deposit and prepare the drivers (for later download) on - the print server (Samba); this enables the clients to use - <quote>Point'n'Print</quote> to get drivers semi-automatically installed the - first time they access the printer; with this method NT/200x/XP - clients use the <emphasis>SPOOLSS/MS-RPC</emphasis> - type printing calls.</para></listitem> - </itemizedlist> - - <para> - The second method is recommended for use over the first. - </para> - </sect2> - - <sect2 id="cups-raw"> - <title>Explicitly Enable <quote>raw</quote> Printing for <emphasis>application/octet-stream</emphasis></title> - - - <para> - <indexterm><primary>application/octet-stream</primary></indexterm> - <indexterm><primary>raw printing</primary></indexterm> - <indexterm><primary>MIME</primary><secondary>raw</secondary></indexterm> - If you use the first option (drivers are installed on the client - side), there is one setting to take care of: CUPS needs to be told - that it should allow <quote>raw</quote> printing of deliberate (binary) file - formats. The CUPS files that need to be correctly set for RAW mode - printers to work are: - </para> - - <itemizedlist> - <listitem><para><filename>/etc/cups/mime.types</filename></para></listitem> - <listitem><para><filename>/etc/cups/mime.convs</filename></para></listitem> - </itemizedlist> - - <para> - Both contain entries (at the end of the respective files) which must - be uncommented to allow RAW mode operation. - In <filename>/etc/cups/mime.types</filename>, make sure this line is - present: - - <filterline> - application/octet-stream - </filterline> - - <indexterm><primary>/etc/cups/mime.convs</primary></indexterm> - <indexterm><primary>/etc/cups/mime.types</primary></indexterm> - - In <filename>/etc/cups/mime.convs</filename>, - have this line: - - <indexterm><primary>application/vnd.cups-raw</primary></indexterm> - - <filterline> - application/octet-stream application/vnd.cups-raw 0 - - </filterline> - - If these two files are not set up correctly for raw Windows client - printing, you may encounter the dreaded <computeroutput>Unable to - convert file 0</computeroutput> in your CUPS error_log file. - </para> - - <note><para>Editing the <filename>mime.convs</filename> and the - <filename>mime.types</filename> file does not - <emphasis>enforce</emphasis> <quote>raw</quote> printing, it only - <emphasis>allows</emphasis> it. - </para></note> - - <formalpara><title>Background</title> - - - <para> - <indexterm><primary>application/octet-stream</primary></indexterm> - CUPS being a more security-aware printing system than traditional ones - does not by default allow a user to send deliberate (possibly binary) - data to printing devices. This could be easily abused to launch a - <quote>Denial of Service</quote> attack on your printer(s), causing at least - the loss of a lot of paper and ink. <quote>Unknown</quote> data are tagged by CUPS - as <parameter>MIME type: application/octet-stream</parameter> and not - allowed to go to the printer. By default, you can only send other - (known) MIME types <quote>raw</quote>. Sending data <quote>raw</quote> means that CUPS does not - try to convert them and passes them to the printer untouched (see the next - chapter for even more background explanations). - </para> - </formalpara> - - <para> - This is all you need to know to get the CUPS/Samba combo printing - <quote>raw</quote> files prepared by Windows clients, which have vendor drivers - locally installed. If you are not interested in background information about - more advanced CUPS/Samba printing, simply skip the remaining sections - of this chapter. - </para> - </sect2> - - <sect2> - <title>Driver Upload Methods</title> - - <para> - This section describes three familiar methods, plus one new one, by which - printer drivers may be uploaded. - </para> - - <para> - <indexterm><primary>point 'n' print</primary></indexterm> - If you want to use the MS-RPC type printing, you must upload the - drivers onto the Samba server first (<smbconfsection>[print$]</smbconfsection> - share). For a discussion on how to deposit printer drivers on the - Samba host (so the Windows clients can download and use them via - <quote>Point'n'Print</quote>), please refer to the previous chapter of this - HOWTO Collection. There you will find a description or reference to - three methods of preparing the client drivers on the Samba server: - </para> - <itemizedlist> - <listitem><para> - <indexterm><primary>add printer wizard</primary></indexterm> - The GUI, <quote>Add Printer Wizard</quote> - <emphasis>upload-from-a-Windows-client</emphasis> - method.</para></listitem> - - <listitem><para>The command line, <quote>smbclient/rpcclient</quote> - upload-from-a-UNIX-workstation method.</para></listitem> - - - <listitem><para> - <indexterm><primary>imprints</primary></indexterm> - The Imprints Toolset - method.</para></listitem> - </itemizedlist> - - <para> - These three methods apply to CUPS all the same. A new and more - convenient way to load the Windows drivers into Samba is provided - if you use CUPS: - </para> - - - <itemizedlist> - <listitem><para> - <indexterm><primary>cupsaddsmb</primary></indexterm> - the <parameter>cupsaddsmb</parameter> - utility.</para></listitem> - </itemizedlist> - - <para> - <command>cupsaddsmb</command> is discussed in much detail further below. But we first - explore the CUPS filtering system and compare the Windows and UNIX printing architectures. - </para> - </sect2> -</sect1> - -<sect1> - <title>Advanced Intelligent Printing with PostScript Driver Download</title> - - - <para> - <indexterm><primary>PostScript</primary><seealso>Ghostscript</seealso></indexterm> - We now know - how to set up a <quote>dump</quote> printserver, that is, a server which is spooling - printjobs <quote>raw</quote>, leaving the print data untouched. - </para> - - <para> - Possibly you need to setup CUPS in a smarter way. The reasons could - be manifold: - </para> - - <itemizedlist> - <listitem><para>Maybe your boss wants to get monthly statistics: Which - printer did how many pages? What was the average data size of a job? - What was the average print run per day? What are the typical hourly - peaks in printing? Which department prints how much?</para></listitem> - - <listitem><para>Maybe you are asked to setup a print quota system: - Users should not be able to print more jobs, once they have surpassed - a given limit per period.</para></listitem> - - <listitem><para>Maybe your previous network printing setup is a mess - and must be re-organized from a clean beginning.</para></listitem> - - <listitem><para>Maybe you have experiencing too many <quote>blue screens</quote> - originating from poorly debugged printer drivers running in NT <quote>kernel mode</quote>?</para></listitem> - </itemizedlist> - - <para> - These goals cannot be achieved by a raw print server. To build a - server meeting these requirements, you'll first need to learn about - how CUPS works and how you can enable its features. - </para> - - <para> - What follows is the comparison of some fundamental concepts for - Windows and UNIX printing; then follows a description of the - CUPS filtering system, how it works and how you can tweak it. - </para> - - <sect2 id="gdipost"> - <title>GDI on Windows -- PostScript on UNIX</title> - - - <para> - <indexterm><primary>GDI</primary></indexterm> - <indexterm><primary>PostScript</primary></indexterm> - Network printing is one of the most complicated and error-prone - day-to-day tasks any user or administrator may encounter. This is - true for all OS platforms. And there are reasons for this. - </para> - - - <para> - <indexterm><primary>PCL</primary></indexterm> - <indexterm><primary>PDL</primary></indexterm> - You can't expect most file formats to just throw them toward - printers and they get printed. There needs to be a file format - conversion in between. The problem is that there is no common standard for - print file formats across all manufacturers and printer types. While - PostScript (trademark held by Adobe) and, to an - extent, PCL (trademark held by HP) have developed - into semi-official <quote>standards</quote> by being the most widely used PDLs - Page Description Languages (PDLs), there are still - many manufacturers who <quote>roll their own</quote> (their reasons may be - unacceptable license fees for using printer-embedded PostScript - interpreters, and so on). - </para> - </sect2> - - <sect2> - <title>Windows Drivers, GDI and EMF</title> - - - <para> - <indexterm><primary>GDI</primary></indexterm> - <indexterm><primary>EMF</primary></indexterm> - <indexterm><primary>WYSIWYG</primary></indexterm> - In Windows OS, the format conversion job is done by the printer - drivers. On MS Windows OS platforms all application programmers have - at their disposal a built-in API, the Graphical Device - Interface (GDI), as part and parcel of the OS itself to base - themselves on. This GDI core is used as one common unified ground for - all Windows programs to draw pictures, fonts and documents - <emphasis>on screen</emphasis> as well as <emphasis>on - paper</emphasis> (print). Therefore, printer driver developers can - standardize on a well-defined GDI output for their own driver - input. Achieving WYSIWYG (<quote>What You See Is What You Get</quote>) is - relatively easy, because the on-screen graphic primitives, as well as - the on-paper drawn objects, come from one common source. This source, - the GDI, often produces a file format called Enhanced - MetaFile (EMF). The EMF is processed by the printer driver and - converted to the printer-specific file format. - </para> - - <note><para> - <indexterm><primary>PDF</primary></indexterm> - To the GDI foundation in MS Windows, Apple has chosen to - put paper and screen output on a common foundation for their - (BSD-UNIX-based, did you know?) Mac OS X and Darwin Operating - <indexterm><primary>X Window System</primary></indexterm> - <indexterm><primary>PostScript</primary></indexterm> - <indexterm><primary>PCL</primary></indexterm> - <indexterm><primary>Xprint</primary></indexterm> - Systems. Their <emphasis>Core Graphic Engine</emphasis> uses a - <emphasis>PDF</emphasis> derivative for all display work. - </para></note> - - <para> - - <image><imagedescription>Windows printing to a local printer.</imagedescription><imagefile>1small</imagefile></image> - </para> - </sect2> - - <sect2> - <title>UNIX Printfile Conversion and GUI Basics</title> - - - <para> - <indexterm><primary>X Window System</primary></indexterm> - <indexterm><primary>PostScript</primary></indexterm> - <indexterm><primary>PCL</primary></indexterm> - <indexterm><primary>Xprint</primary></indexterm> - In UNIX and Linux, there is no comparable layer built into the OS - kernel(s) or the X (screen display) server. Every application is - responsible for itself to create its print output. Fortunately, most - use PostScript and that at least gives some common ground. Unfortunately, - there are many different levels of quality for this PostScript. And - worse, there is a huge difference (and no common root) in the way - the same document is displayed on screen and how it is presented on - paper. WYSIWYG is more difficult to achieve. This goes back to the - time, decades ago, when the predecessors of X.org, - designing the UNIX foundations and protocols for Graphical User - Interfaces, refused to take responsibility for <quote>paper output</quote> - also, as some had demanded at the time, and restricted itself to - <quote>on-screen only.</quote> (For some years now, the <quote>Xprint</quote> project has been - under development, attempting to build printing support into the X - framework, including a PostScript and a PCL driver, but it is not yet - ready for prime time.) You can see this unfavorable inheritance up to - the present day by looking into the various <quote>font</quote> directories on your - system; there are separate ones for fonts used for X display and fonts - to be used on paper. - </para> - - <formalpara> - <title>Background</title> - - - <para> - <indexterm><primary>PostScript</primary></indexterm> - The PostScript programming language is an <quote>invention</quote> by Adobe Inc., - but its specifications have been published to the full. Its strength - lies in its powerful abilities to describe graphical objects (fonts, - shapes, patterns, lines, curves, and dots), their attributes (color, - linewidth) and the way to manipulate (scale, distort, rotate, - shift) them. Because of its open specification, anybody with the - skill can start writing his own implementation of a PostScript - interpreter and use it to display PostScript files on screen or on - paper. Most graphical output devices are based on the concept of - <quote>raster images</quote> or <quote>pixels</quote> (one notable exception is pen - plotters). Of course, you can look at a PostScript file in its textual - form and you will be reading its PostScript code, the language - instructions which need to be interpreted by a rasterizer. Rasterizers - produce pixel images, which may be displayed on screen by a viewer - program or on paper by a printer. - </para> - </formalpara> - </sect2> - - <sect2 id="post-and-ghost"> - <title>PostScript and Ghostscript</title> - - - <para> - <indexterm><primary>PostScript</primary></indexterm> - <indexterm><primary>GhostScript</primary><seealso>PostScript</seealso></indexterm> - <indexterm><primary>PostScript</primary><secondary>RIP</secondary></indexterm> - So, UNIX is lacking a common ground for printing on paper and - displaying on screen. Despite this unfavorable legacy for UNIX, basic - printing is fairly easy if you have PostScript printers at your - disposal. The reason is these devices have a built-in PostScript - language <quote>interpreter,</quote> also called a Raster Image - Processor (RIP) (which makes them more expensive than - other types of printers); throw PostScript toward them, and they will - spit out your printed pages. Their RIP is doing all the hard work of - converting the PostScript drawing commands into a bitmap picture as - you see it on paper, in a resolution as done by your printer. This is - no different to PostScript printing a file from a Windows origin. - </para> - - <note><para> - <indexterm><primary>PPD</primary></indexterm> - Traditional UNIX programs and printing systems &smbmdash; while - using PostScript &smbmdash; are largely not PPD-aware. PPDs are <quote>PostScript - Printer Description</quote> files. They enable you to specify and control all - options a printer supports: duplexing, stapling and punching. Therefore, - UNIX users for a long time couldn't choose many of the supported - device and job options, unlike Windows or Apple users. But now there - is CUPS. - </para> - </note> - - <para> - <image><imagedescription>Printing to a PostScript printer.</imagedescription> - <imagefile>2small</imagefile></image> - </para> - - - <para> - <indexterm><primary>PDL</primary></indexterm> - However, there are other types of printers out there. These do not know - how to print PostScript. They use their own Page Description - Language (PDL, often proprietary). To print to them is much - more demanding. Since your UNIX applications mostly produce - PostScript, and since these devices do not understand PostScript, you - need to convert the printfiles to a format suitable for your printer - on the host before you can send it away. - </para> - </sect2> - - <sect2> - <title>Ghostscript &smbmdash; the Software RIP for Non-PostScript Printers</title> - - - <para> - <indexterm><primary>GhostScript</primary></indexterm> - Here is where Ghostscript kicks in. Ghostscript is - the traditional (and quite powerful) PostScript interpreter used on - UNIX platforms. It is a RIP in software, capable of doing a - <emphasis>lot</emphasis> of file format conversions for a very broad - spectrum of hardware devices as well as software file formats. - Ghostscript technology and drivers are what enable PostScript printing - to non-PostScript hardware. - </para> - - <para> - <image><imagedescription>Ghostscript as a RIP for non-postscript printers.</imagedescription> - <imagefile>3small</imagefile> - </image> - </para> - - <tip><para> - Use the <quote>gs -h</quote> command to check for all built-in <quote>devices</quote> - of your Ghostscript version. If you specify a parameter of - <parameter>-sDEVICE=png256</parameter> on your Ghostscript command - line, you are asking Ghostscript to convert the input into a PNG - file. Naming a <quote>device</quote> on the command line is the most important - single parameter to tell Ghostscript exactly how it should render the - input. New Ghostscript versions are released at fairly regular - intervals, now by artofcode LLC. They are initially put under the - <quote>AFPL</quote> license, but re-released under the GNU GPL as soon as the next - AFPL version appears. GNU Ghostscript is probably the version - installed on most Samba systems. But it has some deficiencies. - <indexterm><primary>Ghostscript</primary><secondary>ESP</secondary><see>ESP GhostScript</see></indexterm> - Therefore, ESP Ghostscript was developed as an - enhancement over GNU Ghostscript, with lots of bug-fixes, additional - devices and improvements. It is jointly maintained by developers from - CUPS, Gimp-Print, MandrakeSoft, SuSE, RedHat, and Debian. It includes - the <quote>cups</quote> device (essential to print to non-PS printers from CUPS). - </para></tip> - </sect2> - - <sect2> - <title>PostScript Printer Description (PPD) Specification</title> - - - <para> - <indexterm><primary>PPD</primary></indexterm> - While PostScript in essence is a Page Description - Language (PDL) to represent the page layout in a - device-independent way, real-world print jobs are - always ending up being output on hardware with device-specific - features. To take care of all the differences in hardware and to - allow for innovations, Adobe has specified a syntax and file format - for PostScript Printer Description (PPD) - files. Every PostScript printer ships with one of these files. - </para> - - <para> - PPDs contain all the information about general and special features of the - given printer model: Which different resolutions can it handle? Does - it have a Duplexing Unit? How many paper trays are there? What media - types and sizes does it take? For each item, it also names the special - command string to be sent to the printer (mostly inside the PostScript - file) in order to enable it. - </para> - - <para> - Information from these PPDs is meant to be taken into account by the - printer drivers. Therefore, installed as part of the Windows - PostScript driver for a given printer is the printer's PPD. Where it - makes sense, the PPD features are presented in the drivers' UI dialogs - to display to the user a choice of print options. In the end, the - user selections are somehow written (in the form of special - PostScript, PJL, JCL or vendor-dependent commands) into the PostScript - file created by the driver. - </para> - - <warning><para> - <indexterm><primary>PDF</primary></indexterm> - A PostScript file that was created to contain device-specific commands - for achieving a certain print job output (e.g., duplexed, stapled and - punched) on a specific target machine, may not print as expected, or - may not be printable at all on other models; it also may not be fit - for further processing by software (e.g., by a PDF distilling program). - </para></warning> - </sect2> - - <sect2> - <title>Using Windows-Formatted Vendor PPDs</title> - - <para> - CUPS can handle all spec-compliant PPDs as supplied by the - manufacturers for their PostScript models. Even if a - vendor might not have mentioned our favorite - OS in his manuals and brochures, you can safely trust this: - <emphasis>If you get the Windows NT version of the PPD, you - can use it unchanged in CUPS</emphasis> and thus access the full - power of your printer just like a Windows NT user could! - </para> - - <tip><para> - To check the spec compliance of any PPD online, go to <ulink - noescape="1" url="http://www.cups.org/testppd.php">http://www.cups.org/testppd.php</ulink> - and upload your PPD. You will see the results displayed - immediately. CUPS in all versions after 1.1.19 has a much more strict - internal PPD parsing and checking code enabled; in case of printing - trouble, this online resource should be one of your first pitstops. - </para></tip> - - <warning><para> - <indexterm><primary>foomatic</primary></indexterm> - <indexterm><primary>cupsomatic</primary></indexterm> - For real PostScript printers, <emphasis>do not</emphasis> use the - <emphasis>Foomatic</emphasis> or <emphasis>cupsomatic</emphasis> - PPDs from Linuxprinting.org. With these devices, the original - vendor-provided PPDs are always the first choice! - </para></warning> - - <tip><para> - If you are looking for an original vendor-provided PPD of a specific - device, and you know that an NT4 box (or any other Windows box) on - your LAN has the PostScript driver installed, just use - <command>smbclient //NT4-box/print\$ -U username</command> to - access the Windows directory where all printer driver files are - stored. First look in the <filename>W32X86/2</filename> subdir for - the PPD you are seeking. - </para></tip> - </sect2> - - <sect2> - <title>CUPS Also Uses PPDs for Non-PostScript Printers</title> - - <para> - CUPS also uses specially crafted PPDs to handle non-PostScript - printers. These PPDs are usually not available from the vendors (and - no, you can't just take the PPD of a PostScript printer with the same - model name and hope it works for the non-PostScript version too). To - understand how these PPDs work for non-PS printers, we first need to - dive deeply into the CUPS filtering and file format conversion - architecture. Stay tuned. - </para> - </sect2> -</sect1> - -<sect1> -<title>The CUPS Filtering Architecture</title> - -<para> -The core of the CUPS filtering system is based on -Ghostscript. In addition to Ghostscript, CUPS -uses some other filters of its own. You (or your OS vendor) may have -plugged in even more filters. CUPS handles all data file formats under -the label of various MIME types. Every incoming -printfile is subjected to an initial -auto-typing. The auto-typing determines its given -MIME type. A given MIME type implies zero or more possible filtering -chains relevant to the selected target printer. This section discusses -how MIME types recognition and conversion rules interact. They are -used by CUPS to automatically setup a working filtering chain for any -given input data format. -</para> - -<para> -If CUPS rasterizes a PostScript file natively to -a bitmap, this is done in two stages: -</para> - -<itemizedlist> - <listitem><para>The first stage uses a Ghostscript device named <quote>cups</quote> -(this is since version 1.1.15) and produces a generic raster format -called <quote>CUPS raster</quote>. -</para></listitem> - -<listitem><para>The second stage uses a <quote>raster driver</quote> that converts - the generic CUPS raster to a device-specific raster.</para></listitem> -</itemizedlist> - -<para> -Make sure your Ghostscript version has the <quote>cups</quote> device compiled in -(check with <command>gs -h | grep cups</command>). Otherwise you -may encounter the dreaded <computeroutput>Unable to convert file -0</computeroutput> in your CUPS error_log file. To have <quote>cups</quote> as a -device in your Ghostscript, you either need to patch GNU -Ghostscript and re-compile, or use <indexterm><primary>ESP</primary><secondary>Ghostscript</secondary></indexterm><ulink -url="http://www.cups.org/ghostscript.php">ESP Ghostscript</ulink>. The -superior alternative is ESP Ghostscript. It supports not just CUPS, -but 300 other devices too (while GNU Ghostscript supports only about -180). Because of this broad output device support, ESP Ghostscript is -the first choice for non-CUPS spoolers, too. It is now recommended by -Linuxprinting.org for all spoolers. -</para> - -<para> -<indexterm><primary>cupsomatic</primary></indexterm> -<indexterm><primary>foomatic</primary></indexterm> -CUPS printers may be setup to use external -rendering paths. One of the most common is provided by the -Foomatic/cupsomatic concept from <ulink -url="http://www.linuxprinting.org/">Linuxprinting.org.</ulink> This -uses the classical Ghostscript approach, doing everything in one -step. It does not use the <quote>cups</quote> device, but one of the many -others. However, even for Foomatic/cupsomatic usage, best results and -<indexterm><primary>ESP</primary><secondary>Ghostscript</secondary></indexterm> -broadest printer model support is provided by ESP Ghostscript (more -about cupsomatic/Foomatic, particularly the new version called now -<emphasis>foomatic-rip</emphasis>, follows below). -</para> - -<sect2> -<title>MIME Types and CUPS Filters</title> - - -<para> -<indexterm><primary>MIME</primary><secondary>filters</secondary></indexterm> - <indexterm><primary>MIME</primary></indexterm> -CUPS reads the file <filename>/etc/cups/mime.types</filename> -(and all other files carrying a <filename>*.types</filename> suffix -in the same directory) upon startup. These files contain the MIME -type recognition rules that are applied when CUPS runs its -auto-typing routines. The rule syntax is explained in the man page -for <filename>mime.types</filename> and in the comments section of the -<filename>mime.types</filename> file itself. A simple rule reads -like this: - -<indexterm><primary>application/pdf</primary></indexterm> -<filterline> - application/pdf pdf string(0,%PDF) -</filterline> - -This means if a filename has either a -<filename>.pdf</filename> suffix or if the magic -string <emphasis>%PDF</emphasis> is right at the -beginning of the file itself (offset 0 from the start), then it is -a PDF file (<parameter>application/pdf</parameter>). -Another rule is this: - -<filterline> - application/postscript ai eps ps string(0,%!) string(0,<04>%!) -</filterline> - -If the filename has one of the suffixes -<filename>.ai</filename>, <filename>.eps</filename>, -<filename>.ps</filename> or if the file itself starts with one of the -strings <emphasis>%!</emphasis> or <emphasis><![CDATA[<04>%!]]></emphasis>, it -is a generic PostScript file -(<parameter>application/postscript</parameter>). -</para> - -<warning><para> -Don't confuse the other mime.types files your system might be using -with the one in the <filename>/etc/cups/</filename> directory. -</para></warning> - -<note><para> -There is an important difference between two similar MIME types in -CUPS: one is <parameter>application/postscript</parameter>, the other is -<parameter>application/vnd.cups-postscript</parameter>. While -<parameter>application/postscript</parameter> is meant to be device -independent (job options for the file are still outside the PS file -content, embedded in command line or environment variables by CUPS), -<parameter>application/vnd.cups-postscript</parameter> may have the job -options inserted into the PostScript data itself (where -applicable). The transformation of the generic PostScript -(<parameter>application/postscript</parameter>) to the device-specific version -(<parameter>application/vnd.cups-postscript</parameter>) is the responsibility of the -CUPS <parameter>pstops</parameter> filter. pstops uses information -contained in the PPD to do the transformation. -</para></note> - -<para> -CUPS can handle ASCII text, HP-GL, PDF, PostScript, DVI, and -many image formats (GIF. PNG, TIFF, JPEG, Photo-CD, SUN-Raster, -PNM, PBM, SGI-RGB, and more) and their associated MIME types -with its filters. -</para> -</sect2> - -<sect2> -<title>MIME Type Conversion Rules</title> - - -<para> -<indexterm><primary>MIME</primary></indexterm> -<indexterm><primary>application/pdf</primary></indexterm> -CUPS reads the file <filename>/etc/cups/mime.convs</filename> -(and all other files named with a <filename>*.convs</filename> -suffix in the same directory) upon startup. These files contain -lines naming an input MIME type, an output MIME type, a format -conversion filter that can produce the output from the input type -and virtual costs associated with this conversion. One example line -reads like this: - -<filterline> - application/pdf application/postscript 33 pdftops -</filterline> - -This means that the <parameter>pdftops</parameter> filter will take -<parameter>application/pdf</parameter> as input and produce -<parameter>application/postscript</parameter> as output; the virtual -cost of this operation is 33 CUPS-$. The next filter is more -expensive, costing 66 CUPS-$: - -<indexterm><primary>pdf</primary></indexterm> - -<filterline> - application/vnd.hp-HPGL application/postscript 66 hpgltops -</filterline> - -This is the <parameter>hpgltops</parameter>, which processes HP-GL -plotter files to PostScript. - -<indexterm><primary>application/octet-stream</primary></indexterm> - -<filterline> - application/octet-stream -</filterline> - -Here are two more examples: - -<indexterm><primary>text/plain</primary></indexterm> - -<filterline> - application/x-shell application/postscript 33 texttops - text/plain application/postscript 33 texttops -</filterline> - -The last two examples name the <parameter>texttops</parameter> filter -to work on <parameter>text/plain</parameter> as well as on <parameter>application/x-shell</parameter>. (Hint: -This differentiation is needed for the syntax highlighting feature of -<parameter>texttops</parameter>). -</para> -</sect2> - -<sect2> -<title>Filtering Overview</title> - - -<para> -<indexterm><primary>MIME</primary></indexterm> -There are many more combinations named in <filename>mime.convs</filename>. However, you -are not limited to use the ones pre-defined there. You can plug in any -filter you like into the CUPS framework. It must meet, or must be made -to meet, some minimal requirements. If you find (or write) a cool -conversion filter of some kind, make sure it complies to what CUPS -needs and put in the right lines in <filename>mime.types</filename> -and <filename>mime.convs</filename>, then it will work seamlessly -inside CUPS. -</para> - -<sect3> -<title>Filter requirements</title> -<para> -The mentioned <quote>CUPS requirements</quote> for filters are simple. Take -filenames or <filename>stdin</filename> as input and write to -<filename>stdout</filename>. They should take these 5 or 6 arguments: -<emphasis>printer job user title copies options [filename]</emphasis> -</para> - -<variablelist> -<varlistentry><term>Printer </term> -<listitem><para>The name of the printer queue (normally this is the -name of the filter being run).</para></listitem> -</varlistentry> - -<varlistentry><term>job </term> -<listitem><para>The numeric job ID for the job being -printed.</para></listitem> -</varlistentry> - -<varlistentry><term>user </term> -<listitem><para>The string from the originating-user-name -attribute.</para></listitem> -</varlistentry> - -<varlistentry><term>title </term> -<listitem><para>The string from the job-name attribute.</para></listitem> -</varlistentry> - -<varlistentry><term>copies </term> -<listitem><para>The numeric value from the number-copies -attribute.</para></listitem> -</varlistentry> - -<varlistentry><term>options </term> -<listitem><para>The job options.</para></listitem> -</varlistentry> - -<varlistentry><term>filename </term> -<listitem><para>(Optionally) The print request file (if missing, -filters expected data fed through <filename>stdin</filename>). In most -cases, it is easy to write a simple wrapper script around existing -filters to make them work with CUPS.</para></listitem> -</varlistentry> -</variablelist> -</sect3> -</sect2> - -<sect2> -<title>Prefilters</title> - - -<para> -<indexterm><primary>PostScript</primary></indexterm> -As previously stated, PostScript is the central file format to any UNIX-based -printing system. From PostScript, CUPS generates raster data to feed -non-PostScript printers. -</para> - -<para> -But what happens if you send one of the supported non-PS formats -to print? Then CUPS runs <quote>pre-filters</quote> on these input formats to -generate PostScript first. There are pre-filters to create PS from -ASCII text, PDF, DVI, or HP-GL. The outcome of these filters is always -of MIME type <parameter>application/postscript</parameter> (meaning that -any device-specific print options are not yet embedded into the -PostScript by CUPS, and that the next filter to be called is -pstops). Another pre-filter is running on all supported image formats, -the <parameter>imagetops</parameter> filter. Its outcome is always of -MIME type <parameter>application/vnd.cups-postscript</parameter> -(not application/postscript), meaning it has the -print options already embedded into the file. -</para> - -<para> - <image scale="25"><imagedescription>Pre-filtering in CUPS to form PostScript.</imagedescription> - <imagefile>4small</imagefile> -</image> -</para> -</sect2> - -<sect2> -<title>pstops</title> - -<para> -<emphasis>pstops</emphasis> is the filter to convert -<parameter>application/postscript</parameter> to <?latex \linebreak ?> -<parameter>application/vnd.cups-postscript</parameter>. It was said -above that this filter inserts all device-specific print options -(commands to the printer to ask for the duplexing of output, or -stapling and punching it, and so on) into the PostScript file. -</para> - -<para> - <image scale="25"><imagedescription>Adding device-specific print options.</imagedescription> - <imagefile>5small</imagefile> - </image> -</para> - -<para> -This is not all. Other tasks performed by it are: -</para> - -<itemizedlist> -<listitem><para> -Selecting the range of pages to be printed (if you choose to -print only pages <quote>3, 6, 8-11, 16, 19-21</quote>, or only the odd numbered -ones). -</para></listitem> - -<listitem><para> -Putting 2 or more logical pages on one sheet of paper (the -so-called <quote>number-up</quote> function). -</para></listitem> - -<listitem><para>Counting the pages of the job to insert the accounting -information into the <filename>/var/log/cups/page_log</filename>. -</para></listitem> -</itemizedlist> -</sect2> - -<sect2> -<title>pstoraster</title> - -<para> -<parameter>pstoraster</parameter> is at the core of the CUPS filtering -system. It is responsible for the first stage of the rasterization -process. Its input is of MIME type application/vnd.cups-postscript; -its output is application/vnd.cups-raster. This output format is not -yet meant to be printable. Its aim is to serve as a general purpose -input format for more specialized <emphasis>raster drivers</emphasis> -that are able to generate device-specific printer data. -</para> - -<para> - <image scale="25"><imagedescription>PostScript to intermediate raster format.</imagedescription><imagefile>6small</imagefile></image> -</para> - -<para> -CUPS raster is a generic raster format with powerful features. It is -able to include per-page information, color profiles, and more, to be -used by the following downstream raster drivers. Its MIME type is -registered with IANA and its specification is, of course, completely -open. It is designed to make it quite easy and inexpensive for -manufacturers to develop Linux and UNIX raster drivers for their -printer models, should they choose to do so. CUPS always takes care -for the first stage of rasterization so these vendors do not need to care -about Ghostscript complications (in fact, there is currently more -than one vendor financing the development of CUPS raster drivers). -</para> - -<para> - <image><imagedescription>CUPS-raster production using Ghostscript.</imagedescription> - <imagefile>7small</imagefile> - </image> -</para> - -<para> -CUPS versions before version 1.1.15 were shipping a binary (or source -code) standalone filter, named <parameter>pstoraster</parameter>. <parameter>pstoraster</parameter> was derived -from GNU Ghostscript 5.50, and could be installed besides and in -addition to any GNU or AFPL Ghostscript package without conflicting. -</para> - -<para> ->From version 1.1.15, this has changed. The functions for this have been -integrated back into Ghostscript (now based on GNU Ghostscript version -7.05). The <parameter>pstoraster</parameter> filter is now a simple shell script calling -<command>gs</command> with the <command>-sDEVICE=cups</command> -parameter. If your Ghostscript does not show a success on asking for -<command>gs -h |grep cups</command>, you might not be able to -print. Update your Ghostscript. -</para> -</sect2> - -<sect2> -<title>imagetops and imagetoraster</title> - -<para> -In the section about pre-filters, we mentioned the pre-filter -that generates PostScript from image formats. The <parameter>imagetoraster</parameter> -filter is used to convert directly from image to raster, without the -intermediate PostScript stage. It is used more often than the above -mentioned pre-filters. A summarizing flowchart of image file -filtering is shown in <link linkend="small8"/>. -</para> - -<para> - <image id="small8"><imagedescription>Image format to CUPS-raster format conversion.</imagedescription> - <imagefile>8small</imagefile> - </image> -</para> - -</sect2> - -<sect2> -<title>rasterto [printers specific]</title> - -<para> -CUPS ships with quite different raster drivers processing CUPS -raster. On my system I find in /usr/lib/cups/filter/ these: -<parameter>rastertoalps</parameter>, <parameter>rastertobj</parameter>, <parameter>rastertoepson</parameter>, <parameter>rastertoescp</parameter>, -<parameter>rastertopcl</parameter>, <parameter>rastertoturboprint</parameter>, <parameter>rastertoapdk</parameter>, <parameter>rastertodymo</parameter>, -<parameter>rastertoescp</parameter>, <parameter>rastertohp</parameter>, and -<parameter>rastertoprinter</parameter>. Don't worry if you have less -than this; some of these are installed by commercial add-ons to CUPS -(like <parameter>rastertoturboprint</parameter>), others (like -<parameter>rastertoprinter</parameter>) by third-party driver -development projects (such as Gimp-Print) wanting to cooperate as -closely as possible with CUPS. -</para> - -<para> - <image id="small9"><imagedescription>Raster to printer-specific formats.</imagedescription> - <imagefile>9small</imagefile> - </image> -</para> -</sect2> - -<sect2> -<title>CUPS Backends</title> - -<para> -The last part of any CUPS filtering chain is a backend. Backends -are special programs that send the print-ready file to the final -device. There is a separate backend program for any transfer -protocol of sending printjobs over the network, or for every local -interface. Every CUPS print queue needs to have a CUPS <quote>device-URI</quote> -associated with it. The device URI is the way to encode the backend -used to send the job to its destination. Network device-URIs are using -two slashes in their syntax, local device URIs only one, as you can -see from the following list. Keep in mind that local interface names -may vary much from my examples, if your OS is not Linux: -</para> - -<variablelist> - <varlistentry><term>usb </term> - <listitem><para> - This backend sends printfiles to USB-connected printers. An - example for the CUPS device-URI to use is: - <filename>usb:/dev/usb/lp0</filename>. - </para></listitem></varlistentry> - - <varlistentry><term>serial </term> - <listitem><para> - This backend sends printfiles to serially connected printers. - An example for the CUPS device-URI to use is: - <filename>serial:/dev/ttyS0?baud=11500</filename>. - </para></listitem></varlistentry> - - <varlistentry><term>parallel </term> - <listitem><para> - This backend sends printfiles to printers connected to the - parallel port. An example for the CUPS device-URI to use is: - <filename>parallel:/dev/lp0</filename>. - </para></listitem></varlistentry> - - <varlistentry><term>scsi </term> - <listitem><para> - This backend sends printfiles to printers attached to the - SCSI interface. An example for the CUPS device-URI to use is: - <filename>scsi:/dev/sr1</filename>. - </para></listitem></varlistentry> - - <varlistentry><term>lpd </term> - <listitem><para> - This backend sends printfiles to LPR/LPD connected network - printers. An example for the CUPS device-URI to use is: - <filename>lpd://remote_host_name/remote_queue_name</filename>. - </para></listitem></varlistentry> - - <varlistentry><term>AppSocket/HP JetDirect </term> - <listitem><para> - This backend sends printfiles to AppSocket (a.k.a. "HP - JetDirect") connected network printers. An example for the CUPS - device-URI to use is: - <filename>socket://10.11.12.13:9100</filename>. - </para></listitem></varlistentry> - - <varlistentry><term>ipp </term> - <listitem><para> - This backend sends printfiles to IPP connected network - printers (or to other CUPS servers). Examples for CUPS device-URIs - to use are: - <filename>ipp:://192.193.194.195/ipp</filename> - (for many HP printers) or - <filename>ipp://remote_cups_server/printers/remote_printer_name</filename>. - </para></listitem></varlistentry> - - <varlistentry><term>http </term> - <listitem><para> - This backend sends printfiles to HTTP connected printers. - (The http:// CUPS backend is only a symlink to the ipp:// backend.) - Examples for the CUPS device-URIs to use are: - <filename>http:://192.193.194.195:631/ipp</filename> - (for many HP printers) or - <filename>http://remote_cups_server:631/printers/remote_printer_name</filename>. - </para></listitem></varlistentry> - - <varlistentry><term>smb </term> - <listitem><para> - This backend sends printfiles to printers shared by a Windows - host. An example for CUPS device-URIs that may be used includes: - </para> - - <para> - <simplelist> - <member><filename>smb://workgroup/server/printersharename</filename></member> - <member><filename>smb://server/printersharename</filename></member> - <member><filename>smb://username:password@workgroup/server/printersharename</filename></member> - <member><filename>smb://username:password@server/printersharename</filename></member> - </simplelist> - </para> - - <para> - The smb:// backend is a symlink to the Samba utility - <parameter>smbspool</parameter> (does not ship with CUPS). If the - symlink is not present in your CUPS backend directory, have your - root user create it: <command>ln -s `which smbspool' - /usr/lib/cups/backend/smb</command>. - </para></listitem></varlistentry> -</variablelist> - -<para> -It is easy to write your own backends as shell or Perl scripts, if you -need any modification or extension to the CUPS print system. One -reason could be that you want to create <quote>special</quote> printers that send -the printjobs as email (through a <quote>mailto:/</quote> backend), convert them to -PDF (through a <quote>pdfgen:/</quote> backend) or dump them to <quote>/dev/null</quote>. (In -fact I have the system-wide default printer set up to be connected to -a devnull:/ backend: there are just too many people sending jobs -without specifying a printer, or scripts and programs which do not name -a printer. The system-wide default deletes the job and sends a polite -email back to the $USER asking him to always specify the correct -printer name.) -</para> - -<para> -Not all of the mentioned backends may be present on your system or -usable (depending on your hardware configuration). One test for all -available CUPS backends is provided by the <emphasis>lpinfo</emphasis> -utility. Used with the <option>-v</option> parameter, it lists -all available backends: -</para> - -<para><screen> -&prompt;<userinput>lpinfo -v</userinput> -</screen></para> -</sect2> - -<sect2> -<title>The Role of <parameter>cupsomatic/foomatic</parameter></title> - -<para> -<indexterm><primary>cupsomatic</primary></indexterm> -<indexterm><primary>foomatic</primary></indexterm> -<parameter>cupsomatic</parameter> filters may be the most widely used on CUPS -installations. You must be clear about the fact that these were not -developed by the CUPS people. They are a third party add-on to -CUPS. They utilize the traditional Ghostscript devices to render jobs -for CUPS. When troubleshooting, you should know about the -difference. Here the whole rendering process is done in one stage, -inside Ghostscript, using an appropriate device for the target -printer. <parameter>cupsomatic</parameter> uses PPDs that are generated from the Foomatic -Printer & Driver Database at Linuxprinting.org. -</para> - -<para> -You can recognize these PPDs from the line calling the -<parameter>cupsomatic</parameter> filter: - -<filterline> - *cupsFilter: "application/vnd.cups-postscript 0 cupsomatic" -</filterline> - -You may find this line among the first 40 or so lines of the PPD -file. If you have such a PPD installed, the printer shows up in the -CUPS Web interface with a <parameter>foomatic</parameter> namepart for -the driver description. <parameter>cupsomatic</parameter> is a Perl script that runs -Ghostscript with all the complicated command line options -auto-constructed from the selected PPD and command line options give to -the printjob. -</para> - -<para> -<indexterm><primary>point 'n' print</primary></indexterm> - However, <parameter>cupsomatic</parameter> is now deprecated. Its PPDs (especially the first -generation of them, still in heavy use out there) are not meeting the -Adobe specifications. You might also suffer difficulties when you try -to download them with <quote>Point'n'Print</quote> to Windows clients. A better -and more powerful successor is now in a stable beta-version: it is called <parameter>foomatic-rip</parameter>. To use -<parameter>foomatic-rip</parameter> as a filter with CUPS, you need the new-type PPDs. These -have a similar but different line: - -<filterline> - *cupsFilter: "application/vnd.cups-postscript 0 foomatic-rip" -</filterline> - -The PPD generating engine at Linuxprinting.org has been revamped. -The new PPDs comply to the Adobe spec. On top, they also provide a -new way to specify different quality levels (hi-res photo, normal -color, grayscale, and draft) with a single click, whereas before you -could have required five or more different selections (media type, -resolution, inktype and dithering algorithm). There is support for -custom-size media built in. There is support to switch -print-options from page to page in the middle of a job. And the -best thing is the new foomatic-rip now works seamlessly with all -legacy spoolers too (like LPRng, BSD-LPD, PDQ, PPR and so on), providing -for them access to use PPDs for their printing. -</para> -</sect2> - -<sect2> -<title>The Complete Picture</title> - -<para> -If you want to see an overview of all the filters and how they -relate to each other, the complete picture of the puzzle is at the end -of this document. -</para> -</sect2> - -<sect2> -<title><filename>mime.convs</filename></title> - -<para> -CUPS auto-constructs all possible filtering chain paths for any given -MIME type, and every printer installed. But how does it decide in -favor or against a specific alternative? (There may often be cases -where there is a choice of two or more possible filtering chains for -the same target printer.) Simple. You may have noticed the figures in -the third column of the mime.convs file. They represent virtual costs -assigned to this filter. Every possible filtering chain will sum up to -a total <quote>filter cost.</quote> CUPS decides for the most <quote>inexpensive</quote> route. -</para> - -<tip><para> -The setting of <parameter>FilterLimit 1000</parameter> in -<filename>cupsd.conf</filename> will not allow more filters to -run concurrently than will consume a total of 1000 virtual filter -cost. This is an efficient way to limit the load of any CUPS -server by setting an appropriate <quote>FilterLimit</quote> value. A FilterLimit of -200 allows roughly one job at a time, while a FilterLimit of 1000 allows -approximately five jobs maximum at a time. -</para></tip> -</sect2> - -<sect2> - <title><quote>Raw</quote> Printing</title> - -<para> - You can tell CUPS to print (nearly) any file <quote>raw</quote>. <quote>Raw</quote> means it - will not be filtered. CUPS will send the file to the printer <quote>as is</quote> -without bothering if the printer is able to digest it. Users need to -take care themselves that they send sensible data formats only. Raw -printing can happen on any queue if the <quote><parameter>-o raw</parameter></quote> option is specified -on the command line. You can also set up raw-only queues by simply not -associating any PPD with it. This command: -</para> - -<para><screen> -&prompt;<userinput>lpadmin -P rawprinter -v socket://11.12.13.14:9100 -E</userinput> -</screen></para> - -<para> - sets up a queue named <quote>rawprinter</quote>, connected via the <quote>socket</quote> - protocol (a.k.a. <quote>HP JetDirect</quote>) to the device at IP address -11.12.1.3.14, using port 9100. (If you had added a PPD with -<command>-P /path/to/PPD</command> to this command line, you would -have installed a <quote>normal</quote> print queue. -</para> - -<para> -CUPS will automatically treat each job sent to a queue as a <quote>raw</quote> one, -if it can't find a PPD associated with the queue. However, CUPS will -only send known MIME types (as defined in its own mime.types file) and -refuse others. -</para> -</sect2> - -<sect2> -<title>application/octet-stream Printing</title> - -<para> -Any MIME type with no rule in the -<filename>/etc/cups/mime.types</filename> file is regarded as unknown -or <parameter>application/octet-stream</parameter> and will not be -sent. Because CUPS refuses to print unknown MIME types per default, -you will probably have experienced the fact that print jobs originating -from Windows clients were not printed. You may have found an error -message in your CUPS logs like: -</para> - -<para><computeroutput> - Unable to convert file 0 to printable format for job -</computeroutput></para> - -<para> -To enable the printing of <parameter>application/octet-stream</parameter> files, edit -these two files: -</para> - -<itemizedlist> -<listitem><para><filename>/etc/cups/mime.convs</filename></para></listitem> - -<listitem><para><filename>/etc/cups/mime.types</filename></para></listitem> -</itemizedlist> - -<para> -Both contain entries (at the end of the respective files) which must -be uncommented to allow RAW mode operation for -<parameter>application/octet-stream</parameter>. In <filename>/etc/cups/mime.types</filename> -make sure this line is present: - -<indexterm><primary>application/octet-stream</primary></indexterm> - -<filterline> -application/octet-stream -</filterline> - -This line (with no specific auto-typing rule set) makes all files -not otherwise auto-typed a member of <parameter>application/octet-stream</parameter>. In -<filename>/etc/cups/mime.convs</filename>, have this -line: - -<filterline> -application/octet-stream application/vnd.cups-raw 0 - -</filterline> - -<indexterm><primary>MIME</primary></indexterm> - -This line tells CUPS to use the <emphasis>Null Filter</emphasis> -(denoted as <quote>-</quote>, doing nothing at all) on -<parameter>application/octet-stream</parameter>, and tag the result as -<parameter>application/vnd.cups-raw</parameter>. This last one is -always a green light to the CUPS scheduler to now hand the file over -to the backend connecting to the printer and sending it over. -</para> - -<note><para>Editing the <filename>mime.convs</filename> and the -<filename>mime.types</filename> file does not -<emphasis>enforce</emphasis> <quote>raw</quote> printing, it only -<emphasis>allows</emphasis> it. -</para></note> - -<formalpara> -<title>Background</title> - -<para> -CUPS being a more security-aware printing system than traditional ones -does not by default allow one to send deliberate (possibly binary) -data to printing devices. (This could be easily abused to launch a -Denial of Service attack on your printer(s), causing at least the loss -of a lot of paper and ink...) <quote>Unknown</quote> data are regarded by CUPS -as <emphasis>MIME type</emphasis> -<emphasis>application/octet-stream</emphasis>. While you -<emphasis>can</emphasis> send data <quote>raw</quote>, the MIME type for these must -be one that is known to CUPS and an allowed one. The file -<filename>/etc/cups/mime.types</filename> defines the <quote>rules</quote> of how CUPS -recognizes MIME types. The file -<filename>/etc/cups/mime.convs</filename> decides which file -conversion filter(s) may be applied to which MIME types. -</para> -</formalpara> -</sect2> - -<sect2> -<title>PostScript Printer Descriptions (PPDs) for Non-PS Printers</title> - - -<para> -<indexterm><primary>PPD</primary></indexterm> -Originally PPDs were meant to be used for PostScript printers -only. Here, they help to send device-specific commands and settings -to the RIP which processes the jobfile. CUPS has extended this -scope for PPDs to cover non-PostScript printers too. This was not -difficult, because it is a standardized file format. In a way -it was logical too: CUPS handles PostScript and uses a PostScript -RIP (Ghostscript) to process the jobfiles. The only difference is: -a PostScript printer has the RIP built-in, for other types of -printers the Ghostscript RIP runs on the host computer. -</para> - -<para> -PPDs for a non-PS printer have a few lines that are unique to -CUPS. The most important one looks similar to this: - -<indexterm><primary>application/vnd.cups-raster</primary></indexterm> - -<filterline> - *cupsFilter: application/vnd.cups-raster 66 rastertoprinter -</filterline> - -It is the last piece in the CUPS filtering puzzle. This line tells the -CUPS daemon to use as a last filter <parameter>rastertoprinter</parameter>. This filter -should be served as input an <parameter>application/vnd.cups-raster</parameter> MIME type -file. Therefore, CUPS should auto-construct a filtering chain, which -delivers as its last output the specified MIME type. This is then -taken as input to the specified <parameter>rastertoprinter</parameter> filter. After this -the last filter has done its work (<parameter>rastertoprinter</parameter> is a Gimp-Print -filter), the file should go to the backend, which sends it to the -output device. -</para> - -<para> -CUPS by default ships only a few generic PPDs, but they are good for -several hundred printer models. You may not be able to control -different paper trays, or you may get larger margins than your -specific model supports. See <link linkend="cups-ppds"/> for summary information. -</para> - -<table frame="all" id="cups-ppds"> - <title>PPDs shipped with CUPS</title> - <tgroup cols="2" align="left"> - <colspec align="left"/> - <colspec align="justify" width="1*"/> - <thead><row><entry>PPD file</entry><entry>Printer type</entry></row></thead> - <tbody> - <row><entry>deskjet.ppd</entry><entry>older HP inkjet printers and compatible</entry></row> - - <row><entry>deskjet2.ppd</entry> <entry>newer HP inkjet printers and compatible </entry> </row> - - <row><entry>dymo.ppd</entry> <entry>label printers </entry> </row> - - <row><entry>epson9.ppd</entry> <entry>Epson 24pin impact printers and compatible </entry> </row> - - <row><entry>epson24.ppd</entry> <entry>Epson 24pin impact printers and compatible </entry> </row> - - <row><entry>okidata9.ppd</entry> <entry>Okidata 9pin impact printers and compatible </entry> </row> - - <row><entry>okidat24.ppd</entry> <entry>Okidata 24pin impact printers and compatible </entry> </row> - - <row><entry>stcolor.ppd</entry> <entry>older Epson Stylus Color printers </entry> </row> - - <row><entry>stcolor2.ppd</entry> <entry>newer Epson Stylus Color printers </entry> </row> - - <row><entry>stphoto.ppd</entry> <entry>older Epson Stylus Photo printers </entry> </row> - - <row><entry>stphoto2.ppd</entry> <entry>newer Epson Stylus Photo printers </entry> </row> - - <row><entry>laserjet.ppd</entry> <entry>all PCL printers. Further below is a discussion - of several other driver/PPD-packages suitable for use with CUPS. </entry> </row> - - </tbody> - </tgroup> -</table> - -</sect2> - -<sect2> -<title><emphasis>cupsomatic/foomatic-rip</emphasis> Versus <emphasis>native CUPS</emphasis> Printing</title> - - -<para> -<indexterm><primary>cupsomatic</primary></indexterm> -<indexterm><primary>foomatic-rip</primary></indexterm> -Native CUPS rasterization works in two steps: -</para> - -<itemizedlist> -<listitem><para> -First is the <parameter>pstoraster</parameter> step. It uses the special CUPS -<indexterm><primary>ESP</primary><secondary>Ghostscript</secondary></indexterm> -device from ESP Ghostscript 7.05.x as its tool. -</para></listitem> - -<listitem><para> -Second comes the <parameter>rasterdriver</parameter> step. It uses various -device-specific filters; there are several vendors who provide good -quality filters for this step. Some are free software, some are -shareware/non-free and some are proprietary.</para></listitem> -</itemizedlist> - -<para> -Often this produces better quality (and has several more -advantages) than other methods. -</para> - -<para> - <image id="cupsomatic-dia"><imagedescription>cupsomatic/foomatic Processing versus Native CUPS.</imagedescription> - <imagefile>10small</imagefile> - </image> -</para> - -<para> -One other method is the <parameter>cupsomatic/foomatic-rip</parameter> -way. Note that <parameter>cupsomatic</parameter> is <emphasis>not</emphasis> made by the CUPS -developers. It is an independent contribution to printing development, -made by people from Linuxprinting.org <footnote>see also <ulink - noescape="1" url="http://www.cups.org/cups-help.html">http://www.cups.org/cups-help.html</ulink></footnote>. -<parameter>cupsomatic</parameter> is no longer developed and maintained and is no longer -supported. It has now been replaced by -<parameter>foomatic-rip</parameter>. <parameter>foomatic-rip</parameter> is a complete re-write -of the old <parameter>cupsomatic</parameter> idea, but very much improved and generalized to -other (non-CUPS) spoolers. An upgrade to foomatic-rip is strongly -advised, especially if you are upgrading to a recent version of CUPS, -too. -</para> - -<para> - <indexterm><primary>cupsomatic</primary></indexterm> - <indexterm><primary>foomatic</primary></indexterm> -Both the <parameter>cupsomatic</parameter> (old) and the <parameter>foomatic-rip</parameter> (new) methods from -Linuxprinting.org use the traditional Ghostscript print file -processing, doing everything in a single step. It therefore relies on -all the other devices built into Ghostscript. The quality is as -good (or bad) as Ghostscript rendering is in other spoolers. The -advantage is that this method supports many printer models not -supported (yet) by the more modern CUPS method. -</para> - -<para> -Of course, you can use both methods side by side on one system (and -even for one printer, if you set up different queues) and find out -which works best for you. -</para> - -<para> -<parameter>cupsomatic</parameter> kidnaps the printfile after the -<parameter>application/vnd.cups-postscript</parameter> stage and -deviates it through the CUPS-external, system-wide Ghostscript -installation. Therefore the printfile bypasses the <parameter>pstoraster</parameter> filter -(and also bypasses the CUPS-raster-drivers -<parameter>rastertosomething</parameter>). After Ghostscript finished its rasterization, -<parameter>cupsomatic</parameter> hands the rendered file directly to the CUPS backend. The -flowchart in <link linkend="cupsomatic-dia"/> illustrates the difference between native CUPS -rendering and the <parameter>Foomatic/cupsomatic</parameter> method. -</para> -</sect2> - -<sect2> -<title>Examples for Filtering Chains</title> - -<para> -Here are a few examples of commonly occurring filtering chains to -illustrate the workings of CUPS. -</para> - -<para> -Assume you want to print a PDF file to an HP JetDirect-connected -PostScript printer, but you want to print the pages 3-5, 7, 11-13 -only, and you want to print them <quote>two-up</quote> and <quote>duplex</quote>: -</para> - -<itemizedlist> -<listitem><para>Your print options (page selection as required, two-up, -duplex) are passed to CUPS on the command line.</para></listitem> - -<listitem><para>The (complete) PDF file is sent to CUPS and autotyped as -<parameter>application/pdf</parameter>.</para></listitem> - -<listitem><para>The file therefore must first pass the -<parameter>pdftops</parameter> pre-filter, which produces PostScript -MIME type <parameter>application/postscript</parameter> (a preview here -would still show all pages of the original PDF).</para></listitem> - -<listitem><para>The file then passes the <parameter>pstops</parameter> -filter that applies the command line options: it selects the pages -2-5, 7 and 11-13, creates an imposed layout <quote>2 pages on 1 sheet</quote> and -inserts the correct <quote>duplex</quote> command (as defined in the printer's -PPD) into the new PostScript file; the file is now of PostScript MIME -type -<parameter>application/vnd.cups-postscript</parameter>.</para></listitem> - -<listitem><para>The file goes to the <parameter>socket</parameter> -backend, which transfers the job to the printers.</para></listitem> -</itemizedlist> - -<para> - The resulting filter chain, therefore, is as drawn in <link linkend="pdftosocket"/>. -</para> - -<image id="pdftosocket"><imagefile>pdftosocket</imagefile><imagedescription>PDF to socket chain.</imagedescription></image> - -<para> -Assume your want to print the same filter to an USB-connected -Epson Stylus Photo printer installed with the CUPS -<filename>stphoto2.ppd</filename>. The first few filtering stages -are nearly the same: -</para> - -<itemizedlist> -<listitem><para>Your print options (page selection as required, two-up, -duplex) are passed to CUPS on the commandline.</para></listitem> - -<listitem><para>The (complete) PDF file is sent to CUPS and autotyped as -<parameter>application/pdf</parameter>.</para></listitem> - -<listitem><para>The file must first pass the -<parameter>pdftops</parameter> pre-filter, which produces PostScript -MIME type <parameter>application/postscript</parameter> (a preview here -would still show all pages of the original PDF).</para></listitem> - -<listitem><para>The file then passes the <quote>pstops</quote> filter that applies -the commandline options: it selects the pages 2-5, 7 and 11-13, -creates an imposed layout <quote>two pages on one sheet</quote> and inserts the -correct <quote>duplex</quote> command... (Oops &smbmdash; this printer and PPD -do not support duplex printing at all &smbmdash; so this option will -be ignored) into the new PostScript file; the file is now of PostScript -MIME type -<parameter>application/vnd.cups-postscript</parameter>.</para></listitem> - -<listitem><para>The file then passes the - <!--FIXME--> -<parameter>pstoraster</parameter> stage and becomes MIME type -<parameter>application/ -cups-raster</parameter>.</para></listitem> - -<listitem><para>Finally, the <parameter>rastertoepson</parameter> filter -does its work (as indicated in the printer's PPD), creating the -rinter-specific raster data and embedding any user-selected -print-options into the print data stream.</para></listitem> - -<listitem><para>The file goes to the <parameter>usb</parameter> backend, -which transfers the job to the printers.</para></listitem> -</itemizedlist> - -<para> -The resulting filter chain therefore is as drawn in <link linkend="pdftoepsonusb"/>. -</para> - -<image id="pdftoepsonusb"><imagefile>pdftoepsonusb</imagefile><imagedescription>PDF to USB chain.</imagedescription></image> -</sect2> - -<sect2> -<title>Sources of CUPS Drivers/PPDs</title> - -<para> -On the Internet you can now find many thousands of CUPS-PPD files -(with their companion filters), in many national languages -supporting more than thousand non-PostScript models. -</para> - -<itemizedlist> -<indexterm><primary>ESP</primary><secondary>Print Pro</secondary></indexterm> -<indexterm><primary>PrintPro</primary><see>ESP Print Pro</see></indexterm> -<listitem><para><ulink url="http://wwwl.easysw.com/printpro/">ESP -PrintPro</ulink> (commercial, -non-free) is packaged with more than three thousand PPDs, ready for -successful use <quote>out of the box</quote> on Linux, Mac OS X, IBM-AIX, -HP-UX, Sun-Solaris, SGI-IRIX, Compaq Tru64, Digital UNIX, and some -more commercial Unices (it is written by the CUPS developers -themselves and its sales help finance the further development of -CUPS, as they feed their creators).</para></listitem> - -<listitem><para>The <ulink -url="http://gimp-print.sourceforge.net/">Gimp-Print-Project -</ulink> (GPL, free software) -provides around 140 PPDs (supporting nearly 400 printers, many driven -to photo quality output), to be used alongside the Gimp-Print CUPS -filters.</para></listitem> - -<listitem><para><ulink url="http://www.turboprint.com/">TurboPrint -</ulink> (shareware, non-free) supports -roughly the same amount of printers in excellent -quality.</para></listitem> - -<listitem><para><ulink -url="http://www-124.ibm.com/developerworks/oss/linux/projects/omni/">OMNI -</ulink> -(LPGL, free) is a package made by IBM, now containing support for more -than 400 printers, stemming from the inheritance of IBM OS/2 Know-How -ported over to Linux (CUPS support is in a beta-stage at -present).</para></listitem> - -<listitem><para><ulink url="http://hpinkjet.sourceforge.net/">HPIJS -</ulink> (BSD-style licenses, free) -supports around 150 of HP's own printers and is also providing -excellent print quality now (currently available only via the Foomatic -path).</para></listitem> - -<listitem><para><ulink -url="http://www.linuxprinting.org/">Foomatic/cupsomatic -</ulink> (LPGL, free) from -Linuxprinting.org are providing PPDs for practically every Ghostscript -filter known to the world (including Omni, Gimp-Print and -HPIJS).</para></listitem> -</itemizedlist> - -</sect2> - -<sect2> -<title>Printing with Interface Scripts</title> - -<para> -CUPS also supports the usage of <quote>interface scripts</quote> as known from -System V AT&T printing systems. These are often used for PCL -printers, from applications that generate PCL print jobs. Interface -scripts are specific to printer models. They have a similar role as -PPDs for PostScript printers. Interface scripts may inject the Escape -sequences as required into the print data stream, if the user has -chosen to select a certain paper tray, or print landscape, or use A3 -paper, etc. Interfaces scripts are practically unknown in the Linux -realm. On HP-UX platforms they are more often used. You can use any -working interface script on CUPS too. Just install the printer with -the <command>-i</command> option: -</para> - -<para><screen> -&rootprompt;<userinput>lpadmin -p pclprinter -v socket://11.12.13.14:9100 \ - -i /path/to/interface-script</userinput> -</screen></para> - -<para> -Interface scripts might be the <quote>unknown animal</quote> to many. However, -with CUPS they provide the easiest way to plug in your own -custom-written filtering script or program into one specific print -queue (some information about the traditional usage of interface scripts is -to be found at <ulink - noescape="1" url="http://playground.sun.com/printing/documentation/interface.html">http://playground.sun.com/printing/documentation/interface.html</ulink>). -</para> -</sect2> -</sect1> - -<sect1> - <title>Network Printing (Purely Windows)</title> - -<para> -Network printing covers a lot of ground. To understand what exactly -goes on with Samba when it is printing on behalf of its Windows -clients, let's first look at a <quote>purely Windows</quote> setup: Windows clients -with a Windows NT print server. -</para> - -<sect2> -<title>From Windows Clients to an NT Print Server</title> - -<para> -Windows clients printing to an NT-based print server have two -options. They may: -<indexterm><primary>GDI</primary></indexterm> -<indexterm><primary>EMF</primary></indexterm> -</para> - - -<itemizedlist> - <listitem><para>Execute the driver locally and render the GDI output - (EMF) into the printer-specific format on their own. - </para></listitem> - - <listitem><para>Send the GDI output (EMF) to the server, where the -driver is executed to render the printer specific -output.</para></listitem> -</itemizedlist> - -<para> -Both print paths are shown in the flowcharts in <link linkend="small11"/> and <link linkend="small12"/>. -</para> -</sect2> - -<sect2> -<title>Driver Execution on the Client</title> - -<para> -In the first case the print server must spool the file as raw, -meaning it shouldn't touch the jobfile and try to convert it in any -way. This is what a traditional UNIX-based print server can do too, and -at a better performance and more reliably than an NT print server. This -is what most Samba administrators probably are familiar with. One -advantage of this setup is that this <quote>spooling-only</quote> print server may -be used even if no driver(s) for UNIX are available it is sufficient -to have the Windows client drivers available; and installed on the -clients. -</para> - -<para> - <image id="small11"><imagedescription>Print driver execution on the client.</imagedescription> - <imagefile>11small</imagefile> - </image> -</para> -</sect2> - -<sect2> -<title>Driver Execution on the Server</title> - - -<para> -<indexterm><primary>PostScript</primary></indexterm> -<indexterm><primary>PCL</primary></indexterm> -<indexterm><primary>ESC/P</primary></indexterm> -<indexterm><primary>EMF</primary></indexterm> -<indexterm><primary>GDI</primary></indexterm> -The other path executes the printer driver on the server. The client -transfers print files in EMF format to the server. The server uses the -PostScript, PCL, ESC/P or other driver to convert the EMF file into -the printer-specific language. It is not possible for UNIX to do the -same. Currently, there is no program or method to convert a Windows -client's GDI output on a UNIX server into something a printer could -understand. -</para> - -<para> - <image id="small12"><imagedescription>Print driver execution on the server.</imagedescription> - <imagefile>12small</imagefile> - </image> -</para> - -<para> -However, there is something similar possible with CUPS. Read on. -</para> -</sect2> -</sect1> - -<sect1> -<title>Network Printing (Windows Clients &smbmdash; UNIX/Samba Print -Servers)</title> - -<para> -Since UNIX print servers <emphasis>cannot</emphasis> execute the Win32 -program code on their platform, the picture is somewhat -different. However, this does not limit your options all that -much. On the contrary, you may have a way here to implement printing -features that are not possible otherwise. -</para> - -<sect2> -<title>From Windows Clients to a CUPS/Samba Print Server</title> - -<para> -Here is a simple recipe showing how you can take advantage of CUPS' -powerful features for the benefit of your Windows network printing -clients: -</para> - -<itemizedlist> - -<listitem><para>Let the Windows clients send PostScript to the CUPS -server.</para></listitem> - -<listitem><para>Let the CUPS server render the PostScript into device-specific raster format.</para></listitem> -</itemizedlist> - -<para> -This requires the clients to use a PostScript driver (even if the -printer is a non-PostScript model. It also requires that you have a -driver on the CUPS server. -</para> - -<para> -First, to enable CUPS-based rinting through Samba the -following options should be set in your &smb.conf; file [global] -section: -</para> - -<smbconfblock> -<smbconfoption><name>printing</name><value>cups</value></smbconfoption> -<smbconfoption><name>printcap</name><value>cups</value></smbconfoption> -</smbconfblock> - -<para> -When these parameters are specified, all manually set print directives -(like <smbconfoption><name>print command</name></smbconfoption>, or <smbconfoption><name>lppause command</name></smbconfoption>) in &smb.conf; (as well as -in Samba itself) will be ignored. Instead, Samba will directly -interface with CUPS through its application program interface (API), -as long as Samba has been compiled with CUPS library (libcups) -support. If Samba has not been compiled with CUPS support, and if no -other print commands are set up, then printing will use the -<emphasis>System V</emphasis> AT&T command set, with the -oraw -option automatically passing through (if you want your own defined -print commands to work with a Samba that has CUPS support compiled in, -simply use <smbconfoption><name>printing</name><value>sysv</value></smbconfoption>). -</para> - -<para> -<image><imagedescription>Printing via CUPS/Samba server.</imagedescription> - <imagefile>13small</imagefile> -</image> -</para> -</sect2> - -<sect2> -<title>Samba Receiving Jobfiles and Passing Them to CUPS</title> - -<para> -Samba <emphasis>must</emphasis> use its own spool directory (it is set -by a line similar to <smbconfoption><name>path</name><value>/var/spool/samba</value></smbconfoption>, -in the <smbconfsection>[printers]</smbconfsection> or -<smbconfsection>[printername]</smbconfsection> section of -&smb.conf;). Samba receives the job in its own -spool space and passes it into the spool directory of CUPS (the CUPS -spooling directory is set by the <parameter>RequestRoot</parameter> -directive, in a line that defaults to <parameter>RequestRoot -/var/spool/cups</parameter>). CUPS checks the access rights of its -spool dir and resets it to healthy values with every restart. We have -seen quite a few people who had used a common spooling space for Samba -and CUPS, and were struggling for weeks with this <quote>problem.</quote> -</para> - -<para> -A Windows user authenticates only to Samba (by whatever means is -configured). If Samba runs on the same host as CUPS, you only need to -allow <quote>localhost</quote> to print. If they run on different machines, you -need to make sure the Samba host gets access to printing on CUPS. -</para> -</sect2> -</sect1> - -<sect1> -<title>Network PostScript RIP</title> - -<para> -This section discusses the use of CUPS filters on the server &smbmdash; configuration where -clients make use of a PostScript driver with CUPS-PPDs. -</para> - - -<para> -<indexterm><primary>PostScript</primary></indexterm> -<indexterm><primary>PCL</primary></indexterm> -<indexterm><primary>PJL</primary></indexterm> -PPDs can control all print device options. They are usually provided -by the manufacturer, if you own a PostScript printer, that is. PPD -files (PostScript Printer Descriptions) are always a component of -PostScript printer drivers on MS Windows or Apple Mac OS systems. They -are ASCII files containing user-selectable print options, mapped to -appropriate PostScript, PCL or PJL commands for the target -printer. Printer driver GUI dialogs translate these options -<quote>on-the-fly</quote> into buttons and drop-down lists for the user to select. -</para> - -<para> -CUPS can load, without any conversions, the PPD file from any Windows -(NT is recommended) PostScript driver and handle the options. There is -a Web browser interface to the print options (select <ulink -noescape="1" url="http://localhost:631/printers/">http://localhost:631/printers/</ulink> -and click on one <guibutton>Configure Printer</guibutton> button to see -it), or a command line interface (see <command>man lpoptions</command> -or see if you have <command>lphelp</command> on your system). There are also some -different GUI frontends on Linux/UNIX, which can present PPD options -to users. PPD options are normally meant to be evaluated by the -PostScript RIP on the real PostScript printer. -</para> - -<sect2> -<title>PPDs for Non-PS Printers on UNIX</title> - - -<para> -<indexterm><primary>PPD</primary></indexterm> -CUPS does not limit itself to <quote>real</quote> PostScript printers in its usage -of PPDs. The CUPS developers have extended the scope of the PPD -concept to also describe available device and driver options for -non-PostScript printers through CUPS-PPDs. -</para> - -<para> -This is logical, as CUPS includes a fully featured PostScript -interpreter (RIP). This RIP is based on Ghostscript. It can process -all received PostScript (and additionally many other file formats) -from clients. All CUPS-PPDs geared to non-PostScript printers contain -an additional line, starting with the keyword -<parameter>*cupsFilter</parameter>. This line tells the CUPS print -system which printer-specific filter to use for the interpretation of -the supplied PostScript. Thus CUPS lets all its printers appear as -PostScript devices to its clients, because it can act as a PostScript -RIP for those printers, processing the received PostScript code into a -proper raster print format. -</para> -</sect2> - -<sect2> -<title>PPDs for Non-PS Printers on Windows</title> - -<para> -<indexterm><primary>PPD</primary></indexterm> -CUPS-PPDs can also be used on Windows-Clients, on top of a -<quote>core</quote> PostScript driver (now recommended is the "CUPS PostScript -Driver for WindowsNT/200x/XP"; you can also use the Adobe one, with -limitations). This feature enables CUPS to do a few tricks no other -spooler can do: -</para> - -<itemizedlist> - -<listitem><para>Act as a networked PostScript RIP (Raster Image -Processor), handling printfiles from all client platforms in a uniform -way.</para></listitem> - -<listitem><para>Act as a central accounting and billing server, since -all files are passed through the pstops filter and are, therefore, -logged in the CUPS <filename>page_log</filename> file. -<emphasis>Note:</emphasis> this cannot happen with <quote>raw</quote> print jobs, -which always remain unfiltered per definition.</para></listitem> - -<listitem><para>Enable clients to consolidate on a single PostScript -driver, even for many different target printers.</para></listitem> -</itemizedlist> - -<para> -Using CUPS PPDs on Windows clients enables these to control -all print job settings just as a UNIX client can do. -</para> -</sect2> -</sect1> - -<sect1> -<title>Windows Terminal Servers (WTS) as CUPS Clients</title> - -<para> -This setup may be of special interest to people experiencing major -problems in WTS environments. WTS often need a multitude of -non-PostScript drivers installed to run their clients' variety of -different printer models. This often imposes the price of much -increased instability. -</para> - -<sect2> -<title>Printer Drivers Running in <quote>Kernel Mode</quote> Cause Many -Problems</title> - -<para> - In Windows NT printer drivers which run in <quote>Kernel -Mode</quote>, introduces a high risk for the stability of the system -if the driver is not really stable and well-tested. And there are a -lot of bad drivers out there! Especially notorious is the example -of the PCL printer driver that had an additional sound module -running, to notify users via soundcard of their finished jobs. Do I -need to say that this one was also reliably causing <quote>blue screens -of death</quote> on a regular basis? -</para> - -<para> -PostScript drivers are generally well tested. They are not known -to cause any problems, even though they also run in kernel mode. This -might be because there have been so far only two different PostScript -drivers: the ones from Adobe and the one from Microsoft. Both are -well tested and are as stable as you can imagine on -Windows. The CUPS driver is derived from the Microsoft one. -</para> -</sect2> - -<sect2> -<title>Workarounds Impose Heavy Limitations</title> - -<para> -In many cases, in an attempt to work around this problem, site -administrators have resorted to restricting the allowed drivers installed -on their WTS to one generic PCL and one PostScript driver. This, -however, restricts the clients in the number of printer options -available for them. Often they can't get out more than simplex -prints from one standard paper tray, while their devices could do much -better, if driven by a different driver! -</para> -</sect2> - -<sect2> -<title>CUPS: A <quote>Magical Stone</quote>?</title> - - -<para> -<indexterm><primary>PPD</primary></indexterm> -<indexterm><primary>PostScript</primary></indexterm> -Using a PostScript driver, enabled with a CUPS-PPD, seems to be a very -elegant way to overcome all these shortcomings. There are, depending -on the version of Windows OS you use, up to three different PostScript -drivers available: Adobe, Microsoft and CUPS PostScript drivers. None -of them is known to cause major stability problems on WTS (even if -used with many different PPDs). The clients will be able to (again) -chose paper trays, duplex printing and other settings. However, there -is a certain price for this too: a CUPS server acting as a PostScript -RIP for its clients requires more CPU and RAM than when just acting as -a <quote>raw spooling</quote> device. Plus, this setup is not yet widely tested, -although the first feedbacks look very promising. -</para> -</sect2> - -<sect2> -<title>PostScript Drivers with No Major Problems &smbmdash; Even in Kernel -Mode</title> - -<para> -<indexterm><primary>DDK</primary></indexterm> -More recent printer drivers on W200x and XP no longer run in kernel mode -(unlike Windows NT). However, both operating systems can still -use the NT drivers, running in kernel mode (you can roughly tell which -is which as the drivers in subdirectory <quote>2</quote> of <quote>W32X86</quote> are <quote>old</quote> -ones). As was said before, the Adobe as well as the Microsoft -PostScript drivers are not known to cause any stability problems. The -CUPS driver is derived from the Microsoft one. There is a simple -reason for this: The MS DDK (Device Development Kit) for Windows NT (which -used to be available at no cost to licensees of Visual Studio) -includes the source code of the Microsoft driver, and licensees of -Visual Studio are allowed to use and modify it for their own driver -development efforts. This is what the CUPS people have done. The -license does not allow them to publish the whole of the source code. -However, they have released the <quote>diff</quote> under the GPL, and if you are -the owner of an <quote>MS DDK for Windows NT,</quote> you can check the driver yourself. -</para> -</sect2> -</sect1> - -<sect1> -<title>Configuring CUPS for Driver Download</title> - -<para> -As we have said before, all previously known methods to prepare client -printer drivers on the Samba server for download and Point'n'Print -convenience of Windows workstations are working with CUPS, too. These -methods were described in the previous chapter. In reality, this is a -pure Samba business and only relates to the Samba/Windows client -relationship. -</para> - -<sect2> -<title><emphasis>cupsaddsmb</emphasis>: The Unknown Utility</title> - - -<para> -<indexterm><primary>cupsaddsmb</primary></indexterm> -The <command>cupsaddsmb</command> utility (shipped with all current CUPS versions) is an -alternate method to transfer printer drivers into the Samba -<smbconfsection>[print$]</smbconfsection> share. Remember, this share is where -clients expect drivers deposited and setup for download and -installation. It makes the sharing of any (or all) installed CUPS -printers quite easy. <command>cupsaddsmb</command> can use the Adobe PostScript driver as -well as the newly developed CUPS PostScript Driver for -Windows NT/200x/XP. <parameter>cupsaddsmb</parameter> does -<emphasis>not</emphasis> work with arbitrary vendor printer drivers, -but only with the <emphasis>exact</emphasis> driver files that are -named in its man page. -</para> - -<para> -The CUPS printer driver is available from the CUPS download site. Its -package name is <filename>cups-samba-[version].tar.gz</filename> . It -is preferred over the Adobe drivers since it has a number of -advantages: -</para> - -<itemizedlist> -<listitem><para>It supports a much more accurate page -accounting.</para></listitem> - -<listitem><para>It supports banner pages, and page labels on all -printers.</para></listitem> - -<listitem><para>It supports the setting of a number of job IPP -attributes (such as job-priority, page-label and -job-billing).</para></listitem> -</itemizedlist> - -<para> -However, currently only Windows NT, 2000 and XP are supported by the -CUPS drivers. You will also need to get the respective part of Adobe driver -if you need to support Windows 95, 98 and ME clients. -</para> -</sect2> - -<sect2> - <title>Prepare Your &smb.conf; for <command>cupsaddsmb</command></title> - -<para> -Prior to running <command>cupsaddsmb</command>, you need the settings in -&smb.conf; as shown in <link linkend="cupsadd-ex"/>: -</para> - -<para><smbconfexample id="cupsadd-ex"> -<title>smb.conf for cupsaddsmb usage</title> -<smbconfsection>[global]</smbconfsection> -<smbconfoption><name>load printers</name><value>yes</value></smbconfoption> -<smbconfoption><name>printing</name><value>cups</value></smbconfoption> -<smbconfoption><name>printcap name</name><value>cups</value></smbconfoption> - -<smbconfsection>[printers]</smbconfsection> -<smbconfoption><name>comment</name><value>All Printers</value></smbconfoption> -<smbconfoption><name>path</name><value>/var/spool/samba</value></smbconfoption> -<smbconfoption><name>browseable</name><value>no</value></smbconfoption> -<smbconfoption><name>public</name><value>yes</value></smbconfoption> -<smbconfcomment>setting depends on your requirements</smbconfcomment> -<smbconfoption><name>guest ok</name><value>yes</value></smbconfoption> -<smbconfoption><name>writable</name><value>no</value></smbconfoption> -<smbconfoption><name>printable</name><value>yes</value></smbconfoption> -<smbconfoption><name>printer admin</name><value>root</value></smbconfoption> - <smbconfsection>[print$]</smbconfsection> -<smbconfoption><name>comment</name><value>Printer Drivers</value></smbconfoption> -<smbconfoption><name>path</name><value>/etc/samba/drivers</value></smbconfoption> -<smbconfoption><name>browseable</name><value>yes</value></smbconfoption> -<smbconfoption><name>guest ok</name><value>no</value></smbconfoption> -<smbconfoption><name>read only</name><value>yes</value></smbconfoption> -<smbconfoption><name>write list</name><value>root</value></smbconfoption> -</smbconfexample></para> -</sect2> - -<sect2> -<title>CUPS <quote>PostScript Driver for Windows NT/200x/XP</quote></title> - -<para> -<indexterm><primary>PostScript</primary></indexterm> -CUPS users may get the exact same packages from <ulink -noescape="1" url="http://www.cups.org/software.html">http://www.cups.org/software.html</ulink>. -It is a separate package from the CUPS base software files, tagged as -CUPS 1.1.x Windows NT/200x/XP Printer Driver for Samba -(tar.gz, 192k). The filename to download is -<filename>cups-samba-1.1.x.tar.gz</filename>. Upon untar and unzipping, -it will reveal these files: -</para> - -<para><screen> -&rootprompt;<userinput>tar xvzf cups-samba-1.1.19.tar.gz</userinput> -cups-samba.install -cups-samba.license -cups-samba.readme -cups-samba.remove -cups-samba.ss -</screen></para> - -<para> -<indexterm><primary>ESP</primary><secondary>meta packager</secondary></indexterm> -<indexterm><primary>EPM</primary><see>ESP meta packager</see></indexterm> -These have been packaged with the ESP meta packager software -EPM. The <filename>*.install</filename> and -<filename>*.remove</filename> files are simple shell scripts, which -untars the <filename>*.ss</filename> (the <filename>*.ss</filename> is -nothing else but a tar-archive, which can be untarred by <quote>tar</quote> -too). Then it puts the content into -<filename>/usr/share/cups/drivers/</filename>. This content includes three -files: -</para> - -<para><screen> -&rootprompt;<userinput>tar tv cups-samba.ss</userinput> -cupsdrvr.dll -cupsui.dll -cups.hlp -</screen></para> - -<para> -The <parameter>cups-samba.install</parameter> shell scripts are easy to -handle: -</para> - -<para><screen> -&rootprompt;<userinput>./cups-samba.install</userinput> -[....] -Installing software... -Updating file permissions... -Running post-install commands... -Installation is complete. -</screen></para> - -<para> -The script should automatically put the driver files into the -<filename>/usr/share/cups/drivers/</filename> directory. -</para> - -<warning><para> -Due to a bug, one recent CUPS release puts the -<filename>cups.hlp</filename> driver file -into<filename>/usr/share/drivers/</filename> instead of -<filename>/usr/share/cups/drivers/</filename>. To work around this, -copy/move the file (after running the -<command>./cups-samba.install</command> script) manually to the -correct place. -</para></warning> - -<para><screen> -&rootprompt;<userinput>cp /usr/share/drivers/cups.hlp /usr/share/cups/drivers/</userinput> -</screen></para> - - -<para> -<indexterm><primary>DDK</primary></indexterm> -This new CUPS PostScript driver is currently binary-only, but free of -charge. No complete source code is provided (yet). The reason is that -it has been developed with the help of the Microsoft Driver -Developer Kit (DDK) and compiled with Microsoft Visual -Studio 6. Driver developers are not allowed to distribute the whole of -the source code as free software. However, CUPS developers released -the <quote>diff</quote> in source code under the GPL, so anybody with a license of -Visual Studio and a DDK will be able to compile for him/herself. -</para> -</sect2> - -<sect2> -<title>Recognizing Different Driver Files</title> - -<para> -The CUPS drivers do not support the older Windows 95/98/Me, but only -the Windows NT/2000/XP client. -</para> - -<para>Windows NT, 2000 and XP are supported by:</para> - -<para> - <itemizedlist> - <listitem>cups.hlp</listitem> - <listitem>cupsdrvr.dll</listitem> - <listitem>cupsui.dll</listitem> - </itemizedlist> -</para> - -<para> -Adobe drivers are available for the older Windows 95/98/Me as well as -the Windows NT/2000/XP clients. The set of files is different from the -different platforms. -</para> - -<para>Windows 95, 98 and ME are supported by:</para> - -<para> - <itemizedlist> - <listitem>ADFONTS.MFM</listitem> - <listitem>ADOBEPS4.DRV</listitem> - <listitem>ADOBEPS4.HLP</listitem> - <listitem>DEFPRTR2.PPD</listitem> - <listitem>ICONLIB.DLL</listitem> - <listitem>PSMON.DLL</listitem> -</itemizedlist> -</para> - -<para>Windows NT, 2000 and XP are supported by:</para> - -<para> -<itemizedlist> - <listitem>ADOBEPS5.DLL</listitem> - <listitem>ADOBEPSU.DLL</listitem> - <listitem>ADOBEPSU.HLP</listitem> -</itemizedlist> - -</para> - -<note><para> -If both the Adobe driver files and the CUPS driver files for the -support of Windows NT/200x/XP are present in FIXME, the Adobe ones will be ignored -and the CUPS ones will be used. If you prefer &smbmdash; for whatever reason -&smbmdash; to use Adobe-only drivers, move away the three CUPS driver files. The -Windows 9x/Me clients use the Adobe drivers in any case. -</para></note> -</sect2> - -<sect2> -<title>Acquiring the Adobe Driver Files</title> - -<para> -Acquiring the Adobe driver files seems to be unexpectedly difficult -for many users. They are not available on the Adobe Web site as single -files and the self-extracting and/or self-installing Windows-.exe is -not easy to locate either. Probably you need to use the included -native installer and run the installation process on one client -once. This will install the drivers (and one Generic PostScript -printer) locally on the client. When they are installed, share the -Generic PostScript printer. After this, the client's -<smbconfsection>[print$]</smbconfsection> share holds the Adobe files, from -where you can get them with smbclient from the CUPS host. -</para> -</sect2> - -<sect2> -<title>ESP Print Pro PostScript Driver for Windows NT/200x/XP</title> - - - -<para> -<indexterm><primary>ESP</primary><secondary>Print Pro</secondary></indexterm> -Users of the ESP Print Pro software are able to install their Samba -drivers package for this purpose with no problem. Retrieve the driver -files from the normal download area of the ESP Print Pro software -at <ulink - noescape="1" url="http://www.easysw.com/software.html">http://www.easysw.com/software.html</ulink>. -You need to locate the link labelled <quote>SAMBA</quote> among the -<guilabel>Download Printer Drivers for ESP Print Pro 4.x</guilabel> -area and download the package. Once installed, you can prepare any -driver by simply highlighting the printer in the Printer Manager GUI -and select <guilabel>Export Driver...</guilabel> from the menu. Of -course you need to have prepared Samba beforehand to handle the -driver files; i.e., setup the <smbconfsection>[print$]</smbconfsection> -share, and so on. The ESP Print Pro package includes the CUPS driver files -as well as a (licensed) set of Adobe drivers for the Windows 95/98/Me -client family. -</para> -</sect2> - -<sect2> -<title>Caveats to be Considered</title> - - -<para> -<indexterm><primary>cupsaddsmb</primary></indexterm> -Once you have run the install script (and possibly manually -moved the <filename>cups.hlp</filename> file to -<filename>/usr/share/cups/drivers/</filename>), the driver is -ready to be put into Samba's <smbconfsection>[print$]</smbconfsection> share (which often maps to -<filename>/etc/samba/drivers/</filename> and contains a subdirectory -tree with <emphasis>WIN40</emphasis> and -<emphasis>W32X86</emphasis> branches). You do this by running -<command>cupsaddsmb</command> (see also <command>man cupsaddsmb</command> for -CUPS since release 1.1.16). -</para> - -<tip><para> -<indexterm><primary>Single Sign On</primary></indexterm> -You may need to put root into the smbpasswd file by running -<command>smbpasswd</command>; this is especially important if you -should run this whole procedure for the first time, and are not -working in an environment where everything is configured for -<emphasis>single sign on</emphasis> to a Windows Domain Controller. -</para></tip> - -<para> -Once the driver files are in the <smbconfsection>[print$]</smbconfsection> share -and are initialized, they are ready to be downloaded and installed by -the Windows NT/200x/XP clients. -</para> - -<note><para> -Win 9x/Me clients will not work with the CUPS PostScript driver. For -these you still need to use the <filename>ADOBE*.*</filename> -drivers as previously stated. -</para></note> - -<note> -<para> -It is not harmful if you still have the -<filename>ADOBE*.*</filename> driver files from previous -installations in the <filename>/usr/share/cups/drivers/</filename> -directory. The new <command>cupsaddsmb</command> (from 1.1.16) will -automatically prefer its own drivers if it finds both. -</para></note> - -<note><para> -<indexterm><primary>"Printers" folder</primary></indexterm> -Should your Windows clients have had the old <filename>ADOBE*.*</filename> -files for the Adobe PostScript driver installed, the download and -installation of the new CUPS PostScript driver for Windows NT/200x/XP -will fail at first. You need to wipe the old driver from the clients -first. It is not enough to <quote>delete</quote> the printer, as the driver files -will still be kept by the clients and re-used if you try to re-install -the printer. To really get rid of the Adobe driver files on the -clients, open the <guilabel>Printers</guilabel> folder (possibly via <guilabel>Start > Settings > Control Panel > Printers</guilabel>), -right-click on the folder background and select <guimenuitem>Server -Properties</guimenuitem>. When the new dialog opens, select the -<guilabel>Drivers</guilabel> tab. On the list select the driver you -want to delete and click the <guilabel>Delete</guilabel> -button. This will only work if there is not one single printer left -that uses that particular driver. You need to <quote>delete</quote> all printers -using this driver in the <guilabel>Printers</guilabel> folder first. You will need -Administrator privileges to do this. -</para></note> - -<note><para> -<indexterm><primary>rpcclient</primary><secondary>setdriver</secondary></indexterm> -Once you have successfully downloaded the CUPS PostScript driver to a -client, you can easily switch all printers to this one by proceeding -as described in <link linkend="printing"/>. Either change -a driver for an existing printer by running the <guilabel>Printer Properties</guilabel> -dialog, or use <command>rpcclient</command> with the -<command>setdriver</command> subcommand. -</para></note> -</sect2> - -<sect2> -<title>Windows CUPS PostScript Driver Versus Adobe Driver</title> - -<para> -Are you interested in a comparison between the CUPS and the Adobe -PostScript drivers? For our purposes these are the most important -items that weigh in favor of the CUPS ones: -</para> - -<itemizedlist> -<listitem><para>No hassle with the Adobe EULA.</para></listitem> - -<listitem><para>No hassle with the question <quote>Where do I -get the ADOBE*.* driver files from?</quote></para></listitem> - -<listitem><para> -<indexterm><primary>PJL</primary></indexterm> -The Adobe drivers (on request of the printer PPD -associated with them) often put a PJL header in front of the main -PostScript part of the print file. Thus, the printfile starts with -<parameter><1B >%-12345X</parameter> or -<parameter><escape>%-12345X</parameter> instead -of <parameter>%!PS</parameter>). This leads to the -CUPS daemon auto-typing the incoming file as a print-ready file, -not initiating a pass through the <parameter>pstops</parameter> filter (to speak more -technically, it is not regarded as the generic MIME-type -<indexterm><primary>application/postscript</primary></indexterm> -<parameter>application/postscript</parameter>, but as -the more special MIME type -<indexterm><primary>application/cups.vnd-postscript</primary></indexterm> -<parameter>application/cups.vnd-postscript</parameter>), -which therefore also leads to the page accounting in -<parameter>/var/log/cups/page_log</parameter> not -receiving the exact number of pages; instead the dummy page number -of <quote>1</quote> is logged in a standard setup).</para></listitem> - -<listitem><para>The Adobe driver has more options to misconfigure the -PostScript generated by it (like setting it inadvertently to -<guilabel>Optimize for Speed</guilabel>, instead of -<guilabel>Optimize for Portability</guilabel>, which -could lead to CUPS being unable to process it).</para></listitem> - -<listitem><para>The CUPS PostScript driver output sent by Windows -clients to the CUPS server is guaranteed to auto-type -as the generic MIME type <parameter>application/postscript</parameter>, -thus passing through the CUPS <parameter>pstops</parameter> filter and logging the -correct number of pages in the <filename>page_log</filename> for -accounting and quota purposes.</para></listitem> - -<listitem><para>The CUPS PostScript driver supports the sending of -additional standard (IPP) print options by Windows NT/200x/XP clients. Such -additional print options are: naming the CUPS standard -<emphasis>banner pages</emphasis> (or the custom ones, should they be -installed at the time of driver download), using the CUPS -page-label option, setting a -job-priority, and setting the scheduled -time of printing (with the option to support additional -useful IPP job attributes in the future).</para></listitem> - -<listitem><para>The CUPS PostScript driver supports the inclusion of -the new <parameter>*cupsJobTicket</parameter> comments at the -beginning of the PostScript file (which could be used in the future -for all sort of beneficial extensions on the CUPS side, but which will -not disturb any other applications as they will regard it as a comment -and simply ignore it).</para></listitem> - -<listitem><para>The CUPS PostScript driver will be the heart of the -fully fledged CUPS IPP client for Windows NT/200x/XP to be released soon -(probably alongside the first beta release for CUPS -1.2).</para></listitem> -</itemizedlist> - -</sect2> - -<sect2> -<title>Run cupsaddsmb (Quiet Mode)</title> - - -<para> -<indexterm><primary>cupsaddsmb</primary></indexterm> -<indexterm><primary>point 'n' print</primary></indexterm> -The <command>cupsaddsmb</command> command copies the needed files into your -<smbconfsection>[print$]</smbconfsection> share. Additionally, the PPD -associated with this printer is copied from -<filename>/etc/cups/ppd/</filename> to -<smbconfsection>[print$]</smbconfsection>. There the files wait for convenient -Windows client installations via Point'n'Print. Before we can run the -command successfully, we need to be sure that we can authenticate -toward Samba. If you have a small network, you are probably using user-level -security (<smbconfoption><name>security</name><value>user</value></smbconfoption>). -</para> - -<para> -Here is an example of a successfully run <command>cupsaddsmb</command> command: -</para> - -<para><screen> -&rootprompt;<userinput>cupsaddsmb -U root infotec_IS2027</userinput> -Password for root required to access localhost via Samba: <userinput>['secret']</userinput> -</screen></para> - -<para> -To share <emphasis>all</emphasis> printers and drivers, use the -<option>-a</option> parameter instead of a printer name. Since -<command>cupsaddsmb</command> <quote>exports</quote> the printer drivers to Samba, it should be -obvious that it only works for queues with a CUPS driver associated. -</para> -</sect2> - -<sect2> -<title>Run cupsaddsmb with Verbose Output</title> - - -<para> -<indexterm><primary>cupsaddsmb</primary></indexterm> -Probably you want to see what's going on. Use the -<option>-v</option> parameter to get a more verbose output. The -output below was edited for better readability: all <quote>\</quote> at the end of -a line indicate that I inserted an artificial line break plus some -indentation here: -</para> - -<warning><para> -You will see the root password for the Samba account printed on -screen. -</para></warning> - -<para> - -<indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm> -<indexterm><primary>rpcclient</primary><secondary>setdriver</secondary></indexterm> - <screen> -&rootprompt;<userinput>cupsaddsmb -U root -v infotec_2105</userinput> -Password for root required to access localhost via &example.server.samba;: -Running command: smbclient //localhost/print\$ -N -U'root%secret' \ - -c 'mkdir W32X86; \ - put /var/spool/cups/tmp/3e98bf2d333b5 W32X86/infotec_2105.ppd; \ - put /usr/share/cups/drivers/cupsdrvr.dll W32X86/cupsdrvr.dll; \ - put /usr/share/cups/drivers/cupsui.dll W32X86/cupsui.dll; \ - put /usr/share/cups/drivers/cups.hlp W32X86/cups.hlp' -added interface ip=10.160.51.60 bcast=10.160.51.255 nmask=255.255.252.0 -Domain=[CUPS-PRINT] OS=[UNIX] Server=[Samba 2.2.7a] -NT_STATUS_OBJECT_NAME_COLLISION making remote directory \W32X86 -putting file /var/spool/cups/tmp/3e98bf2d333b5 as \W32X86/infotec_2105.ppd -putting file /usr/share/cups/drivers/cupsdrvr.dll as \W32X86/cupsdrvr.dll -putting file /usr/share/cups/drivers/cupsui.dll as \W32X86/cupsui.dll -putting file /usr/share/cups/drivers/cups.hlp as \W32X86/cups.hlp - -Running command: rpcclient localhost -N -U'root%secret' - -c 'adddriver "Windows NT x86" \ - "infotec_2105:cupsdrvr.dll:infotec_2105.ppd:cupsui.dll:cups.hlp:NULL: \ - RAW:NULL"' -cmd = adddriver "Windows NT x86" \ - "infotec_2105:cupsdrvr.dll:infotec_2105.ppd:cupsui.dll:cups.hlp:NULL: \ - RAW:NULL" -Printer Driver infotec_2105 successfully installed. - -Running command: smbclient //localhost/print\$ -N -U'root%secret' \ --c 'mkdir WIN40; \ - put /var/spool/cups/tmp/3e98bf2d333b5 WIN40/infotec_2105.PPD; \ - put /usr/share/cups/drivers/ADFONTS.MFM WIN40/ADFONTS.MFM; \ - put /usr/share/cups/drivers/ADOBEPS4.DRV WIN40/ADOBEPS4.DRV; \ - put /usr/share/cups/drivers/ADOBEPS4.HLP WIN40/ADOBEPS4.HLP; \ - put /usr/share/cups/drivers/DEFPRTR2.PPD WIN40/DEFPRTR2.PPD; \ - put /usr/share/cups/drivers/ICONLIB.DLL WIN40/ICONLIB.DLL; \ - put /usr/share/cups/drivers/PSMON.DLL WIN40/PSMON.DLL;' - added interface ip=10.160.51.60 bcast=10.160.51.255 nmask=255.255.252.0 - Domain=[CUPS-PRINT] OS=[UNIX] Server=[Samba 2.2.7a] - NT_STATUS_OBJECT_NAME_COLLISION making remote directory \WIN40 - putting file /var/spool/cups/tmp/3e98bf2d333b5 as \WIN40/infotec_2105.PPD - putting file /usr/share/cups/drivers/ADFONTS.MFM as \WIN40/ADFONTS.MFM - putting file /usr/share/cups/drivers/ADOBEPS4.DRV as \WIN40/ADOBEPS4.DRV - putting file /usr/share/cups/drivers/ADOBEPS4.HLP as \WIN40/ADOBEPS4.HLP - putting file /usr/share/cups/drivers/DEFPRTR2.PPD as \WIN40/DEFPRTR2.PPD - putting file /usr/share/cups/drivers/ICONLIB.DLL as \WIN40/ICONLIB.DLL - putting file /usr/share/cups/drivers/PSMON.DLL as \WIN40/PSMON.DLL - - Running command: rpcclient localhost -N -U'root%secret' \ - -c 'adddriver "Windows 4.0" \ - "infotec_2105:ADOBEPS4.DRV:infotec_2105.PPD:NULL:ADOBEPS4.HLP: \ - PSMON.DLL:RAW:ADOBEPS4.DRV,infotec_2105.PPD,ADOBEPS4.HLP,PSMON.DLL, \ - ADFONTS.MFM,DEFPRTR2.PPD,ICONLIB.DLL"' - cmd = adddriver "Windows 4.0" "infotec_2105:ADOBEPS4.DRV:\ - infotec_2105.PPD:NULL:ADOBEPS4.HLP:PSMON.DLL:RAW:ADOBEPS4.DRV,\ - infotec_2105.PPD,ADOBEPS4.HLP,PSMON.DLL,ADFONTS.MFM,DEFPRTR2.PPD,\ - ICONLIB.DLL" - Printer Driver infotec_2105 successfully installed. - - Running command: rpcclient localhost -N -U'root%secret' \ - -c 'setdriver infotec_2105 infotec_2105' - cmd = setdriver infotec_2105 infotec_2105 - Successfully set infotec_2105 to driver infotec_2105. - -</screen></para> - -<para> -If you look closely, you'll discover your root password was transferred -unencrypted over the wire, so beware! Also, if you look further, -you'll discover error messages like <?latex \linebreak ?>NT_STATUS_OBJECT_NAME_COLLISION in between. They occur, because the directories WIN40 and W32X86 already existed in the <smbconfsection>[print$]</smbconfsection> driver download share (from a previous driver installation). They are harmless here. -</para> -</sect2> - -<sect2> -<title>Understanding cupsaddsmb</title> - - -<para> -<indexterm><primary>cupsaddsmb</primary></indexterm> -What has happened? What did <command>cupsaddsmb</command> do? There are five stages of -the procedure: -</para> - -<orderedlist> - <listitem><para> - <indexterm><primary>IPP</primary></indexterm> - Call the CUPS server via IPP and request the -driver files and the PPD file for the named printer.</para></listitem> - -<listitem><para>Store the files temporarily in the local -TEMPDIR (as defined in -<filename>cupsd.conf</filename>).</para></listitem> - -<listitem><para>Connect via smbclient to the Samba server's - <smbconfsection>[print$]</smbconfsection> share and put the files into the - share's WIN40 (for Windows 9x/Me) and W32X86/ (for Windows NT/200x/XP) subdirectories.</para></listitem> - -<listitem><para> -<indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm> - Connect via rpcclient to the Samba server and -execute the <command>adddriver</command> command with the correct -parameters.</para></listitem> - -<listitem><para> -<indexterm><primary>rpcclient</primary><secondary>setdriver</secondary></indexterm> - Connect via rpcclient to the Samba server a second -time and execute the <command>setdriver</command> command.</para></listitem> -</orderedlist> - -<note> -<para> -You can run the <command>cupsaddsmb</command> utility with parameters to -specify one remote host as Samba host and a second remote host as CUPS -host. Especially if you want to get a deeper understanding, it is a -good idea to try it and see more clearly what is going on (though in real -life most people will have their CUPS and Samba servers run on the -same host): -</para> - -<para><screen> -&rootprompt;<userinput>cupsaddsmb -H sambaserver -h cupsserver -v printer</userinput> -</screen></para> -</note> -</sect2> - -<sect2> -<title>How to Recognize If cupsaddsmb Completed Successfully</title> - -<para> -You <emphasis>must</emphasis> always check if the utility completed -successfully in all fields. You need as a minimum these three messages -among the output: -</para> - -<orderedlist> - -<listitem><para><emphasis>Printer Driver infotec_2105 successfully -installed.</emphasis> # (for the W32X86 == Windows NT/200x/XP -architecture).</para></listitem> - -<listitem><para><emphasis>Printer Driver infotec_2105 successfully -installed.</emphasis> # (for the WIN40 == Windows 9x/Me -architecture).</para></listitem> - -<listitem><para><emphasis>Successfully set [printerXPZ] to driver -[printerXYZ].</emphasis></para></listitem> -</orderedlist> - -<para> -These messages are probably not easily recognized in the general -output. If you run <command>cupsaddsmb</command> with the <option>-a</option> -parameter (which tries to prepare <emphasis>all</emphasis> active CUPS -printer drivers for download), you might miss if individual printers -drivers had problems installing properly. Here a redirection of the -output will help you analyze the results in retrospective. -</para> - -<note><para> -It is impossible to see any diagnostic output if you do not run -<command>cupsaddsmb</command> in verbose mode. Therefore, we strongly recommend to not -use the default quiet mode. It will hide any problems from you that -might occur. -</para></note> -</sect2> - -<sect2> -<title>cupsaddsmb with a Samba PDC</title> - - -<para> -<indexterm><primary>cupsaddsmb</primary></indexterm> -Can't get the standard <command>cupsaddsmb</command> command to run on a Samba PDC? -Are you asked for the password credential all over again and again and -the command just will not take off at all? Try one of these -variations: -</para> - -<para><screen> -&rootprompt;<userinput>cupsaddsmb -U &example.workgroup;\\root -v printername</userinput> -&rootprompt;<userinput>cupsaddsmb -H &example.pdc.samba; -U &example.workgroup;\\root -v printername</userinput> -&rootprompt;<userinput>cupsaddsmb -H &example.pdc.samba; -U &example.workgroup;\\root -h cups-server -v printername</userinput> -</screen></para> - -<para> -(Note the two backslashes: the first one is required to -<quote>escape</quote> the second one). -</para> -</sect2> - -<sect2> -<title>cupsaddsmb Flowchart</title> - -<para> -<indexterm><primary>cupsaddsmb</primary></indexterm> -<link linkend="small14"/> shows a chart about the procedures, commandflows and -dataflows of the <command>cupaddsmb</command> command. Note again: cupsaddsmb is -not intended to, and does not work with, raw queues! -</para> - -<para> - <image id="small14"><imagedescription>cupsaddsmb flowchart.</imagedescription> - <imagefile>14small</imagefile></image> -</para> -</sect2> - -<sect2> -<title>Installing the PostScript Driver on a Client</title> - -<para> -<indexterm><primary>point 'n' print</primary></indexterm> -After <command>cupsaddsmb</command> is completed, your driver is prepared for the clients to -use. Here are the steps you must perform to download and install it -via Point'n'Print. From a Windows client, browse to the CUPS/Samba -server: -</para> - -<itemizedlist> - - -<listitem><para> -<indexterm><primary>"Printers" folder</primary></indexterm> -Open the <guilabel>Printers</guilabel> -share of Samba in Network Neighborhood.</para></listitem> - -<listitem><para>Right-click on the printer in -question.</para></listitem> - -<listitem><para>From the opening context-menu select -<guimenuitem>Install...</guimenuitem> or -<guimenuitem>Connect...</guimenuitem> (depending on the Windows version you -use).</para></listitem> -</itemizedlist> - -<para> -After a few seconds, there should be a new printer in your -client's <emphasis>local</emphasis> <guilabel>Printers</guilabel> folder. On Windows -XP it will follow a naming convention of <emphasis>PrinterName on -SambaServer</emphasis>. (In my current case it is "infotec_2105 on -kde-bitshop"). If you want to test it and send your first job from -an application like Winword, the new printer appears in a -<filename>\\SambaServer\PrinterName</filename> entry in the -drop-down list of available printers. -</para> - -<para> -<indexterm><primary>PPD</primary></indexterm> -<command>cupsaddsmb</command> will only reliably work with CUPS version 1.1.15 or higher -and Samba from 2.2.4. If it does not work, or if the automatic printer -driver download to the clients does not succeed, you can still manually -install the CUPS printer PPD on top of the Adobe PostScript driver on -clients. Then point the client's printer queue to the Samba printer -share for a UNC type of connection: -</para> - -<para><screen> -&dosprompt;<userinput>net use lpt1: \\sambaserver\printershare /user:ntadmin</userinput> -</screen></para> - -<para> -should you desire to use the CUPS networked PostScript RIP -functions. (Note that user <quote>ntadmin</quote> needs to be a valid Samba user -with the required privileges to access the printershare.) This -sets up the printer connection in the traditional -<emphasis>LanMan</emphasis> way (not using MS-RPC). -</para> -</sect2> - -<sect2> -<title>Avoiding Critical PostScript Driver Settings on the Client</title> - -<para> -Printing works, but there are still problems. Most jobs print -well, some do not print at all. Some jobs have problems with fonts, -which do not look very good. Some jobs print fast and some are -dead-slow. Many of these problems can be greatly reduced or even -completely eliminated if you follow a few guidelines. Remember, if -your print device is not PostScript-enabled, you are treating your -Ghostscript installation on your CUPS host with the output your client -driver settings produce. Treat it well: -</para> - -<itemizedlist> -<listitem><para>Avoid the PostScript Output Option: Optimize -for Speed setting. Use the Optimize for -Portability instead (Adobe PostScript -driver).</para></listitem> - -<listitem><para>Don't use the Page Independence: -NO setting. Instead, use Page Independence -YES (CUPS PostScript Driver).</para></listitem> - -<listitem><para>Recommended is the True Type Font -Downloading Option: Native True Type over -Automatic and Outline; you -should by all means avoid Bitmap (Adobe -PostScript Driver).</para></listitem> - -<listitem><para>Choose True Type Font: Download as Softfont -into Printer over the default Replace by Device -Font (for exotic fonts, you may need to change it back to -get a printout at all) (Adobe).</para></listitem> - -<listitem><para>Sometimes you can choose PostScript Language -Level: In case of problems try 2 -instead of 3 (the latest ESP Ghostscript package -handles Level 3 PostScript very well) (Adobe).</para></listitem> - -<listitem><para>Say Yes to PostScript -Error Handler (Adobe).</para></listitem> -</itemizedlist> -</sect2> -</sect1> - -<sect1> -<title>Installing PostScript Driver Files Manually Using rpcclient</title> - -<para> -Of course, you can run all the commands that are embedded into the -cupsaddsmb convenience utility yourself, one by one, and hereby upload -and prepare the driver files for future client downloads. -</para> - -<orderedlist> -<listitem><para>Prepare Samba (A CUPS print queue with the name of the -printer should be there. We are providing the driver -now).</para></listitem> - -<listitem><para>Copy all files to - <smbconfsection>[print$]</smbconfsection>.</para></listitem> - -<listitem><para> -<indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm> -Run <command>rpcclient adddriver</command> -(for each client architecture you want to support).</para></listitem> - -<listitem><para> -<indexterm><primary>rpcclient</primary><secondary>setdriver</secondary></indexterm> -Run <command>rpcclient -setdriver.</command></para></listitem> -</orderedlist> - -<para> -<indexterm><primary>rpcclient</primary><secondary>enumports</secondary></indexterm> -<indexterm><primary>rpcclient</primary><secondary>enumprinters</secondary></indexterm> -<indexterm><primary>rpcclient</primary><secondary>enumdrivers</secondary></indexterm> -<indexterm><primary>rpcclient</primary><secondary>setdriver</secondary></indexterm> -<indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm> -We are going to do this now. First, read the man page on <parameter>rpcclient</parameter> -to get a first idea. Look at all the printing related -subcommands. <command>enumprinters</command>, -<command>enumdrivers</command>, <command>enumports</command>, -<command>adddriver</command>, <command>setdriver</command> are among -the most interesting ones. <parameter>rpcclient</parameter> implements an important part of -the MS-RPC protocol. You can use it to query (and command) a Windows NT -(or 200x/XP) PC, too. MS-RPC is used by Windows clients, among other -things, to benefit from the Point'n'Print features. Samba can now -mimic this as well. -</para> - -<sect2> -<title>A Check of the rpcclient man Page</title> - -<para> - First let's check the <parameter>rpcclient</parameter> man page. Here are -two relevant passages: -</para> - -<para> -<command>adddriver <arch> <config></command> Execute an -<command>AddPrinterDriver()</command> RPC to install the printer driver information on -the server. The driver files should already exist in the -directory returned by <command>getdriverdir</command>. Possible -values for <parameter>arch</parameter> are the same as those for the -<command>getdriverdir</command> command. The -<parameter>config</parameter> parameter is defined as follows: -</para> - -<para><screen> -Long Printer Name:\ -Driver File Name:\ -Data File Name:\ -Config File Name:\ -Help File Name:\ -Language Monitor Name:\ -Default Data Type:\ -Comma Separated list of Files -</screen></para> - -<para>Any empty fields should be enter as the string <quote>NULL</quote>. </para> - -<para>Samba does not need to support the concept of Print Monitors -since these only apply to local printers whose driver can make use of -a bi-directional link for communication. This field should be <quote>NULL</quote>. -On a remote NT print server, the Print Monitor for a driver must -already be installed prior to adding the driver or else the RPC will -fail. -</para> - -<para> -<command>setdriver <printername> <drivername></command> -Execute a <command>SetPrinter()</command> command to update the -printer driver associated with an installed printer. The printer -driver must already be correctly installed on the print server. -</para> - -<para>See also the <command>enumprinters</command> and <command>enumdrivers</command> commands for -obtaining a list of installed printers and drivers. -</para> - -</sect2> - -<sect2> -<title>Understanding the rpcclient man Page</title> - -<para> -The <emphasis>exact</emphasis> format isn't made too clear by the man -page, since you have to deal with some parameters containing -spaces. Here is a better description for it. We have line-broken the -command and indicated the breaks with <quote>\</quote>. Usually you would type the -command in one line without the linebreaks: -<indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm> -</para> - -<para><screen> - adddriver "Architecture" \ - "LongPrinterName:DriverFile:DataFile:ConfigFile:HelpFile:\ - LanguageMonitorFile:DataType:ListOfFiles,Comma-separated" -</screen></para> - -<para> -What the man pages denote as a simple <parameter><config></parameter> -keyword, in reality consists of eight colon-separated fields. The -last field may take multiple (in some very insane cases, even -20 different additional) files. This might sound confusing at first. -What the man pages names the <quote>LongPrinterName</quote> in -reality should be called the <quote>Driver Name</quote>. You can name it -anything you want, as long as you use this name later in the -<command>rpcclient ... setdriver</command> command. For -practical reasons, many name the driver the same as the -printer. -</para> - -<para> -It isn't simple at all. I hear you asking: -<quote>How do I know which files are "Driver -File</quote>, <quote>Data File</quote>, <quote>Config File</quote>, <quote>Help File</quote> and <quote>Language -Monitor File" in each case?</quote> &smbmdash; For an answer, you may -want to have a look at how a Windows NT box with a shared printer -presents the files to us. Remember, that this whole procedure has -to be developed by the Samba team by overhearing the traffic caused -by Windows computers on the wire. We may as well turn to a Windows -box now and access it from a UNIX workstation. We will query it -with <command>rpcclient</command> to see what it tells us and -try to understand the man page more clearly that we've read just -now. -</para> -</sect2> - -<sect2> -<title>Producing an Example by Querying a Windows Box</title> - -<para> - <indexterm><primary>rpcclient</primary><secondary>getdriver</secondary></indexterm> - <indexterm><primary>rpcclient</primary><secondary>getprinter</secondary></indexterm> -We could run <command>rpcclient</command> with a -<command>getdriver</command> or a <command>getprinter</command> -subcommand (in level 3 verbosity) against it. Just sit down at a UNIX or -Linux workstation with the Samba utilities installed, then type the -following command: -</para> - -<para><screen> -&rootprompt;<userinput>rpcclient -U'user%secret' NT-SERVER -c 'getdriver printername 3'</userinput> -</screen></para> - -<para> -From the result it should become clear which is which. Here is an example from my installation: -</para> - -<para> -<indexterm><primary>rpcclient</primary><secondary>getdriver</secondary></indexterm> - <screen> -&rootprompt;<userinput>rpcclient -U'Danka%xxxx' W200xSERVER \ - -c'getdriver "DANKA InfoStream Virtual Printer" 3'</userinput> - cmd = getdriver "DANKA InfoStream Virtual Printer" 3 - - [Windows NT x86] - Printer Driver Info 3: - Version: [2] - Driver Name: [DANKA InfoStream] - Architecture: [Windows NT x86] - Driver Path: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\PSCRIPT.DLL] - Datafile: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\INFOSTRM.PPD] - Configfile: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\PSCRPTUI.DLL] - Helpfile: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\PSCRIPT.HLP] - - Dependentfiles: [] - Dependentfiles: [] - Dependentfiles: [] - Dependentfiles: [] - Dependentfiles: [] - Dependentfiles: [] - Dependentfiles: [] - - Monitorname: [] - Defaultdatatype: [] - -</screen></para> - -<para> -Some printer drivers list additional files under the label -<parameter>Dependentfiles</parameter> and these would go into the last field -<parameter>ListOfFiles,Comma-separated</parameter>. For the CUPS -PostScript drivers, we do not need any (nor would we for the Adobe -PostScript driver), therefore, the field will get a <quote>NULL</quote> entry. -</para> -</sect2> - -<sect2> -<title>Requirements for adddriver and setdriver to Succeed</title> - -<para> ->From the man page (and from the quoted output -of <command>cupsaddsmb</command> above) it becomes clear that you -need to have certain conditions in order to make the manual uploading -and initializing of the driver files succeed. The two <command>rpcclient</command> -<indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm> -subcommands (<command>adddriver</command> and -<command>setdriver</command>) need to encounter the following -preconditions to complete successfully: -</para> -<itemizedlist> - -<listitem><para>You are connected as <smbconfoption><name>printer admin</name></smbconfoption> or root (this is <emphasis>not</emphasis> the <quote>Printer Operators</quote> group in -NT, but the <emphasis>printer admin</emphasis> group as defined in -the <smbconfsection>[global]</smbconfsection> section of -&smb.conf;).</para></listitem> - -<listitem><para>Copy all required driver files to -<filename>\\SAMBA\print$\w32x86</filename> and -<filename>\\SAMBA\print$\win40</filename> as appropriate. They -will end up in the <quote>0</quote> respective <quote>2</quote> subdirectories later. For now, -<emphasis>do not</emphasis> put them there, they'll be automatically -used by the <command>adddriver</command> subcommand. (If you use -<command>smbclient</command> to put the driver files into the share, note that you need -to escape the <quote>$</quote>: <command>smbclient //sambaserver/print\$ -U -root.</command>)</para></listitem> - -<listitem><para>The user you're connecting as must be able to write to -the <smbconfsection>[print$]</smbconfsection> share and create -subdirectories.</para></listitem> - -<listitem><para>The printer you are going to setup for the Windows -clients needs to be installed in CUPS already.</para></listitem> - -<listitem><para> - <indexterm><primary>rpcclient</primary><secondary>setdriver</secondary></indexterm> - <indexterm><primary>rpcclient</primary><secondary>enumprinters</secondary></indexterm> - The CUPS printer must be known to Samba, otherwise the -<command>setdriver</command> subcommand fails with an -NT_STATUS_UNSUCCESSFUL error. To check if the printer is known by -Samba, you may use the <command>enumprinters</command> subcommand to -<command>rpcclient</command>. A long-standing bug prevented a proper update of the -printer list until every smbd process had received a SIGHUP or was -restarted. Remember this in case you've created the CUPS printer just -recently and encounter problems: try restarting -Samba.</para></listitem> -</itemizedlist> -</sect2> - -<sect2> -<title>Manual Driver Installation in 15 Steps</title> - -<para> -We are going to install a printer driver now by manually executing all -required commands. As this may seem a rather complicated process at -first, we go through the procedure step by step, explaining every -single action item as it comes up. -</para> - -<procedure> - <title>Manual Driver Installation</title> - -<step> -<title>Install the printer on CUPS.</title> - -<para><screen> -&rootprompt;<userinput>lpadmin -p mysmbtstprn -v socket://10.160.51.131:9100 -E \ - -P canonIR85.ppd</userinput> -</screen></para> - -<para> -This installs a printer with the name <parameter>mysmbtstprn</parameter> -to the CUPS system. The printer is accessed via a socket -(a.k.a. JetDirect or Direct TCP/IP) connection. You need to be root -for this step. -</para> -</step> - -<step> -<title>(Optional) Check if the printer is recognized by Samba.</title> - -<para> -<indexterm><primary>rpcclient</primary><secondary>enumprinters</secondary></indexterm> -<screen> - &rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'enumprinters' localhost \ - | grep -C2 mysmbtstprn</userinput> -flags:[0x800000] -name:[\\kde-bitshop\mysmbtstprn] -description:[\\kde-bitshop\mysmbtstprn,,mysmbtstprn] -comment:[mysmbtstprn] -</screen></para> - -<para> -This should show the printer in the list. If not, stop and restart -the Samba daemon (smbd), or send a HUP signal: -<screen> -&rootprompt;<userinput>kill -HUP `pidof smbd`</userinput> -</screen>Check again. Troubleshoot and repeat until -successful. Note the <quote>empty</quote> field between the two commas in the -<quote>description</quote> line. The driver name would appear here if there was one already. You need to know root's Samba password (as set by the -<command>smbpasswd</command> command) for this step and most of the -following steps. Alternately, you can authenticate as one of the -users from the <quote>write list</quote> as defined in &smb.conf; for -<smbconfsection>[print$]</smbconfsection>. -</para> -</step> - -<step> -<title>(Optional) Check if Samba knows a driver for the printer.</title> - -<para> - <indexterm><primary>rpcclient</primary><secondary>getprinter</secondary></indexterm> - <indexterm><primary>rpcclient</primary><secondary>getdriver</secondary></indexterm> - <screen> -&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'getprinter mysmbtstprn 2' localhost \ - | grep driver </userinput> -drivername:[] - -&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'getprinter mysmbtstprn 2' localhost \ - | grep -C4 driv</userinput> -servername:[\\kde-bitshop] -printername:[\\kde-bitshop\mysmbtstprn] -sharename:[mysmbtstprn] -portname:[Samba Printer Port] -drivername:[] -comment:[mysmbtstprn] -location:[] -sepfile:[] -printprocessor:[winprint] - -&rootprompt;<userinput>rpcclient -U root%xxxx -c 'getdriver mysmbtstprn' localhost</userinput> - result was WERR_UNKNOWN_PRINTER_DRIVER - -</screen></para> - -<para> -None of the three commands shown above should show a driver. -This step was done for the purpose of demonstrating this condition. An -attempt to connect to the printer at this stage will prompt the -message along the lines of: <quote>The server does not have the required printer -driver installed.</quote> -</para> -</step> - -<step> -<title>Put all required driver files into Samba's -[print$].</title> - -<para><screen> -&rootprompt;<userinput>smbclient //localhost/print\$ -U 'root%xxxx' \ - -c 'cd W32X86; \ - put /etc/cups/ppd/mysmbtstprn.ppd mysmbtstprn.PPD; \ - put /usr/share/cups/drivers/cupsui.dll cupsui.dll; \ - put /usr/share/cups/drivers/cupsdrvr.dll cupsdrvr.dll; \ - put /usr/share/cups/drivers/cups.hlp cups.hlp'</userinput> -</screen></para> - -<para> -(This command should be entered in one long single -line. Line-breaks and the line-end indicated by <quote>\</quote> have been inserted -for readability reasons.) This step is <emphasis>required</emphasis> -for the next one to succeed. It makes the driver files physically -present in the <smbconfsection>[print$]</smbconfsection> share. However, clients -would still not be able to install them, because Samba does not yet -treat them as driver files. A client asking for the driver would still -be presented with a <quote>not installed here</quote> message. -</para> -</step> - -<step> -<title>Verify where the driver files are now.</title> - -<para><screen> -&rootprompt;<userinput>ls -l /etc/samba/drivers/W32X86/</userinput> -total 669 -drwxr-sr-x 2 root ntadmin 532 May 25 23:08 2 -drwxr-sr-x 2 root ntadmin 670 May 16 03:15 3 --rwxr--r-- 1 root ntadmin 14234 May 25 23:21 cups.hlp --rwxr--r-- 1 root ntadmin 278380 May 25 23:21 cupsdrvr.dll --rwxr--r-- 1 root ntadmin 215848 May 25 23:21 cupsui.dll --rwxr--r-- 1 root ntadmin 169458 May 25 23:21 mysmbtstprn.PPD -</screen></para> - -<para> -The driver files now are in the W32X86 architecture <quote>root</quote> of -<smbconfsection>[print$]</smbconfsection>. -</para> -</step> - -<step> -<title>Tell Samba that these are driver files (<command>adddriver</command>).</title> - -<para> -<indexterm><primary>rpcclient</primary><secondary>adddriver</secondary></indexterm> -<screen> -&rootprompt;<userinput>rpcclient -Uroot%xxxx -c `adddriver "Windows NT x86" \ - "mydrivername:cupsdrvr.dll:mysmbtstprn.PPD: \ - cupsui.dll:cups.hlp:NULL:RAW:NULL" \ - localhost</userinput> -Printer Driver mydrivername successfully installed. -</screen></para> - -<para> -You cannot repeat this step if it fails. It could fail even -as a result of a simple typo. It will most likely have moved a part of -the driver files into the <quote>2</quote> subdirectory. If this step fails, you -need to go back to the fourth step and repeat it before you can try -this one again. In this step, you need to choose a name for your -driver. It is normally a good idea to use the same name as is used for -the printer name; however, in big installations you may use this driver -for a number of printers that obviously have different names, so the -name of the driver is not fixed. -</para> -</step> - -<step> -<title>Verify where the driver files are now.</title> - -<para><screen> -&rootprompt;<userinput>ls -l /etc/samba/drivers/W32X86/</userinput> -total 1 -drwxr-sr-x 2 root ntadmin 532 May 25 23:22 2 -drwxr-sr-x 2 root ntadmin 670 May 16 03:15 3 - -&rootprompt;<userinput>ls -l /etc/samba/drivers/W32X86/2</userinput> -total 5039 -[....] --rwxr--r-- 1 root ntadmin 14234 May 25 23:21 cups.hlp --rwxr--r-- 1 root ntadmin 278380 May 13 13:53 cupsdrvr.dll --rwxr--r-- 1 root ntadmin 215848 May 13 13:53 cupsui.dll --rwxr--r-- 1 root ntadmin 169458 May 25 23:21 mysmbtstprn.PPD -</screen></para> - -<para> -Notice how step 6 also moved the driver files to the appropriate -subdirectory. Compare this with the situation after step 5. -</para> -</step> - -<step> -<title>(Optional) Verify if Samba now recognizes the driver.</title> - -<para> -<indexterm><primary>rpcclient</primary><secondary>enumdrivers</secondary></indexterm> -<screen> -&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'enumdrivers 3' \ - localhost | grep -B2 -A5 mydrivername</userinput> -Printer Driver Info 3: -Version: [2] -Driver Name: [mydrivername] -Architecture: [Windows NT x86] -Driver Path: [\\kde-bitshop\print$\W32X86\2\cupsdrvr.dll] -Datafile: [\\kde-bitshop\print$\W32X86\2\mysmbtstprn.PPD] -Configfile: [\\kde-bitshop\print$\W32X86\2\cupsui.dll] -Helpfile: [\\kde-bitshop\print$\W32X86\2\cups.hlp] -</screen></para> - -<para> -Remember, this command greps for the name you chose for the -driver in step 6. This command must succeed before you can proceed. -</para> -</step> - -<step> -<para>Tell Samba which printer should use these driver files (<command>setdriver</command>).</para> - - -<para> -<indexterm><primary>rpcclient</primary><secondary>setdriver</secondary></indexterm> -<screen> -&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'setdriver mysmbtstprn mydrivername' \ - localhost</userinput> -Successfully set mysmbtstprn to driver mydrivername -</screen></para> - -<para> -Since you can bind any printername (print queue) to any driver, this -is a convenient way to setup many queues that use the same -driver. You do not need to repeat all the previous steps for the -setdriver command to succeed. The only preconditions are: -<command>enumdrivers</command> must find the driver and -<command>enumprinters</command> must find the printer. -</para> -</step> - -<step> - <title>(Optional) Verify if Samba has recognized this association.</title> - -<para> -<indexterm><primary>rpcclient</primary><secondary>getprinter</secondary></indexterm> -<indexterm><primary>rpcclient</primary><secondary>getdriver</secondary></indexterm> -<indexterm><primary>rpcclient</primary><secondary>enumprinters</secondary></indexterm> -<screen> -&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'getprinter mysmbtstprn 2' localhost \ - | grep driver</userinput> -drivername:[mydrivername] - -&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'getprinter mysmbtstprn 2' localhost \ - | grep -C4 driv</userinput> -servername:[\\kde-bitshop] -printername:[\\kde-bitshop\mysmbtstprn] -sharename:[mysmbtstprn] -portname:[Done] -drivername:[mydrivername] -comment:[mysmbtstprn] -location:[] -sepfile:[] -printprocessor:[winprint] - -&rootprompt;<userinput>rpcclient -U root%xxxx -c 'getdriver mysmbtstprn' localhost</userinput> -[Windows NT x86] -Printer Driver Info 3: - Version: [2] - Driver Name: [mydrivername] - Architecture: [Windows NT x86] - Driver Path: [\\kde-bitshop\print$\W32X86\2\cupsdrvr.dll] - Datafile: [\\kde-bitshop\print$\W32X86\2\mysmbtstprn.PPD] - Configfile: [\\kde-bitshop\print$\W32X86\2\cupsui.dll] - Helpfile: [\\kde-bitshop\print$\W32X86\2\cups.hlp] - Monitorname: [] - Defaultdatatype: [RAW] - Monitorname: [] - Defaultdatatype: [RAW] - -&rootprompt;<userinput>rpcclient -Uroot%xxxx -c 'enumprinters' localhost \ - | grep mysmbtstprn</userinput> - name:[\\kde-bitshop\mysmbtstprn] - description:[\\kde-bitshop\mysmbtstprn,mydrivername,mysmbtstprn] - comment:[mysmbtstprn] - -</screen></para> - -<para> -<indexterm><primary>rpcclient</primary><secondary>enumprinters</secondary></indexterm> -Compare these results with the ones from steps 2 and 3. Every one of these commands show the driver is installed. Even -the <command>enumprinters</command> command now lists the driver -on the <quote>description</quote> line. -</para> -</step> - -<step> -<title>(Optional) Tickle the driver into a correct -device mode.</title> - -<para> -<indexterm><primary>"Printers" folder</primary></indexterm> -You certainly know how to install the driver on the client. In case -you are not particularly familiar with Windows, here is a short -recipe: Browse the Network Neighborhood, go to the Samba server, and look -for the shares. You should see all shared Samba printers. -Double-click on the one in question. The driver should get -installed and the network connection set up. An alternate way is to -open the <guilabel>Printers (and Faxes)</guilabel> folder, right-click on the printer in -question and select <guilabel>Connect</guilabel> or <guilabel>Install</guilabel>. As a result, a new printer -should have appeared in your client's local <guilabel>Printers (and Faxes)</guilabel> -folder, named something like <guilabel>printersharename on Sambahostname</guilabel>. -</para> - -<para> -It is important that you execute this step as a Samba printer admin -(as defined in &smb.conf;). Here is another method -to do this on Windows XP. It uses a command line, which you may type -into the <quote>DOS box</quote> (type root's smbpassword when prompted): -</para> - -<para><screen> -&dosprompt;<userinput>runas /netonly /user:root "rundll32 printui.dll,PrintUIEntry \ - /in /n \\sambaserver\mysmbtstprn"</userinput> -</screen></para> - -<para> -Change any printer setting once (like changing <emphasis><guilabel>portrait</guilabel> to - <guilabel>landscape</guilabel></emphasis>), click on <guibutton>Apply</guibutton>; change the setting -back. -</para> -</step> - -<step> -<title>Install the printer on a client -(Point'n'Print).</title> - - -<para> -<indexterm significance="preferred"><primary>point 'n' print</primary></indexterm> - <screen> -&dosprompt;<userinput>rundll32 printui.dll,PrintUIEntry /in /n <quote>\\sambaserver\mysmbtstprn</quote></userinput> -</screen></para> - -<para> -If it does not work it could be a permission problem with the -<smbconfsection>[print$]</smbconfsection> share. -</para> -</step> - -<step> -<title>(Optional) Print a test page.</title> - -<para><screen> -&dosprompt;<userinput>rundll32 printui.dll,PrintUIEntry /p /n "\\sambaserver\mysmbtstprn"</userinput> -</screen></para> - -<para> -Then hit [TAB] five times, [ENTER] twice, [TAB] once and [ENTER] again -and march to the printer. -</para> -</step> - -<step> -<title>(Recommended) Study the test page.</title> - -<para> -Hmmm.... just kidding! By now you know everything about printer -installations and you do not need to read a word. Just put it in a -frame and bolt it to the wall with the heading "MY FIRST -RPCCLIENT-INSTALLED PRINTER" &smbmdash; why not just throw it away! -</para> -</step> - -<step> -<title>(Obligatory) Enjoy. Jump. Celebrate your -success.</title> - -<para><screen> -&rootprompt;<userinput>echo "Cheeeeerioooooo! Success..." >> /var/log/samba/log.smbd</userinput> -</screen></para> -</step> -</procedure> -</sect2> - -<sect2> -<title>Troubleshooting Revisited</title> - -<para> -The setdriver command will fail, if in Samba's mind the queue is not -already there. You had promising messages about the: -</para> - -<para><screen> - Printer Driver ABC successfully installed. -</screen></para> - -<para> -after the <command>adddriver</command> parts of the procedure? But you are also seeing -a disappointing message like this one? -</para> - -<para><computeroutput> - result was NT_STATUS_UNSUCCESSFUL -</computeroutput></para> - -<para> -<indexterm><primary>lpstat</primary></indexterm> -It is not good enough that you -can see the queue in CUPS, using -the <command>lpstat -p ir85wm</command> command. A -bug in most recent versions of Samba prevents the proper update of -the queuelist. The recognition of newly installed CUPS printers -fails unless you restart Samba or send a HUP to all smbd -processes. To verify if this is the reason why Samba does not -execute the <command>setdriver</command> command successfully, check if Samba <quote>sees</quote> -the printer: -</para> - -<para> -<indexterm><primary>rpcclient</primary><secondary>enumprinters</secondary></indexterm> - <screen> -&rootprompt;<userinput>rpcclient transmeta -N -U'root%xxxx' -c 'enumprinters 0'|grep ir85wm</userinput> - printername:[ir85wm] -</screen></para> - -<para> -An alternate command could be this: -</para> - -<para> -<indexterm><primary>rpcclient</primary><secondary>getprinter</secondary></indexterm> - <screen> -&rootprompt;<userinput>rpcclient transmeta -N -U'root%secret' -c 'getprinter ir85wm' </userinput> - cmd = getprinter ir85wm - flags:[0x800000] - name:[\\transmeta\ir85wm] - description:[\\transmeta\ir85wm,ir85wm,DPD] - comment:[CUPS PostScript-Treiber for Windows NT/200x/XP] -</screen></para> - -<para> -By the way, you can use these commands, plus a few more, of course, -to install drivers on remote Windows NT print servers too! -</para> -</sect2> -</sect1> - -<sect1> -<title>The Printing <filename>*.tdb</filename> Files</title> - -<para> -<indexterm><primary>TDB</primary></indexterm> -<indexterm><primary>connections.tdb</primary><seealso>TDB</seealso></indexterm> -<indexterm><primary>printing.tdb</primary><seealso>TDB</seealso></indexterm> -<indexterm><primary>share_info.tdb</primary><seealso>TDB</seealso></indexterm> -<indexterm><primary>ntdrivers.tdb</primary><seealso>TDB</seealso></indexterm> -<indexterm><primary>unexpected.tdb</primary><seealso>TDB</seealso></indexterm> -<indexterm><primary>brlock.tdb</primary><seealso>TDB</seealso></indexterm> -<indexterm><primary>locking.tdb</primary><seealso>TDB</seealso></indexterm> -<indexterm><primary>ntforms.tdb</primary><seealso>TDB</seealso></indexterm> -<indexterm><primary>messages.tdb</primary><seealso>TDB</seealso></indexterm> -<indexterm><primary>ntprinters.tdb</primary><seealso>TDB</seealso></indexterm> -<indexterm><primary>sessionid.tdb</primary><seealso>TDB</seealso></indexterm> -<indexterm><primary>secrets.tdb</primary><seealso>TDB</seealso></indexterm> -Some mystery is associated with the series of files with a -tdb suffix appearing in every Samba installation. They are -<filename>connections.tdb</filename>, -<filename>printing.tdb</filename>, -<filename>share_info.tdb</filename>, -<filename>ntdrivers.tdb</filename>, -<filename>unexpected.tdb</filename>, -<filename>brlock.tdb</filename>, -<filename>locking.tdb</filename>, -<filename>ntforms.tdb</filename>, -<filename>messages.tdb</filename> , -<filename>ntprinters.tdb</filename>, -<filename>sessionid.tdb</filename> and -<filename>secrets.tdb</filename>. What is their purpose? -</para> - -<sect2> -<title>Trivial Database Files</title> - -<para> -<indexterm><primary>TDB</primary></indexterm> -A Windows NT (print) server keeps track of all information needed to serve -its duty toward its clients by storing entries in the Windows -registry. Client queries are answered by reading from the registry, -Administrator or user configuration settings that are saved by writing into -the registry. Samba and UNIX obviously do not have such a -Registry. Samba instead keeps track of all client related information in a -series of <filename>*.tdb</filename> files. (TDB = Trivial Data -Base). These are often located in <filename>/var/lib/samba/</filename> -or <filename>/var/lock/samba/</filename>. The printing related files -are <filename>ntprinters.tdb</filename>, -<filename>printing.tdb</filename>,<filename>ntforms.tdb</filename> and -<filename>ntdrivers.tdb</filename>. -</para> -</sect2> - -<sect2> -<title>Binary Format</title> - -<para> -<filename>*.tdb</filename> files are not human readable. They are -written in a binary format. <quote>Why not ASCII?</quote>, you may ask. <quote>After all, -ASCII configuration files are a good and proven tradition on UNIX.</quote> -The reason for this design decision by the Samba team is mainly -performance. Samba needs to be fast; it runs a separate -<command>smbd</command> process for each client connection, in some -environments many thousands of them. Some of these smbds might need to -write-access the same <filename>*.tdb</filename> file <emphasis>at the -same time</emphasis>. The file format of Samba's -<filename>*.tdb</filename> files allows for this provision. Many smbd -processes may write to the same <filename>*.tdb</filename> file at the -same time. This wouldn't be possible with pure ASCII files. -</para> -</sect2> - -<sect2> -<title>Losing <filename>*.tdb</filename> Files</title> - -<para> -It is very important that all <filename>*.tdb</filename> files remain -consistent over all write and read accesses. However, it may happen -that these files <emphasis>do</emphasis> get corrupted. (A -<command>kill -9 `pidof smbd'</command> while a write access is in -progress could do the damage as well as a power interruption, -etc.). In cases of trouble, a deletion of the old printing-related -<filename>*.tdb</filename> files may be the only option. After that you need to -re-create all print-related setup or you have made a -backup of the <filename>*.tdb</filename> files in time. -</para> -</sect2> - -<sect2> -<title>Using <command>tdbbackup</command></title> - - -<para> -<indexterm><primary>TDB</primary><secondary>backing up</secondary><see>tdbbackup</see></indexterm> -<indexterm><primary>tdbbackup</primary></indexterm> -Samba ships with a little utility that helps the root user of your -system to backup your <filename>*.tdb</filename> files. If you run it -with no argument, it prints a usage message: -</para> - -<para><screen> -&rootprompt;<userinput>tdbbackup</userinput> - Usage: tdbbackup [options] <fname...> - - Version:3.0a - -h this help message - -s suffix set the backup suffix - -v verify mode (restore if corrupt) - -</screen></para> - -<para> -Here is how I backed up my <filename>printing.tdb</filename> file: -</para> - -<para><screen> -&rootprompt;<userinput>ls</userinput> -. browse.dat locking.tdb ntdrivers.tdb printing.tdb -.. share_info.tdb connections.tdb messages.tdb ntforms.tdb -printing.tdbkp unexpected.tdb brlock.tdb gmon.out namelist.debug -ntprinters.tdb sessionid.tdb - -&rootprompt;<userinput>tdbbackup -s .bak printing.tdb</userinput> - printing.tdb : 135 records - -&rootprompt;<userinput>ls -l printing.tdb*</userinput> - -rw------- 1 root root 40960 May 2 03:44 printing.tdb - -rw------- 1 root root 40960 May 2 03:44 printing.tdb.bak - -</screen></para> -</sect2> -</sect1> - -<sect1> -<title>CUPS Print Drivers from Linuxprinting.org</title> - - -<para> -<indexterm><primary>Linuxprinting.org</primary></indexterm> -CUPS ships with good support for HP LaserJet-type printers. You can -install the generic driver as follows: -</para> - - -<para> -<indexterm><primary>lpadmin</primary></indexterm> - <screen> -&rootprompt;<userinput>lpadmin -p laserjet4plus -v parallel:/dev/lp0 -E -m laserjet.ppd</userinput> -</screen></para> - -<para> -The <option>-m</option> switch will retrieve the -<filename>laserjet.ppd</filename> from the standard repository for -not-yet-installed-PPDs, which CUPS typically stores in -<filename>/usr/share/cups/model</filename>. Alternately, you may use -<option>-P /path/to/your.ppd</option>. -</para> - -<para> -The generic <filename>laserjet.ppd,</filename> however, does not support every special option -for every LaserJet-compatible model. It constitutes a sort of <quote>least common -denominator</quote> of all the models. If for some reason -you must pay for the commercially available ESP Print Pro drivers, your -first move should be to consult the database on <ulink -noescape="1" url="http://www.linuxprinting.org/printer_list.cgi">http://www.linuxprinting.org/printer_list.cgi</ulink>. -Linuxprinting.org has excellent recommendations about which driver is -best used for each printer. Its database is kept current by the -tireless work of Till Kamppeter from MandrakeSoft, who is also the -principal author of the <command>foomatic-rip</command> utility. -</para> - -<note><para> -<indexterm><primary>foomatic-rip</primary></indexterm> -The former <command>cupsomatic</command> concept is now being replaced by the new -successor, a much -more powerful <command>foomatic-rip</command>. -<command>cupsomatic</command> is no longer maintained. Here is the new URL -to the Foomatic-3.0 database: <ulink -noescape="1" url="http://www.linuxprinting.org/driver_list.cgi">http://www.linuxprinting.org/driver_list.cgi</ulink>. -If you upgrade to <command>foomatic-rip</command>, remember to also upgrade to the -new-style PPDs for your Foomatic-driven printers. foomatic-rip will -not work with PPDs generated for the old <command>cupsomatic</command>. The new-style -PPDs are 100% compliant to the Adobe PPD specification. They are -also intended to be used by Samba and the cupsaddsmb utility, to -provide the driver files for the Windows clients! -</para></note> - -<sect2> -<title>foomatic-rip and Foomatic Explained</title> - - -<para> -<indexterm significance="preferred"><primary>foomatic</primary></indexterm> -<indexterm significance="preferred"><primary>foomatic-rip</primary></indexterm> -Nowadays, most Linux distributions rely on the utilities of Linuxprinting.org -to create their printing-related software (which, by the way, works on all -UNIXes and on Mac OS X or Darwin, too). It is not known as well as it -should be, that it also has a very end-user-friendly interface that -allows for an easy update of drivers and PPDs for all supported -models, all spoolers, all operating systems, and all package formats -(because there is none). Its history goes back a few years. -</para> - -<para> -Recently, Foomatic has achieved the astonishing milestone of <ulink -url="http://www.linuxprinting.org/printer_list.cgi?make=Anyone">1000 -listed</ulink> printer models. Linuxprinting.org keeps all the -important facts about printer drivers, supported models and which -options are available for the various driver/printer combinations in -its <ulink -url="http://www.linuxprinting.org/foomatic.html">Foomatic</ulink> -database. Currently there are <ulink -url="http://www.linuxprinting.org/driver_list.cgi">245 drivers</ulink> -in the database. Many drivers support various models, and many models -may be driven by different drivers &smbmdash; its your choice! -</para> - -<sect3> -<title>690 <quote>Perfect</quote> Printers</title> - -<para> -At present, there are 690 devices dubbed as working perfectly, 181 -mostly, 96 partially, and 46 are paperweights. Keeping in mind -that most of these are non-PostScript models (PostScript printers are -automatically supported by CUPS to perfection, by using -their own manufacturer-provided Windows-PPD), and that a -multifunctional device never qualifies as working perfectly if it -does not also scan and copy and fax under GNU/Linux &smbmdash; then this is a -truly astonishing achievement! Three years ago the number was not -more than 500, and Linux or UNIX printing at the time wasn't -anywhere near the quality it is today. -</para> -</sect3> - -<sect3> -<title>How the Printing HOWTO Started It All</title> - -<para> -A few years ago <ulink url="http://www2.picante.com:81/~gtaylor/">Grant Taylor</ulink> -started it all. The roots of today's Linuxprinting.org are in the -first <ulink url="http://www.linuxprinting.org/foomatic2.9/howto/">Linux Printing -HOWTO</ulink> that he authored. As a side-project to this document, -which served many Linux users and admins to guide their first steps in -this complicated and delicate setup (to a scientist, printing is -<quote>applying a structured deposition of distinct patterns of ink or toner -particles on paper substrates</quote>, he started to -build in a little Postgres database with information about the -hardware and driver zoo that made up Linux printing of the time. This -database became the core component of today's Foomatic collection of -tools and data. In the meantime, it has moved to an XML representation -of the data. -</para> -</sect3> - -<sect3> -<title>Foomatic's Strange Name</title> - - -<para> -<indexterm><primary>foomatic</primary></indexterm> -<quote>Why the funny name?</quote> you ask. When it really took off, around spring -2000, CUPS was far less popular than today, and most systems used LPD, -LPRng or even PDQ to print. CUPS shipped with a few generic drivers -(good for a few hundred different printer models). These didn't -support many device-specific options. CUPS also shipped with its own -built-in rasterization filter (<parameter>pstoraster</parameter>, derived from -Ghostscript). On the other hand, CUPS provided brilliant support for -<emphasis>controlling</emphasis> all printer options through -standardized and well-defined PPD files (PostScript Printers -Description files). Plus, CUPS was designed to be easily extensible. -</para> - -<para> -Taylor already had in his database a respectable compilation -of facts about many more printers and the Ghostscript <quote>drivers</quote> -they run with. His idea, to generate PPDs from the database information -and use them to make standard Ghostscript filters work within CUPS, -proved to work very well. It also killed several birds with one -stone: -</para> - -<itemizedlist> -<listitem><para>It made all current and future Ghostscript filter -developments available for CUPS.</para></listitem> - -<listitem><para>It made available a lot of additional printer models -to CUPS users (because often the traditional Ghostscript way of -printing was the only one available).</para></listitem> - -<listitem><para>It gave all the advanced CUPS options (Web interface, -GUI driver configurations) to users wanting (or needing) to use -Ghostscript filters.</para></listitem> -</itemizedlist> -</sect3> - -<sect3> -<title>cupsomatic, pdqomatic, lpdomatic, directomatic</title> - - -<para> -<indexterm><primary>cupsomatic</primary></indexterm> -<indexterm><primary>CUPS-PPD</primary></indexterm> -<indexterm><primary>PPD</primary><secondary>CUPS</secondary><see>CUPS-PPD</see></indexterm> -CUPS worked through a quickly-hacked up filter script named <ulink -url="http://www.linuxprinting.org/download.cgi?filename=cupsomatic&show=0">cupsomatic.</ulink> -cupsomatic ran the printfile through Ghostscript, constructing -automatically the rather complicated command line needed. It just -needed to be copied into the CUPS system to make it work. To -configure the way cupsomatic controls the Ghostscript rendering -process, it needs a CUPS-PPD. This PPD is generated directly from the -contents of the database. For CUPS and the respective printer/filter -combo, another Perl script named CUPS-O-Matic did the PPD -generation. After that was working, Taylor implemented within a few -days a similar thing for two other spoolers. Names chosen for the -config-generator scripts were <ulink -url="http://www.linuxprinting.org/download.cgi?filename=lpdomatic&show=0">PDQ-O-Matic</ulink> -(for PDQ) and <ulink -url="http://www.linuxprinting.org/download.cgi?filename=lpdomatic&show=0">LPD-O-Matic</ulink> -(for &smbmdash; you guessed it &smbmdash; LPD); the configuration here didn't use PPDs -but other spooler-specific files. -</para> - -<para> -From late summer of that year, <ulink url="http://www.linuxprinting.org/till/">Till Kamppeter</ulink> -started to put work into the database. Kamppeter had been newly employed by -<ulink url="http://www.mandrakesoft.com/">MandrakeSoft</ulink> to -convert its printing system over to CUPS, after they had seen his -<ulink url="http://www.fltk.org/">FLTK</ulink>-based <ulink -url="http://cups.sourceforge.net/xpp/">XPP</ulink> (a GUI frontend to -the CUPS lp-command). He added a huge amount of new information and new -printers. He also developed the support for other spoolers, like -<ulink url="http://ppr.sourceforge.net/">PPR</ulink> (via ppromatic), -<ulink url="http://sourceforge.net/projects/lpr/">GNUlpr</ulink> and -<ulink url="http://www.lprng.org/">LPRng</ulink> (both via an extended -lpdomatic) and spoolerless printing (<ulink -url="http://www.linuxprinting.org/download.cgi?filename=directomatic&show=0">directomatic</ulink>). -</para> - -<para> -So, to answer your question: <quote>Foomatic</quote> is the general name for all -the overlapping code and data behind the <quote>*omatic</quote> scripts. -Foomatic, up to versions 2.0.x, required (ugly) Perl data structures -attached to Linuxprinting.org PPDs for CUPS. It had a different -<quote>*omatic</quote> script for every spooler, as well as different printer -configuration files. -</para> -</sect3> - -<sect3> -<title>The <emphasis>Grand Unification</emphasis> Achieved</title> - - -<para> -<indexterm><primary>foomatic-rip</primary></indexterm> -This has all changed in Foomatic versions 2.9 (beta) and released as -<quote>stable</quote> 3.0. It has now achieved the convergence of all *omatic -scripts and is called the <ulink -url="http://www.linuxprinting.org/foomatic2.9/download.cgi?filename=foomatic-rip&show=0">foomatic-rip.</ulink> -This single script is the unification of the previously different -spooler-specific *omatic scripts. foomatic-rip is used by all the -different spoolers alike and because it can read PPDs (both the -original PostScript printer PPDs and the Linuxprinting.org-generated -ones), all of a sudden all supported spoolers can have the power of -PPDs at their disposal. Users only need to plug foomatic-rip into -their system. For users there is improved media type and source -support &smbmdash; paper sizes and trays are easier to configure. -</para> - -<para> -Also, the New Generation of Linuxprinting.org PPDs no longer contains -Perl data structures. If you are a distro maintainer and have -used the previous version of Foomatic, you may want to give the new -one a spin, but remember to generate a new-version set of PPDs -via the new <ulink -url="http://www.linuxprinting.org/download/foomatic/foomatic-db-engine-3.0.0beta1.tar.gz">foomatic-db-engine!</ulink> -Individual users just need to generate a single new PPD specific to -their model by <ulink -url="http://www.linuxprinting.org/kpfeifle/LinuxKongress2002/Tutorial/II.Foomatic-User/II.tutorial-handout-foomatic-user.html">following -the steps</ulink> outlined in the Foomatic tutorial or in this chapter. This new development is truly amazing. -</para> - -<para> -foomatic-rip is a very clever wrapper around the need to run -Ghostscript with a different syntax, options, device selections, and/or filters for each different printer -or spooler. At the same time it can read the PPD associated -with a print queue and modify the print job according to the user -selections. Together with this comes the 100% compliance of the new -Foomatic PPDs with the Adobe spec. Some innovative features of -the Foomatic concept may surprise users. It will support custom paper -sizes for many printers and will support printing on media drawn -from different paper trays within the same job (in both cases, even -where there is no support for this from Windows-based vendor printer -drivers). -</para> -</sect3> - -<sect3> -<title>Driver Development Outside</title> - -<para> -Most driver development itself does not happen within -Linuxprinting.org. Drivers are written by independent maintainers. -Linuxprinting.org just pools all the information and stores it in its -database. In addition, it also provides the Foomatic glue to integrate -the many drivers into any modern (or legacy) printing system known to -the world. -</para> - -<para> -Speaking of the different driver development groups, most of -the work is currently done in three projects. These are: -</para> - -<itemizedlist> -<listitem><para><ulink -url="http://www-124.ibm.com/developerworks/oss/linux/projects/omni/">Omni</ulink> -&smbmdash; a free software project by IBM that tries to convert their printer -driver knowledge from good-ol' OS/2 times into a modern, modular, -universal driver architecture for Linux/UNIX (still beta). This -currently supports 437 models.</para></listitem> - -<listitem><para><ulink url="http://hpinkjet.sf.net/">HPIJS</ulink> &smbmdash; -a free software project by HP to provide the support for their own -range of models (very mature, printing in most cases is perfect and -provides true photo quality). This currently supports 369 -models.</para></listitem> - -<listitem><para><ulink -url="http://gimp-print.sf.net/">Gimp-Print</ulink> &smbmdash; a free software -effort, started by Michael Sweet (also lead developer for CUPS), now -directed by Robert Krawitz, which has achieved an amazing level of -photo print quality (many Epson users swear that its quality is -better than the vendor drivers provided by Epson for the Microsoft -platforms). This currently supports 522 models.</para></listitem> -</itemizedlist> -</sect3> - -<sect3> -<title>Forums, Downloads, Tutorials, Howtos &smbmdash; also for Mac OS X and Commercial UNIX</title> - -<para> -Linuxprinting.org today is the one-stop shop to download printer -drivers. Look for printer information and <ulink -url="http://www.linuxprinting.org//kpfeifle/LinuxKongress2002/Tutorial/">tutorials</ulink> -or solve printing problems in its popular <ulink -url="http://www.linuxprinting.org/newsportal/">forums.</ulink> This forum -it's not just for GNU/Linux users, but admins of <ulink -url="http://www.linuxprinting.org/macosx/">commercial UNIX -systems</ulink> are also going there, and the relatively new <ulink -url="http://www.linuxprinting.org/newsportal/thread.php3?name=linuxprinting.macosx.general">Mac -OS X forum</ulink> has turned out to be one of the most frequented -forums after only a few weeks. -</para> - -<para> -Linuxprinting.org and the Foomatic driver wrappers around Ghostscript -are now a standard toolchain for printing on all the important -distros. Most of them also have CUPS underneath. While in recent years -most printer data had been added by Kamppeter (who works at Mandrake), many -additional contributions came from engineers with SuSE, RedHat, -Connectiva, Debian, and others. Vendor-neutrality is an important goal -of the Foomatic project. -</para> - -<note><para> -Till Kamppeter from MandrakeSoft is doing an excellent job in his -spare time to maintain Linuxprinting.org and Foomatic. So if you use -it often, please send him a note showing your appreciation. -</para></note> -</sect3> - -<sect3> -<title>Foomatic Database-Generated PPDs</title> - -<para> -The Foomatic database is an amazing piece of ingenuity in itself. Not -only does it keep the printer and driver information, but it is -organized in a way that it can generate PPD files on the fly from -its internal XML-based datasets. While these PPDs are modelled to the -Adobe specification of PostScript Printer Descriptions (PPDs), the -Linuxprinting.org/Foomatic-PPDs do not normally drive PostScript -printers. They are used to describe all the bells and whistles you -could ring or blow on an Epson Stylus inkjet, or a HP Photosmart, or -what-have-you. The main trick is one little additional line, not -envisaged by the PPD specification, starting with the <parameter>*cupsFilter</parameter> -keyword. It tells the CUPS daemon how to proceed with the PostScript -print file (old-style Foomatic-PPDs named the -cupsomatic filter script, while the new-style -PPDs are now call foomatic-rip). This filter -script calls Ghostscript on the host system (the recommended variant -is ESP Ghostscript) to do the rendering work. foomatic-rip knows which -filter or internal device setting it should ask from Ghostscript to -convert the PostScript printjob into a raster format ready for the -target device. This usage of PPDs to describe the options of non-PS -printers was the invention of the CUPS developers. The rest is easy. -GUI tools (like KDE's marvelous <ulink -url="http://printing.kde.org/overview/kprinter.phtml">kprinter,</ulink> -or the GNOME <ulink -url="http://gtklp.sourceforge.net/">gtklp,</ulink> xpp and the CUPS -Web interface) read the PPD as well and use this information to present -the available settings to the user as an intuitive menu selection. -</para> -</sect3> -</sect2> - -<sect2> -<title>foomatic-rip and Foomatic-PPD Download and Installation</title> - -<para> -Here are the steps to install a foomatic-rip driven LaserJet 4 Plus-compatible -printer in CUPS (note that recent distributions of SuSE, UnitedLinux and -Mandrake may ship with a complete package of Foomatic-PPDs plus the -<command>foomatic-rip</command> utility. Going directly to -Linuxprinting.org ensures that you get the latest driver/PPD files): -</para> - -<itemizedlist> -<listitem><para>Open your browser at the Linuxprinting.org printer list<ulink url="http://www.linuxprinting.org/printer_list.cgi">page.</ulink> -</para></listitem> - -<listitem><para>Check the complete list of printers in the -<ulink url="http://www.linuxprinting.org/printer_list.cgi?make=Anyone">database.</ulink>. -</para></listitem> - -<listitem><para>Select your model and click on the link. -</para></listitem> - -<listitem><para>You'll arrive at a page listing all drivers working with this -model (for all printers, there will always be <emphasis>one</emphasis> -recommended driver. Try this one first). -</para></listitem> - -<listitem><para>In our case (HP LaserJet 4 Plus), we'll arrive at the default driver for the -<ulink url="http://www.linuxprinting.org/show_printer.cgi?recnum=HP-LaserJet_4_Plus">HP-LaserJet 4 Plus.</ulink> -</para></listitem> - -<listitem><para>The recommended driver is ljet4.</para></listitem> - -<listitem><para>Several links are provided here. You should visit them all if you -are not familiar with the Linuxprinting.org database. -</para></listitem> - -<listitem><para>There is a link to the database page for the -<ulink url="http://www.linuxprinting.org/show_driver.cgi?driver=ljet4">ljet4.</ulink> -On the driver's page, you'll find important and detailed information -about how to use that driver within the various available -spoolers.</para></listitem> - -<listitem><para>Another link may lead you to the homepage of the -driver author or the driver.</para></listitem> - -<listitem><para>Important links are the ones that provide hints with -setup instructions for <ulink noescape="1" url="http://www.linuxprinting.org/cups-doc.html">CUPS</ulink>, -<ulink url="http://www.linuxprinting.org/pdq-doc.html">PDQ</ulink>, -<ulink url="http://www.linuxprinting.org/lpd-doc.html">LPD, LPRng and GNUlpr</ulink>) -as well as <ulink url="http://www.linuxprinting.org/ppr-doc.html">PPR</ulink> -or <quote>spooler-less</quote> <ulink url="http://www.linuxprinting.org/direct-doc.html">printing.</ulink> -</para></listitem> - -<listitem><para>You can view the PPD in your browser through this link: -<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> -</para></listitem> <listitem><para>Most importantly, you can also generate and download -the <ulink url="http://www.linuxprinting.org/ppd-o-matic.cgi?driver=ljet4&printer=HP-LaserJet_4_Plus&show=0">PPD.</ulink> -</para></listitem> - -<listitem><para>The PPD contains all the information needed to use our -model and the driver; once installed, this works transparently -for the user. Later you'll only need to choose resolution, paper size, -and so on from the Web-based menu, or from the print dialog GUI, or from -the command line.</para></listitem> - -<listitem><para>If you ended up on the drivers -<ulink url="http://www.linuxprinting.org/show_driver.cgi?driver=ljet4">page</ulink> -you can choose to use the <quote>PPD-O-Matic</quote> online PPD generator -program.</para></listitem> - -<listitem><para>Select the exact model and check either <guilabel>Download</guilabel> or -<guilabel>Display PPD file</guilabel> and click <guilabel>Generate PPD file</guilabel>.</para></listitem> - -<listitem><para>If you save the PPD file from the browser view, please -do not use cut and paste (since it could possibly damage line endings -and tabs, which makes the PPD likely to fail its duty), but use <guimenuitem>Save -as...</guimenuitem> in your browser's menu. (It is best to use the <guilabel>Download</guilabel> option -directly from the Web page).</para></listitem> - -<listitem><para>Another interesting part on each driver page is -the <guimenuitem>Show execution details</guimenuitem> button. If you -select your printer model and click on that button, -a complete Ghostscript command line will be displayed, enumerating all options -available for that combination of driver and printer model. This is a great way to -<quote>learn Ghostscript by doing</quote>. It is also an excellent cheat sheet -for all experienced users who need to re-construct a good command line -for that damn printing script, but can't remember the exact -syntax. </para></listitem> - -<listitem><para>Some time during your visit to Linuxprinting.org, save -the PPD to a suitable place on your harddisk, say -<filename>/path/to/my-printer.ppd</filename> (if you prefer to install -your printers with the help of the CUPS Web interface, save the PPD to -the <filename>/usr/share/cups/model/</filename> path and restart -cupsd).</para></listitem> - -<listitem><para>Then install the printer with a suitable command line, -like this: -</para> - -<para><screen> -&rootprompt;<userinput>lpadmin -p laserjet4plus -v parallel:/dev/lp0 -E \ - -P path/to/my-printer.ppd</userinput> -</screen></para></listitem> - -<listitem><para>For all the new-style <quote>Foomatic-PPDs</quote> -from Linuxprinting.org, you also need a special CUPS filter named -foomatic-rip. -</para></listitem> - -<listitem><para>The foomatic-rip Perlscript itself also makes some -interesting <ulink url="http://www.linuxprinting.org/foomatic2.9/download.cgi?filename=foomatic-rip&show=1">reading</ulink> -because it is well documented by Kamppeter's inline comments (even -non-Perl hackers will learn quite a bit about printing by reading -it).</para></listitem> - -<listitem><para>Save foomatic-rip either directly in -<filename>/usr/lib/cups/filter/foomatic-rip</filename> or somewhere in -your $PATH (and remember to make it world-executable). Again, -do not save by copy and paste but use the appropriate link or the -<guimenuitem>Save as...</guimenuitem> menu item in your browser.</para></listitem> - -<listitem><para>If you save foomatic-rip in your $PATH, create a symlink: -<screen> -&rootprompt;<userinput>cd /usr/lib/cups/filter/ ; ln -s `which foomatic-rip'</userinput> -</screen> -</para> - -<para> -CUPS will discover this new available filter at startup after restarting -cupsd.</para></listitem> -</itemizedlist> - -<para> -Once you print to a print queue set up with the Foomatic-PPD, CUPS will -insert the appropriate commands and comments into the resulting -PostScript jobfile. foomatic-rip is able to read and act upon -these and uses some specially encoded Foomatic comments -embedded in the jobfile. These in turn are used to construct -(transparently for you, the user) the complicated Ghostscript command -line telling the printer driver exactly how the resulting raster -data should look and which printer commands to embed into the -data stream. You need: -</para> - -<itemizedlist> - -<listitem><para>A <quote>foomatic+something</quote> PPD &smbmdash; but this is not enough -to print with CUPS (it is only <emphasis>one</emphasis> important -component).</para></listitem> - -<listitem><para>The <parameter>foomatic-rip</parameter> filter script (Perl) in -<filename>/usr/lib/cups/filters/</filename>.</para></listitem> - -<listitem><para>Perl to make foomatic-rip run.</para></listitem> - -<listitem><para>Ghostscript (because it is doing the main work, -controlled by the PPD/foomatic-rip combo) to produce the raster data -fit for your printer model's consumption.</para></listitem> - -<listitem><para>Ghostscript <emphasis>must</emphasis> (depending on -the driver/model) contain support for a certain device representing -the selected driver for your model (as shown by <command>gs - -h</command>).</para></listitem> - -<listitem><para>foomatic-rip needs a new version of PPDs (PPD versions -produced for cupsomatic do not work with -foomatic-rip).</para></listitem> -</itemizedlist> -</sect2> -</sect1> - -<sect1> -<title>Page Accounting with CUPS</title> - - -<para> -<indexterm><primary>CUPS</primary><secondary>Page Accounting</secondary></indexterm> -Often there are questions regarding print quotas where Samba users -(that is, Windows clients) should not be able to print beyond a -certain number of pages or data volume per day, week or month. This -feature is dependent on the real print subsystem you're using. -Samba's part is always to receive the job files from the clients -(filtered <emphasis>or</emphasis> unfiltered) and hand it over to this -printing subsystem. -</para> - -<para> -Of course one could hack things with one's own scripts. But then -there is CUPS. CUPS supports quotas that can be based on the size of -jobs or on the number of pages or both, and span any time -period you want. -</para> - -<sect2> -<title>Setting Up Quotas</title> - -<para> -<indexterm><primary>CUPS</primary><secondary>quotas</secondary></indexterm> -This is an example command of how root would set a print quota in CUPS, -assuming an existing printer named <quote>quotaprinter</quote>: -</para> - - -<para> -<indexterm><primary>lpadmin</primary></indexterm> - <screen> -&rootprompt;<userinput>lpadmin -p quotaprinter -o job-quota-period=604800 \ - -o job-k-limit=1024 -o job-page-limit=100</userinput> -</screen></para> - -<para> -This would limit every single user to print 100 pages or 1024 KB of -data (whichever comes first) within the last 604,800 seconds ( = 1 -week). -</para> -</sect2> - -<sect2> -<title>Correct and Incorrect Accounting</title> - -<para> -For CUPS to count correctly, the printfile needs to pass the CUPS -pstops filter, otherwise it uses a dummy count of <quote>one</quote>. Some -print files do not pass it (e.g., image files) but then those are mostly one- -page jobs anyway. This also means that proprietary drivers for the -target printer running on the client computers and CUPS/Samba, which -then spool these files as <quote>raw</quote> (i.e., leaving them untouched, not -filtering them), will be counted as one-pagers too! -</para> - -<para> -You need to send PostScript from the clients (i.e., run a PostScript -driver there) to have the chance to get accounting done. If the -printer is a non-PostScript model, you need to let CUPS do the job to -convert the file to a print-ready format for the target printer. This -is currently working for about a thousand different printer models. -Linuxprinting has a driver -<ulink url="http://www.linuxprinting.org/printer_list.cgi">list.</ulink> -</para> -</sect2> - -<sect2> -<title>Adobe and CUPS PostScript Drivers for Windows Clients</title> - -<para> -Before CUPS 1.1.16, your only option was to use the Adobe PostScript -Driver on the Windows clients. The output of this driver was not -always passed through the <command>pstops</command> filter on the CUPS/Samba side, and -therefore was not counted correctly (the reason is that it often, -depending on the PPD being used, wrote a PJL-header in front of -the real PostScript which caused CUPS to skip <command>pstops</command> and go directly -to the <command>pstoraster</command> stage). -</para> - -<para> -From CUPS 1.1.16 onward, you can use the CUPS PostScript Driver for -Windows <?latex \linebreak ?>NT/200x/XP clients (which is tagged in the download area of -<filename>http://www.cups.org/</filename> as the <filename>cups-samba-1.1.16.tar.gz</filename> -package). It does <emphasis>not</emphasis> work for Windows 9x/ME clients, but it guarantees: -</para> - -<itemizedlist> - -<listitem><para> <indexterm><primary>PJL</primary></indexterm> To not write a PJL-header.</para></listitem> - -<listitem><para>To still read and support all PJL-options named in the -driver PPD with its own means.</para></listitem> - -<listitem><para>That the file will pass through the <command>pstops</command> filter -on the CUPS/Samba server.</para></listitem> - -<listitem><para>To page-count correctly the print file.</para></listitem> -</itemizedlist> - -<para> -You can read more about the setup of this combination in the man page -for <command>cupsaddsmb</command> (which is only present with CUPS installed, and only -current from CUPS 1.1.16). -</para> -</sect2> - -<sect2> -<title>The page_log File Syntax</title> - -<para> -<indexterm><primary>page_log</primary></indexterm> -These are the items CUPS logs in the <filename>page_log</filename> for every -page of a job: -</para> - -<itemizedlist> -<listitem><para>Printer name</para></listitem> - -<listitem><para>User name</para></listitem> - -<listitem><para>Job ID</para></listitem> - -<listitem><para>Time of printing</para></listitem> - -<listitem><para>The page number</para></listitem> - -<listitem><para>The number of copies</para></listitem> - -<listitem><para>A billing information string (optional)</para></listitem> - -<listitem><para>The host that sent the job (included since version 1.1.19)</para></listitem> -</itemizedlist> - -<para> -Here is an extract of my CUPS server's <filename>page_log</filename> file to illustrate the -format and included items: -</para> - -<para><screen> -tec_IS2027 kurt 401 [22/Apr/2003:10:28:43 +0100] 1 3 #marketing 10.160.50.13 -tec_IS2027 kurt 401 [22/Apr/2003:10:28:43 +0100] 2 3 #marketing 10.160.50.13 -tec_IS2027 kurt 401 [22/Apr/2003:10:28:43 +0100] 3 3 #marketing 10.160.50.13 -tec_IS2027 kurt 401 [22/Apr/2003:10:28:43 +0100] 4 3 #marketing 10.160.50.13 -Dig9110 boss 402 [22/Apr/2003:10:33:22 +0100] 1 440 finance-dep 10.160.51.33 -</screen></para> - -<para> -This was job ID <parameter>401</parameter>, printed on <parameter>tec_IS2027</parameter> -by user <parameter>kurt</parameter>, a 64-page job printed in three copies and billed to -<parameter>#marketing</parameter>, sent from IP address <constant>10.160.50.13.</constant> - The next job had ID <parameter>402</parameter>, was sent by user <parameter>boss</parameter> -from IP address <constant>10.160.51.33</constant>, printed from one page 440 copies and -is set to be billed to <parameter>finance-dep</parameter>. -</para> -</sect2> - -<sect2> -<title>Possible Shortcomings</title> - -<para> -What flaws or shortcomings are there with this quota system? -</para> - -<itemizedlist> -<listitem><para>The ones named above (wrongly logged job in case of -printer hardware failure, and so on).</para></listitem> - -<listitem><para>In reality, CUPS counts the job pages that are being -processed in <emphasis>software</emphasis> (that is, going through the -RIP) rather than the physical sheets successfully leaving the -printing device. Thus if there is a jam while printing the fifth sheet out -of a thousand and the job is aborted by the printer, the page count will -still show the figure of a thousand for that job.</para></listitem> - -<listitem><para>All quotas are the same for all users (no flexibility -to give the boss a higher quota than the clerk) and no support for -groups.</para></listitem> - -<listitem><para>No means to read out the current balance or the -<quote>used-up</quote> number of current quota.</para></listitem> - -<listitem><para>A user having used up 99 sheets of a 100 quota will -still be able to send and print a thousand sheet job.</para></listitem> - -<listitem><para>A user being denied a job because of a filled-up quota -does not get a meaningful error message from CUPS other than -<quote>client-error-not-possible</quote>.</para></listitem> -</itemizedlist> -</sect2> - -<sect2> -<title>Future Developments</title> - -<para> -This is the best system currently available, and there are huge -improvements under development for CUPS 1.2: -</para> - -<itemizedlist> -<listitem><para>Page counting will go into the backends (these talk -directly to the printer and will increase the count in sync with the -actual printing process; thus, a jam at the fifth sheet will lead to a -stop in the counting).</para></listitem> - -<listitem><para>Quotas will be handled more flexibly.</para></listitem> - -<listitem><para>Probably there will be support for users to inquire -about their accounts in advance.</para></listitem> - -<listitem><para>Probably there will be support for some other tools -around this topic.</para></listitem> -</itemizedlist> -</sect2> - -<!-- FIXME -<sect2> -<title>Other Accounting Tools</title> - -<para> -PrintAnalyzer, pyKota, printbill, LogReport. -</para> -</sect2> ---> -</sect1> - -<sect1> -<title>Additional Material</title> - -<para> -A printer queue with <emphasis>no</emphasis> PPD associated to it is a -<quote>raw</quote> printer and all files will go directly there as received by the -spooler. The exceptions are file types <parameter>application/octet-stream</parameter> -that need passthrough feature enabled. <quote>Raw</quote> queues do not do any -filtering at all, they hand the file directly to the CUPS backend. -This backend is responsible for sending the data to the device -(as in the <quote>device URI</quote> notation: <filename>lpd://, socket://, -smb://, ipp://, http://, parallel:/, serial:/, usb:/</filename>, and so on). -</para> - -<para> -cupsomatic/Foomatic are <emphasis>not</emphasis> native CUPS drivers -and they do not ship with CUPS. They are a third party add-on -developed at Linuxprinting.org. As such, they are a brilliant hack to -make all models (driven by Ghostscript drivers/filters in traditional -spoolers) also work via CUPS, with the same (good or bad!) quality as -in these other spoolers. <parameter>cupsomatic</parameter> is only a vehicle to execute a -Ghostscript commandline at that stage in the CUPS filtering chain, -where normally the native CUPS <parameter>pstoraster</parameter> filter would kick -in. cupsomatic bypasses pstoraster, kidnaps the printfile from CUPS -away and redirects it to go through Ghostscript. CUPS accepts this, -because the associated cupsomatic/foomatic-PPD specifies: - -<filterline> - *cupsFilter: "application/vnd.cups-postscript 0 cupsomatic" -</filterline> - -This line persuades CUPS to hand the file to cupsomatic, once it has -successfully converted it to the MIME type -<parameter>application/vnd.cups-postscript</parameter>. This conversion will not happen for -Jobs arriving from Windows that are auto-typed -<parameter>application/octet-stream</parameter>, with the according changes in -<filename>/etc/cups/mime.types</filename> in place. -</para> - -<para> -CUPS is widely configurable and flexible, even regarding its filtering -mechanism. Another workaround in some situations would be to have in -<filename>/etc/cups/mime.types</filename> entries as follows: - -<filterline> - application/postscript application/vnd.cups-raw 0 - - application/vnd.cups-postscript application/vnd.cups-raw 0 - -</filterline> - -This would prevent all PostScript files from being filtered (rather, -they will through the virtual <emphasis>nullfilter</emphasis> -denoted with <quote>-</quote>). This could only be useful for PS printers. If you -want to print PS code on non-PS printers (provided they support ASCII -text printing), an entry as follows could be useful: - -<filterline> - */* application/vnd.cups-raw 0 - -</filterline> - -and would effectively send <emphasis>all</emphasis> files to the -backend without further processing. -</para> - -<para> -You could have the following entry: - -<filterline> -application/vnd.cups-postscript application/vnd.cups-raw 0 \ - my_PJL_stripping_filter -</filterline> - -You will need to write a <parameter>my_PJL_stripping_filter</parameter> -(which could be a shell script) that parses the PostScript and removes the -unwanted PJL. This needs to conform to CUPS filter design -(mainly, receive and pass the parameters printername, job-id, -username, jobtitle, copies, print options and possibly the -filename). It is installed as world executable into -<filename>/usr/lib/cups/filters/</filename> and is called by CUPS -if it encounters a MIME type <parameter>application/vnd.cups-postscript</parameter>. -</para> - -<para> -CUPS can handle <parameter>-o job-hold-until=indefinite</parameter>. -This keeps the job in the queue on hold. It will only be printed -upon manual release by the printer operator. This is a requirement in -many central reproduction departments, where a few operators manage -the jobs of hundreds of users on some big machine, where no user is -allowed to have direct access (such as when the operators often need -to load the proper paper type before running the 10,000 page job -requested by marketing for the mailing, and so on). -</para> -</sect1> - -<sect1> -<title>Auto-Deletion or Preservation of CUPS Spool Files</title> - -<para> -Samba print files pass through two spool directories. One is the -incoming directory managed by Samba, (set in the -<smbconfoption><name>path</name><value>/var/spool/samba</value></smbconfoption> -directive in the <smbconfsection>[printers]</smbconfsection> section of -&smb.conf;). The other is the spool directory of -your UNIX print subsystem. For CUPS it is normally -<filename>/var/spool/cups/</filename>, as set by the <filename>cupsd.conf</filename> -directive <filename>RequestRoot /var/spool/cups</filename>. -</para> - -<sect2> -<title>CUPS Configuration Settings Explained</title> - -<para> -Some important parameter settings in the CUPS configuration file -<filename>cupsd.conf</filename> are: -</para> - -<variablelist> - -<varlistentry><term>PreserveJobHistory Yes</term> -<listitem><para> -This keeps some details of jobs in cupsd's mind (well it keeps the -c12345, c12346, and so on, files in the CUPS spool directory, which do a -similar job as the old-fashioned BSD-LPD control files). This is set -to <quote>Yes</quote> as a default. -</para></listitem></varlistentry> - -<varlistentry><term>PreserveJobFiles Yes</term> -<listitem><para> -This keeps the job files themselves in cupsd's mind -(it keeps the d12345, d12346 etc. files in the CUPS spool -directory). This is set to <quote>No</quote> as the CUPS -default. -</para></listitem></varlistentry> - -<varlistentry><term><emphasis><quote>MaxJobs 500</quote></emphasis></term> -<listitem><para> -This directive controls the maximum number of jobs -that are kept in memory. Once the number of jobs reaches the limit, -the oldest completed job is automatically purged from the system to -make room for the new one. If all of the known jobs are still -pending or active, then the new job will be rejected. Setting the -maximum to 0 disables this functionality. The default setting is -0. -</para></listitem></varlistentry> -</variablelist> - -<para> -(There are also additional settings for <parameter>MaxJobsPerUser</parameter> and -<parameter>MaxJobsPerPrinter</parameter>...) -</para> -</sect2> - -<sect2> -<title>Pre-Conditions</title> - -<para> -For everything to work as announced, you need to have three -things: -</para> - -<itemizedlist> -<listitem><para>A Samba-smbd that is compiled against <filename>libcups</filename> (check -on Linux by running <userinput>ldd `which smbd'</userinput>).</para></listitem> - -<listitem><para>A Samba-&smb.conf; setting of - <smbconfoption><name>printing</name><value>cups</value></smbconfoption>.</para></listitem> - -<listitem><para>Another Samba-&smb.conf; setting of - <smbconfoption><name>printcap</name><value>cups</value></smbconfoption>.</para></listitem> -</itemizedlist> - -<note><para> -In this case, all other manually set printing-related commands (like -<smbconfoption><name>print command</name></smbconfoption>, -<smbconfoption><name>lpq command</name></smbconfoption>, -<smbconfoption><name>lprm command</name></smbconfoption>, -<smbconfoption><name>lppause command</name></smbconfoption> or -<smbconfoption><name>lpresume command</name></smbconfoption>) are ignored and they should normally have no -influence whatsoever on your printing. -</para></note> -</sect2> - -<sect2> -<title>Manual Configuration</title> - -<para> -If you want to do things manually, replace the <smbconfoption><name>printing</name><value>cups</value></smbconfoption> -by <smbconfoption><name>printing</name><value>bsd</value></smbconfoption>. Then your manually set commands may work -(I haven't tested this), and a <smbconfoption><name>print command</name><value>lp -d %P %s; rm %s"</value></smbconfoption> -may do what you need. -</para> -</sect2> -</sect1> - -<sect1> -<title>Printing from CUPS to Windows Attached Printers</title> - -<para> ->From time to time the question arises, how can you print -<emphasis>to</emphasis> a Windows attached printer -<emphasis>from</emphasis> Samba? Normally the local connection -from Windows host to printer would be done by USB or parallel -cable, but this does not matter to Samba. From here only an SMB -connection needs to be opened to the Windows host. Of course, this -printer must be shared first. As you have learned by now, CUPS uses -<emphasis>backends</emphasis> to talk to printers and other -servers. To talk to Windows shared printers, you need to use the -<filename>smb</filename> (surprise, surprise!) backend. Check if this -is in the CUPS backend directory. This usually resides in -<filename>/usr/lib/cups/backend/</filename>. You need to find an <filename>smb</filename> -file there. It should be a symlink to <filename>smbspool</filename> -and the file must exist and be executable: -</para> - -<para><screen> -&rootprompt;<userinput>ls -l /usr/lib/cups/backend/</userinput> -total 253 -drwxr-xr-x 3 root root 720 Apr 30 19:04 . -drwxr-xr-x 6 root root 125 Dec 19 17:13 .. --rwxr-xr-x 1 root root 10692 Feb 16 21:29 canon --rwxr-xr-x 1 root root 10692 Feb 16 21:29 epson -lrwxrwxrwx 1 root root 3 Apr 17 22:50 http -> ipp --rwxr-xr-x 1 root root 17316 Apr 17 22:50 ipp --rwxr-xr-x 1 root root 15420 Apr 20 17:01 lpd --rwxr-xr-x 1 root root 8656 Apr 20 17:01 parallel --rwxr-xr-x 1 root root 2162 Mar 31 23:15 pdfdistiller -lrwxrwxrwx 1 root root 25 Apr 30 19:04 ptal -> /usr/sbin/ptal-cups --rwxr-xr-x 1 root root 6284 Apr 20 17:01 scsi -lrwxrwxrwx 1 root root 17 Apr 2 03:11 smb -> /usr/bin/smbspool --rwxr-xr-x 1 root root 7912 Apr 20 17:01 socket --rwxr-xr-x 1 root root 9012 Apr 20 17:01 usb - -&rootprompt;<userinput>ls -l `which smbspool`</userinput> --rwxr-xr-x 1 root root 563245 Dec 28 14:49 /usr/bin/smbspool -</screen></para> - -<para> -If this symlink does not exist, create it: -</para> - -<para><screen> -&rootprompt;<userinput>ln -s `which smbspool` /usr/lib/cups/backend/smb</userinput> -</screen></para> - -<para> -<command>smbspool</command> has been written by Mike Sweet from the CUPS folks. It is -included and ships with Samba. It may also be used with print -subsystems other than CUPS, to spool jobs to Windows printer shares. To -set up printer <replaceable>winprinter</replaceable> on CUPS, you need to have a driver for -it. Essentially this means to convert the print data on the CUPS/Samba -host to a format that the printer can digest (the Windows host is -unable to convert any files you may send). This also means you should -be able to print to the printer if it were hooked directly at your -Samba/CUPS host. For troubleshooting purposes, this is what you -should do to determine if that part of the process chain is in -order. Then proceed to fix the network connection/authentication to -the Windows host, and so on. -</para> - -<para> -To install a printer with the <parameter>smb</parameter> backend on CUPS, use this command: -</para> - -<para><screen> -&rootprompt;<userinput>lpadmin -p winprinter -v smb://WINDOWSNETBIOSNAME/printersharename \ - -P /path/to/PPD</userinput> -</screen></para> - -<para> -The PPD must be able to direct CUPS to generate -the print data for the target model. For PostScript printers, just use -the PPD that would be used with the Windows NT PostScript driver. But -what can you do if the printer is only accessible with a password? Or -if the printer's host is part of another workgroup? This is provided -for: You can include the required parameters as part of the -<filename>smb://</filename> device-URI like this: -</para> - -<itemizedlist> - <listitem><filename>smb://WORKGROUP/WINDOWSNETBIOSNAME/printersharename</filename></listitem> - <listitem><filename>smb://username:password@WORKGROUP/WINDOWSNETBIOSNAME/printersharename</filename></listitem> - <listitem><filename>smb://username:password@WINDOWSNETBIOSNAME/printersharename</filename></listitem> -</itemizedlist> - -<para> -Note that the device-URI will be visible in the process list of the -Samba server (e.g., when someone uses the <command>ps -aux</command> -command on Linux), even if the username and passwords are sanitized -before they get written into the log files. So this is an inherently -insecure option, however, it is the only one. Don't use it if you want -to protect your passwords. Better share the printer in a way that -does not require a password! Printing will only work if you have a -working netbios name resolution up and running. Note that this is a -feature of CUPS and you do not necessarily need to have smbd running. - -</para> -</sect1> - -<sect1> -<title>More CUPS-Filtering Chains</title> - -<para> -The following diagrams reveal how CUPS handles print jobs. -</para> - -<image id="cups1"><imagefile>cups1</imagefile><imagedescription>Filtering chain 1.</imagedescription></image> - -<image id="cups2"><imagefile>cups2</imagefile><imagedescription>Filtering chain with cupsomatic</imagedescription></image> - -</sect1> - -<sect1> - <title>Common Errors</title> - - <sect2> - <title>Windows 9x/ME Client Can't Install Driver</title> - - <para>For Windows 9x/ME, clients require the printer names to be eight -characters (or <quote>8 plus 3 chars suffix</quote>) max; otherwise, the driver files -will not get transferred when you want to download them from -Samba.</para> - - </sect2> - - <sect2> - <title><quote>cupsaddsmb</quote> Keeps Asking for Root Password in Never-ending Loop</title> - - <para>Have you <smbconfoption><name>security</name><value>user</value></smbconfoption>? Have -you used <command>smbpasswd</command> to give root a Samba account? -You can do two things: open another terminal and execute -<command>smbpasswd -a root</command> to create the account and -continue entering the password into the first terminal. Or break -out of the loop by pressing ENTER twice (without trying to type a -password).</para> - - </sect2> - - <sect2> - <title><quote>cupsaddsmb</quote> Errors</title> - - <para> - The use of <quote>cupsaddsmb</quote> gives <quote>No PPD file for printer...</quote> Message While PPD File Is Present. - What might the problem be? - </para> - - <para>Have you enabled printer sharing on CUPS? This means: -Do you have a <parameter><Location -/printers>....</Location></parameter> section in CUPS -server's <filename>cupsd.conf</filename> that does not deny access to -the host you run <quote>cupsaddsmb</quote> from? It <emphasis>could</emphasis> be -an issue if you use cupsaddsmb remotely, or if you use it with a -<option>-h</option> parameter: <userinput>cupsaddsmb -H - sambaserver -h cupsserver -v printername</userinput>. -</para> -<para>Is your -<parameter>TempDir</parameter> directive in -<filename>cupsd.conf</filename> -set to a valid value and is it writeable? -</para> - - </sect2> - - <sect2> - <title>Client Can't Connect to Samba Printer</title> - <para>Use <command>smbstatus</command> to check which user -you are from Samba's point of view. Do you have the privileges to -write into the <smbconfsection>[print$]</smbconfsection> -share?</para> - - </sect2> - - <sect2> - <title>New Account Reconnection from Windows 200x/XP Troubles</title> - -<para>Once you are connected as the wrong user (for -example, as <constant>nobody</constant>, which often occurs if you have -<smbconfoption><name>map to guest</name><value>bad user</value></smbconfoption>), Windows Explorer will not accept an -attempt to connect again as a different user. There will not be any byte -transfered on the wire to Samba, but still you'll see a stupid error -message that makes you think Samba has denied access. Use -<command>smbstatus</command> to check for active connections. Kill the -PIDs. You still can't re-connect and you get the dreaded -<computeroutput>You can't connect with a second account from the same -machine</computeroutput> message, as soon as you are trying. And you -do not see any single byte arriving at Samba (see logs; use <quote>ethereal</quote>) -indicating a renewed connection attempt. Shut all Explorer Windows. -This makes Windows forget what it has cached in its memory as -established connections. Then reconnect as the right user. The best -method is to use a DOS terminal window and <emphasis>first</emphasis> -do <userinput>net use z: \\&example.server.samba;\print$ /user:root</userinput>. Check -with <command>smbstatus</command> that you are connected under a -different account. Now open the <guilabel>Printers</guilabel> folder (on the Samba server -in the <guilabel>Network Neighborhood</guilabel>), right-click on the -printer in question and select -<guibutton>Connect...</guibutton></para></sect2> - -<sect2> -<title>Avoid Being Connected to the Samba Server as the Wrong User</title> - -<para>You see per <command>smbstatus</command> that you are -connected as user nobody; while you want to be root or -printeradmin. This is probably due to -<smbconfoption><name>map to guest</name><value>bad user</value></smbconfoption>, which silently connects you under the guest account -when you gave (maybe by accident) an incorrect username. Remove -<smbconfoption><name>map to guest</name></smbconfoption>, if you want to prevent -this.</para></sect2> - -<sect2> -<title>Upgrading to CUPS Drivers from Adobe Drivers</title> - -<para> -This information came from a mailinglist posting regarding problems experienced when -upgrading from Adobe drivers to CUPS drivers on Microsoft Windows NT/200x/XP Clients. -</para> - -<para>First delete all old Adobe-using printers. Then -delete all old Adobe drivers. (On Windows 200x/XP, right-click in -the background of <guilabel>Printers</guilabel> folder, select <guimenuitem>Server Properties...</guimenuitem>, select -tab <guilabel>Drivers</guilabel> and delete here).</para></sect2> - -<sect2><title>Can't Use <quote>cupsaddsmb</quote> on Samba Server Which Is a PDC</title> -<para>Do you use the <quote>naked</quote> root user name? Try to do it -this way: <userinput>cupsaddsmb -U <replaceable>DOMAINNAME</replaceable>\\root -v -<replaceable>printername</replaceable></userinput>> (note the two backslashes: the first one is -required to <quote>escape</quote> the second one).</para></sect2> - -<sect2><title>Deleted Windows 200x Printer Driver Is Still Shown</title> -<para>Deleting a printer on the client will not delete the -driver too (to verify, right-click on the white background of the -<guilabel>Printers</guilabel> folder, select <guimenuitem>Server Properties</guimenuitem> and click on the -<guilabel>Drivers</guilabel> tab). These same old drivers will be re-used when you try to -install a printer with the same name. If you want to update to a new -driver, delete the old ones first. Deletion is only possible if no -other printer uses the same driver.</para></sect2> - -<sect2><title>Windows 200x/XP "Local Security Policies"</title> -<para>Local Security Policies may not -allow the installation of unsigned drivers. <quote>Local Security Policies</quote> -may not allow the installation of printer drivers at -all.</para></sect2> - -<sect2><title>Administrator Cannot Install Printers for All Local Users</title> -<para>Windows XP handles SMB printers on a <quote>per-user</quote> basis. -This means every user needs to install the printer himself. To have a -printer available for everybody, you might want to use the built-in -IPP client capabilities of WinXP. Add a printer with the print path of -<parameter>http://cupsserver:631/printers/printername</parameter>. -We're still looking into this one. Maybe a logon script could -automatically install printers for all -users.</para></sect2> - -<sect2><title>Print Change Notify Functions on NT-clients</title> -<para>For print change, notify functions on NT++ clients. -These need to run the <command>Server</command> service first (renamed to -<command>File & Print Sharing for MS Networks</command> in -XP).</para></sect2> - -<sect2> -<title>WinXP-SP1</title> - -<para>WinXP-SP1 introduced a Point and Print Restriction Policy (this restriction does not apply to -<quote>Administrator</quote> or <quote>Power User</quote> groups of users). In Group Policy -Object Editor, go to <guimenu>User Configuration -> Administrative Templates -> - Control Panel -> Printers</guimenu>. The policy is automatically set to -<constant>Enabled</constant> and the <constant>Users can only Point -and Print to machines in their Forest</constant> . You probably need -to change it to <constant>Disabled</constant> or <constant>Users can -only Point and Print to these servers</constant> to make -driver downloads from Samba possible. -</para> -</sect2> - -<sect2> -<title>Print Options for All Users Can't Be Set on Windows 200x/XP</title> - -<para>How are you doing it? I bet the wrong way (it is not -easy to find out, though). There are three different ways to bring -you to a dialog that <emphasis>seems</emphasis> to set everything. All -three dialogs <emphasis>look</emphasis> the same, yet only one of them -does what you intend. You need to be -Administrator or Print Administrator to do this for all users. Here -is how I do in on XP: -</para> - -<orderedlist numeration="upperalpha"> - -<listitem><para>The first wrong way: - -<orderedlist> -<listitem><para>Open the <guilabel>Printers</guilabel> -folder.</para></listitem> - -<listitem><para>Right-click on the printer -(<guilabel>remoteprinter on cupshost</guilabel>) and -select in context menu <guimenuitem>Printing -Preferences...</guimenuitem></para></listitem> - -<listitem><para>Look at this dialog closely and remember what it looks -like.</para></listitem> -</orderedlist> -</para> -</listitem> - -<listitem><para>The second wrong way: - -<orderedlist> -<listitem><para>Open the <guilabel>Printers</guilabel> -folder.</para></listitem> - -<listitem><para>Right-click on the printer (<guilabel>remoteprinter on -cupshost</guilabel>) and select the context menu -<guimenuitem>Properties</guimenuitem>.</para></listitem> - -<listitem><para>Click on the <guilabel>General</guilabel> -tab.</para></listitem> - -<listitem><para>Click on the button <guibutton>Printing -Preferences...</guibutton></para></listitem> - -<listitem><para>A new dialog opens. Keep this dialog open and go back -to the parent dialog.</para></listitem> -</orderedlist> -</para> -</listitem> - -<listitem><para>The third, and the correct way: - -<orderedlist> - -<listitem><para>Open the <guilabel>Printers</guilabel> -folder.</para></listitem> - -<listitem><para>Click on the <guilabel>Advanced</guilabel> -tab. (If everything is <quote>grayed out,</quote> then you are not logged -in as a user with enough privileges).</para></listitem> - -<listitem><para>Click on the <guibutton>Printing -Defaults...</guibutton> button.</para></listitem> - -<listitem><para>On any of the two new tabs, click on the -<guibutton>Advanced...</guibutton> -button.</para></listitem> - -<listitem><para>A new dialog opens. Compare this one to the other -identical looking one from <quote>B.5</quote> or A.3".</para></listitem> -</orderedlist> -</para> -</listitem> -</orderedlist> - -<para> -Do you see any difference? I don't either. However, only the last -one, which you arrived at with steps <quote>C.1.-6.</quote>, will save any settings -permanently and be the defaults for new users. If you want all clients -to get the same defaults, you need to conduct these steps <emphasis>as -Administrator</emphasis> (<smbconfoption><name>printer admin</name></smbconfoption> in -&smb.conf;) <emphasis>before</emphasis> a client -downloads the driver (the clients can later set their own -<emphasis>per-user defaults</emphasis> by following the -procedures <emphasis>A</emphasis> or <emphasis>B</emphasis> -above).</para></sect2> - -<sect2><title>Most Common Blunders in Driver Settings on Windows Clients</title> -<para>Don't use <parameter>Optimize for -Speed</parameter>, but use <parameter>Optimize for -Portability</parameter> instead (Adobe PS Driver). Don't use -<parameter>Page Independence: No</parameter>: always -settle with <parameter>Page Independence: -Yes</parameter> (Microsoft PS Driver and CUPS PS Driver for -Windows NT/200x/XP). If there are problems with fonts, use -<parameter>Download as Softfont into -printer</parameter> (Adobe PS Driver). For -<guilabel>TrueType Download Options</guilabel> -choose <constant>Outline</constant>. Use PostScript -Level 2, if you are having trouble with a non-PS printer and if -there is a choice.</para></sect2> - -<sect2><title><command>cupsaddsmb</command> Does Not Work with Newly Installed Printer</title> -<para>Symptom: The last command of -<command>cupsaddsmb</command> does not complete successfully: -<command>cmd = setdriver printername printername</command> result was -NT_STATUS_UNSUCCESSFUL then possibly the printer was not yet -recognized by Samba. Did it show up in Network -Neighborhood? Did it show up i n <command>rpcclient -hostname -c `enumprinters'</command>? Restart smbd (or send a -<command>kill -HUP</command> to all processes listed by -<command>smbstatus</command> and try -again.</para></sect2> - -<sect2> -<title>Permissions on <filename>/var/spool/samba/</filename> Get Reset After Each Reboot</title> -<para>Have you ever by accident set the CUPS spool directory to -the same location? (<parameter>RequestRoot /var/spool/samba/</parameter> in <filename>cupsd.conf</filename> or -the other way round: <filename>/var/spool/cups/</filename> is set as -<smbconfoption><name>path</name></smbconfoption>> in the <smbconfsection>[printers]</smbconfsection> -section). These <parameter>must</parameter> be different. Set -<!--FIXME--> -<parameter>RequestRoot /var/spool/cups/</parameter> in -<filename>cupsd.conf</filename> and <smbconfoption><name>path</name><value> -/var/spool/samba</value></smbconfoption> in the <smbconfsection>[printers]</smbconfsection> -section of &smb.conf;. Otherwise cupsd will -sanitize permissions to its spool directory with each restart and -printing will not work reliably.</para></sect2> - -<sect2> -<title>Print Queue Called <quote>lp</quote> Mis-handles Print Jobs</title> - -<para> -In this case a print queue called <quote>lp</quote> intermittently swallows jobs and -spits out completely different ones from what was sent. -</para> - -<para>It is a bad idea to name any printer <quote>lp</quote>. This -is the traditional UNIX name for the default printer. CUPS may be set -up to do an automatic creation of Implicit Classes. This means, to -group all printers with the same name to a pool of devices, and -load-balancing the jobs across them in a round-robin fashion. Chances -are high that someone else has a printer named <quote>lp</quote> too. You may -receive his jobs and send your own to his device unwittingly. To have -tight control over the printer names, set <parameter>BrowseShortNames -No</parameter>. It will present any printer as <replaceable>printername@cupshost</replaceable> -and then gives you better control over what may happen in a large -networked environment.</para></sect2> - -<sect2><title>Location of Adobe PostScript Driver Files for <quote>cupsaddsmb</quote></title> -<para>Use <command>smbclient</command> to connect to any -Windows box with a shared PostScript printer: <command>smbclient -//windowsbox/print\$ -U guest</command>. You can navigate to the -<filename>W32X86/2</filename> subdir to <command>mget ADOBE*</command> -and other files or to <filename>WIN40/0</filename> to do the same. -Another option is to download the <filename>*.exe</filename> packaged -files from the Adobe Web site.</para></sect2> - -</sect1> - -<sect1> -<title>Overview of the CUPS Printing Processes</title> - -<para>A complete overview of the CUPS printing processes can be found in <link linkend="a_small"/>.</para> - -<image id="a_small"><imagedescription>CUPS printing overview.</imagedescription> - <imagefile>a_small</imagefile> -</image> -</sect1> - -</chapter> - - - - - - - - - - - - |