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.