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 'state' 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 'states' 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 'states' 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 'states' 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 states 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 a NAME_QUERY_SRV_CHK is sent when samba receives a list of backup
 119 browsers. it checks to see if that server is alive (by doing a
 120 name query on a server) and then syncs browse lists with it.
 121
 122
 123 /*************************************************************************
 124   reply_name_query()
 125   *************************************************************************/
 126
 127 this function is responsible for replying to a NetBIOS name query.
 128
 129 there are two kinds of name queries: directed, and broadcast. directed
 130 queries are usually sent to samba in its WINS capacity. such hosts are
 131 termed 'point-to-point' hosts. broadcast queries are usually sent from
 132 'broadcast' or 'mixed' hosts.
 133
 134 broadcasting is used by either older NetBIOS hosts, new NetBIOS hosts that
 135 have not had WINS capabilities added and new NetBIOS hosts that think the
 136 WINS server has died.
 137
 138 the samba NetBIOS name database is divided into sections, on a
 139 per-subnet basis. there is also a WINS NetBIOS name database, and for
 140 convenience this is added as a pseudo-subnet with the ip address of
 141 255.255.255.255.
 142
 143 the local subnet NetBIOS name databases only contain samba's names.
 144 the reason for this is that if a broadcast query is received, a NetBIOS
 145 hosts is only expected to respond if that query is for one of its own
 146 names (the exception to this is if a host is configured as a 'proxy'
 147 server, in which case, samba should redirect the query to another WINS
 148 server).
 149
 150 the WINS pseudo-subnet NetBIOS database contains all NetBIOS names
 151 that are not 'special browser' type names (regarding this i am a
 152 _bit_ confused :-). names of type 0x01, 0x1d and 0x1e i consider to
 153 be 'special browser' names. at the moment. maybe.
 154
 155 the type of search to be initiated is determined. if the NetBIOS name
 156 type is a non-special-browser name, then the WINS database is included
 157 in the search.
 158
 159 if the name is not a special browser name, then we need to find the
 160 right subnet that the query came from. this is done using
 161 find_req_subnet(). this also has the benefit of stopping any queries
 162 from subnets that samba does not know about.
 163
 164 if the query is a broadcast query, then the database of the local subnet
 165 is included in the search.
 166
 167 the name is then searched for in the appropriate NetBIOS data structures.
 168 if it is found, then we need to check whether it is appropriate for us
 169 to reply to such a query.
 170
 171 we will only reply if the query is a directed query, the name belongs to
 172 samba on that subnet, or the name is a primary domain controller type,
 173 or we're doing replies on behalf of hosts on subnets not known to the
 174 host issuing the query. in the latter instance, it would be appropriate
 175 if samba is using a WINS server for it to forward the name query on to
 176 this WINS server.
 177
 178 reply_name_query() then takes note of all the information that is
 179 needed to construct a reply to the caller. a negative reply (if the
 180 name is unknown to samba) or a positive reply (the name is known to
 181 samba) is then issued.
 182
 183
 184 /*************************************************************************
 185   search_for_name()
 186   *************************************************************************/
 187
 188 this function is responsible for finding a name in the appropriate part
 189 of samba's NetBIOS name database. if the name cannot be found, then it
 190 should look the name up using DNS. later modifications will be to
 191 forward the request on to another WINS server, should samba not be able
 192 to find out about the requested name (this will be implemented through
 193 issuing a new type of samba 'state').
 194
 195 the name is first searched for in the NetBIOS cache. if it cannot be
 196 found, then it if the name looks like it's a server-type name (0x20
 197 0x0 or 0x1b) then DNS is used to look for the name.
 198
 199 if DNS fails, then a record of this failure is kept. if it succeeds, then
 200 a new NetBIOS entry is added.
 201
 202 the successfully found name is returned. on failure, NULL is returned.
 203
 204
 205 /*************************************************************************
 206   reply_name_status()
 207   *************************************************************************/
 208
 209 this function is responsible for constructing a reply to a NetBIOS
 210 name status query. this response contains all samba's NetBIOS names
 211 on the subnet that the query came in from.
 212
 213 a reply will only be made if the NetBIOS name being queried exists.
 214
 215 see rfc1001.txt and rfc1002.txt for details of the name status reply.
 216
 217
 218 /*************************************************************************
 219   reply_name_reg()
 220   *************************************************************************/
 221
 222 this function is responsible for updating the NetBIOS name database
 223 from registration packets sent out by hosts wishing to register a
 224 name, and for informing them, if necessary, if this is acceptable
 225 or not.
 226
 227 name registration can be done by broadcast or by point-to-point,
 228 i.e the registration is sent directly to samba in its capacity as
 229 a WINS server.
 230
 231 if the name registration is done by broadcast (see rfc1001.txt 15.2.1),
 232 then samba's involvement in replying is limited to whether that name
 233 is owned by samba or not, on the relevant subnet.
 234
 235 if the name registration is done point-to-point (see rfc1001.txt 15.2.2)
 236 then samba will first need to check its WINS name database records and
 237 proceed accordingly.
 238
 239 samba looks for the appropriate subnet record that the registration
 240 should be added to / checked against, using find_req_subnet().
 241
 242 next, the name is searched for in the local database or the WINS
 243 database as appropriate.
 244
 245 if the name is not found, then it is added to the NetBIOS name database,
 246 using add_netbios_entry(), which may choose not to add the name (not
 247 that this affects the registration of the name on the network in any way).
 248 it will only add names to the WINS database, and even then it will only
 249 add non-special-browser type names.
 250
 251 if the name is found, then samba must decide whether to accept the name
 252 or not. a group name is always added. for unique names, further checks
 253 need to be carried out.
 254
 255 firstly, if the name in the database is one of samba's names, or if the
 256 name in the database is a group name, then it cannot be added as a unique
 257 name belonging to someone else. it is therefore rejected.
 258
 259 secondly, if the ip address of the name being registered does not match
 260 against the ip in the database, then the unique name may belong to
 261 someone else. a check needs to be carried out with the owner in case
 262 they still wish to keep this name. a detailed discussion of what action
 263 to take is in rfc1001.txt 15.2.2.2 and 15.2.2.3.
 264
 265 samba currently implements non-secured WINS, whereupon the responsibility
 266 for checking the name is passed on to the host doing the registration.
 267 rfc1001.txt refers to this as an END-NODE CHALLENGE REGISTRATION RESPONSE.
 268 (samba itself cannot yet cope with receiving such responses if it
 269 registers its names with another WINS server).
 270
 271 having decided what kind of response to send (if any - acceptance of
 272 name registrations by broadcast is implicit), samba will send either a
 273 positive or negative NAME REGISTRATION RESPONSE, or an END-NODE CHALLENGE
 274 REGISTRATION RESPONSE to the host that initially sent the registration.
 275
 276 whew.
 277
 278
 279 /*************************************************************************
 280   response_name_reg()
 281   *************************************************************************/
 282
 283 this function is responsible for dealing with samba's registration
 284 attempts, by broadcast to a local subnet, or point-to-point with
 285 another WINS server.
 286
 287 please note that it cannot cope with END-NODE CHALLENGE REGISTRATION
 288 RESPONSEs at present.
 289
 290 when a response is received, samba determines if the response is a
 291 positive or a negative one. if it is a positive response, the name
 292 is added to samba's database.
 293
 294 when a negative response is received, samba will remove the name
 295 from its database. if, however, the name is a browser type (0x1b is
 296 a primary domain controller type name; or 0x1d, which is a master
 297 browser type name) then it must also stop being a primary domain
 298 controller or master browser respectively, depending on what kind
 299 of name was rejected.
 300
 301 (when no response is received, then expire_netbios_response_entries()
 302 is expected to deal with this. the only case that is dealt with here
 303 at present is when the registration was done by broadcast. if there
 304 is no challenge to the broadcast registration, it is implicitly
 305 assumed that claiming the name is acceptable).
 306
 307
 308 /*************************************************************************
 309   response_name_release()
 310   *************************************************************************/
 311
 312 this function is responsible for removing samba's NetBIOS name when
 313 samba contacts another WINS server with which it had registered the
 314 name.
 315
 316 only positive name releases are expected and dealt with. exactly what
 317 to do if a negative name release (i.e someone says 'oi! you have to
 318 keep that name!') is received is uncertain.
 319
 320 (when no response is received, then expire_netbios_response_entries()
 321 is expected to deal with this. if there is no challenge to the release
 322 of the name, the name is then removed from that subnet's NetBIOS
 323 name database).
 324
 325
 326 /*************************************************************************
 327   expire_names()
 328   *************************************************************************/
 329
 330 this function is responsible for removing old NetBIOS names from its
 331 database. no further action is required.
 332
 333 for over-zealous WINS systems, the use of query_refresh_names() is
 334 recommended. this function initiates polling of hosts that have
 335 registered with samba in its capacity as a WINS server. an alternative
 336 means to achieve the same end as query_refresh_names() is to
 337 reduce the time to live when the name is registered with samba,
 338 except that in this instance the responsibility for refreshing the
 339 name is with the owner of the name, not the server with which the name
 340 is registered.
 341
 342
 343 /*************************************************************************
 344   query_refresh_names()
 345   *************************************************************************/
 346
 347 this function is responsible for polling all names registered in the
 348 WINS database. it is planned to enable this function should samba
 349 detect an inconsistency on the network, which could occur if the
 350 samba NetBIOS daemon dies and is restarted.
 351
 352 polling is done very infrequently, but all names will be covered
 353 within a period NAME_POLL_REFRESH_TIME. a group of at most ten names
 354 will be queried at once, at intervals of NAME_POLL_INTERVAL seconds.
 355 if the total number of names queried in this way will take too long,
 356 then the time that an individual name will next be polled is
 357 increased accordingly.
 358
 359 name query polling is functionality over-and-above the normal
 360 requirement (see rfc1001.txt 15.1.7 point 7). it is normally the
 361 responsibility of the owner of a name to re-register the name at
 362 regular intervals.
 363
 364
 365 /*************************************************************************
 366   refresh_my_names()
 367   *************************************************************************/
 368
 369 this function is responsible for refreshing samba's names that have
 370 been registered with other servers on a local subnet, or with another
 371 WINS server if samba is using one.
 372
 373 samba's names' refresh_time will be updated through the use of the function
 374 add_my_name_entry().
 375
 376
 377 /*************************************************************************
 378   remove_my_names()
 379   *************************************************************************/
 380
 381 this function is responsible for removing all samba's SELF names. it
 382 is used when samba receives a SIG_TERM. samba at present does not wait
 383 for the WINS server to reply to the name releases sent out.
 384
 385
 386 /*************************************************************************
 387   add_my_names()
 388   *************************************************************************/
 389
 390 this function is responsible for adding and registering if necessary all
 391 samba's SELF names, on each of its local subnets and with another WINS
 392 server if samba is using one.
 393
 394 /*************************************************************************
 395   add_my_name_entry()
 396   *************************************************************************/
 397
 398 this function is responsible for registering or re-registering one of
 399 samba's names, either on the local subnet or with another WINS server
 400 if samba is using one.
 401
 402 if the name is already in samba's database, then it is re-registered,
 403 otherwise it is simply registered.
 404
 405 if samba registers its name with another WINS server, then the function
 406 response_name_reg() is responsible for updating samba's name database
 407 to reflect the claim or otherwise of the name.
 408
 409 expire_netbios_response_entries() is responsible for taking further action
 410 if no response to the registration is received.
 411
 412
 413 /*************************************************************************
 414   remove_name_entry()
 415   *************************************************************************/
 416
 417 this function is responsible for removing a NetBIOS name. if the name
 418 being removed is registered on a local subnet, a name release should be
 419 broadcast on the local subnet.
 420
 421 if samba has registered the name with a WINS server, it must send a
 422 name release to the WINS server it is using. once it receives a reply,
 423 it can proceed (see response_name_rel())
 424
 425 expire_netbios_response_entries() is responsible for taking further action
 426 if no response to the name release is received.
 427
 428
 429 /*************************************************************************
 430   load_netbios_names()
 431   *************************************************************************/
 432
 433 this function is responsible for loading any NetBIOS names that samba,
 434 in its WINS capacity, has written out to disk. all the relevant details
 435 are recorded in this file, including the time-to-live. should the
 436 time left to live be small, the name is not added back in to samba's
 437 WINS database.
 438
 439
 440 /*************************************************************************
 441   dump_names()
 442   *************************************************************************/
 443
 444 this function is responsible for outputting NetBIOS names in two formats.
 445 firstly, as debugging information, and secondly, all names that have been
 446 registered with samba in its capacity as a WINS server are written to
 447 disk.
 448
 449 writing all WINS names allows two things. firstly, if samba's NetBIOS
 450 daemon dies or is terminated, on restarting the daemon most if not all
 451 of the registered WINS names will be preserved (which is a good reason
 452 why query_netbios_names() should be used).
 453
 454
 455 /*************************************************************************
 456   find_name_search()
 457   *************************************************************************/
 458
 459 this function is a wrapper around find_name(). find_name_search() can
 460 be told whether to search for the name in a local subnet structure or
 461 in the WINS database. on top of this, it can be told to search only
 462 for samba's SELF names.
 463
 464 if it finds the name in the WINS database, it will set the subnet_record
 465 and also return the name it finds.
 466
 467
 468 /*************************************************************************
 469   find_req_subnet()
 470   *************************************************************************/
 471
 472 this function is responsible for finding the appropriate subnet record
 473 to use. it is assumed that any directed packets are going to need to
 474 use the WINS pseudo-subnet records, and that any broadcast transactions
 475 received are going to need to use a local subnet record, which is found
 476 from the ip address that the transaction was received on.
 477
 478 a side-effect of this function is that any broadcast packet received
 479 on a subnet not known to samba is ignored.
 480