[Opendnssec-develop] Unified Control Program (was -a vs --all)

[Stephen.Morris at nominet.org.uk]

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
> past...
> 
> 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 
--version
> in another.
> 
> So, do we need a central list of what options we have used, and what 
they
> 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 
tell
> 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 
below.

Comments?

Stephen



=== First Draft of Uniform Control Program Requirements ===

Integrated Command Language Interpreter

Background
==========
A tool (or set of tools) to effectively manage OpenDNSSEC requires the 
following capabilities:

* 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 
parameters)

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.

The document describes the functionality of such an application (called, 
for the purposes of this document, "odctl" [OpenDNSSEC Control]).



Scope
=====
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 
hand-edited.

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 
systems.
 
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 
settled down.



CLI Basics
==========
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>
              :
   odctl> quit
   %

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).


Functions
=========

a) Starting odctl
-----------------
The control program is started by the command:

% odctl [-c <config_dir>] [command]

where:

-c <config_dir>
Specifies the name of the directory holding the conf.xml file.  If not 
specified, the default installation directory is assumed.

[command]
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
-----------------------------------

odctl> quit
Exits the program.

odctl> help
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
---------------------------------------

c.1) Information
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.

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 
lines of:

Signer:   Running
Enforcer: Running
Auditor:  Running
   :         :

-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.


odctl> update
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 
information.

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 
specified.


odctl> purge [zone]
Removes dead keys from the database for the specified zone (all zones if 
nothing given).


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 
signing.


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 
it). 

[To be completed]

List of Command Flags
=====================
-d: Date
-f: "Force"
-h: Help
-k: Key
-o: Output file
-p: Policy
-q: Queue
-r: Repository
-s: Status
-t: Key type
-z: Zone
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.opendnssec.org/pipermail/opendnssec-develop/attachments/20090821/1a2c7a0c/attachment.htm>