1
0
mirror of https://github.com/samba-team/samba.git synced 2024-12-22 13:34:15 +03:00

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

and updated the other two.

lkcl
This commit is contained in:
Samba Release Account 0001-01-01 00:00:00 +00:00
parent 546c490807
commit 96d242826d
3 changed files with 489 additions and 15 deletions

View File

@ -27,6 +27,161 @@ nameresp.c deals with the maintenance of the netbios response records:
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.

View File

@ -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

297
source/namework.doc Normal file
View File

@ -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.