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.

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

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]

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

/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]

In general for production systems we recommend using cron to run the Iguana daemon automatically. Though you can also run the Iguana executable from a terminal or using a shell script.

To start the Iguana daemon automatically:

  1.  Run this command to edit your crontab file: 
    crontab -e
  2. Add the following line to your crontab file: 
    @reboot <iguana install path>/iguana_service
  3. Run the following command to view the crontab manual page: 
    man 5 crontab

To run Iguana as a daemon:

  1. Type the following in a terminal window: 
    /home/<user>/iNTERFACEWARE-Iguana/iguana_service
  2. Alternatively you can use a shell script to start Iguana when you log on, for example: 
    #!/bin/sh

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

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

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 open files limit on your system:

  1. Run the ulimit -a command in a terminal window, and check the open files entry:

    The open files line indicates the upper limit on the number of files that can be open at one time — we recommend a setting of 1024.

    $ 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
  2. Use ulimit -n to set the open files entry to 1024: 
    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:

  1. Run the ulimit -a command in a terminal window, and check the open files entry:

    The open files line indicates the upper limit on the number of files that can be open at one time — we recommend a setting of 1024.

    $ 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
  2. To change the stack size, use the ulimit -s <size in kilobytes> command. 
    ulimit -s 4098

    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 macOS and you have used the iguana_service daemon to start Iguana, you must be careful when stopping Iguana. To stop you must stop the parent process iguana_service, not the iguana process that is spawned by iguana_service. When iguana_service is killed, it exits immediately, and Iguana can be restarted in the normal way without problems.

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, then Iguana issues a SIGQUIT signal. This signal enables your system to generate a core dump.

Also see the FAQ Gracefully Stopping Iguana Daemon on Linux for more information.

Tagged: