added QNX entry to MIRRORS
[ira/wip.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 specifed somain
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 .RE
267
268 .B -n
269 .I netbios name
270
271 .RS 3
272 This parameter tells the server what netbios name to respond with when 
273 queried. The same name is also registered on startup unless the -R 
274 parameter was specified.
275
276 The default netbios name used if this parameter is not specified is the 
277 name of the host on which the server is running.
278 .RE
279
280 .B -p
281 .I port number
282 .RS 3
283
284 port number is a positive integer value.
285
286 The default value if this parameter is not specified is 137.
287
288 This number is the port number that will be used when making connections to
289 the server from client software. The standard (well-known) port number for the
290 server is 137, hence the default. If you wish to run the server as an ordinary
291 user rather than as root, most systems will require you to use a port number
292 greater than 1024 - ask your system administrator for help if you are in this
293 situation.
294
295 Note that the name server uses UDP, not TCP!
296
297 This parameter is not normally specified except in the above situation.
298 .RE
299 .SH FILES
300
301 .B /etc/inetd.conf
302
303 .RS 3
304 If the server is to be run by the inetd meta-daemon, this file must contain
305 suitable startup information for the meta-daemon. See the section 
306 "INSTALLATION" below.
307 .RE
308
309 .B /etc/rc.d/rc.inet2
310
311 .RS 3
312 (or whatever initialisation script your system uses)
313
314 If running the server as a daemon at startup, this file will need to contain
315 an appropriate startup sequence for the server. See the section "Installation"
316 below.
317 .RE
318
319 .B /etc/services
320
321 .RS 3
322 If running the server via the meta-daemon inetd, this file must contain a
323 mapping of service name (eg., netbios-ns)  to service port (eg., 137) and
324 protocol type (eg., udp). See the section "INSTALLATION" below.
325 .RE
326 .RE
327
328 .SH ENVIRONMENT VARIABLES
329 Not applicable.
330
331 .SH INSTALLATION
332 The location of the server and its support files is a matter for individual
333 system administrators. The following are thus suggestions only.
334
335 It is recommended that the server software be installed under the /usr/local
336 hierarchy, in a directory readable by all, writeable only by root. The server
337 program itself should be executable by all, as users may wish to run the 
338 server themselves (in which case it will of course run with their privileges).
339 The server should NOT be setuid or setgid!
340
341 The server log files should be put in a directory readable and writable only
342 by root, as the log files may contain sensitive information.
343
344 The remaining notes will assume the following:
345
346 .RS 3
347 nmbd (the server program) installed in /usr/local/smb
348
349 log files stored in /var/adm/smblogs
350 .RE
351
352 The server may be run either as a daemon by users or at startup, or it may
353 be run from a meta-daemon such as inetd upon request. If run as a daemon, the
354 server will always be ready, so starting sessions will be faster. If run from 
355 a meta-daemon some memory will be saved and utilities such as the tcpd 
356 TCP-wrapper may be used for extra security.
357
358 When you've decided, continue with either "Running the server as a daemon" or
359 "Running the server on request".
360 .SH RUNNING THE SERVER AS A DAEMON
361 To run the server as a daemon from the command line, simply put the "-D" option
362 on the command line. There is no need to place an ampersand at the end of the
363 command line - the "-D" option causes the server to detach itself from the
364 tty anyway.
365
366 Any user can run the server as a daemon (execute permissions permitting, of 
367 course). This is useful for testing purposes.
368
369 To ensure that the server is run as a daemon whenever the machine is started,
370 you will need to modify the system startup files. Wherever appropriate (for
371 example, in /etc/rc.d/rc.inet2), insert the following line, substituting 
372 values appropriate to your system:
373
374 .RS 3
375 /usr/local/smb/nmbd -D -l/var/adm/smblogs/log
376 .RE
377
378 (The above should appear in your initialisation script as a single line. 
379 Depending on your terminal characteristics, it may not appear that way in
380 this man page. If the above appears as more than one line, please treat any 
381 newlines or indentation as a single space or TAB character.)
382
383 If the options used at compile time are appropriate for your system, all
384 parameters except the desired debug level and "-D" may be omitted. See the
385 section on "Options" above.
386 .SH RUNNING THE SERVER ON REQUEST
387 If your system uses a meta-daemon such as inetd, you can arrange to have the
388 SMB name server started whenever a process attempts to connect to it. This 
389 requires several changes to the startup files on the host machine. If you are
390 experimenting as an ordinary user rather than as root, you will need the 
391 assistance of your system administrator to modify the system files.
392
393 First, ensure that a port is configured in the file /etc/services. The 
394 well-known port 137 should be used if possible, though any port may be used.
395
396 Ensure that a line similar to the following is in /etc/services:
397
398 .RS 3
399 netbios-ns      137/udp
400 .RE
401
402 Note for NIS/YP users: You may need to rebuild the NIS service maps rather
403 than alter your local /etc/services file.
404
405 Next, put a suitable line in the file /etc/inetd.conf (in the unlikely event
406 that you are using a meta-daemon other than inetd, you are on your own). Note
407 that the first item in this line matches the service name in /etc/services.
408 Substitute appropriate values for your system in this line (see
409 .B inetd(8)):
410
411 .RS 3
412 netbios-ns dgram udp wait root /usr/local/smb/nmbd -l/var/adm/smblogs/log
413 .RE
414
415 (The above should appear in /etc/inetd.conf as a single line. Depending on 
416 your terminal characteristics, it may not appear that way in this man page.
417 If the above appears as more than one line, please treat any newlines or 
418 indentation as a single space or TAB character.)
419
420 Note that there is no need to specify a port number here, even if you are 
421 using a non-standard port number.
422 .SH TESTING THE INSTALLATION
423 If running the server as a daemon, execute it before proceeding. If
424 using a meta-daemon, either restart the system or kill and restart the 
425 meta-daemon. Some versions of inetd will reread their configuration tables if
426 they receive a HUP signal.
427
428 To test whether the name server is running, start up a client
429 .I on a different machine
430 and see whether the desired name is now present. Alternatively, run 
431 the nameserver
432 .I on a different machine
433 specifying "-L netbiosname", where "netbiosname" is the name you have 
434 configured the test server to respond with. The command should respond 
435 with success, and the IP number of the machine using the specified netbios 
436 name. You may need the -B parameter on some systems. See the README
437 file for more information on testing nmbd.
438
439 .SH VERSION
440 This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some
441 of the recent patches to it. These notes will necessarily lag behind 
442 development of the software, so it is possible that your version of 
443 the server has extensions or parameter semantics that differ from or are not 
444 covered by this man page. Please notify these to the address below for 
445 rectification.
446 .SH SEE ALSO
447 .B inetd(8),
448 .B smbd(8), 
449 .B smb.conf(5),
450 .B smbclient(1),
451 .B testparm(1), 
452 .B testprns(1)
453
454 .SH DIAGNOSTICS
455 [This section under construction]
456
457 Most diagnostics issued by the server are logged in the specified log file. The
458 log file name is specified at compile time, but may be overridden on the
459 command line.
460
461 The number and nature of diagnostics available depends on the debug level used
462 by the server. If you have problems, set the debug level to 3 and peruse the
463 log files.
464
465 Most messages are reasonably self-explanatory. Unfortunately, at time of
466 creation of this man page the source code is still too fluid to warrant
467 describing each and every diagnostic. At this stage your best bet is still
468 to grep the source code and inspect the conditions that gave rise to the 
469 diagnostics you are seeing.
470
471 .SH BUGS
472 None known.
473 .SH CREDITS
474 The original Samba software and related utilities were created by 
475 Andrew Tridgell (samba-bugs@anu.edu.au). Andrew is also the Keeper
476 of the Source for this project.
477
478 This man page written by Karl Auer (Karl.Auer@anu.edu.au)
479
480 See
481 .B smb.conf(5) for a full list of contributors and details on how to 
482 submit bug reports, comments etc.
483
484
485
486
487