Server Directives

The Action directive associates the specified program path with a document mime type. The Action directive may be  used to ensure a specific program is used to run CGI scripts.

The CGI handler may match URLs by extension or by prefix path, depending on how the appweb configuration file setup. When a match by extension occurs, the cgiHandler will first see if an Action directive has been specified for the corresponding mime type for the URLs extension. If one is defined, the specified program is run with the CGI script passed as the first argument. If no action directive is found, the script is examined to see if it contains a "#!/programPath" in the first line of the script. If it does, the specified program is run with the CGI script passed as the first argument. If the script is a binary executable or if the first line does not contain such a programPath, the CGI script will be directly executed.

The default extensions in the appweb configuration file are: cgi, cgi-nph, bat, cmd, pl, py, and php. For Linux, the default settings also include an Action directive for the php extension. The other default extensions do not have Action directives.

The mime type may be added via the AddType directive or you may edit the mime.types file to add the mime type. Mime type entries associate a mime type with a given URL extension. For example, the following mime entry specifies that any URL with a ".php" extension should will have the application/x-appweb-php mime type:

application/x-appweb-php php

The AddType directive will associate the specified MIME type with the nominated extension. MIME types are used by Appweb when processing CGI scripts. When processing client requests, Appweb will map a URLs extension to a mime type. If an Action directive has been specified for this mime type, the associate program will be run using the CGI protocol to process the URL.

The CanonicalName directive specifies the preferred, public, fully qualified hostname for the server. This address will be used when constructing URLs and redirections. The given hostname should be a fully qualified domain name with port number if using a port other than the default port.

If a CanonicalName is not defined, the value provided by the client in the request HTTP Host header will be used.

Escape environment variables passed to CGI programs for special shell characters. If using shell scripts as CGI programs, this directive will escape all special shell characters to make scripting easier and more secure. This will escape (with \) the following characters: &;`'\"|*?~<>^()[]{}$\\\n and also on windows \r%. The default value is "on".

Note: this will escape the QUERY_STRING and "&" characters will be converted to "\&".

See Wikipedia Chroot for more information.

The GroupAccount directive specifies the account group in which Appweb will be a member when running. If UserAccount and GroupAccount are defined, the supplemental groups will include only the specified group and not the other groups to which the user is a member of. If you require all supplemental groups, do not set the GroupAccount.

It is important that you run Appweb with the lowest system privilege that will get the job done. If any application is compromised, including Appweb, then the system will be safest if the compromised application has as few privileges as possible.

When Appweb starts it initially runs as root or administrator and then changes account if a group account is defined in the Appweb configuration file by the GroupAccount directive.

If logged in as root or administrator, the pseudo name of APPWEB will change group to _www on Mac, nogroup/nobody on Unix and Administrator on Windows.

The Home is by default /etc/appweb on Linux and "C:\appweb" on Windows. It is important that the server root directory be protected against modification by other users. It should be owned by either root or administrator and should only be writable by these users.

This directive controls support of the HTTP/2 protocol. If Appweb is built with HTTP/2 support via the ME_HTTP_HTTP2 compile time directive (default), then Appweb will support both HTTP/1 and HTTP/2. The Http2 directive allows the runtime control of HTTP/2 support. By setting the directive to "off", HTTP/2 will be disabled and only HTTP/1 will be supported. The default value is "on". It is imperative that this directive be used before any ListenSecure directives. The HTTP/1 protocol is aways supported and cannot be disabled.

The Listen directive specifies the IP endpoints on which Appweb will listen for incoming HTTP requests. If you specify only the port number and omit the IP address, Appweb will listen on all network interfaces including the loop-back adaptor. It will listen on both IPv4 and IPv6 if only a portNumber is specified.

To listen on IPv6 endpoints, enclose the IP address in square brackets. For example: Listen [2001:05c0:9168:0000:0000:0000:0000:0001]

To listen on IPv4 endpoints, supply an IPv4 IP address. You may use 0.0.0.0 to listen on all IPv4 interfaces.

To listen for SSL requests, use the ListenSecure directive.

To permit multiple instances of Appweb to bind to the same listen endpoint, specify the multiple attribute. Multiple binding is supported on Linux only.

The ServerName defines the set of hostnames that should be served by this host or virtual host. The host name may be a fully qualified hostname with port number, a partial hostname with a "*" wild card character or a regular expression.

If the ServerName begins with "*", it will match requests with a client HTTP Host header that "contains" the given name. For example: a ServerName directive of "*.example.com" will match farm.example.com and www.example.com.

Similarly, if the ServerName ends with "*", it will match client HTTP Host headers that begin with the pattern. For example: "example.*" will match "example.com" and "example.org".

If the ServerName begins and ends with "/", the pattern is interpreted as a regular expression.

Unlike Apache, the ServerName directive is not used for redirections. See the CanonicalName directive to define the public hostname by which the server prefers to be known.

The StreamInput directive specifies if the request body data should be buffered before processing the request or whether the processing should be started immediately and the body data streamed to the handler.

By default, POST forms that have a Content-Type of "application/x-www-form-urlencoded" or "application/json" will have their request body data buffered before processing. This enables form requests to use body data in the route processing. By default, all other requests content types will be streamed.

The mimeType specifies the required "Content-Type" HTTP header for the request. The URI is optional and if supplied, specifies a matching URI prefix for qualifying requests.

StreamInput application/x-gzip /upload

The StreamInput applies to the entire host and is not specific per-route.

The TypeConfig directive specifies the location of the MIME types files. This file contains the mappings from file extensions to content types and is used by Appweb to determine the document content type which is included in the HTTP response back to the browser. The MIME types file included with Appweb follows the standard specified by IANA.

The directory path may be an absolute path or it may be relative to the Home directory.

The MIME types file has lines of the format:

ApplicationType [extensions]...

Feel free to modify the default mime types file, but be careful to save it as it will be overwritten should you upgrade Appweb.

The UserAccount directive instructs Appweb to change accounts to run as the specified account name. The account name chosen for the UserAccount directive should have minimal privilege and should not be able to read or modify any files outside the Documents directory or specified Alias directories.

If logged in as root or administrator, the pseudo name of APPWEB will change user to _www on Mac OSX, nobody on Unix and Administrator on Windows.

If UserAccount and GroupAccount are defined, the supplemental groups will be set to include only the specified group. This means you get one UID and one GID. No supplemental groups.

If UserAccount is set and GroupAccount is not set, then Appweb will run with group membership set to include all groups to which the user account is a member of.

The UserAccount directive can only be used if Appweb is started using a privileged account such as root. Normally Appweb is started using the account root or administrator and thereafter it changes to run with less privilege using the specified accountName.