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

FreeBSD Manual Pages


home | help
ods-ksmutil(1)		    OpenDNSSEC ods-ksmutil		ods-ksmutil(1)

       ods-ksmutil - OpenDNSSEC	zone and key management

       ods-ksmutil setup
       ods-ksmutil start|stop|notify
       ods-ksmutil update kasp|zonelist|conf|all
       ods-ksmutil zone	add|delete|list	...
       ods-ksmutil zonelist import|export
       ods-ksmutil    key   generate|import|export|list|purge|rollover|ksk-re-
       tire|ds-seen ...
       ods-ksmutil rollover list ...
       ods-ksmutil policy export|import|purge ...
       ods-ksmutil repository list ...
       ods-ksmutil backup list|prepare|commit|rollback|done
       ods-ksmutil database backup ...

       ods-ksmutil manages the operation of the	KASP Enforcer,	which  is  the
       part  of	OpenDNSSEC that	triggers key generation	and signing operations
       on domains based	on policies with user-defined timing and security  re-
       quirements.  Since everything beyond this management utility is usually
       automatic, ods-ksmutil is the primary  tool  for	 managing  OpenDNSSEC.
       Among  the  functions of	ods-ksmutil are	key management,	updates	to the
       zone list and manually rolling keys to recover from exceptional	situa-
       tions like key loss.

       To  get started,	a first	invocation of ods-ksmutil setup	is needed; see
       SETUP AND UPDATE	COMMANDS below for details.  After this	is  done,  the
       rest of the functionality of ods-ksmutil	becomes	available.

       The  following  sections	discuss	the subcommands	in logical groups, de-
       tailing any options that	they support.

       -c configfile, --config configfile
	      Change the conf.xml file that is used from the default.

       help   This can be used as a subcommand to ods-ksmutil  or  it  can  be
	      used  after a partial subcommand.	 In response, ods-ksmutil will
	      give a synopsis of how to	continue the command.

       -V, --version
	      Display version number

       setup  Import conf.xml, kasp.xml	 and  zonelist.xml  into  a  database.
	      This  deletes  any current management information	from the data-
	      base with	OpenDNSSEC management information, including any  ref-
	      erences  to keys.	 Updates to an existing	setup should therefore
	      not normally run this subcommand,	but update instead.

       update kasp

       update zonelist

       update conf

       update all
	      Update the database with the contents of the respective configu-
	      ration  file,  or	 all those files.  The result is comparable to
	      the setup	subcommand, except that	management  information	 about
	      OpenDNSSEC  is  not deleted.(Also	note that update kasp does not
	      remove any policies from the database, policy purge can be  used
	      to remove	unused policies).

       zone  add  --zone|-z zone [--policy|-p name] [--input|-i	input] [--out-
       put|-o output] [--no-xml]
	      Add a zone to both  zonelist.xml	and  the  database.   This  is
	      equivalent to manually editing zonelist.xml and then running the
	      update zonelist subcommand.  The --zone option names the zone to
	      add;  the	--policy option	names the policy to use	instead	of de-
	      fault; the --input option	specifies a non-standard location  for
	      the  unsigned  zone  (default  is	 /usr/local/var/opendnssec/un-
	      signed/ZONE); the	--output option	specifies a non-standard loca-
	      tion    for    the    signed    zone    (default	 is   /usr/lo-
	      cal/var/opendnssec/signed/ZONE).	The --no-xml  flag  stops  the
	      zonelist.xml  file  from	being  updated.	This is	suitable for a
	      batch mode where you will	add multiple zones and then just write
	      zonelist once at the end.

       zone delete --zone|-z name [--no-xml]

       zone delete --all|-a
	      Delete   one   zone  (or	all  zones,  respectively)  from  both
	      zonelist.xml and the database.  This is equivalent  to  manually
	      editing  zonelist.xml  and then running the update zonelist sub-
	      command.	The --no-xml flag stops	the zonelist.xml file from be-
	      ing  updated.  This  is suitable for a batch mode	where you will
	      delete multiple zones and	then just write	zonelist once  at  the

       zone list
	      List zones from the zonelist.xml.	 TODO:Not from the database?

       zonelist	export
	      Export  list  of	zones  from the	database in the	same format as

       zonelist	import
	      Synchronise the database	with  the  contents  of	 zonelist.xml;
	      identical	to "update zonelist"

       key  generate  --policy|-p  name	--interval|-n interval [--zonetotal|-Z
	      Create enough keys for the named policy to last for  the	period
	      of  time	given by interval.  See	INTERVAL FORMAT	for the	format
	      of timing	specifications.

	      If configured to,	OpenDNSSEC will	automatically create keys when
	      the  need	 arises.  This command can be used to pregenerate keys
	      (maybe for the expected lifetime of an HSM) to help with	backup
	      policies.	 It is also a convenient method	of pregenerating a set
	      of keys to allow a disaster recovery site	to have	a copy of  the
	      keys without needed to synchronise keys generated	on the fly.

	      By default the command generates keys for	all the	zones found on
	      the specified policy. If the optional parameter  --zonetotal  is
	      specified	 then  keys will be generated for that total number of
	      zones, regardless	of how many are	actually currently on the pol-

       key  import  --algorithm|-g algname --bits|-b bits --repository|-r repo
       --cka_id|-k ckaid --zone|-z zone	--keytype|-t type --keystate|-e	 state
       --time|-w  time	[--check-repository|-C	checkrepository]  [--retire|-y
	      Add a key	which was created outside of the OpenDNSSEC code  into
	      the  database.  In doing so, the further details involved	in key
	      management must be specified in options.

	      The --algorithm option names the algorithm used with  this  key;
	      the  --bits  specifies  the  strength of this algorithm as a key
	      size in bits.

	      The --repository option names the	repository in  which  the  key
	      should  be  stored;  the --cka_id	option specifies the name that
	      will be used to identify this key	in that	repository; the	--zone
	      option  specifies	the zone for which this	key is to be used; the
	      --keytype	option specifies whether this key should  serve	 as  a
	      KSK  or a	ZSK.  See KEY TYPES below for an introduction to these

	      The --keystate option specifies the state	in which the key  will
	      be  after	 import, and must be one of the	options	defined	in the
	      KEY STATES section below.	 the --time option specifies the  time
	      that  this key was created; the --check-repository option	speci-
	      fied that	the key	import should fail if no matching key with the
	      specified	 cka_id	exists in the Repository.  the --retire	option
	      specifies	the time that this key should be retired.  These  last
	      two  options  take the formats given in the TIME FORMATS section

       key export --zone|-z name  [--keystate|-e  state]  [--keytype|-t	 type]

       key export --all	[--keystate|-e state] [--keytype|-t type] [--ds]
	      Export  the keys for a particular	zone, or for all zones respec-
	      tively, from the database.  The --ds option can be used  to  re-
	      trieve  DS  records for upload to	a registry instead of the full
	      key; the --keystate option can be	used to	limit  the  output  to
	      keys in a	given state; the --keytype option can be used to limit
	      the output to keys of a given type.  See the KEY TYPES  and  KEY
	      STATES  sections below for a specification of possible key types
	      and states.

       key  list  [--zone  name]  [--verbose]  [--keystate|--all|-e  state|-a]
       [--keytype type|-t type]
	      List  information	 about	keys  in all zones, or in a particular
	      zone. By default keys in the GENERATE and	 DEAD  state  are  not

	      The  --verbose  option  is  used	to list	additional information
	      about each key.

	      The --keystate option can	be used	to limit the output to keys in
	      a	 given	state.	If  the	 --all option is used then keys	in all
	      states (including	GENERATE and DEAD) are displayed.  The	--key-
	      type  option  can	be used	to limit the output to keys of a given
	      type.  See the KEY TYPES and KEY STATES  sections	 below	for  a
	      specification of possible	key types and states.

       key purge --zone|-z name

       key purge --policy|-p name
	      Remove  any  keys	in the Dead state from the repository and from
	      the database of the  KASP	 Enforcer.   The  options  --zone  and
	      --policy are used	to limit this operation	to a single named zone
	      or policy, respectively.

       key rollover --zone|-z name --keytype type|-t type

       key rollover --zone|-z name --all|-a

       key rollover --policy|-p	name --keytype type|-t type

       key rollover --policy|-p	name --all|-a
	      Rollover active keys on the named	zone or	policy,	 respectively.
	      This  command  is	used to	intiate	manual rollovers; if it	is not
	      given, OpenDNSSEC	will automatically rollover keys when the need
	      arises.  (Or,  in	 the  case  of KSKs it will start the rollover
	      process, to finish the KSK rollover see ksk-roll below.)

	      The --keytype option specifies the type of key to	roll. Alterna-
	      tively  the  --all option	can be used which will roll both types
	      of keys. After running, the KASP Enforcer	will be	 woken	up  so
	      that the signer can be sent the new information.

	      If the policy that the zone is on	specifies that keys are	shared
	      then all zones on	that policy will be rolled. If appropriate,  a
	      backup of	the sqlite DB file is made.

	      If  there	 are  no  keys ready to	take over from the current key
	      then the rollover	will not occur immediately, but	 will  be  put
	      off until	the is a key in	the ready state.

       key ksk-retire --zone|-z	zone

       key ksk-retire --keytag|-x keytag

       key ksk-retire --cka_id|-k ckaid
	      Indicate to OpenDNSSEC that a currently active key should	be re-
	      tired.  If key identifiers are not provided then the oldest  key
	      in the zone will be retired.

	      If  only	one  key is in the active state	then this command will
	      exit with	an error message, as completing	would leave no	active

       key   ds-seen   --zone|-z   zone	 --keytag|-x  keytag  [--no-notify|-l]

       key ds-seen --zone|-z zone --cka_id|-k ckaid [--no-notify|-l] [--no-re-
	      Indicate	to  OpenDNSSEC that a submitted	DS record has appeared
	      in the parent zone, and thereby trigger the completion of	a  KSK
	      rollover.	  Note	that  this action is not yet standardised, and
	      can therefore not	be solved in a generic,	automatic  way.	  This
	      command  was  designed  for  inclusion in	any personalised setup
	      that may or may not be automated.

	      There are	several	ways to	specify	which DS is in	DNS,  and  the
	      options  reflect these alternatives.  The	--keytag option	speci-
	      fies the short integer that serves as a DNSSEC handle to a  key;
	      the --cka_id option refers to a key by way of its	long hexadeci-
	      mal identifier used to identify the key in the repository.

	      An optional --no-notify flag can also be passed in,  which  pre-
	      vents  the  enforcer being notified of this change. If this flag
	      is used then the enforcer	must be	 manually  notified  with  the
	      'ods-enforcerd  notify' command or the changes will not take ef-
	      fect until the next scheduled run	of the enforcer.

	      An optional --no-retire flag can also be passed in, without this
	      the  existing  key  is  moved into the retired state at the same
	      time as making the new key active. If you	 wish  to  delay  this
	      step  then pass in this flag and use the ksk-retire command when

       ods-ksmutil rollover list
	      List the expected	dates and times	of upcoming  rollovers.	  This
	      can  be  used  to	get an idea of upcoming	work, such as the non-
	      standardised submission of DS records to a registry.

       policy export [--policy|--all|-p|-a]
	      Export a policy from the database	in  the	 same  format  as  the
	      kasp.xml file.

       policy import
	      Update  the database with	the contents of	kasp.xml; identical to
	      "update kasp".

       policy purge
	      *	Experimental *

	      Remove any policies which	have no	zones  associated  with	 them.
	      Note that	this command has only been tested in a lab environment
	      and so caution is	recommended.

       repository list
	      List repositories	from the database.

       backup list --repository|-r name
	      List the backups that have been made on  the  given  repository.
	      The --repository option specifies	what repository	to list.

       backup prepare --repository|-r name
	      Start a two-phase	key backup procedure.  Prepare the keys	gener-
	      ated up to here for backup.  Any keys generated automatically by
	      OpenDNSSEC  after	 this  command are not guaranteed to be	backed
	      up, and will therefore not be taken into account when committing
	      the  prepared  keys  for use by OpenDNSSEC.  The next command is
	      usually either backup commit or, in case of failure of  the  key
	      backup itself, backup rollback.  This sequence works reliably if
	      the KASP Enforcer	is running.  If	it is  not,  the  single-phase
	      backup of	backup done provides a one-phase backup	alternative.

       backup commit --repository|-r name
	      Successfully  end	a two-phase key	backup procedure.  After a key
	      backup has succeeded, release all	previously prepared  keys  for
	      service  by  OpenDNSSEC.	Any keys that were generated since the
	      last issued preparation will not be released as it is  uncertain
	      whether these are	actually backed	up.

       backup rollback --repository|-r name
	      Safely end a failed two-phase key	backup procedure.  After a key
	      backup has failed, rollback all previously  prepapared  keys  to
	      the  state  where	 they are generated, but not yet available for
	      service by OpenDNSSEC.  After fixing this	problem, a new attempt
	      to backup	the keys can be	made.

       backup done --repository|-r name
	      Indicate	that  a	 backup	of the given repository	has been done,
	      all non-backed up	keys will now be marked	 as  backed  up.   The
	      --repository  option specifies what repository to	list.  This is
	      a	necessary step for repositories	that  have  the	 RequireBackup
	      flag set.

	      Note  that the KASP Enforcer may take the	initiative to generate
	      keys after the backup has	started	and before the backup is done.
	      This single-phase	backup command waives that, which is safe when
	      the KASP Enforcer	is not running.	 If you	intend to keep the En-
	      forcer  running,	you  will  instead  want  to use the two-phase
	      backup prepare followed by either	backup commit or backup	 roll-

       database	backup [--output|-o output]
	      Make  a  copy  of	 the  database	of the KASP Enforcer (if using
	      sqlite).	This command ensures that the database is in a consis-
	      tent  state  by  taking  a  lock out first.  The --output	option
	      specifies	where the output should	go; if not specified, the out-
	      put goes to the usual enforcer.db.backup file.

	      Start, stop or send "SIGHUP" to the ods-enforcerd	process.

	      The key has just been generated, but is not ready	for use.

	      The key has been published in the	parent zone.

       READY  The key is ready for use.	E.g. according to settings in the pol-
	      icy the key has been published for long enough  to  have	propa-
	      gated to all resolvers.

       ACTIVE The key is actively being	used to	sign one or more zones.

       RETIRE The  key has either reached the end of its scheduled life, or it
	      has been rolled prematurely. However, records signed with	it may
	      still be cached sp the key is still being	published.

       DEAD   The  key	has  been  retired  for	long enough that its use is no
	      longer cached, so	it has been removed from the zone.

       Keys can	be of two types: KSK or	ZSK.  These  terms  are	 explained  in
       more detail in opendnssec(1).

       In  DNS	records,  the  KSK can usually be recognised by	having its SEP
       (Secure Entry Point) flag set.  But please note that officially this is
       a mere hint.

       When specifying an interval for a key generation	run the	ISO 8601 stan-
       dard is used, e.g. P2Y6M	for 2 years and	6 months; or PT12H30M  for  12
       hours  and 30 minutes. Note that	a year is assumed to be	365 days and a
       month is	assumed	to be 31 days.

       When specifying a generation/retire time	for a key being	 imported  the
       following formats are understood:

	      (all numeric)

       D-MMM-YYYY[:| ]HH[:MM[:SS]]

       DD-MMM-YYYY[:| ]HH[:MM[:SS]]

       YYYY-MMM-DD[:| ]HH[:MM[:SS]]
	      (alphabetic month)

       D-MM-YYYY[:| ]HH[:MM[:SS]]

       DD-MM-YYYY[:| ]HH[:MM[:SS]]

       YYYY-MM-DD[:| ]HH[:MM[:SS]]
	      (numeric month)

	      The main configuration file for OpenDNSSEC.

	      The list of zones, as defined in conf.xml.

	      The  configuration  of policies that define timing and security,
	      as defined in conf.xml.

	      A	backup file of the database used  by  the  KASP	 Enforcer.Note
	      that  this  does not include the keys, which are to be extracted
	      from its own repository.

	      The location that	is usually configured in conf.xml  to  contain
	      unsigned zones.

	      The  location  that is usually configured	in conf.xml to contain
	      signed zones.

       ods-auditor(1),	ods-control(8),	  ods-enforcerd(8),   ods-hsmspeed(1),
       ods-hsmutil(1),	  ods-kaspcheck(1),   ods-signer(8),   ods-signerd(8),
       ods-timing(5), opendnssec(7),

       ods-ksmutil was written by Sion	Lloyd  and  Nominet  as	 part  of  the
       OpenDNSSEC project.

OpenDNSSEC			 February 2010			ods-ksmutil(1)


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

home | help