services.xml

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

services [version]
  admin [version]
  content [version]
  container [version]
  routing [version]
  service [command] [version]
  clients [version]
Note: the container element is equivalent to jdisc - use container, as jdisc will be discontinued.

Some attributes are common to most of services sub-elements:
  • jvmargs: Pass arguments to the JVM for the given service
  • preload: Preload shared libraries for the given service. Vespa-internal use only
  • baseport: All services in a Vespa systems have a default baseport - to change it, use baseport. The most common port to change is the http port of jdisc container instances
  • hostalias: All nodes/hosts referred to in services.xml must be defined in hosts.xml

services

Attributes:

  • version (required): 1.0
  • major-version (optional): An integer: The Vespa major version this application package is valid for. Do not specify except to work around problems with a new major version.
Optional subelements (one or more of jdisc, content or service is required): Example:
<?xml version="1.0" encoding="utf-8" ?>
<services version="1.0">
  <container version="1.0" id="container">
    <search />
    <nodes>
      <node hostalias="node0"/>
    </nodes>
  </container>
  <content id="music" version="1.0">
    <redundancy>2</redundancy>
    <nodes>
      <node hostalias="node0"/>
    </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

clients holds feeding-relevant configuration. Attributes:

  • version (required): 2.0
Optional subelements: Example:
<clients version="2.0">
  <load-types>
    <type name="update" default-priority="NORMAL_2"/>
  </load-types>
</clients>

load-types

load-types is a container for different classes (types) of load. Use this is prioritize Document API load, like de-prioritize backup reads or reprocessing jobs. Optional subelements:

type

Configure priority for a load-type. Attributes:

  • name (required): The name for the load type.
  • default-priority (required): Default priority for the load-type - use priorities below.
Priorities are byte values from 0 to 255, where 0 is the highest priority. 16 priority values are mapped to names. Do not use HIGH_3 or higher, as this will interfere with internal Vespa operations.
  • HIGHEST
  • VERY_HIGH
  • HIGH_1
  • HIGH_2
  • HIGH_3
  • NORMAL_1
  • NORMAL_2
  • NORMAL_3
  • NORMAL_4
  • NORMAL_5
  • NORMAL_6
  • LOW_1
  • LOW_2
  • LOW_3
  • VERY_LOW
  • LOWEST
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.