1KDB5_UTIL(8) MIT Kerberos KDB5_UTIL(8)
2
6 kdb5_util - Kerberos database maintenance utility
7
9 kdb5_util [-r realm] [-d dbname] [-k mkeytype] [-kv mkeyVNO] [-M mkey‐
10 name] [-m] [-sf stashfilename] [-P password] [-x db_args] command [com‐
11 mand_options]
12
14 kdb5_util allows an administrator to perform maintenance procedures on
15 the KDC database. Databases can be created, destroyed, and dumped to
16 or loaded from ASCII files. kdb5_util can create a Kerberos master key
17 stash file or perform live rollover of the master key.
18 When kdb5_util is run, it attempts to acquire the master key and open
20 the database. However, execution continues regardless of whether or
21 not kdb5_util successfully opens the database, because the database may
22 not exist yet or the stash file may be corrupt.
23 Note that some KDC database modules may not support all kdb5_util com‐
25 mands.
26
28 -r realm
29 specifies the Kerberos realm of the database.
30 -d dbname
32 specifies the name under which the principal database is stored;
33 by default the database is that listed in kdc.conf. The pass‐
34 word policy database and lock files are also derived from this
35 value.
36 -k mkeytype
38 specifies the key type of the master key in the database. The
39 default is given by the master_key_type variable in kdc.conf.
40 -kv mkeyVNO
42 Specifies the version number of the master key in the database;
43 the default is 1. Note that 0 is not allowed.
44 -M mkeyname
46 principal name for the master key in the database. If not spec‐
47 ified, the name is determined by the master_key_name variable in
48 kdc.conf.
49 -m specifies that the master database password should be read from
51 the keyboard rather than fetched from a file on disk.
52 -sf stash_file
54 specifies the stash filename of the master database password.
55 If not specified, the filename is determined by the
56 key_stash_file variable in kdc.conf.
57 -P password
59 specifies the master database password. Using this option may
60 expose the password to other users on the system via the process
61 list.
62 -x db_args
64 specifies database-specific options. See kadmin for supported
65 options.
66
68 create
69 create [-s]
70 Creates a new database. If the -s option is specified, the stash file
72 is also created. This command fails if the database already exists.
73 If the command is successful, the database is opened just as if it had
74 already existed when the program was first run.
75 destroy
77 destroy [-f]
78 Destroys the database, first overwriting the disk sectors and then un‐
80 linking the files, after prompting the user for confirmation. With the
81 -f argument, does not prompt the user.
82 stash
84 stash [-f keyfile]
85 Stores the master principal's keys in a stash file. The -f argument
87 can be used to override the keyfile specified in kdc.conf.
88 dump
90 dump [-b7|-r13|-r18] [-verbose] [-mkey_convert] [-new_mkey_file
91 mkey_file] [-rev] [-recurse] [filename [principals...]]
92 Dumps the current Kerberos and KADM5 database into an ASCII file. By
94 default, the database is dumped in current format, "kdb5_util load_dump
95 version 7". If filename is not specified, or is the string "-", the
96 dump is sent to standard output. Options:
97 -b7 causes the dump to be in the Kerberos 5 Beta 7 format
99 ("kdb5_util load_dump version 4"). This was the dump format
100 produced on releases prior to 1.2.2.
101 -r13 causes the dump to be in the Kerberos 5 1.3 format ("kdb5_util
103 load_dump version 5"). This was the dump format produced on re‐
104 leases prior to 1.8.
105 -r18 causes the dump to be in the Kerberos 5 1.8 format ("kdb5_util
107 load_dump version 6"). This was the dump format produced on re‐
108 leases prior to 1.11.
109 -verbose
111 causes the name of each principal and policy to be printed as it
112 is dumped.
113 -mkey_convert
115 prompts for a new master key. This new master key will be used
116 to re-encrypt principal key data in the dumpfile. The principal
117 keys themselves will not be changed.
118 -new_mkey_file mkey_file
120 the filename of a stash file. The master key in this stash file
121 will be used to re-encrypt the key data in the dumpfile. The
122 key data in the database will not be changed.
123 -rev dumps in reverse order. This may recover principals that do not
125 dump normally, in cases where database corruption has occurred.
126 -recurse
128 causes the dump to walk the database recursively (btree only).
129 This may recover principals that do not dump normally, in cases
130 where database corruption has occurred. In cases of such cor‐
131 ruption, this option will probably retrieve more principals than
132 the -rev option will.
133 Changed in version 1.15: Release 1.15 restored the functionality
135 of the -recurse option.
136 Changed in version 1.5: The -recurse option ceased working until
139 release 1.15, doing a normal dump instead of a recursive traver‐
140 sal.
141 load
144 load [-b7|-r13|-r18] [-hash] [-verbose] [-update] filename
145 Loads a database dump from the named file into the named database. If
147 no option is given to determine the format of the dump file, the format
148 is detected automatically and handled as appropriate. Unless the -up‐
149 date option is given, load creates a new database containing only the
150 data in the dump file, overwriting the contents of any previously ex‐
151 isting database. Note that when using the LDAP KDC database module,
152 the -update flag is required.
153 Options:
155 -b7 requires the database to be in the Kerberos 5 Beta 7 format
157 ("kdb5_util load_dump version 4"). This was the dump format
158 produced on releases prior to 1.2.2.
159 -r13 requires the database to be in Kerberos 5 1.3 format ("kdb5_util
161 load_dump version 5"). This was the dump format produced on re‐
162 leases prior to 1.8.
163 -r18 requires the database to be in Kerberos 5 1.8 format ("kdb5_util
165 load_dump version 6"). This was the dump format produced on re‐
166 leases prior to 1.11.
167 -hash stores the database in hash format, if using the DB2 database
169 type. If this option is not specified, the database will be
170 stored in btree format. This option is not recommended, as
171 databases stored in hash format are known to corrupt data and
172 lose principals.
173 -verbose
175 causes the name of each principal and policy to be printed as it
176 is dumped.
177 -update
179 records from the dump file are added to or updated in the exist‐
180 ing database. Otherwise, a new database is created containing
181 only what is in the dump file and the old one destroyed upon
182 successful completion.
183 ark
185 ark [-e enc:salt,...] principal
186 Adds new random keys to principal at the next available key version
188 number. Keys for the current highest key version number will be pre‐
189 served. The -e option specifies the list of encryption and salt types
190 to be used for the new keys.
191 add_mkey
193 add_mkey [-e etype] [-s]
194 Adds a new master key to the master key principal, but does not mark it
196 as active. Existing master keys will remain. The -e option specifies
197 the encryption type of the new master key; see Encryption types in
198 kdc.conf for a list of possible values. The -s option stashes the new
199 master key in the stash file, which will be created if it doesn't al‐
200 ready exist.
201 After a new master key is added, it should be propagated to replica
203 servers via a manual or periodic invocation of kprop. Then, the stash
204 files on the replica servers should be updated with the kdb5_util stash
205 command. Once those steps are complete, the key is ready to be marked
206 active with the kdb5_util use_mkey command.
207 use_mkey
209 use_mkey mkeyVNO [time]
210 Sets the activation time of the master key specified by mkeyVNO. Once
212 a master key becomes active, it will be used to encrypt newly created
213 principal keys. If no time argument is given, the current time is
214 used, causing the specified master key version to become active immedi‐
215 ately. The format for time is getdate time string.
216 After a new master key becomes active, the kdb5_util update_princ_en‐
218 cryption command can be used to update all principal keys to be en‐
219 crypted in the new master key.
220 list_mkeys
222 list_mkeys
223 List all master keys, from most recent to earliest, in the master key
225 principal. The output will show the kvno, enctype, and salt type for
226 each mkey, similar to the output of kadmin getprinc. A * following an
227 mkey denotes the currently active master key.
228 purge_mkeys
230 purge_mkeys [-f] [-n] [-v]
231 Delete master keys from the master key principal that are not used to
233 protect any principals. This command can be used to remove old master
234 keys all principal keys are protected by a newer master key.
235 -f does not prompt for confirmation.
237 -n performs a dry run, showing master keys that would be purged,
239 but not actually purging any keys.
240 -v gives more verbose output.
242 update_princ_encryption
244 update_princ_encryption [-f] [-n] [-v] [princ-pattern]
245 Update all principal records (or only those matching the princ-pattern
247 glob pattern) to re-encrypt the key data using the active database mas‐
248 ter key, if they are encrypted using a different version, and give a
249 count at the end of the number of principals updated. If the -f option
250 is not given, ask for confirmation before starting to make changes.
251 The -v option causes each principal processed to be listed, with an in‐
252 dication as to whether it needed updating or not. The -n option per‐
253 forms a dry run, only showing the actions which would have been taken.
254 tabdump
256 tabdump [-H] [-c] [-e] [-n] [-o outfile] dumptype
257 Dump selected fields of the database in a tabular format suitable for
259 reporting (e.g., using traditional Unix text processing tools) or im‐
260 porting into relational databases. The data format is tab-separated
261 (default), or optionally comma-separated (CSV), with a fixed number of
262 columns. The output begins with a header line containing field names,
263 unless suppression is requested using the -H option.
264 The dumptype parameter specifies the name of an output table (see be‐
266 low).
267 Options:
269 -H suppress writing the field names in a header line
271 -c use comma separated values (CSV) format, with minimal quoting,
273 instead of the default tab-separated (unquoted, unescaped) for‐
274 mat
275 -e write empty hexadecimal string fields as empty fields instead of
277 as "-1".
278 -n produce numeric output for fields that normally have symbolic
280 output, such as enctypes and flag names. Also requests output
281 of time stamps as decimal POSIX time_t values.
282 -o outfile
284 write the dump to the specified output file instead of to stan‐
285 dard output
286 Dump types:
288 keydata
290 principal encryption key information, including actual key data
291 (which is still encrypted in the master key)
292 name principal name
294 keyindex
296 index of this key in the principal's key list
297 kvno key version number
299 enctype
301 encryption type
302 key key data as a hexadecimal string
304 salttype
306 salt type
307 salt salt data as a hexadecimal string
309 keyinfo
311 principal encryption key information (as in keydata above), ex‐
312 cluding actual key data
313 princ_flags
315 principal boolean attributes. Flag names print as hexadecimal
316 numbers if the -n option is specified, and all flag positions
317 are printed regardless of whether or not they are set. If -n is
318 not specified, print all known flag names for each principal,
319 but only print hexadecimal flag names if the corresponding flag
320 is set.
321 name principal name
323 flag flag name
325 value boolean value (0 for clear, or 1 for set)
327 princ_lockout
329 state information used for tracking repeated password failures
330 name principal name
332 last_success
334 time stamp of most recent successful authentication
335 last_failed
337 time stamp of most recent failed authentication
338 fail_count
340 count of failed attempts
341 princ_meta
343 principal metadata
344 name principal name
346 modby name of last principal to modify this principal
348 modtime
350 timestamp of last modification
351 lastpwd
353 timestamp of last password change
354 policy policy object name
356 mkvno key version number of the master key that encrypts this
358 principal's key data
359 hist_kvno
361 key version number of the history key that encrypts the
362 key history data for this principal
363 princ_stringattrs
365 string attributes (key/value pairs)
366 name principal name
368 key attribute name
370 value attribute value
372 princ_tktpolicy
374 per-principal ticket policy data, including maximum ticket life‐
375 times
376 name principal name
378 expiration
380 principal expiration date
381 pw_expiration
383 password expiration date
384 max_life
386 maximum ticket lifetime
387 max_renew_life
389 maximum renewable ticket lifetime
390 Examples:
392 $ kdb5_util tabdump -o keyinfo.txt keyinfo
394 $ cat keyinfo.txt
395 name keyindex kvno enctype salttype salt
396 K/M@EXAMPLE.COM 0 1 aes256-cts-hmac-sha384-192 normal -1
397 foo@EXAMPLE.COM 0 1 aes128-cts-hmac-sha1-96 normal -1
398 bar@EXAMPLE.COM 0 1 aes128-cts-hmac-sha1-96 normal -1
399 $ sqlite3
400 sqlite> .mode tabs
401 sqlite> .import keyinfo.txt keyinfo
402 sqlite> select * from keyinfo where enctype like 'aes256-%';
403 K/M@EXAMPLE.COM 1 1 aes256-cts-hmac-sha384-192 normal -1
404 sqlite> .quit
405 $ awk -F'\t' '$4 ~ /aes256-/ { print }' keyinfo.txt
406 K/M@EXAMPLE.COM 1 1 aes256-cts-hmac-sha384-192 normal -1
407
409 See kerberos for a description of Kerberos environment variables.
410
412 kadmin, kerberos
413
415 MIT
416
418 1985-2023, MIT
4191.21.2 KDB5_UTIL(8)