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