docs/manpages/smbd.8

   1 .TH SMBD 8 "08 Jan 1998" "smbd 1.9.18"
   2 .SH NAME
   3 smbd \- provide SMB (aka LanManager) services to clients
   4 .SH SYNOPSIS
   5 .B smbd
   6 [
   7 .B \-D
   8 ] [
   9 .B \-a
  10 ] [
  11 .B \-o
  12 ] [
  13 .B \-d
  14 .I debuglevel
  15 ] [
  16 .B \-l
  17 .I log file
  18 ] [
  19 .B \-p
  20 .I port number
  21 ] [
  22 .B \-O
  23 .I socket options
  24 ] [
  25 .B \-s
  26 .I configuration file
  27 ]
  28 .SH DESCRIPTION
  29 This program is part of the Samba suite.
  30
  31 .B smbd
  32 is a server that can provide most SMB services. The server provides
  33 filespace and printer services to clients using the SMB protocol. This
  34 is compatible with the LanManager protocol, and can service LanManager
  35 clients.  These include MSCLIENT 3.0 for DOS, Windows for Workgroups,
  36 Windows 95, Windows NT, OS/2, DAVE for Macintosh, and smbfs for Linux.
  37
  38 An extensive description of the services that the server can provide is given
  39 in the man page for the configuration file controlling the attributes of those
  40 services (see
  41 .BR smb.conf (5)).
  42 This man page will not describe the services, but
  43 will concentrate on the administrative aspects of running the server.
  44
  45 Please note that there are significant security implications to running this
  46 server, and
  47 .BR smb.conf (5)
  48 should be regarded as mandatory reading before proceeding with
  49 installation.
  50
  51 A session is created whenever a client requests one. Each client gets a copy
  52 of the server for each session. This copy then services all connections made
  53 by the client during that session. When all connections from its client are
  54 are closed, the copy of the server for that client terminates.
  55
  56 The configuration file, and any files that it includes, are automatically
  57 reloaded every minute, if they change.  You can force a reload by sending a
  58 SIGHUP to the server.  Reloading the configuration file will not affect
  59 connections to any service that is already established.  Either the user
  60 will have to disconnect from the service, or smbd killed and restarted.
  61 .SH OPTIONS
  62 .B \-D
  63
  64 .RS 3
  65 If specified, this parameter causes the server to operate as a daemon. That is,
  66 it detaches itself and runs in the background, fielding requests on the
  67 appropriate port.
  68
  69 By default, the server will NOT operate as a daemon.
  70 .RE
  71
  72 .B \-a
  73
  74 .RS 3
  75 If this parameter is specified, each new connection will append log messages
  76 to the log file.  This is the default.
  77 .RE
  78
  79 .B \-o
  80
  81 .RS 3
  82 If this parameter is specified, the log files will be overwritten when opened.
  83 By default, the log files will be appended to.
  84 .RE
  85
  86 .B \-d
  87 .I debuglevel
  88 .RS 3
  89
  90 debuglevel is an integer from 0 to 10.
  91
  92 The default value if this parameter is not specified is zero.
  93
  94 The higher this value, the more detail will be logged to the log files about
  95 the activities of the server. At level 0, only critical errors and serious
  96 warnings will be logged. Level 1 is a reasonable level for day to day running
  97 - it generates a small amount of information about operations carried out.
  98
  99 Levels above 1 will generate considerable amounts of log data, and should
 100 only be used when investigating a problem. Levels above 3 are designed for
 101 use only by developers and generate HUGE amounts of log data, most of which
 102 is extremely cryptic.
 103 .RE
 104
 105 .B \-l
 106 .I log file
 107
 108 .RS 3
 109 If specified,
 110 .I logfile
 111 specifies a base filename into which operational data from the running server
 112 will be logged.
 113
 114 The default base name is specified at compile time.
 115
 116 The base name is used to generate actual log file names. For example, if the
 117 name specified was "log", the following files would be used for log data:
 118
 119 .RS 3
 120 log.debug (containing debugging information)
 121
 122 log.in (containing inbound transaction data)
 123
 124 log.out (containing outbound transaction data)
 125 .RE
 126
 127 The log files generated are never removed by the server.
 128 .RE
 129
 130 .B \-O
 131 .I socket options
 132 .RS 3
 133
 134 See the socket options section of
 135 .BR smb.conf (5)
 136 for details
 137
 138 .RE
 139 .B \-p
 140 .I port number
 141 .RS 3
 142
 143 port number is a positive integer value.
 144
 145 The default value if this parameter is not specified is 139.
 146
 147 This number is the port number that will be used when making connections to
 148 the server from client software. The standard (well-known) port number for the
 149 server is 139, hence the default. If you wish to run the server as an ordinary
 150 user rather than as root, most systems will require you to use a port number
 151 greater than 1024 - ask your system administrator for help if you are in this
 152 situation.
 153
 154 In order for the server to be useful by most clients, should you configure
 155 it on a port other than 139, you will require port redirection services
 156 on port 139, details of which are outlined in rfc1002.txt section 4.3.5.
 157
 158 This parameter is not normally specified except in the above situation.
 159 .RE
 160
 161 .B \-s
 162 .I configuration file
 163
 164 .RS 3
 165 The default configuration file name is determined at compile time.
 166
 167 The file specified contains the configuration details required by the server.
 168 The information in this file includes server-specific information such as
 169 what printcap file to use, as well as descriptions of all the services that the
 170 server is to provide. See
 171 .BR smb.conf (5)
 172 for more information.
 173 .RE
 174 .SH FILES
 175
 176 .B /etc/inetd.conf
 177
 178 .RS 3
 179 If the server is to be run by the inetd meta-daemon, this file must contain
 180 suitable startup information for the meta-daemon. See the section
 181 "INSTALLATION" below.
 182 .RE
 183
 184 .B /etc/rc
 185
 186 .RS 3
 187 (or whatever initialisation script your system uses)
 188
 189 If running the server as a daemon at startup, this file will need to contain
 190 an appropriate startup sequence for the server. See the section "INSTALLATION"
 191 below.
 192 .RE
 193
 194 .B /etc/services
 195
 196 .RS 3
 197 If running the server via the meta-daemon inetd, this file must contain a
 198 mapping of service name (eg., netbios-ssn)  to service port (eg., 139) and
 199 protocol type (eg., tcp). See the section "INSTALLATION" below.
 200 .RE
 201
 202 .B /usr/local/samba/lib/smb.conf
 203
 204 .RS 3
 205 This file describes all the services the server is to make available to
 206 clients. See
 207 .BR smb.conf (5)
 208 for more information.
 209 .RE
 210 .SH LIMITATIONS
 211
 212 On some systems
 213 .B smbd
 214 cannot change uid back to root after a setuid() call.
 215 Such systems are called "trapdoor" uid systems. If you have such a system,
 216 you will be unable to connect from a client (such as a PC) as two different
 217 users at once. Attempts to connect the second user will result in "access
 218 denied" or similar.
 219 .SH ENVIRONMENT VARIABLES
 220
 221 .B PRINTER
 222
 223 .RS 3
 224 If no printer name is specified to printable services, most systems will
 225 use the value of this variable (or "lp" if this variable is not defined)
 226 as the name of the printer to use. This is not specific to the server,
 227 however.
 228 .RE
 229 .SH INSTALLATION
 230 The location of the server and its support files is a matter for individual
 231 system administrators. The following are thus suggestions only.
 232
 233 It is recommended that the server software be installed under the
 234 /usr/local/samba hierarchy, in a directory readable by all, writeable only
 235 by root. The server program itself should be executable by all, as
 236 users may wish to run the server themselves (in which case it will of
 237 course run with their privileges).  The server should NOT be
 238 setuid. On some systems it may be worthwhile to make smbd setgid to an
 239 empty group. This is because some systems may have a security hole where
 240 daemon processes that become a user can be attached to with a
 241 debugger. Making the smbd file setgid to an empty group may prevent
 242 this hole from being exploited. This security hole and the suggested
 243 fix has only been confirmed on Linux at the time this was written. It
 244 is possible that this hole only exists in Linux, as testing on other
 245 systems has thus far shown them to be immune.
 246
 247 The server log files should be put in a directory readable and writable only
 248 by root, as the log files may contain sensitive information.
 249
 250 The configuration file should be placed in a directory readable and writable
 251 only by root, as the configuration file controls security for the services
 252 offered by the server. The configuration file can be made readable by all if
 253 desired, but this is not necessary for correct operation of the server and
 254 is not recommended. A sample configuration file "smb.conf.sample" is supplied
 255 with the source to the server - this may be renamed to "smb.conf" and
 256 modified to suit your needs.
 257
 258 The remaining notes will assume the following:
 259
 260 .RS 3
 261 .B smbd
 262 (the server program) installed in /usr/local/samba/bin
 263
 264 smb.conf (the configuration file) installed in /usr/local/samba/lib
 265
 266 log files stored in /var/adm/smblogs
 267 .RE
 268
 269 The server may be run either as a daemon by users or at startup, or it may
 270 be run from a meta-daemon such as inetd upon request. If run as a daemon, the
 271 server will always be ready, so starting sessions will be faster. If run from
 272 a meta-daemon some memory will be saved and utilities such as the tcpd
 273 TCP-wrapper may be used for extra security.
 274
 275 When you've decided, continue with either "RUNNING THE SERVER AS A DAEMON" or
 276 "RUNNING THE SERVER ON REQUEST".
 277 .SH RUNNING THE SERVER AS A DAEMON
 278 To run the server as a daemon from the command line, simply put the
 279 .B \-D
 280 option
 281 on the command line. There is no need to place an ampersand at the end of the
 282 command line - the
 283 .B \-D
 284 option causes the server to detach itself from the
 285 tty anyway.
 286
 287 Any user can run the server as a daemon (execute permissions permitting, of
 288 course). This is useful for testing purposes, and may even be useful as a
 289 temporary substitute for something like ftp. When run this way, however, the
 290 server will only have the privileges of the user who ran it.
 291
 292 To ensure that the server is run as a daemon whenever the machine is started,
 293 and to ensure that it runs as root so that it can serve multiple clients, you
 294 will need to modify the system startup files. Wherever appropriate (for
 295 example, in /etc/rc), insert the following line, substituting
 296 port number, log file location, configuration file location and debug level as
 297 desired:
 298
 299 .RS 3
 300 /usr/local/samba/bin/smbd -D -l /var/adm/smblogs/log -s /usr/local/samba/lib/smb.conf
 301 .RE
 302
 303 (The above should appear in your initialisation script as a single line.
 304 Depending on your terminal characteristics, it may not appear that way in
 305 this man page. If the above appears as more than one line, please treat any
 306 newlines or indentation as a single space or TAB character.)
 307
 308 If the options used at compile time are appropriate for your system, all
 309 parameters except the desired debug level and
 310 .B \-D
 311 may be omitted. See the
 312 section "OPTIONS" above.
 313 .SH RUNNING THE SERVER ON REQUEST
 314 If your system uses a meta-daemon such as inetd, you can arrange to have the
 315 smbd server started whenever a process attempts to connect to it. This requires
 316 several changes to the startup files on the host machine. If you are
 317 experimenting as an ordinary user rather than as root, you will need the
 318 assistance of your system administrator to modify the system files.
 319
 320 You will probably want to set up the name server
 321 .B nmbd
 322 at the same time as
 323 .B smbd
 324 - refer to the man page
 325 .BR nmbd (8).
 326
 327 First, ensure that a port is configured in the file /etc/services. The
 328 well-known port 139 should be used if possible, though any port may be used.
 329
 330 Ensure that a line similar to the following is in /etc/services:
 331
 332 .RS 3
 333 netbios-ssn     139/tcp
 334 .RE
 335
 336 Note for NIS/YP users - you may need to rebuild the NIS service maps rather
 337 than alter your local /etc/services file.
 338
 339 Next, put a suitable line in the file /etc/inetd.conf (in the unlikely event
 340 that you are using a meta-daemon other than inetd, you are on your own). Note
 341 that the first item in this line matches the service name in /etc/services.
 342 Substitute appropriate values for your system in this line (see
 343 .BR inetd (8)):
 344
 345 .RS 3
 346 .\" turn off right adjustment
 347 .ad l
 348 netbios-ssn stream tcp nowait root /usr/local/samba/bin/smbd -d1
 349 -l/var/adm/smblogs/log -s/usr/local/samba/lib/smb.conf
 350 .ad
 351 .RE
 352
 353 (The above should appear in /etc/inetd.conf as a single line. Depending on
 354 your terminal characteristics, it may not appear that way in this man page.
 355 If the above appears as more than one line, please treat any newlines or
 356 indentation as a single space or TAB character.)
 357
 358 Note that there is no need to specify a port number here, even if you are
 359 using a non-standard port number.
 360
 361 Lastly, edit the configuration file to provide suitable services. To start
 362 with, the following two services should be all you need:
 363
 364 .RS 3
 365 [homes]
 366 .RS 3
 367  writable = yes
 368 .RE
 369
 370 [printers]
 371 .RS 3
 372  writable = no
 373  printable = yes
 374  path = /tmp
 375  public = yes
 376 .RE
 377 .RE
 378
 379 This will allow you to connect to your home directory and print to any printer
 380 supported by the host (user privileges permitting).
 381 .SH TESTING THE INSTALLATION
 382 If running the server as a daemon, execute it before proceeding. If
 383 using a meta-daemon, either restart the system or kill and restart the
 384 meta-daemon. Some versions of inetd will reread their configuration tables if
 385 they receive a HUP signal.
 386
 387 If your machine's name is "fred" and your name is "mary", you should now be
 388 able to connect to the service "\e\efred\emary".
 389
 390 To properly test and experiment with the server, we recommend using the
 391 smbclient program (see
 392 .BR smbclient (1)).
 393 .SH VERSION
 394 This man page is (mostly) correct for version 1.9.00 of the Samba suite,
 395 plus some of the recent patches to it. These notes will necessarily lag behind
 396 development of the software, so it is possible that your version of
 397 the server has extensions or parameter semantics that differ from or are not
 398 covered by this man page. Please notify these to the address below for
 399 rectification.
 400 .SH SEE ALSO
 401 .BR hosts_access (5),
 402 .BR inetd (8),
 403 .BR nmbd (8),
 404 .BR smb.conf (5),
 405 .BR smbclient (1),
 406 .BR testparm (1),
 407 .BR testprns (1)
 408 .BR rfc1001.txt
 409 .BR rfc1002.txt
 410 .SH DIAGNOSTICS
 411 [This section under construction]
 412
 413 Most diagnostics issued by the server are logged in a specified log file. The
 414 log file name is specified at compile time, but may be overridden on the
 415 command line.
 416
 417 The number and nature of diagnostics available depends on the debug level used
 418 by the server. If you have problems, set the debug level to 3 and peruse the
 419 log files.
 420
 421 Most messages are reasonably self-explanatory. Unfortunately, at time of
 422 creation of this man page the source code is still too fluid to warrant
 423 describing each and every diagnostic. At this stage your best bet is still
 424 to grep the source code and inspect the conditions that gave rise to the
 425 diagnostics you are seeing.
 426
 427 .SH SIGNALS
 428
 429 In version 1.9.18 and above the debug log level of smbd may be raised
 430 by sending it a SIGUSR1 (kill -USR1 <smbd-pid>) and lowered by sending
 431 it a SIGUSR2 (kill -USR2 <smbd-pid>). This is to allow transient problems
 432 to be diagnosed, whilst still running at a normally low log level.
 433
 434 Note that as the signal handlers send a debug write, they are not
 435 re-entrant in smbd. This you should wait until smbd is in a state of
 436 waiting for an incoming smb before issuing them. It is possible to
 437 make the signal handlers safe by un-blocking the signals before the
 438 select call and re-blocking them after, however this would affect
 439 performance.
 440
 441 .SH BUGS
 442 None known.
 443 .SH CREDITS
 444 The original Samba software and related utilities were created by
 445 Andrew Tridgell (samba-bugs@samba.anu.edu.au). Andrew is also the Keeper
 446 of the Source for this project.
 447
 448
 449 See
 450 .BR smb.conf (5)
 451 for a full list of contributors and details on how to
 452 submit bug reports, comments etc.