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