source3/nameresp.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: nameresp.doc
  21
  22    Revision History:
  23
  24    0.0 - 02jul96 : lkcl@pires.co.uk
  25    created
  26 */
  27
  28 the netbios expected response code is a key part of samba's NetBIOS
  29 handling capabilities. it allows samba to carry on dealing with
  30 other things while expecting a response from one or more hosts.
  31
  32 this allows samba to simultaneously deal with registering its names
  33 with another WINS server, register its names on its local subnets,
  34 query any hosts that have registered with samba in its capacity as
  35 a WINS server, and at a later date it will be also be able handle
  36 END-NODE CHALLENGES (see rfc1001.txt 15.2.2.2 and 15.2.2.3 - secured
  37 NBNS functionality).
  38
  39 all at once!
  40
  41 when a netbios packet is sent out by samba and it expects a response,
  42 a record of all the relevant information is kept (most importantly,
  43 the unique transaction id associated which will come back to us in
  44 a response packet is recorded, and also recorded is the reason that
  45 the original packet was sent out by samba in the first place!).
  46
  47 if a response is received, then the unique transaction identifier
  48 returned in the response packet is searched for in the expected
  49 response records. the record indicates why the initial request was
  50 made (and therefore the type of response can be verified) and
  51 appropriate action can be taken.
  52
  53 when no responses, after a number of retries, are not received, then
  54 samba may take appropriate action. this is a crucial part of samba's
  55 operation: for a key number of NetBIOS operations, no response is an
  56 implicit positive response.
  57
  58 module nameresp deals with the initial transmission, re-transmission
  59 and time-out of netbios response records.
  60
  61 module namedbresp deals with the maintenance of the list of expected
  62 responses - creation, finding and removal.
  63
  64
  65 /*************************************************************************
  66   queue_netbios_packet()
  67   *************************************************************************/
  68
  69 this function is responsible for sending out a netbios packet, and then
  70 making a record of the information that was sent out. a response will
  71 be expected later (or not, as the case may be).
  72
  73 if a response is received, response_netbios_packet() will deal with it.
  74 otherwise, it will be dealt with in expire_netbios_response_entries().
  75
  76
  77 /*************************************************************************
  78   queue_netbios_pkt_wins()
  79   *************************************************************************/
  80
  81 this function is a wrapper around queue_netbios_packet(). there is
  82 some confusion about B, M and P nodes (see rfc1001.txt section 10) -
  83 confusion introduced by luke :-) - which needs sorting out.
  84
  85 for example, rfc1001.txt 15.2.3 - an M node must attempt to register a
  86 name first as a B node, then attempt to register as an M node. negative
  87 responses on either of these attempts is a failure to register the
  88 name.
  89
  90 this is NOT the case with a P node.
  91
  92
  93 /*************************************************************************
  94   expire_netbios_response_entries()
  95   *************************************************************************/
  96
  97 this function is responsible for dealing with queued response records
  98 that have not received a response packet matching their unique
  99 transaction id.
 100
 101 if the retry count for any record is non-zero, and its time-out period
 102 has expired, the retry count is reduced, the time-out period is stepped
 103 forward and the packet is re-transmitted (from the information stored
 104 in the queued response record) with the same unique transaction id of
 105 the initial attempt at soliciting a response.
 106
 107 if the retry count is zero, then the packet is assumed to have expired.
 108 dead_netbios_entry() is called to deal with the possibility of an error
 109 or a problem (or in certain instances, no answer is an implicit
 110 positive response!).
 111
 112 the expected response record is then deleted, and the number of expected
 113 responses reduced. when this count gets to zero, listen_for_packets()
 114 will no longer time-out for 1 second on account of expecting response
 115 packets.
 116
 117
 118 /*************************************************************************
 119   dead_netbios_entry()
 120   *************************************************************************/
 121
 122 this function is responsible for dealing with the case when a NetBIOS
 123 response to a packet sent out by samba was not received. for certain
 124 transactions, this may be normal. for others, under certain conditions
 125 it may constitute either an error or a problem with or failure of one
 126 or more hosts.
 127
 128 - NAME_QUERY_CONFIRM
 129
 130 when a samba 'state' of type NAME_QUERY_CONFIRM is sent, a response
 131 may or may not be forthcoming. if no response is received to a unique
 132 name, then the record is removed from samba's WINS database. non-unique
 133 names are simply expected to die off on a time-to-live basis (see
 134 rfc1001.txt 15.1.3.4)
 135
 136 query_refresh_names() issues this samba 'state'
 137 response_name_query_sync() deals with responses to NAME_QUERY_CONFIRM.
 138
 139 - NAME_QUERY_MST_CHK
 140
 141 when a samba 'state' of type NAME_QUERY_MST_CHK is sent, and a response
 142 is not received, this implies that a master browser will have failed.
 143 remedial action may need to be taken, for example if samba is a member
 144 of that workgroup and it is also a potential master browser it could
 145 force an election.
 146
 147 check_master_browser() issues this samba 'state'.
 148 response_process() does nothing if a response is received. this is normal.
 149
 150 - NAME_RELEASE
 151
 152 when a samba 'state' of type NAME_RELEASE is sent, and a response is
 153 not received, it is assumed to be acceptable to release the name. if the
 154 original response was sent to another WINS server, then that WINS server
 155 may be inaccessible or may have failed. if so, then at a later date
 156 samba should take this into account (see rfc1001.txt 10.3).
 157
 158 remove_name_entry() issues this samba 'state'
 159 response_name_rel() deals with responses to NAME_RELEASE.
 160
 161 - NAME_REGISTER
 162
 163 when a samba 'state' of type NAME_REGISTER is sent, and a response is
 164 not received, if the registration was done by broadcast, it is assumed
 165 that there are no objections to the registration of this name, and samba
 166 adds the name to the appropriate subnet record name database. if the
 167 registration was point-to-point (i.e with another WINS server) then that
 168 WINS server may be inaccessible or may have failed. if so, then at a later
 169 date samba should take this into account (see rfc1001.txt 10.3).
 170
 171 add_my_name_entry() issues this samba 'state'
 172 response_name_reg() deals with responses to NAME_REGISTER.
 173
 174 no action is taken for any other kinds of samba 'states' if a response
 175 is not received. this is not to say that action may not be appropriate,
 176 just that it's not been looked at yet :-)
 177
 178