-.TH SMBPASSWD 8 "28 Oct 1997" "smbpasswd 1.9.18alpha6"
+.\" This manpage has been automatically generated by docbook2man
+.\" from a DocBook document. This tool can be found at:
+.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
+.\" Please send any bug reports, improvements, comments, patches,
+.\" etc. to Steve Cheng <steve@ggi-project.org>.
+.TH "SMBPASSWD" "8" "28 January 2003" "" ""
+
.SH NAME
-smbpasswd \- change a users smb password in the smbpasswd file.
+smbpasswd \- change a user's SMB password
.SH SYNOPSIS
-.B smbpasswd
-[
-.B \-add
-] [
-.B username
-]
-.SH DESCRIPTION
-
-This program is part of the Samba suite.
-
-.B smbpasswd
-allows a user to change their encrypted smb password which
-is stored in the smbpasswd file (usually kept in the
-.I private
-directory under the
-.I Samba
-directory hierarchy. Ordinary users can only run the command
-with no options. It 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.
-
-The
-.I \-add
-and
-.I username
-options can only be used by a user running as root.
-
-.SH OPTIONS
-.I \-add
-
-.RS 3
-Specifies that the username following should be added to
-the
-.I 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
-.I smbpasswd
-file and it is treated like a regular change password
-command. Note that the user to be added
-.B must
-already exist in the system password file (usually /etc/passwd)
-else the request to add the user will fail.
-.RE
-.I username
+\fBsmbpasswd\fR [ \fB-a\fR ] [ \fB-x\fR ] [ \fB-d\fR ] [ \fB-e\fR ] [ \fB-D debuglevel\fR ] [ \fB-n\fR ] [ \fB-r <remote machine>\fR ] [ \fB-R <name resolve order>\fR ] [ \fB-m\fR ] [ \fB-U username[%password]\fR ] [ \fB-h\fR ] [ \fB-s\fR ] [ \fB-w pass\fR ] [ \fB-i\fR ] [ \fB-L\fR ] [ \fBusername\fR ]
-.RS 3
-You may only specify a username to the smbpasswd command
-if you are running as root. Only root should have the
-permission to modify other users smb passwords.
+.SH "DESCRIPTION"
+.PP
+This tool is part of the \fBSamba\fR(7) suite.
+.PP
+The smbpasswd program has several different
+functions, depending on whether it is run by the \fBroot\fR 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.
+.PP
+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 \fBpasswd(1)\fR program works. \fB smbpasswd\fR differs from how the passwd program works
+however in that it is not \fBsetuid root\fR but works in
+a client-server mode and communicates with a
+locally running \fBsmbd\fR(8). 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 \fBsmbpasswd\fR(5) file.
+.PP
+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.
+.PP
+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 (\fI-r\fR) and \fI-U\fR options
+below.
+.PP
+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, \fB smbpasswd\fR accesses the local smbpasswd file
+directly, thus enabling changes to be made even if smbd is not
+running.
+.SH "OPTIONS"
+.TP
+\fB-a\fR
+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
+\fI/etc/passwd\fR), else the request to add the
+user will fail.
-.RE
-.RE
-.SH INSTALLATION
-
-The location of the server and its support files is a matter for individual
-system administrators. The following are thus suggestions only.
-
-It is recommended that the
-.B smbpasswd
-program be installed in the /usr/local/samba/bin directory. This should be
-a directory readable by all, writeable only by root. The program should be
-executable by all. The program
-.B must
-be setuid root. This means the permissions should
-look like -r-sr-xr-x and the program must be owned by root.
-
-.SH VERSION
-
-This man page is correct for version 1.9.17 of the Samba suite.
-These notes will necessarily lag behind
-development of the software, so it is possible that your version of
-the program has extensions or parameter semantics that differ from or are not
-covered by this man page. Please notify these to the address below for
-rectification.
-.SH SEE ALSO
-.BR smbd (8),
-.BR smb.conf (5)
-.SH
-.B BUGS
+This option is only available when running smbpasswd
+as root.
+.TP
+\fB-x\fR
+This option specifies that the username
+following should be deleted from the local smbpasswd file.
+This option is only available when running smbpasswd as
+root.
+.TP
+\fB-d\fR
+This option specifies that the username following
+should be disabled in the local smbpasswd
+file. This is done by writing a 'D' 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.
+
+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 \fBsmbpasswd\fR(5) for details on the 'old' and new password file formats.
+
+This option is only available when running smbpasswd as
+root.
+.TP
+\fB-e\fR
+This option specifies that the username following
+should be enabled 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.
+
+If the smbpasswd file is in the 'old' format, then \fB smbpasswd\fR will FAIL to enable the account.
+See \fBsmbpasswd\fR(5) for
+details on the 'old' and new password file formats.
+
+This option is only available when running smbpasswd as root.
+.TP
+\fB-D debuglevel\fR
+\fIdebuglevel\fR is an integer
+from 0 to 10. The default value if this parameter is not specified
+is zero.
+
+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.
+
+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.
+.TP
+\fB-n\fR
+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.
+
+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 \fIsmb.conf\fR file :
+
+\fBnull passwords = yes\fR
+
+This option is only available when running smbpasswd as
+root.
+.TP
+\fB-r remote machine name\fR
+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 \fIremote
+machine name\fR 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 \fI-R
+name resolve order\fR parameter for details on changing
+this resolving mechanism.
+
+The username whose password is changed is that of the
+current UNIX logged on user. See the \fI-U username\fR
+parameter for details on changing the password for a different
+username.
+
+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).
+
+\fBNote\fR 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.
+.TP
+\fB-R name resolve order\fR
+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.
+
+The options are :"lmhosts", "host", "wins" and "bcast". They
+cause names to be resolved as follows:
+.RS
+.TP 0.2i
+\(bu
+lmhosts: 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 \fBlmhosts\fR(5) for details) then
+any name type matches for lookup.
+.TP 0.2i
+\(bu
+host: Do a standard host
+name to IP address resolution, using the system \fI/etc/hosts
+\fR, 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 \fI/etc/nsswitch.conf\fR
+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.
+.TP 0.2i
+\(bu
+wins: Query a name with
+the IP address listed in the \fIwins server\fR
+parameter. If no WINS server has been specified this method
+will be ignored.
+.TP 0.2i
+\(bu
+bcast: Do a broadcast on
+each of the known local interfaces listed in the
+\fIinterfaces\fR parameter. This is the least
+reliable of the name resolution methods as it depends on the
+target host being on a locally connected subnet.
.RE
-The
-.B smbpasswd
-command is only useful if
-.I Samba
-has been compiled with encrypted passwords. See the file
-.I ENCRYPTION.txt
-in the docs directory for details on how to do this.
-
-.SH CREDITS
-.RE
-The original Samba software and related utilities were created by
-Andrew Tridgell (samba-bugs@samba.anu.edu.au). Andrew is also the Keeper
-of the Source for this project. smbpasswd and the encrypted password
-file code was written by Jeremy Allison (samba-bugs@samba.anu.edu.au).
-This man page was written by Jeremy Allison. Bug reports to samba-bugs@samba.anu.edu.au.
+The default order is \fBlmhosts, host, wins, bcast\fR
+and without this parameter or any entry in the \fBsmb.conf\fR(5) file the name resolution methods will
+be attempted in this order.
+.TP
+\fB-m\fR
+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.
+
+This option is only available when running smbpasswd as root.
+.TP
+\fB-U username\fR
+This option may only be used in conjunction
+with the \fI-r\fR 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.
+.TP
+\fB-h\fR
+This option prints the help string for \fB smbpasswd\fR, selecting the correct one for running as root
+or as an ordinary user.
+.TP
+\fB-s\fR
+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 \fI/dev/tty\fR
+(like the \fBpasswd(1)\fR program does). This option
+is to aid people writing scripts to drive smbpasswd
+.TP
+\fB-w password\fR
+This parameter is only available if Samba
+has been configured to use the experimental
+\fB--with-ldapsam\fR option. The \fI-w\fR
+switch is used to specify the password to be used with the
+\fIldap admin
+dn\fR Note that the password is stored in
+the \fIsecrets.tdb\fR and is keyed off
+of the admin's DN. This means that if the value of \fIldap
+admin dn\fR ever changes, the password will need to be
+manually updated as well.
+.TP
+\fB-i\fR
+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.
-See
-.BR smb.conf (5)
-for a full list of contributors and details of how to
-submit bug reports, comments etc.
+This option is only available when running smbpasswd as root.
+.TP
+\fB-L\fR
+Run in local mode.
+.TP
+\fBusername\fR
+This specifies the username for all of the
+\fBroot only\fR 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.
+.SH "NOTES"
+.PP
+Since \fBsmbpasswd\fR 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 \fB smbd\fR running on the local machine by specifying either \fIallow
+hosts\fR or \fIdeny hosts\fR entry in
+the \fBsmb.conf\fR(5) file and neglecting to
+allow "localhost" access to the smbd.
+.PP
+In addition, the smbpasswd command is only useful if Samba
+has been set up to use encrypted passwords. See the document "LanMan and NT Password Encryption in Samba" in the docs directory for details
+on how to do this.
+.SH "VERSION"
+.PP
+This man page is correct for version 3.0 of the Samba suite.
+.SH "SEE ALSO"
+.PP
+\fBsmbpasswd\fR(5), \fBSamba\fR(7).
+.SH "AUTHOR"
+.PP
+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.
+.PP
+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 ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) 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.