1 .\" This manpage has been automatically generated by docbook2man-spec
2 .\" from a DocBook document. docbook2man-spec can be found at:
3 .\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/>
4 .\" Please send any bug reports, improvements, comments, patches,
5 .\" etc. to Steve Cheng <steve@ggi-project.org>.
6 .TH "SMBPASSWD" "8" "06 June 2002" "" ""
8 smbpasswd \- change a user's SMB password
13 \fBsmbpasswd\fR [ \fBoptions\fR ] [ \fBusername\fR ] [ \fBpassword\fR ]
17 \fBsmbpasswd\fR [ \fBoptions\fR ] [ \fBpassword\fR ]
20 This tool is part of the Sambasuite.
22 The smbpasswd program has several different
23 functions, depending on whether it is run by the \fBroot\fR
24 user or not. When run as a normal user it allows the user to change
25 the password used for their SMB sessions on any machines that store
28 By default (when run with no arguments) it will attempt to
29 change the current user's SMB password on the local machine. This is
30 similar to the way the \fBpasswd(1)\fR program works.
31 \fBsmbpasswd\fR differs from how the passwd program works
32 however in that it is not \fBsetuid root\fR but works in
33 a client-server mode and communicates with a locally running
34 \fBsmbd(8)\fR. As a consequence in order for this to
35 succeed the smbd daemon must be running on the local machine. On a
36 UNIX machine the encrypted SMB passwords are usually stored in
37 the \fIsmbpasswd(5)\fR file.
39 When run by an ordinary user with no options. smbpasswd
40 will prompt them for their old SMB password and then ask them
41 for their new password twice, to ensure that the new password
42 was typed correctly. No passwords will be echoed on the screen
43 whilst being typed. If you have a blank SMB password (specified by
44 the string "NO PASSWORD" in the smbpasswd file) then just press
45 the <Enter> key when asked for your old password.
47 smbpasswd can also be used by a normal user to change their
48 SMB password on remote machines, such as Windows NT Primary Domain
49 Controllers. See the (-r) and -U options below.
51 When run by root, smbpasswd allows new users to be added
52 and deleted in the smbpasswd file, as well as allows changes to
53 the attributes of the user in this file to be made. When run by root,
54 \fBsmbpasswd\fR accesses the local smbpasswd file
55 directly, thus enabling changes to be made even if smbd is not
60 Run the smbpasswd command in local mode. This
61 allows a non-root user to specify the root-only options. This
62 is used mostly in test environments where a non-root user needs
63 to make changes to the local \fIsmbpasswd\fR file.
64 The \fIsmbpasswd\fR file must have read/write
65 permissions for the user running the command.
68 This option prints the help string for
71 \fB-c smb.conf file\fR
72 This option specifies that the configuration
73 file specified should be used instead of the default value
74 specified at compile time.
77 \fIdebuglevel\fR is an integer
78 from 0 to 10. The default value if this parameter is not specified
81 The higher this value, the more detail will be logged to the
82 log files about the activities of smbpasswd. At level 0, only
83 critical errors and serious warnings will be logged.
85 Levels above 1 will generate considerable amounts of log
86 data, and should only be used when investigating a problem. Levels
87 above 3 are designed for use only by developers and generate
88 HUGE amounts of log data, most of which is extremely cryptic.
90 \fB-r remote machine name\fR
91 This option allows a user to specify what machine
92 they wish to change their password on. Without this parameter
93 smbpasswd defaults to the local host. The \fIremote
94 machine name\fR is the NetBIOS name of the SMB/CIFS
95 server to contact to attempt the password change. This name is
96 resolved into an IP address using the standard name resolution
97 mechanism in all programs of the Samba suite. See the \fI-R
98 name resolve order\fR parameter for details on changing
99 this resolving mechanism.
101 The username whose password is changed is that of the
102 current UNIX logged on user. See the \fI-U username\fR
103 parameter for details on changing the password for a different
106 Note that if changing a Windows NT Domain password the
107 remote machine specified must be the Primary Domain Controller for
108 the domain (Backup Domain Controllers only have a read-only
109 copy of the user account database and will not allow the password
112 \fBNote\fR that Windows 95/98 do not have
113 a real password database so it is not possible to change passwords
114 specifying a Win95/98 machine as remote machine target.
117 This option causes smbpasswd to be silent (i.e.
118 not issue prompts) and to read its old and new passwords from
119 standard input, rather than from \fI/dev/tty\fR
120 (like the \fBpasswd(1)\fR program does). This option
121 is to aid people writing scripts to drive smbpasswd
124 This option causes \fBsmbpasswd\fR
125 to query a domain controller of the domain specified
127 parameter in \fIsmb.conf\fR and store the
128 domain SID in the \fIsecrets.tdb\fR file
129 as its own machine SID. This is only useful when configuring
130 a Samba PDC and Samba BDC, or when migrating from a Windows PDC
133 The \fI-r\fR options can be used
134 as well to indicate a specific domain controller which should
135 be contacted. In this case, the domain SID obtained is the
136 one for the domain to which the remote machine belongs.
138 \fB-U username[%pass]\fR
139 This option may only be used in conjunction
140 with the \fI-r\fR option. When changing
141 a password on a remote machine it allows the user to specify
142 the user name on that machine whose password will be changed. It
143 is present to allow users who have different user names on
144 different systems to change these passwords. The optional
145 %pass may be used to specify to old password.
147 In particular, this parameter specifies the username
148 used to create the machine account when invoked with -j
151 \fBThe following options are available only when the smbpasswd command is
152 run as root or in local mode.\fR
155 This option specifies that the username
156 following should be added to the local smbpasswd file, with the
157 new password typed. This
158 option is ignored if the username specified already exists in
159 the smbpasswd file and it is treated like a regular change
160 password command. Note that the user to be added must already exist
161 in the system password file (usually \fI/etc/passwd\fR)
162 else the request to add the user will fail.
165 This option specifies that the username following
166 should be disabled in the local smbpasswd
167 file. This is done by writing a 'D' flag
168 into the account control space in the smbpasswd file. Once this
169 is done all attempts to authenticate via SMB using this username
172 If the smbpasswd file is in the 'old' format (pre-Samba 2.0
173 format) there is no space in the user's password entry to write
174 this information and so the user is disabled by writing 'X' characters
175 into the password space in the smbpasswd file. See \fBsmbpasswd(5)
176 \fRfor details on the 'old' and new password file formats.
179 This option specifies that the username following
180 should be enabled in the local smbpasswd file,
181 if the account was previously disabled. If the account was not
182 disabled this option has no effect. Once the account is enabled then
183 the user will be able to authenticate via SMB once again.
185 If the smbpasswd file is in the 'old' format, then \fB smbpasswd\fR will prompt for a new password for this user,
186 otherwise the account will be enabled by removing the 'D'
187 flag from account control space in the \fI smbpasswd\fR file. See \fBsmbpasswd (5)\fR for
188 details on the 'old' and new password file formats.
191 This option tells smbpasswd that the account
192 being changed is a MACHINE account. Currently this is used
193 when Samba is being used as an NT Primary Domain Controller.
196 This option specifies that the username following
197 should have their password set to null (i.e. a blank password) in
198 the local smbpasswd file. This is done by writing the string "NO
199 PASSWORD" as the first part of the first password stored in the
202 Note that to allow users to logon to a Samba server once
203 the password has been set to "NO PASSWORD" in the smbpasswd
204 file the administrator must set the following parameter in the [global]
205 section of the \fIsmb.conf\fR file :
207 \fBnull passwords = yes\fR
210 This parameter is only available is Samba
211 has been configured to use the experimental
212 \fB--with-ldapsam\fR option. The \fI-w\fR
213 switch is used to specify the password to be used with the
215 dn\fR. Note that the password is stored in
216 the \fIprivate/secrets.tdb\fR and is keyed off
217 of the admin's DN. This means that if the value of \fIldap
218 admin dn\fR ever changes, the password will need to be
219 manually updated as well.
222 This option specifies that the username
223 following should be deleted from the local smbpasswd file.
226 This option is used to add a Samba server
227 into a Windows NT Domain, as a Domain member capable of authenticating
228 user accounts to any Domain Controller in the same way as a Windows
229 NT Server. See the \fBsecurity = domain\fR option in
230 the \fIsmb.conf(5)\fR man page.
232 This command can work both with and without the -U parameter.
234 When invoked with -U, that username (and optional password) are
235 used to contact the PDC (which must be specified with -r) to both
236 create a machine account, and to set a password on it.
238 Alternately, if -U is omitted, Samba will contact its PDC
239 and attempt to change the password on a pre-existing account.
241 In order to be used in this way, the Administrator for
242 the Windows NT Domain must have used the program "Server Manager
243 for Domains" to add the primary NetBIOS name of the Samba server
244 as a member of the Domain.
246 After this has been done, to join the Domain invoke \fB smbpasswd\fR with this parameter. smbpasswd will then
247 look up the Primary Domain Controller for the Domain (found in
248 the \fIsmb.conf\fR file in the parameter
249 \fIpassword server\fR and change the machine account
250 password used to create the secure Domain communication.
252 Either way, this password is then stored by smbpasswd in a TDB,
253 writeable only by root, called \fIsecrets.tdb\fR
255 Once this operation has been performed the \fI smb.conf\fR file may be updated to set the \fB security = domain\fR option and all future logins
256 to the Samba server will be authenticated to the Windows NT
259 Note that even though the authentication is being
260 done to the PDC all users accessing the Samba server must still
261 have a valid UNIX account on that machine.
262 The \fBwinbindd(8)\fR daemon can be used
263 to create UNIX accounts for NT users.
265 \fB-R name resolve order\fR
266 This option allows the user of smbpasswd to determine
267 what name resolution services to use when looking up the NetBIOS
268 name of the host being connected to.
270 The options are :"lmhosts", "host", "wins" and "bcast". They cause
271 names to be resolved as follows :
275 lmhosts : Lookup an IP
276 address in the Samba lmhosts file. If the line in lmhosts has
277 no name type attached to the NetBIOS name (see the lmhosts(5)for details) then
278 any name type matches for lookup.
281 host : Do a standard host
282 name to IP address resolution, using the system \fI/etc/hosts
283 \fR, NIS, or DNS lookups. This method of name resolution
284 is operating system dependent. For instance, on IRIX or Solaris this
285 may be controlled by the \fI/etc/nsswitch.conf\fR
286 file). Note that this method is only used if the NetBIOS name
287 type being queried is the 0x20 (server) name type, otherwise
291 wins : Query a name with
292 the IP address listed in the \fIwins server\fR
293 parameter. If no WINS server has been specified this method
297 bcast : Do a broadcast on
298 each of the known local interfaces listed in the
299 \fIinterfaces\fR parameter. This is the least
300 reliable of the name resolution methods as it depends on the
301 target host being on a locally connected subnet.
304 The default order is \fBlmhosts, host, wins, bcast\fR
305 and without this parameter or any entry in the
306 \fIsmb.conf\fR file the name resolution methods will
307 be attempted in this order.
311 This specifies the username for all of the
312 \fBroot only\fR options to operate on. Only root
313 can specify this parameter as only root has the permission needed
314 to modify attributes directly in the local smbpasswd file.
317 This specifies the new password. If this parameter
318 is specified you will not be prompted for the new password.
321 Since \fBsmbpasswd\fR works in client-server
322 mode communicating with a local smbd for a non-root user then
323 the smbd daemon must be running for this to work. A common problem
324 is to add a restriction to the hosts that may access the \fB smbd\fR running on the local machine by specifying a
325 \fIallow hosts\fR or \fIdeny hosts\fR
326 entry in the \fIsmb.conf\fR file and neglecting to
327 allow "localhost" access to the smbd.
329 In addition, the smbpasswd command is only useful if Samba
330 has been set up to use encrypted passwords. See the file
331 \fIENCRYPTION.txt\fR in the docs directory for details
335 This man page is correct for version 2.2 of
343 The original Samba software and related utilities
344 were created by Andrew Tridgell. Samba is now developed
345 by the Samba Team as an Open Source project similar
346 to the way the Linux kernel is developed.
348 The original Samba man pages were written by Karl Auer.
349 The man page sources were converted to YODL format (another
350 excellent piece of Open Source software, available at
351 ftp://ftp.icce.rug.nl/pub/unix/ <URL:ftp://ftp.icce.rug.nl/pub/unix/>) and updated for the Samba 2.0
352 release by Jeremy Allison. The conversion to DocBook for
353 Samba 2.2 was done by Gerald Carter