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:

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:

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.