The WatchCUB^tm configuration file is in Apache's httpd.conf-style format.

 

Configuration File Syntax

Configuration file consists of several syntatical constructions:

 

1. Comments 

A '#' comments everything towards the end of the line. End of line is the only comment break available.

 

Example:

11: Port    80  # port number for test plugin to use

12: # Debug   3

 

2. Includes

 

Syntax:  IncludeFile <path_to_file>

 

IncludeFile parameter is including the contents of specified file. Inclusions are done before parsing, e.g. in the beginning of parsing every IncludeFile statement is substituted with the contents of the file pointed to. If there is no such file, parsing fails. Path to included file is either absolute or relative. Includes can be placed anywhere in the config file. Included files can include other files. A table of already included files is maintained during the config file building in order to avoid cyclic inclusions. If a cyclic inclusion is detected, parsing fails and error message is issued.

 

Example:

11: IncludeFile    "/etc/wc/plugins_definitions.cfg"

12: IncludeFile   config/global_definitions.cfg

 

 

3. Parameter Definitions

 

Syntax:  Identifier Value

Here, Identifier is the name of the parameter which is being defined. It consists only of letters (lower- and upper-case).

 

Valid identifiers: Port, LogFile, someValidIdentifier, username

Invalid identifiers: log_file, port3, SuccessString$

 

Value is a string containing no spaces or quoted string. If quote (") should be used within quoted string, it is ascaped by doubling the quote.

 

Valid values: 80, /var/log/wc/detail.log, "some text containing spaces", "we should escape ""quotes""!!!"

Invalid values: non-quotes string with spaces, "quoted, but with non-escaped "s..."

 

Examples: 

11: SomeParameter      some_value

12: AnotherParameter   "spaced value"

13: ErrorLog           /var/log/wc/error.log

14: SuccessString      "I hate ""quotes"" in values!!!"

 

 

4. Sections

Syntax: <Section[ SectionID]> ... </Section>

Here, Section can be any valid identifier (as defined in [Parameter Definitions]), SectionID can be any valid value (as in previous context) and within the <Section> opening and closing tags can be inserted any valid syntatical construction (comments, includes, parameter definitions and even other sections). SectionID is optional.

 

Examples:

11: <LogFiles>

12:    Error             /var/log/wc/error.log

13:    Detail            /var/log/wc/detail.log

14:    Action            /var/log/wc/action.log

15: </LogFiles>

 

Configuration File Semantics

 

1. Plugins

In order to perform tests, WatchCub Framework parses configuration file and loads different plugins. Every plugin should be defined on global level like this:
 

10: <Plugin port>

11:    Module            plugin_port

12: </Plugin>

13:

14: <Plugin http>

15:    Module            plugin_http

16:    Debug             10

17:    Quarantine        yes

18: </Plugin>

      

plugin section supports the following parameters:

• Module - the name of the plugin .so library, where the the plugin resides. This could be either a relative name, in which case the shared library file is looked for in standard library directories, or an absolute path.
• Debug - defines the debug level for this plugin (not implemented).
• NumThreads - the maximum number of concurrent threads running this plugin.
• MaxAsync - the maximum number of tests asynchronously run by this plugin (supported only on plugins using state machine approach)
• Pace - the interval in seconds between successive tests (default 60).
• Timeout - the maximum running interval for tests in seconds.
• Quarantine - If the value is set to yes this plugin is in quarantine mode. Quarantine mode prevents the framework from executing test originating from this module (not implemented).

 

The value for each attribute can be overwritten later inside Test or Machine sections.

Parameters, specific to different plugins can be seen per plugin on Plugins page.

 

4. Test template section

Syntax:
<Test "plugin_name::template_name">
   ...

</Test>
Context: global level
 
Test templates are used to specify a common test behaviour. For example local and remote ICMP tests behave differently, e.g. are given different values to common parameters. So it is useful to specify them once and then use the test template instead of the plugin definition directly. In terms of object-orientedness, test template inherits plugin and a particular test inherits either plugin directly or indirectly through a test template.
   
  

                       

The inheritance of a plugin is specified by the name attribute of the test template. Format plugin_name::template_name is used. When the parser encounters template "plugin_name::template_name" derivation from "plugin_name" plugin is assumed. Values of the test template parameters override the values of the plugin equally named plugin parameters. Later on the same is true for Test sections parameters - they override both the inherited plugin and template parameters.

 

Parameters with special meaning:

Debug and Quarantine tags have similar meaning but a narrower scope - only for tests derived from the test template (not implemented).

 5. Machine section

This section is used to describe machines against which tests should be performed. A single machine is described by the <Machine> section with ID, the human-readable name of machine which is to be used for identification. Parameters and subsections of this section have meaning to the tests being executed on the machine. Every plugin has its own specific parameters which can be seen per plugin on the plugins page.

Parameters and subsections with special meaning:

• Debug and Quarantine having scope over the particular machine (not implemented).
• Host - holds the domain name of machine or its IP address. Example: Host www.netclime.com
• <Test> (subsection) - defines a test to be performed against this particular machine. <Test> was used to define test template, but when encountered within a <Machine> its meaning is "test to be performed on machine"
  Global attributes valid for all tests:

 

Parameter	Description
Type	ID of plugin/test template this test originates from

 

Common parameters for <Test> section: 

• Debug and Quarantine as usual (not implemented).
• Timeout and Pace values as defined in Plugin section
• <Dependancy> section.
  Defines dependance of particular test on some other(s). This means that framework will not execute the test before the other has finished successfully. Example:

 

10: <Test web_site_test>

#

#   Test params for the father plugin

#

11:    Plugin            http

12:    <Dependancy>

13:       ping_test

14:    </Dependancy>

15: </Test>

16: <Test ping_test>

17:    Plugin            port

18: </Test>

  

Dependancies can be on test, executed on another machine. This is stated the following way:

<Dependancy>MachineID::TestID</Dependancy>

 

Inheritance

Parameters to tests are inherited in the following sequence:

Plugin --> Test template --> Machine --> Test

This means that for example if you set parameter Host at Plugin level and then on Machine level, it is overrided and the second value is considered. This gives the flexibility to "hardcode" globalo values to some parameters and override them in specific cases.

 

 

Parsing Theory of Operation

 

Configuration file parsing is done at three stages:

• Assembling configuration file from all included. At this stage IncludeFile's are substituted with contents of files to which they point. During this, inclusion loops are detected.

• Lexical parsing. This part of the parser splits the config file into tokens. This is done with finite state automaton.

• Grammatical parsing. Since the configuration file is built upon a context-free grammer, a push-down automaton is used to parse the tokens using gramatical production rules and then build a parse tree of the config file. The following grammer is used:

 

<config> := (<section>|<param_definition>|<comment>)*
<section> := <opening_tag>+<config>+<closing_tag>
<opening_tag> := `<'+identifier+Value+`>'
<closing_tag> := `<\'+identifier+`>'
<param_definition> := identifier+Value
<identifier> := letter[+letter*]
<letter> := `a'|..|`z'|`A'..`Z'
<value> := <unquoted_value> | <quoted_value>
<unquoted_value> := <non_white_space_symbol>* 
<quoted_value> := `"'+(<non_quote_symbol>|`""')*+`"' 
<non_white_space_symbol> := <symbol> / { \n,\t,` ' }
<non_quote_symbol> := <symbol> / { `"' }
<symbol> := ASCII 0..255
<comment> := `#' + <symbol>* + `\n'

 

Config File Parser QA Plan

 

• Build multiple config files pointing to each other and forming inclusion loop. Check if loop is detected.
• Build a config file, with some fake include. Check if error is reported.
• Build a config file with unopened/unclosed tags and check if error will be reported.
• Build a config file with some funny symbol ( not a letter, digit and '_' ) in Tag name and check for error
• Check if unescaped `"' will cause an error. Check if escaping it fixes the error.