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