Testvar Properties

Testvar Properties

This section describes the various properties that can be assigned to testvars in config.dic when defining them with buddy::testvar_define.

also-accept

Indicates a list of alternate values a testvar can contain.

buddy::testvar_define mssClampingValue {
    type { decimal }
    also-accept default
}

also-reject

Indicates a list of values a testvar explicitly cannot contain.

buddy::testvar_define wanInterface {
    type { interface }
    also-reject { none }
}

children

This property is only relevant for wildcard testvars. Its value is a list that contains the names of additional wildcard testvars that may be defined after defining an instance of the testvar that is being defined by buddy::testvar_define. For example, the wildcard testvar eapIdentity is defined as follows:

buddy::testvar_define eapIdentity* {
    children {
        eapPassword
        eapUserCertPassword
        eapUserCertPath
        eapUserPrivateKey
    }
}

which means that the instances eapPassword<N>, eapUserCertPassword<N>, eapUserCertPath<N> and eapPrivateKey<N> are only relevant if eapIdentity<N> is also defined.

constraints

This property’s value contains Tcl script which performs semantic validation of the testvar’s value. See Testvar Constraints for more info on testvar constraints.

default

The value of the testvar returned by buddy::getvar if the testvar is not defined in the config file and the default-disabled property is not set to yes.

buddy::testvar_define lanIp {
    default 192.168.1.1
}

The value returned by buddy::getvar is this property’s value after being passed through Tcl’s subst command, therefore simple command substitution can be used to generate a testvar’s default value dynamically (see testvars acsDiscoveryUrl and lanIp for real-world examples).

proc my_proc_that_returns_lanip_default_value {} {
    return 192.168.1.1
}

buddy::testvar_define lanIp {
    default {[ my_proc_that_returns_lanip_default_value ]}
}

Setting a testvar’s default to a call to buddy::getvar is can be useful if a testvar should inherit the value of another testvar by default:

buddy::testvar_define lanIp {
    default {[ buddy::getvar wanIspIp ]}
}

It may be necessary to use buddy::getvar_group to ensure the inherited value is taken from a specific testvar group:

buddy::testvar_define lanIp {
    default {[ buddy::getvar_group main wanIspIp ]}
}

default-disabled

If this property exists and is set to yes, the testvar has no default value and must be explicitly set in the config file. Also, if this property exists and is set to yes, buddy::getvar returns an empty string if the testvar is not set in the config file.

buddy::testvar_define NAME {
    default-disabled yes
}

description

Text which describes the testvars meaning for humans.

human-name

This property’s value contains a human-friendly name for the testvar being defined. The name should be short and concise but easier to digest than the camelCaseTestvarNames generally used for testvar names. For example, the testvar acsIp might be given a human-name property such as:

buddy::testvar_define acsIp {
    human-name {ACS Server}
}

The human-name property is used by the configuration visualizer to display a human-friendly name for each node in the network graph.

instances

This property is only relevant for wildcard testvars. Its value contains the number of instances of the testvar that may be defined. For example, the wildcard testvar dnsHostname is defined with an instances property of 10:

buddy::testvar_define dnsHostname* {
    instances 10
}

which means that the only valid instances of the testvar dnsHostname are: dnsHostname1, dnsHostname2, dnsHostname3, … dnsHostname10.

ip-range

Indicates the testvar is a member of an IP range start/end pair of testvars. This property’s value is a two-element list of testvar names, the first element is the starting address testvar and the second element is the ending address testvar.

buddy::testvar_define dhcpClientStart {
    ip-range { dhcpClientStart dhcpClientEnd }
}

buddy::testvar_define dhcpClientEnd {
    ip-range { dhcpClientStart dhcpClientEnd }
}

length

Indicates the number of characters a testvar’s value should contain.

buddy::testvar_define cdrouterOui {
    type { hex-bytes }
    length 6
}

If given as a range MIN-MAX, indicates the minimum and maximum number of characters a testvar’s value should contain.

buddy::testvar_define cdrouterOui {
    type { hex-bytes }
    length 6-24
}

Both forms are used by testvars whose type property is set to hex-bytes.

list

A list of values the testvar is allowed to hold. Used by testvars whose type property is set to keyword-list or subset-list.

buddy::testvar_define eapType {
    type { keyword-list }
    list { eap-md5 eap-tls eap-ttls eap-peap eap-sim eap-aka }
}

min / max

Indicates the minimum/maximum value a testvar can contain. Used by testvars whose type property is set to decimal or decimal-list.

buddy::testvar_define dhcpv6DuidType {
    type { decimal }
    min 1
    max 3
}

network / *-network

Declares the side of the CPE and which network an IPv4/IPv6 address testvar should reside on. Used by the valid_address constraint command, see Testvar Network Constraints for more info on network validation.

relevant-groups

Indicates which testvar groups a testvar is relevant in. This property’s value should be a list of one or more group types. If not set, this property defaults to main. When processing testvar constraints, only testvars defined in testvar groups in which they are relevant are checked. The group types available are below:

The plural form of each group type is also accepted and is treated identically to the singular form. For example, wan-groups is the same as wan-group and lan-groups-mp is the same as lan-group-mp. If the relevant-groups property does not match any of the above values, it is assumed to be a regular expression and will be matched against the group name using Tcl’s regexp command.

For example, the testvar acsIp is only relevant if defined in the main testvar group. Therefore a definition without a relevant-groups property:

buddy::testvar_define acsIp {
    type { IPv4orIPv6 }
}

is equivalent to a definition with a relevant-groups property of main:

buddy::testvar_define acsIp {
    type { IPv4orIPv6 }
    relevant-groups { main }
}

In contrast, the testvar dhcpClientStart is only relevant in LAN groups. Therefore it would require a relevant-groups property that looks like:

buddy::testvar_define dhcpClientStart {
    relevant-groups { lan-group }
}

which means that dhcpClientStart is only relevant in the main testvar group or additional LAN groups lan2, lan3, etc.

status

This property’s value is a Tcl dictionary which describes the history of the testvar being defined and can contain the following keys:

The value for each key should be a CDRouter version number of the form X.Y where X is the major version and Y is the minor version. For example, if acsWaitForConnectionRequest was added in CDRouter 7.3, deprecated in CDRouter 8.0 and obsoleted in CDRouter 8.3 it would have the following status property:

buddy::testvar_define acsWaitForConnectionRequest {
    status { added 7.3 deprecated 8.0 obsoleted 8.3 }
}

This property is used to display a link to the corresponding release notes in the testvar’s documentation.

test-constraints

This property’s value contains Tcl script which calls skip_labels based on the values of any number of testvars. Each test-constraints property is processed after cdrouter-cli has loaded the configuration file and performed data type validation on the defined testvars but before constraints properties are processed. The Tcl script in a test-constraints property can call all the same constraint commands that a constraints property can use.

See Test Labels for more info on test labels and the test-constraints property.

type

The type of value the testvar must contain. Used to perform syntactic validation of a testvar’s value. See below for the list of possible types:

For example, the testvar dhcpClientTimeout is expected to hold a decimal value and would there form have the following type property:

buddy::testvar_define dhcpClientTimeout {
    type { decimal }
}

undocumented

If exists and is set to yes, the testvar should not be displayed to the user.

buddy::testvar_define NAME {
    undocumented yes
}