docs/docbook/manpages/smbd.8.sgml

   1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
   2 <refentry id="smbd">
   3
   4 <refmeta>
   5         <refentrytitle>smbd</refentrytitle>
   6         <manvolnum>8</manvolnum>
   7 </refmeta>
   8
   9
  10 <refnamediv>
  11         <refname>smbd</refname>
  12         <refpurpose>server to provide SMB/CIFS services to clients</refpurpose>
  13 </refnamediv>
  14
  15 <refsynopsisdiv>
  16         <cmdsynopsis>
  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">-d &lt;debug level&gt;</arg>
  25                 <arg choice="opt">-l &lt;log file&gt;</arg>
  26                 <arg choice="opt">-p &lt;port number&gt;</arg>
  27                 <arg choice="opt">-O &lt;socket option&gt;</arg>
  28                 <arg choice="opt">-s &lt;configuration file&gt;</arg>
  29         </cmdsynopsis>
  30 </refsynopsisdiv>
  31
  32 <refsect1>
  33         <title>DESCRIPTION</title>
  34         <para>This program is part of the Samba suite.</para>
  35
  36         <para><command>smbd</command> is the server daemon that
  37         provides filesharing and printing services to Windows clients.
  38         The server provides filespace and printer services to
  39         clients using the SMB (or CIFS) protocol. This is compatible
  40         with the LanManager protocol, and can service LanManager
  41         clients.  These include MSCLIENT 3.0 for DOS, Windows for
  42         Workgroups, Windows 95/98/ME, Windows NT, Windows 2000,
  43         OS/2, DAVE for Macintosh, and smbfs for Linux.</para>
  44
  45         <para>An extensive description of the services that the
  46         server can provide is given in the man page for the
  47         configuration file controlling the attributes of those
  48         services (see <ulink url="smb.conf.5.html"><filename>smb.conf(5)
  49         </filename></ulink>.  This man page will not describe the
  50         services, but will concentrate on the administrative aspects
  51         of running the server.</para>
  52
  53         <para>Please note that there are significant security
  54         implications to running this server, and the <ulink
  55         url="smb.conf.5.html"><filename>smb.conf(5)</filename></ulink>
  56         manpage should be regarded as mandatory reading before
  57         proceeding with installation.</para>
  58
  59         <para>A session is created whenever a client requests one.
  60         Each client gets a copy of the server for each session. This
  61         copy then services all connections made by the client during
  62         that session. When all connections from its client are closed,
  63         the copy of the server for that client terminates.</para>
  64
  65         <para>The configuration file, and any files that it includes,
  66         are automatically reloaded every minute, if they change.  You
  67         can force a reload by sending a SIGHUP to the server.  Reloading
  68         the configuration file will not affect connections to any service
  69         that is already established.  Either the user will have to
  70         disconnect from the service, or smbd killed and restarted.</para>
  71 </refsect1>
  72
  73 <refsect1>
  74         <title>OPTIONS</title>
  75
  76         <variablelist>
  77                 <varlistentry>
  78                 <term>-D</term>
  79                 <listitem><para>If specified, this parameter causes
  80                 the server to operate as a daemon. That is, it detaches
  81                 itself and runs in the background, fielding requests
  82                 on the appropriate port. Operating the server as a
  83                 daemon is the recommended way of running smbd for
  84                 servers that provide more than casual use file and
  85                 print services.  This switch is assumed is <command>smbd
  86                 </command> is executed on the command line of a shell.
  87                 </para></listitem>
  88                 </varlistentry>
  89
  90                 <varlistentry>
  91                 <term>-a</term>
  92                 <listitem><para>If this parameter is specified, each new
  93                 connection will append log messages to the log file.
  94                 This is the default.</para></listitem>
  95                 </varlistentry>
  96
  97                 <varlistentry>
  98                 <term>-o</term>
  99                 <listitem><para>If this parameter is specified, the
 100                 log files will be overwritten when opened.  By default,
 101                 <command>smbd</command> will append entries to the log
 102                 files.</para></listitem>
 103                 </varlistentry>
 104
 105                 <varlistentry>
 106                 <term>-P</term>
 107                 <listitem><para>Passive option. Causes smbd not to
 108                 send any network traffic out. Used for debugging by
 109                 the developers only.</para></listitem>
 110                 </varlistentry>
 111
 112                 <varlistentry>
 113                 <term>-h</term>
 114                 <listitem><para>Prints the help information (usage)
 115                 for <command>smbd</command>.</para></listitem>
 116                 </varlistentry>
 117
 118                 <varlistentry>
 119                 <term>-v</term>
 120                 <listitem><para>Prints the version number for
 121                 <command>smbd</command>.</para></listitem>
 122                 </varlistentry>
 123
 124                 <varlistentry>
 125                 <term>-d &lt;debug level&gt;</term>
 126                 <listitem><para>debuglevel is an integer
 127                 from 0 to 10.  The default value if this parameter is
 128                 not specified is zero.</para>
 129
 130                 <para>The higher this value, the more detail will be
 131                 logged to the log files about the activities of the
 132                 server. At level 0, only critical errors and serious
 133                 warnings will be logged. Level 1 is a reasonable level for
 134                 day to day running - it generates a small amount of
 135                 information about operations carried out.</para>
 136
 137                 <para>Levels above 1 will generate considerable
 138                 amounts of log data, and should only be used when
 139                 investigating a problem. Levels above 3 are designed for
 140                 use only by developers and generate HUGE amounts of log
 141                 data, most of which is extremely cryptic.</para>
 142
 143                 <para>Note that specifying this parameter here will
 144                 override the <ulink url="smb.conf.5.html#loglevel">log
 145                 level</ulink> parameter in the <ulink url="smb.conf.5.html">
 146                 <filename>smb.conf(5)</filename></ulink> file.</para>
 147                 </listitem>
 148                 </varlistentry>
 149
 150                 <varlistentry>
 151                 <term>-l &lt;log file&gt;</term>
 152                 <listitem><para>If specified, <emphasis>log file</emphasis>
 153                 specifies a log filename into which informational and debug
 154                 messages from the running server will be logged. The log
 155                 file generated is never removed by the server although
 156                 its size may be controlled by the <ulink
 157                 url="smb.conf.5.html#maxlogsize">max log size</ulink>
 158                 option in the <ulink url="smb.conf.5.html"><filename>
 159                 smb.conf(5)</filename></ulink> file.  The default log
 160                 file name is specified at compile time.</para></listitem>
 161                 </varlistentry>
 162
 163                 <varlistentry>
 164                 <term>-O &lt;socket options&gt;</term>
 165                 <listitem><para>See the <ulink
 166                 url="smb.conf.5.html#socketoptions">socket options</ulink>
 167                 parameter in the <ulink url="smb.conf.5.html"><filename>smb.conf(5)
 168                 </filename></ulink> file for details.</para></listitem>
 169                 </varlistentry>
 170
 171                 <varlistentry>
 172                 <term>-p &lt;port number&gt;</term>
 173                 <listitem><para>port number is a positive integer
 174                 value.  The default value if this parameter is not
 175                 specified is 139.</para>
 176
 177                 <para>This number is the port number that will be
 178                 used when making connections to the server from client
 179                 software. The standard (well-known) port number for the
 180                 SMB over TCP is 139, hence the default. If you wish to
 181                 run the server as an ordinary user rather than
 182                 as root, most systems will require you to use a port
 183                 number greater than 1024 - ask your system administrator
 184                 for help if you are in this situation.</para>
 185
 186                 <para>In order for the server to be useful by most
 187                 clients, should you configure it on a port other
 188                 than 139, you will require port redirection services
 189                 on port 139, details of which are outlined in rfc1002.txt
 190                 section 4.3.5.</para>
 191
 192                 <para>This parameter is not normally specified except
 193                 in the above situation.</para></listitem>
 194                 </varlistentry>
 195
 196                 <varlistentry>
 197                 <term>-s &lt;configuration file&gt;</term>
 198                 <listitem><para>The file specified contains the
 199                 configuration details required by the server.  The
 200                 information in this file includes server-specific
 201                 information such as what printcap file to use, as well
 202                 as descriptions of all the services that the server is
 203                 to provide. See <ulink url="smb.conf.5.html"><filename>
 204                 smb.conf(5)</filename></ulink> for more information.
 205                 The default configuration file name is determined at
 206                 compile time.</para></listitem>
 207                 </varlistentry>
 208         </variablelist>
 209 </refsect1>
 210
 211 <refsect1>
 212         <title>FILES</title>
 213
 214         <variablelist>
 215                 <varlistentry>
 216                 <term><filename>/etc/inetd.conf</filename></term>
 217                 <listitem><para>If the server is to be run by the
 218                 <command>inetd</command> meta-daemon, this file
 219                 must contain suitable startup information for the
 220                 meta-daemon. See the section INSTALLATION below.
 221                 </para></listitem>
 222                 </varlistentry>
 223
 224                 <varlistentry>
 225                 <term><filename>/etc/rc</filename></term>
 226                 <listitem><para>or whatever initialization script your
 227                 system uses).</para>
 228
 229                 <para>If running the server as a daemon at startup,
 230                 this file will need to contain an appropriate startup
 231                 sequence for the server. See the section INSTALLATION
 232                 below.</para></listitem>
 233                 </varlistentry>
 234
 235                 <varlistentry>
 236                 <term><filename>/etc/services</filename></term>
 237                 <listitem><para>If running the server via the
 238                 meta-daemon <command>inetd</command>, this file
 239                 must contain a mapping of service name (e.g., netbios-ssn)
 240                 to service port (e.g., 139) and protocol type (e.g., tcp).
 241                 See the section INSTALLATION below.</para></listitem>
 242                 </varlistentry>
 243
 244                 <varlistentry>
 245                 <term><filename>/usr/local/samba/lib/smb.conf</filename></term>
 246                 <listitem><para>This is the default location of the
 247                 <ulink url="smb.conf.5.html"><filename>smb.conf</filename></ulink>
 248                 server configuration file. Other common places that systems
 249                 install this file are <filename>/usr/samba/lib/smb.conf</filename>
 250                 and <filename>/etc/smb.conf</filename>.</para>
 251
 252                 <para>This file describes all the services the server
 253                 is to make available to clients. See <ulink url="smb.conf.5.html">
 254                 <filename>smb.conf(5)</filename></ulink>  for more information.</para>
 255                 </listitem>
 256                 </varlistentry>
 257         </variablelist>
 258 </refsect1>
 259
 260 <refsect1>
 261         <title>LIMITATIONS</title>
 262         <para>On some systems <command>smbd</command> cannot change uid back
 263         to root after a setuid() call.  Such systems are called
 264         &quot;trapdoor&quot; uid systems. If you have such a system,
 265         you will be unable to connect from a client (such as a PC) as
 266         two different users at once. Attempts to connect the
 267         second user will result in &quot;access denied&quot; or
 268         similar.</para>
 269 </refsect1>
 270
 271 <refsect1>
 272         <title>ENVIRONMENTVARIABLES</title>
 273
 274         <variablelist>
 275                 <varlistentry>
 276                 <term>PRINTER</term>
 277                 <listitem><para>If no printer name is specified to
 278                 printable services, most systems will use the value of
 279                 this variable (or &quot;lp&quot; if this variable is
 280                 not defined) as the name of the printer to use. This
 281                 is not specific to the server, however.</para></listitem>
 282                 </varlistentry>
 283         </variablelist>
 284 </refsect1>
 285
 286 <refsect1>
 287         <title>INSTALLATION</title>
 288
 289         <para>The location of the server and its support files
 290         is a matter for individual system administrators. The following
 291         are thus suggestions only.</para>
 292
 293         <para>It is recommended that the server software be installed
 294         under the <filename>/usr/local/samba/</filename> hierarchy,
 295         in a directory readable by all, writeable only by root. The server
 296         program itself should be executable by all, as users may wish to
 297         run the server themselves (in which case it will of course run
 298         with their privileges).  The server should NOT be setuid. On some
 299         systems it may be worthwhile to make smbd setgid to an empty group.
 300         This is because some systems may have a security hole where daemon
 301         processes that become a user can be attached to with a debugger.
 302         Making the smbd file setgid to an empty group may prevent
 303         this hole from being exploited. This security hole and the suggested
 304         fix has only been confirmed on old versions (pre-kernel 2.0) of Linux
 305         at the time this was written. It is possible that this hole only
 306         exists in Linux, as testing on other systems has thus far shown them
 307         to be immune.</para>
 308
 309         <para>The server log files should be put in a directory readable and
 310         writeable only by root, as the log files may contain sensitive
 311         information.</para>
 312
 313         <para>The configuration file should be placed in a directory
 314         readable and writeable only by root, as the configuration file
 315         controls security for the services offered by the server. The
 316         configuration file can be made readable by all if desired, but
 317         this is not necessary for correct operation of the server and is
 318         not recommended. A sample configuration file <filename>smb.conf.sample
 319         </filename> is supplied with the source to the server - this may
 320         be renamed to <filename>smb.conf</filename> and modified to suit
 321         your needs.</para>
 322
 323         <para>The remaining notes will assume the following:</para>
 324
 325         <itemizedlist>
 326                 <listitem><para><command>smbd</command> (the server program)
 327                 installed in <filename>/usr/local/samba/bin</filename></para>
 328                 </listitem>
 329
 330                 <listitem><para><filename>smb.conf</filename> (the configuration
 331                 file) installed in <filename>/usr/local/samba/lib</filename></para>
 332                 </listitem>
 333
 334                 <listitem><para>log files stored in <filename>/var/adm/smblogs
 335                 </filename></para></listitem>
 336         </itemizedlist>
 337
 338         <para>The server may be run either as a daemon by users
 339         or at startup, or it may be run from a meta-daemon such as
 340         <command>inetd</command> upon request. If run as a daemon,
 341         the server will always be ready, so starting sessions will be
 342         faster. If run from a meta-daemon some memory will be saved and
 343         utilities such as the tcpd TCP-wrapper may be used for extra
 344         security.  For serious use as file server it is recommended
 345         that <command>smbd</command> be run as a daemon.</para>
 346
 347         <para>When you've decided, continue with either</para>
 348
 349         <itemizedlist>
 350                 <listitem><para>RUNNING THE SERVER AS A DAEMON or</para></listitem>
 351                 <listitem><para>RUNNING THE SERVER ON REQUEST.</para></listitem>
 352         </itemizedlist>
 353 </refsect1>
 354
 355 <refsect1>
 356         <title>RUNNING THE SERVER AS A DAEMON</title>
 357
 358         <para>To run the server as a daemon from the command
 359         line, simply put the <emphasis>-D</emphasis> option on the
 360         command line. There is no need to place an ampersand at
 361         the end of the command line - the <emphasis>-D</emphasis>
 362         option causes the server to detach itself from the tty
 363         anyway.</para>
 364
 365         <para>Any user can run the server as a daemon (execute
 366         permissions permitting, of course). This is useful for
 367         testing purposes, and may even be useful as a temporary
 368         substitute for something like ftp. When run this way, however,
 369         the server will only have the privileges of the user who ran
 370         it.</para>
 371
 372         <para>To ensure that the server is run as a daemon whenever
 373         the machine is started, and to ensure that it runs as root
 374         so that it can serve multiple clients, you will need to modify
 375         the system startup files. Wherever appropriate (for example, in
 376         <filename>/etc/rc</filename>), insert the following line,
 377         substituting port number, log file location, configuration file
 378         location and debug level as desired:</para>
 379
 380         <para><command>/usr/local/samba/bin/smbd -D -l /var/adm/smblogs/log
 381         -s /usr/local/samba/lib/smb.conf</command></para>
 382
 383         <para>(The above should appear in your initialization script
 384         as a single line.  Depending on your terminal characteristics,
 385         it may not appear that way in this man page. If the above appears
 386         as more than one line, please treat any newlines or indentation
 387         as a single space or TAB character.)</para>
 388
 389         <para>If the options used at compile time are appropriate for
 390         your system, all parameters except <emphasis>-D</emphasis> may
 391         be omitted. See the section OPTIONS above.</para>
 392 </refsect1>
 393
 394 <refsect1>
 395         <title>RUNNING THE SERVER ON REQUEST</title>
 396
 397         <para>If your system uses a meta-daemon such as <command>inetd
 398         </command>, you can arrange to have the smbd server started
 399         whenever a process attempts to connect to it. This requires several
 400         changes to the startup files on the host machine. If you are
 401         experimenting as an ordinary user rather than as root, you will
 402         need the assistance of your system administrator to modify the
 403         system files.</para>
 404
 405         <para>You will probably want to set up the NetBIOS name server
 406         <ulink url="nmbd.8.html"><command>nmbd</command></ulink> at
 407         the same time as <command>smbd</command>. To do this refer to the
 408         man page for <ulink url="nmbd.8.html"><command>nmbd(8)</command>
 409         </ulink>.</para>
 410
 411         <para>First, ensure that a port is configured in the file
 412         <filename>/etc/services</filename>. The well-known port 139
 413         should be used if possible, though any port may be used.</para>
 414
 415         <para>Ensure that a line similar to the following is in
 416         <filename>/etc/services</filename>:</para>
 417
 418         <para><command>netbios-ssn      139/tcp</command></para>
 419
 420         <para>Note for NIS/YP users - you may need to rebuild the
 421         NIS service maps rather than alter your local <filename>/etc/services
 422         </filename> file.</para>
 423
 424         <para>Next, put a suitable line in the file <filename>/etc/inetd.conf
 425         </filename> (in the unlikely event that you are using a meta-daemon
 426         other than inetd, you are on your own). Note that the first item
 427         in this line matches the service name in <filename>/etc/services
 428         </filename>.  Substitute appropriate values for your system
 429         in this line (see <command>inetd(8)</command>):</para>
 430
 431         <para><command>netbios-ssn stream tcp nowait root /usr/local/samba/bin/smbd
 432         -d1 -l/var/adm/smblogs/log -s/usr/local/samba/lib/smb.conf</command></para>
 433
 434         <para>(The above should appear in <filename>/etc/inetd.conf</filename>
 435         as a single line. Depending on your terminal characteristics, it may
 436         not appear that way in this man page.  If the above appears as more
 437         than one line, please treat any newlines or indentation as a single
 438         space or TAB character.)</para>
 439
 440         <para>Note that there is no need to specify a port number here,
 441         even if you are using a non-standard port number.</para>
 442
 443         <para>Lastly, edit the configuration file to provide suitable
 444         services. To start with, the following two services should be
 445         all you need:</para>
 446
 447         <screen>
 448         <computeroutput>
 449         [homes]
 450                 writeable = yes
 451
 452         [printers]
 453                 writeable = no
 454                 printable = yes
 455                 path = /tmp
 456                 public = yes
 457         </computeroutput>
 458         </screen>
 459
 460         <para>This will allow you to connect to your home directory
 461         and print to any printer supported by the host (user privileges
 462         permitting).</para>
 463 </refsect1>
 464
 465 <refsect1>
 466         <title>TESTING THE INSTALLATION</title>
 467
 468         <para>If running the server as a daemon, execute it before
 469         proceeding. If using a meta-daemon, either restart the system
 470         or kill and restart the meta-daemon. Some versions of
 471         <command>inetd</command> will reread their configuration
 472         tables if they receive a HUP signal.</para>
 473
 474         <para>If your machine's name is &quot;fred&quot; and your
 475         name is &quot;mary&quot;, you should now be able to connect
 476         to the service <filename>&bsol;&bsol;fred&bsol;mary</filename>.
 477         </para>
 478
 479         <para>To properly test and experiment with the server, we
 480         recommend using the <command>smbclient</command> program (see
 481         <ulink url="smbclient.1.html"><command>smbclient(1)</command></ulink>)
 482         and also going through the steps outlined in the file
 483         <filename>DIAGNOSIS.txt</filename> in the <filename>docs/</filename>
 484         directory of your Samba installation.</para>
 485 </refsect1>
 486
 487 <refsect1>
 488         <title>VERSION</title>
 489
 490         <para>This man page is correct for version 2.2 of
 491         the Samba suite.</para>
 492 </refsect1>
 493
 494 <refsect1>
 495         <title>DIAGNOSTICS</title>
 496
 497         <para>Most diagnostics issued by the server are logged
 498         in a specified log file. The log file name is specified
 499         at compile time, but may be overridden on the command line.</para>
 500
 501         <para>The number and nature of diagnostics available depends
 502         on the debug level used by the server. If you have problems, set
 503         the debug level to 3 and peruse the log files.</para>
 504
 505         <para>Most messages are reasonably self-explanatory. Unfortunately,
 506         at the time this man page was created, there are too many diagnostics
 507         available in the source code to warrant describing each and every
 508         diagnostic. At this stage your best bet is still to grep the
 509         source code and inspect the conditions that gave rise to the
 510         diagnostics you are seeing.</para>
 511 </refsect1>
 512
 513 <refsect1>
 514         <title>SIGNALS</title>
 515
 516         <para>Sending the smbd a SIGHUP will cause it to
 517         re-load its <filename>smb.conf</filename> configuration
 518         file within a short period of time.</para>
 519
 520         <para>To shut down a users smbd process it is recommended
 521         that <command>SIGKILL (-9)</command> <emphasis>NOT</emphasis>
 522         be used, except as a last resort, as this may leave the shared
 523         memory area in an inconsistent state. The safe way to terminate
 524         an smbd is to send it a SIGTERM (-15) signal and wait for
 525         it to die on its own.</para>
 526
 527         <para>The debug log level of smbd may be raised by sending
 528         it a SIGUSR1 (<command>kill -USR1 &lt;smbd-pid&gt;</command>)
 529         and lowered by sending it a SIGUSR2 (<command>kill -USR2 &lt;smbd-pid&gt;
 530         </command>). This is to allow transient problems to be diagnosed,
 531         whilst still running at a normally low log level.</para>
 532
 533         <para>Note that as the signal handlers send a debug write,
 534         they are not re-entrant in smbd. This you should wait until
 535         smbd is in a state of waiting for an incoming smb before
 536         issuing them. It is possible to make the signal handlers safe
 537         by un-blocking the signals before the select call and re-blocking
 538         them after, however this would affect performance.</para>
 539 </refsect1>
 540
 541 <refsect1>
 542         <title>SEE ALSO</title>
 543         <para>hosts_access(5), <command>inetd(8)</command>,
 544         <ulink url="nmbd.8.html"><command>nmbd(8)</command></ulink>,
 545         <ulink url="smb.conf.5.html"><filename>smb.conf(5)</filename>
 546         </ulink>, <ulink url="smbclient.1.html"><command>smbclient(1)
 547         </command></ulink>, <ulink url="testparm.1.html"><command>
 548         testparm(1)</command></ulink>, <ulink url="testprns.1.html">
 549         <command>testprns(1)</command></ulink>, and the Internet RFC's
 550         <filename>rfc1001.txt</filename>, <filename>rfc1002.txt</filename>.
 551         In addition the CIFS (formerly SMB) specification is available
 552         as a link from the Web page <ulink url="http://samba.org/cifs/">
 553         http://samba.org/cifs/</ulink>.</para>
 554 </refsect1>
 555
 556 <refsect1>
 557         <title>AUTHOR</title>
 558
 559         <para>The original Samba software and related utilities
 560         were created by Andrew Tridgell. Samba is now developed
 561         by the Samba Team as an Open Source project similar
 562         to the way the Linux kernel is developed.</para>
 563
 564         <para>The original Samba man pages were written by Karl Auer.
 565         The man page sources were converted to YODL format (another
 566         excellent piece of Open Source software, available at
 567         <ulink url="ftp://ftp.icce.rug.nl/pub/unix/">
 568         ftp://ftp.icce.rug.nl/pub/unix/</ulink>) and updated for the Samba 2.0
 569         release by Jeremy Allison.  The conversion to DocBook for
 570         Samba 2.2 was done by Gerald Carter</para>
 571 </refsect1>
 572
 573 </refentry>