This page applies equally to all of our Enterprise Server server-side apps.
How to set properties
Each property can be set either in a properties file, as a sysarg
, or as an environment variable. The property definition format and order from the lowest to highest precedence are:
- The properties file chosen with the
--config <path>
sysarg with the property in it, e.g.org.id=my.org
. - Environment variables (use capitals and underscores), e.g.
ORG_ID=my.org java -jar app.jar
. - Command-line arguments e.g.
java -jar app.jar --property org.id=my.org
.
General properties
These relate to the basic configuration and how the app REST API and/or web app is accessed:
Property | Description |
---|---|
org.id |
An identifier for your business that comes with your license. We’ll assign this to you. Example: evaluation.org
|
api.hostname |
The IP address or hostname that the service will listen to. The 0.0.0.0 address means binding to all available IP interfaces.Example: 0.0.0.0
|
api.port |
The listening port of the service. You may choose any port if the service is behind a Reverse Proxy or Load Balancer if the service is ultimately exposed on the 443 port to the client. If you run the node stand-alone without any layer in front of it, use the 443 port.Example: 443
|
api.accept.hosts |
The allowed hosts the browser/client can send requests to. This corresponds to the HTTP request Host header. You can set more than one comma-separated allowed hosts: api.accept.hosts=[host as seen from the load balancer]:[port],[host as seen from the client]:[port] .Example: evaluation.org,localhost:8080
|
api.https.enabled |
true to listen on HTTPS, and false to listen on HTTP. Either enable HTTPS in configs or put it behind the HTTPS reverse proxy on the same machine.Example: true
|
api.https.key.file |
(for api.https.enabled=true ) The keystore file containing the certificate to present to HTTPS requests.Example: keystore.p12
|
api.https.key.password optional |
(for api.https.enabled=true ) The password to access the keystore file. Empty means the keystore file isn’t encrypted.Example: ` ` (empty) |
api.cors.origins optional |
A comma-separated CORS valid origins. Use * for greedy matching. No property means all origins are accepted.Example: https://*.example.com
|
api.error.format optional |
The level of detail to show in error messages. The detailed option returns the full stack trace, short offers a simple message that exposes fewer system details, and id_only returns an ID for the message so that full details can be found in the logs. Default value: detailed Example: detailed
|
api.openapi.enabled |
Set to true to allow Swagger API definitions to run at /openapi and /openapi/json .Example: false
|
truststore.file optional |
Java trust store which holds public certificates/keys used to validate other users and issuing authorities. Comment out this line to use the default JRE trust store, or uncomment to set a truststore to verify KMIP connections. Example: truststore.p12
|
truststore.password optional |
The password for the truststore file. Empty means the truststore file isn’t encrypted. Example: password
|
truststore.include.default optional |
When the value is set to false , it means that only the provided truststore file is used; true means that the JVM default and the provided truststore are both used.Default value: false Example: true
|
Don’t run me as a root
We don’t recommend running the service as root. Instead, you can use the following command:
sudo setcap CAP_NET_BIND_SERVICE=+eip $(readlink -f `which java`)
By executing this command, the java
binary will be able to bind on low ports without running it as a root. Alternatively, you could run the above-mentioned command for a specific startup script, like so:
sudo setcap CAP_NET_BIND_SERVICE=+eip /full/path/to/start-ekm-service.sh
How to create SSL/HTTPS certs and truststore
To create/edit a Java keystore file, we’d recommend one of the following options:
-
openssl: If you already have a PEM file, you can convert it to PKCS#12 as follows:
openssl pkcs12 -export -out cert.p12 -in cert.pem -inkey key.pem
. - KeyStore Explorer: Use PKCS#12 format when exporting the keystore file.
How to configure Java keystore & truststore files
A Java keystore stores private key entries or TLS certificates. You can configure this EKM with two keystore files: api.https.key.file
for HTTPS and store.kmip.key.file
for KMIP connection TLS.
A truststore is the opposite. While a keystore holds onto keys/certificates that identify us, a truststore holds onto certificates that identify others. This is particularly important if you use your own CA, as this will be required for communication between two deployed services, as well as between the service and external KMIP store if such an integration can be configured for that particular service. Java comes with a default truststore only containing public CAs. To use self-signed certificates, point to a custom truststore with a truststore.file
property.
Troubleshooting
Below are common startup problems and how to resolve them:
Message | How to fix |
---|---|
java.io.FileNotFoundException: flowcrypt-\[service].properties |
The application can’t find the properties file. Please rename or create the file. |
\[xxx] is not a valid option for property \[yyy] |
There is a typo or invalid option for the specified property. Please select a valid value from the displayed options. |
Property '\[xxx]' not found |
The service is expecting a property to be defined in the properties file but it’s not found. Please create, or uncomment the line. |
UnrecoverableKeyException: failed to decrypt safe contents entry |
This means the password for your Java keystore or truststore file is incorrect. |
ConnectException: Connection refused: connect |
This message during startup means that one of the URLs in your properties file is down. Please check the provided JWKS URLs. |
You can debug more complex issues by running with the logger.default.level=DEBUG
property.