source3/nameserv.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: nameserv.doc
  21
  22    Revision History:
  23
  24    0.0 - 02jul96 : lkcl@pires.co.uk
  25    created
  26 */
  27
  28 this module deals with general maintenance of NetBIOS names.
  29
  30 /*************************************************************************
  31   query_refresh_names()
  32   *************************************************************************/
  33
  34 this function is responsible for polling all names registered in the
  35 WINS database. it is planned to enable this function should samba
  36 detect an inconsistency on the network, which could occur if the
  37 samba NetBIOS daemon dies and is restarted.
  38
  39 polling is done very infrequently, but all names will be covered
  40 within a period NAME_POLL_REFRESH_TIME. a group of at most ten names
  41 will be queried at once, at intervals of NAME_POLL_INTERVAL seconds.
  42 if the total number of names queried in this way will take too long,
  43 then the time that an individual name will next be polled is
  44 increased accordingly.
  45
  46 name query polling is functionality over-and-above the normal
  47 requirement (see rfc1001.txt 15.1.7 point 7). it is normally the
  48 responsibility of the owner of a name to re-register the name at
  49 regular intervals.
  50
  51
  52 /*************************************************************************
  53   refresh_my_names()
  54   *************************************************************************/
  55
  56 this function is responsible for refreshing samba's names that have
  57 been registered with other servers on a local subnet, or with another
  58 WINS server if samba is using one.
  59
  60 samba's names' refresh_time will be updated through the use of the function
  61 add_my_name_entry().
  62
  63
  64 /*************************************************************************
  65   remove_my_names()
  66   *************************************************************************/
  67
  68 this function is responsible for removing all samba's SELF names. it
  69 is used when samba receives a SIG_TERM. samba at present does not wait
  70 for the WINS server to reply to the name releases sent out.
  71
  72
  73 /*************************************************************************
  74   add_my_names()
  75   *************************************************************************/
  76
  77 this function is responsible for adding and registering if necessary all
  78 samba's SELF names, on each of its local subnets and with another WINS
  79 server if samba is using one.
  80
  81 /*************************************************************************
  82   add_my_name_entry()
  83   *************************************************************************/
  84
  85 this function is responsible for registering or re-registering one of
  86 samba's names, either on the local subnet or with another WINS server
  87 if samba is using one.
  88
  89 if the name is already in samba's database, then it is re-registered,
  90 otherwise it is simply registered.
  91
  92 if the name is being registered in a WINS capacity (the subnet to which
  93 the name should be added is the WINS pseudo-subnet) then we add the entry
  94 immediately if samba is a WINS server. it uses name_register_work()
  95 because if the name is being added as part of becoming a master browser,
  96 we want to carry on that process. if the name is registered with another
  97 WINS server, we must wait for an answer from that WINS server. either
  98 name_register_work() or name_unregister_work() will be called as a result.
  99
 100 if the name is being registered on a local subnet, then it is
 101 broadcast. an explicit rejection from another host will result
 102 in name_unregister_work() being called. no response will, after
 103 retrying, result in name_register_work() being called.
 104
 105 what ever method is used, the name will either be registered
 106 or rejected, and what ever process was taking place (becoming
 107 a master browser for example) will carry on.
 108
 109 expire_netbios_response_entries() is responsible for taking further
 110 action if no response to the registration is received.
 111
 112 note that there may be a large number of function calls on the
 113 stack if become_master() is called and samba is configured as
 114 a WINS server. the loop will be:
 115
 116 become_master(), add_my_name_entry(), name_register_work() and
 117 back to become_master() with the new value of the workgroup
 118 'state'.
 119
 120
 121 /*************************************************************************
 122   remove_name_entry()
 123   *************************************************************************/
 124
 125 this function is responsible for removing a NetBIOS name. if the name
 126 being removed is registered on a local subnet, a name release should be
 127 broadcast on the local subnet.
 128
 129 if the name is being released in a WINS capacity (the subnet to
 130 which the name should be added is the WINS pseudo-subnet) then we
 131 remove the entry immediately if samba is a WINS server. it uses
 132 name_unregister_work() because if the name is being added as part of
 133 becoming a master browser, we want to terminate that process. if the
 134 name is released from another WINS server, we must wait for an
 135 answer from that WINS server. name_unregister_work() will
 136 definitely be called as a result, because at present we ignore
 137 negative responses for a name release from a WINS server.
 138
 139 if the name is being releasedd on a local subnet, then it is
 140 broadcast. name_unregister_work() will definitely be called
 141 because we ignore negative name releases at present.
 142
 143 what ever method is used, the name will be released. (NOT TRUE!
 144 see response_name_release())
 145
 146 expire_netbios_response_entries() is responsible for taking further action
 147 if no response to the name release is received.
 148
 149
 150 /*************************************************************************
 151   load_netbios_names()
 152   *************************************************************************/
 153
 154 this function is responsible for loading any NetBIOS names that samba,
 155 in its WINS capacity, has written out to disk. all the relevant details
 156 are recorded in this file, including the time-to-live. should the
 157 time left to live be small, the name is not added back in to samba's
 158 WINS database.
 159