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