Using a proxy

Introduction

You can operate ConSol CM behind a proxy server, e.g. Apache HTTPD. This might be required by security policies concerning system access over the internet. Two common scenarios are:

• The Web Client and CM/Track should be available through the proxy, but external access to the other clients should be blocked.
• All clients should be available through the proxy.

When using a proxy server, all URLs which are not white-listed explicitly in the proxy configuration are blocked. Therefore, you can decide for each client if it should be available externally via proxy or internally only.

info

ConSol CM comes with an example configuration for Apache HTTPD proxies. The example configuration has been created for Ubuntu 18. Please ask your consultant or the ConSol CM support for the files. The following section shows how to adapt this configuration. If another Linux distribution is used, additional changes might be needed.

Preconditions

The following preconditions apply for the example configuration:

• Apache HTTPD version 2.4
• The applications server bind address (-b parameter) has been set to 127.0.0.1, so it will only allow connections from the local machine.
• Apache HTTPD and the application server reside on the same machine (applicable for most ConSol CM installations except for clustered environments).

Content of the example configuration

The example configuration consists of two folders, one for Linux and one for Windows. Each folder contains three files.

Windows

• http-vhosts.conf: Virtual host configuration for HTTP
• https-vhosts.conf: Virtual host configuration for HTTPS
• httpd.conf: Parameters and main configuration

Linux

• cm.http.apache.conf: Virtual host configuration for HTTP
• cm.https.apache.conf: Virtual host configuration for HTTPS
• envvars: Environment variables

The envvars / httpd.conf files contain the parameters which are used in the virtual host configuration. The following parameters are available:

• SERVER_NAME: The host name and port that the server uses to identify itself. Used to set the main address of the website, e.g. cm6.apacheproxy.consol.pl. Accepts port numbers.

• SERVER_ALIAS: Alternate names for a host. Used to add additional addresses, e.g. www.cm6.apacheproxy.consol.pl. Accepts wildcards, e.g. *.cm6.apacheproxy.consol.pl. Does not accept port numbers.

• SERVER_ADMIN: Email address of the administrator included in error messages to the client.

• ERROR_LOG: The name of the file to which the server logs the errors it encounters. If the file path is not absolute, it is assumed to be relative to the server root, e.g. "/logs/error.log". Must be specified with quotes.

• CUSTOM_LOG: The name of the file to which the server logs the requests. If the file path is not absolute, it is assumed to be relative to the server root, e.g. "/logs/error.log combined". Must be specified with quotes and the keyword combined.

• SRVROOT: Root path of the server, e.g. "C:\\consol\apache\Apache24" without the last . Must be specified with quotes. Only for the Windows configuration.

• CM6_BACKEND_SERVER: Server host and port of the JBoss with the cm6.ear, e.g. cm6.consol.pl:8009. Connection via AJP. Used for the Web Client and webhook interface.

• WAS_BACKEND_SERVER: Server host and port of the Web Admin Suite. Connection via AJP. Used for the Web Admin Suite.

• ATMOSPHERE_BACKEND_SERVER: Server host and port of Atmosphere. Connection via WS. Used for the notifications in the Web Client.

• TRACK_BACKEND_SERVER: Server host, port and path without the last . Connection via AJP. Used for CM/Track V2. There are two options:

  • CM/Track V2 deployed in the same application server as ConSol CM: track.consol.pl:8080/track
  • CM/Track V2 deployed on Tomcat: The path to the backend server is different. You can register CM/Track V2 as root path, e.g. track.consol.pl:8080.

• TRACK_PROXY: Request name for CM/Track V2, e.g. cm6.apache.consol.pl/track. You need to specify the same request name like in the backend server, e.g. if the backend server is track.consol.pl:8080/track, set the TRACK_PROXY parameter to track (without /).

• TRACK_BACKEND_SERVER2: Same as TRACK_BACKEND_SERVER. Uncomment to use a second CM/Track V2 server. Copy to use more CM/Track V2 servers. Connection via AJP.

• TRACK_PROXY2: Same as TRACK_PROXY. Uncomment to use a second CM/Track server. Copy to use more CM/Track V2 servers.

• TRACK3_BACKEND_SERVER: Server host, port and path of CM/Track V3. There are two options:

  • CM/Track V3 deployed in the same application server as ConSol CM: cm.consol.de:8009/cm-track

  • CM/Track V3 executed as standalone Java application: The path to backend server is different. You can register CM/Track V3 as root path, e.g. cm.consol.de:8081.

    warnung

    You need to use HTTP instead of AJP for the standalone version of CM/Track V3.

• TRACK3_PROXY: Request name for CM/Track V3, e.g. cm-track.

• CMAS_AUTH_PORTAL_USER_BACKEND: Server host, port and path of the authentication application for CM/Track V3. There are two options:

  • Authentication application deployed in the same application server as ConSol CM: cm.consol.de:8009/cmas-auth-portal-user

  • Authentication application executed as standalone Java application: The path to backend server is different. You can register the authentication application as root path, e.g. cm.consol.de:8081.

    hinweis

    The configuration file needs to contain the property cmas.auth.portal.user.issuer with value from the system property cmas-core-security, oidc.track3.authority.<OIDC_CONNFIGURATION> on the ConSol CM side.

• CMAS_AUTH_PORTAL_USER: Request name for the authentication application, e.g. cmas-auth-portal-user.

• CMAS_AUTH_USER_BACKEND: Server host, port and path of the authentication application for the Web Client and Web Admin Suite. There are two options:

  • Authentication application deployed in the same application server as ConSol CM: cm.consol.de:8009/cmas-auth-user
  • Authentication application executed as standalone Java application: The path to backend server is different. You can register the authentication application as root path, e.g. cm.consol.de:8081.
  hinweis

  The configuration file needs to contain the property cmas.auth.user.issuer with value from the system property cmas-core-security, oidc.was|web.authority.<OIDC_CONNFIGURATION> on the ConSol CM side.

• CMAS_AUTH_USER: Request name for the authentication application, e.g. cmas-auth-user.

• ETL_RUNNER_BACKEND_SERVER: Server host, port and path of ETL Runner. There are two options:

  • ETL Runner deployed in the same application server as ConSol CM: cm.consol.de:8009/etl-runner
  • ETL Runner executed as standalone Java application: The path to backend server is different. You can register ETL Runner as root path, e.g. cm.consol.de:8081.

• ETL_RUNNER_PROXY: Request name for ETL Runner, e.g. etl-runner.

• ARCHIVE_BACKEND_SERVER: Server host and port of CM/Archive. Connection by HTTP. Used for CM/Archive.

• EBIA_BACKEND_SERVER: Server host and port of CM/EBIA. Connection by HTTP. Used for CM/EBIA.

• PATH_TO_CERTIFICATE_FILE: Path to a file with certificate data in PEM format. Only needed for the HTTPS configuration.

• PATH_TO_CERTIFICATE_KEY: Path to the PEM-encoded private key file for the server. Only needed for the HTTPS configuration.

warnung

If you specify all parameters, the respective clients are available through the proxy. If this is not desired, you must comment out the respective parameters in the configuration file and in the virtual host configuration file for HTTP or HTTPS.

Installing and configuring Apache HTTPD

Windows

1. Download and unzip Apache 2.4.x, e.g. from the Apache Haus.
2. Download and unzip the proxy distribution file provided by ConSol.
3. Copy the httpd.conf file from proxy-distribution\windows to <APACHE_PROXY_HOME>\httpd-2.4.x\Apache24\conf\
4. Copy the appropriate virtual host configuration file to <APACHE_PROXY_HOME>\httpd-2.4.x\Apache24\conf\extra\. Choose http-vhosts.conf for the HTTP configuration or https-vhosts.conf for the HTTPS configuration.
5. Open the <APACHE_PROXY_HOME>\httpd-2.4.x\Apache24\conf\httpd.conf file and fill out the properties in the CM6 ENVIRONMENT VARIABLES section. The paths must be provided in quotes.
6. Choose the HTTPS or HTTP configuration by specifying the respective virtual host file in VHOST_FILE_NAME. By default, the https section is commented in, so the HTTPS configuration is enabled. For HTTP configuration, comment out the https section and comment in the http section. For HTTPS, the SSL module is loaded by default and you need to set PATH_TO_CERTIFIKATE_FILE and PATH_TO_CERTIFIKATE_KEY.
7. Comment out all unneeded parameters in the httpd.conf and https-vhosts.conf files. For example, if the Web Admin Suite should not be available for external access, comment out the settings referring to the WAS backend server.
8. Remove the example definition of VirtualHost _default_:${SSL_PORT}> in the <APACHE_PROXY_HOME>\httpd-2.4.x\Apache24\conf\extra\httpd-ssl.conf file.
9. Start the Apache server

    <APACHE_PROXY_HOME>\Apache24\bin\httpd.exe`.

tipp

On Windows machines, you might want to run Apache HTTPD as a service. Execute the following command as an administrator:

<APACHE_PROXY_HOME>\Apache24\bin>httpd.exe -k install

Make sure that the start mode of this service is automatic (same as the application server service).

Linux

1. Install Apache 2.4.x, e.g. using apt-get:

    sudo apt-get update
    sudo apt-get install apache2

2. Download and unzip the proxy distribution file provided by ConSol.

3. Copy the envvars file from proxy-distribution/linux to /etc/apache2.

4. Copy the appropriate virtual host configuration file to /etc/apache2/sites-available/. Choose cm.http.apache.conf for the HTTP configuration or cm.https.apache.conf for the HTTPS configuration.

5. Rename the virtual host configuration file using the pattern: <server name>.conf, e.g. cm.https.apache.conf → cm6.consol.conf

6. Load all needed modules for a HTTP configuration:

    sudo a2enmod headers
    sudo a2enmod proxy
    sudo a2enmod proxy_ajp
    sudo a2enmod proxy_http
    sudo a2enmod proxy_wstunnel
    sudo a2enmod rewrite

   For HTTPS, also load the SSL module:

    sudo a2enmod ssl

7. Open the /etc/apache2/envvars file and fill out the properties in the CM6 ENVIRONMENT VARIABLES section. The paths must be provided in quotes.

8. Choose the HTTPS or HTTP configuration. By default, the https section is commented in, so the HTTPS configuration is enabled. For HTTP configuration, comment out the https section. For HTTPS you need to set PATH_TO_CERTIFIKATE_FILE and PATH_TO_CERTIFIKATE_KEY.

9. Comment out all unneeded parameters in the envvars and cm.https.apache.conf files. For example, if the Web Admin Suite should not be available for external access, comment out the settings referring to the WAS backend server.

10. Enable the virtual host:

    a2ensite cm6.consol.conf

11. Restart the Apache server:

    apache2ctl stop && apache2ctl start

    or

    sudo systemctl restart apache2.service

Advanced settings

On Windows, you can change the default thread stack size in the <APACHE_PROXY_HOME>\httpd-2.4.x\Apache24\conf\extra\httpd-mpm.conf file:

# WinNT MPM
# ThreadsPerChild: constant number of worker threads in the server process
# MaxConnectionsPerChild: maximum number of connections a server process serves
<IfModule mpm_winnt_module>
  ThreadsPerChild 150
  MaxConnectionsPerChild 0
  ThreadStackSize 8242880
</IfModule>

If there is a firewall between Apache and the application server, you can set disablereuse=on to force mod_proxy to close connections to its backend after using it.

By default, AJP uses port 8009. In order to change this port, add the variable jboss.socket.binding.ajp.port to your configuration file, e.g. cm6-config.properties, and specify the desired port:

# port overrides
jboss.socket.binding.ajp.port=8009

Additional settings for CM/Track and CM/EBIA

CM/Track:

• Enter the server proxy URL without any path in the property cmas-restapi-core, csrf.domain.white.list, e.g. https://myserver.consol.de.

CM/EBIA:

• Log in to the CM/EBIA administration as an administrator and enter the EBIA proxy URL, e.g. https://myserver.consol.de/ebia, in the following settings:
  • Admin -> General -> Site URL
  • Admin -> Embedding in other applications -> Embedding the entire CM/EBIA app
• Enter the EBIA proxy URL in the property cmas-analytics, metabase.url, e.g. https://myserver.consol.de/ebia.