• [+] expand all

Node and Network setup

Vespa is composed of services that communicate and interact with each other. These services can be partitioned onto any amount of actual hardware for scaling, or they can all coexist on a single environment for development. To achieve this flexibility, some requirements must be met for the environment where the services will run.


A node in this context is the environment where some Vespa services are running. This can be an actual machine like a server in a datacenter, or a laptop for development and testing of Vespa configuration. It can also be a Virtual Machine or a Docker container, so one can run multiple nodes on a single piece of hardware.

The different Vespa services that run on nodes will mostly communicate with each other via the network. This means that all nodes must have an IP address and have network connectivity to all other nodes. Both IPv4 and IPv6 protocols are supported. Note that the same framework is used even when running the entire Vespa stack on a single node.


In order to find the IP address of a node and connect to it, the node must have a hostname that identifies it and which maps to its IP address. Actual machines on a network will usually have a Fully Qualified Domain Name (FQDN) in DNS which should be used as the host name for this purpose.

Note that it is a requirement that the host name (configured in hosts.xml) can be used to look up the IP address of the node. The configuration server use this host name to construct URLs that will be used to open network connections to Vespa services running on that node. If the nodes use IP addresses which don't have DNS names, one must have all those IP addresses with corresponding host names in /etc/hosts on all nodes in the Vespa installation. We recommend using names that can be used as FQDNs also in this case, in case of moving to using a DNS server instead of publishing the /etc/hosts file.

Identifying the node for configuration

When Vespa services are started on a node, the node must identify itself to the configuration system to get the correct configuration (including which services to run). This requires a unique identifier for the node in the config server. Since it is already a requirement that the node has a hostname that the config server knows, Vespa uses the same hostname when a node identifies itself to get its configuration.

This means that the node must know its own hostname (FQDN), and be in agreement with the config server about what exactly the host name is.

Finding the hostname

As discussed above, a Vespa node needs to know its own host name when it starts. Usually this is achieved by just running the hostname command. If hostname is set to the FQDN of the node, then everything should Just Work.

But sometimes this doesn't work properly, either because that name can't be used to find an IP address which works for connecting to services running on the node, or it's just that the name doesn't agree with what the config server thinks the node's host name is. In this case, override by setting the VESPA_HOSTNAME environment variable, then that will be used instead of running the hostname command.

Note that VESPA_HOSTNAME will be used both when a node identifies itself to the config server and when a service on that node registers a network connection point that other services can connect to.

An error message with "hostname detection failed" is emitted if the VESPA_HOSTNAME isn't set and the hostname isn't usable. If VESPA_HOSTNAME is set to something that cannot work, an error with "hostname validation failed" is emitted instead.

Simple single-node development environment

When testing a Vespa configuration on a single-node setup, one can usually avoid the setup hassle by overriding the hostname with the value "localhost". Try this command for that purpose:

$ echo "override VESPA_HOSTNAME localhost" >> $VESPA_HOME/conf/vespa/default-env.txt

Running Java unit tests won't pick up settings in default-env.txt and will default to "localhost" if VESPA_HOSTNAME isn't set in the environment.