docs/docbook/smbdotconf/security/security.xml

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