To install LXP, you must have the Apache web server installed and configured to support mod_so.
This is the Apache Shared Object module. If you have not built Apache with this module, you will need to reconfigure it,
making sure to include the - -enable-module=so configuration option before compiling.
Warning
If you choose to manually compile Apache, be sure that you remove any existing Apache RPMs first. You can
usually identify these with the rpm -qa |grep apache command.
If Apache is installed, and the Shared Object module is enabled, you may insert the CD included with this book, mount
it, and proceed with the installation. You will need to be logged in as root in order to successfully
install LXP, since it requires access to system-level files and directories.
There are two ways to install LXP as of Version 0.8; you may use the lxpinstall.sh
script, found in the lxp directory on the CD, or you may install it manually. The
lxpinstall.sh script is intended to both install the required LXP files and to configure
your httpd.conf file to load and enable the LXP module.
If you encounter any errors during the installation from lxpinstall.sh, see the following
section about manual configuration.
The lxpinstall.sh script is extremely straightforward. On a fresh system, the only
option you should be prompted to respond to is at the end of the script, when it asks you whether or not to automatically
restart Apache (as must be done, to enable LXP). You may run it again afterward in case something goes wrong, though it
will prompt you whether or not certain files should be overwritten.
Example 13-1 changes to the lxp directory on the CD (mounted
in /mnt/cdrom, in this case), and runs the lxpinstall.sh file.
Example 13-1. Installing LXP with lxpinstall.sh
[root@host root]# cd /mnt/cdrom/lxp
[root@host lxp]# ./lxpinstall.sh
===================================================================
Thank you for installing Command Prompt LXP, 0.8.0.
Copyright (c) 1999-2001, Command Prompt, Inc.
See the LICENSE file for licensing restrictions.
==================================================================
[cmd] Checking for PostgreSQL libs (this may take a moment) ...
[cmd] Found PostgreSQL libpq library.
[cmd] Using apxs: '/usr/local/apache/bin/apxs'
[cmd] Using '/usr/local/apache/libexec/' for shared object file
==================================================================
[cmd] Installing 'liblxp.so'
[activating module `lxp' in /usr/local/apache/conf/httpd.conf]
cp lib/liblxp.so /usr/local/apache/libexec/liblxp.so
chmod 755 /usr/local/apache/libexec/liblxp.so
cp /usr/local/apache/conf/httpd.conf /usr/local/apache/conf/httpd.conf.bak
cp /usr/local/apache/conf/httpd.conf.new /usr/local/apache/conf/httpd.conf
rm /usr/local/apache/conf/httpd.conf.new
==================================================================
[cmd] Using '/usr/local/apache/conf/httpd.conf' for configuration
[cmd] Backing up original configuration file...
/usr/local/apache/conf/httpd.conf -> /usr/local/apache/conf/httpd.conf.lxp_backup
[cmd] Backing up original configuration file...
/usr/local/apache/conf/srm.conf -> /usr/local/apache/conf/srm.conf.lxp_backup
[cmd] Adding LXP directives to httpd.conf...
==================================================================
[cmd] Installing 'lxp.conf' into /usr/local/cmd/etc ...
conf/lxp.conf-dist -> /usr/local/cmd/etc/lxp.conf
==================================================================
[cmd] Re-start Apache with '/usr/local/apache/bin/apachectl'? (y/n) y
/usr/local/apache/bin/apachectl stop: httpd stopped
/usr/local/apache/bin/apachectl start: httpd started
[cmd] Command Prompt LXP 0.8.0 successfully installed.
Note: In case there is a problem with your httpd.conf reconfiguration, remember that LXP creates a
backup of your original configuration called httpd.conf.lxp_backup in the same directory as your
httpd.conf before making any modifications.
You may receive the following error when running the lxpinstall.sh script:
[cmd] ERROR: LXP requires Apache be configured with Shared Object support,
[cmd] but we couldn't find Apache's apxs script.
[cmd] Please make sure it is in your path, if you know mod_so is enabled.
[cmd] exit error 1
This error indicates that apxs, the Apache Extension tool, could not be found on
your system. It is typically found in /usr/local/apache/bin, though it may be missing if your Apache
web server was not built with mod_so support enabled, or if you have not installed the
apache-devel RPM for your system. If you know it is installed, be sure that the
directory it resides within is in your PATH environment variable.
Alternatively, you may get an error message similar to the following:
If you are not using a configuration file with a standard name (i.e., httpd.conf ), you
will need to manually configure it. See the next section instructions.
This section describes how to manually install LXP if the lxpinstall.sh script
does not work for you. If you've already installed LXP successfully through this script, you may skip this
section.
There are three steps to manually installing LXP:
Installing the LXP shared-object file
Installing the LXP configuration file
Configuring Apache's httpd.conf file
The liblxp.so file (located in the /lxp/lib directory on the CD) must be
copied to the directory that your Apache web server is configured to load external modules from. This is typically
/usr/local/apache/libexec for manual installations of Apache, and
/etc/httpd/modules for RPM installations. Note that this directory varies wildly, and may be
different in your distribution. You should be able to install into this directory through the use of
apxs, however, with the following syntax:
apxs -i -n module -a shared_object
Example 13-2 demonstrates using the apxs script to install and
configure the liblxp.so file directly into Apache's module directory.
Example 13-2. Manually installing liblxp.so
[root@host lib]# apxs -i -n "lxp" -a lib/liblxp.so
cp lib/liblxp.so /usr/local/apache/libexec/liblxp.so
chmod 755 /usr/local/apache/libexec/liblxp.so
[activating module `lxp' in /usr/local/apache/conf/httpd.conf]
If you do not have PostgreSQL installed, the libpq.so.2.2 file (also located in the
/lxp/lib directory on the CD) should be copied to the /usr/local/cmd/lib
directory. A symbolic link named libpq.so.2 should also be created to point to this file. If you
have not run lxpinstall.sh, you may need to create this directory. Example 13-3 demonstrates this process.
Next, the lxp.conf file must be installed in the /usr/local/cmd/etc
directory. This is the configuration file for LXP 0.8, discussed in detail in the next section. The distributed
configuration file is found in the lxp/conf directory on the CD, and is named
lxp.conf-dist. Copy this file to /usr/local/cmd/etc from the
lxp/conf directory on the CD, as shown in Example 13-4. If you have
not run lxpinstall.sh at all, you may need to create this directory. Be sure to rename it from
lxp.conf-dist to lxp.conf !
A line similar to the first line in Example 13-5 should already exist in your
httpd.conf file. You must add index.lxp as a value to this
directive if you wish for Apache to automatically look for an LXP index in a directory request.
The second line must be added from scratch. This AddType directive should be
entered exactly as it is shown in Example 13-5. This line enables the LXP module to
process files ending in .lxp.
It is generally not important where you put these last two directives within the httpd.conf
file, though you may wish to place them with similarly named directives that already exist, to keep the configuration
file organized.
Once you have finished, you must restart Apache for the changes to take effect. This is typically done with either
the apachectl command, or the httpd service script.
After installing LXP, you will find the lxp.conf file in the
/usr/local/cmd/etc directory. This file defines the database settings with which LXP connects to the
PostgreSQL database for persistent connections. The file also contains a pair of debugging options.
The lxp.conf file is a simple configuration file using common conventions. The format of this
file can consist of comments, directives, and associated
values for each directive.
Comments are always prefixed with a hash mark (#). They can be at the beginning of a
line, or follow a directive and value. They are totally ignored by LXP when the configuration is loaded, and are only
useful for remembering notes on why directives are set and what possible options there may be. You can add your own
comments without harming the functionality of LXP as long as you remember to precede the comment with a hash mark
(#).
Directives have a very basic affect upon the functionality of LXP. They typically start at the beginning of a line,
have a name (without spaces), and are followed by their associated value. The directive name defines a behavior to affect,
while the value sets how to affect that behavior. Some directives accept multiple values, which are separated by either
tabs or spaces. Here is example syntax:
# Here's an example directive.
MyDirective SomeValue # MyDirective defines some arbitrary value.
You may never need to make serious alterations in your lxp.conf file, but it's a good idea to
know what it is, and what it does, in case you ever need to change one of these basic behaviors. As of LXP 0.8, the
lxp.conf file is broken up into two sections; general settings and database settings.
The first two directives under the General settings section are Debug and MaxIncludeDepth:
#######################
# General LXP settings.
#######################
Debug No # (Yes|No)
MaxIncludeDepth 15 # (Number)
Setting the Debug directive to Yes adds a
debugging-header to the top of all LXP documents. This can be useful for tracking down unexplained behavior of LXP files
and included scripts. The debug header includes the name of the LXP document requested, any cookies found for the given
domain, any GET/POST variables that are passed, and maximum depth inclusion.
The maximum depth inclusion is the highest number of includes LXP will traverse
down before stopping and displaying an error. This is used to prevent accidental infinite
includes (e.g., a.lxp includes b.lxp, which
includes a.lxp). Set this value with the MaxIncludeDepth directive.
The default value is 15.
Note: The value assigned to MaxIncludeDepth does not limit the total number of files
that can be included within a document. It describes only the deepest level LXP can go in
sub-inclusions (e.g., a.lxp includes b.lxp, which
includes c.lxp, which includes d.lxp, etc).
The next six directives pertain to database connectivity with PostgreSQL. Most of the default options are usable on
most systems, but you may wish to modify these if you have special needs for your PostgreSQL installation:
#############################################
# PostgreSQL persistent connectivity options.
#############################################
UseDb No # (Yes|No) Set to Yes if you wish to connect to the database.
DbName template1 # The database to use. By default, "template1".
DbHost localhost # The database host to use. By default, "localhost".
DbPort 5432 # The port to connect to PostgreSQL on.
DbUser postgres # The username to connect with. By default, "postgres".
DbPass # The password to connect with. By default, empty
If you wish to enable LXP's persistent connections to a database, set UseDb to
Yes. If set to No, you will still be able to use the
Direct SQL Interface to dynamically open up connections (see the Section called Including SQL Content"), but you will incur the cost of
a new PostgreSQL backend connection for each connection request.
The remaining options—DbName, DbHost,
DbPort, DbUser, and
DbPass—should be familiar to anyone with experience connecting to PostgreSQL. The
defaults will usually work fine, but you might wish to change them if you have special needs (for example, if you wish to
store your data on a separate database server, you would change DbHost to point to the
appropriate machine).
Warning
When utilizing the persistent connections between Apache and LXP's PostgreSQL database, it is important to
recognize that there will be a separate postmaster binary running for each
httpd process. Be sure that your system is configured to be capable of loading as many
PostgreSQL postmaster backends as Apache requires (i.e., the number defined by the
MaxClients directive in Apache's httpd.conf ) file.
