Mesh Configuration (.conf) file

Overview

The perfSONAR MeshConfig software allows an administrator to generate a central file that defines measurements for a set of hosts that read the published file. The file is defined by the administrator in Apache config format. This document covers this format and the complete listing of options available.

Each configuration file consists of the following elements:

  • A list of description providing a human-readable string that names your mesh. See description Directive for details on defining this element.
  • A list of administrators responsible for the configuration file. See <administrator> Directive for details on defining this element.
  • A list of organizations including the sites and hosts that they contain. See <organization> Directive for details on defining this element.
  • A list of test specification that describe the parameters of the tests to be run. See <test_spec> Directive for details on defining this element.
  • A list of groups the describe the topology of tests and the hosts they contain. See <group> Directive for details on defining this element.
  • A list of tests that connect the previously defined test specifications and groups. See <test> Directive for details on defining this element.
  • An optional set of host classes that allow for dynamic joining of tests to groups. See <host_class> Directive for details on defining this element.

Naming

description Directive

Description:A human-readable name for the parent directive
Syntax:description TEXT GOES HERE
Contexts:top level, organization, site, host, host
Occurrences:Exactly one per parent
Compatibility:3.3 and later

The description is a human-readable name applied for the parent element. It is primarily relevant to GUIs for display purposes. For example, MaDDash configurations uses this field as the title of the created dashboard in the top-level context. Likewise it uses this field as the name displayed for each host in the rows and columns of a grid in the host context.

Grouping

<organization> Directive

Description:An optional construct that groups together sites and hosts by the organization to which they belong
Syntax:<organization>...</organization>
Contexts:top level
Occurrences:Zero or more
Compatibility:3.3 and later

The <organization> directive is strictly of purposes of grouping elements managed by the same entity together. In addition to keeping sites and hosts in a logical order, the description field can also be matched on when defining host classes.

<site> Directive

Description:An optional construct that groups an organization’s hosts together, generally based on location
Syntax:<site>...</site>
Contexts:organization
Occurrences:Zero or more
Compatibility:3.3 and later

A site can group hosts within an organization together. For example, if an organization has multiple campuses with two hosts deployed at each, then the site directive can be used to group the hosts at each campus. This example is illustrate below:

<site>
    description Site 1
    <host>...</host>
    <host>...</host>
</site>

<site>
    description Site 2
    <host>...</host>
    <host>...</host>
</site>

The <site> may have additional significance for tools that display data. For example, a MaDDash configuration can plot data on the same graph for hosts belonging to the same site. This is especially useful when different types of measurement data are spread across multiple hosts, such as throughput and one-way delay data.

Hosts

<host> Directive

Description:Describes a host that will be used as an endpoint in measurements
Syntax:<host>...</host>
Contexts:top level, organization, site
Occurrences:Zero or more
Compatibility:3.3 and later

The host object is a critical part of your mesh configuration. You may define a host object at the top level of the file or within an organization or site. The latter two options simply provide more metadata about the host that can be used for documentation purposes or for hos class matches. Inside the construct you will define all the addresses which may be used for performing network measurements to/from this host as well as some additional metadata.

no_agent Directive

Description:A boolean indicating that his host does NOT read the mesh
Syntax:no_agent 0|1
Default:0
Contexts:host
Occurrences:Zero or One
Compatibility:3.3 and later

If set to 1, this value indicates that the host in question is not reading the mesh. This is significant because it means those that test to it are responsible for initiating tests in both directions and storing the results. The default is 0 meaning other testers can assume this host is reading the mesh and will initiate its portion of the tests accordingly.

toolkit_url Directive

Description:A URL to the host’s perfSONAR Toolkit instance or other related web site
Syntax:toolkit_url URL
Contexts:host
Occurrences:Zero or One
Compatibility:3.3 and later

This option is for graphical displays that wish to provide a link to more information about the host. traditionally this is a link to the perfSONAR Toolkit, but may in practice be any valid URL.

<address> Directive

Description:An IPv4 address, IPv6 address, or hostname belonging to a host
Syntax:address ADDRESS or <address>...</address>
Default:0
Contexts:host
Occurrences:One or more
Compatibility:3.3 or later for simple form, 3.5 and later for complex form

An address is a required element of a host that defines an IPv4address , IPv6 address or hostname assigned to an interface on the host. You can and likely will define multiple of these for a single a host. If using a hostname it is not required to also define theIP addresses to which the hostname maps as the tools will do the look-ups automatically.

You can define address in one of two forms. In the simple form you simply provide the address. Example:

address 10.0.1.1

In the complex form you make it a block and can optionally add the tags field to label the address. Tags are used when defining a host class. Example:

<address>
    address 10.0.1.1
    tag latency
</address>

address Directive

Description:In the complex form of <address>, a simple string representation of the IPv4, IPv6 address or hostname
Syntax:address ADDRESS
Contexts:address
Occurrences:Zero or One
Compatibility:3.3 and later

Storing Results

<measurement_archive> Directive

Description:Defines where measurement results are stored
Syntax:<measurement_archive>...</measurement_archive>
Contexts:top level, organization, site, host
Occurrences:One per <measurement_archive> type
Compatibility:3.3 or later

The <measurement_archive> defines where measurements of a certain type are stored. Depending on where it is placed in the document it can have the following semantics:

  • If placed in the <host> directive, then all measurements initiated by that host(and matching the measurement archive type) will be stored in the provided MA
  • If placed in the <site> directive, all measurements initiated by hosts defined in the site will use the provided measurement archive UNLESS a <measurement_archive> is defined in the <host> directive.
  • If placed in the <organization> directive, all measurements initiated by hosts defined in the organization will use the provided measurement archive UNLESS a <measurement_archive> is defined in the <site> directive OR the <host> directive (with <host> given preference).
  • If placed in the top level, then all hosts will use the defined <measurement_archive> UNLESS there is <measurement_archive> defined in the <host>, <site>, or <organization> (with preference given in that order).

type Directive

Description:The type of measurement archive
Syntax:type perfsonarbuoy/bwctl|perfsonarbuoy/owamp|pinger|traceroute
Contexts:measurement archive
Occurrences:Exactly one
Compatibility:3.3 and later

This specifies the type of data to be stored. The supported values refer to an older version of the perfSONAR software where different data types were stored in different archives. Even if the data ultimately ends up in the same archive you need to define multiple <measurement_archive> directives for each type of data you plan to store. The types have the following meanings:

  • perfsonarbuoy/bwctl - Throughput tests such as those initiated by BWCTL running iperf or iperf3
  • perfsonarbuoy/owamp - OWAMP tests initiated by the powstream tool
  • pinger - Ping tests initiated by ping, bwping or OWAMP tests initiated by bwping running OWAMP
  • traceroute - Any type of test initiated by bwtraceroute

read_url Directive

Description:The URL where tools should query for results
Syntax:read_url URL
Contexts:measurement archive
Occurrences:Exactly one
Compatibility:3.3 and later

This is the URL where tools, such as a MaDDash dashboard, will query for test results. In general, this value will be the same as the write_url if running the perfSONAR Toolkit 3.4 or newer. You may want it to be a different value if your server uses a different public address than it uses to store data, such as in a NAT environment.

write_url Directive

Description:The URL where tools should send results to store
Syntax:write_url URL
Contexts:measurement archive
Occurrences:Exactly one
Compatibility:3.3, ignored in 3.4, supported again in 3.5 or later

This is the URL where tools, such as regular-testing on the perfSONAR Toolkit, should send results. This value is only useful if your measurement archive is using IP authentication. if using API key authentication, you will need to define the measurement archive in your local regulartesting.conf file. This is because it is not safe for the MeshConfig to share login credentials in it’s current form and would be difficult to manage in a large mesh.

Defining Test Parameters

<test_spec> Directive

Description:The parameters to use when running a test that uses this specification. The NAME tag is used to reference the test_spec elsewhere in the configuration.
Syntax:<test_spec NAME>...</test_spec>
Contexts:top level
Occurrences:Zero or more
Compatibility:3.3 or later

The <test_spec> defines the parameters used when running a test. Every test_spec has a type directive that indicates what kind of test is to be run. A set of directives are available for each type that are then used to further refine the parameters of the tests that use this specification.

type Directive

Description:The type of test to be run for tests using this specification
Syntax:type perfsonarbuoy/bwctl|perfsonarbuoy/owamp|pinger|traceroute
Contexts:test_spec
Occurrences:Exactly one
Compatibility:3.3 or later

The types have the following meanings:

Defining Throughput Test Parameters

tool Directive

Description:The tool to use in performing the throughput test. For a description of the pros and cons of each tool, see fasterdata.es.net.
Syntax:tool iperf|iperf3|nuttcp
Contexts:test_spec where type is perfsonarbuoy/bwctl
Occurrences:Exactly one
Compatibility:3.3 or later

duration Directive

Description:The length to run each throughput test in seconds, or in ISO8601 format (e.g.: “PT10S”)
Syntax:duration SECONDS
Contexts:test_spec where type is perfsonarbuoy/bwctl
Occurrences:Exactly one
Compatibility:3.3 or later

interval Directive

Description:The time in between throughput tests in seconds, or in ISO8601 format (e.g.: “PT10S”)
Syntax:interval SECONDS
Contexts:test_spec where type is perfsonarbuoy/bwctl
Occurrences:Exactly one
Compatibility:3.3 or later

buffer_length Directive

Description:Length of read and write buffers
Syntax:buffer_length NUMBER
Contexts:test_spec where type is perfsonarbuoy/bwctl
Occurrences:Zero or one
Default:system default
Compatibility:3.3 or later

force_bidirectional Directive

Description:Forces each endpoint to initiate the test in both directions. This will lead to redundant tests being run on each side.
Syntax:force_bidirectional 0|1
Contexts:test_spec where type is perfsonarbuoy/bwctl
Occurrences:Zero or one
Default:0
Compatibility:3.3 or later

ipv4_only Directive

Description:Forces each side to use IPv4. Test will fail if no IPv4 address can be determined for either endpoint
Syntax:ipv4_only 0|1
Contexts:test_spec where type is perfsonarbuoy/bwctl
Occurrences:Zero or one
Default:0
Compatibility:3.3 or later

ipv6_only Directive

Description:Forces each side to use IPv6. Test will fail if no IPv6 address can be determined for either endpoint
Syntax:ipv6_only 0|1
Contexts:test_spec where type is perfsonarbuoy/bwctl
Occurrences:Zero or one
Default:0
Compatibility:3.3 or later

latest_time Directive

Description:The delay in seconds after the test is requested that it is allowed to start. This may be useful on busy hosts where a test cannot be scheduled until further in the future than the default allows.
Syntax:latest_time seconds
Contexts:test_spec where type is perfsonarbuoy/bwctl
Occurrences:Zero or one
Default:50% of the interval OR the difference between the interval and duration (whichever is smaller)
Compatibility:3.3 or later

omit_interval Directive

Description:The time to ignore results at the beginning of a test in seconds. Useful for excluding TCP ramp-up time. Note that this is added to the duration (e.g. omit_interval of 5 and duration 30 leads to a 35 second test).
Syntax:omit_interval SECONDS
Contexts:test_spec where type is perfsonarbuoy/bwctl and protocol is tcp and tool is iperf3
Occurrences:Zero or one
Default:0
Compatibility:3.3 or later

protocol Directive

Description:The transport protocol to use for the test. May be tcp or udp.
Syntax:protocol tcp|udp
Contexts:test_spec where type is perfsonarbuoy/bwctl
Occurrences:Zero or one
Default:tcp
Compatibility:3.3 or later

random_start_percentage Directive

Description:The percentage to randomize the start time of requests. Valid values are between 0 and 50 (inclusive). Example: interval of 7200 (2 hours) and random_start_percentage 50 means that a test can start anywhere between 1 hour and 3 hours after the previous test completes.
Syntax:random_start_percentage PERCENTAGE
Contexts:test_spec where type is perfsonarbuoy/bwctl
Occurrences:Zero or one
Default:10
Compatibility:3.3 or later

report_interval Directive

Description:The sub-interval at which to report results in seconds.
Syntax:report_interval SECONDS
Contexts:test_spec where type is perfsonarbuoy/bwctl
Occurrences:Zero or one
Default:1
Compatibility:3.3 or later

streams Directive

Description:The number of parallel streams to use in the test
Syntax:streams NUMBER
Contexts:test_spec where type is perfsonarbuoy/bwctl
Occurrences:Zero or one
Default:1
Compatibility:3.3 or later

tos_bits Directive

Description:The type of service to set in the IP header of outgoing packets as an integer from 0-255.
Syntax:tos_bits NUMBER
Contexts:test_spec where type is perfsonarbuoy/bwctl
Occurrences:Zero or one
Default:not set
Compatibility:3.3 or later

dscp Directive

Description:The DSCP value to set in the IP header of outgoing packets
Syntax:dscp NUMBER
Contexts:test_spec where type is perfsonarbuoy/bwctl and tool is nuttcp
Occurrences:Zero or one
Default:not set
Compatibility:4.0 or later

tcp_bandwidth Directive

Description:The rate at which the tool will attempt to send TCP packets. Can specify as bits per second or with suffix K, M, or G to indicated Kbps, Mbps or Gbps respectively.
Syntax:tcp_bandwidth NUMBER
Contexts:test_spec where type is perfsonarbuoy/bwctl
Occurrences:Zero or one
Default:not set
Compatibility:4.0 or later

udp_bandwidth Directive

Description:The rate at which the tool will attempt to send UDP packets in bits per second.
Syntax:udp_bandwidth NUMBER
Contexts:test_spec where type is perfsonarbuoy/bwctl and protcol is udp
Occurrences:Zero or one
Default:1Mbps if a udp protocol set, n/a otherwise
Compatibility:3.3 or later

window_size Directive

Description:TCP window size (in bytes). Can use K or M to indicate Kilo or Mega bytes.
Syntax:window_size NUMBYTES
Contexts:test_spec where type is perfsonarbuoy/bwctl and protocol is tcp
Occurrences:Zero or one
Default:0 (i.e. use endpoint host default)
Compatibility:3.3 or later

mss Directive

Description:Tell the tool to use a MSS of N bytes
Syntax:mss BYTES
Contexts:test_spec where type is perfsonarbuoy/bwctl and tool is nuttcp
Occurrences:Zero or one
Default:not set
Compatibility:4.0 or later

congestion Directive

Description:Use this TCP congestion control algorithm (cubic, htcp, bbr, etc)
Syntax:congestion VALUE
Contexts:test_spec where type is perfsonarbuoy/bwctl and protocol is tcp and tool is iperf3
Occurrences:Zero or one
Default:not set, will use system default
Compatibility:4.0 or later

no_delay Directive

Description:Set TCP_NODELAY option for the tests
Syntax:no_delay 0|1
Contexts:test_spec where type is perfsonarbuoy/bwctl and protocol is tcp
Occurrences:Zero or one
Default:not set
Compatibility:4.0 or later

client_cpu_affinity Directive

Description:which cores to use for the client tool (useful for 40/100G NUMA hosts)
Syntax:client_cpu_affinity NUMBER CPU socket ID, used to start tool with ‘numactl -N ID’
Contexts:test_spec where type is perfsonarbuoy/bwctl
Occurrences:Zero or one
Default:not set
Compatibility:4.0 or later

server_cpu_affinity Directive

Description:which cores to use for the server tool (useful for 40/100G NUMA hosts)
Syntax:server_cpu_affinity NUMBER CPU socket ID, used to start tool with ‘numactl -N ID’
Contexts:test_spec where type is perfsonarbuoy/bwctl
Occurrences:Zero or one
Default:not set
Compatibility:4.0 or later

flow_label Directive

Description:set the IPv6 flow label (iperf3 -L) integer
Syntax:flow_label INT
Contexts:test_spec where type is perfsonarbuoy/bwctl and tool is iperf3
Occurrences:Zero or one
Default:not set
Compatibility:4.0 or later

Defining Streaming One-way Delay Test Parameters

bucket_width Directive

Description:The bin size for histogram calculations in terms of seconds. For example a value such as .001 means all histogram bins will be in milliseconds.
Syntax:bucket_width VALUE
Contexts:test_spec where type is perfsonarbuoy/owamp
Occurrences:Exactly one
Compatibility:3.3 or later

packet_interval Directive

Description:The mean average time between packets in seconds. For example, .1 means send 10 packets per second.
Syntax:packet_interval SECONDS
Contexts:test_spec where type is perfsonarbuoy/owamp
Occurrences:Exactly one
Compatibility:3.3 or later

sample_count Directive

Description:The number of packets contained in each summary. This combined with packet_interval determines how often data is stored. For example, a packet_interval of .1 (10 packets per second) and sample_count of 600 stores a result every 60 seconds.
Syntax:sample_count NUMBER
Contexts:test_spec where type is perfsonarbuoy/owamp
Occurrences:Exactly one
Compatibility:3.3 or later

force_bidirectional Directive

Description:Forces each endpoint to initiate the test in both directions. This will lead to redundant tests being run on each side.
Syntax:force_bidirectional 0|1
Contexts:test_spec where type is perfsonarbuoy/owamp
Occurrences:Zero or one
Default:0
Compatibility:3.3 or later

ipv4_only Directive

Description:Forces each side to use IPv4. Test will fail if no IPv4 address can be determined for either endpoint
Syntax:ipv4_only 0|1
Contexts:test_spec where type is perfsonarbuoy/owamp
Occurrences:Zero or one
Default:0
Compatibility:3.3 or later

ipv6_only Directive

Description:Forces each side to use IPv6. Test will fail if no IPv6 address can be determined for either endpoint
Syntax:ipv6_only 0|1
Contexts:test_spec where type is perfsonarbuoy/owamp
Occurrences:Zero or one
Default:0
Compatibility:3.3 or later

packet_padding Directive

Description:The size of the padding added to each packet in bytes
Syntax:packet_padding BYTES
Contexts:test_spec where type is perfsonarbuoy/owamp
Occurrences:Zero or more
Default:0
Compatibility:3.3 or later

output_raw Directive

Description:This will store the raw owamp results as JSON in the measurement archive.
Syntax:output_raw 0|1
Contexts:test_spec where type is perfsonarbuoy/owamp
Occurrences:Exactly one
Default:0
Compatibility:4.0 or later

tos_bits Directive

Description:The type of service to set in the IP header of outgoing packets as an integer from 0-255.
Syntax:tos_bits NUMBER
Contexts:test_spec where type is perfsonarbuoy/owamp
Occurrences:Zero or one
Default:not set
Compatibility:4.0 or later

Defining Ping Test Parameters

test_interval Directive

Description:The time in between ping tests in seconds
Syntax:test_interval SECONDS
Contexts:test_spec where type is pinger
Occurrences:Exactly one
Compatibility:3.3 or later

force_bidirectional Directive

Description:Forces each endpoint to initiate the test in both directions. This will lead to redundant tests being run on each side.
Syntax:force_bidirectional 0|1
Contexts:test_spec where type is pinger
Occurrences:Zero or one
Default:0
Compatibility:3.3 or later

ipv4_only Directive

Description:Forces each side to use IPv4. Test will fail if no IPv4 address can be determined for either endpoint (-4)
Syntax:ipv4_only 0|1
Contexts:test_spec where type is pinger
Occurrences:Zero or one
Default:0
Compatibility:3.3 or later

ipv6_only Directive

Description:Forces each side to use IPv6. Test will fail if no IPv6 address can be determined for either endpoint (-6)
Syntax:ipv6_only 0|1
Contexts:test_spec where type is pinger
Occurrences:Zero or one
Default:0
Compatibility:3.3 or later

packet_count Directive

Description:The number of packets to send per test. This multiplied by packet_interval is the duration of the test.
Syntax:packet_count NUMBER
Contexts:test_spec where type is pinger
Occurrences:Zero or One
Default:10
Compatibility:3.3 or later

packet_interval Directive

Description:The average time between packets. A decimal value less than one means to send multiple packets per second (e.g. .1 means 10 packets per second). This multiplied by packet_count is the duration of the test. (-i)
Syntax:packet_interval SECONDS
Contexts:test_spec where type is pinger
Occurrences:Zero or One
Default:10
Compatibility:3.3 or later

packet_size Directive

Description:The size of packets in bytes. (ping -s)
Syntax:packet_size BYTES
Contexts:test_spec where type is pinger and tool is ping
Occurrences:Zero or One
Default:Tool default
Compatibility:3.3 or later

packet_ttl Directive

Description:The TTL to set in the IP header of outgoing packets (ping -t)
Syntax:packet_ttl TTL
Contexts:test_spec where type is pinger and tool is ping
Occurrences:Zero or One
Default:System default
Compatibility:3.3 or later

random_start_percentage Directive

Description:The percentage to randomize the start time of test. Valid values are between 0 and 50 (inclusive). Example: interval of 7200 (2 hours) and random_start_percentage 50 means that a test can start anywhere between 1 hour and 3 hours after the previous test completes.
Syntax:random_start_percentage PERCENTAGE
Contexts:test_spec where type is pinger
Occurrences:Zero or one
Default:10
Compatibility:3.3 or later

flow_label Directive

Description:Set the flow label on echo request packets as an integer. (ping6 -F)
Syntax:flow_label INT
Contexts:test_spec where type is pinger and test is running over IPv6
Occurrences:Zero or One
Default:System default
Compatibility:4.0 or later

suppress_loopback Directive

Description:Suppress loopback of multicast packets (ping -L)
Syntax:suppress_loopback 0|1
Contexts:test_spec where type is pinger and tool is ping
Occurrences:Zero or One
Default:System default
Compatibility:4.0 or later

deadline Directive

Description:Specify a timeout, in seconds, before ping exits regardless of how many packets have been sent (ping -w)
Syntax:deadline SECONDS
Contexts:test_spec where type is pinger and tool is ping
Occurrences:Zero or One
Default:System default
Compatibility:4.0 or later

timeout Directive

Description:Time to wait for a response (ping -W)
Syntax:timeout SECONDS
Contexts:test_spec where type is pinger and tool is ping
Occurrences:Zero or One
Default:System default
Compatibility:4.0 or later

hostnames Directive

Description:Do not try to map IP addresses to host names when displaying them. (ping -n)
Syntax:hostnames 0|1
Contexts:test_spec where type is pinger
Occurrences:Zero or one
Default:system default
Compatibility:4.0 or later

tos_bits Directive

Description:The type of service to set in the IP header of outgoing packets as an integer from 0-255.
Syntax:tos_bits NUMBER
Contexts:test_spec where type is pinger
Occurrences:Zero or one
Default:not set
Compatibility:4.0 or later

Defining Traceroute Parameters

test_interval Directive

Description:The time in between traceroute tests in seconds
Syntax:test_interval SECONDS
Contexts:test_spec where type is traceroute
Occurrences:Exactly one
Compatibility:3.3 or later

first_ttl Directive

Description:The first hop to look at starting at 1. This can be used to hide local routers. Not supported by tracepath or paris-traceroute
Syntax:first_ttl TTL
Contexts:test_spec where type is traceroute and tool is traceroute
Occurrences:Zero or more
Default:1
Compatibility:3.3 or later

force_bidirectional Directive

Description:Forces each endpoint to initiate the test in both directions. This will lead to redundant tests being run on each side.
Syntax:force_bidirectional 0|1
Contexts:test_spec where type is traceroute
Occurrences:Zero or one
Default:0
Compatibility:3.3 or later

ipv4_only Directive

Description:Forces each side to use IPv4. Test will fail if no IPv4 address can be determined for either endpoint
Syntax:ipv4_only 0|1
Contexts:test_spec where type is traceroute
Occurrences:Zero or one
Default:0
Compatibility:3.3 or later

ipv6_only Directive

Description:Forces each side to use IPv6. Test will fail if no IPv6 address can be determined for either endpoint
Syntax:ipv6_only 0|1
Contexts:test_spec where type is traceroute
Occurrences:Zero or one
Default:0
Compatibility:3.3 or later

packet_size Directive

Description:The size of packets to send in bytes when performing the traceroute. Not supported by tracepath or paris-traceroute
Syntax:packet_size BYTES
Contexts:test_spec where type is traceroute and tool is traceroute
Occurrences:Zero or one
Default:Tool default
Compatibility:3.3 or later

timeout Directive

Description:The maximum amount of time to wait in seconds for the traceroute to complete
Syntax:timeout SECONDS
Contexts:test_spec where type is traceroute
Occurrences:Zero or one
Default:10
Compatibility:3.3 or later

tool Directive

Description:The tool to use to perform the traceroute.
Syntax:tool traceroute|tracepath|paris-traceroute
Contexts:test_spec where type is traceroute
Occurrences:Zero or more
Default:traceroute
Compatibility:3.3 or later

You can specify on of the following tools for a traceroute test:

  • traceroute - This is the default and generally the more reliable of the tools. It also includes more options in terms of setting the TTL and properly binding to interfaces.
  • tracepath - The main advantage of this tool is it reports MTU by default. It has fewer options than standard traceroute for setting TTLs and binding to local interfaces. It also is UDP-only and may be blocked by firewalls. It’s also been reported to have a harder time with MTU mismatches on the destination host.
  • paris-traceroute - This is another approach to running traceroute that tries to identify load balanced routes and similar. It requires the client to grant the paris-traceroute command the CAP_NET_RAW privilege on the system in order to run as a non-root user.

tos_bits Directive

Description:The type of service to set in the IP header of outgoing packets as an integer from 0-255.
Syntax:tos_bits NUMBER
Contexts:test_spec where type is traceroute
Occurrences:Zero or one
Default:not set
Compatibility:4.0 or later

max_ttl Directive

Description:The maximum number of hops before a traceroute fails. Not supported by tracepath or paris-traceroute
Syntax:max_ttl TTL
Contexts:test_spec where type is traceroute and tool is traceroute
Occurrences:Zero or more
Default:traceroute default (usually 30)
Compatibility:3.3 or later

protocol Directive

Description:Indicates whether to use ICMP or UDP for the traceroute. Not supported by tracepath or paris-traceroute
Syntax:protocol icmp|udp
Contexts:test_spec where type is traceroute and tool is traceroute
Occurrences:Zero or more
Default:icmp
Compatibility:3.3 or later

random_start_percentage Directive

Description:The percentage to randomize the start time of test. Valid values are between 0 and 50 (inclusive). Example: interval of 7200 (2 hours) and random_start_percentage 50 means that a test can start anywhere between 1 hour and 3 hours after the previous test completes.
Syntax:random_start_percentage PERCENTAGE
Contexts:test_spec where type is traceroute
Occurrences:Zero or one
Default:10
Compatibility:3.3 or later

fragment Directive

Description:Set the ‘do not fragment’ bit (traceroute -F)
Syntax:fragment 0|1
Contexts:test_spec where type is traceroute
Occurrences:Zero or one
Default:system default (1)
Compatibility:4.0 or later

probe_type Directive

Description:Sets the Probe type to UDP or ICMP or TCP SYN
Syntax:probe_type icmp|udp|tcp
Contexts:test_spec where type is traceroute
Occurrences:Zero or one
Default:system default
Compatibility:4.0 or later

sendwait Directive

Description:Minimal time interval between probes (traceroute -z)
Syntax:sendwait SECONDS
Contexts:test_spec where type is traceroute
Occurrences:Zero or one
Default:system default
Compatibility:4.0 or later

queries Directive

Description:Sets the number of probe packets per hop (traceroute -q)
Syntax:queries NUM
Contexts:test_spec where type is traceroute
Occurrences:Zero or one
Default:system default
Compatibility:4.0 or later

wait Directive

Description:Set the time (in seconds) to wait for a response to a probe (traceroute -w)
Syntax:wait SECONDS
Contexts:test_spec where type is traceroute
Occurrences:Zero or one
Default:system default
Compatibility:4.0 or later

as Directive

Description:Perform AS path lookups in routing registries and print results directly after the corresponding addresses. (traceroute -A)
Syntax:as 0|1
Contexts:test_spec where type is traceroute
Occurrences:Zero or one
Default:system default
Compatibility:4.0 or later

hostnames Directive

Description:Do not try to map IP addresses to host names when displaying them. (traceroute -n)
Syntax:hostnames 0|1
Contexts:test_spec where type is traceroute
Occurrences:Zero or one
Default:system default
Compatibility:4.0 or later

algorithm Directive

Description:Sets the algorithm used by paris-traceroute (paris-traceroute -a)
Syntax:algorithm hopbyhop|packetbypacket|concurrent|scout|exhaustive
Contexts:test_spec where type is traceroute and tool is paris-traceroute
Occurrences:Zero or one
Default:system default
Compatibility:4.0 or later

Defining Test Topology

<group> Directive

Description:Describes which tests should be run between a given set of addresses. The NAME tag is used to identify the group elsewhere in the configuration.
Syntax:<group NAME>...</group>
Contexts:top level
Occurrences:One or more
Compatibility:3.3 or later

The group directive is one of the primary elements used for defining your configuration. Each group has a at a minimum a type and a list of members. The combination of these elements defines which tests are run. Each member of a group must reference either an address defined in a host block or a host_class. For example, the following defines a group named example_group where each host tests to every other host in the list (i.e. type is mesh). The first two addresses in the list are explicitly defined (10.0.1.1 and 10.0.1.2) and the third is a host class (host_class::ten_gige):

<group example_group>
    type mesh

    member 10.0.1.1
    member 10.0.1.2
    member host_class::ten_gige
</group>

For more on the different types of groups, see the group type section.

type Directive

Description:The type of group, which further determines which options should be used in the rest of the group directive.
Syntax:type disjoint|mesh|ordered_mesh|star
Contexts:group
Occurrences:Exactly one
Compatibility:3.3 or later

The type can be one of the following values:

  • disjoint - This type of test defines that tests are performed between a set of addresses in group A and a second set of addresses in group B. It is possible for an address to be in both groups. See a_member Directive, b_member Directive and no_agent Directive for more information on defining members. Example:

    <group example_disjoint_group>
        type disjoint
    
        a_member 10.0.1.1
        a_member 10.0.1.2
    
        b_member 10.0.2.1
        b_member 10.0.2.2
    </group>
    
  • mesh - This type of test defines that tests are performed between all addresses in the given list. See member Directive and no_agent Directive for more information on defining members. Example:

    <group example_mesh_group>
        type mesh
    
        member 10.0.1.1
        member 10.0.1.2
        member host_class::ten_gige
    </group>
    
  • ordered_mesh - A special type of group were the order an address is listed matters. The first address is responsible for testing to all the hosts listed below it, the second host is responsible for testing to all the hosts below that, etc until the last address is reached, which does not initiate any tests. This ultimately leads to a full mesh, with hosts toward the top of the list taking on a larger burden for initiating and storing tests. This may be desirable if you have a set of more powerful hosts (in terms of hardware) you can put toward the top of this list with less powerful hosts toward the bottom. See member Directive for more information on defining members. Example:

    <group example_ordered_group>
        type ordered_mesh
    
        member 10.0.1.1
        member 10.0.1.2
        member 10.0.2.1
        member 10.0.2.2
    </group>
    
  • star - A mesh where a single center address tests to all other members of the group. See center_address Directive and member Directive for more information on defining members. Example:

     <group example_star_group>
        type star
    
        center_address 10.0.0.1
    
        member 10.0.1.1
        member 10.0.1.2
        member 10.0.2.1
        member 10.0.2.2
    </group>
    

Note

The functional equivalent of a star group can alternatively be defined as a disjoint group where the a_member OR b_member is the center_address.

a_member Directive

Description:For disjoint type groups, defines an address belonging to group A. This address will only test to addresses defined in group B using the b_member directive and will NOT test to other addresses in group A (unless they are also in group B). Note that the address MUST map to an address defined in one (and only one) host directive.
Syntax:a_member ADDRESS
Contexts:group where type is disjoint
Occurrences:One or more
Compatibility:3.3 or later

b_member Directive

Description:For disjoint type groups, defines an address belonging to group B. This address will only test to addresses defined in group A using the a_member directive and will NOT test to other addresses in group B (unless they are also in group A). Note that the address MUST map to an address defined in one (and only one) host directive.
Syntax:b_member ADDRESS
Contexts:group where type is disjoint
Occurrences:One or more
Compatibility:3.3 or later

center_address Directive

Description:For star type groups, defines the address that will test to all other addresses defined by the member directive. Note that the address MUST map to an address defined in one (and only one) host directive.
Syntax:center_address ADDRESS
Contexts:group where type is star
Occurrences:Exactly one
Compatibility:3.3 or later

member Directive

Description:Defines an address to be used in a group of various types (see Context row later in this table). Note that the address MUST map to an address defined in one (and only one) host directive.
Syntax:member ADDRESS
Contexts:group where type is mesh, ordered_mesh or star
Occurrences:One or more
Compatibility:3.3 or later

no_agent Directive

Description:Defines an address that will not initiate tests when used in this group. This will override the no_agent field specified in the host directive if defined. It is recommended you use the host directive to define this if a address cannot initiate tests for any group. Only use this form if you want a host to initiate tests when used in some groups but not others.
Syntax:no_agent ADDRESS
Contexts:group
Occurrences:Zero or more
Compatibility:3.3 or later

Defining Tests

<test> Directive

Description:Maps a test_spec to group.
Syntax:<test>...</test>
Contexts:top level
Occurrences:One or more
Compatibility:3.3 or later

A <test> directive is essentially the final step in defining the set of measurements to be run on participating hosts. By mapping a test_spec to a group, you are declaring you want a test run with the parameters defined in test_spec for each point-to-point pair defined in group. You also provided a description to name the test. The description has little significance to the tests themselves, but may be used for display purposes in a user interface, such as naming a grid in a dashboard. An example is below:

<test>
    description Example BWCTL Tests
    test_spec example_bwctl_spec
    group example_mesh_group
<test>

group Directive

Description:The name of the group to use. The name must be exactly the NAME used when defining the group.
Syntax:group NAME
Contexts:test
Occurrences:Exactly one
Compatibility:3.3 or later

test_spec Directive

Description:The name of the test_spec to use. The name must be exactly the NAME used when defining the test_spec
Syntax:test_spec NAME
Contexts:test
Occurrences:Exactly one
Compatibility:3.3 or later

Dynamic Mesh Generation

tag Directive

Description:A custom string used to label an organization, site, host or address
Syntax:tag TAG
Contexts:organization, site, host, address
Occurrences:Zero or more
Compatibility:3.5 or later

The tag directive labels the parent object in a custom way. This label can then be used in a <host_class> Directive definition to match items sharing the same tag. A good example is if you want to tag some <address> directives as “latency” and others as “throughput” on a dual-homed host. You can then define a host tag that selects only the “throughput” interfaces for throughput tests and “latency” interfaces for latency tests.

<host_class> Directive

Description:Defines a set of criteria that if a host meets, then will be included in this class. the class can then be referenced by name in test definitions to include groups of hosts.
Syntax:<host_class>...<host_class>
Contexts:top level
Occurrences:Zero or more
Compatibility:3.5 or later

The <host_class> structure is one of the more complex in the MeshConfig. It is the foundational element in generating dynamic lists of hosts. A host_class has a name used to identify it, one or more data sources that contain an initial list of hosts, and a set of filters used to select hosts from the data sources that meet certain criteria. Optionally it may also have host properties used to set attributes on matching hosts such as measurement archives for storing test results. This host class can then be referenced in a <group> Directive as a member using the notation host_class::NAME where NAME is the name of the hos class. For example, below we define a host_class that matches all hosts in our current mesh file (that’s our data source in this case) belonging to organization Acme:

<host_class>
    name      acme_org

    <data_source>
        type     current_mesh
    </data_source>

    <match>
       <filter>
           type   organization
           description   Acme
       </filter>
    </match>
</host_class>

We could then letter reference this host_class in a group as follows:

<group example_group>
    type mesh

    member 10.0.1.1
    member 10.0.1.2
    member host_class::acme_org
</group>

An hosts we add to our mesh in the future with organization “Acme” will automatically get added to the test definitions using this group.

name Directive

Description:Names a host_class. This is used to reference the host class in group definitions later.
Syntax:name CLASSNAME
Contexts:<host_class> Directive
Occurrences:Exactly one
Compatibility:3.5 or later

data_source Directive

Description:The data source from which to build an initial list of hosts before applying filters. See <config_mesh-dynamic_sources> for information in different types of data sources and their options.
Syntax:<data_source>...</data_source>
Contexts:<host_class> Directive
Occurrences:One or more
Compatibility:3.5 or later

match Directive

Description:Contains a list of filters that must be matched. An empty match filter matches everything. The exclude directive takes precedence if they both match the same host. Within a match directive, filters of the same type have an implied OR condition and filter of a different type have an implied AND condition.
Syntax:<match>...</match>
Contexts:<host_class> Directive
Occurrences:Zero or one
Compatibility:3.5 or later

exclude Directive

Description:Contains a list of filters that if matched, exclude the host from the class. An empty exclude filter matches excludes nothing. This directive takes precedence over the match directive if they both match the same host. Within an exclude directive, filters of the same type have an implied OR condition and filter of a different type have an implied AND condition.
Syntax:<exclude>...</exclude>
Contexts:<host_class> Directive
Occurrences:Zero or one
Compatibility:3.5 or later

filter Directive

Description:Used in match, exclude and certain other ref:filter <config_mesh-dynamic_gen-filter> directives to select a host. See Dynamic Mesh Filters for a list of filter types and their options.
Syntax:<filter>...</filter>
Contexts:match Directive, exclude Directive, filter Directive where type is and, or or not.
Occurrences:Zero or one
Compatibility:3.5 or later

<host_properties> Directive

Description:Defines properties to assign hosts that match the specified class. Primarily used to set the measurement archives where test results will be stored. This is a host directive, so any sub-directives supported by host are also supported by host_properties. You do not need to set the address. In general, this will only contain measurement archive directives. If the properties set in the block conflict with any already set in an explicit host directive, then the configurations will be merged. For measurement archives this means that both sets of archives will be used.
Syntax:<host_properties>...<host_properties>
Contexts:<host_class> Directive
Occurrences:Zero or one
Compatibility:3.5 or later

Dynamic Mesh Data Sources

type Directive

Description:Defines the type of data source to be used to build the initial list of hosts
Syntax:type current_mesh|requesting_agent
Contexts:data_source Directive
Occurrences:Exactly one
Compatibility:3.5 or later

The type of data source defines where a <host_class> Directive get the initial list of hosts where filters will be applied. The following are valid values for the type:

  • current_mesh - Looks at all host definitions in the current mesh file
  • requesting_agent - Looks at the client reading the mesh file as a host

Dynamic Mesh Filters

type Directive

Description:Defines the type of filter.
Syntax:type address_type|and|class|netmask|not|or|organization|site|tag
Contexts:filter Directive
Occurrences:Exactly one
Compatibility:3.5 or later

The type of filter indicates what property of the address or its parent elements to match against. There are also some special filters that define boolean operations across multiple filters. The valid types and their meanings are:

  • address_type - Matches addresses on hosts of the specified type (e.g. ipv4 or ipv6)
  • and - A special operand that takes a set of filters and will return true if ALL filters match
  • class - This takes the name of another class and only returns true if the host also belong to the specified class. This allows a simple form of inheritance between classes.
  • netmask - Matches a address if it is in the specified IP netmask
  • not - A special operand that returns true only if the underlying filters return false and vice versa
  • or - A special operand that takes a set of filters and will return true if ANY filters match
  • organization - Matches the organization ref:description <config_mesh-description> of a host
  • site - Matches the site ref:description <config_mesh-description> of a host
  • tag - Matches a tag on an address or its parent organization, site, or host

address_type Directive

Description:Defines the type of address to match against for filters with type address_type
Syntax:address_type ipv4|ipv6
Contexts:filter Directive where type is address_type
Occurrences:Exactly one
Compatibility:3.5 or later

class Directive

Description:Defines the name of the host_class to match against for filters with type class
Syntax:class CLASSNAME
Contexts:filter Directive where type is class
Occurrences:Exactly one
Compatibility:3.5 or later

description Directive

Description:Defines the description of the parent organization or site to match for hosts belonging to this class
Syntax:description DESCRIPTION
Contexts:filter Directive where type is organization or site
Occurrences:Exactly one
Compatibility:3.5 or later

exact Directive

Description:Indicates the given match should be case-sensitive if enabled. Disabled (i.e. case-insensitive matches) by default if not specified.
Syntax:exact 0|1
Contexts:filter Directive where type is tag, organization or site
Occurrences:Exactly one

netmask Directive

Description:The IP netmask used to match addresses when filter type is netmask
Syntax:netmask NETMASK
Contexts:filter Directive where type is netmask
Occurrences:Exactly one

tag Directive

Description:The tag to match for an address or its parent elements in order for it to be included in the mesh
Syntax:tag TAG
Contexts:filter Directive where type is tag
Occurrences:Exactly one

Optional Descriptive Fields

<administrator> Directive

Description:Defines contact information for administrator of parent element
Syntax:<administrator>...</administrator>
Contexts:top level, organization, site, host
Occurrences:Zero or more
Compatibility:3.3 and later

This element is primarily used for informational purposes. If defined at the top-level, it is assumed it is the contact information of the person managing this mesh. It is not strictly required in any of it’s parent elements but may be useful in keeping track of the various administrators of meshes, organization, hosts and/or sites.

name Directive

Description:The full name of the administrator.
Syntax:name ADMINISTRATOR NAME
Contexts:administrator
Occurrences:Exactly one per parent
Compatibility:3.3 and later

email Directive

Description:The full name of the administrator.
Syntax:email ADMIN@MYDOMAIN
Contexts:administrator
Occurrences:Exactly one per parent
Compatibility:3.3 and later

<location> Directive

Description:A directive to describe the location of the parent
Syntax:<location>...</location>
Contexts:organization, site, host
Occurrences:Zero or One
Compatibility:3.3 or later

This element’s intent is primarily for uses for displays that are capable of showing location information. At this point it is largely unused and may be skipped if so desired.

street_address Directive

Description:The street address (e.g. 1 Cyclotron Road) of the parent location
Syntax:street_address ADDRESS
Contexts:location
Occurrences:Exactly one
Compatibility:3.3 or later

city Directive

Description:The city (e.g. Berkeley) of the parent location
Syntax:city CITY
Contexts:location
Occurrences:Exactly one
Compatibility:3.3 or later

state Directive

Description:The state, province or other country-specific region (e.g. CA) of the parent location
Syntax:state STATE
Contexts:location
Occurrences:Exactly one
Compatibility:3.3 or later

country Directive

Description:The 2-letter ISO country code (e.g. US) of the parent location
Syntax:country COUNTRY
Contexts:location
Occurrences:Exactly one
Compatibility:3.3 or later

postal_code Directive

Description:The postal code (e.g. 94720) of the parent location
Syntax:postal_code POSTAL_CODE
Contexts:location
Occurrences:Exactly one
Compatibility:3.3 or later

latitude Directive

Description:The latitude (e.g. 37.8717) of the parent location
Syntax:latitude LATITUDE
Contexts:location
Occurrences:Exactly one
Compatibility:3.3 or later

longitude Directive

Description:The longitude (e.g. -122.2728) of the parent location
Syntax:longitude LONGITUDE
Contexts:location
Occurrences:Exactly one
Compatibility:3.3 or later