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