How to add a new parameter to an existing model

Introduction

This page explains with an example how to improve an existing model.

This example is based on OpenSsh model before major version 2. Now OpenSsh model is generated from its documentation, so this example is not really useful for OpenSsh. But it can be useful for models written manually.

What was wrong with OpenSsh model ?

A while ago, a ssh_config file containing the ControlPersist parameter triggered an error. This parameter was missing from OpenSsh model.

Let's see how this was fixed.

get the source Luke

First get the source code for the model. The easiest way is to fork the git repository on github. The repository to fork is mentioned in Config::Model::OpenSsh man page. Once forked, you will have to clone it on your machine:

git clone git://github.com/your-login/config-model-openssh.git

install required tools

Then to update the OpenSsh model, you must install a GUI that will help you in this task. This GUI is provided by Config::Model::Itself. On Debian/Ubuntu, you can install it with

sudo aptitude install libconfig-model-itself-perl

Otherwise, use cpanm.

Launch the GUI

In the directory config-model-openssh installed by git, run

cme meta edit 

If your version of Config::Model::Itself is before 2.001, run:

    config-model-edit -model Ssh

You should get this window:

Click on the [+] box besides class to get the list of configuration classes provided with OpenSsh model:

Search for sibling of ControlPersist

This still does not tell us where to put the new parameters. Since the new parameter is listed in the man pages right after ControlPath, the best is to place the new ControlPersist parameter right after ControlPath.

Let's search for ControlPath in the GUI. Use menu Edit→Find and type "ControlPath" in the bottom field:

Click on "next" and you will land in the description field of the "ControlMaster" parameter. Why ? Because its description mentions ControlPath.

Create ControlPersist element

Now, use the scroller on the left to go to the "element" parent node and right click on it. You will get on the right of the window a widget to edit the content of "element" so you can add "ControlPersist":

In this widget, select "ControlPath", type "ControlPersist" in the edit field:

and click on the big green arrow. This will insert the new "ControlPersist" element right after "ControlPath". On the widget on left side, open "ControlPersist" and right click on it:

The red cross means that some mandatory parameter must be filled. Use the drop down menu to set type to "leaf":

Setting type to "leaf" will bring another mandatory parameter: "value_type". To go on, one must read ssh_config documentation to find the best fit for "ControlPersist" parameter. In this case, "ControlPersist" can be "yes", "no" or a time (integer). So the value type must be set to "uniline". We'll see how to specify some sanity check later for this value.

Now, let's set up some documentation for the end user, i.e. set up the summary and description parameter so the configuration editor for ssh_config you're modifying will provide some online help for the new "ControlPersist" parameter.

• right click on ControlPersist's "summary"
• write some text in "Value" field on the right
• click on "Store"

Then let's provide more detailed documentation. The easiest way is to cut'n'paste the man page into the GUI:

• run man -E ascii ssh_config (The -E option avoids needlessly embedding UTF-8 characters)
• search "ControlPersist" parameter
• cut the text from the man page
• paste it (middle click) right on ControlPersist's "description" on the left side of the window
• right click on "description" to plish the text
• click on "cleanup" to remove extra white space
• Optionaly, click on "external editor" to perform further editing
• click on "store"

View the updated GUI

You can also directly view the ssh_config GUI with the new parameter you entered with with Model→test:

Save and test the modified model

Now let's save and quit the new model with the menu File→quit.

To really make sure that nothing is broken, you should run the non-regression tests with the prove command:

$ prove -l t
t/augeas_match.t ....... ok   
t/augeas_sshd.t ........ ok   
t/custom_sshd.t ........ ok   
t/custom_sshd_match.t .. ok   
t/model_tests.t ........ 1/? Element 'AuthorizedKeysFile2' of node 'Sshd' is deprecated
Unhandled type: GLOB at /usr/share/perl5/Devel/Cycle.pm line 107.
t/model_tests.t ........ ok    
t/pod.t ................ ok     
t/ssh_config.t ......... ok     
All tests successful.
Files=7, Tests=70,  9 wallclock secs ( 0.07 usr  0.01 sys +  7.16 cusr  0.28 csys =  7.52 CPU)
Result: PASS

The few warnings are normal and are part of the tests.

And you're done. Once the test run, you can send your work with git push on your repository and send a pull request.

Option: add sanity check to validate ControlPersist content

We've seen above that "ControlPersist" legal value are rather peculiar: it's a mix of boolean ("yes" or "no") and integer. Here's a way to make cme check this value. We'll set it up so an error is raised if the value does not match what is expected:

• Go back to editing the "ControlPersist" parameter in ssh model.
• Make sure that Options->experience is set to master
• right click the match parameter
• enter and store ^(?i)yes|no|\d+$ in the value box. This regular expression will return false if ControlPersist value is not legal. See perl regular expression documentation for more details.