Quest Software (logo)

Quest Samba Suite

Using Samba with Vintela Authentication Services

A short guide to Samba's capabilities and how best to integrate it with Vintela Authentication Services (VAS) using the Quest Samba server packages.

What is Samba?

Samba is a suite of tools for sharing files and printers using the CIFS suite of protocols. Samba can operate either as a standalone server, a member of a Microsoft domain or as a domain controller1. Samba runs on POSIX-compatible systems and is tested regularly on the most common Unix and Linux platforms.

What can Samba do?

Samba can share POSIX file systems from a Unix/Linux host to Windows and other CIFS compliant clients such as Mac OS X, DOS, and Linux.2

A Samba file server can either stand alone, or participate as a full Active Directory domain member. Samba can either obtain AD membership on its own or share the membership obtained by Vintela Authentication Services. Samba supports or emulates all features of the CIFS protocol.

Samba uses advanced file system features like POSIX ACLs, extend attributes and quota support to achieve maximum compatibility with CIFS. Advanced operating systems features such as opportunistic locking are used to improve performance when available.

Not all Unix/Linux systems provide the advanced features that Samba can use. When a feature is not present, Samba can sometimes emulate that feature, but in other cases it will simply not be available for use by clients. However, the core function of serving files is always there.

The best Linux platform on which to run Samba is one with on a recent (2.6.x) Linux kernel and with a file system that supports both ACLs and EAs (e.g. ext2, ext3, jfs, xfs, reiser3). Other Unix platforms support many extended features, for example Solaris.

Solving the identity management problem

A key problem when integrating Samba with Active Directory is that while Windows uses 128-bit SIDs (security identifiers) to identify owners of files, most POSIX filesystems use smaller UIDs (user identifiers) and GIDs (group identifiers). Samba addresses this by mapping SIDs to UIDs. It provides an IDMAP (identity mapping) module interface as part of its Winbind daemon. The Samba administrator can plug-in different IDMAP modules, each implementing a different method to store and/or assign mappings between SIDs, UIDs and GIDs.

Quest provides a bridge from Samba's IDMAP to VAS in the form of a daemon called vasidmapd. It interoperates with Samba's idmap_ldap module in order to resolve SID queries over LDAP via VAS. The vasidmapd daemon services requests by idmap_ldap by implementing a 'bare bones' LDAP server on the loopback interface. The daemon relays queries directly to VAS which obtains information about the mapping from the local VAS NSS (name service switch) cache.

Consequently, the Quest Samba suite of Samba packages provides a fully functional UPM/PSS aware Samba server that uses Vintela Authentication Services for all Unix-enabled user and group mappings.

Advantages of Vintela Authentication Services over Samba's ADS support

Samba can become an ADS domain member without help, but to provide correct file security information it requires configuration of a mapping between Unix user/group account and AD user/group accounts. The way Samba does this is with its winbind component. Winbind can either store the mapping tables on the local system, on a centralized server or even inside Active Directory when using the appropriate idmap modules.

Like winbind, VAS uses Active Directory's RFC2307 identity mapping, but Winbind lacks many features that Vintela Authentication Services provides already. Such features include Unix Personality Management (UPM), Personality Service Switch (PSS), support for NIS maps, LDAP proxy, Vintela Group Policy, MMC snapins, the schema extension wizard, and reporting tools. These tools and features have been specially developed by Quest to solve the difficult class of enterprise integration problems we see in complex heterogeous Unix and Active Directory environments.

Making Samba use Vintela Authentication Services

The vasidmap package contains all the idmap related components. Before installing this package please make sure that you have properly installed and configured Vintela Authentication Services (VAS) (version 3.0.2 or later).

The vasidmap package contains a service daemon, a few test utilities and a configuration script that modifies smb.conf and vas.conf. Before using the package you should ensure your machine is joined to the Active Directory domain with VAS. This is usually done with the vastool join command as a normal part of installing VAS.

Next, you should consider if you need to adjust your system's native Kerberos configuration to match VAS. This is necessary when the installation of Samba server that you use is linked against the system Kerberos libraries. (Quest Samba server isn't.) Running the /opt/quest/sbin/vas-krb5-config script will modify files such as /etc/krb5.conf so that VAS's Active Directory configuration becomes available to all software that use the system Kerberos library; such as Samba. 

# /opt/quest/sbin/vas-krb5-config

Finally, you will need to invoke the /opt/quest/sbin/vas-samba-config script. This will check your smb.conf and vas.conf files and modify them as needed. It may then proceed to reset your machine's host password if you wish to support legacy NTLM authentication. 

# /opt/quest/sbin/vas-samba-config

If your particular version of Samba is not correctly found by the vas-samba-config script, then you should specify its location explicitly with the -S option. More information is found in the vas-samba-config(1) manual page. 

# /opt/quest/sbin/vas-samba-config -S /usr/local

For versions of VAS prior to 3.1, if you rejoin your machine to the domain you may need to re-run the vas-samba-config helper script after re-joining. This is because of the problem of host key renewal. Running net ads testjoin will tell you if this is necessary.

Once you have the vasidmapd, winbind and smbd daemons running, your system will be ready. Quest Samba server uses the configuration information located in /etc/opt/quest/samba/smb.conf.

WARNING: The vas-samba-config script will reset your local machine password, which may invalidate tickets previously acquired for the host. This is a known bug with keeping previous 'kvno's that will be fixed in VAS 3.1. For earlier versions of VAS, do not install this package on production machines that exports Kerberos-enabled services (Quest OpenSSH, apache + mod_auth_vas) before warning the users. Windows Users can flush their local ticket cache by using Ctrl-Alt-Delete to lock and unlock their screen; Unix VAS users will need to run vastool kdestroy followed by vastool kinit.

The Quest Samba packages embed the latest Heimdal release of Kerberos and OpenLDAP libraries. The Kerberos libraries are pre-configured to find configuration directives first in /etc/opt/quest/vas/vas.conf and then from /etc/krb5.conf. If you are using a different Samba package, you should instead set the environment variable KRB5_CONFIG before running the smbd server: 

KRB5_CONFIG=/etc/opt/quest/vas/vas.conf

The Quest Samba server packages do not include the optional winbind PAM and NSS modules as these are made redundant by the PAM and NSS modules that come with Vintela Authentication Services.

Changes made to smb.conf

This section describes the parameters used for VAS intergration or modified by vas-samba-config.

workgroup
This parameter sets the pre-Windows 2000 domain name of the server. The vas-samba-config script will automatically determine the workgroup name of with the currently joined domain and update smb.conf. 
workgroup = EXAMPLE
realm
This parameter specifies the Active Directory domain name, also known as the Kerberos realm. If unspecified, Quest Samba server obtains the current domain from krb5.conf or vas.conf at run time. The vas-samba-config script sets this parameter to the currently joined domain. 
realm = EXAMPLE.COM
security
This specifies the role of the server. It must be set to ads which means Active Directory Server. The vas-samba-config script sets this parameter to 
security = ads
use spnego
This parameter specifies whether RFC2478 authentication should be used. It must be enabled so as to allow encapsulated Kerberos authentication. The vas-samba-config script sets this parameter to 
use spnego = yes
use kerberos keytab
This parameter specifies whether Samba should keep the machine password (host key) in a private database, or in the keytab file named by the external Kerberos library. VAS keeps its machine password in the keytab file host.keytab, so this parameter must be enabled for interoperability. The vas-samba-config script sets this parameter to 
use keberos keytab = yes
machine password timeout
Both Samba and VAS attempt to reset the machine password approximately once a month. This parameter must be set to 0 so that only VAS changes the machine password, otherwise vasd may cease functioning. Please also see the changes on vas.conf, below. The vas-samba-config script sets this parameter to 
machine password timeout = 0
ldap admin dn
This parameter specifies the credentials used by Samba's ldap_idmap backend to authenticate to the LDAP server providing an identity map. The credentials are ignored when using vasidmapd, however a well-formed distinguished name is required by Samba. The vas-samba-config also sets the ldap admin password to a non-empty string with smbpasswd to stop Samba from complaining. The vas-samba-config script sets the ldap admin dn parameter to 
ldap admin dn = CN=VasIdmapAdmin
idmap backend
This parameter specifies the identity mapping service to use. For normal use with vasidmapd this parameter should be set to 
ldap:ldap://localhost
If the host already runs an LDAP service, then vasidmapd should be configured to run on a diffent port (say 12345) with the argument -p12345, and this parameter should be changed to 
ldap:ldap://localhost:12345
By default, the vas-samba-config script sets this parameter to 
ldap:ldap://localhost
idmap uid
idmap gid
These parameters specify the range of values that a backend may use when allocating new mappings. The vasidmapd service does not use this information (because it does not allocate new UIDs), however Samba requires that a range be specified. The vas-samba-config script sets these parameters to 
idmap uid = 1-2147483647
idmap gid = 1-2147483647
idmap expire time
This parameter applies only to versions of Samba after 3.0.29 and controls the positive caching timeout for mappings in seconds. On busy servers in environments where UID and GID changes in Active Directory are unlikely or very rare, you can raise this timeout to improve peformance (e.g. 1 hour) with the understanding that changes to UIDs and GIDs may not be reflected in server operations for up to that time. New mappings are not affected by this parameter and are made available immediately. The vas-samba-config script sets this parameter to 
idmap expire time = 300
winbind nested groups
This parameter tells Samba whether or not to use winbind when resolving some groups. For now, this option is disabled by the vas-samba-config to avoid corner case problems. 
winbind nested group = no
username map script
This parameter specifies the location of a program that converts between UIDs, GIDs, SIDs and usernames. In UPM/PSS environments, the unix user name may not match the Windows user name, in which case Samba must be made aware of the mapping. The vasidmap can provide this information. This parameter is currently not set by vas-samba-config because of a known problem in Samba 3 which arises when the Windows user's primary group SID is not a Unix-enabled group (typically Domain Users) and a known problem with vasidmap that cannot provide the correct map in some domain configuration. 
username map script = /opt/quest/bin/vasidmap
obey pam restrictions
Samba can check with PAM before allowing a user to mount a share. Only the account and session stacks are checked, under the service name samba.

Changes made to vas.conf and krb5.conf

The Quest Samba server package is compiled statically with Heimdal Kerberos. This version of Heimdal has been modified to look for both /etc/opt/quest/vas/vas.conf and /etc/krb5.conf. While the vas-samba-config does not modify /etc/krb5.conf, you must ensure that it does not contain bogus or conflicting directives.

If the version of Samba that you are configuring uses the system Kerberos libraries then you should run the vas-krb5-config script to update it.

Quest recommends that you first back-up and delete /etc/krb5.conf if it is not otherwise used. Then run vas-krb5-config to re-create it. This may enable other Kerberos-aware software on your system to use VAS's Kerberos configuration to Active Directory. 

# mv /etc/krb5.conf /etc/krb5.conf.my-backup
# /opt/quest/sbin/vas-krb5-config
# /opt/quest/sbin/vas-samba-config

vas-samba-config will add one parameter to vas.conf to inform Samba of automatic machine password changes. Vintela Authentication Services periodically changes the machine password, and Samba requires knowledge of this to perform NTLM authentication. A small script provides this function. 

[vasd]
password-change-script = /opt/quest/libexec/vas-set-samba-password

On installations using earlier versions than VAS 3.1, the vas-samba-config script will instead disable automatic password changes. 

[vasd]
password-change-interval = 0

The default vas.conf file should work for most Samba deployments. However, if you have problems locating the domain controllers, you can use vastool info toconf to specify a REALM and a DC to use.

To instruct Samba to use a preferred DC you can also set the option password server in smb.conf. By specifying the FQDN of the preferred DC as the first entry and appending a wildcard star character, Samba will be able to use a different domain controller by querying the DNS records if the preferred one is down.
Example: 

password server = w2k3.example.com *

Testing the Samba server is properly configured

There are a couple of basic tests that can be done to make sure your Samba server is properly configured.

First of all, after each edit of the smb.conf file run the tool named testparm. This tool will check that parameter names are correct. It will also confirm that the Samba server is configured as a domain member.

After you have run vas-samba-config you can test that Samba recognizes itself as correctly joined to the windows domain. Run 

# net ads testjoin
# net rpc testjoin

These two command will confirm that Samba is correctly joined both using the Kerberos/AD and the NTLM/RPC protocols.

If the rpc testjoin takes a long time, or fails, you may need to set the wins server parameter in smb.conf.

Finally, get a shell on your machine as a normal user (make sure you have a Kerberos ticket) and run: 

$ smbclient //server-fqdn/username
where server-fqdn is the fully-qualified hostname of your server, and username is your username.

This will let you browse your home directory. (It is assumed that you have not modified the default [homes] section in the Samba configuration file. Use any other share you have configured, otherwise.)

If you are upgrading a previous Samba server you may find directives such as valid users/invalid users on some shares. Please note that recently the Samba configuration rules have been tightened and now Samba requires strict identification of users and groups in these directives. Therefore if you want to apply one of these rules to domain users make sure the name is fully qualified. As of Samba 3.0.23 you should use the forms DOMAIN\username and DOMAIN\groupname to identify domain users and groups. DOMAIN is always the short domain name, not the Active Directory domain name (Kerberos realm). Also, remember to use quotes surrounding names with spaces. For example: 

valid users = EXAMPLE\alice @"EXAMPLE\Domain Users"

If you have problems you may raise the log level of your Samba sever to 5 (initially) or 10 (for high quantity of output), and make sure log size is set to 0 so that your logs are not rotated. Quest recommend you do not use higher log levels and absolutely never use log level = 100 or it will fill up your disk with packet dumps.

Troubleshooting notes

Common problems

I changed the host/ password and now samba logins don't work. The logs show failed to get schannel session key from HOST for domain DOMAIN: Error was NT_STATUS_ACCESS_DENIED
On older versions of VAS, if you changed the password with something like 
# vastool -u host/ passwd -r  or
# vastool -u Administrator passwd -r host/
then the two machine secrets for the host will have become desynchronized and the samba server will shortly discover it can't talk to any other domain controllers.

The reason for desynchronisation is that copies of the host's secret key are kept in VAS's /etc/opt/quest/vas/host.keytab and Samba's /etc/opt/quest/samba/secrets.tdb. And only one of them was updated.

You can, and should, reset the password in both files simultaneously with the following command: 

# /opt/quest/bin/vastool -q -u host/ passwd -r -o |
  /opt/quest/libexec/vas-set-samba-password
# net ads testjoin
With earlier versions of vasidmap, vas-set-samba-password may not be available, in which case use Samba's net directly, e.g.: 
# /opt/quest/bin/vastool -q -u host/ passwd -r -o |
  net -f -i changesecretpw
smbclient is complaining NT_STATUS_CANT_ACCESS_DOMAIN_INFO, or Windows user is seeing the error "\\host\share is not accessible. You might not have permission to use this network resource. Contact the administrator of this server to find out if you have access permissions. Configuration information could not be read from the domain controller, either because the machine is unavailable, or access has been denied."
This can be caused by having the wrong workgroup in /etc/smb.conf and is fixed by running 
# vas-samba-config
smbclient is complaining that it cannot find KDC
This could be caused by interference from an existing /etc/krb5.conf. Either remove that file, or look for a line containing srv_lookup = false and remove that. The Quest Samba server's Heimdal implementation was modified to first load /etc/opt/quest/vas/vas.conf and then /etc/krb5.conf. Please also try running /opt/quest/sbin/vas-krb5-config.
Access is denied for some unix users when smb.conf contains a username map:
The primary group of a unix-enabled VAS user must itself be unix-enabled, or Samba will refuse to serve it. Samba 3.0.23a treats the primary SID group as the primary GID. A workaround for this problem is to unix-enable the 'Domain Users' group.
smbd frequently complains reply_spnego_kerberos(286) Username DOMAIN\username is invalid on this system:
This usually happens when a non unix-enabled account performs a network browse. It is often a workstation account, appearing as DOMAIN\HOST$. The account successfully authenticates itself to the samba server, but there is no UID associated with it (as it's not VAS-enabled). The messages are harmless, and indicate that some of your shares can't be accessed by non-unix enabled users.

To remove these messages, do ONE of the following:

  1. specify "log level = 0" in smb.conf. This will hide those messages (and other messages).
  2. specify "map to guest = bad uid" in smb.conf. This will map non-VAS-enabled users who correctly authenticate to the 'nobody' UID. If you have your share set as writeable by those users, then they may be able to create files that appear to be owned by 'nobody'.
  3. VAS-enable those accounts.
smbd won't start: ld.so.1: vasidmapd: fatal: relocation error: file /opt/quest/sbin/vasidmapd: symbol vas_group_get_grinfo: referenced symbol not found
vasidmap uses new features not available in earlier versions of VAS. Upgrade VAS to 3.0.2 or later.
smbclient complains spnego_gen_negTokenTarg failed: No such file or directory; session setup failed: SUCCESS - 0:
Your credential cache is missing. Run 
$ vastool kinit
to login and get a new TGT, then try again.
winbindd exits after complaining fetch_ldap_pw: neither ldap secret retrieved!; ldap_connect_system: Failed to retrieve password from secrets.tdb; Connection to LDAP server failed for the 1 try!
Somehow the secrets.tdb file has become corrupt. The following may help: 
# /opt/quest/bin/tdbtool /etc/opt/quest/samba/secrets.tdb
tdb> insert SECRETS/LDAP_BIND_PW/CN=VasIdmapAdmin secret
tdb> quit
and then restart the winbindd-quest service. The secret value is actually ignored when recieved by vasidmapd, so it can be anything.
I re-joined the server and now my Windows users are prompted for a password.
Ask your Windows users to flush their credentials with Ctrl-Alt-Del and lock workstation. Entering a password to unlock a workstation forces fresh credentials to be obtained for all services.
smb complains: smbd/sesssetup.c:reply_spnego_kerberos(##) Failed to verify incoming ticket!
This indicates a problem with the Keberos ticket that the client has obtained to use the Samba service (smbd). It is possible that either the ticket key is stale or the service name in the ticket is wrong.

The ticket key can be stale if you recently rejoined the Samba server to the domain or reset the machine secret (host key). In this case, the client should flush their credential cache (vastool kdestroy/kinit on Unix, or Ctrl-Alt-Del, lock and unlock display on windows, or wait 8 hours for a refresh).

Another explanation is that the name in the ticket is wrong. This can happen because clients typically ask Active Directory for a cifs/ ticket, but cifs/ is aliased to host/. When Samba receives the ticket it dispatches it to the local Kerberos library, which searches a keytab file for a matching service name.

If you are using MIT Kerberos (eg with Red Hat samba), it is known to be very sensitive to the service name. In this case you may need to arrange to have a separate cifs/ service in Active Directory (with corresponding entries in the system keytab), or you can create a duplicate from existing keytab entries using ktutil or ktedit.

Alternatively, you can use a Heimdal Kerberos library with Samba. Heimdal ignores the name in the ticket and simply tries all the keys it can find until one works. Quest-samba's binaries include Heimdal Kerberos.

Troubleshooting steps

These notes assume that VAS is installed and working correctly. They focus on problems with Samba configuration.

Advanced troubleshooting steps

References

Footnotes

  1. Samba can perform domain controller functionality ONLY using the NT4 style domain protocols. Samba 3 CANNOT provide AD style domain controller functionality. While Samba4 is targeting AD domain controller compatibility it is still a development project and not suitable nor close to production level usability.
  2. While it is possible to share non POSIX file systems (Like a FAT32 file system mounted on a Linux host) it is not recommended and functionality may be severely limited
  3. Each user/group that need to be used on the Samba server MUST be UnixEnabled.