Configuring Appweb

The Appweb operation is typically controlled by an Appweb configuration file. This configuration file is read when Appweb starts up, and it manages every aspect of Appweb's configuration including what ports and addresses to listen to, what modules to load, where to find the web pages and how to log requests.

Appweb can also be configured programmatically. For details, please read the Appweb API.

The top-level configuration file is usually called appweb.conf and is read once when appweb is started. Changes to the configuration file will require Appweb to be restarted.

An alternative configuration file may be specified by using the --config Appweb command option.

appweb --config myConfigFile.conf

The configuration file may include other configuration files and it is normal practice to partition the configuration file into sections — especially application definitions.

Apache Compatible

The Appweb configuration file closely matches that used by the Apache web server. Compatibility with the Apache configuration file has been a goal to minimize learning time and switching costs. While the level of compatibility is high, there are a few differences:

• The Appweb configuration file is processed in a single-pass.
• A subset of Apache directives are supported.
• For enhanced security, Appweb has a few extra security directives

By processing directives on a single-pass, Appweb is more efficient, but the order of directives does matter with Appweb.

Configuration File Syntax

Configuration directives are one per line and are case-insensitive for the directive names. Lines beginning with a "#" character are comments and are ignored.

Sample configuration file

Home "."
ErrorLog error.log
ServerName http://localhost:7777
Documents "/var/web"
Listen 7777
LoadModule espHandler mod_esp
AddHandler espHandler esp

Configuration Blocks

The configuration file is comprised of several directive groups or blocks:

• Global Directives
• Route Blocks
• Virtual Host Blocks

When a new block is defined, it inherits the settings of the outer block. New directives defined inside a block are local to that block.

Global Directives

A directive is regarded as global if it is not enclosed in a block. You cannot nest blocks of a like kind. i.e. you cannot nest a directory block inside a directory block.

Route Blocks

A Route block defines a group of directives that apply to a specific URL. The block is created by the Route directive.

<Route "/myapp/">
    SetHandler esp
</Route>

This will configure Appweb to pass requests that begin with the URL "/myapp" to the esp handler.

Virtual Host Blocks

A Virtual host block defines a group of directives that apply to a virtual sub-server. A virtual server may be associated with a virtual server name or with an IP address. Virtual hosts enable you to segment the web server to serve unique content for different domains or IP addresses.

Here is an example of an IP-based virtual host.

<VirtualHost>
    Documents /var/www/mycorp
    ...
</VirtualHost>

Here is an example of a Name-based virtual host.

<VirtualHost>
    ServerName www.mycorp.org
    Documents /var/www/mycorp
    ...
</VirtualHost>

See Virtual Hosting for more details.

Include Directives

The include directive allows other files to be included in the configuration file. The include directive can be a single filename or filename with wildcards.

Include myconfig.conf
Include conf/applications/*.conf

Conditional Directives

The configuration file supports conditional processing via the <if> directive. The if directive tests a symbolic value and if true, it enables parsing the nested directives. If the value is false, the nested directives are ignored.

<if ESP_MODULE>
    LoadModule espHandler mod_esp
</if>

This will load the file handler if it has been enabled via the configure command.

Supported Conditional Values

Value	Description
BLD_DEBUG	True if this is a DEBUG build
NAME_MODULE	True if the module if enabled, where NAME is the name of the module.

Order of Processing

The configuration file is parsed in a single top-to-bottom pass. The order of directives is important as certain directives depend on others. For example, you must define the Home before using the LoadModule directive. Also, block level directives inherit their configuration from the outer block. For example: a Route block will inherit the outer configuration and may modify that inside the Route block.

Configuration File Directives

Consult the Configuration Directives for a full list of the supported appweb.conf directives.