Product
Search Results

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:

Type Description
main Default
wan-group main or wan<N>
lan-group main or lan<N>
wan-group-mp wan<N>
lan-group-mp lan<N>
smb-group smbuser<N>
ftp-group ftpuser<N>
cwmp-group cwmp_profile<N>
tr069-group tr069_device<N>
snmp-group snmpuser<N>

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:

Key Value
added CDRouter version X.Y the testvar was added in
deprecated CDRouter version X.Y the testvar was deprecated in
obsoleted CDRouter version X.Y the testvar was obsoleted in

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:

Type Description
802.11-channel 802.11 channel number, accepts ‘auto’ value also.
IP-list List of IPv4 addresses
IPv4 IPv4 address
IPv4-netmask IPv4 netmask (e.g. 255.255.255.0)
IPv4orIPv6 IPv4 address or IPv6 address
IPv6 IPv6 address
IPv6-list List of IPv6 addresses
IPv6-prefix IPv6 address with prefix length (e.g. 2001::/64)
IPv6Dynamic IPv6 address, may contain %eui64% token
IPv6IfId 64-bit IPv6 interface identifier, may contain %eui64 token
auth IPsec tunnel authentication type
bssid 802.11 BSSID (Basic Service Set IDentifier), i.e. MAC address, accepts auto value also
custom Reserved for customer-created testvars
date-time Date-time string (see Tcl’s clock scan)
decimal Decimal value, uses min / max and also-accept properties
decimal-list List of decimal values
dlci Data link connection identifier
encrypt IPsec tunnel encryption type
hex Hex string
hex-bytes Even number of hex characters, uses length property
host-name Hostname
keyword-list List of acceptable values stored in list property
lanInterface Linux interface name (e.g. eth0) for LAN interface
lanWEPKey Wireless WEP key
lease-time DHCP lease-time
mac-address MAC address (e.g. 11:22:33:44:55:66)
mtu Packet MTU value
network-slash-mask IPv4 address with netmask (e.g. 192.168.1.0/255.255.255.0)
port-list List of port numbers
port-number Port number 0-65535
public-type Transport type udp, tcp or both
spi IPsec tunnel SPI number
ssid 802.11 SSID (Service Set IDentifier), i.e. access point name
subset-list List of acceptable values stored in list property, value must be a subset with no duplicates
tr69DeviceSummary DeviceSummary string for TR-069
url URL (e.g. http://www.qacafe.com)
url-list List of URLs
usp-endpoint-id USP endpoint ID, see https://usp.technology/specification/index.html#sec:endpoint-identifier
wan-interface Name of WAN group (e.g. wan2) or IPv4/IPv6 address
wanInterface Linux interface name (e.g. eth0) for WAN interface
word Any alphanumeric characters plus -, _, ., * and /
wpaKey Wireless WPA key
yes-no Must be yes or no (deprecated, use keyword-list instead)

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
}