1. Administrator's Guide
  2. Configure
  3. Oracle NoSQL Database Proxy
  4. Configuring the Proxy

Configuring the Proxy

You configure the Oracle NoSQL Database Proxy after deploying a data store.

Obtain the following information from the secure data store deployment:

Here is the general usage to start the proxy:
java -jar lib/httpproxy.jar [-async <default: false>] [-config <>] [-helperHosts <>] [-hostname <>] [-httpPort <default: 80>] [-httpsPort <default: 443>] [-idleReadTimeout <default: 0>] [-kvConsistency <default: NONE_REQUIRED>] [-kvDurability <default: COMMIT_NO_SYNC>] [-kvRequestTimeout <default: -1>] [-monitorStatsEnabled <default: false>] [-numAcceptThreads <default: 3>] [-numRequestThreads <default: 32>] [-sslCertificate <>] [-sslCiphers <>] [-sslPrivateKey <>] [-sslPrivateKeyPass <>] [-sslProtocols <default: TLSv1.2,TLSv1.1,TLSv1>] [-sslSecurityDir <>] [-storeName <>] [-storeSecurityFile <>] [-verbose <default: false>]

Proxy Parameters

You can provide the following parameters as the command line arguments to start the proxy.

Parameter Required ? Default Value Description
-async No false Defines whether or not the proxy uses the asynchronous interfaces of the data store. This option instructs the proxy to use asynchronous requests, which can reduce the number of processing threads needed.
-config No No Default value
Specifies a Java properties file that contains the proxy configuration options. Supply the options in the following format:
property_name=value
For example: 
async=true
storeName=mystore
helperHosts=node01:5000
httpPort=8080
monitorStatsEnabled=true

You can pass this configuration file as a single parameter to the httpproxy.jar command from the CLI.

Note:

Ensure that you include all the options marked as Required in this table.
-idleReadTimeout No 30 Specifies the time duration (in seconds) for the server to terminate the unused connections.
-kvConsistency No NONE_REQUIRED

Configures the default read consistency used for this session. The Oracle NoSQL Database Proxy uses this parameter if the request does not specify a consistency. The consistency values are defined in the Consistency class of Java APIs.

The read operations are serviced either on a master or a replica node depending on the configured value. The following policies are supported:
  • ABSOLUTE - The read operation is serviced on a master node. With ABSOLUTE consistency, you are guaranteed to obtain the latest updated data.
  • NONE-REQUIRED - The read operation can be serviced on a replica node. Data read from the replica can be older than data on the master.

For more details on consistency, see Consistency Guarantees.

-kvDurability No COMMIT_NO_SYNC
Configures the default write durability setting used in this session. The 
kvDurability
parameter defines the durability policy to be used by a master when committing a transaction. The Oracle NoSQL Database Proxy uses the kvDurability parameter if the request does not specify a durability.
  • COMMIT_NO_SYNC - The data is written to the host's in-memory cache, but the master node does not wait for the data to be written to the file system's data buffers or subsequent physical storage.
  • COMMIT_SYNC - The data is written to the in-memory cache, transferred to the file system's data buffers, and then synchronized to a stable storage before the write operation completes normally.
  • COMMIT_WRITE_NO_SYNC - The data is written to the in-memory cache, and transferred to the file system's data buffers, but not necessarily into physical storage.

For more details on durability, see Durability Guarantees.

-kvRequestTimeout No -1

Configures the default request timeout used for this session (in milliseconds).

The Oracle NoSQL Database Proxy adjusts this parameter on a specific request depending on the timeout specified in the request.

Default value of -1 configures a timeout value of 5000.
-monitorStatsEnabled No false Enables statistics collection in the proxy. If enabled, the statistics are collected in the log file proxy_metric.log.
-sslCiphers No No Default value Advanced configuration related to SSL.
-sslProtocols No TLSv1.2,TLSv1.1,TLSv1 Advanced configuration related to SSL.
-sslSecurityDir No No Default value Advanced configuration related to SSL.
-helperHosts Required No Default value

Specifies the host name and port pairs that identify how to contact helper nodes within the data store. Use an array of strings to identify multiple helper hosts . Typically, you will get these host name and port pairs from the data store's deployer or administrator.

Example pattern:
hostname1:port1,hostname2:port2,...hostnameX:portX

Confirm that the ports in helper host list are left open by the firewall rules for connection between the proxy and data store server.
-storeName Required No Default value Specifies the name of the data store. you can obtain this name from the data store deployment process.
-hostname No localhost Specifies the host name of the machine which is starting up the proxy instance.

By default, the proxy listens on all the available network interfaces on the host. Specifying a host name allows the proxy to listen on a specific interface.

-httpPort No 80 Specifies the HTTP port of the proxy machine, which the proxy uses to accept non-secure connections from HTTP requests. This parameter is mutually exclusive with the -httpsPort parameter. Only one of these parameters can be specified.

Confirm that the port is left open by the firewall rules for connection between the proxy and the driver.

Note:

Using port 80 requires root privilege. You can use port 8080 if you do not have root privilege.
-httpsPort No 443 Specifies the HTTPS port of the proxy machine, which the proxy uses to accept secure connections from HTTPS requests. This parameter is mutually exclusive with the -httpPort parameter. Only one of these parameters can be specified.

Confirm that the port is left open by the firewall rules for connection between the proxy and the driver.

Note:

Using port 443 requires root privilege. You can use port 8443 if you do not have root privilege.
-numAcceptThreads No 3 This value determines the thread pool size for the threads that are used to handle the incoming connections to the proxy.
-numRequestThreads No 32 Determines the thread pool size for the threads that are used to handle the request input/output traffic, after the connection has been registered by the "AcceptThread" and handed over to the "RequestThread".
-verbose No false Displays the proxy start-up information. Can take either "true" or "false" as values.
-sslCertificate Required for secure proxy only. No Default value
Specifies the path to the SSL certificate file in pem file format. You can either generate a self-signed certificate using OpenSSL, or send a request to a public CA to generate a certificate. See Generating Certificate and Private Key for the Oracle NoSQL Database Proxy in the Security Guide.

Note:

The path to the SSL certificate file can be an absolute path or a path relative to the current directory (from where the proxy is started).
-sslPrivateKey Required for secure proxy only. No Default value Specifies the path to the SSL private key file. You can either generate a private key using OpenSSL, or send a request to a public CA to generate a private key. See Generating Certificate and Private Key for the Oracle NoSQL Database Proxy in the Security Guide.

Note:

The path to the SSL private key file can be an absolute path or a path relative to the current directory (from where the proxy is started).
-sslPrivateKeyPass Required for secure proxy only. No Default value Specifies the password for the private key, if the private key is encrypted. This parameter is not required if the private key is not encrypted.
-storeSecurityFile Required for secure proxy only. No Default value Specifies the path to the security log in file which is generated by the client user of the data store. The client user of the data store should be a non-admin proxy user.

Note:

Note: The path to the store security file can be an absolute path or a path relative to the current directory (from where the proxy is started).

Note:

The Oracle NoSQL Database Proxy can run in one or multiple dedicated hosts. It can be hosted inside the nodes of the data store. You can use a load balancer as the front end, which has a back end set of multiple NoSQL proxies on different hosts. While configuring a load balancer, you can add an HTTP health check. The Oracle NoSQL Database Proxy provides the following URI /V2/health for the HTTP health check. An HTTP request to this URI returns a successful response 200 OK. You can find an example for configuring HA proxy in the GitHub.