Merge lp:~ahasenack/serverguide/samba-ldap-fixes into lp:serverguide/trunk

[Andreas Hasenack]

Update the samba-ldap.html guide to current Ubuntu Xenial.

Update the samba-ldap.html guide to current Ubuntu Xenial.

Many changes here:
- clarify the shown commands assume ldap and samba are on the same server. In that way we can use the -Y EXTERNAL SASL mechanism which we use all over the place in the server guide already
- the samba schema is already shipped as an ldif file in the samba package, so we don't have to go through all the hops of converting the schema into ldif and then importing it
- call attention to netbios name and workgroup config options before running smbldap-config, because if these parameters are changed afterwards the configuration will be inconsistent and odd errors like "invalid SID" will be shown when trying to authenticate users
- quickly explain some of the smbldap-config questions
- use a better smbldap-populate command that will avoid overlapping uids/gids with local users. Without it, the moment you create your first user with smbldap-useradd, for example, he will have uid=1000 which is the same uid of the first local non-root user in any ubuntu system.
- only restart smbd and nmbd after having set the ldap password with smbpasswd -W, or else there will be authentication errors in smbd's log
- change smbpasswd to use -W (upper case) instead of -w (lowercase) so we don't have to supply the password in the command line. This parameter probably wasn't available when this section of the guide was first written.
- call out the need to install libnss-ldap, and show how to. Without this, user authentication against this samba server won't work.
- added test commands for libnss-ldap, to make sure it's working
- add "-m" to the smbldap-useradd command so that the user's home directory is created
- switched the list of smbldap example commands from a numbered list to a bullet list, since it's not a sequence of commands that have to be run one after the other
- removed the add machine command from smb.conf since that is only used for domain controllers, which we are not configuring here

[Doug Smythies (dsmythies)]

O.K. great, thanks.

See line 207 below, I'm going to change that tab character to a space.

review: Approve

=== modified file 'serverguide/C/network-auth.xml'
--- serverguide/C/network-auth.xml	2017-05-12 00:46:00 +0000
+++ serverguide/C/network-auth.xml	2017-05-22 19:41:33 +0000
@@ -2196,6 +2196,10 @@
 	that can accept authentication requests. See <xref linkend="openldap-server"/> for details on fulfilling this requirement. Once this
 	section is completed, you will need to decide what specifically you want Samba to do for you and then configure it accordingly.
 	</para>
+	<para>
+	This guide will assume that the LDAP and Samba services are running on the same server and therefore use SASL EXTERNAL authentication
+	whenever changing something under <emphasis>cn=config</emphasis>. If that is not your scenario, you will have to run those ldap
+	commands on the LDAP server.</para>
 
   <sect2 id="samba-ldap-installation" status="review">
   <title>Software Installation</title>
@@ -2261,116 +2265,20 @@
 
 	<step>
 		<para>
-		The schema is found in the now-installed <application>samba</application> package. It needs to be unzipped and copied to 
-		the <filename>/etc/ldap/schema</filename> directory:
+		The schema is found in the now-installed <application>samba</application> package and is already in the ldif format.
+		We can import it with one simple command:
 		</para>
         
 <screen>
-<command>sudo cp /usr/share/doc/samba/examples/LDAP/samba.schema.gz /etc/ldap/schema</command>
-<command>sudo gzip -d /etc/ldap/schema/samba.schema.gz</command>
+<command>zcat /usr/share/doc/samba/examples/LDAP/samba.ldif.gz | sudo ldapadd -Q -Y EXTERNAL -H ldapi:///</command>
 </screen>
 
 	</step>
 
 	<step>
-		<para>                  
-		Have the configuration file <filename>schema_convert.conf</filename> that contains the following lines:
-		</para>
-
-<programlisting>
-include /etc/ldap/schema/core.schema
-include /etc/ldap/schema/collective.schema
-include /etc/ldap/schema/corba.schema
-include /etc/ldap/schema/cosine.schema
-include /etc/ldap/schema/duaconf.schema
-include /etc/ldap/schema/dyngroup.schema
-include /etc/ldap/schema/inetorgperson.schema
-include /etc/ldap/schema/java.schema
-include /etc/ldap/schema/misc.schema
-include /etc/ldap/schema/nis.schema
-include /etc/ldap/schema/openldap.schema
-include /etc/ldap/schema/ppolicy.schema
-include /etc/ldap/schema/ldapns.schema
-include /etc/ldap/schema/pmi.schema
-include /etc/ldap/schema/samba.schema
-</programlisting>
-
-	</step>
-
-       	<step>
-                <para>
-                Have the directory <filename>ldif_output</filename> hold output.
-                </para> 
-       	</step>
-
-       	<step>
-		<para>
-		Determine the index of the schema:
-		</para>
-
-<screen>
-<command>slapcat -f schema_convert.conf -F ldif_output -n 0 | grep samba,cn=schema</command>
-<computeroutput>
-dn: cn={14}samba,cn=schema,cn=config
-</computeroutput>
-</screen>
-
-	</step>
-
-       	<step>
-                <para>
-                Convert the schema to LDIF format:
-                </para>
-
-<screen>
-<command>slapcat -f schema_convert.conf -F ldif_output -n0 -H \
-ldap:///cn={14}samba,cn=schema,cn=config -l cn=samba.ldif</command>
-</screen>
-
-       	</step>
-
-       	<step>
-                <para>
-                Edit the generated <filename>cn=samba.ldif</filename> file by removing index information to arrive at:
-                </para> 
-
-<programlisting>
-dn: cn=samba,cn=schema,cn=config
-...
-cn: samba
-</programlisting>
-		
-                <para>
-                Remove the bottom lines:
-                </para> 
-
-<programlisting>
-structuralObjectClass: olcSchemaConfig
-entryUUID: b53b75ca-083f-102d-9fff-2f64fd123c95
-creatorsName: cn=config
-createTimestamp: 20080827045234Z
-entryCSN: 20080827045234.341425Z#000000#000#000000
-modifiersName: cn=config
-modifyTimestamp: 20080827045234Z
-</programlisting>
-
-		<para>
-		Your attribute values will vary.
-		</para>
-	</step>
-
-       	<step>
-                <para>
-                Add the new schema:
-                </para>
-
-<screen>
-<command>sudo ldapadd -Q -Y EXTERNAL -H ldapi:/// -f cn\=samba.ldif</command>
-</screen>
-
-                <para>
-                To query and view this new schema:
-                </para>
+		<para>
+		To query and view this new schema:
+		</para>
 
 <screen>
 <command>sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=schema,cn=config 'cn=*samba*'</command>
@@ -2436,9 +2344,50 @@
  
 	<para>
 	Next, configure the <application>smbldap-tools</application> package to match your environment.  The package 
-	comes with a configuration helper script, smbldap-config.pl, that will ask questions.
-	</para>
-
+	comes with a configuration helper script called <application>smbldap-config</application>. Before running it,
+	though, you should decide on two important configuration settings in <filename>/etc/samba/smb.conf</filename>:
+	</para>
+	<itemizedlist mark='bullet'>
+		<listitem>
+		<para><emphasis>netbios name</emphasis>: how this server will be known. The default value is derived
+		from the server's hostname, but truncated at 15 characters.</para>
+		</listitem>
+		<listitem>
+		<para><emphasis>workgroup</emphasis>: the workgroup name for this server, or, if you later decide to make it
+		a domain controller, this will be the domain.</para>
+		</listitem>
+	</itemizedlist>
+	<para>It's important to make these choices now because <application>smbldap-config</application> will use them
+	to generate the config that will be later stored in the LDAP directory. If you run
+	<application>smbldap-config</application> now and later change these values in <filename>/etc/samba/smb.conf</filename>
+	there will be an inconsistency.
+	</para>
+
+	<para>Once you are happy with <emphasis>netbios name</emphasis> and <emphasis>workgroup</emphasis>, proceed to generat
+	the <application>smbldap-tools</application> configuration by running the configuration script which will ask you
+	some questions:
+	</para>
+<screen>
+<command>sudo smbldap-config</command>
+</screen>
+
+	<para>Some of the more important ones:</para>
+	<itemizedlist>
+		<listitem>
+			<para><emphasis>workgroup name</emphasis>: has to match what you will configure in
+			<filename>/etc/samba/smb.conf</filename> later on.</para>
+		</listitem>
+		<listitem>
+			<para><emphasis>ldap suffix</emphasis>: has to match the ldap suffix you chose when you configured the LDAP server.</para>
+		</listitem>
+		<listitem>
+			<para>other ldap suffixes: they are all relative to <emphasis>ldap suffix</emphasis> above. For example, for
+			<emphasis>ldap user suffix</emphasis> you should use <emphasis>ou=People</emphasis>.</para>
+		</listitem>
+		<listitem>
+			<para><emphasis>ldap master bind dn</emphasis> and <emphasis>bind password</emphasis>: use the rootDN credentials.</para>
+		</listitem>
+	</itemizedlist>
 	<para>
 	The <application>smbldap-populate</application> script will then add the LDAP objects required for Samba. It is a good idea to first
 	make a backup of your DIT using <application>slapcat</application>:
@@ -2449,13 +2398,18 @@
 </screen>
           
 	<para>
-	Once you have a backup proceed to populate your directory:
+	Once you have a backup proceed to populate your directory. It will ask you for a password for the "domain root"
+	user, which is also the "root" user stored in LDAP:
 	</para>
 
 <screen>
-<command>sudo smbldap-populate</command>
+<command>sudo smbldap-populate -g 10000 -u 10000 -r 10000</command>
 </screen>
 
+	<para>The <emphasis>-g</emphasis>, <emphasis>-u</emphasis> and <emphasis>-r</emphasis> parameters tell
+	<application>smbldap-tools</application> where to start the numeric uid and	gid allocation for the LDAP
+	users. You should pick a range start that does not overlap with your local
+	<emphasis>/etc/passwd</emphasis> users.</para>
 	<para>
 	You can create a LDIF file containing the new Samba objects by executing <command>sudo smbldap-populate -e samba.ldif</command>.
 	This allows you to look over the changes making sure everything is correct. If it is, rerun the script without the '-e'
@@ -2476,11 +2430,13 @@
 	<para>
 	There are multiple ways to configure Samba. For details on some common configurations see <xref linkend="samba"/>.      
 	To configure Samba to use LDAP, edit its configuration file <filename>/etc/samba/smb.conf</filename> commenting out
-	the default <emphasis>passdb backend</emphasis> parameter and adding some ldap-related ones:
+	the default <emphasis>passdb backend</emphasis> parameter and adding some ldap-related ones. Make sure to use the
+	same values you used when running <application>smbldap-populate</application>:
 	</para>
 
 <programlisting>
-#   passdb backend = tdbsam
+#  passdb backend = tdbsam
+   workgroup = EXAMPLE
 
 # LDAP Settings
    passdb backend = ldapsam:ldap://hostname
@@ -2490,37 +2446,64 @@
    ldap machine suffix = ou=Computers
    ldap idmap suffix = ou=Idmap
    ldap admin dn = cn=admin,dc=example,dc=com
+   # or off if TLS/SSL is not configured
    ldap ssl = start tls
    ldap passwd sync = yes
-...
-   add machine script = sudo /usr/sbin/smbldap-useradd -t 0 -w "%u"
 </programlisting>
 
 	<para>
 	Change the values to match your environment.
 	</para>
-
-	<para>
-	Restart <application>samba</application> to enable the new settings:
-	</para>
-
-<screen>
-<command>sudo systemctl restart smbd.service nmbd.service</command>
-</screen>
+	<note>
+		<para>The <filename>smb.conf</filename> as shipped by the package is quite long and has many configuration
+		examples. An easy way to visualize it without any comments is to run <application>testparm -s</application>.</para>
+	</note>
 
 	<para>
 	Now inform Samba about the rootDN user's password (the one set during the installation of the slapd package):
 	</para>
 
 <screen>
-<command>sudo smbpasswd -w password</command>
-</screen>
-
+<command>sudo smbpasswd -W</command>
+</screen>
+
+	<para>
+	As a final step to have your LDAP users be able to connect to samba and authenticate, we need these users to also show up
+	in the system as "unix" users. One way to do this is to use <application>libnss-ldap</application>. Detailed instructions
+	can be found in the <xref linkend="openldap-auth-config"/> section, but we only need the NSS part.
+	</para>
+
+	<procedure>
+		<step>
+			<para>Install <application>libnss-ldap</application></para>
+			<screen>sudo apt install libnss-ldap</screen>
+			<para>There is no need to use the LDAP rootDN login credentials, so you can skip that step.</para>
+		</step>
+		<step>
+			<para>Configure the LDAP profile for NSS:</para>
+			<screen>sudo auth-client-config -t nss -p lac_ldap</screen>
+		</step>
+		<step>
+			<para>Restart the Samba services:</para>
+			<screen>sudo systemctl restart smbd.service nmbd.service</screen>
+		</step>
+		<step>
+			<para>To quickly test the setup, see if <application>getent</application> can list the Samba groups:</para>
+<screen>
+<command>getent group</command>
+<computeroutput>
+...
+Account Operators:*:548:
+Print Operators:*:550:
+Backup Operators:*:551:
+Replicators:*:552:
+</computeroutput>
+</screen>
+		</step>
+	</procedure>
 	<para>
 	If you have existing LDAP users that you want to include in your new LDAP-backed Samba they will, of course, also need to be given
-	some of the extra attributes. The <application>smbpasswd</application> utility can do this as well (your host will need to be
-	able to see (enumerate) those users via NSS; install and configure either <application>libnss-ldapd</application> or
-	<application>libnss-ldap</application>):
+	some of the extra Samba specific attributes. The <application>smbpasswd</application> utility can do this for you:
 	</para>
 
 <screen>
@@ -2529,6 +2512,8 @@
 
 	<para>
 	You will prompted to enter a password. It will be considered as the new password for that user. Making it the same as before is reasonable.
+	Note that this command cannot be used to create a new user from scratch in LDAP (unless you are using <emphasis>ldapsam:trusted</emphasis>
+	and <emphasis>ldapsam:editposix</emphasis>, not covered in this guide).
 	</para>
 
 	<para>
@@ -2536,21 +2521,25 @@
 	Here are some examples:
 	</para> 
 
-	<itemizedlist>
+	<itemizedlist mark='bullet'>
 
 		<listitem>
 		<para>
-		To add a new user:
+		To add a new user with a home directory:
 		</para>
 
 <screen>
-<command>sudo smbldap-useradd -a -P username</command>
+<command>sudo smbldap-useradd -a -P -m username</command>
 </screen>
 
 		<para>
 		The <emphasis>-a</emphasis> option adds the Samba attributes, and the <emphasis>-P</emphasis> option calls the 
 		<application>smbldap-passwd</application> utility after the user is created allowing you to enter a password for the user.
+		Finally, <emphasis>-m</emphasis> creates a local home directory.
+		Test with the <application>getent</application> command:
 		</para>
+		<screen>getent passwd username</screen>
+		<para>If you don't get a response, then your <application>libnss-ldap</application> configuration is incorrect.</para>
 		</listitem>
 
 		<listitem>