6 <firstname>Gerald (Jerry)
</firstname><surname>Carter
</surname>
8 <orgname>Samba Team
</orgname>
10 <email>jerry@samba.org
</email>
16 <pubdate> (
20 Apr
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>
62 <title>Configuration
</title>
65 <emphasis>WARNING!!!
</emphasis> Previous versions of Samba
66 recommended using a share named [printer$]. This name was taken from the
67 printer$ service created by Windows
9x clients when a
68 printer was shared. Windows
9x printer servers always have
69 a printer$ service which provides read-only access via no
70 password in order to support printer driver downloads.
74 However, the initial implementation allowed for a
75 parameter named
<parameter>printer driver location
</parameter>
76 to be used on a per share basis to specify the location of
77 the driver files associated with that printer. Another
78 parameter named
<parameter>printer driver
</parameter> provided
79 a means of defining the printer driver name to be sent to
84 These parameters, including
<parameter>printer driver
85 file
</parameter> parameter, are being depreciated and should not
86 be used in new installations. For more information on this change,
87 you should refer to the
<link linkend=
"MIGRATION">Migration section
88 </link>of this document.
93 <title>Creating [print$]
</title>
96 In order to support the uploading of printer driver
97 files, you must first configure a file share named [print$].
98 The name of this share is hard coded in Samba's internals so
99 the name is very important (print$ is the service used by
100 Windows NT print servers to provide support for printer driver
104 <para>You should modify the server's smb.conf file to create the
105 following file share (of course, some of the parameter values,
106 such as 'path' are arbitrary and should be replaced with
107 appropriate values for your site):
</para>
109 <para><programlisting>
111 path = /usr/local/samba/printers
116 </programlisting></para>
118 <para>The
<ulink url=
"smb.conf.5.html#WRITELIST"><parameter>
119 write list
</parameter></ulink> is used to allow administrative
120 level user accounts to have write access in order to update files
121 on the share. See the
<ulink url=
"smb./conf.5.html">
122 smb.conf(
5) man page
</ulink> for more information on
123 configuring file shares.
</para>
125 <para>The requirement for
<ulink url=
"smb.conf.5.html#GUESTOK"><command>
126 guest ok = yes
</command></ulink> depends upon how your
127 site is configured. If users will be guaranteed to have
128 an account on the Samba host, then this is a non-issue.
</para>
131 <title>Author's Note
</title>
134 The non-issue is that if all your Windows NT users are guaranteed to be
135 authenticated by the Samba server (such as a domain member server and the NT
136 user has already been validated by the Domain Controller in
137 order to logon to the Windows NT console), then guest access
138 is not necessary. Of course, in a workgroup environment where
139 you just want to be able to print without worrying about
140 silly accounts and security, then configure the share for
141 guest access. You'll probably want to add
<ulink
142 url=
"smb.conf.5.html#MAPTOGUEST"><command>map to guest = Bad User
143 </command></ulink> in the [global] section as well. Make sure
144 you understand what this parameter does before using it
149 <para>In order for a Windows NT print server to support
150 the downloading of driver files by multiple client architectures,
151 it must create subdirectories within the [print$] service
152 which correspond to each of the supported client architectures.
153 Samba follows this model as well.
</para>
155 <para>Next create the directory tree below the [print$] share
156 for each architecture you wish to support.
</para>
158 <para><programlisting>
160 |-W32X86 ;
"Windows NT x86"
161 |-WIN40 ;
"Windows 95/98"
162 |-W32ALPHA ;
"Windows NT Alpha_AXP"
163 |-W32MIPS ;
"Windows NT R4000"
164 |-W32PPC ;
"Windows NT PowerPC"
165 </programlisting></para>
168 <title>ATTENTION! REQUIRED PERMISSIONS
</title>
170 <para>In order to currently add a new driver to you Samba host,
171 one of two conditions must hold true:
</para>
174 <listitem><para>The account used to connect to the Samba host
175 must have a uid of
0 (i.e. a root account)
</para></listitem>
177 <listitem><para>The account used to connect to the Samba host
178 must be a member of the
<ulink
179 url=
"smb.conf.5.html#PRINTERADMIN"><parameter>printer
180 admin
</parameter></ulink> list.
</para></listitem>
183 <para>Of course, the connected account must still possess access
184 to add files to the subdirectories beneath [print$].
</para>
188 <para>Once you have created the required [print$] service and
189 associated subdirectories, simply log onto the Samba server using
190 a root (or
<parameter>printer admin
</parameter>) account
191 from a Windows NT
4.0 client. Navigate to the
"Printers" folder
192 on the Samba server. You should see an initial listing of printers
193 that matches the printer shares defined on your Samba host.
198 <title>Setting Drivers for Existing Printers
</title>
200 <para>The initial listing of printers in the Samba host's
201 Printers folder will have no printer driver assigned to them.
202 The way assign a driver to a printer is to view the Properties
203 of the printer and either
</para>
206 <listitem><para>Use the
"New Driver..." button to install
207 a new printer driver, or
</para></listitem>
209 <listitem><para>Select a driver from the popup list of
210 installed drivers. Initially this list will be empty.
</para>
214 <para>If you wish to install printer drivers for client
215 operating systems other than
"Windows NT x86", you will need
216 to use the
"Sharing" tab of the printer properties dialog.
</para>
218 <para>Assuming you have connected with a root account, you
219 will also be able modify other printer properties such as
220 ACLs and device settings using this dialog box.
</para>
222 <para>A few closing comments for this section, it is possible
223 on a Windows NT print server to have printers
224 listed in the Printers folder which are not shared. Samba does
225 not make this distinction. By definition, the only printers of
226 which Samba is aware are those which are specified as shares in
227 <filename>smb.conf
</filename>.
</para>
229 <para>Another interesting side note is that Windows NT clients do
230 not use the SMB printer share, but rather can print directly
231 to any printer on another Windows NT host using MS-RPC. This
232 of course assumes that the printing client has the necessary
233 privileges on the remote host serving the printer. The default
234 permissions assigned by Windows NT to a printer gives the
"Print"
235 permissions to the
"Everyone" well-known group.
242 <title>Support a large number of printers
</title>
244 <para>One issue that has arisen during the development
245 phase of Samba
2.2 is the need to support driver downloads for
246 100's of printers. Using the Windows NT APW is somewhat
247 awkward to say the list. If more than one printer are using the
248 same driver, the
<ulink url=
"rpcclient.1.html"><command>rpcclient's
249 setdriver command
</command></ulink> can be used to set the driver
250 associated with an installed driver. The following is example
251 of how this could be accomplished:
</para>
253 <para><programlisting>
254 <prompt>$
</prompt>rpcclient pogo -U root%secret -c
"enumdrivers"
255 Domain=[NARNIA] OS=[Unix] Server=[Samba
2.2.0-alpha3]
258 Printer Driver Info
1:
259 Driver Name: [HP LaserJet
4000 Series PS]
261 Printer Driver Info
1:
262 Driver Name: [HP LaserJet
2100 Series PS]
264 Printer Driver Info
1:
265 Driver Name: [HP LaserJet
4Si/
4SiMX PS]
267 <prompt>$
</prompt>rpcclient pogo -U root%secret -c
"enumprinters"
268 Domain=[NARNIA] OS=[Unix] Server=[Samba
2.2.0-alpha3]
270 name:[\\POGO\hp-print]
271 description:[POGO\\POGO\hp-print,NO DRIVER AVAILABLE FOR THIS PRINTER,]
274 <prompt>$
</prompt>rpcclient pogo -U root%bleaK.er \
275 <prompt>> </prompt> -c
"setdriver hp-print \"HP LaserJet
4000 Series PS\
""
276 Domain=[NARNIA] OS=[Unix] Server=[Samba
2.2.0-alpha3]
277 Successfully set hp-print to driver HP LaserJet
4000 Series PS.
278 </programlisting></para>
284 <title>Adding New Printers via the Windows NT APW
</title>
287 By default, Samba offers all printer shares defined in
<filename>smb.conf
</filename>
288 in the
"Printers..." folder. Also existing in this folder is the Windows NT
289 Add Printer Wizard icon. The APW will be show only if
293 <listitem><para>The connected user is able to successfully
294 execute an OpenPrinterEx(\\server) with administrative
295 priviledges (i.e. root or
<parameter>printer admin
</parameter>.
298 <listitem><para><ulink url=
"smb.conf.5.html#SHOWADDPRINTERWIZARD"><parameter>show
299 add printer wizard = yes
</parameter></ulink> (the default).
304 In order to be able to use the APW to successfully add a printer to a Samba
305 server, the
<ulink url=
"smb.conf.5.html#ADDPRINTERCOMMAND"><parameter>addprinter
306 command
</parameter></ulink> must have a defined value. The program
307 hook must successfully add the printer to the system (i.e.
308 <filename>/etc/printcap
</filename> or appropriate files) and
309 <filename>smb.conf
</filename> if necessary.
313 When using the APW from a client, if the named printer share does
314 not exist,
<command>smbd
</command> will execute the
<parameter>add printer
315 program
</parameter> and reparse to the
<filename>smb.conf
</filename>
316 to attempt to locate the new printer share. If the share is still not defined,
317 an error of
"Access Denied" is returned to the client. Note that the
318 <parameter>add printer program
</parameter> is executed undet the context
319 of the connected user, not necessarily a root account.
323 There is a complementing
<ulink url=
"smb.conf.5.html#DELETEPRINTERCOMMAND"><parameter>deleteprinter
324 command
</parameter></ulink> for removing entries from the
"Printers..."
332 <title>Samba and Printer Ports
</title>
335 Windows NT/
2000 print servers associate a port with each printer. These normally
336 take the form of LPT1:, COM1:, FILE:, etc... Samba must also support the
337 concept of ports associated with a printer. By default, only one printer port,
338 named
"Samba Printer Port", exists on a system. Samba does not really a port in
339 order to print, rather it is a requirement of Windows clients.
343 Note that Samba does not support the concept of
"Printer Pooling" internally
344 either. This is when a logical printer is assigned to multiple ports as
345 a form of load balancing or fail over.
349 If you require that multiple ports be defined for some reason,
350 <filename>smb.conf
</filename> possesses a
<ulink
351 url=
"smb.conf.5.html#ENUMPORTSCOMMAND"><parameter>enumports
352 command
</parameter></ulink> which can be used to define an external program
353 that generates a listing of ports on a system.
362 <title>The Imprints Toolset
</title>
364 <para>The Imprints tool set provides a UNIX equivalent of the
365 Windows NT Add Printer Wizard. For complete information, please
366 refer to the Imprints web site at
<ulink url=
"http://imprints.sourceforge.net/">
367 http://imprints.sourceforge.net/
</ulink> as well as the documentation
368 included with the imprints source distribution. This section will
369 only provide a brief introduction to the features of Imprints.
</para>
373 <title>What is Imprints?
</title>
375 <para>Imprints is a collection of tools for supporting the goals
379 <listitem><para>Providing a central repository information
380 regarding Windows NT and
95/
98 printer driver packages
</para>
383 <listitem><para>Providing the tools necessary for creating
384 the Imprints printer driver packages.
</para></listitem>
386 <listitem><para>Providing an installation client which
387 will obtain and install printer drivers on remote Samba
388 and Windows NT
4 print servers.
</para></listitem>
395 <title>Creating Printer Driver Packages
</title>
397 <para>The process of creating printer driver packages is beyond
398 the scope of this document (refer to Imprints.txt also included
399 with the Samba distribution for more information). In short,
400 an Imprints driver package is a gzipped tarball containing the
401 driver files, related INF files, and a control file needed by the
402 installation client.
</para>
407 <title>The Imprints server
</title>
409 <para>The Imprints server is really a database server that
410 may be queried via standard HTTP mechanisms. Each printer
411 entry in the database has an associated URL for the actual
412 downloading of the package. Each package is digitally signed
413 via GnuPG which can be used to verify that package downloaded
414 is actually the one referred in the Imprints database. It is
415 <emphasis>not
</emphasis> recommended that this security check
420 <title>The Installation Client
</title>
422 <para>More information regarding the Imprints installation client
423 is available in the
<filename>Imprints-Client-HOWTO.ps
</filename>
424 file included with the imprints source package.
</para>
426 <para>The Imprints installation client comes in two forms.
</para>
429 <listitem><para>a set of command line Perl scripts
</para>
432 <listitem><para>a GTK+ based graphical interface to
433 the command line perl scripts
</para></listitem>
436 <para>The installation client (in both forms) provides a means
437 of querying the Imprints database server for a matching
438 list of known printer model names as well as a means to
439 download and install the drivers on remote Samba and Windows
440 NT print servers.
</para>
442 <para>The basic installation process is in four steps and
443 perl code is wrapped around
<command>smbclient
</command>
444 and
<command>rpcclient
</command>.
</para>
446 <para><programlisting>
447 foreach (supported architecture for a given driver)
449 1. rpcclient: Get the appropriate upload directory
451 2. smbclient: Upload the driver files
452 3. rpcclient: Issues an AddPrinterDriver() MS-RPC
455 4. rpcclient: Issue an AddPrinterEx() MS-RPC to actually
457 </programlisting></para>
459 <para>One of the problems encountered when implementing
460 the Imprints tool set was the name space issues between
461 various supported client architectures. For example, Windows
462 NT includes a driver named
"Apple LaserWriter II NTX v51.8"
463 and Windows
95 callsits version of this driver
"Apple
464 LaserWriter II NTX"</para>
466 <para>The problem is how to know what client drivers have
467 been uploaded for a printer. As astute reader will remember
468 that the Windows NT Printer Properties dialog only includes
469 space for one printer driver name. A quick look in the
470 Windows NT
4.0 system registry at
</para>
472 <para><filename>HKLM\System\CurrentControlSet\Control\Print\Environment
475 <para>will reveal that Windows NT always uses the NT driver
476 name. The is ok as Windows NT always requires that at least
477 the Windows NT version of the printer driver is present.
478 However, Samba does not have the requirement internally.
479 Therefore, how can you use the NT driver name if is has not
480 already been installed?
</para>
482 <para>The way of sidestepping this limitation is to require
483 that all Imprints printer driver packages include both the Intel
484 Windows NT and
95/
98 printer drivers and that NT driver is
485 installed first.
</para>
492 <title><anchor id=
"MIGRATION">Migration to from Samba
2.0.x to
495 <para>Given that printer driver management has changed
496 (we hope improved :) ) in
2.2.0 over prior releases,
497 migration from an existing setup to
2.2.0 can follow
498 several paths.
</para>
501 <title>Achtung!
</title>
502 <para>The following smb.conf parameters are considered to be
503 depreciated and will be removed soon. Do not use them
504 in new installations
</para>
507 <listitem><para><parameter>printer driver file (G)
</parameter>
510 <listitem><para><parameter>printer driver (S)
</parameter>
513 <listitem><para><parameter>printer driver location (S)
</parameter>
519 <para>Here are the possible scenarios for supporting migration:
</para>
522 <listitem><para>If you do not desire the new Windows NT
523 print driver support, nothing needs to be done.
524 All existing parameters work the same.
</para></listitem>
526 <listitem><para>If you want to take advantage of NT printer
527 driver support but do not want to migrate the
528 9x drivers to the new setup, the leave the existing
529 printers.def file. When smbd attempts to locate a
530 9x driver for the printer in the TDB and fails it
531 will drop down to using the printers.def (and all
532 associated parameters). The
<command>make_printerdef
</command>
533 tool will also remain for backwards compatibility but will
534 be moved to the
"this tool is the old way of doing it"
535 pile.
</para></listitem>
537 <listitem><para>If you install a Windows
9x driver for a printer
538 on your Samba host (in the printing TDB), this information will
539 take precedence and the three old printing parameters
540 will be ignored (including print driver location).
</para></listitem>
542 <listitem><para>If you want to migrate an existing
<filename>printers.def
</filename>
543 file into the new setup, the current only
544 solution is to use the Windows NT APW to install the NT drivers
545 and the
9x drivers. This can be scripted using
<command>smbclient
</command>
546 and
<command>rpcclient
</command>. See the
547 Imprints installation client at
<ulink
548 url=
"http://imprints.sourceforge.net/">http://imprints.sourceforge.net/
</ulink>