Oracle XStream Gluesync Configuration
Web UI Configuration
Configure the following parameters in the Gluesync Web UI:
Basic Connection Settings
-
Hostname / IP Address: DNS record or IP Address of your server
-
Port: Optional, defaults to
1521 -
Database name: Name of your database
-
Username: Username with read access to the tables
-
Password: Password belonging to the given username
-
Max connections count: Maximum number of connections the pool can instantiate
-
Enable TLS: (optional, defaults to
false) Connects to the TCPS listener of Oracle. See Connect over TLS or through a wallet -
Upload 'trust store' file and Trust store password: (optional) The CA certificates that the server certificate of Oracle is validated against. Without a trust store, the default CAs of the Java runtime are used
-
Upload 'key store' file and Key store password: (optional) The client certificate and its private key, only for a listener that requires client authentication (mutual TLS)
The Oracle form has no Trust server certificate switch: the Oracle driver always validates the certificate of the server.
Advanced Settings
-
Connection type: (optional, defaults to
SID) Connection type used to connect to Oracle. Available types are:-
SID -
SERVICE_NAME
-
-
Timeout seconds: (optional, defaults to
60seconds) Number of seconds to set as timeout for operations -
Xstream server name: (defaults to
GSXOUT) The name of the Xstream outbound server -
Use wallet: (optional, defaults to
false) Connects through a TNS alias resolved from a wallet folder, instead of the host and the port -
Instance name: (required when Use wallet is on) The TNS alias, defined in the
tnsnames.oraof Wallet path, of the database. Despite its name, it is an alias and not the name of an Oracle instance -
Wallet path: (required when Use wallet is on) The folder that contains
tnsnames.oraand the wallet, as Core Hub sees it
Connect over TLS or through a wallet
Gluesync reaches an Oracle listener that requires TLS (TCPS) in one of two ways: with Enable TLS and a trust store, or through a TNS alias of an Oracle wallet. In both cases the XStream connection uses the Oracle thin driver instead of OCI, because the trust material is read by the thin driver.
Enable TLS with a trust store
With Enable TLS on, the agent builds a TCPS descriptor from Hostname, Port, Connection type and Database name, for example jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS)(HOST=oracle)(PORT=2484))(CONNECT_DATA=(SID=ORCL))). Set Port to the TCPS port of the listener.
-
The server certificate is always validated, against the uploaded trust store or, without one, against the default CAs of the Java runtime. A certificate issued by a private CA needs a trust store that holds that CA.
-
A trust store can be a
.jks,.p12or.pfxfile, or a PEM file (.pem,.crt,.cer) with the CA certificates, which the agent converts to PKCS12. Use a.jks,.p12or.pfxkey store for mutual TLS. -
A custom Connection string is used as you write it: enter
PROTOCOL=TCPSin it yourself. With Enable TLS on, the trust store and the key store are applied to it as well.
Use an Oracle wallet
With Use wallet on, the agent connects to jdbc:oracle:thin:@<Instance name>?TNS_ADMIN=<Wallet path>, so the alias is resolved from the tnsnames.ora in Wallet path.
To get the wallet, change its paths and copy it where Core Hub reads it, see Prepare an Oracle wallet for Gluesync.
-
The wallet folder decides the security of the connections that go through the alias: Enable TLS and the trust and key stores of the form are not applied to them.
-
Wallet path is a path inside the Core Hub container. In the Linux kit, the folder
data/core-hubof the installation is mounted as/opt/gluesync/data: put the wallet folder under it and enter/opt/gluesync/data/<folder>. A path of the host fails withORA-12263: Failed to access tnsnames.ora. -
The wallet does not replace the credentials: Gluesync always sends the Username and the Password of the form.
-
A custom Connection string takes precedence over the wallet for the connection pool: the TLS settings of the form apply to it.
REST API Configuration
Basic Connection Setup
curl --location --request PUT 'http://core-hub-ip-address/pipelines/{pipelineId}/agents/{agentId}/config/credentials' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"hostCredentials": {
"connectionName": "myAgentNickName",
"host": "host-address",
"port": 1521,
"databaseName": "db_name",
"username": "",
"password": "",
"maxConnectionsCount": 100,
"enableTls": true,
"trustStorePath": "/opt/gluesync/data/oracle-tls/truststore.jks",
"trustStorePassword": "your_trust_store_password"
},
"customHostCredentials": {
"defaultConnectionType": "SID",
"xstreamServerName": "GSXOUT"
}
}'
trustStorePath and keyStorePath are paths inside the Core Hub container. Leave them out to use the files uploaded in the Web UI. To connect through a wallet instead, set useWalletAuthentication to true and fill instanceName and walletPath in customHostCredentials.
XStream-Specific Configuration
Configure XStream-specific settings via REST API:
curl --location --request PUT 'http://core-hub-ip-address/pipelines/{pipelineId}/agents/{agentId}/config/specific' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"configuration": {
"xstreamLowWatermarkRetentionHours": 24
}
}'
Configuration Parameters
XStream Parameters
-
xstreamLowWatermarkRetentionHours: (optional, defaults to
24hours)-
Controls the retention period for the lowest watermark level
-
Affects tables that have not had changes during the specified period
-
Helps manage archive log retention
-
Security Parameters
In hostCredentials:
-
enableTls: (boolean, defaults to
false) Connect to the TCPS listener -
trustStorePath and trustStorePassword: (optional) Trust store with the CA of the server certificate
-
keyStorePath and keyStorePassword: (optional) Key store with the client certificate, for mutual TLS
In customHostCredentials:
-
useWalletAuthentication: (boolean, defaults to
false) Connect through a TNS alias of the wallet (Use wallet in the Web UI) -
instanceName: TNS alias of the database, required with the wallet
-
walletPath: Folder with
tnsnames.oraand the wallet, inside the Core Hub container, required with the wallet
The Oracle agents do not read trustServerCertificate or certificatePath.
Best Practices
-
Connection Pool Management:
-
Set appropriate
maxConnectionsCountbased on your workload -
Monitor connection usage patterns
-
-
Timeout Configuration:
-
Adjust
timeoutSecondsbased on network latency -
Consider longer timeouts for large data operations
-
-
XStream Settings:
-
Keep default
xstreamServerNameunless multiple instances needed -
Adjust
xstreamLowWatermarkRetentionHoursbased on change frequency
-
-
Security:
-
Always use TLS in production, with Enable TLS and a trust store or with a wallet
-
The wallet resolves the connection and secures it, but does not replace the user name and the password
-
Troubleshooting
For configuration-related issues:
-
Verify connection parameters
-
Check user permissions
-
Validate XStream server name
-
Review timeout settings
-
With Enable TLS, check that Port is the TCPS port and that the trust store holds the CA of the server certificate; with the wallet, check Instance name and Wallet path
For detailed troubleshooting steps, see XStream Troubleshooting Guide.