aeb3d29f17a2de806e0e8a81cd34911ed333e544
[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 registered with samba in its capacity as a WINS server.
30
31 the type of search to be initiated is determined. if the packet
32 received is a point-to-point (unicast), then the WINS database
33 is included in the search.
34
35 if the search is not in the WINS database, then we need to find the
36 right subnet that the query came from. this is done using
37 find_req_subnet(). this also has the benefit of stopping any queries
38 from subnets that samba does not know about.
39
40 if the query is a broadcast query, then the database of the local subnet
41 is included in the search.
42
43 the name is then searched for in the appropriate NetBIOS data structures.
44 if it is found, then we need to check whether it is appropriate for us
45 to reply to such a query.
46
47 we will only reply if the query is a directed query, the name belongs to
48 samba on that subnet, or the name is a primary domain controller type,
49 or we're doing replies on behalf of hosts on subnets not known to the
50 host issuing the query. in the latter instance, it would be appropriate
51 if samba is using a WINS server for it to forward the name query on to
52 this WINS server.
53
54 reply_name_query() then takes note of all the information that is
55 needed to construct a reply to the caller. a negative reply (if the
56 name is unknown to samba) or a positive reply (the name is known to
57 samba) is then issued.
58
59
60 /*************************************************************************
61   reply_name_status()
62   *************************************************************************/
63
64 this function is responsible for constructing a reply to a NetBIOS
65 name status query. this response contains all samba's NetBIOS names
66 on the subnet that the query came in from.
67
68 a reply will only be made if the NetBIOS name being queried exists.
69
70 see rfc1001.txt and rfc1002.txt for details of the name status reply.
71
72
73 /*************************************************************************
74   reply_name_reg()
75   *************************************************************************/
76
77 this function is responsible for updating the NetBIOS name database
78 from registration packets sent out by hosts wishing to register a
79 name, and for informing them, if necessary, if this is acceptable
80 or not.
81
82 name registration can be done by broadcast or by point-to-point,
83 i.e the registration is sent directly to samba in its capacity as
84 a WINS server.
85
86 if the name registration is done by broadcast (see rfc1001.txt 15.2.1),
87 then samba's involvement in replying is limited to whether that name
88 is owned by samba or not, on the relevant subnet.
89
90 if the name registration is done point-to-point (see rfc1001.txt 15.2.2)
91 then samba will first need to check its WINS name database records and
92 proceed accordingly.
93
94 samba looks for the appropriate subnet record that the registration
95 should be added to / checked against, using find_req_subnet().
96
97 next, the name is searched for in the local database or the WINS
98 database as appropriate.
99
100 if the name is not found, then it is added to the NetBIOS name database,
101 using add_netbios_entry(), which may choose not to add the name (not
102 that this affects the registration of the name on the network in any way).
103 it will only add non-SELF names to the WINS database.
104
105 if the name is found, then samba must decide whether to accept the name
106 or not. a group name is always added. for unique names, further checks
107 need to be carried out.
108
109 firstly, if the name in the database is one of samba's names, or if the
110 name in the database is a group name, then it cannot be added as a unique
111 name belonging to someone else. it is therefore rejected.
112
113 secondly, if the ip address of the name being registered does not match
114 against the ip in the database, then the unique name may belong to
115 someone else. a check needs to be carried out with the owner in case
116 they still wish to keep this name. a detailed discussion of what action
117 to take is in rfc1001.txt 15.2.2.2 and 15.2.2.3.
118
119 #if 0
120
121 samba currently implements non-secured WINS, whereupon the responsibility
122 for checking the name is passed on to the host doing the registration.
123 rfc1001.txt refers to this as an END-NODE CHALLENGE REGISTRATION RESPONSE.
124 (samba itself cannot yet cope with receiving such responses if it
125 registers its names with another WINS server). 
126
127 #else
128
129 samba currently implements secured WINS, whereupon it is samba's
130 responsibility to check the unique name before allowing it to be
131 registered by the new owner.
132
133 as checking the unique name may take some time, samba must send a Wait
134 Acknowledge packet to the host that wishes to claim the name. a
135 NAME_REGISTER_CHALLENGE 'state' is then initiated, which will result
136 in a name query being issued to the current owner.
137
138 if we receive a negative response or no response, the host wishing
139 to claim the name is informed that they can have it. if we receive
140 a positive response, this host is informed that it cannot have it.
141
142 #endif
143
144 having decided what kind of response to send (if any - acceptance of
145 name registrations by broadcast is implicit), samba will send a
146 positive or negative NAME REGISTRATION RESPONSE, or an END-NODE CHALLENGE
147 REGISTRATION RESPONSE or a WAIT ACKNOWLEDGEMENT to the host that
148 initially sent the registration.
149
150
151 whew.
152
153
154 /*************************************************************************
155   send_name_response()
156   *************************************************************************/
157
158 this function is responsible for sending out a positive or a negative
159 registration response or release, or an end-node challenge registration
160 response.
161
162 it is called from reply_name_release(), reply_name_reg(),
163 dead_netbios_entry() and response_name_query_register().
164
165
166 /*************************************************************************
167   reply_name_release()
168   *************************************************************************/
169
170 this function is responsible for removing a NetBIOS name from the
171 database when a server sends a release packet.
172
173 samba looks for the appropriate subnet record that the release should
174 be removed from, using find_req_subnet(). next, the name is searched
175 for in the local database or the WINS database as appropriate.
176
177 if the name is found, it is removed from the database and a
178 positive reply is sent confirming this. if the name is not
179 found, a negative reply is sent.
180
181 a reply is _not_ sent if the release was done by broadcast: the
182 release is implicit, and we should be grateful that they bothered
183 to tell us. if the release was done by directed packet, then
184 we deal with it as a WINS server and must reply (pos / neg).
185
186 at present, the criteria for removing a name have yet to be
187 developed / experimented with. at present, the only flags that
188 are checked are the NetBIOS flags.
189