Docbook XML conversion: projdoc

(This used to be commit f7c9df751459da2d4a996d5f0135334fb3f87f69)

1 files changed, 1038 insertions, 0 deletions

diff --git a/docs/docbook/projdoc/printer_driver2.xml b/docs/docbook/projdoc/printer_driver2.xml
new file mode 100644
index 0000000000..da3eb838f2
--- /dev/null
+++ b/docs/docbook/projdoc/printer_driver2.xml
@@ -0,0 +1,1038 @@
+<chapter id="printing">
+
+<chapterinfo>
+	&author.jerry;
+	<author>
+		<firstname>Patrick</firstname><surname>Powell</surname>
+		<affiliation>
+			<address><email>papowell@lprng.org</email></address>
+		</affiliation>
+	</author>
+	<pubdate> (3 May 2001) </pubdate>
+</chapterinfo>
+
+<title>Printing Support</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>
+
+<para>
+There has been some initial confusion about what all this means
+and whether or not it is a requirement for printer drivers to be 
+installed on a Samba host in order to support printing from Windows 
+clients. As a side note, Samba does not use these drivers in any way to process 
+spooled files.  They are utilized entirely by the clients.
+</para>
+
+<para>
+The following MS KB article, may be of some help if you are dealing with
+Windows 2000 clients:  <emphasis>How to Add Printers with No User 
+Interaction in Windows 2000</emphasis>
+</para>
+
+<para>
+<ulink url="http://support.microsoft.com/support/kb/articles/Q189/1/05.ASP">http://support.microsoft.com/support/kb/articles/Q189/1/05.ASP</ulink>
+</para>
+
+</sect1>
+
+
+<sect1>
+<title>Configuration</title>
+
+<warning>
+<title>[print$] vs. [printer$]</title>
+
+<para>
+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>
+
+</warning>
+ 
+<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 add the global
+parameters and 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>
+[global]
+    ; members of the ntadmin group should be able
+    ; to add drivers and set printer properties
+    ; root is implicitly a 'printer admin'
+    printer admin = @ntadmin
+
+[print$]
+    path = /usr/local/samba/printers
+    guest ok = yes
+    browseable = yes
+    read only = yes
+    ; since this share is configured as read only, then we need
+    ; a 'write list'.  Check the file system permissions to make
+    ; sure this account can copy files to the share.  If this
+    ; is setup to a non-root account, then it should also exist
+    ; as a 'printer admin'
+    write list = @ntadmin,root
+</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><computeroutput>
+[print$]-----
+        |-W32X86           ; "Windows NT x86"
+        |-WIN40            ; "Windows 95/98"
+        |-W32ALPHA         ; "Windows NT Alpha_AXP"
+        |-W32MIPS          ; "Windows NT R4000"
+        |-W32PPC           ; "Windows NT PowerPC"
+</computeroutput></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$]. Remember
+that all file shares are set to 'read only' by default.
+</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/2k client.  Open "Network Neighbourhood" or
+"My Network Places" and browse for the Samba host.  Once you have located
+the server, navigate to the "Printers..." folder.
+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 real printer driver assigned 
+to them. This defaults to a NULL string to allow the use
+of the local Add Printer Wizard on NT/2000 clients.
+Attempting to view the printer properties for a printer
+which has this default driver assigned will result in 
+the error message:</para>
+
+<para>
+<emphasis>Device settings cannot be displayed.  The driver 
+for the specified printer is not installed, only spooler 
+properties will be displayed.  Do you want to install the 
+driver now?</emphasis>
+</para>
+
+<para>
+Click "No" in the error dialog and you will be presented with
+the printer properties window.  The way to assign a driver to a 
+printer is to 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>
+<prompt>$ </prompt><userinput>rpcclient pogo -U root%secret -c "enumdrivers"</userinput>
+<programlisting> 
+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]
+</programlisting>				  
+<prompt>$ </prompt><userinput>rpcclient pogo -U root%secret -c "enumprinters"</userinput>
+<programlisting>
+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:[]
+				  
+</programlisting>
+<prompt>$ </prompt><userinput>rpcclient pogo -U root%secret -c "setdriver hp-print \"HP LaserJet 4000 Series PS\""</userinput>
+<programlisting>
+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
+	privileges (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>add 
+printer 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 
+command</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 under the context
+of the connected user, not necessarily a root account.
+</para>
+
+<para>
+There is a complementary <ulink url="smb.conf.5.html#DELETEPRINTERCOMMAND"><parameter>delete
+printer command</parameter></ulink> for removing entries from the "Printers..."
+folder.
+</para>
+
+<para>
+The following is an example <ulink url="smb.conf.5.html#ADDPRINTERCOMMAN"><parameter>add printer command</parameter></ulink> script. It adds the appropriate entries to <filename>/etc/printcap.local</filename> (change that to what you need) and returns a line of 'Done' which is needed for the whole process to work.
+</para>
+
+<programlisting>
+#!/bin/sh
+
+# Script to insert a new printer entry into printcap.local
+#
+# $1, printer name, used as the descriptive name
+# $2, share name, used as the printer name for Linux
+# $3, port name
+# $4, driver name
+# $5, location, used for the device file of the printer
+# $6, win9x location
+
+#
+# Make sure we use the location that RedHat uses for local printer defs
+PRINTCAP=/etc/printcap.local
+DATE=`date +%Y%m%d-%H%M%S`
+LP=lp
+RESTART="service lpd restart"
+
+# Keep a copy
+cp $PRINTCAP $PRINTCAP.$DATE
+# Add the printer to $PRINTCAP
+echo ""				 			>> $PRINTCAP
+echo "$2|$1:\\" 					>> $PRINTCAP
+echo "  :sd=/var/spool/lpd/$2:\\" 			>> $PRINTCAP
+echo "  :mx=0:ml=0:sh:\\" 				>> $PRINTCAP
+echo "  :lp=/usr/local/samba/var/print/$5.prn:" 	>> $PRINTCAP
+
+touch "/usr/local/samba/var/print/$5.prn" >> /tmp/printadd.$$ 2>&amp;1
+chown $LP "/usr/local/samba/var/print/$5.prn" >> /tmp/printadd.$$ 2>&amp;1
+
+mkdir /var/spool/lpd/$2
+chmod 700 /var/spool/lpd/$2
+chown $LP /var/spool/lpd/$2
+#echo $1 >> "/usr/local/samba/var/print/$5.prn"
+#echo $2 >> "/usr/local/samba/var/print/$5.prn"
+#echo $3 >> "/usr/local/samba/var/print/$5.prn"
+#echo $4 >> "/usr/local/samba/var/print/$5.prn"
+#echo $5 >> "/usr/local/samba/var/print/$5.prn"
+#echo $6 >> "/usr/local/samba/var/print/$5.prn"
+$RESTART >> "/usr/local/samba/var/print/$5.prn"
+# Not sure if this is needed
+touch /usr/local/samba/lib/smb.conf
+#
+# You need to return a value, but I am not sure what it means.
+#
+echo "Done"
+exit 0
+</programlisting>
+
+</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 calls its 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.  This 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>
+
+<!--
+
+  This comment from rpc_server/srv_spoolss_nt.c:_spoolss_open_printer_ex()
+  needs to be added into a section probably.  This is to remind me it needs 
+  to be done.  -jerry
+
+                /*
+                 * If the openprinterex rpc call contains a devmode,
+                 * it's a per-user one. This per-user devmode is derivated
+                 * from the global devmode. Openprinterex() contains a per-user
+                 * devmode for when you do EMF printing and spooling.
+                 * In the EMF case, the NT workstation is only doing half the job
+                 * of rendering the page. The other half is done by running the printer
+                 * driver on the server.
+                 * The EMF file doesn't contain the page description (paper size, orientation, ...).
+                 * The EMF file only contains what is to be printed on the page.
+                 * So in order for the server to know how to print, the NT client sends
+                 * a devicemode attached to the openprinterex call.
+                 * But this devicemode is short lived, it's only valid for the current print job.
+                 *
+                 * If Samba would have supported EMF spooling, this devicemode would
+                 * have been attached to the handle, to sent it to the driver to correctly
+                 * rasterize the EMF file.
+                 *
+                 * As Samba only supports RAW spooling, we only receive a ready-to-print file,
+                 * we just act as a pass-thru between windows and the printer.
+                 *
+                 * In order to know that Samba supports only RAW spooling, NT has to call
+                 * getprinter() at level 2 (attribute field) or NT has to call startdoc()
+                 * and until NT sends a RAW job, we refuse it.
+                 *
+                 * But to call getprinter() or startdoc(), you first need a valid handle,
+                 * and to get an handle you have to call openprintex(). Hence why you have
+                 * a devicemode in the openprinterex() call.
+                 *
+                 *
+                 * Differences between NT4 and NT 2000.
+                 * NT4:
+                 * 
+                 * On NT4, you only have a global devicemode. This global devicemode can be changed
+                 * by the administrator (or by a user with enough privs). Every time a user
+                 * wants to print, the devicemode is reset to the default. In Word, every time
+                 * you print, the printer's characteristics are always reset to the global devicemode.
+                 *
+                 * NT 2000:
+                 * 
+                 * In W2K, there is the notion of per-user devicemode. The first time you use
+                 * a printer, a per-user devicemode is build from the global devicemode.
+                 * If you change your per-user devicemode, it is saved in the registry, under the
+                 * H_KEY_CURRENT_KEY sub_tree. So that every time you print, you have your default
+                 * printer preferences available.
+                 *
+                 * To change the per-user devicemode: it's the "Printing Preferences ..." button
+                 * on the General Tab of the printer properties windows.
+                 *
+                 * To change the global devicemode: it's the "Printing Defaults..." button
+                 * on the Advanced Tab of the printer properties window.
+-->
+
+<sect1>
+<title>Diagnosis</title>
+
+<sect2>
+<title>Introduction</title>
+
+<para>
+This is a short description of how to debug printing problems with
+Samba. This describes how to debug problems with printing from a SMB
+client to a Samba server, not the other way around. For the reverse
+see the examples/printing directory.
+</para>
+
+<para>
+Ok, so you want to print to a Samba server from your PC. The first
+thing you need to understand is that Samba does not actually do any
+printing itself, it just acts as a middleman between your PC client
+and your Unix printing subsystem. Samba receives the file from the PC
+then passes the file to a external "print command". What print command
+you use is up to you.
+</para>
+
+<para>
+The whole things is controlled using options in smb.conf. The most
+relevant options (which you should look up in the smb.conf man page)
+are:
+</para>
+
+<para><programlisting>
+      [global]
+        print command     - send a file to a spooler
+        lpq command       - get spool queue status
+        lprm command      - remove a job
+      [printers]
+        path = /var/spool/lpd/samba
+</programlisting></para>
+
+<para>
+The following are nice to know about:
+</para>
+
+<para><programlisting>
+        queuepause command   - stop a printer or print queue
+        queueresume command  - start a printer or print queue
+</programlisting></para>
+
+<para>
+Example:
+</para>
+
+<para><programlisting>
+        print command = /usr/bin/lpr -r -P%p %s
+        lpq command   = /usr/bin/lpq    -P%p %s
+        lprm command  = /usr/bin/lprm   -P%p %j
+        queuepause command = /usr/sbin/lpc -P%p stop
+        queuepause command = /usr/sbin/lpc -P%p start
+</programlisting></para>
+
+<para>
+Samba should set reasonable defaults for these depending on your
+system type, but it isn't clairvoyant. It is not uncommon that you
+have to tweak these for local conditions.  The commands should
+always have fully specified pathnames,  as the smdb may not have
+the correct PATH values.
+</para>
+
+<para>
+When you send a job to Samba to be printed,  it will make a temporary
+copy of it in the directory specified in the [printers] section.
+and it should be periodically cleaned out.  The lpr -r option
+requests that the temporary copy be removed after printing; If
+printing fails then you might find leftover files in this directory,
+and it should be periodically cleaned out.  Samba used the lpq
+command to determine the "job number" assigned to your print job
+by the spooler.
+</para>
+
+<para>
+The %&gt;letter&lt; are "macros" that get dynamically replaced with appropriate
+values when they are used. The %s gets replaced with the name of the spool
+file that Samba creates and the %p gets replaced with the name of the
+printer. The %j gets replaced with the "job number" which comes from
+the lpq output.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Debugging printer problems</title>
+
+<para>
+One way to debug printing problems is to start by replacing these
+command with shell scripts that record the arguments and the contents
+of the print file. A simple example of this kind of things might
+be:
+</para>
+
+<para><programlisting>
+	print command = /tmp/saveprint %p %s
+
+    #!/bin/saveprint
+    # we make sure that we are the right user
+    /usr/bin/id -p >/tmp/tmp.print
+    # we run the command and save the error messages
+    # replace the command with the one appropriate for your system
+    /usr/bin/lpr -r -P$1 $2 2>>&amp;/tmp/tmp.print
+</programlisting></para>
+
+<para>
+Then you print a file and try removing it.  You may find that the
+print queue needs to be stopped in order to see the queue status
+and remove the job:
+</para>
+
+<para><programlisting>
+
+h4: {42} % echo hi >/tmp/hi
+h4: {43} % smbclient //localhost/lw4
+added interface ip=10.0.0.4 bcast=10.0.0.255 nmask=255.255.255.0
+Password: 
+Domain=[ASTART] OS=[Unix] Server=[Samba 2.0.7]
+smb: \> print /tmp/hi
+putting file /tmp/hi as hi-17534 (0.0 kb/s) (average 0.0 kb/s)
+smb: \> queue
+1049     3            hi-17534
+smb: \> cancel 1049
+Error cancelling job 1049 : code 0
+smb: \> cancel 1049
+Job 1049 cancelled
+smb: \> queue
+smb: \> exit
+</programlisting></para>
+
+<para>
+The 'code 0' indicates that the job was removed.  The comment
+by the  smbclient is a bit misleading on this.
+You can observe the command output and then and look at the
+/tmp/tmp.print file to see what the results are.  You can quickly
+find out if the problem is with your printing system.  Often people
+have problems with their /etc/printcap file or permissions on
+various print queues.
+</para>
+</sect2>
+
+<sect2>
+<title>What printers do I have?</title>
+
+<para>
+You can use the 'testprns' program to check to see if the printer
+name you are using is recognized by Samba.  For example,  you can
+use:
+</para>
+
+<para><programlisting>
+    testprns printer /etc/printcap
+</programlisting></para>
+
+<para>
+Samba can get its printcap information from a file or from a program.
+You can try the following to see the format of the extracted
+information:
+</para>
+
+<para><programlisting>
+    testprns -a printer /etc/printcap
+
+    testprns -a printer '|/bin/cat printcap'
+</programlisting></para>
+
+</sect2>
+
+<sect2>
+<title>Setting up printcap and print servers</title>
+
+<para>
+You may need to set up some printcaps for your Samba system to use.
+It is strongly recommended that you use the facilities provided by
+the print spooler to set up queues and printcap information.
+</para>
+
+<para>
+Samba requires either a printcap or program to deliver printcap
+information.  This printcap information has the format:
+</para>
+
+<para><programlisting>
+  name|alias1|alias2...:option=value:...
+</programlisting></para>
+
+<para>
+For almost all printing systems, the printer 'name' must be composed
+only of alphanumeric or underscore '_' characters.  Some systems also
+allow hyphens ('-') as well.  An alias is an alternative name for the
+printer,  and an alias with a space in it is used as a 'comment'
+about the printer.  The printcap format optionally uses a \ at the end of lines
+to extend the printcap to multiple lines.
+</para>
+
+<para>
+Here are some examples of printcap files:
+</para>
+
+<para>
+<orderedlist>
+<listitem><para>
+pr              just printer name
+</para></listitem>
+<listitem><para>
+pr|alias        printer name and alias
+</para></listitem>
+<listitem><para>
+pr|My Printer   printer name, alias used as comment
+</para></listitem>
+<listitem><para>
+pr:sh:\        Same as pr:sh:cm= testing
+  :cm= \ 
+  testing
+</para></listitem>
+<listitem><para>
+pr:sh           Same as pr:sh:cm= testing
+  :cm= testing
+</para></listitem>
+</orderedlist>
+</para>
+
+<para>
+Samba reads the printcap information when first started.  If you make
+changes in the printcap information, then you must do the following:
+</para>
+
+<orderedlist>
+
+<listitem><para>
+make sure that the print spooler is aware of these changes.
+The LPRng system uses the 'lpc reread' command to do this.
+</para></listitem>
+
+<listitem><para>
+make sure that the spool queues, etc., exist and have the
+correct permissions.  The LPRng system uses the 'checkpc -f'
+command to do this.
+</para></listitem>
+
+<listitem><para>
+You now should send a SIGHUP signal to the smbd server to have
+it reread the printcap information.
+</para></listitem>
+</orderedlist>
+
+</sect2>
+
+<sect2>
+<title>Job sent, no output</title>
+
+<para>
+This is the most frustrating part of printing.  You may have sent the
+job,  verified that the job was forwarded,  set up a wrapper around
+the command to send the file,  but there was no output from the printer.
+</para>
+
+<para>
+First,  check to make sure that the job REALLY is getting to the
+right print queue.  If you are using a BSD or LPRng print spooler,
+you can temporarily stop the printing of jobs.  Jobs can still be
+submitted, but they will not be printed.  Use:
+</para>
+
+<para><programlisting>
+  lpc -Pprinter stop
+</programlisting></para>
+
+<para>
+Now submit a print job and then use 'lpq -Pprinter' to see if the
+job is in the print queue.  If it is not in the print queue then
+you will have to find out why it is not being accepted for printing.
+</para>
+
+<para>
+Next, you may want to check to see what the format of the job really
+was.  With the assistance of the system administrator you can view
+the submitted jobs files.  You may be surprised to find that these
+are not in what you would expect to call a printable format.
+You can use the UNIX 'file' utitily to determine what the job
+format actually is:
+</para>
+
+<para><programlisting>
+    cd /var/spool/lpd/printer   # spool directory of print jobs
+    ls                          # find job files
+    file dfA001myhost
+</programlisting></para>
+
+<para>
+You should make sure that your printer supports this format OR that
+your system administrator has installed a 'print filter' that will
+convert the file to a format appropriate for your printer.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Job sent, strange output</title>
+
+<para>
+Once you have the job printing, you can then start worrying about
+making it print nicely.
+</para>
+
+<para>
+The most common problem is extra pages of output: banner pages
+OR blank pages at the end.
+</para>
+
+<para>
+If you are getting banner pages,  check and make sure that the
+printcap option or printer option is configured for no banners.
+If you have a printcap,  this is the :sh (suppress header or banner
+page) option.  You should have the following in your printer.
+</para>
+
+<para><programlisting>
+   printer: ... :sh
+</programlisting></para>
+
+<para>
+If you have this option and are still getting banner pages,  there
+is a strong chance that your printer is generating them for you
+automatically.  You should make sure that banner printing is disabled
+for the printer.  This usually requires using the printer setup software
+or procedures supplied by the printer manufacturer.
+</para>
+
+<para>
+If you get an extra page of output,  this could be due to problems
+with your job format,  or if you are generating PostScript jobs,
+incorrect setting on your printer driver on the MicroSoft client.
+For example, under Win95 there is a option:
+</para>
+
+<para><programlisting>
+  Printers|Printer Name|(Right Click)Properties|Postscript|Advanced|
+</programlisting></para>
+
+<para>
+that allows you to choose if a Ctrl-D is appended to all jobs.
+This is a very bad thing to do, as most spooling systems will
+automatically add a ^D to the end of the job if it is detected as
+PostScript.  The multiple ^D may cause an additional page of output.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Raw PostScript printed</title>
+
+<para>
+This is a problem that is usually caused by either the print spooling
+system putting information at the start of the print job that makes
+the printer think the job is a text file, or your printer simply
+does not support PostScript.  You may need to enable 'Automatic
+Format Detection' on your printer.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Advanced Printing</title>
+
+<para>
+Note that you can do some pretty magic things by using your
+imagination with the "print command" option and some shell scripts.
+Doing print accounting is easy by passing the %U option to a print
+command shell script. You could even make the print command detect
+the type of output and its size and send it to an appropriate
+printer.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Real debugging</title>
+
+<para>
+If the above debug tips don't help, then maybe you need to bring in
+the bug guns, system tracing. See Tracing.txt in this directory.
+</para>
+</sect2>
+</sect1>
+
+</chapter>