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, 405 insertions, 0 deletions

diff --git a/docs/manpages/smbpasswd.8.xml b/docs/manpages/smbpasswd.8.xml
new file mode 100644
index 0000000000..3ee3a9e12e
--- /dev/null
+++ b/docs/manpages/smbpasswd.8.xml
@@ -0,0 +1,405 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+				  
+<!ENTITY % globalentities SYSTEM '../global.ent'> %globalentities;
+]>
+<refentry id="smbpasswd.8">
+
+<refmeta>
+	<refentrytitle>smbpasswd</refentrytitle>
+	<manvolnum>8</manvolnum>
+</refmeta>
+
+
+<refnamediv>
+	<refname>smbpasswd</refname>
+	<refpurpose>change a user's SMB password</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+	<cmdsynopsis>
+		<command>smbpasswd</command>
+		<arg choice="opt">-a</arg>	
+		<arg choice="opt">-x</arg>	
+		<arg choice="opt">-d</arg>	
+		<arg choice="opt">-e</arg>	
+		<arg choice="opt">-D debuglevel</arg>	
+		<arg choice="opt">-n</arg>	
+		<arg choice="opt">-r &lt;remote machine&gt;</arg>	
+		<arg choice="opt">-R &lt;name resolve order&gt;</arg>	
+		<arg choice="opt">-m</arg>	
+		<arg choice="opt">-U username[%password]</arg>	
+		<arg choice="opt">-h</arg>	
+		<arg choice="opt">-s</arg>	
+		<arg choice="opt">-w pass</arg>	
+		<arg choice="opt">-i</arg>
+		<arg choice="opt">-L</arg>
+		<arg choice="opt">username</arg>	
+	</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1>
+	<title>DESCRIPTION</title>
+
+	<para>This tool is part of the <citerefentry><refentrytitle>Samba</refentrytitle>
+	<manvolnum>7</manvolnum></citerefentry> suite.</para>
+	
+	<para>The smbpasswd program has several different 
+	functions, depending on whether it is run by the <emphasis>root</emphasis> user 
+	or not. When run as a normal user it allows the user to change 
+	the password used for their SMB sessions on any machines that store 
+	SMB passwords. </para>
+
+	<para>By default (when run with no arguments) it will attempt to 
+	change the current user's SMB password on the local machine. This is 
+	similar to the way the <command>passwd(1)</command> program works. <command>
+	smbpasswd</command> differs from how the passwd program works 
+	however in that it is not <emphasis>setuid root</emphasis> but works in 
+	a client-server mode and communicates with a 
+	locally running <citerefentry><refentrytitle>smbd</refentrytitle>
+	<manvolnum>8</manvolnum></citerefentry>. As a consequence in order for this to 
+	succeed the smbd daemon must be running on the local machine. On a 
+	UNIX machine the encrypted SMB passwords are usually stored in 
+	the <citerefentry><refentrytitle>smbpasswd</refentrytitle>
+	<manvolnum>5</manvolnum></citerefentry> file. </para>
+
+	<para>When run by an ordinary user with no options, smbpasswd 
+	will prompt them for their old SMB password and then ask them 
+	for their new password twice, to ensure that the new password
+	was typed correctly. No passwords will be echoed on the screen 
+	whilst being typed. If you have a blank SMB password (specified by 
+	the string "NO PASSWORD" in the smbpasswd file) then just press 
+	the &lt;Enter&gt; key when asked for your old password. </para>
+
+	<para>smbpasswd can also be used by a normal user to change their
+	SMB password on remote machines, such as Windows NT Primary Domain 
+	Controllers.   See the (<parameter>-r</parameter>) and <parameter>-U</parameter> options 
+	below. </para>
+
+	<para>When run by root, smbpasswd allows new users to be added 
+	and deleted in the smbpasswd file, as well as allows changes to 
+	the attributes of the user in this file to be made. When run by root, <command>
+	smbpasswd</command> accesses the local smbpasswd file 
+	directly, thus enabling changes to be made even if smbd is not 
+	running. </para>
+</refsect1>
+
+<refsect1>
+	<title>OPTIONS</title>
+	<variablelist>
+		<varlistentry>
+		<term>-a</term>
+		<listitem><para>This option specifies that the username 
+		following should be added to the local smbpasswd file, with the 
+		new password typed (type &lt;Enter&gt; for the old password). This 
+		option is ignored if the username following already exists in 
+		the smbpasswd file and it is treated like a regular change 
+		password command.  Note that the default passdb backends require 
+                the user to already exist in the system password file (usually 
+                <filename>/etc/passwd</filename>), else the request to add the 
+                user will fail. </para>
+		
+		<para>This option is only available when running smbpasswd 
+		as root. </para></listitem>
+		</varlistentry>
+		
+		
+		
+		<varlistentry>
+		<term>-x</term>
+		<listitem><para>This option specifies that the username 
+		following should be deleted from the local smbpasswd file.
+		</para>
+
+		<para>This option is only available when running smbpasswd as 
+		root.</para></listitem>
+		</varlistentry>
+		
+		
+		
+		<varlistentry>
+		<term>-d</term>
+		<listitem><para>This option specifies that the username following 
+		should be <constant>disabled</constant> in the local smbpasswd 
+		file. This is done by writing a <constant>'D'</constant> flag 
+		into the account control space in the smbpasswd file. Once this 
+		is done all attempts to authenticate via SMB using this username 
+		will fail. </para>
+		
+		<para>If the smbpasswd file is in the 'old' format (pre-Samba 2.0 
+		format) there is no space in the user's password entry to write
+		this information and the command will FAIL. See <citerefentry><refentrytitle>smbpasswd</refentrytitle>
+		<manvolnum>5</manvolnum></citerefentry> for details on the 'old' and new password file formats.
+		</para>
+
+		<para>This option is only available when running smbpasswd as 
+		root.</para></listitem>
+		</varlistentry>
+		
+		
+		<varlistentry>
+		<term>-e</term>
+		<listitem><para>This option specifies that the username following 
+		should be <constant>enabled</constant> in the local smbpasswd file, 
+		if the account was previously disabled. If the account was not 
+		disabled this option has no effect. Once the account is enabled then 
+		the user will be able to authenticate via SMB once again. </para>
+		
+		<para>If the smbpasswd file is in the 'old' format, then <command>
+		smbpasswd</command> will FAIL to enable the account.  
+                See <citerefentry><refentrytitle>smbpasswd</refentrytitle>
+		<manvolnum>5</manvolnum></citerefentry> for 
+		details on the 'old' and new password file formats. </para>
+
+		<para>This option is only available when running smbpasswd as root. 
+		</para></listitem>
+		</varlistentry>
+		
+
+
+		<varlistentry>
+		<term>-D debuglevel</term>
+		<listitem><para><replaceable>debuglevel</replaceable> is an integer 
+		from 0 to 10.  The default value if this parameter is not specified 
+		is zero. </para>
+
+		<para>The higher this value, the more detail will be logged to the 
+		log files about the activities of smbpasswd. At level 0, only 
+		critical errors and serious warnings will be logged. </para>
+
+		<para>Levels above 1 will generate considerable amounts of log 
+		data, and should only be used when investigating a problem. Levels 
+		above 3 are designed for use only by developers and generate
+		HUGE amounts of log data, most of which is extremely cryptic. 
+		</para></listitem>
+		</varlistentry>
+		
+		
+		
+		<varlistentry>
+		<term>-n</term>
+		<listitem><para>This option specifies that the username following 
+		should have their password set to null (i.e. a blank password) in 
+		the local smbpasswd file. This is done by writing the string "NO 
+		PASSWORD" as the first part of the first password stored in the 
+		smbpasswd file. </para>
+
+		<para>Note that to allow users to logon to a Samba server once 
+		the password has been set to "NO PASSWORD" in the smbpasswd
+		file the administrator must set the following parameter in the [global]
+		section of the <filename>smb.conf</filename> file : </para>
+		
+		<para><command>null passwords = yes</command></para> 
+		
+		<para>This option is only available when running smbpasswd as 
+		root.</para></listitem>
+		</varlistentry>
+		
+		
+		
+		<varlistentry>
+		<term>-r remote machine name</term>
+		<listitem><para>This option allows a user to specify what machine 
+		they wish to change their password on. Without this parameter 
+		smbpasswd defaults to the local host. The <replaceable>remote 
+		machine name</replaceable> is the NetBIOS name of the SMB/CIFS 
+		server to contact to attempt the password change. This name is 
+		resolved into an IP address using the standard name resolution 
+		mechanism in all programs of the Samba suite. See the <parameter>-R 
+		name resolve order</parameter> parameter for details on changing 
+		this resolving mechanism. </para>
+
+		<para>The username whose password is changed is that of the 
+		current UNIX logged on user. See the <parameter>-U username</parameter>
+		parameter for details on changing the password for a different 
+		username. </para>
+
+		<para>Note that if changing a Windows NT Domain password the 
+		remote machine specified must be the Primary Domain Controller for 
+		the domain (Backup Domain Controllers only have a read-only
+		copy of the user account database and will not allow the password 
+		change).</para>
+		
+		<para><emphasis>Note</emphasis> that Windows 95/98 do not have 
+		a real password database so it is not possible to change passwords 
+		specifying a Win95/98  machine as remote machine target. </para>
+		</listitem>
+		</varlistentry>
+		
+		
+		<varlistentry>
+		<term>-R name resolve order</term>
+		<listitem><para>This option allows the user of smbpasswd to determine
+		what name resolution services to use when looking up the NetBIOS
+		name of the host being connected to. </para>
+
+		<para>The options are :"lmhosts", "host", "wins" and "bcast". They
+		 cause names to be resolved as follows: </para>
+			<itemizedlist>
+				<listitem><para><constant>lmhosts</constant>: Lookup an IP 
+            address in the Samba lmhosts file. If the line in lmhosts has 
+            no name type attached to the NetBIOS name (see the <citerefentry><refentrytitle>lmhosts</refentrytitle>
+	    <manvolnum>5</manvolnum></citerefentry> for details) then
+            any name type matches for lookup.</para></listitem>
+
+            <listitem><para><constant>host</constant>: Do a standard host 
+            name to IP address resolution, using the system <filename>/etc/hosts
+            </filename>, NIS, or DNS lookups. This method of name resolution 
+            is operating system depended for instance on IRIX or Solaris this 
+            may be controlled by the <filename>/etc/nsswitch.conf</filename> 
+            file).  Note that this method is only used if the NetBIOS name 
+            type being queried is the 0x20 (server) name type, otherwise 
+            it is ignored.</para></listitem>
+
+            <listitem><para><constant>wins</constant>: Query a name with 
+            the IP address listed in the <parameter>wins server</parameter> 
+	    parameter.  If no WINS server has been specified this method 
+	    will be ignored.</para></listitem>
+
+            <listitem><para><constant>bcast</constant>: Do a broadcast on 
+            each of the known local interfaces listed in the
+            <parameter>interfaces</parameter> parameter. This is the least 
+	    reliable of the name resolution methods as it depends on the 
+	    target host being on a locally connected subnet.</para></listitem>
+		</itemizedlist>
+		
+		<para>The default order is <command>lmhosts, host, wins, bcast</command> 
+		and without this parameter or any entry in the <citerefentry><refentrytitle>smb.conf</refentrytitle>
+		<manvolnum>5</manvolnum></citerefentry> file the name resolution methods will 
+		be attempted in this order. </para></listitem>
+		</varlistentry>
+		
+		
+		<varlistentry>
+		<term>-m</term>
+		<listitem><para>This option tells smbpasswd that the account 
+		being changed is a MACHINE account. Currently this is used 
+		when Samba is being used as an NT Primary Domain Controller.</para>
+
+		<para>This option is only available when running smbpasswd as root.
+		</para></listitem>
+		</varlistentry>
+		
+		
+		<varlistentry>
+		<term>-U username</term>
+		<listitem><para>This option may only be used in conjunction 
+		with the <parameter>-r</parameter> option. When changing
+		a password on a remote machine it allows the user to specify 
+		the user name on that machine whose password will be changed. It 
+		is present to allow users who have different user names on 
+		different systems to change these passwords. </para></listitem>
+		</varlistentry>
+		
+		
+		<varlistentry>
+		<term>-h</term>
+		<listitem><para>This option prints the help string for <command>
+		smbpasswd</command>, selecting the correct one for running as root 
+		or as an ordinary user. </para></listitem>
+		</varlistentry>
+		
+		
+		<varlistentry>
+		<term>-s</term>
+		<listitem><para>This option causes smbpasswd to be silent (i.e. 
+		not issue prompts) and to read its old and new passwords from 
+		standard  input, rather than from <filename>/dev/tty</filename> 
+		(like the <command>passwd(1)</command> program does). This option 
+		is to aid people writing scripts to drive smbpasswd</para>
+		</listitem>
+		</varlistentry>
+		
+
+		<varlistentry>
+		<term>-w password</term>
+		<listitem><para>This parameter is only available if Samba
+		has been configured to use the experimental
+		<command>--with-ldapsam</command> option. The <parameter>-w</parameter> 
+		switch is used to specify the password to be used with the 
+		<smbconfoption><name>ldap admin dn</name></smbconfoption>.  Note that the password is stored in
+		the <filename>secrets.tdb</filename> and is keyed off 
+		of the admin's DN.  This means that if the value of <parameter>ldap
+		admin dn</parameter> ever changes, the password will need to be 
+		manually updated as well.
+		</para>
+		</listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>-i</term>
+		<listitem><para>This option tells smbpasswd that the account 
+		being changed is an interdomain trust account. Currently this is used 
+		when Samba is being used as an NT Primary Domain Controller. 
+		The account contains the info about another trusted domain.</para>
+
+		<para>This option is only available when running smbpasswd as root.
+		</para></listitem>
+		</varlistentry>
+
+		<varlistentry>
+		<term>-L</term>
+		<listitem><para>Run in local mode.</para></listitem>
+		</varlistentry>
+		
+		<varlistentry>
+		<term>username</term>
+		<listitem><para>This specifies the username for all of the 
+		<emphasis>root only</emphasis> options to operate on. Only root 
+		can specify this parameter as only root has the permission needed 
+		to modify attributes directly in the local smbpasswd file. 
+		</para></listitem>
+		</varlistentry>
+	</variablelist>
+</refsect1>
+
+
+<refsect1>
+	<title>NOTES</title>
+	
+	<para>Since <command>smbpasswd</command> works in client-server 
+	mode communicating  with a local smbd for a non-root user then 
+	the smbd daemon must be running for this to work. A common problem 
+	is to add a restriction to the hosts that may access the <command>
+	smbd</command> running on the local machine by specifying either <parameter>allow
+	hosts</parameter> or <parameter>deny hosts</parameter> entry in 
+	the <citerefentry><refentrytitle>smb.conf</refentrytitle>
+	<manvolnum>5</manvolnum></citerefentry> file and neglecting to 
+	allow "localhost" access to the smbd. </para>
+
+	<para>In addition, the smbpasswd command is only useful if Samba
+	has been set up to use encrypted passwords. </para>
+</refsect1>
+
+
+<refsect1>
+	<title>VERSION</title>
+
+	<para>This man page is correct for version 3.0 of the Samba suite.</para>
+</refsect1>
+
+<refsect1>
+	<title>SEE ALSO</title>
+	<para><citerefentry><refentrytitle>smbpasswd</refentrytitle>
+	<manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>Samba</refentrytitle>
+	<manvolnum>7</manvolnum></citerefentry>.</para>
+</refsect1>
+
+<refsect1>
+	<title>AUTHOR</title>
+	
+	<para>The original Samba software and related utilities 
+	were created by Andrew Tridgell. Samba is now developed
+	by the Samba Team as an Open Source project similar 
+	to the way the Linux kernel is developed.</para>
+	
+	<para>The original Samba man pages were written by Karl Auer. 
+	The man page sources were converted to YODL format (another 
+	excellent piece of Open Source software, available at <ulink url="ftp://ftp.icce.rug.nl/pub/unix/">
+	ftp://ftp.icce.rug.nl/pub/unix/</ulink>) and updated for the Samba 2.0 
+	release by Jeremy Allison.  The conversion to DocBook for 
+	Samba 2.2 was done by Gerald Carter. The conversion to DocBook XML 4.2
+	for Samba 3.0 was done by Alexander Bokovoy.</para>
+</refsect1>
+
+</refentry>