Skip to main content

Configuring Application Access

This article describes how to configure applications to which the InterSystems IRIS® Web Gateway connects. For these configuration tasks, you use the Web Gateway management pages. Other articles describe how to configure default settings and servers.

Each web application must have the path to its CSP files configured. The configuration for each path identifies the InterSystems IRIS server responsible for running the application. Optional directives for specifying failover and load-balancing are included in the application path's configuration. The default application path, root, (/) is automatically configured when the Web Gateway is started for the first time. Inheritance is applied to application paths. For example, if a CSP request asks for a file in /Accounts/Invoices and there is no configuration for /Accounts/Invoices, the Web Gateway uses the configuration defined for /Accounts. If this is not defined, the configuration for the default path of / is used.

Adding an Application Path

To configure the path to an application:

  1. On the Web Gateway management pages main menu, select Application Access.

  2. Select Add Application. Note that many parameters have default settings.

  3. In the Application Path text box enter a unique path for the application. This path is the path which appears in the application URLs.


    An InterSystems IRIS installation creates a new /csp configuration. If you have configured /csp as your application, your configuration is overwritten when you install a new build of InterSystems IRIS. To maintain your application configuration, enter a path other than /csp.

    Any directory under /csp works fine, such as /csp/myapplication, but the path cannot contain any dots (periods), because these lead to ambiguity for the Web Gateway. In this example: /csp/samples/menu.csp/csp/aaa/bbb/ccc.cls, the Web Gateway could either interpret this as a request for /csp/samples/menu.csp/csp/aaa/bbb/ccc.cls or as a REST request for/csp/samples/menu.csp (where PATH_INFO is /csp/aaa/bbb/ccc.cls). The Web Gateway, working in the web server environment, has no way of resolving these ambiguities.

    CSP is case-sensitive. Specify your path names consistently when you are configuring CSP.

  4. Enter the other configuration path and server parameters (described in the tables below) for this application.

  5. When you have finished, select Save Configuration. Changes you make to the application configuration take effect as new user sessions are created for that application path. Existing users are unaffected.

Application Path Configuration Parameters

The set of base parameters are as follows:

Parameter Function
Service Status Enable and disable access to an application via the application path (default is Enabled).
Web Server Physical Path Path to the corresponding directory on the web server. This setting is particularly important for Microsoft IIS systems where each path configured must be set up as a virtual directory under the web server configuration. Each virtual directory defined within IIS must have a physical path associated with it. The purpose of this additional configuration procedure for IIS is to allow the paths used by InterSystems IRIS (specifically by the CSP engine) to be defined with execute permissions. The default is for execute (and hence access to the CSP engine) to be denied.
Extra CGI Environment Variables Comma-separated list of additional CGI environment variables to be returned to the InterSystems IRIS environment with each and every request. The commonly-used CGI environment variables are automatically sent with each request. Enter the wildcard character (*) to instruct the Web Gateway to send all environment variables supplied by the web server to the InterSystems IRIS server with each request.
Process with this class Process files in this path with the specified class. This allows you to build your own request handlers in CSP.
GZIP Compression Enable or disable GZIP compression for all CSP pages returned in this path (default is Disabled).
GZIP Minimum File Size Minimum response size, in bytes, for which GZIP compression is invoked. Default is 500 bytes.
GZIP Exclude File Types
This is a list of file types to be excluded from GZIP compression. Files to be excluded can be listed by MIME type (such as image/jpeg) or by common extension (such as jpeg).
By default, these common (natively compressed) image files are excluded:
GZIP Exclude File Types: jpeg gif ico png gz zip mp3 mp4 tiff
Separate additional types or extensions with a space.
Response Size Notification
This parameter provides configurable control over the method used by the Web Gateway to notify clients of the amount of data contained in each response.
Web clients typically require some form of response size notification if HTTP KeepAlive connectivity is used. Under these circumstances, the Web Gateway defaults to using chunked transfer encoding, provided HTTP v1.1 is in use. If an earlier HTTP protocol is in force it buffers the response data received from InterSystems IRIS and generate a content-length header instead. Also, in cases where the entire response fits into one output buffer a content-length header is generated instead of using chunked transfer.
There are scenarios in which it is desirable to instruct the Web Gateway to specifically use one method or the other. For example, in cases where HTTP v1.1 is used but some intermediary (such as a proxy) is unable to properly support chunked transfer. Also, while not sending any form of size notification (such as, where the close connection event is used as the response terminator) should be supported by all web clients, it is nevertheless recommended as 'good practice' that all responses should be accompanied by some form of size notification. Indeed, some clients require this.
The following options are provided:
  • Chunked Transfer Encoding and Content Length (the default)
  • Chunked Transfer Encoding
  • Content Length
This parameter is supplemented with a check box to instruct the Web Gateway to always generate a size notification for all requests regardless of whether or not KeepAlive is used.
There is a 500 kilobyte limit on the size of HTTP responses that specify a content-length header, as opposed to chunked responses. If you exceed this limit, a warning message appears in the CSP log:
WARNING: Unable to generate a 'Content-Length' header directive for this oversize response (Current size: size; Maximum buffer size allowed: 500000)
KeepAlive Enable or disable HTTP KeepAlive connectivity for this path. Default is No Action in which case the KeepAlive status is determined by the HTTP response headers for each request.
Non-Parsed Headers Enable or disable Non-Parsed Headers protocol for this path. Default is Enabled in which case HTTP response headers are streamed directly back to the client. If this property is disabled, the response headers are submitted back to the hosting web server. This gives the web server the opportunity to parse the headers and invoke any output filters that may be indicated. For example, the Apache Group’s mod_deflate facility. Note that for the Apache web server, if keep-alive is enabled, then the response headers are submitted back to Apache regardless of the Non-Parsed Headers setting.

Server Parameters

You can define a list of InterSystems IRIS servers to use for an application and the purpose for which they are to be used.

Parameter Function
Use Alternate Servers For
The first server listed, Server 0, is the default InterSystems IRIS server. It is used first. Other listed servers can be used for load balancing or failover, depending on the option checked.
  • Fail-Over If the first server fails (becomes unavailable), use an alternative.
  • Load-Balancing and Fail-Over . If the first server fails, use a server that is configured as either failover or load-balancing.
Server #: List of servers. The configuration screen initially shows only three server slots, but additional slots appear that enable you to define any number of alternative servers. Each server can be checked as Enabled or Disabled. Default is always Enabled. See Load Balancing and Failover Between Multiple InterSystems IRIS Server Instances for more information.

Copying an Application Path Configuration

You can quickly configure a new application path by copying the configuration entry of an existing path and editing it.


This feature is also useful for fine-tuning a configuration. By creating a second (temporary) configuration for an application path, you can test parameter changes without worrying about losing the original configuration.

To copy an existing application path configuration:

  1. From the Web Gateway management pages main menu, select Application Access.

  2. On the Application Access screen, select an existing application path.

  3. Select Copy Application.

  4. Select Submit.

  5. In the Application Path text box, enter a new and unique application path.

  6. Select Save Configuration. The new application configuration takes effect as new user sessions are created for the new application path. Existing users are unaffected.

Disabling Access via an Application Path

Use this facility to prevent users accessing a configured application through this Web Gateway installation.

To disable access via an application path:

  1. From the Web Gateway management pages main menu, select Application Access.

  2. At the Application Access screen, select an application path.

  3. Select Edit Application.

  4. Select Submit. The configuration screen for the application path appears.

  5. For the Application Status parameter, select Disabled.

  6. Select Save Configuration.

To re-enable access, repeat the procedure and select Enabled at Step 5.

Deleting an Application Path Configuration

To delete a configured application path:

  1. From the Web Gateway management pages main menu, select Application Access.

  2. At the Application Access screen, select an application path.

  3. Select the Delete Application option.

  4. Select Submit.

  5. Force a restart of all the applications by restarting the web server.