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">-F</arg>
  20                 <arg choice="opt">-S</arg>
  21                 <arg choice="opt">-i</arg>
  22                 <arg choice="opt">-h</arg>
  23                 <arg choice="opt">-V</arg>
  24                 <arg choice="opt">-b</arg>
  25                 <arg choice="opt">-d &lt;debug level&gt;</arg>
  26                 <arg choice="opt">-l &lt;log directory&gt;</arg>
  27                 <arg choice="opt">-p &lt;port number&gt;</arg>
  28                 <arg choice="opt">-O &lt;socket option&gt;</arg>
  29                 <arg choice="opt">-s &lt;configuration file&gt;</arg>
  30         </cmdsynopsis>
  31 </refsynopsisdiv>
  32
  33 <refsect1>
  34         <title>DESCRIPTION</title>
  35         <para>This program is part of the Samba suite.</para>
  36
  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>
  45
  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>
  53
  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>
  59
  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>
  65
  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>
  72 </refsect1>
  73
  74 <refsect1>
  75         <title>OPTIONS</title>
  76
  77         <variablelist>
  78                 <varlistentry>
  79                 <term>-D</term>
  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.
  88                 </para></listitem>
  89                 </varlistentry>
  90
  91                 <varlistentry>
  92                 <term>-F</term>
  93                 <listitem><para>If specified, this parameter causes
  94                 the main <command>smbd</command> process to not daemonize,
  95                 i.e. double-fork and disassociate with the terminal.
  96                 Child processes are still created as normal to service
  97                 each connection request, but the main process does not
  98                 exit. This operation mode is suitable for running
  99                 <command>smbd</command> under process supervisors such
 100                 as <command>supervise</command> and <command>svscan</command>
 101                 from Daniel J. Bernstein's <command>daemontools</command>
 102                 package, or the AIX process monitor.
 103                 </para></listitem>
 104                 </varlistentry>
 105
 106                 <varlistentry>
 107                 <term>-S</term>
 108                 <listitem><para>If specified, this parameter causes
 109                 <command>smbd</command> to log to standard output rather
 110                 than a file.</para></listitem>
 111                 </varlistentry>
 112
 113                 <varlistentry>
 114                 <term>-i</term>
 115                 <listitem><para>If this parameter is specified it causes the
 116                 server to run "interactively", not as a daemon, even if the
 117                 server is executed on the command line of a shell. Setting this
 118                 parameter negates the implicit deamon mode when run from the
 119                 command line. <command>smbd</command> also logs to standard
 120                 output, as if the <command>-S</command> parameter had been
 121                 given.
 122                 </para></listitem>
 123                 </varlistentry>
 124
 125                 <varlistentry>
 126                 <term>-h</term>
 127                 <listitem><para>Prints the help information (usage)
 128                 for <command>smbd</command>.</para></listitem>
 129                 </varlistentry>
 130
 131                 <varlistentry>
 132                 <term>-V</term>
 133                 <listitem><para>Prints the version number for
 134                 <command>smbd</command>.</para></listitem>
 135                 </varlistentry>
 136
 137                 <varlistentry>
 138                 <term>-b</term>
 139                 <listitem><para>Prints information about how
 140                 Samba was built.</para></listitem>
 141                 </varlistentry>
 142
 143                 <varlistentry>
 144                 <term>-d &lt;debug level&gt;</term>
 145                 <listitem><para><replaceable>debuglevel</replaceable> is an integer
 146                 from 0 to 10.  The default value if this parameter is
 147                 not specified is zero.</para>
 148
 149                 <para>The higher this value, the more detail will be
 150                 logged to the log files about the activities of the
 151                 server. At level 0, only critical errors and serious
 152                 warnings will be logged. Level 1 is a reasonable level for
 153                 day to day running - it generates a small amount of
 154                 information about operations carried out.</para>
 155
 156                 <para>Levels above 1 will generate considerable
 157                 amounts of log data, and should only be used when
 158                 investigating a problem. Levels above 3 are designed for
 159                 use only by developers and generate HUGE amounts of log
 160                 data, most of which is extremely cryptic.</para>
 161
 162                 <para>Note that specifying this parameter here will
 163                 override the <ulink url="smb.conf.5.html#loglevel">log
 164                 level</ulink> parameter in the <ulink url="smb.conf.5.html">
 165                 <filename>smb.conf(5)</filename></ulink> file.</para>
 166                 </listitem>
 167                 </varlistentry>
 168
 169                 <varlistentry>
 170                 <term>-l &lt;log directory&gt;</term>
 171                 <listitem><para>If specified,
 172                 <replaceable>log directory</replaceable>
 173                 specifies a log directory into which the "log.smbd" log
 174                 file will be created for informational and debug
 175                 messages from the running server. The log
 176                 file generated is never removed by the server although
 177                 its size may be controlled by the <ulink
 178                 url="smb.conf.5.html#maxlogsize">max log size</ulink>
 179                 option in the <ulink url="smb.conf.5.html"><filename>
 180                 smb.conf(5)</filename></ulink> file. <emphasis>Beware:</emphasis>
 181                 If the directory specified does not exist, <command>smbd</command>
 182                 will log to the default debug log location defined at compile time.
 183                 </para>
 184
 185                 <para>The default log directory is specified at
 186                 compile time.</para></listitem>
 187                 </varlistentry>
 188
 189                 <varlistentry>
 190                 <term>-O &lt;socket options&gt;</term>
 191                 <listitem><para>See the <ulink
 192                 url="smb.conf.5.html#socketoptions">socket options</ulink>
 193                 parameter in the <ulink url="smb.conf.5.html"><filename>smb.conf(5)
 194                 </filename></ulink> file for details.</para></listitem>
 195                 </varlistentry>
 196
 197                 <varlistentry>
 198                 <term>-p &lt;port number&gt;</term>
 199                 <listitem><para><replaceable>port number</replaceable> is a positive integer
 200                 value.  The default value if this parameter is not
 201                 specified is 139.</para>
 202
 203                 <para>This number is the port number that will be
 204                 used when making connections to the server from client
 205                 software. The standard (well-known) port number for the
 206                 SMB over TCP is 139, hence the default. If you wish to
 207                 run the server as an ordinary user rather than
 208                 as root, most systems will require you to use a port
 209                 number greater than 1024 - ask your system administrator
 210                 for help if you are in this situation.</para>
 211
 212                 <para>In order for the server to be useful by most
 213                 clients, should you configure it on a port other
 214                 than 139, you will require port redirection services
 215                 on port 139, details of which are outlined in rfc1002.txt
 216                 section 4.3.5.</para>
 217
 218                 <para>This parameter is not normally specified except
 219                 in the above situation.</para></listitem>
 220                 </varlistentry>
 221
 222                 <varlistentry>
 223                 <term>-s &lt;configuration file&gt;</term>
 224                 <listitem><para>The file specified contains the
 225                 configuration details required by the server.  The
 226                 information in this file includes server-specific
 227                 information such as what printcap file to use, as well
 228                 as descriptions of all the services that the server is
 229                 to provide. See <ulink url="smb.conf.5.html"><filename>
 230                 smb.conf(5)</filename></ulink> for more information.
 231                 The default configuration file name is determined at
 232                 compile time.</para></listitem>
 233                 </varlistentry>
 234         </variablelist>
 235 </refsect1>
 236
 237 <refsect1>
 238         <title>FILES</title>
 239
 240         <variablelist>
 241                 <varlistentry>
 242                 <term><filename>/etc/inetd.conf</filename></term>
 243                 <listitem><para>If the server is to be run by the
 244                 <command>inetd</command> meta-daemon, this file
 245                 must contain suitable startup information for the
 246                 meta-daemon. See the <ulink url="UNIX_INSTALL.html">UNIX_INSTALL.html</ulink>
 247                 document for details.
 248                 </para></listitem>
 249                 </varlistentry>
 250
 251                 <varlistentry>
 252                 <term><filename>/etc/rc</filename></term>
 253                 <listitem><para>or whatever initialization script your
 254                 system uses).</para>
 255
 256                 <para>If running the server as a daemon at startup,
 257                 this file will need to contain an appropriate startup
 258                 sequence for the server. See the <ulink url="UNIX_INSTALL.html">UNIX_INSTALL.html</ulink>
 259                 document for details.</para></listitem>
 260                 </varlistentry>
 261
 262                 <varlistentry>
 263                 <term><filename>/etc/services</filename></term>
 264                 <listitem><para>If running the server via the
 265                 meta-daemon <command>inetd</command>, this file
 266                 must contain a mapping of service name (e.g., netbios-ssn)
 267                 to service port (e.g., 139) and protocol type (e.g., tcp).
 268                 See the <ulink url="UNIX_INSTALL.html">UNIX_INSTALL.html</ulink>
 269                 document for details.</para></listitem>
 270                 </varlistentry>
 271
 272                 <varlistentry>
 273                 <term><filename>/usr/local/samba/lib/smb.conf</filename></term>
 274                 <listitem><para>This is the default location of the
 275                 <ulink url="smb.conf.5.html"><filename>smb.conf</filename></ulink>
 276                 server configuration file. Other common places that systems
 277                 install this file are <filename>/usr/samba/lib/smb.conf</filename>
 278                 and <filename>/etc/smb.conf</filename>.</para>
 279
 280                 <para>This file describes all the services the server
 281                 is to make available to clients. See <ulink url="smb.conf.5.html">
 282                 <filename>smb.conf(5)</filename></ulink>  for more information.</para>
 283                 </listitem>
 284                 </varlistentry>
 285         </variablelist>
 286 </refsect1>
 287
 288 <refsect1>
 289         <title>LIMITATIONS</title>
 290         <para>On some systems <command>smbd</command> cannot change uid back
 291         to root after a setuid() call.  Such systems are called
 292         trapdoor uid systems. If you have such a system,
 293         you will be unable to connect from a client (such as a PC) as
 294         two different users at once. Attempts to connect the
 295         second user will result in access denied or
 296         similar.</para>
 297 </refsect1>
 298
 299 <refsect1>
 300         <title>ENVIRONMENT VARIABLES</title>
 301
 302         <variablelist>
 303                 <varlistentry>
 304                 <term><envar>PRINTER</envar></term>
 305                 <listitem><para>If no printer name is specified to
 306                 printable services, most systems will use the value of
 307                 this variable (or <constant>lp</constant> if this variable is
 308                 not defined) as the name of the printer to use. This
 309                 is not specific to the server, however.</para></listitem>
 310                 </varlistentry>
 311         </variablelist>
 312 </refsect1>
 313
 314
 315 <refsect1>
 316         <title>PAM INTERACTION</title>
 317         <para>Samba uses PAM for authentication (when presented with a plaintext
 318         password), for account checking (is this account disabled?) and for
 319         session management.  The degree too which samba supports PAM is restricted
 320         by the limitations of the SMB protocol and the
 321         <ulink url="smb.conf.5.html#OBEYPAMRESRICTIONS">obey pam restricions</ulink>
 322         smb.conf paramater.  When this is set, the following restrictions apply:
 323         </para>
 324
 325         <itemizedlist>
 326         <listitem><para><emphasis>Account Validation</emphasis>:  All accesses to a
 327         samba server are checked
 328         against PAM to see if the account is vaild, not disabled and is permitted to
 329         login at this time.  This also applies to encrypted logins.
 330         </para></listitem>
 331
 332         <listitem><para><emphasis>Session Management</emphasis>:  When not using share
 333         level secuirty, users must pass PAM's session checks before access
 334         is granted.  Note however, that this is bypassed in share level secuirty.
 335         Note also that some older pam configuration files may need a line
 336         added for session support.
 337         </para></listitem>
 338         </itemizedlist>
 339 </refsect1>
 340
 341 <refsect1>
 342         <title>VERSION</title>
 343
 344         <para>This man page is correct for version 3.0 of
 345         the Samba suite.</para>
 346 </refsect1>
 347
 348 <refsect1>
 349         <title>DIAGNOSTICS</title>
 350
 351         <para>Most diagnostics issued by the server are logged
 352         in a specified log file. The log file name is specified
 353         at compile time, but may be overridden on the command line.</para>
 354
 355         <para>The number and nature of diagnostics available depends
 356         on the debug level used by the server. If you have problems, set
 357         the debug level to 3 and peruse the log files.</para>
 358
 359         <para>Most messages are reasonably self-explanatory. Unfortunately,
 360         at the time this man page was created, there are too many diagnostics
 361         available in the source code to warrant describing each and every
 362         diagnostic. At this stage your best bet is still to grep the
 363         source code and inspect the conditions that gave rise to the
 364         diagnostics you are seeing.</para>
 365 </refsect1>
 366
 367 <refsect1>
 368         <title>SIGNALS</title>
 369
 370         <para>Sending the <command>smbd</command> a SIGHUP will cause it to
 371         reload its <filename>smb.conf</filename> configuration
 372         file within a short period of time.</para>
 373
 374         <para>To shut down a user's <command>smbd</command> process it is recommended
 375         that <command>SIGKILL (-9)</command> <emphasis>NOT</emphasis>
 376         be used, except as a last resort, as this may leave the shared
 377         memory area in an inconsistent state. The safe way to terminate
 378         an <command>smbd</command> is to send it a SIGTERM (-15) signal and wait for
 379         it to die on its own.</para>
 380
 381         <para>The debug log level of <command>smbd</command> may be raised
 382         or lowered using <ulink url="smbcontrol.1.html"><command>smbcontrol(1)
 383         </command></ulink> program (SIGUSR[1|2] signals are no longer used in
 384         Samba 2.2). This is to allow transient problems to be diagnosed,
 385         whilst still running at a normally low log level.</para>
 386
 387         <para>Note that as the signal handlers send a debug write,
 388         they are not re-entrant in <command>smbd</command>. This you should wait until
 389         <command>smbd</command> is in a state of waiting for an incoming SMB before
 390         issuing them. It is possible to make the signal handlers safe
 391         by un-blocking the signals before the select call and re-blocking
 392         them after, however this would affect performance.</para>
 393 </refsect1>
 394
 395 <refsect1>
 396         <title>SEE ALSO</title>
 397         <para>hosts_access(5), <command>inetd(8)</command>,
 398         <ulink url="nmbd.8.html"><command>nmbd(8)</command></ulink>,
 399         <ulink url="smb.conf.5.html"><filename>smb.conf(5)</filename>
 400         </ulink>, <ulink url="smbclient.1.html"><command>smbclient(1)
 401         </command></ulink>, <ulink url="testparm.1.html"><command>
 402         testparm(1)</command></ulink>, <ulink url="testprns.1.html">
 403         <command>testprns(1)</command></ulink>, and the Internet RFC's
 404         <filename>rfc1001.txt</filename>, <filename>rfc1002.txt</filename>.
 405         In addition the CIFS (formerly SMB) specification is available
 406         as a link from the Web page <ulink url="http://samba.org/cifs/">
 407         http://samba.org/cifs/</ulink>.</para>
 408 </refsect1>
 409
 410 <refsect1>
 411         <title>AUTHOR</title>
 412
 413         <para>The original Samba software and related utilities
 414         were created by Andrew Tridgell. Samba is now developed
 415         by the Samba Team as an Open Source project similar
 416         to the way the Linux kernel is developed.</para>
 417
 418         <para>The original Samba man pages were written by Karl Auer.
 419         The man page sources were converted to YODL format (another
 420         excellent piece of Open Source software, available at
 421         <ulink url="ftp://ftp.icce.rug.nl/pub/unix/">
 422         ftp://ftp.icce.rug.nl/pub/unix/</ulink>) and updated for the Samba 2.0
 423         release by Jeremy Allison.  The conversion to DocBook for
 424         Samba 2.2 was done by Gerald Carter</para>
 425 </refsect1>
 426
 427 </refentry>