source/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 /*************************************************************************
  26   check_elections()
  27   *************************************************************************/
  28
  29 this function returns True if samba is in the process of running an
  30 election on any of its interfaces. a better version of this function
  31 should return the time-out period in between election packets, in
  32 milliseconds.
  33
  34
  35 /*************************************************************************
  36   process_election()
  37   *************************************************************************/
  38
  39 this function is responsible for dealing with the receipt of an election
  40 browse MAILSLOT packet.
  41
  42 if samba is running an election, it checks the criteria in the packet
  43 received using win_election() to see if it has lost the election or if
  44 it should join in the election.
  45
  46 if it loses the election, then it becomes a non-master.
  47
  48
  49 /*************************************************************************
  50   win_election()
  51   *************************************************************************/
  52
  53 this function returns True if samba has won an election. the criteria
  54 in order of precedence are:
  55
  56 the election version; the election criteria; the time since samba was
  57 started; and as a last resort, a name comparison is used.
  58
  59
  60 /*************************************************************************
  61   run_elections()
  62   *************************************************************************/
  63
  64 this function is responsible for sending out election packets if
  65 samba is running in an election. once the fourth packet is sent
  66 out, it is assumed that we have won, and samba initiates becoming
  67 a master browser.
  68
  69 (it looks like samba sends out an extra packet just to be sure...)
  70
  71
  72 /*************************************************************************
  73   become_nonmaster()
  74   *************************************************************************/
  75
  76 this function is responsible for down-grading samba's status from
  77 either domain master to master browser or nothing, or master browser
  78 to nothing, depending on its current status.
  79
  80 samba can become a non-master in three ways: by losing an election -
  81 see process_election(); by having one of its special browser names
  82 de-registered - see name_unregister_work(); by receiving and
  83 processing a browser reset packet - see process_reset_browser().
  84
  85 when samba stops being a domain master, it must release its unique
  86 0x1b name. when samba stops being a master browser, it must release
  87 its unique 0x1d name.
  88
  89 becoming non-master is done on a per-subnet basis.
  90
  91
  92 /*************************************************************************
  93   become_master()
  94   *************************************************************************/
  95
  96 this function is responsible for slowly turning samba into a
  97 master browser or a domain master (primary domain controller).
  98
  99
 100 this is done in stages. note that this could take a while,
 101 particularly on a broadcast subnet, as we have to wait for
 102 the implicit registration of each name to be accepted.
 103
 104 as each name is successfully registered, become_master() is
 105 called again via name_register_work(), in order to initiate
 106 the next stage (see dead_netbios_entry() - deals with implicit
 107 name registration and response_name_reg() - deals with explicit
 108 registration with a WINS server).
 109
 110 stage 1: was MST_NONE - go to MST_NONE and register ^1^2__MSBROWSE__^2^1.
 111 stage 2: was MST_WON  - go to MST_MSB  and register WORKGROUP(0x1d)
 112 stage 3: was MST_MSB  - go to MST_BROWSER and register WORKGROUP(0x1b)
 113 stage 4: was MST_BROWSER - go to MST_DOMAIN (do not pass GO, do not...)
 114
 115 note that this code still does not cope with the distinction
 116 between different types of nodes, particularly between M and P
 117 nodes (see rfc1001.txt). that will be developed later.
 118
 119
 120 /*************************************************************************
 121   name_register_work()
 122   *************************************************************************/
 123
 124 this function is called when a NetBIOS name is successfully
 125 registered. it will add the registered name into samba's NetBIOS
 126 records.
 127
 128 it has the additional responsibility that when samba is becoming
 129 a master browser, it must initiate the next stage in the progress
 130 towards becoming a master browser.
 131
 132 implicit name registration is done through dead_netbios_entry()
 133 by time-out. explicit name registration is done through
 134 response_name_reg() with a WINS server.
 135
 136
 137 /*************************************************************************
 138   name_unregister_work()
 139   *************************************************************************/
 140
 141 this function is called when there is an objection to a NetBIOS
 142 name being registered. this will always be done through a negative
 143 response to a name registration, whether it be by a host that
 144 already owns the unique name being registered on a subnet, or
 145 by a WINS server.
 146
 147 the name being objected to must be removed from samba's records.
 148
 149 it has the additional responsibility of checking whether samba is
 150 currently a master browser or not, and if so it should initiate
 151 becoming a non-master.
 152
 153
 154
 155 /*************************************************************************
 156   send_election()
 157   *************************************************************************/
 158
 159 this function is responsible for sending a browse mailslot
 160 datagram election packet (of type ANN_Election). it constructs
 161 the packet with all the relevant info needed to participate:
 162 election version; election criteria; time since startup and
 163 our name.
 164
 165 this function can be used to ensure that initiate but lose an
 166 election by specifying a criteria and time up of zero. this
 167 is necessary if we are a master browser and we are about to
 168 go down (politely!) - see nmbd.c:sig_term().
 169
 170
 171 /*************************************************************************
 172   browser_gone()
 173   *************************************************************************/
 174
 175 this function is responsible for dealing with the instance when
 176 the master browser we thought was present on a subnet is no longer
 177 responding.
 178
 179 if it is samba's workgroup, and it's a local interface, samba
 180 detects that it can participate in an election on that interface
 181 and potentially become a master browser or domain master.
 182
 183 if it's a remote subnet or not one of samba's workgroups, then
 184 samba will force an election (which it is not obliged to do) and
 185 will remove that workgroup and the servers contained in it from
 186 its records. maybe this functionality isn't a good idea.
 187
 188
 189 /*************************************************************************
 190   check_master_browser()
 191   *************************************************************************/
 192
 193 this function is responsible for periodically checking whether
 194 master browsers that samba expects to be alive are alive. this
 195 is done every CHECK_TIME_MST_BROWSE minutes.
 196
 197 for every workgroup record for which samba is not a master browser,
 198 on both local and remote interfaces, samba will initiate a
 199 broadcast query for a master browser on that subnet.
 200
 201 (browser_gone() will be called to deal with the case where no
 202 response is received to the NAME_QUERY_MST_CHK initiated here.
 203 no action is required when a response _is_ received, however:
 204 see nameservresp.c:response_process() and dead_netbios_entry()
 205 for details)
 206
 207