source3/namebrowse.doc

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