Quick Nav
- File Syntax
- Configuration Blocks
- Include Directives
- Conditional Directives
- Order of Processing
- Configuration Directives
See Also
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 programatically. 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.
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
ServerRoot "." ErrorLog error.log ServerName http://localhost:7777 DocumentRoot "/var/web" Listen 7777 LoadModule fileHandler mod_file AddHandler fileHandler .html
Configuration Blocks
The configuration file is comprised of several directive groups or blocks:
- Global Directives
- Directory Blocks
- Location 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.
Directory Blocks
A Directory block defines a group of directives that apply to a physical disk location. The block is created by the Directory directive.
<Directory "/home/my/docs> AuthType digest AuthName "MyCorp" Require valid-user </Directory>
This will enable user authentication for accesses to the documents in the "/home/my/docs" directory.
Location Blocks
A Location block defines a group of directives that apply to a specific URL. The block is created by the Location directive.
<Location "/myapp/"> SetHandler egi </Directory>
This will configure Appweb to pass requests that begin with the URL "/myapp" to the egi handler. So whereas a Directory block applies to physical files, Location blocks apply to URL names.
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 206.148.97.56> DocumentRoot /var/www/mycorp ... </VirtualHost>
Here is an example of a Name-based virtual host.
NameVirtualHost 206.148.96.56 <VirtualHost 206.148.97.56> ServerName www.mycorp.org DocumentRoot /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 include a single file or, via a simple wild-card, can include all the files in a directory.
Include myconfig.conf Include conf/applications/*
NOTE: The "*" wild card means all the files in this directory. You cannot use "*.conf" or other conditional wild cards in the current release.
The only wild-card supported is "*".
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 values, 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
Value | Description |
ACCESS_LOG | True if access logging is enabled |
BLD_DEBUG | True if this is a DEBUG build |
DIGEST | True if digest authentication is enabled |
DOC | True if documentation is enabled |
LOG | True if logging is enabled |
NAME_MODULE | True if the module if enabled, where NAME is the name of the module. |
MULTITHREAD | True if this build is multi-threaded |
SAMPLES | True if building samples |
TEST | True if building unit tests |
Order of Processing
The configuration file is parsed in a single top-to-bottom pass. Because certain directives depend on others, the order of directives is important. For example, you must define the ServerRoot before using the LoadModule directive.
Configuration File Directives
This is the list of Appweb supported configuration directives.
Name | Purpose |
Action | CGI program to run to handle specific content. |
AddHandler | Add a handler for processing given file extensions. |
AddInputFilter | Add an input filter to the processing pipeline. |
AddOutputFilter | Add an output filter to the processing pipeline. |
AddType | Add a MIME type specification. |
Alias | Map URLs to directories. |
Allow | Define which servers can access content. |
AuthDigestQop | Define the quality of protection for Digest Authentication. |
AuthGroupFile | Define the name of the user group file for authentication. |
AuthMethod | Define the authentication method: File or PAM. |
AuthName | Define the realm of users to be permitted access to this set of documents. |
AuthType | Define the type of authentication to use: Basic or Digest. |
AuthUserFile | Defines the file of user names. |
Chroot | Define the directory for a "chroot jail" in which Appweb will execute. |
CustomLog | Define the location and format of the access log. |
Deny | Define which servers cannot access content. |
Directory | Define a block of directives to apply to a directory tree. |
DirectoryIndex | Define the default index file to service for directory requests. |
DocumentRoot | Directory containing web content. |
EjsApp | Enable the enclosing location block as an Ejscript application. |
EjsAppAlias | Define an Ejscript application alias. |
EjsAppDir | Define a directory as containing Ejscript applications. |
EjsAppDirAlias | Define an Ejscript application directory alias. |
EjsErrors | Control how Ejscript manages errors. |
EjsSession | Control if Ejscript automatically creates sessions. |
EjsSessionTimeout | Define the default session timeout value. |
ErrorDocument | Define an error document to serve. |
ErrorLog | Define the location and format of the error log. |
Group | Define the O/S account group used by Appweb. |
IndexOptions | Define the options for directory listings. |
IndexOrder | Define the order of processing directory index options. |
KeepAlive | Enable HTTP Keep-Alive |
KeepAliveTimeout | Define the time period to reuse a TCP/IP connection. |
LimitChunkSize | Set the transfer chunk encoding size. |
LimitClients | Set the limit of simultaneous clients. |
LimitRequestBody | Set the maximum size of the incoming request body. |
LimitRequestFieldSize | Set the maximum request header size. |
LimitRequestFields | Set the maximum number of request header lines. |
LimitResponseBody | Set the maximum response body size. |
LimitStageBuffer | Set the maximum buffer size for pipeline stages. |
LimitUrl | Set the maximum size of a URL. |
Listen | Define the IP address and port on which to listen. |
LoadModule | Load an Appweb module. |
LoadModulePath | Specify a list of directories to search for modules. |
Location | Define a block of directives to apply to a URL location. |
LogLevel | Define the verbosity of messages to the error log. |
LogTrace | Control the tracing of HTTP messages. |
LogTraceFilter | Filter the tracing of HTTP messages. |
MaxKeepAliveRequests | Define the re-use count for a connection. |
NameVirtualHost | Nominate an IP address for name-based virtual hosting. |
Order | Specify the order in which the allow and deny directives apply. |
Protocol | Define the HTTP protocol to use. |
PutMethod | Control use of the HTTP PUT method. |
Redirect | Redirect requests to a new target. |
Require | Define which authenticated users will be permitted access to content. |
ResetPipeline | Reset the input and output pipeline for a block. |
ScriptAlias | Map a URL to a directory for CGI processing. |
SendBufferSize | Set the TCP/IP internal buffer size. |
SetConnector | Set the connector stage for a block. |
SetHandler | Set the handler to process requests. |
StartThreads | Number of threads to pre-allocate. |
ThreadLimit | Maximum number of threads. |
ThreadStackSize | Stack size for each thread. |
Timeout | Define the request timeout limit. |
ServerName | Define a name for the server to use for itself. |
ServerRoot | Define the directory containing the core Appweb configuration. |
SSLCACertificateFile | Define the location of the client certificate file. |
SSLCACertificatePath | Define the directory for client certificates. |
SSLCertificateFile | Define the server certificate. |
SSLCertificateKeyFile | Define the server's private key. |
SSLCipherSuite | Set the cipher suite to use for SSL. |
SSLEngine | Enable SSL processing for a block. |
SSLProtocol | Set the SSL protocols to enable. |
TraceMethod | Control whether the HTTP Trace method is enabled. |
TypesConfig | Specify the location of the MIME types file. |
User | Define the O/S user account used by Appweb. |
VirtualHost | Create a directory block for virtual hosting for an IP address. |