New post
Article
· Oct 8, 2018 5m read

Configuring Apache to work with InterSystems products on Linux

#Beginner #System Administration #Frontend #Caché

InterSystems products (IRIS, Caché, Ensemble) already include a built-in Apache web server. But the built-in server is designed for the development and administration tasks and thus has certain limitations. Though you may find some useful workarounds for these limitations, the more common approach is to deploy a full-scale web server for your production environment. This article describes how to set up Apache to work with InterSystems products and how to provide HTTPS access. We will be using Ubuntu, but the configuration process is almost the same for all Linux distributions.

Installing Apache


I assume that you have already installed let's say Caché to /InterSystems/Cache.
By default, Caché is supplied with a plugin for Apache, so you can simply go to /InterSystems/Cache/csp/bin and select the corresponding file:

  • CSPa24.so (Apache Version 2.4.x)
  • CSPa22.so (Apache Version 2.2.x)
  • CSPa20.so (Apache Version 2.0.x)
  • CSPa.so (Apache Version 1.3.x)

If several are available it's better to choose the latest one.

Now it's time to install Apache. For Ubuntu execute

apt-get update
apt-get install apache2 zlib1g-dev

In some OSes, there's no apache2 package (you'd get an "unable to locate package" error) and it's named httpd instead.

If there's no apache build for your OS in the default repositories, I recommend searching for a repository against building apache yourself. While it's possible, it's fairly challenging and binaries generally could be found.

Once the installation is complete, make sure that the installed Apache version meets the requirements:

apache2 -v

Then open the full list of modules to check whether 'mod_so' is on the list:

apache2 -l

So, Apache is now up and running. To test your Apache installation, type the IP address of your server in a web browser and see if the following page appears:

 

Apache config structure

Again, this can change depending on your OS and Apache versions but usually, Apache has the following configuration structure:

In here:

  • apache2.conf - main config file, loads first and loads everything else
  • envvars - default environment variables for apache2ctl
  • ports.conf - ports that apache listens (usually 80 and 443)
  • conf-available/conf-enabled - configuration snippets that are available or enabled
  • mods-available/mods-enabled - mods (for example we need to add CSP mod to work with InterSystems products)
  • sites-available/sites-enabled - sites (i.e. on port 80, on port 443, on host test.domain.com and so on)

There are also several utilities to run and configure Apache:

Linking CSP to Apache

Now that Apache is up and running let's connect it to Cache. To do this, make some changes to the Apache configuration. Edit the following files:
1. /etc/apache2/envvars contains the environment variables. Set the variables APACHE_RUN_USER and APACHE_RUN_GROUP to cacheusr or (irisusr for InterSystems IRIS)

2. In a mod directory /etc/apache2/mods-available create a new mod - a file named CSP.load:

CSPModulePath /InterSystems/Cache/csp/bin/
LoadModule csp_module_sa /InterSystems/Cache/csp/bin/CSPa24.so
AddHandler csp-handler-sa csp cls cxw zen

3. Enable CSP module using a2enmod programm

4. Create a new site in /etc/apache2/sites-available named Cache80.conf:

<IfModule mod_ssl.c>
<VirtualHost _default_:80>
    ServerName test.domain.com
    DocumentRoot "/InterSystems/Cache/csp"
    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
    LogLevel info
    <Location />
        CSP On
        SetHandler csp-handler-sa
    </Location>
    <Location "/csp/bin/Systems/">
        SetHandler csp-handler-sa
    </Location>
    <Location "/csp/bin/RunTime/">
        SetHandler csp-handler-sa
    </Location>
    DirectoryIndex  index.csp index.html index.htm
</VirtualHost>
</IfModule>

5. Using a2dissite/a2ensite disable old site on port 80 and enable Cache site

6. Restart apache with: service apache2 restart

7. Open http://<ip>/csp/sys/UtilHome.csp and see if the system management portal appears:

If apache didn't start, check the logs - it usually points to the problem line in configuration.

Run apachectl configtest to check your configuration.

If there's no pointer to error or configtest says that everything is fine, try starting apache in a foreground

apache2 -DFOREGROUND -e debug

If you're getting "application path" error it means that apache is unable to access CSP\bin directory and CSP.ini file inside.

SSL


Now let's set up https. To do this, you need a domain name, they start at $2/year. After you bought your domain name and configured DNS A record to point to your IP address go to any certificate authority for certificates. I'll show how it can be done with Let's Encrypt for free.

1. Using a2dissite/a2ensite disable Cache site on port 80 and enable default site

2. Restart apache with: service apache2 restart

3. Follow these instructions (I recommend forcing http->https redirect)

4. Create new site combining SSL configuration and Cache site:

<IfModule mod_ssl.c>
<VirtualHost _default_:443>
    ServerName test.domain.com
    DocumentRoot "/InterSystems/Cache/csp"
    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
    LogLevel info
    <Location />
        CSP On
        SetHandler csp-handler-sa
    </Location>
    <Location "/csp/bin/Systems/">
        SetHandler csp-handler-sa
    </Location>
    <Location "/csp/bin/RunTime/">
        SetHandler csp-handler-sa
    </Location>
    #DirectoryIndex  index.csp index.php index.html index.htm
    DirectoryIndex index.html
   SSLCertificateFile /etc/letsencrypt/live/test.domain.com/fullchain.pem
   SSLCertificateKeyFile /etc/letsencrypt/live/test.domain.com/privkey.pem
   Include /etc/letsencrypt/options-ssl-apache.conf
   ServerAlias test.domain.com
</VirtualHost>
</IfModule>

Make sure that 'Server Name' matches the 'commonName' parameter in the server certificate, and that the paths to all keys (server key 'SSLCertificateKeyFile', server certificate 'SSLCertificateFile' issued by the certificate authority) are valid.

5. Enable it, disable default SSL site, enable Cache SSL site

6. Restart apache with: service apache2 restart

7. Check whether the system management portal is now available at https://<ip>/csp/sys/UtilHome.csp

8. Enable auto-updating certificate. Edit crontab with: crontab -e and add a line there:

0 0 * * 0 certbot renew

Summary

It's easy to start running Apache server with InterSystems products. Increase security by implementing HTTPS on your sites.

Links

Discussion (2)2
Log in or sign up to continue
Fabian Haupt · Dec 25, 2018

The configuration structure for apache is actually much more dependent on which distribution you are using than the OS. There are pretty huge differences in the way Ubuntu/SuSE/RH/Centos are setting things up. Even down to some of them calling the system service apache vs apache2 vs httpd. There are also differences with some of them using systemd vs still the old sysvinit.
The good news is, you can always re-arrange your apache config to your liking.

Please also note, setting

        CSP On
        SetHandler csp-handler-sa

Is redundant. CSP On on a path already maps all filetypes to be handled by the gateway. Adding the sethandler doesn't add anything.
If you are omitting CSP On, but use the csp-handler-sa as detailed above, the gateway will not serve static files. Either you will need to add them (ok for low traffic sites), or you will need to configure apache to serve the static files directly (if your apache is not on the same machine as your instance you will need to copy the static files or mount a network drive)

1 0