From a4a8d71085f2df22bbebf1a39cb98864255ec9e2 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Wed, 16 Jun 2004 16:20:05 +0000 Subject: Makefile dependency updates (This used to be commit d519625378fdc5a1c0192766095104fded5b628c) --- docs/manpages/smb.conf.5.xml | 656 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 656 insertions(+) create mode 100644 docs/manpages/smb.conf.5.xml (limited to 'docs/manpages') diff --git a/docs/manpages/smb.conf.5.xml b/docs/manpages/smb.conf.5.xml new file mode 100644 index 0000000000..a81f8e0274 --- /dev/null +++ b/docs/manpages/smb.conf.5.xml @@ -0,0 +1,656 @@ + + + + smb.conf + 5 + + + + + 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 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 (;) or a hash (#) + character is ignored, as are lines containing only whitespace. + + 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 significant in boolean + values, but is preserved in string values. 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 descriptions. + + 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 modern clients such as + Windows 95/98/ME/NT/2000, this should not be necessary. + + 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 + read onlyread only = no + + + The following sample section defines a printable share. + The share is read-only, 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 onlyyes + printableyes + guest okyes + + + + + SPECIAL SECTIONS + + + The [global] section + + Parameters in this section apply to the server + as a whole, or are defaults for sections that 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 directories 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 + username 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, you may find it useful + to use the %S macro. For example : + + path = /data/pchome/%S + + is 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 normal service section can specify, though some make more sense + than others. The following is a typical and suitable [homes] + section: + + + [homes] + read onlyno + + + 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 + is wise to also specify read only access. + + 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] 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] section. + + 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 username was given, the username is set to the located + printer name. + + + The [printers] service MUST be + printable - if you specify otherwise, the server will refuse + to load the configuration file. + + Typically the path specified is that of a + world-writeable spool directory with the sticky bit set on + it. A typical [printers] entry looks like + this: + + + [printers] + path/usr/spool/public + guest okyes + printableyes + + + 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 only recognize + 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 (|). + + 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 sections (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. 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 is 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: + + + + %U + session username (the username that the client + wanted, not necessarily the same as the one they got). + + + + %G + primary group name of %U. + + + + %h + the Internet 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. + + This parameter is not available when Samba listens + on port 445, as clients no longer send this information. + + + + + + %M + the Internet name of the client machine. + + + + + %R + the selected protocol level after + protocol negotiation. 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, Windows for Workgroups, Windows 95, + Windows NT and Windows 2000. Anything else will be known as + UNKNOWN. If it gets it wrong sending a level + 3 log to samba@samba.org + should allow it to be fixed. + + + + %I + The IP address of the client machine. + + + + + %T + the current date and time. + + + + %D + Name of the domain or workgroup of the current user. + + + + %$(envvar) + The value of the environment variable + envar. + + + + The following substitutes apply only to some configuration options (only those + that are used when a connection has been established): + + + + %S + the name of the current service, if any. + + + + + %P + the root directory of the current service, + if any. + + + + %u + username of the current service, if any. + + + + + %g + primary group name of %u. + + + + %H + the home directory of the user given + by %u. + + + + %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, this value will be the same as %L. + + + + + %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. + + + + 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 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 whether names that have characters that + aren't of the default case are mangled. For example, + if this is yes, a name like Mail will be mangled. + Default no. + + + + case sensitive = yes/no/auto + controls whether filenames are case sensitive. If + they aren't, Samba must do a filename search and match on passed + names. The default setting of auto allows clients that support case + sensitive filenames (Linux CIFSVFS and smbclient 3.0.5 and above currently) + to tell the Samba server on a per-packet basis that they wish to access + the file system in a case-sensitive manner (to support UNIX case sensitive + semantics). No Windows or DOS system supports case-sensitive filename so + setting this option to auto is that same as setting it to no for them. + Default auto. + + + + default case = upper/lower + controls what the default case is for new + filenames. Default lower. + + + + preserve case = yes/no + controls whether 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 used with preserve case = yes + to permit long filenames to retain their case, while short names + are lowercased. Default yes. + + + + By default, Samba 3.0 has the same semantics as a Windows + NT server, in that it is case insensitive but case preserving. + + + + + 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 determining + if it will allow a connection to a specified service. If all the + steps fail, the connection request is rejected. However, if one of the + steps succeeds, the following steps are not checked. + + If the service is marked guest only = yes and the + server is running with share-level security (security = share, + steps 1 to 5 are skipped. + + + + If the client has passed a username/password + pair and that username/password pair is validated by the UNIX + system's password programs, the connection is made as that + username. This includes the + \\server\service%username method of passing + a username. + + If the client has previously registered a username + with the system and now supplies a correct password for that + username, the connection is allowed. + + The client's NetBIOS name and any previously + used usernames are checked against the supplied password. If + they match, the connection is allowed as the corresponding + user. + + If the client has previously validated a + username/password pair with the server and the client has passed + the validation token, that username is used. + + 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, the connection is made as + the username in the user = line. If one + of the usernames in the user = list begins with a + @, that name expands to a list of names in + the group of the same name. + + If the service is a guest service, a + connection is made as the username given in the guest + account = for the service, irrespective of the + supplied password. + + + + + + EXPLANATION OF EACH PARAMETER + + + + + + + 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 + 8 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. + + + + VERSION + + This man page is correct for version 3.0 of the Samba suite. + + + + SEE ALSO + + samba + 7, smbpasswd + 8, swat + 8, smbd + 8, nmbd + 8, smbclient + 1, nmblookup + 1, testparm + 1, testprns + 1. + + + + AUTHOR + + The original Samba software and related utilities + were created by Andrew Tridgell. Samba is now developed + by the Samba Team as an Open Source project similar + to the way the Linux kernel is developed. + + The original Samba man pages were written by Karl Auer. + The man page sources were converted to YODL format (another + excellent piece of Open Source software, available at + ftp://ftp.icce.rug.nl/pub/unix/) and updated for the Samba 2.0 + release by Jeremy Allison. The conversion to DocBook for + Samba 2.2 was done by Gerald Carter. The conversion to DocBook XML 4.2 + for Samba 3.0 was done by Alexander Bokovoy. + + + -- cgit