diff options
Diffstat (limited to 'docs-xml/manpages/winbindd.8.xml')
| -rw-r--r-- | docs-xml/manpages/winbindd.8.xml | 531 |
1 files changed, 531 insertions, 0 deletions
diff --git a/docs-xml/manpages/winbindd.8.xml b/docs-xml/manpages/winbindd.8.xml new file mode 100644 index 0000000..e60bd65 --- /dev/null +++ b/docs-xml/manpages/winbindd.8.xml @@ -0,0 +1,531 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc"> +<refentry id="winbindd.8"> + +<refmeta> + <refentrytitle>winbindd</refentrytitle> + <manvolnum>8</manvolnum> + <refmiscinfo class="source">Samba</refmiscinfo> + <refmiscinfo class="manual">System Administration tools</refmiscinfo> + <refmiscinfo class="version">&doc.version;</refmiscinfo> +</refmeta> + + +<refnamediv> + <refname>winbindd</refname> + <refpurpose>Name Service Switch daemon for resolving names + from NT servers</refpurpose> +</refnamediv> + +<refsynopsisdiv> + <cmdsynopsis> + <command>winbindd</command> + <arg choice="opt">-D|--daemon</arg> + <arg choice="opt">-i|--interactive</arg> + <arg choice="opt">-F|--foreground</arg> + <arg choice="opt">--no-process-group</arg> + <arg choice="opt">-n|--no-caching</arg> + <arg choice="opt">-d <debug level></arg> + <arg choice="opt">--debug-stdout</arg> + <arg choice="opt">--configfile=<configuration file></arg> + <arg choice="opt">--option=<name>=<value></arg> + <arg choice="opt">-l|--log-basename <log directory></arg> + <arg choice="opt">--leak-report</arg> + <arg choice="opt">--leak-report-full</arg> + <arg choice="opt">-V|--version</arg> + </cmdsynopsis> +</refsynopsisdiv> + +<refsect1> + <title>DESCRIPTION</title> + + <para>This program is part of the <citerefentry><refentrytitle>samba</refentrytitle> + <manvolnum>7</manvolnum></citerefentry> suite.</para> + + <para><command>winbindd</command> is a daemon that provides + a number of services to the Name Service Switch capability found + in most modern C libraries, to arbitrary applications via PAM + and <command>ntlm_auth</command> and to Samba itself.</para> + + <para>Even if winbind is not used for nsswitch, it still provides a + service to <command>smbd</command>, <command>ntlm_auth</command> + and the <command>pam_winbind.so</command> PAM module, by managing connections to + domain controllers. In this configuration the + <smbconfoption name="idmap config * : range"/> + parameter is not required. (This is known as `netlogon proxy only mode'.)</para> + + <para> The Name Service Switch allows user + and system information to be obtained from different databases + services such as NIS or DNS. The exact behaviour can be configured + through the <filename>/etc/nsswitch.conf</filename> file. + Users and groups are allocated as they are resolved to a range + of user and group ids specified by the administrator of the + Samba system.</para> + + <para>The service provided by <command>winbindd</command> is called `winbind' and + can be used to resolve user and group information from a + Windows NT server. The service can also provide authentication + services via an associated PAM module. </para> + + <para> + The <filename>pam_winbind</filename> module supports the + <parameter>auth</parameter>, <parameter>account</parameter> + and <parameter>password</parameter> + module-types. It should be noted that the + <parameter>account</parameter> module simply performs a getpwnam() to verify that + the system can obtain a uid for the user, as the domain + controller has already performed access control. If the + <filename>libnss_winbind</filename> library has been correctly + installed, or an alternate source of names configured, this should always succeed. + </para> + + <para>The following nsswitch databases are implemented by + the winbindd service: </para> + + <variablelist> + <varlistentry> + <term>hosts</term> + <listitem><para>This feature is only available on IRIX. + User information traditionally stored in + the <filename>hosts(5)</filename> file and used by + <command>gethostbyname(3)</command> functions. Names are + resolved through the WINS server or by broadcast. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>passwd</term> + <listitem><para>User information traditionally stored in + the <filename>passwd(5)</filename> file and used by + <command>getpwent(3)</command> functions. </para></listitem> + </varlistentry> + + <varlistentry> + <term>group</term> + <listitem><para>Group information traditionally stored in + the <filename>group(5)</filename> file and used by + <command>getgrent(3)</command> functions. </para></listitem> + </varlistentry> + </variablelist> + + <para>For example, the following simple configuration in the + <filename>/etc/nsswitch.conf</filename> file can be used to initially + resolve user and group information from <filename>/etc/passwd + </filename> and <filename>/etc/group</filename> and then from the + Windows NT server. + </para> + +<programlisting> +passwd: files winbind +group: files winbind +## only available on IRIX: use winbind to resolve hosts: +# hosts: files dns winbind +## All other NSS enabled systems should use libnss_wins.so like this: +hosts: files dns wins + +</programlisting> + + <para>The following simple configuration in the + <filename>/etc/nsswitch.conf</filename> file can be used to initially + resolve hostnames from <filename>/etc/hosts</filename> and then from the + WINS server.</para> +<programlisting> +hosts: files wins +</programlisting> + +</refsect1> + + +<refsect1> + <title>OPTIONS</title> + + <variablelist> + <varlistentry> + <term>-D|--daemon</term> + <listitem><para>If specified, this parameter causes + the server to operate as a daemon. That is, it detaches + itself and runs in the background on the appropriate port. + This switch is assumed if <command>winbindd</command> is + executed on the command line of a shell. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-i|--interactive</term> + <listitem><para>Tells <command>winbindd</command> to not + become a daemon and detach from the current terminal. This + option is used by developers when interactive debugging + of <command>winbindd</command> is required. + <command>winbindd</command> also logs to standard output, + as if the <command>-S</command> parameter had been given. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-F|--foreground</term> + <listitem><para>If specified, this parameter causes + the main <command>winbindd</command> process to not daemonize, + i.e. double-fork and disassociate with the terminal. + Child processes are still created as normal to service + each connection request, but the main process does not + exit. This operation mode is suitable for running + <command>winbindd</command> under process supervisors such + as <command>supervise</command> and <command>svscan</command> + from Daniel J. Bernstein's <command>daemontools</command> + package, or the AIX process monitor. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>--no-process-group</term> + <listitem><para>Do not create a new process group for winbindd. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-n|--no-caching</term> + <listitem><para>Disable some caching. This means winbindd will + often have to wait for a response from the domain controller + before it can respond to a client and this thus makes things + slower. The results will however be more accurate, since + results from the cache might not be up-to-date. This + might also temporarily hang winbindd if the DC doesn't respond. + This does not disable the samlogon cache, which is required for + group membership tracking in trusted environments. + </para></listitem> + </varlistentry> + + &cmdline.common.debug.server; + &cmdline.common.config.server; + &cmdline.common.option; + + <varlistentry> + <term>-l|--log-basename=logdirectory</term> + <listitem> + <para> + Base directory name for log/debug files. The parent process + uses filename log.winbindd, the child process uses filename + log.wb-<name>. The log file is never removed by winbindd. + </para> + </listitem> + </varlistentry> + + &cmdline.common.samba.leakreport; + &cmdline.common.samba.leakreportfull; + &cmdline.version; + + &popt.autohelp; + + </variablelist> +</refsect1> + + +<refsect1> + <title>NAME AND ID RESOLUTION</title> + + <para>Users and groups on a Windows NT server are assigned + a security id (SID) which is globally unique when the + user or group is created. To convert the Windows NT user or group + into a unix user or group, a mapping between SIDs and unix user + and group ids is required. This is one of the jobs that <command> + winbindd</command> performs. </para> + + <para>As winbindd users and groups are resolved from a server, user + and group ids are allocated from a specified range. This + is done on a first come, first served basis, although all existing + users and groups will be mapped as soon as a client performs a user + or group enumeration command. The allocated unix ids are stored + in a database and will be remembered. </para> + + <para>WARNING: The SID to unix id database is the only location + where the user and group mappings are stored by winbindd. If this + store is deleted or corrupted, there is no way for winbindd to + determine which user and group ids correspond to Windows NT user + and group rids. </para> + +</refsect1> + + +<refsect1> + <title>CONFIGURATION</title> + + <para>Configuration of the <command>winbindd</command> daemon + is done through configuration parameters in the <citerefentry> + <refentrytitle>smb.conf</refentrytitle><manvolnum>5</manvolnum> + </citerefentry> file. All parameters should be specified in the + [global] section of smb.conf. </para> + + <itemizedlist> + <listitem><para> + <smbconfoption name="winbind separator"/></para></listitem> + <listitem><para> + <smbconfoption name="idmap config * : range"/></para></listitem> + <listitem><para> + <smbconfoption name="idmap config * : backend"/></para></listitem> + <listitem><para> + <smbconfoption name="winbind cache time"/></para></listitem> + <listitem><para> + <smbconfoption name="winbind enum users"/></para></listitem> + <listitem><para> + <smbconfoption name="winbind enum groups"/></para></listitem> + <listitem><para> + <smbconfoption name="template homedir"/></para></listitem> + <listitem><para> + <smbconfoption name="template shell"/></para></listitem> + <listitem><para> + <smbconfoption name="winbind use default domain"/></para></listitem> + <listitem><para> + <smbconfoption name="winbind: rpc only"/> + Setting this parameter forces winbindd to use RPC + instead of LDAP to retrieve information from Domain + Controllers. + </para></listitem> + </itemizedlist> +</refsect1> + + +<refsect1> + <title>EXAMPLE SETUP</title> + + <para> + To setup winbindd for user and group lookups plus + authentication from a domain controller use something like the + following setup. This was tested on an early Red Hat Linux box. + </para> + + <para>In <filename>/etc/nsswitch.conf</filename> put the + following: +<programlisting> +passwd: files winbind +group: files winbind +</programlisting> + </para> + + <para>In <filename>/etc/pam.d/*</filename> replace the <parameter> + auth</parameter> lines with something like this: +<programlisting> +auth required /lib/security/pam_securetty.so +auth required /lib/security/pam_nologin.so +auth sufficient /lib/security/pam_winbind.so +auth required /lib/security/pam_unix.so \ + use_first_pass shadow nullok +</programlisting> + </para> + + <note><para> + The PAM module pam_unix has recently replaced the module pam_pwdb. + Some Linux systems use the module pam_unix2 in place of pam_unix. + </para></note> + + <para>Note in particular the use of the <parameter>sufficient + </parameter> keyword and the <parameter>use_first_pass</parameter> keyword. </para> + + <para>Now replace the account lines with this: </para> + + <para><command>account required /lib/security/pam_winbind.so + </command></para> + + <para>The next step is to join the domain. To do that use the + <command>net</command> program like this: </para> + + <para><command>net join -S PDC -U Administrator</command></para> + + <para>The username after the <parameter>-U</parameter> can be any + Domain user that has administrator privileges on the machine. + Substitute the name or IP of your PDC for "PDC".</para> + + <para>Next copy <filename>libnss_winbind.so</filename> to + <filename>/lib</filename> and <filename>pam_winbind.so + </filename> to <filename>/lib/security</filename>. A symbolic link needs to be + made from <filename>/lib/libnss_winbind.so</filename> to + <filename>/lib/libnss_winbind.so.2</filename>. If you are using an + older version of glibc then the target of the link should be + <filename>/lib/libnss_winbind.so.1</filename>.</para> + + <para>Finally, setup a <citerefentry><refentrytitle>smb.conf</refentrytitle> + <manvolnum>5</manvolnum></citerefentry> containing directives like the + following: +<programlisting> +[global] + winbind separator = + + winbind cache time = 10 + template shell = /bin/bash + template homedir = /home/%D/%U + idmap config * : range = 10000-20000 + workgroup = DOMAIN + security = domain + password server = * +</programlisting></para> + + + <para>Now start winbindd and you should find that your user and + group database is expanded to include your NT users and groups, + and that you can login to your unix box as a domain user, using + the DOMAIN+user syntax for the username. You may wish to use the + commands <command>getent passwd</command> and <command>getent group + </command> to confirm the correct operation of winbindd.</para> +</refsect1> + + +<refsect1> + <title>NOTES</title> + + <para>The following notes are useful when configuring and + running <command>winbindd</command>: </para> + + <para>PAM is really easy to misconfigure. Make sure you know what + you are doing when modifying PAM configuration files. It is possible + to set up PAM such that you can no longer log into your system. </para> + + <para>If more than one UNIX machine is running <command>winbindd</command>, + then in general the user and groups ids allocated by winbindd will not + be the same. The user and group ids will only be valid for the local + machine, unless a shared <smbconfoption name="idmap config * : backend"/> is configured.</para> + + <para>If the Windows NT SID to UNIX user and group id mapping + file is damaged or destroyed then the mappings will be lost. </para> +</refsect1> + + +<refsect1> + <title>SIGNALS</title> + + <para>The following signals can be used to manipulate the + <command>winbindd</command> daemon. </para> + + <variablelist> + <varlistentry> + <term>SIGHUP</term> + <listitem><para>Reload the <citerefentry><refentrytitle>smb.conf</refentrytitle> + <manvolnum>5</manvolnum></citerefentry> file and + apply any parameter changes to the running + version of winbindd. This signal also clears any cached + user and group information. The list of other domains trusted + by winbindd is also reloaded. + </para> + <para>Instead of sending a SIGHUP signal, a request to reload configuration + file may be sent using <citerefentry><refentrytitle>smbcontrol</refentrytitle> + <manvolnum>1</manvolnum></citerefentry> program. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>SIGUSR2</term> + <listitem><para>The SIGUSR2 signal will cause <command> + winbindd</command> to write status information to the winbind + log file.</para> + + <para>Log files are stored in the filename specified by the + log file parameter.</para></listitem> + </varlistentry> + </variablelist> +</refsect1> + +<refsect1> + <title>FILES</title> + + <variablelist> + <varlistentry> + <term><filename>/etc/nsswitch.conf(5)</filename></term> + <listitem><para>Name service switch configuration file.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&pathconfig.WINBINDD_SOCKET_DIR;/pipe</term> + <listitem><para>The UNIX pipe over which clients communicate with + the <command>winbindd</command> program. For security reasons, the + winbind client will only attempt to connect to the winbindd daemon + if both the <filename>&pathconfig.WINBINDD_SOCKET_DIR;</filename> directory + and <filename>&pathconfig.WINBINDD_SOCKET_DIR;/pipe</filename> file are owned by + root. </para> + + <para><smbconfoption name="winbindd socket directory"/> + overrides this default.</para> + + </listitem> + </varlistentry> + + <varlistentry> + <term>$STATEDIR/winbindd_privileged/pipe</term> + <listitem><para>The UNIX pipe over which 'privileged' clients + communicate with the <command>winbindd</command> program. For security + reasons, access to some winbindd functions - like those needed by + the <command>ntlm_auth</command> utility - is restricted. By default, + only users in the 'root' group will get this access, however the administrator + may change the group permissions on $STATEDIR/winbindd_privileged to allow + programs like 'squid' to use ntlm_auth. + Note that the winbind client will only attempt to connect to the winbindd daemon + if both the <filename>$STATEDIR/winbindd_privileged</filename> directory + and <filename>$STATEDIR/winbindd_privileged/pipe</filename> file are owned by + root. </para> + <para><smbconfoption name="state dir"/> controls what + $STATEDIR refers to.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>/lib/libnss_winbind.so.X</term> + <listitem><para>Implementation of name service switch library. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>$STATEDIR/winbindd_idmap.tdb</term> + <listitem><para>Storage for the Windows NT rid to UNIX user/group + id mapping. The directory is specified when Samba is initially + compiled using the + <parameter>--with-statedir</parameter> option or <smbconfoption name="state dir"/>. + The default directory in this installation is <filename>&pathconfig.STATEDIR; + </filename>. </para></listitem> + </varlistentry> + + <varlistentry> + <term>$LOCKDIR/winbindd_cache.tdb</term> + <listitem><para>Storage for cached user and group information. + </para></listitem> + </varlistentry> + </variablelist> +</refsect1> + + +<refsect1> + <title>VERSION</title> + + <para>This man page is part of version &doc.version; of + the Samba suite.</para> +</refsect1> + +<refsect1> + <title>SEE ALSO</title> + + <para><filename>nsswitch.conf(5)</filename>, <citerefentry> + <refentrytitle>samba</refentrytitle> + <manvolnum>7</manvolnum></citerefentry>, <citerefentry> + <refentrytitle>wbinfo</refentrytitle> + <manvolnum>1</manvolnum></citerefentry>, <citerefentry> + <refentrytitle>ntlm_auth</refentrytitle> + <manvolnum>8</manvolnum></citerefentry>, <citerefentry> + <refentrytitle>smb.conf</refentrytitle> + <manvolnum>5</manvolnum></citerefentry>, <citerefentry> + <refentrytitle>pam_winbind</refentrytitle> + <manvolnum>8</manvolnum></citerefentry></para> +</refsect1> + +<refsect1> + <title>AUTHOR</title> + + <para>The original Samba software and related utilities + were created by Andrew Tridgell. Samba is now developed + by the Samba Team as an Open Source project similar + to the way the Linux kernel is developed.</para> + + <para><command>wbinfo</command> and <command>winbindd</command> were + written by Tim Potter.</para> + + <para>The conversion to DocBook for Samba 2.2 was done + by Gerald Carter. The conversion to DocBook XML 4.2 for + Samba 3.0 was done by Alexander Bokovoy.</para> +</refsect1> + +</refentry> |