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