twampyre Configuration Guide

twampyre uses a structured YAML-based configuration system with three main sections:

• plugins – declares and configures globally available plugins.
• kinds – defines reusable test-suite templates (can inherit from each other).
• targets – specifies actual test instances, based on kinds.

🧩 Section: plugins

The plugins section defines which plugins should be loaded at runtime. Each entry enables a plugin and may include global settings applied to all test sessions using that plugin.

Only plugins listed in this section will be activated.

plugins:
  icmp: {}  # Enable ICMP plugin with default settings
  twamp:
    traffic_class: 0
    ttl: 64

📦 Section: kinds

The kinds section defines reusable configurations for test sessions. Think of them as named templates that group plugin-specific settings. In essence, those define a suite of test definitions to be executed.

Kinds can extend other kinds using the extends key. The inheritance chain is resolved before applying settings to a target.

kinds:
  server:
    icmp:
      interval: 5
      payload_size: 1000
      tags: ["twampyre", "funtime"]

  webserver:
    extends: server
    icmp:
      payload_size: 500
    http:
      scheme: https

In this example, webserver inherits all ICMP settings from server and adds its own HTTP settings. It override the payload_size. Multi-level inheritance is supported. Avoid self-dependence and circular dependencies.

🧪 Target Section

The targets section defines network / services under test. The key is the target IP-address or hostname. Target entry may reference one kind, and can override or extend its settings.

targets:
  10.0.0.1:
    kind: server

  www.example.com:
    kind: webserver
    http:
      pattern: .*example.*

  www.example.com#search:
    kind: webserver
    http:
      request: /browse

• The #search suffix uniquely identifies this instance.
• Suffixes also act as instance tags, which are included as labels in all collected metrics.

🔁 Inheritance & Overrides

• A target inherits plugin configurations from its kind.
• A kind can extend another kind, enabling inheritance to define/reuse of common settings. By this, DRY principles can be achieved.
• Parameters defined at a more specific level (target > kind > extends) override those at more general levels.

---

🏷️ Tags and Metrics

• Use the tags list to associate custom labels with test sessions.
• Tags and instance suffixes both appear in metric labels, allowing rich filtering and aggregation.

Example metric labels:

• target = www.example.com
• plugin = http
• kind = webserver
• tag_twampyre = true
• tag_funtime = true
• target_instance = search77
• direction = roundtrip
• reason = timeout

✅ Summary

Section	Purpose
plugins	Enable and configure plugins globally
kinds	Define reusable session templates
targets	Specify real test destinations

This flexible structure enables concise, modular, and scalable test configurations across many hosts and protocols.