Route 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

AddHandler

Description Add a handler for processing content with specific file extensions
Synopsis AddHandler handlerName extension [extension] ...
Context Default server, Virtual host, Route
Example AddHandler ejsHandler ejs asp
Notes

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.

AddInputFilter

Description Add the specified filter to the input processing pipeline
Synopsis AddInputFilter filterName
Context Default server, VirtualHost, Route
Example <Route /secret/>
    AddInputFilter decryptFilter
</Route>
Notes

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.

AddOutputFilter

Description Add the specified filter to the output processing pipeline
Synopsis AddOutputFilter filterName
Context Default server, VirtualHost, Route
Example <Route /capture/>
    AddOutputFilter compressFilter
</Route>
Notes

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.

AddLanguageDir

Description Add the specified language and language document directory to the route
Synopsis AddLanguageDir iso-lang-tag path
Context Default server, VirtualHost, Route
Example <Route /public/>
    AddLanguageDir en english-docs
</Route>
Notes

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.

AddLanguageSuffix

Description Add the specified language
Synopsis AddLanguageSuffix iso-lang-tag suffix [position]
Context Default server, VirtualHost, Route
Example <Route /public/>
    AddLanguageSuffix en en before
</Route>
Notes

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.

Alias

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

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/
is equivalent to:
<Route /manual/>
    Documents /home/john/doc/
    Prefix /manual
</Route>

Cache

Description Control content caching
Synopsis Cache lifespan
Cache [client=secs] [methods="set"] [extensions="set"]
    →     [types="set"] [URI ..]
Cache [server=secs] [manual] [methods="set"] [ext="set"]
    →     [types="set"] [URI ..]
Context Default server, VirtualHost, Route
Example Cache client=86400 ext="gif,jpeg,jpg,png,pdf,ico,js"
Cache server=86400 methods="GET,POST" /status.esp
Cache client=1800 server=86400 methods="GET,POST" /status.esp
Cache server manual /inventory.esp
Cache 86400
Notes

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.

CharSet

Description Set the default character set encoding for a route.
Synopsis CharSet set
Context Default server, VirtualHost, Route
Example CharSet utf-8
Notes

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.

Condition

Description Define a pre-condition that must be true for the route to be selected.
Synopsis Condition [!] rule details ...
Condition [!] missing
Condition [!] directory string
Condition [!] exists string
Condition [!] match string regular-expression-pattern
Context Default server, VirtualHost, Route
Example Condition missing
Condition directory ${request:filename}
Condition ! exists ${request:filename}
Condition match ${header:User-Agent} (Chrome|Safari)
Notes

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.

CrossOrigin

Description Directive to control cross-origin resource sharing.
Synopsis CrossOrigin origin=[client|all|*|NAME]
     [credentials=[yes|no]] [headers=HDR,...] [age=NN]
Context Default server, VirtualHost, Route
Example CrossOrigin origin=*
CrossOrigin origin=http://www.google.com credentials=yes age=3000
Notes

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.

Defense

Description Define a defensive policy to respond to attacks.
Synopsis Defense [tokens=value]
Context Default server, VirtualHost, Route
Examples Defense deny REMEDY=ban STATUS=406 PERIOD=10mins
Defense block REMEDY=ban PERIOD=30mins
Defense report REMEDY=http URI=http://example.com/report
Defense alarm REMEDY=cmd CMD="afplay klaxon.mp3"
Defense slow REMEDY=delay PERIOD=10mins DELAY=1sec
Defense fix REMEDY=cmd CMD="${MESSAGE} | sendmail admin@example.com"
Defense notify REMEDY=email TO=info@example.com
Defense firewall REMEDY=cmd CMD="iptables -A INPUT -s ${IP} -j DROP"
Defense reboot REMEDY=restart
Notes

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.

DefaultLanguage

Description Set the default language to select for content.
Synopsis DefaultLanguage language
Context Default server, VirtualHost, Route
Example DefaultLanguage en
Notes

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.

Documents

Description Top level directory containing the documents to be published for context.
Synopsis Documents directoryPath
Context Default server, Virtual host, Route
Example Documents /var/www
Notes

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.

ErrorDocument

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

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

FastConnect

Description Configure FastCGI applications
Synopsis FastConnect endpoint
FastConnect endpoint [launch[=command]] [keep] [maxRequests] [max=number] [min=number] [multiplex=number] [timeout="timespec"]
Context Default server, VirtualHost, Route
Example FastConnect 127.0.0.1:9000
FastConnect localhost:9000 launch
FastConnect localhost:9000 launch min=1 max=2 maxRequests=500 timeout=5mins multiplex=1
FastConnect localhost:9000 launch="/program/to/run"
Notes

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.

Header

Description Define a request HTTP header value must match a value for the route to be selected.
Synopsis Header [add|append|remove|set] field value
Context Default server, VirtualHost, Route
Example Header set X-Frame-Options deny
Notes

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.

IgnoreEncodingErrors

Description Ignore UTF-8 encoding errors
Synopsis IgnoreEncodingErrors on|off
Context Default Server, Virtual Host, Route
Example IgnoreEncodingErrors on
Notes

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

InactivityTimeout

Description Control the timeout period for TCP/IP connections
Synopsis InactivityTimeout time
Context Default Server, Virtual Host
Examples InactivityTimeout 2mins
InactivityTimeout never
Notes

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.

Map

Description Control mapping of requests by extension.
Synopsis Map compressed
Map "ext,ext,..." "newext, newext, newext"
Context Default server, VirtualHost, Route
Example Map compressed
Map "js,css,less" min.${1}.gz, min.${1}, ${1}.gz
Notes

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"

Methods

Description Define the valid HTTP Methods for the route
Synopsis Methods [add|remove|set] MethodSet
Context Default server, VirtualHost, Route
Example Methods set GET POST
Notes

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.

Monitor

Description Monitor server resources for attacks
Synopsis Monitor Expression Period Defenses ...
Context Default server, VirtualHost, Route
Examples Monitor "NotFoundErrors > 190" 5sec deny log email
Monitor "RequestsPerClient > 200" 5sec deny
Notes

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.

Name

Description Define a name for the route
Synopsis Name string
Context Default server, VirtualHost, Route
Example Name web-service-login
Notes

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.

Param

Description Add a request param test that must match for the route to be selected.
Synopsis Param [!] field pattern
Context Default server, VirtualHost, Route
Example Param name "John Smith"
Notes

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.

Prefix

Description Define a URI prefix for the route.
Synopsis Prefix URI-Prefix
Context Default server, VirtualHost, Route
Example Prefix /info
Notes

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.

PreserveFrames

Description Preserve WebSocket frame boundaries
Synopsis PreserveFrames on|off
Context Default Server, Virtual Host, Route
Example PreserveFrames on
Notes

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.

ProxyConfig

Description Configure Proxy Network
Synopsis <ProxyConfig>
... SSL directives ... Limit directives </ProxyConfig>
Context Proxy Route
Example ProxyConnect 127.0.0.1:9000
<ProxyConfig>
SSLCertificateFile "${BIN_DIR}/test.crt"
SSLCertificateKeyFile "${BIN_DIR}/test.key"
</ProxyConfig>
Notes

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.

ProxyConnect

Description Configure Proxy applications
Synopsis ProxyConnect endpoint
ProxyConnect endpoint [launch="program args.."]
[http2] [maxRequests=number] [max=number] [min=number] [multiplex=number] [ssl] [timeout="timespec"]
Context Default server, VirtualHost, Route
Example ProxyConnect 127.0.0.1:9000
ProxyConnect localhost:9000 launch="myApp --debug"
ProxyConnect localhost:9000 min=1 max=2 maxRequests=500 timeout=5mins multiplex=1
ProxyConnect localhost:9999 http2
Notes

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.

Redirect

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

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.

RequestHeader

Description Define a request HTTP header value must match a value for the route to be selected.
Synopsis RequestHeader [!] field pattern
Context Default server, VirtualHost, Route
Example RequestHeader User-Agent (Chrome|Safari)
Notes

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.

RequestParseTimeout

Description Defines the maximum time to parse the request or response HTTP headers
Synopsis RequestParseTimeout time
Context Default Server, Virtual Host
Example RequestParseTimeout 20secs
Notes

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.

Security

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.

RequestTimeout

Description Defines the maximum request duration
Synopsis RequestTimeout time
Context Default Server, Virtual Host
Examples RequestTimeout 10mins
RequestTimeout never
Notes

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.

Reroute

Description Open a previously defined route to add or modify directives
Synopsis <Reroute URI-Pattern>
...
</Route>
Context Default server, VirtualHost, Route
Example <Route /admin/debug>
    AddHandler myDebugHandler
</Route>
Notes

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.

Reset [routes|pipeline]

Description Reset the input and output processing pipeline.
Synopsis Reset pipeline
Reset routes
Context Default Server, Virtual host, Route
Example Reset routes
Notes

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.

Route

Description Define a block of directives to apply to a matching URI pattern
Synopsis <Route URI-Pattern>
...
</Route>
Context Default server, VirtualHost, Route
Example <Route /admin/debug>
    AddHandler myDebugHandler
</Route>
Notes

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.

ScriptAlias

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

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>
Security Make sure you locate your CGI script directories outside the Documents.

SessionCookie

Description Sets the Session cookie options.
Synopsis SessionCookie name=NAME visible=[true|false] persist=[true|false]
SessionCookie enable
SessionCookie disable
Context Default Server, Virtual Host, Route
Example SessionCookie name=myapp visible=true persist=false same=lax|strict
Notes

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.

SessionTimeout

Description Defines the maximum session state duration
Synopsis SessionTimeout time
Context Default Server, Virtual Host, Route
Example SessionTimeout 30mins
Notes

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.

SetConnector

Description Set the connector to transmit the response to the client
Synopsis SetConnector connectorName
Context Default server, Virtual host, Route
Example SetConnector netConnector
Notes

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.

SetHandler

Description Set the handler to processing requests
Synopsis SetHandler handlerName
Context Default server, Virtual host, Route
Example SetHandler handlerName
Notes

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

ShowErrors

Description Control whether to display server-side errors to the client.
Synopsis ShowErrors on|off
Context Default server, Virtual host, Route
Example
ShowErrors on
Notes

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.

Source

Description Define source code for the handler to use when servicing the request.
Synopsis Source path
Context Default server, VirtualHost, Route
Example Source blog.c
Notes Some load scripts or source when servicing a request. This directive configures the file path to a source script or code file to be used by the handler when servicing the request. For example: ESP uses this to specify the name of the controller to load when invoking an action.

Stealth

Description Control stealth mode.
Synopsis Stealth [on|off]
Context Default server, VirtualHost, Route
Example Stealth on
Notes When Stealth mode is enabled, Appweb will emit less information about its configuration. Specifically, appweb will not emit a "Server" HTTP response header. While this does not provide security, it may increase the workload of those attempting to hack the server, and this may make the target less attractive.

Target

Description Define the route target rule that describes how the request should be handled.
Synopsis Target rule details ...
Target close
Target redirect status URI
Target run document
Target write [-r] status message
Context Default server, VirtualHost, Route
Example Target close
Target redirect 302 /updated/$&
Target run
Target run ${request:filename}.gz
Target write 200 "Hello World\r\n"
Notes

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.

Update

Description Define an update rule to modify the request when the route is selected.
Synopsis Update param var value ...
Update cmd commandLine...
Context Default server, VirtualHost, Route
Example Update param client ${request:clientAddress}
Update cmd sh -c 'echo Demo Downloaded | mail -s"Download from ${request:clientAddress}"'
Notes

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.

UploadAutoDelete

Description Set the directory to store uploaded files.
Synopsis UploadAutoDelete [on|off]
Context Default server, VirtualHost, Route
Example UploadAutoDelete off
Notes

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.

UploadDir

Description Set the directory to store uploaded files.
Synopsis UploadDir path
Context Default server, VirtualHost, Route
Example UploadDir /tmp
Notes

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

WebSocketsPing

Description Define the period for a Web Sockets Ping message.
Synopsis WebSocketsPing time
Context Default server, VirtualHost, Route
Example WebSocketsPing 30secs
Notes

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.

© Embedthis Software. All rights reserved.