docs/htmldocs/winbindd.8.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <HTML
   3 ><HEAD
   4 ><TITLE
   5 >winbindd</TITLE
   6 ><META
   7 NAME="GENERATOR"
   8 CONTENT="Modular DocBook HTML Stylesheet Version 1.77"></HEAD
   9 ><BODY
  10 CLASS="REFENTRY"
  11 BGCOLOR="#FFFFFF"
  12 TEXT="#000000"
  13 LINK="#0000FF"
  14 VLINK="#840084"
  15 ALINK="#0000FF"
  16 ><H1
  17 ><A
  18 NAME="WINBINDD"
  19 ></A
  20 >winbindd</H1
  21 ><DIV
  22 CLASS="REFNAMEDIV"
  23 ><A
  24 NAME="AEN5"
  25 ></A
  26 ><H2
  27 >Name</H2
  28 >winbindd&nbsp;--&nbsp;Name Service Switch daemon for resolving names
  29         from NT servers</DIV
  30 ><DIV
  31 CLASS="REFSYNOPSISDIV"
  32 ><A
  33 NAME="AEN8"
  34 ></A
  35 ><H2
  36 >Synopsis</H2
  37 ><P
  38 ><B
  39 CLASS="COMMAND"
  40 >winbindd</B
  41 >  [-i] [-d &lt;debug level&gt;] [-s &lt;smb config file&gt;]</P
  42 ></DIV
  43 ><DIV
  44 CLASS="REFSECT1"
  45 ><A
  46 NAME="AEN14"
  47 ></A
  48 ><H2
  49 >DESCRIPTION</H2
  50 ><P
  51 >This program is part of the <A
  52 HREF="samba.7.html"
  53 TARGET="_top"
  54 >       Samba</A
  55 > suite.</P
  56 ><P
  57 ><B
  58 CLASS="COMMAND"
  59 >winbindd</B
  60 > is a daemon that provides
  61         a service for the Name Service Switch capability that is present
  62         in most modern C libraries.  The Name Service Switch allows user
  63         and system information to be obtained from different databases
  64         services such as NIS or DNS.  The exact behaviour can be configured
  65         throught the <TT
  66 CLASS="FILENAME"
  67 >/etc/nsswitch.conf</TT
  68 > file.
  69         Users and groups are allocated as they are resolved to a range
  70         of user and group ids specified by the administrator of the
  71         Samba system.</P
  72 ><P
  73 >The service provided by <B
  74 CLASS="COMMAND"
  75 >winbindd</B
  76 > is called `winbind' and
  77         can be used to resolve user and group information from a
  78         Windows NT server. The service can also provide authentication
  79         services via an associated PAM module. </P
  80 ><P
  81 >       The <TT
  82 CLASS="FILENAME"
  83 >pam_winbind</TT
  84 > module in the 2.2.2 release only
  85         supports the <TT
  86 CLASS="PARAMETER"
  87 ><I
  88 >auth</I
  89 ></TT
  90 > and <TT
  91 CLASS="PARAMETER"
  92 ><I
  93 >account</I
  94 ></TT
  95 >
  96         module-types.  The latter simply
  97         performs a getpwnam() to verify that the system can obtain a uid for the
  98         user.  If the <TT
  99 CLASS="FILENAME"
 100 >libnss_winbind</TT
 101 > library has been correctly
 102         installed, this should always succeed.
 103         </P
 104 ><P
 105 >The following nsswitch databases are implemented by
 106         the winbindd service: </P
 107 ><P
 108 ></P
 109 ><DIV
 110 CLASS="VARIABLELIST"
 111 ><DL
 112 ><DT
 113 >hosts</DT
 114 ><DD
 115 ><P
 116 >User information traditionally stored in
 117                 the <TT
 118 CLASS="FILENAME"
 119 >hosts(5)</TT
 120 > file and used by
 121                 <B
 122 CLASS="COMMAND"
 123 >gethostbyname(3)</B
 124 > functions. Names are
 125                 resolved through the WINS server or by broadcast.
 126                 </P
 127 ></DD
 128 ><DT
 129 >passwd</DT
 130 ><DD
 131 ><P
 132 >User information traditionally stored in
 133                 the <TT
 134 CLASS="FILENAME"
 135 >passwd(5)</TT
 136 > file and used by
 137                 <B
 138 CLASS="COMMAND"
 139 >getpwent(3)</B
 140 > functions. </P
 141 ></DD
 142 ><DT
 143 >group</DT
 144 ><DD
 145 ><P
 146 >Group information traditionally stored in
 147                 the <TT
 148 CLASS="FILENAME"
 149 >group(5)</TT
 150 > file and used by
 151                 <B
 152 CLASS="COMMAND"
 153 >getgrent(3)</B
 154 > functions. </P
 155 ></DD
 156 ></DL
 157 ></DIV
 158 ><P
 159 >For example, the following simple configuration in the
 160         <TT
 161 CLASS="FILENAME"
 162 >/etc/nsswitch.conf</TT
 163 > file can be used to initially
 164         resolve user and group information from <TT
 165 CLASS="FILENAME"
 166 >/etc/passwd
 167         </TT
 168 > and <TT
 169 CLASS="FILENAME"
 170 >/etc/group</TT
 171 > and then from the
 172         Windows NT server. </P
 173 ><P
 174 ><PRE
 175 CLASS="PROGRAMLISTING"
 176 >passwd:         files winbind
 177 group:          files winbind
 178         </PRE
 179 ></P
 180 ><P
 181 >The following simple configuration in the
 182         <TT
 183 CLASS="FILENAME"
 184 >/etc/nsswitch.conf</TT
 185 > file can be used to initially
 186         resolve hostnames from <TT
 187 CLASS="FILENAME"
 188 >/etc/hosts</TT
 189 > and then from the
 190         WINS server.</P
 191 ></DIV
 192 ><DIV
 193 CLASS="REFSECT1"
 194 ><A
 195 NAME="AEN57"
 196 ></A
 197 ><H2
 198 >OPTIONS</H2
 199 ><P
 200 ></P
 201 ><DIV
 202 CLASS="VARIABLELIST"
 203 ><DL
 204 ><DT
 205 >-d debuglevel</DT
 206 ><DD
 207 ><P
 208 >Sets the debuglevel to an integer between
 209                 0 and 100. 0 is for no debugging and 100 is for reams and
 210                 reams. To submit a bug report to the Samba Team, use debug
 211                 level 100 (see BUGS.txt).   </P
 212 ></DD
 213 ><DT
 214 >-i</DT
 215 ><DD
 216 ><P
 217 >Tells <B
 218 CLASS="COMMAND"
 219 >winbindd</B
 220 > to not
 221                 become a daemon and detach from the current terminal. This
 222                 option is used by developers when interactive debugging
 223                 of <B
 224 CLASS="COMMAND"
 225 >winbindd</B
 226 > is required. </P
 227 ></DD
 228 ></DL
 229 ></DIV
 230 ></DIV
 231 ><DIV
 232 CLASS="REFSECT1"
 233 ><A
 234 NAME="AEN70"
 235 ></A
 236 ><H2
 237 >NAME AND ID RESOLUTION</H2
 238 ><P
 239 >Users and groups on a Windows NT server are assigned
 240         a relative id (rid) which is unique for the domain when the
 241         user or group is created.  To convert the Windows NT user or group
 242         into a unix user or group, a mapping between rids and unix user
 243         and group ids is required.  This is one of the jobs that <B
 244 CLASS="COMMAND"
 245 >       winbindd</B
 246 > performs. </P
 247 ><P
 248 >As winbindd users and groups are resolved from a server, user
 249         and group ids are allocated from a specified range.  This
 250         is done on a first come, first served basis, although all existing
 251         users and groups will be mapped as soon as a client performs a user
 252         or group enumeration command.  The allocated unix ids are stored
 253         in a database file under the Samba lock directory and will be
 254         remembered. </P
 255 ><P
 256 >WARNING: The rid to unix id database is the only location
 257         where the user and group mappings are stored by winbindd.  If this
 258         file is deleted or corrupted, there is no way for winbindd to
 259         determine which user and group ids correspond to Windows NT user
 260         and group rids. </P
 261 ></DIV
 262 ><DIV
 263 CLASS="REFSECT1"
 264 ><A
 265 NAME="AEN76"
 266 ></A
 267 ><H2
 268 >CONFIGURATION</H2
 269 ><P
 270 >Configuration of the <B
 271 CLASS="COMMAND"
 272 >winbindd</B
 273 > daemon
 274         is done through configuration parameters in the <TT
 275 CLASS="FILENAME"
 276 >smb.conf(5)
 277         </TT
 278 > file.  All parameters should be specified in the
 279         [global] section of smb.conf. </P
 280 ><P
 281 ></P
 282 ><UL
 283 ><LI
 284 ><P
 285 ><A
 286 HREF="smb.conf.5.html#WINBINDSEPARATOR"
 287 TARGET="_top"
 288 >               <TT
 289 CLASS="PARAMETER"
 290 ><I
 291 >winbind separator</I
 292 ></TT
 293 ></A
 294 ></P
 295 ></LI
 296 ><LI
 297 ><P
 298 ><A
 299 HREF="smb.conf.5.html#WINBINDUID"
 300 TARGET="_top"
 301 >               <TT
 302 CLASS="PARAMETER"
 303 ><I
 304 >winbind uid</I
 305 ></TT
 306 ></A
 307 ></P
 308 ></LI
 309 ><LI
 310 ><P
 311 ><A
 312 HREF="smb.conf.5.html#WINBINDGID"
 313 TARGET="_top"
 314 >               <TT
 315 CLASS="PARAMETER"
 316 ><I
 317 >winbind gid</I
 318 ></TT
 319 ></A
 320 ></P
 321 ></LI
 322 ><LI
 323 ><P
 324 ><A
 325 HREF="smb.conf.5.html#WINBINDCACHETIME"
 326 TARGET="_top"
 327 >               <TT
 328 CLASS="PARAMETER"
 329 ><I
 330 >winbind cache time</I
 331 ></TT
 332 ></A
 333 ></P
 334 ></LI
 335 ><LI
 336 ><P
 337 ><A
 338 HREF="smb.conf.5.html#WINBINDENUMUSERS"
 339 TARGET="_top"
 340 >               <TT
 341 CLASS="PARAMETER"
 342 ><I
 343 >winbind enum users</I
 344 ></TT
 345 ></A
 346 ></P
 347 ></LI
 348 ><LI
 349 ><P
 350 ><A
 351 HREF="smb.conf.5.html#WINBINDENUMGROUPS"
 352 TARGET="_top"
 353 >               <TT
 354 CLASS="PARAMETER"
 355 ><I
 356 >winbind enum groups</I
 357 ></TT
 358 ></A
 359 ></P
 360 ></LI
 361 ><LI
 362 ><P
 363 ><A
 364 HREF="smb.conf.5.html#TEMPLATEHOMEDIR"
 365 TARGET="_top"
 366 >               <TT
 367 CLASS="PARAMETER"
 368 ><I
 369 >template homedir</I
 370 ></TT
 371 ></A
 372 ></P
 373 ></LI
 374 ><LI
 375 ><P
 376 ><A
 377 HREF="smb.conf.5.html#TEMPLATESHELL"
 378 TARGET="_top"
 379 >               <TT
 380 CLASS="PARAMETER"
 381 ><I
 382 >template shell</I
 383 ></TT
 384 ></A
 385 ></P
 386 ></LI
 387 ><LI
 388 ><P
 389 ><A
 390 HREF="smb.conf.5.html#WINBINDUSEDEFAULTDOMAIN"
 391 TARGET="_top"
 392 >               <TT
 393 CLASS="PARAMETER"
 394 ><I
 395 >winbind use default domain</I
 396 ></TT
 397 ></A
 398 ></P
 399 ></LI
 400 ></UL
 401 ></DIV
 402 ><DIV
 403 CLASS="REFSECT1"
 404 ><A
 405 NAME="AEN118"
 406 ></A
 407 ><H2
 408 >EXAMPLE SETUP</H2
 409 ><P
 410 >To setup winbindd for user and group lookups plus
 411         authentication from a domain controller use something like the
 412         following setup. This was tested on a RedHat 6.2 Linux box. </P
 413 ><P
 414 >In <TT
 415 CLASS="FILENAME"
 416 >/etc/nsswitch.conf</TT
 417 > put the
 418         following:</P
 419 ><P
 420 ><PRE
 421 CLASS="PROGRAMLISTING"
 422 >passwd:     files winbind
 423 group:      files winbind
 424         </PRE
 425 ></P
 426 ><P
 427 >In <TT
 428 CLASS="FILENAME"
 429 >/etc/pam.d/*</TT
 430 > replace the
 431         <TT
 432 CLASS="PARAMETER"
 433 ><I
 434 >auth</I
 435 ></TT
 436 > lines with something like this: </P
 437 ><P
 438 ><PRE
 439 CLASS="PROGRAMLISTING"
 440 >auth       required    /lib/security/pam_securetty.so
 441 auth       required     /lib/security/pam_nologin.so
 442 auth       sufficient   /lib/security/pam_winbind.so
 443 auth       required     /lib/security/pam_pwdb.so use_first_pass shadow nullok
 444         </PRE
 445 ></P
 446 ><P
 447 >Note in particular the use of the <TT
 448 CLASS="PARAMETER"
 449 ><I
 450 >sufficient</I
 451 ></TT
 452 >
 453         keyword and the <TT
 454 CLASS="PARAMETER"
 455 ><I
 456 >use_first_pass</I
 457 ></TT
 458 > keyword. </P
 459 ><P
 460 >Now replace the account lines with this: </P
 461 ><P
 462 ><B
 463 CLASS="COMMAND"
 464 >account    required    /lib/security/pam_winbind.so
 465         </B
 466 ></P
 467 ><P
 468 >The next step is to join the domain. To do that use the
 469         <B
 470 CLASS="COMMAND"
 471 >smbpasswd</B
 472 > program like this:  </P
 473 ><P
 474 ><B
 475 CLASS="COMMAND"
 476 >smbpasswd -j DOMAIN -r PDC -U
 477         Administrator</B
 478 ></P
 479 ><P
 480 >The username after the <TT
 481 CLASS="PARAMETER"
 482 ><I
 483 >-U</I
 484 ></TT
 485 > can be any
 486         Domain user that has administrator privileges on the machine.
 487         Substitute your domain name for "DOMAIN" and the name of your PDC
 488         for "PDC".</P
 489 ><P
 490 >Next copy <TT
 491 CLASS="FILENAME"
 492 >libnss_winbind.so</TT
 493 > to
 494         <TT
 495 CLASS="FILENAME"
 496 >/lib</TT
 497 > and <TT
 498 CLASS="FILENAME"
 499 >pam_winbind.so</TT
 500 >
 501         to <TT
 502 CLASS="FILENAME"
 503 >/lib/security</TT
 504 >.  A symbolic link needs to be
 505         made from <TT
 506 CLASS="FILENAME"
 507 >/lib/libnss_winbind.so</TT
 508 > to
 509         <TT
 510 CLASS="FILENAME"
 511 >/lib/libnss_winbind.so.2</TT
 512 >.  If you are using an
 513         older version of glibc then the target of the link should be
 514         <TT
 515 CLASS="FILENAME"
 516 >/lib/libnss_winbind.so.1</TT
 517 >.</P
 518 ><P
 519 >Finally, setup a <TT
 520 CLASS="FILENAME"
 521 >smb.conf</TT
 522 > containing directives like the
 523         following:  </P
 524 ><P
 525 ><PRE
 526 CLASS="PROGRAMLISTING"
 527 >[global]
 528         winbind separator = +
 529         winbind cache time = 10
 530         template shell = /bin/bash
 531         template homedir = /home/%D/%U
 532         winbind uid = 10000-20000
 533         winbind gid = 10000-20000
 534         workgroup = DOMAIN
 535         security = domain
 536         password server = *
 537         </PRE
 538 ></P
 539 ><P
 540 >Now start winbindd and you should find that your user and
 541         group database is expanded to include your NT users and groups,
 542         and that you can login to your unix box as a domain user, using
 543         the DOMAIN+user syntax for the username. You may wish to use the
 544         commands <B
 545 CLASS="COMMAND"
 546 >getent passwd</B
 547 > and <B
 548 CLASS="COMMAND"
 549 >getent group
 550         </B
 551 > to confirm the correct operation of winbindd.</P
 552 ></DIV
 553 ><DIV
 554 CLASS="REFSECT1"
 555 ><A
 556 NAME="AEN157"
 557 ></A
 558 ><H2
 559 >NOTES</H2
 560 ><P
 561 >The following notes are useful when configuring and
 562         running <B
 563 CLASS="COMMAND"
 564 >winbindd</B
 565 >: </P
 566 ><P
 567 ><B
 568 CLASS="COMMAND"
 569 >nmbd</B
 570 > must be running on the local machine
 571         for <B
 572 CLASS="COMMAND"
 573 >winbindd</B
 574 > to work. <B
 575 CLASS="COMMAND"
 576 >winbindd</B
 577 >
 578         queries the list of trusted domains for the Windows NT server
 579         on startup and when a SIGHUP is received.  Thus, for a running <B
 580 CLASS="COMMAND"
 581 >       winbindd</B
 582 > to become aware of new trust relationships between
 583         servers, it must be sent a SIGHUP signal. </P
 584 ><P
 585 >Client processes resolving names through the <B
 586 CLASS="COMMAND"
 587 >winbindd</B
 588 >
 589         nsswitch module read an environment variable named <TT
 590 CLASS="ENVAR"
 591 >       $WINBINDD_DOMAIN</TT
 592 >.  If this variable contains a comma separated
 593         list of Windows NT domain names, then winbindd will only resolve users
 594         and groups within those Windows NT domains. </P
 595 ><P
 596 >PAM is really easy to misconfigure.  Make sure you know what
 597         you are doing when modifying PAM configuration files.  It is possible
 598         to set up PAM such that you can no longer log into your system. </P
 599 ><P
 600 >If more than one UNIX machine is running <B
 601 CLASS="COMMAND"
 602 >winbindd</B
 603 >,
 604         then in general the user and groups ids allocated by winbindd will not
 605         be the same.  The user and group ids will only be valid for the local
 606         machine.</P
 607 ><P
 608 >If the the Windows NT RID to UNIX user and group id mapping
 609         file is damaged or destroyed then the mappings will be lost. </P
 610 ></DIV
 611 ><DIV
 612 CLASS="REFSECT1"
 613 ><A
 614 NAME="AEN173"
 615 ></A
 616 ><H2
 617 >SIGNALS</H2
 618 ><P
 619 >The following signals can be used to manipulate the
 620         <B
 621 CLASS="COMMAND"
 622 >winbindd</B
 623 > daemon. </P
 624 ><P
 625 ></P
 626 ><DIV
 627 CLASS="VARIABLELIST"
 628 ><DL
 629 ><DT
 630 >SIGHUP</DT
 631 ><DD
 632 ><P
 633 >Reload the <TT
 634 CLASS="FILENAME"
 635 >smb.conf(5)</TT
 636 >
 637                 file and apply any parameter changes to the running
 638                 version of winbindd.  This signal also clears any cached
 639                 user and group information.  The list of other domains trusted
 640                 by winbindd is also reloaded.  </P
 641 ></DD
 642 ><DT
 643 >SIGUSR1</DT
 644 ><DD
 645 ><P
 646 >The SIGUSR1 signal will cause <B
 647 CLASS="COMMAND"
 648 >               winbindd</B
 649 > to write status information to the winbind
 650                 log file including information about the number of user and
 651                 group ids allocated by <B
 652 CLASS="COMMAND"
 653 >winbindd</B
 654 >.</P
 655 ><P
 656 >Log files are stored in the filename specified by the
 657                 log file parameter.</P
 658 ></DD
 659 ></DL
 660 ></DIV
 661 ></DIV
 662 ><DIV
 663 CLASS="REFSECT1"
 664 ><A
 665 NAME="AEN190"
 666 ></A
 667 ><H2
 668 >FILES</H2
 669 ><P
 670 ></P
 671 ><DIV
 672 CLASS="VARIABLELIST"
 673 ><DL
 674 ><DT
 675 ><TT
 676 CLASS="FILENAME"
 677 >/etc/nsswitch.conf(5)</TT
 678 ></DT
 679 ><DD
 680 ><P
 681 >Name service switch configuration file.</P
 682 ></DD
 683 ><DT
 684 >/tmp/.winbindd/pipe</DT
 685 ><DD
 686 ><P
 687 >The UNIX pipe over which clients communicate with
 688                 the <B
 689 CLASS="COMMAND"
 690 >winbindd</B
 691 > program.  For security reasons, the
 692                 winbind client will only attempt to connect to the winbindd daemon
 693                 if both the <TT
 694 CLASS="FILENAME"
 695 >/tmp/.winbindd</TT
 696 > directory
 697                 and <TT
 698 CLASS="FILENAME"
 699 >/tmp/.winbindd/pipe</TT
 700 > file are owned by
 701                 root. </P
 702 ></DD
 703 ><DT
 704 >/lib/libnss_winbind.so.X</DT
 705 ><DD
 706 ><P
 707 >Implementation of name service switch library.
 708                 </P
 709 ></DD
 710 ><DT
 711 >$LOCKDIR/winbindd_idmap.tdb</DT
 712 ><DD
 713 ><P
 714 >Storage for the Windows NT rid to UNIX user/group
 715                 id mapping.  The lock directory is specified when Samba is initially
 716                 compiled using the <TT
 717 CLASS="PARAMETER"
 718 ><I
 719 >--with-lockdir</I
 720 ></TT
 721 > option.
 722                 This directory is by default <TT
 723 CLASS="FILENAME"
 724 >/usr/local/samba/var/locks
 725                 </TT
 726 >. </P
 727 ></DD
 728 ><DT
 729 >$LOCKDIR/winbindd_cache.tdb</DT
 730 ><DD
 731 ><P
 732 >Storage for cached user and group information.
 733                 </P
 734 ></DD
 735 ></DL
 736 ></DIV
 737 ></DIV
 738 ><DIV
 739 CLASS="REFSECT1"
 740 ><A
 741 NAME="AEN219"
 742 ></A
 743 ><H2
 744 >VERSION</H2
 745 ><P
 746 >This man page is correct for version 2.2 of
 747         the Samba suite.</P
 748 ></DIV
 749 ><DIV
 750 CLASS="REFSECT1"
 751 ><A
 752 NAME="AEN222"
 753 ></A
 754 ><H2
 755 >SEE ALSO</H2
 756 ><P
 757 ><TT
 758 CLASS="FILENAME"
 759 >nsswitch.conf(5)</TT
 760 >,
 761         <A
 762 HREF="samba.7.html"
 763 TARGET="_top"
 764 >samba(7)</A
 765 >,
 766         <A
 767 HREF="wbinfo.1.html"
 768 TARGET="_top"
 769 >wbinfo(1)</A
 770 >,
 771         <A
 772 HREF="smb.conf.5.html"
 773 TARGET="_top"
 774 >smb.conf(5)</A
 775 ></P
 776 ></DIV
 777 ><DIV
 778 CLASS="REFSECT1"
 779 ><A
 780 NAME="AEN229"
 781 ></A
 782 ><H2
 783 >AUTHOR</H2
 784 ><P
 785 >The original Samba software and related utilities
 786         were created by Andrew Tridgell. Samba is now developed
 787         by the Samba Team as an Open Source project similar
 788         to the way the Linux kernel is developed.</P
 789 ><P
 790 ><B
 791 CLASS="COMMAND"
 792 >wbinfo</B
 793 > and <B
 794 CLASS="COMMAND"
 795 >winbindd</B
 796 >
 797         were written by Tim Potter.</P
 798 ><P
 799 >The conversion to DocBook for Samba 2.2 was done
 800         by Gerald Carter</P
 801 ></DIV
 802 ></BODY
 803 ></HTML
 804 >