source3/nameservresp.doc

   1 /*
   2    Unix SMB/Netbios documentation.
   3    Version 0.0
   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: nameservresp.doc
  21
  22    Revision History:
  23
  24    0.0 - 02jul96 : lkcl@pires.co.uk
  25    created
  26 */
  27
  28 this module deals with the receipt of response packets. the
  29 response packets are expected to be received, and there is a
  30 record of this kept (see also: modules nameresp and namedbresp)
  31
  32 point of interest to design purists: every function in this
  33 module is static except response_netbios_packet().
  34
  35 /*************************************************************************
  36   response_netbios_packet()
  37   *************************************************************************/
  38
  39 this function receives netbios response packets. the samba server
  40 (or a rogue tcp/ip system, or nmblookup) will have sent out a packet
  41 requesting a response. a client (or a rogue tcp/ip system) responds
  42 to that request.
  43
  44 this function checks the validity of the packet it receives.
  45 the expected response records are searched for the transaction id,
  46 to see if it's a response expected by the samba server. if it isn't
  47 it's reported as such, and ignored.
  48
  49 if the response is found, then the subnet it was expected from will
  50 also have been found. the subnet it actually came in on can be
  51 checked against the subnet it was expected from and reported,
  52 otherwise this function just carries on.
  53
  54 the number of responses received is increased, and the number of
  55 retries left to be sent is set to zero.
  56
  57 after debug information is reported, and validation of the netbios
  58 packet (e.g only one response from one machine is expected for some
  59 functions) has occurred, the packet is processed. when the initial
  60 request was sent out, the expected response record was flagged with,
  61 for lack of a better word, a samba 'state' type. whenever a
  62 response is received, the appropriate function is called to carry on
  63 where the program control flow was interrupted while awaiting exactly
  64 such a response.
  65
  66 please note that _not_ receiving a response is dealt with in another
  67 area of code - expire_netbios_response_entries().
  68
  69
  70 /*************************************************************************
  71   response_name_query_sync()
  72   *************************************************************************/
  73
  74 this function receives responses to samba 'states' NAME_QUERY_SYNC and
  75 NAME_QUERY_CONFIRM.
  76
  77 NAME_QUERY_SYNC: name query a server before synchronising browse lists.
  78 NAME_QUERY_CONFIRM: name query a server to check that it's alive.
  79
  80 a NAME_QUERY_SYNC will be carried out in order to check that a server
  81 is alive before syncing browse lists. we don't want to delay the SMB
  82 NetServerEnum api just because the server has gone down: we have too
  83 much else to do.
  84
  85 a NAME_QUERY_CONFIRM is just a name query to see whether the server is
  86 alive.  these queries are sent out by samba's WINS server side, to verify
  87 its netbios name database of all machines that have registered with it.
  88
  89 we don't normally expect a negative response from such a query, although
  90 we may do so if the query was sent to another WINS server. the registered
  91 entry should be removed if we receive a negative response.
  92
  93
  94 /*************************************************************************
  95   response_name_status_check()
  96   *************************************************************************/
  97
  98 this function receives responses to samba 'states' NAME_STATUS_SRV_CHK
  99 and NAME_STATUS_DOM_SRV_CHK
 100
 101 NAME_STATUS_DOM_SRV_CHK: name status a domain master browser
 102                           confirm its domain and then initiate syncing
 103                           its browse list.
 104
 105 NAME_STATUS_SRV_CHK: same as NAME_STATUS_DOM_SRV_CHK except the
 106                      name status is issued to a master browser.
 107
 108 if we don't know what workgroup a server is responsible for, but we
 109 know that there is a master browser at a certain ip, we can issue a
 110 name status check. from the response received, there will be
 111 a master browser netbios entry. this will allow us to synchronise
 112 browse lists with that machine and then add the information to the
 113 correct part of samba's workgroup - server database.
 114
 115
 116 /*************************************************************************
 117   response_server_check()
 118   *************************************************************************/
 119
 120 this function receives responses to samba 'states' NAME_QUERY_DOM_SRV_CHK,
 121 NAME_QUERY_SRV_CHK and NAME_QUERY_FIND_MST.
 122
 123 NAME_QUERY_FIND_MST: issued as a broadcast when we wish to find out all
 124                      master browsers (i.e all servers that have registered
 125                      the NetBIOS name ^1^2__MSBROWSE__^2(0x1), and then
 126                      issue a NAME_STATUS_MASTER_CHECK on any servers that
 127                      respond, which will initiate a sync browse lists.
 128
 129 NAME_QUERY_DOM_SRV_CHK: same as a NAME_QUERY_FIND_MST except this is sent
 130                         to a domain master browser.
 131
 132 NAME_QUERY_SRV_CHK: same as a NAME_QUERY_DOM_SRV_CHK except this is sent to
 133                     a master browser.
 134
 135 the purpose of each of these states is to do a broadcast name query, or
 136 a name query directed at a WINS server, then to all hosts that respond,
 137 we issue a name status check, which will confirm for us the workgroup
 138 or domain name, and then initiate issuing a sync browse list call with
 139 that server.
 140
 141 a NAME_QUERY_SRV_CHK is sent when samba receives a list of backup
 142 browsers. it checks to see if that server is alive (by doing a
 143 name query on a server) and then syncs browse lists with it.
 144
 145
 146 /*************************************************************************
 147   response_name_reg()
 148   *************************************************************************/
 149
 150 this function is responsible for dealing with samba's registration
 151 attempts, by broadcast to a local subnet, or point-to-point with
 152 another WINS server.
 153
 154 please note that it cannot cope with END-NODE CHALLENGE REGISTRATION
 155 RESPONSEs at present.
 156
 157 when a response is received, samba determines if the response is a
 158 positive or a negative one. if it is a positive response, the name
 159 is added to samba's database.
 160
 161 when a negative response is received, samba will remove the name
 162 from its database. if, however, the name is a browser type (0x1b is
 163 a domain master browser type name; or 0x1d, which is a local master
 164 browser type name) then it must also stop being a domain master
 165 browser or master browser respectively, depending on what kind
 166 of name was rejected.
 167
 168 (when no response is received, then expire_netbios_response_entries()
 169 is expected to deal with this. the only case that is dealt with here
 170 at present is when the registration was done by broadcast. if there
 171 is no challenge to the broadcast registration, it is implicitly
 172 assumed that claiming the name is acceptable).
 173
 174
 175 /*************************************************************************
 176   response_name_release()
 177   *************************************************************************/
 178
 179 this function is responsible for removing samba's NetBIOS name when
 180 samba contacts another WINS server with which it had registered the
 181 name.
 182
 183 only positive name releases are expected and dealt with. exactly what
 184 to do if a negative name release (i.e someone says 'oi! you have to
 185 keep that name!') is received is uncertain.
 186
 187 (when no response is received, then expire_netbios_response_entries()
 188 is expected to deal with this. if there is no challenge to the release
 189 of the name, the name is then removed from that subnet's NetBIOS
 190 name database).
 191