Deploying Iguana on Linux and Mac OS X

Iguana Binary Distribution

In the 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 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 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:

myLinuxSystem:~ 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.

Shutting Down [top]

If you are running Iguana on 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?