src/man/kdb5_util.8

   1 .TH "KDB5_UTIL" "8" "January 06, 2012" "0.0.1" "MIT Kerberos"
   2 .SH NAME
   3 kdb5_util \- Kerberos database maintenance utility
   4 .
   5 .nr rst2man-indent-level 0
   6 .
   7 .de1 rstReportMargin
   8 \\$1 \\n[an-margin]
   9 level \\n[rst2man-indent-level]
  10 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
  11 -
  12 \\n[rst2man-indent0]
  13 \\n[rst2man-indent1]
  14 \\n[rst2man-indent2]
  15 ..
  16 .de1 INDENT
  17 .\" .rstReportMargin pre:
  18 . RS \\$1
  19 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
  20 . nr rst2man-indent-level +1
  21 .\" .rstReportMargin post:
  22 ..
  23 .de UNINDENT
  24 . RE
  25 .\" indent \\n[an-margin]
  26 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
  27 .nr rst2man-indent-level -1
  28 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
  29 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
  30 ..
  31 .\" Man page generated from reStructeredText.
  32 .
  33 .SH SYNOPSIS
  34 .INDENT 0.0
  35 .TP
  36 .B \fBkdb5_util\fP
  37 .sp
  38 [\fB\-r\fP \fIrealm\fP]
  39 [\fB\-d\fP \fIdbname\fP]
  40 [\fB\-k\fP \fImkeytype\fP]
  41 [\fB\-M\fP \fImkeyname\fP]
  42 [\fB\-kv\fP \fImkeyVNO\fP]
  43 [\fB\-sf\fP \fIstashfilename\fP]
  44 [\fB\-m\fP]
  45 \fIcommand\fP [\fIcommand_options\fP]
  46 .UNINDENT
  47 .SH DESCRIPTION
  48 .sp
  49 \fIkdb5_util\fP  allows an administrator to perform low\-level maintenance procedures on the Kerberos and KADM5 database.
  50 Databases can be created, destroyed, and dumped to and loaded from ASCII files.
  51 Additionally, \fIkdb5_util\fP can create a Kerberos master key stash file.
  52 \fIkdb5_util\fP subsumes the functionality of and makes obsolete the previous database maintenance programs kdb5_create, kdb5_edit, kdb5_destroy, and kdb5_stash.
  53 .sp
  54 When \fIkdb5_util\fP is run, it attempts to acquire the master key and open the database.  However, execution continues regardless of whether or not
  55 \fIkdb5_util\fP successfully opens the database, because the database may not exist yet or the stash file may be corrupt.
  56 .sp
  57 Note that some KDB plugins may not support all \fIkdb5_util\fP commands.
  58 .SH COMMAND-LINE OPTIONS
  59 .INDENT 0.0
  60 .INDENT 3.5
  61 .INDENT 0.0
  62 .TP
  63 .B \fB\-r\fP \fIrealm\fP
  64 .sp
  65 specifies the Kerberos realm of the database.
  66 .TP
  67 .B \fB\-d\fP \fIdbname\fP
  68 .sp
  69 specifies the name under which the principal database is stored; by default the database is that listed in \fIkdc.conf\fP.
  70 The  KADM5  policy database and lock file are also derived from this value.
  71 .TP
  72 .B \fB\-k\fP \fImkeytype\fP
  73 .sp
  74 specifies the key type of the master key in the database; the default is that given in \fIkdc.conf\fP.
  75 .TP
  76 .B \fB\-kv\fP \fImkeyVNO\fP
  77 .sp
  78 Specifies the version number of the master key in the database; the default is 1.  Note that 0 is not allowed.
  79 .TP
  80 .B \fB\-M\fP \fImkeyname\fP
  81 .sp
  82 principal name for the master key in the database; the default is that given in \fIkdc.conf\fP.
  83 .TP
  84 .B \fB\-m\fP
  85 .sp
  86 specifies that the master database password should be read from the TTY rather than fetched from a file on disk.
  87 .TP
  88 .B \fB\-sf\fP \fIstash_file\fP
  89 .sp
  90 specifies the stash file of the master database password.
  91 .TP
  92 .B \fB\-P\fP \fIpassword\fP
  93 .sp
  94 specifies the master database password.  This option is not recommended.
  95 .UNINDENT
  96 .UNINDENT
  97 .UNINDENT
  98 .SH COMMANDS
  99 .INDENT 0.0
 100 .INDENT 3.5
 101 .INDENT 0.0
 102 .TP
 103 .B \fBcreate\fP [\fB\-s\fP]
 104 .sp
 105 Creates a new database.  If the \fI\-s\fP option is specified, the stash file is also created.  This command fails if the database already exists.
 106 If the command is successful, the database is opened just as if it had already existed when the program was first run.
 107 .UNINDENT
 108 .UNINDENT
 109 .UNINDENT
 110 .INDENT 0.0
 111 .INDENT 3.5
 112 .INDENT 0.0
 113 .TP
 114 .B \fBdestroy\fP [\fB\-f\fP]
 115 .sp
 116 Destroys the database, first overwriting the disk sectors and then unlinking the files, after prompting the user for confirmation.
 117 With the \fI\-f\fP argument, does not prompt the user.
 118 .UNINDENT
 119 .UNINDENT
 120 .UNINDENT
 121 .INDENT 0.0
 122 .INDENT 3.5
 123 .INDENT 0.0
 124 .TP
 125 .B \fBstash\fP [\fB\-f\fP \fIkeyfile\fP]
 126 .sp
 127 Stores the master principal\(aqs keys in a stash file.  The \fI\-f\fP argument can be used to override the \fIkeyfile\fP specified at startup.
 128 .UNINDENT
 129 .UNINDENT
 130 .UNINDENT
 131 .INDENT 0.0
 132 .INDENT 3.5
 133 .INDENT 0.0
 134 .TP
 135 .B \fBdump\fP [\fB\-old|\-b6|\-b7|\-ov|\-r13\fP] [\fB\-verbose\fP] [\fB\-mkey_convert\fP] [\fB\-new_mkey_file\fP \fImkey_file\fP] [\fB\-rev\fP] [\fB\-recurse\fP] [\fIfilename\fP [\fIprincipals\fP...]]
 136 .sp
 137 Dumps the current Kerberos and KADM5 database into an ASCII file.  By default, the database is dumped in current format, "\fIkdb5_util\fP
 138 load_dump version 6".  If filename is not specified, or is the string "\-", the dump is sent to standard output.  Options:
 139 .INDENT 7.0
 140 .TP
 141 .B \fB\-old\fP
 142 .sp
 143 causes the dump to be in the Kerberos 5 Beta 5 and earlier dump format ("kdb5_edit load_dump version 2.0").
 144 .TP
 145 .B \fB\-b6\fP
 146 .sp
 147 causes the dump to be in the Kerberos 5 Beta 6 format ("kdb5_edit load_dump version 3.0").
 148 .TP
 149 .B \fB\-b7\fP
 150 .sp
 151 causes the dump to be in the Kerberos 5 Beta 7 format ("\fIkdb5_util\fP load_dump version 4").
 152 This  was  the  dump  format  produced  on releases prior to 1.2.2.
 153 .TP
 154 .B \fB\-ov\fP
 155 .sp
 156 causes the dump to be in \fIovsec_adm_export\fP format.
 157 .TP
 158 .B \fB\-r13\fP
 159 .sp
 160 causes the dump to be in the Kerberos 5 1.3 format ("\fIkdb5_util\fP load_dump version 5").
 161 This was the dump format produced on releases prior to 1.8.
 162 .TP
 163 .B \fB\-verbose\fP
 164 .sp
 165 causes the name of each principal and policy to be printed as it is dumped.
 166 .TP
 167 .B \fB\-mkey_convert\fP
 168 .sp
 169 prompts for a new master key.  This new master key will be used to re\-encrypt the key data in the dumpfile.
 170 The key data in the database will not be changed.
 171 .TP
 172 .B \fB\-new_mkey_file\fP \fImkey_file\fP
 173 .sp
 174 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.
 175 The key data in the database will not be changed.
 176 .TP
 177 .B \fB\-rev\fP
 178 .sp
 179 dumps in reverse order.  This may recover principals that do not dump normally, in cases where database corruption has occurred.
 180 .TP
 181 .B \fB\-recurse\fP
 182 .sp
 183 causes the dump to walk the database recursively (btree only).  This may recover principals that do not dump normally,
 184 in cases where database corruption has occurred.
 185 In  cases  of such corruption, this option will probably retrieve more principals than the \fI\-rev\fP option will.
 186 .UNINDENT
 187 .UNINDENT
 188 .UNINDENT
 189 .UNINDENT
 190 .INDENT 0.0
 191 .INDENT 3.5
 192 .INDENT 0.0
 193 .TP
 194 .B \fBload\fP [\fB\-old|\-b6|\-b7|\-ov|\-r13\fP] [\fB\-hash\fP] [\fB\-verbose\fP] [\fB\-update\fP] \fIfilename dbname\fP
 195 .sp
 196 Loads a database dump from the named file into the named database.
 197 Unless the \fI\-old\fP or \fI\-b6\fP option is given, the format of the dump file is detected automatically and handled as appropriate.
 198 Unless the \fI\-update\fP option is given, load creates a new database containing only the principals in the dump file,
 199 overwriting the contents of any previously existing database.
 200 Note that when using the LDAP KDB plugin the \fI\-update\fP must be given.  Options:
 201 .INDENT 7.0
 202 .TP
 203 .B \fB\-old\fP
 204 .sp
 205 requires the database to be in the Kerberos 5 Beta 5 and earlier format ("kdb5_edit load_dump version 2.0").
 206 .TP
 207 .B \fB\-b6\fP
 208 .sp
 209 requires the database to be in the Kerberos 5 Beta 6 format ("kdb5_edit load_dump version 3.0").
 210 .TP
 211 .B \fB\-b7\fP
 212 .sp
 213 requires the database to be in the Kerberos 5 Beta 7 format ("\fIkdb5_util\fP load_dump version 4").
 214 .TP
 215 .B \fB\-ov\fP
 216 .sp
 217 requires the database to be in ovsec_adm_import format.  Must be used with the \fI\-update\fP option.
 218 .TP
 219 .B \fB\-hash\fP
 220 .sp
 221 requires the database to be stored as a hash.  If this option is not specified, the database will be stored as a btree.
 222 This option is not recommended, as databases stored in hash format are known to corrupt data and lose principals.
 223 .TP
 224 .B \fB\-verbose\fP
 225 .sp
 226 causes the name of each principal and policy to be printed as it is dumped.
 227 .TP
 228 .B \fB\-update\fP
 229 .sp
 230 records from the dump file are added to or updated in the existing database.
 231 (This is useful in conjunction with an \fIovsec_adm_export\fP format dump if you want to preserve per\-principal policy information,
 232 since the current default format does not contain this data.)
 233 Otherwise, a new database is created containing only what is in the dump file and the old one destroyed upon successful completion.
 234 .UNINDENT
 235 .sp
 236 \fIdbname\fP is required and overrides the value specified on the command line or the default.
 237 .UNINDENT
 238 .UNINDENT
 239 .UNINDENT
 240 .INDENT 0.0
 241 .INDENT 3.5
 242 .INDENT 0.0
 243 .TP
 244 .B \fBark\fP
 245 .sp
 246 Adds a random key.
 247 .TP
 248 .B \fBadd_mkey\fP [\fB\-e\fP \fIetype\fP] [\fB\-s\fP]
 249 .sp
 250 Adds a new master key to the \fIK/M\fP (master key) principal.  Existing master keys will remain.
 251 The \fI\-e etype\fP option allows specification of the enctype of the new master key.
 252 The \fI\-s\fP option stashes the new master key in a local stash file which will be created if it doesn\(aqt already exist.
 253 .TP
 254 .B \fBuse_mkey\fP \fImkeyVNO\fP [\fItime\fP]
 255 .sp
 256 Sets the activation time of the master key specified by \fImkeyVNO\fP.
 257 Once a master key is active (i.e. its activation time has been reached) it will then be used to encrypt principal keys either when
 258 the principal keys change, are newly created or when the \fIupdate_princ_encryption\fP command is run.
 259 If the time argument is provided then that will be the activation time otherwise the current time is used by default.
 260 The format of the optional time argument is that specified in the \fITime Formats\fP section of the kadmin man page.
 261 .TP
 262 .B \fBlist_mkeys\fP
 263 .sp
 264 List all master keys from most recent to earliest in \fIK/M\fP principal.
 265 The output will show the kvno, enctype and salt for each mkey similar to kadmin getprinc output.
 266 A * following an mkey denotes the currently active master key.
 267 .TP
 268 .B \fBpurge_mkeys\fP [\fB\-f\fP] [\fB\-n\fP] [\fB\-v\fP]
 269 .sp
 270 Delete master keys from the \fIK/M\fP principal that are not used to protect any principals.
 271 This command can be used to remove old master keys from a \fIK/M\fP principal once all principal keys are protected by a newer master key.
 272 .INDENT 7.0
 273 .TP
 274 .B \fB\-f\fP
 275 .sp
 276 does not prompt user.
 277 .TP
 278 .B \fB\-n\fP
 279 .sp
 280 do a dry run, shows master keys that would be purged, does not actually purge any keys.
 281 .TP
 282 .B \fB\-v\fP
 283 .sp
 284 verbose output.
 285 .UNINDENT
 286 .TP
 287 .B \fBupdate_princ_encryption\fP [\fB\-f\fP] [\fB\-n\fP] [\fB\-v\fP] [\fIprinc\-pattern\fP]
 288 .sp
 289 Update all principal records (or only those matching the princ\-pattern glob pattern)
 290 to re\-encrypt the key data using the active database master key, if they are encrypted using older versions,
 291 and give a count at the end of the number of principals updated.
 292 If the \fI\-f\fP option is not given, ask for confirmation before starting to make changes.
 293 The \fI\-v\fP option causes each principal processed (each one matching the pattern) to be listed,
 294 and an indication given as to whether it needed updating or not.
 295 The \fI\-n\fP option causes the actions not to be taken, only the normal or verbose status messages displayed;
 296 this implies \fI\-f\fP since no database changes will be performed and thus there\(aqs little reason to seek confirmation.
 297 .UNINDENT
 298 .UNINDENT
 299 .UNINDENT
 300 .SH SEE ALSO
 301 .sp
 302 kadmin(8)
 303 .SH AUTHOR
 304 MIT
 305 .SH COPYRIGHT
 306 2011, MIT
 307 .\" Generated by docutils manpage writer.
 308 .