~zulcss/samba/server-dailies-3.4

« back to all changes in this revision

Viewing changes to docs-xml/manpages-3/smb.conf.5.xml

  • Committer: Chuck Short
  • Date: 2010-09-28 20:38:39 UTC
  • Revision ID: zulcss@ubuntu.com-20100928203839-pgjulytsi9ue63x1
Initial version

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
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.4</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>
 
276
alias|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>
 
356
mkdir /usr/local/samba/lib/usershares
 
357
chgrp foo /usr/local/samba/lib/usershares
 
358
chmod 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
                    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
                </listitem>
 
507
                </varlistentry>
 
508
 
 
509
                <varlistentry>
 
510
                <term>%i</term>
 
511
                <listitem><para>the local IP address to which a client connected.</para>
 
512
                </listitem>
 
513
                </varlistentry>
 
514
 
 
515
                <varlistentry>
 
516
                <term>%T</term>
 
517
                <listitem><para>the current date and time.</para></listitem>
 
518
                </varlistentry>
 
519
 
 
520
                <varlistentry>
 
521
                <term>%D</term>
 
522
                <listitem><para>name of the domain or workgroup of the current user.</para></listitem>
 
523
                </varlistentry>
 
524
                
 
525
                <varlistentry>
 
526
                <term>%w</term>
 
527
                <listitem><para>the winbind separator.</para></listitem>
 
528
                </varlistentry>
 
529
                
 
530
                <varlistentry>
 
531
                <term>%$(<replaceable>envvar</replaceable>)</term>
 
532
                <listitem><para>the value of the environment variable
 
533
                <replaceable>envar</replaceable>.</para></listitem>
 
534
                </varlistentry>
 
535
        </variablelist>
 
536
 
 
537
        <para>
 
538
        The following substitutes apply only to some configuration options (only those that are
 
539
        used when a connection has been established):
 
540
        </para>
 
541
 
 
542
        <variablelist>
 
543
                <varlistentry>
 
544
                <term>%S</term>
 
545
                <listitem><para>the name of the current service, if any.</para>
 
546
                </listitem>
 
547
                </varlistentry>
 
548
        
 
549
                <varlistentry>
 
550
                <term>%P</term>
 
551
                <listitem><para>the root directory of the current service, if any.</para></listitem>
 
552
                </varlistentry>
 
553
        
 
554
                <varlistentry>
 
555
                <term>%u</term>
 
556
                <listitem><para>username of the current service, if any.</para>
 
557
                </listitem>
 
558
                </varlistentry>
 
559
        
 
560
                <varlistentry>
 
561
                <term>%g</term>
 
562
                <listitem><para>primary group name of %u.</para></listitem>
 
563
                </varlistentry>
 
564
        
 
565
                <varlistentry>
 
566
                <term>%H</term>
 
567
                <listitem><para>the home directory of the user given by %u.</para></listitem>
 
568
                </varlistentry>
 
569
 
 
570
                <varlistentry>
 
571
                <term>%N</term>
 
572
                <listitem><para>
 
573
                        the name of your NIS home directory server.  This is obtained from your NIS auto.map entry. 
 
574
                        If you have not compiled Samba with the <emphasis>--with-automount</emphasis> option, this
 
575
                        value will be the same as %L.</para></listitem>
 
576
                </varlistentry>
 
577
        
 
578
                <varlistentry>
 
579
                <term>%p</term>
 
580
                <listitem><para>
 
581
                        the path of the service's home directory, obtained from your NIS auto.map entry. The NIS
 
582
                        auto.map entry is split up as <literal>%N:%p</literal>.</para></listitem>
 
583
                </varlistentry>
 
584
        </variablelist>
 
585
        
 
586
        <para>
 
587
        There are some quite creative things that can be done with these substitutions and other
 
588
        <filename moreinfo="none">smb.conf</filename> options.
 
589
        </para>
 
590
</refsect1>
 
591
 
 
592
<refsect1 id="NAMEMANGLINGSECT">
 
593
        <title>NAME MANGLING</title>
 
594
        
 
595
        <para>
 
596
        Samba supports <literal>name mangling</literal> so that DOS and Windows clients can use files that don't
 
597
        conform to the 8.3 format. It can also be set to adjust the case of 8.3 format filenames.
 
598
        </para>
 
599
 
 
600
        <para>
 
601
        There are several options that control the way mangling is performed, and they are grouped here rather
 
602
        than listed separately. For the defaults look at the output of the testparm program.
 
603
        </para>
 
604
 
 
605
        <para>
 
606
        These options can be set separately for each service.
 
607
        </para>
 
608
 
 
609
        <para>
 
610
        The options are:
 
611
        </para>
 
612
        
 
613
        <variablelist>
 
614
        
 
615
        <varlistentry>
 
616
                <term>case sensitive = yes/no/auto</term>
 
617
                <listitem><para>
 
618
                controls whether filenames are case sensitive. If they aren't, Samba must do a filename search and match on
 
619
                passed names. The default setting of auto allows clients that support case sensitive filenames (Linux CIFSVFS
 
620
                and smbclient 3.0.5 and above currently) to tell the Samba server on a per-packet basis that they wish to
 
621
                access the file system in a case-sensitive manner (to support UNIX case sensitive semantics). No Windows or
 
622
                DOS system supports case-sensitive filename so setting this option to auto is that same as setting it to no
 
623
                for them. Default <emphasis>auto</emphasis>.
 
624
                </para></listitem>
 
625
                </varlistentry> 
 
626
 
 
627
                <varlistentry>
 
628
                <term>default case = upper/lower</term>
 
629
                <listitem><para>
 
630
                controls what the default case is for new filenames (ie. files that don't currently exist in the filesystem).
 
631
                Default <emphasis>lower</emphasis>.  IMPORTANT NOTE: This option will be used to modify the case of
 
632
                <emphasis>all</emphasis> incoming client filenames, not just new filenames if the options <smbconfoption
 
633
                name="case sensitive">yes</smbconfoption>, <smbconfoption name="preserve case">No</smbconfoption>,
 
634
                <smbconfoption name="short preserve case">No</smbconfoption> are set.  This change is needed as part of the
 
635
                optimisations for directories containing large numbers of files.
 
636
                </para></listitem>
 
637
                </varlistentry> 
 
638
        
 
639
                <varlistentry>
 
640
                <term>preserve case = yes/no</term>
 
641
                <listitem><para>
 
642
                controls whether new files (ie. files that don't currently exist in the filesystem) are created with the case
 
643
                that the client passes, or if they are forced to be the <literal>default</literal> case. Default
 
644
                <emphasis>yes</emphasis>.
 
645
                </para></listitem>
 
646
                </varlistentry> 
 
647
 
 
648
                <varlistentry>
 
649
                <term>short preserve case = yes/no</term>
 
650
                <listitem><para>
 
651
                controls if new files (ie. files that don't currently exist in the filesystem) which conform to 8.3 syntax,
 
652
                that is all in upper case and of suitable length, are created upper case, or if they are forced to be the
 
653
                <literal>default</literal> case. This option can be used with <literal>preserve case = yes</literal> to permit
 
654
                long filenames to retain their case, while short names are lowercased. Default <emphasis>yes</emphasis>.
 
655
                </para></listitem>
 
656
                </varlistentry> 
 
657
        </variablelist>
 
658
        
 
659
        <para>
 
660
        By default, Samba 3.0 has the same semantics as a Windows NT server, in that it is case insensitive
 
661
        but case preserving. As a special case for directories with large numbers of files, if the case
 
662
        options are set as follows, "case sensitive = yes", "case preserve = no", "short preserve case = no"
 
663
        then the "default case" option will be applied and will modify all filenames sent from the client
 
664
        when accessing this share.
 
665
        </para>
 
666
        
 
667
</refsect1>
 
668
 
 
669
<refsect1 id="VALIDATIONSECT">
 
670
        <title>NOTE ABOUT USERNAME/PASSWORD VALIDATION</title>
 
671
 
 
672
        <para>
 
673
        There are a number of ways in which a user can connect to a service. The server uses the following steps
 
674
        in determining if it will allow a connection to a specified service. If all the steps fail, the connection
 
675
        request is rejected.  However, if one of the steps succeeds, the following steps are not checked.
 
676
        </para>
 
677
 
 
678
        <para>
 
679
        If the service is marked <quote>guest only = yes</quote> and the server is running with share-level
 
680
        security (<quote>security = share</quote>, steps 1 to 5 are skipped.
 
681
        </para>
 
682
 
 
683
 
 
684
        <orderedlist continuation="restarts" inheritnum="ignore" numeration="arabic">
 
685
                <listitem><para>
 
686
                If the client has passed a username/password pair and that username/password pair is validated by the UNIX 
 
687
                system's password programs, the connection is made as that username. This includes the
 
688
                <literal>\\server\service</literal>%<replaceable>username</replaceable> method of passing a username.
 
689
                </para></listitem>
 
690
 
 
691
                <listitem><para>
 
692
                If the client has previously registered a username with the system and now supplies a correct password for that 
 
693
                username, the connection is allowed.
 
694
                </para></listitem>
 
695
                
 
696
                <listitem><para>
 
697
                The client's NetBIOS name and any previously used usernames are checked against the supplied password. If 
 
698
                they match, the connection is allowed as the corresponding user.
 
699
                </para></listitem>
 
700
                
 
701
                <listitem><para>
 
702
                If the client has previously validated a username/password pair with the server and the client has passed 
 
703
                the validation token, that username is used.
 
704
                </para></listitem>
 
705
 
 
706
                <listitem><para>
 
707
                If a <literal>user = </literal> field is given in the <filename moreinfo="none">smb.conf</filename> file for the
 
708
                service and the client has supplied a password, and that password matches (according to the UNIX system's
 
709
                password checking) with one of the usernames from the <literal>user =</literal> field, the connection is made as
 
710
                the username in the <literal>user =</literal> line. If one of the usernames in the <literal>user =</literal> list
 
711
                begins with a <literal>@</literal>, that name expands to a list of names in the group of the same name.
 
712
                </para></listitem>
 
713
 
 
714
                <listitem><para>
 
715
                If the service is a guest service, a connection is made as the username given in the <literal>guest account
 
716
                =</literal> for the service, irrespective of the supplied password.
 
717
                </para></listitem>
 
718
        </orderedlist>
 
719
 
 
720
</refsect1>
 
721
 
 
722
<refsect1>
 
723
        <title>REGISTRY-BASED CONFIGURATION</title>
 
724
 
 
725
        <para>
 
726
                Starting with Samba version 3.2.0, the capability to
 
727
                store Samba configuration in the registry is available.
 
728
                The configuration is stored in the registry key
 
729
                 <emphasis><literal>HKLM\Software\Samba\smbconf</literal></emphasis>.
 
730
                There are two levels of registry configuration:
 
731
        </para>
 
732
 
 
733
        <orderedlist continuation="restarts" inheritnum="ignore" numeration="arabic">
 
734
                <listitem><para>Share definitions stored in registry are used.
 
735
                This is triggered by setting the global 
 
736
                parameter <parameter>registry shares</parameter>
 
737
                to <quote>yes</quote> in <emphasis>smb.conf</emphasis>.
 
738
                </para>
 
739
 
 
740
                <para>The registry shares are loaded not at startup but
 
741
                on demand at runtime by <emphasis>smbd</emphasis>.
 
742
                Shares defined in <emphasis>smb.conf</emphasis> take
 
743
                priority over shares of the same name defined in
 
744
                registry.</para></listitem>
 
745
 
 
746
                <listitem>
 
747
                <para>Global <emphasis>smb.conf</emphasis>
 
748
                options stored in registry are used. This can be activated
 
749
                in two different ways:</para>
 
750
 
 
751
                <para>Firstly, a registry only configuration is triggered
 
752
                by setting
 
753
                <smbconfoption name="config backend">registry</smbconfoption>
 
754
                in the [global] section of <emphasis>smb.conf</emphasis>.
 
755
                This resets everything that has been read from config files
 
756
                to this point and reads the content of the global configuration
 
757
                section from the registry.
 
758
                This is the recommended method of using registry based
 
759
                configuration.</para>
 
760
 
 
761
                <para>Secondly, a mixed configuration can be activated
 
762
                by a special new meaning of the parameter
 
763
                <smbconfoption name="include">registry</smbconfoption>
 
764
                in the [global] section of <emphasis>smb.conf</emphasis>.
 
765
                This reads the global options from registry with the same
 
766
                priorities as for an include of a text file.
 
767
                This may be especially useful in cases where an initial
 
768
                configuration is needed to access the registry.</para>
 
769
 
 
770
                <para>Activation of global registry options automatically
 
771
                activates registry shares. So in the registry only case,
 
772
                shares are loaded on demand only.</para>
 
773
                </listitem>
 
774
        </orderedlist>
 
775
 
 
776
        <para>
 
777
                Note: To make registry-based configurations foolproof
 
778
                at least to a certain extent, the use
 
779
                of <parameter>lock directory</parameter> and
 
780
                 <parameter>config backend</parameter>
 
781
                inside the registry configuration has been disabled:
 
782
                Especially by changing the
 
783
                 <parameter>lock directory</parameter> inside the registry
 
784
                configuration, one would create a broken setup where the daemons
 
785
                do not see the configuration they loaded once it is active.
 
786
        </para>
 
787
 
 
788
        <para>
 
789
                The registry configuration can be accessed with
 
790
                tools like <emphasis>regedit</emphasis> or <emphasis>net (rpc)
 
791
                registry</emphasis> in the key
 
792
                 <emphasis><literal>HKLM\Software\Samba\smbconf</literal></emphasis>.
 
793
 
 
794
                More conveniently, the <emphasis>conf</emphasis> subcommand of the
 
795
                 <citerefentry><refentrytitle>net</refentrytitle>
 
796
                <manvolnum>8</manvolnum></citerefentry> utility
 
797
                offers a dedicated interface to read and write the
 
798
                registry based configuration locally, i.e. directly
 
799
                accessing the database file, circumventing the
 
800
                server.
 
801
        </para>
 
802
 
 
803
</refsect1>
 
804
 
 
805
<refsect1>
 
806
        <title>EXPLANATION OF EACH PARAMETER</title>
 
807
        
 
808
        <samba:parameterlist>
 
809
                <xi:include href="../smbdotconf/parameters.all.xml" parse="xml"/>
 
810
        </samba:parameterlist>
 
811
 
 
812
</refsect1>
 
813
 
 
814
<refsect1>
 
815
        <title>WARNINGS</title>
 
816
        
 
817
        <para>
 
818
        Although the configuration file permits service names to contain spaces, your client software may not.
 
819
        Spaces will be ignored in comparisons anyway, so it shouldn't be a problem - but be aware of the possibility.
 
820
        </para>
 
821
 
 
822
        <para>
 
823
        On a similar note, many clients - especially DOS clients - limit service names to eight characters.
 
824
        <citerefentry><refentrytitle>smbd</refentrytitle> <manvolnum>8</manvolnum></citerefentry> has no such
 
825
        limitation, but attempts to connect from such clients will fail if they truncate the service names.  For this
 
826
        reason you should probably keep your service names down to eight characters in length.
 
827
        </para>
 
828
 
 
829
        <para>
 
830
        Use of the <literal>[homes]</literal> and <literal>[printers]</literal> special sections make life 
 
831
        for an administrator easy, but the various combinations of default attributes can be tricky. Take extreme
 
832
        care when designing these sections. In particular, ensure that the permissions on spool directories are
 
833
        correct.
 
834
        </para>
 
835
 
 
836
</refsect1>
 
837
 
 
838
<refsect1>
 
839
        <title>VERSION</title>
 
840
 
 
841
        <para>This man page is correct for version 3 of the Samba suite.</para>
 
842
</refsect1>
 
843
 
 
844
<refsect1>
 
845
        <title>SEE ALSO</title>
 
846
        <para>
 
847
        <citerefentry><refentrytitle>samba</refentrytitle>
 
848
        <manvolnum>7</manvolnum></citerefentry>, <citerefentry><refentrytitle>smbpasswd</refentrytitle>
 
849
        <manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>swat</refentrytitle>
 
850
        <manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>smbd</refentrytitle>
 
851
        <manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>nmbd</refentrytitle>
 
852
        <manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>smbclient</refentrytitle>
 
853
        <manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>nmblookup</refentrytitle>
 
854
        <manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>testparm</refentrytitle>
 
855
        <manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>testprns</refentrytitle>
 
856
        <manvolnum>1</manvolnum></citerefentry>.</para>
 
857
</refsect1>
 
858
 
 
859
<refsect1>
 
860
        <title>AUTHOR</title>
 
861
        
 
862
        <para>
 
863
        The original Samba software and related utilities were created by Andrew Tridgell. Samba is now developed
 
864
        by the Samba Team as an Open Source project similar to the way the Linux kernel is developed.
 
865
        </para>
 
866
        
 
867
        <para>
 
868
        The original Samba man pages were written by Karl Auer. The man page sources were converted to YODL format (another 
 
869
        excellent piece of Open Source software, available at <ulink noescape="1" url="ftp://ftp.icce.rug.nl/pub/unix/">
 
870
        ftp://ftp.icce.rug.nl/pub/unix/</ulink>) and updated for the Samba 2.0 release by Jeremy Allison.  The conversion
 
871
        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
 
872
        Alexander Bokovoy.
 
873
        </para>
 
874
</refsect1>
 
875
 
 
876
</refentry>