docs/docbook/manpages/smbpasswd.8.sgml

   1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
   2 <refentry id="smbpasswd">
   3
   4 <refmeta>
   5         <refentrytitle>smbpasswd</refentrytitle>
   6         <manvolnum>8</manvolnum>
   7 </refmeta>
   8
   9
  10 <refnamediv>
  11         <refname>smbpasswd</refname>
  12         <refpurpose>change a user's SMB password</refpurpose>
  13 </refnamediv>
  14
  15 <refsynopsisdiv>
  16         <cmdsynopsis>
  17                 <command>smbpasswd</command>
  18                 <arg choice="opt">-a</arg>
  19                 <arg choice="opt">-x</arg>
  20                 <arg choice="opt">-d</arg>
  21                 <arg choice="opt">-e</arg>
  22                 <arg choice="opt">-D debuglevel</arg>
  23                 <arg choice="opt">-n</arg>
  24                 <arg choice="opt">-r &lt;remote machine&gt;</arg>
  25                 <arg choice="opt">-R &lt;name resolve order&gt;</arg>
  26                 <arg choice="opt">-m</arg>
  27                 <arg choice="opt">-j DOMAIN</arg>
  28                 <arg choice="opt">-U username[%password]</arg>
  29                 <arg choice="opt">-h</arg>
  30                 <arg choice="opt">-s</arg>
  31                 <arg choice="opt">-w pass</arg>
  32                 <arg choice="opt">username</arg>
  33         </cmdsynopsis>
  34 </refsynopsisdiv>
  35
  36 <refsect1>
  37         <title>DESCRIPTION</title>
  38
  39         <para>This tool is part of the <ulink url="samba.7.html">
  40         Samba</ulink> suite.</para>
  41
  42         <para>The smbpasswd program has several different
  43         functions, depending on whether it is run by the <emphasis>root</emphasis>
  44         user or not. When run as a normal user it allows the user to change
  45         the password used for their SMB sessions on any machines that store
  46         SMB passwords. </para>
  47
  48         <para>By default (when run with no arguments) it will attempt to
  49         change the current user's SMB password on the local machine. This is
  50         similar to the way the <command>passwd(1)</command> program works.
  51         <command>smbpasswd</command> differs from how the passwd program works
  52         however in that it is not <emphasis>setuid root</emphasis> but works in
  53         a client-server mode and communicates with a locally running
  54         <command>smbd(8)</command>. As a consequence in order for this to
  55         succeed the smbd daemon must be running on the local machine. On a
  56         UNIX machine the encrypted SMB passwords are usually stored in
  57         the <filename>smbpasswd(5)</filename> file. </para>
  58
  59         <para>When run by an ordinary user with no options. smbpasswd
  60         will prompt them for their old SMB password and then ask them
  61         for their new password twice, to ensure that the new password
  62         was typed correctly. No passwords will be echoed on the screen
  63         whilst being typed. If you have a blank SMB password (specified by
  64         the string "NO PASSWORD" in the smbpasswd file) then just press
  65         the &lt;Enter&gt; key when asked for your old password. </para>
  66
  67         <para>smbpasswd can also be used by a normal user to change their
  68         SMB password on remote machines, such as Windows NT Primary Domain
  69         Controllers.   See the (-r) and -U options below. </para>
  70
  71         <para>When run by root, smbpasswd allows new users to be added
  72         and deleted in the smbpasswd file, as well as allows changes to
  73         the attributes of the user in this file to be made. When run by root,
  74         <command>smbpasswd</command> accesses the local smbpasswd file
  75         directly, thus enabling changes to be made even if smbd is not
  76         running. </para>
  77 </refsect1>
  78
  79 <refsect1>
  80         <title>OPTIONS</title>
  81         <variablelist>
  82                 <varlistentry>
  83                 <term>-a</term>
  84                 <listitem><para>This option specifies that the username
  85                 following should be added to the local smbpasswd file, with the
  86                 new password typed (type &lt;Enter&gt; for the old password). This
  87                 option is ignored if the username following already exists in
  88                 the smbpasswd file and it is treated like a regular change
  89                 password command.  Note that the default passdb backends require
  90                 the user to already exist in the system password file (usually
  91                 <filename>/etc/passwd</filename>), else the request to add the
  92                 user will fail.  </para>
  93
  94                 <para>This option is only available when running smbpasswd
  95                 as root. </para></listitem>
  96                 </varlistentry>
  97
  98
  99
 100                 <varlistentry>
 101                 <term>-x</term>
 102                 <listitem><para>This option specifies that the username
 103                 following should be deleted from the local smbpasswd file.
 104                 </para>
 105
 106                 <para>This option is only available when running smbpasswd as
 107                 root.</para></listitem>
 108                 </varlistentry>
 109
 110
 111
 112                 <varlistentry>
 113                 <term>-d</term>
 114                 <listitem><para>This option specifies that the username following
 115                 should be <constant>disabled</constant> in the local smbpasswd
 116                 file. This is done by writing a <constant>'D'</constant> flag
 117                 into the account control space in the smbpasswd file. Once this
 118                 is done all attempts to authenticate via SMB using this username
 119                 will fail. </para>
 120
 121                 <para>If the smbpasswd file is in the 'old' format (pre-Samba 2.0
 122                 format) there is no space in the user's password entry to write
 123                 this information and the command will FAIL. See <command>smbpasswd(5)
 124                 </command> for details on the 'old' and new password file formats.
 125                 </para>
 126
 127                 <para>This option is only available when running smbpasswd as
 128                 root.</para></listitem>
 129                 </varlistentry>
 130
 131
 132                 <varlistentry>
 133                 <term>-e</term>
 134                 <listitem><para>This option specifies that the username following
 135                 should be <constant>enabled</constant> in the local smbpasswd file,
 136                 if the account was previously disabled. If the account was not
 137                 disabled this option has no effect. Once the account is enabled then
 138                 the user will be able to authenticate via SMB once again. </para>
 139
 140                 <para>If the smbpasswd file is in the 'old' format, then <command>
 141                 smbpasswd</command> will FAIL to enable the account.
 142                 See <command>smbpasswd (5)</command> for
 143                 details on the 'old' and new password file formats. </para>
 144
 145                 <para>This option is only available when running smbpasswd as root.
 146                 </para></listitem>
 147                 </varlistentry>
 148
 149
 150
 151                 <varlistentry>
 152                 <term>-D debuglevel</term>
 153                 <listitem><para><replaceable>debuglevel</replaceable> is an integer
 154                 from 0 to 10.  The default value if this parameter is not specified
 155                 is zero. </para>
 156
 157                 <para>The higher this value, the more detail will be logged to the
 158                 log files about the activities of smbpasswd. At level 0, only
 159                 critical errors and serious warnings will be logged. </para>
 160
 161                 <para>Levels above 1 will generate considerable amounts of log
 162                 data, and should only be used when investigating a problem. Levels
 163                 above 3 are designed for use only by developers and generate
 164                 HUGE amounts of log data, most of which is extremely cryptic.
 165                 </para></listitem>
 166                 </varlistentry>
 167
 168
 169
 170                 <varlistentry>
 171                 <term>-n</term>
 172                 <listitem><para>This option specifies that the username following
 173                 should have their password set to null (i.e. a blank password) in
 174                 the local smbpasswd file. This is done by writing the string "NO
 175                 PASSWORD" as the first part of the first password stored in the
 176                 smbpasswd file. </para>
 177
 178                 <para>Note that to allow users to logon to a Samba server once
 179                 the password has been set to "NO PASSWORD" in the smbpasswd
 180                 file the administrator must set the following parameter in the [global]
 181                 section of the <filename>smb.conf</filename> file : </para>
 182
 183                 <para><command>null passwords = yes</command></para>
 184
 185                 <para>This option is only available when running smbpasswd as
 186                 root.</para></listitem>
 187                 </varlistentry>
 188
 189
 190
 191                 <varlistentry>
 192                 <term>-r remote machine name</term>
 193                 <listitem><para>This option allows a user to specify what machine
 194                 they wish to change their password on. Without this parameter
 195                 smbpasswd defaults to the local host. The <replaceable>remote
 196                 machine name</replaceable> is the NetBIOS name of the SMB/CIFS
 197                 server to contact to attempt the password change. This name is
 198                 resolved into an IP address using the standard name resolution
 199                 mechanism in all programs of the Samba suite. See the <parameter>-R
 200                 name resolve order</parameter> parameter for details on changing
 201                 this resolving mechanism. </para>
 202
 203                 <para>The username whose password is changed is that of the
 204                 current UNIX logged on user. See the <parameter>-U username</parameter>
 205                 parameter for details on changing the password for a different
 206                 username. </para>
 207
 208                 <para>Note that if changing a Windows NT Domain password the
 209                 remote machine specified must be the Primary Domain Controller for
 210                 the domain (Backup Domain Controllers only have a read-only
 211                 copy of the user account database and will not allow the password
 212                 change).</para>
 213
 214                 <para><emphasis>Note</emphasis> that Windows 95/98 do not have
 215                 a real password database so it is not possible to change passwords
 216                 specifying a Win95/98  machine as remote machine target. </para>
 217                 </listitem>
 218                 </varlistentry>
 219
 220
 221                 <varlistentry>
 222                 <term>-R name resolve order</term>
 223                 <listitem><para>This option allows the user of smbpasswd to determine
 224                 what name resolution services to use when looking up the NetBIOS
 225                 name of the host being connected to. </para>
 226
 227                 <para>The options are :"lmhosts", "host", "wins" and "bcast". They cause
 228                 names to be resolved as follows : </para>
 229                         <itemizedlist>
 230                                 <listitem><para><constant>lmhosts</constant> : Lookup an IP
 231             address in the Samba lmhosts file. If the line in lmhosts has
 232             no name type attached to the NetBIOS name (see the <ulink
 233             url="lmhosts.5.html">lmhosts(5)</ulink> for details) then
 234             any name type matches for lookup.</para></listitem>
 235
 236             <listitem><para><constant>host</constant> : Do a standard host
 237             name to IP address resolution, using the system <filename>/etc/hosts
 238             </filename>, NIS, or DNS lookups. This method of name resolution
 239             is operating system depended for instance on IRIX or Solaris this
 240             may be controlled by the <filename>/etc/nsswitch.conf</filename>
 241             file).  Note that this method is only used if the NetBIOS name
 242             type being queried is the 0x20 (server) name type, otherwise
 243             it is ignored.</para></listitem>
 244
 245             <listitem><para><constant>wins</constant> : Query a name with
 246             the IP address listed in the <parameter>wins server</parameter>
 247                                 parameter.  If no WINS server has been specified this method
 248                                 will be ignored.</para></listitem>
 249
 250             <listitem><para><constant>bcast</constant> : Do a broadcast on
 251             each of the known local interfaces listed in the
 252             <parameter>interfaces</parameter> parameter. This is the least
 253                                 reliable of the name resolution methods as it depends on the
 254                                 target host being on a locally connected subnet.</para></listitem>
 255                 </itemizedlist>
 256
 257                 <para>The default order is <command>lmhosts, host, wins, bcast</command>
 258                 and without this parameter or any entry in the
 259                 <filename>smb.conf</filename> file the name resolution methods will
 260                 be attempted in this order. </para></listitem>
 261                 </varlistentry>
 262
 263
 264                 <varlistentry>
 265                 <term>-m</term>
 266                 <listitem><para>This option tells smbpasswd that the account
 267                 being changed is a MACHINE account. Currently this is used
 268                 when Samba is being used as an NT Primary Domain Controller.</para>
 269
 270                 <para>This option is only available when running smbpasswd as root.
 271                 </para></listitem>
 272                 </varlistentry>
 273
 274
 275                 <varlistentry>
 276                 <term>-U username</term>
 277                 <listitem><para>This option may only be used in conjunction
 278                 with the <parameter>-r</parameter> option. When changing
 279                 a password on a remote machine it allows the user to specify
 280                 the user name on that machine whose password will be changed. It
 281                 is present to allow users who have different user names on
 282                 different systems to change these passwords. </para></listitem>
 283                 </varlistentry>
 284
 285
 286                 <varlistentry>
 287                 <term>-h</term>
 288                 <listitem><para>This option prints the help string for <command>
 289                 smbpasswd</command>, selecting the correct one for running as root
 290                 or as an ordinary user. </para></listitem>
 291                 </varlistentry>
 292
 293
 294
 295                 <varlistentry>
 296                 <term>-s</term>
 297                 <listitem><para>This option causes smbpasswd to be silent (i.e.
 298                 not issue prompts) and to read its old and new passwords from
 299                 standard  input, rather than from <filename>/dev/tty</filename>
 300                 (like the <command>passwd(1)</command> program does). This option
 301                 is to aid people writing scripts to drive smbpasswd</para>
 302                 </listitem>
 303                 </varlistentry>
 304
 305
 306                 <varlistentry>
 307                 <term>-w password</term>
 308                 <listitem><para>This parameter is only available is Samba
 309                 has been configured to use the experiemental
 310                 <command>--with-ldapsam</command> option. The <parameter>-w</parameter>
 311                 switch is used to specify the password to be used with the
 312                 <ulink url="smb.conf.5.html#LDAPADMINDN"><parameter>ldap admin
 313                 dn</parameter></ulink>.  Note that the password is stored in
 314                 the <filename>private/secrets.tdb</filename> and is keyed off
 315                 of the admin's DN.  This means that if the value of <parameter>ldap
 316                 admin dn</parameter> ever changes, the password will beed to be
 317                 manually updated as well.
 318                 </para>
 319                 </listitem>
 320                 </varlistentry>
 321
 322
 323                 <varlistentry>
 324                 <term>username</term>
 325                 <listitem><para>This specifies the username for all of the
 326                 <emphasis>root only</emphasis> options to operate on. Only root
 327                 can specify this parameter as only root has the permission needed
 328                 to modify attributes directly in the local smbpasswd file.
 329                 </para></listitem>
 330                 </varlistentry>
 331         </variablelist>
 332 </refsect1>
 333
 334
 335 <refsect1>
 336         <title>NOTES</title>
 337
 338         <para>Since <command>smbpasswd</command> works in client-server
 339         mode communicating  with a local smbd for a non-root user then
 340         the smbd daemon must be running for this to work. A common problem
 341         is to add a restriction to the hosts that may access the <command>
 342         smbd</command> running on the local machine by specifying a
 343         <parameter>allow hosts</parameter> or <parameter>deny hosts</parameter>
 344         entry in the <filename>smb.conf</filename> file and neglecting to
 345         allow "localhost" access to the smbd. </para>
 346
 347         <para>In addition, the smbpasswd command is only useful if Samba
 348         has been set up to use encrypted passwords. See the file
 349         <filename>ENCRYPTION.txt</filename> in the docs directory for details
 350         on how to do this. </para>
 351 </refsect1>
 352
 353
 354 <refsect1>
 355         <title>VERSION</title>
 356
 357         <para>This man page is correct for version 3.0 of
 358         the Samba suite.</para>
 359 </refsect1>
 360
 361 <refsect1>
 362         <title>SEE ALSO</title>
 363         <para><ulink url="smbpasswd.5.html"><filename>smbpasswd(5)</filename></ulink>,
 364         <ulink url="samba.7.html">samba(7)</ulink>
 365         </para>
 366 </refsect1>
 367
 368 <refsect1>
 369         <title>AUTHOR</title>
 370
 371         <para>The original Samba software and related utilities
 372         were created by Andrew Tridgell. Samba is now developed
 373         by the Samba Team as an Open Source project similar
 374         to the way the Linux kernel is developed.</para>
 375
 376         <para>The original Samba man pages were written by Karl Auer.
 377         The man page sources were converted to YODL format (another
 378         excellent piece of Open Source software, available at
 379         <ulink url="ftp://ftp.icce.rug.nl/pub/unix/">
 380         ftp://ftp.icce.rug.nl/pub/unix/</ulink>) and updated for the Samba 2.0
 381         release by Jeremy Allison.  The conversion to DocBook for
 382         Samba 2.2 was done by Gerald Carter</para>
 383 </refsect1>
 384
 385 </refentry>
 386
 387
 388
 389