Skip to main content
Mole configuring routing

Routing Configuration

Control how routes propagate through your mesh. These settings affect route advertisement timing, expiration, and path depth limits.

Default settings work for most deployments:

routing:
  advertise_interval: 2m
  route_ttl: 5m
  max_hops: 16

Configuration​

routing:
  advertise_interval: 2m   # How often to re-advertise routes
  node_info_interval: 2m   # How often to advertise node info
  route_ttl: 5m            # How long routes are valid
  max_hops: 16             # Maximum path length

Options​

OptionTypeDefaultDescription
advertise_intervalduration2mRoute advertisement frequency
node_info_intervalduration2mNode info advertisement frequency
route_ttlduration5mTime until routes expire
max_hopsint16Maximum route path length

Route Advertisement​

Routes are periodically re-advertised to keep them alive:

routing:
  advertise_interval: 2m  # Re-advertise every 2 minutes

Trigger Immediate Advertisement​

After configuration changes, trigger immediate advertisement:

curl -X POST http://localhost:8080/routes/advertise

Trade-offs​

IntervalBandwidthResponsiveness
30sHigherFast failover
2mModerateGood balance
5mLowerSlower failover

Route TTL​

Routes expire if not refreshed:

routing:
  route_ttl: 5m  # Routes expire after 5 minutes

Relationship with Advertisement​

TTL should be at least 2x the advertisement interval:

AdvertisementRecommended TTLWhy
30s90sAllow 2 missed advertisements
2m5mDefault - good balance
5m12mSlower networks

If TTL < 2x advertisement interval, routes may flap during normal operation.

Node Info Advertisement​

Node info (display name, roles, system info) is advertised separately:

routing:
  node_info_interval: 2m  # Update node info every 2 minutes

This controls how often the dashboard sees updated information about agents.

Maximum Hops​

Limit route propagation depth:

routing:
  max_hops: 16  # Routes stop propagating after 16 hops

What max_hops Affects​

  • Route advertisements: Routes with metric >= max_hops are not forwarded
  • NOT stream paths: Stream open timeout (30s default) limits actual path length
TopologySuggested max_hops
Simple chain (2-3 agents)4
Small mesh (5-10 agents)8
Large mesh (10+ agents)16
Complex topology16 (default)

Setting max_hops too low may prevent routes from reaching all agents. Setting it too high has minimal cost.

Connection Tuning​

Related settings in the connections section affect peer behavior:

connections:
  idle_threshold: 5m       # Keepalive after idle time
  timeout: 90s             # Peer dead after no response
  keepalive_jitter: 0.2    # Timing jitter (OPSEC)

  reconnect:
    initial_delay: 1s      # First reconnect attempt
    max_delay: 60s         # Maximum backoff
    multiplier: 2.0        # Backoff multiplier
    jitter: 0.2            # Reconnect timing jitter
    max_retries: 0         # 0 = infinite retries

Keepalive Settings​

OptionTypeDefaultDescription
idle_thresholdduration5mSend keepalive after idle
timeoutduration90sDeclare peer dead
keepalive_jitterfloat0.2Timing randomization

Reconnection Settings​

OptionTypeDefaultDescription
initial_delayduration1sFirst retry delay
max_delayduration60sMaximum retry delay
multiplierfloat2.0Exponential backoff factor
jitterfloat0.2Retry timing randomization
max_retriesint0Maximum attempts (0 = infinite)

Tuning Guide​

Fast Failover​

For environments requiring quick recovery:

routing:
  advertise_interval: 30s
  route_ttl: 90s

connections:
  idle_threshold: 15s
  timeout: 45s

Bandwidth Conscious​

For low-bandwidth or metered connections:

routing:
  advertise_interval: 5m
  route_ttl: 12m
  node_info_interval: 5m

connections:
  idle_threshold: 2m
  timeout: 5m

High Latency Networks​

For satellite or high-latency links:

routing:
  advertise_interval: 3m
  route_ttl: 8m

connections:
  idle_threshold: 1m
  timeout: 3m

Examples​

Default (Most Deployments)​

routing:
  advertise_interval: 2m
  node_info_interval: 2m
  route_ttl: 5m
  max_hops: 16

Fast Convergence​

routing:
  advertise_interval: 30s
  node_info_interval: 30s
  route_ttl: 90s
  max_hops: 16

Large Mesh​

routing:
  advertise_interval: 3m
  node_info_interval: 3m
  route_ttl: 8m
  max_hops: 32

Environment Variables​

routing:
  advertise_interval: "${ROUTE_ADVERTISE_INTERVAL:-2m}"
  route_ttl: "${ROUTE_TTL:-5m}"
  max_hops: ${ROUTE_MAX_HOPS:-16}