Previous Next JavaScript must be enabled to correctly display this content

## 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.