doc/admin/admin_commands/kdb5_util.rst

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