Environment:Vespa engine Vespa FNET Transport Config

Knowledge Sources	Vespa Engine frtconnectionpool.cpp sourcespec.cpp
Domains	Infrastructure, Configuration
Last Updated	2026-02-09 00:00 GMT

Overview

FNET/FRT transport environment for config subscription RPC communication, with configurable server endpoints and LZ4 compression.

Description

This environment provides the network transport context for the Vespa config subscription system. Config clients communicate with config servers using FRT (Fast RPC Transport) over FNET. The connection pool manages pooled connections with round-robin source selection and exponential backoff on failures. Protocol defaults include LZ4 compression and version 3 of the config protocol. The default proxy port is 19090.

Usage

Use this environment for all config subscription operations. It is the mandatory prerequisite for the ConfigSubscriber_Subscribe, ConfigSubscriber_NextConfig, ConfigSubscriber_NextGeneration, FRTConnectionPool_Constructor, and ConfigSubscriber_Close implementations. Any Vespa process that subscribes to configuration requires FNET transport.

System Requirements

Category	Requirement	Notes
OS	Linux	FNET uses POSIX networking
Network	TCP connectivity to config servers	Default port 19090
Software	FNET library (libvespa_fnet)	Part of Vespa C++ build

Dependencies

System Packages

libvespa_fnet (Vespa FNET networking library)
libvespa_frt (Vespa FRT RPC library)
LZ4 compression library (for protocol compression)

Credentials

The following environment variables configure the transport:

VESPA_CONFIG_SOURCES: Comma-separated list of config servers (default: localhost)
VESPA_CONFIG_PROTOCOL_VERSION: Protocol version 1/2/3 (default: 3)
VESPA_CONFIG_PROTOCOL_TRACELEVEL: Debug trace level (default: 0)
VESPA_CONFIG_PROTOCOL_COMPRESSION: Compression type: LZ4 (default) or UNCOMPRESSED

Quick Install

# FNET transport is built as part of the Vespa C++ build
# Configure config sources for the client:
export VESPA_CONFIG_SOURCES="configserver1.example.com,configserver2.example.com"

Code Evidence

Default config source fallback from sourcespec.cpp:

ServerSpec::ServerSpec() {
    char* cfgSourcesPtr = getenv("VESPA_CONFIG_SOURCES");
    if (cfgSourcesPtr != nullptr) {
        initialize(std::string(cfgSourcesPtr));
    } else {
        initialize("localhost");  // Fallback to localhost
    }
}

const static int DEFAULT_PROXY_PORT = 19090;

Connection pool from frtconnectionpool.cpp:

FRTConnectionPool::FRTConnectionPool(FNET_Transport & transport,
                                     const ServerSpec & spec,
                                     const TimingValues & timingValues)
    : _supervisor(std::make_unique<FRT_Supervisor>(& transport)),
      _selectIdx(0),
      _hostname("")

Per-connection backoff from frtconnection.cpp:

constexpr uint32_t MAX_DELAY_MULTIPLIER = 6u;
constexpr vespalib::duration WARN_INTERVAL = 10s;

void FRTConnection::calculateSuspension(ErrorType type) {
    delay = std::min(MAX_DELAY_MULTIPLIER, ++_failures) * _delay;
    // Exponential backoff: 60s -> 120s -> ... capped at 360s
}

Common Errors

Error Message	Cause	Solution
`FRT Connection suspended`	Config server unreachable	Check `VESPA_CONFIG_SOURCES` and network connectivity
`No config sources specified`	VESPA_CONFIG_SOURCES not set and localhost unavailable	Set `VESPA_CONFIG_SOURCES` to config server addresses
Config subscription timeout	Server not responding within 55s default	Check config server health; adjust TimingValues if needed

Compatibility Notes

Default fallback: If VESPA_CONFIG_SOURCES is not set, falls back to localhost:19090.
LZ4 compression: Default protocol compression; can be set to UNCOMPRESSED for debugging.
Protocol version: Version 3 is default; versions 1 and 2 are legacy.
Round-robin: Connection pool uses round-robin selection among ready sources; falls back to suspended sources if all are failing.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment