home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1998 July & August / Pcwk78a98.iso / Wtestowe / Clico / UNIX / SAMBA / SOURCE / SAMBA.TAR / samba-1.9.17 / source / nameelect.doc < prev    next >
Text File  |  1996-08-05  |  10KB  |  257 lines
  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.  
  257.