WEB5, WEB64: Simple Web Server Appliance

	At a Glance
	Catalog	System
	Category	Web Servers
	User volumes	yes
	Min. memory	128 MB
	OS	Linux
	Constraints	no
	Questions/Comments	Ask Forum

Functional Overview

WEB4 is not available in AppLogic 2.8+; please use WEB5 or WEB64 instead.

WEB is a web server appliance based on the Apache open-source web server software (see http://httpd.apache.org).

WEB serves static web content and executes scripts from a user-configurable read-only content volume. The paths to the documents and scripts are configurable, so that the same volume can be shared between multiple web servers and/or other appliances serving different content.

WEB has three generic output terminals intended for accessing external services from scripts on the content volume. The db terminal is for accessing a MySQL database; the fs terminal is for accessing shared file storage (using NFS); and the aux terminal is for any auxiliary access (e.g., sending e-mail messages to a SMTP server).

The log terminal can be used to connect WEB to a shared file system on which WEB can store its logs.

The configuration of the web server is provided through properties. The properties are designed to cover the most uses in an easy-to-configure way and in most cases only a few need to be set to non-default values. Advanced configurations can be achieved through include files in the Apache configuration format, coming from the content volume. Access and options to content and script files can be further specialized through .htaccess files in the content directories.

If the features provided by the WEB appliance do not meet your needs, please contact our Technical Support to discuss the possible options. We may be able to extend the catalog by providing appliances that cover your needs.

Boundary

Resources

Terminals

The default interface is enabled. The default interface is used by the appliance to report to AppLogic that it has booted successfully. It can also be used to log in over secure shell to the appliance from the AppLogic controller, primarily for diagnostic and troubleshooting purposes.

User Volumes

The volume may provide static and/or dynamic content with an optional configurable directory dedicated for scripts. Script execution from any directory can also be configured using a file name pattern.

In addition to content, the document directory (configured through the docs_dir property) on the content volume may also hold the following optional configuration files, all in the standard apache configuration format (see http://httpd.apache.org/docs/2.2):

• .htconf - if present, this file is included in the apache configuration. This should be used for advanced configuration only. See Advanced Configuration below.
• .apache_conf/*.conf - all files matching this pattern are included in the configuration. This should be used for advanced configuration only. See Advanced Configuration below.
• .htaccess - Per-directory configuration. Each directory may have its own .htaccess file, defining options and access rules for the files in that directory and its sub-directories. The use of .htaccess files is disabled by default. Since the content volume is read-only and is not normally modified at runtime, it may be better to configure per-directory access using <directory> or <location> sections in the custom config files in the .apache_conf directory (see above). Enable the use of .htaccess with the use_htaccess property, if the use of config files is not feasible or if some of the content is sym-linked to data modifiable at runtime (not recommended).
• .rc.local - Script that is executed on boot. The appliance executes the script if it exists, but will not fail if the script is missing. If the script fails with a non-zero status code, the appliance will fail to start.

Properties

Property name	Type	Description
host_name	String	Host name of the web site. WEB uses this name to display in automatically generated pages, as well as for constructing absolute URLs, e.g., in server-generated redirects (e.g., as may be set up in a custom config file installed on the content volume). Note that although explicit redirects are rarely configured, a request for a directory without the trailing '/' causes a re-direct to be issued to the client, with the '/' appended; this redirect will use the value of host_name if it is set. Setting this property correctly is recommended if WEB is expected to be accessed by older clients that do not send a Host: header with their HTTP requests. If this property is set to an empty string, the host name used in the client's request is used. Default: (empty)
admin_email	String	E-mail address for the server administrator. WEB uses this name to display it in automatically generated pages. Default: root@localhost
content_on_fs	String	Specifies whether the content is relative to the file system at the fs terminal or is on the content volume. Allowed values are on and off. If set to on, all content is relative to the file system at the fs terminal. If set to off, the content is on the content volume. Default: off
docs_dir	String	Root directory on the content volume where the documents to be served are located. For example, it may be /mydocs. This property is convenient to use when more than one WEB server share the content volume and each server needs its own documents. If docs_dir is set to the empty string, the root directory of the content volume is used. The directory must be pre-existing on the content volume. Default: (empty)
docs_loc	String	An optional location within the client-visible namespace where the content should appear ("client-visible namespace" is the path portion of a URL, or what appears to the right of the host name in a URL, including the leading /). If set to a non-empty value, this becomes the namespace root, as seen by the client, where the document root directory appears. For example, if docs_loc is set to subspace/samples, an HTTP request for /subspace/samples/file1.html will serve file1.html from the document root directory. Note that a request for a location outside /subspace/samples will return an error, except if it is a request for a script in the scripts directory (see scripts_loc). This property is useful when WEB serves a subspace of a Web site. Do not append a trailing slash to this value. Default: (empty)
scripts_dir	String	Root directory on the content volume where CGI scripts are located. For example, it may be /scripts. This should be set to a non-empty value, referring to a directory on the content volume that contains only executable scripts (don't set it to "/"). The directory must be pre-existing on the content volume. Default: (empty)
scripts_loc	String	The location in the web space where the scripts directory specified by scripts_dir should be visible. This must be set to a non-empty string to enable the use of a dedicated scripts directory. A typical value may be /cgi-bin. Do not append a trailing slash to this value. Default: (empty)
logs_enabled	String	Controls whether WEB will send its logs out the log terminal. Allowed values are on and off. If set to on, the log terminal must be connected. If this is set to off, no access log is used at all and the error log is written to a file on the root filesystem of the WEB instance, rotated weekly, with 4 weeks of back logs kept (/var/log/httpd/error_log*). Default: off
logs_base_dir	String	Directory where WEB's logs are stored. This propery has no effect if logs_enabled is set to 'off'. Default: /
access_log_filename	String	Filename for the access log, relative to the file system accessible on the log terminal. For example, access_log. The name may include directory names, e.g., /srv1_logs/access_log or /logs/srv1_access_log. If empty, access log is not created. If the directories don't exist, they will be created. This propery has no effect if logs_enabled is set to 'off'. Default: (empty)
error_log_filename	String	Filename for the error log, relative to the file system accessible on the log terminal. The name may include directory names. For examples, see the access_log_filename. If this is set to an empty value or if logs_enabled is 'off', the error log is written to a file on the root filesystem of the WEB instance itself. This propery has no effect if logs_enabled is set to 'off'. Default: (empty)
error_log_level	String	Severity level of messages to be written to the error log. Allowed values are debug, info, notice, warn, error, crit, alert and emerg. debug writes most messages, emerg writes only emergency messages. Default: warn
timezone	String	Specifies the time zone where the appliance is located. If this property is empty, the timezone is not modified and left as-is. A list of supported time zones is available here. Default: empty

All enumerated string properties are not case sensitive (lowercase). All other string properties are case sensitive.

Advanced Properties

These are additional properties that should normally not need to be configured. They can be used to tune up WEB in non-standard circumstances.

All enumerated string properties are not case sensitive (lowercase). All other string properties are case sensitive.

Custom Counters

The following counters belong to the Apache counter group:

Error Messages

• content_on_fs is 'off' but the local content volume is missing
• content_on_fs is 'on' but the fs terminal is not connected.
• Failed to mount fs share.
• Failed to mount content volume.
• Failed to set up content on fs.
• docs directory 'docs_dir' does not exist on content volume
• scripts directory 'scripts_dir' does not exist on content volume
• Failed to mount log share.
• "Logs are enabled but the 'log' terminal is not connected.

Memory Usage

WEB configures itself automatically to run with a wide range of available memory, to fit applications of different size and load. Despite this, please note that the configuration calculation cannot predict the memory usage of dynamic-content scripts that may be installed on the WEB's content volume and a misbehaving script can cause the server to malfunction by overcomitting memory and causing the OS to kill processes.

By default, WEB configures the maximum number of active connections assuming:

• 16MB for system use (OS kernel, system daemons, Apache shared code)
• 2MB per active connection, with 1MB used by Apache and 1MB for an external script

For example, in the 'sandbox' configuration with 32M, the max number of active connections will be set to 8.

The maximum number of connections can be limited below the automatically computed value using the max_connections property. Remember that if max_connections is above the limit imposed by the available system memory, it is trimmed without warning.

In addition, the PHP pre-processor's allocation limit is set to 1/2 the memory available for scripts, as computed according to the above rules, i.e., the PHP is configured to limit the memory for a running script to

(system_memory - 16MB - max_connections * 1MB) / 2

Where the max_connections value is the smaller of the max_connections property and the limit imposed by the available memory (computed assuming 2MB per connection, as described above). If the max_connections property is left at its default value, this will yield the following value for the PHP memory limit:

(system_memory - 16MB) / 4

Note that the "1/2 of available memory per script" rule used is somewhat optimistic and is based on the assumption that either not all active connections will use a hungry PHP script that actually hits the limit, or that the scripts don't actually use all the memory that they allocate.

TIP: If a memory-heavy application starts misbehaving under load (drops connections), and increasing the available memory is not an option, try setting the max_connections property to a lower value. This will reduce the possible number of script instances that run at the same time, giving each instance more memory to run in.

Setting Up The Content, Shared File Storage

This section provides useful information for configuring scripts that serve dynamic content.

Fixed Directory Names

On starting the HTTP server, the following directories and files are available within the filesystem space of the WEB instance. Note that using absolute directory names outside of these locations in any script or configuration file is not recommended.

/var/www/html - web root, visible as '/' to the client. This refers to a location on the content volume and is read-only. Note that if the 'docs_loc' property is set, then /var/www/html itself will have no data files in it. Appending the value of docs_loc will produce the name of a valid symbolic link that refers to the document root. This directory name and the /var/www/cgi-bin name (see below) and any of their sub-directories can be used in Apache configuration files to set up additional per-directory settings. This avoids the need for such configuration files to be aware of the particular setting for the docs_dir and scripts_dir properties.

/var/www/cgi-bin - symbolic link to the scripts root, if set up via the scripts_dir property.

/mnt/fs - root of the shared read/write file storage provided by a NFS server connected to the 'fs' terminal. If one is not connected, /mnt/fs will be empty.

Fixed Web Space Locations

The /icons/ path is aliased to a directory containing stock icons for server-generated directory listings. Therefore, a directory named icons in the content volume will not be visible.

Access Control

The HTTP server runs as user 48, group 48. CGI scripts run in the same context.

Files on the content volume should have 'read' permission for everyone, to be eligible for serving through HTTP. Executable scripts should have 'read' and 'execute' permissions for everyone.

Although the Apache server has other means to control access to files, one may also remove the 'read' permission for 'everyone' from files or directories that should not be made accessible through HTTP. Do leave the 'x' bit set on for directories for which a listing should not be accessible, but contain files or sub-directories that are accessible.

Sending E-mail

The 'sendmail' system is not configured on WEB. Do not use it for sending e-mail from this appliance. To provide access to an external SMTP server, connect the aux terminal to an appliance which provides this functionality or to an OUT gateway directed to a server outside of the application. If using Perl-based scripts, the Mail::Mailer module can be used for sending e-mail, if it is configured to use the 'smtp' mailer. In all cases, your SMTP mailer should be set up to use 'aux' as the hostname of the SMTP server, e.g., if using Mail::Mailer :

$mailer = new Mail::Mailer 'smtp', (Server => 'aux');
$mailer->open(\%headers); #... etc.

Installing Additional PHP/Perl Modules On The Content Volume

PHP modules

Install all required software dependencies

rpm --test -Uv php-mhash-5.1.6-5.el5.i386.rpm

This will complain if there are any unsatisfied dependencies. If you are using rpm packages for the dependencies, check that they do not have unsatisfied dependencies of their own, e.g.:

rpm --test -Uv libmhash-0.9.1-1.2.el5.rf.i386.rpm

Then install all required rpm's on the fs share, e.g.:

rpm --root=/mnt/fs/php -Uv --nodeps libmhash-0.9.1-1.2.el5.rf.i386.rpm

If you are not installing the php module from an rpm, make sure it is compatible with the version of php used in WEB and that it does not require any additional libs (ldd /path/to/php/module.so). If you have unsatisfied dependencies, install the needed software on the fs share.

Install the php module on the fs share

rpm --root=/mnt/fs/php -Uv php-mhash-5.1.6-5.el5.i386.rpm

This will install the rpm under /mnt/fs/php.

Create a .rc.local script that will update the php configuration on appliance boot

#!/bin/bash

# die on all errors
set -e

# Add configuration to the main php conf dir. Path to extensions must be changed to be relative to /usr/lib/php/modules/
sed  's/extension=\(.*\)$/extension=..\/..\/..\/..\/mnt\/fs\/php\/usr\/lib\/php\/modules\/\1/g' /mnt/fs/php/etc/php.d/*ini > /etc/php.d/custom-php.ini

# If we installed any dependent libs on the =fs= share, we need to tell ldconfig to load them
# You can skip this if you did not install any dependent libs on the =fs= share
echo /mnt/fs/php/usr/lib > /etc/ld.so.conf.d/custom-libs.conf
ldconfig

# Restart apache and check status
/etc/init.d/httpd restart
sleep 1
/etc/init.d/httpd status

Perl modules

Install any software dependencies that might be required

#!/bin/bash

# die on all errors
set -e

# If we installed any dependent libs on the =fs= share, we need to tell ldconfig to load them
# You can skip this id you did not install any dependent libs on the =fs= share
echo /mnt/fs/php/usr/lib > /etc/ld.so.conf.d/custom-libs.conf
ldconfig

Install the perl modules

Add the installation path to your perl include path

For perl running as cgi, you can add the following to a .htconf file on your fs share to add the install path to @INC:

SetEnv PERL5LIB  /mnt/fs/perl_mods/usr/lib/perl5/vendor_perl/5.8.8/ 

For perl running as mod_perl, you can add the following to .htconf:

PerlSwitches -I/mnt/fs/perl_mods/usr/lib/perl5/vendor_perl/5.8.8/

Typical Usage

Static web site

2-tier application with database

2-tier application with database and log

2-tier application with shared file system and e-mail gateway

Scalable 2-tier application

(see also the Sample SugarCRM application)

Notes and Links

Known Limitations

• If using WEB to serve pages to clients outside of the application, the web server never gets the real IP addresses of the clients. Instead, it sees the IP address of the output of the appliance that is connected to WEB's in terminal. This creates problems in (a) the access log and (b) getting the IP address of the client to CGI scripts. We are working on finding appropriate solutions.
  • For the log, a solution may be to log the incoming IPs on an advanced IN gateway, using the iptables log capability. A current workaround is to use a small JavaScript on each page and record the stats on a regular web site -- similar to the access tracking done with Urchin (now Google Analytics).
  • For the IP addresses, if what you want to do is control what clients can connect, use the IP filtering in the gateway.
  • A new gateway, INSSLR is available. It provides the real IP address in the X-Forwarded-For http header field and is OK to use even though the SSL support is not used..
  • For problems and suggestions, please contact Technical Support.

Open source and 3rd party software used inside of the appliance

The following open source 3rd party software is used in addition to that software found on the appliance base class (LUX5 is the base class of WEB5 and LUX64 is the base class of WEB64).

To see the full list of open source packages used in the WEB5 appliance, please see its implementation design.

To see the full list of open source packages used in the WEB64 appliance, please see its implementation design.

Related Documents

• Release Notes
• Test Plan
• WEB5 Implementation Design
• WEB64 Implementation Design

Questions and Comments

To post a question or comment on this appliance, visit our forum.

-- StephenQ - 21 Jan 2010