diff options
Diffstat (limited to 'docs-xml/manpages/smb.conf.5.xml')
| -rw-r--r-- | docs-xml/manpages/smb.conf.5.xml | 924 |
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> |