Provided by: opendnssec-enforcer-mysql_1.4.9-2_amd64 
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 respective configuration 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 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 (should be DNS or File, 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] [--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 displayed.
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 --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 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.