JHT ==> Been playing again! Whooooooo!
[samba.git] / docs / textdocs / BROWSING.txt
1 Author/s:       Many (Thanks to Luke, Jeremy, Andrew, etc.)
2 Updated:        June 29, 1997
3 Status:         Current - For VERY Advanced Users ONLY
4
5 Summary: This describes how to configure Samba for improved browsing.
6 =====================================================================
7
8 OVERVIEW:
9 =========
10 SMB networking provides a mechanism by which clients can access a list
11 of machines that are available within the network. This list is called
12 the browse list and is heavily used by all SMB clients. Configuration
13 of SMB browsing has been problematic for some Samba users, hence this
14 document.
15
16 =====================================================================
17
18 BROWSING
19 ========
20 Samba now fully supports browsing. The browsing is supported by nmbd
21 and is also controlled by options in the smb.conf file (see smb.conf(5)).
22
23 Samba can act as a local browse master for a workgroup and the ability
24 for samba to support domain logons and scripts is now available.  See
25 DOMAIN.txt for more information on domain logons.
26
27 Samba can also act as a domain master browser for a workgroup.  This
28 means that it will collate lists from local browse masters into a
29 wide area network server list.  In order for browse clients to
30 resolve the names they may find in this list, it is recommended that
31 both samba and your clients use a WINS server
32
33 Note that you should NOT set Samba to be the domain master for a
34 workgroup that has the same name as an NT Domain.
35
36 [Note that nmbd can be configured as a WINS server, but it is not
37 necessary to specifically use samba as your WINS server.  NTAS can
38 be configured as your WINS server.  In a mixed NT server and
39 samba environment on a Wide Area Network, it is recommended that
40 you use the NT server's WINS server capabilities.  In a samba-only
41 environment, it is recommended that you use one and only one nmbd
42 as your WINS server].
43
44 To get browsing to work you need to run nmbd as usual, but will need
45 to use the "workgroup" option in smb.conf to control what workgroup
46 Samba becomes a part of.
47
48 Samba also has a useful option for a Samba server to offer itself for
49 browsing on another subnet.  It is recommended that this option is only
50 used for 'unusual' purposes: announcements over the internet, for
51 example. See "remote announce" in the smb.conf man page. 
52
53 If something doesn't work then hopefully the log.nmb file will
54 help you track down the problem. Try a debug level of 2 or 3 for
55 finding problems.
56
57 Note that if it doesn't work for you, then you should still be able to
58 type the server name as \\SERVER in filemanager then hit enter and
59 filemanager should display the list of available shares.
60
61 Some people find browsing fails because they don't have the global
62 "guest account" set to a valid account. Remember that the IPC$
63 connection that lists the shares is done as guest, and thus you must
64 have a valid guest account.
65
66 Also, a lot of people are getting bitten by the problem of too many
67 parameters on the command line of nmbd in inetd.conf. This trick is to
68 not use spaces between the option and the parameter (eg: -d2 instead
69 of -d 2), and to not use the -B and -N options. New versions of nmbd
70 are now far more likely to correctly find your broadcast and network
71 addess, so in most cases these aren't needed.
72
73 The other big problem people have is that their broadcast address,
74 netmask or IP address is wrong (specified with the "interfaces" option
75 in smb.conf)
76
77 BROWSING ACROSS SUBNETS
78 =======================
79
80 With the release of Samba 1.9.17(alpha1 and above) Samba has been
81 updated to enable it to support the replication of browse lists
82 across subnet boundaries. New code and options have been added to
83 achieve this. This section describes how to set this feature up
84 in different settings.
85
86 To see browse lists that span TCP/IP subnets (ie. networks separated
87 by routers that don't pass broadcast traffic) you must set up at least
88 one WINS server. The WINS server acts as a DNS for NetBIOS names, allowing
89 NetBIOS name to IP address translation to be done by doing a direct
90 query of the WINS server. This is done via a directed UDP packet on
91 port 137 to the WINS server machine. The reason for a WINS server is
92 that by default, all NetBIOS name to IP address translation is done
93 by broadcasts from the querying machine. This means that machines
94 on one subnet will not be able to resolve the names of machines on
95 another subnet without using a WINS server.
96
97 Remember, for browsing across subnets to work correctly, all machines,
98 be they Windows 95, Windows NT, or Samba servers must have the IP address
99 of a WINS server given to them by a DHCP server, or by manual configuration 
100 (for Win95 and WinNT, this is in the TCP/IP Properties, under Network 
101 settings) for Samba this is in the smb.conf file.
102
103 How does cross subnet browsing work ?
104 =====================================
105
106 Cross subnet browsing is a complicated dance, containing multiple
107 moving parts. It has taken Microsoft several years to get the code
108 that achieves this correct, and Samba lags behind in some areas.
109 However, with the 1.9.17 release, Samba is capable of cross subnet
110 browsing when configured correctly.
111
112 Consider a network set up as follows :
113
114                                    (DMB)
115              N1_A      N1_B        N1_C       N1_D        N1_E
116               |          |           |          |           |
117           -------------------------------------------------------
118             |          subnet 1                       |
119           +---+                                      +---+
120           |R1 | Router 1                  Router 2   |R2 |
121           +---+                                      +---+
122             |                                          |
123             |  subnet 2              subnet 3          |
124   --------------------------       ------------------------------------
125   |     |     |      |               |        |         |           |
126  N2_A  N2_B  N2_C   N2_D           N3_A     N3_B      N3_C        N3_D 
127                     (WINS)
128
129 Consisting of 3 subnets (1, 2, 3) conneted by two routers
130 (R1, R2) - these do not pass broadcasts. Subnet 1 has 5 machines
131 on it, subnet 2 has 4 machines, subnet 3 has 4 machines. Assume
132 for the moment that all these machines are configured to be in the
133 same workgroup (for simplicities sake). Machine N1_C on subnet 1
134 is configured as Domain Master Browser (ie. it will collate the
135 browse lists for the workgroup). Machine N2_D is configured as
136 WINS server and all the other machines are configured to register
137 their NetBIOS names with it.
138
139 As all these machines are booted up, elections for master browsers
140 will take place on each of the three subnets. Assume that machine
141 N1_C wins on subnet 1, N2_B wins on subnet 2, and N3_D wins on
142 subnet 3 - these machines are known as local master browsers for
143 their particular subnet. N1_C has an advantage in winning as the
144 local master browser on subnet 1 as it is set up as Domain Master
145 Browser.
146
147 On each of the three networks, machines that are configured to 
148 offer sharing services will broadcast that they are offering
149 these services. The local master browser on each subnet will
150 receive these broadcasts and keep a record of the fact that
151 the machine is offering a service. This list of records is
152 the basis of the browse list. For this case, assume that
153 all the machines are configured to offer services so all machines
154 will be on the browse list.
155
156 For each network, the local master browser on that network is
157 considered 'authoritative' for all the names it receives via
158 local broadcast. This is because a machine seen by the local
159 master browser via a local broadcast must be on the same 
160 network as the local master browser and thus is a 'trusted'
161 and 'verifiable' resource. Machines on other networks that
162 the local master browsers learn about when collating their
163 browse lists have not been directly seen - these records are
164 called 'non-authoritative'.
165
166 At this point the browse lists look as follows (these are 
167 the machines you would see in your network neighborhood if
168 you looked in it on a particular network right now).
169
170 Subnet           Browse Master   List
171 ------           -------------   ----
172 Subnet1          N1_C            N1_A, N1_B, N1_C, N1_D, N1_E
173
174 Subnet2          N2_B            N2_A, N2_B, N2_C, N2_D
175
176 Subnet3          N3_D            N3_A, N3_B, N3_C, N3_D
177
178 Note that at this point all the subnets are separate, no
179 machine is seen across any of the subnets.
180
181 Now examine subnet 2. As soon as N2_B has become the local
182 master browser it looks for a Domain master browser to synchronize
183 its browse list with. It does this by querying the WINS server
184 (N2_D) for the IP address associated with the NetBIOS name 
185 WORKGROUP<1B>. This name was registerd by the Domain master
186 browser (N1_C) with the WINS server as soon as it was booted.
187
188 Once N2_B knows the address of the Domain master browser it
189 tells it that is the local master browser for subnet 2 by
190 sending a MasterAnnouncement packet as a UDP port 138 packet.
191 It then synchronizes with it by doing a NetServerEnum2 call. This
192 tells the Domain Master Browser to send it all the server
193 names it knows about. Once the domain master browser receives
194 the MasterAnnouncement packet it schedules a synchronization
195 request to the sender of that packet. After both synchronizations
196 are done the browse lists look like :
197
198 Subnet           Browse Master   List
199 ------           -------------   ----
200 Subnet1          N1_C            N1_A, N1_B, N1_C, N1_D, N1_E, 
201                                  N2_A(*), N2_B(*), N2_C(*), N2_D(*)
202
203 Subnet2          N2_B            N2_A, N2_B, N2_C, N2_D
204                                  N1_A(*), N1_B(*), N1_C(*), N1_D(*), N1_E(*)
205
206 Subnet3          N3_D            N3_A, N3_B, N3_C, N3_D
207
208 Servers with a (*) after them are non-authoritative names.
209
210 At this point users looking in their network neighborhood on
211 subnets 1 or 2 will see all the servers on both, users on
212 subnet 3 will still only see the servers on their own subnet.
213
214 The same sequence of events that occured for N2_B now occurs
215 for the local master browser on subnet 3 (N3_D). When it
216 synchronizes browse lists with the domain master browser (N1_A)
217 it gets both the server entries on subnet 1, and those on
218 subnet 2. After N3_D has synchronized with N1_C and vica-versa
219 the browse lists look like.
220
221 Subnet           Browse Master   List
222 ------           -------------   ----
223 Subnet1          N1_C            N1_A, N1_B, N1_C, N1_D, N1_E, 
224                                  N2_A(*), N2_B(*), N2_C(*), N2_D(*),
225                                  N3_A(*), N3_B(*), N3_C(*), N3_D(*)
226
227 Subnet2          N2_B            N2_A, N2_B, N2_C, N2_D
228                                  N1_A(*), N1_B(*), N1_C(*), N1_D(*), N1_E(*)
229
230 Subnet3          N3_D            N3_A, N3_B, N3_C, N3_D
231                                  N1_A(*), N1_B(*), N1_C(*), N1_D(*), N1_E(*),
232                                  N2_A(*), N2_B(*), N2_C(*), N2_D(*)
233
234 Servers with a (*) after them are non-authoritative names.
235
236 At this point users looking in their network neighborhood on
237 subnets 1 or 3 will see all the servers on all sunbets, users on
238 subnet 2 will still only see the servers on subnets 1 and 2, but not 3.
239
240 Finally, the local master browser for subnet 2 (N2_B) will sync again
241 with the domain master browser (N1_C) and will recieve the missing
242 server entries. Finally - and as a steady state (if no machines
243 are removed or shut off) the browse lists will look like :
244
245 Subnet           Browse Master   List
246 ------           -------------   ----
247 Subnet1          N1_C            N1_A, N1_B, N1_C, N1_D, N1_E, 
248                                  N2_A(*), N2_B(*), N2_C(*), N2_D(*),
249                                  N3_A(*), N3_B(*), N3_C(*), N3_D(*)
250
251 Subnet2          N2_B            N2_A, N2_B, N2_C, N2_D
252                                  N1_A(*), N1_B(*), N1_C(*), N1_D(*), N1_E(*)
253                                  N3_A(*), N3_B(*), N3_C(*), N3_D(*)
254
255 Subnet3          N3_D            N3_A, N3_B, N3_C, N3_D
256                                  N1_A(*), N1_B(*), N1_C(*), N1_D(*), N1_E(*),
257                                  N2_A(*), N2_B(*), N2_C(*), N2_D(*)
258
259 Servers with a (*) after them are non-authoritative names.
260
261 Synchronizations between the domain master browser and local
262 master browsers will continue to occur, but this should be a
263 steady state situation.
264
265 If either router R1 or R2 fails the following will occur:
266
267 1) Names of computers on each side of the inaccessible network fragments
268 will be maintained for as long as 36 minutes, in the network neighbourhood
269 lists.
270
271 2) Attempts to connect to these inaccessible computers will fail, but the
272 names will not be removed from the network neighbourhood lists.
273
274 3) If one of the fragments is cut off from the WINS server, it will only
275 be able to access servers on its local subnet, by using subnet-isolated
276 broadcast NetBIOS name resolution. The effects are similar to that of
277 losing access to a DNS server.
278
279 Setting up a WINS server
280 ========================
281
282 Either a Samba machine or a Windows NT Server machine may be set up
283 as a WINS server. To set a Samba machine to be a WINS server you must
284 add the following option to the smb.conf file on the selected machine :
285 in the [globals] section add the line 
286
287         wins support = yes
288
289 Versions of Samba previous to 1.9.17 had this parameter default to
290 yes. If you have any older versions of Samba on your network it is
291 strongly suggested you upgrade to 1.9.17 or above, or at the very
292 least set the parameter to 'no' on all these machines.
293
294 Machines with "wins support = yes" will keep a list of all NetBIOS
295 names registered with them, acting as a DNS for NetBIOS names.
296
297 You should set up only ONE wins server. Do NOT set the
298 "wins support = yes" option on more than one Samba server.
299
300 To set up a Windows NT Server as a WINS server you need to set up
301 the WINS service - see your NT documentation for details. Note that
302 Windows NT WINS Servers can replicate to each other, allowing more
303 than one to be set up in a complex subnet environment. As Microsoft
304 refuse to document these replication protocols Samba cannot currently
305 participate in these replications. It is possible in the future that
306 a Samba->Samba WINS replication protocol may be defined, in which
307 case more than one Samba machine could be set up as a WINS server
308 but currently only one Samba server should have the "wins support = yes"
309 parameter set.
310
311 After the WINS server has been configured you must ensure that all
312 machines participating on the network are configured with the address
313 of this WINS server. If your WINS server is a Samba machine, fill in
314 the Samba machine IP address in the "Primary WINS Server" field of
315 the "Control Panel->Network->Protocols->TCP->WINS Server" dialogs
316 in Windows 95 or Windows NT. To tell a Samba server the IP address
317 of the WINS server add the following line to the [global] section of
318 all smb.conf files :
319
320         wins server = <name or IP address>
321
322 where <name or IP address> is either the DNS name of the WINS server
323 machine or it's IP address.
324
325 Note that this line MUST NOT BE SET in the smb.conf file of the Samba
326 server acting as the WINS server itself. If you set both the
327 "wins support = yes" option and the "wins server = <name>" option then
328 nmbd will fail to start.
329
330 There are two possible scenarios for setting up cross subnet browsing.
331 The first details setting up cross subnet browsing on a network containing
332 Windows 95, Samba and Windows NT machines that are not configured as
333 part of a Windows NT Domain. The second details setting up cross subnet
334 browsing on networks that contain NT Domains.
335
336 Setting up Browsing in a WORKGROUP
337 ==================================
338
339 To set up cross subnet browsing on a network containing machines
340 in up to be in a WORKGROUP, not an NT Domain you need to set up one
341 Samba server to be the Domain Master Browser (note that this is *NOT*
342 the same as a Primary Domain Controller, although in an NT Domain the
343 same machine plays both roles). The role of a Domain master browser is
344 to collate the browse lists from local master browsers on all the
345 subnets that have a machine participating in the workgroup. Without
346 one machine configured as a domain master browser each subnet would
347 be an isolated workgroup, unable to see any machines on any other
348 subnet. It is the presense of a domain master browser that makes
349 cross subnet browsing possible for a workgroup.
350
351 In an WORKGROUP environment the domain master browser must be a
352 Samba server, and there must only be one domain master browser per
353 workgroup name (although the same Samba server can act as Domain
354 master browser for multiple workgroup names). To set up a Samba
355 server as a domain master browser set the following option in the
356 [global] section of the smb.conf file :
357
358         domain master = yes
359
360 The domain master browser should also preferrably be the local master
361 browser for it's own subnet. In order to achieve this set the following
362 options in the [global] section of the smb.conf file :
363
364         domain master = yes
365         local master = yes
366         preferred master = yes
367         os level = 65
368
369 The domain master browser may be the same machine as the WINS
370 server, if you require.
371
372 Next, you should ensure that each of the subnets contains a
373 machine that can act as a local master browser for the
374 workgroup. Any NT machine should be able to do this, as will
375 Windows 95 machines (although these tend to get rebooted more
376 often, so it's not such a good idea to use these). To make a 
377 Samba server a local master browser set the following
378 options in the [global] section of the smb.conf file :
379
380         domain master = no
381         local master = yes
382         preferred master = yes
383         os level = 65
384
385 Do not do this for more than one Samba server on each subnet,
386 or they will war with each other over which is to be the local
387 master browser.
388
389 The "local master" parameter allows Samba to act as a local master
390 browser. The "preferred master" causes nmbd to force a browser
391 election on startup and the "os level" parameter sets Samba high
392 enough so that it should win any browser elections.
393
394 If you have an NT machine on the subnet that you wish to
395 be the local master browser then you can disable Samba from
396 becoming a local master browser by setting the following
397 options in the [global] section of the smb.conf file :
398
399         domain master = no
400         local master = no
401         preferred master = no
402         os level = 0
403
404 Setting up Browsing in a DOMAIN
405 ===============================
406
407 If you are adding Samba servers to a Windows NT Domain then
408 you must not set up a Samba server as a domain master browser.
409 By default, a Windows NT Primary Domain Controller for a Domain
410 name is also the Domain master browser for that name, and many
411 things will break if a Samba server registers the Domain master
412 browser NetBIOS name (DOMAIN<1B>) with WINS instead of the PDC.
413
414 For subnets other than the one containing the Windows NT PDC
415 you may set up Samba servers as local master browsers as
416 described. To make a Samba server a local master browser set 
417 the following options in the [global] section of the smb.conf 
418 file :
419
420         domain master = no
421         local master = yes
422         preferred master = yes
423         os level = 65
424
425 If you wish to have a Samba server fight the election with machines
426 on the same subnet you may set the "os level" parameter to lower
427 levels. By doing this you can tune the order of machines that
428 will become local master browsers if they are running. For
429 more details on this see the section "FORCING SAMBA TO BE THE MASTER"
430 below.
431
432 If you have Windows NT machines that are members of the domain
433 on all subnets, and you are sure they will always be running then
434 you can disable Samba from taking part in browser elections and
435 ever becoming a local master browser by setting following options 
436 in the [global] section of the smb.conf file :
437  
438         domain master = no
439         local master = no
440         preferred master = no
441         os level = 0
442
443 FORCING SAMBA TO BE THE MASTER
444 ==============================
445
446 Who becomes the "master browser" is determined by an election process
447 using broadcasts. Each election packet contains a number of parameters
448 which determine what precedence (bias) a host should have in the
449 election. By default Samba uses a very low precedence and thus loses
450 elections to just about anyone else.
451
452 If you want Samba to win elections then just set the "os level" global
453 option in smb.conf to a higher number. It defaults to 0. Using 34
454 would make it win all elections over every other system (except other
455 samba systems!)
456
457 A "os level" of 2 would make it beat WfWg and Win95, but not NTAS. A
458 NTAS domain controller uses level 32.
459
460 The maximum os level is 255
461
462 If you want samba to force an election on startup, then set the
463 "preferred master" global option in smb.conf to "yes".  Samba will
464 then have a slight advantage over other potential master browsers
465 that are not preferred master browsers.  Use this parameter with
466 care, as if you have two hosts (whether they are windows 95 or NT or
467 samba) on the same local subnet both set with "preferred master" to
468 "yes", then periodically and continually they will force an election
469 in order to become the local master browser.
470
471 If you want samba to be a "domain master browser", then it is
472 recommended that you also set "preferred master" to "yes", because
473 samba will not become a domain master browser for the whole of your
474 LAN or WAN if it is not also a local master browser on its own
475 broadcast isolated subnet.
476
477 It is possible to configure two samba servers to attempt to become
478 the domain master browser for a domain.  The first server that comes
479 up will be the domain master browser.  All other samba servers will
480 attempt to become the domain master browser every 5 minutes.  They
481 will find that another samba server is already the domain master
482 browser and will fail.  This provides automatic redundancy, should
483 the current domain master browser fail.
484  
485
486 MAKING SAMBA THE DOMAIN MASTER
487 ==============================
488
489 The domain master is responsible for collating the browse lists of
490 multiple subnets so that browsing can occur between subnets. You can
491 make samba act as the domain master by setting "domain master = yes"
492 in smb.conf. By default it will not be a domain master.
493
494 Note that you should NOT set Samba to be the domain master for a
495 workgroup that has the same name as an NT Domain.
496
497 When samba is the domain master and the master browser it will listen
498 for master announcements (made roughly every twelve minutes) from local
499 master browsers on other subnets and then contact them to synchronise
500 browse lists.
501
502 If you want samba to be the domain master then I suggest you also set
503 the "os level" high enough to make sure it wins elections, and set
504 "preferred master" to "yes", to get samba to force an election on
505 startup.
506
507 Note that all your servers (including samba) and clients should be
508 using a WINS server to resolve NetBIOS names.  If your clients are only
509 using broadcasting to resolve NetBIOS names, then two things will occur:
510
511 a) your local master browsers will be unable to find a domain master
512    browser, as it will only be looking on the local subnet.
513
514 b) if a client happens to get hold of a domain-wide browse list, and
515    a user attempts to access a host in that list, it will be unable to
516    resolve the NetBIOS name of that host.
517
518 If, however, both samba and your clients are using a WINS server, then:
519
520 a) your local master browsers will contact the WINS server and, as long as
521    samba has registered that it is a domain master browser with the WINS
522    server, your local master browser will receive samba's ip address
523    as its domain master browser.
524
525 b) when a client receives a domain-wide browse list, and a user attempts
526    to access a host in that list, it will contact the WINS server to
527    resolve the NetBIOS name of that host.  as long as that host has
528    registered its NetBIOS name with the same WINS server, the user will
529    be able to see that host. 
530
531 NOTE ABOUT BROADCAST ADDRESSES
532 ==============================
533
534 If your network uses a "0" based broadcast address (for example if it
535 ends in a 0) then you will strike problems. Windows for Workgroups
536 does not seem to support a 0's broadcast and you will probably find
537 that browsing and name lookups won't work.
538
539
540 MULTIPLE INTERFACES
541 ===================
542
543 Samba now supports machines with multiple network interfaces. If you
544 have multiple interfaces then you will need to use the "interfaces"
545 option in smb.conf to configure them. See smb.conf(5) for details.
546