Provided by: opendnssec-enforcer_1.3.4-1ubuntu1_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 ...
       ods-ksmutil rollover list ...
       ods-ksmutil policy export|import ...
       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]  [--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 --input option specifies a non-standard location for  the  unsigned
              zone  (default is /var/lib/opendnssec/unsigned/ZONE); the --output option specifies
              a    non-standard    location    for    the     signed     zone     (default     is
              /var/lib/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  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
              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.

       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 [--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 --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]

       key rollover --policy|-p name [--keytype type]
              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 (both are rolled if  nothing
              is  specified) 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 --keytag|-x keytag

       key ds-seen --cka_id|-k ckaid
              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-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.

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

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

AUTHOR

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