docs: Add documentation for server role

2 files changed, 75 insertions, 1 deletions

diff --git a/docs-xml/smbdotconf/security/security.xml b/docs-xml/smbdotconf/security/security.xml
index 55e147e8dc..74ea569b86 100644
--- a/docs-xml/smbdotconf/security/security.xml
+++ b/docs-xml/smbdotconf/security/security.xml
@@ -42,9 +42,14 @@
     <para>The different settings will now be explained.</para>
 
 
+    <para><anchor id="SECURITYEQUALSAUTO"/><emphasis>SECURITY = AUTO</emphasis></para>
+
+    <para>This is the default security setting in Samba, and causes Samba to consult
+    the <smbconfoption name="server role"/> parameter (if set) to determine the security mode.</para>
+
     <para><anchor id="SECURITYEQUALSUSER"/><emphasis>SECURITY = USER</emphasis></para>
 
-    <para>This is the default security setting in Samba. 
+    <para>If <smbconfoption name="server role"/> is not specified, this is the default security setting in Samba. 
     With user-level security a client must first &quot;log-on&quot; with a 
     valid username and password (which can be mapped using the <smbconfoption name="username map"/> 
     parameter). Encrypted passwords (see the <smbconfoption name="encrypted passwords"/> parameter) can also
diff --git a/docs-xml/smbdotconf/security/serverrole.xml b/docs-xml/smbdotconf/security/serverrole.xml
new file mode 100644
index 0000000000..5832887040
--- /dev/null
+++ b/docs-xml/smbdotconf/security/serverrole.xml
@@ -0,0 +1,69 @@
+<samba:parameter name="server role"
+                 context="G"
+				 type="enum"
+                 basic="1" advanced="1" wizard="1" developer="1"
+		 xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+    <para>This option determines the basic operating mode of a Samba
+    server and is one of the most important settings in the <filename
+    moreinfo="none"> smb.conf</filename> file.</para>
+
+    <para>The default is <command moreinfo="none">server role = auto</command>, as causes
+    Samba to operate according to the <smbconfoption name="security"/> setting, or if not
+    specified as a simple file server that is not connected to any domain.</para>
+
+    <para>The alternatives are
+    <command moreinfo="none">server role = standalone</command> or <command moreinfo="none">server role = member server
+    </command>, which support joining Samba to a Windows domain, along with <command moreinfo="none">server role = domain controller</command>, which run Samba as a Windows domain controller.</para>
+
+    <para>You should use <command moreinfo="none">server role = standalone</command> and 
+    <smbconfoption name="map to guest"/> if you 
+    want to mainly setup shares without a password (guest shares). This 
+    is commonly used for a shared printer server. </para>
+		
+    <para><anchor id="AUTO"/><emphasis>SERVER ROLE = AUTO</emphasis></para>
+
+    <para>This is the default server role in Samba, and causes Samba to consult
+    the <smbconfoption name="security"/> parameter (if set) to determine the server role, giving compatable behaviours to previous Samba versions.</para>
+
+    <para><anchor id="STANDALONE"/><emphasis>SERVER ROLE = STANDALONE</emphasis></para>
+
+    <para>If <smbconfoption name="security"/> is also not specified, this is the default security setting in Samba. 
+    In standalone operation, a client must first &quot;log-on&quot; with a 
+    valid username and password (which can be mapped using the <smbconfoption name="username map"/> 
+    parameter) stored on this machine. Encrypted passwords (see the <smbconfoption name="encrypted passwords"/> parameter) are by default
+    used in this security mode. Parameters such as <smbconfoption name="user"/> and <smbconfoption
+	name="guest only"/> 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><anchor id="MEMBER SERVER"/><emphasis>SERVER ROLE = MEMBER SERVER</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 Domain. It expects the <smbconfoption name="encrypted passwords"/>
+	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 or Samba Domain Controller, in exactly 
+    the same way that a Windows 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.  Winbind can provide this.</para>
+
+    <para>See also the section <link linkend="VALIDATIONSECT">
+    NOTE ABOUT USERNAME/PASSWORD VALIDATION</link>.</para>
+
+    <para><anchor id="DC"/><emphasis>SERVER ROLE = DOMAIN CONTROLLER</emphasis></para>
+
+    <para>This mode of operation runs Samba as a domain controller, providing domain logon services to Windows and Samba clients of the domain.  Clients must be joined to the domain to create a secure, trusted path across the network.</para>
+
+</description>
+
+<related>security</related>
+<related>realm</related>
+<related>encrypt passwords</related>
+
+<value type="default">AUTO</value>
+<value type="example">DOMAIN CONTROLLER</value>
+</samba:parameter>