summaryrefslogtreecommitdiff
path: root/docs/docbook/smbdotconf/security/security.xml
diff options
context:
space:
mode:
Diffstat (limited to 'docs/docbook/smbdotconf/security/security.xml')
-rw-r--r--docs/docbook/smbdotconf/security/security.xml237
1 files changed, 237 insertions, 0 deletions
diff --git a/docs/docbook/smbdotconf/security/security.xml b/docs/docbook/smbdotconf/security/security.xml
new file mode 100644
index 0000000000..8e97d8721f
--- /dev/null
+++ b/docs/docbook/smbdotconf/security/security.xml
@@ -0,0 +1,237 @@
+<samba:parameter xmlns:samba="http://samba.org/common">
+ <term><anchor id="SECURITY"/>security (G)</term>
+ <listitem><para>This option affects how clients respond to
+ Samba and is one of the most important settings in the <filename moreinfo="none">
+ smb.conf</filename> file.</para>
+
+ <para>The option sets the &quot;security mode bit&quot; in replies to
+ protocol negotiations with <citerefentry><refentrytitle>smbd</refentrytitle>
+ <manvolnum>8</manvolnum></citerefentry> to turn share level security on or off. Clients decide
+ based on this bit whether (and how) to transfer user and password
+ information to the server.</para>
+
+
+ <para>The default is <command moreinfo="none">security = user</command>, as this is
+ the most common setting needed when talking to Windows 98 and
+ Windows NT.</para>
+
+ <para>The alternatives are <command moreinfo="none">security = share</command>,
+ <command moreinfo="none">security = server</command> or <command moreinfo="none">security = domain
+ </command>.</para>
+
+ <para>In versions of Samba prior to 2.0.0, the default was
+ <command moreinfo="none">security = share</command> mainly because that was
+ the only option at one stage.</para>
+
+ <para>There is a bug in WfWg that has relevance to this
+ setting. When in user or server level security a WfWg client
+ will totally ignore the password you type in the &quot;connect
+ drive&quot; dialog box. This makes it very difficult (if not impossible)
+ to connect to a Samba service as anyone except the user that
+ you are logged into WfWg as.</para>
+
+ <para>If your PCs use usernames that are the same as their
+ usernames on the UNIX machine then you will want to use
+ <command moreinfo="none">security = user</command>. If you mostly use usernames
+ that don't exist on the UNIX box then use <command moreinfo="none">security =
+ share</command>.</para>
+
+ <para>You should also use <command moreinfo="none">security = share</command> if you
+ want to mainly setup shares without a password (guest shares). This
+ is commonly used for a shared printer server. It is more difficult
+ to setup guest shares with <command moreinfo="none">security = user</command>, see
+ the <link linkend="MAPTOGUEST"><parameter moreinfo="none">map to guest</parameter>
+ </link>parameter for details.</para>
+
+ <para>It is possible to use <command moreinfo="none">smbd</command> in a <emphasis>
+ hybrid mode</emphasis> where it is offers both user and share
+ level security under different <link linkend="NETBIOSALIASES">
+ <parameter moreinfo="none">NetBIOS aliases</parameter></link>. </para>
+
+ <para>The different settings will now be explained.</para>
+
+
+ <para><anchor id="SECURITYEQUALSSHARE"/><emphasis>SECURITY = SHARE
+ </emphasis></para>
+
+ <para>When clients connect to a share level security server they
+ need not log onto the server with a valid username and password before
+ attempting to connect to a shared resource (although modern clients
+ such as Windows 95/98 and Windows NT will send a logon request with
+ a username but no password when talking to a <command moreinfo="none">security = share
+ </command> server). Instead, the clients send authentication information
+ (passwords) on a per-share basis, at the time they attempt to connect
+ to that share.</para>
+
+ <para>Note that <command moreinfo="none">smbd</command> <emphasis>ALWAYS</emphasis>
+ uses a valid UNIX user to act on behalf of the client, even in
+ <command moreinfo="none">security = share</command> level security.</para>
+
+ <para>As clients are not required to send a username to the server
+ in share level security, <command moreinfo="none">smbd</command> uses several
+ techniques to determine the correct UNIX user to use on behalf
+ of the client.</para>
+
+ <para>A list of possible UNIX usernames to match with the given
+ client password is constructed using the following methods :</para>
+
+ <itemizedlist>
+ <listitem><para>If the <link linkend="GUESTONLY"><parameter moreinfo="none">guest
+ only</parameter></link> parameter is set, then all the other
+ stages are missed and only the <link linkend="GUESTACCOUNT">
+ <parameter moreinfo="none">guest account</parameter></link> username is checked.
+ </para></listitem>
+
+ <listitem><para>Is a username is sent with the share connection
+ request, then this username (after mapping - see <link linkend="USERNAMEMAP"><parameter moreinfo="none">username map</parameter></link>),
+ is added as a potential username.</para></listitem>
+
+ <listitem><para>If the client did a previous <emphasis>logon
+ </emphasis> request (the SessionSetup SMB call) then the
+ username sent in this SMB will be added as a potential username.
+ </para></listitem>
+
+ <listitem><para>The name of the service the client requested is
+ added as a potential username.</para></listitem>
+
+ <listitem><para>The NetBIOS name of the client is added to
+ the list as a potential username.</para></listitem>
+
+ <listitem><para>Any users on the <link linkend="USER"><parameter moreinfo="none">
+ user</parameter></link> list are added as potential usernames.
+ </para></listitem>
+ </itemizedlist>
+
+ <para>If the <parameter moreinfo="none">guest only</parameter> parameter is
+ not set, then this list is then tried with the supplied password.
+ The first user for whom the password matches will be used as the
+ UNIX user.</para>
+
+ <para>If the <parameter moreinfo="none">guest only</parameter> parameter is
+ set, or no username can be determined then if the share is marked
+ as available to the <parameter moreinfo="none">guest account</parameter>, then this
+ guest user will be used, otherwise access is denied.</para>
+
+ <para>Note that it can be <emphasis>very</emphasis> confusing
+ in share-level security as to which UNIX username will eventually
+ be used in granting access.</para>
+
+ <para>See also the section <link linkend="VALIDATIONSECT">
+ NOTE ABOUT USERNAME/PASSWORD VALIDATION</link>.</para>
+
+ <para><anchor id="SECURITYEQUALSUSER"/><emphasis>SECURITY = USER
+ </emphasis></para>
+
+ <para>This is the default security setting in Samba 3.0.
+ With user-level security a client must first &quot;log-on&quot; with a
+ valid username and password (which can be mapped using the <link linkend="USERNAMEMAP"><parameter moreinfo="none">username map</parameter></link>
+ parameter). Encrypted passwords (see the <link linkend="ENCRYPTPASSWORDS">
+ <parameter moreinfo="none">encrypted passwords</parameter></link> parameter) can also
+ be used in this security mode. Parameters such as <link linkend="USER">
+ <parameter moreinfo="none">user</parameter></link> and <link linkend="GUESTONLY">
+ <parameter moreinfo="none">guest only</parameter></link> if set are then applied and
+ may change the UNIX user to use on this connection, but only after
+ the user has been successfully authenticated.</para>
+
+ <para><emphasis>Note</emphasis> that the name of the resource being
+ requested is <emphasis>not</emphasis> sent to the server until after
+ the server has successfully authenticated the client. This is why
+ guest shares don't work in user level security without allowing
+ the server to automatically map unknown users into the <link linkend="GUESTACCOUNT"><parameter moreinfo="none">guest account</parameter></link>.
+ See the <link linkend="MAPTOGUEST"><parameter moreinfo="none">map to guest</parameter>
+ </link> parameter for details on doing this.</para>
+
+ <para>See also the section <link linkend="VALIDATIONSECT">
+ NOTE ABOUT USERNAME/PASSWORD VALIDATION</link>.</para>
+
+ <para><anchor id="SECURITYEQUALSDOMAIN"/><emphasis>SECURITY = DOMAIN
+
+ </emphasis></para>
+
+ <para>This mode will only work correctly if <citerefentry><refentrytitle>net</refentrytitle>
+ <manvolnum>8</manvolnum></citerefentry> has been used to add this
+ machine into a Windows NT Domain. It expects the <link linkend="ENCRYPTPASSWORDS"><parameter moreinfo="none">encrypted passwords</parameter>
+ </link> parameter to be set to <constant>yes</constant>. In this
+ mode Samba will try to validate the username/password by passing
+ it to a Windows NT Primary or Backup Domain Controller, in exactly
+ the same way that a Windows NT Server would do.</para>
+
+ <para><emphasis>Note</emphasis> that a valid UNIX user must still
+ exist as well as the account on the Domain Controller to allow
+ Samba to have a valid UNIX account to map file access to.</para>
+
+ <para><emphasis>Note</emphasis> that from the client's point
+ of view <command moreinfo="none">security = domain</command> is the same as <command moreinfo="none">security = user
+ </command>. It only affects how the server deals with the authentication,
+ it does not in any way affect what the client sees.</para>
+
+ <para><emphasis>Note</emphasis> that the name of the resource being
+ requested is <emphasis>not</emphasis> sent to the server until after
+ the server has successfully authenticated the client. This is why
+ guest shares don't work in user level security without allowing
+ the server to automatically map unknown users into the <link linkend="GUESTACCOUNT"><parameter moreinfo="none">guest account</parameter></link>.
+ See the <link linkend="MAPTOGUEST"><parameter moreinfo="none">map to guest</parameter>
+ </link> parameter for details on doing this.</para>
+
+ <para>See also the section <link linkend="VALIDATIONSECT">
+ NOTE ABOUT USERNAME/PASSWORD VALIDATION</link>.</para>
+
+ <para>See also the <link linkend="PASSWORDSERVER"><parameter moreinfo="none">password
+ server</parameter></link> parameter and the <link linkend="ENCRYPTPASSWORDS"><parameter moreinfo="none">encrypted passwords</parameter>
+ </link> parameter.</para>
+
+ <para><anchor id="SECURITYEQUALSSERVER"/><emphasis>SECURITY = SERVER
+ </emphasis></para>
+
+ <para>In this mode Samba will try to validate the username/password
+ by passing it to another SMB server, such as an NT box. If this
+ fails it will revert to <command moreinfo="none">security =
+ user</command>. It expects the <link linkend="ENCRYPTPASSWORDS"><parameter moreinfo="none">encrypted passwords</parameter>
+ </link> parameter to be set to
+ <constant>yes</constant>, unless the remote server
+ does not support them. However note
+ that if encrypted passwords have been negotiated then Samba cannot
+ revert back to checking the UNIX password file, it must have a valid
+ <filename moreinfo="none">smbpasswd</filename> file to check users against. See the
+ documentation file in the <filename moreinfo="none">docs/</filename> directory
+ <filename moreinfo="none">ENCRYPTION.txt</filename> for details on how to set this
+ up.</para>
+
+ <para><emphasis>Note</emphasis> this mode of operation
+ has significant pitfalls, due to the fact that is
+ activly initiates a man-in-the-middle attack on the
+ remote SMB server. In particular, this mode of
+ operation can cause significant resource consuption on
+ the PDC, as it must maintain an active connection for
+ the duration of the user's session. Furthermore, if
+ this connection is lost, there is no way to
+ reestablish it, and futher authenticaions to the Samba
+ server may fail. (From a single client, till it
+ disconnects). </para>
+
+ <para><emphasis>Note</emphasis> that from the client's point of
+ view <command moreinfo="none">security = server</command> is the same as <command moreinfo="none">
+ security = user</command>. It only affects how the server deals
+ with the authentication, it does not in any way affect what the
+ client sees.</para>
+
+ <para><emphasis>Note</emphasis> that the name of the resource being
+ requested is <emphasis>not</emphasis> sent to the server until after
+ the server has successfully authenticated the client. This is why
+ guest shares don't work in user level security without allowing
+ the server to automatically map unknown users into the <link linkend="GUESTACCOUNT"><parameter moreinfo="none">guest account</parameter></link>.
+ See the <link linkend="MAPTOGUEST"><parameter moreinfo="none">map to guest</parameter>
+ </link> parameter for details on doing this.</para>
+
+ <para>See also the section <link linkend="VALIDATIONSECT">
+ NOTE ABOUT USERNAME/PASSWORD VALIDATION</link>.</para>
+
+ <para>See also the <link linkend="PASSWORDSERVER"><parameter moreinfo="none">password
+ server</parameter></link> parameter and the <link linkend="ENCRYPTPASSWORDS"><parameter moreinfo="none">encrypted passwords</parameter>
+ </link> parameter.</para>
+
+ <para>Default: <command moreinfo="none">security = USER</command></para>
+ <para>Example: <command moreinfo="none">security = DOMAIN</command></para>
+
+ </listitem>
+ </samba:parameter>