Configure Carapace Proxy

Intro

The Carapace Proxy configuration can be performed in actually two ways:

• Before starting the service, by a static configuration file that Carapace automatically loads.
• With server up, applying a new configuration (named dynamic) with the REST API exposed or by editing the current one in the Admin UI > Configuration.

Static configuration

The static configuration is applied only once, when the server starts. The configuration file has to be located in the configuration folder of the server (carapace-server/conf) named server.properties. For an example of static-configuration file see server.properties.

Dynamic configuration

The configuration is named dynamic whenever the server is running and you submit a new configuration (by the REST API exposed, performing a POST request to api/config/apply with the configuration you want to apply) or edit the current one by the Admin UI > Configuration. For an example of dynamic-configuration file see server.db.dynamic.properties.

Configure a Backend mapping

To proxy a defined Listener to a specified Backend you need to setup the configuration as follow:

1. Add the Backend.
2. Add a Director that points to the backend.
3. Add an Action of type proxy or cache, depending on whether you want to cache static resources or not, and pointing to the director created above.
4. Add a Route to map each request that matches a specified regexp to the defined action.

1. Backend setup

backend.1.id=localhost:8086 id to use in the Director definition
backend.1.host=localhost
backend.1.port=8086
backend.1.probePath=/tomcatstatus/up path where the proxy looks up to check the backend reachability
backend.1.enabled=true

2. Director setup

director.1.id=director1 id to use in the Action definition
director.1.backends=localhost:8086 set of comma-separated backends ids to direct to
director.1.enabled=true

3. Action setup

action.1.id=action1 id to use in the Route definition
action.1.type=cache type of the action (for all the available action types see here)
action.1.director=director1 id of the director to use
action.1.enabled=true

4. Route setup

route.1.id=route1
route.1.action=action1 id of the Action to perform
route.1.match=regexp .*test.* RegEx used for the request mapping (whether not specified the route will be match to every request)
route.1.enabled=true

Configure a Dynamic Certificate for a Backend

Carapace Proxy features an ACME client that allows you to automatically manage dynamic certificates for configured backends, by a manager that takes care of performing all necessary steps needed to issue and renew all certificates from the Let's Encrypt CA.

Important: Before go ahead and configure Carapace to manage dynamic certificates, we suggest you to read Let's Encrypt Rate Limits Policy.

Enabling Carapace to manage Dynamic Certificates

By default dynamic certificates management is disabled. To enable it, you need to set an execution period > 0 for the Dynamic Certificates Manager as follow:
dynamiccertificatesmanager.period=30 in seconds

Once enabled, you can specify the size (bytes) of the Key Pairs (Public + Private keys) generated to perform certificate signing for a specific domain (default value is 2048):
dynamiccertificatesmanager.keypairssize=1024 size in bytes

Finally, all you need to do is setup the hostnames for those you want manage a dynamic certificate:
certificate.i.hostname=backend_domain
certificate.i.dynamic=true default false