summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/docbook/projdoc/printer_driver2.xml3989
1 files changed, 3247 insertions, 742 deletions
diff --git a/docs/docbook/projdoc/printer_driver2.xml b/docs/docbook/projdoc/printer_driver2.xml
index b081053a12..c7188d783a 100644
--- a/docs/docbook/projdoc/printer_driver2.xml
+++ b/docs/docbook/projdoc/printer_driver2.xml
@@ -1,1018 +1,3523 @@
<chapter id="printing">
<chapterinfo>
- &author.jerry;
<author>
- <firstname>Patrick</firstname><surname>Powell</surname>
+ <firstname>Kurt</firstname><surname>Pfeifle</surname>
<affiliation>
- <address><email>papowell@lprng.org</email></address>
+ <orgname> Danka Deutschland GmbH </orgname>
+ <address><email>kpfeifle@danka.de</email></address>
</affiliation>
</author>
- <pubdate> 3 May 2001 </pubdate>
+ <pubdate> (23 May 2003) </pubdate>
</chapterinfo>
-<title>Printing Support</title>
+<title>Classical Printing Support in Samba 3.0</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>
+<sect2>
-<para>The additional functionality provided by the new
-SPOOLSS support includes:</para>
-
+<title>Features and Benefits</title>
+
+<para>
+Printing is often a mission-critical service for the users. Samba can
+provide this service reliably and seamlessly for a client network
+consisting of Windows workstations.
+</para>
+
+<para>
+A Samba-3.0 print service may be run on a Standalone or a Domain
+member server, side by side with file serving functions, or on a
+dedicated print server. It can be made as tight or as loosely secured
+as needs dictate. Configurations may be simple or complex. Available
+authentication schemes are essentially the same as described for file
+services in previous chapters. Overall, Samba's printing support is
+now able to replace an NT or Windows 2000 print server full-square,
+with additional benefits in many cases. Clients may download and
+install drivers and printers through their familiar "Point'n'Print"
+mechanism. Printer installations executed by "Logon Scripts" are no
+problem. Administrators can upload and manage drivers to be used by
+clients through the familiar "Add Printer Wizard". As an additional
+benefit, driver and printer management may be run from the commandline
+or through scripts, making it more efficient in case of large numbers
+of printers. If a central accounting of print jobs (tracking every
+single page and supplying the raw data for all sorts of statistical
+reports) is required, this is best supported by CUPS as the print
+subsystem underneath the Samba hood.
+</para>
+
+<para>
+This chapter deals with the foundations of Samba printing, as they
+implemented by the more traditional UNIX (BSD- and System V-style)
+printing systems. Many things apply to CUPS, the newer Common UNIX
+Printing System, too; so if you use CUPS, you might be tempted to jump
+to the next chapter -- but you will certainly miss a few things if you
+do so. Better read this chapter too.
+</para>
+
+<note>
+<para>
+Most of the given examples have been verified on Windows XP
+Professional clients. Where this document describes the responses to
+commands given, bear in mind that Windows 2000 clients are very
+similar, but may differ in details. Windows NT is somewhat different
+again.
+</para>
+</note>
+
+</sect2>
+
+</sect1>
+
+<sect1>
+<title>Technical Introduction</title>
+
+<para>
+Samba's printing support always relies on the installed print
+subsystem of the Unix OS it runs on. Samba is a "middleman". It takes
+printfiles from Windows (or other SMB) clients and passes them to the
+real printing system for further processing. Therefore it needs to
+"talk" to two sides: to the Windows print clients and to the Unix
+printing system. Hence we must differentiate between the various
+client OS types each of which behave differently, as well as the
+various UNIX print subsystems, which themselves have different
+features and are accessed differently. This part of the Samba HOWTO
+Collection deals with the "traditional" way of Unix printing first;
+the next chapter covers in great detail the more modern
+<emphasis>Common UNIX Printing System</emphasis>
+(CUPS).
+
+<important><para>CUPS users, be warned: don't just jump on to the next
+chapter. You might miss important information contained only
+here!</para></important>
+</para>
+
+<sect2>
+<title>What happens if you send a Job from a Client</title>
+
+<para>
+To successfully print a job from a Windows client via a Samba
+print server to a UNIX printer, there are 6 (potentially 7)
+stages:
+</para>
+
+<orderedlist>
+<listitem><para>Windows opens a connection to the printershare</para></listitem>
+
+<listitem><para>Samba must authenticate the user</para></listitem>
+
+<listitem><para>Windows sends a copy of the printfile over the network
+into Samba's spooling area</para></listitem>
+
+<listitem><para>Windows closes the connection again</para></listitem>
+
+<listitem><para>Samba invokes the print command to hand the file over
+to the UNIX print subsystem's spooling area</para></listitem>
+
+<listitem><para>The Unix print subsystem processes the print
+job</para></listitem>
+
+<listitem><para>The printfile may need to be explicitely deleted
+from the Samba spooling area.</para></listitem>
+
+</orderedlist>
+</sect2>
+
+<sect2>
+<title>Printing Related Configuration Parameters</title>
+
+<para>
+There are a number of configuration parameters in
+<filename>smb.conf</filename> controlling Samba's printing
+behaviour. Please also refer to the man page for smb.conf to
+acquire an overview about these. As with other parameters, there are
+Global Level (tagged with a "<emphasis>G</emphasis>" in the listings) and
+Service Level ("<emphasis>S</emphasis>") parameters.
+</para>
+
+<variablelist>
+<varlistentry><term>Service Level Parameters</term>
+<listitem><para>These <emphasis>may</emphasis> go into the
+<parameter>[global]</parameter> section of
+<filename>smb.conf</filename>. In this case they define the default
+behaviour of all individual or service level shares (provided those
+don't have a different setting defined for the same parameter, thus
+overriding the global default).</para></listitem>
+</varlistentry>
+
+<varlistentry><term>Global Parameters</term>
+<listitem><para>These <emphasis>may not</emphasis> go into individual
+shares. If they go in by error, the "testparm" utility can discover
+this (if you run it) and tell you so.</para></listitem>
+</varlistentry>
+</variablelist>
+</sect2>
+
+<sect2>
+<title>Parameters Recommended for Use</title>
+
+<para>The following <filename>smb.conf</filename> parameters directly
+related to printing are used in Samba 3.0. See also the
+<filename>smb.conf</filename> man page for detailed explanations:
+</para>
+
+<formalpara>
+<title>LIST OF PRINTING RELATED PARAMETERS IN SAMBA-3.0</title>
+<para>
+<itemizedlist><title>Global level parameters:</title>
+<listitem><para><parameter>addprinter command (G)</parameter></para></listitem>
+<listitem><para><parameter>deleteprinter command (G)</parameter></para></listitem>
+<listitem><para><parameter>disable spoolss (G)</parameter></para></listitem>
+<listitem><para><parameter>enumports command (G)</parameter></para></listitem>
+<listitem><para><parameter>load printers (G)</parameter></para></listitem>
+<listitem><para><parameter>lpq cache time (G)</parameter></para></listitem>
+<listitem><para><parameter>os2 driver map (G)</parameter></para></listitem>
+<listitem><para><parameter>printcap name (G), printcap (G)</parameter></para></listitem>
+<listitem><para><parameter>show add printer wizard (G)</parameter></para></listitem>
+<listitem><para><parameter>total print jobs (G)</parameter></para></listitem>
+<listitem><para><parameter>use client driver (G)</parameter></para></listitem>
+</itemizedlist>
+
+<itemizedlist><title>Service level parameters:</title>
+<listitem><para><parameter>hosts allow (S)</parameter></para></listitem>
+<listitem><para><parameter>hosts deny (S)</parameter></para></listitem>
+<listitem><para><parameter>lppause command (S)</parameter></para></listitem>
+<listitem><para><parameter>lpq command (S)</parameter></para></listitem>
+<listitem><para><parameter>lpresume command (S)</parameter></para></listitem>
+<listitem><para><parameter>lprm command (S)</parameter></para></listitem>
+<listitem><para><parameter>max print jobs (S)</parameter></para></listitem>
+<listitem><para><parameter>min print space (S)</parameter></para></listitem>
+<listitem><para><parameter>print command (S)</parameter></para></listitem>
+<listitem><para><parameter>printable (S), print ok (S)</parameter></para></listitem>
+<listitem><para><parameter>printer name (S), printer (S)</parameter></para></listitem>
+<listitem><para><parameter>printer admin (S)</parameter></para></listitem>
+<listitem><para><parameter>printing = [cups|bsd|lprng...] (S)</parameter></para></listitem>
+<listitem><para><parameter>queuepause command (S)</parameter></para></listitem>
+<listitem><para><parameter>queueresume command (S)</parameter></para></listitem>
+<listitem><para><parameter>total print jobs (S)</parameter></para></listitem>
+</itemizedlist>
+</para>
+</formalpara>
+
+<para>
+Samba's printing support implements the Microsoft Remote Procedure
+Calls (MS-RPC) methods for printing. These are used by Windows NT (and
+later) print servers. The old "LanMan" protocol is still supported as
+a fallback resort, and for older clients to use. More details will
+follow further beneath.
+</para>
+</sect2>
+
+<sect2>
+<title>Parameters for Backwards Compatibility</title>
+
+<para>
+Two new parameters that were added in Samba 2.2.2, are still present
+in Samba-3.0. Both of these options are described in the
+<filename>smb.conf</filename>(5) man page and are disabled by
+default. <emphasis>Use them with caution!</emphasis>
+</para>
+
+<variablelist>
+<varlistentry><term><parameter>disable spoolss(G)</parameter></term>
+<listitem><para> This is
+provided for better support of Samba 2.0.x backwards capability. It
+will disable Samba's support for MS-RPC printing and yield identical
+printing behaviour to Samba 2.0.x.</para></listitem>
+</varlistentry>
+
+<varlistentry><term><parameter>use client driver (G)</parameter></term>
+<listitem><para> was provided
+for using local printer drivers on Windows NT/2000 clients. It does
+not apply to Windows 95/98/ME clients.</para></listitem>
+</varlistentry>
+</variablelist>
+
+<formalpara>
+<title>PARAMETERS "FOR BACKWARD COMPATIBILITY ONLY", USE WITH CAUTION</title>
+
+<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>
+<listitem><para><parameter>disable spoolss (G)</parameter></para></listitem>
+
+<listitem><para><parameter>use client driver (S)</parameter></para></listitem>
</itemizedlist>
+</para>
+</formalpara>
+
+</sect2>
+
+<sect2>
+<title>Parameters no longer in Use</title>
<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.
+Samba users upgrading from 2.2.x to 3.0 need to be aware that some
+previously available settings are no longer supported (as was
+announced some time ago). Here is a list of them:
</para>
+<formalpara>
+<title>"OLD" PARAMETERS, REMOVED IN SAMBA-3.0</title>
+
<para>
-The following MS KB article, may be of some help if you are dealing with
-Windows 2000 clients:
-<ulink url="http://support.microsoft.com/support/kb/articles/Q189/1/05.ASP">How to Add Printers with No User Interaction in Windows 2000</ulink>
+The following <filename>smb.conf</filename> parameters have been
+deprecated already in Samba 2.2 and are now completely removed from
+Samba 3.0. You cannot use them in new 3.0 installations:
+
+<itemizedlist>
+<listitem><para><parameter>printer driver file (G)</parameter></para></listitem>
+<listitem><para><parameter>total print jobs (G)</parameter></para></listitem>
+<listitem><para><parameter>postscript (S)</parameter></para></listitem>
+<listitem><para><parameter>printer driver (S)</parameter></para></listitem>
+<listitem><para><parameter>printer driver location (S)</parameter></para></listitem>
+</itemizedlist>
</para>
-</sect1>
+</formalpara>
+</sect2>
+</sect1>
<sect1>
-<title>Configuration</title>
+<title>A simple Configuration to Print with Samba 3.0</title>
-<warning>
-<title>[print$] vs. [printer$]</title>
+<para>
+Here is a very simple example configuration for print related settings
+in the <filename>smb.conf</filename> file. If you compare it with your
+own system's <filename>smb.conf</filename>, you probably find some
+additional parameters included there (as pre-configured by your OS
+vendor). Further below is a discussion and explanation of the
+parameters. Note, that this example doesn't use many parameters.
+However, in many environments these are enough to provide a valid
+<filename>smb.conf</filename> which enables all clients to print.
+</para>
+
+<para><programlisting>
+ [global]
+ printing = bsd
+ load printers = yes
+
+ [printers]
+ path = /var/spool/samba
+ printable = yes
+ public = yes
+ writable = no
+</programlisting></para>
<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.
+This is only an example configuration. Many settings, if not
+explicitly set to a specific value, are used and set by Samba
+implicitly to its own default, because these have been compiled in.
+To see all settings, let root use the <command>testparm</command>
+utility. <command>testparm</command> also gives warnings if you have
+mis-configured certain things. Its complete output is easily 340 lines
+and more. You may want to pipe it through a pager program.
</para>
-
+
+<para>
+The syntax for the configuration file is easy to grasp. You should
+know that <filename>smb.conf</filename> is not very picky about its
+syntax. It has been explained elsewhere in this document. A short
+reminder: It even tolerates some spelling errors (like "browsable"
+instead of "browseable"). Most spelling is case-insensitive. Also, you
+can use "Yes|No" or "True|False" for boolean settings. Lists of names
+may be separated by commas, spaces or tabs.
+</para>
+
+<sect2>
+<title>Verification of "Settings in Use" with <command>testparm</command></title>
+
<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.
+To see all (or at least most) printing related settings in Samba,
+including the implicitly used ones, try the command outlined below
+(hit "ENTER" twice!). It greps for all occurrences of "lp", "print",
+"spool", "driver", "ports" and "[" in testparm's output and gives you
+a nice overview about the running smbd's print configuration. (Note
+that this command does not show individually created printer shares,
+or the spooling paths in each case). Here is the output of my Samba
+setup, with exactly the same settings in <filename>smb.conf</filename>
+as shown above:
</para>
-</warning>
+<para><programlisting>
+
+ transmeta: # testparm -v | egrep "(lp|print|spool|driver|ports|\[)"
+
+ Load smb config files from /etc/samba/smb.conf.simpleprinting
+ Processing section "[homes]"
+ Processing section "[printers]"
+ [global]
+ smb ports = 445 139
+ lpq cache time = 10
+ total print jobs = 0
+ load printers = Yes
+ printcap name = /etc/printcap
+ disable spoolss = No
+ enumports command =
+ addprinter command =
+ deleteprinter command =
+ show add printer wizard = Yes
+ os2 driver map =
+ printer admin =
+ min print space = 0
+ max print jobs = 1000
+ printable = No
+ printing = bsd
+ print command = lpr -r -P'%p' %s
+ lpq command = lpq -P'%p'
+ lprm command = lprm -P'%p' %j
+ lppause command =
+ lpresume command =
+ printer name =
+ use client driver = No
+
+ [homes]
+
+ [printers]
+ path = /var/spool/samba
+ printable = Yes
+
+</programlisting></para>
+
+<para>
+You can easily verify which settings were implicitly added by Samba's
+default behaviour. <emphasis>Don't forget about this point: it may
+be important in your future dealings with Samba.</emphasis>
+</para>
+
+<note><para> testparm in Samba-3.0 behaves differently from 2.2.x: used
+without the "-v" switch it only shows you the settings actually
+written into <filename>smb.conf</filename>! To see the complete
+configuration used, add the "-v" parameter to testparm.</para></note>
+
+</sect2>
+
<sect2>
-<title>Creating [print$]</title>
+<title>A little Experiment to warn you</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).
+Should you need to troubleshoot at any stage, please always come back
+to this point first and verify if "testparm" shows the parameters you
+expect! To give you an example from personal experience as a warning,
+try to just "comment out" the <parameter>load printers</parameter>"
+parameter. If your 2.2.x system behaves like mine, you'll see this:
</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>
+
+ kde-bitshop:/etc/samba # grep "load printers" smb.conf
+ # load printers = Yes
+ # This setting is commented ooouuuuut!!
+
+ kde-bitshop:/etc/samba # testparm -v smb.conf | egrep "(load printers)"
+ load printers = Yes
+
+</programlisting></para>
+
+<para>
+Despite my imagination that the commenting out of this setting should
+prevent Samba from publishing my printers, it still did! Oh Boy -- it
+cost me quite some time to find out the reason. But I am not fooled
+any more... at least not by this ;-)
+</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
+ kde-bitshop:/etc/samba # grep -A1 "load printers" smb.conf
+ load printers = No
+ # This setting is what I mean!!
+ # load printers = Yes
+ # This setting is commented ooouuuuut!!
+
+ kde-bitshop:/etc/samba # testparm -v smb.conf.simpleprinting | egrep "(load printers)"
+ load printers = No
+
</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"><parameter>guest
-ok = yes</parameter></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"><parameter>map to guest = Bad User
-</parameter></ulink> in the <parameter>[global]</parameter> section as well. Make sure
-you understand what this parameter does before using it
-though. --jerry
+
+<para>
+Only when setting the parameter explicitly to
+"<parameter>load printers = No</parameter>"
+would Samba recognize my intentions. So my strong advice is:
</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>
-
+<itemizedlist>
+<listitem><para>Never rely on "commented out" parameters!</para></listitem>
+
+<listitem><para>Always set it up explicitly as you intend it to
+behave.</para></listitem>
+
+<listitem><para>Use <command>testparm</command> to uncover hidden
+settings which might not reflect your intentions.</para></listitem>
+
+</itemizedlist>
+
<para>
-In order to currently add a new driver to you Samba host,
-one of two conditions must hold true:
+You can have a working Samba print configuration with this
+minimal <filename>smb.conf</filename>:
</para>
-
+
+<para><programlisting>
+
+ kde-bitshop:/etc/samba # cat /etc/samba/smb.conf-minimal
+ [printers]
+
+</programlisting></para>
+
+<para>
+This example should show you that you can use testparm to test any
+filename for fitness as a Samba configuration. Actually, we want to
+encourage you <emphasis>not</emphasis> to change your
+<filename>smb.conf</filename> on a working system (unless you know
+exactly what you are doing)! Don't rely on an assumption that changes
+will only take effect after you re-start smbd! This is not the
+case. Samba re-reads its <filename>smb.conf</filename> every 60
+seconds and on each new client connection. You might have to face
+changes for your production clients that you didn't intend to apply at
+this time! You will now note a few more interesting things. Let's now
+ask <command>testparm</command> what the Samba print configuration
+would be, if you used this minimalistic file as your real
+<filename>smb.conf</filename>:
+</para>
+
+<para><programlisting>
+
+ kde-bitshop:~ # testparm -v /etc/samba/smb.conf-minimal | egrep "(print|lpq|spool|driver|ports|[)"
+ Processing section "[printers]"
+ WARNING: [printers] service MUST be printable!
+ No path in service printers - using /tmp
+
+ lpq cache time = 10
+ total print jobs = 0
+ load printers = Yes
+ printcap name = /etc/printcap
+ disable spoolss = No
+ enumports command =
+ addprinter command =
+ deleteprinter command =
+ show add printer wizard = Yes
+ os2 driver map =
+ printer admin =
+ min print space = 0
+ max print jobs = 1000
+ printable = No
+ printing = bsd
+ print command = lpr -r -P%p %s
+ lpq command = lpq -P%p
+ printer name =
+ use client driver = No
+ [printers]
+ printable = Yes
+
+</programlisting></para>
+
+<para>
+testparm issued 2 warnings:
+</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>
+<listitem><para>because we didn't specify the
+<parameter>[printers]</parameter> section as printable,
+and</para></listitem>
+
+<listitem><para>because we didn't tell it which spool directory to
+use.</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.
+However, this was not fatal, and Samba-3.0 will default to values that
+will work here. But, please!, don't rely on this and don't use this
+example! This was only meant to make you careful to design and specify
+your setup to be what you really want it to be. The outcome on your
+system may vary for some parameters, since you may have a Samba built
+with a different compile-time configuration.
+<emphasis>Warning:</emphasis> don't put a comment sign <emphasis>at
+the end</emphasis> of a valid <filename>smb.conf</filename> line. It
+will cause the parameter to be ignored (just as if you had put the
+comment sign at the front). At first I regarded this as a bug in my
+Samba version(s). But the man page states: <quote>Internal whitespace
+in a parameter value is retained verbatim.</quote> This means that a
+line consisting of, for example,
</para>
-</warning>
+<para><programlisting>
+printing =lprng #This defines LPRng as the printing system"
+</programlisting></para>
<para>
-Once you have created the required <parameter>[print$]</parameter> 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 <guilabel>Network Neighbourhood</guilabel> or
-<guilabel>My Network Places</guilabel> and browse for the Samba host. Once you have located
-the server, navigate to the <guilabel>Printers...</guilabel> folder.
-You should see an initial listing of printers
-that matches the printer shares defined on your Samba host.
+will regard the whole of the string after the "="
+sign as the value you want to define. And this is an invalid value
+that will be ignored, and a default value used instead.]
</para>
</sect2>
+</sect1>
+
+<sect1>
+<title>Extended Sample Configuration to Print with Samba 3.0</title>
+
+<para>
+Here we show a more verbose example configuration for print related
+settings in an <filename>smb.conf</filename>. Below is a discussion
+and explanation of the various parameters. We chose to use BSD-style
+printing here, because we guess it is still the most commonly used
+system on legacy Linux installations (new installs now predominantly
+have CUPS, which is discussed entirely in the next chapter of this
+document). Note, that this example explicitly names many parameters
+which don't need to be stated because they are set by default. You
+might be able to do with a leaner <filename>smb.conf</filename>.</para>
+
+<tip><para>
+if you read access it with the Samba Web Administration Tool (SWAT),
+and then write it to disk again, it will be optimized in a way such
+that it doesn't contain any superfluous parameters and comments. SWAT
+organizes the file for best performance. Remember that each smbd
+re-reads the Samba configuration once a minute, and that each
+connection spawns an smbd process of its own, so it is not a bad idea
+to optimize the <filename>smb.conf</filename> in environments with
+hundreds or thousands of clients.</para></tip>
+
+<para><programlisting>
+ [global]
+ printing = bsd
+ load printers = yes
+ show add printer wizard = yes
+ printcap name = /etc/printcap
+ printer admin = @ntadmin, root
+ total print jobs = 100
+ lpq cache time = 20
+ use client driver = no
+
+ [printers]
+ comment = All Printers
+ printable = yes
+ path = /var/spool/samba
+ browseable = no
+ guest ok = yes
+ public = yes
+ read only = yes
+ writable = no
+
+ [my_printer_name]
+ comment = Printer with Restricted Access
+ path = /var/spool/samba_my_printer
+ printer admin = kurt
+ browseable = yes
+ printable = yes
+ writeable = no
+ hosts allow = 0.0.0.0
+ hosts deny = turbo_xp, 10.160.50.23, 10.160.51.60
+ guest ok = no
+</programlisting></para>
+
+<para>
+This <emphasis>also</emphasis> is only an example configuration. You
+may not find all the settings in your own
+<filename>smb.conf</filename> (as pre-configured by your OS
+vendor). Many configuration parameters, if not explicitly set to a
+specific value, are used and set by Samba implicitly to its own
+default, because these have been compiled in. To see all settings, let
+root use the <command>testparm</command>
+utility. <command>testparm</command> also gives warnings if you have
+mis-configured certain things..
+</para>
+</sect1>
+
+<sect1>
+<title>Detailed Explanation of the Example's Settings</title>
+
+<para>
+Following is a discussion of the settings from above shown example.
+</para>
<sect2>
-<title>Setting Drivers for Existing Printers</title>
+<title>The <parameter>[global]</parameter> Section</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>
+The <parameter>[global]</parameter> section is one of 4 special
+sections (along with [<parameter>[homes]</parameter>,
+<parameter>[printers]</parameter> and
+<parameter>[print$]</parameter>...) It contains all parameters which
+apply to the server as a whole. It is the place for parameters which
+have only a "global" meaning (G). It may also contain service level
+parameters (S) which then define default settings for all other
+sections and shares. This way you can simplify the configuration and
+avoid setting the same value repeatedly. (Within each individual
+section or share you may however override these globally set "share
+level" settings and specify other values).
+</para>
+
+<variablelist>
+<varlistentry><term><parameter>printing = bsd</parameter></term>
+<listitem><para> this causes Samba to use default print commands
+applicable for the BSD (a.k.a. RFC 1179 style or LPR/LPD) printing
+system. In general, the "printing" parameter informs Samba about the
+print subsystem it should expect. Samba supports CUPS, LPD, LPRNG,
+SYSV, HPUX, AIX, QNX and PLP. Each of these systems defaults to a
+different "print command" (and other queue control
+commands). <emphasis>Caution:</emphasis> The "printing" parameter is
+normally a service level parameter. Since it is included here in the
+<parameter>[global]</parameter> section, it will take effect for all
+printer shares that are not defined differently. Samba-3.0 no longer
+supports the SOFTQ printing system.</para></listitem></varlistentry>
+
+<varlistentry><term><parameter>load printers = yes</parameter></term>
+<listitem><para> this tells Samba to create automatically all
+available printer shares. "Available" printer shares are discovered by
+scanning the printcap file. All created printer shares are also loaded
+for browsing. If you use this parameter, you do not need to specify
+separate shares for each printer. Each automatically created printer
+share will clone the configuration options found in the
+<parameter>[printers]</parameter> section. (A <parameter>load printers
+= no</parameter> setting will allow you to specify each UNIX printer
+you want to share separately, leaving out some you don't want to be
+publicly visible and available). </para></listitem></varlistentry>
+
+<varlistentry><term><parameter>show add printer wizard =
+yes</parameter></term> <listitem><para> this setting is normally
+enabled by default (even if the parameter is not written into the
+<filename>smb.conf</filename>). It makes the "Add Printer Wizard" icon
+show up in the "Printers" folder of the Samba host's share listing (as
+shown in "Network Neighbourhood" or by the "net view" command). To
+disable it, you need to explicitly set it to "no" (commenting it out
+will not suffice!). The Add Printer Wizard lets you upload printer
+drivers to the <parameter>[print$]</parameter> share and associate it
+with a printer (if the respective queue exists there before the
+action), or exchange a printer's driver against any other previously
+uploaded driver. </para></listitem></varlistentry>
+
+<varlistentry><term><parameter>total print jobs = 100</parameter></term>
+<listitem><para> this setting sets the upper limit to 100 print jobs
+being active on the Samba server at any one time. Should a client
+submit a job which exceeds this number, a <quote>no more space
+available on server</quote> type of error message will be returned by
+Samba to the client. A setting of "0" (the default) means there is
+<emphasis>no</emphasis> limit at all!
+</para></listitem></varlistentry>
+
+<varlistentry><term><parameter>printcap name = /etc/printcap</parameter></term>
+
+<listitem><para> this tells Samba where to look for a list of
+available printer names. (If you use CUPS, make sure that a printcap
+file is written: this is controlled by the "Printcap" directive of
+<filename>cupsd.conf</filename>).
+</para></listitem></varlistentry>
+
+<varlistentry><term><parameter>printer admin = @ntadmin</parameter></term>
+<listitem><para> members of the ntadmin group should be able to add
+drivers and set printer properties ("ntadmin" is only an example name,
+it needs to be a valid UNIX group name); root is implicitly always a
+'printer admin'. The "@" sign precedes group names in
+<filename>smb.conf</filename>. A printer admin can do anything to
+printers via the remote administration interfaces offered by MS-RPC
+(see below). Note that the <parameter>printer admin</parameter>
+parameter is normally a share level parameter, so you may associate
+different groups to different printer shares in larger installations,
+if you use the <parameter>printer admin</parameter> parameter on the
+share levels).
+</para></listitem></varlistentry>
+
+<varlistentry><term><parameter>lpq cache time = 20</parameter></term>
+<listitem><para> this controls the cache time for the results of the
+lpq command. It prevents the lpq command being called too often and
+reduces load on a heavily used print server.
+</para></listitem></varlistentry>
+
+<varlistentry><term><parameter>use client driver = no</parameter></term>
+<listitem><para> if set to "yes", this setting only takes effect for
+Win NT/2k/XP clients (and not for Win 95/98/ME). Its default value is
+"No" (or "False"). It must <emphasis>not</emphasis> be enabled on
+print shares (with a "yes" or "true" setting) which have valid drivers
+installed on the Samba server! For more detailed explanations see the
+man page of <filename>smb.conf</filename>.
+</para></listitem></varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2>
+<title>The <parameter>[printers]</parameter> Section</title>
<para>
-<errorname>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?</errorname>
+This is the second special section. If a section with this name
+appears in the <filename>smb.conf</filename>, users are able to
+connect to any printer specified in the Samba host's printcap file,
+because Samba on startup then creates a printer share for every
+printername it finds in the printcap file. You could regard this
+section as a general convenience shortcut to share all printers with
+minimal configuration. It is also a container for settings which
+should apply as default to all printers. (For more details see the
+<filename>smb.conf</filename> man page.) Settings inside this
+container must be share level parameters (S).
+</para>
+
+<variablelist>
+<varlistentry><term><parameter>comment = All printers</parameter></term>
+<listitem><para> the <parameter>comment</parameter> is shown next to
+the share if a client queries the server, either via "Network
+Neighbourhood" or with the <command>net view</command> command to list
+available shares.
+</para></listitem></varlistentry>
+
+<varlistentry><term><parameter>printable = yes</parameter></term>
+<listitem><para> please note well, that the
+<parameter>[printers]</parameter> service <emphasis>must</emphasis> be
+declared as printable. If you specify otherwise, smbd will refuse to
+load <filename>smb.conf</filename> at startup. This parameter allows
+connected clients to open, write to and submit spool files into the
+directory specified with the <parameter>path</parameter> parameter for
+this service. It is used by Samba to differentiate printer shares from
+file shares. </para></listitem></varlistentry>
+
+<varlistentry><term><parameter>path = /var/spool/samba</parameter></term>
+<listitem><para>this must point to a directory used by Samba to spool
+incoming print files. <emphasis>It must not be the same as the spool
+directory specified in the configuration of your UNIX print
+subsystem!</emphasis> The path would typically point to a directory
+which is world writeable, with the "sticky" bit set to it.
+</para></listitem></varlistentry>
+
+<varlistentry><term><parameter>browseable = no</parameter></term>
+<listitem><para> this is always set to "no" if <parameter>printable =
+yes</parameter>. It makes the [printer] share itself invisible in the
+list of available shares in a <command>net view</command> command or
+in the Explorer browse list. (Note that you will of course see the
+individual printers).
+</para></listitem></varlistentry>
+
+<varlistentry><term><parameter>guest ok = yes</parameter></term>
+
+<listitem><para>
+if set to "yes", then no password is required to
+connect to the printers service. Access will be granted with the
+privileges of the "guest account". On many systems the guest
+account will map to a user named "nobody". This user is in the UNIX
+passwd file with an empty password, but with no valid UNIX login.
+(Note: on some systems the guest account might not have the
+privilege to be able to print. Test this by logging in as your
+guest user using "su - guest" and run a system print command like
</para>
+<para><programlisting>
+lpr -P printername /etc/motd
+</programlisting></para>
+
+</listitem></varlistentry>
+
+<varlistentry><term><parameter>public = yes</parameter></term>
+<listitem><para> this is a synonym for <parameter>guest ok =
+yes</parameter>. Since we have <parameter>guest ok = yes</parameter>,
+it really doesn't need to be here! (This leads to the interesting
+question: <quote>What, if I by accident have to contradictory settings
+for the same share?</quote> The answer is: the last one encountered by
+Sambe wins. The "winner" is shown by testparm. Testparm doesn't
+complain about different settings of the same parameter for the same
+share! You can test this by setting up multiple lines for the "guest
+account" parameter with different usernames, and then run testparm to
+see which one is actually used by Samba.)
+</para></listitem></varlistentry>
+
+<varlistentry><term><parameter>read only = yes</parameter></term>
+<listitem><para>this normally (for other types of shares) prevents
+users creating or modifying files in the service's directory. However,
+in a "printable" service, it is <emphasis>always</emphasis> allowed to
+write to the directory (if user privileges allow the connection), but
+only via print spooling operations. "Normal" write operations are not
+allowed. </para></listitem></varlistentry>
+
+<varlistentry><term><parameter>writeable = no</parameter></term>
+<listitem><para>
+synonym for <parameter>read only = yes</parameter>
+</para></listitem></varlistentry>
+</variablelist>
+</sect2>
+
+<sect2>
+<title>Any [my_printer_name] Section</title>
+
<para>
-Click <guibutton>No</guibutton> 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
+If a section appears in the <filename>smb.conf</filename>, which is
+tagged as <parameter>printable = yes</parameter>, Samba presents it as
+a printer share to its clients. Note, that Win95/98/ME clients may
+have problems with connecting or loading printer drivers if the share
+name has more than 8 characters! Also be very careful if you give a
+printer the same name as an existing user or file share name: upon a
+client's connection request to a certain sharename, Samba always tries
+to find file shares with that name first; if it finds one, it will
+connect to this and will never ultimately connect to a printer with
+the same name!
</para>
-
-<procedure>
- <step><para>Use the <guibutton>New Driver...</guibutton> button to install
- a new printer driver, or</para></step>
-
- <step><para>Select a driver from the popup list of
- installed drivers. Initially this list will be empty.</para>
- </step>
-</procedure>
-
-<para>If you wish to install printer drivers for client
-operating systems other than "Windows NT x86", you will need
-to use the <guilabel>Sharing</guilabel> 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
-&smb.conf;.</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 least. 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>
-<screen>
-<prompt>$ </prompt><userinput>rpcclient <replaceable>pogo</replaceable> -U root%<replaceable>secret</replaceable> -c "enumdrivers"</userinput>
-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><userinput>rpcclient <replaceable>pogo</replaceable> -U root%<replaceable>secret</replaceable> -c "enumprinters"</userinput>
-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><userinput>rpcclient <replaceable>pogo</replaceable> -U root%<replaceable>secret</replaceable> -c "setdriver <replaceable>hp-print</replaceable> <replaceable>\"HP LaserJet 4000 Series PS\"</replaceable></userinput>
-Domain=[NARNIA] OS=[Unix] Server=[Samba 2.2.0-alpha3]
-Successfully set hp-print to driver HP LaserJet 4000 Series PS.
-</screen></para>
+
+<variablelist>
+<varlistentry><term><parameter>comment = Printer with Restricted Access</parameter></term>
+<listitem><para> the comment says it all.
+</para></listitem></varlistentry>
+
+<varlistentry><term><parameter>path = /var/spool/samba_my_printer</parameter></term>
+<listitem><para> here we set the spooling area for this printer to
+another directory than the default. It is not a requirement to set it
+differently, but the option is available.
+</para></listitem></varlistentry>
+
+<varlistentry><term><parameter>printer admin = kurt</parameter></term>
+<listitem><para> the printer admin definition is different for this
+explicitly defined printer share from the general
+<parameter>[printers]</parameter> share. It is not a requirement; we
+did it to show that it is possible if you want it.
+</para></listitem></varlistentry>
+
+<varlistentry><term><parameter>browseable = yes</parameter></term>
+<listitem><para> we also made this printer browseable (so that the
+clients may conveniently find it when browsing the Network
+Neighbourhood).
+</para></listitem></varlistentry>
+
+<varlistentry><term><parameter>printable = yes</parameter></term>
+<listitem><para>see explanation in last subsection.
+</para></listitem></varlistentry>
+
+<varlistentry><term><parameter>writeable = no</parameter></term>
+<listitem><para>see explanation in last subsection.
+</para></listitem></varlistentry>
+
+<varlistentry><term><parameter>hosts allow = 10.160.50.,10.160.51.</parameter></term>
+<listitem><para>here we exercise a certain degree of access control
+by using the "hosts allow" and "hosts deny" parameters. Note, that
+this is not by any means a safe bet. It is not a way to secure your
+printers. This line accepts all clients from a certain subnet in a
+first evaluation of access control
+</para></listitem></varlistentry>
+
+<varlistentry><term><parameter>hosts deny = turbo_xp,10.160.50.23,10.160.51.60
+</parameter></term>
+<listitem><para>all listed hosts are not allowed here (even if they
+belong to the "allowed subnets"). As you can see, you could name IP
+addresses as well as NetBIOS hostnames
+here.
+</para></listitem></varlistentry>
+
+<varlistentry><term><parameter>guest ok = no</parameter></term>
+<listitem><para>this printer is not open for the guest account!
+</para></listitem></varlistentry>
+
+</variablelist>
</sect2>
+<sect2>
+<title>Print Commands</title>
+<para>
+In each section defining a printer (or in the
+<parameter>[printers]</parameter> section), a <parameter>print
+command</parameter> parameter may be defined. It sets a command to
+process the files which have been placed into the Samba print spool
+directory for that printer. (That spool directory was, if you
+remember, set up with the <parameter>path</parameter>
+parameter). Typically, this command will submit the spool file to the
+Samba host's print subsystem, using the suitable system print
+command. But there is no requirement that this needs to be the
+case. For debugging purposes or some other reason you may want to do
+something completely different than "print" the file. An example is a
+command that just copies the print file to a temporary location for
+further investigation when you need to debug printing. If you craft
+your own print commands (or even develop print command shell scripts),
+make sure you pay attention to the need to remove the files from the
+Samba spool directory. Otherwise your hard disk may soon suffer from
+shortage of free space.
+</para>
+</sect2>
<sect2>
-<title>Adding New Printers via the Windows NT APW</title>
-
+<title>Default Print Commands for various Unix Print Subsystems</title>
+
+<para>
+You learned earlier on, that Samba in most cases uses its built-in
+settings for many parameters if it can not find an explicitly stated
+one in its configuration file. The same is true for the
+<parameter>print command</parameter>. The default print command varies
+depending on the <parameter>printing =...</parameter> parameter
+setting. In the commands listed below, you will notice some parameters
+of the form <emphasis>%X</emphasis> where <emphasis>X</emphasis> is
+<emphasis>p, s, J</emphasis> etc. These letters stand for
+"printername", "spoolfile" and "job ID" respectively. They are
+explained in more detail further below. Here is an overview (excluding
+the special case of CUPS, which is discussed in the next chapter):
+</para>
+
+<informaltable frame='all'>
+<tgroup cols='2' align='left' colsep='1' rowsep='1'>
+<thead>
+<row>
+<entry>If this setting is active...</entry>
+<entry>...this is used in lieu of an explicit command:</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><parameter>printing = bsd|aix|lprng|plp</parameter></entry>
+<entry>print command is <command>lpr -r -P%p %s</command></entry>
+</row>
+<row>
+<entry><parameter>printing = sysv|hpux</parameter></entry>
+<entry>print command is <command>lp -c -P%p %s; rm %s</command></entry>
+</row>
+<row>
+<entry> <parameter>printing = qnx</parameter></entry>
+<entry>print command is <command>lp -r -P%p -s %s</command></entry>
+</row>
+<row>
+<entry><parameter>printing = bsd|aix|lprng|plp</parameter></entry>
+<entry>lpq command is <command>lpq -P%p</command></entry>
+</row>
+<row>
+<entry><parameter>printing = sysv|hpux</parameter></entry>
+<entry>lpq command is <command>lpstat -o%p</command></entry>
+</row>
+<row>
+<entry><parameter>printing = qnx</parameter></entry>
+<entry>lpq command is <command>lpq -P%p</command></entry>
+</row>
+<row>
+<entry><parameter>printing = bsd|aix|lprng|plp</parameter></entry>
+<entry>lprm command is <command>lprm -P%p %j</command></entry>
+</row>
+<row>
+<entry><parameter>printing = sysv|hpux</parameter></entry>
+<entry>lprm command is <command>cancel %p-%j</command></entry>
+</row>
+<row>
+<entry><parameter>printing = qnx</parameter></entry>
+<entry>lprm command is <command>cancel %p-%j</command></entry>
+</row>
+<row>
+<entry><parameter>printing = bsd|aix|lprng|plp</parameter></entry>
+<entry>lppause command is <command>lp -i %p-%j -H hold</command></entry>
+</row>
+<row>
+<entry><parameter>printing = sysv|hpux</parameter></entry>
+<entry>lppause command (...is empty)</entry>
+</row>
+<row>
+<entry><parameter>printing = qnx</parameter></entry>
+<entry>lppause command (...is empty)</entry>
+</row>
+<row>
+<entry><parameter>printing = bsd|aix|lprng|plp</parameter></entry>
+<entry>lpresume command is <command>lp -i %p-%j -H resume</command></entry>
+</row>
+<row>
+<entry><parameter>printing = sysv|hpux</parameter></entry>
+<entry>lpresume command (...is empty)</entry>
+</row>
+<row>
+<entry><parameter>printing = qnx</parameter></entry>
+<entry>lpresume command (...is empty)</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+We excluded the special CUPS case here, because it is discussed in the
+next chapter. Just a short summary. For <parameter>printing =
+CUPS</parameter>: If SAMBA is compiled against libcups, it uses the
+CUPS API to submit jobs, etc. (It is a good idea also to set
+"<parameter>printcap = cups</parameter>" in case your
+<filename>cupsd.conf</filename> is set to write its autogenerated
+printcap file to an unusual place). Otherwise Samba maps to the System
+V printing commands with the -oraw option for printing, i.e. it uses
+<command>lp -c -d%p -oraw; rm %s</command> With <parameter>printing =
+cups</parameter> , and if SAMBA is compiled against libcups, any
+manually set print command will be ignored!
+</para>
+
+<para>
+Having listed the above mappings here, you should note that there used
+to be a <emphasis>bug</emphasis> in recent 2.2.x versions which
+prevented the mapping from taking effect. It lead to the
+"bsd|aix|lprng|plp" settings taking effect for all other systems, for
+the most important commands (the <command>print</command> command, the
+<command>lpq</command> command and the <command>lprm</command>
+command). The <command>lppause</command> command and the
+<command>lpresume</command> command remained empty. Of course, these
+commands worked on bsd|aix|lprng|plp but they didn't work on
+sysv|hpux|qnx systems. To work around this bug, you need to
+explicitly set the commands. Use <command>testparm -v</command> to
+check which command takes effect. Then check that this command is
+adequate and actually works for your installed print subsystem. It is
+always a good idea to explicitly set up your configuration files the
+way you want them to work and not rely on any built-in defaults.
+</para>
+</sect2>
+
+<sect2>
+<title>Setting up your own Print Commands</title>
+
+<para>
+After a print job has finished spooling to a service, the
+<parameter>print command</parameter> will be used by Samba via a
+<emphasis>system()</emphasis> call to process the spool file. Usually
+the command specified will submit the spool file to the host's
+printing subsystem. But there is no requirement at all that this must
+be the case. The print subsystem will probably not remove the spool
+file on its own. So whatever command you specify on your own you
+should ensure that the spool file is deleted after it has been
+processed.
+</para>
+
<para>
-By default, Samba offers all printer shares defined in &smb.conf;
-in the <filename>Printers...</filename> folder. Also existing in this folder is the Windows NT
-Add Printer Wizard icon. The <acronym>APW</acronym> will be show only if
+There is no difficulty with using your own customized print commands
+with the traditional printing systems. However, if you don't wish to
+"roll your own", you should be well informed about the default
+built-in commands that Samba uses for each printing subsystem (see the
+table above). In all the commands listed in the last paragraphs you
+see parameters of the form <emphasis>%X</emphasis> These are
+<emphasis>macros</emphasis>, or shortcuts, used as place holders for
+the names of real objects. At the time of running a command with such
+a placeholder, Samba will insert the appropriate value
+automatically. Print commands can handle all Samba macro
+substitutions. In regard to printing, the following ones do have
+special relevance:
</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>
+<listitem><para><parameter>%s, %f</parameter> - the path to the spool
+file name</para></listitem>
+
+<listitem><para><parameter>%p</parameter> - the appropriate printer
+name</para></listitem>
+
+<listitem><para><parameter>%J</parameter> - the job name as
+transmitted by the client.</para></listitem>
+
+<listitem><para><parameter>%c</parameter> - the number of printed
+pages of the spooled job (if known).</para></listitem>
+
+<listitem><para><parameter>%z</parameter> - the size of the spooled
+print job (in bytes)</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
-&smb.conf; if necessary.
+The print command MUST contain at least one occurrence of
+<parameter>%s</parameter> or <parameter>%f</parameter>. -- The
+<parameter>%p</parameter> is optional. If no printer name is supplied,
+the <parameter>%p</parameter> will be silently removed from the print
+command. In this case the job is sent to the default printer.
+</para>
+
+<para>
+If specified in the <parameter>[global]</parameter> section, the print
+command given will be used for any printable service that does not
+have its own print command specified. If there is neither a specified
+print command for a printable service nor a global print command,
+spool files will be created but not processed! And (most importantly):
+print files will not be removed, so they will start filling your Samba
+hard disk.
+</para>
+
+<para>
+Note that printing may fail on some UNIXes from the "nobody"
+account. If this happens, create an alternative guest account and
+supply it with the privilege to print. Set up this guest account in
+the <parameter>[global]</parameter> section with the <parameter>guest
+account</parameter> parameter.
+</para>
+
+<para>
+You can form quite complex print commands. You need to realize that
+print commands are just passed to a UNIX shell. The shell is able to
+expand the included environment variables as usual. (The syntax to
+include a UNIX environment variable <parameter>$variable</parameter>
+in <filename>smb.conf</filename> or in the Samba print command is
+<parameter>%$variable</parameter>.) To give you a working
+<parameter>print command</parameter> example, the following will log a
+print job to <filename>/tmp/print.log</filename>, print the file, then
+remove it. Note that ';' is the usual separator for commands in shell
+scripts:
+</para>
+
+<para><programlisting>
+<![CDATA[
+ print command = echo Printing %s >> /tmp/print.log; lpr -P %p %s; rm %s
+]]>
+</programlisting></para>
+
+<para>
+You may have to vary your own command considerably from this example
+depending on how you normally print files on your system. The default
+for the <parameter>print command</parameter> parameter varies depending on the setting of
+the <parameter>printing</parameter> parameter. Another example is:
</para>
+<para><programlisting>
+ print command = /usr/local/samba/bin/myprintscript %p %s
+</programlisting></para>
+</sect2>
+</sect1>
+
+<sect1>
+<title>Innovations in Samba Printing since 2.2</title>
+
<para>
-When using the APW from a client, if the named printer share does
-not exist, &smbd; will execute the <parameter>add printer
-command</parameter> and reparse to the &smb.conf;
-to attempt to locate the new printer share. If the share is still not defined,
-an error of <errorname>Access Denied</errorname> 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.
+Before version 2.2.0, Samba's print server support for Windows clients
+was limited to the level of <emphasis>LanMan</emphasis> printing
+calls. This is the same protocol level as Windows 9x PCs offer when
+they share printers. Beginning with the 2.2.0 release, Samba started
+to support the native Windows NT printing mechanisms. These are
+implemented via <emphasis>MS-RPC</emphasis> (RPC = <emphasis>Remote
+Procedure Calls</emphasis> ). MS-RPCs use the
+<emphasis>SPOOLSS</emphasis> named pipe for all printing.
</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.
+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 (<emphasis>Point'n'Print</emphasis>);
+</para></listitem>
+
+<listitem><para>Uploading of printer drivers via the Windows NT
+<emphasis>Add Printer Wizard</emphasis> (APW) or the
+<emphasis>Imprints</emphasis> 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 <emphasis>Access Control
+Lists</emphasis> (ACL) on printer objects;</para></listitem>
+
+<listitem><para>Improved support for printer queue manipulation
+through the use of internal databases for spooled job information
+(implemented by various <filename>*.tdb</filename>
+files).</para></listitem>
+
+</itemizedlist>
+
<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.
+One other benefit of an update is this: Samba 3.0 is able to publish
+all its printers in Active Directory (or LDAP)!
</para>
-<programlisting>
-#!/bin/sh
+<para>
+One slight difference is here: it is possible on a Windows NT print
+server to have printers listed in the Printers folder which are
+<emphasis>not</emphasis> 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>. The reason is that Windows NT/2k/XPprof
+clients do not normally need to use the standard SMB printer share;
+rather they 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 well-known <emphasis>Everyone</emphasis>
+group. (The older clients of type Win9x can only print to "shared"
+printers).
+</para>
-# 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
+<sect2>
+<title>Client Drivers on Samba Server for <emphasis>Point'n'Print</emphasis></title>
-#
-# 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"
+<para>
+There is still confusion about what all this means: <emphasis>Is it or
+is it not a requirement for printer drivers to be installed on a Samba
+host in order to support printing from Windows clients?</emphasis> The
+answer to this is: No, it is not a
+<emphasis>requirement</emphasis>. Windows NT/2000 clients can, of
+course, also run their APW to install drivers
+<emphasis>locally</emphasis> (which then connect to a Samba served
+print queue). This is the same method as used by Windows 9x
+clients. (However, a <emphasis>bug</emphasis> existed in Samba 2.2.0
+which made Windows NT/2000 clients require that the Samba server
+possess a valid driver for the printer. This was fixed in Samba
+2.2.1).
+</para>
-# 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
+<para>
+But it is a new <emphasis>option</emphasis> to install the printer
+drivers into the <parameter>[print$]</parameter> share of the Samba
+server, and a big convenience too. Then <emphasis>all</emphasis>
+clients (including 95/98/ME) get the driver installed when they first
+connect to this printer share. The <emphasis>uploading</emphasis> or
+<emphasis>depositing</emphasis> of the driver into this
+<parameter>[print$]</parameter> share, and the following binding of
+this driver to an existing Samba printer share can be achieved by
+different means:
+</para>
-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
+<itemizedlist>
+<listitem><para>running the <emphasis>APW</emphasis> on an
+NT/2k/XPprof client (this doesn't work from 95/98/ME
+clients);</para></listitem>
-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>
+<listitem><para>using the <emphasis>Imprints</emphasis>
+toolset;</para></listitem>
+<listitem><para>using the <emphasis>smbclient</emphasis> and
+<emphasis>rpcclient</emphasis> commandline tools;</para></listitem>
+
+<listitem><para>using <emphasis>cupsaddsmb</emphasis>(only works for
+the CUPS printing system, not for LPR/LPD, LPRng
+etc.).</para></listitem>
+
+</itemizedlist>
+
+<para>
+Please take additional note of the following fact: <emphasis>Samba
+does not use these uploaded drivers in any way to process spooled
+files</emphasis>. Drivers are utilized entirely by the clients, who
+download and install them via the "Point 'n'Print" mechanism supported
+by Samba. The clients use these drivers to generate print files in the
+format the printer (or the Unix print system) requires. Print files
+received by Samba are handed over to the Unix printing system, which
+is responsible for all further processing, if needed.
+</para>
</sect2>
+<sect2>
+<title>The [printer$] Section is removed from Samba 3.0</title>
+
+<formalpara><title>
+<parameter>[print$]</parameter> vs. <parameter>[printer$]</parameter>
+</title>
+
+<para>
+Versions of Samba prior to 2.2 made it possible to use a share
+named <emphasis>[printer$]</emphasis>. This name was taken from the
+same named service created by Windows 9x clients when a printer was
+shared by them. Windows 9x printer servers always have a
+<parameter>[printer$]</parameter> service which provides read-only
+access (with no password required) in order to support printer driver
+downloads. However, Samba's initial implementation allowed for a
+parameter named <parameter>printer driver location</parameter> to be
+used on a per share basis. This specified 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. These parameters,
+including the <parameter>printer driver file</parameter> parameter,
+are now removed and can not be used in installations of Samba-3.0.
+Now the share name <parameter>[print$]</parameter> is used for the
+location of downloadable printer drivers. It is taken from the
+<parameter>[print$]</parameter> service created by Windows NT PCs when
+a printer is shared by them. Windows NT print servers always have a
+<parameter>[print$]</parameter> service which provides read-write
+access (in the context of its ACLs) in order to support printer driver
+down- and uploads. Don't fear -- this does not mean Windows 9x
+clients are thrown aside now. They can use Samba's
+<parameter>[print$]</parameter> share support just fine.
+</para></formalpara>
+</sect2>
<sect2>
-<title>Samba and Printer Ports</title>
+<title>Creating the <parameter>[print$]</parameter> Share</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.
+In order to support the up- and downloading of printer driver files,
+you must first configure a file share named
+<parameter>[print$]</parameter>. The "public" name of this share is
+hard coded in Samba's internals (because it is hardcoded in the MS
+Windows clients too). It cannot be renamed since Windows clients are
+programmed to search for a service of exactly this name if they want
+to retrieve printer driver files.
</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.
+You should modify the server's <filename>smb.conf</filename> file to
+add the global parameters and create the
+<parameter>[print$]</parameter> 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 always a 'printer admin'.
+ printer admin = @ntadmin
+ [....]
+
+ [printers]
+ [....]
+
+ [print$]
+ comment = Printer Driver Download Area
+ path = /etc/samba/drivers
+ browseable = yes
+ guest ok = yes
+ read only = yes
+ write list = @ntadmin, root
+</programlisting></para>
+
<para>
-If you require that multiple ports be defined for some reason,
-&smb.conf; 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.
+Of course, you also need to ensure that the directory named by the
+<parameter>path</parameter> parameter exists on the Unix file system.
</para>
</sect2>
-</sect1>
+<sect2>
+<title>Parameters in the <parameter>[print$]</parameter> Section</title>
+<para>
+<parameter>[print$]</parameter> is a special section in
+<filename>smb.conf</filename>. It contains settings relevant to
+potential printer driver download and local installation by clients.
+</para>
-<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>
+<variablelist>
+<varlistentry><term><parameter>comment = Printer Driver
+Download Area</parameter></term>
+<listitem><para> the comment appears next to the share name if it is
+listed in a share list (usually Windows clients won't see it often but
+it will also appear up in a <command>smbclient -L sambaserver
+</command> output). </para></listitem></varlistentry>
+
+<varlistentry><term><parameter>path = /etc/samba/printers</parameter></term>
+<listitem><para> this is the path to the location of the Windows
+driver file deposit from the UNIX point of
+view.</para></listitem></varlistentry>
+
+<varlistentry><term><parameter>browseable = no</parameter></term>
+<listitem><para> this makes the <parameter>[print$]</parameter> share
+"invisible" in Network Neighbourhood to clients. However, you can
+still "mount" it from any client using the <command>net use
+g:\\sambaserver\print$</command> command in a "DOS box" or the
+"Connect network drive" menu from Windows
+Explorer.</para></listitem></varlistentry>
+
+<varlistentry><term><parameter>guest ok = yes</parameter></term>
+<listitem><para>this gives read only access to this share for all
+guest users. Access may be used to download and install printer
+drivers on clients. The requirement for <parameter>guest ok =
+yes</parameter> 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><para>
+The non-issue is this: if all your Windows NT users are guaranteed to
+be authenticated by the Samba server (for example if Samba
+authenticates via an NT domain server and the NT user has already been
+validated by the Domain Controller in order to logon to the Windows NT
+session), 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 <parameter>map to guest
+= Bad User</parameter> in the <parameter>[global]</parameter> section
+as well. Make sure you understand what this parameter does before
+using it.
+</para></note> </listitem></varlistentry>
+
+<varlistentry><term><parameter>read only = yes</parameter></term>
+<listitem><para>as we don't want everybody to upload driver files (or
+even change driver settings) we tagged this share as not
+writeable.</para></listitem></varlistentry>
+
+<varlistentry><term><parameter>write list = @ntadmin,root</parameter></term>
+<listitem><para>since the <parameter>[print$]</parameter> was made
+read only by the previous setting, we need to create a "write list"
+also. UNIX groups (denoted with a leading "@" character) and users
+listed here are allowed write access (as an exception to the general
+public's "read-only" access), which they need to update files on the
+share. Normally you will want to only name administrative level user
+accounts in this setting. Check the file system permissions to make
+sure these accounts can copy files to the share. If this is a non-root
+account, then the account should also be mentioned in the global
+<parameter>printer admin </parameter> parameter. See the
+<filename>smb.conf</filename> man page for more information on
+configuring file shares. </para></listitem></varlistentry>
+
+</variablelist>
+
+</sect2>
+
+<sect2>
+<title>Subdirectory Structure in <parameter>[print$]</parameter></title>
-<!--
-FIXME
-
- 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.
--->
+<para>
+In order for a Windows NT print server to support the downloading of
+driver files by multiple client architectures, you must create several
+subdirectories within the <parameter>[print$]</parameter> service
+(i.e. the Unix directory named by the <parameter>path</parameter>
+parameter). These correspond to each of the supported client
+architectures. Samba follows this model as well. Just like the name of
+the <parameter>[print$]</parameter> share itself, the subdirectories
+*must* be exactly the names listed below (you may leave out the
+subdirectories of architectures you don't want to support).
+</para>
+
+<para>
+Therefore, create a directory tree below the
+<parameter>[print$]</parameter> share for each architecture you wish
+to support.
+</para>
+
+<para><programlisting>
+
+[print$]--+--
+ |--W32X86 # serves drivers to "Windows NT x86"
+ |--WIN40 # serves drivers to "Windows 95/98"
+ |--W32ALPHA # serves drivers to "Windows NT Alpha_AXP"
+ |--W32MIPS # serves drivers to "Windows NT R4000"
+ |--W32PPC # serves drivers to "Windows NT PowerPC"
+
+</programlisting></para>
+
+<important><title>REQUIRED PERMISSIONS</title>
+
+<para>
+In order to add a new driver to your 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
+named in the <emphasis>printer admin</emphasis>list.</para></listitem>
+
+</itemizedlist>
+
+<para>
+Of course, the connected account must still possess access to add
+files to the subdirectories beneath
+<parameter>[print$]</parameter>. Remember that all file shares are set
+to 'read only' by default.
+</para>
+</important>
+
+<para>
+Once you have created the required <parameter>[print$]</parameter>
+service and associated subdirectories, go to a Windows NT 4.0/2k/XP
+client workstation. Open "Network Neighbourhood" or "My Network
+Places" and browse for the Samba host. Once you have located the
+server, navigate to its "Printers and Faxes" folder. You should see
+an initial listing of printers that matches the printer shares defined
+on your Samba host.
+</para>
+</sect2>
+</sect1>
<sect1>
-<title>Diagnosis</title>
+<title>Installing Drivers into <parameter>[print$]</parameter></title>
+
+<para>
+You have successfully created the <parameter>[print$]</parameter>
+share in <filename>smb.conf</filename>? And Samba has re-read its
+configuration? Good. But you are not yet ready to take off. The
+<emphasis>driver files</emphasis> need to be present in this share,
+too! So far it is still an empty share. Unfortunatly, it is not enough
+to just copy the driver files over. They need to be <emphasis>set
+up</emphasis> too. And that is a bit tricky, to say the least. We
+will now discuss two alternative ways to install the drivers into
+<parameter>[print$]</parameter>:
+</para>
+
+<itemizedlist>
+
+<listitem><para>using the Samba commandline utility
+<command>rpcclient</command> with its various subcommands (here:
+<command>adddriver</command> and <command>setdriver</command>) from
+any UNIX workstation;</para></listitem>
+
+<listitem><para>running a GUI (<emphasis>Printer
+Properties</emphasis> and <emphasis>Add Printer Wizard</emphasis>)
+from any Windows NT/2k/XP client workstation.</para></listitem>
+
+</itemizedlist>
+
+<para>
+The latter option is probably the easier one (even if the only
+entrance to this realm seems a little bit weird at first).
+</para>
<sect2>
-<title>Introduction</title>
+<title>Setting Drivers for existing Printers with a Client GUI</title>
+
+<para>
+The initial listing of printers in the Samba host's
+<emphasis>Printers</emphasis> folder accessed from a client's Explorer
+will have no real printer driver assigned to them. By default, in
+Samba 3.0 (as in 2.2.1 and later) this driver name is set to a NULL
+string. This must be changed now. The local <emphasis>Add Printer
+Wizard</emphasis>, run from NT/2000/XP clients, will help us in this
+task.
+</para>
+
+<para>
+However, the job to set a valid driver for the printer is not a
+straightforward one: You must attempt to view the printer properties
+for the printer to which you want the driver assigned. Open the
+Windows Explorer, open Network Neighbourhood, browse to the Samba
+host, open Samba's "Printers" folder, right-click the printer icon and
+select "Properties...". You are now trying to view printer and driver
+properties for a queue which has this default "NULL" driver
+assigned. This will result in an error message (this is normal here):
+</para>
+
+<para><computeroutput> 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?</computeroutput></para>
+
+<para>
+<emphasis>Important:</emphasis>Don't click "Yes"! Instead,
+<emphasis>click "No"</emphasis> in the error dialog. Only now you will
+be presented with the printer properties window. From here, the way to
+assign a driver to a printer is open to us. You have now the choice
+either:
+</para>
+
+<itemizedlist>
+<listitem><para>select a driver from the popup list of installed
+drivers. <emphasis>Initially this list will be empty.</emphasis>
+Or</para></listitem>
+
+<listitem><para>use the <emphasis>"New Driver..."</emphasis> button to
+install a new printer driver (which will in fact start up the
+APW).</para></listitem>
+</itemizedlist>
+
+<para>
+Once the APW is started, the procedure is exactly the same as the one
+you are familiar with in Wiindows (we assume here that you are
+familiar with the printer driver installations procedure on Windows
+NT). Make sure your connection is in fact setup as a user with
+<emphasis>printer admin</emphasis> privileges (if in doubt, use
+<command>smbstatus</command> to check for this). If you wish to
+install printer drivers for client operating systems other than
+"Windows NT x86", you will need to use the
+<emphasis>Sharing</emphasis> tab of the printer properties dialog.
+</para>
+
+<para>
+Assuming you have connected with an administrative (or root) account
+(as named by the <parameter>printer admin</parameter> parameter),
+you will also be able to modify other printer properties such as ACLs
+and default device settings using this dialog. For the default device
+settings, please consider the advice given further below.
+</para>
+</sect2>
+
+<sect2>
+<title>Setting Drivers for existing Printers with
+<command>rpcclient</command></title>
+
+<para>
+The second way to install printer drivers into
+<parameter>[print$]</parameter> and set them up in a valid way can be
+done from the UNIX command line. This involves four distinct steps:
+</para>
+
+<orderedlist>
+<listitem><para> gathering the info about the required driver files
+and collecting the files together;</para></listitem>
+
+<listitem><para> deposit the driver files into the
+<parameter>[print$]</parameter> share's correct subdirectories
+(possibly by using <command>smbclient</command>);</para></listitem>
+
+<listitem><para>2. -- running the <command>rpcclient</command>
+commandline utility once with the <command>addriver</command>
+subcommand,</para></listitem>
+
+<listitem><para>3. -- running <command>rpcclient</command> a second
+time with the <command>setdriver</command>
+subcommand.</para></listitem>
+</orderedlist>
+
+<para>
+We will provide detailed hints for each of these steps in the next few
+paragraphs.
+</para>
+
+<sect3>
+<title>Identifying the Driver Files</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.
+To find out about the driver files, you have two options: you could
+investigate the driver CD which comes with your printer. Study the
+<filename>*.inf</filename> file on the CD, if it is contained. This
+may not be the possible, since the *.inf file might be
+missing. Unfortunately, many vendors have now started to use their own
+installation programs. These installations packages are often some
+sort of Windows platform archive format, plus, the files may get
+re-named during the installation process. This makes it extremely
+difficult to identify the driver files you need.
</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.
+Then you only have the second option: install the driver first on a
+Windows client *locally* and investigate which file names and paths it
+uses after they are installed. (Note, that you need to repeat this
+procedure for every client platform you want to support. We are going
+to show it here for the "<emphasis>W32X86</emphasis>" platform only, a
+name used by Microsoft for all WinNT/2k/XP clients...)
</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:
+A good method to recognize the driver files this is to print the test
+page from the driver's <emphasis>Properties</emphasis> Dialog
+(<emphasis>General</emphasis> tab). Then look at the list of driver
+files named on the printout. You'll need to recognize what Windows
+(and Samba) are calling the <parameter>Driver File</parameter> , the
+<parameter>Data File</parameter>, the <parameter>Config File</parameter>,
+the <parameter>Help File</parameter> and (optionally) the
+<parameter>Dependent Driver Files</parameter> (this may vary slightly
+for Windows NT). You need to remember all names (or better take a
+note) for the next steps.
+</para>
+
+<para>
+Another method to quickly test the driver filenames and related paths
+is provided by the <command>rpcclient</command> utility. Run it with
+<command>enumdrivers</command> or with the
+<command>getdriver</command> subcommand, each in the
+<emphasis>3</emphasis> level. In the following example,
+<emphasis>TURBO_XP</emphasis> is the name of the Windows PC (in this
+case it was a Windows XP Professional laptop, BTW). I had installed
+the driver locally to TURBO_XP while <emphasis>kde-bitshop</emphasis> is
+the name of the Linux host from which I am working. We could run an
+<emphasis>interactive</emphasis> <command>rpcclient</command> session;
+then we'd get an <emphasis>rpcclient /></emphasis> prompt and would
+type the subcommands at this prompt. This is left as a good exercise
+to the reader. For now we use <command>rpcclient</command> with the
+<parameter>-c</parameter> parameter to execute a single subcommand
+line and exit again. This is the method you would use if you want to
+create scripts to automate the procedure for a large number of
+printers and drivers. Note the different quotes used to overcome the
+different spaces in between words:
</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
+
+ kde-bitshop:~# rpcclient -U'Danka%xxxx' -c 'getdriver "Heidelberg Digimaster 9110 (PS)" 3' TURBO_XP
+ cmd = getdriver "Heidelberg Digimaster 9110 (PS)" 3
+
+ [Windows NT x86]
+ Printer Driver Info 3:
+ Version: [2]
+ Driver Name: [Heidelberg Digimaster 9110 (PS)]
+ Architecture: [Windows NT x86]
+ Driver Path: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\HDNIS01_de.DLL]
+ Datafile: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.ppd]
+ Configfile: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\HDNIS01U_de.DLL]
+ Helpfile: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\HDNIS01U_de.HLP]
+
+ Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.DLL]
+ Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.INI]
+ Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1KMMin.DLL]
+ Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.dat]
+ Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.cat]
+ Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.def]
+ Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.hre]
+ Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.vnd]
+ Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de.hlp]
+ Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\Hddm91c1_de_reg.HLP]
+ Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\HDNIS01Aux.dll]
+ Dependentfiles: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\HDNIS01_de.NTF]
+
+ Monitorname: []
+ Defaultdatatype: []
+
</programlisting></para>
<para>
-The following are nice to know about:
+You may notice, that this driver has quite a big number of
+"Dependentfiles" (I know worse cases however). Also, strangely, the
+"<filename>Driver File</filename>" is here tagged as "<filename>Driver
+Path</filename>".... oh, well. Here we don't have yet support for the
+so-called "WIN40" architecture installed. This name is used by
+Microsoft for the Win95/98/ME platforms. If we want to support these,
+we need to install the Win95/98/ME driver files in addition to those
+for W32X86 (i.e. the WinNT72000/XP clients) onto a Windows PC. This PC
+can also host the Win9x drivers, even if itself runs on Windows NT,
+2000 or XP.
+</para>
+
+<para>
+Since the <parameter>print$</parameter> share is usually accessible
+through the Network Neighbourhood, you can also use the UNC notation
+from Windows Explorer to poke at it. The Win9x driver files will end
+up in subdirectory "0" of the "WIN40" directory. The full path to
+access them will be
+<filename>\\WINDOWSHOST\print$\WIN40\0\</filename>.
+</para>
+
+<note><para> more recent drivers on Windows 2000 and Wndows XP are
+installed into the "3" subdirectory instead of the "2". The version 2
+of drivers, as used in Windows NT, were running in Kernel Mode.
+Windows 2000 changed this. While it still can use the Kernel Mode
+drivers (if this is enabled by the Admin), its native mode for printer
+drivers is User Mode execution. This requires drivers designed for
+this. These type of drivers install into the "3" subdirectory.
+</para></note>
+</sect3>
+
+<sect3>
+<title>Collecting the Driver Files from a Windows Host's
+<parameter>[print$]</parameter> Share</title>
+
+<para>
+Now we need to collect all the driver files we identified. in our
+previous step. Where do we get them from? Well, why not retrieve them
+from the very PC and the same <parameter>[print$]</parameter> share
+which we investigated in our last step to identify the files? We can
+use <command>smbclient</command> to do this. We will use the paths and
+names which were leaked to us by <command>getdriver</command>. The
+listing is edited to include linebreaks for readability:
</para>
<para><programlisting>
- queuepause command - stop a printer or print queue
- queueresume command - start a printer or print queue
+
+ kde-bitshop:~# smbclient //TURBO_XP/print\$ -U'Danka%xxxx' \
+ -c 'cd W32X86/2;mget HD*_de.* \
+ hd*ppd Hd*_de.* Hddm*dll HDN*Aux.DLL'
+ added interface ip=10.160.51.60 bcast=10.160.51.255 nmask=255.255.252.0
+ Got a positive name query response from 10.160.50.8 ( 10.160.50.8 )
+ Domain=[DEVELOPMENT] OS=[Windows 5.1] Server=[Windows 2000 LAN Manager]
+ Get file Hddm91c1_de.ABD? n
+ Get file Hddm91c1_de.def? y
+ getting file \W32X86\2\Hddm91c1_de.def of size 428 as Hddm91c1_de.def (22.0 kb/s) \
+ (average 22.0 kb/s)
+ Get file Hddm91c1_de.DLL? y
+ getting file \W32X86\2\Hddm91c1_de.DLL of size 876544 as Hddm91c1_de.DLL (737.3 kb/s) \
+ (average 737.3 kb/s)
+ [...,]
+
</programlisting></para>
<para>
-Example:
+After this command is complete, the files are in our current local
+directory. You probably have noticed that this time we passed several
+commands to the "-c" parameter, separated by semi-colons. This
+effects that all commands are executed in sequence on the remote
+Windows server before smbclient exits again.
+</para>
+
+<para>
+Don't forget to repeat the procedure for the "WIN40" architecture
+should you need to support Win95/98/XP clients. Remember, the files
+for these architectures are in the WIN40/0/ subdir. Once we are
+complete, we can run <command>smbclient ... put</command> to store
+the collected files on the Samba server's
+<parameter>[print$]</parameter> share.
+</para>
+</sect3>
+
+<sect3>
+<title>Depositing the Driver Files into <parameter>[print$]</parameter></title>
+
+<para>
+So, now we are going to put the driver files into the
+<parameter>[print$]</parameter> share. Remember, the UNIX path to this
+share has been defined previously in your
+<filename>smb.conf</filename>. You also have created subdirectories
+for the different Windows client types you want to support. Supposing
+your <parameter>[print$]</parameter> share maps to the UNIX path
+<filename>/etc/samba/drivers/</filename>, your driver files should now
+go here:
+</para>
+
+<itemizedlist>
+<listitem><para>for all Windows NT, 2000 and XP clients into
+<filename>/etc/samba/drivers/W32X86/</filename> <emphasis>but
+*not*(yet) into the "2" subdir</emphasis>!</para></listitem>
+
+<listitem><para>for all Windows 95, 98 and ME clients into
+<filename>/etc/samba/drivers/WIN40/</filename> -- <emphasis>but *not*
+(yet) into the "0" subdir</emphasis>!</para></listitem>
+</itemizedlist>
+
+<para>
+We again use smbclient to transfer the driver files across the
+network. We specify the same files and paths as were leaked to us by
+running "<command>getdriver</command>" against the original
+<emphasis>Windows</emphasis> install. However, now we are going to
+store the files into a <emphasis>Samba/UNIX</emphasis> print server's
+<parameter>[print$]</parameter> share...
</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
+
+ kde-bitshop:~# smbclient //SAMBA-CUPS/print\$ -U'root%xxxx' -c 'cd W32X86; put HDNIS01_de.DLL; \
+ put Hddm91c1_de.ppd; put HDNIS01U_de.DLL; \
+ put HDNIS01U_de.HLP; put Hddm91c1_de.DLL; \
+ put Hddm91c1_de.INI; put Hddm91c1KMMin.DLL; \
+ put Hddm91c1_de.dat; put Hddm91c1_de.dat; \
+ put Hddm91c1_de.def; put Hddm91c1_de.hre; \
+ put Hddm91c1_de.vnd; put Hddm91c1_de.hlp; \
+ put Hddm91c1_de_reg.HLP; put HDNIS01Aux.dll; \
+ put HDNIS01_de.NTF'
+ added interface ip=10.160.51.60 bcast=10.160.51.255 nmask=255.255.252.0
+ Got a positive name query response from 10.160.51.162 ( 10.160.51.162 )
+ Domain=[CUPS-PRINT] OS=[Unix] Server=[Samba 2.2.7a]
+ putting file HDNIS01_de.DLL as \W32X86\HDNIS01_de.DLL (4465.5 kb/s) (average 4465.5 kb/s)
+ putting file Hddm91c1_de.ppd as \W32X86\Hddm91c1_de.ppd (12876.8 kb/s) (average 4638.9 kb/s)
+ putting file HDNIS01U_de.DLL as \W32X86\HDNIS01U_de.DLL (20249.8 kb/s) (average 5828.3 kb/s)
+ putting file HDNIS01U_de.HLP as \W32X86\HDNIS01U_de.HLP (9652.8 kb/s) (average 5899.8 kb/s)
+ putting file Hddm91c1_de.DLL as \W32X86\Hddm91c1_de.DLL (23777.7 kb/s) (average 10400.6 kb/s)
+ putting file Hddm91c1_de.INI as \W32X86\Hddm91c1_de.INI (98.6 kb/s) (average 10329.0 kb/s)
+ putting file Hddm91c1KMMin.DLL as \W32X86\Hddm91c1KMMin.DLL (22931.5 kb/s) (average 10501.7 kb/s)
+ putting file Hddm91c1_de.dat as \W32X86\Hddm91c1_de.dat (2462.8 kb/s) (average 10393.0 kb/s)
+ putting file Hddm91c1_de.dat as \W32X86\Hddm91c1_de.dat (4925.3 kb/s) (average 10356.3 kb/s)
+ putting file Hddm91c1_de.def as \W32X86\Hddm91c1_de.def (417.9 kb/s) (average 10290.1 kb/s)
+ putting file Hddm91c1_de.hre as \W32X86\Hddm91c1_de.hre (22571.3 kb/s) (average 11338.5 kb/s)
+ putting file Hddm91c1_de.vnd as \W32X86\Hddm91c1_de.vnd (3384.6 kb/s) (average 10754.3 kb/s)
+ putting file Hddm91c1_de.hlp as \W32X86\Hddm91c1_de.hlp (18406.8 kb/s) (average 10839.8 kb/s)
+ putting file Hddm91c1_de_reg.HLP as \W32X86\Hddm91c1_de_reg.HLP (20278.3 kb/s) (average 11386.3 kb/s)
+ putting file HDNIS01Aux.dll as \W32X86\HDNIS01Aux.dll (14994.6 kb/s) (average 11405.2 kb/s)
+ putting file HDNIS01_de.NTF as \W32X86\HDNIS01_de.NTF (23390.2 kb/s) (average 13170.8 kb/s)
+
</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.
+Phewww -- that was a lot of typing! Most drivers are a lot smaller --
+many only having 3 generic PostScript driver files plus 1 PPD. Note,
+that while we did retrieve the files from the "2" subdirectory of the
+"W32X86" directory from the Windows box, we <emphasis>don't</emphasis>
+put them (for now) in this same subdirectory of the Samba box! This
+re-location will automatically be done by the
+<command>adddriver</command> command which we will run shortly (and
+don't forget to also put the files for the Win95/98/ME architecture
+into the <emphasis>WIN40/</emphasis> subdirectory should you need
+them).
</para>
+</sect3>
+
+<sect3>
+<title>Check if the Driver Files are there (with smbclient)</title>
<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.
+For now we verify that our files are there. This can be done with
+<command>smbclient</command> too (but of course you can log in via SSH
+also and do this through a standard UNIX shell access too):
</para>
+<para><programlisting>
+
+ kde-bitshop:~# smbclient //SAMBA-CUPS/print\$ -U 'root%xxxx' -c 'cd W32X86; pwd; dir; cd 2; pwd; dir'
+ added interface ip=10.160.51.60 bcast=10.160.51.255 nmask=255.255.252.0
+ Got a positive name query response from 10.160.51.162 ( 10.160.51.162 )
+ Domain=[CUPS-PRINT] OS=[Unix] Server=[Samba 2.2.7a]
+
+ Current directory is \\SAMBA-CUPS\print$\W32X86\
+ . D 0 Sun May 4 03:56:35 2003
+ .. D 0 Thu Apr 10 23:47:40 2003
+ 2 D 0 Sun May 4 03:56:18 2003
+ HDNIS01Aux.dll A 15356 Sun May 4 03:58:59 2003
+ Hddm91c1KMMin.DLL A 46966 Sun May 4 03:58:59 2003
+ HDNIS01_de.DLL A 434400 Sun May 4 03:58:59 2003
+ HDNIS01_de.NTF A 790404 Sun May 4 03:56:35 2003
+ Hddm91c1_de.DLL A 876544 Sun May 4 03:58:59 2003
+ Hddm91c1_de.INI A 101 Sun May 4 03:58:59 2003
+ Hddm91c1_de.dat A 5044 Sun May 4 03:58:59 2003
+ Hddm91c1_de.def A 428 Sun May 4 03:58:59 2003
+ Hddm91c1_de.hlp A 37699 Sun May 4 03:58:59 2003
+ Hddm91c1_de.hre A 323584 Sun May 4 03:58:59 2003
+ Hddm91c1_de.ppd A 26373 Sun May 4 03:58:59 2003
+ Hddm91c1_de.vnd A 45056 Sun May 4 03:58:59 2003
+ HDNIS01U_de.DLL A 165888 Sun May 4 03:58:59 2003
+ HDNIS01U_de.HLP A 19770 Sun May 4 03:58:59 2003
+ Hddm91c1_de_reg.HLP A 228417 Sun May 4 03:58:59 2003
+ 40976 blocks of size 262144. 709 blocks available
+
+ Current directory is \\SAMBA-CUPS\print$\W32X86\2\
+ . D 0 Sun May 4 03:56:18 2003
+ .. D 0 Sun May 4 03:56:35 2003
+ ADOBEPS5.DLL A 434400 Sat May 3 23:18:45 2003
+ laserjet4.ppd A 9639 Thu Apr 24 01:05:32 2003
+ ADOBEPSU.DLL A 109568 Sat May 3 23:18:45 2003
+ ADOBEPSU.HLP A 18082 Sat May 3 23:18:45 2003
+ PDFcreator2.PPD A 15746 Sun Apr 20 22:24:07 2003
+ 40976 blocks of size 262144. 709 blocks available
+
+</programlisting></para>
+
+<para>
+Notice that there are already driver files present in the
+<filename>2</filename> subdir (probably from a previous
+installation). Once the files for the new driver are there too, you
+are still a few steps away from being able to use them on the
+clients. The only thing you could do *now* is to retrieve them from a
+client just like you retrieve ordinary files from a file share, by
+opening print$ in Windows Explorer. But that wouldn't install them per
+Point'n'Print. The reason is: Samba doesn't know yet that these files
+are something special, namely <emphasis>printer driver
+files</emphasis> and it doesn't know yet to which print queue(s) these
+driver files belong.
+</para>
+</sect3>
+
+<sect3>
+<title>Running <command>rpcclient</command> with
+<command>adddriver</command></title>
+
<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.
+So, next you must tell Samba about the special category of the files
+you just uploaded into the <parameter>[print$]</parameter> share. This
+is done by the "<command>adddriver</command>" command. It will
+prompt Samba to register the driver files into its internal TDB
+database files. The following command and its output has been edited,
+again, for readability:
</para>
+<para><programlisting>
+
+ kde-bitshop:~# rpcclient -Uroot%xxxx -c 'adddriver "Windows NT x86" "dm9110:HDNIS01_de.DLL: \
+ Hddm91c1_de.ppd:HDNIS01U_de.DLL:HDNIS01U_de.HLP: \
+ NULL:RAW:Hddm91c1_de.DLL,Hddm91c1_de.INI, \
+ Hddm91c1_de.dat,Hddm91c1_de.def,Hddm91c1_de.hre, \
+ Hddm91c1_de.vnd,Hddm91c1_de.hlp,Hddm91c1KMMin.DLL, \
+ HDNIS01Aux.dll,HDNIS01_de.NTF, \
+ Hddm91c1_de_reg.HLP' SAMBA-CUPS
+
+ cmd = adddriver "Windows NT x86" "dm9110:HDNIS01_de.DLL:Hddm91c1_de.ppd:HDNIS01U_de.DLL: \
+ HDNIS01U_de.HLP:NULL:RAW:Hddm91c1_de.DLL,Hddm91c1_de.INI, \
+ Hddm91c1_de.dat,Hddm91c1_de.def,Hddm91c1_de.hre, \
+ Hddm91c1_de.vnd,Hddm91c1_de.hlp,Hddm91c1KMMin.DLL, \
+ HDNIS01Aux.dll,HDNIS01_de.NTF,Hddm91c1_de_reg.HLP"
+
+ Printer Driver dm9110 successfully installed.
+
+</programlisting></para>
+
+<para>
+After this step the driver should be recognized by Samba on the print
+server. You need to be very carefull when typing the command. Don't
+exchange the order of the fields. Some changes would lead to a
+<computeroutput>NT_STATUS_UNSUCCESSFUL</computeroutput> error
+message. These become obvious. Other changes might install the driver
+files successfully, but render the driver unworkable. So take care!
+Hints about the syntax of the adddriver command are in the man
+page. The CUPS printing chapter of this HOWTO collection provides a
+more detailed description, if you should need it.
+</para>
+</sect3>
+
+<sect3>
+<title>Check how Driver Files have been moved after
+<command>adddriver</command> finished</title>
+
+<para>
+One indication for Samba's recognition of the files as driver files is
+the <computeroutput>successfully installed</computeroutput> message.
+Another one is the fact, that our files have been moved by the
+<command>adddriver</command> command into the "<filename>2</filename>"
+subdirectory. You can check this again with
+<command>smbclient</command>:
+</para>
+
+<para><programlisting>
+
+ kde-bitshop:~# smbclient //SAMBA-CUPS/print\$ -Uroot%xxxx -c 'cd W32X86;dir;pwd;cd 2;dir;pwd'
+ added interface ip=10.160.51.162 bcast=10.160.51.255 nmask=255.255.252.0
+ Domain=[CUPS-PRINT] OS=[Unix] Server=[Samba 2.2.7a]
+
+ Current directory is \\SAMBA-CUPS\print$\W32X86\
+ . D 0 Sun May 4 04:32:48 2003
+ .. D 0 Thu Apr 10 23:47:40 2003
+ 2 D 0 Sun May 4 04:32:48 2003
+ 40976 blocks of size 262144. 731 blocks available
+
+ Current directory is \\SAMBA-CUPS\print$\W32X86\2\
+ . D 0 Sun May 4 04:32:48 2003
+ .. D 0 Sun May 4 04:32:48 2003
+ DigiMaster.PPD A 148336 Thu Apr 24 01:07:00 2003
+ ADOBEPS5.DLL A 434400 Sat May 3 23:18:45 2003
+ laserjet4.ppd A 9639 Thu Apr 24 01:05:32 2003
+ ADOBEPSU.DLL A 109568 Sat May 3 23:18:45 2003
+ ADOBEPSU.HLP A 18082 Sat May 3 23:18:45 2003
+ PDFcreator2.PPD A 15746 Sun Apr 20 22:24:07 2003
+ HDNIS01Aux.dll A 15356 Sun May 4 04:32:18 2003
+ Hddm91c1KMMin.DLL A 46966 Sun May 4 04:32:18 2003
+ HDNIS01_de.DLL A 434400 Sun May 4 04:32:18 2003
+ HDNIS01_de.NTF A 790404 Sun May 4 04:32:18 2003
+ Hddm91c1_de.DLL A 876544 Sun May 4 04:32:18 2003
+ Hddm91c1_de.INI A 101 Sun May 4 04:32:18 2003
+ Hddm91c1_de.dat A 5044 Sun May 4 04:32:18 2003
+ Hddm91c1_de.def A 428 Sun May 4 04:32:18 2003
+ Hddm91c1_de.hlp A 37699 Sun May 4 04:32:18 2003
+ Hddm91c1_de.hre A 323584 Sun May 4 04:32:18 2003
+ Hddm91c1_de.ppd A 26373 Sun May 4 04:32:18 2003
+ Hddm91c1_de.vnd A 45056 Sun May 4 04:32:18 2003
+ HDNIS01U_de.DLL A 165888 Sun May 4 04:32:18 2003
+ HDNIS01U_de.HLP A 19770 Sun May 4 04:32:18 2003
+ Hddm91c1_de_reg.HLP A 228417 Sun May 4 04:32:18 2003
+ 40976 blocks of size 262144. 731 blocks available
+
+</programlisting></para>
+
+<para>
+Another verification is that the timestamp of the printing TDB files
+is now updated (and possibly their filesize has increased).
+</para>
+</sect3>
+
+<sect3>
+<title>Check if the Driver is recognized by Samba</title>
+
+<para>
+Now the driver should be registered with Samba. We can easily verify
+this, and will do so in a moment. However, this driver is
+<emphasis>not yet</emphasis> associated with a particular
+<emphasis>printer</emphasis>. We may check the driver status of the
+files by at least three methods:
+</para>
+
+<itemizedlist>
+<listitem><para>from any Windows client browse Network Neighbourhood,
+finde the Samba host and open the Samba "<emphasis>Printers and
+Faxes</emphasis>" folder. Select any printer icon, right-click and
+select the printer " <emphasis>Properties</emphasis>". Click on the
+"<emphasis>Advanced</emphasis>" tab. Here is a field indicating the
+driver for that printer. A drop down menu allows you to change that
+driver (be carefull to not do this unwittingly.). You can use this
+list to view all drivers know to Samba. Your new one should be amongst
+them. (Each type of client will only see his own architecture's
+list. If you don't have every driver installed for each platform, the
+list will differ if you look at it from Windows95/98/ME or
+WindowsNT/2000/XP.)</para></listitem>
+
+<listitem><para>from a Windows 2000 or XP client (not WinNT) browse
+<emphasis>Network Neighbourhood</emphasis>, search for the Samba
+server and open the server's <emphasis>Printers</emphasis> folder,
+right-click the white background (with no printer highlighted). Select
+"<emphasis>Server Properties</emphasis>". On the
+"<emphasis>Drivers</emphasis> " tab you will see the new driver listed
+now. This view enables you to also inspect the list of files belonging
+to that driver<emphasis> (this doesn't work on Windows NT, but only on
+Windows 2000 and Windows XP. WinNT doesn't provide the "Drivers"
+tab).</emphasis>. An alternative, much quicker method for Windows
+2000/XP to start this dialog is by typing into a DOS box (you must of
+course adapt the name to your Samba server instead of SAMBA-CUPS):
+</para>
+
+<para><programlisting>
+ rundll32 printui.dll,PrintUIEntry /s /t2 /n\\SAMBA-CUPS
+</programlisting></para>
+</listitem>
+
+<listitem><para>from a UNIX prompt run this command (or a variant
+thereof), where "SAMBA-CUPS" is the name of the Samba host and "xxxx"
+represents the actual Samba password assigned to root:
+</para>
+
+<para><programlisting>
+ rpcclient -U'root%xxxx' -c 'enumdrivers' SAMBA-CUPS
+</programlisting></para>
+
+<para>
+You will see a listing of all drivers Samba knows about. Your new one
+should be amongst them. But it is only listed under the [Windows NT
+x86] heading, not under [Windows 4.0], since we didn't install that
+part. Or did *you*? -- You will see a listing of all drivers Samba
+knows about. Your new one should be amongst them. In our example it is
+named <emphasis>dm9110</emphasis>. Note that the 3rd column shows the
+other installed drivers twice, for each supported architecture one
+time. Our new driver only shows up for "Windows NT 4.0 or 2000". To
+have it present for "Windows 95, 98 and ME" you'll have to repeat the
+whole procedure with the WIN40 architecture and subdirectory.
+</para></listitem>
+</itemizedlist>
+</sect3>
+
+<sect3>
+<title>A sidenote: you are not bound to specific driver names</title>
+
+<para>
+You can name the driver as you like. If you repeat the
+<command>adddriver</command> step, with the same files as before, but
+with a different driver name, it will work the same:
+</para>
+
+<para><programlisting>
+
+ kde-bitshop:~# rpcclient -Uroot%xxxx \
+ -c 'adddriver "Windows NT x86" \
+ "myphantasydrivername:HDNIS01_de.DLL: \
+ Hddm91c1_de.ppd:HDNIS01U_de.DLL:HDNIS01U_de.HLP: \
+ NULL:RAW:Hddm91c1_de.DLL,Hddm91c1_de.INI, \
+ Hddm91c1_de.dat,Hddm91c1_de.def,Hddm91c1_de.hre, \
+ Hddm91c1_de.vnd,Hddm91c1_de.hlp,Hddm91c1KMMin.DLL, \
+ HDNIS01Aux.dll,HDNIS01_de.NTF,Hddm91c1_de_reg.HLP' SAMBA-CUPS
+
+ cmd = adddriver "Windows NT x86"
+ "myphantasydrivername:HDNIS01_de.DLL:Hddm91c1_de.ppd:HDNIS01U_de.DLL:\
+ HDNIS01U_de.HLP:NULL:RAW:Hddm91c1_de.DLL,Hddm91c1_de.INI, \
+ Hddm91c1_de.dat,Hddm91c1_de.def,Hddm91c1_de.hre, \
+ Hddm91c1_de.vnd,Hddm91c1_de.hlp,Hddm91c1KMMin.DLL, \
+ HDNIS01Aux.dll,HDNIS01_de.NTF,Hddm91c1_de_reg.HLP"
+
+ Printer Driver myphantasydrivername successfully installed.
+
+</programlisting></para>
+
+<para>
+You will also be able to bind that driver to any print queue (however,
+you are responsible yourself that you associate drivers to queues
+which make sense to the target printer). Note, that you can't run the
+<command>rpcclient</command> <command>adddriver</command> command
+repeatedly. Each run "consumes" the files you had put into the
+<parameter>[print$]</parameter> share by moving them into the
+respective subdirectories. So you <emphasis>must</emphasis> precede an
+"<command>smbclient ... put"</command> command before each
+"<command>rpcclient ... addriver</command>" command.
+</para>
+</sect3>
+
+<sect3>
+<title>La Grande Finale: Running <command>rpcclient</command> with
+<command>setdriver</command></title>
+
+<para>
+Samba still needs to know <emphasis>which</emphasis> printer's driver
+this is. It needs to create a mapping of the driver to a printer, and
+store this info in its "memory", the TDB files. The <command>rpcclient
+setdriver</command> command achieves exactly this:
+</para>
+
+<para><programlisting>
+ kde-bitshop:~# rpcclient -U'root%xxxx' -c 'setdriver dm9110 myphantasydrivername' SAMBA-CUPS
+ cmd = setdriver dm9110 myphantasydrivername
+ Successfully set dm9110 to driver myphantasydrivername.
+</programlisting></para>
+
+<para>
+Ahhhhh -- no, I didn't want to do that. Repeat, this time with the
+name I intended:
+</para>
+
+<para><programlisting>
+ kde-bitshop:~# rpcclient -U'root%xxxx' -c 'setdriver dm9110 dm9110' SAMBA-CUPS
+ cmd = setdriver dm9110 dm9110
+ Succesfully set dm9110 to driver dm9110.
+</programlisting></para>
+
+<para>
+The syntax of the command is <command>rpcclient -U'root%sambapassword'
+-c 'setdriver "printername" "drivername' SAMBA-Hostname</command> . --
+Now we have done *most* of the work. But not yet all....
+</para>
+
+<note><para>
+the "setdriver" command will only succeed if the printer is known to
+Samba already. A bug in 2.2.x prevented Samba from recognizing freshly
+installed printers. You had to restart Samba, or at least send a HUP
+signal to all running smbd processes to work around this:
+<command>kill -HUP `pidof smbd`</command>. </para></note>
+</sect3>
</sect2>
+</sect1>
+
+<sect1>
+<title>"The Proof of the Pudding lies in the Eating" (Client Driver Insta
+Procedure)</title>
+
+<para>
+A famous philosopher said once: <quote>The Proof of the Pudding lies
+in the Eating</quote>. The proof for our setup lies in the printing.
+So let's install the printer driver onto the client PCs. This is not
+as straightforward as it may seem. Read on.
+</para>
<sect2>
-<title>Debugging printer problems</title>
+<title>The first Client Driver Installation</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:
+Especially important is the installation onto the first client PC (for
+each architectural platform separately). Once this is done correctly,
+all further clients are easy to setup and shouldn't need further
+attention. What follows is a description for the recommended first
+procedure. You work now from a client workstation. First you should
+guarantee that your connection is not unwittingly mapped to
+<parameter>bad user</parameter> "nobody". In a DOS box type:
</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
+net use \\SAMBA-SERVER\print$ /user:root
</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:
+Replace root, if needed, by another valid 'printer admin' user as
+given in the <filename>smb.conf</filename> definition. Should you
+already be connected as a different user, you'll get an error
+message. There is no easy way to get rid of that connection, because
+Windows doesn't seem to know a concept of "logging off" from a share
+connection (don't confuse this with logging off from the local
+workstation; that is a different matter). You can try to close
+<emphasis>all</emphasis> Windows file explorer and Internet Explorer
+windows. As a last resort, you may have to reboot. Make sure there is
+no automatic re-connection set up. It may be easier to go to a
+different workstation and try from there. After you have made sure you
+are connected as a printer admin user (you can check this with the
+<command>smbstatus</command> command on Samba) do this from the
+Windows workstation:
</para>
-<para><screen>
-<prompt>h4: {42} % </prompt><userinput>echo hi >/tmp/hi</userinput>
-<prompt>h4: {43} % </prompt><userinput>smbclient //localhost/lw4</userinput>
-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]
-<prompt>smb: \> </prompt><userinput>print /tmp/hi</userinput>
-putting file /tmp/hi as hi-17534 (0.0 kb/s) (average 0.0 kb/s)
-<prompt>smb: \> </prompt><userinput>queue</userinput>
-1049 3 hi-17534
-<prompt>smb: \> </prompt><userinput>cancel 1049</userinput>
-Error cancelling job 1049 : code 0
-<prompt>smb: \> </prompt><userinput>cancel 1049</userinput>
-Job 1049 cancelled
-<prompt>smb: \> </prompt><userinput>queue</userinput>
-<prompt>smb: \> </prompt><userinput>exit</userinput>
-</screen></para>
+<itemizedlist>
+<listitem><para>Open <emphasis>Network
+Neighbourhood</emphasis></para></listitem>
+
+<listitem><para>Browse to Samba server</para></listitem>
+
+<listitem><para>Open its <emphasis>Printers and
+Faxes</emphasis> folder</para></listitem>
+
+<listitem><para>Highlight and right-click the printer</para></listitem>
+
+<listitem><para>Select <emphasis>Connect...</emphasis> (for WinNT4/2K
+it is possibly <emphasis>Install...</emphasis>)</para></listitem>
+</itemizedlist>
<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.
+A new printer (named <replaceable>printername</replaceable> on
+samba-server) should now have appeared in your
+<emphasis>local</emphasis> Printer folder (check <emphasis>Start --
+Settings -- Control Panel -- Printers and Faxes</emphasis>).
+</para>
+
+<para>
+Most likely you are now tempted to try and print a test page. After
+all, you now can open the printer properties and on the "General" tab,
+there is a button offering to do just that. But chances are that you
+get an error message saying <computeroutput>Unable to print Test
+Page</computeroutput>. The reason might be that there is not yet a
+valid Device Mode set for the driver, or that the "Printer Driver
+Data" set is still incomplete.
+</para>
+
+<para>
+You must now make sure that a valid "Device Mode" is set for the
+driver. Don't fear -- we will explain now what that means.
</para>
</sect2>
<sect2>
-<title>What printers do I have?</title>
+<title>IMPORTANT! Setting Device Modes on new Printers</title>
+
+<para>
+In order for a printer to be truly usable by a Windows NT/2K/XP
+client, it must possess:
+</para>
+
+<itemizedlist>
+<listitem><para>a valid <emphasis>Device Mode</emphasis> generated by
+the driver for the printer (defining things like paper size,
+orientation and duplex settings), and</para></listitem>
+
+<listitem><para>a complete set of
+<emphasis>Printer Driver Data</emphasis> generated by the
+driver.</para></listitem>
+</itemizedlist>
<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:
+If either one of these is incomplete, the clients can produce less
+than optimal output at best. In the worst cases, unreadable garbage or
+nothing at all comes from the printer or they produce a harvest of
+error messages when attempting to print. Samba stores the named values
+and all printing related info in its internal TDB database files
+<filename>(ntprinters.tdb</filename>,
+<filename>ntdrivers.tdb</filename>, <filename>printing.tdb</filename>
+and <filename>ntforms.tdb</filename>).
</para>
-<para><screen>
-<prompt>$ </prompt><userinput>testprns printer /etc/printcap</userinput>
-</screen></para>
+<para>
+What do these two words stand for? Basically, the Device Mode and the
+set of Printer Driver Data is a collection of settings for all print
+queue properties, initialized in a sensible way. Device Modes and
+Printer Driver Data should initially be set on the print server (that is
+here: the Samba host) to healthy values so that the clients can start
+to use them immediately. How do we set these initial healthy values?
+This can be achieved by accessing the drivers remotely from an NT (or
+2k/XP) client, as is discussed in the next paragraphs.
+</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:
+Be aware, that a valid Device Mode can only be initiated by a
+"<emphasis>printer admin</emphasis>", or root (the reason should be
+obvious). Device Modes can only correctly be set by executing the
+printer driver program itself. Since Samba can not execute this Win32
+platform driver code, it sets this field initially to NULL (which is
+not a valid setting for clients to use). Fortunately, most drivers
+generate themselves the Printer Driver Data that is needed, when they
+are uploaded to the <parameter>[print$]</parameter> share with the
+help of the APW or rpcclient.
</para>
-<para><screen>
-<prompt>$ </prompt><userinput>testprns -a printer /etc/printcap</userinput>
-<prompt>$ </prompt><userinput>testprns -a printer '|/bin/cat printcap'</userinput>
-</screen></para>
+<para>
+The generation and setting of a first valid Device Mode however
+requires some "tickling" from a client, to set it on the Samba
+server. The easiest means of doing so is to simply change the page
+orientation on the server's printer. This "executes" enough of the
+printer driver program on the client for the desired effect to happen,
+and feeds back the new Device Mode to our Samba server. You can use the
+native Windows NT/2K/XP printer properties page from a Window client
+for this:
+</para>
+
+<itemizedlist>
+<listitem><para>Browse the "Network Neighbourhood"</para></listitem>
+
+<listitem><para>Find the Samba server</para></listitem>
+
+<listitem><para>Open the Samba server's <emphasis>Printers and
+Faxes</emphasis> folder</para></listitem>
+
+<listitem><para>Highlight the shared printer in question</para></listitem>
+
+<listitem><para>Right-click the printer (you may already be here, if you
+followed the last section's description)</para></listitem>
+<listitem><para>At the bottom of the context menu select
+"Properties...." (if the menu still offers the "Connect..." entry
+further above, you need to click that one first to achieve the driver
+installation as shown in the last section)</para></listitem>
+
+<listitem><para>Go to the "Advanced" tab; click on "Printing
+Defaults..."</para></listitem>
+
+<listitem><para>Change the "Portrait" page setting to "Landscape" (and
+back)</para></listitem>
+
+<listitem><para>(Oh, and make sure to <emphasis>apply</emphasis>
+changes between swapping the page orientation to cause the change to
+actually take effect...).</para></listitem>
+
+<listitem><para>While you're at it, you may optionally also want to
+set the desired printing defaults here, which then apply to all future
+client driver installations on the remaining from now
+on.</para></listitem>
+</itemizedlist>
+
+<para>
+This procedure has executed the printer driver program on the client
+platform and fed back the correct Device Mode to Samba, which now
+stored it in its TDB files. Once the driver is installed on the
+client, you can follow the analogous steps by accessing the
+<emphasis>local</emphasis> "Printers" folder too if you are a Samba
+printer admin user. From now on printing should work as expected.
+</para>
+
+<para>
+Samba also includes a service level parameter name <parameter>default
+devmode</parameter> for generating a default Device Mode for a
+printer. Some drivers will function well with Samba's default set of
+properties. Others may crash the client's spooler service. So use this
+parameter with caution. It is always better to have the client
+generate a valid device mode for the printer and store it on the
+server for you.
+</para>
</sect2>
<sect2>
-<title>Setting up printcap and print servers</title>
+<title>Further Client Driver Install Procedures</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.
+Every further driver may be done by any user, along the lines
+described above: Browse network, open printers folder on Samba server,
+right-click printer and choose "Connect...". Once this completes
+(should be not more than a few seconds, but could also take a minute,
+depending on network conditions), you should find the new printer in
+your client workstation local <emphasis>Printers and
+Faxes</emphasis> folder.
</para>
<para>
-Samba requires either a printcap or program to deliver printcap
-information. This printcap information has the format:
+You can also open your local "Printers and Faxes" folder by using this
+command on Windows 2000 and Windows XP Professional workstations:
</para>
<para><programlisting>
- name|alias1|alias2...:option=value:...
+rundll32 shell32.dll,SHHelpShortcuts_RunDLL PrintersFolder
</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.
+or this command on Windows NT 4.0 workstations:
</para>
+<para><programlisting>
+rundll32 shell32.dll,Control_RunDLL MAIN.CPL @2
+</programlisting></para>
+
<para>
-Here are some examples of printcap files:
+You can enter the commands either inside a "DOS box" window or in the
+"Run command..." field from the "Start" menu.
</para>
+</sect2>
-<table frame="all">
- <title>Example printcap files</title>
- <tgroup cols="2" align="left">
- <tbody>
- <row><entry><programlisting>pr</programlisting></entry><entry>just printer name</entry></row>
- <row><entry><programlisting>pr|alias</programlisting></entry><entry>printer name and alias</entry></row>
- <row><entry><programlisting>pr|My Printer</programlisting></entry><entry>printer name, alias used as comment</entry></row>
- <row><entry><programlisting>
-pr:sh:\
- :cm= \
- testing
-</programlisting></entry><entry>Same as pr:sh:cm= testing</entry></row>
- <row><entry><programlisting>
-pr:sh
- :cm= testing
-</programlisting></entry><entry>Same as pr:sh:cm= testing</entry></row>
-</tbody>
-</tgroup>
-</table>
+<sect2>
+<title>Always make first Client Connection as root or "printer admin"</title>
<para>
-Samba reads the printcap information when first started. If you make
-changes in the printcap information, then you must do the following:
+After you installed the driver on the Samba server (in its
+<parameter>[print$]</parameter> share, you should always make sure
+that your first client installation completes correctly. Make it a habit for
+yourself to build that the very first connection from a client as
+"printer admin". This is to make sure that:
</para>
-<orderedlist>
+<itemizedlist>
-<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> a first valid <emphasis>Device Mode</emphasis> is
+really initialized (see above for more explanation details), and
+that</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> the default print settings of your printer for all
+further client installations are as you want them</para></listitem>
+</itemizedlist>
-<listitem><para>
-You now should send a SIGHUP signal to the smbd server to have
-it reread the printcap information.
-</para></listitem>
+<para>
+Do this by changing the orientation to landscape, click
+<emphasis>Apply</emphasis>, and then change it back again. Then modify
+the other settings (for example, you don't want the default media size
+set to <emphasis>Letter</emphasis>, when you are all using
+<emphasis>A4</emphasis>, right? You may want to set the printer for
+<emphasis>duplex</emphasis> as the default; etc.).
+</para>
+
+<para>
+To connect as root to a Samba printer, try this command from a Windows
+2K/XP DOS box command prompt:
+</para>
+
+<para><programlisting>
+runas /netonly /user:root "rundll32 printui.dll,PrintUIEntry /p /t3 /n \\SAMBA-SERVER\printername"
+</programlisting></para>
+
+<para>
+You will be prompted for root's Samba-password; type it, wait a few
+seconds, click on "<emphasis>Printing Defaults...</emphasis>" and
+proceed to set the job options as should be used as defaults by all
+clients. Alternatively, instead of root you can name one other member
+of the<emphasis>printer admins</emphasis> from the
+<filename>smb.conf</filename> setting.
+</para>
+
+<para>
+Now all the other users downloading and installing the driver
+the same way (called <emphasis>Point'n'Print</emphasis>) will
+have the same defaults set for them. If you miss this step you'll
+get a lot of helpdesk calls from your users. But maybe you like to
+talk to people.... ;-)
+</para>
+</sect2>
+</sect1>
+
+<sect1>
+<title>Other Gotchas</title>
+
+<para>
+Your driver is installed. It is ready for
+<emphasis>Point'n'Print</emphasis> installation by the clients
+now. You <emphasis>may</emphasis> have tried to download and use it
+onto your first client machine now. But wait... let's make you
+acquainted first with a few tips and tricks you may find useful. For
+example, suppose you didn't manage to "set the defaults" on the
+printer, as advised in the preceeding paragraphs? And your users
+complain about various issues (such as <quote>We need to set the paper
+size for each job from Letter to A4 and it won't store it!</quote>)
+</para>
+
+<sect2>
+<title>Setting Default Print Options for the Client Drivers</title>
+
+<para>
+The last sentence might be viewed with mixed feelings by some users and
+admins. They have struggled for hours and hours and couldn't arrive at
+a point were their settings seemed to be saved. It is not their
+fault. The confusing thing is this: in the multi-tabbed dialog that pops
+up when you right-click the printer name and select
+<emphasis>Properties...</emphasis>, you can arrive at two identically
+looking dialogs, each claiming that they help you to set printer options,
+in three different ways. Here is the definite answer to the "Samba
+Default Driver Setting FAQ":
+</para>
+
+<formalpara><title><quote>I can't set and save default print options
+for all users on Win2K/XP! Why not?</quote></title>
+
+<para>
+How are you doing it? I bet the wrong way.... (it is not very
+easy to find out, though). There are 3 different ways to bring you to
+a dialog that <emphasis>seems</emphasis> to set everything. All three
+dialogs <emphasis>look</emphasis> the same. Only one of them
+<emphasis>does</emphasis> what you intend.
+<emphasis>Important:</emphasis> you need to be Administrator or Print
+Administrator to do this for all users. Here is how I reproduce it in
+on XP Professional:
+
+<orderedlist numeration="upperalpha">
+
+<listitem><para>The first "wrong" way:
+
+<orderedlist numeration="arabic">
+<listitem><para>Open the <emphasis>Printers</emphasis>
+folder.</para></listitem>
+
+<listitem><para>Right-click on the printer
+(<emphasis>remoteprinter on cupshost</emphasis>) and
+select in context menu <emphasis>Printing
+Preferences...</emphasis></para></listitem>
+
+<listitem><para>Look at this dialog closely and remember what it looks
+like.</para></listitem>
+</orderedlist>
+</para>
+</listitem>
+
+<listitem><para>The second "wrong" way:
+
+<orderedlist numeration="arabic">
+<listitem><para>Open the "<emphasis>Printers</emphasis>"
+folder.</para></listitem>
+
+<listitem><para>Right-click on the printer (<emphasis>remoteprinter on
+cupshost</emphasis>) and select in the context menu
+<emphasis>Properties</emphasis></para></listitem>
+
+<listitem><para>Click on the <emphasis>General</emphasis>
+tab</para></listitem>
+
+<listitem><para>Click on the button <emphasis>Printing
+Preferences...</emphasis></para></listitem>
+
+<listitem><para>A new dialog opens. Keep this dialog open and go back
+to the parent dialog.</para></listitem>
</orderedlist>
+</para>
+</listitem>
+
+<listitem><para>The third, the "correct" way: (should you do
+this from the beginning, just carry out steps 1. and 2. from second
+"way" above)
+
+<orderedlist numeration="arabic">
+<listitem><para>Click on the <emphasis>Advanced</emphasis>
+tab. (Hmmm... if everything is "Grayed Out", then you are not logged
+in as a user with enough privileges).</para></listitem>
+
+<listitem><para>Click on the "<emphasis>Printing
+Defaults...</emphasis>" button.</para></listitem>
+
+<listitem><para>On any of the two new tabs, click on the
+<emphasis>Advanced...</emphasis>
+button.</para></listitem>
+
+<listitem><para>A new dialog opens. Compare this one to the other,
+identical looking one from "B.5" or A.3".</para></listitem>
+</orderedlist>
+</para>
+</listitem>
+</orderedlist>
+
+Do you see any difference in the two settings dialogs? I don't
+either. However, only the last one, which you arrived at with steps
+C.1.-6. will permanently save any settings which will then become the
+defaults for new users. If you want all clients to have the same
+defaults, you need to conduct these steps as administrator
+(<emphasis>printer admin</emphasis> in <filename>smb.conf</filename>)
+<emphasis>before</emphasis> a client downloads the driver (the clients
+can later set their own <emphasis>per-user defaults</emphasis> by
+following the procedures<emphasis>A.</emphasis>
+or<emphasis>B.</emphasis> above...). (This is new: Windows 2000 and
+Windows XP allow <emphasis>per-user</emphasis> default settings and
+the ones the administrator gives them, before they set up their own).
+The "parents" of the identically looking dialogs have a slight
+difference in their window names: one is called
+<computeroutput>Default Print Values for Printer Foo on Server
+Bar"</computeroutput> (which is the one you need) and the other is
+called "<computeroutput>Print Settings for Printer Foo on Server
+Bar</computeroutput>". The last one is the one you arrive at when you
+right-click on the printer and select <emphasis>Print
+Settings...</emphasis>. This is the one what you were
+taught to use back in the days of Windows NT! So it is only natural to
+try the same way with Win2k or WinXP. You wouldn't dream
+that there is now a different "clicking path" to arrive at an
+identically looking, but functionally different dialog to set defaults
+for all users!
+</para></formalpara>
+
+<tip><para>Try (on Win2000 and WinXP) to run this command (as a user
+with the right privileges):
+</para>
+
+<para><programlisting>
+rundll32 printui.dll,PrintUIEntry /p /t3 /n\\SAMBA-SERVER\printersharename
+</programlisting></para>
+
+<para>
+to see the tab with the <emphasis>Printing Defaults...</emphasis>
+button (the one you need). Also run this command:
+</para>
+
+<para><programlisting>
+rundll32 printui.dll,PrintUIEntry /p /t0 /n\\SAMBA-SERVER\printersharename
+</programlisting></para>
+
+<para>
+to see the tab with the <emphasis>Printing Preferences...</emphasis>
+button (the one which doesn't set system-wide defaults). You can
+start the commands from inside a DOS box" or from the <emphasis>Start
+-- Run...</emphasis> menu.
+</para>
+</tip>
</sect2>
<sect2>
-<title>Job sent, no output</title>
+<title>Supporting large Numbers of Printers</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.
+One issue that has arisen during the recent development phase of Samba
+is the need to support driver downloads for 100's of printers. Using
+Windows NT APW here is somewhat awkward (to say the least). If you
+don't want to acquire RSS pains from such the printer installation
+clicking orgy alone, you need to think about a non-interactive script.
</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:
+If more than one printer is using the same driver, the
+<command>rpcclient setdriver</command> command can be used to set the
+driver associated with an installed queue. If the driver is uploaded
+to <parameter>[print$]</parameter> once and registered with the
+printing TDBs, it can be used by multiple print queues. In this case
+you just need to repeat the <command>setprinter</command> subcommand
+of <command>rpcclient</command> for every queue (without the need to
+conduct the <command>adddriver</command> again and again). The
+following is an example of how this could be accomplished:
</para>
-<para><screen>
-<prompt>$ </prompt><userinput>lpc -Pprinter stop</userinput>
-</screen></para>
+<para><programlisting>
+
+ ----------------------------------------------------------------------------------
+ $ rpcclient SAMBA-CUPS -U root%secret -c 'enumdrivers'
+ cmd = enumdrivers
+
+ [Windows NT x86]
+ Printer Driver Info 1:
+ Driver Name: [infotec IS 2075 PCL 6]
+
+ Printer Driver Info 1:
+ Driver Name: [DANKA InfoStream]
+
+ Printer Driver Info 1:
+ Driver Name: [Heidelberg Digimaster 9110 (PS)]
+
+ Printer Driver Info 1:
+ Driver Name: [dm9110]
+
+ Printer Driver Info 1:
+ Driver Name: [myphantasydrivername]
+
+ [....]
+ ----------------------------------------------------------------------------------
+
+----------------------------------------------------------------------------------
+ $ rpcclient SAMBA-CUPS -U root%secret -c 'enumprinters'
+ cmd = enumprinters
+ flags:[0x800000]
+ name:[\\SAMBA-CUPS\dm9110]
+ description:[\\SAMBA-CUPS\dm9110,,110ppm HiVolume DANKA Stuttgart]
+ comment:[110 ppm HiVolume DANKA Stuttgart]
+ [....]
+ ----------------------------------------------------------------------------------
+
+----------------------------------------------------------------------------------
+ $ rpcclient SaMbA-cUpS -U root%secret -c 'setdriver dm9110 "Heidelberg Digimaster 9110 (PS)"'
+ cmd = setdriver dm9110 Heidelberg Digimaster 9110 (PPD)
+ Successfully set dm9110 to driver Heidelberg Digimaster 9110 (PS).
+ ----------------------------------------------------------------------------------
+
+----------------------------------------------------------------------------------
+ $ rpcclient samba-cups -U root%secret -c 'enumprinters'
+ cmd = enumprinters
+ flags:[0x800000]
+ name:[\\SAMBA-CUPS\dm9110]
+ description:[\\SAMBA-CUPS\dm9110,Heidelberg Digimaster 9110 (PS),110ppm HiVolume DANKA Stuttgart]
+ comment:[110ppm HiVolume DANKA Stuttgart]
+ [....]
+ ----------------------------------------------------------------------------------
+
+----------------------------------------------------------------------------------
+ $ rpcclient SaMbA-cUpS -U root%secret -c 'setdriver dm9110 myphantasydrivername'
+ cmd = setdriver dm9110 myphantasydrivername
+ Successfully set dm9110 to myphantasydrivername.
+ ----------------------------------------------------------------------------------
+
+----------------------------------------------------------------------------------
+ $ rpcclient samba-cups -U root%secret -c 'enumprinters'
+ cmd = enumprinters
+ flags:[0x800000]
+ name:[\\SAMBA-CUPS\dm9110]
+ description:[\\SAMBA-CUPS\dm9110,myphantasydrivername,110ppm HiVolume DANKA Stuttgart]
+ comment:[110ppm HiVolume DANKA Stuttgart]
+ [....]
+ ----------------------------------------------------------------------------------
+
+</programlisting></para>
<para>
-Now submit a print job and then use <userinput>lpq -Pprinter</userinput> 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.
+It may be not easy to recognize: but the first call to
+<command>enumprinters</command> showed the "dm9110" printer with an
+empty string where the driver should have been listed (between the 2
+commas in the "description" field). After the
+<command>setdriver</command> command succeeded, all is well. (The
+CUPS Printing chapter has more info about the installation of printer
+drivers with the help of <command>rpccclient</command>).
</para>
+</sect2>
+
+<sect2>
+<title>Adding new Printers with the Windows NT APW</title>
<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:
+By default, Samba exhibits all printer shares defined in
+<emphasis><filename>smb.conf</filename></emphasis> in the
+<emphasis>Printers...</emphasis> folder. Also located in this folder
+is the Windows NT Add Printer Wizard icon. The APW will be shown only
+if:
</para>
-<para><screen>
-<prompt>$ </prompt><userinput>cd /var/spool/lpd/printer # spool directory of print jobs</userinput>
-<prompt>$ </prompt><userinput>ls # find job files</userinput>
-<prompt>$ </prompt><userinput>file dfA001myhost</userinput>
-</screen></para>
+<itemizedlist>
+<listitem><para>...the connected user is able to successfully execute
+an <command>OpenPrinterEx(\\server)</command> with administrative
+privileges (i.e. root or <emphasis>printer admin</emphasis>).
+</para>
+
+<tip><para> Try this from a Windows 2K/XP DOS box command prompt:
+</para>
+
+<para><programlisting>
+runas /netonly /user:root rundll32 printui.dll,PrintUIEntry /p /t0 /n \\SAMBA-SERVER\printersharename
+</programlisting></para>
+
+<para>
+and click on <emphasis>Printing Preferences...</emphasis>
+</para></tip></listitem>
+
+<listitem><para>...<filename>smb.conf</filename> contains the setting
+<emphasis>show add printer wizard = yes</emphasis> (the
+default).</para></listitem>
+</itemizedlist>
<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.
+The APW can do various things:
</para>
+<itemizedlist>
+<listitem><para>upload a new driver to the Samba
+<parameter>[print$]</parameter> share;</para></listitem>
+
+<listitem><para>associate an uploaded driver with an existing (but
+still "driverless") print queue;</para></listitem>
+
+<listitem><para>exchange the currently used driver for an existing
+print queue with one that has been uploaded before;</para></listitem>
+
+<listitem><para>add an entirely new printer to the Samba host (only in
+conjunction with a working <parameter>add printer command</parameter>;
+a corresponding <parameter>delete printer command</parameter> for
+removing entries from the <emphasis>Printers...</emphasis> folder
+may be provided too)</para></listitem>
+</itemizedlist>
+
+<para>
+The last one (add a new printer) requires more effort than the
+previous ones. In order to use the APW to successfully add a printer
+to a Samba server, the <parameter>add printer command</parameter> must
+have a defined value. The program hook must successfully add the
+printer to the Unix print system (i.e. to
+<filename>/etc/printcap</filename>,
+<filename>/etc/cups/printers.conf</filename> or other appropriate
+files) and to <filename>smb.conf</filename> if necessary.
+</para>
+
+<para>
+When using the APW from a client, if the named printer share does not
+exist, smbd 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 <computeroutput>Access Denied</computeroutput> is
+returned to the client. Note that the <parameter>add printer
+command</parameter> is executed under the context of the connected
+user, not necessarily a root account. A <parameter>map to guest = bad
+user</parameter> may have connected you unwittingly under the wrong
+privilege; you should check it by using the
+<command>smbstatus</command> command.
+</para>
</sect2>
<sect2>
-<title>Job sent, strange output</title>
+<title>Weird Error Message <computeroutput>Cannot connect under a
+different Name</computeroutput></title>
<para>
-Once you have the job printing, you can then start worrying about
-making it print nicely.
+Once you are connected with the wrong credentials, there is no means
+to reverse the situation other than to close all Explorer windows, and
+perhaps reboot.
</para>
+<itemizedlist>
+<listitem><para>The <command>net use \\SAMBA-SERVER\sharename
+/user:root</command> gives you an error message: <computeroutput>Multiple
+connections to a server or a shared resource by the same user
+utilizing the several user names are not allowed. Disconnect all
+previous connections to the server, resp. the shared resource, and try
+again.</computeroutput></para></listitem>
+
+<listitem><para>Every attempt to "connect a network drive" to
+<filename>\\SAMBASERVER\\print$</filename> to z: is countered by the
+pertinacious message. <computeroutput>This network folder is currently
+connected under different credentials (username and password).
+Disconnect first any existing connection to this network share in
+order to connect again under a different username and
+password</computeroutput>.</para></listitem>
+</itemizedlist>
+
<para>
-The most common problem is extra pages of output: banner pages
-OR blank pages at the end.
+So you close all connections. You try again. You get the same
+message. You check from the Samba side, using
+<command>smbstatus</command>. Yes, there are some more
+connections. You kill them all. The client still gives you the same
+error message. You watch the smbd.log file on a very high debug level
+and try re-connect. Same error message, but not a single line in the
+log. You start to wonder if there was a connection attempt at all. You
+run ethereal and tcpdump while you try to connect. Result: not a
+single byte goes on the wire. Windows still gives the error
+message. You close all Explorer Windows and start it again. You try to
+connect - and this times it works! Windows seems to cache connection
+info somewhere and doesn't keep it up to date (if you are unlucky you
+might need to reboot to get rid of the error message).
</para>
+</sect2>
+
+<sect2>
+<title>Be careful when assembling Driver Files</title>
<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.
+You need to be very careful when you take notes about the files and
+belonging to a particular driver. Don't confuse the files for driver
+version "0" (for Win95/98/ME, going into
+<filename>[print$]/WIN/0/</filename>), driver version "2" (Kernel Mode
+driver for WinNT, going into <filename>[print$]/W32X86/2/</filename>
+<emphasis>may</emphasis> be used on Win2K/XP too), and driver version
+"3" (non-Kernel Mode driver going into
+<filename>[print$]/W32X86/3/</filename> <emphasis>can not</emphasis>
+be used on WinNT). Very often these different driver versions contain
+files carrying the same name; but still the files are very different!
+Also, if you look at them from the Windows Explorer (they reside in
+"<filename>%WINDOWS%\system32\spool\drivers\W32X86\</filename>") you
+will probably see names in capital letters, while an "enumdrivers"
+command from Samba would show mixed or lower case letters. So it is
+easy to confuse them. If you install them manually using
+<command>rpcclient</command> and subcommands, you may even succeed
+without an error message. Only later, when you try install on a
+client, you will encounter error messages like <computeroutput>This
+server has no appropriate driver for the printer</computeroutput>.
+</para>
+
+<para>
+Here is an example. You are invited to look very closely at the
+various files, compare their names and their spelling, and discover
+the differences in the composition of the version-2 and -3 sets
+Note: the version-0 set contained 40 (!)
+<parameter>Dependentfiles</parameter>, so I left it out for space
+reasons:
</para>
<para><programlisting>
- printer: ... :sh
+
+ kde4@kde-bitshop:# rpcclient -U 'Administrator%xxxx' -c 'enumdrivers 3' 10.160.50.8
+
+ Printer Driver Info 3:
+ Version: [3]
+ Driver Name: [Canon iR8500 PS3]
+ Architecture: [Windows NT x86]
+ Driver Path: [\\10.160.50.8\print$\W32X86\3\cns3g.dll]
+ Datafile: [\\10.160.50.8\print$\W32X86\3\iR8500sg.xpd]
+ Configfile: [\\10.160.50.8\print$\W32X86\3\cns3gui.dll]
+ Helpfile: [\\10.160.50.8\print$\W32X86\3\cns3g.hlp]
+
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\3\aucplmNT.dll]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\3\ucs32p.dll]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\3\tnl32.dll]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\3\aussdrv.dll]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cnspdc.dll]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\3\aussapi.dat]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cns3407.dll]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\3\CnS3G.cnt]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\3\NBAPI.DLL]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\3\NBIPC.DLL]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cpcview.exe]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cpcdspl.exe]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cpcedit.dll]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cpcqm.exe]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cpcspl.dll]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cfine32.dll]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cpcr407.dll]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\3\Cpcqm407.hlp]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cpcqm407.cnt]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\3\cns3ggr.dll]
+
+ Monitorname: []
+ Defaultdatatype: []
+
+ Printer Driver Info 3:
+ Version: [2]
+ Driver Name: [Canon iR5000-6000 PS3]
+ Architecture: [Windows NT x86]
+ Driver Path: [\\10.160.50.8\print$\W32X86\2\cns3g.dll]
+ Datafile: [\\10.160.50.8\print$\W32X86\2\IR5000sg.xpd]
+ Configfile: [\\10.160.50.8\print$\W32X86\2\cns3gui.dll]
+ Helpfile: [\\10.160.50.8\print$\W32X86\2\cns3g.hlp]
+
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\2\AUCPLMNT.DLL]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\2\aussdrv.dll]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\2\cnspdc.dll]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\2\aussapi.dat]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\2\cns3407.dll]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\2\CnS3G.cnt]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\2\NBAPI.DLL]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\2\NBIPC.DLL]
+ Dependentfiles: [\\10.160.50.8\print$\W32X86\2\cns3gum.dll]
+
+ Monitorname: [CPCA Language Monitor2]
+ Defaultdatatype: []
+
</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.
+If we write the "version 2" files and the "version 3" files
+into different text files and compare the result, we see this
+picture:
</para>
+<para><programlisting>
+<![CDATA[
+ kde4@kde-bitshop:# sdiff 2-files 3-files
+
+ cns3g.dll cns3g.dll
+ iR8500sg.xpd iR8500sg.xpd
+ cns3gui.dll cns3gui.dll
+ cns3g.hlp cns3g.hlp
+ AUCPLMNT.DLL | aucplmNT.dll
+ > ucs32p.dll
+ > tnl32.dll
+ aussdrv.dll aussdrv.dll
+ cnspdc.dll cnspdc.dll
+ aussapi.dat aussapi.dat
+ cns3407.dll cns3407.dll
+ CnS3G.cnt CnS3G.cnt
+ NBAPI.DLL NBAPI.DLL
+ NBIPC.DLL NBIPC.DLL
+ cns3gum.dll | cpcview.exe
+ > cpcdspl.exe
+ > cpcqm.exe
+ > cpcspl.dll
+ > cfine32.dll
+ > cpcr407.dll
+ > Cpcqm407.hlp
+ > cpcqm407.cnt
+ > cns3ggr.dll
+]]>
+
+
+</programlisting></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:
+Don't be fooled though! Driver files for each version with identical
+names may be different in their content, as you can see from this size
+comparison:
</para>
<para><programlisting>
- Printers|Printer Name|(Right Click)Properties|Postscript|Advanced|
+
+ kde4@kde-bitshop:# for i in cns3g.hlp cns3gui.dll cns3g.dll; do \
+ smbclient //10.160.50.8/print\$ -U 'Administrator%xxxx' \
+ -c "cd W32X86/3; dir $i; cd .. ; cd 2; dir $i"; \
+ done
+
+ CNS3G.HLP A 122981 Thu May 30 02:31:00 2002
+ CNS3G.HLP A 99948 Thu May 30 02:31:00 2002
+
+ CNS3GUI.DLL A 1805824 Thu May 30 02:31:00 2002
+ CNS3GUI.DLL A 1785344 Thu May 30 02:31:00 2002
+
+ CNS3G.DLL A 1145088 Thu May 30 02:31:00 2002
+ CNS3G.DLL A 15872 Thu May 30 02:31:00 2002
+
</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.
+In my example were even more differences than shown here. Conclusion:
+you must be very careful to select the correct driver files for each
+driver version. Don't rely on the names alone. Don't interchange files
+belonging to different driver versions.
+</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 <filename>LPT1:</filename>,
+<filename>COM1:</filename>, <filename>FILE:</filename>, 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 need such a "port" in order to print;
+it rather is a requirement of Windows clients. They insist on being
+told about an available port when they request this info, otherwise
+they throw an error message at you. So Samba fakes the port
+information to keep the Windows clients happy.
+</para>
+
+<para>
+Note that Samba does not support the concept of "Printer Pooling"
+internally either. Printer Pooling assigns a logical printer 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 or
+another (<quote>My users and my Boss should not know that they are
+working with Samba</quote>), <filename>smb.conf</filename> possesses a
+<parameter>enumports command</parameter> which can be used to define
+an external program that generates a listing of ports on a system.
+</para>
</sect2>
<sect2>
-<title>Raw PostScript printed</title>
+<title>Avoiding the most common Misconfigurations of the Client Driver</title>
+
+<para>
+So - printing works, but there are still problems. Most jobs print
+well, some don't print at all. Some jobs have problems with fonts,
+which don't look good at all. Some jobs print fast, and some are
+dead-slow. We can't cover it all; but we want to encourage you to read
+the little paragraph about "Avoiding the wrong PostScript Driver
+Settings" in the CUPS Printing part of this document.
+</para>
+</sect2>
+</sect1>
+
+<sect1>
+<title>The Imprints Toolset</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.
+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>
+<formalpara><title>ATTENTION! MAINTAINER REQUIRED</title>
+
+<para>
+Unfortunately, the Imprints toolset is no longer maintained. As of
+December, 2000, the project is in need of a new maintainer. The most
+important skill to have is decent perl coding and an interest in
+MS-RPC based printing using Samba. If you wish to volunteer, please
+coordinate your efforts on the samba-technical mailing list. The
+toolset is still in usable form; but only for a series of older
+printer models, where there are prepared packages to use. Packages for
+more up to date print devices are needed if Imprints should have a
+future.</para></formalpara>
+
+<sect2>
+<title>What is Imprints?</title>
+
+<para>
+Imprints is a collection of tools for supporting these goals:
+</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
+printer drivers from a central internet (or intranet) Imprints Server
+repository and install them on remote Samba and Windows NT4 print
+servers.</para></listitem>
+</itemizedlist>
</sect2>
<sect2>
-<title>Advanced Printing</title>
+<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 strongly recommended that this security check
+<emphasis>not</emphasis> 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 smbclient and rpcclient
+</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. An 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><programlisting>
+ HKLM\System\CurrentControlSet\Control\Print\Environment
+</programlisting></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>
+
+<sect1>
+<title>Add Network Printers at Logon without User Interaction</title>
+
+<para>
+The following MS Knowledge Base article may be of some help if you
+need to handle Windows 2000 clients: <emphasis>How to Add Printers
+with No User Interaction in Windows 2000.</emphasis> ( <ulink
+url="http://support.microsoft.com/default.aspx?scid=kb;en-us;189105">http://support.microsoft.com/default.aspx?scid=kb;en-us;189105</ulink>
+). It also applies to Windows XP Professional clients.
+</para>
+
+<para>
+The ideas sketched out below are inspired by this article. It
+describes a commandline method which can be applied to install
+network and local printers and their drivers. This is most useful
+if integrated in Logon Scripts. You can see what options are
+available by typing in a command prompt ("DOS box") this:
+</para>
+
+<para><programlisting>
+ rundll32 printui.dll,PrintUIEntry /?
+</programlisting></para>
+
+<para>
+A window pops up which shows you all of the commandline switches
+available. An extensive list of examples is also provided. This is
+only for Win 2k/XP. It doesn't work on WinNT. WinNT has probably some
+other tools in the respective Resource Kit. Here is a suggestion about
+what a client logon script might contain, with a short explanation of
+what the lines actually do (it works if 2k/XP Windows clients access
+printers via Samba, but works for Windows-based print servers too):
+</para>
+
+<para><programlisting>
+ rundll32 printui.dll,PrintUIEntry /dn /n "\\sambacupsserver\infotec2105-IPDS" /q
+ rundll32 printui.dll,PrintUIEntry /in /n "\\sambacupsserver\infotec2105-PS"
+ rundll32 printui.dll,PrintUIEntry /y /n "\\sambacupsserver\infotec2105-PS"
+</programlisting></para>
+
+<para>
+Here is a list of the used commandline parameters:
+</para>
+
+<variablelist>
+<varlistentry><term>/dn</term>
+<listitem><para>deletes a network printer</para></listitem>
+</varlistentry>
+<varlistentry><term>/q</term>
+<listitem><para>quiet modus</para></listitem>
+</varlistentry>
+<varlistentry><term>/n</term>
+<listitem><para>names a printer</para></listitem>
+</varlistentry>
+<varlistentry><term>/in</term>
+<listitem><para>adds a network printer connection</para></listitem>
+</varlistentry>
+<varlistentry><term>/y</term>
+<listitem><para>sets printer as default printer</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>
+I have tested this with a Samba 2.2.7a and a Samba 3.0alpha24
+installation and Windows XP Professional clients. Note that this
+specific command set works with network print queues (installing
+local print queues requires different parameters, but this is of no
+interest here).
+</para>
+
+<itemizedlist>
+<listitem><para>Line 1 deletes a possibly existing previous network
+printer <emphasis>infotec2105-IPDS</emphasis> (which had used native
+Windows drivers with LPRng that were removed from the server which was
+converted to CUPS). The <command>/q</command> at the end eliminates
+"Confirm" or error dialog boxes popping up. They should not be
+presented to the user logging on.</para></listitem>
+
+<listitem><para>Line 2 adds the new printer
+<emphasis>infotec2105-PS</emphasis> (which actually is same physical
+device but is now run by the new CUPS printing system and associated
+with the CUPS/Adobe PS drivers). The printer and its driver
+<emphasis>must</emphasis> have been added to Samba prior to the user
+logging in (e.g. by a procedure as discussed earlier in this chapter,
+or by running <command>cupsaddsmb</command>). The driver is now
+auto-downloaded to the client PC where the user is about to log
+in.</para></listitem>
+
+<listitem><para>Line 3 sets the default printer to this new network
+printer (there might be several other printers installed with this
+same method and some may be local as well -- so we deside for a
+default printer). The default printer selection may of course be
+different for different users.</para></listitem>
+</itemizedlist>
+
+<para>
+Note that the second line only works if the printer
+<emphasis>infotec2105-PS</emphasis> has an already working printqueue
+on "sambacupsserver", and if the printer drivers have sucessfully been
+uploaded (via <command>APW</command> ,
+<command>smbclient/rpcclient</command> or
+<command>cupsaddsmb</command>) into the
+<parameter>[print$]</parameter> driver repository of Samba. Also, some
+Samba versions prior to version 3.0 required a re-start of smbd after
+the printer install and the driver upload, otherwise the script (or
+any other client driver download) would fail.
+</para>
<para>
-Note that you can do some pretty magic things by using your
-imagination with the <parameter>print command</parameter> 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.
+Since there no easy way to test for the existence of an installed
+network printer from the logon script, the suggestion is: don't bother
+checking and just allow the deinstallation/reinstallation to occur
+every time a user logs in; it's really quick anyway (1 to 2 seconds).
</para>
+<para>
+The additional benefits for this are:
+</para>
+
+<itemizedlist>
+<listitem><para>It puts in place any printer default setup changes
+automatically at every user logon.</para></listitem>
+
+<listitem><para>It allows for "roaming" users' login into the domain from
+different workstations.</para></listitem>
+</itemizedlist>
+
+<para>
+Since network printers are installed per user this much simplifies the
+process of keeping the installation up-to-date. The extra few seconds
+at logon time will not really be noticeable. Printers can be centrally
+added, changed, and deleted at will on the server with no user
+intervention required on the clients (you just need to keep the logon
+scripts up to date).
+</para>
+</sect1>
+
+<sect1>
+<title>The <command>addprinter</command> command</title>
+
+<para>
+The <command>addprinter</command> command can be configured to be a
+shell script or program executed by Samba. It is triggered by running
+the APW from a client against the Samba print server. The APW asks the
+user to fill in several fields (such as printer name, driver to be
+used, comment, port monitor, etc.). These parameters are passed on to
+Samba by the APW. If the addprinter command is designed in a way that
+it can create a new printer (through writing correct printcap entries
+on legacy systems, or execute the <command>lpadmin</command> command
+on more modern systems) and create the associated share in
+<filename>smb.conf</filename>, then the APW will in effect really
+create a new printer on Samba and the UNIX print subsystem!
+</para>
+</sect1>
+
+<sect1>
+<title>Migration of "Classical" printing to Samba 3.0</title>
+
+<para>
+The basic "NT-style" printer driver management has not changed
+considerably in 3.0 over the 2.2.x releases (apart from many small
+improvements). Here migration should be quite easy, especially if you
+followed previous advice to stop using deprecated parameters in your
+setup. For migrations from an existing 2.0.x setup, or if you
+continued "Win9x-style" printing in your Samba 2.2 installations, it
+is more of an effort. Please read the appropriate release notes and
+the HOWTO Collection for 2.2. You can follow several paths. Here are
+possible scenarios for migration:
+</para>
+
+<itemizedlist>
+<listitem><para>You need to study and apply the new Windows NT printer
+and driver support. Previously used parameters "<parameter>printer
+driver file</parameter>", " <parameter>printer driver</parameter>" and
+"<parameter>printer driver location</parameter>" are no longer
+supported.</para></listitem>
+
+<listitem><para>If you want to take advantage of WinNT printer driver
+support you also need to migrate theWin9x/ME drivers to the new
+setup.</para></listitem>
+
+<listitem><para>An existing <filename>printers.def</filename> file
+(the one specified in the now removed parameter <parameter>printer
+driver file = ...</parameter>) will work no longer with Samba-3.0. In
+3.0, smbd attempts to locate a Win9x/ME driver files for the printer
+in <parameter>[print$]</parameter> and additional settings in the TDB
+and only there; if it fails it will <emphasis>not</emphasis> (as 2.2.x
+used to do) drop down to using a <filename>printers.def</filename>
+(and all associated parameters). The make_printerdef tool is removed
+and there is no backwards compatibility for this.</para></listitem>
+
+<listitem><para>You need to install a Windows 9x driver into the
+<parameter>[print$]</parameter> share for a printer on your Samba
+host. The driver files will be stored in the "WIN40/0" subdirectory of
+<parameter>[print$]</parameter>, and some other settings and info go
+into the printing-related TDBs.</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 smbclient and
+rpcclient. See the Imprints installation client at:
+</para>
+
+<para>
+<ulink url="http://imprints.sourceforge.net/"><emphasis>http://imprints.sourceforge.net/</emphasis></ulink>
+</para>
+
+<para>
+for an example. See also the discussion of rpcclient usage in the
+"CUPS Printing" section.</para></listitem>
+</itemizedlist>
+</sect1>
+
+<sect1>
+<title>Publishing Printer Information in Active Directory or LDAP</title>
+
+<para>
+We will publish an update to this section shortly.
+</para>
+</sect1>
+
+<sect1>
+<title>Common Errors and Problems</title>
+
+<para>
+Here are a few typical errors and problems people have
+encountered. You can avoid them. Read on.
+</para>
+
+<sect2>
+<title>I give my root password but I don't get access</title>
+
+<para>
+Don't confuse the root password which is valid for the Unix system
+(and in most cases stored in the form of a one-way hash in a file
+named <filename>/etc/shadow</filename>) with the password used to
+authenticate against Samba!. Samba doesn't know the UNIX password; for
+root to access Samba resources via Samba-type access, a Samba account
+for root must be created first. This is often done with the
+<command>smbpasswd</command> command.
+</para>
</sect2>
+<sect2>
+<title>My printjobs get spooled into the spooling directory, but then get lost</title>
+
+<para>
+Don't use the existing Unix print system spool directory for the Samba
+spool directory. It may seem convenient and a saving of space, but it
+only leads to problems. The two <emphasis>must</emphasis> be separate.
+</para>
+
+</sect2>
</sect1>
</chapter>