1 <chapter id="printing">
6 <firstname>Gerald (Jerry)</firstname><surname>Carter</surname>
8 <orgname>Samba Team</orgname>
10 <email>jerry@samba.org</email>
16 <pubdate> (3 May 2001) </pubdate>
19 <title>Printing Support in Samba 2.2.x</title>
22 <title>Introduction</title>
24 <para>Beginning with the 2.2.0 release, Samba supports
25 the native Windows NT printing mechanisms implemented via
26 MS-RPC (i.e. the SPOOLSS named pipe). Previous versions of
27 Samba only supported LanMan printing calls.</para>
29 <para>The additional functionality provided by the new
30 SPOOLSS support includes:</para>
33 <listitem><para>Support for downloading printer driver
34 files to Windows 95/98/NT/2000 clients upon demand.
37 <listitem><para>Uploading of printer drivers via the
38 Windows NT Add Printer Wizard (APW) or the
39 Imprints tool set (refer to <ulink
40 url="http://imprints.sourceforge.net">http://imprints.sourceforge.net</ulink>).
43 <listitem><para>Support for the native MS-RPC printing
44 calls such as StartDocPrinter, EnumJobs(), etc... (See
45 the MSDN documentation at <ulink
46 url="http://msdn.microsoft.com/">http://msdn.microsoft.com/</ulink>
47 for more information on the Win32 printing API)
50 <listitem><para>Support for NT Access Control Lists (ACL)
51 on printer objects</para></listitem>
53 <listitem><para>Improved support for printer queue manipulation
54 through the use of an internal databases for spooled job
55 information</para></listitem>
59 There has been some initial confusion about what all this means
60 and whether or not it is a requirement for printer drivers to be
61 installed on a Samba host in order to support printing from Windows
62 clients. A bug existed in Samba 2.2.0 which made Windows NT/2000 clients
63 require that the Samba server possess a valid driver for the printer.
64 This is fixed in Samba 2.2.1 and once again, Windows NT/2000 clients
65 can use the local APW for installing drivers to be used with a Samba
66 served printer. This is the same behavior exhibited by Windows 9x clients.
67 As a side note, Samba does not use these drivers in any way to process
68 spooled files. They are utilized entirely by the clients.
72 The following MS KB article, may be of some help if you are dealing with
73 Windows 2000 clients: <emphasis>How to Add Printers with No User
74 Interaction in Windows 2000</emphasis>
78 <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>
85 <title>Configuration</title>
88 <title>[print$] vs. [printer$]</title>
91 Previous versions of Samba recommended using a share named [printer$].
92 This name was taken from the printer$ service created by Windows 9x
93 clients when a printer was shared. Windows 9x printer servers always have
94 a printer$ service which provides read-only access via no
95 password in order to support printer driver downloads.
99 However, the initial implementation allowed for a
100 parameter named <parameter>printer driver location</parameter>
101 to be used on a per share basis to specify the location of
102 the driver files associated with that printer. Another
103 parameter named <parameter>printer driver</parameter> provided
104 a means of defining the printer driver name to be sent to
109 These parameters, including <parameter>printer driver
110 file</parameter> parameter, are being depreciated and should not
111 be used in new installations. For more information on this change,
112 you should refer to the <link linkend="MIGRATION">Migration section</link>
118 <title>Creating [print$]</title>
121 In order to support the uploading of printer driver
122 files, you must first configure a file share named [print$].
123 The name of this share is hard coded in Samba's internals so
124 the name is very important (print$ is the service used by
125 Windows NT print servers to provide support for printer driver
129 <para>You should modify the server's smb.conf file to add the global
130 parameters and to create the
131 following file share (of course, some of the parameter values,
132 such as 'path' are arbitrary and should be replaced with
133 appropriate values for your site):</para>
135 <para><programlisting>
137 ; members of the ntadmin group should be able
138 ; to add drivers and set printer properties
139 ; root is implicitly a 'printer admin'
140 printer admin = @ntadmin
143 path = /usr/local/samba/printers
147 ; since this share is configured as read only, then we need
148 ; a 'write list'. Check the file system permissions to make
149 ; sure this account can copy files to the share. If this
150 ; is setup to a non-root account, then it should also exist
151 ; as a 'printer admin'
152 write list = @ntadmin,root
153 </programlisting></para>
155 <para>The <ulink url="smb.conf.5.html#WRITELIST"><parameter>
156 write list</parameter></ulink> is used to allow administrative
157 level user accounts to have write access in order to update files
158 on the share. See the <ulink url="smb.conf.5.html">smb.conf(5)
159 man page</ulink> for more information on configuring file shares.</para>
161 <para>The requirement for <ulink url="smb.conf.5.html#GUESTOK"><command>guest
162 ok = yes</command></ulink> depends upon how your
163 site is configured. If users will be guaranteed to have
164 an account on the Samba host, then this is a non-issue.</para>
167 <title>Author's Note</title>
170 The non-issue is that if all your Windows NT users are guaranteed to be
171 authenticated by the Samba server (such as a domain member server and the NT
172 user has already been validated by the Domain Controller in
173 order to logon to the Windows NT console), then guest access
174 is not necessary. Of course, in a workgroup environment where
175 you just want to be able to print without worrying about
176 silly accounts and security, then configure the share for
177 guest access. You'll probably want to add <ulink
178 url="smb.conf.5.html#MAPTOGUEST"><command>map to guest = Bad User
179 </command></ulink> in the [global] section as well. Make sure
180 you understand what this parameter does before using it
185 <para>In order for a Windows NT print server to support
186 the downloading of driver files by multiple client architectures,
187 it must create subdirectories within the [print$] service
188 which correspond to each of the supported client architectures.
189 Samba follows this model as well.</para>
191 <para>Next create the directory tree below the [print$] share
192 for each architecture you wish to support.</para>
194 <para><programlisting>
196 |-W32X86 ; "Windows NT x86"
197 |-WIN40 ; "Windows 95/98"
198 |-W32ALPHA ; "Windows NT Alpha_AXP"
199 |-W32MIPS ; "Windows NT R4000"
200 |-W32PPC ; "Windows NT PowerPC"
201 </programlisting></para>
204 <title>ATTENTION! REQUIRED PERMISSIONS</title>
207 In order to currently add a new driver to you Samba host,
208 one of two conditions must hold true:
212 <listitem><para>The account used to connect to the Samba host
213 must have a uid of 0 (i.e. a root account)</para></listitem>
215 <listitem><para>The account used to connect to the Samba host
216 must be a member of the <ulink
217 url="smb.conf.5.html#PRINTERADMIN"><parameter>printer
218 admin</parameter></ulink> list.</para></listitem>
222 Of course, the connected account must still possess access
223 to add files to the subdirectories beneath [print$]. Remember
224 that all file shares are set to 'read only' by default.
230 Once you have created the required [print$] service and
231 associated subdirectories, simply log onto the Samba server using
232 a root (or <parameter>printer admin</parameter>) account
233 from a Windows NT 4.0 client. Navigate to the "Printers" folder
234 on the Samba server. You should see an initial listing of printers
235 that matches the printer shares defined on your Samba host.
240 <title>Setting Drivers for Existing Printers</title>
242 <para>The initial listing of printers in the Samba host's
243 Printers folder will have no real printer driver assigned
244 to them. By default, in Samba 2.2.0 this driver name was set to
245 <emphasis>NO PRINTER DRIVER AVAILABLE FOR THIS PRINTER</emphasis>.
246 Later versions changed this to a NULL string to allow the use
247 tof the local Add Printer Wizard on NT/2000 clients.
248 Attempting to view the printer properties for a printer
249 which has this default driver assigned will result in
250 the error message:</para>
253 <emphasis>Device settings cannot be displayed. The driver
254 for the specified printer is not installed, only spooler
255 properties will be displayed. Do you want to install the
256 driver now?</emphasis>
260 Click "No" in the error dialog and you will be presented with
261 the printer properties window. The way assign a driver to a
266 <listitem><para>Use the "New Driver..." button to install
267 a new printer driver, or</para></listitem>
269 <listitem><para>Select a driver from the popup list of
270 installed drivers. Initially this list will be empty.</para>
274 <para>If you wish to install printer drivers for client
275 operating systems other than "Windows NT x86", you will need
276 to use the "Sharing" tab of the printer properties dialog.</para>
278 <para>Assuming you have connected with a root account, you
279 will also be able modify other printer properties such as
280 ACLs and device settings using this dialog box.</para>
282 <para>A few closing comments for this section, it is possible
283 on a Windows NT print server to have printers
284 listed in the Printers folder which are not shared. Samba does
285 not make this distinction. By definition, the only printers of
286 which Samba is aware are those which are specified as shares in
287 <filename>smb.conf</filename>.</para>
289 <para>Another interesting side note is that Windows NT clients do
290 not use the SMB printer share, but rather can print directly
291 to any printer on another Windows NT host using MS-RPC. This
292 of course assumes that the printing client has the necessary
293 privileges on the remote host serving the printer. The default
294 permissions assigned by Windows NT to a printer gives the "Print"
295 permissions to the "Everyone" well-known group.
302 <title>Support a large number of printers</title>
304 <para>One issue that has arisen during the development
305 phase of Samba 2.2 is the need to support driver downloads for
306 100's of printers. Using the Windows NT APW is somewhat
307 awkward to say the list. If more than one printer are using the
308 same driver, the <ulink url="rpcclient.1.html"><command>rpcclient's
309 setdriver command</command></ulink> can be used to set the driver
310 associated with an installed driver. The following is example
311 of how this could be accomplished:</para>
313 <para><programlisting>
314 <prompt>$ </prompt>rpcclient pogo -U root%secret -c "enumdrivers"
315 Domain=[NARNIA] OS=[Unix] Server=[Samba 2.2.0-alpha3]
318 Printer Driver Info 1:
319 Driver Name: [HP LaserJet 4000 Series PS]
321 Printer Driver Info 1:
322 Driver Name: [HP LaserJet 2100 Series PS]
324 Printer Driver Info 1:
325 Driver Name: [HP LaserJet 4Si/4SiMX PS]
327 <prompt>$ </prompt>rpcclient pogo -U root%secret -c "enumprinters"
328 Domain=[NARNIA] OS=[Unix] Server=[Samba 2.2.0-alpha3]
330 name:[\\POGO\hp-print]
331 description:[POGO\\POGO\hp-print,NO DRIVER AVAILABLE FOR THIS PRINTER,]
334 <prompt>$ </prompt>rpcclient pogo -U root%secret \
335 <prompt>> </prompt> -c "setdriver hp-print \"HP LaserJet 4000 Series PS\""
336 Domain=[NARNIA] OS=[Unix] Server=[Samba 2.2.0-alpha3]
337 Successfully set hp-print to driver HP LaserJet 4000 Series PS.
338 </programlisting></para>
344 <title>Adding New Printers via the Windows NT APW</title>
347 By default, Samba offers all printer shares defined in <filename>smb.conf</filename>
348 in the "Printers..." folder. Also existing in this folder is the Windows NT
349 Add Printer Wizard icon. The APW will be show only if
353 <listitem><para>The connected user is able to successfully
354 execute an OpenPrinterEx(\\server) with administrative
355 privileges (i.e. root or <parameter>printer admin</parameter>).
358 <listitem><para><ulink url="smb.conf.5.html#SHOWADDPRINTERWIZARD"><parameter>show
359 add printer wizard = yes</parameter></ulink> (the default).
364 In order to be able to use the APW to successfully add a printer to a Samba
365 server, the <ulink url="smb.conf.5.html#ADDPRINTERCOMMAND"><parameter>add
366 printer command</parameter></ulink> must have a defined value. The program
367 hook must successfully add the printer to the system (i.e.
368 <filename>/etc/printcap</filename> or appropriate files) and
369 <filename>smb.conf</filename> if necessary.
373 When using the APW from a client, if the named printer share does
374 not exist, <command>smbd</command> will execute the <parameter>add printer
375 command</parameter> and reparse to the <filename>smb.conf</filename>
376 to attempt to locate the new printer share. If the share is still not defined,
377 an error of "Access Denied" is returned to the client. Note that the
378 <parameter>add printer program</parameter> is executed under the context
379 of the connected user, not necessarily a root account.
383 There is a complementing <ulink url="smb.conf.5.html#DELETEPRINTERCOMMAND"><parameter>delete
384 printer command</parameter></ulink> for removing entries from the "Printers..."
392 <title>Samba and Printer Ports</title>
395 Windows NT/2000 print servers associate a port with each printer. These normally
396 take the form of LPT1:, COM1:, FILE:, etc... Samba must also support the
397 concept of ports associated with a printer. By default, only one printer port,
398 named "Samba Printer Port", exists on a system. Samba does not really a port in
399 order to print, rather it is a requirement of Windows clients.
403 Note that Samba does not support the concept of "Printer Pooling" internally
404 either. This is when a logical printer is assigned to multiple ports as
405 a form of load balancing or fail over.
409 If you require that multiple ports be defined for some reason,
410 <filename>smb.conf</filename> possesses a <ulink
411 url="smb.conf.5.html#ENUMPORTSCOMMAND"><parameter>enumports
412 command</parameter></ulink> which can be used to define an external program
413 that generates a listing of ports on a system.
422 <title>The Imprints Toolset</title>
424 <para>The Imprints tool set provides a UNIX equivalent of the
425 Windows NT Add Printer Wizard. For complete information, please
426 refer to the Imprints web site at <ulink url="http://imprints.sourceforge.net/">
427 http://imprints.sourceforge.net/</ulink> as well as the documentation
428 included with the imprints source distribution. This section will
429 only provide a brief introduction to the features of Imprints.</para>
433 <title>What is Imprints?</title>
435 <para>Imprints is a collection of tools for supporting the goals
439 <listitem><para>Providing a central repository information
440 regarding Windows NT and 95/98 printer driver packages</para>
443 <listitem><para>Providing the tools necessary for creating
444 the Imprints printer driver packages.</para></listitem>
446 <listitem><para>Providing an installation client which
447 will obtain and install printer drivers on remote Samba
448 and Windows NT 4 print servers.</para></listitem>
455 <title>Creating Printer Driver Packages</title>
457 <para>The process of creating printer driver packages is beyond
458 the scope of this document (refer to Imprints.txt also included
459 with the Samba distribution for more information). In short,
460 an Imprints driver package is a gzipped tarball containing the
461 driver files, related INF files, and a control file needed by the
462 installation client.</para>
467 <title>The Imprints server</title>
469 <para>The Imprints server is really a database server that
470 may be queried via standard HTTP mechanisms. Each printer
471 entry in the database has an associated URL for the actual
472 downloading of the package. Each package is digitally signed
473 via GnuPG which can be used to verify that package downloaded
474 is actually the one referred in the Imprints database. It is
475 <emphasis>not</emphasis> recommended that this security check
480 <title>The Installation Client</title>
482 <para>More information regarding the Imprints installation client
483 is available in the <filename>Imprints-Client-HOWTO.ps</filename>
484 file included with the imprints source package.</para>
486 <para>The Imprints installation client comes in two forms.</para>
489 <listitem><para>a set of command line Perl scripts</para>
492 <listitem><para>a GTK+ based graphical interface to
493 the command line perl scripts</para></listitem>
496 <para>The installation client (in both forms) provides a means
497 of querying the Imprints database server for a matching
498 list of known printer model names as well as a means to
499 download and install the drivers on remote Samba and Windows
500 NT print servers.</para>
502 <para>The basic installation process is in four steps and
503 perl code is wrapped around <command>smbclient</command>
504 and <command>rpcclient</command>.</para>
506 <para><programlisting>
507 foreach (supported architecture for a given driver)
509 1. rpcclient: Get the appropriate upload directory
511 2. smbclient: Upload the driver files
512 3. rpcclient: Issues an AddPrinterDriver() MS-RPC
515 4. rpcclient: Issue an AddPrinterEx() MS-RPC to actually
517 </programlisting></para>
519 <para>One of the problems encountered when implementing
520 the Imprints tool set was the name space issues between
521 various supported client architectures. For example, Windows
522 NT includes a driver named "Apple LaserWriter II NTX v51.8"
523 and Windows 95 calls its version of this driver "Apple
524 LaserWriter II NTX"</para>
526 <para>The problem is how to know what client drivers have
527 been uploaded for a printer. As astute reader will remember
528 that the Windows NT Printer Properties dialog only includes
529 space for one printer driver name. A quick look in the
530 Windows NT 4.0 system registry at</para>
532 <para><filename>HKLM\System\CurrentControlSet\Control\Print\Environment
535 <para>will reveal that Windows NT always uses the NT driver
536 name. This is ok as Windows NT always requires that at least
537 the Windows NT version of the printer driver is present.
538 However, Samba does not have the requirement internally.
539 Therefore, how can you use the NT driver name if is has not
540 already been installed?</para>
542 <para>The way of sidestepping this limitation is to require
543 that all Imprints printer driver packages include both the Intel
544 Windows NT and 95/98 printer drivers and that NT driver is
545 installed first.</para>
552 <title><anchor id="MIGRATION">Migration to from Samba 2.0.x to 2.2.x</title>
555 Given that printer driver management has changed (we hope improved) in
556 2.2 over prior releases, migration from an existing setup to 2.2 can
557 follow several paths. Here are the possible scenarios for
562 <listitem><para>If you do not desire the new Windows NT
563 print driver support, nothing needs to be done.
564 All existing parameters work the same.</para></listitem>
566 <listitem><para>If you want to take advantage of NT printer
567 driver support but do not want to migrate the
568 9x drivers to the new setup, the leave the existing
569 <filename>printers.def</filename> file. When smbd attempts
571 9x driver for the printer in the TDB and fails it
572 will drop down to using the printers.def (and all
573 associated parameters). The <command>make_printerdef</command>
574 tool will also remain for backwards compatibility but will
575 be removed in the next major release.</para></listitem>
577 <listitem><para>If you install a Windows 9x driver for a printer
578 on your Samba host (in the printing TDB), this information will
579 take precedence and the three old printing parameters
580 will be ignored (including print driver location).</para></listitem>
582 <listitem><para>If you want to migrate an existing <filename>printers.def</filename>
583 file into the new setup, the current only solution is to use the Windows
584 NT APW to install the NT drivers and the 9x drivers. This can be scripted
585 using <command>smbclient</command> and <command>rpcclient</command>. See the
586 Imprints installation client at <ulink
587 url="http://imprints.sourceforge.net/">http://imprints.sourceforge.net/</ulink>
594 <title>Achtung!</title>
597 The following <filename>smb.conf</filename> parameters are considered to
598 be deprecated and will be removed soon. Do not use them in new
603 <listitem><para><parameter>printer driver file (G)</parameter>
606 <listitem><para><parameter>printer driver (S)</parameter>
609 <listitem><para><parameter>printer driver location (S)</parameter>
616 The have been two new parameters add in Samba 2.2.2 to for
617 better support of Samba 2.0.x backwards capability (<parameter>disable
618 spoolss</parameter>) and for using local printers drivers on Windows
619 NT/2000 clients (<parameter>use client driver</parameter>). Both of
620 these options are described in the smb.coinf(5) man page and are
630 This comment from rpc_server/srv_spoolss_nt.c:_spoolss_open_printer_ex()
631 needs to be added into a section probably. This is to remind me it needs
635 * If the openprinterex rpc call contains a devmode,
636 * it's a per-user one. This per-user devmode is derivated
637 * from the global devmode. Openprinterex() contains a per-user
638 * devmode for when you do EMF printing and spooling.
639 * In the EMF case, the NT workstation is only doing half the job
640 * of rendering the page. The other half is done by running the printer
641 * driver on the server.
642 * The EMF file doesn't contain the page description (paper size, orientation, ...).
643 * The EMF file only contains what is to be printed on the page.
644 * So in order for the server to know how to print, the NT client sends
645 * a devicemode attached to the openprinterex call.
646 * But this devicemode is short lived, it's only valid for the current print job.
648 * If Samba would have supported EMF spooling, this devicemode would
649 * have been attached to the handle, to sent it to the driver to correctly
650 * rasterize the EMF file.
652 * As Samba only supports RAW spooling, we only receive a ready-to-print file,
653 * we just act as a pass-thru between windows and the printer.
655 * In order to know that Samba supports only RAW spooling, NT has to call
656 * getprinter() at level 2 (attribute field) or NT has to call startdoc()
657 * and until NT sends a RAW job, we refuse it.
659 * But to call getprinter() or startdoc(), you first need a valid handle,
660 * and to get an handle you have to call openprintex(). Hence why you have
661 * a devicemode in the openprinterex() call.
664 * Differences between NT4 and NT 2000.
667 * On NT4, you only have a global devicemode. This global devicemode can be changed
668 * by the administrator (or by a user with enough privs). Every time a user
669 * wants to print, the devicemode is reset to the default. In Word, every time
670 * you print, the printer's characteristics are always reset to the global devicemode.
674 * In W2K, there is the notion of per-user devicemode. The first time you use
675 * a printer, a per-user devicemode is build from the global devicemode.
676 * If you change your per-user devicemode, it is saved in the registry, under the
677 * H_KEY_CURRENT_KEY sub_tree. So that every time you print, you have your default
678 * printer preferences available.
680 * To change the per-user devicemode: it's the "Printing Preferences ..." button
681 * on the General Tab of the printer properties windows.
683 * To change the global devicemode: it's the "Printing Defaults..." button
684 * on the Advanced Tab of the printer properties window.