Provided by: opendnssec-enforcer_1.4.3-3_all bug

NAME

       ods-ksmutil - OpenDNSSEC zone and key management

SYNOPSIS

       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-retire |
       ds-seen | delete ] ...
       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 ...

DESCRIPTION

       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 requirements.  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 situations 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, detailing any options
       that they support.

GENERIC OPTIONS

       -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 AND UPDATE SUBCOMMANDS

       setup  Import conf.xml, kasp.xml and zonelist.xml  into  a  database.   This  deletes  any
              current  management  information  from  the  database  with  OpenDNSSEC  management
              information, including any references 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 respecive configuration file, or all
              those files.  The result  is  comparable  to  the  setup  subcommand,  except  that
              management information about OpenDNSSEC is not deleted.

ZONE MANAGEMENT SUBCOMMANDS

       zone  add  --zone|-z  zone  [--policy|-p  name]  [--in-type|-j  type] [--out-type|-q type]
       [--input|-i input] [--output|-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  default;  the  --in-type  and  --out-type  specify the type of input and output
              adapters (default is File); the --input option specifies  a  non-standard  location
              for  the  unsigned  zone  (default is /var/lib/opendnssec/unsigned/ZONE) or the DNS
              input file(default is /etc/opendnssec/addns.xml); the --output option  specifies  a
              non-standard      location      for     the     signed     zone     (default     is
              /var/lib/opendnssec/signed/ZONE)   or    the    DNS    output    file(default    is
              /etc/opendnssec/addns.xml).   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  subcommand.   The  --no-xml flag stops the zonelist.xml file from
              being updated. This is suitable for a batch mode where  you  will  delete  multiple
              zones and then just write zonelist once at the end.

       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.xml

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

KEY MANAGEMENT SUBCOMMANDS

       key generate --policy|-p name --interval|-n interval [--zonetotal|-Z zonetotal]
              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 policy.

       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 time]
              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 terms.

              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
              specified 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 below.

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

       key export --all [--keystate|-e state] [--keytype|-t type] [--ds]
              Export  the  keys  for  a  particular zone, or for all zones respectively, from the
              database.  The --ds option can be used to retrieve  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]

       key list --all [--verbose]
              List information about keys in a particular zone, or all zones, respectively.   The
              --verbose option is used to list additional information about each key.

       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.  Alternatively  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  retired.   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 keys.

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

       key ds-seen --zone|-z zone --cka_id|-k ckaid [--no-notify|-l] [--no-retire|-f]
              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  specifies 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
              hexadecimal identifier used to identify the key in the repository.

              An  optional  --no-notify  flag  can also be passed in, which prevents 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 effect 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 needed.

       key delete --cka_id|-k ckaid [--no-hsm]
              Remove a named key from the system.

              Keys  in  the  GENERATE or DEAD state can be safely removed from the system as they
              are not in use.

              The --no-hsm flag can be provided if you want to leave the key material on the HSM.

       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 ADMINISTRATION SUBCOMMANDS

       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 AND BACKUP SUBCOMMANDS

       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 generated 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 [--force]
              *DEPRECATED*

              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.

              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 Enforcer running, you will  instead  want  to  use  the  two-phase  backup
              prepare followed by either backup commit or backup rollback.

       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 consistent state by taking a lock out first.  The
              --output  option specifies where the output should go; if not specified, the output
              goes to the usual enforcer.db.backup file.

PROCESS CONTROL SUBCOMMANDS

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

KEY STATES

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

       PUBLISH
              The key has been published in the parent zone.

       READY  The key is ready for use. E.g. according to settings in the policy the key has been
              published for long enough to have propagated 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.

KEY TYPES

       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.

INTERVAL FORMAT

       When specifying an interval for a key generation run the ISO 8601 standard 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.

TIME FORMATS

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

       YYYYMMDD[HH[MM[SS]]]
              (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)

FILES

       /etc/opendnssec/conf.xml
              The main configuration file for OpenDNSSEC.

       /etc/opendnssec/zonelist.xml
              The list of zones, as defined in conf.xml.

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

       /var/lib/opendnssec/enforcer.db.backup
              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.

       /var/lib/opendnssec/unsigned/
              The location that is usually configured in conf.xml to contain unsigned zones.

       /var/lib/opendnssec/signed/
              The location that is usually configured in conf.xml to contain signed zones.

SEE ALSO

       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), http://www.opendnssec.org/

AUTHOR

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