Kyvos ODBC Driver for Linux
This documentation is for Kyvos 2026.8.x. To view documentation for other Kyvos versions, click here. |
|---|
1. Overview
The Kyvos ODBC Driver for Linux is a compressed archive-based driver (tar.gz) that enables ODBC connectivity to the Kyvos Analytical Server from 64-bit Linux environments (Ubuntu). Installation involves extracting the archive to /opt and configuring DSN and driver settings through .ini files (odbc.ini, odbcinst.ini, and kyvos.odbcclient.ini).
2. Prerequisites
Each computer on which you install the driver must meet the following minimum requirements:
Root or administrative (sudo) privileges on the Linux machine
Supported 64-bit Linux distribution: Ubuntu 20.04.6 LTS (Focal Fossa).
3. Installing Kyvos ODBC Driver
Kyvos ODBC Driver for Linux is provided as a compressed archive (tar.gz) and does not require an installer.
To install the Kyvos ODBC Driver on Linux, perform the following steps.
The driver is downloaded as a Zip file from the Kyvos website.
Unzip the downloaded file to get the tar.gz file.
Copy the tar.gz file to the Linux system and extract it under
/opt.Extracting the package automatically creates the required directory structure and installs the latest version of the driver.
Once the extraction is completed, you can view the folder structure under extracted location as follows:
/opt/KyvosODBCDriver/
ErrorMessages/
setup/
odbc.ini
odbcinst.ini
lib/
kyvos.odbcclient.ini
Libkyvosodbc.so
Cacerts.pem 4. Configuring Kyvos ODBC Driver
After extracting the Kyvos ODBC Driver package, use the odbcinst.ini file to configure the Kyvos ODBC Driver.
4.1 Configuring the odbcinst.ini File
Navigate the Kyvos ODBC Driver extracted location. You will find the odbcinst.ini file in the package. For example,
/opt/KyvosODBCDriver/Setup/In the Setup folder, the
odbcinst.inifile is located that appears as follows:[ODBC Drivers] Kyvos ODBC Driver = Installed [Kyvos ODBC Driver] Driver=/opt/KyvosODBCDriver/lib/libkyvosodbc.so Setup=/opt/KyvosODBCDriver/lib/libkyvosodbc.soVerify that the path of the libkyvosodbc.so file is correct.
Now, navigate to the system-level
odbcinst.inifile at/etc/odbcinst.ini. This is where you need to add the Kyvos ODBC driver configuration (refer to step-2).Add the required Kyvos ODBC Driver configuration to the system-level
odbcinst.inifile.Save the file and verify that the changes have been applied successfully.
5. Creating a Data Source Name (DSN) on Linux
Use the odbc.ini file and configure a DSN on your Linux system.
5.1 Configuring the odbc.ini File
In the same setup folder, edit the odbc.ini file to define the DSN and its connection properties:
[ODBC Data Sources] Kyvos ODBC=Kyvos ODBC Driver [Kyvos ODBC] Description = 64 bit Kyvos ODBC Driver Driver = /opt/KyvosODBCDriver/lib/libkyvosodbc.so Host = 127.0.0.1 Locale = en-US Port = 8081 AuthMech = 3 UserName = HTTPPath = kyvos/sql SSL = 0Update the following properties for your deployment:
Kyvos ODBC — the DSN name; rename this section header (and the corresponding entry under [ODBC Data Sources]) to create additional or differently named DSNs.
Host — the IP address or hostname of the Kyvos Web App Server.
Port — the TCP port number that the Kyvos Web App Server uses to listen for client connections.
HTTPPath — the web application path, in the format <webapp name>/sql. For example, if the application name is kyvos, enter kyvos/sql.
UserName — your Kyvos Web App Server user name.
AuthMech — the authentication mechanism used to connect.
SSL — set to 1 to connect to an SSL-enabled Kyvos Analytical Server, or 0 to disable SSL.
6. Configuring Kyvos ODBC Driver using unixODBC
User can also configure Kyvos ODBC using unixODBC. Ensure that the unixODBC binaries, libraries, and configuration directories must be installed under /opt/unixODBC
If unixODBC is not installed, do the perform the following steps:
Download unixODBC
From the extracted unixODBC source directory, run the following commands:
./configure --prefix=/opt/unixODBC make sudo make installVerify that these commands should be run from the extracted unixODBC source directory.
6.1 Setting Environment Variables
Before using the driver, the following environment variables must be set so that unixODBC and the Kyvos ODBC Driver can locate their libraries and configuration files.
One-time for the Current Session
export LD_LIBRARY_PATH=/opt/unixODBC-2.3.7/lib:/opt/KyvosODBCDriver/lib:$LD_LIBRARY_PATH export PATH=/opt/unixODBC-2.3.7/bin:$PATH export ODBCINI=/opt/KyvosODBCDriver/Setup/odbc.ini export ODBCSYSINI=/opt/KyvosODBCDriver/SetupPermanently for the Current User
Add the same lines to your ~/.bashrc file:export LD_LIBRARY_PATH=/opt/unixODBC-2.3.7/lib:/opt/KyvosODBCDriver/lib:$LD_LIBRARY_PATH export PATH=/opt/unixODBC-2.3.7/bin:$PATH export ODBCINI=/opt/KyvosODBCDriver/Setup/odbc.ini export ODBCSYSINI=/opt/KyvosODBCDriver/Setup
Then run source ~/.bashrc, or open a new terminal session, to apply the changes.
Permanently for All Users (Optional)
Add the following lines to /etc/environment (without the export keyword):LD_LIBRARY_PATH="/opt/unixODBC-2.3.7/lib:/opt/KyvosODBCDriver/lib:$LD_LIBRARY_PATH" PATH="/opt/unixODBC-2.3.7/bin:$PATH" ODBCINI="/opt/KyvosODBCDriver/setup/odbc.ini" ODBCSYSINI="/opt/KyvosODBCDriver/setup"
Log out and log back in for the changes to take effect.
6.2 Testing the Connection on Linux
Unlike Windows and Mac OS, which provide a Test button in their respective ODBC administration tools, Linux does not have a graphical ODBC administrator. Use the isql command-line utility (included with unixODBC) to test the connection instead.
Open the terminal.
Run the
isql -v "Kyvos ODBC"command.If the driver is configured correctly, isql reports a successful connection.
If the connection fails, check the logs at the location specified in LogPath or ErrorMessagesPath, verify all configuration file paths, and recheck the environment variables described earlier in this document.
6.3 Troubleshooting Tips
Run odbcinst -j to check the unixODBC system configuration locations (confirms which odbc.ini and odbcinst.ini files are actually being read).
Verify that the driver's .so file has the correct permissions, and that all configuration files are readable by the user running the connection.
Double-check that LD_LIBRARY_PATH, PATH, ODBCINI, and ODBCSYSINI are all set correctly before running ODBC commands.
Review the log files at the location specified in LogPath, and the driver error message files under ErrorMessagesPath, for details on connection failures.
7. Configuring Kyvos ODBC Advanced Settings
The Kyvos ODBC settings controls driver-level settings such as encoding, certificate paths, locale, logging, fetching rows per block, and enabling asynchronous reading. These settings are provided in the kyvos.odbcclient.ini file located in the lib folder.
[Driver]
DriverManagerEncoding=UTF-16
DriverLocale=en-US
ErrorMessagesPath=/opt/KyvosODBCDriver/ErrorMessages
LogFileCount=
LogFileSize=
LogLevel=
LogPath=
TrustedCertificatePath=
RowsFetchedPerBlock=50000
EnableAsyncRead=1Update the logging-related properties and TrustedCertificatePath as needed for your environment.
7.1 Configuring Logging Settings on Linux
To help troubleshoot issues, you can configure logging settings for the driver.
Open the kyvos.odbcclient.ini file located in the lib folder (for example, /opt/KyvosODBCDriver/lib/kyvos.odbcclient.ini)
Configure the following logging parameters and save the file. After saving the file, restart your BI application for the new settings to take effect.
LogFileCount — the maximum number of log files to keep. After this number is reached, the driver deletes the oldest log file each time a new one is created.
LogFileSize — the maximum size of each log file, in Bytes. After this size is reached, the driver creates a new file and continues logging.
LogLevel — the logging level corresponding to the amount of information to include in log files.
Logging Level Number | Logging Level | Description |
1 | FATAL | Logs severe error events that lead the driver to stop processing. |
2 | ERROR | Logs error events that might allow the driver to continue running. |
3 | WARNING | Logs events that might result in an error if no action is taken. |
4 | INFO | Logs general information that describes the progress of the driver. |
5 | DEBUG | Logs detailed information that is useful for debugging the driver. |
6 | TRACE | Logs all driver activity, including result set. |
LogPath — the full path to the folder where log files are saved.
TrustedCertificatePath: Specify the trusted certificate path.
Rows Fetched Per Block: Specify the number of rows fetched in each chunk. The default value of the Rows Fetched Per Block property is 50000.
To increase the limit for the chunk size at Kyvos Analytical Server:
Add the sql.hive.server2.thrift.resultset.max.fetch.size property at the connection level.
Add a required limit in the Value field.
EnableAsyncRead: Set it to 1 to enable or 0 to disable. By Default, this property is enabled and set to 1. This feature can be enabled in scenarios where a query is expected to return a large number of records to the BI tool. With asynchronous reading enabled, the Kyvos ODBC Driver streams and displays results as they arrive instead of waiting for the complete result set, improving overall query performance and responsiveness.
7.2 Logging Path Directory and Permissions
Create a dedicated directory for ODBC query logs within your system where appropriate read/write permissions are available. Provide write access to "Other" users to ensure logs are written for all queries executed through the Kyvos ODBC Driver.
For initial setup, the directory owner must run the isql command. This establishes the first connection and automatically creates the log file.
Once the log file is created, grant write permissions to "Other" users on the log file as well.
Important
After connecting using the Kyvos ODBC Driver, a folder named SQLLog is created at the logging path location. Under this folder, new folders are created for the current date(s), containing the Kyvos_odbc_client_SQLLog.log file. This file captures records for all queries sent to the Kyvos Analytical Server.