source3/namebrowse.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: namebrowse.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 this module deals with queueing servers that samba must sync browse
  32 lists with. it will always issue a name query immediately before
  33 actually carrying out the NetServerEnum call, to ensure that time
  34 is not wasted by a remote server's failure.
  35
  36 this module was created to minimise the amount of NetServerEnum calls
  37 that samba may be asked to perform, by maintaining the name of a server
  38 for up to a minute after the NetServerEnum call was issued, and
  39 disallowing further NetServerEnum calls to this remote server until
  40 the entry is removed.
  41
  42 samba can ask for a NetServerEnum call to be issued to grab a remote
  43 server's list of servers and workgroups either in its capacity as
  44 a domain master browser, as a local master browser.
  45
  46 samba does not deal with becoming a backup master browser properly
  47 at present.
  48
  49 -------------
  50 NOTE FROM TRIDGE:
  51
  52 Yes, samba can send these either in its capacity as a DMB or as a
  53 MB. There are only two situations:
  54
  55 - If samba is a DMB then it should sync with the "local only" bit set
  56 with any master browser that has sent it a "master announce".
  57
  58 - if samba is not a DMB then it can only sync with the DMB, and should
  59 not set the "local only" bit.
  60
  61 Note that samba should never sync with other non-DMB servers when it
  62 is not a DMB.
  63
  64 Try to do a sync under any other circumstances is dangerous without a
  65 multi-threaded nmbd. I have a print server at home that knows some SMB
  66 and NBT, but if you try to sync browse lists with it then it clogs up,
  67 and also clogs up nmbd while it times out the connection. If  we
  68 follow  the above two rules then we can't get into this sort of
  69 trouble as:
  70
  71 - if we are a DMB and a master browser sends us a "master announce"
  72 then it is expecting to receive a NetServerEnum SMB connection soon,
  73 and must be capabable of handling it.
  74
  75 - if we are not a DMB then we will only sync with the DMB, which must
  76 be capable of doing this stuff or things are really in a mess :-)
  77 --------------
  78
  79
  80 /*************************************************************************
  81   do_browser_lists()
  82   *************************************************************************/
  83
  84 this function is responsible for finding an appropriate entry in the
  85 sync browser cache, initiating a name query (which results in a
  86 NetServerEnum call if there is a positive response), and then
  87 removing all entries that have been actioned and have been around
  88 for over a minute.
  89
  90
  91 /*************************************************************************
  92   start_sync_browse_entry()
  93   *************************************************************************/
  94
  95 this function is responsible for initiating a name query. if a
  96 positive response is received, then this will result in a
  97 NetServerEnum api call.
  98
  99 samba will only initiate this process if it is a master browser
 100 for this workgroup.
 101
 102 -----------
 103 NOTE FROM TRIDGE:
 104
 105 I'd actually prefer to skip the name query completely if we can
 106 resolve the DMBs name via gethostbyname(). For the name query to work
 107 we either have to have WINS working, or we need to know the broadcast
 108 address of the network that the DMB is on. This makes us too dependent
 109 on too many thing being right.
 110
 111 If the gethostbyname() fails then sure, go for a normal name query,
 112 but if it works then we have saved ourselves a lot of trouble and
 113 gained a lot of robustness.
 114
 115 This is best handled by a generic "resolve netbios name" routine that
 116 tries DNS first then resorts to WINS or bcast if that fails. It also
 117 needs to cache the results.
 118 -------------
 119
 120
 121 /*************************************************************************
 122   add_browser_entry()
 123   *************************************************************************/
 124
 125 this function is responsible for adding a browser into the list of
 126 servers to sync browse lists with. if the server entry has already
 127 been added and syncing browse lists has already been initiated, it
 128 will not be added again.
 129
 130
 131 /*************************************************************************
 132   expire_browse_cache()
 133   *************************************************************************/
 134
 135 this function is responsible for removing entries that have had the
 136 sync browse list initiated (whether that succeeded or not is beyond
 137 this function's scope) and have been in the cache for a while.
 138
 139
 140 /*************************************************************************
 141   add_browse_entry()
 142   *************************************************************************/
 143
 144 this function is responsible for adding a new entry into the list
 145 of servers to sync browse lists with at some point in the near future.
 146
 147
 148
 149