<tt><font size=2>sion@nominet.org.uk wrote on 21/08/2009 10:02:28:<br>
<br>
> I hesitate to start this discussion as it has caused small wars in
the<br>
> past...<br>
> <br>
> We have a number of components that take command line arguments, and
I<br>
> think that we should be consistent in both style and meaning of flags.
I<br>
> wouldn't expect -v to mean verbose in one place and version in another;<br>
> similarly I wouldn't expect to have to type -v in one place and --version<br>
> in another.<br>
> <br>
> So, do we need a central list of what options we have used, and what
they<br>
> mean? And do we need to decide between short and long options (or
decide<br>
> that we want both to always work?)<br>
> <br>
> I'm happy with either type, so long as we are consistent. Or you can
tell<br>
> me that I am worrying about nothing.<br>
</font></tt>
<br><tt><font size=2>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 :-)</font></tt>
<br>
<br><tt><font size=2>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 below.</font></tt>
<br>
<br><tt><font size=2>Comments?</font></tt>
<br>
<br><tt><font size=2>Stephen</font></tt>
<br>
<br>
<br>
<br><tt><font size=2>=== First Draft of Uniform Control Program Requirements
===</font></tt>
<br>
<br><tt><font size=2>Integrated Command Language Interpreter</font></tt>
<br>
<br><tt><font size=2>Background</font></tt>
<br><tt><font size=2>==========</font></tt>
<br><tt><font size=2>A tool (or set of tools) to effectively manage OpenDNSSEC
requires the following capabilities:</font></tt>
<br>
<br><tt><font size=2>* Able to display information about the system (e.g.
display the zones being signed and the signing schedule)</font></tt>
<br><tt><font size=2>* Able to control the system (e.g. start and stop
the system)</font></tt>
<br><tt><font size=2>* Able to configure the system (e.g. able to set signing
policy parameters)</font></tt>
<br>
<br><tt><font size=2>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 command-line based.</font></tt>
<br>
<br><tt><font size=2>The document describes the functionality of such an
application (called, for the purposes of this document, "odctl"
[OpenDNSSEC Control]).</font></tt>
<br>
<br>
<br>
<br><tt><font size=2>Scope</font></tt>
<br><tt><font size=2>=====</font></tt>
<br><tt><font size=2>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:</font></tt>
<br>
<br><tt><font size=2>kasp.xml: this describes signing policies. At
present, it must be hand-edited.</font></tt>
<br>
<br><tt><font size=2>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.</font></tt>
<br>
<br><tt><font size=2>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 systems.</font></tt>
<br><tt><font size=2> </font></tt>
<br><tt><font size=2>conf.xml: contains parameters for the daemons (how
they run, where they log, etc.) At present, it must be hand-edited.</font></tt>
<br>
<br>
<br><tt><font size=2>For the first release, it is proposed that odctl does
not include any ability to configure the system. This is for several
reasons:</font></tt>
<br>
<br><tt><font size=2>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.</font></tt>
<br><tt><font size=2>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.</font></tt>
<br><tt><font size=2>b) The configuration files are still being altered
as development proceeds. It will be better to wait until the format
and contents have settled down.</font></tt>
<br>
<br>
<br>
<br><tt><font size=2>CLI Basics</font></tt>
<br><tt><font size=2>==========</font></tt>
<br><tt><font size=2>It is suggested that any form of CLI be available
in both single-command mode and subsystem mode.</font></tt>
<br>
<br><tt><font size=2>In subsystem mode, running the CLI enters a command
subsystem which prompts the user for commands, e.g.</font></tt>
<br>
<br><tt><font size=2> % odctl [command switches]</font></tt>
<br><tt><font size=2> odctl> list <list parameters></font></tt>
<br><tt><font size=2> odctl> <other commands></font></tt>
<br><tt><font size=2> :</font></tt>
<br><tt><font size=2> odctl> quit</font></tt>
<br><tt><font size=2> %</font></tt>
<br>
<br><tt><font size=2>Single command mode is of the form:</font></tt>
<br>
<br><tt><font size=2> % odctl [command switches] list <list
parameters></font></tt>
<br>
<br><tt><font size=2>... which will invoke the odctl program, run the command
(in this case, "addzone") and exit odctl, returning control to
the shell prompt.</font></tt>
<br>
<br><tt><font size=2>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).</font></tt>
<br>
<br>
<br><tt><font size=2>Functions</font></tt>
<br><tt><font size=2>=========</font></tt>
<br>
<br><tt><font size=2>a) Starting odctl</font></tt>
<br><tt><font size=2>-----------------</font></tt>
<br><tt><font size=2>The control program is started by the command:</font></tt>
<br>
<br><tt><font size=2>% odctl [-c <config_dir>] [command]</font></tt>
<br>
<br><tt><font size=2>where:</font></tt>
<br>
<br><tt><font size=2>-c <config_dir></font></tt>
<br><tt><font size=2>Specifies the name of the directory holding the conf.xml
file. If not specified, the default installation directory is assumed.</font></tt>
<br>
<br><tt><font size=2>[command]</font></tt>
<br><tt><font size=2>Optional command. If specified, the command
is executed and the program terminates. Otherwise it prompts at the
command terminal.</font></tt>
<br>
<br>
<br>
<br><tt><font size=2>b) Commands Related to odctl Itself</font></tt>
<br><tt><font size=2>-----------------------------------</font></tt>
<br>
<br><tt><font size=2>odctl> quit</font></tt>
<br><tt><font size=2>Exits the program.</font></tt>
<br>
<br><tt><font size=2>odctl> help</font></tt>
<br><tt><font size=2>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.</font></tt>
<br>
<br><tt><font size=2>odctl> source <file></font></tt>
<br><tt><font size=2>Reads and executes odctl commands from the given file.
(The commands should be echoed to stdout before execution.)</font></tt>
<br>
<br>
<br>
<br><tt><font size=2>c) Commands Related to The Whole System</font></tt>
<br><tt><font size=2>---------------------------------------</font></tt>
<br>
<br><tt><font size=2>c.1) Information</font></tt>
<br><tt><font size=2>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 daemons.</font></tt>
<br>
<br><tt><font size=2>odctl> status [-s] [-k] ...</font></tt>
<br><tt><font size=2>Prints out the status of the system. If no switches
are specified, all are assumed. The listing comprises various sections:</font></tt>
<br>
<br><tt><font size=2>-r: Lists the key repositories in the system</font></tt>
<br>
<br><tt><font size=2>-s: Displays status of the running system. Outputs
something along the lines of:</font></tt>
<br>
<br><tt><font size=2>Signer: Running</font></tt>
<br><tt><font size=2>Enforcer: Running</font></tt>
<br><tt><font size=2>Auditor: Running</font></tt>
<br><tt><font size=2> : :</font></tt>
<br>
<br><tt><font size=2>-k: Displays the status of keys in the system.</font></tt>
<br><tt><font size=2>[TBD - more details from the ksmutil listing]</font></tt>
<br>
<br><tt><font size=2>-q: Displays the signer's task queue</font></tt>
<br>
<br><tt><font size=2>-z: Lists all zones known to the system.</font></tt>
<br>
<br>
<br><tt><font size=2>c.2) Starting and Stopping the System</font></tt>
<br><tt><font size=2>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.</font></tt>
<br>
<br><tt><font size=2>Possible commands are:</font></tt>
<br>
<br><tt><font size=2>odctl> start [-p hsm_password] [component]</font></tt>
<br><tt><font size=2>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.</font></tt>
<br><tt><font size=2> </font></tt>
<br><tt><font size=2>odctl> stop [component]</font></tt>
<br><tt><font size=2>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.</font></tt>
<br>
<br><tt><font size=2>odctl> restart [component]</font></tt>
<br><tt><font size=2>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.)</font></tt>
<br>
<br>
<br>
<br><tt><font size=2>d) Component-Related Commands</font></tt>
<br><tt><font size=2>-----------------------------</font></tt>
<br><tt><font size=2>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. </font></tt>
<br>
<br>
<br><tt><font size=2>d.1) Enforcer Commands</font></tt>
<br><tt><font size=2>This is basically the set of commands available via
ksmutil and sets up the policy database:</font></tt>
<br>
<br><tt><font size=2>odctl> dbinit [-f]</font></tt>
<br><tt><font size=2>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.</font></tt>
<br>
<br><tt><font size=2>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.</font></tt>
<br>
<br>
<br><tt><font size=2>odctl> update</font></tt>
<br><tt><font size=2>Updates the database from the configuration directory.
(This should be called by the users' systems whenever zonelist.xml
is altered.)</font></tt>
<br>
<br>
<br><tt><font size=2>odctl> dbexport [-o file] <policy></font></tt>
<br><tt><font size=2>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.</font></tt>
<br>
<br>
<br><tt><font size=2>odctl> roll -z [-t ksk | -t zsk] <zone></font></tt>
<br><tt><font size=2>odctl> roll -p [-t ksk | -t zsk] <policy></font></tt>
<br><tt><font size=2>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 information.</font></tt>
<br>
<br><tt><font size=2>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.</font></tt>
<br>
<br><tt><font size=2>A backup of the sqlite DB file is made (if appropriate).</font></tt>
<br>
<br>
<br><tt><font size=2>odctl> bckdone [-d date] [repository]</font></tt>
<br><tt><font size=2>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 specified.</font></tt>
<br>
<br>
<br><tt><font size=2>odctl> purge [zone]</font></tt>
<br><tt><font size=2>Removes dead keys from the database for the specified
zone (all zones if nothing given).</font></tt>
<br>
<br>
<br><tt><font size=2>d.2) Signer Commands</font></tt>
<br><tt><font size=2>These are the functions available from the signer_engine_cli.
Note that the "queue" command has been subsumed into odctl
"list" command.</font></tt>
<br>
<br><tt><font size=2>odctl> sign [zone]</font></tt>
<br><tt><font size=2>Schedules the zone (all zones if no parameter given)
for immediate signing.</font></tt>
<br>
<br>
<br><tt><font size=2>d.3) HSM Commands</font></tt>
<br><tt><font size=2>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.</font></tt>
<br>
<br>
<br><tt><font size=2>d.4) Auditor Commands</font></tt>
<br><tt><font size=2>---------------------</font></tt>
<br>
<br><tt><font size=2>odctl> audit <percent> [zone]</font></tt>
<br><tt><font size=2>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 it). </font></tt>
<br>
<br><tt><font size=2>[To be completed]</font></tt>
<br>
<br><tt><font size=2>List of Command Flags</font></tt>
<br><tt><font size=2>=====================</font></tt>
<br><tt><font size=2>-d: Date</font></tt>
<br><tt><font size=2>-f: "Force"</font></tt>
<br><tt><font size=2>-h: Help</font></tt>
<br><tt><font size=2>-k: Key</font></tt>
<br><tt><font size=2>-o: Output file</font></tt>
<br><tt><font size=2>-p: Policy</font></tt>
<br><tt><font size=2>-q: Queue</font></tt>
<br><tt><font size=2>-r: Repository</font></tt>
<br><tt><font size=2>-s: Status</font></tt>
<br><tt><font size=2>-t: Key type</font></tt>
<br><tt><font size=2>-z: Zone</font></tt>