KDB5_UTIL(8)

hey bestie 💖 welcome to kdb5_util(8), aka the MIT Kerberos database maintenance utility. She's the one you call when the KDC database needs a little glow-up, a backup, a restore, or a whole master-key situation. No cap.

💖 NAME 💖

kdb5_util — Kerberos database maintenance utility

✨ SYNOPSIS ✨

kdb5_util [-r realm] [-d dbname] [-k mkeytype] [-kv mkeyVNO] [-M
mkeyname] [-m] [-sf stashfilename] [-P password] [-x db_args] command
[command_options]

🦋 DESCRIPTION 🦋

So like, kdb5_util lets an admin do maintenance procedures on the KDC database. You can create databases, destroy them, dump them to ASCII files, and load them back from ASCII files. It can also create a Kerberos master key stash file, or do a live rollover of the master key. Very main character energy, honestly.

When kdb5_util runs, it tries to acquire the master key and open the database. But plot twist: execution continues regardless of whether or not it successfully opens the database, because the database may not exist yet or the stash file may be corrupt. So yeah, she keeps it moving. 💅

Also note: some KDC database modules may not support all kdb5_util commands. Not every module ate the same breakfast, okay?

👑 COMMAND-LINE OPTIONS 👑

• -r realm — specifies the Kerberos realm of the database. That's the realm, bestie.
• -d dbname — specifies the name under which the principal database is stored; by default the database is that listed in kdc.conf. The password policy database and lock files are also derived from this value. So this one is lowkey doing a lot.
• -k mkeytype — specifies the key type of the master key in the database. The default is given by the master_key_type variable in kdc.conf.
• -kv mkeyVNO — Specifies the version number of the master key in the database; the default is 1. Note that 0 is not allowed. Zero? In this economy? No. 🚫
• -M mkeyname — principal name for the master key in the database. If not specified, the name is determined by the master_key_name variable in kdc.conf.
• -m — specifies that the master database password should be read from the keyboard rather than fetched from a file on disk. Typing it out, living dangerously.
• -sf stash_file — specifies the stash filename of the master database password. If not specified, the filename is determined by the key_stash_file variable in kdc.conf.
• -P password — specifies the master database password. Using this option may expose the password to other users on the system via the process list. ⚠️ Bestie, this is giving security risk, be careful.
• -x db_args — specifies database-specific options. See kadmin for supported options.

🌸 COMMANDS 🌸

create

create [-s]

Creates a new database. If the -s option is specified, the stash file is also created. This command fails if the database already exists. If the command is successful, the database is opened just as if it had already existed when the program was first run. It's giving "new phone, who dis?" but for databases. ✨

destroy

destroy [-f]

Destroys the database, first overwriting the disk sectors and then unlinking the files, after prompting the user for confirmation. With the -f argument, does not prompt the user. So -f is the "no thoughts, just destruction" flag. 💀

stash

stash [-f keyfile]

Stores the master principal's keys in a stash file. The -f argument can be used to override the keyfile specified in kdc.conf.

dump

dump [-b7|-r13|-r18] [-verbose] [-mkey_convert] [-new_mkey_file
mkey_file] [-rev] [-recurse] [filename [principals...]]

Dumps the current Kerberos and KADM5 database into an ASCII file. By default, the database is dumped in current format, "kdb5_util load_dump version 7". If filename is not specified, or is the string "-", the dump is sent to standard output.

Options:

• -b7 — causes the dump to be in the Kerberos 5 Beta 7 format ("kdb5_util load_dump version 4"). This was the dump format produced on releases prior to 1.2.2.
• -r13 — causes the dump to be in the Kerberos 5 1.3 format ("kdb5_util load_dump version 5"). This was the dump format produced on releases prior to 1.8.
• -r18 — causes the dump to be in the Kerberos 5 1.8 format ("kdb5_util load_dump version 6"). This was the dump format produced on releases prior to 1.11.
• -verbose — causes the name of each principal and policy to be printed as it is dumped. Chatty queen. 🗣️
• -mkey_convert — prompts for a new master key. This new master key will be used to re-encrypt principal key data in the dumpfile. The principal keys themselves will not be changed.
• -new_mkey_file mkey_file — the filename of a stash file. The master key in this stash file will be used to re-encrypt the key data in the dumpfile. The key data in the database will not be changed.
• -rev — dumps in reverse order. This may recover principals that do not dump normally, in cases where database corruption has occurred. Corruption? Not on my watch. 🙈
• -recurse — causes the dump to walk the database recursively (btree only). This may recover principals that do not dump normally, in cases where database corruption has occurred. In cases of such corruption, this option will probably retrieve more principals than the -rev option will.

Changed in version 1.15: Release 1.15 restored the functionality of the -recurse option.

Changed in version 1.5: The -recurse option ceased working until release 1.15, doing a normal dump instead of a recursive traversal.

load

load [-b7|-r13|-r18] [-hash] [-verbose] [-update] filename

Loads a database dump from the named file into the named database. If no option is given to determine the format of the dump file, the format is detected automatically and handled as appropriate. Unless the -update option is given, load creates a new database containing only the data in the dump file, overwriting the contents of any previously existing database. Note that when using the LDAP KDC database module, the -update flag is required. LDAP said "you WILL use -update," periodt.

Options:

• -b7 — requires the database to be in the Kerberos 5 Beta 7 format ("kdb5_util load_dump version 4"). This was the dump format produced on releases prior to 1.2.2.
• -r13 — requires the database to be in Kerberos 5 1.3 format ("kdb5_util load_dump version 5"). This was the dump format produced on releases prior to 1.8.
• -r18 — requires the database to be in Kerberos 5 1.8 format ("kdb5_util load_dump version 6"). This was the dump format produced on releases prior to 1.11.
• -hash — stores the database in hash format, if using the DB2 database type. If this option is not specified, the database will be stored in btree format. This option is not recommended, as databases stored in hash format are known to corrupt data and lose principals. 🚩 Not recommended, bestie. She said what she said.
• -verbose — causes the name of each principal and policy to be printed as it is dumped.
• -update — records from the dump file are added to or updated in the existing database. Otherwise, a new database is created containing only what is in the dump file and the old one destroyed upon successful completion.

ark

ark [-e enc:salt,...] principal

Adds new random keys to principal at the next available key version number. Keys for the current highest key version number will be preserved. The -e option specifies the list of encryption and salt types to be used for the new keys.

add_mkey

add_mkey [-e etype] [-s]

Adds a new master key to the master key principal, but does not mark it as active. Existing master keys will remain. The -e option specifies the encryption type of the new master key; see Encryption types in kdc.conf for a list of possible values. The -s option stashes the new master key in the stash file, which will be created if it doesn't already exist.

After a new master key is added, it should be propagated to replica servers via a manual or periodic invocation of kprop. Then, the stash files on the replica servers should be updated with the kdb5_util stash command. Once those steps are complete, the key is ready to be marked active with the kdb5_util use_mkey command. It's a whole process, but you got this. 🫶

use_mkey

use_mkey mkeyVNO [time]

Sets the activation time of the master key specified by mkeyVNO. Once a master key becomes active, it will be used to encrypt newly created principal keys. If no time argument is given, the current time is used, causing the specified master key version to become active immediately. The format for time is getdate time string.

After a new master key becomes active, the kdb5_util update_princ_encryption command can be used to update all principal keys to be encrypted in the new master key.

list_mkeys

list_mkeys

List all master keys, from most recent to earliest, in the master key principal. The output will show the kvno, enctype, and salt type for each mkey, similar to the output of kadmin getprinc. A * following an mkey denotes the currently active master key. Star of the show. ⭐

purge_mkeys

purge_mkeys [-f] [-n] [-v]

Delete master keys from the master key principal that are not used to protect any principals. This command can be used to remove old master keys when all principal keys are protected by a newer master key.

• -f — does not prompt for confirmation.
• -n — performs a dry run, showing master keys that would be purged, but not actually purging any keys.
• -v — gives more verbose output.

update_princ_encryption

update_princ_encryption [-f] [-n] [-v] [princ-pattern]

Update all principal records (or only those matching the princ-pattern glob pattern) to re-encrypt the key data using the active database master key, if they are encrypted using a different version, and give a count at the end of the number of principals updated. If the -f option is not given, ask for confirmation before starting to make changes. The -v option causes each principal processed to be listed, with an indication as to whether it needed updating or not. The -n option performs a dry run, only showing the actions which would have been taken.

tabdump

tabdump [-H] [-c] [-e] [-n] [-o outfile] dumptype

Dump selected fields of the database in a tabular format suitable for reporting (e.g., using traditional Unix text processing tools) or importing into relational databases. The data format is tab-separated (default), or optionally comma-separated (CSV), with a fixed number of columns. The output begins with a header line containing field names, unless suppression is requested using the -H option.

The dumptype parameter specifies the name of an output table (see below).

Options:

• -H — suppress writing the field names in a header line
• -c — use comma separated values (CSV) format, with minimal quoting, instead of the default tab-separated (unquoted, unescaped) format
• -e — write empty hexadecimal string fields as empty fields instead of as "-1".

so the last two flags for tabdump, bestie, and then we get into the good part 💖

• -n — numeric mode, periodt. Fields that normally print all symbolic — think enctypes and flag names — come out as numbers instead. and it also asks for time stamps as decimal POSIX time_t values. 🕰️
• -o outfile — writes the dump into outfile instead of spilling it all over standard output. your terminal says thank you 🫶

---

Dump types 💅

okay so tabdump can hand you a whole bunch of different flavours of dump, and each one has its own lil list of fields. here's the entire menu, no cap:

• alias — principal alias information ✨
  • aliasname — the name of the alias
  • targetname — the target of the alias
• keydata — principal encryption key information, and yes, this one includes the actual key data (which is still encrypted in the master key, so breathe 😮‍💨)
  • name — principal name
  • keyindex — index of this key in the principal's key list
  • kvno — key version number
  • enctype — encryption type
  • key — key data as a hexadecimal string
  • salttype — salt type
  • salt — salt data as a hexadecimal string
• keyinfo — principal encryption key information, same as in keydata above, except it leaves out the actual key data. privacy queen 👑
• princ_flags — principal boolean attributes. here's the tea: flag names print as hexadecimal numbers if you passed -n, and all flag positions get printed whether or not they're set. if you did not pass -n, you get every known flag name for each principal, but hexadecimal flag names only show up when that corresponding flag is actually set.
  • name — principal name
  • flag — flag name
  • value — boolean value (0 for clear, or 1 for set)
• princ_lockout — state information used for tracking repeated password failures. the "we see you trying" file 🙈
  • name — principal name
  • last_success — time stamp of most recent successful authentication
  • last_failed — time stamp of most recent failed authentication
  • fail_count — count of failed attempts
• princ_meta — principal metadata 🌸
  • name — principal name
  • modby — name of last principal to modify this principal
  • modtime — timestamp of last modification
  • lastpwd — timestamp of last password change
  • policy — policy object name
  • mkvno — key version number of the master key that encrypts this principal's key data
  • hist_kvno — key version number of the history key that encrypts the key history data for this principal
• princ_stringattrs — string attributes, aka key/value pairs 🎀
  • name — principal name
  • key — attribute name
  • value — attribute value
• princ_tktpolicy — per-principal ticket policy data, including maximum ticket lifetimes ⏳
  • name — principal name
  • expiration — principal expiration date
  • pw_expiration — password expiration date
  • max_life — maximum ticket lifetime
  • max_renew_life — maximum renewable ticket lifetime

---

Examples 🌈

watch her cook:

$ kdb5_util tabdump -o keyinfo.txt keyinfo
$ cat keyinfo.txt
name        keyindex        kvno    enctype salttype        salt
K/M@EXAMPLE.COM     0       1       aes256-cts-hmac-sha384-192      normal  -1
foo@EXAMPLE.COM     0       1       aes128-cts-hmac-sha1-96 normal  -1
bar@EXAMPLE.COM     0       1       aes128-cts-hmac-sha1-96 normal  -1
$ sqlite3
sqlite> .mode tabs
sqlite> .import keyinfo.txt keyinfo
sqlite> select * from keyinfo where enctype like 'aes256-%';
K/M@EXAMPLE.COM     1       1       aes256-cts-hmac-sha384-192      normal  -1
sqlite> .quit
$ awk -F'\t' '$4 ~ /aes256-/ { print }' keyinfo.txt
K/M@EXAMPLE.COM     1       1       aes256-cts-hmac-sha384-192      normal  -1

---

🌿 ENVIRONMENT 🌿

wanna know about the Kerberos environment variables? go read kerberos, bestie — it's all spelled out over there. 🦋

---

👀 SEE ALSO 👀

kadmin, kerberos

---

💜 AUTHOR 💜

MIT

---

📜 COPYRIGHT 📜

1985-2026, MIT

---

and that's the whole page, babes 💖 this was KDB5_UTIL(8), version 1.22.2, and honestly? she ate. now go dump some tables, you icon 👑✨