source3/nameservresp.doc

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