first draft of low-level design documents describing the operation of
[samba.git] / source / nameserv.doc
1 /*************************************************************************
2   process_nmb()
3   *************************************************************************/
4
5 this function receives a packet identified as a netbios packet.
6 it further identifies whether it is a response or a query packet.
7 by identifying the type of packet (name registration, query etc)
8 process_nmb() will call the appropriate function to deal with the
9 type of packet received.
10
11
12 /*************************************************************************
13   response_netbios_packet()
14   *************************************************************************/
15
16 this function received netbios response packets. the samba server
17 (or a rogue tcp/ip system, or nmblookup) will have sent out a packet
18 requesting a response. a client (or a rogue tcp/ip system) responds
19 to that request.
20
21 this function checks the validity of the packet it receives.
22 the expected response records are searched for the transaction id,
23 to see if it's a response expected by the samba server. if it isn't
24 it's reported as such, and ignored.
25
26 if the response is found, then the subnet it was expected from will
27 also have been found. the subnet it actually came in on can be
28 checked against the subnet it was expected from and reported,
29 otherwise this function just carries on.
30
31 the number of responses received is increased, and the number of
32 retries left to be sent is set to zero.
33
34 after debug information is reported, and validation of the netbios
35 packet (e.g only one response from one machine is expected for some
36 functions) has occurred, the packet is processed. when the initial
37 request was sent out, the expected response record was flagged with,
38 for lack of a better word, a samba 'command' type. whenever a
39 response is received, the appropriate function is called to carry on
40 where the program control flow was interrupted while awaiting exactly
41 such a response.
42
43 please note that _not_ receiving a response is dealt with in another
44 area of code - expire_netbios_response_entries().
45
46
47 /*************************************************************************
48   response_name_query_sync()
49   *************************************************************************/
50
51 this function receives responses to samba 'commands' NAME_QUERY_SYNC and
52 NAME_QUERY_CONFIRM.
53
54 NAME_QUERY_SYNC: name query a server before synchronising browse lists.
55 NAME_QUERY_CONFIRM: name query a server to check that it's alive.
56
57 a NAME_QUERY_SYNC will be carried out in order to check that a server
58 is alive before syncing browse lists. we don't want to delay the SMB
59 NetServerEnum api just because the server has gone down: we have too
60 much else to do.
61
62 a NAME_QUERY_CONFIRM is just a name query to see whether the server is
63 alive.  these queries are sent out by samba's WINS server side, to verify
64 its netbios name database of all machines that have registered with it.
65
66 we don't normally expect a negative response from such a query, although
67 we may do so if the query was sent to another WINS server. the registered
68 entry should be removed if we receive a negative response.
69
70
71 /*************************************************************************
72   response_name_status_check()
73   *************************************************************************/
74
75 this function receives responses to samba 'commands' NAME_STATUS_CHECK
76 and NAME_STATUS_MASTER_CHECK
77
78 NAME_STATUS_MASTER_CHECK: name status a primary domain controller, 
79                           confirm its domain and then initiate syncing
80                           its browse list.
81
82 NAME_STATUS_CHECK: same as NAME_STATUS_MASTER_CHECK except the name status
83                    is issued to a master browser.
84
85 if we don't know what workgroup a server is responsible for, but we
86 know that there is a master browser at a certain ip, we can issue a
87 name status check. from the response received, there will be
88 a master browser netbios entry. this will allow us to synchronise
89 browse lists with that machine and then add the information to the
90 correct part of samba's workgroup - server database.
91
92
93 /*************************************************************************
94   response_server_check()
95   *************************************************************************/
96
97 this function receives responses to samba 'commands' NAME_QUERY_MST_SRV_CHK,
98 NAME_QUERY_SRV_CHK and NAME_QUERY_FIND_MST.
99
100 NAME_QUERY_FIND_MST: issued as a broadcast when we wish to find out all
101                      master browsers (i.e all servers that have registered
102                      the NetBIOS name ^1^2__MSBROWSE__^2(0x1), and then
103                      issue a NAME_STATUS_MASTER_CHECK on any servers that
104                      respond, which will initiate a sync browse lists.
105
106 NAME_QUERY_MST_SRV_CHK: same as a NAME_QUERY_FIND_MST except this is sent
107                         to a primary domain controller.
108
109 NAME_QUERY_SRV_CHK: same as a NAME_QUERY_MST_SRV_CHK except this is sent to
110                     a master browser.
111                         
112 the purpose of each of these commands is to do a broadcast name query, or
113 a name query directed at a WINS server, then to all hosts that respond,
114 we issue a name status check, which will confirm for us the workgroup
115 or domain name, and then initiate issuing a sync browse list call with
116 that server.
117
118
119 /*************************************************************************
120   reply_name_query()
121   *************************************************************************/
122
123 this function is responsible for replying to a NetBIOS name query.
124
125 there are two kinds of name queries: directed, and broadcast. directed
126 queries are usually sent to samba in its WINS capacity. such hosts are
127 termed 'point-to-point' hosts. broadcast queries are usually sent from
128 'broadcast' or 'mixed' hosts.
129
130 broadcasting is used by either older NetBIOS hosts, new NetBIOS hosts that
131 have not had WINS capabilities added and new NetBIOS hosts that think the
132 WINS server has died.
133
134 the samba NetBIOS name database is divided into sections, on a
135 per-subnet basis. there is also a WINS NetBIOS name database, and for
136 convenience this is added as a pseudo-subnet with the ip address of
137 255.255.255.255.
138
139 the local subnet NetBIOS name databases only contain samba's names.
140 the reason for this is that if a broadcast query is received, a NetBIOS
141 hosts is only expected to respond if that query is for one of its own
142 names (the exception to this is if a host is configured as a 'proxy'
143 server, in which case, samba should redirect the query to another WINS
144 server).
145
146 the WINS pseudo-subnet NetBIOS database contains all NetBIOS names
147 that are not 'special browser' type names (regarding this i am a
148 _bit_ confused :-). names of type 0x01, 0x1d and 0x1e i consider to
149 be 'special browser' names. at the moment. maybe.
150
151 the type of search to be initiated is determined. if the NetBIOS name
152 type is a non-special-browser name, then the WINS database is included
153 in the search.
154
155 if the name is not a special browser name, then we need to find the
156 right subnet that the query came from. this is done using
157 find_req_subnet(). this also has the benefit of stopping any queries
158 from subnets that samba does not know about.
159
160 if the query is a broadcast query, then the database of the local subnet
161 is included in the search.
162
163 the name is then searched for in the appropriate NetBIOS data structures.
164 if it is found, then we need to check whether it is appropriate for us
165 to reply to such a query.
166
167 we will only reply if the query is a directed query, the name belongs to
168 samba on that subnet, or the name is a primary domain controller type,
169 or we're doing replies on behalf of hosts on subnets not known to the
170 host issuing the query. in the latter instance, it would be appropriate
171 if samba is using a WINS server for it to forward the name query on to
172 this WINS server.
173
174 reply_name_query() then takes note of all the information that is
175 needed to construct a reply to the caller. a negative reply (if the
176 name is unknown to samba) or a positive reply (the name is known to
177 samba) is then issued.
178
179
180 /*************************************************************************
181   search_for_name()
182   *************************************************************************/
183
184 this function is responsible for finding a name in the appropriate part
185 of samba's NetBIOS name database. if the name cannot be found, then it
186 should look the name up using DNS. later modifications will be to
187 forward the request on to another WINS server, should samba not be able
188 to find out about the requested name (this will be implemented through
189 issuing a new type of samba 'command').
190
191 the name is first searched for in the NetBIOS cache. if it cannot be
192 found, then it if the name looks like it's a server-type name (0x20
193 0x0 or 0x1b) then DNS is used to look for the name.
194
195 if DNS fails, then a record of this failure is kept. if it succeeds, then
196 a new NetBIOS entry is added.
197
198 the successfully found name is returned. on failure, NULL is returned.
199
200
201 /*************************************************************************
202   reply_name_status()
203   *************************************************************************/
204
205 this function is responsible for constructing a reply to a NetBIOS
206 name status query. this response contains all samba's NetBIOS names
207 on the subnet that the query came in from.
208
209 a reply will only be made if the NetBIOS name being queried exists.
210
211 see rfc1001.txt and rfc1002.txt for details of the name status reply.
212
213
214 /*************************************************************************
215   reply_name_reg()
216   *************************************************************************/
217
218 this function is responsible for updating the NetBIOS name database
219 from registration packets sent out by hosts wishing to register a
220 name, and for informing them, if necessary, if this is acceptable
221 or not.
222
223 name registration can be done by broadcast or by point-to-point,
224 i.e the registration is sent directly to samba in its capacity as
225 a WINS server.
226
227 if the name registration is done by broadcast (see rfc1001.txt 15.2.1),
228 then samba's involvement in replying is limited to whether that name
229 is owned by samba or not, on the relevant subnet.
230
231 if the name registration is done point-to-point (see rfc1001.txt 15.2.2)
232 then samba will first need to check its WINS name database records and
233 proceed accordingly.
234
235 samba looks for the appropriate subnet record that the registration
236 should be added to / checked against, using find_req_subnet().
237
238 next, the name is searched for in the local database or the WINS
239 database as appropriate.
240
241 if the name is not found, then it is added to the NetBIOS name database,
242 using add_netbios_entry(), which may choose not to add the name (not
243 that this affects the registration of the name on the network in any way).
244 it will only add names to the WINS database, and even then it will only
245 add non-special-browser type names.
246
247 if the name is found, then samba must decide whether to accept the name
248 or not. a group name is always added. for unique names, further checks
249 need to be carried out.
250
251 firstly, if the name in the database is one of samba's names, or if the
252 name in the database is a group name, then it cannot be added as a unique
253 name belonging to someone else. it is therefore rejected.
254
255 secondly, if the ip address of the name being registered does not match
256 against the ip in the database, then the unique name may belong to
257 someone else. a check needs to be carried out with the owner in case
258 they still wish to keep this name. a detailed discussion of what action
259 to take is in rfc1001.txt 15.2.2.2 and 15.2.2.3.
260
261 samba currently implements non-secured WINS, whereupon the responsibility
262 for checking the name is passed on to the host doing the registration.
263 rfc1001.txt refers to this as an END-NODE CHALLENGE REGISTRATION RESPONSE.
264 (samba itself cannot yet cope with receiving such responses if it
265 registers its names with another WINS server). 
266
267 having decided what kind of response to send (if any - acceptance of
268 name registrations by broadcast is implicit), samba will send either a
269 positive or negative NAME REGISTRATION RESPONSE, or an END-NODE CHALLENGE
270 REGISTRATION RESPONSE to the host that initially sent the registration.
271
272 whew.
273
274
275 /*************************************************************************
276   response_name_reg()
277   *************************************************************************/
278
279 this function is responsible for dealing with samba's registration
280 attempts, by broadcast to a local subnet, or point-to-point with 
281 another WINS server.
282
283 please note that it cannot cope with END-NODE CHALLENGE REGISTRATION
284 RESPONSEs at present.
285
286 when a response is received, samba determines if the response is a
287 positive or a negative one. if it is a positive response, the name
288 is added to samba's database.
289
290 when a negative response is received, samba will remove the name
291 from its database. if, however, the name is a browser type (0x1b is
292 a primary domain controller type name; or 0x1d, which is a master
293 browser type name) then it must also stop being a primary domain
294 controller or master browser respectively, depending on what kind
295 of name was rejected.
296
297 (when no response is received, then expire_netbios_response_entries()
298 is expected to deal with this. the only case that is dealt with here
299 at present is when the registration was done by broadcast. if there
300 is no challenge to the broadcast registration, it is implicitly
301 assumed that claiming the name is acceptable).
302
303
304 /*************************************************************************
305   response_name_release()
306   *************************************************************************/
307
308 this function is responsible for removing samba's NetBIOS name when
309 samba contacts another WINS server with which it had registered the
310 name.
311
312 only positive name releases are expected and dealt with. exactly what
313 to do if a negative name release (i.e someone says 'oi! you have to
314 keep that name!') is received is uncertain.
315
316 (when no response is received, then expire_netbios_response_entries()
317 is expected to deal with this. if there is no challenge to the release
318 of the name, the name is then removed from that subnet's NetBIOS
319 name database).
320
321
322 /*************************************************************************
323   expire_names()
324   *************************************************************************/
325
326 this function is responsible for removing old NetBIOS names from its
327 database. no further action is required.
328
329 for over-zealous WINS systems, the use of query_refresh_names() is
330 recommended. this function initiates polling of hosts that have
331 registered with samba in its capacity as a WINS server. an alternative
332 means to achieve the same end as query_refresh_names() is to
333 reduce the time to live when the name is registered with samba,
334 except that in this instance the responsibility for refreshing the
335 name is with the owner of the name, not the server with which the name
336 is registered. 
337
338
339 /*************************************************************************
340   query_refresh_names()
341   *************************************************************************/
342
343 this function is responsible for polling all names registered in the
344 WINS database. it is planned to enable this function should samba
345 detect an inconsistency on the network, which could occur if the
346 samba NetBIOS daemon dies and is restarted.
347
348 polling is done very infrequently, but all names will be covered
349 within a period NAME_POLL_REFRESH_TIME. a group of at most ten names
350 will be queried at once, at intervals of NAME_POLL_INTERVAL seconds.
351 if the total number of names queried in this way will take too long,
352 then the time that an individual name will next be polled is
353 increased accordingly.
354
355 name query polling is functionality over-and-above the normal
356 requirement (see rfc1001.txt 15.1.7 point 7). it is normally the
357 responsibility of the owner of a name to re-register the name at
358 regular intervals.
359
360
361 /*************************************************************************
362   refresh_my_names()
363   *************************************************************************/
364
365 this function is responsible for refreshing samba's names that have
366 been registered with other servers on a local subnet, or with another
367 WINS server if samba is using one.
368
369 samba's names' refresh_time will be updated through the use of the function
370 add_my_name_entry().
371
372
373 /*************************************************************************
374   remove_my_names()
375   *************************************************************************/
376
377 this function is responsible for removing all samba's SELF names. it
378 is used when samba receives a SIG_TERM. samba at present does not wait
379 for the WINS server to reply to the name releases sent out.
380
381
382 /*************************************************************************
383   add_my_names()
384   *************************************************************************/
385
386 this function is responsible for adding and registering if necessary all
387 samba's SELF names, on each of its local subnets and with another WINS
388 server if samba is using one.
389
390 /*************************************************************************
391   add_my_name_entry()
392   *************************************************************************/
393
394 this function is responsible for registering or re-registering one of
395 samba's names, either on the local subnet or with another WINS server
396 if samba is using one.
397
398 if the name is already in samba's database, then it is re-registered,
399 otherwise it is simply registered.
400
401 if samba registers its name with another WINS server, then the function
402 response_name_reg() is responsible for updating samba's name database
403 to reflect the claim or otherwise of the name.
404
405 expire_netbios_response_entries() is responsible for taking further action
406 if no response to the registration is received.
407
408
409 /*************************************************************************
410   remove_name_entry()
411   *************************************************************************/
412
413 this function is responsible for removing a NetBIOS name. if the name
414 being removed is registered on a local subnet, a name release should be
415 broadcast on the local subnet.
416
417 if samba has registered the name with a WINS server, it must send a 
418 name release to the WINS server it is using. once it receives a reply,
419 it can proceed (see response_name_rel())
420
421 expire_netbios_response_entries() is responsible for taking further action
422 if no response to the name release is received.
423
424
425 /*************************************************************************
426   load_netbios_names()
427   *************************************************************************/
428
429 this function is responsible for loading any NetBIOS names that samba,
430 in its WINS capacity, has written out to disk. all the relevant details
431 are recorded in this file, including the time-to-live. should the 
432 time left to live be small, the name is not added back in to samba's
433 WINS database.
434
435  
436 /*************************************************************************
437   dump_names()
438   *************************************************************************/
439
440 this function is responsible for outputting NetBIOS names in two formats.
441 firstly, as debugging information, and secondly, all names that have been
442 registered with samba in its capacity as a WINS server are written to
443 disk.
444
445 writing all WINS names allows two things. firstly, if samba's NetBIOS
446 daemon dies or is terminated, on restarting the daemon most if not all
447 of the registered WINS names will be preserved (which is a good reason
448 why query_netbios_names() should be used).
449  
450
451 /*************************************************************************
452   find_name_search()
453   *************************************************************************/
454
455 this function is a wrapper around find_name(). find_name_search() can
456 be told whether to search for the name in a local subnet structure or
457 in the WINS database. on top of this, it can be told to search only
458 for samba's SELF names.
459
460 if it finds the name in the WINS database, it will set the subnet_record
461 and also return the name it finds.
462  
463
464 /*************************************************************************
465   find_req_subnet()
466   *************************************************************************/
467
468 this function is responsible for finding the appropriate subnet record
469 to use. it is assumed that any directed packets are going to need to
470 use the WINS pseudo-subnet records, and that any broadcast transactions
471 received are going to need to use a local subnet record, which is found
472 from the ip address that the transaction was received on.
473
474 a side-effect of this function is that any broadcast packet received
475 on a subnet not known to samba is ignored.
476