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] [-M mkeyname] [-kv
10 mkeyVNO] [-sf stashfilename] [-m] command [command_options]
11
13 kdb5_util allows an administrator to perform maintenance procedures on
14 the KDC database. Databases can be created, destroyed, and dumped to
15 or loaded from ASCII files. kdb5_util can create a Kerberos master key
16 stash file or perform live rollover of the master key.
17 When kdb5_util is run, it attempts to acquire the master key and open
19 the database. However, execution continues regardless of whether or
20 not kdb5_util successfully opens the database, because the database may
21 not exist yet or the stash file may be corrupt.
22 Note that some KDC database modules may not support all kdb5_util com‐
24 mands.
25
27 -r realm
28 specifies the Kerberos realm of the database.
29 -d dbname
31 specifies the name under which the principal database is stored;
32 by default the database is that listed in kdc.conf(5). The
33 password policy database and lock files are also derived from
34 this value.
35 -k mkeytype
37 specifies the key type of the master key in the database. The
38 default is given by the master_key_type variable in kdc.conf(5).
39 -kv mkeyVNO
41 Specifies the version number of the master key in the database;
42 the default is 1. Note that 0 is not allowed.
43 -M mkeyname
45 principal name for the master key in the database. If not spec‐
46 ified, the name is determined by the master_key_name variable in
47 kdc.conf(5).
48 -m specifies that the master database password should be read from
50 the keyboard rather than fetched from a file on disk.
51 -sf stash_file
53 specifies the stash filename of the master database password.
54 If not specified, the filename is determined by the
55 key_stash_file variable in kdc.conf(5).
56 -P password
58 specifies the master database password. Using this option may
59 expose the password to other users on the system via the process
60 list.
61
63 create
64 create [-s]
65 Creates a new database. If the -s option is specified, the stash file
67 is also created. This command fails if the database already exists.
68 If the command is successful, the database is opened just as if it had
69 already existed when the program was first run.
70 destroy
72 destroy [-f]
73 Destroys the database, first overwriting the disk sectors and then
75 unlinking the files, after prompting the user for confirmation. With
76 the -f argument, does not prompt the user.
77 stash
79 stash [-f keyfile]
80 Stores the master principal's keys in a stash file. The -f argument
82 can be used to override the keyfile specified in kdc.conf(5).
83 dump
85 dump [-b7|-ov|-r13] [-verbose] [-mkey_convert] [-new_mkey_file
86 mkey_file] [-rev] [-recurse] [filename [principals...]]
87 Dumps the current Kerberos and KADM5 database into an ASCII file. By
89 default, the database is dumped in current format, "kdb5_util load_dump
90 version 7". If filename is not specified, or is the string "-", the
91 dump is sent to standard output. Options:
92 -b7 causes the dump to be in the Kerberos 5 Beta 7 format
94 ("kdb5_util load_dump version 4"). This was the dump format
95 produced on releases prior to 1.2.2.
96 -ov causes the dump to be in "ovsec_adm_export" format.
98 -r13 causes the dump to be in the Kerberos 5 1.3 format ("kdb5_util
100 load_dump version 5"). This was the dump format produced on
101 releases prior to 1.8.
102 -r18 causes the dump to be in the Kerberos 5 1.8 format ("kdb5_util
104 load_dump version 6"). This was the dump format produced on
105 releases prior to 1.11.
106 -verbose
108 causes the name of each principal and policy to be printed as it
109 is dumped.
110 -mkey_convert
112 prompts for a new master key. This new master key will be used
113 to re-encrypt principal key data in the dumpfile. The principal
114 keys themselves will not be changed.
115 -new_mkey_file mkey_file
117 the filename of a stash file. The master key in this stash file
118 will be used to re-encrypt the key data in the dumpfile. The
119 key data in the database will not be changed.
120 -rev dumps in reverse order. This may recover principals that do not
122 dump normally, in cases where database corruption has occurred.
123 -recurse
125 causes the dump to walk the database recursively (btree only).
126 This may recover principals that do not dump normally, in cases
127 where database corruption has occurred. In cases of such cor‐
128 ruption, this option will probably retrieve more principals than
129 the -rev option will.
130 Changed in version 1.15: Release 1.15 restored the functionality
132 of the -recurse option.
133 Changed in version 1.5: The -recurse option ceased working until
136 release 1.15, doing a normal dump instead of a recursive traver‐
137 sal.
138 load
141 load [-b7|-ov|-r13] [-hash] [-verbose] [-update] filename [dbname]
142 Loads a database dump from the named file into the named database. If
144 no option is given to determine the format of the dump file, the format
145 is detected automatically and handled as appropriate. Unless the
146 -update option is given, load creates a new database containing only
147 the data in the dump file, overwriting the contents of any previously
148 existing database. Note that when using the LDAP KDC database module,
149 the -update flag is required.
150 Options:
152 -b7 requires the database to be in the Kerberos 5 Beta 7 format
154 ("kdb5_util load_dump version 4"). This was the dump format
155 produced on releases prior to 1.2.2.
156 -ov requires the database to be in "ovsec_adm_import" format. Must
158 be used with the -update option.
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
162 releases 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
166 releases prior to 1.11.
167 -hash requires the database to be stored as a hash. If this option is
169 not specified, the database will be stored as a btree. This
170 option is not recommended, as databases stored in hash format
171 are known to corrupt data and lose principals.
172 -verbose
174 causes the name of each principal and policy to be printed as it
175 is dumped.
176 -update
178 records from the dump file are added to or updated in the exist‐
179 ing database. Otherwise, a new database is created containing
180 only what is in the dump file and the old one destroyed upon
181 successful completion.
182 If specified, dbname overrides the value specified on the command line
184 or the default.
185 ark
187 ark [-e enc:salt,...] principal
188 Adds new random keys to principal at the next available key version
190 number. Keys for the current highest key version number will be pre‐
191 served. The -e option specifies the list of encryption and salt types
192 to be used for the new keys.
193 add_mkey
195 add_mkey [-e etype] [-s]
196 Adds a new master key to the master key principal, but does not mark it
198 as active. Existing master keys will remain. The -e option specifies
199 the encryption type of the new master key; see Encryption_types in
200 kdc.conf(5) for a list of possible values. The -s option stashes the
201 new master key in the stash file, which will be created if it doesn't
202 already exist.
203 After a new master key is added, it should be propagated to slave
205 servers via a manual or periodic invocation of kprop(8). Then, the
206 stash files on the slave servers should be updated with the kdb5_util
207 stash command. Once those steps are complete, the key is ready to be
208 marked active with the kdb5_util use_mkey command.
209 use_mkey
211 use_mkey mkeyVNO [time]
212 Sets the activation time of the master key specified by mkeyVNO. Once
214 a master key becomes active, it will be used to encrypt newly created
215 principal keys. If no time argument is given, the current time is
216 used, causing the specified master key version to become active immedi‐
217 ately. The format for time is getdate string.
218 After a new master key becomes active, the kdb5_util
220 update_princ_encryption command can be used to update all principal
221 keys to be encrypted in the new master key.
222 list_mkeys
224 list_mkeys
225 List all master keys, from most recent to earliest, in the master key
227 principal. The output will show the kvno, enctype, and salt type for
228 each mkey, similar to the output of kadmin(1) getprinc. A * following
229 an mkey denotes the currently active master key.
230 purge_mkeys
232 purge_mkeys [-f] [-n] [-v]
233 Delete master keys from the master key principal that are not used to
235 protect any principals. This command can be used to remove old master
236 keys all principal keys are protected by a newer master key.
237 -f does not prompt for confirmation.
239 -n performs a dry run, showing master keys that would be purged,
241 but not actually purging any keys.
242 -v gives more verbose output.
244 update_princ_encryption
246 update_princ_encryption [-f] [-n] [-v] [princ-pattern]
247 Update all principal records (or only those matching the princ-pattern
249 glob pattern) to re-encrypt the key data using the active database mas‐
250 ter key, if they are encrypted using a different version, and give a
251 count at the end of the number of principals updated. If the -f option
252 is not given, ask for confirmation before starting to make changes.
253 The -v option causes each principal processed to be listed, with an
254 indication as to whether it needed updating or not. The -n option per‐
255 forms a dry run, only showing the actions which would have been taken.
256 tabdump
258 tabdump [-H] [-c] [-e] [-n] [-o outfile] dumptype
259 Dump selected fields of the database in a tabular format suitable for
261 reporting (e.g., using traditional Unix text processing tools) or
262 importing into relational databases. The data format is tab-separated
263 (default), or optionally comma-separated (CSV), with a fixed number of
264 columns. The output begins with a header line containing field names,
265 unless suppression is requested using the -H option.
266 The dumptype parameter specifies the name of an output table (see
268 below).
269 Options:
271 -H suppress writing the field names in a header line
273 -c use comma separated values (CSV) format, with minimal quoting,
275 instead of the default tab-separated (unquoted, unescaped) for‐
276 mat
277 -e write empty hexadecimal string fields as empty fields instead of
279 as "-1".
280 -n produce numeric output for fields that normally have symbolic
282 output, such as enctypes and flag names. Also requests output
283 of time stamps as decimal POSIX time_t values.
284 -o outfile
286 write the dump to the specified output file instead of to stan‐
287 dard output
288 Dump types:
290 keydata
292 principal encryption key information, including actual key data
293 (which is still encrypted in the master key)
294 name principal name
296 keyindex
298 index of this key in the principal's key list
299 kvno key version number
301 enctype
303 encryption type
304 key key data as a hexadecimal string
306 salttype
308 salt type
309 salt salt data as a hexadecimal string
311 keyinfo
313 principal encryption key information (as in keydata above),
314 excluding actual key data
315 princ_flags
317 principal boolean attributes. Flag names print as hexadecimal
318 numbers if the -n option is specified, and all flag positions
319 are printed regardless of whether or not they are set. If -n is
320 not specified, print all known flag names for each principal,
321 but only print hexadecimal flag names if the corresponding flag
322 is set.
323 name principal name
325 flag flag name
327 value boolean value (0 for clear, or 1 for set)
329 princ_lockout
331 state information used for tracking repeated password failures
332 name principal name
334 last_success
336 time stamp of most recent successful authentication
337 last_failed
339 time stamp of most recent failed authentication
340 fail_count
342 count of failed attempts
343 princ_meta
345 principal metadata
346 name principal name
348 modby name of last principal to modify this principal
350 modtime
352 timestamp of last modification
353 lastpwd
355 timestamp of last password change
356 policy policy object name
358 mkvno key version number of the master key that encrypts this
360 principal's key data
361 hist_kvno
363 key version number of the history key that encrypts the
364 key history data for this principal
365 princ_stringattrs
367 string attributes (key/value pairs)
368 name principal name
370 key attribute name
372 value attribute value
374 princ_tktpolicy
376 per-principal ticket policy data, including maximum ticket life‐
377 times
378 name principal name
380 expiration
382 principal expiration date
383 pw_expiration
385 password expiration date
386 max_life
388 maximum ticket lifetime
389 max_renew_life
391 maximum renewable ticket lifetime
392 Examples:
394 $ kdb5_util tabdump -o keyinfo.txt keyinfo
396 $ cat keyinfo.txt
397 name keyindex kvno enctype salttype salt
398 foo@EXAMPLE.COM 0 1 aes128-cts-hmac-sha1-96 normal -1
399 bar@EXAMPLE.COM 0 1 aes128-cts-hmac-sha1-96 normal -1
400 bar@EXAMPLE.COM 1 1 des-cbc-crc normal -1
401 $ sqlite3
402 sqlite> .mode tabs
403 sqlite> .import keyinfo.txt keyinfo
404 sqlite> select * from keyinfo where enctype like 'des-cbc-%';
405 bar@EXAMPLE.COM 1 1 des-cbc-crc normal -1
406 sqlite> .quit
407 $ awk -F'\t' '$4 ~ /des-cbc-/ { print }' keyinfo.txt
408 bar@EXAMPLE.COM 1 1 des-cbc-crc normal -1
409
411 kadmin(1)
412
414 MIT
415
417 1985-2018, MIT
4181.16.1 KDB5_UTIL(8)