Very large number of markup fixes, layout updates, etc.
[samba.git] / docs / docbook / projdoc / printer_driver2.xml
1 <chapter id="printing">
2
3 <chapterinfo>
4         &author.jerry;
5         <author>
6                 <firstname>Patrick</firstname><surname>Powell</surname>
7                 <affiliation>
8                         <address><email>papowell@lprng.org</email></address>
9                 </affiliation>
10         </author>
11         <pubdate> 3 May 2001 </pubdate>
12 </chapterinfo>
13
14 <title>Printing Support</title>
15
16 <sect1>
17 <title>Introduction</title>
18         
19 <para>Beginning with the 2.2.0 release, Samba supports 
20 the native Windows NT printing mechanisms implemented via 
21 MS-RPC (i.e. the SPOOLSS named pipe).  Previous versions of 
22 Samba only supported LanMan printing calls.</para>
23
24 <para>The additional functionality provided by the new 
25 SPOOLSS support includes:</para>
26         
27 <itemizedlist>
28         <listitem><para>Support for downloading printer driver 
29         files to Windows 95/98/NT/2000 clients upon demand.
30         </para></listitem>
31         
32         <listitem><para>Uploading of printer drivers via the 
33         Windows NT Add Printer Wizard (APW) or the 
34         Imprints tool set (refer to <ulink 
35         url="http://imprints.sourceforge.net">http://imprints.sourceforge.net</ulink>). 
36         </para></listitem>
37                 
38         <listitem><para>Support for the native MS-RPC printing 
39         calls such as StartDocPrinter, EnumJobs(), etc...  (See 
40         the MSDN documentation at <ulink 
41         url="http://msdn.microsoft.com/">http://msdn.microsoft.com/</ulink> 
42         for more information on the Win32 printing API)
43         </para></listitem>
44                 
45         <listitem><para>Support for NT Access Control Lists (ACL) 
46         on printer objects</para></listitem>
47         
48         <listitem><para>Improved support for printer queue manipulation 
49         through the use of an internal databases for spooled job 
50         information</para></listitem>
51 </itemizedlist>
52
53 <para>
54 There has been some initial confusion about what all this means
55 and whether or not it is a requirement for printer drivers to be 
56 installed on a Samba host in order to support printing from Windows 
57 clients. As a side note, Samba does not use these drivers in any way to process 
58 spooled files.  They are utilized entirely by the clients.
59 </para>
60
61 <para>
62 The following MS KB article, may be of some help if you are dealing with
63 Windows 2000 clients:
64 <ulink url="http://support.microsoft.com/support/kb/articles/Q189/1/05.ASP">How to Add Printers with No User Interaction in Windows 2000</ulink>
65 </para>
66
67 </sect1>
68
69
70 <sect1>
71 <title>Configuration</title>
72
73 <warning>
74 <title>[print$] vs. [printer$]</title>
75
76 <para>
77 Previous versions of Samba recommended using a share named [printer$].  
78 This name was taken from the printer$ service created by Windows 9x 
79 clients when a printer was shared.  Windows 9x printer servers always have 
80 a printer$ service which provides read-only access via no 
81 password in order to support printer driver downloads.
82 </para>
83         
84 <para>
85 However, the initial implementation allowed for a 
86 parameter named <parameter>printer driver location</parameter> 
87 to be used on a per share basis to specify the location of 
88 the driver files associated with that printer.  Another 
89 parameter named <parameter>printer driver</parameter> provided 
90 a means of defining the printer driver name to be sent to 
91 the client.
92 </para>
93
94 </warning>
95  
96 <sect2>
97 <title>Creating [print$]</title>        
98
99 <para>
100 In order to support the uploading of printer driver 
101 files, you must first configure a file share named [print$].  
102 The name of this share is hard coded in Samba's internals so 
103 the name is very important (print$ is the service used by 
104 Windows NT print servers to provide support for printer driver 
105 download).
106 </para>
107
108 <para>You should modify the server's smb.conf file to add the global
109 parameters and to create the 
110 following file share (of course, some of the parameter values,
111 such as 'path' are arbitrary and should be replaced with
112 appropriate values for your site):</para>
113
114 <para><programlisting>
115 [global]
116     ; members of the ntadmin group should be able
117     ; to add drivers and set printer properties
118     ; root is implicitly a 'printer admin'
119     printer admin = @ntadmin
120
121 [print$]
122     path = /usr/local/samba/printers
123     guest ok = yes
124     browseable = yes
125     read only = yes
126     ; since this share is configured as read only, then we need
127     ; a 'write list'.  Check the file system permissions to make
128     ; sure this account can copy files to the share.  If this
129     ; is setup to a non-root account, then it should also exist
130     ; as a 'printer admin'
131     write list = @ntadmin,root
132 </programlisting></para>
133         
134 <para>The <ulink url="smb.conf.5.html#WRITELIST"><parameter>
135 write list</parameter></ulink> is used to allow administrative 
136 level user accounts to have write access in order to update files 
137 on the share.  See the <ulink url="smb.conf.5.html">smb.conf(5) 
138 man page</ulink> for more information on configuring file shares.</para>
139         
140 <para>The requirement for <ulink url="smb.conf.5.html#GUESTOK"><parameter>guest 
141 ok = yes</parameter></ulink> depends upon how your
142 site is configured.  If users will be guaranteed to have 
143 an account on the Samba host, then this is a non-issue.</para>
144
145 <note>  
146 <title>Author's Note</title>
147
148 <para>
149 The non-issue is that if all your Windows NT users are guaranteed to be 
150 authenticated by the Samba server (such as a domain member server and the NT 
151 user has already been validated by the Domain Controller in 
152 order to logon to the Windows NT console), then guest access 
153 is not necessary.  Of course, in a workgroup environment where 
154 you just want to be able to print without worrying about 
155 silly accounts and security, then configure the share for 
156 guest access.  You'll probably want to add <ulink 
157 url="smb.conf.5.html#MAPTOGUEST"><parameter>map to guest = Bad User
158 </parameter></ulink> in the <parameter>[global]</parameter> section as well.  Make sure 
159 you understand what this parameter does before using it 
160 though. --jerry
161 </para>
162 </note>
163
164 <para>In order for a Windows NT print server to support 
165 the downloading of driver files by multiple client architectures,
166 it must create subdirectories within the [print$] service
167 which correspond to each of the supported client architectures.
168 Samba follows this model as well.</para>
169
170 <para>Next create the directory tree below the [print$] share 
171 for each architecture you wish to support.</para>
172
173 <para><computeroutput>
174 [print$]-----
175         |-W32X86           ; "Windows NT x86"
176         |-WIN40            ; "Windows 95/98"
177         |-W32ALPHA         ; "Windows NT Alpha_AXP"
178         |-W32MIPS          ; "Windows NT R4000"
179         |-W32PPC           ; "Windows NT PowerPC"
180 </computeroutput></para>
181
182 <warning>
183 <title>ATTENTION!  REQUIRED PERMISSIONS</title>
184         
185 <para>
186 In order to currently add a new driver to you Samba host, 
187 one of two conditions must hold true:
188 </para>
189                 
190 <itemizedlist>
191         <listitem><para>The account used to connect to the Samba host 
192         must have a uid of 0 (i.e. a root account)</para></listitem>
193                 
194         <listitem><para>The account used to connect to the Samba host
195         must be a member of the <ulink 
196         url="smb.conf.5.html#PRINTERADMIN"><parameter>printer 
197         admin</parameter></ulink> list.</para></listitem>
198 </itemizedlist>
199
200 <para>
201 Of course, the connected account must still possess access
202 to add files to the subdirectories beneath [print$]. Remember
203 that all file shares are set to 'read only' by default.
204 </para>
205 </warning>
206
207
208 <para>
209 Once you have created the required <parameter>[print$]</parameter> service and 
210 associated subdirectories, simply log onto the Samba server using 
211 a root (or <parameter>printer admin</parameter>) account
212 from a Windows NT 4.0/2k client.  Open <guilabel>Network Neighbourhood</guilabel> or
213 <guilabel>My Network Places</guilabel> and browse for the Samba host.  Once you have located
214 the server, navigate to the <guilabel>Printers...</guilabel> folder.
215 You should see an initial listing of printers
216 that matches the printer shares defined on your Samba host.
217 </para>
218 </sect2>
219
220 <sect2>
221 <title>Setting Drivers for Existing Printers</title>
222
223 <para>The initial listing of printers in the Samba host's 
224 Printers folder will have no real printer driver assigned 
225 to them. This defaults to a NULL string to allow the use
226 of the local Add Printer Wizard on NT/2000 clients.
227 Attempting to view the printer properties for a printer
228 which has this default driver assigned will result in 
229 the error message:</para>
230
231 <para>
232 <errorname>Device settings cannot be displayed.  The driver 
233 for the specified printer is not installed, only spooler 
234 properties will be displayed.  Do you want to install the 
235 driver now?</errorname>
236 </para>
237
238 <para>
239 Click <guibutton>No</guibutton> in the error dialog and you will be presented with
240 the printer properties window.  The way to assign a driver to a 
241 printer is to either
242 </para>
243         
244 <procedure>
245         <step><para>Use the <guibutton>New Driver...</guibutton> button to install 
246                                 a new printer driver, or</para></step>
247         
248         <step><para>Select a driver from the popup list of 
249                         installed drivers.  Initially this list will be empty.</para>
250         </step>
251 </procedure>
252         
253 <para>If you wish to install printer drivers for client 
254 operating systems other than "Windows NT x86", you will need 
255 to use the <guilabel>Sharing</guilabel> tab of the printer properties dialog.</para>
256
257 <para>Assuming you have connected with a root account, you 
258 will also be able modify other printer properties such as 
259 ACLs and device settings using this dialog box.</para>
260
261 <para>A few closing comments for this section, it is possible 
262 on a Windows NT print server to have printers
263 listed in the Printers folder which are not shared.  Samba does
264 not make this distinction.  By definition, the only printers of
265 which Samba is aware are those which are specified as shares in
266 &smb.conf;.</para>
267   
268 <para>Another interesting side note is that Windows NT clients do
269 not use the SMB printer share, but rather can print directly 
270 to any printer on another Windows NT host using MS-RPC.  This
271 of course assumes that the printing client has the necessary
272 privileges on the remote host serving the printer.  The default
273 permissions assigned by Windows NT to a printer gives the "Print"
274 permissions to the "Everyone" well-known group.
275 </para>
276
277 </sect2>        
278
279
280 <sect2>
281 <title>Support a large number of printers</title>
282                 
283 <para>One issue that has arisen during the development
284 phase of Samba 2.2 is the need to support driver downloads for
285 100's of printers.  Using the Windows NT APW is somewhat 
286 awkward to say the least.  If more than one printer are using the 
287 same driver, the <ulink url="rpcclient.1.html"><command>rpcclient's
288 setdriver command</command></ulink> can be used to set the driver
289 associated with an installed driver.  The following is example
290 of how this could be accomplished:</para>
291                 
292 <para>
293 <screen>
294 <prompt>$ </prompt><userinput>rpcclient <replaceable>pogo</replaceable> -U root%<replaceable>secret</replaceable> -c "enumdrivers"</userinput>
295 Domain=[NARNIA] OS=[Unix] Server=[Samba 2.2.0-alpha3]
296  
297 [Windows NT x86]
298 Printer Driver Info 1:
299      Driver Name: [HP LaserJet 4000 Series PS]
300  
301 Printer Driver Info 1:
302      Driver Name: [HP LaserJet 2100 Series PS]
303  
304 Printer Driver Info 1:
305      Driver Name: [HP LaserJet 4Si/4SiMX PS]
306 <prompt>$ </prompt><userinput>rpcclient <replaceable>pogo</replaceable> -U root%<replaceable>secret</replaceable> -c "enumprinters"</userinput>
307 Domain=[NARNIA] OS=[Unix] Server=[Samba 2.2.0-alpha3]
308      flags:[0x800000]
309      name:[\\POGO\hp-print]
310      description:[POGO\\POGO\hp-print,NO DRIVER AVAILABLE FOR THIS PRINTER,]
311      comment:[]
312                                   
313 <prompt>$ </prompt><userinput>rpcclient <replaceable>pogo</replaceable> -U root%<replaceable>secret</replaceable> -c "setdriver <replaceable>hp-print</replaceable> <replaceable>\"HP LaserJet 4000 Series PS\"</replaceable></userinput>
314 Domain=[NARNIA] OS=[Unix] Server=[Samba 2.2.0-alpha3]
315 Successfully set hp-print to driver HP LaserJet 4000 Series PS.
316 </screen></para>
317 </sect2>
318
319
320
321 <sect2>
322 <title>Adding New Printers via the Windows NT APW</title>
323         
324 <para>
325 By default, Samba offers all printer shares defined in &smb.conf;
326 in the <filename>Printers...</filename> folder.  Also existing in this folder is the Windows NT 
327 Add Printer Wizard icon.  The <acronym>APW</acronym> will be show only if
328 </para>
329
330 <itemizedlist>
331         <listitem><para>The connected user is able to successfully
332         execute an OpenPrinterEx(\\server) with administrative
333         privileges (i.e. root or <parameter>printer admin</parameter>).
334         </para></listitem>
335         
336         <listitem><para><ulink url="smb.conf.5.html#SHOWADDPRINTERWIZARD"><parameter>show 
337         add printer wizard = yes</parameter></ulink> (the default).
338         </para></listitem>
339 </itemizedlist>
340
341 <para>
342 In order to be able to use the APW to successfully add a printer to a Samba 
343 server, the <ulink url="smb.conf.5.html#ADDPRINTERCOMMAND"><parameter>add 
344 printer command</parameter></ulink> must have a defined value.  The program
345 hook must successfully add the printer to the system (i.e. 
346 <filename>/etc/printcap</filename> or appropriate files) and 
347 &smb.conf; if necessary.
348 </para>
349
350 <para>
351 When using the APW from a client, if the named printer share does 
352 not exist, &smbd; will execute the <parameter>add printer 
353 command</parameter> and reparse to the &smb.conf;
354 to attempt to locate the new printer share.  If the share is still not defined,
355 an error of <errorname>Access Denied</errorname> is returned to the client.  Note that the 
356 <parameter>add printer program</parameter> is executed under the context
357 of the connected user, not necessarily a root account.
358 </para>
359
360 <para>
361 There is a complementary <ulink url="smb.conf.5.html#DELETEPRINTERCOMMAND"><parameter>delete
362 printer command</parameter></ulink> for removing entries from the "Printers..."
363 folder.
364 </para>
365
366 <para>
367 The following is an example <ulink url="smb.conf.5.html#ADDPRINTERCOMMAN"><parameter>add printer command</parameter></ulink> script. It adds the appropriate entries to <filename>/etc/printcap.local</filename> (change that to what you need) and returns a line of 'Done' which is needed for the whole process to work.
368 </para>
369
370 <programlisting>
371 #!/bin/sh
372
373 # Script to insert a new printer entry into printcap.local
374 #
375 # $1, printer name, used as the descriptive name
376 # $2, share name, used as the printer name for Linux
377 # $3, port name
378 # $4, driver name
379 # $5, location, used for the device file of the printer
380 # $6, win9x location
381
382 #
383 # Make sure we use the location that RedHat uses for local printer defs
384 PRINTCAP=/etc/printcap.local
385 DATE=`date +%Y%m%d-%H%M%S`
386 LP=lp
387 RESTART="service lpd restart"
388
389 # Keep a copy
390 cp $PRINTCAP $PRINTCAP.$DATE
391 # Add the printer to $PRINTCAP
392 echo ""                                                 >> $PRINTCAP
393 echo "$2|$1:\\"                                         >> $PRINTCAP
394 echo "  :sd=/var/spool/lpd/$2:\\"                       >> $PRINTCAP
395 echo "  :mx=0:ml=0:sh:\\"                               >> $PRINTCAP
396 echo "  :lp=/usr/local/samba/var/print/$5.prn:"         >> $PRINTCAP
397
398 touch "/usr/local/samba/var/print/$5.prn" >> /tmp/printadd.$$ 2>&amp;1
399 chown $LP "/usr/local/samba/var/print/$5.prn" >> /tmp/printadd.$$ 2>&amp;1
400
401 mkdir /var/spool/lpd/$2
402 chmod 700 /var/spool/lpd/$2
403 chown $LP /var/spool/lpd/$2
404 #echo $1 >> "/usr/local/samba/var/print/$5.prn"
405 #echo $2 >> "/usr/local/samba/var/print/$5.prn"
406 #echo $3 >> "/usr/local/samba/var/print/$5.prn"
407 #echo $4 >> "/usr/local/samba/var/print/$5.prn"
408 #echo $5 >> "/usr/local/samba/var/print/$5.prn"
409 #echo $6 >> "/usr/local/samba/var/print/$5.prn"
410 $RESTART >> "/usr/local/samba/var/print/$5.prn"
411 # Not sure if this is needed
412 touch /usr/local/samba/lib/smb.conf
413 #
414 # You need to return a value, but I am not sure what it means.
415 #
416 echo "Done"
417 exit 0
418 </programlisting>
419
420 </sect2>
421
422
423 <sect2>
424 <title>Samba and Printer Ports</title>
425
426 <para>
427 Windows NT/2000 print servers associate a port with each printer.  These normally
428 take the form of LPT1:, COM1:, FILE:, etc...  Samba must also support the
429 concept of ports associated with a printer.  By default, only one printer port,
430 named "Samba Printer Port", exists on a system.  Samba does not really a port in
431 order to print, rather it is a requirement of Windows clients.  
432 </para>
433
434 <para>
435 Note that Samba does not support the concept of "Printer Pooling" internally 
436 either.  This is when a logical printer is assigned to multiple ports as 
437 a form of load balancing or fail over.
438 </para>
439
440 <para>
441 If you require that multiple ports be defined for some reason,
442 &smb.conf; possesses a <ulink 
443 url="smb.conf.5.html#ENUMPORTSCOMMAND"><parameter>enumports 
444 command</parameter></ulink> which can be used to define an external program 
445 that generates a listing of ports on a system.
446 </para>
447
448 </sect2>
449
450 </sect1>
451
452
453 <sect1>
454         <title>The Imprints Toolset</title>
455         
456         <para>The Imprints tool set provides a UNIX equivalent of the 
457         Windows NT Add Printer Wizard.  For complete information, please 
458         refer to the Imprints web site at <ulink url="http://imprints.sourceforge.net/">
459         http://imprints.sourceforge.net/</ulink> as well as the documentation 
460         included with the imprints source distribution.  This section will 
461         only provide a brief introduction to the features of Imprints.</para>
462         
463         
464         <sect2>
465                 <title>What is Imprints?</title>
466
467                 <para>Imprints is a collection of tools for supporting the goals 
468                 of</para>
469                 
470                 <itemizedlist>
471                         <listitem><para>Providing a central repository information 
472                         regarding Windows NT and 95/98 printer driver packages</para>
473                         </listitem>
474                         
475                         <listitem><para>Providing the tools necessary for creating 
476                         the Imprints printer driver packages.</para></listitem>
477                         
478                         <listitem><para>Providing an installation client which 
479                         will obtain and install printer drivers on remote Samba 
480                         and Windows NT 4 print servers.</para></listitem>
481                 </itemizedlist>
482                 
483         </sect2>
484         
485         
486         <sect2>
487                 <title>Creating Printer Driver Packages</title>
488                 
489                 <para>The process of creating printer driver packages is beyond
490                 the scope of this document (refer to Imprints.txt also included
491                 with the Samba distribution for more information).  In short,
492                 an Imprints driver package is a gzipped tarball containing the
493                 driver files, related INF files, and a control file needed by the
494                 installation client.</para>
495         </sect2>
496         
497         
498         <sect2>
499                 <title>The Imprints server</title>
500                 
501                 <para>The Imprints server is really a database server that 
502                 may be queried via standard HTTP mechanisms.  Each printer 
503                 entry in the database has an associated URL for the actual
504                 downloading of the package.  Each package is digitally signed
505                 via GnuPG which can be used to verify that package downloaded
506                 is actually the one referred in the Imprints database.  It is 
507                 <emphasis>not</emphasis> recommended that this security check 
508                 be disabled.</para>
509         </sect2>
510         
511         <sect2>
512                 <title>The Installation Client</title>
513
514                 <para>More information regarding the Imprints installation client 
515                 is available in the <filename>Imprints-Client-HOWTO.ps</filename> 
516                 file included with the imprints source package.</para>
517
518                 <para>The Imprints installation client comes in two forms.</para>
519
520                 <itemizedlist>
521                         <listitem><para>a set of command line Perl scripts</para>
522                         </listitem>
523                         
524                         <listitem><para>a GTK+ based graphical interface to 
525                         the command line perl scripts</para></listitem>
526                 </itemizedlist>
527                 
528                 <para>The installation client (in both forms) provides a means
529                 of querying the Imprints database server for a matching
530                 list of known printer model names as well as a means to 
531                 download and install the drivers on remote Samba and Windows
532                 NT print servers.</para>
533
534                 <para>The basic installation process is in four steps and 
535                 perl code is wrapped around <command>smbclient</command> 
536                 and <command>rpcclient</command>.</para>
537
538 <para><programlisting>  
539 foreach (supported architecture for a given driver)
540 {
541      1.  rpcclient: Get the appropriate upload directory 
542          on the remote server
543      2.  smbclient: Upload the driver files
544      3.  rpcclient: Issues an AddPrinterDriver() MS-RPC
545 }
546         
547 4.  rpcclient: Issue an AddPrinterEx() MS-RPC to actually
548     create the printer
549 </programlisting></para>
550                 
551                 <para>One of the problems encountered when implementing 
552                 the Imprints tool set was the name space issues between 
553                 various supported client architectures.  For example, Windows 
554                 NT includes a driver named "Apple LaserWriter II NTX v51.8" 
555                 and Windows 95 calls its version of this driver "Apple 
556                 LaserWriter II NTX"</para>
557                 
558                 <para>The problem is how to know what client drivers have 
559                 been uploaded for a printer.  As astute reader will remember 
560                 that the Windows NT Printer Properties dialog only includes 
561                 space for one printer driver name.  A quick look in the 
562                 Windows NT 4.0 system registry at</para>
563         
564                 <para><filename>HKLM\System\CurrentControlSet\Control\Print\Environment
565                 </filename></para>
566                 
567                 <para>will reveal that Windows NT always uses the NT driver 
568                 name.  This is ok as Windows NT always requires that at least 
569                 the Windows NT version of the printer driver is present.  
570                 However, Samba does not have the requirement internally.  
571                 Therefore, how can you use the NT driver name if is has not 
572                 already been installed?</para>
573                 
574                 <para>The way of sidestepping this limitation is to require 
575                 that all Imprints printer driver packages include both the Intel 
576                 Windows NT and 95/98 printer drivers and that NT driver is 
577                 installed first.</para>
578         </sect2>
579         
580 </sect1>
581
582 <!--
583 FIXME
584
585   This comment from rpc_server/srv_spoolss_nt.c:_spoolss_open_printer_ex()
586   needs to be added into a section probably.  This is to remind me it needs 
587   to be done.  -jerry
588
589                 /*
590                  * If the openprinterex rpc call contains a devmode,
591                  * it's a per-user one. This per-user devmode is derivated
592                  * from the global devmode. Openprinterex() contains a per-user
593                  * devmode for when you do EMF printing and spooling.
594                  * In the EMF case, the NT workstation is only doing half the job
595                  * of rendering the page. The other half is done by running the printer
596                  * driver on the server.
597                  * The EMF file doesn't contain the page description (paper size, orientation, ...).
598                  * The EMF file only contains what is to be printed on the page.
599                  * So in order for the server to know how to print, the NT client sends
600                  * a devicemode attached to the openprinterex call.
601                  * But this devicemode is short lived, it's only valid for the current print job.
602                  *
603                  * If Samba would have supported EMF spooling, this devicemode would
604                  * have been attached to the handle, to sent it to the driver to correctly
605                  * rasterize the EMF file.
606                  *
607                  * As Samba only supports RAW spooling, we only receive a ready-to-print file,
608                  * we just act as a pass-thru between windows and the printer.
609                  *
610                  * In order to know that Samba supports only RAW spooling, NT has to call
611                  * getprinter() at level 2 (attribute field) or NT has to call startdoc()
612                  * and until NT sends a RAW job, we refuse it.
613                  *
614                  * But to call getprinter() or startdoc(), you first need a valid handle,
615                  * and to get an handle you have to call openprintex(). Hence why you have
616                  * a devicemode in the openprinterex() call.
617                  *
618                  *
619                  * Differences between NT4 and NT 2000.
620                  * NT4:
621                  * 
622                  * On NT4, you only have a global devicemode. This global devicemode can be changed
623                  * by the administrator (or by a user with enough privs). Every time a user
624                  * wants to print, the devicemode is reset to the default. In Word, every time
625                  * you print, the printer's characteristics are always reset to the global devicemode.
626                  *
627                  * NT 2000:
628                  * 
629                  * In W2K, there is the notion of per-user devicemode. The first time you use
630                  * a printer, a per-user devicemode is build from the global devicemode.
631                  * If you change your per-user devicemode, it is saved in the registry, under the
632                  * H_KEY_CURRENT_KEY sub_tree. So that every time you print, you have your default
633                  * printer preferences available.
634                  *
635                  * To change the per-user devicemode: it's the "Printing Preferences ..." button
636                  * on the General Tab of the printer properties windows.
637                  *
638                  * To change the global devicemode: it's the "Printing Defaults..." button
639                  * on the Advanced Tab of the printer properties window.
640 -->
641
642 <sect1>
643 <title>Diagnosis</title>
644
645 <sect2>
646 <title>Introduction</title>
647
648 <para>
649 This is a short description of how to debug printing problems with
650 Samba. This describes how to debug problems with printing from a SMB
651 client to a Samba server, not the other way around. For the reverse
652 see the examples/printing directory.
653 </para>
654
655 <para>
656 Ok, so you want to print to a Samba server from your PC. The first
657 thing you need to understand is that Samba does not actually do any
658 printing itself, it just acts as a middleman between your PC client
659 and your Unix printing subsystem. Samba receives the file from the PC
660 then passes the file to a external "print command". What print command
661 you use is up to you.
662 </para>
663
664 <para>
665 The whole things is controlled using options in smb.conf. The most
666 relevant options (which you should look up in the smb.conf man page)
667 are:
668 </para>
669
670 <para><programlisting>
671       [global]
672         print command     - send a file to a spooler
673         lpq command       - get spool queue status
674         lprm command      - remove a job
675       [printers]
676         path = /var/spool/lpd/samba
677 </programlisting></para>
678
679 <para>
680 The following are nice to know about:
681 </para>
682
683 <para><programlisting>
684         queuepause command   - stop a printer or print queue
685         queueresume command  - start a printer or print queue
686 </programlisting></para>
687
688 <para>
689 Example:
690 </para>
691
692 <para><programlisting>
693         print command = /usr/bin/lpr -r -P%p %s
694         lpq command   = /usr/bin/lpq    -P%p %s
695         lprm command  = /usr/bin/lprm   -P%p %j
696         queuepause command = /usr/sbin/lpc -P%p stop
697         queuepause command = /usr/sbin/lpc -P%p start
698 </programlisting></para>
699
700 <para>
701 Samba should set reasonable defaults for these depending on your
702 system type, but it isn't clairvoyant. It is not uncommon that you
703 have to tweak these for local conditions.  The commands should
704 always have fully specified pathnames,  as the smdb may not have
705 the correct PATH values.
706 </para>
707
708 <para>
709 When you send a job to Samba to be printed,  it will make a temporary
710 copy of it in the directory specified in the [printers] section.
711 and it should be periodically cleaned out.  The lpr -r option
712 requests that the temporary copy be removed after printing; If
713 printing fails then you might find leftover files in this directory,
714 and it should be periodically cleaned out.  Samba used the lpq
715 command to determine the "job number" assigned to your print job
716 by the spooler.
717 </para>
718
719 <para>
720 The %&gt;letter&lt; are "macros" that get dynamically replaced with appropriate
721 values when they are used. The %s gets replaced with the name of the spool
722 file that Samba creates and the %p gets replaced with the name of the
723 printer. The %j gets replaced with the "job number" which comes from
724 the lpq output.
725 </para>
726
727 </sect2>
728
729 <sect2>
730 <title>Debugging printer problems</title>
731
732 <para>
733 One way to debug printing problems is to start by replacing these
734 command with shell scripts that record the arguments and the contents
735 of the print file. A simple example of this kind of things might
736 be:
737 </para>
738
739 <para><programlisting>
740         print command = /tmp/saveprint %p %s
741
742     #!/bin/saveprint
743     # we make sure that we are the right user
744     /usr/bin/id -p >/tmp/tmp.print
745     # we run the command and save the error messages
746     # replace the command with the one appropriate for your system
747     /usr/bin/lpr -r -P$1 $2 2>>&amp;/tmp/tmp.print
748 </programlisting></para>
749
750 <para>
751 Then you print a file and try removing it.  You may find that the
752 print queue needs to be stopped in order to see the queue status
753 and remove the job:
754 </para>
755
756 <para><screen>
757 <prompt>h4: {42} % </prompt><userinput>echo hi >/tmp/hi</userinput>
758 <prompt>h4: {43} % </prompt><userinput>smbclient //localhost/lw4</userinput>
759 added interface ip=10.0.0.4 bcast=10.0.0.255 nmask=255.255.255.0
760 Password: 
761 Domain=[ASTART] OS=[Unix] Server=[Samba 2.0.7]
762 <prompt>smb: \> </prompt><userinput>print /tmp/hi</userinput>
763 putting file /tmp/hi as hi-17534 (0.0 kb/s) (average 0.0 kb/s)
764 <prompt>smb: \> </prompt><userinput>queue</userinput>
765 1049     3            hi-17534
766 <prompt>smb: \> </prompt><userinput>cancel 1049</userinput>
767 Error cancelling job 1049 : code 0
768 <prompt>smb: \> </prompt><userinput>cancel 1049</userinput>
769 Job 1049 cancelled
770 <prompt>smb: \> </prompt><userinput>queue</userinput>
771 <prompt>smb: \> </prompt><userinput>exit</userinput>
772 </screen></para>
773
774 <para>
775 The 'code 0' indicates that the job was removed.  The comment
776 by the  smbclient is a bit misleading on this.
777 You can observe the command output and then and look at the
778 /tmp/tmp.print file to see what the results are.  You can quickly
779 find out if the problem is with your printing system.  Often people
780 have problems with their /etc/printcap file or permissions on
781 various print queues.
782 </para>
783 </sect2>
784
785 <sect2>
786 <title>What printers do I have?</title>
787
788 <para>
789 You can use the 'testprns' program to check to see if the printer
790 name you are using is recognized by Samba.  For example,  you can
791 use:
792 </para>
793
794 <para><screen>
795 <prompt>$ </prompt><userinput>testprns printer /etc/printcap</userinput>
796 </screen></para>
797
798 <para>
799 Samba can get its printcap information from a file or from a program.
800 You can try the following to see the format of the extracted
801 information:
802 </para>
803
804 <para><screen>
805 <prompt>$ </prompt><userinput>testprns -a printer /etc/printcap</userinput>
806 <prompt>$ </prompt><userinput>testprns -a printer '|/bin/cat printcap'</userinput>
807 </screen></para>
808
809 </sect2>
810
811 <sect2>
812 <title>Setting up printcap and print servers</title>
813
814 <para>
815 You may need to set up some printcaps for your Samba system to use.
816 It is strongly recommended that you use the facilities provided by
817 the print spooler to set up queues and printcap information.
818 </para>
819
820 <para>
821 Samba requires either a printcap or program to deliver printcap
822 information.  This printcap information has the format:
823 </para>
824
825 <para><programlisting>
826   name|alias1|alias2...:option=value:...
827 </programlisting></para>
828
829 <para>
830 For almost all printing systems, the printer 'name' must be composed
831 only of alphanumeric or underscore '_' characters.  Some systems also
832 allow hyphens ('-') as well.  An alias is an alternative name for the
833 printer,  and an alias with a space in it is used as a 'comment'
834 about the printer.  The printcap format optionally uses a \ at the end of lines
835 to extend the printcap to multiple lines.
836 </para>
837
838 <para>
839 Here are some examples of printcap files:
840 </para>
841
842 <table>
843         <tgroup cols="2" align="left">
844                 <tbody>
845                         <row><entry><programlisting>pr</programlisting></entry><entry>just printer name</entry></row>
846                         <row><entry><programlisting>pr|alias</programlisting></entry><entry>printer name and alias</entry></row>
847                         <row><entry><programlisting>pr|My Printer</programlisting></entry><entry>printer name, alias used as comment</entry></row>
848                         <row><entry><programlisting>
849 pr:sh:\        
850   :cm= \ 
851   testing
852 </programlisting></entry><entry>Same as pr:sh:cm= testing</entry></row>
853                         <row><entry><programlisting>
854 pr:sh           
855   :cm= testing
856 </programlisting></entry><entry>Same as pr:sh:cm= testing</entry></row>
857 </tbody>
858 </tgroup>
859 </table>
860
861 <para>
862 Samba reads the printcap information when first started.  If you make
863 changes in the printcap information, then you must do the following:
864 </para>
865
866 <orderedlist>
867
868 <listitem><para>
869 make sure that the print spooler is aware of these changes.
870 The LPRng system uses the 'lpc reread' command to do this.
871 </para></listitem>
872
873 <listitem><para>
874 make sure that the spool queues, etc., exist and have the
875 correct permissions.  The LPRng system uses the 'checkpc -f'
876 command to do this.
877 </para></listitem>
878
879 <listitem><para>
880 You now should send a SIGHUP signal to the smbd server to have
881 it reread the printcap information.
882 </para></listitem>
883 </orderedlist>
884
885 </sect2>
886
887 <sect2>
888 <title>Job sent, no output</title>
889
890 <para>
891 This is the most frustrating part of printing.  You may have sent the
892 job,  verified that the job was forwarded,  set up a wrapper around
893 the command to send the file,  but there was no output from the printer.
894 </para>
895
896 <para>
897 First,  check to make sure that the job REALLY is getting to the
898 right print queue.  If you are using a BSD or LPRng print spooler,
899 you can temporarily stop the printing of jobs.  Jobs can still be
900 submitted, but they will not be printed.  Use:
901 </para>
902
903 <para><screen>
904 <prompt>$ </prompt><userinput>lpc -Pprinter stop</userinput>
905 </screen></para>
906
907 <para>
908 Now submit a print job and then use <userinput>lpq -Pprinter</userinput> to see if the
909 job is in the print queue.  If it is not in the print queue then
910 you will have to find out why it is not being accepted for printing.
911 </para>
912
913 <para>
914 Next, you may want to check to see what the format of the job really
915 was.  With the assistance of the system administrator you can view
916 the submitted jobs files.  You may be surprised to find that these
917 are not in what you would expect to call a printable format.
918 You can use the UNIX 'file' utitily to determine what the job
919 format actually is:
920 </para>
921
922 <para><screen>
923 <prompt>$ </prompt><userinput>cd /var/spool/lpd/printer   # spool directory of print jobs</userinput>
924 <prompt>$ </prompt><userinput>ls                          # find job files</userinput>
925 <prompt>$ </prompt><userinput>file dfA001myhost</userinput>
926 </screen></para>
927
928 <para>
929 You should make sure that your printer supports this format OR that
930 your system administrator has installed a 'print filter' that will
931 convert the file to a format appropriate for your printer.
932 </para>
933
934 </sect2>
935
936 <sect2>
937 <title>Job sent, strange output</title>
938
939 <para>
940 Once you have the job printing, you can then start worrying about
941 making it print nicely.
942 </para>
943
944 <para>
945 The most common problem is extra pages of output: banner pages
946 OR blank pages at the end.
947 </para>
948
949 <para>
950 If you are getting banner pages,  check and make sure that the
951 printcap option or printer option is configured for no banners.
952 If you have a printcap,  this is the :sh (suppress header or banner
953 page) option.  You should have the following in your printer.
954 </para>
955
956 <para><programlisting>
957    printer: ... :sh
958 </programlisting></para>
959
960 <para>
961 If you have this option and are still getting banner pages,  there
962 is a strong chance that your printer is generating them for you
963 automatically.  You should make sure that banner printing is disabled
964 for the printer.  This usually requires using the printer setup software
965 or procedures supplied by the printer manufacturer.
966 </para>
967
968 <para>
969 If you get an extra page of output,  this could be due to problems
970 with your job format,  or if you are generating PostScript jobs,
971 incorrect setting on your printer driver on the MicroSoft client.
972 For example, under Win95 there is a option:
973 </para>
974
975 <para><programlisting>
976   Printers|Printer Name|(Right Click)Properties|Postscript|Advanced|
977 </programlisting></para>
978
979 <para>
980 that allows you to choose if a Ctrl-D is appended to all jobs.
981 This is a very bad thing to do, as most spooling systems will
982 automatically add a ^D to the end of the job if it is detected as
983 PostScript.  The multiple ^D may cause an additional page of output.
984 </para>
985
986 </sect2>
987
988 <sect2>
989 <title>Raw PostScript printed</title>
990
991 <para>
992 This is a problem that is usually caused by either the print spooling
993 system putting information at the start of the print job that makes
994 the printer think the job is a text file, or your printer simply
995 does not support PostScript.  You may need to enable 'Automatic
996 Format Detection' on your printer.
997 </para>
998
999 </sect2>
1000
1001 <sect2>
1002 <title>Advanced Printing</title>
1003
1004 <para>
1005 Note that you can do some pretty magic things by using your
1006 imagination with the <parameter>print command</parameter> option and some shell scripts.
1007 Doing print accounting is easy by passing the %U option to a print
1008 command shell script. You could even make the print command detect
1009 the type of output and its size and send it to an appropriate
1010 printer.
1011 </para>
1012
1013 </sect2>
1014
1015 </sect1>
1016
1017 </chapter>