YaST Tutorials

	Important
	Keep in mind that this is only an example, not a real expert configuration tool. Features have been selected to keep the project extremely simple.

Chosen areas of configuration are:

This module will use only two dialogs arranged in a wizard sequence. Both dialogs will be based on the typical YaST dialog with a Back, Abort, and Next buttons and the help text in the frame on the left side of the dialog. These dialogs will be surrounded by Read dialog with a progress bar, where the current configuration is read, and Write dialog where a new configuration is written.

This is the design of the proposed workflow:

This workflow also shows that user can abort the configuration on every screen by clicking the Abort button. After this button is pressed, a pop-up dialog appears asking whether to abort the configuration. When this is confirmed, the configuration is canceled and program is terminated without saving changes.

The first dialog will contain a table of TCP ports used by the SSH daemon and its general features. The second one will contain all login settings.

Drawing of the first dialog:

The Back button will be disabled in the first dialog and the Next button will be replaced with the Accept button in the last dialog as it appears in every YaST module written strictly following the Program Text Style Guide.

Drawing of the second dialog:

This is the way how to install the current state of the project into the system:

	Important
	If there are any problems, it drops out a warning or an error message. Missing development package must be installed, syntax error must be fixed.

Once you have installed it for the first time, you only need to call sudo make install if you do some changes in the source code.

If there were no errors during the previous steps, you can simply run this command to open up your new YaST SSHD Configuration Tool:

sudo /sbin/yast2 sshd

or just

/sbin/yast2 sshd

After that, YaST opens up a Read dialog with a progress bar and after the configuration is read, it automatically switches to the Configuration dialog which looks like this one:

Application definitions for KDE, AutoYaST, YaST Control Center...

[Desktop Entry]
Type=Application
...
X-SuSE-YaST-Group=Misc
...
Icon=yast-sshd
Exec=/sbin/yast2 sshd
...
Name=Sshd
GenericName=sshd
...

These settings are used by another applications than the YaST SSHD Configuration itself. They define the module behavior and identification. See the YaST Desktop Files document for more details.

A basic application client also with a command line interface definition. Command line support will be described in another tutorial.

Clients are stored under the /usr/share/YaST2/clients/ path

/**
 * File: clients/sshd.ycp
 ...
 */

{

textdomain "sshd";

/* The main () */
y2milestone ("----------------------------------------");
y2milestone ("Sshd module started");

import "Progress";
import "Report";
import "Summary";

import "CommandLine";
include "sshd/wizards.ycp";

map cmdline_description = $[
    ...
    "guihandler" : SshdSequence,
    ...
];

/* is this proposal or not? */
boolean propose = false;
...

/* main ui function */
any ret = nil;

if (propose) ret = SshdAutoSequence();
else ret = CommandLine::Run(cmdline_description);
y2debug("ret=%1", ret);

/* Finish */
y2milestone("Sshd module finished");
y2milestone("----------------------------------------");

return ret;

/* EOF */
}

This client is called by YaST binary, it includes the wizard.ycp file with defined sequences and calls the CommandLine::Run() wich, in our case, calls the SshdSequence() workflow from wizard.ycp.

	Note
	We have also other clients <module-name>_auto.ycp for the AutoYaST and <module-name>_proposal.ycp for the installation proposal but they aren't needed for this tutorial.

Contains dialogs sequence definitions that are used by clients.

Wizards are stored under the /usr/share/YaST2/include/<module-name>/ path.

/**
 * File: include/sshd/wizards.ycp
 ...
 */

{

textdomain "sshd";

import "Sequencer";
import "Wizard";

include "sshd/complex.ycp";
include "sshd/dialogs.ycp";

/**
 * Add a configuration of sshd
 * @return sequence result
 */
any AddSequence() {
    ...
}

/**
 * Main workflow of the sshd configuration
 * @return sequence result
 */
any MainSequence() {

    map aliases = $[
	"summary"	:   ``( SummaryDialog() ),
	"overview"	:   ``( OverviewDialog() ),
	"add"		: [ ``( AddSequence() ), true ],
	"edit"		: [ ``( AddSequence() ), true ]
    ];

    map sequence = $[
	"ws_start" : "summary",
	"summary" : $[
	    `abort	: `abort,
	    `next	: `next,
	    `overview	: "overview",
	],
	"overview" : $[
	    `abort	: `abort,
	    `next	: `next,
	    `add	: "add",
	    `edit	: "edit",
	],
	"add" : $[
	    `abort	: `abort,
	    `next	: "overview",
	],
	"edit" : $[
	    `abort	: `abort,
	    `next	: "overview",
	]
    ];

    any ret = Sequencer::Run(aliases, sequence);

    return ret;
}

/**
 * Whole configuration of sshd
 * @return sequence result
 */
any SshdSequence() {

    map aliases = $[
	"read"	: [ ``( ReadDialog() ), true ],
	"main"	:   ``( MainSequence() ),
	"write"	: [ ``( WriteDialog() ), true ]
    ];

    map sequence = $[
	"ws_start" : "read",
	"read" : $[
	    `abort	: `abort,
	    `next	: "main"
	],
	"main" : $[
	    `abort	: `abort,
	    `next	: "write"
	],
	"write" : $[
	    `abort	: `abort,
	    `next	: `next
	]
    ];

    Wizard::CreateDialog();

    any ret = Sequencer::Run(aliases, sequence);

    UI::CloseDialog();
    return ret;
}

/**
 * Whole configuration of sshd but without reading and writing.
 * For use with autoinstallation.
 * @return sequence result
 */
any SshdAutoSequence() {
    ...
}

/* EOF */
}

First of all, complex.ycp and dialogs.ycp are included because they define dialogs that are used in dialog sequences.

After that, aliases to these dialogs are defined in aliases map. Then sequences pointing to these aliases are defined in a sequence map. Sequence handlers defines the relationship between event returned by a dialog function and action called by sequencer.

At the end, the SshdSequence() is called from the sshd.ycp client.

	Important
	Never define the `back event, dialog wizard handles it by itself.

Note

Please, take note, that sequences can call another ones: SshdSequence() calls MainSequence() and that one calls AddSequence(). Sequence called from a client should contain Wizard::CreateDialog() and UI::CloseDialog() because user should see the UI as soon as possible. Additionally Wizard::CreateDialog() creates the classic Wizard window with help text on the left side, space for dialogs on the other one and Back, Abort and Next buttons. Screenshot of the Wizard window:

Dialogs definitions and their simple handling.

Dialogs are stored under the /usr/share/YaST2/include/<module-name>/ path

/**
 * File: include/sshd/dialogs.ycp
 ...
 */

{

textdomain "sshd";

import "Label";
import "Wizard";
import "Sshd";

include "sshd/helps.ycp";

/**
 * Configure1 dialog
 * @return dialog result
 */
any Configure1Dialog () {

    /* Sshd configure1 dialog caption */
    string caption = _("Sshd Configuration");

    /* Sshd configure1 dialog contents */
    term contents = `Label (_("First part of configuration of sshd"));

    Wizard::SetContentsButtons(caption, contents, HELPS["c1"]:"",
	    Label::BackButton(), Label::NextButton());

    any ret = nil;
    while (true) {

	ret = UI::UserInput();

	/* abort? */
	if(ret == `abort || ret == `cancel) {
	    if(ReallyAbort()) break;
	    else continue;
	}
        else if(ret == `next || ret == `back) {
            break;
        }
        else {
            y2error("unexpected retcode: %1", ret);
            continue;
        }
    }

    return ret;
}

/**
 * Configure2 dialog
 * @return dialog result
 */
any Configure2Dialog () {
    ...
}

/* EOF */
}

This file defines two dialog functions Configure1Dialog() and Configure2Dialog(). These functions set the behavior by calling the Wizard::SetContentsButtons() function. We can use this advanced function because we have used the Wizard::CreateDialog() in the wizards.ycp.

After the dialog is created there is a loop function that handles the user input.

Help texts are included from the helps.ycp as the HELPS map.

	Note
	Every string we want to mark for translation uses the _("...") notation. Every such string should have a comment for translators defined above. We use standard gettext style. Translations insist on defined textdomain inside the file.

YCP include which contains complex functions for dialogs handling.

/**
 * File: include/sshd/complex.ycp
 ...
 */

{

textdomain "sshd";

import "Label";
...
import "Sshd";


include "sshd/helps.ycp";

...

/**
 * Read settings dialog
 * @return `abort if aborted and `next otherwise
 */
symbol ReadDialog() {
    Wizard::RestoreHelp(HELPS["read"]:"");
    // Sshd::AbortFunction = PollAbort;
    if (!Confirm::MustBeRoot()) return `abort;
    boolean ret = Sshd::Read();
    return ret ? `next : `abort;
}

/**
 * Write settings dialog
 * @return `abort if aborted and `next otherwise
 */
symbol WriteDialog() {
    ...
}

/**
 * Summary dialog
 * @return dialog result
 */
any SummaryDialog() {
    ..
}

/**
 * Overview dialog
 * @return dialog result
 */
any OverviewDialog() {

    /* Sshd overview dialog caption */
    string caption = _("Sshd Overview");

    list overview = Sshd::Overview();

    /* FIXME table header */
    term contents = Wizard_hw::ConfiguredContent(
	/* Table header */
	`header(_("Number"), _("Sshd")),
	overview, nil, nil, nil, nil );

    contents = Wizard_hw::SpacingAround(contents, 1.5, 1.5, 1.0, 1.0);

    Wizard::SetContentsButtons(caption, contents, HELPS["overview"]:"",
	    Label::BackButton(), Label::FinishButton());

    any ret = nil;
    while (true) {

	ret = UI::UserInput();

	/* abort? */
	if(ret == `abort || ret == `cancel) {
	    if(ReallyAbort()) break;
	    else continue;
	}
        /* add */
        else if(ret == `add_button) {
            ret = `add;
            break;
        }
        /* edit */
        else if(ret == `edit_button) {
            ret = `edit;
            break;
        }
        /* delete */
        else if(ret == `delete_button) {
            continue;
        }
        else if(ret == `next || ret == `back) {
            break;
        }
        else {
            y2error("unexpected retcode: %1", ret);
            continue;
        }
    }

    return ret;
}

/* EOF */
}

This file is very similar to the dialogs.ycp one but here should be more complex dialogs with handling.

The most important is the ReadDialog() that calls the Sshd::Read()—a global function from the Sshd YCP module.

Dialog functions defined in the file can be seen used in the wizards.ycp file in map of aliases.

Help texts for every dialog.

Helps are stored under the /usr/share/YaST2/include/<module-name>/ path

/**
 * File: include/sshd/helps.ycp
 ...
 */

{

textdomain "sshd";

/**
 * All helps are here
 */
map HELPS = $[

    /* Read dialog help 1/2 */
    "read" : _("<p><b><big>Initializing sshd Configuration</big></b><br>
Please wait...<br></p>
") +

    /* Read dialog help 2/2 */
    _("<p><b><big>Aborting Initialization:</big></b><br>
Safely abort the configuration utility by pressing <b>Abort</b> now.</p>
"),

...

    /* Configure1 dialog help 1/2 */
    "c1" : _("<p><b><big>Configuration Part One</big></b><br>
Press <b>Next</b> to continue.
<br></p>") +

    /* Configure1 dialog help 2/2 */
    _("<p><b><big>Selecting Something</big></b><br>
It is not possible. You must code it first. :-)
</p>"),

...

];

/* EOF */
}

This file is included by the dialogs.ycp and complex.ycp. All texts are defined in the HELPS map.

All help texts are written in HTML but they must follow the Text Style Guide.

	Note
	Please, take note, that help texts are divided into smaller chunks by logic parts. For translators, it's also easier to translate only a short string after you change something.

YCP module with global API that can be used from another modules or projects.

All modules are stored under the /usr/share/YaST2/modules/ path.

/**
 * File:        modules/Sshd.ycp
 * Package:     Configuration of sshd
 * Summary:     Sshd settings, input and output functions
 * Authors:     John The Fish <john@thesmallfish.net>
 *
 * $Id: Sshd.ycp 27914 2006-02-13 14:32:08Z jtf $
 *
 * Representation of the configuration of sshd.
 * Input and output routines.
 */

{

module "Sshd";
textdomain "sshd";

...

/**
 * Read all sshd settings
 * @return true on success
 */
global boolean Read() {
    /* Sshd read dialog caption */
    string caption = _("Initializing sshd Configuration");
    ...
    integer steps = 4;
    ...
    Progress::New( caption, " ", steps, [
	...
	], [
	...
	],
	""
    );
    ...
    Progress::NextStage();
    ...
    if(Abort()) return false;
    modified = false;
    return true;
}

/**
 * Write all sshd settings
 * @return true on success
 */
global boolean Write() {
    /* Sshd write dialog caption */
    string caption = _("Saving sshd Configuration");
    ...
    integer steps = 4;
    ...
    Progress::New( caption, " ", steps, [
	...
	], [
	...
	],
	""
    );
    ...
    Progress::NextStage();
    ...
    if(Abort()) return false;
    return true;
}

...
}

The module keyword sets the module namespace. You can acces the global variables and function with the module_name:: prefix (e.g., Sshd:: for Sshd module).

Global Read and Write functions also define the Progress bar that is changed by calling Progress::NextStage() function.

Read and Write functions should always return a boolean whether they succeeded or failed.

	Note
	Our project also contains the Sshd2.pm file that is a module written in a Perl language. Usage of a Perl module is is the same as usage of a YCP one but the internal syntax is different. Creating Perl modules will be explained in another tutorial.

You can download the changed source files here or you can download them one by one later in this section.

module_DATA =                   \ 
       Sshd.ycp                \ 
       Sshd2.pm

module_DATA =                   \ 
       Sshd.ycp

2.5.1.1.2. File Sshd.ycp

	Note
	This configuration module will provide the basic functional interface with no global variables. The main reason for a functional interface is that you can simply control your configuration data flow. Global variables are more vulnerable to corruption by other modules.

You had better download the changed file Sshd.ycp here

Here you can see the list of changes in the original file:

Cleaning the source code from unneeded functions:

• Remove Modified() function (both definitions global boolean Modified...).

• Remove AbortFunction() function.

• Remove Abort() function.

• Remove Export() function.

• Remove Summary() function.

• Remove Overview() function.

• Remove AutoPackages() function.

• Remove Import() function.

New and modified functionality:

• Remove the global keyword from all definitions of variables to make them local-only because we don't want anybody to change our data internally but using the functions.

  Original:

  global boolean modified = false;

  Changed:

  boolean modified = false;

• Add this

  import "Service";
  import "Popup";

  under other imports in the module. We are using these modules later in the module.

• Add new variable definition

  integer sl = 1000;

  after the boolean modified... definition. This variable is used for length definition of short sleeps between read and write progress steps.

• Add new GetModified() function just after the integer sl = 1000; definition:

  /**
   * Returns whether the configuration has been modified.
   */
  global boolean GetModified() {
      return modified;
  }

• Add new SetModified() function after the GetModified() one:

  /**
   * Sets that the configuration has been modified.
   */
  global void SetModified() {
      modified = true;
  }

• Modify Abort() function:

  /**
   * Returns a confirmation popup dialog whether user wants to really abort.
   */
  global boolean Abort() {
      return Popup::ReallyAbort(GetModified());
  }

• Add new PollAbort() function after the Abort() function:

  /**
   * Checks whether an Abort button has been pressed.
   * If so, calls function to confirm the abort call.
   *
   * @return boolean true if abort confirmed
   */
  global boolean PollAbort() {
      if (UI::PollInput() == `abort)
  	return Abort();
  
      return false;
  }

• Modify Read() function:

  Two useless progress steps were removed. Some texts were changed, e.g., Sshd to SSHD.

  /**
   * Read all SSHD settings
   * @return true on success
   */
  global boolean Read() {
  
      /* SSHD read dialog caption */
      string caption = _("Initializing SSHD Configuration");
  
      integer steps = 2;
  
      Progress::New( caption, " ", steps, [
      /* Progress stage 1/2 */
      _("Read current SSHD configuration"),
      /* Progress stage 2/2 */
      _("Read current SSHD state")
  ], [
      /* Progress step 1/2 */
      _("Reading current SSHD configuration..."),
      /* Progress step 2/2 */
      _("Reading current SSHD state..."),
      /* Progress finished */
      Message::Finished()
  ],
  ""
      );
  
      sleep(sl);
  
      if(PollAbort()) return false;
      Progress::NextStage();
      /* Error message */
      if(false) Report::Error(Message::CannotReadCurrentSettings());
      sleep(sl);
  
      if(PollAbort()) return false;
      Progress::NextStep();
      /* Error message */
      if(false) Report::Error(_("Cannot read current SSHD state."));
      sleep(sl);
  
      if(PollAbort()) return false;
      Progress::NextStage ();
      sleep(sl);
  
      modified = false;
      return true;
  }

• Modify Write() function:

  Some texts were changed, e.g., Sshd to SSHD. Message::SuSEConfigFailed() is replaced with Message::CannotAdjustService("sshd").

  /**
   * Write all SSHD settings
   * @return true on success
   */
  global boolean Write() {
  
      /* SSHD read dialog caption */
      string caption = _("Saving SSHD Configuration");
  
      integer steps = 2;
      
      Progress::New(caption, " ", steps, [
      /* Progress stage 1/2 */
      _("Write the SSHD settings"),
      /* Progress stage 2/2 */
      _("Adjust the SSHD service")
  ], [
      /* Progress step 1/2 */
      _("Writing the SSHD settings..."),
      /* Progress step 2/2 */
      _("Adjusting the SSHD service..."),
      Message::Finished()
  ],
  ""
      );
  
      sleep(sl);
  
      if(PollAbort()) return false;
      Progress::NextStage();
      /* Error message */
      if(false) Report::Error (_("Cannot write SSHD settings."));
      sleep(sl);
  
      if(PollAbort()) return false;
      Progress::NextStage ();
      /* Error message */
      if(false) Report::Error (Message::CannotAdjustService("sshd"));
      sleep(sl);
  
      Progress::NextStage ();
      sleep(sl);
  
      return true;
  }

2.5.1.1.5. File helps.ycp

You had better download the changed file helps.ycp here

Here is the list of changes in the file:

• Remove helps for summary, overview, c1 and c2.

• Add new helps for server_configuration and login_settings

  /* Server Configuration dialog help */
      "server_configuration" : _("<p><b><big>Server Configuration</big></b><br>
  Configure SSHD here.<br></p>"),
  
      /* Login Settings dialog help */
      "login_settings" : _("<p><b><big>Login Settings</big></b><br>
  Configure SSHD login settings here.<br></p>"),

	Note
	Structure of helps is: map HELPS = $[ // TRANSLATORS: Comment for translators (this is a help text for...) "help_for" : _("Help text marked for translation..."), ];

client_DATA =                   \
       sshd.ycp                \
       sshd_auto.ycp   \
       sshd_proposal.ycp

client_DATA =                   \
       sshd.ycp

Testsuites were designed for checking the global functionality, such as functions of modules, to keep them consistent. They can also help to find out when something else, used by your module, is suddenly changed.

In this tutorial, all testsuites testsuite/tests/Sshd.* have been completely removed. Creating and running testsuites will be later described in another tutorial.

This script creates a Wizard dialog with two push buttons and the Back-Abort-Next navigation at the bottom.

If you press any of those two push buttons, the AnnounceKeyPress() function is called and reports the event by a pop-up window.

When Back or Next button is pressed, it reports the event by a pop-up window and then the script finishes. When pressed the Abort button or when you try to close the window by your window manager's Close [x] button a confirmation of closing the script is required.

// loop_example.ycp
{
    /* --- importing needed modules --- */
    import "Wizard";
    import "Report";
    import "Label";
    import "Popup";
    /* --- importing needed modules --- */

    /* --- definition of functions --- */
    // dialog definition
    term dialog_content = `HBox (
	`PushButton(`id("pb_1"), "Button &1"),
	`PushButton(`id("pb_2"), "Button &2")
    );

    // function definition
    void AnnounceKeyPress (any key_pressed) {
	y2milestone("Pressed %1", key_pressed);
	// sformat replaces %1 with the value stored in key_pressed variable
	Report::Message(sformat("Button with id '%1' has been pressed.",
	    key_pressed)
	);
    }
    /* --- definition of functions --- */


    /* --- setting UI up --- */
    // Opening up a standard Wizard dialog
    Wizard::CreateDialog();
    Wizard::SetContentsButtons("Caption", dialog_content, "dialog help",
	Label::BackButton(), Label::NextButton());
    /* --- setting UI up --- */


    /* --- handling user input --- */
    any ret = nil;
    // starting the endless while (true) { do... } loop
    while ("hell" != "frozen over") {
	ret = UI::UserInput();
      
	// One of those dialog buttons have been pressed
	if (ret == "pb_1" || ret == "pb_2") {
	    AnnounceKeyPress(ret);

	// Back or Next navigation button have been pressed
	} else if (ret == `back || ret == `next) {
	    AnnounceKeyPress(ret);
	    // exits from the loop
	    break;

	// Confirmation question before closing the script
	} else if (ret == `abort || ret == `cancel) {
	    // exits from the loop when user confirms
	    if (Popup::ContinueCancel("Do you really want to abort?")) break;

	// unexpected return code
	} else {
	    Report::Error(sformat("Unexpected retcode %1", ret));
	}
    }
    /* --- handling user input --- */


    // Every opened dialog must be properly closed
    UI::CloseDialog();
}

SCR is and abstraction layer. YaST never touches the system directly even if the functionality is written in Perl and such functionality exists.

Every SCR Agent is a small program which transforms any service configuration, file attribute or whatever you can imagine into the YaST data-structure. They can be written in several languages such as C, Bash, Perl or Greenlandic.

The most important functions of SCR Agent are Read() and Write() but not every SCR Agent needs to provide these functions. Additionaly, some SCR Agents have also the Execute() or Dir() function.

The first thing, we should do, is to run through all already created SCR Agents whether there is any agent we could use instead of creating a new one. After some time spent on browsing that documentation we could run across the universal .target agent which can also read and return a textual file as one string and might be also used in case when every other tries failed. Unfortunately this is not suitable for such yast-hacker you want to be. That's why we have to create our own SCR Agent.

Fortunately YaST has a configurable so-called IniAgent which is quite easy to use and sufficiently fulfills our needs. You can find its documentation here: /usr/share/doc/packages/yast2-core/agent-ini/ini.html (you need yast2-core-devel package installed).

Our new SCR Agent should be able to:

This is the full definition of a .sshd SCR Agent which has the Read(), Write() and Dir() functions. It should be saved into the agents/sshd.scr file:

/**
 * File:
 *   sshd.scr
 * Summary:
 *   SCR Agent for reading/writing /etc/ssh/sshd_config
 *   using the ini-agent
 * Access:
 *   read/write
 * Authors:
 *   John The Fish <john@thesmallfish.net>
 * Example:
 *   Dir(.sshd)
 *   (["Port", "X11Forwarding", "Compression", "MaxAuthTries", "PermitRootLogin"])
 *
 *   Read(.sshd.Compression)
 *   (["yes"])
 *
 *   Write(.sshd.Compression, "no")
 *   (true)
 *
 * $Id: sshd.scr 11113 2005-10-20 14:15:16Z jtf $
 *
 * Fore more information about possible keys and values
 * consult with the sshd_config man pages `man sshd_config`.
 */

.sshd

`ag_ini(
    `IniAgent( "/etc/ssh/sshd_config",
        $[
            "options"   : [ "global_values", "repeat_names", "flat" ],
            "comments"  : [ "^[ \t]*#.*$", "^[ \t]*$" ],
            "params"    : [
                // Options with one value ('yes' / 'no')
                $[ "match" : [ "^[ \t]*([^ \t]+)[ \t]+([^ \t]+)[ \t]+$", "%s %s" ]],
                // Options with more possible values
                $[ "match" : [ "^[ \t]*([^ \t]+)[ \t]+(.+)[ \t]*$", "%s %s" ]],
            ],
            "subindent" : " ",
        ]
    )
)

The file agents/Makefile.am should be modified to have the sshd.scr added into the scrconf_DATA variable. This is the new version of agents/Makefile.am:

# Makefile.am for sshd/agents

agent_SCRIPTS =

scrconf_DATA = sshd.scr

EXTRA_DIST = $(agent_SCRIPTS) $(scrconf_DATA)

Run command sudo make install in the agents directory to get it installed into the /usr/share/YaST2/scrconf/ directory. Make sure, that the file has been copied there.

Every SCR Agent should have documented its functionality in the file header. Examples for every function are also very important. See the agent configuration.

For more information consult these agent's settings with the ini-agent documentation, please. This tutorial is not supposed to provide so complex information already described somewhere else.

You can directly test the SCR Agent by running the y2base binary in the terminal with this command: /usr/lib/YaST2/bin/y2base stdio scr. Don't forget to watch your /var/log/YaST2/y2log file while testing.

Because this SCR Agent communicates using the standard I/O, you can replace the interactive call method with with the single command call using the pipe echo '`Read(.sshd.UsePAM)' | /usr/lib/YaST2/bin/y2base stdio scr which would return:

([])
(["yes"])

Once we have the SCR Agent and the Data Model, we are about to create functions which will connect these two parts.

Into the upper part of the src/Sshd.ycp add the import of the SCR module:

import "SCR";

Now we can use the SCR functions.

Add this part below the PollAbort() function definition:

/**
 * Reads current sshd configuration
 */
boolean ReadSSHDSettings () {
    foreach (string key, (list <string>) SCR::Dir(.sshd), {
	list <string> val = (list <string>) SCR::Read(add(.sshd, key));
        if (val != nil) SETTINGS[key] = val;
    });
      
    y2milestone("SSHD configuration has been read: %1", SETTINGS);
    return true;
}

/**
 * Writes current sshd configuration
 */
boolean WriteSSHDSettings () {
    y2milestone("Writing SSHD configuration: %1", SETTINGS);

    foreach (string option_key, list <string> option_val, SETTINGS, {
	SCR::Write(add(.sshd, option_key), option_val);
    });
    // This is very important
    // it flushes the cache, and stores the configuration on the disk
    SCR::Write(.sshd, nil);

    return true;
}

The ReadSSHDSettings() function lists all already set options from the configuration file using the SCR::Dir() function, reads these options using the SCR::Read() function and if they have some value, stores them to the SETTINGS map.

The WriteSSHDSettings() function writes all variables from the SETTINGS map to the agent's writing cache using the SCR::Write() function and then sends the nil to the same function to store this configuration to the configuration file.

Below the previous functions we will also add functions for reading the current status of the sshd service and for restarting if it is needed:

/**
 * Reads current sshd status
 */
boolean ReadSSHDService () {
    if (Service::Status("sshd") == 0) {
	sshd_is_running = true;
    } else {
	sshd_is_running = false;
    }

    y2milestone((sshd_is_running ? "SSH is running":"SSH is not running"));
  
    return true;
}

/**
 * Restarts the sshd when the daemon was running when starting the configuration
 */
boolean WriteSSHDService () {
    boolean all_ok = true;

    if (sshd_is_running) {
	y2milestone("Restarting sshd daemon");
	all_ok = Service::Restart("sshd");
    } else {
	y2milestone("Sshd is not running - leaving...");
    }
      
    return all_ok;
}

Here is the documentation for more information about the Service module.

Then we have to change some lines in the general Read() and Write() functions to get the configuration read by starting the configuration and to get it written by finishing it.

Here are the changes:

/**
 * File:	modules/Sshd.ycp
 * Package:	Configuration of SSHD
 * Summary:	SSHD settings, input and output functions
 * Authors:	John The Fish <john@thesmallfish.net>
 *
 * Representation of the configuration of SSHD.
 * Input and output routines.
 */

{

module "Sshd";
textdomain "sshd";

import "Progress";
import "Report";
import "Message";
import "Service";
import "Popup";
import "SCR";

/**
 * Data was modified?
 */
boolean modified = false;

/**
 * Sleep time between Read or Write steps
 */
integer sl = 1000;

/**
 * Returns whether the configuration has been modified.
 */
global boolean GetModified() {
    return modified;
}

/**
 * Sets that the configuration has been modified.
 */
global void SetModified() {
    modified = true;
}

/**
 * map of SSHD settings
 */
map <string, list<string> > SETTINGS = $[];

map <string, list<string> > DEFAULT_CONFIG = $[
    "Port"                      : ["22"],
    "AllowTcpForwarding"        : ["yes"],
    "X11Forwarding"             : ["no"],
    "Compression"               : ["yes"],
    "PrintMotd"                 : ["yes"],
    "PermitRootLogin"           : ["yes"],
    "IgnoreUserKnownHosts"      : ["no"],
    "MaxAuthTries"              : ["6"],
    "PasswordAuthentication"    : ["yes"],
    "RSAAuthentication"         : ["no"],
    "PubkeyAuthentication"      : ["yes"],
];

/**
 * Describes whether the daemon is running
 */
boolean sshd_is_running = false;

/**
 * Returns a confirmation popup dialog whether user wants to really abort.
 */
global boolean Abort() {
    return Popup::ReallyAbort(GetModified());
}

/**
 * Checks whether an Abort button has been pressed.
 * If so, calls function to confirm the abort call.
 *
 * @return boolean true if abort confirmed
 */
global boolean PollAbort() {
    if (UI::PollInput() == `abort)
	return Abort();

    return false;
}

/**
 * Reads current sshd configuration
 */
boolean ReadSSHDSettings () {
    foreach (string key, (list <string>) SCR::Dir(.sshd), {
        list <string> val = (list <string>) SCR::Read(add(.sshd, key));
        if (val != nil) SETTINGS[key] = val;
    });
    
    y2milestone("SSHD configuration has been read: %1", SETTINGS);
    return true;
}

/**
 * Writes current sshd configuration
 */
boolean WriteSSHDSettings () {
    y2milestone("Writing SSHD configuration: %1", SETTINGS);

    foreach (string option_key, list <string> option_val, SETTINGS, {
        SCR::Write(add(.sshd, option_key), option_val);
    });
    SCR::Write(.sshd, nil);

    return true;
}

/**
 * Reads current sshd status
 */
boolean ReadSSHDService () {
    if (Service::Status("sshd") == 0) {
        sshd_is_running = true;
    } else {
        sshd_is_running = false;
    }
    y2milestone((sshd_is_running ? "SSH is running":"SSH is not running"));
    
    return true;
}

/**
 * Restarts the sshd when the daemon was running when starting the configuration
 */
boolean WriteSSHDService () {
    boolean all_ok = true;

    if (sshd_is_running) {
        y2milestone("Restarting sshd daemon");
        all_ok = Service::Restart("sshd");
    } else {
        y2milestone("Sshd is not running - leaving...");
    }
    
    return all_ok;
}

/**
 * Read all SSHD settings
 * @return true on success
 */
global boolean Read() {

    /* SSHD read dialog caption */
    string caption = _("Initializing SSHD Configuration");

    integer steps = 2;

    Progress::New( caption, " ", steps, [
	    /* Progress stage 1/2 */
	    _("Read current SSHD configuration"),
	    /* Progress stage 2/2 */
	    _("Read current SSHD state")
	], [
	    /* Progress step 1/2 */
	    _("Reading current SSHD configuration..."),
	    /* Progress step 2/2 */
	    _("Reading current SSHD state..."),
	    /* Progress finished */
	    Message::Finished()
	],
	""
    );

    sleep(sl);

    if(PollAbort()) return false;
    Progress::NextStage();
    /* Error message */
    if(!ReadSSHDSettings()) Report::Error(Message::CannotReadCurrentSettings());
    sleep(sl);

    if(PollAbort()) return false;
    Progress::NextStep();
    /* Error message */
    if(!ReadSSHDService()) Report::Error(_("Cannot read current SSHD state."));
    sleep(sl);

    if(PollAbort()) return false;
    Progress::NextStage ();
    sleep(sl);

    modified = false;
    return true;
}

/**
 * Write all SSHD settings
 * @return true on success
 */
global boolean Write() {

    /* SSHD read dialog caption */
    string caption = _("Saving SSHD Configuration");

    integer steps = 2;
    
    Progress::New(caption, " ", steps, [
	    /* Progress stage 1/2 */
	    _("Write the SSHD settings"),
	    /* Progress stage 2/2 */
	    _("Adjust the SSHD service")
	], [
	    /* Progress step 1/2 */
	    _("Writing the SSHD settings..."),
	    /* Progress step 2/2 */
	    _("Adjusting the SSHD service..."),
	    Message::Finished()
	],
	""
    );

    sleep(sl);

    if(PollAbort()) return false;
    Progress::NextStage();
    /* Error message */
    if(!WriteSSHDSettings()) Report::Error (_("Cannot write SSHD settings."));
    sleep(sl);

    if(PollAbort()) return false;
    Progress::NextStage ();
    /* Error message */
    if(!WriteSSHDService()) Report::Error (Message::CannotAdjustService("sshd"));
    sleep(sl);

    Progress::NextStage ();
    sleep(sl);

    return true;
}

}

/**
 * File:	include/sshd/complex.ycp
 * Package:	Configuration of sshd
 * Summary:	Dialogs handling and definitions
 * Authors:	John The Fish <john@thesmallfish.net>
 *
 * $Id: complex.ycp 13891 2004-02-05 15:16:57Z jtf $
 */

{

textdomain "sshd";

This is here only for the completeness of the file. Nevertheles you can see at least the default style of the file header.

import "Label";
import "Popup";
import "Wizard";
import "Wizard_hw";
import "Sshd";
import "Confirm";
import "Report";

include "sshd/helps.ycp";

All YCP or Perl modules have their documentation here. Take note of Sshd module being imported too.

/**
 * Read settings dialog
 * @return `abort if aborted and `next otherwise
 */
symbol ReadDialog() {
    Wizard::RestoreHelp(HELPS["read"]:"");
    boolean ret = Sshd::Read();
    return ret ? `next : `abort;
}

/**
 * Write settings dialog
 * @return `abort if aborted and `next otherwise
 */
symbol WriteDialog() {
    Wizard::RestoreHelp(HELPS["write"]:"");
    boolean ret = Sshd::Write();
    return ret ? `next : `abort;
}

Standard ReadDialog() and WriteDialog() functions which are called from the src/wizards.ycp file. They call the appropriate functions of the Sshd module and return a symbol to the Sequencer.

/**
 * Initializes the table of ports
 */
void InitPortsTable () {
    list <string> ports = Sshd::GetSSHDOption("Port");

    if (ports != nil && ports != []) {
	list <term> items = [];
	foreach (string port, ports, {
	    items = add (items, `item(`id(port), port));
	});

	// Redraw table of ports and enable modification buttons
	UI::ChangeWidget(`id("Port"), `Items, items);
	UI::ChangeWidget(`id("edit_port"), `Enabled, true);
	UI::ChangeWidget(`id("delete_port"), `Enabled, true);
    } else {
	// Redraw table of ports and disable modification buttons
	UI::ChangeWidget(`id("Port"), `Items, []);
	UI::ChangeWidget(`id("edit_port"), `Enabled, false);
	UI::ChangeWidget(`id("delete_port"), `Enabled, false);
    }
}

/**
 * Initializes the Server Configuration Dialog
 */
void InitServerConfigurationDialog() {
    InitPortsTable();

    foreach (string key, ["AllowTcpForwarding", "X11Forwarding", "Compression"], {
	UI::ChangeWidget(`id(key), `Value, (Sshd::GetSSHDOption(key) == ["yes"]));
    });
}

/**
 * Initializes the Login Settings Dialog
 */
void InitLoginSettingsDialog() {
    UI::ChangeWidget( `id("MaxAuthTries"), `ValidChars, "0123456789");
    list <string> MaxAuthTries = Sshd::GetSSHDOption("MaxAuthTries");
    UI::ChangeWidget(`id("MaxAuthTries"), `Value, MaxAuthTries[0]:"0");

    foreach (string key, ["PrintMotd", "PermitRootLogin",
	"PasswordAuthentication", "RSAAuthentication", "PubkeyAuthentication"], {
	    UI::ChangeWidget(`id(key), `Value, (Sshd::GetSSHDOption(key) == ["yes"]));
    });
}

Functions InitServerConfigurationDialog() and InitLoginSettingsDialog() initialize the appropriate dialogs and fill them up with the current data.

Function InitLoginSettingsDialog() also sets the valid characters for the MaxAuthTries text entry to numbers only.

Function InitPortsTable() is called from the InitServerConfigurationDialog(). It sets the list of currently configured used ports into the table and enables Edit and Delete buttons when some ports are configured. In the case of no ports configured disables those two buttons.

/**
 * Removes the port from list of current ports
 *
 * @param string port_number
 */
void DeletePort (string port) {
    Sshd::SetSSHDOption("Port", filter (
	string single_port, Sshd::GetSSHDOption("Port"), ``(single_port != port)
    ));
}

/**
 * Function handles the adding or editing port number.
 * When the current_port is not 'nil', the dialog will
 * allow to edit it.
 *
 * @param string current_port a port number to be edited or 'nil' when adding a new one
 */
void AddEditPortDialog (string current_port) {
    UI::OpenDialog(`opt(`decorated), `VBox(
	`MinWidth (30,
	    `HBox(
		`HSpacing(1),
		`Frame(
		    (current_port == nil ?
		    /* A popup dialog caption */
		    _("Add New Port")
		    :
		    /* A popup dialog caption */
		    _("Edit Current Port")),
		    /* A text entry */
		    `TextEntry(`id("port_number"), _("&Port"), (current_port == nil ? "":current_port))
		),
		`HSpacing(1)
	    )
	),
	`VSpacing(1),
	`HBox(
	    `PushButton(`id(`ok), Label::OKButton()),
	    `HSpacing(1),
	    `PushButton(`id(`cancel), Label::CancelButton())
	)
    ));

    UI::ChangeWidget( `id("port_number"), `ValidChars, "0123456789");

    any ret = nil;
    while (true) {
	ret = UI::UserInput();
	if (ret == `ok) {
	    string new_port = (string) UI::QueryWidget(`id("port_number"), `Value);

	    if (new_port == "") {
		UI::SetFocus(`id("port_number"));
		Report::Error(_("Port number must not be empty."));
		continue;
	    }

	    Sshd::SetSSHDOption("Port", add (Sshd::GetSSHDOption("Port"), new_port));

	    if (current_port != nil) DeletePort(current_port);
	}

	break;
    }

    UI::CloseDialog();
}

/**
 * Function handles Add, Edit and Delete buttons
 *
 * @param any action from "add_port", "edit_port" or "delete_port"
 */
void HandleServerConfigurationDialog(any action) {
    string selected_port = (string) UI::QueryWidget(`id("Port"), `CurrentItem);

    // Adding a new port
    if (action == "add_port") {
	AddEditPortDialog(nil);
    // Editing current port
    } else if (action == "edit_port") {
	AddEditPortDialog(selected_port);
    // Deleting current port
    } else if (action == "delete_port") {
	if (Confirm::DeleteSelected()) DeletePort(selected_port);
    } else {
	y2error("Unknown action %1", action);
    }
      
    InitPortsTable();
}

The HandleServerConfigurationDialog() function handles the dialog events when any of Add, Edit or Delete buttons are pressed.

/**
 * Stores the current configuration from Server Configuration Dialog
 */
void StoreServerConfigurationDialog() {
    Sshd::SetModified();

    // Stores all boolean values and turns them to the "yes"/"no" notation
    foreach (string key, ["AllowTcpForwarding", "X11Forwarding", "Compression"], {
    Sshd::SetSSHDOption(
    key,
    [ (((boolean) UI::QueryWidget(`id(key), `Value) == true) ? "yes":"no") ]
    );
    });
    }

/**
 * Stores the current configuration from Login Settings  Dialog
 */
void StoreLoginSettingsDialog() {
    Sshd::SetModified();

    // Stores an integer value as a string
    Sshd::SetSSHDOption(
	"MaxAuthTries",
	[ (string) UI::QueryWidget(`id("MaxAuthTries"), `Value) ]
    );

    // Stores all boolean values and turns them to the "yes"/"no" notation
    foreach (string key, ["PrintMotd", "PermitRootLogin",
	"PasswordAuthentication", "RSAAuthentication", "PubkeyAuthentication"], {
	    Sshd::SetSSHDOption(
		key,
		[ (((boolean) UI::QueryWidget(`id(key), `Value) == true) ? "yes":"no") ]
	    );
    });
}

These functions get the UI widgets statuses and store them using the Sshd::SetSSHDOption() function. You can see how the boolean value of every check box is read and transformed to the yes/no notation which is used in the configuration file. All options have to be lists of strings.

For reading the widget's status is used the UI::QueryWidget(`id(widget_id), `Value) function.

Widget with id MaxAuthTries has not a boolean value so has its own call of UI::QueryWidget() and Sshd::SetSSHDOption().

}

This is the standard End of File left here just for the file completeness.

Into the ServerConfigurationDialog() function between the Wizard::DisableBackButton(); call and the while-loop add calling the dialog initialization function:

InitServerConfigurationDialog();

Into the ServerConfigurationDialog() function into the while-loop add the function call for storing configuration and for handling the Add, Edit and Delete buttons. The mentioned part of the while-loop should look like this one:

    while(true) {

    ret = UI::UserInput();
      
    /* abort? */
    if(ret == `abort) {
	if(Sshd::Abort()) break;
	else continue;
    /* next */
    } else if(ret == `next) {
	StoreServerConfigurationDialog();
	break;
    /* add, edit or delete */
    } else if (ret == "add_port" || ret == "edit_port" || ret == "delete_port") {
	HandleServerConfigurationDialog(ret);
    /* unknown */
    } else {
	y2error("unexpected retcode: %1", ret);
	continue;
    }
}

Into the LoginSettingsDialog() function between the Wizard::SetNextButton(`next, Label::AcceptButton()); call and the while-loop add calling the dialog initialization function:

InitLoginSettingsDialog();

Into the LoginSettingsDialog() function into the while-loop add the function call for storing configuration. It should look like this one:

    while(true) {

    ret = UI::UserInput();

    /* abort? */
    if(ret == `abort) {
	if(Sshd::Abort()) break;
	else continue;
    /* next */
    } else if(ret == `next) {
	StoreLoginSettingsDialog();
	break;
    } else if(ret == `back) {
	break;
    /* unknown */
    } else {
	y2error("unexpected retcode: %1", ret);
	continue;
    }
}