Embedthis Appweb 3.4.0
Home > Users Guide > Configuration Directives > Server Directives

Quick Nav

See Also

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

Alias

Description Map URLs and leading URL portions to file system locations.
Synopsis Alias urlPortion destinationPath
Context Default server, Virtual host
Example Alias /manual /ftp/manualDirectory
Notes

The Alias directive allows URLs to refer to documents that are stored outside the Document Root. The urlPortion of the request URL will be mapped onto the nominated destinationPath which may be a file or a directory anywhere on the system.

It is an easy mistake to have mismatched trailing slashes. If you have a trailing slash on the urlPortion ensure you also have one on the destinationPath. Appweb will warn you if you have mismatched trailing slashes.

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 User and Group potential security exposures can be minimized.

DocumentRoot

Description Directory containing the documents to be published for the default server.
Synopsis DocumentRoot directoryPath
Context Default server, Virtual host
Example DocumentRoot /var/www
Notes

The DocumentRoot directive defines the directory containing the documents that will be served by the default server. The directoryPath should not have a trailing slash.

ErrorDocument

Description Define an error document to be served when a HTTP error occurs
Synopsis ErrorDocument code URL
Context Default server, Virtual host
Example ErrorDocument 404 /notFound.html
Notes

This directive configures a specific web page to be served whenever a given HTTP error code is encountered.

Group

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

The Group directive specifies the account group in which Appweb will be a member when running.

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 to the user account defined in the Appweb configuration file by the User directive. As installed, Appweb will be configured to run using the nobody account on Linux and in the guest account on Windows.

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

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
Notes

The Listen directive specifies the IP endpoints on which Appweb will listen for incoming HTTP requests. If you specify only the portNumber and omit the IP address, Appweb will listen on all network interfaces including the loop-back adaptor. Multiple Listen directives may be given and Appweb will listen on all the specified endpoints.

If you are using virtual hosts, you must still specify a Listen directive for the endpoint that the virtual host will serve. It makes no difference where you specify a Listen directive. in the configuration file. For compatibility with Apache, you should specify your listen directives outside any VirtualHost blocks.

Protocol

Description HTTP protocol version to use
Synopsis Protocol [HTTP/1.0 | HTTP/1.1]
Context Default server
Example Protocol HTTP/1.0
Notes

The Protocol directive specifies the HTTP protocol version to respond with. If the Protocol directive specifies HTTP/1.0, a browser may issue requests using either HTTP/1.0 or HTTP/1.1. However, the response will always be downgraded to use HTTP/1.0 without Keep-Alive support.

If the Protocol directive specifies HTTP/1.1 and a browser makes a request using HTTP/1.0 it will not be processed and the client will receive an error.

NOTE: this directive is proprietary to Appweb and is not an Apache directive.

Redirect

Description Redirect requests to a new target.
Synopsis Redirect [status] oldUrl newUrl
Context Default server, VirtualHost, Directory
Example Redirect temp /pressRelease.html /fixedPressRelease.html
Redirect permanent /acme.html http://www.coyote.com/acme.html
Redirect 410 /membersOnly
Notes

The Redirect directive translates requests to a URL into a new URL. The old URL may be a full URL or it may be a leading portion of a URL. Typical use for URL portions is to redirect all requests below a directory to another directory or site.

The new URL may be local to the system, in which case it will begin with a "/" character. Or it may be on another system, in which case it will begin with "http://". In both cases, the user will receive a HTTP redirection response informing them of the new location of the document.

The status argument may be either a numeric HTTP code or it may be one of the following symbolic codes:

  • permanent -- Permanent redirection. HTTP code 301.
  • temp -- Temporary redirection. HTTP code 302
  • seeother -- Document has been replaced, see other document. HTTP code 303.
  • gone -- The resource has been remove. HTTP code 410. The newURL argument is ignored.

ScriptAlias

Description Map a URL to a destination and enable CGI script processing for that location.
Synopsis ScriptAlias urlPath destinationPath
Context Default server, Virtual Host
Example ScriptAlias /cgi-bin/ /var/myHost/cgi-bin
Notes

The ScriptAlias directive maps a URL to a file system path and enables the processing of CGI scripts in that directory. The ScriptAlias directive is a convenient short-hand and is equivalent to the following directives:

<Location /cgi-bin>
   Alias /cgi-bin/ "/var/myHost/cgi-bin/"
   SetHandler cgiHandler
</Location>
Security Make sure you locate your CGI script directories outside the DocumentRoot.

ServerName

Description Define the fully qualified hostname and port number for the server to use.
Synopsis ServerName hostName
Context Default server, Virtual Host
Example ServerName www.acme.com
Notes

The ServerName directive allows the server to create a HTTP address for itself to use when creating redirection URLs. The hostName should be a fully qualified domain name with port number if using a port other than port 80.

When used inside Name VirtualHost blocks, the ServerName directive specifies the name that must be specified in the "Host" HTTP header.

ServerRoot

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

The ServerRoot 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.

TraceMethod

Description Control the Trace HTTP method
Synopsis TraceMethod on|off
Context Default server
Example TraceMethod on
Notes

The TraceMethod directive controls whether the TRACE HTTP method is enabled or not. Starting with version 2.2.2, the Trace method is disabled by default as it can represent a security risk. Use "TraceMethod on" to enable the trace method.

Security It is considered by some to be a security risk to enable the Trace method.

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

User

Description The user account that Appweb will run as.
Synopsis User accountName
Context Default server
Example User nobody
Notes

The User directive instructs Appweb to change accounts to run as the specified accountName. The User 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.

The accountName chosen for the User directive should have minimal privilege and should not be able to read or modify any files outside the DocumentRoot or specified Alias directories.

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 LLC, 2003-2012. All rights reserved. Embedthis, Ejscript and Appweb are trademarks of Embedthis Software LLC.