1KDB5_UTIL(8) System Manager's Manual KDB5_UTIL(8)
2
6 kdb5_util - Kerberos database maintenance utility
7
9 kdb5_util [-r realm] [-d dbname] [-k mkeytype] [-M mkeyname]
10 [-kv mkeyVNO] [-sf stashfilename] [-m] command [command_options]
11
13 kdb5_util allows an administrator to perform low-level maintenance pro‐
14 cedures on the Kerberos and KADM5 database. Databases can be created,
15 destroyed, and dumped to and loaded from ASCII files. Additionally,
16 kdb5_util can create a Kerberos master key stash file. kdb5_util sub‐
17 sumes the functionality of and makes obsolete the previous database
18 maintenance programs kdb5_create, kdb5_edit, kdb5_destroy, and
19 kdb5_stash.
20 When kdb5_util is run, it attempts to acquire the master key and open
22 the database. However, execution continues regardless of whether or
23 not kdb5_util successfully opens the database, because the database may
24 not exist yet or the stash file may be corrupt.
25 Note that some KDB plugins may not support all kdb5_util commands.
27
29 -r realm
30 specifies the Kerberos realm of the database; by default the
31 realm returned by krb5_default_local_realm(3) is used.
32 -d dbname
34 specifies the name under which the principal database is stored;
35 by default the database is that listed in kdc.conf(5). The
36 KADM5 policy database and lock file are also derived from this
37 value.
38 -k mkeytype
40 specifies the key type of the master key in the database; the
41 default is that given in kdc.conf.
42 -kv mkeyVNO
44 Specifies the version number of the master key in the database;
45 the default is 1. Note that 0 is not allowed.
46 -M mkeyname
48 principal name for the master key in the database; the default
49 is that given in kdc.conf.
50 -m specifies that the master database password should be read from
52 the TTY rather than fetched from a file on disk.
53 -sf stash_file
55 specifies the stash file of the master database password.
56 -P password
58 specifies the master database password. This option is not rec‐
59 ommended.
60
62 create [-s]
63 Creates a new database. If the -s option is specified, the
64 stash file is also created. This command fails if the database
65 already exists. If the command is successful, the database is
66 opened just as if it had already existed when the program was
67 first run.
68 destroy [-f]
70 Destroys the database, first overwriting the disk sectors and
71 then unlinking the files, after prompting the user for confirma‐
72 tion. With the -f argument, does not prompt the user.
73 stash [-f keyfile]
75 Stores the master principal's keys in a stash file. The -f
76 argument can be used to override the keyfile specified at
77 startup.
78 dump [-old|-b6|-b7|-ov|-r13]
80 [-verbose] [-mkey_convert] [-new_mkey_file mkey_file] [-rev]
81 [-recurse] [filename [principals...]]
82 Dumps the current Kerberos and KADM5 database into an ASCII
83 file. By default, the database is dumped in current format,
84 "kdb5_util load_dump version 6". If filename is not specified,
85 or is the string "-", the dump is sent to standard output.
86 Options:
87 -old causes the dump to be in the Kerberos 5 Beta 5 and ear‐
89 lier dump format ("kdb5_edit load_dump version 2.0").
90 -b6 causes the dump to be in the Kerberos 5 Beta 6 format
92 ("kdb5_edit load_dump version 3.0").
93 -b7 causes the dump to be in the Kerberos 5 Beta 7 format
95 ("kdb5_util load_dump version 4"). This was the dump
96 format produced on releases prior to 1.2.2.
97 -ov causes the dump to be in ovsec_adm_export format.
99 -r13 causes the dump to be in the Kerberos 5 1.3 format
101 ("kdb5_util load_dump version 5"). This was the dump
102 format produced on releases prior to 1.8.
103 -verbose
105 causes the name of each principal and policy to be
106 printed as it is dumped.
107 -mkey_convert
109 prompts for a new master key. This new master key will
110 be used to re-encrypt the key data in the dumpfile. The
111 key data in the database will not be changed.
112 -new_mkey_file mkey_file
114 the filename of a stash file. The master key in this
115 stash file will be used to re-encrypt the key data in the
116 dumpfile. The key data in the database will not be
117 changed.
118 -rev dumps in reverse order. This may recover principals that
120 do not dump normally, in cases where database corruption
121 has occured.
122 -recurse
124 causes the dump to walk the database recursively (btree
125 only). This may recover principals that do not dump nor‐
126 mally, in cases where database corruption has occured.
127 In cases of such corruption, this option will probably
128 retrieve more principals than the -rev option will.
129 load -old|-b6|-b7|-ov|-r13] [-hash]
131 [-verbose] [-update] filename dbname
132 Loads a database dump from the named file into the named data‐
133 base. Unless the -old or -b6 option is given, the format of the
134 dump file is detected automatically and handled as appropriate.
135 Unless the -update option is given, load creates a new database
136 containing only the principals in the dump file, overwriting the
137 contents of any previously existing database. Note that when
138 using the LDAP KDB plugin the -update must be given. Options:
139 -old requires the database to be in the Kerberos 5 Beta 5 and
141 earlier format ("kdb5_edit load_dump version 2.0").
142 -b6 requires the database to be in the Kerberos 5 Beta 6 for‐
144 mat ("kdb5_edit load_dump version 3.0").
145 -b7 requires the database to be in the Kerberos 5 Beta 7 for‐
147 mat ("kdb5_util load_dump version 4").
148 -ov requires the database to be in ovsec_adm_import format.
150 Must be used with the -update option.
151 -hash requires the database to be stored as a hash. If this
153 option is not specified, the database will be stored as a
154 btree. This option is not recommended, as databases
155 stored in hash format are known to corrupt data and lose
156 principals.
157 -verbose
159 causes the name of each principal and policy to be
160 printed as it is dumped.
161 -update
163 records from the dump file are added to or updated in the
164 existing database; otherwise, a new database is created
165 containing only what is in the dump file and the old one
166 destroyed upon successful completion.
167 dbname is required and overrides the value specified on the com‐
169 mand line or the default.
170 ark Adds a random key.
172 add_mkey [-e etype] [-s]
174 Adds a new master key to the K/M (master key) principal. Exist‐
175 ing master keys will remain. The -e etype option allows speci‐
176 fication of the enctype of the new master key. The -s option
177 stashes the new master key in a local stash file which will be
178 created if it doesn't already exist.
179 use_mkey mkeyVNO [time]
181 Sets the activation time of the master key specified by mkeyVNO.
182 Once a master key is active (i.e. its activation time has been
183 reached) it will then be used to encrypt principal keys either
184 when the principal keys change, are newly created or when the
185 update_princ_encryption command is run. If the time argument is
186 provided then that will be the activation time otherwise the
187 current time is used by default. The format of the optional
188 time argument is that specified in the Time Formats section of
189 the kadmin man page.
190 list_mkeys
192 List all master keys from most recent to earliest in K/M princi‐
193 pal. The output will show the KVNO, enctype and salt for each
194 mkey similar to kadmin getprinc output. A * following an mkey
195 denotes the currently active master key.
196 purge_mkeys [-f] [-n] [-v]
198 Delete master keys from the K/M principal that are not used to
199 protect any principals. This command can be used to remove old
200 master keys from a K/M principal once all principal keys are
201 protected by a newer master key.
202 -f does not prompt user.
204 -n do a dry run, shows master keys that would be purged, does not
206 actually purge any keys.
207 -v verbose output.
209 update_princ_encryption [-f] [-n] [-v] [princ-pattern]
211 Update all principal records (or only those matching the
212 princ-pattern glob pattern) to re-encrypt the key data using the
213 active database master key, if they are encrypted using older
214 versions, and give a count at the end of the number of princi‐
215 pals updated. If the -f option is not given, ask for confirma‐
216 tion before starting to make changes. The -v option causes each
217 principal processed (each one matching the pattern) to be
218 listed, and an indication given as to whether it needed updating
219 or not. The -n option causes the actions not to be taken, only
220 the normal or verbose status messages displayed; this implies -f
221 since no database changes will be performed and thus there's
222 little reason to seek confirmation.
223
225 kadmin(8)
226 KDB5_UTIL(8)