Merge tag 'upstream/4.0.5+dfsg1' into samba_4.0_ivo

[abartlet/samba-debian.git] / docs-xml / smbdotconf / security / serverrole.xml

diff --git a/docs-xml/smbdotconf/security/serverrole.xml b/docs-xml/smbdotconf/security/serverrole.xml
new file mode 100644 (file)
index 0000000..005b6e9
--- /dev/null
+++ b/docs-xml/smbdotconf/security/serverrole.xml
@@ -0,0 +1,88 @@
+<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><anchor id="PDC"/><emphasis>SERVER ROLE = CLASSIC PRIMARY DOMAIN CONTROLLER</emphasis></para>
+
+    <para>This mode of operation runs a classic Samba primary domain
+    controller, providing domain logon services to Windows and Samba
+    clients of an NT4-like domain.  Clients must be joined to the domain to
+    create a secure, trusted path across the network.  There must be
+    only one PDC per NetBIOS scope (typcially a broadcast network or
+    clients served by a single WINS server).</para>
+
+    <para><anchor id="BDC"/><emphasis>SERVER ROLE = NETBIOS BACKUP DOMAIN CONTROLLER</emphasis></para>
+
+    <para>This mode of operation runs a classic Samba backup domain
+    controller, providing domain logon services to Windows and Samba
+    clients of an NT4-like domain.  As a BDC, this allows
+    multiple Samba servers to provide rudundent logon services to a
+    single NetBIOS scope.</para>
+
+    <para><anchor id="AD-DC"/><emphasis>SERVER ROLE = ACTIVE DIRECTORY DOMAIN CONTROLLER</emphasis></para>
+
+    <para>This mode of operation runs Samba as an active directory
+    domain controller, providing domain logon services to Windows and
+    Samba clients of the domain.  This role requires special
+    configuration, see the <ulink
+    url="http://wiki.samba.org/index.php/Samba4/HOWTO">Samba4
+    HOWTO</ulink></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>