e42f194cdee4cc353cec2c3a53c7e7940d3f7a72
[samba.git] / docs / manpages / nmbd.8
1 .TH NMBD 8 17/1/1995 nmbd nmbd
2 .SH NAME
3 nmbd \- provide netbios nameserver support to clients
4 .SH SYNOPSIS
5 .B nmbd
6 [
7 .B -B
8 .I broadcast address
9 ] [
10 .B -I
11 .I IP address
12 ] [
13 .B -D
14 ] [
15 .B -C comment string
16 ] [
17 .B -G
18 .I group name
19 ] [
20 .B -H
21 .I netbios hosts file
22 ] [
23 .B -N
24 .I netmask
25 ] [
26 .B -d
27 .I debuglevel
28 ] [
29 .B -l
30 .I log basename
31 ] [
32 .B -n
33 .I netbios name
34 ] [
35 .B -p
36 .I port number
37 ] [
38 .B -s
39 .I config file name
40 ]
41
42 .SH DESCRIPTION
43 This program is part of the Samba suite.
44
45 .B nmbd
46 is a server that understands and can reply to netbios
47 name service requests, like those produced by LanManager
48 clients. It also controls browsing.
49
50 LanManager clients, when they start up, may wish to locate a LanManager server.
51 That is, they wish to know what IP number a specified host is using.
52
53 This program simply listens for such requests, and if its own name is specified
54 it will respond with the IP number of the host it is running on. "Its own name"
55 is by default the name of the host it is running on, but this can be overriden
56 with the
57 .B -n
58 option (see "OPTIONS" below). Using the
59 .B -S
60 option (see "OPTIONS" below), it can also be instructed to respond with IP 
61 information about other hosts, provided they are locatable via the 
62 gethostbyname() call, or they are in a netbios hosts file.
63
64 Nmbd can also be used as a WINS (Windows Internet Name Server)
65 server. It will do this automatically by default. What this basically
66 means is that it will respond to all name requests that it receives
67 that are not broadcasts, as long as it can resolve the name.
68 .SH OPTIONS
69 .B -B
70
71 .RS 3
72 On some systems, the server is unable to determine the broadcast address to
73 use for name registration requests. If your system has this difficulty, this 
74 parameter may be used to specify an appropriate broadcast address. The 
75 address should be given in standard "a.b.c.d" notation.
76
77 Only use this parameter if you are sure that the server cannot properly 
78 determine the proper broadcast address.
79
80 The default broadcast address is determined by the server at run time. If it
81 encounters difficulty doing so, it makes a guess based on the local IP
82 number.
83 .RE
84 .B -I
85
86 .RS 3
87 On some systems, the server is unable to determine the correct IP
88 address to use. This allows you to override the default choice.
89 .RE
90
91 .B -D
92
93 .RS 3
94 If specified, this parameter causes the server to operate as a daemon. That is,
95 it detaches itself and runs in the background, fielding requests on the 
96 appropriate port.
97
98 By default, the server will NOT operate as a daemon.
99 .RE
100
101 .B -C comment string
102
103 .RS 3
104 This allows you to set the "comment string" that is shown next to the
105 machine name in browse listings. 
106
107 A %v will be replaced with the Samba version number.
108
109 A %h will be replaced with the hostname.
110
111 It defaults to "Samba %v".
112 .RE
113
114 .B -G
115
116 .RS 3
117 This option allows you to specify a netbios group (also known as
118 lanmanager domain) that the server should be part of. You may include
119 several of these on the command line if you like. Alternatively you
120 can use the -H option to load a netbios hosts file containing domain names.
121
122 At startup, unless the -R switch has been used, the server will
123 attempt to register all group names in the hosts file and on the
124 command line (from the -G option).
125
126 The server will also respond to queries on this name.
127 .RE
128
129 .B -H
130
131 .RS 3
132 It may be useful in some situations to be able to specify a list of
133 netbios names for which the server should send a reply if
134 queried. This option allows that. The syntax is similar to the
135 standard /etc/hosts file format, but has some extensions.
136
137 The file contains three columns. Lines beginning with a # are ignored
138 as comments. The first column is an IP address, or a hostname. If it
139 is a hostname then it is interpreted as the IP address returned by
140 gethostbyname() when read. Any IP address of 0.0.0.0 will be
141 interpreted as the servers own IP address.
142
143 The second column is a netbios name. This is the name that the server
144 will respond to. It must be less than 20 characters long.
145
146 The third column is optional, and is intended for flags. Currently the
147 only flags supported are G, S and M. A G indicates that the name is a
148 group (also known as domain) name.
149
150 At startup all groups known to the server (either from this file or
151 from the -G option) are registered on the network (unless the -R
152 option has been selected).
153
154 A S or G means that the specified address is a broadcast address of a
155 network that you want people to be able to browse you from. Nmbd will
156 search for a master browser in that domain and will send host
157 announcements to that machine, informing it that the specifed somain
158 is available.
159
160 A M means that this name is the default netbios name for this
161 machine. This has the same affect as specifying the -n option to nmbd.
162
163 After startup the server waits for queries, and will answer queries to
164 any name known to it. This includes all names in the netbios hosts
165 file (if any), it's own name, and any names given with the -G option.
166
167 The primary intention of the -H option is to allow a mapping from
168 netbios names to internet domain names, and to allow the specification
169 of groups that the server should be part of.
170
171 .B Example:
172
173         # This is a sample netbios hosts file
174
175         # DO NOT USE THIS FILE AS-IS
176         # YOU MAY INCONVENIENCE THE OWNERS OF THESE IPs
177         # if you want to include a name with a space in it then 
178         # use double quotes.
179
180         # first put ourselves in the group LANGROUP
181         0.0.0.0 LANGROUP G
182
183         # next add a netbios alias for a faraway host
184         arvidsjaur.anu.edu.au ARVIDSJAUR
185
186         # finally put in an IP for a hard to find host
187         130.45.3.213 FREDDY
188
189         # now we want another subnet to be able to browse
190         # us in the workgroup UNIXSERV
191         192.0.2.255  UNIXSERV G
192
193 .RE
194
195 .B -M
196 .I workgroup name
197
198 .RS 3
199 If this parameter is given, the server will look for a master browser
200 for the specified workgroup name, report success or failure, then
201 exit. If successful, the IP address of the name located will be
202 reported. 
203
204 If you use the workgroup name "-" then nmbd will search for a master
205 browser for any workgroup by using the name __MSBROWSE__.
206
207 This option is meant to be used interactively on the command line, not
208 as a daemon or in inetd.
209
210 .RE
211 .B -N
212
213 .RS 3
214 On some systems, the server is unable to determine the netmask. If
215 your system has this difficulty, this parameter may be used to specify
216 an appropriate netmask. The mask should be given in standard
217 "a.b.c.d" notation.
218
219 Only use this parameter if you are sure that the server cannot properly 
220 determine the proper netmask.
221
222 The default netmask is determined by the server at run time. If it
223 encounters difficulty doing so, it makes a guess based on the local IP
224 number.
225 .RE
226
227 .B -d
228 .I debuglevel
229 .RS 3
230
231 debuglevel is an integer from 0 to 5.
232
233 The default value if this parameter is not specified is zero.
234
235 The higher this value, the more detail will be logged to the log files about
236 the activities of the server. At level 0, only critical errors and serious 
237 warnings will be logged. Level 1 is a reasonable level for day to day running
238 - it generates a small amount of information about operations carried out.
239
240 Levels above 1 will generate considerable amounts of log data, and should 
241 only be used when investigating a problem. Levels above 3 are designed for 
242 use only by developers and generate HUGE amounts of log data, most of which 
243 is extremely cryptic.
244 .RE
245
246 .B -l
247 .I log file
248
249 .RS 3
250 If specified,
251 .I logfile
252 specifies a base filename into which operational data from the running server
253 will be logged.
254
255 The default base name is specified at compile time.
256
257 The base name is used to generate actual log file names. For example, if the
258 name specified was "log", the following files would be used for log data:
259
260 .RS 3
261 log.nmb (containing debugging information)
262
263 log.nmb.in (containing inbound transaction data)
264
265 log.nmb.out (containing outbound transaction data)
266 .RE
267
268 The log files generated are never removed by the server.
269 .RE
270 .RE
271
272 .B -n
273 .I netbios name
274
275 .RS 3
276 This parameter tells the server what netbios name to respond with when 
277 queried. The same name is also registered on startup unless the -R 
278 parameter was specified.
279
280 The default netbios name used if this parameter is not specified is the 
281 name of the host on which the server is running.
282 .RE
283
284 .B -p
285 .I port number
286 .RS 3
287
288 port number is a positive integer value.
289
290 The default value if this parameter is not specified is 137.
291
292 This number is the port number that will be used when making connections to
293 the server from client software. The standard (well-known) port number for the
294 server is 137, hence the default. If you wish to run the server as an ordinary
295 user rather than as root, most systems will require you to use a port number
296 greater than 1024 - ask your system administrator for help if you are in this
297 situation.
298
299 Note that the name server uses UDP, not TCP!
300
301 This parameter is not normally specified except in the above situation.
302 .RE
303 .SH FILES
304
305 .B /etc/inetd.conf
306
307 .RS 3
308 If the server is to be run by the inetd meta-daemon, this file must contain
309 suitable startup information for the meta-daemon. See the section 
310 "INSTALLATION" below.
311 .RE
312
313 .B /etc/rc.d/rc.inet2
314
315 .RS 3
316 (or whatever initialisation script your system uses)
317
318 If running the server as a daemon at startup, this file will need to contain
319 an appropriate startup sequence for the server. See the section "Installation"
320 below.
321 .RE
322
323 .B /etc/services
324
325 .RS 3
326 If running the server via the meta-daemon inetd, this file must contain a
327 mapping of service name (eg., netbios-ns)  to service port (eg., 137) and
328 protocol type (eg., udp). See the section "INSTALLATION" below.
329 .RE
330 .RE
331
332 .SH ENVIRONMENT VARIABLES
333 Not applicable.
334
335 .SH INSTALLATION
336 The location of the server and its support files is a matter for individual
337 system administrators. The following are thus suggestions only.
338
339 It is recommended that the server software be installed under the /usr/local
340 hierarchy, in a directory readable by all, writeable only by root. The server
341 program itself should be executable by all, as users may wish to run the 
342 server themselves (in which case it will of course run with their privileges).
343 The server should NOT be setuid or setgid!
344
345 The server log files should be put in a directory readable and writable only
346 by root, as the log files may contain sensitive information.
347
348 The remaining notes will assume the following:
349
350 .RS 3
351 nmbd (the server program) installed in /usr/local/smb
352
353 log files stored in /var/adm/smblogs
354 .RE
355
356 The server may be run either as a daemon by users or at startup, or it may
357 be run from a meta-daemon such as inetd upon request. If run as a daemon, the
358 server will always be ready, so starting sessions will be faster. If run from 
359 a meta-daemon some memory will be saved and utilities such as the tcpd 
360 TCP-wrapper may be used for extra security.
361
362 When you've decided, continue with either "Running the server as a daemon" or
363 "Running the server on request".
364 .SH RUNNING THE SERVER AS A DAEMON
365 To run the server as a daemon from the command line, simply put the "-D" option
366 on the command line. There is no need to place an ampersand at the end of the
367 command line - the "-D" option causes the server to detach itself from the
368 tty anyway.
369
370 Any user can run the server as a daemon (execute permissions permitting, of 
371 course). This is useful for testing purposes.
372
373 To ensure that the server is run as a daemon whenever the machine is started,
374 you will need to modify the system startup files. Wherever appropriate (for
375 example, in /etc/rc.d/rc.inet2), insert the following line, substituting 
376 values appropriate to your system:
377
378 .RS 3
379 /usr/local/smb/nmbd -D -l/var/adm/smblogs/log
380 .RE
381
382 (The above should appear in your initialisation script as a single line. 
383 Depending on your terminal characteristics, it may not appear that way in
384 this man page. If the above appears as more than one line, please treat any 
385 newlines or indentation as a single space or TAB character.)
386
387 If the options used at compile time are appropriate for your system, all
388 parameters except the desired debug level and "-D" may be omitted. See the
389 section on "Options" above.
390 .SH RUNNING THE SERVER ON REQUEST
391 If your system uses a meta-daemon such as inetd, you can arrange to have the
392 SMB name server started whenever a process attempts to connect to it. This 
393 requires several changes to the startup files on the host machine. If you are
394 experimenting as an ordinary user rather than as root, you will need the 
395 assistance of your system administrator to modify the system files.
396
397 First, ensure that a port is configured in the file /etc/services. The 
398 well-known port 137 should be used if possible, though any port may be used.
399
400 Ensure that a line similar to the following is in /etc/services:
401
402 .RS 3
403 netbios-ns      137/udp
404 .RE
405
406 Note for NIS/YP users: You may need to rebuild the NIS service maps rather
407 than alter your local /etc/services file.
408
409 Next, put a suitable line in the file /etc/inetd.conf (in the unlikely event
410 that you are using a meta-daemon other than inetd, you are on your own). Note
411 that the first item in this line matches the service name in /etc/services.
412 Substitute appropriate values for your system in this line (see
413 .B inetd(8)):
414
415 .RS 3
416 netbios-ns dgram udp wait root /usr/local/smb/nmbd -l/var/adm/smblogs/log
417 .RE
418
419 (The above should appear in /etc/inetd.conf as a single line. Depending on 
420 your terminal characteristics, it may not appear that way in this man page.
421 If the above appears as more than one line, please treat any newlines or 
422 indentation as a single space or TAB character.)
423
424 Note that there is no need to specify a port number here, even if you are 
425 using a non-standard port number.
426 .SH TESTING THE INSTALLATION
427 If running the server as a daemon, execute it before proceeding. If
428 using a meta-daemon, either restart the system or kill and restart the 
429 meta-daemon. Some versions of inetd will reread their configuration tables if
430 they receive a HUP signal.
431
432 To test whether the name server is running, start up a client
433 .I on a different machine
434 and see whether the desired name is now present. Alternatively, run 
435 the nameserver
436 .I on a different machine
437 specifying "-L netbiosname", where "netbiosname" is the name you have 
438 configured the test server to respond with. The command should respond 
439 with success, and the IP number of the machine using the specified netbios 
440 name. You may need the -B parameter on some systems. See the README
441 file for more information on testing nmbd.
442
443 .SH VERSION
444 This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some
445 of the recent patches to it. These notes will necessarily lag behind 
446 development of the software, so it is possible that your version of 
447 the server has extensions or parameter semantics that differ from or are not 
448 covered by this man page. Please notify these to the address below for 
449 rectification.
450 .SH SEE ALSO
451 .B inetd(8),
452 .B smbd(8), 
453 .B smb.conf(5),
454 .B smbclient(1),
455 .B testparm(1), 
456 .B testprns(1)
457
458 .SH DIAGNOSTICS
459 [This section under construction]
460
461 Most diagnostics issued by the server are logged in the specified log file. The
462 log file name is specified at compile time, but may be overridden on the
463 command line.
464
465 The number and nature of diagnostics available depends on the debug level used
466 by the server. If you have problems, set the debug level to 3 and peruse the
467 log files.
468
469 Most messages are reasonably self-explanatory. Unfortunately, at time of
470 creation of this man page the source code is still too fluid to warrant
471 describing each and every diagnostic. At this stage your best bet is still
472 to grep the source code and inspect the conditions that gave rise to the 
473 diagnostics you are seeing.
474
475 .SH BUGS
476 None known.
477 .SH CREDITS
478 The original Samba software and related utilities were created by 
479 Andrew Tridgell (samba-bugs@anu.edu.au). Andrew is also the Keeper
480 of the Source for this project.
481
482 This man page written by Karl Auer (Karl.Auer@anu.edu.au)
483
484 See
485 .B smb.conf(5) for a full list of contributors and details on how to 
486 submit bug reports, comments etc.
487
488
489
490
491