First draft of new printing doc describing the SPOOLSS support in the

upcoming 2.2.0 release.

Needs some other eyes to review it.  :-)



jerry
(This used to be commit c9a76a2e10fd14fc1c63184afcda986163912b06)

1 files changed, 290 insertions, 0 deletions

diff --git a/docs/textdocs/PRINTER_DRIVER2.txt b/docs/textdocs/PRINTER_DRIVER2.txt
new file mode 100644
index 0000000000..f522942b07
--- /dev/null
+++ b/docs/textdocs/PRINTER_DRIVER2.txt
@@ -0,0 +1,290 @@
+
+!==
+!== PRINTER_DRIVER.txt for Samba release 2.2.0 14 Sep 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 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 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.
+
+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"
+
+
+These directories should be owned by an administrative account.
+Currently this must initially be an "root" account (uid = 0).
+
+!== 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/
+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
+
+	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 =======================================
+!=====================================================================