4 SWAT Parameters help<p>
6 We need to reformat the smb.conf man page as HTML with a label for
7 each parameter. Anyone want to write a perl script? Currently I've
8 just done a quick hack with an emacs macro to get something in
9 place. Or maybe the SGML conversion will be the way to go?<p>
13 <a name="admin users">
14 <H3>admin users (S)</H3><p>
16 This is a list of users who will be granted administrative privileges
17 on the share. This means that they will do all file operations as the
20 You should use this option very carefully, as any user in this list
21 will be able to do anything they like on the share, irrespective of
28 admin users = jason<p>
30 <a name="announce as">
31 <H3>announce as (G)</H3><p>
33 This specifies what type of server nmbd will announce itself as in
34 browse lists. By default this is set to Windows NT. The valid options
35 are "NT", "Win95" or "WfW" meaining Windows NT, Windows 95 and
36 Windows for Workgroups respectively. Do not change this parameter
37 unless you have a specific need to stop Samba appearing as an NT
38 server as this may prevent Samba servers from participating as
39 browser servers correctly.<p>
45 announce as = Win95<p>
47 <a name="announce version">
48 <H3>announce version (G)</H3><p>
50 This specifies the major and minor version numbers that nmbd
51 will use when announcing itself as a server. The default is 4.2.
52 Do not change this parameter unless you have a specific need to
53 set a Samba server to be a downlevel server.<p>
56 announce version = 4.2<p>
59 announce version = 2.0<p>
61 <a name="auto services">
62 <H3>auto services (G)</H3>
63 This is a list of services that you want to be automatically added to
64 the browse lists. This is most useful for homes and printers services
65 that would otherwise not be visible.<p>
67 Note that if you just want all printers in your printcap file loaded
68 then the "load printers" option is easier.<p>
74 auto services = fred lp colorlp<p>
76 <a name="allow hosts">
77 <H3>allow hosts (S)</H3>
78 A synonym for this parameter is 'hosts allow'.<p>
80 This parameter is a comma delimited set of hosts which are permitted to access
83 If specified in the [global] section then it will apply to all
84 services, regardless of whether the individual service has a different
87 You can specify the hosts by name or IP number. For example, you could
88 restrict access to only the hosts on a Class C subnet with something like
89 "allow hosts = 150.203.5.". The full syntax of the list is described in
91 .BR hosts_access (5).<p>
93 You can also specify hosts by network/netmask pairs and by netgroup
94 names if your system supports netgroups. The EXCEPT keyword can also
95 be used to limit a wildcard list. The following examples may provide
98 Example 1: allow all IPs in 150.203.*.* except one<p>
100 hosts allow = 150.203. EXCEPT 150.203.6.66<p>
102 Example 2: allow hosts that match the given network/netmask<p>
104 hosts allow = 150.203.15.0/255.255.255.0<p>
106 Example 3: allow a couple of hosts<p>
108 hosts allow = lapland, arvidsjaur<p>
110 Example 4: allow only hosts in netgroup "foonet" or localhost, but
111 deny access from one particular host<p>
113 hosts allow = @foonet, localhost
114 hosts deny = pirate<p>
116 Note that access still requires suitable user-level passwords.<p>
120 for a way of testing your host access to see if it
121 does what you expect.<p>
124 none (i.e., all hosts permitted access)<p>
127 allow hosts = 150.203.5. myhost.mynet.edu.au<p>
129 <a name="alternate permissions">
130 <H3>alternate permissions (S)</H3><p>
132 This option affects the way the "read only" DOS attribute is produced
133 for UNIX files. If this is false then the read only bit is set for
134 files on writeable shares which the user cannot write to.<p>
136 If this is true then it is set for files whos user write bit is not set.<p>
138 The latter behaviour is useful for when users copy files from each
139 others directories, and use a file manager that preserves
140 permissions. Without this option they may get annoyed as all copied
141 files will have the "read only" bit set.<p>
144 alternate permissions = no<p>
147 alternate permissions = yes<p>
150 <H3>available (S)</H3>
151 This parameter lets you 'turn off' a service. If 'available = no', then
152 ALL attempts to connect to the service will fail. Such failures are logged.<p>
160 <a name="bind interfaces only">
161 <H3>bind interfaces only (G)</H3>
162 This global parameter (new for 1.9.18) allows the Samba admin to limit
163 what interfaces on a machine will serve smb requests. If affects file service
164 (smbd) and name service (nmbd) in slightly different ways.<p>
166 For name service it causes nmbd to bind to ports 137 and 138 on
167 the interfaces listed in the 'interfaces' parameter. nmbd also binds
168 to the 'all addresses' interface (0.0.0.0) on ports 137 and 138
169 for the purposes of reading broadcast messages. If this option is
170 not set then nmbd will service name requests on all of these
171 sockets. If "bind interfaces only" is set then nmbd will check
172 the source address of any packets coming in on the broadcast
173 sockets and discard any that don't match the broadcast addresses
174 of the interfaces in the 'interfaces' parameter list. As unicast
175 packets are received on the other sockets it allows nmbd to
176 refuse to serve names to machines that send packets that arrive
177 through any interfaces not listed in the 'interfaces' list.
178 IP Source address spoofing does defeat this simple check, however
179 so it must not be used seriously as a security feature for nmbd.<p>
181 For file service it causes smbd to bind only to the interface
182 list given in the 'interfaces' parameter. This restricts the
183 networks that smbd will serve to packets coming in those interfaces.
184 Note that you should not use this parameter for machines that
185 are serving ppp or other intermittant or non-broadcast network
186 interfaces as it will not cope with non-permanent interfaces.<p>
189 bind interfaces only = False<p>
192 bind interfaces only = True<p>
194 <a name="browseable">
195 <H3>browseable (S)</H3>
196 This controls whether this share is seen in the list of available
197 shares in a net view and in the browse list.<p>
204 <a name="browse lis">
205 <H3>browse list(G)</H3>
206 This controls whether the smbd will serve a browse list to a client
207 doing a NetServerEnum call. Normally set to true. You should never
208 need to change this.<p>
213 <a name="case sensitive">
214 <H3>case sensitive (G)</H3>
215 See the discussion on NAME MANGLING.<p>
217 <a name="case sig names">
218 <H3>case sig names (G)</H3>
219 See "case sensitive"<p>
221 <a name="character set">
222 <H3>character set (G)</H3>
223 This allows a smbd to map incoming characters from a DOS 850 Code page
224 to either a Western European (ISO8859-1) or Easter European (ISO8859-2)
225 code page. Normally not set, meaning no filename translation is done.<p>
233 character set = iso8859-1<p>
235 <a name="client code page">
236 <H3>client code page (G)</H3>
237 Currently (Samba 1.9.17 and above) this may be set to one of two
238 values, 850 or 437. It specifies the base DOS code page that the
239 clients accessing Samba are using. To determine this, open a DOS
240 command prompt and type the command "chcp". This will output the
241 code page. The default for USA MS-DOS, Windows 95, and Windows NT
242 releases is code page 437. The default for western european
243 releases of the above operating systems is code page 850.<p>
245 This parameter co-operates with the "valid chars" parameter in
246 determining what characters are valid in filenames and how
247 capitalization is done. It has been added as a convenience for
248 clients whose code page is either 437 or 850 so a convoluted
249 "valid chars" string does not have to be determined. If you
250 set both this parameter and the "valid chars" parameter the
251 "client code page" parameter MUST be set before the "valid chars"
252 in the smb.conf file. The "valid chars" string will then augment
253 the character settings in the "client code page" parameter.<p>
255 If "client code page" is set to a value other than 850 or 437
256 it will default to 850.<p>
258 See also : "valid chars".<p>
262 client code page = 850<p>
266 client code page = 437<p>
270 This is a text field that is seen next to a share when a client does a
271 net view to list what shares are available.<p>
273 If you want to set the string that is displayed next to the machine
274 name then see the server string command.<p>
280 comment = Fred's Files<p>
282 <a name="config file">
283 <H3>config file (G)</H3><p>
285 This allows you to override the config file to use, instead of the
286 default (usually smb.conf). There is a chicken and egg problem here as
287 this option is set in the config file! <p>
289 For this reason, if the name of the config file has changed when the
290 parameters are loaded then it will reload them from the new config
293 This option takes the usual substitutions, which can be very useful.<p>
295 If the config file doesn't exist then it won't be loaded (allowing
296 you to special case the config files of just a few clients).<p>
299 config file = /usr/local/samba/lib/smb.conf.%m<p>
303 This parameter allows you to 'clone' service entries. The specified
304 service is simply duplicated under the current service's name. Any
305 parameters specified in the current section will override those in the
306 section being copied.<p>
308 This feature lets you set up a 'template' service and create similar
309 services easily. Note that the service being copied must occur earlier
310 in the configuration file than the service doing the copying.<p>
317 <a name="create mask">
318 <H3>create mask (S)</H3>
319 A synonym for this parameter is 'create mode'.<p>
321 When a file is created, the neccessary permissions are calculated
322 according to the mapping from DOS modes to UNIX permissions, and
323 the resulting UNIX mode is then bit-wise 'AND'ed with this parameter.
324 This parameter may be thought of as a bit-wise MASK for the UNIX
325 modes of a file. Any bit *not* set here will be removed from the
326 modes set on a file when it is created.<p>
328 The default value of this parameter removes the 'group' and 'other'
329 write and execute bits from the UNIX modes.<p>
331 Following this Samba will bit-wise 'OR' the UNIX mode created from
332 this parameter with the value of the "force create mode" parameter
333 which is set to 000 by default.<p>
335 For Samba 1.9.17 and above this parameter no longer affects directory
336 modes. See the parameter 'directory mode' for details.<p>
338 See also the "force create mode" parameter for forcing particular
339 mode bits to be set on created files.
340 See also the "directory mode" parameter for masking mode bits on created
344 create mask = 0744<p>
348 <a name="create mode">
349 <H3>create mode (S)</H3>
354 <H3>dead time (G)</H3>
355 The value of the parameter (a decimal integer) represents the number of
356 minutes of inactivity before a connection is considered dead, and it
357 is disconnected. The deadtime only takes effect if the number of open files
360 This is useful to stop a server's resources being exhausted by a large
361 number of inactive connections.<p>
363 Most clients have an auto-reconnect feature when a connection is broken so
364 in most cases this parameter should be transparent to users.<p>
366 Using this parameter with a timeout of a few minutes is recommended
369 A deadtime of zero indicates that no auto-disconnection should be performed.<p>
376 <a name="debug level">
377 <H3>debug level (G)</H3>
378 The value of the parameter (an integer) allows the debug level
379 (logging level) to be specified in the
381 file. This is to give
382 greater flexibility in the configuration of the system.<p>
384 The default will be the debug level specified on the command line.<p>
392 <a name="default case">
393 <H3>default case (S)</H3><p>
395 See the section on "NAME MANGLING" Also note the addition of "short
398 <a name="default service">
399 <H3>default service (G)</H3>
400 A synonym for this parameter is 'default'.<p>
402 This parameter specifies the name of a service which will be connected to
403 if the service actually requested cannot be found. Note that the square
404 brackets are NOT given in the parameter value (see example below).<p>
406 There is no default value for this parameter. If this parameter is not given,
407 attempting to connect to a nonexistent service results in an error.<p>
409 Typically the default service would be a public, read-only service.<p>
411 Also note that as of 1.9.14 the apparent service name will be changed to
412 equal that of the requested service, this is very useful as it allows
413 you to use macros like %S to make a wildcard service.<p>
415 Note also that any _ characters in the name of the service used in the
416 default service will get mapped to a /. This allows for interesting
421 default service = pub
427 <a name="delete readonly">
428 <H3>delete readonly (S)</H3>
429 This parameter allows readonly files to be deleted. This is not normal DOS
430 semantics, but is allowed by UNIX.<p>
432 This option may be useful for running applications such as rcs, where UNIX
433 file ownership prevents changing file permissions, and DOS semantics prevent
434 deletion of a read only file.<p>
437 delete readonly = No<p>
440 delete readonly = Yes
441 <a name="deny hosts">
442 <H3>deny hosts (S)</H3>
443 A synonym for this parameter is 'hosts deny'.<p>
445 The opposite of 'allow hosts' - hosts listed here are NOT permitted
446 access to services unless the specific services have their own lists to
447 override this one. Where the lists conflict, the 'allow' list takes precedence.<p>
450 none (i.e., no hosts specifically excluded)<p>
453 deny hosts = 150.203.4. badhost.mynet.edu.au<p>
455 <a name="delete veto files">
456 <H3>delete veto files (S)</H3><p>
458 This option is used when Samba is attempting to delete a directory
459 that contains one or more vetoed directories (see the 'veto files' option).
460 If this option is set to False (the default) then if a vetoed directory
461 contains any non-vetoed files or directories then the directory delete
462 will fail. This is usually what you want. <p>
464 If this option is set to True, then Samba will attempt
465 to recursively delete any files and directories within the vetoed
466 directory. This can be useful for integration with file serving
467 systems such as Netatalk, which create meta-files within directories
468 you might normally veto DOS/Windows users from seeing (eg. .AppleDouble)<p>
470 Setting 'delete veto files = True' allows these directories to be
471 transparently deleted when the parent directory is deleted (so long
472 as the user has permissions to do so).<p>
475 delete veto files = False<p>
478 delete veto files = True<p>
483 <a name="dfree command">
484 <H3>dfree command (G)</H3>
485 The dfree command setting should only be used on systems where a
486 problem occurs with the internal disk space calculations. This has
487 been known to happen with Ultrix, but may occur with other operating
488 systems. The symptom that was seen was an error of "Abort Retry
489 Ignore" at the end of each directory listing.<p>
491 This setting allows the replacement of the internal routines to
492 calculate the total disk space and amount available with an external
493 routine. The example below gives a possible script that might fulfill
496 The external program will be passed a single parameter indicating a
497 directory in the filesystem being queried. This will typically consist
498 of the string "./". The script should return two integers in ascii. The
499 first should be the total disk space in blocks, and the second should
500 be the number of available blocks. An optional third return value
501 can give the block size in bytes. The default blocksize is 1024 bytes.<p>
503 Note: Your script should NOT be setuid or setgid and should be owned by
504 (and writable only by) root!<p>
507 By default internal routines for determining the disk capacity
508 and remaining space will be used.<p>
511 dfree command = /usr/local/samba/bin/dfree<p>
513 Where the script dfree (which must be made executable) could be<p>
517 df $1 | tail -1 | awk '{print $2" "$4}'
520 or perhaps (on Sys V)<p>
524 /usr/bin/df -k $1 | tail -1 | awk '{print $3" "$5}'
527 Note that you may have to replace the command names with full
528 path names on some systems.
530 <H3>directory (S)</H3>
534 <a name="directory mask">
535 <H3>directory mask (S)</H3>
536 A synonym for this parameter is 'directory mode'.<p>
538 This parameter is the octal modes which are used when converting DOS modes
539 to UNIX modes when creating UNIX directories.<p>
541 When a directory is created, the neccessary permissions are calculated
542 according to the mapping from DOS modes to UNIX permissions, and
543 the resulting UNIX mode is then bit-wise 'AND'ed with this parameter.
544 This parameter may be thought of as a bit-wise MASK for the UNIX
545 modes of a directory. Any bit *not* set here will be removed from the
546 modes set on a directory when it is created.<p>
548 The default value of this parameter removes the 'group' and 'other'
549 write bits from the UNIX mode, allowing only the user who owns the
550 directory to modify it.<p>
552 Following this Samba will bit-wise 'OR' the UNIX mode created from
553 this parameter with the value of the "force directory mode" parameter.
554 This parameter is set to 000 by default (ie. no extra mode bits are added).<p>
556 See the "force directory mode" parameter to cause particular mode
557 bits to always be set on created directories.<p>
559 See also the "create mode" parameter for masking mode bits on created
563 directory mask = 0755<p>
566 directory mask = 0775<p>
568 <a name="directory mode">
569 <H3>directory mode (S)</H3>
571 .B directory mask.<p>
574 <H3>dns proxy (G)</H3><p>
576 Specifies that nmbd should (as a WINS server), on finding that a NetBIOS
577 name has not been registered, treat the NetBIOS name word-for-word as
580 Note that the maximum length for a NetBIOS name is 15
581 characters, so the DNS name (or DNS alias) can likewise only be 15
582 characters, maximum.<p>
584 Note also that nmbd will block completely until the DNS name is resolved.
585 This will result in temporary loss of browsing and WINS services.
586 Enable this option only if you are certain that DNS resolution is fast,
587 or you can live with the consequences of periodic pauses in nmbd service.<p>
592 <a name="domain controller">
593 <H3>domain controller (G)</H3><p>
595 Specifies the DNS name or IP address of the machine to refer domain
596 logons from Win95 machines to. You should never need to set this parameter.<p>
599 domain controller = no<p>
601 <a name="domain logons">
602 <H3>domain logons (G)</H3><p>
604 If set to true, the Samba server will serve Windows 95 domain logons
605 for the workgroup it is in. For more details on setting up this feature
606 see the file DOMAINS.txt in the Samba source documentation directory.<p>
609 domain logons = no<p>
611 <a name="domain master">
612 <H3>domain master (G)</H3><p>
614 Enable WAN-wide browse list collation. Local master browsers on
615 broadcast-isolated subnets will give samba their local browse lists, and
616 ask for a complete copy of the browse list for the whole wide area network.
617 Browser clients will then contact their local master browser, and will
618 receive the domain-wide browse list, instead of just the list for their
619 broadcast-isolated subnet.<p>
622 domain master = no<p>
624 <a name="dont descend">
625 <H3>dont descend (S)</H3>
626 There are certain directories on some systems (eg., the /proc tree under
627 Linux) that are either not of interest to clients or are infinitely deep
628 (recursive). This parameter allows you to specify a comma-delimited list
629 of directories that the server should always show as empty.<p>
631 Note that Samba can be very fussy about the exact format of the "dont
632 descend" entries. For example you may need "./proc" instead of just
633 "/proc". Experimentation is the best policy :-)<p>
636 none (i.e., all directories are OK to descend)<p>
639 dont descend = /proc,/dev<p>
641 <a name="dos filetimes">
642 <H3>dos filetimes (S)</H3>
643 Under DOS and Windows, if a user can write to a file they can change
644 the timestamp on it. Under POSIX semantics, only the owner of the file
645 or root may change the timestamp. By default, Samba runs with POSIX
646 semantics and refuses to change the timestamp on a file if the user
647 smbd is acting on behalf of is not the file owner. Setting this option
648 to True allows DOS semantics and smbd will change the file timstamp as
649 DOS requires. This is a correct implementation of a previous compile-time
650 options (UTIME_WORKAROUND) which was broken and is now removed.<p>
653 dos filetimes = False<p>
656 dos filetimes = True<p>
658 <a name="dos filetime resolution">
659 <H3>dos filetime resolution (S)</H3>
660 Under the DOS and Windows FAT filesystem, the finest granulatity on
661 time resolution is two seconds. Setting this parameter for a share
662 causes Samba to round the reported time down to the nearest two
663 second boundary when a query call that requires one second resolution
666 This option is mainly used as a compatibility option for Visual C++
667 when used against Samba shares. If oplocks are enabled on a share,
668 Visual C++ uses two different time reading calls to check if a file
669 has changed since it was last read. One of these calls uses a one-second
670 granularity, the other uses a two second granularity. As the two second
671 call rounds any odd second down, then if the file has a timestamp of an
672 odd number of seconds then the two timestamps will not match and Visual
673 C++ will keep reporting the file has changed. Setting this option causes
674 the two timestamps to match, and Visual C++ is happy.<p>
677 dos filetime resolution = False<p>
680 dos filetime resolution = True<p>
682 <a name="encrypt passwords">
683 <H3>encrypt passwords (G)</H3><p>
685 This boolean controls whether encrypted passwords will be negotiated
686 with the client. Note that this option has no effect if you haven't
687 compiled in the necessary des libraries and encryption code. It
693 This is an alias for preexec<p>
695 <a name="fake oplocks">
696 <H3>fake oplocks (S)</H3><p>
698 Oplocks are the way that SMB clients get permission from a server to
699 locally cache file operations. If a server grants an oplock
700 (opportunistic lock) then the client is free to assume that it is the
701 only one accessing the file and it will aggressively cache file
702 data. With some oplock types the client may even cache file open/close
703 operations. This can give enormous performance benefits.<p>
705 When you set "fake oplocks = yes" Samba will always grant oplock
706 requests no matter how many clients are using the file. <p>
708 By enabling this option on all read-only shares or shares that you know
709 will only be accessed from one client at a time you will see a big
710 performance improvement on many operations. If you enable this option
711 on shares where multiple clients may be accessing the files read-write
712 at the same time you can get data corruption. Use this option
715 It is generally much better to use the real oplock support except for
716 physically read-only media such as CDROMs.<p>
718 This option is disabled by default.<p>
720 <a name="follow symlinks">
721 <H3>follow symlinks (S)</H3><p>
723 This parameter allows the Samba administrator to stop smbd from
724 following symbolic links in a particular share. Setting this
725 parameter to "No" prevents any file or directory that is a
726 symbolic link from being followed (the user will get an error).
727 This option is very useful to stop users from adding a symbolic
728 link to /etc/pasword in their home directory for instance.
729 However it will slow filename lookups down slightly.<p>
731 This option is enabled (ie. smbd will follow symbolic links)
734 <a name="force create mode">
735 <H3>force create mode (S)</H3>
736 This parameter specifies a set of UNIX mode bit permissions that
737 will *always* be set on a file created by Samba. This is done
738 by bitwise 'OR'ing these bits onto the mode bits of a file that
739 is being created. The default for this parameter is (in octel)
740 000. The modes in this parameter are bitwise 'OR'ed onto the
741 file mode after the mask set in the "create mask" parameter
744 See also the parameter "create mask" for details on masking mode
745 bits on created files.<p>
748 force create mode = 000<p>
751 force create mode = 0755<p>
753 would force all created files to have read and execute permissions
754 set for 'group' and 'other' as well as the read/write/execute bits
755 set for the 'user'.<p>
757 <a name="force directory mode">
758 <H3>force directory mode (S)</H3>
759 This parameter specifies a set of UNIX mode bit permissions that
760 will *always* be set on a directory created by Samba. This is done
761 by bitwise 'OR'ing these bits onto the mode bits of a directory that
762 is being created. The default for this parameter is (in octel)
763 0000 which will not add any extra permission bits to a created
764 directory. This operation is done after the mode mask in the parameter
765 "directory mask" is applied.<p>
767 See also the parameter "directory mask" for details on masking mode
768 bits on created directories.<p>
771 force directory mode = 000<p>
774 force directory mode = 0755<p>
776 would force all created directories to have read and execute permissions
777 set for 'group' and 'other' as well as the read/write/execute bits
778 set for the 'user'.<p>
780 <a name="force group">
781 <H3>force group (S)</H3>
782 This specifies a group name that all connections to this service
783 should be made as. This may be useful for sharing files.<p>
789 force group = agroup<p>
791 <a name="force user">
792 <H3>force user (S)</H3>
793 This specifies a user name that all connections to this service
794 should be made as. This may be useful for sharing files. You should
795 also use it carefully as using it incorrectly can cause security
798 This user name only gets used once a connection is established. Thus
799 clients still need to connect as a valid user and supply a valid
800 password. Once connected, all file operations will be performed as the
801 "forced user", not matter what username the client connected as.<p>
807 force user = auser<p>
809 <a name="getwd cache">
810 <H3>getwd cache (G)</H3>
811 This is a tuning option. When this is enabled a cacheing algorithm will
812 be used to reduce the time taken for getwd() calls. This can have a
813 significant impact on performance, especially when widelinks is False.<p>
823 This is an alias for "force group" and is only kept for compatibility
824 with old versions of Samba. It may be removed in future versions.<p>
826 <a name="guest account">
827 <H3>guest account (S)</H3>
828 This is a username which will be used for access to services which are
829 specified as 'guest ok' (see below). Whatever privileges this user has
830 will be available to any client connecting to the guest
831 service. Typically this user will exist in the password file, but will
832 not have a valid login. If a username is specified in a given service,
833 the specified username overrides this one.<p>
835 One some systems the account "nobody" may not be able to print. Use
836 another account in this case. You should test this by trying to log in
837 as your guest user (perhaps by using the "su \-" command) and trying to
841 Note that as of version 1.9 of Samba this option may be set
842 differently for each service.<p>
845 specified at compile time<p>
848 guest account = nobody
850 <H3>guest ok (S)</H3>
853 <a name="guest only">
854 <H3>guest only (S)</H3>
855 If this parameter is 'yes' for a service, then only guest connections to the
856 service are permitted. This parameter will have no affect if "guest ok" or
857 "public" is not set for the service.<p>
859 See the section below on user/password validation for more information about
867 <a name="hide dot files">
868 <H3>hide dot files (S)</H3>
869 This is a boolean parameter that controls whether files starting with
870 a dot appear as hidden files.<p>
873 hide dot files = yes<p>
876 hide dot files = no<p>
880 <H3>hide files(S)</H3>
881 This is a list of files or directories that are not visible but are
882 accessible. The DOS 'hidden' attribute is applied to any files or
883 directories that match.<p>
885 Each entry in the list must be separated by a "/", which allows spaces
886 to be included in the entry. '*' and '?' can be used to specify multiple
887 files or directories as in DOS wildcards.<p>
889 Each entry must be a unix path, not a DOS path and must not include the
890 unix directory separator "/".<p>
892 Note that the case sensitivity option is applicable in hiding files.<p>
894 Setting this parameter will affect the performance of Samba, as
895 it will be forced to check all files and directories for a match
896 as they are scanned.<p>
898 See also "hide dot files", "veto files" and "case sensitive"<p>
901 No files or directories are hidden by this option (dot files are
902 hidden by default because of the "hide dot files" option).<p>
905 hide files = /.*/DesktopFolderDB/TrashFor%m/resource.frk/<p>
907 The above example is based on files that the Macintosh client (DAVE)
908 creates for internal use, and also still hides all files beginning with
911 <a name="homedir map">
912 <H3>homedir map (G)</H3>
913 If "nis homedir" is true, this parameter specifies the NIS (or YP) map
914 from which the server for the user's home directory should be extracted.
915 At present, only the Sun auto.home map format is understood. The form of
918 username server:/some/file/system<p>
920 and the program will extract the servername from before the first ':'.
921 There should probably be a better parsing system that copes with different
922 map formats and also Amd (another automounter) maps.<p>
924 NB: The -DNETGROUP option is required in the Makefile for option to work
925 and on some architectures the line -lrpcsvc needs to be added to the
926 LIBSM variable. This is required for Solaris 2, FreeBSD and HPUX.<p>
928 See also "nis homedir"<p>
931 homedir map = auto.home<p>
934 homedir map = amd.homedir
935 <a name="hosts allow">
936 <H3>hosts allow (S)</H3>
939 <a name="hosts deny">
940 <H3>hosts deny (S)</H3>
944 <a name="hosts equiv">
945 <H3>hosts equiv (G)</H3>
946 If this global parameter is a non-null string, it specifies the name of
947 a file to read for the names of hosts and users who will be allowed access
948 without specifying a password.<p>
950 This is not be confused with
952 which is about hosts access to services and is more useful for guest services.
954 may be useful for NT clients which will not supply passwords to samba.<p>
956 NOTE: The use of hosts.equiv can be a major security hole. This is
957 because you are trusting the PC to supply the correct username. It is
958 very easy to get a PC to supply a false username. I recommend that the
959 hosts.equiv option be only used if you really know what you are doing,
960 or perhaps on a home network where you trust your wife and kids :-)<p>
963 No host equivalences<p>
966 hosts equiv = /etc/hosts.equiv<p>
969 <H3>include (G)</H3><p>
971 This allows you to include one config file inside another. The file is
972 included literally, as though typed in place.<p>
974 It takes the standard substitutions, except %u, %P and %S<p>
976 <a name="interfaces">
977 <H3>interfaces (G)</H3><p>
979 This option allows you to setup multiple network interfaces, so that
980 Samba can properly handle browsing on all interfaces.<p>
982 The option takes a list of ip/netmask pairs. The netmask may either be
983 a bitmask, or a bitlength. <p>
985 For example, the following line:<p>
987 interfaces = 192.168.2.10/24 192.168.3.10/24<p>
989 would configure two network interfaces with IP addresses 192.168.2.10
990 and 192.168.3.10. The netmasks of both interfaces would be set to
993 You could produce an equivalent result by using:<p>
995 interfaces = 192.168.2.10/255.255.255.0 192.168.3.10/255.255.255.0<p>
997 if you prefer that format.<p>
999 If this option is not set then Samba will attempt to find a primary
1000 interface, but won't attempt to configure more than one interface.<p>
1002 <a name="invalid users">
1003 <H3>invalid users (S)</H3>
1004 This is a list of users that should not be allowed to login to this
1005 service. This is really a "paranoid" check to absolutely ensure an
1006 improper setting does not breach your security.<p>
1008 A name starting with @ is interpreted as a UNIX group.<p>
1010 The current servicename is substituted for %S. This is useful in the
1013 See also "valid users"<p>
1019 invalid users = root fred admin @wheel<p>
1021 <a name="keepalive">
1022 <H3>keepalive (G)</H3>
1023 The value of the parameter (an integer) represents the number of seconds
1024 between 'keepalive' packets. If this parameter is zero, no keepalive packets
1025 will be sent. Keepalive packets, if sent, allow the server to tell whether a
1026 client is still present and responding.<p>
1028 Keepalives should, in general, not be needed if the socket being used
1029 has the SO_KEEPALIVE attribute set on it (see "socket
1030 options"). Basically you should only use this option if you strike
1039 <a name="lm announce">
1040 <H3>lm announce (G)</H3><p>
1042 This parameter determines if Samba will produce Lanman announce
1043 broadcasts that are needed by OS/2 clients in order for them to
1044 see the Samba server in their browse list. This parameter can
1045 have three values, true, false, or auto. The default is auto.
1046 If set to False Samba will never produce these broadcasts. If
1047 set to true Samba will produce Lanman announce broadcasts at
1048 a frequency set by the parameter 'lm interval'. If set to auto
1049 Samba will not send Lanman announce broadcasts by default but
1050 will listen for them. If it hears such a broadcast on the wire
1051 it will then start sending them at a frequency set by the parameter
1054 See also "lm interval".<p>
1057 lm announce = auto<p>
1060 lm announce = true<p>
1062 <a name="lm interval">
1063 <H3>lm interval (G)</H3><p>
1065 If Samba is set to produce Lanman announce broadcasts needed
1066 by OS/2 clients (see the "lm announce" parameter) this parameter
1067 defines the frequency in seconds with which they will be made.
1068 If this is set to zero then no Lanman announcements will be
1069 made despite the setting of the "lm announce" parameter.<p>
1071 See also "lm announce".<p>
1077 lm interval = 120<p>
1079 <a name="load printers">
1080 <H3>load printers (G)</H3>
1081 A boolean variable that controls whether all printers in the printcap
1082 will be loaded for browsing by default. <p>
1085 load printers = yes<p>
1088 load printers = no<p>
1090 <a name="local master">
1091 <H3>local master (G)</H3>
1092 This option allows the nmbd to become a local master browser on a
1093 subnet. If set to False then nmbd will not attempt to become a local
1094 master browser on a subnet and will also lose in all browsing elections.
1095 By default this value is set to true. Setting this value to true doesn't
1096 mean that Samba will become the local master browser on a subnet, just
1097 that the nmbd will participate in elections for local master browser.<p>
1100 local master = yes<p>
1102 <a name="lock directory">
1103 <H3>lock directory (G)</H3>
1104 This option specifies the directory where lock files will be placed.
1105 The lock files are used to implement the "max connections" option.<p>
1108 lock directory = /tmp/samba<p>
1111 lock directory = /usr/local/samba/var/locks<p>
1114 <H3>locking (S)</H3>
1115 This controls whether or not locking will be performed by the server in
1116 response to lock requests from the client.<p>
1118 If "locking = no", all lock and unlock requests will appear to succeed and
1119 all lock queries will indicate that the queried lock is clear.<p>
1121 If "locking = yes", real locking will be performed by the server.<p>
1123 This option may be particularly useful for read-only filesystems which
1124 do not need locking (such as cdrom drives).<p>
1126 Be careful about disabling locking either globally or in a specific
1127 service, as lack of locking may result in data corruption.<p>
1136 <H3>log file (G)</H3><p>
1138 This options allows you to override the name of the Samba log file
1139 (also known as the debug file).<p>
1141 This option takes the standard substitutions, allowing you to have
1142 separate log files for each user or machine.<p>
1145 log file = /usr/local/samba/var/log.%m<p>
1147 <a name="log level">
1148 <H3>log level (G)</H3>
1149 see "debug level"<p>
1151 <a name="logon drive">
1152 <H3>logon drive (G)</H3><p>
1154 This parameter specifies the local path to which the home directory
1155 will be connected (see "logon home") and is only used by NT Workstations.<p>
1160 <a name="logon home">
1161 <H3>logon home (G)</H3><p>
1163 This parameter specifies the home directory location when a Win95 or
1164 NT Workstation logs into a Samba PDC. It allows you to do "NET USE
1165 H: /HOME" from a command prompt, for example.<p>
1168 This option takes the standard substitutions, allowing you to have
1169 separate logon scripts for each user or machine.<p>
1172 logon home = "\\\\remote_smb_server\\%U"<p>
1175 logon home = "\\\\%N\\%U"<p>
1177 <a name="logon path">
1178 <H3>logon path (G)</H3><p>
1180 This parameter specifies the home directory where roaming profiles
1181 (USER.DAT / USER.MAN files for Windows 95) are stored.<p>
1183 This option takes the standard substitutions, allowing you to have
1184 separate logon scripts for each user or machine. It also specifies
1185 the directory from which the "desktop", "start menu", "nethood" and
1186 "programs" folders, and their contents, are loaded and displayed
1187 on your Windows 95 client.<p>
1189 The share and the path must be readable by the user for the preferences
1190 and directories to be loaded onto the Windows 95 client. The share
1191 must be writeable when the logs in for the first time, in order that
1192 the Windows 95 client can create the user.dat and other directories.<p>
1194 Thereafter, the directories and any of contents can, if required,
1195 be made read-only. It is not adviseable that the USER.DAT file be made
1196 read-only - rename it to USER.MAN to achieve the desired effect
1197 (a MANdatory profile).<p>
1199 Windows clients can sometimes maintain a connection to the [homes]
1200 share, even though there is no user logged in. Therefore, it is
1201 vital that the logon path does not include a reference to the
1202 homes share (i.e \\\\%N\\HOMES\profile_path will cause problems).<p>
1205 This option takes the standard substitutions, allowing you to have
1206 separate logon scripts for each user or machine.<p>
1209 logon path = \\\\%N\\%U\\profile<p>
1212 logon path = \\\\PROFILESERVER\\HOME_DIR\\%U\\PROFILE<p>
1214 <a name="logon script">
1215 <H3>logon script (G)</H3><p>
1217 This parameter specifies the batch file (.bat) or NT command file (.cmd)
1218 to be downloaded and run on a machine when a user successfully logs in.
1219 The file must contain the DOS style cr/lf line endings. Using a DOS-style
1220 editor to create the file is recommended.<p>
1222 The script must be a relative path to the [netlogon] service. If the
1223 [netlogon] service specifies a path of /usr/local/samba/netlogon, and
1224 logon script = STARTUP.BAT, then file that will be downloaded is:<p>
1226 .B /usr/local/samba/netlogon/STARTUP.BAT<p>
1228 The contents of the batch file is entirely your choice. A suggested
1229 command would be to add NET TIME \\\\SERVER /SET /YES, to force every
1230 machine to synchronise clocks with the same time server. Another use
1231 would be to add NET USE U: \\\\SERVER\\UTILS for commonly used utilities,
1232 or NET USE Q: \\\\SERVER\\ISO9001_QA.<p>
1234 Note that it is particularly important not to allow write access to
1235 the [netlogon] share, or to grant users write permission on the
1236 batch files in a secure environment, as this would allow the batch
1237 files to be arbitrarily modified.<p>
1240 This option takes the standard substitutions, allowing you to have
1241 separate logon scripts for each user or machine.<p>
1244 logon script = scripts/%U.bat<p>
1246 <a name="lppause command">
1247 <H3>lppause command (S)</H3>
1248 This parameter specifies the command to be executed on the server host in
1249 order to stop printing or spooling a specific print job.<p>
1251 This command should be a program or script which takes a printer name and
1252 job number to pause the print job. Currently I don't know of any print
1253 spooler system that can do this with a simple option, except for the PPR
1254 system from Trinity College (ppr\-dist.trincoll.edu/pub/ppr). One way
1255 of implementing this is by using job priorities, where jobs having a too
1256 low priority won't be sent to the printer. See also the
1260 If a %p is given then the printername is put in its place. A %j is
1261 replaced with the job number (an integer).
1262 On HPUX (see printing=hpux), if the -p%p option is added to the lpq
1263 command, the job will show up with the correct status, i.e. if the job
1264 priority is lower than the set fence priority it will have the PAUSED
1265 status, whereas if the priority is equal or higher it will have the
1266 SPOOLED or PRINTING status.<p>
1268 Note that it is good practice to include the absolute path in the lppause
1269 command as the PATH may not be available to the server.<p>
1272 Currently no default value is given to this string<p>
1274 .B Example for HPUX:
1275 lppause command = /usr/bin/lpalt %p-%j -p0<p>
1277 <a name="lpq cache time">
1278 <H3>lpq cache time (G)</H3><p>
1280 This controls how long lpq info will be cached for to prevent the lpq
1281 command being called too often. A separate cache is kept for each
1282 variation of the lpq command used by the system, so if you use
1283 different lpq commands for different users then they won't share cache
1286 The cache files are stored in /tmp/lpq.xxxx where xxxx is a hash
1287 of the lpq command in use.<p>
1289 The default is 10 seconds, meaning that the cached results of a
1290 previous identical lpq command will be used if the cached data is less
1291 than 10 seconds old. A large value may be advisable if your lpq
1292 command is very slow.<p>
1294 A value of 0 will disable cacheing completely.<p>
1297 lpq cache time = 10<p>
1300 lpq cache time = 30<p>
1302 <a name="lpq command">
1303 <H3>lpq command (S)</H3>
1304 This parameter specifies the command to be executed on the server host in
1305 order to obtain "lpq"-style printer status information. <p>
1307 This command should be a program or script which takes a printer name
1308 as its only parameter and outputs printer status information. <p>
1310 Currently six styles of printer status information are supported; BSD,
1311 SYSV, AIX, HPUX, QNX, LPRNG and PLP. This covers most UNIX systems. You
1312 control which type is expected using the "printing =" option.<p>
1314 Some clients (notably Windows for Workgroups) may not correctly send the
1315 connection number for the printer they are requesting status information
1316 about. To get around this, the server reports on the first printer service
1317 connected to by the client. This only happens if the connection number sent
1320 If a %p is given then the printername is put in its place. Otherwise
1321 it is placed at the end of the command.<p>
1323 Note that it is good practice to include the absolute path in the lpq
1324 command as the PATH may not be available to the server.<p>
1327 depends on the setting of "printing ="<p>
1330 lpq command = /usr/bin/lpq %p<p>
1332 <a name="lpresume command">
1333 <H3>lpresume command (S)</H3>
1334 This parameter specifies the command to be executed on the server host in
1335 order to restart or continue printing or spooling a specific print job.<p>
1337 This command should be a program or script which takes a printer name and
1338 job number to resume the print job. See also the lppause command.<p>
1340 If a %p is given then the printername is put in its place. A %j is
1341 replaced with the job number (an integer).<p>
1343 Note that it is good practice to include the absolute path in the lpresume
1344 command as the PATH may not be available to the server.<p>
1347 Currently no default value is given to this string<p>
1349 .B Example for HPUX:
1350 lpresume command = /usr/bin/lpalt %p-%j -p2<p>
1352 <a name="lprm command">
1353 <H3>lprm command (S)</H3>
1354 This parameter specifies the command to be executed on the server host in
1355 order to delete a print job.<p>
1357 This command should be a program or script which takes a printer name
1358 and job number, and deletes the print job.<p>
1360 Currently seven styles of printer control are supported; BSD, SYSV, AIX
1361 HPUX, QNX, LPRNG and PLP. This covers most UNIX systems. You control
1362 which type is expected using the "printing =" option.<p>
1364 If a %p is given then the printername is put in its place. A %j is
1365 replaced with the job number (an integer).<p>
1367 Note that it is good practice to include the absolute path in the lprm
1368 command as the PATH may not be available to the server.<p>
1371 depends on the setting of "printing ="<p>
1374 lprm command = /usr/bin/lprm -P%p %j<p>
1377 lprm command = /usr/bin/cancel %p-%j<p>
1379 <a name="magic output">
1380 <H3>magic output (S)</H3>
1381 This parameter specifies the name of a file which will contain output
1382 created by a magic script (see
1386 Warning: If two clients use the same magic script in the same directory the
1387 output file content is undefined.
1389 magic output = <magic script name>.out<p>
1392 magic output = myfile.txt
1393 <a name="magic script">
1394 <H3>magic script (S)</H3>
1395 This parameter specifies the name of a file which, if opened, will be
1396 executed by the server when the file is closed. This allows a UNIX script
1397 to be sent to the Samba host and executed on behalf of the connected user.<p>
1399 Scripts executed in this way will be deleted upon completion, permissions
1402 If the script generates output, output will be sent to the file specified by
1405 parameter (see above).<p>
1407 Note that some shells are unable to interpret scripts containing
1408 carriage-return-linefeed instead of linefeed as the end-of-line
1409 marker. Magic scripts must be executable "as is" on the host, which
1410 for some hosts and some shells will require filtering at the DOS end.<p>
1412 Magic scripts are EXPERIMENTAL and should NOT be relied upon.<p>
1415 None. Magic scripts disabled.<p>
1418 magic script = user.csh<p>
1420 <a name="mangle case">
1421 <H3>mangle case (S)</H3><p>
1423 See the section on "NAME MANGLING"<p>
1425 <a name="mangled map">
1426 <H3>mangled map (S)</H3>
1427 This is for those who want to directly map UNIX file names which are
1428 not representable on DOS. The mangling of names is not always what is
1429 needed. In particular you may have documents with file extensions
1430 that differ between DOS and UNIX. For example, under UNIX it is common
1431 to use .html for HTML files, whereas under DOS .htm is more commonly
1434 So to map 'html' to 'htm' you put:<p>
1436 mangled map = (*.html *.htm)<p>
1438 One very useful case is to remove the annoying ;1 off the ends of
1439 filenames on some CDROMS (only visible under some UNIXes). To do this
1440 use a map of (*;1 *)<p>
1446 mangled map = (*;1 *)<p>
1448 <a name="mangled names">
1449 <H3>mangled names (S)</H3>
1450 This controls whether non-DOS names under UNIX should be mapped to
1451 DOS-compatible names ("mangled") and made visible, or whether non-DOS names
1452 should simply be ignored.<p>
1454 See the section on "NAME MANGLING" for details on how to control the
1455 mangling process.<p>
1457 If mangling is used then the mangling algorithm is as follows:
1459 - the first (up to) five alphanumeric characters before the rightmost dot of
1460 the filename are preserved, forced to upper case, and appear as the first (up
1461 to) five characters of the mangled name.<p>
1463 - a tilde ("~") is appended to the first part of the mangled name, followed
1464 by a two-character unique sequence, based on the original root name
1465 (i.e., the original filename minus its final extension). The final
1466 extension is included in the hash calculation only if it contains any upper
1467 case characters or is longer than three characters.<p>
1469 Note that the character to use may be specified using the "mangling
1470 char" option, if you don't like ~.<p>
1472 - the first three alphanumeric characters of the final extension are preserved,
1473 forced to upper case and appear as the extension of the mangled name. The
1474 final extension is defined as that part of the original filename after the
1475 rightmost dot. If there are no dots in the filename, the mangled name will
1476 have no extension (except in the case of hidden files - see below).<p>
1478 - files whose UNIX name begins with a dot will be presented as DOS hidden
1479 files. The mangled name will be created as for other filenames, but with the
1480 leading dot removed and "___" as its extension regardless of actual original
1481 extension (that's three underscores).
1484 The two-digit hash value consists of upper case alphanumeric characters.<p>
1486 This algorithm can cause name collisions only if files in a directory share
1487 the same first five alphanumeric characters. The probability of such a clash
1490 The name mangling (if enabled) allows a file to be copied between UNIX
1491 directories from DOS while retaining the long UNIX filename. UNIX files can
1492 be renamed to a new extension from DOS and will retain the same basename.
1493 Mangled names do not change between sessions.<p>
1496 mangled names = yes<p>
1500 <a name="mangling char">
1501 <H3>mangling char (S)</H3>
1502 This controls what character is used as the "magic" character in name
1503 mangling. The default is a ~ but this may interfere with some
1504 software. Use this option to set it to whatever you prefer.<p>
1507 mangling char = ~<p>
1510 mangling char = ^<p>
1512 <a name="mangled stack">
1513 <H3>mangled stack (G)</H3>
1514 This parameter controls the number of mangled names that should be cached in
1515 the Samba server.<p>
1517 This stack is a list of recently mangled base names (extensions are only
1518 maintained if they are longer than 3 characters or contains upper case
1521 The larger this value, the more likely it is that mangled names can be
1522 successfully converted to correct long UNIX names. However, large stack
1523 sizes will slow most directory access. Smaller stacks save memory in the
1524 server (each stack element costs 256 bytes).<p>
1526 It is not possible to absolutely guarantee correct long file names, so
1527 be prepared for some surprises!<p>
1530 mangled stack = 50<p>
1533 mangled stack = 100<p>
1535 <a name="map archive">
1536 <H3>map archive (S)</H3>
1537 This controls whether the DOS archive attribute should be mapped to the
1538 UNIX owner execute bit. The DOS archive bit is set when a file has been modified
1539 since its last backup. One motivation for this option it to keep Samba/your
1540 PC from making any file it touches from becoming executable under UNIX.
1541 This can be quite annoying for shared source code, documents, etc...<p>
1543 Note that this requires the 'create mask' to be set such that owner
1544 execute bit is not masked out (ie. it must include 100). See the
1545 parameter "create mask" for details.<p>
1548 map archive = yes<p>
1553 <a name="map hidden">
1554 <H3>map hidden (S)</H3>
1555 This controls whether DOS style hidden files should be mapped to the
1556 UNIX world execute bit.<p>
1558 Note that this requires the 'create mask' to be set such that the world
1559 execute bit is not masked out (ie. it must include 001).
1560 See the parameter "create mask" for details.<p>
1567 <a name="map system">
1568 <H3>map system (S)</H3>
1569 This controls whether DOS style system files should be mapped to the
1570 UNIX group execute bit.<p>
1572 Note that this requires the 'create mask' to be set such that the group
1573 execute bit is not masked out (ie. it must include 010). See the parameter
1574 "create mask" for details.<p>
1581 <a name="max connections">
1582 <H3>max connections (S)</H3>
1583 This option allows the number of simultaneous connections to a
1584 service to be limited. If "max connections" is greater than 0 then
1585 connections will be refused if this number of connections to the
1586 service are already open. A value of zero mean an unlimited number of
1587 connections may be made.<p>
1589 Record lock files are used to implement this feature. The lock files
1590 will be stored in the directory specified by the "lock directory" option.<p>
1593 max connections = 0<p>
1596 max connections = 10<p>
1598 <a name="max disk size">
1599 <H3>max disk size (G)</H3>
1600 This option allows you to put an upper limit on the apparent size of
1601 disks. If you set this option to 100 then all shares will appear to be
1602 not larger than 100 MB in size.<p>
1604 Note that this option does not limit the amount of data you can put on
1605 the disk. In the above case you could still store much more than 100
1606 MB on the disk, but if a client ever asks for the amount of free disk
1607 space or the total disk size then the result will be bounded by the
1608 amount specified in "max disk size".<p>
1610 This option is primarily useful to work around bugs in some pieces of
1611 software that can't handle very large disks, particularly disks over
1614 A "max disk size" of 0 means no limit.<p>
1617 max disk size = 0<p>
1620 max disk size = 1000<p>
1622 <a name="max log size">
1623 <H3>max log size (G)</H3><p>
1625 This option (an integer in kilobytes) specifies the max size the log
1626 file should grow to. Samba periodically checks the size and if it is
1627 exceeded it will rename the file, adding a .old extension.<p>
1629 A size of 0 means no limit.<p>
1632 max log size = 5000<p>
1635 max log size = 1000<p>
1638 <H3>max mux (G)</H3><p>
1640 This option controls the maximum number of outstanding simultaneous SMB
1641 operations that samba tells the client it will allow. You should never need
1642 to set this parameter.<p>
1647 <a name="max packet">
1648 <H3>max packet (G)</H3><p>
1650 A synonym for this parameter is 'packet size'.<p>
1653 <H3>max ttl (G)</H3><p>
1655 This option tells nmbd what the default 'time to live' of NetBIOS
1656 names should be (in seconds) when nmbd is requesting a name using
1657 either a broadcast or from a WINS server. You should never need to
1658 change this parameter.<p>
1663 <a name="max wins ttl">
1664 <H3>max wins ttl (G)</H3><p>
1666 This option tells nmbd when acting as a WINS server (wins support = true)
1667 what the maximum 'time to live' of NetBIOS names that nmbd will grant will
1668 be (in seconds). You should never need to change this parameter.
1669 The default is 3 days (259200 seconds).<p>
1672 max wins ttl = 259200<p>
1675 <H3>max xmit (G)</H3><p>
1677 This option controls the maximum packet size that will be negotiated
1678 by Samba. The default is 65535, which is the maximum. In some cases
1679 you may find you get better performance with a smaller value. A value
1680 below 2048 is likely to cause problems.<p>
1688 <a name="message command">
1689 <H3>message command (G)</H3><p>
1691 This specifies what command to run when the server receives a WinPopup
1694 This would normally be a command that would deliver the message
1695 somehow. How this is to be done is up to your imagination.<p>
1699 message command = csh -c 'xedit %s;rm %s' &<p>
1701 This delivers the message using xedit, then removes it
1702 afterwards. NOTE THAT IT IS VERY IMPORTANT THAT THIS COMMAND RETURN
1703 IMMEDIATELY. That's why I have the & on the end. If it doesn't return
1704 immediately then your PCs may freeze when sending messages (they
1705 should recover after 30secs, hopefully).<p>
1707 All messages are delivered as the global guest user. The command takes
1708 the standard substitutions, although %u won't work (%U may be better
1711 Apart from the standard substitutions, some additional ones apply. In
1714 %s = the filename containing the message<p>
1716 %t = the destination that the message was sent to (probably the server
1719 %f = who the message is from<p>
1721 You could make this command send mail, or whatever else takes your
1722 fancy. Please let me know of any really interesting ideas you have.<p>
1724 Here's a way of sending the messages as mail to root:<p>
1726 message command = /bin/mail -s 'message from %f on %m' root < %s; rm %s<p>
1728 If you don't have a message command then the message won't be
1729 delivered and Samba will tell the sender there was an
1730 error. Unfortunately WfWg totally ignores the error code and carries
1731 on regardless, saying that the message was delivered.<p>
1733 If you want to silently delete it then try "message command = rm %s".<p>
1735 For the really adventurous, try something like this:<p>
1737 message command = csh -c 'csh < %s |& /usr/local/samba/bin/smbclient \e
1740 this would execute the command as a script on the server, then give
1741 them the result in a WinPopup message. Note that this could cause a
1742 loop if you send a message from the server using smbclient! You better
1743 wrap the above in a script that checks for this :-)<p>
1746 no message command<p>
1749 message command = csh -c 'xedit %s;rm %s' &<p>
1751 <a name="min print space">
1752 <H3>min print space (S)</H3><p>
1754 This sets the minimum amount of free disk space that must be available
1755 before a user will be able to spool a print job. It is specified in
1756 kilobytes. The default is 0, which means no limit.<p>
1759 min print space = 0<p>
1762 min print space = 2000<p>
1764 <a name="min wins ttl">
1765 <H3>min wins ttl (G)</H3><p>
1767 This option tells nmbd when acting as a WINS server (wins support = true)
1768 what the minimum 'time to live' of NetBIOS names that nmbd will grant will
1769 be (in seconds). You should never need to change this parameter.
1770 The default is 6 hours (21600 seconds).<p>
1773 min wins ttl = 21600<p>
1776 <a name="netbios aliases">
1777 <H3>netbios aliases (G)</H3><p>
1779 This is a list of names that nmbd will advertise as additional
1780 names by which the Samba server is known. This allows one machine
1781 to appear in browse lists under multiple names. If a machine is
1782 acting as a browse server or logon server none of these names
1783 will be advertised as either browse server or logon servers, only
1784 the primary name of the machine will be advertised with these
1787 See also 'netbios name'.<p>
1790 netbios aliases = TEST TEST1 TEST2<p>
1792 <a name="netbios name">
1793 <H3>netbios name (G)</H3><p>
1795 This sets the NetBIOS name by which a Samba server is known. By
1796 default it is the same as the first component of the host's DNS name.
1797 If a machine is a browse server or logon server this name (or the
1798 first component of the hosts DNS name) will be the name that these
1799 services are advertised under.<p>
1801 See also 'netbios aliases'.<p>
1804 netbios name = MYNAME<p>
1806 <a name="nis homedir">
1807 <H3>nis homedir (G)</H3>
1808 Get the home share server from a NIS (or YP) map. For unix systems that
1809 use an automounter, the user's home directory will often be mounted on
1810 a workstation on demand from a remote server. When the Samba logon server
1811 is not the actual home directory server, two network hops are required
1812 to access the home directory and this can be very slow especially with
1813 writing via Samba to an NFS mounted directory. This option allows samba
1814 to return the home share as being on a different server to the logon
1815 server and as long as a samba daemon is running on the home directory
1816 server, it will be mounted on the Samba client directly from the directory
1817 server. When Samba is returning the home share to the client, it will
1818 consult the NIS (or YP) map specified in "homedir map" and return the
1819 server listed there.<p>
1822 nis homedir = false<p>
1825 nis homedir = true<p>
1827 <a name="networkstation user login">
1828 <H3>networkstation user login (G)</H3>
1829 This global parameter (new for 1.9.18p3) affects server level security.
1830 With this set (recommended) samba will do a full NetWkstaUserLogon to
1831 confirm that the client really should have login rights. This can cause
1832 problems with machines in trust relationships in which case you can
1833 disable it here, but be warned, we have heard that some NT machines
1834 will then allow anyone in with any password! Make sure you test it.<p>
1837 networkstation user login = yes<p>
1840 networkstation user login = no<p>
1842 <a name="null passwords">
1843 <H3>null passwords (G)</H3>
1844 Allow or disallow access to accounts that have null passwords. <p>
1847 null passwords = no<p>
1850 null passwords = yes<p>
1852 <a name="only guest">
1853 <H3>only guest (S)</H3>
1854 A synonym for this command is 'guest only'.<p>
1856 <a name="only user">
1857 <H3>only user (S)</H3>
1858 This is a boolean option that controls whether connections with
1859 usernames not in the user= list will be allowed. By default this
1860 option is disabled so a client can supply a username to be used by
1863 Note that this also means Samba won't try to deduce usernames from the
1864 service name. This can be annoying for the [homes] section. To get
1865 around this you could use "user = %S" which means your "user" list
1866 will be just the service name, which for home directories is the name
1870 only user = False<p>
1876 <H3>oplocks (S)</H3>
1877 This boolean option tells smbd whether to issue oplocks (opportunistic
1878 locks) to file open requests on this share. The oplock code was introduced in
1879 Samba 1.9.18 and can dramatically (approx 30% or more) improve the speed
1880 of access to files on Samba servers. It allows the clients to agressively
1881 cache files locally and you may want to disable this option for unreliable
1882 network environments (it is turned on by default in Windows NT Servers).
1883 For more information see the file Speed.txt in the Samba docs/ directory.<p>
1885 Oplocks may be selectively turned off on certain files on a per share basis.
1886 See the 'veto oplock files' parameter.<p>
1896 <H3>os level (G)</H3>
1897 This integer value controls what level Samba advertises itself as for
1898 browse elections. See BROWSING.txt for details.<p>
1900 <a name="packet size">
1901 <H3>packet size (G)</H3>
1902 The maximum transmit packet size during a raw read. This option is no
1903 longer implemented as of version 1.7.00, and is kept only so old
1904 configuration files do not become invalid.<p>
1906 <a name="passwd chat">
1907 <H3>passwd chat (G)</H3>
1908 This string controls the "chat" conversation that takes places
1909 between smbd and the local password changing program to change the
1910 users password. The string describes a sequence of response-receive
1911 pairs that smbd uses to determine what to send to the passwd program
1912 and what to expect back. If the expected output is not received then
1913 the password is not changed.<p>
1915 This chat sequence is often quite site specific, depending on what
1916 local methods are used for password control (such as NIS+ etc).<p>
1918 The string can contain the macros %o and %n which are substituted for
1919 the old and new passwords respectively. It can also contain the
1920 standard macros \en \er \et and \es to give line-feed, carriage-return,
1923 The string can also contain a * which matches any sequence of
1926 Double quotes can be used to collect strings with spaces in them into
1929 If the send string in any part of the chat sequence is a fullstop "."
1930 then no string is sent. Similarly, is the expect string is a fullstop
1931 then no string is expected.<p>
1934 passwd chat = "*Enter OLD password*" %o\en "*Enter NEW password*" %n\en \e
1935 "*Reenter NEW password*" %n\en "*Password changed*"<p>
1939 passwd chat = *old*password* %o\en *new*password* %n\en *new*password* %n\en *changed*<p>
1941 <a name="passwd program">
1942 <H3>passwd program (G)</H3>
1943 The name of a program that can be used to set user passwords.<p>
1945 This is only necessary if you have enabled remote password changing at
1946 compile time. Any occurrences of %u will be replaced with the user
1949 Also note that many passwd programs insist in "reasonable" passwords,
1950 such as a minimum length, or the inclusion of mixed case chars and
1951 digits. This can pose a problem as some clients (such as Windows for
1952 Workgroups) uppercase the password before sending it. <p>
1955 passwd program = /bin/passwd<p>
1958 passwd program = /sbin/passwd %u<p>
1960 <a name="password level">
1961 <H3>password level (G)</H3>
1962 Some client/server combinations have difficulty with mixed-case passwords.
1963 One offending client is Windows for Workgroups, which for some reason forces
1964 passwords to upper case when using the LANMAN1 protocol, but leaves them alone
1965 when using COREPLUS!<p>
1967 This parameter defines the maximum number of characters that may be upper case
1970 For example, say the password given was "FRED". If
1972 is set to 1 (one), the following combinations would be tried if "FRED" failed:
1973 "Fred", "fred", "fRed", "frEd", "freD". If
1974 .B password level was set to 2 (two), the following combinations would also be
1975 tried: "FRed", "FrEd", "FreD", "fREd", "fReD", "frED". And so on.<p>
1977 The higher value this parameter is set to the more likely it is that a mixed
1978 case password will be matched against a single case password. However, you
1979 should be aware that use of this parameter reduces security and increases the
1980 time taken to process a new connection.<p>
1982 A value of zero will cause only two attempts to be made - the password as is
1983 and the password in all-lower case.<p>
1985 If you find the connections are taking too long with this option then
1986 you probably have a slow crypt() routine. Samba now comes with a fast
1987 "ufc crypt" that you can select in the Makefile. You should also make
1988 sure the PASSWORD_LENGTH option is correct for your system in local.h
1989 and includes.h. On most systems only the first 8 chars of a password
1990 are significant so PASSWORD_LENGTH should be 8, but on some longer
1991 passwords are significant. The includes.h file tries to select the
1992 right length for your system.<p>
1995 password level = 0<p>
1998 password level = 4<p>
2000 <a name="password server">
2001 <H3>password server (G)</H3><p>
2003 By specifying the name of another SMB server (such as a WinNT box)
2004 with this option, and using "security = server" you can get Samba to
2005 do all its username/password validation via a remote server.<p>
2007 This options sets the name of the password server to use. It must be a
2008 netbios name, so if the machine's netbios name is different from its
2009 internet name then you may have to add its netbios name to
2012 The password server much be a machine capable of using the "LM1.2X002"
2013 or the "LM NT 0.12" protocol, and it must be in user level security
2016 NOTE: Using a password server means your UNIX box (running Samba) is
2017 only as secure as your password server. DO NOT CHOOSE A PASSWORD
2018 SERVER THAT YOU DON'T COMPLETELY TRUST.<p>
2020 Never point a Samba server at itself for password serving. This will
2021 cause a loop and could lock up your Samba server!<p>
2023 The name of the password server takes the standard substitutions, but
2024 probably the only useful one is %m, which means the Samba server will
2025 use the incoming client as the password server. If you use this then
2026 you better trust your clients, and you better restrict them with hosts
2029 If you list several hosts in the "password server" option then smbd
2030 will try each in turn till it finds one that responds. This is useful
2031 in case your primary server goes down.<p>
2033 If you are using a WindowsNT server as your password server then you
2034 will have to ensure that your users are able to login from the Samba
2035 server, as the network logon will appear to come from there rather
2036 than from the users workstation.<p>
2040 A synonym for this parameter is 'directory'.<p>
2042 This parameter specifies a directory to which the user of the service is to
2043 be given access. In the case of printable services, this is where print data
2044 will spool prior to being submitted to the host for printing.<p>
2046 For a printable service offering guest access, the service should be readonly
2047 and the path should be world-writable and have the sticky bit set. This is not
2048 mandatory of course, but you probably won't get the results you expect if you
2051 Any occurrences of %u in the path will be replaced with the username
2052 that the client is connecting as. Any occurrences of %m will be
2053 replaced by the name of the machine they are connecting from. These
2054 replacements are very useful for setting up pseudo home directories
2057 Note that this path will be based on 'root dir' if one was specified.
2062 path = /home/fred+ <p>
2065 <H3>postexec (S)</H3><p>
2067 This option specifies a command to be run whenever the service is
2068 disconnected. It takes the usual substitutions. The command may be run
2069 as the root on some systems.<p>
2071 An interesting example may be do unmount server resources:<p>
2073 postexec = /etc/umount /cdrom<p>
2078 none (no command executed)<p>
2081 postexec = echo \e"%u disconnected from %S from %m (%I)\e" >> /tmp/log<p>
2083 <a name="postscript">
2084 <H3>postscript (S)</H3>
2085 This parameter forces a printer to interpret the print files as
2086 postscript. This is done by adding a %! to the start of print output. <p>
2088 This is most useful when you have lots of PCs that persist in putting
2089 a control-D at the start of print jobs, which then confuses your
2093 postscript = False<p>
2096 postscript = True<p>
2099 <H3>preexec (S)</H3><p>
2101 This option specifies a command to be run whenever the service is
2102 connected to. It takes the usual substitutions.<p>
2104 An interesting example is to send the users a welcome message every
2105 time they log in. Maybe a message of the day? Here is an example:<p>
2107 preexec = csh -c 'echo \e"Welcome to %S!\e" | \e
2108 /usr/local/samba/bin/smbclient -M %m -I %I' &<p>
2110 Of course, this could get annoying after a while :-)<p>
2112 See also postexec<p>
2115 none (no command executed)<p>
2118 preexec = echo \e"%u connected to %S from %m (%I)\e" >> /tmp/log<p>
2120 <a name="preferred master">
2121 <H3>preferred master (G)</H3>
2122 This boolean parameter controls if Samba is a preferred master browser
2124 If this is set to true, on startup, samba will force an election,
2125 and it will have a slight advantage in winning the election.
2126 It is recommended that this parameter is used in conjunction
2127 with domain master = yes, so that samba can guarantee becoming
2128 a domain master. <p>
2130 Use this option with caution, because if there are several hosts
2131 (whether samba servers, Windows 95 or NT) that are preferred master
2132 browsers on the same subnet, they will each periodically and continuously
2133 attempt to become the local master browser. This will result in
2134 unnecessary broadcast traffic and reduced browsing capabilities.<p>
2140 preferred master = no<p>
2143 This is an alias for "auto services"<p>
2147 This is an alias for "auto services"<p>
2149 <a name="preserve case">
2150 <H3>preserve case (S)</H3><p>
2152 This controls if new filenames are created with the case that the
2153 client passes, or if they are forced to be the "default" case.<p>
2156 preserve case = no<p>
2158 See the section on "NAME MANGLING" for a fuller discussion.<p>
2160 <a name="print command">
2161 <H3>print command (S)</H3>
2162 After a print job has finished spooling to a service, this command will be
2163 used via a system() call to process the spool file. Typically the command
2164 specified will submit the spool file to the host's printing subsystem, but
2165 there is no requirement that this be the case. The server will not remove the
2166 spool file, so whatever command you specify should remove the spool file when
2167 it has been processed, otherwise you will need to manually remove old spool
2170 The print command is simply a text string. It will be used verbatim,
2171 with two exceptions: All occurrences of "%s" will be replaced by the
2172 appropriate spool file name, and all occurrences of "%p" will be
2173 replaced by the appropriate printer name. The spool file name is
2174 generated automatically by the server, the printer name is discussed
2177 The full path name will be used for the filename if %s is not preceded
2178 by a /. If you don't like this (it can stuff up some lpq output) then
2179 use %f instead. Any occurrences of %f get replaced by the spool
2180 filename without the full path at the front.<p>
2182 The print command MUST contain at least one occurrence of "%s" or %f -
2183 the "%p" is optional. At the time a job is submitted, if no printer
2184 name is supplied the "%p" will be silently removed from the printer
2187 If specified in the [global] section, the print command given will be used
2188 for any printable service that does not have its own print command specified.<p>
2190 If there is neither a specified print command for a printable service nor a
2191 global print command, spool files will be created but not processed and (most
2192 importantly) not removed.<p>
2194 Note that printing may fail on some UNIXes from the "nobody"
2195 account. If this happens then create an alternative guest account that
2196 can print and set the "guest account" in the [global] section.<p>
2198 You can form quite complex print commands by realising that they are
2199 just passed to a shell. For example the following will log a print
2200 job, print the file, then remove it. Note that ; is the usual
2201 separator for command in shell scripts.<p>
2203 print command = echo Printing %s >> /tmp/print.log; lpr -P %p %s; rm %s<p>
2205 You may have to vary this command considerably depending on how you
2206 normally print files on your system.<p>
2209 print command = lpr -r -P %p %s<p>
2212 print command = /usr/local/samba/bin/myprintscript %p %s
2214 <H3>print ok (S)</H3>
2217 <a name="printable">
2218 <H3>printable (S)</H3>
2219 A synonym for this parameter is 'print ok'.<p>
2221 If this parameter is 'yes', then clients may open, write to and submit spool
2222 files on the directory specified for the service.<p>
2224 Note that a printable service will ALWAYS allow writing to the service path
2225 (user privileges permitting) via the spooling of print data. The 'read only'
2226 parameter controls only non-printing access to the resource.<p>
2234 <a name="printcap name">
2235 <H3>printcap name (G)</H3>
2236 This parameter may be used to override the compiled-in default printcap
2237 name used by the server (usually /etc/printcap). See the discussion of the
2238 [printers] section above for reasons why you might want to do this.<p>
2240 On SystemV systems that use lpstat to list available printers you
2241 can use "printcap name = lpstat" to automatically obtain lists of
2242 available printers. This is the default for systems that define
2243 SYSV at compile time in Samba (this includes most SystemV based
2244 systems). If "printcap name" is set to lpstat on these systems then
2245 Samba will launch "lpstat -v" and attempt to parse the output to
2246 obtain a printer list.<p>
2248 A minimal printcap file would look something like this:<p>
2258 print5|My Printer 5<p>
2260 where the | separates aliases of a printer. The fact that the second
2261 alias has a space in it gives a hint to Samba that it's a comment.<p>
2263 NOTE: Under AIX the default printcap name is "/etc/qconfig". Samba
2264 will assume the file is in AIX "qconfig" format if the string
2265 "/qconfig" appears in the printcap filename.<p>
2268 printcap name = /etc/printcap<p>
2271 printcap name = /etc/myprintcap<p>
2274 <H3>printer (S)</H3>
2275 A synonym for this parameter is 'printer name'.<p>
2277 This parameter specifies the name of the printer to which print jobs spooled
2278 through a printable service will be sent.<p>
2280 If specified in the [global] section, the printer name given will be used
2281 for any printable service that does not have its own printer name specified.<p>
2284 none (but may be 'lp' on many systems)<p>
2287 printer name = laserwriter<p>
2289 <a name="printer driver">
2290 <H3>printer driver (S)</H3>
2291 This option allows you to control the string that clients receive when
2292 they ask the server for the printer driver associated with a
2293 printer. If you are using Windows95 or WindowsNT then you can use this
2294 to automate the setup of printers on your system.<p>
2296 You need to set this parameter to the exact string (case sensitive)
2297 that describes the appropriate printer driver for your system.
2298 If you don't know the exact string to use then you should first try
2299 with no "printer driver" option set and the client will give you a
2300 list of printer drivers. The appropriate strings are shown in a
2301 scrollbox after you have chosen the printer manufacturer.<p>
2304 printer driver = HP LaserJet 4L<p>
2306 <a name="printer name">
2307 <H3>printer name (S)</H3>
2311 <a name="printer driver file">
2312 <H3>printer driver file (G)</H3>
2313 This parameter tells Samba where the printer driver definition file,
2314 used when serving drivers to Windows 95 clients, is to be found. If
2315 this is not set, the default is :<p>
2317 SAMBA_INSTALL_DIRECTORY/lib/printers.def<p>
2319 This file is created from Windows 95 'msprint.def' files found on the
2320 Windows 95 client system. For more details on setting up serving of
2321 printer drivers to Windows 95 clients, see the documentation file
2322 docs/PRINTER_DRIVER.txt.<p>
2325 None (set in compile).<p>
2328 printer driver file = /usr/local/samba/printers/drivers.def<p>
2331 .B printer driver location<p>
2333 <a name="printer driver location">
2334 <H3>printer driver location (S)</H3>
2335 This parameter tells clients of a particular printer share where
2336 to find the printer driver files for the automatic installation
2337 of drivers for Windows 95 machines. If Samba is set up to serve
2338 printer drivers to Windows 95 machines, this should be set to<p>
2340 \e\eMACHINE\ePRINTER$<p>
2342 Where MACHINE is the NetBIOS name of your Samba server, and PRINTER$
2343 is a share you set up for serving printer driver files. For more
2344 details on setting this up see the documentation file
2345 docs/PRINTER_DRIVER.txt.<p>
2351 printer driver location = \e\eMACHINE\ePRINTER$<p>
2354 .B printer driver file<p>
2358 <H3>printing (S)</H3>
2359 This parameters controls how printer status information is interpreted
2360 on your system, and also affects the default values for the "print
2361 command", "lpq command" and "lprm command".<p>
2363 Currently six printing styles are supported. They are "printing =
2364 bsd", "printing = sysv", "printing = hpux", "printing = aix",
2365 "printing = qnx" and "printing = plp".<p>
2367 To see what the defaults are for the other print commands when using
2368 these three options use the "testparm" program.<p>
2370 As of version 1.9.18 of Samba this option can be set on a per printer basis<p>
2373 <H3>protocol (G)</H3>
2374 The value of the parameter (a string) is the highest protocol level that will
2375 be supported by the server. <p>
2377 Possible values are CORE, COREPLUS, LANMAN1, LANMAN2 and NT1. The relative
2378 merits of each are discussed in the README file.<p>
2380 Normally this option should not be set as the automatic negotiation
2381 phase in the SMB protocol takes care of choosing the appropriate protocol.<p>
2390 A synonym for this parameter is 'guest ok'.<p>
2392 If this parameter is 'yes' for a service, then no password is required
2393 to connect to the service. Privileges will be those of the guest
2396 See the section below on user/password validation for more information about
2404 <a name="read list">
2405 <H3>read list (S)</H3>
2406 This is a list of users that are given read-only access to a
2407 service. If the connecting user is in this list then they will
2408 not be given write access, no matter what the "read only" option
2409 is set to. The list can include group names using the @group syntax.<p>
2411 See also the "write list" option<p>
2417 read list = mary, @students<p>
2419 <a name="read only">
2420 <H3>read only (S)</H3>
2425 Note that this is an inverted synonym for writable and write ok.
2426 <a name="read prediction">
2427 <H3>read prediction (G)</H3>
2428 This options enables or disables the read prediction code used to
2429 speed up reads from the server. When enabled the server will try to
2430 pre-read data from the last accessed file that was opened read-only
2431 while waiting for packets.<p>
2434 read prediction = False<p>
2437 read prediction = True
2438 <a name="Default:</H3>
2439 read prediction = False<p>
2442 read prediction = True
2444 <H3>read raw (G)</H3>
2445 This parameter controls whether or not the server will support raw reads when
2446 transferring data to clients.<p>
2448 If enabled, raw reads allow reads of 65535 bytes in one packet. This
2449 typically provides a major performance benefit.<p>
2451 However, some clients either negotiate the allowable block size incorrectly
2452 or are incapable of supporting larger block sizes, and for these clients you
2453 may need to disable raw reads.<p>
2455 In general this parameter should be viewed as a system tuning tool and left
2456 severely alone. See also
2464 <a name="read size">
2465 <H3>read size (G)</H3><p>
2467 The option "read size" affects the overlap of disk reads/writes with
2468 network reads/writes. If the amount of data being transferred in
2469 several of the SMB commands (currently SMBwrite, SMBwriteX and
2470 SMBreadbraw) is larger than this value then the server begins writing
2471 the data before it has received the whole packet from the network, or
2472 in the case of SMBreadbraw, it begins writing to the network before
2473 all the data has been read from disk.<p>
2475 This overlapping works best when the speeds of disk and network access
2476 are similar, having very little effect when the speed of one is much
2477 greater than the other.<p>
2479 The default value is 2048, but very little experimentation has been
2480 done yet to determine the optimal value, and it is likely that the best
2481 value will vary greatly between systems anyway. A value over 65536 is
2482 pointless and will cause you to allocate memory unnecessarily.<p>
2490 <a name="remote announce">
2491 <H3>remote announce (G)</H3><p>
2493 This option allows you to setup nmbd to periodically announce itself
2494 to arbitrary IP addresses with an arbitrary workgroup name. <p>
2496 This is useful if you want your Samba server to appear in a remote
2497 workgroup for which the normal browse propagation rules don't
2498 work. The remote workgroup can be anywhere that you can send IP
2503 remote announce = 192.168.2.255/SERVERS 192.168.4.255/STAFF<p>
2505 the above line would cause nmbd to announce itself to the two given IP
2506 addresses using the given workgroup names. If you leave out the
2507 workgroup name then the one given in the "workgroup" option is used
2510 The IP addresses you choose would normally be the broadcast addresses
2511 of the remote networks, but can also be the IP addresses of known
2512 browse masters if your network config is that stable.<p>
2514 This option replaces similar functionality from the nmbd lmhosts file.<p>
2516 <a name="remote browse sync">
2517 <H3>remote browse sync (G)</H3><p>
2519 This option allows you to setup nmbd to periodically request synchronisation
2520 of browse lists with the master browser of a samba server that is on a remote
2521 segment. This option will allow you to gain browse lists for multiple
2522 workgroups across routed networks. This is done in a manner that does not work
2523 with any non-samba servers.<p>
2525 This is useful if you want your Samba server and all local clients
2526 to appear in a remote workgroup for which the normal browse propagation
2527 rules don't work. The remote workgroup can be anywhere that you can send IP
2532 remote browse sync = 192.168.2.255 192.168.4.255<p>
2534 the above line would cause nmbd to request the master browser on the
2535 specified subnets or addresses to synchronise their browse lists with
2536 the local server.<p>
2538 The IP addresses you choose would normally be the broadcast addresses
2539 of the remote networks, but can also be the IP addresses of known
2540 browse masters if your network config is that stable. If a machine IP
2541 address is given Samba makes NO attempt to validate that the remote
2542 machine is available, is listening, nor that it is in fact the browse
2543 master on it's segment.<p>
2546 <a name="revalidate">
2547 <H3>revalidate (S)</H3><p>
2549 This options controls whether Samba will allow a previously validated
2550 username/password pair to be used to attach to a share. Thus if you
2551 connect to \e\eserver\eshare1 then to \e\eserver\eshare2 it won't
2552 automatically allow the client to request connection to the second
2553 share as the same username as the first without a password.<p>
2555 If "revalidate" is True then the client will be denied automatic
2556 access as the same username.<p>
2559 revalidate = False<p>
2562 revalidate = True<p>
2569 <H3>root dir (G)</H3>
2572 <a name="root directory">
2573 <H3>root directory (G)</H3>
2574 Synonyms for this parameter are 'root dir' and 'root'.<p>
2576 The server will chroot() to this directory on startup. This is not
2577 strictly necessary for secure operation. Even without it the server
2578 will deny access to files not in one of the service entries. It may
2579 also check for, and deny access to, soft links to other parts of the
2580 filesystem, or attempts to use .. in file names to access other
2581 directories (depending on the setting of the "wide links" parameter).<p>
2583 Adding a "root dir" entry other than "/" adds an extra level of security,
2584 but at a price. It absolutely ensures that no access is given to files not
2585 in the sub-tree specified in the "root dir" option, *including* some files
2586 needed for complete operation of the server. To maintain full operability
2587 of the server you will need to mirror some system files into the "root dir"
2588 tree. In particular you will need to mirror /etc/passwd (or a subset of it),
2589 and any binaries or configuration files needed for printing (if required).
2590 The set of files that must be mirrored is operating system dependent.<p>
2593 root directory = /<p>
2596 root directory = /homes/smb
2597 <a name="root postexec">
2598 <H3>root postexec (S)</H3><p>
2600 This is the same as postexec except that the command is run as
2601 root. This is useful for unmounting filesystems (such as cdroms) after
2602 a connection is closed.<p>
2604 <a name="root preexec">
2605 <H3>root preexec (S)</H3><p>
2607 This is the same as preexec except that the command is run as
2608 root. This is useful for mounting filesystems (such as cdroms) before
2609 a connection is finalised.<p>
2612 <H3>security (G)</H3>
2613 This option affects how clients respond to Samba.<p>
2615 The option sets the "security mode bit" in replies to protocol negotiations
2616 to turn share level security on or off. Clients decide based on this bit
2617 whether (and how) to transfer user and password information to the server.<p>
2619 The default is "security=SHARE", mainly because that was the only
2620 option at one stage.<p>
2622 The alternatives are "security = user" or "security = server". <p>
2624 If your PCs use usernames that are the same as their usernames on the
2625 UNIX machine then you will want to use "security = user". If you
2626 mostly use usernames that don't exist on the UNIX box then use
2627 "security = share".<p>
2629 There is a bug in WfWg that may affect your decision. When in user
2630 level security a WfWg client will totally ignore the password you type
2631 in the "connect drive" dialog box. This makes it very difficult (if
2632 not impossible) to connect to a Samba service as anyone except the
2633 user that you are logged into WfWg as.<p>
2635 If you use "security = server" then Samba will try to validate the
2636 username/password by passing it to another SMB server, such as an NT
2637 box. If this fails it will revert to "security = USER".<p>
2639 See the "password server" option for more details.<p>
2646 <a name="server string">
2647 <H3>server string (G)</H3>
2648 This controls what string will show up in the printer comment box in
2649 print manager and next to the IPC connection in "net view". It can be
2650 any string that you wish to show to your users.<p>
2652 It also sets what will appear in browse lists next to the machine name.<p>
2654 A %v will be replaced with the Samba version number.<p>
2656 A %h will be replaced with the hostname.<p>
2659 server string = Samba %v<p>
2662 server string = University of GNUs Samba Server<p>
2664 <a name="set directory">
2665 <H3>set directory (S)</H3>
2666 If 'set directory = no', then users of the service may not use the setdir
2667 command to change directory.<p>
2669 The setdir command is only implemented in the Digital Pathworks client. See the
2670 Pathworks documentation for details.<p>
2673 set directory = no<p>
2676 set directory = yes<p>
2678 <a name="shared file entries">
2679 <H3>shared file entries (G)</H3>
2680 This parameter has been removed (as of Samba 1.9.18 and above). The new
2681 System V shared memory code prohibits the user from allocating the
2682 share hash bucket size directly.<p>
2684 <a name="shared mem size">
2685 <H3>shared mem size (G)</H3>
2686 This parameter is only useful when Samba has been compiled with FAST_SHARE_MODES.
2687 It specifies the size of the shared memory (in bytes) to use between smbd
2688 processes. You should never change this parameter unless you have studied
2689 the source and know what you are doing. This parameter defaults to 1024
2690 multiplied by the setting of the maximum number of open files in the
2691 file local.h in the Samba source code. MAX_OPEN_FILES is normally set
2692 to 100, so this parameter defaults to 102400 bytes.<p>
2695 shared mem size = 102400<p>
2697 <a name="smb passwd file">
2698 <H3>smb passwd file (G)</H3>
2699 This option sets the path to the encrypted smbpasswd file. This is a *VERY
2700 DANGEROUS OPTION* if the smb.conf is user writable. By default the path
2701 to the smbpasswd file is compiled into Samba.<p>
2705 This sets the full path to the smbrun binary. This defaults to the
2706 value in the Makefile.<p>
2708 You must get this path right for many services to work correctly.<p>
2711 taken from Makefile<p>
2714 smbrun = /usr/local/samba/bin/smbrun<p>
2716 <a name="share modes">
2717 <H3>share modes (S)</H3><p>
2719 This enables or disables the honouring of the "share modes" during a
2720 file open. These modes are used by clients to gain exclusive read or
2721 write access to a file. <p>
2723 These open modes are not directly supported by UNIX, so they are
2724 simulated using lock files in the "lock directory". The "lock
2725 directory" specified in smb.conf must be readable by all users.<p>
2727 The share modes that are enabled by this option are DENY_DOS,
2728 DENY_ALL, DENY_READ, DENY_WRITE, DENY_NONE and DENY_FCB.<p>
2730 Enabling this option gives full share compatibility but may cost a bit
2731 of processing time on the UNIX server. They are enabled by default.<p>
2734 share modes = yes<p>
2739 <a name="short preserve case">
2740 <H3>short preserve case (S)</H3><p>
2742 This controls if new short filenames are created with the case that
2743 the client passes, or if they are forced to be the "default" case.<p>
2746 short preserve case = no<p>
2748 See the section on "NAME MANGLING" for a fuller discussion.<p>
2750 <a name="socket address">
2751 <H3>socket address (G)</H3><p>
2753 This option allows you to control what address Samba will listen for
2754 connections on. This is used to support multiple virtual interfaces on
2755 the one server, each with a different configuration.<p>
2757 By default samba will accept connections on any address.<p>
2760 socket address = 192.168.2.20<p>
2762 <a name="socket options">
2763 <H3>socket options (G)</H3>
2764 This option (which can also be invoked with the -O command line
2765 option) allows you to set socket options to be used when talking with
2768 Socket options are controls on the networking layer of the operating
2769 systems which allow the connection to be tuned.<p>
2771 This option will typically be used to tune your Samba server for
2772 optimal performance for your local network. There is no way that Samba
2773 can know what the optimal parameters are for your net, so you must
2774 experiment and choose them yourself. I strongly suggest you read the
2775 appropriate documentation for your operating system first (perhaps
2776 "man setsockopt" will help).<p>
2778 You may find that on some systems Samba will say "Unknown socket
2779 option" when you supply an option. This means you either mis-typed it
2780 or you need to add an include file to includes.h for your OS. If the
2781 latter is the case please send the patch to me
2782 (samba-bugs@samba.anu.edu.au).<p>
2784 Any of the supported socket options may be combined in any way you
2785 like, as long as your OS allows it.<p>
2787 This is the list of socket options currently settable using this
2810 Those marked with a * take an integer argument. The others can
2811 optionally take a 1 or 0 argument to enable or disable the option, by
2812 default they will be enabled if you don't specify 1 or 0.<p>
2814 To specify an argument use the syntax SOME_OPTION=VALUE for example
2815 SO_SNDBUF=8192. Note that you must not have any spaces before or after
2818 If you are on a local network then a sensible option might be<p>
2820 socket options = IPTOS_LOWDELAY<p>
2822 If you have an almost unloaded local network and you don't mind a lot
2823 of extra CPU usage in the server then you could try<p>
2825 socket options = IPTOS_LOWDELAY TCP_NODELAY<p>
2827 If you are on a wide area network then perhaps try setting
2828 IPTOS_THROUGHPUT. <p>
2830 Note that several of the options may cause your Samba server to fail
2831 completely. Use these options with caution!<p>
2834 no socket options<p>
2837 socket options = IPTOS_LOWDELAY <p>
2844 This enables or disables logging of connections to a status file that
2850 won't be able to tell you what
2851 connections are active.<p>
2859 <a name="strict locking">
2860 <H3>strict locking (S)</H3>
2861 This is a boolean that controls the handling of file locking in the
2862 server. When this is set to yes the server will check every read and
2863 write access for file locks, and deny access if locks exist. This can
2864 be slow on some systems.<p>
2866 When strict locking is "no" the server does file lock checks only when
2867 the client explicitly asks for them. <p>
2869 Well behaved clients always ask for lock checks when it is important,
2870 so in the vast majority of cases "strict locking = no" is preferable.<p>
2873 strict locking = no<p>
2876 strict locking = yes<p>
2878 <a name="strip dot">
2879 <H3>strip dot (G)</H3>
2880 This is a boolean that controls whether to strip trailing dots off
2881 UNIX filenames. This helps with some CDROMs that have filenames ending in a
2892 This parameter maps how Samba debug messages are logged onto the
2893 system syslog logging levels. Samba debug level zero maps onto
2894 syslog LOG_ERR, debug level one maps onto LOG_WARNING, debug
2895 level two maps to LOG_NOTICE, debug level three maps onto LOG_INFO.
2896 The paramter sets the threshold for doing the mapping, all Samba
2897 debug messages above this threashold are mapped to syslog LOG_DEBUG
2904 <a name="syslog only">
2905 <H3>syslog only (G)</H3>
2906 If this parameter is set then Samba debug messages are logged into
2907 the system syslog only, and not to the debug log files.<p>
2912 <a name="sync always">
2913 <H3>sync always (S)</H3><p>
2915 This is a boolean parameter that controls whether writes will always
2916 be written to stable storage before the write call returns. If this is
2917 false then the server will be guided by the client's request in each
2918 write call (clients can set a bit indicating that a particular write
2919 should be synchronous). If this is true then every write will be
2920 followed by a fsync() call to ensure the data is written to disk.<p>
2926 sync always = yes<p>
2928 <a name="time offset">
2929 <H3>time offset (G)</H3>
2930 This parameter is a setting in minutes to add to the normal GMT to
2931 local time conversion. This is useful if you are serving a lot of PCs
2932 that have incorrect daylight saving time handling.<p>
2940 <a name="time server">
2941 <H3>time server (G)</H3>
2942 This parameter determines if nmbd advertises itself as a time server
2943 to Windows clients. The default is False.<p>
2946 time server = False<p>
2949 time server = True<p>
2951 <a name="unix realname">
2952 <H3>unix realname (G)</H3>
2953 This boolean parameter when set causes samba to supply the real name field
2954 from the unix password file to the client. This is useful for setting up
2955 mail clients and WWW browsers on systems used by more than one person.<p>
2958 unix realname = no<p>
2961 unix realname = yes<p>
2968 <H3>username (S)</H3>
2969 A synonym for this parameter is 'user'.<p>
2971 Multiple users may be specified in a comma-delimited list, in which case the
2972 supplied password will be tested against each username in turn (left to right).<p>
2974 The username= line is needed only when the PC is unable to supply its own
2975 username. This is the case for the coreplus protocol or where your
2976 users have different WfWg usernames to UNIX usernames. In both these
2977 cases you may also be better using the \e\eserver\eshare%user syntax
2980 The username= line is not a great solution in many cases as it means Samba
2981 will try to validate the supplied password against each of the
2982 usernames in the username= line in turn. This is slow and a bad idea for
2983 lots of users in case of duplicate passwords. You may get timeouts or
2984 security breaches using this parameter unwisely.<p>
2986 Samba relies on the underlying UNIX security. This parameter does not
2987 restrict who can login, it just offers hints to the Samba server as to
2988 what usernames might correspond to the supplied password. Users can
2989 login as whoever they please and they will be able to do no more
2990 damage than if they started a telnet session. The daemon runs as the
2991 user that they log in as, so they cannot do anything that user cannot
2994 To restrict a service to a particular set of users you can use the
2995 "valid users=" line.<p>
2997 If any of the usernames begin with a @ then the name will be looked up
2998 in the groups file and will expand to a list of all users in the group
2999 of that name. Note that searching though a groups file can take quite
3000 some time, and some clients may time out during the search.<p>
3002 See the section below on username/password validation for more information
3003 on how this parameter determines access to the services.<p>
3006 The guest account if a guest service, else the name of the service.<p>
3010 username = fred, mary, jack, jane, @users, @pcgroup<p>
3012 <a name="username level">
3013 <H3>username level (G)</H3><p>
3015 This option helps Samba to try and 'guess' at the real UNIX username,
3016 as many DOS clients send an all-uppercase username. By default Samba
3017 tries all lowercase, followed by the username with the first letter
3018 capitalized, and fails if the username is not found on the UNIX machine.<p>
3020 If this parameter is set to non-zero the behaviour changes. This
3021 parameter is a number that specifies the number of uppercase combinations
3022 to try whilst trying to determine the UNIX user name. The higher the number
3023 the more combinations will be tried, but the slower the discovery
3024 of usernames will be. Use this parameter when you have strange
3025 usernames on your UNIX machine, such as 'AstrangeUser'.<p>
3028 username level = 0<p>
3031 username level = 5<p>
3033 <a name="username map">
3034 <H3>username map (G)</H3><p>
3036 This option allows you to to specify a file containing a mapping of
3037 usernames from the clients to the server. This can be used for several
3038 purposes. The most common is to map usernames that users use on DOS or
3039 Windows machines to those that the UNIX box uses. The other is to map
3040 multiple users to a single username so that they can more easily share
3043 The map file is parsed line by line. Each line should contain a single
3044 UNIX username on the left then a '=' followed by a list of usernames
3045 on the right. The list of usernames on the right may contain names of
3046 the form @group in which case they will match any UNIX username in
3047 that group. The special client name '*' is a wildcard and matches any
3050 The file is processed on each line by taking the supplied username and
3051 comparing it with each username on the right hand side of the '='
3052 signs. If the supplied name matches any of the names on the right
3053 hand side then it is replaced with the name on the left. Processing
3054 then continues with the next line.<p>
3056 If any line begins with a '#' or a ';' then it is ignored<p>
3058 If any line begins with an ! then the processing will stop after that
3059 line if a mapping was done by the line. Otherwise mapping continues
3060 with every line being processed. Using ! is most useful when you have
3061 a wildcard mapping line later in the file.<p>
3063 For example to map from the name "admin" or "administrator" to the UNIX
3064 name "root" you would use<p>
3066 root = admin administrator<p>
3068 Or to map anyone in the UNIX group "system" to the UNIX name "sys" you
3073 You can have as many mappings as you like in a username map file.<p>
3075 You can map Windows usernames that have spaces in them by using double
3076 quotes around the name. For example:<p>
3078 tridge = "Andrew Tridgell"<p>
3080 would map the windows username "Andrew Tridgell" to the unix username
3083 The following example would map mary and fred to the unix user sys,
3084 and map the rest to guest. Note the use of the ! to tell Samba to stop
3085 processing if it gets a match on that line.<p>
3091 Note that the remapping is applied to all occurrences of
3092 usernames. Thus if you connect to "\e\eserver\efred" and "fred" is
3093 remapped to "mary" then you will actually be connecting to
3094 "\e\eserver\emary" and will need to supply a password suitable for
3095 "mary" not "fred". The only exception to this is the username passed
3096 to the "password server" (if you have one). The password server will
3097 receive whatever username the client supplies without modification.<p>
3099 Also note that no reverse mapping is done. The main effect this has is
3100 with printing. Users who have been mapped may have trouble deleting
3101 print jobs as PrintManager under WfWg will think they don't own the
3108 username map = /usr/local/samba/lib/users.map<p>
3110 <a name="valid chars">
3111 <H3>valid chars (S)</H3><p>
3113 The option allows you to specify additional characters that should be
3114 considered valid by the server in filenames. This is particularly
3115 useful for national character sets, such as adding u-umlaut or a-ring.<p>
3117 The option takes a list of characters in either integer or character
3118 form with spaces between them. If you give two characters with a colon
3119 between them then it will be taken as an lowercase:uppercase pair.<p>
3121 If you have an editor capable of entering the characters into the
3122 config file then it is probably easiest to use this method. Otherwise
3123 you can specify the characters in octal, decimal or hexadecimal form
3124 using the usual C notation.<p>
3126 For example to add the single character 'Z' to the charset (which is a
3127 pointless thing to do as it's already there) you could do one of the
3132 valid chars = 0132:0172<p>
3134 The last two examples above actually add two characters, and alter
3135 the uppercase and lowercase mappings appropriately.<p>
3137 Note that you MUST specify this parameter after the "client code page"
3138 parameter if you have both set. If "client code page" is set after
3139 the "valid chars" parameter the "valid chars" settings will be
3142 See also the "client code page" parameter.<p>
3146 Samba defaults to using a reasonable set of valid characters
3148 for english systems<p>
3151 valid chars = 0345:0305 0366:0326 0344:0304<p>
3153 The above example allows filenames to have the swedish characters in
3156 NOTE: It is actually quite difficult to correctly produce a "valid
3157 chars" line for a particular system. To automate the process
3158 tino@augsburg.net has written a package called "validchars" which will
3159 automatically produce a complete "valid chars" line for a given client
3160 system. Look in the examples subdirectory for this package.<p>
3162 <a name="valid users">
3163 <H3>valid users (S)</H3>
3164 This is a list of users that should be allowed to login to this
3165 service. A name starting with @ is interpreted as a UNIX group.<p>
3167 If this is empty (the default) then any user can login. If a username
3168 is in both this list and the "invalid users" list then access is
3169 denied for that user.<p>
3171 The current servicename is substituted for %S. This is useful in the
3174 See also "invalid users"<p>
3177 No valid users list. (anyone can login)<p>
3180 valid users = greg, @pcusers<p>
3183 <a name="veto file">
3184 <H3>veto files(S)</H3>
3185 This is a list of files and directories that are neither visible nor
3186 accessible. Each entry in the list must be separated by a "/", which
3187 allows spaces to be included in the entry. '*' and '?' can be used to
3188 specify multiple files or directories as in DOS wildcards.<p>
3190 Each entry must be a unix path, not a DOS path and must not include the
3191 unix directory separator "/".<p>
3193 Note that the case sensitivity option is applicable in vetoing files.<p>
3195 One feature of the veto files parameter that it is important to be
3196 aware of, is that if a directory contains nothing but files that
3197 match the veto files parameter (which means that Windows/DOS clients
3198 cannot ever see them) is deleted, the veto files within that directory
3199 *are automatically deleted* along with it, if the user has UNIX permissions
3202 Setting this parameter will affect the performance of Samba, as
3203 it will be forced to check all files and directories for a match
3204 as they are scanned.<p>
3206 See also "hide files" and "case sensitive"<p>
3209 No files or directories are vetoed.<p>
3213 Veto any files containing the word Security,
3214 any ending in .tmp, and any directory containing the
3217 veto files = /*Security*/*.tmp/*root*/<p>
3220 Veto the Apple specific files that a NetAtalk server
3223 veto files = /.AppleDouble/.bin/.AppleDesktop/Network Trash Folder/<p>
3225 <a name="veto oplock files">
3226 <H3>veto oplock files (S)</H3>
3227 This parameter is only valid when the 'oplocks' parameter is turned on
3228 for a share. It allows the Samba administrator to selectively turn off
3229 the granting of oplocks on selected files that match a wildcarded list,
3230 similar to the wildcarded list used in the 'veto files' parameter.<p>
3233 No files are vetoed for oplock grants.<p>
3236 You might want to do this on files that you know will be heavily
3237 contended for by clients. A good example of this is in the NetBench
3238 SMB benchmark program, which causes heavy client contention for files
3239 ending in .SEM. To cause Samba not to grant oplocks on these files
3240 you would use the line (either in the [global] section or in the section
3241 for the particular NetBench share :<p>
3243 veto oplock files = /*.SEM/<p>
3247 This allows you to override the volume label returned for a
3248 share. Useful for CDROMs with installation programs that insist on a
3249 particular volume label.<p>
3251 The default is the name of the share<p>
3253 <a name="wide links">
3254 <H3>wide links (S)</H3>
3255 This parameter controls whether or not links in the UNIX file system may be
3256 followed by the server. Links that point to areas within the directory tree
3257 exported by the server are always allowed; this parameter controls access
3258 only to areas that are outside the directory tree being exported.<p>
3266 <a name="wins proxy">
3267 <H3>wins proxy (G)</H3><p>
3269 This is a boolean that controls if nmbd will respond to broadcast name
3270 queries on behalf of other hosts. You may need to set this to no for
3271 some older clients.<p>
3275 <a name="wins server">
3276 <H3>wins server (G)</H3><p>
3278 This specifies the DNS name (or IP address) of the WINS server that Samba
3279 should register with. If you have a WINS server on your network then you
3280 should set this to the WINS servers name.<p>
3282 You should point this at your WINS server if you have a multi-subnetted
3287 <a name="wins support">
3288 <H3>wins support (G)</H3><p>
3290 This boolean controls if the nmbd process in Samba will act as a WINS server.
3291 You should not set this to true unless you have a multi-subnetted network and
3292 you wish a particular nmbd to be your WINS server. Note that you
3293 should *NEVER* set this to true on more than one machine in your
3297 wins support = no<p>
3299 <a name="workgroup">
3300 <H3>workgroup (G)</H3><p>
3302 This controls what workgroup your server will appear to be in when
3303 queried by clients. <p>
3306 set in the Makefile<p>
3309 workgroup = MYGROUP<p>
3312 <H3>writable (S)</H3>
3313 A synonym for this parameter is 'write ok'. An inverted synonym is 'read only'.<p>
3315 If this parameter is 'no', then users of a service may not create or modify
3316 files in the service's directory.<p>
3318 Note that a printable service ('printable = yes') will ALWAYS allow
3319 writing to the directory (user privileges permitting), but only via
3320 spooling operations.<p>
3329 <a name="write list">
3330 <H3>write list (S)</H3>
3331 This is a list of users that are given read-write access to a
3332 service. If the connecting user is in this list then they will be
3333 given write access, no matter what the "read only" option is set
3334 to. The list can include group names using the @group syntax.<p>
3336 Note that if a user is in both the read list and the write list then
3337 they will be given write access.<p>
3339 See also the "read list" option<p>
3345 write list = admin, root, @staff<p>
3348 <H3>write ok (S)</H3>
3354 <a name="write raw">
3355 <H3>write raw (G)</H3>
3356 This parameter controls whether or not the server will support raw writes when
3357 transferring data from clients.<p>