<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 "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 chapter about the User Database in the Samba HOWTO Collection for details on how to set this up.</para>
<note><para>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></note>
<note><para>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></note>
<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="SECURITYEQUALSADS"/><emphasis>SECURITY = ADS</emphasis></para>
<para>In this mode, Samba will act as a domain member in an ADS realm. To operate
in this mode, the machine running Samba will need to have Kerberos installed
and configured and Samba will need to be joined to the ADS realm using the
net utility. </para>
<para>Note that this mode does NOT make Samba operate as a Active Directory Domain
Controller. </para>
<para>Read the chapter about Domain Membership in the HOWTO for details.</para>
<para>See also the <link linkend="ADSSERVER"><parameter moreinfo="none">ads server
</parameter></link> parameter, the <link linkend="REALM"><parameter moreinfo="none">realm
</parameter></link> paramter 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>