Skip to main content

Using or Replacing the Private Web Server

InterSystems IRIS® provides the Private Web Server, a minimal build of Apache, for the sole purpose of running the Management Portal.


For deployments of HTTP-based applications, including REST, CSP, Zen, and SOAP over HTTP or HTTPS, you should not use the private web server; instead, you must install and configure one of the supported web servers.

Purpose of the Private Web Server

The purpose of the Private Web Server (PWS) is only to connect to InterSystems IRIS and to meet its management needs. This private version of Apache is installed to ensure that:

  • The Management Portal runs out of the box.

  • An out-of-the-box testing capability is provided for development environments.

The Private Web Server is self contained and configured to listen on a TCP port other than the usual, well known, HTTP server port of 80. It does not interfere with any other web server installation operating on the same host.

The entry point for the Management Portal is normally via the following CSP path and file: /csp/sys/UtilHome.csp. For example:

Limitations of the Private Web Server

Regarding the private web server:

  • It is not suitable for production use.

  • It uses minimal security, and is built and configured exclusively for use within a secured environment.

  • It should only be used in environments where there is no public access to the Management Portal and in which all users are both trusted and connecting to the server through secured connections.

Additionally, the configuration deployed is generally unsuitable for applications for which a high volume of HTTP requests is anticipated. InterSystems tests the private web server only for use with the Management Portal.

This section discusses the differences between the configuration of the private web server and that of a typical production-grade Apache installation.

Limitations on Windows

Windows-based Apache installations use a special multi-threaded form of the Apache Multi-Processing Module (MPM) which is better suited to the way the operating system is optimized. Therefore, the behavior of the private web server under Windows is similar to that of a production grade Apache build as far as the ability to handle concurrent load is concerned.

If high availability and production-grade security is a requirement, or there is a need to integrate with other sources of web information, or a need for a high degree of control over the web server, a separate production-grade build of Apache is recommended — ideally operating on its own server. If, on the other hand, low volumes of HTTP traffic are expected, and there are limited demands for high availability and security, then the private web server may be suitable for deployment under these circumstances.

Building the Private Web Server

The (default) full Apache server is usually created with the following sequence of commands:

./configure --prefix=<install-dir>
make install

The minimal Apache build is typically created as follows:

./configure --prefix=/usr/iris/httpd --with-port=57773
            --enable-mods-static="log_config mime alias unixd authz_core"
            --enable-so --without-gdbm --without-ndbm
            --without-berkeley-db --with-included-apr --with-expat=builtin
            --with-mpm=prefork --disable-shared
make install

Notice that many of the services that are normally required for a production grade installation are excluded.

While this server can be used to host other web applications it is strongly recommended that a full, independent web server installation is used for this purpose. It should be remembered that any changes made to the configuration of the Management Portal Apache installation are overwritten when the hosting InterSystems IRIS installation is upgraded.

Limitations on UNIX®

The private web server defaults to using the Apache Group’s prefork Multi-Processing Module (MPM). This is a non-threaded server model: the number of requests that can be concurrently served is directly related to the number of Apache worker processes in the pool.

The private web server is configured to occupy the smallest possible footprint by allowing a maximum of two worker processes to be created for the pool. The following settings are found in the Apache configuration (httpd.conf) for the private web server:

MinSpareServers 1
MaxSpareServers 2

By contrast, the default Apache configuration for a production grade build is usually as follows:

StartServers       5
MinSpareServers    2
MaxSpareServers   20
ServerLimit      256
MaxRequestWorkers       256

This configuration allows Apache to create 5 worker processes at start-up, increasing to a maximum of 256 as the concurrent load increases. Because of these differences in configuration, the performance of the private web server is noticeably inferior to that of a production grade Apache build. This performance deficit becomes more noticeable as the concurrent load increases. However, it is possible to change the configuration of the private web server to match that of a full Apache installation (shown above). Apache must be completely restarted after changing these parameters.


The Management Portal Apache installation uses the following Web Gateway modules for communicating with InterSystems IRIS:

  • Windows: CSPa24.dll and CSPa24Sys.dll

  • UNIX®: and

Using a Different Web Server to Run the Management Portal

You can use a different web server to support the Management Portal.

  • If you are using a web server other than the private web server to manage an instance of InterSystems IRIS, you must configure the web server so that links to the documentation continue to work. To do this, configure the web server so that it includes a redirection from /csp/docbook/ to the correct URL for the documentation. You can find this information in the file install_dir/httpd/conf/httpd-doc.conf, which Apache uses to redirect /csp/docbook/. For information on creating a redirection, consult the documentation for the web server that you are using.

  • To disable the private web server, set the WebServer CPF parameter equal to 0.

If you want to serve the Management Portal with a standalone Apache, you need to manually configure additional file types. See Configuring Apache to Pass Additional File Types.

Managing the Private Web Server

Under normal operational conditions, the private web server for a particular instance of InterSystems IRIS is started when InterSystems IRIS is started and closed down when InterSystems IRIS is closed down. Occasionally it may be necessary to restart the private web server without disrupting the corresponding InterSystems IRIS server, for example, if you make a configuration change to the web server.

Making Configuration Changes

The configuration file for the private web server is located at: install_dir/httpd/conf/httpd.conf. However, edits made to this file do not persist through a software upgrade. The configuration file install_dir/httpd/conf/httpd-local.conf is provided for configuration changes you want to retain on upgrade. It is created on a new install or on upgrade if it does not already exist. If it does exist, upgrade makes no changes to its content.

Managing the Private Web Server on Windows

Start the private web server:

<install-dir>\httpd\bin\httpd -k start -n <instname>httpd
  -c "Listen port"

Stop the private web server:

<install-dir>\httpd\bin\httpd -k stop -n <instname>httpd

For example, suppose that InterSystems IRIS is installed in: C:\iris

InterSystems IRIS instance name: IRIS

TCP port for Apache: 52773


C:\iris\httpd\bin\httpd -k start -n IRIShttpd -c "Listen 52773"

And you can stop it as follows:

C:\iris\httpd\bin\httpd -k stop -n IRIShttpd

Managing the Private Web Server on UNIX®

Start the private web server:

<install-dir>/httpd/bin/httpd -d <install-dir>/httpd
  -c "Listen port"

Stop the private web server:

kill `cat <install-dir>/httpd/logs/`

For example, suppose that InterSystems IRIS installed in /usr/iris, and the TCP port for Apache is 8972. In this case, you can start the Private Web Server as follows:

/usr/iris/httpd/bin/httpd -d /usr/iris/httpd -c "Listen 8972"

And you can stop it as follows:

kill `cat /usr/iris/httpd/logs/`


On AIX, LD_LIBRARY_PATH must include the install-dir/bin directory in order to manually run httpd in this way.

FeedbackOpens in a new tab