Route 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 AddHandler directive ensures that the Appweb handler specified by handlerName, will be run whenever a document with the given extension is requested. Multiple extensions may be specified and multiple AddHandler directives may exist for any handler.

If the AddHandler directive is specified within a VirtualHost or Route block, it is only valid within that context. VirtualHosts and Route blocks inherit the handler settings defined by outer blocks. I.e. a VirtualHost will inherit all the handlers of the default server. If you wish to remove a handler mapping, use Reset pipeline and then re-add the required handlers.

NOTE: Unlike Apache, the extensions are case sensitive on systems that have case sensitive file systems. Also, the period must be part of the extension.

The AddInputFilter directive adds a filter to the input processing pipeline. Incoming request data is passed through the input pipeline and may be processed by each filter in turn.

Filters stack and thus have an order. The first filter added will receive the data last and the last filter defined for a given URI will be the first filter to receive the data.

The AddOutputFilter directive adds a filter to the output processing pipeline. Output response data is passed through the output pipeline before being sent to the client.

Filters stack and thus have an order. The first filter added will receive the output data first and the last filter defined for a given URI will be the last filter to receive the data before it is passed to the network connector for transmitting to the client.

The AddLanguageDir directive defines a language with an associated directory of language specific content. When a client request is served, the appropriate language will be selected using the language specified by the client's Accept-Language HTTP header. Then, the document filename will be constructed using the language content path.

If the client requested language is not defined, the language specified via the DefaultLanguage directive or "english" will be used.

The AddLanguageSuffix directive defines a supported language with an associated filename suffix. When a client request is received, the appropriate language will be selected using the language specified by the client's Accept-Language HTTP header. Then, the document filename will be constructed using the language suffix. The suffix can be positioned either before or after the document extension via the "position" argument.

If the client requested language is not defined, the language specified via the DefaultLanguage directive or "english" will be used.

The Alias directive is a short-cut to create a Route that maps a URI prefix to a Document Root. It allows URIs to refer to documents that are stored outside the Document Root. The urlPortion of the request URI 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.

The Alias directive:

Alias /manual/ /home/john/doc/

<Route /manual/>
    Documents /home/john/doc/
    Prefix /manual
</Route>

This directive controls client and server-side caching for response content. Each Cache directive selects a set of requests to be cached for the current route. The selected requests are determined by specifying qualifying HTTP methods, document extensions, extension Mime types and/or URI paths. All such parameters must match for the response to be cached. A route may have multiple Cache directives. Cache directives, similar to most directives are inherited from outer routes.

Caching may be used for any HTTP method, though typically it is most useful for state-less GET requests. Response data may be uniquely cached for requests with different request parameters (query, post and route parameters). Alternatively, the URI may specify request parameters in sorted www-urlencoded form to select a specific URI/parameter combination. When responses are cached, the response data and response headers are cached.

Client-Side Caching

If client caching is requested by specifying "client" with an optional lifespan, a "Cache-Control: max-age=lifespan" HTTP header will be added to the response. This header will define a client-side cache lifespan that instructs clients to cache response content for a specified duration. If the document is subsequently requested by the client before the cached response has expired in the client cache, the document will be served from the client cache without contacting the server.

Server-Side Caching Modes

When using Server-Side caching, there are three possible modes:

• Combined — All qualifying requests for a cache definition will be combined onto a single cached response. the request params (query, post data and route parameters) will be ignored and all requests for a given URI path will cache to the same cache record.
• Unique — All qualifying requests will cache uniquely depending on the request parameters. i.e. Requests with different query, post data, or route parameters will be separately cached. Any URIs specified in the directive should not contain any request parameters.
• Only — Only the exact URIs specified in the directive will be cached. The URIs specified must contain request parameters in a sorted www-urlencoded format.
  E.g.: /example.esp?hobby=sailing&name=john.
• Manual — In manual-mode the response will still be automatically cached. However, it will not be automatically written to the client. The request handler must call the espWriteCached API or must set the X-SendCache HTTP header to manually write the cached response content.

Server-Side Caching

When a request is generated, the response is automatically cached and also sent to the client. The response is sent with an HTTP ETag header and a last-modified timestamp. Together these uniquely identify the response data. Subsequent client requests will submit these header values so that they can then be validated by the server. If the server-side cached content has not expired and has not been modified, then an HTTP Not-Modified (304) response will be sent to the client and then the client can use its client-side cached content. This results in a very fast transaction with the client as no response data is sent.

Note: Server-side caching will cache both the response headers and content.

Cache Lifespans

The Cache directive may specify a lifespan using the "client=time" or "server=time" options. If the lifespan is not specified, the default route lifespan will be used. To set the default lifespan for the route, just include a lifespan with no other arguments. E.g. Cache 1day.

Summary

Use client-side caching for static content that will rarely change or for content for which using "reload" in the browser is an adequate solution to force a refresh. Use server-side manual caching in situations where you need explicit control of when the page is updated. Otherwise, use standard server-side caching.

The CharSet directive defines the default character to use with the Content-Type response header. If defined, the "; charset=value" will be appended to the Content-Type header.

The Condition directive supports four rule varieties:

• missing — True if the default request filename is missing.
• directory — True the if rule argument evaluates to a directory
• exists — True if the rule argument evaluates to an existing file
• match — True if the regular expression pattern matches the string argument

The rule result can be negated by prefixing with "!".

For information about embedded {tokens}, see Tokens in the Routing Guide.

The CrossOrigin directive configures exceptions to permit cross-origin sharing. The normal browser sharing model only permits XMLHttp requests to the same server that originated the request. Use of this directive instructs Appweb to emit relevant CORS headers to permit cross-origin sharing. It also configures Appweb to appropriately respond to the client's pre-flight sharing test requests.

See Using CORS for examples of how to create a CORS client request.

The Defense directive defines a policy to invoke when the server is under attack. Defenses invoke remedies which are predefined actions. Supported remedies are:

• ban — Ban the offending client
• cmd — Run an external command to implement the remedy
• delay — Delay responding to the client, but do not ban
• email — Send an email alert
• http — Invoke an HTTP URL
• log — Log information about the defense
• restart — Restart the server

Remedies can be passed arguments in the form of "key=value" pairs. These key values are available for any defines, but some are only utilized for specific remedies.

Cmd Arguments

• CMD — The command to run
• MESSAGE — Descriptive message about the event

CMD strings may include a single pipe symbol "|" to provide input to a commands standard input. The string to the left of the pipe symbol is sent to the command.

Ban Arguments

• PERIOD — Time period to ban the client

Delay Arguments

• DELAY — Time period to delay each request."
• PERIOD — Time period to delay the client the client

Email Arguments

• MESSAGE — Descriptive message about the event
• FROM — Whom the email should be from
• SUBJECT — Email subject
• TO — Where to send the email

Http Arguments

• METHOD — HTTP method verb to use. Defaults to "POST". The request post body is set to the MESSAGES.
• MESSAGE — Descriptive message about the event
• URI — URI to invoke

Other Keyword Tokens

• IP — IP address of the offending client
• STATUS — HTTP status to return to the attacking client. If not defined, the client is silently disconnected.

The DefaultLanguage directive defines the default language to use when the the client Accept-Language HTTP header is either absent or requests a non-supported language.

The Documents directive defines the directory containing the documents that will be served. Each route can have a different document root. The directoryPath should not have a trailing slash.

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

The FastConnect directive configures the FastCGI handler to serve requests using the FastCGI protocol on Unix like systems.

FastCGI programs may be pre-launched or may be launched on-demand by Appweb. If using pre-launched configuration, the FastCGI program should be started before Appweb and should be configured to listen for requests on the IP:PORT address specified via this directive. The port may be zero in which case an available port number is dynamically selected.

The "keep" attributes specifies the communication socket to the FastCGI application should be reused for subsequent requests.

The "launch" attribute specifies that the FastCGI application should be launched by Appweb. The path to the applications is given via the Action directive which specifies a mapping from a mime-type (and hence request extension) to the FastCGI program to serve the request of that type. Alternatively, the command may be specified directly via a "launch=" attribute.

The "min" attribute specifies the minimum number of FastCGI programs to maintain. Appweb will launch FastCGI programs up to the maximum specified via the "max" attribute. After the "timeout" expires, Appweb will kill unwanted FastCGI programs to reduce resource load down to the minimum specified by "min". The default min and max values are 1. The default timeout is 5 minutes.

The "multiplex" attribute defines how many simultaneous requests the FastCGI application can handle. The default is 1. When using a multiplex value greater than one, it is essential that your FastCGI application can handle multiplexing and that the value stipulated in the FastConnect directive be equal or less than the capacity of your FastCGI program. PHP defines the multiplex capacity via its PHP_FCGI_CHILDREN environment variable.

The "maxRequests" attribute defines how many requests to serve before a launched FastCGI application is restarted. The default is unlimited.

The Header directive manages the response headers. Headers can be added, appended, removed or set. The add option will add the header if it is not already present. The append option will add or append to an existing header of the same name. The remove option will remove the header if it exists. The set option will set the header overwriting any prior value.

Header values may contain tokens of the form ${token} which will be expanded when the client HTTP requests are processed. See the httpSetRouteTarget API for full details regarding possible tokens.

This directive controls whether UTF-8 encoding errors will be ignored for WebSockets communications. The default is off.

This directive defines the maximum time that requests and connections can be inactive before Appweb will forcibly terminate the request and close the connection. If further requests arrive on an idle connection, the timeout period is restarted.

Setting the timeout period too high may impact performance on high-traffic servers because the number of open, idle TCP/IP connections can grow.

Appweb supports HTTP KeepAlive where a single TCP/IP connection may be reused for multiple requests. This can significantly speed up overall performance. Keep-Alive is supported by Appweb with both HTTP/1.0 and HTTP/1.1 protocols. With HTTP/1.1, Keep-Alive is the default. With HTTP/1.0, clients may optionally request Keep-Alive via the Keep-Alive HTTP request header.

The Map directive controls the mapping of requests by extension to alternative resources. Most frequently, this is used to transparently serve compressed content instead of uncompressed content.

The Map directive will cause Appweb to serve alternate content if the alternate is present and the client will accept the specified encoding. To use this feature, just compress the required documents with the new extensions and optionally remove the originals.

The new extension pattern may reference the original filename as ${1}.

The short form "Map compressed" directive configures Appweb to serve compressed content for Html, Text, XML, Javascript, CSS or Less documents. It is equivalent to:

Map "js,css,less" "min.${1}.gz, min.${1}, ${1}.gz"
Map "html,txt,xml", "${1}.gz"

The Methods directive controls the valid HTTP methods for the route. The method set is inherited from the parent routes. The "add" command may be used to add methods to the current method set. The "remove" command will remove methods and the "set" command will define a new method set.

The standard HTTP methods are: DELETE, GET, OPTIONS, POST, PUT and TRACE. The MethodSet argument can also be set to "ALL" or "*" to indicate any possible HTTP method.

The Monitor directive instructs the server to monitor specified server resources for unusual behavior that may represent an attack on the server.

Monitors evaluate conditional expressions and if true, invoke Defenses to remedy or protect the server.

Expressions

Monitor expressions are of the form: "Counter Operation Number". The quotes are required. There are two classes of counters: per-client counters and system-wide counters. Counters represent the number of events that occurred over the period specified by the Monitor.

The Operation is either "<" or ">".

Per-Client Counters

• BadRequestErrors —
• Errors —
• LimitErrors — The request violated an Appweb sandbox limit
• NetworkIO — The request had a network I/O error
• NotFoundErrors — The request accessed a missing URI. This may indicated probing of the server by an attacker.
• Requests — Number of requests by the client.
• SSLErrors — Number of SSL errors

System-Wide Counters

System-wide counters are the current value of the counter when the monitor is run.

• ActiveClients — The number of clients accessing the server over the Monitor period.
• ActiveConnections — The number of network connections accessing the server of the Monitor period.
• ActiveRequests — The number of active requests pending completion.
• ActiveProcesses — The number of CGI processes pending completion.
• Memory — The current Appweb memory size.

Monitor Periods

The monitor is invoked at the period specified. If the Counter is a per-client counter, it is evaluated for each active client.

Defenses

One or more defenses may be specified to be invoked if the monitor condition is true. Defenses are defined via the Defense directive.

The Name directive defines a name for the route that will be used by the LogRoutes directive when displaying the route table in the error log. If no route name is defined, the route pattern is used instead.

The Param directive tests if the specified request param value matches the required value. Request params are sourced from the request URI query and posted form data.

The rule result can be negated by prefixing with "!".

For information about embedded {tokens}, see Tokens in the Routing Guide.

The Prefix directive defines a URI-prefix that will be stripped from the request URI Request.pathInfo if the route is selected to handle the request. Once stripped, the Request.scriptName will be set to the prefix. This is useful for an application to be able to be installed with various URI application prefixes without having to modify the application.

This directive controls whether to preserve WebSocket frames. If enabled, frames will not be aggregated or split. i.e. frame boundaries will be preserved to the user callback. Note: using HTTP_MORE to httpSendBlock achieves the same effect on a per-API call basis. The default is off.

The ProxyConfig directive opens a block that may contain other SSL or limit directives. These directives then apply to the network connection from Appweb to the proxied application.

The ProxyConfig directive can be used to enable SSL to be used for communication to the proxied application. It can also be used to define a non-default inactivity timeout for the network connection to the proxied application which by default is 5 minutes.

The ProxyConnect directive configures the Proxy handler to relay requests to configured proxied applications on Unix like systems.

Proxied programs may be pre-launched or may be launched on-demand by Appweb. If using pre-launched configuration, the Proxy program should be started before Appweb and should be configured to listen for requests on the IP:PORT address specified via this directive. The port may be zero in which case an available port number is dynamically selected.

The "launch" attribute specifies that the proxied application that should be launched by Appweb including the program name and arguments.

The "min" attribute specifies the minimum number of Proxy application instances to maintain. Appweb will launch proxied programs up to the maximum specified via the "max" attribute. After the "timeout" expires, Appweb will kill unwanted proxied programs to reduce resource load down to the minimum specified by "min". The default min is zero and and the default max is 1. The default timeout is 5 minutes.

The "multiplex" attribute defines how many simultaneous requests the proxied application can handle. The default is 1. When using a multiplex value greater than one, it is essential that your Proxy application can handle multiplexing and that the value stipulated in the FastConnect directive be equal or less than the capacity of your program.

The "maxRequests" attribute defines how many requests to serve before a launched Proxied application is restarted. The default is unlimited.

The "ssl" attributes specifies the protocol to communicate with the proxy should use TLS. The "http2" attributes specifies the protocol should be HTTP/2 over TLS. The "http2" attribute implies "ssl". Use the ProxyConfig directive to define the SSL cipher parameters for the protocol.

Appweb will rewrite any Location HTTP headers returned from the application if a Canonical (public) URL is defined for the server on that route. Appweb will pass the canonical URL via the X-Canonical HTTP header to the application. The client IP address will also be passed via the X-Client header.

The Redirect directive is a short-cut to create a Route that maps requests from a URI to a new URI.

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

• permanent — redirection. HTTP code 301.
• temp — redirection. HTTP code 302
• seeother — has been replaced, see other document. HTTP code 303.
• gone — resource has been remove. HTTP code 410. The newURI argument is ignored.

The new URI 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 new URI may be omitted for non-3XX status arguments, in which case, a default response page will be generated by Appweb.

The Redirect secure directive redirects all HTTP traffic over a configured HTTPS transport. This performs an immediate redirect of a current request.

The RequestHeader directive tests if the specified request HTTP header value matches the required value. The rule result can be negated by prefixing with "!".

For information about embedded {tokens}, see Tokens in the Routing Guide.

This directive defines the maximum time to parse the HTTP headers for a request or a response. If the maximum is exceeded, Appweb will forcibly terminate the request and close the connection.

This directive is useful to mitigate some denial of service attacks such as the slowloris. It should be configured to a low value typically less than 10 seconds.

This directive defines the maximum duration for a request. If the maximum is exceeded, Appweb will forcibly terminate the request and close the connection.

Some web user interfaces with monitoring applets open HTTP connections and keep them open to stream response data back to the applet. To prevent Appweb from closing the connection, you may need to increase the timeout value for the Route managing the request.

The Reroute directive opens a previously defined route by its matching URI pattern. Inside the Reroute block, you can add or override any prior configuration for the route.

The Reset routes directive erases the configured and inherited route definition. This is useful to start with a clean slate for route configuration. The Reset pipeline preserves route configuration but erases defined handlers, filters and connectors for the specified context. Use AddInputFilter, AddoutputFilter, AddHandler and AddConnector to re-initialize the pipeline.

Reset pipeline is most often used inside VirtualHost blocks when you want to limit the pipeline to a small set of handlers and filters for that Virtual Host.

NOTE: Reset is a proprietary Appweb directive.

The Route directive defines a block of directives that apply to URIs that match specified URI pattern. Routes may be nested where inner routes inherit the outer routes configuration at that point in the configuration file. If a Route directive specifies a URI pattern that has been previously defined, the prior route is re-opened and modified. i.e. A new route is not created.

The ScriptAlias directive is a short-cut to create a Route that maps matching URIs to a directory containing CGI scripts. The ScriptAlias directive is a convenient short-hand and is equivalent to the following directives:

<Route /cgi-bin>
   Alias /cgi-bin/ "/var/myHost/cgi-bin/"
   SetHandler cgiHandler
</Route>

This directive controls the Session cookie. It can disable generation of a session cookie via Session disable. If enabled, it can define a unique prefix to use for the session cookie used by the route. The default session cookie prefix is: "-http-session-".

It is possible to set if the cookie is readable by Javascript in the browser via visible=false|true. By default, the session cookie is not visible to Javascript. It is desirable to keep the session cookie invisible to minimize XSS security vulnerabilities. Appweb implements this by adding the httpOnly option on the Set-Cookie response header.

The persist option defines if the cookie is persisted to disk in the browser. If false, the browser discards the cookie when the browser exits. Otherwise the cookie is retained until the session timeout limit expires.

The same option defines if the cookie is emitted with SameSite=lax or SameSite=strict.

This directive defines the maximum duration for session state data. When this time period expires, Appweb will prune inactive session state data from its session cache.

The SetConnector directive defines the network connector that will transmit a response to the client. The connector represents the last stage in the output request pipeline.

The SetHandler directive defines the request handler that will service a request matching the enclosing block.

ShowErrors on

The ShowErrors directive controls whether errors are sent to the client and displayed in the browser. If ShowErrors is off, then errors will be sent to the Appweb log file. If ShowErrors is on, then the errors will also be sent back to the client. This is useful in development mode to quickly diagnose errors.

The Target directive support four rules:

• close — Immediately close the connection without sending a response to the client.
• redirect — Redirect the client with the given status and URI.
• run — Run the selected handler and use the any argument as the destination document or resource to serve back to the client. If the argument is omitted, most handlers will construct a filename from the request URI and the route document root and serve that to the client.
• write — Writes the given message to the client with the specified status. By default, this rule will escape embedded HTML sequences. If you need to emit pure HTML, use the -r switch for raw write output.

If the Target directive is omitted in a Route, the default action is Target run.

Arguments for the redirect and run rules may contain embedded tokens. For information about embedded {tokens}, see Tokens in the Routing Guide.

The Update directive support two rules:

• param — Set a request parameter.
• cmd — Run an external command.

Update arguments can contain embedded tokens. For information about embedded {tokens}, see Tokens in the Routing Guide.

Once an uploaded file is fully received and processed by the handler, Appweb will either delete or preserve the temporary file depending on the UploadAutoDelete setting. If set to on, the uploaded file will be deleted when the handler completes the request. If set to off the temporary file will be preserved in the Upload directory.

The UploadDir directive defines the directory used to store the temporary files holding uploaded files. These files are temporarily used while the file is being uploaded. Once fully received, the handler responsible for responding to the request must copy, move or process the uploaded file. The uploadedHandler will delete the temporary (subject to the value of UploadAutoDelete).

The WebSocketsPing directive defines the time period for a regular, keep-alive ping message to be sent to the peer so that the connection is not closed.