path: root/source3/namework.doc

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.