[Opendnssec-develop] Unified Control Program (was -a vs --all)
Stephen.Morris at nominet.org.uk
Stephen.Morris at nominet.org.uk
Fri Aug 21 14:49:18 UTC 2009
sion at nominet.org.uk wrote on 21/08/2009 10:02:28:
> I hesitate to start this discussion as it has caused small wars in the
> We have a number of components that take command line arguments, and I
> think that we should be consistent in both style and meaning of flags. I
> wouldn't expect -v to mean verbose in one place and version in another;
> similarly I wouldn't expect to have to type -v in one place and
> in another.
> So, do we need a central list of what options we have used, and what
> mean? And do we need to decide between short and long options (or decide
> that we want both to always work?)
> I'm happy with either type, so long as we are consistent. Or you can
> me that I am worrying about nothing.
No, you are not worrying about nothing. This is something I have been
considering in drawing up requirements for a unified control program. I
think consistency is very important - as well as making the software
easier to use, it makes it look more professional. (In particular, it
makes it look as though the authors have talked to one another :-)
I haven't yet entered the story for the control program as I wanted to get
some idea of what it should do first. My initial thoughts are listed
=== First Draft of Uniform Control Program Requirements ===
Integrated Command Language Interpreter
A tool (or set of tools) to effectively manage OpenDNSSEC requires the
* Able to display information about the system (e.g. display the zones
being signed and the signing schedule)
* Able to control the system (e.g. start and stop the system)
* Able to configure the system (e.g. able to set signing policy
At present, the alpha version of OpenDNSSEC has a set of command-line
programs (ksmutil, signer_engine_cli, etc.), each providing part of this
functionality. To improve usability, a single, integrated control program
is required. For simplicity, and to ensure that it works on as many
systems as possible with relatively little development effort (as well as
allowing it to be integrated into users' scripts), the system should be
The document describes the functionality of such an application (called,
for the purposes of this document, "odctl" [OpenDNSSEC Control]).
As noted above, a management program requires the ability to configure the
system. In the current version of OpenDNSSEC, configuration options are
held in three files:
kasp.xml: this describes signing policies. At present, it must be
zonelist.xml: list of zones to be signed together with the policies
associated with the zones and the location of the signed and unsigned
files. This is produced by the user (or user's systems); when changed, it
is imported into the system via the "update" command.
Note that the zonelist.xml is the master list of zones being signed by the
system. In environments where zones are frequently added and removed, it
is expected that zonelist file will be maintained by the user's own
conf.xml: contains parameters for the daemons (how they run, where they
log, etc.) At present, it must be hand-edited.
For the first release, it is proposed that odctl does not include any
ability to configure the system. This is for several reasons:
a) It is possible to edit the configuration files by hand. For small
files, this is feasible, especially as it is unlikely that the
configurations will be frequently changed. Larger files are more
difficult to edit and a tool would be useful. However, this entails
addition work and effort, whilst the first production version of the
software is being developed, is better targeted elsewhere.
c) It is not clear that a CLI is the best way to edit the structured data
in the configuration files - a GUI may be a better option, although this
will entail much more work.
b) The configuration files are still being altered as development
proceeds. It will be better to wait until the format and contents have
It is suggested that any form of CLI be available in both single-command
mode and subsystem mode.
In subsystem mode, running the CLI enters a command subsystem which
prompts the user for commands, e.g.
% odctl [command switches]
odctl> list <list parameters>
odctl> <other commands>
Single command mode is of the form:
% odctl [command switches] list <list parameters>
... which will invoke the odctl program, run the command (in this case,
"addzone") and exit odctl, returning control to the shell prompt.
In practice, odctl will be a thin layer over functions in the OpenDNSSEC
libraries; there should be little (if anything) that odctl does that
cannot be done by calling one of the library functions (this will
facilitate the creation of a GUI interface).
a) Starting odctl
The control program is started by the command:
% odctl [-c <config_dir>] [command]
Specifies the name of the directory holding the conf.xml file. If not
specified, the default installation directory is assumed.
Optional command. If specified, the command is executed and the program
terminates. Otherwise it prompts at the command terminal.
b) Commands Related to odctl Itself
Exits the program.
Lists a summary of the commands. Help for each command is obtained by
issuing the command with the "-h" switch, e.g. "addzone -h" gives help for
the "addzone" command.
odctl> source <file>
Reads and executes odctl commands from the given file. (The commands
should be echoed to stdout before execution.)
c) Commands Related to The Whole System
Some command to instantly see the current status of the system is needed -
we should not require the user to do a "ps" and search for the various
odctl> status [-s] [-k] ...
Prints out the status of the system. If no switches are specified, all
are assumed. The listing comprises various sections:
-r: Lists the key repositories in the system
-s: Displays status of the running system. Outputs something along the
-k: Displays the status of keys in the system.
[TBD - more details from the ksmutil listing]
-q: Displays the signer's task queue
-z: Lists all zones known to the system.
c.2) Starting and Stopping the System
Given that some systems use the "init" style to start daemon processes and
others (such as OS/X and Solaris) use operating system-specific tools, a
common interface simplifies operation.
Possible commands are:
odctl> start [-p hsm_password] [component]
Starts the system. If the HSM password is not supplied, prompts the user.
The optional "component" parameter (something like "signer", "auditor"
etc.) allows single components to be started in isolation.
odctl> stop [component]
Stops all the daemon processes in a controlled fashion but, if there is no
response from a process, executes a "kill -9" on it. The optional
"component" parameter allows single components to be halted.
odctl> restart [component]
Executes a "stop" and, when everything has halted, executes a "start". The
optional "component" parameter allows single components to be restarted.
(Using "restart" - rather than "stop" and "start" means that the password
does not have to be re-entered.)
d) Component-Related Commands
As the system comprises different components, each with its own functions,
inevitably each component will require a set of component-specific
commands. The CLI includes functions currently handled by separate
programs, but ensuring syntax and semantic consistency.
d.1) Enforcer Commands
This is basically the set of commands available via ksmutil and sets up
the policy database:
odctl> dbinit [-f]
The equivalent of the "setup" command. I suggest "dbinit" as that implies
initialization and is more associated with wiping the current contents of
something than the command "setup". The command should prompt for
confirmation before taking the action, unless "-f" (force) is given.
It both wipes the current data from the database and initializes the
tables, i.e. it does a "DROP TABLE IF EXISTS..." before executing a
"CREATE TABLE" command.
Updates the database from the configuration directory. (This should be
called by the users' systems whenever zonelist.xml is altered.)
odctl> dbexport [-o file] <policy>
Export all policies [or named policy] to xml (in kasp.xml format). If the
output file is not specified, the XML is listed to stdout.
odctl> roll -z [-t ksk | -t zsk] <zone>
odctl> roll -p [-t ksk | -t zsk] <policy>
Rolls the keys on a zone (with "roll -z") or on a policy (with "roll -p").
The "-t ksk" or "-t zsk" switches specify the type of key to roll. Both
are rolled if nothing is specified. After running the rollover the
communicator will be woken up so that the signer can be sent the new
If an attempt is made to roll a zone for which keys are shared, a warning
will be output that all zones on the policy should be rolled and the
operation is abandoned.
A backup of the sqlite DB file is made (if appropriate).
odctl> bckdone [-d date] [repository]
Sets the most recent backup date for keys in the repository (all
repositories if no repository is listed) for which no backup has been
performed to the specified date, or to the current date if no date is
odctl> purge [zone]
Removes dead keys from the database for the specified zone (all zones if
d.2) Signer Commands
These are the functions available from the signer_engine_cli. Note that
the "queue" command has been subsumed into odctl "list" command.
odctl> sign [zone]
Schedules the zone (all zones if no parameter given) for immediate
d.3) HSM Commands
All HSM access is done by the components through library functions.
Initializing the HSM and other maintenance tasks will be done with
HSM-specific control programs.
d.4) Auditor Commands
odctl> audit <percent> [zone]
Sets the auditing level for a zone (or all zones if no zone is given).
<percent> ranges between 0 (disabling the auditor) and 100 (fully-enabling
[To be completed]
List of Command Flags
-o: Output file
-t: Key type
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Opendnssec-develop