diff options
Diffstat (limited to 'docs/htmldocs/Samba-Developers-Guide.html')
| -rw-r--r-- | docs/htmldocs/Samba-Developers-Guide.html | 623 |
1 files changed, 622 insertions, 1 deletions
diff --git a/docs/htmldocs/Samba-Developers-Guide.html b/docs/htmldocs/Samba-Developers-Guide.html index f7a452bfc5..7c008667af 100644 --- a/docs/htmldocs/Samba-Developers-Guide.html +++ b/docs/htmldocs/Samba-Developers-Guide.html @@ -35,7 +35,7 @@ NAME="AEN8">Abstract</H1 ><I CLASS="EMPHASIS" >Last Update</I -> : Mon aug 26 12:41:19 CEST 2002</P +> : Mon Sep 30 15:23:53 CDT 2002</P ><P >This book is a collection of documents that might be useful for people developing samba or those interested in doing so. @@ -652,6 +652,54 @@ HREF="#AEN2811" ></DD ></DL ></DD +><DT +><A +HREF="#PRINTING" +>Samba Printing Internals</A +></DT +><DD +><DL +><DT +><A +HREF="#AEN2895" +>Abstract</A +></DT +><DT +><A +HREF="#AEN2898" +>Printing Interface to Various Back ends</A +></DT +><DT +><A +HREF="#AEN2924" +>Print Queue TDB's</A +></DT +><DT +><A +HREF="#AEN2958" +>ChangeID & Client Caching of Printer Information</A +></DT +><DT +><A +HREF="#AEN2961" +>Windows NT/2K Printer Change Notify</A +></DT +></DL +></DD +><DT +><A +HREF="#WINS" +>Samba WINS Internals</A +></DT +><DD +><DL +><DT +><A +HREF="#AEN3032" +>WINS Failover</A +></DT +></DL +></DD ></DL ></DIV ><DIV @@ -7728,6 +7776,579 @@ NAME="AEN2846">Well-known RID aliases</H4 ></DIV ></DIV ></DIV +><DIV +CLASS="CHAPTER" +><HR><H1 +><A +NAME="PRINTING">Samba Printing Internals</H1 +><DIV +CLASS="SECT1" +><H2 +CLASS="SECT1" +><A +NAME="AEN2895">Abstract</H2 +><P +>The purpose of this document is to provide some insight into +Samba's printing functionality and also to describe the semantics +of certain features of Windows client printing.</P +></DIV +><DIV +CLASS="SECT1" +><HR><H2 +CLASS="SECT1" +><A +NAME="AEN2898">Printing Interface to Various Back ends</H2 +><P +>Samba uses a table of function pointers to seven functions. The +function prototypes are defined in the <TT +CLASS="VARNAME" +>printif</TT +> structure declared +in <TT +CLASS="FILENAME" +>printing.h</TT +>.</P +><P +></P +><UL +><LI +><P +>retrieve the contents of a print queue</P +></LI +><LI +><P +>pause the print queue</P +></LI +><LI +><P +>resume a paused print queue</P +></LI +><LI +><P +>delete a job from the queue</P +></LI +><LI +><P +>pause a job in the print queue</P +></LI +><LI +><P +>result a paused print job in the queue</P +></LI +><LI +><P +>submit a job to the print queue</P +></LI +></UL +><P +>Currently there are only two printing back end implementations +defined.</P +><P +></P +><UL +><LI +><P +>a generic set of functions for working with standard UNIX + printing subsystems</P +></LI +><LI +><P +>a set of CUPS specific functions (this is only enabled if + the CUPS libraries were located at compile time).</P +></LI +></UL +></DIV +><DIV +CLASS="SECT1" +><HR><H2 +CLASS="SECT1" +><A +NAME="AEN2924">Print Queue TDB's</H2 +><P +>Samba provides periodic caching of the output from the "lpq command" +for performance reasons. This cache time is configurable in seconds. +Obviously the longer the cache time the less often smbd will be +required to exec a copy of lpq. However, the accuracy of the print +queue contents displayed to clients will be diminished as well.</P +><P +>The list of currently opened print queue TDB's can be found +be examining the list of tdb_print_db structures ( see print_db_head +in printing.c ). A queue TDB is opened using the wrapper function +printing.c:get_print_db_byname(). The function ensures that smbd +does not open more than MAX_PRINT_DBS_OPEN in an effort to prevent +a large print server from exhausting all available file descriptors. +If the number of open queue TDB's exceeds the MAX_PRINT_DBS_OPEN +limit, smbd falls back to a most recently used algorithm for maintaining +a list of open TDB's.</P +><P +>There are two ways in which a a print job can be entered into +a print queue's TDB. The first is to submit the job from a Windows +client which will insert the job information directly into the TDB. +The second method is to have the print job picked up by executing the +"lpq command".</P +><P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +>/* included from printing.h */ +struct printjob { + pid_t pid; /* which process launched the job */ + int sysjob; /* the system (lp) job number */ + int fd; /* file descriptor of open file if open */ + time_t starttime; /* when the job started spooling */ + int status; /* the status of this job */ + size_t size; /* the size of the job so far */ + int page_count; /* then number of pages so far */ + BOOL spooled; /* has it been sent to the spooler yet? */ + BOOL smbjob; /* set if the job is a SMB job */ + fstring filename; /* the filename used to spool the file */ + fstring jobname; /* the job name given to us by the client */ + fstring user; /* the user who started the job */ + fstring queuename; /* service number of printer for this job */ + NT_DEVICEMODE *nt_devmode; +};</PRE +></TD +></TR +></TABLE +></P +><P +>The current manifestation of the printjob structure contains a field +for the UNIX job id returned from the "lpq command" and a Windows job +ID (32-bit bounded by PRINT_MAX_JOBID). When a print job is returned +by the "lpq command" that does not match an existing job in the queue's +TDB, a 32-bit job ID above the <*vance doesn't know what word is missing here*> is generating by adding UNIX_JOB_START to +the id reported by lpq.</P +><P +>In order to match a 32-bit Windows jobid onto a 16-bit lanman print job +id, smbd uses an in memory TDB to match the former to a number appropriate +for old lanman clients.</P +><P +>When updating a print queue, smbd will perform the following +steps ( refer to <TT +CLASS="FILENAME" +>print.c:print_queue_update()</TT +> ):</P +><P +></P +><OL +TYPE="1" +><LI +><P +>Check to see if another smbd is currently in + the process of updating the queue contents by checking the pid + stored in <TT +CLASS="CONSTANT" +>LOCK/<TT +CLASS="REPLACEABLE" +><I +>printer_name</I +></TT +></TT +>. + If so, then do not update the TDB.</P +></LI +><LI +><P +>Lock the mutex entry in the TDB and store our own pid. + Check that this succeeded, else fail.</P +></LI +><LI +><P +>Store the updated time stamp for the new cache + listing</P +></LI +><LI +><P +>Retrieve the queue listing via "lpq command"</P +></LI +><LI +><P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="90%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +> foreach job in the queue + { + if the job is a UNIX job, create a new entry; + if the job has a Windows based jobid, then + { + Lookup the record by the jobid; + if the lookup failed, then + treat it as a UNIX job; + else + update the job status only + } + }</PRE +></TD +></TR +></TABLE +></P +></LI +><LI +><P +>Delete any jobs in the TDB that are not + in the in the lpq listing</P +></LI +><LI +><P +>Store the print queue status in the TDB</P +></LI +><LI +><P +>update the cache time stamp again</P +></LI +></OL +><P +>Note that it is the contents of this TDB that is returned to Windows +clients and not the actual listing from the "lpq command".</P +><P +>The NT_DEVICEMODE stored as part of the printjob structure is used to +store a pointer to a non-default DeviceMode associated with the print +job. The pointer will be non-null when the client included a Device +Mode in the OpenPrinterEx() call and subsequently submitted a job for +printing on that same handle. If the client did not include a Device +Mode in the OpenPrinterEx() request, the nt_devmode field is NULL +and the job has the printer's device mode associated with it by default.</P +><P +>Only non-default Device Mode are stored with print jobs in the print +queue TDB. Otherwise, the Device Mode is obtained from the printer +object when the client issues a GetJob(level == 2) request.</P +></DIV +><DIV +CLASS="SECT1" +><HR><H2 +CLASS="SECT1" +><A +NAME="AEN2958">ChangeID & Client Caching of Printer Information</H2 +><P +>[To be filled in later]</P +></DIV +><DIV +CLASS="SECT1" +><HR><H2 +CLASS="SECT1" +><A +NAME="AEN2961">Windows NT/2K Printer Change Notify</H2 +><P +>When working with Windows NT+ clients, it is possible for a +print server to use RPC to send asynchronous change notification +events to clients for certain printer and print job attributes. +This can be useful when the client needs to know that a new +job has been added to the queue for a given printer or that the +driver for a printer has been changed. Note that this is done +entirely orthogonal to cache updates based on a new ChangeID for +a printer object.</P +><P +>The basic set of RPC's used to implement change notification are</P +><P +></P +><UL +><LI +><P +>RemoteFindFirstPrinterChangeNotifyEx ( RFFPCN )</P +></LI +><LI +><P +>RemoteFindNextPrinterChangeNotifyEx ( RFNPCN )</P +></LI +><LI +><P +>FindClosePrinterChangeNotify( FCPCN )</P +></LI +><LI +><P +>ReplyOpenPrinter</P +></LI +><LI +><P +>ReplyClosePrinter</P +></LI +><LI +><P +>RouteRefreshPrinterChangeNotify ( RRPCN )</P +></LI +></UL +><P +>One additional RPC is available to a server, but is never used by the +Windows spooler service:</P +><P +></P +><UL +><LI +><P +>RouteReplyPrinter()</P +></LI +></UL +><P +>The opnum for all of these RPC's are defined in include/rpc_spoolss.h</P +><P +>Windows NT print servers use a bizarre method of sending print +notification event to clients. The process of registering a new change +notification handle is as follows. The 'C' is for client and the +'S' is for server. All error conditions have been eliminated.</P +><P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +>C: Obtain handle to printer or to the printer + server via the standard OpenPrinterEx() call. +S: Respond with a valid handle to object + +C: Send a RFFPCN request with the previously obtained + handle with either (a) set of flags for change events + to monitor, or (b) a PRINTER_NOTIFY_OPTIONS structure + containing the event information to monitor. The windows + spooler has only been observed to use (b). +S: The <* another missing word*> opens a new TCP session to the client (thus requiring + all print clients to be CIFS servers as well) and sends + a ReplyOpenPrinter() request to the client. +C: The client responds with a printer handle that can be used to + send event notification messages. +S: The server replies success to the RFFPCN request. + +C: The windows spooler follows the RFFPCN with a RFNPCN + request to fetch the current values of all monitored + attributes. +S: The server replies with an array SPOOL_NOTIFY_INFO_DATA + structures (contained in a SPOOL_NOTIFY_INFO structure). + +C: If the change notification handle is ever released by the + client via a FCPCN request, the server sends a ReplyClosePrinter() + request back to the client first. However a request of this + nature from the client is often an indication that the previous + notification event was not marshalled correctly by the server + or a piece of data was wrong. +S: The server closes the internal change notification handle + (POLICY_HND) and does not send any further change notification + events to the client for that printer or job.</PRE +></TD +></TR +></TABLE +></P +><P +>The current list of notification events supported by Samba can be +found by examining the internal tables in srv_spoolss_nt.c</P +><P +></P +><UL +><LI +><P +>printer_notify_table[]</P +></LI +><LI +><P +>job_notify_table[]</P +></LI +></UL +><P +>When an event occurs that could be monitored, smbd sends a message +to itself about the change. The list of events to be transmitted +are queued by the smbd process sending the message to prevent an +overload of TDB usage and the internal message is sent during smbd's +idle loop (refer to printing/notify.c and the functions +send_spoolss_notify2_msg() and print_notify_send_messages() ).</P +><P +>The decision of whether or not the change is to be sent to connected +clients is made by the routine which actually sends the notification. +( refer to srv_spoolss_nt.c:recieve_notify2_message() ).</P +><P +>Because it possible to receive a listing of multiple changes for +multiple printers, the notification events must be split into +categories by the printer name. This makes it possible to group +multiple change events to be sent in a single RPC according to the +printer handle obtained via a ReplyOpenPrinter().</P +><P +>The actual change notification is performed using the RRPCN request +RPC. This packet contains</P +><P +></P +><UL +><LI +><P +>the printer handle registered with the +client's spooler on which the change occurred</P +></LI +><LI +><P +>The change_low value which was sent as part +of the last RFNPCN request from the client</P +></LI +><LI +><P +>The SPOOL_NOTIFY_INFO container with the event +information</P +></LI +></UL +><P +>A <TT +CLASS="VARNAME" +>SPOOL_NOTIFY_INFO</TT +> contains:</P +><P +></P +><UL +><LI +><P +>the version and flags field are predefined +and should not be changed</P +></LI +><LI +><P +>The count field is the number of entries +in the SPOOL_NOTIFY_INFO_DATA array</P +></LI +></UL +><P +>The <TT +CLASS="VARNAME" +>SPOOL_NOTIFY_INFO_DATA</TT +> entries contain:</P +><P +></P +><UL +><LI +><P +>The type defines whether or not this event +is for a printer or a print job</P +></LI +><LI +><P +>The field is the flag identifying the event</P +></LI +><LI +><P +>the notify_data union contains the new valuie of the +attribute</P +></LI +><LI +><P +>The enc_type defines the size of the structure for marshalling +and unmarshalling</P +></LI +><LI +><P +>(a) the id must be 0 for a printer event on a printer handle. +(b) the id must be the job id for an event on a printer job +(c) the id must be the matching number of the printer index used +in the response packet to the RFNPCN when using a print server +handle for notification. Samba currently uses the snum of +the printer for this which can break if the list of services +has been modified since the notification handle was registered.</P +></LI +><LI +><P +>The size is either (a) the string length in UNICODE for strings, +(b) the size in bytes of the security descriptor, or (c) 0 for +data values.</P +></LI +></UL +></DIV +></DIV +><DIV +CLASS="CHAPTER" +><HR><H1 +><A +NAME="WINS">Samba WINS Internals</H1 +><DIV +CLASS="SECT1" +><H2 +CLASS="SECT1" +><A +NAME="AEN3032">WINS Failover</H2 +><P +>The current Samba codebase possesses the capability to use groups of WINS +servers that share a common namespace for NetBIOS name registration and +resolution. The formal parameter syntax is</P +><P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +> WINS_SERVER_PARAM = SERVER [ SEPARATOR SERVER_LIST ] + WINS_SERVER_PARAM = "wins server" + SERVER = ADDR[:TAG] + ADDR = ip_addr | fqdn + TAG = string + SEPARATOR = comma | \s+ + SERVER_LIST = SERVER [ SEPARATOR SERVER_LIST ]</PRE +></TD +></TR +></TABLE +></P +><P +>A simple example of a valid wins server setting is</P +><P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +>[global] + wins server = 192.168.1.2 192.168.1.3</PRE +></TD +></TR +></TABLE +></P +><P +>In the event that no TAG is defined in for a SERVER in the list, smbd assigns a default +TAG of "*". A TAG is used to group servers of a shared NetBIOS namespace together. Upon +startup, nmbd will attempt to register the netbios name value with one server in each +tagged group.</P +><P +>An example using tags to group WINS servers together is show here. Note that the use of +interface names in the tags is only by convention and is not a technical requirement.</P +><P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="PROGRAMLISTING" +>[global] + wins server = 192.168.1.2:eth0 192.168.1.3:eth0 192.168.2.2:eth1</PRE +></TD +></TR +></TABLE +></P +><P +>Using this configuration, nmbd would attempt to register the server's NetBIOS name +with one WINS server in each group. Because the "eth0" group has two servers, the +second server would only be used when a registration (or resolution) request to +the first server in that group timed out.</P +><P +>NetBIOS name resolution follows a similar pattern as name registration. When resolving +a NetBIOS name via WINS, smbd and other Samba programs will attempt to query a single WINS +server in a tagged group until either a positive response is obtained at least once or +until a server from every tagged group has responded negatively to the name query request. +If a timeout occurs when querying a specific WINS server, that server is marked as down to +prevent further timeouts and the next server in the WINS group is contacted. Once marked as +dead, Samba will not attempt to contact that server for name registration/resolution queries +for a period of 10 minutes.</P +></DIV +></DIV ></DIV ></BODY ></HTML |