Search docs.molo17.com

    Oracle XStream logo 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 60 seconds) 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.ora of 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.ora and the wallet, as Core Hub sees it

    Multi-Tenant Specific Settings

    For multi-tenant databases, additional settings are required:

    • CDB Name: Name of the container database

    • PDB Name: Name of the pluggable database containing the data

    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, .p12 or .pfx file, or a PEM file (.pem, .crt, .cer) with the CA certificates, which the agent converts to PKCS12. Use a .jks, .p12 or .pfx key store for mutual TLS.

    • A custom Connection string is used as you write it: enter PROTOCOL=TCPS in 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-hub of 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 with ORA-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 24 hours)

      • 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.ora and the wallet, inside the Core Hub container, required with the wallet

    The Oracle agents do not read trustServerCertificate or certificatePath.

    Best Practices

    1. Connection Pool Management:

      • Set appropriate maxConnectionsCount based on your workload

      • Monitor connection usage patterns

    2. Timeout Configuration:

      • Adjust timeoutSeconds based on network latency

      • Consider longer timeouts for large data operations

    3. XStream Settings:

      • Keep default xstreamServerName unless multiple instances needed

      • Adjust xstreamLowWatermarkRetentionHours based on change frequency

    4. 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:

    1. Verify connection parameters

    2. Check user permissions

    3. Validate XStream server name

    4. Review timeout settings

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