Linux in a Windows World/Centralized Authentication Tools/Using NT Domains for Linux Authentication

From WikiContent

Jump to: navigation, search
(Initial conversion from Docbook)
Current revision (23:06, 11 March 2008) (edit) (undo)
(Initial conversion from Docbook)

Current revision

Linux in a Windows World

If your existing network uses an NT domain or an Active Directory domain, you may want to tap into your existing domain controller for Linux authentication. For instance, you might want a Linux POP server to use your existing Windows domain accounts. Doing so presents certain challenges, though; the Windows and Linux authentication systems require different types of information, so some information Linux needs isn't available from the domain controller. Fortunately, Samba's Winbind software helps bridge this gap. Winbind links together the domain controller's database and Linux's native authentication system, the Pluggable Authentication Modules (PAM). Using Winbind requires configuring Samba options for Winbind, as well as for PAM and another helper tool, the Name Service Switch (NSS).


Active Directory, introduced with Windows 2000, is the successor to NT domains. AD domain controllers support the older NT domain controller protocols for the sake of backward compatibility, so you can authenticate Linux systems against an AD controller using the methods described in this chapter. You can also authenticate Linux systems against an NT domain controller that runs Samba.

Because Winbind is part of Samba, you should understand the basics of Samba configuration before proceeding, even if you don't want to run the full Samba server suite on the system you're configuring. If you're not already familiar with the basics of Samba, you should read Chapter 3. If you want to have Linux fill the role of the NT domain controller, you should read Chapter 5.


The Principles Behind Winbind

When configuring a Linux system to authenticate users against an NT domain controller, you should understand the basic principles behind this operation—that is, how Linux can work with an account database that wasn't designed with Linux or other Unix-like OSs in mind. Essentially, the problem is one of integrating two dissimilar systems—the NT domain system and Linux's PAM. Winbind is a tool that performs most of this integration, although some details are left to other tools.

The Problem: Linux Users on an NT Domain

As a practical matter, the desirability of running Linux as an NT domain controller's client (that is, as a domain member server ) varies from one network to another. The most common use for this approach is limited to file shares on a Samba server, and that procedure is described in Chapter 3. This configuration, though, works only for Samba shares, not for other services the computer might offer, such as a POP server, an SSH login server, or console logins. If a computer should be used in any of these ways in addition to or instead of being used as a Samba server, you must normally maintain local Linux-only accounts. On a network that already uses NT domain authentication for Windows systems, this separation can be a serious problem. You need to recreate your NT domain accounts on your Samba server—a tedious undertaking for you and for your users, who will have to reenter their passwords. If you want to run multiple Linux server computers or add Linux desktop systems, you need to either maintain separate Linux account databases on each Linux system or use some other network authentication database. In other words, you'll be throwing away the benefits of the NT domain controller for the new Linux systems.

Using an NT domain controller can be a good way to minimize the account maintenance difficulties when you start adding Linux systems. Instead of using a Unix-centric centralized account system or using local Linux account databases, you can tap into the NT domain controller. Once you've done this, a Linux POP server, SSH server, or most other servers automatically accepts logins using the usernames and passwords supported by the NT domain controller. You can even use this method to enable console logins using the NT domain's accounts.


Typically, some accounts are still maintained locally. Most notably, you should leave the root account defined only in the local Linux account database. This practice enables you to log in even if network problems exist. It also enables you to set different root passwords for each Linux system, which can help improve your overall network security; a breach of one system won't necessarily translate into a breach of all your systems.

NT domain authentication was designed with the needs of Windows computers in mind. These authentication tools provide some information that Linux requires, such as a username and password. This information isn't always available in a form the Linux system will find immediately useful, though; for instance, the password is encrypted using a method that's foreign to Linux. Worse, NT domain accounts lack some information that's critical to Linux, such as the Linux account's home directory and default shell. Thus, Winbind must make up some of this information using values set in Samba's smb.conf file. Other differences, such as NT domain password encryption, are handled by Winbind's PAM integration modules.

Linux's PAM and NSS Systems

Linux relies on two systems to help manage accounts: PAM and NSS. PAM is described in detail in Appendix A. In brief, PAM tells login services whether a user may log in or not, helps programs change passwords, and handles a few related tasks. PAM is a modular system, so you can reconfigure PAM to use authentication modules based on authentication tools other than the common /etc/passwd and /etc/shadow files. In particular, this chapter describes how to configure PAM modules that link to an NT domain controller with the Winbind tool.

In addition to PAM, Linux relies on another software component, NSS, for account information. Rather than authentication information, though, NSS provides more mundane information, such as a mapping of UIDs to usernames and the account's default shell. Like PAM, NSS is designed in a modular way and sits between applications that ask for this information and the actual account databases. Although you may think in terms of domain authentication, which is what PAM provides, this ancillary information is just as important, so you must configure NSS to query Winbind. Most of the information NSS delivers is made up rather than pulled out of the NT domain controller, though, because this is the information the domain controller doesn't support.

Winbind: Linking PAM and NSS to an NT Domain

Winbind is implemented as a daemon, winbindd . This daemon ships with the official Samba source code tarball, although some Linux distributions split it off into its own package, such as winbind. As described in the later Section 7.2.2, this daemon runs at all times on any server that authenticates users against a domain controller. Although winbindd is a daemon, it's not an externally accessible server; it doesn't bind to a port and listen for external connections. It does, though, use Unix domain sockets to communicate with local processes—namely, the PAM and NSS libraries that are also part of the Winbind package.

Winbind connects to the domain controller to authenticate users and thus functions as a domain member server to a domain controller. Winbind works in this way only when the computer on which it's running is fully joined to a domain using the Samba net command, which is described in Section 7.2.1.

Samba Winbind Configuration

Much of the configuration of Winbind is done using Samba. The main Winbind options appear in smb.conf (although, as described earlier, some options are set in the PAM and NSS configuration files, as well). Thus, you must know how to set these Samba options. Running the Winbind daemon is also critically important to getting the system running.


This configuration occurs on the domain member server—the Linux system you want to configure to use a domain controller's account database. If you use a Samba server as the domain controller, it requires its own configuration, which need not include most of the options described here.

Winbind Options in smb.conf

You should configure the smb.conf file on the domain member server much as you would for any Samba server on a domain, as described in Chapter 3. Most notably, you should set the workgroup, security, encrypt passwords, and password server global options:

workgroup = GREENHOUSE
security = Domain
encrypt passwords = Yes
password server =

You should adjust the values of the workgroup and password server parameters for your network, of course. The security parameter must be set to Domain, and encrypt passwords must be set to Yes.


If your domain controller supports AD, you can set security = ADS instead of security = Domain, but this configuration requires setting additional options and can be finicky. It provides somewhat better security on your LAN because it uses the extremely robust Kerberos authentication system.

In addition to these options, which are the same as those you must set for any Samba domain member server, you may want to set several other global parameters. These parameters set values for information required by Linux accounts but not provided by the domain controller:

winbind use default domain
Ordinarily, Winbind returns Linux usernames that are based on a combination of the NT domain name and the NT username. This feature enables you to maintain multiple domains and support users with duplicate usernames in these domains without causing conflicts. If you set this Boolean parameter's value to Yes, though, Winbind omits the domain name from usernames, which results in shorter and more sensible usernames. Doing this is safest when you have just one domain or when you're sure that no usernames are duplicated on multiple domains. This parameter's default value is No.
winbind separator
This parameter specifies a character that separates domain names from usernames when winbind use default domain = No. The default character is a backslash (\).
winbind enum users
Linux provides certain system calls that enable programs to enumerate users on a system. Winbind supports these features if this parameter is set to Yes (the default), but this support can be slow. Thus, if the programs you run on a system don't require this support, setting this parameter to No can improve performance.
winbind enum groups
This parameter works much like winbind enum users, but it affects system calls for enumerating groups rather than users.
idmap uid
Linux uses UIDs internally for tracking users. NT domains use a number called a Security Identifier (SID) for a similar purpose; however, the two numbers aren't identical. Thus, you can give Winbind a range of local UID numbers to use for the accounts it handles. This range is given as two numbers separated by a dash, as in 2000-5000. You should never create local Linux accounts in the range you reserve for Winbind in this way. This parameter's default range is undefined. Prior to Samba 3.0.6, this value had to be set, but in Samba 3.0.6 and later, an undefined idmap uid causes Winbind to try to map NT domain usernames to locally defined accounts, which can be useful if you have existing Linux accounts but want to rely on a domain controller for password authentication. A synonym for this parameter is winbind uid.
idmap gid
This parameter works much like idmap uid, but it reserves a range of GID numbers rather than UID numbers. This parameter's default value is undefined. A synonym for this parameter is winbind gid.

Winbind makes no guarantees about the UIDs and GIDs assigned to particular users and groups. In particular, two Linux systems might assign completely different UIDs and GIDs to a user, even if you specify the same range of UIDs with idmap uid. This can complicate certain Linux-to-Linux protocols, such as NFS, which identifies accounts by UID rather than username. You can overcome this problem using the idmap backend parameter to point to an LDAP directory that holds the UID mapping information.


Samba maintains information about UID and GID mapping in Trivial Database (TDB) files, typically in /var/cache/samba or a similar location. If these files are damaged or deleted, Winbind has to rebuild these mappings, and they may not match the originals. If this happens, you have to reassign ownership of all your users' files and home directories.

template shell
An /etc/passwd file normally specifies a default shell for a user; this program is run when a user logs in at a text-mode console, via SSH, and so on. NT domain controllers don't maintain this information, though, so you must tell Winbind what value to provide. The default is /bin/false, which is a conservative choice from a security point of view and may be good for some functions. However, for systems that should support shell access, another value, such as /bin/bash, will function better. You can't customize this value on a per-user basis; all accounts mediated by Winbind must use the same shell.
template homedir
Just as with the default shell, NT domain controllers don't maintain information on the users' home directories. You specify this information with this parameter, which defaults to /home/%D/%U. Because %D is a Samba variable for the domain name and %U stands for the username, this value sets a unique home directory for each user. As of Samba 3.0.6, only the %D, %N, %U, and %u variables are supported in this option.
winbind cache time
This parameter sets the amount of time, in seconds, that Winbind will cache authentication information before querying the server again, should a new authentication request occur. The default value is 300 (five minutes). You may want to reduce this value during testing.

The most important of these parameters to set or change are usually idmap uid, idmap gid, and template shell. Setting other parameters can sometimes be desirable, though. For instance, you might use parameters like these for testing in a one-domain configuration:

winbind use default domain = Yes
idmap uid = 2000-5000
idmap gid = 2000-5000
template shell = /bin/bash
template homedir = /home/%U
winbind cache time = 5

Once you're convinced everything is working, you should increase the cache time so as to reduce the number of queries the system makes of the domain controller. Changes to some other parameters might require additional system changes; for instance, if you alter template homedir, you have to move users' home directories yourself.

Before proceeding, remember to add a machine trust account to the domain controller for the Linux computer. This can be done from the Linux system using the net utility. For instance, to join a computer to the domain specified by the workgroup parameter in smb.conf, type this command:

# net join member -U 

This command needs to be run just once. In this example, adminuser is the username of an account on the domain controller that may add machine trust accounts. (This topic is covered in more detail in Chapter 3.) If the domain controller is a Samba server, consult Chapter 5 for information on configuring the necessary machine trust accounts.

Running the Winbind Daemon

Because Winbind relies on a running daemon, you must configure it to run at all times. For testing purposes, though, you may want to run it manually:

# /usr/sbin/winbindd -i


The winbindd program file may be in another directory on your system. /usr/local/samba/sbin is common if you compiled Samba from source code yourself. If you can't find the binary on your system, check your distribution's Samba packages; you might not have installed the package in which the daemon ships.

To run the daemon permanently, you should do one of two things:

  • Add a line to launch the program to a local startup script, such as the /etc/rc.d/rc.local script in Fedora Core, Mandrake, or Red Hat; /etc/init.d/boot.local in SuSE; or /etc/conf.d/local.start in Gentoo.
  • Configure a SysV startup script to launch the daemon. Many distributions' Samba packages include such scripts, usually called winbind or something similar. Create appropriate symbolic links or use whatever SysV startup script management tools your distribution provides to do the job.

In either case, you should remove the -i option from the line that launches winbindd. This option causes the daemon to log information on its operation to standard output and to not detach from the current terminal, which is handy when testing the daemon but not when using it in normal operation.

Once Winbind is running, you can test its basic operation using the wbinfo command. This command supports numerous options that return information on accounts maintained by the domain controller. Some options enable you to modify those accounts, as well. To test the most basic operation, use the -t option to test the trust account you've created and the basic Winbind functionality:

$ wbinfo -t
checking the trust secret via RPC calls succeeded

If this call returns an error message, review your smb.conf options and check the logs on the Linux system and the domain controller for clues to the cause. A subsequent testing step involves -u; this option returns a list of accounts maintained by the domain controller:

$ wbinfo -u


This example shows output consistent with a setting of winbind use default domain = Yes. If this option is set to No, the usernames include domain names, as in GREENHOUSE\linnaeus rather than linnaeus.

If wbinfo -u returns a list of users, you can be confident that Winbind is operating, at least minimally. If you receive an error message, though, you should look into the matter. Review your smb.conf entries, and check the logs on both the Linux system and the domain controller for clues.

PAM and NSS Winbind Options

Getting the Winbind daemon up and running is only part of the configuration required on the domain member server. Once Winbind is functioning, you must configure PAM and NSS to use Winbind to authenticate users and return additional account information to programs that need it. These tasks are handled by special modules and configuration of these two subsystems. You may also want to configure Linux to create home directories automatically when they don't exist.

NSS and PAM Winbind Modules

PAM and NSS both rely on modules to interface with Winbind. These module files, and , are usually installed as part of a Samba package, such as samba-common. The file usually appears in /lib/security or /usr/lib/security. The file usually resides in /lib and is linked to another file, (either file may be a symbolic link to the other).

If you've installed Samba from source code, you may need to install these libraries independently. The source code appears in the source/nsswitch subdirectory of the Samba source code package, and the compiled libraries should appear there after you build the main Samba package. (These files appear only if you select the --with-pam configure option.) Copy the files to appropriate directories, and create an appropriate link for the file. You can then type ldconfig to force Linux to reexamine the library directories and register the new libraries.

Configuring NSS

NSS provides nonauthentication information on accounts to tools that require it. Before PAM allows you to log in using Winbind, you must configure NSS to use Winbind. This can be done by editing the /etc/nsswitch.conf file. Locate the passwd and group lines in this file. (The shadow line usually separates them, but you won't edit this line.) Add winbind to the passwd and group lines:

passwd:  files winbind
shadow:  files
group:   files winbind


Some distributions place other options on these lines in addition to files. Some use compat instead of files. If yours is so configured, simply add winbind to the end of the list, or to an earlier position if you prefer. (NSS consults each source in turn for account information.)

Configuring PAM

PAM enables you to customize authentication options on a service-by-service basis. For instance, you can tell Linux to use only the local account database for console logins, to use only the NT domain controller for FTP logins, and to use either method for remote SSH logins. PAM accomplishes this goal by using one or more configuration files: either a file called /etc/pam.conf or files in the /etc/pam.d directory named after the particular systems they control. Modifying these files to use additional PAM modules, such as those that support NT domain authentication, is described in Appendix A.


When reconfiguring PAM, you can easily render your system unable to support logins. Thus, I recommend experimenting with one login server at a time, leaving yourself some way to log in should you create an inoperable system. For instance, experiment with the login service and leave the gdm or xdm service alone.

As an example of adding NT domain authentication, consider Example 7-1. This listing shows the contents of the /etc/pam.d/login file on a Debian system, which defines how PAM handles authentication for text-mode console logins and logins via such servers as Telnet.

Example 7-1. Sample PAM configuration file

auth       requisite
auth       requisite
auth       required
auth       required nullok

account    requisite
account    required

session    required
session    optional
session    optional
session    optional standard noenv

password   required nullok min=6 max=255 md5


PAM configurations vary both from one service to another and from one distribution to another. If your PAM configuration file doesn't look exactly like Example 7-1, don't panic. The most important part of PAM Winbind configuration is adding lines, as described shortly.

To add NT domain authentication to this system, you should add a couple of lines to this file. These lines tell PAM to use the library for authentication and account validity checks. The result of adding these lines appears in Example 7-2, with the added or changed material shown in bold.

Example 7-2. Sample PAM configuration file with Winbind support

auth       requisite
auth       requisite
auth       required
auth       sufficient
auth       required nullok try_first_pass

account    requisite
account    sufficient
account    required

session    required
session    optional
session    optional
session    optional standard noenv
session    required skel=/etc/skel umask=0027

password   required nullok min=6 max=255 md5

This configuration adds an auth line just before the existing auth line that references and adds the try_first_pass parameter to that existing line. These changes add Winbind to the authentication system and cause to use the password entered for Winbind if Winbind authentication fails. A second set of changes is in the account stack, which adds a Winbind call to it. Finally, this configuration adds a call to, which creates a new home directory for the user if one doesn't already exist. You need to make these changes for every service that should use the NT domain controller.


Some distributions, including Red Hat, Fedora, and Gentoo, now use the module rather than or If you see calls to this module, you can either add your calls to to the file as described here or modify the /etc/pam/system-auth file instead of the file for the individual servers. The module pushes part of the PAM configuration into the system-auth file, as described in Appendix A.

You should also change the /etc/pam.d/passwd file, which controls the passwd command's actions. As described in Appendix A, this change requires adding references to to the auth, account, and password stacks.


You normally don't need to change the /etc/pam.d/samba configuration. The Samba server provides its own tools for authenticating against the domain controller, and in fact, if you configure Winbind properly, Samba is automatically configured to use the domain controller directly. Thus, although it has one, there's no need to edit Samba's PAM configuration file.

Winbind in Action

In theory, Winbind should now be working. In practice, though, various problems can occur. You can perform tests to check on Winbind's operation that will point you to likely solutions for any problems that might exist. Once the system is up and running, you can begin using it, but you should understand its capabilities and limitations in day-to-day operation.

Testing Winbind Operation

We looked at the wbinfo tool that tests Winbind operation in Section 7.2.2. This tool queries the domain controller via Winbind without using the NSS or PAM libraries, and as such, it's a good test of "pure" Winbind operation. It provides several options you can use to test basic Winbind operations:

-a username%password
This option performs a test authentication using the provided username and password. If it succeeds, Winbind can authenticate users. This option only works when run as root.
This option displays all groups available on the current domain.
-n name
Winbind returns the SID of the specified name, which is normally a username but could be a group name.
This option checks for the presence of Winbind; if it's running and working at least minimally, the program responds Ping to winbindd succeeded.
Use this option to check the validity of your domain trust account. If it's valid, wbinfo responds:
checking the trust secret via RPC calls succeeded
As described earlier, this option displays a list of usernames managed by Winbind.

Some additional options provide more features for converting between SIDs, Unix usernames, and Unix UIDs. Still more options can be used for account management. Consult the wbinfo manpage for more information.

When debugging problems, I recommend using the -p, -t, -u, and -g options to check for basic functionality. (The last of these may return an empty list under some circumstances, though.) Using options that work on specific accounts or groups, such as -a and -n, can help you verify that more advanced features are working. If any tests fail, the pattern of failures can be informative. For instance, if -t fails, but -p works, you should check your machine trust account, and if necessary recreate it.

A second layer of tests uses the getent command. This tool returns the contents of administrative databases, such as /etc/passwd or /etc/group. The tool works through NSS, though, so when you configure NSS to use a domain controller, getent should return information from the local /etc/passwd or /etc/group files, followed by constructed entries for the NT domain accounts and groups. You obtain these lists by typing the command followed by the database—that is, getent passwd or getent group. Check the outputs of these commands for the accounts and groups that are defined on your domain controller. If either output lacks entries that should be present, you might have mistyped an entry in /etc/nsswitch.conf, or your system might be missing the appropriate library. Remember to type ldconfig after adding libraries.

You should also check the output of getent for appropriate UID and GID numbers. The NT domain accounts and groups should use numbers specified in the idmap uid and idmap gid parameters, respectively, in smb.conf. If these numbers overlap those of locally defined accounts, reconfigure smb.conf so they don't overlap.


Sorting the getent output by UID can sometimes be helpful. Typing getent passwd | sort -t: -k3 -n will do this.

Winbind Logins

Once you've performed these tests, you can try logging in using Winbind. Doing so may require you to restart the login process you're using, though. If you can't seem to log in, try terminating the server you're using and restarting it. (The local login process, which handles text-mode logins, normally starts anew whenever you log out. The same is true of processes run from a super server.)

If all goes well, you should be able to log into your system using the NT domain controller just as you would using the local login database; you should see absolutely no difference. To be sure you're using the NT domain controller, use an account that exists on the domain controller but not in the Linux system's local account database.


Some PAM configuration errors enable you to log into an account with no password or with an incorrect password, so be sure to test not only your ability to log in, but Linux's response to incorrect passwords.

If you set winbind use default domain = No, you'll have to provide the domain name as part of each username, as in GREENHOUSE\linnaeus rather than linnaeus. This can be awkward, so you should set this parameter to Yes, if possible.

If your server should support multiple login services, such as text-mode console, GDM, and FTP accesses, be sure to test all of them. Of course, you'll also have to adjust each service's /etc/pam.d file.


Some servers require unusual configurations, either in their PAM configuration files or in their own configuration files. For instance, OpenSSH requires you to set UsePrivilegeSeparation no in its /etc/ssh/sshd_config file. Some servers also provide optional PAM support, which must be enabled either in a configuration file or when building the server. If you find that most servers work with NT domain authentication but some don't, try a web search on Winbind or PAM and the server name for clues about any server-specific quirks.

If your domain controller is a Samba server, you might find that your NT domain accounts don't belong to an explicitly defined group. The usual symptom is a GID number rather than a group name in ls listings:

$ ls -l
total 0
-rw-r--r--  1 linnaeus 2009 0 May 23 15:55 myfile.txt

Note the GID number (2009) in this output where a group name normally appears. This problem is a result of the fact that Samba doesn't automatically map its local Linux groups to NT domain groups. You may be able to safely ignore this problem, but if groups are important to you, you can overcome it using the net utility to set up a mapping of Linux to NT domain groups. First, create NT groups using the GROUP ADD subcommand:

$ net GROUP ADD 

Now, set up a mapping of existing Linux groups to the NT domain groups:

$ net GROUPMAP ADD ntgroup=
                  Botanists unixgroup=botany

Of course, the Linux group must exist before you type this command; if it doesn't, you should create it first, using groupadd or some other tool. You may be asked for a password after typing these commands. You may also need to add the -U adminuser option to perform this action as the specified administrative user. If you want to configure multiple groups, you must set up each individually. In any event, after performing these steps, group mapping should operate in a fairly straightforward way.

Another approach to the problem of missing group mappings is to use NIS, LDAP, or some other tool to share group information between the Samba server and the Winbind client. This approach requires either setting winbind trusted domains only = Yes or not setting the idmap gid parameter. In either case, the Winbind client then uses the GID information distributed via the alternative protocol, such as NIS or LDAP.

In normal operation, Winbind attempts to authenticate users against the NT domain controller. This attempt can fail, though. This can happen because of a failure of the domain controller, network problems, or local configuration problems or because the account doesn't exist on the domain controller. In such situations, if you've configured Winbind as described in this chapter, Linux falls back on its local account database. You may want to keep this database populated with a few critical accounts—most importantly, the root account, so that you can perform system maintenance even if the domain authentication system fails. However, if you maintain redundant accounts (for instance, if linnaeus is defined both locally and on the domain controller), which account is used depends on the order of entries in the PAM configuration file and the /etc/nsswitch.conf file. As a general rule, defining an account in both ways is likely to lead to confusion, so this practice should be avoided.


Many Windows networks use NT domain controllers or AD domain controllers to provide authentication services to Windows systems. You can tap into this existing resource to provide automatic account creation and password authentication on a Linux system—even one that doesn't function as a Samba server. To do this, you must adjust some smb.conf entries, run the Winbind daemon, and configure the PAM and NSS systems to use Winbind for account authentication and information queries. Once this system is configured and running, users shouldn't be able to tell that Winbind is in use; everything should work just as it does with a local account database.

Personal tools