tidied up: code shuffling and documentation.
[samba.git] / source / nameresp.doc
1 the netbios expected response code is a key part of samba's NetBIOS
2 handling capabilities. it allows samba to carry on dealing with
3 other things while expecting a response from one or more hosts.
4
5 this allows samba to simultaneously deal with registering its names
6 with another WINS server, register its names on its local subnets,
7 query any hosts that have registered with samba in its capacity as
8 a WINS server, and at a later date it will be also be able handle
9 END-NODE CHALLENGES (see rfc1001.txt 15.2.2.2 and 15.2.2.3 - secured
10 NBNS functionality).
11
12 all at once!
13
14 when a netbios packet is sent out by samba and it expects a response,
15 a record of all the relevant information is kept (most importantly,
16 the unique transaction id associated which will come back to us in
17 a response packet is recorded, and also recorded is the reason that
18 the original packet was sent out by samba in the first place!).
19
20 if a response is received, then the unique transaction identifier 
21 returned in the response packet is searched for in the expected
22 response records. the record indicates why the initial request was
23 made (and therefore the type of response can be verified) and
24 appropriate action can be taken.
25
26 when no responses, after a number of retries, are not received, then
27 samba may take appropriate action. this is a crucial part of samba's
28 operation: for a key number of NetBIOS operations, no response is an
29 implicit positive response.
30
31 module nameresp deals with the initial transmission, re-transmission
32 and time-out of netbios response records.
33
34 module namedbresp deals with the maintenance of the list of expected
35 responses - creation, finding and removal.
36
37
38 /*************************************************************************
39   queue_netbios_packet()
40   *************************************************************************/
41
42 this function is responsible for sending out a netbios packet, and then
43 making a record of the information that was sent out. a response will
44 be expected later (or not, as the case may be).
45
46 if a response is received, response_netbios_packet() will deal with it.
47 otherwise, it will be dealt with in expire_netbios_response_entries().
48
49
50 /*************************************************************************
51   queue_netbios_pkt_wins()
52   *************************************************************************/
53
54 this function is a wrapper around queue_netbios_packet(). there is
55 some confusion about B, M and P nodes (see rfc1001.txt section 10) -
56 confusion introduced by luke :-) - which needs sorting out.
57
58 for example, rfc1001.txt 15.2.3 - an M node must attempt to register a
59 name first as a B node, then attempt to register as an M node. negative
60 responses on either of these attempts is a failure to register the
61 name.
62
63 this is NOT the case with a P node.
64
65
66 /*************************************************************************
67   expire_netbios_response_entries()
68   *************************************************************************/
69
70 this function is responsible for dealing with queued response records
71 that have not received a response packet matching their unique
72 transaction id.
73
74 if the retry count for any record is non-zero, and its time-out period
75 has expired, the retry count is reduced, the time-out period is stepped
76 forward and the packet is re-transmitted (from the information stored
77 in the queued response record) with the same unique transaction id of
78 the initial attempt at soliciting a response.
79
80 if the retry count is zero, then the packet is assumed to have expired.
81 dead_netbios_entry() is called to deal with the possibility of an error
82 or a problem (or in certain instances, no answer is an implicit
83 positive response!).
84
85 the expected response record is then deleted, and the number of expected
86 responses reduced. when this count gets to zero, listen_for_packets()
87 will no longer time-out for 1 second on account of expecting response
88 packets.
89
90
91 /*************************************************************************
92   dead_netbios_entry()
93   *************************************************************************/
94
95 this function is responsible for dealing with the case when a NetBIOS
96 response to a packet sent out by samba was not received. for certain
97 transactions, this may be normal. for others, under certain conditions
98 it may constitute either an error or a problem with or failure of one
99 or more hosts.
100
101 - NAME_QUERY_CONFIRM
102
103 when a samba 'state' of type NAME_QUERY_CONFIRM is sent, a response
104 may or may not be forthcoming. if no response is received to a unique
105 name, then the record is removed from samba's WINS database. non-unique
106 names are simply expected to die off on a time-to-live basis (see
107 rfc1001.txt 15.1.3.4)
108
109 query_refresh_names() issues this samba 'state'
110 response_name_query_sync() deals with responses to NAME_QUERY_CONFIRM.
111
112 - NAME_QUERY_MST_CHK
113
114 when a samba 'state' of type NAME_QUERY_MST_CHK is sent, and a response
115 is not received, this implies that a master browser will have failed.
116 remedial action may need to be taken, for example if samba is a member
117 of that workgroup and it is also a potential master browser it could
118 force an election.
119
120 check_master_browser() issues this samba 'state'.
121 response_process() does nothing if a response is received. this is normal.
122
123 - NAME_RELEASE
124
125 when a samba 'state' of type NAME_RELEASE is sent, and a response is
126 not received, it is assumed to be acceptable to release the name. if the
127 original response was sent to another WINS server, then that WINS server
128 may be inaccessible or may have failed. if so, then at a later date
129 samba should take this into account (see rfc1001.txt 10.3).
130
131 remove_name_entry() issues this samba 'state'
132 response_name_rel() deals with responses to NAME_RELEASE.
133
134 - NAME_REGISTER_CHALLENGE
135
136 when a samba 'state' of type NAME_REGISTER_CHALLENGE is sent, and a
137 response is not received, it is assumed that the server being queried
138 is either dead, deaf or unreachable. the host that wanted this
139 unique name is then informed that it can have it (the name query
140 challenge went unanswered) and that its registration of this name
141 did in fact succeed.
142
143 reply_name_reg() issues this samba 'state'
144 response_name_query_register() deals with responses.
145
146 - NAME_REGISTER
147
148 when a samba 'state' of type NAME_REGISTER is sent, and a response is
149 not received, if the registration was done by broadcast, it is assumed
150 that there are no objections to the registration of this name, and samba
151 adds the name to the appropriate subnet record name database. if the
152 registration was point-to-point (i.e with another WINS server) then that
153 WINS server may be inaccessible or may have failed. if so, then at a later
154 date samba should take this into account (see rfc1001.txt 10.3).
155
156 add_my_name_entry() issues this samba 'state'
157 response_name_reg() deals with responses to NAME_REGISTER.
158
159 no action is taken for any other kinds of samba 'states' if a response
160 is not received. this is not to say that action may not be appropriate,
161 just that it's not been looked at yet :-)
162
163