Deploying Iguana on Unix, Linux and Mac OS X

Database Deployment Issues

Note: If you are using Iguana in the Unix, Linux or Mac OS X environment and are using MySQL or Oracle, you must ensure that the LD_LIBRARY_PATH environment variable includes the location of your database’s shared libraries.

Using Iguana With PostgreSQL via ODBC on Unix, Linux and Mac OS X

Iguana supports PostgreSQL on Unix/Linux platforms through ODBC. Iguana utilizes the shared library of an ODBC manager, which in turn utilizes the shared library of PostgreSQL’s ODBC driver.

If your installation of PostgreSQL does not include an ODBC driver, you may download psqlodbc, which is the official PostgreSQL ODBC driver. Furthermore, if you do not already have an ODBC driver manager, you may download unixODBC, which is a popular ODBC driver manager distributed under GPL and LGPL.

Although unixODBC includes a PostgreSQL ODBC driver, at the time of writing of this manual (Dec. 2004), some features utilized by Iguana weren’t supported by the included driver. Therefore, it is recommended that the latest version of psqlodbc be installed. Additionally, please ensure that the odbc.ini file utilized by the ODBC driver manager is configured to link to psqlodbc and not to some other PostgreSQL ODBC driver.

Two environment variables need to be configured for proper ODBC support on Unix/Linux. The LD_LIBRARY_PATH (or the equivalent dynamic linker variable for your platform) will need to include the absolute path to the ODBC driver manager’s shared library. Also, unixODBC requires an ODBCSYSINI environment variable to point to the directory that contains the odbc.ini file.

Using Iguana With MySQL on Unix, Linux and Mac OS X

MySQL can be accessed locally as well as via a remote database connection in a Unix or Linux environment.

Use the Database Settings page to search for the MySQL library that you want to use. For more information, see Database Settings.

The table below shows the shared object name for each supported platform:

Platform Shared Object Name
Linux libmysqlclient_r.so
Solaris libmysqlclient_r.so
Mac libmysqlclient_r.dylib
Hpux libmysqlclient_r.sl

Using Iguana With OCI Oracle Using Oracle Instant Client on Unix, Linux and Mac OS X

Install OCI

To enable OCI support for Unix, install the correct Oracle Instant Client for the Unix distribution Iguana is being deployed on.

The OCI Shared Object

Iguana relies on the detection of the Oracle Instance Client shared object. The shared object name is platform dependent and is listed below:

Platform Shared Object File Name
HPUX libclntsh.sl
Other Unix platforms libclntsh.so
Mac OS X libclntsh.dylib

Once the shared object is found, the absolute directory path it is located in must be placed into the LD_LIBRARY_PATH (or the equivalent dynamic linker variable for your platform) or ld.so.conf before starting Iguana.

The Instance Client distribution may append a version number to the shared object file name. In that case, simply create a symbolic link with the appropriate name to the versioned name, so Iguana can find the file.

Oracle Client library install and configuration

You may have to do these steps in order to make OCI available to Iguana:

  • Architecture match – Make sure you have the Oracle client library for the same architecture as Iguana – e.g. if Iguana is x64, Oracle client must also be x64 – use the “file” command to check architecture of binaries and shared libraries – e.g.$ file iNTERFACEWARE-Iguana/iguana
    iNTERFACEWARE-Iguana/iguana: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked (uses shared libs), for GNU/Linux 2.6.9, stripped$ file /path/to/instantclient/lib/libclntsh.so.*
    /path/to/instantclient/lib/libclntsh.so.11.1: ELF 64-bit LSB shared object, x86-64, version 1 (SYSV), dynamically linked, not stripped
  • Executable Mode – Shared libraries must have executable mode, i.e.,sudo chmod +x /path/to/instantclient/lib/*.so*
  • Symlink – liblcntsh.so from Instant Client packages is only provided with a version-specific extension – e.g. libclntsh.so.11.1 – for simplicity, a symlink can be created to make it available as libclntsh.so, i.e.,ln -s libclntsh.so.11.1 libclntsh.so
  • LD config to find shared libraries – Shared libraries should be added to LD_LIBRARY_PATH or /etc/ld.so.conf + ldconfig or equivalent – this may also be required to load Oracle client’s own sub-dependencies provided from the same directory. May have to restart Iguana for this to take effect.
  • TNS_ADMIN points to the directory containing tnsnames.ora – make sure Iguana is seeing the valuable – add it to Iguana Settings – Environment Variables to ensure it’s always available. May have to restart Iguana for this to take effect.
  • Settings – Databases – OCI Oracle – point to /path/to/instantclient/lib/libclntsh.so (or the equivalent platform-specific extension as above)

OCI configuration – tnsnames.ora and TNS_ADMIN

A common issue that arises with OCI under Unix, Linux or Mac OS X is providing access to the TNS Names when configuring a channel.

A file named tnsnames.ora must exist in the path listing pointed to by the TNS_ADMIN environment variable.

Please see the Oracle documentation about creating/editing the tnsnames.ora file, and setting the TNS_ADMIN environment variable.

When connecting, name parameter should refer to the name of a tnsnames.ora entry.

Leave A Comment?