Sorry, I do not know SGML but I thought some documentation should exist:

Q. I work in a large corporation that has multiple NT user domains that trust each other (and in some cases there are also isolated/non-trusted domains).  How can I get pam_smb to work in that environment?
A:  This is a several part answer:
a) If your user names are unique across domains, you are in great luck.  Simply make the first line of your pam_smb.conf contain "_TRUSTEDDOMAINS_" for the domain followed by 2 domain controllers in the standard pam_smb.conf fashion.  It is recommended; although not necessary, to list the actual domain names and domain controllers on following lines.
b) If you user names are not 100% unique, that is still all right; however, it may take a bit more administration effort.  As above the first line should contain the "_TRUSTEDDOMAINS_" followed by 2 domain controllers.  The following lines must contain the each actual domain and controllers.  Use the "pam_smb.usermap" to list all the non-unique usernames, in the following format.  One entry per line: unixname=DOMAIN\ntname.   This method will also work when dealing with a mix of trusted and non-trusted domains.  Users in the non trusted domains will require the usermap entry.

Q. What is the recommended location in the pam.conf or equiv for pam_smb?
A. It is reccommended that pam_smb be listed after the local system authentication.  This is because in larger environments, an NT domain controller may have X number of failed requests for a user account cause the account to lock.  Therefore, by listing it second to local authentication, a valid local authentication will not cause a "failed" attempted from the perspective of the NT Domain controllers.  You will most likely need to change the AUTH entry before it from required to sufficient and remember to include the "use_first_pass" option on the pam_smb line.  Example:

auth       sufficient  /lib/security/pam_pwdb.so shadow nullok
auth       required   /lib/security/pam_smb_auth.so debug cachetime=20 use_first_pass

Q. I understand that pam_smb keeps an authentication cache, need I be concerned that someone will have clear text access or decrypt the password in the cache?
A. For version 1.9.8 (development version) you need be very concerned! However, there is some excellent news: for releases post 1.9.8 the authentication cache only stores MD5 hashes of the passwords.  Optionally, you could use the Makefile.crypt in the pamsmbd directory to replace the MD5 hash with standard UNIX crypt.  Both are one way hashes with no means for decryption thus keeping anything in the cache is fairly safe.  Also, the cache files should be stored similar to Shadows files on a system, such that only root (the user running pamsmbd) should have any access to it.  The largest difference between crypt and MD5 from the pam_smb perspective is that UNIX crypt only uses the first 8 characters of the password.  Being the NT passwords can be longer than 8 characters, we believe the MD5 is probably the safer way to go.


Q. How do I control the length of time to cache an authentication?
A. This can be dynamicly controled without requiring a restart of any component by simply making changes to your pam.conf (Solaris/HP-UX/etc...) or appropriate files in your "pam.d" directory.  You will need to pass the "cachetime=N" param on the pam_smb line.  Where N = the number of minutes to cache the authentication.  The default value is 15 minutes.  If N=0 then, pamsmbd will not keep a cache.  If N=-1, then pamsmbd will not expire (/not timeout) a cached entry.

auth       required   /lib/security/pam_smb_auth.so cachetime=20 use_first_pass

Q.  How do I control debugging of the module and daemon?
A. This can be dynamicly controled without requiring a restart of any component by simply making changes to your pam.conf (Solaris/HP-UX/etc...) or appropriate files in your "pam.d" directory.  You will need to pass the "debug" param on the pam_smb line.

auth       required   /lib/security/pam_smb_auth.so debug use_first_pass

Q. What do the different signals do when sent to the daemon?
A. There are several:
a) TERM - exits the daemon.
b) USR1 - resets the user authentication cache file
c) HUP - re-reads the configuration file and pam_smb.usermap file.
d) USR2 - should print the number of users in the cache to syslog (this may need some more testing...)