docs: Bump version up to 4.6.
[sfrench/samba-autobuild/.git] / docs-xml / manpages / pdbedit.8.xml
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
3 <refentry id="pdbedit.8">
4
5 <refmeta>
6         <refentrytitle>pdbedit</refentrytitle>
7         <manvolnum>8</manvolnum>
8         <refmiscinfo class="source">Samba</refmiscinfo>
9         <refmiscinfo class="manual">System Administration tools</refmiscinfo>
10         <refmiscinfo class="version">4.6</refmiscinfo>
11 </refmeta>
12
13
14 <refnamediv>
15         <refname>pdbedit</refname>
16         <refpurpose>manage the SAM database (Database of Samba Users)</refpurpose>
17 </refnamediv>
18
19 <refsynopsisdiv>
20         <cmdsynopsis>
21                 <command>pdbedit</command>
22                 <arg choice="opt">-a</arg>
23                 <arg choice="opt">-b passdb-backend</arg>
24                 <arg choice="opt">-c account-control</arg>
25                 <arg choice="opt">-C value</arg>
26                 <arg choice="opt">-d debuglevel</arg>
27                 <arg choice="opt">-D drive</arg>
28                 <arg choice="opt">-e passdb-backend</arg>
29                 <arg choice="opt">-f fullname</arg>
30                 <arg choice="opt">--force-initialized-passwords</arg>
31                 <arg choice="opt">-g</arg>
32                 <arg choice="opt">-h homedir</arg>
33                 <arg choice="opt">-i passdb-backend</arg>
34                 <arg choice="opt">-I domain</arg>
35                 <arg choice="opt">-K</arg>
36                 <arg choice="opt">-L </arg>
37                 <arg choice="opt">-m</arg>
38                 <arg choice="opt">-M SID|RID</arg>
39                 <arg choice="opt">-N description</arg>
40                 <arg choice="opt">-P account-policy</arg>
41                 <arg choice="opt">-p profile</arg>
42                 <arg choice="opt">--policies-reset</arg>
43                 <arg choice="opt">-r</arg>
44                 <arg choice="opt">-s configfile</arg>
45                 <arg choice="opt">-S script</arg>
46                 <arg choice="opt">--set-nt-hash</arg>
47                 <arg choice="opt">-t</arg>
48                 <arg choice="opt">--time-format</arg>
49                 <arg choice="opt">-u username</arg>
50                 <arg choice="opt">-U SID|RID</arg>
51                 <arg choice="opt">-v</arg>
52                 <arg choice="opt">-V</arg>
53                 <arg choice="opt">-w</arg>
54                 <arg choice="opt">-x</arg>
55                 <arg choice="opt">-y</arg>
56                 <arg choice="opt">-z</arg>
57                 <arg choice="opt">-Z</arg>
58         </cmdsynopsis>
59 </refsynopsisdiv>
60
61 <refsect1>
62         <title>DESCRIPTION</title>
63
64         <para>This tool is part of the <citerefentry><refentrytitle>samba</refentrytitle>
65         <manvolnum>7</manvolnum></citerefentry> suite.</para>
66
67         <para>The pdbedit program is used to manage the users accounts
68         stored in the sam database and can only be run by root.</para>
69
70         <para>The pdbedit tool uses the passdb modular interface and is
71         independent from the kind of users database used (currently there
72         are smbpasswd, ldap, nis+ and tdb based and more can be added
73         without changing the tool).</para>
74
75         <para>There are five main ways to use pdbedit: adding a user account,
76         removing a user account, modifying a user account, listing user
77         accounts, importing users accounts.</para>
78 </refsect1>
79
80 <refsect1>
81         <title>OPTIONS</title>
82         <variablelist>
83                 <varlistentry>
84                 <term>-L|--list</term>
85                 <listitem><para>This option lists all the user accounts
86                 present in the users database.
87                 This option prints a list of user/uid pairs separated by
88                 the ':' character.</para>
89                 <para>Example: <command>pdbedit -L</command></para>
90                 <para><programlisting>
91 sorce:500:Simo Sorce
92 samba:45:Test User
93 </programlisting></para>
94                 </listitem>
95                 </varlistentry>
96                 
97                 
98                 
99                 <varlistentry>
100                 <term>-v|--verbose</term>
101                 <listitem><para>This option enables the verbose listing format.
102                 It causes pdbedit to list the users in the database, printing
103                 out the account fields in a descriptive format. Used together
104                 with -w also shows passwords hashes.</para>
105
106                 <para>Example: <command>pdbedit -L -v</command></para>
107                 <para><programlisting>
108 ---------------
109 username:       sorce
110 user ID/Group:  500/500
111 user RID/GRID:  2000/2001
112 Full Name:      Simo Sorce
113 Home Directory: \\BERSERKER\sorce
114 HomeDir Drive:  H:
115 Logon Script:   \\BERSERKER\netlogon\sorce.bat
116 Profile Path:   \\BERSERKER\profile
117 ---------------
118 username:       samba
119 user ID/Group:  45/45
120 user RID/GRID:  1090/1091
121 Full Name:      Test User
122 Home Directory: \\BERSERKER\samba
123 HomeDir Drive:  
124 Logon Script:   
125 Profile Path:   \\BERSERKER\profile
126 </programlisting></para>
127                 </listitem>
128                 </varlistentry>
129                 
130                 
131                 
132                 <varlistentry>
133                 <term>-w|--smbpasswd-style</term>
134                 <listitem><para>This option sets the "smbpasswd" listing format.
135                 It will make pdbedit list the users in the database, printing
136                 out the account fields in a format compatible with the
137                 <filename>smbpasswd</filename> file format. (see the
138                 <citerefentry><refentrytitle>smbpasswd</refentrytitle>
139                 <manvolnum>5</manvolnum></citerefentry> for details).
140                 Instead used together with (-v) displays the passwords
141                 hashes in verbose output.</para>
142
143                 <para>Example: <command>pdbedit -L -w</command></para>
144                 <programlisting>
145 sorce:500:508818B733CE64BEAAD3B435B51404EE:
146           D2A2418EFC466A8A0F6B1DBB5C3DB80C:
147           [UX         ]:LCT-00000000:
148 samba:45:0F2B255F7B67A7A9AAD3B435B51404EE:
149           BC281CE3F53B6A5146629CD4751D3490:
150           [UX         ]:LCT-3BFA1E8D:
151 </programlisting>
152                 </listitem>
153                 </varlistentry>
154                 
155                 
156                 <varlistentry>
157                 <term>-u|--user username</term>
158                 <listitem><para>This option specifies the username to be
159                 used for the operation requested (listing, adding, removing).
160                 It is <emphasis>required</emphasis> in add, remove and modify
161                 operations and <emphasis>optional</emphasis> in list
162                 operations.</para>
163                 </listitem>
164                 </varlistentry>
165
166                 <varlistentry>
167                 <term>-f|--fullname fullname</term>
168                 <listitem><para>This option can be used while adding or
169                 modifying a user account. It will specify the user's full
170                 name. </para>
171
172                 <para>Example: <command>-f "Simo Sorce"</command></para>
173                 </listitem>
174                 </varlistentry>
175                 
176                 <varlistentry>
177                 <term>-h|--homedir homedir</term>
178                 <listitem><para>This option can be used while adding or
179                 modifying a user account. It will specify the user's home
180                 directory network path.</para>
181
182                 <para>Example: <command>-h "\\\\BERSERKER\\sorce"</command>
183                 </para>
184                 </listitem>
185                 </varlistentry>
186                 
187                 <varlistentry>
188                 <term>-D|--drive drive</term>
189                 <listitem><para>This option can be used while adding or
190                 modifying a user account. It will specify the windows drive
191                 letter to be used to map the home directory.</para>
192
193                 <para>Example: <command>-D "H:"</command>
194                 </para>
195                 </listitem>
196                 </varlistentry>
197                 
198                 
199                 <varlistentry>
200                 <term>-S|--script script</term>
201                 <listitem><para>This option can be used while adding or
202                 modifying a user account. It will specify the user's logon
203                 script path.</para>
204
205                 <para>Example: <command>-S "\\\\BERSERKER\\netlogon\\sorce.bat"</command>
206                 </para>
207                 </listitem>
208                 </varlistentry>
209                 
210                 
211                 <varlistentry>
212                 <term>--set-nt-hash</term>
213                 <listitem><para>This option can be used while modifying
214                 a user account. It will set the user's password using
215                 the nt-hash value given as hexadecimal string.
216                 Useful to synchronize passwords.</para>
217        
218                 <para>Example: <command>--set-nt-hash 8846F7EAEE8FB117AD06BDD830B7586C</command>
219                 </para>
220                 </listitem>
221                 </varlistentry>
222
223                 <varlistentry>
224                 <term>-p|--profile profile</term>
225                 <listitem><para>This option can be used while adding or
226                 modifying a user account. It will specify the user's profile
227                 directory.</para>
228
229                 <para>Example: <command>-p "\\\\BERSERKER\\netlogon"</command>
230                 </para>
231                 </listitem>
232                 </varlistentry>
233
234                 <varlistentry>
235                 <term>-M|'--machine SID' SID|rid</term>
236                 <listitem><para>
237                 This option can be used while adding or modifying a machine account. It
238                 will specify the machines' new primary group SID (Security Identifier) or
239                 rid. </para>
240
241                 <para>Example: <command>-M S-1-5-21-2447931902-1787058256-3961074038-1201</command></para>
242                 </listitem>
243                 </varlistentry>
244
245                 <varlistentry>
246                 <term>-U|'--user SID' SID|rid</term>
247                 <listitem><para>
248                 This option can be used while adding or modifying a user account. It 
249                 will specify the users' new SID (Security Identifier) or 
250                 rid. </para>
251
252                 <para>Example: <command>-U S-1-5-21-2447931902-1787058256-3961074038-5004</command></para>
253                 <para>Example: <command>'--user SID' S-1-5-21-2447931902-1787058256-3961074038-5004</command></para>
254                 <para>Example: <command>-U 5004</command></para>
255                 <para>Example: <command>'--user SID' 5004</command></para>
256                 </listitem>
257                 </varlistentry>
258
259                 <varlistentry>
260                 <term>-c|--account-control account-control</term>
261                 <listitem><para>This option can be used while adding or modifying a user
262                                 account. It will specify the users' account control property. Possible flags are listed below.
263         </para>
264
265         <para>
266                 <itemizedlist>
267                         <listitem><para>N: No password required</para></listitem>
268                         <listitem><para>D: Account disabled</para></listitem>
269                         <listitem><para>H: Home directory required</para></listitem>
270                         <listitem><para>T: Temporary duplicate of other account</para></listitem>
271                         <listitem><para>U: Regular user account</para></listitem>
272                         <listitem><para>M: MNS logon user account</para></listitem>
273                         <listitem><para>W: Workstation Trust Account</para></listitem>
274                         <listitem><para>S: Server Trust Account</para></listitem>
275                         <listitem><para>L: Automatic Locking</para></listitem>
276                         <listitem><para>X: Password does not expire</para></listitem>
277                         <listitem><para>I: Domain Trust Account</para></listitem>
278                 </itemizedlist>
279         </para>
280
281                 <para>Example: <command>-c "[X          ]"</command></para>
282                 </listitem>
283                 </varlistentry>
284
285                 <varlistentry>
286                 <term>-K|--kickoff-time</term>
287                 <listitem><para>This option is used to modify the kickoff
288                 time for a certain user. Use "never" as argument to set the
289                 kickoff time to unlimited.
290                 </para>
291                 <para>Example: <command>pdbedit -K never user</command></para>
292                 </listitem>
293                 </varlistentry>
294
295                 <varlistentry>
296                 <term>-a|--create</term>
297                 <listitem><para>This option is used to add a user into the
298                 database. This command needs a user name specified with
299                 the -u switch. When adding a new user, pdbedit will also
300                 ask for the password to be used.</para>
301
302                 <para>Example: <command>pdbedit -a -u sorce</command>
303 <programlisting>new password:
304 retype new password
305 </programlisting>
306 </para>
307
308                 <note><para>pdbedit does not call the unix password synchronization 
309                                 script if <smbconfoption name="unix password sync"/>
310                                 has been set. It only updates the data in the Samba 
311                                 user database. 
312                         </para>
313
314                         <para>If you wish to add a user and synchronise the password
315                                 that immediately, use <command>smbpasswd</command>'s <option>-a</option> option.
316                         </para>
317                 </note>
318                 </listitem>
319                 </varlistentry>
320                 
321                 <varlistentry>
322                 <term>-t|--password-from-stdin</term>
323                 <listitem><para>This option causes pdbedit to read the password
324                 from standard input, rather than from /dev/tty (like the
325                 <command>passwd(1)</command> program does).  The password has
326                 to be submitted twice and terminated by a newline each.</para>
327                 </listitem>
328                 </varlistentry>
329
330                 <varlistentry>
331                 <term>-r|--modify</term>
332                 <listitem><para>This option is used to modify an existing user 
333                 in the database. This command needs a user name specified with the -u 
334                 switch. Other options can be specified to modify the properties of 
335                 the specified user. This flag is kept for backwards compatibility, but 
336                 it is no longer necessary to specify it.
337                 </para></listitem>
338                 </varlistentry>
339                         
340                 <varlistentry>
341                 <term>-m|--machine</term>
342                 <listitem><para>This option may only be used in conjunction 
343                 with the <parameter>-a</parameter> option. It will make
344                 pdbedit to add a machine trust account instead of a user
345                 account (-u username will provide the machine name).</para>
346
347                 <para>Example: <command>pdbedit -a -m -u w2k-wks</command>
348                 </para>
349                 </listitem>
350                 </varlistentry>
351                 
352                 
353                 <varlistentry>
354                 <term>-x|--delete</term>
355                 <listitem><para>This option causes pdbedit to delete an account
356                 from the database. It needs a username specified with the
357                 -u switch.</para>
358
359                 <para>Example: <command>pdbedit -x -u bob</command></para>
360                 </listitem>
361                 </varlistentry>
362                 
363
364                 <varlistentry>
365                 <term>-i|--import passdb-backend</term>
366                 <listitem><para>Use a different passdb backend to retrieve users
367                 than the one specified in smb.conf. Can be used to import data into
368                 your local user database.</para>
369
370                 <para>This option will ease migration from one passdb backend to
371                 another.</para>
372
373                 <para>Example: <command>pdbedit -i smbpasswd:/etc/smbpasswd.old
374                 </command></para>
375                 </listitem>
376                 </varlistentry>
377
378                 <varlistentry>
379                 <term>-e|--export passdb-backend</term>
380                 <listitem><para>Exports all currently available users to the
381                 specified password database backend.</para>
382
383                 <para>This option will ease migration from one passdb backend to
384                 another and will ease backing up.</para>
385                 
386                 <para>Example: <command>pdbedit -e smbpasswd:/root/samba-users.backup</command></para>
387                 </listitem>
388                 </varlistentry>
389
390                 <varlistentry>
391                 <term>-g|--group</term>
392                 <listitem><para>If you specify <parameter>-g</parameter>,
393                 then <parameter>-i in-backend -e out-backend</parameter>
394                 applies to the group mapping instead of the user database.</para>
395
396                 <para>This option will ease migration from one passdb backend to
397                 another and will ease backing up.</para>
398                 
399                 </listitem>
400                 </varlistentry>
401
402                 <varlistentry>
403                 <term>-b|--backend passdb-backend</term>
404                 <listitem><para>Use a different default passdb backend. </para>
405
406                 <para>Example: <command>pdbedit -b xml:/root/pdb-backup.xml -l</command></para>
407                 </listitem>
408                 </varlistentry>
409
410                 <varlistentry>
411                 <term>-P|--account-policy account-policy</term>
412                 <listitem><para>Display an account policy</para>
413                 <para>Valid policies are: minimum password age, reset count minutes, disconnect time,
414                 user must logon to change password, password history, lockout duration, min password length,
415                 maximum password age and bad lockout attempt.</para>
416
417                 <para>Example: <command>pdbedit -P "bad lockout attempt"</command></para>
418 <para><programlisting>
419 account policy value for bad lockout attempt is 0
420 </programlisting></para>
421
422                 </listitem>
423                 </varlistentry>
424
425
426                 <varlistentry>
427                 <term>-C|--value account-policy-value</term>
428                 <listitem><para>Sets an account policy to a specified value. 
429                 This option may only be used in conjunction
430                 with the <parameter>-P</parameter> option.
431                 </para>
432
433                 <para>Example: <command>pdbedit -P "bad lockout attempt" -C 3</command></para>
434 <para><programlisting>
435 account policy value for bad lockout attempt was 0
436 account policy value for bad lockout attempt is now 3
437 </programlisting></para>
438                 </listitem>
439                 </varlistentry>
440
441                 <varlistentry>
442                 <term>-y|--policies</term>
443                 <listitem><para>If you specify <parameter>-y</parameter>,
444                 then <parameter>-i in-backend -e out-backend</parameter>
445                 applies to the account policies instead of the user database.</para>
446
447                 <para>This option will allow one to migrate account policies from their default
448                 tdb-store into a passdb backend, e.g. an LDAP directory server.</para>
449
450                 <para>Example: <command>pdbedit -y -i tdbsam: -e ldapsam:ldap://my.ldap.host</command></para>
451         
452                 </listitem>
453                 </varlistentry>
454
455                 <varlistentry>
456                 <term>--force-initialized-passwords</term>
457                 <listitem><para>This option forces all users to change their
458                                 password upon next login.
459                 </para>
460                 </listitem>
461                 </varlistentry>
462
463                 <varlistentry>
464                 <term>-N|--account-desc description</term>
465                 <listitem><para>This option can be used while adding or
466                 modifying a user account. It will specify the user's description
467                 field.</para>
468
469                 <para>Example: <command>-N "test description"</command>
470                 </para>
471                 </listitem>
472                 </varlistentry>
473
474                 <varlistentry>
475                 <term>-Z|--logon-hours-reset</term>
476                 <listitem><para>This option can be used while adding or
477                 modifying a user account. It will reset the user's allowed logon
478                 hours. A user may login at any time afterwards.</para>
479
480                 <para>Example: <command>-Z</command>
481                 </para>
482                 </listitem>
483                 </varlistentry>
484
485                 <varlistentry>
486                 <term>-z|--bad-password-count-reset</term>
487                 <listitem><para>This option can be used while adding or
488                 modifying a user account. It will reset the stored bad login
489                 counter from a specified user.</para>
490
491                 <para>Example: <command>-z</command>
492                 </para>
493                 </listitem>
494                 </varlistentry>
495
496                 <varlistentry>
497                 <term>--policies-reset</term>
498                 <listitem><para>This option can be used to reset the general
499                                 password policies stored for a domain to their
500                                 default values.</para>
501                 <para>Example: <command>--policies-reset</command>
502                 </para>
503                 </listitem>
504                 </varlistentry>
505
506                 <varlistentry>
507                 <term>-I|--domain</term>
508                 <listitem><para>This option can be used while adding or
509                 modifying a user account. It will specify the user's domain field.</para>
510
511                 <para>Example: <command>-I "MYDOMAIN"</command>
512                 </para>
513                 </listitem>
514                 </varlistentry>
515
516                 <varlistentry>
517                 <term>--time-format</term>
518                 <listitem><para>This option is currently not being used.</para>
519                 </listitem>
520                 </varlistentry>
521
522                 &popt.autohelp;
523                 &stdarg.server.debug;
524                 &popt.common.samba;
525
526         </variablelist>
527 </refsect1>
528
529
530 <refsect1>
531         <title>NOTES</title>
532         
533         <para>This command may be used only by root.</para>
534 </refsect1>
535
536
537 <refsect1>
538         <title>VERSION</title>
539
540         <para>This man page is correct for version 3 of 
541         the Samba suite.</para>
542 </refsect1>
543
544 <refsect1>
545         <title>SEE ALSO</title>
546         <para><citerefentry><refentrytitle>smbpasswd</refentrytitle>
547         <manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>samba</refentrytitle>
548         <manvolnum>7</manvolnum></citerefentry></para>
549 </refsect1>
550
551 <refsect1>
552         <title>AUTHOR</title>
553         
554         <para>The original Samba software and related utilities 
555         were created by Andrew Tridgell. Samba is now developed
556         by the Samba Team as an Open Source project similar 
557         to the way the Linux kernel is developed.</para>
558
559         <para>The pdbedit manpage was written by Simo Sorce and Jelmer Vernooij.</para>
560
561 </refsect1>
562
563 </refentry>