This version of the docs is a work in progress. If you don’t see what you are looking for check the legacy wiki.

The Repose system-model.cfg.xml is the main configuration file for Repose. It outlines the entire deployment layout for the service cluster. Repose must be aware of this in order to configure itself and correctly coordinate routing if necessary. Additionally, the system model lets Repose know where the other Repose nodes reside. Using this information, Repose can coordinate its own clustering to help load balance or share data among nodes that share common filters.

Model Definitions

Cluster (Service or Repose)

An entity that defines a collection of nodes, all of which provide equivalent functionality. This element also defines service’s scope within the system model. The service hosted on each node must be functionally equivalent at the API level. A filter chain may be attached to a Repose cluster to identify the Repose HTTP message interception logic that must be performed by each node within the cluster.


An endpoint is a special type of destination. An endpoint destination can specify an exact node to which requests can be routed. This element can contain protocol, hostname, root-path, and port elements that are used in constructing a route. If the endpoint is within the same container as Repose, protocol, hostname and port are not specified.


A Repose cluster must enumerate eligible routes to which HTTP messages can be forwarded. These are listed in the destinations section of the repose-cluster. If a destination is requested that is not listed in this section, a "service not available" code is returned. A valid destination can either be an endpoint or a target cluster. All nodes within the target cluster of a destination are considered eligible for routing, and by default, Repose forwards to each node in round-robin order, starting at the top of the node sequence.


An HTTP message interceptor that provides a specific piece of business functionality. A filter contains a Repose specific named reference.

Filters (Filter Chain)

A sequence of filters that will intercept and process the request and/ord response. The request will be processed in order starting from the topmost filter in the sequence down to the bottom. The response will be processed in order starting from the bottommost filter in the sequence up to the top.

Node (Cluster Node)

A named reference that may be used to locate a network endpoint. The hostname may be the human readable, string representation of an IPv4 or IPv6 address or a named reference that an IPv4 or IPv6 address.


A service is any served REST API bound to a TCP/IP address and port. A service is considered served and available so long as it is addressable and accessible to a separate processes (local or remote).


A sequence of services that will be loaded into the servlet context to be available for filters in the cluster.

Target Cluster

A target cluster is a type of destination that specifies another cluster (Repose or service) as a routing destination. The target cluster element can contain cluster, protocol, root-path attributes. Repose will choose a node from the target cluster as the target of the dispatch in a round-robin manner.


This section is only meant to explain certain quirks of the system model, and to provide a link to the comprehensive configuration schema. Other aspects of configuration will be explained through examples. See: Repose Deployment Scenarios

Since port numbers below 1024 are privileged, Repose typically can not connect directly to them. There are several ways to go about getting around this, but one of the most generally accepted ways is to execute the following commands with root privilege (e.g., sudo):

/sbin/iptables -t nat -I PREROUTING -p tcp --dport  80 -j REDIRECT --to-port 8080
/sbin/iptables -t nat -I PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 8443

Repose Deployment Scenarios

Simple Pass-Through Proxy

<system-model xmlns="">
  <repose-cluster id="repose_cluster1"> (1)
      <node id="repose_node1" (2)
            hostname="localhost" (3)
            http-port="8080"/> (4)

    <filters/> (5)

    <services/> (6)

      <endpoint id="open_repose" (7)
                protocol="http" (8)
                hostname="" (9)
                root-path="/" (10)
                port="80" (11)
                default="true"/> (12)
1 Defines a new Repose cluster with an ID that must be unique across all defined clusters.
2 Defines a new Repose node with an ID that must be unique across all defined nodes in the list.
3 Defines the hostname of the Repose node. If set to localhost, any physical node will match and run the Repose node.
4 Defines the port for the node to listen on.
5 Defines a sequence of filters to run. In this case, no filters are being used.
6 Defines a set of services to run. In this case, no services are being used.
7 Defines a new endpoint with an ID that must be unique across all defined endpoints in the destinations list. There must be exactly one default destination endpoint.
8 Defines the endpoint’s protocol. If the protocol is not specified, then internal dispatch is assumed.
9 Defines the endpoint’s host name. If not specified, localhost is assumed.
10 Defines the endpoint’s base path. This will be used in building the URI/path for connecting to the service. Any additional URI info will be appended to this.
11 Defines the endpoint’s port. If not specified (or 0), internal dispatch is assumed.
12 Specifies whether or not this is the default destination endpoint. The default destination endpoint will be responsible for handling all traffic that is not explicitly routed to a different destination endpoint. Remember that a target can be specified rather than an endpoint if you want to use round-robin routing to a service cluster.

Filter Activation Determination

<system-model xmlns="">
  <repose-cluster id="repose_cluster1"> (1)
      <node id="repose_node", hostname="localhost", http-port="8080"/> (2)

    <filters> (3)
      <filter name="ip-user"> (4)
          <and> (5)
            <methods value="GET HEAD POST PUT"/> (6)
            <or> (7)
              <header name="foo"/> (8)
              <header name="bar" value="BaZ"/> (9)
            <not> (10)
              <uri regex="^/v1/[^/]+/[^/]+/public/?"/> (11)

    <services/> (12)

      <endpoint id="origin_service", protocol="http", port="80", default="true"/> (13)
1 Defines a new Repose cluster with an ID that must be unique across all defined clusters.
2 Defines a new Repose node.
3 Defines a sequence of filters to run.
4 Defines the IP User Filter should be used by the nodes in this cluster.
5 Defines a boolean AND operator where all direct sub-elements must evaluate to true.
6 Defines the space separated list of case sensitive methods to check the current request against.
7 Defines a boolean OR operator where at least one direct sub-element must evaluate to true.
8 Defines that a header named foo (case insensitive) must be defined.
9 Defines that a header named bar (case insensitive) must be defined and have a value of BaZ (case sensitive).
10 Defines a boolean NOT operator that negates the result of the single direct sub-element’s evaluation.
11 Defines the Java regular expression the URI must match. This particular one requires that it has exactly four total path segments, the first path segment must be v1, the fourth path segment is public, and the trailing slash is optional.
Example: /v1/two/three/public
12 Defines a set of services to run. In this case, no services are being used.
13 Defines the required one default endpoint.

Nova-API Localhost Deployment


Root WAR (Local Servlet Application-Container Routing) Deployment


Complex Cluster Layout With Cluster Routing


Health Check Passthrough