Debian Codegraph @

doc/admin/admin_commands/kdb5_util.rst

raw
1 .. _kdb5_util(8):
2
3 kdb5_util
4 =========
5
6 SYNOPSIS
7 --------
8
9 .. _kdb5_util_synopsis:
10
11 **kdb5_util**
12 [**-r** *realm*]
13 [**-d** *dbname*]
14 [**-k** *mkeytype*]
15 [**-kv** *mkeyVNO*]
16 [**-M** *mkeyname*]
17 [**-m**]
18 [**-sf** *stashfilename*]
19 [**-P** *password*]
20 [**-x** *db_args*]
21 *command* [*command_options*]
22
23 .. _kdb5_util_synopsis_end:
24
25 DESCRIPTION
26 -----------
27
28 kdb5_util allows an administrator to perform maintenance procedures on
29 the KDC database. Databases can be created, destroyed, and dumped to
30 or loaded from ASCII files. kdb5_util can create a Kerberos master
31 key stash file or perform live rollover of the master key.
32
33 When kdb5_util is run, it attempts to acquire the master key and open
34 the database. However, execution continues regardless of whether or
35 not kdb5_util successfully opens the database, because the database
36 may not exist yet or the stash file may be corrupt.
37
38 Note that some KDC database modules may not support all kdb5_util
39 commands.
40
41
42 COMMAND-LINE OPTIONS
43 --------------------
44
45 .. _kdb5_util_options:
46
47 **-r** *realm*
48 specifies the Kerberos realm of the database.
49
50 **-d** *dbname*
51 specifies the name under which the principal database is stored;
52 by default the database is that listed in :ref:`kdc.conf(5)`. The
53 password policy database and lock files are also derived from this
54 value.
55
56 **-k** *mkeytype*
57 specifies the key type of the master key in the database. The
58 default is given by the **master_key_type** variable in
59 :ref:`kdc.conf(5)`.
60
61 **-kv** *mkeyVNO*
62 Specifies the version number of the master key in the database;
63 the default is 1. Note that 0 is not allowed.
64
65 **-M** *mkeyname*
66 principal name for the master key in the database. If not
67 specified, the name is determined by the **master_key_name**
68 variable in :ref:`kdc.conf(5)`.
69
70 **-m**
71 specifies that the master database password should be read from
72 the keyboard rather than fetched from a file on disk.
73
74 **-sf** *stash_file*
75 specifies the stash filename of the master database password. If
76 not specified, the filename is determined by the
77 **key_stash_file** variable in :ref:`kdc.conf(5)`.
78
79 **-P** *password*
80 specifies the master database password. Using this option may
81 expose the password to other users on the system via the process
82 list.
83
84 **-x** *db_args*
85 specifies database-specific options. See :ref:`kadmin(1)` for
86 supported options.
87
88 .. _kdb5_util_options_end:
89
90
91 COMMANDS
92 --------
93
94 create
95 ~~~~~~
96
97 .. _kdb5_util_create:
98
99 **create** [**-s**]
100
101 Creates a new database. If the **-s** option is specified, the stash
102 file is also created. This command fails if the database already
103 exists. If the command is successful, the database is opened just as
104 if it had already existed when the program was first run.
105
106 .. _kdb5_util_create_end:
107
108 destroy
109 ~~~~~~~
110
111 .. _kdb5_util_destroy:
112
113 **destroy** [**-f**]
114
115 Destroys the database, first overwriting the disk sectors and then
116 unlinking the files, after prompting the user for confirmation. With
117 the **-f** argument, does not prompt the user.
118
119 .. _kdb5_util_destroy_end:
120
121 stash
122 ~~~~~
123
124 .. _kdb5_util_stash:
125
126 **stash** [**-f** *keyfile*]
127
128 Stores the master principal's keys in a stash file. The **-f**
129 argument can be used to override the *keyfile* specified in
130 :ref:`kdc.conf(5)`.
131
132 .. _kdb5_util_stash_end:
133
134 dump
135 ~~~~
136
137 .. _kdb5_util_dump:
138
139 **dump** [**-b7**\|\ **-r13**\|\ **-r18**]
140 [**-verbose**] [**-mkey_convert**] [**-new_mkey_file**
141 *mkey_file*] [**-rev**] [**-recurse**] [*filename*
142 [*principals*...]]
143
144 Dumps the current Kerberos and KADM5 database into an ASCII file. By
145 default, the database is dumped in current format, "kdb5_util
146 load_dump version 7". If filename is not specified, or is the string
147 "-", the dump is sent to standard output. Options:
148
149 **-b7**
150 causes the dump to be in the Kerberos 5 Beta 7 format ("kdb5_util
151 load_dump version 4"). This was the dump format produced on
152 releases prior to 1.2.2.
153
154 **-r13**
155 causes the dump to be in the Kerberos 5 1.3 format ("kdb5_util
156 load_dump version 5"). This was the dump format produced on
157 releases prior to 1.8.
158
159 **-r18**
160 causes the dump to be in the Kerberos 5 1.8 format ("kdb5_util
161 load_dump version 6"). This was the dump format produced on
162 releases prior to 1.11.
163
164 **-verbose**
165 causes the name of each principal and policy to be printed as it
166 is dumped.
167
168 **-mkey_convert**
169 prompts for a new master key. This new master key will be used to
170 re-encrypt principal key data in the dumpfile. The principal keys
171 themselves will not be changed.
172
173 **-new_mkey_file** *mkey_file*
174 the filename of a stash file. The master key in this stash file
175 will be used to re-encrypt the key data in the dumpfile. The key
176 data in the database will not be changed.
177
178 **-rev**
179 dumps in reverse order. This may recover principals that do not
180 dump normally, in cases where database corruption has occurred.
181
182 **-recurse**
183 causes the dump to walk the database recursively (btree only).
184 This may recover principals that do not dump normally, in cases
185 where database corruption has occurred. In cases of such
186 corruption, this option will probably retrieve more principals
187 than the **-rev** option will.
188
189 .. versionchanged:: 1.15
190 Release 1.15 restored the functionality of the **-recurse**
191 option.
192
193 .. versionchanged:: 1.5
194 The **-recurse** option ceased working until release 1.15,
195 doing a normal dump instead of a recursive traversal.
196
197 .. _kdb5_util_dump_end:
198
199 load
200 ~~~~
201
202 .. _kdb5_util_load:
203
204 **load** [**-b7**\|\ **-r13**\|\ **-r18**] [**-hash**]
205 [**-verbose**] [**-update**] *filename*
206
207 Loads a database dump from the named file into the named database. If
208 no option is given to determine the format of the dump file, the
209 format is detected automatically and handled as appropriate. Unless
210 the **-update** option is given, **load** creates a new database
211 containing only the data in the dump file, overwriting the contents of
212 any previously existing database. Note that when using the LDAP KDC
213 database module, the **-update** flag is required.
214
215 Options:
216
217 **-b7**
218 requires the database to be in the Kerberos 5 Beta 7 format
219 ("kdb5_util load_dump version 4"). This was the dump format
220 produced on releases prior to 1.2.2.
221
222 **-r13**
223 requires the database to be in Kerberos 5 1.3 format ("kdb5_util
224 load_dump version 5"). This was the dump format produced on
225 releases prior to 1.8.
226
227 **-r18**
228 requires the database to be in Kerberos 5 1.8 format ("kdb5_util
229 load_dump version 6"). This was the dump format produced on
230 releases prior to 1.11.
231
232 **-hash**
233 stores the database in hash format, if using the DB2 database
234 type. If this option is not specified, the database will be
235 stored in btree format. This option is not recommended, as
236 databases stored in hash format are known to corrupt data and lose
237 principals.
238
239 **-verbose**
240 causes the name of each principal and policy to be printed as it
241 is dumped.
242
243 **-update**
244 records from the dump file are added to or updated in the existing
245 database. Otherwise, a new database is created containing only
246 what is in the dump file and the old one destroyed upon successful
247 completion.
248
249 .. _kdb5_util_load_end:
250
251 ark
252 ~~~
253
254 **ark** [**-e** *enc*:*salt*,...] *principal*
255
256 Adds new random keys to *principal* at the next available key version
257 number. Keys for the current highest key version number will be
258 preserved. The **-e** option specifies the list of encryption and
259 salt types to be used for the new keys.
260
261 add_mkey
262 ~~~~~~~~
263
264 **add_mkey** [**-e** *etype*] [**-s**]
265
266 Adds a new master key to the master key principal, but does not mark
267 it as active. Existing master keys will remain. The **-e** option
268 specifies the encryption type of the new master key; see
269 :ref:`Encryption_types` in :ref:`kdc.conf(5)` for a list of possible
270 values. The **-s** option stashes the new master key in the stash
271 file, which will be created if it doesn't already exist.
272
273 After a new master key is added, it should be propagated to replica
274 servers via a manual or periodic invocation of :ref:`kprop(8)`. Then,
275 the stash files on the replica servers should be updated with the
276 kdb5_util **stash** command. Once those steps are complete, the key
277 is ready to be marked active with the kdb5_util **use_mkey** command.
278
279 use_mkey
280 ~~~~~~~~
281
282 **use_mkey** *mkeyVNO* [*time*]
283
284 Sets the activation time of the master key specified by *mkeyVNO*.
285 Once a master key becomes active, it will be used to encrypt newly
286 created principal keys. If no *time* argument is given, the current
287 time is used, causing the specified master key version to become
288 active immediately. The format for *time* is :ref:`getdate` string.
289
290 After a new master key becomes active, the kdb5_util
291 **update_princ_encryption** command can be used to update all
292 principal keys to be encrypted in the new master key.
293
294 list_mkeys
295 ~~~~~~~~~~
296
297 **list_mkeys**
298
299 List all master keys, from most recent to earliest, in the master key
300 principal. The output will show the kvno, enctype, and salt type for
301 each mkey, similar to the output of :ref:`kadmin(1)` **getprinc**. A
302 ``*`` following an mkey denotes the currently active master key.
303
304 purge_mkeys
305 ~~~~~~~~~~~
306
307 **purge_mkeys** [**-f**] [**-n**] [**-v**]
308
309 Delete master keys from the master key principal that are not used to
310 protect any principals. This command can be used to remove old master
311 keys all principal keys are protected by a newer master key.
312
313 **-f**
314 does not prompt for confirmation.
315
316 **-n**
317 performs a dry run, showing master keys that would be purged, but
318 not actually purging any keys.
319
320 **-v**
321 gives more verbose output.
322
323 update_princ_encryption
324 ~~~~~~~~~~~~~~~~~~~~~~~
325
326 **update_princ_encryption** [**-f**] [**-n**] [**-v**]
327 [*princ-pattern*]
328
329 Update all principal records (or only those matching the
330 *princ-pattern* glob pattern) to re-encrypt the key data using the
331 active database master key, if they are encrypted using a different
332 version, and give a count at the end of the number of principals
333 updated. If the **-f** option is not given, ask for confirmation
334 before starting to make changes. The **-v** option causes each
335 principal processed to be listed, with an indication as to whether it
336 needed updating or not. The **-n** option performs a dry run, only
337 showing the actions which would have been taken.
338
339 tabdump
340 ~~~~~~~
341
342 **tabdump** [**-H**] [**-c**] [**-e**] [**-n**] [**-o** *outfile*]
343 *dumptype*
344
345 Dump selected fields of the database in a tabular format suitable for
346 reporting (e.g., using traditional Unix text processing tools) or
347 importing into relational databases. The data format is tab-separated
348 (default), or optionally comma-separated (CSV), with a fixed number of
349 columns. The output begins with a header line containing field names,
350 unless suppression is requested using the **-H** option.
351
352 The *dumptype* parameter specifies the name of an output table (see
353 below).
354
355 Options:
356
357 **-H**
358 suppress writing the field names in a header line
359
360 **-c**
361 use comma separated values (CSV) format, with minimal quoting,
362 instead of the default tab-separated (unquoted, unescaped) format
363
364 **-e**
365 write empty hexadecimal string fields as empty fields instead of
366 as "-1".
367
368 **-n**
369 produce numeric output for fields that normally have symbolic
370 output, such as enctypes and flag names. Also requests output of
371 time stamps as decimal POSIX time_t values.
372
373 **-o** *outfile*
374 write the dump to the specified output file instead of to standard
375 output
376
377 Dump types:
378
379 **alias**
380 principal alias information
381
382 **aliasname**
383 the name of the alias
384 **targetname**
385 the target of the alias
386
387 **keydata**
388 principal encryption key information, including actual key data
389 (which is still encrypted in the master key)
390
391 **name**
392 principal name
393 **keyindex**
394 index of this key in the principal's key list
395 **kvno**
396 key version number
397 **enctype**
398 encryption type
399 **key**
400 key data as a hexadecimal string
401 **salttype**
402 salt type
403 **salt**
404 salt data as a hexadecimal string
405
406 **keyinfo**
407 principal encryption key information (as in **keydata** above),
408 excluding actual key data
409
410 **princ_flags**
411 principal boolean attributes. Flag names print as hexadecimal
412 numbers if the **-n** option is specified, and all flag positions
413 are printed regardless of whether or not they are set. If **-n**
414 is not specified, print all known flag names for each principal,
415 but only print hexadecimal flag names if the corresponding flag is
416 set.
417
418 **name**
419 principal name
420 **flag**
421 flag name
422 **value**
423 boolean value (0 for clear, or 1 for set)
424
425 **princ_lockout**
426 state information used for tracking repeated password failures
427
428 **name**
429 principal name
430 **last_success**
431 time stamp of most recent successful authentication
432 **last_failed**
433 time stamp of most recent failed authentication
434 **fail_count**
435 count of failed attempts
436
437 **princ_meta**
438 principal metadata
439
440 **name**
441 principal name
442 **modby**
443 name of last principal to modify this principal
444 **modtime**
445 timestamp of last modification
446 **lastpwd**
447 timestamp of last password change
448 **policy**
449 policy object name
450 **mkvno**
451 key version number of the master key that encrypts this
452 principal's key data
453 **hist_kvno**
454 key version number of the history key that encrypts the key
455 history data for this principal
456
457 **princ_stringattrs**
458 string attributes (key/value pairs)
459
460 **name**
461 principal name
462 **key**
463 attribute name
464 **value**
465 attribute value
466
467 **princ_tktpolicy**
468 per-principal ticket policy data, including maximum ticket
469 lifetimes
470
471 **name**
472 principal name
473 **expiration**
474 principal expiration date
475 **pw_expiration**
476 password expiration date
477 **max_life**
478 maximum ticket lifetime
479 **max_renew_life**
480 maximum renewable ticket lifetime
481
482 Examples::
483
484 $ kdb5_util tabdump -o keyinfo.txt keyinfo
485 $ cat keyinfo.txt
486 name keyindex kvno enctype salttype salt
487 K/[email protected] 0 1 aes256-cts-hmac-sha384-192 normal -1
488 [email protected] 0 1 aes128-cts-hmac-sha1-96 normal -1
489 [email protected] 0 1 aes128-cts-hmac-sha1-96 normal -1
490 $ sqlite3
491 sqlite> .mode tabs
492 sqlite> .import keyinfo.txt keyinfo
493 sqlite> select * from keyinfo where enctype like 'aes256-%';
494 K/[email protected] 1 1 aes256-cts-hmac-sha384-192 normal -1
495 sqlite> .quit
496 $ awk -F'\t' '$4 ~ /aes256-/ { print }' keyinfo.txt
497 K/[email protected] 1 1 aes256-cts-hmac-sha384-192 normal -1
498
499
500 ENVIRONMENT
501 -----------
502
503 See :ref:`kerberos(7)` for a description of Kerberos environment
504 variables.
505
506
507 SEE ALSO
508 --------
509
510 :ref:`kadmin(1)`, :ref:`kerberos(7)`