Add some more common errors
[sfrench/samba-autobuild/.git] / docs / docbook / projdoc / printer_driver2.xml
1 <chapter id="printing">
2
3 <chapterinfo>
4         <author>
5                 <firstname>Kurt</firstname><surname>Pfeifle</surname>
6                 <affiliation>
7                         <orgname> Danka Deutschland GmbH </orgname>
8                         <address><email>kpfeifle@danka.de</email></address>
9                 </affiliation>
10         </author>
11         <pubdate>May 32, 2003</pubdate>
12 </chapterinfo>
13
14 <title>Classical Printing Support</title>
15
16 <sect1>
17 <title>Features and Benefits</title>
18
19 <para>
20 Printing is often a mission-critical service for the users.  Samba can
21 provide this service reliably and seamlessly for a client network
22 consisting of Windows workstations.
23 </para>
24
25 <para>
26 A Samba-3.0 print service may be run on a Standalone or a Domain
27 member server, side by side with file serving functions, or on a
28 dedicated print server. It can be made as tight or as loosely secured
29 as needs dictate. Configurations may be simple or complex.  Available
30 authentication schemes are essentially the same as described for file
31 services in previous chapters. Overall, Samba's printing support is
32 now able to replace an NT or Windows 2000 print server full-square,
33 with additional benefits in many cases. Clients may download and
34 install drivers and printers through their familiar "Point'n'Print"
35 mechanism. Printer installations executed by "Logon Scripts" are no
36 problem. Administrators can upload and manage drivers to be used by
37 clients through the familiar "Add Printer Wizard". As an additional
38 benefit, driver and printer management may be run from the commandline
39 or through scripts, making it more efficient in case of large numbers
40 of printers. If a central accounting of print jobs (tracking every
41 single page and supplying the raw data for all sorts of statistical
42 reports) is required, this is best supported by CUPS as the print
43 subsystem underneath the Samba hood.
44 </para>
45
46 <para>
47 This chapter deals with the foundations of Samba printing, as they
48 implemented by the more traditional UNIX (BSD- and System V-style)
49 printing systems. Many things apply to CUPS, the newer Common UNIX
50 Printing System, too; so if you use CUPS, you might be tempted to jump
51 to the next chapter -- but you will certainly miss a few things if you
52 do so. Better read this chapter too.
53 </para>
54
55 <note>
56 <para>
57 Most of the given examples have been verified on Windows XP
58 Professional clients. Where this document describes the responses to
59 commands given, bear in mind that Windows 2000 clients are very
60 similar, but may differ in details. Windows NT is somewhat different
61 again.
62 </para>
63 </note>
64
65 </sect1>
66
67 <sect1>
68 <title>Technical Introduction</title>
69
70 <para>
71 Samba's printing support always relies on the installed print
72 subsystem of the Unix OS it runs on. Samba is a "middleman". It takes
73 printfiles from Windows (or other SMB) clients and passes them to the
74 real printing system for further processing. Therefore it needs to
75 "talk" to two sides: to the Windows print clients and to the Unix
76 printing system. Hence we must differentiate between the various
77 client OS types each of which behave differently, as well as the
78 various UNIX print subsystems, which themselves have different
79 features and are accessed differently. This part of the Samba HOWTO
80 Collection deals with the "traditional" way of Unix printing first;
81 the next chapter covers in great detail the more modern
82 <emphasis>Common UNIX Printing System</emphasis>
83 (CUPS).
84
85 <important><para>CUPS users, be warned: don't just jump on to the next
86 chapter. You might miss important information contained only
87 here!</para></important>
88 </para>
89
90 <sect2>
91 <title>What happens if you send a Job from a Client</title>
92
93 <para>
94 To successfully print a job from a Windows client via a Samba
95 print server to a UNIX printer, there are 6 (potentially 7)
96 stages:
97 </para>
98
99 <orderedlist>
100 <listitem><para>Windows opens a connection to the printershare</para></listitem>
101
102 <listitem><para>Samba must authenticate the user</para></listitem>
103
104 <listitem><para>Windows sends a copy of the printfile over the network
105 into Samba's spooling area</para></listitem>
106
107 <listitem><para>Windows closes the connection again</para></listitem>
108
109 <listitem><para>Samba invokes the print command to hand the file over
110 to the UNIX print subsystem's spooling area</para></listitem>
111
112 <listitem><para>The Unix print subsystem processes the print
113 job</para></listitem>
114
115 <listitem><para>The printfile may need to be explicitely deleted
116 from the Samba spooling area.</para></listitem>
117
118 </orderedlist>
119 </sect2>
120
121 <sect2>
122 <title>Printing Related Configuration Parameters</title>
123
124 <para>
125 There are a number of configuration parameters in
126 <filename>smb.conf</filename> controlling Samba's printing
127 behaviour. Please also refer to the man page for smb.conf to
128 acquire an overview about these. As with other parameters, there are
129 Global Level (tagged with a "<emphasis>G</emphasis>" in the listings) and
130 Service Level ("<emphasis>S</emphasis>") parameters.
131 </para>
132
133 <variablelist>
134 <varlistentry><term>Service Level Parameters</term>
135 <listitem><para>These <emphasis>may</emphasis> go into the
136 <parameter>[global]</parameter> section of
137 <filename>smb.conf</filename>. In this case they define the default
138 behaviour of all individual or service level shares (provided those
139 don't have a different setting defined for the same parameter, thus
140 overriding the global default).</para></listitem>
141 </varlistentry>
142
143 <varlistentry><term>Global Parameters</term>
144 <listitem><para>These <emphasis>may not</emphasis> go into individual
145 shares.  If they go in by error, the "testparm" utility can discover
146 this (if you run it) and tell you so.</para></listitem>
147 </varlistentry>
148 </variablelist>
149 </sect2>
150
151 <sect2>
152 <title>Parameters Recommended for Use</title>
153
154 <para>The following <filename>smb.conf</filename> parameters directly
155 related to printing are used in Samba-3. See also the
156 <filename>smb.conf</filename> man page for detailed explanations:
157 </para>
158
159 <formalpara>
160 <title>LIST OF PRINTING RELATED PARAMETERS IN Samba-3</title>
161 <para>
162 <itemizedlist><title>Global level parameters:</title>
163 <listitem><para><parameter>addprinter command (G)</parameter></para></listitem>
164 <listitem><para><parameter>deleteprinter command (G)</parameter></para></listitem>
165 <listitem><para><parameter>disable spoolss (G)</parameter></para></listitem>
166 <listitem><para><parameter>enumports command (G)</parameter></para></listitem>
167 <listitem><para><parameter>load printers (G)</parameter></para></listitem>
168 <listitem><para><parameter>lpq cache time (G)</parameter></para></listitem>
169 <listitem><para><parameter>os2 driver map (G)</parameter></para></listitem>
170 <listitem><para><parameter>printcap name (G), printcap (G)</parameter></para></listitem>
171 <listitem><para><parameter>show add printer wizard (G)</parameter></para></listitem>
172 <listitem><para><parameter>total print jobs (G)</parameter></para></listitem>
173 <listitem><para><parameter>use client driver (G)</parameter></para></listitem>
174 </itemizedlist>
175
176 <itemizedlist><title>Service level parameters:</title>
177 <listitem><para><parameter>hosts allow (S)</parameter></para></listitem>
178 <listitem><para><parameter>hosts deny (S)</parameter></para></listitem>
179 <listitem><para><parameter>lppause command (S)</parameter></para></listitem>
180 <listitem><para><parameter>lpq command (S)</parameter></para></listitem>
181 <listitem><para><parameter>lpresume command (S)</parameter></para></listitem>
182 <listitem><para><parameter>lprm command (S)</parameter></para></listitem>
183 <listitem><para><parameter>max print jobs (S)</parameter></para></listitem>
184 <listitem><para><parameter>min print space (S)</parameter></para></listitem>
185 <listitem><para><parameter>print command (S)</parameter></para></listitem>
186 <listitem><para><parameter>printable (S), print ok (S)</parameter></para></listitem>
187 <listitem><para><parameter>printer name (S), printer (S)</parameter></para></listitem>
188 <listitem><para><parameter>printer admin (S)</parameter></para></listitem>
189 <listitem><para><parameter>printing = [cups|bsd|lprng...] (S)</parameter></para></listitem>
190 <listitem><para><parameter>queuepause command (S)</parameter></para></listitem>
191 <listitem><para><parameter>queueresume command (S)</parameter></para></listitem>
192 <listitem><para><parameter>total print jobs (S)</parameter></para></listitem>
193 </itemizedlist>
194 </para>
195 </formalpara>
196
197 <para>
198 Samba's printing support implements the Microsoft Remote Procedure
199 Calls (MS-RPC) methods for printing. These are used by Windows NT (and
200 later) print servers. The old "LanMan" protocol is still supported as
201 a fallback resort, and for older clients to use.  More details will
202 follow further beneath.
203 </para>
204 </sect2>
205
206 <sect2>
207 <title>Parameters for Backwards Compatibility</title>
208
209 <para>
210 Two new parameters that were added in Samba 2.2.2, are still present
211 in Samba-3.0. Both of these options are described in the
212 <filename>smb.conf</filename>(5) man page and are disabled by
213 default. <emphasis>Use them with caution!</emphasis>
214 </para>
215
216 <variablelist>
217 <varlistentry><term><parameter>disable spoolss(G)</parameter></term>
218 <listitem><para> This is
219 provided for better support of Samba 2.0.x backwards capability. It
220 will disable Samba's support for MS-RPC printing and yield identical
221 printing behaviour to Samba 2.0.x.</para></listitem>
222 </varlistentry>
223
224 <varlistentry><term><parameter>use client driver (G)</parameter></term>
225 <listitem><para> was provided
226 for using local printer drivers on Windows NT/2000 clients. It does
227 not apply to Windows 95/98/ME clients.</para></listitem>
228 </varlistentry>
229 </variablelist>
230
231 <formalpara>
232 <title>PARAMETERS "FOR BACKWARD COMPATIBILITY ONLY", USE WITH CAUTION</title>
233
234 <para>
235 <itemizedlist>
236 <listitem><para><parameter>disable spoolss (G)</parameter></para></listitem>
237
238 <listitem><para><parameter>use client driver (S)</parameter></para></listitem>
239 </itemizedlist>
240 </para>
241 </formalpara>
242
243 </sect2>
244
245 <sect2>
246 <title>Parameters no longer in Use</title>
247
248 <para>
249 Samba users upgrading from 2.2.x to 3.0 need to be aware that some
250 previously available settings are no longer supported (as was
251 announced some time ago). Here is a list of them:
252 </para>
253
254 <formalpara>
255 <title>"OLD" PARAMETERS, REMOVED IN Samba-3</title>
256
257 <para>
258 The following <filename>smb.conf</filename> parameters have been
259 deprecated already in Samba 2.2 and are now completely removed from
260 Samba-3.  You cannot use them in new 3.0 installations:
261
262 <itemizedlist>
263 <listitem><para><parameter>printer driver file (G)</parameter></para></listitem>
264 <listitem><para><parameter>total print jobs (G)</parameter></para></listitem>
265 <listitem><para><parameter>postscript (S)</parameter></para></listitem>
266 <listitem><para><parameter>printer driver (S)</parameter></para></listitem>
267 <listitem><para><parameter>printer driver location (S)</parameter></para></listitem>
268 </itemizedlist>
269 </para>
270
271 </formalpara>
272
273 </sect2>
274 </sect1>
275
276 <sect1>
277 <title>A simple Configuration to Print with Samba-3</title>
278
279 <para>
280 Here is a very simple example configuration for print related settings
281 in the <filename>smb.conf</filename> file. If you compare it with your
282 own system's <filename>smb.conf</filename>, you probably find some
283 additional parameters included there (as pre-configured by your OS
284 vendor). Further below is a discussion and explanation of the
285 parameters. Note, that this example doesn't use many parameters.
286 However, in many environments these are enough to provide a valid
287 <filename>smb.conf</filename> which enables all clients to print.
288 </para>
289
290 <para><screen>
291  [global]
292          printing = bsd
293          load printers = yes
294
295  [printers]
296          path = /var/spool/samba
297          printable = yes
298          public = yes
299          writable = no
300 </screen></para>
301
302 <para>
303 This is only an example configuration. Many settings, if not
304 explicitly set to a specific value, are used and set by Samba
305 implicitly to its own default, because these have been compiled in.
306 To see all settings, let root use the <command>testparm</command>
307 utility. <command>testparm</command> also gives warnings if you have
308 mis-configured certain things. Its complete output is easily 340 lines
309 and more. You may want to pipe it through a pager program.
310 </para>
311
312 <para>
313 The syntax for the configuration file is easy to grasp. You should
314 know that <filename>smb.conf</filename> is not very picky about its
315 syntax. It has been explained elsewhere in this document. A short
316 reminder: It even tolerates some spelling errors (like "browsable"
317 instead of "browseable"). Most spelling is case-insensitive. Also, you
318 can use "Yes|No" or "True|False" for boolean settings. Lists of names
319 may be separated by commas, spaces or tabs.
320 </para>
321
322 <sect2>
323 <title>Verification of "Settings in Use" with <command>testparm</command></title>
324
325 <para>
326 To see all (or at least most) printing related settings in Samba,
327 including the implicitly used ones, try the command outlined below
328 (hit "ENTER" twice!). It greps for all occurrences of "lp", "print",
329 "spool", "driver", "ports" and "[" in testparm's output and gives you
330 a nice overview about the running smbd's print configuration. (Note
331 that this command does not show individually created printer shares,
332 or the spooling paths in each case). Here is the output of my Samba
333 setup, with exactly the same settings in <filename>smb.conf</filename>
334 as shown above:
335 </para>
336
337 <para><screen>
338  transmeta: # testparm -v | egrep "(lp|print|spool|driver|ports|\[)"
339  
340  Load smb config files from /etc/samba/smb.conf.simpleprinting
341  Processing section "[homes]"
342  Processing section "[printers]"
343  
344  [global]
345         smb ports = 445 139
346         lpq cache time = 10
347         total print jobs = 0
348         load printers = Yes
349         printcap name = /etc/printcap
350         disable spoolss = No
351         enumports command =
352         addprinter command = 
353         deleteprinter command = 
354         show add printer wizard = Yes
355         os2 driver map =
356         printer admin =
357         min print space = 0
358         max print jobs = 1000
359         printable = No
360         printing = bsd
361         print command = lpr -r -P'%p' %s
362         lpq command = lpq -P'%p'
363         lprm command = lprm -P'%p' %j
364         lppause command =
365         lpresume command =
366         printer name =
367         use client driver = No
368
369  [homes]
370
371  [printers]
372         path = /var/spool/samba
373         printable = Yes
374
375 </screen></para>
376
377 <para>
378 You can easily verify which settings were implicitly added by Samba's
379 default behaviour. <emphasis>Don't forget about this point: it may
380 be important in your future dealings with Samba.</emphasis>
381 </para>
382
383 <note><para> testparm in Samba-3.0 behaves differently from 2.2.x: used
384 without the "-v" switch it only shows you the settings actually
385 written into <filename>smb.conf</filename>! To see the complete
386 configuration used, add the "-v" parameter to testparm.</para></note>
387
388 </sect2>
389
390 <sect2>
391 <title>A little Experiment to warn you</title>
392
393 <para>
394 Should you need to troubleshoot at any stage, please always come back
395 to this point first and verify if "testparm" shows the parameters you
396 expect! To give you an example from personal experience as a warning,
397 try to just "comment out" the <parameter>load printers</parameter>"
398 parameter. If your 2.2.x system behaves like mine, you'll see this:
399 </para>
400
401 <para><screen>
402
403  kde-bitshop:/etc/samba # grep "load printers" smb.conf
404  #      load printers = Yes
405         # This setting is commented ooouuuuut!!
406
407  kde-bitshop:/etc/samba # testparm -v smb.conf | egrep "(load printers)"
408         load printers = Yes
409
410 </screen></para>
411
412 <para>
413 Despite my imagination that the commenting out of this setting should
414 prevent Samba from publishing my printers, it still did! Oh Boy -- it
415 cost me quite some time to find out the reason. But I am not fooled
416 any more... at least not by this ;-)
417 </para>
418
419 <para><screen>
420
421  kde-bitshop:/etc/samba # grep -A1 "load printers" smb.conf
422         load printers = No
423         # This setting is what I mean!!
424  #      load printers = Yes
425         # This setting is commented ooouuuuut!!
426
427  kde-bitshop:/etc/samba # testparm -v smb.conf.simpleprinting | egrep "(load printers)"
428         load printers = No
429
430 </screen></para>
431
432 <para>
433 Only when setting the parameter explicitly to
434 "<parameter>load printers = No</parameter>"
435 would Samba recognize my intentions. So my strong advice is:
436 </para>
437
438 <itemizedlist>
439 <listitem><para>Never rely on "commented out" parameters!</para></listitem>
440
441 <listitem><para>Always set it up explicitly as you intend it to
442 behave.</para></listitem>
443
444 <listitem><para>Use <command>testparm</command> to uncover hidden
445 settings which might not reflect your intentions.</para></listitem>
446
447 </itemizedlist>
448
449 <para>
450 You can have a working Samba print configuration with this
451 minimal <filename>smb.conf</filename>:
452 </para>
453
454 <para><screen>
455
456  kde-bitshop:/etc/samba # cat /etc/samba/smb.conf-minimal
457         [printers]
458
459 </screen></para>
460
461 <para>
462 This example should show you that you can use testparm to test any
463 filename for fitness as a Samba configuration. Actually, we want to
464 encourage you <emphasis>not</emphasis> to change your
465 <filename>smb.conf</filename> on a working system (unless you know
466 exactly what you are doing)! Don't rely on an assumption that changes
467 will only take effect after you re-start smbd!  This is not the
468 case. Samba re-reads its <filename>smb.conf</filename> every 60
469 seconds and on each new client connection. You might have to face
470 changes for your production clients that you didn't intend to apply at
471 this time! You will now note a few more interesting things. Let's now
472 ask <command>testparm</command> what the Samba print configuration
473 would be, if you used this minimalistic file as your real
474 <filename>smb.conf</filename>:
475 </para>
476
477 <para><screen>
478
479  kde-bitshop:~ # testparm -v /etc/samba/smb.conf-minimal | egrep "(print|lpq|spool|driver|ports|[)"
480  Processing section "[printers]"
481  WARNING: [printers] service MUST be printable!
482  No path in service printers - using /tmp
483
484         lpq cache time = 10
485         total print jobs = 0
486         load printers = Yes
487         printcap name = /etc/printcap
488         disable spoolss = No
489         enumports command =
490         addprinter command =
491         deleteprinter command =
492         show add printer wizard = Yes
493         os2 driver map =
494         printer admin =
495         min print space = 0
496         max print jobs = 1000
497         printable = No
498         printing = bsd
499         print command = lpr -r -P%p %s
500         lpq command = lpq -P%p
501         printer name =
502         use client driver = No
503  [printers]
504         printable = Yes
505
506 </screen></para>
507
508 <para>
509 testparm issued 2 warnings:
510 </para>
511
512 <itemizedlist>
513 <listitem><para>because we didn't specify the
514 <parameter>[printers]</parameter> section as printable,
515 and</para></listitem>
516
517 <listitem><para>because we didn't tell it which spool directory to
518 use.</para></listitem>
519
520 </itemizedlist>
521
522 <para>
523 However, this was not fatal, and Samba-3.0 will default to values that
524 will work here. But, please!, don't rely on this and don't use this
525 example! This was only meant to make you careful to design and specify
526 your setup to be what you really want it to be. The outcome on your
527 system may vary for some parameters, since you may have a Samba built
528 with a different compile-time configuration.
529 <emphasis>Warning:</emphasis> don't put a comment sign <emphasis>at
530 the end</emphasis> of a valid <filename>smb.conf</filename> line. It
531 will cause the parameter to be ignored (just as if you had put the
532 comment sign at the front). At first I regarded this as a bug in my
533 Samba version(s). But the man page states: <quote>Internal whitespace
534 in a parameter value is retained verbatim.</quote> This means that a
535 line consisting of, for example,
536 </para>
537
538 <para><screen>
539 printing =lprng     #This defines LPRng as the printing system"
540 </screen></para>
541
542 <para>
543 will regard the whole of the string after the "="
544 sign as the value you want to define. And this is an invalid value
545 that will be ignored, and a default value used instead.]
546 </para>
547 </sect2>
548 </sect1>
549
550 <sect1>
551 <title>Extended Sample Configuration to Print with Samba-3</title>
552
553 <para>
554 Here we show a more verbose example configuration for print related
555 settings in an <filename>smb.conf</filename>. Below is a discussion
556 and explanation of the various parameters. We chose to use BSD-style
557 printing here, because we guess it is still the most commonly used
558 system on legacy Linux installations (new installs now predominantly
559 have CUPS, which is discussed entirely in the next chapter of this
560 document). Note, that this example explicitly names many parameters
561 which don't need to be stated because they are set by default. You
562 might be able to do with a leaner <filename>smb.conf</filename>.</para>
563
564 <tip><para>
565 if you read access it with the Samba Web Administration Tool (SWAT),
566 and then write it to disk again, it will be optimized in a way such
567 that it doesn't contain any superfluous parameters and comments. SWAT
568 organizes the file for best performance. Remember that each smbd
569 re-reads the Samba configuration once a minute, and that each
570 connection spawns an smbd process of its own, so it is not a bad idea
571 to optimize the <filename>smb.conf</filename> in environments with
572 hundreds or thousands of clients.</para></tip>
573
574 <para><screen>
575  [global]
576          printing = bsd
577          load printers = yes
578          show add printer wizard = yes
579          printcap name = /etc/printcap
580          printer admin = @ntadmin, root
581          total print jobs = 100
582          lpq cache time = 20
583          use client driver = no
584
585  [printers]
586          comment = All Printers
587          printable = yes
588          path = /var/spool/samba
589          browseable = no
590          guest ok = yes
591          public = yes
592          read only = yes
593          writable = no       
594
595  [my_printer_name]
596          comment = Printer with Restricted Access
597          path = /var/spool/samba_my_printer
598          printer admin = kurt
599          browseable = yes
600          printable = yes
601          writeable = no
602          hosts allow = 0.0.0.0
603          hosts deny = turbo_xp, 10.160.50.23, 10.160.51.60
604          guest ok = no
605 </screen></para>
606
607 <para>
608 This <emphasis>also</emphasis> is only an example configuration. You
609 may not find all the settings in your own
610 <filename>smb.conf</filename> (as pre-configured by your OS
611 vendor). Many configuration parameters, if not explicitly set to a
612 specific value, are used and set by Samba implicitly to its own
613 default, because these have been compiled in. To see all settings, let
614 root use the <command>testparm</command>
615 utility. <command>testparm</command> also gives warnings if you have
616 mis-configured certain things..
617 </para>
618 </sect1>
619
620 <sect1>
621 <title>Detailed Explanation of the Example's Settings</title>
622
623 <para>
624 Following is a discussion of the settings from above shown example.
625 </para>
626
627 <sect2>
628 <title>The [global] Section</title>
629
630 <para>
631 The <parameter>[global]</parameter> section is one of 4 special
632 sections (along with [<parameter>[homes]</parameter>,
633 <parameter>[printers]</parameter> and
634 <parameter>[print$]</parameter>...) It contains all parameters which
635 apply to the server as a whole. It is the place for parameters which
636 have only a "global" meaning (G). It may also contain service level
637 parameters (S) which then define default settings for all other
638 sections and shares. This way you can simplify the configuration and
639 avoid setting the same value repeatedly. (Within each individual
640 section or share you may however override these globally set "share
641 level" settings and specify other values).
642 </para>
643
644 <variablelist>
645 <varlistentry><term><parameter>printing = bsd</parameter></term>
646 <listitem><para> this causes Samba to use default print commands
647 applicable for the BSD (a.k.a. RFC 1179 style or LPR/LPD) printing
648 system. In general, the "printing" parameter informs Samba about the
649 print subsystem it should expect. Samba supports CUPS, LPD, LPRNG,
650 SYSV, HPUX, AIX, QNX and PLP. Each of these systems defaults to a
651 different "print command" (and other queue control
652 commands). <emphasis>Caution:</emphasis> The "printing" parameter is
653 normally a service level parameter. Since it is included here in the
654 <parameter>[global]</parameter> section, it will take effect for all
655 printer shares that are not defined differently. Samba-3.0 no longer
656 supports the SOFTQ printing system.</para></listitem></varlistentry>
657
658 <varlistentry><term><parameter>load printers = yes</parameter></term>
659 <listitem><para> this tells Samba to create automatically all
660 available printer shares. "Available" printer shares are discovered by
661 scanning the printcap file. All created printer shares are also loaded
662 for browsing. If you use this parameter, you do not need to specify
663 separate shares for each printer. Each automatically created printer
664 share will clone the configuration options found in the
665 <parameter>[printers]</parameter> section. (A <parameter>load printers
666 = no</parameter> setting will allow you to specify each UNIX printer
667 you want to share separately, leaving out some you don't want to be
668 publicly visible and available).  </para></listitem></varlistentry>
669
670 <varlistentry><term><parameter>show add printer wizard =
671 yes</parameter></term> <listitem><para> this setting is normally
672 enabled by default (even if the parameter is not written into the
673 <filename>smb.conf</filename>). It makes the "Add Printer Wizard" icon
674 show up in the "Printers" folder of the Samba host's share listing (as
675 shown in "Network Neighbourhood" or by the "net view" command). To
676 disable it, you need to explicitly set it to "no" (commenting it out
677 will not suffice!). The Add Printer Wizard lets you upload printer
678 drivers to the <parameter>[print$]</parameter> share and associate it
679 with a printer (if the respective queue exists there before the
680 action), or exchange a printer's driver against any other previously
681 uploaded driver.  </para></listitem></varlistentry>
682
683 <varlistentry><term><parameter>total print jobs = 100</parameter></term>
684 <listitem><para> this setting sets the upper limit to 100 print jobs
685 being active on the Samba server at any one time. Should a client
686 submit a job which exceeds this number, a <quote>no more space
687 available on server</quote> type of error message will be returned by
688 Samba to the client. A setting of "0" (the default) means there is
689 <emphasis>no</emphasis> limit at all!
690 </para></listitem></varlistentry>
691
692 <varlistentry><term><parameter>printcap name = /etc/printcap</parameter></term>
693
694 <listitem><para> this tells Samba where to look for a list of
695 available printer names. (If you use CUPS, make sure that a printcap
696 file is written: this is controlled by the "Printcap" directive of
697 <filename>cupsd.conf</filename>).
698 </para></listitem></varlistentry>
699
700 <varlistentry><term><parameter>printer admin = @ntadmin</parameter></term>
701 <listitem><para> members of the ntadmin group should be able to add
702 drivers and set printer properties ("ntadmin" is only an example name,
703 it needs to be a valid UNIX group name); root is implicitly always a
704 'printer admin'. The "@" sign precedes group names in
705 <filename>smb.conf</filename>. A printer admin can do anything to
706 printers via the remote administration interfaces offered by MS-RPC
707 (see below).  Note that the <parameter>printer admin</parameter>
708 parameter is normally a share level parameter, so you may associate
709 different groups to different printer shares in larger installations,
710 if you use the <parameter>printer admin</parameter> parameter on the
711 share levels).
712 </para></listitem></varlistentry>
713
714 <varlistentry><term><parameter>lpq cache time = 20</parameter></term>
715 <listitem><para> this controls the cache time for the results of the
716 lpq command. It prevents the lpq command being called too often and
717 reduces load on a heavily used print server.
718 </para></listitem></varlistentry>
719
720 <varlistentry><term><parameter>use client driver = no</parameter></term>
721 <listitem><para> if set to "yes", this setting only takes effect for
722 Win NT/2k/XP clients (and not for Win 95/98/ME). Its default value is
723 "No" (or "False"). It must <emphasis>not</emphasis> be enabled on
724 print shares (with a "yes" or "true" setting) which have valid drivers
725 installed on the Samba server! For more detailed explanations see the
726 man page of <filename>smb.conf</filename>.
727 </para></listitem></varlistentry>
728 </variablelist>
729
730 </sect2>
731
732 <sect2>
733 <title>The [printers] Section</title>
734
735 <para>
736 This is the second special section. If a section with this name
737 appears in the <filename>smb.conf</filename>, users are able to
738 connect to any printer specified in the Samba host's printcap file,
739 because Samba on startup then creates a printer share for every
740 printername it finds in the printcap file. You could regard this
741 section as a general convenience shortcut to share all printers with
742 minimal configuration. It is also a container for settings which
743 should apply as default to all printers. (For more details see the
744 <filename>smb.conf</filename> man page.) Settings inside this
745 container must be share level parameters (S).
746 </para>
747
748 <variablelist>
749 <varlistentry><term><parameter>comment = All printers</parameter></term>
750 <listitem><para> the <parameter>comment</parameter> is shown next to
751 the share if a client queries the server, either via "Network
752 Neighbourhood" or with the <command>net view</command> command to list
753 available shares.
754 </para></listitem></varlistentry>
755
756 <varlistentry><term><parameter>printable = yes</parameter></term>
757 <listitem><para> please note well, that the
758 <parameter>[printers]</parameter> service <emphasis>must</emphasis> be
759 declared as printable. If you specify otherwise, smbd will refuse to
760 load <filename>smb.conf</filename> at startup. This parameter allows
761 connected clients to open, write to and submit spool files into the
762 directory specified with the <parameter>path</parameter> parameter for
763 this service. It is used by Samba to differentiate printer shares from
764 file shares.  </para></listitem></varlistentry>
765
766 <varlistentry><term><parameter>path = /var/spool/samba</parameter></term>
767 <listitem><para>this must point to a directory used by Samba to spool
768 incoming print files. <emphasis>It must not be the same as the spool
769 directory specified in the configuration of your UNIX print
770 subsystem!</emphasis> The path would typically point to a directory
771 which is world writeable, with the "sticky" bit set to it.
772 </para></listitem></varlistentry>
773
774 <varlistentry><term><parameter>browseable = no</parameter></term>
775 <listitem><para> this is always set to "no" if <parameter>printable =
776 yes</parameter>. It makes the [printer] share itself invisible in the
777 list of available shares in a <command>net view</command> command or
778 in the Explorer browse list. (Note that you will of course see the
779 individual printers).
780 </para></listitem></varlistentry>
781
782 <varlistentry><term><parameter>guest ok = yes</parameter></term>
783
784 <listitem><para>
785 if set to "yes", then no password is required to
786 connect to the printers service. Access will be granted with the
787 privileges of the "guest account". On many systems the guest
788 account will map to a user named "nobody". This user is in the UNIX
789 passwd file with an empty password, but with no valid UNIX login.
790 (Note: on some systems the guest account might not have the
791 privilege to be able to print. Test this by logging in as your
792 guest user using "su - guest" and run a system print command like
793 </para>
794
795 <para><screen>
796 lpr -P printername /etc/motd
797 </screen></para>
798
799 </listitem></varlistentry>
800
801 <varlistentry><term><parameter>public = yes</parameter></term>
802 <listitem><para> this is a synonym for <parameter>guest ok =
803 yes</parameter>. Since we have <parameter>guest ok = yes</parameter>,
804 it really doesn't need to be here! (This leads to the interesting
805 question: <quote>What, if I by accident have to contradictory settings
806 for the same share?</quote> The answer is: the last one encountered by
807 Sambe wins. The "winner" is shown by testparm. Testparm doesn't
808 complain about different settings of the same parameter for the same
809 share! You can test this by setting up multiple lines for the "guest
810 account" parameter with different usernames, and then run testparm to
811 see which one is actually used by Samba.)
812 </para></listitem></varlistentry>
813
814 <varlistentry><term><parameter>read only = yes</parameter></term>
815 <listitem><para>this normally (for other types of shares) prevents
816 users creating or modifying files in the service's directory. However,
817 in a "printable" service, it is <emphasis>always</emphasis> allowed to
818 write to the directory (if user privileges allow the connection), but
819 only via print spooling operations. "Normal" write operations are not
820 allowed.  </para></listitem></varlistentry>
821
822 <varlistentry><term><parameter>writeable = no</parameter></term>
823 <listitem><para>
824 synonym for <parameter>read only = yes</parameter>
825 </para></listitem></varlistentry>
826 </variablelist>
827 </sect2>
828
829 <sect2>
830 <title>Any [my_printer_name] Section</title>
831
832 <para>
833 If a section appears in the <filename>smb.conf</filename>, which is
834 tagged as <parameter>printable = yes</parameter>, Samba presents it as
835 a printer share to its clients. Note, that Win95/98/ME clients may
836 have problems with connecting or loading printer drivers if the share
837 name has more than 8 characters! Also be very careful if you give a
838 printer the same name as an existing user or file share name: upon a
839 client's connection request to a certain sharename, Samba always tries
840 to find file shares with that name first; if it finds one, it will
841 connect to this and will never ultimately connect to a printer with
842 the same name!
843 </para>
844
845 <variablelist>
846 <varlistentry><term><parameter>comment = Printer with Restricted Access</parameter></term>
847 <listitem><para> the comment says it all.
848 </para></listitem></varlistentry>
849
850 <varlistentry><term><parameter>path = /var/spool/samba_my_printer</parameter></term>
851 <listitem><para> here we set the spooling area for this printer to
852 another directory than the default. It is not a requirement to set it
853 differently, but the option is available.
854 </para></listitem></varlistentry>
855
856 <varlistentry><term><parameter>printer admin = kurt</parameter></term>
857 <listitem><para> the printer admin definition is different for this
858 explicitly defined printer share from the general
859 <parameter>[printers]</parameter> share. It is not a requirement; we
860 did it to show that it is possible if you want it.
861 </para></listitem></varlistentry>
862
863 <varlistentry><term><parameter>browseable = yes</parameter></term>
864 <listitem><para> we also made this printer browseable (so that the
865 clients may conveniently find it when browsing the Network
866 Neighbourhood).
867 </para></listitem></varlistentry>
868
869 <varlistentry><term><parameter>printable = yes</parameter></term>
870 <listitem><para>see explanation in last subsection.
871 </para></listitem></varlistentry>
872
873 <varlistentry><term><parameter>writeable = no</parameter></term>
874 <listitem><para>see explanation in last subsection.
875 </para></listitem></varlistentry>
876
877 <varlistentry><term><parameter>hosts allow = 10.160.50.,10.160.51.</parameter></term>
878 <listitem><para>here we exercise a certain degree of access control
879 by using the "hosts allow" and "hosts deny" parameters. Note, that
880 this is not by any means a safe bet. It is not a way to secure your
881 printers. This line accepts all clients from a certain subnet in a
882 first evaluation of access control
883 </para></listitem></varlistentry>
884
885 <varlistentry><term><parameter>hosts deny = turbo_xp,10.160.50.23,10.160.51.60
886 </parameter></term>
887 <listitem><para>all listed hosts are not allowed here (even if they
888 belong to the "allowed subnets"). As you can see, you could name IP
889 addresses as well as NetBIOS hostnames
890 here.
891 </para></listitem></varlistentry>
892
893 <varlistentry><term><parameter>guest ok = no</parameter></term>
894 <listitem><para>this printer is not open for the guest account!
895 </para></listitem></varlistentry>
896
897 </variablelist>
898 </sect2>
899
900 <sect2>
901 <title>Print Commands</title>
902
903 <para>
904 In each section defining a printer (or in the
905 <parameter>[printers]</parameter> section), a <parameter>print
906 command</parameter> parameter may be defined. It sets a command to
907 process the files which have been placed into the Samba print spool
908 directory for that printer. (That spool directory was, if you
909 remember, set up with the <parameter>path</parameter>
910 parameter). Typically, this command will submit the spool file to the
911 Samba host's print subsystem, using the suitable system print
912 command. But there is no requirement that this needs to be the
913 case. For debugging purposes or some other reason you may want to do
914 something completely different than "print" the file. An example is a
915 command that just copies the print file to a temporary location for
916 further investigation when you need to debug printing. If you craft
917 your own print commands (or even develop print command shell scripts),
918 make sure you pay attention to the need to remove the files from the
919 Samba spool directory. Otherwise your hard disk may soon suffer from
920 shortage of free space.
921 </para>
922 </sect2>
923
924 <sect2>
925 <title>Default Print Commands for various Unix Print Subsystems</title>
926
927 <para>
928 You learned earlier on, that Samba in most cases uses its built-in
929 settings for many parameters if it can not find an explicitly stated
930 one in its configuration file. The same is true for the
931 <parameter>print command</parameter>. The default print command varies
932 depending on the <parameter>printing =...</parameter> parameter
933 setting. In the commands listed below, you will notice some parameters
934 of the form <emphasis>%X</emphasis> where <emphasis>X</emphasis> is
935 <emphasis>p, s, J</emphasis> etc. These letters stand for
936 "printername", "spoolfile" and "job ID" respectively.  They are
937 explained in more detail further below. Here is an overview (excluding
938 the special case of CUPS, which is discussed in the next chapter):
939 </para>
940
941 <informaltable frame='all'>
942 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
943 <thead>
944 <row>
945 <entry>If this setting is active...</entry>
946 <entry>...this is used in lieu of an explicit command:</entry>
947 </row>
948 </thead>
949 <tbody>
950 <row>
951 <entry><parameter>printing = bsd|aix|lprng|plp</parameter></entry>
952 <entry>print command is <command>lpr -r -P%p %s</command></entry>
953 </row>
954 <row>
955 <entry><parameter>printing = sysv|hpux</parameter></entry>
956 <entry>print command is <command>lp -c -P%p %s; rm %s</command></entry>
957 </row>
958 <row>
959 <entry> <parameter>printing = qnx</parameter></entry>
960 <entry>print command is <command>lp -r -P%p -s %s</command></entry>
961 </row>
962 <row>
963 <entry><parameter>printing = bsd|aix|lprng|plp</parameter></entry>
964 <entry>lpq command is <command>lpq -P%p</command></entry>
965 </row>
966 <row>
967 <entry><parameter>printing = sysv|hpux</parameter></entry>
968 <entry>lpq command is <command>lpstat -o%p</command></entry>
969 </row>
970 <row>
971 <entry><parameter>printing = qnx</parameter></entry>
972 <entry>lpq command is <command>lpq -P%p</command></entry>
973 </row>
974 <row>
975 <entry><parameter>printing = bsd|aix|lprng|plp</parameter></entry>
976 <entry>lprm command is <command>lprm -P%p %j</command></entry>
977 </row>
978 <row>
979 <entry><parameter>printing = sysv|hpux</parameter></entry>
980 <entry>lprm command is <command>cancel %p-%j</command></entry>
981 </row>
982 <row>
983 <entry><parameter>printing = qnx</parameter></entry>
984 <entry>lprm command is <command>cancel %p-%j</command></entry>
985 </row>
986 <row>
987 <entry><parameter>printing = bsd|aix|lprng|plp</parameter></entry>
988 <entry>lppause command is <command>lp -i %p-%j -H hold</command></entry>
989 </row>
990 <row>
991 <entry><parameter>printing = sysv|hpux</parameter></entry>
992 <entry>lppause command   (...is empty)</entry>
993 </row>
994 <row>
995 <entry><parameter>printing = qnx</parameter></entry>
996 <entry>lppause command   (...is empty)</entry>
997 </row>
998 <row>
999 <entry><parameter>printing = bsd|aix|lprng|plp</parameter></entry>
1000 <entry>lpresume command is <command>lp -i %p-%j -H resume</command></entry>
1001 </row>
1002 <row>
1003 <entry><parameter>printing = sysv|hpux</parameter></entry>
1004 <entry>lpresume command   (...is empty)</entry>
1005 </row>
1006 <row>
1007 <entry><parameter>printing = qnx</parameter></entry>
1008 <entry>lpresume command   (...is empty)</entry>
1009 </row>
1010 </tbody>
1011 </tgroup>
1012 </informaltable>
1013
1014 <para>
1015 We excluded the special CUPS case here, because it is discussed in the
1016 next chapter. Just a short summary. For <parameter>printing =
1017 CUPS</parameter>: If SAMBA is compiled against libcups, it uses the
1018 CUPS API to submit jobs, etc. (It is a good idea also to set
1019 "<parameter>printcap = cups</parameter>" in case your
1020 <filename>cupsd.conf</filename> is set to write its autogenerated
1021 printcap file to an unusual place). Otherwise Samba maps to the System
1022 V printing commands with the -oraw option for printing, i.e. it uses
1023 <command>lp -c -d%p -oraw; rm %s</command> With <parameter>printing =
1024 cups</parameter> , and if SAMBA is compiled against libcups, any
1025 manually set print command will be ignored!
1026 </para>
1027
1028 <para>
1029 Having listed the above mappings here, you should note that there used
1030 to be a <emphasis>bug</emphasis> in recent 2.2.x versions which
1031 prevented the mapping from taking effect. It lead to the
1032 "bsd|aix|lprng|plp" settings taking effect for all other systems, for
1033 the most important commands (the <command>print</command> command, the
1034 <command>lpq</command> command and the <command>lprm</command>
1035 command). The <command>lppause</command> command and the
1036 <command>lpresume</command> command remained empty. Of course, these
1037 commands worked on bsd|aix|lprng|plp but they didn't work on
1038 sysv|hpux|qnx systems. To work around this bug, you need to
1039 explicitly set the commands. Use <command>testparm -v</command> to
1040 check which command takes effect. Then check that this command is
1041 adequate and actually works for your installed print subsystem. It is
1042 always a good idea to explicitly set up your configuration files the
1043 way you want them to work and not rely on any built-in defaults.
1044 </para>
1045 </sect2>
1046
1047 <sect2>
1048 <title>Setting up your own Print Commands</title>
1049
1050 <para>
1051 After a print job has finished spooling to a service, the
1052 <parameter>print command</parameter> will be used by Samba via a
1053 <emphasis>system()</emphasis> call to process the spool file.  Usually
1054 the command specified will submit the spool file to the host's
1055 printing subsystem. But there is no requirement at all that this must
1056 be the case. The print subsystem will probably not remove the spool
1057 file on its own. So whatever command you specify on your own you
1058 should ensure that the spool file is deleted after it has been
1059 processed.
1060 </para>
1061
1062 <para>
1063 There is no difficulty with using your own customized print commands
1064 with the traditional printing systems. However, if you don't wish to
1065 "roll your own", you should be well informed about the default
1066 built-in commands that Samba uses for each printing subsystem (see the
1067 table above).  In all the commands listed in the last paragraphs you
1068 see parameters of the form <emphasis>%X</emphasis> These are
1069 <emphasis>macros</emphasis>, or shortcuts, used as place holders for
1070 the names of real objects. At the time of running a command with such
1071 a placeholder, Samba will insert the appropriate value
1072 automatically. Print commands can handle all Samba macro
1073 substitutions. In regard to printing, the following ones do have
1074 special relevance:
1075 </para>
1076
1077 <itemizedlist>
1078 <listitem><para><parameter>%s, %f</parameter> - the path to the spool
1079 file name</para></listitem>
1080
1081 <listitem><para><parameter>%p</parameter> - the appropriate printer
1082 name</para></listitem>
1083
1084 <listitem><para><parameter>%J</parameter> - the job name as
1085 transmitted by the client.</para></listitem>
1086
1087 <listitem><para><parameter>%c</parameter> - the number of printed
1088 pages of the spooled job (if known).</para></listitem>
1089
1090 <listitem><para><parameter>%z</parameter> - the size of the spooled
1091 print job (in bytes)</para></listitem>
1092
1093 </itemizedlist>
1094
1095 <para>
1096 The print command MUST contain at least one occurrence of
1097 <parameter>%s</parameter> or <parameter>%f</parameter>. -- The
1098 <parameter>%p</parameter> is optional. If no printer name is supplied,
1099 the <parameter>%p</parameter> will be silently removed from the print
1100 command. In this case the job is sent to the default printer.
1101 </para>
1102
1103 <para>
1104 If specified in the <parameter>[global]</parameter> section, the print
1105 command given will be used for any printable service that does not
1106 have its own print command specified. If there is neither a specified
1107 print command for a printable service nor a global print command,
1108 spool files will be created but not processed! And (most importantly):
1109 print files will not be removed, so they will start filling your Samba
1110 hard disk.
1111 </para>
1112
1113 <para>
1114 Note that printing may fail on some UNIXes from the "nobody"
1115 account. If this happens, create an alternative guest account and
1116 supply it with the privilege to print. Set up this guest account in
1117 the <parameter>[global]</parameter> section with the <parameter>guest
1118 account</parameter> parameter.
1119 </para>
1120
1121 <para>
1122 You can form quite complex print commands. You need to realize that
1123 print commands are just passed to a UNIX shell. The shell is able to
1124 expand the included environment variables as usual. (The syntax to
1125 include a UNIX environment variable <parameter>$variable</parameter>
1126 in <filename>smb.conf</filename> or in the Samba print command is
1127 <parameter>%$variable</parameter>.) To give you a working
1128 <parameter>print command</parameter> example, the following will log a
1129 print job to <filename>/tmp/print.log</filename>, print the file, then
1130 remove it. Note that ';' is the usual separator for commands in shell
1131 scripts:
1132 </para>
1133
1134 <para><screen>
1135 <![CDATA[
1136  print command = echo Printing %s >> /tmp/print.log; lpr -P %p %s; rm %s
1137 ]]>
1138 </screen></para>
1139
1140 <para>
1141 You may have to vary your own command considerably from this example
1142 depending on how you normally print files on your system.  The default
1143 for the <parameter>print command</parameter> parameter varies depending on the setting of
1144 the <parameter>printing</parameter> parameter. Another example is:
1145 </para>
1146
1147 <para><screen>
1148  print command = /usr/local/samba/bin/myprintscript %p %s
1149 </screen></para>
1150 </sect2>
1151 </sect1>
1152
1153 <sect1>
1154 <title>Innovations in Samba Printing since 2.2</title>
1155
1156 <para>
1157 Before version 2.2.0, Samba's print server support for Windows clients
1158 was limited to the level of <emphasis>LanMan</emphasis> printing
1159 calls. This is the same protocol level as Windows 9x PCs offer when
1160 they share printers.  Beginning with the 2.2.0 release, Samba started
1161 to support the native Windows NT printing mechanisms. These are
1162 implemented via <emphasis>MS-RPC</emphasis> (RPC = <emphasis>Remote
1163 Procedure Calls</emphasis> ). MS-RPCs use the
1164 <emphasis>SPOOLSS</emphasis> named pipe for all printing.
1165 </para>
1166
1167 <para>
1168 The additional functionality provided by the new SPOOLSS support includes:
1169 </para>
1170
1171 <itemizedlist>
1172 <listitem><para>Support for downloading printer driver files to Windows
1173 95/98/NT/2000 clients upon demand (<emphasis>Point'n'Print</emphasis>);
1174 </para></listitem>
1175
1176 <listitem><para>Uploading of printer drivers via the Windows NT
1177 <emphasis>Add Printer Wizard</emphasis> (APW) or the
1178 <emphasis>Imprints</emphasis> tool set (refer to <ulink
1179 url="http://imprints.sourceforge.net/">http://imprints.sourceforge.net</ulink>);
1180 </para></listitem>
1181
1182 <listitem><para>Support for the native MS-RPC printing calls such as
1183 StartDocPrinter, EnumJobs(), etc... (See the MSDN documentation
1184 at <ulink
1185 url="http://msdn.microsoft.com/">http://msdn.microsoft.com/</ulink>
1186 for more information on the Win32 printing API);</para></listitem>
1187
1188 <listitem><para>Support for NT <emphasis>Access Control
1189 Lists</emphasis> (ACL) on printer objects;</para></listitem>
1190
1191 <listitem><para>Improved support for printer queue manipulation
1192 through the use of internal databases for spooled job information
1193 (implemented by various <filename>*.tdb</filename>
1194 files).</para></listitem>
1195
1196 </itemizedlist>
1197
1198 <para>
1199 One other benefit of an update is this: Samba-3 is able to publish
1200 all its printers in Active Directory (or LDAP)!
1201 </para>
1202
1203 <para>
1204 One slight difference is here: it is possible on a Windows NT print
1205 server to have printers listed in the Printers folder which are
1206 <emphasis>not</emphasis> shared. Samba does not make this
1207 distinction. By definition, the only printers of which Samba is aware
1208 are those which are specified as shares in
1209 <filename>smb.conf</filename>. The reason is that Windows NT/2k/XPprof
1210 clients do not normally need to use the standard SMB printer share;
1211 rather they can print directly to any printer on another Windows NT
1212 host using MS-RPC. This of course assumes that the printing client has
1213 the necessary privileges on the remote host serving the printer. The
1214 default permissions assigned by Windows NT to a printer gives the
1215 "Print" permissions to the well-known <emphasis>Everyone</emphasis>
1216 group. (The older clients of type Win9x can only print to "shared"
1217 printers).
1218 </para>
1219
1220 <sect2>
1221 <title>Client Drivers on Samba Server for <emphasis>Point'n'Print</emphasis></title>
1222
1223 <para>
1224 There is still confusion about what all this means: <emphasis>Is it or
1225 is it not a requirement for printer drivers to be installed on a Samba
1226 host in order to support printing from Windows clients?</emphasis> The
1227 answer to this is: No, it is not a
1228 <emphasis>requirement</emphasis>. Windows NT/2000 clients can, of
1229 course, also run their APW to install drivers
1230 <emphasis>locally</emphasis> (which then connect to a Samba served
1231 print queue). This is the same method as used by Windows 9x
1232 clients. (However, a <emphasis>bug</emphasis> existed in Samba 2.2.0
1233 which made Windows NT/2000 clients require that the Samba server
1234 possess a valid driver for the printer. This was fixed in Samba
1235 2.2.1).
1236 </para>
1237
1238 <para>
1239 But it is a new <emphasis>option</emphasis> to install the printer
1240 drivers into the <parameter>[print$]</parameter> share of the Samba
1241 server, and a big convenience too. Then <emphasis>all</emphasis>
1242 clients (including 95/98/ME) get the driver installed when they first
1243 connect to this printer share. The <emphasis>uploading</emphasis> or
1244 <emphasis>depositing</emphasis> of the driver into this
1245 <parameter>[print$]</parameter> share, and the following binding of
1246 this driver to an existing Samba printer share can be achieved by
1247 different means:
1248 </para>
1249
1250 <itemizedlist>
1251 <listitem><para>running the <emphasis>APW</emphasis> on an
1252 NT/2k/XPprof client (this doesn't work from 95/98/ME
1253 clients);</para></listitem>
1254
1255 <listitem><para>using the <emphasis>Imprints</emphasis>
1256 toolset;</para></listitem>
1257
1258 <listitem><para>using the <emphasis>smbclient</emphasis> and
1259 <emphasis>rpcclient</emphasis> commandline tools;</para></listitem>
1260
1261 <listitem><para>using <emphasis>cupsaddsmb</emphasis>(only works for
1262 the CUPS printing system, not for LPR/LPD, LPRng
1263 etc.).</para></listitem>
1264
1265 </itemizedlist>
1266
1267 <para>
1268 Please take additional note of the following fact: <emphasis>Samba
1269 does not use these uploaded drivers in any way to process spooled
1270 files</emphasis>. Drivers are utilized entirely by the clients, who
1271 download and install them via the "Point 'n'Print" mechanism supported
1272 by Samba. The clients use these drivers to generate print files in the
1273 format the printer (or the Unix print system) requires. Print files
1274 received by Samba are handed over to the Unix printing system, which
1275 is responsible for all further processing, if needed.
1276 </para>
1277 </sect2>
1278
1279 <sect2>
1280 <title>The [printer$] Section is removed from Samba-3</title>
1281
1282 <formalpara><title>
1283 <parameter>[print$]</parameter> vs. <parameter>[printer$]</parameter>
1284 </title>
1285
1286 <para>
1287 Versions of Samba prior to 2.2 made it possible to use a share
1288 named <emphasis>[printer$]</emphasis>. This name was taken from the
1289 same named service created by Windows 9x clients when a printer was
1290 shared by them. Windows 9x printer servers always have a
1291 <parameter>[printer$]</parameter> service which provides read-only
1292 access (with no password required) in order to support printer driver
1293 downloads.  However, Samba's initial implementation allowed for a
1294 parameter named <parameter>printer driver location</parameter> to be
1295 used on a per share basis.  This specified the location of the driver
1296 files associated with that printer. Another parameter named
1297 <parameter>printer driver</parameter> provided a means of defining the
1298 printer driver name to be sent to the client.  These parameters,
1299 including the <parameter>printer driver file</parameter> parameter,
1300 are now removed and can not be used in installations of Samba-3.0.
1301 Now the share name <parameter>[print$]</parameter> is used for the
1302 location of downloadable printer drivers. It is taken from the
1303 <parameter>[print$]</parameter> service created by Windows NT PCs when
1304 a printer is shared by them. Windows NT print servers always have a
1305 <parameter>[print$]</parameter> service which provides read-write
1306 access (in the context of its ACLs) in order to support printer driver
1307 down- and uploads.  Don't fear -- this does not mean Windows 9x
1308 clients are thrown aside now. They can use Samba's
1309 <parameter>[print$]</parameter> share support just fine.
1310 </para></formalpara>
1311 </sect2>
1312
1313 <sect2>
1314 <title>Creating the [print$] Share</title>
1315
1316 <para>
1317 In order to support the up- and downloading of printer driver files,
1318 you must first configure a file share named
1319 <parameter>[print$]</parameter>. The "public" name of this share is
1320 hard coded in Samba's internals (because it is hardcoded in the MS
1321 Windows clients too). It cannot be renamed since Windows clients are
1322 programmed to search for a service of exactly this name if they want
1323 to retrieve printer driver files.
1324 </para>
1325
1326 <para>
1327 You should modify the server's <filename>smb.conf</filename> file to
1328 add the global parameters and create the
1329 <parameter>[print$]</parameter> file share (of course, some of the
1330 parameter values, such as 'path' are arbitrary and should be replaced
1331 with appropriate values for your site):
1332 </para>
1333
1334 <para><screen>
1335  [global]
1336       ; members of the ntadmin group should be able to add drivers and set
1337       ; printer properties. root is implicitly always a 'printer admin'.
1338       printer admin = @ntadmin
1339       [....]
1340
1341  [printers]
1342       [....]
1343
1344  [print$]
1345       comment = Printer Driver Download Area
1346       path = /etc/samba/drivers
1347       browseable = yes
1348       guest ok = yes
1349       read only = yes
1350       write list = @ntadmin, root
1351 </screen></para>
1352
1353 <para>
1354 Of course, you also need to ensure that the directory named by the
1355 <parameter>path</parameter> parameter exists on the Unix file system.
1356 </para>
1357
1358 </sect2>
1359
1360 <sect2>
1361 <title>Parameters in the <parameter>[print$]</parameter> Section</title>
1362
1363 <para>
1364 <parameter>[print$]</parameter> is a special section in
1365 <filename>smb.conf</filename>. It contains settings relevant to
1366 potential printer driver download and local installation by clients.
1367 </para>
1368
1369 <variablelist>
1370 <varlistentry><term><parameter>comment = Printer Driver
1371 Download Area</parameter></term>
1372 <listitem><para> the comment appears next to the share name if it is
1373 listed in a share list (usually Windows clients won't see it often but
1374 it will also appear up in a <command>smbclient -L sambaserver
1375 </command> output). </para></listitem></varlistentry>
1376
1377 <varlistentry><term><parameter>path = /etc/samba/printers</parameter></term>
1378 <listitem><para> this is the path to the location of the Windows
1379 driver file deposit from the UNIX point of
1380 view.</para></listitem></varlistentry>
1381
1382 <varlistentry><term><parameter>browseable = no</parameter></term>
1383 <listitem><para> this makes the <parameter>[print$]</parameter> share
1384 "invisible" in Network Neighbourhood to clients. However, you can
1385 still "mount" it from any client using the <command>net use
1386 g:\\sambaserver\print$</command> command in a "DOS box" or the
1387 "Connect network drive" menu from Windows
1388 Explorer.</para></listitem></varlistentry>
1389
1390 <varlistentry><term><parameter>guest ok = yes</parameter></term>
1391 <listitem><para>this gives read only access to this share for all
1392 guest users. Access may be used to download and install printer
1393 drivers on clients. The requirement for <parameter>guest ok =
1394 yes</parameter> depends upon how your site is configured. If users
1395 will be guaranteed to have an account on the Samba host, then this is
1396 a non-issue.</para>
1397
1398 <note><para> 
1399 The non-issue is this: if all your Windows NT users are guaranteed to
1400 be authenticated by the Samba server (for example if Samba
1401 authenticates via an NT domain server and the NT user has already been
1402 validated by the Domain Controller in order to logon to the Windows NT
1403 session), then guest access is not necessary. Of course, in a
1404 workgroup environment where you just want to be able to print without
1405 worrying about silly accounts and security, then configure the share
1406 for guest access. You'll probably want to add <parameter>map to guest
1407 = Bad User</parameter> in the <parameter>[global]</parameter> section
1408 as well. Make sure you understand what this parameter does before
1409 using it.
1410 </para></note> </listitem></varlistentry>
1411
1412 <varlistentry><term><parameter>read only = yes</parameter></term>
1413 <listitem><para>as we don't want everybody to upload driver files (or
1414 even change driver settings) we tagged this share as not
1415 writeable.</para></listitem></varlistentry>
1416
1417 <varlistentry><term><parameter>write list = @ntadmin,root</parameter></term>
1418 <listitem><para>since the <parameter>[print$]</parameter> was made
1419 read only by the previous setting, we need to create a "write list"
1420 also. UNIX groups (denoted with a leading "@" character) and users
1421 listed here are allowed write access (as an exception to the general
1422 public's "read-only" access), which they need to update files on the
1423 share.  Normally you will want to only name administrative level user
1424 accounts in this setting. Check the file system permissions to make
1425 sure these accounts can copy files to the share. If this is a non-root
1426 account, then the account should also be mentioned in the global
1427 <parameter>printer admin </parameter> parameter.  See the
1428 <filename>smb.conf</filename> man page for more information on
1429 configuring file shares.  </para></listitem></varlistentry>
1430
1431 </variablelist>
1432
1433 </sect2>
1434
1435 <sect2>
1436 <title>Subdirectory Structure in <parameter>[print$]</parameter></title>
1437
1438 <para>
1439 In order for a Windows NT print server to support the downloading of
1440 driver files by multiple client architectures, you must create several
1441 subdirectories within the <parameter>[print$]</parameter> service
1442 (i.e. the Unix directory named by the <parameter>path</parameter>
1443 parameter). These correspond to each of the supported client
1444 architectures. Samba follows this model as well. Just like the name of
1445 the <parameter>[print$]</parameter> share itself, the subdirectories
1446 *must* be exactly the names listed below (you may leave out the
1447 subdirectories of architectures you don't want to support).
1448 </para>
1449
1450 <para>
1451 Therefore, create a directory tree below the
1452 <parameter>[print$]</parameter> share for each architecture you wish
1453 to support.
1454 </para>
1455
1456 <para><screen>
1457
1458 [print$]--+--
1459           |--W32X86           # serves drivers to "Windows NT x86"
1460           |--WIN40            # serves drivers to "Windows 95/98"
1461           |--W32ALPHA         # serves drivers to "Windows NT Alpha_AXP"
1462           |--W32MIPS          # serves drivers to "Windows NT R4000"
1463           |--W32PPC           # serves drivers to "Windows NT PowerPC"
1464
1465 </screen></para>
1466
1467 <important><title>REQUIRED PERMISSIONS</title>
1468
1469 <para>
1470 In order to add a new driver to your Samba host, one of two conditions
1471 must hold true:
1472 </para>
1473
1474 <itemizedlist>
1475 <listitem><para>The account used to connect to the Samba host must
1476 have a UID of 0 (i.e. a root account)</para></listitem>
1477
1478 <listitem><para>The account used to connect to the Samba host must be
1479 named in the <emphasis>printer admin</emphasis>list.</para></listitem>
1480
1481 </itemizedlist>
1482
1483 <para>
1484 Of course, the connected account must still possess access to add
1485 files to the subdirectories beneath
1486 <parameter>[print$]</parameter>. Remember that all file shares are set
1487 to 'read only' by default.
1488 </para>
1489 </important>
1490
1491 <para>
1492 Once you have created the required <parameter>[print$]</parameter>
1493 service and associated subdirectories, go to a Windows NT 4.0/2k/XP
1494 client workstation. Open "Network Neighbourhood" or "My Network
1495 Places" and browse for the Samba host. Once you have located the
1496 server, navigate to its "Printers and Faxes" folder.  You should see
1497 an initial listing of printers that matches the printer shares defined
1498 on your Samba host.
1499 </para>
1500 </sect2>
1501 </sect1>
1502
1503 <sect1>
1504 <title>Installing Drivers into [print$]</title>
1505
1506 <para>
1507 You have successfully created the <parameter>[print$]</parameter>
1508 share in <filename>smb.conf</filename>?  And Samba has re-read its
1509 configuration? Good. But you are not yet ready to take off. The
1510 <emphasis>driver files</emphasis> need to be present in this share,
1511 too! So far it is still an empty share. Unfortunatly, it is not enough
1512 to just copy the driver files over. They need to be <emphasis>set
1513 up</emphasis> too.  And that is a bit tricky, to say the least. We
1514 will now discuss two alternative ways to install the drivers into
1515 <parameter>[print$]</parameter>:
1516 </para>
1517
1518 <itemizedlist>
1519
1520 <listitem><para>using the Samba commandline utility
1521 <command>rpcclient</command> with its various subcommands (here:
1522 <command>adddriver</command> and <command>setdriver</command>) from
1523 any UNIX workstation;</para></listitem>
1524
1525 <listitem><para>running a GUI (<emphasis>Printer
1526 Properties</emphasis> and <emphasis>Add Printer Wizard</emphasis>)
1527 from any Windows NT/2k/XP client workstation.</para></listitem>
1528
1529 </itemizedlist>
1530
1531 <para>
1532 The latter option is probably the easier one (even if the only
1533 entrance to this realm seems a little bit weird at first).
1534 </para>
1535
1536 <sect2>
1537 <title>Setting Drivers for existing Printers with a Client GUI</title>
1538
1539 <para>
1540 The initial listing of printers in the Samba host's
1541 <emphasis>Printers</emphasis> folder accessed from a client's Explorer
1542 will have no real printer driver assigned to them. By default, in
1543 Samba-3 (as in 2.2.1 and later) this driver name is set to a NULL
1544 string. This must be changed now. The local <emphasis>Add Printer
1545 Wizard</emphasis>, run from NT/2000/XP clients, will help us in this
1546 task.
1547 </para>
1548
1549 <para>
1550 However, the job to set a valid driver for the printer is not a
1551 straightforward one: You must attempt to view the printer properties
1552 for the printer to which you want the driver assigned. Open the
1553 Windows Explorer, open Network Neighbourhood, browse to the Samba
1554 host, open Samba's <guiicon>Printers</guiicon> folder, right-click the printer icon and
1555 select <guimenu>Properties...</guimenu>. You are now trying to view printer and driver
1556 properties for a queue which has this default <constant>NULL</constant> driver
1557 assigned. This will result in an error message (this is normal here):
1558 </para>
1559
1560 <para><computeroutput> Device settings cannot be displayed. The driver
1561 for the specified printer is not installed, only spooler properties
1562 will be displayed. Do you want to install the driver
1563 now?</computeroutput></para>
1564
1565 <para>
1566 <emphasis>Important:</emphasis>Don't click "Yes"!  Instead,
1567 <emphasis>click "No"</emphasis> in the error dialog. Only now you will
1568 be presented with the printer properties window. From here, the way to
1569 assign a driver to a printer is open to us. You have now the choice
1570 either:
1571 </para>
1572
1573 <itemizedlist>
1574 <listitem><para>select a driver from the popup list of installed
1575 drivers.  <emphasis>Initially this list will be empty.</emphasis>
1576 Or</para></listitem>
1577
1578 <listitem><para>use the <emphasis>"New Driver..."</emphasis> button to
1579 install a new printer driver (which will in fact start up the
1580 APW).</para></listitem>
1581 </itemizedlist>
1582
1583 <para>
1584 Once the APW is started, the procedure is exactly the same as the one
1585 you are familiar with in Wiindows (we assume here that you are
1586 familiar with the printer driver installations procedure on Windows
1587 NT). Make sure your connection is in fact setup as a user with
1588 <emphasis>printer admin</emphasis> privileges (if in doubt, use
1589 <command>smbstatus</command> to check for this). If you wish to
1590 install printer drivers for client operating systems other than
1591 "Windows NT x86", you will need to use the
1592 <emphasis>Sharing</emphasis> tab of the printer properties dialog.
1593 </para>
1594
1595 <para>
1596 Assuming you have connected with an administrative (or root) account
1597 (as named by the <parameter>printer admin</parameter> parameter),
1598 you will also be able to modify other printer properties such as ACLs
1599 and default device settings using this dialog. For the default device
1600 settings, please consider the advice given further below.
1601 </para>
1602 </sect2>
1603
1604 <sect2>
1605 <title>Setting Drivers for existing Printers with
1606 <command>rpcclient</command></title>
1607
1608 <para>
1609 The second way to install printer drivers into
1610 <parameter>[print$]</parameter> and set them up in a valid way can be
1611 done from the UNIX command line.  This involves four distinct steps:
1612 </para>
1613
1614 <orderedlist>
1615 <listitem><para> gathering the info about the required driver files
1616 and collecting the files together;</para></listitem>
1617
1618 <listitem><para> deposit the driver files into the
1619 <parameter>[print$]</parameter> share's correct subdirectories
1620 (possibly by using <command>smbclient</command>);</para></listitem>
1621
1622 <listitem><para>2. -- running the <command>rpcclient</command>
1623 commandline utility once with the <command>addriver</command>
1624 subcommand,</para></listitem>
1625
1626 <listitem><para>3. -- running <command>rpcclient</command> a second
1627 time with the <command>setdriver</command>
1628 subcommand.</para></listitem>
1629 </orderedlist>
1630
1631 <para>
1632 We will provide detailed hints for each of these steps in the next few
1633 paragraphs.
1634 </para>
1635
1636 <sect3>
1637 <title>Identifying the Driver Files</title>
1638
1639 <para>
1640 To find out about the driver files, you have two options: you could
1641 investigate the driver CD which comes with your printer.  Study the
1642 <filename>*.inf</filename> file on the CD, if it is contained. This
1643 may not be the possible, since the *.inf file might be
1644 missing. Unfortunately, many vendors have now started to use their own
1645 installation programs. These installations packages are often some
1646 sort of Windows platform archive format, plus, the files may get
1647 re-named during the installation process. This makes it extremely
1648 difficult to identify the driver files you need.
1649 </para>
1650
1651 <para>
1652 Then you only have the second option: install the driver first on a
1653 Windows client *locally* and investigate which file names and paths it
1654 uses after they are installed. (Note, that you need to repeat this
1655 procedure for every client platform you want to support. We are going
1656 to show it here for the "<emphasis>W32X86</emphasis>" platform only, a
1657 name used by Microsoft for all WinNT/2k/XP clients...)
1658 </para>
1659
1660 <para>
1661 A good method to recognize the driver files this is to print the test
1662 page from the driver's <emphasis>Properties</emphasis> Dialog
1663 (<emphasis>General</emphasis> tab). Then look at the list of driver
1664 files named on the printout. You'll need to recognize what Windows
1665 (and Samba) are calling the <parameter>Driver File</parameter> , the
1666 <parameter>Data File</parameter>, the <parameter>Config File</parameter>,
1667 the <parameter>Help File</parameter> and (optionally) the
1668 <parameter>Dependent Driver Files</parameter> (this may vary slightly
1669 for Windows NT).  You need to remember all names (or better take a
1670 note) for the next steps.
1671 </para>
1672
1673 <para>
1674 Another method to quickly test the driver filenames and related paths
1675 is provided by the <command>rpcclient</command> utility. Run it with
1676 <command>enumdrivers</command> or with the
1677 <command>getdriver</command> subcommand, each in the
1678 <emphasis>3</emphasis> level. In the following example,
1679 <emphasis>TURBO_XP</emphasis> is the name of the Windows PC (in this
1680 case it was a Windows XP Professional laptop, BTW). I had installed
1681 the driver locally to TURBO_XP while <emphasis>kde-bitshop</emphasis> is
1682 the name of the Linux host from which I am working. We could run an
1683 <emphasis>interactive</emphasis> <command>rpcclient</command> session;
1684 then we'd get an <emphasis>rpcclient /></emphasis> prompt and would
1685 type the subcommands at this prompt. This is left as a good exercise
1686 to the reader. For now we use <command>rpcclient</command> with the
1687 <parameter>-c</parameter> parameter to execute a single subcommand
1688 line and exit again. This is the method you would use if you want to
1689 create scripts to automate the procedure for a large number of
1690 printers and drivers. Note the different quotes used to overcome the
1691 different spaces in between words:
1692 </para>
1693
1694 <para><screen>
1695
1696   kde-bitshop:~# rpcclient -U'Danka%xxxx' -c 'getdriver "Heidelberg Digimaster 9110 (PS)" 3' TURBO_XP
1697   cmd = getdriver "Heidelberg Digimaster 9110 (PS)" 3
1698
1699   [Windows NT x86]
1700   Printer Driver Info 3:
1701           Version: [2]
1702           Driver Name: [Heidelberg Digimaster 9110 (PS)]
1703           Architecture: [Windows NT x86]
1704           Driver Path: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\HDNIS01_de.DLL]
1705           Datafile: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.ppd]
1706           Configfile: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\HDNIS01U_de.DLL]
1707           Helpfile: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\HDNIS01U_de.HLP]
1708   
1709           Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.DLL]
1710           Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.INI]
1711           Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1KMMin.DLL]
1712           Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.dat]
1713           Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.cat]
1714           Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.def]
1715           Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.hre]
1716           Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.vnd]
1717           Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.hlp]
1718           Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de_reg.HLP]
1719           Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\HDNIS01Aux.dll]
1720           Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\HDNIS01_de.NTF]
1721   
1722           Monitorname: []
1723           Defaultdatatype: []
1724
1725 </screen></para>
1726
1727 <para>
1728 You may notice, that this driver has quite a big number of
1729 "Dependentfiles" (I know worse cases however). Also, strangely, the
1730 "<filename>Driver File</filename>" is here tagged as "<filename>Driver
1731 Path</filename>".... oh, well. Here we don't have yet support for the
1732 so-called "WIN40" architecture installed. This name is used by
1733 Microsoft for the Win95/98/ME platforms. If we want to support these,
1734 we need to install the Win95/98/ME driver files in addition to those
1735 for W32X86 (i.e. the WinNT72000/XP clients) onto a Windows PC. This PC
1736 can also host the Win9x drivers, even if itself runs on Windows NT,
1737 2000 or XP.
1738 </para>
1739
1740 <para>
1741 Since the <parameter>print$</parameter> share is usually accessible
1742 through the Network Neighbourhood, you can also use the UNC notation
1743 from Windows Explorer to poke at it. The Win9x driver files will end
1744 up in subdirectory "0" of the "WIN40" directory. The full path to
1745 access them will be
1746 <filename>\\WINDOWSHOST\print$\WIN40\0\</filename>.
1747 </para>
1748
1749 <note><para> more recent drivers on Windows 2000 and Wndows XP are
1750 installed into the "3" subdirectory instead of the "2". The version 2
1751 of drivers, as used in Windows NT, were running in Kernel Mode.
1752 Windows 2000 changed this. While it still can use the Kernel Mode
1753 drivers (if this is enabled by the Admin), its native mode for printer
1754 drivers is User Mode execution. This requires drivers designed for
1755 this. These type of drivers install into the "3" subdirectory.
1756 </para></note>
1757 </sect3>
1758
1759 <sect3>
1760 <title>Collecting the Driver Files from a Windows Host's
1761 <parameter>[print$]</parameter> Share</title>
1762
1763 <para>
1764 Now we need to collect all the driver files we identified. in our
1765 previous step. Where do we get them from? Well, why not retrieve them
1766 from the very PC and the same <parameter>[print$]</parameter> share
1767 which we investigated in our last step to identify the files? We can
1768 use <command>smbclient</command> to do this. We will use the paths and
1769 names which were leaked to us by <command>getdriver</command>. The
1770 listing is edited to include linebreaks for readability:
1771 </para>
1772
1773 <para><screen>
1774
1775   kde-bitshop:~# smbclient //TURBO_XP/print\$ -U'Danka%xxxx'                            \
1776                                               -c 'cd W32X86/2;mget HD*_de.*             \
1777                                               hd*ppd Hd*_de.* Hddm*dll HDN*Aux.DLL'
1778   added interface ip=10.160.51.60 bcast=10.160.51.255 nmask=255.255.252.0
1779   Got a positive name query response from 10.160.50.8 ( 10.160.50.8 )
1780   Domain=[DEVELOPMENT] OS=[Windows 5.1] Server=[Windows 2000 LAN Manager]
1781   Get file Hddm91c1_de.ABD? n
1782   Get file Hddm91c1_de.def? y
1783   getting file \W32X86\2\Hddm91c1_de.def of size 428 as Hddm91c1_de.def (22.0 kb/s)     \
1784                                                                 (average 22.0 kb/s)
1785   Get file Hddm91c1_de.DLL? y
1786   getting file \W32X86\2\Hddm91c1_de.DLL of size 876544 as Hddm91c1_de.DLL (737.3 kb/s) \
1787                                                                    (average 737.3 kb/s)
1788   [...,]
1789
1790 </screen></para>
1791
1792 <para>
1793 After this command is complete, the files are in our current local
1794 directory. You probably have noticed that this time we passed several
1795 commands to the "-c" parameter, separated by semi-colons.  This
1796 effects that all commands are executed in sequence on the remote
1797 Windows server before smbclient exits again.
1798 </para>
1799
1800 <para>
1801 Don't forget to repeat the procedure for the "WIN40" architecture
1802 should you need to support Win95/98/XP clients.  Remember, the files
1803 for these architectures are in the WIN40/0/ subdir. Once we are
1804 complete, we can run <command>smbclient ...  put</command> to store
1805 the collected files on the Samba server's
1806 <parameter>[print$]</parameter> share.
1807 </para>
1808 </sect3>
1809
1810 <sect3>
1811 <title>Depositing the Driver Files into <parameter>[print$]</parameter></title>
1812
1813 <para>
1814 So, now we are going to put the driver files into the
1815 <parameter>[print$]</parameter> share. Remember, the UNIX path to this
1816 share has been defined previously in your
1817 <filename>smb.conf</filename>. You also have created subdirectories
1818 for the different Windows client types you want to support. Supposing
1819 your <parameter>[print$]</parameter> share maps to the UNIX path
1820 <filename>/etc/samba/drivers/</filename>, your driver files should now
1821 go here:
1822 </para>
1823
1824 <itemizedlist>
1825 <listitem><para>for all Windows NT, 2000 and XP clients into
1826 <filename>/etc/samba/drivers/W32X86/</filename> <emphasis>but
1827 *not*(yet) into the "2" subdir</emphasis>!</para></listitem>
1828
1829 <listitem><para>for all Windows 95, 98 and ME clients into
1830 <filename>/etc/samba/drivers/WIN40/</filename> -- <emphasis>but *not*
1831 (yet) into the "0" subdir</emphasis>!</para></listitem>
1832 </itemizedlist>
1833
1834 <para>
1835 We again use smbclient to transfer the driver files across the
1836 network. We specify the same files and paths as were leaked to us by
1837 running "<command>getdriver</command>" against the original
1838 <emphasis>Windows</emphasis> install. However, now we are going to
1839 store the files into a <emphasis>Samba/UNIX</emphasis> print server's
1840 <parameter>[print$]</parameter> share...
1841 </para>
1842
1843 <para><screen>
1844
1845  kde-bitshop:~# smbclient //SAMBA-CUPS/print\$ -U'root%xxxx' -c 'cd W32X86; put HDNIS01_de.DLL; \
1846                                                put Hddm91c1_de.ppd; put HDNIS01U_de.DLL;        \
1847                                                put HDNIS01U_de.HLP; put Hddm91c1_de.DLL;        \
1848                                                put Hddm91c1_de.INI; put Hddm91c1KMMin.DLL;      \
1849                                                put Hddm91c1_de.dat; put Hddm91c1_de.dat;        \
1850                                                put Hddm91c1_de.def; put Hddm91c1_de.hre;        \
1851                                                put Hddm91c1_de.vnd; put Hddm91c1_de.hlp;        \
1852                                                put Hddm91c1_de_reg.HLP; put HDNIS01Aux.dll;     \
1853                                                put HDNIS01_de.NTF'
1854  added interface ip=10.160.51.60 bcast=10.160.51.255 nmask=255.255.252.0
1855  Got a positive name query response from 10.160.51.162 ( 10.160.51.162 )
1856  Domain=[CUPS-PRINT] OS=[Unix] Server=[Samba 2.2.7a]
1857  putting file HDNIS01_de.DLL as \W32X86\HDNIS01_de.DLL (4465.5 kb/s) (average 4465.5 kb/s)
1858  putting file Hddm91c1_de.ppd as \W32X86\Hddm91c1_de.ppd (12876.8 kb/s) (average 4638.9 kb/s)
1859  putting file HDNIS01U_de.DLL as \W32X86\HDNIS01U_de.DLL (20249.8 kb/s) (average 5828.3 kb/s)
1860  putting file HDNIS01U_de.HLP as \W32X86\HDNIS01U_de.HLP (9652.8 kb/s) (average 5899.8 kb/s)
1861  putting file Hddm91c1_de.DLL as \W32X86\Hddm91c1_de.DLL (23777.7 kb/s) (average 10400.6 kb/s)
1862  putting file Hddm91c1_de.INI as \W32X86\Hddm91c1_de.INI (98.6 kb/s) (average 10329.0 kb/s)
1863  putting file Hddm91c1KMMin.DLL as \W32X86\Hddm91c1KMMin.DLL (22931.5 kb/s) (average 10501.7 kb/s)
1864  putting file Hddm91c1_de.dat as \W32X86\Hddm91c1_de.dat (2462.8 kb/s) (average 10393.0 kb/s)
1865  putting file Hddm91c1_de.dat as \W32X86\Hddm91c1_de.dat (4925.3 kb/s) (average 10356.3 kb/s)
1866  putting file Hddm91c1_de.def as \W32X86\Hddm91c1_de.def (417.9 kb/s) (average 10290.1 kb/s)
1867  putting file Hddm91c1_de.hre as \W32X86\Hddm91c1_de.hre (22571.3 kb/s) (average 11338.5 kb/s)
1868  putting file Hddm91c1_de.vnd as \W32X86\Hddm91c1_de.vnd (3384.6 kb/s) (average 10754.3 kb/s)
1869  putting file Hddm91c1_de.hlp as \W32X86\Hddm91c1_de.hlp (18406.8 kb/s) (average 10839.8 kb/s)
1870  putting file Hddm91c1_de_reg.HLP as \W32X86\Hddm91c1_de_reg.HLP (20278.3 kb/s) (average 11386.3 kb/s)
1871  putting file HDNIS01Aux.dll as \W32X86\HDNIS01Aux.dll (14994.6 kb/s) (average 11405.2 kb/s)
1872  putting file HDNIS01_de.NTF as \W32X86\HDNIS01_de.NTF (23390.2 kb/s) (average 13170.8 kb/s)
1873
1874 </screen></para>
1875
1876 <para>
1877 Phewww -- that was a lot of typing! Most drivers are a lot smaller --
1878 many only having 3 generic PostScript driver files plus 1 PPD. Note,
1879 that while we did retrieve the files from the "2" subdirectory of the
1880 "W32X86" directory from the Windows box, we <emphasis>don't</emphasis>
1881 put them (for now) in this same subdirectory of the Samba box! This
1882 re-location will automatically be done by the
1883 <command>adddriver</command> command which we will run shortly (and
1884 don't forget to also put the files for the Win95/98/ME architecture
1885 into the <emphasis>WIN40/</emphasis> subdirectory should you need
1886 them).
1887 </para>
1888 </sect3>
1889
1890 <sect3>
1891 <title>Check if the Driver Files are there (with smbclient)</title>
1892
1893 <para>
1894 For now we verify that our files are there. This can be done with
1895 <command>smbclient</command> too (but of course you can log in via SSH
1896 also and do this through a standard UNIX shell access too):
1897 </para>
1898
1899 <para><screen>
1900
1901  kde-bitshop:~# smbclient //SAMBA-CUPS/print\$ -U 'root%xxxx' -c 'cd W32X86; pwd; dir; cd 2; pwd; dir'
1902  added interface ip=10.160.51.60 bcast=10.160.51.255 nmask=255.255.252.0
1903  Got a positive name query response from 10.160.51.162 ( 10.160.51.162 )
1904  Domain=[CUPS-PRINT] OS=[Unix] Server=[Samba 2.2.7a]
1905
1906   Current directory is \\SAMBA-CUPS\print$\W32X86\
1907   .                                   D        0  Sun May  4 03:56:35 2003
1908   ..                                  D        0  Thu Apr 10 23:47:40 2003
1909   2                                   D        0  Sun May  4 03:56:18 2003
1910   HDNIS01Aux.dll                      A    15356  Sun May  4 03:58:59 2003
1911   Hddm91c1KMMin.DLL                   A    46966  Sun May  4 03:58:59 2003
1912   HDNIS01_de.DLL                      A   434400  Sun May  4 03:58:59 2003
1913   HDNIS01_de.NTF                      A   790404  Sun May  4 03:56:35 2003
1914   Hddm91c1_de.DLL                     A   876544  Sun May  4 03:58:59 2003
1915   Hddm91c1_de.INI                     A      101  Sun May  4 03:58:59 2003
1916   Hddm91c1_de.dat                     A     5044  Sun May  4 03:58:59 2003
1917   Hddm91c1_de.def                     A      428  Sun May  4 03:58:59 2003
1918   Hddm91c1_de.hlp                     A    37699  Sun May  4 03:58:59 2003
1919   Hddm91c1_de.hre                     A   323584  Sun May  4 03:58:59 2003
1920   Hddm91c1_de.ppd                     A    26373  Sun May  4 03:58:59 2003
1921   Hddm91c1_de.vnd                     A    45056  Sun May  4 03:58:59 2003
1922   HDNIS01U_de.DLL                     A   165888  Sun May  4 03:58:59 2003
1923   HDNIS01U_de.HLP                     A    19770  Sun May  4 03:58:59 2003
1924   Hddm91c1_de_reg.HLP                 A   228417  Sun May  4 03:58:59 2003
1925                 40976 blocks of size 262144. 709 blocks available
1926
1927   Current directory is \\SAMBA-CUPS\print$\W32X86\2\
1928   .                                   D        0  Sun May  4 03:56:18 2003
1929   ..                                  D        0  Sun May  4 03:56:35 2003
1930   ADOBEPS5.DLL                        A   434400  Sat May  3 23:18:45 2003
1931   laserjet4.ppd                       A     9639  Thu Apr 24 01:05:32 2003
1932   ADOBEPSU.DLL                        A   109568  Sat May  3 23:18:45 2003
1933   ADOBEPSU.HLP                        A    18082  Sat May  3 23:18:45 2003
1934   PDFcreator2.PPD                     A    15746  Sun Apr 20 22:24:07 2003
1935                 40976 blocks of size 262144. 709 blocks available
1936
1937 </screen></para>
1938
1939 <para>
1940 Notice that there are already driver files present in the
1941 <filename>2</filename> subdir (probably from a previous
1942 installation). Once the files for the new driver are there too, you
1943 are still a few steps away from being able to use them on the
1944 clients. The only thing you could do *now* is to retrieve them from a
1945 client just like you retrieve ordinary files from a file share, by
1946 opening print$ in Windows Explorer. But that wouldn't install them per
1947 Point'n'Print. The reason is: Samba doesn't know yet that these files
1948 are something special, namely <emphasis>printer driver
1949 files</emphasis> and it doesn't know yet to which print queue(s) these
1950 driver files belong.
1951 </para>
1952 </sect3>
1953
1954 <sect3>
1955 <title>Running <command>rpcclient</command> with
1956 <command>adddriver</command></title>
1957
1958 <para>
1959 So, next you must tell Samba about the special category of the files
1960 you just uploaded into the <parameter>[print$]</parameter> share. This
1961 is done by the "<command>adddriver</command>" command. It will
1962 prompt Samba to register the driver files into its internal TDB
1963 database files. The following command and its output has been edited,
1964 again, for readability:
1965 </para>
1966
1967 <para><screen>
1968
1969  kde-bitshop:~# rpcclient -Uroot%xxxx -c 'adddriver "Windows NT x86" "dm9110:HDNIS01_de.DLL: \
1970                                           Hddm91c1_de.ppd:HDNIS01U_de.DLL:HDNIS01U_de.HLP:   \
1971                                           NULL:RAW:Hddm91c1_de.DLL,Hddm91c1_de.INI,          \
1972                                           Hddm91c1_de.dat,Hddm91c1_de.def,Hddm91c1_de.hre,   \
1973                                           Hddm91c1_de.vnd,Hddm91c1_de.hlp,Hddm91c1KMMin.DLL, \
1974                                           HDNIS01Aux.dll,HDNIS01_de.NTF,                     \
1975                                           Hddm91c1_de_reg.HLP'                       SAMBA-CUPS
1976
1977  cmd = adddriver "Windows NT x86" "dm9110:HDNIS01_de.DLL:Hddm91c1_de.ppd:HDNIS01U_de.DLL:    \
1978                                    HDNIS01U_de.HLP:NULL:RAW:Hddm91c1_de.DLL,Hddm91c1_de.INI, \
1979                                    Hddm91c1_de.dat,Hddm91c1_de.def,Hddm91c1_de.hre,          \
1980                                    Hddm91c1_de.vnd,Hddm91c1_de.hlp,Hddm91c1KMMin.DLL,        \
1981                                    HDNIS01Aux.dll,HDNIS01_de.NTF,Hddm91c1_de_reg.HLP"
1982
1983  Printer Driver dm9110 successfully installed.
1984
1985 </screen></para>
1986
1987 <para>
1988 After this step the driver should be recognized by Samba on the print
1989 server. You need to be very carefull when typing the command. Don't
1990 exchange the order of the fields. Some changes would lead to a
1991 <computeroutput>NT_STATUS_UNSUCCESSFUL</computeroutput> error
1992 message. These become obvious. Other changes might install the driver
1993 files successfully, but render the driver unworkable. So take care!
1994 Hints about the syntax of the adddriver command are in the man
1995 page. The CUPS printing chapter of this HOWTO collection provides a
1996 more detailed description, if you should need it.
1997 </para>
1998 </sect3>
1999
2000 <sect3>
2001 <title>Check how Driver Files have been moved after
2002 <command>adddriver</command> finished</title>
2003
2004 <para>
2005 One indication for Samba's recognition of the files as driver files is
2006 the <computeroutput>successfully installed</computeroutput> message.
2007 Another one is the fact, that our files have been moved by the
2008 <command>adddriver</command> command into the "<filename>2</filename>"
2009 subdirectory. You can check this again with
2010 <command>smbclient</command>:
2011 </para>
2012
2013 <para><screen>
2014
2015  kde-bitshop:~# smbclient //SAMBA-CUPS/print\$ -Uroot%xxxx -c 'cd W32X86;dir;pwd;cd 2;dir;pwd'
2016  added interface ip=10.160.51.162 bcast=10.160.51.255 nmask=255.255.252.0
2017  Domain=[CUPS-PRINT] OS=[Unix] Server=[Samba 2.2.7a]
2018
2019   Current directory is \\SAMBA-CUPS\print$\W32X86\
2020   .                                   D        0  Sun May  4 04:32:48 2003
2021   ..                                  D        0  Thu Apr 10 23:47:40 2003
2022   2                                   D        0  Sun May  4 04:32:48 2003
2023                 40976 blocks of size 262144. 731 blocks available 
2024
2025   Current directory is \\SAMBA-CUPS\print$\W32X86\2\
2026   .                                   D        0  Sun May  4 04:32:48 2003
2027   ..                                  D        0  Sun May  4 04:32:48 2003
2028   DigiMaster.PPD                      A   148336  Thu Apr 24 01:07:00 2003
2029   ADOBEPS5.DLL                        A   434400  Sat May  3 23:18:45 2003
2030   laserjet4.ppd                       A     9639  Thu Apr 24 01:05:32 2003
2031   ADOBEPSU.DLL                        A   109568  Sat May  3 23:18:45 2003
2032   ADOBEPSU.HLP                        A    18082  Sat May  3 23:18:45 2003
2033   PDFcreator2.PPD                     A    15746  Sun Apr 20 22:24:07 2003
2034   HDNIS01Aux.dll                      A    15356  Sun May  4 04:32:18 2003
2035   Hddm91c1KMMin.DLL                   A    46966  Sun May  4 04:32:18 2003
2036   HDNIS01_de.DLL                      A   434400  Sun May  4 04:32:18 2003
2037   HDNIS01_de.NTF                      A   790404  Sun May  4 04:32:18 2003
2038   Hddm91c1_de.DLL                     A   876544  Sun May  4 04:32:18 2003
2039   Hddm91c1_de.INI                     A      101  Sun May  4 04:32:18 2003
2040   Hddm91c1_de.dat                     A     5044  Sun May  4 04:32:18 2003
2041   Hddm91c1_de.def                     A      428  Sun May  4 04:32:18 2003
2042   Hddm91c1_de.hlp                     A    37699  Sun May  4 04:32:18 2003
2043   Hddm91c1_de.hre                     A   323584  Sun May  4 04:32:18 2003
2044   Hddm91c1_de.ppd                     A    26373  Sun May  4 04:32:18 2003
2045   Hddm91c1_de.vnd                     A    45056  Sun May  4 04:32:18 2003
2046   HDNIS01U_de.DLL                     A   165888  Sun May  4 04:32:18 2003
2047   HDNIS01U_de.HLP                     A    19770  Sun May  4 04:32:18 2003
2048   Hddm91c1_de_reg.HLP                 A   228417  Sun May  4 04:32:18 2003
2049                 40976 blocks of size 262144. 731 blocks available
2050
2051 </screen></para>
2052
2053 <para>
2054 Another verification is that the timestamp of the printing TDB files
2055 is now updated (and possibly their filesize has increased).
2056 </para>
2057 </sect3>
2058
2059 <sect3>
2060 <title>Check if the Driver is recognized by Samba</title>
2061
2062 <para>
2063 Now the driver should be registered with Samba. We can easily verify
2064 this, and will do so in a moment. However, this driver is
2065 <emphasis>not yet</emphasis> associated with a particular
2066 <emphasis>printer</emphasis>. We may check the driver status of the
2067 files by at least three methods:
2068 </para>
2069
2070 <itemizedlist>
2071 <listitem><para>from any Windows client browse Network Neighbourhood,
2072 finde the Samba host and open the Samba "<emphasis>Printers and
2073 Faxes</emphasis>" folder. Select any printer icon, right-click and
2074 select the printer " <emphasis>Properties</emphasis>". Click on the
2075 "<emphasis>Advanced</emphasis>" tab. Here is a field indicating the
2076 driver for that printer. A drop down menu allows you to change that
2077 driver (be carefull to not do this unwittingly.).  You can use this
2078 list to view all drivers know to Samba. Your new one should be amongst
2079 them. (Each type of client will only see his own architecture's
2080 list. If you don't have every driver installed for each platform, the
2081 list will differ if you look at it from Windows95/98/ME or
2082 WindowsNT/2000/XP.)</para></listitem>
2083
2084 <listitem><para>from a Windows 2000 or XP client (not WinNT) browse
2085 <emphasis>Network Neighbourhood</emphasis>, search for the Samba
2086 server and open the server's <emphasis>Printers</emphasis> folder,
2087 right-click the white background (with no printer highlighted). Select
2088 "<emphasis>Server Properties</emphasis>". On the
2089 "<emphasis>Drivers</emphasis> " tab you will see the new driver listed
2090 now. This view enables you to also inspect the list of files belonging
2091 to that driver<emphasis> (this doesn't work on Windows NT, but only on
2092 Windows 2000 and Windows XP. WinNT doesn't provide the "Drivers"
2093 tab).</emphasis>. An alternative, much quicker method for Windows
2094 2000/XP to start this dialog is by typing into a DOS box (you must of
2095 course adapt the name to your Samba server instead of SAMBA-CUPS):
2096 </para>
2097
2098 <para><screen>
2099   rundll32 printui.dll,PrintUIEntry /s /t2 /n\\SAMBA-CUPS
2100 </screen></para>
2101 </listitem>
2102
2103 <listitem><para>from a UNIX prompt run this command (or a variant
2104 thereof), where "SAMBA-CUPS" is the name of the Samba host and "xxxx"
2105 represents the actual Samba password assigned to root:
2106 </para>
2107
2108 <para><screen>
2109   rpcclient -U'root%xxxx' -c 'enumdrivers' SAMBA-CUPS
2110 </screen></para>
2111
2112 <para>
2113 You will see a listing of all drivers Samba knows about. Your new one
2114 should be amongst them. But it is only listed under the [Windows NT
2115 x86] heading, not under [Windows 4.0], since we didn't install that
2116 part. Or did *you*? -- You will see a listing of all drivers Samba
2117 knows about. Your new one should be amongst them. In our example it is
2118 named <emphasis>dm9110</emphasis>.  Note that the 3rd column shows the
2119 other installed drivers twice, for each supported architecture one
2120 time. Our new driver only shows up for "Windows NT 4.0 or 2000". To
2121 have it present for "Windows 95, 98 and ME" you'll have to repeat the
2122 whole procedure with the WIN40 architecture and subdirectory.
2123 </para></listitem>
2124 </itemizedlist>
2125 </sect3>
2126
2127 <sect3>
2128 <title>A sidenote: you are not bound to specific driver names</title>
2129
2130 <para>
2131 You can name the driver as you like. If you repeat the
2132 <command>adddriver</command> step, with the same files as before, but
2133 with a different driver name, it will work the same:
2134 </para>
2135
2136 <para><screen>
2137
2138  kde-bitshop:~# rpcclient -Uroot%xxxx                                        \
2139                           -c 'adddriver "Windows NT x86"                     \
2140                           "myphantasydrivername:HDNIS01_de.DLL:              \
2141                           Hddm91c1_de.ppd:HDNIS01U_de.DLL:HDNIS01U_de.HLP:   \
2142                           NULL:RAW:Hddm91c1_de.DLL,Hddm91c1_de.INI,          \
2143                           Hddm91c1_de.dat,Hddm91c1_de.def,Hddm91c1_de.hre,   \
2144                           Hddm91c1_de.vnd,Hddm91c1_de.hlp,Hddm91c1KMMin.DLL, \
2145                           HDNIS01Aux.dll,HDNIS01_de.NTF,Hddm91c1_de_reg.HLP' SAMBA-CUPS
2146
2147  cmd = adddriver "Windows NT x86" 
2148                  "myphantasydrivername:HDNIS01_de.DLL:Hddm91c1_de.ppd:HDNIS01U_de.DLL:\
2149                   HDNIS01U_de.HLP:NULL:RAW:Hddm91c1_de.DLL,Hddm91c1_de.INI,           \
2150                   Hddm91c1_de.dat,Hddm91c1_de.def,Hddm91c1_de.hre,                    \
2151                   Hddm91c1_de.vnd,Hddm91c1_de.hlp,Hddm91c1KMMin.DLL,                  \
2152                   HDNIS01Aux.dll,HDNIS01_de.NTF,Hddm91c1_de_reg.HLP"
2153
2154  Printer Driver myphantasydrivername successfully installed.
2155
2156 </screen></para>
2157
2158 <para>
2159 You will also be able to bind that driver to any print queue (however,
2160 you are responsible yourself that you associate drivers to queues
2161 which make sense to the target printer). Note, that you can't run the
2162 <command>rpcclient</command> <command>adddriver</command> command
2163 repeatedly. Each run "consumes" the files you had put into the
2164 <parameter>[print$]</parameter> share by moving them into the
2165 respective subdirectories. So you <emphasis>must</emphasis> precede an
2166 "<command>smbclient ... put"</command> command before each
2167 "<command>rpcclient ...  addriver</command>" command.
2168 </para>
2169 </sect3>
2170
2171 <sect3>
2172 <title>La Grande Finale: Running <command>rpcclient</command> with
2173 <command>setdriver</command></title>
2174
2175 <para>
2176 Samba still needs to know <emphasis>which</emphasis> printer's driver
2177 this is.  It needs to create a mapping of the driver to a printer, and
2178 store this info in its "memory", the TDB files. The <command>rpcclient
2179 setdriver</command> command achieves exactly this:
2180 </para>
2181
2182 <para><screen>
2183  kde-bitshop:~# rpcclient -U'root%xxxx' -c 'setdriver dm9110 myphantasydrivername' SAMBA-CUPS
2184  cmd = setdriver dm9110 myphantasydrivername
2185  Successfully set dm9110 to driver myphantasydrivername.
2186 </screen></para>
2187
2188 <para>
2189 Ahhhhh -- no, I didn't want to do that. Repeat, this time with the
2190 name I intended: 
2191 </para>
2192
2193 <para><screen>
2194  kde-bitshop:~# rpcclient -U'root%xxxx' -c 'setdriver dm9110 dm9110' SAMBA-CUPS
2195  cmd = setdriver dm9110 dm9110
2196  Succesfully set dm9110 to driver dm9110.
2197 </screen></para>
2198
2199 <para>
2200 The syntax of the command is <command>rpcclient -U'root%sambapassword'
2201 -c 'setdriver "printername" "drivername' SAMBA-Hostname</command> . --
2202 Now we have done *most* of the work. But not yet all....
2203 </para>
2204
2205 <note><para>
2206 the "setdriver" command will only succeed if the printer is known to
2207 Samba already. A bug in 2.2.x prevented Samba from recognizing freshly
2208 installed printers. You had to restart Samba, or at least send a HUP
2209 signal to all running smbd processes to work around this:
2210 <command>kill -HUP `pidof smbd`</command>.  </para></note>
2211 </sect3>
2212 </sect2>
2213 </sect1>
2214
2215 <sect1>
2216 <title>"The Proof of the Pudding lies in the Eating" (Client Driver Insta
2217 Procedure)</title>
2218
2219 <para>
2220 A famous philosopher said once: <quote>The Proof of the Pudding lies
2221 in the Eating</quote>. The proof for our setup lies in the printing.
2222 So let's install the printer driver onto the client PCs. This is not
2223 as straightforward as it may seem. Read on.
2224 </para>
2225
2226 <sect2>
2227 <title>The first Client Driver Installation</title>
2228
2229 <para>
2230 Especially important is the installation onto the first client PC (for
2231 each architectural platform separately). Once this is done correctly,
2232 all further clients are easy to setup and shouldn't need further
2233 attention. What follows is a description for the recommended first
2234 procedure. You work now from a client workstation. First you should
2235 guarantee that your connection is not unwittingly mapped to
2236 <parameter>bad user</parameter> "nobody". In a DOS box type:
2237 </para>
2238
2239 <para><screen>
2240 net use \\SAMBA-SERVER\print$ /user:root
2241 </screen></para>
2242
2243 <para>
2244 Replace root, if needed, by another valid 'printer admin' user as
2245 given in the <filename>smb.conf</filename> definition. Should you
2246 already be connected as a different user, you'll get an error
2247 message. There is no easy way to get rid of that connection, because
2248 Windows doesn't seem to know a concept of "logging off" from a share
2249 connection (don't confuse this with logging off from the local
2250 workstation; that is a different matter). You can try to close
2251 <emphasis>all</emphasis> Windows file explorer and Internet Explorer
2252 windows. As a last resort, you may have to reboot. Make sure there is
2253 no automatic re-connection set up. It may be easier to go to a
2254 different workstation and try from there. After you have made sure you
2255 are connected as a printer admin user (you can check this with the
2256 <command>smbstatus</command> command on Samba) do this from the
2257 Windows workstation:
2258 </para>
2259
2260 <itemizedlist>
2261 <listitem><para>Open <emphasis>Network
2262 Neighbourhood</emphasis></para></listitem>
2263
2264 <listitem><para>Browse to Samba server</para></listitem>
2265
2266 <listitem><para>Open its <emphasis>Printers and
2267 Faxes</emphasis> folder</para></listitem>
2268
2269 <listitem><para>Highlight and right-click the printer</para></listitem>
2270
2271 <listitem><para>Select <emphasis>Connect...</emphasis> (for WinNT4/2K
2272 it is possibly <emphasis>Install...</emphasis>)</para></listitem>
2273 </itemizedlist>
2274
2275 <para>
2276 A new printer (named <replaceable>printername</replaceable> on
2277 samba-server) should now have appeared in your
2278 <emphasis>local</emphasis> Printer folder (check <emphasis>Start --
2279 Settings -- Control Panel -- Printers and Faxes</emphasis>).
2280 </para>
2281
2282 <para>
2283 Most likely you are now tempted to try and print a test page.  After
2284 all, you now can open the printer properties and on the "General" tab,
2285 there is a button offering to do just that. But chances are that you
2286 get an error message saying <computeroutput>Unable to print Test
2287 Page</computeroutput>. The reason might be that there is not yet a
2288 valid Device Mode set for the driver, or that the "Printer Driver
2289 Data" set is still incomplete.
2290 </para>
2291
2292 <para>
2293 You must now make sure that a valid "Device Mode" is set for the
2294 driver. Don't fear -- we will explain now what that means.
2295 </para>
2296 </sect2>
2297
2298 <sect2>
2299 <title>IMPORTANT! Setting Device Modes on new Printers</title>
2300
2301 <para>
2302 In order for a printer to be truly usable by a Windows NT/2K/XP
2303 client, it must possess:
2304 </para>
2305
2306 <itemizedlist>
2307 <listitem><para>a valid <emphasis>Device Mode</emphasis> generated by
2308 the driver for the printer (defining things like paper size,
2309 orientation and duplex settings), and</para></listitem>
2310
2311 <listitem><para>a complete set of
2312 <emphasis>Printer Driver Data</emphasis> generated by the
2313 driver.</para></listitem>
2314 </itemizedlist>
2315
2316 <para>
2317 If either one of these is incomplete, the clients can produce less
2318 than optimal output at best. In the worst cases, unreadable garbage or
2319 nothing at all comes from the printer or they produce a harvest of
2320 error messages when attempting to print. Samba stores the named values
2321 and all printing related info in its internal TDB database files
2322 <filename>(ntprinters.tdb</filename>,
2323 <filename>ntdrivers.tdb</filename>, <filename>printing.tdb</filename>
2324 and <filename>ntforms.tdb</filename>).
2325 </para>
2326
2327 <para>
2328 What do these two words stand for? Basically, the Device Mode and the
2329 set of Printer Driver Data is a collection of settings for all print
2330 queue properties, initialized in a sensible way. Device Modes and
2331 Printer Driver Data should initially be set on the print server (that is
2332 here: the Samba host) to healthy values so that the clients can start
2333 to use them immediately. How do we set these initial healthy values?
2334 This can be achieved by accessing the drivers remotely from an NT (or
2335 2k/XP) client, as is discussed in the next paragraphs.
2336 </para>
2337
2338 <para>
2339 Be aware, that a valid Device Mode can only be initiated by a
2340 "<emphasis>printer admin</emphasis>", or root (the reason should be
2341 obvious). Device Modes can only correctly be set by executing the
2342 printer driver program itself. Since Samba can not execute this Win32
2343 platform driver code, it sets this field initially to NULL (which is
2344 not a valid setting for clients to use). Fortunately, most drivers
2345 generate themselves the Printer Driver Data that is needed, when they
2346 are uploaded to the <parameter>[print$]</parameter> share with the
2347 help of the APW or rpcclient.
2348 </para>
2349
2350 <para>
2351 The generation and setting of a first valid Device Mode however
2352 requires some "tickling" from a client, to set it on the Samba
2353 server. The easiest means of doing so is to simply change the page
2354 orientation on the server's printer. This "executes" enough of the
2355 printer driver program on the client for the desired effect to happen,
2356 and feeds back the new Device Mode to our Samba server. You can use the
2357 native Windows NT/2K/XP printer properties page from a Window client
2358 for this:
2359 </para>
2360
2361 <itemizedlist>
2362 <listitem><para>Browse the "Network Neighbourhood"</para></listitem>
2363
2364 <listitem><para>Find the Samba server</para></listitem>
2365
2366 <listitem><para>Open the Samba server's <emphasis>Printers and
2367 Faxes</emphasis> folder</para></listitem>
2368
2369 <listitem><para>Highlight the shared printer in question</para></listitem>
2370
2371 <listitem><para>Right-click the printer (you may already be here, if you
2372 followed the last section's description)</para></listitem>
2373
2374 <listitem><para>At the bottom of the context menu select
2375 "Properties...." (if the menu still offers the "Connect..." entry
2376 further above, you need to click that one first to achieve the driver
2377 installation as shown in the last section)</para></listitem>
2378
2379 <listitem><para>Go to the "Advanced" tab; click on "Printing
2380 Defaults..."</para></listitem>
2381
2382 <listitem><para>Change the "Portrait" page setting to "Landscape" (and
2383 back)</para></listitem>
2384
2385 <listitem><para>(Oh, and make sure to <emphasis>apply</emphasis>
2386 changes between swapping the page orientation to cause the change to
2387 actually take effect...).</para></listitem>
2388
2389 <listitem><para>While you're at it, you may optionally also want to
2390 set the desired printing defaults here, which then apply to all future
2391 client driver installations on the remaining from now
2392 on.</para></listitem>
2393 </itemizedlist>
2394
2395 <para>
2396 This procedure has executed the printer driver program on the client
2397 platform and fed back the correct Device Mode to Samba, which now
2398 stored it in its TDB files. Once the driver is installed on the
2399 client, you can follow the analogous steps by accessing the
2400 <emphasis>local</emphasis> "Printers" folder too if you are a Samba
2401 printer admin user. From now on printing should work as expected.
2402 </para>
2403
2404 <para>
2405 Samba also includes a service level parameter name <parameter>default
2406 devmode</parameter> for generating a default Device Mode for a
2407 printer. Some drivers will function well with Samba's default set of
2408 properties. Others may crash the client's spooler service. So use this
2409 parameter with caution. It is always better to have the client
2410 generate a valid device mode for the printer and store it on the
2411 server for you.
2412 </para>
2413 </sect2>
2414
2415 <sect2>
2416 <title>Further Client Driver Install Procedures</title>
2417
2418 <para>
2419 Every further driver may be done by any user, along the lines
2420 described above: Browse network, open printers folder on Samba server,
2421 right-click printer and choose "Connect...". Once this completes
2422 (should be not more than a few seconds, but could also take a minute,
2423 depending on network conditions), you should find the new printer in
2424 your client workstation local <emphasis>Printers and
2425 Faxes</emphasis> folder.
2426 </para>
2427
2428 <para>
2429 You can also open your local "Printers and Faxes" folder by using this
2430 command on Windows 2000 and Windows XP Professional workstations:
2431 </para>
2432
2433 <para><screen>
2434 rundll32 shell32.dll,SHHelpShortcuts_RunDLL PrintersFolder
2435 </screen></para>
2436
2437 <para>
2438 or this command on Windows NT 4.0 workstations:
2439 </para>
2440
2441 <para><screen>
2442 rundll32 shell32.dll,Control_RunDLL MAIN.CPL @2
2443 </screen></para>
2444
2445 <para>
2446 You can enter the commands either inside a "DOS box" window or in the
2447 "Run command..." field from the "Start" menu.
2448 </para>
2449 </sect2>
2450
2451 <sect2>
2452 <title>Always make first Client Connection as root or "printer admin"</title>
2453
2454 <para>
2455 After you installed the driver on the Samba server (in its
2456 <parameter>[print$]</parameter> share, you should always make sure
2457 that your first client installation completes correctly. Make it a habit for
2458 yourself to build that the very first connection from a client as
2459 "printer admin". This is to make sure that:
2460 </para>
2461
2462 <itemizedlist>
2463
2464 <listitem><para> a first valid <emphasis>Device Mode</emphasis> is
2465 really initialized (see above for more explanation details), and
2466 that</para></listitem>
2467
2468 <listitem><para> the default print settings of your printer for all
2469 further client installations are as you want them</para></listitem>
2470 </itemizedlist>
2471
2472 <para>
2473 Do this by changing the orientation to landscape, click
2474 <emphasis>Apply</emphasis>, and then change it back again. Then modify
2475 the other settings (for example, you don't want the default media size
2476 set to <emphasis>Letter</emphasis>, when you are all using
2477 <emphasis>A4</emphasis>, right? You may want to set the printer for
2478 <emphasis>duplex</emphasis> as the default; etc.).
2479 </para>
2480
2481 <para>
2482 To connect as root to a Samba printer, try this command from a Windows
2483 2K/XP DOS box command prompt:
2484 </para>
2485
2486 <para><screen>
2487 runas /netonly /user:root "rundll32 printui.dll,PrintUIEntry /p /t3 /n \\SAMBA-SERVER\printername"
2488 </screen></para>
2489
2490 <para>
2491 You will be prompted for root's Samba-password; type it, wait a few
2492 seconds, click on "<emphasis>Printing Defaults...</emphasis>" and
2493 proceed to set the job options as should be used as defaults by all
2494 clients. Alternatively, instead of root you can name one other member
2495 of the<emphasis>printer admins</emphasis> from the
2496 <filename>smb.conf</filename> setting.
2497 </para>
2498
2499 <para>
2500 Now all the other users downloading and installing the driver
2501 the same way (called <emphasis>Point'n'Print</emphasis>) will
2502 have the same defaults set for them. If you miss this step you'll
2503 get a lot of helpdesk calls from your users. But maybe you like to
2504 talk to people.... ;-)
2505 </para>
2506 </sect2>
2507 </sect1>
2508
2509 <sect1>
2510 <title>Other Gotchas</title>
2511
2512 <para>
2513 Your driver is installed. It is ready for
2514 <emphasis>Point'n'Print</emphasis> installation by the clients
2515 now. You <emphasis>may</emphasis> have tried to download and use it
2516 onto your first client machine now. But wait... let's make you
2517 acquainted first with a few tips and tricks you may find useful.  For
2518 example, suppose you didn't manage to "set the defaults" on the
2519 printer, as advised in the preceeding paragraphs? And your users
2520 complain about various issues (such as <quote>We need to set the paper
2521 size for each job from Letter to A4 and it won't store it!</quote>)
2522 </para>
2523
2524 <sect2>
2525 <title>Setting Default Print Options for the Client Drivers</title>
2526
2527 <para>
2528 The last sentence might be viewed with mixed feelings by some users and
2529 admins. They have struggled for hours and hours and couldn't arrive at
2530 a point were their settings seemed to be saved.  It is not their
2531 fault. The confusing thing is this: in the multi-tabbed dialog that pops
2532 up when you right-click the printer name and select 
2533 <emphasis>Properties...</emphasis>, you can arrive at two identically
2534 looking dialogs, each claiming that they help you to set printer options,
2535 in three different ways. Here is the definite answer to the "Samba
2536 Default Driver Setting FAQ":
2537 </para>
2538
2539 <formalpara><title><quote>I can't set and save default print options
2540 for all users on Win2K/XP! Why not?</quote></title>
2541
2542 <para>
2543 How are you doing it? I bet the wrong way.... (it is not very
2544 easy to find out, though). There are 3 different ways to bring you to
2545 a dialog that <emphasis>seems</emphasis> to set everything. All three
2546 dialogs <emphasis>look</emphasis> the same. Only one of them
2547 <emphasis>does</emphasis> what you intend.
2548 <emphasis>Important:</emphasis> you need to be Administrator or Print
2549 Administrator to do this for all users. Here is how I reproduce it in
2550 on XP Professional:
2551
2552 <orderedlist numeration="upperalpha">
2553
2554 <listitem><para>The first "wrong" way:
2555
2556 <orderedlist numeration="arabic">
2557 <listitem><para>Open the <emphasis>Printers</emphasis>
2558 folder.</para></listitem>
2559
2560 <listitem><para>Right-click on the printer
2561 (<emphasis>remoteprinter on cupshost</emphasis>) and
2562 select in context menu <emphasis>Printing
2563 Preferences...</emphasis></para></listitem>
2564
2565 <listitem><para>Look at this dialog closely and remember what it looks
2566 like.</para></listitem>
2567 </orderedlist>
2568 </para>
2569 </listitem>
2570
2571 <listitem><para>The second "wrong" way:
2572
2573 <orderedlist numeration="arabic">
2574 <listitem><para>Open the "<emphasis>Printers</emphasis>"
2575 folder.</para></listitem>
2576
2577 <listitem><para>Right-click on the printer (<emphasis>remoteprinter on
2578 cupshost</emphasis>) and select in the context menu
2579 <emphasis>Properties</emphasis></para></listitem>
2580
2581 <listitem><para>Click on the <emphasis>General</emphasis>
2582 tab</para></listitem>
2583
2584 <listitem><para>Click on the button <emphasis>Printing
2585 Preferences...</emphasis></para></listitem>
2586
2587 <listitem><para>A new dialog opens. Keep this dialog open and go back
2588 to the parent dialog.</para></listitem>
2589 </orderedlist>
2590 </para>
2591 </listitem>
2592
2593 <listitem><para>The third, the "correct" way: (should you do
2594 this from the beginning, just carry out steps 1. and 2. from second
2595 "way" above)
2596
2597 <orderedlist numeration="arabic">
2598 <listitem><para>Click on the <emphasis>Advanced</emphasis>
2599 tab. (Hmmm... if everything is "Grayed Out", then you are not logged
2600 in as a user with enough privileges).</para></listitem>
2601
2602 <listitem><para>Click on the "<emphasis>Printing
2603 Defaults...</emphasis>" button.</para></listitem>
2604
2605 <listitem><para>On any of the two new tabs, click on the
2606 <emphasis>Advanced...</emphasis>
2607 button.</para></listitem>
2608
2609 <listitem><para>A new dialog opens. Compare this one to the other,
2610 identical looking one from "B.5" or A.3".</para></listitem>
2611 </orderedlist>
2612 </para>
2613 </listitem>
2614 </orderedlist>
2615
2616 Do you see any difference in the two settings dialogs? I don't
2617 either. However, only the last one, which you arrived at with steps
2618 C.1.-6. will permanently save any settings which will then become the
2619 defaults for new users. If you want all clients to have the same
2620 defaults, you need to conduct these steps as administrator
2621 (<emphasis>printer admin</emphasis> in <filename>smb.conf</filename>)
2622 <emphasis>before</emphasis> a client downloads the driver (the clients
2623 can later set their own <emphasis>per-user defaults</emphasis> by
2624 following the procedures<emphasis>A.</emphasis>
2625 or<emphasis>B.</emphasis> above...). (This is new: Windows 2000 and
2626 Windows XP allow <emphasis>per-user</emphasis> default settings and
2627 the ones the administrator gives them, before they set up their own).
2628 The "parents" of the identically looking dialogs have a slight
2629 difference in their window names: one is called
2630 <computeroutput>Default Print Values for Printer Foo on Server
2631 Bar"</computeroutput> (which is the one you need) and the other is
2632 called "<computeroutput>Print Settings for Printer Foo on Server
2633 Bar</computeroutput>". The last one is the one you arrive at when you
2634 right-click on the printer and select <emphasis>Print
2635 Settings...</emphasis>. This is the one what you were
2636 taught to use back in the days of Windows NT! So it is only natural to
2637 try the same way with Win2k or WinXP. You wouldn't dream
2638 that there is now a different "clicking path" to arrive at an
2639 identically looking, but functionally different dialog to set defaults
2640 for all users!
2641 </para></formalpara>
2642
2643 <tip><para>Try (on Win2000 and WinXP) to run this command (as a user
2644 with the right privileges):
2645 </para>
2646
2647 <para><screen>
2648 rundll32 printui.dll,PrintUIEntry /p /t3 /n\\SAMBA-SERVER\printersharename
2649 </screen></para>
2650
2651 <para>
2652 to see the tab with the <emphasis>Printing Defaults...</emphasis>
2653 button (the one you need). Also run this command:
2654 </para>
2655
2656 <para><screen>
2657 rundll32 printui.dll,PrintUIEntry /p /t0 /n\\SAMBA-SERVER\printersharename
2658 </screen></para>
2659
2660 <para>
2661 to see the tab with the <emphasis>Printing Preferences...</emphasis>
2662 button (the one which doesn't set system-wide defaults). You can
2663 start the commands from inside a DOS box" or from the <emphasis>Start
2664 -- Run...</emphasis> menu.
2665 </para>
2666 </tip>
2667
2668 </sect2>
2669
2670 <sect2>
2671 <title>Supporting large Numbers of Printers</title>
2672
2673 <para>
2674 One issue that has arisen during the recent development phase of Samba
2675 is the need to support driver downloads for 100's of printers. Using
2676 Windows NT APW here is somewhat awkward (to say the least). If you
2677 don't want to acquire RSS pains from such the printer installation
2678 clicking orgy alone, you need to think about a non-interactive script.
2679 </para>
2680
2681 <para>
2682 If more than one printer is using the same driver, the
2683 <command>rpcclient setdriver</command> command can be used to set the
2684 driver associated with an installed queue. If the driver is uploaded
2685 to <parameter>[print$]</parameter> once and registered with the
2686 printing TDBs, it can be used by multiple print queues. In this case
2687 you just need to repeat the <command>setprinter</command> subcommand
2688 of <command>rpcclient</command> for every queue (without the need to
2689 conduct the <command>adddriver</command> again and again). The
2690 following is an example of how this could be accomplished:
2691 </para>
2692
2693 <para><screen>
2694
2695  ----------------------------------------------------------------------------------
2696  $ rpcclient SAMBA-CUPS -U root%secret -c 'enumdrivers'
2697  cmd = enumdrivers
2698  
2699  [Windows NT x86]
2700  Printer Driver Info 1:
2701    Driver Name: [infotec  IS 2075 PCL 6]
2702  
2703  Printer Driver Info 1:
2704    Driver Name: [DANKA InfoStream]
2705  
2706  Printer Driver Info 1:
2707    Driver Name: [Heidelberg Digimaster 9110 (PS)]
2708  
2709  Printer Driver Info 1:
2710    Driver Name: [dm9110]
2711
2712  Printer Driver Info 1:
2713    Driver Name: [myphantasydrivername]
2714
2715  [....]
2716  ----------------------------------------------------------------------------------
2717  
2718 ----------------------------------------------------------------------------------
2719  $ rpcclient SAMBA-CUPS -U root%secret -c 'enumprinters'
2720  cmd = enumprinters
2721    flags:[0x800000]
2722    name:[\\SAMBA-CUPS\dm9110]
2723    description:[\\SAMBA-CUPS\dm9110,,110ppm HiVolume DANKA Stuttgart]
2724    comment:[110 ppm HiVolume DANKA Stuttgart]
2725  [....]
2726  ----------------------------------------------------------------------------------
2727
2728 ----------------------------------------------------------------------------------
2729  $ rpcclient SaMbA-cUpS -U root%secret -c 'setdriver dm9110 "Heidelberg Digimaster 9110 (PS)"'
2730  cmd = setdriver dm9110 Heidelberg Digimaster 9110 (PPD)
2731  Successfully set dm9110 to driver Heidelberg Digimaster 9110 (PS).
2732  ----------------------------------------------------------------------------------
2733  
2734 ----------------------------------------------------------------------------------
2735  $ rpcclient samba-cups -U root%secret -c 'enumprinters'
2736  cmd = enumprinters
2737    flags:[0x800000]
2738    name:[\\SAMBA-CUPS\dm9110]
2739    description:[\\SAMBA-CUPS\dm9110,Heidelberg Digimaster 9110 (PS),110ppm HiVolume DANKA Stuttgart]
2740    comment:[110ppm HiVolume DANKA Stuttgart]
2741  [....]
2742  ----------------------------------------------------------------------------------
2743
2744 ----------------------------------------------------------------------------------
2745  $ rpcclient SaMbA-cUpS -U root%secret -c 'setdriver dm9110 myphantasydrivername'
2746  cmd = setdriver dm9110 myphantasydrivername
2747  Successfully set dm9110 to myphantasydrivername.
2748  ----------------------------------------------------------------------------------
2749  
2750 ----------------------------------------------------------------------------------
2751  $ rpcclient samba-cups -U root%secret -c 'enumprinters'
2752  cmd = enumprinters
2753    flags:[0x800000]
2754    name:[\\SAMBA-CUPS\dm9110]
2755    description:[\\SAMBA-CUPS\dm9110,myphantasydrivername,110ppm HiVolume DANKA Stuttgart]
2756    comment:[110ppm HiVolume DANKA Stuttgart]
2757  [....]
2758  ----------------------------------------------------------------------------------
2759
2760 </screen></para>
2761
2762 <para>
2763 It may be not easy to recognize: but the first call to
2764 <command>enumprinters</command> showed the "dm9110" printer with an
2765 empty string where the driver should have been listed (between the 2
2766 commas in the "description" field). After the
2767 <command>setdriver</command> command succeeded, all is well.  (The
2768 CUPS Printing chapter has more info about the installation of printer
2769 drivers with the help of <command>rpccclient</command>).
2770 </para>
2771 </sect2>
2772
2773 <sect2>
2774 <title>Adding new Printers with the Windows NT APW</title>
2775
2776 <para>
2777 By default, Samba exhibits all printer shares defined in
2778 <emphasis><filename>smb.conf</filename></emphasis> in the
2779 <emphasis>Printers...</emphasis> folder. Also located in this folder
2780 is the Windows NT Add Printer Wizard icon. The APW will be shown only
2781 if:
2782 </para>
2783
2784 <itemizedlist>
2785 <listitem><para>...the connected user is able to successfully execute
2786 an <command>OpenPrinterEx(\\server)</command> with administrative
2787 privileges (i.e. root or <emphasis>printer admin</emphasis>).
2788 </para>
2789
2790 <tip><para> Try this from a Windows 2K/XP DOS box command prompt:
2791 </para>
2792
2793 <para><screen>
2794 runas /netonly /user:root rundll32 printui.dll,PrintUIEntry /p /t0 /n \\SAMBA-SERVER\printersharename
2795 </screen></para>
2796
2797 <para>
2798 and click on <emphasis>Printing Preferences...</emphasis>
2799 </para></tip></listitem>
2800
2801 <listitem><para>...<filename>smb.conf</filename> contains the setting
2802 <emphasis>show add printer wizard = yes</emphasis> (the
2803 default).</para></listitem>
2804 </itemizedlist>
2805
2806 <para>
2807 The APW can do various things:
2808 </para>
2809
2810 <itemizedlist>
2811 <listitem><para>upload a new driver to the Samba
2812 <parameter>[print$]</parameter> share;</para></listitem>
2813
2814 <listitem><para>associate an uploaded driver with an existing (but
2815 still "driverless") print queue;</para></listitem>
2816
2817 <listitem><para>exchange the currently used driver for an existing
2818 print queue with one that has been uploaded before;</para></listitem>
2819
2820 <listitem><para>add an entirely new printer to the Samba host (only in
2821 conjunction with a working <parameter>add printer command</parameter>;
2822 a corresponding <parameter>delete printer command</parameter> for
2823 removing entries from the <emphasis>Printers...</emphasis> folder
2824 may be provided too)</para></listitem>
2825 </itemizedlist>
2826
2827 <para>
2828 The last one (add a new printer) requires more effort than the
2829 previous ones. In order to use the APW to successfully add a printer
2830 to a Samba server, the <parameter>add printer command</parameter> must
2831 have a defined value. The program hook must successfully add the
2832 printer to the Unix print system (i.e. to
2833 <filename>/etc/printcap</filename>,
2834 <filename>/etc/cups/printers.conf</filename> or other appropriate
2835 files) and to <filename>smb.conf</filename> if necessary.
2836 </para>
2837
2838 <para>
2839 When using the APW from a client, if the named printer share does not
2840 exist, smbd will execute the <parameter>add printer
2841 command</parameter> and reparse to the <filename>smb.conf</filename>
2842 to attempt to locate the new printer share. If the share is still not
2843 defined, an error of <computeroutput>Access Denied</computeroutput> is
2844 returned to the client.  Note that the <parameter>add printer
2845 command</parameter> is executed under the context of the connected
2846 user, not necessarily a root account. A <parameter>map to guest = bad
2847 user</parameter> may have connected you unwittingly under the wrong
2848 privilege; you should check it by using the
2849 <command>smbstatus</command> command.
2850 </para>
2851 </sect2>
2852
2853 <sect2>
2854 <title>Weird Error Message <errorname>Cannot connect under a
2855 different Name</errorname></title>
2856
2857 <para>
2858 Once you are connected with the wrong credentials, there is no means
2859 to reverse the situation other than to close all Explorer windows, and
2860 perhaps reboot.
2861 </para>
2862
2863 <itemizedlist>
2864 <listitem><para>The <command>net use \\SAMBA-SERVER\sharename
2865 /user:root</command> gives you an error message: <computeroutput>Multiple
2866 connections to a server or a shared resource by the same user
2867 utilizing the several user names are not allowed. Disconnect all
2868 previous connections to the server, resp. the shared resource, and try
2869 again.</computeroutput></para></listitem>
2870
2871 <listitem><para>Every attempt to "connect a network drive" to
2872 <filename>\\SAMBASERVER\\print$</filename> to z: is countered by the
2873 pertinacious message. <computeroutput>This network folder is currently
2874 connected under different credentials (username and password).
2875 Disconnect first any existing connection to this network share in
2876 order to connect again under a different username and
2877 password</computeroutput>.</para></listitem>
2878 </itemizedlist>
2879
2880 <para>
2881 So you close all connections. You try again. You get the same
2882 message. You check from the Samba side, using
2883 <command>smbstatus</command>. Yes, there are some more
2884 connections. You kill them all. The client still gives you the same
2885 error message. You watch the smbd.log file on a very high debug level
2886 and try re-connect. Same error message, but not a single line in the
2887 log. You start to wonder if there was a connection attempt at all. You
2888 run ethereal and tcpdump while you try to connect. Result: not a
2889 single byte goes on the wire. Windows still gives the error
2890 message. You close all Explorer Windows and start it again. You try to
2891 connect - and this times it works!  Windows seems to cache connection
2892 info somewhere and doesn't keep it up to date (if you are unlucky you
2893 might need to reboot to get rid of the error message).
2894 </para>
2895 </sect2>
2896
2897 <sect2>
2898 <title>Be careful when assembling Driver Files</title>
2899
2900 <para>
2901 You need to be very careful when you take notes about the files and
2902 belonging to a particular driver. Don't confuse the files for driver
2903 version "0" (for Win95/98/ME, going into
2904 <filename>[print$]/WIN/0/</filename>), driver version "2" (Kernel Mode
2905 driver for WinNT, going into <filename>[print$]/W32X86/2/</filename>
2906 <emphasis>may</emphasis> be used on Win2K/XP too), and driver version
2907 "3" (non-Kernel Mode driver going into
2908 <filename>[print$]/W32X86/3/</filename> <emphasis>can not</emphasis>
2909 be used on WinNT). Very often these different driver versions contain
2910 files carrying the same name; but still the files are very different!
2911 Also, if you look at them from the Windows Explorer (they reside in
2912 "<filename>%WINDOWS%\system32\spool\drivers\W32X86\</filename>") you
2913 will probably see names in capital letters, while an "enumdrivers"
2914 command from Samba would show mixed or lower case letters. So it is
2915 easy to confuse them. If you install them manually using
2916 <command>rpcclient</command> and subcommands, you may even succeed
2917 without an error message. Only later, when you try install on a
2918 client, you will encounter error messages like <computeroutput>This
2919 server has no appropriate driver for the printer</computeroutput>.
2920 </para>
2921
2922 <para>
2923 Here is an example. You are invited to look very closely at the
2924 various files, compare their names and their spelling, and discover
2925 the differences in the composition of the version-2 and -3 sets
2926 Note: the version-0 set contained 40 (!)
2927 <parameter>Dependentfiles</parameter>, so I left it out for space
2928 reasons:
2929 </para>
2930
2931 <para><screen>
2932
2933  kde4@kde-bitshop:# rpcclient -U 'Administrator%xxxx' -c 'enumdrivers 3' 10.160.50.8 
2934
2935  Printer Driver Info 3:
2936          Version: [3]
2937          Driver Name: [Canon iR8500 PS3]
2938          Architecture: [Windows NT x86]
2939          Driver Path: [\\10.160.50.8\print$\W32X86\3\cns3g.dll]
2940          Datafile: [\\10.160.50.8\print$\W32X86\3\iR8500sg.xpd]
2941          Configfile: [\\10.160.50.8\print$\W32X86\3\cns3gui.dll]
2942          Helpfile: [\\10.160.50.8\print$\W32X86\3\cns3g.hlp]
2943  
2944          Dependentfiles: [\\10.160.50.8\print$\W32X86\3\aucplmNT.dll]
2945          Dependentfiles: [\\10.160.50.8\print$\W32X86\3\ucs32p.dll]
2946          Dependentfiles: [\\10.160.50.8\print$\W32X86\3\tnl32.dll]
2947          Dependentfiles: [\\10.160.50.8\print$\W32X86\3\aussdrv.dll]
2948          Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cnspdc.dll]
2949          Dependentfiles: [\\10.160.50.8\print$\W32X86\3\aussapi.dat]
2950          Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cns3407.dll]
2951          Dependentfiles: [\\10.160.50.8\print$\W32X86\3\CnS3G.cnt]
2952          Dependentfiles: [\\10.160.50.8\print$\W32X86\3\NBAPI.DLL]
2953          Dependentfiles: [\\10.160.50.8\print$\W32X86\3\NBIPC.DLL]
2954          Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cpcview.exe]
2955          Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cpcdspl.exe]
2956          Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cpcedit.dll]
2957          Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cpcqm.exe]
2958          Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cpcspl.dll]
2959          Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cfine32.dll]
2960          Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cpcr407.dll]
2961          Dependentfiles: [\\10.160.50.8\print$\W32X86\3\Cpcqm407.hlp]
2962          Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cpcqm407.cnt]
2963          Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cns3ggr.dll]
2964  
2965          Monitorname: []
2966          Defaultdatatype: []
2967
2968  Printer Driver Info 3:
2969          Version: [2]
2970          Driver Name: [Canon iR5000-6000 PS3]
2971          Architecture: [Windows NT x86]
2972          Driver Path: [\\10.160.50.8\print$\W32X86\2\cns3g.dll]
2973          Datafile: [\\10.160.50.8\print$\W32X86\2\IR5000sg.xpd]
2974          Configfile: [\\10.160.50.8\print$\W32X86\2\cns3gui.dll]
2975          Helpfile: [\\10.160.50.8\print$\W32X86\2\cns3g.hlp]
2976  
2977          Dependentfiles: [\\10.160.50.8\print$\W32X86\2\AUCPLMNT.DLL]
2978          Dependentfiles: [\\10.160.50.8\print$\W32X86\2\aussdrv.dll]
2979          Dependentfiles: [\\10.160.50.8\print$\W32X86\2\cnspdc.dll]
2980          Dependentfiles: [\\10.160.50.8\print$\W32X86\2\aussapi.dat]
2981          Dependentfiles: [\\10.160.50.8\print$\W32X86\2\cns3407.dll]
2982          Dependentfiles: [\\10.160.50.8\print$\W32X86\2\CnS3G.cnt]
2983          Dependentfiles: [\\10.160.50.8\print$\W32X86\2\NBAPI.DLL]
2984          Dependentfiles: [\\10.160.50.8\print$\W32X86\2\NBIPC.DLL]
2985          Dependentfiles: [\\10.160.50.8\print$\W32X86\2\cns3gum.dll]
2986  
2987          Monitorname: [CPCA Language Monitor2]
2988          Defaultdatatype: []
2989
2990 </screen></para>
2991
2992 <para>
2993 If we write the "version 2" files and the "version 3" files
2994 into different text files and compare the result, we see this
2995 picture:
2996 </para>
2997
2998 <para><screen>
2999 <![CDATA[
3000  kde4@kde-bitshop:# sdiff 2-files 3-files
3001
3002  cns3g.dll                     cns3g.dll
3003  iR8500sg.xpd                  iR8500sg.xpd
3004  cns3gui.dll                   cns3gui.dll
3005  cns3g.hlp                     cns3g.hlp
3006  AUCPLMNT.DLL                | aucplmNT.dll
3007                              > ucs32p.dll
3008                              > tnl32.dll
3009  aussdrv.dll                   aussdrv.dll
3010  cnspdc.dll                    cnspdc.dll
3011  aussapi.dat                   aussapi.dat
3012  cns3407.dll                   cns3407.dll
3013  CnS3G.cnt                     CnS3G.cnt
3014  NBAPI.DLL                     NBAPI.DLL
3015  NBIPC.DLL                     NBIPC.DLL
3016  cns3gum.dll                 | cpcview.exe
3017                              > cpcdspl.exe 
3018                              > cpcqm.exe
3019                              > cpcspl.dll
3020                              > cfine32.dll
3021                              > cpcr407.dll
3022                              > Cpcqm407.hlp
3023                              > cpcqm407.cnt
3024                              > cns3ggr.dll
3025 ]]>
3026
3027
3028 </screen></para>
3029
3030 <para>
3031 Don't be fooled though! Driver files for each version with identical
3032 names may be different in their content, as you can see from this size
3033 comparison:
3034 </para>
3035
3036 <para><screen>
3037
3038  kde4@kde-bitshop:#  for i in cns3g.hlp cns3gui.dll cns3g.dll; do                  \
3039                             smbclient //10.160.50.8/print\$ -U 'Administrator%xxxx' \
3040                                -c "cd W32X86/3; dir $i; cd .. ; cd 2; dir $i";      \
3041                             done
3042
3043   CNS3G.HLP               A   122981  Thu May 30 02:31:00 2002
3044   CNS3G.HLP               A    99948  Thu May 30 02:31:00 2002
3045
3046   CNS3GUI.DLL             A  1805824  Thu May 30 02:31:00 2002
3047   CNS3GUI.DLL             A  1785344  Thu May 30 02:31:00 2002
3048
3049   CNS3G.DLL               A  1145088  Thu May 30 02:31:00 2002
3050   CNS3G.DLL               A    15872  Thu May 30 02:31:00 2002
3051
3052 </screen></para>
3053
3054 <para>
3055 In my example were even more differences than shown here.  Conclusion:
3056 you must be very careful to select the correct driver files for each
3057 driver version. Don't rely on the names alone. Don't interchange files
3058 belonging to different driver versions.
3059 </para>
3060 </sect2>
3061
3062 <sect2>
3063 <title>Samba and Printer Ports</title>
3064
3065 <para>
3066 Windows NT/2000 print servers associate a port with each
3067 printer. These normally take the form of <filename>LPT1:</filename>,
3068 <filename>COM1:</filename>, <filename>FILE:</filename>, etc. Samba
3069 must also support the concept of ports associated with a printer. By
3070 default, only one printer port, named "Samba Printer Port", exists on
3071 a system. Samba does not really need such a "port" in order to print;
3072 it rather is a requirement of Windows clients.  They insist on being
3073 told about an available port when they request this info, otherwise
3074 they throw an error message at you. So Samba fakes the port
3075 information to keep the Windows clients happy.
3076 </para>
3077
3078 <para>
3079 Note that Samba does not support the concept of "Printer Pooling"
3080 internally either. Printer Pooling assigns a logical printer to
3081 multiple ports as a form of load balancing or fail over.
3082 </para>
3083
3084 <para>
3085 If you require that multiple ports be defined for some reason or
3086 another (<quote>My users and my Boss should not know that they are
3087 working with Samba</quote>), <filename>smb.conf</filename> possesses a
3088 <parameter>enumports command</parameter> which can be used to define
3089 an external program that generates a listing of ports on a system.
3090 </para>
3091 </sect2>
3092
3093 <sect2>
3094 <title>Avoiding the most common Misconfigurations of the Client Driver</title>
3095
3096 <para>
3097 So - printing works, but there are still problems. Most jobs print
3098 well, some don't print at all. Some jobs have problems with fonts,
3099 which don't look good at all. Some jobs print fast, and some are
3100 dead-slow. We can't cover it all; but we want to encourage you to read
3101 the little paragraph about "Avoiding the wrong PostScript Driver
3102 Settings" in the CUPS Printing part of this document.
3103 </para>
3104 </sect2>
3105 </sect1>
3106
3107 <sect1>
3108 <title>The Imprints Toolset</title>
3109
3110 <para>
3111 The Imprints tool set provides a UNIX equivalent of the
3112 Windows NT Add Printer Wizard. For complete information, please
3113 refer to the Imprints web site
3114 at<ulink url="http://imprints.sourceforge.net/">http://imprints.sourceforge.net/</ulink>
3115 as well as the documentation included with the imprints source
3116 distribution. This section will only provide a brief introduction
3117 to the features of Imprints.
3118 </para>
3119
3120 <formalpara><title>ATTENTION! MAINTAINER REQUIRED</title>
3121
3122 <para>
3123 Unfortunately, the Imprints toolset is no longer maintained. As of
3124 December, 2000, the project is in need of a new maintainer. The most
3125 important skill to have is decent perl coding and an interest in
3126 MS-RPC based printing using Samba. If you wish to volunteer, please
3127 coordinate your efforts on the samba-technical mailing list. The
3128 toolset is still in usable form; but only for a series of older
3129 printer models, where there are prepared packages to use. Packages for
3130 more up to date print devices are needed if Imprints should have a
3131 future.</para></formalpara>
3132
3133 <sect2>
3134 <title>What is Imprints?</title>
3135
3136 <para>
3137 Imprints is a collection of tools for supporting these goals:
3138 </para>
3139
3140 <itemizedlist>
3141 <listitem><para>Providing a central repository information regarding
3142 Windows NT and 95/98 printer driver packages</para></listitem>
3143
3144 <listitem><para>Providing the tools necessary for creating the
3145 Imprints printer driver packages.</para></listitem>
3146
3147 <listitem><para>Providing an installation client w