source: vendor/3.6.0/docs-xml/manpages-3/smb.conf.5.xml

Last change on this file was 740, checked in by Silvan Scherrer, 13 years ago

Samba Server: update vendor to 3.6.0
File size: 34.5 KB
Line 
1<refentry id="smb.conf.5" xmlns:xi="http://www.w3.org/2003/XInclude"
2 xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
3
4<refmeta>
5 <refentrytitle>smb.conf</refentrytitle>
6 <manvolnum>5</manvolnum>
7 <refmiscinfo class="source">Samba</refmiscinfo>
8 <refmiscinfo class="manual">File Formats and Conventions</refmiscinfo>
9 <refmiscinfo class="version">3.6</refmiscinfo>
10</refmeta>
11
12
13<refnamediv>
14 <refname>smb.conf</refname>
15 <refpurpose>The configuration file for the Samba suite</refpurpose>
16</refnamediv>
17
18<refsect1>
19 <title>SYNOPSIS</title>
20
21 <para>
22 The <filename moreinfo="none">smb.conf</filename> file is a configuration file for the Samba suite. <filename
23 moreinfo="none">smb.conf</filename> contains runtime configuration information for the Samba programs. The
24 <filename moreinfo="none">smb.conf</filename> file is designed to be configured and administered by the
25 <citerefentry><refentrytitle>swat</refentrytitle> <manvolnum>8</manvolnum></citerefentry> program. The
26 complete description of the file format and possible parameters held within are here for reference purposes.
27 </para>
28</refsect1>
29
30<refsect1 id="FILEFORMATSECT">
31 <title>FILE FORMAT</title>
32
33 <para>
34 The file consists of sections and parameters. A section begins with the name of the section in square brackets
35 and continues until the next section begins. Sections contain parameters of the form:
36<programlisting>
37<replaceable>name</replaceable> = <replaceable>value </replaceable>
38</programlisting>
39 </para>
40
41 <para>
42 The file is line-based - that is, each newline-terminated line represents either a comment, a section name or
43 a parameter.
44 </para>
45
46 <para>Section and parameter names are not case sensitive.</para>
47
48 <para>
49 Only the first equals sign in a parameter is significant. Whitespace before or after the first equals sign is
50 discarded. Leading, trailing and internal whitespace in section and parameter names is irrelevant. Leading
51 and trailing whitespace in a parameter value is discarded. Internal whitespace within a parameter value is
52 retained verbatim.
53 </para>
54
55 <para>
56 Any line beginning with a semicolon (<quote>;</quote>) or a hash (<quote>#</quote>)
57 character is ignored, as are lines containing only whitespace.
58 </para>
59
60 <para>
61 Any line ending in a <quote><literal>\</literal></quote> is continued on the next line in the customary UNIX fashion.
62 </para>
63
64 <para>
65 The values following the equals sign in parameters are all either a string (no quotes needed) or a boolean,
66 which may be given as yes/no, 1/0 or true/false. Case is not significant in boolean values, but is preserved
67 in string values. Some items such as create masks are numeric.
68 </para>
69
70</refsect1>
71
72<refsect1>
73 <title>SECTION DESCRIPTIONS</title>
74
75 <para>
76 Each section in the configuration file (except for the [global] section) describes a shared resource (known as
77 a <quote>share</quote>). The section name is the name of the shared resource and the parameters within the
78 section define the shares attributes.
79 </para>
80
81 <para>
82 There are three special sections, [global], [homes] and [printers], which are described under
83 <emphasis>special sections</emphasis>. The following notes apply to ordinary section descriptions.
84 </para>
85
86 <para>
87 A share consists of a directory to which access is being given plus a description of the access rights
88 which are granted to the user of the service. Some housekeeping options are also specifiable.
89 </para>
90
91 <para>
92 Sections are either file share services (used by the client as an extension of their native file systems)
93 or printable services (used by the client to access print services on the host running the server).
94 </para>
95
96 <para>
97 Sections may be designated <emphasis>guest</emphasis> services, in which case no password is required to
98 access them. A specified UNIX <emphasis>guest account</emphasis> is used to define access privileges in this
99 case.
100 </para>
101
102 <para>
103 Sections other than guest services will require a password to access them. The client provides the
104 username. As older clients only provide passwords and not usernames, you may specify a list of usernames to
105 check against the password using the <literal>user =</literal> option in the share definition. For modern clients
106 such as Windows 95/98/ME/NT/2000, this should not be necessary.
107 </para>
108
109 <para>
110 The access rights granted by the server are masked by the access rights granted to the specified or guest
111 UNIX user by the host system. The server does not grant more access than the host system grants.
112 </para>
113
114 <para>
115 The following sample section defines a file space share. The user has write access to the path <filename
116 moreinfo="none">/home/bar</filename>. The share is accessed via the share name <literal>foo</literal>:
117<programlisting>
118 <smbconfsection name="[foo]"/>
119 <smbconfoption name="path">/home/bar</smbconfoption>
120 <smbconfoption name="read only">no</smbconfoption>
121</programlisting>
122 </para>
123
124 <para>
125 The following sample section defines a printable share. The share is read-only, but printable. That is,
126 the only write access permitted is via calls to open, write to and close a spool file. The <emphasis>guest
127 ok</emphasis> parameter means access will be permitted as the default guest user (specified elsewhere):
128<programlisting>
129 <smbconfsection name="[aprinter]"/>
130 <smbconfoption name="path">/usr/spool/public</smbconfoption>
131 <smbconfoption name="read only">yes</smbconfoption>
132 <smbconfoption name="printable">yes</smbconfoption>
133 <smbconfoption name="guest ok">yes</smbconfoption>
134</programlisting>
135 </para>
136
137</refsect1>
138
139<refsect1>
140 <title>SPECIAL SECTIONS</title>
141
142 <refsect2>
143 <title>The [global] section</title>
144
145 <para>
146 Parameters in this section apply to the server as a whole, or are defaults for sections that do not
147 specifically define certain items. See the notes under PARAMETERS for more information.
148 </para>
149 </refsect2>
150
151 <refsect2 id="HOMESECT">
152 <title>The [homes] section</title>
153
154 <para>
155 If a section called [homes] is included in the configuration file, services connecting clients
156 to their home directories can be created on the fly by the server.
157 </para>
158
159 <para>
160 When the connection request is made, the existing sections are scanned. If a match is found, it is
161 used. If no match is found, the requested section name is treated as a username and looked up in the local
162 password file. If the name exists and the correct password has been given, a share is created by cloning the
163 [homes] section.
164 </para>
165
166 <para>
167 Some modifications are then made to the newly created share:
168 </para>
169
170 <itemizedlist>
171 <listitem><para>
172 The share name is changed from homes to the located username.
173 </para></listitem>
174
175 <listitem><para>
176 If no path was given, the path is set to the user's home directory.
177 </para></listitem>
178 </itemizedlist>
179
180 <para>
181 If you decide to use a <emphasis>path =</emphasis> line in your [homes] section, it may be useful
182 to use the %S macro. For example:
183<programlisting>
184<userinput moreinfo="none">path = /data/pchome/%S</userinput>
185</programlisting>
186 is useful if you have different home directories for your PCs than for UNIX access.
187 </para>
188
189 <para>
190 This is a fast and simple way to give a large number of clients access to their home directories with a minimum
191 of fuss.
192 </para>
193
194 <para>
195 A similar process occurs if the requested section name is <quote>homes</quote>, except that the share
196 name is not changed to that of the requesting user. This method of using the [homes] section works well if
197 different users share a client PC.
198 </para>
199
200 <para>
201 The [homes] section can specify all the parameters a normal service section can specify, though some make more sense
202 than others. The following is a typical and suitable [homes] section:
203<programlisting>
204<smbconfsection name="[homes]"/>
205<smbconfoption name="read only">no</smbconfoption>
206</programlisting>
207 </para>
208
209 <para>
210 An important point is that if guest access is specified in the [homes] section, all home directories will be
211 visible to all clients <emphasis>without a password</emphasis>. In the very unlikely event that this is actually
212 desirable, it is wise to also specify <emphasis>read only access</emphasis>.
213 </para>
214
215 <para>
216 The <emphasis>browseable</emphasis> flag for auto home directories will be inherited from the global browseable
217 flag, not the [homes] browseable flag. This is useful as it means setting <emphasis>browseable = no</emphasis> in
218 the [homes] section will hide the [homes] share but make any auto home directories visible.
219 </para>
220 </refsect2>
221
222 <refsect2 id="PRINTERSSECT">
223 <title>The [printers] section</title>
224
225 <para>
226 This section works like [homes], but for printers.
227 </para>
228
229 <para>
230 If a [printers] section occurs in the configuration file, users are able to connect to any printer
231 specified in the local host's printcap file.
232 </para>
233
234 <para>
235 When a connection request is made, the existing sections are scanned. If a match is found, it is used.
236 If no match is found, but a [homes] section exists, it is used as described above. Otherwise, the requested
237 section name is treated as a printer name and the appropriate printcap file is scanned to see if the requested
238 section name is a valid printer share name. If a match is found, a new printer share is created by cloning the
239 [printers] section.
240 </para>
241
242 <para>
243 A few modifications are then made to the newly created share:
244 </para>
245
246 <itemizedlist>
247 <listitem><para>The share name is set to the located printer name</para></listitem>
248
249 <listitem><para>If no printer name was given, the printer name is set to the located printer name</para></listitem>
250
251 <listitem><para>If the share does not permit guest access and no username was given, the username is set
252 to the located printer name.</para></listitem>
253 </itemizedlist>
254
255 <para>
256 The [printers] service MUST be printable - if you specify otherwise, the server will refuse
257 to load the configuration file.
258 </para>
259
260 <para>
261 Typically the path specified is that of a world-writeable spool directory with the sticky bit set on
262 it. A typical [printers] entry looks like this:
263<programlisting>
264<smbconfsection name="[printers]"/>
265<smbconfoption name="path">/usr/spool/public</smbconfoption>
266<smbconfoption name="guest ok">yes</smbconfoption>
267<smbconfoption name="printable">yes</smbconfoption>
268</programlisting>
269 </para>
270
271 <para>
272 All aliases given for a printer in the printcap file are legitimate printer names as far as the server is concerned.
273 If your printing subsystem doesn't work like that, you will have to set up a pseudo-printcap. This is a file
274 consisting of one or more lines like this:
275<programlisting>
276alias|alias|alias|alias...
277</programlisting>
278 </para>
279
280 <para>
281 Each alias should be an acceptable printer name for your printing subsystem. In the [global] section,
282 specify the new file as your printcap. The server will only recognize names found in your pseudo-printcap,
283 which of course can contain whatever aliases you like. The same technique could be used simply to limit access
284 to a subset of your local printers.
285 </para>
286
287 <para>
288 An alias, by the way, is defined as any component of the first entry of a printcap record. Records are separated by newlines,
289 components (if there are more than one) are separated by vertical bar symbols (<literal>|</literal>).
290 </para>
291
292 <note><para>
293 On SYSV systems which use lpstat to determine what printers are defined on the system you may be able to use
294 <literal>printcap name = lpstat</literal> to automatically obtain a list of printers. See the
295 <literal>printcap name</literal> option for more details.
296 </para></note>
297 </refsect2>
298</refsect1>
299
300<refsect1>
301 <title>USERSHARES</title>
302
303 <para>Starting with Samba version 3.0.23 the capability for non-root users to add, modify, and delete
304 their own share definitions has been added. This capability is called <emphasis>usershares</emphasis> and
305 is controlled by a set of parameters in the [global] section of the smb.conf.
306 The relevant parameters are :
307 </para>
308
309 <variablelist>
310 <varlistentry>
311 <term>usershare allow guests</term>
312 <listitem><para>Controls if usershares can permit guest access.</para></listitem>
313 </varlistentry>
314
315 <varlistentry>
316 <term>usershare max shares</term>
317 <listitem><para>Maximum number of user defined shares allowed.</para></listitem>
318 </varlistentry>
319
320 <varlistentry>
321 <term>usershare owner only</term>
322 <listitem><para>If set only directories owned by the sharing user can be shared.</para></listitem>
323 </varlistentry>
324
325 <varlistentry>
326 <term>usershare path</term>
327 <listitem><para>Points to the directory containing the user defined share definitions.
328 The filesystem permissions on this directory control who can create user defined shares.</para></listitem>
329 </varlistentry>
330
331 <varlistentry>
332 <term>usershare prefix allow list</term>
333 <listitem><para>Comma-separated list of absolute pathnames restricting what directories
334 can be shared. Only directories below the pathnames in this list are permitted.</para></listitem>
335 </varlistentry>
336
337 <varlistentry>
338 <term>usershare prefix deny list</term>
339 <listitem><para>Comma-separated list of absolute pathnames restricting what directories
340 can be shared. Directories below the pathnames in this list are prohibited.</para></listitem>
341 </varlistentry>
342
343 <varlistentry>
344 <term>usershare template share</term>
345 <listitem><para>Names a pre-existing share used as a template for creating new usershares.
346 All other share parameters not specified in the user defined share definition
347 are copied from this named share.</para></listitem>
348 </varlistentry>
349 </variablelist>
350
351 <para>To allow members of the UNIX group <literal>foo</literal> to create user defined
352 shares, create the directory to contain the share definitions as follows:
353 </para>
354 <para>Become root:</para>
355<programlisting>
356mkdir /usr/local/samba/lib/usershares
357chgrp foo /usr/local/samba/lib/usershares
358chmod 1770 /usr/local/samba/lib/usershares
359</programlisting>
360<para>Then add the parameters
361
362<programlisting>
363 <smbconfoption name="usershare path">/usr/local/samba/lib/usershares</smbconfoption>
364 <smbconfoption name="usershare max shares">10</smbconfoption> # (or the desired number of shares)
365</programlisting>
366
367 to the global
368 section of your <filename>smb.conf</filename>. Members of the group foo may then manipulate the user defined shares
369 using the following commands.</para>
370
371 <variablelist>
372 <varlistentry>
373 <term>net usershare add sharename path [comment] [acl] [guest_ok=[y|n]]</term>
374 <listitem><para>To create or modify (overwrite) a user defined share.</para></listitem>
375 </varlistentry>
376
377 <varlistentry>
378 <term>net usershare delete sharename</term>
379 <listitem><para>To delete a user defined share.</para></listitem>
380 </varlistentry>
381
382 <varlistentry>
383 <term>net usershare list wildcard-sharename</term>
384 <listitem><para>To list user defined shares.</para></listitem>
385 </varlistentry>
386
387 <varlistentry>
388 <term>net usershare info wildcard-sharename</term>
389 <listitem><para>To print information about user defined shares.</para></listitem>
390 </varlistentry>
391 </variablelist>
392</refsect1>
393
394<refsect1>
395 <title>PARAMETERS</title>
396
397 <para>Parameters define the specific attributes of sections.</para>
398
399 <para>
400 Some parameters are specific to the [global] section (e.g., <emphasis>security</emphasis>). Some parameters
401 are usable in all sections (e.g., <emphasis>create mask</emphasis>). All others are permissible only in normal
402 sections. For the purposes of the following descriptions the [homes] and [printers] sections will be
403 considered normal. The letter <emphasis>G</emphasis> in parentheses indicates that a parameter is specific to
404 the [global] section. The letter <emphasis>S</emphasis> indicates that a parameter can be specified in a
405 service specific section. All <emphasis>S</emphasis> parameters can also be specified in the [global] section
406 - in which case they will define the default behavior for all services.
407 </para>
408
409 <para>
410 Parameters are arranged here in alphabetical order - this may not create best bedfellows, but at least you can
411 find them! Where there are synonyms, the preferred synonym is described, others refer to the preferred
412 synonym.
413 </para>
414</refsect1>
415
416<refsect1>
417 <title>VARIABLE SUBSTITUTIONS</title>
418
419 <para>
420 Many of the strings that are settable in the config file can take substitutions. For example the option
421 <quote>path = /tmp/%u</quote> is interpreted as <quote>path = /tmp/john</quote> if the user connected with the
422 username john.
423 </para>
424
425 <para>
426 These substitutions are mostly noted in the descriptions below, but there are some general substitutions
427 which apply whenever they might be relevant. These are:
428 </para>
429
430 <variablelist>
431 <varlistentry>
432 <term>%U</term>
433 <listitem><para>session username (the username that the client wanted, not
434 necessarily the same as the one they got).</para></listitem>
435 </varlistentry>
436
437 <varlistentry>
438 <term>%G</term>
439 <listitem><para>primary group name of %U.</para></listitem>
440 </varlistentry>
441
442 <varlistentry>
443 <term>%h</term>
444 <listitem><para>the Internet hostname that Samba is running on.</para></listitem>
445 </varlistentry>
446
447 <varlistentry>
448 <term>%m</term>
449 <listitem><para>the NetBIOS name of the client machine (very useful).</para>
450
451 <para>This parameter is not available when Samba listens on port 445, as clients no longer
452 send this information. If you use this macro in an include statement on a domain that has
453 a Samba domain controller be sure to set in the [global] section <parameter>smb ports =
454 139</parameter>. This will cause Samba to not listen on port 445 and will permit include
455 functionality to function as it did with Samba 2.x.
456 </para></listitem>
457
458 </varlistentry>
459
460 <varlistentry>
461 <term>%L</term>
462 <listitem><para>the NetBIOS name of the server. This allows you to change your config based on what
463 the client calls you. Your server can have a <quote>dual personality</quote>.
464 </para></listitem>
465 </varlistentry>
466
467 <varlistentry>
468 <term>%M</term>
469 <listitem><para>the Internet name of the client machine.
470 </para></listitem>
471 </varlistentry>
472
473 <varlistentry>
474 <term>%R</term>
475 <listitem><para>the selected protocol level after protocol negotiation. It can be one of CORE, COREPLUS,
476 LANMAN1, LANMAN2 or NT1.</para></listitem>
477 </varlistentry>
478
479 <varlistentry>
480 <term>%d</term>
481 <listitem><para>the process id of the current server
482 process.</para></listitem>
483 </varlistentry>
484
485 <varlistentry>
486 <term>%a</term>
487 <listitem><para>
488 The architecture of the remote
489 machine. It currently recognizes Samba (<constant>Samba</constant>),
490 the Linux CIFS file system (<constant>CIFSFS</constant>), OS/2, (<constant>OS2</constant>),
491 Mac OS X (<constant>OSX</constant>), Windows for Workgroups (<constant>WfWg</constant>), Windows 9x/ME
492 (<constant>Win95</constant>), Windows NT (<constant>WinNT</constant>),
493 Windows 2000 (<constant>Win2K</constant>),
494 Windows XP (<constant>WinXP</constant>),
495 Windows XP 64-bit(<constant>WinXP64</constant>),
496 Windows 2003 including
497 2003R2 (<constant>Win2K3</constant>), and Windows
498 Vista (<constant>Vista</constant>). Anything else will be known as
499 <constant>UNKNOWN</constant>.</para>
500 </listitem>
501 </varlistentry>
502
503 <varlistentry>
504 <term>%I</term>
505 <listitem><para>the IP address of the client machine.</para>
506 <para>Before 3.6.0 it could contain IPv4 mapped IPv6 addresses,
507 now it only contains IPv4 or IPv6 addresses.</para>
508 </listitem>
509 </varlistentry>
510
511 <varlistentry>
512 <term>%i</term>
513 <listitem><para>the local IP address to which a client connected.</para>
514 <para>Before 3.6.0 it could contain IPv4 mapped IPv6 addresses,
515 now it only contains IPv4 or IPv6 addresses.</para>
516 </listitem>
517 </varlistentry>
518
519 <varlistentry>
520 <term>%T</term>
521 <listitem><para>the current date and time.</para></listitem>
522 </varlistentry>
523
524 <varlistentry>
525 <term>%D</term>
526 <listitem><para>name of the domain or workgroup of the current user.</para></listitem>
527 </varlistentry>
528
529 <varlistentry>
530 <term>%w</term>
531 <listitem><para>the winbind separator.</para></listitem>
532 </varlistentry>
533
534 <varlistentry>
535 <term>%$(<replaceable>envvar</replaceable>)</term>
536 <listitem><para>the value of the environment variable
537 <replaceable>envar</replaceable>.</para></listitem>
538 </varlistentry>
539 </variablelist>
540
541 <para>
542 The following substitutes apply only to some configuration options (only those that are
543 used when a connection has been established):
544 </para>
545
546 <variablelist>
547 <varlistentry>
548 <term>%S</term>
549 <listitem><para>the name of the current service, if any.</para>
550 </listitem>
551 </varlistentry>
552
553 <varlistentry>
554 <term>%P</term>
555 <listitem><para>the root directory of the current service, if any.</para></listitem>
556 </varlistentry>
557
558 <varlistentry>
559 <term>%u</term>
560 <listitem><para>username of the current service, if any.</para>
561 </listitem>
562 </varlistentry>
563
564 <varlistentry>
565 <term>%g</term>
566 <listitem><para>primary group name of %u.</para></listitem>
567 </varlistentry>
568
569 <varlistentry>
570 <term>%H</term>
571 <listitem><para>the home directory of the user given by %u.</para></listitem>
572 </varlistentry>
573
574 <varlistentry>
575 <term>%N</term>
576 <listitem><para>
577 the name of your NIS home directory server. This is obtained from your NIS auto.map entry.
578 If you have not compiled Samba with the <emphasis>--with-automount</emphasis> option, this
579 value will be the same as %L.</para></listitem>
580 </varlistentry>
581
582 <varlistentry>
583 <term>%p</term>
584 <listitem><para>
585 the path of the service's home directory, obtained from your NIS auto.map entry. The NIS
586 auto.map entry is split up as <literal>%N:%p</literal>.</para></listitem>
587 </varlistentry>
588 </variablelist>
589
590 <para>
591 There are some quite creative things that can be done with these substitutions and other
592 <filename moreinfo="none">smb.conf</filename> options.
593 </para>
594</refsect1>
595
596<refsect1 id="NAMEMANGLINGSECT">
597 <title>NAME MANGLING</title>
598
599 <para>
600 Samba supports <literal>name mangling</literal> so that DOS and Windows clients can use files that don't
601 conform to the 8.3 format. It can also be set to adjust the case of 8.3 format filenames.
602 </para>
603
604 <para>
605 There are several options that control the way mangling is performed, and they are grouped here rather
606 than listed separately. For the defaults look at the output of the testparm program.
607 </para>
608
609 <para>
610 These options can be set separately for each service.
611 </para>
612
613 <para>
614 The options are:
615 </para>
616
617 <variablelist>
618
619 <varlistentry>
620 <term>case sensitive = yes/no/auto</term>
621 <listitem><para>
622 controls whether filenames are case sensitive. If they aren't, Samba must do a filename search and match on
623 passed names. The default setting of auto allows clients that support case sensitive filenames (Linux CIFSVFS
624 and smbclient 3.0.5 and above currently) to tell the Samba server on a per-packet basis that they wish to
625 access the file system in a case-sensitive manner (to support UNIX case sensitive semantics). No Windows or
626 DOS system supports case-sensitive filename so setting this option to auto is that same as setting it to no
627 for them. Default <emphasis>auto</emphasis>.
628 </para></listitem>
629 </varlistentry>
630
631 <varlistentry>
632 <term>default case = upper/lower</term>
633 <listitem><para>
634 controls what the default case is for new filenames (ie. files that don't currently exist in the filesystem).
635 Default <emphasis>lower</emphasis>. IMPORTANT NOTE: As part of the optimizations for directories containing
636 large numbers of files, the following special case applies. If the options
637 <smbconfoption name="case sensitive">yes</smbconfoption>, <smbconfoption name="preserve case">No</smbconfoption>, and
638 <smbconfoption name="short preserve case">No</smbconfoption> are set, then the case of <emphasis>all</emphasis>
639 incoming client filenames, not just new filenames, will be modified. See additional notes below.
640 </para></listitem>
641 </varlistentry>
642
643 <varlistentry>
644 <term>preserve case = yes/no</term>
645 <listitem><para>
646 controls whether new files (ie. files that don't currently exist in the filesystem) are created with the case
647 that the client passes, or if they are forced to be the <literal>default</literal> case. Default
648 <emphasis>yes</emphasis>.
649 </para></listitem>
650 </varlistentry>
651
652 <varlistentry>
653 <term>short preserve case = yes/no</term>
654 <listitem><para>
655 controls if new files (ie. files that don't currently exist in the filesystem) which conform to 8.3 syntax,
656 that is all in upper case and of suitable length, are created upper case, or if they are forced to be the
657 <literal>default</literal> case. This option can be used with <literal>preserve case = yes</literal> to permit
658 long filenames to retain their case, while short names are lowercased. Default <emphasis>yes</emphasis>.
659 </para></listitem>
660 </varlistentry>
661 </variablelist>
662
663 <para>
664 By default, Samba 3.0 has the same semantics as a Windows NT server, in that it is case insensitive
665 but case preserving. As a special case for directories with large numbers of files, if the case
666 options are set as follows, "case sensitive = yes", "case preserve = no", "short preserve case = no"
667 then the "default case" option will be applied and will modify all filenames sent from the client
668 when accessing this share.
669 </para>
670
671</refsect1>
672
673<refsect1 id="VALIDATIONSECT">
674 <title>NOTE ABOUT USERNAME/PASSWORD VALIDATION</title>
675
676 <para>
677 There are a number of ways in which a user can connect to a service. The server uses the following steps
678 in determining if it will allow a connection to a specified service. If all the steps fail, the connection
679 request is rejected. However, if one of the steps succeeds, the following steps are not checked.
680 </para>
681
682 <para>
683 If the service is marked <quote>guest only = yes</quote> and the server is running with share-level
684 security (<quote>security = share</quote>, steps 1 to 5 are skipped.
685 </para>
686
687
688 <orderedlist continuation="restarts" inheritnum="ignore" numeration="arabic">
689 <listitem><para>
690 If the client has passed a username/password pair and that username/password pair is validated by the UNIX
691 system's password programs, the connection is made as that username. This includes the
692 <literal>\\server\service</literal>%<replaceable>username</replaceable> method of passing a username.
693 </para></listitem>
694
695 <listitem><para>
696 If the client has previously registered a username with the system and now supplies a correct password for that
697 username, the connection is allowed.
698 </para></listitem>
699
700 <listitem><para>
701 The client's NetBIOS name and any previously used usernames are checked against the supplied password. If
702 they match, the connection is allowed as the corresponding user.
703 </para></listitem>
704
705 <listitem><para>
706 If the client has previously validated a username/password pair with the server and the client has passed
707 the validation token, that username is used.
708 </para></listitem>
709
710 <listitem><para>
711 If a <literal>user = </literal> field is given in the <filename moreinfo="none">smb.conf</filename> file for the
712 service and the client has supplied a password, and that password matches (according to the UNIX system's
713 password checking) with one of the usernames from the <literal>user =</literal> field, the connection is made as
714 the username in the <literal>user =</literal> line. If one of the usernames in the <literal>user =</literal> list
715 begins with a <literal>@</literal>, that name expands to a list of names in the group of the same name.
716 </para></listitem>
717
718 <listitem><para>
719 If the service is a guest service, a connection is made as the username given in the <literal>guest account
720 =</literal> for the service, irrespective of the supplied password.
721 </para></listitem>
722 </orderedlist>
723
724</refsect1>
725
726<refsect1>
727 <title>REGISTRY-BASED CONFIGURATION</title>
728
729 <para>
730 Starting with Samba version 3.2.0, the capability to
731 store Samba configuration in the registry is available.
732 The configuration is stored in the registry key
733 <emphasis><literal>HKLM\Software\Samba\smbconf</literal></emphasis>.
734 There are two levels of registry configuration:
735 </para>
736
737 <orderedlist continuation="restarts" inheritnum="ignore" numeration="arabic">
738 <listitem><para>Share definitions stored in registry are used.
739 This is triggered by setting the global
740 parameter <parameter>registry shares</parameter>
741 to <quote>yes</quote> in <emphasis>smb.conf</emphasis>.
742 </para>
743
744 <para>The registry shares are loaded not at startup but
745 on demand at runtime by <emphasis>smbd</emphasis>.
746 Shares defined in <emphasis>smb.conf</emphasis> take
747 priority over shares of the same name defined in
748 registry.</para></listitem>
749
750 <listitem>
751 <para>Global <emphasis>smb.conf</emphasis>
752 options stored in registry are used. This can be activated
753 in two different ways:</para>
754
755 <para>Firstly, a registry only configuration is triggered
756 by setting
757 <smbconfoption name="config backend">registry</smbconfoption>
758 in the [global] section of <emphasis>smb.conf</emphasis>.
759 This resets everything that has been read from config files
760 to this point and reads the content of the global configuration
761 section from the registry.
762 This is the recommended method of using registry based
763 configuration.</para>
764
765 <para>Secondly, a mixed configuration can be activated
766 by a special new meaning of the parameter
767 <smbconfoption name="include">registry</smbconfoption>
768 in the [global] section of <emphasis>smb.conf</emphasis>.
769 This reads the global options from registry with the same
770 priorities as for an include of a text file.
771 This may be especially useful in cases where an initial
772 configuration is needed to access the registry.</para>
773
774 <para>Activation of global registry options automatically
775 activates registry shares. So in the registry only case,
776 shares are loaded on demand only.</para>
777 </listitem>
778 </orderedlist>
779
780 <para>
781 Note: To make registry-based configurations foolproof
782 at least to a certain extent, the use
783 of <parameter>lock directory</parameter> and
784 <parameter>config backend</parameter>
785 inside the registry configuration has been disabled:
786 Especially by changing the
787 <parameter>lock directory</parameter> inside the registry
788 configuration, one would create a broken setup where the daemons
789 do not see the configuration they loaded once it is active.
790 </para>
791
792 <para>
793 The registry configuration can be accessed with
794 tools like <emphasis>regedit</emphasis> or <emphasis>net (rpc)
795 registry</emphasis> in the key
796 <emphasis><literal>HKLM\Software\Samba\smbconf</literal></emphasis>.
797
798 More conveniently, the <emphasis>conf</emphasis> subcommand of the
799 <citerefentry><refentrytitle>net</refentrytitle>
800 <manvolnum>8</manvolnum></citerefentry> utility
801 offers a dedicated interface to read and write the
802 registry based configuration locally, i.e. directly
803 accessing the database file, circumventing the
804 server.
805 </para>
806
807</refsect1>
808
809<refsect1>
810 <title>EXPLANATION OF EACH PARAMETER</title>
811
812 <samba:parameterlist>
813 <xi:include href="../smbdotconf/parameters.all.xml" parse="xml"/>
814 </samba:parameterlist>
815
816</refsect1>
817
818<refsect1>
819 <title>WARNINGS</title>
820
821 <para>
822 Although the configuration file permits service names to contain spaces, your client software may not.
823 Spaces will be ignored in comparisons anyway, so it shouldn't be a problem - but be aware of the possibility.
824 </para>
825
826 <para>
827 On a similar note, many clients - especially DOS clients - limit service names to eight characters.
828 <citerefentry><refentrytitle>smbd</refentrytitle> <manvolnum>8</manvolnum></citerefentry> has no such
829 limitation, but attempts to connect from such clients will fail if they truncate the service names. For this
830 reason you should probably keep your service names down to eight characters in length.
831 </para>
832
833 <para>
834 Use of the <literal>[homes]</literal> and <literal>[printers]</literal> special sections make life
835 for an administrator easy, but the various combinations of default attributes can be tricky. Take extreme
836 care when designing these sections. In particular, ensure that the permissions on spool directories are
837 correct.
838 </para>
839
840</refsect1>
841
842<refsect1>
843 <title>VERSION</title>
844
845 <para>This man page is correct for version 3 of the Samba suite.</para>
846</refsect1>
847
848<refsect1>
849 <title>SEE ALSO</title>
850 <para>
851 <citerefentry><refentrytitle>samba</refentrytitle>
852 <manvolnum>7</manvolnum></citerefentry>, <citerefentry><refentrytitle>smbpasswd</refentrytitle>
853 <manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>swat</refentrytitle>
854 <manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>smbd</refentrytitle>
855 <manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>nmbd</refentrytitle>
856 <manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>smbclient</refentrytitle>
857 <manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>nmblookup</refentrytitle>
858 <manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>testparm</refentrytitle>
859 <manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>testprns</refentrytitle>
860 <manvolnum>1</manvolnum></citerefentry>.</para>
861</refsect1>
862
863<refsect1>
864 <title>AUTHOR</title>
865
866 <para>
867 The original Samba software and related utilities were created by Andrew Tridgell. Samba is now developed
868 by the Samba Team as an Open Source project similar to the way the Linux kernel is developed.
869 </para>
870
871 <para>
872 The original Samba man pages were written by Karl Auer. The man page sources were converted to YODL format (another
873 excellent piece of Open Source software, available at <ulink noescape="1" url="ftp://ftp.icce.rug.nl/pub/unix/">
874 ftp://ftp.icce.rug.nl/pub/unix/</ulink>) and updated for the Samba 2.0 release by Jeremy Allison. The conversion
875 to DocBook for Samba 2.2 was done by Gerald Carter. The conversion to DocBook XML 4.2 for Samba 3.0 was done by
876 Alexander Bokovoy.
877 </para>
878</refsect1>
879
880</refentry>
Note: See TracBrowser for help on using the repository browser.