docs/docbook/smbdotconf/security/security.xml

   1 <samba:parameter xmlns:samba="http://samba.org/common">
   2                 <term><anchor id="SECURITY"/>security (G)</term>
   3                 <listitem><para>This option affects how clients respond to
   4                 Samba and is one of the most important settings in the <filename moreinfo="none">
   5                 smb.conf</filename> file.</para>
   6
   7                 <para>The option sets the &quot;security mode bit&quot; in replies to
   8                 protocol negotiations with <citerefentry><refentrytitle>smbd</refentrytitle>
   9                 <manvolnum>8</manvolnum></citerefentry> to turn share level security on or off. Clients decide
  10                 based on this bit whether (and how) to transfer user and password
  11                 information to the server.</para>
  12
  13
  14                 <para>The default is <command moreinfo="none">security = user</command>, as this is
  15                 the most common setting needed when talking to Windows 98 and
  16                 Windows NT.</para>
  17
  18                 <para>The alternatives are <command moreinfo="none">security = share</command>,
  19                 <command moreinfo="none">security = server</command> or <command moreinfo="none">security = domain
  20                 </command>.</para>
  21
  22                 <para>In versions of Samba prior to 2.0.0, the default was
  23                 <command moreinfo="none">security = share</command> mainly because that was
  24                 the only option at one stage.</para>
  25
  26                 <para>There is a bug in WfWg that has relevance to this
  27                 setting. When in user or server level security a WfWg client
  28                 will totally ignore the password you type in the &quot;connect
  29                 drive&quot; dialog box. This makes it very difficult (if not impossible)
  30                 to connect to a Samba service as anyone except the user that
  31                 you are logged into WfWg as.</para>
  32
  33                 <para>If your PCs use usernames that are the same as their
  34                 usernames on the UNIX machine then you will want to use
  35                 <command moreinfo="none">security = user</command>. If you mostly use usernames
  36                 that don't exist on the UNIX box then use <command moreinfo="none">security =
  37                 share</command>.</para>
  38
  39                 <para>You should also use <command moreinfo="none">security = share</command> if you
  40                 want to mainly setup shares without a password (guest shares). This
  41                 is commonly used for a shared printer server. It is more difficult
  42                 to setup guest shares with <command moreinfo="none">security = user</command>, see
  43                 the <link linkend="MAPTOGUEST"><parameter moreinfo="none">map to guest</parameter>
  44                 </link>parameter for details.</para>
  45
  46                 <para>It is possible to use <command moreinfo="none">smbd</command> in a <emphasis>
  47                 hybrid mode</emphasis> where it is offers both user and share
  48                 level security under different <link linkend="NETBIOSALIASES">
  49                 <parameter moreinfo="none">NetBIOS aliases</parameter></link>. </para>
  50
  51                 <para>The different settings will now be explained.</para>
  52
  53
  54                 <para><anchor id="SECURITYEQUALSSHARE"/><emphasis>SECURITY = SHARE
  55                 </emphasis></para>
  56
  57                 <para>When clients connect to a share level security server they
  58                 need not log onto the server with a valid username and password before
  59                 attempting to connect to a shared resource (although modern clients
  60                 such as Windows 95/98 and Windows NT will send a logon request with
  61                 a username but no password when talking to a <command moreinfo="none">security = share
  62                 </command> server). Instead, the clients send authentication information
  63                 (passwords) on a per-share basis, at the time they attempt to connect
  64                 to that share.</para>
  65
  66                 <para>Note that <command moreinfo="none">smbd</command> <emphasis>ALWAYS</emphasis>
  67                 uses a valid UNIX user to act on behalf of the client, even in
  68                 <command moreinfo="none">security = share</command> level security.</para>
  69
  70                 <para>As clients are not required to send a username to the server
  71                 in share level security, <command moreinfo="none">smbd</command> uses several
  72                 techniques to determine the correct UNIX user to use on behalf
  73                 of the client.</para>
  74
  75                 <para>A list of possible UNIX usernames to match with the given
  76                 client password is constructed using the following methods :</para>
  77
  78                 <itemizedlist>
  79                         <listitem><para>If the <link linkend="GUESTONLY"><parameter moreinfo="none">guest
  80                         only</parameter></link> parameter is set, then all the other
  81                         stages are missed and only the <link linkend="GUESTACCOUNT">
  82                         <parameter moreinfo="none">guest account</parameter></link> username is checked.
  83                         </para></listitem>
  84
  85                         <listitem><para>Is a username is sent with the share connection
  86                         request, then this username (after mapping - see <link linkend="USERNAMEMAP"><parameter moreinfo="none">username map</parameter></link>),
  87                         is added as a potential username.</para></listitem>
  88
  89                         <listitem><para>If the client did a previous <emphasis>logon
  90                         </emphasis> request (the SessionSetup SMB call) then the
  91                         username sent in this SMB will be added as a potential username.
  92                         </para></listitem>
  93
  94                         <listitem><para>The name of the service the client requested is
  95                         added as a potential username.</para></listitem>
  96
  97                         <listitem><para>The NetBIOS name of the client is added to
  98                         the list as a potential username.</para></listitem>
  99
 100                         <listitem><para>Any users on the <link linkend="USER"><parameter moreinfo="none">
 101                         user</parameter></link> list are added as potential usernames.
 102                         </para></listitem>
 103                 </itemizedlist>
 104
 105                 <para>If the <parameter moreinfo="none">guest only</parameter> parameter is
 106                 not set, then this list is then tried with the supplied password.
 107                 The first user for whom the password matches will be used as the
 108                 UNIX user.</para>
 109
 110                 <para>If the <parameter moreinfo="none">guest only</parameter> parameter is
 111                 set, or no username can be determined then if the share is marked
 112                 as available to the <parameter moreinfo="none">guest account</parameter>, then this
 113                 guest user will be used, otherwise access is denied.</para>
 114
 115                 <para>Note that it can be <emphasis>very</emphasis> confusing
 116                 in share-level security as to which UNIX username will eventually
 117                 be used in granting access.</para>
 118
 119                 <para>See also the section <link linkend="VALIDATIONSECT">
 120                 NOTE ABOUT USERNAME/PASSWORD VALIDATION</link>.</para>
 121
 122                 <para><anchor id="SECURITYEQUALSUSER"/><emphasis>SECURITY = USER
 123                 </emphasis></para>
 124
 125                 <para>This is the default security setting in Samba 3.0.
 126                 With user-level security a client must first &quot;log-on&quot; with a
 127                 valid username and password (which can be mapped using the <link linkend="USERNAMEMAP"><parameter moreinfo="none">username map</parameter></link>
 128                 parameter). Encrypted passwords (see the <link linkend="ENCRYPTPASSWORDS">
 129                 <parameter moreinfo="none">encrypted passwords</parameter></link> parameter) can also
 130                 be used in this security mode. Parameters such as <link linkend="USER">
 131                 <parameter moreinfo="none">user</parameter></link> and <link linkend="GUESTONLY">
 132                 <parameter moreinfo="none">guest only</parameter></link> if set are then applied and
 133                 may change the UNIX user to use on this connection, but only after
 134                 the user has been successfully authenticated.</para>
 135
 136                 <para><emphasis>Note</emphasis> that the name of the resource being
 137                 requested is <emphasis>not</emphasis> sent to the server until after
 138                 the server has successfully authenticated the client. This is why
 139                 guest shares don't work in user level security without allowing
 140                 the server to automatically map unknown users into the <link linkend="GUESTACCOUNT"><parameter moreinfo="none">guest account</parameter></link>.
 141                 See the <link linkend="MAPTOGUEST"><parameter moreinfo="none">map to guest</parameter>
 142                 </link> parameter for details on doing this.</para>
 143
 144                 <para>See also the section <link linkend="VALIDATIONSECT">
 145                 NOTE ABOUT USERNAME/PASSWORD VALIDATION</link>.</para>
 146
 147                 <para><anchor id="SECURITYEQUALSDOMAIN"/><emphasis>SECURITY = DOMAIN
 148
 149                 </emphasis></para>
 150
 151                 <para>This mode will only work correctly if <citerefentry><refentrytitle>net</refentrytitle>
 152                 <manvolnum>8</manvolnum></citerefentry> has been used to add this
 153                 machine into a Windows NT Domain. It expects the <link linkend="ENCRYPTPASSWORDS"><parameter moreinfo="none">encrypted passwords</parameter>
 154                 </link> parameter to be set to <constant>yes</constant>. In this
 155                 mode Samba will try to validate the username/password by passing
 156                 it to a Windows NT Primary or Backup Domain Controller, in exactly
 157                 the same way that a Windows NT Server would do.</para>
 158
 159                 <para><emphasis>Note</emphasis> that a valid UNIX user must still
 160                 exist as well as the account on the Domain Controller to allow
 161                 Samba to have a valid UNIX account to map file access to.</para>
 162
 163                 <para><emphasis>Note</emphasis> that from the client's point
 164                 of view <command moreinfo="none">security = domain</command> is the same as <command moreinfo="none">security = user
 165                 </command>. It only affects how the server deals with the authentication,
 166                 it does not in any way affect what the client sees.</para>
 167
 168                 <para><emphasis>Note</emphasis> that the name of the resource being
 169                 requested is <emphasis>not</emphasis> sent to the server until after
 170                 the server has successfully authenticated the client. This is why
 171                 guest shares don't work in user level security without allowing
 172                 the server to automatically map unknown users into the <link linkend="GUESTACCOUNT"><parameter moreinfo="none">guest account</parameter></link>.
 173                 See the <link linkend="MAPTOGUEST"><parameter moreinfo="none">map to guest</parameter>
 174                 </link> parameter for details on doing this.</para>
 175
 176                 <para>See also the section <link linkend="VALIDATIONSECT">
 177                 NOTE ABOUT USERNAME/PASSWORD VALIDATION</link>.</para>
 178
 179                 <para>See also the <link linkend="PASSWORDSERVER"><parameter moreinfo="none">password
 180                 server</parameter></link> parameter and the <link linkend="ENCRYPTPASSWORDS"><parameter moreinfo="none">encrypted passwords</parameter>
 181                 </link> parameter.</para>
 182
 183                 <para><anchor id="SECURITYEQUALSSERVER"/><emphasis>SECURITY = SERVER
 184                 </emphasis></para>
 185
 186                 <para>In this mode Samba will try to validate the username/password
 187                 by passing it to another SMB server, such as an NT box. If this
 188                 fails it will revert to <command moreinfo="none">security =
 189                 user</command>. It expects the <link linkend="ENCRYPTPASSWORDS"><parameter moreinfo="none">encrypted passwords</parameter>
 190                 </link> parameter to be set to
 191                 <constant>yes</constant>, unless the remote server
 192                 does not support them.  However note
 193                 that if encrypted passwords have been negotiated then Samba cannot
 194                 revert back to checking the UNIX password file, it must have a valid
 195                 <filename moreinfo="none">smbpasswd</filename> file to check users against. See the
 196                 documentation file in the <filename moreinfo="none">docs/</filename> directory
 197                 <filename moreinfo="none">ENCRYPTION.txt</filename> for details on how to set this
 198                 up.</para>
 199
 200                 <para><emphasis>Note</emphasis> this mode of operation
 201                 has significant pitfalls, due to the fact that is
 202                 activly initiates a man-in-the-middle attack on the
 203                 remote SMB server.  In particular, this mode of
 204                 operation can cause significant resource consuption on
 205                 the PDC, as it must maintain an active connection for
 206                 the duration of the user's session.  Furthermore, if
 207                 this connection is lost, there is no way to
 208                 reestablish it, and futher authenticaions to the Samba
 209                 server may fail.  (From a single client, till it
 210                 disconnects). </para>
 211
 212                 <para><emphasis>Note</emphasis> that from the client's point of
 213                 view <command moreinfo="none">security = server</command> is the same as <command moreinfo="none">
 214                 security = user</command>.  It only affects how the server deals
 215                 with the authentication, it does not in any way affect what the
 216                 client sees.</para>
 217
 218                 <para><emphasis>Note</emphasis> that the name of the resource being
 219                 requested is <emphasis>not</emphasis> sent to the server until after
 220                 the server has successfully authenticated the client. This is why
 221                 guest shares don't work in user level security without allowing
 222                 the server to automatically map unknown users into the <link linkend="GUESTACCOUNT"><parameter moreinfo="none">guest account</parameter></link>.
 223                 See the <link linkend="MAPTOGUEST"><parameter moreinfo="none">map to guest</parameter>
 224                 </link> parameter for details on doing this.</para>
 225
 226                 <para>See also the section <link linkend="VALIDATIONSECT">
 227                 NOTE ABOUT USERNAME/PASSWORD VALIDATION</link>.</para>
 228
 229                 <para>See also the <link linkend="PASSWORDSERVER"><parameter moreinfo="none">password
 230                 server</parameter></link> parameter and the <link linkend="ENCRYPTPASSWORDS"><parameter moreinfo="none">encrypted passwords</parameter>
 231                 </link> parameter.</para>
 232
 233                 <para>Default: <command moreinfo="none">security = USER</command></para>
 234                 <para>Example: <command moreinfo="none">security = DOMAIN</command></para>
 235
 236                 </listitem>
 237                 </samba:parameter>