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