Embedthis Appweb 4.3.4
Home > Users Guide > Configuration Directives > Route Directives

# 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

- Configuration
- Configuration Directives
- Request Routing

# 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 Caching

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

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

## 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:

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

## 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:

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

## 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:

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

## 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:

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