3d4bc3c3484b789c99c0d97b742bd5b6d3bee4cf
[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 this allows samba to simultaneously deal with registering its names
5 with another WINS server, register its names on its local subnets,
6 query any hosts that have registered with samba in its capacity as
7 a WINS server, and at a later date it will be also be able handle
8 END-NODE CHALLENGES (see rfc1001.txt 15.2.2.2 and 15.2.2.3 - secured
9 NBNS functionality). all at once!
10
11 when a netbios packet is sent out by samba and it expects a response,
12 a record of all the relevant information is kept (most importantly,
13 the unique transaction id associated which will come back to us in
14 a response packet is recorded, and also recorded is the reason that
15 the original packet was sent out by samba in the first place!).
16
17 if a response is received, then the unique transaction identifier 
18 returned in the response packet is searched for in the expected
19 response records. the record indicates why the initial request was
20 made (and therefore the type of response can be verified) and
21 appropriate action can be taken.
22
23 when no responses, after a number of retries, are not received, then
24 samba may take appropriate action.
25
26 nameresp.c deals with the maintenance of the netbios response records:
27 their creation, retransmission, and eventual removal.
28
29
30 /*************************************************************************
31   send_mailslot_reply()
32   *************************************************************************/
33
34 this function is responsible for sending a MAILSLOT packet.
35
36 it will _not_ send packets to the pseudo WINS subnet's address of 
37 255.255.255.255: this would be disastrous.
38
39 each packet sent out has a unique transaction identifier. this is done
40 so that responses can be matched with the original purpose for the packet
41 being sent out in the first place.
42
43
44 /*************************************************************************
45   interpret_node_status()
46   *************************************************************************/
47
48 this function is responsible for interpreting the raw data that comes in
49 from a node status reply. in the process, it identifies both the server
50 name and the workgroup name in the node status reply.
51
52 it also updates information in the WINS name database if the names 
53 received are not already in samba's records.
54
55
56 /*************************************************************************
57   listen_for_packets()
58   *************************************************************************/
59
60 this function is responsible for reading NMB and DGRAM packets, and then
61 queueing them. it will normally time-out for NMBD_SELECT_LOOP seconds, but
62 if there is an election currently running or we are expecting a response
63 then this time is reduced to 1 second.
64
65 note: the time-out period needs refining to the millisecond level.
66
67
68 /*************************************************************************
69   queue_packet()
70   *************************************************************************/
71
72 this function is responsible for queueing any NMB and DGRAM packets passed
73 to it. these packets will be removed from the queue in run_packet_queue().
74
75
76 /*************************************************************************
77   run_packet_queue()
78   *************************************************************************/
79
80 this function is responsible for taking a packet off the queue, 
81 identifying whether it is an NMB or a DGRAM packet, processing
82 it accordingly and deleting it. this process continues until
83 there are no more packets on the queue.
84
85
86 /*************************************************************************
87   find_response_record()
88   *************************************************************************/
89
90 this function is responsible for matching the unique response transaction
91 id with an expected response record. as a side-effect of this search,
92 it will find the subnet (or the WINS pseudo-subnet) that samba expected
93 the response to come from.
94
95
96 /*************************************************************************
97   queue_netbios_packet()
98   *************************************************************************/
99
100 this function is responsible for sending out a netbios packet, and then
101 making a record of the information that was sent out. a response will
102 be expected later (or not, as the case may be).
103
104 if a response is received, response_netbios_packet() will deal with it.
105 otherwise, it will be dealt with in expire_netbios_response_entries().
106
107
108 /*************************************************************************
109   make_response_queue_record()
110   *************************************************************************/
111
112 this function is responsible for creating a response record, which will
113 be queued awaiting a response.
114
115 the number of retries is set to 4, and the retry period set to 1 second.
116 if no response is received, then the packet is re-transmitted, which is
117 why so much information is stored in the response record.
118
119 the number of expected responses queued is kept, so listen_for_packets()
120 knows it must time-out after 1 second if one or more responses are
121 expected.
122
123
124 /*************************************************************************
125   queue_netbios_pkt_wins()
126   *************************************************************************/
127
128 this function is a wrapper around queue_netbios_packet(). there is
129 some confusion about B, M and P nodes (see rfc1001.txt section 10) -
130 confusion introduced by luke :-) - which needs sorting out.
131
132 for example, rfc1001.txt 15.2.3 - an M node must attempt to register a
133 name first as a B node, then attempt to register as an M node. negative
134 responses on either of these attempts is a failure to register the
135 name.
136
137 this is NOT the case with a P node.
138
139
140 /*************************************************************************
141   reply_netbios_packet()
142   *************************************************************************/
143
144 this function is responsible for sending a reply to another NetBIOS
145 packet from another host. it can be used to send a reply to a name
146 registration, name release, name query or name status request.
147
148 the reply can be either a positive or a negative one.
149
150
151 /*************************************************************************
152   expire_netbios_response_entries()
153   *************************************************************************/
154
155 this function is responsible for dealing with queued response records
156 that have not received a response packet matching their unique
157 transaction id.
158
159 if the retry count for any record is non-zero, and its time-out period
160 has expired, the retry count is reduced, the time-out period is stepped
161 forward and the packet is re-transmitted (from the information stored
162 in the queued response record) with the same unique transaction id of
163 the initial attempt at soliciting a response.
164
165 if the retry count is zero, then the packet is assumed to have expired.
166 dead_netbios_entry() is called to deal with the possibility of an error
167 or a problem (or in certain instances, no answer is an implicit
168 positive response!).
169
170 the expected response record is then deleted, and the number of expected
171 responses reduced. when this count gets to zero, listen_for_packets()
172 will no longer time-out for 1 second on account of expecting response
173 packets.
174
175
176 /*************************************************************************
177   initiate_netbios_packet()
178   *************************************************************************/
179
180 this function is responsible for construction a netbios packet and sending
181 it. if the packet has not had a unique transaction id allocated to it,
182 then initiate_netbios_packet() will give it one.
183
184
185 /*************************************************************************
186   dead_netbios_entry()
187   *************************************************************************/
188
189 this function is responsible for dealing with the case when a NetBIOS
190 response to a packet sent out by samba was not received. for certain
191 transactions, this may be normal. for others, under certain conditions
192 it may constitute either an error or a problem with or failure of one
193 or more hosts.
194
195 - NAME_QUERY_CONFIRM
196
197 when a samba 'state' of type NAME_QUERY_CONFIRM is sent, a response
198 may or may not be forthcoming. if no response is received to a unique
199 name, then the record is removed from samba's WINS database. non-unique
200 names are simply expected to die off on a time-to-live basis (see
201 rfc1001.txt 15.1.3.4)
202
203 query_refresh_names() issues this samba 'state'
204 response_name_query_sync() deals with responses to NAME_QUERY_CONFIRM.
205
206 - NAME_QUERY_MST_CHK
207
208 when a samba 'state' of type NAME_QUERY_MST_CHK is sent, and a response
209 is not received, this implies that a master browser will have failed.
210 remedial action may need to be taken, for example if samba is a member
211 of that workgroup and it is also a potential master browser it could
212 force an election.
213
214 check_master_browser() issues this samba 'state'.
215 response_process() does nothing if a response is received. this is normal.
216
217 - NAME_RELEASE
218
219 when a samba 'state' of type NAME_RELEASE is sent, and a response is
220 not received, it is assumed to be acceptable to release the name. if the
221 original response was sent to another WINS server, then that WINS server
222 may be inaccessible or may have failed. if so, then at a later date
223 samba should take this into account (see rfc1001.txt 10.3).
224
225 remove_name_entry() issues this samba 'state'
226 response_name_rel() deals with responses to NAME_RELEASE.
227
228 - NAME_REGISTER
229
230 when a samba 'state' of type NAME_REGISTER is sent, and a response is
231 not received, if the registration was done by broadcast, it is assumed
232 that there are no objections to the registration of this name, and samba
233 adds the name to the appropriate subnet record name database. if the
234 registration was point-to-point (i.e with another WINS server) then that
235 WINS server may be inaccessible or may have failed. if so, then at a later
236 date samba should take this into account (see rfc1001.txt 10.3).
237
238 add_my_name_entry() issues this samba 'state'
239 response_name_reg() deals with responses to NAME_REGISTER.
240
241 no action is taken for any other kinds of samba 'states' if a response
242 is not received. this is not to say that action may not be appropriate,
243 just that it's not been looked at yet :-)
244
245
246 /*************************************************************************
247   add_response_record()
248   *************************************************************************/
249
250 this function is responsible for adding the response record created by
251 make_response_queue_record() into the appropriate response record queue.
252
253
254 /*************************************************************************
255   update_name_trn_id()
256   *************************************************************************/
257
258 this function is responsible for allocating unique transaction identifiers
259 for each new packet sent on the network.
260
261