Adding upstream version 2:4.17.12+dfsg.upstream/2%4.17.12+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 924 insertions, 0 deletions

diff --git a/docs-xml/manpages/smb.conf.5.xml b/docs-xml/manpages/smb.conf.5.xml
new file mode 100644
index 0000000..4b33c0f
--- /dev/null
+++ b/docs-xml/manpages/smb.conf.5.xml
@@ -0,0 +1,924 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
+<refentry id="smb.conf.5" xmlns:xi="http://www.w3.org/2003/XInclude"
+	                 xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+
+<refmeta>
+	<refentrytitle>smb.conf</refentrytitle>
+	<manvolnum>5</manvolnum>
+	<refmiscinfo class="source">Samba</refmiscinfo>
+	<refmiscinfo class="manual">File Formats and Conventions</refmiscinfo>
+	<refmiscinfo class="version">&doc.version;</refmiscinfo>
+</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
+	complete description of the file format and possible parameters held within are here for reference purposes.
+	</para>
+</refsect1>
+
+<refsect1>
+	<title>HOW CONFIGURATION CHANGES ARE APPLIED</title>
+
+	<para>
+	The Samba suite includes a number of different programs. Some of them operate in a client mode, others are
+	server daemons that provide various services to its clients. The <filename moreinfo="none">smb.conf
+        </filename> file is processed in the following way:
+        </para>
+
+	<itemizedlist>
+		<listitem><para>
+		The Samba suite's client applications read their configuration only once. Any changes made after start aren't
+		reflected in the context of already running client code.
+		</para></listitem>
+
+		<listitem><para>
+		The Samba suite's server daemons reload their configuration when requested. However, already active connections
+		do not change their configuration. More detailed information can be found in
+		<citerefentry><refentrytitle>smbd</refentrytitle><manvolnum>8</manvolnum></citerefentry> and <citerefentry>
+		<refentrytitle>winbindd</refentrytitle><manvolnum>8</manvolnum></citerefentry> manual pages.
+                </para></listitem>
+	</itemizedlist>
+
+	<para>
+	To request Samba server daemons to refresh their configuration, please use
+	<citerefentry><refentrytitle>smbcontrol</refentrytitle><manvolnum>1</manvolnum></citerefentry> utility.
+        </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:
+<programlisting>
+<replaceable>name</replaceable> = <replaceable>value </replaceable>
+</programlisting>
+	</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 (<quote>;</quote>) or a hash (<quote>#</quote>)
+	character is ignored, as are lines containing only whitespace.
+	</para>
+
+	<para>
+	Any line ending in a <quote><literal>\</literal></quote> 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, 1/0 or true/false. Case is not significant in boolean values, but is preserved
+	in string values. Some items such as create masks 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 <quote>share</quote>). 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 <literal>user =</literal> option in the share definition. For modern clients
+	such as Windows 95/98/ME/NT/2000, this should not be necessary.
+	</para>
+
+	<para>
+	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 <literal>foo</literal>:
+<programlisting>
+	<smbconfsection name="[foo]"/>
+	<smbconfoption name="path">/home/bar</smbconfoption>
+	<smbconfoption name="read only">no</smbconfoption>
+</programlisting>
+	</para>
+
+	<para>
+	The following sample section defines a printable share.  The share is read-only, but printable. That is,
+	the only write access permitted is via calls to open, write to and close a spool file. The <emphasis>guest
+	ok</emphasis> parameter means access will be permitted as the default guest user (specified elsewhere):
+<programlisting>
+	<smbconfsection name="[aprinter]"/>
+	<smbconfoption name="path">/var/tmp</smbconfoption>
+	<smbconfoption name="read only">yes</smbconfoption>
+	<smbconfoption name="printable">yes</smbconfoption>
+	<smbconfoption name="guest ok">yes</smbconfoption>
+</programlisting>
+	</para>
+
+</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 that 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 username and looked up in the local
+		password file. If the name exists and the correct password has been given, a share is created by cloning the
+		[homes] section.
+		</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, it may be useful
+		to use the %S macro. For example:
+<programlisting>
+<userinput moreinfo="none">path = /data/pchome/%S</userinput>
+</programlisting>
+		is 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 <quote>homes</quote>, 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:
+<programlisting>
+<smbconfsection name="[homes]"/>
+<smbconfoption name="read only">no</smbconfoption>
+</programlisting>
+		</para>
+
+		<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 is wise to also specify <emphasis>read only access</emphasis>.
+		</para>
+
+		<para>
+		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>
+		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 is that of a world-writeable spool directory with the sticky bit set on
+		it. A typical [printers] entry looks like this:
+<programlisting>
+<smbconfsection name="[printers]"/>
+<smbconfoption name="path">/var/tmp</smbconfoption>
+<smbconfoption name="guest ok">yes</smbconfoption>
+<smbconfoption name="printable">yes</smbconfoption>
+</programlisting>
+		</para>
+
+		<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:
+<programlisting>
+alias|alias|alias|alias...
+</programlisting>
+		</para>
+
+		<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 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 (<literal>|</literal>).
+		</para>
+
+		<note><para>
+		On SYSV systems which use lpstat to determine what printers are defined on the system you may be able to use
+		<literal>printcap name = lpstat</literal> to automatically obtain a list of printers. See the
+		<literal>printcap name</literal> option for more details.
+		</para></note>
+	</refsect2>
+</refsect1>
+
+<refsect1>
+	<title>USERSHARES</title>
+
+	<para>Starting with Samba version 3.0.23 the capability for non-root users to add, modify, and delete
+	their own share definitions has been added. This capability is called <emphasis>usershares</emphasis> and
+	is controlled by a set of parameters in the [global] section of the smb.conf.
+	The relevant parameters are :
+	</para>
+
+	<variablelist>
+		<varlistentry>
+		<term>usershare allow guests</term>
+		<listitem><para>Controls if usershares can permit guest access.</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>usershare max shares</term>
+		<listitem><para>Maximum number of user defined shares allowed.</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>usershare owner only</term>
+		<listitem><para>If set only directories owned by the sharing user can be shared.</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>usershare path</term>
+		<listitem><para>Points to the directory containing the user defined share definitions.
+		The filesystem permissions on this directory control who can create user defined shares.</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>usershare prefix allow list</term>
+		<listitem><para>Comma-separated list of absolute pathnames restricting what directories
+		can be shared. Only directories below the pathnames in this list are permitted.</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>usershare prefix deny list</term>
+		<listitem><para>Comma-separated list of absolute pathnames restricting what directories
+		can be shared. Directories below the pathnames in this list are prohibited.</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>usershare template share</term>
+		<listitem><para>Names a pre-existing share used as a template for creating new usershares.
+		All other share parameters not specified in the user defined share definition
+		are copied from this named share.</para></listitem>
+		</varlistentry>
+	</variablelist>
+
+	<para>To allow members of the UNIX group <literal>foo</literal> to create user defined
+	shares, create the directory to contain the share definitions as follows:
+	</para>
+	<para>Become root:</para>
+<programlisting>
+mkdir /usr/local/samba/lib/usershares
+chgrp foo /usr/local/samba/lib/usershares
+chmod 1770 /usr/local/samba/lib/usershares
+</programlisting>
+<para>Then add the parameters
+
+<programlisting>
+	<smbconfoption name="usershare path">/usr/local/samba/lib/usershares</smbconfoption>
+	<smbconfoption name="usershare max shares">10</smbconfoption> # (or the desired number of shares)
+</programlisting>
+
+	to the global
+	section of your <filename>smb.conf</filename>. Members of the group foo may then manipulate the user defined shares
+	using the following commands.</para>
+
+	<variablelist>
+		<varlistentry>
+		<term>net usershare add sharename path [comment] [acl] [guest_ok=[y|n]]</term>
+		<listitem><para>To create or modify (overwrite) a user defined share.</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>net usershare delete sharename</term>
+		<listitem><para>To delete a user defined share.</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>net usershare list wildcard-sharename</term>
+		<listitem><para>To list user defined shares.</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>net usershare info wildcard-sharename</term>
+		<listitem><para>To print information about user defined shares.</para></listitem>
+		</varlistentry>
+	</variablelist>
+</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 mask</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. 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
+	<quote>path = /tmp/%u</quote> is interpreted as <quote>path = /tmp/john</quote> 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 username (the username 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>
+
+			<para>This parameter is not available when Samba listens on port 445, as clients no longer
+			send this information. If you use this macro in an include statement on a domain that has
+			a Samba domain controller be sure to set in the [global] section <parameter>smb ports =
+			139</parameter>. This will cause Samba to not listen on port 445 and will permit include
+			functionality to function as it did with Samba 2.x.
+			</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 <quote>dual personality</quote>.
+		</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, NT1,
+			SMB2_02, SMB2_10, SMB3_00, SMB3_02, SMB3_11
+			or SMB2_FF.</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.  It currently recognizes Samba (<constant>Samba</constant>),
+		    the Linux CIFS file system (<constant>CIFSFS</constant>), OS/2, (<constant>OS2</constant>),
+		    Mac OS X (<constant>OSX</constant>), Windows for Workgroups (<constant>WfWg</constant>), Windows 9x/ME
+		    (<constant>Win95</constant>), Windows NT (<constant>WinNT</constant>),
+		    Windows 2000 (<constant>Win2K</constant>),
+		    Windows XP (<constant>WinXP</constant>),
+		    Windows XP 64-bit(<constant>WinXP64</constant>),
+		    Windows 2003 including
+		    2003R2 (<constant>Win2K3</constant>), and Windows
+		    Vista (<constant>Vista</constant>).  Anything else will be known as
+		    <constant>UNKNOWN</constant>.</para>
+		</listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>%I</term>
+		<listitem><para>the IP address of the client machine.</para>
+		<para>Before 4.0.0 it could contain IPv4 mapped IPv6 addresses,
+			now it only contains IPv4 or IPv6 addresses.</para>
+		</listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>%J</term>
+		<listitem><para>the IP address of the client machine,
+			colons/dots replaced by underscores.</para>
+		</listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>%i</term>
+		<listitem><para>the local IP address to which a client connected.</para>
+		<para>Before 4.0.0 it could contain IPv4 mapped IPv6 addresses,
+			now it only contains IPv4 or IPv6 addresses.</para>
+		</listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>%j</term>
+		<listitem><para>the local IP address to which a client connected,
+			colons/dots replaced by underscores.</para>
+		</listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>%T</term>
+		<listitem><para>the current date and time.</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>%t</term>
+		<listitem><para>the current date and time in a minimal format without colons (YYYYYmmdd_HHMMSS).</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>%D</term>
+		<listitem><para>name of the domain or workgroup of the current user.</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>%w</term>
+		<listitem><para>the winbind separator.</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>username 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>This value is the same as %L.</para></listitem>
+		</varlistentry>
+	</variablelist>
+
+	<para>
+	There are some quite creative things that can be done with these substitutions and other
+	<filename moreinfo="none">smb.conf</filename> options.
+	</para>
+</refsect1>
+
+<refsect1 id="NAMEMANGLINGSECT">
+	<title>NAME MANGLING</title>
+
+	<para>
+	Samba supports <literal>name mangling</literal> 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>
+	These options can be set separately for each service.
+	</para>
+
+	<para>
+	The options are:
+	</para>
+
+	<variablelist>
+
+	<varlistentry>
+		<term>case sensitive = yes/no/auto</term>
+		<listitem><para>
+		controls whether filenames are case sensitive. If they aren't, Samba must do a filename search and match on
+		passed names. The default setting of auto allows clients that support case sensitive filenames (Linux CIFSVFS
+		and smbclient 3.0.5 and above currently) to tell the Samba server on a per-packet basis that they wish to
+		access the file system in a case-sensitive manner (to support UNIX case sensitive semantics). No Windows or
+		DOS system supports case-sensitive filename so setting this option to auto is that same as setting it to no
+		for them. Default <emphasis>auto</emphasis>.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>default case = upper/lower</term>
+		<listitem><para>
+		controls what the default case is for new filenames (ie. files that don't currently exist in the filesystem).
+		Default <emphasis>lower</emphasis>.  IMPORTANT NOTE: As part of the optimizations for directories containing
+		large numbers of files, the following special case applies. If the options
+		<smbconfoption 	name="case sensitive">yes</smbconfoption>, <smbconfoption name="preserve case">No</smbconfoption>, and
+		<smbconfoption name="short preserve case">No</smbconfoption> are set, then the case of <emphasis>all</emphasis>
+		incoming client filenames, not just new filenames, will be modified. See additional notes below.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>preserve case = yes/no</term>
+		<listitem><para>
+		controls whether new files (ie. files that don't currently exist in the filesystem) are created with the case
+		that the client passes, or if they are forced to be the <literal>default</literal> case. Default
+		<emphasis>yes</emphasis>.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>short preserve case = yes/no</term>
+		<listitem><para>
+		controls if new files (ie. files that don't currently exist in the filesystem) 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
+		<literal>default</literal> case. This option can be used with <literal>preserve case = yes</literal> 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. As a special case for directories with large numbers of files, if the case
+	options are set as follows, "case sensitive = yes", "case preserve = no", "short preserve case = no"
+	then the "default case" option will be applied and will modify all filenames sent from the client
+	when accessing this share.
+	</para>
+
+</refsect1>
+
+<refsect1>
+	<title>REGISTRY-BASED CONFIGURATION</title>
+
+	<para>
+		Starting with Samba version 3.2.0, the capability to
+		store Samba configuration in the registry is available.
+		The configuration is stored in the registry key
+		 <emphasis><literal>HKLM\Software\Samba\smbconf</literal></emphasis>.
+		There are two levels of registry configuration:
+	</para>
+
+	<orderedlist continuation="restarts" inheritnum="ignore" numeration="arabic">
+		<listitem><para>Share definitions stored in registry are used.
+		This is triggered by setting the global
+		parameter <parameter>registry shares</parameter>
+		to <quote>yes</quote> in <emphasis>smb.conf</emphasis>.
+		</para>
+
+		<para>The registry shares are loaded not at startup but
+		on demand at runtime by <emphasis>smbd</emphasis>.
+		Shares defined in <emphasis>smb.conf</emphasis> take
+		priority over shares of the same name defined in
+		registry.</para></listitem>
+
+		<listitem>
+		<para>Global <emphasis>smb.conf</emphasis>
+		options stored in registry are used. This can be activated
+		in two different ways:</para>
+
+		<para>Firstly, a registry only configuration is triggered
+		by setting
+		<smbconfoption name="config backend">registry</smbconfoption>
+		in the [global] section of <emphasis>smb.conf</emphasis>.
+		This resets everything that has been read from config files
+		to this point and reads the content of the global configuration
+		section from the registry.
+		This is the recommended method of using registry based
+		configuration.</para>
+
+		<para>Secondly, a mixed configuration can be activated
+		by a special new meaning of the parameter
+		<smbconfoption name="include">registry</smbconfoption>
+		in the [global] section of <emphasis>smb.conf</emphasis>.
+		This reads the global options from registry with the same
+		priorities as for an include of a text file.
+		This may be especially useful in cases where an initial
+		configuration is needed to access the registry.</para>
+
+		<para>Activation of global registry options automatically
+		activates registry shares. So in the registry only case,
+		shares are loaded on demand only.</para>
+		</listitem>
+	</orderedlist>
+
+	<para>
+		Note: To make registry-based configurations foolproof
+		at least to a certain extent, the use
+		of <parameter>lock directory</parameter> and
+		 <parameter>config backend</parameter>
+		inside the registry configuration has been disabled:
+		Especially by changing the
+		 <parameter>lock directory</parameter> inside the registry
+		configuration, one would create a broken setup where the daemons
+		do not see the configuration they loaded once it is active.
+	</para>
+
+	<para>
+		The registry configuration can be accessed with
+		tools like <emphasis>regedit</emphasis> or <emphasis>net (rpc)
+		registry</emphasis> in the key
+		 <emphasis><literal>HKLM\Software\Samba\smbconf</literal></emphasis>.
+
+		More conveniently, the <emphasis>conf</emphasis> subcommand of the
+		 <citerefentry><refentrytitle>net</refentrytitle>
+		<manvolnum>8</manvolnum></citerefentry> utility
+		offers a dedicated interface to read and write the
+		registry based configuration locally, i.e. directly
+		accessing the database file, circumventing the
+		server.
+	</para>
+
+</refsect1>
+
+<refsect1 ID="IDMAPCONSIDERATIONS">
+	<title>IDENTITY MAPPING CONSIDERATIONS</title>
+
+	<para>
+	In the SMB protocol, users, groups, and machines are represented by their security identifiers (SIDs).
+	On POSIX system Samba processes need to run under corresponding POSIX user identities and
+	with supplemental POSIX groups to allow access to the files owned by those users and groups.
+	The process of mapping SIDs to POSIX users and groups is called <emphasis>IDENTITY MAPPING</emphasis>
+	or, in short, <emphasis>ID MAPPING</emphasis>.
+	</para>
+
+	<para>
+	Samba supports multiple ways to map SIDs to POSIX users and groups. The configuration is driven by
+	the <smbconfoption name="idmap config DOMAIN : OPTION"/> option which allows one to specify identity
+	mapping (idmap) options for each domain	separately.
+	</para>
+
+	<para>
+	Identity mapping modules implement different strategies for mapping of SIDs to POSIX user and group
+	identities. They are applicable to different use cases and scenarios. It is advised to read the documentation
+	of the individual identity mapping modules before choosing a specific scenario to use. Each identity
+	management module is documented in a separate manual page. The standard idmap backends are
+	tdb (<citerefentry><refentrytitle>idmap_tdb</refentrytitle><manvolnum>8</manvolnum></citerefentry>),
+	tdb2 (<citerefentry><refentrytitle>idmap_tdb2</refentrytitle><manvolnum>8</manvolnum></citerefentry>),
+	ldap (<citerefentry><refentrytitle>idmap_ldap</refentrytitle><manvolnum>8</manvolnum></citerefentry>),
+	rid (<citerefentry><refentrytitle>idmap_rid</refentrytitle><manvolnum>8</manvolnum></citerefentry>),
+	hash (<citerefentry><refentrytitle>idmap_hash</refentrytitle><manvolnum>8</manvolnum></citerefentry>),
+	autorid (<citerefentry><refentrytitle>idmap_autorid</refentrytitle><manvolnum>8</manvolnum></citerefentry>),
+	ad (<citerefentry><refentrytitle>idmap_ad</refentrytitle> <manvolnum>8</manvolnum></citerefentry>),
+	nss (<citerefentry><refentrytitle>idmap_nss</refentrytitle> <manvolnum>8</manvolnum></citerefentry>), and
+	rfc2307 (<citerefentry><refentrytitle>idmap_rfc2307</refentrytitle> <manvolnum>8</manvolnum></citerefentry>).
+	</para>
+
+	<para>
+	Overall, ID mapping configuration should be decided carefully. Changes to the already deployed ID mapping
+	configuration may create the risk of losing access to the data or disclosing the data to the wrong parties.
+	</para>
+
+	<para>
+	This example shows how to configure two domains with <citerefentry><refentrytitle>idmap_rid</refentrytitle>
+	<manvolnum>8</manvolnum> </citerefentry>, the principal domain and a trusted domain,
+	leaving the default id mapping scheme at tdb.
+	</para>
+
+	<programlisting>
+	[global]
+	security = domain
+	workgroup = MAIN
+
+	idmap config * : backend        = tdb
+	idmap config * : range          = 1000000-1999999
+
+	idmap config MAIN : backend     = rid
+	idmap config MAIN : range       = 5000000-5999999
+
+	idmap config TRUSTED : backend  = rid
+	idmap config TRUSTED : range    = 6000000-6999999
+	</programlisting>
+</refsect1>
+
+<refsect1>
+	<title>EXPLANATION OF EACH PARAMETER</title>
+
+	<samba:parameterlist>
+		<!-- The URI below is resolved to local generated version of parameters.all.xml //-->
+		<!-- WAF build places it in bin/default/docs-xml/smbdotconf/parameters.all.xml //-->
+		<!-- and we redirect there via use of XML_CATALOG_FILES, see docs-xml/build/catalog.xml.in //-->
+		<xi:include href="http://www.samba.org/samba/smbdotconf/parameters.all.xml" parse="xml"/>
+	</samba:parameterlist>
+
+</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 <literal>[homes]</literal> and <literal>[printers]</literal> 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 part of version &doc.version; 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>smbd</refentrytitle>
+	<manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>nmbd</refentrytitle>
+	<manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>winbindd</refentrytitle>
+	<manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>samba</refentrytitle>
+	<manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>samba-tool</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>.</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>
+</refsect1>
+
+</refentry>