diff options
Diffstat (limited to 'docs/docbook/manpages/smbpasswd.8.xml')
| -rw-r--r-- | docs/docbook/manpages/smbpasswd.8.xml | 409 |
1 files changed, 409 insertions, 0 deletions
diff --git a/docs/docbook/manpages/smbpasswd.8.xml b/docs/docbook/manpages/smbpasswd.8.xml new file mode 100644 index 0000000000..37f617e46a --- /dev/null +++ b/docs/docbook/manpages/smbpasswd.8.xml @@ -0,0 +1,409 @@ +<?xml version="1.0" encoding="iso8859-1"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ + +<!ENTITY % globalentities SYSTEM './../global.ent'> %globalentities; +]> +<refentry id="smbpasswd.8"> + +<refmeta> + <refentrytitle>smbpasswd</refentrytitle> + <manvolnum>8</manvolnum> +</refmeta> + + +<refnamediv> + <refname>smbpasswd</refname> + <refpurpose>change a user's SMB password</refpurpose> +</refnamediv> + +<refsynopsisdiv> + <cmdsynopsis> + <command>smbpasswd</command> + <arg choice="opt">-a</arg> + <arg choice="opt">-x</arg> + <arg choice="opt">-d</arg> + <arg choice="opt">-e</arg> + <arg choice="opt">-D debuglevel</arg> + <arg choice="opt">-n</arg> + <arg choice="opt">-r <remote machine></arg> + <arg choice="opt">-R <name resolve order></arg> + <arg choice="opt">-m</arg> + <arg choice="opt">-U username[%password]</arg> + <arg choice="opt">-h</arg> + <arg choice="opt">-s</arg> + <arg choice="opt">-w pass</arg> + <arg choice="opt">-i</arg> + <arg choice="opt">-L</arg> + <arg choice="opt">username</arg> + </cmdsynopsis> +</refsynopsisdiv> + +<refsect1> + <title>DESCRIPTION</title> + + <para>This tool is part of the <citerefentry><refentrytitle>Samba</refentrytitle> + <manvolnum>7</manvolnum></citerefentry> suite.</para> + + <para>The smbpasswd program has several different + functions, depending on whether it is run by the <emphasis>root</emphasis> user + or not. When run as a normal user it allows the user to change + the password used for their SMB sessions on any machines that store + SMB passwords. </para> + + <para>By default (when run with no arguments) it will attempt to + change the current user's SMB password on the local machine. This is + similar to the way the <command>passwd(1)</command> program works. <command> + smbpasswd</command> differs from how the passwd program works + however in that it is not <emphasis>setuid root</emphasis> but works in + a client-server mode and communicates with a + locally running <citerefentry><refentrytitle>smbd</refentrytitle> + <manvolnum>8</manvolnum></citerefentry>. As a consequence in order for this to + succeed the smbd daemon must be running on the local machine. On a + UNIX machine the encrypted SMB passwords are usually stored in + the <citerefentry><refentrytitle>smbpasswd</refentrytitle> + <manvolnum>5</manvolnum></citerefentry> file. </para> + + <para>When run by an ordinary user with no options, smbpasswd + will prompt them for their old SMB password and then ask them + for their new password twice, to ensure that the new password + was typed correctly. No passwords will be echoed on the screen + whilst being typed. If you have a blank SMB password (specified by + the string "NO PASSWORD" in the smbpasswd file) then just press + the <Enter> key when asked for your old password. </para> + + <para>smbpasswd can also be used by a normal user to change their + SMB password on remote machines, such as Windows NT Primary Domain + Controllers. See the (<parameter>-r</parameter>) and <parameter>-U</parameter> options + below. </para> + + <para>When run by root, smbpasswd allows new users to be added + and deleted in the smbpasswd file, as well as allows changes to + the attributes of the user in this file to be made. When run by root, <command> + smbpasswd</command> accesses the local smbpasswd file + directly, thus enabling changes to be made even if smbd is not + running. </para> +</refsect1> + +<refsect1> + <title>OPTIONS</title> + <variablelist> + <varlistentry> + <term>-a</term> + <listitem><para>This option specifies that the username + following should be added to the local smbpasswd file, with the + new password typed (type <Enter> for the old password). This + option is ignored if the username following already exists in + the smbpasswd file and it is treated like a regular change + password command. Note that the default passdb backends require + the user to already exist in the system password file (usually + <filename>/etc/passwd</filename>), else the request to add the + user will fail. </para> + + <para>This option is only available when running smbpasswd + as root. </para></listitem> + </varlistentry> + + + + <varlistentry> + <term>-x</term> + <listitem><para>This option specifies that the username + following should be deleted from the local smbpasswd file. + </para> + + <para>This option is only available when running smbpasswd as + root.</para></listitem> + </varlistentry> + + + + <varlistentry> + <term>-d</term> + <listitem><para>This option specifies that the username following + should be <constant>disabled</constant> in the local smbpasswd + file. This is done by writing a <constant>'D'</constant> flag + into the account control space in the smbpasswd file. Once this + is done all attempts to authenticate via SMB using this username + will fail. </para> + + <para>If the smbpasswd file is in the 'old' format (pre-Samba 2.0 + format) there is no space in the user's password entry to write + this information and the command will FAIL. See <citerefentry><refentrytitle>smbpasswd</refentrytitle> + <manvolnum>5</manvolnum></citerefentry> for details on the 'old' and new password file formats. + </para> + + <para>This option is only available when running smbpasswd as + root.</para></listitem> + </varlistentry> + + + <varlistentry> + <term>-e</term> + <listitem><para>This option specifies that the username following + should be <constant>enabled</constant> in the local smbpasswd file, + if the account was previously disabled. If the account was not + disabled this option has no effect. Once the account is enabled then + the user will be able to authenticate via SMB once again. </para> + + <para>If the smbpasswd file is in the 'old' format, then <command> + smbpasswd</command> will FAIL to enable the account. + See <citerefentry><refentrytitle>smbpasswd</refentrytitle> + <manvolnum>5</manvolnum></citerefentry> for + details on the 'old' and new password file formats. </para> + + <para>This option is only available when running smbpasswd as root. + </para></listitem> + </varlistentry> + + + + <varlistentry> + <term>-D debuglevel</term> + <listitem><para><replaceable>debuglevel</replaceable> is an integer + from 0 to 10. The default value if this parameter is not specified + is zero. </para> + + <para>The higher this value, the more detail will be logged to the + log files about the activities of smbpasswd. At level 0, only + critical errors and serious warnings will be logged. </para> + + <para>Levels above 1 will generate considerable amounts of log + data, and should only be used when investigating a problem. Levels + above 3 are designed for use only by developers and generate + HUGE amounts of log data, most of which is extremely cryptic. + </para></listitem> + </varlistentry> + + + + <varlistentry> + <term>-n</term> + <listitem><para>This option specifies that the username following + should have their password set to null (i.e. a blank password) in + the local smbpasswd file. This is done by writing the string "NO + PASSWORD" as the first part of the first password stored in the + smbpasswd file. </para> + + <para>Note that to allow users to logon to a Samba server once + the password has been set to "NO PASSWORD" in the smbpasswd + file the administrator must set the following parameter in the [global] + section of the <filename>smb.conf</filename> file : </para> + + <para><command>null passwords = yes</command></para> + + <para>This option is only available when running smbpasswd as + root.</para></listitem> + </varlistentry> + + + + <varlistentry> + <term>-r remote machine name</term> + <listitem><para>This option allows a user to specify what machine + they wish to change their password on. Without this parameter + smbpasswd defaults to the local host. The <replaceable>remote + machine name</replaceable> is the NetBIOS name of the SMB/CIFS + server to contact to attempt the password change. This name is + resolved into an IP address using the standard name resolution + mechanism in all programs of the Samba suite. See the <parameter>-R + name resolve order</parameter> parameter for details on changing + this resolving mechanism. </para> + + <para>The username whose password is changed is that of the + current UNIX logged on user. See the <parameter>-U username</parameter> + parameter for details on changing the password for a different + username. </para> + + <para>Note that if changing a Windows NT Domain password the + remote machine specified must be the Primary Domain Controller for + the domain (Backup Domain Controllers only have a read-only + copy of the user account database and will not allow the password + change).</para> + + <para><emphasis>Note</emphasis> that Windows 95/98 do not have + a real password database so it is not possible to change passwords + specifying a Win95/98 machine as remote machine target. </para> + </listitem> + </varlistentry> + + + <varlistentry> + <term>-R name resolve order</term> + <listitem><para>This option allows the user of smbpasswd to determine + what name resolution services to use when looking up the NetBIOS + name of the host being connected to. </para> + + <para>The options are :"lmhosts", "host", "wins" and "bcast". They + cause names to be resolved as follows: </para> + <itemizedlist> + <listitem><para><constant>lmhosts</constant>: Lookup an IP + address in the Samba lmhosts file. If the line in lmhosts has + no name type attached to the NetBIOS name (see the <citerefentry><refentrytitle>lmhosts</refentrytitle> + <manvolnum>5</manvolnum></citerefentry> for details) then + any name type matches for lookup.</para></listitem> + + <listitem><para><constant>host</constant>: Do a standard host + name to IP address resolution, using the system <filename>/etc/hosts + </filename>, NIS, or DNS lookups. This method of name resolution + is operating system depended for instance on IRIX or Solaris this + may be controlled by the <filename>/etc/nsswitch.conf</filename> + file). Note that this method is only used if the NetBIOS name + type being queried is the 0x20 (server) name type, otherwise + it is ignored.</para></listitem> + + <listitem><para><constant>wins</constant>: Query a name with + the IP address listed in the <parameter>wins server</parameter> + parameter. If no WINS server has been specified this method + will be ignored.</para></listitem> + + <listitem><para><constant>bcast</constant>: Do a broadcast on + each of the known local interfaces listed in the + <parameter>interfaces</parameter> parameter. This is the least + reliable of the name resolution methods as it depends on the + target host being on a locally connected subnet.</para></listitem> + </itemizedlist> + + <para>The default order is <command>lmhosts, host, wins, bcast</command> + and without this parameter or any entry in the <citerefentry><refentrytitle>smb.conf</refentrytitle> + <manvolnum>5</manvolnum></citerefentry> file the name resolution methods will + be attempted in this order. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>-m</term> + <listitem><para>This option tells smbpasswd that the account + being changed is a MACHINE account. Currently this is used + when Samba is being used as an NT Primary Domain Controller.</para> + + <para>This option is only available when running smbpasswd as root. + </para></listitem> + </varlistentry> + + + <varlistentry> + <term>-U username</term> + <listitem><para>This option may only be used in conjunction + with the <parameter>-r</parameter> option. When changing + a password on a remote machine it allows the user to specify + the user name on that machine whose password will be changed. It + is present to allow users who have different user names on + different systems to change these passwords. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>-h</term> + <listitem><para>This option prints the help string for <command> + smbpasswd</command>, selecting the correct one for running as root + or as an ordinary user. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>-s</term> + <listitem><para>This option causes smbpasswd to be silent (i.e. + not issue prompts) and to read its old and new passwords from + standard input, rather than from <filename>/dev/tty</filename> + (like the <command>passwd(1)</command> program does). This option + is to aid people writing scripts to drive smbpasswd</para> + </listitem> + </varlistentry> + + + <varlistentry> + <term>-w password</term> + <listitem><para>This parameter is only available if Samba + has been configured to use the experimental + <command>--with-ldapsam</command> option. The <parameter>-w</parameter> + switch is used to specify the password to be used with the + <ulink url="smb.conf.5.html#LDAPADMINDN"><parameter>ldap admin + dn</parameter></ulink>. Note that the password is stored in + the <filename>secrets.tdb</filename> and is keyed off + of the admin's DN. This means that if the value of <parameter>ldap + admin dn</parameter> ever changes, the password will need to be + manually updated as well. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-i</term> + <listitem><para>This option tells smbpasswd that the account + being changed is an interdomain trust account. Currently this is used + when Samba is being used as an NT Primary Domain Controller. + The account contains the info about another trusted domain.</para> + + <para>This option is only available when running smbpasswd as root. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>-L</term> + <listitem><para>Run in local mode.</para></listitem> + </varlistentry> + + <varlistentry> + <term>username</term> + <listitem><para>This specifies the username for all of the + <emphasis>root only</emphasis> options to operate on. Only root + can specify this parameter as only root has the permission needed + to modify attributes directly in the local smbpasswd file. + </para></listitem> + </varlistentry> + </variablelist> +</refsect1> + + +<refsect1> + <title>NOTES</title> + + <para>Since <command>smbpasswd</command> works in client-server + mode communicating with a local smbd for a non-root user then + the smbd daemon must be running for this to work. A common problem + is to add a restriction to the hosts that may access the <command> + smbd</command> running on the local machine by specifying either <parameter>allow + hosts</parameter> or <parameter>deny hosts</parameter> entry in + the <citerefentry><refentrytitle>smb.conf</refentrytitle> + <manvolnum>5</manvolnum></citerefentry> file and neglecting to + allow "localhost" access to the smbd. </para> + + <para>In addition, the smbpasswd command is only useful if Samba + has been set up to use encrypted passwords. See the document <ulink url="pwencrypt.html"> + "LanMan and NT Password Encryption in Samba"</ulink> in the docs directory for details + on how to do this. </para> +</refsect1> + + +<refsect1> + <title>VERSION</title> + + <para>This man page is correct for version 3.0 of the Samba suite.</para> +</refsect1> + +<refsect1> + <title>SEE ALSO</title> + <para><citerefentry><refentrytitle>smbpasswd</refentrytitle> + <manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>Samba</refentrytitle> + <manvolnum>7</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>The original Samba man pages were written by Karl Auer. + The man page sources were converted to YODL format (another + excellent piece of Open Source software, available at <ulink url="ftp://ftp.icce.rug.nl/pub/unix/"> + ftp://ftp.icce.rug.nl/pub/unix/</ulink>) and updated for the Samba 2.0 + release by Jeremy Allison. 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> |