Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
KDB5_UTIL(8)			 MIT Kerberos			  KDB5_UTIL(8)

       kdb5_util - Kerberos database maintenance utility

       kdb5_util  [-r realm] [-d dbname] [-k mkeytype] [-kv mkeyVNO] [-M mkey-
       name] [-m] [-sf stashfilename] [-P password] [-x	db_args] command [com-

       kdb5_util  allows an administrator to perform maintenance procedures on
       the KDC database.  Databases can	be created, destroyed, and  dumped  to
       or loaded from ASCII files.  kdb5_util can create a Kerberos master key
       stash file or perform live rollover of the master key.

       When kdb5_util is run, it attempts to acquire the master	key  and  open
       the  database.	However,  execution continues regardless of whether or
       not kdb5_util successfully opens	the database, because the database may
       not exist yet or	the stash file may be corrupt.

       Note  that some KDC database modules may	not support all	kdb5_util com-

       -r realm
	      specifies	the Kerberos realm of the database.

       -d dbname
	      specifies	the name under which the principal database is stored;
	      by  default  the	database  is  that listed in kdc.conf(5).  The
	      password policy database and lock	files are  also	 derived  from
	      this value.

       -k mkeytype
	      specifies	 the  key type of the master key in the	database.  The
	      default is given by the master_key_type variable in kdc.conf(5).

       -kv mkeyVNO
	      Specifies	the version number of the master key in	the  database;
	      the default is 1.	 Note that 0 is	not allowed.

       -M mkeyname
	      principal	name for the master key	in the database.  If not spec-
	      ified, the name is determined by the master_key_name variable in

       -m     specifies	 that the master database password should be read from
	      the keyboard rather than fetched from a file on disk.

       -sf stash_file
	      specifies	the stash filename of the  master  database  password.
	      If   not	 specified,   the   filename   is  determined  by  the
	      key_stash_file variable in kdc.conf(5).

       -P password
	      specifies	the master database password.  Using this  option  may
	      expose the password to other users on the	system via the process

       -x db_args
	      specifies	database-specific options.   See  kadmin(1)  for  sup-
	      ported options.

	  create [-s]

       Creates	a new database.	 If the	-s 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.

	  destroy [-f]

       Destroys	the database, first overwriting	the disk sectors and then  un-
       linking the files, after	prompting the user for confirmation.  With the
       -f argument, does not prompt the	user.

	  stash	[-f keyfile]

       Stores the master principal's keys in a stash file.   The  -f  argument
       can be used to override the keyfile specified in	kdc.conf(5).

	  dump	 [-b7|-r13|-r18]  [-verbose]  [-mkey_convert]  [-new_mkey_file
	  mkey_file] [-rev] [-recurse] [filename [principals...]]

       Dumps the current Kerberos and KADM5 database into an ASCII  file.   By
       default,	the database is	dumped in current format, "kdb5_util load_dump
       version 7".  If filename	is not specified, or is	the  string  "-",  the
       dump is sent to standard	output.	 Options:

       -b7    causes  the  dump	 to  be	 in  the  Kerberos  5  Beta  7	format
	      ("kdb5_util load_dump version 4").  This	was  the  dump	format
	      produced on releases prior to 1.2.2.

       -r13   causes  the  dump	to be in the Kerberos 5	1.3 format ("kdb5_util
	      load_dump	version	5").  This was the dump	format produced	on re-
	      leases prior to 1.8.

       -r18   causes  the  dump	to be in the Kerberos 5	1.8 format ("kdb5_util
	      load_dump	version	6").  This was the dump	format produced	on re-
	      leases prior to 1.11.

	      causes the name of each principal	and policy to be printed as it
	      is dumped.

	      prompts for a new	master key.  This new master key will be  used
	      to re-encrypt principal key data in the dumpfile.	 The principal
	      keys themselves will not be changed.

       -new_mkey_file mkey_file
	      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.

       -rev   dumps in reverse order.  This may	recover	principals that	do not
	      dump normally, in	cases where database corruption	has occurred.

	      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 cor-
	      ruption, this option will	probably retrieve more principals than
	      the -rev option will.

	      Changed in version 1.15: Release 1.15 restored the functionality
	      of the -recurse option.

	      Changed in version 1.5: The -recurse option ceased working until
	      release 1.15, doing a normal dump	instead	of a recursive traver-

	  load [-b7|-r13|-r18] [-hash] [-verbose] [-update] filename

       Loads a database	dump from the named file into the named	database.   If
       no option is given to determine the format of the dump file, the	format
       is detected automatically and handled as	appropriate.  Unless the  -up-
       date  option  is	given, load creates a new database containing only the
       data in the dump	file, overwriting the contents of any  previously  ex-
       isting  database.   Note	 that when using the LDAP KDC database module,
       the -update flag	is required.


       -b7    requires the database to be in the  Kerberos  5  Beta  7	format
	      ("kdb5_util  load_dump  version  4").   This was the dump	format
	      produced on releases prior to 1.2.2.

       -r13   requires the database to be in Kerberos 5	1.3 format ("kdb5_util
	      load_dump	version	5").  This was the dump	format produced	on re-
	      leases prior to 1.8.

       -r18   requires the database to be in Kerberos 5	1.8 format ("kdb5_util
	      load_dump	version	6").  This was the dump	format produced	on re-
	      leases prior to 1.11.

       -hash  stores the database in hash format, if using  the	 DB2  database
	      type.   If  this	option	is not specified, the database will be
	      stored in	btree format.  This  option  is	 not  recommended,  as
	      databases	 stored	 in  hash format are known to corrupt data and
	      lose principals.

	      causes the name of each principal	and policy to be printed as it
	      is dumped.

	      records from the dump file are added to or updated in the	exist-
	      ing database.  Otherwise,	a new database is  created  containing
	      only  what  is  in  the dump file	and the	old one	destroyed upon
	      successful completion.

	  ark [-e enc:salt,...]	principal

       Adds new	random keys to principal at the	 next  available  key  version
       number.	 Keys  for the current highest key version number will be pre-
       served.	The -e option specifies	the list of encryption and salt	 types
       to be used for the new keys.

	  add_mkey [-e etype] [-s]

       Adds a new master key to	the master key principal, but does not mark it
       as active.  Existing master keys	will remain.  The -e option  specifies
       the  encryption	type  of  the  new master key; see Encryption_types in
       kdc.conf(5) for a list of possible values.  The -s option  stashes  the
       new  master  key	in the stash file, which will be created if it doesn't
       already exist.

       After a new master key is added,	it should  be  propagated  to  replica
       servers	via  a	manual	or periodic invocation of kprop(8).  Then, the
       stash files on the replica servers should be updated with the kdb5_util
       stash  command.	 Once those steps are complete,	the key	is ready to be
       marked active with the kdb5_util	use_mkey command.

	  use_mkey mkeyVNO [time]

       Sets the	activation time	of the master key specified by mkeyVNO.	  Once
       a  master  key becomes active, it will be used to encrypt newly created
       principal keys.	If no time argument is	given,	the  current  time  is
       used, causing the specified master key version to become	active immedi-
       ately.  The format for time is getdate string.

       After a new master key becomes active, the  kdb5_util  update_princ_en-
       cryption	 command  can  be  used	to update all principal	keys to	be en-
       crypted in the new master key.


       List all	master keys, from most recent to earliest, in the  master  key
       principal.   The	 output	will show the kvno, enctype, and salt type for
       each mkey, similar to the output	of kadmin(1) getprinc.	A *  following
       an mkey denotes the currently active master key.

	  purge_mkeys [-f] [-n]	[-v]

       Delete  master  keys from the master key	principal that are not used to
       protect any principals.	This command can be used to remove old	master
       keys all	principal keys are protected by	a newer	master key.

       -f     does not prompt for confirmation.

       -n     performs	a  dry	run, showing master keys that would be purged,
	      but not actually purging any keys.

       -v     gives more verbose output.

	  update_princ_encryption [-f] [-n] [-v] [princ-pattern]

       Update all principal records (or	only those matching the	 princ-pattern
       glob pattern) to	re-encrypt the key data	using the active database mas-
       ter key,	if they	are encrypted using a different	version,  and  give  a
       count at	the end	of the number of principals updated.  If the -f	option
       is not given, ask for confirmation before  starting  to	make  changes.
       The -v option causes each principal processed to	be listed, with	an in-
       dication	as to whether it needed	updating or not.  The -n  option  per-
       forms a dry run,	only showing the actions which would have been taken.

	  tabdump [-H] [-c] [-e] [-n] [-o outfile] dumptype

       Dump  selected  fields of the database in a tabular format suitable for
       reporting (e.g.,	using traditional Unix text processing tools)  or  im-
       porting	into  relational  databases.  The data format is tab-separated
       (default), or optionally	comma-separated	(CSV), with a fixed number  of
       columns.	  The output begins with a header line containing field	names,
       unless suppression is requested using the -H option.

       The dumptype parameter specifies	the name of an output table  (see  be-


       -H     suppress writing the field names in a header line

       -c     use  comma  separated values (CSV) format, with minimal quoting,
	      instead of the default tab-separated (unquoted, unescaped)  for-

       -e     write empty hexadecimal string fields as empty fields instead of
	      as "-1".

       -n     produce numeric output for fields	that  normally	have  symbolic
	      output,  such  as	enctypes and flag names.  Also requests	output
	      of time stamps as	decimal	POSIX time_t values.

       -o outfile
	      write the	dump to	the specified output file instead of to	 stan-
	      dard output

       Dump types:

	      principal	 encryption key	information, including actual key data
	      (which is	still encrypted	in the master key)

	      name   principal name

		     index of this key in the principal's key list

	      kvno   key version number

		     encryption	type

	      key    key data as a hexadecimal string

		     salt type

	      salt   salt data as a hexadecimal	string

	      principal	encryption key information (as in keydata above),  ex-
	      cluding actual key data

	      principal	 boolean  attributes.  Flag names print	as hexadecimal
	      numbers if the -n	option is specified, and  all  flag  positions
	      are printed regardless of	whether	or not they are	set.  If -n is
	      not specified, print all known flag names	 for  each  principal,
	      but  only	print hexadecimal flag names if	the corresponding flag
	      is set.

	      name   principal name

	      flag   flag name

	      value  boolean value (0 for clear, or 1 for set)

	      state information	used for tracking repeated password failures

	      name   principal name

		     time stamp	of most	recent successful authentication

		     time stamp	of most	recent failed authentication

		     count of failed attempts

	      principal	metadata

	      name   principal name

	      modby  name of last principal to modify this principal

		     timestamp of last modification

		     timestamp of last password	change

	      policy policy object name

	      mkvno  key version number	of the master key that	encrypts  this
		     principal's key data

		     key  version  number of the history key that encrypts the
		     key history data for this principal

	      string attributes	(key/value pairs)

	      name   principal name

	      key    attribute name

	      value  attribute value

	      per-principal ticket policy data,	including maximum ticket life-

	      name   principal name

		     principal expiration date

		     password expiration date

		     maximum ticket lifetime

		     maximum renewable ticket lifetime


	  $ kdb5_util tabdump -o keyinfo.txt keyinfo
	  $ cat	keyinfo.txt
	  name	      keyindex	      kvno    enctype salttype	      salt
	  K/M@EXAMPLE.COM     0	      1	      aes256-cts-hmac-sha384-192      normal  -1
	  foo@EXAMPLE.COM     0	      1	      aes128-cts-hmac-sha1-96 normal  -1
	  bar@EXAMPLE.COM     0	      1	      aes128-cts-hmac-sha1-96 normal  -1
	  $ sqlite3
	  sqlite> .mode	tabs
	  sqlite> .import keyinfo.txt keyinfo
	  sqlite> select * from	keyinfo	where enctype like 'aes256-%';
	  K/M@EXAMPLE.COM     1	      1	      aes256-cts-hmac-sha384-192      normal  -1
	  sqlite> .quit
	  $ awk	-F'\t' '$4 ~ /aes256-/ { print }' keyinfo.txt
	  K/M@EXAMPLE.COM     1	      1	      aes256-cts-hmac-sha384-192      normal  -1

       See kerberos(7) for a description of Kerberos environment variables.

       kadmin(1), kerberos(7)


       1985-2020, MIT

1.20								  KDB5_UTIL(8)


Want to link to this manual page? Use this URL:

home | help