- 1. General Information about iHTML on Unix
- 1.1. Supported Platforms
- 1.2. Required Components
- 1.2.1. unixODBC
- 1.2.2. Database Server
- 1.2.3. Web Server
- 1.3. Permissions
- 1.4. iHTML Registry Information
- 2. Installing iHTML
- 2.1. Install Introduction
- 2.1.1. Resources
- 2.1.2. Software you may need (deprecated)
- 2.1.3. Quick RPM primer
- 2.2. Required Components
- 2.2.1. Apache Web Server
- 2.2.2. UnixODBC
- 22.214.171.124. Setting up DSNs
- 2.2.3. MySQL
- 2.2.4. MyODBC
- 2.2.5. Postgres
- 126.96.36.199. PostgreSQL Quick Notes
- 2.2.6. Other databases
- 2.2.7. Netscape Web Servers
- 2.3. iHTML installation (make sure required components above are installed)
- 2.3.1. Post iHTML Installation Troubleshooting
- 2.4. System Specific Information
- 2.5. Important Raven-SSL Information
- 2.6. Important FreeBSD Information
- 3. Odds and ends
- 3.1. Using MySQL on a Remote Machine using iODBC
- 3.2. iHTML on Linux with Apache 1.3.23
- 3.3. Apache configuration notes
- 3.4. Using iHTML with Postgres
- 3.5. Using iHTML with PGP
- 4. Trouble Shooting
- 5. Document History
In addition to the Windows NT/2000/XP family, iHTML supports Linux on Intel, FreeBSD 3.x/4.x, Apache 1.36 and above only. For the remainder of this document we will use Unix to refer to all
non Windows versions of iHTML, making system specific comments where necessary.
When installing iHTML on a Unix server, there are a number of other
components that must be installed and setup before installing iHTML or
the iHTML Merchant software. This includes a web server, ODBC driver manager,
and a database server with a working ODBC driver. The most common setup on Unix
based machines is the Apache web server,
the unixODBC driver manager, and either
Postgres or MySQL
as the database server.
UnixODBC is an open source project that aims to be the definitive standard for ODBC on the
Quick Overview of ODBC
unixODBC is comprised of a number of components such as the driver
manager and drivers. The driver manager is what acts as a sort of
traffic cop for database requests. It receives the database requests
and then determines which database server and which database to send
the request to. It does this by sending the request to the particular
ODBC driver that is configured in odbc.ini (or other applicable file
- depending on the brand of driver manager in use, and whether the DSN
is user or system wide). A database server may have multiple databases within it and are segmented by the user and password. A
request in an iHTML page to access a database refers to a datasource
name in the DBNAME directive of the database tags. There must be an
entry in the odbc.ini for the database which has information on where
the database server is and how to connect to it. The driver manager
uses this information to pass through the request and to give
the response back to iHTML.
There are a number of locations and
companies that provide ODBC drivers for Unix. Some are free and
others are commercial products. Some companies providing commercial
ODBC drivers include:
See the FreeODBC library for drivers and links
to other ODBC related sites.
There are a number of popular free database solutions available for
Unix-based platforms. The most popular free choices are Postgres and MySQL.
iHTML will also work with many commercial database products on Unix, such as those
offerend by Oracle and Sybase. The key for chosing a database server to use with iHTML on Unix (or any operating system) is making sure that there
is a working ODBC driver for that database on your platform.
The Apache web server is the most popular web server in the world, and
is used on over 60% of all web sites. Inline highly recommends using Apache
on Unix-based systems.
Apache must be configured with DSO support. DSO stands for dynamic
shared object. Essentially, this allows .so files to be used with
Apache. A .so file is similar to a .DLL file on Windows NT. iHTML
will not work without DSO support enabled. Each version of Apache
has to have a specific version of iHTML compiled for it because Apache
checks the version number any .so file was compiled under and if it
doesn't match then it will not work. If a new version of Apache is
released, check with Inline to get the latest .so file for that
version of Apache. This usually is available a few weeks after the
official release of the new Apache version. You can check to see if
Apache has DSO support enabled by looking for mod_so.c in the output
One of the most important aspects of getting iHTML installed and
running correctly on Unix is to get permissions setup correctly. Any
file that iHTML needs access to must have read and execute
chmod to set these correctly. Since iHTML runs
under the web user account, that account is the one that has to have
the correct permissions. So, unixODBC, the database server and
any directories that have iHTML files in them must have at least these
permissions. When using the Netscape webservers, they only run
correctly when the webuser owns the files it is serving as well. Use
chgrp to adjust this if necessary.
iHTML uses a flat text file system that works in the same manner as
the Windows NT registry. This set of directories and files is laid
out in the same manner and the Windows version of iHTML and the Unix
version of iHTML have the same configuration settings that are stored
in the registry. The registry settings are stored in text files and
can be edited with any text editor. The iHTML specific settings are
in the directory
/usr/ihtml/registry/hkey_local_machine/software/inline/ihtml and the
The following documentation contains step-by-step instructions for getting iHTML up and running with
Apache, unixODBC, and MySQL + MyODBC, or Postgres. The documentation tends to be very Linux oriented (specifically
RPM-based distributions), but platform specific notes will be made where necessary.
The following are helpful links to components that you may need to get
iHTML running correctly on Unix.
- The homepage of the unixODBC project. There are install docs on the
"download" page that are pretty good assuming you have all the
libraries/includes etc. that it requires. You must get Qt 2.x to
compile the GUI programs correctly. The GUI, however, is not necessary to use unixODBC.
- MyODBC Section of mysql.com
- Just a quick link into the main MyODBC section of the very useful mysql.com site.
- RPM Repository
- This is a great site. 60,000 RPMs, usually quite up to date. Be sure to
rpmfind utility from this site and install it. It's extremely
- Information about RPMs
- Some RPM info, links etc. Not bad info, if not a bit dated.
This is sort of a deprecated section of this documentatation, and is being left in simply
for reference. Most recent Red Hat systems should have sufficiently recent versions of all
these packages already installed.
RPMs are software packages for Red Hat (and other types of) Linux. They're handy
because all program info is maintained in a database on the system,
and it's easy to check what version of something you have, or if you
have it at all, or uninstall or upgrade software you have.
$ rpm -qi kernel - Shows info about the kernel package.
$ rpm -qil kernel - Shows package info about the kernel, as well as lists all files in that package.
$ rpm -qf [some file name] - Tries to find out which package [some file name] is part of.
$ rpm -qip whatever-file.rpm - Adding
p allows direct examination of .rpm files.
$ rpm --help - Gives you all the options of the
Installing/Upgrading a RPM
To install or upgrade an RPM, simply use
rpm -Uvh [file.rpm]. The U means upgrade, which will either
install or upgrade file.rpm, depending on what makes sense. (i.e. you can't upgrade if the package isn't installed yet!)
The v means verbose, and the h tells
rpm to output hash (#) marks showing install/upgrade progress.
If you have a number of RPM files, you can specify them all at once, separated by spaces. i.e.
rpm -Uvh file1.rpm file2.rpm file3.rpm Any dependencies between RPMs will be resolved this way.
Building a source RPM
This section about source RPMs is somewhat under-developed. Proceed with caution.
$ rpm --rebuild [file.src.rpm].
Basically, you download the file, run the command above and it
compiles all the stuff and actually builds for you other binary
RPMS. At the end your left with a bunch of new binary RPMS in
/usr/src/redhat/RPMS/[chip architecture] that you can install as
Documentation convention: In this document, a "$" means that you should type whatever follows it
at the Linux prompt. Text to be entered at the prompt will also be set off
like this. This
document assumes that you are logged in as the root user, unless otherwise specified.
It is highly recommended that you read this entire document before beginning your install of iHTML.
Due to the fast-paced changes occurring with all the software involved here, it is recommended that
you read the README and INSTALL files that come with the packages listed below.
To install Apache from source, follow the instructions below:
- Get Apache 1.3.x. (Tested up to 1.3.26. this document asumes 1.3.23.)
- Untar the Apache source to a temp directory somewhere: i.e.
tar zxvf apache_1.3.23.tar.gz.
This will create the apache_1.3.23 directory. Change to that directory:
- Configure the source:
./configure --prefix=/usr/local/apache \
This will configure Apache to be installed to /usr/local/apache -- you can specify any directory you'd like,
but these docs will assume that apache is installed in /usr/local/apache. The backslashes "
at the end of each line just signifies that the command is spanning multiple lines. You may omit them and
put the entire command on one line if you'd like.
- At the command prompt, run:
make; make install. This will compile the Apache source, and
install it to /usr/local/apache, as specified in the
- Apache can be started, stopped, restarted, etc., from the
apachectl utility. i.e. to start
- That's it for Apache for now. You will probably want to edit the /usr/local/apache/conf/httpd.conf file
to customize for your system.
Optionally, Apache can be installed from a package format, like a Red Hat RPM. Check with the Apache homepage
rpmfind to find the latest RPMs for Apache.
It is highly recommended that you read over the installation documentation posted at the unixODBC site. This
document provides enough information to get UnixODBC up and running nicely with iHTML, but there is more to be
learned from the unixODBC docs themselves.
This document assumes unixODBC 2.2.12, though the procedure should be identical from the earlier version 1.8.7 and onwards.
- Get the latest .tar.gz file from unixodbc.org (unixODBC-2.2.12.tar.gz currently).
- Copy the file to a temp directory, and untar/gzip it with
tar zxvf unixODBC-2.2.12.tar.gz.
This will create a directory called unixODBC-1.8.10; change into it via
- Configure the source:
./configure --prefix=/usr/local \
As you can see, the above specifies to turn off the GUI features of unixODBC. You can leave them on if you wish
(and if you have Qt installed), but they are not necessary, and this document does not assume they're
present. Another option that can be handy to save time is
--disable-drivers. This is obviously
only really useful if you already have the drivers you will need. A word about the switches:
specifies the directory into which unixODBC will be installed. In this case we're going to install into
/usr/local. You can specifiy anywhere you wish, though.
sysconfdir tells unixODBC where
to look for (and put) its configuration files. In this case we're specifying /etc, which means that /etc/odbc.ini
will be the file that specifies your system datasources.
- Compile and install unixODBC with
make; make install. This step can be quite lengthy depending
on the speed of your machine.
- Update /etc/ld.so.conf to see your newly installed unixODBC distribution. Edit /etc/ld.so.conf and add
a line containing
/usr/local/lib to the end of the file.
- Update the run-time link bindings by running
- At this point, unixODBC should be installed properly. After installing a database server, we will be able
to run a quick test to verify that unixODBC is working. For future reference, the utility to
do this is /usr/local/bin/isql.
isql will try to connect to datasources listed in /etc/odbc.ini.
Optionally, unixODBC may be installed from a package format, such as RPM or DEB.
Finally, since ihtml looks for /usr/lib/libodbc.so as the ODBC Driver Manager, we must create a couple of symlinks. Execute:
ln -s /usr/local/lib/libodbc.so.1 /usr/lib/libodbc.so
ln -s /usr/local/lib/libodbcinst.so.1 /usr/lib/libodbcinst.so
A DSN (Data Source Name) is how iHTML refers to a particular database in
a database server. You need to create entries in the odbc.ini file
for each database you want to access. You should have
unixODBC 1.8 or better installed. Older versions of unixODBC have a bug where
unixODBC won't find the info in the main odbc.ini unless the file
.odbc.ini (with leadning dot) is found in the web server user's home directory.
Often, httpd is running as user "nobody", and by default nobody
has no home dir.
Correct format of a MySQL DSN
Driver = /usr/lib/libmyodbc.so
Host = 127.0.0.1
Server = 127.0.0.1
Database = some_database
Port = 3306
Flags = 131072
Options = 131072
The above defines a DSN called mysql_dsn which points to the database some_database on
the local MySQL server (running on port 3306, the default for MySQL).
In the above example, you would reference data in the some_database database by using DBNAME="mysql_dsn"
in your iHTML database access tags.
The reason for using both
Host = and
Server = is to account for a
situation in some drivers where the two settings are used interchangably. When setting up DSNs, it's
more reliable to simply include both settings, and set them to the same value. In addition, it is
recommended that you use only IP addresses in for the Host/Server setting, as fully qualified domain
names have been problematic in the past.
Options: this particular set of flags puts MyODBC into safe
mode which allows the use of the INDEX and INDEXED directives on the iSQL and iSQLFETCH set of iHTML tags.
Correct format of a Postgres DSN
Driver = /usr/local/lib/libodbcpsql.so
Database = postgres_database
Servername = 127.0.0.1
Protocol = 6.4
ReadOnly = No
More information about DSN's for various odbc drivers can be found at
MySQL is a popular choice for use with iHTML. It should be no problem to do a source or RPM install of MySQL,
both of which are explained in detail at the MySQL site. If you are planning
to compile MyODBC (as opposed to installing it via a RPM), you will most likely want to do a source install of MySQL
as well. We have seen a problem in which everything appears to be working with mySQL and iHTML except no data appears
to be returned to iHTML from mySQL. In this case use the LoadFile directives to preload the mySQL client libraries.
See section 188.8.131.52 for more details on how to do this. We also recommend running mySQL using UNIX sockets instead
of TCP sockets as the mySQL tcp sockets do have bugs that show up under load.
If you have a relatively new install of MySQL then you shouldn't have
too much trouble getting the latest MyODBC driver compiled. Just install the RPM that
came with your O/S if one is available, or install a complete set of MySQL Server, Client, and
MyODBC RPM's that are provided by mysql.com. If you prefer to install from source, just read
the INSTALL file carefully when you untar the MyODBC source.
Brief instructions for a source install of MyODBC. These instructions are for version 3.51.xx of MyODBC, so
substitute version numbers where appropriate.
- Grab the latest source from the MyODBC section of the MySQL site. Untar the MyODBC source to a temp directory:
tar zxvf MyODBC-[version].tar.gz.
- Follow the instructions found in INSTALL; refer to
./configure --help if you want to see all
- Assuming that the MySQL client and it's headers are installed to /usr/local, and unixODBC is installed to /usr/local, configure the MyODBC source:
./configure --prefix=/usr/local --with-unixODBC=/usr/local --with-mysql-libs=/usr/local/lib/mysql --with-mysql-includes=/usr/local/include/mysql --disable-thread-safe
make; make install to install MyODBC.
Postgres is another very popular DBMS for use with iHTML. Postgres is easily installed via packages, and that
is the recommended method for getting it up and running. The latest 8.1.x release of Postgres is recommended.
The Postgres ODBC driver that comes with unixODBC is known to work well. There is also a psqlodbc driver that has improved ODBC support.
Postgres Quick Notes
These quick notes are not complete, but may offer some help in getting Postgres working with iHTML.
These notes apply to Linux/Intel/glibc 2.0/2.1 and unixODBC 1.8.7 or 1.8.8 though they should apply to
later versions of unixODBC as well.
First make sure that Postgres is running:
ps -aux |grep postmaster
Once we know it's running we need to make sure that we can use it.
Switch to the postgres account and try a Postgres command, create a test database:
su - postgres
We also need to create a user, and set a password.
You will be asked to determine a usernumber and the privelages of the
account, if it is not an administrative user, you can also create a new
database that the user can use.
psql -d template1 -c "ALTER USER WITH PASSWORD "
If you created an administrative user you can exit from the su - postgres
Now, test the database using the psql command:
You will be prompted for a username and password. If this works you're all ready for the next step.
You can use the
isql utility that comes with unixODBC to test the ODBC connection, the format is:
isql looks to odbc.ini for datasources. odbc.ini is typically found in /etc. Depending on how
unixODBC was built, you may find your odbc.ini in /usr/local/etc/ or elsewhere (if
used when unixODBC was compiled). If problems with finding the datasource name persist, also check for
a .odbc.ini file in the home directory of the user you are currently running as. .odbc.ini defines user
datasources (odbc.ini defines system datasources), and depending on the name of the datasource you're trying
to access, there could be a name conflict between the user and system datasources. i.e. if both odbc.ini
and .odbc.ini contained a
If things aren't working make sure that:
Port = 5432 (the default except on Colbalt machines)
Driver = (/usr/local/unixODBC/lib/libodbcpsql.so)
Setup = (/usr/local/unixODBC/lib/libodbcpsqlS.so)
iHTML supports anything with a working ODBC driver. If you are unsure of whether iHTML will be able
to talk to your DBMS, you can test it out by first installing unixODBC, creating a datasource, and then testing
the connectivity with the
isql utility that comes with unixODBC. If isql can successfully connect
and query your database, it is highly likely that iHTML will be able to as well.
The following changes need to be made to the Netscape configuration files:
- Add line
Init fn="load-modules" funcs="send-ihtml,init-ihtml" shlib="[path to ihtml.so]"
Must be inserted before
- Add line
Service method="(GET|HEAD|POST)" type="text/ihtml" fn="send-ihtml" between the
<Object name="default"></Object> tags, after another
- Add line
type=text/ihtml exts=ihtml Somewhere in the file (end of file is fine).
- Change the api string to
The installation of iHTML itself should be relatively stright forward as long as the other componenets
are up and running correctly.
Just to recap, verify that Apache, unixODBC, some DBMS (Postgres or Mysql perhaps?), and an appropriate ODBC
driver are installed.
- First, proceed to http://www.ihtml.com/download/ to download the iHTML Installer. If you have already purchased iHTML
we recommend you use the My iHTML site to get the latest version.
- Untar the installer[platform].tar.gz to a temp directory.
- Change into the
installer directory, and execute
- Answer the questions asked in the script to start the Inline Installer Session. If there are any system libraries that are missing at this time, you will be notified.
- You will be given a URL to open once the installer has launched. Browse to this URL to continue, and follow the step-by-step instructions.
This section attempts to address common issues that occur after installing iHTML. Unless specifically noted, all items in this section pertain to the Apache Web Server.
- Apache apears to start up fine, but nothing is working!
This situation is seen predominantly on Apache servers configured to use any combination of mod_ssl, mod_perl, and php4_module, though other modules not listed here could cause the same sort of problem. Essentially, depending on which modules are loaded, and where in the Apache configuration file they are loaded, Apache may lose track of where certain file are, thus causing iHTML not to start up correctly (and consequently break everything else). The fix is to use LoadFile commands to ensure that iHTML will find the files it needs.
Try adding the following lines to your Apache configuration file (after the
LoadModule ihtml_module /usr/ihtml/ihtml.so line, and then do a complete stop and start of the Apache server.
If using mySQL add the following
If using Postgres add the following
Various SSL modules may require the following to be added
Potentially, if you have an older version of unixODBC (<= 1.8.10), you may need to add the following lines as well:
All of the libraries mentioned should be part of the unixODBC distribution. Remember to do a complete stop and start of the Apache server --
apachectl restart is not sufficient.
- Everything is dumping core when I try to use ODBC driver x!
There is a bug in the glibc library under Linux that prevents a non threaded application to dlopen/dlclose a module that is linked with -lpthread without dumping core. Basically, if any of your ODBC drivers have been linked with pthreads, you could encounter this problem. Please contact Inline Support if you are faced with this problem.
If you are using Raven-SSL for your secure server, you will need to do
something special. Raven-SSL comes with its own source tree of Apache,
which is already modified for Frontpage Extensions. Because Frontpage
Extensions change the way Apache handles API's, you'll need to modify
the currentversion.nv file in the
to include the following:
It is sufficient to simply append the above line to the end of currentversion.nv and
restart the server.
If using FreeBSD please note that the build instructions for myODBC on
FreeBSD are not correct. Also, the admin server will also not start unless you
create a symlink in /usr/lib
libc.so.3 -> libc.so.4
This section contains older, uncategorized documentation that is not being actively maintained. The
following sections are provided as reference, and may not be up to date.
The following was contributed by Steve Freitas (email@example.com)
The following describes a certain setup and provides an example of how
to get iHTML talking to a mySQL database on a remote machine. Using
MySQL server 3.22.27 on the remote machine. On the local machine use:
MySQL-client-3.23.6-1.i386.rpm, MySQL-shared-3.23.6-1.i386.rpm, and
Make sure you have both HOST and SERVER in the iodbc.ini file The
problem is that unless libodbc sees a /usr/local/etc/odbc.ini file
(notice, *not* iodbc.ini), it will still access local databases but
won't access remote databases. So here's what solved the problem:
ln -s /usr/ihtml/iodbc.ini /usr/local/etc/odbc.ini
The details of how to install iHTML are now handled by an automated installer, which is viewed through a web browser. Some additional details are found here if you with to tweak your settings.
We now need to add a bunch of things to the /etc/httpd/conf/httpd.conf
file. Add the following in the requisite places. Different versions
of Apache may need slightly different syntax to that shown below.
Basically look to see how other similar extension packages may have
LoadModule ihtml_module /usr/ihtml/ihtml.so
AddType text/ihtml .ihtml .ihtm .iht .inc
AddHandler ihtml-handler .ihtml
Alias /ihtml_config/ "/usr/ihtml/htdocs/ihtml_config/"
Alias /ihtml/ "/usr/ihtml/htdocs/ihtml/"
Alias /merchant/ "/usr/ihtml/htdocs/merchant/"
Allow from all
You'll also want to modify the following line to allow "index.ihtml"
to be used as a directory index (all on one line):
DirectoryIndex index.shtml index.html index.htm index.ihtml
index.phtml default.htm default.html
Apache config file formats starting with apache 1.3.4 the apache
conf file layout has varied wildly. Since it is partially a compile
time setting, and also can be adjusted at runtime with config settings
in httpd.conf, there are many variants out there, and specific
distributions vary in default config from each other.
In general, the following things have to happen in the config files (httpd.conf, or possibly srm.conf for older Apache servers):
- ihtml.so has to be brought into memory with a LoadModule command file extensions such as .ihtml and .ienc etc have to be associated with ihtml through use of an AddHandler command. This is a minimalist approach to getting ihtml to run.
- On some operating systems a
LoadFile command is also needed to bring the ODBC driver manager into memory as well explicitly. Most times this is redundant but it does not hurt to include this line.
- Other additional things the installs attempt to accomplish are making some directory mappings in httpd.conf (access.conf in older versions of Apache) to point to the three htdocs directories which ihtml installs (merchant, ihtml_config and ihtml).
- Note: beware of lines like
ClearModuleList and the way they affect lines related to iHTML.
- Beware also of conflicts you may create when mapping file extensions to iHTML that may have to be unmapped from something else.
- Beware of configuration files that do not match the version of apache they are being used with. This occurs when upgrading apache from an earlier version and preserving the config info. Often this produces strange behaviours and the relavent sections of the old files should be pasted into a fresh correct one manually when upgrading apache. It is also possible to convince apache to look for the files by their old names--do not attempt this unless you understand what you are doing. Even with this method, newer directives will still be missing from the files, and starting with a fresh set is Inline's recommendation.
- Beware of the command
apachectl restart when testing different apache configurations. Because the
restart command only sends a SIGHUP to the httpd process, some previous configuration information may be retained, thus not giving a reliable test of your current configuration. Using
apachectl stop followed by
apachectl start is more reliable for testing configurations.
You should be able to stop and start the webserver, and you'll be all
done. However, if you do this and you go to
http://servername.com/ihtml_config/ and the browser attempts to
download .ihtml files as a file, check your /var/log/httpd/error_log
[error] Cannot remove module s_apache.c: not found in module list
Solution: If you do, add the following to the /etc/httpd/conf/httpd.conf file after the ClearModuleList line but
at the bottom of other similar AddModule lines:
[error] Cannot remove module mod_ihtml.c: not found in module list
Solution: If you do, add the following to the /etc/httpd/conf/httpd.conf file after the ClearModuleList line but
at the bottom of other similar AddModule lines:
[error] libpthread.so shared object not open
Solution: Something is compiled against pthreads and it shouldn't be. Recompile that module
without pthreads support.
Can't locate API modules structure 'ihtml_module'. Undefined symbol ihtml_module
Solution: You likely have a ClearModuleList in your httpd.conf file. Ensure the line
LoadModule ihtml_module /usr/ihtml/ihtml.so
is before the ClearModuleList and that
is after AddModule mod_so.c in the httpd.conf file.
[warn] Loaded DSO /usr/ihtml/ihtml.so uses
plain Apache 1.3 API, this module might crash under EAPI! (please
recompile it with -DEAPI)
Solution: This happens if Apache is compiled with EAPI. This can happen when
compiling in mod_ssl. iHTML doesn't use an EAPI functions and does not require
EAPI. It will not crash or cause a problem so this warning can be safely
[error] dl-close.c:123....ASSERTION:new_opencount==0 failed
Solution: This is a bug in the glibc libraries and has to do with
pthread support in one of the other modules being loaded. It could
be unixODBC or if using PHP it could also be that. Recompile the offending
module without pthreads support.
The following is a description from Drew Whittle
(firstname.lastname@example.org) on the steps to get iHTML working with
Postgres as the database server.
Red Hat 6.0 comes with versions of Apache (1.3.6) and Postgres (6.5.1)
that are configured correctly to use iHTML. We recommend updating the
version of Postgres to at least 6.5.2 as there is a small bug in
earlier versions that affects the iHTML Merchant.
Assuming that you have used the Red Hat tools to install Postgres and
Apache these are the steps required to get iHTML working using
UnixODBC. (Use version at least version 1.8 it has a Postgres ODBC
- untar (tar zxvf ihtml218.tar.gz) iHTML version 2.18
- change into the ihtml package directory (cd ihtmlpackage)
- run the install script (./install)
- answer the questions
iHTML 2.18 is now installed, before you go any further do the
- get the latest version of UnixODBC (http://www.unixodbc.org/)
- untar (tar zxvf unixODBC-1.8.tar.gz) UnixODBC
- change into the unixODBC directory (cd unixODBC-1.8)
- Run the Configure script (./Configure --enable-gui=no) [This will allow you to compile unixODBC without the GUI tools, which aren't needed on a server, your not running X-Windows on your server are you?! (Security Hassles)]
- Compile the sources (make)
- Install UnixODBC (make install)
- change into the /usr/lib directory (cd /usr/lib)
- Create a symbolic link to the UnixODBC Driver Manager (ln -s /usr/local/lib/libodbc.so libiodbc.so)
- run ldconfig just in case it's needed. (/sbin/ldconfig -v)
- If you can't talk to Postgres then you may not have setup the
database server to listen on a port. (add -i to the startup command
line) - we have found no need to have /etc/odbc.ini or .odbc.ini when
using iHTML/Postgres/UnixODBC - If when you type ps -ax | grep post
you do not see a process called "postmaster" then the Postgres back
end is not running. (Probably due to not doing the initialization of
In the httpd.conf file, there is a setting for MaxRequestsPerChild.
Change to 1000 from the default 100.
Example ODBC.INI for Postgres (/usr/local/etc/odbc.ini):
Driver = PostGres
Database = mercdemo
Servername = localhost
Username = mercdemo
Password = mercdemo
Port = 5432
Protocol = 6.4
ReadOnly = No
There are a few modes PGP can work in and you need to understand what PGP
actually does in order to get it to work with iHTML successfully.
iHTML can make use of PGP only as a "batch convertor". This means iHTML
tells PGP to run, and gives it the name of a file to encode, and the method
to use to encode it.
Depending on the encoding mode selected by command line arguements, PGP may
need to know the "user" invoking the command in order to determine what key
to use to encrypt or decrypt the file.
If PGP is not able to determine this due to being logged in as a particular
user, it prompts for the information. Clearly this is
not going to work when run as part of a server process. Therefore, having
the webserver running as the user necessary is the only choice.
PGP must also be supplied with all parameters necessary using the args=
directive of the icgi tag, such as which mode to operate in, the key to use
if non-public key encoding or signing is desired, the file to operate on,
etc. If PGP is not supplied all necessary arguement, it will prompt for the information.
Programmers must be aware of this and ensure PGP has all the information it
needs to run in an unattended manner.
Unix File System Permissions: Check them all. Make sure that httpd can
access ihtml.so, and that the unixODBC libs are accessible. You need
execute permissions on them as well
MySQL Grant tables: If you have a user whose host access is setup to
be '%' -- i.e. any host, trying to connect from 'localhost', it won't
work, though connecting from any non-localhost machine will. This is
probably a bug, and may be fixed in a newer version of mySQL. If you
want a user to be able to connect from any server at all, create two
user records for them, one with host='%' and another with
Error 900's on ihtml_config utility pages: chown and chmod all the webspace to the
iHTML loads, but files come through without parsing: Check for a
clearmodulelist line in httpd.conf file - either move the 2 ihtml hook
lines after that line OR make an additional addmodule for ihtml like
the others after the clear line OR remove or comment out the clear
Null shows up as the request path in the logs from an apache
installation and results in blowups or 404's: set frontpatch true in
currentversion.nv - the only time the null shows is when frontpage has
contaminated the apache setup, this persists adamantly even after the
frontpage modules are removed from the system until the server is
downloaded fresh and rebuilt. Note: the secure server Raven also
contains the frontpage extensions although they don't say it all the
myODBC driver only looks on localhost for the server: Make sure the
lines HOST=(ip or name) AND SERVER=(ip or name) are both present in
the dsn setup, some versions of the driver look for different lines
and it is simpler just to add both than debug it.
iHTML loading error of "SQLDataSources" symbol not found (or similar
wording): The version of the odbc driver manager (iODBC or unixODBC)
is very old, update to iodbc 2.5 and on or any unixODBC version
(preferably 1.8 or above) Note: Any other missing symbol starting with
"SQL" indicates the driver manager is missing altogether.
iHTML loading error of "sigset" symbol not found (or similar wording):
Get the 2.18 release version of the ihtml.so file this was a corrupt
beta version that some people may have.
iHTML loading error of "__bzero" symbol not found (or similar
wording): You have the wrong version of iHTML for that platform -
glibc/libc version mismatch
iHTML can't find the odbc driver manager: ihtml looks for the driver
manager to exist as /usr/lib/libiodbc.so This may either be a real
file or a link to another real file. If the driver manager is iodbc
(libiodbc.so) then there are no other required files for it to
operate. Just make sure that file exists and is in that location. If
the driver manager is unixODBC (libodbc.so) then the files libini.so,
liblst.so, liblog.so, and libodbcinst.so must also be accessible.
This normally means existing in /usr/lib, however, if the environment
has a variable related to "LD" the path to these .so files may be
somewhere else. Note: unixODBC places the .so files in /usr/local/lib,
so the library path may be adjusted to "see" them there, or copy,
move, or make links to them in /usr/lib If you are having problems
with odbc, make sure that the link /usr/lib/libiodbc.so is pointing to
the correct version of libodbc.so. If you installed a recent version
of unixODBC then this means make sure that libiodbc.so points to
/usr/local/lib/libodbc.so. Also, you may need to ensure that all
drivers and required libraries that your drivers need are in a
location where ld can find them. ie. the LD_LIBRARY_PATH specifies
where to find them or /etc/ld.so.conf has the required directories
in it. On some systems, /etc/ld.so.conf may be called
/etc/ld-elf.so.conf. This file is normally read by default by
ld.so and ldconfig.
What pieces of unixODBC are actually needed ?
The .so files mentioned above are all that is needed to actually
function. A driver .so file is also desirable so connections to a
database can actually be made, but odbc calls can be made and odbc
will load without it. There are many other tools and gui config
components available, but these are not actually needed to make odbc
function. The configuration information may be kept in a couple
places: .odbc.ini - required even if empty (user DSN's for the given
user and must be in the home directory of the user the web server is
logged in as) /etc/odbc.ini - system DSN's - not strictly required
/etc/odbcinst.ini - registered drivers The above are simply text files
with an obvious format once opened - when editing without the gui
config tools refer to the driver docs for what settings apply to that
driver - in general, driver, host and port apply to almost every one.
Driver is either a reference to a section in odbcinst.ini for that
driver, or may simply be the path to the driver .so file for that
What Permissions Are Needed?
iHTML runs as the webserver user, so those permissions apply.
iHTML must be able to find and read the registry tree to startup. Some
features there also require write access to the registry tree to make
settings persist. iHTML must have read access to the webspace to parse
and serve the files iHTML must own and have write and create access
(write to the dir) to work correctly with the admin GUI Permission to
query and change the databases used by the GUI must also exist. This
includes the schedule, itest and merchant DSN's.
What actually needs to be in the registry?
in hkey_local_machine/software/inline/ihtml/currentversion.nv the
following three lines MUST appear API KEY SN for ihtml to start,
everything else will come from internal defaults if the files or
settings are missing. The registry is currently based in
/usr/ihtml/registry, this will be moving to /etc/registry in the
iMAIL, iHTTP or iPOP don't work: In the /etc/services file there
needs to be lines like this following (they are usually in numerical
order in the file). Not a bad idea to double check this even if they
Common Unix Tools
Here are some common tools that can be used to debug reason why iHTML
or ODBC may not be working correctly. These are GNU tools and really
only default on BSD and Linux systems.
- compiles a list of shared libraries on the system for use by the dynamic linker ld.so - uses /etc/ld.so.conf as a list of directories to scan for libraries.
- on some bsd machines, /etc/ld-elf.so.conf is used for elf libraries (most modern libraries are ELF)
- usage: ldconfig -v
- this scans all directories listed in ld*.so.conf for libraries - usage: ldconfig -p
- this prints out the current list of library names and complete paths
- usage: ldconfig -m /path/to/libs/
- scan /path/to/libs/ and merge list of libraries into existing list
- NOTE: bsd only
- usage: ldd filename.so
- shows a list of libraries which filename.so depends on to load. -
useful to determine why something isn't loading and what exact library
something is using. (eg. you have two versions of some library and you
want to see which version some program is using when you run it)
- example 2: you get an SQL Error when using a certain DSN saying that:
the a file is not found and you know that file
exists. Probably the problem is a driver is
dynamically linked to a library which cannot be
found by ld. Use ldd on the driver to find out what
libraries it depends on and which ones are missing.
Links for More Info on ODBC related setup instructions
MySQL ODBC Driver Problems
For RPM installed versions of MySQL and the MyODBC driver provided at
library.freeodbc.org the following error sometimes happens:
Can't open socket /tmp/mysql.sock
Some RPM installtions put mysql.sock in /var/lib/mysql/mysql.sock.
This can be worked around in two ways. Either do "ln -s
/var/lib/mysql/mysql.sock /tmp" or in all your MySQL DSN's put "SOCKET
Many people have problems with myodbc version >= 2.50.xx. We suggest
upgrading to a newer version of the driver >= 3.51.00.
Configuring Apache to Restrict iHTML to certain VirtualHosts
Apache can be configured to only enable iHTML with certain
VirtualHosts that you specify. By only placing AddHandler
ihtml-handler ... lines in certain VirtualHost configurations only
those VirtualHosts will be able to access ihtml.
If you specify AddHandler ihtml-handler ... outside of a VirtualHost
block, then all domains running off of that server will have access to
03/01/2007 - Updated information on ihtml, apache, unixodbc, myodbc.
09/19/2000 - Added information about glibc pthreads bug.
09/17/2000 - Added to Apache Configuration Notes; Added Post iHTML Installation Troubleshooting section.
09/14/2000 - Added information about PGP.
08/10/2000 - Minor fixes to Postgres datasource examples.
07/28/2000 - Added Postgres Quick Notes; reformatted Apache configuration notes.
07/17/2000 - Initial edit and reformat of existing docs.