Embedthis Appweb 3.4.0
Home > Users Guide > Configuring Appweb

Quick Nav

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.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:

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:

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.

© Embedthis Software LLC, 2003-2012. All rights reserved. Embedthis, Ejscript and Appweb are trademarks of Embedthis Software LLC.