JSON Discovery Configuration

AstuteDDS supports a JSON discovery configuration for explicit peer bootstrap and interface targeting.

It is a vendor configuration feature mapped to standard RTPS SPDP behavior.

Enable via Environment

Set ASTUTEDDS_DISCOVERY_JSON to a JSON file path:

export ASTUTEDDS_DISCOVERY_JSON=/path/to/discovery.json
./my_dds_app

The transport loads this file during RtpsUdpTransport::init().

Optional hot-reload (poll file changes):

export ASTUTEDDS_DISCOVERY_JSON=/path/to/discovery.json
export ASTUTEDDS_DISCOVERY_JSON_WATCH=1
./my_dds_app

When enabled, the transport checks file mtime periodically and reloads the JSON without process restart.

JSON Schema

Top-level fields are supported directly, or under a discovery object.

{
  "discovery": {
    "allow_multicast": true,
    "include_loopback": false,
    "strict_validation": false,
    "default_peer_port": 7410,
    "interfaces": {
      "allow": ["eth*", "en*"],
      "deny": ["docker*", "veth*"],
      "addresses": ["192.168.1.20"]
    },
    "peers": [
      "192.168.1.21",
      "seed-dds.local:7412",
      "192.168.1.22:7412",
      "udp4://192.168.1.23:7416",
      { "address": "192.168.1.24", "port": 7420 },
      { "address": "192.168.1.25", "participant_id": 7 }
    ],
    "initial_peers": [
      "10.10.0.10:7412"
    ]
  },
  "domains": {
    "7": {
      "discovery": {
        "allow_multicast": false,
        "strict_validation": true,
        "initial_peers": ["domain7-seed.local:7412"]
      }
    }
  }
}

Field Semantics

allow_multicast:
true: send SPDP via multicast and explicit peers
false: skip multicast SPDP, use explicit peers only
include_loopback:
include 127.0.0.1 as a candidate selected interface
strict_validation:
true: reject invalid config entries and fail startup if interface filters match no interfaces or hostname peers cannot be resolved
false: best-effort parsing with graceful fallback
interfaces.allow:
glob patterns for interface names, for example eth*
interfaces.deny:
glob patterns to exclude interfaces
interfaces.addresses:
exact IPv4 addresses to keep
peers / initial_peers:
string form: A.B.C.D, host.name, A.B.C.D:PORT, host.name:PORT, udp4://A.B.C.D:PORT
object form: { "address": "A.B.C.D", "port": 7412 }
object form with hostname: { "address": "seed-dds.local", "port": 7412 }
object form with participant id: { "address": "A.B.C.D", "participant_id": 7 }
domains:
map keyed by domain id string ("0", "7", ...)
each value is a full discovery profile used only for that domain

When only participant_id is given, port is derived at runtime using the RTPS unicast discovery formula for the current domain.

Programmatic Usage

#include <astutedds/rtps/discovery_config.hpp>
#include <astutedds/rtps/udp_transport.hpp>

astutedds::rtps::RtpsUdpTransport transport(0, 0);

astutedds::rtps::DiscoveryConfig cfg;
cfg.allow_multicast = false;
cfg.peers.push_back({{192, 168, 1, 50}, 7412});

transport.set_discovery_config(cfg);
transport.init();

Runtime Diagnostics

Query the effective runtime discovery configuration:

auto info = transport.get_discovery_runtime_info();

std::cout << "config_loaded=" << info.config_loaded
      << " allow_multicast=" << info.allow_multicast
      << " strict_validation=" << info.strict_validation
      << " selected_if="
      << int(info.selected_interface[0]) << "."
      << int(info.selected_interface[1]) << "."
      << int(info.selected_interface[2]) << "."
      << int(info.selected_interface[3])
      << "\n";

for (const auto& peer : info.peers)
  std::cout << "peer=" << peer << "\n";

Developer package installation and first IDL application setup are documented in guides/developer-packages.md.

CLI Helper Tool

# One-shot dump
ASTUTEDDS_DISCOVERY_JSON=/path/to/peer_only_discovery.json \
  astutedds-discovery-dump --domain 0 --participant 0

# Live mode with config hot-reload
ASTUTEDDS_DISCOVERY_JSON=/path/to/hybrid_discovery.json \
ASTUTEDDS_DISCOVERY_JSON_WATCH=1 \
  astutedds-discovery-dump --watch --interval-ms 1000

Ready-to-Use Example Configs

The repository includes practical JSON configs under examples/discovery/:

peer_only_discovery.json
Multicast disabled
Explicit seed peers only (good for routed or multicast-blocked networks)
multicast_discovery.json
Multicast-enabled LAN discovery
No explicit peers
hybrid_discovery.json
Multicast enabled plus seed peers
Useful for mixed networks and faster bootstrap
localhost_discovery.json
Loopback-only discovery on one machine
Helpful for local development and demos
ci_deterministic_discovery.json
Peer-only deterministic bootstrap for CI jobs
Uses fixed interface/address/peer entries

Run with any example or application:

export ASTUTEDDS_DISCOVERY_JSON=examples/discovery/peer_only_discovery.json
./build/examples/circle_publisher

export ASTUTEDDS_DISCOVERY_JSON=examples/discovery/multicast_discovery.json
./build/examples/circle_subscriber

export ASTUTEDDS_DISCOVERY_JSON=examples/discovery/localhost_discovery.json
./build/examples/circle_publisher

export ASTUTEDDS_DISCOVERY_JSON=examples/discovery/ci_deterministic_discovery.json
./build/examples/circle_subscriber

For CI profile values, replace the example 198.51.100.x addresses with your actual runner network addresses.