summaryrefslogtreecommitdiff
path: root/docs/docbook/projdoc/printer_driver2.xml
diff options
context:
space:
mode:
Diffstat (limited to 'docs/docbook/projdoc/printer_driver2.xml')
-rw-r--r--docs/docbook/projdoc/printer_driver2.xml1038
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>