docs/docbook/projdoc/winbind.xml

   1 <chapter id="winbind">
   2
   3 <chapterinfo>
   4         <authorgroup>
   5         <author>
   6                 <firstname>Tim</firstname><surname>Potter</surname>
   7                 <affiliation>
   8                         <orgname>Samba Team</orgname>
   9                         <address><email>tpot@samba.org</email></address>
  10                 </affiliation>
  11         </author>
  12         &author.tridge;
  13         <author>
  14                 <firstname>Naag</firstname><surname>Mummaneni</surname>
  15                 <affiliation>
  16                         <address><email>getnag@rediffmail.com</email></address>
  17                 </affiliation>
  18         </author>
  19         &author.jelmer;
  20         &author.jht;
  21         </authorgroup>
  22         <pubdate>27 June 2002</pubdate>
  23 </chapterinfo>
  24
  25 <title>Integrated Logon Support using Winbind</title>
  26
  27 <sect1>
  28         <title>Features and Benefits</title>
  29
  30         <para>Integration of UNIX and Microsoft Windows NT through
  31         a unified logon has been considered a "holy grail" in heterogeneous
  32         computing environments for a long time. We present
  33         <emphasis>winbind</emphasis>, a component of the Samba suite
  34         of programs as a solution to the unified logon problem. Winbind
  35         uses a UNIX implementation
  36         of Microsoft RPC calls, Pluggable Authentication Modules, and the Name
  37         Service Switch to allow Windows NT domain users to appear and operate
  38         as UNIX users on a UNIX machine. This paper describes the winbind
  39         system, explaining the functionality it provides, how it is configured,
  40         and how it works internally.</para>
  41 </sect1>
  42
  43
  44 <sect1>
  45         <title>Introduction</title>
  46
  47         <para>It is well known that UNIX and Microsoft Windows NT have
  48         different models for representing user and group information and
  49         use different technologies for implementing them. This fact has
  50         made it difficult to integrate the two systems in a satisfactory
  51         manner.</para>
  52
  53         <para>One common solution in use today has been to create
  54         identically named user accounts on both the UNIX and Windows systems
  55         and use the Samba suite of programs to provide file and print services
  56         between the two. This solution is far from perfect however, as
  57         adding and deleting users on both sets of machines becomes a chore
  58         and two sets of passwords are required both of which
  59         can lead to synchronization problems between the UNIX and Windows
  60         systems and confusion for users.</para>
  61
  62         <para>We divide the unified logon problem for UNIX machines into
  63         three smaller problems:</para>
  64
  65         <itemizedlist>
  66                 <listitem><para>Obtaining Windows NT user and group information
  67                 </para></listitem>
  68
  69                 <listitem><para>Authenticating Windows NT users
  70                 </para></listitem>
  71
  72                 <listitem><para>Password changing for Windows NT users
  73                 </para></listitem>
  74         </itemizedlist>
  75
  76
  77         <para>Ideally, a prospective solution to the unified logon problem
  78         would satisfy all the above components without duplication of
  79         information on the UNIX machines and without creating additional
  80         tasks for the system administrator when maintaining users and
  81         groups on either system. The winbind system provides a simple
  82         and elegant solution to all three components of the unified logon
  83         problem.</para>
  84 </sect1>
  85
  86
  87 <sect1>
  88         <title>What Winbind Provides</title>
  89
  90         <para>Winbind unifies UNIX and Windows NT account management by
  91         allowing a UNIX box to become a full member of a NT domain. Once
  92         this is done the UNIX box will see NT users and groups as if
  93         they were native UNIX users and groups, allowing the NT domain
  94         to be used in much the same manner that NIS+ is used within
  95         UNIX-only environments.</para>
  96
  97         <para>The end result is that whenever any
  98         program on the UNIX machine asks the operating system to lookup
  99         a user or group name, the query will be resolved by asking the
 100         NT domain controller for the specified domain to do the lookup.
 101         Because Winbind hooks into the operating system at a low level
 102         (via the NSS name resolution modules in the C library) this
 103         redirection to the NT domain controller is completely
 104         transparent.</para>
 105
 106         <para>Users on the UNIX machine can then use NT user and group
 107         names as they would use "native" UNIX names. They can chown files
 108         so that they are owned by NT domain users or even login to the
 109         UNIX machine and run a UNIX X-Window session as a domain user.</para>
 110
 111         <para>The only obvious indication that Winbind is being used is
 112         that user and group names take the form DOMAIN\user and
 113         DOMAIN\group. This is necessary as it allows Winbind to determine
 114         that redirection to a domain controller is wanted for a particular
 115         lookup and which trusted domain is being referenced.</para>
 116
 117         <para>Additionally, Winbind provides an authentication service
 118         that hooks into the Pluggable Authentication Modules (PAM) system
 119         to provide authentication via a NT domain to any PAM enabled
 120         applications. This capability solves the problem of synchronizing
 121         passwords between systems since all passwords are stored in a single
 122         location (on the domain controller).</para>
 123
 124         <sect2>
 125                 <title>Target Uses</title>
 126
 127                 <para>Winbind is targeted at organizations that have an
 128                 existing NT based domain infrastructure into which they wish
 129                 to put UNIX workstations or servers. Winbind will allow these
 130                 organizations to deploy UNIX workstations without having to
 131                 maintain a separate account infrastructure. This greatly
 132                 simplifies the administrative overhead of deploying UNIX
 133                 workstations into a NT based organization.</para>
 134
 135                 <para>Another interesting way in which we expect Winbind to
 136                 be used is as a central part of UNIX based appliances. Appliances
 137                 that provide file and print services to Microsoft based networks
 138                 will be able to use Winbind to provide seamless integration of
 139                 the appliance into the domain.</para>
 140         </sect2>
 141 </sect1>
 142
 143
 144
 145 <sect1>
 146         <title>How Winbind Works</title>
 147
 148         <para>The winbind system is designed around a client/server
 149         architecture. A long running <command>winbindd</command> daemon
 150         listens on a UNIX domain socket waiting for requests
 151         to arrive. These requests are generated by the NSS and PAM
 152         clients and processed sequentially.</para>
 153
 154         <para>The technologies used to implement winbind are described
 155         in detail below.</para>
 156
 157         <sect2>
 158                 <title>Microsoft Remote Procedure Calls</title>
 159
 160                 <para>Over the last few years, efforts have been underway
 161                 by various Samba Team members to decode various aspects of
 162                 the Microsoft Remote Procedure Call (MSRPC) system. This
 163                 system is used for most network related operations between
 164                 Windows NT machines including remote management, user authentication
 165                 and print spooling. Although initially this work was done
 166                 to aid the implementation of Primary Domain Controller (PDC)
 167                 functionality in Samba, it has also yielded a body of code which
 168                 can be used for other purposes.</para>
 169
 170                 <para>Winbind uses various MSRPC calls to enumerate domain users
 171                 and groups and to obtain detailed information about individual
 172                 users or groups. Other MSRPC calls can be used to authenticate
 173                 NT domain users and to change user passwords. By directly querying
 174                 a Windows PDC for user and group information, winbind maps the
 175                 NT account information onto UNIX user and group names.</para>
 176         </sect2>
 177
 178         <sect2>
 179                 <title>Microsoft Active Directory Services</title>
 180
 181                 <para>
 182                 Since late 2001, Samba has gained the ability to
 183                 interact with Microsoft Windows 2000 using its 'Native
 184                 Mode' protocols, rather than the NT4 RPC services.
 185                 Using LDAP and Kerberos, a domain member running
 186                 winbind can enumerate users and groups in exactly the
 187                 same way as a Win2k client would, and in so doing
 188                 provide a much more efficient and
 189                 effective winbind implementation.
 190                 </para>
 191         </sect2>
 192
 193         <sect2>
 194                 <title>Name Service Switch</title>
 195
 196                 <para>The Name Service Switch, or NSS, is a feature that is
 197                 present in many UNIX operating systems. It allows system
 198                 information such as hostnames, mail aliases and user information
 199                 to be resolved from different sources. For example, a standalone
 200                 UNIX workstation may resolve system information from a series of
 201                 flat files stored on the local filesystem. A networked workstation
 202                 may first attempt to resolve system information from local files,
 203                 and then consult a NIS database for user information or a DNS server
 204                 for hostname information.</para>
 205
 206                 <para>The NSS application programming interface allows winbind
 207                 to present itself as a source of system information when
 208                 resolving UNIX usernames and groups.  Winbind uses this interface,
 209                 and information obtained from a Windows NT server using MSRPC
 210                 calls to provide a new source of account enumeration.  Using standard
 211                 UNIX library calls, one can enumerate the users and groups on
 212                 a UNIX machine running winbind and see all users and groups in
 213                 a NT domain plus any trusted domain as though they were local
 214                 users and groups.</para>
 215
 216                 <para>The primary control file for NSS is
 217                 <filename>/etc/nsswitch.conf</filename>.
 218                 When a UNIX application makes a request to do a lookup
 219                 the C library looks in <filename>/etc/nsswitch.conf</filename>
 220                 for a line which matches the service type being requested, for
 221                 example the "passwd" service type is used when user or group names
 222                 are looked up. This     config line species which implementations
 223                 of that service should be tried and in what order. If the passwd
 224                 config line is:</para>
 225
 226                 <para><programlisting>
 227 passwd: files example
 228                 </programlisting></para>
 229
 230                 <para>then the C library will first load a module called
 231                 <filename>/lib/libnss_files.so</filename> followed by
 232                 the module <filename>/lib/libnss_example.so</filename>. The
 233                 C library will dynamically load each of these modules in turn
 234                 and call resolver functions within the modules to try to resolve
 235                 the request. Once the request is resolved the C library returns the
 236                 result to the application.</para>
 237
 238                 <para>This NSS interface provides a very easy way for Winbind
 239                 to hook into the operating system. All that needs to be done
 240                 is to put <filename>libnss_winbind.so</filename> in <filename>/lib/</filename>
 241                 then add "winbind" into <filename>/etc/nsswitch.conf</filename> at
 242                 the appropriate place. The C library will then call Winbind to
 243                 resolve user and group names.</para>
 244         </sect2>
 245
 246         <sect2>
 247                 <title>Pluggable Authentication Modules</title>
 248
 249                 <para>Pluggable Authentication Modules, also known as PAM,
 250                 is a system for abstracting authentication and authorization
 251                 technologies. With a PAM module it is possible to specify different
 252                 authentication methods for different system applications without
 253                 having to recompile these applications. PAM is also useful
 254                 for implementing a particular policy for authorization. For example,
 255                 a system administrator may only allow console logins from users
 256                 stored in the local password file but only allow users resolved from
 257                 a NIS database to log in over the network.</para>
 258
 259                 <para>Winbind uses the authentication management and password
 260                 management PAM interface to integrate Windows NT users into a
 261                 UNIX system. This allows Windows NT users to log in to a UNIX
 262                 machine and be authenticated against a suitable Primary Domain
 263                 Controller. These users can also change their passwords and have
 264                 this change take effect directly on the Primary Domain Controller.
 265                 </para>
 266
 267                 <para>PAM is configured by providing control files in the directory
 268                 <filename>/etc/pam.d/</filename> for each of the services that
 269                 require authentication. When an authentication request is made
 270                 by an application the PAM code in the C library looks up this
 271                 control file to determine what modules to load to do the
 272                 authentication check and in what order. This interface makes adding
 273                 a new authentication service for Winbind very easy, all that needs
 274                 to be done is that the <filename>pam_winbind.so</filename> module
 275                 is copied to <filename>/lib/security/</filename> and the PAM
 276                 control files for relevant services are updated to allow
 277                 authentication via winbind. See the PAM documentation
 278                 for more details.</para>
 279         </sect2>
 280
 281
 282         <sect2>
 283                 <title>User and Group ID Allocation</title>
 284
 285                 <para>When a user or group is created under Windows NT
 286                 is it allocated a numerical relative identifier (RID). This is
 287                 slightly different to UNIX which has a range of numbers that are
 288                 used to identify users, and the same range in which to identify
 289                 groups. It is winbind's job to convert RIDs to UNIX id numbers and
 290                 vice versa.  When winbind is configured it is given part of the UNIX
 291                 user id space and a part of the UNIX group id space in which to
 292                 store Windows NT users and groups. If a Windows NT user is
 293                 resolved for the first time, it is allocated the next UNIX id from
 294                 the range. The same process applies for Windows NT groups. Over
 295                 time, winbind will have mapped all Windows NT users and groups
 296                 to UNIX user ids and group ids.</para>
 297
 298                 <para>The results of this mapping are stored persistently in
 299                 an ID mapping database held in a tdb database). This ensures that
 300                 RIDs are mapped to UNIX IDs in a consistent way.</para>
 301         </sect2>
 302
 303
 304         <sect2>
 305                 <title>Result Caching</title>
 306
 307                 <para>An active system can generate a lot of user and group
 308                 name lookups. To reduce the network cost of these lookups winbind
 309                 uses a caching scheme based on the SAM sequence number supplied
 310                 by NT domain controllers.  User or group information returned
 311                 by a PDC is cached by winbind along with a sequence number also
 312                 returned by the PDC. This sequence number is incremented by
 313                 Windows NT whenever any user or group information is modified. If
 314                 a cached entry has expired, the sequence number is requested from
 315                 the PDC and compared against the sequence number of the cached entry.
 316                 If the sequence numbers do not match, then the cached information
 317                 is discarded and up to date information is requested directly
 318                 from the PDC.</para>
 319         </sect2>
 320 </sect1>
 321
 322
 323 <sect1>
 324         <title>Installation and Configuration</title>
 325
 326 <para>
 327 Many thanks to John Trostel <ulink
 328 url="mailto:jtrostel@snapserver.com">jtrostel@snapserver.com</ulink>
 329 for providing the HOWTO for this section.
 330 </para>
 331
 332 <para>
 333 This HOWTO describes how to get winbind services up and running
 334 to control access and authenticate users on your Linux box using
 335 the winbind services which come with SAMBA 3.0.
 336 </para>
 337
 338 <sect2>
 339 <title>Introduction</title>
 340
 341 <para>
 342 This section describes the procedures used to get winbind up and
 343 running on a RedHat 7.1 system.  Winbind is capable of providing access
 344 and authentication control for Windows Domain users through an NT
 345 or Win2K PDC for 'regular' services, such as telnet a nd ftp, as
 346 well for SAMBA services.
 347 </para>
 348
 349 <para>
 350 This HOWTO has been written from a 'RedHat-centric' perspective, so if
 351 you are using another distribution, you may have to modify the instructions
 352 somewhat to fit the way your distribution works.
 353 </para>
 354
 355
 356 <itemizedlist>
 357 <listitem>
 358         <para>
 359         <emphasis>Why should I to this?</emphasis>
 360         </para>
 361
 362         <para>This allows the SAMBA administrator to rely on the
 363         authentication mechanisms on the NT/Win2K PDC for the authentication
 364         of domain members.  NT/Win2K users no longer need to have separate
 365         accounts on the SAMBA server.
 366         </para>
 367 </listitem>
 368
 369 <listitem>
 370         <para>
 371         <emphasis>Who should be reading this document?</emphasis>
 372         </para>
 373
 374         <para>
 375         This HOWTO is designed for system administrators.  If you are
 376         implementing SAMBA on a file server and wish to (fairly easily)
 377         integrate existing NT/Win2K users from your PDC onto the
 378         SAMBA server, this HOWTO is for you.  That said, I am no NT or PAM
 379         expert, so you may find a better or easier way to accomplish
 380         these tasks.
 381         </para>
 382 </listitem>
 383 </itemizedlist>
 384 </sect2>
 385
 386
 387 <sect2>
 388 <title>Requirements</title>
 389
 390 <para>
 391 If you have a Samba configuration file that you are currently
 392 using... <emphasis>BACK IT UP!</emphasis>  If your system already uses PAM,
 393 <emphasis>back up the <filename>/etc/pam.d</filename> directory
 394 contents!</emphasis> If you haven't already made a boot disk,
 395 <emphasis>MAKE ONE NOW!</emphasis>
 396 </para>
 397
 398 <para>
 399 Messing with the PAM configuration files can make it nearly impossible
 400 to log in to your machine. That's why you want to be able to boot back
 401 into your machine in single user mode and restore your
 402 <filename>/etc/pam.d</filename> back to the original state they were in if
 403 you get frustrated with the way things are going.  ;-)
 404 </para>
 405
 406 <para>
 407 The latest version of SAMBA (version 3.0 as of this writing), now
 408 includes a functioning winbindd daemon.  Please refer to the
 409 <ulink url="http://samba.org/">main SAMBA web page</ulink> or,
 410 better yet, your closest SAMBA mirror site for instructions on
 411 downloading the source code.
 412 </para>
 413
 414 <para>
 415 To allow Domain users the ability to access SAMBA shares and
 416 files, as well as potentially other services provided by your
 417 SAMBA machine, PAM (pluggable authentication modules) must
 418 be setup properly on your machine.  In order to compile the
 419 winbind modules, you should have at least the pam libraries resident
 420 on your system.  For recent RedHat systems (7.1, for instance), that
 421 means <filename>pam-0.74-22</filename>.  For best results, it is helpful to also
 422 install the development packages in <filename>pam-devel-0.74-22</filename>.
 423 </para>
 424
 425 </sect2>
 426
 427
 428 <sect2>
 429 <title>Testing Things Out</title>
 430
 431 <para>
 432 Before starting, it is probably best to kill off all the SAMBA
 433 related daemons running on your server.  Kill off all &smbd;,
 434 &nmbd;, and &winbindd; processes that may
 435 be running.  To use PAM, you will want to make sure that you have the
 436 standard PAM package (for RedHat) which supplies the <filename>/etc/pam.d</filename>
 437 directory structure, including the pam modules are used by pam-aware
 438 services, several pam libraries, and the <filename>/usr/doc</filename>
 439 and <filename>/usr/man</filename> entries for pam.  Winbind built better
 440 in SAMBA if the pam-devel package was also installed.  This package includes
 441 the header files needed to compile pam-aware applications.
 442 </para>
 443
 444 <sect3>
 445 <title>Configure and compile SAMBA</title>
 446
 447 <para>
 448 The configuration and compilation of SAMBA is pretty straightforward.
 449 The first three steps may not be necessary depending upon
 450 whether or not you have previously built the Samba binaries.
 451 </para>
 452
 453 <para><screen>
 454 &rootprompt;<command>autoconf</command>
 455 &rootprompt;<command>make clean</command>
 456 &rootprompt;<command>rm config.cache</command>
 457 &rootprompt;<command>./configure</command>
 458 &rootprompt;<command>make</command>
 459 &rootprompt;<command>make install</command>
 460 </screen></para>
 461
 462
 463 <para>
 464 This will, by default, install SAMBA in <filename>/usr/local/samba</filename>.
 465 See the main SAMBA documentation if you want to install SAMBA somewhere else.
 466 It will also build the winbindd executable and libraries.
 467 </para>
 468
 469 </sect3>
 470
 471 <sect3>
 472 <title>Configure <filename>nsswitch.conf</filename> and the
 473 winbind libraries on Linux and Solaris</title>
 474
 475 <para>
 476 The libraries needed to run the &winbindd; daemon
 477 through nsswitch need to be copied to their proper locations, so
 478 </para>
 479
 480 <para>
 481 <screen>
 482 &rootprompt;<userinput>cp ../samba/source/nsswitch/libnss_winbind.so /lib</userinput>
 483 </screen>
 484 </para>
 485
 486 <para>
 487 I also found it necessary to make the following symbolic link:
 488 </para>
 489
 490 <para>
 491 &rootprompt; <userinput>ln -s /lib/libnss_winbind.so /lib/libnss_winbind.so.2</userinput>
 492 </para>
 493
 494 <para>And, in the case of Sun Solaris:</para>
 495 <screen>
 496 &rootprompt;<userinput>ln -s /usr/lib/libnss_winbind.so /usr/lib/libnss_winbind.so.1</userinput>
 497 &rootprompt;<userinput>ln -s /usr/lib/libnss_winbind.so /usr/lib/nss_winbind.so.1</userinput>
 498 &rootprompt;<userinput>ln -s /usr/lib/libnss_winbind.so /usr/lib/nss_winbind.so.2</userinput>
 499 </screen>
 500
 501 <para>
 502 Now, as root you need to edit <filename>/etc/nsswitch.conf</filename> to
 503 allow user and group entries to be visible from the &winbindd;
 504 daemon.  My <filename>/etc/nsswitch.conf</filename> file look like
 505 this after editing:
 506 </para>
 507
 508 <para><programlisting>
 509         passwd:     files winbind
 510         shadow:     files
 511         group:      files winbind
 512 </programlisting></para>
 513
 514 <para>
 515 The libraries needed by the winbind daemon will be automatically
 516 entered into the <command>ldconfig</command> cache the next time
 517 your system reboots, but it
 518 is faster (and you don't need to reboot) if you do it manually:
 519 </para>
 520
 521 <para>
 522 &rootprompt;<userinput>/sbin/ldconfig -v | grep winbind</userinput>
 523 </para>
 524
 525 <para>
 526 This makes <filename>libnss_winbind</filename> available to winbindd
 527 and echos back a check to you.
 528 </para>
 529
 530 </sect3>
 531
 532 <sect3>
 533 <title>NSS Winbind on AIX</title>
 534
 535 <para>(This section is only for those running AIX)</para>
 536
 537 <para>
 538 The winbind AIX identification module gets built as libnss_winbind.so in the
 539 nsswitch directory of the samba source.  This file can be copied to
 540 /usr/lib/security, and the AIX naming convention would indicate that it
 541 should be named WINBIND.  A stanza like the following:
 542 </para>
 543
 544 <para><programlisting>
 545 WINBIND:
 546         program = /usr/lib/security/WINBIND
 547         options = authonly
 548 </programlisting></para>
 549
 550 <para>can then be added to
 551 <filename>/usr/lib/security/methods.cfg</filename>.  This module only
 552 supports identification, but there have been success reports using the
 553 standard winbind pam module for authentication.  Use caution configuring
 554 loadable authentication modules as it is possible to make it impossible
 555 to logon to the system.  More information about the AIX authentication
 556 module API can be found at &quot;Kernel Extensions and Device Support
 557 Programming Concepts for AIX&quot;: <ulink
 558 url="http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixprggd/kernextc/sec_load_mod.htm">
 559 Chapter 18. Loadable Authentication Module Programming Interface</ulink>
 560 and more information on administering the  modules at <ulink
 561 url="http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixbman/baseadmn/iandaadmin.htm">
 562 &quot;System Management Guide: Operating System and Devices&quot;</ulink>.
 563 </para>
 564 </sect3>
 565
 566 <sect3>
 567 <title>Configure smb.conf</title>
 568
 569 <para>
 570 Several parameters are needed in the smb.conf file to control
 571 the behavior of &winbindd;. Configure
 572 &smb.conf; These are described in more detail in
 573 the <citerefentry><refentrytitle>winbindd</refentrytitle>
 574 <manvolnum>8</manvolnum></citerefentry> man page.  My
 575 &smb.conf; file was modified to
 576 include the following entries in the [global] section:
 577 </para>
 578
 579 <para><programlisting>
 580 [global]
 581      &lt;...&gt;
 582      # separate domain and username with '+', like DOMAIN+username
 583      <ulink url="winbindd.8.html#WINBINDSEPARATOR">winbind separator</ulink> = +
 584      # use uids from 10000 to 20000 for domain users
 585      <ulink url="winbindd.8.html#WINBINDUID">idmap uid</ulink> = 10000-20000
 586      # use gids from 10000 to 20000 for domain groups
 587      <ulink url="winbindd.8.html#WINBINDGID">idmap gid</ulink> = 10000-20000
 588      # allow enumeration of winbind users and groups
 589      <ulink url="winbindd.8.html#WINBINDENUMUSERS">winbind enum users</ulink> = yes
 590      <ulink url="winbindd.8.html#WINBINDENUMGROUP">winbind enum groups</ulink> = yes
 591      # give winbind users a real shell (only needed if they have telnet access)
 592      <ulink url="winbindd.8.html#TEMPLATEHOMEDIR">template homedir</ulink> = /home/winnt/%D/%U
 593      <ulink url="winbindd.8.html#TEMPLATESHELL">template shell</ulink> = /bin/bash
 594 </programlisting></para>
 595
 596 </sect3>
 597
 598
 599 <sect3>
 600 <title>Join the SAMBA server to the PDC domain</title>
 601
 602 <para>
 603 Enter the following command to make the SAMBA server join the
 604 PDC domain, where <replaceable>DOMAIN</replaceable> is the name of
 605 your Windows domain and <replaceable>Administrator</replaceable> is
 606 a domain user who has administrative privileges in the domain.
 607 </para>
 608
 609
 610 <para>
 611 &rootprompt;<userinput>/usr/local/samba/bin/net join -S PDC -U Administrator</userinput>
 612 </para>
 613
 614
 615 <para>
 616 The proper response to the command should be: "Joined the domain
 617 <replaceable>DOMAIN</replaceable>" where <replaceable>DOMAIN</replaceable>
 618 is your DOMAIN name.
 619 </para>
 620
 621 </sect3>
 622
 623
 624 <sect3>
 625 <title>Start up the winbindd daemon and test it!</title>
 626
 627 <para>
 628 Eventually, you will want to modify your smb startup script to
 629 automatically invoke the winbindd daemon when the other parts of
 630 SAMBA start, but it is possible to test out just the winbind
 631 portion first.  To start up winbind services, enter the following
 632 command as root:
 633 </para>
 634
 635 <para>
 636 &rootprompt;<userinput>/usr/local/samba/bin/winbindd</userinput>
 637 </para>
 638
 639 <para>
 640 Winbindd can now also run in 'dual daemon mode'. This will make it
 641 run as 2 processes. The first will answer all requests from the cache,
 642 thus making responses to clients faster. The other will
 643 update the cache for the query that the first has just responded.
 644 Advantage of this is that responses stay accurate and are faster.
 645 You can enable dual daemon mode by adding <option>-B</option> to the commandline:
 646 </para>
 647
 648 <para>
 649 &rootprompt;<userinput>/usr/local/samba/bin/winbindd -B</userinput>
 650 </para>
 651
 652 <para>
 653 I'm always paranoid and like to make sure the daemon
 654 is really running...
 655 </para>
 656
 657 <para>
 658 &rootprompt;<userinput>ps -ae | grep winbindd</userinput>
 659 </para>
 660 <para>
 661 This command should produce output like this, if the daemon is running
 662 </para>
 663 <screen>
 664 3025 ?        00:00:00 winbindd
 665 </screen>
 666
 667 <para>
 668 Now... for the real test, try to get some information about the
 669 users on your PDC
 670 </para>
 671
 672 <para>
 673 &rootprompt;<userinput>/usr/local/samba/bin/wbinfo -u</userinput>
 674 </para>
 675
 676 <para>
 677 This should echo back a list of users on your Windows users on
 678 your PDC.  For example, I get the following response:
 679 </para>
 680
 681 <para><screen>
 682         CEO+Administrator
 683         CEO+burdell
 684         CEO+Guest
 685         CEO+jt-ad
 686         CEO+krbtgt
 687         CEO+TsInternetUser
 688 </screen></para>
 689
 690 <para>
 691 Obviously, I have named my domain 'CEO' and my <parameter>winbind
 692 separator</parameter> is '+'.
 693 </para>
 694
 695 <para>
 696 You can do the same sort of thing to get group information from
 697 the PDC:
 698 </para>
 699
 700 <para><screen>
 701 &rootprompt;<userinput>/usr/local/samba/bin/wbinfo -g</userinput>
 702         CEO+Domain Admins
 703         CEO+Domain Users
 704         CEO+Domain Guests
 705         CEO+Domain Computers
 706         CEO+Domain Controllers
 707         CEO+Cert Publishers
 708         CEO+Schema Admins
 709         CEO+Enterprise Admins
 710         CEO+Group Policy Creator Owners
 711 </screen></para>
 712
 713 <para>
 714 The function 'getent' can now be used to get unified
 715 lists of both local and PDC users and groups.
 716 Try the following command:
 717 </para>
 718
 719 <para>
 720 &rootprompt;<userinput>getent passwd</userinput>
 721 </para>
 722
 723 <para>
 724 You should get a list that looks like your <filename>/etc/passwd</filename>
 725 list followed by the domain users with their new uids, gids, home
 726 directories and default shells.
 727 </para>
 728
 729 <para>
 730 The same thing can be done for groups with the command
 731 </para>
 732
 733 <para>
 734 &rootprompt;<userinput>getent group</userinput>
 735 </para>
 736
 737 </sect3>
 738
 739
 740 <sect3>
 741 <title>Fix the init.d startup scripts</title>
 742
 743 <sect4>
 744 <title>Linux</title>
 745
 746 <para>
 747 The &winbindd; daemon needs to start up after the
 748 &smbd; and &nmbd; daemons are running.
 749 To accomplish this task, you need to modify the startup scripts of your system.
 750 They are located at <filename>/etc/init.d/smb</filename> in RedHat and
 751 <filename>/etc/init.d/samba</filename> in Debian.
 752 script to add commands to invoke this daemon in the proper sequence.  My
 753 startup script starts up &smbd;, &nmbd;, and &winbindd; from the
 754 <filename>/usr/local/samba/bin</filename> directory directly.  The 'start'
 755 function in the script looks like this:
 756 </para>
 757
 758 <para><programlisting>
 759 start() {
 760         KIND="SMB"
 761         echo -n $"Starting $KIND services: "
 762         daemon /usr/local/samba/bin/smbd $SMBDOPTIONS
 763         RETVAL=$?
 764         echo
 765         KIND="NMB"
 766         echo -n $"Starting $KIND services: "
 767         daemon /usr/local/samba/bin/nmbd $NMBDOPTIONS
 768         RETVAL2=$?
 769         echo
 770         KIND="Winbind"
 771         echo -n $"Starting $KIND services: "
 772         daemon /usr/local/samba/bin/winbindd
 773         RETVAL3=$?
 774         echo
 775         [ $RETVAL -eq 0 -a $RETVAL2 -eq 0 -a $RETVAL3 -eq 0 ] &amp;&amp; \
 776                 touch /var/lock/subsys/smb || RETVAL=1
 777         return $RETVAL
 778 }
 779 </programlisting></para>
 780
 781 <para>If you would like to run winbindd in dual daemon mode, replace
 782 the line
 783 <programlisting>
 784         daemon /usr/local/samba/bin/winbindd
 785 </programlisting>
 786
 787 in the example above with:
 788
 789 <programlisting>
 790         daemon /usr/local/samba/bin/winbindd -B
 791 </programlisting>.
 792 </para>
 793
 794 <para>
 795 The 'stop' function has a corresponding entry to shut down the
 796 services and looks like this:
 797 </para>
 798
 799 <para><programlisting>
 800 stop() {
 801         KIND="SMB"
 802         echo -n $"Shutting down $KIND services: "
 803         killproc smbd
 804         RETVAL=$?
 805         echo
 806         KIND="NMB"
 807         echo -n $"Shutting down $KIND services: "
 808         killproc nmbd
 809         RETVAL2=$?
 810         echo
 811         KIND="Winbind"
 812         echo -n $"Shutting down $KIND services: "
 813         killproc winbindd
 814         RETVAL3=$?
 815         [ $RETVAL -eq 0 -a $RETVAL2 -eq 0 -a $RETVAL3 -eq 0 ] &amp;&amp; \
 816                  rm -f /var/lock/subsys/smb
 817         echo ""
 818         return $RETVAL
 819 }
 820 </programlisting></para>
 821 </sect4>
 822
 823 <sect4>
 824 <title>Solaris</title>
 825
 826 <para>Winbind doesn't work on Solaris 9, see the <link linkend="winbind-solaris9">Portability</link> chapter for details.</para>
 827
 828 <para>On Solaris, you need to modify the
 829 <filename>/etc/init.d/samba.server</filename> startup script. It usually
 830 only starts smbd and nmbd but should now start winbindd too. If you
 831 have samba installed in <filename>/usr/local/samba/bin</filename>,
 832 the file could contains something like this:
 833 </para>
 834
 835 <para><programlisting>
 836         ##
 837         ## samba.server
 838         ##
 839
 840         if [ ! -d /usr/bin ]
 841         then                    # /usr not mounted
 842                 exit
 843         fi
 844
 845         killproc() {            # kill the named process(es)
 846                 pid=`/usr/bin/ps -e |
 847                      /usr/bin/grep -w $1 |
 848                      /usr/bin/sed -e 's/^  *//' -e 's/ .*//'`
 849                 [ "$pid" != "" ] &amp;&amp; kill $pid
 850         }
 851
 852         # Start/stop processes required for samba server
 853
 854         case "$1" in
 855
 856         'start')
 857         #
 858         # Edit these lines to suit your installation (paths, workgroup, host)
 859         #
 860         echo Starting SMBD
 861            /usr/local/samba/bin/smbd -D -s \
 862                 /usr/local/samba/smb.conf
 863
 864         echo Starting NMBD
 865            /usr/local/samba/bin/nmbd -D -l \
 866                 /usr/local/samba/var/log -s /usr/local/samba/smb.conf
 867
 868         echo Starting Winbind Daemon
 869            /usr/local/samba/bin/winbindd
 870            ;;
 871
 872         'stop')
 873            killproc nmbd
 874            killproc smbd
 875            killproc winbindd
 876            ;;
 877
 878         *)
 879            echo "Usage: /etc/init.d/samba.server { start | stop }"
 880            ;;
 881         esac
 882 </programlisting></para>
 883
 884 <para>
 885 Again, if you would like to run samba in dual daemon mode, replace
 886 <programlisting>
 887         /usr/local/samba/bin/winbindd
 888 </programlisting>
 889
 890 in the script above with:
 891
 892 <programlisting>
 893         /usr/local/samba/bin/winbindd -B
 894 </programlisting>
 895 </para>
 896
 897 </sect4>
 898
 899 <sect4>
 900 <title>Restarting</title>
 901 <para>
 902 If you restart the &smbd;, &nmbd;, and &winbindd; daemons at this point, you
 903 should be able to connect to the samba server as a domain member just as
 904 if you were a local user.
 905 </para>
 906 </sect4>
 907 </sect3>
 908
 909 <sect3>
 910 <title>Configure Winbind and PAM</title>
 911
 912 <para>
 913 If you have made it this far, you know that winbindd and samba are working
 914 together.  If you want to use winbind to provide authentication for other
 915 services, keep reading.  The pam configuration files need to be altered in
 916 this step.  (Did you remember to make backups of your original
 917 <filename>/etc/pam.d</filename> files? If not, do it now.)
 918 </para>
 919
 920 <para>
 921 You will need a pam module to use winbindd with these other services.  This
 922 module will be compiled in the <filename>../source/nsswitch</filename> directory
 923 by invoking the command
 924 </para>
 925
 926 <para>
 927 &rootprompt;<userinput>make nsswitch/pam_winbind.so</userinput>
 928 </para>
 929
 930 <para>
 931 from the <filename>../source</filename> directory.  The
 932 <filename>pam_winbind.so</filename> file should be copied to the location of
 933 your other pam security modules.  On my RedHat system, this was the
 934 <filename>/lib/security</filename> directory. On Solaris, the pam security
 935 modules reside in <filename>/usr/lib/security</filename>.
 936 </para>
 937
 938 <para>
 939 &rootprompt;<userinput>cp ../samba/source/nsswitch/pam_winbind.so /lib/security</userinput>
 940 </para>
 941
 942 <sect4>
 943 <title>Linux/FreeBSD-specific PAM configuration</title>
 944
 945 <para>
 946 The <filename>/etc/pam.d/samba</filename> file does not need to be changed. I
 947 just left this file as it was:
 948 </para>
 949
 950
 951 <para><programlisting>
 952         auth    required        /lib/security/pam_stack.so service=system-auth
 953         account required        /lib/security/pam_stack.so service=system-auth
 954 </programlisting></para>
 955
 956 <para>
 957 The other services that I modified to allow the use of winbind
 958 as an authentication service were the normal login on the console (or a terminal
 959 session), telnet logins, and ftp service.  In order to enable these
 960 services, you may first need to change the entries in
 961 <filename>/etc/xinetd.d</filename> (or <filename>/etc/inetd.conf</filename>).
 962 RedHat 7.1 uses the new xinetd.d structure, in this case you need
 963 to change the lines in <filename>/etc/xinetd.d/telnet</filename>
 964 and <filename>/etc/xinetd.d/wu-ftp</filename> from
 965 </para>
 966
 967 <para><programlisting>
 968         enable = no
 969 </programlisting></para>
 970
 971 <para>
 972 to
 973 </para>
 974
 975 <para><programlisting>
 976         enable = yes
 977 </programlisting></para>
 978
 979 <para>
 980 For ftp services to work properly, you will also need to either
 981 have individual directories for the domain users already present on
 982 the server, or change the home directory template to a general
 983 directory for all domain users.  These can be easily set using
 984 the &smb.conf; global entry
 985 <parameter>template homedir</parameter>.
 986 </para>
 987
 988 <para>
 989 The <filename>/etc/pam.d/ftp</filename> file can be changed
 990 to allow winbind ftp access in a manner similar to the
 991 samba file.  My <filename>/etc/pam.d/ftp</filename> file was
 992 changed to look like this:
 993 </para>
 994
 995 <para><programlisting>
 996         auth       required     /lib/security/pam_listfile.so item=user sense=deny \
 997                  file=/etc/ftpusers onerr=succeed
 998         auth       sufficient   /lib/security/pam_winbind.so
 999         auth       required     /lib/security/pam_stack.so service=system-auth
1000         auth       required     /lib/security/pam_shells.so
1001         account    sufficient   /lib/security/pam_winbind.so
1002         account    required     /lib/security/pam_stack.so service=system-auth
1003         session    required     /lib/security/pam_stack.so service=system-auth
1004 </programlisting></para>
1005
1006 <para>
1007 The <filename>/etc/pam.d/login</filename> file can be changed nearly the
1008 same way.  It now looks like this:
1009 </para>
1010
1011 <para><programlisting>
1012         auth       required     /lib/security/pam_securetty.so
1013         auth       sufficient   /lib/security/pam_winbind.so
1014         auth       sufficient   /lib/security/pam_unix.so use_first_pass
1015         auth       required     /lib/security/pam_stack.so service=system-auth
1016         auth       required     /lib/security/pam_nologin.so
1017         account    sufficient   /lib/security/pam_winbind.so
1018         account    required     /lib/security/pam_stack.so service=system-auth
1019         password   required     /lib/security/pam_stack.so service=system-auth
1020         session    required     /lib/security/pam_stack.so service=system-auth
1021         session    optional     /lib/security/pam_console.so
1022 </programlisting></para>
1023
1024 <para>
1025 In this case, I added the <programlisting>auth sufficient /lib/security/pam_winbind.so</programlisting>
1026 lines as before, but also added the <programlisting>required pam_securetty.so</programlisting>
1027 above it, to disallow root logins over the network.  I also added a
1028 <command>sufficient /lib/security/pam_unix.so use_first_pass</command>
1029 line after the <command>winbind.so</command> line to get rid of annoying
1030 double prompts for passwords.
1031 </para>
1032
1033 </sect4>
1034
1035 <sect4>
1036 <title>Solaris-specific configuration</title>
1037
1038 <para>
1039 The /etc/pam.conf needs to be changed. I changed this file so that my Domain
1040 users can logon both locally as well as telnet.The following are the changes
1041 that I made.You can customize the pam.conf file as per your requirements,but
1042 be sure of those changes because in the worst case it will leave your system
1043 nearly impossible to boot.
1044 </para>
1045
1046 <para><programlisting>
1047         #
1048         #ident  "@(#)pam.conf   1.14    99/09/16 SMI"
1049         #
1050         # Copyright (c) 1996-1999, Sun Microsystems, Inc.
1051         # All Rights Reserved.
1052         #
1053         # PAM configuration
1054         #
1055         # Authentication management
1056         #
1057         login   auth required   /usr/lib/security/pam_winbind.so
1058         login   auth required   /usr/lib/security/$ISA/pam_unix.so.1 try_first_pass
1059         login   auth required   /usr/lib/security/$ISA/pam_dial_auth.so.1 try_first_pass
1060         #
1061         rlogin  auth sufficient /usr/lib/security/pam_winbind.so
1062         rlogin  auth sufficient /usr/lib/security/$ISA/pam_rhosts_auth.so.1
1063         rlogin  auth required   /usr/lib/security/$ISA/pam_unix.so.1 try_first_pass
1064         #
1065         dtlogin auth sufficient /usr/lib/security/pam_winbind.so
1066         dtlogin auth required   /usr/lib/security/$ISA/pam_unix.so.1 try_first_pass
1067         #
1068         rsh     auth required   /usr/lib/security/$ISA/pam_rhosts_auth.so.1
1069         other   auth sufficient /usr/lib/security/pam_winbind.so
1070         other   auth required   /usr/lib/security/$ISA/pam_unix.so.1 try_first_pass
1071         #
1072         # Account management
1073         #
1074         login   account sufficient      /usr/lib/security/pam_winbind.so
1075         login   account requisite       /usr/lib/security/$ISA/pam_roles.so.1
1076         login   account required        /usr/lib/security/$ISA/pam_unix.so.1
1077         #
1078         dtlogin account sufficient      /usr/lib/security/pam_winbind.so
1079         dtlogin account requisite       /usr/lib/security/$ISA/pam_roles.so.1
1080         dtlogin account required        /usr/lib/security/$ISA/pam_unix.so.1
1081         #
1082         other   account sufficient      /usr/lib/security/pam_winbind.so
1083         other   account requisite       /usr/lib/security/$ISA/pam_roles.so.1
1084         other   account required        /usr/lib/security/$ISA/pam_unix.so.1
1085         #
1086         # Session management
1087         #
1088         other   session required        /usr/lib/security/$ISA/pam_unix.so.1
1089         #
1090         # Password management
1091         #
1092         #other   password sufficient     /usr/lib/security/pam_winbind.so
1093         other   password required       /usr/lib/security/$ISA/pam_unix.so.1
1094         dtsession auth required /usr/lib/security/$ISA/pam_unix.so.1
1095         #
1096         # Support for Kerberos V5 authentication (uncomment to use Kerberos)
1097         #
1098         #rlogin auth optional   /usr/lib/security/$ISA/pam_krb5.so.1 try_first_pass
1099         #login  auth optional   /usr/lib/security/$ISA/pam_krb5.so.1 try_first_pass
1100         #dtlogin        auth optional   /usr/lib/security/$ISA/pam_krb5.so.1 try_first_pass
1101         #other  auth optional   /usr/lib/security/$ISA/pam_krb5.so.1 try_first_pass
1102         #dtlogin        account optional /usr/lib/security/$ISA/pam_krb5.so.1
1103         #other  account optional /usr/lib/security/$ISA/pam_krb5.so.1
1104         #other  session optional /usr/lib/security/$ISA/pam_krb5.so.1
1105         #other  password optional /usr/lib/security/$ISA/pam_krb5.so.1 try_first_pass
1106 </programlisting></para>
1107
1108 <para>
1109 I also added a try_first_pass line after the winbind.so line to get rid of
1110 annoying double prompts for passwords.
1111 </para>
1112
1113 <para>
1114 Now restart your Samba and try connecting through your application that you
1115 configured in the pam.conf.
1116 </para>
1117
1118 </sect4>
1119
1120 </sect3>
1121
1122 </sect2>
1123
1124 </sect1>
1125
1126 <sect1>
1127 <title>Conclusion</title>
1128
1129         <para>The winbind system, through the use of the Name Service
1130         Switch, Pluggable Authentication Modules, and appropriate
1131         Microsoft RPC calls have allowed us to provide seamless
1132         integration of Microsoft Windows NT domain users on a
1133         UNIX system. The result is a great reduction in the administrative
1134         cost of running a mixed UNIX and NT network.</para>
1135
1136 </sect1>
1137
1138 <sect1>
1139 <title>Common Errors</title>
1140
1141         <para>Winbind has a number of limitations in its current
1142         released version that we hope to overcome in future
1143         releases:</para>
1144
1145         <itemizedlist>
1146                 <listitem><para>Winbind is currently only available for
1147                 the Linux, Solaris and IRIX operating systems, although ports to other operating
1148                 systems are certainly possible. For such ports to be feasible,
1149                 we require the C library of the target operating system to
1150                 support the Name Service Switch and Pluggable Authentication
1151                 Modules systems. This is becoming more common as NSS and
1152                 PAM gain support among UNIX vendors.</para></listitem>
1153
1154                 <listitem><para>The mappings of Windows NT RIDs to UNIX ids
1155                 is not made algorithmically and depends on the order in which
1156                 unmapped users or groups are seen by winbind. It may be difficult
1157                 to recover the mappings of rid to UNIX id mapping if the file
1158                 containing this information is corrupted or destroyed.</para>
1159                 </listitem>
1160
1161                 <listitem><para>Currently the winbind PAM module does not take
1162                 into account possible workstation and logon time restrictions
1163                 that may be been set for Windows NT users, this is
1164                 instead up to the PDC to enforce.</para></listitem>
1165         </itemizedlist>
1166 </sect1>
1167
1168 </chapter>