Postgres

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:

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
createdb 

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.

If you created an administrative user you can exit from the su - postgres (type exit)

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 --sysconfdir was 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 [test] datasource.

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)

Other databases

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.

Netscape Web Servers

The following changes need to be made to the Netscape configuration files:

obj.conf

1. Add line Init fn="load-modules" funcs="send-ihtml,init-ihtml" shlib="[path to ihtml.so]" Must be inserted before fn="NSServletEarlyInit" and fn="NSServletLateInit" lines.
2. Add line Service method="(GET|HEAD|POST)" type="text/ihtml" fn="send-ihtml" between the <Object name="default"></Object> tags, after another Service tag.

mime.types

1. Add line type=text/ihtml exts=ihtml Somewhere in the file (end of file is fine).

iHTML Registry

1. Change the api string to NSAPI.

Installation of iHTML

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.

1. 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.
2. Untar the installer[platform].tar.gz to a temp directory.
3. Change into the installer directory, and execute ./setup
4. 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.
5. 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.

2.3.1. Post iHTML Installation Troubleshooting

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.

2.3.1.1. Post iHTML Installation Troubleshooting

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.

LoadFile /path/to/libodbc.so
LoadFile /path/to/libodbcinst.so

If using mySQL add the following

LoadFile /path/to/libmysqlclient.so

If using Postgres add the following

LoadFile /path/to/libodbcpsql.so

Various SSL modules may require the following to be added

LoadFile /path/to/libssl.so
LoadFile /path/to/libcrypto.so

Potentially, if you have an older version of unixODBC (<= 1.8.10), you may need to add the following lines as well:

LoadFile /path/to/libini.so
LoadFile /path/to/liblog.so
LoadFile /path/to/liblst.so

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.

2.4. System Specific Information

Important Raven-SSL Information

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 /usr/ihtml/registry/hkey_local_machine/software/inline/ihtml directory to include the following:

frontpatch              true

It is sufficient to simply append the above line to the end of currentversion.nv and restart the server.

Important FreeBSD Information

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

Odds and Ends

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.

Using mySQL on a Remote Machine using iODBC

The following was contributed by Steve Freitas (steveadept@aol.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 MyODBC-2.50.28-1.i386.rpm.

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

Installing the iHTML Application Server

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.

Modifying httpd.conf

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 been added:

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

<Directory /usr/ihtml/htdocs>
  Order allow,deny
  Allow from all
</Directory>

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 Configuration Notes

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 for:

[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:

AddModule s_apache.c

[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:

AddModule mod_ihtml.c

[error] libpthread.so shared object not open

Solution:  Something is compiled against pthreads and it shouldn't be.  Recompile that module
without pthreads support.

[error]
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 

AddModule mod_ihtml.c

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 
ignored.

[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.

Using iHTML with Postgres

The following is a description from Drew Whittle (drew@auctionability.com) 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 driver fix).

1. untar (tar zxvf ihtml218.tar.gz) iHTML version 2.18
2. change into the ihtml package directory (cd ihtmlpackage)
3. run the install script (./install)
4. answer the questions

iHTML 2.18 is now installed, before you go any further do the following:

1. get the latest version of UnixODBC (http://www.unixodbc.org/)
2. untar (tar zxvf unixODBC-1.8.tar.gz) UnixODBC
3. change into the unixODBC directory (cd unixODBC-1.8)
4. 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)]
5. Compile the sources (make)
6. Install UnixODBC (make install)
7. change into the /usr/lib directory (cd /usr/lib)
8. Create a symbolic link to the UnixODBC Driver Manager (ln -s /usr/local/lib/libodbc.so libiodbc.so)
9. run ldconfig just in case it's needed. (/sbin/ldconfig -v)

Notes:

- 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 the database)

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):

[mercdemo]
Driver     = PostGres
Database   = mercdemo
Servername = localhost
Username   = mercdemo
Password   = mercdemo
Port       = 5432
Protocol   = 6.4
ReadOnly   = No

Using iHTML with PGP

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.

Trouble Shooting

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 host='localhost'.

Error 900's on ihtml_config utility pages: chown and chmod all the webspace to the apache webuser

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 line.

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 time outright.

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 driver.

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 future.

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 work.

smtp     25/tcp
http     80/tcp
pop      110/tcp

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.

ldconfig

• 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

ldd

• 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

http://www.unixodbc.org/unixODBCsetup.html
http://www.unixodbc.org/odbcinst.html
http://www.unixodbc.org/myodbc.html

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 = /var/lib/mysql/mysql.sock".

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 iHTML.

Document History

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.