source3/nameelect.doc

   1
   2 the module nameelect.c deals with initiating, winning, losing
   3 browsing elections, and checking if browsers are still around,
   4 and the consequences of getting involved in all this.
   5
   6 an election packet can be received at any time, which will initiate
   7 an election.  samba can also detect that there is no longer a
   8 master browser and will initiate an election.
   9
  10 there is one way to become a master browser, but there are two
  11 ways to un-become a master browser.  if you lose an election, you
  12 must stop being a master browser. if you fail to register your
  13 unique special browser names (either on your local subnet or with
  14 the WINS server) then you must stop being a master browser.
  15
  16 this is a double fail-safe mechanism to ensure that there is only
  17 one master browser per workgroup per subnet (and one primary domain
  18 controller - domain master browser - per domain (workgroup) per
  19 wide area network).
  20
  21 (a wide area network is created when one or more servers on a
  22 broadcast-isolated subnet point to the same WINS server).
  23
  24 --------
  25 NOTE FROM TRIDGE:
  26
  27 I'd say "domain master browser" not "WINS server" here. WINS doesn't
  28 have much to do with browsing, it is the WAN varient of name
  29 resolution. The name resolution and browsing functions of a netbios
  30 network are almost entirely separate. Both grew out of systems that
  31 could only be used on local networks.
  32
  33 To adapt them to WANs, WINS was added for name resolution, and "domain
  34 master browsers" were added for browse lists. It would be perfectly
  35 possible to have a WINS server that doesn't even listen to UDP port
  36 138.
  37 --------
  38
  39 /*************************************************************************
  40   check_elections()
  41   *************************************************************************/
  42
  43 this function returns True if samba is in the process of running an
  44 election on any of its interfaces. a better version of this function
  45 should return the time-out period in between election packets, in
  46 milliseconds.
  47
  48
  49 /*************************************************************************
  50   process_election()
  51   *************************************************************************/
  52
  53 this function is responsible for dealing with the receipt of an election
  54 browse MAILSLOT packet.
  55
  56 if samba is running an election, it checks the criteria in the packet
  57 received using win_election() to see if it has lost the election or if
  58 it should join in the election.
  59
  60 if it loses the election, then it becomes a non-master.
  61
  62
  63 /*************************************************************************
  64   win_election()
  65   *************************************************************************/
  66
  67 this function returns True if samba has won an election. the criteria
  68 in order of precedence are:
  69
  70 the election version; the election criteria; the time since samba was
  71 started; and as a last resort, a name comparison is used.
  72
  73
  74 /*************************************************************************
  75   run_elections()
  76   *************************************************************************/
  77
  78 this function is responsible for sending out election packets if
  79 samba is running in an election. once the fourth packet is sent
  80 out, it is assumed that we have won, and samba initiates becoming
  81 a master browser.
  82
  83 (it looks like samba sends out an extra packet just to be sure...)
  84
  85
  86 /*************************************************************************
  87   become_nonmaster()
  88   *************************************************************************/
  89
  90 this function is responsible for down-grading samba's status from
  91 either domain master to master browser or nothing, or master browser
  92 to nothing, depending on its current status.
  93
  94 samba can become a non-master in three ways: by losing an election -
  95 see process_election(); by having one of its special browser names
  96 de-registered - see name_unregister_work(); by receiving and
  97 processing a browser reset packet - see process_reset_browser().
  98
  99 when samba stops being a domain master, it must release its unique
 100 0x1b name. when samba stops being a master browser, it must release
 101 its unique 0x1d name.
 102
 103 becoming non-master is done on a per-subnet basis.
 104
 105
 106 /*************************************************************************
 107   become_master()
 108   *************************************************************************/
 109
 110 this function is responsible for slowly turning samba into a
 111 master browser or a domain master (primary domain controller).
 112
 113
 114 this is done in stages. note that this could take a while,
 115 particularly on a broadcast subnet, as we have to wait for
 116 the implicit registration of each name to be accepted.
 117
 118 as each name is successfully registered, become_master() is
 119 called again via name_register_work(), in order to initiate
 120 the next stage (see dead_netbios_entry() - deals with implicit
 121 name registration and response_name_reg() - deals with explicit
 122 registration with a WINS server).
 123
 124 stage 1: was MST_NONE - go to MST_NONE and register ^1^2__MSBROWSE__^2^1.
 125 stage 2: was MST_WON  - go to MST_MSB  and register WORKGROUP(0x1d)
 126 stage 3: was MST_MSB  - go to MST_BROWSER and register WORKGROUP(0x1b)
 127 stage 4: was MST_BROWSER - go to MST_DOMAIN (do not pass GO, do not...)
 128
 129 note that this code still does not cope with the distinction
 130 between different types of nodes, particularly between M and P
 131 nodes (see rfc1001.txt). that will be developed later.
 132
 133
 134 /*************************************************************************
 135   name_register_work()
 136   *************************************************************************/
 137
 138 this function is called when a NetBIOS name is successfully
 139 registered. it will add the registered name into samba's NetBIOS
 140 records.
 141
 142 it has the additional responsibility that when samba is becoming
 143 a master browser, it must initiate the next stage in the progress
 144 towards becoming a master browser.
 145
 146 implicit name registration is done through dead_netbios_entry()
 147 by time-out. explicit name registration is done through
 148 response_name_reg() with a WINS server.
 149
 150
 151 /*************************************************************************
 152   name_unregister_work()
 153   *************************************************************************/
 154
 155 this function is called when there is an objection to a NetBIOS
 156 name being registered. this will always be done through a negative
 157 response to a name registration, whether it be by a host that
 158 already owns the unique name being registered on a subnet, or
 159 by a WINS server.
 160
 161 the name being objected to must be removed from samba's records.
 162
 163 it has the additional responsibility of checking whether samba is
 164 currently a master browser or not, and if so it should initiate
 165 becoming a non-master.
 166
 167
 168
 169 /*************************************************************************
 170   send_election()
 171   *************************************************************************/
 172
 173 this function is responsible for sending a browse mailslot
 174 datagram election packet (of type ANN_Election). it constructs
 175 the packet with all the relevant info needed to participate:
 176 election version; election criteria; time since startup and
 177 our name.
 178
 179 this function can be used to ensure that initiate but lose an
 180 election by specifying a criteria and time up of zero. this
 181 is necessary if we are a master browser and we are about to
 182 go down (politely!) - see nmbd.c:sig_term().
 183
 184
 185 /*************************************************************************
 186   browser_gone()
 187   *************************************************************************/
 188
 189 this function is responsible for dealing with the instance when
 190 the master browser we thought was present on a subnet is no longer
 191 responding.
 192
 193 if it is samba's workgroup, and it's a local interface, samba
 194 detects that it can participate in an election on that interface
 195 and potentially become a master browser or domain master.
 196
 197 if it's a local subnet and not one of samba's workgroups, then
 198 samba will force an election (which it is not obliged to do).
 199 remove_workgroup() will be expected to remove all references
 200 to this workgroup and the servers in it from the database.
 201
 202 if it's a remote subnet and not one of samba's workgroups then
 203 no election is forced, and remove_workgroup() will be expected
 204 to remove all server entries from this workgroup _except_ those
 205 added from the lmhosts file. if there are entries added from
 206 the lmhosts file, then the workgroup entry will remain,
 207 otherwise it too will be removed.
 208
 209
 210 /*************************************************************************
 211   check_master_browser()
 212   *************************************************************************/
 213
 214 this function is responsible for periodically checking whether
 215 master browsers that samba expects to be alive are alive. this
 216 is done every CHECK_TIME_MST_BROWSE minutes.
 217
 218 for every workgroup record for which samba is not a master browser,
 219 on both local and remote interfaces, samba will initiate a
 220 broadcast query for a master browser on that subnet.
 221
 222 (browser_gone() will be called to deal with the case where no
 223 response is received to the NAME_QUERY_MST_CHK initiated here.
 224 no action is required when a response _is_ received, however:
 225 see nameservresp.c:response_process() and dead_netbios_entry()
 226 for details)
 227
 228