1.. _kdb5_util(8): 2 3kdb5_util 4========= 5 6SYNOPSIS 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 25DESCRIPTION 26----------- 27 28kdb5_util allows an administrator to perform maintenance procedures on 29the KDC database. Databases can be created, destroyed, and dumped to 30or loaded from ASCII files. kdb5_util can create a Kerberos master 31key stash file or perform live rollover of the master key. 32 33When kdb5_util is run, it attempts to acquire the master key and open 34the database. However, execution continues regardless of whether or 35not kdb5_util successfully opens the database, because the database 36may not exist yet or the stash file may be corrupt. 37 38Note that some KDC database modules may not support all kdb5_util 39commands. 40 41 42COMMAND-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 91COMMANDS 92-------- 93 94create 95~~~~~~ 96 97.. _kdb5_util_create: 98 99 **create** [**-s**] 100 101Creates a new database. If the **-s** option is specified, the stash 102file is also created. This command fails if the database already 103exists. If the command is successful, the database is opened just as 104if it had already existed when the program was first run. 105 106.. _kdb5_util_create_end: 107 108destroy 109~~~~~~~ 110 111.. _kdb5_util_destroy: 112 113 **destroy** [**-f**] 114 115Destroys the database, first overwriting the disk sectors and then 116unlinking the files, after prompting the user for confirmation. With 117the **-f** argument, does not prompt the user. 118 119.. _kdb5_util_destroy_end: 120 121stash 122~~~~~ 123 124.. _kdb5_util_stash: 125 126 **stash** [**-f** *keyfile*] 127 128Stores the master principal's keys in a stash file. The **-f** 129argument can be used to override the *keyfile* specified in 130:ref:`kdc.conf(5)`. 131 132.. _kdb5_util_stash_end: 133 134dump 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 144Dumps the current Kerberos and KADM5 database into an ASCII file. By 145default, the database is dumped in current format, "kdb5_util 146load_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 199load 200~~~~ 201 202.. _kdb5_util_load: 203 204 **load** [**-b7**\|\ **-r13**\|\ **-r18**] [**-hash**] 205 [**-verbose**] [**-update**] *filename* 206 207Loads a database dump from the named file into the named database. If 208no option is given to determine the format of the dump file, the 209format is detected automatically and handled as appropriate. Unless 210the **-update** option is given, **load** creates a new database 211containing only the data in the dump file, overwriting the contents of 212any previously existing database. Note that when using the LDAP KDC 213database module, the **-update** flag is required. 214 215Options: 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 251ark 252~~~ 253 254 **ark** [**-e** *enc*:*salt*,...] *principal* 255 256Adds new random keys to *principal* at the next available key version 257number. Keys for the current highest key version number will be 258preserved. The **-e** option specifies the list of encryption and 259salt types to be used for the new keys. 260 261add_mkey 262~~~~~~~~ 263 264 **add_mkey** [**-e** *etype*] [**-s**] 265 266Adds a new master key to the master key principal, but does not mark 267it as active. Existing master keys will remain. The **-e** option 268specifies the encryption type of the new master key; see 269:ref:`Encryption_types` in :ref:`kdc.conf(5)` for a list of possible 270values. The **-s** option stashes the new master key in the stash 271file, which will be created if it doesn't already exist. 272 273After a new master key is added, it should be propagated to replica 274servers via a manual or periodic invocation of :ref:`kprop(8)`. Then, 275the stash files on the replica servers should be updated with the 276kdb5_util **stash** command. Once those steps are complete, the key 277is ready to be marked active with the kdb5_util **use_mkey** command. 278 279use_mkey 280~~~~~~~~ 281 282 **use_mkey** *mkeyVNO* [*time*] 283 284Sets the activation time of the master key specified by *mkeyVNO*. 285Once a master key becomes active, it will be used to encrypt newly 286created principal keys. If no *time* argument is given, the current 287time is used, causing the specified master key version to become 288active immediately. The format for *time* is :ref:`getdate` string. 289 290After a new master key becomes active, the kdb5_util 291**update_princ_encryption** command can be used to update all 292principal keys to be encrypted in the new master key. 293 294list_mkeys 295~~~~~~~~~~ 296 297 **list_mkeys** 298 299List all master keys, from most recent to earliest, in the master key 300principal. The output will show the kvno, enctype, and salt type for 301each mkey, similar to the output of :ref:`kadmin(1)` **getprinc**. A 302``*`` following an mkey denotes the currently active master key. 303 304purge_mkeys 305~~~~~~~~~~~ 306 307 **purge_mkeys** [**-f**] [**-n**] [**-v**] 308 309Delete master keys from the master key principal that are not used to 310protect any principals. This command can be used to remove old master 311keys 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 323update_princ_encryption 324~~~~~~~~~~~~~~~~~~~~~~~ 325 326 **update_princ_encryption** [**-f**] [**-n**] [**-v**] 327 [*princ-pattern*] 328 329Update all principal records (or only those matching the 330*princ-pattern* glob pattern) to re-encrypt the key data using the 331active database master key, if they are encrypted using a different 332version, and give a count at the end of the number of principals 333updated. If the **-f** option is not given, ask for confirmation 334before starting to make changes. The **-v** option causes each 335principal processed to be listed, with an indication as to whether it 336needed updating or not. The **-n** option performs a dry run, only 337showing the actions which would have been taken. 338 339tabdump 340~~~~~~~ 341 342 **tabdump** [**-H**] [**-c**] [**-e**] [**-n**] [**-o** *outfile*] 343 *dumptype* 344 345Dump selected fields of the database in a tabular format suitable for 346reporting (e.g., using traditional Unix text processing tools) or 347importing into relational databases. The data format is tab-separated 348(default), or optionally comma-separated (CSV), with a fixed number of 349columns. The output begins with a header line containing field names, 350unless suppression is requested using the **-H** option. 351 352The *dumptype* parameter specifies the name of an output table (see 353below). 354 355Options: 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 377Dump types: 378 379**keydata** 380 principal encryption key information, including actual key data 381 (which is still encrypted in the master key) 382 383 **name** 384 principal name 385 **keyindex** 386 index of this key in the principal's key list 387 **kvno** 388 key version number 389 **enctype** 390 encryption type 391 **key** 392 key data as a hexadecimal string 393 **salttype** 394 salt type 395 **salt** 396 salt data as a hexadecimal string 397 398**keyinfo** 399 principal encryption key information (as in **keydata** above), 400 excluding actual key data 401 402**princ_flags** 403 principal boolean attributes. Flag names print as hexadecimal 404 numbers if the **-n** option is specified, and all flag positions 405 are printed regardless of whether or not they are set. If **-n** 406 is not specified, print all known flag names for each principal, 407 but only print hexadecimal flag names if the corresponding flag is 408 set. 409 410 **name** 411 principal name 412 **flag** 413 flag name 414 **value** 415 boolean value (0 for clear, or 1 for set) 416 417**princ_lockout** 418 state information used for tracking repeated password failures 419 420 **name** 421 principal name 422 **last_success** 423 time stamp of most recent successful authentication 424 **last_failed** 425 time stamp of most recent failed authentication 426 **fail_count** 427 count of failed attempts 428 429**princ_meta** 430 principal metadata 431 432 **name** 433 principal name 434 **modby** 435 name of last principal to modify this principal 436 **modtime** 437 timestamp of last modification 438 **lastpwd** 439 timestamp of last password change 440 **policy** 441 policy object name 442 **mkvno** 443 key version number of the master key that encrypts this 444 principal's key data 445 **hist_kvno** 446 key version number of the history key that encrypts the key 447 history data for this principal 448 449**princ_stringattrs** 450 string attributes (key/value pairs) 451 452 **name** 453 principal name 454 **key** 455 attribute name 456 **value** 457 attribute value 458 459**princ_tktpolicy** 460 per-principal ticket policy data, including maximum ticket 461 lifetimes 462 463 **name** 464 principal name 465 **expiration** 466 principal expiration date 467 **pw_expiration** 468 password expiration date 469 **max_life** 470 maximum ticket lifetime 471 **max_renew_life** 472 maximum renewable ticket lifetime 473 474Examples:: 475 476 $ kdb5_util tabdump -o keyinfo.txt keyinfo 477 $ cat keyinfo.txt 478 name keyindex kvno enctype salttype salt 479 K/M@EXAMPLE.COM 0 1 aes256-cts-hmac-sha384-192 normal -1 480 foo@EXAMPLE.COM 0 1 aes128-cts-hmac-sha1-96 normal -1 481 bar@EXAMPLE.COM 0 1 aes128-cts-hmac-sha1-96 normal -1 482 $ sqlite3 483 sqlite> .mode tabs 484 sqlite> .import keyinfo.txt keyinfo 485 sqlite> select * from keyinfo where enctype like 'aes256-%'; 486 K/M@EXAMPLE.COM 1 1 aes256-cts-hmac-sha384-192 normal -1 487 sqlite> .quit 488 $ awk -F'\t' '$4 ~ /aes256-/ { print }' keyinfo.txt 489 K/M@EXAMPLE.COM 1 1 aes256-cts-hmac-sha384-192 normal -1 490 491 492ENVIRONMENT 493----------- 494 495See :ref:`kerberos(7)` for a description of Kerberos environment 496variables. 497 498 499SEE ALSO 500-------- 501 502:ref:`kadmin(1)`, :ref:`kerberos(7)` 503