another merge from 2.2

(This used to be commit f8e4876a04add168a17652431e85a9c2b5b6c619)

1 files changed, 555 insertions, 0 deletions

diff --git a/docs/docbook/projdoc/printer_driver2.sgml b/docs/docbook/projdoc/printer_driver2.sgml
new file mode 100644
index 0000000000..7f0aebc45f
--- /dev/null
+++ b/docs/docbook/projdoc/printer_driver2.sgml
@@ -0,0 +1,555 @@
+<chapter>
+
+
+<chapterinfo>
+	<author>
+		<firstname>Gerald (Jerry)</firstname><surname>Carter</surname>
+		<affiliation>
+			<orgname>Samba Team</orgname>
+			<address>
+				<email>jerry@samba.org</email>
+			</address>
+		</affiliation>
+	</author>
+	
+		
+	<pubdate> (20 Apr 2001) </pubdate>
+</chapterinfo>
+
+<title>Printing Support in Samba 2.2.x</title>
+
+<sect1>
+<title>Introduction</title>
+	
+<para>Beginning with the 2.2.0 release, Samba supports 
+the native Windows NT printing mechanisms implemented via 
+MS-RPC (i.e. the SPOOLSS named pipe).  Previous versions of 
+Samba only supported LanMan printing calls.</para>
+
+<para>The additional functionality provided by the new 
+SPOOLSS support includes:</para>
+	
+<itemizedlist>
+	<listitem><para>Support for downloading printer driver 
+	files to Windows 95/98/NT/2000 clients upon demand.
+	</para></listitem>
+	
+	<listitem><para>Uploading of printer drivers via the 
+	Windows NT Add Printer Wizard (APW) or the 
+	Imprints tool set (refer to <ulink 
+	url="http://imprints.sourceforge.net">http://imprints.sourceforge.net</ulink>). 
+	</para></listitem>
+		
+	<listitem><para>Support for the native MS-RPC printing 
+	calls such as StartDocPrinter, EnumJobs(), etc...  (See 
+	the MSDN documentation at <ulink 
+	url="http://msdn.microsoft.com/">http://msdn.microsoft.com/</ulink> 
+	for more information on the Win32 printing API)
+	</para></listitem>
+		
+	<listitem><para>Support for NT Access Control Lists (ACL) 
+	on printer objects</para></listitem>
+	
+	<listitem><para>Improved support for printer queue manipulation 
+	through the use of an internal databases for spooled job 
+	information</para></listitem>
+</itemizedlist>
+
+</sect1>
+
+
+<sect1>
+<title>Configuration</title>
+
+<para>
+<emphasis>WARNING!!!</emphasis> 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.
+</para>
+	
+<para>
+However, the initial implementation allowed for a 
+parameter named <parameter>printer driver location</parameter> 
+to be used on a per share basis to specify the location of 
+the driver files associated with that printer.  Another 
+parameter named <parameter>printer driver</parameter> provided 
+a means of defining the printer driver name to be sent to 
+the client.
+</para>
+ 
+<para>
+These parameters, including <parameter>printer driver 
+file</parameter> parameter, are being depreciated and should not 
+be used in new installations.  For more information on this change, 
+you should refer to the <link linkend="MIGRATION">Migration section 
+</link>of this document.
+</para>
+
+
+<sect2>
+<title>Creating [print$]</title>	
+
+<para>
+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).
+</para>
+
+<para>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):</para>
+
+<para><programlisting>
+[print$]
+    path = /usr/local/samba/printers
+    guest ok = yes
+    browseable = yes
+    read only = yes
+    write list = ntadmin
+</programlisting></para>
+	
+<para>The <ulink url="smb.conf.5.html#WRITELIST"><parameter>
+write list</parameter></ulink> is used to allow administrative 
+level user accounts to have write access in order to update files 
+on the share.  See the <ulink url="smb./conf.5.html">
+smb.conf(5) man page</ulink> for more information on 
+configuring file shares.</para>
+	
+<para>The requirement for <ulink url="smb.conf.5.html#GUESTOK"><command>
+guest ok = yes</command></ulink> 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.</para>
+
+<note>	
+<title>Author's Note</title>
+
+<para>
+The non-issue is that if all your Windows NT users are guaranteed 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 
+guest access.  You'll probably want to add <ulink 
+url="smb.conf.5.html#MAPTOGUEST"><command>map to guest = Bad User
+</command></ulink> in the [global] section as well.  Make sure 
+you understand what this parameter does before using it 
+though. --jerry
+</para>
+</note>
+
+<para>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.</para>
+
+<para>Next create the directory tree below the [print$] share 
+for each architecture you wish to support.</para>
+
+<para><programlisting>
+[print$]-----
+        |-W32X86           ; "Windows NT x86"
+        |-WIN40            ; "Windows 95/98"
+        |-W32ALPHA         ; "Windows NT Alpha_AXP"
+        |-W32MIPS          ; "Windows NT R4000"
+        |-W32PPC           ; "Windows NT PowerPC"
+</programlisting></para>
+
+<warning>
+	<title>ATTENTION!  REQUIRED PERMISSIONS</title>
+	
+	<para>In order to currently add a new driver to you Samba host, 
+	one of two conditions must hold true:</para>
+		
+	<itemizedlist>
+		<listitem><para>The account used to connect to the Samba host 
+		must have a uid of 0 (i.e. a root account)</para></listitem>
+		
+		<listitem><para>The account used to connect to the Samba host
+		must be a member of the <ulink 
+		url="smb.conf.5.html#PRINTERADMIN"><parameter>printer 
+		admin</parameter></ulink> list.</para></listitem>
+	</itemizedlist>
+
+	<para>Of course, the connected account must still possess access
+	to add files to the subdirectories beneath [print$].</para>
+</warning>
+
+
+<para>Once you have created the required [print$] service and 
+associated subdirectories, simply log onto the Samba server using 
+a root (or <parameter>printer admin</parameter>) 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.
+</para>
+</sect2>
+
+<sect2>
+<title>Setting Drivers for Existing Printers</title>
+
+<para>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</para>
+	
+<itemizedlist>
+	<listitem><para>Use the "New Driver..." button to install 
+	a new printer driver, or</para></listitem>
+	
+	<listitem><para>Select a driver from the popup list of 
+	installed drivers.  Initially this list will be empty.</para>
+	</listitem>
+</itemizedlist>
+	
+<para>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.</para>
+
+<para>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.</para>
+
+<para>A few closing comments for this section, 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
+<filename>smb.conf</filename>.</para>
+  
+<para>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.
+</para>
+
+</sect2>	
+
+
+<sect2>
+<title>Support a large number of printers</title>
+		
+<para>One issue that has arisen during the development
+phase of Samba 2.2 is the need to support driver downloads for
+100's of printers.  Using the Windows NT APW is somewhat 
+awkward to say the list.  If more than one printer are using the 
+same driver, the <ulink url="rpcclient.1.html"><command>rpcclient's
+setdriver command</command></ulink> can be used to set the driver
+associated with an installed driver.  The following is example
+of how this could be accomplished:</para>
+		
+<para><programlisting> 
+<prompt>$ </prompt>rpcclient pogo -U root%secret -c "enumdrivers"
+Domain=[NARNIA] OS=[Unix] Server=[Samba 2.2.0-alpha3]
+ 
+[Windows NT x86]
+Printer Driver Info 1:
+     Driver Name: [HP LaserJet 4000 Series PS]
+ 
+Printer Driver Info 1:
+     Driver Name: [HP LaserJet 2100 Series PS]
+ 
+Printer Driver Info 1:
+     Driver Name: [HP LaserJet 4Si/4SiMX PS]
+				  
+<prompt>$ </prompt>rpcclient pogo -U root%secret -c "enumprinters"
+Domain=[NARNIA] OS=[Unix] Server=[Samba 2.2.0-alpha3]
+     flags:[0x800000]
+     name:[\\POGO\hp-print]
+     description:[POGO\\POGO\hp-print,NO DRIVER AVAILABLE FOR THIS PRINTER,]
+     comment:[]
+				  
+<prompt>$ </prompt>rpcclient pogo -U root%bleaK.er \
+<prompt>&gt; </prompt> -c "setdriver hp-print \"HP LaserJet 4000 Series PS\""
+Domain=[NARNIA] OS=[Unix] Server=[Samba 2.2.0-alpha3]
+Successfully set hp-print to driver HP LaserJet 4000 Series PS.
+</programlisting></para>
+</sect2>
+
+
+
+<sect2>
+<title>Adding New Printers via the Windows NT APW</title>
+	
+<para>
+By default, Samba offers all printer shares defined in <filename>smb.conf</filename>
+in the "Printers..." folder.  Also existing in this folder is the Windows NT 
+Add Printer Wizard icon.  The APW will be show only if
+</para>
+
+<itemizedlist>
+	<listitem><para>The connected user is able to successfully
+	execute an OpenPrinterEx(\\server) with administrative
+	priviledges (i.e. root or <parameter>printer admin</parameter>.
+	</para></listitem>
+	
+	<listitem><para><ulink url="smb.conf.5.html#SHOWADDPRINTERWIZARD"><parameter>show 
+	add printer wizard = yes</parameter></ulink> (the default).
+	</para></listitem>
+</itemizedlist>
+
+<para>
+In order to be able to use the APW to successfully add a printer to a Samba 
+server, the <ulink url="smb.conf.5.html#ADDPRINTERCOMMAND"><parameter>addprinter 
+command</parameter></ulink> must have a defined value.  The program
+hook must successfully add the printer to the system (i.e. 
+<filename>/etc/printcap</filename> or appropriate files) and 
+<filename>smb.conf</filename> if necessary.
+</para>
+
+<para>
+When using the APW from a client, if the named printer share does 
+not exist, <command>smbd</command> will execute the <parameter>add printer 
+program</parameter> and reparse to the <filename>smb.conf</filename>
+to attempt to locate the new printer share.  If the share is still not defined,
+an error of "Access Denied" is returned to the client.  Note that the 
+<parameter>add printer program</parameter> is executed undet the context
+of the connected user, not necessarily a root account.
+</para>
+
+<para>
+There is a complementing <ulink url="smb.conf.5.html#DELETEPRINTERCOMMAND"><parameter>deleteprinter 
+command</parameter></ulink> for removing entries from the "Printers..."
+folder.
+</para>
+
+</sect2>
+
+
+<sect2>
+<title>Samba and Printer Ports</title>
+
+<para>
+Windows NT/2000 print servers associate a port with each printer.  These normally
+take the form of LPT1:, COM1:, FILE:, etc...  Samba must also support the
+concept of ports associated with a printer.  By default, only one printer port,
+named "Samba Printer Port", exists on a system.  Samba does not really a port in
+order to print, rather it is a requirement of Windows clients.  
+</para>
+
+<para>
+Note that Samba does not support the concept of "Printer Pooling" internally 
+either.  This is when a logical printer is assigned to multiple ports as 
+a form of load balancing or fail over.
+</para>
+
+<para>
+If you require that multiple ports be defined for some reason,
+<filename>smb.conf</filename> possesses a <ulink 
+url="smb.conf.5.html#ENUMPORTSCOMMAND"><parameter>enumports 
+command</parameter></ulink> which can be used to define an external program 
+that generates a listing of ports on a system.
+</para>
+
+</sect2>
+
+</sect1>
+
+
+<sect1>
+	<title>The Imprints Toolset</title>
+	
+	<para>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 <ulink url="http://imprints.sourceforge.net/">
+	http://imprints.sourceforge.net/</ulink> as well as the documentation 
+	included with the imprints source distribution.  This section will 
+	only provide a brief introduction to the features of Imprints.</para>
+	
+	
+	<sect2>
+		<title>What is Imprints?</title>
+
+		<para>Imprints is a collection of tools for supporting the goals 
+		of</para>
+		
+		<itemizedlist>
+			<listitem><para>Providing a central repository information 
+			regarding Windows NT and 95/98 printer driver packages</para>
+			</listitem>
+			
+			<listitem><para>Providing the tools necessary for creating 
+			the Imprints printer driver packages.</para></listitem>
+			
+			<listitem><para>Providing an installation client which 
+			will obtain and install printer drivers on remote Samba 
+			and Windows NT 4 print servers.</para></listitem>
+		</itemizedlist>
+		
+	</sect2>
+	
+	
+	<sect2>
+		<title>Creating Printer Driver Packages</title>
+		
+		<para>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.</para>
+	</sect2>
+	
+	
+	<sect2>
+		<title>The Imprints server</title>
+		
+		<para>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 
+		<emphasis>not</emphasis> recommended that this security check 
+		be disabled.</para>
+	</sect2>
+	
+	<sect2>
+		<title>The Installation Client</title>
+
+		<para>More information regarding the Imprints installation client 
+		is available in the <filename>Imprints-Client-HOWTO.ps</filename> 
+		file included with the imprints source package.</para>
+
+		<para>The Imprints installation client comes in two forms.</para>
+
+		<itemizedlist>
+			<listitem><para>a set of command line Perl scripts</para>
+			</listitem>
+			
+			<listitem><para>a GTK+ based graphical interface to 
+			the command line perl scripts</para></listitem>
+		</itemizedlist>
+		
+		<para>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.</para>
+
+		<para>The basic installation process is in four steps and 
+		perl code is wrapped around <command>smbclient</command> 
+		and <command>rpcclient</command>.</para>
+
+<para><programlisting>	
+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
+</programlisting></para>
+		
+		<para>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 callsits version of this driver "Apple 
+		LaserWriter II NTX"</para>
+		
+		<para>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.0 system registry at</para>
+	
+		<para><filename>HKLM\System\CurrentControlSet\Control\Print\Environment
+		</filename></para>
+		
+		<para>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?</para>
+		
+		<para>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.</para>
+	</sect2>
+	
+</sect1>
+
+
+<sect1>
+	<title><anchor id="MIGRATION">Migration to from Samba 2.0.x to 
+	2.2.x</title>
+	
+	<para>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.</para>
+	
+	<warning>
+		<title>Achtung!</title>
+		<para>The following smb.conf parameters are considered to be
+		depreciated and will be removed soon.  Do not use them
+		in new installations</para>
+		
+		<itemizedlist>
+			<listitem><para><parameter>printer driver file (G)</parameter>
+			</para></listitem>
+			
+			<listitem><para><parameter>printer driver (S)</parameter>
+			</para></listitem>
+			
+			<listitem><para><parameter>printer driver location (S)</parameter>
+			</para></listitem>
+		</itemizedlist>
+	</warning>
+
+
+	<para>Here are the possible scenarios for supporting migration:</para>
+	
+	<itemizedlist>
+		<listitem><para>If you do not desire the new Windows NT 
+		print driver support, nothing needs to be done.  
+		All existing parameters work the same.</para></listitem>
+
+		<listitem><para>If you want to take advantage of NT printer 
+		driver support but do 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 <command>make_printerdef</command> 
+		tool will also remain for backwards compatibility but will 
+		be moved to the "this tool is the old way of doing it" 
+		pile.</para></listitem>
+
+		<listitem><para>If you install 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).</para></listitem>
+
+		<listitem><para>If you want to migrate an existing <filename>printers.def</filename> 
+		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.  This can be scripted using <command>smbclient</command> 
+		and <command>rpcclient</command>.  See the 
+		Imprints installation client at <ulink 
+		url="http://imprints.sourceforge.net/">http://imprints.sourceforge.net/</ulink> 
+		for an example.
+		</para></listitem>
+	</itemizedlist>
+
+</sect1>
+
+</chapter>