diff options
Diffstat (limited to 'src/man/kdb5_util.8')
| -rw-r--r-- | src/man/kdb5_util.8 | 308 |
1 files changed, 308 insertions, 0 deletions
diff --git a/src/man/kdb5_util.8 b/src/man/kdb5_util.8 new file mode 100644 index 0000000000..ca0310f360 --- /dev/null +++ b/src/man/kdb5_util.8 @@ -0,0 +1,308 @@ +.TH "KDB5_UTIL" "8" "January 06, 2012" "0.0.1" "MIT Kerberos" +.SH NAME +kdb5_util \- Kerberos database maintenance utility +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.\" Man page generated from reStructeredText. +. +.SH SYNOPSIS +.INDENT 0.0 +.TP +.B \fBkdb5_util\fP +.sp +[\fB\-r\fP \fIrealm\fP] +[\fB\-d\fP \fIdbname\fP] +[\fB\-k\fP \fImkeytype\fP] +[\fB\-M\fP \fImkeyname\fP] +[\fB\-kv\fP \fImkeyVNO\fP] +[\fB\-sf\fP \fIstashfilename\fP] +[\fB\-m\fP] +\fIcommand\fP [\fIcommand_options\fP] +.UNINDENT +.SH DESCRIPTION +.sp +\fIkdb5_util\fP allows an administrator to perform low\-level maintenance procedures on the Kerberos and KADM5 database. +Databases can be created, destroyed, and dumped to and loaded from ASCII files. +Additionally, \fIkdb5_util\fP can create a Kerberos master key stash file. +\fIkdb5_util\fP subsumes the functionality of and makes obsolete the previous database maintenance programs kdb5_create, kdb5_edit, kdb5_destroy, and kdb5_stash. +.sp +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 +\fIkdb5_util\fP successfully opens the database, because the database may not exist yet or the stash file may be corrupt. +.sp +Note that some KDB plugins may not support all \fIkdb5_util\fP commands. +.SH COMMAND-LINE OPTIONS +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.TP +.B \fB\-r\fP \fIrealm\fP +.sp +specifies the Kerberos realm of the database. +.TP +.B \fB\-d\fP \fIdbname\fP +.sp +specifies the name under which the principal database is stored; by default the database is that listed in \fIkdc.conf\fP. +The KADM5 policy database and lock file are also derived from this value. +.TP +.B \fB\-k\fP \fImkeytype\fP +.sp +specifies the key type of the master key in the database; the default is that given in \fIkdc.conf\fP. +.TP +.B \fB\-kv\fP \fImkeyVNO\fP +.sp +Specifies the version number of the master key in the database; the default is 1. Note that 0 is not allowed. +.TP +.B \fB\-M\fP \fImkeyname\fP +.sp +principal name for the master key in the database; the default is that given in \fIkdc.conf\fP. +.TP +.B \fB\-m\fP +.sp +specifies that the master database password should be read from the TTY rather than fetched from a file on disk. +.TP +.B \fB\-sf\fP \fIstash_file\fP +.sp +specifies the stash file of the master database password. +.TP +.B \fB\-P\fP \fIpassword\fP +.sp +specifies the master database password. This option is not recommended. +.UNINDENT +.UNINDENT +.UNINDENT +.SH COMMANDS +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.TP +.B \fBcreate\fP [\fB\-s\fP] +.sp +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. +If the command is successful, the database is opened just as if it had already existed when the program was first run. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.TP +.B \fBdestroy\fP [\fB\-f\fP] +.sp +Destroys the database, first overwriting the disk sectors and then unlinking the files, after prompting the user for confirmation. +With the \fI\-f\fP argument, does not prompt the user. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.TP +.B \fBstash\fP [\fB\-f\fP \fIkeyfile\fP] +.sp +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. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.TP +.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...]] +.sp +Dumps the current Kerberos and KADM5 database into an ASCII file. By default, the database is dumped in current format, "\fIkdb5_util\fP +load_dump version 6". If filename is not specified, or is the string "\-", the dump is sent to standard output. Options: +.INDENT 7.0 +.TP +.B \fB\-old\fP +.sp +causes the dump to be in the Kerberos 5 Beta 5 and earlier dump format ("kdb5_edit load_dump version 2.0"). +.TP +.B \fB\-b6\fP +.sp +causes the dump to be in the Kerberos 5 Beta 6 format ("kdb5_edit load_dump version 3.0"). +.TP +.B \fB\-b7\fP +.sp +causes the dump to be in the Kerberos 5 Beta 7 format ("\fIkdb5_util\fP load_dump version 4"). +This was the dump format produced on releases prior to 1.2.2. +.TP +.B \fB\-ov\fP +.sp +causes the dump to be in \fIovsec_adm_export\fP format. +.TP +.B \fB\-r13\fP +.sp +causes the dump to be in the Kerberos 5 1.3 format ("\fIkdb5_util\fP load_dump version 5"). +This was the dump format produced on releases prior to 1.8. +.TP +.B \fB\-verbose\fP +.sp +causes the name of each principal and policy to be printed as it is dumped. +.TP +.B \fB\-mkey_convert\fP +.sp +prompts for a new master key. This new master key will be used to re\-encrypt the key data in the dumpfile. +The key data in the database will not be changed. +.TP +.B \fB\-new_mkey_file\fP \fImkey_file\fP +.sp +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. +.TP +.B \fB\-rev\fP +.sp +dumps in reverse order. This may recover principals that do not dump normally, in cases where database corruption has occurred. +.TP +.B \fB\-recurse\fP +.sp +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 \fI\-rev\fP option will. +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.TP +.B \fBload\fP [\fB\-old|\-b6|\-b7|\-ov|\-r13\fP] [\fB\-hash\fP] [\fB\-verbose\fP] [\fB\-update\fP] \fIfilename dbname\fP +.sp +Loads a database dump from the named file into the named database. +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. +Unless the \fI\-update\fP option is given, load creates a new database containing only the principals in the dump file, +overwriting the contents of any previously existing database. +Note that when using the LDAP KDB plugin the \fI\-update\fP must be given. Options: +.INDENT 7.0 +.TP +.B \fB\-old\fP +.sp +requires the database to be in the Kerberos 5 Beta 5 and earlier format ("kdb5_edit load_dump version 2.0"). +.TP +.B \fB\-b6\fP +.sp +requires the database to be in the Kerberos 5 Beta 6 format ("kdb5_edit load_dump version 3.0"). +.TP +.B \fB\-b7\fP +.sp +requires the database to be in the Kerberos 5 Beta 7 format ("\fIkdb5_util\fP load_dump version 4"). +.TP +.B \fB\-ov\fP +.sp +requires the database to be in ovsec_adm_import format. Must be used with the \fI\-update\fP option. +.TP +.B \fB\-hash\fP +.sp +requires the database to be stored as a hash. If this option is not specified, the database will be stored as a btree. +This option is not recommended, as databases stored in hash format are known to corrupt data and lose principals. +.TP +.B \fB\-verbose\fP +.sp +causes the name of each principal and policy to be printed as it is dumped. +.TP +.B \fB\-update\fP +.sp +records from the dump file are added to or updated in the existing database. +(This is useful in conjunction with an \fIovsec_adm_export\fP format dump if you want to preserve per\-principal policy information, +since the current default format does not contain this data.) +Otherwise, a new database is created containing only what is in the dump file and the old one destroyed upon successful completion. +.UNINDENT +.sp +\fIdbname\fP is required and overrides the value specified on the command line or the default. +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.TP +.B \fBark\fP +.sp +Adds a random key. +.TP +.B \fBadd_mkey\fP [\fB\-e\fP \fIetype\fP] [\fB\-s\fP] +.sp +Adds a new master key to the \fIK/M\fP (master key) principal. Existing master keys will remain. +The \fI\-e etype\fP option allows specification of the enctype of the new master key. +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. +.TP +.B \fBuse_mkey\fP \fImkeyVNO\fP [\fItime\fP] +.sp +Sets the activation time of the master key specified by \fImkeyVNO\fP. +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 +the principal keys change, are newly created or when the \fIupdate_princ_encryption\fP command is run. +If the time argument is provided then that will be the activation time otherwise the current time is used by default. +The format of the optional time argument is that specified in the \fITime Formats\fP section of the kadmin man page. +.TP +.B \fBlist_mkeys\fP +.sp +List all master keys from most recent to earliest in \fIK/M\fP principal. +The output will show the kvno, enctype and salt for each mkey similar to kadmin getprinc output. +A * following an mkey denotes the currently active master key. +.TP +.B \fBpurge_mkeys\fP [\fB\-f\fP] [\fB\-n\fP] [\fB\-v\fP] +.sp +Delete master keys from the \fIK/M\fP principal that are not used to protect any principals. +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. +.INDENT 7.0 +.TP +.B \fB\-f\fP +.sp +does not prompt user. +.TP +.B \fB\-n\fP +.sp +do a dry run, shows master keys that would be purged, does not actually purge any keys. +.TP +.B \fB\-v\fP +.sp +verbose output. +.UNINDENT +.TP +.B \fBupdate_princ_encryption\fP [\fB\-f\fP] [\fB\-n\fP] [\fB\-v\fP] [\fIprinc\-pattern\fP] +.sp +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 older versions, +and give a count at the end of the number of principals updated. +If the \fI\-f\fP option is not given, ask for confirmation before starting to make changes. +The \fI\-v\fP option causes each principal processed (each one matching the pattern) to be listed, +and an indication given as to whether it needed updating or not. +The \fI\-n\fP option causes the actions not to be taken, only the normal or verbose status messages displayed; +this implies \fI\-f\fP since no database changes will be performed and thus there\(aqs little reason to seek confirmation. +.UNINDENT +.UNINDENT +.UNINDENT +.SH SEE ALSO +.sp +kadmin(8) +.SH AUTHOR +MIT +.SH COPYRIGHT +2011, MIT +.\" Generated by docutils manpage writer. +. |