source/nameannounce.doc

   1 this module deals with announcements: the sending of announcement requests
   2 and the sending of announcements either to refresh other servers' records
   3 or as a response to announcement requests.
   4
   5
   6 /*************************************************************************
   7   announce_master()
   8   *************************************************************************/
   9
  10 this function is responsible for announcing samba as a master browser
  11 to all known primary domain controllers.
  12
  13 this announcement is sent out at CHECK_TIME_MST_ANNOUNCE minute
  14 intervals, only if samba is a master browser on one or more of
  15 its local interfaces.
  16
  17 if no domain controller has been specified (lp_domain_controller())
  18 samba goes through its list of servers looking for primary domain
  19 controllers. when it finds one (other than itself) it will either
  20 initiate a NAME_QUERY_PDC_SRV_CHK by broadcast or with a WINS
  21 server. this will result in a NAME_STATUS_PDC_SRV_CHK, which
  22 will result in a sync browse list and an announcement
  23 ANN_MasterAnnounce being sent (see sync_server()).
  24
  25 if a domain controller has been specified, samba will search for
  26 a primary domain controller for its workgroup (either by directed
  27 packet or by broadcast if it cannot resolve the domain controller
  28 name using DNS), which results in the same action as listed above.
  29
  30 ------------
  31 NOTE FROM TRIDGE:
  32
  33 PDC in the above should really be DMB (domain master browser). They
  34 might be separate entities.
  35
  36 I also propose a simpler scheme :-)
  37
  38 If a DMB is not configured with lp_domain_controller() (perhaps
  39 renamed to lp_domain_master()?) then just don't do master
  40 announcements. Remember that most peoples networks are very simple and
  41 don't need DMB capabilities. Those that do need them will have more
  42 complex network topologies and they really need to choose themselves
  43 which box will act as the "hub" for netbios name resolution. Doing it
  44 via name queries will just lead to lag and propogation delays, because
  45 if two parts of the net choose different DMBs then the data will be
  46 very slow to propoogate.
  47
  48 If a DMB is configured then just sent the master announcemnt to that
  49 box! Thats all that needs to be done. Just send a udp 138 packet and
  50 forget it. If the recipient is indeed a DMB (as it should be if the
  51 config file is correct) then it should initiate a browse list sync
  52 with us at some later time, but that is take care of by smbd and nmbd
  53 doesn't even need to know it happened.
  54
  55 Additionally, if a DMB is configured we need to sync our workgroup
  56 list and server list with them occasionally. Note that this is only
  57 time a non-DMB should do a browse sync, and it should only do it with
  58 a DMB. Essentially WAN based netbios is just a simple star. There is a
  59 DMB in the centre, and the individual master browsers for each subnet
  60 talk to it, but never talk to each other. If they start talking to
  61 each other then the network load will go as the square of the number
  62 of machines, which will result in meltdown :-)
  63 -------------
  64
  65
  66 /*************************************************************************
  67   announce_host()
  68   *************************************************************************/
  69
  70 this complex-looking function is responsible for announcing samba's
  71 existence to other servers by broadcast. the actual announcement
  72 is carried out by announce_server().
  73
  74 the time period between samba's announcement will stretch from one
  75 minute to twelve minutes by one minute. if samba has received an
  76 announce request from a master browser, then it should answer at
  77 any random interval between zero and thirty seconds after the
  78 request is received. this is to ensure that the master browser
  79 does not get overloaded with responses!
  80
  81
  82 /*************************************************************************
  83   announce_server()
  84   *************************************************************************/
  85
  86 this function is responsible for sending announcement packets.
  87 these packets are received by other servers, which will then
  88 update their records accordingly: what services we have, our
  89 name, our comment field and our time to live (to name a few).
  90
  91 if we are a master browser, then using do_announce_host() we
  92 must send an announcement notifying members of that workgroup
  93 that we are their master browser, and another announcement
  94 indicating to all backup browsers and master browsers that
  95 we are a master browser.
  96
  97 (note: if another master browser receives this announcement
  98 and thinks that it is also the master browser for this
  99 workgroup, it stops being a master browser and forces an
 100 election).
 101
 102 if we are not a master browser, then we send an announcement
 103 notifying the master browser that we are a member of its
 104 workgroup.
 105
 106
 107 /*************************************************************************
 108   remove_my_servers()
 109   *************************************************************************/
 110
 111 this function is responsible for informing other servers that
 112 samba is about to go down. it announces, on all subnets, that
 113 samba's time to live is zero and that it has no services.
 114
 115
 116 /*************************************************************************
 117   do_announce_host()
 118   *************************************************************************/
 119
 120 this function is responsible for sending out an announcement
 121 MAILSLOT browse packet. it contains information such as the
 122 time to live, name of the server, services that the server
 123 offers etc.
 124
 125 the format of this MAILSLOT browse packet is described in
 126 draft-heizer-cifs-v1-spec-00.txt 3.9.50.4.1 page 165-6.
 127
 128
 129 /*************************************************************************
 130   announce_backup()
 131   *************************************************************************/
 132
 133 this function is responsible for getting master browsers and domain
 134 controllers to send us lists of backup servers. this is done by
 135 sending an ANN_GetBackupListReq browse mailslot.
 136
 137 the master browser, or primary domain controller, should respond
 138 with an ANN_GetBackupListResp browse mailslot containing the list
 139 of backup servers.
 140
 141 --------------
 142 NOTE FROM TRIDGE: I don't see why nmbd should ever send one of
 143 these. The only reason I can see for any part of Samba sending one of
 144 these is if we implement it in smbclient.
 145
 146 This packet is used to request a list of backup master browsers from
 147 the master browser. It is used by clients (not servers!) to spread the
 148 browse load over more than one server. The only server that needs to
 149 know what the list of backups is is the master browser, and as it is
 150 also responsible for generating this list it will never ask anyone
 151 else for it.
 152 --------------
 153
 154
 155 /*************************************************************************
 156   sync_server()
 157   *************************************************************************/
 158
 159 this function is responsible for initiating a sync browse list
 160 sequence and, if necessary, carrying out an ANN_MasterAnnouncement
 161 to the primary domain controller (that we are also sync'ing
 162 browse lists with).
 163
 164 see nameservresp.c:response_name_status_check().
 165
 166
 167 /*************************************************************************
 168   announce_request()
 169   *************************************************************************/
 170
 171 this function is responsible for sending an announcement request to
 172 another server. this server should respond with an announcement.
 173
 174 if the announce request is sent to WORKGROUP(0x1e) then members of
 175 the workgroup will respond (with ANN_HostAnnounce packets)
 176
 177 if the announce request is sent to WORKGROUP(0x1d) then the master
 178 browser of the workgroup should respond (ANN_LocalMasterAnnounce).
 179 this is untested.
 180
 181 if the announce request is sent to ^1^2__MSBROWSE__^2(0x1) then
 182 (and this is pure speculation), all backup browsers and master
 183 browsers should respond with ANN_DomainAnnounce packets.
 184 this is untested.
 185
 186 -----------
 187 NOTE FROM TRIDGE:
 188
 189 I had great trouble getting machines to actually respond to this
 190 packet. Either we have the format wrong or MS chose not to implement
 191 it.
 192
 193 Not implementing it doesn't break anything, it just means a new master
 194 browser won't get a complete server list as quickly.
 195
 196 Also note that this packet should be used as little as possible as it
 197 could easily cause meltdown if too many servers used it. Imagine a
 198 dozen samba servers on a net all sending this packet! You will get 244
 199 responses all within 30 seconds. now imagine 50 samba servers ....
 200
 201 So I think we should restrict ourselves to sending this packet only if
 202 we are already the master browser for a workgroup. We could send a
 203 single "announce request" when we become the master, just to prime our
 204 server lists. From then on the normal announce cycles should take care
 205 of keeping it uptodate.
 206 -----------
 207