Samba3-HOWTO/TOSHARG-Passdb.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
   3 <chapter id="passdb">
   4 <chapterinfo>
   5         &author.jelmer;
   6         &author.jht;
   7         &author.jerry;
   8         &author.jeremy;
   9         <author>&person.gd;<contrib>LDAP updates</contrib></author>
  10         <author>
  11                 <firstname>Olivier (lem)</firstname><surname>Lemaire</surname>
  12                 <affiliation>
  13                         <orgname>IDEALX</orgname>
  14                         <address><email>olem@IDEALX.org</email></address>
  15                 </affiliation>
  16         </author>
  17
  18         <pubdate>May 24, 2003</pubdate>
  19 </chapterinfo>
  20 <title>Account Information Databases</title>
  21
  22 <para>
  23 <indexterm><primary>account backends</primary></indexterm>
  24 <indexterm><primary>password backends</primary></indexterm>
  25 <indexterm><primary>scalability</primary></indexterm>
  26 <indexterm><primary>ADS</primary></indexterm>
  27 Samba-3 implements a new capability to work concurrently with multiple account backends.
  28 The possible new combinations of password backends allows Samba-3 a degree of flexibility
  29 and scalability that previously could be achieved only with MS Windows Active Directory (ADS).
  30 This chapter describes the new functionality and how to get the most out of it.
  31 </para>
  32
  33 <para>
  34 <indexterm><primary>passdb backend</primary></indexterm>
  35 <indexterm><primary>smbpasswd</primary></indexterm>
  36 <indexterm><primary>tdbsam</primary></indexterm>
  37 <indexterm><primary>ldapsam</primary></indexterm>
  38 <indexterm><primary>LDAP</primary></indexterm>
  39 <indexterm><primary>single repository</primary></indexterm>
  40 The three passdb backends that are fully maintained (actively supported) by the Samba Team are:
  41 <literal>smbpasswd</literal> (being obsoleted), <literal>tdbsam</literal> (a tdb-based binary file format),
  42 and <literal>ldapsam</literal> (LDAP directory).  Of these, only the <literal>ldapsam</literal> backend
  43 stores both POSIX (UNIX) and Samba user and group account information in a single repository. The
  44 <literal>smbpasswd</literal> and <literal>tdbsam</literal> backends store only Samba user accounts.
  45 </para>
  46
  47 <para>
  48 In a strict sense, there are three supported account storage and access systems. One of these is considered
  49 obsolete (smbpasswd). It is recommended to use the <literal>tdbsam</literal> method for all simple systems. Use
  50 <literal>ldapsam</literal> for larger and more complex networks.
  51 </para>
  52
  53 <para>
  54 <indexterm><primary>passdb backend</primary></indexterm>
  55 <indexterm><primary>account storage mechanisms</primary></indexterm>
  56 <indexterm><primary>account storage system</primary></indexterm>
  57 <indexterm><primary>user and trust accounts</primary></indexterm>
  58 <indexterm><primary>machine trust accounts</primary></indexterm>
  59 <indexterm><primary>computer accounts</primary></indexterm>
  60 <indexterm><primary>interdomain trust accounts</primary></indexterm>
  61 In a strict and literal sense, the passdb backends are account storage mechanisms (or methods) alone. The choice
  62 of terminology can be misleading, however we are stuck with this choice of wording. This chapter documents the
  63 nature of the account storage system with a focus on user and trust accounts. Trust accounts have two forms,
  64 machine trust accounts (computer accounts) and interdomain trust accounts. These are all treated as user-like
  65 entities.
  66 </para>
  67
  68 <sect1>
  69 <title>Features and Benefits</title>
  70
  71 <para>
  72 Samba-3 provides for complete backward compatibility with Samba-2.2.x functionality
  73 as follows:
  74 <indexterm><primary>SAM backend</primary><secondary>smbpasswd</secondary></indexterm>
  75 <indexterm><primary>SAM backend</primary><secondary>ldapsam_compat</secondary></indexterm>
  76 <indexterm><primary>encrypted passwords</primary></indexterm>
  77 </para>
  78
  79 <sect2>
  80         <title>Backward Compatibility Account Storage Systems</title>
  81
  82 <variablelist>
  83         <varlistentry><term>Plaintext</term>
  84                 <listitem>
  85                         <para>
  86 <indexterm><primary>plaintext</primary></indexterm>
  87 <indexterm><primary>plaintext authentication</primary></indexterm>
  88 <indexterm><primary>/etc/passwd</primary></indexterm>
  89 <indexterm><primary>/etc/shadow</primary></indexterm>
  90 <indexterm><primary>PAM</primary></indexterm>
  91                         This isn't really a backend at all, but is listed here for simplicity.  Samba can be configured to pass
  92                         plaintext authentication requests to the traditional UNIX/Linux <filename>/etc/passwd</filename> and
  93                         <filename>/etc/shadow</filename>-style subsystems.  On systems that have Pluggable Authentication Modules
  94                         (PAM) support, all PAM modules are supported. The behavior is just as it was with Samba-2.2.x, and the
  95                         protocol limitations imposed by MS Windows clients apply likewise. Please refer to <link
  96                         linkend="passdbtech">Technical Information</link>, for more information regarding the limitations of plaintext
  97                         password usage.
  98                         </para>
  99                 </listitem>
 100         </varlistentry>
 101
 102         <varlistentry><term>smbpasswd</term>
 103                 <listitem>
 104                         <para>
 105 <indexterm><primary>smbpasswd</primary></indexterm>
 106 <indexterm><primary>LanMan passwords</primary></indexterm>
 107 <indexterm><primary>NT-encrypted passwords</primary></indexterm>
 108 <indexterm><primary>SAM</primary></indexterm>
 109                         This option allows continued use of the <filename>smbpasswd</filename>
 110                         file that maintains a plain ASCII (text) layout that includes the MS Windows
 111                         LanMan and NT-encrypted passwords as well as a field that stores some
 112                         account information. This form of password backend does not store any of
 113                         the MS Windows NT/200x SAM (Security Account Manager) information required to
 114                         provide the extended controls that are needed for more comprehensive
 115                         interoperation with MS Windows NT4/200x servers.
 116                         </para>
 117
 118                         <para>
 119                         This backend should be used only for backward compatibility with older
 120                         versions of Samba. It may be deprecated in future releases.
 121                         </para>
 122                 </listitem>
 123         </varlistentry>
 124
 125         <varlistentry><term>ldapsam_compat (Samba-2.2 LDAP Compatibility)</term>
 126                 <listitem>
 127                         <para>
 128 <indexterm><primary>ldapsam_compat</primary></indexterm>
 129 <indexterm><primary>Samba-2.2.x LDAP schema</primary></indexterm>
 130 <indexterm><primary>OpenLDAP backend</primary></indexterm>
 131                         There is a password backend option that allows continued operation with
 132                         an existing OpenLDAP backend that uses the Samba-2.2.x LDAP schema extension.
 133                         This option is provided primarily as a migration tool, although there is
 134                         no reason to force migration at this time. This tool will eventually
 135                         be deprecated.
 136                         </para>
 137                 </listitem>
 138         </varlistentry>
 139 </variablelist>
 140
 141 </sect2>
 142
 143 <sect2>
 144 <title>New Account Storage Systems</title>
 145
 146 <para>
 147 Samba-3 introduces a number of new password backend capabilities.
 148 <indexterm><primary>SAM backend</primary><secondary>tdbsam</secondary></indexterm>
 149 <indexterm><primary>SAM backend</primary><secondary>ldapsam</secondary></indexterm>
 150 <indexterm><primary>SAM backend</primary><secondary>mysqlsam</secondary></indexterm>
 151 <indexterm><primary>SAM backend</primary><secondary>xmlsam</secondary></indexterm>
 152 </para>
 153
 154 <variablelist>
 155         <varlistentry><term>tdbsam</term>
 156                 <listitem>
 157                         <para>
 158 <indexterm><primary>rich database backend</primary></indexterm>
 159 <indexterm><primary>PDC</primary></indexterm>
 160 <indexterm><primary>BDC</primary></indexterm>
 161                         This backend provides a rich database backend for local servers. This
 162                         backend is not suitable for multiple domain controllers (i.e., PDC + one
 163                         or more BDC) installations.
 164                         </para>
 165
 166                         <para>
 167 <indexterm><primary>extended SAM</primary></indexterm>
 168 <indexterm><primary>TDB</primary></indexterm>
 169 <indexterm><primary>binary format TDB</primary></indexterm>
 170 <indexterm><primary>trivial database</primary></indexterm>
 171 <indexterm><primary>system access controls</primary></indexterm>
 172 <indexterm><primary>MS Windows NT4/200x</primary></indexterm>
 173                         The <emphasis>tdbsam</emphasis> password backend stores the old <emphasis>
 174                         smbpasswd</emphasis> information plus the extended MS Windows NT/200x
 175                         SAM information into a binary format TDB (trivial database) file.
 176                         The inclusion of the extended information makes it possible for Samba-3
 177                         to implement the same account and system access controls that are possible
 178                         with MS Windows NT4/200x-based systems.
 179                         </para>
 180
 181                         <para>
 182 <indexterm><primary>simple operation</primary></indexterm>
 183 <indexterm><primary>OpenLDAP</primary></indexterm>
 184 <indexterm><primary>ADS</primary></indexterm>
 185                         The inclusion of the <emphasis>tdbsam</emphasis> capability is a direct
 186                         response to user requests to allow simple site operation without the overhead
 187                         of the complexities of running OpenLDAP. It is recommended to use this only
 188                         for sites that have fewer than 250 users. For larger sites or implementations,
 189                         the use of OpenLDAP or of Active Directory integration is strongly recommended.
 190                         </para>
 191                 </listitem>
 192         </varlistentry>
 193
 194         <varlistentry><term>ldapsam</term>
 195                 <listitem>
 196                         <para>
 197 <indexterm><primary>rich directory backend</primary></indexterm>
 198 <indexterm><primary>distributed account</primary></indexterm>
 199                         This provides a rich directory backend for distributed account installation.
 200                         </para>
 201
 202                         <para>
 203 <indexterm><primary>LDAP</primary></indexterm>
 204 <indexterm><primary>OpenLDAP</primary></indexterm>
 205 <indexterm><primary>Samba schema</primary></indexterm>
 206 <indexterm><primary>schema file</primary></indexterm>
 207 <indexterm><primary>examples/LDAP</primary></indexterm>
 208                         Samba-3 has a new and extended LDAP implementation that requires configuration
 209                         of OpenLDAP with a new format Samba schema. The new format schema file is
 210                         included in the <filename class="directory">examples/LDAP</filename> directory of the Samba distribution.
 211                         </para>
 212
 213                         <para>
 214 <indexterm><primary>expands control abilities</primary></indexterm>
 215 <indexterm><primary>profile</primary></indexterm>
 216 <indexterm><primary>home directories</primary></indexterm>
 217 <indexterm><primary>account access controls</primary></indexterm>
 218 <indexterm><primary>greater scalability</primary></indexterm>
 219                         The new LDAP implementation significantly expands the control abilities that
 220                         were possible with prior versions of Samba. It is now possible to specify
 221                         <quote>per-user</quote> profile settings, home directories, account access controls, and
 222                         much more. Corporate sites will see that the Samba Team has listened to their
 223                         requests both for capability and greater scalability.
 224                         </para>
 225                 </listitem>
 226         </varlistentry>
 227
 228         <varlistentry><term>mysqlsam (MySQL-based backend)</term>
 229                 <listitem>
 230                         <para>
 231 <indexterm><primary>MySQL-based SAM</primary></indexterm>
 232 <indexterm><primary>database backend</primary></indexterm>
 233 <indexterm><primary>mysqlsam</primary></indexterm>
 234                         It is expected that the MySQL-based SAM will be very popular in some corners.
 235                         This database backend will be of considerable interest to sites that want to
 236                         leverage existing MySQL technology.
 237                         </para>
 238                 </listitem>
 239         </varlistentry>
 240
 241         <varlistentry><term>pgsqlsam (PostGreSQL-based backend)</term>
 242                 <listitem>
 243                         <para>
 244 <indexterm><primary>PostgreSQL database</primary></indexterm>
 245 <indexterm><primary>mysqlsam</primary></indexterm>
 246                                 Makes use of a PostgreSQL database to store account information.  This backend is largely undocumented at
 247                                 the moment, though its configuration is very similar to that of the mysqlsam backend.
 248                         </para>
 249                 </listitem>
 250         </varlistentry>
 251
 252         <varlistentry><term>xmlsam (XML-based datafile)</term>
 253                 <listitem>
 254                         <para>
 255 <indexterm><primary>pdbedit</primary></indexterm>
 256 <indexterm><primary>XML format</primary></indexterm>
 257 <indexterm><primary>pdb2pdb</primary></indexterm>
 258                         Allows the account and password data to be stored in an XML format
 259                         data file. This backend cannot be used for normal operation, it can only
 260                         be used in conjunction with <command>pdbedit</command>'s pdb2pdb
 261                         functionality. The Document Type Definition (DTD) file that is used
 262                         might be subject to changes in the future. (See the XML <ulink
 263                         url="http://www.brics.dk/~amoeller/XML/schemas/">reference</ulink> for a definition
 264                         of XML terms.)
 265                         </para>
 266
 267                         <para>
 268 <indexterm><primary>account migration</primary></indexterm>
 269 <indexterm><primary>database backends</primary></indexterm>
 270 <indexterm><primary>backend format</primary></indexterm>
 271                         The <parameter>xmlsam</parameter> option can be useful for account migration between database
 272                         backends or backups. Use of this tool allows the data to be edited before migration
 273                         into another backend format.
 274                         </para>
 275                 </listitem>
 276         </varlistentry>
 277
 278 </variablelist>
 279
 280 </sect2>
 281
 282 </sect1>
 283
 284 <sect1 id="passdbtech">
 285         <title>Technical Information</title>
 286
 287         <para>
 288 <indexterm><primary>plaintext passwords</primary></indexterm>
 289 <indexterm><primary>encrypted passwords</primary></indexterm>
 290         Old Windows clients send plaintext passwords over the wire. Samba can check these
 291         passwords by encrypting them and comparing them to the hash stored in the UNIX user database.
 292         </para>
 293
 294         <para>
 295 <indexterm><primary>encrypted passwords</primary></indexterm>
 296 <indexterm><primary>LanMan</primary></indexterm>
 297 <indexterm><primary>plaintext passwords</primary></indexterm>
 298 <indexterm><primary>registry</primary></indexterm>
 299         Newer Windows clients send encrypted passwords (LanMan and NT hashes) instead of plaintext passwords over
 300         the wire. The newest clients will send only encrypted passwords and refuse to send plaintext passwords unless
 301         their registry is tweaked.
 302         </para>
 303
 304         <para>
 305 <indexterm><primary>UNIX-style encrypted passwords</primary></indexterm>
 306 <indexterm><primary>converted</primary></indexterm>
 307         Many people ask why Samba cannot simply use the UNIX password database. Windows requires
 308         passwords that are encrypted in its own format.  The UNIX passwords can't be converted to
 309         UNIX-style encrypted passwords. Because of that, you can't use the standard UNIX user
 310         database, and you have to store the LanMan and NT hashes somewhere else.
 311         </para>
 312
 313         <para>
 314 <indexterm><primary>differently encrypted passwords</primary></indexterm>
 315 <indexterm><primary>profile</primary></indexterm>
 316 <indexterm><primary>workstations</primary></indexterm>
 317 <indexterm><primary>tdbsam</primary></indexterm>
 318         In addition to differently encrypted passwords, Windows also stores certain data for each
 319         user that is not stored in a UNIX user database: for example, workstations the user may logon from,
 320         the location where the user's profile is stored, and so on. Samba retrieves and stores this
 321         information using a <smbconfoption name="passdb backend"/>. Commonly available backends are LDAP,
 322         tdbsam, plain text file, and MySQL. For more information, see the man page for &smb.conf; regarding the
 323         <smbconfoption name="passdb backend"/> parameter.
 324         </para>
 325
 326
 327         <figure id="idmap-sid2uid">
 328                 <title>IDMAP: Resolution of SIDs to UIDs.</title>
 329                 <imagefile scale="40">idmap-sid2uid</imagefile>
 330         </figure>
 331
 332         <para>
 333         <indexterm><primary>SID</primary></indexterm>
 334 <indexterm><primary>UID</primary></indexterm>
 335 <indexterm><primary>SID</primary></indexterm>
 336         The resolution of SIDs to UIDs is fundamental to correct operation of Samba. In both cases shown, if winbindd
 337         is not running or cannot be contacted, then only local SID/UID resolution is possible. See <link
 338         linkend="idmap-sid2uid">resolution of SIDs to UIDs</link> and <link linkend="idmap-uid2sid">resolution of UIDs
 339         to SIDs</link> diagrams.
 340         </para>
 341
 342         <figure id="idmap-uid2sid">
 343                 <title>IDMAP: Resolution of UIDs to SIDs.</title>
 344                 <imagefile scale="50">idmap-uid2sid</imagefile>
 345         </figure>
 346
 347         <sect2>
 348         <title>Important Notes About Security</title>
 349
 350                 <para>
 351 <indexterm><primary>SMB password encryption</primary></indexterm>
 352 <indexterm><primary>clear-text passwords</primary></indexterm>
 353 <indexterm><primary>hashed password equivalent</primary></indexterm>
 354 <indexterm><primary>LDAP</primary></indexterm>
 355 <indexterm><primary>MYSQL</primary></indexterm>
 356 <indexterm><primary>secret</primary></indexterm>
 357                 The UNIX and SMB password encryption techniques seem similar on the surface. This
 358                 similarity is, however, only skin deep. The UNIX scheme typically sends clear-text
 359                 passwords over the network when logging in. This is bad. The SMB encryption scheme
 360                 never sends the clear-text password over the network, but it does store the 16-byte
 361                 hashed values on disk. This is also bad. Why? Because the 16 byte hashed values
 362                 are a <quote>password equivalent.</quote> You cannot derive the user's password from them, but
 363                 they could potentially be used in a modified client to gain access to a server.
 364                 This would require considerable technical knowledge on behalf of the attacker but
 365                 is perfectly possible. You should therefore treat the data stored in whatever passdb
 366                 backend you use (smbpasswd file, LDAP, MYSQL) as though it contained the clear-text
 367                 passwords of all your users. Its contents must be kept secret, and the file should
 368                 be protected accordingly.
 369                 </para>
 370
 371                 <para>
 372 <indexterm><primary>password scheme</primary></indexterm>
 373 <indexterm><primary>plaintext passwords</primary></indexterm>
 374 <indexterm><primary>compatible</primary></indexterm>
 375                 Ideally, we would like a password scheme that involves neither plaintext passwords
 376                 on the network nor plaintext passwords on disk. Unfortunately, this is not available because Samba is stuck with
 377                 having to be compatible with other SMB systems (Windows NT, Windows for Workgroups, Windows 9x/Me).
 378                 </para>
 379
 380                 <para>
 381 <indexterm><primary>encrypted passwords</primary></indexterm>
 382 <indexterm><primary>plaintext passwords</primary></indexterm>
 383                 Windows NT 4.0 Service Pack 3 changed the default setting so plaintext passwords
 384                 are disabled from being sent over the wire. This mandates either the use of encrypted
 385                 password support or editing the Windows NT registry to re-enable plaintext passwords.
 386                 </para>
 387
 388                 <para>
 389 <indexterm><primary>domain security</primary></indexterm>
 390 <indexterm><primary>domain environment</primary></indexterm>
 391                 The following versions of Microsoft Windows do not support full domain security protocols,
 392                 although they may log onto a domain environment:
 393                 </para>
 394
 395                 <itemizedlist>
 396                         <listitem><para>MS DOS Network client 3.0 with the basic network redirector installed.</para></listitem>
 397                         <listitem><para>Windows 95 with the network redirector update installed.</para></listitem>
 398                         <listitem><para>Windows 98 [Second Edition].</para></listitem>
 399                         <listitem><para>Windows Me.</para></listitem>
 400                 </itemizedlist>
 401
 402                 <note>
 403                 <para>
 404 <indexterm><primary>Windows XP Home</primary></indexterm>
 405 <indexterm><primary>domain member</primary></indexterm>
 406 <indexterm><primary>domain logons</primary></indexterm>
 407                 MS Windows XP Home does not have facilities to become a domain member, and it cannot participate in domain logons.
 408                 </para>
 409                 </note>
 410
 411                 <para>
 412                 The following versions of MS Windows fully support domain security protocols.
 413                 </para>
 414
 415                 <itemizedlist>
 416                         <listitem><para>Windows NT 3.5x.</para></listitem>
 417                         <listitem><para>Windows NT 4.0.</para></listitem>
 418                         <listitem><para>Windows 2000 Professional.</para></listitem>
 419                         <listitem><para>Windows 200x Server/Advanced Server.</para></listitem>
 420                         <listitem><para>Windows XP Professional.</para></listitem>
 421                 </itemizedlist>
 422
 423                 <para>
 424 <indexterm><primary>SMB/CIFS</primary></indexterm>
 425 <indexterm><primary>authentication</primary></indexterm>
 426 <indexterm><primary>challenge/response mechanis</primary></indexterm>
 427 <indexterm><primary>clear-text</primary></indexterm>
 428 <indexterm><primary>encrypted</primary></indexterm>
 429 <indexterm><primary>negotiate</primary></indexterm>
 430                 All current releases of Microsoft SMB/CIFS clients support authentication via the
 431                 SMB challenge/response mechanism described here. Enabling clear-text authentication
 432                 does not disable the ability of the client to participate in encrypted authentication.
 433                 Instead, it allows the client to negotiate either plaintext or encrypted password
 434                 handling.
 435                 </para>
 436
 437                 <para>
 438 <indexterm><primary>cached encrypted password</primary></indexterm>
 439 <indexterm><primary>plaintext passwords</primary></indexterm>
 440 <indexterm><primary>registry change</primary></indexterm>
 441 <indexterm><primary>auto-reconnect</primary></indexterm>
 442 <indexterm><primary>encrypted passwords</primary></indexterm>
 443                 MS Windows clients will cache the encrypted password alone. Where plaintext passwords
 444                 are re-enabled through the appropriate registry change, the plaintext password is never
 445                 cached. This means that in the event that a network connections should become disconnected
 446                 (broken), only the cached (encrypted) password will be sent to the resource server to
 447                 effect an auto-reconnect. If the resource server does not support encrypted passwords, the
 448                 auto-reconnect will fail. Use of encrypted passwords is strongly advised.
 449                 </para>
 450
 451                 <sect3>
 452                 <title>Advantages of Encrypted Passwords</title>
 453
 454                         <itemizedlist>
 455                                 <listitem><para>
 456 <indexterm><primary>passed across the network</primary></indexterm>
 457 <indexterm><primary>network sniffer</primary></indexterm>
 458 <indexterm><primary>SMB server</primary></indexterm>
 459                                 Plaintext passwords are not passed across the network. Someone using a network sniffer
 460                                 cannot just record passwords going to the SMB server.
 461                                 </para></listitem>
 462
 463                                 <listitem><para>
 464 <indexterm><primary>not stored anywhere</primary></indexterm>
 465 <indexterm><primary>memory</primary></indexterm>
 466 <indexterm><primary>disk</primary></indexterm>
 467                                 Plaintext passwords are not stored anywhere in memory or on disk.
 468                                 </para></listitem>
 469
 470                                 <listitem><para>
 471 <indexterm><primary>encrypted passwords</primary></indexterm>
 472 <indexterm><primary>user-level security</primary></indexterm>
 473 <indexterm><primary>password prompt</primary></indexterm>
 474 <indexterm><primary>SMB encryption</primary></indexterm>
 475                                 Windows NT does not like talking to a server that does not support encrypted passwords. It will refuse to
 476                                 browse the server if the server is also in user-level security mode. It will insist on prompting the user for
 477                                 the password on each connection, which is very annoying. The only thing you can do to stop this is to use SMB
 478                                 encryption.
 479                                 </para></listitem>
 480
 481                                 <listitem><para>
 482 <indexterm><primary>encrypted password</primary></indexterm>
 483 <indexterm><primary>automatic reconnects</primary></indexterm>
 484                                 Encrypted password support allows automatic share (resource) reconnects.
 485                                 </para></listitem>
 486
 487                                 <listitem><para>
 488 <indexterm><primary>PDC</primary></indexterm>
 489 <indexterm><primary>BDC</primary></indexterm>
 490                                 Encrypted passwords are essential for PDC/BDC operation.
 491                                 </para></listitem>
 492                         </itemizedlist>
 493                 </sect3>
 494
 495
 496                 <sect3>
 497                 <title>Advantages of Non-Encrypted Passwords</title>
 498
 499                         <itemizedlist>
 500                                 <listitem><para>
 501 <indexterm><primary>cached in memory</primary></indexterm>
 502                                 Plaintext passwords are not kept on disk and are not cached in memory.
 503                                 </para></listitem>
 504
 505                                 <listitem><para>
 506 <indexterm><primary>Login</primary></indexterm>
 507 <indexterm><primary>FTP</primary></indexterm>
 508                                 Plaintext passwords use the same password file as other UNIX services, such as Login and FTP.
 509                                 </para></listitem>
 510
 511                                 <listitem><para>
 512 <indexterm><primary>Telnet</primary></indexterm>
 513 <indexterm><primary>FTP</primary></indexterm>
 514                                 Use of other services (such as Telnet and FTP) that send plaintext passwords over
 515                                 the network makes sending them for SMB not such a big deal.
 516                                 </para></listitem>
 517                         </itemizedlist>
 518                 </sect3>
 519         </sect2>
 520
 521         <sect2>
 522         <title>Mapping User Identifiers between MS Windows and UNIX</title>
 523
 524         <para>
 525 <indexterm><primary>UID</primary></indexterm>
 526 <indexterm><primary>SID</primary></indexterm>
 527 <indexterm><primary>mapping</primary></indexterm>
 528         Every operation in UNIX/Linux requires a user identifier (UID), just as in
 529         MS Windows NT4/200x this requires a security identifier (SID). Samba provides
 530         two means for mapping an MS Windows user to a UNIX/Linux UID.
 531         </para>
 532
 533         <para>
 534 <indexterm><primary>Samba SAM</primary></indexterm>
 535 <indexterm><primary>SAM</primary></indexterm>
 536 <indexterm><primary>UID</primary></indexterm>
 537 <indexterm><primary>account information database</primary></indexterm>
 538 <indexterm><primary>local user account</primary></indexterm>
 539         First, all Samba SAM database accounts require a UNIX/Linux UID that the account will map to. As users are
 540         added to the account information database, Samba will call the <smbconfoption name="add user script"/>
 541         interface to add the account to the Samba host OS. In essence all accounts in the local SAM require a local
 542         user account.
 543         </para>
 544
 545         <para>
 546         <indexterm><primary>idmap uid</primary></indexterm>
 547         <indexterm><primary>idmap gid</primary></indexterm>
 548         <indexterm><primary>UID</primary></indexterm>
 549         <indexterm><primary>SAM</primary></indexterm>
 550         <indexterm><primary>foreign domain</primary></indexterm>
 551         <indexterm><primary>non-member Windows client</primary></indexterm>
 552         <indexterm><primary>SID</primary></indexterm>
 553         The second way to map Windows SID to UNIX UID is via the <emphasis>idmap uid</emphasis> and
 554         <emphasis>idmap gid</emphasis> parameters in &smb.conf;.  Please refer to the man page for information about
 555         these parameters.  These parameters are essential when mapping users from a remote (non-member Windows client
 556         or a member of a foreign domain) SAM server.
 557         </para>
 558
 559         </sect2>
 560
 561         <sect2 id="idmapbackend">
 562         <title>Mapping Common UIDs/GIDs on Distributed Machines</title>
 563
 564         <para>
 565 <indexterm><primary>UID</primary></indexterm>
 566 <indexterm><primary>GID</primary></indexterm>
 567 <indexterm><primary>BDC</primary></indexterm>
 568 <indexterm><primary>domain member servers</primary></indexterm>
 569 <indexterm><primary>NFS</primary></indexterm>
 570 <indexterm><primary>rsync</primary></indexterm>
 571         Samba-3 has a special facility that makes it possible to maintain identical UIDs and GIDs
 572         on all servers in a distributed network. A distributed network is one where there exists
 573         a PDC, one or more BDCs, and/or one or more domain member servers. Why is this important?
 574         This is important if files are being shared over more than one protocol (e.g., NFS) and where
 575         users are copying files across UNIX/Linux systems using tools such as <command>rsync</command>.
 576         </para>
 577
 578         <para>
 579 <indexterm><primary>LDAP-based</primary></indexterm>
 580 <indexterm><primary>idmap backend</primary></indexterm>
 581 <indexterm><primary>UID</primary></indexterm>
 582 <indexterm><primary>GID</primary></indexterm>
 583 <indexterm><primary>LDAP</primary></indexterm>
 584 <indexterm><primary>SAM backend</primary></indexterm>
 585 <indexterm><primary>LDAP idmap Backend</primary></indexterm>
 586         <indexterm><primary>idmap backend</primary></indexterm>
 587         The special facility is enabled using a parameter called <parameter>idmap backend</parameter>.
 588         The default setting for this parameter is an empty string. Technically it is possible to use
 589         an LDAP-based idmap backend for UIDs and GIDs, but it makes most sense when this is done for
 590         network configurations that also use LDAP for the SAM backend.
 591         <link linkend="idmapbackendexample">Example Configuration with the LDAP idmap Backend</link>
 592         shows that configuration.
 593         </para>
 594
 595 <indexterm><primary>SAM backend</primary><secondary>ldapsam</secondary></indexterm>
 596 <example id="idmapbackendexample">
 597 <title>Example Configuration with the LDAP idmap Backend</title>
 598 <smbconfblock>
 599 <smbconfsection name="[global]"/>
 600 <smbconfoption name="idmap backend">ldap:ldap://ldap-server.quenya.org:636</smbconfoption>
 601 <smbconfcomment>Alternatively, this could be specified as:</smbconfcomment>
 602 <smbconfoption name="idmap backend">ldap:ldaps://ldap-server.quenya.org</smbconfoption>
 603 </smbconfblock>
 604 </example>
 605
 606         <para>
 607 <indexterm><primary>LDAP backends</primary></indexterm>
 608 <indexterm><primary>PADL Software</primary></indexterm>
 609         A network administrator who wants to make significant use of LDAP backends will sooner or later be
 610         exposed to the excellent work done by PADL Software. PADL <ulink url="http://www.padl.com"/> have
 611         produced and released to open source an array of tools that might be of interest. These tools include:
 612         </para>
 613
 614         <itemizedlist>
 615                 <listitem>
 616                 <para>
 617 <indexterm><primary>nss_ldap</primary></indexterm>
 618 <indexterm><primary>NSS</primary></indexterm>
 619 <indexterm><primary>AIX</primary></indexterm>
 620 <indexterm><primary>Linux</primary></indexterm>
 621 <indexterm><primary>LDAP</primary></indexterm>
 622 <indexterm><primary>Solaris</primary></indexterm>
 623 <indexterm><primary>UID</primary></indexterm>
 624 <indexterm><primary>GID</primary></indexterm>
 625                 <emphasis>nss_ldap:</emphasis> An LDAP name service switch (NSS) module to provide native
 626                 name service support for AIX, Linux, Solaris, and other operating systems. This tool
 627                 can be used for centralized storage and retrieval of UIDs and GIDs.
 628                 </para>
 629                 </listitem>
 630
 631                 <listitem>
 632                 <para>
 633 <indexterm><primary>pam_ldap</primary></indexterm>
 634 <indexterm><primary>PAM</primary></indexterm>
 635 <indexterm><primary>LDAP</primary></indexterm>
 636 <indexterm><primary>access authentication</primary></indexterm>
 637                 <emphasis>pam_ldap:</emphasis> A PAM module that provides LDAP integration for UNIX/Linux
 638                 system access authentication.
 639                 </para>
 640                 </listitem>
 641
 642                 <listitem>
 643                 <para>
 644 <indexterm><primary>idmap_ad</primary></indexterm>
 645 <indexterm><primary>IDMAP backend</primary></indexterm>
 646 <indexterm><primary>RFC 2307</primary></indexterm>
 647 <indexterm><primary>PADL</primary></indexterm>
 648                 <emphasis>idmap_ad:</emphasis> An IDMAP backend that supports the Microsoft Services for
 649                 UNIX RFC 2307 schema available from the PADL Web
 650                 <ulink url="http://www.padl.com/download/xad_oss_plugins.tar.gz">site</ulink>.
 651                 </para>
 652                 </listitem>
 653         </itemizedlist>
 654
 655         </sect2>
 656
 657         <sect2>
 658         <title>Comments Regarding LDAP</title>
 659
 660         <para>
 661 <indexterm><primary>LDAP</primary><secondary>directories</secondary></indexterm>
 662 <indexterm><primary>architecture</primary></indexterm>
 663 <indexterm><primary>FIM</primary></indexterm>
 664 <indexterm><primary>SSO</primary></indexterm>
 665         There is much excitement and interest in LDAP directories in the information technology world
 666         today. The LDAP architecture was designed to be highly scalable. It was also designed for
 667         use across a huge number of potential areas of application encompassing a wide range of operating
 668         systems and platforms. LDAP technologies are at the heart of the current generations of Federated
 669         Identity Management (FIM) solutions that can underlie a corporate Single Sign-On (SSO) environment.
 670         </para>
 671
 672         <para>
 673 <indexterm><primary>LDAP</primary></indexterm>
 674 <indexterm><primary>eDirectory</primary></indexterm>
 675 <indexterm><primary>ADS</primary></indexterm>
 676 <indexterm><primary>authentication</primary></indexterm>
 677         LDAP implementations have been built across a wide variety of platforms. It lies at the core of Microsoft
 678         Windows Active Directory services (ADS), Novell's eDirectory, as well as many others. Implementation of the
 679         directory services LDAP involves interaction with legacy as well as new generation applications, all of which
 680         depend on some form of authentication services.
 681         </para>
 682
 683         <para>
 684 <indexterm><primary>LDAP directory</primary></indexterm>
 685 <indexterm><primary>authentication</primary></indexterm>
 686 <indexterm><primary>access controls</primary></indexterm>
 687 <indexterm><primary>intermediate tools</primary></indexterm>
 688 <indexterm><primary>middle-ware</primary></indexterm>
 689 <indexterm><primary>central environment</primary></indexterm>
 690 <indexterm><primary>infrastructure</primary></indexterm>
 691 <indexterm><primary>login shells</primary></indexterm>
 692 <indexterm><primary>mail</primary></indexterm>
 693 <indexterm><primary>messaging systems</primary></indexterm>
 694 <indexterm><primary>quota controls</primary></indexterm>
 695 <indexterm><primary>printing systems</primary></indexterm>
 696 <indexterm><primary>DNS servers</primary></indexterm>
 697 <indexterm><primary>DHCP servers</primary></indexterm>
 698         UNIX services can utilize LDAP directory information for authentication and access controls
 699         through intermediate tools and utilities. The total environment that consists of the LDAP directory
 700         and the middle-ware tools and utilities makes it possible for all user access to the UNIX platform
 701         to be managed from a central environment and yet distributed to wherever the point of need may
 702         be physically located. Applications that benefit from this infrastructure include: UNIX login
 703         shells, mail and messaging systems, quota controls, printing systems, DNS servers, DHCP servers,
 704         and also Samba.
 705         </para>
 706
 707         <para>
 708 <indexterm><primary>LDAP</primary></indexterm>
 709 <indexterm><primary>passdb backend</primary></indexterm>
 710 <indexterm><primary>scalable</primary></indexterm>
 711 <indexterm><primary>SAM backend</primary></indexterm>
 712 <indexterm><primary>LDAP directory</primary></indexterm>
 713 <indexterm><primary>management costs</primary></indexterm>
 714         Many sites are installing LDAP for the first time in order to provide a scalable passdb backend
 715         for Samba. Others are faced with the need to adapt an existing LDAP directory to new uses such
 716         as for the Samba SAM backend. Whatever your particular need and attraction to Samba may be,
 717         decisions made in respect of the design of the LDAP directory structure and its implementation
 718         are of a durable nature for the site. These have far-reaching implications that affect long-term
 719         information systems management costs.
 720         </para>
 721
 722         <para>
 723 <indexterm><primary>LDAP deployment</primary></indexterm>
 724 <indexterm><primary>Directory Information Tree</primary><see>DIT</see></indexterm>
 725         Do not rush into an LDAP deployment. Take the time to understand how the design of the Directory
 726         Information Tree (DIT) may impact current and future site needs, as well as the ability to meet
 727         them. The way that Samba SAM information should be stored within the DIT varies from site to site
 728         and with each implementation new experience is gained. It is well understood by LDAP veterans that
 729         first implementations create awakening, second implementations of LDAP create fear, and
 730         third-generation deployments bring peace and tranquility.
 731         </para>
 732
 733         <sect3>
 734         <title>Caution Regarding LDAP and Samba</title>
 735
 736         <para>
 737 <indexterm><primary>POSIX identity</primary></indexterm>
 738 <indexterm><primary>networking environment</primary></indexterm>
 739 <indexterm><primary>user accounts</primary></indexterm>
 740 <indexterm><primary>group accounts</primary></indexterm>
 741 <indexterm><primary>machine trust accounts</primary></indexterm>
 742 <indexterm><primary>interdomain trust accounts</primary></indexterm>
 743 <indexterm><primary>intermediate information</primary></indexterm>
 744         Samba requires UNIX POSIX identity information as well as a place to store information that is
 745         specific to Samba and the Windows networking environment. The most used information that must
 746         be dealt with includes: user accounts, group accounts, machine trust accounts, interdomain
 747         trust accounts, and intermediate information specific to Samba internals.
 748         </para>
 749
 750         <para>
 751 <indexterm><primary>deployment guidelines</primary></indexterm>
 752 <indexterm><primary>HOWTO documents</primary></indexterm>
 753 <indexterm><primary>LDAP</primary></indexterm>
 754         The example deployment guidelines in this book, as well as other books and HOWTO documents
 755         available from the internet may not fit with established directory designs and implementations.
 756         The existing DIT may not be able to accommodate the simple information layout proposed in common
 757         sources. Additionally, you may find that the common scripts and tools that are used to provision
 758         the LDAP directory for use with Samba may not suit your needs.
 759         </para>
 760
 761         <para>
 762 <indexterm><primary>existing LDAP DIT</primary></indexterm>
 763         It is not uncommon, for sites that have existing LDAP DITs to find necessity to generate a
 764         set of site-specific scripts and utilities to make it possible to deploy Samba within the
 765         scope of site operations. The way that user and group accounts are distributed throughout
 766         the DIT may make this a challenging matter. The solution will, of course, be rewarding, but
 767         the journey to it may be challenging. Take time to understand site needs and do not rush
 768         into deployment.
 769         </para>
 770
 771         <para>
 772 <indexterm><primary>scripts</primary></indexterm>
 773 <indexterm><primary>tools</primary></indexterm>
 774         Above all, do not blindly use scripts and tools that are not suitable for your site. Check
 775         and validate all scripts before you execute them to make sure that the existing infrastructure
 776         will not be damaged by inadvertent use of an inappropriate tool.
 777         </para>
 778
 779         </sect3>
 780
 781         </sect2>
 782
 783         <sect2>
 784         <title>LDAP Directories and Windows Computer Accounts</title>
 785
 786                 <para>
 787 <indexterm><primary>turnkey solution</primary></indexterm>
 788 <indexterm><primary>LDAP.</primary></indexterm>
 789 <indexterm><primary>frustrating experience</primary></indexterm>
 790                 Samba doesn't provide a turnkey solution to LDAP. It is best to deal with the design and
 791                 configuration of an LDAP directory prior to integration with Samba. A working knowledge
 792                 of LDAP makes Samba integration easy, and the lack of a working knowledge of LDAP can make
 793                 it a frustrating experience.
 794                 </para>
 795
 796                 <para>
 797 <indexterm><primary>computer accounts</primary></indexterm>
 798 <indexterm><primary>machine accounts</primary></indexterm>
 799 <indexterm><primary>LDAP</primary></indexterm>
 800                 Computer (machine) accounts can be placed wherever you like in an LDAP directory subject
 801                 to some constraints that are described in this chapter.
 802                 </para>
 803
 804                 <para>
 805 <indexterm><primary>POSIX</primary></indexterm>
 806 <indexterm><primary>sambaSamAccount</primary></indexterm>
 807 <indexterm><primary>computer accounts</primary></indexterm>
 808 <indexterm><primary>machine accounts</primary></indexterm>
 809 <indexterm><primary>Windows NT4/200X</primary></indexterm>
 810 <indexterm><primary>user account</primary></indexterm>
 811 <indexterm><primary>trust accounts</primary></indexterm>
 812                 The POSIX and sambaSamAccount components of computer (machine) accounts are both used by Samba.
 813                 Thus, machine accounts are treated inside Samba in the same way that Windows NT4/200X treats
 814                 them. A user account and a machine account are indistinquishable from each other, except that
 815                 the machine account ends in a $ character, as do trust accounts.
 816                 </para>
 817
 818                 <para>
 819 <indexterm><primary>user</primary></indexterm>
 820 <indexterm><primary>group</primary></indexterm>
 821 <indexterm><primary>machine</primary></indexterm>
 822 <indexterm><primary>trust</primary></indexterm>
 823 <indexterm><primary>UID</primary></indexterm>
 824                 The need for Windows user, group, machine, trust, and other accounts to be tied to a valid UNIX
 825                 UID is a design decision that was made a long way back in the history of Samba development. It
 826                 is unlikely that this decision will be reversed or changed during the remaining life of the
 827                 Samba-3.x series.
 828                 </para>
 829
 830                 <para>
 831 <indexterm><primary>UID</primary></indexterm>
 832 <indexterm><primary>SID</primary></indexterm>
 833 <indexterm><primary>NSS</primary></indexterm>
 834                 The resolution of a UID from the Windows SID is achieved within Samba through a mechanism that
 835                 must refer back to the host operating system on which Samba is running. The NSS is the preferred
 836                 mechanism that shields applications (like Samba) from the need to know everything about every
 837                 host OS it runs on.
 838                 </para>
 839
 840                 <para>
 841 <indexterm><primary>UID</primary></indexterm>
 842 <indexterm><primary>passwd</primary></indexterm>
 843 <indexterm><primary>shadow</primary></indexterm>
 844 <indexterm><primary>group</primary></indexterm>
 845 <indexterm><primary>NSS</primary></indexterm>
 846 <indexterm><primary>winbindd</primary></indexterm>
 847 <indexterm><primary>LDAP</primary></indexterm>
 848                 Samba asks the host OS to provide a UID via the <quote>passwd</quote>, <quote>shadow</quote>,
 849                 and <quote>group</quote> facilities in the NSS control (configuration) file. The best tool
 850                 for achieving this is left up to the UNIX administrator to determine. It is not imposed by
 851                 Samba. Samba provides winbindd with its support libraries as one method. It is
 852                 possible to do this via LDAP, and for that Samba provides the appropriate hooks so that
 853                 all account entities can be located in an LDAP directory.
 854                 </para>
 855
 856                 <para>
 857 <indexterm><primary>PADL</primary></indexterm>
 858 <indexterm><primary>nss_ldap</primary></indexterm>
 859 <indexterm><primary>UID</primary></indexterm>
 860 <indexterm><primary>LDAP</primary></indexterm>
 861 <indexterm><primary>documentation</primary></indexterm>
 862                 For many the weapon of choice is to use the PADL nss_ldap utility. This utility must
 863                 be configured so that computer accounts can be resolved to a POSIX/UNIX account UID. That
 864                 is fundamentally an LDAP design question.  The information provided on the Samba list and
 865                 in the documentation is directed at providing working examples only. The design
 866                 of an LDAP directory is a complex subject that is beyond the scope of this documentation.
 867                 </para>
 868
 869         </sect2>
 870
 871 </sect1>
 872
 873 <sect1 id="acctmgmttools">
 874 <title>Account Management Tools</title>
 875
 876 <para>
 877 <indexterm><primary>pdbedit</primary></indexterm>
 878 <indexterm><primary>machine accounts</primary></indexterm>
 879 <indexterm><primary>management tools</primary></indexterm>
 880 Samba provides two tools for management of user and machine accounts:
 881 <command>smbpasswd</command> and <command>pdbedit</command>.
 882 </para>
 883
 884 <para>
 885 <indexterm><primary>pdbedit</primary></indexterm>
 886 <indexterm><primary>password aging</primary></indexterm>
 887 <indexterm><primary>failed logins</primary></indexterm>
 888 The <command>pdbedit</command> can be used to manage account policies in addition to
 889 Samba user account information. The policy management capability is used to administer
 890 domain default settings for password aging and management controls to handle failed login
 891 attempts.
 892 </para>
 893
 894 <para>
 895 <indexterm><primary>smbpasswd</primary></indexterm>
 896 <indexterm><primary>storage mechanism</primary></indexterm>
 897 <indexterm><primary>SambaSAMAccount</primary></indexterm>
 898 <indexterm><primary>net</primary></indexterm>
 899 Some people are confused when reference is made to <literal>smbpasswd</literal> because the
 900 name refers to a storage mechanism for SambaSAMAccount information, but it is also the name
 901 of a utility tool. That tool is destined to eventually be replaced by new functionality that
 902 is being added to the <command>net</command> toolset (see <link linkend="NetCommand">the Net Command</link>.
 903 </para>
 904
 905         <sect2>
 906         <title>The <command>smbpasswd</command> Tool</title>
 907
 908                 <para>
 909 <indexterm><primary>smbpasswd</primary></indexterm>
 910 <indexterm><primary>passwd</primary></indexterm>
 911 <indexterm><primary>yppasswd</primary></indexterm>
 912 <indexterm><primary>passdb backend</primary></indexterm>
 913 <indexterm><primary>storage methods</primary></indexterm>
 914                 The <command>smbpasswd</command> utility is similar to the <command>passwd</command>
 915                 and <command>yppasswd</command> programs. It maintains the two 32 byte password
 916                 fields in the passdb backend. This utility operates independently of the actual
 917                 account and password storage methods used (as specified by the <parameter>passdb
 918                 backend</parameter> in the &smb.conf; file.
 919                 </para>
 920
 921                 <para>
 922 <indexterm><primary>smbpasswd</primary></indexterm>
 923 <indexterm><primary>client-server mode</primary></indexterm>
 924                 <command>smbpasswd</command> works in a client-server mode where it contacts the
 925                 local smbd to change the user's password on its behalf. This has enormous benefits.
 926                 </para>
 927
 928                 <para>
 929 <indexterm><primary>smbpasswd</primary></indexterm>
 930 <indexterm><primary>change passwords</primary></indexterm>
 931                 <command>smbpasswd</command> has the capability to change passwords on Windows NT
 932                 servers (this only works when the request is sent to the NT PDC if changing an NT
 933                 domain user's password).
 934                 </para>
 935
 936                 <para>
 937                 <indexterm><primary>user management</primary></indexterm>
 938                 <indexterm><primary>user account</primary><secondary>Adding/Deleting</secondary></indexterm>
 939                 <command>smbpasswd</command> can be used to:
 940                 </para>
 941
 942                 <itemizedlist>
 943                         <listitem><para><emphasis>add</emphasis> user or machine accounts.</para></listitem>
 944                         <listitem><para><emphasis>delete</emphasis> user or machine accounts.</para></listitem>
 945                         <listitem><para><emphasis>enable</emphasis> user or machine accounts.</para></listitem>
 946                         <listitem><para><emphasis>disable</emphasis> user or machine accounts.</para></listitem>
 947                         <listitem><para><emphasis>set to NULL</emphasis> user passwords.</para></listitem>
 948                         <listitem><para><emphasis>manage</emphasis> interdomain trust accounts.</para></listitem>
 949                 </itemizedlist>
 950
 951                 <para>
 952                 To run smbpasswd as a normal user, just type:
 953                 </para>
 954
 955                 <para>
 956 <screen>
 957 &prompt;<userinput>smbpasswd</userinput>
 958 <prompt>Old SMB password: </prompt><userinput><replaceable>secret</replaceable></userinput>
 959 </screen>
 960                 For <replaceable>secret</replaceable>, type the old value here or press return if
 961                 there is no old password.
 962 <screen>
 963 <prompt>New SMB Password: </prompt><userinput><replaceable>new secret</replaceable></userinput>
 964 <prompt>Repeat New SMB Password: </prompt><userinput><replaceable>new secret</replaceable></userinput>
 965 </screen>
 966                 </para>
 967
 968                 <para>
 969                 If the old value does not match the current value stored for that user, or the two
 970                 new values do not match each other, then the password will not be changed.
 971                 </para>
 972
 973                 <para>
 974 <indexterm><primary>SMB password</primary></indexterm>
 975                 When invoked by an ordinary user, the command will allow only the user to change his or her own
 976                 SMB password.
 977                 </para>
 978
 979                 <para>
 980 <indexterm><primary>smbpasswd</primary></indexterm>
 981 <indexterm><primary>SMB password</primary></indexterm>
 982                 When run by root, <command>smbpasswd</command> may take an optional argument specifying
 983                 the username whose SMB password you wish to change. When run as root, <command>smbpasswd</command>
 984                 does not prompt for or check the old password value, thus allowing root to set passwords
 985                 for users who have forgotten their passwords.
 986                 </para>
 987
 988                 <para>
 989 <indexterm><primary>smbpasswd</primary></indexterm>
 990 <indexterm><primary>passwd</primary></indexterm>
 991 <indexterm><primary>yppasswd</primary></indexterm>
 992 <indexterm><primary>change capabilities</primary></indexterm>
 993                 <command>smbpasswd</command> is designed to work in the way familiar to UNIX
 994                 users who use the <command>passwd</command> or <command>yppasswd</command> commands.
 995                 While designed for administrative use, this tool provides essential user-level
 996                 password change capabilities.
 997                 </para>
 998
 999                 <para>
1000 <indexterm><primary>smbpasswd</primary></indexterm>
1001                 For more details on using <command>smbpasswd</command>, refer to the man page (the
1002                 definitive reference).
1003                 </para>
1004         </sect2>
1005
1006         <sect2 id="pdbeditthing">
1007         <title>The <command>pdbedit</command> Tool</title>
1008
1009                 <para>
1010                 <indexterm><primary>pdbedit</primary></indexterm>
1011                 <indexterm><primary>User Management</primary></indexterm>
1012                 <indexterm><primary>account policy</primary></indexterm>
1013                 <indexterm><primary>User Accounts</primary><secondary>Adding/Deleting</secondary></indexterm>
1014                 <command>pdbedit</command> is a tool that can be used only by root. It is used to
1015                 manage the passdb backend, as well as domain-wide account policy settings. <command>pdbedit</command>
1016                 can be used to:
1017                 </para>
1018
1019                 <itemizedlist>
1020                         <listitem><para>add, remove, or modify user accounts.</para></listitem>
1021                         <listitem><para>list user accounts.</para></listitem>
1022                         <listitem><para>migrate user accounts.</para></listitem>
1023                         <listitem><para>migrate group accounts.</para></listitem>
1024                         <listitem><para>manage account policies.</para></listitem>
1025                         <listitem><para>manage domain access policy settings.</para></listitem>
1026                 </itemizedlist>
1027
1028                 <para>
1029                 <indexterm><primary>Sarbanes-Oxley</primary></indexterm>
1030                 Under the terms of the Sarbanes-Oxley Act of 2002, American businessies and organizations are mandated to
1031                 implement a series of <literal>internal controls</literal> and procedures to communicate, store,
1032                 and protect financial data. The Sarbanes-Oxley Act has far reaching implications in respect of:
1033                 </para>
1034
1035                 <orderedlist>
1036                         <listitem><para>Who has access to information systems that store financial data.</para></listitem>
1037                         <listitem><para>How personal and finacial information is treated among employees and business
1038                                 partners.</para></listitem>
1039                         <listitem><para>How security vulnerabilities are managed.</para></listitem>
1040                         <listitem><para>Security and patch level maintenance for all information systems.</para></listitem>
1041                         <listitem><para>How information systems changes are documented and tracked.</para></listitem>
1042                         <listitem><para>How information access controls are implemented and managed.</para></listitem>
1043                         <listitem><para>Auditability of all information systems in respect of change and security.</para></listitem>
1044                         <listitem><para>Disciplinary procedures and controls to ensure privacy.</para></listitem>
1045                 </orderedlist>
1046
1047                 <para>
1048                 <indexterm><primary>accountability</primary></indexterm>
1049                 <indexterm><primary>compliance</primary></indexterm>
1050                 In short, the Sarbanes-Oxley Act of 2002 is an instrument that enforces accountability in respect of
1051                 business related information systems so as to ensure the compliance of all information systems that
1052                 are used to store personal information and particularly for financial records processing. Similar
1053                 accountabilities are being demanded around the world.
1054                 </para>
1055
1056                 <para>
1057                 <indexterm><primary>laws</primary></indexterm>
1058                 <indexterm><primary>regulations</primary></indexterm>
1059                 <indexterm><primary>pdbedit</primary></indexterm>
1060                 <indexterm><primary>access controls</primary></indexterm>
1061                 <indexterm><primary>manage accounts</primary></indexterm>
1062                 The need to be familiar with the Samba tools and facilities that permit information systems operation
1063                 in compliance with government laws and regulations is clear to all. The <command>pdbedit</command> is
1064                 currently the only Samba tool that provides the capacity to manage account and systems access controls
1065                 and policies. During the remaining life-cycle of the Samba-3 series it is possible the new tools may
1066                 be implemented to aid in this important area.
1067                 </para>
1068
1069                 <para>
1070                 Domain global policy controls available in Windows NT4 compared with Samba
1071                 is shown in <link linkend="policycontrols">NT4 Domain v's Samba Policy Controls</link>.
1072                 </para>
1073
1074                 <table id="policycontrols">
1075                 <title>NT4 Domain v's Samba Policy Controls</title>
1076             <tgroup cols="5">
1077                 <colspec align="left" colwidth="2*"/>
1078                 <colspec align="left" colwidth="2*"/>
1079                 <colspec align="center" colwidth="1*"/>
1080                 <colspec align="center" colwidth="1*"/>
1081                 <colspec align="center" colwidth="1*"/>
1082                 <thead>
1083                     <row>
1084                         <entry><para>NT4 policy Name</para></entry>
1085                         <entry><para>Samba Policy Name</para></entry>
1086                         <entry><para>NT4 Range</para></entry>
1087                         <entry><para>Samba Range</para></entry>
1088                         <entry><para>Samba Default</para></entry>
1089                     </row>
1090                 </thead>
1091                 <tbody>
1092                     <row>
1093                                         <entry><para>Maximum Password Age</para></entry>
1094                                         <entry><para>maximum password age</para></entry>
1095                                         <entry><para>0 - 999 (days)</para></entry>
1096                                         <entry><para>0 - 4294967295 (sec)</para></entry>
1097                                         <entry><para>4294967295</para></entry>
1098                     </row>
1099                     <row>
1100                                         <entry><para>Minimum Password Age</para></entry>
1101                                         <entry><para>minimum password age</para></entry>
1102                                         <entry><para>0 - 999 (days)</para></entry>
1103                                         <entry><para>0 - 4294967295 (sec)</para></entry>
1104                                         <entry><para>0</para></entry>
1105                     </row>
1106                     <row>
1107                                         <entry><para>Mimimum Password Length</para></entry>
1108                                         <entry><para>min password length</para></entry>
1109                                         <entry><para>1 - 14 (Chars)</para></entry>
1110                                         <entry><para>0 - 4294967295 (Chars)</para></entry>
1111                                         <entry><para>5</para></entry>
1112                     </row>
1113                     <row>
1114                                         <entry><para>Password Uniqueness</para></entry>
1115                                         <entry><para>password history</para></entry>
1116                                         <entry><para>0 - 23 (#)</para></entry>
1117                                         <entry><para>0 - 4294967295 (#)</para></entry>
1118                                         <entry><para>0</para></entry>
1119                     </row>
1120                     <row>
1121                                         <entry><para>Account Lockout - Reset count after</para></entry>
1122                                         <entry><para>reset count minutes</para></entry>
1123                                         <entry><para>1 - 99998 (min)</para></entry>
1124                                         <entry><para>0 - 4294967295 (min)</para></entry>
1125                                         <entry><para>30</para></entry>
1126                     </row>
1127                     <row>
1128                                         <entry><para>Lockout after bad logon attempts</para></entry>
1129                                         <entry><para>bad lockout attempt</para></entry>
1130                                         <entry><para>0 - 998 (#)</para></entry>
1131                                         <entry><para>0 - 4294967295 (#)</para></entry>
1132                                         <entry><para>0</para></entry>
1133                     </row>
1134                     <row>
1135                                         <entry><para>*** Not Known ***</para></entry>
1136                                         <entry><para>disconnect time</para></entry>
1137                                         <entry><para>TBA</para></entry>
1138                                         <entry><para>0 - 4294967295</para></entry>
1139                                         <entry><para>0</para></entry>
1140                     </row>
1141                     <row>
1142                                         <entry><para>Lockout Duration</para></entry>
1143                                         <entry><para>lockout duration</para></entry>
1144                                         <entry><para>1 - 99998 (min)</para></entry>
1145                                         <entry><para>0 - 4294967295 (min)</para></entry>
1146                                         <entry><para>30</para></entry>
1147                     </row>
1148                     <row>
1149                                         <entry><para>Users must log on in order to change password</para></entry>
1150                                         <entry><para>user must logon to change password</para></entry>
1151                                         <entry><para>0/1</para></entry>
1152                                         <entry><para>0 - 4294967295</para></entry>
1153                                         <entry><para>0</para></entry>
1154                     </row>
1155                     <row>
1156                                         <entry><para>*** Registry Setting ***</para></entry>
1157                                         <entry><para>refuse machine password change</para></entry>
1158                                         <entry><para>0/1</para></entry>
1159                                         <entry><para>0 - 4294967295</para></entry>
1160                                         <entry><para>0</para></entry>
1161                     </row>
1162                                 </tbody>
1163                         </tgroup>
1164                 </table>
1165
1166                 <para>
1167                 <indexterm><primary>pdbedit</primary></indexterm>
1168 <indexterm><primary>policy settings</primary></indexterm>
1169 <indexterm><primary>account security</primary></indexterm>
1170 <indexterm><primary>smbpasswd</primary></indexterm>
1171                 The <command>pdbedit</command> tool is the only one that can manage the account
1172                 security and policy settings. It is capable of all operations that smbpasswd can
1173                 do as well as a superset of them.
1174                 </para>
1175
1176                 <para>
1177                 <indexterm><primary>pdbedit</primary></indexterm>
1178 <indexterm><primary>account migration</primary></indexterm>
1179 <indexterm><primary>passdb backend</primary></indexterm>
1180                 One particularly important purpose of the <command>pdbedit</command> is to allow
1181                 the migration of account information from one passdb backend to another. See the
1182                 <link linkend="XMLpassdb">XML</link> password backend section of this chapter.
1183                 </para>
1184
1185                 <sect3>
1186                 <title>User Account Management</title>
1187
1188                 <para>
1189 <indexterm><primary>pdbedit</primary></indexterm>
1190 <indexterm><primary>smbpasswd</primary></indexterm>
1191 <indexterm><primary>system accounts</primary></indexterm>
1192 <indexterm><primary>user account</primary></indexterm>
1193 <indexterm><primary>domain user manager</primary></indexterm>
1194 <indexterm><primary>add user script</primary></indexterm>
1195 <indexterm><primary>interface scripts</primary></indexterm>
1196                 The <command>pdbedit</command> tool, like the <command>smbpasswd</command> tool, requires
1197                 that a POSIX user account already exists in the UNIX/Linux system accounts database (backend).
1198                 Neither tool will call out to the operating system to create a user account because this is
1199                 considered to be the responsibility of the system administrator. When the Windows NT4 domain
1200                 user manager is used to add an account, Samba will implement the <literal>add user script</literal>
1201                 (as well as the other interface scripts) to ensure that user, group and machine accounts are
1202                 correctly created and changed. The use of the <command>pdbedit</command> tool does not
1203                 make use of these interface scripts.
1204                 </para>
1205
1206                 <para>
1207 <indexterm><primary>pdbedit</primary></indexterm>
1208 <indexterm><primary>POSIX account</primary></indexterm>
1209                 Before attempting to use the <command>pdbedit</command> tool to manage user and machine
1210                 accounts, make certain that a system (POSIX) account has already been created.
1211                 </para>
1212
1213                 <sect4>
1214                 <title>Listing User and Machine Accounts</title>
1215
1216                 <para>
1217 <indexterm><primary>tdbsam</primary></indexterm>
1218 <indexterm><primary>password backend</primary></indexterm>
1219                 The following is an example of the user account information that is stored in
1220                 a tdbsam password backend. This listing was produced by running:
1221 <screen>
1222 &prompt;<userinput>pdbedit -Lv met</userinput>
1223 UNIX username:        met
1224 NT username:          met
1225 Account Flags:        [U          ]
1226 User SID:             S-1-5-21-1449123459-1407424037-3116680435-2004
1227 Primary Group SID:    S-1-5-21-1449123459-1407424037-3116680435-1201
1228 Full Name:            Melissa E Terpstra
1229 Home Directory:       \\frodo\met\Win9Profile
1230 HomeDir Drive:        H:
1231 Logon Script:         scripts\logon.bat
1232 Profile Path:         \\frodo\Profiles\met
1233 Domain:               &example.workgroup;
1234 Account desc:
1235 Workstations:         melbelle
1236 Munged dial:
1237 Logon time:           0
1238 Logoff time:          Mon, 18 Jan 2038 20:14:07 GMT
1239 Kickoff time:         Mon, 18 Jan 2038 20:14:07 GMT
1240 Password last set:    Sat, 14 Dec 2002 14:37:03 GMT
1241 Password can change:  Sat, 14 Dec 2002 14:37:03 GMT
1242 Password must change: Mon, 18 Jan 2038 20:14:07 GMT
1243 </screen>
1244                 </para>
1245
1246                 <para>
1247 <indexterm><primary>smbpasswd format</primary></indexterm>
1248                 Accounts can also be listed in the older <literal>smbpasswd</literal> format:
1249 <screen>
1250 &rootprompt;<userinput>pdbedit -Lw</userinput>
1251 root:0:84B0D8E14D158FF8417EAF50CFAC29C3:
1252      AF6DD3FD4E2EA8BDE1695A3F05EFBF52:[U          ]:LCT-42681AB8:
1253 jht:1000:6BBC4159020A52741486235A2333E4D2:
1254      CC099521AD554A3C3CF2556274DBCFBC:[U          ]:LCT-40D75B5B:
1255 rcg:1002:E95D4331A6F23AF8AAD3B435B51404EE:
1256      BB0F2C39B04CA6100F0E535DF8314B43:[U          ]:LCT-40D7C5A3:
1257 afw:1003:1AAFA7F9F6DC1DEAAAD3B435B51404EE:
1258      CE92C2F9471594CDC4E7860CA6BC62DB:[T          ]:LCT-40DA501F:
1259 met:1004:A2848CB7E076B435AAD3B435B51404EE:
1260      F25F5D3405085C555236B80B7B22C0D2:[U          ]:LCT-4244FAB8:
1261 aurora$:1005:060DE593EA638B8ACC4A19F14D2FF2BB:
1262      060DE593EA638B8ACC4A19F14D2FF2BB:[W          ]:LCT-4173E5CC:
1263 temptation$:1006:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:
1264      A96703C014E404E33D4049F706C45EE9:[W          ]:LCT-42BF0C57:
1265 vaioboss$:1001:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:
1266      88A30A095160072784C88F811E89F98A:[W          ]:LCT-41C3878D:
1267 frodo$:1008:15891DC6B843ECA41249940C814E316B:
1268      B68EADCCD18E17503D3DAD3E6B0B9A75:[W          ]:LCT-42B7979F:
1269 marvel$:1011:BF709959C3C94E0B3958B7B84A3BB6F3:
1270      C610EFE9A385A3E8AA46ADFD576E6881:[W          ]:LCT-40F07A4
1271 </screen>
1272                 </para>
1273
1274                 </sect4>
1275
1276                 <sect4>
1277                 <title>Adding User Accounts</title>
1278
1279                 <para>
1280 <indexterm><primary>pdbedit</primary></indexterm>
1281 <indexterm><primary>add a user account</primary></indexterm>
1282 <indexterm><primary>standalone server</primary></indexterm>
1283 <indexterm><primary>domain</primary></indexterm>
1284 <indexterm><primary>SambaSAMAccount</primary></indexterm>
1285                 The <command>pdbedit</command> can be used to add a user account to a standalone server
1286                 or to a domain. In the example shown here the account for the user <literal>vlaan</literal>
1287                 has been created before attempting to add the SambaSAMAccount.
1288 <screen>
1289 &rootprompt; pdbedit -a vlaan
1290 new password: secretpw
1291 retype new password: secretpw
1292 Unix username:        vlaan
1293 NT username:          vlaan
1294 Account Flags:        [U          ]
1295 User SID:             S-1-5-21-726309263-4128913605-1168186429-3014
1296 Primary Group SID:    S-1-5-21-726309263-4128913605-1168186429-513
1297 Full Name:            Victor Laan
1298 Home Directory:       \\frodo\vlaan
1299 HomeDir Drive:        H:
1300 Logon Script:         scripts\logon.bat
1301 Profile Path:         \\frodo\profiles\vlaan
1302 Domain:               &example.workgroup;
1303 Account desc:         Guest User
1304 Workstations:
1305 Munged dial:
1306 Logon time:           0
1307 Logoff time:          Mon, 18 Jan 2038 20:14:07 GMT
1308 Kickoff time:         Mon, 18 Jan 2038 20:14:07 GMT
1309 Password last set:    Wed, 29 Jun 2005 19:35:12 GMT
1310 Password can change:  Wed, 29 Jun 2005 19:35:12 GMT
1311 Password must change: Mon, 18 Jan 2038 20:14:07 GMT
1312 Last bad password   : 0
1313 Bad password count  : 0
1314 Logon hours         : FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
1315 </screen>
1316                 </para>
1317
1318                 </sect4>
1319
1320                 <sect4>
1321                 <title>Deleting Accounts</title>
1322
1323                 <para>
1324 <indexterm><primary>account deleted</primary></indexterm>
1325 <indexterm><primary>SambaSAMAccount</primary></indexterm>
1326 <indexterm><primary>pdbedit</primary></indexterm>
1327 <indexterm><primary>passdb backend</primary></indexterm>
1328                 An account can be deleted from the SambaSAMAccount database
1329 <screen>
1330 &rootprompt; pdbedit -x vlaan
1331 </screen>
1332                 The account is removed without further screen output. The account is removed only from the
1333                 SambaSAMAccount (passdb backend) database, it is not removed from the UNIX account backend.
1334                 </para>
1335
1336                 <para>
1337 <indexterm><primary>delete user script</primary></indexterm>
1338 <indexterm><primary>pdbedit</primary></indexterm>
1339                 The use of the NT4 domain user manager to delete an account will trigger the <parameter>delete user
1340                 script</parameter>, but not the <command>pdbedit</command> tool.
1341                 </para>
1342
1343                 </sect4>
1344
1345                 <sect4>
1346                 <title>Changing User Accounts</title>
1347
1348                 <para>
1349 <indexterm><primary>pdbedit</primary></indexterm>
1350                 Refer to the <command>pdbedit</command> man page for a full synopsis of all operations
1351                 that are available with this tool.
1352                 </para>
1353
1354                 <para>
1355 <indexterm><primary>pdbedit</primary></indexterm>
1356                 An example of a simple change in the user account information is the change of the full name
1357                 information shown here:
1358 <screen>
1359 &rootprompt; pdbedit -r --fullname="Victor Aluicious Laan" vlaan
1360 ...
1361 Primary Group SID:    S-1-5-21-726309263-4128913605-1168186429-513
1362 Full Name:            Victor Aluicious Laan
1363 Home Directory:       \\frodo\vlaan
1364 ...
1365 </screen>
1366                 </para>
1367
1368                 <para>
1369 <indexterm><primary>grace time</primary></indexterm>
1370 <indexterm><primary>password expired</primary></indexterm>
1371 <indexterm><primary>expired password</primary></indexterm>
1372                 Let us assume for a moment that a user's password has expired and the user is unable to
1373                 change the password at this time. It may be necessary to give the user additional grace time
1374                 so that it is possible to continue to work with the account and the original password. This
1375                 demonstrates how the password expiration settings may be updated
1376 <screen>
1377 &rootprompt; pdbedit -Lv vlaan
1378 ...
1379 Password last set:    Sun, 09 Sep 2001 22:21:40 GMT
1380 Password can change:  Thu, 03 Jan 2002 15:08:35 GMT
1381 Password must change: Thu, 03 Jan 2002 15:08:35 GMT
1382 Last bad password   : Thu, 03 Jan 2002 15:08:35 GMT
1383 Bad password count  : 2
1384 ...
1385 </screen>
1386 <indexterm><primary>bad logon attempts</primary></indexterm>
1387 <indexterm><primary>lock the account</primary></indexterm>
1388                 The user has recorded 2 bad logon attempts and the next will lock the account, but the
1389                 password is also expired. Here is how this account can be reset:
1390 <screen>
1391 &rootprompt; pdbedit -z vlaan
1392 ...
1393 Password last set:    Sun, 09 Sep 2001 22:21:40 GMT
1394 Password can change:  Thu, 03 Jan 2002 15:08:35 GMT
1395 Password must change: Thu, 03 Jan 2002 15:08:35 GMT
1396 Last bad password   : 0
1397 Bad password count  : 0
1398 ...
1399 </screen>
1400                 The <literal>Password must change:</literal> parameter can be reset like this:
1401 <screen>
1402 &rootprompt; pdbedit --pwd-must-change-time=1200000000 vlaan
1403 ...
1404 Password last set:    Sun, 09 Sep 2001 22:21:40 GMT
1405 Password can change:  Thu, 03 Jan 2002 15:08:35 GMT
1406 Password must change: Thu, 10 Jan 2008 14:20:00 GMT
1407 ...
1408 </screen>
1409                 Another way to use this tools is to set the date like this:
1410 <screen>
1411 &rootprompt; pdbedit --pwd-must-change-time="2010-01-01" \
1412               --time-format="%Y-%m-%d" vlaan
1413 ...
1414 Password last set:    Sun, 09 Sep 2001 22:21:40 GMT
1415 Password can change:  Thu, 03 Jan 2002 15:08:35 GMT
1416 Password must change: Fri, 01 Jan 2010 00:00:00 GMT
1417 ...
1418 </screen>
1419 <indexterm><primary>strptime</primary></indexterm>
1420 <indexterm><primary>time format</primary></indexterm>
1421                 Refer to the strptime man page for specific time format information.
1422                 </para>
1423
1424                 <para>
1425 <indexterm><primary>pdbedit</primary></indexterm>
1426 <indexterm><primary>SambaSAMAccount</primary></indexterm>
1427                 Please refer to the pdbedit man page for further information relating to SambaSAMAccount
1428                 management.
1429                 </para>
1430
1431                 </sect4>
1432
1433                 <sect4>
1434                 <title>Domain Account Policy Managment</title>
1435
1436                 <para>
1437 <indexterm><primary>domain account access policies</primary></indexterm>
1438 <indexterm><primary>access policies</primary></indexterm>
1439                 To view the domain account access policies that may be configured execute:
1440 <screen>
1441 &rootprompt; pdbedit -P ?
1442 No account policy by that name
1443 Account policy names are :
1444 min password length
1445 password history
1446 user must logon to change password
1447 maximum password age
1448 minimum password age
1449 lockout duration
1450 reset count minutes
1451 bad lockout attempt
1452 disconnect time
1453 refuse machine password change
1454 </screen>
1455                 </para>
1456
1457                 <para>
1458                 Commands will be executed to establish controls for our domain as follows:
1459                 </para>
1460
1461                 <orderedlist>
1462                         <listitem><para>min password length = 8 characters.</para></listitem>
1463                         <listitem><para>password history = last 4 passwords.</para></listitem>
1464                         <listitem><para>maximum password age = 90 days.</para></listitem>
1465                         <listitem><para>minimum password age = 7 days.</para></listitem>
1466                         <listitem><para>bad lockout attempt = 8 bad logon attempts.</para></listitem>
1467                         <listitem><para>lockout duration = forever, account must be manually reenabled.</para></listitem>
1468                 </orderedlist>
1469
1470                 <para>
1471                 The following command execution will achieve these settings:
1472 <screen>
1473 &rootprompt; pdbedit -P "min password length" -C 8
1474 account policy value for min password length was 5
1475 account policy value for min password length is now 8
1476 &rootprompt; pdbedit -P "password history" -C 4
1477 account policy value for password history was 0
1478 account policy value for password history is now 4
1479 &rootprompt; pdbedit -P "maximum password age" -C 90
1480 account policy value for maximum password age was 4294967295
1481 account policy value for maximum password age is now 90
1482 &rootprompt; pdbedit -P "minimum password age" -C 7
1483 account policy value for minimum password age was 0
1484 account policy value for minimum password age is now 7
1485 &rootprompt; pdbedit -P "bad lockout attempt" -C 8
1486 account policy value for bad lockout attempt was 0
1487 account policy value for bad lockout attempt is now 8
1488 &rootprompt; pdbedit -P "lockout duration" -C -1
1489 account policy value for lockout duration was 30
1490 account policy value for lockout duration is now 4294967295
1491 </screen>
1492                 </para>
1493
1494 <note><para>
1495 To set the maximum (infinite) lockout time use the value of -1.
1496 </para></note>
1497
1498 <warning><para>
1499 Account policies must be set individually on each PDC and BDC. At this time (Samba 3.0.11 to Samba 3.0.14a)
1500 account policies are not replicated automatically. This may be fixed before Samba 3.0.20 ships or some
1501 time there after.
1502 </para></warning>
1503
1504                 </sect4>
1505
1506                 </sect3>
1507
1508                 <sect3>
1509                 <title>Account Migration</title>
1510
1511                 <para>
1512                 <indexterm><primary>pdbedit</primary></indexterm>
1513 <indexterm><primary>migrate accounts</primary></indexterm>
1514 <indexterm><primary>authentication</primary></indexterm>
1515                 The <command>pdbedit</command> tool allows migration of authentication (account)
1516                 databases from one backend to another. For example, to migrate accounts from an
1517                 old <filename>smbpasswd</filename> database to a <parameter>tdbsam</parameter>
1518                 backend:
1519                 </para>
1520
1521                 <procedure>
1522                         <step><para>
1523                         Set the <smbconfoption name="passdb backend">tdbsam, smbpasswd</smbconfoption>.
1524                         </para></step>
1525
1526                         <step><para>
1527 <indexterm><primary>pdbedit</primary></indexterm>
1528                         Execute:
1529 <screen>
1530 &rootprompt;<userinput>pdbedit -i smbpasswd -e tdbsam</userinput>
1531 </screen>
1532                         </para></step>
1533
1534                         <step><para>
1535 <indexterm><primary>smbpasswd</primary></indexterm>
1536                         Remove the <parameter>smbpasswd</parameter> from the passdb backend
1537                         configuration in &smb.conf;.
1538                         </para></step>
1539                 </procedure>
1540
1541         </sect3>
1542         </sect2>
1543 </sect1>
1544
1545 <sect1>
1546 <title>Password Backends</title>
1547
1548 <para>
1549 <indexterm><primary>account database</primary></indexterm>
1550 <indexterm><primary>SMB/CIFS server</primary></indexterm>
1551 Samba offers the greatest flexibility in backend account database design of any SMB/CIFS server
1552 technology available today. The flexibility is immediately obvious as one begins to explore this
1553 capability.
1554 </para>
1555
1556 <para>
1557 <indexterm><primary>multiple backends</primary></indexterm>
1558 <indexterm><primary>tdbsam databases</primary></indexterm>
1559 It is possible to specify not only multiple password backends, but even multiple
1560 backends of the same type. For example, to use two different <literal>tdbsam</literal> databases:
1561
1562 <smbconfblock>
1563 <smbconfoption name="passdb backend">tdbsam:/etc/samba/passdb.tdb tdbsam:/etc/samba/old-passdb.tdb</smbconfoption>
1564 </smbconfblock>
1565
1566 What is possible is not always sensible. Be careful to avoid complexity to the point that it
1567 may be said that the solution is <quote>too clever by half!</quote>
1568 </para>
1569
1570
1571         <sect2>
1572         <title>Plaintext</title>
1573
1574                 <para>
1575 <indexterm><primary>user database</primary></indexterm>
1576 <indexterm><primary>/etc/samba/smbpasswd</primary></indexterm>
1577 <indexterm><primary>/etc/smbpasswd</primary></indexterm>
1578 <indexterm><primary>password encryption</primary></indexterm>
1579 <indexterm><primary>/etc/passwd</primary></indexterm>
1580 <indexterm><primary>PAM</primary></indexterm>
1581                 Older versions of Samba retrieved user information from the UNIX user database
1582                 and eventually some other fields from the file <filename>/etc/samba/smbpasswd</filename>
1583                 or <filename>/etc/smbpasswd</filename>. When password encryption is disabled, no
1584                 SMB-specific data is stored at all. Instead, all operations are conducted via the way
1585                 that the Samba host OS will access its <filename>/etc/passwd</filename> database.
1586                 On most Linux systems, for example, all user and group resolution is done via PAM.
1587                 </para>
1588
1589         </sect2>
1590
1591         <sect2>
1592         <title>smbpasswd: Encrypted Password Database</title>
1593
1594                 <para>
1595                 <indexterm><primary>SAM backend</primary><secondary>smbpasswd</secondary></indexterm>
1596 <indexterm><primary>user account</primary></indexterm>
1597 <indexterm><primary>LM/NT password hashes</primary></indexterm>
1598 <indexterm><primary>smbpasswd</primary></indexterm>
1599                 Traditionally, when configuring <smbconfoption name="encrypt passwords">yes</smbconfoption>
1600                 in Samba's &smb.conf; file, user account information such as username, LM/NT password hashes,
1601                 password change times, and account flags have been stored in the <filename>smbpasswd(5)</filename>
1602                 file. There are several disadvantages to this approach for sites with large numbers of users
1603                 (counted in the thousands).
1604                 </para>
1605
1606                 <itemizedlist>
1607                 <listitem><para>
1608 <indexterm><primary>lookups</primary></indexterm>
1609                 The first problem is that all lookups must be performed sequentially. Given that
1610                 there are approximately two lookups per domain logon (one during intial logon validation
1611                 and one for a session connection setup, such as when mapping a network drive or printer), this
1612                 is a performance bottleneck for large sites. What is needed is an indexed approach
1613                 such as that used in databases.
1614                 </para></listitem>
1615
1616                 <listitem><para>
1617 <indexterm><primary>smbpasswd</primary></indexterm>
1618 <indexterm><primary>replicate</primary></indexterm>
1619 <indexterm><primary>rsync</primary></indexterm>
1620 <indexterm><primary>ssh</primary></indexterm>
1621 <indexterm><primary>custom scripts</primary></indexterm>
1622                 The second problem is that administrators who desire to replicate an smbpasswd file
1623                 to more than one Samba server are left to use external tools such as
1624                 <command>rsync(1)</command> and <command>ssh(1)</command> and write custom,
1625                 in-house scripts.
1626                 </para></listitem>
1627
1628                 <listitem><para>
1629 <indexterm><primary>smbpasswd</primary></indexterm>
1630 <indexterm><primary>home directory</primary></indexterm>
1631 <indexterm><primary>password expiration</primary></indexterm>
1632 <indexterm><primary>relative identifier</primary></indexterm>
1633 <indexterm><primary>relative identifier</primary><see>RID</see></indexterm>
1634                 Finally, the amount of information that is stored in an smbpasswd entry leaves
1635                 no room for additional attributes such as a home directory, password expiration time,
1636                 or even a relative identifier (RID).
1637                 </para></listitem>
1638                 </itemizedlist>
1639
1640                 <para>
1641 <indexterm><primary>user attributes</primary></indexterm>
1642 <indexterm><primary>smbd</primary></indexterm>
1643 <indexterm><primary>API</primary></indexterm>
1644 <indexterm><primary>samdb interface</primary></indexterm>
1645                 As a result of these deficiencies, a more robust means of storing user attributes
1646                 used by smbd was developed. The API that defines access to user accounts
1647                 is commonly referred to as the samdb interface (previously, this was called the passdb
1648                 API and is still so named in the Samba source code trees).
1649                 </para>
1650
1651                 <para>
1652 <indexterm><primary>passdb backends</primary></indexterm>
1653 <indexterm><primary>smbpasswd plaintext database</primary></indexterm>
1654 <indexterm><primary>tdbsam</primary></indexterm>
1655 <indexterm><primary>ldapsam</primary></indexterm>
1656 <indexterm><primary>xmlsam</primary></indexterm>
1657 <indexterm><primary>enterprise</primary></indexterm>
1658                 Samba provides an enhanced set of passdb backends that overcome the deficiencies
1659                 of the smbpasswd plaintext database. These are tdbsam, ldapsam, and xmlsam.
1660                 Of these, ldapsam will be of most interest to large corporate or enterprise sites.
1661                 </para>
1662
1663         </sect2>
1664
1665         <sect2>
1666         <title>tdbsam</title>
1667
1668                 <para>
1669                 <indexterm><primary>SAM backend</primary><secondary>tdbsam</secondary></indexterm>
1670 <indexterm><primary>trivial database</primary><see>TDB</see></indexterm>
1671 <indexterm><primary>machine account</primary></indexterm>
1672                 Samba can store user and machine account data in a <quote>TDB</quote> (trivial database).
1673                 Using this backend does not require any additional configuration. This backend is
1674                 recommended for new installations that do not require LDAP.
1675                 </para>
1676
1677                 <para>
1678 <indexterm><primary>tdbsam</primary></indexterm>
1679 <indexterm><primary>PDC</primary></indexterm>
1680 <indexterm><primary>BDC</primary></indexterm>
1681 <indexterm><primary>scalability</primary></indexterm>
1682                 As a general guide, the Samba Team does not recommend using the tdbsam backend for sites
1683                 that have 250 or more users. Additionally, tdbsam is not capable of scaling for use
1684                 in sites that require PDB/BDC implementations that require replication of the account
1685                 database. Clearly, for reason of scalability, the use of ldapsam should be encouraged.
1686                 </para>
1687
1688                 <para>
1689 <indexterm><primary>250-user limit</primary></indexterm>
1690 <indexterm><primary>performance-based</primary></indexterm>
1691 <indexterm><primary>tdbsam</primary></indexterm>
1692                 The recommendation of a 250-user limit is purely based on the notion that this
1693                 would generally involve a site that has routed networks, possibly spread across
1694                 more than one physical location. The Samba Team has not at this time established
1695                 the performance-based scalability limits of the tdbsam architecture.
1696                 </para>
1697
1698                 <para>
1699 <indexterm><primary>4,500 user accounts</primary></indexterm>
1700 <indexterm><primary>passdb backend</primary></indexterm>
1701 <indexterm><primary>tdbsam</primary></indexterm>
1702 <indexterm><primary>SambaSAMAccount</primary></indexterm>
1703                 There are sites that have thousands of users and yet require only one server.
1704                 One site recently reported having 4,500 user accounts on one UNIX system and
1705                 reported excellent performance with the <literal>tdbsam</literal> passdb backend.
1706                 The limitation of where the <literal>tdbsam</literal> passdb backend can be used
1707                 is not one pertaining to a limitation in the TDB storage system, it is based
1708                 only on the need for a reliable distribution mechanism for the SambaSAMAccount
1709                 backend.
1710                 </para>
1711
1712         </sect2>
1713
1714         <sect2>
1715         <title>ldapsam</title>
1716
1717                 <para>
1718 <indexterm><primary>LDAP</primary></indexterm>
1719 <indexterm><primary>ldapsam</primary></indexterm>
1720                 <indexterm><primary>SAM backend</primary><secondary>ldapsam</secondary></indexterm>
1721                 There are a few points to stress that the ldapsam does not provide. The LDAP
1722                 support referred to in this documentation does not include:
1723                 </para>
1724
1725                 <itemizedlist>
1726                         <listitem><para>A means of retrieving user account information from
1727                         a Windows 200x Active Directory server.</para></listitem>
1728                         <listitem><para>A means of replacing /etc/passwd.</para></listitem>
1729                 </itemizedlist>
1730
1731                 <para>
1732 <indexterm><primary>LDAP</primary></indexterm>
1733 <indexterm><primary>NSS</primary></indexterm>
1734 <indexterm><primary>PAM</primary></indexterm>
1735 <indexterm><primary>LGPL</primary></indexterm>
1736                 The second item can be accomplished by using LDAP NSS and PAM modules. LGPL versions of these libraries can be
1737                 obtained from <ulink url="http://www.padl.com/">PADL Software</ulink>.  More information about the
1738                 configuration of these packages may be found in <ulink url="http://safari.oreilly.com/?XmlId=1-56592-491-6">
1739                 <emphasis>LDAP, System Administration</emphasis> by Gerald Carter, Chapter 6, Replacing NIS"</ulink>.
1740                 </para>
1741
1742                 <para>
1743 <indexterm><primary>LDAP directory</primary></indexterm>
1744 <indexterm><primary>smbpasswd</primary></indexterm>
1745 <indexterm><primary>directory server</primary></indexterm>
1746                 This document describes how to use an LDAP directory for storing Samba user
1747                 account information traditionally stored in the smbpasswd(5) file. It is
1748                 assumed that the reader already has a basic understanding of LDAP concepts
1749                 and has a working directory server already installed. For more information
1750                 on LDAP architectures and directories, please refer to the following sites:
1751                 </para>
1752
1753                 <itemizedlist>
1754                         <listitem><para><ulink url="http://www.openldap.org/">OpenLDAP</ulink></para></listitem>
1755                         <listitem><para><ulink url="http://www.sun.com/software/products/directory_srvr_ee/index.xml">
1756                                 Sun One Directory Server</ulink></para></listitem>
1757                         <listitem><para><ulink url="http://www.novell.com/products/edirectory/">Novell eDirectory</ulink></para></listitem>
1758                         <listitem><para><ulink url="http://www-306.ibm.com/software/tivoli/products/directory-server/">IBM
1759                                 Tivoli Directory Server</ulink></para></listitem>
1760                         <listitem><para><ulink url="http://www.redhat.com/software/rha/directory/">Red Hat Directory
1761                                 Server</ulink></para></listitem>
1762                         <listitem><para><ulink url="http://www.linuxsecurity.com/content/view/119229">Fedora Directory
1763                                 Server</ulink></para></listitem>
1764                 </itemizedlist>
1765
1766                 <para>
1767                 Two additional Samba resources that may prove to be helpful are:
1768                 </para>
1769
1770                 <itemizedlist>
1771                         <listitem><para>
1772 <indexterm><primary>Samba-PDC-LDAP-HOWTO</primary></indexterm>
1773                         The <ulink url="http://www.unav.es/cti/ldap-smb/ldap-smb-3-howto.html">Samba-PDC-LDAP-HOWTO</ulink>
1774                         maintained by Ignacio Coupeau.
1775                         </para></listitem>
1776
1777                         <listitem><para>
1778 <indexterm><primary>IDEALX</primary></indexterm>
1779 <indexterm><primary>NT migration scripts</primary></indexterm>
1780 <indexterm><primary>smbldap-tools</primary></indexterm>
1781                         The NT migration scripts from <ulink url="http://samba.idealx.org/">IDEALX</ulink> that are
1782                         geared to manage users and groups in such a Samba-LDAP domain controller configuration.
1783                         Idealx also produced the smbldap-tools and the Interactive Console Management tool.
1784                         </para></listitem>
1785                 </itemizedlist>
1786
1787                 <sect3>
1788                 <title>Supported LDAP Servers</title>
1789
1790                         <para>
1791 <indexterm><primary>LDAP</primary></indexterm>
1792 <indexterm><primary>ldapsam</primary></indexterm>
1793 <indexterm><primary>OpenLDAP</primary></indexterm>
1794 <indexterm><primary>Netscape's Directory Server</primary></indexterm>
1795                         The LDAP ldapsam code was developed and tested using the OpenLDAP 2.x server and
1796                         client libraries. The same code should work with Netscape's Directory Server and client SDK.
1797                         However, there are bound to be compile errors and bugs. These should not be hard to fix.
1798                         Please submit fixes via the process outlined in <link linkend="bugreport">Reporting Bugs</link>.
1799                         </para>
1800
1801                         <para>
1802                         Samba is capable of working with any standards-compliant LDAP server.
1803                         </para>
1804
1805                 </sect3>
1806
1807                 <sect3>
1808                 <title>Schema and Relationship to the RFC 2307 posixAccount</title>
1809
1810
1811                         <para>
1812                         Samba-3.0 includes the necessary schema file for OpenLDAP 2.x in the
1813                         <filename>examples/LDAP/samba.schema</filename> directory of the source code distribution
1814                         tarball. The schema entry for the sambaSamAccount ObjectClass is shown here:
1815 <programlisting>
1816 ObjectClass (1.3.6.1.4.1.7165.2.2.6 NAME 'sambaSamAccount' SUP top AUXILIARY
1817     DESC 'Samba-3.0 Auxiliary SAM Account'
1818     MUST ( uid $ sambaSID )
1819     MAY  ( cn $ sambaLMPassword $ sambaNTPassword $ sambaPwdLastSet $
1820           sambaLogonTime $ sambaLogoffTime $ sambaKickoffTime $
1821           sambaPwdCanChange $ sambaPwdMustChange $ sambaAcctFlags $
1822           displayName $ sambaHomePath $ sambaHomeDrive $ sambaLogonScript $
1823           sambaProfilePath $ description $ sambaUserWorkstations $
1824           sambaPrimaryGroupSID $ sambaDomainName ))
1825 </programlisting>
1826                         </para>
1827
1828                         <para>
1829 <indexterm><primary>samba.schema</primary></indexterm>
1830 <indexterm><primary>OpenLDAP</primary></indexterm>
1831 <indexterm><primary>OID</primary></indexterm>
1832                         The <filename>samba.schema</filename> file has been formatted for OpenLDAP 2.0/2.1.
1833                         The Samba Team owns the OID space used by the above schema and recommends its use.
1834                         If you translate the schema to be used with Netscape DS, please submit the modified
1835                         schema file as a patch to <ulink url="mailto:jerry@samba.org">jerry@samba.org</ulink>.
1836                         </para>
1837
1838                         <para>
1839 <indexterm><primary>smbpasswd</primary></indexterm>
1840 <indexterm><primary>/etc/passwd</primary></indexterm>
1841 <indexterm><primary>sambaSamAccount</primary></indexterm>
1842 <indexterm><primary>AUXILIARY</primary></indexterm>
1843 <indexterm><primary>ObjectClass</primary></indexterm>
1844 <indexterm><primary>LDAP</primary></indexterm>
1845 <indexterm><primary>RFC 2307.</primary></indexterm>
1846                         Just as the smbpasswd file is meant to store information that provides information
1847                         additional to  a user's <filename>/etc/passwd</filename> entry, so is the sambaSamAccount
1848                         object meant to supplement the UNIX user account information. A sambaSamAccount is an
1849                         <constant>AUXILIARY</constant> ObjectClass, so it can be used to augment existing
1850                         user account information in the LDAP directory, thus providing information needed
1851                         for Samba account handling. However, there are several fields (e.g., uid) that overlap
1852                         with the posixAccount ObjectClass outlined in RFC 2307. This is by design.
1853                         </para>
1854
1855                         <para>
1856 <indexterm><primary>account information</primary></indexterm>
1857 <indexterm><primary>sambaSamAccount</primary></indexterm>
1858 <indexterm><primary>posixAccount</primary></indexterm>
1859 <indexterm><primary>ObjectClasses</primary></indexterm>
1860 <indexterm><primary>smbd</primary></indexterm>
1861 <indexterm><primary>getpwnam</primary></indexterm>
1862 <indexterm><primary>LDAP</primary></indexterm>
1863 <indexterm><primary>NIS</primary></indexterm>
1864 <indexterm><primary>NSS</primary></indexterm>
1865                         In order to store all user account information (UNIX and Samba) in the directory,
1866                         it is necessary to use the sambaSamAccount and posixAccount ObjectClasses in
1867                         combination. However, <command>smbd</command> will still obtain the user's UNIX account
1868                         information via the standard C library calls, such as getpwnam().
1869                         This means that the Samba server must also have the LDAP NSS library installed
1870                         and functioning correctly. This division of information makes it possible to
1871                         store all Samba account information in LDAP, but still maintain UNIX account
1872                         information in NIS while the network is transitioning to a full LDAP infrastructure.
1873                         </para>
1874                 </sect3>
1875
1876                 <sect3>
1877                 <title>OpenLDAP Configuration</title>
1878
1879                 <para>
1880 <indexterm><primary>sambaSamAccount</primary></indexterm>
1881 <indexterm><primary>OpenLDAP</primary></indexterm>
1882 <indexterm><primary>slapd</primary></indexterm>
1883 <indexterm><primary>samba.schema</primary></indexterm>
1884                 To include support for the sambaSamAccount object in an OpenLDAP directory
1885                 server, first copy the samba.schema file to slapd's configuration directory.
1886                 The samba.schema file can be found in the directory <filename>examples/LDAP</filename>
1887                 in the Samba source distribution.
1888 <screen>
1889 &rootprompt;<userinput>cp samba.schema /etc/openldap/schema/</userinput>
1890 </screen>
1891                 </para>
1892
1893                 <para>
1894 <indexterm><primary>samba.schema</primary></indexterm>
1895 <indexterm><primary>slapd.conf</primary></indexterm>
1896 <indexterm><primary>sambaSamAccount</primary></indexterm>
1897 <indexterm><primary>cosine.schema</primary></indexterm>
1898 <indexterm><primary>uid</primary></indexterm>
1899 <indexterm><primary>inetorgperson.schema</primary></indexterm>
1900 <indexterm><primary>displayName</primary></indexterm>
1901 <indexterm><primary>attribute</primary></indexterm>
1902                 Next, include the <filename>samba.schema</filename> file in <filename>slapd.conf</filename>.
1903                 The sambaSamAccount object contains two attributes that depend on other schema
1904                 files. The <parameter>uid</parameter> attribute is defined in <filename>cosine.schema</filename> and
1905                 the <parameter>displayName</parameter> attribute is defined in the <filename>inetorgperson.schema</filename>
1906                 file. Both of these must be included before the <filename>samba.schema</filename> file.
1907 <programlisting>
1908 ## /etc/openldap/slapd.conf
1909
1910 ## schema files (core.schema is required by default)
1911 include            /etc/openldap/schema/core.schema
1912
1913 ## needed for sambaSamAccount
1914 include            /etc/openldap/schema/cosine.schema
1915 include            /etc/openldap/schema/inetorgperson.schema
1916 include            /etc/openldap/schema/nis.schema
1917 include            /etc/openldap/schema/samba.schema
1918 ....
1919 </programlisting>
1920                 </para>
1921
1922                 <para>
1923 <indexterm><primary>sambaSamAccount</primary></indexterm>
1924 <indexterm><primary>posixAccount</primary></indexterm>
1925 <indexterm><primary>posixGroup</primary></indexterm>
1926 <indexterm><primary>ObjectClasses</primary></indexterm>
1927                 It is recommended that you maintain some indices on some of the most useful attributes,
1928                 as in the following example, to speed up searches made on sambaSamAccount ObjectClasses
1929                 (and possibly posixAccount and posixGroup as well):
1930                 </para>
1931
1932 <para>
1933 <programlisting>
1934 # Indices to maintain
1935 ## required by OpenLDAP
1936 index objectclass             eq
1937
1938 index cn                      pres,sub,eq
1939 index sn                      pres,sub,eq
1940 ## required to support pdb_getsampwnam
1941 index uid                     pres,sub,eq
1942 ## required to support pdb_getsambapwrid()
1943 index displayName             pres,sub,eq
1944
1945 ## uncomment these if you are storing posixAccount and
1946 ## posixGroup entries in the directory as well
1947 ##index uidNumber               eq
1948 ##index gidNumber               eq
1949 ##index memberUid               eq
1950
1951 index   sambaSID              eq
1952 index   sambaPrimaryGroupSID  eq
1953 index   sambaDomainName       eq
1954 index   default               sub
1955 </programlisting>
1956 </para>
1957
1958                 <para>
1959                 Create the new index by executing:
1960 <screen>
1961 &rootprompt;./sbin/slapindex -f slapd.conf
1962 </screen>
1963                 </para>
1964
1965                 <para>
1966                 Remember to restart slapd after making these changes:
1967 <screen>
1968 &rootprompt;<userinput>/etc/init.d/slapd restart</userinput>
1969 </screen>
1970                 </para>
1971
1972                 </sect3>
1973
1974                 <sect3>
1975                 <title>Initialize the LDAP Database</title>
1976
1977                 <para>
1978 <indexterm><primary>LDAP database</primary></indexterm>
1979 <indexterm><primary>account containers</primary></indexterm>
1980 <indexterm><primary>LDIF file</primary></indexterm>
1981 <indexterm><primary>DNS</primary></indexterm>
1982                 Before you can add accounts to the LDAP database, you must create the account containers
1983                 that they will be stored in. The following LDIF file should be modified to match your
1984                 needs (DNS entries, and so on):
1985 <programlisting>
1986 # Organization for Samba Base
1987 dn: dc=quenya,dc=org
1988 objectclass: dcObject
1989 objectclass: organization
1990 dc: quenya
1991 o: Quenya Org Network
1992 description: The Samba-3 Network LDAP Example
1993
1994 # Organizational Role for Directory Management
1995 dn: cn=Manager,dc=quenya,dc=org
1996 objectclass: organizationalRole
1997 cn: Manager
1998 description: Directory Manager
1999
2000 # Setting up container for Users OU
2001 dn: ou=People,dc=quenya,dc=org
2002 objectclass: top
2003 objectclass: organizationalUnit
2004 ou: People
2005
2006 # Setting up admin handle for People OU
2007 dn: cn=admin,ou=People,dc=quenya,dc=org
2008 cn: admin
2009 objectclass: top
2010 objectclass: organizationalRole
2011 objectclass: simpleSecurityObject
2012 userPassword: {SSHA}c3ZM9tBaBo9autm1dL3waDS21+JSfQVz
2013
2014 # Setting up container for groups
2015 dn: ou=Groups,dc=quenya,dc=org
2016 objectclass: top
2017 objectclass: organizationalUnit
2018 ou: Groups
2019
2020 # Setting up admin handle for Groups OU
2021 dn: cn=admin,ou=Groups,dc=quenya,dc=org
2022 cn: admin
2023 objectclass: top
2024 objectclass: organizationalRole
2025 objectclass: simpleSecurityObject
2026 userPassword: {SSHA}c3ZM9tBaBo9autm1dL3waDS21+JSfQVz
2027
2028 # Setting up container for computers
2029 dn: ou=Computers,dc=quenya,dc=org
2030 objectclass: top
2031 objectclass: organizationalUnit
2032 ou: Computers
2033
2034 # Setting up admin handle for Computers OU
2035 dn: cn=admin,ou=Computers,dc=quenya,dc=org
2036 cn: admin
2037 objectclass: top
2038 objectclass: organizationalRole
2039 objectclass: simpleSecurityObject
2040 userPassword: {SSHA}c3ZM9tBaBo9autm1dL3waDS21+JSfQVz
2041 </programlisting>
2042                 </para>
2043
2044                 <para>
2045 <indexterm><primary>userPassword</primary></indexterm>
2046 <indexterm><primary>slappasswd</primary></indexterm>
2047                 The userPassword shown above should be generated using <command>slappasswd</command>.
2048                 </para>
2049
2050                 <para>
2051 <indexterm><primary>LDIF</primary></indexterm>
2052 <indexterm><primary>LDAP</primary></indexterm>
2053                 The following command will then load the contents of the LDIF file into the LDAP
2054                 database.
2055 <indexterm><primary>slapadd</primary></indexterm>
2056 <screen>
2057 &prompt;<userinput>slapadd -v -l initldap.dif</userinput>
2058 </screen>
2059                 </para>
2060
2061                 <para>
2062                 Do not forget to secure your LDAP server with an adequate access control list
2063                 as well as an admin password.
2064                 </para>
2065
2066                 <note><para>
2067 <indexterm><primary>secrets.tdb</primary></indexterm>
2068                 Before Samba can access the LDAP server, you need to store the LDAP admin password
2069                 in the Samba-3 <filename>secrets.tdb</filename> database by:
2070 <indexterm><primary>smbpasswd</primary></indexterm>
2071 <screen>
2072 &rootprompt;<userinput>smbpasswd -w <replaceable>secret</replaceable></userinput>
2073 </screen>
2074                 </para></note>
2075
2076                 </sect3>
2077
2078                 <sect3>
2079                 <title>Configuring Samba</title>
2080
2081                         <para>
2082 <indexterm><primary>LDAP</primary></indexterm>
2083 <indexterm><primary>smbd</primary></indexterm>
2084                         The following parameters are available in &smb.conf; only if your version of Samba was built with
2085                         LDAP support. Samba automatically builds with LDAP support if the LDAP libraries are found. The
2086                         best method to verify that Samba was built with LDAP support is:
2087 <screen>
2088 &rootprompt; smbd -b | grep LDAP
2089    HAVE_LDAP_H
2090    HAVE_LDAP
2091    HAVE_LDAP_DOMAIN2HOSTLIST
2092    HAVE_LDAP_INIT
2093    HAVE_LDAP_INITIALIZE
2094    HAVE_LDAP_SET_REBIND_PROC
2095    HAVE_LIBLDAP
2096    LDAP_SET_REBIND_PROC_ARGS
2097 </screen>
2098                         If the build of the <command>smbd</command> command you are using does not produce output
2099                         that includes <literal>HAVE_LDAP_H</literal> it is necessary to discover why the LDAP headers
2100                         and libraries were not found during compilation.
2101                         </para>
2102
2103                         <para>LDAP-related smb.conf options include these:
2104                         <smbconfblock>
2105                         <smbconfoption name="passdb backend">ldapsam:url</smbconfoption>
2106                         <smbconfoption name="ldap admin dn"/>
2107                         <smbconfoption name="ldap delete dn"/>
2108                         <smbconfoption name="ldap filter"/>
2109                         <smbconfoption name="ldap group suffix"/>
2110                         <smbconfoption name="ldap idmap suffix"/>
2111                         <smbconfoption name="ldap machine suffix"/>
2112                         <smbconfoption name="ldap passwd sync"/>
2113                         <smbconfoption name="ldap ssl"/>
2114                         <smbconfoption name="ldap suffix"/>
2115                         <smbconfoption name="ldap user suffix"/>
2116                         <smbconfoption name="ldap replication sleep"/>
2117                         <smbconfoption name="ldap timeout"/>
2118                         <smbconfoption name="ldap page size"/>
2119                         </smbconfblock>
2120                         </para>
2121
2122                         <para>
2123                         These are described in the &smb.conf; man page and so are not repeated here. However, an example
2124                         for use with an LDAP directory is shown in <link linkend="confldapex">the Configuration with LDAP.</link>
2125                         </para>
2126
2127 <example id="confldapex">
2128 <title>Configuration with LDAP</title>
2129 <smbconfblock>
2130 <smbconfsection name="[global]"/>
2131 <smbconfoption name="security">user</smbconfoption>
2132 <smbconfoption name="encrypt passwords">yes</smbconfoption>
2133 <smbconfoption name="netbios name">MORIA</smbconfoption>
2134 <smbconfoption name="workgroup">NOLDOR</smbconfoption>
2135
2136 <smbconfcomment>LDAP related parameters:</smbconfcomment>
2137
2138 <smbconfcomment>Define the DN used when binding to the LDAP servers.</smbconfcomment>
2139 <smbconfcomment>The password for this DN is not stored in smb.conf</smbconfcomment>
2140 <smbconfcomment>Set it using 'smbpasswd -w secret' to store the</smbconfcomment>
2141 <smbconfcomment>passphrase in the secrets.tdb file.</smbconfcomment>
2142 <smbconfcomment>If the "ldap admin dn" value changes, it must be reset.</smbconfcomment>
2143 <smbconfoption name="ldap admin dn">"cn=Manager,dc=quenya,dc=org"</smbconfoption>
2144
2145 <smbconfcomment>SSL directory connections can be configured by:</smbconfcomment>
2146 <smbconfcomment>('off', 'start tls', or 'on' (default))</smbconfcomment>
2147 <smbconfoption name="ldap ssl">start tls</smbconfoption>
2148
2149 <smbconfcomment>syntax: passdb backend = ldapsam:ldap://server-name[:port]</smbconfcomment>
2150 <smbconfoption name="passdb backend">ldapsam:ldap://frodo.quenya.org</smbconfoption>
2151
2152 <smbconfcomment>smbpasswd -x delete the entire dn-entry</smbconfcomment>
2153 <smbconfoption name="ldap delete dn">no</smbconfoption>
2154
2155 <smbconfcomment>The machine and user suffix are added to the base suffix</smbconfcomment>
2156 <smbconfcomment>wrote WITHOUT quotes. NULL suffixes by default</smbconfcomment>
2157 <smbconfoption name="ldap user suffix">ou=People</smbconfoption>
2158 <smbconfoption name="ldap group suffix">ou=Groups</smbconfoption>
2159 <smbconfoption name="ldap machine suffix">ou=Computers</smbconfoption>
2160
2161 <smbconfcomment>Trust UNIX account information in LDAP</smbconfcomment>
2162 <smbconfcomment> (see the smb.conf man page for details)</smbconfcomment>
2163
2164 <smbconfcomment>Specify the base DN to use when searching the directory</smbconfcomment>
2165 <smbconfoption name="ldap suffix">dc=quenya,dc=org</smbconfoption>
2166 </smbconfblock>
2167 </example>
2168
2169                 </sect3>
2170
2171                 <sect3>
2172                 <title>Accounts and Groups Management</title>
2173
2174                         <para>
2175                         <indexterm><primary>User Management</primary></indexterm>
2176                         <indexterm><primary>User Accounts</primary><secondary>Adding/Deleting</secondary></indexterm>
2177                         Because user accounts are managed through the sambaSamAccount ObjectClass, you should
2178                         modify your existing administration tools to deal with sambaSamAccount attributes.
2179                         </para>
2180
2181                         <para>
2182 <indexterm><primary>sambaSamAccount</primary></indexterm>
2183 <indexterm><primary>/etc/openldap/sldap.conf</primary></indexterm>
2184 <indexterm><primary>NSS</primary></indexterm>
2185                         Machine accounts are managed with the sambaSamAccount ObjectClass, just
2186                         like user accounts. However, it is up to you to store those accounts
2187                         in a different tree of your LDAP namespace. You should use
2188                         <quote>ou=Groups,dc=quenya,dc=org</quote> to store groups and
2189                         <quote>ou=People,dc=quenya,dc=org</quote> to store users. Just configure your
2190                         NSS and PAM accordingly (usually, in the <filename>/etc/openldap/sldap.conf</filename>
2191                         configuration file).
2192                         </para>
2193
2194                         <para>
2195 <indexterm><primary>POSIX</primary></indexterm>
2196 <indexterm><primary>posixGroup</primary></indexterm>
2197 <indexterm><primary>Domain Groups</primary></indexterm>
2198 <indexterm><primary>ADS</primary></indexterm>
2199                         In Samba-3, the group management system is based on POSIX
2200                         groups. This means that Samba makes use of the posixGroup ObjectClass.
2201                         For now, there is no NT-like group system management (global and local
2202                         groups). Samba-3 knows only about <constant>Domain Groups</constant>
2203                         and, unlike MS Windows 2000 and Active Directory, Samba-3 does not
2204                         support nested groups.
2205                         </para>
2206
2207                 </sect3>
2208
2209                 <sect3>
2210                 <title>Security and sambaSamAccount</title>
2211
2212
2213                         <para>
2214 <indexterm><primary>sambaSAMAccount</primary></indexterm>
2215                         There are two important points to remember when discussing the security
2216                         of sambaSAMAccount entries in the directory.
2217                         </para>
2218
2219                         <itemizedlist>
2220                                 <listitem><para><emphasis>Never</emphasis> retrieve the SambaLMPassword or
2221 <indexterm><primary>SambaNTPassword</primary></indexterm>
2222                                 SambaNTPassword attribute values over an unencrypted LDAP session.</para></listitem>
2223                                 <listitem><para><emphasis>Never</emphasis> allow non-admin users to
2224                                 view the SambaLMPassword or SambaNTPassword attribute values.</para></listitem>
2225                         </itemizedlist>
2226
2227                         <para>
2228 <indexterm><primary>clear-text</primary></indexterm>
2229 <indexterm><primary>impersonate</primary></indexterm>
2230 <indexterm><primary>LM/NT password hashes</primary></indexterm>
2231                         These password hashes are clear-text equivalents and can be used to impersonate
2232                         the user without deriving the original clear-text strings. For more information
2233                         on the details of LM/NT password hashes, refer to <link linkend="passdb">the
2234                         Account Information Database section</link>.
2235                         </para>
2236
2237                         <para>
2238 <indexterm><primary>encrypted session</primary></indexterm>
2239 <indexterm><primary>StartTLS</primary></indexterm>
2240 <indexterm><primary>LDAPS</primary></indexterm>
2241 <indexterm><primary>secure communications</primary></indexterm>
2242                         To remedy the first security issue, the <smbconfoption name="ldap ssl"/> &smb.conf;
2243                         parameter defaults to require an encrypted session (<smbconfoption name="ldap
2244                         ssl">on</smbconfoption>) using the default port of <constant>636</constant> when
2245                         contacting the directory server. When using an OpenLDAP server, it
2246                         is possible to use the StartTLS LDAP extended operation in the place of LDAPS.
2247                         In either case, you are strongly encouraged to use secure communications protocols
2248                         (so do not set <smbconfoption name="ldap ssl">off</smbconfoption>).
2249                         </para>
2250
2251                         <para>
2252 <indexterm><primary>LDAPS</primary></indexterm>
2253 <indexterm><primary>StartTLS</primary></indexterm>
2254 <indexterm><primary>LDAPv3</primary></indexterm>
2255                         Note that the LDAPS protocol is deprecated in favor of the LDAPv3 StartTLS
2256                         extended operation. However, the OpenLDAP library still provides support for
2257                         the older method of securing communication between clients and servers.
2258                         </para>
2259
2260                         <para>
2261 <indexterm><primary>harvesting password hashes</primary></indexterm>
2262 <indexterm><primary>ACL</primary></indexterm>
2263 <indexterm><primary>slapd.conf</primary></indexterm>
2264                         The second security precaution is to prevent non-administrative users from
2265                         harvesting password hashes from the directory. This can be done using the
2266                         following ACL in <filename>slapd.conf</filename>:
2267                         </para>
2268
2269 <para>
2270 <programlisting>
2271 ## allow the "ldap admin dn" access, but deny everyone else
2272 access to attrs=SambaLMPassword,SambaNTPassword
2273      by dn="cn=Samba Admin,ou=People,dc=quenya,dc=org" write
2274      by * none
2275 </programlisting>
2276 </para>
2277
2278                 </sect3>
2279
2280                 <sect3>
2281                 <title>LDAP Special Attributes for sambaSamAccounts</title>
2282
2283                         <para> The sambaSamAccount ObjectClass is composed of the attributes shown in next tables: <link
2284                         linkend="attribobjclPartA">Part A</link>, and <link linkend="attribobjclPartB">Part B</link>.
2285                         </para>
2286
2287                         <table frame="all" id="attribobjclPartA">
2288                                 <title>Attributes in the sambaSamAccount ObjectClass (LDAP), Part A</title>
2289                         <tgroup cols="2" align="justify">
2290                                         <colspec align="left"/>
2291                                         <colspec align="justify" colwidth="1*"/>
2292                         <tbody>
2293                                 <row><entry><constant>sambaLMPassword</constant></entry><entry>The LanMan password 16-byte hash stored as a character
2294                                                 representation of a hexadecimal string.</entry></row>
2295                                 <row><entry><constant>sambaNTPassword</constant></entry><entry>The NT password 16-byte hash stored as a character
2296                                                 representation of a hexadecimal string.</entry></row>
2297                                 <row><entry><constant>sambaPwdLastSet</constant></entry><entry>The integer time in seconds since 1970 when the
2298                                                 <constant>sambaLMPassword</constant> and <constant>sambaNTPassword</constant> attributes were last set.
2299                                 </entry></row>
2300
2301                                 <row><entry><constant>sambaAcctFlags</constant></entry><entry>String of 11 characters surrounded by square brackets [ ]
2302                                                 representing account flags such as U (user), W (workstation), X (no password expiration),
2303                                                 I (domain trust account), H (home dir required), S (server trust account),
2304                                                 and D (disabled).</entry></row>
2305
2306                                 <row><entry><constant>sambaLogonTime</constant></entry><entry>Integer value currently unused.</entry></row>
2307
2308                                 <row><entry><constant>sambaLogoffTime</constant></entry><entry>Integer value currently unused.</entry></row>
2309
2310                                 <row><entry><constant>sambaKickoffTime</constant></entry><entry>Specifies the time (UNIX time format) when the user
2311                                 will be locked down and cannot login any longer. If this attribute is omitted, then the account will never expire.
2312                                 Using this attribute together with shadowExpire of the shadowAccount ObjectClass will enable accounts to
2313                                 expire completely on an exact date.</entry></row>
2314
2315                                 <row><entry><constant>sambaPwdCanChange</constant></entry><entry>Specifies the time (UNIX time format)
2316                                 after which the user is allowed to change his password. If this attribute is not set, the user will be free
2317                                 to change his password whenever he wants.</entry></row>
2318
2319                                 <row><entry><constant>sambaPwdMustChange</constant></entry><entry>Specifies the time (UNIX time format) when the user is
2320                                 forced to change his password. If this value is set to 0, the user will have to change his password at first login.
2321                                 If this attribute is not set, then the password will never expire.</entry></row>
2322
2323                                 <row><entry><constant>sambaHomeDrive</constant></entry><entry>Specifies the drive letter to which to map the
2324                                 UNC path specified by sambaHomePath. The drive letter must be specified in the form <quote>X:</quote>
2325                                 where X is the letter of the drive to map. Refer to the <quote>logon drive</quote> parameter in the
2326                                 smb.conf(5) man page for more information.</entry></row>
2327
2328                                 <row><entry><constant>sambaLogonScript</constant></entry><entry>The sambaLogonScript property specifies the path of
2329                                 the user's logon script, .CMD, .EXE, or .BAT file. The string can be null. The path
2330                                 is relative to the netlogon share. Refer to the <smbconfoption name="logon script"/> parameter in the
2331                                 &smb.conf; man page for more information.</entry></row>
2332
2333                                 <row><entry><constant>sambaProfilePath</constant></entry><entry>Specifies a path to the user's profile.
2334                                 This value can be a null string, a local absolute path, or a UNC path. Refer to the
2335                                 <smbconfoption name="logon path"/> parameter in the &smb.conf; man page for more information.</entry></row>
2336
2337                                 <row><entry><constant>sambaHomePath</constant></entry><entry>The sambaHomePath property specifies the path of
2338                                 the home directory for the user. The string can be null. If sambaHomeDrive is set and specifies
2339                                 a drive letter, sambaHomePath should be a UNC path. The path must be a network
2340                                 UNC path of the form <filename>\\server\share\directory</filename>. This value can be a null string.
2341                                 Refer to the <command>logon home</command> parameter in the &smb.conf; man page for more information.
2342                                 </entry></row>
2343                         </tbody>
2344                         </tgroup></table>
2345
2346
2347                         <table frame="all" id="attribobjclPartB">
2348                                 <title>Attributes in the sambaSamAccount ObjectClass (LDAP), Part B</title>
2349                         <tgroup cols="2" align="justify">
2350                                         <colspec align="left"/>
2351                                         <colspec align="justify" colwidth="1*"/>
2352                         <tbody>
2353                                 <row><entry><constant>sambaUserWorkstations</constant></entry><entry>Here you can give a comma-separated list of machines
2354                                 on which the user is allowed to login. You may observe problems when you try to connect to a Samba domain member.
2355                                 Because domain members are not in this list, the domain controllers will reject them. Where this attribute is omitted,
2356                                 the default implies no restrictions.
2357                                 </entry></row>
2358
2359                                 <row><entry><constant>sambaSID</constant></entry><entry>The security identifier(SID) of the user.
2360                                 The Windows equivalent of UNIX UIDs.</entry></row>
2361
2362                                 <row><entry><constant>sambaPrimaryGroupSID</constant></entry><entry>The security identifier (SID) of the primary group
2363                                 of the user.</entry></row>
2364
2365                                 <row><entry><constant>sambaDomainName</constant></entry><entry>Domain the user is part of.</entry></row>
2366                         </tbody>
2367                         </tgroup></table>
2368
2369
2370                         <para>
2371 <indexterm><primary>PDC</primary></indexterm>
2372 <indexterm><primary>sambaSamAccount</primary></indexterm>
2373                         The majority of these parameters are only used when Samba is acting as a PDC of
2374                         a domain (refer to <link linkend="samba-pdc">Domain Control</link>, for details on
2375                         how to configure Samba as a PDC). The following four attributes
2376                         are only stored with the sambaSamAccount entry if the values are non-default values:
2377                         </para>
2378
2379                         <itemizedlist>
2380 <indexterm><primary>sambaHomePath</primary></indexterm>
2381 <indexterm><primary>sambaLogonScript</primary></indexterm>
2382 <indexterm><primary>sambaProfilePath</primary></indexterm>
2383 <indexterm><primary>sambaHomeDrive</primary></indexterm>
2384                                 <listitem><para>sambaHomePath</para></listitem>
2385                                 <listitem><para>sambaLogonScript</para></listitem>
2386                                 <listitem><para>sambaProfilePath</para></listitem>
2387                                 <listitem><para>sambaHomeDrive</para></listitem>
2388                         </itemizedlist>
2389
2390                         <para>
2391 <indexterm><primary>sambaSamAccount</primary></indexterm>
2392 <indexterm><primary>PDC</primary></indexterm>
2393 <indexterm><primary>smbHome</primary></indexterm>
2394                         These attributes are only stored with the sambaSamAccount entry if
2395                         the values are non-default values. For example, assume MORIA has now been
2396                         configured as a PDC and that <smbconfoption name="logon home">\\%L\%u</smbconfoption> was defined in
2397                         its &smb.conf; file. When a user named <quote>becky</quote> logs on to the domain,
2398                         the <smbconfoption name="logon home"/> string is expanded to \\MORIA\becky.
2399                         If the smbHome attribute exists in the entry <quote>uid=becky,ou=People,dc=samba,dc=org</quote>,
2400                         this value is used. However, if this attribute does not exist, then the value
2401                         of the <smbconfoption name="logon home"/> parameter is used in its place. Samba
2402                         will only write the attribute value to the directory entry if the value is
2403                         something other than the default (e.g., <filename>\\MOBY\becky</filename>).
2404                         </para>
2405
2406                 </sect3>
2407
2408                 <sect3>
2409                 <title>Example LDIF Entries for a sambaSamAccount</title>
2410
2411                         <para>
2412                         The following is a working LDIF that demonstrates the use of the SambaSamAccount ObjectClass:
2413 <programlisting>
2414 dn: uid=guest2, ou=People,dc=quenya,dc=org
2415 sambaLMPassword: 878D8014606CDA29677A44EFA1353FC7
2416 sambaPwdMustChange: 2147483647
2417 sambaPrimaryGroupSID: S-1-5-21-2447931902-1787058256-3961074038-513
2418 sambaNTPassword: 552902031BEDE9EFAAD3B435B51404EE
2419 sambaPwdLastSet: 1010179124
2420 sambaLogonTime: 0
2421 objectClass: sambaSamAccount
2422 uid: guest2
2423 sambaKickoffTime: 2147483647
2424 sambaAcctFlags: [UX         ]
2425 sambaLogoffTime: 2147483647
2426 sambaSID: S-1-5-21-2447931902-1787058256-3961074038-5006
2427 sambaPwdCanChange: 0
2428 </programlisting>
2429                         </para>
2430
2431                         <para>
2432                         The following is an LDIF entry for using both the sambaSamAccount and
2433                         posixAccount ObjectClasses:
2434 <programlisting>
2435 dn: uid=gcarter, ou=People,dc=quenya,dc=org
2436 sambaLogonTime: 0
2437 displayName: Gerald Carter
2438 sambaLMPassword: 552902031BEDE9EFAAD3B435B51404EE
2439 sambaPrimaryGroupSID: S-1-5-21-2447931902-1787058256-3961074038-1201
2440 objectClass: posixAccount
2441 objectClass: sambaSamAccount
2442 sambaAcctFlags: [UX         ]
2443 userPassword: {crypt}BpM2ej8Rkzogo
2444 uid: gcarter
2445 uidNumber: 9000
2446 cn: Gerald Carter
2447 loginShell: /bin/bash
2448 logoffTime: 2147483647
2449 gidNumber: 100
2450 sambaKickoffTime: 2147483647
2451 sambaPwdLastSet: 1010179230
2452 sambaSID: S-1-5-21-2447931902-1787058256-3961074038-5004
2453 homeDirectory: /home/moria/gcarter
2454 sambaPwdCanChange: 0
2455 sambaPwdMustChange: 2147483647
2456 sambaNTPassword: 878D8014606CDA29677A44EFA1353FC7
2457 </programlisting>
2458                 </para>
2459
2460                 </sect3>
2461
2462                 <sect3>
2463                 <title>Password Synchronization</title>
2464
2465                 <para>
2466                 Samba-3 and later can update the non-Samba (LDAP) password stored with an account. When
2467                 using pam_ldap, this allows changing both UNIX and Windows passwords at once.
2468                 </para>
2469
2470                 <para>The <smbconfoption name="ldap passwd sync"/> options can have the  values shown in
2471                 <link linkend="ldappwsync">Possible <emphasis>ldap passwd sync</emphasis> Values</link>.</para>
2472
2473                 <table frame="all" id="ldappwsync">
2474                 <title>Possible <parameter>ldap passwd sync</parameter> Values</title>
2475                 <tgroup cols="2">
2476                         <colspec align="left" colwidth="1*"/>
2477                         <colspec align="justify" colwidth="4*"/>
2478                 <thead>
2479                         <row><entry align="left">Value</entry><entry align="center">Description</entry></row>
2480                 </thead>
2481                 <tbody>
2482                 <row><entry>yes</entry><entry><para>When the user changes his password, update
2483                                <constant>SambaNTPassword</constant>, <constant>SambaLMPassword</constant>,
2484                                and the <constant>password</constant> fields.</para></entry></row>
2485
2486                 <row><entry>no</entry><entry><para>Only update <constant>SambaNTPassword</constant> and
2487                                         <constant>SambaLMPassword</constant>.</para></entry></row>
2488
2489                 <row><entry>only</entry><entry><para>Only update the LDAP password and let the LDAP server
2490                         worry about the other fields.  This option is only available on some LDAP servers and
2491                         only when the LDAP server supports LDAP_EXOP_X_MODIFY_PASSWD.</para></entry></row>
2492                 </tbody>
2493                 </tgroup>
2494                 </table>
2495
2496
2497                 <para>More information can be found in the &smb.conf; man page.</para>
2498
2499                 </sect3>
2500
2501                 <sect3>
2502                 <title>Using OpenLDAP Overlay for Password Syncronization</title>
2503
2504                 <para>
2505                 Howard Chu has written a special overlay called <emphasis>smbk5pwd</emphasis>, which modifies
2506                 <constant>SambaNTPassword</constant>, <constant>SambaLMPassword</constant> and <constant>Heimdal</constant>
2507                 hashes in an OpenLDAP entry when LDAP_EXOP_X_MODIFY_PASSWD is performed.
2508                 </para>
2509
2510                 <para>
2511                 The overlay is shipped with OpenLDAP-2.3 and can be found in the
2512                 <filename>contrib/slapd-modules/smbk5pwd</filename> subdirectory. This module can be used with OpenLDAP-2.2
2513                 also.
2514                 </para>
2515
2516                 </sect3>
2517
2518         </sect2>
2519
2520         <sect2>
2521         <title>MySQL</title>
2522
2523         <para>
2524         <indexterm><primary>SAM backend</primary><secondary>mysqlsam</secondary></indexterm>
2525 <indexterm><primary>SQL backend</primary></indexterm>
2526         Every so often someone comes along with what seems (to them) like a great new idea. Storing user accounts
2527         in an SQL backend is one of them. Those who want to do this are in the best position to know what the
2528         specific benefits are to them. This may sound like a cop-out, but in truth we cannot document
2529         every little detail of why certain things of marginal utility to the bulk of Samba users might make sense
2530         to the rest. In any case, the following instructions should help the determined SQL user to implement a
2531         working system. These account storage methods are not actively maintained by the Samba Team.
2532         </para>
2533
2534                 <sect3>
2535                 <title>Creating the Database</title>
2536
2537                         <para>
2538 <indexterm><primary>MySQL</primary></indexterm>
2539                         You can set up your own table and specify the field names to pdb_mysql (see
2540                         <link linkend="moremysqlpdbe">MySQL field names for MySQL passdb backend</link> for
2541                         the column names) or use the default table. The file
2542                         <filename>examples/pdb/mysql/mysql.dump</filename> contains the correct queries to
2543                         create the required tables. Use the command:
2544 <screen>
2545 &rootprompt;<userinput>mysql -u<replaceable>username</replaceable> -h<replaceable>hostname</replaceable> -p<replaceable>password</replaceable> \
2546         <replaceable>databasename</replaceable> &lt; <filename>/path/to/samba/examples/pdb/mysql/mysql.dump</filename></userinput>
2547 </screen>
2548                         </para>
2549                 </sect3>
2550
2551                 <sect3>
2552                 <title>Configuring</title>
2553
2554                         <para>This plug-in lacks some good documentation, but here is some brief information. Add the following to the
2555                         <smbconfoption name="passdb backend"/> variable in your &smb.conf;:
2556 <smbconfblock>
2557 <smbconfoption name="passdb backend">[other-plugins] mysql:identifier [other-plugins]</smbconfoption>
2558 </smbconfblock>
2559                         </para>
2560
2561                         <para>The identifier can be any string you like, as long as it does not collide with
2562                         the identifiers of other plugins or other instances of pdb_mysql. If you
2563                         specify multiple pdb_mysql.so entries in <smbconfoption name="passdb backend"/>, you also need to
2564                         use different identifiers.
2565                         </para>
2566
2567                         <para>
2568                         Additional options can be given through the &smb.conf; file in the <smbconfsection name="[global]"/> section.
2569                         Refer to <link linkend="mysqlpbe">Basic smb.conf Options for MySQL passdb Backend</link>.
2570                         </para>
2571
2572                         <table frame="all" id="mysqlpbe">
2573                                 <title>Basic smb.conf Options for MySQL passdb Backend</title>
2574                                 <tgroup cols="2">
2575                                         <colspec align="left"/>
2576                                         <colspec align="justify" colwidth="1*"/>
2577                                 <thead>
2578                                         <row><entry>Field</entry><entry>Contents</entry></row>
2579                                 </thead>
2580                                 <tbody>
2581                                         <row><entry>mysql host</entry><entry>Host name, defaults to `localhost'</entry></row>
2582                                         <row><entry>mysql password</entry><entry></entry></row>
2583                                         <row><entry>mysql user</entry><entry>Defaults to `samba'</entry></row>
2584                                         <row><entry>mysql database</entry><entry>Defaults to `samba'</entry></row>
2585                                         <row><entry>mysql port</entry><entry>Defaults to 3306</entry></row>
2586                                         <row><entry>table</entry><entry>Name of the table containing the users</entry></row>
2587                                 </tbody>
2588                                 </tgroup>
2589                         </table>
2590
2591                         <warning>
2592                         <para>
2593                         Since the password for the MySQL user is stored in the &smb.conf; file, you should make the &smb.conf; file
2594                         readable only to the user who runs Samba. This is considered a security bug and will soon be fixed.
2595                         </para>
2596                         </warning>
2597
2598                         <para>Names of the columns are given in <link linkend="moremysqlpdbe">MySQL field names for MySQL
2599                         passdb backend</link>.  The default column names can be found in the example table dump.
2600                          </para>
2601
2602                 <para>
2603                         <table frame="all" id="moremysqlpdbe">
2604                                 <title>MySQL field names for MySQL passdb backend</title>
2605                                 <tgroup cols="3" align="justify">
2606                                         <colspec align="left"/>
2607                                         <colspec align="left"/>
2608                                         <colspec align="justify" colwidth="1*"/>
2609                         <thead>
2610                                 <row><entry>Field</entry><entry>Type</entry><entry>Contents</entry></row>
2611                         </thead>
2612                         <tbody>
2613                                 <row><entry>logon time column</entry><entry>int(9)</entry><entry>UNIX timestamp of last logon of user</entry></row>
2614                                 <row><entry>logoff time column</entry><entry>int(9)</entry><entry>UNIX timestamp of last logoff of user</entry></row>
2615                                 <row><entry>kickoff time column</entry><entry>int(9)</entry><entry>UNIX timestamp of moment user should be kicked off workstation (not enforced)</entry></row>
2616                                 <row><entry>pass last set time column</entry><entry>int(9)</entry><entry>UNIX timestamp of moment password was last set</entry></row>
2617                                 <row><entry>pass can change time column</entry><entry>int(9)</entry><entry>UNIX timestamp of moment from which password can be changed</entry></row>
2618                                 <row><entry>pass must change time column</entry><entry>int(9)</entry><entry>UNIX timestamp of moment on which password must be changed</entry></row>
2619                                 <row><entry>username column</entry><entry>varchar(255)</entry><entry>UNIX username</entry></row>
2620                                 <row><entry>domain column</entry><entry>varchar(255)</entry><entry>NT domain user belongs to</entry></row>
2621                                 <row><entry>nt username column</entry><entry>varchar(255)</entry><entry>NT username</entry></row>
2622                                 <row><entry>fullname column</entry><entry>varchar(255)</entry><entry>Full name of user</entry></row>
2623                                 <row><entry>home dir column</entry><entry>varchar(255)</entry><entry>UNIX homedir path (equivalent of the <smbconfoption name="logon home"/> parameter.</entry></row>
2624                                 <row><entry>dir drive column</entry><entry>varchar(2)</entry><entry>Directory drive path (e.g., <quote>H:</quote>)</entry></row>
2625                                 <row><entry>logon script column</entry><entry>varchar(255)</entry><entry>Batch file to run on client side when logging on</entry></row>
2626                                 <row><entry>profile path column</entry><entry>varchar(255)</entry><entry>Path of profile</entry></row>
2627                                 <row><entry>acct desc column</entry><entry>varchar(255)</entry><entry>Some ASCII NT user data</entry></row>
2628                                 <row><entry>workstations column</entry><entry>varchar(255)</entry><entry>Workstations user can logon to (or NULL for all)</entry></row>
2629                                 <row><entry>unknown string column</entry><entry>varchar(255)</entry><entry>Unknown string</entry></row>
2630                                 <row><entry>munged dial column</entry><entry>varchar(255)</entry><entry>Unknown</entry></row>
2631                                 <row><entry>user sid column</entry><entry>varchar(255)</entry><entry>NT user SID</entry></row>
2632                                 <row><entry>group sid column</entry><entry>varchar(255)</entry><entry>NT group SID</entry></row>
2633                                 <row><entry>lanman pass column</entry><entry>varchar(255)</entry><entry>Encrypted lanman password</entry></row>
2634                                 <row><entry>nt pass column</entry><entry>varchar(255)</entry><entry>Encrypted nt passwd</entry></row>
2635                                 <row><entry>plain pass column</entry><entry>varchar(255)</entry><entry>Plaintext password</entry></row>
2636                                 <row><entry>acct ctrl column</entry><entry>int(9)</entry><entry>NT user data</entry></row>
2637                                 <row><entry>unknown 3 column</entry><entry>int(9)</entry><entry>Unknown</entry></row>
2638                                 <row><entry>logon divs column</entry><entry>int(9)</entry><entry>Unknown</entry></row>
2639                                 <row><entry>hours len column</entry><entry>int(9)</entry><entry>Unknown</entry></row>
2640                                 <row><entry>bad password count column</entry><entry>int(5)</entry><entry>Number of failed password tries before disabling an account</entry></row>
2641                                 <row><entry>logon count column</entry><entry>int(5)</entry><entry>Number of logon attempts</entry></row>
2642                                 <row><entry>unknown 6 column</entry><entry>int(9)</entry><entry>Unknown</entry></row>
2643                         </tbody></tgroup>
2644                 </table>
2645                 </para>
2646
2647                         <para>
2648                         You can put a colon (:) after the name of each column, which
2649                         should specify the column to update when updating the table. You can also specify nothing behind the colon, in which case the field data will not be updated. Setting a column name to <parameter>NULL</parameter> means the field should not be used.
2650                         </para>
2651
2652                         <para><link linkend="mysqlsam">An example configuration</link> is shown in <link
2653                         linkend="mysqlsam">Example Configuration for the MySQL passdb Backend</link>.
2654                         </para>
2655
2656                         <example id="mysqlsam">
2657                         <title>Example Configuration for the MySQL passdb Backend</title>
2658                         <smbconfblock>
2659                         <smbconfsection name="[global]"/>
2660                         <smbconfoption name="passdb backend">mysql:foo</smbconfoption>
2661                         <smbconfoption name="foo:mysql user">samba</smbconfoption>
2662                         <smbconfoption name="foo:mysql password">abmas</smbconfoption>
2663                         <smbconfoption name="foo:mysql database">samba</smbconfoption>
2664                         <smbconfcomment>domain name is static and can't be changed</smbconfcomment>
2665                         <smbconfoption name="foo:domain column">'MYWORKGROUP':</smbconfoption>
2666                         <smbconfcomment>The fullname column comes from several other columns</smbconfcomment>
2667                         <smbconfoption name="foo:fullname column">CONCAT(firstname,' ',surname):</smbconfoption>
2668                         <smbconfcomment>Samba should never write to the password columns</smbconfcomment>
2669                         <smbconfoption name="foo:lanman pass column">lm_pass:</smbconfoption>
2670                         <smbconfoption name="foo:nt pass column">nt_pass:</smbconfoption>
2671                         <smbconfcomment>The unknown 3 column is not stored</smbconfcomment>
2672                         <smbconfoption name="foo:unknown 3 column">NULL</smbconfoption>
2673                         </smbconfblock>
2674                         </example>
2675                 </sect3>
2676
2677                 <sect3>
2678                 <title>Using Plaintext Passwords or Encrypted Password</title>
2679
2680                         <para>
2681 <indexterm><primary>encrypted passwords</primary></indexterm>
2682                         I strongly discourage the use of plaintext passwords; however, you can use them.
2683                         </para>
2684
2685                         <para>
2686 <indexterm><primary>plaintext passwords</primary></indexterm>
2687                         If you would like to use plaintext passwords, set
2688                         `identifier:lanman pass column' and `identifier:nt pass column' to
2689                         `NULL' (without the quotes) and `identifier:plain pass column' to the
2690                         name of the column containing the plaintext passwords.
2691                         </para>
2692
2693                         <para>
2694                         If you use encrypted passwords, set the 'identifier:plain pass
2695                         column' to 'NULL' (without the quotes). This is the default.
2696                         </para>
2697
2698                 </sect3>
2699
2700                 <sect3>
2701                 <title>Getting Non-Column Data from the Table</title>
2702
2703                         <para>
2704                         It is possible to have not all data in the database by making some "constant."
2705                         </para>
2706
2707                         <para>
2708                         For example, you can set `identifier:fullname column' to
2709                         something like <command>CONCAT(Firstname,' ',Surname)</command>
2710                         </para>
2711
2712                         <para>
2713                         Or, set `identifier:workstations column' to:
2714                         <command>NULL</command></para>.
2715
2716                         <para>See the MySQL documentation for more language constructs.</para>
2717
2718                 </sect3>
2719         </sect2>
2720
2721         <sect2 id="XMLpassdb">
2722         <title>XML</title>
2723
2724         <para>
2725 <indexterm><primary>SAM backend</primary><secondary>xmlsam</secondary></indexterm>
2726 <indexterm><primary>libxml2</primary></indexterm>
2727 <indexterm><primary>pdb_xml</primary></indexterm>
2728                 This module requires libxml2 to be installed.</para>
2729
2730                 <para>The usage of pdb_xml is fairly straightforward. To export data, use:
2731                 </para>
2732
2733                 <para>
2734 <indexterm><primary>pdbedit</primary></indexterm>
2735                         <prompt>$ </prompt> <userinput>pdbedit -e xml:filename</userinput>
2736                 </para>
2737
2738                 <para>
2739                 where filename is the name of the file to put the data in.
2740                 </para>
2741
2742                 <para>
2743                 To import data, use:
2744                 <prompt>$ </prompt> <userinput>pdbedit -i xml:filename</userinput>
2745                 </para>
2746         </sect2>
2747 </sect1>
2748
2749 <sect1>
2750 <title>Common Errors</title>
2751
2752         <sect2>
2753                 <title>Users Cannot Logon</title>
2754
2755                 <para><quote>I've installed Samba, but now I can't log on with my UNIX account! </quote></para>
2756
2757                 <para>Make sure your user has been added to the current Samba <smbconfoption name="passdb backend"/>.
2758                 Read the <link linkend="acctmgmttools">Account Management Tools,</link> for details.</para>
2759
2760         </sect2>
2761
2762         <sect2>
2763         <title>Users Being Added to the Wrong Backend Database</title>
2764
2765         <para>
2766         A few complaints have been received from users who just moved to Samba-3. The following
2767         &smb.conf; file entries were causing problems: new accounts were being added to the old
2768         smbpasswd file, not to the tdbsam passdb.tdb file:
2769         </para>
2770
2771         <para>
2772         <smbconfblock>
2773         <smbconfsection name="[global]"/>
2774         <member>...</member>
2775         <smbconfoption name="passdb backend">smbpasswd, tdbsam</smbconfoption>
2776         <member>...</member>
2777         </smbconfblock>
2778         </para>
2779
2780         <para>
2781         Samba will add new accounts to the first entry in the <emphasis>passdb backend</emphasis>
2782         parameter entry. If you want to update to the tdbsam, then change the entry to:
2783         </para>
2784
2785         <para>
2786 <smbconfblock>
2787 [globals]
2788 ...
2789 <smbconfoption name="passdb backend">tdbsam, smbpasswd</smbconfoption>
2790 ...
2791 </smbconfblock>
2792         </para>
2793
2794         </sect2>
2795
2796         <sect2>
2797         <title>Configuration of <parameter>auth methods</parameter></title>
2798
2799         <para>
2800         When explicitly setting an <smbconfoption name="auth methods"/> parameter,
2801         <parameter>guest</parameter> must be specified as the first entry on the line &smbmdash;
2802         for example, <smbconfoption name="auth methods">guest sam</smbconfoption>.
2803         </para>
2804
2805         </sect2>
2806
2807 </sect1>
2808
2809 </chapter>