updated low-level design documentation on nmbd. first draft of namework.doc

and updated the other two.

lkcl
(This used to be commit 96d242826d618f7dcdb1a1adf50d484df7e2a5c0)

3 files changed, 489 insertions, 15 deletions

diff --git a/source3/nameresp.doc b/source3/nameresp.doc
index 71698c138e..3d4bc3c348 100644
--- a/source3/nameresp.doc
+++ b/source3/nameresp.doc
@@ -28,6 +28,161 @@ their creation, retransmission, and eventual removal.
 
 
 /*************************************************************************
+  send_mailslot_reply()
+  *************************************************************************/
+
+this function is responsible for sending a MAILSLOT packet.
+
+it will _not_ send packets to the pseudo WINS subnet's address of 
+255.255.255.255: this would be disastrous.
+
+each packet sent out has a unique transaction identifier. this is done
+so that responses can be matched with the original purpose for the packet
+being sent out in the first place.
+
+
+/*************************************************************************
+  interpret_node_status()
+  *************************************************************************/
+
+this function is responsible for interpreting the raw data that comes in
+from a node status reply. in the process, it identifies both the server
+name and the workgroup name in the node status reply.
+
+it also updates information in the WINS name database if the names 
+received are not already in samba's records.
+
+
+/*************************************************************************
+  listen_for_packets()
+  *************************************************************************/
+
+this function is responsible for reading NMB and DGRAM packets, and then
+queueing them. it will normally time-out for NMBD_SELECT_LOOP seconds, but
+if there is an election currently running or we are expecting a response
+then this time is reduced to 1 second.
+
+note: the time-out period needs refining to the millisecond level.
+
+
+/*************************************************************************
+  queue_packet()
+  *************************************************************************/
+
+this function is responsible for queueing any NMB and DGRAM packets passed
+to it. these packets will be removed from the queue in run_packet_queue().
+
+
+/*************************************************************************
+  run_packet_queue()
+  *************************************************************************/
+
+this function is responsible for taking a packet off the queue, 
+identifying whether it is an NMB or a DGRAM packet, processing
+it accordingly and deleting it. this process continues until
+there are no more packets on the queue.
+
+
+/*************************************************************************
+  find_response_record()
+  *************************************************************************/
+
+this function is responsible for matching the unique response transaction
+id with an expected response record. as a side-effect of this search,
+it will find the subnet (or the WINS pseudo-subnet) that samba expected
+the response to come from.
+
+
+/*************************************************************************
+  queue_netbios_packet()
+  *************************************************************************/
+
+this function is responsible for sending out a netbios packet, and then
+making a record of the information that was sent out. a response will
+be expected later (or not, as the case may be).
+
+if a response is received, response_netbios_packet() will deal with it.
+otherwise, it will be dealt with in expire_netbios_response_entries().
+
+
+/*************************************************************************
+  make_response_queue_record()
+  *************************************************************************/
+
+this function is responsible for creating a response record, which will
+be queued awaiting a response.
+
+the number of retries is set to 4, and the retry period set to 1 second.
+if no response is received, then the packet is re-transmitted, which is
+why so much information is stored in the response record.
+
+the number of expected responses queued is kept, so listen_for_packets()
+knows it must time-out after 1 second if one or more responses are
+expected.
+
+
+/*************************************************************************
+  queue_netbios_pkt_wins()
+  *************************************************************************/
+
+this function is a wrapper around queue_netbios_packet(). there is
+some confusion about B, M and P nodes (see rfc1001.txt section 10) -
+confusion introduced by luke :-) - which needs sorting out.
+
+for example, rfc1001.txt 15.2.3 - an M node must attempt to register a
+name first as a B node, then attempt to register as an M node. negative
+responses on either of these attempts is a failure to register the
+name.
+
+this is NOT the case with a P node.
+
+
+/*************************************************************************
+  reply_netbios_packet()
+  *************************************************************************/
+
+this function is responsible for sending a reply to another NetBIOS
+packet from another host. it can be used to send a reply to a name
+registration, name release, name query or name status request.
+
+the reply can be either a positive or a negative one.
+
+
+/*************************************************************************
+  expire_netbios_response_entries()
+  *************************************************************************/
+
+this function is responsible for dealing with queued response records
+that have not received a response packet matching their unique
+transaction id.
+
+if the retry count for any record is non-zero, and its time-out period
+has expired, the retry count is reduced, the time-out period is stepped
+forward and the packet is re-transmitted (from the information stored
+in the queued response record) with the same unique transaction id of
+the initial attempt at soliciting a response.
+
+if the retry count is zero, then the packet is assumed to have expired.
+dead_netbios_entry() is called to deal with the possibility of an error
+or a problem (or in certain instances, no answer is an implicit
+positive response!).
+
+the expected response record is then deleted, and the number of expected
+responses reduced. when this count gets to zero, listen_for_packets()
+will no longer time-out for 1 second on account of expecting response
+packets.
+
+
+/*************************************************************************
+  initiate_netbios_packet()
+  *************************************************************************/
+
+this function is responsible for construction a netbios packet and sending
+it. if the packet has not had a unique transaction id allocated to it,
+then initiate_netbios_packet() will give it one.
+
+
+/*************************************************************************
   dead_netbios_entry()
   *************************************************************************/
 
@@ -39,40 +194,40 @@ or more hosts.
 
 - NAME_QUERY_CONFIRM
 
-when a samba 'command' of type NAME_QUERY_CONFIRM is sent, a response
+when a samba 'state' of type NAME_QUERY_CONFIRM is sent, a response
 may or may not be forthcoming. if no response is received to a unique
 name, then the record is removed from samba's WINS database. non-unique
 names are simply expected to die off on a time-to-live basis (see
 rfc1001.txt 15.1.3.4)
 
-query_refresh_names() issues this samba 'command'
+query_refresh_names() issues this samba 'state'
 response_name_query_sync() deals with responses to NAME_QUERY_CONFIRM.
 
 - NAME_QUERY_MST_CHK
 
-when a samba 'command' of type NAME_QUERY_MST_CHK is sent, and a response
+when a samba 'state' of type NAME_QUERY_MST_CHK is sent, and a response
 is not received, this implies that a master browser will have failed.
 remedial action may need to be taken, for example if samba is a member
 of that workgroup and it is also a potential master browser it could
 force an election.
 
-check_master_browser() issues this samba 'command'.
+check_master_browser() issues this samba 'state'.
 response_process() does nothing if a response is received. this is normal.
 
 - NAME_RELEASE
 
-when a samba 'command' of type NAME_RELEASE is sent, and a response is
+when a samba 'state' of type NAME_RELEASE is sent, and a response is
 not received, it is assumed to be acceptable to release the name. if the
 original response was sent to another WINS server, then that WINS server
 may be inaccessible or may have failed. if so, then at a later date
 samba should take this into account (see rfc1001.txt 10.3).
 
-remove_name_entry() issues this samba 'command'
+remove_name_entry() issues this samba 'state'
 response_name_rel() deals with responses to NAME_RELEASE.
 
 - NAME_REGISTER
 
-when a samba 'command' of type NAME_REGISTER is sent, and a response is
+when a samba 'state' of type NAME_REGISTER is sent, and a response is
 not received, if the registration was done by broadcast, it is assumed
 that there are no objections to the registration of this name, and samba
 adds the name to the appropriate subnet record name database. if the
@@ -80,9 +235,27 @@ registration was point-to-point (i.e with another WINS server) then that
 WINS server may be inaccessible or may have failed. if so, then at a later
 date samba should take this into account (see rfc1001.txt 10.3).
 
-add_my_name_entry() issues this samba 'command'
+add_my_name_entry() issues this samba 'state'
 response_name_reg() deals with responses to NAME_REGISTER.
 
-no action is taken for any other kinds of samba 'commands' if a response
+no action is taken for any other kinds of samba 'states' if a response
 is not received. this is not to say that action may not be appropriate,
 just that it's not been looked at yet :-)
+
+
+/*************************************************************************
+  add_response_record()
+  *************************************************************************/
+
+this function is responsible for adding the response record created by
+make_response_queue_record() into the appropriate response record queue.
+
+
+/*************************************************************************
+  update_name_trn_id()
+  *************************************************************************/
+
+this function is responsible for allocating unique transaction identifiers
+for each new packet sent on the network.
+
+
diff --git a/source3/nameserv.doc b/source3/nameserv.doc
index b2e966a2c6..60ff52f4a3 100644
--- a/source3/nameserv.doc
+++ b/source3/nameserv.doc
@@ -35,7 +35,7 @@ after debug information is reported, and validation of the netbios
 packet (e.g only one response from one machine is expected for some
 functions) has occurred, the packet is processed. when the initial
 request was sent out, the expected response record was flagged with,
-for lack of a better word, a samba 'command' type. whenever a
+for lack of a better word, a samba 'state' type. whenever a
 response is received, the appropriate function is called to carry on
 where the program control flow was interrupted while awaiting exactly
 such a response.
@@ -48,7 +48,7 @@ area of code - expire_netbios_response_entries().
   response_name_query_sync()
   *************************************************************************/
 
-this function receives responses to samba 'commands' NAME_QUERY_SYNC and
+this function receives responses to samba 'states' NAME_QUERY_SYNC and
 NAME_QUERY_CONFIRM.
 
 NAME_QUERY_SYNC: name query a server before synchronising browse lists.
@@ -72,7 +72,7 @@ entry should be removed if we receive a negative response.
   response_name_status_check()
   *************************************************************************/
 
-this function receives responses to samba 'commands' NAME_STATUS_CHECK
+this function receives responses to samba 'states' NAME_STATUS_CHECK
 and NAME_STATUS_MASTER_CHECK
 
 NAME_STATUS_MASTER_CHECK: name status a primary domain controller, 
@@ -94,7 +94,7 @@ correct part of samba's workgroup - server database.
   response_server_check()
   *************************************************************************/
 
-this function receives responses to samba 'commands' NAME_QUERY_MST_SRV_CHK,
+this function receives responses to samba 'states' NAME_QUERY_MST_SRV_CHK,
 NAME_QUERY_SRV_CHK and NAME_QUERY_FIND_MST.
 
 NAME_QUERY_FIND_MST: issued as a broadcast when we wish to find out all
@@ -109,12 +109,16 @@ NAME_QUERY_MST_SRV_CHK: same as a NAME_QUERY_FIND_MST except this is sent
 NAME_QUERY_SRV_CHK: same as a NAME_QUERY_MST_SRV_CHK except this is sent to
                     a master browser.
                         
-the purpose of each of these commands is to do a broadcast name query, or
+the purpose of each of these states is to do a broadcast name query, or
 a name query directed at a WINS server, then to all hosts that respond,
 we issue a name status check, which will confirm for us the workgroup
 or domain name, and then initiate issuing a sync browse list call with
 that server.
 
+a NAME_QUERY_SRV_CHK is sent when samba receives a list of backup
+browsers. it checks to see if that server is alive (by doing a
+name query on a server) and then syncs browse lists with it.
+
 
 /*************************************************************************
   reply_name_query()
@@ -186,7 +190,7 @@ of samba's NetBIOS name database. if the name cannot be found, then it
 should look the name up using DNS. later modifications will be to
 forward the request on to another WINS server, should samba not be able
 to find out about the requested name (this will be implemented through
-issuing a new type of samba 'command').
+issuing a new type of samba 'state').
 
 the name is first searched for in the NetBIOS cache. if it cannot be
 found, then it if the name looks like it's a server-type name (0x20
diff --git a/source3/namework.doc b/source3/namework.doc
new file mode 100644
index 0000000000..4616b328da
--- /dev/null
+++ b/source3/namework.doc
@@ -0,0 +1,297 @@
+
+the module namework.c deals with NetBIOS datagram packets, primarily.
+it deals with nmbd's workgroup browser side and the domain log in
+side. none of the functionality here has specification documents available.
+empirical observation of packet traces has been the order of the day.
+
+beware!
+
+the receipt of datagram packets for workgroup browsing are dealt with here.
+some of the functions listed here will call others outside of this
+module, or will activate functionality dealt with by other modules.
+
+these include: namedb.c, nameannounce.c, nameelect.c,
+               namelogon.c, and namebrowse.c.
+
+
+/*************************************************************************
+  process_dgram()
+  *************************************************************************/
+
+this function is responsible for identifying whether the datagram
+packet received is a browser packet or a domain logon packet. it
+also does some filtering of certain types of packets (e.g it
+filters out error packets).
+
+
+/*************************************************************************
+  process_browse_packet()
+  *************************************************************************/
+
+this function is responsible for further identifying which type of
+browser datagram packet has been received, and dealing with it
+accordingly. if the packet is not dealt with, then an error is
+logged along with the type of packet that has been received.
+
+if listening_type() was in use, then it would be used here.
+
+the types of packets received and dealt with are:
+
+- ANN_HostAnnouncement         
+- ANN_DomainAnnouncement      
+- ANN_LocalMasterAnnouncement 
+
+these are all identical in format and can all be processed by
+process_announce(). an announcement is received from a host
+(either a master browser telling us about itself, a server
+telling us about itself or a master browser telling us about
+a domain / workgroup)
+
+- ANN_AnnouncementRequest      
+
+these are sent by master browsers or by servers. it is a
+request to announce ourselves as appropriate by sending
+either a ANN_HostAnnouncement datagram or both an
+ANN_DomainAnnouncement and an ANN_LocalMasterAnnouncement
+if we are a master browser (but not both).
+
+- ANN_Election                 
+
+this is an election datagram. if samba has been configured
+as a domain master then it will also send out election
+datagrams. 
+
+- ANN_GetBackupListReq         
+
+this is a request from another server for us to send a
+backup list of all servers that we know about. we respond
+by sending a datagram ANN_GetBackupListResp. the protocol
+here is a little dicey.
+
+- ANN_GetBackupListResp       
+
+this is a response from another server that we have sent an
+ANN_GetBackupListReq to. the protocol is a little dicey.
+
+- ANN_BecomeBackup            
+
+this is a message sent by a primary domain controller to a
+potential master browser, indicating that it should become
+a backup master browser for the workgroup it is a member
+of. samba does not respond at present to such datagrams,
+and it also sends out such datagrams for the wrong reasons
+(this code has now been disabled until this is fixed).
+
+- ANN_ResetBrowserState       
+
+this datagram is sent by a primary domain controller (or
+anyone else, for that matter) for trouble-shooting purposes.
+it asks a browser to clear out its server lists, or to
+stop becoming a master browser altogether. NT/AS and
+samba do not implement this latter option.
+
+- ANN_MasterAnnouncement      
+
+this datagram is sent by a master browser to a primary domain
+controller. it is a way to ensure that master browsers are
+kept in sync with a primary domain controller across a wide
+area network.
+
+(i never got the hang of this one when i was experimenting.
+i forget exactly what it's for, and i never fully worked
+out how to coax a server to send it. :-)
+
+
+/*************************************************************************
+  listening_type()
+  *************************************************************************/
+
+
+a datagram packet is sent from one NetBIOS name of a specific type
+to another NetBIOS name of a specific type. certain types of
+datagrams are only expected from certain types of NetBIOS names.
+
+this function is intended to catch errors in the type of datagrams
+received from different NetBIOS names. it is currently incomplete
+due to lack of information on the types of names and the datagrams
+they send.
+
+
+/*************************************************************************
+  process_announce_request()
+  *************************************************************************/
+
+this function is responsible for dealing with announcement requests.
+if the type of name that the request is sent to matches our current
+status, then we should respond. otherwise, the datagram should be
+ignored.
+
+samba only responds on its local subnets.
+
+at present, just the name is checked to see if the packet is for us.
+what should be done is that if we own the name (e.g WORGROUP(0x1d)
+or WORKGROUP(0x1b) then we should respond, otherwise, ignore the
+datagram.
+
+if the name is for us, and we are a member of that workgroup, then
+samba should respond.
+ 
+note that samba does not respond immediately. this is to ensure that
+if the master browser for the workgroup that samba is a member of
+sends out a broadcast request announcement, that that master browser
+is not swamped with replies. it is therefore up to samba to reply
+at some random interval. hence, a flag is set indicating the need
+to announce later.
+
+
+/*************************************************************************
+  process_reset_browser()
+  *************************************************************************/
+
+this function is responsible for dealing with reset state datagrams.
+there are three kinds of diagnostic reset requests:
+
+- stop being a master browser
+- discard browse lists, stop being a master browser, and run for re-election
+- stop being a master browser forever.
+
+samba and windows nt do not implement the latter option.
+
+there appears to be a discrepancy between this description and the
+code actually implemented.
+
+
+/*************************************************************************
+  process_send_backup_list()
+  *************************************************************************/
+
+this function is part of samba's primary domain controller functionality.
+
+it is responsible for giving master browsers a list of other browsers
+that maintain backup lists of servers for that master browser's workgroup.
+
+it is also responsible for giving master browsers a list of primary domain
+controllers for that master browser's domain.
+
+a correct way to think of this function is that it is a 'request to
+send out a backup list for the requested workgroup or domain'.
+
+i have some suspicions and intuitions about this function and how it
+is to actually be used. there is no documentation on this, so it is a
+matter of experimenting until it's right.
+
+
+/*************************************************************************
+  send_backup_list()
+  *************************************************************************/
+
+this function is responsible for compiling a list of either master
+browsers and backup master browsers or primary domain controllers or
+backup domain controllers. samba constructs this list from its 
+workgroup / server database.
+
+the list is then sent to the host that requested it by sending an
+ANN_GetBackupListResp datagram to this host.
+
+
+/*************************************************************************
+  process_rcv_backup_list()
+  *************************************************************************/
+
+this function is implemented with a slightly over-kill algorithm.
+the correct functionality is to pick any three names at random from
+the list that is received from this datagram, and then at intervals
+contact _one_ of them for a list of browser, in order to update
+samba's browse list.
+
+samba contacts every single one of the backup browsers listed, through
+the use of a NAME_QUERY_SRV_CHK 'state'.
+
+
+/*************************************************************************
+  process_master_announce()
+  *************************************************************************/
+
+this function is responsible for synchronising browse lists with a
+master browser that contacts samba in its capacity as a primary
+domain controller.
+
+the function add_browser_entry() is used to add the server that
+contacts us to our list of browser to sync browse lists with at
+some point in the near future.
+
+
+/*************************************************************************
+  process_announce()
+  *************************************************************************/
+
+this function is responsible for dealing with the three types of
+announcement type datagrams that samba recognises. some appropriate
+type-checking is done on the name that the datagram is sent to.
+
+samba does not at present deal with LanManager announcements.
+
+these announcements are for updating the browse entry records.
+each browse entry has a time-to-live associated with it. each server
+must refresh its entry with all other servers by broadcasting
+Announcements. if it does not do so, then other servers will not
+know about that machine, and the records on each server of that
+other machine will die.
+
+if an ANN_DomainAnnouncement is received, then this will be from
+a master browser. only one machine on any given broadcast area (e.g
+a subnet) should be broadcasting such announcements. the information
+it contains tells other servers that there is a master browser for
+this workgroup. if another server thinks that it is also a master
+browser for the same workgroup, then it should stop being a master
+browser and force an election.
+
+if an ANN_LocalMasterAnnouncement is received, then a master browser
+is telling us that it exists. i am uncertain that anything else
+actually needs to be done with this, other than to shout 'hooray' and
+'thank you for informing me of this fact'.
+
+
+/*************************************************************************
+  listening_name()
+  *************************************************************************/
+
+this function is an over-simplified way of identifying whether we
+should be responding to a datagram that has been received.
+
+
+/*************************************************************************
+  same_context()
+  *************************************************************************/
+
+this function helps us to identify whether we should be responding to
+a datagram that has been received.
+
+
+/*************************************************************************
+  tell_become_backup()
+  *************************************************************************/
+
+this function is part of samba's primary domain controller capabilities.
+it is responsible for finding appropriate servers to tell to become a
+backup master browser for the domain that samba controls.
+
+other servers that contact samba asking for a list of backup browsers
+will then be given that server's name, and that server can expect to
+receive NetServerEnum requests for lists of servers and workgroups.
+
+this function must be updated before it is in a fit state to be used.
+it must properly check whether a server is prepared to become a backup
+browser before actually asking it to be one.
+
+
+/*************************************************************************
+  reset_server()
+  *************************************************************************/
+
+this function is responsible for issuing an ANN_ResetBrowserState to
+the specified server, asking it to reset its browser information.
+
+see process_reset_browser() for details on this function.
+
+