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.confThe configuration file may include other configuration files and it is normal practice to partition the configuration file into sections — especially application definitions.
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 fileHandler mod_file AddHandler fileHandler html
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.
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.
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.
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
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 FILE_MODULE> LoadModule fileHandler mod_file </if>
This will load the file handler if it has been enabled via the configure command.
Supported Conditional Values
|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.