From d62754e9487d62bf11bc0a4970a1bca2dd5d6727 Mon Sep 17 00:00:00 2001 From: Gerald Carter Date: Tue, 20 Feb 2001 05:31:37 +0000 Subject: save as we go. Probably last check in for tonight. jerry (This used to be commit 519010345f1ac11e593597d538c08f95d92afe6b) --- docs/docbook/smb.conf.5.sgml | 533 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 533 insertions(+) create mode 100644 docs/docbook/smb.conf.5.sgml (limited to 'docs') diff --git a/docs/docbook/smb.conf.5.sgml b/docs/docbook/smb.conf.5.sgml new file mode 100644 index 0000000000..ed2dd53f5d --- /dev/null +++ b/docs/docbook/smb.conf.5.sgml @@ -0,0 +1,533 @@ + + + + + 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 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). + + 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. + + Note that the access rights granted by the server are + masked by the access rights granted to the specified or guest + UNIX user by the host system. The server does not grant more + access than the host system grants. + + The following sample section defines a file space share. + The user has write access to the path /home/bar. + The share is accessed via the share name "foo": + + + + [foo] + path = /home/bar + writeable = true + + + + The following sample section defines a printable share. + The share is readonly, but printable. That is, the only write + access permitted is via calls to open, write to and close a + spool file. The guest ok parameter means + access will be permitted as the default guest user (specified + elsewhere): + + + + [aprinter] + path = /usr/spool/public + writeable = false + printable = true + guest ok = true + + + + + + SPECIAL SECTIONS + + + The [global] section + + Parameters in this section apply to the server + as a whole, or are defaults for sections which do not + specifically define certain items. See the notes + under PARAMETERS for more information. + + + + The [homes] section + + If a section called homes is included in the + configuration file, services connecting clients to their + home 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 + user name and looked up in the local password file. If the + name exists and the correct password has been given, a share is + created by cloning the [homes] section. + + Some modifications are then made to the newly + created share: + + + The share name is changed from homes to + the located username. + + If no path was given, the path is set to + the user's home directory. + + + If you decide to use a path= line + in your [homes] section then you may find it useful + to use the %S macro. For 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 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] + writeable = yes + + + + An important point is that if guest access is specified + in the [homes] section, all home directories will be + visible to all clients without a password. + In the very unlikely event that this is actually desirable, it + would be wise to also specify read only + access. + + Note that the browseable flag for + auto home directories will be inherited from the global browseable + flag, not the [homes] browseable flag. This is useful as + it means 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. + + + Note that the [printers] service MUST be + printable - if you specify otherwise, the server will refuse + to load the configuration file. + + Typically the path specified would be that of a + world-writeable spool directory with the sticky bit set on + it. A typical [printers] entry would look like + this: + + + [printers] + path = /usr/spool/public + guest ok = yes + printable = yes + + + All aliases given for a printer in the printcap file + are legitimate printer names as far as the server is 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 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 ("|"). + + NOTE: On SYSV systems which use lpstat to determine what + printers are defined on the system you may be able to use + "printcap name = lpstat" to automatically obtain a list + of printers. See the "printcap name" option + for more details. + + + + + PARAMETRS + + 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. Note that all S parameters can also be specified in + the [global] section - in which case they will define + the default behavior for all services. + + Parameters are arranged here in alphabetical order - this may + not create best bedfellows, but at least you can find them! Where + there are synonyms, the preferred synonym is described, others refer + to the preferred synonym. + + + + VARIABLE SUBSTITUTIONS + + Many of the strings that are settable in the config file + can take substitutions. For example the option "path = + /tmp/%u" would be interpreted as "path = + /tmp/john" if the user connected with the username john. + + These substitutions are mostly noted in the descriptions below, + but there are some general substitutions which apply whenever they + might be relevant. These are: + + + + %S + the name of the current service, if any. + + + + + %P + the root directory of the current service, + if any. + + + + %u + user name of the current service, if any. + + + + + %g + primary group name of %u. + + + + %U + session user name (the user name that the client + wanted, not necessarily the same as the one they got). + + + + %G + primary group name of %U. + + + + %H + the home directory of the user given + by %u. + + + + %v + the Samba version. + + + + %h + the internet hostname that Samba is running + on. + + + + %m + the NetBIOS name of the client machine + (very 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. + + + + + %N + the name of your NIS home directory server. + This is obtained from your NIS auto.map entry. If you have + not compiled Samba with the --with-automount + option then this value will be the same as %. + + + + + %p + the path of the service's home directory, + obtained from your NIS auto.map entry. The NIS auto.map entry + is split up as "%N:%p". + + + + %R + the selected protocol level after + protocol 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, WfWg, + WinNT and Win95. Anything else will be known as + "UNKNOWN". If it gets it wrong then sending a level + 3 log to samba@samba.org + should allow it to be fixed. + + + + %I + The IP address of the client machine. + + + + + %T + the current date and time. + + + + %$(envvar) + The value of the environment variable + envar. + + + + There are some quite creative things that can be done + with these substitutions and other smb.conf options. + + + NAME MANGLINGBy default, Samba 2.2 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 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. + + + 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. + + 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. + + 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. + + 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. + + 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. + + If the service is a guest service then a + connection is made as the username given in the "guest + account =" for the service, irrespective of the + supplied password. + + + + + + COMPLETE LIST OF GLOBAL PARAMETERS + + Here is a list of all global parameters. See the section of + each parameter for details. Note that some are synonyms. + + + -- cgit