Configuring web proxy

Ideally, the URL used to access HCL Detect will be in the form https://HCL.acme.com/drive, where HCL designates this locator as an HCL product installation at acme.com (the customer's Internet domain) and the context path, drive, indicates the name of the product.

Usually, the friendlier HCL name will map to an internal server hosting the HCL Detect installation, whose name will follow an (often less friendlier) internal IT convention (e.g., drive-cluster003-node001.acme.com). Thus, we recommend that a DNS alias (specifically a CNAME entry) be obtained and registered prior to the HCL Detect installation.

Procedures to update the corporate DNS servers vary. We recommend that the system administrator installing Detect contacts a local IT specialist to understand the process and to carry out the actual DNS registration.

As an example, an organization using TinyDNS will need to add the following entry to its configuration:

CHCL.acme.com:drive-cluster003-node001.acme.com:120

And invoke the utility (tinydns-data) to activate this entry.

SSL certificates come in different forms. A certificate can be obtained for a single host name, for multiple host names, or as a wildcard, accepting any name under a particular domain. While all of them ought to work with HCL Detect, a single-host certificate is sufficient and this option, if procuring a commercial certificate, is often the most economical.

Procedures to obtain a certificate vary both for commercial as well as for self-signed internal certificates.

Please consult a local IT specialist to understand which alternative is the most adequate in your environment.

In the rest of this document, it is assumed that a commercial certificate is on hand and available to be used during the configuration of the web proxy.

Regardless of how a certificate is obtained, in the end, a set of files related to the certificate must be available. In the example below, we are assuming that the certificates are being kept in a directory called HCL.acme.com:

• HCL.acme.com/fullchain.pem: this is the actual certificate plus the intermediate certificates (if any). See the documentation the Apache httpd SSLCertificateFile configuration key and the the nginx ssl_certificate configuration key for more information.
• HCL.acme.com/privkey.pem: this is the certificate private key for the server. See the documentation the Apache httpd SSLCertificateKeyFile configuration key and the the nginx ssl_certificate_key configuration key for more information.

Once the certificate has been obtained and these files are available either the Apache httpd or nginx must be installed and configured.

In the following sections, we will describe these steps assuming that the installation is being made on a RedHat server, where the HCL Detect web backend will eventually run.

Since the installation and configuration require updating system-owned resources, either sudo or root access is required.

The installation requires downloading and installing the necessary OS packages:

$ yum install -y httpd mod_ssl

To ensure that the Apache httpd server is started on boot, the service must be enabled:

$ systemctl enable httpd

Once installed, the configuration enabling the proxying must be added to httpd's main configuration file /etc/httpd/conf/httpd.conf. The following excerpt demonstrates how this is done, by creating a new virtual host entry:

...
<VirtualHost *:443>
    ServerName HCL.acme.com
    ## HCL Detect will accessible at https://HCL.acme.com/drive
    ProxyPass /drive http://[::1]:8081/drive
    ## HCL Detect must be configured with HTTP access restricted to localhost binding to port 8081
    ## Note that the IPv6 address being used, [::1], is the IP address corresponding to the loopback interface.
    ## HCL Detect's Tomcat instance by ## default will use the IPv6 protocol stack
    ProxyPassReverse /drive http://[::1]:8081/drive
    ProxyPreserveHost on
    ProxyRequests off
    Header always set Strict-Transport-Security "max-age=31536000; includeSubdomains; preload"
    SSLCertificateFile /etc/httpd/stash/HCL.acme.com/fullchain.pem
    SSLCertificateKeyFile /etc/httpd/stash/HCL.acme.com/privkey.pem
    SSLEngine on
    SSLProtocol TLSv1.2
    SSLProxyEngine on
</VirtualHost>
...

$ restorecon -vr /etc/httpd/stash

$ systemctl start httpd

If all is well, you should be able to start HCL Detect, open a browser and point it to https://HCL.acme.com/drive.

To start HCL Detect, see the Starting and stopping HCL Detect section. If a failure has happened when starting httpd, see the Testing and troubleshooting the web proxy installation section for additional help with troubleshooting.

The installation requires downloading and installing the necessary OS packages:

$ yum install -y nginx

To ensure that the nginx server is started on boot, the service must be enabled:

$ systemctl enable nginx

Once installed, the configuration enabling the proxying must be added to nginx's main configuration file /etc/nginx/nginx.conf. The following excerpt demonstrates how this is done, by creating a new server entry:

http {
...
    server {

        listen 443;
        server_name HCL.acme.com;

        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload";

        ssl on;
        ssl_certificate /etc/nginx/stash/HCL.acme.com/fullchain.pem;
        ssl_certificate_key /etc/nginx/stash/HCL.acme.com/privkey.pem;
        ssl_session_timeout 5m;
        ssl_protocols TLSv1.2;
        ssl_ciphers HIGH:!aNULL:!MD5;
        ssl_prefer_server_ciphers on;

        ssl_session_cache shared:SSL:10m;
        ## HCL Detect will accessible at https://HCL.acme.com/drive
        location /drive {

            ## HCL Detect must be configured with HTTP access restricted to localhost binding to port 8081
            proxy_pass http://[::1]:8081/drive;
            ## Note that the IPv6 address being used, [::1], is the IP address corresponding to the loopback
            ## interface. HCL Detect's Tomcat instance by default will use the IPv6 protocol stack
            proxy_set_header X-Forwarded-Host $host;
            proxy_set_header X-Forwarded-Server $host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_redirect off;
        }
    }
}

$ restorecon -vr /etc/nginx/stash

$ systemctl start nginx

If all is well, you should be able to start HCL Detect, open a browser, and point it to https://HCL.acme.com/drive. troubleshooting.

To start HCL Detect, see the Starting and stopping HCL Detect section. If a failure has happened when starting httpd, see the Testing and troubleshooting the web proxy installation section for additional help with troubleshooting.

Once the web proxy is configured and HCL Detect has been started, using the web interface is as simple as entering the access URL in the browser window.

There are typically two problems that might occur in a new installation, where either RedHat Linux or CentOS is being used:

• the firewall configuration: if the server running the proxy has firewalld installed, HTTPS access is typically blocked by default. While we provide some helpful directions below, we strongly recommend reading the firewalld documentation so the impact of these commands is fully understood.

To check on current status of firewalld, the following command can be executed:

$ firewall-cmd --list-all
public (active)
target: default
icmp-block-inversion: no
interfaces: enp0s3
sources:
services: dhcpv6-client https ssh
protocols:
masquerade: no
forward-ports:
sourceports:
icmp-blocks:
rich rules:

If https does not appear in the list of services (as it does above), it must be added, either temporarily:

$ firewall-cmd --zone=public --add-service=https
$ firewall-cmd --reload

Or permanently:

$ firewall-cmd --zone=public --permanent --add-service=https

At this point, re-running the status command will reveal whether HTTPS access to the server is now enabled.

• the SE Linux configuration SELinux is a set of kernel modifications and tools that have been added to RedHat and CentOS, providing support for access control security policies. It may affect the web proxy in the sense.

Often, if the SELinux access control is not properly configured for the web proxy, there will be two symptoms. First, an access from the browser will be rejected, often, with a "bad gateway" error message. Second, the SELinux log file (ll/var/log/audit/audit.log, root access is required both for search the logs as well as for reconfiguring SELinux policies) will include a rejection of an operation attempted by the web proxy (in the example below, nginx, but very similar for httpd as well), possibly, similar to the following:

$ grep nginx /var/log/audit/audit.log
type=AVC msg=audit(1490570804.119:555): avc:  denied  { name_connect } for  pid=5725 comm="nginx" dest=8080
scontext=system_u:system_r:httpd_t:s0 tcontext=system_u:object_r:http_cache_port_t:s0 tclass=tcp_socket

Fiddling with SELinux will have a direct impact on the security of a host as well as on the overall network where that host is located. HCL strongly recommends that changes being done on SELinux policies are undertaken by someone familiar with its configuration. The procedures we indicate below are not to be taken without understanding their potential repercussions.

This audit entry can be better understood by running the following command, which also prescribes the possible fixes:

$ ausearch -c nginx | audit2allow -m nginx

module nginx 1.0;

require {
    type httpd_t;
    type http_cache_port_t;
    class tcp_socket name_connect;
}

#============= httpd_t ==============

#!!!! This avc can be allowed using one of the these booleans:
#     httpd_can_network_connect, httpd_can_network_relay
allow httpd_t http_cache_port_t:tcp_socket name_connect;

You can check the current state of these Booleans settings as follows, which at this point, is most likely off:

$ getsebool -a | grep httpd

Finally, the problem can be resolved by allowing network connections from the web proxy to the actual server (i.e., so it can act as a relay):

$ setsebool -P httpd_can_network_relay on

Alternatively, a new SELinux non-base policy can be put in place:

$cd /tmp
$ ausearch -c nginx | audit2allow -M nginx
$ semodule -i nginx.pp
$ rm nginx.pp