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