docs/docbook/projdoc/printer_driver2.sgml

   1 <chapter>
   2
   3
   4 <chapterinfo>
   5         <author>
   6                 <firstname>Gerald (Jerry)</firstname><surname>Carter</surname>
   7                 <affiliation>
   8                         <orgname>Samba Team</orgname>
   9                         <address>
  10                                 <email>jerry@samba.org</email>
  11                         </address>
  12                 </affiliation>
  13         </author>
  14
  15
  16         <pubdate> (20 Apr 2001) </pubdate>
  17 </chapterinfo>
  18
  19 <title>Printing Support in Samba 2.2.x</title>
  20
  21 <sect1>
  22 <title>Introduction</title>
  23
  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>
  28
  29 <para>The additional functionality provided by the new
  30 SPOOLSS support includes:</para>
  31
  32 <itemizedlist>
  33         <listitem><para>Support for downloading printer driver
  34         files to Windows 95/98/NT/2000 clients upon demand.
  35         </para></listitem>
  36
  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>).
  41         </para></listitem>
  42
  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)
  48         </para></listitem>
  49
  50         <listitem><para>Support for NT Access Control Lists (ACL)
  51         on printer objects</para></listitem>
  52
  53         <listitem><para>Improved support for printer queue manipulation
  54         through the use of an internal databases for spooled job
  55         information</para></listitem>
  56 </itemizedlist>
  57
  58 </sect1>
  59
  60
  61 <sect1>
  62 <title>Configuration</title>
  63
  64 <para>
  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.
  71 </para>
  72
  73 <para>
  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
  80 the client.
  81 </para>
  82
  83 <para>
  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.
  89 </para>
  90
  91
  92 <sect2>
  93 <title>Creating [print$]</title>
  94
  95 <para>
  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
 101 download).
 102 </para>
 103
 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>
 108
 109 <para><programlisting>
 110 [print$]
 111     path = /usr/local/samba/printers
 112     guest ok = yes
 113     browseable = yes
 114     read only = yes
 115     write list = ntadmin
 116 </programlisting></para>
 117
 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>
 124
 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>
 129
 130 <note>
 131 <title>Author's Note</title>
 132
 133 <para>
 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
 145 though. --jerry
 146 </para>
 147 </note>
 148
 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>
 154
 155 <para>Next create the directory tree below the [print$] share
 156 for each architecture you wish to support.</para>
 157
 158 <para><programlisting>
 159 [print$]-----
 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>
 166
 167 <warning>
 168         <title>ATTENTION!  REQUIRED PERMISSIONS</title>
 169
 170         <para>In order to currently add a new driver to you Samba host,
 171         one of two conditions must hold true:</para>
 172
 173         <itemizedlist>
 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>
 176
 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>
 181         </itemizedlist>
 182
 183         <para>Of course, the connected account must still possess access
 184         to add files to the subdirectories beneath [print$].</para>
 185 </warning>
 186
 187
 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.
 194 </para>
 195 </sect2>
 196
 197 <sect2>
 198 <title>Setting Drivers for Existing Printers</title>
 199
 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>
 204
 205 <itemizedlist>
 206         <listitem><para>Use the "New Driver..." button to install
 207         a new printer driver, or</para></listitem>
 208
 209         <listitem><para>Select a driver from the popup list of
 210         installed drivers.  Initially this list will be empty.</para>
 211         </listitem>
 212 </itemizedlist>
 213
 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>
 217
 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>
 221
 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>
 228
 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.
 236 </para>
 237
 238 </sect2>
 239
 240
 241 <sect2>
 242 <title>Support a large number of printers</title>
 243
 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>
 252
 253 <para><programlisting>
 254 <prompt>$ </prompt>rpcclient pogo -U root%secret -c "enumdrivers"
 255 Domain=[NARNIA] OS=[Unix] Server=[Samba 2.2.0-alpha3]
 256
 257 [Windows NT x86]
 258 Printer Driver Info 1:
 259      Driver Name: [HP LaserJet 4000 Series PS]
 260
 261 Printer Driver Info 1:
 262      Driver Name: [HP LaserJet 2100 Series PS]
 263
 264 Printer Driver Info 1:
 265      Driver Name: [HP LaserJet 4Si/4SiMX PS]
 266
 267 <prompt>$ </prompt>rpcclient pogo -U root%secret -c "enumprinters"
 268 Domain=[NARNIA] OS=[Unix] Server=[Samba 2.2.0-alpha3]
 269      flags:[0x800000]
 270      name:[\\POGO\hp-print]
 271      description:[POGO\\POGO\hp-print,NO DRIVER AVAILABLE FOR THIS PRINTER,]
 272      comment:[]
 273
 274 <prompt>$ </prompt>rpcclient pogo -U root%bleaK.er \
 275 <prompt>&gt; </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>
 279 </sect2>
 280
 281
 282
 283 <sect2>
 284 <title>Adding New Printers via the Windows NT APW</title>
 285
 286 <para>
 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
 290 </para>
 291
 292 <itemizedlist>
 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>.
 296         </para></listitem>
 297
 298         <listitem><para><ulink url="smb.conf.5.html#SHOWADDPRINTERWIZARD"><parameter>show
 299         add printer wizard = yes</parameter></ulink> (the default).
 300         </para></listitem>
 301 </itemizedlist>
 302
 303 <para>
 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.
 310 </para>
 311
 312 <para>
 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.
 320 </para>
 321
 322 <para>
 323 There is a complementing <ulink url="smb.conf.5.html#DELETEPRINTERCOMMAND"><parameter>deleteprinter
 324 command</parameter></ulink> for removing entries from the "Printers..."
 325 folder.
 326 </para>
 327
 328 </sect2>
 329
 330
 331 <sect2>
 332 <title>Samba and Printer Ports</title>
 333
 334 <para>
 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.
 340 </para>
 341
 342 <para>
 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.
 346 </para>
 347
 348 <para>
 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.
 354 </para>
 355
 356 </sect2>
 357
 358 </sect1>
 359
 360
 361 <sect1>
 362         <title>The Imprints Toolset</title>
 363
 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>
 370
 371
 372         <sect2>
 373                 <title>What is Imprints?</title>
 374
 375                 <para>Imprints is a collection of tools for supporting the goals
 376                 of</para>
 377
 378                 <itemizedlist>
 379                         <listitem><para>Providing a central repository information
 380                         regarding Windows NT and 95/98 printer driver packages</para>
 381                         </listitem>
 382
 383                         <listitem><para>Providing the tools necessary for creating
 384                         the Imprints printer driver packages.</para></listitem>
 385
 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>
 389                 </itemizedlist>
 390
 391         </sect2>
 392
 393
 394         <sect2>
 395                 <title>Creating Printer Driver Packages</title>
 396
 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>
 403         </sect2>
 404
 405
 406         <sect2>
 407                 <title>The Imprints server</title>
 408
 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
 416                 be disabled.</para>
 417         </sect2>
 418
 419         <sect2>
 420                 <title>The Installation Client</title>
 421
 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>
 425
 426                 <para>The Imprints installation client comes in two forms.</para>
 427
 428                 <itemizedlist>
 429                         <listitem><para>a set of command line Perl scripts</para>
 430                         </listitem>
 431
 432                         <listitem><para>a GTK+ based graphical interface to
 433                         the command line perl scripts</para></listitem>
 434                 </itemizedlist>
 435
 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>
 441
 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>
 445
 446 <para><programlisting>
 447 foreach (supported architecture for a given driver)
 448 {
 449      1.  rpcclient: Get the appropriate upload directory
 450          on the remote server
 451      2.  smbclient: Upload the driver files
 452      3.  rpcclient: Issues an AddPrinterDriver() MS-RPC
 453 }
 454
 455 4.  rpcclient: Issue an AddPrinterEx() MS-RPC to actually
 456     create the printer
 457 </programlisting></para>
 458
 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>
 465
 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>
 471
 472                 <para><filename>HKLM\System\CurrentControlSet\Control\Print\Environment
 473                 </filename></para>
 474
 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>
 481
 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>
 486         </sect2>
 487
 488 </sect1>
 489
 490
 491 <sect1>
 492         <title><anchor id="MIGRATION">Migration to from Samba 2.0.x to
 493         2.2.x</title>
 494
 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>
 499
 500         <warning>
 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>
 505
 506                 <itemizedlist>
 507                         <listitem><para><parameter>printer driver file (G)</parameter>
 508                         </para></listitem>
 509
 510                         <listitem><para><parameter>printer driver (S)</parameter>
 511                         </para></listitem>
 512
 513                         <listitem><para><parameter>printer driver location (S)</parameter>
 514                         </para></listitem>
 515                 </itemizedlist>
 516         </warning>
 517
 518
 519         <para>Here are the possible scenarios for supporting migration:</para>
 520
 521         <itemizedlist>
 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>
 525
 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>
 536
 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>
 541
 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>
 549                 for an example.
 550                 </para></listitem>
 551         </itemizedlist>
 552
 553 </sect1>
 554
 555 </chapter>