This section describes how to set up ODBC connectivity and configure DSNs on several Linux distributions: Debian-based systems, like Ubuntu, and Red Hat Linux platforms, like Red Hat Enterprise Linux (RHEL) and Fedora.

Minimum Linux Versions

Here are the minimum supported versions for Red Hat-based and Debian-based systems:

OS	Min. Version
Ubuntu	18.04
Debian	10
RHEL	8
Fedora	28
SUSE	15

Installing the Driver Dependencies

Run the following commands as root or with sudo to install the necessary dependencies:

• Debian/Ubuntu:
  

  apt-get install libc6 libstdc++6 zlib1g libgcc1

• RHEL/Fedora:
  

  yum install glibc libstdc++ zlib libgcc

Installing the Driver

You can use standard package management systems to install the driver.

On Debian-based systems, like Ubuntu, run the following command with root or sudo:

dpkg -i /path/to/driver/setup/ApacheCouchDBODBCDriverforUnix.deb 

On systems that support the RPM package format, run the following command with root or sudo:

rpm -ivh /path/to/driver/ApacheCouchDBODBCDriverforUnix.rpm 

Licensing the Driver

Run the following commands to license the driver. To activate a trial, omit the <key> input.

cd /opt/cdata/cdata-odbc-driver-for-apachecouchdb/bin/
sudo ./install-license.sh <key>

Connecting through the Driver Manager

The driver manager loads the driver and passes function calls from the application to the driver. You need to register the driver with the driver manager and you define DSNs in the driver manager's configuration files.

The driver installation registers the driver with the unixODBC driver manager and creates a system DSN. The unixODBC driver manager can be used from Python and from many other applications. Your application may embed another driver manager.

Creating the DSN

See Using unixODBC to install unixODBC and configure DSNs. See Using the DataDirect Driver Manager to create a DSN to connect to OBIEE, Informatica, and SAS.

Connecting to Apache CouchDB

Apache CouchDB supports three types of authentication:

• Basic: Basic username/password authentication.
• JWT: Authentication with JWT token.
• None: Anonymous access for databases that are public.

If you want your users (or JWT tokens) to have access to only specific databases, you have to configure the admin_only_all_dbs option in the Apache CouchDB instance to grant all users access to the "/_all_dbs" endpoint which is required by the driver for listing tables. Otherwise the driver won't be able to connect, because the endpoint will throw an authentication error.

Basic Authentication

Set the following to connect to data:

• AuthScheme: Basic.
• Url: The Url of your Apache CouchDB instance. For example: http://localhost:5984
• User The Apache CouchDB user account used to authenticate.
• Password The Apache CouchDB password associated with the authenticating user.

JWT Authentication

The following connection properties are required and must always be specified:

• AuthScheme: JWT.
• Url: The Url of your Apache CouchDB instance. For example: http://localhost:5984.

From here you can:

1. Set the following so that the driver automatically generates (and refreshes if applicable) the tokens for you:

Required

• JWTSubject: The name of the user to assign to the JWT token.
• JWTAlgorithm: The algorithm to use for the JWT token signature.
• JWTKeyType: The type of the encryption key.
• JWTKey: The encryption key used to sign the JWT token generated by the driver.

Optional

• JWTIssuer: The issuer of the JWT token.
• JWTExpiration: How long the JWT token should remain valid, in seconds.
• JWTHeaders: A collection of extra headers that should be included in the JWT header.
• JWTClaims: A collection of extra claims that should be included in the JWT payload.
• CredentialsLocation: The location of the settings file where the JWT token is saved.

2. Or you can generate the tokens yourself manually and pass them to the driver by using the JWTToken connection property.

Generating the key pair

When using asymmetric algorithms to sign the tokens, you must generate a private/public key pair. For that, a cryptographic library like OpenSSL can be used. For example:

# generate private key
openssl genrsa --out private_rsa256.pem 2048

# extract public key
openssl rsa -in private_rsa256.pem -pubout > public_rsa256.pem

JWT Configurations

Refer to CouchDB JWT Authentication Documentation for the following.

The alg and sub are required claims and will always be validated by the Apache CouchDB instance. Other required claims can be configured in the server (see required_claims). In that case, you must use JWTHeaders and JWTClaims so that the driver can include those additional claims when generating the JWT token.

You can use roles_claim_name or the roles_claim_path options to assign roles to the JWT tokens.

Refer to the following example for configuring the server and the driver:

server configuration

[chttpd]
...
authentication_handlers = {chttpd_auth, jwt_authentication_handler}, {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, default_authentication_handler}
admin_only_all_dbs = false
...

[jwt_auth]
...
required_claims = exp
roles_claim_path = my.nested._couchdb\.roles
rsa:rsa_256 = -----BEGIN PUBLIC KEY-----\nYOUR_PUBLIC_KEY\n-----END PUBLIC KEY-----\n
...

driver configuration

Url=http://localhost:5984;
JWTSubject=JWT User 1;
JWTAlgorithm=RS256;
JWTKeyType=PEMKEY_FILE;
JWTKey=PATH_TO_FOLDER\private_rsa256.pem;
JWTHeaders=kid : rsa_256 | Custom Header 1 : Test 1;
JWTClaims= my : eyJuZXN0ZWQiOnsiX2NvdWNoZGIucm9sZXMiOlsidXNlcjIiXX19 | Custom Claim 1 : Test 1;

Anonymous

Set the following to connect to data:

• AuthScheme: None.
• Url: The Url of your Apache CouchDB instance. For example: http://localhost:5984
• PublicDatabases: A comma-separated list of public databases to list as tables.

Set the Driver Encoding

The ODBC drivers need to specify which encoding to use with the ODBC Driver Manager. By default, the CData ODBC Drivers for Unix are configured to use UTF-16 which is compatible with unixODBC, but other Driver Managers may require alternative encoding.

Alternatively, if you are using the ODBC driver from an application that uses the ANSI ODBC API it may be necessary to set the ANSI code page. For example, to import Japanese characters in an ANSI application, you can specify the code page in the config file '/opt/cdata/cdata-odbc-driver-for-apachecouchdb/lib/cdata.odbc.apachecouchdb.ini':

[Driver]
AnsiCodePage = 932