Add all the source files from the old CVS tree,

add the 5 missing chapters from the HOWTO
and add jht's Samba by Example book.
(This used to be commit 9fb5bcb93e57c5162b3ee6f9c7d777dc0269d100)

1 files changed, 268 insertions, 0 deletions

diff --git a/docs/smbdotconf/security/security.xml b/docs/smbdotconf/security/security.xml
new file mode 100644
index 0000000000..b029c0fa67
--- /dev/null
+++ b/docs/smbdotconf/security/security.xml
@@ -0,0 +1,268 @@
+<samba:parameter name="security"
+                 context="G"
+				 type="enum"
+                 basic="1" advanced="1" wizard="1" developer="1"
+		 xmlns:samba="http://samba.org/common">
+<description>
+    <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>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 &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 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>
+</description>
+
+<related>realm</related>
+<related>encrypt passwords</related>
+
+<value type="default">USER</value>
+<value type="example">DOMAIN</value>
+</samba:parameter>