path: root/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 =======================================
!=====================================================================