4 <H1 ALIGN=CENTER>SWAT Parameters help</H1>
8 <H3><A NAME="admin users">admin users (S)</A></H3>
9 This is a list of users who will be granted administrative privileges on the
10 share. This means that they will do all file operations as the super-user
12 You should use this option very carefully, as any user in this list will be
13 able to do anything they like on the share, irrespective of file permissions.<P>
14 <B>Default:</B> no admin users <P>
15 <B>Example:</B> admin users = jason <P>
17 <H3><A NAME="announce as">announce as (G)</A></H3>
18 This specifies what type of server nmbd will announce itself as in browse
19 lists. By default this is set to Windows NT. The valid options are "NT",
20 "Win95" or "WfW" meaining Windows NT, Windows 95 and Windows for Workgroups
21 respectively. Do not change this parameter unless you have a specific need to
22 stop Samba appearing as an NT server as this may prevent Samba servers from
23 participating as browser servers correctly. <P>
24 <B>Default:</B> announce as = NT <P>
25 <B>Example:</B> announce as = Win95 <P>
27 <H3><A NAME="announce version">announce version (G)</A></H3>
28 This specifies the major and minor version numbers that nmbd will use when
29 announcing itself as a server. The default is 4.2. Do not change this parameter
30 unless you have a specific need to set a Samba server to be a downlevel
32 <B>Default:</B> announce version = 4.2 <P>
33 <B>Example:</B> announce version = 2.0 <P>
35 <H3><A NAME="alternate permissions">alternate permissions (S)</A></H3>
36 This option affects the way the "read only" DOS attribute is produced for
37 UNIX files. If this is No then the read only bit is set for files on
38 writeable shares which the user cannot write to. <P>
39 If this is Yes then "read only" is set for files when the user write bit is
41 The latter behaviour is useful when users copy files from each others
42 directories, and use a file manager that preserves permissions. Without this
43 option they may get annoyed as all copied files will have the "read only"
45 <B>Default:</B> alternate permissions = no <P>
46 <B>Example:</B> alternate permissions = yes <P>
48 <H3><A NAME="available">available (S)</A></H3>
49 This parameter lets you 'turn off' a service. If 'available = no', then ALL
50 attempts to connect to the service will fail. Such failures are logged. <P>
51 <B>Default:</B> available = yes <P>
52 <B>Example:</B> available = no <P>
54 <H3><A NAME="bind interfaces only">bind interfaces only (G)</A></H3>
55 This global parameter (new for 1.9.18) allows the Samba admin to limit what
56 interfaces on a machine will serve smb requests. If affects file service
57 (smbd) and name service (nmbd) in slightly different ways. <P>
58 For name service it causes nmbd to bind to ports 137 and 138 on the interfaces
59 listed in the 'interfaces' parameter. nmbd also binds to the 'all addresses'
60 interface (0.0.0.0) on ports 137 and 138 for the purposes of reading broadcast
61 messages. If this option is not set then nmbd will service name requests on
62 all of these sockets. If "bind interfaces only" is set then nmbd will check
63 the source address of any packets coming in on the broadcast sockets and
64 discard any that don't match the broadcast addresses of the interfaces in the
65 <A HREF="#interfaces">interfaces</A> parameter list. As unicast packets are
66 received on the other sockets it allows nmbd to refuse to serve names to
67 machines that send packets that arrive through any interfaces not listed in
68 the 'interfaces' list. IP Source address spoofing does defeat this simple
69 check, however so it must not be used seriously as a security feature for
71 For file service it causes smbd to bind only to the interface list given in
72 the <A HREF="#interfaces">interfaces</A> parameter. This restricts
73 the networks that smbd will serve to packets coming in those interfaces.
74 Note that you should not use this parameter for machines that are serving
75 ppp or other intermittant or non-broadcast network interfaces as it will
76 not cope with non-permanent interfaces. <P>
77 <B>Default:</B> bind interfaces only = No <P>
78 <B>Example:</B> bind interfaces only = Yes <P>
80 <H3><A NAME="browseable">browseable (S)</A></H3>
81 This controls whether this share is seen in the list of available shares
82 in a net view and in the browse list. <P>
83 <B>Default:</B> browseable = Yes <P>
84 <B>Example:</B> browseable = No <P>
86 <H3><A NAME="browse list">browse list(G)</A></H3>
87 This controls whether the smbd will serve a browse list to a client doing a
88 NetServerEnum call. Normally set to Yes. You should never need to change
90 <B>Default:</B> browse list = Yes <P>
92 <H3><A NAME="case sensitive">case sensitive (G)</A></H3>
93 Controls whether filenames are case sensitive. If they aren't then Samba must
94 do a filename search and match on passed names.<P>
95 <B>Default:</B> case sensitive = No <P>
96 See the discussion on <A HREF="#NAME MANGLING">NAME MANGLING</A>. <P>
98 <H3><A NAME="character set">character set (G)</A></H3>
99 This allows smbd to map incoming characters from a DOS 850 Code page to
100 either a Western European (ISO8859-1) or Easter European (ISO8859-2) code page.
101 Normally not set, meaning no filename translation is done. <P>
102 <B>Default:</B> character set = <P>
103 <B>Example:</B> character set = iso8859-1 <P>
105 <H3><A NAME="client code page">client code page (G)</A></H3>
106 Currently (Samba 1.9.19 and above) this may be set to one of the following
107 values: 437, 850, 852, 866, 932, 936, 949, or 950. It specifies the base DOS
108 code page that the clients accessing Samba are using. To determine this,
109 open a DOS command prompt and type the command "chcp". This will output
110 the code page. The default for USA MS-DOS, Windows 95, and Windows NT releases
111 is code page 437. The default for western european releases of the above
112 operating systems is code page 850. <P>
113 This parameter co-operates with the <A HREF="#valid chars">valid chars</A>
114 parameter in determining what characters are valid in filenames
115 and how capitalization is done. It has been added as a convenience for
116 clients whose code page is either 437 or 850 so a convoluted "valid chars"
117 string does not have to be determined. If you set both this parameter and
118 the "valid chars" parameter the "client code page" parameter MUST be
119 set before the "valid chars" in the smb.conf file. The "valid chars" string
120 will then augment the character settings in the "client code page" parameter.
122 If "client code page" is set to a value other than those listed above, it will
124 See also : <A HREF="#valid chars">valid chars</A>. <P>
125 <B>Default:</B> client code page = 850 <P>
126 <B>Example:</B> client code page = 437 <P>
128 <H3><A NAME="coding system">coding system (G)</A></H3>
129 <B>Default:</B> coding system = <P>
131 <H3><A NAME="comment">comment (S)</A></H3>
132 This is a text field that is seen next to a share when a client does a net
133 view to list what shares are available. <P>
134 If you want to set the string that is displayed next to the machine name then
135 see the <A HREF="#server string">server string</A> command. <P>
136 <B>Default:</B> No comment string <P>
137 <B>Example:</B> comment = Fred's Files <P>
139 <H3><A NAME="create mask">create mask (S)</A></H3>
140 A synonym for this parameter is 'create mode'. <P>
141 When a file is created, the neccessary permissions are calculated according
142 to the mapping from DOS modes to UNIX permissions, and the resulting UNIX
143 mode is then bit-wise 'AND'ed with this parameter. This parameter may be
144 thought of as a bit-wise MASK for the UNIX modes of a file. Any bit *not* set
145 here will be removed from the modes set on a file when it is created. <P>
146 The default value of this parameter removes the 'group' and 'other' write and
147 execute bits from the UNIX modes. <P>
148 Following this Samba will bit-wise 'OR' the UNIX mode created from this
149 parameter with the value of the
150 <A HREF="#force create mode">force create mode</A>
151 parameter which is set to 000 by default. <P>
152 For Samba 1.9.17 and above this parameter no longer affects directory modes.
153 See the parameter <A HREF="#directory mask">directory mask</A> for details. <P>
154 See also the <A HREF="#force create mode">force create mode</A> parameter for
155 forcing particular mode bits to be set on created files. See also the
156 <A HREF="#directory mask">directory mask</A>
157 parameter for masking mode bits on created directories. <P>
158 <B>Default:</B> create mask = 0744 <P>
159 <B>Example:</B> create mask = 0775 <P>
161 <H3><A NAME="deadtime">deadtime (G)</A></H3>
162 The value of the parameter (a decimal integer) represents the number of
163 minutes of inactivity before a connection is considered dead, and it is
164 disconnected. The deadtime only takes effect if the number of open files is
166 This is useful to stop a server's resources being exhausted by a large number
167 of inactive connections. <P>
168 Most clients have an auto-reconnect feature when a connection is broken so in
169 most cases this parameter should be transparent to users. <P>
170 Using this parameter with a timeout of a few minutes is recommended for most
172 A deadtime of zero indicates that no auto-disconnection should be performed.<P>
173 <B>Default:</B> deadtime = 0 <P>
174 <B>Example:</B> deadtime = 15
176 <H3><A NAME="default case">default case (S)</A></H3>
177 Controls what the default case (upper/lower) is for new filenames.<P>
178 See the section on <A HREF="#NAME MANGLING">NAME MANGLING</A> <P>
179 <B>Default:</B> default case = lower <P>
180 <B>Example:</B> default case = upper <P>
182 <H3><A NAME="default service">default service (G)</A></H3> A synonym for this
183 parameter is 'default'. <P>
184 This parameter specifies the name of a service which will be connected to if
185 the service actually requested cannot be found. Note that the square brackets
186 are NOT given in the parameter value (see example below). <P>
187 There is no default value for this parameter. If this parameter is not given,
188 attempting to connect to a nonexistent service results in an error. <P>
189 Typically the default service would be a public, read-only service. <P>
190 Also note that as of 1.9.14 the apparent service name will be changed to be
191 that of the requested service, this is very useful as it allows
192 you to use macros like %S to make a wildcard service. <P>
193 Note also that any _ characters in the name of the service used in the default
194 service will get mapped to a /. This allows for interesting things. <P>
195 <B>Example:</B> default service = pub<P>
201 <H3><A NAME="delete readonly">delete readonly (S)</A></H3>
202 This parameter allows readonly files to be deleted. This is not normal DOS
203 semantics, but is allowed by UNIX. <P>
204 This option may be useful for running applications such as rcs, where UNIX
205 file ownership prevents changing file permissions, and DOS semantics prevent
206 deletion of a read only file. <P>
207 <B>Default:</B> delete readonly = No <P>
208 <B>Example:</B> delete readonly = Yes <P>
210 <H3><A NAME="delete veto files">delete veto files (S)</A></H3>
211 This option is used when Samba is attempting to delete a directory that
212 contains one or more vetoed directories (see the
213 <A HREF="#veto files">veto files</A> option). If this option is set to No
214 (the default) then if a vetoed directory contains any non-vetoed files or
215 directories then the directory delete will fail. This is usually what you
217 If this option is set to Yes, then Samba will attempt to recursively delete
218 any files and directories within the vetoed directory. This can be useful
219 for integration with file serving systems such as Netatalk, which create
220 meta-files within directories you might normally veto DOS/Windows users
221 from seeing (eg. .AppleDouble) <P>
222 Setting 'delete veto files = Yes' allows these directories to be
223 transparently deleted when the parent directory is deleted (so long as the
224 user has permissions to do so). <P>
225 <B>Default:</B> delete veto files = No <P>
226 <B>Example:</B> delete veto files = Yes <P>
227 See <A HREF="#veto files">veto files</A> <P>
229 <H3><A NAME="dfree command">dfree command (G)</A></H3>
230 The dfree command setting should only be used on systems where a problem
231 occurs with the internal disk space calculations. This has been known to
232 happen with Ultrix, but may occur with other operating systems. The symptom
233 that was seen was an error of "Abort Retry Ignore" at the end of each
234 directory listing. <P>
235 This setting allows the replacement of the internal routines to calculate the
236 total disk space and amount available with an external routine. The example
237 below gives a possible script that might fulfill this function. <P>
238 The external program will be passed a single parameter indicating a directory
239 in the filesystem being queried. This will typically consist of the string
240 "./". The script should return two integers in ascii. The first should be the
241 total disk space in blocks, and the second should be the number of available
242 blocks. An optional third return value can give the block size in bytes. The
243 default blocksize is 1024 bytes. <P>
244 Note: Your script should NOT be setuid or setgid and should be owned by
245 (and writable only by) root! <P>
246 <B>Default:</B> By default internal routines for determining the disk capacity
247 and remaining space will be used. <P>
248 <B>Example:</B> dfree command = /usr/local/samba/bin/dfree <P>
249 Where the script dfree (which must be made executable) could be <P>
252 df $1 | tail -1 | awk '{print $2" "$4}'
254 or perhaps (on Sys V) <P>
257 /usr/bin/df -k $1 | tail -1 | awk '{print $3" "$5}'
259 Note that you may have to replace the command names with full path names on
262 <H3><A NAME="directory mask">directory mask (S)</A></H3>
263 A synonym for this parameter is 'directory mode'. <P>
264 This parameter is the octal modes which are used when converting DOS modes
265 to UNIX modes when creating UNIX directories. <P>
266 When a directory is created, the neccessary permissions are calculated
267 according to the mapping from DOS modes to UNIX permissions, and the resulting
268 UNIX mode is then bit-wise 'AND'ed with this parameter. This parameter may be
269 thought of as a bit-wise MASK for the UNIX modes of a directory. Any bit *not*
270 set here will be removed from the modes set on a directory when it is
272 The default value of this parameter removes the 'group' and 'other' write
273 bits from the UNIX mode, allowing only the user who owns the directory to
275 Following this Samba will bit-wise 'OR' the UNIX mode created from this
276 parameter with the value of the
277 <A HREF="#force directory mode">force directory mode</A>
278 parameter. This parameter is set to 000 by default (ie. no extra mode bits
280 See the <A HREF="#force directory mode">force directory mode</A>
281 parameter to cause particular mode bits to always be set on created
283 See also the <A HREF="#create mask">create mask</A> parameter
284 for masking mode bits on created files. <P>
285 <B>Default:</B> directory mask = 0755 <P>
286 <B>Example:</B> directory mask = 0775 <P>
288 <H3><A NAME="dns proxy">dns proxy (G)</A></H3>
289 Specifies that nmbd should (as a WINS server), on finding that a NetBIOS name
290 has not been registered, treat the NetBIOS name word-for-word as a DNS name.<P>
291 Note that the maximum length for a NetBIOS name is 15 characters, so the DNS
292 name (or DNS alias) can likewise only be 15 characters, maximum. <P>
293 <B>Default:</B> dns proxy = yes <P>
295 <H3><A NAME="domain admin users">domain admin users (G)</A></H3>
298 <H3><A NAME="domain controller">domain controller (G)</A></H3>
299 <h4>This is wrong</h4>
300 Specifies the DNS name or IP address of the machine to refer domain logons
301 from Win95 machines to. You should never need to set this parameter. <P>
302 <B>Default:</B> domain controller = no <P>
304 <H3><A NAME="domain groups">domain groups (G)</A></H3>
307 <H3><A NAME="domain guest users">domain guest users (G)</A></H3>
310 <H3><A NAME="domain hosts allow">domain hosts allow (G)</A></H3>
313 <H3><A NAME="domain hosts deny">domain hosts deny (G)</A></H3>
316 <H3><A NAME="domain logons">domain logons (G)</A></H3>
317 If set to Yes, the Samba server will serve Windows 95 domain
318 logons for the workgroup it is in. For more details on setting up this
319 feature see the file DOMAINS.txt in the Samba source documentation directory.
321 <B>Default:</B> domain logons = no <P>
323 <H3><A NAME="domain master">domain master (G)</A></H3>
324 Enable WAN-wide browse list collation. Local master browsers on
325 broadcast-isolated subnets will give samba their local browse lists, and
326 ask for a complete copy of the browse list for the whole wide area network.
327 Browser clients will then contact their local master browser, and will
328 receive the domain-wide browse list, instead of just the list for their
329 broadcast-isolated subnet. There should only be one "domain master" for
330 each workgroup name.<P>
331 <B>Default:</B> domain master = no <P>
333 <H3><A NAME="domain other sid">domain other sid (G)</A></H3>
336 <H3><A NAME="domain sid">domain sid (G)</A></H3>
339 <H3><A NAME="dont descend">dont descend (S)</A></H3>
340 There are certain directories on some systems (eg., the /proc tree under Linux)
341 that are either not of interest to clients or are infinitely deep (recursive).
342 This parameter allows you to specify a comma-delimited list of directories
343 that the server should always show as empty. <P>
344 Note that Samba can be very fussy about the exact format of the "dont descend"
345 entries. For example you may need "./proc" instead of just "/proc".
346 Experimentation is the best policy :-) <P>
347 <B>Default:</B> none (i.e., all directories are OK to descend) <P>
348 <B>Example:</B> dont descend = /proc,/dev <P>
350 <H3><A NAME="dos filetimes">dos filetimes (S)</A></H3>
351 Under DOS and Windows, if a user can write to a file they can change the
352 timestamp on it. Under POSIX semantics, only the owner of the file or root
353 may change the timestamp. By default, Samba runs with POSIX semantics and
354 refuses to change the timestamp on a file if the user smbd is acting on
355 behalf of is not the file owner. Setting this option to Yes allows DOS
356 semantics and smbd will change the file timstamp as DOS requires. This is a
357 correct implementation of a previous compile-time options (UTIME_WORKAROUND)
358 which was broken and is now removed. <P>
359 <B>Default:</B> dos filetimes = No <P>
360 <B>Example:</B> dos filetimes = Yes <P>
362 <H3><A NAME="dos filetime resolution">dos filetime resolution (S)</A></H3>
363 Under the DOS and Windows FAT filesystem, the finest granulatity on time
364 resolution is two seconds. Setting this parameter for a share causes Samba
365 to round the reported time down to the nearest two second boundary when a
366 query call that requires one second resolution is made to smbd. <P>
367 This option is mainly used as a compatibility option for Visual C++ when
368 used against Samba shares. If oplocks are enabled on a share, Visual C++
369 uses two different time reading calls to check if a file has changed since
370 it was last read. One of these calls uses a one-second granularity, the
371 other uses a two second granularity. As the two second call rounds any odd
372 second down, then if the file has a timestamp of an odd number of seconds
373 then the two timestamps will not match and Visual C++ will keep reporting
374 the file has changed. Setting this option causes the two timestamps to
375 match, and Visual C++ is happy. <P>
376 <B>Default:</B> dos filetime resolution = No <P>
377 <B>Example:</B> dos filetime resolution = Yes <P>
379 <H3><A NAME="encrypt passwords">encrypt passwords (G)</A></H3>
380 This boolean controls whether encrypted passwords will be negotiated with
381 the client. Note that Windows NT 4.0 SP3 and above will by default expect
382 encrypted passwords unless a registry entry is changed. To use encrypted
383 passwords in Samba see the file docs/ENCRYPTION.txt. <P>
384 <B>Default:</B> encrypt passwords = No <P>
386 <H3><A NAME="exec">exec (S)</A></H3>
387 A synonym for this is preexec. <P>
388 This option specifies a command to be run whenever a connection is made to
389 the service. It takes the usual substitutions. <P>
390 An interesting example is to send the users a welcome message every time
391 they log in. Maybe a message of the day? Here is an example: <P>
392 exec = csh -c 'echo \"Welcome to %S!\" | \ /usr/local/samba/bin/smbclient -M %m -I %I' & <P>
393 Of course, this could get annoying after a while :-) <P>
394 See also <A HREF="#postexec">postexec</A> <P>
395 <B>Default:</B> none (no command executed) <P>
396 <B>Example:</B> exec = echo \"%u connected to %S from %m (%I)\" >> /tmp/log <P>
399 <H3><A NAME="fake directory create times">fake directory create times (S)</A></H3>
400 NTFS and Windows VFAT file systems keep a create time for all files and
401 directories. This is not the same as the ctime - status change time - that
402 Unix keeps, so Samba by default reports the earliest of the various times
403 Unix does keep. Setting this parameter for a share causes Samba to always
404 report midnight 1-1-1980 as the create time for directories. <P>
405 This option is mainly used as a compatibility option for Visual C++
406 when used against Samba shares. Visual C++ generated makefiles have the
407 object directory as a dependency for each object file, and a make rule
408 to create the directory. Also, when NMAKE compares timestamps it uses the
409 creation time when examining a directory. Thus the object directory will
410 be created if it does not exist, but once it does exist it will always
411 have an earlier timestamp than the object files it contains. <P>
412 However, Unix time semantics mean that the create time reported by Samba
413 will be updated whenever a file is created or deleted in the directory.
414 NMAKE therefore finds all object files in the object directory bar the last
415 one built are out of date compared to the directory and rebuilds them.
416 Enabling this option ensures directories always predate their contents and
417 an NMAKE build will proceed as expected. <P>
418 <B>Default:</B> fake directory create times = No <P>
419 <B>Example:</B> fake directory create times = Yes <P>
421 <H3><A NAME="fake oplocks">fake oplocks (S)</A></H3>
422 Oplocks are the way that SMB clients get permission from a server to locally
423 cache file operations. If a server grants an oplock (opportunistic
424 lock) then the client is free to assume that it is the only one accessing
425 the file and it will aggressively cache file data. With some oplock types
426 the client may even cache file open/close operations. This can give enormous
427 performance benefits. <P>
428 When you set "fake oplocks = yes" Samba will always grant oplock requests
429 no matter how many clients are using the file. <P>
430 By enabling this option on all read-only shares or shares that you know
431 will only be accessed from one client at a time you will see a big performance
432 improvement on many operations. If you enable this option on shares where
433 multiple clients may be accessing the files read-write at the same time
434 you can get data corruption. Use this option carefully! <P>
435 It is generally much better to use the real oplock support except for
436 physically read-only media such as CDROMs. <P>
437 <B>Default:</B> fake oplocks = No <P>
438 <B>Example:</B> fake oplocks = Yes <P>
440 <H3><A NAME="follow symlinks">follow symlinks (S)</A></H3>
441 This parameter allows the Samba administrator to stop smbd from following
442 symbolic links in a particular share. Setting this parameter to "No" prevents
443 any file or directory that is a symbolic link from being followed (the
444 user will get an error). This option is very useful to stop users from
445 adding a symbolic link to /etc/pasword in their home directory for instance.
446 However it will slow filename lookups down slightly. <P>
447 <B>Default:</B> follow symlinks = Yes (smbd will follow symbolic links)<P>
449 <H3><A NAME="force create mode">force create mode (S)</A></H3>
450 This parameter specifies a set of UNIX mode bit permissions that will *always*
451 be set on a file created by Samba. This is done by bitwise 'OR'ing these
452 bits onto the mode bits of a file that is being created. The modes in this
453 parameter are bitwise 'OR'ed onto the file mode after the mask set in the
454 <A HREF="#create mask">create mask</A> parameter is applied. <P>
455 See also the parameter <A HREF="#create mask">create mask</A> for details
456 on masking mode bits on created files. <P>
457 <B>Default:</B> force create mode = 000 <P>
458 <B>Example:</B> force create mode = 0755 <P>
459 would force all created files to have read and execute permissions set for
460 'group' and 'other' as well as the read/write/execute bits set for the
463 <H3><A NAME="force directory mode">force directory mode (S)</A></H3>
464 This parameter specifies a set of UNIX mode bit permissions that will *always*
465 be set on a directory created by Samba. This is done by bitwise 'OR'ing these
466 bits onto the mode bits of a directory that is being created. The default for
467 this parameter is (in octel) 0000 which will not add any extra permission bits
468 to a created directory. This operation is done after the mode mask in the
469 parameter <A HREF="#directory mask">directory mask</A> is applied. <P>
470 See also the parameter <A HREF="#directory mask">directory mask</A>
471 for details on masking mode bits on created directories. <P>
472 <B>Default:</B> force directory mode = 000 <P>
473 <B>Example:</B> force directory mode = 0755 <P>
474 would force all created directories to have read and execute permissions
475 set for 'group' and 'other' as well as the read/write/execute bits set for
478 <H3><A NAME="force group">force group (S)</A></H3>
479 This specifies a group name that all connections to this service should be
480 made as. This may be useful for sharing files. <P>
481 <B>Default:</B> no forced group <P>
482 <B>Example:</B> force group = agroup <P>
484 <H3><A NAME="force user">force user (S)</A></H3>
485 This specifies a user name that all connections to this service should be
486 made as. This may be useful for sharing files. You should also use it
487 carefully as using it incorrectly can cause security problems. <P>
488 This user name only gets used once a connection is established. Thus clients
489 still need to connect as a valid user and supply a valid password. Once
490 connected, all file operations will be performed as the "forced user",
491 no matter what username the client connected as. <P>
492 <B>Default:</B> no forced user <P>
493 <B>Example:</B> force user = auser <P>
495 <H3><A NAME="getwd cache">getwd cache (G)</A></H3>
496 This is a tuning option. When this is enabled a cacheing algorithm will be
497 used to reduce the time taken for getwd() calls. This can have a significant
498 impact on performance, especially when widelinks is No. <P>
499 <B>Default:</B>getwd cache = No <P>
500 <B>Example:</B>getwd cache = Yes <P>
502 <H3><A NAME="guest account">guest account (S)</A></H3>
503 This is a username which will be used for access to services which are
504 specified as <A HREF="#guest ok">guest ok</A>. Whatever privileges this
505 user has will be available to any client connecting to the guest service.
506 Typically this user will exist in the password file, but will not have a
507 valid login. If a username is specified in a given service, the specified
508 username overrides this one. <P>
509 One some systems the account "nobody" may not be able to print. Use another
510 account in this case. You should test this by trying to log in as your
511 guest user (perhaps by using the "su -" command) and trying to print using
513 Note that as of version 1.9 of Samba this option may be set differently
514 for each service. <P>
515 <B>Default:</B>specified at compile time <P>
516 <B>Example:</B>guest account = nobody
518 <H3><A NAME="guest ok">guest ok (S)</A></H3>
519 A synonym for this parameter is 'public'. <P>
520 If this parameter is 'Yes' for a service, then no password is required
521 to connect to the service. Privileges will be those of the guest account. <P>
522 See the section below on
523 <A HREF="#USERNAME/PASSWORD VALIDATION">USERNAME/PASSWORD VALIDATION</A>
524 for more information about this option. <P>
525 <B>Default:</B> guest ok = No <P>
526 <B>Example:</B> guest ok = Yes
528 <H3><A NAME="guest only">guest only (S)</A></H3>
529 If this parameter is 'Yes' for a service, then only guest connections to the
530 service are permitted. This parameter will have no affect if
531 <A HREF="#guest ok">guest ok</A> is not set for the service. <P>
532 See the section below on
533 <A HREF="#USERNAME/PASSWORD VALIDATION">USERNAME/PASSWORD VALIDATION</A> for
534 more information about this option. <P>
535 <B>Default:</B> guest only = No <P>
536 <B>Example:</B> guest only = Yes
538 <H3><A NAME="hide dot files">hide dot files (S)</A></H3>
539 This is a boolean parameter that controls whether files starting with a dot
540 appear as hidden files. <P>
541 <B>Default:</B> hide dot files = Yes <P>
542 <B>Example:</B> hide dot files = No <P>
544 <H3><A NAME="hide files">hide files (S)</A></H3>
545 This is a list of files or directories that are not visible but are accessible.
546 The DOS 'hidden' attribute is applied to any files or directories that match.<P>
547 Each entry in the list must be separated by a "/", which allows spaces
548 to be included in the entry. '*' and '?' can be used to specify multiple
549 files or directories as in DOS wildcards. <P>
550 Each entry must be a unix path, not a DOS path and must not include the unix
551 directory separator "/". <P>
552 Note that the case sensitivity option is applicable in hiding files. <P>
553 Setting this parameter will affect the performance of Samba, as it will
554 be forced to check all files and directories for a match as they are scanned.<P>
555 See also <A HREF="#hide dot files">hide dot files</A>,
556 <A HREF="#veto files">veto files</A> and
557 <A HREF="#case sensitive">case sensitive</A> <P>
558 <B>Default</B> No files or directories are hidden by this option
559 (dot files are hidden by default because of the "hide dot files" option). <P>
560 <B>Example</B> hide files = /.*/DesktopFolderDB/TrashFor%m/resource.frk/ <P>
561 The above example is based on files that the Macintosh client (DAVE) creates
562 for internal use, and also still hides all files beginning with a dot. <P>
564 <H3><A NAME="homedir map">homedir map (G)</A></H3>
565 If <A HREF="#NIS homedir">NIS homedir</A> is Yes, this parameter specifies
566 the NIS (or YP) map from which the server for the user's home directory should
567 be extracted. At present, only the Sun auto.home map format is understood.
568 The form of the map is: <P>
569 username server:/some/file/system <P>
570 and the program will extract the servername from before the first ':'. There
571 should probably be a better parsing system that copes with different map
572 formats and also Amd (another automounter) maps. <P>
573 NB: The -DNETGROUP option is required in the Makefile for option
574 to work and on some architectures the line -lrpcsvc needs to be added to
575 the LIBSM variable. This is required for Solaris 2, FreeBSD and HPUX. <P>
576 See also <A HREF="#NIS homedir">NIS homedir</A> <P>
577 <B>Default:</B> homedir map = auto.home <P>
578 <B>Example:</B> homedir map = amd.homedir
580 <H3><A NAME="hosts allow">hosts allow (S)</A></H3>
581 A synonym for this parameter is 'allow hosts'. <P>
582 This parameter is a comma delimited set of hosts which are permitted to access
584 If specified in the [global] section then it will apply to all services,
585 regardless of whether the individual service has a different setting. <P>
586 You can specify the hosts by name or IP number. For example, you could restrict
587 access to only the hosts on a Class C subnet with something like
588 "hosts allow = 150.203.5.". <P>
589 You can also specify hosts by network/netmask pairs and by netgroup names
590 if your system supports netgroups. The EXCEPT keyword can also be used
591 to limit a wildcard list. The following examples may provide some help: <P>
592 Example 1: allow all IPs in 150.203.*.* except one <P>
593 hosts allow = 150.203. EXCEPT 150.203.6.66 <P>
594 Example 2: allow hosts that match the given network/netmask <P>
595 hosts allow = 150.203.15.0/255.255.255.0 <P>
596 Example 3: allow a couple of hosts <P>
597 hosts allow = lapland, arvidsjaur <P>
598 Example 4: allow only hosts in netgroup "foonet" or localhost, but deny
599 access from one particular host <P>
600 hosts allow = @foonet, localhost<P>
601 hosts deny = pirate <P>
602 Note that access still requires suitable user-level passwords. <P>
603 See <B>testparm</B>(1) for a way of testing your host access to see if it
604 does what you expect. <P>
605 <B>Default:</B> none (i.e., all hosts permitted access) <P>
606 <B>Example:</B> hosts allow = 150.203.5. myhost.mynet.edu.au<P>
608 <H3><A NAME="hosts deny">hosts deny (S)</A></H3>
609 A synonym for this parameter is 'deny hosts'. <P>
610 This is the opposite of <A HREF="#hosts allow">hosts allow</A> - hosts listed
611 here are NOT permitted access to services unless the specific services have
612 their own lists to override this one. Where the lists conflict, the 'allow'
613 list takes precedence. <P>
614 <B>Default:</B> none (i.e., no hosts specifically excluded) <P>
615 <B>Example:</B>hosts deny = 150.203.4. badhost.mynet.edu.au <P>
617 <H3><A NAME="hosts equiv">hosts equiv (G)</A></H3>
618 If this global parameter is a non-null string, it specifies the name of a
619 file to read for the names of hosts and users who will be allowed access
620 without specifying a password. <P>
621 This is not be confused with <A HREF="#hosts allow">hosts allow</A> which is
622 about hosts access to services and is more useful for guest services.
623 <B>hosts equiv</B> may be useful for NT clients which will not supply
624 passwords to samba. <P>
625 NOTE: The use of hosts.equiv can be a major security hole. This is because you
626 are trusting the PC to supply the correct username. It is very easy to get a
627 PC to supply a false username. I recommend that the hosts.equiv option be
628 only used if you really know what you are doing, or perhaps on a home network
629 where you trust your wife and kids :-) <P>
630 <B>Default</B> No host equivalences <P>
631 <B>Example</B> hosts equiv = /etc/hosts.equiv <P>
633 <H3><A NAME="include">include (G)</A></H3>
634 This allows you to include one config file
635 inside another. The file is included literally, as though typed in place. <P>
636 It takes the standard substitutions, except %u, %P and %S <P>
638 <H3><A NAME="interfaces">interfaces (G)</A></H3>
639 This option allows you to setup multiple network interfaces, so that
640 Samba can properly handle browsing on all interfaces. <P>
641 The option takes a list of ip/netmask pairs. The netmask may either be a
642 bitmask, or a bitlength. <P>
643 For example, the following line: <P>
644 interfaces = 192.168.2.10/24 192.168.3.10/24 <P>
645 would configure two network interfaces with IP addresses 192.168.2.10 and
646 192.168.3.10. The netmasks of both interfaces would be set to 255.255.255.0.<P>
647 You could produce an equivalent result by using: <P>
648 interfaces = 192.168.2.10/255.255.255.0 192.168.3.10/255.255.255.0<P>
649 if you prefer that format. <P>
650 If this option is not set then Samba will attempt to find a primary interface,
651 but won't attempt to configure more than one interface. <P>
653 <H3><A NAME="invalid users">invalid users (S)</A></H3>
654 This is a list of users that should not be allowed to login to this service.
655 This is really a "paranoid" check to absolutely ensure an improper setting
656 does not breach your security. <P>
657 A name starting with @ is interpreted as a UNIX group. <P>
658 The current servicename is substituted for %S. This is useful in the [homes]
660 See also <A HREF="#valid users">valid users</A> <P>
661 <B>Default</B> No invalid users <P>
662 <B>Example</B> invalid users = root fred admin @wheel <P>
664 <H3><A NAME="keepalive">keepalive (G)</A></H3>
665 The value of the parameter (an integer) represents the number of seconds
666 between 'keepalive' packets. If this parameter is zero, no keepalive packets
667 will be sent. Keepalive packets, if sent, allow the server to tell whether a
668 client is still present and responding. <P>
669 <B>Default:</B> keep alive = 300 <P>
670 <B>Example:</B> keep alive = 60 <P>
672 <H3><A NAME="lm announce">lm announce (G)</A></H3>
673 This parameter determines if Samba will produce Lanman announce broadcasts
674 that are needed by OS/2 clients in order for them to see the Samba server in
675 their browse list. This parameter can have three values, True, False, or Auto.
676 The default is Auto. If set to False Samba will never produce these broadcasts.
677 If set to True Samba will produce Lanman announce broadcasts at a frequency
678 set by the parameter <A HREF="#lm interval">lm interval</A>. If set to Auto
679 Samba will not send Lanman announce broadcasts by default but will listen for
680 them. If it hears such a broadcast on the wire it will then start sending
681 them at a frequency set by the 'lm interval' parameter<P>
682 See also <A HREF="#lm interval">lm interval</A>. <P>
683 <B>Default:</B> lm announce = Auto <P>
684 <B>Example:</B> lm announce = True <P>
686 <H3><A NAME="lm interval">lm interval (G)</A></H3>
687 If Samba is set to produce Lanman announce broadcasts needed by OS/2 clients
688 (see the <A HREF="#lm announce">lm announce</A> parameter) this
689 parameter defines the frequency in seconds with which they will be made.
690 If this is set to zero then no Lanman announcements will be made despite
691 the setting of the <A HREF="#lm announce">lm announce</A> parameter. <P>
692 See also <A HREF="#lm announce">lm announce</A>. <P>
693 <B>Default:</B> lm interval = 60 <P>
694 <B>Example:</B> lm interval = 120 <P>
696 <H3><A NAME="load printers">load printers (G)</A></H3>
697 A boolean variable that controls whether all printers in the printcap
698 will be loaded for browsing by default. <P>
699 <B>Default:</B> load printers = Yes <P>
700 <B>Example:</B> load printers = No <P>
702 <H3><A NAME="local master">local master (G)</A></H3>
703 This option allows nmbd to become a local master browser on a subnet. If set
704 to No then nmbd will not attempt to become a local master browser on a subnet
705 and will also lose in all browsing elections. By default this value is set
706 to Yes. Setting this value to Yes doesn't mean that Samba will become the local
707 master browser on a subnet, just that the nmbd will participate in elections
708 for local master browser. <P>
709 <B>Default:</B> local master = yes <P>
711 <H3><A NAME="lock dir">lock dir (G)</A></H3>
712 This option specifies the directory where lock files will be placed.
713 The lock files are used to implement the
714 <A HREF="#max connections">max connections</A> option. <P>
715 <B>Default:</B> lock dir = /tmp/samba <P>
716 <B>Example:</B> lock dir = /usr/local/samba/var/locks <P>
718 <H3><A NAME="locking">locking (S)</A></H3>
719 This controls whether or not locking will be performed by the server in
720 response to lock requests from the client. <P>
721 If set to No, all lock and unlock requests will appear to succeed and all
722 lock queries will indicate that the queried lock is clear. <P>
723 If set to Yes, real locking will be performed by the server. <P>
724 This option may be particularly useful for read-only filesystems which do not
725 need locking (such as CDROM drives). <P>
726 Be careful about disabling locking either globally or in a specific
727 service, as lack of locking may result in data corruption. <P>
728 <B>Default:</B> locking = Yes <P>
729 <B>Example:</B> locking = No <P>
731 <H3><A NAME="log file">log file (G)</A></H3>
732 This options allows you to override the name of the Samba log file (also
733 known as the debug file). <P>
734 This option takes the standard substitutions, allowing you to have separate
735 log files for each user or machine. <P>
736 <B>Example:</B> log file = /usr/local/samba/var/log.%m <P>
738 <H3><A NAME="log level">log level (G)</A></H3>
739 A synonym for this is debuglevel<P>
740 The value of the parameter (an integer) allows the logging level (debug level)
741 to be specified in the <B>smb.conf</B> file. This is to give greater
742 flexibility in the configuration of the system. <P>
743 The default will be the logging level specified on the command line. <P>
744 <B>Example:</B> log level = 3
746 <H3><A NAME="logon drive">logon drive (G)</A></H3>
747 This parameter specifies the local path to which the home directory will be
748 connected (see <A HREF="#logon home">logon home</A>) and is only used by NT
750 <B>Example:</B> logon drive = h: <P>
752 <H3><A NAME="logon home">logon home (G)</A></H3>
753 This parameter specifies the home directory location when a Win95 or NT
754 Workstation logs into a Samba PDC. It allows you to do "NET USE H: /HOME"
755 from a command prompt, for example. <P>
756 This option takes the standard substitutions, allowing you to have separate
757 logon scripts for each user or machine. <P>
758 <B>Default:</B> logon home = "\\%N\%U" <P>
759 <B>Example:</B> logon home = "\\remote_smb_server\%U" <P>
761 <H3><A NAME="logon path">logon path (G)</A></H3>
762 This parameter specifies the home directory where roaming profiles (USER.DAT
763 / USER.MAN files for Windows 95) are stored. <P>
764 This option takes the standard substitutions, allowing you to have separate
765 logon scripts for each user or machine. It also specifies the directory from
766 which the "desktop", "start menu", "nethood" and "programs" folders, and their
767 contents, are loaded and displayed on your Windows 95 client. <P>
768 The share and the path must be readable by the user for the preferences and
769 directories to be loaded onto the Windows 95 client. The share must be
770 writeable when the user logs in for the first time, in order that the
771 Windows 95 client can create the user.dat and other directories. <P>
772 Thereafter, the directories and any of contents can, if required, be
773 made read-only. It is not adviseable that the USER.DAT file be made read-only
774 - rename it to USER.MAN to achieve the desired effect (a MANdatory profile). <P>
775 Windows clients can sometimes maintain a connection to the [homes] share,
776 even though there is no user logged in. Therefore, it is vital that the
777 logon path does not include a reference to the homes share (i.e
778 \\%N\HOMESprofile_path will cause problems). <P>
779 This option takes the standard substitutions, allowing you to have separate
780 logon scripts for each user or machine. <P>
781 <B>Default:</B> logon path = \\%N\%U\profile <P>
782 <B>Example:</B> logon path = \\PROFILESERVER\HOME_DIR\%U\PROFILE <P>
784 <H3><A NAME="logon script">logon script (G)</A></H3>
785 This parameter specifies the batch file (.bat) or NT command file (.cmd) to
786 be downloaded and run on a machine when a user successfully logs in. The file
787 must contain the DOS style cr/lf line endings. Using a DOS-style editor to
788 create the file is recommended. <P>
789 The script must be a relative path to the [netlogon] service. If the
790 [netlogon] service specifies a path of /usr/local/samba/netlogon, and logon
791 script = STARTUP.BAT, then file that will be downloaded is: <P>
792 <B>/usr/local/samba/netlogon/STARTUP.BAT</B> <P>
793 The contents of the batch file is entirely your choice. A suggested command
794 would be to add NET TIME \\SERVER /SET /YES, to force every machine to
795 synchronise clocks with the same time server. Another use would be to add
796 NET USE U: \\SERVER\UTILS for commonly used utilities, or
797 NET USE Q: \\SERVER\ISO9001_QA. <P>
798 Note that it is particularly important not to allow write access to the
799 [netlogon] share, or to grant users write permission on the batch files
800 in a secure environment, as this would allow the batch files to be arbitrarily
802 This option takes the standard substitutions, allowing you to have separate
803 logon scripts for each user or machine. <P>
804 <B>Example:</B> logon script = scripts/%U.bat <P>
806 <H3><A NAME="lppause command">lppause command (S)</A></H3>
807 This parameter specifies the command to be executed on the server host in
808 order to stop printing or spooling a specific print job. <P>
809 This command should be a program or script which takes a printer name and
810 job number to pause the print job. Currently I don't know of any print spooler
811 system that can do this with a simple option, except for the PPR system from
812 Trinity College (ppr-dist.trincoll.edu/pub/ppr). One way of implementing this
813 is by using job priorities, where jobs having a too low priority won't be
814 sent to the printer. See also
815 <A HREF="#lpresume command">lpresume command</A>.<P>
816 If a %p is given then the printername is put in its place. A %j is replaced
817 with the job number (an integer). On HPUX (see
818 <A HREF="#printing">printing</A>=hpux), if the -p%p
819 option is added to the lpq command, the job will show up with the correct
820 status, i.e. if the job priority is lower than the set fence priority it
821 will have the PAUSED status, whereas if the priority is equal or higher
822 it will have the SPOOLED or PRINTING status. <P>
823 Note that it is good practice to include the absolute path in the lppause
824 command as the PATH may not be available to the server. <P>
825 <B>Default:</B> Currently no default value is given to this string <P>
826 <B>Example for HPUX:</B> lppause command = /usr/bin/lpalt %p-%j -p0 <P>
828 <H3><A NAME="lpq cache time">lpq cache time (G)</A></H3>
829 This controls how long lpq info will be cached for to prevent the lpq command
830 being called too often. A separate cache is kept for each variation of the
831 lpq command used by the system, so if you use different lpq commands for
832 different users then they won't share cache information. <P>
833 The cache files are stored in /tmp/lpq.xxxx where xxxx is a hash of the lpq
835 The default is 10 seconds, meaning that the cached results of a previous
836 identical lpq command will be used if the cached data is less than 10 seconds
837 old. A large value may be advisable if your lpq command is very slow. <P>
838 A value of 0 will disable cacheing completely. <P>
839 <B>Default:</B> lpq cache time = 10 <P>
840 <B>Example:</B> lpq cache time = 30 <P>
842 <H3><A NAME="lpq command">lpq command (S)</A></H3>
843 This parameter specifies the command to be executed on the server host
844 in order to obtain "lpq"-style printer status information. <P>
845 This command should be a program or script which takes a printer name as its
846 only parameter and outputs printer status information. <P>
847 Currently six styles of printer status information are supported; BSD, SYSV,
848 AIX, HPUX, QNX, LPRNG and PLP. This covers most UNIX systems. You control
849 which type is expected using the <A HREF="#printing">printing</A> option. <P>
850 Some clients (notably Windows for Workgroups) may not correctly send the
851 connection number for the printer they are requesting status information
852 about. To get around this, the server reports on the first printer service
853 connected to by the client. This only happens if the connection number sent
855 If a %p is given then the printername is put in its place. Otherwise it is
856 placed at the end of the command. <P>
857 Note that it is good practice to include the absolute path in the lpq
858 command as the PATH may not be available to the server. <P>
859 <B>Default:</B> depends on the setting of <A HREF="#printing">printing</A><P>
860 <B>Example:</B> lpq command = /usr/bin/lpq %p <P>
862 <H3><A NAME="lpresume command">lpresume command (S)</A></H3>
863 This parameter specifies the command to be executed on the server host in
864 order to restart or continue printing or spooling a specific print job. <P>
865 This command should be a program or script which takes a printer name and
866 job number to resume the print job. See also the
867 <A HREF="#lppause command">lppause command</A>. <P>
868 If a %p is given then the printername is put in its place.
869 A %j is replaced with the job number (an integer). <P>
870 Note that it is good practice to include the absolute path in the lpresume
871 command as the PATH may not be available to the server. <P>
872 <B>Default:</B> Currently no default value is given to this string <P>
873 <B>Example for HPUX:</B> lpresume command = /usr/bin/lpalt %p-%j -p2 <P>
875 <H3><A NAME="lprm command">lprm command (S)</A></H3>
876 This parameter specifies the command to be executed on the server host in
877 order to delete a print job. <P>
878 This command should be a program or script which takes a printer name
879 and job number, and deletes the print job. <P>
880 Currently seven styles of printer control are supported; BSD, SYSV, AIX HPUX,
881 QNX, LPRNG and PLP. This covers most UNIX systems. You control which type is
882 expected using the <A HREF="#printing">printing</A> option. <P>
883 If a %p is given then the printername is put in its place. A
884 %j is replaced with the job number (an integer). <P>
885 Note that it is good practice to include the absolute path in the lprm
886 command as the PATH may not be available to the server. <P>
887 <B>Default:</B> depends on the setting of <A HREF="#printing">printing</A><P>
888 <B>Example 1:</B>lprm command = /usr/bin/lprm -P%p %j <P>
889 <B>Example 2:</B>lprm command = /usr/bin/cancel %p-%j <P>
891 <H3><A NAME="magic output">magic output (S)</A></H3>
892 This parameter specifies the name of a file which will contain output
893 created by a magic script (see <A HREF="#magic script">magic script</A>
895 Warning: If two clients use the same magic script in the same directory the
896 output file content is undefined. <P>
897 <B>Default:</B> magic output = <magic script name>.out <P>
898 <B>Example:</B> magic output = myfile.txt <P>
900 <H3><A NAME="magic script">magic script (S)</A></H3>
901 This parameter specifies the name of a file which, if opened, will be
902 executed by the server when the file is closed. This allows a UNIX script to
903 be sent to the Samba host and executed on behalf of the connected user. <P>
904 Scripts executed in this way will be deleted upon completion, permissions
906 If the script generates output, output will be sent to the file specified by
907 the <A HREF="#magic output">magic output</A> parameter. <P>
908 Note that some shells are unable to interpret scripts containing
909 carriage-return-linefeed instead of linefeed as the end-of-line marker. Magic
910 scripts must be executable "as is" on the host, which for some hosts and
911 some shells will require filtering at the DOS end. <P>
912 Magic scripts are EXPERIMENTAL and should NOT be relied upon. <P>
913 <B>Default:</B> None. Magic scripts disabled. <P>
914 <B>Example:</B> magic script = user.csh <P>
916 <H3><A NAME="mangle case">mangle case (S)</A></H3>
917 Controls if names that have characters that aren't of the "default" case are
919 See the section on <A HREF="#NAME MANGLING">NAME MANGLING</A> <P>
921 <H3><A NAME="mangled map">mangled map (S)</A></H3>
922 This is for those who want to directly map UNIX file names which are not
923 representable on DOS. The mangling of names is not always what is needed. In
924 particular you may have documents with file extensions that differ between
925 DOS and UNIX. For example, under UNIX it is common to use .html for HTML
926 files, whereas under DOS .htm is more commonly used. <P>
927 So to map 'html' to 'htm' you put: <P>
928 mangled map = (*.html *.htm) <P>
929 One very useful case is to remove the annoying ;1 off the ends of filenames
930 on some CDROMS (only visible under some UNIXes). To do this use a map of
932 <B>default:</B> no mangled map <P>
933 <B>Example:</B> mangled map = (*;1 *) <P>
935 <H3><A NAME="mangled names">mangled names (S)</A></H3>
936 This controls whether non-DOS names under UNIX should be mapped
937 to DOS-compatible names ("mangled") and made visible, or whether non-DOS
938 names should simply be ignored. <P>
939 See the section on <A HREF="#NAME MANGLING">NAME MANGLING</A> for
940 details on how to control the mangling process. <P>
941 If mangling is used then the mangling algorithm is as follows:
942 <blockquote>- the first (up to) five alphanumeric characters before the
943 rightmost dot of the filename are preserved, forced to upper case, and appear
944 as the first (up to) five characters of the mangled name. <P>
945 - a tilde ("~") is appended to the first part of the mangled name, followed
946 by a two-character unique sequence, based on the original root name (i.e.,
947 the original filename minus its final extension). The final
948 extension is included in the hash calculation only if it contains any
949 upper case characters or is longer than three characters. <P>
950 Note that the character to use may be specified using the
951 <A HREF="#mangling char">mangling char</A> option, if you don't like ~. <P>
952 - the first three alphanumeric characters of the final
953 extension are preserved, forced to upper case and appear as the extension
954 of the mangled name. The final extension is defined as that part of the
955 original filename after the rightmost dot. If there are no dots in the
956 filename, the mangled name will have no extension (except in the case
957 of hidden files - see below). <P>
958 - files whose UNIX name begins with a dot will be presented as DOS hidden
959 files. The mangled name will be created as for other filenames, but with the
960 leading dot removed and "___" as its extension regardless of actual original
961 extension (that's three underscores).
963 The two-digit hash value consists of upper case alphanumeric characters. <P>
964 This algorithm can cause name collisions only if files in a directory
965 share the same first five alphanumeric characters. The probability of such
966 a clash is 1/1300. <P>
967 The name mangling (if enabled) allows a file to be copied between UNIX
968 directories from DOS while retaining the long UNIX filename. UNIX files can
969 be renamed to a new extension from DOS and will retain the same basename.
970 Mangled names do not change between sessions. <P>
971 <B>Default:</B> mangled names = Yes <P>
972 <B>Example:</B> mangled names = No <P>
974 <H3><A NAME="mangling char">mangling char (S)</A></H3>
975 This controls what character is used as the "magic" character
976 in name mangling. The default is a ~ but this may interfere with some software.
977 Use this option to set it to whatever you prefer. <P>
978 <B>Default:</B> mangling char = ~ <P>
979 <B>Example:</B> mangling char = ^ <P>
981 <H3><A NAME="mangled stack">mangled stack (G)</A></H3>
982 This parameter controls the number of mangled names that should be cached in
983 the Samba server. <P>
984 This stack is a list of recently mangled base names (extensions are only
985 maintained if they are longer than 3 characters or contains upper case
987 The larger this value, the more likely it is that mangled
988 names can be successfully converted to correct long UNIX names. However,
989 large stack sizes will slow most directory access. Smaller stacks save
990 memory in the server (each stack element costs 256 bytes). <P>
991 It is not possible to absolutely guarantee correct long file names, so be
992 prepared for some surprises! <P>
993 <B>Default:</B> mangled stack = 50 <P>
994 <B>Example:</B> mangled stack = 100 <P>
996 <H3><A NAME="map archive">map archive (S)</A></H3>
997 This controls whether the DOS archive attribute should
998 be mapped to the UNIX owner execute bit. The DOS archive bit is set when
999 a file has been modified since its last backup. One motivation for this
1000 option it to keep Samba/your PC from making any file it touches from becoming
1001 executable under UNIX. This can be quite annoying for shared source code,
1002 documents, etc... <P>
1003 Note that this requires the 'create mask' to be set such
1004 that owner execute bit is not masked out (ie. it must include 100). See
1005 the parameter <A HREF="#create mask">create mask</A> for details. <P>
1006 <B>Default:</B> map archive = Yes <P>
1007 <B>Example:</B> map archive = No <P>
1009 <H3><A NAME="map hidden">map hidden (S)</A></H3>
1010 This controls whether DOS style hidden files should be mapped to the UNIX
1011 world execute bit. <P>
1012 Note that this requires the 'create mask' to be set such that the world
1013 execute bit is not masked out (ie. it must include 001). See the parameter
1014 <A HREF="#create mask">create mask</A> for details. <P>
1015 <B>Default:</B> map hidden = No <P>
1016 <B>Example:</B> map hidden = Yes <P>
1018 <H3><A NAME="map system">map system (S)</A></H3>
1019 This controls whether DOS style system files should be mapped to the UNIX
1020 group execute bit. <P>
1021 Note that this requires the 'create mask' to be set such that the group
1022 execute bit is not masked out (ie. it must include 010). See the parameter
1023 <A HREF="#create mask">create mask</A> for details. <P>
1024 <B>Default:</B> map system = No <P>
1025 <B>Example:</B> map system = Yes <P>
1027 <H3><A NAME="max connections">max connections (S)</A></H3>
1028 This option allows the number of simultaneous connections to a service to be
1029 limited. If "max connections" is greater than 0 then connections will be
1030 refused if this number of connections to the service are already open. A value
1031 of zero mean an unlimited number of connections may be made. <P>
1032 Record lock files are used to implement this feature. The lock files will be
1033 stored in the directory specified by the
1034 <A HREF="#lock dir">lock dir</A> option. <P>
1035 <B>Default:</B> max connections = 0 <P>
1036 <B>Example:</B> max connections = 10 <P>
1038 <H3><A NAME="max disk size">max disk size (G)</A></H3>
1039 This option allows you to put an upper limit on the apparent size of disks.
1040 If you set this option to 100 then all shares will appear to be not larger
1041 than 100 MB in size. <P>
1042 Note that this option does not limit the amount of data you can put on the
1043 disk. In the above case you could still store much more than 100 MB on the
1044 disk, but if a client ever asks for the amount of free disk space or the
1045 total disk size then the result will be bounded by the amount specified in
1046 "max disk size". <P>
1047 This option is primarily useful to work around bugs in some pieces of
1048 software that can't handle very large disks, particularly disks over 1GB in
1050 A "max disk size" of 0 means no limit. <P>
1051 <B>Default:</B> max disk size = 0 <P>
1052 <B>Example:</B> max disk size = 1000 <P>
1054 <H3><A NAME="max log size">max log size (G)</A></H3>
1055 This option (an integer in kilobytes) specifies the max size
1056 the log file should grow to. Samba periodically checks the size and if
1057 it is exceeded it will rename the file, adding a .old extension. <P>
1058 A size of 0 means no limit. <P>
1059 <B>Default:</B> max log size = 5000 <P>
1060 <B>Example:</B> max log size = 1000 <P>
1062 <H3><A NAME="max mux">max mux (G)</A></H3>
1063 This option controls the maximum number of outstanding simultaneous SMB
1064 operations that samba tells the client it will allow. You should never need
1065 to set this parameter. <P>
1066 <B>Default:</B> max mux = 50 <P>
1068 <H3><A NAME="max packet">max packet (G)</A></H3>
1069 A synonym for this parameter is 'packet size'. <P>
1070 The maximum transmit packet size during a raw read. This option is no longer
1071 implemented as of version 1.7.00, and is kept only so old configuration files
1072 do not become invalid. <P>
1074 <H3><A NAME="max ttl">max ttl (G)</A></H3>
1075 This option tells nmbd what the default 'time to live' of NetBIOS names should
1076 be (in seconds) when nmbd is requesting a name using either a broadcast
1077 or from a WINS server. You should never need to change this parameter. <P>
1078 <B>Default:</B> max ttl = 14400 <P>
1080 <H3><A NAME="max wins ttl">max wins ttl (G)</A></H3>
1081 This option tells nmbd when acting as a WINS server
1082 (<A HREF="#wins support">wins support</A> = Yes) what the maximum 'time to
1083 live' of NetBIOS names that nmbd will grant will be (in seconds). You should
1084 never need to change this parameter. The default is 3 days (259200
1086 <B>Default:</B> max wins ttl = 259200 <P>
1088 <H3><A NAME="max xmit">max xmit (G)</A></H3>
1089 This option controls the maximum packet size that will be negotiated by
1090 Samba. The default is 65535, which is the maximum. In some cases you may find
1091 you get better performance with a smaller value. A value below 2048 is likely
1092 to cause problems. <P>
1093 <B>Default:</B> max xmit = 65535 <P>
1094 <B>Example:</B> max xmit = 8192 <P>
1096 <H3><A NAME="message command">message command (G)</A></H3>
1097 This specifies what command to run when the server receives a WinPopup style
1099 This would normally be a command that would deliver the message somehow.
1100 How this is to be done is up to your imagination. <P>
1102 message command = csh -c 'xedit %s;rm %s' & <P>
1103 This delivers the message using xedit, then removes it afterwards. NOTE
1104 THAT IT IS VERY IMPORTANT THAT THIS COMMAND RETURN IMMEDIATELY. That's why
1105 I have the & on the end. If it doesn't return immediately then your PCs may
1106 freeze when sending messages (they should recover after 30secs, hopefully). <P>
1107 All messages are delivered as the global guest user. The command takes
1108 the standard substitutions, although %u won't work (%U may be better in
1110 Apart from the standard substitutions, some additional ones apply. In
1112 %s = the filename containing the message <P>
1113 %t = the destination that the message was sent to (probably the server name) <P>
1114 %f = who the message is from <P>
1115 You could make this command send mail, or whatever else takes your fancy.
1116 Please let me know of any really interesting ideas you have. <P>
1117 Here's a way of sending the messages as mail to root: <P>
1118 message command = /bin/mail -s 'message from %f on %m' root < %s; rm %s <P>
1119 If you don't have a message command then the message won't be delivered and
1120 Samba will tell the sender there was an error. Unfortunately WfWg totally
1121 ignores the error code and carries on regardless, saying that the message was
1123 If you want to silently delete it then try "message command = rm %s". <P>
1124 For the really adventurous, try something like this: <P>
1125 message command = csh -c 'csh < %s |& /usr/local/samba/bin/smbclient \
1126 -M %m; rm %s' & <P>
1127 this would execute the command as a script on the server,
1128 then give them the result in a WinPopup message. Note that this could cause
1129 a loop if you send a message from the server using smbclient! You better
1130 wrap the above in a script that checks for this :-) <P>
1131 <B>Default:</B> no message command <P>
1132 <B>Example:</B> message command = csh -c 'xedit %s;rm %s' & <P>
1134 <H3><A NAME="min print space">min print space (S)</A></H3>
1135 This sets the minimum amount of free disk space that must
1136 be available before a user will be able to spool a print job. It is specified
1137 in kilobytes. The default is 0, which means no limit. <P>
1138 <B>Default:</B> min print space = 0 <P>
1139 <B>Example:</B> min print space = 2000 <P>
1141 <H3><A NAME="min wins ttl">min wins ttl (G)</A></H3>
1142 This option tells nmbd when acting as a WINS server
1143 (<A HREF="#wins support">wins support</A> = Yes) what the
1144 minimum 'time to live' of NetBIOS names that nmbd will grant will be (in
1145 seconds). You should never need to change this parameter. The default is
1146 6 hours (21600 seconds). <P>
1147 <B>Default:</B> min wins ttl = 21600 <P>
1149 <H3><A NAME="name resolve order">name resolve order (G)</A></H3>
1150 This option is used by the programs smbd, nmbd and smbclient
1151 to determine what naming services and in what order to resolve host names
1152 to IP addresses. This option is most useful in smbclient. The option takes
1153 a space separated string of different name resolution options. These are
1154 "lmhosts", "host", "wins" and "bcast". They cause names to be resolved
1157 lmhosts Lookup an IP address in the Samba lmhosts file.
1158 host Do a standard host name to IP address resolution, using the
1159 system /etc/hosts, NIS, or DNS lookups. This method of name
1160 resolution is operating system depended (for instance on Solaris
1161 this may be controlled by the /etc/nsswitch.conf file).
1162 wins Query a name with the IP address listed in the "wins server ="
1163 parameter. If no WINS server has been specified this method will
1165 bcast Do a broadcast on each of the known local
1166 interfaces listed in the "interfaces =" parameter. This is the
1167 least reliable of the name resolution methods as it depends
1168 on the target host being on a locally connected subnet.
1170 The default order is lmhosts, host, wins, bcast and these name resolution
1171 methods will be attempted in this order. <P>
1172 This option was first introduced in Samba 1.9.18p4. <P>
1173 <B>Default:</B> name resolve order = lmhosts host wins bcast <P>
1174 <B>example:</B> name resolve order = lmhosts bcast host <P>
1175 This will cause the local lmhosts file to be examined first, followed by a
1176 broadcast attempt, followed by a normal system hostname lookup. <P>
1178 <H3><A NAME="netbios aliases">netbios aliases (G)</A></H3>
1179 This is a list of names that nmbd will advertise as additional names by which
1180 the Samba server is known. This allows one machine to appear in browse
1181 lists under multiple names. If a machine is acting as a browse server or
1182 logon server none of these names will be advertised as either browse server
1183 or logon servers, only the primary name of the machine will be advertised
1184 with these capabilities. <P>
1185 See also <A HREF="#netbios name">netbios name</A>. <P>
1186 <B>Example:</B>netbios aliases = TEST TEST1 TEST2 <P>
1188 <H3><A NAME="netbios name">netbios name (G)</A></H3>
1189 This sets the NetBIOS name by which a Samba server is known. By default it is
1190 the same as the first component of the host's DNS name. If a machine is a
1191 browse server or logon server this name (or the first component of the hosts
1192 DNS name) will be the name that these services are advertised under. <P>
1193 See also <A HREF="#netbios aliases">netbios aliases</A>. <P>
1194 <B>Example:</B> netbios name = MYNAME <P>
1196 <H3><A NAME="NIS homedir">NIS homedir (G)</A></H3>
1197 Get the home share server from a NIS (or YP) map. For unix systems that use
1198 an automounter, the user's home directory will often be mounted on a
1199 workstation on demand from a remote server. When the Samba logon server is
1200 not the actual home directory server, two network hops are required to access
1201 the home directory and this can be very slow especially with writing via
1202 Samba to an NFS mounted directory. This option allows samba to return the
1203 home share as being on a different server to the logon server and as long as
1204 a samba daemon is running on the home directory server, it will be mounted
1205 on the Samba client directly from the directory server. When Samba is
1206 returning the home share to the client, it will consult the NIS (or YP) map
1207 specified in <A HREF="#homedir map">homedir map</A> and return the server
1209 <B>Default:</B> NIS homedir = No <P>
1210 <B>Example:</B> NIS homedir = Yes <P>
1212 <H3><A NAME="networkstation user login">networkstation user login (G)</A></H3>
1213 This global parameter (new for 1.9.18p3) affects server level security. With
1214 this set (recommended) samba will do a full NetWkstaUserLogon to confirm that
1215 the client really should have login rights. This can cause problems with
1216 machines in trust relationships in which case you can disable it here,
1217 but be warned, we have heard that some NT machines will then allow anyone
1218 in with any password! Make sure you test it. <P>
1219 <B>Default:</B> networkstation user login = Yes <P>
1220 <B>Example:</B> networkstation user login = No <P>
1222 <H3><A NAME="null passwords">null passwords (G)</A></H3>
1223 Allow or disallow access to accounts that have null passwords. <P>
1224 <B>Default:</B> null passwords = No <P>
1225 <B>Example:</B> null passwords = Yes <P>
1227 <H3><A NAME="only user">only user (S)</A></H3>
1228 This is a boolean option that controls whether connections with usernames not
1229 in the <A HREF="#username">username</A> list will be allowed. By default this
1230 option is disabled so a client can supply a username to be used by the
1232 Note that this also means Samba won't try to deduce usernames from the
1233 service name. This can be annoying for the [homes] section. To get around
1234 this you could use "<A HREF="#username">username</A> = %S" which means your
1235 "username" list will be just the service name, which for home directories
1236 is the name of the user. <P>
1237 <B>Default: </B> only user = No <P>
1238 <B>Example: </B> only user = Yes <P>
1240 <H3><A NAME="oplocks">oplocks (S)</A></H3>
1241 This boolean option tells smbd whether to issue oplocks (opportunistic locks)
1242 to file open requests on this share. The oplock code
1243 was introduced in Samba 1.9.18 and can dramatically (approx 30% or more)
1244 improve the speed of access to files on Samba servers. It allows the clients
1245 to agressively cache files locally and you may want to disable this option
1246 for unreliable network environments (it is turned on by default in Windows
1247 NT Servers). For more information see the file Speed.txt in the Samba docs/
1249 Oplocks may be selectively turned off on certain files on a per share basis.
1250 See the <A HREF="#veto oplock files">veto oplock files</A> parameter. <P>
1251 <B>Default:</B> oplocks = Yes <P>
1252 <B>Example:</B> oplocks = No <P>
1254 <H3><A NAME="os level">os level (G)</A></H3>
1255 This integer value controls what level Samba advertises itself as for browse
1256 elections. See BROWSING.txt for details. <P>
1258 <H3><A NAME="passwd chat debug">passwd chat debug (G)</A></H3>
1259 This boolean specifies if the passwd chat script parameter is run
1260 in 'debug' mode. In this mode the strings passed to and received from the
1261 passwd chat are printed in the smbd log with a debug level of 100. This
1262 is a dangerous option as it will allow plaintext passwords to be seen
1263 in the smbd log. It is available to help Samba admins debug their passwd
1264 chat scripts and should be turned off after this has been done. This parameter
1265 is off by default. <P>
1266 <B>Example:</B> passwd chat debug = Yes <P>
1267 <B>Default:</B> passwd chat debug = No <P>
1269 <H3><A NAME="passwd chat">passwd chat (G)</A></H3>
1270 This string controls the "chat" conversation that takes places
1271 between smbd and the local password changing program to change the users
1272 password. The string describes a sequence of response-receive pairs that
1273 smbd uses to determine what to send to the passwd program and what to
1274 expect back. If the expected output is not received then the password is
1276 This chat sequence is often quite site specific, depending
1277 on what local methods are used for password control (such as NIS+ etc). <P>
1278 The string can contain the macros %o and %n which are substituted for
1279 the old and new passwords respectively. It can also contain the standard
1280 macros \n \r \t and \s to give line-feed, carriage-return, tab and space. <P>
1281 The string can also contain a * which matches any sequence of characters. <P>
1282 Double quotes can be used to collect strings with spaces in them into
1283 a single string. <P>
1284 If the send string in any part of the chat sequence is
1285 a fullstop "." then no string is sent. Similarly, is the expect string is
1286 a fullstop then no string is expected. <P>
1287 <B>Default:</B> passwd chat = *old*password* %o\n *new*password* %n\n *new*password* %n\n *changed* <P>
1288 <B>Example:</B> passwd chat = "*Enter OLD password*" %o\n "*Enter NEW password*" %n\n \
1289 "*Reenter NEW password*" %n\n "*Password changed*" <P>
1291 <H3><A NAME="passwd program">passwd program (G)</A></H3>
1292 The name of a program that can be used to set user passwords. <P>
1293 This is only necessary if you have enabled remote password changing at
1294 compile time. Any occurrences of %u will be replaced with the user name. <P>
1295 Also note that many passwd programs insist in "reasonable"
1296 passwords, such as a minimum length, or the inclusion of mixed case chars
1297 and digits. This can pose a problem as some clients (such as Windows for
1298 Workgroups) uppercase the password before sending it. <P>
1299 <B>Default:</B> passwd program = /bin/passwd <P>
1300 <B>Example:</B> passwd program = /sbin/passwd %u <P>
1302 <H3><A NAME="password level">password level (G)</A></H3>
1303 Some client/server combinations have difficulty with mixed-case
1304 passwords. One offending client is Windows for Workgroups, which for some
1305 reason forces passwords to upper case when using the LANMAN1 protocol,
1306 but leaves them alone when using COREPLUS! <P>
1307 This parameter defines the maximum number of characters that may be upper
1308 case in passwords. <P>
1309 For example, say the password given was "FRED". If password level is set to
1310 1 (one), the following combinations would be tried if "FRED" failed: "Fred",
1311 "fred", "fRed", "frEd", "freD". If password level was set to 2 (two), the
1312 following combinations would also be tried: "FRed", "FrEd", "FreD", "fREd",
1313 "fReD", "frED". And so on. <P>
1314 The higher value this parameter is set to the more likely it is that a mixed
1315 case password will be matched against a single case password. However, you
1316 should be aware that use of this parameter reduces security and increases the
1317 time taken to process a new connection. <P>
1318 A value of zero will cause only two attempts to be made - the password
1319 as is and the password in all-lower case. <P>
1320 If you find the connections are taking too long with this option then you
1321 probably have a slow crypt() routine. Samba now comes with a fast "ufc crypt"
1322 that you can select in the Makefile. You should also make sure the
1323 PASSWORD_LENGTH option is correct for your system in local.h and includes.h.
1324 On most systems only the first 8 chars of a password are significant so
1325 PASSWORD_LENGTH should be 8, but on some longer passwords are significant.
1326 The includes.h file tries to select the right length for your system. <P>
1327 <B>Default:</B> password level = 0 <P>
1328 <B>Example:</B> password level = 4 <P>
1330 <H3><A NAME="password server">password server (G)</A></H3>
1331 By specifying the name of another SMB server (such as a WinNT box) with this
1332 option, and using "<A HREF="#security">security</A> = server" you can get
1333 Samba to do all its username/password validation via a remote server. <P>
1334 This options sets the name of the password server to use. It must be a netbios
1335 name, so if the machine's netbios name is different from its internet name
1336 then you may have to add its netbios name to /etc/hosts. <P>
1337 Note that with Samba 1.9.18p4 and above the name of the password server is
1338 looked up using the <A HREF="#name resolve order">name resolve order</A>
1339 parameter and so may resolved by any method and order described in that
1341 The password server much be a machine capable of using the "LM1.2X002"
1342 or the "LM NT 0.12" protocol, and it must be in user level security mode. <P>
1343 NOTE: Using a password server means your UNIX box (running Samba) is
1344 only as secure as your password server. DO NOT CHOOSE A PASSWORD SERVER
1345 THAT YOU DON'T COMPLETELY TRUST. <P>
1346 Never point a Samba server at itself for password serving. This will cause a
1347 loop and could lock up your Samba server! <P>
1348 The name of the password server takes the standard substitutions, but
1349 probably the only useful one is %m, which means the Samba server will
1350 use the incoming client as the password server. If you use this then you
1351 better trust your clients, and you better restrict them with
1352 <A HREF="#hosts allow">hosts allow</A>! <P>
1353 If you list several hosts in the "password server" option then smbd will
1354 try each in turn till it finds one that responds. This is useful in case
1355 your primary server goes down. <P>
1356 If you are using a WindowsNT server as your password server then you will
1357 have to ensure that your users are able to login from the Samba server, as
1358 the network logon will appear to come from there rather than from the users
1361 <H3><A NAME="path">path (S)</A></H3>
1362 A synonym for this parameter is "directory". <P>
1363 This parameter specifies a directory to which the user of the service is to
1364 be given access. In the case of printable services, this is where print data
1365 will spool prior to being submitted to the host for printing. <P>
1366 For a printable service offering guest access, the service should be readonly
1367 and the path should be world-writable and have the sticky bit set. This is
1368 not mandatory of course, but you probably won't get the results you expect if
1369 you do otherwise. <P>
1370 Any occurrences of %u in the path will be replaced with the username that the
1371 client is connecting as. Any occurrences of %m will be replaced by the name
1372 of the machine they are connecting from. These replacements are very useful
1373 for setting up pseudo home directories for users. <P>
1374 Note that this path will be based on
1375 <A HREF="#root directory">root directory</A> if one was specified.<P>
1376 <B>Default:</B> none <P>
1377 <B>Example:</B> path = /home/fred <P>
1379 <H3><A NAME="postexec">postexec (S)</A></H3>
1380 This option specifies a command to be run whenever the
1381 service is disconnected. It takes the usual substitutions. The command may
1382 be run as the root on some systems. <P>
1383 An interesting example may be do unmount server resources: <P>
1384 postexec = /etc/umount /cdrom <P>
1385 See also <A HREF="#preexec">preexec</A> <P>
1386 <B>Default:</B> none (no command executed) <P>
1387 <B>Example:</B> postexec = echo \"%u disconnected from %S from %m (%I)\" >> /tmp/log <P>
1389 <H3><A NAME="postscript">postscript (S)</A></H3>
1390 This parameter forces a printer to interpret the print files as postscript.
1391 This is done by adding a %! to the start of print output. <P>
1392 This is most useful when you have lots of PCs that persist in putting a
1393 control-D at the start of print jobs, which then confuses your printer. <P>
1394 <B>Default:</B> postscript = No <P>
1395 <B>Example:</B> postscript = Yes <P>
1397 <H3><A NAME="preferred master">preferred master (G)</A></H3>
1398 This boolean parameter controls if Samba is a preferred master browser for
1399 its workgroup. If this is set to Yes, on startup, samba will force an
1400 election, and it will have a slight advantage in winning the election.
1401 It is recommended that this parameter is used in conjunction with
1402 <A HREF="#domain master">domain master</A> = yes, so that samba can guarantee
1403 becoming a domain master. <P>
1404 Use this option with caution, because if there are several hosts (whether
1405 samba servers, Windows 95 or NT) that are preferred master browsers on
1406 the same subnet, they will each periodically and continuously attempt
1407 to become the local master browser. This will result in unnecessary broadcast
1408 traffic and reduced browsing capabilities. <P>
1409 See <A HREF="#os level">os level</A> = nn <P>
1410 <B>Default:</B> preferred master = no <P>
1412 <H3><A NAME="preload">preload</A></H3>
1413 An alias is "auto services". This is a list of services that you want to be
1414 automatically added to the browse lists. This is most useful for homes and
1415 printers services that would otherwise not be visible. <P>
1416 Note that if you just want all printers in your printcap file loaded then the
1417 <A HREF="#load printers">load printers</A> option is easier. <P>
1418 <B>Default:</B> no preloaded services <P>
1419 <B>Example:</B> preload = fred lp colorlp <P>
1421 <H3><A NAME="preserve case">preserve case (S)</A></H3>
1422 This controls if new filenames are created with the case that
1423 the client passes, or if they are forced to be the "default" case. <P>
1424 <B>Default:</B> preserve case = no <P>
1425 See the section on <A HREF="#NAME MANGLING">NAME MANGLING</A> for a fuller
1428 <H3><A NAME="print command">print command (S)</A></H3>
1429 After a print job has finished spooling to a service, this command will be
1430 used via a system() call to process the spool file. Typically the command
1431 specified will submit the spool file to the host's printing subsystem, but
1432 there is no requirement that this be the case. The server will not remove
1433 the spool file, so whatever command you specify should remove the spool file
1434 when it has been processed, otherwise you will need to manually remove old
1436 The print command is simply a text string. It will be used verbatim, with
1437 two exceptions: All occurrences of "%s" will be replaced by the appropriate
1438 spool file name, and all occurrences of "%p" will be replaced by the
1439 appropriate printer name. The spool file name is generated automatically by
1440 the server, the <A HREF="#printer name">printer name</A> is discussed below. <P>
1441 The full path name will be used for the filename if %s is not preceded by a
1442 /. If you don't like this (it can stuff up some lpq output) then use %f
1443 instead. Any occurrences of %f get replaced by the spool filename without
1444 the full path at the front. <P>
1445 The print command MUST contain at least one occurrence of "%s" or %f -
1446 the "%p" is optional. At the time a job is submitted, if no printer name is
1447 supplied the "%p" will be silently removed from the printer command. <P>
1448 If specified in the [global] section, the print command given will be used for
1449 any printable service that does not have its own print command specified.<P>
1450 If there is neither a specified print command for a printable service nor a
1451 global print command, spool files will be created but not processed and (most
1452 importantly) not removed. <P>
1453 Note that printing may fail on some UNIXes from the "nobody" account. If this
1454 happens then create an alternative guest account that can print and set the
1455 <A HREF="#guest account">guest account</A> in the [global] section. <P>
1456 You can form quite complex print commands by realising that they are
1457 just passed to a shell. For example the following will log a print job,
1458 print the file, then remove it. Note that ; is the usual separator for
1459 command in shell scripts. <P>
1460 print command = echo Printing %s >> /tmp/print.log; lpr -P %p %s; rm %s<P>
1461 You may have to vary this command considerably depending on how you normally
1462 print files on your system. <P>
1463 <B>Default:</B> print command = lpr -r -P %p %s <P>
1464 <B>Example:</B>print command = /usr/local/samba/bin/myprintscript %p %s <P>
1466 <H3><A NAME="print ok">print ok (S)</A></H3>
1467 A synonym for this parameter is 'printable'. <P>
1468 If this parameter is 'Yes', then clients may open, write to
1469 and submit spool files on the directory specified for the service. <P>
1470 Note that a printable service will ALWAYS allow writing to the service path
1471 (user privileges permitting) via the spooling of print data. The
1472 <A HREF="#read only">read only</A> parameter controls only non-printing
1473 access to the resource. <P>
1474 <B>Default:</B> print ok = No <P>
1475 <B>Example:</B> print ok = Yes <P>
1477 <H3><A NAME="printcap name">printcap name (G)</A></H3>
1478 This parameter may be used to override the compiled-in default printcap name
1479 used by the server (usually /etc/printcap). On SystemV systems that
1480 use lpstat to list available printers you can use "printcap name = lpstat"
1481 to automatically obtain lists of available printers. This is the default
1482 for systems that define SYSV at compile time in Samba (this includes
1483 most SystemV based systems). If "printcap name" is set to lpstat on these
1484 systems then Samba will launch "lpstat -v" and attempt to parse the output
1485 to obtain a printer list. <P>
1486 A minimal printcap file would look something like this: <P>
1487 print1|My Printer 1 <BR>
1488 print2|My Printer 2 <BR>
1489 print3|My Printer 3 <BR>
1490 print4|My Printer 4 <BR>
1491 print5|My Printer 5 <P>
1492 where the | separates aliases of a printer. The fact that the second alias
1493 has a space in it gives a hint to Samba that it's a comment. <P>
1494 NOTE: Under AIX the default printcap name is "/etc/qconfig".
1495 Samba will assume the file is in AIX "qconfig" format if the string "/qconfig"
1496 appears in the printcap filename. <P>
1497 <B>Default:</B> printcap name = /etc/printcap <P>
1498 <B>Example:</B> printcap name = /etc/myprintcap <P>
1500 <H3><A NAME="printer driver">printer driver (S)</A></H3>
1501 This option allows you to control the string that clients receive when they
1502 ask the server for the printer driver associated with a printer. If you are
1503 using Windows95 or WindowsNT then you can use this to automate the setup of
1504 printers on your system. <P>
1505 You need to set this parameter to the exact string (case sensitive) that
1506 describes the appropriate printer driver for your system. If you don't know
1507 the exact string to use then you should first try with no "printer driver"
1508 option set and the client will give you a list of printer drivers. The
1509 appropriate strings are shown in a scrollbox after you have chosen the
1510 printer manufacturer. <P>
1511 <B>Example:</B> printer driver = HP LaserJet 4L <P>
1513 <H3><A NAME="printer name">printer name (S)</A></H3>
1514 A synonym for this parameter is 'printer'. <P>
1515 This parameter specifies the name of the printer to which print jobs spooled
1516 through a printable service will be sent. <P>
1517 If specified in the [global] section, the printer name given will be used for
1518 any printable service that does not have its own printer name specified. <P>
1519 <B>Default:</B> none (but may be 'lp' on many systems) <P>
1520 <B>Example:</B> printer name = laserwriter <P>
1522 <H3><A NAME="printer driver file">printer driver file (G)</A></H3>
1523 This parameter tells Samba where the printer driver definition file, used
1524 when serving drivers to Windows 95 clients, is to be found. If this is not
1525 set, the default is : <P>
1526 SAMBA_INSTALL_DIRECTORY/lib/printers.def <P>
1527 This file is created from Windows 95 'msprint.def' files found on the Windows
1528 95 client system. For more details on setting up serving of printer drivers
1529 to Windows 95 clients, see the documentation file docs/PRINTER_DRIVER.txt. <P>
1530 <B>Default:</B> None (set in compile). <P>
1531 <B>Example:</B> printer driver file = /usr/local/samba/printers/drivers.def <P>
1533 <A HREF="#printer driver location">printer driver location</A> <P>
1535 <H3><A NAME="printer driver location">printer driver location (S)</A></H3>
1536 This parameter tells clients of a particular printer share where to find the
1537 printer driver files for the automatic installation of drivers for Windows 95
1538 machines. If Samba is set up to serve printer drivers to Windows 95 machines,
1539 this should be set to <P>
1540 \\MACHINE\PRINTER$ <P>
1541 Where MACHINE is the NetBIOS name of your Samba
1542 server, and PRINTER$ is a share you set up for serving printer driver
1543 files. For more details on setting this up see the documentation file
1544 docs/PRINTER_DRIVER.txt. <P>
1545 <B>Default:</B> None <P>
1546 <B>Example:</B> printer driver location = \\MACHINE\PRINTER$ <P>
1548 <A HREF="#printer driver file">printer driver file</A><P>
1550 <H3><A NAME="printing">printing (S)</A></H3>
1551 This parameters controls how printer status information is interpreted
1552 on your system, and also affects the default values for the
1553 <A HREF="#print command">print command</A>,
1554 <A HREF="#lpq command">lpq command</A> and
1555 <A HREF="#lprm command">lprm command</A>. <P>
1556 Currently six printing styles are supported. They are bsd, sysv, hpux, aix,
1558 To see what the defaults are for the other print commands when using these
1559 options use the "testparm" program. <P>
1560 As of version 1.9.18 of Samba this option can be set on a per printer basis <P>
1561 <B>Example:</B> printing = sysv <P>
1563 <H3><A NAME="protocol">protocol (G)</A></H3>
1564 The value of the parameter (a string) is the highest protocol level that will
1565 be supported by the server. <P>
1566 Possible values are CORE, COREPLUS, LANMAN1, LANMAN2 and NT1. The relative
1567 merits of each are discussed in the README file. <P>
1568 Normally this option should not be set as the automatic negotiation phase in
1569 the SMB protocol takes care of choosing the appropriate protocol. <P>
1570 <B>Default:</B> protocol = NT1 <P>
1571 <B>Example:</B> protocol = LANMAN1 <P>
1573 <H3><A NAME="read bmpx">read bmpx (S)</A></H3>
1574 <B>Default:</B> read bmpx = Yes <P>
1576 <H3><A NAME="read list">read list (S)</A></H3>
1577 This is a list of users that are given read-only access to a service.
1578 If the connecting user is in this list then they will not be given write
1579 access, no matter what the <A HREF="#read only">read only</A> option is set
1580 to. The list can include group names using the @group syntax. <P>
1581 See also the <A HREF="#write list">write list</A> option <P>
1582 <B>Default:</B> read list = <P>
1583 <B>Example:</B> read list = mary, @students <P>
1585 <H3><A NAME="read only">read only (S)</A></H3>
1586 Inverted synonyms for this parameter are 'writable' and 'write ok'. <P>
1587 If this parameter is 'Yes', then users of the service may not create or
1588 modify files in the service's directory. <P>
1589 Note that a printable service ('<A HREF="#printable">printable</A> = Yes')
1590 will ALWAYS allow writing to the directory (user privileges permitting), but
1591 only via spooling operations. <P>
1592 <B>Default:</B> read only = Yes <P>
1593 <B>Examples:</B> read only = No <BR>
1597 <H3><A NAME="read prediction">read prediction (G)</A></H3>
1598 This options enables or disables the read prediction code used to speed up
1599 reads from the server. When enabled the server will try to pre-read data
1600 from the last accessed file that was opened read-only while waiting for
1602 <B>Default:</B> read prediction = No <P>
1603 <B>Example:</B> read prediction = Yes <P>
1605 <H3><A NAME="read raw">read raw (G)</A></H3>
1606 This parameter controls whether or not the server will support raw reads when
1607 transferring data to clients. <P>
1608 If enabled, raw reads allow reads of 65535 bytes in one packet. This typically
1609 provides a major performance benefit. <P>
1610 However, some clients either negotiate the allowable block size incorrectly
1611 or are incapable of supporting larger block sizes, and for these clients you
1612 may need to disable raw reads. <P>
1613 In general this parameter should be viewed as a system tuning tool and left
1614 severely alone. See also <A HREF="#write raw">write raw.</A> <P>
1615 <B>Default:</B> read raw = Yes <P>
1616 <B>Example:</B> read raw = No <P>
1618 <H3><A NAME="read size">read size (G)</A></H3>
1619 The option "read size" affects the overlap of disk reads/writes with network
1620 reads/writes. If the amount of data being transferred in several of the SMB
1621 commands (currently SMBwrite, SMBwriteX and SMBreadbraw) is larger than this
1622 value then the server begins writing the data before it has received the
1623 whole packet from the network, or in the case of SMBreadbraw, it begins
1624 writing to the network before all the data has been read from disk. <P>
1625 This overlapping works best when the speeds of disk and network access are
1626 similar, having very little effect when the speed of one is much greater
1628 The default value is 2048, but very little experimentation has been done
1629 yet to determine the optimal value, and it is likely that the best value
1630 will vary greatly between systems anyway. A value over 65536 is pointless
1631 and will cause you to allocate memory unnecessarily. <P>
1632 <B>Default:</B> read size = 2048 <P>
1633 <B>Example:</B> read size = 8192 <P>
1635 <H3><A NAME="remote announce">remote announce (G)</A></H3>
1636 This option allows you to setup nmbd to periodically announce itself to
1637 arbitrary IP addresses with an arbitrary workgroup name. <P>
1638 This is useful if you want your Samba server to appear in a remote workgroup
1639 for which the normal browse propagation rules don't work. The remote
1640 workgroup can be anywhere that you can send IP packets to. <P>
1642 remote announce = 192.168.2.255/SERVERS 192.168.4.255/STAFF <P>
1643 the above line would cause nmbd to announce itself to the two given IP
1644 addresses using the given workgroup names. If you leave out the workgroup
1645 name then the one given in the <A HREF="#workgroup">workgroup</A> option is
1647 The IP addresses you choose would normally be the broadcast
1648 addresses of the remote networks, but can also be the IP addresses of
1649 known browse masters if your network config is that stable. <P>
1650 This option replaces similar functionality from the nmbd lmhosts file. <P>
1652 <H3><A NAME="remote browse sync">remote browse sync (G)</A></H3>
1653 This option allows you to setup nmbd to periodically request
1654 synchronisation of browse lists with the master browser of a samba server
1655 that is on a remote segment. This option will allow you to gain browse
1656 lists for multiple workgroups across routed networks. This is done in a
1657 manner that does not work with any non-samba servers. <P>
1658 This is useful if you want your Samba server and all local clients to appear
1659 in a remote workgroup for which the normal browse propagation rules don't
1660 work. The remote workgroup can be anywhere that you can send IP packets to.<P>
1662 remote browse sync = 192.168.2.255 192.168.4.255 <P>
1663 the above line would cause nmbd to request the master browser on the
1664 specified subnets or addresses to synchronise their browse lists with the
1666 The IP addresses you choose would normally be the broadcast addresses
1667 of the remote networks, but can also be the IP addresses of known browse
1668 masters if your network config is that stable. If a machine IP address
1669 is given Samba makes NO attempt to validate that the remote machine is
1670 available, is listening, nor that it is in fact the browse master on it's
1673 <H3><A NAME="revalidate">revalidate (S)</A></H3>
1674 This options controls whether Samba will allow a previously validated
1675 username/password pair to be used to attach to a share. Thus if you connect
1676 to \\server\share1 then to \\server\share2 it won't automatically allow the
1677 client to request connection to the second share as the same username as the
1678 first without a password. <P>
1679 If "revalidate" is Yes then the client will be denied automatic access as
1680 the same username. <P>
1681 <B>Default:</B> revalidate = No <P>
1682 <B>Example:</B> revalidate = Yes <P>
1684 <H3><A NAME="root directory">root directory (G)</A></H3>
1685 Synonyms for this parameter are 'root dir' and 'root'. <P>
1686 The server will chroot() to this directory on startup. This is not strictly
1687 necessary for secure operation. Even without it the server will deny access
1688 to files not in one of the service entries. It may also check for, and deny
1689 access to, soft links to other parts of the filesystem, or attempts to use
1690 .. in file names to access other directories (depending on the setting of
1691 the <A HREF="#wide links">wide links</A> parameter). <P>
1692 Adding a "root dir" entry other than "/" adds an extra level
1693 of security, but at a price. It absolutely ensures that no access is given
1694 to files not in the sub-tree specified in the "root dir" option, *including*
1695 some files needed for complete operation of the server. To maintain full
1696 operability of the server you will need to mirror some system files into
1697 the "root dir" tree. In particular you will need to mirror /etc/passwd
1698 (or a subset of it), and any binaries or configuration files needed for
1699 printing (if required). The set of files that must be mirrored is operating
1700 system dependent. <P>
1701 <B>Default:</B> root directory = / <P>
1702 <B>Example:</B> root directory = /homes/smb <P>
1704 <H3><A NAME="root postexec">root postexec (S)</A></H3>
1705 This is the same as <A HREF="#postexec">postexec</A> except that
1706 the command is run as root. This is useful for unmounting filesystems (such
1707 as CDROMS) after a connection is closed. <P>
1709 <H3><A NAME="root preexec">root preexec (S)</A></H3>
1710 This is the same as <A HREF="#exec">exec</A> except that the command is run
1711 as root. This is useful for mounting filesystems (such as CDROMS) before a
1712 connection is finalised. <P>
1714 <H3><A NAME="security">security (G)</A></H3>
1715 This option affects how clients respond to Samba. <P>
1716 The option sets the "security mode bit" in replies to protocol negotiations
1717 to turn share level security on or off. Clients decide based on this bit
1718 whether (and how) to transfer user and password information to the server.<P>
1719 The default is "security=SHARE", mainly because that was the only option at
1721 The alternatives are "security = user" or "security = server". <P>
1722 If your PCs use usernames that are the same as their usernames on the
1723 UNIX machine then you will want to use "security = user". If you mostly
1724 use usernames that don't exist on the UNIX box then use "security = share".<P>
1725 There is a bug in WfWg that may affect your decision. When in user level
1726 security a WfWg client will totally ignore the password you type in the
1727 "connect drive" dialog box. This makes it very difficult (if not impossible)
1728 to connect to a Samba service as anyone except the user that you are logged
1730 If you use "security = server" then Samba will try to validate
1731 the username/password by passing it to another SMB server, such as an
1732 NT box. If this fails it will revert to "security = USER". <P>
1733 See the <A HREF="#password server">password server</A> option for more
1735 <B>Default:</B> security = SHARE <P>
1736 <B>Example:</B> security = USER <P>
1738 <H3><A NAME="server string">server string (G)</A></H3>
1739 This controls what string will show up in the printer comment box in print
1740 manager and next to the IPC connection in "net view". It can be any string
1741 that you wish to show to your users. <P>
1742 It also sets what will appear in browse lists next to the machine name. <P>
1743 A %v will be replaced with the Samba version number. <P>
1744 A %h will be replaced with the hostname. <P>
1745 <B>Default:</B> server string = Samba %v <P>
1746 <B>Example:</B> server string = University of GNUs Samba Server <P>
1748 <H3><A NAME="set directory">set directory (S)</A></H3>
1749 If 'set directory = No', then users of the service may not use the setdir
1750 command to change directory. <P>
1751 The setdir command is only implemented in the Digital Pathworks
1752 client. See the Pathworks documentation for details. <P>
1753 <B>Default:</B> set directory = No <P>
1754 <B>Example:</B> set directory = Yes <P>
1756 <H3><A NAME="shared mem size">shared mem size (G)</A></H3>
1757 This parameter is only useful when Samba has been compiled with
1758 FAST_SHARE_MODES. It specifies the size of the shared
1759 memory (in bytes) to use between smbd processes. You should never change
1760 this parameter unless you have studied the source and know what you are
1761 doing. This parameter defaults to 1024 multiplied by the setting of the
1762 maximum number of open files in the file local.h in the Samba source code.
1763 MAX_OPEN_FILES is normally set to 100, so this parameter defaults to 102400
1765 <B>Default</B> shared mem size = 102400 <P>
1767 <H3><A NAME="smb passwd file">smb passwd file (G)</A></H3>
1768 This option sets the path to the encrypted smbpasswd file. This is a
1769 *VERY DANGEROUS OPTION* if the smb.conf is user writable. By default the
1770 path to the smbpasswd file is compiled into Samba. <P>
1772 <H3><A NAME="smbrun">smbrun (G)</A></H3>
1773 This sets the full path to the smbrun binary. This defaults to the value in
1775 You must get this path right for many services to work correctly. <P>
1776 <B>Default:</B> taken from Makefile <P>
1777 <B>Example:</B> smbrun = /usr/local/samba/bin/smbrun <P>
1779 <H3><A NAME="share modes">share modes (S)</A></H3>
1780 This enables or disables the honouring of the "share modes" during a file
1781 open. These modes are used by clients to gain exclusive read or write access
1783 These open modes are not directly supported by UNIX, so they are simulated
1784 using lock files in the <A HREF="#lock dir">lock dir</A>. The "lock dir"
1785 specified in smb.conf must be readable by all users. <P>
1786 The share modes that are enabled by this option are DENY_DOS, DENY_ALL,
1787 DENY_READ, DENY_WRITE, DENY_NONE and DENY_FCB. <P>
1788 Enabling this option gives full share compatibility but may cost a bit of
1789 processing time on the UNIX server. They are enabled by default. <P>
1790 <B>Default:</B> share modes = Yes <P>
1791 <B>Example:</B> share modes = No <P>
1793 <H3><A NAME="short preserve case">short preserve case (S)</A></H3>
1794 This controls if new short filenames are created with the case that the client
1795 passes, or if they are forced to be the "default" case. <P>
1796 <B>Default:</B> short preserve case = No <P>
1797 See the section on <A HREF="#NAME MANGLING">NAME MANGLING</A> for a fuller
1800 <H3><A NAME="socket address">socket address (G)</A></H3>
1801 This option allows you to control what address Samba will listen for
1802 connections on. This is used to support multiple virtual interfaces on the
1803 one server, each with a different configuration. <P>
1804 By default samba will accept connections on any address. <P>
1805 <B>Example:</B> socket address = 192.168.2.20 <P>
1807 <H3><A NAME="socket options">socket options (G)</A></H3>
1808 This option (which can also be invoked with the -O command line option) allows
1809 you to set socket options to be used when talking with the client. <P>
1810 Socket options are controls on the networking layer of the operating systems
1811 which allow the connection to be tuned. <P>
1812 This option will typically be used to tune your Samba server for optimal
1813 performance for your local network. There is no way that Samba can know what
1814 the optimal parameters are for your net, so you must experiment and choose
1815 them yourself. I strongly suggest you read the appropriate documentation for
1816 your operating system first (perhaps "man setsockopt" will help). <P>
1817 You may find that on some systems Samba will say "Unknown socket option" when
1818 you supply an option. This means you either mis-typed it or you need to add
1819 an include file to includes.h for your OS. If the latter is the case please
1820 send the patch to me (samba-bugs@samba.anu.edu.au). <P>
1821 Any of the supported socket options may be combined in any way you like, as
1822 long as your OS allows it. <P>
1823 This is the list of socket options currently settable using this option: <P>
1829 IPTOS_THROUGHPUT <BR>
1834 Those marked with a * take an integer argument. The others can optionally take
1835 a 1 or 0 argument to enable or disable the option, by default they will
1836 be enabled if you don't specify 1 or 0. <P>
1837 To specify an argument use the syntax SOME_OPTION=VALUE for example
1838 SO_SNDBUF=8192. Note that you must not have any spaces before or after the =
1840 If you are on a local network then a sensible option might be <P>
1841 socket options = IPTOS_LOWDELAY <P>
1842 If you have an almost unloaded local network and you don't mind a lot
1843 of extra CPU usage in the server then you could try <P>
1844 socket options = IPTOS_LOWDELAY TCP_NODELAY <P>
1845 If you are on a wide area network then perhaps try setting IPTOS_THROUGHPUT. <P>
1846 Note that several of the options may cause your Samba server to fail
1847 completely. Use these options with caution! <P>
1848 <B>Default:</B> no socket options <P>
1849 <B>Example:</B> socket options = IPTOS_LOWDELAY <P>
1851 <H3><A NAME="status">status (G)</A></H3>
1852 This enables or disables logging of connections to a status
1853 file that <B>smbstatus</B> can read. <P>
1854 With this disabled <B>smbstatus</B> won't be able to tell you what connections
1856 <B>Default:</B> status = Yes <P>
1857 <B>Example:</B> status = No <P>
1859 <H3><A NAME="strict locking">strict locking (S)</A></H3>
1860 This is a boolean that controls the handling of file locking in the server.
1861 When this is set to yes the server will check every read and write access
1862 for file locks, and deny access if locks exist. This can be slow on some
1864 When strict locking is "no" the server does file lock checks only when the
1865 client explicitly asks for them. <P>
1866 Well behaved clients always ask for lock checks when it is important,
1867 so in the vast majority of cases "strict locking = no" is preferable. <P>
1868 <B>Default:</B> strict locking = No <P>
1869 <B>Example:</B> strict locking = Yes <P>
1871 <H3><A NAME="strip dot">strip dot (G)</A></H3>
1872 This is a boolean that controls whether to strip trailing dots off
1873 UNIX filenames. This helps with some CDROMs that have filenames ending
1874 in a single dot. <P>
1875 <B>Default:</B> strip dot = No <P>
1876 <B>Example:</B> strip dot = Yes <P>
1878 <H3><A NAME="syslog">syslog (G)</A></H3>
1879 This parameter maps how Samba debug messages are logged onto
1880 the system syslog logging levels. Samba debug level zero maps onto syslog
1881 LOG_ERR, debug level one maps onto LOG_WARNING, debug level two maps to
1882 LOG_NOTICE, debug level three maps onto LOG_INFO. The paramter sets the
1883 threshold for doing the mapping, all Samba debug messages above this threashold
1884 are mapped to syslog LOG_DEBUG messages. <P>
1885 <B>Default:</B> syslog = 1 <P>
1887 <H3><A NAME="syslog only">syslog only (G)</A></H3>
1888 If this parameter is set then Samba debug messages are logged
1889 into the system syslog only, and not to the debug log files. <P>
1890 <B>Default:</B> syslog only = no <P>
1892 <H3><A NAME="sync always">sync always (S)</A></H3>
1893 This is a boolean parameter that controls whether writes will always be
1894 written to stable storage before the write call returns. If this is No then
1895 the server will be guided by the client's request in each write call (clients
1896 can set a bit indicating that a particular write should be synchronous). If
1897 this is Yes then every write will be followed by a fsync() call to ensure the
1898 data is written to disk. <P>
1899 <B>Default:</B> sync always = No <P>
1900 <B>Example:</B> sync always = Yes <P>
1902 <H3><A NAME="time offset">time offset (G)</A></H3>
1903 This parameter is a setting in minutes to add to the normal GMT to local time
1904 conversion. This is useful if you are serving a lot of PCs that have incorrect
1905 daylight saving time handling. <P>
1906 <B>Default:</B> time offset = 0 <P>
1907 <B>Example:</B> time offset = 60 <P>
1909 <H3><A NAME="time server">time server (G)</A></H3>
1910 This parameter determines if nmbd advertises itself as a time server to
1911 Windows clients. <P>
1912 <B>Default:</B> time server = No <P>
1913 <B>Example:</B> time server = Yes <P>
1915 <H3><A NAME="unix password sync">unix password sync (G)</A></H3>
1916 This boolean parameter controlls whether Samba attempts to synchronise the
1917 UNIX password with the SMB password when the encrypted SMB password in
1918 the smbpasswd file is changed. If this is set to Yes the
1919 <A HREF="#passwd program">passwd program</A>
1920 program is called *AS ROOT* - to allow the new UNIX password to be set
1921 without access to the old UNIX password (as the SMB password has change
1922 code has no access to the old password cleartext, only the new). By default
1923 this is set to No. <P>
1924 See also <A HREF="#passwd program">passwd program</A>,
1925 <A HREF="#passwd chat">passwd chat</A> <P>
1926 <B>Default:</B> unix password sync = No <P>
1927 <B>Example:</B> unix password sync = Yes <P>
1929 <H3><A NAME="unix realname">unix realname (G)</A></H3>
1930 This boolean parameter when set causes samba to supply the real name field
1931 from the unix password file to the client. This is useful for setting up mail
1932 clients and WWW browsers on systems used by more than one person. <P>
1933 <B>Default:</B> unix realname = No <P>
1934 <B>Example:</B> unix realname = Yes <P>
1936 <H3><A NAME="update encrypted">update encrypted (S)</A></H3>
1937 This boolean parameter allows a user logging on with a plaintext password to
1938 have their encrypted (hashed) password in the smbpasswd file to be updated
1939 automatically as they log on. This option allows a site to migrate from
1940 plaintext password authentication (users authenticate with plaintext
1941 password over the wire, and are checked against a UNIX account database) to
1942 encrypted password authentication (the SMB challenge/response authentication
1943 mechanism) without forcing all users to re-enter their passwords via smbpasswd
1944 at the time the change is made. This is a convenience option to allow the
1945 change over to encrypted passwords to be made over a longer period. Once all
1946 users have encrypted representations of their passwords in the smbpasswd file \
1947 this parameter should be set to "No". <P>
1948 In order for this parameter to work correctly the
1949 i<A HREF="#encrypt passwords">encrypt passwords</A> must be set to "No" when
1950 this parameter is set to "Yes". <P>
1951 Note that even when this parameter is set a user authenticating to smbd must
1952 still enter a valid password in order to connect correctly, and to update their
1953 hashed (smbpasswd) passwords. <P>
1954 <B>Default:</B> update encrypted = No <P>
1956 <H3><A NAME="use rhosts">use rhosts (S)</A></H3>
1957 <B>Default:</B> use rhosts = No <P>
1959 <H3><A NAME="username">username (S)</A></H3>
1960 A synonym for this parameter is 'user'. <P>
1961 Multiple users may be specified in a comma-delimited list, in which case the
1962 supplied password will be tested against each username in turn (left to
1964 The username= line is needed only when the PC is unable to supply its own
1965 username. This is the case for the coreplus protocol or where your users have
1966 different WfWg usernames to UNIX usernames. In both these cases you may also
1967 be better using the \\server\share%user syntax instead. <P>
1968 The username= line is not a great solution in many cases as it means Samba
1969 will try to validate the supplied password against each of the usernames in
1970 the username= line in turn. This is slow and a bad idea for lots of users in
1971 case of duplicate passwords. You may get timeouts or security breaches using
1972 this parameter unwisely. <P>
1973 Samba relies on the underlying UNIX security. This parameter does not restrict
1974 who can login, it just offers hints to the Samba server as to what usernames
1975 might correspond to the supplied password. Users can login as whoever they
1976 please and they will be able to do no more damage than if they started a
1977 telnet session. The daemon runs as the user that they log in as, so they
1978 cannot do anything that user cannot do. <P>
1979 To restrict a service to a particular set of users you can use the
1980 <A HREF="#valid users">valid users</A> line. <P>
1981 If any of the usernames begin with a @ then the name will be looked
1982 up in the groups file and will expand to a list of all users in the group
1983 of that name. Note that searching though a groups file can take quite some
1984 time, and some clients may time out during the search. <P>
1985 See the section below on
1986 <A HREF="#USERNAME/PASSWORD VALIDATION">USERNAME/PASSWORD VALIDATION</A>
1987 for more information on how this parameter determines access to the services.<P>
1988 <B>Default:</B> The guest account if a guest service, else the name of the service. <P>
1989 <B>Examples:</B>username = fredusername = fred, mary, jack, jane, @users, @pcgroup <P>
1991 <H3><A NAME="username level">username level (G)</A></H3>
1992 This option helps Samba to try and 'guess' at the real UNIX username,
1993 as many DOS clients send an all-uppercase username. By default Samba tries
1994 all lowercase, followed by the username with the first letter capitalized,
1995 and fails if the username is not found on the UNIX machine. <P>
1996 If this parameter is set to non-zero the behaviour changes. This parameter
1997 is a number that specifies the number of uppercase combinations to try whilst
1998 trying to determine the UNIX user name. The higher the number the more
1999 combinations will be tried, but the slower the discovery of usernames will be.
2000 Use this parameter when you have strange usernames on your UNIX machine,
2001 such as 'AstrangeUser'. <P>
2002 <B>Default:</B> username level = 0 <P>
2003 <B>Example:</B> username level = 5 <P>
2005 <H3><A NAME="username map">username map (G)</A></H3>
2006 This option allows you to to specify a file containing
2007 a mapping of usernames from the clients to the server. This can be used
2008 for several purposes. The most common is to map usernames that users use
2009 on DOS or Windows machines to those that the UNIX box uses. The other is
2010 to map multiple users to a single username so that they can more easily
2012 The map file is parsed line by line. Each line should contain
2013 a single UNIX username on the left then a '=' followed by a list of usernames
2014 on the right. The list of usernames on the right may contain names of the
2015 form @group in which case they will match any UNIX username in that group.
2016 The special client name '*' is a wildcard and matches any name. <P>
2017 The file is processed on each line by taking the supplied username and
2018 comparing it with each username on the right hand side of the '=' signs. If
2019 the supplied name matches any of the names on the right hand side then it is
2020 replaced with the name on the left. Processing then continues with the next
2022 If any line begins with a '#' or a ';' then it is ignored <P>
2023 If any line begins with an ! then the processing will stop after that line if
2024 a mapping was done by the line. Otherwise mapping continues with every line
2025 being processed. Using ! is most useful when you have a wildcard mapping line
2026 later in the file. <P>
2027 For example to map from the name "admin" or "administrator" to the UNIX name
2028 "root" you would use <P>
2029 root = admin administrator <P>
2030 Or to map anyone in the UNIX group "system" to the UNIX name "sys" you would
2033 You can have as many mappings as you like in a username map file. <P>
2034 You can map Windows usernames that have spaces in them by using
2035 double quotes around the name. For example: <P>
2036 tridge = "Andrew Tridgell" <P>
2037 would map the windows username "Andrew Tridgell" to the unix username
2039 The following example would map mary and fred to the unix user
2040 sys, and map the rest to guest. Note the use of the ! to tell Samba to
2041 stop processing if it gets a match on that line. <P>
2042 !sys = mary fred guest = * <P>
2043 Note that the remapping is applied to all occurrences of usernames.
2044 Thus if you connect to "\\server\fred" and "fred" is remapped to "mary" then
2045 you will actually be connecting to "\\server\mary" and will need to supply
2046 a password suitable for "mary" not "fred". The only exception to this is
2047 the username passed to the <A HREF="#password server">password server</A>
2048 (if you have one). The password server will receive whatever username the
2049 client supplies without modification. <P>
2050 Also note that no reverse mapping is done. The main effect this has is
2051 with printing. Users who have been mapped may have trouble deleting print
2052 jobs as PrintManager under WfWg will think they don't own the print job. <P>
2053 <B>Default</B> no username map <P>
2054 <B>Example</B> username map = /usr/local/samba/lib/users.map <P>
2056 <H3><A NAME="valid chars">valid chars (S)</A></H3>
2057 The option allows you to specify additional characters that should be
2058 considered valid by the server in filenames. This is particularly
2059 useful for national character sets, such as adding u-umlaut or a-ring. <P>
2060 The option takes a list of characters in either integer or character form
2061 with spaces between them. If you give two characters with a colon between
2062 them then it will be taken as an lowercase:uppercase pair. <P>
2063 If you have an editor capable of entering the characters into the config file
2064 then it is probably easiest to use this method. Otherwise you can specify the
2065 characters in octal, decimal or hexadecimal form using the usual C notation.<P>
2066 For example to add the single character 'Z' to the charset (which is a
2067 pointless thing to do as it's already there) you could do one of the following
2069 valid chars = Z <BR>
2070 valid chars = z:Z <BR>
2071 valid chars = 0132:0172 <P>
2072 The last two examples above actually add two characters, and alter the
2073 uppercase and lowercase mappings appropriately. <P>
2074 Note that you MUST specify this parameter after the
2075 <A HREF="#client code page">client code page</A> parameter if you have both
2076 set. If "client code page" is set after the "valid chars" parameter the
2077 "valid chars" settings will be overwritten. <P>
2078 See also the <A HREF="#client code page">client code page</A> parameter. <P>
2079 <B>Default:</B> Samba defaults to using a reasonable set of valid characters
2080 for english systems <P>
2081 <B>Example:</B> valid chars = 0345:0305 0366:0326 0344:0304 <P>
2082 The above example allows filenames to have the swedish characters in them. <P>
2083 NOTE: It is actually quite difficult to correctly produce a "valid chars" line
2084 for a particular system. To automate the process tino@augsburg.net
2085 has written a package called "validchars" which will automatically produce
2086 a complete "valid chars" line for a given client system. Look in the examples
2087 subdirectory for this package. <P>
2089 <H3><A NAME="valid users">valid users (S)</A></H3>
2090 This is a list of users that should be allowed to login to this service. A
2091 name starting with @ is interpreted as a UNIX group. <P>
2092 If this is empty (the default) then any user can login. If a username is in
2093 both this list and the <A HREF="#invalid users">invalid users</A> list then
2094 access is denied for that user. <P>
2095 The current servicename is substituted for %S. This is useful in the [homes]
2097 See also <A HREF="#invalid users">invalid users</A> <P>
2098 <B>Default</B> No valid users list. (anyone can login) <P>
2099 <B>Example</B> valid users = greg, @pcusers <P>
2101 <H3><A NAME="veto files">veto files (S)</A></H3>
2102 This is a list of files and directories that are neither visible nor
2103 accessible. Each entry in the list must be separated by a "/", which allows
2104 spaces to be included in the entry. '*' and '?' can be used to specify
2105 multiple files or directories as in DOS wildcards. <P>
2106 Each entry must be a unix path, not a DOS path and must not include the
2107 unix directory separator "/". <P>
2108 Note that the case sensitivity option is applicable in vetoing files. <P>
2109 One feature of the veto files parameter that it is important to be aware of,
2110 is that if a directory contains nothing but files that match the veto files
2111 parameter (which means that Windows/DOS clients cannot ever see them) is
2112 deleted, the veto files within that directory *are automatically deleted*
2113 along with it, if the user has UNIX permissions to do so.Setting this
2114 parameter will affect the performance of Samba, as it will be forced to check
2115 all files and directories for a match as they are scanned. <P>
2116 See also <A HREF="#hide files">hide files</A> and
2117 <A HREF="#case sensitive">case sensitive</A> <P>
2118 <B>Default</B> No files or directories are vetoed. <P>
2119 <B>Examples</B> Example 1. Veto any files containing the word Security, any
2120 ending in .tmp, and any directory containing the word root. <P>
2121 veto files = /*Security*/*.tmp/*root*/ <P>
2122 Example 2. Veto the Apple specific files that a NetAtalk server creates. <P>
2123 veto files = /.AppleDouble/.bin/.AppleDesktop/Network Trash Folder/ <P>
2125 <H3><A NAME="veto oplock files">veto oplock files (S)</A></H3>
2126 This parameter is only valid when the <A HREF="#oplocks">oplocks</A>
2127 parameter is turned on for a share. It allows the Samba administrator to
2128 selectively turn off the granting of oplocks on selected files that match
2129 a wildcarded list, similar to the wildcarded list used in the
2130 <A HREF="#veto files">veto files</A> parameter. <P>
2131 <B>Default</B> No files are vetoed for oplock grants. <P>
2132 <B>Examples</B> You might want to do this on files that you know will be
2133 heavily contended for by clients. A good example of this is in the NetBench
2134 SMB benchmark program, which causes heavy client contention for files ending
2135 in .SEM. To cause Samba not to grant oplocks on these files you would use the
2136 line (either in the [global] section or in the section for the particular
2137 NetBench share : <P>
2138 veto oplock files = /*.SEM/ <P>
2140 <H3><A NAME="volume">volume (S)</A></H3>
2141 This allows you to override the volume label returned for a share. Useful for
2142 CDROMs with installation programs that insist on a particular volume label.<P>
2143 The default is the name of the share <P>
2145 <H3><A NAME="wide links">wide links (S)</A></H3>
2146 This parameter controls whether or not links in the UNIX file system may be
2147 followed by the server. Links that point to areas within the directory tree
2148 exported by the server are always allowed; this parameter controls access only
2149 to areas that are outside the directory tree being exported. <P>
2150 <B>Default:</B> wide links = Yes <P>
2151 <B>Example:</B> wide links = No <P>
2153 <H3><A NAME="wins proxy">wins proxy (G)</A></H3>
2154 This is a boolean that controls if nmbd will respond to broadcast name queries
2155 on behalf of other hosts. You may need to set this to no for some older
2157 <B>Default:</B> wins proxy = No <P>
2159 <H3><A NAME="wins server">wins server (G)</A></H3>
2160 This specifies the DNS name (or IP address) of the WINS server that Samba
2161 should register with. If you have a WINS server on your network then you
2162 should set this to the WINS servers name. <P>
2163 You should point this at your WINS server if you have a multi-subnetted
2165 <B>Default:</B> wins server = <P>
2167 <H3><A NAME="wins support">wins support (G)</A></H3>
2168 This boolean controls if the nmbd process in Samba will act as a WINS server.
2169 You should not set this to Yes unless you have a multi-subnetted network and
2170 you wish a particular nmbd to be your WINS server. Note that you should
2171 *NEVER* set this to Yes on more than one machine in your network. <P>
2172 <B>Default:</B> wins support = No <P>
2174 <H3><A NAME="workgroup">workgroup (G)</A></H3>
2175 This controls what workgroup your server will appear to be in when queried by
2177 <B>Default:</B> set in the Makefile <P>
2178 <B>Example:</B> workgroup = MYGROUP <P>
2180 <H3><A NAME="write list">write list (S)</A></H3>
2181 This is a list of users that are given read-write access to a service. If
2182 the connecting user is in this list then they will be given write access,
2183 no matter what the <A HREF="#writable">writable</A> option is set to.
2184 The list can include group names using the @group syntax. <P>
2185 Note that if a user is in both the read list and the write list then they
2186 will be given write access. <P>
2187 See also the <A HREF="#read list">read list</A> option <P>
2188 <B>Default:</B> write list = <P>
2189 <B>Example:</B> write list = admin, root, @staff <P>
2191 <H3><A NAME="write raw">write raw (G)</A></H3>
2192 This parameter controls whether or not the server will support raw writes
2193 when transferring data from clients. <P>
2194 <B>Default:</B> write raw = Yes <P>
2195 <B>Example:</B> write raw = No <P>
2197 <H3><A NAME="USERNAME/PASSWORD VALIDATION">USERNAME/PASSWORD VALIDATION</A></H3>
2198 There are a number of ways in which a user can connect to a
2199 service. The server follows the following steps in determining if it will
2200 allow a connection to a specified service. If all the steps fail then the
2201 connection request is rejected. If one of the steps pass then the following
2202 steps are not checked. <P>
2203 If the service is marked "<A HREF="#guest only">guest only</A> = yes" then
2204 steps 1 to 5 are skipped <P>
2205 Step 1: If the client has passed a username/password
2206 pair and that username/password pair is validated by the UNIX system's
2207 password programs then the connection is made as that username. Note that
2208 this includes the \\server\service%username method of passing a username. <P>
2209 Step 2: If the client has previously registered a username with the system
2210 and now supplies a correct password for that username then the connection
2212 Step 3: The client's netbios name and any previously used user
2213 names are checked against the supplied password, if they match then the
2214 connection is allowed as the corresponding user. <P>
2215 Step 4: If the client has previously validated a username/password pair with
2216 the server and the client has passed the validation token then that username
2217 is used. This step is skipped if "<A HREF="#revalidate">revalidate</A> = yes"
2218 for this service. <P>
2219 Step 5: If a "<A HREF="#username">username</A> = " field is given in the
2220 smb.conf file for the service and the client has supplied a password, and
2221 that password matches (according to the UNIX system's password checking) with
2222 one of the usernames from the username= field then the connection is made as
2223 the username in the "username=" line. If one of the username in the username=
2224 list begins with a @ then that name expands to a list of names in the group
2225 of the same name. <P>
2226 Step 6: If the service is a guest service then a connection is made as the
2227 username given in the "<A HREF="#guest account">guest account</A> =" for the
2228 service, irrespective of the supplied password.<P>
2230 <H3><A NAME="NAME MANGLING">NAME MANGLING </A></H3>
2231 Samba supports "name mangling" so that DOS and Windows clients can use files
2232 that don't conform to the 8.3 format. It can also be set to adjust the case of
2233 8.3 format filenames. <P>
2234 There are several options that control the way mangling is
2235 performed, and they are grouped here rather than listed separately. <P>
2236 All of these options can be set separately for each service (or globally,
2238 The options are: <P>
2239 "<A HREF="#mangle case">mangle case</A> = yes/no" controls if names that have
2240 characters that aren't of the "default" case are mangled. For example, if
2241 this is yes then a name like "Mail" would be mangled. Default no. <P>
2242 "<A HREF="#case sensitive">case sensitive</A> = yes/no" controls whether
2243 filenames are case sensitive. If they aren't then Samba must do a filename
2244 search and match on passed names. Default no. <P>
2245 "<A HREF="#default case">default case</A> = upper/lower" controls what the
2246 default case is for new filenames. Default lower. <P>
2247 "<A HREF="#preserve case">preserve case</A> = yes/no" controls if new
2248 files are created with the case that the client passes, or if they are
2249 forced to be the "default" case. Default no. <P>
2250 "<A HREF="#short preserve case">short preserve case</A> = yes/no"
2251 controls if new files which conform to 8.3 syntax, that is all in upper
2252 case and of suitable length, are created upper case, or if they are forced
2253 to be the "default" case. This option can be use with "preserve case =
2254 yes" to permit long filenames to retain their case, while short names
2255 are lowered. Default no. <P>
git.samba.org / samba.git / blob