1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
5 <refentrytitle>smbd</refentrytitle>
6 <manvolnum>8</manvolnum>
11 <refname>smbd</refname>
12 <refpurpose>server to provide SMB/CIFS services to clients</refpurpose>
17 <command>smbd</command>
18 <arg choice="opt">-D</arg>
19 <arg choice="opt">-a</arg>
20 <arg choice="opt">-o</arg>
21 <arg choice="opt">-P</arg>
22 <arg choice="opt">-h</arg>
23 <arg choice="opt">-V</arg>
24 <arg choice="opt">-b</arg>
25 <arg choice="opt">-d <debug level></arg>
26 <arg choice="opt">-l <log directory></arg>
27 <arg choice="opt">-p <port number></arg>
28 <arg choice="opt">-O <socket option></arg>
29 <arg choice="opt">-s <configuration file></arg>
34 <title>DESCRIPTION</title>
35 <para>This program is part of the Samba suite.</para>
37 <para><command>smbd</command> is the server daemon that
38 provides filesharing and printing services to Windows clients.
39 The server provides filespace and printer services to
40 clients using the SMB (or CIFS) protocol. This is compatible
41 with the LanManager protocol, and can service LanManager
42 clients. These include MSCLIENT 3.0 for DOS, Windows for
43 Workgroups, Windows 95/98/ME, Windows NT, Windows 2000,
44 OS/2, DAVE for Macintosh, and smbfs for Linux.</para>
46 <para>An extensive description of the services that the
47 server can provide is given in the man page for the
48 configuration file controlling the attributes of those
49 services (see <ulink url="smb.conf.5.html"><filename>smb.conf(5)
50 </filename></ulink>. This man page will not describe the
51 services, but will concentrate on the administrative aspects
52 of running the server.</para>
54 <para>Please note that there are significant security
55 implications to running this server, and the <ulink
56 url="smb.conf.5.html"><filename>smb.conf(5)</filename></ulink>
57 manpage should be regarded as mandatory reading before
58 proceeding with installation.</para>
60 <para>A session is created whenever a client requests one.
61 Each client gets a copy of the server for each session. This
62 copy then services all connections made by the client during
63 that session. When all connections from its client are closed,
64 the copy of the server for that client terminates.</para>
66 <para>The configuration file, and any files that it includes,
67 are automatically reloaded every minute, if they change. You
68 can force a reload by sending a SIGHUP to the server. Reloading
69 the configuration file will not affect connections to any service
70 that is already established. Either the user will have to
71 disconnect from the service, or <command>smbd</command> killed and restarted.</para>
75 <title>OPTIONS</title>
80 <listitem><para>If specified, this parameter causes
81 the server to operate as a daemon. That is, it detaches
82 itself and runs in the background, fielding requests
83 on the appropriate port. Operating the server as a
84 daemon is the recommended way of running <command>smbd</command> for
85 servers that provide more than casual use file and
86 print services. This switch is assumed if <command>smbd
87 </command> is executed on the command line of a shell.
93 <listitem><para>If this parameter is specified, each new
94 connection will append log messages to the log file.
95 This is the default.</para></listitem>
100 <listitem><para>If this parameter is specified, the
101 log files will be overwritten when opened. By default,
102 <command>smbd</command> will append entries to the log
103 files.</para></listitem>
108 <listitem><para>Passive option. Causes <command>smbd</command> not to
109 send any network traffic out. Used for debugging by
110 the developers only.</para></listitem>
115 <listitem><para>Prints the help information (usage)
116 for <command>smbd</command>.</para></listitem>
121 <listitem><para>Prints the version number for
122 <command>smbd</command>.</para></listitem>
127 <listitem><para>Prints information about how
128 Samba was built.</para></listitem>
132 <term>-d <debug level></term>
133 <listitem><para><replaceable>debuglevel</replaceable> is an integer
134 from 0 to 10. The default value if this parameter is
135 not specified is zero.</para>
137 <para>The higher this value, the more detail will be
138 logged to the log files about the activities of the
139 server. At level 0, only critical errors and serious
140 warnings will be logged. Level 1 is a reasonable level for
141 day to day running - it generates a small amount of
142 information about operations carried out.</para>
144 <para>Levels above 1 will generate considerable
145 amounts of log data, and should only be used when
146 investigating a problem. Levels above 3 are designed for
147 use only by developers and generate HUGE amounts of log
148 data, most of which is extremely cryptic.</para>
150 <para>Note that specifying this parameter here will
151 override the <ulink url="smb.conf.5.html#loglevel">log
152 level</ulink> parameter in the <ulink url="smb.conf.5.html">
153 <filename>smb.conf(5)</filename></ulink> file.</para>
158 <term>-l <log directory></term>
159 <listitem><para>If specified,
160 <replaceable>log directory</replaceable>
161 specifies a log directory into which the "log.smbd" log
162 file will be created for informational and debug
163 messages from the running server. The log
164 file generated is never removed by the server although
165 its size may be controlled by the <ulink
166 url="smb.conf.5.html#maxlogsize">max log size</ulink>
167 option in the <ulink url="smb.conf.5.html"><filename>
168 smb.conf(5)</filename></ulink> file.
171 <para>The default log directory is specified at
172 compile time.</para></listitem>
176 <term>-O <socket options></term>
177 <listitem><para>See the <ulink
178 url="smb.conf.5.html#socketoptions">socket options</ulink>
179 parameter in the <ulink url="smb.conf.5.html"><filename>smb.conf(5)
180 </filename></ulink> file for details.</para></listitem>
184 <term>-p <port number></term>
185 <listitem><para><replaceable>port number</replaceable> is a positive integer
186 value. The default value if this parameter is not
187 specified is 139.</para>
189 <para>This number is the port number that will be
190 used when making connections to the server from client
191 software. The standard (well-known) port number for the
192 SMB over TCP is 139, hence the default. If you wish to
193 run the server as an ordinary user rather than
194 as root, most systems will require you to use a port
195 number greater than 1024 - ask your system administrator
196 for help if you are in this situation.</para>
198 <para>In order for the server to be useful by most
199 clients, should you configure it on a port other
200 than 139, you will require port redirection services
201 on port 139, details of which are outlined in rfc1002.txt
202 section 4.3.5.</para>
204 <para>This parameter is not normally specified except
205 in the above situation.</para></listitem>
209 <term>-s <configuration file></term>
210 <listitem><para>The file specified contains the
211 configuration details required by the server. The
212 information in this file includes server-specific
213 information such as what printcap file to use, as well
214 as descriptions of all the services that the server is
215 to provide. See <ulink url="smb.conf.5.html"><filename>
216 smb.conf(5)</filename></ulink> for more information.
217 The default configuration file name is determined at
218 compile time.</para></listitem>
228 <term><filename>/etc/inetd.conf</filename></term>
229 <listitem><para>If the server is to be run by the
230 <command>inetd</command> meta-daemon, this file
231 must contain suitable startup information for the
232 meta-daemon. See the section INSTALLATION below.
237 <term><filename>/etc/rc</filename></term>
238 <listitem><para>or whatever initialization script your
241 <para>If running the server as a daemon at startup,
242 this file will need to contain an appropriate startup
243 sequence for the server. See the section INSTALLATION
244 below.</para></listitem>
248 <term><filename>/etc/services</filename></term>
249 <listitem><para>If running the server via the
250 meta-daemon <command>inetd</command>, this file
251 must contain a mapping of service name (e.g., netbios-ssn)
252 to service port (e.g., 139) and protocol type (e.g., tcp).
253 See the section INSTALLATION below.</para></listitem>
257 <term><filename>/usr/local/samba/lib/smb.conf</filename></term>
258 <listitem><para>This is the default location of the
259 <ulink url="smb.conf.5.html"><filename>smb.conf</filename></ulink>
260 server configuration file. Other common places that systems
261 install this file are <filename>/usr/samba/lib/smb.conf</filename>
262 and <filename>/etc/smb.conf</filename>.</para>
264 <para>This file describes all the services the server
265 is to make available to clients. See <ulink url="smb.conf.5.html">
266 <filename>smb.conf(5)</filename></ulink> for more information.</para>
273 <title>LIMITATIONS</title>
274 <para>On some systems <command>smbd</command> cannot change uid back
275 to root after a setuid() call. Such systems are called
276 trapdoor uid systems. If you have such a system,
277 you will be unable to connect from a client (such as a PC) as
278 two different users at once. Attempts to connect the
279 second user will result in access denied or
284 <title>ENVIRONMENT VARIABLES</title>
288 <term><envar>PRINTER</envar></term>
289 <listitem><para>If no printer name is specified to
290 printable services, most systems will use the value of
291 this variable (or <constant>lp</constant> if this variable is
292 not defined) as the name of the printer to use. This
293 is not specific to the server, however.</para></listitem>
299 <title>INSTALLATION</title>
301 <para>The location of the server and its support files
302 is a matter for individual system administrators. The following
303 are thus suggestions only.</para>
305 <para>It is recommended that the server software be installed
306 under the <filename>/usr/local/samba/</filename> hierarchy,
307 in a directory readable by all, writeable only by root. The server
308 program itself should be executable by all, as users may wish to
309 run the server themselves (in which case it will of course run
310 with their privileges). The server should NOT be setuid. On some
311 systems it may be worthwhile to make <command>smbd</command> setgid to an empty group.
312 This is because some systems may have a security hole where daemon
313 processes that become a user can be attached to with a debugger.
314 Making the <command>smbd</command> file setgid to an empty group may prevent
315 this hole from being exploited. This security hole and the suggested
316 fix has only been confirmed on old versions (pre-kernel 2.0) of Linux
317 at the time this was written. It is possible that this hole only
318 exists in Linux, as testing on other systems has thus far shown them
321 <para>The server log files should be put in a directory readable and
322 writeable only by root, as the log files may contain sensitive
325 <para>The configuration file should be placed in a directory
326 readable and writeable only by root, as the configuration file
327 controls security for the services offered by the server. The
328 configuration file can be made readable by all if desired, but
329 this is not necessary for correct operation of the server and is
330 not recommended. A sample configuration file <filename>smb.conf.sample
331 </filename> is supplied with the source to the server - this may
332 be renamed to <filename>smb.conf</filename> and modified to suit
335 <para>The remaining notes will assume the following:</para>
338 <listitem><para><command>smbd</command> (the server program)
339 installed in <filename>/usr/local/samba/bin</filename></para>
342 <listitem><para><filename>smb.conf</filename> (the configuration
343 file) installed in <filename>/usr/local/samba/lib</filename></para>
346 <listitem><para>log files stored in <filename>/var/adm/smblogs
347 </filename></para></listitem>
350 <para>The server may be run either as a daemon by users
351 or at startup, or it may be run from a meta-daemon such as
352 <command>inetd</command> upon request. If run as a daemon,
353 the server will always be ready, so starting sessions will be
354 faster. If run from a meta-daemon some memory will be saved and
355 utilities such as the tcpd TCP-wrapper may be used for extra
356 security. For serious use as file server it is recommended
357 that <command>smbd</command> be run as a daemon.</para>
359 <para>When you've decided, continue with either</para>
362 <listitem><para>RUNNING THE SERVER AS A DAEMON or</para></listitem>
363 <listitem><para>RUNNING THE SERVER ON REQUEST.</para></listitem>
368 <title>RUNNING THE SERVER AS A DAEMON</title>
370 <para>To run the server as a daemon from the command
371 line, simply put the <emphasis>-D</emphasis> option on the
372 command line. There is no need to place an ampersand at
373 the end of the command line - the <emphasis>-D</emphasis>
374 option causes the server to detach itself from the tty
377 <para>Any user can run the server as a daemon (execute
378 permissions permitting, of course). This is useful for
379 testing purposes, and may even be useful as a temporary
380 substitute for something like ftp. When run this way, however,
381 the server will only have the privileges of the user who ran
384 <para>To ensure that the server is run as a daemon whenever
385 the machine is started, and to ensure that it runs as root
386 so that it can serve multiple clients, you will need to modify
387 the system startup files. Wherever appropriate (for example, in
388 <filename>/etc/rc</filename>), insert the following line,
389 substituting port number, log file location, configuration file
390 location and debug level as desired:</para>
392 <para><command>/usr/local/samba/bin/smbd -D -l /var/adm/smblogs/log
393 -s /usr/local/samba/lib/smb.conf</command></para>
395 <para>(The above should appear in your initialization script
396 as a single line. Depending on your terminal characteristics,
397 it may not appear that way in this man page. If the above appears
398 as more than one line, please treat any newlines or indentation
399 as a single space or TAB character.)</para>
401 <para>If the options used at compile time are appropriate for
402 your system, all parameters except <emphasis>-D</emphasis> may
403 be omitted. See the section OPTIONS above.</para>
407 <title>RUNNING THE SERVER ON REQUEST</title>
409 <para>If your system uses a meta-daemon such as <command>inetd
410 </command>, you can arrange to have the <command>smbd</command> server started
411 whenever a process attempts to connect to it. This requires several
412 changes to the startup files on the host machine. If you are
413 experimenting as an ordinary user rather than as root, you will
414 need the assistance of your system administrator to modify the
417 <para>You will probably want to set up the NetBIOS name server
418 <ulink url="nmbd.8.html"><command>nmbd</command></ulink> at
419 the same time as <command>smbd</command>. To do this refer to the
420 man page for <ulink url="nmbd.8.html"><command>nmbd(8)</command>
423 <para>First, ensure that a port is configured in the file
424 <filename>/etc/services</filename>. The well-known port 139
425 should be used if possible, though any port may be used.</para>
427 <para>Ensure that a line similar to the following is in
428 <filename>/etc/services</filename>:</para>
430 <para><command>netbios-ssn 139/tcp</command></para>
432 <para>Note for NIS/YP users - you may need to rebuild the
433 NIS service maps rather than alter your local <filename>/etc/services
434 </filename> file.</para>
436 <para>Next, put a suitable line in the file <filename>/etc/inetd.conf
437 </filename> (in the unlikely event that you are using a meta-daemon
438 other than inetd, you are on your own). Note that the first item
439 in this line matches the service name in <filename>/etc/services
440 </filename>. Substitute appropriate values for your system
441 in this line (see <command>inetd(8)</command>):</para>
443 <para><command>netbios-ssn stream tcp nowait root /usr/local/samba/bin/smbd
444 -d1 -l/var/adm/smblogs/log -s/usr/local/samba/lib/smb.conf</command></para>
446 <para>(The above should appear in <filename>/etc/inetd.conf</filename>
447 as a single line. Depending on your terminal characteristics, it may
448 not appear that way in this man page. If the above appears as more
449 than one line, please treat any newlines or indentation as a single
450 space or TAB character.)</para>
452 <para>Note that there is no need to specify a port number here,
453 even if you are using a non-standard port number.</para>
455 <para>Lastly, edit the configuration file to provide suitable
456 services. To start with, the following two services should be
472 <para>This will allow you to connect to your home directory
473 and print to any printer supported by the host (user privileges
478 <title>PAM INTERACTION</title>
479 <para>Samba uses PAM for authentication (when presented with a plaintext
480 password), for account checking (is this account disabled?) and for
481 session management. The degree too which samba supports PAM is restricted
482 by the limitations of the SMB protocol and the
483 <ulink url="smb.conf.5.html#OBEYPAMRESRICTIONS">obey pam restricions</ulink>
484 smb.conf paramater. When this is set, the following restrictions apply:
488 <listitem><para><emphasis>Account Validation</emphasis>: All acccesses to a
489 samba server are checked
490 against PAM to see if the account is vaild, not disabled and is permitted to
491 login at this time. This also applies to encrypted logins.
494 <listitem><para><emphasis>Session Management</emphasis>: When not using share
495 level secuirty, users must pass PAM's session checks before access
496 is granted. Note however, that this is bypassed in share level secuirty.
497 Note also that some older pam configuration files may need a line
498 added for session support.
504 <title>TESTING THE INSTALLATION</title>
506 <para>If running the server as a daemon, execute it before
507 proceeding. If using a meta-daemon, either restart the system
508 or kill and restart the meta-daemon. Some versions of
509 <command>inetd</command> will reread their configuration
510 tables if they receive a HUP signal.</para>
512 <para>If your machine's name is <replaceable>fred</replaceable> and your
513 name is <replaceable>mary</replaceable>, you should now be able to connect
514 to the service <filename>\\fred\mary</filename>.
517 <para>To properly test and experiment with the server, we
518 recommend using the <command>smbclient</command> program (see
519 <ulink url="smbclient.1.html"><command>smbclient(1)</command></ulink>)
520 and also going through the steps outlined in the file
521 <filename>DIAGNOSIS.txt</filename> in the <filename>docs/</filename>
522 directory of your Samba installation.</para>
526 <title>VERSION</title>
528 <para>This man page is correct for version 2.2 of
529 the Samba suite.</para>
533 <title>DIAGNOSTICS</title>
535 <para>Most diagnostics issued by the server are logged
536 in a specified log file. The log file name is specified
537 at compile time, but may be overridden on the command line.</para>
539 <para>The number and nature of diagnostics available depends
540 on the debug level used by the server. If you have problems, set
541 the debug level to 3 and peruse the log files.</para>
543 <para>Most messages are reasonably self-explanatory. Unfortunately,
544 at the time this man page was created, there are too many diagnostics
545 available in the source code to warrant describing each and every
546 diagnostic. At this stage your best bet is still to grep the
547 source code and inspect the conditions that gave rise to the
548 diagnostics you are seeing.</para>
552 <title>SIGNALS</title>
554 <para>Sending the <command>smbd</command> a SIGHUP will cause it to
555 reload its <filename>smb.conf</filename> configuration
556 file within a short period of time.</para>
558 <para>To shut down a user's <command>smbd</command> process it is recommended
559 that <command>SIGKILL (-9)</command> <emphasis>NOT</emphasis>
560 be used, except as a last resort, as this may leave the shared
561 memory area in an inconsistent state. The safe way to terminate
562 an <command>smbd</command> is to send it a SIGTERM (-15) signal and wait for
563 it to die on its own.</para>
565 <para>The debug log level of <command>smbd</command> may be raised
566 or lowered using <ulink url="smbcontrol.1.html"><command>smbcontrol(1)
567 </command></ulink> program (SIGUSR[1|2] signals are no longer used in
568 Samba 2.2). This is to allow transient problems to be diagnosed,
569 whilst still running at a normally low log level.</para>
571 <para>Note that as the signal handlers send a debug write,
572 they are not re-entrant in <command>smbd</command>. This you should wait until
573 <command>smbd</command> is in a state of waiting for an incoming SMB before
574 issuing them. It is possible to make the signal handlers safe
575 by un-blocking the signals before the select call and re-blocking
576 them after, however this would affect performance.</para>
580 <title>SEE ALSO</title>
581 <para>hosts_access(5), <command>inetd(8)</command>,
582 <ulink url="nmbd.8.html"><command>nmbd(8)</command></ulink>,
583 <ulink url="smb.conf.5.html"><filename>smb.conf(5)</filename>
584 </ulink>, <ulink url="smbclient.1.html"><command>smbclient(1)
585 </command></ulink>, <ulink url="testparm.1.html"><command>
586 testparm(1)</command></ulink>, <ulink url="testprns.1.html">
587 <command>testprns(1)</command></ulink>, and the Internet RFC's
588 <filename>rfc1001.txt</filename>, <filename>rfc1002.txt</filename>.
589 In addition the CIFS (formerly SMB) specification is available
590 as a link from the Web page <ulink url="http://samba.org/cifs/">
591 http://samba.org/cifs/</ulink>.</para>
595 <title>AUTHOR</title>
597 <para>The original Samba software and related utilities
598 were created by Andrew Tridgell. Samba is now developed
599 by the Samba Team as an Open Source project similar
600 to the way the Linux kernel is developed.</para>
602 <para>The original Samba man pages were written by Karl Auer.
603 The man page sources were converted to YODL format (another
604 excellent piece of Open Source software, available at
605 <ulink url="ftp://ftp.icce.rug.nl/pub/unix/">
606 ftp://ftp.icce.rug.nl/pub/unix/</ulink>) and updated for the Samba 2.0
607 release by Jeremy Allison. The conversion to DocBook for
608 Samba 2.2 was done by Gerald Carter</para>