Quest ID Mapper

Using Samba with Quest Authentication Services

A short guide to Samba's capabilities and how best to integrate it with Quest Authentication Services (QAS).

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 Quest 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 Quest Authentication Services 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 Quest Authentication Services. 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 Quest Authentication Services which obtains information about the mapping from the local Quest Authentication Services NSS (name service switch) cache.

Consequently, Samba in conjunction with vasidmap provides a fully functional UPM/PSS-aware Samba server that uses Quest Authentication Services for all Unix-enabled user and group mappings.

Advantages of Quest 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, Quest Authentication Services uses Active Directory's RFC2307 identity mapping, but Winbind lacks many features that Quest Authentication Services provides already. Such features include Unix Personality Management (UPM), Personality Service Switch (PSS), support for NIS maps, LDAP proxy, Group Policy integration, 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 Quest 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 Quest Authentication Services (QAS) (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 Quest Authentication Services. This is usually done with the vastool join command as a normal part of installing Quest Authentication Services.

Next, you should consider if you need to adjust your system's native Kerberos configuration to match Quest Authentication Services. This is necessary when the installation of Samba server that you use is linked against the system Kerberos libraries. Running the /opt/quest/sbin/vas-krb5-config script will modify files such as /etc/krb5.conf so that Quest Authentication Services'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 Quest Authentication Services 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.

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 Quest Authentication Services 3.1. For earlier versions of Quest Authentication Services, do not install this package on production machines that export 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-enabled users will need to run vastool kdestroy followed by vastool kinit.

Changes made to smb.conf

This section describes the parameters used for intergration with Quest Authentication Services or modified by vas-samba-config.

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
This parameter specifies the Active Directory domain name, also known as the Kerberos realm. If unspecified, vasidmap 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.
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
(Replaced in Samba 3.4.0 with kerberos method)
This parameter only applies to Samba versions 3.3 and older. It 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. Quest Authentication Services 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
kerberos method
(Available in Samba 3.4.0 and newer)
When the kerberos method is in "dedicated keytab" mode, dedicated keytab file must be set to specify the location of the keytab file.
dedicated keytab
(Available in Samba 3.4.0 and newer)
Specifies the path to the kerberos keytab file when kerberos method is set to "dedicated keytab".
machine password timeout
Both Samba and Quest Authentication Services attempt to reset the machine password approximately once a month. This parameter must be set to 0 so that only Quest Authentication Services 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
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
By default, the vas-samba-config script sets this parameter to
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

If you are using your operating system's Samba package, you should run vas-krb5-config to update the /etc/krb5.conf file which will be used by the Kerberos subsystem of your Samba server.

We recommend that you first back-up and delete /etc/krb5.conf, then run vas-krb5-config to re-create it with settings determined by QAS. This may enable other Kerberos-aware software on your system to use Quest Authentication Services's Kerberos configuration to Active Directory.

# mv /etc/krb5.conf /etc/
# /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. Quest Authentication Services periodically changes the machine password, and Samba requires knowledge of this to perform NTLM authentication. A small script provides this function.

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

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

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.

password server = *

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. It should be set to the hostname of a nearby domain controller.

Finally, get a shell on your machine as a normal user (make sure you have a Kerberos ticket, run vastool kinit if not) 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 3 (initially) or 5 (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 log levels above 10 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 Quest Authentication Services, 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 desynchronization is that copies of the host's secret key are kept in Quest Authentication Services's /etc/opt/quest/vas/host.keytab and Samba's secrets.tdb. And only one of them was updated.

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

# /opt/quest/bin/vastool -q -u host/ passwd -r -o |
# 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. Ensure that /etc/krb5.conf provides options suitable for finding the correct domain & servers. The easiest way to do this is to create a symlink from /etc/krb5.conf to /etc/opt/quest/vas/vas.conf. That way, all applications that are Kerberos-aware will take advantage of the Quest Authentication Services domain settings. Ensure /etc/krb5.conf does not contain the line srv_lookup = false. Alternatively, try running /opt/quest/sbin/vas-krb5-config to automatically ensure that /etc/krb5.conf is correctly configured.
Access is denied for some unix users when smb.conf contains a username map:
The primary group of a Unix-enabled 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 Unix-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-Unix-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. Unix-enable those accounts.
smbd won't start: 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 Quest Authentication Services. Upgrade to Quest Authentication Services 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.
winbind-idmap logging shows fetch_ldap_pw: neither ldap secret retrieved!; Failed to issue the StartTLS instruction: Insufficient access
On samba 3.3 and newer, the default setting for ldap ssl was changed from off to starttls. changing ldap ssl back to the pre-Samba 3.3 default of off, will resolve this issue. For more information see the smb.conf man page.
See: Quest Solution 77310
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.

smb complains: posix_fcntl_getlock: WARNING: lock request at offset 0, length 2 returned an Invalid argument error. This can happen when using 64 bit lock offsets on 32 bit NFS mounted file systems.
This happens when you are sharing an NFS mount and the operating system's API don't allow sign-extended conversion of '-1' between 32 and 64-bit lock addresses. Remedies include:
  • Adding strict locking = no to smb.conf
  • Adding llock to your NFS mount options
  • Running the 32-bit build of Samba (if available) on your 64-bit machine.

Troubleshooting steps

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

Advanced troubleshooting steps

Enable Vasidmapd Logging

Running the vasidmapd daemon by hand with the -d <level> flag, will output log messages, based on the level provided, to stderr and only to stderr. Omitting the -d flag will output log messages to the system logger based on configured syslog settings. (The default behavior logs to the system logging daemon facility)

Valid debug levels are 0 - 7
0: EMERG   system is unusable
1: ALERT   action must be taken immediately
2: CRIT    critical conditions
3: ERR     error conditions
4: WARNING warning conditions
5: NOTICE  normal but significant condition
6: INFO    informational
7: DEBUG   debug-level messages

To disable logging set the log level to -1.

Example setup for syslog: /var/log/daemon-info.log

Vasidmapd would log all info log level and higher the daemon-info.log. For more information see the man page for your operating systems syslog.

On systems that use rsyslog the following can be used to write out all vasidmapd messages to its own custom log file. Doing this can reduce the clutter in the default daemon log.

if $programname == 'vasidmapd' and $syslogseverity <= '7' then /var/log/vasidmapd
if $programname == 'vasidmapd' then ~
To increase verbosity set syslogseverity in the range of 0 to 7.



  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 Unix-enabled.