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 / namework.doc < prev    next >
Text File  |  1996-08-05  |  14KB  |  364 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: namework.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 namework.c deals with NetBIOS datagram packets, primarily.
  32. it deals with nmbd's workgroup browser side and the domain log in
  33. side. none of the functionality here has specification documents available.
  34. empirical observation of packet traces has been the order of the day,
  35. along with some guess-work.
  36.  
  37. beware!
  38.  
  39. the receipt of datagram packets for workgroup browsing are dealt with here.
  40. some of the functions listed here will call others outside of this
  41. module, or will activate functionality dealt with by other modules
  42. (namedb, nameannounce, nameelect, namelogon, and namebrowse).
  43.  
  44.  
  45. /*************************************************************************
  46.   process_browse_packet()
  47.   *************************************************************************/
  48.  
  49. this function is responsible for further identifying which type of
  50. browser datagram packet has been received, and dealing with it
  51. accordingly. if the packet is not dealt with, then an error is
  52. logged along with the type of packet that has been received.
  53.  
  54. if listening_type() was in use, then it would be used here.
  55.  
  56. the types of packets received and dealt with are:
  57.  
  58. - ANN_HostAnnouncement         
  59. - ANN_DomainAnnouncement      
  60. - ANN_LocalMasterAnnouncement 
  61.  
  62. these are all identical in format and can all be processed by
  63. process_announce(). an announcement is received from a host
  64. (either a master browser telling us about itself, a server
  65. telling us about itself or a master browser telling us about
  66. a domain / workgroup)
  67.  
  68. - ANN_AnnouncementRequest      
  69.  
  70. these are sent by master browsers or by servers. it is a
  71. request to announce ourselves as appropriate by sending
  72. either a ANN_HostAnnouncement datagram or both an
  73. ANN_DomainAnnouncement and an ANN_LocalMasterAnnouncement
  74. if we are a master browser (but not both).
  75.  
  76. - ANN_Election                 
  77.  
  78. this is an election datagram. if samba has been configured
  79. as a domain master then it will also send out election
  80. datagrams. 
  81.  
  82. - ANN_GetBackupListReq         
  83.  
  84. this is a request from another server for us to send a
  85. backup list of all servers that we know about. we respond
  86. by sending a datagram ANN_GetBackupListResp. the protocol
  87. here is a little dicey.
  88.  
  89. - ANN_GetBackupListResp       
  90.  
  91. this is a response from another server that we have sent an
  92. ANN_GetBackupListReq to. the protocol is a little dicey.
  93.  
  94. - ANN_BecomeBackup            
  95.  
  96. this is a message sent by a master browser to a
  97. potential master browser, indicating that it should become
  98. a backup master browser for the workgroup it is a member
  99. of. samba does not respond at present to such datagrams,
  100. and it also sends out such datagrams for the wrong reasons
  101. (this code has now been disabled until this is fixed).
  102.  
  103. - ANN_ResetBrowserState       
  104.  
  105. this datagram is sent for trouble-shooting purposes.
  106. it asks a browser to clear out its server lists, or to
  107. stop becoming a master browser altogether. NT/AS and
  108. samba do not implement this latter option.
  109.  
  110. - ANN_MasterAnnouncement      
  111.  
  112. this datagram is sent by a master browser to a domain master
  113. browser. it is a way to ensure that master browsers are kept in sync
  114. with a domain master browser across a wide area network. on
  115. receipt of an ANN_MasterAnnouncement we should sync browse lists with
  116. the sender.
  117.  
  118. (i never got the hang of this one when i was experimenting.
  119. i forget exactly what it's for, and i never fully worked
  120. out how to coax a server to send it. :-)
  121.  
  122. NOTE FROM TRIDGE: The reason you didn't work out how to coax a server
  123. into sending it is that you can't (or shouldn't try!). Basically these
  124. "master announce" datagrams are the way that separate netbios subnets
  125. are linked together to form a complete browse net. The way it works is
  126. that the local master decides it is going to inform the domain master
  127. of its presence, then sends this master announce to the domain
  128. master. The domain master then syncs with the local master using a
  129. "local only" sync. The whole transaction is initiated by the local
  130. master, not the domain master, so the domain master should not do any
  131. of this if it does not first receive a "master announcement". The
  132. local domain masters need to be configured to know the IP address of
  133. the domain master.
  134.  
  135.  
  136. /*************************************************************************
  137.   listening_type()
  138.   *************************************************************************/
  139.  
  140.  
  141. a datagram packet is sent from one NetBIOS name of a specific type
  142. to another NetBIOS name of a specific type. certain types of
  143. datagrams are only expected from certain types of NetBIOS names.
  144.  
  145. this function is intended to catch errors in the type of datagrams
  146. received from different NetBIOS names. it is currently incomplete
  147. due to lack of information on the types of names and the datagrams
  148. they send.
  149.  
  150.  
  151. /*************************************************************************
  152.   process_announce_request()
  153.   *************************************************************************/
  154.  
  155. this function is responsible for dealing with announcement requests.
  156. if the type of name that the request is sent to matches our current
  157. status, then we should respond. otherwise, the datagram should be
  158. ignored.
  159.  
  160. samba only responds on its local subnets.
  161.  
  162. at present, just the name is checked to see if the packet is for us.
  163. what should be done is that if we own the name (e.g WORGROUP(0x1d)
  164. or WORKGROUP(0x1b) then we should respond, otherwise, ignore the
  165. datagram.
  166.  
  167. if the name is for us, and we are a member of that workgroup, then
  168. samba should respond.
  169.  
  170. note that samba does not respond immediately. this is to ensure that
  171. if the master browser for the workgroup that samba is a member of
  172. sends out a broadcast request announcement, that that master browser
  173. is not swamped with replies. it is therefore up to samba to reply
  174. at some random interval. hence, a flag is set indicating the need
  175. to announce later.
  176.  
  177.  
  178. /*************************************************************************
  179.   process_reset_browser()
  180.   *************************************************************************/
  181.  
  182. this function is responsible for dealing with reset state datagrams.
  183. there are three kinds of diagnostic reset requests:
  184.  
  185. - stop being a master browser
  186. - discard browse lists, stop being a master browser, and run for re-election
  187. - stop being a master browser forever.
  188.  
  189. samba and windows nt do not implement the latter option.
  190.  
  191. there appears to be a discrepancy between this description and the
  192. code actually implemented.
  193.  
  194.  
  195. /*************************************************************************
  196.   process_send_backup_list()
  197.   *************************************************************************/
  198.  
  199. this function is part of samba's domain master browser functionality.
  200.  
  201. it is responsible for giving master browsers a list of other browsers
  202. that maintain backup lists of servers for that master browser's workgroup.
  203.  
  204. it is also responsible for giving master browsers a list of domain master
  205. browsers for that local master browser's domain.
  206.  
  207. a correct way to think of this function is that it is a 'request to
  208. send out a backup list for the requested workgroup or domain'.
  209.  
  210. i have some suspicions and intuitions about this function and how it
  211. is to actually be used. there is no documentation on this, so it is a
  212. matter of experimenting until it's right.
  213.  
  214.  
  215. /*************************************************************************
  216.   send_backup_list()
  217.   *************************************************************************/
  218.  
  219. this function is responsible for compiling a list of either master
  220. browsers and backup master browsers or domain master browsers and
  221. backup domain master browsers. samba constructs this list from its 
  222. workgroup / server database.
  223.  
  224. the list is then sent to the host that requested it by sending an
  225. ANN_GetBackupListResp datagram to this host.
  226.  
  227.  
  228. NOTE FROM TRIDGE: The "backup list" stuff is only relevant to 
  229. local subnets. It has nothing to do with PDCs or domain masters. Its
  230. function is twofold:
  231.  
  232. 1) spread the browsing load over multiple servers so one server
  233. doesn't get overloaded with browse requests
  234. 2) make sure the database doesn't get lost completely if the master
  235. goes down
  236.  
  237. To accomplish this a few things are supposed to be done:
  238.  
  239. - the master browser maintains a list of "backup browsers".  
  240.  
  241. - backup browsers are are machines that are just like ordinary servers
  242. but also maintain a browse list and respond to "NetServerEnum"
  243. requests
  244.  
  245. - when a server initially announces itself to the master it may set
  246. its "maintain browse list" flag to auto. 
  247.  
  248. - when a master browser sees a server announcement with "auto" set it
  249. may send a "become backup" to that server telling it to become a
  250. backup.
  251.  
  252. - the master has a simple algorithm to determine how many backups it wants
  253. given the number of hosts on the net
  254.  
  255. - when a client wishes to get a browse list it asks the master for a
  256. backup list. The master sends it the current list of backup browsers,
  257. including itself. The client caches this list. The client then sends
  258. the NetServerEnum to a random member of this list easch time it wants
  259. to browse. This spreads the load.
  260.  
  261.  
  262.  
  263. /*************************************************************************
  264.   process_rcv_backup_list()
  265.   *************************************************************************/
  266.  
  267. this function is implemented with a slightly over-kill algorithm.
  268. the correct functionality is to pick any three names at random from
  269. the list that is received from this datagram, and then at intervals
  270. contact _one_ of them for a list of browser, in order to update
  271. samba's browse list.
  272.  
  273. samba contacts every single one of the backup browsers listed, through
  274. the use of a NAME_QUERY_SRV_CHK 'state'.
  275.  
  276.  
  277. /*************************************************************************
  278.   process_master_announce()
  279.   *************************************************************************/
  280.  
  281. this function is responsible for synchronising browse lists with a
  282. master browser that contacts samba in its capacity as a domain master
  283. browser.
  284.  
  285. the function add_browser_entry() is used to add the server that
  286. contacts us to our list of browser to sync browse lists with at
  287. some point in the near future.
  288.  
  289.  
  290. /*************************************************************************
  291.   process_announce()
  292.   *************************************************************************/
  293.  
  294. this function is responsible for dealing with the three types of
  295. announcement type datagrams that samba recognises. some appropriate
  296. type-checking is done on the name that the datagram is sent to.
  297.  
  298. samba does not at present deal with LanManager announcements.
  299.  
  300. these announcements are for updating the browse entry records.
  301. each browse entry has a time-to-live associated with it. each server
  302. must refresh its entry with all other servers by broadcasting
  303. Announcements. if it does not do so, then other servers will not
  304. know about that machine, and the records on each server of that
  305. other machine will die.
  306.  
  307. if an ANN_DomainAnnouncement is received, then this will be from
  308. a master browser. only one machine on any given broadcast area (e.g
  309. a subnet) should be broadcasting such announcements. the information
  310. it contains tells other servers that there is a master browser for
  311. this workgroup. if another server thinks that it is also a master
  312. browser for the same workgroup, then it should stop being a master
  313. browser and force an election.
  314.  
  315. if an ANN_LocalMasterAnnouncement is received, then a master browser
  316. is telling us that it exists. i am uncertain that anything else
  317. actually needs to be done with this, other than to shout 'hooray' and
  318. 'thank you for informing me of this fact'.
  319.  
  320.  
  321. /*************************************************************************
  322.   listening_name()
  323.   *************************************************************************/
  324.  
  325. this function is an over-simplified way of identifying whether we
  326. should be responding to a datagram that has been received.
  327.  
  328.  
  329. /*************************************************************************
  330.   same_context()
  331.   *************************************************************************/
  332.  
  333. this function helps us to identify whether we should be responding to
  334. a datagram that has been received.
  335.  
  336.  
  337. /*************************************************************************
  338.   tell_become_backup()
  339.   *************************************************************************/
  340.  
  341. this function is part of samba's domain master browser capabilities.
  342. it is responsible for finding appropriate servers to tell to become a
  343. backup master browser for the domain that samba controls.
  344.  
  345. other servers that contact samba asking for a list of backup browsers
  346. will then be given that server's name, and that server can expect to
  347. receive NetServerEnum requests for lists of servers and workgroups.
  348.  
  349. this function must be updated before it is in a fit state to be used.
  350. it must properly check whether a server is prepared to become a backup
  351. browser before actually asking it to be one.
  352.  
  353.  
  354. /*************************************************************************
  355.   reset_server()
  356.   *************************************************************************/
  357.  
  358. this function is responsible for issuing an ANN_ResetBrowserState to
  359. the specified server, asking it to reset its browser information.
  360.  
  361. see process_reset_browser() for details on this function.
  362.  
  363.  
  364.