| 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)` |