services.xml

services.xml is the primary configuration file in an application package. Elements:

services [version]
  container [version]
  content [version]
  admin [version]
  routing [version]
  service [command] [version]
  clients [version]
Nodes/hosts referred to in services.xml must be defined in hosts.xml using hostalias.

services

Attributes:

  • version (required): 1.0
Optional subelements (one or more of container, content or service is required): Example:
<?xml version="1.0" encoding="utf-8" ?>
<services version="1.0">
  <container version="1.0" id="container">
    <search/>
    <document-api/>
    <nodes>
      <node hostalias="node0"/>
    </nodes>
  </container>
  <content id="music" version="1.0">
    <redundancy>2</redundancy>
    <nodes>
      <node hostalias="node0"/>
      <node hostalias="node1"/>
    </nodes>
    <documents>
      <document type="music"/>
    </documents>
  </content>
</services>

service

Service clusters can run any program - only the start command is needed. Vespa will start the service cluster, and keep processes alive (auto restarts). Attributes:

  • version (required): 1.0
  • command (required): command to start the service
Example:
<service name="myprogram" command=".../bin/myprogram" version="1.0">
  <node hostalias="mynode"/>
</service>
stdout from the service is written to vespa.log. The service name will be that defined in the cluster. Example using vespa-logfmt:
[2015-09-30 10:16:13.367] INFO    : myprogram    stdout     Started successfully
If more than one instance of the same service run on the same node, the names will be myprogram, myprogram2 etc.

clients

The clients-element is for configuring clients accessing Vespa using the Document API. version must be set to "2.0". The only supported child element is load-types, that has one or more types. Use the type to create user-defined load-types with a default priority.

  • name (required): User-defined load type name
  • default-priority (required): Default priority
Priorities are byte values from 0 to 255, where 0 is the highest priority. 16 priority values are mapped to names, see Priority enum in DocumentProtocol. Do not use HIGH_3 or higher, as this will interfere with internal Vespa operations. Example:
<clients version="2.0">
  <load-types>
    <type name="user_query"  default-priority="VERY_HIGH" />
    <type name="maintenance" default-priority="NORMAL_6" />
    <type name="third_party" default-priority="LOW_1" />
  </load-types>
</clients>

Generic configuration using <config>

Most elements in services.xml accept a sub-element named config. config elements can be included on different levels in the XML structure and the lower-level ones will override values in the higher-level ones (example below). The config element must include the attribute name, which gives the full name of the configuration option in question, including the namespace. The name can either refer to configuration definitions that are shipped with Vespa or ones that are part of the application package. For a complete example on generic configuration see the application package reference.

<container id="default" version="1.0">
  <handler id="com.yahoo.vespatest.ConfiguredHandler">
    <config name="vespatest.response">
      <response>configured string</response>
    </config>
  </handler>
  <nodes>
    <node hostalias="node0"/>
  </nodes>
</container>

Modular Configuration

Some features are configurable using XML files in sub-directories of the application package. This means that the configuration found in these XML files will be used as if it was inlined in services.xml. This is supported for search chains, docproc chains and routing tables.