Store - com.phenixidentity~phenix-store-json

Store is a module which is a core piece that is required in all installations.  The store module is responsible for the system configuration. All modules needing any kind of persistant configuration will use the store module to read and write configuration.

A single file

Configuration data is persisted in a single JSON file, phenix-store.json.

The data in this file is categorised into a number of categories: data sources , system nodes and PIPES to mention a few.

Editing in the file directly is not recommended. Updates should be done through the web interface.

Data structure

phenix-store.json  contains a number of "buckets"/categories.

 

Data structure

Objects

A bucket contains 0 to X objects.

Objects

Parameters

Parameters

Object references

Objects can be referenced by ID

Object references

Configuration

Two custom configuration options are available: 

"store.file": "<absolute path to the store file>",
"encryption.key": "supersecret"
Click to copy

Changing any of these parameters after the system should be done after the first initial startup. Doing so will result in unsupported behaviour .

Configuration HTTP API

The configuration store can can accessed through a HTTP API. The API is disabled by default. To enable and configure the API, use the configuration for phenix-store-json in boot.json. Available configuration parameters are listed below.

Parameter key Default value Comment
api_enabled
 false
api_host 127.0.0.1
api_port 9443
api_use_ssl true
api_use_client_auth true Applies if api_use_ssl = true. 
api_keystore_file
Mandatory if api_use_ssl = true 
api_keystore_file_type pkcs12 Applies if api_use_ssl = true
api_keystore_file_password
Mandatory if api_use_ssl = true
api_truststore_file
Applies if api_use_ssl = true and api_use_client_auth = true. If no trust store is provided, the host’s default trust store is used.

Available in 3.0 and later
api_truststore_file_type pkcs12 Applies if api_use_ssl = true and api_use_client_auth = true

Available in 3.0 and later

By default the API listens only to the loopback interface 127.0.0.1, with two-way TLS enabled.

If server.p12 is a PKCS#12 file containing the server certificate and private key, and cachain.pem is an ASCII file containing the PEM formatted public certificate chain, then the API can be configured to listen to the interface 192.168.10.112 with two way SSL using the following update to the boot.json configuration:

{
    "name": "com.phenixidentity~phenix-store-json",
	 ...
    "config": {
		...
		"api_enabled": "true",
		"api_host": "192.168.10.112",
		"api_keystore_file": "/path/to/server.p12",
		"api_keystore_file_password": "supersecret",
		"api_truststore_file": "/path/to/cachain.pem"
	 }
}
Click to copy

Note that if the api_truststore_file parameter is missing, the default trust material on the server host is used. For a detailed log of trust and key certificates, start the server with the -Djavax.net.debug=ssl option.

The setup can be tested with the cURL command provided below: it should return a JSON array of all available types in the configuration.

curl -vvv \
	--cert /path/to/client.cert.pem \
	--key /path/to/client.privkey.pem \
	--cacert /path/to/cachain.pem \
	-X POST "https://192.168.10.112:9443/types"
Click to copy

How to use the HTTP API

When the configuration is updated with, for example, a PUT call to the endpoint /config/{type}/{itemId}, the data in the configuration store changes. However, since some components in the system caches the configuration, they might not be aware of the change that has occurred. The system might therefore be in an inconsistent state until the changes has been propagated to all components. This propagation is triggered by a POST call to the endpoint /state.

See below for all available endpoints and methods.

Endpoint Method Body Description
/types GET
Get all item types.
/config/{type} GET
Get all items of specific type.
/config/{type}/{itemId} GET
Get specific item.
/config/{type} PUT [{ 
   "id": "string", 
   "config": {} 
}] 
 Create or update item with specific type and ID. Idempotent.
/config/{type}/{itemId}
 DELETE
Delete specific item. Idempotent.
/config/pipes/{pipeId}/valves
 GET
Get valves of specific pipe.
/config/node_groups/{nodeGroupId}/module_refs
 GET
Get module refs of specific node group
/config/node_groups/{nodeGroupId}/module_refs
 PUT ["string"]
 Add module refs to specific node group. Itempotent.
/config/node_groups/{nodeGroupId}/module_refs
 DELETE ["string"]
 Delete module refs from specific node group. Idempotent.
/state POST
Trigger configuration reload.