Skip to main content

Configuration File

Verifier reads a YAML file (verifier.yaml by default) that tells it where to find your model, how to start your component, which transports to use, and how many attempts to make. This page lists every key in that file, whether it is required, its default, and the values it accepts.

Three keys are required: flex_json_paths, commands, and license_file. Every other key has a default.

Pass a different file with verifier -c FILE run or verifier -c FILE doctor. Changes to the file after Verifier starts have no effect on the current run.

tip

Run verifier init to generate a starting configuration from your model, and verifier doctor to check a configuration before running a test. The same reference is built into Verifier: run verifier docs open config and verifier docs open transports.

Minimal Configuration​

The smallest configuration that runs a test:

flex_json_paths:
  - ./sensor.json
license_file: ./license.zip
serializer: direct

commands:
  - command: /usr/local/bin/sensor
    startup_ms: 500

transports:
  - name: main
    type: zmq
    settings:
      pub_socket:
        ip: 127.0.0.1
        port: 6667
        type: Connect
      sub_socket:
        ip: 127.0.0.1
        port: 6668
        type: Connect

Top-Level Keys​

KeyRequiredDefaultSection
flex_json_pathsYesTest Options
license_fileYesTest Options
commandsYesCommands
timeout_msNo1000Test Options
test_typeNovalidTest Options
iterationsNo1Test Options
attemptsNo1Test Options
seedsNoRandomTest Options
componentNoTest Options
passiveNofalseTest Options
proto_file_mapNoTest Options
profileNoTest Options
serializerNodirectSerialization
package_serializersNoSerialization
generationNoGeneration
redisNoRedis
transportsNoTransports

Test Options​

  • flex_json_paths: Required List of paths to compiled Flex JSON model files. Verifier loads all of them and merges their type environments.
  • license_file: Required Path to the license bundle. verifier run fails without it, and verifier doctor reports an error. The file itself may be mounted at runtime; verifier doctor warns rather than errors when the key is set but the file is not on disk yet.
  • timeout_ms: Optional (Defaults to 1000) How long Verifier waits for an expected message, in milliseconds, before recording a timeout. A protocol can override this with the @Timeout annotation.
  • test_type: Optional (Defaults to valid) The kind of messages to generate. Values are case-insensitive:
    • valid: messages that satisfy every constraint
    • invalid: messages that violate at least one constraint
    • random: unconstrained random messages. rand is also accepted.
  • iterations: Optional (Defaults to 1) How many times to run the full set of protocols. Each iteration tests every protocol from a fresh start. The key reruns is accepted as a deprecated alias.
  • attempts: Optional (Defaults to 1) How many attempts each protocol gets per iteration. The CLI flag --retries overrides this value when given. See why attempts are needed.
  • seeds: Optional List of seeds for the random number generator (std::mt19937_64). One seed is consumed per iteration; if more iterations run than seeds are provided, Verifier generates the remainder. A fixed seed list makes every test produce the same generated values.
  • component: Optional Fully-qualified name of the component under test. Required when the model declares more than one component; omit it when there is exactly one. verifier init fills this in for you.
  • passive: Optional (Defaults to false) When true, Verifier listens on all configured connections and validates only what it receives. It never sends.
  • proto_file_map: Optional Path to proto_file_map.txt. Needed only when using the protobuf serializer and Verifier cannot find the file automatically in the Flex package.
  • profile: Not yet implemented. Accepted without an unknown-key warning; currently has no effect.

Serialization​

  • serializer: Optional (Defaults to direct) Default serializer for all packages. Values are case-insensitive:
    • direct: raw binary
    • json: JSON
    • protobuf: Protocol Buffers
    • csv: CSV
    • lmcp: LMCP
    • mavlink: MAVLink
    • oms20xml: OMS 2.0 XML
    • ros: ROS
    • stanag4586: STANAG 4586
    • uai: UAI
    • wosa: WOSA
    • xml: XML
  • package_serializers: Optional Per-package serializer overrides. Maps a fully-qualified package name (e.g., MyPackage::v1) to a serializer value from the list above. Packages not in the map use serializer.

The direct, json, and xml formats follow Tangram's own generic format.

serializer: direct
package_serializers:
  MyPackage::v1: json
  OtherPackage: protobuf

Generation​

The generation section controls how Verifier generates message content. Constraints in your model override these defaults for the fields they cover.

  • recursionDepth: Optional (Defaults to 20) Maximum depth Verifier recurses into nested message fields. Verifier logs an informational message on passing 80% of this value and a warning when it stops descending at the cap.
  • listLimits: Optional Default length range for generated lists that have no @Length annotation or length constraint:
    • minLength: Optional (Defaults to 0) Minimum number of elements
    • maxLength: Optional (Defaults to 10) Maximum number of elements. Must not be less than minLength.
  • floatLimits: Not yet implemented. Verifier validates this section but does not apply it; generated floats are not bounded by it. Constrain floats in your model instead. Omitting the section means no bounds. When present:
    • min: Optional (Defaults to -1000000.0) Minimum float value. Set to None (or none) for no lower bound.
    • max: Optional (Defaults to 1000000.0) Maximum float value. Set to None (or none) for no upper bound. Must not be less than min.

When reading or writing these with verifier config, the float bounds are addressed as generation.floatLimits.minValue and generation.floatLimits.maxValue, even though the YAML keys are min and max.

generation:
  recursionDepth: 15
  listLimits:
    minLength: 1
    maxLength: 5

Redis​

When set, Verifier writes structured logs, test results, and a done message to a Redis pub/sub channel during the run.

  • redis: Optional Redis configuration:
    • hostname: Required IP or hostname of the Redis server
    • port: Required Port for Redis pub/sub
    • password: Required Authentication password
    • topic: Required Channel name. Every message on this channel carries a logtype key: log, result, or done.
redis:
  hostname: localhost
  port: 12000
  password: redis
  topic: verifier-output

Commands​

Verifier controls the lifecycle of your component. List how to start it under commands; at least one entry is required. When multiple are listed, each starts in the order given, and each waits out its own startup_ms before the next begins.

A command with restart: true (the default) is started before each attempt and torn down after it, so every attempt sees a fresh process. A command with restart: false starts once at the beginning of an iteration and stays up for that whole iteration.

Verifier decides each entry's kind from the keys it contains, checked in this order:

  1. Any of commandStart, commandKill, or commandWatch: External Command
  2. Any of k8s_namespace or k8s_name: Kubernetes Pod
  3. image: Docker Container
  4. Otherwise: Direct Binary

For every kind, startup_ms is a maximum: if the component sends a message before it elapses, Verifier treats the component as ready immediately.

Direct Binary​

A binary Verifier launches and manages directly with signals.

  • command: Required The full command line including arguments, as a single string. Use the full path to the binary.
  • startup_ms: Required Milliseconds to wait after starting the process before beginning the test.
  • shutdown_ms: Optional (Defaults to 0) Milliseconds to wait after sending SIGINT and the process exiting, before starting the process again.
  • capture_stdout: Optional (Defaults to true) Collect stdout and log it when the process exits.
  • capture_stderr: Optional (Defaults to true) Collect stderr and log it when the process exits.
  • restart: Optional (Defaults to true) When true, start and stop the process around each attempt. When false, start once per iteration.
commands:
  - command: /usr/local/bin/sensor --listen 6668 --report 6667
    startup_ms: 500
    shutdown_ms: 200

Docker Container​

A Docker container Verifier runs and stops.

  • image: Required Docker image name (e.g., sensor:latest)
  • startup_ms: Required Milliseconds to wait after starting the container before beginning the test.
  • container_name: Optional Name to give the container.
  • ports: Optional Port mappings in Docker format (e.g., ["8080:80", "443:443"])
  • environment: Optional Environment variables in KEY=VALUE format (e.g., ["DEBUG=1", "PORT=8080"])
  • volumes: Optional Volume mounts in Docker format (e.g., ["/host/path:/container/path"])
  • host_network: Optional (Defaults to false) Use host network mode.
  • shutdown_ms: Optional (Defaults to 0) Milliseconds to wait after stopping and removing the container before starting it again.
  • capture_stdout: Optional (Defaults to true) Collect the container's stdout and log it.
  • capture_stderr: Optional (Defaults to true) Collect the container's stderr and log it.
  • restart: Optional (Defaults to true) Same as Direct Binary.
commands:
  - image: sensor:latest
    container_name: sensor-test
    ports:
      - "6668:6668"
    startup_ms: 1000

Kubernetes Pod​

A pod already running in a cluster. Verifier cycles the pod to control component lifetime.

  • k8s_namespace: Required Namespace the pod lives in.
  • k8s_name: Required The pod must have an app label with this value.
  • startup_ms: Required Milliseconds to wait after restarting the pod before beginning the test.
  • shutdown_ms: Optional (Defaults to 0) Milliseconds to wait after deleting the pod before recreating it.
  • restart: Optional (Defaults to true) Same as Direct Binary.
commands:
  - k8s_namespace: default
    k8s_name: sensor
    startup_ms: 2000

External Command​

A component whose lifetime is managed outside Verifier. Verifier signals it by running short commands and watches a file to learn when the component exits on its own.

  • commandStart: Required Command to signal the component to start.
  • commandKill: Required Command to signal the component to stop.
  • commandWatch: Required Path to a file Verifier watches with inotify. Any modification is treated as the component having exited.
  • startup_ms: Required Milliseconds to wait after running commandStart before beginning the test.
  • shutdown_ms: Optional (Defaults to 0) Milliseconds to wait after running commandKill before running commandStart again.
  • restart: Optional (Defaults to true) Same as Direct Binary.
commands:
  - commandStart: /bin/bash -c 'echo start > /tmp/startfile'
    commandKill:  /bin/bash -c 'echo kill  > /tmp/killfile'
    commandWatch: /tmp/watchfile
    startup_ms: 1000
    shutdown_ms: 5000

Transports​

A transport connects Verifier to your component on the wire. Each entry in the transports list names the transport, specifies its type and settings, and optionally lists the model connections it carries.

transports:
  - name: my_transport
    type: zmq
    settings:
      # type-specific settings, see below
    connections:
      - name: connection_name
    byte_map:
      # optional, see Byte Mapping
    topic_map:
      # optional, see Topic Mapping
    ignore_messages:
      - MyPackage::MessageToIgnore

  • name: Required Unique identifier for this transport within the configuration.

  • type: Required Transport type. Case-insensitive. See Transport Types.

  • settings: Required Type-specific settings.

  • connections: Optional List of model connections this transport carries. Each entry identifies a connection by one of:

    • name: The fully-qualified connection name from the model.
    • to and from: The component names on each end of the connection.

    Verifier assigns connections automatically when the model has one connection per direction; use connections when you need explicit control.

  • byte_map: Optional Rules to identify message type from raw bytes. See Byte Mapping.

  • topic_map: Optional Rules to map topic strings to message names and back. See Topic Mapping.

  • ignore_messages: Optional Fully-qualified message names to discard on this transport without processing.

Transport Types​

Transporttype values
ActiveMQamq, activemq, amqpubsub, activemqpubsub
Filefile, filepubsub
Kafkakafka, kafkapubsub
MQTTmqtt, mqttpubsub
NATSnats, natspubsub
RabbitMQrmq, rabbitmq, rmqpubsub, rabbitmqpubsub
Serialserial
TCPtcp
UDPudp
ZeroMQzmq, zeromq, zmqpubsub, zeromqpubsub

Across types, max_send_size and max_recv_size are the largest message Verifier can send and receive, in bytes, and startup_ms is how many milliseconds Verifier waits after connecting.

ActiveMQ​

  • broker_uri: Required Broker URI (e.g., tcp://127.0.0.1:61616)
  • auto_ack: Optional (Defaults to true) Auto-acknowledge messages from the broker.
  • use_text: Optional (Defaults to true) Convert bytes to text before sending.
  • max_send_size: Optional (Defaults to 65536)
  • max_recv_size: Optional (Defaults to 65536)
  • startup_ms: Optional (Defaults to 20)
  • tls: Optional TLS settings:
    • keystore_file: Path to the keystore
    • keystore_pass: Keystore password
    • trust_cert_file: Path to the truststore
    • trust_cert_pass: Truststore password
transports:
  - name: amq
    type: activemq
    settings:
      broker_uri: failover:(tcp://127.0.0.1:61616)?timeout=1000

File​

Verifier reads messages from one directory and writes to another.

  • recv_dir: Required Directory Verifier reads incoming messages from.
  • send_dir: Required Directory Verifier writes outgoing messages to.

Kafka​

  • brokers: Required Broker address (e.g., 127.0.0.1:9092)
  • group: Required Consumer group ID.
  • partition: Optional (Defaults to 0) Partition to use.
  • max_send_size: Optional (Defaults to 65536)
  • max_recv_size: Optional (Defaults to 65536)
  • startup_ms: Optional (Defaults to 20)
transports:
  - name: kafka
    type: kafka
    settings:
      brokers: 127.0.0.1:9092
      group: verifier

MQTT​

  • pub_socket: Required Publish socket:
    • ip: Broker IP address
    • port: Port number
    • type: Bind or Connect. Use Connect to reach a broker.
  • sub_socket: Required Subscribe socket (same fields as pub_socket)
  • max_send_size: Optional (Defaults to 65536)
  • max_recv_size: Optional (Defaults to 65536)
  • startup_ms: Optional (Defaults to 20)
  • tls: Optional TLS settings:
    • ca_file: Path to the CA certificate
    • tls_cert: Path to the client certificate
    • tls_key: Path to the client private key

NATS​

  • max_send_size: Optional (Defaults to 65536)
  • max_recv_size: Optional (Defaults to 65536)
  • startup_ms: Optional (Defaults to 20)
  • tls_host: Optional TLS hostname
  • queue_topic: Optional Queue topic name
  • tls: Optional TLS settings:
    • tls_key: Path to the private key
    • tls_cert: Path to the certificate
  • auth: Optional Authentication:
    • username: Username
    • password: Password
    • nk_pub_key: NKey public key
    • nk_seed: NKey seed
  • options: Optional NATS client options, passed through to the NATS C client. All are optional:
    • Strings: url (e.g., nats://127.0.0.1:4222), token, name, load_ca_trusted_certificates, ca_trusted_certificates, ciphers, cipher_suites, expected_hostname
    • Integers: timeout (connect timeout, milliseconds), ping_interval, reconnect_wait, io_buf_size, max_reconnect, reconnect_buf_size, max_pending_msgs, ip_resolution_order, message_buffer_padding
    • Booleans: no_randomize, secure, verbose, pedantic, skip_server_verification, allow_reconnect, ignore_discovered_servers, use_global_message_delivery, send_asap, use_old_request_style, fail_requests_on_disconnect, no_echo, disable_no_responders
transports:
  - name: nats
    type: nats
    settings:
      options:
        url: nats://127.0.0.1:4222
        timeout: 2000

RabbitMQ​

  • url: Required Broker URL (e.g., amqp://127.0.0.1:5672)
  • channel: Required Virtual channel ID.
  • max_send_size: Optional (Defaults to 65536)
  • max_recv_size: Optional (Defaults to 65536)
  • startup_ms: Optional (Defaults to 20)
  • ssl: Optional SSL settings:
    • cert: Path to the client certificate
    • ca_cert: Path to the CA certificate
    • key: Path to the client private key
    • verify_peer: Required true to verify the server certificate
    • verify_hostname: Required true to verify the server hostname

Serial​

Like TCP, a serial transport carries traffic in one direction: Bind only receives and Connect only sends.

  • type: Required Bind or Connect. Case-sensitive.
  • port: Required Serial device path (e.g., /dev/ttyUSB0)
  • baud_rate: Optional (Defaults to 9600)
  • bits_per_byte: Optional (Defaults to 8) Data bits.
  • stop_bits: Optional (Defaults to 1)
  • flow_control: Optional Flow control type.
  • parity: Optional Parity mode.
  • non_blocking: Optional (Defaults to false) Use non-blocking I/O.
  • recv_timeout: Optional (Defaults to 1000) Receive timeout in milliseconds.
  • max_send_size: Optional (Defaults to 65536)
  • max_recv_size: Optional (Defaults to 65536)
  • startup_ms: Optional (Defaults to 20)

TCP​

A TCP stream transport. Each TCP transport carries traffic in one direction only, set by type:

  • Bind: Verifier listens on ip:port and accepts a connection from the component. This transport only receives.
  • Connect: Verifier connects out to the component at ip:port. This transport only sends.

A component that both sends and receives needs two TCP transports: one Bind for messages from the component, and one Connect for messages to it. Verifier assigns each model connection to the transport whose direction matches.

  • type: Required Bind or Connect. Case-sensitive.
  • ip: Required IP address or hostname. For Bind, the local address to listen on (0.0.0.0 for all interfaces). For Connect, the component's address.
  • port: Required Port number.
  • max_size: Optional (Defaults to 65536) Largest message Verifier can receive, in bytes.
  • startup_ms: Optional (Defaults to 20) Milliseconds to wait after connecting before sending.
  • has_topic: Optional (Defaults to false) When true, a packet holding the topic string precedes each data packet, in both directions. See Topic Packets.
  • use_ipv4: Optional true forces IPv4, false forces IPv6. Left unset, Verifier determines the address family from the address.
transports:
  - name: from_component
    type: tcp
    settings:
      type: Bind
      ip: 0.0.0.0
      port: 6667
  - name: to_component
    type: tcp
    settings:
      type: Connect
      ip: 127.0.0.1
      port: 6668
      startup_ms: 100

UDP​

A UDP datagram transport. Like TCP, each UDP transport carries traffic in one direction only, set by type:

  • Bind: Verifier binds ip:port and receives datagrams the component sends there. This transport only receives.
  • Connect: Verifier sends datagrams to the component at ip:port. This transport only sends.

A component that both sends and receives needs one Bind and one Connect transport. Each message is one datagram, so a message larger than max_size or the network's datagram limit cannot be carried.

  • type: Required Bind or Connect. Case-sensitive.
  • ip: Required IP address or hostname. For Bind, the local address to receive on (0.0.0.0 for all interfaces). For Connect, the component's address.
  • port: Required Port number.
  • max_size: Optional (Defaults to 65536) Largest datagram Verifier can receive, in bytes.
  • startup_ms: Optional (Defaults to 20) Milliseconds to wait after opening the socket before sending.
  • has_topic: Optional (Defaults to false) When true, a datagram holding the topic string precedes each data datagram, in both directions. See Topic Packets.
  • use_ipv4: Optional true forces IPv4, false forces IPv6. Left unset, Verifier determines the address family from the address.
transports:
  - name: from_component
    type: udp
    settings:
      type: Bind
      ip: 0.0.0.0
      port: 6667
  - name: to_component
    type: udp
    settings:
      type: Connect
      ip: 127.0.0.1
      port: 6668
      startup_ms: 100

Topic Packets​

With has_topic: true on a TCP or UDP transport, Verifier identifies each received message from its topic packet, trying in order:

  1. byte_map, when set (applied to the data packet, not the topic)
  2. topic_map.incoming, when set
  3. The topic string itself, taken as the fully-qualified message name

When sending, Verifier takes the topic from the message's @Topic annotation in the model, or else from topic_map.outgoing. A message with neither is a configuration error.

ZeroMQ​

Each side holds a publish socket and a subscribe socket.

  • pub_socket: Required Publish socket:
    • ip: IP address to connect or bind to
    • port: Port number
    • type: Bind or Connect
  • sub_socket: Required Subscribe socket (same fields as pub_socket)
  • uses_proxy: Optional (Defaults to false) When true, the connection goes through an external ZeroMQ proxy. Set both sockets to Connect.
  • max_send_size: Optional (Defaults to 65536)
  • max_recv_size: Optional (Defaults to 65536)
  • startup_ms: Optional (Defaults to 20)
  • curve: Optional ZeroMQ CURVE encryption:
    • public_key: Path to the public key file
    • secret_key: Path to the secret key file
    • server_ip: Server IP address
    • server_key: Server public key
transports:
  - name: zmq_transport
    type: zmq
    settings:
      uses_proxy: false
      pub_socket:
        ip: 127.0.0.1
        port: 6667
        type: Connect
      sub_socket:
        ip: 127.0.0.1
        port: 6668
        type: Connect

Byte Mapping​

Use byte_map when the transport carries no topic and you need to extract the message type from the payload itself. Verifier reads a byte slice from each received message, converts it to an integer or string, and looks up the message name in your map.

  • from: Required Start byte index, counted from zero. Inclusive.
  • to: Required End byte index. Must not be less than from. How it is counted depends on conversion:
    • LittleEndian and BigEndian: inclusive. from: 0 and to: 3 read four bytes. At most eight bytes.
    • String: exclusive. from: 0 and to: 4 read four bytes.
  • conversion: Required How to interpret the bytes. Case-sensitive:
    • LittleEndian: unsigned integer, least significant byte first
    • BigEndian: unsigned integer, most significant byte first
    • String: raw characters
  • map: Required Map from converted value to fully-qualified message name. For integer conversions, keys are written as strings and may be decimal ("10"), hexadecimal ("0x0A"), or octal ("012").

Reading a four-byte little-endian message ID:

byte_map:
  from: 0
  to: 3
  conversion: LittleEndian
  map:
    "1": "MyPackage::MessageA"
    "2": "MyPackage::MessageB"

Topic Mapping​

Use topic_map on topic-routed transports (ActiveMQ, Kafka, MQTT, NATS, RabbitMQ, ZeroMQ, and TCP or UDP with has_topic: true) to derive message names from incoming topics and produce outgoing topics from message names.

  • incoming: Optional List of rules for received messages. Rules are tried in order; the first match wins. Each rule:
    • topic_regex: Required Regular expression matched against the incoming topic string. Capture groups are referenced as $1, $2, etc. in the other fields.
    • package: Optional Package name, or a capture group reference.
    • module: Required Module name, or a capture group reference. Dots in the result become ::, so sub.module names sub::module.
    • message: Required Message name, or a capture group reference.
  • outgoing: Optional Template for outgoing topic strings:
    • topic_template (or template): Template string. Supported placeholders:
      • {package}: Package name
      • {module}: Module name
      • {message}: Message name
      • {fullname}: package.module.message, joined with dots
topic_map:
  incoming:
    - topic_regex: "^myapp/(.+)/(.+)$"
      package: "MyPackage"
      module: "$1"
      message: "$2"
  outgoing:
    topic_template: "{package}/{module}/{message}"