summaryrefslogtreecommitdiff
path: root/docs/htmldocs/Samba-Developers-Guide.html
diff options
context:
space:
mode:
authorGerald Carter <jerry@samba.org>2002-10-01 01:06:37 +0000
committerGerald Carter <jerry@samba.org>2002-10-01 01:06:37 +0000
commit5de642fc6c476f7631b8caaebd1eda5c4d50df57 (patch)
tree5ef727527eb9844834599053fd1310d99227719f /docs/htmldocs/Samba-Developers-Guide.html
parentd2c0dca984c59847a094d1ea5f03fd271fe19c58 (diff)
downloadsamba-5de642fc6c476f7631b8caaebd1eda5c4d50df57.tar.gz
samba-5de642fc6c476f7631b8caaebd1eda5c4d50df57.tar.bz2
samba-5de642fc6c476f7631b8caaebd1eda5c4d50df57.zip
fixing typos spotted by eagle-eye-vance
(This used to be commit 5bae773e0270c31ba936ef651dda149601ac6ecd)
Diffstat (limited to 'docs/htmldocs/Samba-Developers-Guide.html')
-rw-r--r--docs/htmldocs/Samba-Developers-Guide.html623
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 &#38; 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 &#60;*vance doesn't know what word is missing here*&#62; 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 &#38; 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 &#60;* another missing word*&#62; 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