source3/namework.doc

   1 /*
   2    Unix SMB/Netbios documentation.
   3    Version 0.1
   4    Copyright (C) Luke Leighton  Andrew Tridgell  1996
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 2 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program; if not, write to the Free Software
  18    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  19
  20    Document name: namework.doc
  21
  22    Revision History:
  23
  24    0.0 - 02jul96 : lkcl@pires.co.uk
  25    created
  26
  27    0.1 - 22jul96 Andrew.Tridgell@anu.edu.au
  28    tridge's comments on first revision
  29 */
  30
  31 the module namework.c deals with NetBIOS datagram packets, primarily.
  32 it deals with nmbd's workgroup browser side and the domain log in
  33 side. none of the functionality here has specification documents available.
  34 empirical observation of packet traces has been the order of the day,
  35 along with some guess-work.
  36
  37 beware!
  38
  39 the receipt of datagram packets for workgroup browsing are dealt with here.
  40 some of the functions listed here will call others outside of this
  41 module, or will activate functionality dealt with by other modules
  42 (namedb, nameannounce, nameelect, namelogon, and namebrowse).
  43
  44
  45 /*************************************************************************
  46   process_browse_packet()
  47   *************************************************************************/
  48
  49 this function is responsible for further identifying which type of
  50 browser datagram packet has been received, and dealing with it
  51 accordingly. if the packet is not dealt with, then an error is
  52 logged along with the type of packet that has been received.
  53
  54 if listening_type() was in use, then it would be used here.
  55
  56 the types of packets received and dealt with are:
  57
  58 - ANN_HostAnnouncement
  59 - ANN_DomainAnnouncement
  60 - ANN_LocalMasterAnnouncement
  61
  62 these are all identical in format and can all be processed by
  63 process_announce(). an announcement is received from a host
  64 (either a master browser telling us about itself, a server
  65 telling us about itself or a master browser telling us about
  66 a domain / workgroup)
  67
  68 - ANN_AnnouncementRequest
  69
  70 these are sent by master browsers or by servers. it is a
  71 request to announce ourselves as appropriate by sending
  72 either a ANN_HostAnnouncement datagram or both an
  73 ANN_DomainAnnouncement and an ANN_LocalMasterAnnouncement
  74 if we are a master browser (but not both).
  75
  76 - ANN_Election
  77
  78 this is an election datagram. if samba has been configured
  79 as a domain master then it will also send out election
  80 datagrams.
  81
  82 - ANN_GetBackupListReq
  83
  84 this is a request from another server for us to send a
  85 backup list of all servers that we know about. we respond
  86 by sending a datagram ANN_GetBackupListResp. the protocol
  87 here is a little dicey.
  88
  89 - ANN_GetBackupListResp
  90
  91 this is a response from another server that we have sent an
  92 ANN_GetBackupListReq to. the protocol is a little dicey.
  93
  94 - ANN_BecomeBackup
  95
  96 this is a message sent by a master browser to a
  97 potential master browser, indicating that it should become
  98 a backup master browser for the workgroup it is a member
  99 of. samba does not respond at present to such datagrams,
 100 and it also sends out such datagrams for the wrong reasons
 101 (this code has now been disabled until this is fixed).
 102
 103 - ANN_ResetBrowserState
 104
 105 this datagram is sent for trouble-shooting purposes.
 106 it asks a browser to clear out its server lists, or to
 107 stop becoming a master browser altogether. NT/AS and
 108 samba do not implement this latter option.
 109
 110 - ANN_MasterAnnouncement
 111
 112 this datagram is sent by a master browser to a domain master
 113 browser. it is a way to ensure that master browsers are kept in sync
 114 with a domain master browser across a wide area network. on
 115 receipt of an ANN_MasterAnnouncement we should sync browse lists with
 116 the sender.
 117
 118 (i never got the hang of this one when i was experimenting.
 119 i forget exactly what it's for, and i never fully worked
 120 out how to coax a server to send it. :-)
 121
 122 NOTE FROM TRIDGE: The reason you didn't work out how to coax a server
 123 into sending it is that you can't (or shouldn't try!). Basically these
 124 "master announce" datagrams are the way that separate netbios subnets
 125 are linked together to form a complete browse net. The way it works is
 126 that the local master decides it is going to inform the domain master
 127 of its presence, then sends this master announce to the domain
 128 master. The domain master then syncs with the local master using a
 129 "local only" sync. The whole transaction is initiated by the local
 130 master, not the domain master, so the domain master should not do any
 131 of this if it does not first receive a "master announcement". The
 132 local domain masters need to be configured to know the IP address of
 133 the domain master.
 134
 135
 136 /*************************************************************************
 137   listening_type()
 138   *************************************************************************/
 139
 140
 141 a datagram packet is sent from one NetBIOS name of a specific type
 142 to another NetBIOS name of a specific type. certain types of
 143 datagrams are only expected from certain types of NetBIOS names.
 144
 145 this function is intended to catch errors in the type of datagrams
 146 received from different NetBIOS names. it is currently incomplete
 147 due to lack of information on the types of names and the datagrams
 148 they send.
 149
 150
 151 /*************************************************************************
 152   process_announce_request()
 153   *************************************************************************/
 154
 155 this function is responsible for dealing with announcement requests.
 156 if the type of name that the request is sent to matches our current
 157 status, then we should respond. otherwise, the datagram should be
 158 ignored.
 159
 160 samba only responds on its local subnets.
 161
 162 at present, just the name is checked to see if the packet is for us.
 163 what should be done is that if we own the name (e.g WORGROUP(0x1d)
 164 or WORKGROUP(0x1b) then we should respond, otherwise, ignore the
 165 datagram.
 166
 167 if the name is for us, and we are a member of that workgroup, then
 168 samba should respond.
 169
 170 note that samba does not respond immediately. this is to ensure that
 171 if the master browser for the workgroup that samba is a member of
 172 sends out a broadcast request announcement, that that master browser
 173 is not swamped with replies. it is therefore up to samba to reply
 174 at some random interval. hence, a flag is set indicating the need
 175 to announce later.
 176
 177
 178 /*************************************************************************
 179   process_reset_browser()
 180   *************************************************************************/
 181
 182 this function is responsible for dealing with reset state datagrams.
 183 there are three kinds of diagnostic reset requests:
 184
 185 - stop being a master browser
 186 - discard browse lists, stop being a master browser, and run for re-election
 187 - stop being a master browser forever.
 188
 189 samba and windows nt do not implement the latter option.
 190
 191 there appears to be a discrepancy between this description and the
 192 code actually implemented.
 193
 194
 195 /*************************************************************************
 196   process_send_backup_list()
 197   *************************************************************************/
 198
 199 this function is part of samba's domain master browser functionality.
 200
 201 it is responsible for giving master browsers a list of other browsers
 202 that maintain backup lists of servers for that master browser's workgroup.
 203
 204 it is also responsible for giving master browsers a list of domain master
 205 browsers for that local master browser's domain.
 206
 207 a correct way to think of this function is that it is a 'request to
 208 send out a backup list for the requested workgroup or domain'.
 209
 210 i have some suspicions and intuitions about this function and how it
 211 is to actually be used. there is no documentation on this, so it is a
 212 matter of experimenting until it's right.
 213
 214
 215 /*************************************************************************
 216   send_backup_list()
 217   *************************************************************************/
 218
 219 this function is responsible for compiling a list of either master
 220 browsers and backup master browsers or domain master browsers and
 221 backup domain master browsers. samba constructs this list from its
 222 workgroup / server database.
 223
 224 the list is then sent to the host that requested it by sending an
 225 ANN_GetBackupListResp datagram to this host.
 226
 227
 228 NOTE FROM TRIDGE: The "backup list" stuff is only relevant to
 229 local subnets. It has nothing to do with PDCs or domain masters. Its
 230 function is twofold:
 231
 232 1) spread the browsing load over multiple servers so one server
 233 doesn't get overloaded with browse requests
 234 2) make sure the database doesn't get lost completely if the master
 235 goes down
 236
 237 To accomplish this a few things are supposed to be done:
 238
 239 - the master browser maintains a list of "backup browsers".
 240
 241 - backup browsers are are machines that are just like ordinary servers
 242 but also maintain a browse list and respond to "NetServerEnum"
 243 requests
 244
 245 - when a server initially announces itself to the master it may set
 246 its "maintain browse list" flag to auto.
 247
 248 - when a master browser sees a server announcement with "auto" set it
 249 may send a "become backup" to that server telling it to become a
 250 backup.
 251
 252 - the master has a simple algorithm to determine how many backups it wants
 253 given the number of hosts on the net
 254
 255 - when a client wishes to get a browse list it asks the master for a
 256 backup list. The master sends it the current list of backup browsers,
 257 including itself. The client caches this list. The client then sends
 258 the NetServerEnum to a random member of this list easch time it wants
 259 to browse. This spreads the load.
 260
 261
 262
 263 /*************************************************************************
 264   process_rcv_backup_list()
 265   *************************************************************************/
 266
 267 this function is implemented with a slightly over-kill algorithm.
 268 the correct functionality is to pick any three names at random from
 269 the list that is received from this datagram, and then at intervals
 270 contact _one_ of them for a list of browser, in order to update
 271 samba's browse list.
 272
 273 samba contacts every single one of the backup browsers listed, through
 274 the use of a NAME_QUERY_SRV_CHK 'state'.
 275
 276
 277 /*************************************************************************
 278   process_master_announce()
 279   *************************************************************************/
 280
 281 this function is responsible for synchronising browse lists with a
 282 master browser that contacts samba in its capacity as a domain master
 283 browser.
 284
 285 the function add_browser_entry() is used to add the server that
 286 contacts us to our list of browser to sync browse lists with at
 287 some point in the near future.
 288
 289
 290 /*************************************************************************
 291   process_announce()
 292   *************************************************************************/
 293
 294 this function is responsible for dealing with the three types of
 295 announcement type datagrams that samba recognises. some appropriate
 296 type-checking is done on the name that the datagram is sent to.
 297
 298 samba does not at present deal with LanManager announcements.
 299
 300 these announcements are for updating the browse entry records.
 301 each browse entry has a time-to-live associated with it. each server
 302 must refresh its entry with all other servers by broadcasting
 303 Announcements. if it does not do so, then other servers will not
 304 know about that machine, and the records on each server of that
 305 other machine will die.
 306
 307 if an ANN_DomainAnnouncement is received, then this will be from
 308 a master browser. only one machine on any given broadcast area (e.g
 309 a subnet) should be broadcasting such announcements. the information
 310 it contains tells other servers that there is a master browser for
 311 this workgroup. if another server thinks that it is also a master
 312 browser for the same workgroup, then it should stop being a master
 313 browser and force an election.
 314
 315 if an ANN_LocalMasterAnnouncement is received, then a master browser
 316 is telling us that it exists. i am uncertain that anything else
 317 actually needs to be done with this, other than to shout 'hooray' and
 318 'thank you for informing me of this fact'.
 319
 320
 321 /*************************************************************************
 322   listening_name()
 323   *************************************************************************/
 324
 325 this function is an over-simplified way of identifying whether we
 326 should be responding to a datagram that has been received.
 327
 328
 329 /*************************************************************************
 330   same_context()
 331   *************************************************************************/
 332
 333 this function helps us to identify whether we should be responding to
 334 a datagram that has been received.
 335
 336
 337 /*************************************************************************
 338   tell_become_backup()
 339   *************************************************************************/
 340
 341 this function is part of samba's domain master browser capabilities.
 342 it is responsible for finding appropriate servers to tell to become a
 343 backup master browser for the domain that samba controls.
 344
 345 other servers that contact samba asking for a list of backup browsers
 346 will then be given that server's name, and that server can expect to
 347 receive NetServerEnum requests for lists of servers and workgroups.
 348
 349 this function must be updated before it is in a fit state to be used.
 350 it must properly check whether a server is prepared to become a backup
 351 browser before actually asking it to be one.
 352
 353
 354 /*************************************************************************
 355   reset_server()
 356   *************************************************************************/
 357
 358 this function is responsible for issuing an ANN_ResetBrowserState to
 359 the specified server, asking it to reset its browser information.
 360
 361 see process_reset_browser() for details on this function.
 362
 363