Configuring the MaDDash Server¶

Note

The primary way most users configure MaDDash is with the pSConfig MaDDash Agent. The agent automatically fills in the values detailed below and most never need to touch any of the options listed. If you find you self in a situation where you do need to make manual configuration changes, then this document provides guidance.

The main configuration file for the maddash-server component is located at /etc/maddash/maddash-server/maddash.yaml

The file is in YAML format. In this file you define the checks you want to run and how they are organized. You can also tweak setting for the embedded web server and various other aspects of the software. The configuration file is broken into the following primary sections:

groups - In general, this is the section where you define lists of hosts that you want to check. You can define any number of custom groups in this section. When you define grids these groups will be used to define what constitutes the rows and columns. In theory they don’t have to be hosts, but for the perfSONAR checks this is the common case because your dimensions are endpoints of a test.
checks - This is where you define how to run each check. For Nagios checks, this means defining the command-line script to run and arguments to pass it.
grids - This is where you define how the groups will be applied to the checks. You define the groups that will compose the rows and columns, then define the type of check that will be run.
dashboards - This is where you group grids together.

There are also a number of miscellaneous parameters related to the general operation of the service. Each of these property categories is described in the remainder of this section.

groups¶

groups are used to define the resources that will compose the rows and columns of a grid. For the perfSONAR checks, this is often used to group the endpoints used in performance tests together (e.g. create a group for all the hosts running OWAMP tests and another for all the hosts running BWCTL tests). The names, members and number of groups is all customizable. groups take the following format:

groups:
    groupName:
        - "member"
        - "member"

All groups go under the group block. In the example above groupName can replaced with any alphanumeric string that does not contain whitespace. For example “myOwampHosts”, “campusHosts”, or any other string that meets the requirements. This name will be used later in the configuration, so its important to make note of it. In the above example, you should change member to the name of the host or other resource you want in the list.

groupMembers¶

groupMembers are used to further describe members of a group. Any custom property may be added but only the values listed are understood by the default MaDDash interface. There is also a special map propert that can be used to dynamically set values based on the value of the opposing row/column. groupMembers take the following format where “member” is the name of the member referenced:

groupMembers:
    - id: "member"
      ...member properties...

Below are the list of well-known properties:

Name	Type	Required	Description
id	String	Yes	The group member this is referencing. For example, the hostname or address of a single item in a group list
label	String	No	The value to show when displaying information about the referenced group member.
pstoolkiturl	String	No	The URL of the perfSONAR Toolkit web page.
map	YAML Object	No	Defines properties that change depending on the opposing row/column. The keys of this object are other groupMembers underneath which is a custom set of parameters that can be accessed in template strings using %row.map.<property> and %col.map.<property> respectively. The reserved key default can be used to define a set of properties that apply to hosts not explicitly listed otherwise.

checks¶

General Parameters¶

checks are where you provide instructions as to how results should be obtained. Checks take the current format in the configuration file:

checks:
    checkName :
       ...check-parameters...

The checkName can be any alphanumeric string with no whitespace. It is used to identify the check later in the file, so you should note it. For example you could name it something like “owampLossCheck” or “bwctl100Gbps”. The following parameters are available for the check:

Name	Type	Required	Description
name	String	Yes	A human-readable name used for display purposes when describing this check
description	String	Yes	Human-readable text describing the purpose of this check. The description field accepts the template variables %row and %col that will be populated with the current row and column values respectively when the check in applied to a grid.
type	String	Yes	The type of check. Currently the software supports net.es.maddash.checks.NagiosCheck, net.es.maddash.checks.PSNagiosCheck, and net.es.maddash.checks.RandomCheck
params	YAML Object	Type dependent	A YAML object containing parameters specific to the check. See the Type-specific Parameters section.
checkInterval	int	Yes	How frequently to run the check in seconds
retryInterval	int	Yes	How frequently to run the check in seconds if it encounters a state different from the current state
retryAttempts	int	Yes	The number of consecutive times a new state must be seen before it changes the state of the check. For example, if a check has been OK for many days, but suddenly a critical is seen, then a critical state must be seen 2 more times before the status will change
timeout	int	Yes	The number of seconds to wait for the check to return. If it does not return in this timeframe, the check is set to the UNKNOWN status.

Type-specific Parameters¶

Currently the software supports the following types of checks:

net.es.maddash.checks.NagiosCheck - This check is performed using Nagios command. The parameters provided describe how to run that command.
net.es.maddash.checks.PSNagiosCheck - This check is a perfSONAR Nagios command. It is an extension of net.es.maddash.checks.NagiosCheck, but includes additional fields to collect information necessary to display graphs from the perfSONAR toolkit.
net.es.maddash.checks.RandomCheck - This should only be used for testing. This check returns a random result every time it runs.

NagiosCheck¶

Name	Type	Required	Description
command	String	Yes	The full nagios command to run on the local system. It accepts the template variables %row and %col that will be populated with the row and column values when applied to a grid.

PSNagiosCheck¶

Name	Type	Required	Description
command	String	Yes	See NagiosCheck
maUrl	YAML Object	Yes	The URL of the measurement archive where performance data related to this check may be retrieved. This accepts the template variables listed in the Template Variables section. The object has one key that is called default which will be the default URL used for any cell in a grid. The remaining keys are members of groups assigned to the row. If default and a row key are specified, the row key is preferred for that row. The value of each key is a map where the key is a member of a group assigned to the column or you can use the default key to apply the URL to every column in the row. If default is specified and a specific value for a column, the specific value for the column is preferred. See the default configuration file for a full example.
graphUrl	String	Yes	A URL where a graph of data related to the check can be retrieved. This accepts the template variables listed in the Template Variables section.
metaDataKeyLookup	String	Yes	DEPRECATED A URL where metaDataKeys can be looked up for the data. These are often needed to generate the graph URL. This accepts some of the template variables listed in the Template Variables section. Note: Some variables it cannot accept because it is responsible for generating them.

Template Variables¶

Name	Description
%row	The row in the grid associated with this check at the time its run
%col	The column in the grid associated with this check at the time its run
%row.<prop>	Custom properties defined in the groupMembers section.
%col.<prop>	Custom properties defined in the groupMembers section.
%row.map.<prop>	Custom properties defined in the groupMembers section that change depending on opposing row or column.
%col.map.<prop>	Custom properties defined in the groupMembers section that change depending on opposing row or column.
%maUrl	The url of the measurement archive. You can’t use this in the maUrl parameters as this is generated from that template.
%maKeyF	DEPRECATED A comma-separated list of the metaDataKeys for the forward direction of a test. This cannot be used in metaDataKeyLookup as it is generated after the URL that is called.
%maKeyR	DEPRECATED A comma-separated list of the metaDataKeys for the reverse direction of a test. This cannot be used in metaDataKeyLookup as it is generated after the URL that is called.
%srcName	DEPRECATED The hostname of the source endpoint of a point-to-point test. This cannot be used in metaDataKeyLookup as it is generated after the URL is called.
%srcIP	DEPRECATED The IP address of the source endpoint of a point-to-point test. This cannot be used in metaDataKeyLookup as it is generated after the URL is called.
%dstName	DEPRECATED The hostname of the destination endpoint of a point-to-point test. This cannot be used in metaDataKeyLookup as it is generated after the URL is called.
%dstIP	DEPRECATED The IP of the destination endpoint of a point-to-point test. This cannot be used in metaDataKeyLookup as it is generated after the URL is called.
%eventType	DEPRECATED The eventType returned by metaDataKeyLookup of the destination endpoint of a point-to-point test. This cannot be used in metaDataKeyLookup as it is generated after the URL is called.
%event.delayBuckets	The string http://ggf.org/ns/nmwg/characteristic/delay/summary/20110317
%event.delay	The string http://ggf.org/ns/nmwg/characteristic/delay/summary/20070921
%event.bandwidth	The string http://ggf.org/ns/nmwg/characteristics/bandwidth/achievable/2.0
%event.iperf	The string http://ggf.org/ns/nmwg/tools/iperf/2.0
%event.utilization	The string http://ggf.org/ns/nmwg/characteristic/utilization/2.0

grids¶

grids associate groups with checks and arrange them in a two-dimensional structure. Grids are arranged as a list of objects with the following parameters:

Name	Type	Required	Description
name	String	Yes	A human readable name of the grid
rows	String	Yes	The name of the group that will compose the rows of the grid. This must match a group name defined in the groups section of the configuration file or an error will be returned.
columns	String	Yes	The name of the group that will compose the columns of the grid. This must match a group name defined in the groups section of the configuration file or an error will be returned.
checks	List of Strings	Yes	The name of the check elements that need to be run for each row and column. Each element must match a check name defined under the checks section of the configuration or an error will be returned.
rowOrder	String	Yes	Specifies how the rows should be ordered. Valid values are alphabetical, which will sort them alphabetically, or group which will present them exactly in the order they are defined in the group section.
colOrder	String	Yes	Specifies how the columns should be ordered. Valid values are alphabetical, which will sort them alphabetically, or group which will present them exactly in the order they are defined in the group section.
excludeSelf	boolean	Yes	If set to 1, then a check will not be run where the value of the current row is equal to the value of the current column. If set to 0, then a check will be run in this case.
excludeChecks	YAML Object	No	This excludes individual checks based on the row and column. The structure is a map where the key is the name of the row where you want to exclude a check. It should match a member of the group assigned to the “rows” property of this grid or it can be the special key ‘default’ that matches every row. The value is a list of columns that should not appear in the grid. An item in the list must be a member of the group assigned to the “columns” property of this grid or the special value “all” which removes all columns for a row. A full example is provided in the default configuration file.
columnAlgorithm	boolean	Yes	Determines which checks will be run. Valid values are as follows: all - Run a check between every row and column; afterSelf - Run a check to every host that’s defined after the current row in the ‘rows’ group; beforeSelf - Run a check to every host that’s defined before the current row in the ‘rows’ group
statusLabels	YAML object	Yes	Describes what each status means. Its structured as a set of key/value pairs where the key is the status and the value is the description of the status. Valid status values are ok, warning, critical, unknown and notrun, and extra. You do not need to define every status if not all are applicable to your check.
statusLabels.extra	YAML object	Yes	Object where you can define custom status labels. Valid keys are value which is an integer identifying the custom state, shortName which is a name to label the state and description which is text that will apear in the GUI legend.

dashboards¶

dashboards group grids together. You define them as as a list of YAML objects with the following properties:

Name	Type	Required	Description
name	String	Yes	The name you want displayed as the title of the dashboard
grids	List of YAML objects	Yes	The list of grids you want included in this dashboard. Each item in the list has one property name, where you specify the name of the grid. This must map to a name property for one of the defined grids in the configuration file.

General Properties¶

Name	Type	Required	Description
database	String	Yes	The path to the directory where the database is stored
jobThreadPoolSize	Integer	No	The maximum number of checks that can run in parallel. Defaults to 20
jobBatchSize	Integer	No	The maximum number of checks that can be running or waiting to run in memory. Defaults to 250.
disableScheduler	Boolean	No	If set to 1 then the server will only run as a REST server and not execute any new checks. Default is 0.
skipTableBuild	Boolean	No	If set to 1 then the database tables will not be built and indexes will not be built/rebuilt. The first time you run the server it must be set to 0. After that, you may find that setting it to 1 significantly speeds-up boot time. Keeping it on though has the advantage of rebuilding indexes on startup which can improve query performance.

Web Server Properties¶

Name	Type	Required	Description
serverHost	String	No	The hostname of the interface where the web server should listen. Defaults to localhost.
http	YAML Object	Yes (unless https specified)	Parameters related to http. See http properties section.
https	YAML Object	Yes (unless http specified)	Parameters related to https. See https properties section.

http properties¶

Name	Type	Required	Description
port	Integer	Yes	The port on which the web server should listen for HTTP connections
proxyMode	String	Yes	Reserved for future use. Currently let’s the server know that if it is behind a proxy. This may be used in later implementation to extract headers that forward information related to authentication.

https properties¶

Name	Type	Required	Description
port	Integer	Yes	The port on which the web server should listen for HTTPS connections
keystore	String	Yes	The keystore containing the key ‘mykey’ to use as the ssl server certificate. It should also contain any trusted certificates if doing client authentication.
keystorePassword	String	Yes	The password to access the keystore.
clientAuth	String	Yes	Indicates whether a client to the rest server must have a trusted SSL certificate. Valid values are require, want and off. require means the user MUST have a trusted certificate or the request will be rejected. want means the server will check the certificate if one is presented, but will not reject requests that do not provide one. off means no certificate is required.
proxyMode	String	Yes	Reserved for future use. Currently let’s the server know that if it is behind a proxy. This may be used in later implementation to extract headers that forward information related to authentication.