Deploying Iguana on Unix, Linux and Mac OS X

Iguana Binary Distribution

In the Unix, Linux and Mac OS X environments, Iguana can be run as a process at a terminal or as a daemon. This section shows you what files are included with the Iguana binary distribution, how to run Iguana as an executable or daemon, and how to handle common database deployment issues.

Binary Distribution Structure

The Iguana binary distribution is supplied in a tar.gz file. Expanding the file will result in a folder, with contents similar to what’s shown below:

The large binary file is the Iguana application.

Some optional environment variables can also be set:

Variable Purpose
CHM_PYTHON_LIB_PATH This is the directory that the python lib files are located in. By default if this value is empty when Iguana starts, Iguana will use the “lib” subdirectory of the Chameleon installation. If another lib directory will be used, it can be specified before starting

Note: You can also specify the directory in which the Iguana configuration file is located. See Specifying the Configuration File Directory for more details.

Iguana as an Executable [top]

Note: The Mac OS X and Linux 64-bit versions of Iguana dynamically link to SSL libraries. If you encounter linking errors when first starting Iguana, then you need to check that:

  • SSL is installed on your machine.
  • The SSL libraries are in the link path.
  • The names of the SSL libraries match the ones that Iguana require. If not, then you can create symbolic links to resolve the naming differences. For example:
cd /usr/lib
ln -s libssl.so libssl.so.0.9.7

To run the application as a regular command line executable, type the following:

/home/user/iNTERFACEWARE-Iguana/iguana --run

Note: It is important that an absolute path is given to the shell to execute Iguana because the application relies on it to determine the executable directory.

Iguana as a Daemon [top]

Note: The Mac OS X and Linux 64-bit versions of Iguana dynamically link to SSL libraries. If you encounter linking errors when first starting Iguana, then you need to check that:

  • SSL is installed on your machine.
  • The SSL libraries are in the link path.
  • The names of the SSL libraries match the ones that Iguana require. If not, then you can create symbolic links to resolve the naming differences. For example:
cd /usr/lib
ln -s libssl.so libssl.so.0.9.7

To run the application as a daemon, type the following:

/home/user/iNTERFACEWARE-Iguana/iguana_service

When running as a daemon, the process may be killed by issuing a SIGTERM to the process id listed in the

Iguana.pid

file.

An example startup shell script is provided below:

#!/bin/sh

#start Iguana as an application
#/home/user/iNTERFACEWARE-Iguana/iguana --run

#start Iguana as a daemon
#/home/user/iNTERFACEWARE-Iguana/iguana_service

To start the Iguana daemon automatically when the system is rebooted, add the following to your crontab file:

@reboot iNTERFACEWARE-Iguana/iguana_service

This command is executed after every reboot. The crontab file can be modified by running the following command:

crontab -e

For more information on crontab and its options, run the following command to view its manual page:

man 5 crontab

Open File Limits [top]

If you are using Iguana on Unix, Linux or Mac OS X, and you are running a large number of channels, you must ensure that your system allows enough simultaneous open files. If the open file limit is set too low, you may start to notice unusual behavior, such as SQL I/O errors.

To check the limit imposed by your system on the number of open files, run the ulimit -a command:

$ ulimit -a
core file size          (blocks, -c) 0
data seg size           (kbytes, -d) 6144
file size               (blocks, -f) unlimited
max locked memory       (kbytes, -l) unlimited
max memory size         (kbytes, -m) unlimited
open files                      (-n) 256
pipe size            (512 bytes, -p) 1
stack size              (kbytes, -s) 8192
cpu time               (seconds, -t) unlimited
max user processes              (-u) 266
virtual memory          (kbytes, -v) unlimited

In the output from this command, the open files line indicates the upper limit on the number of files that can be open at one time. If you use ulimit -n to increase this limit, the errors should stop occurring. Setting a value of 1024 is best:

ulimit -n 1024

Memory Usage and Stack Size [top]

If your Iguana server on Unix, Mac OS X or Linux is running a large number of channels and does not have much memory, you can reduce the server’s memory usage by changing the stack size on your system.

To view the current stack size, use the ulimit -a command. This command displays the limits and sizes that have been set for your system, including the stack size:

myUnixSystem:~ username$ ulimit -a
core file size          (blocks, -c) 0
data seg size           (kbytes, -d) 6144
file size               (blocks, -f) unlimited
max locked memory       (kbytes, -l) unlimited
max memory size         (kbytes, -m) unlimited
open files                      (-n) 256
pipe size            (512 bytes, -p) 1
stack size              (kbytes, -s) 8192
cpu time               (seconds, -t) unlimited
max user processes              (-u) 266
virtual memory          (kbytes, -v) unlimited

To change the stack size, use the ulimit -s <size> command, where <size> is the new stack size in kilobytes.

Note: Be careful when setting the stack size. A stack size that is too small may have detrimental effects on other programs.

Database Deployment Issues [top]

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.

Shutting Down [top]

If you are running Iguana on Unix, Linux or Mac OS X and you have used the iguana_service daemon to start Iguana, you must be careful when stopping Iguana.

If you want to stop Iguana by killing the process that is running it, you must stop the iguana_service parent process, not the iguana process that is spawned by iguana_service.

When iguana_service is killed, it exits immediately, and can be restarted in the normal way without problems.

Note: If you are running a version of Iguana that is older than version 4.0, iguana_service is named Iguana_service.

If you are stopping the iguana_service daemon, and it is unable to stop during the time period specified in the service_kill_timeout field of the iguana_service.hdf configuration file, Iguana issues a SIGQUIT signal. This signal enables your system to generate a core dump.

If you want Iguana to issue a signal other than SIGQUIT, you can specify the signal that Iguana is to use. To do this, add the unix_kill_signal field to the iguana_service.hdf configuration file. This file is located in the directory in which Iguana is installed.

For example, if Iguana is to issue a SIGKILL signal, add the following:

unix_kill_signal=9

Leave A Comment?