1ods-ksmutil(1)              OpenDNSSEC ods-ksmutil              ods-ksmutil(1)
2
3
4

NAME

6       ods-ksmutil - OpenDNSSEC zone and key management
7

SYNOPSIS

9       ods-ksmutil setup
10       ods-ksmutil start|stop|notify
11       ods-ksmutil update kasp|zonelist|conf|all
12       ods-ksmutil zone add|delete|list ...
13       ods-ksmutil zonelist import|export
14       ods-ksmutil                          key                         gener‐
15       ate|import|export|list|purge|rollover|ksk-retire|ds-seen|delete ...
16       ods-ksmutil rollover list ...
17       ods-ksmutil policy export|import|purge ...
18       ods-ksmutil repository list ...
19       ods-ksmutil backup list|prepare|commit|rollback|done
20       ods-ksmutil database backup ...
21

DESCRIPTION

23       ods-ksmutil manages the operation of the KASP Enforcer,  which  is  the
24       part  of OpenDNSSEC that triggers key generation and signing operations
25       on domains based on policies  with  user-defined  timing  and  security
26       requirements.   Since everything beyond this management utility is usu‐
27       ally  automatic,  ods-ksmutil  is  the  primary   tool   for   managing
28       OpenDNSSEC.   Among  the  functions  of ods-ksmutil are key management,
29       updates to the zone list and manually  rolling  keys  to  recover  from
30       exceptional situations like key loss.
31
32       To  get started, a first invocation of ods-ksmutil setup is needed; see
33       SETUP AND UPDATE COMMANDS below for details.  After this is  done,  the
34       rest of the functionality of ods-ksmutil becomes available.
35
36       The  following  sections  discuss  the  subcommands  in logical groups,
37       detailing any options that they support.
38

GENERIC OPTIONS

40       -c configfile, --config configfile
41              Change the conf.xml file that is used from the default.
42
43       help   This can be used as a subcommand to ods-ksmutil  or  it  can  be
44              used  after a partial subcommand.  In response, ods-ksmutil will
45              give a synopsis of how to continue the command.
46
47       -V, --version
48              Display version number
49

SETUP AND UPDATE SUBCOMMANDS

51       setup  Import conf.xml, kasp.xml  and  zonelist.xml  into  a  database.
52              This  deletes  any current management information from the data‐
53              base with OpenDNSSEC management information, including any  ref‐
54              erences  to keys.  Updates to an existing setup should therefore
55              not normally run this subcommand, but update instead.
56
57       update kasp
58
59       update zonelist
60
61       update conf
62
63       update all
64              Update the database with the contents of the respective configu‐
65              ration  file,  or  all those files.  The result is comparable to
66              the setup subcommand, except that management  information  about
67              OpenDNSSEC  is  not deleted.(Also note that update kasp does not
68              remove any policies from the database, policy purge can be  used
69              to remove unused policies).
70

ZONE MANAGEMENT SUBCOMMANDS

72       zone   add   --zone|-z  zone  [--policy|-p  name]  [--in-type|-j  type]
73       [--out-type|-q type] [--input|-i input] [--output|-o output] [--no-xml]
74              Add a zone to both  zonelist.xml  and  the  database.   This  is
75              equivalent to manually editing zonelist.xml and then running the
76              update zonelist subcommand.  The --zone option names the zone to
77              add;  the  --policy  option  names  the policy to use instead of
78              default; the --in-type and --out-type specify the type of  input
79              and  output  adapters  (should be DNS or File, default is File);
80              the --input option specifies a  non-standard  location  for  the
81              unsigned  zone (default is /var/opendnssec/unsigned/ZONE) or the
82              DNS input file(default is /etc/opendnssec/addns.xml); the --out‐
83              put option specifies a non-standard location for the signed zone
84              (default  is  /var/opendnssec/signed/ZONE)  or  the  DNS  output
85              file(default  is  /etc/opendnssec/addns.xml).  The --no-xml flag
86              stops the zonelist.xml file from being updated. This is suitable
87              for a batch mode where you will add multiple zones and then just
88              write zonelist once at the end.
89
90       zone delete --zone|-z name [--no-xml]
91
92       zone delete --all|-a
93              Delete  one  zone  (or  all  zones,  respectively)   from   both
94              zonelist.xml  and  the database.  This is equivalent to manually
95              editing zonelist.xml and then running the update  zonelist  sub‐
96              command.   The  --no-xml  flag  stops the zonelist.xml file from
97              being updated. This is suitable for a batch mode where you  will
98              delete  multiple  zones and then just write zonelist once at the
99              end.
100
101       zone list
102              List zones from the zonelist.xml.  TODO:Not from the database?
103
104       zonelist export
105              Export list of zones from the database in  the  same  format  as
106              zonelist.xml
107
108       zonelist import
109              Synchronise  the  database  with  the  contents of zonelist.xml;
110              identical to "update zonelist"
111

KEY MANAGEMENT SUBCOMMANDS

113       key generate --policy|-p name  --interval|-n  interval  [--zonetotal|-Z
114       zonetotal]
115              Create  enough  keys for the named policy to last for the period
116              of time given by interval.  See INTERVAL FORMAT for  the  format
117              of timing specifications.
118
119              If configured to, OpenDNSSEC will automatically create keys when
120              the need arises.  This command can be used to  pregenerate  keys
121              (maybe  for the expected lifetime of an HSM) to help with backup
122              policies.  It is also a convenient method of pregenerating a set
123              of  keys to allow a disaster recovery site to have a copy of the
124              keys without needed to synchronise keys generated on the fly.
125
126              By default the command generates keys for all the zones found on
127              the  specified  policy. If the optional parameter --zonetotal is
128              specified then keys will be generated for that total  number  of
129              zones, regardless of how many are actually currently on the pol‐
130              icy.
131
132       key import --algorithm|-g algname --bits|-b bits  --repository|-r  repo
133       --cka_id|-k  ckaid --zone|-z zone --keytype|-t type --keystate|-e state
134       --time|-w  time  [--check-repository|-C  checkrepository]  [--retire|-y
135       time]
136              Add  a key which was created outside of the OpenDNSSEC code into
137              the database.  In doing so, the further details involved in  key
138              management must be specified in options.
139
140              The  --algorithm  option names the algorithm used with this key;
141              the --bits specifies the strength of this  algorithm  as  a  key
142              size in bits.
143
144              The  --repository  option  names the repository in which the key
145              should be stored; the --cka_id option specifies  the  name  that
146              will be used to identify this key in that repository; the --zone
147              option specifies the zone for which this key is to be used;  the
148              --keytype  option  specifies  whether this key should serve as a
149              KSK or a ZSK.  See KEY TYPES below for an introduction to  these
150              terms.
151
152              The  --keystate option specifies the state in which the key will
153              be after import, and must be one of the options defined  in  the
154              KEY  STATES section below.  the --time option specifies the time
155              that this key was created; the --check-repository option  speci‐
156              fied that the key import should fail if no matching key with the
157              specified cka_id exists in the Repository.  the --retire  option
158              specifies  the  time that this key should be retired. These last
159              two options take the formats given in the TIME  FORMATS  section
160              below.
161
162       key  export  --zone|-z  name  [--keystate|-e state] [--keytype|-t type]
163       [--ds]
164
165       key export --all [--keystate|-e state] [--keytype|-t type] [--ds]
166              Export the keys for a particular zone, or for all zones  respec‐
167              tively,  from  the  database.   The  --ds  option can be used to
168              retrieve DS records for upload to a registry instead of the full
169              key;  the  --keystate  option can be used to limit the output to
170              keys in a given state; the --keytype option can be used to limit
171              the  output  to keys of a given type.  See the KEY TYPES and KEY
172              STATES sections below for a specification of possible key  types
173              and states.
174
175       key  list  [--zone  name]  [--verbose]  [--keystate|--all|-e  state|-a]
176       [--keytype type|-t type]
177              List information about keys in all zones,  or  in  a  particular
178              zone.  By  default  keys  in the GENERATE and DEAD state are not
179              displayed.
180
181              The --verbose option is  used  to  list  additional  information
182              about each key.
183
184              The --keystate option can be used to limit the output to keys in
185              a given state. If the --all option is  used  then  keys  in  all
186              states  (including GENERATE and DEAD) are displayed.  The --key‐
187              type option can be used to limit the output to keys of  a  given
188              type.   See  the  KEY  TYPES and KEY STATES sections below for a
189              specification of possible key types and states.
190
191       key purge --zone|-z name
192
193       key purge --policy|-p name
194              Remove any keys in the Dead state from the repository  and  from
195              the  database  of  the  KASP  Enforcer.   The options --zone and
196              --policy are used to limit this operation to a single named zone
197              or policy, respectively.
198
199       key rollover --zone|-z name --keytype type|-t type
200
201       key rollover --zone|-z name --all|-a
202
203       key rollover --policy|-p name --keytype type|-t type
204
205       key rollover --policy|-p name --all|-a
206              Rollover  active keys on the named zone or policy, respectively.
207              This command is used to intiate manual rollovers; if it  is  not
208              given, OpenDNSSEC will automatically rollover keys when the need
209              arises. (Or, in the case of KSKs  it  will  start  the  rollover
210              process, to finish the KSK rollover see ksk-roll below.)
211
212              The --keytype option specifies the type of key to roll. Alterna‐
213              tively the --all option can be used which will roll  both  types
214              of  keys.  After  running, the KASP Enforcer will be woken up so
215              that the signer can be sent the new information.
216
217              If the policy that the zone is on specifies that keys are shared
218              then  all zones on that policy will be rolled. If appropriate, a
219              backup of the sqlite DB file is made.
220
221              If there are no keys ready to take over  from  the  current  key
222              then  the  rollover  will not occur immediately, but will be put
223              off until the is a key in the ready state.
224
225
226       key ksk-retire --zone|-z zone
227
228       key ksk-retire --keytag|-x keytag
229
230       key ksk-retire --cka_id|-k ckaid
231              Indicate to OpenDNSSEC that a currently  active  key  should  be
232              retired.   If  key  identifiers are not provided then the oldest
233              key in the zone will be retired.
234
235              If only one key is in the active state then  this  command  will
236              exit  with an error message, as completing would leave no active
237              keys.
238
239
240       key  ds-seen  --zone|-z  zone   --keytag|-x   keytag   [--no-notify|-l]
241       [--no-retire|-f]
242
243       key   ds-seen   --zone|-z   zone   --cka_id|-k  ckaid  [--no-notify|-l]
244       [--no-retire|-f]
245              Indicate to OpenDNSSEC that a submitted DS record  has  appeared
246              in  the parent zone, and thereby trigger the completion of a KSK
247              rollover.  Note that this action is not  yet  standardised,  and
248              can  therefore  not be solved in a generic, automatic way.  This
249              command was designed for inclusion  in  any  personalised  setup
250              that may or may not be automated.
251
252              There  are  several  ways to specify which DS is in DNS, and the
253              options reflect these alternatives.  The --keytag option  speci‐
254              fies  the short integer that serves as a DNSSEC handle to a key;
255              the --cka_id option refers to a key by way of its long hexadeci‐
256              mal identifier used to identify the key in the repository.
257
258              An  optional  --no-notify flag can also be passed in, which pre‐
259              vents the enforcer being notified of this change. If  this  flag
260              is  used  then  the  enforcer must be manually notified with the
261              'ods-enforcerd notify' command or  the  changes  will  not  take
262              effect until the next scheduled run of the enforcer.
263
264              An optional --no-retire flag can also be passed in, without this
265              the existing key is moved into the retired  state  at  the  same
266              time  as  making  the  new key active. If you wish to delay this
267              step then pass in this flag and use the ksk-retire command  when
268              needed.
269
270
271       key delete --cka_id|-k ckaid [--no-hsm]
272              Remove a named key from the system.
273
274              Keys  in  the  GENERATE or DEAD state can be safely removed from
275              the system as they are not in use.
276
277              The --no-hsm flag can be provided if you want to leave  the  key
278              material on the HSM.
279
280
281       rollover list
282              List  the  expected dates and times of upcoming rollovers.  This
283              can be used to get  an  idea  of  upcoming  work,  such  as  the
284              non-standardised submission of DS records to a registry.
285

POLICY ADMINISTRATION SUBCOMMANDS

287       policy export [--policy|--all|-p|-a]
288              Export  a  policy  from  the  database in the same format as the
289              kasp.xml file.
290
291       policy import
292              Update the database with the contents of kasp.xml; identical  to
293              "update kasp".
294
295       policy purge
296              * Experimental *
297
298              Remove  any  policies  which have no zones associated with them.
299              Note that this command has only been tested in a lab environment
300              and so caution is recommended.
301

REPOSITORY AND BACKUP SUBCOMMANDS

303       repository list
304              List repositories from the database.
305
306       backup list --repository|-r name
307              List  the  backups  that have been made on the given repository.
308              The --repository option specifies what repository to list.
309
310       backup prepare --repository|-r name
311              Start a two-phase key backup procedure.  Prepare the keys gener‐
312              ated up to here for backup.  Any keys generated automatically by
313              OpenDNSSEC after this command are not guaranteed  to  be  backed
314              up, and will therefore not be taken into account when committing
315              the prepared keys for use by OpenDNSSEC.  The  next  command  is
316              usually  either  backup commit or, in case of failure of the key
317              backup itself, backup rollback.  This sequence works reliably if
318              the  KASP  Enforcer  is running.  If it is not, the single-phase
319              backup of backup done provides a one-phase backup alternative.
320
321       backup commit --repository|-r name
322              Successfully end a two-phase key backup procedure.  After a  key
323              backup  has  succeeded, release all previously prepared keys for
324              service by OpenDNSSEC.  Any keys that were generated  since  the
325              last  issued preparation will not be released as it is uncertain
326              whether these are actually backed up.
327
328       backup rollback --repository|-r name
329              Safely end a failed two-phase key backup procedure.  After a key
330              backup  has  failed,  rollback all previously prepapared keys to
331              the state where they are generated, but not  yet  available  for
332              service by OpenDNSSEC.  After fixing this problem, a new attempt
333              to backup the keys can be made.
334
335       backup done --repository|-r name [--force]
336              *DEPRECATED*
337
338              Indicate that a backup of the given repository  has  been  done,
339              all  non-backed  up  keys  will now be marked as backed up.  The
340              --repository option specifies what repository to list.
341
342              Note that the KASP Enforcer may take the initiative to  generate
343              keys after the backup has started and before the backup is done.
344              This single-phase backup command waives that, which is safe when
345              the  KASP  Enforcer  is  not running.  If you intend to keep the
346              Enforcer running, you will instead want  to  use  the  two-phase
347              backup  prepare followed by either backup commit or backup roll‐
348              back.
349
350       database backup [--output|-o output]
351              Make a copy of the database  of  the  KASP  Enforcer  (if  using
352              sqlite).  This command ensures that the database is in a consis‐
353              tent state by taking a lock  out  first.   The  --output  option
354              specifies where the output should go; if not specified, the out‐
355              put goes to the usual enforcer.db.backup file.
356

PROCESS CONTROL SUBCOMMANDS

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

KEY STATES

362       GENERATE
363              The key has just been generated, but is not ready for use.
364
365       PUBLISH
366              The key has been published in the parent zone.
367
368       READY  The key is ready for use. E.g. according to settings in the pol‐
369              icy  the  key  has been published for long enough to have propa‐
370              gated to all resolvers.
371
372       ACTIVE The key is actively being used to sign one or more zones.
373
374       RETIRE The key has either reached the end of its scheduled life, or  it
375              has been rolled prematurely. However, records signed with it may
376              still be cached sp the key is still being published.
377
378       DEAD   The key has been retired for long enough  that  its  use  is  no
379              longer cached, so it has been removed from the zone.
380

KEY TYPES

382       Keys  can  be  of  two types: KSK or ZSK.  These terms are explained in
383       more detail in opendnssec(1).
384
385       In DNS records, the KSK can usually be recognised  by  having  its  SEP
386       (Secure Entry Point) flag set.  But please note that officially this is
387       a mere hint.
388

INTERVAL FORMAT

390       When specifying an interval for a key generation run the ISO 8601 stan‐
391       dard  is  used, e.g. P2Y6M for 2 years and 6 months; or PT12H30M for 12
392       hours and 30 minutes. Note that a year is assumed to be 365 days and  a
393       month is assumed to be 31 days.
394

TIME FORMATS

396       When  specifying  a generation/retire time for a key being imported the
397       following formats are understood:
398
399       YYYYMMDD[HH[MM[SS]]]
400              (all numeric)
401
402       D-MMM-YYYY[:| ]HH[:MM[:SS]]
403
404       DD-MMM-YYYY[:| ]HH[:MM[:SS]]
405
406       YYYY-MMM-DD[:| ]HH[:MM[:SS]]
407              (alphabetic month)
408
409       D-MM-YYYY[:| ]HH[:MM[:SS]]
410
411       DD-MM-YYYY[:| ]HH[:MM[:SS]]
412
413       YYYY-MM-DD[:| ]HH[:MM[:SS]]
414              (numeric month)
415

FILES

417       /etc/opendnssec/conf.xml
418              The main configuration file for OpenDNSSEC.
419
420       /etc/opendnssec/zonelist.xml
421              The list of zones, as defined in conf.xml.
422
423       /etc/opendnssec/kasp.xml
424              The configuration of policies that define timing  and  security,
425              as defined in conf.xml.
426
427       /var/opendnssec/enforcer.db.backup
428              A  backup  file  of  the database used by the KASP Enforcer.Note
429              that this does not include the keys, which are to  be  extracted
430              from its own repository.
431
432       /var/opendnssec/unsigned/
433              The  location  that is usually configured in conf.xml to contain
434              unsigned zones.
435
436       /var/opendnssec/signed/
437              The location that is usually configured in conf.xml  to  contain
438              signed zones.
439

SEE ALSO

441       ods-control(8),   ods-enforcerd(8),   ods-hsmspeed(1),  ods-hsmutil(1),
442       ods-kaspcheck(1),   ods-signer(8),    ods-signerd(8),    ods-timing(5),
443       opendnssec(7), http://www.opendnssec.org/
444

AUTHOR

446       ods-ksmutil  was  written  by  Sion  Lloyd  and  Nominet as part of the
447       OpenDNSSEC project.
448
449
450
451OpenDNSSEC                       February 2010                  ods-ksmutil(1)
Impressum