updated docs to match code mods from last two or three updates. done
[samba.git] / source / nameservreply.doc
1 /*************************************************************************
2   reply_name_query()
3   *************************************************************************/
4
5 this function is responsible for replying to a NetBIOS name query.
6
7 there are two kinds of name queries: directed, and broadcast. directed
8 queries are usually sent to samba in its WINS capacity. such hosts are
9 termed 'point-to-point' hosts. broadcast queries are usually sent from
10 'broadcast' or 'mixed' hosts.
11
12 broadcasting is used by either older NetBIOS hosts, new NetBIOS hosts that
13 have not had WINS capabilities added and new NetBIOS hosts that think the
14 WINS server has died.
15
16 the samba NetBIOS name database is divided into sections, on a
17 per-subnet basis. there is also a WINS NetBIOS name database, and for
18 convenience this is added as a pseudo-subnet with the ip address of
19 255.255.255.255.
20
21 the local subnet NetBIOS name databases only contain samba's names.
22 the reason for this is that if a broadcast query is received, a NetBIOS
23 hosts is only expected to respond if that query is for one of its own
24 names (the exception to this is if a host is configured as a 'proxy'
25 server, in which case, samba should redirect the query to another WINS
26 server).
27
28 the WINS pseudo-subnet NetBIOS database contains all NetBIOS names
29 that are not 'special browser' type names (regarding this i am a
30 _bit_ confused :-). names of type 0x01, 0x1d and 0x1e i consider to
31 be 'special browser' names. at the moment. maybe.
32
33 the type of search to be initiated is determined. if the NetBIOS name
34 type is a non-special-browser name, then the WINS database is included
35 in the search.
36
37 if the name is not a special browser name, then we need to find the
38 right subnet that the query came from. this is done using
39 find_req_subnet(). this also has the benefit of stopping any queries
40 from subnets that samba does not know about.
41
42 if the query is a broadcast query, then the database of the local subnet
43 is included in the search.
44
45 the name is then searched for in the appropriate NetBIOS data structures.
46 if it is found, then we need to check whether it is appropriate for us
47 to reply to such a query.
48
49 we will only reply if the query is a directed query, the name belongs to
50 samba on that subnet, or the name is a primary domain controller type,
51 or we're doing replies on behalf of hosts on subnets not known to the
52 host issuing the query. in the latter instance, it would be appropriate
53 if samba is using a WINS server for it to forward the name query on to
54 this WINS server.
55
56 reply_name_query() then takes note of all the information that is
57 needed to construct a reply to the caller. a negative reply (if the
58 name is unknown to samba) or a positive reply (the name is known to
59 samba) is then issued.
60
61
62 /*************************************************************************
63   reply_name_status()
64   *************************************************************************/
65
66 this function is responsible for constructing a reply to a NetBIOS
67 name status query. this response contains all samba's NetBIOS names
68 on the subnet that the query came in from.
69
70 a reply will only be made if the NetBIOS name being queried exists.
71
72 see rfc1001.txt and rfc1002.txt for details of the name status reply.
73
74
75 /*************************************************************************
76   reply_name_reg()
77   *************************************************************************/
78
79 this function is responsible for updating the NetBIOS name database
80 from registration packets sent out by hosts wishing to register a
81 name, and for informing them, if necessary, if this is acceptable
82 or not.
83
84 name registration can be done by broadcast or by point-to-point,
85 i.e the registration is sent directly to samba in its capacity as
86 a WINS server.
87
88 if the name registration is done by broadcast (see rfc1001.txt 15.2.1),
89 then samba's involvement in replying is limited to whether that name
90 is owned by samba or not, on the relevant subnet.
91
92 if the name registration is done point-to-point (see rfc1001.txt 15.2.2)
93 then samba will first need to check its WINS name database records and
94 proceed accordingly.
95
96 samba looks for the appropriate subnet record that the registration
97 should be added to / checked against, using find_req_subnet().
98
99 next, the name is searched for in the local database or the WINS
100 database as appropriate.
101
102 if the name is not found, then it is added to the NetBIOS name database,
103 using add_netbios_entry(), which may choose not to add the name (not
104 that this affects the registration of the name on the network in any way).
105 it will only add names to the WINS database, and even then it will only
106 add non-special-browser type names.
107
108 if the name is found, then samba must decide whether to accept the name
109 or not. a group name is always added. for unique names, further checks
110 need to be carried out.
111
112 firstly, if the name in the database is one of samba's names, or if the
113 name in the database is a group name, then it cannot be added as a unique
114 name belonging to someone else. it is therefore rejected.
115
116 secondly, if the ip address of the name being registered does not match
117 against the ip in the database, then the unique name may belong to
118 someone else. a check needs to be carried out with the owner in case
119 they still wish to keep this name. a detailed discussion of what action
120 to take is in rfc1001.txt 15.2.2.2 and 15.2.2.3.
121
122 samba currently implements non-secured WINS, whereupon the responsibility
123 for checking the name is passed on to the host doing the registration.
124 rfc1001.txt refers to this as an END-NODE CHALLENGE REGISTRATION RESPONSE.
125 (samba itself cannot yet cope with receiving such responses if it
126 registers its names with another WINS server). 
127
128 having decided what kind of response to send (if any - acceptance of
129 name registrations by broadcast is implicit), samba will send either a
130 positive or negative NAME REGISTRATION RESPONSE, or an END-NODE CHALLENGE
131 REGISTRATION RESPONSE to the host that initially sent the registration.
132
133 whew.
134
135
136 /*************************************************************************
137   reply_name_release()
138   *************************************************************************/
139
140 this function is responsible for removing a NetBIOS name from the
141 database when a server sends a release packet.
142
143 samba looks for the appropriate subnet record that the release should
144 be removed from, using find_req_subnet(). next, the name is searched
145 for in the local database or the WINS database as appropriate.
146
147 if the name is found, it is removed from the database and a
148 positive reply is sent confirming this. if the name is not
149 found, a negative reply is sent.
150
151 a reply is _not_ sent if the release was done by broadcast: the
152 release is implicit, and we should be grateful that they bothered
153 to tell us. if the release was done by directed packet, then
154 we deal with it as a WINS server and must reply (pos / neg).
155
156 at present, the criteria for removing a name have yet to be
157 developed / experimented with. at present, the only flags that
158 are checked are the NetBIOS flags.
159
160
161 /*************************************************************************
162   send_name_response()
163   *************************************************************************/
164
165 this function is a wrap around reply_netbios_packet(). it sends
166 a response to a name registration or release packet, minimising
167 the function parameters needed to do this.
168
169 if the function is called with the parameter 'success' set to
170 True, then a positive response (to the registration or release)
171 is made (see rfc1002.txt 4.2.5 and 4.2.10). if this parameter
172 is False, then a negative response is issued (see rfc1002.txt
173 4.2.6 and 4.2.11)
174
175 if the function is called with a registration code, and the
176 parameter 'recurse' is False, then an End-Node Challenge
177 Registration response is issued (see rfc1002.txt 4.2.7)
178
179 note: this function could also easily be used for name conflict
180 demand (see rfc1002.txt 4.2.8).
181
182 note: End-Node Challenge Registration response is only sent in
183 non-secured NetBIOS Name Server implementations. samba now
184 implements secured NetBIOS Name Server functionality (see
185 rfc1001.txt 15.1.6).
186