diff options
| author | cvs2svn Import User <samba-bugs@samba.org> | 2003-04-15 12:35:53 +0000 |
|---|---|---|
| committer | cvs2svn Import User <samba-bugs@samba.org> | 2003-04-15 12:35:53 +0000 |
| commit | f39855dcf6b9934c7d535a7068e5d70b3b11c376 (patch) | |
| tree | 9169325fdaeeb7d1ce044fdb6845ba33ebd548bc /docs/docbook/smbdotconf | |
| parent | 37dc79d2b6a29841cf4249cb6aba646fd2d1f83c (diff) | |
| parent | 4bde67ef6011aecc023be5b0f56687da3ca7a875 (diff) | |
| download | samba-f39855dcf6b9934c7d535a7068e5d70b3b11c376.tar.gz samba-f39855dcf6b9934c7d535a7068e5d70b3b11c376.tar.bz2 samba-f39855dcf6b9934c7d535a7068e5d70b3b11c376.zip | |
This commit was manufactured by cvs2svn to create branch 'SAMBA_3_0'.(This used to be commit 35510176fd4feab6c1e3da2ee0ae791f9a064a2e)
Diffstat (limited to 'docs/docbook/smbdotconf')
57 files changed, 2141 insertions, 0 deletions
diff --git a/docs/docbook/smbdotconf/filename/vetofiles.xml b/docs/docbook/smbdotconf/filename/vetofiles.xml new file mode 100644 index 0000000000..567286580d --- /dev/null +++ b/docs/docbook/smbdotconf/filename/vetofiles.xml @@ -0,0 +1,49 @@ +<samba:parameter name="veto files" + context="S" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This is a list of files and directories that + are neither visible nor accessible. Each entry in the list must + be separated by a '/', which allows spaces to be included + in the entry. '*' and '?' can be used to specify multiple files + or directories as in DOS wildcards.</para> + + <para>Each entry must be a unix path, not a DOS path and + must <emphasis>not</emphasis> include the unix directory + separator '/'.</para> + + <para>Note that the <parameter moreinfo="none">case sensitive</parameter> option + is applicable in vetoing files.</para> + + <para>One feature of the veto files parameter that it + is important to be aware of is Samba's behaviour when + trying to delete a directory. If a directory that is + to be deleted contains nothing but veto files this + deletion will <emphasis>fail</emphasis> unless you also set + the <parameter moreinfo="none">delete veto files</parameter> parameter to + <parameter moreinfo="none">yes</parameter>.</para> + + <para>Setting this parameter will affect the performance + of Samba, as it will be forced to check all files and directories + for a match as they are scanned.</para> + + <para>See also <link linkend="HIDEFILES"><parameter moreinfo="none">hide files + </parameter></link> and <link linkend="CASESENSITIVE"><parameter moreinfo="none"> + case sensitive</parameter></link>.</para> + + <para>Default: <emphasis>No files or directories are vetoed. + </emphasis></para> + + <para>Examples: +<programlisting format="linespecific"> +; Veto any files containing the word Security, +; any ending in .tmp, and any directory containing the +; word root. +veto files = /*Security*/*.tmp/*root*/ + +; Veto the Apple specific files that a NetAtalk server +; creates. +veto files = /.AppleDouble/.bin/.AppleDesktop/Network Trash Folder/ +</programlisting></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/generate-context.xsl b/docs/docbook/smbdotconf/generate-context.xsl new file mode 100644 index 0000000000..13fb216700 --- /dev/null +++ b/docs/docbook/smbdotconf/generate-context.xsl @@ -0,0 +1,55 @@ +<?xml version='1.0'?> +<!-- vim:set sts=2 shiftwidth=2 syntax=xml: --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:exsl="http://exslt.org/common" + xmlns:samba="http://samba.org/common" + version="1.1" + extension-element-prefixes="exsl"> + +<xsl:output method="xml" omit-xml-declaration="yes"/> + +<xsl:param name="smb.context" select="'G'"/> + +<!-- This is needed to copy content unchanged --> +<xsl:template match="@*|node()"> + <xsl:copy> + <xsl:apply-templates select="@*|node()"/> + </xsl:copy> +</xsl:template> + +<xsl:template match="variablelist"> + <xsl:element name="itemizedlist"> + <xsl:apply-templates/> + </xsl:element> +</xsl:template> + +<xsl:template match="//samba:parameter"> + <xsl:message> + <xsl:text>Processing samba:parameter (</xsl:text> + <xsl:value-of select="@name"/> + <xsl:text>)</xsl:text> + </xsl:message> + + <xsl:variable name="name"><xsl:value-of select="translate(translate(string(@name),' ',''), + 'abcdefghijklmnopqrstuvwxyz','ABCDEFGHIJKLMNOPQRSTUVWXYZ')"/> + </xsl:variable> + + <xsl:if test="contains(@context,$smb.context)"> + <xsl:element name="listitem"> + <xsl:element name="para"> + <xsl:element name="link"> + <xsl:attribute name="linkend"> + <xsl:value-of select="$name"/> + </xsl:attribute> + <xsl:element name="parameter"> + <xsl:attribute name="moreinfo"><xsl:text>none</xsl:text></xsl:attribute> + <xsl:value-of select="@name"/> + </xsl:element> + </xsl:element> + </xsl:element> + </xsl:element> + <xsl:text> </xsl:text> + </xsl:if> +</xsl:template> + +</xsl:stylesheet> diff --git a/docs/docbook/smbdotconf/misc/addsharecommand.xml b/docs/docbook/smbdotconf/misc/addsharecommand.xml new file mode 100644 index 0000000000..bd5f2101db --- /dev/null +++ b/docs/docbook/smbdotconf/misc/addsharecommand.xml @@ -0,0 +1,63 @@ +<samba:parameter name="add share command" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>Samba 2.2.0 introduced the ability to dynamically + add and delete shares via the Windows NT 4.0 Server Manager. The + <parameter moreinfo="none">add share command</parameter> is used to define an + external program or script which will add a new service definition + to <filename moreinfo="none">smb.conf</filename>. In order to successfully + execute the <parameter moreinfo="none">add share command</parameter>, <command moreinfo="none">smbd</command> + requires that the administrator be connected using a root account (i.e. + uid == 0). + </para> + + <para> + When executed, <command moreinfo="none">smbd</command> will automatically invoke the + <parameter moreinfo="none">add share command</parameter> with four parameters. + </para> + + <itemizedlist> + <listitem> + <para><parameter moreinfo="none">configFile</parameter> - the location + of the global <filename moreinfo="none">smb.conf</filename> file. + </para> + </listitem> + + <listitem> + <para><parameter moreinfo="none">shareName</parameter> - the name of the new + share. + </para> + </listitem> + + <listitem> + <para><parameter moreinfo="none">pathName</parameter> - path to an **existing** + directory on disk. + </para> + </listitem> + + <listitem> + <para><parameter moreinfo="none">comment</parameter> - comment string to associate + with the new share. + </para> + </listitem> + </itemizedlist> + + <para> + This parameter is only used for add file shares. To add printer shares, + see the <link linkend="ADDPRINTERCOMMAND"><parameter moreinfo="none">addprinter + command</parameter></link>. + </para> + + <para> + See also <link linkend="CHANGESHARECOMMAND"><parameter moreinfo="none">change share + command</parameter></link>, <link linkend="DELETESHARECOMMAND"><parameter moreinfo="none">delete share + command</parameter></link>. + </para> + + <para>Default: <emphasis>none</emphasis></para> + + <para>Example: <command moreinfo="none">add share command = /usr/local/bin/addshare</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/autoservices.xml b/docs/docbook/smbdotconf/misc/autoservices.xml new file mode 100644 index 0000000000..d94997a6ce --- /dev/null +++ b/docs/docbook/smbdotconf/misc/autoservices.xml @@ -0,0 +1,9 @@ +<samba:parameter name="auto services" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This is a synonym for the <link linkend="PRELOAD"> + <parameter moreinfo="none">preload</parameter></link>.</para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/available.xml b/docs/docbook/smbdotconf/misc/available.xml new file mode 100644 index 0000000000..20931b3063 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/available.xml @@ -0,0 +1,13 @@ +<samba:parameter name="available" + context="S" + basic="1" advanced="1" print="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This parameter lets you "turn off" a service. If + <parameter moreinfo="none">available = no</parameter>, then <emphasis>ALL</emphasis> + attempts to connect to the service will fail. Such failures are + logged.</para> + + <para>Default: <command moreinfo="none">available = yes</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/changesharecommand.xml b/docs/docbook/smbdotconf/misc/changesharecommand.xml new file mode 100644 index 0000000000..d0116594c0 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/changesharecommand.xml @@ -0,0 +1,62 @@ +<samba:parameter name="change share command" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>Samba 2.2.0 introduced the ability to dynamically + add and delete shares via the Windows NT 4.0 Server Manager. The + <parameter moreinfo="none">change share command</parameter> is used to define an + external program or script which will modify an existing service definition + in <filename moreinfo="none">smb.conf</filename>. In order to successfully + execute the <parameter moreinfo="none">change share command</parameter>, <command moreinfo="none">smbd</command> + requires that the administrator be connected using a root account (i.e. + uid == 0). + </para> + + <para> + When executed, <command moreinfo="none">smbd</command> will automatically invoke the + <parameter moreinfo="none">change share command</parameter> with four parameters. + </para> + + <itemizedlist> + <listitem> + <para><parameter moreinfo="none">configFile</parameter> - the location + of the global <filename moreinfo="none">smb.conf</filename> file. + </para> + </listitem> + + <listitem> + <para><parameter moreinfo="none">shareName</parameter> - the name of the new + share. + </para> + </listitem> + + <listitem> + <para><parameter moreinfo="none">pathName</parameter> - path to an **existing** + directory on disk. + </para> + </listitem> + + <listitem> + <para><parameter moreinfo="none">comment</parameter> - comment string to associate + with the new share. + </para> + </listitem> + </itemizedlist> + + <para> + This parameter is only used modify existing file shares definitions. To modify + printer shares, use the "Printers..." folder as seen when browsing the Samba host. + </para> + + <para> + See also <link linkend="ADDSHARECOMMAND"><parameter moreinfo="none">add share + command</parameter></link>, <link linkend="DELETESHARECOMMAND"><parameter moreinfo="none">delete + share command</parameter></link>. + </para> + + <para>Default: <emphasis>none</emphasis></para> + + <para>Example: <command moreinfo="none">change share command = /usr/local/bin/addshare</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/configfile.xml b/docs/docbook/smbdotconf/misc/configfile.xml new file mode 100644 index 0000000000..855b6460fe --- /dev/null +++ b/docs/docbook/smbdotconf/misc/configfile.xml @@ -0,0 +1,24 @@ +<samba:parameter name="config file" + context="G" + hide="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This allows you to override the config file + to use, instead of the default (usually <filename moreinfo="none">smb.conf</filename>). + There is a chicken and egg problem here as this option is set + in the config file!</para> + + <para>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.</para> + + <para>This option takes the usual substitutions, which can + be very useful.</para> + + <para>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).</para> + + <para>Example: <command moreinfo="none">config file = /usr/local/samba/lib/smb.conf.%m</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/copy.xml b/docs/docbook/smbdotconf/misc/copy.xml new file mode 100644 index 0000000000..c3152956b0 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/copy.xml @@ -0,0 +1,20 @@ +<samba:parameter name="copy" + context="S" + hide="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>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.</para> + + <para>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.</para> + + <para>Default: <emphasis>no value</emphasis></para> + + <para>Example: <command moreinfo="none">copy = otherservice</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/default.xml b/docs/docbook/smbdotconf/misc/default.xml new file mode 100644 index 0000000000..fce58dc40b --- /dev/null +++ b/docs/docbook/smbdotconf/misc/default.xml @@ -0,0 +1,9 @@ +<samba:parameter name="default" + context="G" + developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>A synonym for <link linkend="DEFAULTSERVICE"><parameter moreinfo="none"> + default service</parameter></link>.</para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/defaultservice.xml b/docs/docbook/smbdotconf/misc/defaultservice.xml new file mode 100644 index 0000000000..39e467b1d1 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/defaultservice.xml @@ -0,0 +1,38 @@ +<samba:parameter name="default service" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>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 <emphasis>NOT</emphasis> + given in the parameter value (see example below).</para> + + <para>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.</para> + + <para>Typically the default service would be a <link linkend="GUESTOK"> + <parameter moreinfo="none">guest ok</parameter></link>, <link linkend="READONLY"> + <parameter moreinfo="none">read-only</parameter></link> service.</para> + + <para>Also note that 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 <parameter moreinfo="none">%S</parameter> to make + a wildcard service.</para> + + <para>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.</para> + + <para>Example:</para> + +<para><programlisting format="linespecific"> +[global] + default service = pub + +[pub] + path = /%S +</programlisting></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/deletereadonly.xml b/docs/docbook/smbdotconf/misc/deletereadonly.xml new file mode 100644 index 0000000000..cfffceedcb --- /dev/null +++ b/docs/docbook/smbdotconf/misc/deletereadonly.xml @@ -0,0 +1,14 @@ +<samba:parameter name="delete readonly" + context="S" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This parameter allows readonly files to be deleted. + This is not normal DOS semantics, but is allowed by UNIX.</para> + + <para>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.</para> + + <para>Default: <command moreinfo="none">delete readonly = no</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/deletesharecommand.xml b/docs/docbook/smbdotconf/misc/deletesharecommand.xml new file mode 100644 index 0000000000..cf60b27752 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/deletesharecommand.xml @@ -0,0 +1,51 @@ +<samba:parameter name="delete share command" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>Samba 2.2.0 introduced the ability to dynamically + add and delete shares via the Windows NT 4.0 Server Manager. The + <parameter moreinfo="none">delete share command</parameter> is used to define an + external program or script which will remove an existing service + definition from <filename moreinfo="none">smb.conf</filename>. In order to successfully + execute the <parameter moreinfo="none">delete share command</parameter>, <command moreinfo="none">smbd</command> + requires that the administrator be connected using a root account (i.e. + uid == 0). + </para> + + <para> + When executed, <command moreinfo="none">smbd</command> will automatically invoke the + <parameter moreinfo="none">delete share command</parameter> with two parameters. + </para> + + <itemizedlist> + <listitem> + <para><parameter moreinfo="none">configFile</parameter> - the location + of the global <filename moreinfo="none">smb.conf</filename> file. + </para> + </listitem> + + <listitem> + <para><parameter moreinfo="none">shareName</parameter> - the name of + the existing service. + </para> + </listitem> + </itemizedlist> + + <para> + This parameter is only used to remove file shares. To delete printer shares, + see the <link linkend="DELETEPRINTERCOMMAND"><parameter moreinfo="none">deleteprinter + command</parameter></link>. + </para> + + <para> + See also <link linkend="ADDSHARECOMMAND"><parameter moreinfo="none">add share + command</parameter></link>, <link linkend="CHANGESHARECOMMAND"><parameter moreinfo="none">change + share command</parameter></link>. + </para> + + <para>Default: <emphasis>none</emphasis></para> + + <para>Example: <command moreinfo="none">delete share command = /usr/local/bin/delshare</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/dfreecommand.xml b/docs/docbook/smbdotconf/misc/dfreecommand.xml new file mode 100644 index 0000000000..1e839a5242 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/dfreecommand.xml @@ -0,0 +1,52 @@ +<samba:parameter name="dfree command" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + + <para>The <parameter moreinfo="none">dfree command</parameter> 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.</para> + + <para>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.</para> + + <para>The external program will be passed a single parameter indicating + a directory in the filesystem being queried. This will typically consist + of the string <filename moreinfo="none">./</filename>. 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.</para> + + <para>Note: Your script should <emphasis>NOT</emphasis> be setuid or + setgid and should be owned by (and writeable only by) root!</para> + + <para>Default: <emphasis>By default internal routines for + determining the disk capacity and remaining space will be used. + </emphasis></para> + + <para>Example: <command moreinfo="none">dfree command = /usr/local/samba/bin/dfree</command></para> + + <para>Where the script dfree (which must be made executable) could be:</para> + +<para><programlisting format="linespecific"> +#!/bin/sh +df $1 | tail -1 | awk '{print $2" "$4}' +</programlisting></para> + + <para>or perhaps (on Sys V based systems):</para> + +<para><programlisting format="linespecific"> +#!/bin/sh +/usr/bin/df -k $1 | tail -1 | awk '{print $3" "$5}' +</programlisting></para> + + <para>Note that you may have to replace the command names with full path names on some systems.</para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/dontdescend.xml b/docs/docbook/smbdotconf/misc/dontdescend.xml new file mode 100644 index 0000000000..d3e9fb2d5c --- /dev/null +++ b/docs/docbook/smbdotconf/misc/dontdescend.xml @@ -0,0 +1,21 @@ +<samba:parameter name="dont descend" + context="S" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>There are certain directories on some systems + (e.g., the <filename moreinfo="none">/proc</filename> 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.</para> + + <para>Note that Samba can be very fussy about the exact format + of the "dont descend" entries. For example you may need <filename moreinfo="none"> + ./proc</filename> instead of just <filename moreinfo="none">/proc</filename>. + Experimentation is the best policy :-) </para> + + <para>Default: <emphasis>none (i.e., all directories are OK + to descend)</emphasis></para> + + <para>Example: <command moreinfo="none">dont descend = /proc,/dev</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/dosfilemode.xml b/docs/docbook/smbdotconf/misc/dosfilemode.xml new file mode 100644 index 0000000000..2628dc45b0 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/dosfilemode.xml @@ -0,0 +1,18 @@ +<samba:parameter name="dos filemode" + context="S" + xmlns:samba="http://samba.org/common"> +<listitem> + <para> The default behavior in Samba is to provide + UNIX-like behavior where only the owner of a file/directory is + able to change the permissions on it. However, this behavior + is often confusing to DOS/Windows users. Enabling this parameter + allows a user who has write access to the file (by whatever + means) to modify the permissions on it. Note that a user + belonging to the group owning the file will not be allowed to + change permissions if the group is only granted read access. + Ownership of the file/directory is not changed, only the permissions + are modified.</para> + + <para>Default: <command moreinfo="none">dos filemode = no</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/dosfiletimeresolution.xml b/docs/docbook/smbdotconf/misc/dosfiletimeresolution.xml new file mode 100644 index 0000000000..600294d442 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/dosfiletimeresolution.xml @@ -0,0 +1,25 @@ +<samba:parameter name="dos filetime resolution" + context="S" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>Under the DOS and Windows FAT filesystem, the finest + granularity on time resolution is two seconds. Setting this parameter + for a share causes Samba to round the reported time down to the + nearest two second boundary when a query call that requires one second + resolution is made to <citerefentry><refentrytitle>smbd</refentrytitle> + <manvolnum>8</manvolnum></citerefentry>.</para> + + <para>This option is mainly used as a compatibility option for Visual + C++ when used against Samba shares. If oplocks are enabled on a + share, Visual C++ uses two different time reading calls to check if a + file has changed since it was last read. One of these calls uses a + one-second granularity, the other uses a two second granularity. As + the two second call rounds any odd second down, then if the file has a + timestamp of an odd number of seconds then the two timestamps will not + match and Visual C++ will keep reporting the file has changed. Setting + this option causes the two timestamps to match, and Visual C++ is + happy.</para> + + <para>Default: <command moreinfo="none">dos filetime resolution = no</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/dosfiletimes.xml b/docs/docbook/smbdotconf/misc/dosfiletimes.xml new file mode 100644 index 0000000000..a201d2d832 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/dosfiletimes.xml @@ -0,0 +1,17 @@ +<samba:parameter name="dos filetimes" + context="S" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>Under DOS and Windows, if a user can write to a + file they can change the timestamp on it. Under POSIX semantics, + only the owner of the file or root may change the timestamp. By + default, Samba runs with POSIX semantics and refuses to change the + timestamp on a file if the user <command moreinfo="none">smbd</command> is acting + on behalf of is not the file owner. Setting this option to <constant> + yes</constant> allows DOS semantics and <citerefentry><refentrytitle>smbd</refentrytitle> + <manvolnum>8</manvolnum></citerefentry> will change the file + timestamp as DOS requires.</para> + + <para>Default: <command moreinfo="none">dos filetimes = no</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/exec.xml b/docs/docbook/smbdotconf/misc/exec.xml new file mode 100644 index 0000000000..0d44d81bff --- /dev/null +++ b/docs/docbook/smbdotconf/misc/exec.xml @@ -0,0 +1,9 @@ +<samba:parameter name="exec" + context="S" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This is a synonym for <link linkend="PREEXEC"> + <parameter moreinfo="none">preexec</parameter></link>.</para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/fakedirectorycreatetimes.xml b/docs/docbook/smbdotconf/misc/fakedirectorycreatetimes.xml new file mode 100644 index 0000000000..f0a0d39230 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/fakedirectorycreatetimes.xml @@ -0,0 +1,33 @@ +<samba:parameter name="fake directory create times" + context="S" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>NTFS and Windows VFAT file systems keep a create + time for all files and directories. This is not the same as the + ctime - status change time - that Unix keeps, so Samba by default + reports the earliest of the various times Unix does keep. Setting + this parameter for a share causes Samba to always report midnight + 1-1-1980 as the create time for directories.</para> + + <para>This option is mainly used as a compatibility option for + Visual C++ when used against Samba shares. Visual C++ generated + makefiles have the object directory as a dependency for each object + file, and a make rule to create the directory. Also, when NMAKE + compares timestamps it uses the creation time when examining a + directory. Thus the object directory will be created if it does not + exist, but once it does exist it will always have an earlier + timestamp than the object files it contains.</para> + + <para>However, Unix time semantics mean that the create time + reported by Samba will be updated whenever a file is created or + or deleted in the directory. NMAKE finds all object files in + the object directory. The timestamp of the last one built is then + compared to the timestamp of the object directory. If the + directory's timestamp if newer, then all object files + will be rebuilt. Enabling this option + ensures directories always predate their contents and an NMAKE build + will proceed as expected.</para> + + <para>Default: <command moreinfo="none">fake directory create times = no</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/followsymlinks.xml b/docs/docbook/smbdotconf/misc/followsymlinks.xml new file mode 100644 index 0000000000..1b22eb9e64 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/followsymlinks.xml @@ -0,0 +1,21 @@ +<samba:parameter name="follow symlinks" + context="S" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This parameter allows the Samba administrator + to stop <citerefentry><refentrytitle>smbd</refentrytitle> + <manvolnum>8</manvolnum></citerefentry> from following symbolic + links in a particular share. Setting this + parameter to <constant>no</constant> prevents any file or directory + that is a symbolic link from being followed (the user will get an + error). This option is very useful to stop users from adding a + symbolic link to <filename moreinfo="none">/etc/passwd</filename> in their home + directory for instance. However it will slow filename lookups + down slightly.</para> + + <para>This option is enabled (i.e. <command moreinfo="none">smbd</command> will + follow symbolic links) by default.</para> + + <para>Default: <command moreinfo="none">follow symlinks = yes</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/fstype.xml b/docs/docbook/smbdotconf/misc/fstype.xml new file mode 100644 index 0000000000..4b9c67b202 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/fstype.xml @@ -0,0 +1,18 @@ +<samba:parameter name="fstype" + context="S" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This parameter allows the administrator to + configure the string that specifies the type of filesystem a share + is using that is reported by <citerefentry><refentrytitle>smbd</refentrytitle> + <manvolnum>8</manvolnum></citerefentry> when a client queries the filesystem type + for a share. The default type is <constant>NTFS</constant> for + compatibility with Windows NT but this can be changed to other + strings such as <constant>Samba</constant> or <constant>FAT + </constant> if required.</para> + + <para>Default: <command moreinfo="none">fstype = NTFS</command></para> + + <para>Example: <command moreinfo="none">fstype = Samba</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/hidelocalusers.xml b/docs/docbook/smbdotconf/misc/hidelocalusers.xml new file mode 100644 index 0000000000..18a1c817c1 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/hidelocalusers.xml @@ -0,0 +1,11 @@ +<samba:parameter name="hide local users" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This parameter toggles the hiding of local UNIX + users (root, wheel, floppy, etc) from remote clients.</para> + + <para>Default: <command moreinfo="none">hide local users = no</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/homedirmap.xml b/docs/docbook/smbdotconf/misc/homedirmap.xml new file mode 100644 index 0000000000..d4f09c7f50 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/homedirmap.xml @@ -0,0 +1,32 @@ +<samba:parameter name="homedir map" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>If<link linkend="NISHOMEDIR"><parameter moreinfo="none">nis homedir + </parameter></link> is <constant>yes</constant>, and <citerefentry><refentrytitle>smbd</refentrytitle> + <manvolnum>8</manvolnum></citerefentry> is also acting + as a Win95/98 <parameter moreinfo="none">logon server</parameter> then this parameter + specifies the NIS (or YP) map from which the server for the user's + home directory should be extracted. At present, only the Sun + auto.home map format is understood. The form of the map is:</para> + + <para><command moreinfo="none">username server:/some/file/system</command></para> + + <para>and the program will extract the servername from before + the first ':'. There should probably be a better parsing system + that copes with different map formats and also Amd (another + automounter) maps.</para> + + <note><para>A working NIS client is required on + the system for this option to work.</para></note> + + <para>See also <link linkend="NISHOMEDIR"><parameter moreinfo="none">nis homedir</parameter> + </link>, <link linkend="DOMAINLOGONS"><parameter moreinfo="none">domain logons</parameter> + </link>.</para> + + <para>Default: <command moreinfo="none">homedir map = <empty string></command></para> + + <para>Example: <command moreinfo="none">homedir map = amd.homedir</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/include.xml b/docs/docbook/smbdotconf/misc/include.xml new file mode 100644 index 0000000000..dcc32968e7 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/include.xml @@ -0,0 +1,18 @@ +<samba:parameter name="include" + context="G" + hide="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This allows you to include one config file + inside another. The file is included literally, as though typed + in place.</para> + + <para>It takes the standard substitutions, except <parameter moreinfo="none">%u + </parameter>, <parameter moreinfo="none">%P</parameter> and <parameter moreinfo="none">%S</parameter>. + </para> + + <para>Default: <emphasis>no file included</emphasis></para> + + <para>Example: <command moreinfo="none">include = /usr/local/samba/lib/admin_smb.conf</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/lockdir.xml b/docs/docbook/smbdotconf/misc/lockdir.xml new file mode 100644 index 0000000000..4e5f6bce85 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/lockdir.xml @@ -0,0 +1,9 @@ +<samba:parameter name="lock dir" + context="G" + hide="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>Synonym for <link linkend="LOCKDIRECTORY"><parameter moreinfo="none"> + lock directory</parameter></link>. +</para></listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/lockdirectory.xml b/docs/docbook/smbdotconf/misc/lockdirectory.xml new file mode 100644 index 0000000000..c877566b31 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/lockdirectory.xml @@ -0,0 +1,15 @@ +<samba:parameter name="lock directory" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This option specifies the directory where lock + files will be placed. The lock files are used to implement the + <link linkend="MAXCONNECTIONS"><parameter moreinfo="none">max connections</parameter> + </link> option.</para> + + <para>Default: <command moreinfo="none">lock directory = ${prefix}/var/locks</command></para> + + <para>Example: <command moreinfo="none">lock directory = /var/run/samba/locks</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/magicoutput.xml b/docs/docbook/smbdotconf/misc/magicoutput.xml new file mode 100644 index 0000000000..c321f12b99 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/magicoutput.xml @@ -0,0 +1,18 @@ +<samba:parameter name="magic output" + context="S" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This parameter specifies the name of a file + which will contain output created by a magic script (see the + <link linkend="MAGICSCRIPT"><parameter moreinfo="none">magic script</parameter></link> + parameter below).</para> + + <para>Warning: If two clients use the same <parameter moreinfo="none">magic script + </parameter> in the same directory the output file content + is undefined.</para> + + <para>Default: <command moreinfo="none">magic output = <magic script name>.out</command></para> + + <para>Example: <command moreinfo="none">magic output = myfile.txt</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/magicscript.xml b/docs/docbook/smbdotconf/misc/magicscript.xml new file mode 100644 index 0000000000..67f39d918e --- /dev/null +++ b/docs/docbook/smbdotconf/misc/magicscript.xml @@ -0,0 +1,31 @@ +<samba:parameter name="magic script" + context="S" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>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.</para> + + <para>Scripts executed in this way will be deleted upon + completion assuming that the user has the appropriate level + of privilege and the file permissions allow the deletion.</para> + + <para>If the script generates output, output will be sent to + the file specified by the <link linkend="MAGICOUTPUT"><parameter moreinfo="none"> + magic output</parameter></link> parameter (see above).</para> + + <para>Note that some shells are unable to interpret scripts + containing CR/LF instead of CR as + the end-of-line marker. Magic scripts must be executable + <emphasis>as is</emphasis> on the host, which for some hosts and + some shells will require filtering at the DOS end.</para> + + <para>Magic scripts are <emphasis>EXPERIMENTAL</emphasis> and + should <emphasis>NOT</emphasis> be relied upon.</para> + + <para>Default: <emphasis>None. Magic scripts disabled.</emphasis></para> + + <para>Example: <command moreinfo="none">magic script = user.csh</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/messagecommand.xml b/docs/docbook/smbdotconf/misc/messagecommand.xml new file mode 100644 index 0000000000..6df2a02bb7 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/messagecommand.xml @@ -0,0 +1,73 @@ +<samba:parameter name="message command" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This specifies what command to run when the + server receives a WinPopup style message.</para> + + <para>This would normally be a command that would + deliver the message somehow. How this is to be done is + up to your imagination.</para> + + <para>An example is:</para> + + <para><command moreinfo="none">message command = csh -c 'xedit %s;rm %s' &</command> + </para> + + <para>This delivers the message using <command moreinfo="none">xedit</command>, then + removes it afterwards. <emphasis>NOTE THAT IT IS VERY IMPORTANT + THAT THIS COMMAND RETURN IMMEDIATELY</emphasis>. 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 30 seconds, hopefully).</para> + + <para>All messages are delivered as the global guest user. + The command takes the standard substitutions, although <parameter moreinfo="none"> + %u</parameter> won't work (<parameter moreinfo="none">%U</parameter> may be better + in this case).</para> + + <para>Apart from the standard substitutions, some additional + ones apply. In particular:</para> + + <itemizedlist> + <listitem> + <para><parameter moreinfo="none">%s</parameter> = the filename containing + the message.</para> + </listitem> + + <listitem> + <para><parameter moreinfo="none">%t</parameter> = the destination that + the message was sent to (probably the server name).</para> + </listitem> + + <listitem> + <para><parameter moreinfo="none">%f</parameter> = who the message + is from.</para> + </listitem> + </itemizedlist> + + <para>You could make this command send mail, or whatever else + takes your fancy. Please let us know of any really interesting + ideas you have.</para> + + <para>Here's a way of sending the messages as mail to root:</para> + + <para><command moreinfo="none">message command = /bin/mail -s 'message from %f on + %m' root < %s; rm %s</command></para> + + <para>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. + </para> + + <para>If you want to silently delete it then try:</para> + + <para><command moreinfo="none">message command = rm %s</command></para> + + <para>Default: <emphasis>no message command</emphasis></para> + + <para>Example: <command moreinfo="none">message command = csh -c 'xedit %s; rm %s' &</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/nishomedir.xml b/docs/docbook/smbdotconf/misc/nishomedir.xml new file mode 100644 index 0000000000..734dcf8de5 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/nishomedir.xml @@ -0,0 +1,33 @@ +<samba:parameter name="nis homedir" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>Get the home share server from a NIS map. For + UNIX systems that use an automounter, the user's home directory + will often be mounted on a workstation on demand from a remote + server. </para> + + <para>When the Samba logon server is not the actual home directory + server, but is mounting the home directories via NFS then two + network hops would be required to access the users home directory + if the logon server told the client to use itself as the SMB server + for home directories (one over SMB and one over NFS). This can + be very slow.</para> + + <para>This option allows Samba to return the home share as + being on a different server to the logon server and as + long as a Samba daemon is running on the home directory server, + it will be mounted on the Samba client directly from the directory + server. When Samba is returning the home share to the client, it + will consult the NIS map specified in <link linkend="HOMEDIRMAP"> + <parameter moreinfo="none">homedir map</parameter></link> and return the server + listed there.</para> + + <para>Note that for this option to work there must be a working + NIS system and the Samba server with this option must also + be a logon server.</para> + + <para>Default: <command moreinfo="none">nis homedir = no</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/panicaction.xml b/docs/docbook/smbdotconf/misc/panicaction.xml new file mode 100644 index 0000000000..04b7aab8c8 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/panicaction.xml @@ -0,0 +1,16 @@ +<samba:parameter name="panic action" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This is a Samba developer option that allows a + system command to be called when either <citerefentry><refentrytitle>smbd</refentrytitle> + <manvolnum>8</manvolnum></citerefentry> or <citerefentry><refentrytitle>smbd</refentrytitle> + <manvolnum>8</manvolnum></citerefentry> crashes. This is usually used to + draw attention to the fact that a problem occurred.</para> + + <para>Default: <command moreinfo="none">panic action = <empty string></command></para> + + <para>Example: <command moreinfo="none">panic action = "/bin/sleep 90000"</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/piddirectory.xml b/docs/docbook/smbdotconf/misc/piddirectory.xml new file mode 100644 index 0000000000..b526a80221 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/piddirectory.xml @@ -0,0 +1,13 @@ +<samba:parameter name="pid directory" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This option specifies the directory where pid + files will be placed. </para> + + <para>Default: <command moreinfo="none">pid directory = ${prefix}/var/locks</command></para> + + <para>Example: <command moreinfo="none">pid directory = /var/run/</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/postexec.xml b/docs/docbook/smbdotconf/misc/postexec.xml new file mode 100644 index 0000000000..a6b65515ad --- /dev/null +++ b/docs/docbook/smbdotconf/misc/postexec.xml @@ -0,0 +1,22 @@ +<samba:parameter name="postexec" + context="S" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>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.</para> + + <para>An interesting example may be to unmount server + resources:</para> + + <para><command moreinfo="none">postexec = /etc/umount /cdrom</command></para> + + <para>See also <link linkend="PREEXEC"><parameter moreinfo="none">preexec</parameter></link>.</para> + + <para>Default: <emphasis>none (no command executed)</emphasis></para> + + <para>Example: <command moreinfo="none">postexec = echo \"%u disconnected from %S from %m (%I)\" >> /tmp/log</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/preexec.xml b/docs/docbook/smbdotconf/misc/preexec.xml new file mode 100644 index 0000000000..49c73d9491 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/preexec.xml @@ -0,0 +1,25 @@ +<samba:parameter name="preexec" + context="S" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This option specifies a command to be run whenever + the service is connected to. It takes the usual substitutions.</para> + + <para>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:</para> + + <para><command moreinfo="none">preexec = csh -c 'echo \"Welcome to %S!\" | /usr/local/samba/bin/smbclient -M %m -I %I' & </command></para> + + <para>Of course, this could get annoying after a while :-)</para> + + <para>See also <link linkend="PREEXECCLOSE"><parameter moreinfo="none">preexec close</parameter></link> and <link + linkend="POSTEXEC"><parameter moreinfo="none">postexec + </parameter></link>.</para> + + <para>Default: <emphasis>none (no command executed)</emphasis></para> + + <para>Example: <command moreinfo="none">preexec = echo \"%u connected to %S from %m (%I)\" >> /tmp/log</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/preexecclose.xml b/docs/docbook/smbdotconf/misc/preexecclose.xml new file mode 100644 index 0000000000..346d21dbd8 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/preexecclose.xml @@ -0,0 +1,12 @@ +<samba:parameter name="preexec close" + context="S" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This boolean option controls whether a non-zero + return code from <link linkend="PREEXEC"><parameter moreinfo="none">preexec + </parameter></link> should close the service being connected to.</para> + + <para>Default: <command moreinfo="none">preexec close = no</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/preload.xml b/docs/docbook/smbdotconf/misc/preload.xml new file mode 100644 index 0000000000..96b59e3a43 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/preload.xml @@ -0,0 +1,19 @@ +<samba:parameter name="preload" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>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.</para> + + <para>Note that if you just want all printers in your + printcap file loaded then the <link linkend="LOADPRINTERS"> + <parameter moreinfo="none">load printers</parameter></link> option is easier.</para> + + <para>Default: <emphasis>no preloaded services</emphasis></para> + + <para>Example: <command moreinfo="none">preload = fred lp colorlp</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/remoteannounce.xml b/docs/docbook/smbdotconf/misc/remoteannounce.xml new file mode 100644 index 0000000000..019cc306a7 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/remoteannounce.xml @@ -0,0 +1,35 @@ +<samba:parameter name="remote announce" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This option allows you to setup <citerefentry><refentrytitle>nmbd</refentrytitle> + <manvolnum>8</manvolnum></citerefentry>to periodically announce itself + to arbitrary IP addresses with an arbitrary workgroup name.</para> + + <para>This is useful if you want your Samba server to appear + in a remote workgroup for which the normal browse propagation + rules don't work. The remote workgroup can be anywhere that you + can send IP packets to.</para> + + <para>For example:</para> + + <para><command moreinfo="none">remote announce = 192.168.2.255/SERVERS + 192.168.4.255/STAFF</command></para> + + <para>the above line would cause <command moreinfo="none">nmbd</command> 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 <link linkend="WORKGROUP"><parameter moreinfo="none">workgroup</parameter></link> + parameter is used instead.</para> + + <para>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.</para> + + <para>See the documentation file <ulink url="improved-browsing.html">BROWSING</ulink> + in the <filename moreinfo="none">docs/</filename> directory.</para> + + <para>Default: <command moreinfo="none">remote announce = <empty string></command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/remotebrowsesync.xml b/docs/docbook/smbdotconf/misc/remotebrowsesync.xml new file mode 100644 index 0000000000..06069581e6 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/remotebrowsesync.xml @@ -0,0 +1,35 @@ +<samba:parameter name="remote browse sync" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This option allows you to setup <citerefentry><refentrytitle>nmbd</refentrytitle> + <manvolnum>8</manvolnum></citerefentry> to periodically request + synchronization of browse lists with the master browser of a Samba + server that is on a remote segment. This option will allow you to + gain browse lists for multiple workgroups across routed networks. This + is done in a manner that does not work with any non-Samba servers.</para> + + <para>This is useful if you want your Samba server and all local + clients to appear in a remote workgroup for which the normal browse + propagation rules don't work. The remote workgroup can be anywhere + that you can send IP packets to.</para> + + <para>For example:</para> + + <para><command moreinfo="none">remote browse sync = 192.168.2.255 192.168.4.255</command></para> + + <para>the above line would cause <command moreinfo="none">nmbd</command> to request + the master browser on the specified subnets or addresses to + synchronize their browse lists with the local server.</para> + + <para>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. If + a machine IP address is given Samba makes NO attempt to validate + that the remote machine is available, is listening, nor that it + is in fact the browse master on its segment.</para> + + <para>Default: <command moreinfo="none">remote browse sync = <empty string></command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/rootpostexec.xml b/docs/docbook/smbdotconf/misc/rootpostexec.xml new file mode 100644 index 0000000000..baed004327 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/rootpostexec.xml @@ -0,0 +1,16 @@ +<samba:parameter name="root postexec" + context="S" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This is the same as the <parameter moreinfo="none">postexec</parameter> + parameter except that the command is run as root. This + is useful for unmounting filesystems + (such as CDROMs) after a connection is closed.</para> + + <para>See also <link linkend="POSTEXEC"><parameter moreinfo="none"> + postexec</parameter></link>.</para> + + <para>Default: <command moreinfo="none">root postexec = <empty string></command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/rootpreexec.xml b/docs/docbook/smbdotconf/misc/rootpreexec.xml new file mode 100644 index 0000000000..4939d1ee48 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/rootpreexec.xml @@ -0,0 +1,17 @@ +<samba:parameter name="root preexec" + context="S" + advanced="1" wizard="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This is the same as the <parameter moreinfo="none">preexec</parameter> + parameter except that the command is run as root. This + is useful for mounting filesystems (such as CDROMs) when a + connection is opened.</para> + + <para>See also <link linkend="PREEXEC"><parameter moreinfo="none"> + preexec</parameter></link> and <link linkend="PREEXECCLOSE"> + <parameter moreinfo="none">preexec close</parameter></link>.</para> + + <para>Default: <command moreinfo="none">root preexec = <empty string></command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/rootpreexecclose.xml b/docs/docbook/smbdotconf/misc/rootpreexecclose.xml new file mode 100644 index 0000000000..b333cffe90 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/rootpreexecclose.xml @@ -0,0 +1,15 @@ +<samba:parameter name="root preexec close" + context="S" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This is the same as the <parameter moreinfo="none">preexec close + </parameter> parameter except that the command is run as root.</para> + + <para>See also <link linkend="PREEXEC"><parameter moreinfo="none"> + preexec</parameter></link> and <link linkend="PREEXECCLOSE"> + <parameter moreinfo="none">preexec close</parameter></link>.</para> + + <para>Default: <command moreinfo="none">root preexec close = no</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/setdirectory.xml b/docs/docbook/smbdotconf/misc/setdirectory.xml new file mode 100644 index 0000000000..b4ff72d4d0 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/setdirectory.xml @@ -0,0 +1,15 @@ +<samba:parameter name="set directory" + context="S" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>If <command moreinfo="none">set directory = no</command>, then + users of the service may not use the setdir command to change + directory.</para> + + <para>The <command moreinfo="none">setdir</command> command is only implemented + in the Digital Pathworks client. See the Pathworks documentation + for details.</para> + + <para>Default: <command moreinfo="none">set directory = no</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/socketaddress.xml b/docs/docbook/smbdotconf/misc/socketaddress.xml new file mode 100644 index 0000000000..4d2299acda --- /dev/null +++ b/docs/docbook/smbdotconf/misc/socketaddress.xml @@ -0,0 +1,16 @@ +<samba:parameter name="socket address" + context="G" + developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>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.</para> + + <para>By default Samba will accept connections on any + address.</para> + + <para>Example: <command moreinfo="none">socket address = 192.168.2.20</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/sourceenvironment.xml b/docs/docbook/smbdotconf/misc/sourceenvironment.xml new file mode 100644 index 0000000000..c6b4ce368f --- /dev/null +++ b/docs/docbook/smbdotconf/misc/sourceenvironment.xml @@ -0,0 +1,27 @@ +<samba:parameter name="source environment" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This parameter causes Samba to set environment + variables as per the content of the file named.</para> + + <para>If the value of this parameter starts with a "|" character + then Samba will treat that value as a pipe command to open and + will set the environment variables from the output of the pipe.</para> + + <para>The contents of the file or the output of the pipe should + be formatted as the output of the standard Unix <command moreinfo="none">env(1)</command> command. This is of the form:</para> + + <para>Example environment entry:</para> + + <para><command moreinfo="none">SAMBA_NETBIOS_NAME = myhostname</command></para> + + <para>Default: <emphasis>No default value</emphasis></para> + + <para>Examples: <command moreinfo="none">source environment = |/etc/smb.conf.sh</command></para> + + <para>Example: <command moreinfo="none">source environment = + /usr/local/smb_env_vars</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/timeoffset.xml b/docs/docbook/smbdotconf/misc/timeoffset.xml new file mode 100644 index 0000000000..4cd12b6d36 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/timeoffset.xml @@ -0,0 +1,15 @@ +<samba:parameter name="time offset" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>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.</para> + + <para>Default: <command moreinfo="none">time offset = 0</command></para> + + <para>Example: <command moreinfo="none">time offset = 60</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/utmp.xml b/docs/docbook/smbdotconf/misc/utmp.xml new file mode 100644 index 0000000000..3dfa7caa5d --- /dev/null +++ b/docs/docbook/smbdotconf/misc/utmp.xml @@ -0,0 +1,24 @@ +<samba:parameter name="utmp" + context="G" + developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This boolean parameter is only available if + Samba has been configured and compiled with the option <command moreinfo="none"> + --with-utmp</command>. If set to <constant>yes</constant> then Samba will attempt + to add utmp or utmpx records (depending on the UNIX system) whenever a + connection is made to a Samba server. Sites may use this to record the + user connecting to a Samba share.</para> + + <para>Due to the requirements of the utmp record, we + are required to create a unique identifier for the + incoming user. Enabling this option creates an n^2 + algorithm to find this number. This may impede + performance on large installations. </para> + + <para>See also the <link linkend="UTMPDIRECTORY"><parameter moreinfo="none"> + utmp directory</parameter></link> parameter.</para> + + <para>Default: <command moreinfo="none">utmp = no</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/utmpdirectory.xml b/docs/docbook/smbdotconf/misc/utmpdirectory.xml new file mode 100644 index 0000000000..3b50c3db29 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/utmpdirectory.xml @@ -0,0 +1,20 @@ +<samba:parameter name="utmp directory" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This parameter is only available if Samba has + been configured and compiled with the option <command moreinfo="none"> + --with-utmp</command>. It specifies a directory pathname that is + used to store the utmp or utmpx files (depending on the UNIX system) that + record user connections to a Samba server. See also the <link linkend="UTMP"> + <parameter moreinfo="none">utmp</parameter></link> parameter. By default this is + not set, meaning the system will use whatever utmp file the + native system is set to use (usually + <filename moreinfo="none">/var/run/utmp</filename> on Linux).</para> + + <para>Default: <emphasis>no utmp directory</emphasis></para> + + <para>Example: <command moreinfo="none">utmp directory = /var/run/utmp</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/volume.xml b/docs/docbook/smbdotconf/misc/volume.xml new file mode 100644 index 0000000000..0ab5edb522 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/volume.xml @@ -0,0 +1,11 @@ +<samba:parameter name="volume" + context="S" + xmlns:samba="http://samba.org/common"> + <listitem> + <para> 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.</para> + + <para>Default: <emphasis>the name of the share</emphasis></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/widelinks.xml b/docs/docbook/smbdotconf/misc/widelinks.xml new file mode 100644 index 0000000000..ead3569fd9 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/widelinks.xml @@ -0,0 +1,17 @@ +<samba:parameter name="wide links" + context="S" + xmlns:samba="http://samba.org/common"> + <listitem> + <para>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.</para> + + <para>Note that setting this parameter can have a negative + effect on your server performance due to the extra system calls + that Samba has to do in order to perform the link checks.</para> + + <para>Default: <command moreinfo="none">wide links = yes</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/misc/wtmpdirectory.xml b/docs/docbook/smbdotconf/misc/wtmpdirectory.xml new file mode 100644 index 0000000000..2448edfadb --- /dev/null +++ b/docs/docbook/smbdotconf/misc/wtmpdirectory.xml @@ -0,0 +1,24 @@ +<samba:parameter name="wtmp directory" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This parameter is only available if Samba has + been configured and compiled with the option <command moreinfo="none"> + --with-utmp</command>. It specifies a directory pathname that is + used to store the wtmp or wtmpx files (depending on the UNIX system) that + record user connections to a Samba server. The difference with + the utmp directory is the fact that user info is kept after a user + has logged out.</para> + + <para>See also the <link linkend="UTMP"> + <parameter moreinfo="none">utmp</parameter></link> parameter. By default this is + not set, meaning the system will use whatever utmp file the + native system is set to use (usually + <filename moreinfo="none">/var/run/wtmp</filename> on Linux).</para> + + <para>Default: <emphasis>no wtmp directory</emphasis></para> + + <para>Example: <command moreinfo="none">wtmp directory = /var/log/wtmp</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/printing/lpqcachetime.xml b/docs/docbook/smbdotconf/printing/lpqcachetime.xml new file mode 100644 index 0000000000..df48a5fd01 --- /dev/null +++ b/docs/docbook/smbdotconf/printing/lpqcachetime.xml @@ -0,0 +1,29 @@ +<samba:parameter name="lpq cache time" + context="G" + developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This controls how long lpq info will be cached + for to prevent the <command moreinfo="none">lpq</command> command being called too + often. A separate cache is kept for each variation of the <command moreinfo="none"> + lpq</command> command used by the system, so if you use different + <command moreinfo="none">lpq</command> commands for different users then they won't + share cache information.</para> + + <para>The cache files are stored in <filename moreinfo="none">/tmp/lpq.xxxx</filename> + where xxxx is a hash of the <command moreinfo="none">lpq</command> command in use.</para> + + <para>The default is 10 seconds, meaning that the cached results + of a previous identical <command moreinfo="none">lpq</command> command will be used + if the cached data is less than 10 seconds old. A large value may + be advisable if your <command moreinfo="none">lpq</command> command is very slow.</para> + + <para>A value of 0 will disable caching completely.</para> + + <para>See also the <link linkend="PRINTING"><parameter moreinfo="none">printing</parameter></link> parameter.</para> + + <para>Default: <command moreinfo="none">lpq cache time = 10</command></para> + + <para>Example: <command moreinfo="none">lpq cache time = 30</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/printing/printcapname.xml b/docs/docbook/smbdotconf/printing/printcapname.xml new file mode 100644 index 0000000000..e7aa9e938d --- /dev/null +++ b/docs/docbook/smbdotconf/printing/printcapname.xml @@ -0,0 +1,52 @@ +<samba:parameter name="printcap name" + context="S" + print="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This parameter may be used to override the + compiled-in default printcap name used by the server (usually <filename moreinfo="none"> + /etc/printcap</filename>). See the discussion of the <link + linkend="PRINTERSSECT">[printers]</link> section above for reasons + why you might want to do this.</para> + + <para>To use the CUPS printing interface set <command moreinfo="none">printcap name = cups + </command>. This should be supplemented by an addtional setting + <link linkend="PRINTING">printing = cups</link> in the [global] + section. <command moreinfo="none">printcap name = cups</command> will use the + "dummy" printcap created by CUPS, as specified in your CUPS + configuration file. + </para> + + <para>On System V systems that use <command moreinfo="none">lpstat</command> to + list available printers you can use <command moreinfo="none">printcap name = lpstat + </command> to automatically obtain lists of available printers. This + is the default for systems that define SYSV at configure time in + Samba (this includes most System V based systems). If <parameter moreinfo="none"> + printcap name</parameter> is set to <command moreinfo="none">lpstat</command> on + these systems then Samba will launch <command moreinfo="none">lpstat -v</command> and + attempt to parse the output to obtain a printer list.</para> + + <para>A minimal printcap file would look something like this:</para> + +<para><programlisting format="linespecific"> +print1|My Printer 1 +print2|My Printer 2 +print3|My Printer 3 +print4|My Printer 4 +print5|My Printer 5 +</programlisting></para> + + <para>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.</para> + + <note><para>Under AIX the default printcap + name is <filename moreinfo="none">/etc/qconfig</filename>. Samba will assume the + file is in AIX <filename moreinfo="none">qconfig</filename> format if the string + <filename moreinfo="none">qconfig</filename> appears in the printcap filename.</para></note> + + <para>Default: <command moreinfo="none">printcap name = /etc/printcap</command></para> + + <para>Example: <command moreinfo="none">printcap name = /etc/myprintcap</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/printing/useclientdriver.xml b/docs/docbook/smbdotconf/printing/useclientdriver.xml new file mode 100644 index 0000000000..67c8cbf8d0 --- /dev/null +++ b/docs/docbook/smbdotconf/printing/useclientdriver.xml @@ -0,0 +1,40 @@ +<samba:parameter name="use client driver" + context="S" + print="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This parameter applies only to Windows NT/2000 + clients. It has no affect on Windows 95/98/ME clients. When + serving a printer to Windows NT/2000 clients without first installing + a valid printer driver on the Samba host, the client will be required + to install a local printer driver. From this point on, the client + will treat the print as a local printer and not a network printer + connection. This is much the same behavior that will occur + when <command moreinfo="none">disable spoolss = yes</command>. + </para> + + <para>The differentiating factor is that under normal + circumstances, the NT/2000 client will attempt to open the network + printer using MS-RPC. The problem is that because the client + considers the printer to be local, it will attempt to issue the + OpenPrinterEx() call requesting access rights associated with the + logged on user. If the user possesses local administator rights but + not root privilegde on the Samba host (often the case), the + OpenPrinterEx() call will fail. The result is that the client will + now display an "Access Denied; Unable to connect" message + in the printer queue window (even though jobs may successfully be + printed). </para> + + <para>If this parameter is enabled for a printer, then any attempt + to open the printer with the PRINTER_ACCESS_ADMINISTER right is mapped + to PRINTER_ACCESS_USE instead. Thus allowing the OpenPrinterEx() + call to succeed. <emphasis>This parameter MUST not be able enabled + on a print share which has valid print driver installed on the Samba + server.</emphasis></para> + + <para>See also <link linkend="DISABLESPOOLSS"><parameter + moreinfo="none">disable spoolss</parameter></link></para> + + <para>Default: <command moreinfo="none">use client driver = no</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/security/createmask.xml b/docs/docbook/smbdotconf/security/createmask.xml new file mode 100644 index 0000000000..4a581d3a19 --- /dev/null +++ b/docs/docbook/smbdotconf/security/createmask.xml @@ -0,0 +1,45 @@ +<samba:parameter name="create mask" + context="S" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>A synonym for this parameter is + <link linkend="CREATEMODE"><parameter moreinfo="none">create mode</parameter> + </link>.</para> + + <para>When a file is created, the necessary permissions are + calculated according to the mapping from DOS modes to UNIX + permissions, and the resulting UNIX mode is then bit-wise 'AND'ed + with this parameter. This parameter may be thought of as a bit-wise + MASK for the UNIX modes of a file. Any bit <emphasis>not</emphasis> + set here will be removed from the modes set on a file when it is + created.</para> + + <para>The default value of this parameter removes the + 'group' and 'other' write and execute bits from the UNIX modes.</para> + + <para>Following this Samba will bit-wise 'OR' the UNIX mode created + from this parameter with the value of the <link linkend="FORCECREATEMODE"> + <parameter moreinfo="none">force create mode</parameter></link> + parameter which is set to 000 by default.</para> + + <para>This parameter does not affect directory modes. See the + parameter <link linkend="DIRECTORYMODE"><parameter moreinfo="none">directory mode + </parameter></link> for details.</para> + + <para>See also the <link linkend="FORCECREATEMODE"><parameter moreinfo="none">force + create mode</parameter></link> parameter for forcing particular mode + bits to be set on created files. See also the <link linkend="DIRECTORYMODE"> + <parameter moreinfo="none">directory mode</parameter></link> parameter for masking + mode bits on created directories. See also the <link linkend="INHERITPERMISSIONS"> + <parameter moreinfo="none">inherit permissions</parameter></link> parameter.</para> + + <para>Note that this parameter does not apply to permissions + set by Windows NT/2000 ACL editors. If the administrator wishes to enforce + a mask on access control lists also, they need to set the <link linkend="SECURITYMASK"> + <parameter moreinfo="none">security mask</parameter></link>.</para> + + <para>Default: <command moreinfo="none">create mask = 0744</command></para> + + <para>Example: <command moreinfo="none">create mask = 0775</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/security/minpasswordlength.xml b/docs/docbook/smbdotconf/security/minpasswordlength.xml new file mode 100644 index 0000000000..6f73d9b52f --- /dev/null +++ b/docs/docbook/smbdotconf/security/minpasswordlength.xml @@ -0,0 +1,17 @@ +<samba:parameter name="min password length" + context="G" + advanced="1" developer="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This option sets the minimum length in characters of a + plaintext password that <command moreinfo="none">smbd</command> will + accept when performing UNIX password changing.</para> + + <para>See also <link linkend="UNIXPASSWORDSYNC"><parameter moreinfo="none">unix + password sync</parameter></link>, <link linkend="PASSWDPROGRAM"> + <parameter moreinfo="none">passwd program</parameter></link> and <link linkend="PASSWDCHATDEBUG"> + <parameter moreinfo="none">passwd chat debug</parameter></link>.</para> + + <para>Default: <command moreinfo="none">min password length = 5</command></para> +</listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/security/preloadmodules.xml b/docs/docbook/smbdotconf/security/preloadmodules.xml new file mode 100644 index 0000000000..7b4e57cff1 --- /dev/null +++ b/docs/docbook/smbdotconf/security/preloadmodules.xml @@ -0,0 +1,18 @@ +<samba:parameter name="preload modules" + context="G" + basic="1" + xmlns:samba="http://samba.org/common"> +<listitem> + <para>This is a list of paths to modules that should + be loaded into smbd before a client connects. This improves + the speed of smbd when reacting to new connections somewhat. </para> + + <para>It is recommended to only use this option on heavy-performance + servers.</para> + + <para>Default: <command>preload modules = </command></para> + + <para>Example: <command>preload modules = /usr/lib/samba/passdb/mysql.so+++ </command></para> + + </listitem> +</samba:parameter> diff --git a/docs/docbook/smbdotconf/smb.conf.5.xml b/docs/docbook/smbdotconf/smb.conf.5.xml new file mode 100644 index 0000000000..2a5d190f69 --- /dev/null +++ b/docs/docbook/smbdotconf/smb.conf.5.xml @@ -0,0 +1,685 @@ +<?xml version="1.0" encoding="iso8859-1"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ + +<!ENTITY % globalentities SYSTEM './../global.ent'> %globalentities; +]> +<refentry id="smb.conf.5"> + +<refmeta> + <refentrytitle>smb.conf</refentrytitle> + <manvolnum>5</manvolnum> +</refmeta> + + +<refnamediv> + <refname>smb.conf</refname> + <refpurpose>The configuration file for the Samba suite</refpurpose> +</refnamediv> + +<refsect1> + <title>SYNOPSIS</title> + + <para>The <filename moreinfo="none">smb.conf</filename> file is a configuration + file for the Samba suite. <filename moreinfo="none">smb.conf</filename> contains + runtime configuration information for the Samba programs. The <filename moreinfo="none">smb.conf</filename> file + is designed to be configured and administered by the <citerefentry><refentrytitle>swat</refentrytitle> + <manvolnum>8</manvolnum></citerefentry> program. The complete + description of the file format and possible parameters held within + are here for reference purposes.</para> </refsect1> + +<refsect1 id="FILEFORMATSECT"> + <title>FILE FORMAT</title> + + <para>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</para> + + <para><replaceable>name</replaceable> = <replaceable>value + </replaceable></para> + + <para>The file is line-based - that is, each newline-terminated + line represents either a comment, a section name or a parameter.</para> + + <para>Section and parameter names are not case sensitive.</para> + + <para>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.</para> + + <para>Any line beginning with a semicolon (';') or a hash ('#') + character is ignored, as are lines containing only whitespace.</para> + + <para>Any line ending in a '\' is continued + on the next line in the customary UNIX fashion.</para> + + <para>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.</para> +</refsect1> + +<refsect1> + <title>SECTION DESCRIPTIONS</title> + + <para>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.</para> + + <para>There are three special sections, [global], + [homes] and [printers], which are + described under <emphasis>special sections</emphasis>. The + following notes apply to ordinary section descriptions.</para> + + <para>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.</para> + + <para>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).</para> + + <para>Sections may be designated <emphasis>guest</emphasis> services, + in which case no password is required to access them. A specified + UNIX <emphasis>guest account</emphasis> is used to define access + privileges in this case.</para> + + <para>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.</para> + + <para>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.</para> + + <para>The following sample section defines a file space share. + The user has write access to the path <filename moreinfo="none">/home/bar</filename>. + The share is accessed via the share name "foo":</para> + +<screen format="linespecific"> +<computeroutput moreinfo="none"> +[foo] + path = /home/bar + read only = no +</computeroutput> +</screen> + + <para>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 <emphasis>guest ok</emphasis> parameter means + access will be permitted as the default guest user (specified + elsewhere):</para> + +<screen format="linespecific"> +<computeroutput moreinfo="none"> +[aprinter] + path = /usr/spool/public + read only = yes + printable = yes + guest ok = yes +</computeroutput> +</screen> +</refsect1> + +<refsect1> + <title>SPECIAL SECTIONS</title> + + <refsect2> + <title>The [global] section</title> + + <para>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.</para> + </refsect2> + + <refsect2 id="HOMESECT"> + <title>The [homes] section</title> + + <para>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.</para> + + <para>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.</para> + + <para>Some modifications are then made to the newly + created share:</para> + + <itemizedlist> + <listitem><para>The share name is changed from homes to + the located username.</para></listitem> + + <listitem><para>If no path was given, the path is set to + the user's home directory.</para></listitem> + </itemizedlist> + + <para>If you decide to use a <emphasis>path =</emphasis> line + in your [homes] section then you may find it useful + to use the %S macro. For example :</para> + + <para><userinput moreinfo="none">path = /data/pchome/%S</userinput></para> + + <para>would be useful if you have different home directories + for your PCs than for UNIX access.</para> + + <para>This is a fast and simple way to give a large number + of clients access to their home directories with a minimum + of fuss.</para> + + <para>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.</para> + + <para>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:</para> + +<screen format="linespecific"> +<computeroutput moreinfo="none"> +[homes] + read only = no +</computeroutput> +</screen> + + <para>An important point is that if guest access is specified + in the [homes] section, all home directories will be + visible to all clients <emphasis>without a password</emphasis>. + In the very unlikely event that this is actually desirable, it + would be wise to also specify <emphasis>read only + access</emphasis>.</para> + + <para>Note that the <emphasis>browseable</emphasis> 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 <emphasis>browseable = no</emphasis> in + the [homes] section will hide the [homes] share but make + any auto home directories visible.</para> + </refsect2> + + <refsect2 id="PRINTERSSECT"> + <title>The [printers] section</title> + + <para>This section works like [homes], + but for printers.</para> + + <para>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.</para> + + <para>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.</para> + + <para>A few modifications are then made to the newly created + share:</para> + + <itemizedlist> + <listitem><para>The share name is set to the located printer + name</para></listitem> + + <listitem><para>If no printer name was given, the printer name + is set to the located printer name</para></listitem> + + <listitem><para>If the share does not permit guest access and + no username was given, the username is set to the located + printer name.</para></listitem> + </itemizedlist> + + <para>Note that the [printers] service MUST be + printable - if you specify otherwise, the server will refuse + to load the configuration file.</para> + + <para>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:</para> + +<screen format="linespecific"><computeroutput moreinfo="none"> +[printers] + path = /usr/spool/public + guest ok = yes + printable = yes +</computeroutput></screen> + + <para>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:</para> + +<screen format="linespecific"> +<computeroutput moreinfo="none"> +alias|alias|alias|alias... +</computeroutput> +</screen> + + <para>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.</para> + + <para>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 ('|').</para> + + <note><para>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.</para></note> + </refsect2> +</refsect1> + +<refsect1> + <title>PARAMETERS</title> + + <para>parameters define the specific attributes of sections.</para> + + <para>Some parameters are specific to the [global] section + (e.g., <emphasis>security</emphasis>). Some parameters are usable + in all sections (e.g., <emphasis>create mode</emphasis>). 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 <emphasis>G</emphasis> + in parentheses indicates that a parameter is specific to the + [global] section. The letter <emphasis>S</emphasis> + indicates that a parameter can be specified in a service specific + section. Note that all <emphasis>S</emphasis> parameters can also be specified in + the [global] section - in which case they will define + the default behavior for all services.</para> + + <para>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.</para> +</refsect1> + +<refsect1> + <title>VARIABLE SUBSTITUTIONS</title> + + <para>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.</para> + + <para>These substitutions are mostly noted in the descriptions below, + but there are some general substitutions which apply whenever they + might be relevant. These are:</para> + + <variablelist> + <varlistentry> + <term>%U</term> + <listitem><para>session user name (the user name that the client + wanted, not necessarily the same as the one they got).</para></listitem> + </varlistentry> + + <varlistentry> + <term>%G</term> + <listitem><para>primary group name of %U.</para></listitem> + </varlistentry> + + <varlistentry> + <term>%h</term> + <listitem><para>the Internet hostname that Samba is running + on.</para></listitem> + </varlistentry> + + <varlistentry> + <term>%m</term> + <listitem><para>the NetBIOS name of the client machine + (very useful).</para></listitem> + </varlistentry> + + <varlistentry> + <term>%L</term> + <listitem><para>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".</para> + + <para>Note that this parameter is not available when Samba listens + on port 445, as clients no longer send this information </para> + </listitem> + + </varlistentry> + + <varlistentry> + <term>%M</term> + <listitem><para>the Internet name of the client machine. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>%R</term> + <listitem><para>the selected protocol level after + protocol negotiation. It can be one of CORE, COREPLUS, + LANMAN1, LANMAN2 or NT1.</para></listitem> + </varlistentry> + + <varlistentry> + <term>%d</term> + <listitem><para>The process id of the current server + process.</para></listitem> + </varlistentry> + + <varlistentry> + <term>%a</term> + <listitem><para>the architecture of the remote + machine. Only some are recognized, and those may not be + 100% reliable. It currently recognizes Samba, WfWg, Win95, + WinNT and Win2k. Anything else will be known as + "UNKNOWN". If it gets it wrong then sending a level + 3 log to <ulink url="mailto:samba@samba.org">samba@samba.org + </ulink> should allow it to be fixed.</para></listitem> + </varlistentry> + + <varlistentry> + <term>%I</term> + <listitem><para>The IP address of the client machine.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>%T</term> + <listitem><para>the current date and time.</para></listitem> + </varlistentry> + + <varlistentry> + <term>%D</term> + <listitem><para>Name of the domain or workgroup of the current user.</para></listitem> + </varlistentry> + + <varlistentry> + <term>%$(<replaceable>envvar</replaceable>)</term> + <listitem><para>The value of the environment variable + <replaceable>envar</replaceable>.</para></listitem> + </varlistentry> + </variablelist> + + <para>The following substitutes apply only to some configuration options(only those + that are used when a connection has been established):</para> + + <variablelist> + <varlistentry> + <term>%S</term> + <listitem><para>the name of the current service, if any.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>%P</term> + <listitem><para>the root directory of the current service, + if any.</para></listitem> + </varlistentry> + + <varlistentry> + <term>%u</term> + <listitem><para>user name of the current service, if any.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>%g</term> + <listitem><para>primary group name of %u.</para></listitem> + </varlistentry> + + <varlistentry> + <term>%H</term> + <listitem><para>the home directory of the user given + by %u.</para></listitem> + </varlistentry> + + <varlistentry> + <term>%N</term> + <listitem><para>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 <emphasis>--with-automount</emphasis> + option then this value will be the same as %L.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>%p</term> + <listitem><para>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".</para></listitem> + </varlistentry> + </variablelist> + + <para>There are some quite creative things that can be done + with these substitutions and other smb.conf options.</para> +</refsect1> + +<refsect1 id="NAMEMANGLINGSECT"> + <title>NAME MANGLING</title> + + <para>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.</para> + + <para>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. </para> + + <para>All of these options can be set separately for each service + (or globally, of course). </para> + + <para>The options are: </para> + + <variablelist> + + <varlistentry> + <term>mangle case = yes/no</term> + <listitem><para> 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 <emphasis>no</emphasis>.</para></listitem> + </varlistentry> + + <varlistentry> + <term>case sensitive = yes/no</term> + <listitem><para>controls whether filenames are case sensitive. If + they aren't then Samba must do a filename search and match on passed + names. Default <emphasis>no</emphasis>.</para></listitem> + </varlistentry> + + <varlistentry> + <term>default case = upper/lower</term> + <listitem><para>controls what the default case is for new + filenames. Default <emphasis>lower</emphasis>.</para></listitem> + </varlistentry> + + <varlistentry> + <term>preserve case = yes/no</term> + <listitem><para>controls if new files are created with the + case that the client passes, or if they are forced to be the + "default" case. Default <emphasis>yes</emphasis>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>short preserve case = yes/no</term> + <listitem><para>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 lowercased. Default <emphasis>yes</emphasis>.</para></listitem> + </varlistentry> + </variablelist> + + <para>By default, Samba 3.0 has the same semantics as a Windows + NT server, in that it is case insensitive but case preserving.</para> + +</refsect1> + +<refsect1 id="VALIDATIONSECT"> + <title>NOTE ABOUT USERNAME/PASSWORD VALIDATION</title> + + <para>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, then the connection request is rejected. However, if one of the + steps succeeds, then the following steps are not checked.</para> + + <para>If the service is marked "guest only = yes" and the + server is running with share-level security ("security = share") + then steps 1 to 5 are skipped.</para> + + + <orderedlist continuation="restarts" inheritnum="ignore" numeration="arabic"> + <listitem><para>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%<replaceable>username</replaceable> method of passing + a username.</para></listitem> + + <listitem><para>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.</para></listitem> + + <listitem><para>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.</para></listitem> + + <listitem><para>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. </para></listitem> + + <listitem><para>If a "user = " field is given in the + <filename moreinfo="none">smb.conf</filename> 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.</para></listitem> + + <listitem><para>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.</para></listitem> + </orderedlist> + +</refsect1> + +<refsect1> + <title>COMPLETE LIST OF GLOBAL PARAMETERS</title> + + <para>Here is a list of all global parameters. See the section of + each parameter for details. Note that some are synonyms.</para> + + <xi:include href="parameters.global.xml" parse="xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> + +</refsect1> + +<refsect1> + <title>COMPLETE LIST OF SERVICE PARAMETERS</title> + + <para>Here is a list of all service parameters. See the section on + each parameter for details. Note that some are synonyms.</para> + + <xi:include href="parameters.service.xml" parse="xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> + +</refsect1> + +<refsect1> + <title>EXPLANATION OF EACH PARAMETER</title> + + <xi:include href="parameters.all.xml" parse="xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> + +</refsect1> + +<refsect1> + <title>WARNINGS</title> + + <para>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.</para> + + <para>On a similar note, many clients - especially DOS clients - + limit service names to eight characters. <citerefentry><refentrytitle>smbd</refentrytitle> + <manvolnum>8</manvolnum></citerefentry> 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.</para> + + <para>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.</para> +</refsect1> + +<refsect1> + <title>VERSION</title> + + <para>This man page is correct for version 3.0 of the Samba suite.</para> +</refsect1> + +<refsect1> + <title>SEE ALSO</title> + <para> + <citerefentry><refentrytitle>samba</refentrytitle> + <manvolnum>7</manvolnum></citerefentry>, <citerefentry><refentrytitle>smbpasswd</refentrytitle> + <manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>swat</refentrytitle> + <manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>smbd</refentrytitle> + <manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>nmbd</refentrytitle> + <manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>smbclient</refentrytitle> + <manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>nmblookup</refentrytitle> + <manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>testparm</refentrytitle> + <manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>testprns</refentrytitle> + <manvolnum>1</manvolnum></citerefentry>.</para> +</refsect1> + +<refsect1> + <title>AUTHOR</title> + + <para>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.</para> + + <para>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 <ulink url="ftp://ftp.icce.rug.nl/pub/unix/"> + ftp://ftp.icce.rug.nl/pub/unix/</ulink>) 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.</para> +</refsect1> + +</refentry> |