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