source/namework.doc

   1
   2 the module namework.c deals with NetBIOS datagram packets, primarily.
   3 it deals with nmbd's workgroup browser side and the domain log in
   4 side. none of the functionality here has specification documents available.
   5 empirical observation of packet traces has been the order of the day.
   6
   7 beware!
   8
   9 the receipt of datagram packets for workgroup browsing are dealt with here.
  10 some of the functions listed here will call others outside of this
  11 module, or will activate functionality dealt with by other modules.
  12
  13 these include: namedb.c, nameannounce.c, nameelect.c,
  14                namelogon.c, and namebrowse.c.
  15
  16
  17 /*************************************************************************
  18   process_dgram()
  19   *************************************************************************/
  20
  21 this function is responsible for identifying whether the datagram
  22 packet received is a browser packet or a domain logon packet. it
  23 also does some filtering of certain types of packets (e.g it
  24 filters out error packets).
  25
  26
  27 /*************************************************************************
  28   process_browse_packet()
  29   *************************************************************************/
  30
  31 this function is responsible for further identifying which type of
  32 browser datagram packet has been received, and dealing with it
  33 accordingly. if the packet is not dealt with, then an error is
  34 logged along with the type of packet that has been received.
  35
  36 if listening_type() was in use, then it would be used here.
  37
  38 the types of packets received and dealt with are:
  39
  40 - ANN_HostAnnouncement
  41 - ANN_DomainAnnouncement
  42 - ANN_LocalMasterAnnouncement
  43
  44 these are all identical in format and can all be processed by
  45 process_announce(). an announcement is received from a host
  46 (either a master browser telling us about itself, a server
  47 telling us about itself or a master browser telling us about
  48 a domain / workgroup)
  49
  50 - ANN_AnnouncementRequest
  51
  52 these are sent by master browsers or by servers. it is a
  53 request to announce ourselves as appropriate by sending
  54 either a ANN_HostAnnouncement datagram or both an
  55 ANN_DomainAnnouncement and an ANN_LocalMasterAnnouncement
  56 if we are a master browser (but not both).
  57
  58 - ANN_Election
  59
  60 this is an election datagram. if samba has been configured
  61 as a domain master then it will also send out election
  62 datagrams.
  63
  64 - ANN_GetBackupListReq
  65
  66 this is a request from another server for us to send a
  67 backup list of all servers that we know about. we respond
  68 by sending a datagram ANN_GetBackupListResp. the protocol
  69 here is a little dicey.
  70
  71 - ANN_GetBackupListResp
  72
  73 this is a response from another server that we have sent an
  74 ANN_GetBackupListReq to. the protocol is a little dicey.
  75
  76 - ANN_BecomeBackup
  77
  78 this is a message sent by a primary domain controller to a
  79 potential master browser, indicating that it should become
  80 a backup master browser for the workgroup it is a member
  81 of. samba does not respond at present to such datagrams,
  82 and it also sends out such datagrams for the wrong reasons
  83 (this code has now been disabled until this is fixed).
  84
  85 - ANN_ResetBrowserState
  86
  87 this datagram is sent by a primary domain controller (or
  88 anyone else, for that matter) for trouble-shooting purposes.
  89 it asks a browser to clear out its server lists, or to
  90 stop becoming a master browser altogether. NT/AS and
  91 samba do not implement this latter option.
  92
  93 - ANN_MasterAnnouncement
  94
  95 this datagram is sent by a master browser to a primary domain
  96 controller. it is a way to ensure that master browsers are
  97 kept in sync with a primary domain controller across a wide
  98 area network.
  99
 100 (i never got the hang of this one when i was experimenting.
 101 i forget exactly what it's for, and i never fully worked
 102 out how to coax a server to send it. :-)
 103
 104
 105 /*************************************************************************
 106   listening_type()
 107   *************************************************************************/
 108
 109
 110 a datagram packet is sent from one NetBIOS name of a specific type
 111 to another NetBIOS name of a specific type. certain types of
 112 datagrams are only expected from certain types of NetBIOS names.
 113
 114 this function is intended to catch errors in the type of datagrams
 115 received from different NetBIOS names. it is currently incomplete
 116 due to lack of information on the types of names and the datagrams
 117 they send.
 118
 119
 120 /*************************************************************************
 121   process_announce_request()
 122   *************************************************************************/
 123
 124 this function is responsible for dealing with announcement requests.
 125 if the type of name that the request is sent to matches our current
 126 status, then we should respond. otherwise, the datagram should be
 127 ignored.
 128
 129 samba only responds on its local subnets.
 130
 131 at present, just the name is checked to see if the packet is for us.
 132 what should be done is that if we own the name (e.g WORGROUP(0x1d)
 133 or WORKGROUP(0x1b) then we should respond, otherwise, ignore the
 134 datagram.
 135
 136 if the name is for us, and we are a member of that workgroup, then
 137 samba should respond.
 138
 139 note that samba does not respond immediately. this is to ensure that
 140 if the master browser for the workgroup that samba is a member of
 141 sends out a broadcast request announcement, that that master browser
 142 is not swamped with replies. it is therefore up to samba to reply
 143 at some random interval. hence, a flag is set indicating the need
 144 to announce later.
 145
 146
 147 /*************************************************************************
 148   process_reset_browser()
 149   *************************************************************************/
 150
 151 this function is responsible for dealing with reset state datagrams.
 152 there are three kinds of diagnostic reset requests:
 153
 154 - stop being a master browser
 155 - discard browse lists, stop being a master browser, and run for re-election
 156 - stop being a master browser forever.
 157
 158 samba and windows nt do not implement the latter option.
 159
 160 there appears to be a discrepancy between this description and the
 161 code actually implemented.
 162
 163
 164 /*************************************************************************
 165   process_send_backup_list()
 166   *************************************************************************/
 167
 168 this function is part of samba's primary domain controller functionality.
 169
 170 it is responsible for giving master browsers a list of other browsers
 171 that maintain backup lists of servers for that master browser's workgroup.
 172
 173 it is also responsible for giving master browsers a list of primary domain
 174 controllers for that master browser's domain.
 175
 176 a correct way to think of this function is that it is a 'request to
 177 send out a backup list for the requested workgroup or domain'.
 178
 179 i have some suspicions and intuitions about this function and how it
 180 is to actually be used. there is no documentation on this, so it is a
 181 matter of experimenting until it's right.
 182
 183
 184 /*************************************************************************
 185   send_backup_list()
 186   *************************************************************************/
 187
 188 this function is responsible for compiling a list of either master
 189 browsers and backup master browsers or primary domain controllers or
 190 backup domain controllers. samba constructs this list from its
 191 workgroup / server database.
 192
 193 the list is then sent to the host that requested it by sending an
 194 ANN_GetBackupListResp datagram to this host.
 195
 196
 197 /*************************************************************************
 198   process_rcv_backup_list()
 199   *************************************************************************/
 200
 201 this function is implemented with a slightly over-kill algorithm.
 202 the correct functionality is to pick any three names at random from
 203 the list that is received from this datagram, and then at intervals
 204 contact _one_ of them for a list of browser, in order to update
 205 samba's browse list.
 206
 207 samba contacts every single one of the backup browsers listed, through
 208 the use of a NAME_QUERY_SRV_CHK 'state'.
 209
 210
 211 /*************************************************************************
 212   process_master_announce()
 213   *************************************************************************/
 214
 215 this function is responsible for synchronising browse lists with a
 216 master browser that contacts samba in its capacity as a primary
 217 domain controller.
 218
 219 the function add_browser_entry() is used to add the server that
 220 contacts us to our list of browser to sync browse lists with at
 221 some point in the near future.
 222
 223
 224 /*************************************************************************
 225   process_announce()
 226   *************************************************************************/
 227
 228 this function is responsible for dealing with the three types of
 229 announcement type datagrams that samba recognises. some appropriate
 230 type-checking is done on the name that the datagram is sent to.
 231
 232 samba does not at present deal with LanManager announcements.
 233
 234 these announcements are for updating the browse entry records.
 235 each browse entry has a time-to-live associated with it. each server
 236 must refresh its entry with all other servers by broadcasting
 237 Announcements. if it does not do so, then other servers will not
 238 know about that machine, and the records on each server of that
 239 other machine will die.
 240
 241 if an ANN_DomainAnnouncement is received, then this will be from
 242 a master browser. only one machine on any given broadcast area (e.g
 243 a subnet) should be broadcasting such announcements. the information
 244 it contains tells other servers that there is a master browser for
 245 this workgroup. if another server thinks that it is also a master
 246 browser for the same workgroup, then it should stop being a master
 247 browser and force an election.
 248
 249 if an ANN_LocalMasterAnnouncement is received, then a master browser
 250 is telling us that it exists. i am uncertain that anything else
 251 actually needs to be done with this, other than to shout 'hooray' and
 252 'thank you for informing me of this fact'.
 253
 254
 255 /*************************************************************************
 256   listening_name()
 257   *************************************************************************/
 258
 259 this function is an over-simplified way of identifying whether we
 260 should be responding to a datagram that has been received.
 261
 262
 263 /*************************************************************************
 264   same_context()
 265   *************************************************************************/
 266
 267 this function helps us to identify whether we should be responding to
 268 a datagram that has been received.
 269
 270
 271 /*************************************************************************
 272   tell_become_backup()
 273   *************************************************************************/
 274
 275 this function is part of samba's primary domain controller capabilities.
 276 it is responsible for finding appropriate servers to tell to become a
 277 backup master browser for the domain that samba controls.
 278
 279 other servers that contact samba asking for a list of backup browsers
 280 will then be given that server's name, and that server can expect to
 281 receive NetServerEnum requests for lists of servers and workgroups.
 282
 283 this function must be updated before it is in a fit state to be used.
 284 it must properly check whether a server is prepared to become a backup
 285 browser before actually asking it to be one.
 286
 287
 288 /*************************************************************************
 289   reset_server()
 290   *************************************************************************/
 291
 292 this function is responsible for issuing an ANN_ResetBrowserState to
 293 the specified server, asking it to reset its browser information.
 294
 295 see process_reset_browser() for details on this function.
 296
 297