The wire listener configuration file

The wire listener is configured through a properties file. This properties file contains, among other things, settings for the connection between the wire listener and the database server.

The default name for the configuration file is $INFORMIXDIR/etc/jsonListener.properties. You can rename this file, but the suffix must be .properties.

A sample properties file is provided at $INFORMIXDIR/etc/jsonListener-example.properties. In the sample properties file, all of the parameters are commented out by default. To enable a parameter, you must uncomment the row and customize the parameter.

To modify the wire listener configuration file once the listener is started, you must first stop the wire listener, then update the configuration file and restart the wire listener for the changes to take affect.

Wire listener configuration properties

Important: The url parameter is required. All other parameters are optional.

Required
- url
Setup and configuration
High availability
Command and operation configuration
Database resource management
MongoDB compatibility
Performance
Security
Wire listener resource management

Required parameter

You must configure the url parameter before using the wire listener.

url

This required parameter specifies the host name, port number, user ID, and password that are used in connections to the database server.

You must specify the sysmaster database in the url parameter. That database is used for administrative purposes by the wire listener.

You can include additional JDBC properties in the url parameter such as INFORMIXCONTIME, INFORMIXCONRETRY, LOGINTIMEOUT, and IFX_SOC_TIMEOUT. For a list of HCL OneDB™ environment variables that are supported by the JDBC driver, see HCL OneDB environment variables with the HCL OneDB JDBC Driver.

hostname:portnum: The host name and port number of your computer. For example, localhost:9090.
USER=userid: This optional attribute specifies the user ID that is used in connections to the HCL OneDB database server. If you plan to use this connection to establish or modify collection shards by using the HCL OneDB sharding capability, the specified user must be granted the REPLICATION privilege group access.; If you do not specify the user ID and password, the JDBC driver uses operating system authentication and all wire listener actions are run by using the user ID and password of the operating system user who runs the wire listener start command.
PASSWORD=password: This optional attribute specifies the password for the specified user ID.
NONCE=value: This optional attribute specifies a 16-character value that consists of numbers and the letters a, b, c, d, e, and f. This property triggers password encoding when a pluggable authentication module is configured for the wire listener. Applicable only if the db.authentication parameter is set to onedb-mongodb-cr.

Setup and configuration

These parameters provide setup and configuration options.

documentIdAlgorithm

This optional parameter determines the algorithm that is used to generate the unique HCL OneDB identifier for the ID column that is the primary key on the collection table. The _id field of the document is used as the input to the algorithm. The default value is documentIdAlgorithm=ObjectId.

ObjectId

Indicates that the string representation of the ObjectId is used if the _id field is of type ObjectId; otherwise, the MD5 algorithm is used to compute the hash of the contents of the _id field.

The string representation of an ObjectId is the hexadecimal representation of the 12 bytes that comprise an ObjectId.
The MD5 algorithm provides better performance than the secure hashing algorithms (SHA).

ObjectId is the default value and it is suitable for most situations.

Important: Use the default unless a unique constraint violation is reported even though all documents have a unique _id field. In that case, you might need to use a non-default algorithm, such as SHA-256 or SHA-512.

SHA-256

Indicates that the SHA-256 hashing algorithm is used to derive an identifier from the _id field.

SHA-512

Indicates that the SHA-512 hashing algorithm is used to derive an identifier from the _id field. This option generates the most unique values, but uses the most processor resources.

include

This optional parameter specifies the properties file to reference. The path can be absolute or relative.

listener.onException

This optional parameter specifies an ordered list of actions to take if an exception occurs that is not handled by the processing layer.

reply: When an unhandled exception occurs, reply with the exception message. This is the default value.
closeSession: When an unhandled exception occurs, close the session.
shutdownListener: When an unhandled exception occurs, shut down the wire listener.

listener.hostName

This optional parameter specifies the host name of the wire listener. The host name determines the network adapter or interface that the wire listener binds the server socket to.

Tip: If you enable the wire listener to be accessed by clients on remote hosts, turn on authentication by using the authentication.enable parameter.

localhost: Bind the wire listener to the localhost address. The wire listener is not accessible from clients on remote machines. This is the default value.
hostname: The host name or IP address of host machine where the wire listener binds to.
*: The wire listener can bind to all interfaces or addresses.

listener.port

This optional parameter specifies the port number to listen on for incoming connections from clients. This value can be overridden from the command line by using the -port argument. The default value is 27017.

Important: If you specify a port number that is less than 1024, the user that starts the wire listener might require additional operating system privileges.

listener.timezone

This parameter specifies the timezone of the listener java JVM. This will override any system or user configured default timezone. The timezone property affects the timezone of date values that are used outside of BSON documents.

Important: It is recommended that the listener timezone be set to UTC (or GMT). You should change this property only if you are using the listener to interact with relational tables that store dates in a timezone other than UTC/GMT.

Possible values: UTC, GMT, GMT+1, GMT+2, GMT-1, GMT-2, EST, CST, etc. Set this property to null to use the system's default timezone.

response.documents.count.default

This optional parameter specifies the default number of documents in a single response to a query. The default value is 100.

response.documents.count.maximum

This optional parameter specifies the maximum number of documents in a single response to a query. The default value is 10000.

response.documents.size.maximum

This optional parameter specifies the maximum size, in bytes, of all documents in a single response to a query. The default value is 1048576.

sharding.enable

This optional parameter indicates whether to enable the use of commands and queries on sharded data.

false: Do not enable the use of commands and queries on sharded data. This is the default value.
true: Enable the use of commands and queries on sharded data.

sharding.parallel.query.enable

This optional parameter indicates whether to enable the use of parallel sharded queries. Parallel sharded queries require that the SHARD_ID configuration parameter be set to unique IDs on all shard servers. The sharding.enable parameter must also be set to true.

false: Do not enable parallel sharded queries. This is the default value.
true: Enable parallel sharded queries.

High Availability

These parameters provide configuration options for ensuring high availability and transaction survivability to your MongoDB applications in case of a database server failover.

failover.retry.enable

Enables the listener to automatically retry client requests if a possible server failover is detected.

In the case of a server failover, the wire listener can be automatically rerouted by the Connection Manager to the new primary in the high-availability cluster, or to any other online server in the cluster, depending on how the service level agreement rules are configured. In such a scenario, you may choose to enable the wire listener to monitor for failover error codes from the server. If such a failure is detected, the wire listener will attempt to automatically reconnect through the Connection Manager to another server in the cluster and retry the client operations there. The wire listener will only return an error to the client application if it cannot establish a new connection to the cluster. This automatic retry provides seamless high availability to MongoDB client applications with the wire listener and the Connection Manager automatically handling the rerouting of client operations in the event of a database server failover.

If failover.retry.enable is set to true, the url property must point to a OneDB Connection Manager.

true: Enable automatic retry of client requests if a possible server failover is detected.
false: Disable automatic retry of client requests.

failover.retry.delay

This optional parameter specifies the delay in milliseconds that the wire listener waits before trying to reestablish a connection after a failover error code is received from the database server. This parameter only takes effect if


              failover.retry.enable=true

failover.retry.errorCodes

This optional parameter specifies the list of database server error codes that will be considered an indication of a possible failover.

If failover.retry.enable is set to true, this list provides the list of error codes that will trigger the wire listener to attempt to reestablish a connection from the Connection Manager and retry the client request again. This parameter only takes effect iffailover.retry.enable=true.

failover.retry.maxRetries

This optional parameter specifies the maximum number of times the wire listener will retry an client request after a potential failover error is received from the database server.

If the wire listener is connected to a Connection Manager that can automatically reroute the wire listener when a server failover occurs, this failover.retry.maxRetries parameter controls how many times the wire listener will attempt to reestablish a connection and retry the client operation that failed. This parameter only takes effect iffailover.retry.enable=true.

Command and operation configuration

These parameters provide configuration options for JSON commands and operations.

collection.onedb.options

This optional parameter specifies which table options for shadow columns or auditing to use when creating a JSON collection.

audit: Use the AUDIT option of the CREATE TABLE statement to create a table to be included in the set of tables that are audited at the row level if selective row-level is enabled.
crcols: Use the CRCOLS option of the CREATE TABLE statement to create two shadow columns that Enterprise Replication uses for conflict resolution.
erkey: Use the ERKEY option of the CREATE TABLE statement to create the ERKEY shadow columns that Enterprise Replication uses for a replication key.
replcheck: Use the REPLCHECK option of the CREATE TABLE statement to create the ifx_replcheck shadow column that Enterprise Replication uses for consistency checking.
vercols: Use the VERCOLS option of the CREATE TABLE statement to create two shadow columns that HCL OneDB uses to support update operations on secondary servers.

command.listDatabases.sizeStrategy

This optional parameter specifies a strategy for calculating the size of your database when the MongoDB listDatabases command is run. The listDatabases command estimates the size of all collections and collection indexes for each database. However, relational tables and indexes are excluded from this size calculation.

Important: The MongoDB listDatabases command performs expensive and CPU-intensive computations on the size of each database in the database server instance. You can decrease the expense by using the command.listDatabases.sizeStrategy parameter.

estimate

Estimate the size of the database by sampling documents in every collection. This is the default value. This strategy is the equivalent of {estimate: 1000}, which takes a sample size of 0.1% of the documents in every collection. This is the default value.

command.listDatabases.sizeStrategy=estimate

estimate: n

Estimate the size of the database by sampling one document for every n documents in every collection. The following example estimates the collection size by using sample size of 0.5% or 1/200th of the documents:

command.listDatabases.sizeStrategy={estimate:200}

compute

Compute the exact size of the database.

command.listDatabases.sizeStrategy=compute

none

List the databases but do not compute the size. The database size is listed as 0.

command.listDatabases.sizeStrategy=none

perDatabaseSpace

Calculate the size of a database by adding the sizes for all dbspaces, sbspaces, and blobspaces that are assigned to the tenant database.

Important: The perDatabaseSpace option applies only to tenant databases that are created by the multi-tenancy feature.

update.client.strategy

This optional parameter specifies the method that is used by the wire listener to send updates to the database server. When the wire listener does the update processing, it queries the server for the existing document and then updates the document.

updatableCursor: Updates are sent to the database server by using an updatable cursor. This is the default value.
deleteInsert: The original document is deleted when the updated document is inserted.
Important: If the collection is sharded, you must use this method.

update.mode

This optional parameter determines where document updates are processed. The default value is update.mode=mixed.

client: Use the wire listener to process updates. You must use this mode if you enable sharding and want to allow the updating of shard key field values.
mixed: Attempt to process updates on the database server first, then fallback to the wire listener. This is the default value.

Database resource management

These parameters provide database resource management options.

database.buffer.enable

Prerequisite: database.log.enable=true

This optional parameter indicates whether to enable buffered logging when you create a database by using the wire listener.

true: Enable buffered logging.
false: Do not enable buffered logging. This is the default value.

database.create.enable

This optional parameter indicates whether to enable the automatic creation of a database, if a database does not exist.

true: If a database does not exist, create a database. This is the default value.
false: If a database does not exist, do not create a database. With this option, you can access only existing databases.

database.dbspace

Prerequisite: dbspace.strategy=fixed

This optional parameter specifies the name of the dbspace databases that are created. The default value is database.dbspace=rootdbs.

database.locale.default

This optional parameter specifies the default locale to use when a database is created by using the wire listener. The default value is en_US.utf8.

database.log.enable

This optional parameter indicates whether to create databases that are enabled for logging.

true: Create databases that are enabled for logging. This is the default value. Use the database.buffer.enable parameter to enable buffered logging.
false: Do not create databases that are enabled for logging.

database.onException.errorCodes

A JSON document describing what actions to take on specific database error codes. Each action should be followed by an array of the database's integer error codes that should trigger the specified action.

closePools: Error codes that should trigger the listener to close the existing connection pools.
disposeOfConnections: Error codes that indicate the current connection is stale and should be disposed of.
removeCollectionFromCache: Error codes that indicate that the listener's currently cached information about the collection is stale and should be refreshed.
reprepareStatement: Error codes that indicate that the prepared statement should be re-prepared.
retryStatement: Error codes that indicate that an insert, update, delete or query statement should be retried once before the error/result is returned to the client.

These lists of error codes are the default values for each statement, and can be changed or added as you desire. For example:

database.onException.errorCodes={
    "closePools":[-79716, -79730, -79735], 
    "disposeOfConnection":[-349, -79716, -79730, -79735], 
    "removeCollectionFromCache":[-710, -206], 
    "reprepareStatement":[-208, -267, -285, -79716], 
    "retryStatement":[]
}

dbspace.strategy

This optional parameter specifies the strategy to use when determining the location of new databases, tables, and indexes.

autolocate: The database server automatically determines the dbspace for the new databases, tables, and indexes. This is the default value.
fixed: Use a specific dbspace, as specified by the database.dbspace property.

fragment.count

This optional parameter specifies the number of fragments to use when creating a collection. If you specify 0, the database server determines the number of fragments to create. If you specify a fragment_num greater than 0, that number of fragments are created when the collection is created. The default value is 0.

jdbc.afterNewConnectionCreation

This optional parameter specifies one or more SQL commands to run after a new connection to the database is created.

MongoDB compatibility

These parameters provide options for MongoDB compatibility.

compatible.maxBsonObjectSize.enable

This optional parameter indicates whether the maximum BSON object size is compatible with MongoDB.

Tip: If you insert a BSON document by using an SQL operation, HCL OneDB supports a maximum document size of 2 GB.

false: Use a maximum document size of 256 MB with the wire listener. This is the default value.
true: Use a maximum document size of 16 MB. The maximum document size for MongoDB is 16 MB.

mongo.api.version

This optional parameter specifies the MongoDB API version with which the wire listener is compatible. The version affects authentication methods as well as MongoDB commands.

Note: 4.0 is the default value.

update.one.enable

This optional parameter indicates whether to enable support for updating a single JSON document.

Important: The update.one.enable parameter applies to JSON collections only. For relational tables, the MongoDB multi-parameter is ignored and all documents that meet the query criteria are updated.

false: All collection updates are treated as multiple JSON document updates. This is the default value.; With the update.one.enable=false setting, the MongoDB db.collection.update multi-parameter is ignored and all documents that meet the query criteria are updated.
true: Allow updates on collections to a single document or multiple documents.; With the update.one.enable=true setting, the MongoDB db.collection.update multi-parameter is accepted. The db.collection.update multi-parameter controls whether you can update a single document or multiple documents.

Performance

These parameters provide performance options for databases and collections.

delete.preparedStatement.cache.enable

This optional parameter indicates whether to cache prepared statements that delete documents for reuse.

true: Use a prepared statement cache for statements that delete documents. This is the default value.
false: Do not use a prepared statement cache for statements that delete documents. A new statement is prepared for each query.

insert.batch.enable

If multiple documents are sent as a part of a single INSERT statement, this optional parameter indicates whether to batch document inserts operations into collections.

true: Batch document inserts into collections by using JDBC batch calls to perform the insert operations. This is the default value.
false: Do not batch document insert operations into collections.

insert.batch.queue.enable

This optional parameter indicates whether to queue INSERT statements into larger batches. You can improve insert performance by queuing INSERT statements, however, there is decreased durability.

This parameter batches all INSERT statements, even a single INSERT statement. These batched INSERT statements are flushed at the interval that is specified by the insert.batch.queue.flush.interval parameter, unless another operation arrives on the same collection. If another operation arrives on the same collection, the batch inserts are immediately flushed to the database server before proceeding with the next operation.

false: Do not queue INSERT statements. This is the default.
true: Queue INSERT statements into larger batches. Use the insert.batch.queue.flush.interval parameter to specify the amount of time between insert queue flushes.

insert.batch.queue.flush.interval

Prerequisite: insert.batch.queue.enable=true

This optional parameter specifies the number of milliseconds between flushes of the insert queue to the database server. The default value is insert.batch.queue.flush.interval=100.

index.cache.enable

This optional parameter indicates whether to enable index caching on collections. To write the most efficient queries, the wire listener must be aware of the existing BSON indexes on your collections.

true: Cache indexes on collections. This is the default value.
false: Do not cache indexes on collections. The wire listener queries the database for indexes each time a collection query is translated to SQL.

index.cache.update.interval

This optional parameter specifies the amount of time, in seconds, between updates to the index cache on a collection table. The default value is index.cache.update.interval=120.

insert.preparedStatement.cache.enable

This optional parameter indicates whether to cache the prepared statements that are used to insert documents.

true: Cache the prepared statements that are used to insert documents. This is the default value.
false: Do not cache the prepared statements that are used to insert documents.

preparedStatement.cache.enable

This optional parameter indicates whether to cache prepared statements for reuse.

true: Use a prepared statement cache. This is the default value.
false: Do not use a prepared statement cache. A new statement is prepared for each query.

preparedStatement.cache.size

This optional parameter specifies the size of the least-recently used (LRU) map that is used to cache prepared statements. The default value is preparedStatement.cache.size=20.

Security

The parameters provide security enablement options.

authentication.enable

This optional parameter indicates whether to enable user authentication.

You can choose to authenticate users through the wire listener or in the database server.

false: Do not authenticate users. This is the default value.
true: Authenticate users. Use the authentication.localhost.bypass.enable parameter to control the type of authentication.

authentication.localhost.bypass.enable

Prerequisite: authentication.enable=true

If you connect from the localhost to the HCL OneDB admin database, and the admin database contains no users, this optional parameter indicates whether to grant full administrative access.

The HCL OneDB admin database is similar to the MongoDB admin database. The HCL OneDB authentication.localhost.bypass.enable parameter is similar to the MongoDB enableLocalhostAuthBypass parameter.

true: Grant full administrative access to the user. This is the default value.
false: Do not grant full administrative access to the user.

command.blocklist

This optional parameter lists commands that are removed from the command registry and cannot be called. By default, the block list is empty.

db.authentication

This optional parameter specifies the user authentication method. See User authentication with the wire listener for more information.

mongdb-scram: Authenticate through the wire listener with the MongoDB SCRAM-SHA-256 algorithm. MongoDB SCRAM-SHA-256 authentication is only supported on Mongo listeners. This is the default value .
onedb-mongodb-cr: Authenticate through the database server with a pluggable authentication module (PAM) using the MongoDB Challenge Response (MONGODB-CR) authentication algorithm.

listener.admin.ipAddress

This optional parameter specifies the IP address for the administrative host. Must be a loopback IP address. The default value is 127.0.0.1.

Important: If you specify an address that is not a loopback IP address, an attacker might perform a remote privilege escalation and obtain administrative privileges without knowing a user password.

listener.authentication.timeout

This optional parameter specifies the number of milliseconds that the wire listener waits for a client connection to authenticate. The default value is 0, which indicates that the wire listener waits indefinitely for client connections to authenticate.

listener.ssl.algorithm

This optional parameter specifies the Service Provider Interface (SPI) for the KeyManagerFactory that is used to access the network encryption keystore. On an Oracle Java Virtual Machine (JVM), this value is typically SunX509. On an IBM JVM, this value is typically IbmX509. The default value is no SPI.

Important: Do not set this property if you are not familiar with Java Cryptography Extension (JCE).

listener.ssl.ciphers

This optional parameter specifies a list of Secure Sockets Layer (SSL) or Transport Layer Security (TLS) ciphers to use with network encryption. The default value is no ciphers, which means that the default list of enabled ciphers for the JVM are used.

Important: Do not set this property if you are not familiar with Java Cryptography Extension (JCE) and the implications of using multiple ciphers. Consult a security expert for advice.

You can include spaces between ciphers.

For example, you can set the following ciphers:

listener.ssl.ciphers=TLS_RSA_WITH_AES_128_CBC_SHA, TLS_RSA_WITH_AES_256_CBC_SHA, 
TLS_EMPTY_RENEGOTIATION_INFO_SCSV

listener.ssl.enable

This optional parameter enables SSL or TLS network encryption on the socket for client connections. See Configuring SSL connections between the wire listener and client applications.

false: Disable network encryption. This is the default.
true: Allow network encryption.

listener.ssl.key.alias

This optional parameter specifies the alias, or identifier, of the entry into the keystore. The default value is no alias, which indicates that the keystore contains one entry. If the keystore contain more than one entry and a key password is needed to unlock the keystore, set this parameter to the alias of the entry that unlocks the keystore.