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:

data store name. See ping.
data store helper host:port list. See Obtaining a KVStore Handle in the Java Direct Driver Developer's Guide.

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. In addition to setting this parameter as true, you must also set the `SkLogger` config properties. For more details, see Proxy Monitoring.
-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).

Proxy Monitoring: To enable proxy monitoring, you must create a SkLogger properties config file. To do this, create a logging.properties file with the following details:

/*Defines logger handler*/
oracle.nosql.skhandlers=SkFileHandler

/*Specifies the directory in which the log file should be created*/
SkFileHandler.dir=/oracle/nosql/product/proxy_logs

/*Specifies the logging level
-------Options: SEVERE, WARNING, INFO, FINE, ALL
ALL: Logs all the messages
FINE: Logs tracing messages for debugging
INFO: Logs informational messages showing the state and progress
WARNING: Indicates potential problem
SEVERE: Indicates serious failure */
SkFileHandler.level=ALL

/*Specifies how many output files to cycle through when using log file rotation. When a file reaches the limit (SkFileHandler.limit) specified, a new file is opened (for example: proxy_metrics.log.0, proxy_metrics.log.1 etc)*/
SkFileHandler.count=1

/*Defines the approximate maximum amount of data (in bytes) to write to any single log file in a rotating set. If set to zero, there is no size limit. This property is used in conjunction with count for log file rotation*/
SkFileHandler.limit=50000

When you run the proxy, you can set the logging configuration file using the command line option -D java.util.logging.config.file=logging.properties. For example:

java -Djava.util.logging.config.file=logging.properties -jar lib/httpproxy.jar -storeName
kvstore -helperHosts localhost:5000 -hostname localhost -httpPort 8080 -monitorStatsEnabled true

The metrics will be written to proxy_metrics.log.x (where 'x' depends on SkFileHandler.count that you have set above) in the directory specified. Here, in the above example, the directory specified is /oracle/nosql/product/proxy_logs.

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.