Kyvos ODBC Driver for Linux

Kyvos ODBC Driver for Linux

This documentation is for Kyvos 2026.8.x. To view documentation for other Kyvos versions, click here.

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.  

  1. The driver is downloaded as a Zip file from the Kyvos website.

  2. Unzip the downloaded file to get the tar.gz file.

  3. Copy the tar.gz file to the Linux system and extract it under /opt.

  4. Extracting the package automatically creates the required directory structure and installs the latest version of the driver. 

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

  1. Navigate the Kyvos ODBC Driver extracted location. You will find the odbcinst.ini file in the package. For example, /opt/KyvosODBCDriver/Setup/

  2. In the Setup folder, the odbcinst.ini file 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.so 
  3. Verify that the path of the libkyvosodbc.so file is correct.

  4. Now, navigate to the system-level odbcinst.ini file at /etc/odbcinst.ini. This is where you need to add the Kyvos ODBC driver configuration (refer to step-2).

  5. Add the required Kyvos ODBC Driver configuration to the system-level odbcinst.ini file.

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

  1. 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 = 0
  2. Update 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:

  1. Download unixODBC

  2. From the extracted unixODBC source directory, run the following commands:

    ./configure --prefix=/opt/unixODBC make  sudo make install 
  3. Verify 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/Setup 
  • Permanently 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. 

  1. Open the terminal. 

  2. Run the isql -v "Kyvos ODBC"command.

  3. If the driver is configured correctly, isql reports a successful connection. 

  1. 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=1

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

  1. Open the kyvos.odbcclient.ini file located in the lib folder (for example, /opt/KyvosODBCDriver/lib/kyvos.odbcclient.ini) 

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

        1. Add the sql.hive.server2.thrift.resultset.max.fetch.size property at the connection level.

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

 

Copyright Kyvos, Inc. 2026. All rights reserved.