-
Notifications
You must be signed in to change notification settings - Fork 8
Configure Carapace Proxy
Carapace configuration consists of standard java .properties files, containing a set of key-value pairs following the syntax entityname.index.propertyname=value.
For each property, the indexdefines, for same entity, the application priority during configuration loading.
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.
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.
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.dynamic.properties.
Follow all things you can customize at runtime in the dynamic configuration.
listener.1.defaultcertificate=*
listener.1.host=0.0.0.0address where to listen at
listener.1.port=8080
listener.1.enabled=true|false
listener.1.ocsp=true|false
listener.1.ssl=true|false
listener.1.sslprotocols=TLSv1,TLSv1.1,TLSv1.2,TLSv1.3
listener.1.defaultcertificate=certificate-1 id of the certificate to use as default whether none certificate has been setup
backend.1.id=backend-1 unique id for the backend
backend.1.enabled=true|false
backend.1.host=hostname
backend.1.port=port
backend.1.probePath=/tomcatstatus/up path where the proxy looks up to check the backend reachability
director.1.id=director-1 unique id for the director
director.1.enabled=true|false
director.1.backends=backend-1,backend-2,...,backend-n set of comma separated backends id
action.1.id=action-1 unique id for the action
action.1.enabled=true|false
action.1.type=cache type of the action (for all the available action types see here)
action.1.headers=header-1,header-2,...header-n set of comma separated headers id (for more details see HTTP Headers Management)
In addition to this basic properties, depending on the type of the action there are other properties to setup.
action.1.file=file path-to-file path to the file to serve as static resource
action.1.director=director-1 id of the director to use
action.1.code=307 HTTPS code to use in the redirect response
To perform absolute redirects:
action.1.redirect.location=http://localhost:8080/index0.html
To perform relative redirects:
action.1.redirect.proto=http|https
action.1.redirect.host=192.0.0.1
action.4.redirect.port=1234
action.1.redirect.path=/index.html
route.1.id=route-1 unique id for the route
route.1.enabled=true|false
route.1.action=action-1 id of the Action to perform
route.1.match= ~ ".*test.*" RegEx used for the request mapping (whether not specified the route will be match to every request. For a deeply understending of matchers see Matching Expression Language section)
certificate.1.hostname=domain domain/id of the certificate
certificate.1.file=conf/localhost.p12 path to certificate file
certificate.1.password=testproxy password of the PKCS12 keystore
certificate.1.hostname=domain domain/id of the certificate
certificate.1.mode=manual
Important: this is just the configuration for the certificate: the content has to be uploaded via the Carapace REST API.
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.
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.mode=acme
One of the most important properties you may need to set up whether you want to drive a great amount of connections to the backends is maxconnectionsperendpoint. By default the value is 10 and whether you want to change it you need to define it as follow:
connectionsmanager.maxconnectionsperendpoint=100
BackendHealthManager takes care of monitoring backend status periodically by fetching a probe from the path specified in each backend with property the probePath. By default the value is 0 and whether you want to change it you need to define it as follow:
healthmanager.period=value_in_seconds
cache.maxsize=0 Maximum cache size in bytes (0 for unlimited)
cache.maxfile=xx Maximum file size in bytes that carapace must cache. If not set, files of any size are cached.