smb.conf

SMB.CONF(5) SMB.CONF(5)

NAME
smb.conf - The configuration file for the Samba suite

SYNOPSIS
The smb.conf file is a configuration file for the Samba
suite. smb.conf contains runtime configuration information
for the Samba programs. The smb.conf file is designed to
be configured and administered by the swat(8) program. The
complete description of the file format and possible
parameters held within are here for reference purposes.

FILE FORMAT
The file consists of sections and parameters. A section
begins with the name of the section in square brackets and
continues until the next section begins. Sections contain
parameters of the form

name = value

The file is line-based - that is, each newline-terminated
line represents either a comment, a section name or a
parameter.

Section and parameter names are not case sensitive.

Only the first equals sign in a parameter is significant.
Whitespace before or after the first equals sign is dis
carded. Leading, trailing and internal whitespace in sec
tion and parameter names is irrelevant. Leading and trail
ing whitespace in a parameter value is discarded. Internal
whitespace within a parameter value is retained verbatim.

Any line beginning with a semicolon (';') or a hash ('#')
character is ignored, as are lines containing only whites
pace.

Any line ending in a '\' is continued on the next line in
the customary UNIX fashion.

The values following the equals sign in parameters are all
either a string (no quotes needed) or a boolean, which may
be given as yes/no, 0/1 or true/false. Case is not signif
icant in boolean values, but is preserved in string val
ues. Some items such as create modes are numeric.

SECTION DESCRIPTIONS
Each section in the configuration file (except for the
[global] section) describes a shared resource (known as a
"share"). The section name is the name of the shared
resource and the parameters within the section define the
shares attributes.

There are three special sections, [global], [homes] and
[printers], which are described under special sections.
The following notes apply to ordinary section descrip
tions.

A share consists of a directory to which access is being
given plus a description of the access rights which are
granted to the user of the service. Some housekeeping
options are also specifiable.

Sections are either file share services (used by the
client as an extension of their native file systems) or
printable services (used by the client to access print
services on the host running the server).

Sections may be designated guest services, in which case
no password is required to access them. A specified UNIX
guest account is used to define access privileges in this
case.

Sections other than guest services will require a password
to access them. The client provides the username. As older
clients only provide passwords and not usernames, you may
specify a list of usernames to check against the password
using the "user=" option in the share definition. For mod
ern clients such as Windows 95/98/ME/NT/2000, this should
not be necessary.

Note that the access rights granted by the server are
masked by the access rights granted to the specified or
guest UNIX user by the host system. The server does not
grant more access than the host system grants.

The following sample section defines a file space share.
The user has write access to the path /home/bar. The
share is accessed via the share name "foo":

[foo]
path = /home/bar
writeable = true

The following sample section defines a printable share.
The share is readonly, but printable. That is, the only
write access permitted is via calls to open, write to and
close a spool file. The guest ok parameter means access
will be permitted as the default guest user (specified
elsewhere):

[aprinter]
path = /usr/spool/public
writeable = false
printable = true
guest ok = true

SPECIAL SECTIONS
THE GLOBAL SECTION
parameters in this section apply to the server as a whole,
or are defaults for sections which do not specifically
define certain items. See the notes under PARAMETERS for
more information.

THE HOMES SECTION
If a section called homes is included in the configuration
file, services connecting clients to their home directo
ries can be created on the fly by the server.

When the connection request is made, the existing sections
are scanned. If a match is found, it is used. If no match
is found, the requested section name is treated as a user
name and looked up in the local password file. If the name
exists and the correct password has been given, a share is
created by cloning the [homes] section.

Some modifications are then made to the newly created
share:

· The share name is changed from homes to the located
username.

· If no path was given, the path is set to the user's home
directory.

If you decide to use a path= line in your [homes] section
then you may find it useful to use the %S macro. For exam
ple :

path=/data/pchome/%S

would be useful if you have different home directories for
your PCs than for UNIX access.

This is a fast and simple way to give a large number of
clients access to their home directories with a minimum of
fuss.

A similar process occurs if the requested section name is
"homes", except that the share name is not changed to that
of the requesting user. This method of using the [homes]
section works well if different users share a client PC.

The [homes] section can specify all the parameters a nor
mal service section can specify, though some make more
sense than others. The following is a typical and suitable
[homes] section:

[homes]
writeable = yes

An important point is that if guest access is specified in
the [homes] section, all home directories will be visible
to all clients without a password. In the very unlikely
event that this is actually desirable, it would be wise to
also specify read only access.

Note that the browseable flag for auto home directories
will be inherited from the global browseable flag, not the
[homes] browseable flag. This is useful as it means set
ting browseable=no in the [homes] section will hide the
[homes] share but make any auto home directories visible.

THE PRINTERS SECTION
This section works like [homes], but for printers.

If a [printers] section occurs in the configuration file,
users are able to connect to any printer specified in the
local host's printcap file.

When a connection request is made, the existing sections
are scanned. If a match is found, it is used. If no match
is found, but a [homes] section exists, it is used as
described above. Otherwise, the requested section name is
treated as a printer name and the appropriate printcap
file is scanned to see if the requested section name is a
valid printer share name. If a match is found, a new
printer share is created by cloning the [printers] sec
tion.

A few modifications are then made to the newly created
share:

· The share name is set to the located printer name

· If no printer name was given, the printer name is set to
the located printer name

· If the share does not permit guest access and no user
name was given, the username is set to the located
printer name.

Note that the [printers] service MUST be printable - if
you specify otherwise, the server will refuse to load the
configuration file.

Typically the path specified would be that of a world-
writeable spool directory with the sticky bit set on it. A
typical [printers] entry would look like this:

[printers]
path = /usr/spool/public
guest ok = yes
printable = yes

All aliases given for a printer in the printcap file are
legitimate printer names as far as the server is con
cerned. If your printing subsystem doesn't work like
that, you will have to set up a pseudo-printcap. This is a
file consisting of one or more lines like this:

alias|alias|alias|alias...

Each alias should be an acceptable printer name for your
printing subsystem. In the [global] section, specify the
new file as your printcap. The server will then only rec
ognize names found in your pseudo-printcap, which of
course can contain whatever aliases you like. The same
technique could be used simply to limit access to a subset
of your local printers.

An alias, by the way, is defined as any component of the
first entry of a printcap record. Records are separated by
newlines, components (if there are more than one) are sep
arated by vertical bar symbols ('|').

NOTE: On SYSV systems which use lpstat to determine what
printers are defined on the system you may be able to use
"printcap name = lpstat" to automatically obtain a list of
printers. See the "printcap name" option for more details.

PARAMETERS
parameters define the specific attributes of sections.

Some parameters are specific to the [global] section
(e.g., security). Some parameters are usable in all sec
tions (e.g., create mode). All others are permissible only
in normal sections. For the purposes of the following
descriptions the [homes] and [printers] sections will be
considered normal. The letter G in parentheses indicates
that a parameter is specific to the [global] section. The
letter S indicates that a parameter can be specified in a
service specific section. Note that all S parameters can
also be specified in the [global] section - in which case
they will define the default behavior for all services.

parameters are arranged here in alphabetical order - this
may not create best bedfellows, but at least you can find
them! Where there are synonyms, the preferred synonym is
described, others refer to the preferred synonym.

VARIABLE SUBSTITUTIONS
Many of the strings that are settable in the config file
can take substitutions. For example the option "path =
/tmp/%u" would be interpreted as "path = /tmp/john" if the
user connected with the username john.

These substitutions are mostly noted in the descriptions
below, but there are some general substitutions which
apply whenever they might be relevant. These are:

%S the name of the current service, if any.

%P the root directory of the current service, if any.

%u user name of the current service, if any.

%g primary group name of %u.

%U session user name (the user name that the client
wanted, not necessarily the same as the one they
got).

%G primary group name of %U.

%H the home directory of the user given by %u.

%v the Samba version.

%h the Internet hostname that Samba is running on.

%m the NetBIOS name of the client machine (very use
ful).

%L the NetBIOS name of the server. This allows you to
change your config based on what the client calls
you. Your server can have a "dual personality".

%M the Internet name of the client machine.

%N the name of your NIS home directory server. This
is obtained from your NIS auto.map entry. If you
have not compiled Samba with the --with-automount
option then this value will be the same as %.

%p the path of the service's home directory, obtained
from your NIS auto.map entry. The NIS auto.map
entry is split up as "%N:%p".

%R the selected protocol level after protocol negotia
tion. It can be one of CORE, COREPLUS, LANMAN1,
LANMAN2 or NT1.

%d The process id of the current server process.

%a the architecture of the remote machine. Only some
are recognized, and those may not be 100% reliable.
It currently recognizes Samba, WfWg, WinNT and
Win95. Anything else will be known as "UNKNOWN". If
it gets it wrong then sending a level 3 log to
samba@samba.org
<URL:mailto:samba@samba.org> should allow it to be
fixed.

%I The IP address of the client machine.

%T the current date and time.

%$(envvar)
The value of the environment variable envar.

There are some quite creative things that can be done with
these substitutions and other smb.conf options.

NAME MANGLING
Samba supports "name mangling" so that DOS and Windows
clients can use files that don't conform to the 8.3 for
mat. It can also be set to adjust the case of 8.3 format
filenames.

There are several options that control the way mangling is
performed, and they are grouped here rather than listed
separately. For the defaults look at the output of the
testparm program.

All of these options can be set separately for each ser
vice (or globally, of course).

The options are:

mangle case= yes/no
controls if names that have characters that aren't
of the "default" case are mangled. For example, if
this is yes then a name like "Mail" would be man
gled. Default no.

case sensitive = yes/no
controls whether filenames are case sensitive. If
they aren't then Samba must do a filename search
and match on passed names. Default no.

default case = upper/lower
controls what the default case is for new file
names. Default lower.

preserve case = yes/no
controls if new files are created with the case
that the client passes, or if they are forced to be
the "default" case. Default yes.

short preserve case = yes/no
controls if new files which conform to 8.3 syntax,
that is all in upper case and of suitable length,
are created upper case, or if they are forced to be
the "default" case. This option can be use with
"preserve case = yes" to permit long filenames to
retain their case, while short names are lower
cased. Default yes.

By default, Samba 2.2 has the same semantics as a Windows
NT server, in that it is case insensitive but case pre
serving.

NOTE ABOUT USERNAME/PASSWORD VALIDATION
There are a number of ways in which a user can connect to
a service. The server uses the following steps in deter
mining if it will allow a connection to a specified ser
vice. If all the steps fail, then the connection request
is rejected. However, if one of the steps succeeds, then
the following steps are not checked.

If the service is marked "guest only = yes" then steps 1
to 5 are skipped.

1. If the client has passed a username/password pair
and that username/password pair is validated by the
UNIX system's password programs then the connection
is made as that username. Note that this includes
the \\server\service%username method of passing a
username.

2. If the client has previously registered a username
with the system and now supplies a correct password
for that username then the connection is allowed.

3. The client's NetBIOS name and any previously used
user names are checked against the supplied pass
word, if they match then the connection is allowed
as the corresponding user.

4. If the client has previously validated a user
name/password pair with the server and the client
has passed the validation token then that username
is used.

5. If a "user = " field is given in the smb.conf file
for the service and the client has supplied a pass
word, and that password matches (according to the
UNIX system's password checking) with one of the
usernames from the "user=" field then the connec
tion is made as the username in the "user=" line.
If one of the username in the "user=" list begins
with a '@' then that name expands to a list of
names in the group of the same name.

6. If the service is a guest service then a connection
is made as the username given in the "guest account
=" for the service, irrespective of the supplied
password.

COMPLETE LIST OF GLOBAL PARAMETERS
Here is a list of all global parameters. See the section
of each parameter for details. Note that some are syn
onyms.

· add printer command

· add share command

· add user script

· allow trusted domains

· announce as

· announce version

· auto services

· bind interfaces only

· browse list

· change notify timeout

· change share command

· character set

· client code page

· code page directory

· coding system

· config file

· deadtime

· debug hires timestamp

· debug pid

· debug timestamp

· debug uid

· debuglevel

· default

· default service

· delete printer command

· delete share command

· delete user script

· dfree command

· dns proxy

· domain admin group

· domain guest group

· domain logons

· domain master

· encrypt passwords

· enhanced browsing

· enumports command

· getwd cache

· hide local users

· hide unreadable

· homedir map

· host msdfs

· hosts equiv

· interfaces

· keepalive

· kernel oplocks

· lanman auth

· large readwrite

· lm announce

· lm interval

· load printers

· local master

· lock dir

· lock directory

· log file

· log level

· logon drive

· logon home

· logon path

· logon script

· lpq cache time

· machine password timeout

· mangled stack

· map to guest

· max disk size

· max log size

· max mux

· max open files

· max protocol

· max smbd processes

· max ttl

· max wins ttl

· max xmit

· message command

· min passwd length

· min password length

· min protocol

· min wins ttl

· name resolve order

· netbios aliases

· netbios name

· netbios scope

· nis homedir

· nt acl support

· nt pipe support

· nt smb support

· null passwords

· obey pam restrictions

· oplock break wait time

· os level

· os2 driver map

· pam password change

· panic action

· passwd chat

· passwd chat debug

· passwd program

· password level

· password server

· prefered master

· preferred master

· preload

· printcap

· printcap name

· printer driver file

· protocol

· read bmpx

· read raw

· read size

· remote announce

· remote browse sync

· restrict anonymous

· root

· root dir

· root directory

· security

· server string

· show add printer wizard

· smb passwd file

· socket address

· socket options

· source environment

· ssl

· ssl CA certDir

· ssl CA certFile

· ssl ciphers

· ssl client cert

· ssl client key

· ssl compatibility

· ssl hosts

· ssl hosts resign

· ssl require clientcert

· ssl require servercert

· ssl server cert

· ssl server key

· ssl version

· stat cache

· stat cache size

· strip dot

· syslog

· syslog only

· template homedir

· template shell

· time offset

· time server

· timestamp logs

· total print jobs

· unix password sync

· update encrypted

· use rhosts

· username level

· username map

· utmp directory

· valid chars

· winbind cache time

· winbind gid

· winbind separator

· winbind uid

· wins hook

· wins proxy

· wins server

· wins support

· workgroup

· write raw

COMPLETE LIST OF SERVICE PARAMETERS
Here is a list of all service parameters. See the section
on each parameter for details. Note that some are syn
onyms.

· admin users

· allow hosts

· available

· blocking locks

· browsable

· browseable

· case sensitive

· casesignames

· comment

· copy

· create mask

· create mode

· default case

· delete readonly

· delete veto files

· deny hosts

· directory

· directory mask

· directory mode

· directory security mask

· dont descend

· dos filemode

· dos filetime resolution

· dos filetimes

· exec

· fake directory create times

· fake oplocks

· follow symlinks

· force create mode

· force directory mode

· force directory security mode

· force group

· force security mode

· force user

· fstype

· group

· guest account

· guest ok

· guest only

· hide dot files

· hide files

· hosts allow

· hosts deny

· include

· inherit permissions

· invalid users

· level2 oplocks

· locking

· lppause command

· lpq command

· lpresume command

· lprm command

· magic output

· magic script

· mangle case

· mangled map

· mangled names

· mangling char

· map archive

· map hidden

· map system

· max connections

· max print jobs

· min print space

· msdfs root

· only guest

· only user

· oplock contention limit

· oplocks

· path

· posix locking

· postexec

· postscript

· preexec

· preexec close

· preserve case

· print command

· print ok

· printable

· printer

· printer admin

· printer driver

· printer driver location

· printer name

· printing

· public

· queuepause command

· queueresume command

· read list

· read only

· root postexec

· root preexec

· root preexec close

· security mask

· set directory

· share modes

· short preserve case

· status

· strict locking

· strict sync

· sync always

· user

· username

· users

· utmp

· valid users

· veto files

· veto oplock files

· vfs object

· vfs options

· volume

· wide links

· writable

· write cache size

· write list

· write ok

· writeable

EXPLANATION OF EACH PARAMETER
add printer command (G)
With the introduction of MS-RPC based printing sup
port for Windows NT/2000 clients in Samba 2.2, The
MS Add Printer Wizard (APW) icon is now also avail
able in the "Printers..." folder displayed a share
listing. The APW allows for printers to be add
remotely to a Samba or Windows NT/2000 print
server.

For a Samba host this means that the printer must
be physically added to the underlying printing sys
tem. The add printer command defines a script to be
run which will perform the necessary operations for
adding the printer to the print system and to add
the appropriate service definition to the smb.conf
file in order that it can be shared by smbd(8)

The add printer command is automatically invoked
with the following parameter (in order:

· printer name

· share name

· port name

· driver name

· location

· Windows 9x driver location

All parameters are filled in from the PRINTER_INFO_2
structure sent by the Windows NT/2000 client with one
exception. The "Windows 9x driver location" parameter is
included for backwards compatibility only. The remaining
fields in the structure are generated from answers to the
APW questions.

Once the add printer command has been executed, smbd will
reparse the smb.conf to determine if the share defined by
the APW exists. If the sharename is still invalid, then
smbd will return an ACCESS_DENIED error to the client.

See also delete printer command, printing, show add
printer wizard

Default: none

Example: addprinter command = /usr/bin/addprinter

add share command (G)
Samba 2.2.0 introduced the ability to dynamically
add and delete shares via the Windows NT 4.0 Server
Manager. The add share command is used to define an
external program or script which will add a new
service definition to smb.conf. In order to suc
cessfully execute the add share command, smbd
requires that the administrator be connected using
a root account (i.e. uid == 0).

When executed, smbd will automatically invoke the
add share command with four parameters.

· configFile - the location of the global smb.conf
file.

· shareName - the name of the new share.

· pathName - path to an **existing** directory on
disk.

· comment - comment string to associate with the
new share.

This parameter is only used for add file shares. To add
printer shares, see the add printer command.

See also change share command, delete share command.

Default: none

Example: add share command = /usr/local/bin/addshare

add user script (G)
This is the full pathname to a script that will be
run AS ROOT by smbd(8) under special circumstances
described below.

Normally, a Samba server requires that UNIX users
are created for all users accessing files on this
server. For sites that use Windows NT account
databases as their primary user database creating
these users and keeping the user list in sync with
the Windows NT PDC is an onerous task. This option
allows smbdto create the required UNIX users ON
DEMAND when a user accesses the Samba server.

In order to use this option, smbd must be set to
security=server or security=domain and add user
script must be set to a full pathname for a script
that will create a UNIX user given one argument of
%u, which expands into the UNIX user name to cre
ate.

When the Windows user attempts to access the Samba
server, at login (session setup in the SMB proto
col) time, smbdcontacts the password server and
attempts to authenticate the given user with the
given password. If the authentication succeeds then
smbd attempts to find a UNIX user in the UNIX pass
word database to map the Windows user into. If this
lookup fails, and add user script is set then smbd
will call the specified script AS ROOT, expanding
any %u argument to be the user name to create.

If this script successfully creates the user then
smbd will continue on as though the UNIX user
already existed. In this way, UNIX users are dynam
ically created to match existing Windows NT
accounts.

See also security, password server, delete user
script.

Default: add user script = <empty string>

Example: add user script =
/usr/local/samba/bin/add_user %u

admin users (S)
This is a list of users who will be granted admin
istrative privileges on the share. This means that
they will do all file operations as the super-user
(root).

You should use this option very carefully, as any
user in this list will be able to do anything they
like on the share, irrespective of file permis
sions.

Default: no admin users

Example: admin users = jason

allow hosts (S)
Synonym for hosts allow.

allow trusted domains (G)
This option only takes effect when the security
option is set to server or domain. If it is set to
no, then attempts to connect to a resource from a
domain or workgroup other than the one which smbdis
running in will fail, even if that domain is
trusted by the remote server doing the authentica
tion.

This is useful if you only want your Samba server
to serve resources to users in the domain it is a
member of. As an example, suppose that there are
two domains DOMA and DOMB. DOMB is trusted by DOMA,
which contains the Samba server. Under normal cir
cumstances, a user with an account in DOMB can then
access the resources of a UNIX account with the
same account name on the Samba server even if they
do not have an account in DOMA. This can make
implementing a security boundary difficult.

Default: allow trusted domains = yes

announce as (G)
This specifies what type of server nmbd will
announce itself as, to a network neighborhood
browse list. By default this is set to Windows NT.
The valid options are : "NT Server" (which can also
be written as "NT"), "NT Workstation", "Win95" or
"WfW" meaning Windows NT Server, Windows NT Work
station, Windows 95 and Windows for Workgroups
respectively. Do not change this parameter unless
you have a specific need to stop Samba appearing as
an NT server as this may prevent Samba servers from
participating as browser servers correctly.

Default: announce as = NT Server

Example: announce as = Win95

announce version (G)
This specifies the major and minor version numbers
that nmbd will use when announcing itself as a
server. The default is 4.2. Do not change this
parameter unless you have a specific need to set a
Samba server to be a downlevel server.

Default: announce version = 4.2

Example: announce version = 2.0

auto services (G)
This is a synonym for the preload.

available (S)
This parameter lets you "turn off" a service. If
available = no, then ALL attempts to connect to the
service will fail. Such failures are logged.

Default: available = yes

bind interfaces only (G)
This global parameter allows the Samba admin to
limit what interfaces on a machine will serve SMB
requests. If affects file service smbd(8)and name
service nmbd(8)in slightly different ways.

For name service it causes nmbd to bind to ports
137 and 138 on the interfaces listed in the inter
faces parameter. nmbd also binds to the "all
addresses" interface (0.0.0.0) on ports 137 and 138
for the purposes of reading broadcast messages. If
this option is not set then nmbd will service name
requests on all of these sockets. If bind inter
faces only is set then nmbd will check the source
address of any packets coming in on the broadcast
sockets and discard any that don't match the broad
cast addresses of the interfaces in the interfaces
parameter list. As unicast packets are received on
the other sockets it allows nmbd to refuse to serve
names to machines that send packets that arrive
through any interfaces not listed in the interfaces
list. IP Source address spoofing does defeat this
simple check, however so it must not be used seri
ously as a security feature for nmbd.

For file service it causes smbd(8) to bind only to
the interface list given in the interfaces parame
ter. This restricts the networks that smbd will
serve to packets coming in those interfaces. Note
that you should not use this parameter for machines
that are serving PPP or other intermittent or non-
broadcast network interfaces as it will not cope
with non-permanent interfaces.

If bind interfaces only is set then unless the net
work address 127.0.0.1 is added to the interfaces
parameter list smbpasswd(8) and swat(8)may not work
as expected due to the reasons covered below.

To change a users SMB password, the smbpasswd by
default connects to the localhost - 127.0.0.1
address as an SMB client to issue the password
change request. If bind interfaces only is set then
unless the network address 127.0.0.1 is added to
the interfaces parameter list then smbpasswd will
fail to connect in it's default mode. smbpasswd
can be forced to use the primary IP interface of
the local host by using its -r remote machine
parameter, with remote machine set to the IP name
of the primary interface of the local host.

The swat status page tries to connect with smbd and
nmbd at the address 127.0.0.1 to determine if they
are running. Not adding 127.0.0.1 will cause smbd
and nmbd to always show "not running" even if they
really are. This can prevent swat from start
ing/stopping/restarting smbd and nmbd.

Default: bind interfaces only = no

blocking locks (S)
This parameter controls the behavior of smbd(8)when
given a request by a client to obtain a byte range
lock on a region of an open file, and the request
has a time limit associated with it.

If this parameter is set and the lock range
requested cannot be immediately satisfied, Samba
2.2 will internally queue the lock request, and
periodically attempt to obtain the lock until the
timeout period expires.

If this parameter is set to false, then Samba 2.2
will behave as previous versions of Samba would and
will fail the lock request immediately if the lock
range cannot be obtained.

Default: blocking locks = yes

browsable (S)
See the browseable.

browse list (G)
This controls whether smbd(8)will serve a browse
list to a client doing a NetServerEnum call. Nor
mally set to true. You should never need to change
this.

Default: browse list = yes

browseable (S)
This controls whether this share is seen in the
list of available shares in a net view and in the
browse list.

Default: browseable = yes

case sensitive (S)
See the discussion in the section NAME MANGLING.

Default: case sensitive = no

casesignames (S)
Synonym for case sensitive.

change notify timeout (G)
This SMB allows a client to tell a server to
"watch" a particular directory for any changes and
only reply to the SMB request when a change has
occurred. Such constant scanning of a directory is
expensive under UNIX, hence an smbd(8)daemon only
performs such a scan on each requested directory
once every change notify timeout seconds.

Default: change notify timeout = 60

Example: change notify timeout = 300

Would change the scan time to every 5 minutes.

change share command (G)
Samba 2.2.0 introduced the ability to dynamically
add and delete shares via the Windows NT 4.0 Server
Manager. The change share command is used to define
an external program or script which will modify an
existing service definition in smb.conf. In order
to successfully execute the change share command,
smbd requires that the administrator be connected
using a root account (i.e. uid == 0).

When executed, smbd will automatically invoke the
change share command with four parameters.

· configFile - the location of the global smb.conf
file.

· shareName - the name of the new share.

· pathName - path to an **existing** directory on
disk.

· comment - comment string to associate with the
new share.

This parameter is only used modify existing file shares
definitions. To modify printer shares, use the "Print
ers..." folder as seen when browsing the Samba host.

See also add share command, delete share command.

Default: none

Example: change share command = /usr/local/bin/addshare

character set (G)
This allows smbdto map incoming filenames from a
DOS Code page (see the client code page parameter)
to several built in UNIX character sets. The built
in code page translations are:

· ISO8859-1 : Western European UNIX character set.
The parameter client code page MUST be set to
code page 850 if the character set parameter is
set to ISO8859-1 in order for the conversion to
the UNIX character set to be done correctly.

· ISO8859-2 : Eastern European UNIX character set.
The parameter client code page MUST be set to
code page 852 if the character set parameter is
set to ISO8859-2 in order for the conversion to
the UNIX character set to be done correctly.

· ISO8859-5 : Russian Cyrillic UNIX character set.
The parameter client code page MUST be set to
code page 866 if the character set parameter is
set to ISO8859-5 in order for the conversion to
the UNIX character set to be done correctly.

· ISO8859-7 : Greek UNIX character set. The parame
ter client code page MUST be set to code page 737
if the character set parameter is set to
ISO8859-7 in order for the conversion to the UNIX
character set to be done correctly.

· KOI8-R : Alternate mapping for Russian Cyrillic
UNIX character set. The parameter client code
page MUST be set to code page 866 if the charac
ter set parameter is set to KOI8-R in order for
the conversion to the UNIX character set to be
done correctly.

BUG. These MSDOS code page to UNIX character set mappings
should be dynamic, like the loading of MS DOS code pages,
not static.

Normally this parameter is not set, meaning no filename
translation is done.

Default: character set = <empty string>

Example: character set = ISO8859-1

client code page (G)
This parameter specifies the DOS code page that the
clients accessing Samba are using. To determine
what code page a Windows or DOS client is using,
open a DOS command prompt and type the command
chcp. This will output the code page. The default
for USA MS-DOS, Windows 95, and Windows NT releases
is code page 437. The default for western European
releases of the above operating systems is code
page 850.

This parameter tells smbd(8) which of the code
page.XXX files to dynamically load on startup.
These files, described more fully in the manual
page make_smbcodepage(1), tell smbd how to map
lower to upper case characters to provide the case
insensitivity of filenames that Windows clients
expect.

Samba currently ships with the following code page
files :

· Code Page 437 - MS-DOS Latin US

· Code Page 737 - Windows '95 Greek

· Code Page 850 - MS-DOS Latin 1

· Code Page 852 - MS-DOS Latin 2

· Code Page 861 - MS-DOS Icelandic

· Code Page 866 - MS-DOS Cyrillic

· Code Page 932 - MS-DOS Japanese SJIS

· Code Page 936 - MS-DOS Simplified Chinese

· Code Page 949 - MS-DOS Korean Hangul

· Code Page 950 - MS-DOS Traditional Chinese

Thus this parameter may have any of the values 437, 737,
850, 852, 861, 932, 936, 949, or 950. If you don't find
the codepage you need, read the comments in one of the
other codepage files and the make_smbcodepage(1) man page
and write one. Please remember to donate it back to the
Samba user community.

This parameter co-operates with the valid chars parameter
in determining what characters are valid in filenames and
how capitalization is done. If you set both this parameter
and the valid chars parameter the client code page parame
ter MUST be set before the valid chars parameter in the
smb.conf file. The valid chars string will then augment
the character settings in the client code page parameter.

If not set, client code page defaults to 850.

See also : valid chars, code page directory

Default: client code page = 850

Example: client code page = 936

code page directory (G)
Define the location of the various client code page
files.

See also the printing parameter.

Default: Currently no default value is given to
this string, unless the value of the printing
parameter is SYSV, in which case the default is :

lp -i %p-%j -H hold

or if the value of the printing parameter is SOFTQ,
then the default is:

qstat -s -j%j -h

Example for HPUX: lppause command = /usr/bin/lpalt
%p-%j -p0

lpq cache time (G)
This controls how long lpq info will be cached for
to prevent the lpq command being called too often.
A separate cache is kept for each variation of the
lpq command used by the system, so if you use dif
ferent lpq commands for different users then they
won't share cache information.

The cache files are stored in /tmp/lpq.xxxx where
xxxx is a hash of the lpq command in use.

The default is 10 seconds, meaning that the cached
results of a previous identical lpq command will be
used if the cached data is less than 10 seconds
old. A large value may be advisable if your lpq
command is very slow.

A value of 0 will disable caching completely.

See also the printing parameter.

Default: lpq cache time = 10

Example: lpq cache time = 30

lpq command (S)
This parameter specifies the command to be executed
on the server host in order to obtain lpq -style
printer status information.

This command should be a program or script which
takes a printer name as its only parameter and out
puts printer status information.

Currently eight styles of printer status informa
tion are supported; BSD, AIX, LPRNG, PLP, SYSV,
HPUX, QNX and SOFTQ. This covers most UNIX sys
tems. You control which type is expected using the
printing = option.

Some clients (notably Windows for Workgroups) may
not correctly send the connection number for the
printer they are requesting status information
about. To get around this, the server reports on
the first printer service connected to by the
client. This only happens if the connection number
sent is invalid.

If a %p is given then the printer name is put in
its place. Otherwise it is placed at the end of the
command.

Note that it is good practice to include the abso
lute path in the lpq command as the $PATH may not
be available to the server.

See also the printing parameter.

Default: depends on the setting of printing

Example: lpq command = /usr/bin/lpq -P%p

lpresume command (S)
This parameter specifies the command to be executed
on the server host in order to restart or continue
printing or spooling a specific print job.

This command should be a program or script which
takes a printer name and job number to resume the
print job. See also the lppause command parameter.

If a %p is given then the printer name is put in
its place. A %j is replaced with the job number (an
integer).

Note that it is good practice to include the abso
lute path in the lpresume command as the PATH may
not be available to the server.

See also the printing parameter.

Default: Currently no default value is given to
this string, unless the value of the printing
parameter is SYSV, in which case the default is :

lp -i %p-%j -H resume

or if the value of the printing parameter is SOFTQ,
then the default is:

qstat -s -j%j -r

Example for HPUX: lpresume command = /usr/bin/lpalt
%p-%j -p2

lprm command (S)
This parameter specifies the command to be executed
on the server host in order to delete a print job.

This command should be a program or script which
takes a printer name and job number, and deletes
the print job.

If a %p is given then the printer name is put in
its place. A %j is replaced with the job number (an
integer).

Note that it is good practice to include the abso
lute path in the lprm command as the PATH may not
be available to the server.

See also the printing parameter.

Default: depends on the setting of printing

Example 1: lprm command = /usr/bin/lprm -P%p %j

Example 2: lprm command = /usr/bin/cancel %p-%j

machine password timeout (G)
If a Samba server is a member of a Windows NT
Domain (see the security=domain) parameter) then
periodically a running smbd(8)process will try and
change the MACHINE ACCOUNT PASSWORD stored in the
TDB called private/secrets.tdb . This parameter
specifies how often this password will be changed,
in seconds. The default is one week (expressed in
seconds), the same as a Windows NT Domain member
server.

See also smbpasswd(8) , and the security=domain)
parameter.

Default: machine password timeout = 604800

magic output (S)
This parameter specifies the name of a file which
will contain output created by a magic script (see
the magic script parameter below).

Warning: If two clients use the same magic script
in the same directory the output file content is
undefined.

Default: magic output = <magic script name>.out

Example: magic output = myfile.txt

magic script (S)
This parameter specifies the name of a file which,
if opened, will be executed by the server when the
file is closed. This allows a UNIX script to be
sent to the Samba host and executed on behalf of
the connected user.

Scripts executed in this way will be deleted upon
completion assuming that the user has the appropri
ate level of privilege and the file permissions
allow the deletion.

If the script generates output, output will be sent
to the file specified by the magic output parame
ter (see above).

Note that some shells are unable to interpret
scripts containing CR/LF instead of CR as the end-
of-line marker. Magic scripts must be executable as
is on the host, which for some hosts and some
shells will require filtering at the DOS end.

Magic scripts are EXPERIMENTAL and should NOT be
relied upon.

Default: None. Magic scripts disabled.

Example: magic script = user.csh

mangle case (S)
See the section on NAME MANGLING

Default: mangle case = no

mangled map (S)
This is for those who want to directly map UNIX
file names which cannot be represented on Win
dows/DOS. The mangling of names is not always what
is needed. In particular you may have documents
with file extensions that differ between DOS and
UNIX. For example, under UNIX it is common to use
.html for HTML files, whereas under Windows/DOS
.htm is more commonly used.

So to map html to htm you would use:

mangled map = (*.html *.htm)

One very useful case is to remove the annoying ;1
off the ends of filenames on some CDROMs (only vis
ible under some UNIXes). To do this use a map of
(*;1 *;).

Default: no mangled map

Example: mangled map = (*;1 *;)

mangled names (S)
This controls whether non-DOS names under UNIX
should be mapped to DOS-compatible names ("man
gled") and made visible, or whether non-DOS names
should simply be ignored.

See the section on NAME MANGLING for details on
how to control the mangling process.

If mangling is used then the mangling algorithm is
as follows:

· The first (up to) five alphanumeric characters
before the rightmost dot of the filename are pre
served, forced to upper case, and appear as the
first (up to) five characters of the mangled
name.

· A tilde "~" is appended to the first part of the
mangled name, followed by a two-character unique
sequence, based on the original root name (i.e.,
the original filename minus its final extension).
The final extension is included in the hash cal
culation only if it contains any upper case char
acters or is longer than three characters.

Note that the character to use may be specified
using the mangling char option, if you don't like
'~'.

· The first three alphanumeric characters of the
final extension are preserved, forced to upper
case and appear as the extension of the mangled
name. The final extension is defined as that part
of the original filename after the rightmost dot.
If there are no dots in the filename, the mangled
name will have no extension (except in the case
of "hidden files" - see below).

· Files whose UNIX name begins with a dot will be
presented as DOS hidden files. The mangled name
will be created as for other filenames, but with
the leading dot removed and "___" as its exten
sion regardless of actual original extension
(that's three underscores).

The two-digit hash value consists of upper case
alphanumeric characters.

This algorithm can cause name collisions only if files in
a directory share the same first five alphanumeric charac
ters. The probability of such a clash is 1/1300.

The name mangling (if enabled) allows a file to be copied
between UNIX directories from Windows/DOS while retaining
the long UNIX filename. UNIX files can be renamed to a new
extension from Windows/DOS and will retain the same base
name. Mangled names do not change between sessions.

Default: mangled names = yes

mangled stack (G)
This parameter controls the number of mangled names
that should be cached in the Samba server smbd(8).

This stack is a list of recently mangled base names
(extensions are only maintained if they are longer
than 3 characters or contains upper case charac
ters).

The larger this value, the more likely it is that
mangled names can be successfully converted to cor
rect long UNIX names. However, large stack sizes
will slow most directory accesses. Smaller stacks
save memory in the server (each stack element costs
256 bytes).

It is not possible to absolutely guarantee correct
long filenames, so be prepared for some surprises!

Default: mangled stack = 50

Example: mangled stack = 100

mangling char (S)
This controls what character is used as the magic
character in name mangling. The default is a '~'
but this may interfere with some software. Use this
option to set it to whatever you prefer.

Default: mangling char = ~

Example: mangling char = ^

map archive (S)
This controls whether the DOS archive attribute
should be mapped to the UNIX owner execute bit. The
DOS archive bit is set when a file has been modi
fied since its last backup. One motivation for this
option it to keep Samba/your PC from making any
file it touches from becoming executable under
UNIX. This can be quite annoying for shared source
code, documents, etc...

Note that this requires the create mask parameter
to be set such that owner execute bit is not masked
out (i.e. it must include 100). See the parameter
create mask for details.

Default: map archive = yes

map hidden (S)
This controls whether DOS style hidden files should
be mapped to the UNIX world execute bit.

Note that this requires the create mask to be set
such that the world execute bit is not masked out
(i.e. it must include 001). See the parameter
create mask for details.

Default: map hidden = no

map system (S)
This controls whether DOS style system files should
be mapped to the UNIX group execute bit.

Note that this requires the create mask to be set
such that the group execute bit is not masked out
(i.e. it must include 010). See the parameter
create mask for details.

Default: map system = no

map to guest (G)
This parameter is only useful in security modes
other than security=share - i.e. user, server, and
domain.

This parameter can take three different values,
which tell smbd(8)what to do with user login
requests that don't match a valid UNIX user in some
way.

The three settings are :

· Never - Means user login requests with an invalid
password are rejected. This is the default.

· Bad User - Means user logins with an invalid
password are rejected, unless the username does
not exist, in which case it is treated as a guest
login and mapped into the guest account.

· Bad Password - Means user logins with an invalid
password are treated as a guest login and mapped
into the guest account. Note that this can cause
problems as it means that any user incorrectly
typing their password will be silently logged on
as "guest" - and will not know the reason they
cannot access files they think they should -
there will have been no message given to them
that they got their password wrong. Helpdesk ser
vices will hate you if you set the map to guest
parameter this way :-).

Note that this parameter is needed to set up "Guest" share
services when using security modes other than share. This
is because in these modes the name of the resource being
requested is not sent to the server until after the server
has successfully authenticated the client so the server
cannot make authentication decisions at the correct time
(connection to the share) for "Guest" shares.

For people familiar with the older Samba releases, this
parameter maps to the old compile-time setting of the
GUEST_SESSSETUP value in local.h.

Default: map to guest = Never

Example: map to guest = Bad User

max connections (S)
This option allows the number of simultaneous con
nections to a service to be limited. If max connec
tions is greater than 0 then connections will be
refused if this number of connections to the ser
vice are already open. A value of zero mean an
unlimited number of connections may be made.

Record lock files are used to implement this fea
ture. The lock files will be stored in the direc
tory specified by the lock directory option.

Default: max connections = 0

Example: max connections = 10

max disk size (G)
This option allows you to put an upper limit on the
apparent size of disks. If you set this option to
100 then all shares will appear to be not larger
than 100 MB in size.

Note that this option does not limit the amount of
data you can put on the disk. In the above case you
could still store much more than 100 MB on the
disk, but if a client ever asks for the amount of
free disk space or the total disk size then the
result will be bounded by the amount specified in
max disk size.

This option is primarily useful to work around bugs
in some pieces of software that can't handle very
large disks, particularly disks over 1GB in size.

A max disk size of 0 means no limit.

Default: max disk size = 0

Example: max disk size = 1000

max log size (G)
This option (an integer in kilobytes) specifies the
max size the log file should grow to. Samba period
ically checks the size and if it is exceeded it
will rename the file, adding a .old extension.

A size of 0 means no limit.

Default: max log size = 5000

Example: max log size = 1000

max mux (G)
This option controls the maximum number of out
standing simultaneous SMB operations that Samba
tells the client it will allow. You should never
need to set this parameter.

Default: max mux = 50

max open files (G)
This parameter limits the maximum number of open
files that one smbd(8)file serving process may have
open for a client at any one time. The default for
this parameter is set very high (10,000) as Samba
uses only one bit per unopened file.

The limit of the number of open files is usually
set by the UNIX per-process file descriptor limit
rather than this parameter so you should never need
to touch this parameter.

Default: max open files = 10000

max print jobs (S)
This parameter limits the maximum number of jobs
allowable in a Samba printer queue at any given
moment. If this number is exceeded, smbd(8)will
remote "Out of Space" to the client. See all total
print jobs.

Default: max print jobs = 1000

Example: max print jobs = 5000

max protocol (G)
The value of the parameter (a string) is the high
est protocol level that will be supported by the
server.

Possible values are :

· CORE: Earliest version. No concept of user names.

· COREPLUS: Slight improvements on CORE for effi
ciency.

· LANMAN1: First modern version of the protocol.
Long filename support.

· LANMAN2: Updates to Lanman1 protocol.

· NT1: Current up to date version of the protocol.
Used by Windows NT. Known as CIFS.

Normally this option should not be set as the automatic
negotiation phase in the SMB protocol takes care of choos
ing the appropriate protocol.

See also the printing parameter.

Default: min print space = 0

Example: min print space = 2000

min protocol (G)
The value of the parameter (a string) is the lowest
SMB protocol dialect than Samba will support.
Please refer to the max protocol parameter for a
list of valid protocol names and a brief descrip
tion of each. You may also wish to refer to the C
source code in source/smbd/negprot.c for a listing
of known protocol dialects supported by clients.

If you are viewing this parameter as a security
measure, you should also refer to the lanman auth
parameter. Otherwise, you should never need to
change this parameter.

Default : min protocol = CORE

Example : min protocol = NT1 # disable DOS clients

min wins ttl (G)
This option tells nmbd(8) when acting as a WINS
server ( wins support = yes) what the minimum 'time
to live' of NetBIOS names that nmbd will grant will
be (in seconds). You should never need to change
this parameter. The default is 6 hours (21600 sec
onds).

Default: min wins ttl = 21600

msdfs root (S)
This boolean parameter is only available if Samba
is configured and compiled with the --with-msdfs
option. If set to yes>, Samba treats the share as a
Dfs root and allows clients to browse the dis
tributed file system tree rooted at the share
directory. Dfs links are specified in the share
directory by symbolic links of the form
msdfs:serverA\shareA,serverB\shareB and so on. For
more information on setting up a Dfs tree on Samba,
refer to msdfs_setup.html