more autogen files from the latest SGML/DocBook checkins

[Samba/gbeck.git] / docs / textdocs / PRINTER_DRIVER2.txt

!==
!== PRINTER_DRIVER2.txt for Samba release 2.2.0-alpha1 23 Nov 2000
!==

==========================================================================
        Gerald Carter <jerry@samba.org> 14 Sep 2000
===========================================================================

Introduction
============
Beginning with the 2.2.0 release, Samba now supports the native Windows
NT printing mechanisms implemented via MS-RPC (i.e. the SPOOLSS named
pipe).  Previous versions of Samba only supported the LanMan printing 
calls.

The additional functionality provided by the new SPOOLSS support
includes:

        o       Support for downloading printer driver files to 
                Windows 95/98/NT/2000 clients upon demand.
        o       Uploading of printer drivers via the Windows NT
                Add Printer Wizard (APW) or the Imprints tool set
        o       Support for the native MS-RPC printing calls such
                as StartDocPrinter, EnumJobs(), etc...  (See the MSDN
                documentation for more information on the Win32
                printing API)
        o       Support for NT Access Control Lists (ACL) on 
                printer objects
        o       Improved support for printer queue manipulation through
                the use of an internal database for spooled job information.


Configuration
=============

In order to support the uploading of printer driver files, you 
must first configure a file share named [print$].  The name of 
this share is hard coded in Samba's internals so the name is 
very important (print$ is the service used by Windows NT 
print servers to provide support for printer driver download.

<aside>
  Previous versions of Samba recommended using a share named 
  [printer$].  This name was taken from the printer$ service 
  created by Windows 9x clients when a printer was shared.
  (Windows 9x printer servers always have a printer$ service
  which provides read-only access via no password in order to 
  support printer driver downloads).
  
  However, the initial implementation allowed for a parameter
  named 'printer driver location' to be used on a per share basis
  to specify the location of the driver files associated with that
  printer.  Another parameter named 'printer driver' provided a
  means of defining the printer driver name to be sent to the 
  client.
  
  These parameters, including 'printer driver file', are being
  depreciated and should not be used in new installations.
  For more information on this change, you should refer to the
  "Migration" section of this document.
</aside>

You should modify the server's smb.conf file to create the 
following file share (of course, some of the parameter values,
such as 'path' are arbitrary and should be replaced with
appropriate values for your site):

        [print$]
                        path = /usr/local/samba/printers
                        guest ok = yes
                        browseable = yes
                        read only = yes
                        write list = ntadmin

The 'write list' is used to allow administrative level user accounts
to have write access in order to update files on the share.
See the smb.conf(5) man page for more information on configuring
file shares.

The requirement for 'guest ok = yes' depends upon how your
site is configured.  If users will be guaranteed to have 
an account on the Samba host, then this is a non-issue.

  [author's note: The non-issue is that if all your Windows 
  NT users are guarenteed to be authenticated by the Samba server
  (such as a domain member server and the NT user has already
  been validated by the Domain Controller in order to logon
  to the Windows NT console), then guest access is not necessary.
  Of course, in a workgroup environment where you just want
  to be able to print without worrying about silly accounts
  and security, then configure the share for gues access.
  You'll probably want to add 'map to guest = Bad User'
  in the [global] section as well.  Make sure you understand
  what this parameter does before using it though. --jerry]

In order for a Windows NT print server to support the
downloading of driver files by multiple client architectures,
it must create subdirectories within the [print$] service
which correspond to each of the supported client architectures.
Samba follows this model as well.

Next create the directory tree below the [print$] share for
each architecture you wish to support.

        [print$]-----
                |-W32X86                ; "Windows NT x86"
                |-WIN40                 ; "Windows 95/98"
                |-W32ALPHA              ; "Windows NT Alpha_AXP"
                |-W32MIPS               ; "Windows NT R4000"
                |-W32PPC                ; "Windows NT PowerPC"


+++++++++++++ ATTENTION!  REQUIRED PERMISSIONS +++++++++++++++++

Currently, the connected user must have uid 0 in order to
successfully install a new printer driver.  There are two
points of authorization in this process.

        o       Access permissions to add files to the [print$]
                share.  This access control is managed using
                the same semantics as normal file shares.
                (i.e. filesystem permissions, write list, 
                writeable, etc...)

        o       Authorization to add entries to

                        $SAMBA/var/locks/ntdrivers.tdb

                Updates to this TDB are curently restricted
                to the root account.

Therefore, you must be connected to the samba host as the
root user in order to add a new printer driver.


++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

!== The Windows NT APW

Once you have created the required [print$] service and associated
subdirectories, simply log onto the Samba server using a root account
from a Windows NT 4.0 client.  Navigate to the "Printers" folder
on the Samba server.  You should see an initial listing of printers
that matches the printer shares defined on your Samba host.

<aside>
  It is possible on a Windows NT print server to have printers 
  listed in the Printers folder which are not shared.  Samba does
  not make this distinction.  By definition, the only printers of
  which Samba is aware are those which are specified as shares in
  smb.conf.
  
  Another interesting side note is that Windows NT clients do
  not use the SMB printer share, but rather can print directly 
  to any printer on another Windows NT host using MS-RPC.  This
  of course assumes that the printing client has the necessary
  privileges on the remote host serving the printer.  The default
  permissions assigned by Windows NT to a printer gives the "Print"
  permissions to the "Everyone" well-known group.
</aside>

The initial listing of printers in the Samba host's Printers
folder will have no printer driver assigned to them.  The way
assign a driver to a printer is to view the Properties of the 
printer and either 

        o       Use the "New Driver..." button to install a new printer
                driver, or
        o       Select a driver from the popup list of installed drivers.
                Initially this list will be empty.

If you wish to install printer drivers for client operating 
systems other than "Windows NT x86", you will need to use the
"Sharing" tab of the printer properties dialog.

Assuming you have connected with a root account, you will 
also be able modify other printer properties such as 
ACLs and device settings using this dialog box.


!== Imprints  

The Imprints tool set provides a UNIX equivalent of the Windows
NT Add Printer Wizard.  For complete information, please refer
to the Imprints web site at http://imprints.sourceforge.net/
as well as the documentation included with the imprints source
distribution.  This section will only provide a brief introduction 
to the features of Imprints.

What is Imprints?

        Imprints is a collection of tools for supporting the goals of
        
        o       Providing a central repository information regarding
                Windows NT and 95/98 printer driver packages
        o       Providing the tools necessary for creating the Imprints
                printer driver packages.
        o       Providing an installation client which will obtain
                and install printer drivers on remote Samba and Windows 
                NT 4 print servers.
        
                
Creating Printer Driver Packages

        The process of creating printer driver packages is beyond
        the scope of this document (refer to Imprints.txt also included
        with the Samba distribution for more information).  In short,
        an Imprints driver package is a gzipped tarball containing the
        driver files, related INF files, and a control file needed by the
        installation client.
        
The Imprints server

        The Imprints server is really a database server that may 
        be queried via standard HTTP mechanisms.  Each printer entry
        in the database has an associated URL for the actual
        downloading of the package.  Each package is digitally signed
        via GnuPG which can be used to verify that package downloaded
        is actually the one referred in the Imprints database.  It is 
        **not** recommended that this security check be disabled.
        
The Installation Client
<aside>
  More information regarding the Imprints installation client is available
  in the Imprints-Client-HOWTO.ps file included with the imprints source
  package.
</aside>

        The Imprints installation client comes in two forms.
        
        o       a set of command line Perl scripts
        o       a GTK+ based graphical interface to the command 
                line perl scripts
                
        The installation client (in both forms) provides a means
        of querying the Imprints database server for a matching
        list of known printer model names as well as a means to 
        download and install the drivers on remote Samba and Windows
        NT print servers.
        
        The basic installation process is in four steps and perl code
        is wrapped around smbclient and rpcclient.
        
        foreach (supported architecture for a given driver)
        {
                1.      rpcclient: Get the appropriate upload directory 
                        on the remote server
                2.      smbclient: Upload the driver files
                3.      rpcclient: Issues an AddPrinterDriver() MS-RPC
        }
        
        4.      rpcclient: Issue an AddPrinterEx() MS-RPC to actually
                create the printer
                
!== The printer driver name space problem

        One of the problems encountered when implementing the Imprints
        tool set was the name space issues between various supported
        client architectures.  For example, Windows NT includes a driver
        named "Apple LaserWriter II NTX v51.8" and Windows 95 calls
        its version of this driver "Apple LaserWriter II NTX"
        
        The problem is how to know what client drivers have been
        uploaded for a printer.  As astute reader will remember that
        the Windows NT Printer Properties dialog only includes space
        for one printer driver name.  A quick look in the Windows NT
        4 system registry at
        
                HKLM\System\CurrentControlSet\Control\Print\Environment
                
        will reveal that Windows NT always uses the NT driver name.
        The is ok as Windows NT always requires that at least the Windows
        NT version of the printer driver is present.  However, Samba
        does not have the requirement internally.  Therefore, how can
        you use the NT driver name if is has not already been installed?
        
        The way of sidestepping this limitation is to require that all
        Imprints printer driver packages include both the Intel Windows
        NT and 95/98 printer drivers and that NT driver is installed 
        first.


Migration to 2.2.x
=============================

Given that printer driver management has changed
(we hope improved :) ) in 2.2.0 over prior releases,
migration from an existing setup to 2.2.0 can follow
several paths.

<WARNING>
        The following smb.conf parameters are considered to be
        depreciated and will be removed soon.  Do not use them
        in new installations

        'printer driver file'     (G)
        'printer driver'          (S)
        'printer driver location' (S)
</WARNING>


Here are the possible scenarios for supporting migration:

        o       If you does not desire the new Windows NT 
                print driver support, nothing needs to be done.  
                All existing parameters work the same.

        o       If you want to take advantage of NT printer 
                driver support but does not want to migrate the 
                9x drivers to the new setup, the leave the existing 
                printers.def file.  When smbd attempts to locate a 
                9x driver for the printer in the TDB and fails it 
                will drop down to using the printers.def (and all 
                associated parameters).  The make_printerdef tool 
                will also remain for backwards compatibility but will 
                be moved to the "this tool is the old way of doing it" 
                pile.

        o       If you instal a Windows 9x driver for a printer on
                your Samba host (in the printing TDB), this information will 
                take precedence and the three old printing parameters
                will be ignored (including print driver location).

        o       If you want to migrate an existing printers.def file into
                the new setup, the current only solution is to use the
                Windows NT APW to install the NT drivers and the 9x 
                drivers.  (comment: this could possibly be scripted using 
                smbclient and rpcclient, but I haven't had time  --jerry)

!== end of PRINTER_DRIVER2.txt =======================================
!=====================================================================