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.xml477
1 files changed, 247 insertions, 230 deletions
diff --git a/docs/docbook/smbdotconf/security/security.xml b/docs/docbook/smbdotconf/security/security.xml
index 8e97d8721f..68c5f2cdd2 100644
--- a/docs/docbook/smbdotconf/security/security.xml
+++ b/docs/docbook/smbdotconf/security/security.xml
@@ -1,237 +1,254 @@
-<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>
+<samba:parameter name="security"
+ context="G"
+ basic="1" advanced="1" wizard="1" developer="1"
+ xmlns:samba="http://samba.org/common">
+<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>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>The different settings will now be explained.</para>
- <para><anchor id="SECURITYEQUALSSHARE"/><emphasis>SECURITY = SHARE
- </emphasis></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>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>
+ <para>Default: <command moreinfo="none">security = USER</command></para>
+ <para>Example: <command moreinfo="none">security = DOMAIN</command></para>
- </listitem>
- </samba:parameter>
+</listitem>
+</samba:parameter>