Embedthis Appweb 4.3.4
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 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 fileHandler mod_file
    AddHandler fileHandler html

## 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 206.148.97.56>
        Documents /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
        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 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
--- | ---
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

This is the list of Appweb supported configuration directives.

Name | Purpose
--- | ---
AccessLog | Define the location and format of the access log.
Action | CGI program to handle specific content.
AddInputFilter | Add an input filter to the processing pipeline.
AddHandler | Add a handler for processing given file extensions.
AddLanguageSuffix | Add a supported language and filename suffix to use for this language.
AddLanguageDir | Add a per-language content directory.
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.
AuthStore | Define the authentication method: "file" or "system".
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 | Define the file of user names.
Cache | Configure client and server side caching.
Chroot | Define the directory for a "chroot jail" in which Appweb will execute.
Compress | Control the use of compressed content.
Condition | Define a conditional test for a route.
DefaultLanguage | Set the default language to use for a route.
Deny | Define which servers cannot access content.
DirectoryIndex | Define the default index file to service for directory requests.
Documents | Directory containing web content.
EjsAlias | Define an Ejscript application alias.
EjsStartup | Define an Ejscript application script.
EjsWorkers | Define the maximum number of worker threads.
ErrorDocument | Define an error document to serve.
ErrorLog | Define the location and format of the error log.
EspApp | Define an ESP application with required Routes.
EspCompile | Define the compilation command.
EspDb | ESP Database configuration.
EspDir | Set the directory for ESP MVC components.
EspEnv | Set an environment variable for ESP compilation commands.
EspKeepSource | Control the preservation of intermediate source code.
EspLink | Define the link command.
EspLoad | Load an application.
EspResource | Create routes for a resource.
EspResourceGroup | Create route for a group of resources.
EspRoute | Create a new route for ESP controllers and pages.
EspRouteSet | Define a package of routes for ESP.
EspShowErrors | Show server side errors back to the client.
EspUpdate | Control whether updated ESP source code triggers reloading.
ExitTimeout | Define the timeout period to wait for requests to complete before exiting or restarting.
Header | Define a HTTP header test for a route.
GroupAccount | Define the O/S account group used by Appweb.
Home | Define the directory containing configuration files.
IgnoreEncodingErrors | Ignore UTF-8 encoding errors in WebSockets
IndexOptions | Define the options for directory listings.
IndexOrder | Define the order of processing directory index options.
InactivityTimeout | Maximum request and connection inactivity duration.
LimitBuffer | Set the maximum buffer size for pipeline stages.
LimitCache | Set the maximum size of the Appweb cache for responses and sessions.
LimitCacheItem | Set the maximum size of a single item in the Appweb cache.
LimitChunk | Set the maximum transfer chunk encoding size.
LimitClients | Set the limit of simultaneous clients.
LimitFiles | Set the maximum number of open files or sockets on a Unix system.
LimitKeepAlive | Define the re-use count for a connection.
LimitMemory | Limit the total memory usage of Appweb. This is a hard limit.
LimitProcesses | Maximum number of CGI processes to spawn.
LimitRequests | Set the limit of simultaneous requests.
LimitRequestsPerClient | Set the limit of simultaneous requests for a single IP address.
LimitRequestBody | Set the maximum size of the incoming request body.
LimitRequestForm | Set the maximum size of the incoming request form data.
LimitRequestHeader | Set the maximum total request header size.
LimitRequestHeaderLines | Set the maximum number of request header lines.
LimitResponseBody | Set the maximum response body size.
LimitUpload | Set the maximum file upload size.
LimitUri | Set the maximum size of a request URI.
LimitWebSocketsFrame | Limit the maximum size of a Web Sockets Message Frame.
LimitWebSocketsMessage | Limit the maximum size of a Web Sockets Message.
LimitWebSocketsPacket | Limit the maximum size of a Web Sockets Message Packet.
LimitWorkers | Limit the maximum size of a Web Sockets Message.
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.
LogRoutes | Display the route table in the error log.
Log | Control the tracing of HTTP events.
MemoryPolicy | Define the action to take when memory is depleted.
Methods | The acceptable HTTP method verbs.
NameVirtualHost | Nominate an IP address for name-based virtual hosting.
Options | Control directory listing options.
Order | Specify the order in which the allow and deny directives apply.
Param | Define a route step to test request param values.
Prefix | Define a route prefix to trim from the URI.
Protocol | Define the HTTP protocol to use.
PutMethod | Control use of the HTTP PUT method.
Redirect | Redirect requests to a new target.
RequestParseTimeout | Maximum time to parse a request or response HTTP headers.
RequestTimeout | Maximum request duration.
Require | Define which authenticated users will be permitted access to content.
ResetPipeline | Reset the input and output pipeline for a block.
Route | Define a block of directives to apply to a URL route.
RouteName | Set the route name.
ScriptAlias | Map a URL to a directory for CGI processing.
SetConnector | Set the connector stage for a block.
SetHandler | Set the handler to process requests.
Source | Define source code for the handler to use.
StartWorkers | Number of worker threads to pre-allocate and preserve.
Target | Define the target action to take for a route to serve a response to the client.
ThreadStack | Stack size for each thread.
ServerName | Define a name for the server to use for itself.
SessionTimeout | Maximum session state inactivity duration.
SSLCACertificateFile | Define the location of the client certificate file.
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.
SSLVerifyClient | Verify the identity of the client certificate.
SSLVerifyIssuer | Verify the identity of the issuer or the client certificate.
Target | Define a route target.
TraceMethod | Control whether the HTTP Trace method is enabled.
TypesConfig | Specify the location of the MIME types file.
UnloadModule | Unload an Appweb module.
Update | Define an update modification for a route.
UploadDir | Set the directory for uploaded files.
UploadAutoDelete | Control if files are auto-deleted after uploading.
UserAcount | 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-2013. All rights reserved. Embedthis, Appweb, ESP, Ejscript and Embedthis GoAhead are trademarks of Embedthis Software LLC.