diff options
Diffstat (limited to 'docs/docbook/smbdotconf/security/security.xml')
| -rw-r--r-- | docs/docbook/smbdotconf/security/security.xml | 237 |
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 "security mode bit" 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 "connect + drive" 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 "log-on" 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> |