1 <chapter id="domain-member">
9 <title>Domain Membership</title>
12 Domain Membership is a subject of vital concern, Samba must be able to participate
13 as a member server in a Microsoft Domain security context, and Samba must be capable of
14 providing Domain machine member trust accounts, otherwise it would not be capable of offering
15 a viable option for many users.
19 This chapter covers background information pertaining to domain membership, Samba
20 configuration for it, and MS Windows client procedures for joining a domain. Why is
21 this necessary? Because both are areas in which there exists within the current MS
22 Windows networking world and particularly in the Unix/Linux networking and administration
23 world, a considerable level of mis-information, incorrect understanding, and a lack of
24 knowledge. Hopefully this chapter will fill the voids.
28 <title>Features and Benefits</title>
31 MS Windows workstations and servers that want to participate in domain security need to
32 be made Domain members. Participating in Domain security is often called
33 <emphasis>Single Sign On</emphasis> or SSO for short. This chapter describes the process
34 that must be followed to make a workstation (or another server - be it an MS Windows NT4 / 200x
35 server) or a Samba server a member of an MS Windows Domain security context.
39 Samba-3 can join an MS Windows NT4 style domain as a native member server, an MS Windows
40 Active Directory Domain as a native member server, or a Samba Domain Control network.
44 Domain membership has many advantages:
49 MS Windows workstation users get the benefit of SSO
53 Domain user access rights and file ownership / access controls can be set from
54 the single Domain SAM (Security Accounts Management) database (works with Domain member
55 servers as well as with MS Windows workstations that are domain members)
59 Only MS Windows NT4 / 200x / XP Professional workstations that are Domain members
60 can use network logon facilities
64 Domain Member workstations can be better controlled through the use of Policy files
65 (NTConfig.POL) and Desktop Profiles.
69 Through the use of logon scripts users can be given transparent access to network
70 applications that run off application servers
74 Network administrators gain better application and user access management abilities
75 because there is no need to maintain user accounts on any network client or server,
76 other than the central Domain database (either NT4/Samba SAM style Domain, NT4 Domain
77 that is back ended with an LDAP directory, or via an Active Directory infrastructure)
84 <title>MS Windows Workstation/Server Machine Trust Accounts</title>
87 A machine trust account is an account that is used to authenticate a client machine
88 (rather than a user) to the Domain Controller server. In Windows terminology,
89 this is known as a "Computer Account."
93 The password of a machine trust account acts as the shared secret for
94 secure communication with the Domain Controller. This is a security
95 feature to prevent an unauthorized machine with the same NetBIOS name
96 from joining the domain and gaining access to domain user/group
97 accounts. Windows NT, 200x, XP Professional clients use machine trust
98 accounts, but Windows 9x / Me / XP Home clients do not. Hence, a
99 Windows 9x / Me / XP Home client is never a true member of a domain
100 because it does not possess a machine trust account, and thus has no
101 shared secret with the domain controller.
105 A Windows NT4 PDC stores each machine trust account in the Windows Registry.
106 The introduction of MS Windows 2000 saw the introduction of Active Directory,
107 the new repository for machine trust accounts.
111 A Samba PDC, however, stores each machine trust account in two parts,
116 A Domain Security Account (stored in the <emphasis>passdb backend</emphasis>
117 that has been configured in the &smb.conf; file. The precise nature of the
118 account information that is stored depends on the type of backend database
119 that has been chosen.
123 The older format of this data is the <filename>smbpasswd</filename> database
124 which contains the unix login ID, the Unix user identifier (UID), and the
125 LanMan and NT encrypted passwords. There is also some other information in
126 this file that we do not need to concern ourselves with here.
130 The two newer database types are called <emphasis>ldapsam, tdbsam</emphasis>.
131 Both store considerably more data than the older <filename>smbpasswd</filename>
132 file did. The extra information enables new user account controls to be used.
136 A corresponding Unix account, typically stored in <filename>/etc/passwd</filename>.
137 Work is in progress to allow a simplified mode of operation that does not require
138 Unix user accounts, but this may not be a feature of the early releases of Samba-3.
144 There are three ways to create machine trust accounts:
149 Manual creation from the Unix/Linux command line. Here, both the Samba and corresponding
150 Unix account are created by hand.
154 Using the MS Windows NT4 Server Manager (either from an NT4 Domain member server, or using
155 the Nexus toolkit available from the Microsoft web site. This tool can be run from any
156 MS Windows machine so long as the user is logged on as the administrator account.
160 "On-the-fly" creation. The Samba machine trust account is automatically created by
161 Samba at the time the client is joined to the domain. (For security, this is the
162 recommended method.) The corresponding Unix account may be created automatically or manually.
167 <title>Manual Creation of Machine Trust Accounts</title>
170 The first step in manually creating a machine trust account is to manually create the
171 corresponding Unix account in <filename>/etc/passwd</filename>. This can be done using
172 <command>vipw</command> or other 'add user' command that is normally used to create new
173 Unix accounts. The following is an example for a Linux based Samba server:
177 <prompt>root# </prompt><command>/usr/sbin/useradd -g 100 -d /dev/null -c <replaceable>"machine nickname"</replaceable> -s /bin/false <replaceable>machine_name</replaceable>$ </command>
181 <prompt>root# </prompt><command>passwd -l <replaceable>machine_name</replaceable>$</command>
185 On *BSD systems, this can be done using the 'chpass' utility:
189 <prompt>root# </prompt><command>chpass -a "<replaceable>machine_name</replaceable>$:*:101:100::0:0:Workstation <replaceable>machine_name</replaceable>:/dev/null:/sbin/nologin"</command>
193 The <filename>/etc/passwd</filename> entry will list the machine name
194 with a "$" appended, won't have a password, will have a null shell and no
195 home directory. For example a machine named 'doppy' would have an
196 <filename>/etc/passwd</filename> entry like this:
200 doppy$:x:505:501:<replaceable>machine_nickname</replaceable>:/dev/null:/bin/false
204 Above, <replaceable>machine_nickname</replaceable> can be any
205 descriptive name for the client, i.e., BasementComputer.
206 <replaceable>machine_name</replaceable> absolutely must be the NetBIOS
207 name of the client to be joined to the domain. The "$" must be
208 appended to the NetBIOS name of the client or Samba will not recognize
209 this as a machine trust account.
213 Now that the corresponding Unix account has been created, the next step is to create
214 the Samba account for the client containing the well-known initial
215 machine trust account password. This can be done using the <ulink
216 url="smbpasswd.8.html"><command>smbpasswd(8)</command></ulink> command
222 <prompt>root# </prompt><userinput>smbpasswd -a -m <replaceable>machine_name</replaceable></userinput>
227 where <replaceable>machine_name</replaceable> is the machine's NetBIOS
228 name. The RID of the new machine account is generated from the UID of
229 the corresponding Unix account.
233 <title>Join the client to the domain immediately</title>
236 Manually creating a machine trust account using this method is the
237 equivalent of creating a machine trust account on a Windows NT PDC using
238 the "Server Manager". From the time at which the account is created
239 to the time which the client joins the domain and changes the password,
240 your domain is vulnerable to an intruder joining your domain using
241 a machine with the same NetBIOS name. A PDC inherently trusts
242 members of the domain and will serve out a large degree of user
243 information to such clients. You have been warned!
249 <title>Using NT4 Server Manager to Add Machine Accounts to the Domain</title>
252 If the machine from which you are trying to manage the domain is an MS Windows NT4 workstation
253 then the tool of choice is the package called SRVTOOLS.EXE. When executed in the target directory
254 this will unpack SrvMge.exe and UsrMgr.exe (both are Domain Management tools for MS Windows NT4
259 If your workstation is any other MS Windows product you should download the Nexus.exe package
260 from the Microsoft web site. When executed from the target directory this will unpack the same
261 tools but for use on MS Windows 9x/Me/200x/XP.
265 Launch the <command>srvmgr.exe</command> (Server Manager for Domains) and follow these steps:
269 <title>Server Manager Account Machine Account Management</title>
271 From the menu select Computer
275 Click on "Select Domain"
279 Click on the name of the domain you wish to administer in the "Select Domain" panel
284 Again from the menu select Computer
288 Select "Add to Domain"
292 In the dialog box, click on the radio button to "Add NT Workstation of Server", then
293 enter the machine name in the field provided, then Click the "Add" button.
300 <title>"On-the-Fly" Creation of Machine Trust Accounts</title>
303 The second (and recommended) way of creating machine trust accounts is
304 simply to allow the Samba server to create them as needed when the client
305 is joined to the domain.
308 <para>Since each Samba machine trust account requires a corresponding Unix account, a method
309 for automatically creating the Unix account is usually supplied; this requires configuration of the
310 <ulink url="smb.conf.5.html#ADDMACHINESCRIPT">add machine script</ulink> option in
311 <filename>smb.conf</filename>. This method is not required, however; corresponding Unix
312 accounts may also be created manually.
317 Below is an example for a RedHat Linux system.
320 <para><programlisting>
322 # <...remainder of parameters...>
323 add machine script = /usr/sbin/useradd -d /dev/null -g 100 -s /bin/false -M %u
324 </programlisting></para>
330 <sect2><title>Making an MS Windows Workstation or Server a Domain Member</title>
333 The procedure for making an MS Windows workstation of server a member of the domain varies
334 with the version of Windows:
338 <listitem><para><emphasis>Windows 200x XP Professional</emphasis></para>
341 When the user elects to make the client a domain member, Windows 200x prompts for
342 an account and password that has privileges to create machine accounts in the domain.
343 A Samba administrative account (i.e., a Samba account that has root privileges on the
344 Samba server) must be entered here; the operation will fail if an ordinary user
349 Note: For security reasons the password for this administrative account should be set
350 to a password that is other than that used for the root user in the
351 <filename>/etc/passwd</filename>.
355 The name of the account that is used to create domain member machine accounts can be
356 anything the network administrator may choose. If it is other than <command>root</command>
357 then this is easily mapped to root using the file pointed to be the &smb.conf; parameter
358 <emphasis>username map =</emphasis> <command>/etc/samba/smbusers</command>.
362 The session key of the Samba administrative account acts as an
363 encryption key for setting the password of the machine trust
364 account. The machine trust account will be created on-the-fly, or
365 updated if it already exists.
368 <listitem><para><emphasis>Windows NT4</emphasis></para>
371 If the machine trust account was created manually, on the
372 Identification Changes menu enter the domain name, but do not
373 check the box "Create a Computer Account in the Domain." In this case,
374 the existing machine trust account is used to join the machine to
379 If the machine trust account is to be created
380 on-the-fly, on the Identification Changes menu enter the domain
381 name, and check the box "Create a Computer Account in the Domain." In
382 this case, joining the domain proceeds as above for Windows 2000
383 (i.e., you must supply a Samba administrative account when
387 <listitem><para><emphasis>Samba</emphasis></para>
388 <para>Joining a samba client to a domain is documented in
389 the <link linkend="domain-member">Domain Member</link> chapter.
397 <title>Domain Member Server</title>
400 This mode of server operation involves the samba machine being made a member
401 of a domain security context. This means by definition that all user authentication
402 will be done from a centrally defined authentication regime. The authentication
403 regime may come from an NT3/4 style (old domain technology) server, or it may be
404 provided from an Active Directory server (ADS) running on MS Windows 2000 or later.
409 Of course it should be clear that the authentication back end itself could be from any
410 distributed directory architecture server that is supported by Samba. This can be
411 LDAP (from OpenLDAP), or Sun's iPlanet, of NetWare Directory Server, etc.
416 Please refer to the section on Howto configure Samba as a Primary Domain Controller
417 and for more information regarding how to create a domain machine account for a
418 domain member server as well as for information regarding how to enable the samba
419 domain member machine to join the domain and to be fully trusted by it.
423 <title>Joining an NT4 type Domain with Samba-3</title>
426 <emphasis>Assumptions:</emphasis>
429 Win2K/NT domain name: DOM
430 Domain's PDC NetBIOS name: DOMPDC
431 Domain's BDC NetBIOS names: DOMBDC1 and DOMBDC2
436 First, you must edit your &smb.conf; file to tell Samba it should
437 now use domain security.
441 Change (or add) your <ulink url="smb.conf.5.html#SECURITY">
442 <parameter>security =</parameter></ulink> line in the [global] section
443 of your &smb.conf; to read:
448 <command>security = domain</command>
453 Next change the <ulink url="smb.conf.5.html#WORKGROUP"><parameter>
454 workgroup =</parameter></ulink> line in the [global] section to read:
459 <command>workgroup = DOM</command>
464 as this is the name of the domain we are joining.
468 You must also have the parameter <ulink url="smb.conf.5.html#ENCRYPTPASSWORDS">
469 <parameter>encrypt passwords</parameter></ulink> set to <constant>yes
470 </constant> in order for your users to authenticate to the NT PDC.
474 Finally, add (or modify) a <ulink url="smb.conf.5.html#PASSWORDSERVER">
475 <parameter>password server =</parameter></ulink> line in the [global]
481 <command>password server = DOMPDC DOMBDC1 DOMBDC2</command>
486 These are the primary and backup domain controllers Samba
487 will attempt to contact in order to authenticate users. Samba will
488 try to contact each of these servers in order, so you may want to
489 rearrange this list in order to spread out the authentication load
490 among domain controllers.
494 Alternatively, if you want smbd to automatically determine
495 the list of Domain controllers to use for authentication, you may
501 <command>password server = *</command>
506 This method, allows Samba to use exactly the same mechanism that NT does. This
507 method either broadcasts or uses a WINS database in order to
508 find domain controllers to authenticate against.
512 In order to actually join the domain, you must run this command:
517 <prompt>root# </prompt><userinput>net join -S DOMPDC -U<replaceable>Administrator%password</replaceable></userinput>
522 If the <userinput>-S DOMPDC</userinput> argument is not given then
523 the domain name will be obtained from smb.conf.
527 As we are joining the domain DOM and the PDC for that domain
528 (the only machine that has write access to the domain SAM database)
529 is DOMPDC. The <replaceable>Administrator%password</replaceable> is
530 the login name and password for an account which has the necessary
531 privilege to add machines to the domain. If this is successful
532 you will see the message:
536 <computeroutput>Joined domain DOM.</computeroutput>
537 or <computeroutput>Joined 'SERV1' to realm 'MYREALM'</computeroutput>
541 in your terminal window. See the <ulink url="net.8.html">
542 net(8)</ulink> man page for more details.
546 This process joins the server to the domain without having to create the machine
547 trust account on the PDC beforehand.
551 This command goes through the machine account password
552 change protocol, then writes the new (random) machine account
553 password for this Samba server into a file in the same directory
554 in which an smbpasswd file would be stored - normally :
558 <filename>/usr/local/samba/private/secrets.tdb</filename>
562 This file is created and owned by root and is not
563 readable by any other user. It is the key to the domain-level
564 security for your system, and should be treated as carefully
565 as a shadow password file.
569 Finally, restart your Samba daemons and get ready for
570 clients to begin using domain security!
576 <title>Why is this better than security = server?</title>
579 Currently, domain security in Samba doesn't free you from
580 having to create local Unix users to represent the users attaching
581 to your server. This means that if domain user <constant>DOM\fred
582 </constant> attaches to your domain security Samba server, there needs
583 to be a local Unix user fred to represent that user in the Unix
584 filesystem. This is very similar to the older Samba security mode
585 <ulink url="smb.conf.5.html#SECURITYEQUALSSERVER">security = server</ulink>,
586 where Samba would pass through the authentication request to a Windows
587 NT server in the same way as a Windows 95 or Windows 98 server would.
591 Please refer to the <ulink url="winbind.html">Winbind
592 paper</ulink> for information on a system to automatically
593 assign UNIX uids and gids to Windows NT Domain users and groups.
597 The advantage to domain-level security is that the
598 authentication in domain-level security is passed down the authenticated
599 RPC channel in exactly the same way that an NT server would do it. This
600 means Samba servers now participate in domain trust relationships in
601 exactly the same way NT servers do (i.e., you can add Samba servers into
602 a resource domain and have the authentication passed on from a resource
603 domain PDC to an account domain PDC).
607 In addition, with <command>security = server</command> every Samba
608 daemon on a server has to keep a connection open to the
609 authenticating server for as long as that daemon lasts. This can drain
610 the connection resources on a Microsoft NT server and cause it to run
611 out of available connections. With <command>security = domain</command>,
612 however, the Samba daemons connect to the PDC/BDC only for as long
613 as is necessary to authenticate the user, and then drop the connection,
614 thus conserving PDC connection resources.
618 And finally, acting in the same manner as an NT server
619 authenticating to a PDC means that as part of the authentication
620 reply, the Samba server gets the user identification information such
621 as the user SID, the list of NT groups the user belongs to, etc.
626 Much of the text of this document
627 was first published in the Web magazine <ulink url="http://www.linuxworld.com">
628 LinuxWorld</ulink> as the article <ulink
629 url="http://www.linuxworld.com/linuxworld/lw-1998-10/lw-10-samba.html">Doing
630 the NIS/NT Samba</ulink>.
638 <title>Samba ADS Domain Membership</title>
641 This is a rough guide to setting up Samba 3.0 with kerberos authentication against a
646 <title>Setup your <filename>smb.conf</filename></title>
649 You must use at least the following 3 options in smb.conf:
652 <para><programlisting>
653 realm = your.kerberos.REALM
655 encrypt passwords = yes
656 </programlisting></para>
659 In case samba can't figure out your ads server using your realm name, use the
660 <command>ads server</command> option in <filename>smb.conf</filename>:
662 ads server = your.kerberos.server
667 You do *not* need a smbpasswd file, and older clients will be authenticated as if
668 <command>security = domain</command>, although it won't do any harm and allows you
669 to have local users not in the domain. I expect that the above required options will
670 change soon when we get better active directory integration.
676 <title>Setup your <filename>/etc/krb5.conf</filename></title>
679 Note: you will need the krb5 workstation, devel, and libs installed
683 The minimal configuration for <filename>krb5.conf</filename> is:
686 <para><programlisting>
688 YOUR.KERBEROS.REALM = {
689 kdc = your.kerberos.server
691 </programlisting></para>
694 Test your config by doing a <userinput>kinit
695 <replaceable>USERNAME</replaceable>@<replaceable>REALM</replaceable></userinput> and
696 making sure that your password is accepted by the Win2000 KDC.
700 The realm must be uppercase or you will get "Cannot find KDC for requested
701 realm while getting initial credentials" error
705 Time between the two servers must be synchronized. You will get a
706 "kinit(v5): Clock skew too great while getting initial credentials" if the time
707 difference is more than five minutes.
711 You also must ensure that you can do a reverse DNS lookup on the IP
712 address of your KDC. Also, the name that this reverse lookup maps to
713 must either be the netbios name of the KDC (ie. the hostname with no
714 domain attached) or it can alternatively be the netbios name
715 followed by the realm.
719 The easiest way to ensure you get this right is to add a
720 <filename>/etc/hosts</filename> entry mapping the IP address of your KDC to
721 its netbios name. If you don't get this right then you will get a
722 "local error" when you try to join the realm.
726 If all you want is kerberos support in &smbclient; then you can skip
727 straight to <link linkend="ads-test-smbclient">Test with &smbclient;</link> now.
728 <link linkend="ads-create-machine-account">Creating a computer account</link>
729 and <link linkend="ads-test-server">testing your servers</link>
730 is only needed if you want kerberos support for &smbd; and &winbindd;.
735 <sect2 id="ads-create-machine-account">
736 <title>Create the computer account</title>
739 As a user that has write permission on the Samba private directory
742 <userinput>net join -U Administrator%password</userinput>
747 <title>Possible errors</title>
751 <varlistentry><term>"ADS support not compiled in"</term>
752 <listitem><para>Samba must be reconfigured (remove config.cache) and recompiled
753 (make clean all install) after the kerberos libs and headers are installed.
754 </para></listitem></varlistentry>
756 <varlistentry><term>net join prompts for user name</term>
757 <listitem><para>You need to login to the domain using <userinput>kinit
758 <replaceable>USERNAME</replaceable>@<replaceable>REALM</replaceable></userinput>.
759 <replaceable>USERNAME</replaceable> must be a user who has rights to add a machine
760 to the domain. </para></listitem></varlistentry>
768 <sect2 id="ads-test-server">
769 <title>Test your server setup</title>
772 If the join was successful, you will see a new computer account with the
773 NetBIOS name of your Samba server in Active Directory (in the "Computers"
774 folder under Users and Computers.
778 On a Windows 2000 client try <userinput>net use * \\server\share</userinput>. You should
779 be logged in with kerberos without needing to know a password. If
780 this fails then run <userinput>klist tickets</userinput>. Did you get a ticket for the
781 server? Does it have an encoding type of DES-CBC-MD5 ?
786 <sect2 id="ads-test-smbclient">
787 <title>Testing with &smbclient;</title>
790 On your Samba server try to login to a Win2000 server or your Samba
791 server using &smbclient; and kerberos. Use &smbclient; as usual, but
792 specify the <parameter>-k</parameter> option to choose kerberos authentication.
801 You must change administrator password at least once after DC
802 install, to create the right encoding types
806 w2k doesn't seem to create the _kerberos._udp and _ldap._tcp in
807 their defaults DNS setup. Maybe fixed in service packs?
814 <title>Common Errors</title>
817 In the process of adding / deleting / re-adding domain member machine accounts there are
818 many traps for the unwary player and there are many "little" things that can go wrong.
819 It is particularly interesting how often subscribers on the samba mailing list have concluded
820 after repeated failed attempts to add a machine account that it is necessary to "re-install"
821 MS Windows on t he machine. In truth, it is seldom necessary to reinstall because of this type
822 of problem. The real solution is often very simple, and with understanding of how MS Windows
823 networking functions. easily overcome.
827 <title>Can Not Add Machine Back to Domain</title>
830 <emphasis>Problem:</emphasis> A Windows workstation was reinstalled. The original domain machine
831 account was deleted and added immediately. The workstation will not join the domain if I use
832 the same machine name. Attempts to add the machine fail with a message that the machine already
833 exists on the network - I know it doen't. Why is this failing?
837 The original name is still in the NetBIOS name cache and must expire after machine account
838 deletion BEFORE adding that same name as a domain member again. The best advice is to delete
839 the old account and then to add the machine with a new name.
845 <title>Adding Machine to Domain Fails</title>
848 Adding a Windows 200x or XP Professional machine to the Samba PDC Domain fails with a
849 message that, "The machine could not be added at this time, there is a network problem.
850 Please try again later." Why?
854 You should check that there is an <emphasis>add machine script</emphasis> in your &smb.conf;
855 file. If there is not, please add one that is appropriate for your OS platform. If a script
856 has been defined you will need to debug it's operation. Increase the <emphasis>log level</emphasis>
857 in the &smb.conf; file to level 10, then try to rejoin the domain. Check the logs to see which
858 operation is failing.
862 Possible causes include:
867 The script does not actually exist, or could not be located in the path specified.
871 <emphasis>Corrective Action:</emphasis> Fix it. Make sure that when run manually
872 that the script will add both the Unix system account _and_ the Samba SAM account.
876 The machine could not be added to the Unix system accounts file <filename>/etc/passwd</filename>
880 <emphasis>Corrective Action:</emphasis> Check that the machine name is a legal Unix
881 system account name. ie: If the Unix utility <command>useradd</command> is called
882 then make sure that the machine name you are trying to add can be added using this
883 tool. <command>Useradd</command> on some systems will not allow any upper case characters
884 nor will it allow spaces in the name.