Quick Nav
- AddHandler
- AddInputFilter
- AddLanguageDir
- AddLanguageSuffix
- AddOutputFilter
- Alias
- Cache
- Compress
- Condition
- DefaultLanguage
- DocumentRoot
- ErrorDocument
- Header
- LogRoutes
- Methods
- Name
- Param
- Prefix
- PutMethod
- Redirect
- Reset
- Route
- ScriptAlias
- SetConnector
- SetHandler
- Source
- Target
- TraceMethod
- Update
- UploadAutoDelete
- UploadDir
- WebSocketsPing
See Also
Route Directives
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/> DocumentRoot /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 CachingIf client caching is requested by specifying "client" with an optional lifespan in seconds, 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 ModesWhen using Server-Side caching, there are three possible modes:
Server-Side CachingWhen 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 LifespansThe Cache directive may specify a lifespan in seconds using the "client=secs" or "server=secs" 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 8600. SummaryUse 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. |
ClientCacheByType
Description | Control client-side caching by document mime type |
---|---|
Synopsis | ClientCacheByType lifespan mime-types ... |
Context | Default server, VirtualHost, Route |
Example | ClientCacheByType 86400 image/gif text/css |
Notes |
The CacheByType directive enables the generation of "Cache-Control" and "Expires" HTTP headers for matching documents. The Cache-Control and Expires HTTP headers instruct clients to cache response content for a specified duration. If the document is subsequently required by the client before the response content has expired, the document will be served from the client cache without contacting the server. The ClientCacheByType directive specifies a lifespan in seconds to be used for any document that matches one of the set of given mime-types for the document. An empty mime-type "" may be given to match all documents regardless of type. |
Compress
Description | Control serving of compressed documents. |
---|---|
Synopsis | Compress [gzip|none] |
Context | Default server, VirtualHost, Route |
Example | Compress gzip |
Notes |
The "Compress gzip" directive enables the serving of compressed content by the fileHandler and other supported handlers. If a document is not present, but a compressed version of the document exists, then the compressed version will be served. The filename for compressed content is assumed to be the normal filename with a ".gz" extension added. The "Compress none" directive can be used to turn compression off. |
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:
The rule result can be negated by prefixing with "!". For information about embedded {tokens}, see Tokens in the Routing Guide. |
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. |
DocumentRoot
Description | Top level directory containing the documents to be published for context. |
---|---|
Synopsis | DocumentRoot directoryPath |
Context | Default server, Virtual host, Route |
Example | DocumentRoot /var/www |
Notes |
The DocumentRoot 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. |
Header
Description | Define a header value must match a value for the route to be selected. |
---|---|
Synopsis | Header [!] field pattern |
Context | Default server, VirtualHost, Route |
Example | Header User-Agent (Chrome|Safari) |
Notes |
The Header 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. |
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 |
Example | InactivityTimeout 2mins |
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. |
LogRoutes
Description | Show the route table in the error log. |
---|---|
Synopsis | LogRoutes |
Context | Default server, VirtualHost, Route |
Example | LogRoutes |
Notes |
The LogRoutes directive prints a representation of the important route configuration to the error log. |
Methods
Description | Define the valid HTTP Methods for the route |
---|---|
Synopsis | Methods MethodSet |
Context | Default server, VirtualHost, Route |
Example | Methods GET POST |
Notes |
The Methods directive defines the valid HTTP methods for the route. 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. |
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. |
PutMethod
Description | Control use of the HTTP PUT method inside a route block. |
---|---|
Synopsis | PutMethod [on|off] |
Context | Default Server, Virtual host, Route |
Example | PutMethod on |
Notes |
The HTTP PUT method is used for sending content to the server. It can be destructive and so the PUT method is disabled by default. It must be explicitly enabled for a location block before use. NOTE: PutMethod is a proprietary Appweb directive. |
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 |
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:
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. |
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 |
Example | RequestTimeout 10mins |
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. |
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 DocumentRoot. |
SessionTimeout
Description | Defines the maximum session state duration |
---|---|
Synopsis | SessionTimeout seconds |
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. |
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. |
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:
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. |
TraceMethod
Description | Control the Trace HTTP method |
---|---|
Synopsis | TraceMethod on|off |
Context | Default server, Virtual host, Route |
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. |
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:
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. |