Skip to end of metadata
Go to start of metadata

Default installation paths 

The directories below are set during the installation process. You can find these Repose directories by following the appropriate paths:

  • Repose ear files are installed in /usr/share/repose/filters
  • Repose valve jar is installed in /usr/share/repose

  • Repose logs are available in /var/log/repose/
  • Repose default config directory is /etc/repose 
  • Repose start up script is /etc/init.d/repose-valve

Configuration management

Configuration management helps save time, simplify deployments, and increase reliability. Check out our Configuration Management repositories:

Starting Repose

To start Repose via the service command (recommended):

sudo service repose-valve start

To stop Repose via the service command (recommended):

sudo service repose-valve stop


To start Repose via the startup script:

sudo /etc/init.d/repose-valve start

To stop Repose via the script:

sudo /etc/init.d/repose-valve stop


To start Repose with executable Repose valve jar, use action "start."

java -jar /usr/share/repose/repose-valve.jar

To stop Repose using command line:

kill -2 [repose-pid]

Testing Repose

Send a request to verify that Repose is running:

curl localhost:8080 -v

The default installation returns:

 About to connect() to localhost port 8080 (#0)
*   Trying connected
> GET / HTTP/1.1
> User-Agent: curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/ libidn/1.23 librtmp/2.3
> Host: localhost:8080
> Accept: */*
< HTTP/1.1 301 Moved Permanently
< Content-Type: text/html;charset=UTF-8
< Via: 1.1 Repose (Repose/2.13.1)
< x-pingback:
< x-powered-by: PHP/5.3.24
< x-powered-by: ASP.NET
< Location:
< Content-Length: 149
< Date: Thu, 19 Dec 2013 00:50:32 GMT
< Server: Jetty(8.0.y.z-SNAPSHOT)
<head><title>Document Moved</title></head>
* Connection #0 to host localhost left intact
* Closing connection #0
<body><h1>Object Moved</h1>This document may be found <a HREF="">here</a></body>

Configuration files

Validate configurations with XSDs

You can validate your XML configurations using either an online validator or a command line validator. If you are interested in using an online validator, you may want to look at FreeFormatter or the W3C XML Schema (XSD) Validator. If you prefer to use a command line validator and use Linux or Mac, you can use the xmllint program that is included in libxml2.  

Use xmllint to check the validity of your XML configurations against the XSD by typing the following command in your terminal:

xmllint --noout --schema test.xsd test.xml

For test.xsd use the schema file, and for test.xml use your XML file.

The --noout flag prints only the validation results while preventing the XML file from printing to standard.

Deployment required configurations

Below are files of the default configuration settings that come with this installation. These default files are required to run Repose.

XML Schema definitionExample Config
  • The system model configuration 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.
  • The system model also 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.
  • Tells the system where to look for component artifacts and where to deploy them.


Repose configuration files are evaluated:

  • When Repose is started
    • If there are any invalid configuration files, then Repose logs the error and returns 503 response codes for all requests until all the configuration files are fixed.
  • Every 15 seconds.  This check interval is not configurable.
    • If valid configuration files are updated, making them invalid, Repose logs the error and continues running with the previous good configuration.

Configuration files

Each Repose component specifies a unique configuration name. For information and examples, see Filters and services.



Repose can load Java Servlet Filters and process the requests and responses traveling between the client and server.  

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

A Filter Chain is a sequence of filters that will intercept the request from the first filter of the sequence to the last enumerated filter in the sequence.

How to add filters

You can add filters to Repose using the System Model configuration file. See the system-model.cfg.xml example below.  The filter name's to use in the system-model.cfg.xml are defined in the each filter bundle's web-fragment.xml.

<system-model xmlns="">
  <repose-cluster id="repose">
      <node id="repose-n01" hostname="" http-port="8080" https-port="8443" />
        <filter name="http-logging" />
         <filter name="client-ip-identity" />
         <filter name="rate-limiting"/>
      <endpoint id="origin-service" hostname="" service-port="8080"/>

More about directories

All consumable artifacts meant for deployment through Repose must conform to the Java Platform, Enterprise Edition (JEE 6) specification for Enterprise ARchive (EAR) files. 

Upon completion of the Repose installation the following default directories are made accessible. These directories are described below:

Default directory model

  • Artifact directory:  Store all the artifacts that Repose has been configured to use in the artifact directory.  Default location is /User/share/repose/filters
  • Configuration directory:

    • Default location is /etc/repose.
    • Store all of Repose's XML configurations in the configuration directory.
    • The Root war deploy assumes this directory is located in /etc/repose.
    • Repose only supports file system configuration locations.
  • Deployment directory:

    • Default directory is /var/repose/deployment.
    • Repose uses the deployment directory to copy deployed versions of the artifacts it has been configured to use.
    • Define a deployment directory as a writable location.
  • Logs: This stores System logs and HTTP Logs.
  • Operating system user and group configuration:

    1. Dedicate a user and group to Repose to improve isolation and selection of Repose's permissions.

    2. Be sure the Repose user and group can write to the file system as well as read configurations stored in the file system.


Listen ports and system model interrogator

When Repose starts, it needs to know on which ports (http and/or https) it is listening for requests.  It uses this information for a few things

  1. If using the distributed datastore, Repose uses this port when communicating to other nodes in the cluster.
  2. Repose uses the port information in addition to the local network address information to determine to which cluster it belongs.
If Repose cannot determine to which cluster it belongs, it will fail to start.
In the container.cfg.xml below, we see that this instance of Repose should listen on HTTP port 8774 and HTTPS port 8775.
For v2.x:
<repose-container xmlns=''>
    <deployment-config via="Repose (Cloud Integration)" content-body-read-limit="1024">
        <deployment-directory auto-clean="false">/var/repose</deployment-directory>
        <artifact-directory check-interval="60000">/usr/share/repose/filters</artifact-directory>
        <logging-configuration href="log4j2.xml"/>

Via & X-Forwarded-For

The 'via' attribute in the container.cfg.xml file will configure what Repose will set in the Via Header of the request and response. If this attribute is not configured or left blank Repose will default to passing the version of Repose which is deployed.


When deploying under GlassFish please set a jvm option '' to 'true' so as to allow repose to set the 'Via' header

Repose will add/set the X-Forwarded-For Header to all processed requests.

The 'content-body-read-limit' attribute in the container.cfg.xml file will allow you to configure the maximum size of the request content in bytes, if the attribute is not set the default will be what ever the application server maximum value will be allowed. If the 'content-body-read-limit' is set and the request sends the content larger than the maximum value set Repose will send response with 413 response code.


 <repose-container xmlns=''>
        <deployment-directory auto-clean="false">/var/repose</deployment-directory>
         <artifact-directory check-interval="60000">/usr/share/repose/filters</artifact-directory>
         <logging-configuration href="log4j2.xml"/>


A corresponding system-model.cfg.xml could be:

<?xml version="1.0" encoding="UTF-8"?>
<system-model xmlns="">
  <repose-cluster id="repose">
      <node id="node1" hostname="localhost" http-port="8774" https-port="8775" />
      <node id="node2" hostname="some-other-host" http-port="8774" https-port="8775" />
      <filter name="http-logging"/>
      <endpoint id="openrepose" protocol="http" hostname="" root-path="/" port="80" default="true"/>

In this example, Repose would determine that it is running in the repose-cluster "repose" and is identified by node "node1"




# Set root logger level
log4j.rootLogger=DEBUG, debugFile, infoFile, warnFile, errorFile

# File
log4j.appender.debugFile.layout = org.apache.log4j.PatternLayout
log4j.appender.debugFile.layout.ConversionPattern=%d %-4r [%t] %-5p %c %x - %m%n

# File
log4j.appender.infoFile.layout = org.apache.log4j.PatternLayout
log4j.appender.infoFile.layout.ConversionPattern=%d %-4r [%t] %-5p %c %x - %m%n

# File
log4j.appender.warnFile.layout = org.apache.log4j.PatternLayout
log4j.appender.warnFile.layout.ConversionPattern=%d %-4r [%t] %-5p %c %x - %m%n

# File
log4j.appender.errorFile.layout = org.apache.log4j.PatternLayout
log4j.appender.errorFile.layout.ConversionPattern=%d %-4r [%t] %-5p %c %x - %m%n


  • No labels