table of contents
other versions
- wheezy 1:1.3.9-5
- wheezy-backports 1:1.4.5-6~bpo70+1
- jessie 1:1.4.6-6
- testing 1:2.0.4-3
- unstable 1:2.0.4-3
conflicting packages
ods-ksmutil(1) | OpenDNSSEC ods-ksmutil | ods-ksmutil(1) |
NAME¶
ods-ksmutil - OpenDNSSEC zone and key managementSYNOPSIS¶
ods-ksmutil setupDESCRIPTION¶
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.
- 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.
- 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.
- 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.)
- 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.
- 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.
- key delete --cka_id|-k ckaid [--no-hsm]
- Remove a named key from the system.
- 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 *
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*
- 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).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.February 2010 | OpenDNSSEC |