Skip to main content

Environment Variables

HDDS can be configured via environment variables. All variables are prefixed with HDDS_.

Discovery & Networking​

VariablePurposeExample
HDDS_SPDP_UNICAST_PEERSManual unicast peer list192.168.1.100:7400,192.168.1.101:7400
HDDS_LOG_UDPEnable UDP debug logging1
HDDS_INTEROP_DIAGNOSTICSEnable interop diagnostics1
HDDS_FORCE_DATA_MCRoute DATA to multicast1
HDDS_DISABLE_TYPE_OBJECTDisable TypeObject announcement1

Network Interface Control​

VariablePurposeFormat
HDDS_MULTICAST_IFForce multicast interfaceIPv4 address (e.g., 192.168.1.5)
HDDS_UNICAST_IFForce unicast interfaceIPv4 address
HDDS_INTERFACE_ALLOWAllow specific interfacesCIDR list: eth0,192.168.1.0/24

TTL (Time-To-Live) Configuration​

VariablePurposeRange
HDDS_TTLSet both multicast & unicast TTL1-255
HDDS_MULTICAST_TTLMulticast TTL only1-255
HDDS_UNICAST_TTLUnicast TTL only1-255

Source Filtering​

VariablePurposeFormat
HDDS_SOURCE_ALLOWAllowed source CIDRs192.168.1.0/24,10.0.0.0/8
HDDS_SOURCE_DENYDenied source CIDRs192.168.0.0/16

QoS & Traffic Control​

VariablePurposeFormat
HDDS_DSCPDSCP code points18,46,26 (AF21, EF, AF31)

Observability​

VariablePurposeValues
HDDS_EXPORTER_DISABLEDisable telemetry export1, true, or yes

Participant Configuration​

VariablePurposeExample
HDDS_PARTICIPANT_IDOverride auto-generated participant ID42
HDDS_MULTICAST_ADDRESSCustom multicast address239.255.0.100
HDDS_DISCOVERY_PEERSStatic discovery peer list192.168.1.100:7400,192.168.1.101:7400
HDDS_INITIAL_PEERSInitial peers (alias for DISCOVERY_PEERS)192.168.1.100:7400
HDDS_DISCOVERY_PORTCustom discovery port7400
HDDS_CONFIG_FILEPath to HDDS configuration file/etc/hdds/config.xml

Transport Control​

VariablePurposeValues
HDDS_MULTICAST_DISABLEDisable multicast discovery1, true
HDDS_SHM_DISABLEDisable shared memory transport1, true
HDDS_REUSEPORTEnable SO_REUSEPORT on UDP sockets1

HDDS_REUSEPORT​

Enables SO_REUSEPORT on all UDP sockets (multicast port 7400, metatraffic unicast 7410, user unicast). This allows multiple HDDS processes on the same machine to share the same ports.

# Process 1
HDDS_REUSEPORT=1 python daemon.py

# Process 2
HDDS_REUSEPORT=1 python agent.py
warning

Both processes must have HDDS_REUSEPORT=1 for correct behavior. If only one process sets it, the kernel may route packets unpredictably.

RTI Connext Interop

HDDS_REUSEPORT=1 breaks interoperability with RTI Connext DDS. Only use this for HDDS-to-HDDS inter-process communication on the same machine.

Kubernetes Discovery​

VariableDefaultPurpose
HDDS_K8S_SERVICEhdds-discoveryKubernetes headless service name
HDDS_K8S_NAMESPACEdefaultKubernetes namespace
HDDS_K8S_PORT7411DDS port for discovered peers
HDDS_K8S_POLL_INTERVAL_MS5000DNS poll interval (milliseconds)
HDDS_POD_IP-Pod IP (from Kubernetes downward API)
HDDS_POD_NAME-Pod name (from Kubernetes downward API)

Kubernetes Deployment Example​

env:
- name: HDDS_K8S_SERVICE
  value: hdds-discovery
- name: HDDS_K8S_NAMESPACE
  value: production
- name: HDDS_POD_IP
  valueFrom:
    fieldRef:
      fieldPath: status.podIP

See Kubernetes Discovery Guide for complete setup instructions.

Cloud Discovery (Experimental)​

warning

Cloud Discovery is an experimental feature. See Cloud Discovery Guide.

AWS Cloud Map​

VariablePurposeExample
HDDS_CLOUD_MAP_NAMESPACECloud Map namespace namehdds-namespace
HDDS_CLOUD_MAP_SERVICECloud Map service namehdds-participants
AWS_REGIONAWS regionus-east-1

Azure Discovery​

VariablePurposeExample
HDDS_AZURE_DNS_ZONEDNS Private Zone namehdds.private.azure.local
HDDS_AZURE_TABLE_STORAGETable Storage connection stringDefaultEndpointsProtocol=...

Consul Discovery​

VariablePurposeExample
HDDS_CONSUL_ADDRConsul HTTP API addresshttp://localhost:8500
HDDS_CONSUL_DATACENTERConsul datacenter namedc1

Security​

HDDS Security Variables​

VariablePurposeExample
HDDS_SECURITY_ENABLEEnable DDS Security1, true
HDDS_SECURITY_IDENTITY_CERTPath to participant X.509 certificate/etc/hdds/cert.pem
HDDS_SECURITY_IDENTITY_KEYPath to participant private key/etc/hdds/key.pem
HDDS_SECURITY_CA_CERTPath to CA certificate(s)/etc/hdds/ca.pem
HDDS_SECURITY_PERMISSIONSPath to permissions file/etc/hdds/permissions.xml
HDDS_SECURITY_GOVERNANCEPath to governance rules/etc/hdds/governance.xml
HDDS_AUDIT_LOG_PATHPath to security audit log/var/log/hdds/audit.log
HDDS_REQUIRE_AUTHRequire all participants to authenticate1, true

Legacy Security Variables (Deprecated)​

VariableReplacement
HDDS_IDENTITY_CERTHDDS_SECURITY_IDENTITY_CERT
HDDS_PRIVATE_KEYHDDS_SECURITY_IDENTITY_KEY
HDDS_CA_CERTSHDDS_SECURITY_CA_CERT
HDDS_PERMISSIONS_XMLHDDS_SECURITY_PERMISSIONS
HDDS_GOVERNANCE_XMLHDDS_SECURITY_GOVERNANCE

ROS 2 Security Compatibility​

VariablePurposeExample
ROS_SECURITY_ENABLEEnable security (ROS 2 compatible)true
ROS_SECURITY_ENCLAVESecurity enclave path/my_robot/my_node
ROS_SECURITY_STRATEGYSecurity strategyEnforce, Permissive
ROS_SECURITY_KEYSTOREPath to security keystore/etc/ros/security

Security Example​

# Enable full DDS Security (new style)
export HDDS_SECURITY_ENABLE=true
export HDDS_SECURITY_IDENTITY_CERT=/etc/hdds/certs/participant.pem
export HDDS_SECURITY_IDENTITY_KEY=/etc/hdds/certs/participant_key.pem
export HDDS_SECURITY_CA_CERT=/etc/hdds/certs/ca.pem
export HDDS_SECURITY_PERMISSIONS=/etc/hdds/security/permissions.xml
export HDDS_SECURITY_GOVERNANCE=/etc/hdds/security/governance.xml
export HDDS_AUDIT_LOG_PATH=/var/log/hdds/audit.log
./my_dds_app
# ROS 2 compatible security configuration
export ROS_SECURITY_ENABLE=true
export ROS_SECURITY_STRATEGY=Enforce
export ROS_SECURITY_ENCLAVE=/my_robot/sensor_node
export ROS_SECURITY_KEYSTORE=/etc/ros/security
./my_ros2_node

Logging​

Standard Rust logging via RUST_LOG:

# Enable debug logging for HDDS
RUST_LOG=hdds=debug ./my_app

# Trace-level for discovery
RUST_LOG=hdds::discovery=trace ./my_app

# Multiple filters
RUST_LOG=hdds=debug,hdds::transport=trace ./my_app

Examples​

Static Peer Discovery​

# Disable multicast, use unicast peers only
export HDDS_SPDP_UNICAST_PEERS="10.0.0.1:7400,10.0.0.2:7400"
./my_dds_app

Network Interface Selection​

# Force specific network interface
export HDDS_MULTICAST_IF="192.168.1.100"
export HDDS_UNICAST_IF="192.168.1.100"
./my_dds_app

TTL for Multi-Hop Networks​

# Increase TTL for WAN scenarios
export HDDS_TTL=32
./my_dds_app

Debug Interoperability​

# Enable verbose interop logging
export HDDS_INTEROP_DIAGNOSTICS=1
export RUST_LOG=hdds=debug
./my_dds_app

Firewall-Friendly Setup​

# Disable multicast, use unicast only
export HDDS_SPDP_UNICAST_PEERS="peer1.example.com:7400"
export HDDS_FORCE_DATA_MC=0
./my_dds_app