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