d369f698558d1541633cdf5d9095ef081e96a574
[samba.git] / docs / manpages / smbd.8
1 .TH SMBD 8 "08 Jan 1998" "smbd 1.9.18"
2 .SH NAME
3 smbd \- provide SMB (aka LanManager) services to clients
4 .SH SYNOPSIS
5 .B smbd
6 [
7 .B \-D
8 ] [
9 .B \-a
10 ] [
11 .B \-o
12 ] [
13 .B \-d
14 .I debuglevel
15 ] [
16 .B \-l
17 .I log file
18 ] [
19 .B \-p
20 .I port number
21 ] [
22 .B \-O
23 .I socket options
24 ] [
25 .B \-s
26 .I configuration file
27 ]
28 .SH DESCRIPTION
29 This program is part of the Samba suite.
30
31 .B smbd
32 is a server that can provide most SMB services. The server provides
33 filespace and printer services to clients using the SMB protocol. This
34 is compatible with the LanManager protocol, and can service LanManager
35 clients.  These include MSCLIENT 3.0 for DOS, Windows for Workgroups,
36 Windows 95, Windows NT, OS/2, DAVE for Macintosh, and smbfs for Linux.
37
38 An extensive description of the services that the server can provide is given
39 in the man page for the configuration file controlling the attributes of those
40 services (see
41 .BR smb.conf (5)).
42 This man page will not describe the services, but
43 will concentrate on the administrative aspects of running the server.
44
45 Please note that there are significant security implications to running this
46 server, and
47 .BR smb.conf (5)
48 should be regarded as mandatory reading before proceeding with 
49 installation.
50
51 A session is created whenever a client requests one. Each client gets a copy
52 of the server for each session. This copy then services all connections made
53 by the client during that session. When all connections from its client are
54 are closed, the copy of the server for that client terminates.
55
56 The configuration file, and any files that it includes, are automatically
57 reloaded every minute, if they change.  You can force a reload by sending a
58 SIGHUP to the server.  Reloading the configuration file will not affect
59 connections to any service that is already established.  Either the user
60 will have to disconnect from the service, or smbd killed and restarted.
61 .SH OPTIONS
62 .B \-D
63
64 .RS 3
65 If specified, this parameter causes the server to operate as a daemon. That is,
66 it detaches itself and runs in the background, fielding requests on the 
67 appropriate port.
68
69 By default, the server will NOT operate as a daemon.
70 .RE
71
72 .B \-a
73
74 .RS 3
75 If this parameter is specified, each new connection will append log messages
76 to the log file.  This is the default.
77 .RE
78
79 .B \-o
80
81 .RS 3
82 If this parameter is specified, the log files will be overwritten when opened.
83 By default, the log files will be appended to.
84 .RE
85
86 .B \-d
87 .I debuglevel
88 .RS 3
89
90 debuglevel is an integer from 0 to 10.
91
92 The default value if this parameter is not specified is zero.
93
94 The higher this value, the more detail will be logged to the log files about
95 the activities of the server. At level 0, only critical errors and serious 
96 warnings will be logged. Level 1 is a reasonable level for day to day running
97 - it generates a small amount of information about operations carried out.
98
99 Levels above 1 will generate considerable amounts of log data, and should 
100 only be used when investigating a problem. Levels above 3 are designed for 
101 use only by developers and generate HUGE amounts of log data, most of which 
102 is extremely cryptic.
103 .RE
104
105 .B \-l
106 .I log file
107
108 .RS 3
109 If specified,
110 .I logfile
111 specifies a base filename into which operational data from the running server
112 will be logged.
113
114 The default base name is specified at compile time.
115
116 The base name is used to generate actual log file names. For example, if the
117 name specified was "log", the following files would be used for log data:
118
119 .RS 3
120 log.debug (containing debugging information)
121
122 log.in (containing inbound transaction data)
123
124 log.out (containing outbound transaction data)
125 .RE
126
127 The log files generated are never removed by the server.
128 .RE
129
130 .B \-O
131 .I socket options
132 .RS 3
133
134 See the socket options section of
135 .BR smb.conf (5)
136 for details
137
138 .RE
139 .B \-p
140 .I port number
141 .RS 3
142
143 port number is a positive integer value.
144
145 The default value if this parameter is not specified is 139.
146
147 This number is the port number that will be used when making connections to
148 the server from client software. The standard (well-known) port number for the
149 server is 139, hence the default. If you wish to run the server as an ordinary
150 user rather than as root, most systems will require you to use a port number
151 greater than 1024 - ask your system administrator for help if you are in this
152 situation.
153
154 In order for the server to be useful by most clients, should you configure
155 it on a port other than 139, you will require port redirection services
156 on port 139, details of which are outlined in rfc1002.txt section 4.3.5.
157
158 This parameter is not normally specified except in the above situation.
159 .RE
160
161 .B \-s
162 .I configuration file
163
164 .RS 3
165 The default configuration file name is determined at compile time.
166
167 The file specified contains the configuration details required by the server.
168 The information in this file includes server-specific information such as
169 what printcap file to use, as well as descriptions of all the services that the
170 server is to provide. See
171 .BR smb.conf (5)
172 for more information.
173 .RE
174 .SH FILES
175
176 .B /etc/inetd.conf
177
178 .RS 3
179 If the server is to be run by the inetd meta-daemon, this file must contain
180 suitable startup information for the meta-daemon. See the section 
181 "INSTALLATION" below.
182 .RE
183
184 .B /etc/rc
185
186 .RS 3
187 (or whatever initialisation script your system uses)
188
189 If running the server as a daemon at startup, this file will need to contain
190 an appropriate startup sequence for the server. See the section "INSTALLATION"
191 below.
192 .RE
193
194 .B /etc/services
195
196 .RS 3
197 If running the server via the meta-daemon inetd, this file must contain a
198 mapping of service name (eg., netbios-ssn)  to service port (eg., 139) and
199 protocol type (eg., tcp). See the section "INSTALLATION" below.
200 .RE
201
202 .B /usr/local/samba/lib/smb.conf
203
204 .RS 3
205 This file describes all the services the server is to make available to
206 clients. See
207 .BR smb.conf (5)
208 for more information.
209 .RE
210 .SH LIMITATIONS
211
212 On some systems
213 .B smbd
214 cannot change uid back to root after a setuid() call.
215 Such systems are called "trapdoor" uid systems. If you have such a system,
216 you will be unable to connect from a client (such as a PC) as two different
217 users at once. Attempts to connect the second user will result in "access
218 denied" or similar.
219 .SH ENVIRONMENT VARIABLES
220
221 .B PRINTER
222
223 .RS 3
224 If no printer name is specified to printable services, most systems will
225 use the value of this variable (or "lp" if this variable is not defined)
226 as the name of the printer to use. This is not specific to the server,
227 however.
228 .RE
229 .SH INSTALLATION
230 The location of the server and its support files is a matter for individual
231 system administrators. The following are thus suggestions only.
232
233 It is recommended that the server software be installed under the
234 /usr/local/samba hierarchy, in a directory readable by all, writeable only
235 by root. The server program itself should be executable by all, as
236 users may wish to run the server themselves (in which case it will of
237 course run with their privileges).  The server should NOT be
238 setuid. On some systems it may be worthwhile to make smbd setgid to an
239 empty group. This is because some systems may have a security hole where
240 daemon processes that become a user can be attached to with a
241 debugger. Making the smbd file setgid to an empty group may prevent
242 this hole from being exploited. This security hole and the suggested
243 fix has only been confirmed on Linux at the time this was written. It
244 is possible that this hole only exists in Linux, as testing on other
245 systems has thus far shown them to be immune.
246
247 The server log files should be put in a directory readable and writable only
248 by root, as the log files may contain sensitive information.
249
250 The configuration file should be placed in a directory readable and writable
251 only by root, as the configuration file controls security for the services
252 offered by the server. The configuration file can be made readable by all if
253 desired, but this is not necessary for correct operation of the server and
254 is not recommended. A sample configuration file "smb.conf.sample" is supplied
255 with the source to the server - this may be renamed to "smb.conf" and 
256 modified to suit your needs.
257
258 The remaining notes will assume the following:
259
260 .RS 3
261 .B smbd
262 (the server program) installed in /usr/local/samba/bin
263
264 smb.conf (the configuration file) installed in /usr/local/samba/lib
265
266 log files stored in /var/adm/smblogs
267 .RE
268
269 The server may be run either as a daemon by users or at startup, or it may
270 be run from a meta-daemon such as inetd upon request. If run as a daemon, the
271 server will always be ready, so starting sessions will be faster. If run from 
272 a meta-daemon some memory will be saved and utilities such as the tcpd 
273 TCP-wrapper may be used for extra security.
274
275 When you've decided, continue with either "RUNNING THE SERVER AS A DAEMON" or
276 "RUNNING THE SERVER ON REQUEST".
277 .SH RUNNING THE SERVER AS A DAEMON
278 To run the server as a daemon from the command line, simply put the
279 .B \-D
280 option
281 on the command line. There is no need to place an ampersand at the end of the
282 command line - the
283 .B \-D
284 option causes the server to detach itself from the
285 tty anyway.
286
287 Any user can run the server as a daemon (execute permissions permitting, of 
288 course). This is useful for testing purposes, and may even be useful as a
289 temporary substitute for something like ftp. When run this way, however, the
290 server will only have the privileges of the user who ran it.
291
292 To ensure that the server is run as a daemon whenever the machine is started,
293 and to ensure that it runs as root so that it can serve multiple clients, you 
294 will need to modify the system startup files. Wherever appropriate (for
295 example, in /etc/rc), insert the following line, substituting 
296 port number, log file location, configuration file location and debug level as
297 desired:
298
299 .RS 3
300 /usr/local/samba/bin/smbd -D -l /var/adm/smblogs/log -s /usr/local/samba/lib/smb.conf
301 .RE
302
303 (The above should appear in your initialisation script as a single line. 
304 Depending on your terminal characteristics, it may not appear that way in
305 this man page. If the above appears as more than one line, please treat any 
306 newlines or indentation as a single space or TAB character.)
307
308 If the options used at compile time are appropriate for your system, all
309 parameters except the desired debug level and
310 .B \-D
311 may be omitted. See the
312 section "OPTIONS" above.
313 .SH RUNNING THE SERVER ON REQUEST
314 If your system uses a meta-daemon such as inetd, you can arrange to have the
315 smbd server started whenever a process attempts to connect to it. This requires
316 several changes to the startup files on the host machine. If you are
317 experimenting as an ordinary user rather than as root, you will need the 
318 assistance of your system administrator to modify the system files.
319
320 You will probably want to set up the name server
321 .B nmbd
322 at the same time as
323 .B smbd
324 - refer to the man page 
325 .BR nmbd (8).
326
327 First, ensure that a port is configured in the file /etc/services. The 
328 well-known port 139 should be used if possible, though any port may be used.
329
330 Ensure that a line similar to the following is in /etc/services:
331
332 .RS 3
333 netbios-ssn     139/tcp
334 .RE
335
336 Note for NIS/YP users - you may need to rebuild the NIS service maps rather
337 than alter your local /etc/services file.
338
339 Next, put a suitable line in the file /etc/inetd.conf (in the unlikely event
340 that you are using a meta-daemon other than inetd, you are on your own). Note
341 that the first item in this line matches the service name in /etc/services.
342 Substitute appropriate values for your system in this line (see
343 .BR inetd (8)):
344
345 .RS 3
346 .\" turn off right adjustment
347 .ad l
348 netbios-ssn stream tcp nowait root /usr/local/samba/bin/smbd -d1 
349 -l/var/adm/smblogs/log -s/usr/local/samba/lib/smb.conf
350 .ad
351 .RE
352
353 (The above should appear in /etc/inetd.conf as a single line. Depending on 
354 your terminal characteristics, it may not appear that way in this man page.
355 If the above appears as more than one line, please treat any newlines or 
356 indentation as a single space or TAB character.)
357
358 Note that there is no need to specify a port number here, even if you are 
359 using a non-standard port number.
360
361 Lastly, edit the configuration file to provide suitable services. To start
362 with, the following two services should be all you need:
363
364 .RS 3
365 [homes]
366 .RS 3
367  writable = yes
368 .RE
369
370 [printers]
371 .RS 3
372  writable = no
373  printable = yes
374  path = /tmp
375  public = yes
376 .RE
377 .RE
378
379 This will allow you to connect to your home directory and print to any printer
380 supported by the host (user privileges permitting).
381 .SH TESTING THE INSTALLATION
382 If running the server as a daemon, execute it before proceeding. If
383 using a meta-daemon, either restart the system or kill and restart the 
384 meta-daemon. Some versions of inetd will reread their configuration tables if
385 they receive a HUP signal.
386
387 If your machine's name is "fred" and your name is "mary", you should now be
388 able to connect to the service "\e\efred\emary".
389
390 To properly test and experiment with the server, we recommend using the
391 smbclient program (see
392 .BR smbclient (1)).
393 .SH VERSION
394 This man page is (mostly) correct for version 1.9.00 of the Samba suite,
395 plus some of the recent patches to it. These notes will necessarily lag behind 
396 development of the software, so it is possible that your version of 
397 the server has extensions or parameter semantics that differ from or are not 
398 covered by this man page. Please notify these to the address below for 
399 rectification.
400 .SH SEE ALSO
401 .BR hosts_access (5),
402 .BR inetd (8),
403 .BR nmbd (8), 
404 .BR smb.conf (5),
405 .BR smbclient (1),
406 .BR testparm (1), 
407 .BR testprns (1)
408 .BR rfc1001.txt
409 .BR rfc1002.txt
410 .SH DIAGNOSTICS
411 [This section under construction]
412
413 Most diagnostics issued by the server are logged in a specified log file. The
414 log file name is specified at compile time, but may be overridden on the
415 command line.
416
417 The number and nature of diagnostics available depends on the debug level used
418 by the server. If you have problems, set the debug level to 3 and peruse the
419 log files.
420
421 Most messages are reasonably self-explanatory. Unfortunately, at time of
422 creation of this man page the source code is still too fluid to warrant
423 describing each and every diagnostic. At this stage your best bet is still
424 to grep the source code and inspect the conditions that gave rise to the 
425 diagnostics you are seeing.
426
427 .SH SIGNALS
428
429 In version 1.9.18 and above the debug log level of smbd may be raised 
430 by sending it a SIGUSR1 (kill -USR1 <smbd-pid>) and lowered by sending 
431 it a SIGUSR2 (kill -USR2 <smbd-pid>). This is to allow transient problems
432 to be diagnosed, whilst still running at a normally low log level.
433
434 Note that as the signal handlers send a debug write, they are not
435 re-entrant in smbd. This you should wait until smbd is in a state of
436 waiting for an incoming smb before issuing them. It is possible to
437 make the signal handlers safe by un-blocking the signals before the
438 select call and re-blocking them after, however this would affect
439 performance.
440
441 .SH BUGS
442 None known.
443 .SH CREDITS
444 The original Samba software and related utilities were created by 
445 Andrew Tridgell (samba-bugs@samba.anu.edu.au). Andrew is also the Keeper
446 of the Source for this project.
447
448
449 See
450 .BR smb.conf (5)
451 for a full list of contributors and details on how to 
452 submit bug reports, comments etc.