services.xml - http

This is the reference for the http subelement of container in services.xml. The http block is used to configure http servers and filters - when this element is present, the default http server is disabled.

http
  server [id, port]
  filtering
    access-control
      exclude
        binding
    filter [id, class, bundle, provides, before, after]
      provides
      before
      after
      filter-config
    request-/response-chain [id, inherits, excludes]
      binding
      filter [id, class, bundle, provides, before, after]
        provides
        before
        after
        filter-config
      inherits
        chain
        exclude
      phase [id, before, after]
        before
        after
Most elements takes optional config elements, see example in server.

Note: To bind the search handler port (i.e. queries), refer to search bindings.

Example:

<http>
  <server id="server1" port="8080" />
  <server id="server2" port="9000" />

  <filtering>
    <filter id="request-filter1" class="com.yahoo.test.RequestFilter1" />
    <filter id="response-filter1" class="com.yahoo.test.ResponseFilter1" />

    <request-chain id="test-request-chain">
      <binding>http://*/*</binding>
      <filter id="request-filter1"/>
      <filter id="request-filter2" class="com.yahoo.test.RequestFilter2" />
    </request-chain>

    <response-chain id="test-response-chain">
      <binding>http://*:8080/*</binding>
      <binding>http://*:9000/path</binding>
      <filter id="response-filter1"/>
      <filter id="response-filter2" class="com.yahoo.test.ResponseFilter2" />
    </response-chain>
  </filtering>
</http>

server

The definition of a http server. Configure the server using jdisc.http.connector.def. Attributes:

NameRequiredValueDefaultDescription
id required string The component ID
port required number Server port
Example:
<server id="server1" port="8080">
  <config name="jdisc.http.connector">
    <idleTimeout>90</idleTimeout>
  </config>
</server>

filtering

filtering is for configuring http filter chains. Sub-elements:

Example:
<filtering>
  <filter id="request-filter1" class="com.yahoo.test.RequestFilter1" />
  <filter id="response-filter1" class="com.yahoo.test.ResponseFilter1" />

  <request-chain id="test-request-chain">
    <binding>http://*/</binding>
    <filter id="request-filter1"/>
    <filter id="request-filter2" class="com.yahoo.test.RequestFilter2" />
  </request-chain>

  <response-chain id="test-response-chain">
    <binding>http://*/</binding>
    <filter id="response-filter1"/>
    <filter id="response-filter2" class="com.yahoo.test.ResponseFilter2" />
  </response-chain>
</filtering>

access-control

Enable access control for all HTTP APIs, both including internal APIs of Vespa and application specific request handlers, servlets and rest-apis. Certain APIs that provide non-sensitive status information are whitelisted from this rule. The element configures a request filter chain with an access control filter, given such filter is available. The filter will contain the bindings for all handlers, except those implicitly whitelisted by Vespa and those listed in the exclude element. Notes on the semantics:

  • You cannot set up chains with same or more specific bindings than the access control chain's bindings. Any such chain will disable the access control chain for that binding.
  • If you want to combine the access control filter with other filters, the access control filter must be manually configured using the generic request-chain element.
  • If a handler has multiple bindings, it's sufficient to exclude one of them to exclude all bindings for that handler. For a given handler, you cannot exclude one binding while retaining access control on the other bindings.
Attributes:
NameRequiredValueDefaultDescription
domain required string Name of the application's access control domain
read optional true/false false If true, enables access control on all HTTP read requests (e.g GET, OPTIONS)
write optional true/false true If true, enables access control on all HTTP write requests (e.g POST, PUT, DELETE)
Sub-elements: Example:
<access-control domain="user.john.mydomain" read="true" write="true" />

exclude

A set of bindings that should be whitelisted from access control. Sub-elements:

Example: A container cluster has one handler, one servlet and one rest-api:

<handler id="com.yahoo.handler.MyHandler">
  <binding>http://*/myhandler</binding>
</handler>
<servlet id="my-servlet" class="com.mydomain.MyServlet">
  <path>servlet-path</path>
</servlet>
<rest-api path="rest-api-path">
To whitelist these endpoints from access-control, add bindings:
<access-control domain="user.john.mydomain" read="true" write="true">
  <exclude>
    <binding>http://*/myhandler</binding>        <!-- Exclude handler -->
    <binding>http://*/servlet-path</binding>     <!-- Exclude servlet -->
    <binding>http://*/rest-api-path/*</binding>  <!-- Exclude rest-api, note the /* suffix! -->
  </exclude>
<access-control>

binding

Specifies that requests/responses matching the given URI pattern should be sent through the request-chain/response-chain. Also used to make excludes in access-control.

filter

The definition of a single filter, for referencing when defining chains. If a single filter is to be used in several different chains, it is in general cleaner to define it directly under http and then refer to it with id, than defining it inline separately for each chain. The following filter types are supported:

  • RequestFilter
  • ResponseFilter
  • SecurityRequestFilter
  • SecurityResponseFilter
Security[Request/Response]Filters are automatically wrapped in Security[Request/Response]FilterChains. This makes them behave like regular Request/Response filters with respect to chaining.

Attributes:

NameRequiredValueDefaultDescription
id required string The component ID
class optional string id The class of the component, defaults to id
bundle optional string id or class The bundle to load the component from, defaults to class or id (if no class is given)
before optional string Space separated list of phases and/or filters which should succeed this phase
class optional string id Space separated list of phases and/or filters which should precede this phase
Sub-elements: Example:
<filter id="filter2" class="com.yahoo.test.Filter2"/>

provides

A name provided by a filter for phases and other filters to use as dependencies. Contained in filter and filter (in chain).

before

The name of a phase or filter which should succeed this phase or filter. Several before tags may be used if it is necessary to define several filters or phases which always should succeed this filter or phase in a chain. In other words, the phase or filter defined is placed before name in the tag. Contained in filter, filter (in chain) and phase.

after

The name of a phase or filter which should precede this phase or filter. Several after tags may be used if it is necessary to define several filters or phases which always should precede this filter or phase in a chain. In other words, the phase or filter defined is placed after the name in the tag. Contained in filter, filter (in chain) and phase. Example:

<filter id="filterauth" class="com.yahoo.test.auth">
  <provides>Authorization</provides>
  <before>LastFilters</before>
  <after>Earlyfilters</after>
</filter>

filter-config

Only used to configure filters that are configured with com.yahoo.jdisc.http.filter.security.FilterConfig. This is the case for all filters provided in JDisc bundles.

request-chain/response-chain

Defines a chain of request filters or response filters respectively. A chain is a set ordered by dependencies. Dependencies are expressed through phases, which may depend upon other phases, or filters. Attributes:

NameRequiredValueDefaultDescription
inherits string A space separated list of chains this chain should include the contents of
excludes string A space separated list of filters (contained in an inherited chain) this chain should not include
Sub-elements:
  • binding
  • filter. Refer to or define a filter. config or filter-config can not be added to references, only filter definitions.
  • inherits
  • phase
Examples:
<request-chain id="default-request-filters">
  <binding>http://*/*</binding>
  <filter id="com.yahoo.test.RequestFilter"/>
</request-chain>
<response-chain id="response-filters">
  <binding>http://*:8080/*</binding>
  <binding>http://*:9000/path</binding>
  <filter id="com.yahoo.test.ResponseFilter"/>
</response-chain>

inherits

Wrapper element for information about which chains, if any, a chain should inherit, and how. Contained in request-chain and response-chain. Sub-elements:

(inherited) chain

The ID of a chain which this chain should inherit, i.e. include all filters and phases from. Use several chain tags if it is necessary to combine the filters from several chains. Contained in inherits.

exclude

A filter the chain under definition should exclude from the chain or chains it inherits from. Use several exclude tags to exclude several filters. Contained in inherits. Example:

<request-chain id="demo">
  <inherits>
    <chain>idOfSomeInheritedChain</chain>
    <exclude>idOfUnwantedFilter</exclude>
    <exclude>idOfYetAnotherUnwantedFilter</exclude>
  </inherits>
  <filter id="filter2" class="com.yahoo.test.Filter2"/>
</request-chain>

phase

Defines a phase, which is a checkpoint to help order filters. Filters and other phases may depend on a phase to be able to make assumptions about the order of filters. Contained in chain. Attributes:

NameRequiredValueDefaultDescription
id required string The ID, or name, which other phases and filters may depend upon as a successor or predecessor
before optional string Space separated list of phases and/or filters which should succeed this phase
after optional string Space separated list of phases and/or filters which should precede this phase
Sub-elements: Example:
<request-chain id="demo">
  <phase id="CheckpointName">
    <before>Authorization</before>
  </phase>
  <filter id="filter2" class="com.yahoo.test.Filter2"/>
</request-chain>