docs: Update doc to use absolute path for 'dedicated keytab file'
[sfrench/samba-autobuild/.git] / docs-xml / manpages / smbd.8.xml
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
3 <refentry id="smbd.8">
4
5 <refmeta>
6         <refentrytitle>smbd</refentrytitle>
7         <manvolnum>8</manvolnum>
8         <refmiscinfo class="source">Samba</refmiscinfo>
9         <refmiscinfo class="manual">System Administration tools</refmiscinfo>
10         <refmiscinfo class="version">4.6</refmiscinfo>
11 </refmeta>
12
13
14 <refnamediv>
15         <refname>smbd</refname>
16         <refpurpose>server to provide SMB/CIFS services to clients</refpurpose>
17 </refnamediv>
18
19 <refsynopsisdiv>
20         <cmdsynopsis>
21                 <command>smbd</command>
22                 <arg choice="opt">-D|--daemon</arg>
23                 <arg choice="opt">-F|--foreground</arg>
24                 <arg choice="opt">-S|--log-stdout</arg>
25                 <arg choice="opt">-i|--interactive</arg>
26                 <arg choice="opt">-V</arg>
27                 <arg choice="opt">-b|--build-options</arg>
28                 <arg choice="opt">-d &lt;debug level&gt;</arg>
29                 <arg choice="opt">-l|--log-basename &lt;log directory&gt;</arg>
30                 <arg choice="opt">-p &lt;port number(s)&gt;</arg>
31                 <arg choice="opt">-P &lt;profiling level&gt;</arg>
32                 <arg choice="opt">-s &lt;configuration file&gt;</arg>
33                 <arg choice="opt">--no-process-group</arg>
34         </cmdsynopsis>
35 </refsynopsisdiv>
36
37 <refsect1>
38         <title>DESCRIPTION</title>
39         <para>This program is part of the <citerefentry><refentrytitle>samba</refentrytitle>
40         <manvolnum>7</manvolnum></citerefentry> suite.</para>
41
42         <para><command>smbd</command> is the server daemon that 
43         provides filesharing and printing services to Windows clients. 
44         The server provides filespace and printer services to
45         clients using the SMB (or CIFS) protocol. This is compatible 
46         with the LanManager protocol, and can service LanManager 
47         clients.  These include MSCLIENT 3.0 for DOS, Windows for 
48         Workgroups, Windows 95/98/ME, Windows NT, Windows 2000, 
49         OS/2, DAVE for Macintosh, and smbfs for Linux.</para>
50
51         <para>An extensive description of the services that the 
52         server can provide is given in the man page for the 
53         configuration file controlling the attributes of those 
54         services (see <citerefentry><refentrytitle>smb.conf</refentrytitle>
55         <manvolnum>5</manvolnum></citerefentry>.  This man page will not describe the 
56         services, but will concentrate on the administrative aspects 
57         of running the server.</para>
58
59         <para>Please note that there are significant security 
60         implications to running this server, and the <citerefentry><refentrytitle>smb.conf</refentrytitle>
61         <manvolnum>5</manvolnum></citerefentry> manual page should be regarded as mandatory reading before 
62         proceeding with installation.</para>
63
64         <para>A session is created whenever a client requests one. 
65         Each client gets a copy of the server for each session. This 
66         copy then services all connections made by the client during 
67         that session. When all connections from its client are closed, 
68         the copy of the server for that client terminates.</para>
69
70         <para>The configuration file, and any files that it includes, 
71         are automatically reloaded every minute, if they change.  You 
72         can force a reload by sending a SIGHUP to the server.  Reloading 
73         the configuration file will not affect connections to any service 
74         that is already established.  Either the user will have to 
75         disconnect from the service, or <command>smbd</command> killed and restarted.</para>
76 </refsect1>
77
78 <refsect1>
79         <title>OPTIONS</title>
80
81         <variablelist>
82                 <varlistentry>
83                 <term>-D|--daemon</term>
84                 <listitem><para>If specified, this parameter causes 
85                 the server to operate as a daemon. That is, it detaches 
86                 itself and runs in the background, fielding requests 
87                 on the appropriate port. Operating the server as a
88                 daemon is the recommended way of running <command>smbd</command> for 
89                 servers that provide more than casual use file and 
90                 print services.  This switch is assumed if <command>smbd
91                 </command> is executed on the command line of a shell.
92                 </para></listitem>
93                 </varlistentry>
94
95                 <varlistentry>
96                 <term>-F|--foreground</term>
97                 <listitem><para>If specified, this parameter causes
98                 the main <command>smbd</command> process to not daemonize,
99                 i.e. double-fork and disassociate with the terminal.
100                 Child processes are still created as normal to service
101                 each connection request, but the main process does not
102                 exit. This operation mode is suitable for running
103                 <command>smbd</command> under process supervisors such
104                 as <command>supervise</command> and <command>svscan</command>
105                 from Daniel J. Bernstein's <command>daemontools</command>
106                 package, or the AIX process monitor.
107                 </para></listitem>
108                 </varlistentry>
109
110                 <varlistentry>
111                 <term>-S|--log-stdout</term>
112                 <listitem><para>If specified, this parameter causes
113                 <command>smbd</command> to log to standard output rather
114                 than a file.</para></listitem>
115                 </varlistentry>
116
117                 <varlistentry>
118                 <term>-i|--interactive</term>
119                 <listitem><para>If this parameter is specified it causes the
120                 server to run "interactively", not as a daemon, even if the
121                 server is executed on the command line of a shell. Setting this
122                 parameter negates the implicit daemon mode when run from the
123                 command line. <command>smbd</command> will only accept one
124                 connection and terminate. It will also log to standard output,
125                 as if the <command>-S</command> parameter had been given.
126                 </para></listitem>
127                 </varlistentry>
128
129                 &stdarg.server.debug;
130                 &popt.common.samba;
131                 &popt.autohelp;
132
133                 <varlistentry>
134                 <term>--no-process-group</term>
135                 <listitem><para>Do not create a new process group for smbd.
136                 </para></listitem>
137                 </varlistentry>
138
139                 <varlistentry>
140                 <term>-b|--build-options</term>
141                 <listitem><para>Prints information about how 
142                 Samba was built.</para></listitem>
143                 </varlistentry>
144                 
145                 <varlistentry>
146                 <term>-p|--port&lt;port number(s)&gt;</term>
147                 <listitem><para><replaceable>port number(s)</replaceable> is a 
148                 space or comma-separated list of TCP ports smbd should listen on.
149                 The default value is taken from the <smbconfoption name="ports"/> parameter in &smb.conf;</para>
150
151                 <para>The default ports are 139 (used for SMB over NetBIOS over TCP)
152                         and port 445 (used for plain SMB over TCP).
153                 </para></listitem>
154                 </varlistentry>
155                 
156                 <varlistentry>
157                 <term>-P|--profiling-level&lt;profiling level&gt;</term>
158                 <listitem><para><replaceable>profiling level</replaceable> is a
159                 number specifying the level of profiling data to be collected.
160                 0 turns off profiling, 1 turns on counter profiling only,
161                 2 turns on complete profiling, and 3 resets all profiling data.
162                 </para></listitem>
163                 </varlistentry>
164         </variablelist>
165 </refsect1>
166
167 <refsect1>
168         <title>FILES</title>
169
170         <variablelist>
171                 <varlistentry>
172                 <term><filename>/etc/inetd.conf</filename></term>
173                 <listitem><para>If the server is to be run by the 
174                 <command>inetd</command> meta-daemon, this file 
175                 must contain suitable startup information for the 
176                 meta-daemon. 
177                 </para></listitem>
178                 </varlistentry>
179                 
180                 <varlistentry>
181                 <term><filename>/etc/rc</filename></term>
182                 <listitem><para>or whatever initialization script your 
183                 system uses).</para>
184
185                 <para>If running the server as a daemon at startup, 
186                 this file will need to contain an appropriate startup 
187                 sequence for the server. </para></listitem>
188                 </varlistentry>
189                 
190                 <varlistentry>
191                 <term><filename>/etc/services</filename></term>
192                 <listitem><para>If running the server via the 
193                 meta-daemon <command>inetd</command>, this file 
194                 must contain a mapping of service name (e.g., netbios-ssn) 
195                 to service port (e.g., 139) and protocol type (e.g., tcp). 
196                 </para></listitem>
197                 </varlistentry>
198                 
199                 <varlistentry>
200                 <term><filename>/usr/local/samba/lib/smb.conf</filename></term>
201                 <listitem><para>This is the default location of the <citerefentry><refentrytitle>smb.conf</refentrytitle>
202                 <manvolnum>5</manvolnum></citerefentry> server configuration file. Other common places that systems 
203                 install this file are <filename>/usr/samba/lib/smb.conf</filename> 
204                 and <filename>/etc/samba/smb.conf</filename>.</para>
205                 
206                 <para>This file describes all the services the server 
207                 is to make available to clients. See <citerefentry><refentrytitle>smb.conf</refentrytitle>
208                 <manvolnum>5</manvolnum></citerefentry> for more information.</para>
209                 </listitem>
210                 </varlistentry>
211         </variablelist>
212 </refsect1>
213
214 <refsect1>
215         <title>LIMITATIONS</title>
216         <para>On some systems <command>smbd</command> cannot change uid back 
217         to root after a setuid() call.  Such systems are called 
218         trapdoor uid systems. If you have such a system, 
219         you will be unable to connect from a client (such as a PC) as 
220         two different users at once. Attempts to connect the
221         second user will result in access denied or 
222         similar.</para>
223 </refsect1>
224
225 <refsect1>
226         <title>ENVIRONMENT VARIABLES</title>
227
228         <variablelist>
229                 <varlistentry>
230                 <term><envar>PRINTER</envar></term>
231                 <listitem><para>If no printer name is specified to 
232                 printable services, most systems will use the value of 
233                 this variable (or <constant>lp</constant> if this variable is 
234                 not defined) as the name of the printer to use. This 
235                 is not specific to the server, however.</para></listitem>
236                 </varlistentry>
237         </variablelist>
238 </refsect1>
239
240
241 <refsect1>
242         <title>PAM INTERACTION</title>
243         <para>Samba uses PAM for authentication (when presented with a plaintext 
244         password), for account checking (is this account disabled?) and for
245         session management.  The degree too which samba supports PAM is restricted
246         by the limitations of the SMB protocol and the <smbconfoption name="obey pam restrictions"/> <citerefentry><refentrytitle>smb.conf</refentrytitle>
247         <manvolnum>5</manvolnum></citerefentry> parameter.  When this is set, the following restrictions apply:
248         </para>
249
250         <itemizedlist>
251         <listitem><para><emphasis>Account Validation</emphasis>:  All accesses to a 
252         samba server are checked 
253         against PAM to see if the account is valid, not disabled and is permitted to
254         login at this time.  This also applies to encrypted logins.
255         </para></listitem>
256
257         <listitem><para><emphasis>Session Management</emphasis>:  When not using share 
258         level security, users must pass PAM's session checks before access
259         is granted.  Note however, that this is bypassed in share level security.
260         Note also that some older pam configuration files may need a line 
261         added for session support. 
262         </para></listitem>
263         </itemizedlist>
264 </refsect1>
265
266 <refsect1>
267         <title>VERSION</title>
268
269         <para>This man page is correct for version 3 of 
270         the Samba suite.</para>
271 </refsect1>
272
273 <refsect1>
274         <title>DIAGNOSTICS</title>
275
276         <para>Most diagnostics issued by the server are logged 
277         in a specified log file. The log file name is specified 
278         at compile time, but may be overridden on the command line.</para>
279
280         <para>The number and nature of diagnostics available depends 
281         on the debug level used by the server. If you have problems, set 
282         the debug level to 3 and peruse the log files.</para>
283
284         <para>Most messages are reasonably self-explanatory. Unfortunately, 
285         at the time this man page was created, there are too many diagnostics 
286         available in the source code to warrant describing each and every 
287         diagnostic. At this stage your best bet is still to grep the 
288         source code and inspect the conditions that gave rise to the 
289         diagnostics you are seeing.</para>
290 </refsect1>
291
292 <refsect1>
293         <title>TDB FILES</title>
294
295         <para>Samba stores it's data in several TDB (Trivial Database) files, usually located in <filename>/var/lib/samba</filename>.</para>
296         
297         <para>
298         (*) information persistent across restarts (but not
299         necessarily important to backup).
300         </para>
301
302 <variablelist>
303 <varlistentry><term>account_policy.tdb*</term>
304 <listitem>
305 <para>NT account policy settings such as pw expiration, etc...</para>
306 </listitem>
307 </varlistentry>
308
309 <varlistentry><term>brlock.tdb</term>
310 <listitem><para>byte range locks</para></listitem>
311 </varlistentry>
312
313 <varlistentry><term>browse.dat</term>
314 <listitem><para>browse lists</para></listitem>
315 </varlistentry>
316
317 <varlistentry><term>gencache.tdb</term>
318 <listitem><para>generic caching db</para></listitem>
319 </varlistentry>
320
321 <varlistentry><term>group_mapping.tdb*</term>
322 <listitem><para>group mapping information</para></listitem>
323 </varlistentry>
324
325 <varlistentry><term>locking.tdb</term>
326 <listitem><para>share modes &amp; oplocks</para></listitem>
327 </varlistentry>
328
329 <varlistentry><term>login_cache.tdb*</term>
330 <listitem><para>bad pw attempts</para></listitem>
331 </varlistentry>
332
333 <varlistentry><term>messages.tdb</term>
334 <listitem><para>Samba messaging system</para></listitem>
335 </varlistentry>
336
337 <varlistentry><term>netsamlogon_cache.tdb*</term>
338 <listitem><para>cache of user net_info_3 struct from net_samlogon() request (as a domain member)</para></listitem>
339 </varlistentry>
340
341 <varlistentry><term>ntdrivers.tdb*</term>
342 <listitem><para>installed printer drivers</para></listitem>
343 </varlistentry>
344
345 <varlistentry><term>ntforms.tdb*</term>
346 <listitem><para>installed printer forms</para></listitem>
347 </varlistentry>
348
349 <varlistentry><term>ntprinters.tdb*</term>
350 <listitem><para>installed printer information</para></listitem>
351 </varlistentry>
352
353 <varlistentry><term>printing/</term>
354 <listitem><para>directory containing tdb per print queue of cached lpq output</para></listitem>
355 </varlistentry>
356
357 <varlistentry><term>registry.tdb</term>
358 <listitem><para>Windows registry skeleton (connect via regedit.exe)</para></listitem>
359 </varlistentry>
360
361 <varlistentry><term>smbXsrv_session_global.tdb</term>
362 <listitem><para>session information (e.g. support for 'utmp = yes')</para></listitem>
363 </varlistentry>
364
365 <varlistentry><term>smbXsrv_tcon_global.tdb</term>
366 <listitem><para>share connections (used to enforce max connections, etc...)</para></listitem>
367 </varlistentry>
368
369 <varlistentry><term>smbXsrv_open_global.tdb</term>
370 <listitem><para>open file handles (used durable handles, etc...)</para></listitem>
371 </varlistentry>
372
373 <varlistentry><term>share_info.tdb*</term>
374 <listitem><para>share acls</para></listitem>
375 </varlistentry>
376
377 <varlistentry><term>winbindd_cache.tdb</term>
378 <listitem><para>winbindd's cache of user lists, etc...</para></listitem>
379 </varlistentry>
380
381 <varlistentry><term>winbindd_idmap.tdb*</term>
382 <listitem><para>winbindd's local idmap db</para></listitem>
383 </varlistentry>
384
385 <varlistentry><term>wins.dat*</term>
386 <listitem><para>wins database when 'wins support = yes'</para></listitem>
387 </varlistentry>
388
389 </variablelist>
390
391 </refsect1>
392
393 <refsect1>
394         <title>SIGNALS</title>
395
396         <para>Sending the <command>smbd</command> a SIGHUP will cause it to 
397         reload its <filename>smb.conf</filename> configuration 
398         file within a short period of time.</para>
399
400         <para>To shut down a user's <command>smbd</command> process it is recommended 
401         that <command>SIGKILL (-9)</command> <emphasis>NOT</emphasis> 
402         be used, except as a last resort, as this may leave the shared
403         memory area in an inconsistent state. The safe way to terminate 
404         an <command>smbd</command> is to send it a SIGTERM (-15) signal and wait for 
405         it to die on its own.</para>
406
407         <para>The debug log level of <command>smbd</command> may be raised
408         or lowered using <citerefentry><refentrytitle>smbcontrol</refentrytitle>
409         <manvolnum>1</manvolnum></citerefentry> program (SIGUSR[1|2] signals are no longer 
410         used since Samba 2.2). This is to allow transient problems to be diagnosed, 
411         whilst still running at a normally low log level.</para>
412
413         <para>Note that as the signal handlers send a debug write, 
414         they are not re-entrant in <command>smbd</command>. This you should wait until 
415         <command>smbd</command> is in a state of waiting for an incoming SMB before 
416         issuing them. It is possible to make the signal handlers safe 
417         by un-blocking the signals before the select call and re-blocking 
418         them after, however this would affect performance.</para>
419 </refsect1>
420
421 <refsect1>
422         <title>SEE ALSO</title>
423         <para><citerefentry><refentrytitle>hosts_access</refentrytitle>
424         <manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>inetd</refentrytitle>
425         <manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>nmbd</refentrytitle>
426         <manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>smb.conf</refentrytitle>
427         <manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>smbclient</refentrytitle>
428         <manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>testparm</refentrytitle>
429         <manvolnum>1</manvolnum></citerefentry>, and the 
430         Internet RFC's  <filename>rfc1001.txt</filename>, <filename>rfc1002.txt</filename>. 
431         In addition the CIFS (formerly SMB) specification is available 
432         as a link from the Web page <ulink noescape="1" url="https://www.samba.org/cifs/">
433         https://www.samba.org/cifs/</ulink>.</para>
434 </refsect1>
435
436 <refsect1>
437         <title>AUTHOR</title>
438         
439         <para>The original Samba software and related utilities 
440         were created by Andrew Tridgell. Samba is now developed
441         by the Samba Team as an Open Source project similar 
442         to the way the Linux kernel is developed.</para>
443         
444         <para>The original Samba man pages were written by Karl Auer. 
445         The man page sources were converted to YODL format (another 
446         excellent piece of Open Source software, available at <ulink url="ftp://ftp.icce.rug.nl/pub/unix/">
447         ftp://ftp.icce.rug.nl/pub/unix/</ulink>) and updated for the Samba 2.0 
448         release by Jeremy Allison.  The conversion to DocBook for 
449         Samba 2.2 was done by Gerald Carter. The conversion to DocBook XML 4.2 for
450         Samba 3.0 was done by Alexander Bokovoy.</para>
451 </refsect1>
452
453 </refentry>