diff options
Diffstat (limited to 'docs/manpages/smb.conf.5')
| -rw-r--r-- | docs/manpages/smb.conf.5 | 2892 |
1 files changed, 2892 insertions, 0 deletions
diff --git a/docs/manpages/smb.conf.5 b/docs/manpages/smb.conf.5 new file mode 100644 index 00000000000..f048c94b802 --- /dev/null +++ b/docs/manpages/smb.conf.5 @@ -0,0 +1,2892 @@ +.TH SMB.CONF 5 11/10/94 smb.conf smb.conf +.SH NAME +smb.conf \- configuration file for smbd +.SH SYNOPSIS +.B smb.conf +.SH DESCRIPTION +The +.B smb.conf +file is a configuration file for the Samba suite. + +.B smb.conf +contains runtime configuration information for the +.B smbd +program. The +.B smbd +program provides LanManager-like services to clients +using the SMB protocol. +.SH 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 discarded. Leading, trailing and internal +whitespace in section and parameter names is irrelevant. Leading and +trailing whitespace in a parameter value is discarded. Internal whitespace +within a parameter value is retained verbatim. + +Any line beginning with a semicolon is ignored, as are lines containing +only whitespace. + +Any line ending in a \e 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 significant in boolean values, but is preserved +in string values. Some items such as create modes are numeric. +.SH SERVICE DESCRIPTIONS +Each section in the configuration file describes a service. The section name +is the service name and the parameters within the section define the service's +attributes. + +There are three special sections, [global], [homes] and [printers], which are +described under 'special sections'. The following notes apply to ordinary +service descriptions. + +A service 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. + +Services are either filespace 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). + +Services may be guest services, in which case no password is required to +access them. A specified guest account is used to define access privileges +in this case. + +Services other than guest services will require a password to access +them. The client provides the username. As many 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 service +definition. + +Note that the access rights granted by the server are masked by the access +rights granted to the specified or guest 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 service. The user has write +access to the path /home/bar. The service is accessed via the service name +"foo": + + [foo] + path = /home/bar + writable = true + +The following sample section defines a printable service. The service 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 + read only = true + printable = true + public = true +.SH SPECIAL SECTIONS + +.SS The [global] section +.RS 3 +Parameters in this section apply to the server as a whole, or are defaults +for services which do not specifically define certain items. See the notes +under 'Parameters' for more information. +.RE + +.SS The [homes] section +.RS 3 +If a section called 'homes' is included in the configuration file, services +connecting clients to their home directories can be created on the fly by the +server. + +When the connection request is made, the existing services are scanned. If a +match is found, it is used. If no match is found, the requested service name is +treated as a user name and looked up in the local passwords file. If the +name exists and the correct password has been given, a service is created +by cloning the [homes] section. + +Some modifications are then made to the newly created section: + +.RS 3 +The service name is changed from 'homes' to the located username + +If no path was given, the path is set to the user's home directory. +.RE + +If you decide to use a path= line in your [homes] section then you may +find it useful to use the %S macro. For example 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 service name is "homes", except that +the service 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 normal service section +can specify, though some make more sense than others. The following is a +typical and suitable [homes] section: + + [homes] + writable = yes + +An important point: + +.RS 3 +If guest access is specified in the [homes] section, all home directories will +be accessible to all clients +.B without a password. +In the very unlikely event +that this is actually desirable, it would be wise to also specify read only +access. +.RE +.RE + +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 setting browseable=no in the [homes] +section will hide the [homes] service but make any auto home +directories visible. + +.SS The [printers] section +.RS 3 +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 services 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 service name is +treated as a printer name and the appropriate printcap file is scanned to +see if the requested service name is a valid printer name. If a match is +found, a new service is created by cloning the [printers] section. + +A few modifications are then made to the newly created section: + +.RS 3 +The service 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 service does not permit guest access and no username was given, the +username is set to the located printer name. +.RE + +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-writable spool directory +with the sticky bit set on it. A typical [printers] entry would look like this: + + [printers] + path = /usr/spool/public + writable = no + public = yes + printable = yes + +All aliases given for a printer in the printcap file are legitimate printer +names as far as the server is concerned. 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 recognise 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 separated by vertical bar symbols ("|"). +.RE +.SH PARAMETERS +Parameters define the specific attributes of services. + +Some parameters are specific to the [global] section (eg., security). +Some parameters are usable in all sections (eg., 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 behaviour 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. + +.SS 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 hostname that Samba is running on + +%m = the netbios name of the client machine (very useful) + +%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 + +%d = The process id of the current server process + +%a = the architecture of the remote machine. Only some are recognised, +and those may not be 100% reliable. It currently recognises Samba, +WfWg, WinNT and Win95. Anything else will be known as "UNKNOWN". If it +gets it wrong then sending me a level 3 log should allow me to fix it. + +%I = The IP address of the client machine + +%T = the current date and time + +There are some quite creative things that can be done with these +substitutions and other smb.conf options. + +.SS NAME MANGLING + +Samba supports "name mangling" so that DOS and Windows clients can use +files that don't conform to the 8.3 format. 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 service (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 mangled. 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 +filenames. 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 no. + +"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 lowered. Default no. + +.SS 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 synonyms. + +auto services + +config file + +deadtime + +debuglevel + +default + +default service + +dfree command + +encrypt passwords + +getwd cache + +hosts equiv + +include + +keepalive + +lock dir + +load printers + +lock directory + +log file + +log level + +lpq cache time + +mangled stack + +max log size + +max packet + +max xmit + +message command + +null passwords + +os level + +packet size + +passwd chat + +passwd program + +password level + +password server + +preferred master + +preload + +printing + +printcap name + +protocol + +read bmpx + +read prediction + +read raw + +read size + +remote announce + +root + +root dir + +root directory + +security + +server string + +smbrun + +socket address + +socket options + +status + +strip dot + +time offset + +username map + +use rhosts + +valid chars + +workgroup + +write raw + +.SS COMPLETE LIST OF SERVICE PARAMETERS + +Here is a list of all service parameters. See the section of each +parameter for details. Note that some are synonyms. + +admin users + +allow hosts + +alternate permissions + +available + +browseable + +case sensitive + +case sig names + +copy + +create mask + +create mode + +comment + +default case + +delete readonly + +deny hosts + +directory + +dont descend + +exec + +force group + +force user + +guest account + +guest ok + +guest only + +hide dot files + +hosts allow + +hosts deny + +invalid users + +locking + +lppause command + +lpq command + +lpresume command + +lprm command + +magic output + +magic script + +mangle case + +mangled names + +mangling char + +map archive + +map hidden + +map system + +max connections + +min print space + +only guest + +only user + +path + +postexec + +postscript + +preserve case + +print command + +printer driver + +print ok + +printable + +printer + +printer name + +public + +read only + +read list + +revalidate + +root postexec + +root preexec + +set directory + +share modes + +short preserve case + +strict locking + +sync always + +user + +username + +users + +valid users + +volume + +wide links + +writable + +write ok + +writeable + +write list + +.SS EXPLANATION OF EACH PARAMETER +.RS 3 + +.SS admin users (G) + +This is a list of users who will be granted administrative privilages +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 permissions. + +.B Default: + no admin users + +.B Example: + admin users = jason + +.SS auto services (G) +This is a list of services that you want to be automatically added to +the browse lists. This is most useful for homes and printers services +that would otherwise not be visible. + +Note that if you just want all printers in your printcap file loaded +then the "load printers" option is easier. + +.B Default: + no auto services + +.B Example: + auto services = fred lp colorlp + +.SS allow hosts (S) +A synonym for this parameter is 'hosts allow'. + +This parameter is a comma delimited set of hosts which are permitted to access +a services. If specified in the [global] section, matching hosts will be +allowed access to any service that does not specifically exclude them from +access. Specific services my have their own list, which override those +specified in the [global] section. + +You can specify the hosts by name or IP number. For example, you could +restrict access to only the hosts on a Class C subnet with something like +"allow hosts = 150.203.5.". The full syntax of the list is described in +the man page +.BR hosts_access (5). + +You can also specify hosts by network/netmask pairs and by netgroup +names if your system supports netgroups. The EXCEPT keyword can also +be used to limit a wildcard list. The following examples may provide +some help: + +Example 1: allow all IPs in 150.203.*.* except one + + hosts allow = 150.203. EXCEPT 150.203.6.66 + +Example 2: allow hosts that match the given network/netmask + + hosts allow = 150.203.15.0/255.255.255.0 + +Example 3: allow a couple of hosts + + hosts allow = lapland, arvidsjaur + +Example 4: allow only hosts in netgroup "foonet" or localhost, but +deny access from one particular host + + hosts allow = @foonet, localhost + hosts deny = pirate + +Note that access still requires suitable user-level passwords. + +See +.BR testparm (1) +for a way of testing your host access to see if it +does what you expect. + +.B Default: + none (i.e., all hosts permitted access) + +.B Example: + allow hosts = 150.203.5. myhost.mynet.edu.au + +.SS alternate permissions (S) + +This option affects the way the "read only" DOS attribute is produced +for UNIX files. If this is false then the read only bit is set for +files on writeable shares which the user cannot write to. + +If this is true then it is set for files whos user write bit is not set. + +The latter behaviour is useful for when users copy files from each +others directories, and use a file manager that preserves +permissions. Without this option they may get annoyed as all copied +files will have the "read only" bit set. + +.B Default: + alternate permissions = no + +.B Example: + alternate permissions = yes + +.SS 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. + +.B Default: + available = yes + +.B Example: + available = no +.SS browseable (S) +This controls whether this share is seen in the list of available +shares in a net view and in the browse list. + +.B Default: + browseable = Yes + +.B Example: + browseable = No + +.SS case sig names (G) +See "case sensitive" + +.SS comment (S) +This is a text field that is seen when a client does a net view to +list what shares are available. It will also be used when browsing is +fully supported. + +.B Default: + No comment string + +.B Example: + comment = Fred's Files + +.SS config file (G) + +This allows you to override the config file to use, instead of the +default (usually smb.conf). There is a chicken and egg problem here as +this option is set in the config file! + +For this reason, if the name of the config file has changed when the +parameters are loaded then it will reload them from the new config +file. + +This option takes the usual substitutions, which can be very useful. + +If the config file doesn't exist then it won't be loaded (allowing +you to special case the config files of just a few clients). + +.B Example: + config file = /usr/local/samba/lib/smb.conf.%m + +.SS copy (S) +This parameter allows you to 'clone' service entries. The specified +service is simply duplicated under the current service's name. Any +parameters specified in the current section will override those in the +section being copied. + +This feature lets you set up a 'template' service and create similar +services easily. Note that the service being copied must occur earlier +in the configuration file than the service doing the copying. + +.B Default: + none + +.B Example: + copy = otherservice +.SS create mask (S) +A synonym for this parameter is 'create mode'. + +This parameter is the octal modes which are used when converting DOS modes +to UNIX modes. + +Note that Samba will or this value with 0700 as you must have at least +user read, write and execute for Samba to work properly. + +.B Default: + create mask = 0755 + +.B Example: + create mask = 0775 +.SS create mode (S) +See +.B create mask. +.SS dead time (G) +The value of the parameter (a decimal integer) represents the number of +minutes of inactivity before a connection is considered dead, and it +is disconnected. The deadtime only takes effect if the number of open files +is zero. + +This is useful to stop a server's resources being exhausted by a large +number of inactive connections. + +Most clients have an auto-reconnect feature when a connection is broken so +in most cases this parameter should be transparent to users. + +Using this parameter with a timeout of a few minutes is recommended +for most systems. + +A deadtime of zero indicates that no auto-disconnection should be performed. + +.B Default: + dead time = 0 + +.B Example: + dead time = 15 +.SS debug level (G) +The value of the parameter (an integer) allows the debug level +(logging level) to be specified in the +.B smb.conf +file. This is to give +greater flexibility in the configuration of the system. + +The default will be the debug level specified on the command line. + +.B Example: + debug level = 3 +.SS default (G) +See +.B default service. +.SS default case (S) + +See the section on "NAME MANGLING" Also note the addition of "short +preserve case" + +.SS default service (G) +A synonym for this parameter is 'default'. + +This parameter specifies the name of a service which will be connected to +if the service actually requested cannot be found. Note that the square +brackets are NOT given in the parameter value (see example below). + +There is no default value for this parameter. If this parameter is not given, +attempting to connect to a nonexistent service results in an error. + +Typically the default service would be a public, read-only service. + +Also note that as of 1.9.14 the apparent service name will be changed to +equal that of the requested service, this is very useful as it allows +you to use macros like %S to make a wildcard service. + +Note also that any _ characters in the name of the service used in the +default service will get mapped to a /. This allows for interesting +things. + + +.B Example: + default service = pub + + [pub] + path = /%S + + +.SS delete readonly (S) +This parameter allows readonly files to be deleted. This is not normal DOS +semantics, but is allowed by UNIX. + +This option may be useful for running applications such as rcs, where UNIX +file ownership prevents changing file permissions, and DOS semantics prevent +deletion of a read only file. + +.B Default: + delete readonly = No + +.B Example: + delete readonly = Yes +.SS deny hosts (S) +A synonym for this parameter is 'hosts deny'. + +The opposite of 'allow hosts' - hosts listed here are NOT permitted +access to services unless the specific services have their own lists to +override this one. Where the lists conflict, the 'allow' list takes precedence. + +.B Default: + none (i.e., no hosts specifically excluded) + +.B Example: + deny hosts = 150.203.4. badhost.mynet.edu.au +.SS dfree command (G) +The dfree command setting should only be used on systems where a +problem occurs with the internal disk space calculations. This has +been known to happen with Ultrix, but may occur with other operating +systems. The symptom that was seen was an error of "Abort Retry +Ignore" at the end of each directory listing. + +This setting allows the replacement of the internal routines to +calculate the total disk space and amount available with an external +routine. The example below gives a possible script that might fulfill +this function. + +The external program will be passed a single parameter indicating a +directory in the filesystem being queried. This will typically consist +of the string "./". The script should return two integers in ascii. The +first should be the total disk space in blocks, and the second should +be the number of available blocks. An optional third return value +can give the block size in bytes. The default blocksize is 1024 bytes. + +Note: Your script should NOT be setuid or setgid and should be owned by +(and writable only by) root! + +.B Default: + By default internal routines for determining the disk capacity +and remaining space will be used. + +.B Example: + dfree command = /usr/local/samba/bin/dfree + + Where the script dfree (which must be made executable) could be + +.nf + #!/bin/sh + df $1 | tail -1 | awk '{print $2" "$4}' +.fi + + or perhaps (on Sys V) + +.nf + #!/bin/sh + /usr/bin/df -k $1 | tail -1 | awk '{print $3" "$5}' +.fi + + Note that you may have to replace the command names with full +path names on some systems. +.SS directory (S) +See +.B path. +.SS dont descend (S) +There are certain directories on some systems (eg., the /proc tree under +Linux) that are either not of interest to clients or are infinitely deep +(recursive). This parameter allows you to specify a comma-delimited list +of directories that the server should always show as empty. + +Note that Samba can be very fussy about the exact format of the "dont +descend" entries. For example you may need "./proc" instead of just +"/proc". Experimentation is the best policy :-) + +.B Default: + none (i.e., all directories are OK to descend) + +.B Example: + dont descend = /proc,/dev + +.SS encrypt passwords (G) + +This boolean controls whether encrypted passwords will be negotiated +with the client. Note that this option has no effect if you haven't +compiled in the necessary des libraries and encryption code. It +defaults to no. + +.SS exec (S) + +This is an alias for preexec + + +.SS force group (S) +This specifies a group name that all connections to this service +should be made as. This may be useful for sharing files. + +.B Default: + no forced group + +.B Example: + force group = agroup + +.SS force user (S) +This specifies a user name that all connections to this service +should be made as. This may be useful for sharing files. You should +also use it carefully as using it incorrectly can cause security +problems. + +This user name only gets used once a connection is established. Thus +clients still need to connect as a valid user and supply a valid +password. Once connected, all file operations will be performed as the +"forced user", not matter what username the client connected as. + +.B Default: + no forced user + +.B Example: + force user = auser + +.SS guest account (S) +This is a username which will be used for access to services which are +specified as 'guest ok' (see below). Whatever privileges this user has +will be available to any client connecting to the guest +service. Typically this user will exist in the password file, but will +not have a valid login. If a username is specified in a given service, +the specified username overrides this one. + +One some systems the account "nobody" may not be able to print. Use +another account in this case. You should test this by trying to log in +as your guest user (perhaps by using the "su \-" command) and trying to +print using +.BR lpr . + +Note that as of version 1.9 of Samba this option may be set +differently for each service. + +.B Default: + specified at compile time + +.B Example: + guest account = nobody +.SS getwd cache (G) +This is a tuning option. When this is enabled a cacheing algorithm will +be used to reduce the time taken for getwd() calls. This can have a +significant impact on performance, especially when widelinks is False. + +.B Default: + getwd cache = No + +.B Example: + getwd cache = Yes +.SS guest ok (S) +See +.B public. +.SS guest only (S) +If this parameter is 'yes' for a service, then only guest connections to the +service are permitted. This parameter will have no affect if "guest ok" or +"public" is not set for the service. + +See the section below on user/password validation for more information about +this option. + +.B Default: + guest only = no + +.B Example: + guest only = yes +.SS hide dot files (S) +This is a boolean parameter that controls whether files starting with +a dot appear as hidden files. + +.B Default: + hide dot files = yes + +.B Example: + hide dot files = no +.SS hosts allow (S) +See +.B allow hosts. +.SS hosts deny (S) +See +.B deny hosts. + +.SS group (S) +This is an alias for "force group" and is only kept for compatibility +with old versions of Samba. It may be removed in future versions. + +.SS hosts equiv (G) +If this global parameter is a non-null string, it specifies the name of +a file to read for the names of hosts and users who will be allowed access +without specifying a password. + +This is not be confused with +.B allow hosts +which is about hosts access to services and is more useful for guest services. +.B hosts equiv +may be useful for NT clients which will not supply passwords to samba. + +NOTE: The use of hosts.equiv can be a major security hole. This is +because you are trusting the PC to supply the correct username. It is +very easy to get a PC to supply a false username. I recommend that the +hosts.equiv option be only used if you really know what you are doing, +or perhaps on a home network where you trust your wife and kids :-) + +.B Default + No host equivalences + +.B Example + hosts equiv = /etc/hosts.equiv + +.SS interfaces (G) + +This option allows you to setup multiple network interfaces, so that +Samba can properly handle browsing on all interfaces. + +The option takes a list of ip/netmask pairs. The netmask may either be +a bitmask, or a bitlength. + +For example, the following line: + +interfaces = 192.168.2.10/24 192.168.3.10/24 + +would configure two network interfaces with IP addresses 192.168.2.10 +and 192.168.3.10. The netmasks of both interfaces would be set to +255.255.255.0. + +You could produce an equivalent result by using: + +interfaces = 192.168.2.10/255.255.255.0 192.168.3.10/255.255.255.0 + +if you prefer that format. + +If this option is not set then Samba will attempt to find a primary +interface, but won't attempt to configure more than one interface. + +.SS invalid users (S) +This is a list of users that should not be allowed to login to this +service. This is really a "paranoid" check to absolutely ensure an +improper setting does not breach your security. + +A name starting with @ is interpreted as a UNIX group. + +The current servicename is substituted for %S. This is useful in the +[homes] section. + +See also "valid users" + +.B Default + No invalid users + +.B Example + invalid users = root fred admin @wheel + +.SS include (G) + +This allows you to include one config file inside another. the file is +included literally, as though typed in place. + +It takes the standard substitutions, except %u, %P and %S + +.SS keep alive (G) +The value of the parameter (an integer) represents the number of seconds +between 'keepalive' packets. If this parameter is zero, no keepalive packets +will be sent. Keepalive packets, if sent, allow the server to tell whether a +client is still present and responding. + +Keepalives should, in general, not be needed if the socket being used +has the SO_KEEPALIVE attribute set on it (see "socket +options"). Basically you should only use this option if you strike +difficulties. + +.B Default: + keep alive = 0 + +.B Example: + keep alive = 60 +.SS load printers (G) +A boolean variable that controls whether all printers in the printcap +will be loaded for browsing by default. + +.B Default: + load printers = no + +.B Example: + load printers = yes + +.SS lock directory (G) +This options specifies the directory where lock files will be placed. +The lock files are used to implement the "max connections" option. + +.B Default: + lock directory = /tmp/samba + +.B Example: + lock directory = /usr/local/samba/var/locks +.SS locking (S) +This controls whether or not locking will be performed by the server in +response to lock requests from the client. + +If "locking = no", all lock and unlock requests will appear to succeed and +all lock queries will indicate that the queried lock is clear. + +If "locking = yes", real locking will be performed by the server. + +This option may be particularly useful for read-only filesystems which +do not need locking (such as cdrom drives). + +Be careful about disabling locking either globally or in a specific +service, as lack of locking may result in data corruption. + +.B Default: + locking = yes + +.B Example: + locking = no + +.SS log file (G) + +This options allows you to override the name of the Samba log file +(also known as the debug file). + +This option takes the standard substitutions, allowing you to have +separate log files for each user or machine. + +.B Example: + log file = /usr/local/samba/var/log.%m + +.SS log level (G) +see "debug level" + +.SS lppause command (S) +This parameter specifies the command to be executed on the server host in +order to stop printing or spooling a specific print job. + +This command should be a program or script which takes a printer name and +job number to pause the print job. Currently I don't know of any print +spooler system that can do this with a simple option, except for the PPR +system from Trinity College (ppr\-dist.trincoll.edu/pub/ppr). One way +of implementing this is by using job priorities, where jobs having a too +low priority won't be sent to the printer. See also the +.B lppause +command. + +If a %p is given then the printername is put in its place. A %j is +replaced with the job number (an integer). +On HPUX (see printing=hpux), if the -p%p option is added to the lpq +command, the job will show up with the correct status, i.e. if the job +priority is lower than the set fence priority it will have the PAUSED +status, whereas if the priority is equal or higher it will have the +SPOOLED or PRINTING status. + +Note that it is good practice to include the absolute path in the lppause +command as the PATH may not be available to the server. + +.B Default: + Currently no default value is given to this string + +.B Example for HPUX: + lppause command = /usr/bin/lpalt %p-%j -p0 + +.SS 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 +different 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 cacheing completely. + +.B Default: + lpq cache time = 10 + +.B Example: + lpq cache time = 30 + +.SS 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 outputs printer status information. + +Currently six styles of printer status information are supported; BSD, +SYSV, AIX, HPUX, QNX, LPRNG and PLP. This covers most UNIX systems. 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 printername is put in its place. Otherwise +it is placed at the end of the command. + +Note that it is good practice to include the absolute path in the lpq +command as the PATH may not be available to the server. + +.B Default: + depends on the setting of "printing =" + +.B Example: + lpq command = /usr/bin/lpq %p + +.SS 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. + +If a %p is given then the printername is put in its place. A %j is +replaced with the job number (an integer). + +Note that it is good practice to include the absolute path in the lpresume +command as the PATH may not be available to the server. + +.B Default: + Currently no default value is given to this string + +.B Example for HPUX: + lpresume command = /usr/bin/lpalt %p-%j -p2 + +.SS 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. + +Currently seven styles of printer control are supported; BSD, SYSV, AIX +HPUX, QNX, LPRNG and PLP. This covers most UNIX systems. You control +which type is expected using the "printing =" option. + +If a %p is given then the printername is put in its place. A %j is +replaced with the job number (an integer). + +Note that it is good practice to include the absolute path in the lprm +command as the PATH may not be available to the server. + +.B Default: + depends on the setting of "printing =" + +.B Example 1: + lprm command = /usr/bin/lprm -P%p %j + +.B Example 2: + lprm command = /usr/bin/cancel %p-%j + +.SS magic output (S) +This parameter specifies the name of a file which will contain output +created by a magic script (see +.I magic script +below). + +Warning: If two clients use the same magic script in the same directory the +output file content is undefined. +.B Default: + magic output = <magic script name>.out + +.B Example: + magic output = myfile.txt +.SS 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, permissions +permitting. + +If the script generates output, output will be sent to the file specified by +the +.I magic output +parameter (see above). + +Note that some shells are unable to interpret scripts containing +carriage-return-linefeed instead of linefeed 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. + +.B Default: + None. Magic scripts disabled. + +.B Example: + magic script = user.csh +.SS mangled map (S) +This is for those who want to directly map UNIX file names which are +not representable on DOS. The mangling of names is not always what is +needed. In particular you may have documents with file extensiosn +that differ between DOS and UNIX. For example, under UNIX it is common +to use .html for HTML files, whereas under DOS .htm is more commonly +used. + +So to map 'html' to 'htm' you put: + + mangled map = (*.html *.htm) + +One very useful case is to remove the annoying ;1 off the ends of +filenames on some CDROMS (only visible under some UNIXes). To do this +use a map of (*;1 *) + +.B default: + no mangled map + +.B Example: + mangled map = (*;1 *) + +.SS mangle case (S) + +See the section on "NAME MANGLING" + +.SS mangled names (S) +This controls whether non-DOS names under UNIX should be mapped to +DOS-compatible names ("mangled") 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: +.RS +- the first (up to) five alphanumeric characters before the rightmost dot of +the filename are preserved, 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 origonal root name +(i.e., the original filename minus its final extension). The final +extension is included in the hash calculation only if it contains any upper +case characters 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 extension regardless of actual original +extension (that's three underscores). +.RE + +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 characters. The probability of such a clash +is 1/1300. + +The name mangling (if enabled) allows a file to be copied between UNIX +directories from DOS while retaining the long UNIX filename. UNIX files can +be renamed to a new extension from DOS and will retain the same basename. +Mangled names do not change between sessions. + +.B Default: + mangled names = yes + +.B Example: + mangled names = no +.SS 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. + +.B Default: + mangling char = ~ + +.B Example: + mangling char = ^ + +.SS 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. + +.B Default: + max disk size = 0 + +.B Example: + max disk size = 1000 +.SS max log size (G) + +This option (an integer in kilobytes) specifies the max size the log +file should grow to. Samba periodically checks the size and if it is +exceeded it will rename the file, adding a .old extension. + +A size of 0 means no limit. + +.B Default: + max log size = 5000 + +.B Example: + max log size = 1000 + +.SS max xmit (G) + +This option controls the maximum packet size that will be negotiated +by Samba. The default is 65535, which is the maximum. In some cases +you may find you get better performance with a smaller value. A value +below 2048 is likely to cause problems. + +.B Default: + max xmit = 65535 + +.B Example: + max xmit = 8192 + +.SS mangled stack (G) +This parameter controls the number of mangled names that should be cached in +the Samba server. + +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 +characters). + +The larger this value, the more likely it is that mangled names can be +successfully converted to correct long UNIX names. However, large stack +sizes will slow most directory access. Smaller stacks save memory in the +server (each stack element costs 256 bytes). + +It is not possible to absolutely guarantee correct long file names, so +be prepared for some surprises! + +.B Default: + mangled stack = 50 + +.B Example: + mangled stack = 100 + +.SS map archive (S) +This controls whether the DOS archive attribute should be mapped to UNIX +execute bits. The DOS archive bit is set when a file has been modified +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... + +.B Default: + map archive = yes + +.B Example: + map archive = no + +.SS map hidden (S) +This controls whether DOS style hidden files should be mapped to UNIX +execute bits. + +.B Default: + map hidden = no + +.B Example: + map hidden = yes +.SS map system (S) +This controls whether DOS style system files should be mapped to UNIX +execute bits. + +.B Default: + map system = no + +.B Example: + map system = yes +.SS max connections (S) +This option allows the number of simultaneous connections to a +service to be limited. If "max connections" is greater than 0 then +connections will be refused if this number of connections to the +service are already open. A value of zero mean an unlimited number of +connections may be made. + +Record lock files are used to implement this feature. The lock files +will be stored in the directory specified by the "lock directory" option. + +.B Default: + max connections = 0 + +.B Example: + max connections = 10 +.SS only user (S) +This is a boolean option that controls whether connections with +usernames not in the user= list will be allowed. By default this +option is disabled so a client can supply a username to be used by +the server. + +Note that this also means Samba won't try to deduce usernames from the +service name. This can be annoying for the [homes] section. To get +around this you could use "user = %S" which means your "user" list +will be just the service name, which for home directories is the name +of the user. + +.B Default: + only user = False + +.B Example: + only user = True + +.SS message command (G) + +This specifies what command to run when the server receives a WinPopup +style message. + +This would normally be a command that would deliver the message +somehow. How this is to be done is up to your imagination. + +What I use is: + + message command = csh -c 'xedit %s;rm %s' & + +This delivers the message using xedit, then removes it +afterwards. NOTE THAT IT IS VERY IMPORTANT THAT THIS COMMAND RETURN +IMMEDIATELY. That's why I have the & on the end. If it doesn't return +immediately then your PCs may freeze when sending messages (they +should recover after 30secs, hopefully). + +All messages are delivered as the global guest user. The command takes +the standard substitutions, although %u won't work (%U may be better +in this case). + +Apart from the standard substitutions, some additional ones apply. In +particular: + +%s = the filename containing the message + +%t = the destination that the message was sent to (probably the server +name) + +%f = who the message is from + +You could make this command send mail, or whatever else takes your +fancy. Please let me know of any really interesting ideas you have. + +Here's a way of sending the messages as mail to root: + +message command = /bin/mail -s 'message from %f on %m' root < %s; rm %s + +If you don't have a message command then the message won't be +delivered and Samba will tell the sender there was an +error. Unfortunately WfWg totally ignores the error code and carries +on regardless, saying that the message was delivered. + +If you want to silently delete it then try "message command = rm %s". + +For the really adventurous, try something like this: + +message command = csh -c 'csh < %s |& /usr/local/samba/bin/smbclient \e + -M %m; rm %s' & + +this would execute the command as a script on the server, then give +them the result in a WinPopup message. Note that this could cause a +loop if you send a message from the server using smbclient! You better +wrap the above in a script that checks for this :-) + +.B Default: + no message command + +.B Example: + message command = csh -c 'xedit %s;rm %s' & + +.SS min print space (S) + +This sets the minimum amount of free disk space that must be available +before a user will be able to spool a print job. It is specified in +kilobytes. The default is 0, which means no limit. + +.B Default: + min print space = 0 + +.B Example: + min print space = 2000 + +.SS null passwords (G) +Allow or disallow access to accounts that have null passwords. + +.B Default: + null passwords = no + +.B Example: + null passwords = yes + +.SS os level (G) +This integer value controls what level Samba advertises itself as for +browse elections. See BROWSING.txt for details. + +.SS packet size (G) +The maximum transmit packet size during a raw read. This option is no +longer implemented as of version 1.7.00, and is kept only so old +configuration files do not become invalid. + +.SS passwd chat (G) +This string controls the "chat" conversation that takes places +between smbd and the local password changing program to change the +users password. The string describes a sequence of response-receive +pairs that smbd uses to determine what to send to the passwd program +and what to expect back. If the expected output is not received then +the password is not changed. + +This chat sequence is often quite site specific, depending on what +local methods are used for password control (such as NIS+ etc). + +The string can contain the macros %o and %n which are substituted for +the old and new passwords respectively. It can aso contain the +standard macros \\n \\r \\t and \\s to give line-feed, carriage-return, +tab and space. + +The string can also contain a * which matches any sequence of +characters. + +Double quotes can be used to collect strings with spaces in them into +a single string. + +If the send string in any part of the chat sequence is a fullstop "." +then no string is sent. Similarly, is the expect string is a fullstop +then no string is expected. + +.B Example: + passwd chat = "*Enter OLD password*" %o\\n "*Enter NEW password*" %n\\n \\ + "*Reenter NEW password*" %n\\n "*Password changed*" + +.B Default: + passwd chat = *old*password* %o\\n *new*password* %n\\n *new*password* %n\\n *changed* + +.SS passwd program (G) +The name of a program that can be used to set user passwords. + +This is only necessary if you have enabled remote password changing at +compile time. Any occurances of %u will be replaced with the user +name. + +Also note that many passwd programs insist in "reasonable" passwords, +such as a minimum length, or the inclusion of mixed case chars and +digits. This can pose a problem as some clients (such as Windows for +Workgroups) uppercase the password before sending it. + +.B Default: + passwd program = /bin/passwd + +.B Example: + passwd program = /sbin/passwd %u + +.SS password level (G) +Some client/server conbinations have difficulty with mixed-case passwords. +One offending client is Windows for Workgroups, which for some reason forces +passwords to upper case when using the LANMAN1 protocol, but leaves them alone +when using COREPLUS! + +This parameter defines the maximum number of characters that may be upper case +in passwords. + +For example, say the password given was "FRED". If +.B password level +is set to 1 (one), the following combinations would be tried if "FRED" failed: +"Fred", "fred", "fRed", "frEd", "freD". If +.B password level was set to 2 (two), the following combinations would also be +tried: "FRed", "FrEd", "FreD", "fREd", "fReD", "frED". And so on. + +The higher value this parameter is set to the more likely it is that a mixed +case password will be matched against a single case password. However, you +should be aware that use of this parameter reduces security and increases the +time taken to process a new connection. + +A value of zero will cause only two attempts to be made - the password as is +and the password in all-lower case. + +If you find the connections are taking too long with this option then +you probably have a slow crypt() routine. Samba now comes with a fast +"ufc crypt" that you can select in the Makefile. You should also make +sure the PASSWORD_LENGTH option is correct for your system in local.h +and includes.h. On most systems only the first 8 chars of a password +are significant so PASSWORD_LENGTH should be 8, but on some longer +passwords are significant. The includes.h file tries to select the +right length for your system. + +.B Default: + password level = 0 + +.B Example: + password level = 4 + +.SS password server (G) + +By specifying the name of another SMB server (such as a WinNT box) +with this option, and using "security = server" you can get Samba to +do all its username/password validation via a remote server. + +This options sets the name of the password server to use. It must be a +netbios name, so if the machine's netbios name is different from its +internet name then you may have to add its netbios name to +/etc/hosts. + +The password server much be a machine capable of using the "LM1.2X002" +or the "LM NT 0.12" protocol, and it must be in user level security +mode. + +NOTE: Using a password server means your UNIX box (running Samba) is +only as secure as your password server. DO NOT CHOOSE A PASSWORD +SERVER THAT YOU DON'T COMPLETELY TRUST. + +Never point a Samba server at itself for password serving. This will +cause a loop and could lock up your Samba server! + +The name of the password server takes the standard substitutions, but +probably the only useful one is %m, which means the Samba server will +use the incoming client as the password server. If you use this then +you better trust your clients, and you better restrict them with hosts +allow! + +If you list several hosts in the "password server" option then smbd +will try each in turn till it finds one that responds. This is useful +in case your primary server goes down. + +.SS path (S) +A synonym for this parameter is 'directory'. + +This parameter specifies a directory to which the user of the service is to +be given access. In the case of printable services, this is where print data +will spool prior to being submitted to the host for printing. + +For a printable service offering guest access, the service should be readonly +and the path should be world-writable and have the sticky bit set. This is not +mandatory of course, but you probably won't get the results you expect if you +do otherwise. + +Any occurances of %u in the path will be replaced with the username +that the client is connecting as. Any occurances of %m will be +replaced by the name of the machine they are connecting from. These +replacements are very useful for setting up pseudo home directories +for users. + +Note that this path will be based on 'root dir' if one was specified. +.B Default: + none + +.B Example: + path = /home/fred+ + +.SS postexec (S) + +This option specifies a command to be run whenever the service is +disconnected. It takes the usual substitutions. The command may be run +as the root on some systems. + +An interesting example may be do unmount server resources: + +postexec = /etc/umount /cdrom + +See also preexec + +.B Default: + none (no command executed) + +.B Example: + postexec = echo \"%u disconnected from %S from %m (%I)\" >> /tmp/log + +.SS postscript (S) +This parameter forces a printer to interpret the print files as +postscript. This is done by adding a %! to the start of print output. + +This is most useful when you have lots of PCs that persist in putting +a control-D at the start of print jobs, which then confuses your +printer. + +.B Default: + postscript = False + +.B Example: + postscript = True + +.SS preexec (S) + +This option specifies a command to be run whenever the service is +connected to. It takes the usual substitutions. + +An interesting example is to send the users a welcome message every +time they log in. Maybe a message of the day? Here is an example: + +preexec = csh -c 'echo \"Welcome to %S!\" | \ + /usr/local/samba/bin/smbclient -M %m -I %I' & + +Of course, this could get annoying after a while :-) + +See also postexec + +.B Default: + none (no command executed) + +.B Example: + preexec = echo \"%u connected to %S from %m (%I)\" >> /tmp/log + +.SS preferred master (G) +This boolean parameter controls if Samba is a preferred master browser +for its workgroup. Setting this gives it a slight edge in elections +and also means it will automatically start an election when it starts +up. + +It is on by default. + +.SS preload +This is an alias for "auto services" + +.SS preserve case (S) + +This controls if new filenames are created with the case that the +client passes, or if they are forced to be the "default" case. + +.B Default: + preserve case = no + +See the section on "NAME MANGLING" for a fuller discussion. + +.SS print command (S) +After a print job has finished spooling to a service, this command will be +used via a system() call to process the spool file. Typically the command +specified will submit the spool file to the host's printing subsystem, but +there is no requirement that this be the case. The server will not remove the +spool file, so whatever command you specify should remove the spool file when +it has been processed, otherwise you will need to manually remove old spool +files. + +The print command is simply a text string. It will be used verbatim, +with two exceptions: All occurrences of "%s" will be replaced by the +appropriate spool file name, and all occurrences of "%p" will be +replaced by the appropriate printer name. The spool file name is +generated automatically by the server, the printer name is discussed +below. + +The full path name will be used for the filename if %s is not preceded +by a /. If you don't like this (it can stuff up some lpq output) then +use %f instead. Any occurances of %f get replaced by the spool +filename without the full path at the front. + +The print command MUST contain at least one occurrence of "%s" or %f - +the "%p" is optional. At the time a job is submitted, if no printer +name is supplied the "%p" will be silently removed from the printer +command. + +If specified in the [global] section, the print command given will be used +for any printable service that does not have its own print command specified. + +If there is neither a specified print command for a printable service nor a +global print command, spool files will be created but not processed and (most +importantly) not removed. + +Note that printing may fail on some UNIXes from the "nobody" +account. If this happens then create an alternative guest account that +can print and set the "guest account" in the [global] section. + +You can form quite complex print commands by realising that they are +just passed to a shell. For example the following will log a print +job, print the file, then remove it. Note that ; is the usual +separator for command in shell scripts. + +print command = echo Printing %s >> /tmp/print.log; lpr -P %p %s; rm %s + +You may have to vary this command considerably depending on how you +normally print files on your system. + +.B Default: + print command = lpr -r -P %p %s + +.B Example: + print command = /usr/local/samba/bin/myprintscript %p %s +.SS print ok (S) +See +.B printable. +.SS printable (S) +A synonym for this parameter is 'print ok'. + +If this parameter is 'yes', then clients may open, write to and submit spool +files on the directory specified for the service. + +Note that a printable service will ALWAYS allow writing to the service path +(user privileges permitting) via the spooling of print data. The 'read only' +parameter controls only non-printing access to the resource. + +.B Default: + printable = no + +.B Example: + printable = yes + +.SS printing (G) +This parameters controls how printer status information is interpreted +on your system, and also affects the default values for the "print +command", "lpq command" and "lprm command". + +Currently six printing styles are supported. They are "printing = +bsd", "printing = sysv", "printing = hpux", "printing = aix", +"printing = qnx" and "printing = plp". + +To see what the defaults are for the other print commands when using +these three options use the "testparm" program. + + +.SS printcap name (G) +This parameter may be used to override the compiled-in default printcap +name used by the server (usually /etc/printcap). See the discussion of the +[printers] section above for reasons why you might want to do this. + +For those of you without a printcap (say on SysV) you can just create a +minimal file that looks like a printcap and set "printcap name =" in +[global] to point at it. + +A minimal printcap file would look something like this: + +print1|My Printer 1 +.br +print2|My Printer 2 +.br +print3|My Printer 3 +.br +print4|My Printer 4 +.br +print5|My Printer 5 + +where the | separates aliases of a printer. The fact that the second +alias has a space in it gives a hint to Samba that it's a comment. + +NOTE: Under AIX the default printcap name is "/etc/qconfig". Samba +will assume the file is in AIX "qconfig" format if the string +"/qconfig" appears in the printcap filename. + +.B Default: + printcap name = /etc/printcap + +.B Example: + printcap name = /etc/myprintcap +.SS printer (S) +A synonym for this parameter is 'printer name'. + +This parameter specifies the name of the printer to which print jobs spooled +through a printable service will be sent. + +If specified in the [global] section, the printer name given will be used +for any printable service that does not have its own printer name specified. + +.B Default: + none (but may be 'lp' on many systems) + +.B Example: + printer name = laserwriter + +.SS printer driver (S) +This option allows you to control the string that clients receive when +they ask the server for the printer driver associated with a +printer. If you are using Windows95 or WindowsNT then you can use this +to automate the setup of printers on your system. + +You need to set this parameter to the exact string (case sensitive) +that describes the appropriate printer driver for your system. +If you don't know the exact string to use then you should first try +with no "printer driver" option set and the client will give you a +list of printer drivers. The appropriate strings are shown in a +scrollbox after you have chosen the printer manufacturer. + +.B Example: + printer driver = HP LaserJet 4L + +.SS printer name (S) +See +.B printer. + +.SS protocol (G) +The value of the parameter (a string) is the highest protocol level that will +be supported by the server. + +Possible values are CORE, COREPLUS, LANMAN1, LANMAN2 and NT1. The relative +merits of each are discussed in the README file. + +Normally this option should not be set as the automatic negotiation +phase in the SMB protocol takes care of choosing the appropriate protocol. + +.B Default: + protocol = NT1 + +.B Example: + protocol = LANMAN1 +.SS public (S) +A synonym for this parameter is 'guest ok'. + +If this parameter is 'yes' for a service, then no password is required +to connect to the service. Privileges will be those of the guest +account. + +See the section below on user/password validation for more information about +this option. + +.B Default: + public = no + +.B Example: + public = yes +.SS read list (S) +This is a list of users that are given read-only access to a +service. If the connecting user is in this list then they will +not be given write access, no matter what the "read only" option +is set to. The list can include group names using the @group syntax. + +See also the "write list" option + +.B Default: + read list = + +.B Example: + read list = mary, @students + +.SS read only (S) +See +.B writable +and +.B write ok. +Note that this is an inverted synonym for writable and write ok. +.SS read prediction (G) +This options enables or disables the read prediction code used to +speed up reads from the server. When enabled the server will try to +pre-read data from the last accessed file that was opened read-only +while waiting for packets. + +.SS Default: + read prediction = False + +.SS Example: + read prediction = True +.SS read raw (G) +This parameter controls whether or not the server will support raw reads when +transferring data to clients. + +If enabled, raw reads allow reads of 65535 bytes in one packet. This +typically provides a major performance benefit. + +However, some clients either negotiate the allowable block size incorrectly +or are incapable of supporting larger block sizes, and for these clients you +may need to disable raw reads. + +In general this parameter should be viewed as a system tuning tool and left +severely alone. See also +.B write raw. + +.B Default: + read raw = yes + +.B Example: + read raw = no +.SS read size (G) + +The option "read size" affects the overlap of disk reads/writes with +network reads/writes. If the amount of data being transferred in +several of the SMB commands (currently SMBwrite, SMBwriteX and +SMBreadbraw) is larger than this value then the server begins writing +the data before it has received the whole packet from the network, or +in the case of SMBreadbraw, it begins writing to the network before +all the data has been read from disk. + +This overlapping works best when the speeds of disk and network access +are similar, having very little effect when the speed of one is much +greater than the other. + +The default value is 2048, but very little experimentation has been +done yet to determine the optimal value, and it is likely that the best +value will vary greatly between systems anyway. A value over 65536 is +pointless and will cause you to allocate memory unnecessarily. + +.B Default: + read size = 2048 + +.B Example: + read size = 8192 + +.SS remote announce (G) + +This option allows you to setup nmbd to periodically announce itself +to arbitrary IP addresses with an arbitrary workgroup name. + +This is useful if you want your Samba server to appear in a remote +workgroup for which the normal browse propogation rules don't +work. The remote workgroup can be anywhere that you can send IP +packets to. + +For example: + + remote announce = 192.168.2.255/SERVERS 192.168.4.255/STAFF + +the above line would cause nmbd to announce itself to the two given IP +addresses using the given workgroup names. If you leave out the +workgroup name then the one given in the "workgroup" option is used +instead. + +The IP addresses you choose would normally be the broadcast addresses +of the remote networks, but can also be the IP addresses of known +browse masters if your network config is that stable. + +This option replaces similar functionality from the nmbd lmhosts file. + +.SS revalidate (S) + +This options controls whether Samba will allow a previously validated +username/password pair to be used to attach to a share. Thus if you +connect to \\\\server\\share1 then to \\\\server\\share2 it won't +automatically allow the client to request connection to the second +share as the same username as the first without a password. + +If "revalidate" is True then the client will be denied automatic +access as the same username. + +.B Default: + revalidate = False + +.B Example: + revalidate = True + +.SS root (G) +See +.B root directory. +.SS root dir (G) +See +.B root directory. +.SS root directory (G) +Synonyms for this parameter are 'root dir' and 'root'. + +The server will chroot() to this directory on startup. This is not +strictly necessary for secure operation. Even without it the server +will deny access to files not in one of the service entries. It may +also check for, and deny access to, soft links to other parts of the +filesystem, or attempts to use .. in file names to access other +directories (depending on the setting of the "wide links" parameter). + +Adding a "root dir" entry other than "/" adds an extra level of security, +but at a price. It absolutely ensures that no access is given to files not +in the sub-tree specified in the "root dir" option, *including* some files +needed for complete operation of the server. To maintain full operability +of the server you will need to mirror some system files into the "root dir" +tree. In particular you will need to mirror /etc/passwd (or a subset of it), +and any binaries or configuration files needed for printing (if required). +The set of files that must be mirrored is operating system dependent. + +.B Default: + root directory = / + +.B Example: + root directory = /homes/smb +.SS security (G) +This option affects how clients respond to Samba. + +The option sets the "security mode bit" in replies to protocol negotiations +to turn share level security on or off. Clients decide based on this bit +whether (and how) to transfer user and password information to the server. + +The default is "security=SHARE", mainly because that was the only +option at one stage. + +The alternatives are "security = user" or "security = server". + +If your PCs use usernames that are the same as their usernames on the +UNIX machine then you will want to use "security = user". If you +mostly use usernames that don't exist on the UNIX box then use +"security = share". + +There is a bug in WfWg that may affect your decision. When in user +level security a WfWg client will totally ignore the password you type +in the "connect drive" dialog box. This makes it very difficult (if +not impossible) to connect to a Samba service as anyone except the +user that you are logged into WfWg as. + +If you use "security = server" then Samba will try to validate the +username/password by passing it to another SMB server, such as an NT +box. If this fails it will revert to "security = USER". + +See the "password server" option for more details. + +.B Default: + security = SHARE + +.B Example: + security = USER +.SS server string (G) +This controls what string will show up in the printer comment box in +print manager and next to the IPC connection in "net view". It can be +any string that you wish to show to your users. + +It also sets what will appear in browse lists next to the machine name. + +A %v will be replaced with the Samba version number. + +A %h will be replaced with the hostname. + +.B Default: + server string = Samba %v + +.B Example: + server string = University of GNUs Samba Server + +.SS smbrun (G) +This sets the full path to the smbrun binary. This defaults to the +value in the Makefile. + +You must get this path right for many services to work correctly. + +.B Default: +taken from Makefile + +.B Example: + smbrun = /usr/local/samba/bin/smbrun + +.SS short preserve case (S) + +This controls if new short filenames are created with the case that +the client passes, or if they are forced to be the "default" case. + +.B Default: + short preserve case = no + +See the section on "NAME MANGLING" for a fuller discussion. + +.SS root preexec (S) + +This is the same as preexec except that the command is run as +root. This is useful for mounting filesystems (such as cdroms) before +a connection is finalised. + +.SS root postexec (S) + +This is the same as postexec except that the command is run as +root. This is useful for unmounting filesystems (such as cdroms) after +a connection is closed. + +.SS set directory (S) +If 'set directory = no', then users of the service may not use the setdir +command to change directory. + +The setdir comand is only implemented in the Digital Pathworks client. See the +Pathworks documentation for details. + +.B Default: + set directory = no + +.B Example: + set directory = yes + +.SS share modes (S) + +This enables or disables the honouring of the "share modes" during a +file open. These modes are used by clients to gain exclusive read or +write access to a file. + +These open modes are not directly supported by UNIX, so they are +simulated using lock files in the "lock directory". The "lock +directory" specified in smb.conf must be readable by all users. + +The share modes that are enabled by this option are DENY_DOS, +DENY_ALL, DENY_READ, DENY_WRITE, DENY_NONE and DENY_FCB. + +Enabling this option gives full share compatability but may cost a bit +of processing time on the UNIX server. They are enabled by default. + +.B Default: + share modes = yes + +.B Example: + share modes = no + +.SS socket address (G) + +This option allows you to control what address Samba will listen for +connections on. This is used to support multiple virtual interfaces on +the one server, each with a different configuration. + +By default samba will accept connections on any address. + +.B Example: + socket address = 192.168.2.20 + +.SS socket options (G) +This option (which can also be invoked with the -O command line +option) allows you to set socket options to be used when talking with +the client. + +Socket options are controls on the networking layer of the operating +systems which allow the connection to be tuned. + +This option will typically be used to tune your Samba server for +optimal performance for your local network. There is no way that Samba +can know what the optimal parameters are for your net, so you must +experiment and choose them yourself. I strongly suggest you read the +appropriate documentation for your operating system first (perhaps +"man setsockopt" will help). + +You may find that on some systems Samba will say "Unknown socket +option" when you supply an option. This means you either mis-typed it +or you need to add an include file to includes.h for your OS. If the +latter is the case please send the patch to me +(samba-bugs@anu.edu.au). + +Any of the supported socket options may be combined in any way you +like, as long as your OS allows it. + +This is the list of socket options currently settable using this +option: + + SO_KEEPALIVE + + SO_REUSEADDR + + SO_BROADCAST + + TCP_NODELAY + + IPTOS_LOWDELAY + + IPTOS_THROUGHPUT + + SO_SNDBUF * + + SO_RCVBUF * + + SO_SNDLOWAT * + + SO_RCVLOWAT * + +Those marked with a * take an integer argument. The others can +optionally take a 1 or 0 argument to enable or disable the option, by +default they will be enabled if you don't specify 1 or 0. + +To specify an argument use the syntax SOME_OPTION=VALUE for example +SO_SNDBUF=8192. Note that you must not have any spaces before or after +the = sign. + +If you are on a local network then a sensible option might be + +socket options = IPTOS_LOWDELAY + +If you have an almost unloaded local network and you don't mind a lot +of extra CPU usage in the server then you could try + +socket options = IPTOS_LOWDELAY TCP_NODELAY + +If you are on a wide area network then perhaps try setting +IPTOS_THROUGHPUT. + +Note that several of the options may cause your Samba server to fail +completely. Use these options with caution! + +.B Default: + no socket options + +.B Example: + socket options = IPTOS_LOWDELAY + + + + +.SS status (G) +This enables or disables logging of connections to a status file that +.B smbstatus +can read. + +With this disabled +.B smbstatus +won't be able to tell you what +connections are active. + +.B Default: + status = yes + +.B Example: + status = no + +.SS strip dot (G) +This is a boolean that controls whether to strip trailing dots off +filenames. This helps with some CDROMs that have filenames ending in a +single dot. + +NOTE: This option is now obsolete, and may be removed in future. You +should use the "mangled map" option instead as it is much more +general. + +.SS strict locking (S) +This is a boolean that controls the handling of file locking in the +server. When this is set to yes the server will check every read and +write access for file locks, and deny access if locks exist. This can +be slow on some systems. + +When strict locking is "no" the server does file lock checks only when +the client explicitly asks for them. + +Well behaved clients always ask for lock checks when it is important, +so in the vast majority of cases "strict locking = no" is preferable. + +.B Default: + strict locking = no + +.B Example: + strict locking = yes + +.SS sync always (S) + +This is a boolean parameter that controls whether writes will always +be written to stable storage before the write call returns. If this is +false then the server will be guided by the client's request in each +write call (clients can set a bit indicating that a particular write +should be synchronous). If this is true then every write will be +followed by a fsync() call to ensure the data is written to disk. + +.B Default: + sync always = no + +.B Example: + sync always = yes + +.SS time offset (G) +This parameter is a setting in minutes to add to the normal GMT to +local time conversion. This is useful if you are serving a lot of PCs +that have incorrect daylight saving time handling. + +.B Default: + time offset = 0 + +.B Example: + time offset = 60 + +.SS user (S) +See +.B username. +.SS username (S) +A synonym for this parameter is 'user'. + +Multiple users may be specified in a comma-delimited list, in which case the +supplied password will be tested against each username in turn (left to right). + +The username= line is needed only when the PC is unable to supply its own +username. This is the case for the coreplus protocol or where your +users have different WfWg usernames to UNIX usernames. In both these +cases you may also be better using the \\\\server\\share%user syntax +instead. + +The username= line is not a great solution in many cases as it means Samba +will try to validate the supplied password against each of the +usernames in the username= line in turn. This is slow and a bad idea for +lots of users in case of duplicate passwords. You may get timeouts or +security breaches using this parameter unwisely. + +Samba relies on the underlying UNIX security. This parameter does not +restrict who can login, it just offers hints to the Samba server as to +what usernames might correspond to the supplied password. Users can +login as whoever they please and they will be able to do no more +damage than if they started a telnet session. The daemon runs as the +user that they log in as, so they cannot do anything that user cannot +do. + +To restrict a service to a particular set of users you can use the +"valid users=" line. + +If any of the usernames begin with a @ then the name will be looked up +in the groups file and will expand to a list of all users in the group +of that name. Note that searching though a groups file can take quite +some time, and some clients may time out during the search. + +See the section below on username/password validation for more information +on how this parameter determines access to the services. + +.B Default: + The guest account if a guest service, else the name of the service. + +.B Examples: + username = fred + username = fred, mary, jack, jane, @users, @pcgroup + +.SS username map (G) + +This option allows you to to specify a file containing a mapping of +usernames from the clients to the server. This can be used for several +purposes. The most common is to map usernames that users use on DOS or +Windows machines to those that the UNIX box uses. The other is to map +multiple users to a single username so that they can more easily share +files. + +The map file is parsed line by line. Each line should contain a single +UNIX username on the left then a '=' followed by a list of usernames +on the right. The list of usernames on the right may contain names of +the form @group in which case they will match any UNIX username in +that group. The special client name '*' is a wildcard and matches any +name. + +The file is processed on each line by taking the supplied username and +comparing it with each username on the right hand side of the '=' +signs. If the supplied name matches any of the names on the right +hand side then it is replaced with the name on the left. Processing +then continues with the next line. + +If any line begins with a '#' or a ';' then it is ignored + +For example to map from the name "admin" or "administrator" to the UNIX +name "root" you would use + + root = admin administrator + +Or to map anyone in the UNIX group "system" to the UNIX name "sys" you +would use + + sys = @system + +You can have as many mappings as you like in a username map file. + +Note that the remapping is applied to all occurances of +usernames. Thus if you connect to "\\\\server\\fred" and "fred" is +remapped to "mary" then you will actually be connecting to +"\\\\server\\mary" and will need to supply a password suitable for +"mary" not "fred". The only exception to this is the username passed +to the "password server" (if you have one). The password server will +receive whatever username the client supplies without modification. + +Also note that no reverse mapping is done. The main effect this has is +with printing. Users who have been mapped may have trouble deleting +print jobs as PrintManager under WfWg will think they don't own the +print job. + +.B Default + no username map + +.B Example + username map = /usr/local/samba/lib/users.map + +.SS valid chars (S) + +The option allows you to specify additional characters that should be +considered valid by the server in filenames. This is particularly +useful for national character sets, such as adding u-umlaut or a-ring. + +The option takes a list of characters in either integer or character +form with spaces between them. If you give two characters with a colon +between them then it will be taken as an lowercase:uppercase pair. + +If you have an editor capable of entering the characters into the +config file then it is probably easiest to use this method. Otherwise +you can specify the characters in octal, decimal or hexidecimal form +using the usual C notation. + +For example to add the single character 'Z' to the charset (which is a +pointless thing to do as it's already there) you could do one of the +following + +valid chars = Z +valid chars = z:Z +valid chars = 0132:0172 + +The last two examples above actually add two characters, and alter +the uppercase and lowercase mappings appropriately. + +.B Default +.br + Samba defaults to using a reasonable set of valid characters +.br + for english systems + +.B Example + valid chars = 0345:0305 0366:0326 0344:0304 + +The above example allows filenames to have the swedish characters in +them. + +NOTE: It is actually quite difficult to correctly produce a "valid +chars" line for a particular system. To automate the process +tino@augsburg.net has written a package called "validchars" which will +automatically produce a complete "valid chars" line for a given client +system. Look in the examples subdirectory for this package. + +.SS valid users (S) +This is a list of users that should be allowed to login to this +service. A name starting with @ is interpreted as a UNIX group. + +If this is empty (the default) then any user can login. If a username +is in both this list and the "invalid users" list then access is +denied for that user. + +The current servicename is substituted for %S. This is useful in the +[homes] section. + +See also "invalid users" + +.B Default + No valid users list. (anyone can login) + +.B Example + valid users = greg, @pcusers + +.SS volume (S) +This allows you to override the volume label returned for a +share. Useful for CDROMs with installation programs that insist on a +particular volume label. + +The default is the name of the share + +.SS wide links (S) +This parameter controls whether or not links in the UNIX file system may be +followed by the server. Links that point to areas within the directory tree +exported by the server are always allowed; this parameter controls access +only to areas that are outside the directory tree being exported. + +.B Default: + wide links = yes + +.B Example: + wide links = no + +.SS wins proxy (G) + +This is a boolean that controls if nmbd will respond to broadcast name +queries on behalf of other hosts. You may need to set this to no for +some older clients. + +.B Default: + wins proxy = no +.SS wins support (G) + +This boolean controls if Samba will act as a WINS server. You should +normally set this to true unless you already have another WINS server +on the network. + +.B Default: + wins support = yes +.SS wins server (G) + +This specifies the DNS name of the WINS server that Samba should +register with. If you have a WINS server on your network then you +should set this to the WINS servers name. + +This option only takes effect if Samba is not acting as a WINS server +itself. + +.B Default: + wins server = +.SS workgroup (G) + +This controls what workgroup your server will appear to be in when +queried by clients. This can be different to the workgroup specified +in the nmbd configuration, but it is probably best if you set them to + the same value. + +.B Default: + set in the Makefile + +.B Example: + workgroup = MYGROUP + +.SS write ok (S) +See +.B writable +and +.B read only. +.SS writable (S) +A synonym for this parameter is 'write ok'. An inverted synonym is 'read only'. + +If this parameter is 'no', then users of a service may not create or modify +files in the service's directory. + +Note that a printable service ('printable = yes') will ALWAYS allow +writing to the directory (user privileges permitting), but only via +spooling operations. + +.B Default: + writable = no + +.B Examples: + read only = no + writable = yes + write ok = yes +.SS write list (S) +This is a list of users that are given read-write access to a +service. If the connecting user is in this list then they will be +given write access, no matter what the "read only" option is set +to. The list can include group names using the @group syntax. + +Note that if a user is in both the read list and the write list then +they will be given write access. + +See also the "read list" option + +.B Default: + write list = + +.B Example: + write list = admin, root, @staff + +.SS write raw (G) +This parameter controls whether or not the server will support raw writes when +transferring data from clients. + +.B Default: + write raw = yes + +.B Example: + write raw = no +.SH NOTE ABOUT USERNAME/PASSWORD VALIDATION +There are a number of ways in which a user can connect to a +service. The server follows the following steps in determining if it +will allow a connection to a specified service. If all the steps fail +then the connection request is rejected. If one of the steps pass then +the following steps are not checked. + +If the service is marked "guest only = yes" then steps 1 to 5 are skipped + +Step 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. + +Step 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. + +Step 3: The client's netbios name and any previously used user names +are checked against the supplied password, if they match then the +connection is allowed as the corresponding user. + +Step 4: If the client has previously validated a username/password +pair with the server and the client has passed the validation token +then that username is used. This step is skipped if "revalidate = yes" +for this service. + +Step 5: If a "user = " field is given in the smb.conf file for the +service and the client has supplied a password, and that password +matches (according to the UNIX system's password checking) with one of +the usernames from the user= field then the connection 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. + +Step 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. +.SH WARNINGS +Although the configuration file permits service names to contain spaces, +your client software may not. Spaces will be ignored in comparisons anyway, +so it shouldn't be a problem - but be aware of the possibility. + +On a similar note, many clients - especially DOS clients - limit service +names to eight characters. Smbd has no such limitation, but attempts +to connect from such clients will fail if they truncate the service names. +For this reason you should probably keep your service names down to eight +characters in length. + +Use of the [homes] and [printers] special sections make life for an +administrator easy, but the various combinations of default attributes can be +tricky. Take extreme care when designing these sections. In particular, +ensure that the permissions on spool directories are correct. +.SH VERSION +This man page is (mostly) correct for version 1.9.00 of the Samba suite, plus some +of the recent patches to it. These notes will necessarily lag behind +development of the software, so it is possible that your version of +the server has extensions or parameter semantics that differ from or are not +covered by this man page. Please notify these to the address below for +rectification. + +Prior to version 1.5.21 of the Samba suite, the configuration file was +radically different (more primitive). If you are using a version earlier than +1.8.05, it is STRONGLY recommended that you upgrade. +.SH OPTIONS +Not applicable. +.SH FILES +Not applicable. +.SH ENVIRONMENT VARIABLES +Not applicable. +.SH SEE ALSO +.BR smbd (8), +.BR smbclient (1), +.BR nmbd (8), +.BR testparm (1), +.BR testprns (1), +.BR lpq (1), +.BR hosts_access (5) +.SH DIAGNOSTICS +[This section under construction] + +Most diagnostics issued by the server are logged in a specified log file. The +log file name is specified at compile time, but may be overridden on the +smbd command line (see +.BR smbd (8)). + +The number and nature of diagnostics available depends on the debug level used +by the server. If you have problems, set the debug level to 3 and peruse the +log files. + +Most messages are reasonably self-explanatory. Unfortunately, at time of +creation of this man page the source code is still too fluid to warrant +describing each and every diagnostic. At this stage your best bet is still +to grep the source code and inspect the conditions that gave rise to the +diagnostics you are seeing. +.SH BUGS +None known. + +Please send bug reports, comments and so on to: + +.RS 3 +.B samba-bugs@anu.edu.au (Andrew Tridgell) + +.RS 3 +or to the mailing list: +.RE + +.B samba@listproc.anu.edu.au + +.RE +You may also like to subscribe to the announcement channel: + +.RS 3 +.B samba-announce@listproc.anu.edu.au +.RE + +To subscribe to these lists send a message to +listproc@listproc.anu.edu.au with a body of "subscribe samba Your +Name" or "subscribe samba-announce Your Name". + +Errors or suggestions for improvements to the Samba man pages should be +mailed to: + +.RS 3 +.B samba-bugs@anu.edu.au (Andrew Tridgell) +.RE + |