<chapter id="pdb-mysql">
<chapterinfo>
	<author>
		<firstname>Jelmer</firstname><surname>Vernooij</surname>
		<affiliation>
			<orgname>The Samba Team</orgname>
			<address><email>jelmer@samba.org</email></address>
		</affiliation>
	</author>
	<pubdate>November 2002</pubdate>
</chapterinfo>

<title>Passdb MySQL plugin</title>

<sect1>
<title>Building</title>

<para>To build the plugin, run <command>make bin/pdb_mysql.so</command>
in the <filename>source/</filename> directory of samba distribution. 
</para>

<para>Next, copy pdb_mysql.so to any location you want. I 
strongly recommend installing it in $PREFIX/lib or /usr/lib/samba/</para>

</sect1>

<sect1>
<title>Configuring</title>

<para>This plugin lacks some good documentation, but here is some short info:</para>

<para>Add a the following to the <command>passdb backend</command> variable in your <filename>smb.conf</filename>:
<programlisting>
passdb backend = [other-plugins] plugin:/location/to/pdb_mysql.so:identifier [other-plugins]
</programlisting>
</para>

<para>The identifier can be any string you like, as long as it doesn't collide with 
the identifiers of other plugins or other instances of pdb_mysql. If you 
specify multiple pdb_mysql.so entries in 'passdb backend', you also need to 
use different identifiers!
</para>

<para>
Additional options can be given thru the smb.conf file in the [global] section.
</para>

<para><programlisting>
identifier:mysql host                     - host name, defaults to 'localhost'
identifier:mysql password
identifier:mysql user                     - defaults to 'samba'
identifier:mysql database                 - defaults to 'samba'
identifier:mysql port                     - defaults to 3306
identifier:table                          - Name of the table containing users
</programlisting></para>

<para>
<emphasis>
WARNING: since the password for the mysql user is stored in the 
smb.conf file, you should make the the smb.conf file 
readable only to the user that runs samba. This is considered a security 
bug and will be fixed soon.</emphasis>
</para>

<para>Names of the columns in this table(I've added column types those columns should have first):</para>

<para><programlisting>
identifier:logon time column             - int(9)
identifier:logoff time column            - int(9)
identifier:kickoff time column           - int(9)
identifier:pass last set time column     - int(9)
identifier:pass can change time column   - int(9)
identifier:pass must change time column  - int(9)
identifier:username column               - varchar(255) - unix username
identifier:domain column                 - varchar(255) - NT domain user is part of
identifier:nt username column            - varchar(255) - NT username
identifier:fullname column            - varchar(255) - Full name of user
identifier:home dir column               - varchar(255) - Unix homedir path
identifier:dir drive column              - varchar(2) - Directory drive path (eg: 'H:')
identifier:logon script column           - varchar(255) - Batch file to run on client side when logging on
identifier:profile path column           - varchar(255) - Path of profile
identifier:acct desc column              - varchar(255) - Some ASCII NT user data
identifier:workstations column           - varchar(255) - Workstations user can logon to (or NULL for all)
identifier:unknown string column         - varchar(255) - unknown string
identifier:munged dial column            - varchar(255) - ?
identifier:uid column                    - int(9) - Unix user ID (uid)
identifier:gid column                    - int(9) - Unix user group (gid)
identifier:user sid column               - varchar(255) - NT user SID
identifier:group sid column              - varchar(255) - NT group ID
identifier:lanman pass column            - varchar(255) - encrypted lanman password
identifier:nt pass column                - varchar(255) - encrypted nt passwd
identifier:plain pass column             - varchar(255) - plaintext password
identifier:acct control column           - int(9) - nt user data
identifier:unknown 3 column              - int(9) - unknown
identifier:logon divs column             - int(9) - ?
identifier:hours len column              - int(9) - ?
identifier:unknown 5 column              - int(9) - unknown
identifier:unknown 6 column              - int(9) - unknown
</programlisting></para>

<para>
Eventually, you can put a colon (:) after the name of each column, which 
should specify the column to update when updating the table. You can also
specify nothing behind the colon - then the data from the field will not be 
updated. 
</para>

</sect1>

<sect1>
<title>Using plaintext passwords or encrypted password</title>

<para>
I strongly discourage the use of plaintext passwords, however, you can use them:
</para>

<para>
If you would like to use plaintext passwords, set 'identifier:lanman pass column' and 'identifier:nt pass column' to 'NULL' (without the quotes) and 'identifier:plain pass column' to the name of the column containing the plaintext passwords. 
</para>

<para>
If you use encrypted passwords, set the 'identifier:plain pass column' to 'NULL' (without the quotes). This is the default.
</para>

</sect1>

<sect1>
<title>Getting non-column data from the table</title>

<para>
It is possible to have not all data in the database and making some 'constant'.
</para>

<para>
For example, you can set 'identifier:fullname column' to : 
<command>CONCAT(First_name,' ',Sur_name)</command>
</para>

<para>
Or, set 'identifier:workstations column' to :
<command>NULL</command></para>

<para>See the MySQL documentation for more language constructs.</para>

</sect1>
</chapter>
