source3/nameannounce.doc

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