Server Directives

Action

Description Specify the CGI program to run to handle the document
Synopsis Action mimeType programPath
Context Default server, Virtual host
Example Action application/x-appweb-python /usr/bin/python
Notes

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

AddType

Description Add a MIME type specification
Synopsis AddType mimeType extension
Context Default server, Virtual host
Example application/x-appweb-perl pl
Notes

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.

CanonicalName

Description Define the public hostname by which the server is known.
Synopsis CanonicalName hostName
Context Default server, Virtual Host
Example CanonicalName www.acme.com
Notes

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.

CgiEscape

Description 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%.
Synopsis CgiEscape on|off
Context Route
Example CgiEscape on
Notes Shell script variables should always be uses inside quotes. For example: use "${filename}" not $filename. This permits filenames with spaces and special characters from being incorrectly interpreted by the shell.
Security Failing to escape CGI variables and then using $name to reference variables can cause a security vulnerability by permitting user supplied data to inject shell special characters into the variable value. This will then be interpreted by the shell when the variable is referenced.

CgiPrefix

Description Define a prefix to prepend to URI query parameters and form variables that are passed to CGI programs in the environment.
Synopsis CgiPrefix String
Context Route
Example CgiPrefix CGI_
Notes If using shell scripts as CGI programs, you should ensure important shell variables like IFS, SHELL and PATH are not overwritten or corrupted by user supplied URI query or form variables. Use a prefix to ensure parameters have their own namespace. The default appweb.conf defines the "CGI_" prefix.
Security Failing to define When coupled with lowering the privilege for the UserAccount and GroupAccount potential security exposures can be minimized.

Chroot

Description Directory containing a "chroot jail" in which for Appweb to execute. Once this directive is parsed, all files outside the jail will be inaccessible.
Synopsis Chroot directoryPath
Context Entire Application
Example Chroot /etc/appweb/jail
Notes

See Wikipedia Chroot for more information.

Security A chroot jail enhances security by limiting system access should Appweb ever be compromised. When coupled with lowering the privilege for the UserAccount and GroupAccount potential security exposures can be minimized.

GroupAccount

Description Account group that Appweb will run as.
Synopsis GroupAccount group
Context Default server
Example GroupAccount nobody
GroupAccount APPWEB
Notes

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.

Security It is extremely dangerous to run Appweb as Group "root" or "administrators".

Home

Description Directory containing the core Appweb installation files
Synopsis Home directoryPath
Context Default server
Example Home /etc/appweb
Notes

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.

Listen

Description IP address and port on which to listing for incoming requests.
Synopsis Listen [IP address:]portNumber
Context Default server, Virtual Host
Examples Listen 80
Listen 205.162.77.64:7777
Listen [::]
Notes

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.

ServerName

Description Define the hostnames that should be served for this host or virtual host.
Synopsis ServerName hostName
ServerName *hostName
ServerName *hostName
ServerName hostName*
ServerName /hostName|hostname/
Context Default server, Virtual Host
Examples ServerName www.acme.com:4100
ServerName *.acme.com
ServerName www.acme.*
ServerName /acme.com|^www.roadrunner.org$/
Notes

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.

StreamInput

Description Control if request body data should be streamed or buffered.
Synopsis StreamInput [!] mimeType URI
Context Default server, Virtual Host
Example StreamInput ! application/x-www-form-urlencoded /very/big/form
Notes

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.

TypesConfig

Description Specify the location of the Mime types file
Synopsis TypesConfig directoryPath
Context Default server
Example TypesConfig /etc/appweb/mime.types
Notes

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.

UserAccount

Description The user account that Appweb will run as.
Synopsis UserAccount name
Context Default server
Example UserAccount nobody
UserAccount APPWEB
Notes

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.

Security Do not run as root or administrator. Omitting the User directive can have the same effect as using a "User root" directive.

© Embedthis Software. All rights reserved.