diff options
Diffstat (limited to 'docs/docbook/projdoc/printer_driver2.sgml')
| -rw-r--r-- | docs/docbook/projdoc/printer_driver2.sgml | 689 |
1 files changed, 689 insertions, 0 deletions
diff --git a/docs/docbook/projdoc/printer_driver2.sgml b/docs/docbook/projdoc/printer_driver2.sgml new file mode 100644 index 0000000000..84a24bcdef --- /dev/null +++ b/docs/docbook/projdoc/printer_driver2.sgml @@ -0,0 +1,689 @@ +<chapter id="printing"> + + +<chapterinfo> + <author> + <firstname>Gerald (Jerry)</firstname><surname>Carter</surname> + <affiliation> + <orgname>Samba Team</orgname> + <address> + <email>jerry@samba.org</email> + </address> + </affiliation> + </author> + + + <pubdate> (3 May 2001) </pubdate> +</chapterinfo> + +<title>Printing Support in Samba 2.2.x</title> + +<sect1> +<title>Introduction</title> + +<para>Beginning with the 2.2.0 release, Samba supports +the native Windows NT printing mechanisms implemented via +MS-RPC (i.e. the SPOOLSS named pipe). Previous versions of +Samba only supported LanMan printing calls.</para> + +<para>The additional functionality provided by the new +SPOOLSS support includes:</para> + +<itemizedlist> + <listitem><para>Support for downloading printer driver + files to Windows 95/98/NT/2000 clients upon demand. + </para></listitem> + + <listitem><para>Uploading of printer drivers via the + Windows NT Add Printer Wizard (APW) or the + Imprints tool set (refer to <ulink + url="http://imprints.sourceforge.net">http://imprints.sourceforge.net</ulink>). + </para></listitem> + + <listitem><para>Support for the native MS-RPC printing + calls such as StartDocPrinter, EnumJobs(), etc... (See + the MSDN documentation at <ulink + url="http://msdn.microsoft.com/">http://msdn.microsoft.com/</ulink> + for more information on the Win32 printing API) + </para></listitem> + + <listitem><para>Support for NT Access Control Lists (ACL) + on printer objects</para></listitem> + + <listitem><para>Improved support for printer queue manipulation + through the use of an internal databases for spooled job + information</para></listitem> +</itemizedlist> + +<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. A bug 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 is fixed in Samba 2.2.1 and once again, Windows NT/2000 clients +can use the local APW for installing drivers to be used with a Samba +served printer. This is the same behavior exhibited by Windows 9x clients. +As a side note, Samba does not use these drivers in any way to process +spooled files. They are utilized entirely by the clients. +</para> + +<para> +The following MS KB article, may be of some help if you are dealing with +Windows 2000 clients: <emphasis>How to Add Printers with No User +Interaction in Windows 2000</emphasis> +</para> + +<para> +<ulink url="http://support.microsoft.com/support/kb/articles/Q189/1/05.ASP">http://support.microsoft.com/support/kb/articles/Q189/1/05.ASP</ulink> +</para> + +</sect1> + + +<sect1> +<title>Configuration</title> + +<warning> +<title>[print$] vs. [printer$]</title> + +<para> +Previous versions of Samba recommended using a share named [printer$]. +This name was taken from the printer$ service created by Windows 9x +clients when a printer was shared. Windows 9x printer servers always have +a printer$ service which provides read-only access via no +password in order to support printer driver downloads. +</para> + +<para> +However, the initial implementation allowed for a +parameter named <parameter>printer driver location</parameter> +to be used on a per share basis to specify the location of +the driver files associated with that printer. Another +parameter named <parameter>printer driver</parameter> provided +a means of defining the printer driver name to be sent to +the client. +</para> + +<para> +These parameters, including <parameter>printer driver +file</parameter> parameter, are being depreciated and should not +be used in new installations. For more information on this change, +you should refer to the <link linkend="MIGRATION">Migration section</link> +of this document. +</para> +</warning> + +<sect2> +<title>Creating [print$]</title> + +<para> +In order to support the uploading of printer driver +files, you must first configure a file share named [print$]. +The name of this share is hard coded in Samba's internals so +the name is very important (print$ is the service used by +Windows NT print servers to provide support for printer driver +download). +</para> + +<para>You should modify the server's smb.conf file to add the global +parameters and to create the +following file share (of course, some of the parameter values, +such as 'path' are arbitrary and should be replaced with +appropriate values for your site):</para> + +<para><programlisting> +[global] + ; members of the ntadmin group should be able + ; to add drivers and set printer properties + ; root is implicitly a 'printer admin' + printer admin = @ntadmin + +[print$] + path = /usr/local/samba/printers + guest ok = yes + browseable = yes + read only = yes + ; since this share is configured as read only, then we need + ; a 'write list'. Check the file system permissions to make + ; sure this account can copy files to the share. If this + ; is setup to a non-root account, then it should also exist + ; as a 'printer admin' + write list = @ntadmin,root +</programlisting></para> + +<para>The <ulink url="smb.conf.5.html#WRITELIST"><parameter> +write list</parameter></ulink> is used to allow administrative +level user accounts to have write access in order to update files +on the share. See the <ulink url="smb.conf.5.html">smb.conf(5) +man page</ulink> for more information on configuring file shares.</para> + +<para>The requirement for <ulink url="smb.conf.5.html#GUESTOK"><command>guest +ok = yes</command></ulink> depends upon how your +site is configured. If users will be guaranteed to have +an account on the Samba host, then this is a non-issue.</para> + +<note> +<title>Author's Note</title> + +<para> +The non-issue is that if all your Windows NT users are guaranteed to be +authenticated by the Samba server (such as a domain member server and the NT +user has already been validated by the Domain Controller in +order to logon to the Windows NT console), then guest access +is not necessary. Of course, in a workgroup environment where +you just want to be able to print without worrying about +silly accounts and security, then configure the share for +guest access. You'll probably want to add <ulink +url="smb.conf.5.html#MAPTOGUEST"><command>map to guest = Bad User +</command></ulink> in the [global] section as well. Make sure +you understand what this parameter does before using it +though. --jerry +</para> +</note> + +<para>In order for a Windows NT print server to support +the downloading of driver files by multiple client architectures, +it must create subdirectories within the [print$] service +which correspond to each of the supported client architectures. +Samba follows this model as well.</para> + +<para>Next create the directory tree below the [print$] share +for each architecture you wish to support.</para> + +<para><programlisting> +[print$]----- + |-W32X86 ; "Windows NT x86" + |-WIN40 ; "Windows 95/98" + |-W32ALPHA ; "Windows NT Alpha_AXP" + |-W32MIPS ; "Windows NT R4000" + |-W32PPC ; "Windows NT PowerPC" +</programlisting></para> + +<warning> +<title>ATTENTION! REQUIRED PERMISSIONS</title> + +<para> +In order to currently add a new driver to you Samba host, +one of two conditions must hold true: +</para> + +<itemizedlist> + <listitem><para>The account used to connect to the Samba host + must have a uid of 0 (i.e. a root account)</para></listitem> + + <listitem><para>The account used to connect to the Samba host + must be a member of the <ulink + url="smb.conf.5.html#PRINTERADMIN"><parameter>printer + admin</parameter></ulink> list.</para></listitem> +</itemizedlist> + +<para> +Of course, the connected account must still possess access +to add files to the subdirectories beneath [print$]. Remember +that all file shares are set to 'read only' by default. +</para> +</warning> + + +<para> +Once you have created the required [print$] service and +associated subdirectories, simply log onto the Samba server using +a root (or <parameter>printer admin</parameter>) account +from a Windows NT 4.0/2k client. Open "Network Neighbourhood" or +"My Network Places" and browse for the Samba host. Once you have located +the server, navigate to the "Printers..." folder. +You should see an initial listing of printers +that matches the printer shares defined on your Samba host. +</para> +</sect2> + +<sect2> +<title>Setting Drivers for Existing Printers</title> + +<para>The initial listing of printers in the Samba host's +Printers folder will have no real printer driver assigned +to them. By default, in Samba 2.2.0 this driver name was set to +<emphasis>NO PRINTER DRIVER AVAILABLE FOR THIS PRINTER</emphasis>. +Later versions changed this to a NULL string to allow the use +tof the local Add Printer Wizard on NT/2000 clients. +Attempting to view the printer properties for a printer +which has this default driver assigned will result in +the error message:</para> + +<para> +<emphasis>Device settings cannot be displayed. The driver +for the specified printer is not installed, only spooler +properties will be displayed. Do you want to install the +driver now?</emphasis> +</para> + +<para> +Click "No" in the error dialog and you will be presented with +the printer properties window. The way assign a driver to a +printer is to either +</para> + +<itemizedlist> + <listitem><para>Use the "New Driver..." button to install + a new printer driver, or</para></listitem> + + <listitem><para>Select a driver from the popup list of + installed drivers. Initially this list will be empty.</para> + </listitem> +</itemizedlist> + +<para>If you wish to install printer drivers for client +operating systems other than "Windows NT x86", you will need +to use the "Sharing" tab of the printer properties dialog.</para> + +<para>Assuming you have connected with a root account, you +will also be able modify other printer properties such as +ACLs and device settings using this dialog box.</para> + +<para>A few closing comments for this section, it is possible +on a Windows NT print server to have printers +listed in the Printers folder which are not shared. Samba does +not make this distinction. By definition, the only printers of +which Samba is aware are those which are specified as shares in +<filename>smb.conf</filename>.</para> + +<para>Another interesting side note is that Windows NT clients do +not use the SMB printer share, but rather can print directly +to any printer on another Windows NT host using MS-RPC. This +of course assumes that the printing client has the necessary +privileges on the remote host serving the printer. The default +permissions assigned by Windows NT to a printer gives the "Print" +permissions to the "Everyone" well-known group. +</para> + +</sect2> + + +<sect2> +<title>Support a large number of printers</title> + +<para>One issue that has arisen during the development +phase of Samba 2.2 is the need to support driver downloads for +100's of printers. Using the Windows NT APW is somewhat +awkward to say the list. If more than one printer are using the +same driver, the <ulink url="rpcclient.1.html"><command>rpcclient's +setdriver command</command></ulink> can be used to set the driver +associated with an installed driver. The following is example +of how this could be accomplished:</para> + +<para><programlisting> +<prompt>$ </prompt>rpcclient pogo -U root%secret -c "enumdrivers" +Domain=[NARNIA] OS=[Unix] Server=[Samba 2.2.0-alpha3] + +[Windows NT x86] +Printer Driver Info 1: + Driver Name: [HP LaserJet 4000 Series PS] + +Printer Driver Info 1: + Driver Name: [HP LaserJet 2100 Series PS] + +Printer Driver Info 1: + Driver Name: [HP LaserJet 4Si/4SiMX PS] + +<prompt>$ </prompt>rpcclient pogo -U root%secret -c "enumprinters" +Domain=[NARNIA] OS=[Unix] Server=[Samba 2.2.0-alpha3] + flags:[0x800000] + name:[\\POGO\hp-print] + description:[POGO\\POGO\hp-print,NO DRIVER AVAILABLE FOR THIS PRINTER,] + comment:[] + +<prompt>$ </prompt>rpcclient pogo -U root%secret \ +<prompt>> </prompt> -c "setdriver hp-print \"HP LaserJet 4000 Series PS\"" +Domain=[NARNIA] OS=[Unix] Server=[Samba 2.2.0-alpha3] +Successfully set hp-print to driver HP LaserJet 4000 Series PS. +</programlisting></para> +</sect2> + + + +<sect2> +<title>Adding New Printers via the Windows NT APW</title> + +<para> +By default, Samba offers all printer shares defined in <filename>smb.conf</filename> +in the "Printers..." folder. Also existing in this folder is the Windows NT +Add Printer Wizard icon. The APW will be show only if +</para> + +<itemizedlist> + <listitem><para>The connected user is able to successfully + execute an OpenPrinterEx(\\server) with administrative + privileges (i.e. root or <parameter>printer admin</parameter>). + </para></listitem> + + <listitem><para><ulink url="smb.conf.5.html#SHOWADDPRINTERWIZARD"><parameter>show + add printer wizard = yes</parameter></ulink> (the default). + </para></listitem> +</itemizedlist> + +<para> +In order to be able to use the APW to successfully add a printer to a Samba +server, the <ulink url="smb.conf.5.html#ADDPRINTERCOMMAND"><parameter>add +printer command</parameter></ulink> must have a defined value. The program +hook must successfully add the printer to the system (i.e. +<filename>/etc/printcap</filename> or appropriate files) and +<filename>smb.conf</filename> if necessary. +</para> + +<para> +When using the APW from a client, if the named printer share does +not exist, <command>smbd</command> will execute the <parameter>add printer +command</parameter> and reparse to the <filename>smb.conf</filename> +to attempt to locate the new printer share. If the share is still not defined, +an error of "Access Denied" is returned to the client. Note that the +<parameter>add printer program</parameter> is executed under the context +of the connected user, not necessarily a root account. +</para> + +<para> +There is a complementing <ulink url="smb.conf.5.html#DELETEPRINTERCOMMAND"><parameter>delete +printer command</parameter></ulink> for removing entries from the "Printers..." +folder. +</para> + +</sect2> + + +<sect2> +<title>Samba and Printer Ports</title> + +<para> +Windows NT/2000 print servers associate a port with each printer. These normally +take the form of LPT1:, COM1:, FILE:, etc... Samba must also support the +concept of ports associated with a printer. By default, only one printer port, +named "Samba Printer Port", exists on a system. Samba does not really a port in +order to print, rather it is a requirement of Windows clients. +</para> + +<para> +Note that Samba does not support the concept of "Printer Pooling" internally +either. This is when a logical printer is assigned to multiple ports as +a form of load balancing or fail over. +</para> + +<para> +If you require that multiple ports be defined for some reason, +<filename>smb.conf</filename> possesses a <ulink +url="smb.conf.5.html#ENUMPORTSCOMMAND"><parameter>enumports +command</parameter></ulink> which can be used to define an external program +that generates a listing of ports on a system. +</para> + +</sect2> + +</sect1> + + +<sect1> + <title>The Imprints Toolset</title> + + <para>The Imprints tool set provides a UNIX equivalent of the + Windows NT Add Printer Wizard. For complete information, please + refer to the Imprints web site at <ulink url="http://imprints.sourceforge.net/"> + http://imprints.sourceforge.net/</ulink> as well as the documentation + included with the imprints source distribution. This section will + only provide a brief introduction to the features of Imprints.</para> + + + <sect2> + <title>What is Imprints?</title> + + <para>Imprints is a collection of tools for supporting the goals + of</para> + + <itemizedlist> + <listitem><para>Providing a central repository information + regarding Windows NT and 95/98 printer driver packages</para> + </listitem> + + <listitem><para>Providing the tools necessary for creating + the Imprints printer driver packages.</para></listitem> + + <listitem><para>Providing an installation client which + will obtain and install printer drivers on remote Samba + and Windows NT 4 print servers.</para></listitem> + </itemizedlist> + + </sect2> + + + <sect2> + <title>Creating Printer Driver Packages</title> + + <para>The process of creating printer driver packages is beyond + the scope of this document (refer to Imprints.txt also included + with the Samba distribution for more information). In short, + an Imprints driver package is a gzipped tarball containing the + driver files, related INF files, and a control file needed by the + installation client.</para> + </sect2> + + + <sect2> + <title>The Imprints server</title> + + <para>The Imprints server is really a database server that + may be queried via standard HTTP mechanisms. Each printer + entry in the database has an associated URL for the actual + downloading of the package. Each package is digitally signed + via GnuPG which can be used to verify that package downloaded + is actually the one referred in the Imprints database. It is + <emphasis>not</emphasis> recommended that this security check + be disabled.</para> + </sect2> + + <sect2> + <title>The Installation Client</title> + + <para>More information regarding the Imprints installation client + is available in the <filename>Imprints-Client-HOWTO.ps</filename> + file included with the imprints source package.</para> + + <para>The Imprints installation client comes in two forms.</para> + + <itemizedlist> + <listitem><para>a set of command line Perl scripts</para> + </listitem> + + <listitem><para>a GTK+ based graphical interface to + the command line perl scripts</para></listitem> + </itemizedlist> + + <para>The installation client (in both forms) provides a means + of querying the Imprints database server for a matching + list of known printer model names as well as a means to + download and install the drivers on remote Samba and Windows + NT print servers.</para> + + <para>The basic installation process is in four steps and + perl code is wrapped around <command>smbclient</command> + and <command>rpcclient</command>.</para> + +<para><programlisting> +foreach (supported architecture for a given driver) +{ + 1. rpcclient: Get the appropriate upload directory + on the remote server + 2. smbclient: Upload the driver files + 3. rpcclient: Issues an AddPrinterDriver() MS-RPC +} + +4. rpcclient: Issue an AddPrinterEx() MS-RPC to actually + create the printer +</programlisting></para> + + <para>One of the problems encountered when implementing + the Imprints tool set was the name space issues between + various supported client architectures. For example, Windows + NT includes a driver named "Apple LaserWriter II NTX v51.8" + and Windows 95 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> + + +<sect1> +<title><anchor id="MIGRATION">Migration to from Samba 2.0.x to 2.2.x</title> + +<para> +Given that printer driver management has changed (we hope improved) in +2.2 over prior releases, migration from an existing setup to 2.2 can +follow several paths. Here are the possible scenarios for +migration: +</para> + +<itemizedlist> + <listitem><para>If you do not desire the new Windows NT + print driver support, nothing needs to be done. + All existing parameters work the same.</para></listitem> + + <listitem><para>If you want to take advantage of NT printer + driver support but do not want to migrate the + 9x drivers to the new setup, the leave the existing + <filename>printers.def</filename> file. When smbd attempts + to locate a + 9x driver for the printer in the TDB and fails it + will drop down to using the printers.def (and all + associated parameters). The <command>make_printerdef</command> + tool will also remain for backwards compatibility but will + be removed in the next major release.</para></listitem> + + <listitem><para>If you install a Windows 9x driver for a printer + on your Samba host (in the printing TDB), this information will + take precedence and the three old printing parameters + will be ignored (including print driver location).</para></listitem> + + <listitem><para>If you want to migrate an existing <filename>printers.def</filename> + file into the new setup, the current only solution is to use the Windows + NT APW to install the NT drivers and the 9x drivers. This can be scripted + using <command>smbclient</command> and <command>rpcclient</command>. See the + Imprints installation client at <ulink + url="http://imprints.sourceforge.net/">http://imprints.sourceforge.net/</ulink> + for an example. + </para></listitem> +</itemizedlist> + + +<warning> +<title>Achtung!</title> + +<para> +The following <filename>smb.conf</filename> parameters are considered to +be deprecated and will be removed soon. Do not use them in new +installations +</para> + +<itemizedlist> + <listitem><para><parameter>printer driver file (G)</parameter> + </para></listitem> + + <listitem><para><parameter>printer driver (S)</parameter> + </para></listitem> + + <listitem><para><parameter>printer driver location (S)</parameter> + </para></listitem> +</itemizedlist> +</warning> + + +<para> +The have been two new parameters add in Samba 2.2.2 to for +better support of Samba 2.0.x backwards capability (<parameter>disable +spoolss</parameter>) and for using local printers drivers on Windows +NT/2000 clients (<parameter>use client driver</parameter>). Both of +these options are described in the smb.coinf(5) man page and are +disabled by default. +</para> + + +</sect1> + + +<!-- + + This comment from rpc_server/srv_spoolss_nt.c:_spoolss_open_printer_ex() + needs to be added into a section probably. This is to remind me it needs + to be done. -jerry + + /* + * If the openprinterex rpc call contains a devmode, + * it's a per-user one. This per-user devmode is derivated + * from the global devmode. Openprinterex() contains a per-user + * devmode for when you do EMF printing and spooling. + * In the EMF case, the NT workstation is only doing half the job + * of rendering the page. The other half is done by running the printer + * driver on the server. + * The EMF file doesn't contain the page description (paper size, orientation, ...). + * The EMF file only contains what is to be printed on the page. + * So in order for the server to know how to print, the NT client sends + * a devicemode attached to the openprinterex call. + * But this devicemode is short lived, it's only valid for the current print job. + * + * If Samba would have supported EMF spooling, this devicemode would + * have been attached to the handle, to sent it to the driver to correctly + * rasterize the EMF file. + * + * As Samba only supports RAW spooling, we only receive a ready-to-print file, + * we just act as a pass-thru between windows and the printer. + * + * In order to know that Samba supports only RAW spooling, NT has to call + * getprinter() at level 2 (attribute field) or NT has to call startdoc() + * and until NT sends a RAW job, we refuse it. + * + * But to call getprinter() or startdoc(), you first need a valid handle, + * and to get an handle you have to call openprintex(). Hence why you have + * a devicemode in the openprinterex() call. + * + * + * Differences between NT4 and NT 2000. + * NT4: + * + * On NT4, you only have a global devicemode. This global devicemode can be changed + * by the administrator (or by a user with enough privs). Every time a user + * wants to print, the devicemode is reset to the default. In Word, every time + * you print, the printer's characteristics are always reset to the global devicemode. + * + * NT 2000: + * + * In W2K, there is the notion of per-user devicemode. The first time you use + * a printer, a per-user devicemode is build from the global devicemode. + * If you change your per-user devicemode, it is saved in the registry, under the + * H_KEY_CURRENT_KEY sub_tree. So that every time you print, you have your default + * printer preferences available. + * + * To change the per-user devicemode: it's the "Printing Preferences ..." button + * on the General Tab of the printer properties windows. + * + * To change the global devicemode: it's the "Printing Defaults..." button + * on the Advanced Tab of the printer properties window. +--> + +</chapter> |